Azure DevOps TypeScript SDK

A modern, fluent TypeScript SDK for Azure DevOps APIs, inspired by Stripe API design patterns and CLI usability principles.

Features

• Fluent API Design: Intuitive topic-command pattern inspired by Stripe and Heroku CLI
• Type Safety: Full TypeScript support with comprehensive interfaces
• Field Mapping: Automatic conversion from Azure DevOps fields to normalized objects
• Battle-Tested Foundation: Built on top of the official azure-devops-node-api
• Cross-Project Support: Execute queries across multiple projects
• Intelligent Batching: Automatic handling of API limits for large datasets

Installation

npm install azure-devops-ts

Quick Start

import { AzureDevOps } from 'azure-devops-ts';

const azureDevOps = new AzureDevOps({
  organizationUrl: 'https://dev.azure.com/myorg',
  personalAccessToken: 'your-pat-token',
  project: 'MyProject' // optional default project
});

// Test connection
const connection = await azureDevOps.testConnection();
console.log('Connected:', connection.success);

// List recent work items
const recent = await azureDevOps.workItems.list();
console.log(`Found ${recent.length} recent work items`);

// Get specific work item
const workItem = await azureDevOps.workItems.get(123);
console.log(`Work item: ${workItem.title} (${workItem.state})`);

// Execute WIQL query
const bugs = await azureDevOps.workItems.query(`
  SELECT * FROM WorkItems 
  WHERE [System.WorkItemType] = 'Bug' 
    AND [System.State] = 'Active'
`);
console.log(`Found ${bugs.length} active bugs`);

Core API

Work Items

// List work items with filtering
const workItems = await azureDevOps.workItems.list({
  type: 'Bug',
  state: 'Active',
  assignee: 'me',
  top: 100
});

// Get single work item
const workItem = await azureDevOps.workItems.get(123, {
  expand: ['relations', 'revisions']
});

// Get multiple work items efficiently
const workItems = await azureDevOps.workItems.getMany([123, 456, 789]);

// Execute WIQL queries
const results = await azureDevOps.workItems.query(`
  SELECT [System.Id], [System.Title] 
  FROM WorkItems 
  WHERE [System.Tags] CONTAINS 'OMG COM'
  ORDER BY [System.CreatedDate] DESC
`);

// Convenience methods
const omgItems = await azureDevOps.workItems.findByTags(['OMG COM']);
const p1Bugs = await azureDevOps.workItems.findP1Bugs();
const figmaItems = await azureDevOps.workItems.searchByText('Figma');

Data Structure

Work items are automatically mapped from Azure DevOps fields to a normalized structure:

interface WorkItem {
  id: number;
  title: string;                    // System.Title
  state: string;                    // System.State
  workItemType: string;             // System.WorkItemType
  assignedTo?: string;              // System.AssignedTo.displayName
  createdDate: string;              // System.CreatedDate
  changedDate: string;              // System.ChangedDate
  tags?: string;                    // System.Tags
  description?: string;             // System.Description
  areaPath?: string;                // System.AreaPath
  iterationPath?: string;           // System.IterationPath
  priority?: number;                // Microsoft.VSTS.Common.Priority
  severity?: string;                // Microsoft.VSTS.Common.Severity
  storyPoints?: number;             // Microsoft.VSTS.Scheduling.StoryPoints
  url?: string;                     // Work item URL
}

Configuration

interface AzureDevOpsConfig {
  organizationUrl: string;          // https://dev.azure.com/myorg
  personalAccessToken: string;     // PAT token
  project?: string;                 // Default project
  apiVersion?: string;              // API version (default: 7.1-preview.3)
  timeout?: number;                 // Request timeout (default: 30000ms)
  retries?: number;                 // Retry attempts (default: 3)
}

Cross-Project Queries

Execute queries across multiple projects by omitting the project parameter:

// Cross-project query
const allOmgItems = await azureDevOps.workItems.query(`
  SELECT * FROM WorkItems 
  WHERE [System.Tags] CONTAINS 'OMG COM'
`);

// Project-specific query
const projectBugs = await azureDevOps.workItems.query(`
  SELECT * FROM WorkItems 
  WHERE [System.WorkItemType] = 'Bug'
`, 'SpecificProject');

Error Handling

The SDK provides enhanced error messages with context:

try {
  const workItem = await azureDevOps.workItems.get(999);
} catch (error) {
  console.error(error.message); // "Failed to get work item 999: Work item 999 not found"
}

Compatibility

This SDK is designed to be a drop-in replacement for direct azure-devops-node-api usage in existing applications. It maintains the same data structures used by:

• omg-dash-be (NestJS backend)
• mcp-server (MCP protocol server)

License

MIT