/** * Azure DevOps API Client * * Supports: * 1. MCP Server (microsoft/azure-devops-mcp) - Primary * 2. REST API - Fallback * * Features: * - List work items with filtering (by sprint, status, etc.) * - Create work items (Epic, Feature, User Story, Task) * - Update work items * - Get sprint/iteration information */ import { Logger } from '../../utils/logger.js'; /** * Set the logger for this module */ export declare function setAdoClientLogger(logger: Logger): void; export interface AdoWorkItem { id: number; fields: { 'System.Title': string; 'System.Description'?: string; 'System.WorkItemType': string; 'System.State': string; 'System.Priority'?: number; 'System.AreaPath'?: string; 'System.IterationPath'?: string; 'System.Tags'?: string; 'Microsoft.VSTS.Common.AcceptanceCriteria'?: string; [key: string]: any; }; relations?: Array<{ rel: string; url: string; }>; url: string; } export interface AdoIteration { id: string; name: string; path: string; attributes: { startDate?: string; finishDate?: string; timeFrame: 'past' | 'current' | 'future'; }; } export interface AdoWorkItemFilter { workItemType?: string[]; state?: string[]; iteration?: string; areaPath?: string; tags?: string[]; assignedTo?: string; top?: number; changedSince?: Date; workItemIds?: number[]; } /** * External change representation for pull sync */ export interface AdoExternalChange { platform: 'ado'; externalId: string; workItemId: number; changedAt: string; changedBy: string; changedFields: Array<{ field: string; oldValue: unknown; newValue: unknown; }>; currentState: { status: string; priority: number | null; assignee: string | null; }; } export interface AdoWorkItemCreate { workItemType: 'Epic' | 'Feature' | 'User Story' | 'Task' | 'Issue'; title: string; description?: string; acceptanceCriteria?: string; priority?: number; state?: string; areaPath?: string; iterationPath?: string; tags?: string[]; parentId?: number; customFields?: Record; } export interface AdoWorkItemUpdate { id: number; title?: string; description?: string; acceptanceCriteria?: string; priority?: number; state?: string; tags?: string[]; customFields?: Record; } /** * ADO Process Template detection result * Used to determine hierarchy mapping for import */ export interface AdoProcessTemplateInfo { /** Detected template name */ template: 'Agile' | 'Scrum' | 'CMMI' | 'Basic' | 'SAFe'; /** Whether Capability work item type exists (SAFe/Enterprise) */ hasCapability: boolean; /** Work item types available in this project */ workItemTypes: string[]; /** Hierarchy mapping for this template */ hierarchyMapping: { /** ADO Capability → SpecWeave Epic (_epics/EP-XXXE/) - only in SAFe */ capability?: 'epic'; /** ADO Epic → SpecWeave Epic or Feature depending on template */ epic: 'epic' | 'feature'; /** ADO Feature → SpecWeave Feature (FS-XXXE/) */ feature: 'feature'; /** ADO User Story/PBI/Requirement → SpecWeave User Story (us-xxxe.md) */ userStory: 'user-story'; /** ADO Task → SpecWeave Task (tasks.md) */ task: 'task'; }; } /** * Configuration for profile-aware ADO client * Use this when creating client for specific increment's profile */ export interface AdoClientConfig { pat: string; organization: string; project: string; } export declare class AdoClient { private credentials; private baseUrl; private apiVersion; /** * Create ADO client * * @param config - Optional profile-specific config. If not provided, * falls back to credentials from .env (single-profile mode) * * For multi-project support, use createAdoClientForIncrement() factory * which resolves the increment's profile automatically. */ constructor(config?: AdoClientConfig); /** * Get authorization header for REST API */ private getAuthHeader; /** * Check if response text looks like HTML (error page) */ private looksLikeHtml; /** * Safely parse JSON response with HTML detection * * Azure DevOps may return HTML error pages instead of JSON when: * - PAT is invalid/expired * - Organization name is wrong * - Corporate proxy/firewall intercepts the request * - SSO redirect occurs * * @param response - Fetch response object (body must not be consumed) * @returns Parsed JSON data * @throws Error with helpful message if response is not valid JSON */ private safeParseJson; /** * Handle non-OK response with helpful error messages * * @param response - Fetch response with !response.ok * @param context - Context for error message (e.g., "querying work items") * @throws Error with details */ private handleErrorResponse; /** * List work items with filtering */ listWorkItems(filter?: AdoWorkItemFilter): Promise; /** * Build WIQL (Work Item Query Language) query from filter */ private buildWiqlQuery; /** * Get work items by IDs */ private getWorkItemsByIds; /** * Create a new work item */ createWorkItem(item: AdoWorkItemCreate): Promise; /** * Update an existing work item */ updateWorkItem(update: AdoWorkItemUpdate): Promise; /** * Link two work items (parent-child relationship) */ private linkWorkItems; /** * Get current iteration (sprint) */ getCurrentIteration(): Promise; /** * Get all iterations */ getIterations(): Promise; /** * Get all projects accessible to the user */ getProjects(): Promise; /** * Search projects with pagination (for three-tier loading) * * @param options Search options * @returns Paginated project results */ searchProjects(options?: { top?: number; skip?: number; }): Promise; /** * Get area paths for a project (classification nodes) * * @param project Project name or ID * @param depth Depth of area path tree (default: 10) * @returns Area path tree */ getAreaPaths(project: string, depth?: number): Promise; /** * Get teams for a project * * @param project Project name or ID * @returns Teams array */ getTeams(project: string): Promise; /** * Fetch recently changed work items for pull sync (Increment 0089) * * Queries ADO for work items that have changed since a given timestamp. * Used by ExternalChangePuller to detect external updates. * * @param since - Timestamp to query changes from * @param linkedItemIds - Optional list of work item IDs to filter (linked items only) * @returns Array of external changes with changedAt, changedBy, and current values */ fetchRecentChanges(since: Date, linkedItemIds?: number[]): Promise; /** * Get work item updates (revision history) for detailed change tracking * * Use this for detailed changelog when needed. * GET /{organization}/{project}/_apis/wit/workitems/{id}/updates * * @param workItemId - Work item ID * @param top - Limit number of updates * @returns Array of updates with field changes */ getWorkItemUpdates(workItemId: number, top?: number): Promise; /** * ADO Process Template types */ static readonly PROCESS_TEMPLATES: { readonly AGILE: "Agile"; readonly SCRUM: "Scrum"; readonly CMMI: "CMMI"; readonly BASIC: "Basic"; readonly SAFE: "SAFe"; }; /** * Detect ADO Process Template for the project * * Uses project properties API to get the process template name, * then checks for Capability work item type to detect SAFe/Enterprise. * * @param project - Optional project name (uses default if not specified) * @returns Process template info with hierarchy mapping */ detectProcessTemplate(project?: string): Promise; /** * Build hierarchy mapping based on process template */ private buildHierarchyMapping; /** * Test connection to Azure DevOps */ testConnection(): Promise; /** * Add comment to Azure DevOps work item (T-034C) * * POST /{organization}/{project}/_apis/wit/workitems/{id}/comments?api-version=7.0 */ addComment(workItemId: number, comment: string): Promise; /** * Get last comment on Azure DevOps work item (for idempotency check) * * GET /{organization}/{project}/_apis/wit/workitems/{id}/comments?$top=1&order=desc&api-version=7.0-preview */ getLastComment(workItemId: number): Promise<{ text: string; } | null>; } //# sourceMappingURL=ado-client.d.ts.map