@pipelex/sdk 0.46.1 → 0.47.0

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,6FAA6F;AAC7F,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,oFAAoF;AACpF,kFAAkF;AAClF,mFAAmF;AACnF,wBAAwB;AACxB,cAAc,gBAAgB,CAAC;AAE/B,wEAAwE;AACxE,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACtF,sFAAsF;AACtF,yFAAyF;AACzF,2EAA2E;AAC3E,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAgBzF,+FAA+F;AAC/F,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,+FAA+F;AAC/F,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE3D,+FAA+F;AAC/F,6FAA6F;AAC7F,iGAAiG;AACjG,8FAA8F;AAC9F,iEAAiE;AACjE,OAAO,EAAE,yBAAyB,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAEhG,iGAAiG;AACjG,kFAAkF;AAClF,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAK/E,yFAAyF;AACzF,sEAAsE;AACtE,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AASpD,+FAA+F;AAC/F,0EAA0E;AAC1E,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD,uEAAuE;AACvE,wFAAwF;AACxF,0FAA0F;AAC1F,iFAAiF;AACjF,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,sBAAsB,EACtB,qBAAqB,EACrB,0BAA0B,EAC1B,2BAA2B,EAC3B,gCAAgC,EAChC,4BAA4B,GAC7B,MAAM,gBAAgB,CAAC;AAmFxB,+EAA+E;AAC/E,4EAA4E;AAC5E,iFAAiF;AACjF,0EAA0E;AAC1E,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,2BAA2B,EAC3B,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAwE5B,wEAAwE;AACxE,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,WAAW,CAAC;AAwBnB,oFAAoF;AACpF,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAS5C,+EAA+E;AAC/E,gGAAgG;AAChG,8FAA8F;AAC9F,8EAA8E;AAC9E,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,EAChB,mBAAmB,EACnB,qBAAqB,EACrB,yBAAyB,EACzB,2BAA2B,EAC3B,cAAc,EACd,eAAe,EACf,oBAAoB,EACpB,4BAA4B,EAC5B,qBAAqB,EACrB,sBAAsB,EACtB,uBAAuB,EACvB,sBAAsB,EACtB,qBAAqB,EACrB,eAAe,EACf,kBAAkB,EAClB,gCAAgC,EAChC,yBAAyB,EACzB,oBAAoB,EACpB,sBAAsB,EACtB,2BAA2B,EAC3B,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,6FAA6F;AAC7F,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,oFAAoF;AACpF,kFAAkF;AAClF,mFAAmF;AACnF,wBAAwB;AACxB,cAAc,gBAAgB,CAAC;AAE/B,wEAAwE;AACxE,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACtF,sFAAsF;AACtF,yFAAyF;AACzF,2EAA2E;AAC3E,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAgBzF,iGAAiG;AACjG,gGAAgG;AAChG,6DAA6D;AAC7D,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAW1D,+FAA+F;AAC/F,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE3D,+FAA+F;AAC/F,6FAA6F;AAC7F,iGAAiG;AACjG,8FAA8F;AAC9F,iEAAiE;AACjE,OAAO,EAAE,yBAAyB,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAEhG,iGAAiG;AACjG,kFAAkF;AAClF,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAK/E,yFAAyF;AACzF,sEAAsE;AACtE,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AASpD,+FAA+F;AAC/F,0EAA0E;AAC1E,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD,uEAAuE;AACvE,wFAAwF;AACxF,0FAA0F;AAC1F,iFAAiF;AACjF,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,sBAAsB,EACtB,qBAAqB,EACrB,0BAA0B,EAC1B,2BAA2B,EAC3B,gCAAgC,EAChC,4BAA4B,GAC7B,MAAM,gBAAgB,CAAC;AAmFxB,+EAA+E;AAC/E,4EAA4E;AAC5E,iFAAiF;AACjF,0EAA0E;AAC1E,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,2BAA2B,EAC3B,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AA2E5B,wEAAwE;AACxE,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,WAAW,CAAC;AAwBnB,oFAAoF;AACpF,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAS5C,+EAA+E;AAC/E,gGAAgG;AAChG,8FAA8F;AAC9F,8EAA8E;AAC9E,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,EAChB,mBAAmB,EACnB,qBAAqB,EACrB,yBAAyB,EACzB,2BAA2B,EAC3B,cAAc,EACd,eAAe,EACf,oBAAoB,EACpB,4BAA4B,EAC5B,qBAAqB,EACrB,uBAAuB,EACvB,sBAAsB,EACtB,qBAAqB,EACrB,eAAe,EACf,kBAAkB,EAClB,gCAAgC,EAChC,yBAAyB,EACzB,oBAAoB,EACpB,sBAAsB,EACtB,2BAA2B,EAC3B,kBAAkB,EAClB,qBAAqB,EACrB,uBAAuB,GACxB,MAAM,aAAa,CAAC"}

package/dist/method-trees.d.ts

@@ -0,0 +1,209 @@
+/**
+ * A saved method's tree on the client side (see `docs/method-trees.md`): the source a save reads a
+ * tree from, how that tree becomes the `files` map a save sends, inline or by hash, the blob routes
+ * that let a large tree travel by hash (mthds/docs/spec/protocol.md, "Sending files by hash"), the
+ * upload of a blob the platform lacks, and the writing of a saved tree to disk.
+ *
+ * The tree-sending part mirrors the `mthds` npm package's own helpers, which its published
+ * `mthds/protocol` subpath does not export yet. This SDK imports `mthds` through that subpath alone,
+ * so it carries this copy, held to the same rule: the same inline threshold, the same text-or-Base64
+ * choice per file, and each file added as an own property. It needs no Node built-in: SHA-256 is Web
+ * Crypto's, and Base64 is written here. Only `writeMethodTreeTo` needs Node, which it loads when
+ * called.
+ */
+import type { FileEntry, MethodFiles } from "mthds/protocol";
+import { type MethodFileTransferCode } from "./errors.js";
+import type { SavedMethodFile } from "./product-models.js";
+/** A file of a {@link MethodTreeSource}. */
+export interface MethodTreeSourceFile {
+    /** Its tree path. */
+    readonly path: string;
+    /** Its length in bytes. */
+    readonly size: number;
+    /** The SHA-256 of its bytes, in lowercase hexadecimal. */
+    readonly sha256: string;
+}
+/**
+ * A method tree a save reads from: its files, its digest, and a way to read each file's bytes. The
+ * `MethodTree` the `mthds` package's `listMethodTree` returns is one, so a tree listed from a
+ * directory, under the limits `methodTreeLimits` reports, is passed as it is.
+ */
+export interface MethodTreeSource {
+    /** Every file of the tree, each tree path once. */
+    readonly files: readonly MethodTreeSourceFile[];
+    /** The tree digest, `sha256:` and 64 lowercase hexadecimal digits. */
+    readonly digest: string;
+    /** The bytes of the file at `treePath`, which must hash to the SHA-256 the listing gives it. */
+    readFile(treePath: string): Promise<Uint8Array>;
+}
+/**
+ * The limits a deployment holds a tree to, in the shape the `mthds` package's `listMethodTree`
+ * takes as its `limits` option, so a lister stops at the first breach before hashing anything. A
+ * limit the deployment does not announce is absent.
+ */
+export interface MethodTreeLimits {
+    /** The most files a tree may hold. */
+    readonly maxFileCount?: number;
+    /** The largest one file may be, in bytes. */
+    readonly maxFileSize?: number;
+    /** The largest all the files together may be, in bytes. */
+    readonly maxTotalSize?: number;
+}
+/** A blob a sender is about to send by hash, named by its SHA-256 and its size. */
+export interface BlobRef {
+    sha256: string;
+    size: number;
+}
+/**
+ * Body of `POST /v1/blobs/missing`: the blobs a sender is about to send by hash, each hash listed
+ * once, and the digest of the tree they make up, which lets a platform that holds that tree whole
+ * answer at once.
+ */
+export interface MissingBlobsRequest {
+    blobs: BlobRef[];
+    digest?: string;
+}
+/**
+ * Where to upload one blob: its bytes as the whole body of a request with this method to this URL,
+ * carrying exactly these headers. The URL is signed by storage and is a bearer credential.
+ */
+export interface UploadTarget {
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+    [extension: string]: unknown;
+}
+/** A blob the platform lacks, with where to upload it. */
+export interface MissingBlob {
+    sha256: string;
+    size: number;
+    upload: UploadTarget;
+    [extension: string]: unknown;
+}
+/** The `200` answer of `POST /v1/blobs/missing`; an empty `missing` means nothing to upload. */
+export interface MissingBlobsResult {
+    missing: MissingBlob[];
+    [extension: string]: unknown;
+}
+/**
+ * The heaviest inline map, in bytes of its JSON serialization in UTF-8, that a save sends inline
+ * to a deployment keeping a blob store. Below it a tree is cheaper to send whole than to check and
+ * upload; above it every file travels by hash. `mthds`'s clients use the same threshold.
+ */
+export declare const INLINE_TREE_MAX_BYTES: number;
+/** How many blobs a save uploads at once, and how many files `writeMethodTree` downloads at once. */
+export declare const MAX_CONCURRENT_TRANSFERS = 8;
+/** Whether a version handshake declares a blob store (`blob_store: true`). */
+export declare function declaresBlobStore(version: object): boolean;
+/**
+ * The tree limits a version handshake announces under `limits.method_tree`. A value that is not a
+ * positive safe integer is left out rather than trusted, and a limit not announced is absent, so a
+ * bare runner, which announces none, yields no limit.
+ */
+export declare function announcedTreeLimits(version: object): MethodTreeLimits;
+/** What an inline map spends in a request: its JSON serialization with no whitespace, in UTF-8. */
+export declare function inlineMapBytes(files: MethodFiles): number;
+/** The total of a tree's file sizes, in bytes. */
+export declare function treeTotalSize(tree: MethodTreeSource): number;
+/** Every file's bytes, by tree path, each read and checked by the tree, one file at a time. */
+export declare function readTreeBytes(tree: MethodTreeSource): Promise<Map<string, Uint8Array>>;
+/** The whole tree as inline entries, from bytes already read by `readTreeBytes`. */
+export declare function inlineFilesOf(tree: MethodTreeSource, bytesByPath: ReadonlyMap<string, Uint8Array>): MethodFiles;
+/** The whole tree as hash entries, which the platform resolves in the organization's blobs. */
+export declare function hashMethodFiles(tree: MethodTreeSource): MethodFiles;
+/** Each blob of the tree once, in the tree's order: files with the same bytes share one blob. */
+export declare function uniqueBlobs(tree: MethodTreeSource): BlobRef[];
+/** A file of the tree holding each blob, so a missing blob's bytes can be read and uploaded. */
+export declare function fileByBlob(tree: MethodTreeSource): Map<string, MethodTreeSourceFile>;
+/**
+ * Run `task` over `items`, at most `limit` at a time. The first task to fail stops the run: no
+ * queued item is handed out after it, `signal` is aborted so the tasks still in flight can stop
+ * early, and once they have settled the first failure is thrown.
+ */
+export declare function forEachConcurrently<T>(items: readonly T[], limit: number, task: (item: T, signal: AbortSignal) => Promise<void>): Promise<void>;
+/**
+ * The tree whose files are `contents`, each file's bytes or its text by tree path, a text encoded
+ * in UTF-8. The keys are sent as they are, and the platform refuses one that is not a tree path,
+ * with the `422` `invalid_method_files` naming it. `call` names the caller's method in a refusal.
+ *
+ * Throws `RequestArgumentError` for `contents` holding no file, for a value that is neither a
+ * string nor bytes, and for a text holding a lone surrogate, which no file can hold.
+ */
+export declare function contentsTreeSource(contents: Readonly<Record<string, Uint8Array | string>>, call: string): Promise<MethodTreeSource>;
+/**
+ * The tree digest of a tree's files: `sha256:` and the SHA-256 of its listing, one line
+ * `<sha256>  <path>` per file, in tree path order.
+ */
+export declare function treeDigestOf(files: readonly MethodTreeSourceFile[]): Promise<string>;
+/** The SHA-256 of `bytes`, in lowercase hexadecimal, by Web Crypto. */
+export declare function sha256Hex(bytes: Uint8Array): Promise<string>;
+/**
+ * Compare two strings byte for byte on their UTF-8 encoding, the order tree paths are sorted in.
+ * JavaScript's own string order compares UTF-16 code units, which puts a character above U+FFFF
+ * before one between U+E000 and U+FFFF, where UTF-8 puts it after.
+ */
+export declare function compareUtf8(left: string, right: string): number;
+/** The entry a file travels as inline: its text when its bytes are UTF-8, its Base64 otherwise. */
+export declare function inlineFileEntry(bytes: Uint8Array): FileEntry;
+/**
+ * Add a file to a map of file entries as an own property, since assigning to a key such as
+ * `__proto__`, a tree path like any other, would set the object's prototype instead of adding the
+ * file.
+ */
+export declare function defineFileEntry(files: MethodFiles, treePath: string, entry: FileEntry): void;
+/** Canonical padded standard Base64 (RFC 4648), with no line break and its pad bits zero. */
+export declare function encodeBase64(bytes: Uint8Array): string;
+/**
+ * Upload one blob's bytes to the target `POST /v1/blobs/missing` named: the bytes as the whole body
+ * of a request with the target's method to its URL, carrying exactly the target's headers and no
+ * credential of the client, since the signed URL authorizes the upload itself. A `412` from a
+ * target asking for a create-only write (`If-None-Match`) means the bytes are already stored, and
+ * counts as uploaded.
+ *
+ * Throws `MethodFileTransferError` (`operation` `upload`) when storage gives no answer within
+ * `timeoutMs` or answers any other non-2xx; neither its message nor any member carries the URL,
+ * nor storage's error body, which can echo the signed request.
+ */
+export declare function uploadBlob(blob: MissingBlob, bytes: Uint8Array, options: {
+    timeoutMs: number;
+    signal?: AbortSignal;
+}): Promise<void>;
+/**
+ * The code of a transfer storage answered with a non-2xx `status`: `storage_error` for one the
+ * fallback table calls retryable (`408`, `429`, a `5xx` other than `501`), `refused` otherwise.
+ */
+export declare function methodFileTransferCodeOfStatus(status: number): MethodFileTransferCode;
+/**
+ * Write a saved tree to disk, each file of `files` at its tree path under `destination`; see
+ * `PipelexApiClient.writeMethodTree`. Node only: the file system modules are loaded when it runs.
+ */
+export declare function writeMethodTreeTo(files: readonly SavedMethodFile[], destination: string, options: {
+    timeoutMs: number;
+}): Promise<void>;
+/**
+ * Refuse a listing whose paths could not be written as a tree, before anything is downloaded. A
+ * platform's listing holds tree paths that never collide; the check guards the disk against any
+ * other listing a caller hands over, such as one built by hand, since a path such as `../x` would
+ * be written outside the destination. Throws `RequestArgumentError`.
+ */
+export declare function refuseUnwritableListing(files: readonly SavedMethodFile[]): void;
+/**
+ * Why `candidate` is not a tree path, or `null` when it is one (mthds/docs/spec/method-tree.md,
+ * "Tree Paths"), the rule the `mthds` package's `treePathViolation` holds.
+ */
+export declare function treePathViolation(candidate: string): string | null;
+/**
+ * The paths that collide: those equal to another once case-folded, and those naming, once
+ * case-folded, a directory of another, with the paths under it, sorted byte for byte. The fold is
+ * `toUpperCase().toLowerCase()`, which agrees with Unicode full case folding on the scripts a file
+ * name uses; a pair it misses still fails the write, which never writes over a file.
+ */
+export declare function pathCollisions(treePaths: readonly string[]): string[];
+/**
+ * `text`, an answer that carries signed links, with every link hidden, for an error to hold: in a
+ * JSON body every `url` member, at any depth, is replaced whole, and in any text, JSON or not, a
+ * truncated body included, the query of every `http(s)` link is replaced, since a signed link's
+ * signature rides its query. A link is a bearer credential, so no error, message or member may
+ * carry one.
+ */
+export declare function redactSignedLinks(text: string): string;