@giveitsmaller/sdk 0.19.0 → 0.20.0

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;

package/dist/retry-metadata.js

@@ -0,0 +1,86 @@
+// Shared HTTP retry-metadata helpers. Extracted here so `errors.ts` can consume
+// them WITHOUT importing `client.ts`: `client.ts` already imports `errors.ts`, so
+// pulling the module-private `parseRetryAfterMs` back out of `client.ts` would
+// form a `client → errors → client` circular import. The millisecond parser is
+// MOVED here verbatim; `client.ts` re-imports it so the retry-loop timing stays
+// byte-identical.
+/**
+ * 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 function isApiRetryableStatus(status) {
+    return status === 408 || status === 429 || (status >= 500 && status <= 599);
+}
+// 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.
+export 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;
+}
+/**
+ * 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 function retryAfterSecondsFromHeaders(headers) {
+    const ms = parseRetryAfterMs(headers?.['retry-after']);
+    if (ms === undefined)
+        return undefined;
+    const seconds = Math.floor(ms / 1000);
+    return seconds > 0 ? seconds : undefined;
+}
+// Parse a non-negative integer response header. Returns `undefined` for an
+// absent value or anything that isn't a bare run of decimal digits (so a
+// float, sign, or units suffix is rejected rather than silently truncated).
+function parseIntHeader(headerValue) {
+    if (headerValue === undefined)
+        return undefined;
+    const trimmed = headerValue.trim();
+    if (!/^\d+$/.test(trimmed))
+        return undefined;
+    return Number(trimmed);
+}
+/**
+ * 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 function rateLimitFromHeaders(headers) {
+    if (headers === undefined)
+        return undefined;
+    const limit = parseIntHeader(headers['x-ratelimit-limit']);
+    const remaining = parseIntHeader(headers['x-ratelimit-remaining']);
+    const resetSeconds = parseIntHeader(headers['x-ratelimit-reset']);
+    if (limit === undefined || remaining === undefined || resetSeconds === undefined) {
+        return undefined;
+    }
+    return { limit, remaining, resetSeconds };
+}

package/dist/sse.d.ts

@@ -1,4 +1,4 @@
-import type { GislSseEvent } from './types.js';
+import type { GislSseEvent, GislSseParseFailure } from './types.js';
 /**
  * Parse an SSE stream from a fetch Response into an AsyncIterable of typed events.
  *
@@ -27,4 +27,5 @@ import type { GislSseEvent } from './types.js';
  */
 export declare function parseSseStream(response: Response, opts?: {
     signal?: AbortSignal;
+    onParseError?: (diagnostic: GislSseParseFailure) => void;
 }): AsyncGenerator<GislSseEvent>;

package/dist/sse.js

@@ -76,15 +76,27 @@ export async function* parseSseStream(response, opts = {}) {
                     // Empty line = end of event
                     if (dataLines.length > 0) {
                         const rawData = dataLines.join('\n');
+                        const frameEvent = eventType || 'message';
                         let parsed;
                         try {
                             parsed = JSON.parse(rawData);
                         }
-                        catch {
-                            parsed = rawData;
+                        catch (err) {
+                            // TYNjcjpo — a malformed-JSON frame is SKIPPED (not yielded as a
+                            // raw string) so the stream stays resilient, but the failure is
+                            // surfaced via the optional onParseError diagnostic rather than
+                            // silently lost. Identical to the PHP `flushSseFrame` drop-path.
+                            opts.onParseError?.({
+                                raw: rawData,
+                                event: frameEvent,
+                                error: err instanceof Error ? err.message : String(err),
+                            });
+                            eventType = '';
+                            dataLines = [];
+                            continue;
                         }
                         yield {
-                            event: eventType || 'message',
+                            event: frameEvent,
                             data: parsed,
                         };
                     }
@@ -124,15 +136,23 @@ export async function* parseSseStream(response, opts = {}) {
         // not be yielded once the consumer has abandoned the stream.
         if (!aborted && dataLines.length > 0) {
             const rawData = dataLines.join('\n');
+            const frameEvent = eventType || 'message';
             let parsed;
             try {
                 parsed = JSON.parse(rawData);
             }
-            catch {
-                parsed = rawData;
+            catch (err) {
+                // TYNjcjpo — trailing-flush malformed frame: skip + diagnostic (same as
+                // the in-loop path above).
+                opts.onParseError?.({
+                    raw: rawData,
+                    event: frameEvent,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                return;
             }
             yield {
-                event: eventType || 'message',
+                event: frameEvent,
                 data: parsed,
             };
         }

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import type { OperationType, OperationsSchemaResponse, CallbackEventType, SseEventType, SseOperationProgressData, SseOperationCompletedData, SseOperationFailedData, SseJobCompletedData, SseJobFailedData, SseWorkflowTerminalData, MultipartInitiateRequestMetadataHint, UploadProbeResponse } from '@giveitsmaller/contracts/openapi';
+import type { OperationType, OperationsSchemaResponse, OperationCapability, OutputProperties, ImageEncodeCapabilities, CallbackEventType, SseEventType, SseOperationProgressData, SseOperationCompletedData, SseOperationFailedData, SseJobCompletedData, SseJobFailedData, SseWorkflowTerminalData, MultipartInitiateRequestMetadataHint, UploadProbeResponse } from '@giveitsmaller/contracts/openapi';
 import type { JobInputV2RoleEnum } from '@giveitsmaller/contracts/openapi';
 export interface GislClientConfig {
     baseUrl: string;
@@ -227,6 +227,32 @@ export type GetSchemaResult = {
     etag?: string;
     lastModified?: string;
 };
+/**
+ * Typed projection of the operation-capability surface returned by
+ * {@link ErgonomicClient.capabilities} (qUhxfDA5). Bundles the three v2.124
+ * capability fields of `OperationsSchemaResponse` — previously typed but with
+ * no ergonomic consumer — so a caller can read them without dropping to
+ * `getSchema()` and its not-modified union.
+ *
+ * Mirrors the PHP `Gisl\Sdk\Ergonomic\CapabilitiesSnapshot` value object.
+ */
+export interface CapabilitiesSnapshot {
+    /**
+     * Tier-scoped operation-capability matrix, keyed by operation type
+     * (`compress`, `convert`, …). Empty when the server omits the field.
+     */
+    readonly operations: Record<string, OperationCapability>;
+    /**
+     * Output-format property table (`hasAudioTrack` / `isAnimated`), keyed by
+     * `output_format`. Tier-invariant. Empty when the server omits the field.
+     */
+    readonly outputProperties: Record<string, OutputProperties>;
+    /**
+     * Pre-flight image-encode capability matrix (`webpQualitySupported`,
+     * `backgroundFlatten`). Tier-invariant. `undefined` when the server omits it.
+     */
+    readonly imageEncode?: ImageEncodeCapabilities;
+}
 export interface CreditsUsageOptions {
     /**
      * Page size. Server defaults to 20 and rejects values outside `[1, 100]`
@@ -373,6 +399,22 @@ export type GislSseEvent = {
     event: string;
     data: unknown;
 };
+/**
+ * A typed, non-throwing diagnostic surfaced when an SSE frame's `data:` body fails
+ * to JSON-parse (TYNjcjpo). The malformed frame is SKIPPED from the event stream —
+ * a long-running consumer must not break on one garbled server frame — but the
+ * failure is observable via the `onParseError` callback on `streamEvents` /
+ * `parseSseStream` rather than silently lost. Mirrors the PHP `GislSseParseFailure`
+ * value object; the shape is identical across the two SDKs (cross-SDK parity).
+ */
+export interface GislSseParseFailure {
+    /** The joined `data:` line(s) that failed to parse. */
+    readonly raw: string;
+    /** The frame's event type (or `'message'` when the frame had no `event:` field). */
+    readonly event: string;
+    /** The parse error message (e.g. the `JSON.parse` `SyntaxError` text). */
+    readonly error: string;
+}
 export interface UploadOptions {
     /** Called with bytes uploaded so far (only for multipart) */
     onProgress?: (uploadedBytes: number, totalBytes: number) => void;