@pipelex/sdk 0.41.0 → 0.43.0

package/README.md

@@ -72,6 +72,23 @@ const saved = await client.start({ method_id: "mt_abc123@3", inputs: {} });
 console.log(saved.method_version); // 3
 ```
 
+### A start you can retry: `idempotencyKey`
+
+`start` and `startAndWaitForResult` take an optional `idempotencyKey`, sent as the `Idempotency-Key` header of `POST /v1/start`. The hosted API binds the key to the run the first request starts, so the same start sent again under the same key is answered with that run and starts nothing: a start whose answer was lost can be sent again without paying for a second run. Generate one key per run, and keep it with the options, unchanged, across that start's retries:
+
+```ts
+import { runMayHaveStartedOf } from "@pipelex/sdk";
+
+const options = { method_id: "mt_abc123", inputs, idempotencyKey: crypto.randomUUID() };
+const ack = await client.start(options).catch((err: unknown) => {
+  // The run may exist: under the same key, the same start is answered with it.
+  if (runMayHaveStartedOf(err)) return client.start(options);
+  throw err;
+});
+```
+
+A key is 1 to 255 visible ASCII characters; a key reused with other options is refused with a `409` `conflict`, and one whose earlier start is still being handled with a retryable `409` `idempotency_key_in_use` ([`docs/errors.md`](./docs/errors.md#a-starts-idempotency-key--idempotencykey)). A bare runner ignores the header.
+
 ### Checking a model reference
 
 `checkModelReference` asks the runner whether a reference a method's `model` field could name resolves, as what kind and to which model (`GET /v1/models/check`, served by `pipelex-api` from pipelex 0.78.0). A reference that resolves nowhere is a verdict, not an error, and narrowing on `kind` types its `matches`:
@@ -124,6 +141,21 @@ else console.log(`version ${published.version.version}`); // "published" or "unc
 const versions = await client.listMethodVersions(created.method_id); // newest first
 const { method_id, version } = parseMethodSelector("mt_abc123@3"); // the method routes take a bare id
 
+// A saved example is a named set of inputs with the latest run of exactly those inputs. Record a
+// run against the revision whose inputs it used: an edit since answers `stale`, never an error.
+const example = await client.createMethodExample(created.method_id, {
+  name: "March receipt",
+  inputs: { total: 3 },
+});
+const run = await client.start({ method_id: created.method_id, inputs: example.inputs });
+const verdict = await client.recordMethodExampleLatestRun(created.method_id, example.example_id, {
+  run_id: run.pipeline_run_id,
+  input_revision: example.input_revision,
+});
+for await (const saved of client.iterateMethodExamples(created.method_id)) {
+  // every example, oldest first
+}
+
 try {
   const { portal_url } = await client.getBillingPortal();
   // open portal_url ...
@@ -136,7 +168,7 @@ try {
 
 ### Errors
 
-Every error the SDK throws carries a verdict: `retryable`, whether asking again can succeed, and `errorDomain`, who can fix the failure (`input` for the caller, `config` for a change to the environment such as the credential, the plan or the base URL, `runtime` for nobody beforehand). Both are always decided, and `errorVerdictOf` reads them from anything a `catch` holds, returning `undefined` for what is not an SDK error, such as a bug in the calling code or your own abort. A failed `start` or blocking `execute` also says whether it may have created a run anyway, as `runMayHaveStarted`, read with `runMayHaveStartedOf`: when it is `true`, `retryable` is `false`, since asking again could start a second paid run, and the person should look the run up in the run history first ([`docs/errors.md`](./docs/errors.md#a-failed-run-start--runmayhavestarted)).
+Every error the SDK throws carries a verdict: `retryable`, whether asking again can succeed, and `errorDomain`, who can fix the failure (`input` for the caller, `config` for a change to the environment such as the credential, the plan or the base URL, `runtime` for nobody beforehand). Both are always decided, and `errorVerdictOf` reads them from anything a `catch` holds, returning `undefined` for what is not an SDK error, such as a bug in the calling code or your own abort. A failed `start` or blocking `execute` also says whether it may have created a run anyway, as `runMayHaveStarted`, read with `runMayHaveStartedOf`: when it is `true`, `retryable` is `false`, since asking again could start a second paid run, and the person should look the run up in the run history first ([`docs/errors.md`](./docs/errors.md#a-failed-run-start--runmayhavestarted)), unless the start carried an `idempotencyKey`, in which case sending it again unchanged recovers the run ([above](#a-start-you-can-retry-idempotencykey)).
 
 ```ts
 import { errorVerdictOf } from "@pipelex/sdk";
@@ -212,6 +244,8 @@ 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/bundle-resources.md`](./docs/bundle-resources.md) | Sending the files a bundle's steps read, such as a `PipeDocGen` step's template, as `resources` beside its `.mthds` contents: where they go, what is refused and by whom, and the template check's warnings |
+| [`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/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 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 |
 | [`docs/errors.md`](./docs/errors.md) | The verdict every error carries (`retryable`, `errorDomain`, `errorVerdictOf`), a failed run's stored error report on `RunFailedError` and `RunRead`, and every member of a refused request's `ApiResponseError`, with the fields to branch on |

package/dist/cli/present.d.ts

@@ -43,7 +43,8 @@ export declare function validationLine(item: Pick<ValidationErrorItem, "message"
 export declare function isAbsence(mainStuff: unknown): boolean;
 /**
  * Print a finished run's main output on stdout, as the method produced it: indented JSON,
- * unvalidated and unrepaired, a list included whichever shape it arrived in. An output the method
- * left absent prints `null`, and a line on stderr says so.
+ * unvalidated and unrepaired, a list included whichever shape it arrived in, an integer past
+ * `Number.MAX_SAFE_INTEGER`, which the client reads as a `bigint`, printed with its exact digits.
+ * An output the method left absent prints `null`, and a line on stderr says so.
  */
 export declare function printResult(mainStuff: unknown, io: CommandIO): void;

package/dist/cli/present.js

@@ -13,7 +13,7 @@
  * alone names what could not be read (`API POST /v1/start answered 202 with a body that is not
  * JSON`). Both SDKs word those messages alike, and the case table holds the ones both meet.
  */
-import { ApiResponseError, ApiUnreachableError, InputPreparationError, InvalidInputValueError, InvalidLocalSourceError, MethodLoadError, PipelineRequestError, RejectedAssetError, RunFailedError, UnsupportedUploadCapabilityError, UploadAuthenticationError, UploadTransportError, } from "../index.js";
+import { ApiResponseError, ApiUnreachableError, InputPreparationError, InvalidInputValueError, InvalidLocalSourceError, MethodLoadError, PipelineRequestError, RejectedAssetError, RunFailedError, UnsupportedUploadCapabilityError, UploadAuthenticationError, UploadTransportError, stringifyExactJson, } from "../index.js";
 import { CommandError, EXIT_FAILED, EXIT_USAGE } from "./io.js";
 /** Word any failure for stderr and choose its exit code. */
 export function presentError(error) {
@@ -189,8 +189,9 @@ export function isAbsence(mainStuff) {
 }
 /**
  * Print a finished run's main output on stdout, as the method produced it: indented JSON,
- * unvalidated and unrepaired, a list included whichever shape it arrived in. An output the method
- * left absent prints `null`, and a line on stderr says so.
+ * unvalidated and unrepaired, a list included whichever shape it arrived in, an integer past
+ * `Number.MAX_SAFE_INTEGER`, which the client reads as a `bigint`, printed with its exact digits.
+ * An output the method left absent prints `null`, and a line on stderr says so.
  */
 export function printResult(mainStuff, io) {
     if (isAbsence(mainStuff)) {
@@ -203,6 +204,6 @@ export function printResult(mainStuff, io) {
         }
         return;
     }
-    io.writeStdout(`${JSON.stringify(mainStuff, null, 2)}\n`);
+    io.writeStdout(`${stringifyExactJson(mainStuff, 2)}\n`);
 }
 //# sourceMappingURL=present.js.map

package/dist/cli/present.js.map

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

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.41.0";
+export declare const SCRIPT_RUNNER = "npx --yes --no-update-notifier --loglevel=warn @pipelex/sdk@0.43.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, DictPipeOutput, FormatResponse, LintResponse, ModelCheckCategory, ModelReferenceVerdict, MthdsFileItem, PipeIORequest, PipeIOResponse, PipelexRunResultStart, PipelexValidationResult, ResolveRequest, ResolveResponse, ValidateMethodSelector } from "./models.js";
 import { type GetRunResultOptions, type RunRead, type RunResults, type RunResultState, type StartAndWaitForResultOptions, type WaitForResultOptions } from "./runs.js";
-import type { BillingPortalResponse, ChangePlanResponse, CheckoutResponse, InvoiceView, Membership, MembershipsResponse, ListMethodsQuery, ListMethodVersionsQuery, MethodData, MethodDeletionAccepted, MethodDraftInput, MethodPage, MethodPublishInput, MethodPublishResult, MethodRenameInput, MethodSummary, MethodVersion, MethodVersionPage, MethodWriteInput, OnboardingSubmission, PipelexApiKeyCreated, PipelexApiKeyList, ListRunsQuery, RunHistoryItem, RunDetail, RunPage, PlanView, ResolvedStorageUrl, SubscriptionResponse, UpdateRunInput, UploadGrant, UploadGrantInput, UploadInput, UploadedFile, UserProfile } from "./product-models.js";
+import type { BillingPortalResponse, ChangePlanResponse, CheckoutResponse, InvoiceView, Membership, MembershipsResponse, ListMethodExamplesQuery, ListMethodsQuery, ListMethodVersionsQuery, MethodData, MethodDeletionAccepted, MethodDraftInput, MethodExample, MethodExampleCreateInput, MethodExampleLatestRunInput, MethodExampleLatestRunResult, MethodExamplePage, MethodExampleUpdateInput, MethodPage, MethodPublishInput, MethodPublishResult, MethodRenameInput, MethodSummary, MethodVersion, MethodVersionPage, MethodWriteInput, OnboardingSubmission, PipelexApiKeyCreated, PipelexApiKeyList, ListRunsQuery, RunHistoryItem, RunDetail, RunPage, PlanView, ResolvedStorageUrl, SubscriptionResponse, UpdateRunInput, UploadGrant, UploadGrantInput, UploadInput, UploadedFile, UserProfile } from "./product-models.js";
 import type { AppInfo } from "./user-agent.js";
 import type { UploadableAsset, UploadFileOptions, UploadRecord } from "./upload.js";
 import type { BundleResources } from "./bundle-resources.js";
@@ -105,8 +105,37 @@ export interface PipelexHostedRunExtensions {
 }
 /** `execute()` options — the protocol's run arguments plus the Pipelex API and hosted extensions. */
 export type PipelexRunOptions = RunOptions & PipelexApiRunExtensions & PipelexHostedRunExtensions;
-/** `start()` / `startAndWaitForResult()` options — the same, for the durable path. */
-export type PipelexStartOptions = StartOptions & PipelexApiRunExtensions & PipelexHostedRunExtensions;
+/**
+ * What a run start sends beside its body: the request's own headers, which no run argument
+ * reaches. Each is camelCase, since none of them is a wire field of the run request.
+ */
+export interface PipelexStartRequestOptions {
+    /**
+     * The start's idempotency key, sent as the `Idempotency-Key` header of `POST /v1/start`, and
+     * not sent at all when absent or `null`. Generate one per run the caller means to start (a
+     * `crypto.randomUUID()` is a good key), and keep it, with every other option unchanged, across
+     * that start's retries.
+     *
+     * The hosted API binds the key to the run the first request starts, before it dispatches it, so
+     * the same start sent again under the same key is answered with that run's acknowledgement and
+     * starts nothing, whatever became of the first attempt, for 24 hours. A failed start whose
+     * `runMayHaveStarted` is true can therefore be sent again unchanged, and recovers the run instead
+     * of paying for a second one. 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); see `docs/errors.md`. A bare
+     * runner ignores the header.
+     *
+     * A key is 1 to 255 visible ASCII characters (`!` to `~`, so no space); anything else, an empty
+     * string included, is a `RequestArgumentError` before any request is sent, since a start sent
+     * without the key the caller asked for would lose the protection silently.
+     */
+    idempotencyKey?: string | null;
+}
+/**
+ * `start()` / `startAndWaitForResult()` options — the same, for the durable path, plus the start
+ * request's own `idempotencyKey`.
+ */
+export type PipelexStartOptions = StartOptions & PipelexApiRunExtensions & PipelexHostedRunExtensions & PipelexStartRequestOptions;
 /**
  * The method selector `validate()` takes in place of inline contents — declared
  * beside the other wire shapes in `./models.js` and re-exported here, the import
@@ -205,6 +234,8 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * cleanly. Non-2xx interpretation is left to the caller. `url` is a fully
      * 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.
      */
     private requestRaw;
     /**
@@ -239,14 +270,45 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      */
     private readStoredSources;
     /**
-     * One page of a cursor-paged product route (`listMethods`, `listMethodVersions`, `listRuns`),
-     * 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 iterable, or a missing
-     * cursor that is neither the end nor a next page, which `iterateRuns` would follow forever.
+     * A verdict, the `200` a route answers discriminated on `outcome` with the object the verdict
+     * is about as one `member`: `publishMethod`'s `method`, `recordMethodExampleLatestRun`'s
+     * `example`. The answer is read as `readObjectAnswer` reads it, then an `outcome` that is none
+     * of `outcomes` is an answer the SDK cannot read, and so is a `member` that is not an object,
+     * the check `readObjectAnswerAt` holds a route's whole answer to: each throws the
+     * `ApiResponseError` `unreadableAnswer` builds, `verdict` naming the answer in the message.
+     * A route whose member has a reader of its own passes it as `readMember`, which then checks the
+     * member in place of that object check, so the member is checked once. `parse` reads the
+     * answer's text, `readJson` unless the route names another. Returns the answer, its `outcome`
+     * and the member as `subject`, for the route to read further.
+     */
+    private readVerdict;
+    /**
+     * One page of a cursor-paged product route (`listMethods`, `listMethodVersions`,
+     * `listMethodExamples`, `listRuns`), 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
+     * iterable, or a missing cursor that is neither the end nor a next page, which `iterateRuns`
+     * would follow forever. A route reading its rows itself passes `rows`: `parse` reads the page's
+     * text, and `item` reads each row, throwing as `unreadableAnswer` does for one it cannot read.
      */
     private requestPage;
+    /**
+     * A route answering one method example (`createMethodExample`, `getMethodExample`,
+     * `updateMethodExample`), its answer read with `parseExactJson`, so an integer past the safe
+     * range in the inputs is a `bigint` holding its exact digits, and checked by
+     * `readMethodExample`.
+     */
+    private requestMethodExample;
+    /**
+     * A method example as `res` carried it, checked against `METHOD_EXAMPLE_FIELDS`: a value that
+     * is not an object, or that misses a field the Python SDK's model requires or holds one of
+     * another type, is an answer the SDK cannot read, thrown as the `ApiResponseError`
+     * `unreadableAnswer` builds, `where` naming the example's place in the answer in the message.
+     * Every route answering an example reads it here, the page rows and the latest-run verdict's
+     * member included.
+     */
+    private readMethodExample;
     /** Issue a product request and return its 2xx answer, a non-2xx thrown as `ApiResponseError`. */
     private requestProductAnswer;
     private throwApiResponseError;
@@ -256,9 +318,11 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
     private readObjectAnswer;
     /**
      * The JSON body of a 2xx answer, naming the route by its `path` from the origin as a refusal
-     * does. A body that is not UTF-8, or not JSON, an empty one included, is an answer the SDK
-     * cannot read, so it throws the `ApiResponseError` `unreadableAnswer` builds, with the parse
-     * failure as `cause`.
+     * does, its text read by `parse`: `JSON.parse`, or `parseExactJson` for an answer carrying a
+     * person's data. A body that is not UTF-8, or not JSON, an empty one included, is an answer the
+     * SDK cannot read, so it throws the `ApiResponseError` `unreadableAnswer` builds, with the parse
+     * failure as `cause`; so is a body holding a number `parseExactJson` cannot read exactly on this
+     * runtime (`ExactJsonUnsupportedError`), rather than read rounded.
      * The one place a success body is parsed.
      */
     private readAnswerAt;
@@ -323,6 +387,9 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * that exceeds that surfaces as `PipelineExecuteTimeoutError` pointing at the
      * durable start+poll path. Throws `RunStillRunningError` on the protocol's
      * optional 202 degrade.
+     *
+     * The answer is read with `parseExactJson`, so an integer past `Number.MAX_SAFE_INTEGER` in the
+     * working memory, the main output included, is a `bigint` holding its exact digits.
      */
     execute(options: PipelexRunOptions): Promise<PipelexExecuteResult>;
     /**
@@ -337,6 +404,13 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * durable — poll `getRunStatus` / `getRunResult`. A `method_ref` run's ack
      * additionally carries `method_provenance` — the address, the tag, and the
      * commit SHA that was actually fetched.
+     *
+     * `options.idempotencyKey` is sent as the `Idempotency-Key` header, and nothing
+     * is sent without it: the hosted API answers the same start sent again under the
+     * same key with the run the first one started, so a failure whose
+     * `runMayHaveStarted` is true can be retried unchanged (see
+     * `PipelexStartRequestOptions`). A malformed key is a `RequestArgumentError`
+     * before anything is sent.
      */
     start(options: PipelexStartOptions): Promise<PipelexRunResultStart>;
     /**
@@ -638,6 +712,11 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * before any request. `MissingMainStuffError` is thrown only for a read that asked
      * for `main_stuff` — no selection, or one naming it.
      *
+     * A completed result is read with `parseExactJson`, so an integer past
+     * `Number.MAX_SAFE_INTEGER` anywhere in it, the main output, the working memory and the graph
+     * included, is a `bigint` holding its exact digits, and an output passed back to `start` goes
+     * back as the run produced it.
+     *
      * Throws `RunLifecycleUnavailableError` when the lifecycle routes are absent
      * (a bare runner).
      */
@@ -687,6 +766,12 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * up in the run history first. An error from the wait, once `onStarted` has named the run,
      * started nothing, so its `runMayHaveStarted` is false, and its `retryable` is about waiting
      * again on that id with `waitForResult`, never about calling this method again.
+     *
+     * `options.idempotencyKey` rides the durable start, so a call that failed while its start may
+     * have created a run can be made again with the same options and the same key: the hosted API
+     * answers the start with the run the first call started, and the wait follows it. The blocking
+     * execute of a bare runner carries no key, a bare runner having no idempotency to honour it. A
+     * malformed key is refused before the version handshake.
      */
     startAndWaitForResult(options: PipelexStartOptions, pollOptions?: StartAndWaitForResultOptions): Promise<RunResults>;
     /** The authenticated user's profile — `GET /v1/me`. */
@@ -746,7 +831,9 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * Takes a bare catalog id: the method routes address the method itself, never a version of
      * it. A caller holding `mt_…@3` strips the suffix with `parseMethodSelector` and reads that
      * version with `getMethodVersion`. Every method route throws `RequestArgumentError` for a
-     * suffixed id, before any request, rather than read back the `404` the platform would answer.
+     * suffixed id, before any request, rather than read back the `404` the platform would answer,
+     * and for an id that is empty, `.` or `..`, which the URL would resolve into another route's
+     * path.
      */
     getMethod(methodId: string): Promise<MethodData>;
     /**
@@ -894,6 +981,124 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * as `getMethod` does: the whole method is erased, never one of its versions.
      */
     deleteMethod(methodId: string): Promise<MethodDeletionAccepted>;
+    /**
+     * Save an example on a method — `POST /v1/methods/{id}/examples`: a named set of inputs, and
+     * with `run_id`, a run of this method that used exactly those inputs, recorded as its latest
+     * run. Answers the example as stored, at `input_revision` 1.
+     *
+     * Sends `name`, `inputs` and, when given, `run_id`, and nothing else: the route's body is
+     * closed, and a `null` `run_id` reads as not given. Throws `RequestArgumentError` before any
+     * request when `name` or `inputs` is not given (`null` counting as not given), and for a
+     * `run_id` that is given but is not a non-empty string. Throws `ApiResponseError`: `404`
+     * `run_not_found` for a `run_id` that is not one of this method's runs in the caller's
+     * organization, with nothing written; `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.
+     */
+    createMethodExample(methodId: string, input: MethodExampleCreateInput): Promise<MethodExample>;
+    /**
+     * One page of a method's examples, oldest first, inputs included —
+     * `GET /v1/methods/{id}/examples`.
+     *
+     * Pass the page's `nextCursor` back as `cursor` to continue; `null` is the last page. A page
+     * may be short while `nextCursor` is set, because the platform reads examples whole and stops
+     * a read at 1 MB; `iterateMethodExamples` follows the cursor for a caller that wants them all.
+     *
+     * Throws `ApiResponseError`: `400` `malformed_request` for a cursor the listing did not issue
+     * for this method, `422` for a `limit` outside 1 to 100, and the codes every example route
+     * answers. A page whose `items` is not an array, whose `next_cursor` is neither a string nor
+     * `null`, or one of whose items is not an example `readMethodExample` can read, is an answer
+     * the SDK cannot read, thrown as an `ApiResponseError` too. An example whose inputs hold an
+     * integer past the safe range is read like any other, that integer as a `bigint`.
+     */
+    listMethodExamples(methodId: string, query?: ListMethodExamplesQuery): Promise<MethodExamplePage>;
+    /**
+     * Every example of a method, oldest first, streamed — follows the cursor of
+     * `listMethodExamples` for you.
+     *
+     * ```ts
+     * for await (const example of client.iterateMethodExamples(methodId)) {
+     *   rerun(example); // stop whenever you like
+     * }
+     * ```
+     *
+     * An iterator rather than an all-at-once list, for the reason `iterateMethods` is one: a
+     * helper returning an array needs a page cap, and a cap returns a truncated list with no
+     * error. It runs the same loop as `iterateMethods` and `iterateRuns`, so it keeps going through
+     * a short or empty page that carries a cursor, stops on a `null` cursor or on a cursor the
+     * server failed to advance, and throws `PagingNotTerminatingError` past the same page ceiling.
+     *
+     * Throws `RequestArgumentError` at the call, before the iterator is pulled or anything is sent,
+     * for a method id `listMethodExamples` refuses: a suffixed one, or one that is empty, `.` or `..`
+     * or holds a lone surrogate.
+     */
+    iterateMethodExamples(methodId: string, query?: Omit<ListMethodExamplesQuery, "cursor">): AsyncGenerator<MethodExample, void, undefined>;
+    /**
+     * One example of a method — `GET /v1/methods/{id}/examples/{example_id}`, read consistently,
+     * so an example saved a moment ago is found.
+     *
+     * Throws `RequestArgumentError` for an example id that is empty, `.` or `..`, or holds a lone
+     * surrogate, before any request. Throws `ApiResponseError`: `422` for an example id longer
+     * than one can be (64 characters), and the codes every example route answers.
+     */
+    getMethodExample(methodId: string, exampleId: string): Promise<MethodExample>;
+    /**
+     * Rename an example, give it new inputs, or both —
+     * `PATCH /v1/methods/{id}/examples/{example_id}` — and return it as it now stands.
+     *
+     * **New inputs raise `input_revision` by one and clear `latest_run_id`**, since the run no
+     * longer shows what the inputs produce; inputs that are the same as the stored ones, their
+     * keys in another order included, change nothing, while `3` becoming `3.0` is a change. A
+     * rename alone keeps both. The edit takes no revision or token: the latest-run write is what
+     * the revision guards. Sends `name` and `inputs` when given, and nothing else; `null` reads as
+     * not given, as the platform reads it.
+     *
+     * **Send `inputs` only when they changed.** Inputs read from an example and sent back unchanged
+     * are a change for the platform when they hold a float with no fractional part, `3.0`, which
+     * JavaScript reads as `3` (see `MethodExample.inputs`): they raise the revision and clear the
+     * latest run. A rename sent alone never does. An integer past `Number.MAX_SAFE_INTEGER` is no
+     * such case: it reads as a `bigint` and is sent back as its exact digits.
+     *
+     * Throws `RequestArgumentError` before any request for an example id that is empty, `.` or
+     * `..`, or when neither `name` nor `inputs` is given. Throws `ApiResponseError`: `413`
+     * `payload_too_large` for inputs 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, a `503` that wrote
+     * nothing, safe to retry, when concurrent edits kept landing under the write, and the codes
+     * every example route answers.
+     */
+    updateMethodExample(methodId: string, exampleId: string, input: MethodExampleUpdateInput): Promise<MethodExample>;
+    /**
+     * Record a run as an example's latest —
+     * `PUT /v1/methods/{id}/examples/{example_id}/latest-run` — **only while the example still
+     * holds the revision whose inputs the run used**.
+     *
+     * `input_revision` is the example's `input_revision` the caller read when it started the run
+     * with the example's inputs; the platform trusts it and does not compare the run's own inputs.
+     * The answer is a `MethodExampleLatestRunResult` discriminated on `outcome` — branch on it:
+     * `recorded`, the run is now the example's latest; `stale`, the example's inputs were edited
+     * since and nothing was written. A stale run is the expected end of a run that outlasted an
+     * edit, so it is answered, never thrown. Both arms carry the `example` as it stands.
+     *
+     * Throws `RequestArgumentError` before any request, checking in this order: an example id that
+     * is empty, `.` or `..`, or holds a lone surrogate, a `run_id` that is not a non-empty string,
+     * and an `input_revision` that is not a positive integer. Throws `ApiResponseError` when no
+     * verdict was produced: `404` `not_found` for an example deleted since, `404` `run_not_found`
+     * for a run that is not one of this method's, with nothing written, 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, read as `publishMethod` reads its verdict.
+     */
+    recordMethodExampleLatestRun(methodId: string, exampleId: string, input: MethodExampleLatestRunInput): Promise<MethodExampleLatestRunResult>;
+    /**
+     * 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.
+     *
+     * Throws `RequestArgumentError` for an example id that is empty, `.` or `..`, before any
+     * request: `..` would address the method, and its erasure would answer the delete. Throws
+     * `ApiResponseError`: `404` `not_found` when there is no such example, one already deleted
+     * included, and the codes every example route answers.
+     */
+    deleteMethodExample(methodId: string, exampleId: string): Promise<void>;
     /** The caller's org memberships + active-org feature flags — `GET /v1/organizations/memberships`. */
     listMemberships(): Promise<MembershipsResponse>;
     /** Create an organization — `POST /v1/organizations`. */
@@ -1125,6 +1330,10 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * executed) and `inputs`. Kept off the status read, which pollers hit every
      * few seconds. A failed run's stored report, `error`, is checked field by
      * field (see `RunErrorReport`).
+     *
+     * Read with `parseExactJson`, so an integer past `Number.MAX_SAFE_INTEGER` in the inputs is a
+     * `bigint` holding its exact digits, and the inputs passed back to `start` or saved as an
+     * example's go back as the run used them.
      */
     getRunDetail(runId: string): Promise<RunDetail>;
     /** Patch a run's status (admin/manual) — `PUT /v1/runs/{id}`. */