@giveitsmaller/sdk 0.7.0 → 0.9.0

package/dist/generated/sdk_spec/errors.d.ts

@@ -1,4 +1,4 @@
-export type ErrorCode = "missing_credentials" | "feature_requires_auth" | "undeclared_asset" | "unused_asset" | "per_input_options_not_supported" | "chain_cardinality_mismatch" | "multipart_part_invalid" | "multipart_part_count_exceeded" | "timeout" | "aborted" | "validation_failed" | "auth_failed" | "feature_tier_restricted" | "tier_restriction" | "multipart_session_ownership" | "multipart_session_auth_required" | "multipart_session_not_found" | "workflow_expired" | "balance_exhausted" | "feature_not_available" | "upload_size_exceeds_tier" | "upload_duration_exceeds_tier" | "probe_pending" | "requires_reencode" | "invalid_options" | "invalid_combination" | "missing_dependency" | "unsupported_value" | "type_mismatch" | "upload_failed" | "workflow_failed";
+export type ErrorCode = "missing_credentials" | "feature_requires_auth" | "undeclared_asset" | "unused_asset" | "per_input_options_not_supported" | "chain_cardinality_mismatch" | "multipart_part_invalid" | "multipart_part_count_exceeded" | "timeout" | "aborted" | "validation_failed" | "cyclic_workflow_edges" | "workflow_edge_references_unknown_job" | "reserved_job_id_pattern" | "cyclic_job_output_source_graph" | "auth_failed" | "feature_tier_restricted" | "tier_restriction" | "multipart_session_ownership" | "multipart_session_auth_required" | "multipart_session_not_found" | "workflow_expired" | "balance_exhausted" | "feature_not_available" | "upload_size_exceeds_tier" | "upload_duration_exceeds_tier" | "probe_pending" | "requires_reencode" | "invalid_options" | "invalid_combination" | "missing_dependency" | "unsupported_value" | "type_mismatch" | "upload_failed" | "workflow_failed";
 export type ErrorCategory = 'api' | 'config' | 'network' | 'auth' | 'validation' | 'chain';
 export type ErrorStatus = 'wired' | 'planned';
 export interface ErrorEntry {

package/dist/generated/sdk_spec/errors.js

@@ -150,6 +150,52 @@ export const ERROR_CODES = Object.freeze({
             "details": "array",
         }),
     }),
+    "cyclic_workflow_edges": Object.freeze({
+        code: "cyclic_workflow_edges",
+        category: "validation",
+        source: "ErrorEnvelope.error",
+        status: "wired",
+        httpStatus: 422,
+        retryable: false,
+        sdkClass: "GislValidationError",
+        description: "422 — cycle/self-edge in the explicit `workflow_edges` DAG. Wire `CYCLIC_WORKFLOW_EDGES` (g8PPkbNu); ValidationErrorEnvelope shape, `details[0].field`=`workflow_edges`.",
+        metadataSchema: Object.freeze({
+            "details": "array",
+        }),
+    }),
+    "workflow_edge_references_unknown_job": Object.freeze({
+        code: "workflow_edge_references_unknown_job",
+        category: "validation",
+        source: "ErrorEnvelope.error",
+        status: "wired",
+        httpStatus: 400,
+        retryable: false,
+        sdkClass: "GislValidationError",
+        description: "400 — a `workflow_edges` entry, job-level `source`, or `inputs[].source` references a job not in the request. Wire `WORKFLOW_EDGE_REFERENCES_UNKNOWN_JOB` (g8PPkbNu).",
+        metadataSchema: Object.freeze({}),
+    }),
+    "reserved_job_id_pattern": Object.freeze({
+        code: "reserved_job_id_pattern",
+        category: "validation",
+        source: "ErrorEnvelope.error",
+        status: "wired",
+        httpStatus: 400,
+        retryable: false,
+        sdkClass: "GislValidationError",
+        description: "400 — user job `id` matches the reserved `^job_\\d+$` pattern as the SOLE failure. Wire `RESERVED_JOB_ID_PATTERN` (g8PPkbNu); mixed violations keep generic `BAD_REQUEST`.",
+        metadataSchema: Object.freeze({}),
+    }),
+    "cyclic_job_output_source_graph": Object.freeze({
+        code: "cyclic_job_output_source_graph",
+        category: "validation",
+        source: "ErrorEnvelope.error",
+        status: "wired",
+        httpStatus: 400,
+        retryable: false,
+        sdkClass: "GislValidationError",
+        description: "400 — an implicit cycle in the `job_output` source graph, caught during effective-input-MIME resolution on POST /api/workflows. Wire `CYCLIC_JOB_OUTPUT_SOURCE_GRAPH` (g8PPkbNu).",
+        metadataSchema: Object.freeze({}),
+    }),
     "auth_failed": Object.freeze({
         code: "auth_failed",
         category: "auth",
@@ -458,6 +504,10 @@ export const ERROR_CATEGORIES = Object.freeze({
         "multipart_part_invalid",
         "multipart_part_count_exceeded",
         "validation_failed",
+        "cyclic_workflow_edges",
+        "workflow_edge_references_unknown_job",
+        "reserved_job_id_pattern",
+        "cyclic_job_output_source_graph",
         "invalid_options",
         "invalid_combination",
         "missing_dependency",

package/dist/generated/sdk_spec/version.d.ts

@@ -1,3 +1,3 @@
-export declare const SDK_SPEC_VERSION: "1.1.0";
+export declare const SDK_SPEC_VERSION: "1.2.0";
 export declare const PRESET_VERSION: "1.0";
 export declare const PRESET_CONFIG_HASH: "sha256:35aeb0b6b86edd9814ace5b75cfeef8a7b1432ecb8e4d5ee8b38d9187a0b45eb";

package/dist/generated/sdk_spec/version.js

@@ -1,6 +1,6 @@
 // CODE GENERATED — DO NOT EDIT.
 // Source: compression_contracts/sdk-spec/ (see sdk-spec/README.md).
 // Regenerate with: scripts/generate.py.
-export const SDK_SPEC_VERSION = "1.1.0";
+export const SDK_SPEC_VERSION = "1.2.0";
 export const PRESET_VERSION = "1.0";
 export const PRESET_CONFIG_HASH = "sha256:35aeb0b6b86edd9814ace5b75cfeef8a7b1432ecb8e4d5ee8b38d9187a0b45eb";

package/dist/gisl.d.ts

@@ -23,6 +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, 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
@@ -67,6 +69,35 @@ export declare function create(opts?: GislCreateOptions): Promise<ErgonomicClien
  * ergonomic factory's narrower string-only typing).
  */
 export type ErgonomicClient = GislClient & {
+    /**
+     * File-first entry point (FF2a). Returns an immutable {@link Recipe} you
+     * call operations on (`.compress()` / `.convert()` / `.thumbnail()` /
+     * `.textWatermark()`), chaining sequentially. A bare string is a filesystem
+     * path; pass a {@link FileInput} (e.g. `fileInput.uploadId(...)`) to reuse a
+     * pre-uploaded file. `key` is RESULT-addressing only — never input wiring.
+     * 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;

package/dist/gisl.js

@@ -22,6 +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, FilesRecipe, fileInput } from './file-first.js';
+import { Handle } from './handle.js';
 // ---------------------------------------------------------------------------
 // Anonymous-capable operation allowlist (internal)
 // ---------------------------------------------------------------------------
@@ -71,6 +73,51 @@ export async function create(opts = {}) {
 function wrapErgonomic(client, presetDefaults, scopedPresetDefaults) {
     return new Proxy(client, {
         get(target, prop, receiver) {
+            if (prop === 'file') {
+                // File-first entry point — the subject of the file-first surface.
+                // A bare string is a filesystem path, a Blob/File an in-memory input;
+                // pass a `FileInput` (e.g. `fileInput.uploadId(...)`) to reuse a
+                // pre-uploaded file. `key` is RESULT-addressing only. The Proxy's
+                // closure forwards the same preset-defaults references the op builders
+                // get, so a file-first `compress()` resolves presets identically.
+                return (input, key) => {
+                    const resolved = typeof input === 'string'
+                        ? fileInput.path(input)
+                        : input instanceof Blob
+                            ? fileInput.blob(input)
+                            : input;
+                    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/http-downloader.d.ts

@@ -0,0 +1,9 @@
+import type { Downloader } from './file-first.js';
+/**
+ * Streams a (typically pre-signed) URL to a local path without buffering the
+ * whole body in memory. Pre-signed download URLs require no SDK auth, so this
+ * issues a plain unauthenticated `fetch`.
+ */
+export declare class HttpDownloader implements Downloader {
+    downloadTo(url: string, destPath: string): Promise<void>;
+}

package/dist/http-downloader.js

@@ -0,0 +1,55 @@
+/**
+ * Node-only streaming {@link Downloader} implementation.
+ *
+ * Lives in its own module so the framework-free `file-first.ts` stays
+ * Node-import-free; the Node `fs`/`stream` imports are isolated here.
+ */
+import { createWriteStream } from 'node:fs';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { GislNetworkError, GislSinkError } from './errors.js';
+/**
+ * Streams a (typically pre-signed) URL to a local path without buffering the
+ * whole body in memory. Pre-signed download URLs require no SDK auth, so this
+ * issues a plain unauthenticated `fetch`.
+ */
+export class HttpDownloader {
+    async downloadTo(url, destPath) {
+        // Source-read failures surface as GislNetworkError to match the PHP
+        // StreamingDownloader (both raise GislNetworkError when the output URL
+        // cannot be fetched); a dest-write failure is GislSinkError(write_failed)
+        // on the RunResult sink side. Parity-critical: the FF1 sink contract tells
+        // callers to narrow with instanceof, so the source-read error type must
+        // match across languages.
+        let res;
+        try {
+            res = await fetch(url);
+        }
+        catch (cause) {
+            // A rejected fetch (DNS, TCP, TLS, mid-flight disconnect) must surface as
+            // GislNetworkError too — not the raw TypeError — so callers can narrow
+            // every download-source failure with `instanceof GislNetworkError`
+            // (codex review medium).
+            throw new GislNetworkError(`Failed to fetch download source: ${cause instanceof Error ? cause.message : String(cause)}`);
+        }
+        if (!res.ok) {
+            throw new GislNetworkError(`Download failed with status ${res.status}`);
+        }
+        if (res.body === null) {
+            throw new GislNetworkError('Download response had no body');
+        }
+        // `fetch`'s WHATWG ReadableStream and Node's `stream/web` ReadableStream
+        // are structurally the same at runtime but typed in two different lib
+        // declarations; the cast bridges them for `Readable.fromWeb`.
+        try {
+            await pipeline(Readable.fromWeb(res.body), createWriteStream(destPath));
+        }
+        catch {
+            // Destination-write failures (unwritable dir, disk full, …) surface as
+            // GislSinkError(write_failed) to match the PHP StreamingDownloader — a
+            // raw Node ENOENT would otherwise leak through the parity-critical sink
+            // contract. Source-read failures are handled above as GislNetworkError.
+            throw new GislSinkError(`Failed to stream download to destination: ${destPath}`, { reason: 'write_failed' });
+        }
+    }
+}