@giveitsmaller/sdk 0.18.0 → 0.20.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';
@@ -57,6 +57,34 @@ export interface OutputFile {
     readonly filename: string;
     readonly sizeBytes: number;
     readonly operation: string;
+    /**
+     * For a `target_size` encode: the quality the encode-measure loop settled
+     * on. Projected from the generated {@link OperationDownload.chosenQuality};
+     * undefined (omitted) for non-target-size outputs. Pairs with
+     * {@link targetSizeMet}.
+     */
+    readonly chosenQuality?: number;
+    /**
+     * For a `target_size` encode: whether the output landed at or under the
+     * requested byte target. `false` is an honest best-effort outcome (target
+     * unreachable at min quality), NOT a failure. Projected from the generated
+     * {@link OperationDownload.targetSizeMet}; undefined for non-target-size
+     * 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
@@ -101,6 +129,10 @@ export interface Manifest {
  *  - `ok`: true iff `failed` is empty. (A boolean — the partition lists are
  *    `succeeded`/`failed`; resolves the design doc's `ok` bool-vs-list
  *    contradiction.)
+ *  - `targetSizeMissed`: derived target-size signal — undefined when no output
+ *    reports a target-size outcome (not a target_size run); otherwise true iff
+ *    some artifact has `targetSizeMet === false`. Omitted from the JSON when
+ *    undefined so non-target-size runs keep the common-case shape.
  *  - `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
@@ -117,6 +149,14 @@ export declare class RunResult {
     readonly url?: string;
     /** True iff {@link failed} is empty. */
     readonly ok: boolean;
+    /**
+     * Whether any output missed its requested byte target. Derived from the
+     * per-output {@link OutputFile.targetSizeMet}: undefined when NO artifact
+     * reports a target-size outcome (every `targetSizeMet` undefined — not a
+     * target_size run); otherwise true iff some artifact has
+     * `targetSizeMet === false`.
+     */
+    readonly targetSizeMissed?: 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
@@ -143,16 +183,18 @@ export declare class RunResult {
         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()`.
+     * Plain-object projection. Field ORDER (workflowId, state, ok,
+     * targetSizeMissed?, url?, artifacts, succeeded, failed) is fixed to match
+     * the PHP `toArray()` reference so JSON-string parity holds (FF1 shape
+     * assertion + FF2b harness fixture). `targetSizeMissed` + `url` are 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;
+        targetSizeMissed?: boolean;
         url?: string;
         artifacts: readonly OutputFile[];
         succeeded: readonly {
@@ -295,7 +337,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>>;
 }
 /**
@@ -349,6 +391,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
@@ -385,7 +440,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).
      */
@@ -437,6 +493,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;
@@ -536,6 +594,14 @@ export declare const WATERMARK_CAPABILITY: {
             readonly mimes: readonly ["image/gif"];
             readonly availability: "planned";
         };
+        readonly image_tiff: {
+            readonly mimes: readonly ["image/tiff"];
+            readonly availability: "stable";
+        };
+        readonly image_bmp: {
+            readonly mimes: readonly ["image/bmp"];
+            readonly availability: "stable";
+        };
     };
     readonly video_watermark: {
         readonly video: {
@@ -588,6 +654,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;
     /**
@@ -644,6 +712,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;
@@ -724,6 +794,8 @@ 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
@@ -751,6 +823,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;
@@ -850,6 +924,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;
@@ -907,6 +983,8 @@ 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
@@ -930,6 +1008,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;
@@ -968,4 +1048,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 {};