@pipelex/sdk 0.21.0 → 0.23.0

package/README.md

@@ -84,6 +84,23 @@ const client = new PipelexApiClient({ appInfo: { name: "acme-invoicer", version:
 // User-Agent: acme-invoicer/1.4.0 pipelex-sdk-js/<version> node/<version> (<os>; <arch>)
 ```
 
+### Uploading from a browser
+
+A browser page that holds a file but not the API key can still store it: the server that holds the key asks for an upload grant, and the page sends the file straight to storage with it. The file never crosses your server or the API gateway, so it can be as large as the service's own limit. The page imports `@pipelex/sdk/upload`, the browser-safe entry, which bundles with no Node builtin to mark external; the main `@pipelex/sdk` entry is Node-first.
+
+```ts
+// On the server, which holds the key:
+const grant = await client.requestUploadGrant({
+  filename: "report.pdf",
+  content_type: "application/pdf",
+  size: 48213,
+});
+
+// In the page, which holds the file:
+import { uploadWithGrant } from "@pipelex/sdk/upload";
+const { uri } = await uploadWithGrant(grant, file); // pipelex-storage://…
+```
+
 The full client surface is documented in [`docs/architecture.md`](./docs/architecture.md).
 
 ## Documentation
@@ -95,8 +112,8 @@ These pages ship inside the published package, so a reader who has only installe
 | [`docs/architecture.md`](./docs/architecture.md) | The whole client surface: the request pipeline, every route, the typed errors |
 | [`docs/run-results.md`](./docs/run-results.md) | Every field of `RunResults` — the run id as a durable handle, `main_stuff`, `working_memory`, `graph_spec`, the usage pair, produced files |
 | [`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: `collectArtifacts`, `resolveArtifacts`, `fetchArtifact`, `downloadArtifacts` |
-| [`docs/input-preparation.md`](./docs/input-preparation.md) | The other direction — `uploadFile` and `prepareInputs`, which turn local files into references a run can take |
+| [`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/crate-routes.md`](./docs/crate-routes.md) | `resolve` and `codegen`, and the offline `runCodegenCheck` that guards a committed tree |
 | [`docs/build-routes.md`](./docs/build-routes.md) | The `/v1/build/*` projections: `buildInputs`, `buildOutput`, `buildRunner` |
 | [`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 |

package/dist/artifacts.d.ts

@@ -2,8 +2,9 @@
  * The artifact stack — the download twin of `prepareInputs`, in layers so each
  * operation is usable without the next:
  *
- * - {@link collectArtifacts} — a pure walk of any JSON value for the strings that
- *   ARE `pipelex-storage://` references. No network, no key.
+ * - {@link locateArtifacts} — a pure walk of any JSON value for the strings that
+ *   ARE `pipelex-storage://` references, each with every path it sits at.
+ *   {@link collectArtifacts} is the same walk's bare references. No network, no key.
  * - {@link resolveArtifacts} — the platform's bulk resolve route over a whole
  *   list, chunked at the route's bound, one verdict per reference.
  * - {@link fetchArtifact} — a bounded `Response` for one reference: resolved
@@ -20,7 +21,7 @@
  *
  * `node:fs/promises`, `node:path` and `undici` are imported dynamically, behind
  * `isNodeRuntime()`, so the module's static import graph stays free of Node
- * builtins: `collectArtifacts` and `resolveArtifacts` run anywhere, `fetchArtifact`
+ * builtins: the walk and `resolveArtifacts` run anywhere, `fetchArtifact`
  * runs anywhere the global `fetch` does (the dispatcher is a Node refinement), and
  * only `downloadArtifacts` touches a filesystem.
  */
@@ -135,14 +136,36 @@ export type DownloadArtifactsRequest = DownloadArtifactsOptions & ({
     results: RunResults;
     run_id?: never;
 });
+/**
+ * Where one `pipelex-storage://` reference sits in a walked value — what
+ * {@link locateArtifacts} answers per reference. `found_at` lists every path at
+ * which the reference occurs, in walk order, and is never empty: `found_at[0]` is
+ * where it was first seen, and the path a saved file is named after.
+ *
+ * A path is `$`-rooted: `$` is the walked value itself, an object key matching
+ * `^[A-Za-z_][A-Za-z0-9_]*$` is `.key`, any other key is `["…"]` in JSON string
+ * escaping, and an array index is `[n]` — `$.rooms[3].staged_photo.url`,
+ * `$.items[0].url`, `$["a key"].url`. It is the exact path of the string, the
+ * final `url` of a content object included.
+ */
+export interface ArtifactLocation {
+    /** The reference, exactly as it appears in the walked value. */
+    uri: string;
+    /** Every `$`-rooted path at which the reference occurs, in walk order. */
+    found_at: string[];
+}
 /**
  * One reference's outcome in a download verdict — one shape with nullable fields,
  * like {@link ResolvedArtifact}: either `path` and `size` are set and `error` is
- * null, or `error` is set and both are null. `content_type` is the platform's
- * guess from the reference's extension, known before the fetch, on both arms.
+ * null, or `error` is set and both are null. `found_at` says where the reference
+ * sits in the walked scope, and `content_type` is the platform's guess from the
+ * reference's extension, known before the fetch; both are on both arms, so an
+ * item that was not saved still says which field it would have filled.
  */
 export type DownloadedArtifact = {
     uri: string;
+    /** Every `$`-rooted path in the walked scope where the reference sits; the first one named the file. */
+    found_at: string[];
     /** Absolute path of the written file. */
     path: string;
     content_type: string | null;
@@ -151,6 +174,8 @@ export type DownloadedArtifact = {
     error: null;
 } | {
     uri: string;
+    /** Every `$`-rooted path in the walked scope where the reference sits. */
+    found_at: string[];
     path: null;
     content_type: string | null;
     size: null;
@@ -185,32 +210,68 @@ export interface ArtifactCapableClient {
         signal?: AbortSignal;
     }): Promise<RunResultState>;
 }
+/**
+ * Every `pipelex-storage://` reference inside a JSON-shaped value, each with
+ * every path at which it occurs. The references are deduplicated and kept in
+ * discovery order (the order of their first sighting), and each one's `found_at`
+ * lists its paths in walk order, so `found_at[0]` is where it was first seen.
+ *
+ * The string test is {@link collectArtifacts}'s: a string counts only when it IS
+ * a reference. A path is rooted at `$`, the walked value itself; an object key
+ * matching `^[A-Za-z_][A-Za-z0-9_]*$` is written `.key`, any other key `["…"]` in
+ * JSON string escaping, and an array index `[n]`. The runtime serializes a
+ * produced image or document as content carrying its reference in `url`, so a
+ * typical path ends there: `$.rooms[3].staged_photo.url`, `$.items[0].url`, or
+ * `$.url` for an output that is one image. Pure — no network, no key.
+ */
+export declare function locateArtifacts(value: unknown): ArtifactLocation[];
 /**
  * Every `pipelex-storage://` reference inside a JSON-shaped value, deduplicated,
- * in discovery order. A string counts only when it IS a reference — the whole
- * string, scheme first, with something after the scheme; text that merely
- * contains one does not. The scheme is unambiguous, so this walk is a contract
- * rather than a heuristic: the runtime serializes a produced image or document
- * as content carrying its reference in `url`, beside an expiring `public_url`
- * this walk ignores. Pure — no network, no key — so a consumer can count or
- * list a run's produced files without resolving any of them.
+ * in discovery order — the references of {@link locateArtifacts}, without their
+ * paths. A string counts only when it IS a reference — the whole string, scheme
+ * first, with something after the scheme; text that merely contains one does
+ * not. The scheme is unambiguous, so this walk is a contract rather than a
+ * heuristic: the runtime serializes a produced image or document as content
+ * carrying its reference in `url`, beside an expiring `public_url` this walk
+ * ignores. Pure — no network, no key — so a consumer can count or list a run's
+ * produced files without resolving any of them.
  */
 export declare function collectArtifacts(value: unknown): string[];
 /** A string that is a storage reference: the scheme, then at least one character. */
 export declare function isStorageReference(value: string): boolean;
 /**
- * The bare filename a storage reference is saved under: the last segment of the
- * storage key, reduced to a conservative character set so it can never name
- * anything but a regular file directly inside the target directory. Path
- * separators are the split point, so no traversal survives; leading dots are
- * stripped, so no hidden file and no `..`; everything outside `[A-Za-z0-9._-]`
- * becomes `_`; an empty result falls back to a numbered `artifact-N`. Length is
- * capped with the extension preserved, and an extension is added from the
- * content type when the key carries none. A collision on disk is not this
+ * The bare filename a reference is saved under, named after the field it fills:
+ * the path in `location.found_at[0]`, where the reference was first seen.
+ *
+ * 1. A final object key `url` is dropped, since the runtime's image and
+ *    document contents carry their reference there; a reference under any other
+ *    key keeps that key, and a `url` key that is not final is kept.
+ * 2. Each key is reduced to `[A-Za-z0-9_]`, every other character (`-` and `.`
+ *    included) becoming `_`; an index stays its decimal digits.
+ * 3. The segments are joined with `-`. An empty result — the reference is the
+ *    walked value itself, or its `url` — becomes the scope's name.
+ * 4. Over the filename length cap (`MAX_FILENAME_LENGTH`, extension included),
+ *    the tail is kept: whole leading segments are dropped first, since the last
+ *    ones are the specific ones, and a single segment still too long is cut to
+ *    fit.
+ * 5. A stem Windows reserves for a device (`con`, `prn`, `aux`, `nul`,
+ *    `com0`–`com9`, `lpt0`–`lpt9`, in any case) gets a trailing `_`, so
+ *    `$.aux.url` is saved as `aux_.png`.
+ * 6. The extension is the storage key's own, reduced to `[A-Za-z0-9]`, when it
+ *    has a short one; otherwise the content type's, for the types a run
+ *    produces; otherwise there is none.
+ *
+ * So `$.rooms[3].staged_photo.url` is saved as `rooms-3-staged_photo.png`, and
+ * `$.url` in `main_stuff` as `main_stuff.png`. The stem is ASCII letters, digits,
+ * `_` and the `-` joins, never empty and never a device name, so the name can
+ * only ever be a regular file directly inside the target directory. A collision on disk is not this
  * function's concern: `downloadArtifacts` suffixes the stem (`name-1.ext`) on
  * exclusive creation, so a file is never overwritten.
+ *
+ * Throws `ArtifactOperationError` for a location whose `found_at[0]` is not a path
+ * in the notation {@link locateArtifacts} writes, or for an unknown scope.
  */
-export declare function artifactFilename(uri: string, contentType: string | null | undefined, index: number): string;
+export declare function artifactFilename(location: ArtifactLocation, contentType: string | null | undefined, scope: ArtifactScope): string;
 /**
  * Resolve a list of references through the bulk route, chunked at
  * {@link BULK_RESOLVE_MAX_URIS} per request, and answer one
@@ -264,19 +325,20 @@ export declare function writeFully(writer: ChunkWriter, chunk: Uint8Array): Prom
  * Save a run's produced files under `dir` — Node-only, like the path-string arm
  * of `uploadFile`. Takes a `run_id` (the results are re-read, so a run is
  * downloadable days later) or a `RunResults` in hand; walks the requested scope
- * with {@link collectArtifacts}; resolves the whole set through the bulk route
+ * with {@link locateArtifacts}; resolves the whole set through the bulk route
  * ahead of the workers; then a bounded pool of workers each fetch → open with
  * `wx` → write, re-resolving any link that has expired by the time a worker
- * reaches it. The embedded `public_url` is never used. Files are named by
- * {@link artifactFilename} and never overwritten; a failed or aborted download
- * unlinks its partial file.
+ * reaches it. The embedded `public_url` is never used. Each file is named after
+ * the field it fills, by {@link artifactFilename}'s rule, and never overwritten;
+ * a failed or aborted download unlinks its partial file.
  *
  * Returns a produced verdict: one entry per reference, errors as values. It
  * throws only when no verdict can be produced — `RunStillRunningError` or
  * `RunFailedError` for a run that has not completed, `ScopeUnavailableError`
  * when the scope's artifact is null or missing, `ArtifactAuthenticationError`
  * (carrying the verdict so far) when the resolve route refuses the credential,
- * `ArtifactOperationError` outside Node or for an unusable `dir`, and the
+ * `ArtifactOperationError` outside Node, for an unusable `dir` or for an
+ * unknown `scope`, and the
  * transport and lifecycle errors of the reads it makes (`ApiResponseError` for
  * a deployment without the bulk route, `RunLifecycleUnavailableError` for a
  * bare runner asked by id, `ApiUnreachableError`).