@giveitsmaller/sdk 0.7.0 → 0.9.0

package/dist/file-first.d.ts

@@ -0,0 +1,503 @@
+/**
+ * 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 type { OperationDownload, WorkflowStatusResponse } from '@giveitsmaller/contracts/openapi';
+import { OptimizeFor } from './generated/sdk_spec/enums.js';
+import type { PresetDefaults } from './ergonomic/presets/index.js';
+import type { WorkflowCreatePayload } from './types.js';
+import { Handle } from './handle.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;
+}
+/**
+ * Flatten the terminal workflow status + its downloads into a {@link RunResult}.
+ *
+ * Shared by {@link Recipe.run} (passes its recipe key) and the file-first
+ * {@link Handle} reattach surface (`Handle.wait()`/`Handle.result()`, FF5a —
+ * passes `null` because a reattached handle carries no recipe key).
+ *
+ * **Partition invariant (carries a prior codex-review fix — do NOT let it
+ * drift):** success is ONLY `state === 'completed'`. Every other terminal
+ * state — `failed`, `partially_failed`, `cancelled`, `expired`,
+ * `paused_insufficient_credits` — partitions into `failed[]` so a caller's
+ * `ok`/`succeeded` check can never treat a cancelled/expired/paused run as a
+ * clean result.
+ *
+ * @internal Exported for reuse by the file-first `Handle`; not part of the
+ *   caller-facing fluent surface.
+ */
+export declare function projectDownloadsToRunResult(workflowId: string, finalStatus: WorkflowStatusResponse, jobDownloads: readonly {
+    files: readonly OperationDownload[];
+}[], key: string | null, downloader?: Downloader): RunResult;
+/**
+ * Flatten a terminal multi-job workflow (the `client.files([...])` fan-out)
+ * into a partitioned {@link RunResult}. One job per input file, keyed by the
+ * `file-{i}` job ref the {@link FilesRecipe} lowering assigns; the result's
+ * `succeeded` / `failed` partition is PER JOB, so one bad input does not sink
+ * the rest.
+ *
+ * Join model: `finalStatus.jobs[]` carries the per-job {@link JobStatus} +
+ * `operations[]` (for the error message); `jobDownloads[]` carries the per-job
+ * output files. Both are joined on the job `ref` ("file-{i}"); the partition
+ * key is the index `"{i}"` parsed out of that ref. The flat `artifacts[]` is
+ * every job's outputs in job order (the order `finalStatus.jobs[]` lists them).
+ *
+ * **Partition invariant (mirrors {@link projectDownloadsToRunResult} PER JOB —
+ * do NOT let it drift):** a job is a SUCCESS only when its
+ * {@link JobResponse.status} `=== 'completed'`. Any other per-job status —
+ * `failed`, `pending`, `waiting`, `blocked_insufficient_credits`,
+ * `in_progress` — partitions that job into `failed[]` (with that job's first
+ * operation error message, scoped to THAT job only).
+ *
+ * @internal Exported for the file-first `client.files([...]).run()` producer;
+ *   not part of the caller-facing fluent surface.
+ */
+export declare function projectMultiJobToRunResult(workflowId: string, finalStatus: WorkflowStatusResponse, jobDownloads: readonly {
+    ref: string;
+    files: readonly OperationDownload[];
+}[], keyByRef: ReadonlyMap<string, string | null>, downloader?: Downloader): RunResult;
+/**
+ * True when a terminal status describes a homogeneous `files([...])` fan-out —
+ * i.e. it has at least one job and EVERY job ref is `file-{i}` (the ids the
+ * {@link FilesRecipe} lowering assigns). A single-file {@link Recipe} omits the
+ * job id, so its job carries a non-`file-N` ref (e.g. `op`) and this is false.
+ *
+ * This is the data-driven seam that lets {@link Handle.wait}/{@link Handle.result}
+ * pick the per-job producer ({@link projectMultiJobToRunResult}) over the
+ * single-output one for a fan-out — WITHOUT a construction-time marker, so a
+ * fan-out **reattached** via `client.workflow(id)` (which carries no marker)
+ * still partitions per job. Keys are recovered from the `file-{i}` refs.
+ *
+ * @internal Exported for the file-first `Handle`; not part of the public API.
+ */
+export declare function isFanoutStatus(finalStatus: WorkflowStatusResponse): boolean;
+/**
+ * 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`).
+     *
+     * When `callbackUrl` is given (the file-first `submit()` path), it is built
+     * INTO the payload at construction (`callback_url`) rather than spread onto an
+     * already-built readonly payload. `run()` passes no `callbackUrl`.
+     *
+     * @internal Consumed by FF2b's `run()` (after a real upload), FF5b's
+     *   `submit()` (with a webhook), and the cross-language parity harness (with a
+     *   fixed id). Not part of the caller-facing fluent surface.
+     */
+    toWorkflowPayload(fileId: string, callbackUrl?: 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;
+    /**
+     * The captured op chain. Read by {@link FilesRecipe} to compose a shared
+     * chain across many inputs without duplicating the chain-method validation.
+     * @internal
+     */
+    get recipeSteps(): readonly RecipeStep[];
+    /**
+     * 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>;
+    /**
+     * Fire-and-forget the recipe: upload the input (when required), create the
+     * workflow (wiring `webhook` into `callback_url` when given), and return a
+     * client-bound {@link Handle} carrying the workflow id + webhook secret + the
+     * recipe key. Does NOT wait for terminal status — call `handle.wait()` /
+     * `handle.result()` later to collect the {@link RunResult}.
+     *
+     * Requires a client bound at construction time (same `no_client` guard as
+     * {@link run}). `webhook` is OPTIONAL: when omitted, no `callback_url` is
+     * sent. Mirrors the PHP `Recipe.submit()`.
+     *
+     * @param webhook Absolute callback URL the server POSTs lifecycle events to.
+     */
+    submit(webhook?: string): Promise<Handle>;
+    /**
+     * Resolve the upload id (verbatim for a pre-uploaded id; uploading a path /
+     * blob otherwise, emitting `{phase:'upload'}` progress), check the post-upload
+     * deadline, lower to the workflow-create payload (wiring `webhook` into
+     * `callback_url`), and create the workflow. Shared first half of
+     * {@link run} + {@link submit}.
+     *
+     * The post-upload deadline check carries a prior codex fix (9a117f04eb59): a
+     * slow upload must not proceed to createWorkflow past the deadline.
+     */
+    private _uploadAndCreate;
+    private withStep;
+    private lowerStep;
+    private lowerCompressOptions;
+    private compressMediaHint;
+}
+/**
+ * The homogeneous fan-out builder value (FF3a). `client.files([a, b, c])`
+ * returns a `FilesRecipe`; the op-chain methods (`compress`, `convert`,
+ * `thumbnail`, `textWatermark`) build ONE shared recipe (chain) that is applied
+ * to EVERY input file in ONE workflow. `run()` returns a partitioned
+ * {@link RunResult} — one `succeeded`/`failed` entry per input, keyed by its
+ * 0-based index ("0", "1", …) so one bad input does not sink the rest.
+ *
+ * **Immutable / clone-on-write**, exactly like {@link Recipe}: every op returns
+ * a NEW `FilesRecipe` carrying the appended step. The inputs are held as an
+ * ORDERED list (NOT a map) so the per-file index is the partition key.
+ *
+ * **Lowering composes {@link Recipe} per file** rather than duplicating
+ * `lowerStep`/`lowerCompressOptions`: for each input `i` it builds an internal
+ * single-file `Recipe(input_i, …, steps)`, calls its `toWorkflowPayload` to get
+ * that file's one-job payload, then merges all jobs into ONE
+ * {@link WorkflowCreatePayload} with `jobs[i].id = "file-{i}"`. This preserves
+ * each file's media-hint (different extensions per input resolve compress
+ * presets independently).
+ *
+ * Exposes both `run()` (blocking, returns a partitioned {@link RunResult}) and
+ * `submit(webhook?)` (fire-and-forget, returns a {@link Handle}). Mirrors the
+ * PHP `FilesRecipe`.
+ */
+export declare class FilesRecipe {
+    private readonly inputs;
+    private readonly steps;
+    private readonly presetDefaults?;
+    private readonly scopedPresetDefaults?;
+    private readonly client?;
+    constructor(inputs: readonly FileInput[], steps?: readonly RecipeStep[], presetDefaults?: PresetDefaults | undefined, scopedPresetDefaults?: PresetDefaults | undefined, client?: GislClient | undefined);
+    /**
+     * Reduce file size on every input. `optimize` selects a per-media preset
+     * (resolved per file at lower-time, so each input's extension picks its own
+     * preset). Reuses {@link Recipe}'s validation — a directly-constructed
+     * lowering builds an internal Recipe that throws the same `GislConfigError`.
+     */
+    compress(optimize?: OptimizeFor): FilesRecipe;
+    /** Change every input's format. `format` lowers verbatim to the `format` option. */
+    convert(format: string): FilesRecipe;
+    /** Generate a preview of every input. Omitted dimensions are dropped from the wire options. */
+    thumbnail(options?: {
+        width?: number;
+        height?: number;
+    }): FilesRecipe;
+    /** Apply the same text watermark to every input. */
+    textWatermark(text: string): FilesRecipe;
+    /** The number of inputs in this fan-out (introspection / tests). */
+    get inputCount(): number;
+    /** The number of operations chained so far (introspection / tests). */
+    get stepCount(): number;
+    /**
+     * Lower this fan-out to a single multi-job workflow-create payload against a
+     * list of resolved upload ids (one per input, in input order). Each input `i`
+     * becomes ONE job with `id = "file-{i}"`, its `source: upload(fileIds[i])`,
+     * and the SHARED lowered `operations[]`. Composes the single-file
+     * {@link Recipe.toWorkflowPayload} per file so per-file media-hints resolve
+     * independently and lowering logic is not duplicated.
+     *
+     * @internal Consumed by {@link run} (after uploading all inputs) and the
+     *   cross-language parity harness (with fixed ids). Not caller-facing.
+     */
+    toWorkflowPayload(fileIds: readonly string[], callbackUrl?: string): WorkflowCreatePayload;
+    /**
+     * Execute the fan-out end-to-end: upload EVERY input, create ONE workflow
+     * with one job per input, await a terminal state (SSE with poll fallback),
+     * then resolve the per-job downloads into a partitioned {@link RunResult}.
+     * `partially_failed` is a NORMAL terminal state here — its successful jobs
+     * land in `succeeded`, its failed jobs in `failed`.
+     *
+     * Requires a client bound at construction time — `gisl().files(...)` wires
+     * it; a directly-constructed `FilesRecipe` throws {@link GislConfigError}.
+     * Mirrors the single-file {@link Recipe.run}; see {@link submit} for the
+     * fire-and-forget arm.
+     */
+    run(options?: {
+        maxWait?: string | number;
+        onProgress?: (event: ProgressEvent) => void;
+        signal?: AbortSignal;
+        pollIntervalMs?: number;
+    }): Promise<RunResult>;
+    /**
+     * Fire-and-forget the fan-out: upload every input, create ONE multi-job
+     * workflow (wiring `webhook` into `callback_url` when given), and return a
+     * client-bound {@link Handle}. Does NOT wait for terminal status — call
+     * `handle.wait()` / `handle.result()` later to collect the partitioned
+     * {@link RunResult}. The Handle detects the fan-out from the wire `file-{i}`
+     * job refs, so per-file `byKey()` works even after a `client.workflow(id)`
+     * reattach (the keys are the input indices `"0"`, `"1"`, …).
+     *
+     * Requires a client bound at construction time (same `no_client` guard as
+     * {@link run}). `webhook` is OPTIONAL. Fire-and-forget, so NO whole-run
+     * deadline (a multi-GB upload is bounded by the HTTP client's own timeout).
+     * Mirrors the single-file {@link Recipe.submit}.
+     *
+     * @param webhook Absolute callback URL the server POSTs lifecycle events to.
+     */
+    submit(webhook?: string): Promise<Handle>;
+    /**
+     * Upload every input (verbatim for a pre-uploaded id; uploading a path /
+     * blob otherwise, emitting `{phase:'upload'}` progress) then create ONE
+     * multi-job workflow (one job per input, `callback_url` built in when
+     * `webhook` is given). Shared first half of {@link run} + {@link submit}.
+     *
+     * Uploads are sequential so progress events stay ordered and the abort
+     * signal is honoured promptly; a resource arm is impossible in TS (Blob).
+     * `run()` passes a whole-run deadline (a slow upload must not proceed to
+     * createWorkflow past maxWait); `submit()` passes `undefined`, so the
+     * deadline checks are skipped.
+     */
+    private _uploadAllAndCreate;
+    /**
+     * The shared single-file {@link Recipe} that captures the op chain (input is
+     * a placeholder — only the steps are read). Reuses Recipe's op-chain
+     * validation + coercion so a `FilesRecipe.compress(bad)` throws the identical
+     * `GislConfigError` as `Recipe.compress(bad)`.
+     */
+    private baseRecipe;
+    private withStep;
+}
+export {};