@giveitsmaller/sdk 0.8.0 → 0.9.0

package/dist/file-first.js

@@ -15,6 +15,11 @@ import { HttpDownloader } from './http-downloader.js';
 import { resolveCompressOptions, } from './ergonomic/preset_resolver.js';
 import { OptimizeFor } from './generated/sdk_spec/enums.js';
 import { uploadSource } from './types.js';
+// Deferred-usage-only import: `Handle` is constructed inside `submit()` at call
+// time, never at module-eval, so the handle.ts <-> file-first.ts back-edge
+// (handle.ts imports RunResult/projectDownloadsToRunResult from here) resolves
+// cleanly under ESM. Mirrors builder.ts/merge.ts importing Handle the same way.
+import { Handle } from './handle.js';
 /**
  * Result of a file-first run. Coexists with the operation-first `Result`
  * (in `builder.ts`) until FF6.
@@ -163,6 +168,137 @@ export class RunResult {
         return this.downloader;
     }
 }
+/**
+ * Flatten the terminal workflow status + its downloads into a {@link RunResult}.
+ *
+ * Shared by {@link Recipe.run} (passes its recipe key) and the file-first
+ * {@link Handle} reattach surface (`Handle.wait()`/`Handle.result()`, FF5a —
+ * passes `null` because a reattached handle carries no recipe key).
+ *
+ * **Partition invariant (carries a prior codex-review fix — do NOT let it
+ * drift):** success is ONLY `state === 'completed'`. Every other terminal
+ * state — `failed`, `partially_failed`, `cancelled`, `expired`,
+ * `paused_insufficient_credits` — partitions into `failed[]` so a caller's
+ * `ok`/`succeeded` check can never treat a cancelled/expired/paused run as a
+ * clean result.
+ *
+ * @internal Exported for reuse by the file-first `Handle`; not part of the
+ *   caller-facing fluent surface.
+ */
+export function projectDownloadsToRunResult(workflowId, finalStatus, jobDownloads, key, downloader) {
+    // Flatten to the lean OutputFile[] (the four file-first fields only).
+    const artifacts = [];
+    for (const job of jobDownloads) {
+        for (const f of job.files) {
+            artifacts.push({
+                url: f.downloadUrl,
+                filename: f.filename,
+                sizeBytes: f.sizeBytes,
+                operation: f.operation,
+            });
+        }
+    }
+    const state = finalStatus.status;
+    let succeeded;
+    let failed;
+    if (state === 'completed') {
+        succeeded = [{ key, outputs: artifacts }];
+        failed = [];
+    }
+    else {
+        const firstError = (finalStatus.jobs ?? [])
+            .flatMap((j) => j.operations ?? [])
+            .map((op) => op.errorMessage)
+            .find((m) => m !== undefined);
+        succeeded = [];
+        failed = [
+            { key, error: new Error(firstError !== undefined ? `${state}: ${firstError}` : state) },
+        ];
+    }
+    return new RunResult(workflowId, state, artifacts, succeeded, failed, downloader);
+}
+/**
+ * Flatten a terminal multi-job workflow (the `client.files([...])` fan-out)
+ * into a partitioned {@link RunResult}. One job per input file, keyed by the
+ * `file-{i}` job ref the {@link FilesRecipe} lowering assigns; the result's
+ * `succeeded` / `failed` partition is PER JOB, so one bad input does not sink
+ * the rest.
+ *
+ * Join model: `finalStatus.jobs[]` carries the per-job {@link JobStatus} +
+ * `operations[]` (for the error message); `jobDownloads[]` carries the per-job
+ * output files. Both are joined on the job `ref` ("file-{i}"); the partition
+ * key is the index `"{i}"` parsed out of that ref. The flat `artifacts[]` is
+ * every job's outputs in job order (the order `finalStatus.jobs[]` lists them).
+ *
+ * **Partition invariant (mirrors {@link projectDownloadsToRunResult} PER JOB —
+ * do NOT let it drift):** a job is a SUCCESS only when its
+ * {@link JobResponse.status} `=== 'completed'`. Any other per-job status —
+ * `failed`, `pending`, `waiting`, `blocked_insufficient_credits`,
+ * `in_progress` — partitions that job into `failed[]` (with that job's first
+ * operation error message, scoped to THAT job only).
+ *
+ * @internal Exported for the file-first `client.files([...]).run()` producer;
+ *   not part of the caller-facing fluent surface.
+ */
+export function projectMultiJobToRunResult(workflowId, finalStatus, jobDownloads, keyByRef, downloader) {
+    // Group downloads by job ref so a job's outputs can be flattened AFTER the
+    // per-job partition is decided (grouping is unrecoverable post-flatten).
+    const filesByRef = new Map();
+    for (const job of jobDownloads) {
+        filesByRef.set(job.ref, job.files);
+    }
+    const artifacts = [];
+    const succeeded = [];
+    const failed = [];
+    const jobs = finalStatus.jobs ?? [];
+    for (const job of jobs) {
+        const key = keyByRef.get(job.ref) ?? jobIndexFromRef(job.ref);
+        const outputs = (filesByRef.get(job.ref) ?? []).map((f) => ({
+            url: f.downloadUrl,
+            filename: f.filename,
+            sizeBytes: f.sizeBytes,
+            operation: f.operation,
+        }));
+        // The flat artifacts[] keeps every job's outputs in job order.
+        artifacts.push(...outputs);
+        if (job.status === 'completed') {
+            succeeded.push({ key, outputs });
+        }
+        else {
+            const firstError = (job.operations ?? [])
+                .map((op) => op.errorMessage)
+                .find((m) => m !== undefined);
+            failed.push({
+                key,
+                error: new Error(firstError !== undefined ? `${job.status}: ${firstError}` : String(job.status)),
+            });
+        }
+    }
+    return new RunResult(workflowId, finalStatus.status, artifacts, succeeded, failed, downloader);
+}
+/** Derive the partition key `"{i}"` from a `file-{i}` job ref; the ref verbatim otherwise. */
+function jobIndexFromRef(ref) {
+    return ref.startsWith('file-') ? ref.slice('file-'.length) : ref;
+}
+const _FANOUT_REF = /^file-\d+$/;
+/**
+ * True when a terminal status describes a homogeneous `files([...])` fan-out —
+ * i.e. it has at least one job and EVERY job ref is `file-{i}` (the ids the
+ * {@link FilesRecipe} lowering assigns). A single-file {@link Recipe} omits the
+ * job id, so its job carries a non-`file-N` ref (e.g. `op`) and this is false.
+ *
+ * This is the data-driven seam that lets {@link Handle.wait}/{@link Handle.result}
+ * pick the per-job producer ({@link projectMultiJobToRunResult}) over the
+ * single-output one for a fan-out — WITHOUT a construction-time marker, so a
+ * fan-out **reattached** via `client.workflow(id)` (which carries no marker)
+ * still partitions per job. Keys are recovered from the `file-{i}` refs.
+ *
+ * @internal Exported for the file-first `Handle`; not part of the public API.
+ */
+export function isFanoutStatus(finalStatus) {
+    const jobs = finalStatus.jobs ?? [];
+    return jobs.length > 0 && jobs.every((job) => _FANOUT_REF.test(job.ref));
+}
 /** Named constructors for {@link FileInput} — mirror the PHP static factories. */
 export const fileInput = {
     path(path) {
@@ -252,16 +388,20 @@ export class Recipe {
      * `operations[]`; the job `id` is omitted (a single job referenced by
      * nothing — the server auto-assigns `job_N`).
      *
-     * @internal Consumed by FF2b's `run()` (after a real upload) and by the
-     *   cross-language parity harness (with a fixed id). Not part of the
-     *   caller-facing fluent surface.
+     * When `callbackUrl` is given (the file-first `submit()` path), it is built
+     * INTO the payload at construction (`callback_url`) rather than spread onto an
+     * already-built readonly payload. `run()` passes no `callbackUrl`.
+     *
+     * @internal Consumed by FF2b's `run()` (after a real upload), FF5b's
+     *   `submit()` (with a webhook), and the cross-language parity harness (with a
+     *   fixed id). Not part of the caller-facing fluent surface.
      */
-    toWorkflowPayload(fileId) {
+    toWorkflowPayload(fileId, callbackUrl) {
         const operations = this.steps.map((step) => this.lowerStep(step));
         // Key order (source, operations) matches the PHP `toWire()` so the
         // JSON-string serialisation is byte-identical across languages.
         const job = { source: uploadSource(fileId), operations };
-        return { jobs: [job] };
+        return callbackUrl === undefined ? { jobs: [job] } : { jobs: [job], callback_url: callbackUrl };
     }
     /** The result-addressing key passed to `file()`, or undefined. */
     key() {
@@ -271,6 +411,14 @@ export class Recipe {
     get stepCount() {
         return this.steps.length;
     }
+    /**
+     * The captured op chain. Read by {@link FilesRecipe} to compose a shared
+     * chain across many inputs without duplicating the chain-method validation.
+     * @internal
+     */
+    get recipeSteps() {
+        return this.steps;
+    }
     /**
      * Execute the recipe end-to-end: upload the input (when required), create
      * the workflow, await a terminal state (SSE with poll fallback), then
@@ -289,34 +437,9 @@ export class Recipe {
             throw new GislConfigError('Recipe.run() requires a client; build the recipe via gisl().file(...) rather than constructing Recipe directly.', { reason: 'no_client' });
         }
         const deadline = Date.now() + _parseMaxWait(options.maxWait ?? 300_000);
-        // 1. Resolve the upload id. A pre-uploaded id skips the upload entirely;
-        // a path / blob is uploaded now, emitting {phase:'upload'} progress.
-        let fileId;
-        if (this.input.kind === 'uploadId') {
-            fileId = this.input.fileId;
-        }
-        else {
-            const source = this.input.kind === 'path' ? this.input.path : this.input.blob;
-            const up = await this.client.uploadFile(source, {
-                signal,
-                ...(onProgress !== undefined
-                    ? {
-                        onProgress: (uploadedBytes, totalBytes) => {
-                            onProgress({ phase: 'upload', uploadedBytes, totalBytes });
-                        },
-                    }
-                    : {}),
-            });
-            fileId = up.fileId;
-        }
-        _checkAborted(signal);
-        if (Date.now() >= deadline) {
-            throw new GislTimeoutError('Upload completed but maxWait elapsed before workflow could be created');
-        }
-        // 2. Create the workflow from the lowered payload.
-        const payload = this.toWorkflowPayload(fileId);
-        const created = await this.client.createWorkflow(payload);
-        _checkAborted(signal);
+        // 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);
         // 3. Wait to terminal status — SSE first, poll on a genuine SSE error.
         // Caller-aborted + deadline-elapsed errors MUST propagate (not transient).
         let finalStatus;
@@ -354,46 +477,80 @@ export class Recipe {
             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);
-        // Flatten to the lean OutputFile[] (the four file-first fields only).
-        const artifacts = [];
-        for (const job of downloads.downloads) {
-            for (const f of job.files) {
-                artifacts.push({
-                    url: f.downloadUrl,
-                    filename: f.filename,
-                    sizeBytes: f.sizeBytes,
-                    operation: f.operation,
-                });
-            }
+        // Download URLs from getWorkflowDownloads are pre-signed and require no SDK
+        // auth, so the downloader issues a plain unauthenticated fetch.
+        const downloader = new HttpDownloader();
+        return projectDownloadsToRunResult(created.workflowId, finalStatus, downloads.downloads, this.recipeKey ?? null, downloader);
+    }
+    /**
+     * Fire-and-forget the recipe: upload the input (when required), create the
+     * workflow (wiring `webhook` into `callback_url` when given), and return a
+     * client-bound {@link Handle} carrying the workflow id + webhook secret + the
+     * recipe key. Does NOT wait for terminal status — call `handle.wait()` /
+     * `handle.result()` later to collect the {@link RunResult}.
+     *
+     * Requires a client bound at construction time (same `no_client` guard as
+     * {@link run}). `webhook` is OPTIONAL: when omitted, no `callback_url` is
+     * sent. Mirrors the PHP `Recipe.submit()`.
+     *
+     * @param webhook Absolute callback URL the server POSTs lifecycle events to.
+     */
+    async submit(webhook) {
+        if (this.client === undefined) {
+            throw new GislConfigError('Recipe.submit() requires a client; build the recipe via gisl().file(...) rather than constructing Recipe directly.', { reason: 'no_client' });
         }
-        // Partition the single input into succeeded / failed by terminal state.
-        // Success is ONLY `completed`: every other terminal state — `failed`,
-        // `partially_failed`, `cancelled`, `expired`,
-        // `paused_insufficient_credits` — is a non-success and partitions into
-        // `failed` so a caller's `ok`/`succeeded` check can never treat a
-        // cancelled/expired/paused run as a clean result (codex review high).
-        const state = finalStatus.status;
-        const key = this.recipeKey ?? null;
-        let succeeded;
-        let failed;
-        if (state === 'completed') {
-            succeeded = [{ key, outputs: artifacts }];
-            failed = [];
+        // submit() is fire-and-forget — NO whole-run deadline. The upload may be
+        // large (a multi-GB master, example 12) and is bounded by the HTTP client's
+        // own request timeout, not an arbitrary submit-side cap. Pass `undefined`
+        // so the post-upload deadline check is skipped: a 300s cap here would throw
+        // on a slow-but-successful big upload before createWorkflow (codex).
+        const created = await this._uploadAndCreate(webhook, undefined);
+        return new Handle(created.workflowId, created.webhookSecret != null ? created.webhookSecret : undefined, this.client, this.recipeKey ?? null);
+    }
+    /**
+     * Resolve the upload id (verbatim for a pre-uploaded id; uploading a path /
+     * blob otherwise, emitting `{phase:'upload'}` progress), check the post-upload
+     * deadline, lower to the workflow-create payload (wiring `webhook` into
+     * `callback_url`), and create the workflow. Shared first half of
+     * {@link run} + {@link submit}.
+     *
+     * The post-upload deadline check carries a prior codex fix (9a117f04eb59): a
+     * slow upload must not proceed to createWorkflow past the deadline.
+     */
+    async _uploadAndCreate(webhook, deadline, onProgress, signal) {
+        // 1. Resolve the upload id. A pre-uploaded id skips the upload entirely;
+        // a path / blob is uploaded now, emitting {phase:'upload'} progress.
+        let fileId;
+        if (this.input.kind === 'uploadId') {
+            fileId = this.input.fileId;
         }
         else {
-            const firstError = (finalStatus.jobs ?? [])
-                .flatMap((j) => j.operations ?? [])
-                .map((op) => op.errorMessage)
-                .find((m) => m !== undefined);
-            succeeded = [];
-            failed = [
-                { key, error: new Error(firstError !== undefined ? `${state}: ${firstError}` : state) },
-            ];
+            const source = this.input.kind === 'path' ? this.input.path : this.input.blob;
+            const up = await this.client.uploadFile(source, {
+                signal,
+                ...(onProgress !== undefined
+                    ? {
+                        onProgress: (uploadedBytes, totalBytes) => {
+                            onProgress({ phase: 'upload', uploadedBytes, totalBytes });
+                        },
+                    }
+                    : {}),
+            });
+            fileId = up.fileId;
         }
-        // Download URLs from getWorkflowDownloads are pre-signed and require no SDK
-        // auth, so the downloader issues a plain unauthenticated fetch.
-        const downloader = new HttpDownloader();
-        return new RunResult(created.workflowId, state, artifacts, succeeded, failed, downloader);
+        _checkAborted(signal);
+        // run() passes a whole-run deadline (the codex 9a117f04eb59 fix: a slow
+        // upload must not proceed to createWorkflow past maxWait); submit() passes
+        // `undefined` (fire-and-forget, no upload cap), so the check is skipped.
+        if (deadline !== undefined && Date.now() >= deadline) {
+            throw new GislTimeoutError('Upload completed but maxWait elapsed before workflow could be created');
+        }
+        // 2. Create the workflow from the lowered payload (callback_url built into
+        // the payload at construction when a webhook is given).
+        const payload = this.toWorkflowPayload(fileId, webhook);
+        const created = await this.client.createWorkflow(payload);
+        _checkAborted(signal);
+        return created;
     }
     withStep(step) {
         return new Recipe(this.input, this.recipeKey, [...this.steps, step], this.presetDefaults, this.scopedPresetDefaults, this.client);
@@ -443,3 +600,241 @@ export class Recipe {
         return undefined;
     }
 }
+/**
+ * The homogeneous fan-out builder value (FF3a). `client.files([a, b, c])`
+ * returns a `FilesRecipe`; the op-chain methods (`compress`, `convert`,
+ * `thumbnail`, `textWatermark`) build ONE shared recipe (chain) that is applied
+ * to EVERY input file in ONE workflow. `run()` returns a partitioned
+ * {@link RunResult} — one `succeeded`/`failed` entry per input, keyed by its
+ * 0-based index ("0", "1", …) so one bad input does not sink the rest.
+ *
+ * **Immutable / clone-on-write**, exactly like {@link Recipe}: every op returns
+ * a NEW `FilesRecipe` carrying the appended step. The inputs are held as an
+ * ORDERED list (NOT a map) so the per-file index is the partition key.
+ *
+ * **Lowering composes {@link Recipe} per file** rather than duplicating
+ * `lowerStep`/`lowerCompressOptions`: for each input `i` it builds an internal
+ * single-file `Recipe(input_i, …, steps)`, calls its `toWorkflowPayload` to get
+ * that file's one-job payload, then merges all jobs into ONE
+ * {@link WorkflowCreatePayload} with `jobs[i].id = "file-{i}"`. This preserves
+ * each file's media-hint (different extensions per input resolve compress
+ * presets independently).
+ *
+ * Exposes both `run()` (blocking, returns a partitioned {@link RunResult}) and
+ * `submit(webhook?)` (fire-and-forget, returns a {@link Handle}). Mirrors the
+ * PHP `FilesRecipe`.
+ */
+export class FilesRecipe {
+    inputs;
+    steps;
+    presetDefaults;
+    scopedPresetDefaults;
+    client;
+    constructor(inputs, steps = [], presetDefaults, scopedPresetDefaults, client) {
+        this.inputs = inputs;
+        this.steps = steps;
+        this.presetDefaults = presetDefaults;
+        this.scopedPresetDefaults = scopedPresetDefaults;
+        this.client = client;
+    }
+    /**
+     * Reduce file size on every input. `optimize` selects a per-media preset
+     * (resolved per file at lower-time, so each input's extension picks its own
+     * preset). Reuses {@link Recipe}'s validation — a directly-constructed
+     * lowering builds an internal Recipe that throws the same `GislConfigError`.
+     */
+    compress(optimize) {
+        return this.withStep(this.baseRecipe().compress(optimize));
+    }
+    /** Change every input's format. `format` lowers verbatim to the `format` option. */
+    convert(format) {
+        return this.withStep(this.baseRecipe().convert(format));
+    }
+    /** Generate a preview of every input. Omitted dimensions are dropped from the wire options. */
+    thumbnail(options = {}) {
+        return this.withStep(this.baseRecipe().thumbnail(options));
+    }
+    /** Apply the same text watermark to every input. */
+    textWatermark(text) {
+        return this.withStep(this.baseRecipe().textWatermark(text));
+    }
+    /** The number of inputs in this fan-out (introspection / tests). */
+    get inputCount() {
+        return this.inputs.length;
+    }
+    /** The number of operations chained so far (introspection / tests). */
+    get stepCount() {
+        return this.steps.length;
+    }
+    /**
+     * Lower this fan-out to a single multi-job workflow-create payload against a
+     * list of resolved upload ids (one per input, in input order). Each input `i`
+     * becomes ONE job with `id = "file-{i}"`, its `source: upload(fileIds[i])`,
+     * and the SHARED lowered `operations[]`. Composes the single-file
+     * {@link Recipe.toWorkflowPayload} per file so per-file media-hints resolve
+     * independently and lowering logic is not duplicated.
+     *
+     * @internal Consumed by {@link run} (after uploading all inputs) and the
+     *   cross-language parity harness (with fixed ids). Not caller-facing.
+     */
+    toWorkflowPayload(fileIds, callbackUrl) {
+        const jobs = this.inputs.map((input, i) => {
+            const single = new Recipe(input, undefined, this.steps, this.presetDefaults, this.scopedPresetDefaults);
+            const oneJob = single.toWorkflowPayload(fileIds[i]).jobs[0];
+            // Key order (id, source, operations) matches the PHP `toWire()` so the
+            // JSON-string serialisation is byte-identical across languages.
+            return { id: `file-${i}`, source: oneJob.source, operations: oneJob.operations };
+        });
+        // When `callbackUrl` is given (the file-first `submit()` path) it is built
+        // INTO the payload (`callback_url`) — mirrors Recipe.toWorkflowPayload.
+        // `run()` passes no callbackUrl.
+        return callbackUrl === undefined ? { jobs } : { jobs, callback_url: callbackUrl };
+    }
+    /**
+     * Execute the fan-out end-to-end: upload EVERY input, create ONE workflow
+     * with one job per input, await a terminal state (SSE with poll fallback),
+     * then resolve the per-job downloads into a partitioned {@link RunResult}.
+     * `partially_failed` is a NORMAL terminal state here — its successful jobs
+     * land in `succeeded`, its failed jobs in `failed`.
+     *
+     * Requires a client bound at construction time — `gisl().files(...)` wires
+     * it; a directly-constructed `FilesRecipe` throws {@link GislConfigError}.
+     * Mirrors the single-file {@link Recipe.run}; see {@link submit} for the
+     * fire-and-forget arm.
+     */
+    async run(options = {}) {
+        const signal = options.signal;
+        const onProgress = options.onProgress;
+        if (this.client === undefined) {
+            throw new GislConfigError('FilesRecipe.run() requires a client; build the fan-out via gisl().files(...) rather than constructing FilesRecipe directly.', { reason: 'no_client' });
+        }
+        const deadline = Date.now() + _parseMaxWait(options.maxWait ?? 300_000);
+        // 1+2. Upload EVERY input + create ONE multi-job workflow. Shared with
+        // submit() (which passes a webhook → callback_url and no deadline).
+        const created = await this._uploadAllAndCreate(undefined, deadline, onProgress, signal);
+        // 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 GislTimeoutError)
+                throw err;
+            if (err instanceof DOMException && err.name === 'AbortError')
+                throw err;
+            if (err instanceof GislApiError)
+                throw err;
+            finalStatus = await _pollToTerminal(this.client, {
+                workflowId: created.workflowId,
+                deadline,
+                signal,
+                pollIntervalMs: options.pollIntervalMs,
+            });
+        }
+        // 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`);
+        }
+        const downloads = await this.client.getWorkflowDownloads(created.workflowId);
+        // keyByRef maps each job ref ("file-{i}") to the partition key. Today the
+        // key is just the index string; the Map seam leaves room for the FF3b
+        // keyed-fan-out card to map refs to caller-supplied keys without changing
+        // the producer's signature.
+        const keyByRef = new Map(this.inputs.map((_, i) => [`file-${i}`, String(i)]));
+        const downloader = new HttpDownloader();
+        return projectMultiJobToRunResult(created.workflowId, finalStatus, downloads.downloads, keyByRef, downloader);
+    }
+    /**
+     * Fire-and-forget the fan-out: upload every input, create ONE multi-job
+     * workflow (wiring `webhook` into `callback_url` when given), and return a
+     * client-bound {@link Handle}. Does NOT wait for terminal status — call
+     * `handle.wait()` / `handle.result()` later to collect the partitioned
+     * {@link RunResult}. The Handle detects the fan-out from the wire `file-{i}`
+     * job refs, so per-file `byKey()` works even after a `client.workflow(id)`
+     * reattach (the keys are the input indices `"0"`, `"1"`, …).
+     *
+     * Requires a client bound at construction time (same `no_client` guard as
+     * {@link run}). `webhook` is OPTIONAL. Fire-and-forget, so NO whole-run
+     * deadline (a multi-GB upload is bounded by the HTTP client's own timeout).
+     * Mirrors the single-file {@link Recipe.submit}.
+     *
+     * @param webhook Absolute callback URL the server POSTs lifecycle events to.
+     */
+    async submit(webhook) {
+        if (this.client === undefined) {
+            throw new GislConfigError('FilesRecipe.submit() requires a client; build the fan-out via gisl().files(...) rather than constructing FilesRecipe directly.', { reason: 'no_client' });
+        }
+        const created = await this._uploadAllAndCreate(webhook, undefined);
+        return new Handle(created.workflowId, created.webhookSecret != null ? created.webhookSecret : undefined, this.client, null);
+    }
+    /**
+     * Upload every input (verbatim for a pre-uploaded id; uploading a path /
+     * blob otherwise, emitting `{phase:'upload'}` progress) then create ONE
+     * multi-job workflow (one job per input, `callback_url` built in when
+     * `webhook` is given). Shared first half of {@link run} + {@link submit}.
+     *
+     * Uploads are sequential so progress events stay ordered and the abort
+     * signal is honoured promptly; a resource arm is impossible in TS (Blob).
+     * `run()` passes a whole-run deadline (a slow upload must not proceed to
+     * createWorkflow past maxWait); `submit()` passes `undefined`, so the
+     * deadline checks are skipped.
+     */
+    async _uploadAllAndCreate(webhook, deadline, onProgress, signal) {
+        const fileIds = [];
+        for (const input of this.inputs) {
+            // Fail fast between uploads — a deadline that elapses mid-batch should
+            // not force every remaining input to upload before throwing.
+            _checkAborted(signal);
+            if (deadline !== undefined && Date.now() >= deadline) {
+                throw new GislTimeoutError('maxWait elapsed during fan-out uploads before all inputs were uploaded');
+            }
+            if (input.kind === 'uploadId') {
+                fileIds.push(input.fileId);
+            }
+            else {
+                const source = input.kind === 'path' ? input.path : input.blob;
+                const up = await this.client.uploadFile(source, {
+                    signal,
+                    ...(onProgress !== undefined
+                        ? {
+                            onProgress: (uploadedBytes, totalBytes) => {
+                                onProgress({ phase: 'upload', uploadedBytes, totalBytes });
+                            },
+                        }
+                        : {}),
+                });
+                fileIds.push(up.fileId);
+            }
+        }
+        _checkAborted(signal);
+        if (deadline !== undefined && Date.now() >= deadline) {
+            throw new GislTimeoutError('Uploads completed but maxWait elapsed before workflow could be created');
+        }
+        const created = await this.client.createWorkflow(this.toWorkflowPayload(fileIds, webhook));
+        _checkAborted(signal);
+        return created;
+    }
+    /**
+     * The shared single-file {@link Recipe} that captures the op chain (input is
+     * a placeholder — only the steps are read). Reuses Recipe's op-chain
+     * validation + coercion so a `FilesRecipe.compress(bad)` throws the identical
+     * `GislConfigError` as `Recipe.compress(bad)`.
+     */
+    baseRecipe() {
+        // The placeholder input never reaches the wire (only `steps` are read off
+        // the returned Recipe). A path placeholder gives compress() a media hint so
+        // optimize validation matches the single-file path; per-file lowering in
+        // toWorkflowPayload() rebuilds a Recipe with the REAL input.
+        return new Recipe(this.inputs[0] ?? fileInput.path('placeholder'), undefined, this.steps, this.presetDefaults, this.scopedPresetDefaults);
+    }
+    withStep(recipeWithStep) {
+        return new FilesRecipe(this.inputs, recipeWithStep.recipeSteps, this.presetDefaults, this.scopedPresetDefaults, this.client);
+    }
+}

package/dist/gisl.d.ts

@@ -23,7 +23,8 @@ import type { GislClientConfig } from './types.js';
 import { OperationBuilder } from './builder.js';
 import { MergeBuilder, type Asset, type MergeOptions } from './merge.js';
 import { PresetDefaults } from './ergonomic/presets/index.js';
-import { Recipe, type FileInput } from './file-first.js';
+import { Recipe, FilesRecipe, type FileInput } from './file-first.js';
+import { Handle } from './handle.js';
 /**
  * Operations that may be invoked on a `gisl.anonymous()` client without
  * raising `GislFeatureRequiresAuthError`. Empty until the free-tier launch
@@ -77,6 +78,26 @@ export type ErgonomicClient = GislClient & {
      * Execution (`run()`) lands in FF2b.
      */
     file(input: string | Blob | FileInput, key?: string): Recipe;
+    /**
+     * Homogeneous fan-out entry point (FF3a). Apply ONE recipe (op chain) to
+     * MANY input files in ONE workflow. Each element is a filesystem path
+     * (string), an in-memory {@link FileInput} via `fileInput.*`, or a Blob/File.
+     * Returns an immutable {@link FilesRecipe} you call the same ops on
+     * (`.compress()` / `.convert()` / `.thumbnail()` / `.textWatermark()`); the
+     * chain applies to every input. `run()` returns a partitioned
+     * {@link RunResult} keyed by each input's 0-based index — one bad input does
+     * not sink the rest. `submit(webhook?)` is the fire-and-forget arm: it
+     * returns a {@link Handle} whose `wait()`/`result()` partition per input.
+     */
+    files(inputs: ReadonlyArray<string | Blob | FileInput>): FilesRecipe;
+    /**
+     * Reattach to a previously-created workflow (FF5a). Returns a client-bound
+     * {@link Handle} you can `.status()` / `.wait()` / `.result()`. The handle
+     * carries no `webhookSecret` and no recipe key, so the {@link RunResult}
+     * from `wait()`/`result()` is keyless (`succeeded[].key === null`) — address
+     * outputs positionally or via the sinks.
+     */
+    workflow(id: string): Handle;
     compress(input: string | Blob, options?: Record<string, unknown>): OperationBuilder;
     convert(input: string | Blob, options?: Record<string, unknown>): OperationBuilder;
     thumbnail(input: string | Blob, options?: Record<string, unknown>): OperationBuilder;