@giveitsmaller/sdk 0.7.0 → 0.8.0

package/dist/_audit.js

@@ -121,4 +121,15 @@ export function _runAudit() {
     accept();
     accept();
     accept();
+    // FF1 / 3BIxEnfR — file-first result surface + sink errors.
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
 }

package/dist/client.js

@@ -399,10 +399,19 @@ export class GislClient {
                 locale: json.locale,
                 messageParams: json.message_params,
             };
+            // Human-readable text comes from `message` (the I26 localised field).
+            // `error` is the stable, never-localised SCREAMING_SNAKE machine code —
+            // NOT display text. Surfacing `error` as the thrown error's `.message`
+            // regressed consumers that render the human string (x9Lbf6uy). Fall back
+            // to `error` when `message` is absent (deployed contract guarantees
+            // `message` on conforming error envelopes). Machine dispatch keys off
+            // `error_type` (below), unchanged.
+            const status = response.status;
+            const errorMessage = json.message ?? json.error ?? 'Unknown error';
             // Validation-details branch first — preserve existing shape so callers
             // matching on `instanceof GislValidationError` keep working.
             if (isValidationDetails(json.details)) {
-                throw new GislValidationError(response.status, json.error ?? 'Validation error', json.details, path, i18n);
+                throw new GislValidationError(response.status, errorMessage, json.details, path, i18n);
             }
             // Dispatch by (status, error_type) onto the structured envelope shapes
             // emitted by the v2 contracts. Each branch builds the typed payload via
@@ -416,8 +425,6 @@ export class GislClient {
             // fall through to the base `GislApiError` rather than handing the
             // caller silently-corrupted typed metadata.
             const errorType = json.error_type;
-            const status = response.status;
-            const errorMessage = json.error ?? 'Unknown error';
             // Build the typed payload via FromJSON, then validate that all
             // required typed fields are well-formed. FromJSON does not throw on
             // missing required fields — for example `workflow_expired` without
@@ -1740,7 +1747,10 @@ export class GislClient {
             let errorMessage = 'Unknown error';
             try {
                 const errJson = (await response.json());
-                if (errJson.error)
+                // Prefer the human `message`; `error` is the machine code (x9Lbf6uy).
+                if (errJson.message)
+                    errorMessage = errJson.message;
+                else if (errJson.error)
                     errorMessage = errJson.error;
             }
             catch {

package/dist/errors.d.ts

@@ -300,6 +300,18 @@ export declare class GislChainCardinalityMismatchError extends GislConfigError {
 export declare class GislTimeoutError extends GislError {
     constructor(message: string);
 }
+/**
+ * Transport-level failure: the underlying `fetch` (or other transport) could
+ * not produce a usable response — DNS, TCP, TLS, a mid-stream disconnect, or a
+ * non-ok status / empty body when fetching a result download. Mirrors the PHP
+ * `Gisl\Sdk\Errors\GislNetworkError`. Subclasses `GislError` (not
+ * `GislApiError`) because it carries no contract error envelope. The concrete
+ * file-first {@link Downloader} raises this when the output URL cannot be read
+ * (a destination-WRITE failure is `GislSinkError` reason `write_failed`).
+ */
+export declare class GislNetworkError extends GislError {
+    constructor(message: string);
+}
 export declare class GislAbortError extends GislError {
     constructor(message: string);
 }
@@ -326,3 +338,40 @@ export declare class GislMultipartPartCountError extends GislError {
     readonly maxParts: number;
     constructor(message: string, requiredParts: number, maxParts: number);
 }
+/**
+ * Thrown by the file-first `RunResult.byKey()` (FF1) when no result entry
+ * matches the requested key. A keyless run (no `key:` supplied to `file()`)
+ * is addressable positionally only — `byKey()` always throws.
+ *
+ * Mirrors the PHP `Gisl\Sdk\Errors\GislNoSuchKeyError`.
+ */
+export declare class GislNoSuchKeyError extends GislError {
+    constructor(message: string);
+}
+/** Machine-readable cause carried by {@link GislSinkError}. */
+export type GislSinkErrorReason = 'not_single_output' | 'downloader_unavailable' | 'partial_failure' | 'duplicate_filename' | 'invalid_directory' | 'write_failed';
+/**
+ * Thrown by the file-first `RunResult` sinks (`toFile()` / `downloadTo()`,
+ * FF1) when they cannot deliver. The machine-readable `reason` discriminates
+ * the three cases, mirroring the `reason`-bag convention on
+ * {@link GislConfigError}:
+ *
+ *  - `not_single_output`      — `toFile()` requires exactly one output but the
+ *                               run produced zero or more than one.
+ *  - `downloader_unavailable` — the `RunResult` has no downloader bound (e.g. a
+ *                               browser / no-I/O context).
+ *  - `partial_failure`        — `downloadTo({ failOnPartial: true })` and the
+ *                               run had at least one failed input.
+ *  - `duplicate_filename`     — two outputs share a destination filename in one
+ *                               `downloadTo(dir)`, which would silently overwrite.
+ *  - `write_failed`           — a concrete {@link Downloader} could not open or
+ *                               stream to the destination path.
+ *
+ * Mirrors the PHP `Gisl\Sdk\Errors\GislSinkError`.
+ */
+export declare class GislSinkError extends GislError {
+    readonly reason: GislSinkErrorReason;
+    constructor(message: string, options: {
+        readonly reason: GislSinkErrorReason;
+    });
+}

package/dist/errors.js

@@ -320,6 +320,21 @@ export class GislTimeoutError extends GislError {
         this.name = 'GislTimeoutError';
     }
 }
+/**
+ * Transport-level failure: the underlying `fetch` (or other transport) could
+ * not produce a usable response — DNS, TCP, TLS, a mid-stream disconnect, or a
+ * non-ok status / empty body when fetching a result download. Mirrors the PHP
+ * `Gisl\Sdk\Errors\GislNetworkError`. Subclasses `GislError` (not
+ * `GislApiError`) because it carries no contract error envelope. The concrete
+ * file-first {@link Downloader} raises this when the output URL cannot be read
+ * (a destination-WRITE failure is `GislSinkError` reason `write_failed`).
+ */
+export class GislNetworkError extends GislError {
+    constructor(message) {
+        super(message);
+        this.name = 'GislNetworkError';
+    }
+}
 export class GislAbortError extends GislError {
     constructor(message) {
         super(message);
@@ -359,3 +374,43 @@ export class GislMultipartPartCountError extends GislError {
         this.maxParts = maxParts;
     }
 }
+/**
+ * Thrown by the file-first `RunResult.byKey()` (FF1) when no result entry
+ * matches the requested key. A keyless run (no `key:` supplied to `file()`)
+ * is addressable positionally only — `byKey()` always throws.
+ *
+ * Mirrors the PHP `Gisl\Sdk\Errors\GislNoSuchKeyError`.
+ */
+export class GislNoSuchKeyError extends GislError {
+    constructor(message) {
+        super(message);
+        this.name = 'GislNoSuchKeyError';
+    }
+}
+/**
+ * Thrown by the file-first `RunResult` sinks (`toFile()` / `downloadTo()`,
+ * FF1) when they cannot deliver. The machine-readable `reason` discriminates
+ * the three cases, mirroring the `reason`-bag convention on
+ * {@link GislConfigError}:
+ *
+ *  - `not_single_output`      — `toFile()` requires exactly one output but the
+ *                               run produced zero or more than one.
+ *  - `downloader_unavailable` — the `RunResult` has no downloader bound (e.g. a
+ *                               browser / no-I/O context).
+ *  - `partial_failure`        — `downloadTo({ failOnPartial: true })` and the
+ *                               run had at least one failed input.
+ *  - `duplicate_filename`     — two outputs share a destination filename in one
+ *                               `downloadTo(dir)`, which would silently overwrite.
+ *  - `write_failed`           — a concrete {@link Downloader} could not open or
+ *                               stream to the destination path.
+ *
+ * Mirrors the PHP `Gisl\Sdk\Errors\GislSinkError`.
+ */
+export class GislSinkError extends GislError {
+    reason;
+    constructor(message, options) {
+        super(message);
+        this.name = 'GislSinkError';
+        this.reason = options.reason;
+    }
+}

package/dist/file-first.d.ts

@@ -0,0 +1,284 @@
+/**
+ * File-first result surface — the value the file-first layer's `run()` /
+ * `Handle.wait()` / `Handle.result()` return (producers land in FF2b/FF5).
+ *
+ * Coexists with the operation-first `Result`/`Artifact` (in `builder.ts`)
+ * until the operation-first layer is removed (FF6). The file-first shape is
+ * flatter and adds an always-present per-input partition (`succeeded` /
+ * `failed`) so one bad input in a multi-input run doesn't sink the rest.
+ *
+ * Mirrors `packages/php/src/FileFirst/*`.
+ */
+import { type ProgressEvent } from './builder.js';
+import type { GislClient } from './client.js';
+import { OptimizeFor } from './generated/sdk_spec/enums.js';
+import type { PresetDefaults } from './ergonomic/presets/index.js';
+import type { WorkflowCreatePayload } from './types.js';
+/**
+ * Streams a single output URL to a local path. The seam between the
+ * file-first {@link RunResult} sinks and the SDK's HTTP/auth layer.
+ *
+ * FF1 defines ONLY this type — the concrete implementation (fetch +
+ * filesystem streamer) is wired by the producer tickets (`run()`/`submit()`,
+ * FF2b/FF5), which construct a `RunResult` with a real downloader bound to
+ * the client's auth context. Unit tests inject a small stub. A `RunResult`
+ * built WITHOUT a downloader (e.g. in a browser, or any no-I/O context)
+ * throws {@link GislSinkError} from its sinks rather than reaching for a
+ * global client.
+ *
+ * Mirrors the PHP `Downloader` interface.
+ *
+ * STREAMING CONTRACT: implementations MUST stream the URL body to
+ * `destPath` — they MUST NOT buffer the whole output in memory. The
+ * `Promise<void>` return exists precisely so no buffered-bytes value can
+ * leak into the calling convention.
+ */
+export interface Downloader {
+    /**
+     * Stream the body at `url` to the local filesystem path `destPath`.
+     * Implementations create/overwrite `destPath`. Failures reject.
+     */
+    downloadTo(url: string, destPath: string): Promise<void>;
+}
+/**
+ * A single deliverable output of a file-first run — the file-first layer's
+ * flat output type. Leaner than the operation-first `Artifact`: just the
+ * four fields a caller needs to identify + fetch an output.
+ *
+ * Mirrors the PHP `OutputFile`.
+ */
+export interface OutputFile {
+    readonly url: string;
+    readonly filename: string;
+    readonly sizeBytes: number;
+    readonly operation: string;
+}
+/**
+ * One succeeded entry in {@link RunResult.succeeded}: a single input's
+ * outputs, addressable by the `key:` the caller gave that file (null when
+ * no key was supplied). Mirrors the PHP `ItemResult`.
+ */
+export interface ItemResult {
+    readonly key: string | null;
+    readonly outputs: readonly OutputFile[];
+}
+/**
+ * One failed entry in {@link RunResult.failed}: an input that did not
+ * produce a deliverable, paired with the cause. One bad input does not sink
+ * the rest of a multi-input run. `error` is `unknown` (mirroring the PHP
+ * `\Throwable`) so the caller narrows with `instanceof`. Mirrors the PHP
+ * `ItemFailure`.
+ */
+export interface ItemFailure {
+    readonly key: string | null;
+    readonly error: unknown;
+}
+/**
+ * Return value of {@link RunResult.downloadTo} — the local paths written,
+ * in the SAME order as {@link RunResult.artifacts}. Mirrors the PHP
+ * `Manifest`.
+ */
+export interface Manifest {
+    readonly paths: readonly string[];
+}
+/**
+ * Result of a file-first run. Coexists with the operation-first `Result`
+ * (in `builder.ts`) until FF6.
+ *
+ * Mirrors the PHP `RunResult` class. A class (not a bare interface) because
+ * it carries the `byKey()`/`toFile()`/`downloadTo()` behaviour; the data
+ * fields stay public + readonly so `toArray()` round-trips.
+ *
+ * Field notes:
+ *  - `url`: single-output sugar — the lone artifact's URL when exactly one
+ *    output exists, else undefined.
+ *  - `ok`: true iff `failed` is empty. (A boolean — the partition lists are
+ *    `succeeded`/`failed`; resolves the design doc's `ok` bool-vs-list
+ *    contradiction.)
+ *  - `state`: lifecycle state (`completed` | `failed` | ...). Named `state`,
+ *    NOT `status`, matching the file-first `StatusSnapshot.state`.
+ *  - sinks fetch via the injected {@link Downloader}; a result with no
+ *    downloader throws {@link GislSinkError} (reason `downloader_unavailable`).
+ */
+export declare class RunResult {
+    readonly workflowId: string;
+    readonly state: string;
+    readonly artifacts: readonly OutputFile[];
+    readonly succeeded: readonly ItemResult[];
+    readonly failed: readonly ItemFailure[];
+    private readonly downloader?;
+    /** Single-output sugar: the lone artifact's URL, or undefined for 0 / >1. */
+    readonly url?: string;
+    /** True iff {@link failed} is empty. */
+    readonly ok: boolean;
+    constructor(workflowId: string, state: string, artifacts: readonly OutputFile[], succeeded: readonly ItemResult[], failed: readonly ItemFailure[], downloader?: Downloader | undefined);
+    /**
+     * Address a succeeded input by the `key:` given to `file()`. Duplicate keys
+     * are not valid input — the producer enforces key uniqueness (a later
+     * ticket); the first match is returned.
+     * @throws {GislNoSuchKeyError} when no succeeded entry has that key (a
+     *   keyless run always throws — it is positionally addressable only).
+     */
+    byKey(key: string): ItemResult;
+    /**
+     * Write the single output to `path`. Requires EXACTLY ONE artifact.
+     * @throws {GislSinkError} reason `not_single_output` for 0/>1 outputs;
+     *   reason `downloader_unavailable` when no downloader is bound.
+     */
+    toFile(path: string): Promise<void>;
+    /**
+     * Download every output into `dir` (filename per output), in output order.
+     * Returns the {@link Manifest} of local paths written.
+     * @throws {GislSinkError} reason `partial_failure` when `failOnPartial` and
+     *   the run had failed inputs; reason `downloader_unavailable` when no
+     *   downloader is bound.
+     */
+    downloadTo(dir: string, options?: {
+        failOnPartial?: boolean;
+    }): Promise<Manifest>;
+    /**
+     * Plain-object projection. Field ORDER (workflowId, state, ok, url?,
+     * artifacts, succeeded, failed) is fixed to match the PHP `toArray()`
+     * reference so JSON-string parity holds (FF1 shape assertion + FF2b harness
+     * fixture). `url` is omitted entirely when undefined — `JSON.stringify`
+     * then produces the identical shape to PHP's omit-when-null `toArray()`.
+     */
+    toJSON(): {
+        workflowId: string;
+        state: string;
+        ok: boolean;
+        url?: string;
+        artifacts: readonly OutputFile[];
+        succeeded: readonly {
+            key: string | null;
+            outputs: readonly OutputFile[];
+        }[];
+        failed: readonly {
+            key: string | null;
+            error: string;
+        }[];
+    };
+    private requireDownloader;
+}
+/**
+ * The primary file a {@link Recipe} operates on — the "subject" of the
+ * file-first surface. A discriminated union over the ways a caller names an
+ * input:
+ *
+ *  - `path`     — a local filesystem path (Node; the common case).
+ *  - `blob`     — an in-memory `Blob`/`File` (browser, or Node 18+).
+ *  - `uploadId` — a previously-uploaded `file_id` (reuse across recipes).
+ *
+ * FF2a does NO upload, so only the `path` + `uploadId` arms are exercised
+ * end-to-end here; the `blob` arm is DEFINED and type-checked but its upload
+ * is wired by FF2b (`run()`). Mirrors the PHP `FileInput` value object.
+ */
+export type FileInput = {
+    readonly kind: 'path';
+    readonly path: string;
+} | {
+    readonly kind: 'blob';
+    readonly blob: Blob;
+} | {
+    readonly kind: 'uploadId';
+    readonly fileId: string;
+};
+/** Named constructors for {@link FileInput} — mirror the PHP static factories. */
+export declare const fileInput: {
+    readonly path: (path: string) => FileInput;
+    readonly blob: (blob: Blob) => FileInput;
+    readonly uploadId: (fileId: string) => FileInput;
+};
+/** One step in a {@link Recipe}'s chain — an op kind + captured ergonomic args. */
+interface RecipeStep {
+    readonly opType: 'compress' | 'convert' | 'thumbnail' | 'text_watermark';
+    readonly options: Readonly<Record<string, unknown>>;
+}
+/**
+ * The file-first builder value. `client.file(path)` returns a `Recipe`;
+ * single-input operations called on it (`compress`, `convert`, `thumbnail`,
+ * `textWatermark`) chain SEQUENTIALLY — each op feeds the next, and the chain
+ * lowers to ONE workflow job with an ordered `operations[]` (per ADR-0004:
+ * operations execute sequentially, each consuming the previous output). A
+ * chain yields the TERMINAL output only; intermediates are consumed (surfaced
+ * by FF2b's `run()`/{@link RunResult}).
+ *
+ * **Immutable / clone-on-write.** Every op returns a NEW `Recipe` carrying the
+ * appended step — `this` is never mutated. A Recipe is therefore a reusable
+ * value: branching the same base recipe two different ways cannot let one
+ * branch observe the other's steps (the aliasing trap mutable builders fall
+ * into).
+ *
+ * FF2a is network-free: there is NO `run()` here (that is FF2b). The lowering
+ * seam {@link toWorkflowPayload} takes the resolved upload id as a parameter
+ * so it stays pure — FF2b's `run()` calls the SAME method after uploading, and
+ * the parity harness calls it with a fixed id to assert the lowered shape.
+ *
+ * Mirrors the PHP `Recipe`.
+ */
+export declare class Recipe {
+    private readonly input;
+    private readonly recipeKey;
+    private readonly steps;
+    private readonly presetDefaults?;
+    private readonly scopedPresetDefaults?;
+    private readonly client?;
+    constructor(input: FileInput, recipeKey?: string | undefined, steps?: readonly RecipeStep[], presetDefaults?: PresetDefaults | undefined, scopedPresetDefaults?: PresetDefaults | undefined, client?: GislClient | undefined);
+    /**
+     * Reduce file size. `optimize` selects a per-media preset (resolved to
+     * concrete wire fields at lower-time, exactly as `client.compress()` does).
+     */
+    compress(optimize?: OptimizeFor): Recipe;
+    /** Change format. `format` is lowered verbatim to the `format` wire option. */
+    convert(format: string): Recipe;
+    /**
+     * Generate a preview. Width and/or height in pixels; an omitted dimension is
+     * dropped from the wire options (not sent as `undefined`).
+     */
+    thumbnail(options?: {
+        width?: number;
+        height?: number;
+    }): Recipe;
+    /**
+     * Apply a text watermark. Single-input (the text is an option, not a
+     * secondary file) — lowers to the `text_watermark` op with a `text` option.
+     */
+    textWatermark(text: string): Recipe;
+    /**
+     * Lower this recipe to a workflow-create payload against a resolved upload
+     * id. Single-input chain → ONE job, `source: upload(fileId)`, ordered
+     * `operations[]`; the job `id` is omitted (a single job referenced by
+     * nothing — the server auto-assigns `job_N`).
+     *
+     * @internal Consumed by FF2b's `run()` (after a real upload) and by the
+     *   cross-language parity harness (with a fixed id). Not part of the
+     *   caller-facing fluent surface.
+     */
+    toWorkflowPayload(fileId: string): WorkflowCreatePayload;
+    /** The result-addressing key passed to `file()`, or undefined. */
+    key(): string | undefined;
+    /** The number of operations chained so far (introspection / tests). */
+    get stepCount(): number;
+    /**
+     * Execute the recipe end-to-end: upload the input (when required), create
+     * the workflow, await a terminal state (SSE with poll fallback), then
+     * resolve the produced downloads into a flat {@link RunResult}. Throws
+     * {@link GislTimeoutError} if `maxWait` elapses before terminal status.
+     *
+     * Mirrors the operation-first `OperationBuilder.run` (in `builder.ts`).
+     * Requires a client bound at construction time — `gisl().file(...)` wires
+     * it; a directly-constructed `Recipe` (e.g. in a lowering-only test) has no
+     * client and throws {@link GislConfigError}.
+     */
+    run(options?: {
+        maxWait?: string | number;
+        onProgress?: (event: ProgressEvent) => void;
+        signal?: AbortSignal;
+        pollIntervalMs?: number;
+    }): Promise<RunResult>;
+    private withStep;
+    private lowerStep;
+    private lowerCompressOptions;
+    private compressMediaHint;
+}
+export {};

package/dist/file-first.js

@@ -0,0 +1,445 @@
+/**
+ * File-first result surface — the value the file-first layer's `run()` /
+ * `Handle.wait()` / `Handle.result()` return (producers land in FF2b/FF5).
+ *
+ * Coexists with the operation-first `Result`/`Artifact` (in `builder.ts`)
+ * until the operation-first layer is removed (FF6). The file-first shape is
+ * flatter and adds an always-present per-input partition (`succeeded` /
+ * `failed`) so one bad input in a multi-input run doesn't sink the rest.
+ *
+ * Mirrors `packages/php/src/FileFirst/*`.
+ */
+import { GislApiError, GislConfigError, GislNoSuchKeyError, GislSinkError, GislTimeoutError } from './errors.js';
+import { _detectCompressMedia, _consumeSseToTerminal, _pollToTerminal, _parseMaxWait, _checkAborted, } from './builder.js';
+import { HttpDownloader } from './http-downloader.js';
+import { resolveCompressOptions, } from './ergonomic/preset_resolver.js';
+import { OptimizeFor } from './generated/sdk_spec/enums.js';
+import { uploadSource } from './types.js';
+/**
+ * Result of a file-first run. Coexists with the operation-first `Result`
+ * (in `builder.ts`) until FF6.
+ *
+ * Mirrors the PHP `RunResult` class. A class (not a bare interface) because
+ * it carries the `byKey()`/`toFile()`/`downloadTo()` behaviour; the data
+ * fields stay public + readonly so `toArray()` round-trips.
+ *
+ * Field notes:
+ *  - `url`: single-output sugar — the lone artifact's URL when exactly one
+ *    output exists, else undefined.
+ *  - `ok`: true iff `failed` is empty. (A boolean — the partition lists are
+ *    `succeeded`/`failed`; resolves the design doc's `ok` bool-vs-list
+ *    contradiction.)
+ *  - `state`: lifecycle state (`completed` | `failed` | ...). Named `state`,
+ *    NOT `status`, matching the file-first `StatusSnapshot.state`.
+ *  - sinks fetch via the injected {@link Downloader}; a result with no
+ *    downloader throws {@link GislSinkError} (reason `downloader_unavailable`).
+ */
+export class RunResult {
+    workflowId;
+    state;
+    artifacts;
+    succeeded;
+    failed;
+    downloader;
+    /** Single-output sugar: the lone artifact's URL, or undefined for 0 / >1. */
+    url;
+    /** True iff {@link failed} is empty. */
+    ok;
+    constructor(workflowId, state, artifacts, succeeded, failed, downloader) {
+        this.workflowId = workflowId;
+        this.state = state;
+        this.artifacts = artifacts;
+        this.succeeded = succeeded;
+        this.failed = failed;
+        this.downloader = downloader;
+        this.url = artifacts.length === 1 ? artifacts[0].url : undefined;
+        this.ok = failed.length === 0;
+    }
+    /**
+     * Address a succeeded input by the `key:` given to `file()`. Duplicate keys
+     * are not valid input — the producer enforces key uniqueness (a later
+     * ticket); the first match is returned.
+     * @throws {GislNoSuchKeyError} when no succeeded entry has that key (a
+     *   keyless run always throws — it is positionally addressable only).
+     */
+    byKey(key) {
+        const item = this.succeeded.find((i) => i.key === key);
+        if (item === undefined) {
+            throw new GislNoSuchKeyError(`No result for key '${key}'.`);
+        }
+        return item;
+    }
+    /**
+     * Write the single output to `path`. Requires EXACTLY ONE artifact.
+     * @throws {GislSinkError} reason `not_single_output` for 0/>1 outputs;
+     *   reason `downloader_unavailable` when no downloader is bound.
+     */
+    async toFile(path) {
+        if (this.artifacts.length !== 1) {
+            throw new GislSinkError(`toFile() requires exactly one output; this run produced ${this.artifacts.length}. ` +
+                'Use downloadTo() for multi-output runs.', { reason: 'not_single_output' });
+        }
+        await this.requireDownloader().downloadTo(this.artifacts[0].url, path);
+    }
+    /**
+     * Download every output into `dir` (filename per output), in output order.
+     * Returns the {@link Manifest} of local paths written.
+     * @throws {GislSinkError} reason `partial_failure` when `failOnPartial` and
+     *   the run had failed inputs; reason `downloader_unavailable` when no
+     *   downloader is bound.
+     */
+    async downloadTo(dir, options) {
+        if (options?.failOnPartial && this.failed.length > 0) {
+            throw new GislSinkError(`downloadTo({ failOnPartial: true }) but the run had ${this.failed.length} failed input(s).`, { reason: 'partial_failure' });
+        }
+        if (dir === '') {
+            throw new GislSinkError("downloadTo(): the directory argument is empty. Pass a target directory (use '.' for the current directory).", { reason: 'invalid_directory' });
+        }
+        const downloader = this.requireDownloader();
+        const sep = dir.endsWith('/') || dir.endsWith('\\') ? '' : '/';
+        // Resolve destinations first so a basename collision fails loudly BEFORE any
+        // byte is written — silently overwriting an earlier output is data loss.
+        const names = this.artifacts.map(
+        // Strip any directory component from a server-supplied filename so a value
+        // like "../x" or "a/b" cannot escape `dir` (mirrors PHP basename()).
+        (a) => a.filename.split(/[/\\]/).pop() ?? a.filename);
+        // Collision key is case-folded: many destination filesystems (macOS, NTFS)
+        // are case-insensitive, so `a.jpg` and `A.jpg` would target the same file.
+        const seen = new Set();
+        for (const name of names) {
+            const key = name.toLowerCase();
+            if (seen.has(key)) {
+                throw new GislSinkError(`downloadTo(): two outputs resolve to the same filename '${name}' in '${dir}' ` +
+                    '(case-insensitively). Download them to separate directories.', { reason: 'duplicate_filename' });
+            }
+            seen.add(key);
+        }
+        const paths = [];
+        for (let i = 0; i < this.artifacts.length; i++) {
+            const dest = `${dir}${sep}${names[i]}`;
+            await downloader.downloadTo(this.artifacts[i].url, dest);
+            paths.push(dest);
+        }
+        return { paths };
+    }
+    /**
+     * Plain-object projection. Field ORDER (workflowId, state, ok, url?,
+     * artifacts, succeeded, failed) is fixed to match the PHP `toArray()`
+     * reference so JSON-string parity holds (FF1 shape assertion + FF2b harness
+     * fixture). `url` is omitted entirely when undefined — `JSON.stringify`
+     * then produces the identical shape to PHP's omit-when-null `toArray()`.
+     */
+    toJSON() {
+        // Re-project each OutputFile to exactly its four fields so structurally
+        // compatible inputs carrying extra properties can't leak into the JSON.
+        const file = (o) => ({
+            url: o.url,
+            filename: o.filename,
+            sizeBytes: o.sizeBytes,
+            operation: o.operation,
+        });
+        const rest = {
+            artifacts: this.artifacts.map(file),
+            succeeded: this.succeeded.map((i) => ({ key: i.key, outputs: i.outputs.map(file) })),
+            failed: this.failed.map((f) => ({
+                key: f.key,
+                error: f.error instanceof Error ? f.error.message : String(f.error),
+            })),
+        };
+        const head = { workflowId: this.workflowId, state: this.state, ok: this.ok };
+        // Insert `url` BETWEEN ok and artifacts when present, matching the PHP
+        // toArray() field order (workflowId, state, ok, url?, artifacts, ...) so
+        // JSON-string parity holds. Omitted entirely when undefined (PHP omits
+        // null), so `JSON.stringify` produces the identical shape.
+        return this.url === undefined
+            ? { ...head, ...rest }
+            : { ...head, url: this.url, ...rest };
+    }
+    requireDownloader() {
+        if (this.downloader === undefined) {
+            throw new GislSinkError('This result has no downloader bound, so its outputs cannot be written to disk here ' +
+                '(e.g. a browser / no-I/O context). Fetch each output from its URL instead.', { reason: 'downloader_unavailable' });
+        }
+        return this.downloader;
+    }
+}
+/** Named constructors for {@link FileInput} — mirror the PHP static factories. */
+export const fileInput = {
+    path(path) {
+        return { kind: 'path', path };
+    },
+    blob(blob) {
+        return { kind: 'blob', blob };
+    },
+    uploadId(fileId) {
+        return { kind: 'uploadId', fileId };
+    },
+};
+/**
+ * The file-first builder value. `client.file(path)` returns a `Recipe`;
+ * single-input operations called on it (`compress`, `convert`, `thumbnail`,
+ * `textWatermark`) chain SEQUENTIALLY — each op feeds the next, and the chain
+ * lowers to ONE workflow job with an ordered `operations[]` (per ADR-0004:
+ * operations execute sequentially, each consuming the previous output). A
+ * chain yields the TERMINAL output only; intermediates are consumed (surfaced
+ * by FF2b's `run()`/{@link RunResult}).
+ *
+ * **Immutable / clone-on-write.** Every op returns a NEW `Recipe` carrying the
+ * appended step — `this` is never mutated. A Recipe is therefore a reusable
+ * value: branching the same base recipe two different ways cannot let one
+ * branch observe the other's steps (the aliasing trap mutable builders fall
+ * into).
+ *
+ * FF2a is network-free: there is NO `run()` here (that is FF2b). The lowering
+ * seam {@link toWorkflowPayload} takes the resolved upload id as a parameter
+ * so it stays pure — FF2b's `run()` calls the SAME method after uploading, and
+ * the parity harness calls it with a fixed id to assert the lowered shape.
+ *
+ * Mirrors the PHP `Recipe`.
+ */
+export class Recipe {
+    input;
+    recipeKey;
+    steps;
+    presetDefaults;
+    scopedPresetDefaults;
+    client;
+    constructor(input, recipeKey = undefined, steps = [], presetDefaults, scopedPresetDefaults, client) {
+        this.input = input;
+        this.recipeKey = recipeKey;
+        this.steps = steps;
+        this.presetDefaults = presetDefaults;
+        this.scopedPresetDefaults = scopedPresetDefaults;
+        this.client = client;
+    }
+    /**
+     * Reduce file size. `optimize` selects a per-media preset (resolved to
+     * concrete wire fields at lower-time, exactly as `client.compress()` does).
+     */
+    compress(optimize) {
+        if (optimize !== undefined && !Object.values(OptimizeFor).includes(optimize)) {
+            const allowed = Object.values(OptimizeFor).join(', ');
+            throw new GislConfigError(`compress 'optimize' must be one of ${allowed}; got '${String(optimize)}'.`, { reason: 'invalid_optimize', conflictingFields: ['optimize'] });
+        }
+        return this.withStep({ opType: 'compress', options: optimize === undefined ? {} : { optimize } });
+    }
+    /** Change format. `format` is lowered verbatim to the `format` wire option. */
+    convert(format) {
+        return this.withStep({ opType: 'convert', options: { format } });
+    }
+    /**
+     * Generate a preview. Width and/or height in pixels; an omitted dimension is
+     * dropped from the wire options (not sent as `undefined`).
+     */
+    thumbnail(options = {}) {
+        const wire = {};
+        if (options.width !== undefined)
+            wire.width = options.width;
+        if (options.height !== undefined)
+            wire.height = options.height;
+        return this.withStep({ opType: 'thumbnail', options: wire });
+    }
+    /**
+     * Apply a text watermark. Single-input (the text is an option, not a
+     * secondary file) — lowers to the `text_watermark` op with a `text` option.
+     */
+    textWatermark(text) {
+        return this.withStep({ opType: 'text_watermark', options: { text } });
+    }
+    /**
+     * Lower this recipe to a workflow-create payload against a resolved upload
+     * id. Single-input chain → ONE job, `source: upload(fileId)`, ordered
+     * `operations[]`; the job `id` is omitted (a single job referenced by
+     * nothing — the server auto-assigns `job_N`).
+     *
+     * @internal Consumed by FF2b's `run()` (after a real upload) and by the
+     *   cross-language parity harness (with a fixed id). Not part of the
+     *   caller-facing fluent surface.
+     */
+    toWorkflowPayload(fileId) {
+        const operations = this.steps.map((step) => this.lowerStep(step));
+        // Key order (source, operations) matches the PHP `toWire()` so the
+        // JSON-string serialisation is byte-identical across languages.
+        const job = { source: uploadSource(fileId), operations };
+        return { jobs: [job] };
+    }
+    /** The result-addressing key passed to `file()`, or undefined. */
+    key() {
+        return this.recipeKey;
+    }
+    /** The number of operations chained so far (introspection / tests). */
+    get stepCount() {
+        return this.steps.length;
+    }
+    /**
+     * Execute the recipe end-to-end: upload the input (when required), create
+     * the workflow, await a terminal state (SSE with poll fallback), then
+     * resolve the produced downloads into a flat {@link RunResult}. Throws
+     * {@link GislTimeoutError} if `maxWait` elapses before terminal status.
+     *
+     * Mirrors the operation-first `OperationBuilder.run` (in `builder.ts`).
+     * Requires a client bound at construction time — `gisl().file(...)` wires
+     * it; a directly-constructed `Recipe` (e.g. in a lowering-only test) has no
+     * client and throws {@link GislConfigError}.
+     */
+    async run(options = {}) {
+        const signal = options.signal;
+        const onProgress = options.onProgress;
+        if (this.client === undefined) {
+            throw new GislConfigError('Recipe.run() requires a client; build the recipe via gisl().file(...) rather than constructing Recipe directly.', { reason: 'no_client' });
+        }
+        const deadline = Date.now() + _parseMaxWait(options.maxWait ?? 300_000);
+        // 1. Resolve the upload id. A pre-uploaded id skips the upload entirely;
+        // a path / blob is uploaded now, emitting {phase:'upload'} progress.
+        let fileId;
+        if (this.input.kind === 'uploadId') {
+            fileId = this.input.fileId;
+        }
+        else {
+            const source = this.input.kind === 'path' ? this.input.path : this.input.blob;
+            const up = await this.client.uploadFile(source, {
+                signal,
+                ...(onProgress !== undefined
+                    ? {
+                        onProgress: (uploadedBytes, totalBytes) => {
+                            onProgress({ phase: 'upload', uploadedBytes, totalBytes });
+                        },
+                    }
+                    : {}),
+            });
+            fileId = up.fileId;
+        }
+        _checkAborted(signal);
+        if (Date.now() >= deadline) {
+            throw new GislTimeoutError('Upload completed but maxWait elapsed before workflow could be created');
+        }
+        // 2. Create the workflow from the lowered payload.
+        const payload = this.toWorkflowPayload(fileId);
+        const created = await this.client.createWorkflow(payload);
+        _checkAborted(signal);
+        // 3. Wait to terminal status — SSE first, poll on a genuine SSE error.
+        // Caller-aborted + deadline-elapsed errors MUST propagate (not transient).
+        let finalStatus;
+        try {
+            finalStatus = await _consumeSseToTerminal(this.client, {
+                workflowId: created.workflowId,
+                deadline,
+                signal,
+                onProgress,
+            });
+        }
+        catch (err) {
+            // Only genuine SSE transport / clean-stream-end failures fall through to
+            // poll. Caller-deadline, abort, and API errors (a 401/402/etc. from
+            // /events, or an onProgress callback throw surfacing as GislApiError)
+            // MUST propagate — re-issuing the same doomed request via poll would mask
+            // them. Mirrors the PHP BuilderInternals::awaitTerminal sealed-marker
+            // discipline (codex review medium).
+            if (err instanceof GislTimeoutError)
+                throw err;
+            if (err instanceof DOMException && err.name === 'AbortError')
+                throw err;
+            if (err instanceof GislApiError)
+                throw err;
+            finalStatus = await _pollToTerminal(this.client, {
+                workflowId: created.workflowId,
+                deadline,
+                signal,
+                pollIntervalMs: options.pollIntervalMs,
+            });
+        }
+        // 4. Fetch downloads. The maxWait deadline covers upload + create + wait +
+        // downloads, so check before issuing the request (mirrors builder.ts).
+        if (Date.now() >= deadline) {
+            throw new GislTimeoutError(`Workflow ${created.workflowId} reached terminal status but maxWait elapsed before downloads could be fetched`);
+        }
+        const downloads = await this.client.getWorkflowDownloads(created.workflowId);
+        // Flatten to the lean OutputFile[] (the four file-first fields only).
+        const artifacts = [];
+        for (const job of downloads.downloads) {
+            for (const f of job.files) {
+                artifacts.push({
+                    url: f.downloadUrl,
+                    filename: f.filename,
+                    sizeBytes: f.sizeBytes,
+                    operation: f.operation,
+                });
+            }
+        }
+        // Partition the single input into succeeded / failed by terminal state.
+        // Success is ONLY `completed`: every other terminal state — `failed`,
+        // `partially_failed`, `cancelled`, `expired`,
+        // `paused_insufficient_credits` — is a non-success and partitions into
+        // `failed` so a caller's `ok`/`succeeded` check can never treat a
+        // cancelled/expired/paused run as a clean result (codex review high).
+        const state = finalStatus.status;
+        const key = this.recipeKey ?? null;
+        let succeeded;
+        let failed;
+        if (state === 'completed') {
+            succeeded = [{ key, outputs: artifacts }];
+            failed = [];
+        }
+        else {
+            const firstError = (finalStatus.jobs ?? [])
+                .flatMap((j) => j.operations ?? [])
+                .map((op) => op.errorMessage)
+                .find((m) => m !== undefined);
+            succeeded = [];
+            failed = [
+                { key, error: new Error(firstError !== undefined ? `${state}: ${firstError}` : state) },
+            ];
+        }
+        // Download URLs from getWorkflowDownloads are pre-signed and require no SDK
+        // auth, so the downloader issues a plain unauthenticated fetch.
+        const downloader = new HttpDownloader();
+        return new RunResult(created.workflowId, state, artifacts, succeeded, failed, downloader);
+    }
+    withStep(step) {
+        return new Recipe(this.input, this.recipeKey, [...this.steps, step], this.presetDefaults, this.scopedPresetDefaults, this.client);
+    }
+    lowerStep(step) {
+        const options = step.opType === 'compress' ? this.lowerCompressOptions(step.options) : { ...step.options };
+        // Empty options omit the `options` wire key entirely, so TS (undefined →
+        // absent) and PHP (null → absent) serialise byte-identically.
+        return Object.keys(options).length === 0
+            ? { type: step.opType }
+            : { type: step.opType, options };
+    }
+    lowerCompressOptions(options) {
+        const optimize = options.optimize;
+        const media = this.compressMediaHint();
+        if (media === undefined) {
+            // Cannot infer a media class (a Blob without a recognised name, or a
+            // bare upload id) → preset resolution is impossible. Fail FAST rather
+            // than silently dropping an explicit `optimize`; bare compress() is fine.
+            if (optimize !== undefined) {
+                throw new GislConfigError(`compress(optimize: ${String(optimize)}) needs a media type to resolve the preset, but the ` +
+                    'input has no inferable media (a pre-uploaded file id or unnamed Blob carries no extension). ' +
+                    'Use a path with a file extension, or call compress() without optimize.', { reason: 'media_unknown', conflictingFields: ['optimize'] });
+            }
+            return {};
+        }
+        const input = { media, op: 'compress', explicitOptions: {} };
+        if (this.presetDefaults !== undefined) {
+            input.presetDefaults = this.presetDefaults;
+        }
+        if (this.scopedPresetDefaults !== undefined) {
+            input.scopedPresetDefaults =
+                this.scopedPresetDefaults;
+        }
+        if (optimize !== undefined) {
+            input.optimize = optimize;
+        }
+        return { ...resolveCompressOptions(input).wireOptions };
+    }
+    compressMediaHint() {
+        if (this.input.kind === 'path') {
+            return _detectCompressMedia(this.input.path);
+        }
+        if (this.input.kind === 'blob') {
+            return _detectCompressMedia(this.input.blob);
+        }
+        return undefined;
+    }
+}

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,7 @@ 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';
 /**
  * Operations that may be invoked on a `gisl.anonymous()` client without
  * raising `GislFeatureRequiresAuthError`. Empty until the free-tier launch
@@ -67,6 +68,15 @@ 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;
     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,7 @@ 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';
 // ---------------------------------------------------------------------------
 // Anonymous-capable operation allowlist (internal)
 // ---------------------------------------------------------------------------
@@ -71,6 +72,22 @@ 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 === 'compress' || prop === 'convert' || prop === 'thumbnail') {
                 return (input, options = {}) => {
                     // T4b — pass client-scope presetDefaults into the builder so

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' });
+        }
+    }
+}

package/dist/index.d.ts

@@ -4,8 +4,13 @@ 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, GislConfigError, GislMissingCredentialsError, GislFeatureRequiresAuthError, GislUndeclaredAssetError, GislUnusedAssetError, GislPerInputOptionsNotSupportedError, GislChainCardinalityMismatchError, } 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 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 { HttpDownloader } from './http-downloader.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';

package/dist/index.js

@@ -7,6 +7,9 @@ export { uploadSource, jobOutputSource, externalImportSource, connectionSource,
 export { GislError, GislApiError, GislValidationError, GislBalanceExhaustedError, GislTierRestrictedError, GislFeatureTierRestrictedError, GislFeatureNotAvailableError, GislWorkflowExpiredError, GislProbePendingError, GislAuthError, GislUploadCapExceededError, GislMultipartPartError, GislMultipartPartCountError, 
 // SDK-3 (Wb6ebOMM) — typed errors for the 3 resume-support endpoints.
 GislMultipartSessionNotFoundError, GislMultipartSessionOwnershipError, GislMultipartSessionAuthRequiredError, GislTimeoutError, GislAbortError, 
+// FF2b / tywwynmN — transport-level failure (mirrors PHP GislNetworkError);
+// raised by the file-first HttpDownloader when an output URL cannot be read.
+GislNetworkError, 
 // T1 / wVU4xHx3 — local config-error tree (pre-I/O; sibling of GislApiError).
 GislConfigError, GislMissingCredentialsError, GislFeatureRequiresAuthError, 
 // T3 / cuecCmb5 — merge-compose local validation errors.
@@ -14,7 +17,17 @@ GislUndeclaredAssetError, GislUnusedAssetError, GislPerInputOptionsNotSupportedE
 // T6 / aDR1jnyZ — chain-cardinality validation (dormant until chain
 // methods on OperationBuilder ship; type + audit registration land
 // here so the future chain-method PR is a pure addition).
-GislChainCardinalityMismatchError, } from './errors.js';
+GislChainCardinalityMismatchError, 
+// FF1 / 3BIxEnfR — file-first result sink errors.
+GislNoSuchKeyError, GislSinkError, } 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 execution (FF2b / MfV0PDok) — Node streaming downloader bound by
+// `Recipe.run()` to write pre-signed output URLs to disk.
+export { HttpDownloader } from './http-downloader.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@giveitsmaller/sdk",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Node.js SDK for the GISL (Give It Smaller) file compression and processing API",
   "license": "MIT",
   "type": "module",
@@ -19,12 +19,12 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@giveitsmaller/contracts": "^0.8.0"
+    "@giveitsmaller/contracts": "^0.9.0"
   },
   "devDependencies": {
     "@types/node": "^22",
     "typescript": "^5.7",
-    "vitest": "^3.1",
+    "vitest": "^3.1 <3.2.5",
     "yaml": "^2.6"
   },
   "scripts": {