@giveitsmaller/sdk 0.16.0 → 0.17.0

package/README.md

@@ -69,6 +69,27 @@ Docs are published in the [giveitsmaller-sdks](https://github.com/AntonioCS/give
 - **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)
 
+## Contributing: the committed `dist/`
+
+Unlike most packages, `packages/typescript/dist/` is **committed**, not gitignored.
+This is deliberate: consumers that install the SDK via the `file:` protocol (the
+e2e canary, the frontend, the API repo, local dev) get whatever is on disk — npm
+does **not** run `prepare`/`prepack` for `file:` deps, so a `dist/` that lagged
+behind `src/` would silently ship stale exports.
+
+When you change anything under `src/`, rebuild and commit `dist/`:
+
+```bash
+npm run build   # tsc → dist/
+```
+
+CI enforces this with a freshness guard that rebuilds `dist/` and fails the PR on
+any `git diff` against the committed tree (mirroring the `git diff --exit-code
+generated/` drift rule). `typescript` is pinned to an exact version so the rebuild
+is reproducible. New hand-written SDK packages (PHP/Python) that grow a build step
+should follow the same commit-`dist`-and-guard convention to avoid reintroducing
+the `file:` gap.
+
 ## License
 
 MIT — see the [LICENSE](https://github.com/AntonioCS/giveitsmaller-sdks/blob/main/LICENSE) file.

package/dist/_audit.js

@@ -68,6 +68,17 @@ export function _runAudit() {
     accept();
     // T2 / xVDTIm8C — operation-builder surface.
     accept();
+    // 8yqUXLCS — pin the credits/limits accessor SIGNATURES on ErgonomicClient.
+    // accept<ErgonomicClient>() proves the type compiles; these prove the three
+    // methods EXIST and their signatures/return types match (indexed access errors
+    // if a method is missing; the typed LHS errors if the signature drifts). The
+    // RHS is a type-only cast (`null as unknown as …`) — no runtime property read.
+    const _creditsSig = null;
+    const _creditsUsageSig = null;
+    const _limitsSig = null;
+    void _creditsSig;
+    void _creditsUsageSig;
+    void _limitsSig;
     accept();
     accept();
     accept();
@@ -113,8 +124,6 @@ export function _runAudit() {
     accept();
     accept();
     accept();
-    accept();
-    accept();
     // T4b / 27rE1fZn — preset resolver public types.
     accept();
     accept();
@@ -136,6 +145,7 @@ export function _runAudit() {
     accept();
     accept();
     accept();
+    accept();
     // FF5a / Ao8RPVxD — file-first Handle reattach surface.
     accept();
     accept();

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { AudioWatermarkDecodeRequest, AudioWatermarkDecodeResponse, ExternalImportCreatedResponse, ExternalImportRequest, LoginUserRequest, LoginUser200ResponseData, ContactRequest, CreditsBalanceResponse, CreditsUsageResponse, UploadResponse, UploadProbeResponse, WorkflowCancelResponse, WorkflowCreateResponse, WorkflowResumeResponse, WorkflowStatusResponse, WorkflowListResponse, WorkflowSummary, WorkflowDownloadResponse, MetadataResponse, RetryResponse } from '@giveitsmaller/contracts/openapi';
+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';
 export declare const MULTIPART_CONCURRENCY_DEFAULT: 4;
 export declare const DEFAULT_MULTIPART_FIRST_CHUNK_SIZE: number;
@@ -245,6 +245,13 @@ export declare class GislClient {
      * off the error envelope.
      */
     getCreditsBalance(): Promise<CreditsBalanceResponse>;
+    /**
+     * Fetch the caller's effective account limits (the tier-resolved caps:
+     * upload/merge size + total caps, surfaced override-aware). `GET
+     * /api/v2/account/limits`. The success envelope's `data` is unwrapped to the
+     * {@link AccountLimits} model (mirrors {@link getCreditsBalance}).
+     */
+    getAccountLimits(): Promise<AccountLimits>;
     /**
      * Authenticate with email/password. On success the server issues a
      * session cookie via `Set-Cookie`; subsequent requests authenticate

package/dist/client.js

@@ -4,7 +4,7 @@
 // blobByteSource, which never touches these). Kept as a STATIC import (not a
 // dynamic one) so `vi.mock('node:fs/promises')` still intercepts it in tests.
 import { open, stat, basename } from './node-fs.js';
-import { AudioWatermarkDecodeRequestToJSON, AudioWatermarkDecodeResponseFromJSON, ExternalImportCreatedResponseFromJSON, ExternalImportRequestToJSON, LoginUser200ResponseDataFromJSON, 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 { 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';
 import { parseSseStream } from './sse.js';
 const DEFAULT_TIMEOUT_MS = 30_000;
@@ -1934,6 +1934,17 @@ export class GislClient {
             deserialize: CreditsBalanceResponseFromJSON,
         });
     }
+    /**
+     * Fetch the caller's effective account limits (the tier-resolved caps:
+     * upload/merge size + total caps, surfaced override-aware). `GET
+     * /api/v2/account/limits`. The success envelope's `data` is unwrapped to the
+     * {@link AccountLimits} model (mirrors {@link getCreditsBalance}).
+     */
+    async getAccountLimits() {
+        return this.request('GET', '/api/v2/account/limits', {
+            deserialize: AccountLimitsFromJSON,
+        });
+    }
     // -----------------------------------------------------------------------
     // Auth
     // -----------------------------------------------------------------------

package/dist/ergonomic/image_output_routes.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Route-aware image "Output" model (card YNLrGhNo, contracts tewB37Jg / v2.97.0).
+ *
+ * The file-first `output()`/`resize()` helpers resolve a single user-facing
+ * "Output" operation to the right underlying wire op + options, driven by the
+ * contract's `accepted-options/image-output-routes.json` projection. The route is
+ * `(input format token, output_format token)`:
+ *   - `same_format` (output == input) → `source_op: compress` (libcaesium optimiser),
+ *     wire `output_format: 'original'`;
+ *   - `format_change` (output != input) → `source_op: convert` (transcoder),
+ *     wire `output_format: <token>`.
+ *
+ * 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`.
+ *
+ * This hand table MIRRORS the generated projection and is PINNED to it by
+ * `output-route-conformance.test.ts` (the watermark-capability-gate precedent) —
+ * a contract regen that changes a route's source_op / honored / planned options
+ * fails that test. Kept a hand table (not a runtime JSON read) so the gate is
+ * browser-safe, exactly like {@link WATERMARK_CAPABILITY}. Mirrored by the PHP
+ * `ImageOutputRoutes`.
+ */
+/** The resize option keys — input-keyed, raster-only (see module doc). */
+export declare const RESIZE_KEYS: readonly ["width", "height", "fit"];
+/** Image area cap shared by every resizable route (projection `max_output_pixels`). */
+export declare const MAX_OUTPUT_PIXELS = 16000000;
+/**
+ * Output formats reachable via the legacy `compress(output_format=…)` facade
+ * (projection `facade_managed_outputs`). Used ONLY as the undetectable-input
+ * fallback — a detectable input always routes via `source_op`.
+ */
+export declare const FACADE_MANAGED_OUTPUTS: readonly string[];
+interface RouteCell {
+    readonly honored: readonly string[];
+    readonly planned: readonly string[];
+}
+/**
+ * Per-route, per-output-format honored + planned option keys, mirroring
+ * `image-output-routes.json` `media.image`. `source_op` is uniform
+ * (same_format→compress, format_change→convert) so it is a derivation rule, not
+ * a table column. `same_format` is keyed by the INPUT token; `format_change` by
+ * the OUTPUT token.
+ */
+export declare const IMAGE_OUTPUT_ROUTES: {
+    readonly same_format: Readonly<Record<string, RouteCell>>;
+    readonly format_change: Readonly<Record<string, RouteCell>>;
+};
+export type OutputRoute = 'same_format' | 'format_change';
+/** A resolved Output lowering target. */
+export interface ResolvedOutputRoute {
+    readonly route: OutputRoute;
+    /** The wire op to emit. */
+    readonly sourceOp: 'compress' | 'convert';
+    /** The wire `output_format` value ('original' for same_format, the token for format_change). */
+    readonly outputFormatWire: string;
+    /** The input format token the route resolved against (for per-value gating). */
+    readonly inputToken: string;
+    /** Effective honored option keys (incl. input-keyed resize on format_change). */
+    readonly honored: ReadonlySet<string>;
+    /** Planned option keys → gate as `feature_not_available`. */
+    readonly planned: ReadonlySet<string>;
+}
+/** The bare format token for a MIME type, or undefined if not a known image MIME. */
+export declare function tokenForMime(mime: string): string | undefined;
+/** The bare format token for a filename / path extension, or undefined. */
+export declare function tokenForPath(path: string): string | undefined;
+/** Every image format token the projection knows (for validation / tests). */
+export declare function knownImageTokens(): ReadonlySet<string>;
+/**
+ * Resolve an Output request to its wire op + gating sets. Returns undefined when
+ * the route is unrepresentable (e.g. converting TO a format no `format_change`
+ * cell covers). `outputFormat` undefined → same-format (keep input format).
+ */
+export declare function resolveOutputRoute(inputToken: string, outputFormat: string | undefined): ResolvedOutputRoute | undefined;
+/**
+ * Whether a specific VALUE of an option is `availability: 'planned'` for the
+ * given input format — the per-value gate (e.g. `metadata: 'keep'` is planned
+ * even though the `metadata` key is honored). Reads the generated
+ * `compressMetadata` `per_value_availability`; same_format only (the only route
+ * where value-level options like `metadata` are honored). Returns false when the
+ * option / value / group is unknown (no gate).
+ */
+export declare function isPlannedValue(inputToken: string, optionKey: string, value: unknown): boolean;
+export {};

package/dist/ergonomic/image_output_routes.js

@@ -0,0 +1,155 @@
+/**
+ * Route-aware image "Output" model (card YNLrGhNo, contracts tewB37Jg / v2.97.0).
+ *
+ * The file-first `output()`/`resize()` helpers resolve a single user-facing
+ * "Output" operation to the right underlying wire op + options, driven by the
+ * contract's `accepted-options/image-output-routes.json` projection. The route is
+ * `(input format token, output_format token)`:
+ *   - `same_format` (output == input) → `source_op: compress` (libcaesium optimiser),
+ *     wire `output_format: 'original'`;
+ *   - `format_change` (output != input) → `source_op: convert` (transcoder),
+ *     wire `output_format: <token>`.
+ *
+ * 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`.
+ *
+ * This hand table MIRRORS the generated projection and is PINNED to it by
+ * `output-route-conformance.test.ts` (the watermark-capability-gate precedent) —
+ * a contract regen that changes a route's source_op / honored / planned options
+ * fails that test. Kept a hand table (not a runtime JSON read) so the gate is
+ * browser-safe, exactly like {@link WATERMARK_CAPABILITY}. Mirrored by the PHP
+ * `ImageOutputRoutes`.
+ */
+import { compressMetadata } from '@giveitsmaller/contracts/operations';
+/** The resize option keys — input-keyed, raster-only (see module doc). */
+export const RESIZE_KEYS = ['width', 'height', 'fit'];
+/** Image area cap shared by every resizable route (projection `max_output_pixels`). */
+export const MAX_OUTPUT_PIXELS = 16_000_000;
+/**
+ * Output formats reachable via the legacy `compress(output_format=…)` facade
+ * (projection `facade_managed_outputs`). Used ONLY as the undetectable-input
+ * fallback — a detectable input always routes via `source_op`.
+ */
+export const FACADE_MANAGED_OUTPUTS = ['webp'];
+/** Canonical MIME → bare format token (projection `mime_tokens`). */
+const MIME_TOKEN = {
+    'image/avif': 'avif',
+    'image/gif': 'gif',
+    'image/jpeg': 'jpeg',
+    'image/png': 'png',
+    'image/svg+xml': 'svg',
+    'image/tiff': 'tiff',
+    'image/webp': 'webp',
+};
+/** File extension → bare format token (for path / named-blob inputs). */
+const EXT_TOKEN = {
+    jpg: 'jpeg', jpeg: 'jpeg', jpe: 'jpeg', jfif: 'jpeg',
+    png: 'png', webp: 'webp', gif: 'gif', avif: 'avif',
+    tif: 'tiff', tiff: 'tiff', svg: 'svg',
+};
+/**
+ * Per-route, per-output-format honored + planned option keys, mirroring
+ * `image-output-routes.json` `media.image`. `source_op` is uniform
+ * (same_format→compress, format_change→convert) so it is a derivation rule, not
+ * a table column. `same_format` is keyed by the INPUT token; `format_change` by
+ * the OUTPUT 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', 'metadata', 'output_format', 'progressive', 'quality', 'width'], planned: ['lossless'] },
+        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', 'metadata', 'output_format', 'quality', 'width'], planned: ['lossless'] },
+    },
+    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: [] },
+    },
+};
+/** The bare format token for a MIME type, or undefined if not a known image MIME. */
+export function tokenForMime(mime) {
+    return MIME_TOKEN[mime.split(';')[0].trim().toLowerCase()];
+}
+/** The bare format token for a filename / path extension, or undefined. */
+export function tokenForPath(path) {
+    const ext = path.toLowerCase().split('.').pop();
+    return ext !== undefined ? EXT_TOKEN[ext] : undefined;
+}
+/** Every image format token the projection knows (for validation / tests). */
+export function knownImageTokens() {
+    return new Set(Object.keys(IMAGE_OUTPUT_ROUTES.same_format));
+}
+/**
+ * Resolve an Output request to its wire op + gating sets. Returns undefined when
+ * the route is unrepresentable (e.g. converting TO a format no `format_change`
+ * cell covers). `outputFormat` undefined → same-format (keep input format).
+ */
+export function resolveOutputRoute(inputToken, outputFormat) {
+    const outToken = outputFormat ?? inputToken;
+    if (outToken === inputToken) {
+        const cell = IMAGE_OUTPUT_ROUTES.same_format[inputToken];
+        if (cell === undefined)
+            return undefined;
+        return {
+            route: 'same_format',
+            sourceOp: 'compress',
+            outputFormatWire: 'original',
+            inputToken,
+            honored: new Set(cell.honored),
+            planned: new Set(cell.planned),
+        };
+    }
+    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).
+    const inCell = IMAGE_OUTPUT_ROUTES.same_format[inputToken];
+    const resize = inCell ? RESIZE_KEYS.filter((k) => inCell.honored.includes(k)) : [];
+    return {
+        route: 'format_change',
+        sourceOp: 'convert',
+        outputFormatWire: outToken,
+        inputToken,
+        honored: new Set([...cell.honored, ...resize]),
+        planned: new Set(cell.planned),
+    };
+}
+/** Input token → its `compress.image*` mime-group name (for per-value availability lookup). */
+function compressGroupForToken(token) {
+    if (token === 'jpeg')
+        return 'image_jpeg';
+    if (token === 'png')
+        return 'image_png';
+    if (token === 'avif')
+        return 'image_avif';
+    return 'image'; // webp / gif / svg / tiff
+}
+/**
+ * Whether a specific VALUE of an option is `availability: 'planned'` for the
+ * given input format — the per-value gate (e.g. `metadata: 'keep'` is planned
+ * even though the `metadata` key is honored). Reads the generated
+ * `compressMetadata` `per_value_availability`; same_format only (the only route
+ * where value-level options like `metadata` are honored). Returns false when the
+ * option / value / group is unknown (no gate).
+ */
+export function isPlannedValue(inputToken, optionKey, value) {
+    const group = compressMetadata.mime_groups[compressGroupForToken(inputToken)];
+    const opt = group?.options[optionKey];
+    if (opt === undefined)
+        return false;
+    const entry = opt.per_value_availability[String(value)];
+    return entry?.availability === 'planned';
+}

package/dist/ergonomic/option_types.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Typed per-op option interfaces for the ergonomic verbs (card Dhje3Faq).
+ * These replace the untyped `Record<string, unknown>` bags so the IDE can offer
+ * key completion and `tsc` rejects typos. The KEY SET of each interface is pinned
+ * to the contract two ways: (1) the source-level `Equal<...>` assertions below tie
+ * each interface to its `*_OPTION_KEYS` tuple at `tsc` time; (2) the wire-key
+ * conformance guard ties each tuple (∪ positional-owned) to the generated
+ * `OperationMetadata` at test time. Value types are best-effort (per-value/enum
+ * sync is out of scope — keys are the contract anchor).
+ *
+ * Keys a verb owns via a positional argument are EXCLUDED from its interface
+ * (`output_format` on convert, `text` on textWatermark) — they are set by the
+ * first argument and rejected if supplied in the bag (see `option_validation.ts`).
+ *
+ * Mirrored by the PHP array-shape docblocks — keep in lockstep.
+ */
+/** 9-grid anchor shared by text/image/video watermark. */
+export type WatermarkAnchor = 'top_left' | 'top_center' | 'top_right' | 'center_left' | 'center' | 'center_right' | 'bottom_left' | 'bottom_center' | 'bottom_right';
+export interface ConvertOptions {
+    /** Output quality for lossy image formats (1-100). */
+    quality?: number;
+    /** Background colour (hex) for transparent images → JPEG. */
+    background?: string;
+    /** Video Constant Rate Factor (0 best — 51 worst). */
+    crf?: number;
+    /** Trim from the start, in seconds (video). */
+    trim_start?: number;
+    /** Trim from the end, in seconds (video). */
+    trim_end?: number;
+    /** Output frame rate for video → GIF. */
+    fps?: number;
+    /** Max output width in pixels (video → GIF downscale cap). */
+    width?: number;
+    /** GIF palette size (2-256). */
+    max_colors?: number;
+    /** GIF loop count (0 infinite, N>0 N times, -1 once). */
+    loop?: number;
+    /** GIF dithering method. */
+    dither?: 'none' | 'bayer' | 'floyd_steinberg' | 'sierra2' | 'sierra2_4a';
+    /** Output bitrate in kbps (lossy audio). */
+    bitrate?: 64 | 96 | 128 | 192 | 256 | 320;
+    /** Page selection for PDF → image (e.g. '1-5,8'). */
+    pages?: string;
+    /** Render resolution in DPI for PDF → image. */
+    dpi?: number;
+}
+export interface ThumbnailOptions {
+    /** Target width in pixels (1-16384). REQUIRED. */
+    width: number;
+    /** Target height in pixels (1-16384). REQUIRED. */
+    height: number;
+    /** Resize mode. */
+    fit?: 'max' | 'crop' | 'scale';
+    /** Output format for the thumbnail. */
+    format?: 'jpg' | 'png' | 'webp';
+    /** Output quality for lossy thumbnail formats (image input). */
+    quality?: number;
+    /** Frame timestamp for video input (e.g. '00:00:01'). */
+    timestamp?: string;
+    /** Document source: a printed page or the cover. */
+    source?: 'page' | 'cover';
+    /** 1-based page index for document input. */
+    page?: number;
+}
+export interface TextWatermarkOptions {
+    /** Font size in pixels (8-512). */
+    font_size?: number;
+    /** Text colour as hex RGB/RGBA (e.g. '#FFFFFF80'). */
+    color?: string;
+    /** Font family (bundled). */
+    font_family?: 'liberation_sans';
+    /** Rotation angle in degrees (-360..360). */
+    rotation?: number;
+    /** Rendering mode. */
+    watermark_mode?: 'single' | 'tiled';
+    /** Spacing between tiled labels in pixels (tiled mode). */
+    tile_spacing?: number;
+    /** 9-grid anchor position. */
+    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;
+}
+export interface WatermarkOptions {
+    /** 9-grid anchor position. */
+    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;
+}
+/** Resize mode (contract `fit` enum, v2.97.0). */
+export type OutputFit = 'max' | 'crop' | 'scale';
+/** Metadata policy (contract `metadata` enum, v2.97.0). `keep` is `availability:planned`. */
+export type OutputMetadata = 'all' | 'keep';
+/**
+ * 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
+ * projection); the PER-ROUTE honored/planned narrowing happens in the lowering
+ * (`resolveOutputRoute`), so supplying an option not honored on the resolved
+ * route (or a planned one) throws pre-upload. `output_format` is set via the
+ * positional `format` argument, so it is excluded here. Resize (`width`/`height`/
+ * `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. */
+    quality?: number;
+    /** Resize target width in px (1-16384; width*height <= 16MP). */
+    width?: number;
+    /** Resize target height in px (optional — width-only resize preserves aspect). */
+    height?: number;
+    /** Resize mode (applies when width or height is set). */
+    fit?: OutputFit;
+    /** Background colour (hex) for transparent images → JPEG. Honored: format_change→jpeg only. */
+    background?: string;
+    /** Progressive JPEG. Honored: same_format jpeg only. */
+    progressive?: boolean;
+    /** PNG lossless optimisation effort. Honored: same_format png only. */
+    optimization_level?: number;
+    /** AVIF encode speed. Honored: same_format avif only. */
+    avif_speed?: number;
+    /** Metadata policy. Honored: same_format routes. (`keep` value is planned.) */
+    metadata?: OutputMetadata;
+    /** JPEG/WebP lossless. PLANNED (gated unavailable). */
+    lossless?: boolean;
+    /** Lossy PNG quantization. PLANNED (gated unavailable; licence-gated). */
+    lossy?: boolean;
+}
+/**
+ * The user-supplyable option keys per verb (excludes positional-owned keys).
+ * Exported for the wire-key conformance guard, which asserts each tuple ∪ its
+ * 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 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"];
+};

package/dist/ergonomic/option_types.js

@@ -0,0 +1,57 @@
+/**
+ * Typed per-op option interfaces for the ergonomic verbs (card Dhje3Faq).
+ * These replace the untyped `Record<string, unknown>` bags so the IDE can offer
+ * key completion and `tsc` rejects typos. The KEY SET of each interface is pinned
+ * to the contract two ways: (1) the source-level `Equal<...>` assertions below tie
+ * each interface to its `*_OPTION_KEYS` tuple at `tsc` time; (2) the wire-key
+ * conformance guard ties each tuple (∪ positional-owned) to the generated
+ * `OperationMetadata` at test time. Value types are best-effort (per-value/enum
+ * sync is out of scope — keys are the contract anchor).
+ *
+ * Keys a verb owns via a positional argument are EXCLUDED from its interface
+ * (`output_format` on convert, `text` on textWatermark) — they are set by the
+ * first argument and rejected if supplied in the bag (see `option_validation.ts`).
+ *
+ * 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',
+];
+const THUMBNAIL_OPTION_KEYS = [
+    'width', 'height', 'fit', 'format', 'quality', 'timestamp', 'source', 'page',
+];
+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',
+];
+const OUTPUT_OPTION_KEYS = [
+    'quality', 'width', 'height', 'fit', 'background', 'progressive',
+    'optimization_level', 'avif_speed', 'metadata', 'lossless', 'lossy',
+];
+const _convertKeysMatch = true;
+const _thumbnailKeysMatch = true;
+const _textWatermarkKeysMatch = true;
+const _watermarkKeysMatch = true;
+const _outputKeysMatch = true;
+// Reference the assertions so `noUnusedLocals` doesn't strip them.
+void _convertKeysMatch;
+void _thumbnailKeysMatch;
+void _textWatermarkKeysMatch;
+void _watermarkKeysMatch;
+void _outputKeysMatch;
+/**
+ * The user-supplyable option keys per verb (excludes positional-owned keys).
+ * Exported for the wire-key conformance guard, which asserts each tuple ∪ its
+ * positional-owned keys equals the contract `operationOptionKeys(metadata)`.
+ */
+export const VERB_OPTION_KEYS = {
+    convert: CONVERT_OPTION_KEYS,
+    thumbnail: THUMBNAIL_OPTION_KEYS,
+    textWatermark: TEXT_WATERMARK_OPTION_KEYS,
+    watermark: WATERMARK_OPTION_KEYS,
+    output: OUTPUT_OPTION_KEYS,
+};

package/dist/ergonomic/option_validation.d.ts

@@ -0,0 +1,58 @@
+import { type OperationMetadata } from '@giveitsmaller/contracts/operations';
+/**
+ * Eager, synchronous, PRE-UPLOAD option-key validation for the ergonomic verbs
+ * (card Dhje3Faq). The file-first builders accept verb options as untyped bags;
+ * a user typo (`{ quaity: 80 }`) would otherwise flow to the server and 422.
+ * This module rejects unknown keys at the verb call — before any upload —
+ * mirroring the existing `compress()` optimize-check and the watermark eager
+ * gate. The allowed key set is read from the generated `OperationMetadata`
+ * 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
+ * (`optimize`, `presetOverrides`) and camelCase resolver aliases (`targetSize`,
+ * `outputFormat`) that are not `operationOptionKeys(compressMetadata)`; it has its
+ * own `unknown_field` validation through the preset resolver.
+ *
+ * Mirrored by the PHP `OptionValidation` helper — keep the two in lockstep.
+ */
+/**
+ * OPERATION-LEVEL contract option keys (the keys valid in `OperationDef.options`):
+ * the union of every mime group's `options` plus `direct_options` for
+ * media-agnostic ops. Deliberately EXCLUDES `per_input_options` (valid only on a
+ * merge input). Promoted from the wire-key conformance guard for runtime reuse.
+ */
+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';
+/** Accessor for the conformance guard (pins these sets to the contract metadata). */
+export declare function allowedKeysFor(verb: ValidatedVerb): ReadonlySet<string>;
+/**
+ * Validate a USER-supplied options bag for an ergonomic verb. Throws
+ * {@link GislConfigError} (reason `unknown_field`) synchronously, BEFORE any
+ * upload or wire-key injection. Call this at the TOP of every verb body, before
+ * the `format`-drop / `output_format` / `text` injection.
+ *
+ * @throws {GislConfigError} reason `unknown_field` when the bag carries a key the
+ *   verb owns via a positional argument, or a key absent from the op's contract
+ *   option set.
+ */
+export declare function validateVerbOptions(verb: ValidatedVerb, 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
+ * already enforces this at compile time; this RUNTIME guard catches JS callers and
+ * an explicit `undefined`/`null` BEFORE upload. Rejecting `null` (not just
+ * `undefined`) keeps TS in lockstep with the PHP `assertThumbnailDimensions`, which
+ * must reject `null` because PHP drops null values pre-lower — so a `null` dimension
+ * is a pre-upload error in BOTH languages, never a wire `null` that 422s. Mirrored
+ * in PHP.
+ *
+ * @throws {GislConfigError} reason `missing_required_field` naming the absent
+ *   dimension(s) in `conflictingFields`.
+ */
+export declare function assertThumbnailDimensions(options: {
+    width?: unknown;
+    height?: unknown;
+} | null | undefined): void;