@giveitsmaller/sdk 0.19.0 → 0.21.0

package/dist/file-first.d.ts

@@ -13,7 +13,7 @@ import { GislItemFailedError } from './errors.js';
 import { type ProgressEvent } from './builder.js';
 import type { GislClient } from './client.js';
 import type { OperationDownload, WorkflowStatusResponse } from '@giveitsmaller/contracts/openapi';
-import type { ConvertOptions, ThumbnailOptions, TextWatermarkOptions, WatermarkOptions, OutputOptions, OutputFit } from './ergonomic/option_types.js';
+import type { ConvertOptions, ThumbnailOptions, TransformOptions, TextWatermarkOptions, WatermarkOptions, OutputOptions, OutputFit } from './ergonomic/option_types.js';
 import { OptimizeFor } from './generated/sdk_spec/enums.js';
 import type { PresetDefaults } from './ergonomic/presets/index.js';
 import type { WorkflowCreatePayload } from './types.js';
@@ -72,6 +72,19 @@ export interface OutputFile {
      * outputs.
      */
     readonly targetSizeMet?: boolean;
+    /**
+     * The measured perceptual quality of an `auto_quality` encode (0-1). Projected
+     * from the generated {@link OperationDownload.measuredQuality}; undefined
+     * (omitted) when the worker reported no measurement. Pairs with
+     * {@link qualityMetric}, which names the metric it was measured on.
+     */
+    readonly measuredQuality?: number;
+    /**
+     * The metric {@link measuredQuality} was measured on (e.g. `ssimulacra2`).
+     * Projected from the generated {@link OperationDownload.qualityMetric};
+     * undefined when no measurement was reported.
+     */
+    readonly qualityMetric?: string;
 }
 /**
  * One succeeded entry in {@link RunResult.succeeded}: a single input's
@@ -243,10 +256,43 @@ export declare function projectMultiJobToRunResult(workflowId: string, finalStat
  * @internal Exported for the file-first `Handle`; not part of the public API.
  */
 export declare function isFanoutStatus(finalStatus: WorkflowStatusResponse): boolean;
+/**
+ * Job id/ref for the DOWNSTREAM job that carries post-`sole_op` steps. A
+ * `sole_op` op (image_watermark / video_watermark / merge — ADR-0025) MUST be
+ * the only op in its job, so when a caller chains `compress()` / `convert()` /
+ * `thumbnail()` / `transform()` after `watermark()` / `merge()`, those steps
+ * lower into this separate job that consumes the sole_op output via
+ * `job_output` (the server derives the DAG from the `from` reference — no
+ * explicit `workflow_edges` needed). When present it is the TERMINAL deliverable,
+ * so `run()` / the {@link Handle} project THIS job's output, and the status-shape
+ * detectors accept it alongside the sole_op + `src_{i}` refs. PIiUit28.
+ */
+export declare const _POST_STEP_JOB_REF = "post";
+/**
+ * Job id/ref for the UPSTREAM job carrying any steps that PRECEDE a single-input
+ * `sole_op` op (e.g. `.compress().textWatermark()`): the pre-steps run in this
+ * job, the `sole_op` job then consumes its output via `job_output`. Distinct
+ * from the multi-input `src_{i}` fan-in refs. IQc01rj0.
+ */
+export declare const _PRE_STEP_JOB_REF = "pre";
+/**
+ * Wire op types the API marks `sole_op` (ADR-0025) — the op MUST be the ONLY op
+ * in its job. Mirrors `operation-capabilities.json` `operations.<op>.sole_op`,
+ * inlined as a browser-safe const (the raw-JSON sidecar subpath is Node-only)
+ * and PINNED to that projection by `sole-op-conformance.test.ts` — a contract
+ * regen that flips an op's `sole_op` fails there. The single-input
+ * {@link Recipe.toWorkflowPayload} reads THIS set to split a chain at every
+ * sole_op boundary into a `job_output`-linked job chain (so
+ * `.textWatermark('x').compress()` lowers to a valid DAG, not a contract-invalid
+ * co-bundled job). Mirrored by PHP `Recipe::SOLE_OP_TYPES`. IQc01rj0.
+ * @internal
+ */
+export declare const SOLE_OP_TYPES: ReadonlySet<string>;
 /**
  * True when a terminal status describes a fluent `files([...]).merge(...)`
  * combine — at least one job ref `merge` and every OTHER job ref is `src_{i}`
- * (the ids the {@link MergedRecipe} lowering assigns). The data-driven seam that
+ * or the downstream `post` job (the ids the {@link MergedRecipe} lowering
+ * assigns; `post` carries any post-combine steps). The data-driven seam that
  * lets {@link Handle.wait}/{@link Handle.result} project ONLY the merged output
  * — filtering the `src_*` passthrough plumbing — even after a
  * `client.workflow(id)` reattach (no construction-time marker), matching
@@ -269,9 +315,10 @@ export declare function isMergeStatus(finalStatus: WorkflowStatusResponse): bool
 export declare function isArchiveStatus(finalStatus: WorkflowStatusResponse): boolean;
 /**
  * True when a terminal status describes a fluent `file(...).watermark(overlay)`
- * — at least one job ref `watermark` and every OTHER job ref is `src_{i}` (the
- * ids the {@link WatermarkedRecipe} lowering assigns: `src_0` base, `src_1`
- * overlay). Lets {@link Handle.wait}/{@link Handle.result} AND
+ * — at least one job ref `watermark` and every OTHER job ref is `src_{i}` or
+ * the downstream `post` job (the ids the {@link WatermarkedRecipe} lowering
+ * assigns: `src_0` base, `src_1` overlay, `post` any post-watermark steps).
+ * Lets {@link Handle.wait}/{@link Handle.result} AND
  * {@link WatermarkedRecipe.run} project ONLY the watermark output — filtering
  * the `src_*` passthrough plumbing — even after a `client.workflow(id)` reattach.
  * Mutually exclusive with {@link isFanoutStatus} / {@link isMergeStatus} /
@@ -280,6 +327,28 @@ export declare function isArchiveStatus(finalStatus: WorkflowStatusResponse): bo
  * @internal Exported for the file-first `Handle`; not part of the public API.
  */
 export declare function isWatermarkStatus(finalStatus: WorkflowStatusResponse): boolean;
+/**
+ * True when a terminal status describes a SINGLE-INPUT `sole_op` chain — e.g.
+ * `.textWatermark('x').compress()` lowered to a `text_watermark` job + a
+ * downstream `post` job (and an optional upstream `pre` job for steps before the
+ * sole_op). Every job ref is a `sole_op` wire type ({@link SOLE_OP_TYPES}) or the
+ * `pre`/`post` chain refs, with NO `src_{i}` fan-in ref (which distinguishes it
+ * from the multi-input merge/watermark/archive DAGs). Lets a submitted/reattached
+ * {@link Handle} project ONLY the terminal deliverable — filtering the
+ * intermediate sole_op artifact — without builder state. IQc01rj0.
+ *
+ * @internal Exported for the file-first `Handle`; not part of the public API.
+ */
+export declare function isSoleOpChainStatus(finalStatus: WorkflowStatusResponse): boolean;
+/**
+ * The terminal deliverable ref for a single-input `sole_op` chain status: the
+ * downstream `post` job when present, else the `sole_op` job itself (the ref in
+ * {@link SOLE_OP_TYPES}). Mirrors how the merge/watermark paths pick their
+ * terminal via {@link terminalOutputRef} in `handle.ts`. IQc01rj0.
+ *
+ * @internal
+ */
+export declare function soleOpChainDeliverableRef(finalStatus: WorkflowStatusResponse): string;
 /**
  * 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
@@ -324,7 +393,7 @@ export declare const fileInput: {
 };
 /** One step in a {@link Recipe}'s chain — an op kind + captured ergonomic args. */
 interface RecipeStep {
-    readonly opType: 'compress' | 'convert' | 'thumbnail' | 'text_watermark' | 'output';
+    readonly opType: 'compress' | 'convert' | 'thumbnail' | 'text_watermark' | 'output' | 'transform';
     readonly options: Readonly<Record<string, unknown>>;
 }
 /**
@@ -378,6 +447,19 @@ export declare class Recipe {
      * dropped from the wire options (not sent as `undefined`).
      */
     thumbnail(options: ThumbnailOptions): Recipe;
+    /**
+     * Geometric transform: rotate (0/90/180/270°) and/or flip. Chainable — the
+     * canonical single-job order is `transform → convert → compress → thumbnail`,
+     * so downstream size options refer to the final (post-transform) frame.
+     *
+     * Passthrough: `rotate`/`flip` are forwarded as-is; the SDK does NOT narrow
+     * per media (a `flip` on a PDF input passes SDK validation but the server
+     * rejects it — documents rotate only). The transform op is `availability:
+     * planned` today, so workflow-create returns `feature_not_available` (422)
+     * until the per-media Lambdas ship. A no-op (`rotate:0` + `flip:none`) is
+     * rejected server-side as `invalid_options`.
+     */
+    transform(options?: TransformOptions): Recipe;
     /**
      * Produce ONE transformed image: keep or change format, plus quality, resize
      * and route-honored controls. The single user-facing image transform — the SDK
@@ -414,7 +496,8 @@ export declare class Recipe {
      * (beta). Audio/document/animated-GIF/unsupported-subtype/undetectable bases
      * throw locally BEFORE any upload (the planned-op gate). `options` carries the
      * wire watermark options (`anchor`, `opacity`, `margin_x`, `margin_y`,
-     * `overlay_width`). Returns a {@link WatermarkedRecipe} (chain post-watermark
+     * `overlay_width`, or `overlays[]` for the multi-overlay stack). Returns a
+     * {@link WatermarkedRecipe} (chain post-watermark
      * `compress`/`convert`/`thumbnail`, then `run`/`submit`). Distinct from
      * {@link textWatermark} (single-input text overlay).
      */
@@ -434,6 +517,15 @@ export declare class Recipe {
      *   fixed id). Not part of the caller-facing fluent surface.
      */
     toWorkflowPayload(fileId: string, callbackUrl?: string): WorkflowCreatePayload;
+    /**
+     * Trigger the per-step lowering purely for its validation side effects
+     * (route honoring, planned / out-of-enum values, `media_unknown`), discarding
+     * the result. Called BEFORE uploading bytes so a route-invalid recipe fails
+     * fast instead of after the upload is spent — parity with PHP
+     * `assertOperationsLowerable`. Lowering reads only `steps` + the input token,
+     * not the upload id, so this is a faithful preflight (0azjb6Rg).
+     */
+    private assertOperationsLowerable;
     /** The result-addressing key passed to `file()`, or undefined. */
     key(): string | undefined;
     /** The number of operations chained so far (introspection / tests). */
@@ -466,6 +558,8 @@ export declare class Recipe {
         maxWait?: string | number;
         onProgress?: (event: ProgressEvent) => void;
         signal?: AbortSignal;
+        /** Force the poll fallback instead of attempting SSE. Default true (SSE-first, poll fallback). */
+        useSSE?: boolean;
         pollIntervalMs?: number;
         probeBeforeCreate?: boolean;
         probeTimeoutMs?: number;
@@ -625,6 +719,8 @@ export declare class FilesRecipe {
     convert(format: string, options?: ConvertOptions): FilesRecipe;
     /** Generate a preview of every input. `width` AND `height` are required; validated via the base {@link Recipe} before any upload. */
     thumbnail(options: ThumbnailOptions): FilesRecipe;
+    /** Apply the same geometric transform (rotate/flip) to every input. Validated via the base {@link Recipe}. */
+    transform(options?: TransformOptions): FilesRecipe;
     /** Apply the same text watermark to every input. Option keys validated via the base {@link Recipe}. */
     textWatermark(text: string, options?: TextWatermarkOptions): FilesRecipe;
     /**
@@ -681,6 +777,8 @@ export declare class FilesRecipe {
         maxWait?: string | number;
         onProgress?: (event: ProgressEvent) => void;
         signal?: AbortSignal;
+        /** Force the poll fallback instead of attempting SSE. Default true (SSE-first, poll fallback). */
+        useSSE?: boolean;
         pollIntervalMs?: number;
         probeBeforeCreate?: boolean;
         probeTimeoutMs?: number;
@@ -738,9 +836,10 @@ export declare class FilesRecipe {
  *
  * **Lowering (one workflow):** each input is uploaded once and wrapped in its
  * own single-input `passthrough` source job (`src_N`); the `merge` job consumes
- * those via `job_output` inputs (array order = play order) and carries the merge
- * op FIRST in its `operations[]`, followed by any post-combine ops (compress /
- * convert / thumbnail) so they run on the merged output in the same job. The
+ * those via `job_output` inputs (array order = play order). `merge` is
+ * `sole_op` (ADR-0025), so it is the ONLY op in its job; any post-combine ops
+ * (compress / convert / thumbnail / transform) lower into a downstream `post`
+ * job that consumes the merged output via `job_output`. The
  * merge-level wire options reuse {@link wireMergeOptions} so a fluent merge
  * lowers identically to the operation-first `client.merge()`.
  *
@@ -761,11 +860,13 @@ export declare class MergedRecipe {
     convert(format: string, options?: ConvertOptions): MergedRecipe;
     /** Thumbnail the merged output. `width` AND `height` are required; validated pre-upload. */
     thumbnail(options: ThumbnailOptions): MergedRecipe;
+    /** Geometric transform (rotate/flip) of the merged output. Passthrough; see {@link Recipe.transform}. */
+    transform(options?: TransformOptions): MergedRecipe;
     /**
      * Lower to the merge DAG: one `passthrough` source job per input + one
-     * `merge` job whose `operations[]` is `[merge, ...post-combine ops]`. The
-     * merge job's `inputs[]` consume the source jobs via `job_output` in input
-     * (play) order.
+     * `merge` job whose `operations[]` is exactly `[merge]` (sole_op). The merge
+     * job's `inputs[]` consume the source jobs via `job_output` in input (play)
+     * order; any post-combine ops lower into a downstream `post` job.
      *
      * @internal Consumed by {@link run} (after uploading all inputs), {@link submit}
      *   (with a webhook), and the cross-language parity harness (with fixed ids).
@@ -788,6 +889,8 @@ export declare class MergedRecipe {
         maxWait?: string | number;
         onProgress?: (event: ProgressEvent) => void;
         signal?: AbortSignal;
+        /** Force the poll fallback instead of attempting SSE. Default true (SSE-first, poll fallback). */
+        useSSE?: boolean;
         pollIntervalMs?: number;
         probeBeforeCreate?: boolean;
         probeTimeoutMs?: number;
@@ -887,6 +990,8 @@ export declare class ArchivedRecipe {
         maxWait?: string | number;
         onProgress?: (event: ProgressEvent) => void;
         signal?: AbortSignal;
+        /** Force the poll fallback instead of attempting SSE. Default true (SSE-first, poll fallback). */
+        useSSE?: boolean;
         pollIntervalMs?: number;
         probeBeforeCreate?: boolean;
         probeTimeoutMs?: number;
@@ -925,7 +1030,8 @@ export declare class ArchivedRecipe {
  * `passthrough` source job (`src_0` base, `src_1` overlay; their own preceding
  * steps lower into those jobs), and the `watermark` job consumes them via
  * `job_output` inputs tagged `role: base` / `role: overlay`. Post-watermark
- * `compress`/`convert`/`thumbnail` chain onto the watermark output. Mirrors
+ * `compress`/`convert`/`thumbnail`/`transform` steps lower into a downstream
+ * `post` job on the watermark output (`image_watermark` is `sole_op`). Mirrors
  * {@link MergedRecipe}. `textWatermark` is intentionally NOT a post-verb here.
  */
 export declare class WatermarkedRecipe {
@@ -944,11 +1050,14 @@ export declare class WatermarkedRecipe {
     convert(format: string, options?: ConvertOptions): WatermarkedRecipe;
     /** Thumbnail the watermarked output. `width` AND `height` are required; validated pre-upload. */
     thumbnail(options: ThumbnailOptions): WatermarkedRecipe;
+    /** Geometric transform (rotate/flip) of the watermarked output. Passthrough; see {@link Recipe.transform}. */
+    transform(options?: TransformOptions): WatermarkedRecipe;
     /**
      * Lower to the watermark DAG: a `src_0` passthrough/base-steps job + a `src_1`
      * passthrough/overlay-steps job + one `watermark` job whose `inputs[]` consume
-     * them via `job_output` (role base/overlay) and whose `operations[]` is
-     * `[image_watermark|video_watermark, ...post-watermark ops]`. `fileIds` is
+     * them via `job_output` (role base/overlay). The watermark op is `sole_op`
+     * (ADR-0025), so `operations[]` is exactly `[image_watermark|video_watermark]`;
+     * any post-watermark ops lower into a downstream `post` job. `fileIds` is
      * `[baseId, overlayId]` (upload order). Throws pre-lowering if the base media
      * is undetectable/unsupported (the planned-op gate).
      *
@@ -967,6 +1076,8 @@ export declare class WatermarkedRecipe {
         maxWait?: string | number;
         onProgress?: (event: ProgressEvent) => void;
         signal?: AbortSignal;
+        /** Force the poll fallback instead of attempting SSE. Default true (SSE-first, poll fallback). */
+        useSSE?: boolean;
         pollIntervalMs?: number;
         probeBeforeCreate?: boolean;
         probeTimeoutMs?: number;
@@ -1005,4 +1116,111 @@ export declare class WatermarkedRecipe {
     private lowerPostSteps;
     private withStep;
 }
+/**
+ * The keyed multi-recipe batch builder (FF7 / MFaCjL8d). `client.batch([r1, r2, …])`
+ * runs N DISTINCT single-input keyed {@link Recipe}s as ONE workflow; the
+ * partitioned {@link RunResult} addresses each entry's outputs by the caller key
+ * given at `client.file(input, key)` time (`res.byKey('hero')`), and one failed
+ * entry lands in `failed` without sinking the rest.
+ *
+ * **v1 scope (locked):** `.run()` only (no `submit()` / reattach — a follow-up);
+ * single-input {@link Recipe} entries only — the multi-input builders
+ * ({@link FilesRecipe}, {@link MergedRecipe}, {@link WatermarkedRecipe},
+ * {@link ArchivedRecipe}) are REJECTED pre-upload. Cross-entry upload dedupe
+ * IS applied (1LwSJcz1): two entries sourcing the SAME input (by
+ * {@link inputIdentity}) upload ONCE and share the resulting fileId —
+ * correctness-neutral (same bytes → same per-job output), it only elides
+ * redundant uploads. Observable caveat: `onProgress` upload-phase events drop
+ * to one-per-UNIQUE input rather than one-per-entry.
+ *
+ * **Lowering (one workflow):** for each entry `i`, lower its single job via
+ * {@link Recipe.toWorkflowPayload} and re-id it `b{i}` — a POSITIONAL namespace
+ * DISTINCT from the fan-out `file-{i}` / merge-archive-watermark `src_{i}` refs so
+ * a future reattach can't misdetect the wire as a fan-out / merge. `keyByRef`
+ * maps each `b{i}` ref to that entry's caller key, so
+ * {@link projectMultiJobToRunResult} partitions per entry (1 job ↔ 1 key:
+ * `completed` → `succeeded`, else → `failed` with a {@link GislItemFailedError}).
+ *
+ * **Immutability:** the ctor is CLIENT-ONLY (the ordered entries + the client) —
+ * entries are already-built Recipes that captured their own preset defaults at
+ * `client.file(...)` time, so batch never re-plumbs
+ * presetDefaults/scopedPresetDefaults. Mirrors the PHP `BatchRecipe`.
+ */
+export declare class BatchRecipe {
+    private readonly client?;
+    private readonly recipes;
+    constructor(recipes: ReadonlyArray<Recipe>, client?: GislClient | undefined);
+    /**
+     * Execute the batch end-to-end: validate + lowering-preflight EVERY entry
+     * BEFORE any upload, upload each entry's input, create ONE multi-job workflow
+     * (one `b{i}` job per entry), await a terminal state (SSE with poll fallback,
+     * honouring `useSSE`), then partition the per-job downloads into a keyed
+     * {@link RunResult}. `partially_failed` is a NORMAL terminal state here — the
+     * completed entries land in `succeeded`, the rest in `failed`.
+     *
+     * Requires a client bound at construction time — `gisl().batch([...])` wires
+     * it; a directly-constructed {@link BatchRecipe} (e.g. a lowering-only test)
+     * throws {@link GislConfigError}. Mirrors the fan-out {@link FilesRecipe.run}.
+     */
+    run(options?: {
+        maxWait?: string | number;
+        onProgress?: (event: ProgressEvent) => void;
+        signal?: AbortSignal;
+        /** Force the poll fallback instead of attempting SSE. Default true (SSE-first, poll fallback). */
+        useSSE?: boolean;
+        pollIntervalMs?: number;
+        probeBeforeCreate?: boolean;
+        probeTimeoutMs?: number;
+    }): Promise<RunResult>;
+    /**
+     * Lower the batch to ONE multi-job workflow-create payload against a list of
+     * resolved upload ids (one per entry, in entry order). Each entry `i` becomes
+     * ONE job re-id'd `b{i}` carrying that entry's lowered `source` + `operations`.
+     * Composes the single-file {@link Recipe.toWorkflowPayload} per entry so each
+     * keeps its own media-hint + preset resolution and lowering logic is not
+     * duplicated. `callback_url` is built in ONLY when a webhook is supplied
+     * (batch v1 run() supplies none, so it is omitted).
+     *
+     * @internal Consumed by {@link run} (after uploading) and the cross-language
+     *   golden-payload lowering test (with fixed ids). Not caller-facing.
+     */
+    toWorkflowPayload(fileIds: readonly string[], callbackUrl?: string): WorkflowCreatePayload;
+    /** The number of recipe entries in this batch (introspection / tests). */
+    get recipeCount(): number;
+    /**
+     * Validate the batch AND lowering-preflight every entry BEFORE any upload
+     * fires — an invalid entry costs no bandwidth. TWO PASSES (mirrors PHP
+     * `BatchRecipe`'s structural-loop-then-preflight-loop), throwing
+     * {@link GislConfigError}:
+     *  0. empty batch → `no_recipes` (checked first).
+     *  PASS 1 (structural, ALL entries in order):
+     *    - a KNOWN multi-input builder (checked FIRST — they do NOT extend
+     *      {@link Recipe}, so the not-a-Recipe catch-all would otherwise misreport
+     *      them as plain type errors) → `multi_input_recipe_unsupported`;
+     *    - a non-{@link Recipe} entry → `invalid_recipe`;
+     *    - a missing/empty key → `missing_key`;
+     *    - a duplicate key → `duplicate_key`.
+     *  PASS 2 (lowering preflight, ALL entries): lower each entry (via
+     *    {@link Recipe.toWorkflowPayload}) so an invalid lowering throws BEFORE any
+     *    upload, mirroring what {@link FilesRecipe} lowers pre-create.
+     *
+     * Two passes so a batch with MULTIPLE distinct violations throws the SAME
+     * reason regardless of entry order (a structural error anywhere wins over a
+     * lowering error elsewhere) — converging TS + PHP error reporting. The
+     * offending key/index rides the MESSAGE (not `conflictingFields`, which is
+     * reserved for wire FIELD names).
+     */
+    private validatePreUpload;
+    /**
+     * Collapse the entry inputs to a first-appearance-unique list for cross-entry
+     * upload dedupe: two entries sourcing the SAME input (by {@link inputIdentity})
+     * upload ONCE and share the fileId. Returns the ordered `uniqueInputs` plus an
+     * `entryToUnique` index map (length N, entry order) so {@link run} can expand
+     * the unique fileIds back to one-per-entry before {@link toWorkflowPayload} —
+     * keeping the b{i} refs + {@link keyByRef} N-length and correctness-neutral.
+     */
+    private planUploads;
+    /** Map each `b{i}` job ref to that entry's caller key (validated non-empty). */
+    private keyByRef;
+}
 export {};