@giveitsmaller/sdk 0.19.0 → 0.21.0

package/dist/ergonomic/preset_resolver.d.ts

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

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,6 @@
-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 {
     constructor(message: string);
 }
@@ -14,6 +16,11 @@ export interface GislApiErrorOptions {
     readonly locale?: string;
     readonly messageParams?: Record<string, unknown>;
     readonly payload?: unknown;
+    /**
+     * The wire-stable machine error code (the response envelope's `error` field,
+     * SCREAMING_SNAKE, never localised). See {@link GislApiError.errorCode}.
+     */
+    readonly errorCode?: string;
     /**
      * The response headers from the HTTP response that produced this error.
      * Keys are LOWERCASED (HTTP header names are case-insensitive per RFC 9110,
@@ -33,6 +40,19 @@ export interface GislApiErrorOptions {
 export declare class GislApiError extends GislError {
     readonly statusCode: number;
     readonly errorMessage: string;
+    /**
+     * The wire-stable machine error code — the response envelope's `error` field
+     * (SCREAMING_SNAKE, never localised). DISTINCT from {@link errorMessage},
+     * which is the human `message`. Mirrors the PHP `GislApiError.errorCode`.
+     *
+     * Optional here (PHP's is a required field defaulting to `'unknown_error'`):
+     * a DELIBERATE optional-vs-sentinel divergence — `undefined` when the wire
+     * envelope carries no `error` (e.g. a non-JSON / invalid-JSON response). When
+     * the wire DOES carry `error`, both SDKs surface the same value. Machine
+     * dispatch still keys off the typed subclasses (`payload.errorType`); this is
+     * the flat machine code for a base `GislApiError` (e.g. a plain 404).
+     */
+    readonly errorCode?: string;
     readonly path?: string;
     readonly details?: unknown;
     readonly messageKey?: string;
@@ -53,6 +73,42 @@ export declare class GislApiError extends GislError {
      */
     readonly contentLanguage?: string;
     constructor(statusCode: number, errorMessage: string, path?: string, details?: unknown, options?: GislApiErrorOptions);
+    /**
+     * Resolve the generated `ERROR_CODES` entry for this error, SOURCE-AWARE
+     * (plan D1). ~9 registry codes are keyed by the `error_type` discriminator
+     * rather than the envelope `error` field, so try the typed discriminator
+     * FIRST (camel `errorType`, raw-snake `error_type` fallback), then fall back
+     * to the flat machine {@link errorCode}. Returns `undefined` when neither
+     * resolves — e.g. a bare base error whose payload carries no discriminator.
+     * NEVER throws on a missing payload / discriminator.
+     */
+    private resolveErrorEntry;
+    /**
+     * Whether retrying this request could plausibly succeed. `true` when the HTTP
+     * status is inherently retryable (408 / 429 / 5xx) OR the resolved taxonomy
+     * entry marks the code retryable (e.g. `probe_pending`). Note: logical OR
+     * (not `??`) — a 429 is retryable regardless of the taxonomy, and a
+     * registry-retryable code is retryable regardless of status.
+     */
+    get retryable(): boolean;
+    /**
+     * The taxonomy category for this error's machine code, from the generated
+     * `ERROR_CODES` registry, or `undefined` when the code isn't in the registry
+     * (e.g. a bare base error whose payload carries no discriminator).
+     */
+    get category(): ErrorCategory | undefined;
+    /**
+     * The rate-limit snapshot parsed from the `x-ratelimit-*` response headers,
+     * or `undefined` when they aren't all present as non-negative integers. Read
+     * this after a 429 to schedule a back-off.
+     */
+    get rateLimit(): RateLimitSnapshot | undefined;
+    /**
+     * The server-suggested back-off delay in whole seconds, parsed from the
+     * `Retry-After` response header, or `undefined` when absent / zero / past /
+     * malformed. Mirrors the retry-loop parser's semantics.
+     */
+    get retryAfterSeconds(): number | undefined;
 }
 /**
  * Shape of a single validation detail entry. Mirrors the v2
@@ -78,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'>);
@@ -355,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
@@ -439,7 +541,7 @@ export type GislSinkErrorReason = 'not_single_output' | 'downloader_unavailable'
 /**
  * Thrown by the file-first `RunResult` sinks (`toFile()` / `downloadTo()`,
  * FF1) when they cannot deliver. The machine-readable `reason` discriminates
- * the three cases, mirroring the `reason`-bag convention on
+ * the six cases below, mirroring the `reason`-bag convention on
  * {@link GislConfigError}:
  *
  *  - `not_single_output`      — `toFile()` requires exactly one output but the

package/dist/errors.js

@@ -1,3 +1,12 @@
+// W8v4jWzx — the generated error-taxonomy registry stays INTERNAL to this
+// module (only the `ErrorCategory` TYPE is re-exported from the public barrel).
+import { ERROR_CODES } from './generated/sdk_spec/errors.js';
+import { isApiRetryableStatus, rateLimitFromHeaders, retryAfterSecondsFromHeaders, } from './retry-metadata.js';
+// Registry keys are lowercase_snake; normalise the wire code / discriminator
+// (trim + lowercase) before looking it up in ERROR_CODES.
+function normalizeErrorCode(rawCode) {
+    return rawCode.trim().toLowerCase();
+}
 export class GislError extends Error {
     constructor(message) {
         super(message);
@@ -7,6 +16,19 @@ export class GislError extends Error {
 export class GislApiError extends GislError {
     statusCode;
     errorMessage;
+    /**
+     * The wire-stable machine error code — the response envelope's `error` field
+     * (SCREAMING_SNAKE, never localised). DISTINCT from {@link errorMessage},
+     * which is the human `message`. Mirrors the PHP `GislApiError.errorCode`.
+     *
+     * Optional here (PHP's is a required field defaulting to `'unknown_error'`):
+     * a DELIBERATE optional-vs-sentinel divergence — `undefined` when the wire
+     * envelope carries no `error` (e.g. a non-JSON / invalid-JSON response). When
+     * the wire DOES carry `error`, both SDKs surface the same value. Machine
+     * dispatch still keys off the typed subclasses (`payload.errorType`); this is
+     * the flat machine code for a base `GislApiError` (e.g. a plain 404).
+     */
+    errorCode;
     path;
     details;
     messageKey;
@@ -41,10 +63,69 @@ export class GislApiError extends GislError {
             this.locale = options.locale;
             this.messageParams = options.messageParams;
             this.payload = options.payload;
+            this.errorCode = options.errorCode;
             this.responseHeaders = options.responseHeaders;
             this.contentLanguage = options.contentLanguage;
         }
     }
+    /**
+     * Resolve the generated `ERROR_CODES` entry for this error, SOURCE-AWARE
+     * (plan D1). ~9 registry codes are keyed by the `error_type` discriminator
+     * rather than the envelope `error` field, so try the typed discriminator
+     * FIRST (camel `errorType`, raw-snake `error_type` fallback), then fall back
+     * to the flat machine {@link errorCode}. Returns `undefined` when neither
+     * resolves — e.g. a bare base error whose payload carries no discriminator.
+     * NEVER throws on a missing payload / discriminator.
+     */
+    resolveErrorEntry() {
+        const payload = this.payload;
+        const rawErrorType = payload?.errorType ?? payload?.error_type;
+        if (typeof rawErrorType === 'string') {
+            const byType = ERROR_CODES[normalizeErrorCode(rawErrorType)];
+            if (byType !== undefined)
+                return byType;
+        }
+        if (this.errorCode !== undefined) {
+            const byCode = ERROR_CODES[normalizeErrorCode(this.errorCode)];
+            if (byCode !== undefined)
+                return byCode;
+        }
+        return undefined;
+    }
+    /**
+     * Whether retrying this request could plausibly succeed. `true` when the HTTP
+     * status is inherently retryable (408 / 429 / 5xx) OR the resolved taxonomy
+     * entry marks the code retryable (e.g. `probe_pending`). Note: logical OR
+     * (not `??`) — a 429 is retryable regardless of the taxonomy, and a
+     * registry-retryable code is retryable regardless of status.
+     */
+    get retryable() {
+        return (isApiRetryableStatus(this.statusCode) || (this.resolveErrorEntry()?.retryable ?? false));
+    }
+    /**
+     * The taxonomy category for this error's machine code, from the generated
+     * `ERROR_CODES` registry, or `undefined` when the code isn't in the registry
+     * (e.g. a bare base error whose payload carries no discriminator).
+     */
+    get category() {
+        return this.resolveErrorEntry()?.category;
+    }
+    /**
+     * The rate-limit snapshot parsed from the `x-ratelimit-*` response headers,
+     * or `undefined` when they aren't all present as non-negative integers. Read
+     * this after a 429 to schedule a back-off.
+     */
+    get rateLimit() {
+        return rateLimitFromHeaders(this.responseHeaders);
+    }
+    /**
+     * The server-suggested back-off delay in whole seconds, parsed from the
+     * `Retry-After` response header, or `undefined` when absent / zero / past /
+     * malformed. Mirrors the retry-loop parser's semantics.
+     */
+    get retryAfterSeconds() {
+        return retryAfterSecondsFromHeaders(this.responseHeaders);
+    }
 }
 export class GislValidationError extends GislApiError {
     constructor(statusCode, errorMessage, details, path, options) {
@@ -64,6 +145,38 @@ export class GislBalanceExhaustedError extends GislApiError {
         this.name = 'GislBalanceExhaustedError';
     }
 }
+/**
+ * `429` on `POST /api/workflows` when the caller already holds the maximum
+ * number of concurrent in-flight long-form (Fargate) workflows their tier
+ * permits (Pro 2 / Max 5; Enterprise uncapped). DISTINCT from an infrastructure
+ * rate-limit `429`: it carries the machine code `LONG_FORM_CONCURRENCY_LIMIT_EXCEEDED`
+ * and a `links.upgrade` deep link, and has **no `Retry-After`** — the limit clears
+ * when an in-flight long-form workflow finishes, not on a timer. A generic infra
+ * rate-limit `429` (no matching code) surfaces as the base {@link GislApiError}
+ * instead, where {@link GislApiError.retryAfterSeconds} applies.
+ *
+ * Dispatched on the `error` CODE, not `error_type` (the envelope carries none).
+ *
+ * @example
+ * try {
+ *   await client.createWorkflow({ jobs });
+ * } catch (e) {
+ *   if (e instanceof GislLongFormConcurrencyError) {
+ *     showUpgradeCta(e.upgradeUrl); // wait on completion or upgrade — do NOT back off
+ *   }
+ *   throw e;
+ * }
+ */
+export class GislLongFormConcurrencyError extends GislApiError {
+    constructor(statusCode, errorMessage, payload, path, extra) {
+        super(statusCode, errorMessage, path, undefined, buildOptionsWithPayload(payload, extra));
+        this.name = 'GislLongFormConcurrencyError';
+    }
+    /** The pricing / upgrade deep link (`links.upgrade`), or `undefined` when absent. */
+    get upgradeUrl() {
+        return this.payload.links?.upgrade;
+    }
+}
 export class GislTierRestrictedError extends GislApiError {
     constructor(statusCode, errorMessage, payload, path, extra) {
         super(statusCode, errorMessage, path, undefined, buildOptionsWithPayload(payload, extra));
@@ -366,9 +479,30 @@ export class GislBundleAlreadyArchivedError extends GislConfigError {
     }
 }
 export class GislTimeoutError extends GislError {
-    constructor(message) {
+    /**
+     * The workflow this timeout is scoped to, when the SDK knows it. Set on a
+     * timed-out `run()` / `wait()` / poll / download once the workflow has been
+     * created: a timeout does NOT mean the work failed — the server keeps
+     * processing, so poll `client.getWorkflowStatus(workflowId)` /
+     * `getWorkflowDownloads(workflowId)` to recover a result that completed after
+     * the deadline, instead of re-running (a re-run re-uploads and, for
+     * authenticated callers, settles a SECOND charge for the same deliverable).
+     *
+     * `undefined` when the SDK has no id to offer. That is NOT a guarantee that
+     * nothing was created or charged: it covers both the safe case (an upload /
+     * probe timeout before any workflow existed) AND the AMBIGUOUS case (the
+     * `POST /api/workflows` request itself timed out — the server may have
+     * created and charged the workflow before its response was lost). Treat an
+     * absent id as "cannot auto-recover", not "clean slate": reconcile (e.g. list
+     * recent workflows) before re-running rather than assuming nothing happened.
+     */
+    workflowId;
+    constructor(message, workflowId) {
         super(message);
         this.name = 'GislTimeoutError';
+        // Normalise an empty id to "absent" — an empty string is not a usable
+        // recovery handle (some throw sites derive the id as `… ?? ''`).
+        this.workflowId = workflowId === '' ? undefined : workflowId;
     }
 }
 /**
@@ -479,7 +613,7 @@ export class GislResultNotReadyError extends GislError {
 /**
  * Thrown by the file-first `RunResult` sinks (`toFile()` / `downloadTo()`,
  * FF1) when they cannot deliver. The machine-readable `reason` discriminates
- * the three cases, mirroring the `reason`-bag convention on
+ * the six cases below, mirroring the `reason`-bag convention on
  * {@link GislConfigError}:
  *
  *  - `not_single_output`      — `toFile()` requires exactly one output but the