@giveitsmaller/sdk 0.18.0 → 0.19.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/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. */
@@ -98,8 +110,27 @@ export interface WatermarkOptions {
 }
 /** 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 +141,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 +165,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 +180,9 @@ 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 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 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,11 +15,11 @@
  * 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 TEXT_WATERMARK_OPTION_KEYS = [
     'font_size', 'color', 'font_family', 'rotation', 'watermark_mode',
@@ -29,8 +29,9 @@ const WATERMARK_OPTION_KEYS = [
     'anchor', 'margin_x', 'margin_y', 'opacity', 'overlay_width',
 ];
 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;

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.

package/dist/ergonomic/option_validation.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.

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

package/dist/ergonomic/preset_resolver.js

@@ -63,7 +63,6 @@ const WIRE_ALIASES = Object.freeze({
     sampleRate: 'sample_rate',
     audioCodec: 'audio_codec',
     audioBitrate: 'audio_bitrate',
-    imageQuality: 'image_quality',
     stripMacros: 'strip_macros',
     stripHiddenData: 'strip_hidden_data',
     stripUnusedFonts: 'strip_unused_fonts',
@@ -254,9 +253,9 @@ const MEDIA_FIELDS = Object.freeze({
     audio: new Set(['bitrate', 'channels', 'sampleRate', 'normalize']),
     video: new Set(['codec', 'targetSize', 'crf', 'preset', 'width', 'height', 'fit', 'fps', 'faststart', 'audioCodec', 'audioBitrate']),
     document_pdf: new Set(['profile', 'grayscale']),
-    document_office: new Set(['imageQuality', 'stripMacros', 'stripHiddenData', 'stripUnusedFonts']),
-    document_odf: new Set(['imageQuality', 'stripMetadata', 'stripUnusedStyles']),
-    document_epub: new Set(['imageQuality', 'fontSubsetting', 'stripUnusedCss']),
+    document_office: new Set(['stripMacros', 'stripHiddenData', 'stripUnusedFonts']),
+    document_odf: new Set(['stripMetadata', 'stripUnusedStyles']),
+    document_epub: new Set(['fontSubsetting', 'stripUnusedCss']),
 });
 function detectMismatchedOverrides(media, overrides) {
     const expected = MEDIA_FIELDS[media];
@@ -323,9 +322,9 @@ export const KNOWN_WIRE_FIELDS = Object.freeze({
     audio: new Set(['bitrate', 'channels', 'sample_rate', 'normalize', 'trim_start', 'trim_end']),
     video: new Set(['codec', 'encoding_mode', 'crf', 'target_size_bytes', 'preset', 'width', 'height', 'fit', 'fps', 'faststart', 'audio_codec', 'audio_bitrate', 'trim_start', 'trim_end']),
     document_pdf: new Set(['profile', 'grayscale']),
-    document_office: new Set(['image_quality', 'strip_macros', 'strip_hidden_data', 'strip_unused_fonts']),
-    document_odf: new Set(['image_quality', 'strip_metadata', 'strip_unused_styles']),
-    document_epub: new Set(['image_quality', 'font_subsetting', 'strip_unused_css']),
+    document_office: new Set(['strip_macros', 'strip_hidden_data', 'strip_unused_fonts']),
+    document_odf: new Set(['strip_metadata', 'strip_unused_styles']),
+    document_epub: new Set(['font_subsetting', 'strip_unused_css']),
 });
 function validateMerged(media, merged, explicitKeys, winners) {
     // Unknown-field defence-in-depth: every key must belong to the

package/dist/ergonomic/presets/document_epub_compress.d.ts

@@ -1,11 +1,9 @@
 import { OptimizeFor } from '../../generated/sdk_spec/enums.js';
 export interface DocumentEpubCompressPresetOptionsInput {
-    readonly imageQuality?: number;
     readonly fontSubsetting?: boolean;
     readonly stripUnusedCss?: boolean;
 }
 export declare class DocumentEpubCompressPresetOptions {
-    readonly imageQuality?: number;
     readonly fontSubsetting?: boolean;
     readonly stripUnusedCss?: boolean;
     private constructor();

package/dist/ergonomic/presets/document_epub_compress.js

@@ -1,15 +1,12 @@
 // T4a — DocumentEpubCompressPresetOptions leaf DTO.
 //
-// Field set per ticket VhIj4S7T: EPUB = 3 fields
-//   (imageQuality, fontSubsetting, stripUnusedCss). Primitives only.
+// Field set per ticket VhIj4S7T: EPUB = 2 fields
+//   (fontSubsetting, stripUnusedCss). Primitives only.
 import { shippedDefaultsFor as f3ShippedDefaultsFor } from '../../generated/sdk_spec/presets.js';
 export class DocumentEpubCompressPresetOptions {
-    imageQuality;
     fontSubsetting;
     stripUnusedCss;
     constructor(input) {
-        if (input.imageQuality !== undefined)
-            this.imageQuality = input.imageQuality;
         if (input.fontSubsetting !== undefined)
             this.fontSubsetting = input.fontSubsetting;
         if (input.stripUnusedCss !== undefined)
@@ -23,8 +20,6 @@ export class DocumentEpubCompressPresetOptions {
         const cell = f3ShippedDefaultsFor('document_epub_compress', level);
         const input = {};
         const mut = input;
-        if ('imageQuality' in cell)
-            mut.imageQuality = cell.imageQuality;
         if ('fontSubsetting' in cell)
             mut.fontSubsetting = cell.fontSubsetting;
         if ('stripUnusedCss' in cell)

package/dist/ergonomic/presets/document_odf_compress.d.ts

@@ -1,11 +1,9 @@
 import { OptimizeFor } from '../../generated/sdk_spec/enums.js';
 export interface DocumentOdfCompressPresetOptionsInput {
-    readonly imageQuality?: number;
     readonly stripMetadata?: boolean;
     readonly stripUnusedStyles?: boolean;
 }
 export declare class DocumentOdfCompressPresetOptions {
-    readonly imageQuality?: number;
     readonly stripMetadata?: boolean;
     readonly stripUnusedStyles?: boolean;
     private constructor();

package/dist/ergonomic/presets/document_odf_compress.js

@@ -1,15 +1,12 @@
 // T4a — DocumentOdfCompressPresetOptions leaf DTO.
 //
-// Field set per ticket VhIj4S7T: ODF = 3 fields
-//   (imageQuality, stripMetadata, stripUnusedStyles). Primitives only.
+// Field set per ticket VhIj4S7T: ODF = 2 fields
+//   (stripMetadata, stripUnusedStyles). Primitives only.
 import { shippedDefaultsFor as f3ShippedDefaultsFor } from '../../generated/sdk_spec/presets.js';
 export class DocumentOdfCompressPresetOptions {
-    imageQuality;
     stripMetadata;
     stripUnusedStyles;
     constructor(input) {
-        if (input.imageQuality !== undefined)
-            this.imageQuality = input.imageQuality;
         if (input.stripMetadata !== undefined)
             this.stripMetadata = input.stripMetadata;
         if (input.stripUnusedStyles !== undefined)
@@ -23,8 +20,6 @@ export class DocumentOdfCompressPresetOptions {
         const cell = f3ShippedDefaultsFor('document_odf_compress', level);
         const input = {};
         const mut = input;
-        if ('imageQuality' in cell)
-            mut.imageQuality = cell.imageQuality;
         if ('stripMetadata' in cell)
             mut.stripMetadata = cell.stripMetadata;
         if ('stripUnusedStyles' in cell)

package/dist/ergonomic/presets/document_office_compress.d.ts

@@ -1,12 +1,10 @@
 import { OptimizeFor } from '../../generated/sdk_spec/enums.js';
 export interface DocumentOfficeCompressPresetOptionsInput {
-    readonly imageQuality?: number;
     readonly stripMacros?: boolean;
     readonly stripHiddenData?: boolean;
     readonly stripUnusedFonts?: boolean;
 }
 export declare class DocumentOfficeCompressPresetOptions {
-    readonly imageQuality?: number;
     readonly stripMacros?: boolean;
     readonly stripHiddenData?: boolean;
     readonly stripUnusedFonts?: boolean;

package/dist/ergonomic/presets/document_office_compress.js

@@ -1,17 +1,14 @@
 // T4a — DocumentOfficeCompressPresetOptions leaf DTO.
 //
-// Field set per ticket VhIj4S7T: office = 4 fields
-//   (imageQuality, stripMacros, stripHiddenData, stripUnusedFonts).
+// Field set per ticket VhIj4S7T: office = 3 fields
+//   (stripMacros, stripHiddenData, stripUnusedFonts).
 // All primitive values — no enum translation needed.
 import { shippedDefaultsFor as f3ShippedDefaultsFor } from '../../generated/sdk_spec/presets.js';
 export class DocumentOfficeCompressPresetOptions {
-    imageQuality;
     stripMacros;
     stripHiddenData;
     stripUnusedFonts;
     constructor(input) {
-        if (input.imageQuality !== undefined)
-            this.imageQuality = input.imageQuality;
         if (input.stripMacros !== undefined)
             this.stripMacros = input.stripMacros;
         if (input.stripHiddenData !== undefined)
@@ -27,8 +24,6 @@ export class DocumentOfficeCompressPresetOptions {
         const cell = f3ShippedDefaultsFor('document_office_compress', level);
         const input = {};
         const mut = input;
-        if ('imageQuality' in cell)
-            mut.imageQuality = cell.imageQuality;
         if ('stripMacros' in cell)
             mut.stripMacros = cell.stripMacros;
         if ('stripHiddenData' in cell)

package/dist/file-first.d.ts

@@ -57,6 +57,21 @@ 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;
 }
 /**
  * One succeeded entry in {@link RunResult.succeeded}: a single input's
@@ -101,6 +116,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 +136,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 +170,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 {
@@ -536,6 +565,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: {

package/dist/file-first.js

@@ -40,6 +40,10 @@ import { Handle } from './handle.js';
  *  - `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
@@ -56,6 +60,14 @@ export class RunResult {
     url;
     /** True iff {@link failed} is empty. */
     ok;
+    /**
+     * 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`.
+     */
+    targetSizeMissed;
     constructor(workflowId, state, artifacts, succeeded, failed, downloader) {
         this.workflowId = workflowId;
         this.state = state;
@@ -65,6 +77,9 @@ export class RunResult {
         this.downloader = downloader;
         this.url = artifacts.length === 1 ? artifacts[0].url : undefined;
         this.ok = failed.length === 0;
+        this.targetSizeMissed = artifacts.every((a) => a.targetSizeMet === undefined)
+            ? undefined
+            : artifacts.some((a) => a.targetSizeMet === false);
     }
     /**
      * Address a succeeded input by the `key:` given to `file()`. Duplicate keys
@@ -134,20 +149,26 @@ export class RunResult {
         return { paths };
     }
     /**
-     * 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() {
-        // Re-project each OutputFile to exactly its four fields so structurally
+        // Re-project each OutputFile to exactly its known fields so structurally
         // compatible inputs carrying extra properties can't leak into the JSON.
+        // The target-size fields (chosenQuality/targetSizeMet) are OMITTED when
+        // undefined, mirroring PHP's omit-when-null so non-target-size outputs
+        // stay byte-identical across languages.
         const file = (o) => ({
             url: o.url,
             filename: o.filename,
             sizeBytes: o.sizeBytes,
             operation: o.operation,
+            ...(o.chosenQuality !== undefined ? { chosenQuality: o.chosenQuality } : {}),
+            ...(o.targetSizeMet !== undefined ? { targetSizeMet: o.targetSizeMet } : {}),
         });
         const rest = {
             artifacts: this.artifacts.map(file),
@@ -164,13 +185,18 @@ export class RunResult {
             }),
         };
         const head = { workflowId: this.workflowId, state: this.state, ok: this.ok };
-        // Insert `url` BETWEEN ok and artifacts when present, matching the PHP
-        // toArray() field order (workflowId, state, ok, url?, artifacts, ...) so
-        // JSON-string parity holds. Omitted entirely when undefined (PHP omits
-        // null), so `JSON.stringify` produces the identical shape.
+        // Insert `targetSizeMissed` immediately after `ok` (before `url`) when
+        // present, then `url` BETWEEN it and artifacts, matching the PHP toArray()
+        // field order (workflowId, state, ok, targetSizeMissed?, url?, artifacts,
+        // ...) so JSON-string parity holds. Both are omitted entirely when
+        // undefined (PHP omits null), so `JSON.stringify` produces the identical
+        // shape.
+        const headWithMissed = this.targetSizeMissed === undefined
+            ? head
+            : { ...head, targetSizeMissed: this.targetSizeMissed };
         return this.url === undefined
-            ? { ...head, ...rest }
-            : { ...head, url: this.url, ...rest };
+            ? { ...headWithMissed, ...rest }
+            : { ...headWithMissed, url: this.url, ...rest };
     }
     requireDownloader() {
         if (this.downloader === undefined) {
@@ -200,6 +226,10 @@ export function projectDownloadsToRunResult(workflowId, finalStatus, jobDownload
                 filename: f.filename,
                 sizeBytes: f.sizeBytes,
                 operation: f.operation,
+                // Omit-when-absent on the LIVE OutputFile too (not just toJSON): a
+                // non-target-size output carries no chosenQuality/targetSizeMet key.
+                ...(f.chosenQuality !== undefined ? { chosenQuality: f.chosenQuality } : {}),
+                ...(f.targetSizeMet !== undefined ? { targetSizeMet: f.targetSizeMet } : {}),
             });
         }
     }
@@ -259,6 +289,10 @@ export function projectMultiJobToRunResult(workflowId, finalStatus, jobDownloads
             filename: f.filename,
             sizeBytes: f.sizeBytes,
             operation: f.operation,
+            // Omit-when-absent on the LIVE OutputFile too (mirrors toJSON + the
+            // single-job projector).
+            ...(f.chosenQuality !== undefined ? { chosenQuality: f.chosenQuality } : {}),
+            ...(f.targetSizeMet !== undefined ? { targetSizeMet: f.targetSizeMet } : {}),
         }));
         // The flat artifacts[] keeps every job's outputs in job order.
         artifacts.push(...outputs);
@@ -1055,6 +1089,8 @@ export const WATERMARK_CAPABILITY = {
     image_watermark: {
         image: { mimes: ['image/jpeg', 'image/png', 'image/webp'], availability: 'stable' },
         image_gif: { mimes: ['image/gif'], availability: 'planned' },
+        image_tiff: { mimes: ['image/tiff'], availability: 'stable' },
+        image_bmp: { mimes: ['image/bmp'], availability: 'stable' },
     },
     video_watermark: {
         video: { mimes: ['video/mp4', 'video/webm'], availability: 'beta' },

package/dist/generated/sdk_spec/enums.d.ts

@@ -10,8 +10,9 @@ export declare const ImageFormat: {
 };
 export type ImageFormat = typeof ImageFormat[keyof typeof ImageFormat];
 export declare const ImageMetadataPolicy: {
-    readonly All: "all";
+    readonly Strip: "strip";
     readonly Keep: "keep";
+    readonly All: "all";
 };
 export type ImageMetadataPolicy = typeof ImageMetadataPolicy[keyof typeof ImageMetadataPolicy];
 export declare const VideoCodec: {
@@ -88,8 +89,9 @@ export declare const ERGONOMIC_ENUMS: {
         readonly Webp: "webp";
     };
     readonly ImageMetadataPolicy: {
-        readonly All: "all";
+        readonly Strip: "strip";
         readonly Keep: "keep";
+        readonly All: "all";
     };
     readonly VideoCodec: {
         readonly H264: "h264";

package/dist/generated/sdk_spec/enums.js

@@ -13,15 +13,21 @@ export const ImageFormat = {
     Webp: "webp",
 };
 // Image metadata handling (compress.image, optimiser/same_format route):
-//   All  = strip all EXIF/IPTC/XMP (default, smallest file)
-//   Keep = preserve EXIF/ICC/XMP — worker-proven on the libcaesium formats
-//          (JPEG/PNG/WebP/GIF/TIFF; lambdas PR #260, un-parked 2026-06-23).
+//   Strip = remove all EXIF/IPTC/XMP (default, smallest file) — the canonical
+//           strip token (renamed from `all` 2026-06-23; `all` reading as
+//           "strip all" was counterintuitive).
+//   Keep  = preserve EXIF/ICC/XMP — worker-proven on the libcaesium formats
+//           (JPEG/PNG/WebP/GIF/TIFF; lambdas PR #260, un-parked 2026-06-23).
+//   All   = DEPRECATED alias of Strip (still accepted on the wire, emits
+//           Deprecation/Sunset; the API lowers `strip`→`all` at the worker
+//           boundary). Migrate to Strip.
 // Keep is NOT available for AVIF (ravif) / SVG (SVGO) — those re-encode from
 // pixels and cannot preserve metadata, so the worker rejects it there (the
-// `metadata` enum is narrowed to [all] on those groups).
+// `metadata` enum is narrowed to [strip, all] on those groups).
 export const ImageMetadataPolicy = {
-    All: "all",
+    Strip: "strip",
     Keep: "keep",
+    All: "all",
 };
 // Video codec. H264 = widest compatibility; H265/Av1 = better compression but slower.
 export const VideoCodec = {

package/dist/generated/sdk_spec/presets.js

@@ -5,17 +5,17 @@ export const PRESETS = Object.freeze({
     "image_compress": Object.freeze({
         Size: Object.freeze({
             "quality": 65,
-            "metadata": "All",
+            "metadata": "Strip",
             "outputFormat": "Original",
         }),
         Balanced: Object.freeze({
             "quality": 80,
-            "metadata": "All",
+            "metadata": "Strip",
             "outputFormat": "Original",
         }),
         Quality: Object.freeze({
             "quality": 92,
-            "metadata": "All",
+            "metadata": "Strip",
             "outputFormat": "Original",
         }),
     }),
@@ -66,19 +66,16 @@ export const PRESETS = Object.freeze({
     }),
     "document_office_compress": Object.freeze({
         Size: Object.freeze({
-            "imageQuality": 60,
             "stripMacros": true,
             "stripHiddenData": true,
             "stripUnusedFonts": true,
         }),
         Balanced: Object.freeze({
-            "imageQuality": 80,
             "stripMacros": true,
             "stripHiddenData": false,
             "stripUnusedFonts": false,
         }),
         Quality: Object.freeze({
-            "imageQuality": 92,
             "stripMacros": false,
             "stripHiddenData": false,
             "stripUnusedFonts": false,
@@ -86,34 +83,28 @@ export const PRESETS = Object.freeze({
     }),
     "document_odf_compress": Object.freeze({
         Size: Object.freeze({
-            "imageQuality": 60,
             "stripMetadata": true,
             "stripUnusedStyles": true,
         }),
         Balanced: Object.freeze({
-            "imageQuality": 80,
             "stripMetadata": true,
             "stripUnusedStyles": false,
         }),
         Quality: Object.freeze({
-            "imageQuality": 92,
             "stripMetadata": false,
             "stripUnusedStyles": false,
         }),
     }),
     "document_epub_compress": Object.freeze({
         Size: Object.freeze({
-            "imageQuality": 60,
             "fontSubsetting": true,
             "stripUnusedCss": true,
         }),
         Balanced: Object.freeze({
-            "imageQuality": 80,
             "fontSubsetting": true,
             "stripUnusedCss": false,
         }),
         Quality: Object.freeze({
-            "imageQuality": 92,
             "fontSubsetting": false,
             "stripUnusedCss": false,
         }),

package/dist/generated/sdk_spec/version.d.ts

@@ -1,3 +1,3 @@
-export declare const SDK_SPEC_VERSION: "2.1.0";
-export declare const PRESET_VERSION: "1.4";
-export declare const PRESET_CONFIG_HASH: "sha256:62fbada24e33f983dacb0f717b0c9bb80824a208c3dc7f9af8523026e783543a";
+export declare const SDK_SPEC_VERSION: "2.2.0";
+export declare const PRESET_VERSION: "1.6";
+export declare const PRESET_CONFIG_HASH: "sha256:0fe215aede1da13430380384c58226d074c3b8344c091efc53e097c2930a34f7";

package/dist/generated/sdk_spec/version.js

@@ -1,6 +1,6 @@
 // CODE GENERATED — DO NOT EDIT.
 // Source: compression_contracts/sdk-spec/ (see sdk-spec/README.md).
 // Regenerate with: scripts/generate.py.
-export const SDK_SPEC_VERSION = "2.1.0";
-export const PRESET_VERSION = "1.4";
-export const PRESET_CONFIG_HASH = "sha256:62fbada24e33f983dacb0f717b0c9bb80824a208c3dc7f9af8523026e783543a";
+export const SDK_SPEC_VERSION = "2.2.0";
+export const PRESET_VERSION = "1.6";
+export const PRESET_CONFIG_HASH = "sha256:0fe215aede1da13430380384c58226d074c3b8344c091efc53e097c2930a34f7";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@giveitsmaller/sdk",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Node.js SDK for the GISL (Give It Smaller) file compression and processing API",
   "license": "MIT",
   "type": "module",
@@ -31,7 +31,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@giveitsmaller/contracts": "^0.35.0"
+    "@giveitsmaller/contracts": "^0.50.0"
   },
   "devDependencies": {
     "@types/node": "^22",