@giveitsmaller/sdk 0.18.0 → 0.20.0

package/dist/generated/sdk_spec/enums.d.ts

@@ -10,8 +10,9 @@ export declare const ImageFormat: {
 };
 export type ImageFormat = typeof ImageFormat[keyof typeof ImageFormat];
 export declare const ImageMetadataPolicy: {
-    readonly All: "all";
+    readonly Strip: "strip";
     readonly Keep: "keep";
+    readonly All: "all";
 };
 export type ImageMetadataPolicy = typeof ImageMetadataPolicy[keyof typeof ImageMetadataPolicy];
 export declare const VideoCodec: {
@@ -88,8 +89,9 @@ export declare const ERGONOMIC_ENUMS: {
         readonly Webp: "webp";
     };
     readonly ImageMetadataPolicy: {
-        readonly All: "all";
+        readonly Strip: "strip";
         readonly Keep: "keep";
+        readonly All: "all";
     };
     readonly VideoCodec: {
         readonly H264: "h264";

package/dist/generated/sdk_spec/enums.js

@@ -13,15 +13,21 @@ export const ImageFormat = {
     Webp: "webp",
 };
 // Image metadata handling (compress.image, optimiser/same_format route):
-//   All  = strip all EXIF/IPTC/XMP (default, smallest file)
-//   Keep = preserve EXIF/ICC/XMP — worker-proven on the libcaesium formats
-//          (JPEG/PNG/WebP/GIF/TIFF; lambdas PR #260, un-parked 2026-06-23).
+//   Strip = remove all EXIF/IPTC/XMP (default, smallest file) — the canonical
+//           strip token (renamed from `all` 2026-06-23; `all` reading as
+//           "strip all" was counterintuitive).
+//   Keep  = preserve EXIF/ICC/XMP — worker-proven on the libcaesium formats
+//           (JPEG/PNG/WebP/GIF/TIFF; lambdas PR #260, un-parked 2026-06-23).
+//   All   = DEPRECATED alias of Strip (still accepted on the wire, emits
+//           Deprecation/Sunset; the API lowers `strip`→`all` at the worker
+//           boundary). Migrate to Strip.
 // Keep is NOT available for AVIF (ravif) / SVG (SVGO) — those re-encode from
 // pixels and cannot preserve metadata, so the worker rejects it there (the
-// `metadata` enum is narrowed to [all] on those groups).
+// `metadata` enum is narrowed to [strip, all] on those groups).
 export const ImageMetadataPolicy = {
-    All: "all",
+    Strip: "strip",
     Keep: "keep",
+    All: "all",
 };
 // Video codec. H264 = widest compatibility; H265/Av1 = better compression but slower.
 export const VideoCodec = {

package/dist/generated/sdk_spec/presets.js

@@ -5,17 +5,17 @@ export const PRESETS = Object.freeze({
     "image_compress": Object.freeze({
         Size: Object.freeze({
             "quality": 65,
-            "metadata": "All",
+            "metadata": "Strip",
             "outputFormat": "Original",
         }),
         Balanced: Object.freeze({
             "quality": 80,
-            "metadata": "All",
+            "metadata": "Strip",
             "outputFormat": "Original",
         }),
         Quality: Object.freeze({
             "quality": 92,
-            "metadata": "All",
+            "metadata": "Strip",
             "outputFormat": "Original",
         }),
     }),
@@ -66,19 +66,16 @@ export const PRESETS = Object.freeze({
     }),
     "document_office_compress": Object.freeze({
         Size: Object.freeze({
-            "imageQuality": 60,
             "stripMacros": true,
             "stripHiddenData": true,
             "stripUnusedFonts": true,
         }),
         Balanced: Object.freeze({
-            "imageQuality": 80,
             "stripMacros": true,
             "stripHiddenData": false,
             "stripUnusedFonts": false,
         }),
         Quality: Object.freeze({
-            "imageQuality": 92,
             "stripMacros": false,
             "stripHiddenData": false,
             "stripUnusedFonts": false,
@@ -86,34 +83,28 @@ export const PRESETS = Object.freeze({
     }),
     "document_odf_compress": Object.freeze({
         Size: Object.freeze({
-            "imageQuality": 60,
             "stripMetadata": true,
             "stripUnusedStyles": true,
         }),
         Balanced: Object.freeze({
-            "imageQuality": 80,
             "stripMetadata": true,
             "stripUnusedStyles": false,
         }),
         Quality: Object.freeze({
-            "imageQuality": 92,
             "stripMetadata": false,
             "stripUnusedStyles": false,
         }),
     }),
     "document_epub_compress": Object.freeze({
         Size: Object.freeze({
-            "imageQuality": 60,
             "fontSubsetting": true,
             "stripUnusedCss": true,
         }),
         Balanced: Object.freeze({
-            "imageQuality": 80,
             "fontSubsetting": true,
             "stripUnusedCss": false,
         }),
         Quality: Object.freeze({
-            "imageQuality": 92,
             "fontSubsetting": false,
             "stripUnusedCss": false,
         }),

package/dist/generated/sdk_spec/version.d.ts

@@ -1,3 +1,3 @@
-export declare const SDK_SPEC_VERSION: "2.1.0";
-export declare const PRESET_VERSION: "1.4";
-export declare const PRESET_CONFIG_HASH: "sha256:62fbada24e33f983dacb0f717b0c9bb80824a208c3dc7f9af8523026e783543a";
+export declare const SDK_SPEC_VERSION: "2.2.0";
+export declare const PRESET_VERSION: "1.6";
+export declare const PRESET_CONFIG_HASH: "sha256:0fe215aede1da13430380384c58226d074c3b8344c091efc53e097c2930a34f7";

package/dist/generated/sdk_spec/version.js

@@ -1,6 +1,6 @@
 // CODE GENERATED — DO NOT EDIT.
 // Source: compression_contracts/sdk-spec/ (see sdk-spec/README.md).
 // Regenerate with: scripts/generate.py.
-export const SDK_SPEC_VERSION = "2.1.0";
-export const PRESET_VERSION = "1.4";
-export const PRESET_CONFIG_HASH = "sha256:62fbada24e33f983dacb0f717b0c9bb80824a208c3dc7f9af8523026e783543a";
+export const SDK_SPEC_VERSION = "2.2.0";
+export const PRESET_VERSION = "1.6";
+export const PRESET_CONFIG_HASH = "sha256:0fe215aede1da13430380384c58226d074c3b8344c091efc53e097c2930a34f7";

package/dist/gisl.d.ts

@@ -19,12 +19,12 @@
 import { GislClient } from './client.js';
 import { GislConfigError, GislFeatureRequiresAuthError, GislMissingCredentialsError } from './errors.js';
 import { type ResolveCredentialsOptions, type ResolveEndpointOptions } from './credentials.js';
-import type { CreditsUsageOptions, GislClientConfig } from './types.js';
-import type { AccountLimits, CreditsBalanceResponse, CreditsUsageResponse } from '@giveitsmaller/contracts/openapi';
+import type { CreditsUsageOptions, GislClientConfig, CapabilitiesSnapshot } from './types.js';
+import type { AccountLimits, CreditsBalanceResponse, CreditsUsageResponse, OperationCapability, OperationType } from '@giveitsmaller/contracts/openapi';
 import { OperationBuilder } from './builder.js';
 import { MergeBuilder, type Asset, type MergeOptions } from './merge.js';
 import { PresetDefaults } from './ergonomic/presets/index.js';
-import { Recipe, FilesRecipe, type FileInput } from './file-first.js';
+import { Recipe, FilesRecipe, BatchRecipe, type FileInput } from './file-first.js';
 import { Handle } from './handle.js';
 /**
  * Operations that may be invoked on a `gisl.anonymous()` client without
@@ -61,6 +61,21 @@ export interface GislCreateOptions extends ResolveCredentialsOptions, ResolveEnd
  * legitimately have no apiKey at construction time.
  */
 export declare function create(opts?: GislCreateOptions): Promise<ErgonomicClient>;
+/**
+ * Operation types that need MORE THAN ONE input source, so they cannot be
+ * driven through the single-input {@link ErgonomicClient.operation} escape
+ * hatch — each has a dedicated multi-input builder (`merge(...)`,
+ * `files(...).archive(...)`, `file(a).watermark(b)`). Excluded from
+ * `operation()`'s op-type autocomplete.
+ */
+export type MultiInputOperationType = 'merge' | 'archive' | 'image_watermark' | 'video_watermark' | 'audio_overlay' | 'audio_to_video';
+/**
+ * Op types reachable via {@link ErgonomicClient.operation}: every
+ * {@link OperationType} except the {@link MultiInputOperationType} ones, widened
+ * with `(string & {})` so a genuinely-unknown (not-yet-in-contract) op type is
+ * still accepted while known single-input ops keep autocomplete.
+ */
+export type SingleInputOperationType = Exclude<OperationType, MultiInputOperationType> | (string & {});
 /**
  * The ergonomic-client surface: `GislClient` (verbatim low-level API)
  * plus three ergonomic op-builder factories. Intersection type — at
@@ -91,6 +106,20 @@ export type ErgonomicClient = GislClient & {
      * returns a {@link Handle} whose `wait()`/`result()` partition per input.
      */
     files(inputs: ReadonlyArray<string | Blob | FileInput>): FilesRecipe;
+    /**
+     * Keyed multi-recipe batch entry point (FF7). Run N DISTINCT single-input
+     * keyed {@link Recipe}s as ONE workflow — build each via
+     * `client.file(input, key).<op>(...)` with a UNIQUE key, then
+     * `client.batch([r1, r2, …]).run()`. The partitioned {@link RunResult}
+     * addresses each entry's outputs by its caller key (`res.byKey('hero')`); one
+     * failed entry lands in `failed` without sinking the rest.
+     *
+     * v1 accepts ONLY single-input {@link Recipe} entries — the multi-input
+     * builders ({@link FilesRecipe} via `files(...)`, `merge(...)`, `archive(...)`,
+     * `watermark(...)`) are rejected pre-upload with a typed {@link GislConfigError}.
+     * `.run()`-only; `.submit()` / reattach are a follow-up.
+     */
+    batch(recipes: ReadonlyArray<Recipe>): BatchRecipe;
     /**
      * Reattach to a previously-created workflow (FF5a). Returns a client-bound
      * {@link Handle} you can `.status()` / `.wait()` / `.result()`. The handle
@@ -102,6 +131,8 @@ export type ErgonomicClient = GislClient & {
     compress(input: string | Blob, options?: Record<string, unknown>): OperationBuilder;
     convert(input: string | Blob, options?: Record<string, unknown>): OperationBuilder;
     thumbnail(input: string | Blob, options?: Record<string, unknown>): OperationBuilder;
+    /** Geometric transform (rotate/flip). Passthrough; the op is `planned` (server 422s until Lambdas ship). */
+    transform(input: string | Blob, options?: Record<string, unknown>): OperationBuilder;
     /**
      * Merge ordered-sequence factory (T3). Accepts a variadic list of assets
      * (strings/Blobs/`handle()`/`asset()`) optionally terminated by a
@@ -135,6 +166,44 @@ export type ErgonomicClient = GislClient & {
     creditsUsage(options?: CreditsUsageOptions): Promise<CreditsUsageResponse>;
     /** Effective account limits / tier-resolved caps (sugar for `getAccountLimits()`). */
     limits(): Promise<AccountLimits>;
+    /**
+     * Operation-capability read helper (qUhxfDA5). A typed projection over
+     * `getSchema()` that surfaces the tier-scoped operation-capability matrix,
+     * the output-property table, and the image-encode capability matrix —
+     * without dropping to the low-level `getSchema()` and its not-modified union.
+     *
+     * Called with no argument it returns the full {@link CapabilitiesSnapshot};
+     * called with an operation type it returns just that op's
+     * {@link OperationCapability}, or `undefined` when the op is absent from the
+     * server's capability matrix.
+     *
+     * Degraded fallback: if the client is configured to force conditional
+     * revalidation (a static `If-None-Match` in `config.headers`) the schema
+     * fetch may 304 with no body — in that case the snapshot is empty / the
+     * per-op lookup is `undefined`.
+     */
+    capabilities(): Promise<CapabilitiesSnapshot>;
+    capabilities(opType: OperationType | (string & {})): Promise<OperationCapability | undefined>;
+    /**
+     * Generic operation escape hatch (qUhxfDA5). Build + run a SINGLE-input,
+     * SINGLE-operation job for an op type with no first-class verb (e.g.
+     * `text_watermark`, `split`, or a not-yet-in-contract op). `options` reach the
+     * wire unchanged — there is NO pre-upload validation (the server validates) and
+     * NO preset resolution unless `opType` is `compress`. Prefer the typed verbs
+     * (`compress` / `convert` / `thumbnail`) when they exist — they add local
+     * validation.
+     *
+     * Multi-input operations (`merge`, `archive`, overlay watermarks — see
+     * {@link MultiInputOperationType}) are REJECTED at compile time: passing one
+     * of those literals is a type error (its dedicated builder is `merge(...)`,
+     * `files(...).archive(...)`, or `file(a).watermark(b)`). A genuinely-unknown
+     * (not-yet-in-contract) op string is still accepted.
+     *
+     * The generic parameter enforces the exclusion: a known single-input op or an
+     * unknown string maps to itself, while a {@link MultiInputOperationType}
+     * literal maps to `never` (so it cannot be passed).
+     */
+    operation<Op extends SingleInputOperationType>(opType: Op extends MultiInputOperationType ? never : Op, input: string | Blob, options?: Record<string, unknown>): OperationBuilder;
 };
 /**
  * The `gisl` namespace — primary ergonomic-layer entry point.

package/dist/gisl.js

@@ -20,9 +20,10 @@ import { GislClient } from './client.js';
 import { GislConfigError, GislFeatureRequiresAuthError, GislMissingCredentialsError, } from './errors.js';
 import { resolveApiKey, resolveEndpoint, } from './credentials.js';
 import { OperationBuilder } from './builder.js';
+import { validateVerbOptions, validateSingleOpConvertOptions, assertThumbnailDimensions, } from './ergonomic/option_validation.js';
 import { MergeBuilder, asset } from './merge.js';
 import { PresetDefaults } from './ergonomic/presets/index.js';
-import { Recipe, FilesRecipe, fileInput } from './file-first.js';
+import { Recipe, FilesRecipe, BatchRecipe, fileInput } from './file-first.js';
 import { Handle } from './handle.js';
 // ---------------------------------------------------------------------------
 // Anonymous-capable operation allowlist (internal)
@@ -112,14 +113,42 @@ function wrapErgonomic(client, presetDefaults, scopedPresetDefaults) {
                     return new FilesRecipe(resolved, [], presetDefaults, scopedPresetDefaults, target);
                 };
             }
+            if (prop === 'batch') {
+                // Keyed multi-recipe batch entry point (FF7). Run N DISTINCT single-input
+                // keyed recipes as ONE workflow; run() partitions the RunResult per entry
+                // by the caller key given at `file(input, key)` time. Client-only ctor —
+                // each entry already captured its own preset defaults at `client.file(...)`
+                // time, so batch never re-plumbs presetDefaults/scopedPresetDefaults.
+                return (recipes) => new BatchRecipe(recipes, target);
+            }
             if (prop === 'workflow') {
                 // Reattach to a previously-created workflow (FF5a). Returns a
                 // client-bound Handle with no webhookSecret and no recipe key —
                 // its RunResult is therefore keyless (succeeded[].key === null).
                 return (id) => new Handle(id, undefined, target);
             }
-            if (prop === 'compress' || prop === 'convert' || prop === 'thumbnail') {
+            if (prop === 'compress' || prop === 'convert' || prop === 'thumbnail' || prop === 'transform') {
                 return (input, options = {}) => {
+                    // ExVcchMz — validate the option bag pre-upload for the exported
+                    // single-op builder so a bad bag (unknown key / missing thumbnail dims /
+                    // missing convert target) fails locally instead of as a server 422.
+                    // `compress` is EXCLUDED: it validates through the preset resolver
+                    // (resolveCompressOptions / KNOWN_WIRE_FIELDS), not these guards.
+                    // `convert` uses a SINGLE-OP-specific guard (NOT validateVerbOptions):
+                    // the single-op builder has no positional format, so its target rides
+                    // the bag as `output_format` — which the file-first convert guard would
+                    // reject as positional-owned. `thumbnail` reuses the file-first guards
+                    // (it has no positional-owned keys).
+                    if (prop === 'convert')
+                        validateSingleOpConvertOptions(options);
+                    if (prop === 'thumbnail') {
+                        validateVerbOptions('thumbnail', options);
+                        assertThumbnailDimensions(options);
+                    }
+                    // `transform` is a passthrough (rotate/flip); no positional-owned keys
+                    // and no required dims — just the generic key-validation.
+                    if (prop === 'transform')
+                        validateVerbOptions('transform', options);
                     // T4b — pass client-scope presetDefaults into the builder so
                     // .run()/.submit() consult the preset resolver. The Proxy's
                     // closure carries the same reference for every per-call
@@ -178,6 +207,47 @@ function wrapErgonomic(client, presetDefaults, scopedPresetDefaults) {
             if (prop === 'limits') {
                 return () => target.getAccountLimits();
             }
+            if (prop === 'capabilities') {
+                // qUhxfDA5 — READ/PROJECTION over getSchema() surfacing the three
+                // v2.124 capability fields (previously typed but with no ergonomic
+                // consumer). No arg → the full CapabilitiesSnapshot; an opType → that
+                // op's OperationCapability (or undefined when absent).
+                return async (opType) => {
+                    const schema = await target.getSchema();
+                    // capabilities() passes no conditional headers, so getSchema()
+                    // normally returns the 200 hit with data. A 304 is only possible if
+                    // the caller globally configured a conditional header (e.g. a static
+                    // `If-None-Match` in `config.headers`) — an unusual, self-inflicted
+                    // case. Rather than throw, degrade to an empty projection (documented
+                    // on the method); a caller who forces revalidation gets no snapshot.
+                    const data = schema.notModified ? undefined : schema.data;
+                    const operations = data?.capabilities ?? {};
+                    if (opType !== undefined) {
+                        return operations[opType];
+                    }
+                    return {
+                        operations,
+                        outputProperties: data?.outputProperties ?? {},
+                        ...(data?.imageEncodeCapabilities !== undefined
+                            ? { imageEncode: data.imageEncodeCapabilities }
+                            : {}),
+                    };
+                };
+            }
+            if (prop === 'operation') {
+                // qUhxfDA5 — generic escape-hatch sibling of the single-op verbs
+                // (compress/convert/thumbnail). Builds a SINGLE-input, SINGLE-operation
+                // job for an op type with no typed verb (e.g. `text_watermark`, `split`,
+                // or a not-yet-in-contract op). Options ride through to the wire
+                // unchanged (no preset resolution unless opType is 'compress'); NO
+                // pre-upload validation — the server validates.
+                //
+                // Multi-input operations (merge, archive, image/video/audio overlay
+                // watermarks) canNOT be expressed here — they need multiple sources and
+                // have dedicated builders (`merge(...)`, `files(...).archive(...)`,
+                // `file(a).watermark(b)`). They are excluded from the op-type param.
+                return (opType, input, options = {}) => new OperationBuilder(target, opType, input, options, presetDefaults, scopedPresetDefaults);
+            }
             return Reflect.get(target, prop, receiver);
         },
     });

package/dist/index.core.d.ts

@@ -1,10 +1,11 @@
 export { GislClient, DEFAULT_MULTIPART_FIRST_CHUNK_SIZE } from './client.js';
 export { parseSseStream } from './sse.js';
-export type { CreditsUsageOptions, ListWorkflowsOptions, GetSchemaOptions, GetSchemaResult, PreflightClipError, PreflightClipsResult, ProbeWaitOptions, ProbeWaitResult, GislClientConfig, GislSseEvent, UploadOptions, WaitOptions, WorkflowCreatePayload, OperationDef, WorkflowSourcePayload, MultiInputSourcePayload, UploadSourcePayload, JobOutputSourcePayload, ExternalImportSourcePayload, ConnectionSourcePayload, JobInputV2Payload, JobDefinitionPayload, ExternalDestinationPayload, DeliveryPayload, DeliveryModePayload, DeliveryBundleFormatPayload, DeliverySelectionPayload, DeliverySelectionTypePayload, DeliveryOutputRefPayload, WorkflowProcessingPayload, ProcessingClassHintPayload, MultipartCheckpointState, _Sdk3HandCodedUploadedPart, _Sdk3HandCodedMultipartStatusResult, _Sdk3HandCodedPresignedPart, _Sdk3HandCodedPresignPartsResult, _Sdk3HandCodedKeepaliveResult, } from './types.js';
+export type { CreditsUsageOptions, ListWorkflowsOptions, GetSchemaOptions, GetSchemaResult, CapabilitiesSnapshot, PreflightClipError, PreflightClipsResult, ProbeWaitOptions, ProbeWaitResult, GislClientConfig, GislSseEvent, GislSseParseFailure, UploadOptions, WaitOptions, WorkflowCreatePayload, OperationDef, WorkflowSourcePayload, MultiInputSourcePayload, UploadSourcePayload, JobOutputSourcePayload, ExternalImportSourcePayload, ConnectionSourcePayload, JobInputV2Payload, JobDefinitionPayload, ExternalDestinationPayload, DeliveryPayload, DeliveryModePayload, DeliveryBundleFormatPayload, DeliverySelectionPayload, DeliverySelectionTypePayload, DeliveryOutputRefPayload, WorkflowProcessingPayload, ProcessingClassHintPayload, MultipartCheckpointState, _Sdk3HandCodedUploadedPart, _Sdk3HandCodedMultipartStatusResult, _Sdk3HandCodedPresignedPart, _Sdk3HandCodedPresignPartsResult, _Sdk3HandCodedKeepaliveResult, } from './types.js';
 export { uploadSource, jobOutputSource, externalImportSource, connectionSource, } from './types.js';
 export type { GislConfigErrorMetadata } from './errors.js';
 export { GislError, GislApiError, GislValidationError, GislBalanceExhaustedError, GislTierRestrictedError, GislFeatureTierRestrictedError, GislFeatureNotAvailableError, GislWorkflowExpiredError, GislProbePendingError, GislAuthError, GislUploadCapExceededError, GislMultipartPartError, GislMultipartPartCountError, GislMultipartSessionNotFoundError, GislMultipartSessionOwnershipError, GislMultipartSessionAuthRequiredError, GislTimeoutError, GislAbortError, GislNetworkError, GislConfigError, GislMissingCredentialsError, GislFeatureRequiresAuthError, GislUndeclaredAssetError, GislUnusedAssetError, GislPerInputOptionsNotSupportedError, GislChainCardinalityMismatchError, GislBundleAlreadyArchivedError, GislNoSuchKeyError, GislSinkError, GislItemFailedError, GislResultNotReadyError, } from './errors.js';
 export type { GislApiErrorOptions, GislUploadCapKind } from './errors.js';
+export type { ErrorCategory } from './generated/sdk_spec/errors.js';
 export { RunResult } from './file-first.js';
 export type { OutputFile, ItemResult, ItemFailure, Manifest, Downloader, } from './file-first.js';
 export { Recipe, fileInput } from './file-first.js';
@@ -15,9 +16,10 @@ export { ArchivedRecipe } from './file-first.js';
 export type { ArchiveRecipeOptions } from './file-first.js';
 export { WatermarkedRecipe } from './file-first.js';
 export type { WatermarkWireOp } from './file-first.js';
+export { BatchRecipe } from './file-first.js';
 export { Handle, StatusSnapshot } from './handle.js';
 export { gisl, create } from './gisl.js';
-export type { GislCreateOptions, Environment, ErgonomicClient } from './gisl.js';
+export type { GislCreateOptions, Environment, ErgonomicClient, SingleInputOperationType, MultiInputOperationType, } from './gisl.js';
 export { presetDefaults, PresetDefaults, type PresetMedia, type PresetOp, type AnyPresetOptions, ImageCompressPresetOptions, type ImageCompressPresetOptionsInput, AudioCompressPresetOptions, type AudioCompressPresetOptionsInput, VideoCompressPresetOptions, type VideoCompressPresetOptionsInput, DocumentPdfCompressPresetOptions, type DocumentPdfCompressPresetOptionsInput, DocumentOfficeCompressPresetOptions, type DocumentOfficeCompressPresetOptionsInput, DocumentOdfCompressPresetOptions, type DocumentOdfCompressPresetOptionsInput, DocumentEpubCompressPresetOptions, type DocumentEpubCompressPresetOptionsInput, OptimizeFor, ImageMetadataPolicy, ImageFormat, VideoCodec, VideoPreset, VideoFit, AudioBitrate, AudioCodec, AudioSampleRate, PdfProfile, PdfColorspace, } from './ergonomic/presets/index.js';
 export { OperationBuilder, MapEachBuilder } from './builder.js';
 export { MergeBuilder, asset, handle, clip } from './merge.js';
@@ -25,14 +27,14 @@ export type { Asset, ClipEntry, ClipOptions, MergeMediaKind, MergeOptions, Seque
 export type { Artifact, ArtifactRef, JobBreakdown, OperationBreakdown, ProcessingProgressEvent, ProgressEvent, ResolvedOptions, ResolvedOptionsSources, Result, RunOptions, SubmitOptions, UploadProgressEvent, } from './builder.js';
 export { PRESET_VERSION, resolveCompressOptions } from './ergonomic/preset_resolver.js';
 export type { ResolveCompressOptionsInput, ResolveCompressOptionsOutput, } from './ergonomic/preset_resolver.js';
-export type { AccountLimits, AccountLimitsLimits, AccountLimitEntry, AudioWatermarkDecodeRequest, AudioWatermarkDecodeResponse, ContactRequest, CreditsBalanceResponse, CreditsUsageResponse, CreditTransaction, ExternalImportCreatedResponse, ExternalImportRequest, LoginUserRequest, LoginUser200ResponseData, LoginUser200ResponseDataUser, WorkflowCancelResponse, WorkflowResumeResponse, WorkflowPausedDetail, WorkflowPausedDetailLinks, UploadResponse, UploadConstraintsApplied, UploadProbeResponse, UploadProbeMediaMetadata, MultipartInitiateRequestMetadataHint, WorkflowCreateResponse, WorkflowStatusResponse, WorkflowListResponse, WorkflowSummary, WorkflowDownloadResponse, MetadataResponse, MetadataResponseDimensions, MetadataResponseExif, MetadataResponseExifGps, OperationsSchemaResponse, OperationSchemaDefinition, MimeGroupSchema, OptionSchema, PerValueAvailabilityEntry, PerRoleCardinalityEntry, RetryResponse, JobDownload, OperationDownload, DownloadBundle, WebhookPayload, WebhookOperationContext, JobResponse, OperationResponse, OperationResult, OperationResultMetrics, ExternalDestination, Delivery, DeliveryPlan, DeliveryPlanOutput, WorkflowProcessing, ProcessingPlan, ProcessingPlanJob, WorkflowEdge, WorkflowWarning, JobInputV2, WorkflowSource, UploadSource, JobOutputSource, ConnectionSource, ExternalImportToken, BalanceExhaustedResponse, BalanceExhaustedResponseAllOfLinks, TierRestrictionResponse, FeatureTierRestrictedResponse, FeatureNotAvailableResponse, FeatureViolation, WorkflowExpiredResponse, ProbePendingResponse, AuthErrorResponse, } from '@giveitsmaller/contracts/openapi';
+export type { AccountLimits, AccountLimitsLimits, AccountLimitEntry, AudioWatermarkDecodeRequest, AudioWatermarkDecodeResponse, ContactRequest, CreditsBalanceResponse, CreditsUsageResponse, CreditTransaction, ExternalImportCreatedResponse, ExternalImportRequest, LoginUserRequest, LoginUser200ResponseData, LoginUser200ResponseDataUser, WorkflowCancelResponse, WorkflowResumeResponse, WorkflowPausedDetail, WorkflowPausedDetailLinks, UploadResponse, UploadConstraintsApplied, UploadProbeResponse, UploadProbeMediaMetadata, MultipartInitiateRequestMetadataHint, WorkflowCreateResponse, WorkflowStatusResponse, WorkflowListResponse, WorkflowSummary, WorkflowDownloadResponse, MetadataResponse, MetadataResponseDimensions, MetadataResponseExif, MetadataResponseExifGps, OperationsSchemaResponse, OperationCapability, OutputProperties, ImageEncodeCapabilities, OperationSchemaDefinition, MimeGroupSchema, OptionSchema, PerValueAvailabilityEntry, PerRoleCardinalityEntry, RetryResponse, JobDownload, OperationDownload, DownloadBundle, WebhookPayload, WebhookOperationContext, JobResponse, OperationResponse, OperationResult, OperationResultMetrics, ExternalDestination, Delivery, DeliveryPlan, DeliveryPlanOutput, WorkflowProcessing, ProcessingPlan, ProcessingPlanJob, WorkflowEdge, WorkflowWarning, JobInputV2, WorkflowSource, UploadSource, JobOutputSource, ConnectionSource, ExternalImportToken, BalanceExhaustedResponse, BalanceExhaustedResponseAllOfLinks, TierRestrictionResponse, FeatureTierRestrictedResponse, FeatureNotAvailableResponse, FeatureViolation, WorkflowExpiredResponse, ProbePendingResponse, AuthErrorResponse, } from '@giveitsmaller/contracts/openapi';
 export { AudioWatermarkDecodeRequestMethodHintEnum, AudioWatermarkDecodeResponseMethodEnum, OperationInputModel, ExternalImportRequestProviderHintEnum, ContactSubject, CreditTransactionSourceBucket, UploadProbeStatus, UploadProbeProcessingClass, WorkflowCancelBillingEffect, WorkflowPauseRequiredAction, WorkflowStatus, WarningType, WorkflowWarningSeverity, OperationType, SseEventType, CallbackEventType, OperationStatus, JobStatus, JobInputV2RoleEnum, AuthErrorType, TierRestrictionKind, BalanceExhaustedResponseRequiredActionEnum, ProcessingClassReason, DeliveryPlanReason, UserTier, ProcessingClass, } from '@giveitsmaller/contracts/openapi';
 export type { SseOperationProgressData, SseOperationCompletedData, SseOperationFailedData, SseJobCompletedData, SseJobFailedData, SseWorkflowTerminalData, } from '@giveitsmaller/contracts/openapi';
 export type { MultiOutputCompletion, PageIndexed, PositionIndexed, Unindexed, } from '@giveitsmaller/contracts/asyncapi';
 import type { MultiOutputCompletion as _MultiOutputCompletion } from '@giveitsmaller/contracts/asyncapi';
 export type OperationResultOutputEntry = _MultiOutputCompletion['outputs'][number];
-export type { CompressImageOptions, CompressImageJpegOptions, CompressImagePngOptions, CompressImageAvifOptions, CompressVideoOptions, CompressAudioOptions, CompressDocumentPdfOptions, CompressDocumentOfficeOptions, CompressDocumentOdfOptions, CompressDocumentEpubOptions, ThumbnailImageOptions, ThumbnailVideoOptions, ThumbnailDocumentOptions, ConvertImageOptions, ConvertVideoOptions, ConvertAudioOptions, ConvertDocumentPdfOptions, MergeImageOptions, MergeVideoOptions, MergeVideoPerInputOptions, MergeAudioOptions, MergeAudioPerInputOptions, ArchiveOptions, ImageWatermarkImageOptions, ImageWatermarkImageGifOptions, TextWatermarkImageOptions, CustomLumaVideoOptions, AudioOverlayAudioOptions, AudioOverlayVideoOptions, AudioWatermarkAudioOptions, AudioWatermarkVideoOptions, AudioToVideoAudioOptions, VideoWatermarkVideoOptions, VideoTextWatermarkVideoOptions, SplitImageGifOptions, SplitDocumentPdfOptions, SplitAudioOptions, SplitVideoOptions, } from '@giveitsmaller/contracts/operations';
+export type { CompressImageOptions, CompressImageJpegOptions, CompressImagePngOptions, CompressImageAvifOptions, CompressVideoOptions, CompressAudioOptions, CompressDocumentPdfOptions, CompressDocumentOfficeOptions, CompressDocumentOdfOptions, CompressDocumentEpubOptions, ThumbnailImageOptions, ThumbnailVideoOptions, ThumbnailDocumentOptions, TransformImageOptions, TransformImageGifOptions, TransformVideoOptions, TransformDocumentPdfOptions, ConvertImageOptions, ConvertVideoOptions, ConvertAudioOptions, ConvertDocumentPdfOptions, MergeImageOptions, MergeVideoOptions, MergeVideoPerInputOptions, MergeAudioOptions, MergeAudioPerInputOptions, ArchiveOptions, ImageWatermarkImageOptions, ImageWatermarkImageGifOptions, TextWatermarkImageOptions, CustomLumaVideoOptions, AudioOverlayAudioOptions, AudioOverlayVideoOptions, AudioWatermarkAudioOptions, AudioWatermarkVideoOptions, AudioToVideoAudioOptions, VideoWatermarkVideoOptions, VideoTextWatermarkVideoOptions, SplitImageGifOptions, SplitDocumentPdfOptions, SplitAudioOptions, SplitVideoOptions, } from '@giveitsmaller/contracts/operations';
 export { ImageWatermarkImageAnchor, ImageWatermarkImageGifAnchor, TextWatermarkImageAnchor, TextWatermarkImageFontFamily, TextWatermarkImageWatermarkMode, AudioOverlayAudioMode, AudioOverlayVideoMode, AudioOverlayVideoNoAudioTrackBehaviour, AudioWatermarkAudioMethod, AudioWatermarkAudioRobustness, AudioWatermarkAudioDensity, AudioWatermarkVideoMethod, AudioWatermarkVideoRobustness, AudioWatermarkVideoDensity, AudioToVideoAudioOutputResolution, AudioToVideoAudioImageFit, AudioToVideoAudioOutputFormat, VideoWatermarkVideoAnchor, VideoTextWatermarkVideoFontFamily, VideoTextWatermarkVideoWatermarkMode, VideoTextWatermarkVideoAnchor, SplitImageGifOutputFormat, SplitDocumentPdfMode, SplitAudioMode, SplitAudioPrecision, SplitVideoMode, SplitVideoPrecision, } from '@giveitsmaller/contracts/operations';
-export { archiveMetadata, audioOverlayMetadata, audioWatermarkMetadata, compressMetadata, convertMetadata, customLumaMetadata, imageWatermarkMetadata, mergeMetadata, textWatermarkMetadata, thumbnailMetadata, audioToVideoMetadata, videoWatermarkMetadata, videoTextWatermarkMetadata, splitMetadata, } from '@giveitsmaller/contracts/operations';
-export type { ConvertOptions, ThumbnailOptions, TextWatermarkOptions, WatermarkOptions, WatermarkAnchor, } from './ergonomic/option_types.js';
+export { archiveMetadata, audioOverlayMetadata, audioWatermarkMetadata, compressMetadata, convertMetadata, customLumaMetadata, imageWatermarkMetadata, mergeMetadata, textWatermarkMetadata, thumbnailMetadata, audioToVideoMetadata, videoWatermarkMetadata, videoTextWatermarkMetadata, splitMetadata, transformMetadata, } from '@giveitsmaller/contracts/operations';
+export type { ConvertOptions, ThumbnailOptions, TransformOptions, TextWatermarkOptions, WatermarkOptions, WatermarkOverlay, WatermarkAnchor, } from './ergonomic/option_types.js';
 export type { OperationMetadata, AvailabilityValue, AvailabilityEntry, FeatureEntry, MimeGroupMetadata, OptionMetadata, ProcessingClassConstraints, } from '@giveitsmaller/contracts/operations';

package/dist/index.core.js

@@ -55,6 +55,11 @@ export { ArchivedRecipe } from './file-first.js';
 // post-watermark ops on, then run()/submit(). Routes image_watermark / video_watermark
 // by base media; gates planned/unsupported bases locally pre-upload.
 export { WatermarkedRecipe } from './file-first.js';
+// File-first keyed multi-recipe batch (FF7 / MFaCjL8d) — `client.batch([r1, r2, …])`
+// runs N DISTINCT single-input keyed recipes as ONE workflow; run() partitions the
+// RunResult by each entry's caller key. v1 = single-input keyed, run()-only; the
+// multi-input builders are rejected pre-upload.
+export { BatchRecipe } from './file-first.js';
 // `HttpDownloader` (Node streaming downloader) is re-exported from the Node-only
 // entry `index.ts`, NOT here — it statically imports node:fs/node:stream.
 // `projectDownloadsToRunResult` is intentionally NOT re-exported here — it is an
@@ -109,4 +114,7 @@ AudioToVideoAudioOutputResolution, AudioToVideoAudioImageFit, AudioToVideoAudioO
 // surfaces as `GislFeatureNotAvailableError`).
 export { archiveMetadata, audioOverlayMetadata, audioWatermarkMetadata, compressMetadata, convertMetadata, customLumaMetadata, imageWatermarkMetadata, mergeMetadata, textWatermarkMetadata, thumbnailMetadata, 
 // New planned operation metadata sidecars — contracts v2.15 (AJCLLGaG).
-audioToVideoMetadata, videoWatermarkMetadata, videoTextWatermarkMetadata, splitMetadata, } from '@giveitsmaller/contracts/operations';
+audioToVideoMetadata, videoWatermarkMetadata, videoTextWatermarkMetadata, splitMetadata, 
+// transform is `availability: planned` — consumers can inspect this sidecar to
+// gate UI before submitting (the API otherwise returns feature_not_available/422). T4.
+transformMetadata, } from '@giveitsmaller/contracts/operations';

package/dist/merge.d.ts

@@ -90,13 +90,25 @@ export interface MergeOptions {
     readonly crossfadeDuration?: number;
     readonly gapDuration?: number;
     readonly normalizeAudio?: boolean;
+    /**
+     * Video re-encode policy (`auto` | `always` | `never`). Passed through
+     * verbatim — `codec`/`crf`/`preset`/`targetResolution`/`targetSize` are only
+     * honoured by the worker when re-encoding (`auto`/`always`); the server owns
+     * that dependency validation (the SDK is a passthrough allowlist, same as the
+     * pre-existing codec/crf/preset fields). Video merge only.
+     */
+    readonly reEncodeMode?: string;
     readonly codec?: string;
     readonly crf?: number;
     readonly preset?: string;
+    /** Video output dimensions `WxH` (e.g. `"1920x1080"`); omit to inherit from inputs. Video merge only. */
+    readonly targetResolution?: string;
     readonly targetSize?: string | number;
     readonly transitionDuration?: number;
     readonly fps?: number;
     readonly durationPerImage?: number;
+    /** Milliseconds between frames for an animated-GIF image merge (`output_type: gif`). Image merge only. */
+    readonly delay?: number;
     readonly loopCount?: number;
     readonly output?: string;
     readonly videoFormat?: string;

package/dist/merge.js

@@ -406,12 +406,16 @@ export class MergeBuilder {
             out.gapDuration = o.gapDuration;
         // Video only.
         if (mediaKind === 'video') {
+            if (o.reEncodeMode !== undefined)
+                out.reEncodeMode = o.reEncodeMode;
             if (o.codec !== undefined)
                 out.codec = o.codec;
             if (o.crf !== undefined)
                 out.crf = o.crf;
             if (o.preset !== undefined)
                 out.preset = o.preset;
+            if (o.targetResolution !== undefined)
+                out.targetResolution = o.targetResolution;
             if (o.targetSize !== undefined)
                 out.targetSize = o.targetSize;
         }
@@ -423,6 +427,8 @@ export class MergeBuilder {
                 out.fps = o.fps;
             if (o.durationPerImage !== undefined)
                 out.durationPerImage = o.durationPerImage;
+            if (o.delay !== undefined)
+                out.delay = o.delay;
             if (o.loopCount !== undefined)
                 out.loopCount = o.loopCount;
             if (o.videoFormat !== undefined)
@@ -519,12 +525,16 @@ export function wireMergeOptions(opts, mediaKind) {
         out.gap_duration = opts.gapDuration;
     // Video only.
     if (mediaKind === 'video') {
+        if (opts.reEncodeMode !== undefined)
+            out.re_encode_mode = opts.reEncodeMode;
         if (opts.codec !== undefined)
             out.codec = opts.codec;
         if (opts.crf !== undefined)
             out.crf = opts.crf;
         if (opts.preset !== undefined)
             out.preset = opts.preset;
+        if (opts.targetResolution !== undefined)
+            out.target_resolution = opts.targetResolution;
         if (opts.targetSize !== undefined) {
             out.target_size_bytes = typeof opts.targetSize === 'number'
                 ? opts.targetSize
@@ -540,6 +550,8 @@ export function wireMergeOptions(opts, mediaKind) {
             out.fps = opts.fps;
         if (opts.durationPerImage !== undefined)
             out.duration_per_image = opts.durationPerImage;
+        if (opts.delay !== undefined)
+            out.delay = opts.delay;
         if (opts.loopCount !== undefined)
             out.loop_count = opts.loopCount;
         if (opts.videoFormat !== undefined)

package/dist/retry-metadata.d.ts

@@ -0,0 +1,37 @@
+/**
+ * A rate-limit snapshot derived from the `x-ratelimit-*` response headers.
+ * `resetSeconds` is the server's seconds-to-reset value (`X-RateLimit-Reset`),
+ * NOT an absolute epoch — read {@link GislApiError.rateLimit} to obtain one.
+ */
+export interface RateLimitSnapshot {
+    readonly limit: number;
+    readonly remaining: number;
+    readonly resetSeconds: number;
+}
+/**
+ * Whether an HTTP status is retryable per the API-error taxonomy: request
+ * timeout (408), rate-limit (429), or any 5xx (500–599). BOUNDED at 599 — a
+ * non-standard 6xx-and-up status is NOT classified retryable.
+ *
+ * Now value-identical to the S3-PUT retry predicate (`isRetryableStatus`) in
+ * `client.ts` (both are `408 || 429 || 500-599` after qz7MjNTy), but kept
+ * DELIBERATELY SEPARATE: they guard different retry paths (S3-PUT chunk uploads
+ * vs the API-error taxonomy) and may diverge again, so they must NOT be merged.
+ */
+export declare function isApiRetryableStatus(status: number): boolean;
+export declare function parseRetryAfterMs(headerValue: string | undefined): number | undefined;
+/**
+ * The server-suggested back-off delay in WHOLE seconds, parsed from the
+ * `Retry-After` response header. Derived from {@link parseRetryAfterMs}
+ * (`Math.floor(ms / 1000)`) so the semantics mirror the retry-loop parser:
+ * absent / malformed / zero / past all collapse to `undefined`, as does a
+ * sub-second future HTTP-date (floors to zero → treated as absent).
+ */
+export declare function retryAfterSecondsFromHeaders(headers: Record<string, string> | undefined): number | undefined;
+/**
+ * A rate-limit snapshot parsed from the `x-ratelimit-*` response headers.
+ * Present ONLY when `x-ratelimit-limit`, `x-ratelimit-remaining`, and
+ * `x-ratelimit-reset` all parse as non-negative integers; otherwise
+ * `undefined` (a partial set is not a usable snapshot).
+ */
+export declare function rateLimitFromHeaders(headers: Record<string, string> | undefined): RateLimitSnapshot | undefined;