@enrichlayer/el-linear 1.44.1 → 1.45.1

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;

package/dist/utils/linear-graphql-error.js

@@ -0,0 +1,182 @@
+/**
+ * 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 const RETRYABLE_GRAPHQL_ERROR_CODES = [
+    "RATELIMITED",
+    "INTERNAL_SERVER_ERROR",
+    "SERVICE_UNAVAILABLE",
+];
+/** HTTP statuses that mean "the request was fine, the moment wasn't". */
+const RETRYABLE_HTTP_STATUSES = [408, 429];
+/** Accept explicit UTC timestamps only; error messages never establish a deadline. */
+function normalizeResetAt(value) {
+    if (typeof value !== "string" ||
+        !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/.test(value)) {
+        return undefined;
+    }
+    const millis = Date.parse(value);
+    if (!Number.isFinite(millis))
+        return undefined;
+    const normalized = new Date(millis).toISOString();
+    // Date.parse normalizes impossible calendar dates rather than rejecting them.
+    return normalized.slice(0, 19) === value.slice(0, 19)
+        ? normalized
+        : undefined;
+}
+function asNumber(value) {
+    return typeof value === "number" ? value : null;
+}
+function asString(value) {
+    return typeof value === "string" ? value : null;
+}
+/** HTTP status of a rejected request, or `null` if no response arrived. */
+export function graphQLErrorHttpStatus(error) {
+    if (typeof error !== "object" || error === null) {
+        return null;
+    }
+    const rejection = error;
+    return (asNumber(rejection.status) ??
+        asNumber(rejection.response?.status) ??
+        asNumber(rejection.response?.statusCode) ??
+        asNumber(rejection.raw?.response?.status));
+}
+/** First GraphQL error's `extensions.code`, or `null` when absent. */
+export function graphQLErrorCode(error) {
+    if (typeof error !== "object" || error === null) {
+        return null;
+    }
+    const rejection = error;
+    return (asString(rejection.response?.errors?.[0]?.extensions?.code) ??
+        asString(rejection.raw?.response?.errors?.[0]?.extensions?.code));
+}
+/** True when an HTTP status alone justifies a retry. */
+export function isRetryableHttpStatus(status) {
+    if (status === null) {
+        return false;
+    }
+    return RETRYABLE_HTTP_STATUSES.includes(status) || status >= 500;
+}
+/** True when a GraphQL `extensions.code` alone justifies a retry. */
+export function isRetryableGraphQLCode(code) {
+    return code !== null && RETRYABLE_GRAPHQL_ERROR_CODES.includes(code);
+}
+/**
+ * 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 function classifyGraphQLFailure(httpStatus, code) {
+    if (isRetryableHttpStatus(httpStatus) || isRetryableGraphQLCode(code)) {
+        return true;
+    }
+    if (httpStatus === null && code === null) {
+        return true;
+    }
+    // A response status or GraphQL code is authoritative. Message text may
+    // contain an unrelated number such as a validation limit of 500; it must
+    // never turn a known permanent 400/401/403 into a retryable transport fault.
+    return false;
+}
+/**
+ * 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 class LinearGraphQLError extends Error {
+    httpStatus;
+    code;
+    retryable;
+    resetAt;
+    constructor(message, detail) {
+        super(message);
+        this.name = "LinearGraphQLError";
+        this.httpStatus = detail.httpStatus;
+        this.code = detail.code;
+        this.retryable = detail.retryable;
+        this.resetAt = normalizeResetAt(detail.resetAt);
+    }
+    get detail() {
+        return {
+            httpStatus: this.httpStatus,
+            code: this.code,
+            retryable: this.retryable,
+            ...(this.resetAt ? { resetAt: this.resetAt } : {}),
+        };
+    }
+}
+/**
+ * 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 function toLinearGraphQLError(error, message) {
+    const httpStatus = graphQLErrorHttpStatus(error);
+    const code = graphQLErrorCode(error);
+    return new LinearGraphQLError(message, {
+        httpStatus,
+        code,
+        retryable: classifyGraphQLFailure(httpStatus, code),
+    });
+}
+/**
+ * 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 function readGraphQLErrorDetail(error) {
+    if (typeof error !== "object" || error === null) {
+        return null;
+    }
+    const candidate = error;
+    if (typeof candidate.retryable !== "boolean") {
+        return null;
+    }
+    const resetAt = normalizeResetAt(candidate.resetAt);
+    return {
+        httpStatus: asNumber(candidate.httpStatus),
+        code: asString(candidate.code),
+        retryable: candidate.retryable,
+        ...(resetAt ? { resetAt } : {}),
+    };
+}

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

@@ -1,6 +1,9 @@
+import { LinearClient } from "@linear/sdk";
 import type { LinearCredential } from "../auth/linear-credential.js";
 import type { LinearComment, LinearCycleDetail, LinearCycleSummary, LinearLabel, LinearProject, LinearTeam, LinearUser } from "../types/linear.js";
 import type { AuthOptions } from "./auth.js";
+import { GraphQLService } from "./graphql-service.js";
+import { type RateLimitAdmission } from "./rate-limit-admission.js";
 /**
  * Constructor arg for `LinearService`. Re-exported alias of the shared
  * `LinearCredential` union (`{ apiKey } | { oauthToken }`). See
@@ -8,9 +11,24 @@ import type { AuthOptions } from "./auth.js";
  * legacy arm was dropped in DEV-4068 T7.
  */
 export type LinearServiceAuth = LinearCredential;
+/**
+ * Classify every generated SDK operation after the SDK has normalized its raw
+ * transport rejection. Patching `client.client.request` is too early: the
+ * LinearClient constructor wraps that transport with `parseLinearError`, which
+ * would immediately strip our additive classification fields again. Keeping
+ * the wrapper here (rather than guessing in `outputError`) also leaves local
+ * validation and not-found errors unclassified.
+ */
+export declare function instrumentLinearGraphQLErrorClassification(client: LinearClient): LinearClient;
+export declare function instrumentClientCredentialsRenewal(client: LinearClient, renewAccessToken?: () => Promise<string>): LinearClient;
 export declare class LinearService {
     private readonly client;
-    constructor(auth: LinearServiceAuth);
+    private readonly graphQLService;
+    constructor(auth: LinearServiceAuth, options?: {
+        admission?: RateLimitAdmission;
+        graphQLService?: GraphQLService;
+        renewAccessToken?: () => Promise<string>;
+    });
     resolveIssueId(issueId: string): Promise<string>;
     getTeams(limit?: number): Promise<LinearTeam[]>;
     resolveUserId(nameOrEmailOrId: string): Promise<string>;
@@ -32,7 +50,6 @@ export declare class LinearService {
     }): Promise<LinearProject[]>;
     resolveTeamId(teamKeyOrNameOrId: string): Promise<string>;
     resolveStatusId(statusName: string, teamId?: string): Promise<string>;
-    private buildLabelData;
     getLabels(teamFilter?: string, limit?: number, nameFilter?: string): Promise<{
         labels: LinearLabel[];
     }>;