@pipelex/sdk 0.39.0 → 0.41.0

package/README.md

@@ -102,6 +102,8 @@ const client = new PipelexApiClient({ apiKey: process.env.PIPELEX_API_KEY });
 
 const me = await client.getMe(); // GET /v1/me
 const page = await client.listMethods(); // GET /v1/methods — one page: { items, nextCursor }
+// Only the methods never published. A filtered page can be empty and still carry a nextCursor.
+const drafts = await client.listMethods({ published: false });
 for await (const method of client.iterateMethods()) {
   // follows the cursor for callers that genuinely want the whole catalog
 }
@@ -209,6 +211,7 @@ These pages ship inside the published package, so a reader who has only installe
 | [`docs/run-usage.md`](./docs/run-usage.md) | What a run consumed, record by record, and `summarizeUsage` which folds them into one reading |
 | [`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/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/bundle-resources.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The files a bundle's steps read, sent with the bundle as the request's `resources`.
+ *
+ * A bundle sent as content has no directory, so a file one of its steps reads from beside the
+ * bundle, such as a `PipeDocGen` step's `template_file`, has to travel with it. The runner takes
+ * such files as `resources`: a JSON object mapping each file's path, exactly as the step names it,
+ * relative to the bundle and written with forward slashes, to the file's bytes in standard padded
+ * base64. It takes them beside `mthds_contents` (or a method bundle) on `/v1/validate`,
+ * `/v1/execute` and `/v1/start`, and beside inline `files[]` on `/v1/pipe-io`, `/v1/resolve` and
+ * `/v1/codegen`. A caller hands this SDK the bytes, keyed by that path, and the SDK encodes them.
+ *
+ * The SDK refuses before any request what the runner refuses for certain about the keys, with the
+ * runner's own rule (`resource_path_refusal` in pipelex's `bundle_resource.py`): an empty path, a
+ * backslash, a colon, a NUL character, an absolute path, a `..` segment, a path naming no file,
+ * and two keys naming one file once `.` segments and repeated slashes collapse. Each is a
+ * `RequestArgumentError` naming the key, where the runner answers a `422` `InvalidResourcePath`.
+ * The sizes are left to the server, since a deployment configures them: 32 files, 5 MiB each and
+ * 10 MiB in all by default, a `413` `PayloadTooLarge` beyond, and 512 KiB in all for the `.html`
+ * template files, a `413` `BundleResourcesTooLargeError`. So is every rule that needs the parsed
+ * bundle: a file no step names is a `422` `BundleResourceNotNamedError`.
+ */
+/** The bytes of one file a bundle's steps read: the byte forms `uploadFile` takes. */
+export type BundleResourceBytes = Uint8Array | ArrayBuffer | Blob;
+/**
+ * The files a 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. `./templates/invoice.docx` names
+ * the same file, so only one of the two spellings may be given.
+ */
+export type BundleResources = Readonly<Record<string, BundleResourceBytes>>;
+/**
+ * Whether `resources` is a plain object, the one shape a map of paths to bytes takes: its
+ * prototype is `Object.prototype` or `null`. A `Map`, an array or a class instance is not one,
+ * and the encoder refuses it rather than reading it as a map with no file in it.
+ */
+export declare function isResourceMap(resources: unknown): resources is Record<string, unknown>;
+/**
+ * Whether `resources` carries at least one file. An absent, `null` or empty map carries none, so
+ * it is not sent, as an empty bundle encoding is not. A value that is not a plain object carries
+ * none either; the encoder refuses it.
+ */
+export declare function hasBundleResources(resources: unknown): boolean;
+/**
+ * Why `path` cannot name a file inside a bundle, or `undefined` when it can — the runner's rule,
+ * held by the key of a file sent with a bundle and by the path a step names.
+ */
+export declare function bundleResourcePathRefusal(path: string): string | undefined;
+/**
+ * The one spelling of a bundle-relative path the runner keys a file by: `.` segments and repeated
+ * slashes collapse, so `./templates//invoice.docx` is `templates/invoice.docx`. Only meaningful
+ * for a path {@link bundleResourcePathRefusal} accepts.
+ */
+export declare function canonicalBundleResourcePath(path: string): string;
+/**
+ * Encode `resources` for the wire: each key as given, each value as its bytes in standard padded
+ * base64. Returns `undefined` when there is nothing to send, so the key stays off the wire.
+ *
+ * Every key is checked before any value is read, so a refused path costs no read of a `Blob`.
+ *
+ * @throws {RequestArgumentError} `resources` is not a map of paths to bytes, a key cannot name a
+ *   file inside the bundle, two keys name one file, or a value is not bytes.
+ */
+export declare function encodeBundleResources(resources: BundleResources | null | undefined): Promise<Record<string, string> | undefined>;

package/dist/bundle-resources.js

@@ -0,0 +1,165 @@
+/**
+ * The files a bundle's steps read, sent with the bundle as the request's `resources`.
+ *
+ * A bundle sent as content has no directory, so a file one of its steps reads from beside the
+ * bundle, such as a `PipeDocGen` step's `template_file`, has to travel with it. The runner takes
+ * such files as `resources`: a JSON object mapping each file's path, exactly as the step names it,
+ * relative to the bundle and written with forward slashes, to the file's bytes in standard padded
+ * base64. It takes them beside `mthds_contents` (or a method bundle) on `/v1/validate`,
+ * `/v1/execute` and `/v1/start`, and beside inline `files[]` on `/v1/pipe-io`, `/v1/resolve` and
+ * `/v1/codegen`. A caller hands this SDK the bytes, keyed by that path, and the SDK encodes them.
+ *
+ * The SDK refuses before any request what the runner refuses for certain about the keys, with the
+ * runner's own rule (`resource_path_refusal` in pipelex's `bundle_resource.py`): an empty path, a
+ * backslash, a colon, a NUL character, an absolute path, a `..` segment, a path naming no file,
+ * and two keys naming one file once `.` segments and repeated slashes collapse. Each is a
+ * `RequestArgumentError` naming the key, where the runner answers a `422` `InvalidResourcePath`.
+ * The sizes are left to the server, since a deployment configures them: 32 files, 5 MiB each and
+ * 10 MiB in all by default, a `413` `PayloadTooLarge` beyond, and 512 KiB in all for the `.html`
+ * template files, a `413` `BundleResourcesTooLargeError`. So is every rule that needs the parsed
+ * bundle: a file no step names is a `422` `BundleResourceNotNamedError`.
+ */
+import { RequestArgumentError } from "./errors.js";
+import { bytesToBase64 } from "./upload.js";
+/**
+ * Whether `resources` is a plain object, the one shape a map of paths to bytes takes: its
+ * prototype is `Object.prototype` or `null`. A `Map`, an array or a class instance is not one,
+ * and the encoder refuses it rather than reading it as a map with no file in it.
+ */
+export function isResourceMap(resources) {
+    if (typeof resources !== "object" || resources === null)
+        return false;
+    const prototype = Object.getPrototypeOf(resources);
+    return prototype === Object.prototype || prototype === null;
+}
+/**
+ * Whether `resources` carries at least one file. An absent, `null` or empty map carries none, so
+ * it is not sent, as an empty bundle encoding is not. A value that is not a plain object carries
+ * none either; the encoder refuses it.
+ */
+export function hasBundleResources(resources) {
+    return isResourceMap(resources) && Object.keys(resources).length > 0;
+}
+/**
+ * Python's whitespace, the set `str.strip()` removes and `str.isspace()` accepts, which the
+ * runner's rule tests a path against. It differs from JavaScript's `trim()`: it holds the
+ * separators U+001C to U+001F and U+0085, and not the byte-order mark U+FEFF.
+ */
+const PYTHON_WHITESPACE = new Set([
+    0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x1c, 0x1d, 0x1e, 0x1f, 0x20, 0x85, 0xa0, 0x1680, 0x2000, 0x2001,
+    0x2002, 0x2003, 0x2004, 0x2005, 0x2006, 0x2007, 0x2008, 0x2009, 0x200a, 0x2028, 0x2029, 0x202f,
+    0x205f, 0x3000,
+]);
+/** Whether `path` holds nothing but Python's whitespace: `not path.strip()`, the runner's test. */
+function isBlankForPython(path) {
+    for (const character of path) {
+        if (!PYTHON_WHITESPACE.has(character.codePointAt(0)))
+            return false;
+    }
+    return true;
+}
+/**
+ * Why `path` cannot name a file inside a bundle, or `undefined` when it can — the runner's rule,
+ * held by the key of a file sent with a bundle and by the path a step names.
+ */
+export function bundleResourcePathRefusal(path) {
+    if (isBlankForPython(path))
+        return "it is empty";
+    if (path.includes("\\"))
+        return "it holds a backslash; write the path with forward slashes";
+    if (path.includes(":"))
+        return "it holds a colon";
+    if (path.includes("\0"))
+        return "it holds a NUL character";
+    if (path.startsWith("/"))
+        return "it is absolute; write it relative to the bundle";
+    const segments = pathSegments(path);
+    if (segments.includes(".."))
+        return "it leaves the bundle through a '..' segment";
+    if (segments.length === 0)
+        return "it names no file";
+    return undefined;
+}
+/**
+ * The one spelling of a bundle-relative path the runner keys a file by: `.` segments and repeated
+ * slashes collapse, so `./templates//invoice.docx` is `templates/invoice.docx`. Only meaningful
+ * for a path {@link bundleResourcePathRefusal} accepts.
+ */
+export function canonicalBundleResourcePath(path) {
+    return pathSegments(path).join("/");
+}
+function pathSegments(path) {
+    return path.split("/").filter((segment) => segment !== "" && segment !== ".");
+}
+/**
+ * Encode `resources` for the wire: each key as given, each value as its bytes in standard padded
+ * base64. Returns `undefined` when there is nothing to send, so the key stays off the wire.
+ *
+ * Every key is checked before any value is read, so a refused path costs no read of a `Blob`.
+ *
+ * @throws {RequestArgumentError} `resources` is not a map of paths to bytes, a key cannot name a
+ *   file inside the bundle, two keys name one file, or a value is not bytes.
+ */
+export async function encodeBundleResources(resources) {
+    if (resources === undefined || resources === null)
+        return undefined;
+    if (!isResourceMap(resources)) {
+        throw new RequestArgumentError("resources must be a plain object mapping each file's path, as the step names it, to the " +
+            `file's bytes; got ${describeValue(resources)}.`);
+    }
+    // Read once: a second read of a proxy or a getter could differ from the one checked.
+    const entries = Object.entries(resources);
+    if (entries.length === 0)
+        return undefined;
+    const pathByCanonical = new Map();
+    for (const [path] of entries) {
+        const refusal = bundleResourcePathRefusal(path);
+        if (refusal !== undefined) {
+            throw new RequestArgumentError(`resources key ${JSON.stringify(path)} cannot name a file inside the bundle: ${refusal}.`);
+        }
+        const canonical = canonicalBundleResourcePath(path);
+        const first = pathByCanonical.get(canonical);
+        if (first !== undefined) {
+            throw new RequestArgumentError(`resources keys ${JSON.stringify(first)} and ${JSON.stringify(path)} name the same file ` +
+                `"${canonical}": send it once.`);
+        }
+        pathByCanonical.set(canonical, path);
+    }
+    // A null prototype, so a key such as `__proto__` is an own property that reaches the wire.
+    const wire = Object.create(null);
+    for (const [path, value] of entries) {
+        wire[path] = bytesToBase64(await resourceBytes(path, value));
+    }
+    return wire;
+}
+async function resourceBytes(path, value) {
+    if (value instanceof Uint8Array)
+        return value;
+    if (value instanceof ArrayBuffer)
+        return new Uint8Array(value);
+    if (typeof Blob !== "undefined" && value instanceof Blob) {
+        return new Uint8Array(await value.arrayBuffer());
+    }
+    throw new RequestArgumentError(`resources[${JSON.stringify(path)}] must be the file's bytes (a Uint8Array, an ArrayBuffer ` +
+        `or a Blob); got ${describeValue(value)}.` +
+        (typeof value === "string"
+            ? " A string is read neither as a path nor as base64: read the file and pass its bytes."
+            : ""));
+}
+function describeValue(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "an array";
+    if (value instanceof Map)
+        return "a Map; pass Object.fromEntries(map)";
+    if (typeof value === "string")
+        return "a string";
+    if (typeof value === "object") {
+        const name = Object.getPrototypeOf(value)
+            ?.constructor?.name;
+        return typeof name === "string" && name !== "" ? `an instance of ${name}` : "an object";
+    }
+    return `a value of type ${typeof value}`;
+}
+//# sourceMappingURL=bundle-resources.js.map

package/dist/bundle-resources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle-resources.js","sourceRoot":"","sources":["../src/bundle-resources.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.39.0";
+export declare const SCRIPT_RUNNER = "npx --yes --no-update-notifier --loglevel=warn @pipelex/sdk@0.41.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/cli/source.d.ts

@@ -43,7 +43,8 @@ export interface DescribedPipe {
  * the same selection the run's input preparation makes.
  *
  * @throws {CommandError} When the method does not load, or the answer does not describe the pipe
- *   it selected. A refusal of the request itself propagates as the SDK's `ApiResponseError`.
+ *   it selected or describes it with an input form the walk or the template cannot read. A refusal
+ *   of the request itself propagates as the SDK's `ApiResponseError`.
  * @throws {Interrupted} When the person interrupts the wait.
  */
 export declare function describePipe(client: PipelexApiClient, source: MethodSource, pipe: string | undefined, interrupt: AbortSignal): Promise<DescribedPipe>;

package/dist/cli/source.js

@@ -5,6 +5,7 @@
  * bundle, and to the run as `mthds_contents`, in the same order. An address travels as
  * `method_ref` and a catalog id as `method_id`, both resolved by the server.
  */
+import { inputFormFault } from "../index.js";
 import { CommandError, EXIT_FAILED, untilInterrupted } from "./io.js";
 import { loadFailureLines, METHOD_DOES_NOT_LOAD_SENTENCE } from "./present.js";
 export function crateSelector(source) {
@@ -33,7 +34,8 @@ export function runSelector(source) {
  * the same selection the run's input preparation makes.
  *
  * @throws {CommandError} When the method does not load, or the answer does not describe the pipe
- *   it selected. A refusal of the request itself propagates as the SDK's `ApiResponseError`.
+ *   it selected or describes it with an input form the walk or the template cannot read. A refusal
+ *   of the request itself propagates as the SDK's `ApiResponseError`.
  * @throws {Interrupted} When the person interrupts the wait.
  */
 export async function describePipe(client, source, pipe, interrupt) {
@@ -58,12 +60,68 @@ export async function describePipe(client, source, pipe, interrupt) {
     const inputForm = report.input_form;
     if (typeof pipeRef !== "string" ||
         !isPlainObject(inputForm) ||
-        !isPlainObject(inputForm[pipeRef])) {
+        !Object.hasOwn(inputForm, pipeRef)) {
         throw new CommandError("the API's pipe I/O answer does not describe the pipe it selected.", {
             exitCode: EXIT_FAILED,
         });
     }
-    return { report, pipeRef, descriptor: inputForm[pipeRef] };
+    // The template is rendered from this entry, so it is checked as input preparation checks it,
+    // and then for what the template reads beyond the walk: a malformed entry would otherwise crash
+    // the rendering or print a template under made-up keys. The sentence is the Python command's,
+    // printed when its client cannot parse an entry, which cannot say where, so neither command
+    // names the fault. Python's closed models refuse more than this, such as a member the standard
+    // does not define, which the template never reads.
+    const entry = inputForm[pipeRef];
+    if (inputFormFault(entry) !== undefined || !templateReadable(entry)) {
+        throw new CommandError("the API's pipe I/O answer describes the pipe it selected with a malformed input form.", { exitCode: EXIT_FAILED });
+    }
+    return { report, pipeRef, descriptor: entry };
+}
+/**
+ * Whether an entry `inputFormFault` passed also holds what the inputs template reads beyond the
+ * walk, in a shape it can render: every node's `concept_ref` a string, its `refines` a list of
+ * strings, an enum's `choices` a list and a list's `item_count` a whole number of at least two,
+ * the last three when present. Members the template only tests for truth are not checked.
+ */
+function templateReadable(entry) {
+    return entry.fields.every(templateReadableNode);
+}
+function templateReadableNode(node) {
+    if (node.concept_ref !== undefined && typeof node.concept_ref !== "string")
+        return false;
+    if (node.refines !== undefined &&
+        node.refines !== null &&
+        !(Array.isArray(node.refines) && node.refines.every((ref) => typeof ref === "string"))) {
+        return false;
+    }
+    // Every kind is listed, so a kind a newer `mthds` pin adds stops the build here until the
+    // template's reads of it are checked, as it does in the walk's own table.
+    const kind = node.kind;
+    switch (kind) {
+        case "text":
+        case "prose":
+        case "date":
+        case "number":
+        case "boolean":
+        case "document":
+        case "image":
+        case "unknown":
+            return true;
+        case "object":
+            return templateReadable(node);
+        case "enum":
+            return Array.isArray(node.choices);
+        case "list":
+            return ((node.item_count === undefined ||
+                node.item_count === null ||
+                (Number.isInteger(node.item_count) && node.item_count >= 2)) &&
+                templateReadableNode(node.item));
+        default: {
+            // Unreachable: `inputFormFault` refused a kind outside the walk's table.
+            const unreachable = kind;
+            return unreachable;
+        }
+    }
 }
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);

package/dist/cli/source.js.map

@@ -1 +1 @@
-{"version":3,"file":"source.js","sourceRoot":"","sources":["../../src/cli/source.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"source.js","sourceRoot":"","sources":["../../src/cli/source.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAUH,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AACtE,OAAO,EAAE,gBAAgB,EAAE,6BAA6B,EAAE,MAAM,cAAc,CAAC;AAc/E,MAAM,UAAU,aAAa,CAAC,MAAoB;IAChD,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,KAAK,QAAQ;YACX,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;QAC/F,KAAK,SAAS;YACZ,OAAO,EAAE,UAAU,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC;QAC1C,KAAK,SAAS;YACZ,OAAO,EAAE,SAAS,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC;IAC1C,CAAC;AACH,CAAC;AAED,4CAA4C;AAC5C,MAAM,UAAU,WAAW,CAAC,MAAoB;IAC9C,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,KAAK,QAAQ;YACX,OAAO,EAAE,cAAc,EAAE,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QACtE,KAAK,SAAS;YACZ,OAAO,EAAE,UAAU,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC;QAC1C,KAAK,SAAS;YACZ,OAAO,EAAE,SAAS,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC;IAC1C,CAAC;AACH,CAAC;AASD;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,MAAwB,EACxB,MAAoB,EACpB,IAAwB,EACxB,SAAsB;IAEtB,MAAM,OAAO,GAAkB;QAC7B,GAAG,aAAa,CAAC,MAAM,CAAC;QACxB,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;KAClD,CAAC;IACF,MAAM,MAAM,GAAY,MAAM,gBAAgB,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,SAAS,CAAC,CAAC;IACxF,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,OAAO,MAAM,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QACnE,MAAM,IAAI,YAAY,CACpB,mFAAmF,EACnF;YACE,QAAQ,EAAE,WAAW;SACtB,CACF,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;QACrB,MAAM,IAAI,YAAY,CAAC,6BAA6B,EAAE;YACpD,QAAQ,EAAE,WAAW;YACrB,OAAO,EAAE,gBAAgB,CAAC,MAAM,CAAC,iBAAiB,EAAE,MAAM,CAAC,OAAO,CAAC;SACpE,CAAC,CAAC;IACL,CAAC;IACD,MAAM,MAAM,GAAG,MAAsC,CAAC;IACtD,MAAM,OAAO,GAAG,MAAM,CAAC,QAAQ,CAAC;IAChC,MAAM,SAAS,GAAY,MAAM,CAAC,UAAU,CAAC;IAC7C,IACE,OAAO,OAAO,KAAK,QAAQ;QAC3B,CAAC,aAAa,CAAC,SAAS,CAAC;QACzB,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,EAClC,CAAC;QACD,MAAM,IAAI,YAAY,CAAC,mEAAmE,EAAE;YAC1F,QAAQ,EAAE,WAAW;SACtB,CAAC,CAAC;IACL,CAAC;IACD,6FAA6F;IAC7F,gGAAgG;IAChG,8FAA8F;IAC9F,4FAA4F;IAC5F,+FAA+F;IAC/F,mDAAmD;IACnD,MAAM,KAAK,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;IACjC,IAAI,cAAc,CAAC,KAAK,CAAC,KAAK,SAAS,IAAI,CAAC,gBAAgB,CAAC,KAAgC,CAAC,EAAE,CAAC;QAC/F,MAAM,IAAI,YAAY,CACpB,uFAAuF,EACvF,EAAE,QAAQ,EAAE,WAAW,EAAE,CAC1B,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,KAA2C,EAAE,CAAC;AACtF,CAAC;AAED;;;;;GAKG;AACH,SAAS,gBAAgB,CAAC,KAA8B;IACtD,OAAQ,KAAK,CAAC,MAAyC,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC;AACtF,CAAC;AAED,SAAS,oBAAoB,CAAC,IAA6B;IACzD,IAAI,IAAI,CAAC,WAAW,KAAK,SAAS,IAAI,OAAO,IAAI,CAAC,WAAW,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACzF,IACE,IAAI,CAAC,OAAO,KAAK,SAAS;QAC1B,IAAI,CAAC,OAAO,KAAK,IAAI;QACrB,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,EACtF,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,0FAA0F;IAC1F,0EAA0E;IAC1E,MAAM,IAAI,GAAG,IAAI,CAAC,IAAiB,CAAC;IACpC,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,MAAM,CAAC;QACZ,KAAK,OAAO,CAAC;QACb,KAAK,MAAM,CAAC;QACZ,KAAK,QAAQ,CAAC;QACd,KAAK,SAAS,CAAC;QACf,KAAK,UAAU,CAAC;QAChB,KAAK,OAAO,CAAC;QACb,KAAK,SAAS;YACZ,OAAO,IAAI,CAAC;QACd,KAAK,QAAQ;YACX,OAAO,gBAAgB,CAAC,IAAI,CAAC,CAAC;QAChC,KAAK,MAAM;YACT,OAAO,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACrC,KAAK,MAAM;YACT,OAAO,CACL,CAAC,IAAI,CAAC,UAAU,KAAK,SAAS;gBAC5B,IAAI,CAAC,UAAU,KAAK,IAAI;gBACxB,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,UAAU,CAAC,IAAK,IAAI,CAAC,UAAqB,IAAI,CAAC,CAAC,CAAC;gBAC1E,oBAAoB,CAAC,IAAI,CAAC,IAA+B,CAAC,CAC3D,CAAC;QACJ,OAAO,CAAC,CAAC,CAAC;YACR,yEAAyE;YACzE,MAAM,WAAW,GAAU,IAAI,CAAC;YAChC,OAAO,WAAW,CAAC;QACrB,CAAC;IACH,CAAC;AACH,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACnC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC"}

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`.
@@ -356,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
@@ -364,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.
      *
@@ -418,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
@@ -432,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.
@@ -526,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
@@ -535,10 +593,11 @@ 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>;
     /**
@@ -646,7 +705,11 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * Rows are `MethodSummary`: no `mthds`, no `python`, no `updated_at`. Reach
      * for `getMethod(id)` when you need a method's source.
      *
-     * `q` is applied server-side over the whole catalog, not over the page.
+     * `q` is applied server-side over the whole catalog, not over the page, and so is
+     * `published` (`true` for the methods with a published version, `false` for those never
+     * published). Each row carries the method's publish state (`latest_version`,
+     * `latest_published`, `draft_digest`). Both filters run after the index read, so a page can
+     * come back empty and still carry a `nextCursor`: keep following it until it is `null`.
      */
     listMethods(query?: ListMethodsQuery): Promise<MethodPage>;
     /**
@@ -667,6 +730,11 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * TRUNCATED list with no error — precisely the bug paging was introduced to
      * remove. If you truly want an array, `Array.fromAsync` makes that your
      * explicit choice.
+     *
+     * It keeps going **through an empty page that carries a cursor**: under `q` or `published`
+     * such a page means "nothing matched in the slice just read", not "done". It stops on a
+     * `null` cursor or on a cursor the server failed to advance, and throws
+     * `PagingNotTerminatingError` past a page ceiling no real catalog reaches.
      */
     iterateMethods(query?: Omit<ListMethodsQuery, "cursor">): AsyncGenerator<MethodSummary, void, undefined>;
     /**
@@ -965,7 +1033,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).
@@ -976,8 +1045,11 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * 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`.
      *
-     * With `allowUploads: false` it uploads nothing and reads no file: a value that
-     * would need an upload throws `UploadNotAllowedError`, naming the input.
+     * 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>;
     /**
@@ -1002,6 +1074,13 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * conditions, so a bounded page genuinely reads less. They are INSTANTS,
      * not days — see `ListRunsQuery`.
      *
+     * `createdBy: "me"` keeps the caller's own runs and `status` the runs in any of the given
+     * statuses, sent as `created_by=me` and one repeated `status=` parameter per status. Both are
+     * filters applied after the index read, so a filtered page can hold fewer runs than `limit`,
+     * or none, and still carry a `nextCursor`: an empty page is not the end, a `null` cursor is.
+     * An empty `status` list, or a name that is no `RunStatus`, is a `RequestArgumentError`
+     * before any request.
+     *
      * Takes a bare catalog id: the history files the runs of every version and
      * of the draft together under it, so `mt_…@3` names no history of its own
      * and the platform refuses it with a `400`. Strip a suffix with
@@ -1031,6 +1110,11 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * when to stop, and only one page is ever in memory. If you truly want an
      * array, `Array.fromAsync` makes that your explicit choice.
      *
+     * It keeps going **through an empty page that carries a cursor**: under `createdBy` or
+     * `status` such a page means "nothing matched in the slice just read", not "done". It stops on
+     * a `null` cursor or on a cursor the server failed to advance, and throws
+     * `PagingNotTerminatingError` past a page ceiling no real history reaches.
+     *
      * Takes a bare catalog id, as `listRuns` does.
      */
     iterateRuns(methodId: string, query?: Omit<ListRunsQuery, "cursor">): AsyncGenerator<RunHistoryItem, void, undefined>;