@giveitsmaller/sdk 0.9.0 → 0.10.0

package/dist/errors.d.ts

@@ -1,4 +1,4 @@
-import type { AuthErrorResponse, BalanceExhaustedResponse, FeatureNotAvailableResponse, FeatureTierRestrictedResponse, ProbePendingResponse, TierRestrictionResponse, UploadDurationExceedsTierResponse, UploadSizeExceedsTierResponse, WorkflowExpiredResponse } from '@giveitsmaller/contracts/openapi';
+import type { AuthErrorResponse, AuthRejectionEnvelope, AuthRejectionEnvelopeErrorTypeEnum, BalanceExhaustedResponse, FeatureNotAvailableResponse, FeatureTierRestrictedResponse, ProbePendingResponse, TierRestrictionResponse, UploadDurationExceedsTierResponse, UploadSizeExceedsTierResponse, WorkflowExpiredResponse } from '@giveitsmaller/contracts/openapi';
 export declare class GislError extends Error {
     constructor(message: string);
 }
@@ -14,6 +14,21 @@ export interface GislApiErrorOptions {
     readonly locale?: string;
     readonly messageParams?: Record<string, unknown>;
     readonly payload?: unknown;
+    /**
+     * The response headers from the HTTP response that produced this error.
+     * Keys are LOWERCASED (HTTP header names are case-insensitive per RFC 9110,
+     * and `Headers.forEach` yields lowercased keys). Multi-value headers (e.g.
+     * `set-cookie`) are collapsed to a single comma-joined string — do NOT rely
+     * on this map for cookies.
+     */
+    readonly responseHeaders?: Record<string, string>;
+    /**
+     * The resolved language the server reported via the `Content-Language`
+     * response header. DISTINCT from `locale`, which is the body-envelope
+     * localisation tag (the I26 `ErrorEnvelope.locale` field); `contentLanguage`
+     * is the transport-level header the server echoes for content negotiation.
+     */
+    readonly contentLanguage?: string;
 }
 export declare class GislApiError extends GislError {
     readonly statusCode: number;
@@ -24,6 +39,19 @@ export declare class GislApiError extends GislError {
     readonly locale?: string;
     readonly messageParams?: Record<string, unknown>;
     readonly payload?: unknown;
+    /**
+     * Response headers from the HTTP response that produced this error, with
+     * LOWERCASED keys (RFC 9110 case-insensitive). Multi-value headers such as
+     * `set-cookie` are collapsed into a single comma-joined string — don't rely
+     * on this map for cookies.
+     */
+    readonly responseHeaders?: Record<string, string>;
+    /**
+     * The `Content-Language` response header value (the language the server
+     * actually resolved). DISTINCT from `locale`, which is the body-envelope
+     * localisation tag.
+     */
+    readonly contentLanguage?: string;
     constructor(statusCode: number, errorMessage: string, path?: string, details?: unknown, options?: GislApiErrorOptions);
 }
 /**
@@ -101,6 +129,23 @@ export declare class GislAuthError extends GislApiError {
     readonly payload: AuthErrorResponse;
     constructor(statusCode: number, errorMessage: string, payload: AuthErrorResponse, path?: string, extra?: Omit<GislApiErrorOptions, 'payload'>);
 }
+/**
+ * 422 Unprocessable Entity — domain rejection on auth side-effect endpoints
+ * (register / verify-email / api-keys duplicate-or-invalid; profile PATCH email
+ * unchanged). Flat `AuthRejectionEnvelope`, no `details[]`. Mirrors the PHP
+ * `Gisl\Sdk\Errors\GislAuthRejectionError`.
+ *
+ * `payload.errorType` is the auth-422 `oneOf` discriminator
+ * (`unprocessable_entity` or `email_same`); `errorType` re-exposes it directly
+ * for caller-side narrowing without unwrapping the typed payload. Distinct from
+ * `GislValidationError` (the `validation_error` branch of the same `oneOf`,
+ * which carries `details[]`).
+ */
+export declare class GislAuthRejectionError extends GislApiError {
+    readonly payload: AuthRejectionEnvelope;
+    readonly errorType: AuthRejectionEnvelopeErrorTypeEnum;
+    constructor(statusCode: number, errorMessage: string, payload: AuthRejectionEnvelope, path?: string, extra?: Omit<GislApiErrorOptions, 'payload'>);
+}
 /**
  * Discriminates the four upload-too-big shapes the server can return:
  * - `size_tier`        — 422 `upload_size_exceeds_tier` (typed payload present)
@@ -312,6 +357,19 @@ export declare class GislTimeoutError extends GislError {
 export declare class GislNetworkError extends GislError {
     constructor(message: string);
 }
+/**
+ * Internal control-flow marker (TDqmkWpX): the SSE event stream closed cleanly
+ * WITHOUT a terminal (`workflow_completed`/`failed`/`partially_failed`) event.
+ * Raised by {@link _consumeSseToTerminal} so the await-terminal callers can
+ * distinguish a benign server-side stream close (→ fall back to polling) from a
+ * genuine failure that must propagate (an `onProgress` callback throw, an API
+ * error, a caller abort). Mirrors the PHP `SseStreamEndedWithoutTerminal`
+ * sealed marker. Not part of the public error contract — never surfaced to a
+ * caller (the await-terminal path catches it internally and polls).
+ */
+export declare class SseEndedWithoutTerminal extends GislError {
+    constructor(message?: string);
+}
 export declare class GislAbortError extends GislError {
     constructor(message: string);
 }

package/dist/errors.js

@@ -13,6 +13,19 @@ export class GislApiError extends GislError {
     locale;
     messageParams;
     payload;
+    /**
+     * Response headers from the HTTP response that produced this error, with
+     * LOWERCASED keys (RFC 9110 case-insensitive). Multi-value headers such as
+     * `set-cookie` are collapsed into a single comma-joined string — don't rely
+     * on this map for cookies.
+     */
+    responseHeaders;
+    /**
+     * The `Content-Language` response header value (the language the server
+     * actually resolved). DISTINCT from `locale`, which is the body-envelope
+     * localisation tag.
+     */
+    contentLanguage;
     constructor(statusCode, errorMessage, path, details, options) {
         const prefix = path
             ? `API error ${statusCode} at ${path}`
@@ -28,6 +41,8 @@ export class GislApiError extends GislError {
             this.locale = options.locale;
             this.messageParams = options.messageParams;
             this.payload = options.payload;
+            this.responseHeaders = options.responseHeaders;
+            this.contentLanguage = options.contentLanguage;
         }
     }
 }
@@ -112,6 +127,26 @@ export class GislAuthError extends GislApiError {
         this.name = 'GislAuthError';
     }
 }
+/**
+ * 422 Unprocessable Entity — domain rejection on auth side-effect endpoints
+ * (register / verify-email / api-keys duplicate-or-invalid; profile PATCH email
+ * unchanged). Flat `AuthRejectionEnvelope`, no `details[]`. Mirrors the PHP
+ * `Gisl\Sdk\Errors\GislAuthRejectionError`.
+ *
+ * `payload.errorType` is the auth-422 `oneOf` discriminator
+ * (`unprocessable_entity` or `email_same`); `errorType` re-exposes it directly
+ * for caller-side narrowing without unwrapping the typed payload. Distinct from
+ * `GislValidationError` (the `validation_error` branch of the same `oneOf`,
+ * which carries `details[]`).
+ */
+export class GislAuthRejectionError extends GislApiError {
+    errorType;
+    constructor(statusCode, errorMessage, payload, path, extra) {
+        super(statusCode, errorMessage, path, undefined, buildOptionsWithPayload(payload, extra));
+        this.name = 'GislAuthRejectionError';
+        this.errorType = payload.errorType;
+    }
+}
 /**
  * A single class covering all three "upload exceeds a size/duration cap"
  * responses (422 size-tier, 422 duration-tier, 413 absolute).
@@ -335,6 +370,22 @@ export class GislNetworkError extends GislError {
         this.name = 'GislNetworkError';
     }
 }
+/**
+ * Internal control-flow marker (TDqmkWpX): the SSE event stream closed cleanly
+ * WITHOUT a terminal (`workflow_completed`/`failed`/`partially_failed`) event.
+ * Raised by {@link _consumeSseToTerminal} so the await-terminal callers can
+ * distinguish a benign server-side stream close (→ fall back to polling) from a
+ * genuine failure that must propagate (an `onProgress` callback throw, an API
+ * error, a caller abort). Mirrors the PHP `SseStreamEndedWithoutTerminal`
+ * sealed marker. Not part of the public error contract — never surfaced to a
+ * caller (the await-terminal path catches it internally and polls).
+ */
+export class SseEndedWithoutTerminal extends GislError {
+    constructor(message = 'SSE stream ended without a terminal event') {
+        super(message);
+        this.name = 'SseEndedWithoutTerminal';
+    }
+}
 export class GislAbortError extends GislError {
     constructor(message) {
         super(message);

package/dist/file-first.d.ts

@@ -15,6 +15,7 @@ import type { OperationDownload, WorkflowStatusResponse } from '@giveitsmaller/c
 import { OptimizeFor } from './generated/sdk_spec/enums.js';
 import type { PresetDefaults } from './ergonomic/presets/index.js';
 import type { WorkflowCreatePayload } from './types.js';
+import type { MergeOptions } from './merge.js';
 import { Handle } from './handle.js';
 /**
  * Streams a single output URL to a local path. The seam between the
@@ -224,6 +225,30 @@ export declare function projectMultiJobToRunResult(workflowId: string, finalStat
  * @internal Exported for the file-first `Handle`; not part of the public API.
  */
 export declare function isFanoutStatus(finalStatus: WorkflowStatusResponse): boolean;
+/**
+ * True when a terminal status describes a fluent `files([...]).merge(...)`
+ * combine — at least one job ref `merge` and every OTHER job ref is `src_{i}`
+ * (the ids the {@link MergedRecipe} lowering assigns). The data-driven seam that
+ * lets {@link Handle.wait}/{@link Handle.result} project ONLY the merged output
+ * — filtering the `src_*` passthrough plumbing — even after a
+ * `client.workflow(id)` reattach (no construction-time marker), matching
+ * {@link MergedRecipe.run}'s `ref === 'merge'` filter. Mutually exclusive with
+ * {@link isFanoutStatus} (a fan-out's refs are all `file-{i}`).
+ *
+ * @internal Exported for the file-first `Handle`; not part of the public API.
+ */
+export declare function isMergeStatus(finalStatus: WorkflowStatusResponse): boolean;
+/**
+ * True when a terminal status describes a fluent `files([...]).archive(...)`
+ * bundle — at least one job ref `archive` and every OTHER job ref is `src_{i}`
+ * (the ids the {@link ArchivedRecipe} lowering assigns). Lets
+ * {@link Handle.wait}/{@link Handle.result} project ONLY the archive output —
+ * filtering the `src_*` passthrough plumbing — even after a `client.workflow(id)`
+ * reattach. Mutually exclusive with {@link isFanoutStatus} / {@link isMergeStatus}.
+ *
+ * @internal Exported for the file-first `Handle`; not part of the public API.
+ */
+export declare function isArchiveStatus(finalStatus: WorkflowStatusResponse): boolean;
 /**
  * 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
@@ -251,6 +276,19 @@ export type FileInput = {
 export declare const fileInput: {
     readonly path: (path: string) => FileInput;
     readonly blob: (blob: Blob) => FileInput;
+    /**
+     * Reference an already-uploaded file by its upload id, instead of
+     * re-uploading bytes.
+     *
+     * Auth-ownership: an upload created by an **authenticated** caller is owned
+     * by that caller. If you reuse the id from a client configured with a
+     * *different* auth context (a different `apiKey` / session), workflow-create
+     * returns `404 upload_not_found` — the server enforces ownership (api
+     * PqpD9ySv). Reference an upload id only under the SAME auth that created it.
+     * The normal upload-then-create-in-one-client flow is consistent by
+     * construction (the same `Authorization` rides every request). Ownerless
+     * (anonymous-intake) uploads are unaffected.
+     */
     readonly uploadId: (fileId: string) => FileInput;
 };
 /** One step in a {@link Recipe}'s chain — an op kind + captured ergonomic args. */
@@ -427,6 +465,28 @@ export declare class FilesRecipe {
     }): FilesRecipe;
     /** Apply the same text watermark to every input. */
     textWatermark(text: string): FilesRecipe;
+    /**
+     * Combine the inputs into ONE output (N→1), in array order (FF3b). Returns a
+     * single-output {@link MergedRecipe} you chain further ops on
+     * (`files([...]).merge().compress()`). Reuses the operation-first
+     * {@link MergeOptions} for the merge-level options, so the wire shape matches
+     * `client.merge([...], options)`.
+     *
+     * `merge()` must be the FIRST op on `files([...])` — per-file ops before a
+     * combine (compress-each-then-merge) are a separate follow-up, rejected here
+     * with `GislConfigError` reason `pre_merge_ops_unsupported`.
+     */
+    merge(options?: MergeOptions): MergedRecipe;
+    /**
+     * Bundle the inputs into ONE archive (N→1, zip / tar.gz) — media-agnostic,
+     * inputs may mix types. Returns a terminal {@link ArchivedRecipe} (a zip is
+     * the final artefact — no post-bundle chain). `format` / `folderStructure` are
+     * optional; the server defaults to zip + flat.
+     *
+     * `archive()` must be the FIRST op on `files([...])` → `GislConfigError` reason
+     * `pre_archive_ops_unsupported` otherwise.
+     */
+    archive(options?: ArchiveRecipeOptions): ArchivedRecipe;
     /** The number of inputs in this fan-out (introspection / tests). */
     get inputCount(): number;
     /** The number of operations chained so far (introspection / tests). */
@@ -500,4 +560,177 @@ export declare class FilesRecipe {
     private baseRecipe;
     private withStep;
 }
+/**
+ * The single-output recipe you're in AFTER a fluent `files([...]).merge(...)`
+ * (FF3b). Merge collapses the N inputs into ONE output, so the per-file ops
+ * ({@link FilesRecipe.compress} etc.) no longer apply — instead this exposes the
+ * SAME chain ops as the single-file {@link Recipe}, applied to the merged
+ * result. `files([...]).merge().compress()` is the flagship case (example 14).
+ *
+ * **Lowering (one workflow):** each input is uploaded once and wrapped in its
+ * own single-input `passthrough` source job (`src_N`); the `merge` job consumes
+ * those via `job_output` inputs (array order = play order) and carries the merge
+ * op FIRST in its `operations[]`, followed by any post-combine ops (compress /
+ * convert / thumbnail) so they run on the merged output in the same job. The
+ * merge-level wire options reuse {@link wireMergeOptions} so a fluent merge
+ * lowers identically to the operation-first `client.merge()`.
+ *
+ * Immutable / clone-on-write like {@link Recipe} / {@link FilesRecipe}. Mirrors
+ * the PHP `MergedRecipe` in `packages/php/src/FileFirst/MergedRecipe.php`.
+ */
+export declare class MergedRecipe {
+    private readonly inputs;
+    private readonly mergeOptions;
+    private readonly postSteps;
+    private readonly presetDefaults?;
+    private readonly scopedPresetDefaults?;
+    private readonly client?;
+    constructor(inputs: readonly FileInput[], mergeOptions: MergeOptions, postSteps?: readonly RecipeStep[], presetDefaults?: PresetDefaults | undefined, scopedPresetDefaults?: PresetDefaults | undefined, client?: GislClient | undefined);
+    /** Reduce the merged output's size. See {@link Recipe.compress}. */
+    compress(optimize?: OptimizeFor): MergedRecipe;
+    /** Change the merged output's format. See {@link Recipe.convert}. */
+    convert(format: string): MergedRecipe;
+    /** Thumbnail the merged output. Omitted dimensions are dropped from the wire options. */
+    thumbnail(options?: {
+        width?: number;
+        height?: number;
+    }): MergedRecipe;
+    /**
+     * Lower to the merge DAG: one `passthrough` source job per input + one
+     * `merge` job whose `operations[]` is `[merge, ...post-combine ops]`. The
+     * merge job's `inputs[]` consume the source jobs via `job_output` in input
+     * (play) order.
+     *
+     * @internal Consumed by {@link run} (after uploading all inputs), {@link submit}
+     *   (with a webhook), and the cross-language parity harness (with fixed ids).
+     */
+    toWorkflowPayload(fileIds: readonly string[], callbackUrl?: string): WorkflowCreatePayload;
+    /** The number of inputs being combined (introspection / tests). */
+    get inputCount(): number;
+    /** The number of post-combine ops chained so far (introspection / tests). */
+    get stepCount(): number;
+    /**
+     * Execute end-to-end: upload every input, create the merge workflow, await a
+     * terminal state (SSE with poll fallback), then resolve ONLY the merged output
+     * into a {@link RunResult}. Throws {@link GislTimeoutError} on `maxWait`.
+     *
+     * Requires a client bound at construction time — `gisl().files(...).merge(...)`
+     * wires it; a directly-constructed `MergedRecipe` throws {@link GislConfigError}.
+     * Mirrors the single-file {@link Recipe.run}.
+     */
+    run(options?: {
+        maxWait?: string | number;
+        onProgress?: (event: ProgressEvent) => void;
+        signal?: AbortSignal;
+        pollIntervalMs?: number;
+    }): Promise<RunResult>;
+    /**
+     * Fire-and-forget: upload + create the merge workflow (wiring `webhook` into
+     * `callback_url` when given), return a client-bound {@link Handle}. Does NOT
+     * wait for terminal status. Mirrors {@link Recipe.submit}.
+     */
+    submit(webhook?: string): Promise<Handle>;
+    /**
+     * Upload every input (verbatim for a pre-uploaded id; uploading a path / blob
+     * otherwise, emitting `{phase:'upload'}` progress) then create ONE merge
+     * workflow. Rejects fewer than 2 inputs BEFORE any upload fires. Shared first
+     * half of {@link run} + {@link submit}.
+     */
+    private _uploadAllAndCreate;
+    /**
+     * Reject an invalid combine BEFORE any upload fires — mirrors the operation-
+     * first `MergeBuilder.planSequence()` bounds so a typo'd merge costs no
+     * bandwidth: 2–10 inputs (merge schema `min/max_inputs`), and an image merge
+     * must carry an explicit `output_type` (the server rejects image merges
+     * without one). Shared by {@link run} + {@link submit} via
+     * {@link _uploadAllAndCreate}.
+     */
+    private validatePreUpload;
+    /**
+     * Lower the post-combine chain by composing a single-file {@link Recipe} over a
+     * synthetic input whose extension matches the merged OUTPUT media — so
+     * `compress(optimize)` resolves the correct preset for the merged result (it
+     * needs a media hint, which a merge output carries no filename for). Reuses
+     * Recipe's `lowerStep` rather than duplicating it.
+     */
+    private lowerPostSteps;
+    /**
+     * The merged-output media. Honours an explicit {@link MergeOptions.mediaKind};
+     * otherwise infers from the first PATH input's extension (mirrors
+     * {@link MergeBuilder}); defaults to video.
+     */
+    private inferMediaKind;
+    private outputExtensionFor;
+    private withStep;
+}
+/**
+ * Options for a fluent `files([...]).archive(...)` bundle. Both fields are
+ * optional — the server defaults `format` to `zip` and `folderStructure` to
+ * `flat` (archive op schema). Mirrors the PHP `ArchivedRecipe` ctor params.
+ */
+export interface ArchiveRecipeOptions {
+    /** Archive container format. */
+    readonly format?: 'zip' | 'tar.gz';
+    /** `flat` = all files at the top level; `by_job` = a subfolder per source. */
+    readonly folderStructure?: 'flat' | 'by_job';
+}
+/**
+ * The single-output recipe you're in AFTER a fluent `files([...]).archive(...)`
+ * (FF3b). Archive bundles the N inputs into ONE downloadable archive (zip /
+ * tar.gz) — media-agnostic, inputs may mix types. Unlike {@link MergedRecipe},
+ * archive is TERMINAL: a zip is the final artefact, so there is no post-bundle
+ * chain — this exposes only `run()` / `submit()`.
+ *
+ * **Lowering (one workflow):** each input is uploaded once and wrapped in its
+ * own single-input `passthrough` source job (`src_N`); the `archive` job
+ * consumes those via `job_output` inputs (array order = entry order) and carries
+ * the single `archive` op. The archive job's id is `archive`, so {@link RunResult}
+ * projects ONLY its output. Mirrors the PHP `ArchivedRecipe`.
+ */
+export declare class ArchivedRecipe {
+    private readonly inputs;
+    private readonly options;
+    private readonly client?;
+    constructor(inputs: readonly FileInput[], options?: ArchiveRecipeOptions, client?: GislClient | undefined);
+    /** The number of inputs being bundled (introspection / tests). */
+    get inputCount(): number;
+    /**
+     * Lower to the archive DAG: one `passthrough` source job per input + one
+     * `archive` job consuming them via `job_output`.
+     *
+     * @internal Consumed by {@link run} / {@link submit} (after uploading) and the
+     *   cross-language parity harness (with fixed ids).
+     */
+    toWorkflowPayload(fileIds: readonly string[], callbackUrl?: string): WorkflowCreatePayload;
+    /**
+     * Execute end-to-end: upload every input, create the archive workflow, await a
+     * terminal state (SSE with poll fallback), then resolve ONLY the archive output
+     * into a {@link RunResult}. Throws {@link GislTimeoutError} on `maxWait`.
+     * Requires a client bound via `gisl().files(...).archive(...)`.
+     */
+    run(options?: {
+        maxWait?: string | number;
+        onProgress?: (event: ProgressEvent) => void;
+        signal?: AbortSignal;
+        pollIntervalMs?: number;
+    }): Promise<RunResult>;
+    /**
+     * Fire-and-forget: upload + create the archive workflow (wiring `webhook` into
+     * `callback_url` when given), return a client-bound {@link Handle}. Mirrors
+     * {@link MergedRecipe.submit}.
+     */
+    submit(webhook?: string): Promise<Handle>;
+    private _uploadAllAndCreate;
+    /**
+     * Reject an invalid bundle BEFORE any upload fires — the archive schema allows
+     * 2–50 inputs (`min/max_inputs`), so a typo'd bundle costs no bandwidth.
+     */
+    private validatePreUpload;
+    /**
+     * Project the archive options into the wire shape. Both fields are optional
+     * (the server defaults `format` to zip and `folder_structure` to flat), so an
+     * omitted option is dropped rather than sent.
+     */
+    private wireArchiveOptions;
+}
 export {};