@pipelex/sdk 0.48.1 → 0.50.0

package/README.md

@@ -167,6 +167,23 @@ 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 } } });
+// One file with its uses, a link that downloads it under its name, and a zip of a run's files.
+const fileDetail = await client.getFile(files.items[0]!.file_id);
+for (const link of (await client.linkFiles([{ file_id: fileDetail.file_id }])).items) {
+  // A fifteen-minute link, or why this file got none. Hand link.url to a browser, never a log.
+  if (link.error === null) console.log(`${link.name} downloadable until ${link.expires_at}`);
+  else console.error(link.error.code);
+}
+const archive = await client.requestFileArchive({ run_id: run.pipeline_run_id });
+// then getFileArchive(archive.archive_id) until its state is ready or failed.
+// 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 ...
@@ -225,19 +242,18 @@ const client = new PipelexApiClient({ appInfo: { name: "acme-invoicer", version:
 
 ### Uploading from a browser
 
-A browser page that holds a file but not the API key can still store it: the server that holds the key asks for an upload grant, and the page sends the file straight to storage with it. The file never crosses your server or the API gateway, so it can be as large as the service's own limit. The page imports `@pipelex/sdk/upload`, which carries only the grant's sender, its types and its errors. Both entries bundle for the browser with nothing marked external, so a page may also import the main entry's error classes and types, while the client itself stays on the server that holds the key.
+A browser page that holds a file but not the API key can still store it: the page describes the file, its SHA-256 included, the server that holds the key asks for an upload grant with that description, and the page sends the file straight to storage with it, unless the grant says your organization already holds those bytes, in which case nothing is sent at all. The file never crosses your server or the API gateway, so it can be as large as the service's own limit. The page imports `@pipelex/sdk/upload`, which carries only the description, the grant's sender, their types and their errors. Both entries bundle for the browser with nothing marked external, so a page may also import the main entry's error classes and types, while the client itself stays on the server that holds the key.
 
 ```ts
-// On the server, which holds the key:
-const grant = await client.requestUploadGrant({
-  filename: "report.pdf",
-  content_type: "application/pdf",
-  size: 48213,
-});
-
 // In the page, which holds the file:
-import { uploadWithGrant } from "@pipelex/sdk/upload";
-const { uri } = await uploadWithGrant(grant, file); // pipelex-storage://…
+import { describeUpload, uploadWithGrant } from "@pipelex/sdk/upload";
+const description = await describeUpload(file); // { filename, content_type, size, sha256 }
+
+// On the server, which holds the key, given the description:
+const grant = await client.requestUploadGrant(description); // { stored, uri, file_id, url, … }
+
+// Back in the page, with the grant:
+const { uri, file_id } = await uploadWithGrant(grant, file); // sends nothing when grant.stored
 ```
 
 The full client surface is documented in [`docs/architecture.md`](./docs/architecture.md).
@@ -255,7 +271,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/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/files.md`](./docs/files.md) | An organization's files: `listFiles` and `iterateFiles`, the row, the whole record and its provenance, the query and its repeated filters, paging through filtered pages, one file and its uses, the records of an address, the rename rule, links that name the file, a zip of files and its caps, a run's files, the copy into a method's draft, 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, the build assistant's save and its `kept` or `created` 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.50.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, DraftFileFromFileInput, DraftFileFromFileResult, FileArchive, FileArchiveRequest, FileDetail, FileLinkTarget, FileLinksResult, FilePage, FileRecord, FileRecordList, FileRenameInput, FileSummary, GetFileQuery, GetFilesByUriOptions, InvoiceView, Membership, MembershipsResponse, OrganizationBranding, OrganizationBrandingUpdate, ListFilesQuery, ListMethodExamplesQuery, ListMethodsQuery, ListMethodVersionsQuery, ListRunFilesQuery, MethodData, MethodDeletionAccepted, MethodDetail, MethodDraftInput, MethodExample, MethodExampleAssistantSaveInput, MethodExampleAssistantSaveResult, MethodExampleCreateInput, MethodExampleLatestRunInput, MethodExampleLatestRunResult, MethodExamplePage, MethodExampleUpdateInput, MethodPage, MethodPublishInput, MethodPublishResult, MethodRenameInput, MethodSummary, MethodVersion, MethodVersionPage, MethodWriteInput, OnboardingSubmission, PipelexApiKeyCreated, PipelexApiKeyList, ListRunsQuery, RunHistoryItem, RunDetail, RunFilesPage, 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
@@ -1342,6 +1342,36 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * `ApiResponseError` too, read as `publishMethod` reads its verdict.
      */
     recordMethodExampleLatestRun(methodId: string, exampleId: string, input: MethodExampleLatestRunInput): Promise<MethodExampleLatestRunResult>;
+    /**
+     * Save the build assistant's test inputs as its example of the method —
+     * `POST /v1/methods/{id}/examples/assistant-save` — **never writing over a person's edit**.
+     *
+     * The assistant keeps one example of a method current with its test inputs, until a person
+     * edits that example's inputs. Find its example as the method's newest with `kept_by_assistant`
+     * true (`listMethodExamples` answers them oldest first), and send its `example_id` with the
+     * `input_revision` you read it at. The platform writes the inputs into it only while it still
+     * exists, still carries the flag and still holds that revision, in one conditional write that it
+     * never retries. Otherwise, and when no example is named, which is how the first save on a
+     * method creates the assistant's example, it saves the inputs as a new example flagged as the
+     * assistant's, under `name`.
+     *
+     * The answer is a `MethodExampleAssistantSaveResult` discriminated on `outcome` — branch on it:
+     * `kept`, the named example now holds the inputs, its name untouched; `created`, a new example
+     * holds them. Both carry the `example`, which is the assistant's from then on. A retry of a save
+     * that landed answers `kept` and writes nothing again.
+     *
+     * Sends `name`, `inputs` and, when given, `example_id` with `input_revision`, and nothing else:
+     * the body is closed, and `null` reads as not given. Throws `RequestArgumentError` before any
+     * request when `name` or `inputs` is not given, for an `example_id` that is not a non-empty
+     * string or an `input_revision` that is not a positive integer, and when only one of the two is
+     * given. Throws `ApiResponseError`: `403` `role_not_permitted` for a role that may not change
+     * methods, such as a runner; `413` `payload_too_large` for an example larger than one stored item
+     * holds; `422` for a name that is empty, blank or over 200 characters, or inputs that are not a
+     * JSON object; and the codes every example route answers. An answer whose `outcome` is neither
+     * arm's, or whose `example` is not an example `readMethodExample` can read, is an answer the SDK
+     * cannot read, thrown as an `ApiResponseError` too.
+     */
+    saveAssistantMethodExample(methodId: string, input: MethodExampleAssistantSaveInput): Promise<MethodExampleAssistantSaveResult>;
     /**
      * Delete an example — `DELETE /v1/methods/{id}/examples/{example_id}`. The platform answers
      * `204`. Deleting the example leaves its latest run in the method's history.
@@ -1362,6 +1392,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`. */
@@ -1448,7 +1514,8 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      */
     downloadArtifacts(request: DownloadArtifactsRequest): Promise<DownloadArtifactsResult>;
     /**
-     * Upload a base64 file — `POST /v1/upload`. An answer with no non-empty string `uri` names no
+     * Upload a base64 file — `POST /v1/upload`, answering the file's `uri`, the `filename` as sent
+     * and the `file_id` of its record. An answer with no non-empty string `uri` names no
      * stored file, so it is an answer the SDK cannot read: an `ApiResponseError`, `runtime` and
      * not retryable, which `uploadFile` wraps as an `UploadTransportError` with code `unexpected`.
      */
@@ -1456,18 +1523,24 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
     /**
      * Request a grant to upload one file straight to storage — `POST /v1/upload/grant`.
      * `upload` for a caller that holds the bytes but not this client's credential, such
-     * as a browser page: the credential-holding side asks for the grant, hands it over,
-     * and the holder of the bytes sends them with `uploadWithGrant`, from the
-     * browser-safe `@pipelex/sdk/upload` entry. The bytes cross neither this client nor
-     * the API gateway, so the gateway's request quota does not cap the file below the
-     * service's own limit (`max_bytes`).
-     *
-     * The grant describes one new object: its `uri` exists once the `PUT` succeeds, and
-     * not before. It is create-only and short-lived, and it is a bearer capability, so
-     * keep it out of logs. The route never replays a grant: ask again for a new one
-     * rather than retrying. A declared `size` over the cap is a `413` `ApiResponseError`
-     * (`code` `payload_too_large`); a deployment without the route answers a `404`. See
-     * `docs/input-preparation.md`.
+     * as a browser page: the holder of the bytes describes the file with `describeUpload`,
+     * its SHA-256 included, the credential-holding side asks for the grant with that
+     * description and hands the grant over, and the holder of the bytes sends them with
+     * `uploadWithGrant`. Both are on the browser-safe `@pipelex/sdk/upload` entry. The
+     * bytes cross neither this client nor the API gateway, so the gateway's request quota
+     * does not cap the file below the service's own limit (`max_bytes`).
+     *
+     * **Branch on the answer's `stored`.** With the file's `sha256`, the object is named
+     * after its bytes: when the organization already holds them, the grant answers
+     * `stored: true` with the file's `uri` and `file_id` and no upload target, and nothing
+     * is to be sent. Otherwise, and always without a `sha256`, it answers a presigned,
+     * create-only `PUT` whose `uri` exists once the `PUT` succeeds, and not before. That
+     * target is short-lived and a bearer capability, so keep it out of logs. The route
+     * never replays a grant: ask again for a new one rather than retrying; with a
+     * `sha256`, a new grant answers the same file record. A declared `size` over the cap
+     * is a `413` `ApiResponseError` (`code` `payload_too_large`), a malformed `sha256` and
+     * a `size` other than the one the organization holds those bytes at are a `422`, and a
+     * deployment without the route answers a `404`. See `docs/input-preparation.md`.
      */
     requestUploadGrant(input: UploadGrantInput, options?: {
         signal?: AbortSignal;
@@ -1476,9 +1549,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 +1586,231 @@ 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 file with its provenance, the methods whose lists hold it, and one page of its uses —
+     * `GET /v1/files/{file_id}`.
+     *
+     * The answer is a `FileDetail`: the file's whole record (`FileRecord`), its `method_ids`, and
+     * `uses`, one page of the examples that hold its address, then the runs that took it. Page the
+     * uses by passing `uses.next_cursor` back as `usesCursor`; `null` is the last page. A record whose
+     * upload looked unfinished past the upload grant's lifespan is settled by the read, so it answers
+     * `stored` when its bytes are there.
+     *
+     * Throws `RequestArgumentError` for a file id that is empty, `.` or `..`, or holds a lone
+     * surrogate, before any request. Throws `ApiResponseError`: `404` `not_found` for a file that is
+     * not the organization's; `422` for a `usesLimit` outside 1 to 200 or an id that cannot be one.
+     * An answer that is not an object, or whose `uses` is not a page of `items` and `next_cursor`, is
+     * an answer the SDK cannot read, thrown as an `ApiResponseError` too. See `docs/files.md`.
+     */
+    getFile(fileId: string, query?: GetFileQuery): Promise<FileDetail>;
+    /**
+     * The records holding one `pipelex-storage://` address — `GET /v1/files/by-uri` — in the order a
+     * surface picks the one to show, the first being it.
+     *
+     * Several records hold one address when several members uploaded the same bytes. With `runId`,
+     * the records of the member who started that run come first, so a run's inputs show the name its
+     * starter gave the file; then the caller's; then the rest, each group oldest first. A record
+     * whose upload has not finished is answered with its `state`, `pending`. An address no record
+     * holds answers an empty `items`, which is how a client tells a file stored before the platform
+     * kept records.
+     *
+     * Throws `RequestArgumentError` for a `uri` that is not a non-empty string, before any request.
+     * Throws `ApiResponseError`: `400` `invalid_storage_uri` for a malformed address, `403`
+     * `forbidden` for another organization's, `404` `run_not_found` for a run that is not the
+     * organization's, and `422` for an address over 512 characters. An answer whose `items` is not an
+     * array is an answer the SDK cannot read, thrown as an `ApiResponseError` too.
+     */
+    getFilesByUri(uri: string, options?: GetFilesByUriOptions): Promise<FileRecordList>;
+    /**
+     * Rename a file — `PATCH /v1/files/{file_id}` — and return its record as it now stands.
+     *
+     * **The platform holds the name to one rule, for every client**: it removes the characters no
+     * list or header can show (control and format characters, a right-to-left override among
+     * them), trims the ends, refuses a name with nothing left, and adds the file's own extension,
+     * the one its `original_name` ends with, when the name does not end with it, case aside:
+     * `March invoice` becomes `March invoice.pdf`, and `March.docx` becomes `March.docx.pdf`. A file
+     * whose original name has no extension gains none. Read the saved name from the answer's
+     * `name`. The rename changes `name` alone, never the file's bytes, its address or its
+     * `original_name`.
+     *
+     * An `admin` or a `member` renames any file; any other role, a runner among them, only the files
+     * whose record names it as `created_by`: its own uploads and the outputs of the runs it started.
+     *
+     * Sends `name` alone: the body is closed. Throws `RequestArgumentError` for a file id that is
+     * empty, `.` or `..`, or holds a lone surrogate, and for a `name` that is not a string, before
+     * any request. Throws `ApiResponseError`: `403` `role_not_permitted` past the rule above; `404`
+     * `not_found` for a file that is not the organization's; `422` for a name over 512 characters or
+     * with nothing left once cleaned. An answer that is not an object is an answer the SDK cannot
+     * read, thrown as an `ApiResponseError` too.
+     */
+    renameFile(fileId: string, input: FileRenameInput): Promise<FileRecord>;
+    /**
+     * Fresh links to read files — `POST /v1/files/links` — one per requested file, in the request's
+     * order, each named by exactly one of its record's id (`file_id`) and its address (`uri`).
+     *
+     * **Branch on each item's `error`, never on the status**: the request is a `200` whenever every
+     * file got a verdict. A linked file carries its `url`, a presigned `GET` valid for fifteen
+     * minutes, with its `expires_at`, the `name` the download saves under and its `media_type`, and
+     * a `null` `error`. A file that got no link carries `error`, `{ code, detail }`, and `null` link
+     * members: `not_found` for an unknown file id, `conflict` for a file whose upload has not
+     * finished, `invalid_storage_uri` for a malformed address and `forbidden` for another
+     * organization's.
+     *
+     * Each link is signed with a `Content-Disposition` naming the file, so a download saves under
+     * the name a person sees rather than the bytes' hash. It opens in place (`inline`) for an image,
+     * a PDF or plain text and downloads (`attachment`) for every other type, SVG, HTML and XML
+     * included, so a file that could run scripts never opens from a link. A file named by its id is
+     * linked under its record's name; an address under the name of its first stored record, the
+     * caller's before another member's, whose id the item's `file_id` names. A link is a bearer
+     * capability: keep it out of logs, and ask again for a fresh one rather than storing it.
+     *
+     * Sends each file as `{ file_id }` or `{ uri }` and nothing else: the body is closed. Throws
+     * `RequestArgumentError` before any request when `files` is not a list, or one of its items does
+     * not name exactly one of `file_id` and `uri` as a non-empty string. Throws `ApiResponseError`:
+     * `422` for more than 100 files, or an id or address longer than one can be; `500` `config` when
+     * the platform cannot sign at all. An answer that is not one item per requested file, each an
+     * object with its `url` or its `error`, is an answer the SDK cannot read, thrown as an
+     * `ApiResponseError` whose body hides every link.
+     */
+    linkFiles(files: readonly FileLinkTarget[]): Promise<FileLinksResult>;
+    /**
+     * Ask for one zip of chosen files, or of a run's files — `POST /v1/files/archives` — and return
+     * the archive, `queued`.
+     *
+     * The platform cannot build a zip inside a request, so the zip is two calls: this one queues the
+     * archive and answers at once (`202`), and `getFileArchive` reads it until its `state` is `ready`,
+     * whose `url` downloads the zip, or `failed`, whose `failure` says why. Name the files by exactly
+     * one of `file_ids`, in the order the zip holds them, and `run_id`, whose zip holds what went in
+     * and what came out of the run, never a file it made along the way nor an input given as a web
+     * link. `name` is the name the zip downloads under (see `FileArchiveRequest`). An archive is never
+     * a file: no list shows it, and it is gone a day after it was asked for.
+     *
+     * Sends `file_ids` or `run_id`, and `name` when given, and nothing else: the body is closed, and a
+     * `null` member reads as not given. Throws `RequestArgumentError` before any request when the
+     * request names both or neither of `file_ids` and `run_id`, when `file_ids` is not a non-empty
+     * list of non-empty strings, when `run_id` is not a non-empty string, and when `name` is not a
+     * string. Throws `ApiResponseError`:
+     *
+     * - `422` `file_archive_too_large` past a cap, at most 500 files or 2,000,000,000 bytes, whose
+     *   `problemDocument.limit` names it (`FileArchiveLimit`), so the person can be told how far over
+     *   the selection is;
+     * - `422` `validation_failed` for more than 1,000 ids listed, or an id longer than one can be;
+     * - `404` `not_found` for a file that is not the organization's, the `detail` naming up to five
+     *   of them, or a run whose files hold nothing stored to zip; `404` `run_not_found` for a run
+     *   that is not the organization's;
+     * - `409` `conflict`: an `input` one, not retryable, for a selected file whose upload has not
+     *   finished; a `runtime` one, retryable, for a run whose files are not all recorded yet, which
+     *   the same request clears a few seconds after the run ends;
+     * - `503` `service_unavailable`, retryable, when the archive could not be queued: the same request
+     *   sent again asks for a new archive.
+     *
+     * An answer that is not an archive, an object with a string `archive_id` and a known `state`, is
+     * an answer the SDK cannot read, thrown as an `ApiResponseError` too.
+     */
+    requestFileArchive(request: FileArchiveRequest): Promise<FileArchive>;
+    /**
+     * Where an archive stands — `GET /v1/files/archives/{archive_id}` — with a fresh link to its zip
+     * once it is `ready`.
+     *
+     * **Branch on `state`.** `queued` and `building` mean read it again shortly: a zip of a few files
+     * is ready within seconds, and the largest the caps allow within a few minutes. `ready` carries
+     * `url`, a presigned `GET` of the zip valid for fifteen minutes and signed with a
+     * `Content-Disposition` naming the archive's `name`, with `archive_bytes` and `ready_at`; each read
+     * signs a fresh link, so a caller that let one lapse reads the archive again. `failed` carries
+     * `failure`, `file_gone` or `build_failed`, and the remedy for both is a new request. An archive
+     * still `queued` or `building` an hour after it was asked for reads as `failed`.
+     *
+     * Throws `RequestArgumentError` for an archive id that is empty, `.` or `..`, or holds a lone
+     * surrogate, before any request. Throws `ApiResponseError`: `404` `not_found` for an archive that
+     * is not the organization's, never existed, or has expired, a day after `created_at`; `500` when
+     * the link cannot be signed. An answer that is not an archive is an answer the SDK cannot read,
+     * thrown as an `ApiResponseError` whose body hides the link.
+     */
+    getFileArchive(archiveId: string): Promise<FileArchive>;
+    /**
+     * An archive as `res` carried it, checked to be one: an object with a string `archive_id` and a
+     * `state` this SDK knows, the field a caller branches on. Anything else is an answer the SDK
+     * cannot read, thrown as the `ApiResponseError` `unreadableAnswer` builds with every link hidden,
+     * since a ready archive's answer carries one.
+     */
+    private readFileArchive;
+    /**
+     * Copy one of the organization's files into a method's draft —
+     * `POST /v1/methods/{id}/draft/files/from-file`, "Add to method files".
+     *
+     * The file becomes a file of the draft at `path`, replacing a file already there. Its bytes are
+     * copied into the organization's blob store by the storage service itself, so they never cross
+     * the client or the API whatever their size, and are skipped when the store already holds them.
+     * The method file then lives apart from its source: erasing the file's record, the run that made
+     * it or the method it came from leaves it readable.
+     *
+     * The answer is a `DraftFileFromFileResult`, a `200` discriminated on `blob`: `copied`, or
+     * `already_held` when the store held the bytes and nothing was copied. Both carry the `file` as
+     * the draft's tree now names it and the `method` as the draft write stored it, whose
+     * `updated_at` is the new draft token. With `expected_updated_at`, the write is a
+     * compare-and-swap on the draft token; without it, the file is added to the draft as it stands,
+     * never erasing someone else's save.
+     *
+     * Takes a bare catalog id, as `writeDraft` does. Sends `file_id`, `path` and, when given,
+     * `expected_updated_at`, and nothing else: the body is closed, and a `null` token reads as not
+     * given. Throws `RequestArgumentError` before any request for a `file_id` or a `path` that is not
+     * a non-empty string, and an `expected_updated_at` that is not a string. Throws
+     * `ApiResponseError`: `403` `role_not_permitted` for a role that may not change methods; `404`
+     * for an unknown method or a file that is not the organization's; `409` `method_being_deleted`,
+     * `409` `method_update_conflict` for a stale `expected_updated_at`, and `409` `conflict` for a
+     * file whose upload has not finished or whose stored bytes do not match its record; `422`
+     * `invalid_method_files` for a path the draft cannot hold, such as `.env` or `../logo.png`, and
+     * `422` `method_tree_too_large` past the deployment's limits. An answer whose `blob` is neither
+     * arm's, or whose `file` or `method` is not an object, is an answer the SDK cannot read, thrown
+     * as an `ApiResponseError` too.
+     */
+    copyFileIntoDraft(methodId: string, input: DraftFileFromFileInput): Promise<DraftFileFromFileResult>;
     /**
      * One PAGE of a method's runs, newest first — `GET /v1/runs?method_id=`.
      *
@@ -1589,6 +1889,29 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * example's go back as the run used them.
      */
     getRunDetail(runId: string): Promise<RunDetail>;
+    /**
+     * One page of a run's files, sorted by where they sit in the run — `GET /v1/runs/{id}/files`.
+     *
+     * Each entry carries its `mark`, `input`, `final` or `intermediate`, and the record a surface
+     * shows for it (`RunFileEntry`): `inputs` are what went in, the inputs given by their address
+     * with the record of the member who started the run first, then the inline inputs; `outputs` are
+     * the run's final outputs; `intermediates` the files it made along the way. An input given as a
+     * web link gets no record and is listed in `links`, with the warning that replaying the run needs
+     * it to still serve the same file.
+     *
+     * **`state` is `listing` until the platform has recorded every file of the run**, a few seconds
+     * after it ends: read it again until it is `listed` before taking the list as whole. The run's
+     * own records are paged by address with `limit` and `cursor`; the inputs by address and the links
+     * come on the first page only. Pass `nextCursor` back as `cursor`; `null` is the last page.
+     *
+     * Throws `RequestArgumentError` for a run id that is empty, `.` or `..`, or holds a lone
+     * surrogate, before any request. Throws `ApiResponseError`: `404` for a run that is not the
+     * organization's, exactly as for one that does not exist; `400` for a run id holding a character
+     * outside letters, digits, `_` and `-`, or a cursor another listing issued; `422` for a `limit`
+     * outside 1 to 200. A page whose `state` is unknown, whose lists are not arrays, or whose `next_cursor` is neither a
+     * string nor `null`, is an answer the SDK cannot read, thrown as an `ApiResponseError` too.
+     */
+    listRunFiles(runId: string, query?: ListRunFilesQuery): Promise<RunFilesPage>;
     /** Patch a run's status (admin/manual) — `PUT /v1/runs/{id}`. */
     updateRun(runId: string, input: UpdateRunInput): Promise<void>;
     /**