@typeship-ax/cli 0.22.0 → 0.23.1

package/src/core/http.ts

@@ -1,5 +1,5 @@
 /**
- * Runtime core. Generated by typeship — https://typeship.dev
+ * Runtime core. Generated by Typeship — https://typeship.dev
  * Zero dependencies: built on the platform fetch API (Node 20+, browsers, edge).
  */
 
@@ -12,6 +12,14 @@ export interface RequestOptions {
   timeoutMs?: number;
   /** Retry attempts after the first try. Overrides the client default. */
   maxRetries?: number;
+  /** For a list that pages by URL (a Link header or a next-page URL field):
+   * start from this page URL, as a previous page's nextPageParams() gave it.
+   * It must be on the API's origin. */
+  pageUrl?: string;
+  /** Receives this call's response metadata (status, headers, ETag,
+   * rate-limit state) once a response arrives, whether the call succeeded
+   * or failed. A 304 Not Modified raises `NotModifiedError`. */
+  onResponse?: (response: ResponseMeta) => void;
 }
 
 export interface ResponseMeta {
@@ -24,13 +32,82 @@ export interface ResponseMeta {
   /** Request identifier from the JSON response body, or from headers for
    * raw and bodyless responses. */
   requestId?: string;
+  /** The `ETag` header, for a later conditional request (`If-None-Match`). */
+  etag?: string;
+  /** The `Last-Modified` header, for a later `If-Modified-Since`. */
+  lastModified?: string;
+  /** True for a 304 Not Modified: the resource matched the conditional
+   * request, and the call raised `NotModifiedError`. */
+  notModified?: boolean;
+  /** Set when the API said the call was rate limited. */
+  rateLimit?: RateLimitInfo;
+}
+
+/** When a rate-limited call can be retried. Both fields are absent when the
+ * API did not say. */
+export interface RateLimitInfo {
+  /** The instant the limit resets (from `Retry-After` or `x-ratelimit-reset`). */
+  retryAt?: Date;
+  /** Milliseconds from when the response arrived until `retryAt`. */
+  retryAfterMs?: number;
+}
+
+/** Response headers that carry a request identifier, most specific first. */
+const REQUEST_ID_HEADERS = ["request-id", "x-request-id", "x-github-request-id", "twilio-request-id", "x-amzn-requestid", "x-slack-req-id", "cf-ray"];
+
+function requestIdFromHeaders(headers: Headers): string | undefined {
+  for (const name of REQUEST_ID_HEADERS) {
+    const value = headers.get(name);
+    if (value) return value;
+  }
+  return undefined;
+}
+
+/**
+ * Whether a response is a rate limit, and when to retry. A 429 always is. A
+ * 403 is when it says the quota is spent (`x-ratelimit-remaining: 0`) or asks
+ * the caller to wait (`Retry-After`), which is how GitHub signals its primary
+ * and secondary limits. Undefined for every other response.
+ */
+export function rateLimitInfo(status: number, headers: Headers, now = Date.now()): RateLimitInfo | undefined {
+  const retryAfter = headers.get("retry-after");
+  const remaining = headers.get("x-ratelimit-remaining") ?? headers.get("ratelimit-remaining");
+  const limited = status === 429 || (status === 403 && (retryAfter !== null || (remaining !== null && remaining.trim() === "0")));
+  if (!limited) return undefined;
+  let waitMs: number | undefined;
+  if (retryAfter !== null && retryAfter.trim() !== "") {
+    const seconds = Number(retryAfter);
+    if (Number.isFinite(seconds)) waitMs = Math.max(seconds, 0) * 1000;
+    else if (!Number.isNaN(Date.parse(retryAfter))) waitMs = Math.max(Date.parse(retryAfter) - now, 0);
+  }
+  const reset = headers.get("x-ratelimit-reset") ?? headers.get("ratelimit-reset");
+  if (waitMs === undefined && reset !== null && reset.trim() !== "" && Number.isFinite(Number(reset))) {
+    const value = Number(reset);
+    // An epoch timestamp (GitHub, Twitter) or seconds until the reset (the
+    // IETF RateLimit header fields).
+    waitMs = Math.max(value > 1e9 ? value * 1000 - now : value * 1000, 0);
+  }
+  if (waitMs === undefined) return {};
+  return { retryAt: new Date(now + waitMs), retryAfterMs: waitMs };
+}
+
+function rateLimitStep(info: RateLimitInfo): string {
+  if (!info.retryAt) return "Rate limited: wait before retrying.";
+  // Round up to the second so "wait until" is never early.
+  const at = new Date(Math.ceil(info.retryAt.getTime() / 1000) * 1000);
+  return "Rate limited: wait until " + at.toISOString().replace(/\.\d{3}Z$/, "Z") + ", then retry.";
 }
 
 /**
  * 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>);
+export type AuthValue = string | ((context: CredentialContext) => string | Promise<string>);
+
+/** Passed to credential callbacks. `rejected` is true once, on the attempt
+ * after the API answered 401 to the value this callback last returned:
+ * refresh or replace the token instead of returning it again. */
+export interface CredentialContext { rejected: boolean }
 
 /** Passed to onRequest/onResponse hooks. Mutations to headers and url in
  * onRequest apply to the outgoing request. */
@@ -92,53 +169,190 @@ export class SdkError extends Error {
   }
 }
 
+function errorFields(body: unknown): { error?: Record<string, unknown>; value?: Record<string, unknown>; first?: Record<string, unknown> } {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return {};
+  const value = body as Record<string, unknown>;
+  const nested = value.error && typeof value.error === "object" && !Array.isArray(value.error) ? value.error as Record<string, unknown> : undefined;
+  const first = Array.isArray(value.errors) && value.errors[0] && typeof value.errors[0] === "object" ? value.errors[0] as Record<string, unknown> : undefined;
+  return { error: nested, value, first };
+}
+
+/** The API's own error code: `error.code`, `code`, `error.type`, then
+ * `errors[0].code`; numeric codes (Twilio's 20404) as strings. */
 function errorCode(body: unknown, fallback: string): string {
-  if (body && typeof body === "object" && !Array.isArray(body)) {
-    const value = body as Record<string, unknown>;
-    const first = Array.isArray(value.errors) ? value.errors[0] as { code?: unknown } | undefined : undefined;
-    const code = value.code ?? first?.code;
+  const { error, value, first } = errorFields(body);
+  if (!value) return fallback;
+  for (const code of [error?.code, value.code, error?.type, first?.code]) {
     if (typeof code === "string" && code.trim()) return code;
+    if (typeof code === "number" && Number.isFinite(code)) return String(code);
   }
+  // Slack-style `{"ok": false, "error": "invalid_auth"}`: the error is a code.
+  if (typeof value.error === "string" && /^[A-Za-z][\w.-]{0,63}$/.test(value.error)) return value.error;
   return fallback;
 }
 
+/** The API's own message: `error.message`, `message`, `errors[0].message`,
+ * `detail`, `error_description`, then a string `error`. */
 function errorDetail(body: unknown): string {
-  if (!body || typeof body !== "object" || Array.isArray(body)) return "";
-  const value = body as Record<string, unknown>;
-  const first = Array.isArray(value.errors) ? value.errors[0] as { message?: unknown } | undefined : undefined;
-  const detail = value.message ?? value.error ?? value.detail ?? first?.message;
-  return typeof detail === "string" && detail.trim() ? ": " + detail : "";
+  const { error, value, first } = errorFields(body);
+  if (!value) return "";
+  for (const detail of [error?.message, value.message, first?.message, value.detail, value.error_description, value.error]) {
+    if (typeof detail === "string" && detail.trim()) return detail.trim();
+  }
+  return "";
 }
 
 function nextStep(status: number): string {
+  if (status >= 200 && status < 300) return "It arrived in a successful HTTP response; the body says why.";
   if (status === 401) return "Check the credential and retry.";
   if (status === 403) return "Check the credential's permissions and retry.";
   if (status === 404) return "Check the requested identifier or path.";
   if (status === 409) return "Refresh the resource and retry the change.";
+  if (status === 413) return "Send less data in one request.";
   if (status === 422 || status === 400) return "Correct the request and retry.";
   if (status === 429) return "Wait before retrying the request.";
   if (status >= 500) return "Retry later; contact the API provider if this continues.";
   return "Inspect the error body and correct the request before retrying.";
 }
 
-/** Base class for every HTTP error response. */
+/** Base class for every HTTP error response. The message leads with the
+ * status and the API's own message ("HTTP 404: No such customer"), then the
+ * next step. `code` is the API's error code when the body names one. */
 export class ApiError<S extends number = number, B = unknown> extends SdkError {
   readonly status: S;
   readonly body: B;
   readonly response: ResponseMeta;
 
-  constructor(message: string, status: S, body: B, response: ResponseMeta) {
-    super(message + errorDetail(body) + ". " + nextStep(status), errorCode(body, "http_" + status), status, body, response.requestId);
+  /** Set when the API said this call was rate limited (a 429, or a 403
+   * whose headers say the quota is spent): when to retry. */
+  readonly rateLimit?: RateLimitInfo;
+
+  /** `summary` leads the message ("HTTP 404"); the API's message follows it. */
+  constructor(summary: string, status: S, body: B, response: ResponseMeta, own?: { message: string; code: string }) {
+    const limit = response.rateLimit ?? (response.headers ? rateLimitInfo(status, response.headers) : undefined);
+    const detail = errorDetail(body);
+    super(
+      // An API message usually ends its own sentence; do not double it.
+      own?.message ?? (summary + (detail ? ": " + detail : "")).replace(/[.!?]+$/, "") + ". " + (limit ? rateLimitStep(limit) : nextStep(status)),
+      own?.code ?? errorCode(body, limit ? "rate_limited" : "http_" + status),
+      status, body, response.requestId,
+    );
     this.status = status;
     this.body = body;
     this.response = response;
+    if (limit) this.rateLimit = limit;
+  }
+}
+
+/** HTTP 400: the API rejected the request as malformed. Raised for every
+ * 400, documented or not; `body` is typed where the operation declares it. */
+export class BadRequestError<B = unknown> extends ApiError<400, B> {
+  constructor(body: B, response: ResponseMeta) {
+    super("HTTP 400", 400, body, response);
+  }
+}
+
+/** HTTP 401: the credential is missing, invalid or expired. */
+export class UnauthorizedError<B = unknown> extends ApiError<401, B> {
+  constructor(body: B, response: ResponseMeta) {
+    super("HTTP 401", 401, body, response);
+  }
+}
+
+/** HTTP 403: the credential lacks access. A 403 that signals a rate limit
+ * raises RateLimitError instead. */
+export class ForbiddenError<B = unknown> extends ApiError<403, B> {
+  constructor(body: B, response: ResponseMeta) {
+    super("HTTP 403", 403, body, response);
+  }
+}
+
+/** HTTP 404: the resource or path does not exist. */
+export class NotFoundError<B = unknown> extends ApiError<404, B> {
+  constructor(body: B, response: ResponseMeta) {
+    super("HTTP 404", 404, body, response);
+  }
+}
+
+/** HTTP 409: the request conflicts with the resource's current state. */
+export class ConflictError<B = unknown> extends ApiError<409, B> {
+  constructor(body: B, response: ResponseMeta) {
+    super("HTTP 409", 409, body, response);
+  }
+}
+
+/** HTTP 422: the request was well formed but failed validation. */
+export class UnprocessableEntityError<B = unknown> extends ApiError<422, B> {
+  constructor(body: B, response: ResponseMeta) {
+    super("HTTP 422", 422, body, response);
+  }
+}
+
+/** The API rate limited the call: every 429, and a 403 whose headers say
+ * the quota is spent. `rateLimit.retryAt` says when to try again. */
+export class RateLimitError<B = unknown> extends ApiError<number, B> {
+  constructor(body: B, response: ResponseMeta) {
+    super("HTTP " + response.status, response.status, body, response);
+  }
+}
+
+/** Any 5xx: the API failed to handle a valid request. */
+export class ServerError<B = unknown> extends ApiError<number, B> {
+  constructor(body: B, response: ResponseMeta) {
+    super("HTTP " + response.status, response.status, body, response);
+  }
+}
+
+/** HTTP 304: a conditional request (`If-None-Match`, `If-Modified-Since`)
+ * matched, so the resource has not changed and the response has no body.
+ * Raised only when the caller sent a conditional header. `etag` and
+ * `lastModified` are the validators to send next time. */
+export class NotModifiedError extends ApiError<304, undefined> {
+  /** The response's `ETag` header. */
+  readonly etag?: string;
+  /** The response's `Last-Modified` header. */
+  readonly lastModified?: string;
+  constructor(response: ResponseMeta) {
+    super("HTTP 304", 304, undefined, response, {
+      message: "HTTP 304: Not modified. The resource matches the validator sent in If-None-Match or If-Modified-Since; keep using the copy you have.",
+      code: "not_modified",
+    });
+    if (response.etag) this.etag = response.etag;
+    if (response.lastModified) this.lastModified = response.lastModified;
   }
 }
 
-/** A response status the spec didn't document. */
+/** The class raised for a status whatever the operation declares. */
+function statusFamily(status: number): ErrorCtor | undefined {
+  switch (status) {
+    case 400: return BadRequestError;
+    case 401: return UnauthorizedError;
+    case 403: return ForbiddenError;
+    case 404: return NotFoundError;
+    case 409: return ConflictError;
+    case 422: return UnprocessableEntityError;
+    case 429: return RateLimitError;
+  }
+  return status >= 500 && status < 600 ? ServerError : undefined;
+}
+
+/** A 2xx response whose payload reported a failure: a declared envelope
+ * flag set to false (`{"ok": false}`, `{"success": false}`), or a GraphQL
+ * result that is one of the schema's error types. */
+export class PayloadError extends ApiError<number, unknown> {
+  /** The GraphQL error type the result resolved to, for GraphQL operations. */
+  readonly typename?: string;
+  constructor(body: unknown, response: ResponseMeta, typename?: string) {
+    super(typename ? "The operation returned " + typename : "The API reported a failure", response.status, body, response);
+    if (typename) this.typename = typename;
+  }
+}
+
+/** A status with no family class (a 402, 405 or 410, say) that the
+ * operation did not document. */
 export class UnexpectedApiError extends ApiError<number, unknown> {
   constructor(status: number, body: unknown, response: ResponseMeta) {
-    super("Unexpected HTTP status " + status, status, body, response);
+    super("HTTP " + status, status, body, response);
   }
 }
 
@@ -308,13 +522,35 @@ function transportFailureMessage(method: string, url: string, cause: unknown): s
   return method + " " + url + " failed: " + detail;
 }
 
-/** The request failed before a complete HTTP response arrived (network failure, timeout, abort, or truncated body). */
+/** Why a request failed in transit, as TransportError's `code`: the
+ * caller's AbortSignal fired ("aborted"), the per-attempt timeout elapsed
+ * ("timeout"), or the connection or body read failed ("transport_error"). */
+export type TransportFailure = "aborted" | "timeout" | "transport_error";
+
+function transportFailure(cause: unknown, signal?: AbortSignal): TransportFailure {
+  if (signal?.aborted) return "aborted";
+  let node: unknown = cause;
+  for (let depth = 0; depth < 5 && node !== null && typeof node === "object"; depth++) {
+    if ((node as { name?: unknown }).name === "TimeoutError") return "timeout";
+    node = (node as { cause?: unknown }).cause;
+  }
+  return "transport_error";
+}
+
+const TRANSPORT_NEXT_STEP: Record<TransportFailure, string> = {
+  aborted: ". The caller's AbortSignal cancelled the request.",
+  timeout: ". The request timed out; retry, or raise timeoutMs.",
+  transport_error: ". Check the connection and retry.",
+};
+
+/** The request failed before a complete HTTP response arrived (network failure, timeout, abort, or truncated body); `code` says which. */
 export class TransportError extends SdkError {
   override readonly cause?: unknown;
   readonly response?: ResponseMeta;
+  declare readonly code: TransportFailure;
 
-  constructor(message: string, cause?: unknown, response?: ResponseMeta) {
-    super(message + ". Check the connection and retry.", "transport_error", response?.status ?? null, undefined, response?.requestId);
+  constructor(message: string, cause?: unknown, response?: ResponseMeta, failure: TransportFailure = "transport_error") {
+    super(message + TRANSPORT_NEXT_STEP[failure], failure, response?.status ?? null, undefined, response?.requestId);
     this.cause = cause;
     this.response = response;
   }
@@ -326,10 +562,18 @@ export interface CoreRequest {
   security?: Record<string, string[]>[];
   method: string;
   path: string;
+  /** A full URL on the API's origin (a next-page link), sent instead of
+   * path and query. */
+  url?: string;
   query?: Record<string, unknown>;
   headers?: Record<string, string | undefined>;
   body?: unknown;
   bodyKind?: "json" | "form" | "multipart" | "text" | "binary";
+  /** Per-field wire encoding (the media type's `encoding`): a multipart
+   * part's Content-Type, or the delimiter of an unexploded form array. */
+  bodyEncoding?: Record<string, { contentType?: string; delimiter?: string }>;
+  /** Multipart fields that must hold a Blob or File (or an array of them). */
+  fileFields?: string[];
   /** Status matcher -> generated error class ("404", "4XX", "default"). */
   errors?: Record<string, ErrorCtor>;
   /** Idempotent requests are retried automatically. */
@@ -339,13 +583,16 @@ export interface CoreRequest {
   idempotencyKey?: string;
   /** Key into the schemas table for optional runtime validation. */
   schemaKey?: string;
-  /** Operation-level retry policy (x-typeship-retries), merged over the
+  /** The success body's envelope flag (`ok`, `success`): `false` there is a
+   * failure reported inside a 2xx response, raised as a PayloadError. */
+  failureFlag?: string;
+  /** Operation-level retry policy from the API definition, 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). */
+/** Tunable retry behavior (defaults preserved when unset). */
 export interface RetryPolicy {
   maxRetries?: number;
   /** Replaces the default retryable set (408, 429, 500, 502, 503, 504). */
@@ -412,13 +659,18 @@ export interface CoreConfig {
    * 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). */
+  /** Loads the per-operation schema table, keyed "resource.method", and the
+   * shared component definitions it references (see schemas.ts). Called on
+   * the first validated request, so the table stays out of the startup path
+   * and, in a bundler that splits dynamic imports, out of the main bundle. */
+  loadSchemas?: () => Promise<SchemaTables>;
+  /** API-wide retry policy from the API definition. */
   retry?: RetryPolicy;
-  /** Client-level values for x-typeship-globals parameters, by wire name. */
+  /** The longest server-requested wait (Retry-After, x-ratelimit-reset) a
+   * retry honors. A longer wait fails the call at once with the reset time
+   * instead of sleeping. Default 60000ms. */
+  maxRetryWaitMs?: number;
+  /** Client-level values for global 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,
@@ -465,8 +717,15 @@ function isStreamBody(body: unknown): boolean {
   return typeof (body as { getReader?: unknown } | undefined)?.getReader === "function";
 }
 
+/** The validation tables schemas.ts exports. */
+export interface SchemaTables {
+  SCHEMAS: Record<string, { req?: unknown; res?: unknown }>;
+  DEFS: Record<string, unknown>;
+}
+
 export class HttpCore {
   readonly config: CoreConfig;
+  private schemaTables?: Promise<SchemaTables>;
   /** Lowercased header names dropped on a cross-origin hop. */
   private readonly sensitiveHeaders: string[];
   /** Whether this runtime follows redirects itself instead of letting the
@@ -487,7 +746,7 @@ export class HttpCore {
     this.manualRedirects = custom.length > 0 && (globalThis as { document?: unknown }).document === undefined;
   }
 
-  /** The client-level value for an x-typeship-globals parameter. */
+  /** The client-level value for a global parameter. */
   globalValue(name: string): unknown {
     return this.config.globals?.[name];
   }
@@ -514,11 +773,18 @@ export class HttpCore {
         ? crypto.randomUUID()
         : undefined;
 
-    const opSchemas = this.config.validate && req.schemaKey ? this.config.schemas?.[req.schemaKey] : undefined;
+    const tables = this.config.validate && req.schemaKey && this.config.loadSchemas
+      ? await (this.schemaTables ??= this.config.loadSchemas())
+      : undefined;
+    const opSchemas = tables && req.schemaKey ? tables.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);
+      // A GraphQL body is the {query, variables} envelope; the schema
+      // describes the variables.
+      let validated: unknown = req.body;
+      let label = "body";
+      validateAgainstSchema(validated, opSchemas.req, label, violations, tables!.DEFS);
       if (violations.length > 0) {
         const validationError = new ValidationError("request", violations);
         if (this.config.validate!.mode === "warn") {
@@ -532,6 +798,22 @@ export class HttpCore {
     }
 
     let lastError: unknown;
+    let credentialsRefreshed = false;
+    // With an automatic Idempotency-Key, a retry that the API refuses as a
+    // duplicate still in progress (409/429) is about our own first attempt.
+    // Report that original failure instead, with its request id.
+    let original: { error: E; response?: ResponseMeta } | undefined;
+    const errorFor = (response: Response, body: unknown, responseMeta: ResponseMeta, limit: RateLimitInfo | undefined): E => {
+      // A documented status keeps its own class; a family status (404,
+      // 429, 5xx) raises the family class declared or not, so one catch
+      // covers it; ranges and default cover the rest.
+      const Ctor = limit ? RateLimitError
+        : req.errors?.[String(response.status)] ??
+          statusFamily(response.status) ??
+          req.errors?.[String(Math.floor(response.status / 100)) + "XX"] ??
+          req.errors?.["default"];
+      return (Ctor ? new Ctor(body, responseMeta) : new UnexpectedApiError(response.status, body, responseMeta)) as unknown as E;
+    };
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
       let response: Response;
       const attemptStarted = Date.now();
@@ -541,15 +823,16 @@ export class HttpCore {
         status: value.status,
         durationMs: Date.now() - attemptStarted,
         attempt: attempt + 1,
-        requestId:
-          requestIdFromBody(body) ??
-          value.headers.get("request-id") ??
-          value.headers.get("x-request-id") ??
-          undefined,
+        requestId: requestIdFromBody(body) ?? requestIdFromHeaders(value.headers),
       });
       try {
         response = await this.send(req, timeoutMs, attempt, autoIdempotencyKey);
       } catch (cause) {
+        if (cause instanceof CredentialCallbackFailure) {
+          const error = cause.error as E;
+          await this.config.onError?.(error, { method: req.method, path: req.path });
+          return { ok: false, error };
+        }
         lastError = cause;
         this.config.debug?.({
           method: req.method,
@@ -559,17 +842,30 @@ export class HttpCore {
           error: cause instanceof Error ? cause.message : String(cause),
         });
         if (attempt < maxRetries && retryAllowed && !req.options?.signal?.aborted) {
+          if (autoIdempotencyKey) original = { error: new TransportError(transportFailureMessage(req.method, this.config.baseUrl.replace(/\/+$/, "") + req.path, cause), cause, undefined, transportFailure(cause)) as unknown as E };
           await sleep(backoff(attempt, policy));
           continue;
         }
         const error = new TransportError(
           transportFailureMessage(req.method, this.config.baseUrl.replace(/\/+$/, "") + req.path, cause),
           cause,
+          undefined,
+          transportFailure(cause, req.options?.signal),
         ) as unknown as E;
         await this.config.onError?.(error, { method: req.method, path: req.path });
         return { ok: false, error };
       }
 
+      // A conditional request matched: nothing changed. Raised so a method
+      // keeps its non-null type, but not a failure: onError is not called.
+      if (response.status === 304) {
+        void response.body?.cancel().catch(() => {});
+        emitResponseDebug(response);
+        const notModified = { ...meta(response), notModified: true };
+        req.options?.onResponse?.(notModified);
+        return { ok: false, error: new NotModifiedError(notModified) as unknown as E, response: notModified };
+      }
+
       if (response.ok) {
         let data: T;
         try {
@@ -577,21 +873,32 @@ export class HttpCore {
         } catch (cause) {
           const parseError = cause instanceof ResponseParseError ? cause : undefined;
           emitResponseDebug(response, parseError?.body);
+          req.options?.onResponse?.(parseError?.response ?? meta(response));
           const error = (parseError ?? new TransportError(
             "The response body read failed before completing",
             cause,
             meta(response),
+            transportFailure(cause, req.options?.signal),
           )) as unknown as E;
           await this.config.onError?.(error, { method: req.method, path: req.path });
           return { ok: false, error, response: parseError?.response ?? meta(response) };
         }
         emitResponseDebug(response, data);
         const responseMeta = meta(response, data);
+        req.options?.onResponse?.(responseMeta);
         let responseData: unknown = data;
+        // Checked before validation: a failure body rarely matches the
+        // success schema, and the failure is the news.
+        if (req.failureFlag && data && typeof data === "object" && !Array.isArray(data)
+            && (data as Record<string, unknown>)[req.failureFlag] === false) {
+          const payloadError = new PayloadError(data, responseMeta) as unknown as E;
+          await this.config.onError?.(payloadError, { method: req.method, path: req.path });
+          return { ok: false, error: payloadError, response: responseMeta };
+        }
         let shouldValidateResponse = responseData !== undefined;
         if (opSchemas?.res && this.config.validate!.responses && shouldValidateResponse) {
           const violations: Violation[] = [];
-          validateAgainstSchema(responseData, opSchemas.res, "response", violations, this.config.schemaDefs);
+          validateAgainstSchema(responseData, opSchemas.res, "response", violations, tables!.DEFS);
           if (violations.length > 0) {
             const validationError = new ValidationError("response", violations);
             if (this.config.validate!.mode === "warn") {
@@ -607,12 +914,23 @@ export class HttpCore {
       }
 
       // 429 is safe to retry regardless of idempotency; other retryable
-      // statuses only when the verb is idempotent.
+      // statuses, and a rate-limited 403, only when the verb is idempotent.
+      const limit = rateLimitInfo(response.status, response.headers);
       const retryableStatus =
-        retryableStatuses.has(response.status) &&
+        (retryableStatuses.has(response.status) || (limit !== undefined && response.status === 403)) &&
         (retryAllowed || response.status === 429);
-      if (attempt < maxRetries && retryableStatus) {
-        const delay = retryAfterMs(response) ?? backoff(attempt, policy);
+      // A server-requested wait beyond the ceiling fails now, with the reset
+      // time in the error, rather than holding the caller.
+      const requestedWait = limit?.retryAfterMs ?? retryAfterMs(response);
+      const withinCeiling = requestedWait === undefined || requestedWait <= (this.config.maxRetryWaitMs ?? 60_000);
+      if (original && (response.status === 409 || response.status === 429)) {
+        void response.body?.cancel().catch(() => {});
+        emitResponseDebug(response);
+        await this.config.onError?.(original.error, { method: req.method, path: req.path });
+        return { ok: false, error: original.error, ...(original.response ? { response: original.response } : {}) };
+      }
+      if (attempt < maxRetries && retryableStatus && withinCeiling) {
+        const delay = requestedWait ?? backoff(attempt, policy);
         let retryBody: unknown;
         try {
           retryBody = await parseBody(response, req.method);
@@ -620,10 +938,24 @@ export class HttpCore {
           retryBody = undefined;
         }
         emitResponseDebug(response, retryBody);
+        if (autoIdempotencyKey && response.status >= 500) {
+          const failedMeta = meta(response, retryBody);
+          original = { error: errorFor(response, retryBody, failedMeta, limit), response: failedMeta };
+        }
         await sleep(delay);
         continue;
       }
 
+      // A rejected callback or cached token gets one fresh resolution; the
+      // resend does not spend the retry budget. Static credentials do not.
+      if (response.status === 401 && !credentialsRefreshed && this.refreshCredentials(req)) {
+        credentialsRefreshed = true;
+        void response.body?.cancel().catch(() => {});
+        emitResponseDebug(response);
+        attempt--;
+        continue;
+      }
+
       let body: unknown;
       try {
         body = await parseBody(response, req.method);
@@ -632,13 +964,10 @@ export class HttpCore {
       }
       emitResponseDebug(response, body);
       const responseMeta = meta(response, body);
-      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;
+      req.options?.onResponse?.(responseMeta);
+      // A rate limit is its own error whatever the status: a 403 that means
+      // "wait" must not read as "your credential lacks access".
+      const error = errorFor(response, body, responseMeta, limit);
       await this.config.onError?.(error, { method: req.method, path: req.path });
       return { ok: false, error, response: responseMeta };
     }
@@ -649,6 +978,19 @@ export class HttpCore {
     return { ok: false, error };
   }
 
+  /** Drop cached tokens behind the credential this request selected. True
+   * when a callback or cached token can resolve to a new value. */
+  private refreshCredentials(req: CoreRequest): boolean {
+    const selected = req.security && this.config.credentials ? selectSecurity(req.security, this.config.credentials) : {};
+    let refreshable = false;
+    for (const value of [...Object.values(selected.headers ?? {}), ...Object.values(selected.query ?? {})]) {
+      if (typeof value !== "function") continue;
+      refreshable = true;
+      markRejected(value as RefreshableAuth);
+    }
+    return refreshable;
+  }
+
   /** SDK-facing call: resolve to the payload or throw its typed error. */
   async requestData<T, E>(req: CoreRequest): Promise<T> {
     return unwrap(await this.request<T, E>(req));
@@ -768,7 +1110,7 @@ export class HttpCore {
 
   private async buildUrl(req: CoreRequest, authQuery?: Record<string, AuthValue>): Promise<string> {
     const base = this.config.baseUrl.replace(/\/+$/, "");
-    const url = new URL(base + req.path);
+    const url = req.url !== undefined ? new URL(req.url, base) : new URL(base + req.path);
     for (const [k, v] of Object.entries(req.query ?? {})) {
       if (v === undefined || v === null) continue;
       if (Array.isArray(v)) {
@@ -785,8 +1127,37 @@ export class HttpCore {
   }
 }
 
+/** A credential callback failed: surface the caller's own error unchanged
+ * instead of retrying it as a transport failure. */
+class CredentialCallbackFailure {
+  readonly error: unknown;
+  constructor(error: unknown) { this.error = error; }
+}
+
 async function resolveAuthValue(value: AuthValue): Promise<string> {
-  return typeof value === "function" ? await value() : value;
+  if (typeof value !== "function") return value;
+  try {
+    return await callCredential(value);
+  } catch (error) {
+    // The SDK's own token request failures keep the transport retry path.
+    if (error instanceof TransportError) throw error;
+    throw new CredentialCallbackFailure(error);
+  }
+}
+
+/** A refreshable credential: a callback, or a cached client-credentials
+ * token that can be dropped before one resend after a 401. */
+type RefreshableAuth = ((context: CredentialContext) => string | Promise<string>) & { invalidate?: () => void };
+
+/** Callbacks without their own invalidate learn of a 401 on their next call. */
+const rejectedCallbacks = new WeakSet<object>();
+function markRejected(value: RefreshableAuth): void {
+  if (value.invalidate) value.invalidate();
+  else rejectedCallbacks.add(value);
+}
+function callCredential(value: RefreshableAuth): string | Promise<string> {
+  const rejected = rejectedCallbacks.delete(value);
+  return value({ rejected });
 }
 
 
@@ -803,12 +1174,35 @@ export function formatDebugEvent(name: string, event: DebugEvent): string {
 /** 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 Object.assign(async () => "Bearer " + (await callCredential(token)), { invalidate: () => markRejected(token) });
   }
   return "Bearer " + token;
 }
 
 
+/** The media type a local file is uploaded as, from its extension. A
+ * Worker module (.mjs) must arrive as application/javascript+module. */
+export function mediaTypeForPath(path: string): string {
+  const extension = /\.([A-Za-z0-9]+)$/.exec(path)?.[1]?.toLowerCase() ?? "";
+  const types: Record<string, string> = {
+    mjs: "application/javascript+module", js: "application/javascript", cjs: "application/javascript", wasm: "application/wasm",
+    json: "application/json", jsonl: "application/jsonl", txt: "text/plain", md: "text/markdown", csv: "text/csv", html: "text/html",
+    xml: "application/xml", yaml: "application/yaml", yml: "application/yaml", pdf: "application/pdf", zip: "application/zip",
+    png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", gif: "image/gif", webp: "image/webp", svg: "image/svg+xml",
+    mp3: "audio/mpeg", wav: "audio/wav", ogg: "audio/ogg", flac: "audio/flac", m4a: "audio/mp4", mp4: "video/mp4", webm: "video/webm",
+  };
+  return types[extension] ?? "application/octet-stream";
+}
+
+/**
+ * Join a query array into one delimited value (`ids=1,2`) for parameters
+ * whose spec says `explode: false`. Other values pass through unchanged.
+ */
+export function delimited(value: unknown, separator: string): unknown {
+  if (!Array.isArray(value)) return value;
+  return value.map((item) => (item instanceof Date ? item.toISOString() : String(item))).join(separator);
+}
+
 /**
  * Bracket-style deep encoding shared by query strings and form bodies:
  * { created: { gte: 5 } } -> created[gte]=5, { items: [{ id: "x" }] } ->
@@ -827,6 +1221,7 @@ function appendDeep(target: URLSearchParams, key: string, value: unknown): void
   }
 }
 
+
 function serializeBody(req: CoreRequest): { body: NonNullable<RequestInit["body"]> | undefined; contentType?: string } {
   if (req.body === undefined) return { body: undefined };
   switch (req.bodyKind ?? "json") {
@@ -870,15 +1265,17 @@ function requestIdFromBody(body: unknown): string | undefined {
 }
 
 function meta(response: Response, body?: unknown): ResponseMeta {
+  const etag = response.headers.get("etag");
+  const lastModified = response.headers.get("last-modified");
+  const rateLimit = rateLimitInfo(response.status, response.headers);
   return {
     status: response.status,
     headers: response.headers,
     ...(body !== undefined ? { rawBody: body } : {}),
-    requestId:
-      requestIdFromBody(body) ??
-      response.headers.get("request-id") ??
-      response.headers.get("x-request-id") ??
-      undefined,
+    requestId: requestIdFromBody(body) ?? requestIdFromHeaders(response.headers),
+    ...(etag ? { etag } : {}),
+    ...(lastModified ? { lastModified } : {}),
+    ...(rateLimit ? { rateLimit } : {}),
   };
 }
 
@@ -906,13 +1303,14 @@ function composeSignals(signals: AbortSignal[]): AbortSignal {
   return controller.signal;
 }
 
+/** Retry-After on a retryable status that is not a rate limit (a 503). */
 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);
+  if (Number.isFinite(seconds)) return Math.max(seconds * 1000, 0);
   const date = Date.parse(header);
-  if (!Number.isNaN(date)) return Math.min(Math.max(date - Date.now(), 0), 60_000);
+  if (!Number.isNaN(date)) return Math.max(date - Date.now(), 0);
   return undefined;
 }
 
@@ -929,7 +1327,8 @@ function sleep(ms: number): Promise<void> {
 }
 
 export function toBase64(input: string): string {
-  if (typeof btoa === "function") return btoa(input);
+  // Encode UTF-8 bytes: btoa alone rejects characters outside Latin-1.
+  if (typeof btoa === "function") return btoa(Array.from(new TextEncoder().encode(input), (byte) => String.fromCharCode(byte)).join(""));
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   return (globalThis as any).Buffer.from(input, "utf-8").toString("base64");
 }