@giveitsmaller/sdk 0.20.0 → 0.21.0

package/dist/client.js

@@ -4,8 +4,8 @@
 // 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.
@@ -59,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
@@ -98,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 &&
@@ -484,13 +514,16 @@ export class GislClient {
             };
             // 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)) {
@@ -595,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
@@ -1603,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.
@@ -1624,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));
         }
@@ -1681,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.
@@ -1862,22 +1914,26 @@ 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, no machine code.
+                // 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.
@@ -1949,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/preset_resolver.d.ts

@@ -1,6 +1,6 @@
 import type { ResolvedOptions } from '../builder.js';
 import type { OptimizeFor } from '../generated/sdk_spec/enums.js';
-import { type PresetDefaults, type PresetMedia, type PresetOp } from './presets/index.js';
+import { type PresetDefaults, type PresetMedia, type DetectedMedia, type PresetOp } from './presets/index.js';
 /**
  * The preset matrix version emitted on every resolve. Re-exported from the
  * GENERATED `sdk_spec/version.ts` (source of truth: contracts
@@ -17,7 +17,7 @@ export declare const PRESET_VERSION: "1.6";
  * extend the union.
  */
 export interface ResolveCompressOptionsInput {
-    readonly media: PresetMedia;
+    readonly media: DetectedMedia;
     readonly op: PresetOp;
     /** Defaults registered via `gisl.create({ presetDefaults: ... })`. */
     readonly presetDefaults?: PresetDefaults;

package/dist/ergonomic/preset_resolver.js

@@ -37,7 +37,7 @@
 import { sha256Hex } from '../sha256.js';
 import { GislConfigError } from '../errors.js';
 import { PRESET_VERSION as GENERATED_PRESET_VERSION } from '../generated/sdk_spec/version.js';
-import { ImageCompressPresetOptions, AudioCompressPresetOptions, VideoCompressPresetOptions, DocumentPdfCompressPresetOptions, DocumentOfficeCompressPresetOptions, DocumentOdfCompressPresetOptions, DocumentEpubCompressPresetOptions, definedFieldsOf, } from './presets/index.js';
+import { ImageCompressPresetOptions, AudioCompressPresetOptions, VideoCompressPresetOptions, DocumentOfficeCompressPresetOptions, DocumentOdfCompressPresetOptions, DocumentEpubCompressPresetOptions, definedFieldsOf, } from './presets/index.js';
 /**
  * The preset matrix version emitted on every resolve. Re-exported from the
  * GENERATED `sdk_spec/version.ts` (source of truth: contracts
@@ -175,8 +175,6 @@ function sdkDefaultRecord(media, op, optimize) {
             return { ...AudioCompressPresetOptions.shippedDefaultsFor(optimize) };
         case 'video':
             return { ...VideoCompressPresetOptions.shippedDefaultsFor(optimize) };
-        case 'document_pdf':
-            return { ...DocumentPdfCompressPresetOptions.shippedDefaultsFor(optimize) };
         case 'document_office':
             return { ...DocumentOfficeCompressPresetOptions.shippedDefaultsFor(optimize) };
         case 'document_odf':
@@ -213,9 +211,6 @@ function presetDefaultsCellRecord(defaults, media, op, optimize) {
         case 'video':
             cell = defaults.cellFor('video', 'compress', optimize);
             break;
-        case 'document_pdf':
-            cell = defaults.cellFor('document_pdf', 'compress', optimize);
-            break;
         case 'document_office':
             cell = defaults.cellFor('document_office', 'compress', optimize);
             break;
@@ -252,7 +247,6 @@ const MEDIA_FIELDS = Object.freeze({
     image: new Set(['quality', 'metadata', 'outputFormat']),
     audio: new Set(['bitrate', 'channels', 'sampleRate', 'normalize']),
     video: new Set(['codec', 'targetSize', 'crf', 'preset', 'width', 'height', 'fit', 'fps', 'faststart', 'audioCodec', 'audioBitrate']),
-    document_pdf: new Set(['profile', 'grayscale']),
     document_office: new Set(['stripMacros', 'stripHiddenData', 'stripUnusedFonts']),
     document_odf: new Set(['stripMetadata', 'stripUnusedStyles']),
     document_epub: new Set(['fontSubsetting', 'stripUnusedCss']),
@@ -278,9 +272,9 @@ function detectMismatchedOverrides(media, overrides) {
         const otherSet = MEDIA_FIELDS[otherMedia];
         if (unknownFields.every((k) => otherSet.has(k))) {
             // PascalCase every underscore-separated segment so multi-segment
-            // media (`document_pdf` → `DocumentPdf…`) emit the actual exported
+            // media (`document_office` → `DocumentOffice…`) emit the actual exported
             // class name (code-review MEDIUM: previously emitted
-            // `Documentpdf…` which doesn't resolve in user code).
+            // `Documentoffice…` which doesn't resolve in user code).
             const className = otherMedia
                 .split('_')
                 .map((s) => s.charAt(0).toUpperCase() + s.slice(1))
@@ -321,7 +315,6 @@ export const KNOWN_WIRE_FIELDS = Object.freeze({
     image: new Set(['quality', 'metadata', 'output_format']),
     audio: new Set(['bitrate', 'channels', 'sample_rate', 'normalize', 'trim_start', 'trim_end']),
     video: new Set(['codec', 'encoding_mode', 'crf', 'target_size_bytes', 'preset', 'width', 'height', 'fit', 'fps', 'faststart', 'audio_codec', 'audio_bitrate', 'trim_start', 'trim_end']),
-    document_pdf: new Set(['profile', 'grayscale']),
     document_office: new Set(['strip_macros', 'strip_hidden_data', 'strip_unused_fonts']),
     document_odf: new Set(['strip_metadata', 'strip_unused_styles']),
     document_epub: new Set(['font_subsetting', 'strip_unused_css']),
@@ -444,6 +437,9 @@ function computePresetConfigHash(clientDefault, scopedDefault, callPresetOverrid
  * `optimize` unset ⇒ layer 1 contributes nothing; `resolvedOptions.preset = null`.
  */
 export function resolveCompressOptions(input) {
+    if (input.media === 'document_pdf') {
+        throw new GislConfigError('PDF compression was removed at contracts v2.166.0; convert() / transform() still accept PDF.', { reason: 'unsupported_media' });
+    }
     const { media, op, presetDefaults, scopedPresetDefaults, presetOverrides, optimize, explicitOptions, audioLossless } = input;
     if (op !== 'compress') {
         throw new GislConfigError(`Preset resolution is only wired for compress operations today; got op='${op}'.`, { reason: 'unsupported_op' });

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

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

package/dist/ergonomic/presets/index.js

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

package/dist/errors.d.ts

@@ -1,4 +1,4 @@
-import type { AuthErrorResponse, AuthRejectionEnvelope, AuthRejectionEnvelopeErrorTypeEnum, BalanceExhaustedResponse, FeatureNotAvailableResponse, FeatureTierRestrictedResponse, ProbePendingResponse, TierRestrictionResponse, UploadDurationExceedsTierResponse, UploadSizeExceedsTierResponse, WorkflowExpiredResponse } from '@giveitsmaller/contracts/openapi';
+import type { AuthErrorResponse, AuthRejectionEnvelope, AuthRejectionEnvelopeErrorTypeEnum, BalanceExhaustedResponse, FeatureNotAvailableResponse, FeatureTierRestrictedResponse, LongFormConcurrencyLimitResponse, ProbePendingResponse, TierRestrictionResponse, UploadDurationExceedsTierResponse, UploadSizeExceedsTierResponse, WorkflowExpiredResponse } from '@giveitsmaller/contracts/openapi';
 import type { ErrorCategory } from './generated/sdk_spec/errors.js';
 import type { RateLimitSnapshot } from './retry-metadata.js';
 export declare class GislError extends Error {
@@ -134,6 +134,34 @@ export declare class GislBalanceExhaustedError extends GislApiError {
     readonly payload: BalanceExhaustedResponse;
     constructor(statusCode: number, errorMessage: string, payload: BalanceExhaustedResponse, path?: string, extra?: Omit<GislApiErrorOptions, 'payload'>);
 }
+/**
+ * `429` on `POST /api/workflows` when the caller already holds the maximum
+ * number of concurrent in-flight long-form (Fargate) workflows their tier
+ * permits (Pro 2 / Max 5; Enterprise uncapped). DISTINCT from an infrastructure
+ * rate-limit `429`: it carries the machine code `LONG_FORM_CONCURRENCY_LIMIT_EXCEEDED`
+ * and a `links.upgrade` deep link, and has **no `Retry-After`** — the limit clears
+ * when an in-flight long-form workflow finishes, not on a timer. A generic infra
+ * rate-limit `429` (no matching code) surfaces as the base {@link GislApiError}
+ * instead, where {@link GislApiError.retryAfterSeconds} applies.
+ *
+ * Dispatched on the `error` CODE, not `error_type` (the envelope carries none).
+ *
+ * @example
+ * try {
+ *   await client.createWorkflow({ jobs });
+ * } catch (e) {
+ *   if (e instanceof GislLongFormConcurrencyError) {
+ *     showUpgradeCta(e.upgradeUrl); // wait on completion or upgrade — do NOT back off
+ *   }
+ *   throw e;
+ * }
+ */
+export declare class GislLongFormConcurrencyError extends GislApiError {
+    readonly payload: LongFormConcurrencyLimitResponse;
+    constructor(statusCode: number, errorMessage: string, payload: LongFormConcurrencyLimitResponse, path?: string, extra?: Omit<GislApiErrorOptions, 'payload'>);
+    /** The pricing / upgrade deep link (`links.upgrade`), or `undefined` when absent. */
+    get upgradeUrl(): string | undefined;
+}
 export declare class GislTierRestrictedError extends GislApiError {
     readonly payload: TierRestrictionResponse;
     constructor(statusCode: number, errorMessage: string, payload: TierRestrictionResponse, path?: string, extra?: Omit<GislApiErrorOptions, 'payload'>);
@@ -411,7 +439,25 @@ export declare class GislBundleAlreadyArchivedError extends GislConfigError {
     constructor();
 }
 export declare class GislTimeoutError extends GislError {
-    constructor(message: string);
+    /**
+     * The workflow this timeout is scoped to, when the SDK knows it. Set on a
+     * timed-out `run()` / `wait()` / poll / download once the workflow has been
+     * created: a timeout does NOT mean the work failed — the server keeps
+     * processing, so poll `client.getWorkflowStatus(workflowId)` /
+     * `getWorkflowDownloads(workflowId)` to recover a result that completed after
+     * the deadline, instead of re-running (a re-run re-uploads and, for
+     * authenticated callers, settles a SECOND charge for the same deliverable).
+     *
+     * `undefined` when the SDK has no id to offer. That is NOT a guarantee that
+     * nothing was created or charged: it covers both the safe case (an upload /
+     * probe timeout before any workflow existed) AND the AMBIGUOUS case (the
+     * `POST /api/workflows` request itself timed out — the server may have
+     * created and charged the workflow before its response was lost). Treat an
+     * absent id as "cannot auto-recover", not "clean slate": reconcile (e.g. list
+     * recent workflows) before re-running rather than assuming nothing happened.
+     */
+    readonly workflowId?: string;
+    constructor(message: string, workflowId?: string);
 }
 /**
  * Transport-level failure: the underlying `fetch` (or other transport) could