@dcyfr/ai 3.0.1 → 3.0.3

package/dist/ai/src/integrations/linear/issue-mapper.js

@@ -0,0 +1,186 @@
+/**
+ * Issue Key Correlation and Mapping
+ *
+ * Extracts issue keys from GitHub PR titles, branch names, and commit messages
+ * to automatically correlate them with Linear issues. Implements a priority-based
+ * matching strategy and stores mappings for future reference.
+ *
+ * Correlation Strategy (in order of confidence):
+ *   1. Branch name:   `feature/DCYFR-123-description`  [confidence: 0.95]
+ *   2. PR title:      `[DCYFR-123] Feature description` [confidence: 0.85]
+ *   3. Commit message: Usually at end: `... Fixes DCYFR-123` [confidence: 0.75]
+ *   4. Manual mapping: User explicitly linked (stored in DB) [confidence: 1.0]
+ *
+ * Usage:
+ *   const mapper = new IssueMapper({ store: myMappingStore });
+ *   const match = await mapper.correlate({
+ *     branch: 'feature/DCYFR-123-auth',
+ *     prTitle: '[DCYFR-123] Add OAuth',
+ *     commits: ['Add auth module (#123)', 'Fixes DCYFR-123']
+ *   });
+ *   // => { linearIssueId: 'uuid-xxx', identifier: 'DCYFR-123', confidence: 0.95 }
+ *
+ * Part of: Phase 2 (MVP Linear Sync) + Phase 3 (Bidirectional Sync)
+ * Test: __tests__/integrations/linear/issue-mapper.test.ts
+ */
+// ============================================================================
+// Issue Key Regex Patterns
+// ============================================================================
+/**
+ * Matches Jira-style issue keys: TEAM-NUMBER
+ * Examples: DCYFR-123, FOO-999
+ *
+ * Pattern explanation:
+ *   [A-Z]+ = one or more uppercase letters (team key)
+ *   - = hyphen
+ *   \d+ = one or more digits (issue number)
+ */
+const ISSUE_KEY_PATTERN = /([A-Z][A-Z0-9]*-\d+)/g;
+/**
+ * Branch name format: feature/TEAM-NUMBER-description
+ */
+const BRANCH_PATTERN = /^[a-z]+\/([A-Z][A-Z0-9]*-\d+)/;
+/**
+ * PR title format: "[TEAM-NUMBER] Description" or "[TEAM-NUMBER] Description (Fixes)"
+ */
+const PR_TITLE_PATTERN = /^\[([A-Z][A-Z0-9]*-\d+)\]/;
+/**
+ * Commit pattern: "Description (Fixes|Closes|Resolves) TEAM-NUMBER"
+ */
+const COMMIT_PATTERN = /(Fixes|Closes|Resolves|Fixed|Closed|Resolved)\s+([A-Z][A-Z0-9]*-\d+)/i;
+// ============================================================================
+// IssueMapper
+// ============================================================================
+export class IssueMapper {
+    /**
+     * Extract issue key from a string, returning up to `limit` matches.
+     */
+    static extractIssueKeys(text, limit = 5) {
+        const matches = text.matchAll(ISSUE_KEY_PATTERN);
+        return Array.from(matches)
+            .map(m => m[1])
+            .slice(0, limit)
+            .filter((v, i, a) => a.indexOf(v) === i); // Deduplicate
+    }
+    /**
+     * Extract issue key from branch name (highest confidence).
+     * Pattern: feature/DCYFR-123-description
+     */
+    static extractFromBranch(branch) {
+        const match = branch.match(BRANCH_PATTERN);
+        return match ? match[1] : null;
+    }
+    /**
+     * Extract issue key from PR title (high confidence).
+     * Patterns: "[DCYFR-123] Title", "[DCYFR-123]: Title"
+     */
+    static extractFromPrTitle(title) {
+        const match = title.match(PR_TITLE_PATTERN);
+        return match ? match[1] : null;
+    }
+    /**
+     * Extract issue key from commit messages (moderate confidence).
+     * Patterns: "Fixes DCYFR-123", "Closes DCYFR-123", "Resolves DCYFR-123"
+     */
+    static extractFromCommits(commits) {
+        for (const commit of commits) {
+            const match = commit.match(COMMIT_PATTERN);
+            if (match) {
+                return match[2]; // Return the issue key
+            }
+        }
+        return null;
+    }
+    /**
+     * Extract issue keys from PR body/description (low confidence).
+     * Uses generic issue key pattern matching.
+     */
+    static extractFromPrBody(body) {
+        return this.extractIssueKeys(body, 1);
+    }
+    /**
+     * Correlate a pull request to a Linear issue by examining branch, title, commits, and body.
+     *
+     * Returns the best match with highest confidence, plus alternates for manual review.
+     * Implements priority-based matching:
+     *   1. Branch name (0.95) — most specific
+     *   2. PR title (0.85)
+     *   3. Commit messages (0.75)
+     *   4. PR body (0.60) — lowest confidence
+     */
+    static correlate(input) {
+        const candidates = [];
+        // 1. Branch (highest priority)
+        if (input.branch) {
+            const key = this.extractFromBranch(input.branch);
+            if (key) {
+                candidates.push({
+                    identifier: key,
+                    source: 'branch',
+                    confidence: 0.95,
+                });
+            }
+        }
+        // 2. PR title
+        if (input.prTitle) {
+            const key = this.extractFromPrTitle(input.prTitle);
+            if (key) {
+                candidates.push({
+                    identifier: key,
+                    source: 'pr_title',
+                    confidence: 0.85,
+                });
+            }
+        }
+        // 3. Commit messages
+        if (input.commits && input.commits.length > 0) {
+            const key = this.extractFromCommits(input.commits);
+            if (key) {
+                candidates.push({
+                    identifier: key,
+                    source: 'commit_message',
+                    confidence: 0.75,
+                });
+            }
+        }
+        // 4. PR body
+        if (input.prBody) {
+            const keys = this.extractFromPrBody(input.prBody);
+            for (const key of keys) {
+                candidates.push({
+                    identifier: key,
+                    source: 'pr_body',
+                    confidence: 0.60,
+                });
+            }
+        }
+        // Return best match (by confidence, then by source priority)
+        if (candidates.length === 0) {
+            return {
+                identifier: null,
+                source: null,
+                confidence: 0,
+                alternates: [],
+            };
+        }
+        // Sort by confidence descending
+        candidates.sort((a, b) => b.confidence - a.confidence);
+        const best = candidates[0];
+        const alternates = candidates.slice(1);
+        return {
+            identifier: best.identifier,
+            source: best.source,
+            confidence: best.confidence,
+            alternates,
+        };
+    }
+    /**
+     * Validate that a correlation result meets minimum confidence threshold.
+     * Default threshold: 0.8 (requires high confidence)
+     */
+    static isConfident(result, threshold = 0.8) {
+        return result.confidence >= threshold && result.identifier !== null;
+    }
+}
+export default IssueMapper;
+//# sourceMappingURL=issue-mapper.js.map

package/dist/ai/src/integrations/linear/issue-mapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"issue-mapper.js","sourceRoot":"","sources":["../../../../../packages/ai/src/integrations/linear/issue-mapper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AA4BH,+EAA+E;AAC/E,2BAA2B;AAC3B,+EAA+E;AAE/E;;;;;;;;GAQG;AACH,MAAM,iBAAiB,GAAG,uBAAuB,CAAC;AAElD;;GAEG;AACH,MAAM,cAAc,GAAG,+BAA+B,CAAC;AAEvD;;GAEG;AACH,MAAM,gBAAgB,GAAG,2BAA2B,CAAC;AAErD;;GAEG;AACH,MAAM,cAAc,GAAG,uEAAuE,CAAC;AAE/F,+EAA+E;AAC/E,cAAc;AACd,+EAA+E;AAE/E,MAAM,OAAO,WAAW;IACpB;;OAEG;IACH,MAAM,CAAC,gBAAgB,CAAC,IAAY,EAAE,QAAgB,CAAC;QACnD,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAC;QACjD,OAAO,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC;aACrB,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;aACd,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC;aACf,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,cAAc;IAChE,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,iBAAiB,CAAC,MAAc;QACnC,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;QAC3C,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACnC,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,kBAAkB,CAAC,KAAa;QACnC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC;QAC5C,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACnC,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,kBAAkB,CAAC,OAAiB;QACvC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC3B,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;YAC3C,IAAI,KAAK,EAAE,CAAC;gBACR,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,uBAAuB;YAC5C,CAAC;QACL,CAAC;QACD,OAAO,IAAI,CAAC;IAChB,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,iBAAiB,CAAC,IAAY;QACjC,OAAO,IAAI,CAAC,gBAAgB,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IAC1C,CAAC;IAED;;;;;;;;;OASG;IACH,MAAM,CAAC,SAAS,CAAC,KAAuB;QACpC,MAAM,UAAU,GAIX,EAAE,CAAC;QAER,+BAA+B;QAC/B,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;YACf,MAAM,GAAG,GAAG,IAAI,CAAC,iBAAiB,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YACjD,IAAI,GAAG,EAAE,CAAC;gBACN,UAAU,CAAC,IAAI,CAAC;oBACZ,UAAU,EAAE,GAAG;oBACf,MAAM,EAAE,QAAQ;oBAChB,UAAU,EAAE,IAAI;iBACnB,CAAC,CAAC;YACP,CAAC;QACL,CAAC;QAED,cAAc;QACd,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;YAChB,MAAM,GAAG,GAAG,IAAI,CAAC,kBAAkB,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YACnD,IAAI,GAAG,EAAE,CAAC;gBACN,UAAU,CAAC,IAAI,CAAC;oBACZ,UAAU,EAAE,GAAG;oBACf,MAAM,EAAE,UAAU;oBAClB,UAAU,EAAE,IAAI;iBACnB,CAAC,CAAC;YACP,CAAC;QACL,CAAC;QAED,qBAAqB;QACrB,IAAI,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC5C,MAAM,GAAG,GAAG,IAAI,CAAC,kBAAkB,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YACnD,IAAI,GAAG,EAAE,CAAC;gBACN,UAAU,CAAC,IAAI,CAAC;oBACZ,UAAU,EAAE,GAAG;oBACf,MAAM,EAAE,gBAAgB;oBACxB,UAAU,EAAE,IAAI;iBACnB,CAAC,CAAC;YACP,CAAC;QACL,CAAC;QAED,aAAa;QACb,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;YACf,MAAM,IAAI,GAAG,IAAI,CAAC,iBAAiB,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YAClD,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;gBACrB,UAAU,CAAC,IAAI,CAAC;oBACZ,UAAU,EAAE,GAAG;oBACf,MAAM,EAAE,SAAS;oBACjB,UAAU,EAAE,IAAI;iBACnB,CAAC,CAAC;YACP,CAAC;QACL,CAAC;QAED,6DAA6D;QAC7D,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,OAAO;gBACH,UAAU,EAAE,IAAI;gBAChB,MAAM,EAAE,IAAI;gBACZ,UAAU,EAAE,CAAC;gBACb,UAAU,EAAE,EAAE;aACjB,CAAC;QACN,CAAC;QAED,gCAAgC;QAChC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC;QAEvD,MAAM,IAAI,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;QAC3B,MAAM,UAAU,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAEvC,OAAO;YACH,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,MAAM,EAAE,IAAI,CAAC,MAAa;YAC1B,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,UAAU;SACb,CAAC;IACN,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,WAAW,CAAC,MAAyB,EAAE,SAAS,GAAG,GAAG;QACzD,OAAO,MAAM,CAAC,UAAU,IAAI,SAAS,IAAI,MAAM,CAAC,UAAU,KAAK,IAAI,CAAC;IACxE,CAAC;CACJ;AAED,eAAe,WAAW,CAAC"}

package/dist/ai/src/integrations/linear/linear-client.d.ts

@@ -0,0 +1,199 @@
+/**
+ * Linear API Client
+ *
+ * Provides a typed, authenticated wrapper around the Linear GraphQL API for
+ * reading/writing issues, creating comments, adding labels, and managing
+ * issue state transitions.
+ *
+ * Usage:
+ *   const client = new LinearClient({ apiKey: process.env.LINEAR_API_KEY });
+ *   const issue = await client.getIssue('DCYFR-123');
+ *   await client.addComment(issue.id, 'Review started');
+ *   await client.updateIssueState(issue.id, 'In Review');
+ *
+ * Authentication:
+ *   - Requires LINEAR_API_KEY environment variable (org API key)
+ *   - API documentation: https://developers.linear.app/docs
+ *   - GraphQL endpoint: https://api.linear.app/graphql
+ *
+ * Rate Limiting:
+ *   - Linear API: 1000 requests/hour per token
+ *   - Implements sliding-window rate limiter with exponential backoff
+ *
+ * Idempotency:
+ *   - All write operations include deduplication keys
+ *   - Prevents duplicate comments/updates on identical requests
+ *
+ * Error Handling:
+ *   - GraphQL errors returned as structured `LinearError`
+ *   - Network failures trigger exponential backoff retry
+ *   - Rate limits surface as `RateLimitError`
+ *
+ * Part of: dcyfr-ai integration layer
+ * Roadmap: Phase 2 (MVP Linear Sync) + Phase 3 (Bidirectional Sync)
+ * Test: __tests__/integrations/linear/linear-client.test.ts
+ */
+type GraphQLError = {
+    message: string;
+    extensions?: Record<string, unknown>;
+};
+/**
+ * Linear API credentials and configuration.
+ */
+export interface LinearClientConfig {
+    /** Linear API key (org-scoped, from workspace settings) */
+    apiKey: string;
+    /** Optional: Override GraphQL endpoint (default: https://api.linear.app/graphql) */
+    graphqlEndpoint?: string;
+    /** Optional: Maximum retry attempts for transient failures (default: 3) */
+    maxRetries?: number;
+    /** Optional: Timeout in ms for API requests (default: 30000) */
+    requestTimeout?: number;
+}
+/**
+ * Mapping between Linear issue and GitHub PR/issue.
+ * Stored in persistent mapping store for correlation.
+ */
+export interface IssueMapping {
+    /** Linear issue ID (UUID) */
+    linearIssueId: string;
+    /** GitHub repository owner */
+    owner: string;
+    /** GitHub repository name */
+    repo: string;
+    /** GitHub PR number (if PR) or issue number (if issue) */
+    prOrIssueNumber: number;
+    /** How the correlation was established */
+    correlationSource: 'branch' | 'pr_title' | 'commit_message' | 'manual';
+    /** Confidence score (0-1); 1.0 = certain, < 0.8 = needs review */
+    confidence: number;
+    /** When the mapping was created */
+    createdAt: Date;
+    /** When the mapping was last verified */
+    lastVerifiedAt?: Date;
+}
+/**
+ * Linear issue with relevant fields for review/PR sync.
+ */
+export interface LinearIssue {
+    id: string;
+    identifier: string;
+    title: string;
+    description?: string;
+    state: {
+        id: string;
+        name: string;
+    };
+    assignee?: {
+        id: string;
+        name: string;
+        email: string;
+    };
+    team: {
+        id: string;
+        key: string;
+    };
+    labels: Array<{
+        id: string;
+        name: string;
+    }>;
+    createdAt: string;
+    updatedAt: string;
+    /** Custom field for linking to GitHub PR */
+    _githubPrUrl?: string;
+    /** Custom field for PR review status */
+    _prReviewStatus?: 'pending' | 'in_progress' | 'approved' | 'changes_requested';
+}
+/**
+ * Linear issue state for workflow transitions.
+ */
+export interface LinearIssueState {
+    id: string;
+    name: string;
+    type: 'backlog' | 'unstarted' | 'started' | 'completed' | 'cancelled';
+    position: number;
+}
+/**
+ * Comment created on a Linear issue.
+ */
+export interface LinearComment {
+    id: string;
+    body: string;
+    author: {
+        id: string;
+        name: string;
+    };
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Linear API error with detailed context.
+ */
+export declare class LinearError extends Error {
+    readonly statusCode?: number | undefined;
+    readonly graphqlErrors?: GraphQLError[] | undefined;
+    constructor(message: string, statusCode?: number | undefined, graphqlErrors?: GraphQLError[] | undefined);
+}
+/**
+ * Rate limit error when API quota is exceeded.
+ */
+export declare class LinearRateLimitError extends LinearError {
+    readonly resetAt: Date;
+    constructor(message: string, resetAt: Date);
+}
+export declare class LinearClient {
+    private apiKey;
+    private graphqlEndpoint;
+    private maxRetries;
+    private requestTimeout;
+    private requestCount;
+    private requestResetAt;
+    constructor(config: LinearClientConfig);
+    /**
+     * Retrieve a Linear issue by identifier (e.g., "DCYFR-123").
+     */
+    getIssue(identifier: string): Promise<LinearIssue>;
+    /**
+     * Get all available workflow states for a team.
+     * Used for determining valid state transitions.
+     */
+    getWorkflowStates(teamId: string): Promise<LinearIssueState[]>;
+    /**
+     * Update an issue's state (e.g., "In Review" → "Changes Requested").
+     * Returns the updated issue.
+     */
+    updateIssueState(issueId: string, newState: string): Promise<LinearIssue>;
+    /**
+     * Add a comment to a Linear issue.
+     * Includes deduplication key to prevent duplicate comments.
+     */
+    addComment(issueId: string, body: string, deduplicationKey?: string): Promise<LinearComment>;
+    /**
+     * Add a label to a Linear issue.
+     */
+    addLabel(issueId: string, labelId: string): Promise<void>;
+    /**
+     * Assign a Linear issue to a team member.
+     */
+    assignIssue(issueId: string, userId: string): Promise<void>;
+    /**
+     * Search for issues by query (e.g., team or label filters).
+     * Used for finding issues linked to GitHub PRs.
+     */
+    searchIssues(query: string, limit?: number): Promise<LinearIssue[]>;
+    /**
+     * Internal: Execute a GraphQL query/mutation with rate-limit and retry handling.
+     */
+    private graphql;
+    /**
+     * Check if request is within rate limit quota.
+     * Resets hourly.
+     */
+    private checkRateLimit;
+    /**
+     * Determine if an error is transient (can be retried).
+     */
+    private isTransient;
+}
+export default LinearClient;
+//# sourceMappingURL=linear-client.d.ts.map

package/dist/ai/src/integrations/linear/linear-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"linear-client.d.ts","sourceRoot":"","sources":["../../../../../packages/ai/src/integrations/linear/linear-client.ts"],"names":[],"mappings":"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"}

package/dist/ai/src/integrations/linear/linear-client.js

@@ -0,0 +1,300 @@
+/**
+ * Linear API Client
+ *
+ * Provides a typed, authenticated wrapper around the Linear GraphQL API for
+ * reading/writing issues, creating comments, adding labels, and managing
+ * issue state transitions.
+ *
+ * Usage:
+ *   const client = new LinearClient({ apiKey: process.env.LINEAR_API_KEY });
+ *   const issue = await client.getIssue('DCYFR-123');
+ *   await client.addComment(issue.id, 'Review started');
+ *   await client.updateIssueState(issue.id, 'In Review');
+ *
+ * Authentication:
+ *   - Requires LINEAR_API_KEY environment variable (org API key)
+ *   - API documentation: https://developers.linear.app/docs
+ *   - GraphQL endpoint: https://api.linear.app/graphql
+ *
+ * Rate Limiting:
+ *   - Linear API: 1000 requests/hour per token
+ *   - Implements sliding-window rate limiter with exponential backoff
+ *
+ * Idempotency:
+ *   - All write operations include deduplication keys
+ *   - Prevents duplicate comments/updates on identical requests
+ *
+ * Error Handling:
+ *   - GraphQL errors returned as structured `LinearError`
+ *   - Network failures trigger exponential backoff retry
+ *   - Rate limits surface as `RateLimitError`
+ *
+ * Part of: dcyfr-ai integration layer
+ * Roadmap: Phase 2 (MVP Linear Sync) + Phase 3 (Bidirectional Sync)
+ * Test: __tests__/integrations/linear/linear-client.test.ts
+ */
+/**
+ * Linear API error with detailed context.
+ */
+export class LinearError extends Error {
+    statusCode;
+    graphqlErrors;
+    constructor(message, statusCode, graphqlErrors) {
+        super(message);
+        this.statusCode = statusCode;
+        this.graphqlErrors = graphqlErrors;
+        this.name = 'LinearError';
+    }
+}
+/**
+ * Rate limit error when API quota is exceeded.
+ */
+export class LinearRateLimitError extends LinearError {
+    resetAt;
+    constructor(message, resetAt) {
+        super(message, 429);
+        this.resetAt = resetAt;
+        this.name = 'LinearRateLimitError';
+    }
+}
+// ============================================================================
+// Linear Client
+// ============================================================================
+export class LinearClient {
+    apiKey;
+    graphqlEndpoint;
+    maxRetries;
+    requestTimeout;
+    requestCount = 0;
+    requestResetAt = Date.now() + 3600000; // 1 hour from now
+    constructor(config) {
+        this.apiKey = config.apiKey;
+        this.graphqlEndpoint = config.graphqlEndpoint ?? 'https://api.linear.app/graphql';
+        this.maxRetries = config.maxRetries ?? 3;
+        this.requestTimeout = config.requestTimeout ?? 30000;
+        if (!this.apiKey) {
+            throw new LinearError('LINEAR_API_KEY is required');
+        }
+    }
+    /**
+     * Retrieve a Linear issue by identifier (e.g., "DCYFR-123").
+     */
+    async getIssue(identifier) {
+        const query = `
+      query GetIssue($identifier: String!) {
+        issue(id: $identifier) {
+          id
+          identifier
+          title
+          description
+          state { id name }
+          assignee { id name email }
+          team { id key }
+          labels { id name }
+          createdAt
+          updatedAt
+        }
+      }
+    `;
+        const data = await this.graphql(query, { identifier });
+        return data.issue;
+    }
+    /**
+     * Get all available workflow states for a team.
+     * Used for determining valid state transitions.
+     */
+    async getWorkflowStates(teamId) {
+        const query = `
+      query GetWorkflowStates($teamId: String!) {
+        team(id: $teamId) {
+          states {
+            nodes {
+              id
+              name
+              type
+              position
+            }
+          }
+        }
+      }
+    `;
+        const data = await this.graphql(query, { teamId });
+        return data.team.states.nodes;
+    }
+    /**
+     * Update an issue's state (e.g., "In Review" → "Changes Requested").
+     * Returns the updated issue.
+     */
+    async updateIssueState(issueId, newState) {
+        const mutation = `
+      mutation UpdateIssueState($issueId: String!, $state: String!) {
+        issueUpdate(id: $issueId, input: { stateId: $state }) {
+          issue {
+            id
+            identifier
+            title
+            state { id name }
+            updatedAt
+          }
+        }
+      }
+    `;
+        const data = await this.graphql(mutation, { issueId, state: newState });
+        return data.issueUpdate.issue;
+    }
+    /**
+     * Add a comment to a Linear issue.
+     * Includes deduplication key to prevent duplicate comments.
+     */
+    async addComment(issueId, body, deduplicationKey) {
+        const mutation = `
+      mutation AddComment($issueId: String!, $body: String!, $deduplicationKey: String) {
+        commentCreate(input: { issueId: $issueId, body: $body, deduplicationKey: $deduplicationKey }) {
+          comment {
+            id
+            body
+            author { id name }
+            createdAt
+            updatedAt
+          }
+        }
+      }
+    `;
+        const data = await this.graphql(mutation, { issueId, body, deduplicationKey });
+        return data.commentCreate.comment;
+    }
+    /**
+     * Add a label to a Linear issue.
+     */
+    async addLabel(issueId, labelId) {
+        const mutation = `
+      mutation AddLabel($issueId: String!, $labelIds: [String!]!) {
+        issueUpdate(id: $issueId, input: { labelIds: $labelIds }) {
+          issue { id }
+        }
+      }
+    `;
+        await this.graphql(mutation, { issueId, labelIds: [labelId] });
+    }
+    /**
+     * Assign a Linear issue to a team member.
+     */
+    async assignIssue(issueId, userId) {
+        const mutation = `
+      mutation AssignIssue($issueId: String!, $userId: String!) {
+        issueUpdate(id: $issueId, input: { assigneeId: $userId }) {
+          issue { id }
+        }
+      }
+    `;
+        await this.graphql(mutation, { issueId, userId });
+    }
+    /**
+     * Search for issues by query (e.g., team or label filters).
+     * Used for finding issues linked to GitHub PRs.
+     */
+    async searchIssues(query, limit = 25) {
+        const graphqlQuery = `
+      query SearchIssues($query: String!, $first: Int!) {
+        issues(filter: $query, first: $first) {
+          nodes {
+            id
+            identifier
+            title
+            description
+            state { id name }
+            assignee { id name email }
+            team { id key }
+            labels { id name }
+            createdAt
+            updatedAt
+          }
+        }
+      }
+    `;
+        const data = await this.graphql(graphqlQuery, { query, first: limit });
+        return data.issues.nodes;
+    }
+    /**
+     * Internal: Execute a GraphQL query/mutation with rate-limit and retry handling.
+     */
+    async graphql(query, variables, retryCount = 0) {
+        // Check rate limit
+        this.checkRateLimit();
+        const payload = {
+            query,
+            variables: variables ?? {},
+        };
+        const options = {
+            method: 'POST',
+            headers: {
+                'Authorization': `Bearer ${this.apiKey}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(payload),
+            timeout: this.requestTimeout,
+        };
+        try {
+            const response = await fetch(this.graphqlEndpoint, options);
+            this.requestCount++;
+            // Handle rate limiting
+            if (response.status === 429) {
+                const resetAfter = response.headers.get('Retry-After');
+                const resetAt = new Date(Date.now() + (Number.parseInt(resetAfter ?? '60', 10) * 1000));
+                throw new LinearRateLimitError('Linear API rate limit exceeded', resetAt);
+            }
+            if (!response.ok) {
+                throw new LinearError(`Linear API returned ${response.status}`, response.status);
+            }
+            const data = await response.json();
+            // Handle GraphQL errors
+            if (data.errors && data.errors.length > 0) {
+                throw new LinearError(`GraphQL error: ${data.errors[0].message}`, 400, data.errors);
+            }
+            return data.data;
+        }
+        catch (error) {
+            // Retry on transient errors
+            if (retryCount < this.maxRetries && this.isTransient(error)) {
+                const backoffMs = Math.pow(2, retryCount) * 1000;
+                await new Promise(resolve => setTimeout(resolve, backoffMs));
+                return this.graphql(query, variables, retryCount + 1);
+            }
+            if (error instanceof LinearError) {
+                throw error;
+            }
+            throw new LinearError(`Linear API request failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Check if request is within rate limit quota.
+     * Resets hourly.
+     */
+    checkRateLimit() {
+        const now = Date.now();
+        // Reset counter if window has passed
+        if (now > this.requestResetAt) {
+            this.requestCount = 0;
+            this.requestResetAt = now + 3600000; // 1 hour from now
+        }
+        // Linear: 1000 requests/hour
+        if (this.requestCount >= 1000) {
+            throw new LinearRateLimitError('Linear API rate limit exceeded (1000/hour)', new Date(this.requestResetAt));
+        }
+    }
+    /**
+     * Determine if an error is transient (can be retried).
+     */
+    isTransient(error) {
+        if (error instanceof LinearRateLimitError) {
+            return true;
+        }
+        if (error instanceof LinearError) {
+            // Only retry on server errors (5xx)
+            return error.statusCode ? error.statusCode >= 500 : false;
+        }
+        return true; // Assume network errors are transient
+    }
+}
+export default LinearClient;
+//# sourceMappingURL=linear-client.js.map