@giveitsmaller/sdk 0.20.0 → 0.22.0

package/dist/ergonomic/preset_resolver.d.ts

@@ -1,6 +1,6 @@
 import type { ResolvedOptions } from '../builder.js';
 import type { OptimizeFor } from '../generated/sdk_spec/enums.js';
-import { type PresetDefaults, type PresetMedia, type PresetOp } from './presets/index.js';
+import { type PresetDefaults, type PresetMedia, type DetectedMedia, type PresetOp } from './presets/index.js';
 /**
  * The preset matrix version emitted on every resolve. Re-exported from the
  * GENERATED `sdk_spec/version.ts` (source of truth: contracts
@@ -17,7 +17,7 @@ export declare const PRESET_VERSION: "1.6";
  * extend the union.
  */
 export interface ResolveCompressOptionsInput {
-    readonly media: PresetMedia;
+    readonly media: DetectedMedia;
     readonly op: PresetOp;
     /** Defaults registered via `gisl.create({ presetDefaults: ... })`. */
     readonly presetDefaults?: PresetDefaults;
@@ -76,6 +76,28 @@ export interface ResolveCompressOptionsOutput {
  */
 export declare function _parseTargetSize(value: unknown): number;
 export declare const KNOWN_WIRE_FIELDS: Readonly<Record<PresetMedia, ReadonlySet<string>>>;
+/**
+ * Compress options that are `availability: planned` per mime-group, mirroring the
+ * shipped `availability/availability.json`
+ * `operations.compress.mime_groups.<group>.options.<opt>.availability`.
+ *
+ * Kept as a hand table (NOT a runtime read of the ~238KB availability sidecar) for
+ * the same reasons as {@link IMAGE_OUTPUT_ROUTES}: the gate stays browser-safe, and
+ * — decisively — it has NO dependency on which `@giveitsmaller/contracts` version a
+ * consumer resolved. A generated-metadata read would FAIL OPEN on an older published
+ * contracts (the rtkzl9gr failure mode), and fail-open is the wrong direction for a
+ * gate whose entire job is to fail closed.
+ *
+ * PINNED to `availability.json` by `tests/unit/preset-planned-conformance.test.ts`,
+ * which fails closed in BOTH directions — a contract regen that marks a new option
+ * `planned`, or unmarks one, breaks the build rather than the caller. Mirrored by PHP
+ * `PresetResolver::PLANNED_COMPRESS_OPTIONS`.
+ *
+ * `video.speed` is listed for a faithful projection even though no shipped preset
+ * cell emits it; the conformance test pins the whole projection, not just the keys
+ * we happen to use today.
+ */
+export declare const PLANNED_COMPRESS_OPTIONS: Readonly<Record<PresetMedia, ReadonlySet<string>>>;
 /**
  * Resolve the wire payload + introspection projection for a compress
  * operation call. Throws {@link GislConfigError} before any network

package/dist/ergonomic/preset_resolver.js

@@ -37,7 +37,7 @@
 import { sha256Hex } from '../sha256.js';
 import { GislConfigError } from '../errors.js';
 import { PRESET_VERSION as GENERATED_PRESET_VERSION } from '../generated/sdk_spec/version.js';
-import { ImageCompressPresetOptions, AudioCompressPresetOptions, VideoCompressPresetOptions, DocumentPdfCompressPresetOptions, DocumentOfficeCompressPresetOptions, DocumentOdfCompressPresetOptions, DocumentEpubCompressPresetOptions, definedFieldsOf, } from './presets/index.js';
+import { ImageCompressPresetOptions, AudioCompressPresetOptions, VideoCompressPresetOptions, DocumentOfficeCompressPresetOptions, DocumentOdfCompressPresetOptions, DocumentEpubCompressPresetOptions, definedFieldsOf, } from './presets/index.js';
 /**
  * The preset matrix version emitted on every resolve. Re-exported from the
  * GENERATED `sdk_spec/version.ts` (source of truth: contracts
@@ -175,8 +175,6 @@ function sdkDefaultRecord(media, op, optimize) {
             return { ...AudioCompressPresetOptions.shippedDefaultsFor(optimize) };
         case 'video':
             return { ...VideoCompressPresetOptions.shippedDefaultsFor(optimize) };
-        case 'document_pdf':
-            return { ...DocumentPdfCompressPresetOptions.shippedDefaultsFor(optimize) };
         case 'document_office':
             return { ...DocumentOfficeCompressPresetOptions.shippedDefaultsFor(optimize) };
         case 'document_odf':
@@ -213,9 +211,6 @@ function presetDefaultsCellRecord(defaults, media, op, optimize) {
         case 'video':
             cell = defaults.cellFor('video', 'compress', optimize);
             break;
-        case 'document_pdf':
-            cell = defaults.cellFor('document_pdf', 'compress', optimize);
-            break;
         case 'document_office':
             cell = defaults.cellFor('document_office', 'compress', optimize);
             break;
@@ -252,11 +247,24 @@ const MEDIA_FIELDS = Object.freeze({
     image: new Set(['quality', 'metadata', 'outputFormat']),
     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(['stripMacros', 'stripHiddenData', 'stripUnusedFonts']),
     document_odf: new Set(['stripMetadata', 'stripUnusedStyles']),
     document_epub: new Set(['fontSubsetting', 'stripUnusedCss']),
 });
+const OUT = (key) => ({ verb: 'output', key });
+const CROSS_VERB_OVERRIDES = Object.freeze({
+    image: Object.freeze({
+        width: OUT('width'), height: OUT('height'), fit: OUT('fit'),
+        autoOrient: OUT('auto_orient'), colorProfile: OUT('color_profile'),
+        progressive: OUT('progressive'), lossless: OUT('lossless'),
+        qualityPreset: OUT('quality_preset'), encodingMode: OUT('encoding_mode'),
+        targetSizeBytes: OUT('target_size_bytes'), chromaSubsampling: OUT('chroma_subsampling'),
+        optimizationLevel: OUT('optimization_level'), avifSpeed: OUT('avif_speed'),
+    }),
+    // convert() takes the target format positionally, not as an option.
+    audio: Object.freeze({ outputFormat: { verb: 'convert', key: null } }),
+    video: Object.freeze({ outputFormat: { verb: 'convert', key: null } }),
+});
 function detectMismatchedOverrides(media, overrides) {
     const expected = MEDIA_FIELDS[media];
     const keys = Object.keys(overrides);
@@ -270,6 +278,37 @@ function detectMismatchedOverrides(media, overrides) {
     const unknownFields = keys.filter((k) => !expected.has(k));
     if (unknownFields.length === 0)
         return;
+    // Options that are real for THIS media but belong to another verb are
+    // answered with that verb, before the other-media guess below — otherwise a
+    // key both this media and another one recognises (image `width` vs video
+    // `width`) gets blamed on the wrong media.
+    // Classified PER FIELD, not all-or-nothing: `{ width, codec }` on an image
+    // must still tell the caller that `width` is a legal resize on output(),
+    // rather than reverting to "you passed video options" for the pair.
+    const crossVerb = CROSS_VERB_OVERRIDES[media];
+    const crossVerbFields = crossVerb === undefined ? [] : unknownFields.filter((k) => crossVerb[k] !== undefined);
+    if (crossVerbFields.length > 0 && crossVerb !== undefined) {
+        const strays = unknownFields.filter((k) => crossVerb[k] === undefined);
+        const byVerb = new Map();
+        for (const k of crossVerbFields) {
+            const target = crossVerb[k];
+            const list = byVerb.get(target.verb) ?? [];
+            list.push(target.key ?? k);
+            byVerb.set(target.verb, list);
+        }
+        const clauses = [...byVerb.entries()].map(([verb, keys]) => verb === 'convert'
+            ? `${keys.join(', ')} is the format argument of convert()`
+            : `${keys.join(', ')} ${keys.length === 1 ? 'is an option' : 'are options'} on ${verb}()`);
+        const outputKeys = byVerb.get('output');
+        throw new GislConfigError(`presetOverrides for '${media}' contained ${crossVerbFields.join(', ')}, which ${crossVerbFields.length === 1 ? 'does' : 'do'} not belong on the compress preset surface: ${clauses.join('; ')}.` +
+            (strays.length > 0 ? ` Also unrecognised for '${media}': ${strays.join(', ')}.` : ''), {
+            reason: 'type_mismatch',
+            conflictingFields: unknownFields,
+            suggestion: outputKeys !== undefined
+                ? `Move ${outputKeys.join(', ')} to output(): .output(format, { ${outputKeys[0]}: … }).`
+                : 'Use convert(format) to change the output format.',
+        });
+    }
     // Look up which OTHER media owns every unknown field — if a single
     // OTHER media's field set covers them all, that's a type_mismatch.
     for (const otherMedia of Object.keys(MEDIA_FIELDS)) {
@@ -278,9 +317,9 @@ function detectMismatchedOverrides(media, overrides) {
         const otherSet = MEDIA_FIELDS[otherMedia];
         if (unknownFields.every((k) => otherSet.has(k))) {
             // PascalCase every underscore-separated segment so multi-segment
-            // media (`document_pdf` → `DocumentPdf…`) emit the actual exported
+            // media (`document_office` → `DocumentOffice…`) emit the actual exported
             // class name (code-review MEDIUM: previously emitted
-            // `Documentpdf…` which doesn't resolve in user code).
+            // `Documentoffice…` which doesn't resolve in user code).
             const className = otherMedia
                 .split('_')
                 .map((s) => s.charAt(0).toUpperCase() + s.slice(1))
@@ -321,11 +360,39 @@ export const KNOWN_WIRE_FIELDS = Object.freeze({
     image: new Set(['quality', 'metadata', 'output_format']),
     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(['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']),
 });
+/**
+ * Compress options that are `availability: planned` per mime-group, mirroring the
+ * shipped `availability/availability.json`
+ * `operations.compress.mime_groups.<group>.options.<opt>.availability`.
+ *
+ * Kept as a hand table (NOT a runtime read of the ~238KB availability sidecar) for
+ * the same reasons as {@link IMAGE_OUTPUT_ROUTES}: the gate stays browser-safe, and
+ * — decisively — it has NO dependency on which `@giveitsmaller/contracts` version a
+ * consumer resolved. A generated-metadata read would FAIL OPEN on an older published
+ * contracts (the rtkzl9gr failure mode), and fail-open is the wrong direction for a
+ * gate whose entire job is to fail closed.
+ *
+ * PINNED to `availability.json` by `tests/unit/preset-planned-conformance.test.ts`,
+ * which fails closed in BOTH directions — a contract regen that marks a new option
+ * `planned`, or unmarks one, breaks the build rather than the caller. Mirrored by PHP
+ * `PresetResolver::PLANNED_COMPRESS_OPTIONS`.
+ *
+ * `video.speed` is listed for a faithful projection even though no shipped preset
+ * cell emits it; the conformance test pins the whole projection, not just the keys
+ * we happen to use today.
+ */
+export const PLANNED_COMPRESS_OPTIONS = Object.freeze({
+    image: new Set([]),
+    audio: new Set([]),
+    video: new Set(['speed']),
+    document_office: new Set(['strip_hidden_data', 'strip_macros', '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
     // media's wire surface OR be one of the resolver-derived wire keys
@@ -444,6 +511,9 @@ function computePresetConfigHash(clientDefault, scopedDefault, callPresetOverrid
  * `optimize` unset ⇒ layer 1 contributes nothing; `resolvedOptions.preset = null`.
  */
 export function resolveCompressOptions(input) {
+    if (input.media === 'document_pdf') {
+        throw new GislConfigError('PDF compression was removed at contracts v2.166.0; convert() / transform() still accept PDF.', { reason: 'unsupported_media' });
+    }
     const { media, op, presetDefaults, scopedPresetDefaults, presetOverrides, optimize, explicitOptions, audioLossless } = input;
     if (op !== 'compress') {
         throw new GislConfigError(`Preset resolution is only wired for compress operations today; got op='${op}'.`, { reason: 'unsupported_op' });
@@ -531,6 +601,26 @@ export function resolveCompressOptions(input) {
         delete acc.merged.bitrate;
         acc.winners.delete('bitrate');
     }
+    // A shipped preset must never put an `availability: planned` option on the wire.
+    // The API rejects a planned option when the KEY IS PRESENT and ignores it when
+    // absent (`CreateWorkflowCommandHandler::recordPlannedFromMap` — a materialized
+    // default deliberately does NOT trigger it), so a value WE synthesized becomes a
+    // 422 `feature_not_available` at create that the caller never asked for. That is
+    // what broke every document compress with an `optimizeFor` in 0.21.0 (5Eksm9s7).
+    //
+    // Drop ONLY the sdkDefault-sourced ones. A planned option from any other layer is
+    // a caller choice — `clientDefault` and `scopedDefault` are user-registered via
+    // `gisl.create({ presetDefaults })` / `client.withPresetDefaults(...)`, not baked
+    // in by us — and is left in place for the server to refuse honestly. Same rule and
+    // same reason as the lossless-bitrate drop above: never silently swallow a key the
+    // caller chose. Do NOT "simplify" either of these into an always-drop; a silent
+    // no-op on an explicit request is worse than an honest 422.
+    for (const key of PLANNED_COMPRESS_OPTIONS[media]) {
+        if (acc.winners.get(key) === 'sdkDefault') {
+            delete acc.merged[key];
+            acc.winners.delete(key);
+        }
+    }
     // 7. Validate the merged payload (post-merge — catches cross-layer
     // disagreements). May throw GislConfigError with resolvedSnapshot.
     const explicitWireKeys = new Set();

package/dist/ergonomic/presets/image_compress.js

@@ -12,10 +12,22 @@
 // `mode` + `iccProfile` were REMOVED — the worker is lossy-only and always
 // strips metadata, so advertising a lossless mode or ICC-profile policy was
 // an over-claim. `progressive` is still a per-JPEG wire option but is no
-// longer carried in the preset cell. `width`/`height`/`fit`/`autoOrient`
-// were removed earlier — the image-compress worker never resized (resize-fit
-// lives on thumbnail/convert; video keeps its own fit). Per-call knobs are
-// deliberately excluded — they belong on the per-call argument shape.
+// longer carried in the preset cell.
+//
+// `width`/`height`/`fit`/`autoOrient` were removed earlier on the grounds that
+// "the image-compress worker never resized". CAREFUL — that is still true of
+// the Rust optimiser crate and NOT true end-to-end. Since contract v2.97.0
+// ("resize lives inside Output") the API canonicalises an image compress
+// carrying width/height/fit into a `convert` op, and convert IS the resize
+// engine, so such a request returns a genuinely resized file. Their absence
+// here is therefore a SURFACE choice, not a capability limit: resize is
+// expressed via `output()` (see `OutputOptions`), which the compress
+// conformance gate records as CROSS_VERB_ROUTING and self-verifies. Reading
+// this comment as "unsupported" is what produced cySAEZHR. Whether compress()
+// should ALSO carry them is an open ergonomic-expansion decision, not a bug.
+//
+// Per-call knobs are deliberately excluded — they belong on the per-call
+// argument shape.
 import { shippedDefaultsFor as f3ShippedDefaultsFor } from '../../generated/sdk_spec/presets.js';
 import { translateEnum } from './_translate.js';
 export class ImageCompressPresetOptions {

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

@@ -2,27 +2,31 @@ import { OptimizeFor } from '../../generated/sdk_spec/enums.js';
 import { ImageCompressPresetOptions, type ImageCompressPresetOptionsInput } from './image_compress.js';
 import { AudioCompressPresetOptions, type AudioCompressPresetOptionsInput } from './audio_compress.js';
 import { VideoCompressPresetOptions, type VideoCompressPresetOptionsInput } from './video_compress.js';
-import { DocumentPdfCompressPresetOptions, type DocumentPdfCompressPresetOptionsInput } from './document_pdf_compress.js';
 import { DocumentOfficeCompressPresetOptions, type DocumentOfficeCompressPresetOptionsInput } from './document_office_compress.js';
 import { DocumentOdfCompressPresetOptions, type DocumentOdfCompressPresetOptionsInput } from './document_odf_compress.js';
 import { DocumentEpubCompressPresetOptions, type DocumentEpubCompressPresetOptionsInput } from './document_epub_compress.js';
 export { ImageCompressPresetOptions, type ImageCompressPresetOptionsInput, } from './image_compress.js';
 export { AudioCompressPresetOptions, type AudioCompressPresetOptionsInput, } from './audio_compress.js';
 export { VideoCompressPresetOptions, type VideoCompressPresetOptionsInput, } from './video_compress.js';
-export { DocumentPdfCompressPresetOptions, type DocumentPdfCompressPresetOptionsInput, } from './document_pdf_compress.js';
 export { DocumentOfficeCompressPresetOptions, type DocumentOfficeCompressPresetOptionsInput, } from './document_office_compress.js';
 export { DocumentOdfCompressPresetOptions, type DocumentOdfCompressPresetOptionsInput, } from './document_odf_compress.js';
 export { DocumentEpubCompressPresetOptions, type DocumentEpubCompressPresetOptionsInput, } from './document_epub_compress.js';
-export { OptimizeFor, ImageMetadataPolicy, ImageFormat, VideoCodec, VideoPreset, VideoFit, AudioBitrate, AudioCodec, AudioSampleRate, PdfProfile, PdfColorspace, } from '../../generated/sdk_spec/enums.js';
+export { OptimizeFor, ImageMetadataPolicy, ImageFormat, VideoCodec, VideoPreset, VideoFit, AudioBitrate, AudioCodec, AudioSampleRate, } from '../../generated/sdk_spec/enums.js';
 /** Supported media×op pairs for preset cells in T4a. Compress-only. */
-export type PresetMedia = 'image' | 'audio' | 'video' | 'document_pdf' | 'document_office' | 'document_odf' | 'document_epub';
+export type PresetMedia = 'image' | 'audio' | 'video' | 'document_office' | 'document_odf' | 'document_epub';
+/**
+ * Media the file-first detector can identify — the compressible
+ * `PresetMedia` set PLUS `document_pdf`, which is detectable (and a valid
+ * watermark-reject / convert / transform base) but NOT compressible.
+ */
+export type DetectedMedia = PresetMedia | 'document_pdf';
 export type PresetOp = 'compress';
 /**
  * Union of leaf-DTO types the resolver will see from `cellFor()`.
  * Discriminated by which `media` the caller passes — the type system
  * narrows the return automatically via the overload set below.
  */
-export type AnyPresetOptions = ImageCompressPresetOptions | AudioCompressPresetOptions | VideoCompressPresetOptions | DocumentPdfCompressPresetOptions | DocumentOfficeCompressPresetOptions | DocumentOdfCompressPresetOptions | DocumentEpubCompressPresetOptions;
+export type AnyPresetOptions = ImageCompressPresetOptions | AudioCompressPresetOptions | VideoCompressPresetOptions | DocumentOfficeCompressPresetOptions | DocumentOdfCompressPresetOptions | DocumentEpubCompressPresetOptions;
 /**
  * Per-cell field-merge: parent fields ⊕ child fields where defined.
  * Re-construct the leaf DTO via the matching `<LeafClass>.from(merged)`
@@ -73,8 +77,6 @@ export declare class PresetDefaults {
     audioCompress(level: OptimizeFor, input?: AudioCompressPresetOptionsInput): PresetDefaults;
     /** Register a (level, delta) on the video-compress cell. Immutable. */
     videoCompress(level: OptimizeFor, input?: VideoCompressPresetOptionsInput): PresetDefaults;
-    /** Register a (level, delta) on the document-pdf-compress cell. Immutable. */
-    pdfCompress(level: OptimizeFor, input?: DocumentPdfCompressPresetOptionsInput): PresetDefaults;
     /** Register a (level, delta) on the document-office-compress cell. Immutable. */
     officeCompress(level: OptimizeFor, input?: DocumentOfficeCompressPresetOptionsInput): PresetDefaults;
     /** Register a (level, delta) on the document-odf-compress cell. Immutable. */
@@ -84,7 +86,6 @@ export declare class PresetDefaults {
     /** @internal */ cellFor(media: 'image', op: 'compress', level: OptimizeFor): ImageCompressPresetOptions | undefined;
     /** @internal */ cellFor(media: 'audio', op: 'compress', level: OptimizeFor): AudioCompressPresetOptions | undefined;
     /** @internal */ cellFor(media: 'video', op: 'compress', level: OptimizeFor): VideoCompressPresetOptions | undefined;
-    /** @internal */ cellFor(media: 'document_pdf', op: 'compress', level: OptimizeFor): DocumentPdfCompressPresetOptions | undefined;
     /** @internal */ cellFor(media: 'document_office', op: 'compress', level: OptimizeFor): DocumentOfficeCompressPresetOptions | undefined;
     /** @internal */ cellFor(media: 'document_odf', op: 'compress', level: OptimizeFor): DocumentOdfCompressPresetOptions | undefined;
     /** @internal */ cellFor(media: 'document_epub', op: 'compress', level: OptimizeFor): DocumentEpubCompressPresetOptions | undefined;

package/dist/ergonomic/presets/index.js

@@ -28,7 +28,6 @@
 import { ImageCompressPresetOptions, } from './image_compress.js';
 import { AudioCompressPresetOptions, } from './audio_compress.js';
 import { VideoCompressPresetOptions, } from './video_compress.js';
-import { DocumentPdfCompressPresetOptions, } from './document_pdf_compress.js';
 import { DocumentOfficeCompressPresetOptions, } from './document_office_compress.js';
 import { DocumentOdfCompressPresetOptions, } from './document_odf_compress.js';
 import { DocumentEpubCompressPresetOptions, } from './document_epub_compress.js';
@@ -36,12 +35,11 @@ import { DocumentEpubCompressPresetOptions, } from './document_epub_compress.js'
 export { ImageCompressPresetOptions, } from './image_compress.js';
 export { AudioCompressPresetOptions, } from './audio_compress.js';
 export { VideoCompressPresetOptions, } from './video_compress.js';
-export { DocumentPdfCompressPresetOptions, } from './document_pdf_compress.js';
 export { DocumentOfficeCompressPresetOptions, } from './document_office_compress.js';
 export { DocumentOdfCompressPresetOptions, } from './document_odf_compress.js';
 export { DocumentEpubCompressPresetOptions, } from './document_epub_compress.js';
 // Re-export ergonomic enums for callers (single canonical path).
-export { OptimizeFor, ImageMetadataPolicy, ImageFormat, VideoCodec, VideoPreset, VideoFit, AudioBitrate, AudioCodec, AudioSampleRate, PdfProfile, PdfColorspace, } from '../../generated/sdk_spec/enums.js';
+export { OptimizeFor, ImageMetadataPolicy, ImageFormat, VideoCodec, VideoPreset, VideoFit, AudioBitrate, AudioCodec, AudioSampleRate, } from '../../generated/sdk_spec/enums.js';
 function cellKeyOf(media, op) {
     return `${media}_${op}`;
 }
@@ -89,8 +87,6 @@ function mergePresetOptions(cellKey, parentOpts, childOpts) {
             return AudioCompressPresetOptions.from(mergedFields);
         case 'video_compress':
             return VideoCompressPresetOptions.from(mergedFields);
-        case 'document_pdf_compress':
-            return DocumentPdfCompressPresetOptions.from(mergedFields);
         case 'document_office_compress':
             return DocumentOfficeCompressPresetOptions.from(mergedFields);
         case 'document_odf_compress':
@@ -178,10 +174,6 @@ export class PresetDefaults {
     videoCompress(level, input = {}) {
         return new PresetDefaults(withCellEntry(this.cells, 'video_compress', level, VideoCompressPresetOptions.from(input)));
     }
-    /** Register a (level, delta) on the document-pdf-compress cell. Immutable. */
-    pdfCompress(level, input = {}) {
-        return new PresetDefaults(withCellEntry(this.cells, 'document_pdf_compress', level, DocumentPdfCompressPresetOptions.from(input)));
-    }
     /** Register a (level, delta) on the document-office-compress cell. Immutable. */
     officeCompress(level, input = {}) {
         return new PresetDefaults(withCellEntry(this.cells, 'document_office_compress', level, DocumentOfficeCompressPresetOptions.from(input)));

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

@@ -1,6 +1,20 @@
 import { VideoCodec, VideoPreset, VideoFit, AudioCodec, AudioBitrate, OptimizeFor } from '../../generated/sdk_spec/enums.js';
 export interface VideoCompressPresetOptionsInput {
     readonly codec?: VideoCodec;
+    /**
+     * Target output size (`'50MB'`-style string — BINARY units, 1 KB = 1024 — or a byte
+     * count). Derived by the resolver into `target_size_bytes` + `encoding_mode:
+     * 'target_size'`.
+     *
+     * **NOT AVAILABLE FOR LONG INPUTS.** A compress whose input duration routes to the
+     * long-form path rejects it (`reject_long_form_target_size`): that path is
+     * single-pass-CRF by construction and two-pass target-size is unbuilt. The request
+     * fails during execution, and the SDK cannot warn earlier — routing is decided
+     * server-side at create-plan time, so there is nothing here to check it against.
+     * Short-form compresses honour it normally. Tracked by `zJN6XIi5`, blocked on a
+     * contract that can express per-execution-path availability. The same limit applies
+     * to {@link MergeOptions.targetSize}.
+     */
     readonly targetSize?: string | number;
     readonly crf?: number;
     readonly preset?: VideoPreset;

package/dist/errors.d.ts

@@ -1,4 +1,4 @@
-import type { AuthErrorResponse, AuthRejectionEnvelope, AuthRejectionEnvelopeErrorTypeEnum, BalanceExhaustedResponse, FeatureNotAvailableResponse, FeatureTierRestrictedResponse, ProbePendingResponse, TierRestrictionResponse, UploadDurationExceedsTierResponse, UploadSizeExceedsTierResponse, WorkflowExpiredResponse } from '@giveitsmaller/contracts/openapi';
+import type { AuthErrorResponse, AuthRejectionEnvelope, AuthRejectionEnvelopeErrorTypeEnum, BalanceExhaustedResponse, FeatureNotAvailableResponse, FeatureTierRestrictedResponse, LongFormConcurrencyLimitResponse, ProbePendingResponse, TierRestrictionResponse, UploadDurationExceedsTierResponse, UploadSizeExceedsTierResponse, WorkflowExpiredResponse } from '@giveitsmaller/contracts/openapi';
 import type { ErrorCategory } from './generated/sdk_spec/errors.js';
 import type { RateLimitSnapshot } from './retry-metadata.js';
 export declare class GislError extends Error {
@@ -134,6 +134,49 @@ export declare class GislBalanceExhaustedError extends GislApiError {
     readonly payload: BalanceExhaustedResponse;
     constructor(statusCode: number, errorMessage: string, payload: BalanceExhaustedResponse, path?: string, extra?: Omit<GislApiErrorOptions, 'payload'>);
 }
+/**
+ * `429` on `POST /api/workflows` when the caller already holds the maximum
+ * number of concurrent in-flight long-form (Fargate) workflows their tier
+ * permits (Pro 2 / Max 5; Enterprise uncapped). DISTINCT from an infrastructure
+ * rate-limit `429`: it carries the machine code `LONG_FORM_CONCURRENCY_LIMIT_EXCEEDED`
+ * and a `links.upgrade` deep link, and has **no `Retry-After`** — the limit clears
+ * when an in-flight long-form workflow finishes, not on a timer. A generic infra
+ * rate-limit `429` (no matching code) surfaces as the base {@link GislApiError}
+ * instead, where {@link GislApiError.retryAfterSeconds} applies.
+ *
+ * Dispatched on the `error` CODE, not `error_type` (the envelope carries none).
+ *
+ * @example
+ * try {
+ *   await client.createWorkflow({ jobs });
+ * } catch (e) {
+ *   if (e instanceof GislLongFormConcurrencyError) {
+ *     showUpgradeCta(e.upgradeUrl); // wait on completion or upgrade — do NOT back off
+ *   }
+ *   throw e;
+ * }
+ */
+export declare class GislLongFormConcurrencyError extends GislApiError {
+    readonly payload: LongFormConcurrencyLimitResponse;
+    constructor(statusCode: number, errorMessage: string, payload: LongFormConcurrencyLimitResponse, path?: string, extra?: Omit<GislApiErrorOptions, 'payload'>);
+    /**
+     * ALWAYS `false`, overriding the base 429-implies-retryable heuristic
+     * (UO1xYecu). This 429 is not a rate limit: it carries no `Retry-After` and
+     * clears only when an in-flight long-form workflow finishes, so a back-off
+     * retries into a wall that no amount of waiting-then-retrying opens. The base
+     * accessor reported `true` purely from the status, contradicting this class's
+     * own documented handling ("wait on completion or upgrade — do NOT back off")
+     * and instructing the one recovery that cannot work.
+     *
+     * Overridden per-class rather than via a code table because this is the only
+     * such code today; the general fix — an explicit taxonomy verdict outranking
+     * the status heuristic — arrives with the `error-taxonomy.yaml` `retryable`
+     * enum (contracts `plwcAqBr`), tracked on UO1xYecu.
+     */
+    get retryable(): boolean;
+    /** The pricing / upgrade deep link (`links.upgrade`), or `undefined` when absent. */
+    get upgradeUrl(): string | undefined;
+}
 export declare class GislTierRestrictedError extends GislApiError {
     readonly payload: TierRestrictionResponse;
     constructor(statusCode: number, errorMessage: string, payload: TierRestrictionResponse, path?: string, extra?: Omit<GislApiErrorOptions, 'payload'>);
@@ -411,7 +454,63 @@ export declare class GislBundleAlreadyArchivedError extends GislConfigError {
     constructor();
 }
 export declare class GislTimeoutError extends GislError {
-    constructor(message: string);
+    /**
+     * The workflow this timeout is scoped to, when the SDK knows it. Set on a
+     * timed-out `run()` / `wait()` / poll / download once the workflow has been
+     * created: a timeout does NOT mean the work failed — the server keeps
+     * processing, so poll `client.getWorkflowStatus(workflowId)` /
+     * `getWorkflowDownloads(workflowId)` to recover a result that completed after
+     * the deadline, instead of re-running (a re-run re-uploads and, for
+     * authenticated callers, settles a SECOND charge for the same deliverable).
+     *
+     * `undefined` when the SDK has no id to offer. That is NOT a guarantee that
+     * nothing was created or charged: it covers both the safe case (an upload /
+     * probe timeout before any workflow existed) AND the AMBIGUOUS case (the
+     * `POST /api/workflows` request itself timed out — the server may have
+     * created and charged the workflow before its response was lost). Treat an
+     * absent id as "cannot auto-recover", not "clean slate": reconcile (e.g. list
+     * recent workflows) before re-running rather than assuming nothing happened.
+     */
+    readonly workflowId?: string;
+    constructor(message: string, workflowId?: string);
+}
+/**
+ * A `mapEach` fan-out timed out mid-batch — the deadline elapsed either while a
+ * child was still running (the common case) or cleanly between child runs. The
+ * parent and some children have ALREADY completed, so re-running the whole batch
+ * re-does finished work. This carries their ids so the caller can poll them (via
+ * `client.getWorkflowStatus` / `getWorkflowDownloads`) to recover the finished
+ * work and re-run ONLY the children that were never created.
+ *
+ * Subclasses {@link GislTimeoutError}, so an existing
+ * `catch (e) { if (e instanceof GislTimeoutError) … }` still catches it. The
+ * inherited `workflowId` carries the IN-FLIGHT child — the one that was running
+ * when the deadline elapsed (a child's own timeout, the common path) — or stays
+ * `undefined` when the deadline elapsed cleanly BETWEEN children (no in-flight
+ * child). To recover, poll `workflowId` (if set) + {@link parentWorkflowId} +
+ * {@link completedWorkflowIds}, then re-run only the children that never started.
+ *
+ * NOTE on double-charge: the server-side create-dedupe (DSxwCetg) is what
+ * prevents a byte-identical child re-create from settling a SECOND charge within
+ * the dedup window; this error's job is efficient RECOVERY (skip the completed
+ * work) + defense-in-depth, not the sole charge guard.
+ */
+export declare class GislFanOutTimeoutError extends GislTimeoutError {
+    /** The child workflows that completed before the deadline elapsed. */
+    readonly completedWorkflowIds: readonly string[];
+    /** The parent workflow, which ran to completion before the fan-out began. */
+    readonly parentWorkflowId?: string;
+    constructor(message: string, opts: {
+        completedWorkflowIds: readonly string[];
+        parentWorkflowId?: string;
+        /**
+         * The in-flight child that timed out mid-run (its own deadline elapsed);
+         * `undefined` for a clean between-children timeout with no child running.
+         */
+        workflowId?: string;
+        /** The underlying child {@link GislTimeoutError}, preserved for chaining. */
+        cause?: unknown;
+    });
 }
 /**
  * Transport-level failure: the underlying `fetch` (or other transport) could

package/dist/errors.js

@@ -145,6 +145,55 @@ export class GislBalanceExhaustedError extends GislApiError {
         this.name = 'GislBalanceExhaustedError';
     }
 }
+/**
+ * `429` on `POST /api/workflows` when the caller already holds the maximum
+ * number of concurrent in-flight long-form (Fargate) workflows their tier
+ * permits (Pro 2 / Max 5; Enterprise uncapped). DISTINCT from an infrastructure
+ * rate-limit `429`: it carries the machine code `LONG_FORM_CONCURRENCY_LIMIT_EXCEEDED`
+ * and a `links.upgrade` deep link, and has **no `Retry-After`** — the limit clears
+ * when an in-flight long-form workflow finishes, not on a timer. A generic infra
+ * rate-limit `429` (no matching code) surfaces as the base {@link GislApiError}
+ * instead, where {@link GislApiError.retryAfterSeconds} applies.
+ *
+ * Dispatched on the `error` CODE, not `error_type` (the envelope carries none).
+ *
+ * @example
+ * try {
+ *   await client.createWorkflow({ jobs });
+ * } catch (e) {
+ *   if (e instanceof GislLongFormConcurrencyError) {
+ *     showUpgradeCta(e.upgradeUrl); // wait on completion or upgrade — do NOT back off
+ *   }
+ *   throw e;
+ * }
+ */
+export class GislLongFormConcurrencyError extends GislApiError {
+    constructor(statusCode, errorMessage, payload, path, extra) {
+        super(statusCode, errorMessage, path, undefined, buildOptionsWithPayload(payload, extra));
+        this.name = 'GislLongFormConcurrencyError';
+    }
+    /**
+     * ALWAYS `false`, overriding the base 429-implies-retryable heuristic
+     * (UO1xYecu). This 429 is not a rate limit: it carries no `Retry-After` and
+     * clears only when an in-flight long-form workflow finishes, so a back-off
+     * retries into a wall that no amount of waiting-then-retrying opens. The base
+     * accessor reported `true` purely from the status, contradicting this class's
+     * own documented handling ("wait on completion or upgrade — do NOT back off")
+     * and instructing the one recovery that cannot work.
+     *
+     * Overridden per-class rather than via a code table because this is the only
+     * such code today; the general fix — an explicit taxonomy verdict outranking
+     * the status heuristic — arrives with the `error-taxonomy.yaml` `retryable`
+     * enum (contracts `plwcAqBr`), tracked on UO1xYecu.
+     */
+    get retryable() {
+        return false;
+    }
+    /** The pricing / upgrade deep link (`links.upgrade`), or `undefined` when absent. */
+    get upgradeUrl() {
+        return this.payload.links?.upgrade;
+    }
+}
 export class GislTierRestrictedError extends GislApiError {
     constructor(statusCode, errorMessage, payload, path, extra) {
         super(statusCode, errorMessage, path, undefined, buildOptionsWithPayload(payload, extra));
@@ -447,9 +496,67 @@ export class GislBundleAlreadyArchivedError extends GislConfigError {
     }
 }
 export class GislTimeoutError extends GislError {
-    constructor(message) {
+    /**
+     * The workflow this timeout is scoped to, when the SDK knows it. Set on a
+     * timed-out `run()` / `wait()` / poll / download once the workflow has been
+     * created: a timeout does NOT mean the work failed — the server keeps
+     * processing, so poll `client.getWorkflowStatus(workflowId)` /
+     * `getWorkflowDownloads(workflowId)` to recover a result that completed after
+     * the deadline, instead of re-running (a re-run re-uploads and, for
+     * authenticated callers, settles a SECOND charge for the same deliverable).
+     *
+     * `undefined` when the SDK has no id to offer. That is NOT a guarantee that
+     * nothing was created or charged: it covers both the safe case (an upload /
+     * probe timeout before any workflow existed) AND the AMBIGUOUS case (the
+     * `POST /api/workflows` request itself timed out — the server may have
+     * created and charged the workflow before its response was lost). Treat an
+     * absent id as "cannot auto-recover", not "clean slate": reconcile (e.g. list
+     * recent workflows) before re-running rather than assuming nothing happened.
+     */
+    workflowId;
+    constructor(message, workflowId) {
         super(message);
         this.name = 'GislTimeoutError';
+        // Normalise an empty id to "absent" — an empty string is not a usable
+        // recovery handle (some throw sites derive the id as `… ?? ''`).
+        this.workflowId = workflowId === '' ? undefined : workflowId;
+    }
+}
+/**
+ * A `mapEach` fan-out timed out mid-batch — the deadline elapsed either while a
+ * child was still running (the common case) or cleanly between child runs. The
+ * parent and some children have ALREADY completed, so re-running the whole batch
+ * re-does finished work. This carries their ids so the caller can poll them (via
+ * `client.getWorkflowStatus` / `getWorkflowDownloads`) to recover the finished
+ * work and re-run ONLY the children that were never created.
+ *
+ * Subclasses {@link GislTimeoutError}, so an existing
+ * `catch (e) { if (e instanceof GislTimeoutError) … }` still catches it. The
+ * inherited `workflowId` carries the IN-FLIGHT child — the one that was running
+ * when the deadline elapsed (a child's own timeout, the common path) — or stays
+ * `undefined` when the deadline elapsed cleanly BETWEEN children (no in-flight
+ * child). To recover, poll `workflowId` (if set) + {@link parentWorkflowId} +
+ * {@link completedWorkflowIds}, then re-run only the children that never started.
+ *
+ * NOTE on double-charge: the server-side create-dedupe (DSxwCetg) is what
+ * prevents a byte-identical child re-create from settling a SECOND charge within
+ * the dedup window; this error's job is efficient RECOVERY (skip the completed
+ * work) + defense-in-depth, not the sole charge guard.
+ */
+export class GislFanOutTimeoutError extends GislTimeoutError {
+    /** The child workflows that completed before the deadline elapsed. */
+    completedWorkflowIds;
+    /** The parent workflow, which ran to completion before the fan-out began. */
+    parentWorkflowId;
+    constructor(message, opts) {
+        // The inherited workflowId is the in-flight child (or undefined between children).
+        super(message, opts.workflowId);
+        this.name = 'GislFanOutTimeoutError';
+        this.completedWorkflowIds = [...opts.completedWorkflowIds];
+        this.parentWorkflowId = opts.parentWorkflowId === '' ? undefined : opts.parentWorkflowId;
+        if (opts.cause !== undefined) {
+            this.cause = opts.cause;
+        }
     }
 }
 /**