@0xinsider/mcp 2.1.0 → 2.1.3

package/dist/sdk/pagination.d.ts

@@ -1,26 +1,108 @@
 /**
  * Cursor pagination over the Stripe-style V1 list envelope.
  *
- * Every list endpoint returns `{ object: "list", data, has_more, next_cursor }`.
- * `paginate()` yields each `data[]` item across pages, following `next_cursor`
- * while `has_more` is true. `paginatePages()` yields whole pages when you need
- * the envelope (e.g. to read `meta.cost` or `total`).
+ * Every list endpoint returns `{ object: "list", data, has_more, next_cursor }`
+ * (`backend/src/api_v1/types.rs` `ApiList`: `has_more` is always a boolean,
+ * `next_cursor` is a string or omitted). `paginate()` yields each `data[]`
+ * item across pages, following `next_cursor` while `has_more` is true.
+ * `paginatePages()` yields whole pages when you need the envelope (e.g. to
+ * read `meta.cost` or `total`).
  *
- * The loop stops on the first page where `has_more` is false OR `next_cursor`
- * is null/absent, so a buggy server that returns `has_more: true` with no
- * cursor cannot spin forever.
+ * The walker is a progress-checked consumer of that protocol (#16246):
+ *
+ * - A page is validated BEFORE it is yielded. `has_more: true` with no usable
+ *   `next_cursor` is a `PaginationError` (`missing_cursor`); the backend's own
+ *   cursor builders refuse to produce that page ("has_more is true for an
+ *   empty page", `insider_radar.rs`), so a client seeing it is looking at a
+ *   malformed response, not the end of the collection. Before #16246 the
+ *   walk returned as if the collection were exhausted.
+ * - A `next_cursor` that repeats a cursor this walk already requested is a
+ *   `PaginationError` (`repeated_cursor`), thrown before the duplicate
+ *   request. The last `CURSOR_HISTORY_LIMIT` cursors are remembered; a cycle
+ *   longer than that is not detected, which bounds memory on a long walk.
+ * - `maxPages` is validated before any request: a positive integer or
+ *   `Infinity`; `0`, a negative, fractional or `NaN` value throws `RangeError`.
+ * - `has_more: false` ends the walk normally, whatever `next_cursor` says.
+ * - A `PaginationError` carries the offending `page`, so its data is not lost,
+ *   and registers a resume point like any other failure.
+ *
+ * `options.progress`, when passed, is updated as the walk goes: how many
+ * pages were fetched, the last cursor requested, the `next_cursor` of the
+ * last page, and why the walk stopped, so a caller that stops at `maxPages`
+ * can tell "the collection has more" from "the collection is exhausted" and
+ * keep the continuation.
  */
-import type { ApiListEnvelope, ApiOperationId, ApiRequestOptions, ListParams, OxinsiderApiClient } from "./client.js";
+import type { ApiListEnvelope, ApiOperationId, ApiRequestOptions, ListOperationId, ListParams, OperationEnvelope, OperationItem, OxinsiderApiClient } from "./client.js";
+import type { OperationPath, OperationQuery } from "./schema.js";
+/**
+ * How many requested cursors a walk remembers for the repeat check. A cycle
+ * longer than this is not detected; the bound keeps a long walk's memory
+ * flat instead of growing with every page.
+ */
+export declare const CURSOR_HISTORY_LIMIT = 1024;
+/** Why a walk ended; see `PaginationProgress.stoppedBy`. */
+export type PaginationStop = 
+/** The server said `has_more: false`: the collection is exhausted. */
+"exhausted"
+/** The caller's `maxPages` was reached; `nextCursor` continues the walk. */
+ | "max_pages";
+/**
+ * Live progress of a walk (#16246). Pass an object as `options.progress`
+ * and read it after the loop; it is updated before each page is yielded and
+ * when the walk ends. On a throw it holds the state at the failed page, the
+ * same information `paginationResumePoint(error)` returns.
+ */
+export interface PaginationProgress {
+    /** Pages fetched and yielded so far. */
+    pagesFetched?: number;
+    /** The cursor the most recent page was requested with; `undefined` for the first page. */
+    cursor?: string;
+    /**
+     * The most recent page's `next_cursor`. After `stoppedBy: "max_pages"`
+     * this is the continuation: pass it as `query.cursor` to carry on.
+     * `null` or `undefined` once the collection is exhausted.
+     */
+    nextCursor?: string | null;
+    /** Set when the walk ends without throwing. */
+    stoppedBy?: PaginationStop;
+}
 export interface PaginateOptions {
     /** Path parameters for templated list paths (e.g. `{ id }` for deliveries). */
     path?: ApiRequestOptions["path"];
     /** Initial query params (filters, `limit`, an initial `cursor`, ...). */
     query?: ListParams;
+    /** Reject query names the operation does not publish before the first request. */
+    strictQuery?: ApiRequestOptions["strictQuery"];
     /** Forwarded to each request for cooperative cancellation. */
     signal?: AbortSignal;
-    /** Hard cap on pages fetched; defaults to unbounded. */
+    /** Per-request deadline, forwarded to each page; see `ApiRequestOptions.timeoutMs`. */
+    timeoutMs?: number | null;
+    /** Retries per page, forwarded to each request; see `ApiRequestOptions.maxRetries`. */
+    maxRetries?: number;
+    /** Extra headers on every page, such as a conditional read's `If-None-Match`. */
+    headers?: Record<string, string>;
+    /**
+     * Hard cap on pages fetched. A positive integer, or `Infinity` / omitted
+     * for no cap. Anything else (`0`, negative, fractional, `NaN`) throws a
+     * `RangeError` before any request. Reaching it is a caller choice, not
+     * exhaustion: `progress.stoppedBy` reads `"max_pages"` and
+     * `progress.nextCursor` holds the continuation.
+     */
     maxPages?: number;
+    /** Updated as the walk goes; see `PaginationProgress`. */
+    progress?: PaginationProgress;
 }
+/**
+ * `PaginateOptions` bound to one list operation (#16136): `path` required
+ * exactly when the route has path parameters, `query` the documented query.
+ */
+export type OperationPaginateOptions<K extends ListOperationId> = Omit<PaginateOptions, "path" | "query"> & (OperationPath[K] extends Record<string, never> ? {
+    path?: OperationPath[K];
+} : {
+    path: OperationPath[K];
+}) & {
+    query?: OperationQuery[K];
+};
 /** Where an interrupted walk can pick up again; see `paginationResumePoint`. */
 export interface PaginationResumePoint {
     /**
@@ -32,6 +114,34 @@ export interface PaginationResumePoint {
     /** Pages already yielded before the failure. */
     pagesFetched: number;
 }
+/** What a page did that the list protocol does not allow. */
+export type PaginationErrorReason = 
+/** `has_more: true` with no usable `next_cursor` (missing, `null` or empty). */
+"missing_cursor"
+/** `next_cursor` repeats a cursor this walk already requested: a cycle. */
+ | "repeated_cursor";
+/**
+ * The server's list response broke the pagination protocol (#16246). The
+ * walk stops before yielding the page and before any further request.
+ *
+ * `page` is the response as received, so its `data` is still available to
+ * you; `cursor` is what that page was requested with (`undefined` for the
+ * first page) and `nextCursor` is what it offered next. `pagesFetched`
+ * counts the pages already yielded. `paginationResumePoint(error)` returns
+ * `{ cursor, pagesFetched }` for this error too. Retrying the same page later
+ * is reasonable for a transient server fault; a repeat on the same cursor
+ * means the route's cursor is broken and is worth reporting with
+ * `page.meta.request_id`.
+ */
+export declare class PaginationError<T = unknown> extends Error {
+    readonly reason: PaginationErrorReason;
+    readonly operationId: ApiOperationId;
+    readonly cursor: string | undefined;
+    readonly nextCursor: string | null | undefined;
+    readonly pagesFetched: number;
+    readonly page: ApiListEnvelope<T>;
+    constructor(reason: PaginationErrorReason, operationId: ApiOperationId, page: ApiListEnvelope<T>, cursor: string | undefined, pagesFetched: number);
+}
 /**
  * The resume point of an error thrown out of `paginatePages`, `paginate` or
  * `collect`, or `undefined` for any other error (#14281).
@@ -40,6 +150,7 @@ export interface PaginationResumePoint {
  * retries are exhausted the ORIGINAL error is rethrown unchanged, so an
  * `instanceof RateLimitedError` check keeps working, and this function recovers
  * the cursor that the throw would otherwise have destroyed with the generator.
+ * A `PaginationError` (#16246) is registered the same way.
  *
  * @example
  * try {
@@ -54,23 +165,30 @@ export declare function paginationResumePoint(error: unknown): PaginationResumeP
  * Async-iterate whole list pages, following `next_cursor` until exhausted.
  * Yields the full envelope so callers can read `meta`/`total`/`has_more`.
  * A failed page throws its original error; `paginationResumePoint(error)`
- * returns the cursor to continue from.
+ * returns the cursor to continue from. A page that breaks the protocol
+ * throws `PaginationError` before it is yielded (#16246).
  */
-export declare function paginatePages<T>(client: OxinsiderApiClient, operationId: ApiOperationId, options?: PaginateOptions): AsyncGenerator<ApiListEnvelope<T>, void, undefined>;
+export declare function paginatePages<K extends ListOperationId>(client: OxinsiderApiClient, operationId: K, options?: OperationPaginateOptions<K>): AsyncGenerator<OperationEnvelope<K>, void, undefined>;
+/** The untyped form: a runtime-chosen operation, or a caller-asserted `T`. */
+export declare function paginatePages<T = unknown>(client: OxinsiderApiClient, operationId: ApiOperationId, options?: PaginateOptions): AsyncGenerator<ApiListEnvelope<T>, void, undefined>;
 /**
  * Async-iterate individual `data[]` items across all pages.
  *
  * @example
- * for await (const trade of paginate<WhaleTrade>(client, "listWhaleTrades", {
+ * for await (const trade of paginate(client, "listWhaleTrades", {
  *   query: { min_grade: "S", limit: 100 },
  * })) {
- *   handle(trade);
+ *   handle(trade); // typed as the route's whale trade (#16136)
  * }
  */
-export declare function paginate<T>(client: OxinsiderApiClient, operationId: ApiOperationId, options?: PaginateOptions): AsyncGenerator<T, void, undefined>;
+export declare function paginate<K extends ListOperationId>(client: OxinsiderApiClient, operationId: K, options?: OperationPaginateOptions<K>): AsyncGenerator<OperationItem<K>, void, undefined>;
+/** The untyped form: a runtime-chosen operation, or a caller-asserted `T`. */
+export declare function paginate<T = unknown>(client: OxinsiderApiClient, operationId: ApiOperationId, options?: PaginateOptions): AsyncGenerator<T, void, undefined>;
 /**
  * Collect every item across all pages into one array. Convenience over
  * `paginate()` for small result sets; prefer the iterator for large ones.
  */
-export declare function collect<T>(client: OxinsiderApiClient, operationId: ApiOperationId, options?: PaginateOptions): Promise<T[]>;
+export declare function collect<K extends ListOperationId>(client: OxinsiderApiClient, operationId: K, options?: OperationPaginateOptions<K>): Promise<OperationItem<K>[]>;
+/** The untyped form: a runtime-chosen operation, or a caller-asserted `T`. */
+export declare function collect<T = unknown>(client: OxinsiderApiClient, operationId: ApiOperationId, options?: PaginateOptions): Promise<T[]>;
 //# sourceMappingURL=pagination.d.ts.map

package/dist/sdk/pagination.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../../../sdk/src/pagination.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,UAAU,EACV,kBAAkB,EACnB,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,eAAe;IAC9B,+EAA+E;IAC/E,IAAI,CAAC,EAAE,iBAAiB,CAAC,MAAM,CAAC,CAAC;IACjC,yEAAyE;IACzE,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,8DAA8D;IAC9D,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,gFAAgF;AAChF,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,gDAAgD;IAChD,YAAY,EAAE,MAAM,CAAC;CACtB;AAID;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,OAAO,GACb,qBAAqB,GAAG,SAAS,CAInC;AAED;;;;;GAKG;AACH,wBAAuB,aAAa,CAAC,CAAC,EACpC,MAAM,EAAE,kBAAkB,EAC1B,WAAW,EAAE,cAAc,EAC3B,OAAO,GAAE,eAAoB,GAC5B,cAAc,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC,CAsCrD;AAED;;;;;;;;;GASG;AACH,wBAAuB,QAAQ,CAAC,CAAC,EAC/B,MAAM,EAAE,kBAAkB,EAC1B,WAAW,EAAE,cAAc,EAC3B,OAAO,GAAE,eAAoB,GAC5B,cAAc,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC,CAMpC;AAED;;;GAGG;AACH,wBAAsB,OAAO,CAAC,CAAC,EAC7B,MAAM,EAAE,kBAAkB,EAC1B,WAAW,EAAE,cAAc,EAC3B,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,CAAC,EAAE,CAAC,CAMd"}
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../../../sdk/src/pagination.ts"],"names":[],"mappings":"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"}

package/dist/sdk/pagination.js

@@ -1,15 +1,77 @@
 /**
  * Cursor pagination over the Stripe-style V1 list envelope.
  *
- * Every list endpoint returns `{ object: "list", data, has_more, next_cursor }`.
- * `paginate()` yields each `data[]` item across pages, following `next_cursor`
- * while `has_more` is true. `paginatePages()` yields whole pages when you need
- * the envelope (e.g. to read `meta.cost` or `total`).
+ * Every list endpoint returns `{ object: "list", data, has_more, next_cursor }`
+ * (`backend/src/api_v1/types.rs` `ApiList`: `has_more` is always a boolean,
+ * `next_cursor` is a string or omitted). `paginate()` yields each `data[]`
+ * item across pages, following `next_cursor` while `has_more` is true.
+ * `paginatePages()` yields whole pages when you need the envelope (e.g. to
+ * read `meta.cost` or `total`).
  *
- * The loop stops on the first page where `has_more` is false OR `next_cursor`
- * is null/absent, so a buggy server that returns `has_more: true` with no
- * cursor cannot spin forever.
+ * The walker is a progress-checked consumer of that protocol (#16246):
+ *
+ * - A page is validated BEFORE it is yielded. `has_more: true` with no usable
+ *   `next_cursor` is a `PaginationError` (`missing_cursor`); the backend's own
+ *   cursor builders refuse to produce that page ("has_more is true for an
+ *   empty page", `insider_radar.rs`), so a client seeing it is looking at a
+ *   malformed response, not the end of the collection. Before #16246 the
+ *   walk returned as if the collection were exhausted.
+ * - A `next_cursor` that repeats a cursor this walk already requested is a
+ *   `PaginationError` (`repeated_cursor`), thrown before the duplicate
+ *   request. The last `CURSOR_HISTORY_LIMIT` cursors are remembered; a cycle
+ *   longer than that is not detected, which bounds memory on a long walk.
+ * - `maxPages` is validated before any request: a positive integer or
+ *   `Infinity`; `0`, a negative, fractional or `NaN` value throws `RangeError`.
+ * - `has_more: false` ends the walk normally, whatever `next_cursor` says.
+ * - A `PaginationError` carries the offending `page`, so its data is not lost,
+ *   and registers a resume point like any other failure.
+ *
+ * `options.progress`, when passed, is updated as the walk goes: how many
+ * pages were fetched, the last cursor requested, the `next_cursor` of the
+ * last page, and why the walk stopped, so a caller that stops at `maxPages`
+ * can tell "the collection has more" from "the collection is exhausted" and
+ * keep the continuation.
+ */
+/**
+ * How many requested cursors a walk remembers for the repeat check. A cycle
+ * longer than this is not detected; the bound keeps a long walk's memory
+ * flat instead of growing with every page.
  */
+export const CURSOR_HISTORY_LIMIT = 1_024;
+/**
+ * The server's list response broke the pagination protocol (#16246). The
+ * walk stops before yielding the page and before any further request.
+ *
+ * `page` is the response as received, so its `data` is still available to
+ * you; `cursor` is what that page was requested with (`undefined` for the
+ * first page) and `nextCursor` is what it offered next. `pagesFetched`
+ * counts the pages already yielded. `paginationResumePoint(error)` returns
+ * `{ cursor, pagesFetched }` for this error too. Retrying the same page later
+ * is reasonable for a transient server fault; a repeat on the same cursor
+ * means the route's cursor is broken and is worth reporting with
+ * `page.meta.request_id`.
+ */
+export class PaginationError extends Error {
+    reason;
+    operationId;
+    cursor;
+    nextCursor;
+    pagesFetched;
+    page;
+    constructor(reason, operationId, page, cursor, pagesFetched) {
+        const requestId = page.meta?.request_id;
+        super(reason === "missing_cursor"
+            ? `0xinsider API ${operationId} page ${String(pagesFetched + 1)} says has_more but carries no next_cursor${requestId ? ` (request ${requestId})` : ""}; the walk cannot continue safely`
+            : `0xinsider API ${operationId} page ${String(pagesFetched + 1)} offers next_cursor ${JSON.stringify(page.next_cursor)}, which this walk already requested${requestId ? ` (request ${requestId})` : ""}; stopping before the duplicate request`);
+        this.name = "PaginationError";
+        this.reason = reason;
+        this.operationId = operationId;
+        this.cursor = cursor;
+        this.nextCursor = page.next_cursor;
+        this.pagesFetched = pagesFetched;
+        this.page = page;
+    }
+}
 const resumePoints = new WeakMap();
 /**
  * The resume point of an error thrown out of `paginatePages`, `paginate` or
@@ -19,6 +81,7 @@ const resumePoints = new WeakMap();
  * retries are exhausted the ORIGINAL error is rethrown unchanged, so an
  * `instanceof RateLimitedError` check keeps working, and this function recovers
  * the cursor that the throw would otherwise have destroyed with the generator.
+ * A `PaginationError` (#16246) is registered the same way.
  *
  * @example
  * try {
@@ -33,58 +96,97 @@ export function paginationResumePoint(error) {
         ? resumePoints.get(error)
         : undefined;
 }
-/**
- * Async-iterate whole list pages, following `next_cursor` until exhausted.
- * Yields the full envelope so callers can read `meta`/`total`/`has_more`.
- * A failed page throws its original error; `paginationResumePoint(error)`
- * returns the cursor to continue from.
- */
+function assertMaxPages(value) {
+    if (value === undefined || value === Infinity)
+        return Infinity;
+    if (!Number.isInteger(value) || value < 1) {
+        throw new RangeError(`maxPages must be a positive integer or Infinity, got ${String(value)}`);
+    }
+    return value;
+}
+/** A `next_cursor` the walk can request: a non-empty string. */
+function usableCursor(value) {
+    return typeof value === "string" && value !== "";
+}
 export async function* paginatePages(client, operationId, options = {}) {
-    const { path, query, signal, maxPages } = options;
+    const { path, query, strictQuery, signal, progress, timeoutMs, maxRetries, headers } = options;
+    const maxPages = assertMaxPages(options.maxPages);
     let cursor = query?.cursor;
     let pages = 0;
+    // Every cursor requested so far, newest last, capped at CURSOR_HISTORY_LIMIT.
+    const requested = new Set();
+    const requestedOrder = [];
+    const remember = (value) => {
+        if (requested.has(value))
+            return;
+        requested.add(value);
+        requestedOrder.push(value);
+        if (requestedOrder.length > CURSOR_HISTORY_LIMIT) {
+            const oldest = requestedOrder.shift();
+            if (oldest !== undefined)
+                requested.delete(oldest);
+        }
+    };
+    const record = (fields) => {
+        if (progress)
+            Object.assign(progress, fields);
+    };
+    const fail = (error) => {
+        if (!resumePoints.has(error)) {
+            resumePoints.set(error, { cursor, pagesFetched: pages });
+        }
+        return error;
+    };
     for (;;) {
         if (signal?.aborted) {
             throw signal.reason instanceof Error
                 ? signal.reason
                 : new DOMException("The pagination was aborted", "AbortError");
         }
+        if (cursor !== undefined)
+            remember(cursor);
         let page;
         try {
             page = await client.list(operationId, {
                 path,
                 query: { ...query, ...(cursor === undefined ? {} : { cursor }) },
+                strictQuery,
                 signal,
+                ...(timeoutMs === undefined ? {} : { timeoutMs }),
+                ...(maxRetries === undefined ? {} : { maxRetries }),
+                ...(headers === undefined ? {} : { headers }),
             });
         }
         catch (error) {
-            if (typeof error === "object" && error !== null && !resumePoints.has(error)) {
-                resumePoints.set(error, { cursor, pagesFetched: pages });
-            }
+            if (typeof error === "object" && error !== null)
+                fail(error);
             throw error;
         }
+        record({ pagesFetched: pages, cursor, nextCursor: page.next_cursor });
+        const next = page.next_cursor;
+        if (page.has_more) {
+            if (!usableCursor(next)) {
+                throw fail(new PaginationError("missing_cursor", operationId, page, cursor, pages));
+            }
+            if (requested.has(next)) {
+                throw fail(new PaginationError("repeated_cursor", operationId, page, cursor, pages));
+            }
+        }
         yield page;
         pages += 1;
-        const next = page.next_cursor;
-        if (!page.has_more || next === null || next === undefined || next === "") {
+        record({ pagesFetched: pages, cursor, nextCursor: next });
+        if (!page.has_more) {
+            record({ pagesFetched: pages, cursor, nextCursor: next, stoppedBy: "exhausted" });
             return;
         }
-        if (maxPages !== undefined && pages >= maxPages) {
+        if (pages >= maxPages) {
+            record({ pagesFetched: pages, cursor, nextCursor: next, stoppedBy: "max_pages" });
             return;
         }
+        // `has_more` was true and `next` passed both checks above.
         cursor = next;
     }
 }
-/**
- * Async-iterate individual `data[]` items across all pages.
- *
- * @example
- * for await (const trade of paginate<WhaleTrade>(client, "listWhaleTrades", {
- *   query: { min_grade: "S", limit: 100 },
- * })) {
- *   handle(trade);
- * }
- */
 export async function* paginate(client, operationId, options = {}) {
     for await (const page of paginatePages(client, operationId, options)) {
         for (const item of page.data) {
@@ -92,10 +194,6 @@ export async function* paginate(client, operationId, options = {}) {
         }
     }
 }
-/**
- * Collect every item across all pages into one array. Convenience over
- * `paginate()` for small result sets; prefer the iterator for large ones.
- */
 export async function collect(client, operationId, options = {}) {
     const items = [];
     for await (const item of paginate(client, operationId, options)) {

package/dist/sdk/pagination.js.map

@@ -1 +1 @@
-{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../../../sdk/src/pagination.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../../../sdk/src/pagination.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAcH;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,KAAK,CAAC;AAwF1C;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,eAA6B,SAAQ,KAAK;IAC5C,MAAM,CAAwB;IAC9B,WAAW,CAAiB;IAC5B,MAAM,CAAqB;IAC3B,UAAU,CAA4B;IACtC,YAAY,CAAS;IACrB,IAAI,CAAqB;IAElC,YACE,MAA6B,EAC7B,WAA2B,EAC3B,IAAwB,EACxB,MAA0B,EAC1B,YAAoB;QAEpB,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC;QACxC,KAAK,CACH,MAAM,KAAK,gBAAgB;YACzB,CAAC,CAAC,iBAAiB,WAAW,SAAS,MAAM,CAAC,YAAY,GAAG,CAAC,CAAC,4CAA4C,SAAS,CAAC,CAAC,CAAC,aAAa,SAAS,GAAG,CAAC,CAAC,CAAC,EAAE,mCAAmC;YACxL,CAAC,CAAC,iBAAiB,WAAW,SAAS,MAAM,CAAC,YAAY,GAAG,CAAC,CAAC,uBAAuB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,WAAW,CAAC,sCAAsC,SAAS,CAAC,CAAC,CAAC,aAAa,SAAS,GAAG,CAAC,CAAC,CAAC,EAAE,yCAAyC,CAClP,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,WAAW,CAAC;QACnC,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;QACjC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED,MAAM,YAAY,GAAG,IAAI,OAAO,EAAiC,CAAC;AAElE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,qBAAqB,CACnC,KAAc;IAEd,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAChD,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC;QACzB,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC;AAED,SAAS,cAAc,CAAC,KAAyB;IAC/C,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC/D,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,UAAU,CAClB,wDAAwD,MAAM,CAAC,KAAK,CAAC,EAAE,CACxE,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,gEAAgE;AAChE,SAAS,YAAY,CAAC,KAAgC;IACpD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,EAAE,CAAC;AACnD,CAAC;AAoBD,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,aAAa,CAClC,MAA0B,EAC1B,WAA2B,EAC3B,OAAO,GAAoB,EAAE;IAE7B,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IAC/F,MAAM,QAAQ,GAAG,cAAc,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAClD,IAAI,MAAM,GAAuB,KAAK,EAAE,MAAM,CAAC;IAC/C,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,8EAA8E;IAC9E,MAAM,SAAS,GAAG,IAAI,GAAG,EAAU,CAAC;IACpC,MAAM,cAAc,GAAa,EAAE,CAAC;IACpC,MAAM,QAAQ,GAAG,CAAC,KAAa,EAAE,EAAE;QACjC,IAAI,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC;YAAE,OAAO;QACjC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACrB,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC3B,IAAI,cAAc,CAAC,MAAM,GAAG,oBAAoB,EAAE,CAAC;YACjD,MAAM,MAAM,GAAG,cAAc,CAAC,KAAK,EAAE,CAAC;YACtC,IAAI,MAAM,KAAK,SAAS;gBAAE,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACrD,CAAC;IACH,CAAC,CAAC;IACF,MAAM,MAAM,GAAG,CACb,MACgD,EAChD,EAAE;QACF,IAAI,QAAQ;YAAE,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAChD,CAAC,CAAC;IACF,MAAM,IAAI,GAAG,CAAC,KAAa,EAAE,EAAE;QAC7B,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YAC7B,YAAY,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC,CAAC;QAC3D,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;IAEF,SAAS,CAAC;QACR,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;YACpB,MAAM,MAAM,CAAC,MAAM,YAAY,KAAK;gBAClC,CAAC,CAAC,MAAM,CAAC,MAAM;gBACf,CAAC,CAAC,IAAI,YAAY,CAAC,4BAA4B,EAAE,YAAY,CAAC,CAAC;QACnE,CAAC;QACD,IAAI,MAAM,KAAK,SAAS;YAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;QAE3C,IAAI,IAA8B,CAAC;QACnC,IAAI,CAAC;YACH,IAAI,GAAG,MAAM,MAAM,CAAC,IAAI,CAAU,WAAW,EAAE;gBAC7C,IAAI;gBACJ,KAAK,EAAE,EAAE,GAAG,KAAK,EAAE,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE;gBAChE,WAAW;gBACX,MAAM;gBACN,GAAG,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC;gBACjD,GAAG,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC;gBACnD,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC;aAC9C,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;gBAAE,IAAI,CAAC,KAAK,CAAC,CAAC;YAC7D,MAAM,KAAK,CAAC;QACd,CAAC;QAED,MAAM,CAAC,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;QACtE,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC;QAC9B,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC;gBACxB,MAAM,IAAI,CAAC,IAAI,eAAe,CAAC,gBAAgB,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC;YACtF,CAAC;YACD,IAAI,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBACxB,MAAM,IAAI,CAAC,IAAI,eAAe,CAAC,iBAAiB,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC;YACvF,CAAC;QACH,CAAC;QAED,MAAM,IAAI,CAAC;QACX,KAAK,IAAI,CAAC,CAAC;QACX,MAAM,CAAC,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC;QAE1D,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnB,MAAM,CAAC,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,CAAC,CAAC;YAClF,OAAO;QACT,CAAC;QACD,IAAI,KAAK,IAAI,QAAQ,EAAE,CAAC;YACtB,MAAM,CAAC,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,CAAC,CAAC;YAClF,OAAO;QACT,CAAC;QACD,2DAA2D;QAC3D,MAAM,GAAG,IAAc,CAAC;IAC1B,CAAC;AACH,CAAC;AAuBD,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,QAAQ,CAC7B,MAA0B,EAC1B,WAA2B,EAC3B,OAAO,GAAoB,EAAE;IAE7B,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,aAAa,CAAU,MAAM,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,CAAC;QAC9E,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YAC7B,MAAM,IAAI,CAAC;QACb,CAAC;IACH,CAAC;AACH,CAAC;AAiBD,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,MAA0B,EAC1B,WAA2B,EAC3B,OAAO,GAAoB,EAAE;IAE7B,MAAM,KAAK,GAAc,EAAE,CAAC;IAC5B,IAAI,KAAK,EAAE,MAAM,IAAI,IAAI,QAAQ,CAAU,MAAM,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,CAAC;QACzE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnB,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/sdk/retry.d.ts

@@ -0,0 +1,68 @@
+/**
+ * `Retry-After` parsing and the waits it drives, shared by the REST retry
+ * loop (`client.ts`) and the SSE reconnect loop (`stream.ts`) so the two
+ * cannot read the same header differently (#16249).
+ *
+ * Two facts shape this module:
+ *
+ * 1. `Retry-After` is either delta-seconds or an HTTP-date (RFC 9110 §10.2.3,
+ *    https://www.rfc-editor.org/rfc/rfc9110.html#name-retry-after). Both
+ *    loops parsed only the number and treated a date as "no header".
+ * 2. Node schedules a `setTimeout` delay above 2147483647 ms (about 24.8 days)
+ *    as 1 ms, with a warning
+ *    (https://nodejs.org/api/timers.html#settimeoutcallback-delay-args). The
+ *    stream loop multiplied any `Retry-After` by 1000 and handed it straight
+ *    to the timer, so a long server-requested wait -- `monthly_quota_exceeded`
+ *    names the first of next month -- would have reconnected at once, the
+ *    opposite of what the server asked.
+ *
+ * The policy is therefore: parse both forms into a non-negative number of
+ * seconds; never wait in-process past a ceiling the caller can see (60 s by
+ * default, the same for REST and SSE); when the server asks for longer, hand
+ * the caller a typed error carrying the not-before instant and the resume
+ * context, never a clamped earlier retry; and when a caller opts into waiting
+ * longer, wait in timer-sized chunks so the timer range is never exceeded.
+ */
+/**
+ * The largest delay one `setTimeout` can hold in Node (2^31 - 1 ms). A larger
+ * value is scheduled as 1 ms, so every wait here is cut into chunks of at
+ * most this size.
+ */
+export declare const MAX_TIMER_DELAY_MS = 2147483647;
+/**
+ * The longest server-requested wait either loop holds in-process by default.
+ * A `Retry-After` beyond it is the caller's to schedule: the REST loop throws
+ * the response's error (`retryAfterSeconds`, `retryAt`), the stream loop
+ * throws `StreamRetryDeferredError`.
+ */
+export declare const RETRY_AFTER_CEILING_MS = 60000;
+/**
+ * Parse a `Retry-After` header value into seconds to wait, or `null` when
+ * there is no usable value.
+ *
+ * - Delta-seconds: a finite, non-negative number (`"60"`, `"1.5"`). A negative
+ *   or non-finite number (`"-1"`, `"Infinity"`, `"NaN"`) is `null`: the
+ *   grammar does not allow it, and guessing a wait from it would be inventing
+ *   a server instruction.
+ * - HTTP-date (`"Wed, 01 Oct 2026 00:00:00 GMT"`): the seconds from `nowMs`
+ *   to that instant. A date already past is `0` (the server said "after an
+ *   instant that has passed", which is "now"), never negative.
+ * - Anything else (`""`, `"soon"`) is `null`.
+ *
+ * `null` means "as if the header were absent": the caller falls back to its
+ * own backoff. It never means "retry at once".
+ */
+export declare function parseRetryAfter(header: string | null | undefined, nowMs?: number): number | null;
+/** `parseRetryAfter` over a response's `Retry-After` header. */
+export declare function retryAfterSeconds(response: Response): number | null;
+/**
+ * Resolve after `ms`, or reject with the signal's reason the moment it
+ * aborts. A wait longer than `MAX_TIMER_DELAY_MS` runs as consecutive timers
+ * of at most that size, so it is never handed to `setTimeout` as one value
+ * that Node would schedule as 1 ms. `ms` must be a non-negative number;
+ * `Infinity` is refused because it can never elapse.
+ */
+export declare function sleepUnlessAborted(ms: number, signal: AbortSignal | undefined): Promise<void>;
+/** Resolve `true` after `ms`, or `false` the moment `signal` aborts. */
+export declare function waitUnlessAborted(ms: number, signal: AbortSignal | undefined): Promise<boolean>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/sdk/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../../sdk/src/retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,aAAgB,CAAC;AAEhD;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,QAAS,CAAC;AAE7C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACjC,KAAK,GAAE,MAAmB,GACzB,MAAM,GAAG,IAAI,CAaf;AAED,gEAAgE;AAChE,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,GAAG,IAAI,CAEnE;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,WAAW,GAAG,SAAS,GAC9B,OAAO,CAAC,IAAI,CAAC,CAaf;AAED,wEAAwE;AACxE,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,WAAW,GAAG,SAAS,GAC9B,OAAO,CAAC,OAAO,CAAC,CAQlB"}