azure-devops 0.1.0

Idiomatic Rust client for Azure DevOps REST APIs
Documentation
# azure-devops

An idiomatic Rust client for the [Azure DevOps REST APIs](https://learn.microsoft.com/en-us/rest/api/azure/devops/).

Built with reference to the official [azure-devops-node-api](https://github.com/Microsoft/azure-devops-node-api) library and Microsoft's REST API documentation.

## Installation

```toml
[dependencies]
azure-devops = "0.1"
```

## Quick Start

```rust
use azure_devops::AzureDevOps;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = AzureDevOps::builder()
        .organization("my-company")
        .pat(std::env::var("AZURE_DEVOPS_PAT")?)
        .build()?;

    let projects = client.projects().list().await?;

    for project in &projects.value {
        println!("{}", project.name);
    }

    Ok(())
}
```

## Current API Coverage

| API Area          | Client               | Key Operations                                                                                                                |
| ----------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **Projects**      | `ProjectsClient`     | `list`, `get`, `list_with_options`, `get_with_options`                                                                        |
| **Work Items**    | `WorkItemsClient`    | `create`, `get`, `update`, `delete`, `destroy`, `query_by_wiql`, `get_batch`, `get_many`, types, fields, states, state colors |
| **Repositories**  | `RepositoriesClient` | `list`, `get`, `create`, `delete`, branches, commits, refs, items (files), pushes, statuses                                   |
| **Pull Requests** | `PullRequestsClient` | `list`, `get`, `create`, `update`, comments, threads, reviewers, commits, work item refs                                      |
| **Builds**        | `BuildsClient`       | `list`, `get`, `get_latest`, `queue`, definitions, artifacts, logs, timeline, tags, changes, metrics                          |
| **Pipelines**     | `PipelinesClient`    | `list`, `get`, `create`, `run`, preview, runs, logs, artifacts                                                                |

> **Type note:** Most list methods return `Vec<T>` directly (not a wrapper). The `ProjectsClient::list()` and `BuildsClient::list()/list_definitions()` are exceptions that return paginated wrappers with `.value` and `.count` fields.

## Examples

The crate ships with Runnable examples in the [`examples/`](examples/) directory:

| Example                                      | API Area      | Run with                            |
| -------------------------------------------- | ------------- | ----------------------------------- |
| [`list_projects`]examples/list_projects.rs | Projects      | `cargo run --example list_projects` |
| [`work_items`]examples/work_items.rs       | Work Items    | `cargo run --example work_items`    |
| [`builds`]examples/builds.rs               | Builds        | `cargo run --example builds`        |
| [`pipelines`]examples/pipelines.rs         | Pipelines     | `cargo run --example pipelines`     |
| [`pull_requests`]examples/pull_requests.rs | Pull Requests | `cargo run --example pull_requests` |
| [`repositories`]examples/repositories.rs   | Repositories  | `cargo run --example repositories`  |

Set environment variables before running:

```sh
export AZURE_DEVOPS_PAT="your-personal-access-token"
export AZURE_DEVOPS_ORG="your-org-name"
export AZURE_DEVOPS_PROJECT="your-project-name"    # optional
export AZURE_DEVOPS_REPO_ID="repo-uuid"             # for pull_requests example
cargo run --example builds
```

## AI-Assisted Development

This crate is designed for excellent AI coding assistant support:

- **[`AGENTS.md`]AGENTS.md** — Comprehensive usage guide for Copilot, Claude, Cursor, and other AI tools
- **[`.cursor/rules/`].cursor/rules/** — Cursor-specific rules for code generation
- **[`CLAUDE.md`]CLAUDE.md** — Quick reference for Claude Code
- **[`.github/copilot-instructions.md`].github/copilot-instructions.md** — GitHub Copilot instructions

Every public API method, struct, and enum has doc comments with examples. Module-level docs provide Runnable examples for each API area.

## Authentication

Currently supports Personal Access Token (PAT) authentication:

```rust
AzureDevOps::builder()
    .organization("my-company")
    .pat("your-pat-token")
    .build()?;
```

PATs are stored using [`secrecy::SecretString`](https://docs.rs/secrecy) — they will not appear in `Debug` output or logs.

## API Design

The library provides a fluent, strongly-typed API:

```rust
// List projects
let projects = client.projects().list().await?;

// Get a specific project
let project = client.projects().get("my-project").await?;

// With options
use azure_devops::projects::models::{ListProjectsOptions, ProjectStateFilter};

let opts = ListProjectsOptions {
    state_filter: Some(ProjectStateFilter::WellFormed),
    top: Some(10),
    ..Default::default()
};
let projects = client.projects().list_with_options(&opts).await?;
```

## Error Handling

All methods return `Result<T, AzureDevOpsError>`. The error type distinguishes:

- Network failures
- Authentication errors (401/403)
- API errors (with HTTP status and message)
- Serialization failures
- Rate limiting (429)
- Configuration errors

## Minimum Supported Rust Version

Rust 1.75 or later (2021 edition).

## License

MIT