@giveitsmaller/sdk 0.6.0 → 0.8.0

package/dist/errors.js

@@ -67,6 +67,39 @@ export class GislFeatureNotAvailableError extends GislApiError {
         this.name = 'GislFeatureNotAvailableError';
     }
 }
+/**
+ * 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 class GislProbePendingError extends GislApiError {
+    constructor(statusCode, errorMessage, payload, path, extra) {
+        super(statusCode, errorMessage, path, undefined, buildOptionsWithPayload(payload, extra));
+        this.name = 'GislProbePendingError';
+    }
+}
 export class GislWorkflowExpiredError extends GislApiError {
     constructor(statusCode, errorMessage, payload, path, extra) {
         super(statusCode, errorMessage, path, undefined, buildOptionsWithPayload(payload, extra));
@@ -153,12 +186,155 @@ export class GislMultipartSessionAuthRequiredError extends GislApiError {
         this.name = 'GislMultipartSessionAuthRequiredError';
     }
 }
+/**
+ * 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 class GislConfigError extends GislError {
+    reason;
+    conflictingFields;
+    resolvedSnapshot;
+    suggestion;
+    constructor(message, metadata) {
+        super(message);
+        this.name = 'GislConfigError';
+        if (metadata !== undefined) {
+            if (metadata.reason !== undefined)
+                this.reason = metadata.reason;
+            if (metadata.conflictingFields !== undefined) {
+                this.conflictingFields = metadata.conflictingFields;
+            }
+            if (metadata.resolvedSnapshot !== undefined) {
+                this.resolvedSnapshot = metadata.resolvedSnapshot;
+            }
+            if (metadata.suggestion !== undefined)
+                this.suggestion = metadata.suggestion;
+        }
+    }
+}
+/**
+ * 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 class GislMissingCredentialsError extends GislConfigError {
+    constructor(message) {
+        super(message);
+        this.name = 'GislMissingCredentialsError';
+    }
+}
+/**
+ * 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 class GislFeatureRequiresAuthError extends GislConfigError {
+    operation;
+    constructor(operation, message) {
+        super(message);
+        this.name = 'GislFeatureRequiresAuthError';
+        this.operation = operation;
+    }
+}
+/**
+ * `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 class GislUndeclaredAssetError extends GislConfigError {
+    assetId;
+    declaredAssets;
+    constructor(assetId, declaredAssets) {
+        super(`Sequence references asset '${assetId}' but it wasn't declared in merge(...). ` +
+            `Declared assets: [${declaredAssets.join(', ')}]. ` +
+            `Either pass it to merge(...) before sequencing, or remove the reference.`);
+        this.name = 'GislUndeclaredAssetError';
+        this.assetId = assetId;
+        this.declaredAssets = declaredAssets;
+    }
+}
+/**
+ * `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 class GislUnusedAssetError extends GislConfigError {
+    unusedAssets;
+    constructor(unusedAssets) {
+        super(`Assets [${unusedAssets.join(', ')}] were declared in merge(...) but never sequenced. ` +
+            `Reference them in .sequence(...), remove them from the declaration, ` +
+            `or pass {allowUnusedAssets: true} to opt out of this check.`);
+        this.name = 'GislUnusedAssetError';
+        this.unusedAssets = unusedAssets;
+    }
+}
+/**
+ * `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 class GislPerInputOptionsNotSupportedError extends GislConfigError {
+    mediaKind;
+    constructor(mediaKind) {
+        super(`${mediaKind} merge has no per-input options today; set 'transition' at the ` +
+            `.merge(...) level instead — it applies to every join.`);
+        this.name = 'GislPerInputOptionsNotSupportedError';
+        this.mediaKind = mediaKind;
+    }
+}
+/**
+ * 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 class GislChainCardinalityMismatchError extends GislConfigError {
+    previousOperation;
+    attemptedOperation;
+    constructor(previousOperation, attemptedOperation) {
+        super(`Previous step (${previousOperation}) produces multiple artifacts; ` +
+            `use .mapEach(art => art.${attemptedOperation}(...)) to apply the chain per-artifact, ` +
+            `or branch to a single artifact first.`);
+        this.name = 'GislChainCardinalityMismatchError';
+        this.previousOperation = previousOperation;
+        this.attemptedOperation = attemptedOperation;
+    }
+}
 export class GislTimeoutError extends GislError {
     constructor(message) {
         super(message);
         this.name = 'GislTimeoutError';
     }
 }
+/**
+ * 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 class GislNetworkError extends GislError {
+    constructor(message) {
+        super(message);
+        this.name = 'GislNetworkError';
+    }
+}
 export class GislAbortError extends GislError {
     constructor(message) {
         super(message);
@@ -198,3 +374,43 @@ export class GislMultipartPartCountError extends GislError {
         this.maxParts = maxParts;
     }
 }
+/**
+ * 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 class GislNoSuchKeyError extends GislError {
+    constructor(message) {
+        super(message);
+        this.name = 'GislNoSuchKeyError';
+    }
+}
+/**
+ * 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 class GislSinkError extends GislError {
+    reason;
+    constructor(message, options) {
+        super(message);
+        this.name = 'GislSinkError';
+        this.reason = options.reason;
+    }
+}

package/dist/file-first.d.ts

@@ -0,0 +1,284 @@
+/**
+ * File-first result surface — the value the file-first layer's `run()` /
+ * `Handle.wait()` / `Handle.result()` return (producers land in FF2b/FF5).
+ *
+ * Coexists with the operation-first `Result`/`Artifact` (in `builder.ts`)
+ * until the operation-first layer is removed (FF6). The file-first shape is
+ * flatter and adds an always-present per-input partition (`succeeded` /
+ * `failed`) so one bad input in a multi-input run doesn't sink the rest.
+ *
+ * Mirrors `packages/php/src/FileFirst/*`.
+ */
+import { type ProgressEvent } from './builder.js';
+import type { GislClient } from './client.js';
+import { OptimizeFor } from './generated/sdk_spec/enums.js';
+import type { PresetDefaults } from './ergonomic/presets/index.js';
+import type { WorkflowCreatePayload } from './types.js';
+/**
+ * Streams a single output URL to a local path. The seam between the
+ * file-first {@link RunResult} sinks and the SDK's HTTP/auth layer.
+ *
+ * FF1 defines ONLY this type — the concrete implementation (fetch +
+ * filesystem streamer) is wired by the producer tickets (`run()`/`submit()`,
+ * FF2b/FF5), which construct a `RunResult` with a real downloader bound to
+ * the client's auth context. Unit tests inject a small stub. A `RunResult`
+ * built WITHOUT a downloader (e.g. in a browser, or any no-I/O context)
+ * throws {@link GislSinkError} from its sinks rather than reaching for a
+ * global client.
+ *
+ * Mirrors the PHP `Downloader` interface.
+ *
+ * STREAMING CONTRACT: implementations MUST stream the URL body to
+ * `destPath` — they MUST NOT buffer the whole output in memory. The
+ * `Promise<void>` return exists precisely so no buffered-bytes value can
+ * leak into the calling convention.
+ */
+export interface Downloader {
+    /**
+     * Stream the body at `url` to the local filesystem path `destPath`.
+     * Implementations create/overwrite `destPath`. Failures reject.
+     */
+    downloadTo(url: string, destPath: string): Promise<void>;
+}
+/**
+ * A single deliverable output of a file-first run — the file-first layer's
+ * flat output type. Leaner than the operation-first `Artifact`: just the
+ * four fields a caller needs to identify + fetch an output.
+ *
+ * Mirrors the PHP `OutputFile`.
+ */
+export interface OutputFile {
+    readonly url: string;
+    readonly filename: string;
+    readonly sizeBytes: number;
+    readonly operation: string;
+}
+/**
+ * One succeeded entry in {@link RunResult.succeeded}: a single input's
+ * outputs, addressable by the `key:` the caller gave that file (null when
+ * no key was supplied). Mirrors the PHP `ItemResult`.
+ */
+export interface ItemResult {
+    readonly key: string | null;
+    readonly outputs: readonly OutputFile[];
+}
+/**
+ * One failed entry in {@link RunResult.failed}: an input that did not
+ * produce a deliverable, paired with the cause. One bad input does not sink
+ * the rest of a multi-input run. `error` is `unknown` (mirroring the PHP
+ * `\Throwable`) so the caller narrows with `instanceof`. Mirrors the PHP
+ * `ItemFailure`.
+ */
+export interface ItemFailure {
+    readonly key: string | null;
+    readonly error: unknown;
+}
+/**
+ * Return value of {@link RunResult.downloadTo} — the local paths written,
+ * in the SAME order as {@link RunResult.artifacts}. Mirrors the PHP
+ * `Manifest`.
+ */
+export interface Manifest {
+    readonly paths: readonly string[];
+}
+/**
+ * Result of a file-first run. Coexists with the operation-first `Result`
+ * (in `builder.ts`) until FF6.
+ *
+ * Mirrors the PHP `RunResult` class. A class (not a bare interface) because
+ * it carries the `byKey()`/`toFile()`/`downloadTo()` behaviour; the data
+ * fields stay public + readonly so `toArray()` round-trips.
+ *
+ * Field notes:
+ *  - `url`: single-output sugar — the lone artifact's URL when exactly one
+ *    output exists, else undefined.
+ *  - `ok`: true iff `failed` is empty. (A boolean — the partition lists are
+ *    `succeeded`/`failed`; resolves the design doc's `ok` bool-vs-list
+ *    contradiction.)
+ *  - `state`: lifecycle state (`completed` | `failed` | ...). Named `state`,
+ *    NOT `status`, matching the file-first `StatusSnapshot.state`.
+ *  - sinks fetch via the injected {@link Downloader}; a result with no
+ *    downloader throws {@link GislSinkError} (reason `downloader_unavailable`).
+ */
+export declare class RunResult {
+    readonly workflowId: string;
+    readonly state: string;
+    readonly artifacts: readonly OutputFile[];
+    readonly succeeded: readonly ItemResult[];
+    readonly failed: readonly ItemFailure[];
+    private readonly downloader?;
+    /** Single-output sugar: the lone artifact's URL, or undefined for 0 / >1. */
+    readonly url?: string;
+    /** True iff {@link failed} is empty. */
+    readonly ok: boolean;
+    constructor(workflowId: string, state: string, artifacts: readonly OutputFile[], succeeded: readonly ItemResult[], failed: readonly ItemFailure[], downloader?: Downloader | undefined);
+    /**
+     * Address a succeeded input by the `key:` given to `file()`. Duplicate keys
+     * are not valid input — the producer enforces key uniqueness (a later
+     * ticket); the first match is returned.
+     * @throws {GislNoSuchKeyError} when no succeeded entry has that key (a
+     *   keyless run always throws — it is positionally addressable only).
+     */
+    byKey(key: string): ItemResult;
+    /**
+     * Write the single output to `path`. Requires EXACTLY ONE artifact.
+     * @throws {GislSinkError} reason `not_single_output` for 0/>1 outputs;
+     *   reason `downloader_unavailable` when no downloader is bound.
+     */
+    toFile(path: string): Promise<void>;
+    /**
+     * Download every output into `dir` (filename per output), in output order.
+     * Returns the {@link Manifest} of local paths written.
+     * @throws {GislSinkError} reason `partial_failure` when `failOnPartial` and
+     *   the run had failed inputs; reason `downloader_unavailable` when no
+     *   downloader is bound.
+     */
+    downloadTo(dir: string, options?: {
+        failOnPartial?: boolean;
+    }): Promise<Manifest>;
+    /**
+     * Plain-object projection. Field ORDER (workflowId, state, ok, url?,
+     * artifacts, succeeded, failed) is fixed to match the PHP `toArray()`
+     * reference so JSON-string parity holds (FF1 shape assertion + FF2b harness
+     * fixture). `url` is omitted entirely when undefined — `JSON.stringify`
+     * then produces the identical shape to PHP's omit-when-null `toArray()`.
+     */
+    toJSON(): {
+        workflowId: string;
+        state: string;
+        ok: boolean;
+        url?: string;
+        artifacts: readonly OutputFile[];
+        succeeded: readonly {
+            key: string | null;
+            outputs: readonly OutputFile[];
+        }[];
+        failed: readonly {
+            key: string | null;
+            error: string;
+        }[];
+    };
+    private requireDownloader;
+}
+/**
+ * The primary file a {@link Recipe} operates on — the "subject" of the
+ * file-first surface. A discriminated union over the ways a caller names an
+ * input:
+ *
+ *  - `path`     — a local filesystem path (Node; the common case).
+ *  - `blob`     — an in-memory `Blob`/`File` (browser, or Node 18+).
+ *  - `uploadId` — a previously-uploaded `file_id` (reuse across recipes).
+ *
+ * FF2a does NO upload, so only the `path` + `uploadId` arms are exercised
+ * end-to-end here; the `blob` arm is DEFINED and type-checked but its upload
+ * is wired by FF2b (`run()`). Mirrors the PHP `FileInput` value object.
+ */
+export type FileInput = {
+    readonly kind: 'path';
+    readonly path: string;
+} | {
+    readonly kind: 'blob';
+    readonly blob: Blob;
+} | {
+    readonly kind: 'uploadId';
+    readonly fileId: string;
+};
+/** Named constructors for {@link FileInput} — mirror the PHP static factories. */
+export declare const fileInput: {
+    readonly path: (path: string) => FileInput;
+    readonly blob: (blob: Blob) => FileInput;
+    readonly uploadId: (fileId: string) => FileInput;
+};
+/** One step in a {@link Recipe}'s chain — an op kind + captured ergonomic args. */
+interface RecipeStep {
+    readonly opType: 'compress' | 'convert' | 'thumbnail' | 'text_watermark';
+    readonly options: Readonly<Record<string, unknown>>;
+}
+/**
+ * The file-first builder value. `client.file(path)` returns a `Recipe`;
+ * single-input operations called on it (`compress`, `convert`, `thumbnail`,
+ * `textWatermark`) chain SEQUENTIALLY — each op feeds the next, and the chain
+ * lowers to ONE workflow job with an ordered `operations[]` (per ADR-0004:
+ * operations execute sequentially, each consuming the previous output). A
+ * chain yields the TERMINAL output only; intermediates are consumed (surfaced
+ * by FF2b's `run()`/{@link RunResult}).
+ *
+ * **Immutable / clone-on-write.** Every op returns a NEW `Recipe` carrying the
+ * appended step — `this` is never mutated. A Recipe is therefore a reusable
+ * value: branching the same base recipe two different ways cannot let one
+ * branch observe the other's steps (the aliasing trap mutable builders fall
+ * into).
+ *
+ * FF2a is network-free: there is NO `run()` here (that is FF2b). The lowering
+ * seam {@link toWorkflowPayload} takes the resolved upload id as a parameter
+ * so it stays pure — FF2b's `run()` calls the SAME method after uploading, and
+ * the parity harness calls it with a fixed id to assert the lowered shape.
+ *
+ * Mirrors the PHP `Recipe`.
+ */
+export declare class Recipe {
+    private readonly input;
+    private readonly recipeKey;
+    private readonly steps;
+    private readonly presetDefaults?;
+    private readonly scopedPresetDefaults?;
+    private readonly client?;
+    constructor(input: FileInput, recipeKey?: string | undefined, steps?: readonly RecipeStep[], presetDefaults?: PresetDefaults | undefined, scopedPresetDefaults?: PresetDefaults | undefined, client?: GislClient | undefined);
+    /**
+     * Reduce file size. `optimize` selects a per-media preset (resolved to
+     * concrete wire fields at lower-time, exactly as `client.compress()` does).
+     */
+    compress(optimize?: OptimizeFor): Recipe;
+    /** Change format. `format` is lowered verbatim to the `format` wire option. */
+    convert(format: string): Recipe;
+    /**
+     * Generate a preview. Width and/or height in pixels; an omitted dimension is
+     * dropped from the wire options (not sent as `undefined`).
+     */
+    thumbnail(options?: {
+        width?: number;
+        height?: number;
+    }): Recipe;
+    /**
+     * Apply a text watermark. Single-input (the text is an option, not a
+     * secondary file) — lowers to the `text_watermark` op with a `text` option.
+     */
+    textWatermark(text: string): Recipe;
+    /**
+     * Lower this recipe to a workflow-create payload against a resolved upload
+     * id. Single-input chain → ONE job, `source: upload(fileId)`, ordered
+     * `operations[]`; the job `id` is omitted (a single job referenced by
+     * nothing — the server auto-assigns `job_N`).
+     *
+     * @internal Consumed by FF2b's `run()` (after a real upload) and by the
+     *   cross-language parity harness (with a fixed id). Not part of the
+     *   caller-facing fluent surface.
+     */
+    toWorkflowPayload(fileId: string): WorkflowCreatePayload;
+    /** The result-addressing key passed to `file()`, or undefined. */
+    key(): string | undefined;
+    /** The number of operations chained so far (introspection / tests). */
+    get stepCount(): number;
+    /**
+     * Execute the recipe end-to-end: upload the input (when required), create
+     * the workflow, await a terminal state (SSE with poll fallback), then
+     * resolve the produced downloads into a flat {@link RunResult}. Throws
+     * {@link GislTimeoutError} if `maxWait` elapses before terminal status.
+     *
+     * Mirrors the operation-first `OperationBuilder.run` (in `builder.ts`).
+     * Requires a client bound at construction time — `gisl().file(...)` wires
+     * it; a directly-constructed `Recipe` (e.g. in a lowering-only test) has no
+     * client and throws {@link GislConfigError}.
+     */
+    run(options?: {
+        maxWait?: string | number;
+        onProgress?: (event: ProgressEvent) => void;
+        signal?: AbortSignal;
+        pollIntervalMs?: number;
+    }): Promise<RunResult>;
+    private withStep;
+    private lowerStep;
+    private lowerCompressOptions;
+    private compressMediaHint;
+}
+export {};