@giveitsmaller/sdk 0.6.0 → 0.8.0

package/dist/index.d.ts

@@ -3,15 +3,30 @@ export { verifyWebhook } from './webhook.js';
 export { parseSseStream } from './sse.js';
 export type { CreditsUsageOptions, GetSchemaOptions, GetSchemaResult, PreflightClipError, PreflightClipsResult, GislClientConfig, GislSseEvent, UploadOptions, WaitOptions, WorkflowCreatePayload, OperationDef, WorkflowSourcePayload, 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 { GislError, GislApiError, GislValidationError, GislBalanceExhaustedError, GislTierRestrictedError, GislFeatureTierRestrictedError, GislFeatureNotAvailableError, GislWorkflowExpiredError, GislAuthError, GislUploadCapExceededError, GislMultipartPartError, GislMultipartPartCountError, GislMultipartSessionNotFoundError, GislMultipartSessionOwnershipError, GislMultipartSessionAuthRequiredError, GislTimeoutError, GislAbortError, } from './errors.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, GislNoSuchKeyError, GislSinkError, } from './errors.js';
 export type { GislApiErrorOptions, GislUploadCapKind } from './errors.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, WorkflowDownloadResponse, MetadataResponse, MetadataResponseDimensions, MetadataResponseExif, MetadataResponseExifGps, OperationsSchemaResponse, OperationSchemaDefinition, MimeGroupSchema, OptionSchema, PerValueAvailabilityEntry, 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, AuthErrorResponse, } from '@giveitsmaller/contracts/openapi';
+export { RunResult } from './file-first.js';
+export type { OutputFile, ItemResult, ItemFailure, Manifest, Downloader, } from './file-first.js';
+export { Recipe, fileInput } from './file-first.js';
+export type { FileInput } from './file-first.js';
+export { HttpDownloader } from './http-downloader.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, ImageFit, ImageMetadataPolicy, IccProfilePolicy, 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, Handle, 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, 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 { 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, ImageWatermarkVideoOptions, TextWatermarkImageOptions, CustomLumaVideoOptions, AudioOverlayAudioOptions, AudioOverlayVideoOptions, AudioWatermarkAudioOptions, AudioWatermarkVideoOptions, } from '@giveitsmaller/contracts/operations';
-export { ImageWatermarkImageAnchor, ImageWatermarkImageGifAnchor, ImageWatermarkVideoAnchor, TextWatermarkImageAnchor, TextWatermarkImageFontFamily, TextWatermarkImageWatermarkMode, AudioOverlayAudioMode, AudioOverlayVideoMode, AudioOverlayVideoNoAudioTrackBehaviour, AudioWatermarkAudioMethod, AudioWatermarkAudioRobustness, AudioWatermarkAudioDensity, AudioWatermarkVideoMethod, AudioWatermarkVideoRobustness, AudioWatermarkVideoDensity, } from '@giveitsmaller/contracts/operations';
-export { archiveMetadata, audioOverlayMetadata, audioWatermarkMetadata, compressMetadata, convertMetadata, customLumaMetadata, imageWatermarkMetadata, mergeMetadata, textWatermarkMetadata, thumbnailMetadata, } from '@giveitsmaller/contracts/operations';
+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 { 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 { OperationMetadata, AvailabilityValue, AvailabilityEntry, FeatureEntry, MimeGroupMetadata, OptionMetadata, ProcessingClassConstraints, } from '@giveitsmaller/contracts/operations';

package/dist/index.js

@@ -4,9 +4,46 @@ export { verifyWebhook } from './webhook.js';
 export { parseSseStream } from './sse.js';
 export { uploadSource, jobOutputSource, externalImportSource, connectionSource, } from './types.js';
 // Errors
-export { GislError, GislApiError, GislValidationError, GislBalanceExhaustedError, GislTierRestrictedError, GislFeatureTierRestrictedError, GislFeatureNotAvailableError, GislWorkflowExpiredError, GislAuthError, GislUploadCapExceededError, GislMultipartPartError, GislMultipartPartCountError, 
+export { GislError, GislApiError, GislValidationError, GislBalanceExhaustedError, GislTierRestrictedError, GislFeatureTierRestrictedError, GislFeatureNotAvailableError, GislWorkflowExpiredError, GislProbePendingError, GislAuthError, GislUploadCapExceededError, GislMultipartPartError, GislMultipartPartCountError, 
 // SDK-3 (Wb6ebOMM) — typed errors for the 3 resume-support endpoints.
-GislMultipartSessionNotFoundError, GislMultipartSessionOwnershipError, GislMultipartSessionAuthRequiredError, GislTimeoutError, GislAbortError, } from './errors.js';
+GislMultipartSessionNotFoundError, GislMultipartSessionOwnershipError, GislMultipartSessionAuthRequiredError, GislTimeoutError, GislAbortError, 
+// FF2b / tywwynmN — transport-level failure (mirrors PHP GislNetworkError);
+// raised by the file-first HttpDownloader when an output URL cannot be read.
+GislNetworkError, 
+// T1 / wVU4xHx3 — local config-error tree (pre-I/O; sibling of GislApiError).
+GislConfigError, GislMissingCredentialsError, GislFeatureRequiresAuthError, 
+// T3 / cuecCmb5 — merge-compose local validation errors.
+GislUndeclaredAssetError, GislUnusedAssetError, GislPerInputOptionsNotSupportedError, 
+// T6 / aDR1jnyZ — chain-cardinality validation (dormant until chain
+// methods on OperationBuilder ship; type + audit registration land
+// here so the future chain-method PR is a pure addition).
+GislChainCardinalityMismatchError, 
+// FF1 / 3BIxEnfR — file-first result sink errors.
+GislNoSuchKeyError, GislSinkError, } from './errors.js';
+// File-first result surface (FF1 / 3BIxEnfR) — coexists with the
+// operation-first `Result`/`Artifact` until FF6 removes the old layer.
+export { RunResult } from './file-first.js';
+// File-first builder (FF2a / MfV0PDok) — `client.file(path).op()...` lowering.
+export { Recipe, fileInput } from './file-first.js';
+// File-first execution (FF2b / MfV0PDok) — Node streaming downloader bound by
+// `Recipe.run()` to write pre-signed output URLs to disk.
+export { HttpDownloader } from './http-downloader.js';
+// Ergonomic-layer entrypoint (T1 / wVU4xHx3) — `gisl.create()` factory +
+// credential-chain types. `gisl.anonymous()` (public export) lands once
+// the anonymous-capable operation allowlist is non-empty (plan §12).
+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, ImageFit, ImageMetadataPolicy, IccProfilePolicy, 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
+// SDK-synthesised `{phase:'upload'|'processing', ...}` discriminated union.
+export { OperationBuilder, MapEachBuilder } from './builder.js';
+export { MergeBuilder, asset, handle, clip } from './merge.js';
+// T4b — preset resolver public surface (PRESET_VERSION constant + types).
+export { PRESET_VERSION, resolveCompressOptions } from './ergonomic/preset_resolver.js';
 export { AudioWatermarkDecodeRequestMethodHintEnum, AudioWatermarkDecodeResponseMethodEnum, 
 // OperationInputModel — value-bearing enum (`single` | `multi`).
 // Surfaced on OperationSchemaDefinition.inputModel so form-renderers
@@ -25,10 +62,14 @@ AuthErrorType, TierRestrictionKind, BalanceExhaustedResponseRequiredActionEnum,
 // aliases (no runtime value); the openapi versions carry both the
 // string-union type and a const map. Per audit follow-up.
 UserTier, ProcessingClass, } from '@giveitsmaller/contracts/openapi';
-export { ImageWatermarkImageAnchor, ImageWatermarkImageGifAnchor, ImageWatermarkVideoAnchor, TextWatermarkImageAnchor, TextWatermarkImageFontFamily, TextWatermarkImageWatermarkMode, AudioOverlayAudioMode, AudioOverlayVideoMode, AudioOverlayVideoNoAudioTrackBehaviour, AudioWatermarkAudioMethod, AudioWatermarkAudioRobustness, AudioWatermarkAudioDensity, AudioWatermarkVideoMethod, AudioWatermarkVideoRobustness, AudioWatermarkVideoDensity, } from '@giveitsmaller/contracts/operations';
+export { ImageWatermarkImageAnchor, ImageWatermarkImageGifAnchor, TextWatermarkImageAnchor, TextWatermarkImageFontFamily, TextWatermarkImageWatermarkMode, AudioOverlayAudioMode, AudioOverlayVideoMode, AudioOverlayVideoNoAudioTrackBehaviour, AudioWatermarkAudioMethod, AudioWatermarkAudioRobustness, AudioWatermarkAudioDensity, AudioWatermarkVideoMethod, AudioWatermarkVideoRobustness, AudioWatermarkVideoDensity, 
+// New planned operation enums — contracts v2.15 (AJCLLGaG).
+AudioToVideoAudioOutputResolution, AudioToVideoAudioImageFit, AudioToVideoAudioOutputFormat, VideoWatermarkVideoAnchor, VideoTextWatermarkVideoFontFamily, VideoTextWatermarkVideoWatermarkMode, VideoTextWatermarkVideoAnchor, SplitImageGifOutputFormat, SplitDocumentPdfMode, SplitAudioMode, SplitAudioPrecision, SplitVideoMode, SplitVideoPrecision, } from '@giveitsmaller/contracts/operations';
 // Per-operation metadata sidecars. Inspect `availability`,
 // `required_tier`, per-value gating, mime-group availability and
 // per-feature flags before submitting a workflow — the API will
 // otherwise reject planned ops with `feature_not_available` (422,
 // surfaces as `GislFeatureNotAvailableError`).
-export { archiveMetadata, audioOverlayMetadata, audioWatermarkMetadata, compressMetadata, convertMetadata, customLumaMetadata, imageWatermarkMetadata, mergeMetadata, textWatermarkMetadata, thumbnailMetadata, } from '@giveitsmaller/contracts/operations';
+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';

package/dist/merge.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Merge-compose layer for the SDK ergonomic surface (T3 / cuecCmb5).
+ *
+ * `client.merge(...assets, options?)` returns a `MergeBuilder`. The builder
+ * separates WHAT (the asset set) from ORDER (the timeline):
+ *
+ * - `merge(a, b, c)` declares the asset set — each unique input is uploaded
+ *   ONCE per run, even if referenced multiple times in the sequence.
+ * - `.sequence(...refs)` defines the play order. References may repeat
+ *   freely; entries may be bare asset refs or `clip(ref, opts)` objects
+ *   carrying per-position options.
+ * - No `.sequence(...)` => play in declared order, no transitions.
+ *
+ * Wire-truth boundaries (lowering.md §sequences):
+ * - Video merge per-input options: `transition`, `crossfadeDuration` only.
+ * - Audio merge per-input options: `transition`, `crossfadeDuration`,
+ *   `gapDuration` only.
+ * - Image merge has NO per-input options today — `clip(ref)` is reuse/order
+ *   only. Per-position transitions on image merges throw locally as
+ *   `GislPerInputOptionsNotSupportedError`.
+ * - No per-clip `trimStart`/`trimEnd` today (contracts ticket iZzn5QrS
+ *   tracks the fix). Workaround: pre-trim each clip via a chained
+ *   `compress(file, trimStart, trimEnd)`.
+ *
+ * Local validation runs BEFORE any upload — undeclared refs and unused
+ * assets both fail fast so the caller saves bandwidth on typo'd composes.
+ */
+import type { GislClient } from './client.js';
+import { type Handle, type Result, type RunOptions, type SubmitOptions } from './builder.js';
+/**
+ * A declared merge asset. `path` carries a string or Blob (deduped by
+ * normalised source key); `handle` wraps an already-uploaded file (deduped
+ * by handle identity — same handle reference = same upload regardless of
+ * path). Use a handle for guaranteed reuse.
+ */
+export type Asset = {
+    readonly type: 'path';
+    readonly path: string | Blob;
+} | {
+    readonly type: 'handle';
+    readonly fileId: string;
+};
+/**
+ * Construct a path-asset. Bare-string arguments to `merge(...)` are
+ * implicitly wrapped via this helper.
+ */
+export declare function asset(path: string | Blob): Asset;
+/**
+ * Wrap an already-uploaded file_id as a merge asset. Use this when the
+ * SAME logical file should be referenced from multiple merge runs with
+ * guaranteed-single-upload semantics.
+ */
+export declare function handle(fileId: string): Asset;
+/**
+ * Per-position options carried by `clip(ref, opts)` entries. Image merges
+ * reject ANY per-input options today (see module docstring).
+ */
+export interface ClipOptions {
+    /** Transition to apply at this position (video/audio per-input only). */
+    readonly transition?: string;
+    /** Crossfade duration in seconds (when `transition` is crossfade). */
+    readonly crossfadeDuration?: number;
+    /** Gap duration in seconds (audio merge only). */
+    readonly gapDuration?: number;
+}
+/**
+ * A sequence entry that carries per-position options. Use the `clip(...)`
+ * helper to construct.
+ */
+export interface ClipEntry {
+    readonly type: 'clip';
+    readonly asset: Asset;
+    readonly options: ClipOptions;
+}
+/**
+ * Construct a clip entry for `.sequence(...)`. The asset MUST already
+ * be in the merge's declared asset set.
+ */
+export declare function clip(ref: Asset, options?: ClipOptions): ClipEntry;
+export type SequenceEntry = Asset | ClipEntry;
+/**
+ * Inferred media kind. `merge` picks the wire variant from the inferred
+ * media; the SDK reads the FIRST asset's path/MIME to decide.
+ */
+export type MergeMediaKind = 'video' | 'audio' | 'image';
+export interface MergeOptions {
+    /** Merge-level transition (applies to every join — image merge ONLY uses this). */
+    readonly transition?: string;
+    readonly crossfadeDuration?: number;
+    readonly gapDuration?: number;
+    readonly normalizeAudio?: boolean;
+    readonly codec?: string;
+    readonly crf?: number;
+    readonly preset?: string;
+    readonly targetSize?: string | number;
+    readonly transitionDuration?: number;
+    readonly fps?: number;
+    readonly durationPerImage?: number;
+    readonly loopCount?: number;
+    readonly output?: string;
+    readonly videoFormat?: string;
+    readonly outputType?: string;
+    /** Force the inferred media kind (skip the first-asset sniff). */
+    readonly mediaKind?: MergeMediaKind;
+    /** Bypass the unused-asset validation (rarely needed; usually a bug indicator). */
+    readonly allowUnusedAssets?: boolean;
+}
+/**
+ * Captures the (declared assets, options) for a merge. `.sequence(...)`
+ * pins the play order; without it, the declared order is used as-is
+ * with no per-input options.
+ *
+ * Local validation runs at `.run()`/`.submit()` time (BEFORE any upload)
+ * and throws one of `GislUndeclaredAssetError`, `GislUnusedAssetError`,
+ * or `GislPerInputOptionsNotSupportedError` if the compose is invalid.
+ */
+export declare class MergeBuilder {
+    private readonly client;
+    private readonly assets;
+    private readonly opOptions;
+    private sequenceEntries;
+    constructor(client: GislClient, assets: readonly Asset[], opOptions: MergeOptions);
+    /**
+     * Pin the merge play order. Each entry must reference an asset that
+     * was declared in the parent `merge(...)` call. Repeats are allowed
+     * and deduped on upload (one upload per unique declared asset).
+     */
+    sequence(...entries: SequenceEntry[]): this;
+    run(options: RunOptions): Promise<Result>;
+    submit(options: SubmitOptions): Promise<Handle>;
+    /**
+     * Resolve the declared assets + sequence (or fall back to declared order),
+     * dedupe by identity, and run the local validators. The returned plan
+     * carries the SEQUENCE (positional entries) + the UNIQUE assets to upload.
+     */
+    private planSequence;
+    private inferMediaKind;
+    private uploadUniqueAssets;
+    private buildPayload;
+    private opOptionsForResolved;
+    private awaitTerminal;
+}