@spaceinvoices/js-sdk 10.1.4 → 10.2.0

package/dist/paginate.d.cts

@@ -0,0 +1,56 @@
+/**
+ * Guarded "fetch all pages" helper for SDK list methods.
+ *
+ * Every generated list method (`sdk.invoices.list`, `sdk.expenses.list`, ...) returns one page
+ * at a time. Hand-rolling a `while (has_more) fetch(next_cursor)` loop around it is easy to get
+ * subtly wrong - a stale or misspelled cursor parameter means the loop never advances, which is
+ * what sent a customer's hand-rolled loop into an 18+ hour, ~565,000-request outage against
+ * production on 2026-09-18.
+ *
+ * `listAll()` walks every page of a list method for you and yields one item at a time:
+ *
+ * ```ts
+ * for await (const item of listAll(sdk.invoices.list, { limit: 100 })) {
+ *   console.log(item.id);
+ * }
+ * ```
+ *
+ * It is a standalone function rather than a method on the list function itself (e.g. NOT
+ * `sdk.invoices.list.listAll(...)`) because it is hand-written, not generated - see
+ * `packages/js-sdk/scripts/generate-sdk.ts` for why the equivalent generator-based approach was
+ * reverted (a generated `utils.ts` change and a `generate-sdk.ts`-only change can't both satisfy
+ * the release guard's file classification in one bounded change).
+ *
+ * `options` (including any scoping like `entity_id`/`account_id`) is re-sent on every page
+ * request, not only the first - dropping it after page one would silently cross-scope later
+ * pages to the wrong entity/account.
+ *
+ * Three guards, all of which throw a distinguishable error instead of ever silently returning a
+ * partial result labelled as complete:
+ * - a page-count safety limit (`MAX_LIST_ALL_PAGES`)
+ * - a non-advancing cursor (the API returning the same `next_cursor` it was just given - the
+ *   exact failure shape behind the 2026-09-18 incident)
+ * - a response with no pagination envelope: either a bare array, or an object whose `data` is an
+ *   array but which has no `pagination` object at all (e.g. `{ data, has_more }` instead of
+ *   `{ data, pagination: { next_cursor } }`). Both shapes mean the endpoint does not support
+ *   cursor-based pagination the way `listAll()` expects; treating either as "one page, done"
+ *   would silently truncate a real, larger result set.
+ */
+/** Safety limit: maximum pages fetched before `listAll()` fails closed instead of looping forever. */
+export declare const MAX_LIST_ALL_PAGES = 1000;
+type ListItemOf<TMethod> = TMethod extends (options?: any) => Promise<infer R> ? R extends {
+    data: (infer Item)[];
+} ? Item : never : never;
+/**
+ * Iterate every page of a list method, yielding one item at a time until the API reports no
+ * further pages (`pagination.next_cursor` is null/absent).
+ *
+ * @param method A wrapped SDK list method, e.g. `sdk.invoices.list` or the module-level
+ *   `invoices.list` from `@spaceinvoices/js-sdk/sdk`.
+ * @param options Forwarded on every page request (with `next_cursor` overridden per page).
+ * @param label Optional human-readable name for this method, used only to make thrown errors
+ *   easier to trace back to a call site; omit it and the error still identifies the failure
+ *   mode, just not the endpoint name (see the exported errors' messages).
+ */
+export declare function listAll<TMethod extends (options?: any) => Promise<any>>(method: TMethod, options?: Parameters<TMethod>[0], label?: string): AsyncGenerator<ListItemOf<TMethod>, void, undefined>;
+export {};

package/dist/paginate.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Guarded "fetch all pages" helper for SDK list methods.
+ *
+ * Every generated list method (`sdk.invoices.list`, `sdk.expenses.list`, ...) returns one page
+ * at a time. Hand-rolling a `while (has_more) fetch(next_cursor)` loop around it is easy to get
+ * subtly wrong - a stale or misspelled cursor parameter means the loop never advances, which is
+ * what sent a customer's hand-rolled loop into an 18+ hour, ~565,000-request outage against
+ * production on 2026-09-18.
+ *
+ * `listAll()` walks every page of a list method for you and yields one item at a time:
+ *
+ * ```ts
+ * for await (const item of listAll(sdk.invoices.list, { limit: 100 })) {
+ *   console.log(item.id);
+ * }
+ * ```
+ *
+ * It is a standalone function rather than a method on the list function itself (e.g. NOT
+ * `sdk.invoices.list.listAll(...)`) because it is hand-written, not generated - see
+ * `packages/js-sdk/scripts/generate-sdk.ts` for why the equivalent generator-based approach was
+ * reverted (a generated `utils.ts` change and a `generate-sdk.ts`-only change can't both satisfy
+ * the release guard's file classification in one bounded change).
+ *
+ * `options` (including any scoping like `entity_id`/`account_id`) is re-sent on every page
+ * request, not only the first - dropping it after page one would silently cross-scope later
+ * pages to the wrong entity/account.
+ *
+ * Three guards, all of which throw a distinguishable error instead of ever silently returning a
+ * partial result labelled as complete:
+ * - a page-count safety limit (`MAX_LIST_ALL_PAGES`)
+ * - a non-advancing cursor (the API returning the same `next_cursor` it was just given - the
+ *   exact failure shape behind the 2026-09-18 incident)
+ * - a response with no pagination envelope: either a bare array, or an object whose `data` is an
+ *   array but which has no `pagination` object at all (e.g. `{ data, has_more }` instead of
+ *   `{ data, pagination: { next_cursor } }`). Both shapes mean the endpoint does not support
+ *   cursor-based pagination the way `listAll()` expects; treating either as "one page, done"
+ *   would silently truncate a real, larger result set.
+ */
+/** Safety limit: maximum pages fetched before `listAll()` fails closed instead of looping forever. */
+export declare const MAX_LIST_ALL_PAGES = 1000;
+type ListItemOf<TMethod> = TMethod extends (options?: any) => Promise<infer R> ? R extends {
+    data: (infer Item)[];
+} ? Item : never : never;
+/**
+ * Iterate every page of a list method, yielding one item at a time until the API reports no
+ * further pages (`pagination.next_cursor` is null/absent).
+ *
+ * @param method A wrapped SDK list method, e.g. `sdk.invoices.list` or the module-level
+ *   `invoices.list` from `@spaceinvoices/js-sdk/sdk`.
+ * @param options Forwarded on every page request (with `next_cursor` overridden per page).
+ * @param label Optional human-readable name for this method, used only to make thrown errors
+ *   easier to trace back to a call site; omit it and the error still identifies the failure
+ *   mode, just not the endpoint name (see the exported errors' messages).
+ */
+export declare function listAll<TMethod extends (options?: any) => Promise<any>>(method: TMethod, options?: Parameters<TMethod>[0], label?: string): AsyncGenerator<ListItemOf<TMethod>, void, undefined>;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spaceinvoices/js-sdk",
-  "version": "10.1.4",
+  "version": "10.2.0",
   "description": "Official JavaScript/TypeScript SDK for the Space Invoices API",
   "author": "Space Invoices <support@spaceinvoices.com>",
   "license": "MIT",