@giveitsmaller/sdk 0.19.0 → 0.21.0

package/dist/client.js

@@ -4,8 +4,12 @@
 // 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, 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 { 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, LongFormConcurrencyLimitResponseFromJSON, TierRestrictionKind, TierRestrictionResponseFromJSON, UserTier, WorkflowExpiredResponseFromJSON, ProbePendingResponseFromJSON, UploadSizeExceedsTierResponseFromJSON, UploadDurationExceedsTierResponseFromJSON, UploadConstraintsAppliedProcessingClassPreAssignmentEnum, UploadThresholdsSingleShotMaxBytesEnum, UploadThresholdsMultipartChunkSizeEnum, UploadThresholdsMultipartConcurrencyDefaultEnum, } from '@giveitsmaller/contracts/openapi';
+import { GislAbortError, GislApiError, GislAuthError, GislAuthRejectionError, GislBalanceExhaustedError, GislError, GislFeatureNotAvailableError, GislFeatureTierRestrictedError, GislLongFormConcurrencyError, GislMultipartPartCountError, GislMultipartPartError, GislMultipartSessionNotFoundError, GislMultipartSessionOwnershipError, GislMultipartSessionAuthRequiredError, GislTierRestrictedError, GislTimeoutError, GislProbePendingError, GislUploadCapExceededError, GislValidationError, GislWorkflowExpiredError, } from './errors.js';
+// The `Retry-After` millisecond parser lives in the shared retry-metadata
+// module (extracted to break the client ↔ errors circular import); re-imported
+// here so the retry-loop timing stays byte-identical.
+import { parseRetryAfterMs } from './retry-metadata.js';
 import { parseSseStream } from './sse.js';
 const DEFAULT_TIMEOUT_MS = 30_000;
 // SDK-internal aliases derived from the contract-pinned UploadThresholds enums
@@ -55,7 +59,25 @@ const S3_MAX_MULTIPART_PARTS = 10_000;
 // exists to prevent). codex review (high).
 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
+const DEFAULT_POLL_TIMEOUT_MS = 600_000; // 10 min
+/**
+ * Re-tag a bare per-request transport {@link GislTimeoutError} with the workflow
+ * it was scoped to, so a timed-out workflow read (status / downloads) stays
+ * recoverable. No-op for any other error and for a timeout that already carries
+ * an id. See `oYumKo6y`. (PHP transport failures surface as `GislNetworkError`,
+ * so this enrichment is TS-only.)
+ */
+function withWorkflowIdOnTimeout(err, workflowId) {
+    if (!(err instanceof GislTimeoutError) || err.workflowId !== undefined)
+        return err;
+    const enriched = new GislTimeoutError(err.message, workflowId);
+    // Preserve the original throw site + chain the cause — the enriched error is
+    // a re-tag, not a new failure, so diagnostics should still point at the
+    // transport timeout.
+    enriched.stack = err.stack;
+    enriched.cause = err;
+    return enriched;
+}
 // 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
@@ -94,6 +116,18 @@ function headersToRecord(headers) {
     });
     return r;
 }
+// Canonical human-readable fallback when a failure envelope carries NO `message`
+// field. Kept IDENTICAL to the PHP SDK (`GislClient::fallbackErrorMessage`) so a
+// message-absent error surfaces byte-identical `.message` text across SDKs
+// (card U7MACpOj). Used by BOTH error-construction paths (`handleResponse` and
+// the `getSchema` raw-response path) so they cannot drift. The machine code
+// stays on `.errorCode` — this string is human DISPLAY text only; never parse
+// it. `error` absent → `unknown_error` (PHP parity). Historically TS leaked the
+// SCREAMING_SNAKE `error` code as `.message`, diverging from PHP's synthetic
+// sentence; this unifies them on the human-shaped form.
+function fallbackErrorMessage(status, errorCode) {
+    return `Request failed with status ${status} (${errorCode ?? 'unknown_error'}).`;
+}
 function isValidationDetails(value) {
     return (Array.isArray(value) &&
         value.length > 0 &&
@@ -109,12 +143,14 @@ function isAbortError(err) {
         typeof err === 'object' &&
         err.name === 'AbortError');
 }
-// Retryable S3 PUT response statuses: 429 throttling, 503 slow-down, and any
-// other 5xx (502/504 are common transients behind CloudFront/S3). 4xx other
-// than 429 (403 signed-URL expiry, 400 SignatureDoesNotMatch, etc.) are
-// configuration / authority issues — retrying just delays the real failure.
+// Retryable S3 PUT response statuses: 408 request timeout, 429 throttling, 503
+// slow-down, and any other 5xx (502/504 are common transients behind
+// CloudFront/S3). 408 is a transient timeout on the PUT itself, so it is retried
+// (matching the PHP SDK's S3-PUT predicate — qz7MjNTy cross-SDK alignment). Other
+// 4xx (403 signed-URL expiry, 400 SignatureDoesNotMatch, etc.) are configuration
+// / authority issues — retrying just delays the real failure.
 function isRetryableStatus(status) {
-    return status === 429 || (status >= 500 && status <= 599);
+    return status === 408 || status === 429 || (status >= 500 && status <= 599);
 }
 // fetch surfaces network failures (DNS, TLS, TCP reset, mid-body disconnect)
 // as TypeError. Abort surfaces as a DOMException with name='AbortError', not
@@ -123,31 +159,6 @@ function isRetryableStatus(status) {
 function isRetryableNetworkError(err) {
     return err instanceof TypeError;
 }
-// Parse an HTTP `Retry-After` header into milliseconds. Accepts the two RFC
-// 9110 forms: delta-seconds (e.g. "5") or an HTTP-date. Returns `undefined`
-// for an absent / unparseable / negative value (caller falls back to its own
-// backoff). A past HTTP-date clamps to 0.
-function parseRetryAfterMs(headerValue) {
-    if (headerValue === undefined)
-        return undefined;
-    const trimmed = headerValue.trim();
-    if (trimmed === '')
-        return undefined;
-    let ms;
-    if (/^\d+$/.test(trimmed)) {
-        ms = Number(trimmed) * 1000;
-    }
-    else {
-        const when = Date.parse(trimmed);
-        if (Number.isNaN(when))
-            return undefined;
-        ms = when - Date.now();
-    }
-    // A non-positive Retry-After (e.g. "0" or a past HTTP-date) must NOT short-
-    // circuit the backoff to zero — treat it as absent so the caller falls back
-    // to jitter and the loop can't busy-poll until timeout.
-    return ms > 0 ? ms : undefined;
-}
 // Cancellable sleep for poll loops. Resolves after `ms`, or rejects with
 // `GislAbortError` if `signal` aborts. Resolves immediately for ms <= 0.
 function cancellableSleep(ms, signal) {
@@ -493,18 +504,26 @@ export class GislClient {
                 messageKey: json.message_key,
                 locale: json.locale,
                 messageParams: json.message_params,
+                // The wire-stable machine code (SCREAMING_SNAKE `error`), surfaced as
+                // `error.errorCode` on every dispatched error (PHP parity). Threaded via
+                // this single options object → base GislApiError, GislValidationError,
+                // and every structured subclass (passed through as `extra`).
+                errorCode: typeof json.error === 'string' ? json.error : undefined,
                 responseHeaders,
                 contentLanguage,
             };
             // Human-readable text comes from `message` (the I26 localised field).
             // `error` is the stable, never-localised SCREAMING_SNAKE machine code —
-            // NOT display text. Surfacing `error` as the thrown error's `.message`
-            // regressed consumers that render the human string (x9Lbf6uy). Fall back
-            // to `error` when `message` is absent (deployed contract guarantees
-            // `message` on conforming error envelopes). Machine dispatch keys off
-            // `error_type` (below), unchanged.
+            // NOT display text (surfacing it as `.message` regressed consumers that
+            // render the human string, x9Lbf6uy). When `message` is absent (the
+            // deployed contract guarantees it on conforming error envelopes), fall
+            // back to the canonical synthetic sentence — byte-identical to the PHP
+            // SDK — instead of leaking the machine code (card U7MACpOj). The code is
+            // still carried on `.errorCode`. Machine dispatch keys off `error_type`
+            // (below), unchanged.
             const status = response.status;
-            const errorMessage = json.message ?? json.error ?? 'Unknown error';
+            const errorMessage = json.message ??
+                fallbackErrorMessage(status, typeof json.error === 'string' ? json.error : undefined);
             // Validation-details branch first — preserve existing shape so callers
             // matching on `instanceof GislValidationError` keep working.
             if (isValidationDetails(json.details)) {
@@ -609,6 +628,15 @@ export class GislClient {
                 tryThrowCap(UploadDurationExceedsTierResponseFromJSON, 'duration_tier', (p) => isInEnum(p.currentTier, UserTier) &&
                     typeof p.maxDurationSeconds === 'number');
             }
+            // Long-form concurrency limit (429) — a TIER quota, DISTINCT from a
+            // generic infra rate-limit 429. Dispatched on the machine `error` CODE
+            // (this envelope carries NO `error_type`); a generic rate-limit 429 has a
+            // different/absent code, so it falls through to the base GislApiError
+            // where `retryAfterSeconds` applies. The validator re-asserts the code so
+            // a malformed envelope falls through rather than mis-typing.
+            if (status === 429 && json.error === 'LONG_FORM_CONCURRENCY_LIMIT_EXCEEDED') {
+                tryThrowStructured(LongFormConcurrencyLimitResponseFromJSON, GislLongFormConcurrencyError, (p) => p.error === 'LONG_FORM_CONCURRENCY_LIMIT_EXCEEDED');
+            }
             // 413 = the absolute across-tier cap. The contract models 413 as a
             // plain `ErrorEnvelope` (no `error_type` discriminator, no typed
             // payload — api.yaml), so dispatch purely on status with no FromJSON
@@ -1617,10 +1645,15 @@ export class GislClient {
      * authenticated reads. A wrong/missing cap on a null-owner workflow is a 404.
      */
     async getWorkflowStatus(workflowId, opts = {}) {
-        return this.request('GET', `/api/workflows/${encodeURIComponent(workflowId)}/status`, {
-            deserialize: WorkflowStatusResponseFromJSON,
-            headers: workflowCapabilityHeaders(opts.capability),
-        });
+        try {
+            return await this.request('GET', `/api/workflows/${encodeURIComponent(workflowId)}/status`, {
+                deserialize: WorkflowStatusResponseFromJSON,
+                headers: workflowCapabilityHeaders(opts.capability),
+            });
+        }
+        catch (err) {
+            throw withWorkflowIdOnTimeout(err, workflowId);
+        }
     }
     /**
      * Poll until the workflow reaches a terminal status.
@@ -1638,7 +1671,7 @@ export class GislClient {
                 return status;
             }
             if (Date.now() + intervalMs > deadline) {
-                throw new GislTimeoutError(`Workflow ${workflowId} did not complete within ${timeoutMs}ms`);
+                throw new GislTimeoutError(`Workflow ${workflowId} did not complete within ${timeoutMs}ms`, workflowId);
             }
             await new Promise((resolve) => setTimeout(resolve, intervalMs));
         }
@@ -1695,10 +1728,15 @@ export class GislClient {
      * authenticated reads. A wrong/missing cap on a null-owner workflow is a 404.
      */
     async getWorkflowDownloads(workflowId, opts = {}) {
-        return this.request('GET', `/api/workflows/${encodeURIComponent(workflowId)}/downloads`, {
-            deserialize: WorkflowDownloadResponseFromJSON,
-            headers: workflowCapabilityHeaders(opts.capability),
-        });
+        try {
+            return await this.request('GET', `/api/workflows/${encodeURIComponent(workflowId)}/downloads`, {
+                deserialize: WorkflowDownloadResponseFromJSON,
+                headers: workflowCapabilityHeaders(opts.capability),
+            });
+        }
+        catch (err) {
+            throw withWorkflowIdOnTimeout(err, workflowId);
+        }
     }
     /**
      * Stream SSE events for a workflow. Returns an async iterable.
@@ -1747,7 +1785,10 @@ export class GislClient {
                 releaseConsumerSignal();
             }
         }
-        const inner = parseSseStream(response, { signal: controller.signal });
+        const inner = parseSseStream(response, {
+            signal: controller.signal,
+            ...(opts.onParseError !== undefined ? { onParseError: opts.onParseError } : {}),
+        });
         let started = false;
         let settled = false;
         // Idempotent teardown. `abort` only on consumer-driven early
@@ -1873,21 +1914,31 @@ export class GislClient {
             return { notModified: true, etag, lastModified };
         }
         if (!response.ok) {
-            let errorMessage = 'Unknown error';
+            let errorCode;
+            // Seed with the canonical synthetic sentence (unknown_error) so the
+            // message-absent JSON branch below reuses the SAME helper as
+            // handleResponse + PHP — that message-absent JSON envelope is the
+            // U7MACpOj parity target. A non-JSON body is a rare edge that keeps
+            // this seed (it does NOT claim byte-parity with PHP's non-JSON path,
+            // which throws a distinct GislError).
+            let errorMessage = fallbackErrorMessage(response.status, undefined);
             try {
                 const errJson = (await response.json());
-                // Prefer the human `message`; `error` is the machine code (x9Lbf6uy).
-                if (errJson.message)
-                    errorMessage = errJson.message;
-                else if (errJson.error)
-                    errorMessage = errJson.error;
+                // Surface the machine code as errorCode too (parity with handleResponse
+                // + PHP), even when `message` supplied the human text.
+                if (typeof errJson.error === 'string')
+                    errorCode = errJson.error;
+                // Prefer the human `message`; else the canonical synthetic sentence —
+                // NOT the raw machine code (x9Lbf6uy / U7MACpOj).
+                errorMessage = errJson.message ?? fallbackErrorMessage(response.status, errorCode);
             }
             catch {
-                // Non-JSON body — keep generic message.
+                // Non-JSON body — keep the generic synthetic message, no machine code.
             }
             // This throw is OUTSIDE handleResponse (rawResponse:true / 304 path), so
             // build the response-header surface from the in-scope `response` here.
             throw new GislApiError(response.status, errorMessage, path, undefined, {
+                errorCode,
                 responseHeaders: headersToRecord(response.headers),
                 contentLanguage: response.headers.get('content-language') ?? undefined,
             });
@@ -1954,15 +2005,18 @@ export class GislClient {
      * via that cookie when the client is configured with
      * `useSessionCookie: true`.
      *
-     * Failure modes per ticket FX6mbTJD:
-     * - **401** `invalid_credentials` (collapsed with unverified
-     *   accounts for anti-enumeration) → `GislAuthError`.
-     * - **403** account-state failures (`account_locked`,
-     *   `account_disabled`, `account_deleted`,
-     *   `account_deletion_expired`) → `GislAuthError`.
+     * Failure modes per ticket FX6mbTJD (login narrowed at contracts
+     * v2.166.0 authsec — no 403 account-state branch on login):
+     * - **401** `invalid_credentials` (wrong password, unverified, OR
+     *   unknown account — all collapsed for anti-enumeration) →
+     *   `GislAuthError`.
      * - **429** infrastructure rate-limit → `GislApiError` with
      *   the `Retry-After` header echoed on the response.
      *
+     * The account-status error types (`account_locked` / `account_disabled`
+     * / `account_deleted` / `account_deletion_expired`) still exist but are
+     * emitted on the API-key path + live-session enforcement, not on login.
+     *
      * Node session persistence (cookie-jar across processes) is out of
      * scope — this method only touches the request side.
      */

package/dist/ergonomic/image_output_routes.d.ts

@@ -87,4 +87,34 @@ export declare function resolveOutputRoute(inputToken: string, outputFormat: str
  * option / value / group is unknown (no gate).
  */
 export declare function isPlannedValue(inputToken: string, optionKey: string, value: unknown): boolean;
+/**
+ * Compress-route enum members per image mime-group, mirroring the shipped
+ * `availability/availability.json` `operations.compress.mime_groups.<group>.
+ * options.<opt>.values`. Kept as a hand table (NOT a runtime read of the ~238KB
+ * availability sidecar) so the enum-membership gate stays browser-safe, exactly
+ * like {@link IMAGE_OUTPUT_ROUTES} — and, crucially, so the gate has NO
+ * dependency on a contracts version that carries the enum in a compact form (a
+ * generated-metadata `values` field would fail open on an older published
+ * `@giveitsmaller/contracts`). PINNED to `availability.json` by
+ * `output-route-conformance.test.ts`; a contract regen that adds/changes an
+ * enum member fails there. Mirrored by PHP `ImageOutputRoutes::COMPRESS_OPTION_VALUES`.
+ *
+ * `image_svg`/`image_avif` carry the NARROW `metadata: ['strip','all']` (no
+ * `keep`) — the reason a value gate that consulted only the generic `image`
+ * group (`['strip','keep','all']`) let `metadata: 'keep'` reach a server 422 on
+ * those bases (rtkzl9gr). `output_format` is listed for a faithful projection
+ * mirror but is never gated here (the Output lowering owns it positionally).
+ */
+export declare const COMPRESS_OPTION_VALUES: Readonly<Record<string, Readonly<Record<string, readonly string[]>>>>;
+/**
+ * Whether a VALUE lies OUTSIDE the option's compress-route enum for the given
+ * input format — the pre-upload enum-membership gate (rtkzl9gr). Reads the hand
+ * {@link COMPRESS_OPTION_VALUES} table. Returns false when the option is not an
+ * enum on this group (no entry), so a non-enum option (e.g. integer `quality`)
+ * is never gated. Meaningful only on the same_format (compress) route, where
+ * the compress option enums definitionally apply. Membership is STRICT: a value
+ * whose type differs from the string enum members (e.g. numeric `420`) is
+ * treated as unknown rather than coerced to a match.
+ */
+export declare function isUnknownEnumValue(inputToken: string, optionKey: string, value: unknown): boolean;
 export {};

package/dist/ergonomic/image_output_routes.js

@@ -29,8 +29,18 @@
 import { compressMetadata } from '@giveitsmaller/contracts/operations';
 /** The resize option keys — input-keyed, raster-only (see module doc). */
 export const RESIZE_KEYS = ['width', 'height', 'fit'];
-/** Set form of {@link RESIZE_KEYS} for `string`-keyed membership tests. */
-const RESIZE_KEY_SET = new Set(RESIZE_KEYS);
+/**
+ * Options whose availability follows the INPUT format's raster capability, not
+ * the output format — resize (`width`/`height`/`fit`) plus `auto_orient`. The
+ * projection lists them on every `format_change` cell (keyed by OUTPUT), so on
+ * a format change they must be re-gated against the INPUT's `same_format` cell:
+ * a raster input carries them, an SVG (vector) input does not. Before rtkzl9gr
+ * only the resize keys were input-gated, so `auto_orient` leaked onto the
+ * `svg → raster` route and was rejected server-side.
+ */
+const INPUT_GATED_KEYS = [...RESIZE_KEYS, 'auto_orient'];
+/** Set form of {@link INPUT_GATED_KEYS} for `string`-keyed membership tests. */
+const INPUT_GATED_KEY_SET = new Set(INPUT_GATED_KEYS);
 /** Image area cap shared by every resizable route (projection `max_output_pixels`). */
 export const MAX_OUTPUT_PIXELS = 16_000_000;
 /**
@@ -117,21 +127,22 @@ export function resolveOutputRoute(inputToken, outputFormat) {
     const cell = IMAGE_OUTPUT_ROUTES.format_change[outToken];
     if (cell === undefined)
         return undefined;
-    // Resize is INPUT-gated. Since v2.103.0 convert is the resize engine, so the
-    // projection lists width/height/fit on EVERY format_change cell — but an SVG
-    // INPUT cannot be raster-resized (the convert worker rejects it). So strip the
-    // cell's resize keys and re-add only those the INPUT's same_format cell honors:
-    // raster inputs carry them, svg does not. The transcoder options (output_format/
-    // quality/background) ride the cell directly.
-    const transcoderHonored = cell.honored.filter((k) => !RESIZE_KEY_SET.has(k));
+    // Resize + auto_orient are INPUT-gated (see {@link INPUT_GATED_KEYS}). Since
+    // v2.103.0 convert is the resize engine, so the projection lists width/height/
+    // fit AND auto_orient on EVERY format_change cell — but an SVG INPUT cannot be
+    // raster-resized or auto-oriented (the convert worker rejects it). So strip
+    // the cell's input-gated keys and re-add only those the INPUT's same_format
+    // cell honors: raster inputs carry them, svg does not. The transcoder options
+    // (output_format/quality/background/color_profile) ride the cell directly.
+    const transcoderHonored = cell.honored.filter((k) => !INPUT_GATED_KEY_SET.has(k));
     const inCell = IMAGE_OUTPUT_ROUTES.same_format[inputToken];
-    const resize = inCell ? RESIZE_KEYS.filter((k) => inCell.honored.includes(k)) : [];
+    const inputGated = inCell ? INPUT_GATED_KEYS.filter((k) => inCell.honored.includes(k)) : [];
     return {
         route: 'format_change',
         sourceOp: 'convert',
         outputFormatWire: outToken,
         inputToken,
-        honored: new Set([...transcoderHonored, ...resize]),
+        honored: new Set([...transcoderHonored, ...inputGated]),
         planned: new Set(cell.planned),
     };
 }
@@ -161,3 +172,63 @@ export function isPlannedValue(inputToken, optionKey, value) {
     const entry = opt.per_value_availability[String(value)];
     return entry?.availability === 'planned';
 }
+/**
+ * Compress-route enum members per image mime-group, mirroring the shipped
+ * `availability/availability.json` `operations.compress.mime_groups.<group>.
+ * options.<opt>.values`. Kept as a hand table (NOT a runtime read of the ~238KB
+ * availability sidecar) so the enum-membership gate stays browser-safe, exactly
+ * like {@link IMAGE_OUTPUT_ROUTES} — and, crucially, so the gate has NO
+ * dependency on a contracts version that carries the enum in a compact form (a
+ * generated-metadata `values` field would fail open on an older published
+ * `@giveitsmaller/contracts`). PINNED to `availability.json` by
+ * `output-route-conformance.test.ts`; a contract regen that adds/changes an
+ * enum member fails there. Mirrored by PHP `ImageOutputRoutes::COMPRESS_OPTION_VALUES`.
+ *
+ * `image_svg`/`image_avif` carry the NARROW `metadata: ['strip','all']` (no
+ * `keep`) — the reason a value gate that consulted only the generic `image`
+ * group (`['strip','keep','all']`) let `metadata: 'keep'` reach a server 422 on
+ * those bases (rtkzl9gr). `output_format` is listed for a faithful projection
+ * mirror but is never gated here (the Output lowering owns it positionally).
+ */
+export const COMPRESS_OPTION_VALUES = {
+    image: { color_profile: ['keep', 'srgb', 'strip'], fit: ['max', 'crop', 'scale'], metadata: ['strip', 'keep', 'all'], output_format: ['original', 'webp', 'auto', 'smallest'] },
+    image_jpeg: { chroma_subsampling: ['420', '422', '444'], color_profile: ['keep', 'srgb', 'strip'], encoding_mode: ['quality', 'target_size', 'auto_quality'], fit: ['max', 'crop', 'scale'], metadata: ['strip', 'keep', 'all'], output_format: ['original', 'webp', 'auto', 'smallest'], quality_preset: ['best', 'good', 'fair', 'low'] },
+    image_png: { color_profile: ['keep', 'srgb', 'strip'], fit: ['max', 'crop', 'scale'], metadata: ['strip', 'keep', 'all'], output_format: ['original', 'webp', 'auto', 'smallest'] },
+    image_avif: { color_profile: ['keep', 'srgb', 'strip'], encoding_mode: ['quality', 'target_size', 'auto_quality'], fit: ['max', 'crop', 'scale'], metadata: ['strip', 'all'], output_format: ['original', 'webp', 'auto', 'smallest'], quality_preset: ['best', 'good', 'fair', 'low'] },
+    image_svg: { metadata: ['strip', 'all'], output_format: ['original', 'webp', 'auto', 'smallest'] },
+    image_webp: { color_profile: ['keep', 'srgb', 'strip'], encoding_mode: ['quality', 'target_size', 'auto_quality'], fit: ['max', 'crop', 'scale'], metadata: ['strip', 'keep', 'all'], output_format: ['original', 'webp', 'auto', 'smallest'], quality_preset: ['best', 'good', 'fair', 'low'] },
+};
+/**
+ * The compress mime-group whose enum members are authoritative for an image
+ * token's SAME_FORMAT route — the exact `image_<token>` group when
+ * {@link COMPRESS_OPTION_VALUES} carries one, else the generic `image` group
+ * (gif/tiff).
+ *
+ * Deliberately DISTINCT from {@link compressGroupForToken} (which the planned
+ * gate uses). The planned gate routes webp/gif/svg/tiff through the generic
+ * `image` group, where cross-format `planned` markers live (e.g. `srgb`).
+ * Enum MEMBERSHIP is the opposite: it needs the format-specific enum, because
+ * `image_svg`'s `metadata` enum is the narrow `[strip, all]` while the generic
+ * group's is `[strip, keep, all]` — so only the specific group rejects
+ * `metadata: 'keep'` on SVG (and AVIF, which already maps specifically).
+ */
+function enumGroupForToken(token) {
+    const specific = `image_${token}`;
+    return COMPRESS_OPTION_VALUES[specific] !== undefined ? specific : 'image';
+}
+/**
+ * Whether a VALUE lies OUTSIDE the option's compress-route enum for the given
+ * input format — the pre-upload enum-membership gate (rtkzl9gr). Reads the hand
+ * {@link COMPRESS_OPTION_VALUES} table. Returns false when the option is not an
+ * enum on this group (no entry), so a non-enum option (e.g. integer `quality`)
+ * is never gated. Meaningful only on the same_format (compress) route, where
+ * the compress option enums definitionally apply. Membership is STRICT: a value
+ * whose type differs from the string enum members (e.g. numeric `420`) is
+ * treated as unknown rather than coerced to a match.
+ */
+export function isUnknownEnumValue(inputToken, optionKey, value) {
+    const members = COMPRESS_OPTION_VALUES[enumGroupForToken(inputToken)]?.[optionKey];
+    if (members === undefined)
+        return false;
+    return !(typeof value === 'string' && members.includes(value));
+}

package/dist/ergonomic/option_types.d.ts

@@ -74,6 +74,12 @@ export interface ThumbnailOptions {
     /** 1-based page index for document input. */
     page?: number;
 }
+export interface TransformOptions {
+    /** Clockwise rotation in degrees. document_pdf honors `rotate` only. */
+    rotate?: 0 | 90 | 180 | 270;
+    /** Mirror axis (applied after `rotate`). Not honored on document_pdf input. */
+    flip?: 'none' | 'horizontal' | 'vertical' | 'both';
+}
 export interface TextWatermarkOptions {
     /** Font size in pixels (8-512). */
     font_size?: number;
@@ -96,6 +102,24 @@ export interface TextWatermarkOptions {
     /** Overlay opacity (0-1). */
     opacity?: number;
 }
+/**
+ * One entry in the multi-overlay stack (contract `overlays[]` items, v2.152.0).
+ * Index-aligned to the overlay-role sources — `overlays[i]` places overlay
+ * source `i` — and mirrors the flat single-overlay option shape. Matches the
+ * generated `ImageWatermarkImageOverlaysItem`.
+ */
+export interface WatermarkOverlay {
+    /** 9-grid anchor position for this overlay. */
+    anchor?: WatermarkAnchor;
+    /** Horizontal offset from the anchor (e.g. '40px' or '5%'). */
+    margin_x?: string;
+    /** Vertical offset from the anchor. */
+    margin_y?: string;
+    /** Overlay opacity (0-1). */
+    opacity?: number;
+    /** Overlay width (e.g. '120px' or '20%'). */
+    overlay_width?: string;
+}
 export interface WatermarkOptions {
     /** 9-grid anchor position. */
     anchor?: WatermarkAnchor;
@@ -107,6 +131,14 @@ export interface WatermarkOptions {
     opacity?: number;
     /** Overlay width (e.g. '120px' or '20%'). */
     overlay_width?: string;
+    /**
+     * Per-overlay placement for the multi-overlay stack (contract `overlays[]`,
+     * v2.152.0) — one entry per overlay source, index-aligned; stacks up to 8
+     * overlays on one base image (z-order = array index). MUTUALLY EXCLUSIVE with
+     * the flat single-overlay options above; the server rejects mixing the two as
+     * `invalid_options`. image_watermark jpeg/png/webp bases only.
+     */
+    overlays?: WatermarkOverlay[];
 }
 /** Resize mode (contract `fit` enum, v2.97.0). */
 export type OutputFit = 'max' | 'crop' | 'scale';
@@ -182,7 +214,8 @@ export interface OutputOptions {
 export declare const VERB_OPTION_KEYS: {
     readonly convert: readonly ["quality", "background", "crf", "trim_start", "trim_end", "fps", "width", "height", "fit", "metadata", "color_profile", "auto_orient", "max_colors", "loop", "dither", "bitrate", "pages", "dpi"];
     readonly thumbnail: readonly ["width", "height", "fit", "format", "quality", "background", "timestamp", "source", "page"];
+    readonly transform: readonly ["rotate", "flip"];
     readonly textWatermark: readonly ["font_size", "color", "font_family", "rotation", "watermark_mode", "tile_spacing", "anchor", "margin_x", "margin_y", "opacity"];
-    readonly watermark: readonly ["anchor", "margin_x", "margin_y", "opacity", "overlay_width"];
+    readonly watermark: readonly ["anchor", "margin_x", "margin_y", "opacity", "overlay_width", "overlays"];
     readonly output: readonly ["quality", "quality_preset", "encoding_mode", "target_size_bytes", "chroma_subsampling", "width", "height", "fit", "background", "progressive", "optimization_level", "avif_speed", "metadata", "color_profile", "auto_orient", "lossless"];
 };

package/dist/ergonomic/option_types.js

@@ -21,12 +21,13 @@ const CONVERT_OPTION_KEYS = [
 const THUMBNAIL_OPTION_KEYS = [
     'width', 'height', 'fit', 'format', 'quality', 'background', 'timestamp', 'source', 'page',
 ];
+const TRANSFORM_OPTION_KEYS = ['rotate', 'flip'];
 const TEXT_WATERMARK_OPTION_KEYS = [
     'font_size', 'color', 'font_family', 'rotation', 'watermark_mode',
     'tile_spacing', 'anchor', 'margin_x', 'margin_y', 'opacity',
 ];
 const WATERMARK_OPTION_KEYS = [
-    'anchor', 'margin_x', 'margin_y', 'opacity', 'overlay_width',
+    'anchor', 'margin_x', 'margin_y', 'opacity', 'overlay_width', 'overlays',
 ];
 const OUTPUT_OPTION_KEYS = [
     'quality', 'quality_preset', 'encoding_mode', 'target_size_bytes', 'chroma_subsampling', 'width', 'height', 'fit',
@@ -35,12 +36,14 @@ const OUTPUT_OPTION_KEYS = [
 ];
 const _convertKeysMatch = true;
 const _thumbnailKeysMatch = true;
+const _transformKeysMatch = true;
 const _textWatermarkKeysMatch = true;
 const _watermarkKeysMatch = true;
 const _outputKeysMatch = true;
 // Reference the assertions so `noUnusedLocals` doesn't strip them.
 void _convertKeysMatch;
 void _thumbnailKeysMatch;
+void _transformKeysMatch;
 void _textWatermarkKeysMatch;
 void _watermarkKeysMatch;
 void _outputKeysMatch;
@@ -52,6 +55,7 @@ void _outputKeysMatch;
 export const VERB_OPTION_KEYS = {
     convert: CONVERT_OPTION_KEYS,
     thumbnail: THUMBNAIL_OPTION_KEYS,
+    transform: TRANSFORM_OPTION_KEYS,
     textWatermark: TEXT_WATERMARK_OPTION_KEYS,
     watermark: WATERMARK_OPTION_KEYS,
     output: OUTPUT_OPTION_KEYS,

package/dist/ergonomic/option_validation.d.ts

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

package/dist/ergonomic/option_validation.js

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