@giveitsmaller/sdk 0.19.0 → 0.20.0

package/dist/file-first.js

@@ -159,9 +159,10 @@ export class RunResult {
     toJSON() {
         // Re-project each OutputFile to exactly its known fields so structurally
         // compatible inputs carrying extra properties can't leak into the JSON.
-        // The target-size fields (chosenQuality/targetSizeMet) are OMITTED when
-        // undefined, mirroring PHP's omit-when-null so non-target-size outputs
-        // stay byte-identical across languages.
+        // The projected optional fields (chosenQuality/targetSizeMet and the
+        // auto_quality measuredQuality/qualityMetric) are OMITTED when undefined,
+        // mirroring PHP's omit-when-null so outputs lacking them stay
+        // byte-identical across languages.
         const file = (o) => ({
             url: o.url,
             filename: o.filename,
@@ -169,6 +170,8 @@ export class RunResult {
             operation: o.operation,
             ...(o.chosenQuality !== undefined ? { chosenQuality: o.chosenQuality } : {}),
             ...(o.targetSizeMet !== undefined ? { targetSizeMet: o.targetSizeMet } : {}),
+            ...(o.measuredQuality !== undefined ? { measuredQuality: o.measuredQuality } : {}),
+            ...(o.qualityMetric !== undefined ? { qualityMetric: o.qualityMetric } : {}),
         });
         const rest = {
             artifacts: this.artifacts.map(file),
@@ -230,6 +233,8 @@ export function projectDownloadsToRunResult(workflowId, finalStatus, jobDownload
                 // non-target-size output carries no chosenQuality/targetSizeMet key.
                 ...(f.chosenQuality !== undefined ? { chosenQuality: f.chosenQuality } : {}),
                 ...(f.targetSizeMet !== undefined ? { targetSizeMet: f.targetSizeMet } : {}),
+                ...(f.measuredQuality !== undefined ? { measuredQuality: f.measuredQuality } : {}),
+                ...(f.qualityMetric !== undefined ? { qualityMetric: f.qualityMetric } : {}),
             });
         }
     }
@@ -293,6 +298,8 @@ export function projectMultiJobToRunResult(workflowId, finalStatus, jobDownloads
             // single-job projector).
             ...(f.chosenQuality !== undefined ? { chosenQuality: f.chosenQuality } : {}),
             ...(f.targetSizeMet !== undefined ? { targetSizeMet: f.targetSizeMet } : {}),
+            ...(f.measuredQuality !== undefined ? { measuredQuality: f.measuredQuality } : {}),
+            ...(f.qualityMetric !== undefined ? { qualityMetric: f.qualityMetric } : {}),
         }));
         // The flat artifacts[] keeps every job's outputs in job order.
         artifacts.push(...outputs);
@@ -438,6 +445,48 @@ export const fileInput = {
         return { kind: 'uploadId', fileId };
     },
 };
+/**
+ * Await a workflow to a terminal status — SSE first with a poll fallback, or
+ * poll-direct when `useSSE` is false. The single shared implementation behind
+ * every file-first `run()` (Recipe, FilesRecipe, MergedRecipe, ArchivedRecipe,
+ * WatermarkedRecipe), mirroring the operation-first
+ * `OperationBuilder.awaitTerminal` (in `builder.ts`). Callers pass
+ * `useSSE: options.useSSE ?? true` so the default stays SSE-first (today's
+ * behaviour); `useSSE: false` skips the SSE attempt entirely and polls —
+ * useful when an intermediary proxy blocks SSE.
+ *
+ * @internal Not part of the caller-facing fluent surface.
+ */
+async function _awaitTerminal(client, args) {
+    if (args.useSSE) {
+        try {
+            return await _consumeSseToTerminal(client, {
+                workflowId: args.workflowId,
+                deadline: args.deadline,
+                signal: args.signal,
+                onProgress: args.onProgress,
+            });
+        }
+        catch (err) {
+            // TDqmkWpX: poll-fallback ONLY on a clean SSE stream-end
+            // (SseEndedWithoutTerminal) or a typed transport error (GislNetworkError).
+            // Everything else — caller-deadline, abort, an API error from /events, an
+            // onProgress callback throw (propagates as-is, NOT wrapped), anything
+            // unexpected — MUST propagate; re-issuing the same doomed request via poll
+            // would mask it. Mirrors the PHP BuilderInternals::awaitTerminal sealed-
+            // marker discipline.
+            if (!(err instanceof SseEndedWithoutTerminal || err instanceof GislNetworkError)) {
+                throw err;
+            }
+        }
+    }
+    return await _pollToTerminal(client, {
+        workflowId: args.workflowId,
+        deadline: args.deadline,
+        signal: args.signal,
+        pollIntervalMs: args.pollIntervalMs,
+    });
+}
 /**
  * The file-first builder value. `client.file(path)` returns a `Recipe`;
  * single-input operations called on it (`compress`, `convert`, `thumbnail`,
@@ -522,6 +571,27 @@ export class Recipe {
         }
         return this.withStep({ opType: 'thumbnail', options: wire });
     }
+    /**
+     * Geometric transform: rotate (0/90/180/270°) and/or flip. Chainable — the
+     * canonical single-job order is `transform → convert → compress → thumbnail`,
+     * so downstream size options refer to the final (post-transform) frame.
+     *
+     * Passthrough: `rotate`/`flip` are forwarded as-is; the SDK does NOT narrow
+     * per media (a `flip` on a PDF input passes SDK validation but the server
+     * rejects it — documents rotate only). The transform op is `availability:
+     * planned` today, so workflow-create returns `feature_not_available` (422)
+     * until the per-media Lambdas ship. A no-op (`rotate:0` + `flip:none`) is
+     * rejected server-side as `invalid_options`.
+     */
+    transform(options = {}) {
+        validateVerbOptions('transform', options);
+        const wire = {};
+        for (const [key, value] of Object.entries(options)) {
+            if (value !== undefined)
+                wire[key] = value;
+        }
+        return this.withStep({ opType: 'transform', options: wire });
+    }
     /**
      * Produce ONE transformed image: keep or change format, plus quality, resize
      * and route-honored controls. The single user-facing image transform — the SDK
@@ -591,7 +661,8 @@ export class Recipe {
      * (beta). Audio/document/animated-GIF/unsupported-subtype/undetectable bases
      * throw locally BEFORE any upload (the planned-op gate). `options` carries the
      * wire watermark options (`anchor`, `opacity`, `margin_x`, `margin_y`,
-     * `overlay_width`). Returns a {@link WatermarkedRecipe} (chain post-watermark
+     * `overlay_width`, or `overlays[]` for the multi-overlay stack). Returns a
+     * {@link WatermarkedRecipe} (chain post-watermark
      * `compress`/`convert`/`thumbnail`, then `run`/`submit`). Distinct from
      * {@link textWatermark} (single-input text overlay).
      */
@@ -674,35 +745,17 @@ export class Recipe {
         // 1+2. Upload (when required) + create the workflow. Shared with submit()
         // (which passes a webhook → callback_url). run() passes no webhook.
         const created = await this._uploadAndCreate(undefined, deadline, onProgress, signal, options.probeBeforeCreate, options.probeTimeoutMs);
-        // 3. Wait to terminal status — SSE first, poll on a genuine SSE error.
-        // Caller-aborted + deadline-elapsed errors MUST propagate (not transient).
-        let finalStatus;
-        try {
-            finalStatus = await _consumeSseToTerminal(this.client, {
-                workflowId: created.workflowId,
-                deadline,
-                signal,
-                onProgress,
-            });
-        }
-        catch (err) {
-            // TDqmkWpX: poll-fallback ONLY on a clean SSE stream-end
-            // (SseEndedWithoutTerminal) or a typed transport error (GislNetworkError).
-            // Everything else — caller-deadline, abort, an API error from /events, an
-            // onProgress callback throw (propagates as-is, NOT wrapped), anything
-            // unexpected — MUST propagate; re-issuing the same doomed request via poll
-            // would mask it. Mirrors the PHP BuilderInternals::awaitTerminal sealed-
-            // marker discipline.
-            if (!(err instanceof SseEndedWithoutTerminal || err instanceof GislNetworkError)) {
-                throw err;
-            }
-            finalStatus = await _pollToTerminal(this.client, {
-                workflowId: created.workflowId,
-                deadline,
-                signal,
-                pollIntervalMs: options.pollIntervalMs,
-            });
-        }
+        // 3. Wait to terminal status — SSE first, poll on a genuine SSE error
+        // (or poll-direct when `useSSE: false`). Caller-aborted + deadline-elapsed
+        // errors MUST propagate (not transient) — see _awaitTerminal.
+        const finalStatus = await _awaitTerminal(this.client, {
+            workflowId: created.workflowId,
+            deadline,
+            signal,
+            onProgress,
+            pollIntervalMs: options.pollIntervalMs,
+            useSSE: options.useSSE ?? true,
+        });
         // 4. Fetch downloads. The maxWait deadline covers upload + create + wait +
         // downloads, so check before issuing the request (mirrors builder.ts).
         if (Date.now() >= deadline) {
@@ -1221,8 +1274,9 @@ function _validateWatermarkOverlay(overlay) {
     }
 }
 function _lowerWatermarkOp(wireOp, options) {
-    // Watermark options (anchor/opacity/margin_x/margin_y/overlay_width) are
-    // already wire keys; empty options omit the `options` key (byte-identical to PHP).
+    // Watermark options (anchor/opacity/margin_x/margin_y/overlay_width, or the
+    // multi-overlay overlays[] stack) are already wire keys; empty options omit
+    // the `options` key (byte-identical to PHP).
     const wire = { ...options };
     return Object.keys(wire).length === 0 ? { type: wireOp } : { type: wireOp, options: wire };
 }
@@ -1361,6 +1415,10 @@ export class FilesRecipe {
     thumbnail(options) {
         return this.withStep(this.baseRecipe().thumbnail(options));
     }
+    /** Apply the same geometric transform (rotate/flip) to every input. Validated via the base {@link Recipe}. */
+    transform(options = {}) {
+        return this.withStep(this.baseRecipe().transform(options));
+    }
     /** Apply the same text watermark to every input. Option keys validated via the base {@link Recipe}. */
     textWatermark(text, options = {}) {
         return this.withStep(this.baseRecipe().textWatermark(text, options));
@@ -1456,26 +1514,14 @@ export class FilesRecipe {
         // 3. Wait to terminal status — SSE first, poll on a genuine SSE error.
         // `partially_failed` is a normal terminal state here (the helper treats it
         // as terminal); only caller-aborted / deadline / API errors propagate.
-        let finalStatus;
-        try {
-            finalStatus = await _consumeSseToTerminal(this.client, {
-                workflowId: created.workflowId,
-                deadline,
-                signal,
-                onProgress,
-            });
-        }
-        catch (err) {
-            if (!(err instanceof SseEndedWithoutTerminal || err instanceof GislNetworkError)) {
-                throw err;
-            }
-            finalStatus = await _pollToTerminal(this.client, {
-                workflowId: created.workflowId,
-                deadline,
-                signal,
-                pollIntervalMs: options.pollIntervalMs,
-            });
-        }
+        const finalStatus = await _awaitTerminal(this.client, {
+            workflowId: created.workflowId,
+            deadline,
+            signal,
+            onProgress,
+            pollIntervalMs: options.pollIntervalMs,
+            useSSE: options.useSSE ?? true,
+        });
         // 4. Fetch downloads + project per-job into the partitioned RunResult.
         if (Date.now() >= deadline) {
             throw new GislTimeoutError(`Workflow ${created.workflowId} reached terminal status but maxWait elapsed before downloads could be fetched`);
@@ -1621,6 +1667,16 @@ export class MergedRecipe {
         }
         return this.withStep({ opType: 'thumbnail', options: wire });
     }
+    /** Geometric transform (rotate/flip) of the merged output. Passthrough; see {@link Recipe.transform}. */
+    transform(options = {}) {
+        validateVerbOptions('transform', options);
+        const wire = {};
+        for (const [key, value] of Object.entries(options)) {
+            if (value !== undefined)
+                wire[key] = value;
+        }
+        return this.withStep({ opType: 'transform', options: wire });
+    }
     /**
      * Lower to the merge DAG: one `passthrough` source job per input + one
      * `merge` job whose `operations[]` is `[merge, ...post-combine ops]`. The
@@ -1674,26 +1730,14 @@ export class MergedRecipe {
         }
         const deadline = Date.now() + _parseMaxWait(options.maxWait ?? 300_000);
         const created = await this._uploadAllAndCreate(undefined, deadline, onProgress, signal, options.probeBeforeCreate, options.probeTimeoutMs);
-        let finalStatus;
-        try {
-            finalStatus = await _consumeSseToTerminal(this.client, {
-                workflowId: created.workflowId,
-                deadline,
-                signal,
-                onProgress,
-            });
-        }
-        catch (err) {
-            if (!(err instanceof SseEndedWithoutTerminal || err instanceof GislNetworkError)) {
-                throw err;
-            }
-            finalStatus = await _pollToTerminal(this.client, {
-                workflowId: created.workflowId,
-                deadline,
-                signal,
-                pollIntervalMs: options.pollIntervalMs,
-            });
-        }
+        const finalStatus = await _awaitTerminal(this.client, {
+            workflowId: created.workflowId,
+            deadline,
+            signal,
+            onProgress,
+            pollIntervalMs: options.pollIntervalMs,
+            useSSE: options.useSSE ?? true,
+        });
         if (Date.now() >= deadline) {
             throw new GislTimeoutError(`Workflow ${created.workflowId} reached terminal status but maxWait elapsed before downloads could be fetched`);
         }
@@ -1897,26 +1941,14 @@ export class ArchivedRecipe {
         }
         const deadline = Date.now() + _parseMaxWait(options.maxWait ?? 300_000);
         const created = await this._uploadAllAndCreate(undefined, deadline, onProgress, signal, options.probeBeforeCreate, options.probeTimeoutMs);
-        let finalStatus;
-        try {
-            finalStatus = await _consumeSseToTerminal(this.client, {
-                workflowId: created.workflowId,
-                deadline,
-                signal,
-                onProgress,
-            });
-        }
-        catch (err) {
-            if (!(err instanceof SseEndedWithoutTerminal || err instanceof GislNetworkError)) {
-                throw err;
-            }
-            finalStatus = await _pollToTerminal(this.client, {
-                workflowId: created.workflowId,
-                deadline,
-                signal,
-                pollIntervalMs: options.pollIntervalMs,
-            });
-        }
+        const finalStatus = await _awaitTerminal(this.client, {
+            workflowId: created.workflowId,
+            deadline,
+            signal,
+            onProgress,
+            pollIntervalMs: options.pollIntervalMs,
+            useSSE: options.useSSE ?? true,
+        });
         if (Date.now() >= deadline) {
             throw new GislTimeoutError(`Workflow ${created.workflowId} reached terminal status but maxWait elapsed before downloads could be fetched`);
         }
@@ -2046,6 +2078,16 @@ export class WatermarkedRecipe {
         }
         return this.withStep({ opType: 'thumbnail', options: wire });
     }
+    /** Geometric transform (rotate/flip) of the watermarked output. Passthrough; see {@link Recipe.transform}. */
+    transform(options = {}) {
+        validateVerbOptions('transform', options);
+        const wire = {};
+        for (const [key, value] of Object.entries(options)) {
+            if (value !== undefined)
+                wire[key] = value;
+        }
+        return this.withStep({ opType: 'transform', options: wire });
+    }
     /**
      * Lower to the watermark DAG: a `src_0` passthrough/base-steps job + a `src_1`
      * passthrough/overlay-steps job + one `watermark` job whose `inputs[]` consume
@@ -2102,26 +2144,14 @@ export class WatermarkedRecipe {
         }
         const deadline = Date.now() + _parseMaxWait(options.maxWait ?? 300_000);
         const created = await this._uploadAllAndCreate(undefined, deadline, onProgress, signal, options.probeBeforeCreate, options.probeTimeoutMs);
-        let finalStatus;
-        try {
-            finalStatus = await _consumeSseToTerminal(this.client, {
-                workflowId: created.workflowId,
-                deadline,
-                signal,
-                onProgress,
-            });
-        }
-        catch (err) {
-            if (!(err instanceof SseEndedWithoutTerminal || err instanceof GislNetworkError)) {
-                throw err;
-            }
-            finalStatus = await _pollToTerminal(this.client, {
-                workflowId: created.workflowId,
-                deadline,
-                signal,
-                pollIntervalMs: options.pollIntervalMs,
-            });
-        }
+        const finalStatus = await _awaitTerminal(this.client, {
+            workflowId: created.workflowId,
+            deadline,
+            signal,
+            onProgress,
+            pollIntervalMs: options.pollIntervalMs,
+            useSSE: options.useSSE ?? true,
+        });
         if (Date.now() >= deadline) {
             throw new GislTimeoutError(`Workflow ${created.workflowId} reached terminal status but maxWait elapsed before downloads could be fetched`);
         }
@@ -2200,3 +2230,275 @@ export class WatermarkedRecipe {
         return new WatermarkedRecipe(this.baseInput, this.baseSteps, this.overlay, this.watermarkOptions, [...this.postSteps, step], this.presetDefaults, this.scopedPresetDefaults, this.client);
     }
 }
+/**
+ * Identity key for batch cross-entry upload dedupe — mirrors the merge
+ * builder's `assetIdentity` (`merge.ts`). Two batch entries whose inputs share
+ * an identity upload ONCE and point both jobs at the shared fileId. `path` uses
+ * the EXACT caller-provided string (no trim / normalise / case-fold, so
+ * `'./a.jpg'` and `'/abs/a.jpg'` do NOT dedupe — by design); `blob` uses
+ * referential identity via a run-local token map (two distinct-but-equal Blobs
+ * still upload twice); `uploadId` uses the fileId itself (already upload-free,
+ * so deduping it is a pure no-op). `blobTokens` is threaded in so a single
+ * planning pass shares one token space.
+ */
+function inputIdentity(input, blobTokens) {
+    switch (input.kind) {
+        case 'path':
+            return `path:${input.path}`;
+        case 'uploadId':
+            return `id:${input.fileId}`;
+        case 'blob': {
+            let token = blobTokens.get(input.blob);
+            if (token === undefined) {
+                token = blobTokens.size;
+                blobTokens.set(input.blob, token);
+            }
+            return `blob:${token}`;
+        }
+    }
+}
+/**
+ * The keyed multi-recipe batch builder (FF7 / MFaCjL8d). `client.batch([r1, r2, …])`
+ * runs N DISTINCT single-input keyed {@link Recipe}s as ONE workflow; the
+ * partitioned {@link RunResult} addresses each entry's outputs by the caller key
+ * given at `client.file(input, key)` time (`res.byKey('hero')`), and one failed
+ * entry lands in `failed` without sinking the rest.
+ *
+ * **v1 scope (locked):** `.run()` only (no `submit()` / reattach — a follow-up);
+ * single-input {@link Recipe} entries only — the multi-input builders
+ * ({@link FilesRecipe}, {@link MergedRecipe}, {@link WatermarkedRecipe},
+ * {@link ArchivedRecipe}) are REJECTED pre-upload. Cross-entry upload dedupe
+ * IS applied (1LwSJcz1): two entries sourcing the SAME input (by
+ * {@link inputIdentity}) upload ONCE and share the resulting fileId —
+ * correctness-neutral (same bytes → same per-job output), it only elides
+ * redundant uploads. Observable caveat: `onProgress` upload-phase events drop
+ * to one-per-UNIQUE input rather than one-per-entry.
+ *
+ * **Lowering (one workflow):** for each entry `i`, lower its single job via
+ * {@link Recipe.toWorkflowPayload} and re-id it `b{i}` — a POSITIONAL namespace
+ * DISTINCT from the fan-out `file-{i}` / merge-archive-watermark `src_{i}` refs so
+ * a future reattach can't misdetect the wire as a fan-out / merge. `keyByRef`
+ * maps each `b{i}` ref to that entry's caller key, so
+ * {@link projectMultiJobToRunResult} partitions per entry (1 job ↔ 1 key:
+ * `completed` → `succeeded`, else → `failed` with a {@link GislItemFailedError}).
+ *
+ * **Immutability:** the ctor is CLIENT-ONLY (the ordered entries + the client) —
+ * entries are already-built Recipes that captured their own preset defaults at
+ * `client.file(...)` time, so batch never re-plumbs
+ * presetDefaults/scopedPresetDefaults. Mirrors the PHP `BatchRecipe`.
+ */
+export class BatchRecipe {
+    client;
+    recipes;
+    constructor(recipes, client) {
+        this.client = client;
+        // DEFENSIVE COPY (TS-only): snapshot the caller's array so a later mutation
+        // of it (splice/push after construction, or during an in-flight run()) can't
+        // desync the uploaded fileIds from the lowered jobs/keys — validation,
+        // upload, lowering + keyByRef all iterate this frozen order. PHP is
+        // value-semantics-safe already (arrays copy on pass).
+        this.recipes = [...recipes];
+    }
+    /**
+     * Execute the batch end-to-end: validate + lowering-preflight EVERY entry
+     * BEFORE any upload, upload each entry's input, create ONE multi-job workflow
+     * (one `b{i}` job per entry), await a terminal state (SSE with poll fallback,
+     * honouring `useSSE`), then partition the per-job downloads into a keyed
+     * {@link RunResult}. `partially_failed` is a NORMAL terminal state here — the
+     * completed entries land in `succeeded`, the rest in `failed`.
+     *
+     * Requires a client bound at construction time — `gisl().batch([...])` wires
+     * it; a directly-constructed {@link BatchRecipe} (e.g. a lowering-only test)
+     * throws {@link GislConfigError}. Mirrors the fan-out {@link FilesRecipe.run}.
+     */
+    async run(options = {}) {
+        const signal = options.signal;
+        const onProgress = options.onProgress;
+        if (this.client === undefined) {
+            throw new GislConfigError('BatchRecipe.run() requires a client; build the batch via gisl().batch([...]) rather than constructing BatchRecipe directly.', { reason: 'no_client' });
+        }
+        // Validate + lowering-preflight EVERY entry BEFORE any upload: a structural
+        // violation (bad type / missing / duplicate key) or an invalid lowering
+        // aborts here so no input uploads. NOTE — like FilesRecipe, TS does NOT
+        // pre-check path readability: a nonexistent/unreadable path surfaces INSIDE
+        // uploadFile during upload, so an earlier entry's input may already be
+        // uploaded when a later entry's path fails. (PHP pre-checks path/resource
+        // uploadability; this TS/PHP difference mirrors each language's existing
+        // FilesRecipe behavior and is intentionally NOT closed here — a TS
+        // path-precheck would diverge batch from FilesRecipe.)
+        this.validatePreUpload();
+        const deadline = Date.now() + _parseMaxWait(options.maxWait ?? 300_000);
+        // 1+2. Upload each entry's input + create ONE multi-job workflow. batch v1
+        // sends NO webhook (run()-only), so `callback_url` is omitted from the
+        // payload (the closure receives `callbackUrl` undefined).
+        // Dedupe cross-entry uploads: collapse to the first-appearance-unique input
+        // list, upload each unique input ONCE, then expand the returned unique
+        // fileIds back to one-per-entry (in entry order) so the b{i} jobs + keyByRef
+        // stay N-length and correctness-neutral. See planUploads / inputIdentity.
+        const { uniqueInputs, entryToUnique } = this.planUploads();
+        const created = await _uploadInputsAndCreate(this.client, uniqueInputs, (uniqueFileIds, callbackUrl) => this.toWorkflowPayload(entryToUnique.map((u) => uniqueFileIds[u]), callbackUrl), {
+            webhook: undefined,
+            deadline,
+            onProgress,
+            signal,
+            probeBeforeCreate: options.probeBeforeCreate,
+            probeTimeoutMs: options.probeTimeoutMs,
+            uploadsLabel: 'batch',
+            workflowLabel: 'the batch workflow',
+        });
+        // 3. Wait to terminal status — SSE first, poll on a genuine SSE error (or
+        // poll-direct when `useSSE: false`). Caller-aborted + deadline errors
+        // propagate (not transient) — see _awaitTerminal.
+        const finalStatus = await _awaitTerminal(this.client, {
+            workflowId: created.workflowId,
+            deadline,
+            signal,
+            onProgress,
+            pollIntervalMs: options.pollIntervalMs,
+            useSSE: options.useSSE ?? true,
+        });
+        // 4. Fetch downloads + project per-job into the keyed RunResult.
+        if (Date.now() >= deadline) {
+            throw new GislTimeoutError(`Workflow ${created.workflowId} reached terminal status but maxWait elapsed before downloads could be fetched`);
+        }
+        const downloads = await this.client.getWorkflowDownloads(created.workflowId);
+        // TDqmkWpX: re-check AFTER the downloads fetch so a slow getWorkflowDownloads
+        // cannot return a success past the advertised maxWait deadline.
+        if (Date.now() >= deadline) {
+            throw new GislTimeoutError(`Workflow ${created.workflowId} downloads fetch completed after maxWait elapsed`);
+        }
+        const downloader = new LazyHttpDownloader();
+        return projectMultiJobToRunResult(created.workflowId, finalStatus, downloads.downloads, this.keyByRef(), downloader);
+    }
+    /**
+     * Lower the batch to ONE multi-job workflow-create payload against a list of
+     * resolved upload ids (one per entry, in entry order). Each entry `i` becomes
+     * ONE job re-id'd `b{i}` carrying that entry's lowered `source` + `operations`.
+     * Composes the single-file {@link Recipe.toWorkflowPayload} per entry so each
+     * keeps its own media-hint + preset resolution and lowering logic is not
+     * duplicated. `callback_url` is built in ONLY when a webhook is supplied
+     * (batch v1 run() supplies none, so it is omitted).
+     *
+     * @internal Consumed by {@link run} (after uploading) and the cross-language
+     *   golden-payload lowering test (with fixed ids). Not caller-facing.
+     */
+    toWorkflowPayload(fileIds, callbackUrl) {
+        const jobs = this.recipes.map((entry, i) => {
+            const oneJob = entry.toWorkflowPayload(fileIds[i]).jobs[0];
+            // Positional id `b{i}` — a namespace DISTINCT from the fan-out `file-{i}` /
+            // merge `src_{i}` refs. Key order (id, source, operations) matches the PHP
+            // `toWire()` so the JSON serialisation is byte-identical across languages.
+            return { id: `b${i}`, source: oneJob.source, operations: oneJob.operations };
+        });
+        return callbackUrl === undefined ? { jobs } : { jobs, callback_url: callbackUrl };
+    }
+    /** The number of recipe entries in this batch (introspection / tests). */
+    get recipeCount() {
+        return this.recipes.length;
+    }
+    // ---------------------------------------------------------------------------
+    /**
+     * Validate the batch AND lowering-preflight every entry BEFORE any upload
+     * fires — an invalid entry costs no bandwidth. TWO PASSES (mirrors PHP
+     * `BatchRecipe`'s structural-loop-then-preflight-loop), throwing
+     * {@link GislConfigError}:
+     *  0. empty batch → `no_recipes` (checked first).
+     *  PASS 1 (structural, ALL entries in order):
+     *    - a KNOWN multi-input builder (checked FIRST — they do NOT extend
+     *      {@link Recipe}, so the not-a-Recipe catch-all would otherwise misreport
+     *      them as plain type errors) → `multi_input_recipe_unsupported`;
+     *    - a non-{@link Recipe} entry → `invalid_recipe`;
+     *    - a missing/empty key → `missing_key`;
+     *    - a duplicate key → `duplicate_key`.
+     *  PASS 2 (lowering preflight, ALL entries): lower each entry (via
+     *    {@link Recipe.toWorkflowPayload}) so an invalid lowering throws BEFORE any
+     *    upload, mirroring what {@link FilesRecipe} lowers pre-create.
+     *
+     * Two passes so a batch with MULTIPLE distinct violations throws the SAME
+     * reason regardless of entry order (a structural error anywhere wins over a
+     * lowering error elsewhere) — converging TS + PHP error reporting. The
+     * offending key/index rides the MESSAGE (not `conflictingFields`, which is
+     * reserved for wire FIELD names).
+     */
+    validatePreUpload() {
+        if (this.recipes.length === 0) {
+            throw new GislConfigError('batch() requires at least one recipe. Pass an ordered array of ' +
+                'client.file(input, key).<op>(...) recipes, each with a unique key.', { reason: 'no_recipes' });
+        }
+        // PASS 1 — structural checks across ALL entries in order.
+        const seenKeys = new Set();
+        this.recipes.forEach((rawEntry, i) => {
+            // Treat each entry as unknown for the runtime type guards: the public
+            // signature is ReadonlyArray<Recipe>, but a plain-JS caller can pass
+            // anything, and the multi-input builders are structurally Recipe-adjacent.
+            const entry = rawEntry;
+            // ORDER MATTERS (codex r2 #1): check the KNOWN multi-input builders FIRST.
+            // They do NOT extend Recipe, so the not-a-Recipe catch-all below would
+            // otherwise misreport them as plain caller type errors.
+            if (entry instanceof FilesRecipe ||
+                entry instanceof MergedRecipe ||
+                entry instanceof WatermarkedRecipe ||
+                entry instanceof ArchivedRecipe) {
+                throw new GislConfigError(`batch() entry at index ${i} is a multi-input recipe (${entry.constructor.name}), ` +
+                    'which is not supported in batch v1 — batch accepts only single-input keyed recipes ' +
+                    '(client.file(input, key).<op>(...)). Run the multi-input recipe on its own.', { reason: 'multi_input_recipe_unsupported' });
+            }
+            // THEN the catch-all: not a Recipe at all (null / string / plain object).
+            if (!(entry instanceof Recipe)) {
+                throw new GislConfigError(`batch() entry at index ${i} is not a recipe. Build each entry via ` +
+                    'client.file(input, key).<op>(...) before passing it to batch().', { reason: 'invalid_recipe' });
+            }
+            // Keys are the result address → each entry needs a unique, non-empty key.
+            const key = entry.key();
+            if (key === undefined || key === '') {
+                throw new GislConfigError(`batch() entry at index ${i} has no key. Every batch entry needs a unique non-empty key ` +
+                    "(client.file(input, 'key')) to address its result.", { reason: 'missing_key' });
+            }
+            if (seenKeys.has(key)) {
+                throw new GislConfigError(`batch() has a duplicate key '${key}' (entry at index ${i}). Every batch entry needs a unique key.`, { reason: 'duplicate_key' });
+            }
+            seenKeys.add(key);
+        });
+        // PASS 2 — lowering preflight across ALL entries (each is now known to be a
+        // Recipe). Lower each entry now so an invalid lowering (e.g. an undetectable
+        // input + optimize, an unrepresentable output route) throws BEFORE any
+        // upload. The 'preflight' id is a throwaway placeholder — run() re-lowers
+        // against the real upload ids post-upload.
+        this.recipes.forEach((entry) => {
+            entry.toWorkflowPayload('preflight');
+        });
+    }
+    /**
+     * Collapse the entry inputs to a first-appearance-unique list for cross-entry
+     * upload dedupe: two entries sourcing the SAME input (by {@link inputIdentity})
+     * upload ONCE and share the fileId. Returns the ordered `uniqueInputs` plus an
+     * `entryToUnique` index map (length N, entry order) so {@link run} can expand
+     * the unique fileIds back to one-per-entry before {@link toWorkflowPayload} —
+     * keeping the b{i} refs + {@link keyByRef} N-length and correctness-neutral.
+     */
+    planUploads() {
+        const blobTokens = new Map();
+        const identityToUnique = new Map();
+        const uniqueInputs = [];
+        const entryToUnique = this.recipes.map((entry) => {
+            const input = entry.recipeInput;
+            const id = inputIdentity(input, blobTokens);
+            let uniqueIndex = identityToUnique.get(id);
+            if (uniqueIndex === undefined) {
+                uniqueIndex = uniqueInputs.length;
+                uniqueInputs.push(input);
+                identityToUnique.set(id, uniqueIndex);
+            }
+            return uniqueIndex;
+        });
+        return { uniqueInputs, entryToUnique };
+    }
+    /** Map each `b{i}` job ref to that entry's caller key (validated non-empty). */
+    keyByRef() {
+        const map = new Map();
+        this.recipes.forEach((entry, i) => {
+            map.set(`b${i}`, entry.key() ?? null);
+        });
+        return map;
+    }
+}