@giveitsmaller/sdk 0.8.0 → 0.9.0

package/dist/gisl.js

@@ -22,7 +22,8 @@ import { resolveApiKey, resolveEndpoint, } from './credentials.js';
 import { OperationBuilder } from './builder.js';
 import { MergeBuilder, asset } from './merge.js';
 import { PresetDefaults } from './ergonomic/presets/index.js';
-import { Recipe, fileInput } from './file-first.js';
+import { Recipe, FilesRecipe, fileInput } from './file-first.js';
+import { Handle } from './handle.js';
 // ---------------------------------------------------------------------------
 // Anonymous-capable operation allowlist (internal)
 // ---------------------------------------------------------------------------
@@ -88,6 +89,35 @@ function wrapErgonomic(client, presetDefaults, scopedPresetDefaults) {
                     return new Recipe(resolved, key, [], presetDefaults, scopedPresetDefaults, target);
                 };
             }
+            if (prop === 'files') {
+                // Homogeneous fan-out entry point (FF3a) — apply ONE recipe (op chain)
+                // to MANY input files in ONE workflow. Each element is coerced the same
+                // way `file()` coerces its single input: a bare string is a filesystem
+                // path, a Blob/File an in-memory input, a `FileInput` passed through.
+                // The fan-out's RunResult partitions per input by 0-based index.
+                return (inputs) => {
+                    if (inputs.length === 0) {
+                        // A zero-input fan-out is a caller error — "one failing input
+                        // doesn't sink the rest" is meaningless with no inputs, and it
+                        // would otherwise create an empty-jobs workflow the API 422s.
+                        throw new GislConfigError('files() requires at least one input file.', {
+                            reason: 'no_inputs',
+                        });
+                    }
+                    const resolved = inputs.map((input) => typeof input === 'string'
+                        ? fileInput.path(input)
+                        : input instanceof Blob
+                            ? fileInput.blob(input)
+                            : input);
+                    return new FilesRecipe(resolved, [], presetDefaults, scopedPresetDefaults, target);
+                };
+            }
+            if (prop === 'workflow') {
+                // Reattach to a previously-created workflow (FF5a). Returns a
+                // client-bound Handle with no webhookSecret and no recipe key —
+                // its RunResult is therefore keyless (succeeded[].key === null).
+                return (id) => new Handle(id, undefined, target);
+            }
             if (prop === 'compress' || prop === 'convert' || prop === 'thumbnail') {
                 return (input, options = {}) => {
                     // T4b — pass client-scope presetDefaults into the builder so

package/dist/handle.d.ts

@@ -0,0 +1,153 @@
+/**
+ * File-first {@link Handle} + {@link StatusSnapshot} value objects (FF5a).
+ *
+ * A `Handle` is the lightweight return of a fire-and-forget submit
+ * (`OperationBuilder.submit()` / `MergeBuilder.submit()`) AND the value
+ * `client.workflow(id)` hands back to reattach to a previously-created
+ * workflow. When a `Handle` carries a bound client it exposes three
+ * accessors:
+ *
+ *  - `status()` — one non-blocking status fetch, projected to a
+ *    {@link StatusSnapshot}.
+ *  - `wait(maxWait, onProgress?)` — the ONLY blocking path: await terminal
+ *    (SSE with poll fallback), then fetch downloads + project to a
+ *    {@link RunResult}.
+ *  - `result()` — non-blocking: fetch status once; if terminal, fetch
+ *    downloads + project to a {@link RunResult}; if NOT terminal, throw
+ *    {@link GislResultNotReadyError}. Never waits/polls.
+ *
+ * A `Handle` built WITHOUT a client (the operation-first/merge `submit()`
+ * path) keeps its data fields + `toJSON()` byte-identical to the prior
+ * `{ workflowId, webhookSecret }` interface; its accessors throw
+ * {@link GislConfigError} (reason `no_client`).
+ *
+ * Module placement: this lives in its OWN module (not `builder.ts` or
+ * `file-first.ts`) to keep the ESM import graph acyclic at module-load time.
+ * It imports the await-primitives from `builder.ts` and the
+ * {@link RunResult} + {@link projectDownloadsToRunResult} projection from
+ * `file-first.ts`; `builder.ts`/`merge.ts` import `Handle` back for
+ * construction inside their `submit()` methods. That back-edge is
+ * DEFERRED-USAGE-ONLY (construction happens at call time, not module-load),
+ * which ESM resolves cleanly.
+ *
+ * Mirrors the PHP `Gisl\Sdk\Ergonomic\Handle` + `Gisl\Sdk\Ergonomic\StatusSnapshot`.
+ */
+import type { GislClient } from './client.js';
+import { type ProgressEvent } from './builder.js';
+import { RunResult } from './file-first.js';
+/**
+ * A non-blocking snapshot of a workflow's lifecycle state, returned by
+ * {@link Handle.status}. `state` is the RAW wire `WorkflowStatus` value,
+ * verbatim (`pending` | `in_progress` | `completed` | `failed` |
+ * `partially_failed` | `paused_insufficient_credits` | `cancelled` |
+ * `expired`). There is NO `phase` field — phase is an SSE-only concept; the
+ * status response carries no phase.
+ *
+ * Mirrors the PHP `Gisl\Sdk\Ergonomic\StatusSnapshot`.
+ */
+export declare class StatusSnapshot {
+    readonly workflowId: string;
+    readonly state: string;
+    constructor(workflowId: string, state: string);
+    /**
+     * True when {@link state} is one of the terminal states (`completed`,
+     * `failed`, `partially_failed`, `cancelled`, `expired`,
+     * `paused_insufficient_credits`); false for `pending` / `in_progress`.
+     */
+    isTerminal(): boolean;
+    /** Plain-object projection. Mirrors the PHP `toArray()`. */
+    toJSON(): {
+        workflowId: string;
+        state: string;
+    };
+}
+/**
+ * Handle to a created workflow. Carries `workflowId` + an optional
+ * `webhookSecret` (the data the operation-first/merge `submit()` returns)
+ * and, when reattached or built by the file-first run path, an optional
+ * bound {@link GislClient}.
+ *
+ * The bound client is OPTIONAL (mirrors how {@link RunResult} binds its
+ * {@link Downloader}): the data fields + {@link toJSON} stay byte-identical
+ * whether or not a client is present, so the operation-first/merge `submit()`
+ * back-compat fixture (`{ workflowId, webhookSecret }` via `toJSON()`) holds.
+ * When the client is absent, {@link status}/{@link wait}/{@link result} throw
+ * {@link GislConfigError} (reason `no_client`).
+ *
+ * A handle built via `client.workflow(id)` has NO recipe key, so its
+ * {@link RunResult} is keyless (`succeeded[].key === null`) — address its
+ * outputs positionally / via the sinks rather than `byKey()`.
+ *
+ * Mirrors the PHP `Gisl\Sdk\Ergonomic\Handle`.
+ */
+export declare class Handle {
+    #private;
+    readonly workflowId: string;
+    readonly webhookSecret?: string | undefined;
+    constructor(workflowId: string, webhookSecret?: string | undefined, client?: GislClient, key?: string | null);
+    /**
+     * Fetch the workflow's current status once (non-blocking) and project it to
+     * a {@link StatusSnapshot}.
+     * @throws {GislConfigError} reason `no_client` when no client is bound.
+     */
+    status(): Promise<StatusSnapshot>;
+    /**
+     * Block until the workflow reaches a terminal state (SSE with poll
+     * fallback), then fetch its downloads and project to a {@link RunResult}.
+     * This is the ONLY blocking accessor on a `Handle`.
+     *
+     * @param maxWait Wall-clock deadline for the wait + downloads (string suffix
+     *   `'2h'`/`'30m'`/`'120s'` or a number of milliseconds). Defaults to 300s,
+     *   matching `Recipe.run()` / the PHP `Handle::wait()` default.
+     * @throws {GislConfigError} reason `no_client` when no client is bound.
+     * @throws {GislTimeoutError} when `maxWait` elapses before terminal.
+     */
+    wait(maxWait?: string | number, onProgress?: (event: ProgressEvent) => void): Promise<RunResult>;
+    /**
+     * Non-blocking result accessor. Fetches the workflow status once: if the
+     * workflow is terminal, fetches its downloads and projects to a
+     * {@link RunResult}; if it is NOT terminal, throws
+     * {@link GislResultNotReadyError}. Never waits or polls — use {@link wait}
+     * to block.
+     *
+     * @throws {GislConfigError} reason `no_client` when no client is bound.
+     * @throws {GislResultNotReadyError} when the workflow is not yet terminal.
+     */
+    result(): Promise<RunResult>;
+    /**
+     * Project a terminal status + its per-job downloads into a {@link RunResult},
+     * choosing the producer DATA-DRIVEN off the wire (not a construction-time
+     * marker, so a fan-out reattached via `client.workflow(id)` — which carries
+     * no marker — still partitions per job):
+     *
+     *  - A `files([...])` fan-out (every job ref is `file-{i}`, see
+     *    {@link isFanoutStatus}) → {@link projectMultiJobToRunResult} with an
+     *    empty `keyByRef`, so each input's key is recovered from its `file-{i}`
+     *    ref (`"0"`, `"1"`, …). A submitted/reattached fan-out carries no
+     *    caller-supplied keys — keyed fan-out is a separate concern.
+     *  - Anything else (the single-file {@link Recipe} path) →
+     *    {@link projectDownloadsToRunResult} keyed by this handle's `#key`
+     *    (the recipe key from a file-first `submit()`, or `null` on reattach).
+     */
+    private project;
+    /**
+     * Plain-object projection. Field order (`workflowId`, then `webhookSecret`
+     * when present) and the omit-when-undefined behaviour match the PHP
+     * `toArray()` so JSON-string parity holds with the prior `Handle` shape.
+     * The bound client is NEVER serialised.
+     */
+    toJSON(): {
+        workflowId: string;
+        webhookSecret?: string;
+    };
+    /**
+     * Back-compat alias for {@link toJSON} — the prior operation-first/merge
+     * `submit()` fixture asserts a plain `{ workflowId, webhookSecret }` shape.
+     */
+    toArray(): {
+        workflowId: string;
+        webhookSecret?: string;
+    };
+    private makeDownloader;
+    private requireClient;
+}

package/dist/handle.js

@@ -0,0 +1,253 @@
+/**
+ * File-first {@link Handle} + {@link StatusSnapshot} value objects (FF5a).
+ *
+ * A `Handle` is the lightweight return of a fire-and-forget submit
+ * (`OperationBuilder.submit()` / `MergeBuilder.submit()`) AND the value
+ * `client.workflow(id)` hands back to reattach to a previously-created
+ * workflow. When a `Handle` carries a bound client it exposes three
+ * accessors:
+ *
+ *  - `status()` — one non-blocking status fetch, projected to a
+ *    {@link StatusSnapshot}.
+ *  - `wait(maxWait, onProgress?)` — the ONLY blocking path: await terminal
+ *    (SSE with poll fallback), then fetch downloads + project to a
+ *    {@link RunResult}.
+ *  - `result()` — non-blocking: fetch status once; if terminal, fetch
+ *    downloads + project to a {@link RunResult}; if NOT terminal, throw
+ *    {@link GislResultNotReadyError}. Never waits/polls.
+ *
+ * A `Handle` built WITHOUT a client (the operation-first/merge `submit()`
+ * path) keeps its data fields + `toJSON()` byte-identical to the prior
+ * `{ workflowId, webhookSecret }` interface; its accessors throw
+ * {@link GislConfigError} (reason `no_client`).
+ *
+ * Module placement: this lives in its OWN module (not `builder.ts` or
+ * `file-first.ts`) to keep the ESM import graph acyclic at module-load time.
+ * It imports the await-primitives from `builder.ts` and the
+ * {@link RunResult} + {@link projectDownloadsToRunResult} projection from
+ * `file-first.ts`; `builder.ts`/`merge.ts` import `Handle` back for
+ * construction inside their `submit()` methods. That back-edge is
+ * DEFERRED-USAGE-ONLY (construction happens at call time, not module-load),
+ * which ESM resolves cleanly.
+ *
+ * Mirrors the PHP `Gisl\Sdk\Ergonomic\Handle` + `Gisl\Sdk\Ergonomic\StatusSnapshot`.
+ */
+import { GislApiError, GislConfigError, GislResultNotReadyError, GislTimeoutError, } from './errors.js';
+import { _consumeSseToTerminal, _pollToTerminal, _parseMaxWait, } from './builder.js';
+import { projectDownloadsToRunResult, projectMultiJobToRunResult, isFanoutStatus, } from './file-first.js';
+import { HttpDownloader } from './http-downloader.js';
+/**
+ * The terminal workflow states. A status response in any of these states
+ * will not change without caller action. Mirrors the `TERMINAL_STATUSES`
+ * sets in `client.ts` / `WorkflowConstants` (PHP) — `paused_insufficient_credits`
+ * is treated as terminal because the workflow only resumes on caller action.
+ */
+const TERMINAL_STATES = new Set([
+    'completed',
+    'failed',
+    'partially_failed',
+    'cancelled',
+    'expired',
+    'paused_insufficient_credits',
+]);
+/**
+ * A non-blocking snapshot of a workflow's lifecycle state, returned by
+ * {@link Handle.status}. `state` is the RAW wire `WorkflowStatus` value,
+ * verbatim (`pending` | `in_progress` | `completed` | `failed` |
+ * `partially_failed` | `paused_insufficient_credits` | `cancelled` |
+ * `expired`). There is NO `phase` field — phase is an SSE-only concept; the
+ * status response carries no phase.
+ *
+ * Mirrors the PHP `Gisl\Sdk\Ergonomic\StatusSnapshot`.
+ */
+export class StatusSnapshot {
+    workflowId;
+    state;
+    constructor(workflowId, state) {
+        this.workflowId = workflowId;
+        this.state = state;
+    }
+    /**
+     * True when {@link state} is one of the terminal states (`completed`,
+     * `failed`, `partially_failed`, `cancelled`, `expired`,
+     * `paused_insufficient_credits`); false for `pending` / `in_progress`.
+     */
+    isTerminal() {
+        return TERMINAL_STATES.has(this.state);
+    }
+    /** Plain-object projection. Mirrors the PHP `toArray()`. */
+    toJSON() {
+        return { workflowId: this.workflowId, state: this.state };
+    }
+}
+/**
+ * Handle to a created workflow. Carries `workflowId` + an optional
+ * `webhookSecret` (the data the operation-first/merge `submit()` returns)
+ * and, when reattached or built by the file-first run path, an optional
+ * bound {@link GislClient}.
+ *
+ * The bound client is OPTIONAL (mirrors how {@link RunResult} binds its
+ * {@link Downloader}): the data fields + {@link toJSON} stay byte-identical
+ * whether or not a client is present, so the operation-first/merge `submit()`
+ * back-compat fixture (`{ workflowId, webhookSecret }` via `toJSON()`) holds.
+ * When the client is absent, {@link status}/{@link wait}/{@link result} throw
+ * {@link GislConfigError} (reason `no_client`).
+ *
+ * A handle built via `client.workflow(id)` has NO recipe key, so its
+ * {@link RunResult} is keyless (`succeeded[].key === null`) — address its
+ * outputs positionally / via the sinks rather than `byKey()`.
+ *
+ * Mirrors the PHP `Gisl\Sdk\Ergonomic\Handle`.
+ */
+export class Handle {
+    workflowId;
+    webhookSecret;
+    // True ES private (`#`), NOT a TS `private` modifier: a `private` constructor
+    // parameter property is an enumerable own field, so spreading/logging/Object
+    // .assign-ing a bound handle would leak the GislClient (incl. auth headers).
+    // `#client` is non-enumerable and inaccessible outside the class (codex high).
+    #client;
+    // The recipe's result-addressing key, threaded from a file-first `submit()`
+    // (`Recipe.submit()`) so the `RunResult` from `wait()`/`result()` is keyed
+    // (`succeeded[].key === recipeKey`). A reattached handle
+    // (`client.workflow(id)`) passes no key → null → keyless RunResult. It is
+    // ES-private (`#`) — like `#client` — NOT just kept out of `toJSON()`: the
+    // parity ReturnSerialiser enumerates a Handle's OWN ENUMERABLE properties
+    // (it does not call `toJSON()`), so a plain `readonly key` leaked into the
+    // operation-first/merge `submit()` back-compat shape ({workflowId,
+    // webhookSecret}). `#key` is non-enumerable, so that shape stays byte-identical.
+    #key;
+    constructor(workflowId, webhookSecret, client, key = null) {
+        this.workflowId = workflowId;
+        this.webhookSecret = webhookSecret;
+        this.#client = client;
+        this.#key = key;
+    }
+    /**
+     * Fetch the workflow's current status once (non-blocking) and project it to
+     * a {@link StatusSnapshot}.
+     * @throws {GislConfigError} reason `no_client` when no client is bound.
+     */
+    async status() {
+        const client = this.requireClient();
+        const status = await client.getWorkflowStatus(this.workflowId);
+        return new StatusSnapshot(this.workflowId, status.status);
+    }
+    /**
+     * Block until the workflow reaches a terminal state (SSE with poll
+     * fallback), then fetch its downloads and project to a {@link RunResult}.
+     * This is the ONLY blocking accessor on a `Handle`.
+     *
+     * @param maxWait Wall-clock deadline for the wait + downloads (string suffix
+     *   `'2h'`/`'30m'`/`'120s'` or a number of milliseconds). Defaults to 300s,
+     *   matching `Recipe.run()` / the PHP `Handle::wait()` default.
+     * @throws {GislConfigError} reason `no_client` when no client is bound.
+     * @throws {GislTimeoutError} when `maxWait` elapses before terminal.
+     */
+    async wait(maxWait = 300_000, onProgress) {
+        const client = this.requireClient();
+        const deadline = Date.now() + _parseMaxWait(maxWait);
+        let finalStatus;
+        try {
+            finalStatus = await _consumeSseToTerminal(client, {
+                workflowId: this.workflowId,
+                deadline,
+                signal: undefined,
+                onProgress,
+            });
+        }
+        catch (err) {
+            // Mirror Recipe.run(): only genuine SSE transport / clean-stream-end
+            // failures fall through to poll. Caller-deadline, abort, and API errors
+            // MUST propagate — re-issuing the same doomed request via poll would mask
+            // them.
+            if (err instanceof GislTimeoutError)
+                throw err;
+            if (err instanceof DOMException && err.name === 'AbortError')
+                throw err;
+            if (err instanceof GislApiError)
+                throw err;
+            finalStatus = await _pollToTerminal(client, {
+                workflowId: this.workflowId,
+                deadline,
+                signal: undefined,
+            });
+        }
+        if (Date.now() >= deadline) {
+            throw new GislTimeoutError(`Workflow ${this.workflowId} reached terminal status but maxWait elapsed before downloads could be fetched`);
+        }
+        const downloads = await client.getWorkflowDownloads(this.workflowId);
+        return this.project(finalStatus, downloads.downloads);
+    }
+    /**
+     * Non-blocking result accessor. Fetches the workflow status once: if the
+     * workflow is terminal, fetches its downloads and projects to a
+     * {@link RunResult}; if it is NOT terminal, throws
+     * {@link GislResultNotReadyError}. Never waits or polls — use {@link wait}
+     * to block.
+     *
+     * @throws {GislConfigError} reason `no_client` when no client is bound.
+     * @throws {GislResultNotReadyError} when the workflow is not yet terminal.
+     */
+    async result() {
+        const client = this.requireClient();
+        const status = await client.getWorkflowStatus(this.workflowId);
+        if (!TERMINAL_STATES.has(status.status)) {
+            throw new GislResultNotReadyError(this.workflowId, status.status);
+        }
+        const downloads = await client.getWorkflowDownloads(this.workflowId);
+        return this.project(status, downloads.downloads);
+    }
+    /**
+     * Project a terminal status + its per-job downloads into a {@link RunResult},
+     * choosing the producer DATA-DRIVEN off the wire (not a construction-time
+     * marker, so a fan-out reattached via `client.workflow(id)` — which carries
+     * no marker — still partitions per job):
+     *
+     *  - A `files([...])` fan-out (every job ref is `file-{i}`, see
+     *    {@link isFanoutStatus}) → {@link projectMultiJobToRunResult} with an
+     *    empty `keyByRef`, so each input's key is recovered from its `file-{i}`
+     *    ref (`"0"`, `"1"`, …). A submitted/reattached fan-out carries no
+     *    caller-supplied keys — keyed fan-out is a separate concern.
+     *  - Anything else (the single-file {@link Recipe} path) →
+     *    {@link projectDownloadsToRunResult} keyed by this handle's `#key`
+     *    (the recipe key from a file-first `submit()`, or `null` on reattach).
+     */
+    project(finalStatus, jobDownloads) {
+        const downloader = this.makeDownloader();
+        if (isFanoutStatus(finalStatus)) {
+            return projectMultiJobToRunResult(this.workflowId, finalStatus, jobDownloads, new Map(), downloader);
+        }
+        return projectDownloadsToRunResult(this.workflowId, finalStatus, jobDownloads, this.#key, downloader);
+    }
+    /**
+     * Plain-object projection. Field order (`workflowId`, then `webhookSecret`
+     * when present) and the omit-when-undefined behaviour match the PHP
+     * `toArray()` so JSON-string parity holds with the prior `Handle` shape.
+     * The bound client is NEVER serialised.
+     */
+    toJSON() {
+        return this.webhookSecret === undefined
+            ? { workflowId: this.workflowId }
+            : { workflowId: this.workflowId, webhookSecret: this.webhookSecret };
+    }
+    /**
+     * Back-compat alias for {@link toJSON} — the prior operation-first/merge
+     * `submit()` fixture asserts a plain `{ workflowId, webhookSecret }` shape.
+     */
+    toArray() {
+        return this.toJSON();
+    }
+    makeDownloader() {
+        // Download URLs from getWorkflowDownloads are pre-signed and require no SDK
+        // auth, so the downloader issues a plain unauthenticated fetch.
+        return new HttpDownloader();
+    }
+    requireClient() {
+        if (this.#client === undefined) {
+            throw new GislConfigError('This handle has no client bound, so it cannot query the workflow. ' +
+                'Use recipe.run() to execute and get a RunResult directly, or reattach via client.workflow(id).', { reason: 'no_client' });
+        }
+        return this.#client;
+    }
+}

package/dist/index.d.ts

@@ -4,20 +4,22 @@ export { parseSseStream } from './sse.js';
 export type { CreditsUsageOptions, GetSchemaOptions, GetSchemaResult, PreflightClipError, PreflightClipsResult, GislClientConfig, GislSseEvent, UploadOptions, WaitOptions, WorkflowCreatePayload, OperationDef, WorkflowSourcePayload, UploadSourcePayload, JobOutputSourcePayload, ExternalImportSourcePayload, ConnectionSourcePayload, JobInputV2Payload, JobDefinitionPayload, ExternalDestinationPayload, DeliveryPayload, DeliveryModePayload, DeliveryBundleFormatPayload, DeliverySelectionPayload, DeliverySelectionTypePayload, DeliveryOutputRefPayload, WorkflowProcessingPayload, ProcessingClassHintPayload, MultipartCheckpointState, _Sdk3HandCodedUploadedPart, _Sdk3HandCodedMultipartStatusResult, _Sdk3HandCodedPresignedPart, _Sdk3HandCodedPresignPartsResult, _Sdk3HandCodedKeepaliveResult, } from './types.js';
 export { uploadSource, jobOutputSource, externalImportSource, connectionSource, } from './types.js';
 export type { GislConfigErrorMetadata } from './errors.js';
-export { GislError, GislApiError, GislValidationError, GislBalanceExhaustedError, GislTierRestrictedError, GislFeatureTierRestrictedError, GislFeatureNotAvailableError, GislWorkflowExpiredError, GislProbePendingError, GislAuthError, GislUploadCapExceededError, GislMultipartPartError, GislMultipartPartCountError, GislMultipartSessionNotFoundError, GislMultipartSessionOwnershipError, GislMultipartSessionAuthRequiredError, GislTimeoutError, GislAbortError, GislNetworkError, GislConfigError, GislMissingCredentialsError, GislFeatureRequiresAuthError, GislUndeclaredAssetError, GislUnusedAssetError, GislPerInputOptionsNotSupportedError, GislChainCardinalityMismatchError, GislNoSuchKeyError, GislSinkError, } from './errors.js';
+export { GislError, GislApiError, GislValidationError, GislBalanceExhaustedError, GislTierRestrictedError, GislFeatureTierRestrictedError, GislFeatureNotAvailableError, GislWorkflowExpiredError, GislProbePendingError, GislAuthError, GislUploadCapExceededError, GislMultipartPartError, GislMultipartPartCountError, GislMultipartSessionNotFoundError, GislMultipartSessionOwnershipError, GislMultipartSessionAuthRequiredError, GislTimeoutError, GislAbortError, GislNetworkError, GislConfigError, GislMissingCredentialsError, GislFeatureRequiresAuthError, GislUndeclaredAssetError, GislUnusedAssetError, GislPerInputOptionsNotSupportedError, GislChainCardinalityMismatchError, GislNoSuchKeyError, GislSinkError, GislResultNotReadyError, } from './errors.js';
 export type { GislApiErrorOptions, GislUploadCapKind } from './errors.js';
 export { RunResult } from './file-first.js';
 export type { OutputFile, ItemResult, ItemFailure, Manifest, Downloader, } from './file-first.js';
 export { Recipe, fileInput } from './file-first.js';
 export type { FileInput } from './file-first.js';
+export { FilesRecipe } from './file-first.js';
 export { HttpDownloader } from './http-downloader.js';
+export { Handle, StatusSnapshot } from './handle.js';
 export { gisl, create } from './gisl.js';
 export type { GislCreateOptions, Environment, ErgonomicClient } from './gisl.js';
 export { presetDefaults, PresetDefaults, type PresetMedia, type PresetOp, type AnyPresetOptions, ImageCompressPresetOptions, type ImageCompressPresetOptionsInput, AudioCompressPresetOptions, type AudioCompressPresetOptionsInput, VideoCompressPresetOptions, type VideoCompressPresetOptionsInput, DocumentPdfCompressPresetOptions, type DocumentPdfCompressPresetOptionsInput, DocumentOfficeCompressPresetOptions, type DocumentOfficeCompressPresetOptionsInput, DocumentOdfCompressPresetOptions, type DocumentOdfCompressPresetOptionsInput, DocumentEpubCompressPresetOptions, type DocumentEpubCompressPresetOptionsInput, OptimizeFor, ImageMode, ImageFit, ImageMetadataPolicy, IccProfilePolicy, ImageFormat, VideoCodec, VideoPreset, VideoFit, AudioBitrate, AudioCodec, AudioSampleRate, PdfProfile, PdfColorspace, } from './ergonomic/presets/index.js';
 export { OperationBuilder, MapEachBuilder } from './builder.js';
 export { MergeBuilder, asset, handle, clip } from './merge.js';
 export type { Asset, ClipEntry, ClipOptions, MergeMediaKind, MergeOptions, SequenceEntry, } from './merge.js';
-export type { Artifact, ArtifactRef, Handle, JobBreakdown, OperationBreakdown, ProcessingProgressEvent, ProgressEvent, ResolvedOptions, ResolvedOptionsSources, Result, RunOptions, SubmitOptions, UploadProgressEvent, } from './builder.js';
+export type { Artifact, ArtifactRef, JobBreakdown, OperationBreakdown, ProcessingProgressEvent, ProgressEvent, ResolvedOptions, ResolvedOptionsSources, Result, RunOptions, SubmitOptions, UploadProgressEvent, } from './builder.js';
 export { PRESET_VERSION, resolveCompressOptions } from './ergonomic/preset_resolver.js';
 export type { ResolveCompressOptionsInput, ResolveCompressOptionsOutput, } from './ergonomic/preset_resolver.js';
 export type { AudioWatermarkDecodeRequest, AudioWatermarkDecodeResponse, ContactRequest, CreditsBalanceResponse, CreditsUsageResponse, CreditTransaction, ExternalImportCreatedResponse, ExternalImportRequest, LoginUserRequest, LoginUser200ResponseData, LoginUser200ResponseDataUser, WorkflowCancelResponse, WorkflowResumeResponse, WorkflowPausedDetail, WorkflowPausedDetailLinks, UploadResponse, UploadConstraintsApplied, UploadProbeResponse, UploadProbeMediaMetadata, MultipartInitiateRequestMetadataHint, WorkflowCreateResponse, WorkflowStatusResponse, WorkflowDownloadResponse, MetadataResponse, MetadataResponseDimensions, MetadataResponseExif, MetadataResponseExifGps, OperationsSchemaResponse, OperationSchemaDefinition, MimeGroupSchema, OptionSchema, PerValueAvailabilityEntry, PerRoleCardinalityEntry, RetryResponse, JobDownload, OperationDownload, WebhookPayload, WebhookOperationContext, JobResponse, OperationResponse, OperationResult, OperationResultMetrics, ExternalDestination, Delivery, DeliveryPlan, DeliveryPlanOutput, WorkflowProcessing, ProcessingPlan, ProcessingPlanJob, WorkflowEdge, WorkflowWarning, JobInputV2, WorkflowSource, UploadSource, JobOutputSource, ConnectionSource, ExternalImportToken, BalanceExhaustedResponse, BalanceExhaustedResponseAllOfLinks, TierRestrictionResponse, FeatureTierRestrictedResponse, FeatureNotAvailableResponse, FeatureViolation, WorkflowExpiredResponse, ProbePendingResponse, AuthErrorResponse, } from '@giveitsmaller/contracts/openapi';

package/dist/index.js

@@ -19,15 +19,31 @@ GislUndeclaredAssetError, GislUnusedAssetError, GislPerInputOptionsNotSupportedE
 // here so the future chain-method PR is a pure addition).
 GislChainCardinalityMismatchError, 
 // FF1 / 3BIxEnfR — file-first result sink errors.
-GislNoSuchKeyError, GislSinkError, } from './errors.js';
+GislNoSuchKeyError, GislSinkError, 
+// FF5a / Ao8RPVxD — thrown by the file-first Handle.result() when the
+// workflow is not yet terminal (the non-blocking accessor).
+GislResultNotReadyError, } from './errors.js';
 // File-first result surface (FF1 / 3BIxEnfR) — coexists with the
 // operation-first `Result`/`Artifact` until FF6 removes the old layer.
 export { RunResult } from './file-first.js';
 // File-first builder (FF2a / MfV0PDok) — `client.file(path).op()...` lowering.
 export { Recipe, fileInput } from './file-first.js';
+// File-first homogeneous fan-out (FF3a / u0hBt6fl) — `client.files([...]).op()...`
+// applies one recipe to many inputs in one workflow; run() partitions per input.
+// `projectMultiJobToRunResult` is intentionally NOT re-exported — it is the
+// @internal per-job producer consumed only by FilesRecipe.run (codex).
+export { FilesRecipe } from './file-first.js';
 // File-first execution (FF2b / MfV0PDok) — Node streaming downloader bound by
 // `Recipe.run()` to write pre-signed output URLs to disk.
 export { HttpDownloader } from './http-downloader.js';
+// `projectDownloadsToRunResult` is intentionally NOT re-exported here — it is an
+// @internal helper shared between `file-first.ts` (Recipe.run) and `handle.ts`
+// (Handle.wait/result) via direct intra-package import, not public API (codex).
+// File-first Handle + StatusSnapshot (FF5a / Ao8RPVxD) — method-bearing,
+// client-bound value objects. `Handle` is the return of `submit()` (no client)
+// AND `client.workflow(id)` (client-bound, reattach). Exported as VALUES (the
+// prior `export type { Handle }` is replaced) because `Handle` is now a class.
+export { Handle, StatusSnapshot } from './handle.js';
 // Ergonomic-layer entrypoint (T1 / wVU4xHx3) — `gisl.create()` factory +
 // credential-chain types. `gisl.anonymous()` (public export) lands once
 // the anonymous-capable operation allowlist is non-empty (plan §12).

package/dist/merge.d.ts

@@ -26,7 +26,8 @@
  * assets both fail fast so the caller saves bandwidth on typo'd composes.
  */
 import type { GislClient } from './client.js';
-import { type Handle, type Result, type RunOptions, type SubmitOptions } from './builder.js';
+import { type Result, type RunOptions, type SubmitOptions } from './builder.js';
+import { Handle } from './handle.js';
 /**
  * A declared merge asset. `path` carries a string or Blob (deduped by
  * normalised source key); `handle` wraps an already-uploaded file (deduped

package/dist/merge.js

@@ -25,9 +25,10 @@
  * Local validation runs BEFORE any upload — undeclared refs and unused
  * assets both fail fast so the caller saves bandwidth on typo'd composes.
  */
-import { uploadSource } from './types.js';
+import { uploadSource, jobOutputSource } from './types.js';
 import { GislConfigError, GislPerInputOptionsNotSupportedError, GislTimeoutError, GislUndeclaredAssetError, GislUnusedAssetError, } from './errors.js';
 import { _checkAborted, _consumeSseToTerminal, _parseMaxWait, _pollToTerminal, _projectResult, } from './builder.js';
+import { Handle } from './handle.js';
 /**
  * Construct a path-asset. Bare-string arguments to `merge(...)` are
  * implicitly wrapped via this helper.
@@ -117,7 +118,14 @@ export class MergeBuilder {
             throw new GislTimeoutError(`Merge workflow ${created.workflowId} reached terminal status but maxWait elapsed before downloads could be fetched`);
         }
         const downloads = await this.client.getWorkflowDownloads(created.workflowId);
-        return _projectResult(finalStatus, downloads.downloads, this.opOptionsForResolved());
+        // p0SuJEeK — project ONLY the merge job's output. getWorkflowDownloads
+        // returns a download group per terminal job, which now INCLUDES the
+        // `passthrough` source jobs (their output is the unchanged upload). Those
+        // are plumbing, not the merge deliverable — surfacing them as artifacts
+        // would pollute the Result with the raw inputs. The merge job's ref is
+        // 'merge' (see buildPayload); the source jobs are 'src_N'.
+        const mergeDownloads = downloads.downloads.filter((d) => d.ref === 'merge');
+        return _projectResult(finalStatus, mergeDownloads, this.opOptionsForResolved());
     }
     async submit(options) {
         const plan = this.planSequence();
@@ -125,11 +133,9 @@ export class MergeBuilder {
         const payload = this.buildPayload(plan, uploadedByAssetId);
         payload.callback_url = options.webhook;
         const created = await this.client.createWorkflow(payload);
-        const handle = {
-            workflowId: created.workflowId,
-            ...(created.webhookSecret != null ? { webhookSecret: created.webhookSecret } : {}),
-        };
-        return handle;
+        // No client passed → the returned Handle's status()/wait()/result()
+        // throw `no_client`; the merge submit reconciles via webhook.
+        return new Handle(created.workflowId, created.webhookSecret != null ? created.webhookSecret : undefined);
     }
     // ---------------------------------------------------------------------------
     /**
@@ -247,12 +253,38 @@ export class MergeBuilder {
         return uploaded;
     }
     buildPayload(plan, uploadedByAssetId) {
-        const inputs = plan.positions.map((pos) => {
+        // p0SuJEeK — the API rejects upload-direct multi-input
+        // (`MultiInputSource` excludes the `upload` leaf: "use type=job_output").
+        // So each uploaded asset is wrapped in its OWN single-input `passthrough`
+        // source job, and the merge job references those via `job_output` — the
+        // shape the v2.35.0 `v2_merge_two_uploads` example prescribes. One source
+        // job per UNIQUE asset (in first-seen position order); a repeated asset
+        // re-uses its src job. `passthrough` is a lossless inert op (it does NOT
+        // get the implicit compress an empty `operations: []` job would).
+        const srcIdByAsset = new Map();
+        const sourceJobs = [];
+        for (const pos of plan.positions) {
+            if (srcIdByAsset.has(pos.assetId))
+                continue;
             const fileId = uploadedByAssetId.get(pos.assetId);
             if (fileId === undefined) {
                 // Defensive — planSequence should have rejected this.
                 throw new Error(`Asset '${pos.assetId}' was never uploaded — internal builder bug`);
             }
+            const srcId = `src_${sourceJobs.length}`;
+            srcIdByAsset.set(pos.assetId, srcId);
+            sourceJobs.push({
+                id: srcId,
+                source: uploadSource(fileId),
+                operations: [{ type: 'passthrough' }],
+            });
+        }
+        const inputs = plan.positions.map((pos) => {
+            // Defensive — srcIdByAsset was populated for every position's asset above.
+            const srcId = srcIdByAsset.get(pos.assetId);
+            if (srcId === undefined) {
+                throw new Error(`Asset '${pos.assetId}' has no source job — internal builder bug`);
+            }
             // Codex r1 HIGH 502c6bf232c2 — per_input_options goes on EACH
             // JobInputV2Payload (per-input entry), NOT on operations[0].options.
             // Skip emission for image merges (planSequence already rejects opts
@@ -261,7 +293,7 @@ export class MergeBuilder {
             const wireOpts = plan.mediaKind === 'image'
                 ? {}
                 : wirePerInputOptions(pos.options, plan.mediaKind);
-            const input = { source: uploadSource(fileId) };
+            const input = { source: jobOutputSource(srcId) };
             if (Object.keys(wireOpts).length > 0) {
                 input.per_input_options = wireOpts;
             }
@@ -269,12 +301,12 @@ export class MergeBuilder {
         });
         // Merge-level options (excluding the SDK-side mediaKind/allowUnusedAssets).
         const mergeOpts = wireMergeOptions(this.opOptions, plan.mediaKind);
-        const job = {
+        const mergeJob = {
             id: 'merge',
             inputs,
             operations: [{ type: 'merge', options: mergeOpts }],
         };
-        return { jobs: [job] };
+        return { jobs: [...sourceJobs, mergeJob] };
     }
     opOptionsForResolved() {
         // Strip the SDK-only fields before exposing on resolvedOptions.applied.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@giveitsmaller/sdk",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Node.js SDK for the GISL (Give It Smaller) file compression and processing API",
   "license": "MIT",
   "type": "module",