@0xinsider/mcp 1.3.1 → 2.0.0

package/dist/sdk/pagination.d.ts

@@ -0,0 +1,76 @@
+/**
+ * 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`).
+ *
+ * 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.
+ */
+import type { ApiListEnvelope, ApiOperationId, ApiRequestOptions, ListParams, OxinsiderApiClient } from "./client.js";
+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;
+    /** Forwarded to each request for cooperative cancellation. */
+    signal?: AbortSignal;
+    /** Hard cap on pages fetched; defaults to unbounded. */
+    maxPages?: number;
+}
+/** Where an interrupted walk can pick up again; see `paginationResumePoint`. */
+export interface PaginationResumePoint {
+    /**
+     * The cursor of the page that failed. Pass it back as `query.cursor` to
+     * refetch that page and continue. `undefined` means the first page failed,
+     * so start the walk again without a cursor.
+     */
+    cursor: string | undefined;
+    /** Pages already yielded before the failure. */
+    pagesFetched: number;
+}
+/**
+ * The resume point of an error thrown out of `paginatePages`, `paginate` or
+ * `collect`, or `undefined` for any other error (#14281).
+ *
+ * Each page request already retries a 429 or 5xx (`maxRetries`). When those
+ * 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.
+ *
+ * @example
+ * try {
+ *   for await (const trade of paginate(client, "listWhaleTrades", { query })) handle(trade);
+ * } catch (err) {
+ *   const resume = paginationResumePoint(err);
+ *   if (resume) later(() => paginate(client, "listWhaleTrades", { query: { ...query, cursor: resume.cursor } }));
+ * }
+ */
+export declare function paginationResumePoint(error: unknown): PaginationResumePoint | 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.
+ */
+export declare function paginatePages<T>(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", {
+ *   query: { min_grade: "S", limit: 100 },
+ * })) {
+ *   handle(trade);
+ * }
+ */
+export declare function paginate<T>(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[]>;
+//# sourceMappingURL=pagination.d.ts.map

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

@@ -0,0 +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"}

package/dist/sdk/pagination.js

@@ -0,0 +1,106 @@
+/**
+ * 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`).
+ *
+ * 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.
+ */
+const resumePoints = new WeakMap();
+/**
+ * The resume point of an error thrown out of `paginatePages`, `paginate` or
+ * `collect`, or `undefined` for any other error (#14281).
+ *
+ * Each page request already retries a 429 or 5xx (`maxRetries`). When those
+ * 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.
+ *
+ * @example
+ * try {
+ *   for await (const trade of paginate(client, "listWhaleTrades", { query })) handle(trade);
+ * } catch (err) {
+ *   const resume = paginationResumePoint(err);
+ *   if (resume) later(() => paginate(client, "listWhaleTrades", { query: { ...query, cursor: resume.cursor } }));
+ * }
+ */
+export function paginationResumePoint(error) {
+    return typeof error === "object" && error !== null
+        ? 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.
+ */
+export async function* paginatePages(client, operationId, options = {}) {
+    const { path, query, signal, maxPages } = options;
+    let cursor = query?.cursor;
+    let pages = 0;
+    for (;;) {
+        if (signal?.aborted) {
+            throw signal.reason instanceof Error
+                ? signal.reason
+                : new DOMException("The pagination was aborted", "AbortError");
+        }
+        let page;
+        try {
+            page = await client.list(operationId, {
+                path,
+                query: { ...query, ...(cursor === undefined ? {} : { cursor }) },
+                signal,
+            });
+        }
+        catch (error) {
+            if (typeof error === "object" && error !== null && !resumePoints.has(error)) {
+                resumePoints.set(error, { cursor, pagesFetched: pages });
+            }
+            throw error;
+        }
+        yield page;
+        pages += 1;
+        const next = page.next_cursor;
+        if (!page.has_more || next === null || next === undefined || next === "") {
+            return;
+        }
+        if (maxPages !== undefined && pages >= maxPages) {
+            return;
+        }
+        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) {
+            yield item;
+        }
+    }
+}
+/**
+ * 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)) {
+        items.push(item);
+    }
+    return items;
+}
+//# sourceMappingURL=pagination.js.map

package/dist/sdk/pagination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../../../sdk/src/pagination.ts"],"names":[],"mappings":"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"}