@pipelex/sdk 0.49.0 → 0.51.0

package/README.md

@@ -167,11 +167,31 @@ for await (const saved of client.iterateMethodExamples(created.method_id)) {
   // every example, oldest first
 }
 
+// Copy a method into a team, or into your personal workspace, with its draft, its form inputs and
+// its examples (web sessions only). A bundle naming storage the destination cannot read answers
+// `refused`, a verdict rather than an error; the key makes a retry copy once.
+const copy = await client.copyMethod(
+  created.method_id,
+  { destination_org_id: "org_team", expected_draft_updated_at: draft.updated_at },
+  { idempotencyKey: crypto.randomUUID() },
+);
+if (copy.outcome === "copied") console.log(copy.method.copied_from); // the original it names
+const copies = await client.listMethodCopies(created.method_id); // where the copies went
+
 // 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 });
 
@@ -233,19 +253,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).
@@ -263,8 +282,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/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/method-copy.md`](./docs/method-copy.md) | Copying a method into another organization or duplicating it: what a copy holds and the stored files it copies, the `copied` or `refused` verdict, every refusal, the copy's idempotency key, the copies a method lists, and `copied_from` |
 | [`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 |

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.49.0";
+export declare const SCRIPT_RUNNER = "npx --yes --no-update-notifier --loglevel=warn @pipelex/sdk@0.51.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, 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 { BillingPortalResponse, ChangePlanResponse, CheckoutResponse, DraftFileFromFileInput, DraftFileFromFileResult, FileArchive, FileArchiveRequest, FileDetail, FileLinkTarget, FileLinksResult, FilePage, FileRecord, FileRecordList, FileRenameInput, FileSummary, GetFileQuery, GetFilesByUriOptions, InvoiceView, Membership, MembershipsResponse, OrganizationBranding, OrganizationBrandingUpdate, ListFilesQuery, ListMethodCopiesQuery, ListMethodExamplesQuery, ListMethodsQuery, ListMethodVersionsQuery, ListRunFilesQuery, MethodCopyInput, MethodCopyPage, MethodCopyResult, 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";
@@ -122,6 +122,34 @@ export interface PipelexStartRequestOptions {
      */
     idempotencyKey?: string | null;
 }
+/**
+ * What a method copy sends beside its body: the request's own header, which no copy argument
+ * reaches, camelCase since it is no wire field of the copy.
+ */
+export interface MethodCopyRequestOptions {
+    /**
+     * The copy's idempotency key, sent as the `Idempotency-Key` header of
+     * `POST /v1/methods/{id}/copy`, and not sent at all when absent or `null`. Generate one per copy
+     * the caller means to make (a `crypto.randomUUID()` is a good key), and keep it, with the
+     * arguments unchanged, across that copy's retries.
+     *
+     * The hosted API stores the copy's answer under the key for 24 hours, scoped to the caller and
+     * the method's organization, so the same copy sent again under the same key is answered with the
+     * stored answer and copies nothing more: a copy whose answer was lost, as on a client timeout,
+     * can be sent again unchanged and makes one copy, not two. A verdict and a `4xx` refusal of the
+     * copy are stored alike, so the same copy under the same key is answered the same again; a `5xx`
+     * and a refusal for its timing (a `408`, `425` or `429`) are not stored, and a copy that failed
+     * with one left nothing visible, so the same key sends it afresh.
+     * The same key with a different body is refused (`409` `conflict`), as is a key whose earlier
+     * request is still being handled (`409` `idempotency_key_in_use`, retryable: send it again
+     * under the same key in a few seconds); a changed copy, such as one with a fresh draft token,
+     * goes under a new key. See `docs/method-copy.md`.
+     *
+     * A key is held to the rule a start's is (`PipelexStartRequestOptions.idempotencyKey`): 1 to
+     * 255 visible ASCII characters, anything else a `RequestArgumentError` before any request.
+     */
+    idempotencyKey?: string | null;
+}
 /**
  * `start()` / `startAndWaitForResult()` options — the same, for the durable path, plus the start
  * request's own `idempotencyKey`.
@@ -231,7 +259,7 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * resolved absolute URL. `mayStartRun` marks a request that may create a run,
      * whose `ApiUnreachableError` then says whether it may have (see `RunCreation`).
      * `idempotencyKey`, already checked by `idempotencyKeyOf`, is sent as the
-     * `Idempotency-Key` header; only `start` passes one.
+     * `Idempotency-Key` header; only `start` and `copyMethod` pass one.
      */
     private requestRaw;
     /**
@@ -1215,6 +1243,71 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * never rewritten as one, which names no tree to serve.
      */
     getMethodVersion(methodId: string, version: number): Promise<MethodVersion>;
+    /**
+     * Copy a method into an organization the caller may change methods in —
+     * `POST /v1/methods/{id}/copy`: the method's own organization for a duplicate, another team, or
+     * the caller's personal workspace.
+     *
+     * The copy is a new, unpublished method of the destination, the caller's, holding the
+     * original's draft tree (the same `draft_digest`), its name unless `name` gives another, its
+     * form inputs and every saved example, each stored file they name copied into the destination,
+     * and `copied_from` naming the original. Published versions and runs are not copied, and the
+     * original stays as it was. The copy takes the draft, never the latest published version; with
+     * `expected_draft_updated_at`, it takes exactly the draft the caller last saw.
+     *
+     * The answer is a `MethodCopyResult` discriminated on `outcome` — branch on it: `copied` with
+     * the copy as `method`, `examples_copied` and `stored_files_copied`; `refused` with the
+     * `reason` `bundle_names_other_storage`, a `message` and every `references` entry (`{ path, uri
+     * }`) a `.mthds` file of the draft holds that the destination cannot read, nothing written.
+     *
+     * The route serves web sessions only: a Pipelex API key belongs to one organization and cannot
+     * speak for another. `options.idempotencyKey` is sent as the `Idempotency-Key` header, so a copy
+     * sent again under the same key is answered with the first one's answer rather than copied
+     * twice (see `MethodCopyRequestOptions`).
+     *
+     * Takes a bare catalog id, as `getMethod` does. Sends `destination_org_id` and, when given,
+     * `name` and `expected_draft_updated_at`, and nothing else: the body is closed, and a `null`
+     * reads as not given. Throws `RequestArgumentError` before any request for a
+     * `destination_org_id` that is not a non-empty string, a `name` or an
+     * `expected_draft_updated_at` given that is not a string, and a malformed idempotency key.
+     * Throws `ApiResponseError` when no verdict was produced, each refusal writing nothing a reader
+     * sees: `403` `forbidden` for a request that is not from a web session; `403`
+     * `role_not_permitted` for a role that may not change methods, in the method's organization or
+     * in the destination; `404` `organization_not_found` for a destination the caller does not
+     * belong to, still being set up or unknown, alike; `404` `not_found` for an unknown method;
+     * `409` `method_being_deleted`; `409` `method_update_conflict` for a draft that moved since
+     * `expected_draft_updated_at`; `409` `conflict`, `runtime`, for a draft whose tree the
+     * organization holds no full record of; `413` `payload_too_large` for an example or a copy too
+     * large for one stored item; `422` `validation_failed` for a body that does not validate, such
+     * as a name holding a lone surrogate; `422` `method_copy_too_large` past one of the copy's
+     * bounds on the stored files it copies, named by `problemDocument.limit` (`MethodCopyLimit`);
+     * and, each retryable, a `502` when the platform could not read the caller's memberships, a
+     * `500` `storage_backend_failed` and a `503` past the copy's deadline. An answer whose
+     * `outcome` is neither arm's, a `copied` one whose `method` is not an object or a `refused` one
+     * whose `references` is not an array, is an answer the SDK cannot read, thrown as an
+     * `ApiResponseError` too.
+     */
+    copyMethod(methodId: string, input: MethodCopyInput, options?: MethodCopyRequestOptions): Promise<MethodCopyResult>;
+    /**
+     * One page of the copies made of a method, in the order of the copies' ids, which says nothing
+     * of when each was made — `GET /v1/methods/{id}/copies`.
+     *
+     * Each row is the `MethodCopyMarker` the original keeps of a copy: the copy's id, the
+     * destination's id, the member who made it and when. The destination is named by its id alone,
+     * never its name, so a surface shows a destination's name only from the reader's own
+     * memberships, and a copy in an organization the reader does not belong to stays a bare id. A
+     * marker stays when its copy is erased, and the copy then reads as not found. Pass the page's
+     * `nextCursor` back as `cursor` to continue; `null` is the last page. A method never copied,
+     * and a copy itself, answer an empty page. The listing is open to every member of the method's
+     * organization, a runner included, as every read of a method is.
+     *
+     * Takes a bare catalog id, as `getMethod` does. Throws `ApiResponseError`: `404` `not_found` for
+     * an unknown method, `409` `method_being_deleted`, `400` `malformed_request` for a cursor the
+     * listing did not issue for this method, `422` for a `limit` outside 1 to 100. A page whose
+     * `items` is not an array or whose `next_cursor` is neither a string nor `null` is an answer the
+     * SDK cannot read, thrown as an `ApiResponseError` too.
+     */
+    listMethodCopies(methodId: string, query?: ListMethodCopiesQuery): Promise<MethodCopyPage>;
     /**
      * Erase a method and everything it produced — `DELETE /v1/methods/{id}`.
      *
@@ -1342,6 +1435,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.
@@ -1484,7 +1607,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`.
      */
@@ -1492,18 +1616,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;
@@ -1595,6 +1725,185 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * `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=`.
      *
@@ -1673,6 +1982,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>;
     /**