@giveitsmaller/sdk 0.18.0 → 0.20.0

package/dist/ergonomic/preset_resolver.js

@@ -63,7 +63,6 @@ const WIRE_ALIASES = Object.freeze({
     sampleRate: 'sample_rate',
     audioCodec: 'audio_codec',
     audioBitrate: 'audio_bitrate',
-    imageQuality: 'image_quality',
     stripMacros: 'strip_macros',
     stripHiddenData: 'strip_hidden_data',
     stripUnusedFonts: 'strip_unused_fonts',
@@ -254,9 +253,9 @@ const MEDIA_FIELDS = Object.freeze({
     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(['imageQuality', 'stripMacros', 'stripHiddenData', 'stripUnusedFonts']),
-    document_odf: new Set(['imageQuality', 'stripMetadata', 'stripUnusedStyles']),
-    document_epub: new Set(['imageQuality', 'fontSubsetting', 'stripUnusedCss']),
+    document_office: new Set(['stripMacros', 'stripHiddenData', 'stripUnusedFonts']),
+    document_odf: new Set(['stripMetadata', 'stripUnusedStyles']),
+    document_epub: new Set(['fontSubsetting', 'stripUnusedCss']),
 });
 function detectMismatchedOverrides(media, overrides) {
     const expected = MEDIA_FIELDS[media];
@@ -323,9 +322,9 @@ export const KNOWN_WIRE_FIELDS = Object.freeze({
     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(['image_quality', 'strip_macros', 'strip_hidden_data', 'strip_unused_fonts']),
-    document_odf: new Set(['image_quality', 'strip_metadata', 'strip_unused_styles']),
-    document_epub: new Set(['image_quality', 'font_subsetting', 'strip_unused_css']),
+    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']),
 });
 function validateMerged(media, merged, explicitKeys, winners) {
     // Unknown-field defence-in-depth: every key must belong to the

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

@@ -1,11 +1,9 @@
 import { OptimizeFor } from '../../generated/sdk_spec/enums.js';
 export interface DocumentEpubCompressPresetOptionsInput {
-    readonly imageQuality?: number;
     readonly fontSubsetting?: boolean;
     readonly stripUnusedCss?: boolean;
 }
 export declare class DocumentEpubCompressPresetOptions {
-    readonly imageQuality?: number;
     readonly fontSubsetting?: boolean;
     readonly stripUnusedCss?: boolean;
     private constructor();

package/dist/ergonomic/presets/document_epub_compress.js

@@ -1,15 +1,12 @@
 // T4a — DocumentEpubCompressPresetOptions leaf DTO.
 //
-// Field set per ticket VhIj4S7T: EPUB = 3 fields
-//   (imageQuality, fontSubsetting, stripUnusedCss). Primitives only.
+// Field set per ticket VhIj4S7T: EPUB = 2 fields
+//   (fontSubsetting, stripUnusedCss). Primitives only.
 import { shippedDefaultsFor as f3ShippedDefaultsFor } from '../../generated/sdk_spec/presets.js';
 export class DocumentEpubCompressPresetOptions {
-    imageQuality;
     fontSubsetting;
     stripUnusedCss;
     constructor(input) {
-        if (input.imageQuality !== undefined)
-            this.imageQuality = input.imageQuality;
         if (input.fontSubsetting !== undefined)
             this.fontSubsetting = input.fontSubsetting;
         if (input.stripUnusedCss !== undefined)
@@ -23,8 +20,6 @@ export class DocumentEpubCompressPresetOptions {
         const cell = f3ShippedDefaultsFor('document_epub_compress', level);
         const input = {};
         const mut = input;
-        if ('imageQuality' in cell)
-            mut.imageQuality = cell.imageQuality;
         if ('fontSubsetting' in cell)
             mut.fontSubsetting = cell.fontSubsetting;
         if ('stripUnusedCss' in cell)

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

@@ -1,11 +1,9 @@
 import { OptimizeFor } from '../../generated/sdk_spec/enums.js';
 export interface DocumentOdfCompressPresetOptionsInput {
-    readonly imageQuality?: number;
     readonly stripMetadata?: boolean;
     readonly stripUnusedStyles?: boolean;
 }
 export declare class DocumentOdfCompressPresetOptions {
-    readonly imageQuality?: number;
     readonly stripMetadata?: boolean;
     readonly stripUnusedStyles?: boolean;
     private constructor();

package/dist/ergonomic/presets/document_odf_compress.js

@@ -1,15 +1,12 @@
 // T4a — DocumentOdfCompressPresetOptions leaf DTO.
 //
-// Field set per ticket VhIj4S7T: ODF = 3 fields
-//   (imageQuality, stripMetadata, stripUnusedStyles). Primitives only.
+// Field set per ticket VhIj4S7T: ODF = 2 fields
+//   (stripMetadata, stripUnusedStyles). Primitives only.
 import { shippedDefaultsFor as f3ShippedDefaultsFor } from '../../generated/sdk_spec/presets.js';
 export class DocumentOdfCompressPresetOptions {
-    imageQuality;
     stripMetadata;
     stripUnusedStyles;
     constructor(input) {
-        if (input.imageQuality !== undefined)
-            this.imageQuality = input.imageQuality;
         if (input.stripMetadata !== undefined)
             this.stripMetadata = input.stripMetadata;
         if (input.stripUnusedStyles !== undefined)
@@ -23,8 +20,6 @@ export class DocumentOdfCompressPresetOptions {
         const cell = f3ShippedDefaultsFor('document_odf_compress', level);
         const input = {};
         const mut = input;
-        if ('imageQuality' in cell)
-            mut.imageQuality = cell.imageQuality;
         if ('stripMetadata' in cell)
             mut.stripMetadata = cell.stripMetadata;
         if ('stripUnusedStyles' in cell)

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

@@ -1,12 +1,10 @@
 import { OptimizeFor } from '../../generated/sdk_spec/enums.js';
 export interface DocumentOfficeCompressPresetOptionsInput {
-    readonly imageQuality?: number;
     readonly stripMacros?: boolean;
     readonly stripHiddenData?: boolean;
     readonly stripUnusedFonts?: boolean;
 }
 export declare class DocumentOfficeCompressPresetOptions {
-    readonly imageQuality?: number;
     readonly stripMacros?: boolean;
     readonly stripHiddenData?: boolean;
     readonly stripUnusedFonts?: boolean;

package/dist/ergonomic/presets/document_office_compress.js

@@ -1,17 +1,14 @@
 // T4a — DocumentOfficeCompressPresetOptions leaf DTO.
 //
-// Field set per ticket VhIj4S7T: office = 4 fields
-//   (imageQuality, stripMacros, stripHiddenData, stripUnusedFonts).
+// Field set per ticket VhIj4S7T: office = 3 fields
+//   (stripMacros, stripHiddenData, stripUnusedFonts).
 // All primitive values — no enum translation needed.
 import { shippedDefaultsFor as f3ShippedDefaultsFor } from '../../generated/sdk_spec/presets.js';
 export class DocumentOfficeCompressPresetOptions {
-    imageQuality;
     stripMacros;
     stripHiddenData;
     stripUnusedFonts;
     constructor(input) {
-        if (input.imageQuality !== undefined)
-            this.imageQuality = input.imageQuality;
         if (input.stripMacros !== undefined)
             this.stripMacros = input.stripMacros;
         if (input.stripHiddenData !== undefined)
@@ -27,8 +24,6 @@ export class DocumentOfficeCompressPresetOptions {
         const cell = f3ShippedDefaultsFor('document_office_compress', level);
         const input = {};
         const mut = input;
-        if ('imageQuality' in cell)
-            mut.imageQuality = cell.imageQuality;
         if ('stripMacros' in cell)
             mut.stripMacros = cell.stripMacros;
         if ('stripHiddenData' in cell)

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