@giveitsmaller/sdk 0.6.0 → 0.8.0

package/dist/ergonomic/presets/index.js

@@ -0,0 +1,216 @@
+// T4a — PresetDefaults immutable builder + presetDefaults() factory.
+//
+// Implements the user-facing path for layered preset configuration:
+//
+//   const defaults = presetDefaults()
+//     .imageCompress(OptimizeFor.Size, { quality: 75 })
+//     .videoCompress(OptimizeFor.Quality);
+//
+//   const client = await gisl.create({ presetDefaults: defaults });
+//
+// `T4a` ships only the typed slot and the builder semantics — the
+// resolver (T4b) reads `defaults.cellFor(media, op, level)` and merges
+// shipped defaults + this user delta + per-call overrides at workflow-
+// create time.
+//
+// **Semantics**
+// - `cellFor(media, op, level)` returns the USER-SUPPLIED DELTA stored
+//   by the matching `.imageCompress(level, input)` call, or `undefined`
+//   if no such delta was registered. It does NOT return shipped defaults
+//   — those live on the leaf class (`*.shippedDefaultsFor(level)`).
+// - Per-cell methods are immutable: each returns a fresh `PresetDefaults`
+//   carrying the original entries plus the new (cell, level) registration.
+//   Calling the same method twice on the same instance yields two
+//   distinct objects.
+// - Calling `.imageCompress(level)` with no input registers an empty
+//   delta — the resolver will see "this cell asked for `level` with no
+//   overrides" and apply shipped defaults verbatim.
+import { ImageCompressPresetOptions, } from './image_compress.js';
+import { AudioCompressPresetOptions, } from './audio_compress.js';
+import { VideoCompressPresetOptions, } from './video_compress.js';
+import { DocumentPdfCompressPresetOptions, } from './document_pdf_compress.js';
+import { DocumentOfficeCompressPresetOptions, } from './document_office_compress.js';
+import { DocumentOdfCompressPresetOptions, } from './document_odf_compress.js';
+import { DocumentEpubCompressPresetOptions, } from './document_epub_compress.js';
+// Re-export everything callers need from this module's root.
+export { ImageCompressPresetOptions, } from './image_compress.js';
+export { AudioCompressPresetOptions, } from './audio_compress.js';
+export { VideoCompressPresetOptions, } from './video_compress.js';
+export { DocumentPdfCompressPresetOptions, } from './document_pdf_compress.js';
+export { DocumentOfficeCompressPresetOptions, } from './document_office_compress.js';
+export { DocumentOdfCompressPresetOptions, } from './document_odf_compress.js';
+export { DocumentEpubCompressPresetOptions, } from './document_epub_compress.js';
+// Re-export ergonomic enums for callers (single canonical path).
+export { OptimizeFor, ImageMode, ImageFit, ImageMetadataPolicy, IccProfilePolicy, ImageFormat, VideoCodec, VideoPreset, VideoFit, AudioBitrate, AudioCodec, AudioSampleRate, PdfProfile, PdfColorspace, } from '../../generated/sdk_spec/enums.js';
+function cellKeyOf(media, op) {
+    return `${media}_${op}`;
+}
+/**
+ * Per-cell field-merge: parent fields ⊕ child fields where defined.
+ * Re-construct the leaf DTO via the matching `<LeafClass>.from(merged)`
+ * call so the result is a freshly-frozen `*PresetOptions` instance —
+ * NOT a mutated reference into either input. Used by
+ * {@link PresetDefaults.merge} when both parent and child registered
+ * the same `(cellKey, level)` tuple.
+ *
+ * `definedFieldsOf` filters undefined values out of each instance
+ * BEFORE the merge: with TS `useDefineForClassFields` (the ES2022
+ * default), `readonly mode?: ImageMode` declarations initialise the
+ * field as an enumerable own property with value `undefined` BEFORE
+ * the ctor body runs. A naive `Object.assign({}, parent, child)`
+ * therefore lets child's `undefined` overwrite parent's defined value
+ * — caught by CI on PR #125 first run. Filter-then-spread restores
+ * the documented merge-not-replace semantics.
+ *
+ * @internal
+ */
+function definedFieldsOf(opts) {
+    const out = {};
+    for (const key of Object.keys(opts)) {
+        const value = opts[key];
+        if (value !== undefined)
+            out[key] = value;
+    }
+    return out;
+}
+function mergePresetOptions(cellKey, parentOpts, childOpts) {
+    // Child fields win on overlap; parent fills the remaining gaps.
+    // `definedFieldsOf` strips undefined-valued slots that TS class
+    // field declarations create even when the ctor body skipped the
+    // assignment (see helper docblock).
+    const mergedFields = {
+        ...definedFieldsOf(parentOpts),
+        ...definedFieldsOf(childOpts),
+    };
+    switch (cellKey) {
+        case 'image_compress':
+            return ImageCompressPresetOptions.from(mergedFields);
+        case 'audio_compress':
+            return AudioCompressPresetOptions.from(mergedFields);
+        case 'video_compress':
+            return VideoCompressPresetOptions.from(mergedFields);
+        case 'document_pdf_compress':
+            return DocumentPdfCompressPresetOptions.from(mergedFields);
+        case 'document_office_compress':
+            return DocumentOfficeCompressPresetOptions.from(mergedFields);
+        case 'document_odf_compress':
+            return DocumentOdfCompressPresetOptions.from(mergedFields);
+        case 'document_epub_compress':
+            return DocumentEpubCompressPresetOptions.from(mergedFields);
+    }
+}
+/**
+ * Append `(level, options)` into a fresh map under `cellKey`, returning
+ * a new outer map. Both layers stay immutable — callers' references to
+ * the previous PresetDefaults remain unchanged.
+ */
+function withCellEntry(prev, cellKey, level, options) {
+    const next = new Map(prev);
+    const prevEntries = prev.get(cellKey);
+    const nextEntries = new Map(prevEntries ?? []);
+    nextEntries.set(level, options);
+    next.set(cellKey, nextEntries);
+    return next;
+}
+export class PresetDefaults {
+    cells;
+    constructor(cells) {
+        this.cells = cells;
+        Object.freeze(this);
+    }
+    /** Empty builder — entry point for `presetDefaults()`. @internal */
+    static _empty() {
+        return new PresetDefaults(new Map());
+    }
+    /**
+     * Deep-merge two {@link PresetDefaults} into a new instance (T4c —
+     * `ULAlOP6j`). Used by `withPresetDefaults` to stack scoped derives:
+     * `client.withPresetDefaults(a).withPresetDefaults(b)` produces a
+     * scoped layer equivalent to `merge(a, b)` — `b`'s per-cell fields
+     * override `a`'s where defined; `a`'s fields fill gaps.
+     *
+     * Per-cell semantics (codex r2 #5 — scalar-leaf merge):
+     * - If a `(cellKey, level)` entry is present in EITHER only, take it
+     *   verbatim.
+     * - If present in both, merge the per-cell `*Input` shapes via
+     *   `Object.assign({}, parentInput, childInput)` and re-construct
+     *   the leaf DTO. Every cell-DTO field is a scalar (primitive,
+     *   enum-string, or `string | number` for `targetSize`) — shallow
+     *   merge gives the correct field-wise override.
+     *
+     * Parent and child instances are unaffected.
+     */
+    static merge(parent, child) {
+        const merged = new Map();
+        // Seed with a clone of parent's entries (one inner Map per cellKey
+        // so child writes don't bleed back into parent's frozen structure).
+        for (const [cellKey, entries] of parent.cells) {
+            merged.set(cellKey, new Map(entries));
+        }
+        // Overlay child entries. Same (cellKey, level) → field-merge;
+        // child-only → take verbatim.
+        for (const [cellKey, childEntries] of child.cells) {
+            const target = merged.get(cellKey);
+            if (target === undefined) {
+                merged.set(cellKey, new Map(childEntries));
+                continue;
+            }
+            for (const [level, childOpts] of childEntries) {
+                const parentOpts = target.get(level);
+                if (parentOpts === undefined) {
+                    target.set(level, childOpts);
+                    continue;
+                }
+                target.set(level, mergePresetOptions(cellKey, parentOpts, childOpts));
+            }
+        }
+        return new PresetDefaults(merged);
+    }
+    /** Register a (level, delta) on the image-compress cell. Immutable. */
+    imageCompress(level, input = {}) {
+        return new PresetDefaults(withCellEntry(this.cells, 'image_compress', level, ImageCompressPresetOptions.from(input)));
+    }
+    /** Register a (level, delta) on the audio-compress cell. Immutable. */
+    audioCompress(level, input = {}) {
+        return new PresetDefaults(withCellEntry(this.cells, 'audio_compress', level, AudioCompressPresetOptions.from(input)));
+    }
+    /** Register a (level, delta) on the video-compress cell. Immutable. */
+    videoCompress(level, input = {}) {
+        return new PresetDefaults(withCellEntry(this.cells, 'video_compress', level, VideoCompressPresetOptions.from(input)));
+    }
+    /** Register a (level, delta) on the document-pdf-compress cell. Immutable. */
+    pdfCompress(level, input = {}) {
+        return new PresetDefaults(withCellEntry(this.cells, 'document_pdf_compress', level, DocumentPdfCompressPresetOptions.from(input)));
+    }
+    /** Register a (level, delta) on the document-office-compress cell. Immutable. */
+    officeCompress(level, input = {}) {
+        return new PresetDefaults(withCellEntry(this.cells, 'document_office_compress', level, DocumentOfficeCompressPresetOptions.from(input)));
+    }
+    /** Register a (level, delta) on the document-odf-compress cell. Immutable. */
+    odfCompress(level, input = {}) {
+        return new PresetDefaults(withCellEntry(this.cells, 'document_odf_compress', level, DocumentOdfCompressPresetOptions.from(input)));
+    }
+    /** Register a (level, delta) on the document-epub-compress cell. Immutable. */
+    epubCompress(level, input = {}) {
+        return new PresetDefaults(withCellEntry(this.cells, 'document_epub_compress', level, DocumentEpubCompressPresetOptions.from(input)));
+    }
+    /**
+     * Return the user-supplied delta registered for `(media, op, level)`,
+     * or `undefined` if none was registered.
+     *
+     * @internal — consumed by the T4b resolver. Not part of the public
+     * surface; the resolver imports it via the type-only re-export.
+     */
+    cellFor(media, op, level) {
+        const entries = this.cells.get(cellKeyOf(media, op));
+        return entries?.get(level);
+    }
+}
+/**
+ * Construct an empty {@link PresetDefaults} builder. Chain per-cell
+ * methods to register layered defaults; the resolver in T4b consumes
+ * the result via `cellFor(...)`.
+ */
+export function presetDefaults() {
+    return PresetDefaults._empty();
+}

package/dist/ergonomic/presets/video_compress.d.ts

@@ -0,0 +1,30 @@
+import { VideoCodec, VideoPreset, VideoFit, AudioCodec, AudioBitrate, OptimizeFor } from '../../generated/sdk_spec/enums.js';
+export interface VideoCompressPresetOptionsInput {
+    readonly codec?: VideoCodec;
+    readonly targetSize?: string | number;
+    readonly crf?: number;
+    readonly preset?: VideoPreset;
+    readonly width?: number;
+    readonly height?: number;
+    readonly fit?: VideoFit;
+    readonly fps?: number;
+    readonly faststart?: boolean;
+    readonly audioCodec?: AudioCodec;
+    readonly audioBitrate?: AudioBitrate;
+}
+export declare class VideoCompressPresetOptions {
+    readonly codec?: VideoCodec;
+    readonly targetSize?: string | number;
+    readonly crf?: number;
+    readonly preset?: VideoPreset;
+    readonly width?: number;
+    readonly height?: number;
+    readonly fit?: VideoFit;
+    readonly fps?: number;
+    readonly faststart?: boolean;
+    readonly audioCodec?: AudioCodec;
+    readonly audioBitrate?: AudioBitrate;
+    private constructor();
+    static from(input: VideoCompressPresetOptionsInput): VideoCompressPresetOptions;
+    static shippedDefaultsFor(level: OptimizeFor): VideoCompressPresetOptions;
+}

package/dist/ergonomic/presets/video_compress.js

@@ -0,0 +1,83 @@
+// T4a — VideoCompressPresetOptions leaf DTO.
+//
+// Field set per ticket VhIj4S7T: video = 11 fields
+//   (codec, targetSize, crf, preset, width, height, fit, fps, faststart,
+//    audioCodec, audioBitrate).
+// Deliberately excluded: encodingMode + targetSizeBytes (raw wire —
+// replaced by ergonomic `targetSize: string|number` which the SDK derives
+// at resolve time in T4b), trim_start/trim_end (per-call content selection).
+//
+// `targetSize` accepts `string` (e.g. "50MB") or `number` (bytes). The
+// resolver in T4b converts to the wire `target_size_bytes` and sets
+// `encoding_mode: target_size` accordingly.
+import { shippedDefaultsFor as f3ShippedDefaultsFor } from '../../generated/sdk_spec/presets.js';
+import { translateEnum } from './_translate.js';
+export class VideoCompressPresetOptions {
+    codec;
+    targetSize;
+    crf;
+    preset;
+    width;
+    height;
+    fit;
+    fps;
+    faststart;
+    audioCodec;
+    audioBitrate;
+    constructor(input) {
+        if (input.codec !== undefined)
+            this.codec = input.codec;
+        if (input.targetSize !== undefined)
+            this.targetSize = input.targetSize;
+        if (input.crf !== undefined)
+            this.crf = input.crf;
+        if (input.preset !== undefined)
+            this.preset = input.preset;
+        if (input.width !== undefined)
+            this.width = input.width;
+        if (input.height !== undefined)
+            this.height = input.height;
+        if (input.fit !== undefined)
+            this.fit = input.fit;
+        if (input.fps !== undefined)
+            this.fps = input.fps;
+        if (input.faststart !== undefined)
+            this.faststart = input.faststart;
+        if (input.audioCodec !== undefined)
+            this.audioCodec = input.audioCodec;
+        if (input.audioBitrate !== undefined)
+            this.audioBitrate = input.audioBitrate;
+        Object.freeze(this);
+    }
+    static from(input) {
+        return new VideoCompressPresetOptions(input);
+    }
+    static shippedDefaultsFor(level) {
+        const cell = f3ShippedDefaultsFor('video_compress', level);
+        const input = {};
+        const mut = input;
+        if ('codec' in cell)
+            mut.codec = translateEnum('VideoCodec', cell.codec);
+        if ('targetSize' in cell)
+            mut.targetSize = cell.targetSize;
+        if ('crf' in cell)
+            mut.crf = cell.crf;
+        if ('preset' in cell)
+            mut.preset = translateEnum('VideoPreset', cell.preset);
+        if ('width' in cell)
+            mut.width = cell.width;
+        if ('height' in cell)
+            mut.height = cell.height;
+        if ('fit' in cell)
+            mut.fit = translateEnum('VideoFit', cell.fit);
+        if ('fps' in cell)
+            mut.fps = cell.fps;
+        if ('faststart' in cell)
+            mut.faststart = cell.faststart;
+        if ('audioCodec' in cell)
+            mut.audioCodec = translateEnum('AudioCodec', cell.audioCodec);
+        if ('audioBitrate' in cell)
+            mut.audioBitrate = translateEnum('AudioBitrate', cell.audioBitrate);
+        return new VideoCompressPresetOptions(input);
+    }
+}

package/dist/errors.d.ts

@@ -1,4 +1,4 @@
-import type { AuthErrorResponse, BalanceExhaustedResponse, FeatureNotAvailableResponse, FeatureTierRestrictedResponse, TierRestrictionResponse, UploadDurationExceedsTierResponse, UploadSizeExceedsTierResponse, WorkflowExpiredResponse } from '@giveitsmaller/contracts/openapi';
+import type { AuthErrorResponse, BalanceExhaustedResponse, FeatureNotAvailableResponse, FeatureTierRestrictedResponse, ProbePendingResponse, TierRestrictionResponse, UploadDurationExceedsTierResponse, UploadSizeExceedsTierResponse, WorkflowExpiredResponse } from '@giveitsmaller/contracts/openapi';
 export declare class GislError extends Error {
     constructor(message: string);
 }
@@ -62,6 +62,37 @@ export declare class GislFeatureNotAvailableError extends GislApiError {
     readonly payload: FeatureNotAvailableResponse;
     constructor(statusCode: number, errorMessage: string, payload: FeatureNotAvailableResponse, path?: string, extra?: Omit<GislApiErrorOptions, 'payload'>);
 }
+/**
+ * 422 response on `POST /api/workflows` when a job references an upload
+ * whose server-side probe hasn't completed at workflow-create time. The
+ * server rejects rather than silently routing as `short_form` (which
+ * hard-fails long video clips).
+ *
+ * **Recovery contract** (per contracts ProbePendingResponse docblock):
+ * poll `POST /api/uploads/{id}/probe` for the pending upload until
+ * `probe_status` is terminal (`ok` → re-`POST /api/workflows` the same
+ * request; `corrupt` / `unsupported_codec` → surface the probe error).
+ * The `Retry-After` response header (when present) suggests a delay
+ * in seconds before the next poll/retry.
+ *
+ * `payload.jobRef` identifies which job in the multi-job request triggered
+ * the probe-pending rejection.
+ *
+ * @example
+ * try {
+ *   await client.createWorkflow({ jobs });
+ * } catch (e) {
+ *   if (e instanceof GislProbePendingError) {
+ *     await waitForProbe(e.payload.jobRef);
+ *     // retry...
+ *   }
+ *   throw e;
+ * }
+ */
+export declare class GislProbePendingError extends GislApiError {
+    readonly payload: ProbePendingResponse;
+    constructor(statusCode: number, errorMessage: string, payload: ProbePendingResponse, path?: string, extra?: Omit<GislApiErrorOptions, 'payload'>);
+}
 export declare class GislWorkflowExpiredError extends GislApiError {
     readonly payload: WorkflowExpiredResponse;
     constructor(statusCode: number, errorMessage: string, payload: WorkflowExpiredResponse, path?: string, extra?: Omit<GislApiErrorOptions, 'payload'>);
@@ -151,9 +182,136 @@ export declare class GislMultipartSessionOwnershipError extends GislApiError {
 export declare class GislMultipartSessionAuthRequiredError extends GislApiError {
     constructor(statusCode: number, errorMessage: string, path?: string, options?: GislApiErrorOptions);
 }
+/**
+ * Optional structured metadata attached to a {@link GislConfigError}. The
+ * preset resolver (T4b) raises errors with these fields populated so
+ * callers can branch on machine-readable codes rather than parsing the
+ * human message. Every field is optional — existing call sites that
+ * throw `new GislConfigError(message)` keep working unchanged.
+ */
+export interface GislConfigErrorMetadata {
+    /**
+     * Machine-readable error code. Resolver-side values today:
+     * `'invalid_combination'`, `'missing_dependency'`, `'type_mismatch'`,
+     * `'unknown_field'`, `'invalid_target_size'`. Other call sites may add
+     * codes — the union is open.
+     */
+    readonly reason?: string;
+    /**
+     * Field names (camelCase) that participated in the rejection. For
+     * `invalid_combination` reasons this is the *pair* that conflicts
+     * (e.g. `['targetSize', 'codec']`); for `missing_dependency` this is
+     * the dependent field plus the field whose value blocks it.
+     */
+    readonly conflictingFields?: readonly string[];
+    /**
+     * The merged wire-shape snapshot the resolver computed BEFORE the
+     * validation rejected it. Lets callers see "what would have been
+     * sent" for debugging without re-running the chain.
+     */
+    readonly resolvedSnapshot?: Readonly<Record<string, unknown>>;
+    /**
+     * Short human-readable remediation hint specific to the error. E.g.
+     * "Switch codec to H264, or drop targetSize and use crf instead."
+     */
+    readonly suggestion?: string;
+}
+/**
+ * Root of the LOCAL config-error tree — thrown before any HTTP/file I/O.
+ * Sibling of `GislApiError` (which represents server-side error envelopes).
+ * Reserve for fail-early errors raised by the ergonomic-layer factory or
+ * credential-chain resolver when the caller hasn't supplied something the
+ * SDK needs to make a request. Never carries an HTTP status code.
+ *
+ * Optional `metadata` (T4b — `27rE1fZn`) carries structured fields used
+ * by the preset resolver and other ergonomic-layer validators. Existing
+ * call sites that pass `(message)` keep working — metadata is purely
+ * additive and defaults to `undefined`.
+ */
+export declare class GislConfigError extends GislError {
+    readonly reason?: string;
+    readonly conflictingFields?: readonly string[];
+    readonly resolvedSnapshot?: Readonly<Record<string, unknown>>;
+    readonly suggestion?: string;
+    constructor(message: string, metadata?: GislConfigErrorMetadata);
+}
+/**
+ * The ergonomic-layer factory `gisl.create()` could not resolve an API key
+ * from any of explicit arg, `GISL_API_KEY` env, or shared-config profile,
+ * AND the caller did not opt into anonymous or cookie-mode. Thrown BEFORE
+ * any file read or HTTP request — calls to `client.compress(...)`, `.run()`,
+ * etc., synchronously fail with this error.
+ */
+export declare class GislMissingCredentialsError extends GislConfigError {
+    constructor(message: string);
+}
+/**
+ * The caller used `gisl.anonymous()` and then invoked an operation that is
+ * not in the anonymous-capable allowlist. Local-only — thrown before any I/O.
+ * Distinct from server-side `GislAuthError` (401/403 on the wire).
+ */
+export declare class GislFeatureRequiresAuthError extends GislConfigError {
+    readonly operation: string;
+    constructor(operation: string, message: string);
+}
+/**
+ * `MergeBuilder.sequence(...)` referenced an asset that wasn't declared in
+ * the prior `client.merge(...)` call. Local validation runs BEFORE upload
+ * so the caller fails fast on the typo without burning bandwidth.
+ */
+export declare class GislUndeclaredAssetError extends GislConfigError {
+    readonly assetId: string;
+    readonly declaredAssets: readonly string[];
+    constructor(assetId: string, declaredAssets: readonly string[]);
+}
+/**
+ * `MergeBuilder.sequence(...)` was called but at least one declared asset
+ * wasn't referenced. Almost always a bug (wasted upload). Escape via
+ * `allowUnusedAssets: true` on the merge options.
+ */
+export declare class GislUnusedAssetError extends GislConfigError {
+    readonly unusedAssets: readonly string[];
+    constructor(unusedAssets: readonly string[]);
+}
+/**
+ * `MergeBuilder.sequence(...)` on an image merge was given a `clip(ref, opts)`
+ * entry. Image merges have NO per-input options in the wire today — `transition`
+ * applies at the merge level and is uniform across all joins.
+ */
+export declare class GislPerInputOptionsNotSupportedError extends GislConfigError {
+    readonly mediaKind: string;
+    constructor(mediaKind: string);
+}
+/**
+ * Thrown by future chain methods (`.compress()` / `.thumbnail()` /
+ * `.convert()` on an `OperationBuilder`) when the previous step produces
+ * MULTIPLE artifacts and the caller didn't explicitly call `.mapEach(...)`
+ * to opt into per-artifact fan-out. T6 ships the error class + the
+ * `.mapEach(...)` method; the chain methods themselves are a separate
+ * follow-up card, so this error is currently dormant — but the type +
+ * audit-gate registration land here so the future chain-method PR is a
+ * pure addition with no public-API churn.
+ */
+export declare class GislChainCardinalityMismatchError extends GislConfigError {
+    readonly previousOperation: string;
+    readonly attemptedOperation: string;
+    constructor(previousOperation: string, attemptedOperation: string);
+}
 export declare class GislTimeoutError extends GislError {
     constructor(message: string);
 }
+/**
+ * Transport-level failure: the underlying `fetch` (or other transport) could
+ * not produce a usable response — DNS, TCP, TLS, a mid-stream disconnect, or a
+ * non-ok status / empty body when fetching a result download. Mirrors the PHP
+ * `Gisl\Sdk\Errors\GislNetworkError`. Subclasses `GislError` (not
+ * `GislApiError`) because it carries no contract error envelope. The concrete
+ * file-first {@link Downloader} raises this when the output URL cannot be read
+ * (a destination-WRITE failure is `GislSinkError` reason `write_failed`).
+ */
+export declare class GislNetworkError extends GislError {
+    constructor(message: string);
+}
 export declare class GislAbortError extends GislError {
     constructor(message: string);
 }
@@ -180,3 +338,40 @@ export declare class GislMultipartPartCountError extends GislError {
     readonly maxParts: number;
     constructor(message: string, requiredParts: number, maxParts: number);
 }
+/**
+ * Thrown by the file-first `RunResult.byKey()` (FF1) when no result entry
+ * matches the requested key. A keyless run (no `key:` supplied to `file()`)
+ * is addressable positionally only — `byKey()` always throws.
+ *
+ * Mirrors the PHP `Gisl\Sdk\Errors\GislNoSuchKeyError`.
+ */
+export declare class GislNoSuchKeyError extends GislError {
+    constructor(message: string);
+}
+/** Machine-readable cause carried by {@link GislSinkError}. */
+export type GislSinkErrorReason = 'not_single_output' | 'downloader_unavailable' | 'partial_failure' | 'duplicate_filename' | 'invalid_directory' | 'write_failed';
+/**
+ * Thrown by the file-first `RunResult` sinks (`toFile()` / `downloadTo()`,
+ * FF1) when they cannot deliver. The machine-readable `reason` discriminates
+ * the three cases, mirroring the `reason`-bag convention on
+ * {@link GislConfigError}:
+ *
+ *  - `not_single_output`      — `toFile()` requires exactly one output but the
+ *                               run produced zero or more than one.
+ *  - `downloader_unavailable` — the `RunResult` has no downloader bound (e.g. a
+ *                               browser / no-I/O context).
+ *  - `partial_failure`        — `downloadTo({ failOnPartial: true })` and the
+ *                               run had at least one failed input.
+ *  - `duplicate_filename`     — two outputs share a destination filename in one
+ *                               `downloadTo(dir)`, which would silently overwrite.
+ *  - `write_failed`           — a concrete {@link Downloader} could not open or
+ *                               stream to the destination path.
+ *
+ * Mirrors the PHP `Gisl\Sdk\Errors\GislSinkError`.
+ */
+export declare class GislSinkError extends GislError {
+    readonly reason: GislSinkErrorReason;
+    constructor(message: string, options: {
+        readonly reason: GislSinkErrorReason;
+    });
+}