@enrichlayer/el-linear 1.44.2 → 1.46.0

package/dist/utils/graphql-service.d.ts

@@ -1,6 +1,10 @@
+import { LinearClient } from "@linear/sdk";
 import type { LinearCredential } from "../auth/linear-credential.js";
+import type { OAuthState } from "../auth/oauth-storage.js";
 import type { GraphQLResponseData, GraphQLVariables } from "../types/linear.js";
 import type { AuthOptions } from "./auth.js";
+import { type RateLimitInfo } from "./output.js";
+import { type RateLimitAdmission } from "./rate-limit-admission.js";
 export interface GraphQLRequestOptions {
     /**
      * Retry only an operation whose mutation is safe to repeat. Callers must
@@ -13,8 +17,30 @@ export interface GraphQLRequestOptions {
 interface GraphQLServiceRuntimeOptions {
     retryDelaysMs?: readonly number[];
     sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    /** Test/embedding seam; production derives this from EL_LINEAR_RATE_LIMIT_HEADROOM. */
+    admission?: RateLimitAdmission;
+    /** Reacquire an app-user client-credentials token after HTTP 401. */
+    renewAccessToken?: () => Promise<string>;
 }
-/** True only for failures where retrying a known-idempotent request is useful. */
+type OAuthStateRenewal = (state: OAuthState, options: {
+    forceOAuthRenewal: true;
+}) => Promise<OAuthState>;
+/**
+ * Keep the last persisted client-credentials state in a long-lived service.
+ * Each forced 401 renewal must advance from the previous renewal, not from the
+ * state captured when the service was constructed.
+ */
+export declare function createClientCredentialsTokenRenewal(initialState: OAuthState, renew?: OAuthStateRenewal): (() => Promise<string>) | undefined;
+export declare function extractRateLimitInfo(source: unknown, now: () => number): RateLimitInfo | undefined;
+/** True for both HTTP and GraphQL representations of Linear rate limiting. */
+export declare function isRateLimitGraphQLError(error: unknown): boolean;
+/**
+ * True only for failures where retrying a known-idempotent request immediately
+ * is useful. This deliberately differs from published `errorDetail.retryable`:
+ * a rate limit is transient for an external caller with reset-aware backoff,
+ * but must never enter this CLI's 150 ms / 400 ms retry loop.
+ */
 export declare function isTransientGraphQLError(error: unknown): boolean;
 /**
  * Constructor arg for `GraphQLService`. Re-exported alias of the shared
@@ -28,11 +54,26 @@ export declare function isTransientGraphQLError(error: unknown): boolean;
  * semantic change — same `Authorization: <token>` header is emitted).
  */
 export type GraphQLServiceAuth = LinearCredential;
+/**
+ * Put SDK-backed LinearService calls through the same quota admission and
+ * response-header observer as custom GraphQLService calls. The SDK's public
+ * `request()` discards response headers, so this narrow transport adapter uses
+ * its own public-ish rawRequest escape hatch and returns only `data` to the
+ * generated SDK models, preserving their existing contract.
+ */
+export declare function instrumentLinearClient(client: LinearClient, auth: GraphQLServiceAuth, options?: {
+    admission?: RateLimitAdmission;
+    now?: () => number;
+}): LinearClient;
 export declare class GraphQLService {
     private readonly graphQLClient;
     private readonly retryDelaysMs;
     private readonly sleep;
+    private readonly now;
+    private readonly admission;
+    private readonly renewAccessToken?;
     constructor(auth: GraphQLServiceAuth, options?: GraphQLServiceRuntimeOptions);
+    private observeRateLimit;
     rawRequest<T = GraphQLResponseData>(query: string, variables?: GraphQLVariables, options?: GraphQLRequestOptions): Promise<T>;
 }
 export declare function createGraphQLService(options: AuthOptions): Promise<GraphQLService>;

package/dist/utils/graphql-service.js

@@ -1,19 +1,180 @@
 import { LinearClient } from "@linear/sdk";
-import { getActiveAuth } from "../auth/token-resolver.js";
+import { print } from "graphql";
+import { ensureFreshAccessToken, getActiveAuth, } from "../auth/token-resolver.js";
+import { graphQLErrorCode, graphQLErrorHttpStatus, toLinearGraphQLError, } from "./linear-graphql-error.js";
+import { logger } from "./logger.js";
+import { recordRateLimitInfo } from "./output.js";
+import { createOAuthProfileRateLimitAdmission, createRateLimitAdmission, RateLimitAdmissionRefusal, } from "./rate-limit-admission.js";
 const DEFAULT_SAFE_MUTATION_RETRY_DELAYS_MS = [150, 400];
+/**
+ * Keep the last persisted client-credentials state in a long-lived service.
+ * Each forced 401 renewal must advance from the previous renewal, not from the
+ * state captured when the service was constructed.
+ */
+export function createClientCredentialsTokenRenewal(initialState, renew = ensureFreshAccessToken) {
+    if (initialState.grantType !== "client_credentials")
+        return undefined;
+    let currentState = initialState;
+    return async () => {
+        currentState = await renew(currentState, { forceOAuthRenewal: true });
+        return currentState.accessToken;
+    };
+}
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
-/** True only for failures where retrying a known-idempotent request is useful. */
+function errorDetail(error) {
+    return error;
+}
+function errorResponse(error) {
+    const detail = errorDetail(error);
+    return detail.response ?? detail.raw?.response;
+}
+function headerValue(headers, name) {
+    if (!headers)
+        return undefined;
+    if ("get" in headers && typeof headers.get === "function") {
+        return headers.get(name) ?? undefined;
+    }
+    const expected = name.toLowerCase();
+    const entry = Object.entries(headers).find(([key]) => key.toLowerCase() === expected);
+    return entry?.[1];
+}
+function finiteNumber(value) {
+    if (value === undefined || value === null || value === "")
+        return undefined;
+    const parsed = typeof value === "number" ? value : Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+function resetAtFromRetryAfter(value, now) {
+    if (value === undefined)
+        return undefined;
+    const seconds = finiteNumber(value);
+    if (seconds !== undefined) {
+        return new Date(now() + seconds * 1_000).toISOString();
+    }
+    if (typeof value === "string") {
+        const timestamp = Date.parse(value);
+        if (Number.isFinite(timestamp))
+            return new Date(timestamp).toISOString();
+    }
+    return undefined;
+}
+export function extractRateLimitInfo(source, now) {
+    const detail = errorDetail(source);
+    const response = errorResponse(source) ?? source;
+    const headers = response?.headers;
+    const limit = finiteNumber(detail.requestsLimit ?? headerValue(headers, "x-ratelimit-requests-limit"));
+    const remaining = finiteNumber(detail.requestsRemaining ??
+        headerValue(headers, "x-ratelimit-requests-remaining"));
+    const resetTimestamp = finiteNumber(detail.requestsResetAt ??
+        headerValue(headers, "x-ratelimit-requests-reset"));
+    const resetAt = resetTimestamp !== undefined
+        ? new Date(resetTimestamp).toISOString()
+        : resetAtFromRetryAfter(detail.retryAfter ?? headerValue(headers, "retry-after"), now);
+    const complexityCost = finiteNumber(headerValue(headers, "x-complexity"));
+    const complexityLimit = finiteNumber(headerValue(headers, "x-ratelimit-complexity-limit"));
+    const complexityRemaining = finiteNumber(headerValue(headers, "x-ratelimit-complexity-remaining"));
+    const complexityResetTimestamp = finiteNumber(headerValue(headers, "x-ratelimit-complexity-reset"));
+    const endpointName = headerValue(headers, "x-ratelimit-endpoint-name");
+    const endpointLimit = finiteNumber(headerValue(headers, "x-ratelimit-endpoint-requests-limit"));
+    const endpointRemaining = finiteNumber(headerValue(headers, "x-ratelimit-endpoint-requests-remaining"));
+    const endpointResetTimestamp = finiteNumber(headerValue(headers, "x-ratelimit-endpoint-requests-reset"));
+    const hasComplexity = complexityCost !== undefined ||
+        complexityLimit !== undefined ||
+        complexityRemaining !== undefined ||
+        complexityResetTimestamp !== undefined;
+    const hasEndpoint = endpointName !== undefined ||
+        endpointLimit !== undefined ||
+        endpointRemaining !== undefined ||
+        endpointResetTimestamp !== undefined;
+    if (limit === undefined &&
+        remaining === undefined &&
+        resetAt === undefined &&
+        !hasComplexity &&
+        !hasEndpoint) {
+        return undefined;
+    }
+    return {
+        limit,
+        remaining,
+        resetAt,
+        observedRequests: 1,
+        minimumRemaining: remaining,
+        ...(hasComplexity
+            ? {
+                complexity: {
+                    cost: complexityCost,
+                    totalCost: complexityCost,
+                    limit: complexityLimit,
+                    remaining: complexityRemaining,
+                    minimumRemaining: complexityRemaining,
+                    resetAt: complexityResetTimestamp === undefined
+                        ? undefined
+                        : new Date(complexityResetTimestamp).toISOString(),
+                },
+            }
+            : {}),
+        ...(hasEndpoint
+            ? {
+                endpoints: {
+                    [endpointName ?? "unknown"]: {
+                        limit: endpointLimit,
+                        remaining: endpointRemaining,
+                        minimumRemaining: endpointRemaining,
+                        resetAt: endpointResetTimestamp === undefined
+                            ? undefined
+                            : new Date(endpointResetTimestamp).toISOString(),
+                        observedRequests: 1,
+                    },
+                },
+            }
+            : {}),
+    };
+}
+/** True for both HTTP and GraphQL representations of Linear rate limiting. */
+export function isRateLimitGraphQLError(error) {
+    const detail = errorDetail(error);
+    if (graphQLErrorHttpStatus(error) === 429 ||
+        graphQLErrorCode(error)?.toUpperCase() === "RATELIMITED" ||
+        detail.type?.toLowerCase() === "ratelimited") {
+        return true;
+    }
+    return /\b(?:429|rate[- ]?limit(?:ed| exceeded))\b/i.test(errorMessage(error));
+}
+/**
+ * True only for failures where retrying a known-idempotent request immediately
+ * is useful. This deliberately differs from published `errorDetail.retryable`:
+ * a rate limit is transient for an external caller with reset-aware backoff,
+ * but must never enter this CLI's 150 ms / 400 ms retry loop.
+ */
 export function isTransientGraphQLError(error) {
-    const detail = error;
-    const status = detail.response?.status ?? detail.response?.statusCode;
-    if (status === 408 ||
-        status === 429 ||
-        (status !== undefined && status >= 500)) {
+    if (isRateLimitGraphQLError(error))
+        return false;
+    const status = graphQLErrorHttpStatus(error);
+    if (status === 408 || (status !== null && status >= 500)) {
         return true;
     }
-    return /\b(?:408|429|500|502|503|504)\b|(?:ECONNRESET|ECONNREFUSED|ETIMEDOUT|fetch failed|network error|connection termination)/i.test(errorMessage(error));
+    return /\b(?:408|500|502|503|504)\b|(?:ECONNRESET|ECONNREFUSED|ETIMEDOUT|fetch failed|network error|connection termination)/i.test(errorMessage(error));
+}
+function isMutationOperation(query) {
+    const withoutLeadingComments = query.replace(/^(?:\s*#[^\n]*(?:\n|$))*/, "");
+    return /^\s*mutation\b/i.test(withoutLeadingComments);
+}
+function rateLimitError(error, query, now) {
+    const rateLimit = extractRateLimitInfo(error, now);
+    const details = [];
+    if (rateLimit?.remaining !== undefined && rateLimit.limit !== undefined) {
+        details.push(`${rateLimit.remaining}/${rateLimit.limit} requests remain in the current window`);
+    }
+    if (rateLimit?.resetAt) {
+        details.push(`the request limit resets at ${rateLimit.resetAt}`);
+    }
+    const suffix = details.length > 0 ? ` ${details.join("; ")}.` : "";
+    const ambiguity = isMutationOperation(query)
+        ? " This mutation may have been applied; verify its outcome before retrying."
+        : "";
+    return toLinearGraphQLError(error, `GraphQL request failed: Rate limit exceeded.${suffix}${ambiguity}`);
 }
 function buildLinearClient(auth) {
     const baseHeaders = { "public-file-urls-expire-in": "3600" };
@@ -29,10 +190,61 @@ function buildLinearClient(auth) {
     }
     return new LinearClient({ apiKey: auth.apiKey, headers: baseHeaders });
 }
+async function persistRateLimitObservation(admission, info) {
+    recordRateLimitInfo(info);
+    try {
+        await admission.observe(info);
+    }
+    catch (error) {
+        // The request already completed. Never turn an observation write
+        // failure into a replayable command failure (especially for mutations).
+        const message = error instanceof Error ? error.message : String(error);
+        logger.error(`[rate-limit] could not persist quota observation: ${message}`);
+    }
+}
+/**
+ * Put SDK-backed LinearService calls through the same quota admission and
+ * response-header observer as custom GraphQLService calls. The SDK's public
+ * `request()` discards response headers, so this narrow transport adapter uses
+ * its own public-ish rawRequest escape hatch and returns only `data` to the
+ * generated SDK models, preserving their existing contract.
+ */
+export function instrumentLinearClient(client, auth, options = {}) {
+    const transport = client
+        .client;
+    // Unit-test doubles and future SDK versions may not expose the escape hatch.
+    // Leave them untouched rather than manufacturing a partial transport.
+    if (!transport?.rawRequest || !transport.request)
+        return client;
+    const originalRawRequest = transport.rawRequest.bind(transport);
+    const admission = options.admission ?? createRateLimitAdmission(auth, { now: options.now });
+    const now = options.now ?? Date.now;
+    transport.request = async (document, variables, requestHeaders) => {
+        await admission.admit();
+        const query = typeof document === "string" ? document : print(document);
+        try {
+            const response = await originalRawRequest(query, variables, requestHeaders);
+            const rateLimit = extractRateLimitInfo(response, now);
+            if (rateLimit)
+                await persistRateLimitObservation(admission, rateLimit);
+            return response.data;
+        }
+        catch (error) {
+            const rateLimit = extractRateLimitInfo(error, now);
+            if (rateLimit)
+                await persistRateLimitObservation(admission, rateLimit);
+            throw error;
+        }
+    };
+    return client;
+}
 export class GraphQLService {
     graphQLClient;
     retryDelaysMs;
     sleep;
+    now;
+    admission;
+    renewAccessToken;
     constructor(auth, options = {}) {
         const client = buildLinearClient(auth);
         // LinearClient stores a private graphql-request client — access via escape hatch
@@ -42,18 +254,43 @@ export class GraphQLService {
         this.sleep =
             options.sleep ??
                 ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+        this.now = options.now ?? Date.now;
+        this.admission =
+            options.admission ?? createRateLimitAdmission(auth, { now: this.now });
+        this.renewAccessToken = options.renewAccessToken;
+    }
+    async observeRateLimit(info) {
+        await persistRateLimitObservation(this.admission, info);
     }
     // Default type allows property access on raw GraphQL responses.
     // Callers can narrow with explicit type parameter: rawRequest<{ issues: { nodes: T[] } }>(...)
     async rawRequest(query, variables, options = {}) {
         let attempt = 0;
+        let renewedAfterUnauthorized = false;
         try {
             while (true) {
                 try {
+                    await this.admission.admit();
                     const response = await this.graphQLClient.rawRequest(query, variables);
+                    const rateLimit = extractRateLimitInfo(response, this.now);
+                    if (rateLimit)
+                        await this.observeRateLimit(rateLimit);
                     return response.data;
                 }
                 catch (error) {
+                    if (error instanceof RateLimitAdmissionRefusal)
+                        throw error;
+                    const rateLimit = extractRateLimitInfo(error, this.now);
+                    if (rateLimit)
+                        await this.observeRateLimit(rateLimit);
+                    if (!renewedAfterUnauthorized &&
+                        this.renewAccessToken &&
+                        graphQLErrorHttpStatus(error) === 401) {
+                        const token = await this.renewAccessToken();
+                        this.graphQLClient.setHeader("authorization", `Bearer ${token}`);
+                        renewedAfterUnauthorized = true;
+                        continue;
+                    }
                     if (!options.retrySafeMutation ||
                         attempt >= this.retryDelaysMs.length ||
                         !isTransientGraphQLError(error)) {
@@ -65,19 +302,35 @@ export class GraphQLService {
             }
         }
         catch (error) {
-            const err = error;
-            if (err.response?.errors) {
-                const graphQLError = err.response.errors[0];
-                throw new Error(graphQLError.message || "GraphQL query failed");
+            if (error instanceof RateLimitAdmissionRefusal)
+                throw error;
+            if (isRateLimitGraphQLError(error)) {
+                throw rateLimitError(error, query, this.now);
             }
-            throw new Error(`GraphQL request failed: ${err.message}`);
+            const err = error;
+            // The message text is byte-identical to what the plain `Error`
+            // carried before DEV-7987; only the classification is new, so
+            // callers matching on the message are untouched.
+            const message = err.response?.errors
+                ? err.response.errors[0]?.message || "GraphQL query failed"
+                : `GraphQL request failed: ${err.message}`;
+            // This is the ONLY place a Linear GraphQL failure leaves the
+            // service, so it is the only place that has to attach the
+            // classification. Any future branch that throws its own shaped
+            // message from here must go through `toLinearGraphQLError` too, or
+            // that failure silently loses its `errorDetail` on the envelope.
+            throw toLinearGraphQLError(error, message);
         }
     }
 }
 export async function createGraphQLService(options) {
     const auth = await getActiveAuth(options);
     if (auth.kind === "oauth") {
-        return new GraphQLService({ oauthToken: auth.token });
+        const credential = { oauthToken: auth.token };
+        return new GraphQLService(credential, {
+            admission: createOAuthProfileRateLimitAdmission(credential, auth.oauth.clientId, auth.oauth.viewerId),
+            renewAccessToken: createClientCredentialsTokenRenewal(auth.oauth),
+        });
     }
     return new GraphQLService({ apiKey: auth.token });
 }

package/dist/utils/linear-graphql-error.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Structured classification for a failed Linear GraphQL request (DEV-7987).
+ *
+ * WHY THIS EXISTS. Every command routes its failures through `outputError`
+ * in `utils/output.ts`, which used to emit `{ error, activeProfile }` and
+ * nothing else. That flattens a rate limit, a gateway blip and a permanent
+ * schema error into one indistinguishable shape, so a machine caller
+ * shelling out to `el-linear` (a job runner deciding whether to retry, say)
+ * had to substring-match the message to guess. This module carries the two
+ * facts that were being thrown away — the HTTP status and the GraphQL
+ * `extensions.code` — plus the retryable verdict derived from them, so the
+ * envelope can state them.
+ *
+ * Kept in its own module, free of `@linear/sdk`, so `utils/output.ts` can
+ * read the classification without importing the GraphQL client.
+ */
+/**
+ * GraphQL `extensions.code` values Linear returns for conditions that clear
+ * on their own. A caller may retry these regardless of the HTTP status —
+ * Linear answers a rate limit with `RATELIMITED` under more than one
+ * status, so the code is load-bearing on its own.
+ */
+export declare const RETRYABLE_GRAPHQL_ERROR_CODES: readonly string[];
+/**
+ * The classification block `el-linear` publishes as `errorDetail` on a
+ * failed command's JSON envelope. Status, code and retryability are always
+ * present; `null` means no such response signal. A known admission deadline
+ * is additive and optional.
+ */
+export interface LinearGraphQLErrorDetail {
+    /** HTTP status of the Linear response, or `null` if it never arrived. */
+    httpStatus: number | null;
+    /** GraphQL `extensions.code` of the first error, or `null`. */
+    code: string | null;
+    /** Whether retrying the identical request could plausibly succeed. */
+    retryable: boolean;
+    /** Known quota reset or recovery-probe deadline, when admission refused locally. */
+    resetAt?: string;
+}
+/** HTTP status of a rejected request, or `null` if no response arrived. */
+export declare function graphQLErrorHttpStatus(error: unknown): number | null;
+/** First GraphQL error's `extensions.code`, or `null` when absent. */
+export declare function graphQLErrorCode(error: unknown): string | null;
+/** True when an HTTP status alone justifies a retry. */
+export declare function isRetryableHttpStatus(status: number | null): boolean;
+/** True when a GraphQL `extensions.code` alone justifies a retry. */
+export declare function isRetryableGraphQLCode(code: string | null): boolean;
+/**
+ * The retryable verdict from the authoritative response status and GraphQL code.
+ *
+ * "Retryable" here means *the failure is transient* — a caller that waits
+ * an appropriate interval could succeed. It is NOT the same question as
+ * `isTransientGraphQLError` in `graphql-service.ts`, which gates this CLI's
+ * own immediate 150 ms / 400 ms retry: a rate limit is transient (so
+ * `retryable: true`) but a terrible candidate for an immediate retry.
+ *
+ * The last arm is the one that is easy to get wrong: a rejection carrying
+ * NEITHER a status NOR a code never got an answer out of Linear at all —
+ * DNS, a refused connection, a dropped socket — and those are exactly the
+ * failures worth retrying. Every failure Linear itself produced arrives
+ * with a status (`LinearError.status` is set from the HTTP response), so
+ * this arm cannot swallow a permanent schema or permission error. Message
+ * text is deliberately excluded: a permanent response may legitimately
+ * mention a transient-looking number such as a validation limit of 500.
+ */
+export declare function classifyGraphQLFailure(httpStatus: number | null, code: string | null): boolean;
+/**
+ * A Linear GraphQL failure that carries its own classification.
+ *
+ * The `message` is unchanged from what the plain `Error` used to carry, so
+ * every existing consumer that matches on the message text keeps working;
+ * the classification is purely additive.
+ */
+export declare class LinearGraphQLError extends Error {
+    readonly httpStatus: number | null;
+    readonly code: string | null;
+    readonly retryable: boolean;
+    readonly resetAt?: string;
+    constructor(message: string, detail: LinearGraphQLErrorDetail);
+    get detail(): LinearGraphQLErrorDetail;
+}
+/**
+ * Wrap a rejection from the Linear GraphQL client in a classified error,
+ * keeping `message` exactly as the caller composed it.
+ *
+ * This is the seam every throw out of `GraphQLService.rawRequest` must pass
+ * through. A branch that builds its own message and throws a bare `Error`
+ * instead — a rate-limit path with a friendlier wording, say — produces a
+ * failure with NO `errorDetail` on the envelope, which is precisely the
+ * blindness DEV-7987 exists to remove, and it fails silently.
+ */
+export declare function toLinearGraphQLError(error: unknown, message: string): LinearGraphQLError;
+/**
+ * Read the classification off an arbitrary thrown value, or `null` when it
+ * carries none. Structural rather than `instanceof` so a
+ * `LinearGraphQLError` that crossed a module-instance boundary (a vitest
+ * mock, a duplicated dependency copy) is still recognized — the envelope
+ * contract must not depend on prototype identity.
+ */
+export declare function readGraphQLErrorDetail(error: unknown): LinearGraphQLErrorDetail | null;