@giveitsmaller/sdk 0.15.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();
@@ -130,6 +139,10 @@ export function _runAudit() {
     accept();
     // FF3a / u0hBt6fl — homogeneous fan-out builder surface.
     accept();
+    // FF4a / Z7zTr789 — multi-input watermark recipe surface.
+    accept();
+    accept();
+    accept();
     accept();
     accept();
     accept();

package/dist/client.d.ts

@@ -1,5 +1,5 @@
-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 { CreditsUsageOptions, ListWorkflowsOptions, GetSchemaOptions, GetSchemaResult, GislClientConfig, GislSseEvent, PreflightClipsResult, ProbeWaitOptions, ProbeWaitResult, UploadOptions, WaitOptions, WorkflowCreatePayload, _Sdk3HandCodedKeepaliveResult, _Sdk3HandCodedMultipartStatusResult, _Sdk3HandCodedPresignPartsResult } from './types.js';
+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;
 export interface ValidationDetail {
@@ -133,8 +133,13 @@ export declare class GislClient {
     createWorkflow(payload: WorkflowCreatePayload): Promise<WorkflowCreateResponse>;
     /**
      * Get current workflow status.
+     *
+     * For an anonymous (null-owner) workflow, pass `opts.capability` (the `cap`
+     * from the anonymous workflow-create response) so a session-less caller can
+     * read it — the SDK sends it as the `X-Workflow-Capability` header. Omit for
+     * authenticated reads. A wrong/missing cap on a null-owner workflow is a 404.
      */
-    getWorkflowStatus(workflowId: string): Promise<WorkflowStatusResponse>;
+    getWorkflowStatus(workflowId: string, opts?: ReadCapabilityOptions): Promise<WorkflowStatusResponse>;
     /**
      * Poll until the workflow reaches a terminal status.
      */
@@ -176,13 +181,24 @@ export declare class GislClient {
     resumeWorkflow(workflowId: string): Promise<WorkflowResumeResponse>;
     /**
      * Get download URLs for a completed workflow.
+     *
+     * For an anonymous (null-owner) workflow, pass `opts.capability` (the `cap`
+     * from the anonymous workflow-create response) so a session-less caller can
+     * read it — the SDK sends it as the `X-Workflow-Capability` header. Omit for
+     * authenticated reads. A wrong/missing cap on a null-owner workflow is a 404.
      */
-    getWorkflowDownloads(workflowId: string): Promise<WorkflowDownloadResponse>;
+    getWorkflowDownloads(workflowId: string, opts?: ReadCapabilityOptions): Promise<WorkflowDownloadResponse>;
     /**
      * Stream SSE events for a workflow. Returns an async iterable.
+     *
+     * For an anonymous (null-owner) workflow, pass `opts.capability` (the `cap`
+     * from the anonymous workflow-create response) so a session-less caller can
+     * read it — the SDK sends it as the `X-Workflow-Capability` header. Omit for
+     * authenticated reads. A wrong/missing cap on a null-owner workflow is a 404.
      */
     streamEvents(workflowId: string, opts?: {
         signal?: AbortSignal;
+        capability?: string;
     }): Promise<AsyncGenerator<GislSseEvent>>;
     /**
      * Get metadata for an uploaded file.
@@ -229,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;
@@ -56,6 +56,17 @@ const S3_MAX_MULTIPART_PARTS = 10_000;
 const RECOMMENDED_CHUNK_SIZE_MAX_BYTES = 104_857_600; // 100 MiB
 const DEFAULT_POLL_INTERVAL_MS = 2_000;
 const DEFAULT_POLL_TIMEOUT_MS = 300_000; // 5 min
+// Anonymous-read capability header. An anonymous (null-owner) workflow create
+// returns a one-time `cap` token (WorkflowCreateResponse.cap); the session-less
+// caller passes it back on status/downloads/events reads via this header so the
+// server can authorize the read. A wrong/missing cap on a null-owner workflow
+// returns 404 (no existence oracle), per contracts ticket YQt88cq2.
+const WORKFLOW_CAPABILITY_HEADER = 'X-Workflow-Capability';
+// Build the capability header set for a workflow read. Empty when no token is
+// supplied (authenticated reads — the session authorizes those).
+function workflowCapabilityHeaders(capability) {
+    return capability ? { [WORKFLOW_CAPABILITY_HEADER]: capability } : {};
+}
 // Statuses that waitForWorkflow() returns immediately on. Per ticket I24,
 // `cancelled` and `expired` are terminal (a workflow cannot leave either
 // state). `paused_insufficient_credits` is a soft-pause: not terminal, but
@@ -1599,10 +1610,16 @@ export class GislClient {
     }
     /**
      * Get current workflow status.
+     *
+     * For an anonymous (null-owner) workflow, pass `opts.capability` (the `cap`
+     * from the anonymous workflow-create response) so a session-less caller can
+     * read it — the SDK sends it as the `X-Workflow-Capability` header. Omit for
+     * authenticated reads. A wrong/missing cap on a null-owner workflow is a 404.
      */
-    async getWorkflowStatus(workflowId) {
+    async getWorkflowStatus(workflowId, opts = {}) {
         return this.request('GET', `/api/workflows/${encodeURIComponent(workflowId)}/status`, {
             deserialize: WorkflowStatusResponseFromJSON,
+            headers: workflowCapabilityHeaders(opts.capability),
         });
     }
     /**
@@ -1613,7 +1630,9 @@ export class GislClient {
         const timeoutMs = options?.timeoutMs ?? DEFAULT_POLL_TIMEOUT_MS;
         const deadline = Date.now() + timeoutMs;
         while (true) {
-            const status = await this.getWorkflowStatus(workflowId);
+            const status = await this.getWorkflowStatus(workflowId, {
+                capability: options?.capability,
+            });
             options?.onPoll?.(status.status);
             if (TERMINAL_STATUSES.has(status.status)) {
                 return status;
@@ -1669,14 +1688,25 @@ export class GislClient {
     }
     /**
      * Get download URLs for a completed workflow.
+     *
+     * For an anonymous (null-owner) workflow, pass `opts.capability` (the `cap`
+     * from the anonymous workflow-create response) so a session-less caller can
+     * read it — the SDK sends it as the `X-Workflow-Capability` header. Omit for
+     * authenticated reads. A wrong/missing cap on a null-owner workflow is a 404.
      */
-    async getWorkflowDownloads(workflowId) {
+    async getWorkflowDownloads(workflowId, opts = {}) {
         return this.request('GET', `/api/workflows/${encodeURIComponent(workflowId)}/downloads`, {
             deserialize: WorkflowDownloadResponseFromJSON,
+            headers: workflowCapabilityHeaders(opts.capability),
         });
     }
     /**
      * Stream SSE events for a workflow. Returns an async iterable.
+     *
+     * For an anonymous (null-owner) workflow, pass `opts.capability` (the `cap`
+     * from the anonymous workflow-create response) so a session-less caller can
+     * read it — the SDK sends it as the `X-Workflow-Capability` header. Omit for
+     * authenticated reads. A wrong/missing cap on a null-owner workflow is a 404.
      */
     async streamEvents(workflowId, opts = {}) {
         const eventsPath = `/api/workflows/${encodeURIComponent(workflowId)}/events`;
@@ -1702,6 +1732,7 @@ export class GislClient {
             response = await this.request('GET', eventsPath, {
                 rawResponse: true,
                 signal: controller.signal,
+                headers: workflowCapabilityHeaders(opts.capability),
             });
         }
         catch (err) {
@@ -1903,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"];
+};