@giveitsmaller/sdk 0.15.0 → 0.17.0

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

@@ -4,35 +4,15 @@ export declare const OptimizeFor: {
     readonly Quality: "Quality";
 };
 export type OptimizeFor = typeof OptimizeFor[keyof typeof OptimizeFor];
-export declare const ImageMode: {
-    readonly Lossy: "lossy";
-    readonly Lossless: "lossless";
-    readonly Auto: "auto";
-};
-export type ImageMode = typeof ImageMode[keyof typeof ImageMode];
 export declare const ImageFormat: {
     readonly Original: "original";
-    readonly Auto: "auto";
-    readonly Smallest: "smallest";
-    readonly Jpeg: "jpeg";
-    readonly Png: "png";
     readonly Webp: "webp";
-    readonly Avif: "avif";
 };
 export type ImageFormat = typeof ImageFormat[keyof typeof ImageFormat];
 export declare const ImageMetadataPolicy: {
     readonly All: "all";
-    readonly None: "none";
-    readonly Copyright: "copyright";
-    readonly Sensitive: "sensitive";
 };
 export type ImageMetadataPolicy = typeof ImageMetadataPolicy[keyof typeof ImageMetadataPolicy];
-export declare const IccProfilePolicy: {
-    readonly Preserve: "preserve";
-    readonly Strip: "strip";
-    readonly Srgb: "srgb";
-};
-export type IccProfilePolicy = typeof IccProfilePolicy[keyof typeof IccProfilePolicy];
 export declare const VideoCodec: {
     readonly H264: "h264";
     readonly H265: "h265";
@@ -82,10 +62,10 @@ export declare const AudioSampleRate: {
 };
 export type AudioSampleRate = typeof AudioSampleRate[keyof typeof AudioSampleRate];
 export declare const PdfProfile: {
-    readonly Web: "web";
-    readonly Print: "print";
-    readonly Archive: "archive";
-    readonly Max: "max";
+    readonly Screen: "screen";
+    readonly Ebook: "ebook";
+    readonly Printer: "printer";
+    readonly Prepress: "prepress";
 };
 export type PdfProfile = typeof PdfProfile[keyof typeof PdfProfile];
 export declare const PdfColorspace: {
@@ -102,30 +82,12 @@ export declare const ERGONOMIC_ENUMS: {
         readonly Balanced: "Balanced";
         readonly Quality: "Quality";
     };
-    readonly ImageMode: {
-        readonly Lossy: "lossy";
-        readonly Lossless: "lossless";
-        readonly Auto: "auto";
-    };
     readonly ImageFormat: {
         readonly Original: "original";
-        readonly Auto: "auto";
-        readonly Smallest: "smallest";
-        readonly Jpeg: "jpeg";
-        readonly Png: "png";
         readonly Webp: "webp";
-        readonly Avif: "avif";
     };
     readonly ImageMetadataPolicy: {
         readonly All: "all";
-        readonly None: "none";
-        readonly Copyright: "copyright";
-        readonly Sensitive: "sensitive";
-    };
-    readonly IccProfilePolicy: {
-        readonly Preserve: "preserve";
-        readonly Strip: "strip";
-        readonly Srgb: "srgb";
     };
     readonly VideoCodec: {
         readonly H264: "h264";
@@ -170,10 +132,10 @@ export declare const ERGONOMIC_ENUMS: {
         readonly _48000: 48000;
     };
     readonly PdfProfile: {
-        readonly Web: "web";
-        readonly Print: "print";
-        readonly Archive: "archive";
-        readonly Max: "max";
+        readonly Screen: "screen";
+        readonly Ebook: "ebook";
+        readonly Printer: "printer";
+        readonly Prepress: "prepress";
     };
     readonly PdfColorspace: {
         readonly Unchanged: "unchanged";

package/dist/generated/sdk_spec/enums.js

@@ -7,38 +7,19 @@ export const OptimizeFor = {
     Balanced: "Balanced",
     Quality: "Quality",
 };
-// Image compression algorithm. lossy = smaller file; lossless = no quality loss; auto = format-best.
-export const ImageMode = {
-    Lossy: "lossy",
-    Lossless: "lossless",
-    Auto: "auto",
-};
-// Image output format selection. Original keeps input; Auto picks best per browser support; Smallest tries all and returns smallest.
+// Image output format for compress. Original keeps the input format; Webp recompresses to WebP. Other format changes (jpeg/png/avif/...) are the convert operation's job, not compress.
 export const ImageFormat = {
     Original: "original",
-    Auto: "auto",
-    Smallest: "smallest",
-    Jpeg: "jpeg",
-    Png: "png",
     Webp: "webp",
-    Avif: "avif",
 };
-// Image metadata handling. Counter-intuitive wire naming:
-//   All       = strip everything (smallest file)
-//   None      = keep all EXIF/IPTC/XMP
-//   Copyright = keep only copyright/author fields
-//   Sensitive = keep EXIF but strip GPS/location (GDPR-friendly)
+// Image metadata handling. Single value today (Option B, 2026-06-20):
+//   All = strip all EXIF/IPTC/XMP (smallest file)
+// The compress worker always strips metadata; None/Copyright/Sensitive were
+// removed — they never reached the worker (it hardcodes strip-everything), so
+// advertising metadata preservation was an over-claim. Preservation is a
+// possible future feature (would need worker support).
 export const ImageMetadataPolicy = {
     All: "all",
-    None: "none",
-    Copyright: "copyright",
-    Sensitive: "sensitive",
-};
-// ICC color profile handling.
-export const IccProfilePolicy = {
-    Preserve: "preserve",
-    Strip: "strip",
-    Srgb: "srgb",
 };
 // Video codec. H264 = widest compatibility; H265/Av1 = better compression but slower.
 export const VideoCodec = {
@@ -88,12 +69,12 @@ export const AudioSampleRate = {
     _44100: 44100,
     _48000: 48000,
 };
-// PDF optimization profile. Web = aggressive; Print = preserve quality; Archive = PDF/A; Max = smallest.
+// PDF Ghostscript preset. Screen = smallest; Ebook = mid; Printer = 300dpi; Prepress = print-production.
 export const PdfProfile = {
-    Web: "web",
-    Print: "print",
-    Archive: "archive",
-    Max: "max",
+    Screen: "screen",
+    Ebook: "ebook",
+    Printer: "printer",
+    Prepress: "prepress",
 };
 // PDF output color space.
 export const PdfColorspace = {
@@ -105,10 +86,8 @@ export const PdfColorspace = {
 /** Catalog of every ergonomic enum (canonicalName → wire). */
 export const ERGONOMIC_ENUMS = {
     OptimizeFor,
-    ImageMode,
     ImageFormat,
     ImageMetadataPolicy,
-    IccProfilePolicy,
     VideoCodec,
     VideoPreset,
     VideoFit,

package/dist/generated/sdk_spec/presets.js

@@ -4,26 +4,18 @@
 export const PRESETS = Object.freeze({
     "image_compress": Object.freeze({
         Size: Object.freeze({
-            "mode": "Lossy",
             "quality": 65,
             "metadata": "All",
-            "iccProfile": "Strip",
-            "progressive": true,
             "outputFormat": "Original",
         }),
         Balanced: Object.freeze({
-            "mode": "Auto",
             "quality": 80,
-            "metadata": "Sensitive",
-            "iccProfile": "Preserve",
-            "progressive": true,
+            "metadata": "All",
             "outputFormat": "Original",
         }),
         Quality: Object.freeze({
-            "mode": "Lossless",
-            "metadata": "None",
-            "iccProfile": "Preserve",
-            "progressive": true,
+            "quality": 92,
+            "metadata": "All",
             "outputFormat": "Original",
         }),
     }),
@@ -60,19 +52,16 @@ export const PRESETS = Object.freeze({
     }),
     "document_pdf_compress": Object.freeze({
         Size: Object.freeze({
-            "profile": "Max",
-            "colorspace": "Grayscale",
-            "flattenForms": false,
+            "profile": "Screen",
+            "grayscale": true,
         }),
         Balanced: Object.freeze({
-            "profile": "Web",
-            "colorspace": "Unchanged",
-            "flattenForms": false,
+            "profile": "Ebook",
+            "grayscale": false,
         }),
         Quality: Object.freeze({
-            "profile": "Archive",
-            "colorspace": "Unchanged",
-            "flattenForms": false,
+            "profile": "Printer",
+            "grayscale": false,
         }),
     }),
     "document_office_compress": Object.freeze({

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

@@ -1,3 +1,3 @@
-export declare const SDK_SPEC_VERSION: "1.7.0";
-export declare const PRESET_VERSION: "1.2";
-export declare const PRESET_CONFIG_HASH: "sha256:ef4d66a81920cec353633d788061a03f7c8891d622908c1bfca326679725e72b";
+export declare const SDK_SPEC_VERSION: "2.0.0";
+export declare const PRESET_VERSION: "1.4";
+export declare const PRESET_CONFIG_HASH: "sha256:62fbada24e33f983dacb0f717b0c9bb80824a208c3dc7f9af8523026e783543a";

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 = "1.7.0";
-export const PRESET_VERSION = "1.2";
-export const PRESET_CONFIG_HASH = "sha256:ef4d66a81920cec353633d788061a03f7c8891d622908c1bfca326679725e72b";
+export const SDK_SPEC_VERSION = "2.0.0";
+export const PRESET_VERSION = "1.4";
+export const PRESET_CONFIG_HASH = "sha256:62fbada24e33f983dacb0f717b0c9bb80824a208c3dc7f9af8523026e783543a";

package/dist/gisl.d.ts

@@ -19,7 +19,8 @@
 import { GislClient } from './client.js';
 import { GislConfigError, GislFeatureRequiresAuthError, GislMissingCredentialsError } from './errors.js';
 import { type ResolveCredentialsOptions, type ResolveEndpointOptions } from './credentials.js';
-import type { GislClientConfig } from './types.js';
+import type { CreditsUsageOptions, GislClientConfig } from './types.js';
+import type { AccountLimits, CreditsBalanceResponse, CreditsUsageResponse } 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';
@@ -128,6 +129,12 @@ export type ErgonomicClient = GislClient & {
      * over the existing transport.
      */
     withPresetDefaults(defaults: PresetDefaults): ErgonomicClient;
+    /** Current credit balance (sugar for `getCreditsBalance()`). */
+    credits(): Promise<CreditsBalanceResponse>;
+    /** Credit usage history (sugar for `getCreditsUsage()`). */
+    creditsUsage(options?: CreditsUsageOptions): Promise<CreditsUsageResponse>;
+    /** Effective account limits / tier-resolved caps (sugar for `getAccountLimits()`). */
+    limits(): Promise<AccountLimits>;
 };
 /**
  * The `gisl` namespace — primary ergonomic-layer entry point.

package/dist/gisl.js

@@ -166,6 +166,18 @@ function wrapErgonomic(client, presetDefaults, scopedPresetDefaults) {
                     return new MergeBuilder(target, declared, mergeOpts);
                 };
             }
+            // 8yqUXLCS — first-class ergonomic billing/limits accessors (thin fluent
+            // aliases over the low-level getters, surfaced + documented here rather
+            // than relying on undocumented Proxy passthrough).
+            if (prop === 'credits') {
+                return () => target.getCreditsBalance();
+            }
+            if (prop === 'creditsUsage') {
+                return (options) => target.getCreditsUsage(options);
+            }
+            if (prop === 'limits') {
+                return () => target.getAccountLimits();
+            }
             return Reflect.get(target, prop, receiver);
         },
     });

package/dist/handle.js

@@ -34,7 +34,7 @@
  */
 import { GislConfigError, GislNetworkError, GislResultNotReadyError, GislTimeoutError, SseEndedWithoutTerminal, } from './errors.js';
 import { _consumeSseToTerminal, _pollToTerminal, _parseMaxWait, } from './builder.js';
-import { projectDownloadsToRunResult, projectMultiJobToRunResult, isFanoutStatus, isMergeStatus, isArchiveStatus, } from './file-first.js';
+import { projectDownloadsToRunResult, projectMultiJobToRunResult, isFanoutStatus, isMergeStatus, isArchiveStatus, isWatermarkStatus, } from './file-first.js';
 import { LazyHttpDownloader } from './lazy-downloader.js';
 /**
  * The terminal workflow states. A status response in any of these states
@@ -237,6 +237,14 @@ export class Handle {
             const archiveDownloads = jobDownloads.filter((d) => d.ref === 'archive');
             return projectDownloadsToRunResult(this.workflowId, finalStatus, archiveDownloads, null, downloader);
         }
+        // A fluent `file(...).watermark(overlay)` — project ONLY the watermark
+        // output, filtering the `src_*` (base/overlay) passthrough plumbing. Matches
+        // WatermarkedRecipe.run()'s `ref === 'watermark'` filter so a
+        // submitted/reattached watermark handle never surfaces the raw inputs.
+        if (isWatermarkStatus(finalStatus)) {
+            const watermarkDownloads = jobDownloads.filter((d) => d.ref === 'watermark');
+            return projectDownloadsToRunResult(this.workflowId, finalStatus, watermarkDownloads, null, downloader);
+        }
         return projectDownloadsToRunResult(this.workflowId, finalStatus, jobDownloads, this.#key, downloader);
     }
     /**

package/dist/index.core.d.ts

@@ -3,7 +3,7 @@ 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 { 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, GislResultNotReadyError, } 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 { RunResult } from './file-first.js';
 export type { OutputFile, ItemResult, ItemFailure, Manifest, Downloader, } from './file-first.js';
@@ -13,23 +13,26 @@ export { FilesRecipe } from './file-first.js';
 export { MergedRecipe } from './file-first.js';
 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 { Handle, StatusSnapshot } from './handle.js';
 export { gisl, create } from './gisl.js';
 export type { GislCreateOptions, Environment, ErgonomicClient } 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, ImageMode, ImageMetadataPolicy, IccProfilePolicy, ImageFormat, VideoCodec, VideoPreset, VideoFit, AudioBitrate, AudioCodec, AudioSampleRate, PdfProfile, PdfColorspace, } from './ergonomic/presets/index.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';
 export type { Asset, ClipEntry, ClipOptions, MergeMediaKind, MergeOptions, SequenceEntry, } from './merge.js';
 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 { 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, 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, 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, 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, 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 type { OperationMetadata, AvailabilityValue, AvailabilityEntry, FeatureEntry, MimeGroupMetadata, OptionMetadata, ProcessingClassConstraints, } from '@giveitsmaller/contracts/operations';

package/dist/index.core.js

@@ -28,6 +28,8 @@ GislChainCardinalityMismatchError,
 GislBundleAlreadyArchivedError, 
 // FF1 / 3BIxEnfR — file-first result sink errors.
 GislNoSuchKeyError, GislSinkError, 
+// AjhOUuqQ — typed terminal item failure stored in RunResult.failed[].error.
+GislItemFailedError, 
 // FF5a / Ao8RPVxD — thrown by the file-first Handle.result() when the
 // workflow is not yet terminal (the non-blocking accessor).
 GislResultNotReadyError, } from './errors.js';
@@ -48,6 +50,11 @@ export { MergedRecipe } from './file-first.js';
 // File-first N→1 bundle (FF3b) — `client.files([...]).archive(opts?)` returns a
 // terminal ArchivedRecipe (zip / tar.gz; no post-bundle chain), then run()/submit().
 export { ArchivedRecipe } from './file-first.js';
+// File-first multi-input watermark (FF4a / Z7zTr789) — `client.file(base)
+// .watermark(overlay, opts)` returns a single-output WatermarkedRecipe you chain
+// 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';
 // `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
@@ -65,7 +72,7 @@ export { gisl, create } from './gisl.js';
 // Ergonomic preset defaults (T4a / VhIj4S7T) — typed leaf DTOs + immutable
 // `PresetDefaults` builder + `presetDefaults()` factory + ergonomic enum
 // re-exports. Resolver wiring (T4b) consumes `PresetDefaults.cellFor()`.
-export { presetDefaults, PresetDefaults, ImageCompressPresetOptions, AudioCompressPresetOptions, VideoCompressPresetOptions, DocumentPdfCompressPresetOptions, DocumentOfficeCompressPresetOptions, DocumentOdfCompressPresetOptions, DocumentEpubCompressPresetOptions, OptimizeFor, ImageMode, ImageMetadataPolicy, IccProfilePolicy, ImageFormat, VideoCodec, VideoPreset, VideoFit, AudioBitrate, AudioCodec, AudioSampleRate, PdfProfile, PdfColorspace, } from './ergonomic/presets/index.js';
+export { presetDefaults, PresetDefaults, ImageCompressPresetOptions, AudioCompressPresetOptions, VideoCompressPresetOptions, DocumentPdfCompressPresetOptions, DocumentOfficeCompressPresetOptions, DocumentOdfCompressPresetOptions, DocumentEpubCompressPresetOptions, OptimizeFor, ImageMetadataPolicy, ImageFormat, VideoCodec, VideoPreset, VideoFit, AudioBitrate, AudioCodec, AudioSampleRate, PdfProfile, PdfColorspace, } from './ergonomic/presets/index.js';
 // Operation-builder surface (T2 / xVDTIm8C) — `client.compress/convert/thumbnail`
 // returns an `OperationBuilder`; `.run()` projects to a flat `Result` /
 // `.submit({webhook})` returns a `Handle`. Progress events are the

package/dist/types.d.ts

@@ -279,6 +279,20 @@ export interface PreflightClipError {
     fileId: string;
     error: unknown;
 }
+/**
+ * Read-time options for a single anonymous-readable workflow query.
+ *
+ * Carries the one-time capability token returned by an anonymous (null-owner)
+ * workflow create (`WorkflowCreateResponse.cap`). Pass it on status / downloads
+ * / events reads so a session-less caller can read its own workflow; the SDK
+ * sends it as the `X-Workflow-Capability` header. Omit it for authenticated
+ * reads — the session authorizes those. A wrong or missing token on a
+ * null-owner workflow returns 404 (deliberately no existence oracle).
+ */
+export interface ReadCapabilityOptions {
+    /** Anonymous-workflow capability token (the `cap` from workflow-create). */
+    capability?: string;
+}
 export interface WaitOptions {
     /** Poll interval in milliseconds (default: 2000) */
     intervalMs?: number;
@@ -286,6 +300,13 @@ export interface WaitOptions {
     timeoutMs?: number;
     /** Called after each poll with current status */
     onPoll?: (status: string) => void;
+    /**
+     * Anonymous-workflow capability token (the `cap` from workflow-create),
+     * forwarded to each underlying status poll as the `X-Workflow-Capability`
+     * header. Required to poll a null-owner workflow without a session; omit
+     * for authenticated polling.
+     */
+    capability?: string;
 }
 export interface ProbeWaitOptions {
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@giveitsmaller/sdk",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "Node.js SDK for the GISL (Give It Smaller) file compression and processing API",
   "license": "MIT",
   "type": "module",
@@ -31,12 +31,12 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@giveitsmaller/contracts": "^0.19.0"
+    "@giveitsmaller/contracts": "^0.34.0"
   },
   "devDependencies": {
     "@types/node": "^22",
     "esbuild": "^0.27",
-    "typescript": "^5.7",
+    "typescript": "5.9.3",
     "vitest": "^3.1 <3.2.5",
     "yaml": "^2.6"
   },