@giveitsmaller/sdk 0.18.0 → 0.20.0

package/README.md

@@ -67,7 +67,7 @@ Docs are published in the [giveitsmaller-sdks](https://github.com/AntonioCS/give
 - **Webhooks** — [`docs/typescript/webhook.md`](https://github.com/AntonioCS/giveitsmaller-sdks/blob/main/docs/typescript/webhook.md)
 - **Errors & retry guidance** — [`docs/typescript/errors.md`](https://github.com/AntonioCS/giveitsmaller-sdks/blob/main/docs/typescript/errors.md)
 - **Troubleshooting** — [`docs/typescript/troubleshooting.md`](https://github.com/AntonioCS/giveitsmaller-sdks/blob/main/docs/typescript/troubleshooting.md)
-- **Examples** — compress, thumbnail, convert, merge, archive — [`docs/typescript/examples/`](https://github.com/AntonioCS/giveitsmaller-sdks/tree/main/docs/typescript/examples)
+- **Examples** — compress, thumbnail, convert, merge, archive, watermark, output — [`docs/typescript/examples/`](https://github.com/AntonioCS/giveitsmaller-sdks/tree/main/docs/typescript/examples)
 
 ## Contributing: the committed `dist/`
 

package/dist/_audit.js

@@ -139,6 +139,8 @@ export function _runAudit() {
     accept();
     // FF3a / u0hBt6fl — homogeneous fan-out builder surface.
     accept();
+    // FF7 / MFaCjL8d — keyed multi-recipe batch builder surface.
+    accept();
     // FF4a / Z7zTr789 — multi-input watermark recipe surface.
     accept();
     accept();
@@ -149,4 +151,14 @@ export function _runAudit() {
     // FF5a / Ao8RPVxD — file-first Handle reattach surface.
     accept();
     accept();
+    // TYNjcjpo — SSE parse-failure diagnostic surface.
+    accept();
+    // qUhxfDA5 — capabilities() projection surface + the three contract
+    // capability types it exposes.
+    accept();
+    accept();
+    accept();
+    accept();
+    // W8v4jWzx — error-taxonomy category union surfaced by GislApiError.category.
+    accept();
 }

package/dist/builder.d.ts

@@ -217,6 +217,7 @@ export interface UploadProgressEvent {
 export interface ProcessingProgressEvent {
     readonly phase: 'processing';
     readonly status?: SseOperationProgressDataStatusEnum;
+    /** Percent complete, `0-100` (the wire integer) — NOT a 0..1 fraction. */
     readonly progress: number;
     readonly jobRef: string;
     readonly operationId: string;

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 import type { AudioWatermarkDecodeRequest, AudioWatermarkDecodeResponse, ExternalImportCreatedResponse, ExternalImportRequest, LoginUserRequest, LoginUser200ResponseData, ContactRequest, AccountLimits, CreditsBalanceResponse, CreditsUsageResponse, UploadResponse, UploadProbeResponse, WorkflowCancelResponse, WorkflowCreateResponse, WorkflowResumeResponse, WorkflowStatusResponse, WorkflowListResponse, WorkflowSummary, WorkflowDownloadResponse, MetadataResponse, RetryResponse } from '@giveitsmaller/contracts/openapi';
-import type { CreditsUsageOptions, ListWorkflowsOptions, GetSchemaOptions, GetSchemaResult, GislClientConfig, GislSseEvent, PreflightClipsResult, ProbeWaitOptions, ProbeWaitResult, ReadCapabilityOptions, UploadOptions, WaitOptions, WorkflowCreatePayload, _Sdk3HandCodedKeepaliveResult, _Sdk3HandCodedMultipartStatusResult, _Sdk3HandCodedPresignPartsResult } from './types.js';
+import type { CreditsUsageOptions, ListWorkflowsOptions, GetSchemaOptions, GetSchemaResult, GislClientConfig, GislSseEvent, GislSseParseFailure, PreflightClipsResult, ProbeWaitOptions, ProbeWaitResult, ReadCapabilityOptions, UploadOptions, WaitOptions, WorkflowCreatePayload, _Sdk3HandCodedKeepaliveResult, _Sdk3HandCodedMultipartStatusResult, _Sdk3HandCodedPresignPartsResult } from './types.js';
 export declare const MULTIPART_CONCURRENCY_DEFAULT: 4;
 export declare const DEFAULT_MULTIPART_FIRST_CHUNK_SIZE: number;
 export interface ValidationDetail {
@@ -199,6 +199,13 @@ export declare class GislClient {
     streamEvents(workflowId: string, opts?: {
         signal?: AbortSignal;
         capability?: string;
+        /**
+         * Observe malformed-JSON SSE frames (TYNjcjpo). A frame whose `data:` body
+         * fails to parse is SKIPPED from the stream (kept resilient) and reported
+         * here as a typed {@link GislSseParseFailure} instead of being silently lost.
+         * Omit to drop malformed frames silently (the default; PHP parity).
+         */
+        onParseError?: (diagnostic: GislSseParseFailure) => void;
     }): Promise<AsyncGenerator<GislSseEvent>>;
     /**
      * Get metadata for an uploaded file.

package/dist/client.js

@@ -6,6 +6,10 @@
 import { open, stat, basename } from './node-fs.js';
 import { AudioWatermarkDecodeRequestToJSON, AudioWatermarkDecodeResponseFromJSON, ExternalImportCreatedResponseFromJSON, ExternalImportRequestToJSON, LoginUser200ResponseDataFromJSON, AccountLimitsFromJSON, CreditsBalanceResponseFromJSON, CreditsUsageResponseFromJSON, UploadResponseFromJSON, UploadProbeResponseFromJSON, MultipartInitiateResponseFromJSON, MultipartInitiateRequestMetadataHintToJSON, MultipartCompleteResponseFromJSON, MultipartCompleteRequestToJSON, WorkflowCancelResponseFromJSON, WorkflowCreateResponseFromJSON, WorkflowResumeResponseFromJSON, WorkflowStatusResponseFromJSON, WorkflowListResponseFromJSON, WorkflowDownloadResponseFromJSON, MetadataResponseFromJSON, OperationsSchemaResponseFromJSON, RetryResponseFromJSON, WorkflowStatus, AuthErrorResponseFromJSON, AuthErrorType, AuthRejectionEnvelopeFromJSON, AuthRejectionEnvelopeErrorTypeEnum, BalanceExhaustedResponseFromJSON, BalanceExhaustedResponseRequiredActionEnum, FeatureNotAvailableResponseFromJSON, FeatureTierRestrictedResponseFromJSON, TierRestrictionKind, TierRestrictionResponseFromJSON, UserTier, WorkflowExpiredResponseFromJSON, ProbePendingResponseFromJSON, UploadSizeExceedsTierResponseFromJSON, UploadDurationExceedsTierResponseFromJSON, UploadConstraintsAppliedProcessingClassPreAssignmentEnum, UploadThresholdsSingleShotMaxBytesEnum, UploadThresholdsMultipartChunkSizeEnum, UploadThresholdsMultipartConcurrencyDefaultEnum, } from '@giveitsmaller/contracts/openapi';
 import { GislAbortError, GislApiError, GislAuthError, GislAuthRejectionError, GislBalanceExhaustedError, GislError, GislFeatureNotAvailableError, GislFeatureTierRestrictedError, GislMultipartPartCountError, GislMultipartPartError, GislMultipartSessionNotFoundError, GislMultipartSessionOwnershipError, GislMultipartSessionAuthRequiredError, GislTierRestrictedError, GislTimeoutError, GislProbePendingError, GislUploadCapExceededError, GislValidationError, GislWorkflowExpiredError, } from './errors.js';
+// The `Retry-After` millisecond parser lives in the shared retry-metadata
+// module (extracted to break the client ↔ errors circular import); re-imported
+// here so the retry-loop timing stays byte-identical.
+import { parseRetryAfterMs } from './retry-metadata.js';
 import { parseSseStream } from './sse.js';
 const DEFAULT_TIMEOUT_MS = 30_000;
 // SDK-internal aliases derived from the contract-pinned UploadThresholds enums
@@ -109,12 +113,14 @@ function isAbortError(err) {
         typeof err === 'object' &&
         err.name === 'AbortError');
 }
-// Retryable S3 PUT response statuses: 429 throttling, 503 slow-down, and any
-// other 5xx (502/504 are common transients behind CloudFront/S3). 4xx other
-// than 429 (403 signed-URL expiry, 400 SignatureDoesNotMatch, etc.) are
-// configuration / authority issues — retrying just delays the real failure.
+// Retryable S3 PUT response statuses: 408 request timeout, 429 throttling, 503
+// slow-down, and any other 5xx (502/504 are common transients behind
+// CloudFront/S3). 408 is a transient timeout on the PUT itself, so it is retried
+// (matching the PHP SDK's S3-PUT predicate — qz7MjNTy cross-SDK alignment). Other
+// 4xx (403 signed-URL expiry, 400 SignatureDoesNotMatch, etc.) are configuration
+// / authority issues — retrying just delays the real failure.
 function isRetryableStatus(status) {
-    return status === 429 || (status >= 500 && status <= 599);
+    return status === 408 || status === 429 || (status >= 500 && status <= 599);
 }
 // fetch surfaces network failures (DNS, TLS, TCP reset, mid-body disconnect)
 // as TypeError. Abort surfaces as a DOMException with name='AbortError', not
@@ -123,31 +129,6 @@ function isRetryableStatus(status) {
 function isRetryableNetworkError(err) {
     return err instanceof TypeError;
 }
-// Parse an HTTP `Retry-After` header into milliseconds. Accepts the two RFC
-// 9110 forms: delta-seconds (e.g. "5") or an HTTP-date. Returns `undefined`
-// for an absent / unparseable / negative value (caller falls back to its own
-// backoff). A past HTTP-date clamps to 0.
-function parseRetryAfterMs(headerValue) {
-    if (headerValue === undefined)
-        return undefined;
-    const trimmed = headerValue.trim();
-    if (trimmed === '')
-        return undefined;
-    let ms;
-    if (/^\d+$/.test(trimmed)) {
-        ms = Number(trimmed) * 1000;
-    }
-    else {
-        const when = Date.parse(trimmed);
-        if (Number.isNaN(when))
-            return undefined;
-        ms = when - Date.now();
-    }
-    // A non-positive Retry-After (e.g. "0" or a past HTTP-date) must NOT short-
-    // circuit the backoff to zero — treat it as absent so the caller falls back
-    // to jitter and the loop can't busy-poll until timeout.
-    return ms > 0 ? ms : undefined;
-}
 // Cancellable sleep for poll loops. Resolves after `ms`, or rejects with
 // `GislAbortError` if `signal` aborts. Resolves immediately for ms <= 0.
 function cancellableSleep(ms, signal) {
@@ -493,6 +474,11 @@ export class GislClient {
                 messageKey: json.message_key,
                 locale: json.locale,
                 messageParams: json.message_params,
+                // The wire-stable machine code (SCREAMING_SNAKE `error`), surfaced as
+                // `error.errorCode` on every dispatched error (PHP parity). Threaded via
+                // this single options object → base GislApiError, GislValidationError,
+                // and every structured subclass (passed through as `extra`).
+                errorCode: typeof json.error === 'string' ? json.error : undefined,
                 responseHeaders,
                 contentLanguage,
             };
@@ -1747,7 +1733,10 @@ export class GislClient {
                 releaseConsumerSignal();
             }
         }
-        const inner = parseSseStream(response, { signal: controller.signal });
+        const inner = parseSseStream(response, {
+            signal: controller.signal,
+            ...(opts.onParseError !== undefined ? { onParseError: opts.onParseError } : {}),
+        });
         let started = false;
         let settled = false;
         // Idempotent teardown. `abort` only on consumer-driven early
@@ -1874,6 +1863,7 @@ export class GislClient {
         }
         if (!response.ok) {
             let errorMessage = 'Unknown error';
+            let errorCode;
             try {
                 const errJson = (await response.json());
                 // Prefer the human `message`; `error` is the machine code (x9Lbf6uy).
@@ -1881,13 +1871,18 @@ export class GislClient {
                     errorMessage = errJson.message;
                 else if (errJson.error)
                     errorMessage = errJson.error;
+                // Surface the machine code as errorCode too (parity with handleResponse
+                // + PHP), even when `message` supplied the human text.
+                if (typeof errJson.error === 'string')
+                    errorCode = errJson.error;
             }
             catch {
-                // Non-JSON body — keep generic message.
+                // Non-JSON body — keep generic message, no machine code.
             }
             // This throw is OUTSIDE handleResponse (rawResponse:true / 304 path), so
             // build the response-header surface from the in-scope `response` here.
             throw new GislApiError(response.status, errorMessage, path, undefined, {
+                errorCode,
                 responseHeaders: headersToRecord(response.headers),
                 contentLanguage: response.headers.get('content-language') ?? undefined,
             });

package/dist/ergonomic/image_output_routes.d.ts

@@ -12,11 +12,12 @@
  *
  * Each route cell lists the options the worker HONORS (live) and PLANS (advertised,
  * not yet honored — gated unavailable). Resize (`width`/`height`/`fit`) is
- * **INPUT-keyed**: it lives only on the `same_format[input]` cell but applies on
- * EITHER route, gated by input resizability (raster only — `svg` is vector and
- * carries no resize). So a `png → webp + resize` request reads its resize
- * capability from `same_format.png` and its transcoder options from
- * `format_change.webp`.
+ * **INPUT-gated**: since v2.103.0 convert is the resize engine, so the projection
+ * lists resize on every `format_change` cell too — but resizability is keyed to the
+ * INPUT (raster only — `svg` is vector and carries no resize). The lowering reads
+ * resize capability from `same_format[input]` on BOTH routes, so a `png → webp +
+ * resize` request resizes (png is raster) while an `svg → png + resize` request
+ * does NOT (svg's same_format cell has no resize keys).
  *
  * This hand table MIRRORS the generated projection and is PINNED to it by
  * `output-route-conformance.test.ts` (the watermark-capability-gate precedent) —

package/dist/ergonomic/image_output_routes.js

@@ -12,11 +12,12 @@
  *
  * Each route cell lists the options the worker HONORS (live) and PLANS (advertised,
  * not yet honored — gated unavailable). Resize (`width`/`height`/`fit`) is
- * **INPUT-keyed**: it lives only on the `same_format[input]` cell but applies on
- * EITHER route, gated by input resizability (raster only — `svg` is vector and
- * carries no resize). So a `png → webp + resize` request reads its resize
- * capability from `same_format.png` and its transcoder options from
- * `format_change.webp`.
+ * **INPUT-gated**: since v2.103.0 convert is the resize engine, so the projection
+ * lists resize on every `format_change` cell too — but resizability is keyed to the
+ * INPUT (raster only — `svg` is vector and carries no resize). The lowering reads
+ * resize capability from `same_format[input]` on BOTH routes, so a `png → webp +
+ * resize` request resizes (png is raster) while an `svg → png + resize` request
+ * does NOT (svg's same_format cell has no resize keys).
  *
  * This hand table MIRRORS the generated projection and is PINNED to it by
  * `output-route-conformance.test.ts` (the watermark-capability-gate precedent) —
@@ -28,6 +29,8 @@
 import { compressMetadata } from '@giveitsmaller/contracts/operations';
 /** The resize option keys — input-keyed, raster-only (see module doc). */
 export const RESIZE_KEYS = ['width', 'height', 'fit'];
+/** Set form of {@link RESIZE_KEYS} for `string`-keyed membership tests. */
+const RESIZE_KEY_SET = new Set(RESIZE_KEYS);
 /** Image area cap shared by every resizable route (projection `max_output_pixels`). */
 export const MAX_OUTPUT_PIXELS = 16_000_000;
 /**
@@ -61,21 +64,21 @@ const EXT_TOKEN = {
  */
 export const IMAGE_OUTPUT_ROUTES = {
     same_format: {
-        avif: { honored: ['avif_speed', 'fit', 'height', 'metadata', 'output_format', 'quality', 'width'], planned: [] },
-        gif: { honored: ['fit', 'height', 'metadata', 'output_format', 'quality', 'width'], planned: [] },
-        jpeg: { honored: ['fit', 'height', 'lossless', 'metadata', 'output_format', 'progressive', 'quality', 'width'], planned: [] },
-        png: { honored: ['fit', 'height', 'metadata', 'optimization_level', 'output_format', 'quality', 'width'], planned: ['lossy'] },
-        svg: { honored: ['metadata', 'output_format', 'quality'], planned: [] },
-        tiff: { honored: ['fit', 'height', 'metadata', 'output_format', 'quality', 'width'], planned: [] },
-        webp: { honored: ['fit', 'height', 'lossless', 'metadata', 'output_format', 'quality', 'width'], planned: [] },
+        avif: { honored: ['auto_orient', 'avif_speed', 'color_profile', 'encoding_mode', 'fit', 'height', 'metadata', 'output_format', 'quality', 'quality_preset', 'target_size_bytes', 'width'], planned: [] },
+        gif: { honored: ['auto_orient', 'color_profile', 'fit', 'height', 'metadata', 'output_format', 'quality', 'width'], planned: [] },
+        jpeg: { honored: ['auto_orient', 'chroma_subsampling', 'color_profile', 'encoding_mode', 'fit', 'height', 'lossless', 'metadata', 'output_format', 'progressive', 'quality', 'quality_preset', 'target_size_bytes', 'width'], planned: [] },
+        png: { honored: ['auto_orient', 'color_profile', 'fit', 'height', 'metadata', 'optimization_level', 'output_format', 'quality', 'width'], planned: [] },
+        svg: { honored: ['metadata', 'output_format'], planned: [] },
+        tiff: { honored: ['auto_orient', 'color_profile', 'fit', 'height', 'metadata', 'output_format', 'quality', 'width'], planned: [] },
+        webp: { honored: ['auto_orient', 'color_profile', 'encoding_mode', 'fit', 'height', 'lossless', 'metadata', 'output_format', 'quality', 'quality_preset', 'target_size_bytes', 'width'], planned: [] },
     },
     format_change: {
-        avif: { honored: ['output_format', 'quality'], planned: [] },
-        gif: { honored: ['output_format'], planned: [] },
-        jpeg: { honored: ['background', 'output_format', 'quality'], planned: [] },
-        png: { honored: ['output_format'], planned: [] },
-        tiff: { honored: ['output_format'], planned: [] },
-        webp: { honored: ['output_format', 'quality'], planned: [] },
+        avif: { honored: ['auto_orient', 'color_profile', 'fit', 'height', 'output_format', 'quality', 'width'], planned: ['metadata'] },
+        gif: { honored: ['auto_orient', 'color_profile', 'fit', 'height', 'output_format', 'width'], planned: ['metadata'] },
+        jpeg: { honored: ['auto_orient', 'background', 'color_profile', 'fit', 'height', 'output_format', 'quality', 'width'], planned: ['metadata'] },
+        png: { honored: ['auto_orient', 'color_profile', 'fit', 'height', 'output_format', 'width'], planned: ['metadata'] },
+        tiff: { honored: ['auto_orient', 'color_profile', 'fit', 'height', 'output_format', 'width'], planned: ['metadata'] },
+        webp: { honored: ['auto_orient', 'color_profile', 'fit', 'height', 'output_format', 'quality', 'width'], planned: ['metadata'] },
     },
 };
 /** The bare format token for a MIME type, or undefined if not a known image MIME. */
@@ -114,8 +117,13 @@ export function resolveOutputRoute(inputToken, outputFormat) {
     const cell = IMAGE_OUTPUT_ROUTES.format_change[outToken];
     if (cell === undefined)
         return undefined;
-    // Input-keyed resize: the format_change cell carries only transcoder options;
-    // resize capability comes from the INPUT's same_format cell (raster only).
+    // Resize is INPUT-gated. Since v2.103.0 convert is the resize engine, so the
+    // projection lists width/height/fit on EVERY format_change cell — but an SVG
+    // INPUT cannot be raster-resized (the convert worker rejects it). So strip the
+    // cell's resize keys and re-add only those the INPUT's same_format cell honors:
+    // raster inputs carry them, svg does not. The transcoder options (output_format/
+    // quality/background) ride the cell directly.
+    const transcoderHonored = cell.honored.filter((k) => !RESIZE_KEY_SET.has(k));
     const inCell = IMAGE_OUTPUT_ROUTES.same_format[inputToken];
     const resize = inCell ? RESIZE_KEYS.filter((k) => inCell.honored.includes(k)) : [];
     return {
@@ -123,7 +131,7 @@ export function resolveOutputRoute(inputToken, outputFormat) {
         sourceOp: 'convert',
         outputFormatWire: outToken,
         inputToken,
-        honored: new Set([...cell.honored, ...resize]),
+        honored: new Set([...transcoderHonored, ...resize]),
         planned: new Set(cell.planned),
     };
 }

package/dist/ergonomic/option_types.d.ts

@@ -29,8 +29,18 @@ export interface ConvertOptions {
     trim_end?: number;
     /** Output frame rate for video → GIF. */
     fps?: number;
-    /** Max output width in pixels (video → GIF downscale cap). */
+    /** Resize width in px. Image convert: resize-on-convert (1-16384, width*height ≤ 16MP, v2.103.0). Video → GIF: downscale cap. */
     width?: number;
+    /** Resize height in px for image convert (1-16384, v2.103.0). Omit for width-only / aspect-preserving resize. Not honored for SVG input. */
+    height?: number;
+    /** Resize mode for image convert (applies when width or height is set, v2.103.0). `max` never upscales. */
+    fit?: 'max' | 'crop' | 'scale';
+    /** Metadata policy for image convert (`strip` removes EXIF/IPTC/XMP, `keep` preserves). PLANNED on convert.image (v2.106.0). */
+    metadata?: 'strip' | 'keep';
+    /** ICC colour-profile handling for image convert (`keep`/`srgb`/`strip`). PLANNED on convert.image (v2.112.0). */
+    color_profile?: 'keep' | 'srgb' | 'strip';
+    /** Auto-rotate per EXIF orientation for image convert. STABLE since v2.120.0. */
+    auto_orient?: boolean;
     /** GIF palette size (2-256). */
     max_colors?: number;
     /** GIF loop count (0 infinite, N>0 N times, -1 once). */
@@ -55,6 +65,8 @@ export interface ThumbnailOptions {
     format?: 'jpg' | 'png' | 'webp';
     /** Output quality for lossy thumbnail formats (image input). */
     quality?: number;
+    /** Background fill colour (hex) for transparency flattened to JPG output (v2.118.0). */
+    background?: string;
     /** Frame timestamp for video input (e.g. '00:00:01'). */
     timestamp?: string;
     /** Document source: a printed page or the cover. */
@@ -62,6 +74,12 @@ export interface ThumbnailOptions {
     /** 1-based page index for document input. */
     page?: number;
 }
+export interface TransformOptions {
+    /** Clockwise rotation in degrees. document_pdf honors `rotate` only. */
+    rotate?: 0 | 90 | 180 | 270;
+    /** Mirror axis (applied after `rotate`). Not honored on document_pdf input. */
+    flip?: 'none' | 'horizontal' | 'vertical' | 'both';
+}
 export interface TextWatermarkOptions {
     /** Font size in pixels (8-512). */
     font_size?: number;
@@ -84,6 +102,24 @@ export interface TextWatermarkOptions {
     /** Overlay opacity (0-1). */
     opacity?: number;
 }
+/**
+ * One entry in the multi-overlay stack (contract `overlays[]` items, v2.152.0).
+ * Index-aligned to the overlay-role sources — `overlays[i]` places overlay
+ * source `i` — and mirrors the flat single-overlay option shape. Matches the
+ * generated `ImageWatermarkImageOverlaysItem`.
+ */
+export interface WatermarkOverlay {
+    /** 9-grid anchor position for this overlay. */
+    anchor?: WatermarkAnchor;
+    /** Horizontal offset from the anchor (e.g. '40px' or '5%'). */
+    margin_x?: string;
+    /** Vertical offset from the anchor. */
+    margin_y?: string;
+    /** Overlay opacity (0-1). */
+    opacity?: number;
+    /** Overlay width (e.g. '120px' or '20%'). */
+    overlay_width?: string;
+}
 export interface WatermarkOptions {
     /** 9-grid anchor position. */
     anchor?: WatermarkAnchor;
@@ -95,11 +131,38 @@ export interface WatermarkOptions {
     opacity?: number;
     /** Overlay width (e.g. '120px' or '20%'). */
     overlay_width?: string;
+    /**
+     * Per-overlay placement for the multi-overlay stack (contract `overlays[]`,
+     * v2.152.0) — one entry per overlay source, index-aligned; stacks up to 8
+     * overlays on one base image (z-order = array index). MUTUALLY EXCLUSIVE with
+     * the flat single-overlay options above; the server rejects mixing the two as
+     * `invalid_options`. image_watermark jpeg/png/webp bases only.
+     */
+    overlays?: WatermarkOverlay[];
 }
 /** Resize mode (contract `fit` enum, v2.97.0). */
 export type OutputFit = 'max' | 'crop' | 'scale';
-/** Metadata policy (contract `metadata` enum). Both values stable since v2.102.0 (keep/strip un-parked). */
-export type OutputMetadata = 'all' | 'keep';
+/**
+ * Metadata policy (contract `metadata` enum). `strip` (default) removes all
+ * EXIF/IPTC/XMP; `keep` preserves them. Honored on same_format; PLANNED on
+ * format_change (v2.106.0). Renamed in contracts v2.107.0 — the legacy `all`
+ * token is now a DEPRECATED alias of `strip` (still accepted on the wire, emits
+ * a Deprecation header); use `strip`.
+ */
+export type OutputMetadata = 'strip' | 'keep';
+/**
+ * Compression mode on the optimiser (same_format) route (contract `encoding_mode`
+ * enum). `quality` (default) drives the encode by the quality slider; `target_size`
+ * targets a byte budget via the worker's encode-measure loop — STABLE since
+ * contracts v2.108.0 (jpeg/webp/avif).
+ */
+export type OutputEncodingMode = 'quality' | 'target_size';
+/** Chroma subsampling for JPEG output (contract `chroma_subsampling` enum, v2.110.0). `420` smallest → `444` highest fidelity. Honored: same_format jpeg only. */
+export type OutputChromaSubsampling = '420' | '422' | '444';
+/** ICC colour-profile handling (contract `color_profile` enum, v2.112.0). `keep` preserves the embedded profile; `srgb` converts to sRGB; `strip` removes it. Route/value availability is gated by the output lowering. */
+export type OutputColorProfile = 'keep' | 'srgb' | 'strip';
+/** Named quality preset (contract `quality_preset` enum, v2.148.0) — an alternative to the numeric `quality` slider. `best` highest fidelity → `low` smallest. Honored: same_format avif/jpeg/webp. */
+export type OutputQualityPreset = 'best' | 'good' | 'fair' | 'low';
 /**
  * Options for the file-first `output()` image transform. The KEY SET is the
  * UNION of every image route's honored + planned option keys (image-output-routes
@@ -110,8 +173,16 @@ export type OutputMetadata = 'all' | 'keep';
  * `fit`) is honored on raster routes; `height` is optional (width-only resize).
  */
 export interface OutputOptions {
-    /** Output quality for lossy formats (1-100). Honored: avif/jpeg/webp routes. */
+    /** Output quality (1-100). Honored on same-format avif/jpeg/png/webp and lossy format-change routes. */
     quality?: number;
+    /** Named quality preset (`best`/`good`/`fair`/`low`) — an alternative to the numeric `quality` slider (v2.148.0). Honored: same_format avif/jpeg/webp. */
+    quality_preset?: OutputQualityPreset;
+    /** Compression mode (same_format avif/jpeg/webp). `quality` (default) or `target_size` — STABLE since v2.108.0. */
+    encoding_mode?: OutputEncodingMode;
+    /** Target output size in bytes (≥1024) for `encoding_mode: 'target_size'`. STABLE since v2.108.0. Honored: same_format avif/jpeg/webp. */
+    target_size_bytes?: number;
+    /** Chroma subsampling for JPEG output. Honored: same_format jpeg only (v2.110.0). */
+    chroma_subsampling?: OutputChromaSubsampling;
     /** Resize target width in px (1-16384; width*height <= 16MP). */
     width?: number;
     /** Resize target height in px (optional — width-only resize preserves aspect). */
@@ -126,12 +197,14 @@ export interface OutputOptions {
     optimization_level?: number;
     /** AVIF encode speed. Honored: same_format avif only. */
     avif_speed?: number;
-    /** Metadata policy. Honored: same_format routes (both `all` and `keep` since v2.102.0). */
+    /** Metadata policy (`strip` default / `keep`). Honored: same_format; PLANNED on format_change (v2.106.0). */
     metadata?: OutputMetadata;
+    /** ICC colour-profile handling (`keep`/`srgb`/`strip`). Availability depends on route and value. */
+    color_profile?: OutputColorProfile;
+    /** Auto-rotate per EXIF orientation. STABLE since v2.120.0 (both routes). */
+    auto_orient?: boolean;
     /** JPEG/WebP lossless. Honored: same_format jpeg/webp (stable since v2.101.0). */
     lossless?: boolean;
-    /** Lossy PNG quantization. PLANNED (gated unavailable; licence-gated). */
-    lossy?: boolean;
 }
 /**
  * The user-supplyable option keys per verb (excludes positional-owned keys).
@@ -139,9 +212,10 @@ export interface OutputOptions {
  * positional-owned keys equals the contract `operationOptionKeys(metadata)`.
  */
 export declare const VERB_OPTION_KEYS: {
-    readonly convert: readonly ["quality", "background", "crf", "trim_start", "trim_end", "fps", "width", "max_colors", "loop", "dither", "bitrate", "pages", "dpi"];
-    readonly thumbnail: readonly ["width", "height", "fit", "format", "quality", "timestamp", "source", "page"];
+    readonly convert: readonly ["quality", "background", "crf", "trim_start", "trim_end", "fps", "width", "height", "fit", "metadata", "color_profile", "auto_orient", "max_colors", "loop", "dither", "bitrate", "pages", "dpi"];
+    readonly thumbnail: readonly ["width", "height", "fit", "format", "quality", "background", "timestamp", "source", "page"];
+    readonly transform: readonly ["rotate", "flip"];
     readonly textWatermark: readonly ["font_size", "color", "font_family", "rotation", "watermark_mode", "tile_spacing", "anchor", "margin_x", "margin_y", "opacity"];
-    readonly watermark: readonly ["anchor", "margin_x", "margin_y", "opacity", "overlay_width"];
-    readonly output: readonly ["quality", "width", "height", "fit", "background", "progressive", "optimization_level", "avif_speed", "metadata", "lossless", "lossy"];
+    readonly watermark: readonly ["anchor", "margin_x", "margin_y", "opacity", "overlay_width", "overlays"];
+    readonly output: readonly ["quality", "quality_preset", "encoding_mode", "target_size_bytes", "chroma_subsampling", "width", "height", "fit", "background", "progressive", "optimization_level", "avif_speed", "metadata", "color_profile", "auto_orient", "lossless"];
 };

package/dist/ergonomic/option_types.js

@@ -15,31 +15,35 @@
  * Mirrored by the PHP array-shape docblocks — keep in lockstep.
  */
 const CONVERT_OPTION_KEYS = [
-    'quality', 'background', 'crf', 'trim_start', 'trim_end', 'fps', 'width',
-    'max_colors', 'loop', 'dither', 'bitrate', 'pages', 'dpi',
+    'quality', 'background', 'crf', 'trim_start', 'trim_end', 'fps', 'width', 'height', 'fit', 'metadata',
+    'color_profile', 'auto_orient', 'max_colors', 'loop', 'dither', 'bitrate', 'pages', 'dpi',
 ];
 const THUMBNAIL_OPTION_KEYS = [
-    'width', 'height', 'fit', 'format', 'quality', 'timestamp', 'source', 'page',
+    'width', 'height', 'fit', 'format', 'quality', 'background', 'timestamp', 'source', 'page',
 ];
+const TRANSFORM_OPTION_KEYS = ['rotate', 'flip'];
 const TEXT_WATERMARK_OPTION_KEYS = [
     'font_size', 'color', 'font_family', 'rotation', 'watermark_mode',
     'tile_spacing', 'anchor', 'margin_x', 'margin_y', 'opacity',
 ];
 const WATERMARK_OPTION_KEYS = [
-    'anchor', 'margin_x', 'margin_y', 'opacity', 'overlay_width',
+    'anchor', 'margin_x', 'margin_y', 'opacity', 'overlay_width', 'overlays',
 ];
 const OUTPUT_OPTION_KEYS = [
-    'quality', 'width', 'height', 'fit', 'background', 'progressive',
-    'optimization_level', 'avif_speed', 'metadata', 'lossless', 'lossy',
+    'quality', 'quality_preset', 'encoding_mode', 'target_size_bytes', 'chroma_subsampling', 'width', 'height', 'fit',
+    'background', 'progressive', 'optimization_level', 'avif_speed', 'metadata',
+    'color_profile', 'auto_orient', 'lossless',
 ];
 const _convertKeysMatch = true;
 const _thumbnailKeysMatch = true;
+const _transformKeysMatch = true;
 const _textWatermarkKeysMatch = true;
 const _watermarkKeysMatch = true;
 const _outputKeysMatch = true;
 // Reference the assertions so `noUnusedLocals` doesn't strip them.
 void _convertKeysMatch;
 void _thumbnailKeysMatch;
+void _transformKeysMatch;
 void _textWatermarkKeysMatch;
 void _watermarkKeysMatch;
 void _outputKeysMatch;
@@ -51,6 +55,7 @@ void _outputKeysMatch;
 export const VERB_OPTION_KEYS = {
     convert: CONVERT_OPTION_KEYS,
     thumbnail: THUMBNAIL_OPTION_KEYS,
+    transform: TRANSFORM_OPTION_KEYS,
     textWatermark: TEXT_WATERMARK_OPTION_KEYS,
     watermark: WATERMARK_OPTION_KEYS,
     output: OUTPUT_OPTION_KEYS,

package/dist/ergonomic/option_validation.d.ts

@@ -9,8 +9,8 @@ import { type OperationMetadata } from '@giveitsmaller/contracts/operations';
  * sidecars (the same contract-anchored source the wire-key conformance guard
  * uses), so it can never silently drift from the contract.
  *
- * SCOPE: `convert` / `thumbnail` / `textWatermark` / `watermark` only. `compress`
- * is deliberately EXCLUDED — its bag legitimately carries SDK-only keys
+ * SCOPE: `convert` / `thumbnail` / `textWatermark` / `watermark` / `output`
+ * only. `compress` is deliberately EXCLUDED — its bag legitimately carries SDK-only keys
  * (`optimize`, `presetOverrides`) and camelCase resolver aliases (`targetSize`,
  * `outputFormat`) that are not `operationOptionKeys(compressMetadata)`; it has its
  * own `unknown_field` validation through the preset resolver.
@@ -25,7 +25,7 @@ import { type OperationMetadata } from '@giveitsmaller/contracts/operations';
  */
 export declare function operationOptionKeys(metadata: OperationMetadata): ReadonlySet<string>;
 /** The ergonomic verbs whose option bags this module key-validates. */
-export type ValidatedVerb = 'convert' | 'thumbnail' | 'textWatermark' | 'watermark' | 'output';
+export type ValidatedVerb = 'convert' | 'thumbnail' | 'transform' | 'textWatermark' | 'watermark' | 'output';
 /** Accessor for the conformance guard (pins these sets to the contract metadata). */
 export declare function allowedKeysFor(verb: ValidatedVerb): ReadonlySet<string>;
 /**
@@ -39,6 +39,24 @@ export declare function allowedKeysFor(verb: ValidatedVerb): ReadonlySet<string>
  *   option set.
  */
 export declare function validateVerbOptions(verb: ValidatedVerb, options: object | null | undefined): void;
+/**
+ * Validate the option bag for the SINGLE-OP builder `gisl().convert(input, options)`
+ * (ExVcchMz). DISTINCT from `validateVerbOptions('convert', ...)`, which is for the
+ * file-first `Recipe.convert(format, options)` where `output_format` is set by the
+ * positional `format` arg and is therefore positional-owned (rejected in the bag).
+ * The single-op builder has NO positional format — its target is carried in the bag
+ * as the wire key `output_format` — so this guard ALLOWS `output_format` (and only
+ * that; the SDK alias `format` is NOT accepted, the single-op bag lowers verbatim to
+ * the wire) while still rejecting any other unknown key, AND requires `output_format`
+ * to be present (a convert with no target is a guaranteed server 422). `format`, the
+ * SDK alias, is intentionally excluded so a caller using it gets a clear unknown-key
+ * error rather than a silent wire `format` the server 422s.
+ *
+ * @throws {GislConfigError} reason `unknown_field` for a key outside the convert
+ *   contract set ∪ {output_format}; reason `missing_required_field` when
+ *   `output_format` is absent/nullish.
+ */
+export declare function validateSingleOpConvertOptions(options: object | null | undefined): void;
 /**
  * Assert thumbnail `width` AND `height` are both present and non-nullish (the
  * contract marks both `required` for image/video/document). The typed signature

package/dist/ergonomic/option_validation.js

@@ -1,4 +1,4 @@
-import { convertMetadata, thumbnailMetadata, textWatermarkMetadata, imageWatermarkMetadata, videoWatermarkMetadata, } from '@giveitsmaller/contracts/operations';
+import { convertMetadata, thumbnailMetadata, transformMetadata, textWatermarkMetadata, imageWatermarkMetadata, videoWatermarkMetadata, } from '@giveitsmaller/contracts/operations';
 import { GislConfigError } from '../errors.js';
 import { VERB_OPTION_KEYS } from './option_types.js';
 /**
@@ -11,8 +11,8 @@ import { VERB_OPTION_KEYS } from './option_types.js';
  * sidecars (the same contract-anchored source the wire-key conformance guard
  * uses), so it can never silently drift from the contract.
  *
- * SCOPE: `convert` / `thumbnail` / `textWatermark` / `watermark` only. `compress`
- * is deliberately EXCLUDED — its bag legitimately carries SDK-only keys
+ * SCOPE: `convert` / `thumbnail` / `textWatermark` / `watermark` / `output`
+ * only. `compress` is deliberately EXCLUDED — its bag legitimately carries SDK-only keys
  * (`optimize`, `presetOverrides`) and camelCase resolver aliases (`targetSize`,
  * `outputFormat`) that are not `operationOptionKeys(compressMetadata)`; it has its
  * own `unknown_field` validation through the preset resolver.
@@ -51,6 +51,9 @@ function union(...sets) {
 const ALLOWED_KEYS = {
     convert: operationOptionKeys(convertMetadata),
     thumbnail: operationOptionKeys(thumbnailMetadata),
+    // transform is a passthrough verb (rotate/flip). The generic allowed set is
+    // the op-wide union {rotate, flip}; `flip`-on-PDF is narrowed server-side.
+    transform: operationOptionKeys(transformMetadata),
     textWatermark: operationOptionKeys(textWatermarkMetadata),
     watermark: union(operationOptionKeys(imageWatermarkMetadata), operationOptionKeys(videoWatermarkMetadata)),
     // `output` is the image Output facade — its allowed keys are the UNION of every
@@ -115,6 +118,36 @@ export function validateVerbOptions(verb, options) {
         }
     }
 }
+/**
+ * Validate the option bag for the SINGLE-OP builder `gisl().convert(input, options)`
+ * (ExVcchMz). DISTINCT from `validateVerbOptions('convert', ...)`, which is for the
+ * file-first `Recipe.convert(format, options)` where `output_format` is set by the
+ * positional `format` arg and is therefore positional-owned (rejected in the bag).
+ * The single-op builder has NO positional format — its target is carried in the bag
+ * as the wire key `output_format` — so this guard ALLOWS `output_format` (and only
+ * that; the SDK alias `format` is NOT accepted, the single-op bag lowers verbatim to
+ * the wire) while still rejecting any other unknown key, AND requires `output_format`
+ * to be present (a convert with no target is a guaranteed server 422). `format`, the
+ * SDK alias, is intentionally excluded so a caller using it gets a clear unknown-key
+ * error rather than a silent wire `format` the server 422s.
+ *
+ * @throws {GislConfigError} reason `unknown_field` for a key outside the convert
+ *   contract set ∪ {output_format}; reason `missing_required_field` when
+ *   `output_format` is absent/nullish.
+ */
+export function validateSingleOpConvertOptions(options) {
+    const o = (options ?? {});
+    const allowed = new Set([...ALLOWED_KEYS.convert, 'output_format']);
+    for (const key of Object.keys(o)) {
+        if (!allowed.has(key)) {
+            throw new GislConfigError(`convert: unknown option '${key}'. Valid options: ${[...allowed].sort().join(', ')}.`, { reason: 'unknown_field', conflictingFields: [key] });
+        }
+    }
+    if (o.output_format === undefined || o.output_format === null) {
+        throw new GislConfigError(`convert requires 'output_format' (the target format) in the options bag; ` +
+            `e.g. gisl().convert(input, { output_format: 'webp' }).`, { reason: 'missing_required_field', conflictingFields: ['output_format'] });
+    }
+}
 /**
  * Assert thumbnail `width` AND `height` are both present and non-nullish (the
  * contract marks both `required` for image/video/document). The typed signature

package/dist/ergonomic/preset_resolver.d.ts

@@ -9,7 +9,7 @@ import { type PresetDefaults, type PresetMedia, type PresetOp } from './presets/
  * construction. Previously a hand-typed literal that the v2.73.0 regen had to
  * bump manually (yREs0srv).
  */
-export declare const PRESET_VERSION: "1.4";
+export declare const PRESET_VERSION: "1.6";
 /**
  * Inputs to {@link resolveCompressOptions}. `media` selects which leaf
  * DTO drives sdkDefault + clientDefault lookups + invalid-combo