@giveitsmaller/sdk 0.21.0 → 0.25.0

package/dist/errors.js

@@ -172,6 +172,23 @@ export class GislLongFormConcurrencyError extends GislApiError {
         super(statusCode, errorMessage, path, undefined, buildOptionsWithPayload(payload, extra));
         this.name = 'GislLongFormConcurrencyError';
     }
+    /**
+     * ALWAYS `false`, overriding the base 429-implies-retryable heuristic
+     * (UO1xYecu). This 429 is not a rate limit: it carries no `Retry-After` and
+     * clears only when an in-flight long-form workflow finishes, so a back-off
+     * retries into a wall that no amount of waiting-then-retrying opens. The base
+     * accessor reported `true` purely from the status, contradicting this class's
+     * own documented handling ("wait on completion or upgrade — do NOT back off")
+     * and instructing the one recovery that cannot work.
+     *
+     * Overridden per-class rather than via a code table because this is the only
+     * such code today; the general fix — an explicit taxonomy verdict outranking
+     * the status heuristic — arrives with the `error-taxonomy.yaml` `retryable`
+     * enum (contracts `plwcAqBr`), tracked on UO1xYecu.
+     */
+    get retryable() {
+        return false;
+    }
     /** The pricing / upgrade deep link (`links.upgrade`), or `undefined` when absent. */
     get upgradeUrl() {
         return this.payload.links?.upgrade;
@@ -381,6 +398,34 @@ export class GislMissingCredentialsError extends GislConfigError {
         this.name = 'GislMissingCredentialsError';
     }
 }
+/**
+ * `streamEvents` was called on a client whose configuration has **no declared
+ * SSE stream host**. Local-only — thrown before any I/O.
+ *
+ * ⚠️ **THIS ERROR IS A CONTROL, NOT A DEFECT.** The stream lives on a second
+ * host, and the SDK will not guess it from `baseUrl`. Deriving `stream.*` from
+ * `api.*` by string surgery is a *convention*, and a convention is precisely
+ * what put production on the gateway path: the frontend's prod build had no
+ * stream host configured, fell back to the API host silently, and the failure
+ * was invisible until it was measured. Raising here is the loud version of
+ * that same situation.
+ *
+ * Both named environments resolve as of contracts `v2.195.0` (#410), which
+ * declared the production stream host. This now fires only for a
+ * configuration nothing declares — e.g. a bare `baseUrl` with no
+ * `environment` and no `streamBaseUrl`.
+ *
+ * Recover by passing `{streamBaseUrl}` to `gisl.create()` / `new GislClient()`,
+ * setting `GISL_STREAM_BASE_URL`, or constructing with an `{environment}` that
+ * declares one. `run()` does NOT surface this error — it treats an undeclared
+ * stream host as "SSE unavailable for this configuration" and polls instead.
+ */
+export class GislStreamHostNotDeclaredError extends GislConfigError {
+    constructor(message) {
+        super(message);
+        this.name = 'GislStreamHostNotDeclaredError';
+    }
+}
 /**
  * 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.
@@ -506,13 +551,71 @@ export class GislTimeoutError extends GislError {
     }
 }
 /**
- * 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`).
+ * A `mapEach` fan-out timed out mid-batch — the deadline elapsed either while a
+ * child was still running (the common case) or cleanly between child runs. The
+ * parent and some children have ALREADY completed, so re-running the whole batch
+ * re-does finished work. This carries their ids so the caller can poll them (via
+ * `client.getWorkflowStatus` / `getWorkflowDownloads`) to recover the finished
+ * work and re-run ONLY the children that were never created.
+ *
+ * Subclasses {@link GislTimeoutError}, so an existing
+ * `catch (e) { if (e instanceof GislTimeoutError) … }` still catches it. The
+ * inherited `workflowId` carries the IN-FLIGHT child — the one that was running
+ * when the deadline elapsed (a child's own timeout, the common path) — or stays
+ * `undefined` when the deadline elapsed cleanly BETWEEN children (no in-flight
+ * child). To recover, poll `workflowId` (if set) + {@link parentWorkflowId} +
+ * {@link completedWorkflowIds}, then re-run only the children that never started.
+ *
+ * NOTE on double-charge: the server-side create-dedupe (DSxwCetg) is what
+ * prevents a byte-identical child re-create from settling a SECOND charge within
+ * the dedup window; this error's job is efficient RECOVERY (skip the completed
+ * work) + defense-in-depth, not the sole charge guard.
+ */
+export class GislFanOutTimeoutError extends GislTimeoutError {
+    /** The child workflows that completed before the deadline elapsed. */
+    completedWorkflowIds;
+    /** The parent workflow, which ran to completion before the fan-out began. */
+    parentWorkflowId;
+    constructor(message, opts) {
+        // The inherited workflowId is the in-flight child (or undefined between children).
+        super(message, opts.workflowId);
+        this.name = 'GislFanOutTimeoutError';
+        this.completedWorkflowIds = [...opts.completedWorkflowIds];
+        this.parentWorkflowId = opts.parentWorkflowId === '' ? undefined : opts.parentWorkflowId;
+        if (opts.cause !== undefined) {
+            this.cause = opts.cause;
+        }
+    }
+}
+/**
+ * Base for every failure that happened **off the contract envelope** — the
+ * request did not come back as a typed API error, it came back (or failed to)
+ * at the transport or raw-HTTP level. Subclasses `GislError` rather than
+ * `GislApiError` because there is no error envelope to carry.
+ *
+ * ⚠️ **NEVER THROWN DIRECTLY — it is a hierarchy node, not an error code
+ * (`t2qCrjdr`).** Everything that used to throw it now throws
+ * {@link GislTransportError} or {@link GislDownloadHttpError}, because the two
+ * cases cannot share one honest answer to "should I retry this?":
+ *
+ * | case | retry? |
+ * |---|---|
+ * | DNS / TCP / TLS / mid-stream disconnect | **yes** — transient by nature |
+ * | a `404` on a signed download URL | **no** — permanent, retrying burns time |
+ *
+ * `retryable: true` would recommend retrying a permanent failure and
+ * `retryable: false` would discourage retrying a genuine transient one, so
+ * contracts correctly refused to declare this class in
+ * `sdk-spec/error-taxonomy.yaml` at all. The fix is the split, not a caveat in
+ * a description field: **a claim must hold on every path that reaches it.**
+ *
+ * **Kept as the base ON PURPOSE, so this is not a breaking change.** Every
+ * existing `catch (e) { if (e instanceof GislNetworkError) … }` — including the
+ * SSE poll-fallback in `builder.ts` / `merge.ts` / `handle.ts` /
+ * `file-first.ts` — keeps catching exactly what it caught before. Narrow to a
+ * subclass only where you actually need to tell the two apart.
+ *
+ * Mirrors the PHP `Gisl\Sdk\Errors\GislNetworkError`.
  */
 export class GislNetworkError extends GislError {
     constructor(message) {
@@ -520,6 +623,99 @@ export class GislNetworkError extends GislError {
         this.name = 'GislNetworkError';
     }
 }
+/**
+ * The transport could not deliver a usable response: DNS, TCP, TLS, a
+ * mid-stream disconnect, a `fetch` rejection, or a 2xx that arrived with no
+ * body at all. **Always retryable** — nothing about these says the request was
+ * wrong, only that it did not get through.
+ *
+ * The empty-body case lives here rather than with
+ * {@link GislDownloadHttpError} deliberately: the server said 2xx, so it is not
+ * an HTTP-level refusal — a response that promised bytes and delivered none is
+ * a delivery failure, and retrying is the right advice.
+ *
+ * The concrete file-first `Downloader` raises this when an output URL cannot be
+ * read (a destination-WRITE failure is `GislSinkError` reason `write_failed`).
+ */
+export class GislTransportError extends GislNetworkError {
+    constructor(message) {
+        super(message);
+        this.name = 'GislTransportError';
+    }
+    /**
+     * Always `true`. The request did not get through; nothing about that says it
+     * was wrong, so retrying is the correct advice.
+     *
+     * Present as a real accessor rather than only as prose — an unbacked claim in
+     * a docblock is the exact defect `t2qCrjdr` exists to remove, and shipping
+     * the split without it would have reproduced it one level down.
+     */
+    get retryable() {
+        return true;
+    }
+}
+/**
+ * The request was never put on the wire because the client refused to send it —
+ * a malformed URI or an otherwise unsendable request. **Never retryable:**
+ * re-issuing the identical request fails identically, so backing off only
+ * wastes the caller's deadline.
+ *
+ * ⚠️ **THE TWO LANGUAGES DETECT THIS DIFFERENTLY, AND TS DETECTS LESS.** PSR-18
+ * distinguishes a network failure (`NetworkExceptionInterface`) from an
+ * unsendable request (`RequestExceptionInterface`), so the PHP SDK classifies
+ * every such failure. `fetch` surfaces both as an indistinguishable
+ * `TypeError`, so the TS SDK can only catch the cases it can see BEFORE the
+ * call — today, a URL that does not parse (`http-downloader`). A `fetch`
+ * rejection is still reported as {@link GislTransportError}, because guessing
+ * would put a permanent failure back in the retryable bucket, which is the very
+ * thing this split removed.
+ *
+ * So: same class, same meaning, same `retryable` in both SDKs — narrower
+ * detection in TypeScript. Stated here because a cross-language consumer would
+ * otherwise reasonably assume parity of COVERAGE from parity of TYPE.
+ */
+export class GislRequestNotSentError extends GislNetworkError {
+    constructor(message) {
+        super(message);
+        this.name = 'GislRequestNotSentError';
+    }
+    /** Always `false` — the request never left, and re-sending it will not change that. */
+    get retryable() {
+        return false;
+    }
+}
+/**
+ * A download URL answered with a **non-2xx status**. The server was reached and
+ * replied; it simply refused. Distinct from {@link GislTransportError} because
+ * retrying is usually pointless — and `retryable` says so honestly, derived
+ * from the status rather than fixed for the class.
+ *
+ * `status` is carried as a field so a consumer distinguishing a permanent `404`
+ * from a transient `503` does not have to parse the message string — the second
+ * half of `t2qCrjdr`.
+ *
+ * Raised on result-download fetches (signed URLs), NOT on GISL-API calls: an
+ * API non-2xx carries a contract error envelope and surfaces as the matching
+ * {@link GislApiError} subclass instead.
+ */
+export class GislDownloadHttpError extends GislNetworkError {
+    /** The HTTP status the download URL responded with. */
+    status;
+    constructor(message, status) {
+        super(message);
+        this.name = 'GislDownloadHttpError';
+        this.status = status;
+    }
+    /**
+     * Whether retrying this download could plausibly succeed. Derived from the
+     * status by the same rule the API errors use (`408` / `429` / `5xx`), so a
+     * `404` reports `false` and a `503` reports `true` — the distinction the
+     * unsplit class could not express.
+     */
+    get retryable() {
+        return isApiRetryableStatus(this.status);
+    }
+}
 /**
  * Internal control-flow marker (TDqmkWpX): the SSE event stream closed cleanly
  * WITHOUT a terminal (`workflow_completed`/`failed`/`partially_failed`) event.

package/dist/file-first.js

@@ -9,12 +9,12 @@
  *
  * Mirrors `packages/php/src/FileFirst/*`.
  */
-import { GislConfigError, GislItemFailedError, GislNetworkError, GislNoSuchKeyError, GislSinkError, GislTimeoutError, SseEndedWithoutTerminal } from './errors.js';
+import { GislConfigError, GislItemFailedError, GislNetworkError, GislNoSuchKeyError, GislSinkError, GislStreamHostNotDeclaredError, GislTimeoutError, SseEndedWithoutTerminal } from './errors.js';
 import { _detectCompressMedia, _detectAudioLossless, _consumeSseToTerminal, _pollToTerminal, _parseMaxWait, _checkAborted, _cappedProbeTimeoutMs, } from './builder.js';
 import { LazyHttpDownloader } from './lazy-downloader.js';
 import { resolveCompressOptions, } from './ergonomic/preset_resolver.js';
 import { validateVerbOptions, assertThumbnailDimensions } from './ergonomic/option_validation.js';
-import { resolveOutputRoute, tokenForMime, tokenForPath, isPlannedValue, isUnknownEnumValue, FACADE_MANAGED_OUTPUTS, } from './ergonomic/image_output_routes.js';
+import { resolveOutputRoute, tokenForMime, tokenForPath, isPlannedValue, isUnknownEnumValue, dependsOnViolation, FACADE_MANAGED_OUTPUTS, } from './ergonomic/image_output_routes.js';
 import { OptimizeFor } from './generated/sdk_spec/enums.js';
 import { uploadSource, jobOutputSource } from './types.js';
 // Value import used only at call-time (inside MergedRecipe.toWorkflowPayload),
@@ -629,7 +629,17 @@ async function _awaitTerminal(client, args) {
             // unexpected — MUST propagate; re-issuing the same doomed request via poll
             // would mask it. Mirrors the PHP BuilderInternals::awaitTerminal sealed-
             // marker discipline.
-            if (!(err instanceof SseEndedWithoutTerminal || err instanceof GislNetworkError)) {
+            if (!(err instanceof SseEndedWithoutTerminal ||
+                err instanceof GislNetworkError ||
+                // VUozk5Bc: no stream host is DECLARED for this configuration (a
+                // configuration nothing declares; both named environments resolve as of
+                // contracts v2.195.0). That is not a failure to recover from,
+                // it is SSE being unavailable here, and polling is a working
+                // transport. Failing hard instead would strand every caller on a host
+                // nobody has declared yet. A DIRECT `streamEvents` caller still gets
+                // the hard error — they asked for the stream specifically; a `run()`
+                // caller asked for a result.
+                err instanceof GislStreamHostNotDeclaredError)) {
                 throw err;
             }
         }
@@ -1101,7 +1111,7 @@ export class Recipe {
             if (requested !== undefined && FACADE_MANAGED_OUTPUTS.includes(requested)) {
                 const facade = { output_format: requested };
                 for (const [key, value] of Object.entries(step.options)) {
-                    if (key === 'output_format' || value === undefined)
+                    if (key === 'output_format' || value === undefined || value === null)
                         continue;
                     if (key !== 'quality') {
                         throw new GislConfigError(`output(): '${key}' needs a detectable input format to route; reference the file by ` +
@@ -1122,7 +1132,9 @@ export class Recipe {
         }
         const wireOptions = { output_format: resolved.outputFormatWire };
         for (const [key, value] of Object.entries(step.options)) {
-            if (key === 'output_format' || value === undefined)
+            // Drop a null value (as PHP does) so a null option never reaches the wire
+            // and is treated as absent by the depends_on gate — full null parity (codex).
+            if (key === 'output_format' || value === undefined || value === null)
                 continue;
             if (resolved.planned.has(key)) {
                 throw new GislConfigError(`output(): '${key}' is advertised but not available yet on the ${resolved.route} route ` +
@@ -1147,6 +1159,28 @@ export class Recipe {
             }
             wireOptions[key] = value;
         }
+        // quality_preset's contract `depends_on: { encoding_mode: auto_quality }`
+        // (86gAu5Tr) — infer the mode when the caller set NONE so the preset forms a
+        // VALID request. SAME_FORMAT only: encoding_mode is a compress optimiser and
+        // quality_preset isn't honored on a format_change. An explicitly-conflicting
+        // mode is rejected by the general depends_on gate below.
+        if (resolved.route === 'same_format' &&
+            wireOptions.quality_preset !== undefined &&
+            wireOptions.encoding_mode === undefined) {
+            wireOptions.encoding_mode = 'auto_quality';
+        }
+        // General contract `depends_on` validation (ehHU08Hu), scoped per route: the
+        // universal fit→width|height dep runs on BOTH routes (identical in compress +
+        // convert); the encoding_mode-family deps run on same_format only. Subsumes
+        // the 86gAu5Tr auto_quality gate plus target_size_bytes-without-target_size,
+        // fit-without-width/height, and any future compress-image depends_on.
+        const dependency = dependsOnViolation(wireOptions, resolved.route);
+        if (dependency !== undefined) {
+            throw new GislConfigError(dependency.message, {
+                reason: 'invalid_option_combination',
+                conflictingFields: [...dependency.conflictingFields],
+            });
+        }
         return { type: resolved.sourceOp, options: wireOptions };
     }
     /**
@@ -1466,9 +1500,22 @@ function _validateWatermarkOverlay(overlay) {
     }
 }
 function _lowerWatermarkOp(wireOp, options) {
-    // Watermark options (anchor/opacity/margin_x/margin_y/overlay_width, or the
-    // multi-overlay overlays[] stack) are already wire keys; empty options omit
-    // the `options` key (byte-identical to PHP).
+    // `overlays[]` (the multi-overlay stack) is a live contract option but is NOT
+    // reachable through watermark(): the facade composites exactly ONE overlay —
+    // the positional `overlay` (wire source src_1) — so overlays[1..] reference
+    // sources it cannot create, any entry is invalid on a non-image base, and the
+    // contract's `minItems: 1` makes an empty array invalid too. Reject it here at
+    // lowering (mutation-safe — reads the FINAL options, catching a post-watermark()
+    // `opts.overlays = [...]`) and point callers at the single-overlay knobs.
+    // Real multi-overlay stacking is a future feature (Vbbdq9C4).
+    if (options.overlays !== undefined) {
+        throw new GislConfigError("watermark(): 'overlays[]' (multi-overlay stacking) is not supported — watermark() composites a " +
+            'single overlay (the positional overlay argument). Use the top-level anchor / opacity / margin_x / ' +
+            'margin_y / overlay_width options to place it. Multi-overlay stacking is a future feature.', { reason: 'overlays_unsupported', conflictingFields: ['overlays'] });
+    }
+    // The remaining watermark options (anchor/opacity/margin_x/margin_y/
+    // overlay_width) are already wire keys; empty options omit the `options` key
+    // (byte-identical to PHP).
     const wire = { ...options };
     return Object.keys(wire).length === 0 ? { type: wireOp } : { type: wireOp, options: wire };
 }
@@ -1489,6 +1536,14 @@ function _lowerWatermarkOp(wireOp, options) {
  */
 async function _uploadInputsAndCreate(client, inputs, toPayload, opts) {
     const { webhook, deadline, onProgress, signal, probeBeforeCreate, probeTimeoutMs, uploadsLabel, workflowLabel } = opts;
+    // Preflight: lower the composed chains with placeholder ids so a route-invalid
+    // option (or any lowering-time gate — overlays, sole_op split, route/enum) in
+    // ANY input's chain — a watermark base/overlay, a merge/archive member — throws
+    // BEFORE we spend a single upload byte. The multi-input analog of the
+    // single-input Recipe.assertOperationsLowerable preflight (0azjb6Rg); mirrors
+    // PHP. The placeholder ids never reach the wire — the payload is discarded
+    // (T3ltXsou). toWorkflowPayload is pure, so re-lowering at create is cheap.
+    toPayload(inputs.map((_, i) => `preflight_${i}`));
     const fileIds = [];
     // Track each freshly-uploaded input's probe-gate inputs (a pre-uploaded id
     // carries no local mime/size, so it is excluded — never probed).

package/dist/generated/sdk_spec/errors.d.ts

@@ -1,4 +1,4 @@
-export type ErrorCode = "missing_credentials" | "feature_requires_auth" | "undeclared_asset" | "unused_asset" | "per_input_options_not_supported" | "chain_cardinality_mismatch" | "multipart_part_invalid" | "multipart_part_count_exceeded" | "timeout" | "aborted" | "validation_failed" | "validation_error" | "cyclic_workflow_edges" | "workflow_edge_references_unknown_job" | "reserved_job_id_pattern" | "cyclic_job_output_source_graph" | "auth_failed" | "feature_tier_restricted" | "tier_restriction" | "multipart_session_ownership" | "multipart_session_auth_required" | "multipart_session_not_found" | "upload_not_found" | "workflow_expired" | "balance_exhausted" | "feature_not_available" | "upload_size_exceeds_tier" | "upload_duration_exceeds_tier" | "probe_pending" | "requires_reencode" | "invalid_options" | "invalid_combination" | "missing_dependency" | "unsupported_value" | "type_mismatch" | "image_dimensions_too_large" | "upload_failed" | "workflow_failed";
+export type ErrorCode = "missing_credentials" | "feature_requires_auth" | "undeclared_asset" | "unused_asset" | "per_input_options_not_supported" | "chain_cardinality_mismatch" | "multipart_part_invalid" | "multipart_part_count_exceeded" | "timeout" | "aborted" | "validation_failed" | "validation_error" | "cyclic_workflow_edges" | "workflow_edge_references_unknown_job" | "reserved_job_id_pattern" | "cyclic_job_output_source_graph" | "auth_failed" | "feature_tier_restricted" | "tier_restriction" | "multipart_session_ownership" | "multipart_session_auth_required" | "multipart_session_not_found" | "upload_not_found" | "workflow_expired" | "balance_exhausted" | "feature_not_available" | "upload_size_exceeds_tier" | "upload_duration_exceeds_tier" | "probe_pending" | "requires_reencode" | "invalid_options" | "invalid_combination" | "missing_dependency" | "unsupported_value" | "type_mismatch" | "image_dimensions_too_large" | "upload_failed" | "workflow_failed" | "sse_connection_limit_exceeded" | "sse_capacity_exhausted" | "long_form_concurrency_limit_exceeded" | "unprocessable_entity" | "email_same" | "config_error" | "bundle_already_archived" | "fan_out_timeout" | "no_such_key" | "result_not_ready" | "sink_error" | "item_failed";
 export type ErrorCategory = 'api' | 'config' | 'network' | 'auth' | 'validation' | 'chain';
 export type ErrorStatus = 'wired' | 'planned';
 export interface ErrorEntry {

package/dist/generated/sdk_spec/errors.js

@@ -377,7 +377,7 @@ export const ERROR_CODES = Object.freeze({
         status: "wired",
         httpStatus: 422,
         retryable: true,
-        sdkClass: "GislApiError",
+        sdkClass: "GislProbePendingError",
         description: "422 on workflow create — upload probing not yet complete; retry after the upload finishes probing. Wire `error_type: \"probe_pending\"`.",
         metadataSchema: Object.freeze({
             "jobRef": "string",
@@ -506,6 +506,169 @@ export const ERROR_CODES = Object.freeze({
             "jobErrors": "array",
         }),
     }),
+    "sse_connection_limit_exceeded": Object.freeze({
+        code: "sse_connection_limit_exceeded",
+        category: "api",
+        source: "ErrorEnvelope.error",
+        status: "planned",
+        httpStatus: 429,
+        retryable: true,
+        sdkClass: "GislSseConnectionLimitError",
+        description: "429 — the CALLER's own concurrent event-stream allowance is exhausted. Same semantics as the tier long-form concurrency limit and therefore the same status. NOT for a global-capacity refusal; see sse_capacity_exhausted.",
+        metadataSchema: Object.freeze({
+            "openStreams": "integer",
+            "maxStreams": "integer",
+        }),
+    }),
+    "sse_capacity_exhausted": Object.freeze({
+        code: "sse_capacity_exhausted",
+        category: "api",
+        source: "ErrorEnvelope.error",
+        status: "planned",
+        httpStatus: 503,
+        retryable: true,
+        sdkClass: "GislSseCapacityError",
+        description: "503 — GLOBAL event-stream capacity is exhausted, and it says nothing about this caller. A caller who has opened no streams can receive it. ⚠️ `EventSource` does not expose the HTTP status to page script, so a browser client cannot distinguish this from 500 — the status serves non-browser clients, proxies and observability.",
+        metadataSchema: Object.freeze({
+            "links": "object",
+        }),
+    }),
+    "long_form_concurrency_limit_exceeded": Object.freeze({
+        code: "long_form_concurrency_limit_exceeded",
+        category: "api",
+        source: "ErrorEnvelope.error",
+        status: "wired",
+        httpStatus: 429,
+        retryable: false,
+        sdkClass: "GislLongFormConcurrencyError",
+        description: "429 — the caller's tier long-form concurrency allowance is exhausted. Wire value is UPPERCASE `LONG_FORM_CONCURRENCY_LIMIT_EXCEEDED` (api.yaml:1995); this file's `code:` follows the taxonomy's lowercase convention. Dispatched on the machine `error` code, NOT on the status: a generic infra rate-limit 429 carries a different/absent code and falls through to base GislApiError where retryAfterSeconds applies. Do not widen this entry to the status.",
+        metadataSchema: Object.freeze({
+            "currentTier": "string",
+            "maxDurationSeconds": "number",
+        }),
+    }),
+    "unprocessable_entity": Object.freeze({
+        code: "unprocessable_entity",
+        category: "auth",
+        source: "error_type",
+        status: "wired",
+        httpStatus: 422,
+        retryable: false,
+        sdkClass: "GislAuthRejectionError",
+        description: "422 on an auth-side-effect endpoint (register / verify-email / api-keys) — the request was well-formed but rejected on domain grounds. Dispatched on MEMBERSHIP of AuthRejectionEnvelope.error_type, per ADR-0019.",
+        metadataSchema: Object.freeze({
+            "errorType": "string",
+        }),
+    }),
+    "email_same": Object.freeze({
+        code: "email_same",
+        category: "auth",
+        source: "error_type",
+        status: "wired",
+        httpStatus: 422,
+        retryable: false,
+        sdkClass: "GislAuthRejectionError",
+        description: "422 on profile PATCH — the submitted email matches the current one, so there is nothing to change. Same envelope and sdkClass as unprocessable_entity; separate row because the wire value differs.",
+        metadataSchema: Object.freeze({
+            "errorType": "string",
+        }),
+    }),
+    "config_error": Object.freeze({
+        code: "config_error",
+        category: "config",
+        source: "SDK_local",
+        status: "wired",
+        httpStatus: null,
+        retryable: false,
+        sdkClass: "GislConfigError",
+        description: "Client-side configuration rejected before any request — thrown directly (preset resolver, output() gates), not only as a base class. `reason` carries the discriminator: `unknown_field` and `type_mismatch` are values of THIS field and deliberately have no rows of their own.",
+        metadataSchema: Object.freeze({
+            "reason": "string",
+            "conflictingFields": "array",
+            "resolvedSnapshot": "object",
+            "suggestion": "string",
+        }),
+    }),
+    "bundle_already_archived": Object.freeze({
+        code: "bundle_already_archived",
+        category: "config",
+        source: "SDK_local",
+        status: "planned",
+        httpStatus: null,
+        retryable: false,
+        sdkClass: "GislBundleAlreadyArchivedError",
+        description: "PLANNED — not reachable in any shipped build. Raised when a bundle operation targets an already-archived bundle, once `.bundle()` ships. Do not write handler code against this yet.",
+        metadataSchema: Object.freeze({}),
+    }),
+    "fan_out_timeout": Object.freeze({
+        code: "fan_out_timeout",
+        category: "network",
+        source: "SDK_local",
+        status: "wired",
+        httpStatus: null,
+        retryable: true,
+        sdkClass: "GislFanOutTimeoutError",
+        description: "A fan-out deadline elapsed before all children finished. The three metadata fields are the reason this is declared separately from GislTimeoutError: completedWorkflowIds are the children that DID finish, parentWorkflowId ran to completion before the fan-out began, and the inherited workflowId is the in-flight child — absent on a clean between-children timeout.",
+        metadataSchema: Object.freeze({
+            "completedWorkflowIds": "array",
+            "parentWorkflowId": "string",
+            "workflowId": "string",
+        }),
+    }),
+    "no_such_key": Object.freeze({
+        code: "no_such_key",
+        category: "chain",
+        source: "SDK_local",
+        status: "wired",
+        httpStatus: null,
+        retryable: false,
+        sdkClass: "GislNoSuchKeyError",
+        description: "The caller asked for a mapEach result key that does not exist in the output. NOTE the key itself is NOT captured in metadata today — it is interpolated into the message only, so consumers cannot branch on which key was missing.",
+        metadataSchema: Object.freeze({}),
+    }),
+    "result_not_ready": Object.freeze({
+        code: "result_not_ready",
+        category: "validation",
+        source: "SDK_local",
+        status: "wired",
+        httpStatus: null,
+        retryable: true,
+        sdkClass: "GislResultNotReadyError",
+        description: "The caller read a result before the workflow reached a terminal state. `state` carries the non-terminal status observed.",
+        metadataSchema: Object.freeze({
+            "workflowId": "string",
+            "state": "string",
+        }),
+    }),
+    "sink_error": Object.freeze({
+        code: "sink_error",
+        category: "config",
+        source: "SDK_local",
+        status: "wired",
+        httpStatus: null,
+        retryable: false,
+        sdkClass: "GislSinkError",
+        description: "A caller-supplied output sink could not be used. Branch on `reason` — the values span both caller setup (invalid_directory, duplicate_filename) and runtime write outcomes (write_failed, partial_failure), so the category is a best fit rather than an exact one.",
+        metadataSchema: Object.freeze({
+            "reason": "string",
+        }),
+    }),
+    "item_failed": Object.freeze({
+        code: "item_failed",
+        category: "api",
+        source: "SDK_local",
+        status: "wired",
+        httpStatus: null,
+        retryable: false,
+        sdkClass: "GislItemFailedError",
+        description: "CARRIED, not thrown — an entry in a per-item failed[] collection describing one item's server-side failure. `errorCode` carries the server's own code where present; prefer branching on that over this entry.",
+        metadataSchema: Object.freeze({
+            "key": "string",
+            "state": "string",
+            "errorMessage": "string",
+            "errorCode": "string",
+        }),
+    }),
 });
 export const ERROR_CATEGORIES = Object.freeze({
     api: Object.freeze([
@@ -522,20 +685,30 @@ export const ERROR_CATEGORIES = Object.freeze({
         "requires_reencode",
         "image_dimensions_too_large",
         "workflow_failed",
+        "sse_connection_limit_exceeded",
+        "sse_capacity_exhausted",
+        "long_form_concurrency_limit_exceeded",
+        "item_failed",
     ]),
     config: Object.freeze([
         "missing_credentials",
         "feature_requires_auth",
+        "config_error",
+        "bundle_already_archived",
+        "sink_error",
     ]),
     network: Object.freeze([
         "timeout",
         "aborted",
         "upload_failed",
+        "fan_out_timeout",
     ]),
     auth: Object.freeze([
         "auth_failed",
         "multipart_session_ownership",
         "multipart_session_auth_required",
+        "unprocessable_entity",
+        "email_same",
     ]),
     validation: Object.freeze([
         "multipart_part_invalid",
@@ -551,11 +724,13 @@ export const ERROR_CATEGORIES = Object.freeze({
         "missing_dependency",
         "unsupported_value",
         "type_mismatch",
+        "result_not_ready",
     ]),
     chain: Object.freeze([
         "undeclared_asset",
         "unused_asset",
         "per_input_options_not_supported",
         "chain_cardinality_mismatch",
+        "no_such_key",
     ]),
 });

package/dist/gisl.d.ts

@@ -41,7 +41,7 @@ import { Handle } from './handle.js';
  * @internal
  */
 export declare const ANONYMOUS_ALLOWLIST: readonly [];
-export interface GislCreateOptions extends ResolveCredentialsOptions, ResolveEndpointOptions, Omit<GislClientConfig, 'baseUrl' | 'apiKey' | 'useSessionCookie'> {
+export interface GislCreateOptions extends ResolveCredentialsOptions, ResolveEndpointOptions, Omit<GislClientConfig, 'baseUrl' | 'apiKey' | 'useSessionCookie' | 'streamBaseUrl'> {
     /**
      * Layered ergonomic preset defaults (T4a / VhIj4S7T). Built via
      * `presetDefaults().<cell>(level, overrides?)…`. The resolver wiring

package/dist/gisl.js

@@ -18,7 +18,7 @@
  */
 import { GislClient } from './client.js';
 import { GislConfigError, GislFeatureRequiresAuthError, GislMissingCredentialsError, } from './errors.js';
-import { resolveApiKey, resolveEndpoint, } from './credentials.js';
+import { resolveApiKey, resolveEndpoint, resolveStreamEndpoint, } from './credentials.js';
 import { OperationBuilder } from './builder.js';
 import { validateVerbOptions, validateSingleOpConvertOptions, assertThumbnailDimensions, } from './ergonomic/option_validation.js';
 import { MergeBuilder, asset } from './merge.js';
@@ -279,13 +279,19 @@ function isMergeOptions(value) {
  * @internal
  */
 async function _createInternal(opts) {
-    const { apiKey: explicitKey, profile, profilePath, useSessionCookie, baseUrl, environment, allowAnonymous, 
+    const { apiKey: explicitKey, profile, profilePath, useSessionCookie, baseUrl, environment, streamBaseUrl, 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 });
+    // Resolved SEPARATELY and never from `resolvedBaseUrl`. `null` here means
+    // "nothing declares a stream host for this configuration" — a legitimate
+    // state that `streamEvents` reports and `run()` handles by polling. Both
+    // resolvers throw on an unknown explicit `environment`, so a typo cannot
+    // split the two hosts across environments.
+    const resolvedStreamBaseUrl = resolveStreamEndpoint({ baseUrl, environment, streamBaseUrl });
     // 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
@@ -295,6 +301,9 @@ async function _createInternal(opts) {
             baseUrl: resolvedBaseUrl,
             ...transportConfig,
         };
+        if (resolvedStreamBaseUrl !== null) {
+            config.streamBaseUrl = resolvedStreamBaseUrl;
+        }
         if (useSessionCookie !== undefined) {
             config.useSessionCookie = useSessionCookie;
         }
@@ -327,6 +336,9 @@ async function _createInternal(opts) {
         baseUrl: resolvedBaseUrl,
         ...transportConfig,
     };
+    if (resolvedStreamBaseUrl !== null) {
+        config.streamBaseUrl = resolvedStreamBaseUrl;
+    }
     if (resolvedKey !== null) {
         config.apiKey = resolvedKey;
     }