@typeship-ax/cli 0.6.0

package/src/core/http.ts

@@ -0,0 +1,1008 @@
+/**
+ * Runtime core. Generated by typeship — https://typeship.dev
+ * Zero dependencies: built on the platform fetch API (Node 18+, browsers, edge).
+ */
+
+export interface RequestOptions {
+  /** Abort the request (composed with the per-attempt timeout). */
+  signal?: AbortSignal;
+  /** Extra headers for this call. */
+  headers?: Record<string, string | undefined>;
+  /** Per-attempt timeout in milliseconds. Overrides the client default. */
+  timeoutMs?: number;
+  /** Retry attempts after the first try. Overrides the client default. */
+  maxRetries?: number;
+}
+
+export interface ResponseMeta {
+  status: number;
+  headers: Headers;
+  /** x-request-id / request-id header when the server sends one. */
+  requestId?: string;
+}
+
+/**
+ * A static credential or a callback resolved before every attempt. Use a
+ * callback for tokens that expire (OAuth access tokens, STS, Vault).
+ */
+export type AuthValue = string | (() => string | Promise<string>);
+
+/** Passed to onRequest/onResponse hooks. Mutations to headers and url in
+ * onRequest apply to the outgoing request. */
+export interface RequestContext {
+  method: string;
+  url: string;
+  headers: Record<string, string>;
+  /** 0 on the first try, increments per retry. */
+  attempt: number;
+}
+
+/** One server-sent event from a text/event-stream response. */
+export interface SseEvent {
+  /** The `event:` field; undefined for unnamed events. */
+  event?: string;
+  /** The `id:` field, when the server sends one. */
+  id?: string;
+  /** Concatenated `data:` lines. Parse as JSON if your API sends JSON. */
+  data: string;
+}
+
+/**
+ * Every SDK call returns a discriminated result instead of throwing.
+ * Narrow on `ok` and the error side is a typed union of the documented
+ * error responses for that exact operation.
+ */
+export type ApiResult<T, E> =
+  | { ok: true; data: T; response: ResponseMeta }
+  | { ok: false; error: E; response?: ResponseMeta };
+
+/** Collapse a result into its data, throwing the typed error when !ok. */
+export function unwrap<T, E>(result: ApiResult<T, E>): T {
+  if (result.ok) return result.data;
+  if (result.error instanceof Error) throw result.error;
+  throw new Error(String(result.error));
+}
+
+/** Base class for every HTTP error response. */
+export class ApiError<S extends number = number, B = unknown> extends Error {
+  readonly status: S;
+  readonly body: B;
+  readonly response: ResponseMeta;
+
+  constructor(message: string, status: S, body: B, response: ResponseMeta) {
+    super(message);
+    this.name = new.target.name;
+    this.status = status;
+    this.body = body;
+    this.response = response;
+  }
+}
+
+/** A response status the spec didn't document. */
+export class UnexpectedApiError extends ApiError<number, unknown> {
+  constructor(status: number, body: unknown, response: ResponseMeta) {
+    super("Unexpected HTTP status " + status, status, body, response);
+  }
+}
+
+/** A 200 response whose GraphQL payload carried errors. */
+export class GraphQLRequestError extends Error {
+  /** The raw errors array from the GraphQL response. */
+  readonly errors: { message?: string; path?: unknown[]; extensions?: unknown }[];
+  readonly response: ResponseMeta;
+
+  constructor(errors: unknown[], response: ResponseMeta) {
+    const first = (errors[0] as { message?: string } | undefined)?.message;
+    super(first ?? "GraphQL request returned errors");
+    this.name = "GraphQLRequestError";
+    this.errors = errors as GraphQLRequestError["errors"];
+    this.response = response;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// GraphQL selections — typed field picking over the schema's result types
+// ---------------------------------------------------------------------------
+
+type Primitive = string | number | boolean | bigint | symbol | null | undefined;
+type Unwrap<T> = NonNullable<T> extends readonly (infer U)[] ? Unwrap<U> : NonNullable<T>;
+type IsUnion<T, U = T> = T extends unknown ? ([U] extends [T] ? false : true) : never;
+type TypeNameOf<T> = T extends { __typename?: infer N } ? Extract<N, string> : never;
+type Prettify<T> = { [K in keyof T]: T[K] } & {};
+
+/**
+ * A selection over a GraphQL result type `T`: `true` picks a leaf field, a
+ * nested object picks inside an object field, and `on` picks per concrete
+ * type when `T` is a union or interface (`{ on: { Transaction: { amount: true } } }`).
+ * Keys are checked against the schema, so a typo is a compile error.
+ */
+export type Selection<T> = Unwrap<T> extends Primitive ? never : SelectionObject<Unwrap<T>>;
+
+type FieldSelection<V> = Unwrap<V> extends Primitive ? true : SelectionObject<Unwrap<V>>;
+
+type SelectionObject<T> = {
+  [K in Extract<keyof T, string> as K extends "__typename" ? never : K]?: FieldSelection<T[K]>;
+} & { __typename?: true } & (IsUnion<T> extends true
+  ? { on?: { [N in TypeNameOf<T>]?: SelectionObject<Extract<T, { __typename?: N }>> } }
+  : { on?: never });
+
+/** The result type a {@link Selection} `S` produces from result type `T`:
+ * exactly the fields picked, nullability and lists preserved, union members
+ * narrowed by `__typename`. */
+export type Selected<T, S> = T extends readonly (infer U)[]
+  ? Selected<U, S>[]
+  : T extends Primitive
+    ? T
+    : S extends object
+      ? Prettify<SelectedMember<T, S>>
+      : never;
+
+type SelectedMember<T, S> = (S extends { on?: infer O }
+  ? O extends object
+    ? TypeNameOf<T> extends keyof O
+      ? PickSelected<T, NonNullable<O[TypeNameOf<T>]>>
+      : {}
+    : {}
+  : {}) &
+  PickSelected<T, S>;
+
+type PickSelected<T, S> = {
+  -readonly [K in keyof S as K extends "on" ? never : K extends keyof T ? (S[K] extends true | object ? K : never) : never]-?: K extends "__typename"
+    ? NonNullable<T[K & keyof T]>
+    : S[K] extends true
+      ? Exclude<T[K & keyof T], undefined>
+      : Selected<Exclude<T[K & keyof T], undefined>, S[K]>;
+};
+
+/** A selection object or a raw selection set (`"{ id name }"`). */
+export type SelectionInput = string | Record<string, unknown>;
+
+/** Serialize a selection object to a GraphQL selection set. Strings pass
+ * through untouched. */
+export function selectionToString(selection: SelectionInput): string {
+  if (typeof selection === "string") return selection;
+  const parts: string[] = [];
+  for (const [key, value] of Object.entries(selection)) {
+    if (!value) continue;
+    if (key === "on" && typeof value === "object") {
+      for (const [typeName, sub] of Object.entries(value as Record<string, unknown>)) {
+        if (sub && typeof sub === "object") parts.push("... on " + typeName + " " + selectionToString(sub as Record<string, unknown>));
+      }
+    } else if (value === true) {
+      parts.push(key);
+    } else if (typeof value === "object") {
+      parts.push(key + " " + selectionToString(value as Record<string, unknown>));
+    }
+  }
+  return "{ " + (parts.length > 0 ? parts.join(" ") : "__typename") + " }";
+}
+
+// ---------------------------------------------------------------------------
+// Optional runtime validation — zero-dependency, schema table in schemas.ts
+// ---------------------------------------------------------------------------
+
+export interface Violation { path: string; message: string }
+
+/** Request or response data did not match the spec's schema (opt-in via the
+ * client's validate option). Never thrown: returned as the error side of
+ * ApiResult, like every other failure. */
+export class ValidationError extends Error {
+  readonly direction: "request" | "response";
+  readonly violations: Violation[];
+  constructor(direction: "request" | "response", violations: Violation[]) {
+    const shown = violations.slice(0, 3).map((v) => v.path + " " + v.message).join("; ");
+    super(direction + " body failed schema validation: " + shown
+      + (violations.length > 3 ? " (+" + (violations.length - 3) + " more)" : ""));
+    this.name = "ValidationError";
+    this.direction = direction;
+    this.violations = violations;
+  }
+}
+
+function jsonType(value: unknown): string {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}
+
+function typeMatches(value: unknown, t: string): boolean {
+  if (t === "integer") return typeof value === "number" && Number.isInteger(value);
+  return jsonType(value) === t;
+}
+
+const MAX_VIOLATIONS = 50;
+
+/**
+ * Validates against the depth-capped JSON Schema subset emitted in
+ * schemas.ts. Constraints outside the subset (formats, multipleOf, not, ...)
+ * are ignored: validation can miss drift but never false-alarms.
+ */
+export function validateAgainstSchema(value: unknown, schema: unknown, path: string, out: Violation[], defs?: Record<string, unknown>): void {
+  if (out.length >= MAX_VIOLATIONS) return;
+  if (!schema || typeof schema !== "object" || Array.isArray(schema)) return;
+  const s = schema as Record<string, any>;
+
+  // Named components are deduplicated into the DEFS table (see schemas.ts);
+  // recursion is bounded by the data's own depth, so cycles terminate.
+  if (typeof s.$ref === "string") {
+    validateAgainstSchema(value, defs?.[s.$ref], path, out, defs);
+    return;
+  }
+
+  if (Array.isArray(s.allOf)) for (const sub of s.allOf) validateAgainstSchema(value, sub, path, out, defs);
+  const variants = s.anyOf ?? s.oneOf;
+  if (Array.isArray(variants) && variants.length > 0) {
+    const matched = variants.some((sub: unknown) => {
+      const scratch: Violation[] = [];
+      validateAgainstSchema(value, sub, path, scratch, defs);
+      return scratch.length === 0;
+    });
+    if (!matched) out.push({ path, message: "matches none of the allowed variants" });
+  }
+
+  if (s.type !== undefined) {
+    const allowed: string[] = Array.isArray(s.type) ? s.type : [s.type];
+    if (s.nullable === true && !allowed.includes("null")) allowed.push("null");
+    if (!allowed.some((t) => typeMatches(value, t))) {
+      out.push({ path, message: "expected " + allowed.join(" | ") + ", got " + jsonType(value) });
+      return; // remaining constraints assume the right type
+    }
+  }
+  if (value === null) return;
+
+  if (Array.isArray(s.enum) && !s.enum.some((e: unknown) => JSON.stringify(e) === JSON.stringify(value))) {
+    out.push({ path, message: "not one of the allowed enum values" });
+  }
+  if (s.const !== undefined && JSON.stringify(s.const) !== JSON.stringify(value)) {
+    out.push({ path, message: "does not equal the required constant" });
+  }
+  if (typeof value === "number") {
+    if (typeof s.minimum === "number" && value < s.minimum) out.push({ path, message: "below minimum " + s.minimum });
+    if (typeof s.maximum === "number" && value > s.maximum) out.push({ path, message: "above maximum " + s.maximum });
+  }
+  if (typeof value === "string") {
+    if (typeof s.minLength === "number" && value.length < s.minLength) out.push({ path, message: "shorter than minLength " + s.minLength });
+    if (typeof s.maxLength === "number" && value.length > s.maxLength) out.push({ path, message: "longer than maxLength " + s.maxLength });
+    if (typeof s.pattern === "string") {
+      try {
+        if (!new RegExp(s.pattern).test(value)) out.push({ path, message: "does not match pattern" });
+      } catch { /* invalid pattern in the spec: skip, never false-alarm */ }
+    }
+  }
+  if (Array.isArray(value)) {
+    if (typeof s.minItems === "number" && value.length < s.minItems) out.push({ path, message: "fewer than minItems " + s.minItems });
+    if (typeof s.maxItems === "number" && value.length > s.maxItems) out.push({ path, message: "more than maxItems " + s.maxItems });
+    if (s.items) {
+      for (let i = 0; i < value.length && out.length < MAX_VIOLATIONS; i++) {
+        validateAgainstSchema(value[i], s.items, path + "[" + i + "]", out, defs);
+      }
+    }
+  }
+  if (jsonType(value) === "object") {
+    const obj = value as Record<string, unknown>;
+    if (Array.isArray(s.required)) {
+      for (const key of s.required) {
+        if (obj[key as string] === undefined) out.push({ path, message: "missing required property " + JSON.stringify(key) });
+      }
+    }
+    if (s.properties && typeof s.properties === "object") {
+      for (const [key, sub] of Object.entries(s.properties)) {
+        if (obj[key] !== undefined) validateAgainstSchema(obj[key], sub, path + "." + key, out, defs);
+      }
+      if (s.additionalProperties === false) {
+        for (const key of Object.keys(obj)) {
+          if (!(key in (s.properties as object))) out.push({ path, message: "unexpected property " + JSON.stringify(key) });
+        }
+      }
+    }
+  }
+}
+
+/**
+ * "fetch failed" alone is useless in a bug report; surface the request line
+ * and the deepest cause message (getaddrinfo ENOTFOUND, ECONNREFUSED, ...)
+ * the platform buried in the error chain.
+ */
+function transportFailureMessage(method: string, url: string, cause: unknown): string {
+  let detail = cause instanceof Error ? cause.message : String(cause ?? "request failed");
+  let node: unknown = cause;
+  for (let depth = 0; depth < 5 && node instanceof Error; depth++) {
+    node = Array.isArray((node as Error & { errors?: unknown[] }).errors)
+      ? (node as Error & { errors?: unknown[] }).errors![0]
+      : (node as Error & { cause?: unknown }).cause;
+    if (node instanceof Error && node.message && !detail.includes(node.message)) {
+      detail += ": " + node.message;
+    }
+  }
+  return method + " " + url + " failed: " + detail;
+}
+
+/** The request never produced an HTTP response (network failure, timeout, abort). */
+export class TransportError extends Error {
+  override readonly cause?: unknown;
+
+  constructor(message: string, cause?: unknown) {
+    super(message);
+    this.name = "TransportError";
+    this.cause = cause;
+  }
+}
+
+type ErrorCtor = new (body: any, response: ResponseMeta) => ApiError<number, unknown>;
+
+export interface CoreRequest {
+  method: string;
+  path: string;
+  query?: Record<string, unknown>;
+  headers?: Record<string, string | undefined>;
+  body?: unknown;
+  bodyKind?: "json" | "form" | "multipart" | "text" | "binary";
+  /** Status matcher -> generated error class ("404", "4XX", "default"). */
+  errors?: Record<string, ErrorCtor>;
+  /** Idempotent requests are retried automatically. */
+  idempotent?: boolean;
+  /** Success body is text/event-stream: yield SseEvents instead of parsing. */
+  stream?: boolean;
+  /** Header name auto-filled with one UUID per call (stable across retries)
+   * when the caller doesn't supply a value. */
+  idempotencyKey?: string;
+  /** GraphQL: unwrap body.data[field] and turn body.errors into a
+   * GraphQLRequestError. */
+  graphqlField?: string;
+  /** Key into the schemas table for optional runtime validation. */
+  schemaKey?: string;
+  /** Operation-level retry policy (x-typeship-retries), merged over the
+   * client-level policy; per-call options.maxRetries still wins. */
+  retry?: RetryPolicy;
+  options?: RequestOptions;
+}
+
+/** Tunable retry behavior (x-typeship-retries; defaults preserved when unset). */
+export interface RetryPolicy {
+  maxRetries?: number;
+  /** Replaces the default retryable set (408, 429, 500, 502, 503, 504). */
+  statuses?: number[];
+  initialDelayMs?: number;
+  maxDelayMs?: number;
+  /** Also retry non-idempotent methods (POST/PATCH). */
+  retryNonIdempotent?: boolean;
+}
+
+export interface CoreConfig {
+  baseUrl: string;
+  headers: Record<string, AuthValue>;
+  /** Auth carried as query parameters (apiKey-in-query schemes). */
+  query: Record<string, AuthValue>;
+  fetch: typeof fetch;
+  timeoutMs: number;
+  maxRetries: number;
+  /** Called before every attempt; mutate context.headers / context.url. */
+  onRequest?: (context: RequestContext) => void | Promise<void>;
+  /** Called after every HTTP response, before parsing and retry decisions.
+   * Clone the response before reading its body. */
+  onResponse?: (response: Response, context: RequestContext) => void | Promise<void>;
+  /** Called once per failed call — after retries are exhausted, with the
+   * typed error about to be returned. Observability only; the error is
+   * returned unchanged. */
+  onError?: (error: unknown, request: { method: string; path: string }) => void | Promise<void>;
+  /** One structured event per attempt. Never includes headers or bodies,
+   * so nothing secret can reach logs through it. */
+  debug?: (event: DebugEvent) => void;
+  /** Opt-in runtime validation of JSON request/response bodies against the
+   * spec's schemas. Zero-dependency: the validator lives in this file and
+   * the schema table in schemas.ts. */
+  validate?: { requests: boolean; responses: boolean; mode: "throw" | "warn" };
+  /** Per-operation schema table, keyed "resource.method" (see schemas.ts). */
+  schemas?: Record<string, { req?: unknown; res?: unknown }>;
+  /** Shared component definitions the schema table references. */
+  schemaDefs?: Record<string, unknown>;
+  /** Root-level retry policy (x-typeship-retries at the document root). */
+  retry?: RetryPolicy;
+  /** Client-level values for x-typeship-globals parameters, by wire name. */
+  globals?: Record<string, unknown>;
+  /** Header names the spec's API-key schemes use. fetch drops the standard
+   * credential headers on a cross-origin redirect but knows nothing of these,
+   * so when a spec declares any, this runtime follows redirects itself and
+   * drops them too. */
+  authHeaders?: string[];
+}
+
+/** What the debug sink receives: one event per HTTP attempt. */
+export interface DebugEvent {
+  method: string;
+  path: string;
+  /** absent when the attempt failed before a response arrived */
+  status?: number;
+  durationMs: number;
+  /** 1-based; >1 means this was a retry */
+  attempt: number;
+  requestId?: string;
+  /** transport failure message, when there was no response */
+  error?: string;
+}
+
+const RETRYABLE_STATUSES = new Set([408, 429, 500, 502, 503, 504]);
+
+/** Credential-bearing headers fetch itself drops when a redirect crosses to
+ * another origin. A spec's own API-key headers join them below. */
+const SENSITIVE_HEADERS = ["authorization", "cookie", "cookie2", "proxy-authorization", "www-authenticate"];
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+/** Dropped along with the body when a redirect rewrites the method to GET. */
+const CONTENT_HEADERS = ["content-encoding", "content-language", "content-location", "content-type", "content-length"];
+/** fetch's own ceiling, so a redirect loop fails the same way it did before. */
+const MAX_REDIRECTS = 20;
+
+function withoutHeaders(headers: Record<string, string>, drop: string[]): Record<string, string> {
+  const kept: Record<string, string> = {};
+  for (const [name, value] of Object.entries(headers)) {
+    if (!drop.includes(name.toLowerCase())) kept[name] = value;
+  }
+  return kept;
+}
+
+/** A body that can only be read once, so a redirect cannot replay it. */
+function isStreamBody(body: unknown): boolean {
+  return typeof (body as { getReader?: unknown } | undefined)?.getReader === "function";
+}
+
+export class HttpCore {
+  readonly config: CoreConfig;
+  /** Lowercased header names dropped on a cross-origin hop. */
+  private readonly sensitiveHeaders: string[];
+  /** Whether this runtime follows redirects itself instead of letting the
+   * platform do it — see followRedirects(). */
+  private readonly manualRedirects: boolean;
+
+  // no parameter properties: this file also runs under strip-only TS
+  constructor(config: CoreConfig) {
+    this.config = config;
+    const declared = (config.authHeaders ?? []).map((name) => name.toLowerCase());
+    const custom = declared.filter((name, i) => !SENSITIVE_HEADERS.includes(name) && declared.indexOf(name) === i);
+    this.sensitiveHeaders = [...SENSITIVE_HEADERS, ...custom];
+    // Only worth taking over from the platform when the spec puts its
+    // credential on a header fetch has never heard of. A browser is excluded:
+    // there, `redirect: "manual"` yields an opaque response with no Location
+    // to read, and a cross-origin hop carrying a non-safelisted header needs
+    // the target's CORS consent anyway.
+    this.manualRedirects = custom.length > 0 && (globalThis as { document?: unknown }).document === undefined;
+  }
+
+  /** The client-level value for an x-typeship-globals parameter. */
+  globalValue(name: string): unknown {
+    return this.config.globals?.[name];
+  }
+
+  async request<T, E>(req: CoreRequest): Promise<ApiResult<T, E>> {
+    const policy: RetryPolicy = { ...this.config.retry, ...req.retry };
+    const maxRetries = req.options?.maxRetries ?? policy.maxRetries ?? this.config.maxRetries;
+    const timeoutMs = req.options?.timeoutMs ?? this.config.timeoutMs;
+    const retryAllowed = req.idempotent === true || req.method === "GET" || policy.retryNonIdempotent === true;
+    const retryableStatuses = policy.statuses ? new Set(policy.statuses) : RETRYABLE_STATUSES;
+
+    // One key per logical call, reused on every retry — that's the point
+    // of idempotency keys.
+    const autoIdempotencyKey =
+      req.idempotencyKey !== undefined &&
+      req.headers?.[req.idempotencyKey] === undefined &&
+      req.options?.headers?.[req.idempotencyKey] === undefined
+        ? crypto.randomUUID()
+        : undefined;
+
+    const opSchemas = this.config.validate && req.schemaKey ? this.config.schemas?.[req.schemaKey] : undefined;
+    if (opSchemas?.req && this.config.validate!.requests
+        && req.body !== undefined && (req.bodyKind ?? "json") === "json") {
+      const violations: Violation[] = [];
+      validateAgainstSchema(req.body, opSchemas.req, "body", violations, this.config.schemaDefs);
+      if (violations.length > 0) {
+        const validationError = new ValidationError("request", violations);
+        if (this.config.validate!.mode === "warn") {
+          console.warn(req.method + " " + req.path + ": " + validationError.message);
+        } else {
+          const error = validationError as unknown as E;
+          await this.config.onError?.(error, { method: req.method, path: req.path });
+          return { ok: false, error };
+        }
+      }
+    }
+
+    let lastError: unknown;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      let response: Response;
+      const attemptStarted = Date.now();
+      try {
+        response = await this.send(req, timeoutMs, attempt, autoIdempotencyKey);
+        this.config.debug?.({
+          method: req.method,
+          path: req.path,
+          status: response.status,
+          durationMs: Date.now() - attemptStarted,
+          attempt: attempt + 1,
+          requestId: response.headers.get("x-request-id") ?? response.headers.get("request-id") ?? undefined,
+        });
+      } catch (cause) {
+        lastError = cause;
+        this.config.debug?.({
+          method: req.method,
+          path: req.path,
+          durationMs: Date.now() - attemptStarted,
+          attempt: attempt + 1,
+          error: cause instanceof Error ? cause.message : String(cause),
+        });
+        if (attempt < maxRetries && retryAllowed && !req.options?.signal?.aborted) {
+          await sleep(backoff(attempt, policy));
+          continue;
+        }
+        const error = new TransportError(
+          transportFailureMessage(req.method, this.config.baseUrl.replace(/\/+$/, "") + req.path, cause),
+          cause,
+        ) as unknown as E;
+        await this.config.onError?.(error, { method: req.method, path: req.path });
+        return { ok: false, error };
+      }
+
+      if (response.ok) {
+        if (req.stream) {
+          return { ok: true, data: sseEvents(response) as T, response: meta(response) };
+        }
+        let data: T;
+        try {
+          data = (await parseBody(response, req.method)) as T;
+        } catch (cause) {
+          const error = new TransportError(
+            "The response body read was aborted before completing",
+            cause,
+          ) as unknown as E;
+          await this.config.onError?.(error, { method: req.method, path: req.path });
+          return { ok: false, error, response: meta(response) };
+        }
+        if (opSchemas?.res && this.config.validate!.responses && data !== undefined) {
+          const violations: Violation[] = [];
+          validateAgainstSchema(data, opSchemas.res, "response", violations, this.config.schemaDefs);
+          if (violations.length > 0) {
+            const validationError = new ValidationError("response", violations);
+            if (this.config.validate!.mode === "warn") {
+              console.warn(req.method + " " + req.path + ": " + validationError.message);
+            } else {
+              const error = validationError as unknown as E;
+              await this.config.onError?.(error, { method: req.method, path: req.path });
+              return { ok: false, error, response: meta(response) };
+            }
+          }
+        }
+        if (req.graphqlField) {
+          const payload = data as { data?: Record<string, unknown>; errors?: unknown[] } | undefined;
+          const responseMeta = meta(response);
+          if (Array.isArray(payload?.errors) && payload.errors.length > 0) {
+            const gqlError = new GraphQLRequestError(payload.errors, responseMeta) as unknown as E;
+            await this.config.onError?.(gqlError, { method: req.method, path: req.path });
+            return { ok: false, error: gqlError, response: responseMeta };
+          }
+          return { ok: true, data: payload?.data?.[req.graphqlField] as T, response: responseMeta };
+        }
+        return { ok: true, data, response: meta(response) };
+      }
+
+      // 429 is safe to retry regardless of idempotency; other retryable
+      // statuses only when the verb is idempotent.
+      const retryableStatus =
+        retryableStatuses.has(response.status) &&
+        (retryAllowed || response.status === 429);
+      if (attempt < maxRetries && retryableStatus) {
+        await sleep(retryAfterMs(response) ?? backoff(attempt, policy));
+        continue;
+      }
+
+      let body: unknown;
+      try {
+        body = await parseBody(response, req.method);
+      } catch {
+        body = undefined; // error responses keep their status even if the body read aborts
+      }
+      const responseMeta = meta(response);
+      const Ctor =
+        req.errors?.[String(response.status)] ??
+        req.errors?.[String(Math.floor(response.status / 100)) + "XX"] ??
+        req.errors?.["default"];
+      const error = (Ctor
+        ? new Ctor(body, responseMeta)
+        : new UnexpectedApiError(response.status, body, responseMeta)) as unknown as E;
+      await this.config.onError?.(error, { method: req.method, path: req.path });
+      return { ok: false, error, response: responseMeta };
+    }
+
+    // Unreachable, but keeps the compiler honest.
+    const error = new TransportError("Request failed", lastError) as unknown as E;
+    await this.config.onError?.(error, { method: req.method, path: req.path });
+    return { ok: false, error };
+  }
+
+  private async send(
+    req: CoreRequest,
+    timeoutMs: number,
+    attempt: number,
+    autoIdempotencyKey?: string,
+  ): Promise<Response> {
+    const headers: Record<string, string> = {};
+    for (const [k, v] of Object.entries(this.config.headers)) {
+      headers[k] = await resolveAuthValue(v);
+    }
+    if (req.idempotencyKey && autoIdempotencyKey) {
+      headers[req.idempotencyKey] = autoIdempotencyKey;
+    }
+    const { body, contentType } = serializeBody(req);
+    if (contentType) headers["Content-Type"] = contentType;
+    for (const source of [req.headers, req.options?.headers]) {
+      for (const [k, v] of Object.entries(source ?? {})) {
+        if (v !== undefined) headers[k] = v;
+      }
+    }
+
+    const context: RequestContext = {
+      method: req.method,
+      url: await this.buildUrl(req),
+      headers,
+      attempt,
+    };
+    await this.config.onRequest?.(context);
+
+    // Streaming responses are exempt from the attempt timeout once headers
+    // arrive (an event stream may stay open far longer than timeoutMs);
+    // everything else keeps the timeout armed through the body read, so a
+    // stalled body aborts instead of hanging.
+    const signals: AbortSignal[] = [];
+    let clearStreamTimeout: (() => void) | undefined;
+    if (req.stream) {
+      const headersTimeout = new AbortController();
+      const timer = setTimeout(
+        () => headersTimeout.abort(new DOMException("Timed out waiting for response headers", "TimeoutError")),
+        timeoutMs,
+      );
+      (timer as { unref?: () => void }).unref?.();
+      clearStreamTimeout = () => clearTimeout(timer);
+      signals.push(headersTimeout.signal);
+    } else {
+      signals.push(AbortSignal.timeout(timeoutMs));
+    }
+    if (req.options?.signal) signals.push(req.options.signal);
+
+    try {
+      const signal = AbortSignal.any(signals);
+      const response = this.manualRedirects
+        ? await this.followRedirects(context, body, signal)
+        : await this.config.fetch(context.url, {
+            method: req.method,
+            headers: context.headers,
+            body,
+            signal,
+          });
+      await this.config.onResponse?.(response, context);
+      return response;
+    } finally {
+      clearStreamTimeout?.();
+    }
+  }
+
+  /**
+   * The redirect chain, walked here instead of inside fetch, so the header
+   * this spec puts its API key on is dropped when a hop crosses to another
+   * origin. fetch drops Authorization and friends for us, but it has never
+   * heard of X-Whatever-Key, and an operation that returns a file commonly
+   * redirects to object storage.
+   *
+   * Only reached when the spec declares such a header (see the constructor);
+   * every other client stays on the platform's own redirect handling. One
+   * chain is one attempt: retries, the per-attempt timeout, the caller's
+   * signal, and the onRequest/onResponse hooks all sit outside it and see
+   * the chain as the single exchange it replaces.
+   */
+  private async followRedirects(
+    context: RequestContext,
+    body: NonNullable<RequestInit["body"]> | undefined,
+    signal: AbortSignal,
+  ): Promise<Response> {
+    let url = context.url;
+    let origin = new URL(url).origin;
+    let method = context.method;
+    let headers = context.headers;
+    for (let hop = 0; ; hop++) {
+      const response = await this.config.fetch(url, { method, headers, body, redirect: "manual", signal });
+      // A runtime that filters manual redirects (a browser) hands back an
+      // opaque response with no Location to read. Refuse rather than let the
+      // credential travel blind — the constructor already keeps browsers off
+      // this path, so this is a guard, not an expected outcome.
+      if (response.type === "opaqueredirect" || response.status === 0) {
+        throw new TransportError("This runtime hides redirect targets, so the credential cannot be dropped before the hop");
+      }
+      const location = response.headers.get("location");
+      if (!REDIRECT_STATUSES.has(response.status) || location === null) return response;
+      if (hop >= MAX_REDIRECTS) throw new TransportError("Too many redirects (" + (hop + 1) + ")");
+      await response.body?.cancel();
+
+      const target = new URL(location, url);
+      headers = { ...headers };
+      // Origins are compared exactly — scheme, host, and port — which is
+      // fetch's rule and the one the Python runtime applies.
+      if (target.origin !== origin) headers = withoutHeaders(headers, this.sensitiveHeaders);
+      // The method rewrite fetch performs: a 303 continues as a bodyless GET,
+      // and so does a 301/302 that answered a POST.
+      const toGet = response.status === 303
+        ? method !== "HEAD"
+        : (response.status === 301 || response.status === 302) && method === "POST";
+      if (toGet) {
+        method = "GET";
+        body = undefined;
+        headers = withoutHeaders(headers, CONTENT_HEADERS);
+      } else if (isStreamBody(body)) {
+        // A stream reads once; fetch fails the same way rather than sending
+        // an empty body to the new location.
+        throw new TransportError("Cannot replay a streaming request body across a redirect");
+      }
+      url = target.toString();
+      origin = target.origin;
+    }
+  }
+
+  private async buildUrl(req: CoreRequest): Promise<string> {
+    const base = this.config.baseUrl.replace(/\/+$/, "");
+    const url = new URL(base + req.path);
+    for (const [k, v] of Object.entries(req.query ?? {})) {
+      if (v === undefined || v === null) continue;
+      if (Array.isArray(v)) {
+        // top-level arrays repeat the key: expand=a&expand=b
+        for (const item of v) appendDeep(url.searchParams, k, item);
+      } else {
+        appendDeep(url.searchParams, k, v);
+      }
+    }
+    for (const [k, v] of Object.entries(this.config.query)) {
+      url.searchParams.append(k, await resolveAuthValue(v));
+    }
+    return url.toString();
+  }
+}
+
+async function resolveAuthValue(value: AuthValue): Promise<string> {
+  return typeof value === "function" ? await value() : value;
+}
+
+/** Parse a text/event-stream body into SseEvents, lazily. */
+async function* sseEvents(response: Response): AsyncGenerator<SseEvent, void, undefined> {
+  if (!response.body) return;
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let dataLines: string[] = [];
+  let eventName: string | undefined;
+  let eventId: string | undefined;
+
+  const flush = (): SseEvent | undefined => {
+    if (dataLines.length === 0) return undefined;
+    const event: SseEvent = { data: dataLines.join("\n") };
+    if (eventName !== undefined) event.event = eventName;
+    if (eventId !== undefined) event.id = eventId;
+    dataLines = [];
+    eventName = undefined;
+    return event;
+  };
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      let newline: number;
+      while ((newline = buffer.indexOf("\n")) !== -1) {
+        const hasCr = newline > 0 && buffer[newline - 1] === "\r";
+        const line = buffer.slice(0, hasCr ? newline - 1 : newline);
+        buffer = buffer.slice(newline + 1);
+        if (line === "") {
+          const event = flush();
+          if (event) yield event;
+        } else if (line.startsWith("data:")) {
+          dataLines.push(line.slice(5).replace(/^ /, ""));
+        } else if (line.startsWith("event:")) {
+          eventName = line.slice(6).replace(/^ /, "");
+        } else if (line.startsWith("id:")) {
+          eventId = line.slice(3).replace(/^ /, "");
+        }
+        // comments (":") and "retry:" are intentionally ignored
+      }
+    }
+    const last = flush();
+    if (last) yield last;
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+/** Default rendering for debug events (the boolean debug:true sink). */
+export function formatDebugEvent(name: string, event: DebugEvent): string {
+  return name + " " + event.method + " " + event.path +
+    " -> " + (event.status !== undefined ? String(event.status) : "error") +
+    " (" + event.durationMs + "ms)" +
+    (event.attempt > 1 ? " attempt " + event.attempt : "") +
+    (event.requestId !== undefined ? " " + event.requestId : "") +
+    (event.error !== undefined ? ": " + event.error : "");
+}
+
+/** Wrap a bearer credential (static or callback) as an Authorization value. */
+export function bearerAuth(token: AuthValue): AuthValue {
+  if (typeof token === "function") {
+    return async () => "Bearer " + (await token());
+  }
+  return "Bearer " + token;
+}
+
+export interface ClientCredentialsConfig {
+  clientId: string;
+  clientSecret: string;
+  tokenUrl: string;
+  scopes?: string[];
+  /** Extra token-request parameters, e.g. the "audience" some
+   * authorization servers require for API-valid access tokens. */
+  tokenParams?: Record<string, string>;
+  /** How credentials reach the token endpoint. Default "post"
+   * (client_secret_post, form fields); "basic" sends an Authorization
+   * header (client_secret_basic). */
+  authMethod?: "post" | "basic";
+  fetchImpl?: typeof fetch;
+}
+
+/**
+ * OAuth2 client-credentials token source: fetches from the token URL,
+ * caches until expiry (60s early refresh), and shares one in-flight
+ * request across concurrent callers. Returned function plugs in as an
+ * Authorization AuthValue, resolved before every attempt.
+ */
+export function oauthClientCredentials(config: ClientCredentialsConfig): () => Promise<string> {
+  let token: string | undefined;
+  let expiresAt = 0;
+  let inflight: Promise<string> | undefined;
+  const fetchImpl = config.fetchImpl ?? fetch;
+
+  async function fetchToken(): Promise<string> {
+    const params = new URLSearchParams({ grant_type: "client_credentials" });
+    if (config.scopes !== undefined && config.scopes.length > 0) {
+      params.set("scope", config.scopes.join(" "));
+    }
+    for (const [key, value] of Object.entries(config.tokenParams ?? {})) {
+      params.set(key, value);
+    }
+    const headers: Record<string, string> = {
+      "Content-Type": "application/x-www-form-urlencoded",
+      Accept: "application/json",
+    };
+    if (config.authMethod === "basic") {
+      headers["Authorization"] = "Basic " + toBase64(config.clientId + ":" + config.clientSecret);
+    } else {
+      params.set("client_id", config.clientId);
+      params.set("client_secret", config.clientSecret);
+    }
+    const response = await fetchImpl(config.tokenUrl, { method: "POST", headers, body: params.toString() });
+    const body = (await response.json().catch(() => null)) as
+      | { access_token?: string; expires_in?: number; error?: string }
+      | null;
+    if (!response.ok || typeof body?.access_token !== "string") {
+      throw new TransportError(
+        "OAuth token request failed (HTTP " + response.status + (body?.error ? ": " + body.error : "") + ")",
+        body,
+      );
+    }
+    token = body.access_token;
+    expiresAt = body.expires_in !== undefined
+      ? Date.now() + body.expires_in * 1000 - 60_000
+      : Number.MAX_SAFE_INTEGER;
+    return token;
+  }
+
+  return async () => {
+    if (token !== undefined && Date.now() < expiresAt) return "Bearer " + token;
+    inflight ??= fetchToken().finally(() => { inflight = undefined; });
+    return "Bearer " + (await inflight);
+  };
+}
+
+/**
+ * Bracket-style deep encoding shared by query strings and form bodies:
+ * { created: { gte: 5 } } -> created[gte]=5, { items: [{ id: "x" }] } ->
+ * items[0][id]=x. Scalars append as-is.
+ */
+function appendDeep(target: URLSearchParams, key: string, value: unknown): void {
+  if (value === undefined || value === null) return;
+  if (Array.isArray(value)) {
+    value.forEach((item, i) => appendDeep(target, key + "[" + i + "]", item));
+  } else if (typeof value === "object" && !(value instanceof Blob) && !(value instanceof Date)) {
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      appendDeep(target, key + "[" + k + "]", v);
+    }
+  } else {
+    target.append(key, value instanceof Date ? value.toISOString() : String(value));
+  }
+}
+
+function serializeBody(req: CoreRequest): { body: NonNullable<RequestInit["body"]> | undefined; contentType?: string } {
+  if (req.body === undefined) return { body: undefined };
+  switch (req.bodyKind ?? "json") {
+    case "json":
+      return { body: JSON.stringify(req.body), contentType: "application/json" };
+    case "form": {
+      const params = new URLSearchParams();
+      for (const [k, v] of Object.entries(req.body as Record<string, unknown>)) {
+        appendDeep(params, k, v);
+      }
+      // URLSearchParams sets its own content type with the charset suffix.
+      return { body: params };
+    }
+    case "multipart": {
+      const form = new FormData();
+      for (const [k, v] of Object.entries(req.body as Record<string, unknown>)) {
+        if (v === undefined || v === null) continue;
+        form.append(
+          k,
+          v instanceof Blob ? v : typeof v === "object" ? JSON.stringify(v) : String(v),
+        );
+      }
+      // Let fetch set the boundary header.
+      return { body: form };
+    }
+    case "text":
+      return { body: String(req.body), contentType: "text/plain" };
+    case "binary":
+      return { body: req.body as NonNullable<RequestInit["body"]> };
+  }
+}
+
+async function parseBody(response: Response, method: string): Promise<unknown> {
+  if (method === "HEAD" || response.status === 204 || response.status === 205) return undefined;
+  const contentType = response.headers.get("content-type") ?? "";
+  try {
+    if (contentType.includes("json")) return await response.json();
+    if (contentType.startsWith("text/")) return await response.text();
+    if (response.body === null) return undefined;
+    return await response.blob();
+  } catch (cause) {
+    // A timed-out or aborted body read is a transport failure, not an
+    // empty body — surface it instead of faking success.
+    if (cause instanceof Error && (cause.name === "AbortError" || cause.name === "TimeoutError")) throw cause;
+    return undefined;
+  }
+}
+
+function meta(response: Response): ResponseMeta {
+  return {
+    status: response.status,
+    headers: response.headers,
+    requestId:
+      response.headers.get("x-request-id") ??
+      response.headers.get("request-id") ??
+      undefined,
+  };
+}
+
+function retryAfterMs(response: Response): number | undefined {
+  const header = response.headers.get("retry-after");
+  if (!header) return undefined;
+  const seconds = Number(header);
+  if (Number.isFinite(seconds)) return Math.min(seconds * 1000, 60_000);
+  const date = Date.parse(header);
+  if (!Number.isNaN(date)) return Math.min(Math.max(date - Date.now(), 0), 60_000);
+  return undefined;
+}
+
+/** Exponential backoff with full jitter, capped at 10s by default. */
+function backoff(attempt: number, policy?: RetryPolicy): number {
+  const initial = policy?.initialDelayMs ?? 300;
+  const max = policy?.maxDelayMs ?? 10_000;
+  const cap = Math.min(initial * 2 ** attempt, max);
+  return Math.random() * cap;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export function toBase64(input: string): string {
+  if (typeof btoa === "function") return btoa(input);
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return (globalThis as any).Buffer.from(input, "utf-8").toString("base64");
+}