ADO Client - Azure DevOps TypeSpec Library

A comprehensive TypeScript client library for Azure DevOps (ADO) APIs, generated from TypeSpec specifications.

Features

This library provides complete functionality for:

1. Work Items Management

   • Get all work items
   • Get work item by ID
   • Get work item updates and revisions
   • Create new work items
   • Update existing work items
   • Delete work items

2. Pull Request Operations

   • Get all pull requests
   • Get specific pull request details
   • Create new pull requests
   • Get related work items
   • Get PR commits and changes
   • Manage comments and threads
   • Reply to comments

3. Build Management

   • Get all builds with filtering
   • Get specific build details
   • Get build logs
   • Queue new builds
   • Retain builds
   • Get build definitions

Installation

npm install ado-client

Setup

Configuration Options

The ADO Client supports multiple configuration approaches for flexibility:

1. Environment Variables (Recommended)

Set the following environment variables:

export ADO_PAT="your-personal-access-token"           # Required
export ADO_ORGANIZATION="Skype"                       # Optional, defaults to 'Skype'
export ADO_PROJECT="SPOOL"                           # Optional, defaults to 'SPOOL'

Then initialize the client:

import { AdoClient } from 'ado-client';

// Uses environment variables and defaults
const client = new AdoClient();

2. Configuration Object

import { AdoClient } from 'ado-client';

const client = new AdoClient({
  personalAccessToken: 'your-pat-token',
  organization: 'your-organization',    // Optional, defaults to 'Skype'
  project: 'your-project',             // Optional, defaults to 'SPOOL'
  apiVersion: '7.0'                    // Optional, defaults to '7.0'
});

3. Mixed Approach

Override specific values while using environment variables for others:

const client = new AdoClient({
  organization: 'custom-org',    // Override default
  // PAT and project will come from environment variables or defaults
});

Authentication

You need a Personal Access Token (PAT) with appropriate permissions:

1. Go to Azure DevOps → User Settings → Personal Access Tokens
2. Create a new token with required scopes:
   • Work Items: Read & Write
   • Code: Read (for Pull Requests)
   • Build: Read & Execute
3. Use the token via ADO_PAT environment variable or configuration

Usage Examples

Work Items

Basic Work Item Operations

// Get a specific work item by ID (uses default project 'SPOOL')
const workItem = await client.getWorkItemById(12345);
if ('id' in workItem) {
  console.log(`Work Item: ${workItem.fields?.['System.Title']}`);
}

// Get work item from a specific project
const workItemFromProject = await client.getWorkItemById(12345, 'MyProject');

// Get work item updates/history
const updates = await client.getWorkItemUpdatesById(12345);

// Update a work item
const updateOperations = [
  {
    op: 'add',
    path: '/fields/System.State',
    value: 'Active'
  },
  {
    op: 'add',
    path: '/fields/System.AssignedTo',
    value: '[email protected]'
  }
];

const updatedWorkItem = await client.updateWorkItemById(12345, updateOperations);

// Delete a work item
const deletedWorkItem = await client.deleteWorkItemById(12345, false); // false = move to recycle bin

Advanced Work Item Operations

// Create a new work item in default project
const newWorkItem = await client.createWorkItem('Bug', [
  {
    op: 'add',
    path: '/fields/System.Title',
    value: 'New Bug Report'
  },
  {
    op: 'add',
    path: '/fields/System.Description',
    value: 'Description of the bug'
  }
], { project: 'MyProject' }); // Optional project override

// Get all work items with specific fields
const workItems = await client.getAllWorkItems({
  ids: '1,2,3',
  fields: 'System.Id,System.Title,System.State',
  project: 'SPOOL' // Optional project override
});

Pull Requests

// Get all pull requests for a repository
const pullRequests = await client.getAllPullRequests('repository-id');

// Get specific pull request with commits and work items
const pr = await client.getPullRequest('repository-id', 123, {
  includeCommits: true,
  includeWorkItemRefs: true
});

// Create a new pull request
const newPR = await client.createPullRequest('repository-id', {
  sourceRefName: 'refs/heads/feature/new-feature',
  targetRefName: 'refs/heads/main',
  title: 'Add new feature',
  description: 'This PR adds a new feature to the application',
  isDraft: false
});

// Get pull request comments
const threads = await client.getPullRequestThreads('repository-id', 123);

// Reply to a comment
const comment = await client.createPullRequestComment('repository-id', 123, 456, {
  content: 'Thanks for the review!',
  commentType: 'text'
});

// Get related work items
const workItems = await client.getPullRequestWorkItems('repository-id', 123);

// Get all commits in a PR
const commits = await client.getPullRequestCommits('repository-id', 123);

Builds

// Get all builds for a project
const builds = await client.getAllBuilds({
  statusFilter: 'completed',
  resultFilter: 'succeeded',
  top: 10
});

// Get specific build details
const build = await client.getBuild(12345);

// Get build logs
const logs = await client.getBuildLogs(12345);

// Queue a new build
const newBuild = await client.queueBuild({
  definition: { id: 123 },
  sourceBranch: 'refs/heads/main'
});

// Get build definitions
const definitions = await client.getBuildDefinitions({
  name: 'CI Build',
  includeLatestBuilds: true
});

// Retain a build
await client.retainBuild(12345);

Error Handling

const result = await client.getWorkItem(12345);

if ('message' in result) {
  // Handle error
  console.error(`Error: ${result.message}`);
  if (result.errorCode) {
    console.error(`Error Code: ${result.errorCode}`);
  }
} else {
  // Handle success
  console.log(`Work Item Title: ${result.fields?.['System.Title']}`);
}

Advanced Usage

Getting Parent Work Items

async function getWorkItemWithParents(workItemId: number) {
  const workItem = await client.getWorkItem(workItemId, {
    expand: 'relations'
  });
  
  if ('relations' in workItem && workItem.relations) {
    const parentRelations = workItem.relations.filter(
      rel => rel.rel === 'System.LinkTypes.Hierarchy-Reverse'
    );
    
    const parents = [];
    for (const relation of parentRelations) {
      if (relation.url) {
        const parentId = parseInt(relation.url.split('/').pop() || '0');
        const parent = await client.getWorkItem(parentId);
        parents.push(parent);
      }
    }
    
    return { workItem, parents };
  }
  
  return { workItem, parents: [] };
}

Getting PR Changes and Diffs

async function getPRChanges(repositoryId: string, pullRequestId: number) {
  const commits = await client.getPullRequestCommits(repositoryId, pullRequestId);
  
  if ('value' in commits && commits.value) {
    const changes = commits.value.flatMap(commit => commit.changes || []);
    return changes;
  }
  
  return [];
}

TypeScript Support

This library is fully typed with TypeScript. All API responses, request parameters, and models are strongly typed based on the Azure DevOps REST API specifications.

License

MIT