@giveitsmaller/sdk 0.8.0 → 0.10.0

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

@@ -20,12 +20,6 @@ export declare const ImageFormat: {
     readonly Avif: "avif";
 };
 export type ImageFormat = typeof ImageFormat[keyof typeof ImageFormat];
-export declare const ImageFit: {
-    readonly Max: "max";
-    readonly Crop: "crop";
-    readonly Scale: "scale";
-};
-export type ImageFit = typeof ImageFit[keyof typeof ImageFit];
 export declare const ImageMetadataPolicy: {
     readonly All: "all";
     readonly None: "none";
@@ -122,11 +116,6 @@ export declare const ERGONOMIC_ENUMS: {
         readonly Webp: "webp";
         readonly Avif: "avif";
     };
-    readonly ImageFit: {
-        readonly Max: "max";
-        readonly Crop: "crop";
-        readonly Scale: "scale";
-    };
     readonly ImageMetadataPolicy: {
         readonly All: "all";
         readonly None: "none";

package/dist/generated/sdk_spec/enums.js

@@ -23,12 +23,6 @@ export const ImageFormat = {
     Webp: "webp",
     Avif: "avif",
 };
-// Image resize mode. Only applies when width or height is set (depends_on width/height in compress.yaml).
-export const ImageFit = {
-    Max: "max",
-    Crop: "crop",
-    Scale: "scale",
-};
 // Image metadata handling. Counter-intuitive wire naming:
 //   All       = strip everything (smallest file)
 //   None      = keep all EXIF/IPTC/XMP
@@ -113,7 +107,6 @@ export const ERGONOMIC_ENUMS = {
     OptimizeFor,
     ImageMode,
     ImageFormat,
-    ImageFit,
     ImageMetadataPolicy,
     IccProfilePolicy,
     VideoCodec,

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" | "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 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" | "validation_error" | "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" | "upload_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,19 @@ export const ERROR_CODES = Object.freeze({
             "details": "array",
         }),
     }),
+    "validation_error": Object.freeze({
+        code: "validation_error",
+        category: "validation",
+        source: "error_type",
+        status: "wired",
+        httpStatus: 422,
+        retryable: false,
+        sdkClass: "GislValidationError",
+        description: "422 — `error_type` discriminator on `ValidationErrorEnvelope` (ADR-0018/0019); distinct from `validation_failed` (the `error` code), same `GislValidationError`. Carries `details[]`.",
+        metadataSchema: Object.freeze({
+            "details": "array",
+        }),
+    }),
     "cyclic_workflow_edges": Object.freeze({
         code: "cyclic_workflow_edges",
         category: "validation",
@@ -277,6 +290,17 @@ export const ERROR_CODES = Object.freeze({
             "uploadId": "string",
         }),
     }),
+    "upload_not_found": Object.freeze({
+        code: "upload_not_found",
+        category: "api",
+        source: "ErrorEnvelope.error",
+        status: "wired",
+        httpStatus: 404,
+        retryable: false,
+        sdkClass: "GislApiError",
+        description: "404 on POST /api/workflows — a referenced upload was not found, OR exists but is owned by a different identity (deliberate BOLA/IDOR existence-mask: reported as not-found, never 403, so the response does not reveal another user's upload exists). message_key upload.not_found. Wire token UPLOAD_NOT_FOUND keyed on the `error` field. Per ADR-0016 amendment.",
+        metadataSchema: Object.freeze({}),
+    }),
     "workflow_expired": Object.freeze({
         code: "workflow_expired",
         category: "api",
@@ -477,6 +501,7 @@ export const ERROR_CATEGORIES = Object.freeze({
         "feature_tier_restricted",
         "tier_restriction",
         "multipart_session_not_found",
+        "upload_not_found",
         "workflow_expired",
         "balance_exhausted",
         "feature_not_available",
@@ -504,6 +529,7 @@ export const ERROR_CATEGORIES = Object.freeze({
         "multipart_part_invalid",
         "multipart_part_count_exceeded",
         "validation_failed",
+        "validation_error",
         "cyclic_workflow_edges",
         "workflow_edge_references_unknown_job",
         "reserved_job_id_pattern",

package/dist/generated/sdk_spec/presets.js

@@ -8,7 +8,6 @@ export const PRESETS = Object.freeze({
             "quality": 65,
             "metadata": "All",
             "iccProfile": "Strip",
-            "autoOrient": true,
             "progressive": true,
             "outputFormat": "Smallest",
         }),
@@ -17,7 +16,6 @@ export const PRESETS = Object.freeze({
             "quality": 80,
             "metadata": "Sensitive",
             "iccProfile": "Preserve",
-            "autoOrient": true,
             "progressive": true,
             "outputFormat": "Auto",
         }),
@@ -25,7 +23,6 @@ export const PRESETS = Object.freeze({
             "mode": "Lossless",
             "metadata": "None",
             "iccProfile": "Preserve",
-            "autoOrient": true,
             "progressive": true,
             "outputFormat": "Original",
         }),

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

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

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.2.0";
+export const SDK_SPEC_VERSION = "1.5.0";
 export const PRESET_VERSION = "1.0";
-export const PRESET_CONFIG_HASH = "sha256:35aeb0b6b86edd9814ace5b75cfeef8a7b1432ecb8e4d5ee8b38d9187a0b45eb";
+export const PRESET_CONFIG_HASH = "sha256:dc48f4d31f4037cc07fb0686519122c03a55b03a41f05fbfc2af54e54950a0d2";

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;

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,273 @@
+/**
+ * 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 { GislConfigError, GislNetworkError, GislResultNotReadyError, GislTimeoutError, SseEndedWithoutTerminal, } from './errors.js';
+import { _consumeSseToTerminal, _pollToTerminal, _parseMaxWait, } from './builder.js';
+import { projectDownloadsToRunResult, projectMultiJobToRunResult, isFanoutStatus, isMergeStatus, isArchiveStatus, } from './file-first.js';
+import { LazyHttpDownloader } from './lazy-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) {
+            // TDqmkWpX: mirror Recipe.run() — poll-fallback ONLY on a clean SSE
+            // stream-end (SseEndedWithoutTerminal) or a typed transport error
+            // (GislNetworkError). Everything else (timeout, abort, API, an onProgress
+            // callback throw, anything unexpected) MUST propagate — re-issuing the same
+            // doomed request via poll would mask the real failure.
+            if (!(err instanceof SseEndedWithoutTerminal || err instanceof GislNetworkError)) {
+                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);
+        // TDqmkWpX: re-check AFTER the downloads fetch so a slow getWorkflowDownloads
+        // cannot return a success past the advertised maxWait.
+        if (Date.now() >= deadline) {
+            throw new GislTimeoutError(`Workflow ${this.workflowId} downloads fetch completed after maxWait elapsed`);
+        }
+        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);
+        }
+        // A fluent `files([...]).merge(...)` combine — project ONLY the merged
+        // output, filtering the `src_*` passthrough plumbing (which re-exposes the
+        // raw inputs). Matches MergedRecipe.run()'s `ref === 'merge'` filter so a
+        // submitted/reattached merge handle never surfaces the input artifacts
+        // alongside the combined output (codex c1).
+        if (isMergeStatus(finalStatus)) {
+            const mergeDownloads = jobDownloads.filter((d) => d.ref === 'merge');
+            return projectDownloadsToRunResult(this.workflowId, finalStatus, mergeDownloads, null, downloader);
+        }
+        // A fluent `files([...]).archive(...)` bundle — project ONLY the archive
+        // output, filtering the `src_*` passthrough plumbing (mirror of the merge
+        // branch for archive).
+        if (isArchiveStatus(finalStatus)) {
+            const archiveDownloads = jobDownloads.filter((d) => d.ref === 'archive');
+            return projectDownloadsToRunResult(this.workflowId, finalStatus, archiveDownloads, null, 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. Lazy so the
+        // node:fs-importing HttpDownloader stays out of the browser static graph.
+        return new LazyHttpDownloader();
+    }
+    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.browser.d.ts

@@ -0,0 +1 @@
+export * from './index.core.js';