@giveitsmaller/sdk 0.19.0 → 0.20.0

package/dist/_audit.js

@@ -139,6 +139,8 @@ export function _runAudit() {
     accept();
     // FF3a / u0hBt6fl — homogeneous fan-out builder surface.
     accept();
+    // FF7 / MFaCjL8d — keyed multi-recipe batch builder surface.
+    accept();
     // FF4a / Z7zTr789 — multi-input watermark recipe surface.
     accept();
     accept();
@@ -149,4 +151,14 @@ export function _runAudit() {
     // FF5a / Ao8RPVxD — file-first Handle reattach surface.
     accept();
     accept();
+    // TYNjcjpo — SSE parse-failure diagnostic surface.
+    accept();
+    // qUhxfDA5 — capabilities() projection surface + the three contract
+    // capability types it exposes.
+    accept();
+    accept();
+    accept();
+    accept();
+    // W8v4jWzx — error-taxonomy category union surfaced by GislApiError.category.
+    accept();
 }

package/dist/builder.d.ts

@@ -217,6 +217,7 @@ export interface UploadProgressEvent {
 export interface ProcessingProgressEvent {
     readonly phase: 'processing';
     readonly status?: SseOperationProgressDataStatusEnum;
+    /** Percent complete, `0-100` (the wire integer) — NOT a 0..1 fraction. */
     readonly progress: number;
     readonly jobRef: string;
     readonly operationId: string;

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 import type { AudioWatermarkDecodeRequest, AudioWatermarkDecodeResponse, ExternalImportCreatedResponse, ExternalImportRequest, LoginUserRequest, LoginUser200ResponseData, ContactRequest, AccountLimits, CreditsBalanceResponse, CreditsUsageResponse, UploadResponse, UploadProbeResponse, WorkflowCancelResponse, WorkflowCreateResponse, WorkflowResumeResponse, WorkflowStatusResponse, WorkflowListResponse, WorkflowSummary, WorkflowDownloadResponse, MetadataResponse, RetryResponse } from '@giveitsmaller/contracts/openapi';
-import type { CreditsUsageOptions, ListWorkflowsOptions, GetSchemaOptions, GetSchemaResult, GislClientConfig, GislSseEvent, PreflightClipsResult, ProbeWaitOptions, ProbeWaitResult, ReadCapabilityOptions, UploadOptions, WaitOptions, WorkflowCreatePayload, _Sdk3HandCodedKeepaliveResult, _Sdk3HandCodedMultipartStatusResult, _Sdk3HandCodedPresignPartsResult } from './types.js';
+import type { CreditsUsageOptions, ListWorkflowsOptions, GetSchemaOptions, GetSchemaResult, GislClientConfig, GislSseEvent, GislSseParseFailure, PreflightClipsResult, ProbeWaitOptions, ProbeWaitResult, ReadCapabilityOptions, UploadOptions, WaitOptions, WorkflowCreatePayload, _Sdk3HandCodedKeepaliveResult, _Sdk3HandCodedMultipartStatusResult, _Sdk3HandCodedPresignPartsResult } from './types.js';
 export declare const MULTIPART_CONCURRENCY_DEFAULT: 4;
 export declare const DEFAULT_MULTIPART_FIRST_CHUNK_SIZE: number;
 export interface ValidationDetail {
@@ -199,6 +199,13 @@ export declare class GislClient {
     streamEvents(workflowId: string, opts?: {
         signal?: AbortSignal;
         capability?: string;
+        /**
+         * Observe malformed-JSON SSE frames (TYNjcjpo). A frame whose `data:` body
+         * fails to parse is SKIPPED from the stream (kept resilient) and reported
+         * here as a typed {@link GislSseParseFailure} instead of being silently lost.
+         * Omit to drop malformed frames silently (the default; PHP parity).
+         */
+        onParseError?: (diagnostic: GislSseParseFailure) => void;
     }): Promise<AsyncGenerator<GislSseEvent>>;
     /**
      * Get metadata for an uploaded file.

package/dist/client.js

@@ -6,6 +6,10 @@
 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';
+// 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
@@ -109,12 +113,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 +129,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,6 +474,11 @@ 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,
             };
@@ -1747,7 +1733,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
@@ -1874,6 +1863,7 @@ export class GislClient {
         }
         if (!response.ok) {
             let errorMessage = 'Unknown error';
+            let errorCode;
             try {
                 const errJson = (await response.json());
                 // Prefer the human `message`; `error` is the machine code (x9Lbf6uy).
@@ -1881,13 +1871,18 @@ export class GislClient {
                     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;
             }
             catch {
-                // Non-JSON body — keep generic message.
+                // Non-JSON body — keep generic 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,
             });

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

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 { 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
@@ -439,7 +495,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) {
@@ -479,7 +560,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