@giveitsmaller/sdk 0.8.0 → 0.9.0

package/dist/_audit.js

@@ -129,7 +129,12 @@ export function _runAudit() {
     accept();
     accept();
     accept();
+    // FF3a / u0hBt6fl — homogeneous fan-out builder surface.
     accept();
     accept();
     accept();
+    accept();
+    // FF5a / Ao8RPVxD — file-first Handle reattach surface.
+    accept();
+    accept();
 }

package/dist/builder.d.ts

@@ -26,6 +26,7 @@
  */
 import type { GislClient } from './client.js';
 import type { OperationDownload, WorkflowStatusResponse, SseOperationProgressDataStatusEnum } from '@giveitsmaller/contracts/openapi';
+import { Handle } from './handle.js';
 import type { PresetDefaults, PresetMedia } from './ergonomic/presets/index.js';
 /**
  * Best-effort detection of the compress-operation media from the
@@ -183,14 +184,6 @@ export interface Result {
      */
     readonly resolvedOptions: ResolvedOptions;
 }
-/**
- * Lighter return value from `.submit({webhook})` — no SSE/poll wait,
- * caller reconciles completion via the webhook.
- */
-export interface Handle {
-    readonly workflowId: string;
-    readonly webhookSecret?: string;
-}
 /**
  * Upload-phase progress event. The byte counter comes from
  * `UploadOptions.onProgress` — there is no `phase` field on the wire.

package/dist/builder.js

@@ -27,6 +27,10 @@
 import { SseEventType, SseOperationProgressDataFromJSON, } from '@giveitsmaller/contracts/openapi';
 import { uploadSource } from './types.js';
 import { GislTimeoutError } from './errors.js';
+// Deferred-usage-only import: `Handle` is constructed inside submit() at call
+// time, not at module load, so the builder.ts <-> handle.ts cycle is safe
+// under ESM (handle.ts imports the await-primitives from this module).
+import { Handle } from './handle.js';
 import { resolveCompressOptions, } from './ergonomic/preset_resolver.js';
 /**
  * Best-effort detection of the compress-operation media from the
@@ -264,11 +268,9 @@ export class OperationBuilder {
             callback_url: options.webhook,
         };
         const created = await this.client.createWorkflow(payload);
-        const handle = {
-            workflowId: created.workflowId,
-            ...(created.webhookSecret != null ? { webhookSecret: created.webhookSecret } : {}),
-        };
-        return handle;
+        // No client passed → the returned Handle's status()/wait()/result()
+        // throw `no_client`; the operation-first submit reconciles via webhook.
+        return new Handle(created.workflowId, created.webhookSecret != null ? created.webhookSecret : undefined);
     }
     /**
      * Fan-out chain: run this builder to completion, then for each artifact

package/dist/errors.d.ts

@@ -348,6 +348,22 @@ export declare class GislMultipartPartCountError extends GislError {
 export declare class GislNoSuchKeyError extends GislError {
     constructor(message: string);
 }
+/**
+ * Thrown by the file-first `Handle.result()` (FF5a) when the workflow has not
+ * yet reached a terminal state. `result()` is the NON-blocking accessor: it
+ * fetches the current status once and, if the workflow is still
+ * `pending`/`in_progress`, throws this rather than waiting. Use `Handle.wait()`
+ * to block until terminal instead.
+ *
+ * Carries the `workflowId` and the current (non-terminal) `state`.
+ *
+ * Mirrors the PHP `Gisl\Sdk\Errors\GislResultNotReadyError`.
+ */
+export declare class GislResultNotReadyError extends GislError {
+    readonly workflowId: string;
+    readonly state: string;
+    constructor(workflowId: string, state: string);
+}
 /** Machine-readable cause carried by {@link GislSinkError}. */
 export type GislSinkErrorReason = 'not_single_output' | 'downloader_unavailable' | 'partial_failure' | 'duplicate_filename' | 'invalid_directory' | 'write_failed';
 /**

package/dist/errors.js

@@ -387,6 +387,28 @@ export class GislNoSuchKeyError extends GislError {
         this.name = 'GislNoSuchKeyError';
     }
 }
+/**
+ * Thrown by the file-first `Handle.result()` (FF5a) when the workflow has not
+ * yet reached a terminal state. `result()` is the NON-blocking accessor: it
+ * fetches the current status once and, if the workflow is still
+ * `pending`/`in_progress`, throws this rather than waiting. Use `Handle.wait()`
+ * to block until terminal instead.
+ *
+ * Carries the `workflowId` and the current (non-terminal) `state`.
+ *
+ * Mirrors the PHP `Gisl\Sdk\Errors\GislResultNotReadyError`.
+ */
+export class GislResultNotReadyError extends GislError {
+    workflowId;
+    state;
+    constructor(workflowId, state) {
+        super(`Workflow ${workflowId} is not ready (state '${state}'); its result is not available yet. ` +
+            'Call wait() to block until it reaches a terminal state, or poll result() again later.');
+        this.name = 'GislResultNotReadyError';
+        this.workflowId = workflowId;
+        this.state = state;
+    }
+}
 /**
  * Thrown by the file-first `RunResult` sinks (`toFile()` / `downloadTo()`,
  * FF1) when they cannot deliver. The machine-readable `reason` discriminates

package/dist/file-first.d.ts

@@ -11,9 +11,11 @@
  */
 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.
@@ -160,6 +162,68 @@ export declare class RunResult {
     };
     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
@@ -250,15 +314,25 @@ export declare class Recipe {
      * `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.
+     * 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): WorkflowCreatePayload;
+    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
@@ -276,9 +350,154 @@ export declare class Recipe {
         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 {};