@pipelex/sdk 0.38.0 → 0.40.0

package/dist/client.d.ts

@@ -4,6 +4,7 @@ import { type GetRunResultOptions, type RunRead, type RunResults, type RunResult
 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 { AppInfo } from "./user-agent.js";
 import type { UploadableAsset, UploadFileOptions, UploadRecord } from "./upload.js";
+import type { BundleResources } from "./bundle-resources.js";
 import type { PrepareInputsRequest, PreparedInputs } from "./prepare-inputs.js";
 import type { BulkResolveStorageUrlsInput, BulkResolvedStorageUrls, DownloadArtifactsRequest, DownloadArtifactsResult, FetchArtifactOptions, ResolvedArtifact } from "./artifacts.js";
 import { PipelexExecuteResult } from "./execute-result.js";
@@ -14,10 +15,11 @@ export interface MthdsFile {
     uri?: string;
 }
 /**
- * The Pipelex API's own run-source extension — the layer-2 argument the RUNNER
- * itself resolves, beside the protocol's inline sources (`mthds_contents` and
- * the bundle encodings). Served by any pipelex-api >= 0.21.0 deployment, bare
- * or hosted (on `api.pipelex.com`, once the platform deploy carrying it lands).
+ * The Pipelex API's own run arguments — the layer-2 arguments the RUNNER itself
+ * reads, beside the protocol's inline sources (`mthds_contents` and the bundle
+ * encodings): the `method_ref` run source, served by any pipelex-api >= 0.21.0
+ * deployment, bare or hosted (on `api.pipelex.com`, once the platform deploy
+ * carrying it lands), and the `resources` the bundle's steps read.
  *
  * Named options rather than `extra` entries, for the same reason as the hosted
  * extensions below: `extra` remains the escape hatch for an extension this
@@ -43,6 +45,20 @@ export interface PipelexApiRunExtensions {
      * An empty string is treated as absent and is not sent.
      */
     method_ref?: string | null;
+    /**
+     * The files the bundle's steps read, such as a `PipeDocGen` step's `template_file`, keyed
+     * by the path the step names (`templates/invoice.docx`), each as its bytes (a `Uint8Array`,
+     * a Node `Buffer` included, an `ArrayBuffer` or a `Blob`). The client sends them as the
+     * wire's `resources`, each file in standard base64; see `docs/bundle-resources.md`.
+     *
+     * They accompany the bundle whose steps read them: inline `mthds_contents` or a method
+     * bundle (`files` / `bundle_b64`), or a hosted `method_id` the platform resolves. Beside a
+     * `method_ref` (whose files are its package's own), or with no source at all, they are
+     * rejected client-side, mirroring the server's `422`. A key that cannot name a file inside
+     * the bundle (absolute, a `..` segment, a backslash, a colon) is rejected client-side too.
+     * An absent, `null` or empty map is not sent.
+     */
+    resources?: BundleResources | null;
 }
 /**
  * The hosted API's own run arguments — the layer-3 extensions this client adds
@@ -104,6 +120,32 @@ export interface ValidateFilesOptions {
     render?: string[];
     /** Optional structured-view opt-in tokens, e.g. ["input_form", "output_form"]; sent only when given. */
     views?: string[];
+    /**
+     * The files the bundle's steps read, such as a `PipeDocGen` step's `template_file`, keyed by
+     * the path the step names, each as its bytes; sent as `resources` (see {@link ValidateOptions}).
+     */
+    resources?: BundleResources | null;
+    /**
+     * Per-call request ceiling; defaults to the 20-min execute ceiling. A positive number
+     * no larger than 2147483647, the longest delay a timer honours, else a `RangeError`.
+     */
+    timeoutMs?: number;
+    /** Caller-driven cancellation; the abort reason propagates untouched. */
+    signal?: AbortSignal;
+}
+/** `validate()`'s last argument: what rides beside the method, and the call's own transport. */
+export interface ValidateOptions {
+    /**
+     * The files the bundle's steps read, such as a `PipeDocGen` step's `template_file`, keyed by
+     * the path the step names (`templates/invoice.docx`), each as its bytes (a `Uint8Array`, a
+     * Node `Buffer` included, an `ArrayBuffer` or a `Blob`). Sent as the wire's `resources`, each
+     * file in standard base64; see `docs/bundle-resources.md`. They accompany inline contents, or
+     * a hosted `{ method_id }` the platform resolves; beside a `{ method_ref }` they are rejected
+     * client-side, mirroring the server's `422`. A step whose template file was not sent makes the
+     * verdict invalid, saying so; the dry run checks an office template file it was sent and adds
+     * its findings to the valid arm's `warnings` (`template_check_warning`).
+     */
+    resources?: BundleResources | null;
     /**
      * Per-call request ceiling; defaults to the 20-min execute ceiling. A positive number
      * no larger than 2147483647, the longest delay a timer honours, else a `RangeError`.
@@ -161,7 +203,8 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * DNS/connect/TLS/timeout failures as `ApiUnreachableError`; a caller-driven
      * abort (Ctrl-C / agent walk-away) propagates as-is so the poll loop can stop
      * cleanly. Non-2xx interpretation is left to the caller. `url` is a fully
-     * resolved absolute URL.
+     * resolved absolute URL. `mayStartRun` marks a request that may create a run,
+     * whose `ApiUnreachableError` then says whether it may have (see `RunCreation`).
      */
     private requestRaw;
     /**
@@ -230,6 +273,7 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * `API <method> <path> answered <status> with <what>`: the answer's status, its raw text as
      * `responseBody`, no problem member but the `X-Request-ID` header, the failure that made it
      * unreadable as `cause`, and the verdict the fallback gives a 2xx, `runtime` and not retryable.
+     * On a request that may create a run, the run may have started: the server accepted it.
      */
     private unreadableAnswer;
     /**
@@ -249,6 +293,11 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * error. Hosted does not emit 202 today, but the protocol permits it;
      * raising a typed error (with the `pipeline_run_id` + `Location` + `Retry-After`
      * hints) beats a generic parse failure on an unexpected body shape.
+     *
+     * The 202 must name the run it accepted, as `start`'s acknowledgement must: one whose body is
+     * not JSON, or names no run (an empty id included), leaves the caller a run it cannot follow, so it is an answer the
+     * SDK cannot read, which may have started a run, never a `RunStillRunningError` without an id.
+     * The Python SDK reads the same answers the same way.
      */
     private throwIfExecuteDegraded;
     /**
@@ -349,6 +398,15 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * the field regardless — which is why `PipelexValidationReport.input_form` is typed
      * optional rather than required.
      *
+     * `options.resources` sends the files the bundle's steps read, such as a
+     * `PipeDocGen` step's `template_file`, keyed by the path the step names, each as
+     * its bytes (see {@link ValidateOptions}). A step whose template file was not sent
+     * is an `is_valid: false` verdict saying so, and a template check's findings in an
+     * office template file ride the valid arm's `warnings`. A key no step names, or
+     * files over the server's limits, are no-verdict refusals: a `422`
+     * `BundleResourceNotNamedError`, a `413` `PayloadTooLarge` or
+     * `BundleResourcesTooLargeError`.
+     *
      * A `{ method_ref }` source makes the server clone a repository before it
      * validates anything, and it needs no special budget here: this route already
      * defaults to the 20-minute execute ceiling, which clears the internal
@@ -357,10 +415,7 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * exists to RAISE routes whose default is the ~30s poll ceiling; applying it here
      * would lower this one.
      */
-    validate(source: string[] | ValidateMethodSelector, allowSignatures?: boolean, mthdsSources?: string[], render?: string[], views?: string[], options?: {
-        timeoutMs?: number;
-        signal?: AbortSignal;
-    }): Promise<PipelexValidationResult>;
+    validate(source: string[] | ValidateMethodSelector, allowSignatures?: boolean, mthdsSources?: string[], render?: string[], views?: string[], options?: ValidateOptions): Promise<PipelexValidationResult>;
     /**
      * Validate paired MTHDS files while preserving URI attribution for diagnostics.
      *
@@ -411,10 +466,11 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * never on a message.
      *
      * All of these are static and inference-free, so they default to the management-call
-     * timeout. The one internal raise is the fetch-sized budget `crateRequestTimeoutMs`
-     * gives a crate route whose closure is a `method_ref`, because the server may clone a
-     * repository before it answers; it is matched to what the server does, not a
-     * caller-facing parameter.
+     * timeout. The internal raises are `crateRequestTimeoutMs`'s: the fetch-sized budget a
+     * crate route gets when its closure is a `method_ref`, because the server may clone a
+     * repository before it answers, and the execute ceiling it gets when the request
+     * carries `resources`, whose upload alone can outlast the default. Each is matched to
+     * what the request costs, not a caller-facing parameter.
      *
      * **These routes deliberately expose no `timeoutMs` / `signal`, and that is not an
      * oversight to be "fixed" per route.** Automated reviewers have proposed adding them
@@ -425,8 +481,11 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      *    ceiling and takes caller transport options; every extension route rides the
      *    static core. Giving one static route an override while its siblings lack one is
      *    the inconsistency.
-     * 2. The input is **bounded server-side** — the runner's `pipelex_api/limits.py` caps a request
-     *    at 16 `.mthds` files of 1 MiB each — and none of these routes runs inference.
+     * 2. The input is **bounded server-side** — the runner's `pipelex_api/limits.py` caps the
+     *    `.mthds` files of a request and the files sent with them in `resources`, each by a
+     *    count, a size per file and, for `resources`, a total, all configurable per
+     *    deployment — and none of these routes runs inference. The upload those limits allow
+     *    is what `crateRequestTimeoutMs` budgets for, not the server's work.
      * 3. On the hosted path an override would be **inert**: the gateway caps responses at
      *    ~30s (see `POLL_REQUEST_TIMEOUT_MS` above), so raising `timeoutMs` would still be
      *    cut off upstream, just with a less honest error.
@@ -519,8 +578,14 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * describes every pipe instead, and never refuses for want of an entry pipe.
      * `include_files: true` echoes the resolved closure's `.mthds` files as `files`.
      *
+     * Beside inline `files`, `resources` sends the files the closure's steps read, such as a
+     * `PipeDocGen` step's `template_file`, keyed by the path the step names, each as its bytes;
+     * a step whose template file was not sent makes the closure invalid. `resolve` and `codegen`
+     * take it too (see {@link CrateRequestBase}).
+     *
      * Same 200-verdict discipline and same three-form closure selector as {@link resolve}
-     * (the request is posted verbatim, and the selector XOR is the server's to enforce).
+     * (the request is posted as given, its `resources` encoded to base64, and the selector XOR
+     * and the `resources` pairing are the server's to enforce).
      * Only a no-verdict condition throws `ApiResponseError`: a malformed selector and an
      * over-limit file are `ValidationError` `422`s; a selection the route refuses is a
      * `422` whose `errorType` is `EntryPipeNotFoundError` (an unknown `pipe_ref`, no entry
@@ -528,22 +593,28 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * candidates in its `serverMessage`; a registry-form `method_ref` is a `501`; a pipe
      * whose artifacts cannot be derived is a `500`.
      *
-     * A `method_ref` gets the fetch-sized budget, as on the other crate routes. On the
-     * hosted API the gateway caps a request at about 30 seconds whatever the client
-     * allows, so a cold `method_ref` clone can answer a `502` that a retry clears once the
-     * runner has cached the clone.
+     * A `method_ref` gets the fetch-sized budget, as on the other crate routes, and a
+     * request carrying `resources` the execute ceiling, since their upload alone can
+     * outlast the default. On the hosted API the gateway caps a request at about 30
+     * seconds whatever the client allows, so a cold `method_ref` clone can answer a `502`
+     * that a retry clears once the runner has cached the clone.
      */
     pipeIo(request: PipeIORequest): Promise<PipeIOResponse>;
     /**
      * Fetch a run's status by bare id — `GET /v1/runs/{pipeline_run_id}/status`.
      *
      * Self-healing: a finished-but-unrecorded run resolves to its true terminal
-     * status on read. `degraded: true` means Temporal was unreachable and
-     * `status` is the last-known value; `retry_after_seconds` carries the
-     * server's backoff hint when present. A failed run's stored report, `error`,
-     * is checked field by field (see `RunErrorReport`). Throws
-     * `RunLifecycleUnavailableError` when the lifecycle routes are absent (a bare
-     * runner).
+     * status on read. `degraded: true` means the read is not a plain fresh reading,
+     * and `degradation.reason` says why (see `DegradationReason`):
+     * `status_unavailable` when the platform could not reach the workflow engine
+     * and `status` is the last one recorded, `workflow_task_failing` when `status`
+     * is live and the run is stuck, its workflow task failing until the platform
+     * ends it at `degradation.ends_at`. `retry_after_seconds` carries the server's
+     * `Retry-After` hint when present, and `request_id` the id to quote to support.
+     * A failed run's stored report, `error`, and the `degradation` are each
+     * checked field by field (see `RunErrorReport` and `RunDegradation`), so
+     * neither ever fails the read. Throws `RunLifecycleUnavailableError` when the
+     * lifecycle routes are absent (a bare runner).
      */
     getRunStatus(runId: string, options?: {
         signal?: AbortSignal;
@@ -609,6 +680,13 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * `pollOptions.signal` is also read before the run is created: a caller that aborts while the
      * version handshake is in flight gets its abort, and neither the start nor the blocking execute
      * is sent. Once one of them is sent, the abort stops only the wait.
+     *
+     * An error from the start, or from the blocking execute, says whether that request may still
+     * have started a run whose id never reached the caller (`runMayHaveStarted`); when it may have,
+     * it is not retryable, since calling this method again could pay for the run twice: look the run
+     * 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.
      */
     startAndWaitForResult(options: PipelexStartOptions, pollOptions?: StartAndWaitForResultOptions): Promise<RunResults>;
     /** The authenticated user's profile — `GET /v1/me`. */
@@ -946,7 +1024,8 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * Name the method exactly one of three ways, all server-resolved through the
      * one `pipeIo` call this composes:
      *
-     * - `files` — the inline MTHDS closure;
+     * - `files` — the inline MTHDS closure, with the `resources` its steps read
+     *   (a `PipeDocGen` step's `template_file`), keyed by the path a step names;
      * - `method_ref` — a published method's address, fetched by the runner;
      * - `method_id` — a stored method's catalog id, resolved by the platform
      *   (hosted only; requires an API key).
@@ -956,6 +1035,12 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * answers with, which states the kind of every input at every depth, so a file
      * position is a fact of the method, never a guess from the value's shape. It
      * needs an API serving `POST /v1/pipe-io`. See `docs/input-preparation.md`.
+     *
+     * A value at a file input that cannot be a file, such as a number or a
+     * `data:` URL that does not decode, throws `InvalidInputValueError`, naming the
+     * input. With `allowUploads: false` it uploads nothing and reads no file: a
+     * value that would need an upload throws `UploadNotAllowedError`, naming the
+     * input too.
      */
     prepareInputs(request: PrepareInputsRequest): Promise<PreparedInputs>;
     /**
@@ -1050,8 +1135,9 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
  * `is_gateway_cut_off` reads the same failures, its `ABORT_TIMEOUT` being httpx's read or write
  * timeout.
  *
- * The blocking `execute` turns such a failure into a `PipelineExecuteTimeoutError`. A caller timing
- * a request that may create a run, such as `start` from `startAndWaitForResult`'s `onStarting`,
- * reads it to know the server may still be handling the request the gateway gave up on.
+ * The blocking `execute` turns such a failure into a `PipelineExecuteTimeoutError`. Whether a
+ * failed `start` or `execute` may have started a run needs no timing: the error says it as
+ * `runMayHaveStarted`, which reads every `503` but the platform's coded one as a run that may
+ * have started, however quickly it came back.
  */
 export declare function isGatewayCutOff(error: unknown, elapsedMs: number): boolean;