@giveitsmaller/sdk 0.6.0 → 0.7.0

package/dist/gisl.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Ergonomic-layer entrypoint for the GISL SDK. Wraps the low-level
+ * `GislClient` (transport, multipart, SSE, downloads) with credential-chain
+ * resolution + ergonomic factory functions. Designed to feel native to a
+ * developer writing `import { gisl } from '@giveitsmaller/sdk'` and then
+ * `const client = await gisl.create();`.
+ *
+ * Scope of this card (T1, `wVU4xHx3`):
+ * - `gisl.create()` — full functionality. Resolves credentials + endpoint
+ *   via `credentials.ts`, fails early with `GislMissingCredentialsError`
+ *   when no apiKey is found AND the caller hasn't opted into cookie-mode
+ *   or anonymous mode.
+ * - INTERNAL `_gislAnonymous` capability + `ANONYMOUS_ALLOWLIST` constant
+ *   are wired but NOT publicly exported until the free-tier launch decides
+ *   which operations are anonymous-capable (plan §12 open decision). A
+ *   non-empty allowlist + the named export will arrive in a follow-up PR
+ *   the moment user picks; this card avoids shipping a dead `gisl.anonymous()`.
+ */
+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 { OperationBuilder } from './builder.js';
+import { MergeBuilder, type Asset, type MergeOptions } from './merge.js';
+import { PresetDefaults } from './ergonomic/presets/index.js';
+/**
+ * Operations that may be invoked on a `gisl.anonymous()` client without
+ * raising `GislFeatureRequiresAuthError`. Empty until the free-tier launch
+ * decision lands (plan §12). Typed as a `readonly []` tuple (NOT
+ * `readonly string[]`) so the audit-gate compile-time assertion in
+ * `_audit.ts` fires if a future PR widens this without flipping the
+ * parking-decision + adding the public `gisl.anonymous()` export.
+ *
+ * Consumers must not depend on its emptiness today — only `package.json`
+ * `exports` keeps deep-imports blocked; the marker is internal.
+ *
+ * @internal
+ */
+export declare const ANONYMOUS_ALLOWLIST: readonly [];
+export interface GislCreateOptions extends ResolveCredentialsOptions, ResolveEndpointOptions, Omit<GislClientConfig, 'baseUrl' | 'apiKey' | 'useSessionCookie'> {
+    /**
+     * Layered ergonomic preset defaults (T4a / VhIj4S7T). Built via
+     * `presetDefaults().<cell>(level, overrides?)…`. The resolver wiring
+     * that consumes this slot lands in T4b — until then, supplying this
+     * field is a no-op at workflow-create time.
+     */
+    readonly presetDefaults?: PresetDefaults;
+}
+/**
+ * Construct an ergonomic-layer client. Resolves the API key + base URL via
+ * the credential chain (see `credentials.ts`) and constructs a low-level
+ * `GislClient`. Throws `GislMissingCredentialsError` synchronously before
+ * any HTTP I/O when no key is found AND neither `useSessionCookie` nor
+ * `allowAnonymous` is set.
+ *
+ * Cookie-mode (`useSessionCookie: true`) explicitly bypasses the missing-
+ * credentials check — browser SPAs that drive auth via `client.login()`
+ * legitimately have no apiKey at construction time.
+ */
+export declare function create(opts?: GislCreateOptions): Promise<ErgonomicClient>;
+/**
+ * The ergonomic-client surface: `GislClient` (verbatim low-level API)
+ * plus three ergonomic op-builder factories. Intersection type — at
+ * runtime the Proxy synthesises the three methods on-demand. `input`
+ * accepts `string | Blob` matching `GislClient.uploadFile` (codex r1
+ * low 89cae59f4f04 — Blob/File uploads were previously rejected by the
+ * ergonomic factory's narrower string-only typing).
+ */
+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;
+    /**
+     * Merge ordered-sequence factory (T3). Accepts a variadic list of assets
+     * (strings/Blobs/`handle()`/`asset()`) optionally terminated by a
+     * `MergeOptions` object. Returns a `MergeBuilder`; pin the play order
+     * with `.sequence(...)`.
+     */
+    merge(...args: ReadonlyArray<string | Blob | Asset | MergeOptions>): MergeBuilder;
+    /**
+     * Immutable scoped derive (T4c — `ULAlOP6j`). Returns a new client
+     * with `defaults` layered on top of the parent's scoped defaults.
+     * Use for the "next N jobs" pattern — e.g. an evening batch needing
+     * higher quality without mutating the long-lived parent client.
+     *
+     * Identity: the derived client shares the SAME underlying low-level
+     * transport (baseUrl, apiKey, headers, timeouts, multipart, session
+     * cookie) by reference. Safe for concurrent parent + derived use.
+     *
+     * Merge semantics (codex r2 #5 — scalar leaf): scoped per-cell fields
+     * override the parent's scoped where defined; the parent's
+     * `client.presetDefaults` layer is unaffected and still contributes
+     * fields the scoped layer doesn't set.
+     *
+     * Does NOT re-resolve credentials. The derive never calls the
+     * credential chain or constructor — it composes new closure values
+     * over the existing transport.
+     */
+    withPresetDefaults(defaults: PresetDefaults): ErgonomicClient;
+};
+/**
+ * The `gisl` namespace — primary ergonomic-layer entry point.
+ * Exports `gisl.create()` only for v0.7; `gisl.anonymous()` lands once
+ * the anonymous-capable operation allowlist is non-empty (plan §12).
+ */
+export declare const gisl: {
+    readonly create: typeof create;
+};
+export type { Environment } from './credentials.js';
+/** @internal */
+export declare function _internalAnonymous(opts?: GislCreateOptions): Promise<GislClient>;
+export { GislConfigError, GislMissingCredentialsError, GislFeatureRequiresAuthError };

package/dist/gisl.js

@@ -0,0 +1,266 @@
+/**
+ * Ergonomic-layer entrypoint for the GISL SDK. Wraps the low-level
+ * `GislClient` (transport, multipart, SSE, downloads) with credential-chain
+ * resolution + ergonomic factory functions. Designed to feel native to a
+ * developer writing `import { gisl } from '@giveitsmaller/sdk'` and then
+ * `const client = await gisl.create();`.
+ *
+ * Scope of this card (T1, `wVU4xHx3`):
+ * - `gisl.create()` — full functionality. Resolves credentials + endpoint
+ *   via `credentials.ts`, fails early with `GislMissingCredentialsError`
+ *   when no apiKey is found AND the caller hasn't opted into cookie-mode
+ *   or anonymous mode.
+ * - INTERNAL `_gislAnonymous` capability + `ANONYMOUS_ALLOWLIST` constant
+ *   are wired but NOT publicly exported until the free-tier launch decides
+ *   which operations are anonymous-capable (plan §12 open decision). A
+ *   non-empty allowlist + the named export will arrive in a follow-up PR
+ *   the moment user picks; this card avoids shipping a dead `gisl.anonymous()`.
+ */
+import { GislClient } from './client.js';
+import { GislConfigError, GislFeatureRequiresAuthError, GislMissingCredentialsError, } from './errors.js';
+import { resolveApiKey, resolveEndpoint, } from './credentials.js';
+import { OperationBuilder } from './builder.js';
+import { MergeBuilder, asset } from './merge.js';
+import { PresetDefaults } from './ergonomic/presets/index.js';
+// ---------------------------------------------------------------------------
+// Anonymous-capable operation allowlist (internal)
+// ---------------------------------------------------------------------------
+/**
+ * Operations that may be invoked on a `gisl.anonymous()` client without
+ * raising `GislFeatureRequiresAuthError`. Empty until the free-tier launch
+ * decision lands (plan §12). Typed as a `readonly []` tuple (NOT
+ * `readonly string[]`) so the audit-gate compile-time assertion in
+ * `_audit.ts` fires if a future PR widens this without flipping the
+ * parking-decision + adding the public `gisl.anonymous()` export.
+ *
+ * Consumers must not depend on its emptiness today — only `package.json`
+ * `exports` keeps deep-imports blocked; the marker is internal.
+ *
+ * @internal
+ */
+export const ANONYMOUS_ALLOWLIST = [];
+// ---------------------------------------------------------------------------
+// Factories
+// ---------------------------------------------------------------------------
+/**
+ * Construct an ergonomic-layer client. Resolves the API key + base URL via
+ * the credential chain (see `credentials.ts`) and constructs a low-level
+ * `GislClient`. Throws `GislMissingCredentialsError` synchronously before
+ * any HTTP I/O when no key is found AND neither `useSessionCookie` nor
+ * `allowAnonymous` is set.
+ *
+ * Cookie-mode (`useSessionCookie: true`) explicitly bypasses the missing-
+ * credentials check — browser SPAs that drive auth via `client.login()`
+ * legitimately have no apiKey at construction time.
+ */
+export async function create(opts = {}) {
+    // Extract presetDefaults BEFORE `_createInternal` destructures and
+    // strips it — the resolver needs the value for every operation call,
+    // not just construction. `_createInternal` still strips the slot
+    // from the low-level `GislClient` config (no leak into transport).
+    const presetDefaults = opts.presetDefaults;
+    return wrapErgonomic(await _createInternal(opts), presetDefaults);
+}
+/**
+ * Compose the ergonomic operation surface (`.compress` / `.convert` /
+ * `.thumbnail`) on top of a `GislClient` via Proxy — matches the
+ * `wrapAnonymous` precedent (no prototype mutation). Layer order is
+ * builder-wrap INSIDE, anonymous-wrap OUTSIDE so the allowlist gate
+ * runs last in `_internalAnonymous` (see `_createInternal`).
+ */
+function wrapErgonomic(client, presetDefaults, scopedPresetDefaults) {
+    return new Proxy(client, {
+        get(target, prop, receiver) {
+            if (prop === 'compress' || prop === 'convert' || prop === 'thumbnail') {
+                return (input, 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
+                    // builder construction.
+                    // T4c — also forward the scopedPresetDefaults closure (from
+                    // `withPresetDefaults`); `undefined` on root clients.
+                    return new OperationBuilder(target, prop, input, options, presetDefaults, scopedPresetDefaults);
+                };
+            }
+            if (prop === 'withPresetDefaults') {
+                // T4c — immutable scoped derive. Computes mergedScoped =
+                // (parent.scoped === undefined ? new : PresetDefaults.merge(
+                // parent.scoped, new)) and returns a new Proxy wrapping the SAME
+                // underlying GislClient `target` (identity preservation —
+                // baseUrl / apiKey / headers / timeouts / multipart / session-
+                // cookie all by reference). Does NOT re-trigger _createInternal
+                // / resolveApiKey (codex r2 invariant — derives never re-read
+                // env or profile).
+                return (defaults) => {
+                    const mergedScoped = scopedPresetDefaults === undefined
+                        ? defaults
+                        : PresetDefaults.merge(scopedPresetDefaults, defaults);
+                    return wrapErgonomic(target, presetDefaults, mergedScoped);
+                };
+            }
+            if (prop === 'merge') {
+                // merge(...) accepts a mix of:
+                // - Asset objects (handle/path) — declared explicitly
+                // - string | Blob — wrapped via `asset()`
+                // - MergeOptions (always LAST) — sniffed by the absence of asset shape
+                return (...args) => {
+                    let mergeOpts = {};
+                    let last = args.length > 0 ? args[args.length - 1] : undefined;
+                    if (isMergeOptions(last)) {
+                        mergeOpts = last;
+                        args = args.slice(0, -1);
+                    }
+                    const declared = args.map((a) => {
+                        if (typeof a === 'string' || a instanceof Blob)
+                            return asset(a);
+                        // Asset (handle or path).
+                        return a;
+                    });
+                    return new MergeBuilder(target, declared, mergeOpts);
+                };
+            }
+            return Reflect.get(target, prop, receiver);
+        },
+    });
+}
+/**
+ * Sniff whether the final argument to `merge(...)` is a `MergeOptions`
+ * object rather than an `Asset`. Heuristic: an `Asset` always has a
+ * `type` field with `'handle'` or `'path'`; a `MergeOptions` does not.
+ */
+function isMergeOptions(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    if (typeof value.then === 'function')
+        return false;
+    if (value instanceof Blob)
+        return false;
+    const t = value.type;
+    if (t === 'handle' || t === 'path' || t === 'clip')
+        return false;
+    return true;
+}
+/**
+ * Inner factory shared by `create()` and `_internalAnonymous()` — extracted
+ * so the anonymous branch can ENTIRELY skip the credential chain rather
+ * than just suppressing its throw (codex r1 high e9e1c1182d56 — without
+ * this, env-resolved keys would silently attach an Authorization header
+ * to anonymous calls and defeat the parking guarantee).
+ *
+ * @internal
+ */
+async function _createInternal(opts) {
+    const { apiKey: explicitKey, profile, profilePath, useSessionCookie, baseUrl, environment, allowAnonymous, 
+    // T4a slot — stripped from transportConfig so it does not leak
+    // into the low-level `GislClientConfig` spread. The T4b resolver
+    // reads `opts.presetDefaults` directly via its own path.
+    presetDefaults: _presetDefaults, ...transportConfig } = opts;
+    void _presetDefaults;
+    const resolvedBaseUrl = resolveEndpoint({ baseUrl, environment });
+    // Anonymous mode entirely BYPASSES the credential chain. Any env / profile
+    // key that happens to exist on the host MUST NOT leak into the request
+    // (codex r1 high e9e1c1182d56). Cookie-mode also bypasses, since the
+    // caller authenticates via session cookie later.
+    if (allowAnonymous === true) {
+        const config = {
+            baseUrl: resolvedBaseUrl,
+            ...transportConfig,
+        };
+        if (useSessionCookie !== undefined) {
+            config.useSessionCookie = useSessionCookie;
+        }
+        return wrapAnonymous(new GislClient(config));
+    }
+    // Cookie-mode: skip env / profile resolution entirely UNLESS the caller
+    // ALSO passes an explicit `{apiKey}` (the mixed case is legitimate — a
+    // cookie-authenticated SPA may also send a server-issued API key). Codex
+    // r2 medium 913e4d8073f5 — without this, useSessionCookie=true could
+    // silently pick up an ambient GISL_API_KEY or fail on a malformed local
+    // profile, neither of which a cookie-auth caller expects.
+    let resolvedKey;
+    if (useSessionCookie === true && (explicitKey === undefined || explicitKey === '')) {
+        resolvedKey = null;
+    }
+    else {
+        resolvedKey = await resolveApiKey({
+            apiKey: explicitKey,
+            profile,
+            profilePath,
+            useSessionCookie,
+        });
+    }
+    if (resolvedKey === null && useSessionCookie !== true) {
+        throw new GislMissingCredentialsError('No API key found via explicit arg, GISL_API_KEY env, or ~/.gisl/credentials profile. ' +
+            'Pass {apiKey} explicitly, set GISL_API_KEY, populate ~/.gisl/credentials, ' +
+            'or pass {useSessionCookie: true} for browser session-cookie authentication.');
+    }
+    const config = {
+        baseUrl: resolvedBaseUrl,
+        ...transportConfig,
+    };
+    if (resolvedKey !== null) {
+        config.apiKey = resolvedKey;
+    }
+    if (useSessionCookie !== undefined) {
+        config.useSessionCookie = useSessionCookie;
+    }
+    return new GislClient(config);
+}
+/**
+ * Wrap a `GislClient` so calls to non-allowlisted operations throw
+ * `GislFeatureRequiresAuthError` BEFORE any I/O. This is the internal
+ * capability that backs `gisl.anonymous()` once the allowlist is non-empty.
+ *
+ * @internal
+ */
+function wrapAnonymous(client) {
+    // Explicit Set<string> — `ANONYMOUS_ALLOWLIST` is currently typed as the
+    // empty tuple `readonly []` (audit-gate parking-invariant in _audit.ts).
+    // Without this, `new Set(ANONYMOUS_ALLOWLIST)` would infer `Set<never>`.
+    const allowlist = new Set(ANONYMOUS_ALLOWLIST);
+    return new Proxy(client, {
+        get(target, prop, receiver) {
+            const value = Reflect.get(target, prop, receiver);
+            if (typeof value !== 'function' || typeof prop !== 'string') {
+                return value;
+            }
+            // Allow base infrastructure methods that don't carry user operations.
+            if (prop.startsWith('_') ||
+                prop === 'login' ||
+                prop === 'logout' ||
+                prop === 'getSchema' ||
+                prop === 'submitContact' ||
+                prop === 'constructor') {
+                return value.bind(target);
+            }
+            // Allowlist gate: throw if the op isn't approved for anonymous use.
+            if (!allowlist.has(prop)) {
+                return () => {
+                    throw new GislFeatureRequiresAuthError(prop, `Operation '${prop}' is not available on an anonymous client. ` +
+                        `Use gisl.create({apiKey}) for authenticated access, or wait for the operation to be added to the anonymous allowlist.`);
+                };
+            }
+            return value.bind(target);
+        },
+    });
+}
+// ---------------------------------------------------------------------------
+// Public `gisl` namespace
+// ---------------------------------------------------------------------------
+/**
+ * The `gisl` namespace — primary ergonomic-layer entry point.
+ * Exports `gisl.create()` only for v0.7; `gisl.anonymous()` lands once
+ * the anonymous-capable operation allowlist is non-empty (plan §12).
+ */
+export const gisl = {
+    create,
+};
+// `_internalAnonymous` is the implementation behind the future public
+// `gisl.anonymous()` export. Kept underscore-prefixed so it does not
+// reach the audit gate as a public symbol.
+/** @internal */
+export async function _internalAnonymous(opts = {}) {
+    return _createInternal({ ...opts, allowAnonymous: true });
+}
+// Re-export error types for callers that want to `instanceof` them.
+export { GislConfigError, GislMissingCredentialsError, GislFeatureRequiresAuthError };

package/dist/index.d.ts

@@ -3,15 +3,25 @@ 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, GislConfigError, GislMissingCredentialsError, GislFeatureRequiresAuthError, GislUndeclaredAssetError, GislUnusedAssetError, GislPerInputOptionsNotSupportedError, GislChainCardinalityMismatchError, } 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 { 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,33 @@ 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, 
+// 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, } from './errors.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 +49,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;
+}