@pipelex/sdk 0.48.1 → 0.49.0

package/README.md

@@ -167,6 +167,14 @@ for await (const saved of client.iterateMethodExamples(created.method_id)) {
   // every example, oldest first
 }
 
+// The organization's files, newest first: uploads, test files and the files runs made. Each row's
+// `uri` goes into a run's inputs as any address does. A filtered page can be empty and still carry
+// a nextCursor; iterateFiles follows it.
+const files = await client.listFiles({ q: "invoice", kind: "uploaded", format: ["pdf"] });
+await client.start({ method_id: created.method_id, inputs: { invoice: { url: files.items[0]!.uri } } });
+// An upload recorded as a test file of the method it was made to try.
+await client.uploadFile("cases/receipt.pdf", { kind: "test", method_id: created.method_id });
+
 try {
   const { portal_url } = await client.getBillingPortal();
   // open portal_url ...
@@ -255,7 +263,9 @@ These pages ship inside the published package, so a reader who has only installe
 | [`docs/artifact-download.md`](./docs/artifact-download.md) | Turning the `pipelex-storage://` references a run produced back into bytes: `locateArtifacts`, `collectArtifacts`, `resolveArtifacts`, `fetchArtifact`, `downloadArtifacts`, and how a saved file is named after the field it fills |
 | [`docs/input-preparation.md`](./docs/input-preparation.md) | The other direction — `uploadFile` and `prepareInputs`, which turn local files into references a run can take, and the upload grant a browser page sends a file with |
 | [`docs/method-trees.md`](./docs/method-trees.md) | A method's tree: the four forms a run, a validation, a save and the crate routes take it in (a directory on disk among them), how it travels inline or by hash and what is uploaded, the files a step reads, the template check's warnings and which step reads which file of the tree, the deployment's limits, the read's listing with its links, `writeMethodTree`, and `MethodFileTransferError` |
+| [`docs/files.md`](./docs/files.md) | An organization's files: `listFiles` and `iterateFiles`, the row and its provenance, the query and its repeated filters, paging through filtered pages, and an upload recorded as a method's test file with the refusals that come with it |
 | [`docs/method-examples.md`](./docs/method-examples.md) | A method's saved examples: the create, the paged list and its iterator, the edit that raises the input revision, the latest-run write and its `recorded` or `stale` verdict, how an integer past `Number.MAX_SAFE_INTEGER` in the inputs stays exact, and what is refused before sending |
+| [`docs/organization-branding.md`](./docs/organization-branding.md) | An organization's logos and colours: `getBranding`, which every member and API key reads, `updateOrganizationBranding`, an admin's write that sets, clears or keeps each key, and how a refused logo or colour names its slot in `errors` so a settings screen shows the sentence under it |
 | [`docs/exact-integers.md`](./docs/exact-integers.md) | Which reads keep an integer past `Number.MAX_SAFE_INTEGER` exact, as a `bigint` (a run's inputs and outputs, an example's inputs), how a request body writes it back with its digits, and `parseExactJson` and `stringifyExactJson` for code showing such data as JSON text |
 | [`docs/crate-routes.md`](./docs/crate-routes.md) | `resolve`, `codegen` and `pipeIo` — the method's tree as the protocol's `files` map, with its dependencies, the normalized crate, the stamped types, and a method's I/O artifacts without a validation — and the offline `runCodegenCheck` that guards a committed tree |
 | [`docs/client-identification.md`](./docs/client-identification.md) | The `User-Agent` every API request carries, and `appInfo`, the option that puts your program's name in front of it |

package/dist/cli/script.d.ts

@@ -15,7 +15,7 @@ import type { CommandIO } from "./io.js";
  * update notice and npm 12's run notices off the script's stderr, which carries the command's
  * own lines, while npm's warnings and errors still print.
  */
-export declare const SCRIPT_RUNNER = "npx --yes --no-update-notifier --loglevel=warn @pipelex/sdk@0.48.1";
+export declare const SCRIPT_RUNNER = "npx --yes --no-update-notifier --loglevel=warn @pipelex/sdk@0.49.0";
 export declare const SCRIPT_WRITER = "@pipelex/sdk";
 export declare const SCRIPT_NEEDS = "Node 22.12 or later";
 /** Run `pipelex-sdk script` and return its exit code. */

package/dist/client.d.ts

@@ -1,7 +1,7 @@
 import type { MTHDSProtocol, ModelCategory, ModelDeck, RunOptions, StartOptions, VersionInfo } from "mthds/protocol";
 import type { CodegenRequest, CodegenResponse, CrateRouteOptions, DictPipeOutput, FormatResponse, LintResponse, ModelCheckCategory, ModelReferenceVerdict, PipeIORequest, PipeIOResponse, PipelexRunResultStart, PipelexValidateSource, PipelexValidationResult, ResolveRequest, ResolveResponse, ValidateMethodSelector } from "./models.js";
 import { type GetRunResultOptions, type RunProgress, type RunRead, type RunResults, type RunResultState, type StartAndWaitForResultOptions, type WaitForResultOptions } from "./runs.js";
-import type { BillingPortalResponse, ChangePlanResponse, CheckoutResponse, InvoiceView, Membership, MembershipsResponse, ListMethodExamplesQuery, ListMethodsQuery, ListMethodVersionsQuery, MethodData, MethodDeletionAccepted, MethodDetail, MethodDraftInput, MethodExample, MethodExampleCreateInput, MethodExampleLatestRunInput, MethodExampleLatestRunResult, MethodExamplePage, MethodExampleUpdateInput, MethodPage, MethodPublishInput, MethodPublishResult, MethodRenameInput, MethodSummary, MethodVersion, MethodVersionPage, MethodWriteInput, OnboardingSubmission, PipelexApiKeyCreated, PipelexApiKeyList, ListRunsQuery, RunHistoryItem, RunDetail, RunPage, PlanView, ResolvedStorageUrl, SavedMethodFile, SubscriptionResponse, UpdateRunInput, UploadGrant, UploadGrantInput, UploadInput, UploadedFile, UserProfile } from "./product-models.js";
+import type { BillingPortalResponse, ChangePlanResponse, CheckoutResponse, FilePage, FileSummary, InvoiceView, Membership, MembershipsResponse, OrganizationBranding, OrganizationBrandingUpdate, ListFilesQuery, ListMethodExamplesQuery, ListMethodsQuery, ListMethodVersionsQuery, MethodData, MethodDeletionAccepted, MethodDetail, MethodDraftInput, MethodExample, MethodExampleCreateInput, MethodExampleLatestRunInput, MethodExampleLatestRunResult, MethodExamplePage, MethodExampleUpdateInput, MethodPage, MethodPublishInput, MethodPublishResult, MethodRenameInput, MethodSummary, MethodVersion, MethodVersionPage, MethodWriteInput, OnboardingSubmission, PipelexApiKeyCreated, PipelexApiKeyList, ListRunsQuery, RunHistoryItem, RunDetail, RunPage, PlanView, ResolvedStorageUrl, SavedMethodFile, SubscriptionResponse, UpdateRunInput, UploadGrant, UploadGrantInput, UploadInput, UploadedFile, UserProfile } from "./product-models.js";
 import type { MethodTreeForms, MethodTreeLimits } from "./method-trees.js";
 import type { AppInfo } from "./user-agent.js";
 import type { UploadableAsset, UploadFileOptions, UploadRecord } from "./upload.js";
@@ -279,7 +279,7 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
     private readVerdict;
     /**
      * One page of a cursor-paged product route (`listMethods`, `listMethodVersions`,
-     * `listMethodExamples`, `listRuns`), read as the platform always serializes it: `items` an
+     * `listMethodExamples`, `listRuns`, `listFiles`), read as the platform always serializes it: `items` an
      * array, `next_cursor` a string or `null`. A page breaking either is an answer the SDK cannot
      * read, so it throws the `ApiResponseError` `unreadableAnswer` builds, `runtime` and not
      * retryable, rather than handing the iterators a page they cannot walk: `items` that is not
@@ -1362,6 +1362,42 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
     renameOrganization(orgId: string, input: {
         name: string;
     }): Promise<Membership>;
+    /**
+     * The branding of the caller's active organization — `GET /v1/branding`: its name, its light
+     * and dark colour sets and its two logos. Any role reads it, `runner` included, by web session
+     * or API key, so an app scaffolded from the method-app template reads its organization's
+     * branding with its own key. A personal workspace, or a team that set nothing, answers every
+     * colour and logo `null`. A logo's `uri` is a `pipelex-storage://` reference, which
+     * `resolveStorageUrl` turns into a short-lived link to its bytes.
+     *
+     * Throws `ApiResponseError`: `400` when the caller has no active organization, `404` when its
+     * row is missing, and an answer that is not a JSON object, an empty one included.
+     */
+    getBranding(): Promise<OrganizationBranding>;
+    /**
+     * Set or clear an organization's branding — `PATCH /v1/organizations/{org_id}/branding`, an
+     * admin's write to the active organization. Every key of `input` is optional: a value sets it,
+     * `null` clears it, and a key left out keeps its value (`OrganizationBrandingUpdate`), so `{}`
+     * writes nothing. A new logo is the `pipelex-storage://` URI of a file the organization uploaded
+     * on its own, which the platform reads and measures, then copies under `branding/`: the answer's
+     * `uri` is that copy, and sending it back unchanged keeps the logo. The logo a write replaces or
+     * clears is erased. Answers the branding as the write left it.
+     *
+     * Throws `RequestArgumentError` for an organization id that is empty, `.` or `..`, before any
+     * request. Throws `ApiResponseError`, refusing every change of the request when it refuses one:
+     * `403` `forbidden` when `orgId` is not the active organization, `403` `role_not_permitted` for
+     * a caller who is not its admin, `404` for a missing organization, `409` `conflict` for a
+     * personal workspace, which has no branding, and `422` `validation_failed` for a colour that is
+     * not `#rrggbb` or a key the body does not know. A logo's refusal names its slot in the error's
+     * `errors[]`, each entry's `field` being `square_logo` or `wide_logo` and its `detail` the
+     * sentence to show under that slot: `400` `invalid_storage_uri` for a URI that is not a storage
+     * URI, `403` `forbidden` for another organization's file, and `422` `validation_failed` with a
+     * `LogoRefusalCode` per broken rule for a file the platform refused. A failure of the platform's
+     * storage while reading or copying a logo is a `500` `storage_backend_failed`, retryable, with
+     * nothing written. A `503` `service_unavailable` is a failure of its database, after which the
+     * write may have landed or not: the same input sent again is safe.
+     */
+    updateOrganizationBranding(orgId: string, input: OrganizationBrandingUpdate): Promise<OrganizationBranding>;
     /** The active org's subscription state — `GET /v1/billing/subscription`. */
     getSubscription(): Promise<SubscriptionResponse>;
     /** Available plans (with `is_current`) — `GET /v1/billing/plans`. */
@@ -1476,9 +1512,11 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * Upload one local asset and return its {@link UploadRecord} — the single-asset
      * convenience over {@link upload}. Accepts `Blob`/`File`/`ArrayBuffer`/`Uint8Array`
      * in every runtime; a path string is Node-only (it fails instructively elsewhere).
-     * The record guarantees `uri`, `contentType`, `size`, and `filename`. Transport
-     * failures surface as the semantic input-preparation errors (rejected asset, auth,
-     * unsupported capability, transport). See `docs/input-preparation.md`.
+     * The record guarantees `uri`, `contentType`, `size`, and `filename`. A `kind` and its
+     * `method_id` in the options record the upload as a method's test file, checked before the
+     * asset is read. Transport failures surface as the semantic input-preparation errors
+     * (rejected asset, refused test file, auth, unsupported capability, transport). See
+     * `docs/input-preparation.md`.
      */
     uploadFile(asset: UploadableAsset, options?: UploadFileOptions): Promise<UploadRecord>;
     /**
@@ -1511,6 +1549,52 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * input too.
      */
     prepareInputs(request: PrepareInputsRequest): Promise<PreparedInputs>;
+    /**
+     * One page of the organization's files, newest first — `GET /v1/files`.
+     *
+     * Rows are `FileSummary`: the record's id, its `uri`, which a run's inputs take as they take
+     * any address, the name a person sees, its type, size and kind, and where it came from. A list
+     * never holds a file a run made along the way, nor an upload whose bytes have not been seen
+     * stored. Every role of the organization reads every file of it.
+     *
+     * `methodId`, `runId` and `createdBy` choose which list serves the page: the method's files
+     * (what its runs and examples took or made), the run's own files (its final outputs and inline
+     * inputs, in the order of their addresses), one member's (`"me"` for the caller's own), or the
+     * organization's. `q`, `kind`, `format`, `mediaType`, `createdFrom` and `createdTo` filter that
+     * list server-side; `format` and `mediaType` are sent as one repeated parameter per value, and
+     * an empty list of either is a `RequestArgumentError` before any request. The filters run after
+     * the index read, so **a filtered page can hold fewer rows than `limit`, or none, and still
+     * carry a `nextCursor`**: keep following it until it is `null`, with the same filters, since a
+     * cursor is bound to the list and filters that issued it.
+     *
+     * Throws `ApiResponseError`: `400` for a date bound that is not an instant with an offset, a
+     * range whose start is after its end, or a cursor of another list or other filters; `404`
+     * `run_not_found` for a run that is not the organization's; `422` for a `limit` outside 1 to
+     * 200, an unknown `kind`, more than 100 values of `format` or `mediaType`, or an id that cannot
+     * be one. A page whose `items` is not an array or whose `next_cursor` is neither a string nor
+     * `null` is an `ApiResponseError` of an answer the SDK cannot read. See `docs/files.md`.
+     */
+    listFiles(query?: ListFilesQuery): Promise<FilePage>;
+    /**
+     * Every file of the organization the query selects, streamed — follows the cursor for you.
+     *
+     * ```ts
+     * for await (const file of client.iterateFiles({ kind: "uploaded", format: ["pdf"] })) {
+     *   if (file.name === "March invoice.pdf") break; // stop whenever you like
+     * }
+     * ```
+     *
+     * **Prefer `listFiles`** for anything user-facing: this makes as many round trips as the data
+     * demands. It is an iterator rather than an all-at-once helper for the reason `iterateRuns` is
+     * one: a helper returning an array needs a page cap, and a cap returns a truncated list with no
+     * error.
+     *
+     * It keeps going **through an empty page that carries a cursor**, which under any filter means
+     * "nothing matched in the slice just read", not "done", sending the same filters with every
+     * page. It stops on a `null` cursor or on a cursor the server failed to advance, and throws
+     * `PagingNotTerminatingError` past a page ceiling no real file list reaches.
+     */
+    iterateFiles(query?: Omit<ListFilesQuery, "cursor">): AsyncGenerator<FileSummary, void, undefined>;
     /**
      * One PAGE of a method's runs, newest first — `GET /v1/runs?method_id=`.
      *

package/dist/client.js

@@ -14,7 +14,7 @@ import { PipelexExecuteResult, resultsFromExecute } from "./execute-result.js";
 import { ExactJsonUnsupportedError, parseExactJson, stringifyExactJson } from "./exact-json.js";
 import { MAX_TIMER_DELAY_MS, isTimerDelay } from "./timers.js";
 // A pure RUNAWAY guard on the paged-list iterators (`iterateMethods`,
-// `iterateRuns`, `iterateMethodExamples`), deliberately not a coverage limit.
+// `iterateRuns`, `iterateMethodExamples`, `iterateFiles`), deliberately not a coverage limit.
 //
 // It counts TOTAL pages, not empty ones. An earlier version capped consecutive
 // empty pages, which is the wrong axis: an empty page whose cursor ADVANCED is
@@ -31,8 +31,8 @@ import { MAX_TIMER_DELAY_MS, isTimerDelay } from "./timers.js";
 const MAX_PAGES = 10_000;
 /**
  * Follow a paged list's cursor until the server says there is no more, yielding every row —
- * the one loop behind `iterateMethods`, `iterateRuns` and `iterateMethodExamples`, so they cannot
- * drift apart.
+ * the one loop behind `iterateMethods`, `iterateRuns`, `iterateMethodExamples` and
+ * `iterateFiles`, so they cannot drift apart.
  *
  * It yields lazily: a caller that breaks early stops the requests. It stops when `nextCursor`
  * is `null`, the normal end, and when the server hands back the cursor it was just sent, which
@@ -186,6 +186,24 @@ function productQuery(params) {
     const text = search.toString();
     return text ? `?${text}` : "";
 }
+/**
+ * A list filter sent as one repeated query parameter per value, such as `listFiles`' `format`:
+ * `undefined` when omitted, the values as given otherwise. An empty list names no value, and sent
+ * as no parameter at all it would read as no filter and list everything, so it is a
+ * `RequestArgumentError` before any request; a value that is not a list of strings is a
+ * `TypeError`, a bug in the calling code.
+ */
+function repeatedFilter(call, name, values) {
+    if (values === undefined)
+        return undefined;
+    if (!Array.isArray(values) || values.some((value) => typeof value !== "string")) {
+        throw new TypeError(`${call}() takes "${name}" as a list of strings.`);
+    }
+    if (values.length === 0) {
+        throw new RequestArgumentError(`${call}() takes "${name}" as one or more values; omit it to list every ${name}.`);
+    }
+    return values;
+}
 /** `items` joined as a sentence names them, the last after `conjunction`: `a`, `a or b`, `a, b or c`. */
 function inWords(items, conjunction) {
     if (items.length < 2)
@@ -552,7 +570,7 @@ export class PipelexApiClient {
     }
     /**
      * One page of a cursor-paged product route (`listMethods`, `listMethodVersions`,
-     * `listMethodExamples`, `listRuns`), read as the platform always serializes it: `items` an
+     * `listMethodExamples`, `listRuns`, `listFiles`), read as the platform always serializes it: `items` an
      * array, `next_cursor` a string or `null`. A page breaking either is an answer the SDK cannot
      * read, so it throws the `ApiResponseError` `unreadableAnswer` builds, `runtime` and not
      * retryable, rather than handing the iterators a page they cannot walk: `items` that is not
@@ -2499,6 +2517,47 @@ export class PipelexApiClient {
         const segment = idPathSegment(orgId, "renameOrganization", ORG_ID_ARGUMENT);
         return this.requestProduct("PATCH", `organizations/${segment}`, input);
     }
+    /**
+     * The branding of the caller's active organization — `GET /v1/branding`: its name, its light
+     * and dark colour sets and its two logos. Any role reads it, `runner` included, by web session
+     * or API key, so an app scaffolded from the method-app template reads its organization's
+     * branding with its own key. A personal workspace, or a team that set nothing, answers every
+     * colour and logo `null`. A logo's `uri` is a `pipelex-storage://` reference, which
+     * `resolveStorageUrl` turns into a short-lived link to its bytes.
+     *
+     * Throws `ApiResponseError`: `400` when the caller has no active organization, `404` when its
+     * row is missing, and an answer that is not a JSON object, an empty one included.
+     */
+    async getBranding() {
+        return this.requestProductObject("GET", "branding");
+    }
+    /**
+     * Set or clear an organization's branding — `PATCH /v1/organizations/{org_id}/branding`, an
+     * admin's write to the active organization. Every key of `input` is optional: a value sets it,
+     * `null` clears it, and a key left out keeps its value (`OrganizationBrandingUpdate`), so `{}`
+     * writes nothing. A new logo is the `pipelex-storage://` URI of a file the organization uploaded
+     * on its own, which the platform reads and measures, then copies under `branding/`: the answer's
+     * `uri` is that copy, and sending it back unchanged keeps the logo. The logo a write replaces or
+     * clears is erased. Answers the branding as the write left it.
+     *
+     * Throws `RequestArgumentError` for an organization id that is empty, `.` or `..`, before any
+     * request. Throws `ApiResponseError`, refusing every change of the request when it refuses one:
+     * `403` `forbidden` when `orgId` is not the active organization, `403` `role_not_permitted` for
+     * a caller who is not its admin, `404` for a missing organization, `409` `conflict` for a
+     * personal workspace, which has no branding, and `422` `validation_failed` for a colour that is
+     * not `#rrggbb` or a key the body does not know. A logo's refusal names its slot in the error's
+     * `errors[]`, each entry's `field` being `square_logo` or `wide_logo` and its `detail` the
+     * sentence to show under that slot: `400` `invalid_storage_uri` for a URI that is not a storage
+     * URI, `403` `forbidden` for another organization's file, and `422` `validation_failed` with a
+     * `LogoRefusalCode` per broken rule for a file the platform refused. A failure of the platform's
+     * storage while reading or copying a logo is a `500` `storage_backend_failed`, retryable, with
+     * nothing written. A `503` `service_unavailable` is a failure of its database, after which the
+     * write may have landed or not: the same input sent again is safe.
+     */
+    async updateOrganizationBranding(orgId, input) {
+        const segment = idPathSegment(orgId, "updateOrganizationBranding", ORG_ID_ARGUMENT);
+        return this.requestProductObject("PATCH", `organizations/${segment}/branding`, input);
+    }
     /** The active org's subscription state — `GET /v1/billing/subscription`. */
     async getSubscription() {
         return this.requestProduct("GET", "billing/subscription");
@@ -2642,9 +2701,11 @@ export class PipelexApiClient {
      * Upload one local asset and return its {@link UploadRecord} — the single-asset
      * convenience over {@link upload}. Accepts `Blob`/`File`/`ArrayBuffer`/`Uint8Array`
      * in every runtime; a path string is Node-only (it fails instructively elsewhere).
-     * The record guarantees `uri`, `contentType`, `size`, and `filename`. Transport
-     * failures surface as the semantic input-preparation errors (rejected asset, auth,
-     * unsupported capability, transport). See `docs/input-preparation.md`.
+     * The record guarantees `uri`, `contentType`, `size`, and `filename`. A `kind` and its
+     * `method_id` in the options record the upload as a method's test file, checked before the
+     * asset is read. Transport failures surface as the semantic input-preparation errors
+     * (rejected asset, refused test file, auth, unsupported capability, transport). See
+     * `docs/input-preparation.md`.
      */
     async uploadFile(asset, options) {
         return uploadFileImpl(this, asset, options);
@@ -2681,6 +2742,69 @@ export class PipelexApiClient {
     async prepareInputs(request) {
         return prepareInputsImpl(this, request);
     }
+    /**
+     * One page of the organization's files, newest first — `GET /v1/files`.
+     *
+     * Rows are `FileSummary`: the record's id, its `uri`, which a run's inputs take as they take
+     * any address, the name a person sees, its type, size and kind, and where it came from. A list
+     * never holds a file a run made along the way, nor an upload whose bytes have not been seen
+     * stored. Every role of the organization reads every file of it.
+     *
+     * `methodId`, `runId` and `createdBy` choose which list serves the page: the method's files
+     * (what its runs and examples took or made), the run's own files (its final outputs and inline
+     * inputs, in the order of their addresses), one member's (`"me"` for the caller's own), or the
+     * organization's. `q`, `kind`, `format`, `mediaType`, `createdFrom` and `createdTo` filter that
+     * list server-side; `format` and `mediaType` are sent as one repeated parameter per value, and
+     * an empty list of either is a `RequestArgumentError` before any request. The filters run after
+     * the index read, so **a filtered page can hold fewer rows than `limit`, or none, and still
+     * carry a `nextCursor`**: keep following it until it is `null`, with the same filters, since a
+     * cursor is bound to the list and filters that issued it.
+     *
+     * Throws `ApiResponseError`: `400` for a date bound that is not an instant with an offset, a
+     * range whose start is after its end, or a cursor of another list or other filters; `404`
+     * `run_not_found` for a run that is not the organization's; `422` for a `limit` outside 1 to
+     * 200, an unknown `kind`, more than 100 values of `format` or `mediaType`, or an id that cannot
+     * be one. A page whose `items` is not an array or whose `next_cursor` is neither a string nor
+     * `null` is an `ApiResponseError` of an answer the SDK cannot read. See `docs/files.md`.
+     */
+    async listFiles(query = {}) {
+        const search = productQuery({
+            method_id: query.methodId,
+            run_id: query.runId,
+            created_by: query.createdBy,
+            kind: query.kind,
+            format: repeatedFilter("listFiles", "format", query.format),
+            media_type: repeatedFilter("listFiles", "mediaType", query.mediaType),
+            created_from: query.createdFrom,
+            created_to: query.createdTo,
+            q: query.q,
+            limit: query.limit,
+            cursor: query.cursor,
+        });
+        return this.requestPage(`files${search}`);
+    }
+    /**
+     * Every file of the organization the query selects, streamed — follows the cursor for you.
+     *
+     * ```ts
+     * for await (const file of client.iterateFiles({ kind: "uploaded", format: ["pdf"] })) {
+     *   if (file.name === "March invoice.pdf") break; // stop whenever you like
+     * }
+     * ```
+     *
+     * **Prefer `listFiles`** for anything user-facing: this makes as many round trips as the data
+     * demands. It is an iterator rather than an all-at-once helper for the reason `iterateRuns` is
+     * one: a helper returning an array needs a page cap, and a cap returns a truncated list with no
+     * error.
+     *
+     * It keeps going **through an empty page that carries a cursor**, which under any filter means
+     * "nothing matched in the slice just read", not "done", sending the same filters with every
+     * page. It stops on a `null` cursor or on a cursor the server failed to advance, and throws
+     * `PagingNotTerminatingError` past a page ceiling no real file list reaches.
+     */
+    async *iterateFiles(query = {}) {
+        yield* followCursor("listFiles", (cursor) => this.listFiles({ ...query, cursor }));
+    }
     /**
      * One PAGE of a method's runs, newest first — `GET /v1/runs?method_id=`.
      *