@pipelex/sdk 0.3.1 → 0.5.0

package/dist/prepare-inputs.js

@@ -0,0 +1,178 @@
+/**
+ * `prepareInputs` — signature-driven input preparation. Resolves the target
+ * pipe's declared inputs via the explicit inputs template, interprets the
+ * caller's compact inputs top-down against it, uploads the file-bearing values,
+ * and returns rewritten inputs (canonical content carrying `pipelex-storage://`
+ * in `url`) plus one upload record per prepared asset.
+ *
+ * The classification mirrors the runtime: `pipelex`'s `input_normalizer` walks
+ * Image/Document contents (recognized by their `url`-bearing shape, incl. nested
+ * in structured content) and `resolve_uri` decides upload vs pass-through. The
+ * declared signature comes from the explicit template (`buildInputs`,
+ * `explicit: true`), whose canonical content shape is the classifier — the file
+ * signal is a value that is a dict containing a `url` key. See the shared
+ * behavior matrix (`wip/upload/behavior-matrix.md`) and `docs/input-preparation.md`.
+ */
+import { InputPreparationError } from "./errors.js";
+import { uploadFile } from "./upload.js";
+const PIPELEX_STORAGE_SCHEME = "pipelex-storage://";
+const HTTP_URL_RE = /^https?:\/\//i;
+/** Strict plain-object test — excludes arrays, `Uint8Array`, `Blob`, and other exotics. */
+function isPlainObject(value) {
+    return Object.prototype.toString.call(value) === "[object Object]";
+}
+/** A canonical Image/Document content is a plain object carrying a `url` key. */
+function isFileContent(node) {
+    return isPlainObject(node) && "url" in node;
+}
+/** Decode a `data:` URL into bytes plus its MIME type. */
+function decodeDataUrl(dataUrl) {
+    const comma = dataUrl.indexOf(",");
+    if (comma < 0) {
+        throw new InputPreparationError(`Malformed data URL (no comma separator): ${dataUrl.slice(0, 32)}…`);
+    }
+    const header = dataUrl.slice(5, comma); // strip "data:"
+    const payload = dataUrl.slice(comma + 1);
+    const isBase64 = /;base64/i.test(header);
+    const contentType = header.split(";")[0] || "application/octet-stream";
+    // Decoding can throw on a malformed payload — a URIError from percent-decoding,
+    // or an InvalidCharacterError from `atob` on bad base64. Surface those as a typed
+    // InputPreparationError so a bad data URL stays within the preparation contract.
+    try {
+        if (isBase64) {
+            // Decode via atob in every runtime. atob rejects malformed base64 with an
+            // InvalidCharacterError — Buffer.from(payload, "base64") does NOT: in Node it
+            // silently drops invalid characters and returns truncated/empty bytes, which would
+            // upload corrupt content instead of failing the preparation contract. atob is a
+            // global in every supported runtime (engines.node >= 22.12).
+            return { bytes: base64ToBytes(payload), contentType };
+        }
+        const text = decodeURIComponent(payload);
+        return { bytes: new TextEncoder().encode(text), contentType };
+    }
+    catch (cause) {
+        throw new InputPreparationError(`Malformed data URL payload (${isBase64 ? "invalid base64" : "invalid percent-encoding"}): ${dataUrl.slice(0, 32)}…`, { cause });
+    }
+}
+/**
+ * Strict cross-runtime base64 decode via `atob` — the single decoder for data-URL
+ * payloads in every runtime. `atob` throws an `InvalidCharacterError` on malformed
+ * base64, unlike the lenient `Buffer.from(payload, "base64")`, so a bad payload
+ * fails the preparation contract instead of yielding truncated/empty bytes.
+ */
+function base64ToBytes(base64) {
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index += 1)
+        bytes[index] = binary.charCodeAt(index);
+    return bytes;
+}
+/** Resolve one source (string reference or bytes) to the URL/URI to write, deduped by identity. */
+function resolveSource(ctx, source) {
+    const cached = ctx.dedup.get(source);
+    if (cached !== undefined)
+        return cached;
+    const pending = doResolveSource(ctx, source);
+    ctx.dedup.set(source, pending);
+    return pending;
+}
+async function doResolveSource(ctx, source) {
+    if (typeof source === "string") {
+        if (source.startsWith(PIPELEX_STORAGE_SCHEME))
+            return source; // already prepared
+        if (HTTP_URL_RE.test(source))
+            return source; // reachable URL — pass through
+        if (source.startsWith("data:")) {
+            const { bytes, contentType } = decodeDataUrl(source);
+            const record = await uploadFile(ctx.client, bytes, { contentType });
+            ctx.uploads.push(record);
+            return record.uri;
+        }
+        // Anything else is a local filesystem path — Node only (uploadFile enforces it).
+        const record = await uploadFile(ctx.client, source);
+        ctx.uploads.push(record);
+        return record.uri;
+    }
+    if (source instanceof Blob || source instanceof ArrayBuffer || source instanceof Uint8Array) {
+        const record = await uploadFile(ctx.client, source);
+        ctx.uploads.push(record);
+        return record.uri;
+    }
+    // An unrecognized value sits at a file-bearing position (neither a source string,
+    // bytes, nor a canonical `{url}` content dict). Fail with a typed error rather than
+    // letting a raw TypeError escape from the byte-extraction path.
+    throw new InputPreparationError(`Unsupported value at a file input: expected a path string, bytes (Blob/File/ArrayBuffer/Uint8Array), ` +
+        `a data URL, an http(s)/pipelex-storage:// URL, or canonical {url} content; got ${typeof source}.`);
+}
+/** Resolve a value known to sit at a file position into canonical content with a rewritten `url`. */
+async function resolveFilePosition(ctx, callerValue) {
+    if (isFileContent(callerValue)) {
+        const resolved = await resolveSource(ctx, callerValue.url);
+        return { ...callerValue, url: resolved };
+    }
+    const resolved = await resolveSource(ctx, callerValue);
+    return { url: resolved };
+}
+/** Template-guided walk: a template node that is canonical file content marks a file position. */
+async function resolveNode(ctx, templateNode, callerValue) {
+    if (isFileContent(templateNode)) {
+        return resolveFilePosition(ctx, callerValue);
+    }
+    if (Array.isArray(templateNode) && templateNode.length > 0) {
+        const elementTemplate = templateNode[0];
+        if (Array.isArray(callerValue)) {
+            return Promise.all(callerValue.map((item) => resolveNode(ctx, elementTemplate, item)));
+        }
+        return callerValue; // shape mismatch — leave it for the run to reject
+    }
+    if (isPlainObject(templateNode) && isPlainObject(callerValue)) {
+        const result = { ...callerValue };
+        for (const key of Object.keys(templateNode)) {
+            if (key in callerValue) {
+                result[key] = await resolveNode(ctx, templateNode[key], callerValue[key]);
+            }
+        }
+        return result;
+    }
+    return callerValue; // scalar (text/number/…) or shape mismatch — pass through
+}
+/**
+ * Prepare a pipe's inputs: upload local/byte/data-URL assets at the signature's
+ * file-bearing positions and return copy-on-write rewritten inputs plus upload
+ * records. HTTP(S) URLs and existing `pipelex-storage://` URIs pass through
+ * unchanged. All failures are raised before any run is created.
+ *
+ * The declared signature is resolved from the closure; a closure that does not
+ * resolve throws {@link InputPreparationError}. No-verdict conditions from the
+ * signature route (unknown `pipe_ref`, auth, server fault) surface as the build
+ * route's `ApiResponseError`.
+ */
+export async function prepareInputs(client, request) {
+    const report = await client.buildInputs({
+        files: request.files,
+        ...(request.pipe_ref === undefined ? {} : { pipe_ref: request.pipe_ref }),
+        format: "json",
+        explicit: true,
+    });
+    if (!report.is_valid) {
+        const first = report.validation_errors[0]?.message ?? report.message;
+        throw new InputPreparationError(`Cannot prepare inputs: the method signature did not resolve — ${first}`);
+    }
+    // We requested `format: "json"`, so the valid arm carries the envelope in `inputs`.
+    if (report.format !== "json") {
+        throw new InputPreparationError(`Cannot prepare inputs: expected a JSON inputs template, got "${report.format}".`);
+    }
+    const template = report.inputs;
+    const ctx = { client, uploads: [], dedup: new Map() };
+    const rewritten = { ...request.inputs };
+    for (const [name, callerValue] of Object.entries(request.inputs)) {
+        const entry = template[name];
+        if (!isPlainObject(entry) || !("content" in entry)) {
+            // Not a declared input (or an unexpected envelope) — pass through untouched.
+            continue;
+        }
+        rewritten[name] = await resolveNode(ctx, entry.content, callerValue);
+    }
+    return { inputs: rewritten, uploads: ctx.uploads };
+}
+//# sourceMappingURL=prepare-inputs.js.map

package/dist/prepare-inputs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prepare-inputs.js","sourceRoot":"","sources":["../src/prepare-inputs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAGpD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,MAAM,sBAAsB,GAAG,oBAAoB,CAAC;AACpD,MAAM,WAAW,GAAG,eAAe,CAAC;AAsCpC,2FAA2F;AAC3F,SAAS,aAAa,CAAC,KAAc;IACnC,OAAO,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,iBAAiB,CAAC;AACrE,CAAC;AAED,iFAAiF;AACjF,SAAS,aAAa,CAAC,IAAa;IAClC,OAAO,aAAa,CAAC,IAAI,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC;AAC9C,CAAC;AAED,0DAA0D;AAC1D,SAAS,aAAa,CAAC,OAAe;IACpC,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACnC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QACd,MAAM,IAAI,qBAAqB,CAC7B,4CAA4C,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CACpE,CAAC;IACJ,CAAC;IACD,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,gBAAgB;IACxD,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;IACzC,MAAM,QAAQ,GAAG,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACzC,MAAM,WAAW,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,0BAA0B,CAAC;IACvE,gFAAgF;IAChF,kFAAkF;IAClF,iFAAiF;IACjF,IAAI,CAAC;QACH,IAAI,QAAQ,EAAE,CAAC;YACb,0EAA0E;YAC1E,8EAA8E;YAC9E,mFAAmF;YACnF,gFAAgF;YAChF,6DAA6D;YAC7D,OAAO,EAAE,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,EAAE,WAAW,EAAE,CAAC;QACxD,CAAC;QACD,MAAM,IAAI,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;QACzC,OAAO,EAAE,KAAK,EAAE,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,WAAW,EAAE,CAAC;IAChE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,qBAAqB,CAC7B,+BAA+B,QAAQ,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,0BAA0B,MAAM,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,EACpH,EAAE,KAAK,EAAE,CACV,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,SAAS,aAAa,CAAC,MAAc;IACnC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;IAC5B,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC5C,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC;QAAE,KAAK,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;IAC/F,OAAO,KAAK,CAAC;AACf,CAAC;AAED,mGAAmG;AACnG,SAAS,aAAa,CAAC,GAAmB,EAAE,MAAe;IACzD,MAAM,MAAM,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACrC,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC;IACxC,MAAM,OAAO,GAAG,eAAe,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IAC7C,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,KAAK,UAAU,eAAe,CAAC,GAAmB,EAAE,MAAe;IACjE,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC/B,IAAI,MAAM,CAAC,UAAU,CAAC,sBAAsB,CAAC;YAAE,OAAO,MAAM,CAAC,CAAC,mBAAmB;QACjF,IAAI,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC;YAAE,OAAO,MAAM,CAAC,CAAC,+BAA+B;QAC5E,IAAI,MAAM,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YAC/B,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;YACrD,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,WAAW,EAAE,CAAC,CAAC;YACpE,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACzB,OAAO,MAAM,CAAC,GAAG,CAAC;QACpB,CAAC;QACD,iFAAiF;QACjF,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACpD,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACzB,OAAO,MAAM,CAAC,GAAG,CAAC;IACpB,CAAC;IACD,IAAI,MAAM,YAAY,IAAI,IAAI,MAAM,YAAY,WAAW,IAAI,MAAM,YAAY,UAAU,EAAE,CAAC;QAC5F,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACpD,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACzB,OAAO,MAAM,CAAC,GAAG,CAAC;IACpB,CAAC;IACD,kFAAkF;IAClF,oFAAoF;IACpF,gEAAgE;IAChE,MAAM,IAAI,qBAAqB,CAC7B,uGAAuG;QACrG,kFAAkF,OAAO,MAAM,GAAG,CACrG,CAAC;AACJ,CAAC;AAED,qGAAqG;AACrG,KAAK,UAAU,mBAAmB,CAAC,GAAmB,EAAE,WAAoB;IAC1E,IAAI,aAAa,CAAC,WAAW,CAAC,EAAE,CAAC;QAC/B,MAAM,QAAQ,GAAG,MAAM,aAAa,CAAC,GAAG,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC;QAC3D,OAAO,EAAE,GAAG,WAAW,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC;IAC3C,CAAC;IACD,MAAM,QAAQ,GAAG,MAAM,aAAa,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;IACvD,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC;AAC3B,CAAC;AAED,kGAAkG;AAClG,KAAK,UAAU,WAAW,CACxB,GAAmB,EACnB,YAAqB,EACrB,WAAoB;IAEpB,IAAI,aAAa,CAAC,YAAY,CAAC,EAAE,CAAC;QAChC,OAAO,mBAAmB,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;IAC/C,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3D,MAAM,eAAe,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;QACxC,IAAI,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,CAAC;YAC/B,OAAO,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE,eAAe,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;QACzF,CAAC;QACD,OAAO,WAAW,CAAC,CAAC,kDAAkD;IACxE,CAAC;IACD,IAAI,aAAa,CAAC,YAAY,CAAC,IAAI,aAAa,CAAC,WAAW,CAAC,EAAE,CAAC;QAC9D,MAAM,MAAM,GAA4B,EAAE,GAAG,WAAW,EAAE,CAAC;QAC3D,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC;YAC5C,IAAI,GAAG,IAAI,WAAW,EAAE,CAAC;gBACvB,MAAM,CAAC,GAAG,CAAC,GAAG,MAAM,WAAW,CAAC,GAAG,EAAE,YAAY,CAAC,GAAG,CAAC,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC;YAC5E,CAAC;QACH,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,OAAO,WAAW,CAAC,CAAC,0DAA0D;AAChF,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,MAA4B,EAC5B,OAA6B;IAE7B,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC;QACtC,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,GAAG,CAAC,OAAO,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC;QACzE,MAAM,EAAE,MAAM;QACd,QAAQ,EAAE,IAAI;KACf,CAAC,CAAC;IAEH,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;QACrB,MAAM,KAAK,GAAG,MAAM,CAAC,iBAAiB,CAAC,CAAC,CAAC,EAAE,OAAO,IAAI,MAAM,CAAC,OAAO,CAAC;QACrE,MAAM,IAAI,qBAAqB,CAC7B,iEAAiE,KAAK,EAAE,CACzE,CAAC;IACJ,CAAC;IACD,oFAAoF;IACpF,IAAI,MAAM,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;QAC7B,MAAM,IAAI,qBAAqB,CAC7B,gEAAgE,MAAM,CAAC,MAAM,IAAI,CAClF,CAAC;IACJ,CAAC;IACD,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC;IAE/B,MAAM,GAAG,GAAmB,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,GAAG,EAAE,EAAE,CAAC;IACtE,MAAM,SAAS,GAA4B,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IACjE,KAAK,MAAM,CAAC,IAAI,EAAE,WAAW,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACjE,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC7B,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,SAAS,IAAI,KAAK,CAAC,EAAE,CAAC;YACnD,6EAA6E;YAC7E,SAAS;QACX,CAAC;QACD,SAAS,CAAC,IAAI,CAAC,GAAG,MAAM,WAAW,CAAC,GAAG,EAAE,KAAK,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;IACvE,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC;AACrD,CAAC"}

package/dist/runs.d.ts

@@ -1,3 +1,4 @@
+import type { DictPipeOutput } from "./models.js";
 /**
  * Run-lifecycle types + polling for the hosted polling surface (`/v1/runs/*`).
  *
@@ -55,6 +56,61 @@ export interface RunRead extends RunPublic {
     degraded: boolean;
     retry_after_seconds?: number | null;
 }
+/**
+ * One inference call's token usage — the client-facing wire record.
+ *
+ * Mirrors the runtime's `TokensUsageRecord`, specified in
+ * `docs/specs/pipelex-mthds-protocol.md#tokensusage-records-on-run-artifacts`. The same
+ * shape rides both surfaces: the durable `tokens_usages.json` artifact that the hosted
+ * results route relays, and the blocking execute response's `pipe_output.tokens_usages`.
+ *
+ * Every field is optional and the index signature is open **on purpose**. A record the
+ * current runtime emits always carries the full key set (a field with no value is an
+ * explicit `null`, never an omitted key), so callers may read any field directly. But
+ * durable artifacts written before the contract shipped are relayed verbatim and never
+ * migrated: such a record arrives with no `cost` and no `pipe_code`, and keeps its legacy
+ * `job_metadata` / `unit_costs` — reachable through the index signature, never contract
+ * fields.
+ *
+ * The enum-ish fields are open sets on the wire and stay `string` here — never frozen
+ * unions — so runtime enum churn is non-breaking for consumers.
+ */
+export interface TokensUsageRecord {
+    /** Kind of inference. Known values: `llm`, `img_gen`, `extract`, `search`. */
+    model_type?: string | null;
+    /** Human model name (e.g. `gpt-4o`). */
+    inference_model_name?: string | null;
+    /** Provider/platform model id (e.g. `gpt-4o-2024-11-20`). */
+    inference_model_id?: string | null;
+    /** The pipe that made the call — what makes per-pipe cost attribution possible. */
+    pipe_code?: string | null;
+    /** Known values: `llm_job`, `img_gen_job`, `extract_job`, `search_job`, `jinja2_job`, `mock_job`. */
+    job_category?: string | null;
+    /**
+     * Known values: `llm_gen_text`, `llm_gen_object`, `img_gen_text_to_image`,
+     * `extract_pages`, `search_sourced_answer`, `search_structured`.
+     */
+    unit_job_id?: string | null;
+    /**
+     * Raw provider-reported token counts, keyed by token category (`input`, `input_cached`,
+     * `output`, `output_reasoning`, …). `input` is the joined total and `input_cached` a
+     * subset of it — the categories are NOT additive, so summing them double-counts.
+     */
+    nb_tokens_by_category?: Record<string, number> | null;
+    /**
+     * Computed USD cost of this call. Null when the model has no rate table at all (own-GPU,
+     * mock, dry run); `0` means a rate table existed and priced the call at zero. The
+     * underlying rate table never crosses the wire and there is no run-level aggregate — sum
+     * the records.
+     */
+    cost?: number | null;
+    /** ISO 8601 start of the call. */
+    started_at?: string | null;
+    /** ISO 8601 end of the call. Duration is derivable from the pair and deliberately not shipped. */
+    completed_at?: string | null;
+    /** Legacy fields on a pre-contract artifact relayed verbatim (`job_metadata`, `unit_costs`). */
+    [extension: string]: unknown;
+}
 /**
  * Result artifacts for a completed run — `GET /v1/runs/{pipeline_run_id}/results`.
  *
@@ -81,7 +137,22 @@ export interface RunResults {
      * blocking-execute path only; null on the hosted path. Supplementary to `main_stuff`,
      * which is already resolved out of it; kept for consumers that need the whole working memory.
      */
-    pipe_output?: Record<string, unknown> | null;
+    pipe_output?: DictPipeOutput | null;
+    /**
+     * Per-call usage records — token counts by category, computed `cost` in USD, model id —
+     * for LLM and img-gen/extract/search calls alike. On the hosted path this is the
+     * `tokens_usages.json` artifact's record list relayed verbatim; on the blocking path it is
+     * the execute response's `pipe_output.tokens_usages`. Null whenever assembly produced no
+     * list — it was off, it broke (see `usage_assembly_error`), or (hosted) the run was
+     * delivered before the artifact existed; `[]` when assembly ran and no inference happened.
+     */
+    tokens_usages?: TokensUsageRecord[] | null;
+    /**
+     * Non-null when the runner's usage assembly failed for the run. The ONLY field that
+     * separates "usage broke" from "usage was off" / "pre-artifact run" — all three leave
+     * `tokens_usages` null, so a caller that cares must branch on this, not on the list.
+     */
+    usage_assembly_error?: string | null;
 }
 /**
  * Single-shot result lookup outcome, discriminated on `state`:

package/dist/runs.js.map

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

package/dist/upload.d.ts

@@ -0,0 +1,66 @@
+/**
+ * `uploadFile` — the single-asset upload convenience over the raw `upload()` wire
+ * call. Accepts web byte types in every runtime (`Blob`/`File`/`ArrayBuffer`/
+ * `Uint8Array`) and, in Node only, a filesystem path string; returns an
+ * {@link UploadRecord} assembled client-side. See `docs/input-preparation.md`.
+ *
+ * The MIME type and size are known client-side at upload time, so the record is
+ * built without extending the `/v1/upload` response.
+ */
+/** A local asset `uploadFile` accepts. A path string is Node-only (see {@link readLocalPath}). */
+export type UploadableAsset = Blob | ArrayBuffer | Uint8Array | string;
+/**
+ * The record `uploadFile` returns for a prepared asset. Beyond the source identity
+ * it guarantees the resulting `uri`, the MIME `contentType`, the `size` in bytes,
+ * and the `filename`. A content checksum is deliberately not included — it is
+ * best-effort at most, and within-preparation dedup keys on source identity.
+ */
+export interface UploadRecord {
+    /** The `pipelex-storage://` reference for the uploaded asset. */
+    uri: string;
+    filename: string;
+    /** MIME type, known client-side. Best-effort for raw bytes (falls back to `application/octet-stream`). */
+    contentType: string;
+    /** Size of the uploaded bytes. */
+    size: number;
+}
+/** Per-call options for {@link uploadFile}. Fill in a filename/MIME for nameless byte sources. */
+export interface UploadFileOptions {
+    filename?: string;
+    contentType?: string;
+}
+/** The subset of the client `uploadFile` needs — the raw base64 `upload` wire call. */
+export interface UploadCapableClient {
+    upload(input: {
+        filename: string;
+        data: string;
+        content_type: string;
+    }): Promise<{
+        uri: string;
+        filename: string;
+    }>;
+}
+/** True when running under Node (has `process.versions.node`). */
+export declare function isNodeRuntime(): boolean;
+/** MIME guess from a filename extension; `application/octet-stream` when unknown. */
+export declare function guessContentType(filename: string): string;
+/**
+ * Read a filesystem path into bytes — Node only. A path string in a non-Node
+ * runtime cannot be read, so it fails as an invalid local source rather than
+ * being silently misread as text or a URL. `node:fs/promises` is imported
+ * dynamically and guarded by `isNodeRuntime()`, so it is only *loaded* in Node.
+ * Note: the dynamic import defers execution, not bundling — a browser-targeting
+ * bundler still statically resolves this literal specifier, so browser consumers
+ * must currently mark `node:*` external. Making the byte-only path bundle for the
+ * browser out of the box is an open packaging decision (see wip/pr-16-review-notes.md).
+ */
+export declare function readLocalPath(path: string): Promise<Uint8Array>;
+/** Base64-encode bytes, cross-runtime (Buffer when present, else chunked btoa). */
+export declare function bytesToBase64(bytes: Uint8Array): string;
+/**
+ * Upload one local asset and return its {@link UploadRecord}. Maps the raw
+ * `upload()` transport errors onto the semantic input-preparation errors: a
+ * `413` is a rejected asset, `401`/`403` an auth failure, `404` an unsupported
+ * upload capability, an unreachable host a transport failure.
+ */
+export declare function uploadFile(client: UploadCapableClient, asset: UploadableAsset, options?: UploadFileOptions): Promise<UploadRecord>;

package/dist/upload.js

@@ -0,0 +1,153 @@
+/**
+ * `uploadFile` — the single-asset upload convenience over the raw `upload()` wire
+ * call. Accepts web byte types in every runtime (`Blob`/`File`/`ArrayBuffer`/
+ * `Uint8Array`) and, in Node only, a filesystem path string; returns an
+ * {@link UploadRecord} assembled client-side. See `docs/input-preparation.md`.
+ *
+ * The MIME type and size are known client-side at upload time, so the record is
+ * built without extending the `/v1/upload` response.
+ */
+import { InvalidLocalSourceError, RejectedAssetError, UploadAuthenticationError, UploadTransportError, UnsupportedUploadCapabilityError, } from "./errors.js";
+import { ApiResponseError, ApiUnreachableError } from "./errors.js";
+const DEFAULT_CONTENT_TYPE = "application/octet-stream";
+const DEFAULT_FILENAME = "upload.bin";
+const EXTENSION_MIME = {
+    png: "image/png",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    gif: "image/gif",
+    webp: "image/webp",
+    svg: "image/svg+xml",
+    bmp: "image/bmp",
+    tif: "image/tiff",
+    tiff: "image/tiff",
+    heic: "image/heic",
+    pdf: "application/pdf",
+    txt: "text/plain",
+    csv: "text/csv",
+    json: "application/json",
+};
+/** True when running under Node (has `process.versions.node`). */
+export function isNodeRuntime() {
+    return (typeof process !== "undefined" && process.versions != null && process.versions.node != null);
+}
+/** Filename tail of a path, splitting on both separators (no `node:path` import needed). */
+function basename(path) {
+    const parts = path.split(/[\\/]/);
+    return parts[parts.length - 1] || path;
+}
+/** MIME guess from a filename extension; `application/octet-stream` when unknown. */
+export function guessContentType(filename) {
+    const dot = filename.lastIndexOf(".");
+    if (dot < 0 || dot === filename.length - 1)
+        return DEFAULT_CONTENT_TYPE;
+    const ext = filename.slice(dot + 1).toLowerCase();
+    return EXTENSION_MIME[ext] ?? DEFAULT_CONTENT_TYPE;
+}
+/**
+ * Read a filesystem path into bytes — Node only. A path string in a non-Node
+ * runtime cannot be read, so it fails as an invalid local source rather than
+ * being silently misread as text or a URL. `node:fs/promises` is imported
+ * dynamically and guarded by `isNodeRuntime()`, so it is only *loaded* in Node.
+ * Note: the dynamic import defers execution, not bundling — a browser-targeting
+ * bundler still statically resolves this literal specifier, so browser consumers
+ * must currently mark `node:*` external. Making the byte-only path bundle for the
+ * browser out of the box is an open packaging decision (see wip/pr-16-review-notes.md).
+ */
+export async function readLocalPath(path) {
+    if (!isNodeRuntime()) {
+        throw new InvalidLocalSourceError(`Cannot read the local path "${path}" outside Node — path strings are Node-only. ` +
+            "In the browser or an edge runtime, pass the file as bytes (Blob/File/ArrayBuffer/Uint8Array).", path);
+    }
+    try {
+        const { readFile } = await import("node:fs/promises");
+        return await readFile(path);
+    }
+    catch (cause) {
+        throw new InvalidLocalSourceError(`Local file cannot be read: "${path}" (${cause.code ?? "read error"}).`, path, { cause });
+    }
+}
+/** Base64-encode bytes, cross-runtime (Buffer when present, else chunked btoa). */
+export function bytesToBase64(bytes) {
+    if (typeof Buffer !== "undefined") {
+        return Buffer.from(bytes).toString("base64");
+    }
+    let binary = "";
+    const chunk = 0x8000; // stay under the String.fromCharCode argument cap
+    for (let index = 0; index < bytes.length; index += chunk) {
+        binary += String.fromCharCode(...bytes.subarray(index, index + chunk));
+    }
+    return btoa(binary);
+}
+/** Normalize any accepted asset form into bytes plus a filename and MIME. */
+async function toAssetBytes(asset, options) {
+    if (typeof asset === "string") {
+        const bytes = await readLocalPath(asset);
+        const filename = options.filename ?? basename(asset);
+        return { bytes, filename, contentType: options.contentType ?? guessContentType(filename) };
+    }
+    if (asset instanceof Uint8Array) {
+        return assetBytesFromBuffer(asset, options);
+    }
+    if (asset instanceof ArrayBuffer) {
+        return assetBytesFromBuffer(new Uint8Array(asset), options);
+    }
+    // Blob / File — File carries `.name`; both carry `.type`.
+    const bytes = new Uint8Array(await asset.arrayBuffer());
+    const name = options.filename ?? asset.name;
+    const filename = name && name.length > 0 ? name : DEFAULT_FILENAME;
+    const contentType = options.contentType ?? (asset.type || guessContentType(filename));
+    return { bytes, filename, contentType };
+}
+function assetBytesFromBuffer(bytes, options) {
+    const filename = options.filename ?? DEFAULT_FILENAME;
+    return { bytes, filename, contentType: options.contentType ?? guessContentType(filename) };
+}
+/**
+ * Upload one local asset and return its {@link UploadRecord}. Maps the raw
+ * `upload()` transport errors onto the semantic input-preparation errors: a
+ * `413` is a rejected asset, `401`/`403` an auth failure, `404` an unsupported
+ * upload capability, an unreachable host a transport failure.
+ */
+export async function uploadFile(client, asset, options = {}) {
+    const { bytes, filename, contentType } = await toAssetBytes(asset, options);
+    const data = bytesToBase64(bytes);
+    let uploaded;
+    try {
+        uploaded = await client.upload({ filename, data, content_type: contentType });
+    }
+    catch (error) {
+        throw mapUploadError(error, filename);
+    }
+    return { uri: uploaded.uri, filename: uploaded.filename, contentType, size: bytes.length };
+}
+/** Translate a raw `upload()` transport error into the matching preparation error. */
+function mapUploadError(error, filename) {
+    if (error instanceof ApiResponseError) {
+        switch (error.status) {
+            case 413:
+                return new RejectedAssetError(`The server rejected "${filename}": ${error.serverMessage ?? "asset exceeds the service size limit"}.`, filename, error.status, { cause: error });
+            case 401:
+            case 403:
+                return new UploadAuthenticationError(`Upload of "${filename}" was not authorized (${error.status}). Check the configured Pipelex API key.`, error.status, { cause: error });
+            case 404:
+                return new UnsupportedUploadCapabilityError("The configured Pipelex deployment does not support file upload (no /v1/upload route). " +
+                    "Upload is a hosted Pipelex capability.", { cause: error });
+            default:
+                return new UploadTransportError(`Upload of "${filename}" failed (${error.status}): ${error.serverMessage ?? error.statusText}.`, { cause: error });
+        }
+    }
+    if (error instanceof ApiUnreachableError) {
+        return new UploadTransportError(`Upload of "${filename}" could not reach the Pipelex API (${error.code ?? "unreachable"}).`, { cause: error });
+    }
+    // Only errors thrown by the `client.upload()` call reach here — the local-source
+    // and asset-type failures are raised in `toAssetBytes`, before this try block. Any
+    // error that is neither of the two mapped types (a malformed 2xx body surfacing as a
+    // SyntaxError, a custom client throwing a plain Error) is wrapped so every upload
+    // failure stays catchable as an InputPreparationError, never a raw escape.
+    const detail = error instanceof Error ? error.message : String(error);
+    return new UploadTransportError(`Upload of "${filename}" failed unexpectedly: ${detail}.`, {
+        cause: error,
+    });
+}
+//# sourceMappingURL=upload.js.map

package/dist/upload.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pipelex/sdk",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "TypeScript SDK for the Pipelex hosted API — execute methods, manage runs, and call the product surface.",
   "license": "MIT",
   "repository": {
@@ -19,8 +19,10 @@
   },
   "scripts": {
     "build": "tsc",
+    "build:hook": "node scripts/build-hook.mjs",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
+    "test:e2e": "vitest run --config vitest.e2e.config.ts",
     "typecheck": "tsc --noEmit",
     "typecheck:test": "tsc -p tsconfig.test.json --noEmit",
     "lint": "eslint src/ tests/",
@@ -41,9 +43,11 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.39.4",
+    "@pipelex/tools-wasm": "^0.1.0",
     "@types/node": "^22.12.0",
     "@vitest/coverage-v8": "^4.1.9",
     "dependency-cruiser": "^17.4.3",
+    "esbuild": "^0.25.12",
     "eslint": "^9.39.4",
     "globals": "^16.5.0",
     "prettier": "^3.8.4",
@@ -52,6 +56,6 @@
     "vitest": "^4.0.18"
   },
   "dependencies": {
-    "mthds": "^0.18.0"
+    "mthds": "^0.19.0"
   }
 }