@giveitsmaller/sdk 0.22.0 → 0.26.0

package/dist/errors.d.ts

@@ -389,6 +389,31 @@ export declare class GislConfigError extends GislError {
 export declare class GislMissingCredentialsError extends GislConfigError {
     constructor(message: string);
 }
+/**
+ * `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 declare class GislStreamHostNotDeclaredError 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.
@@ -513,17 +538,115 @@ export declare class GislFanOutTimeoutError extends 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`).
+ * 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 declare class GislNetworkError extends GislError {
     constructor(message: string);
 }
+/**
+ * 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 declare class GislTransportError extends GislNetworkError {
+    constructor(message: string);
+    /**
+     * 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(): boolean;
+}
+/**
+ * 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 declare class GislRequestNotSentError extends GislNetworkError {
+    constructor(message: string);
+    /** Always `false` — the request never left, and re-sending it will not change that. */
+    get retryable(): boolean;
+}
+/**
+ * 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 declare class GislDownloadHttpError extends GislNetworkError {
+    /** The HTTP status the download URL responded with. */
+    readonly status: number;
+    constructor(message: string, status: number);
+    /**
+     * 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(): boolean;
+}
 /**
  * Internal control-flow marker (TDqmkWpX): the SSE event stream closed cleanly
  * WITHOUT a terminal (`workflow_completed`/`failed`/`partially_failed`) event.

package/dist/errors.js

@@ -398,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.
@@ -560,13 +588,34 @@ export class GislFanOutTimeoutError extends 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`).
+ * 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) {
@@ -574,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.d.ts

@@ -671,7 +671,7 @@ export declare const WATERMARK_CAPABILITY: {
     readonly video_watermark: {
         readonly video: {
             readonly mimes: readonly ["video/mp4", "video/webm"];
-            readonly availability: "beta";
+            readonly availability: "stable";
         };
     };
 };

package/dist/file-first.js

@@ -9,7 +9,7 @@
  *
  * 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';
@@ -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;
             }
         }
@@ -1362,7 +1372,7 @@ export const WATERMARK_CAPABILITY = {
         image_bmp: { mimes: ['image/bmp'], availability: 'stable' },
     },
     video_watermark: {
-        video: { mimes: ['video/mp4', 'video/webm'], availability: 'beta' },
+        video: { mimes: ['video/mp4', 'video/webm'], availability: 'stable' },
     },
 };
 const _WATERMARK_SHIPPABLE = new Set(['stable', 'beta']);

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" | "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 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

@@ -506,6 +506,33 @@ 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",
@@ -658,6 +685,8 @@ 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",
     ]),

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;
     }

package/dist/handle.js

@@ -32,7 +32,7 @@
  *
  * Mirrors the PHP `Gisl\Sdk\Ergonomic\Handle` + `Gisl\Sdk\Ergonomic\StatusSnapshot`.
  */
-import { GislConfigError, GislNetworkError, GislResultNotReadyError, GislTimeoutError, SseEndedWithoutTerminal, } from './errors.js';
+import { GislConfigError, GislNetworkError, GislResultNotReadyError, GislTimeoutError, GislStreamHostNotDeclaredError, SseEndedWithoutTerminal, } from './errors.js';
 import { _consumeSseToTerminal, _pollToTerminal, _parseMaxWait, } from './builder.js';
 import { projectDownloadsToRunResult, projectMultiJobToRunResult, isFanoutStatus, isMergeStatus, isArchiveStatus, isWatermarkStatus, isSoleOpChainStatus, soleOpChainDeliverableRef, _POST_STEP_JOB_REF, } from './file-first.js';
 import { LazyHttpDownloader } from './lazy-downloader.js';
@@ -172,7 +172,17 @@ export class Handle {
             // (GislNetworkError). Everything else (timeout, abort, API, an onProgress
             // callback throw, anything unexpected) MUST propagate — re-issuing the same
             // doomed request via poll would mask the real failure.
-            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;
             }
             finalStatus = await _pollToTerminal(client, {

package/dist/http-downloader.js

@@ -7,7 +7,7 @@
 import { createWriteStream } from 'node:fs';
 import { Readable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
-import { GislNetworkError, GislSinkError } from './errors.js';
+import { GislDownloadHttpError, GislRequestNotSentError, GislSinkError, GislTransportError, } from './errors.js';
 /**
  * Streams a (typically pre-signed) URL to a local path without buffering the
  * whole body in memory. Pre-signed download URLs require no SDK auth, so this
@@ -21,22 +21,40 @@ export class HttpDownloader {
         // on the RunResult sink side. Parity-critical: the FF1 sink contract tells
         // callers to narrow with instanceof, so the source-read error type must
         // match across languages.
+        // codex f46340e1d58a: a malformed URL fails DETERMINISTICALLY, so it must
+        // not land in the always-retryable bucket with DNS and TLS. `fetch` rejects
+        // both with an indistinguishable TypeError, so the only way to tell them
+        // apart is to check BEFORE the call — which also gives
+        // GislRequestNotSentError a real throw site in TypeScript rather than
+        // leaving it declared-but-dormant.
+        try {
+            new URL(url);
+        }
+        catch {
+            throw new GislRequestNotSentError(`Download source is not a valid URL: ${url}`);
+        }
         let res;
         try {
             res = await fetch(url);
         }
         catch (cause) {
             // A rejected fetch (DNS, TCP, TLS, mid-flight disconnect) must surface as
-            // GislNetworkError too — not the raw TypeError — so callers can narrow
-            // every download-source failure with `instanceof GislNetworkError`
-            // (codex review medium).
-            throw new GislNetworkError(`Failed to fetch download source: ${cause instanceof Error ? cause.message : String(cause)}`);
+            // a typed error — not the raw TypeError — so callers can narrow every
+            // download-source failure with `instanceof GislNetworkError`
+            // (codex review medium). t2qCrjdr: TRANSPORT specifically, so the
+            // retry advice is `true` here and status-derived below.
+            throw new GislTransportError(`Failed to fetch download source: ${cause instanceof Error ? cause.message : String(cause)}`);
         }
         if (!res.ok) {
-            throw new GislNetworkError(`Download failed with status ${res.status}`);
+            // t2qCrjdr: the server was REACHED and refused. Carries the status so a
+            // consumer telling a permanent 404 from a transient 503 never has to
+            // parse the message.
+            throw new GislDownloadHttpError(`Download failed with status ${res.status}`, res.status);
         }
         if (res.body === null) {
-            throw new GislNetworkError('Download response had no body');
+            // 2xx with nothing in it — the server did not refuse, it under-delivered.
+            // Transport rather than HTTP, and retrying is the right advice.
+            throw new GislTransportError('Download response had no body');
         }
         // `fetch`'s WHATWG ReadableStream and Node's `stream/web` ReadableStream
         // are structurally the same at runtime but typed in two different lib

package/dist/index.core.d.ts

@@ -3,7 +3,7 @@ export { parseSseStream } from './sse.js';
 export type { CreditsUsageOptions, ListWorkflowsOptions, GetSchemaOptions, GetSchemaResult, CapabilitiesSnapshot, PreflightClipError, PreflightClipsResult, ProbeWaitOptions, ProbeWaitResult, GislClientConfig, GislSseEvent, GislSseParseFailure, UploadOptions, WaitOptions, WorkflowCreatePayload, OperationDef, WorkflowSourcePayload, MultiInputSourcePayload, UploadSourcePayload, JobOutputSourcePayload, ExternalImportSourcePayload, ConnectionSourcePayload, JobInputV2Payload, JobDefinitionPayload, ExternalDestinationPayload, DeliveryPayload, DeliveryModePayload, DeliveryBundleFormatPayload, DeliverySelectionPayload, DeliverySelectionTypePayload, DeliveryOutputRefPayload, WorkflowProcessingPayload, ProcessingClassHintPayload, MultipartCheckpointState, _Sdk3HandCodedUploadedPart, _Sdk3HandCodedMultipartStatusResult, _Sdk3HandCodedPresignedPart, _Sdk3HandCodedPresignPartsResult, _Sdk3HandCodedKeepaliveResult, } from './types.js';
 export { uploadSource, jobOutputSource, externalImportSource, connectionSource, } from './types.js';
 export type { GislConfigErrorMetadata } from './errors.js';
-export { GislError, GislApiError, GislValidationError, GislBalanceExhaustedError, GislLongFormConcurrencyError, GislTierRestrictedError, GislFeatureTierRestrictedError, GislFeatureNotAvailableError, GislWorkflowExpiredError, GislProbePendingError, GislAuthError, GislUploadCapExceededError, GislMultipartPartError, GislMultipartPartCountError, GislMultipartSessionNotFoundError, GislMultipartSessionOwnershipError, GislMultipartSessionAuthRequiredError, GislTimeoutError, GislFanOutTimeoutError, GislAbortError, GislNetworkError, GislConfigError, GislMissingCredentialsError, GislFeatureRequiresAuthError, GislUndeclaredAssetError, GislUnusedAssetError, GislPerInputOptionsNotSupportedError, GislChainCardinalityMismatchError, GislBundleAlreadyArchivedError, GislNoSuchKeyError, GislSinkError, GislItemFailedError, GislResultNotReadyError, } from './errors.js';
+export { GislError, GislApiError, GislValidationError, GislBalanceExhaustedError, GislLongFormConcurrencyError, GislTierRestrictedError, GislFeatureTierRestrictedError, GislFeatureNotAvailableError, GislWorkflowExpiredError, GislProbePendingError, GislAuthError, GislUploadCapExceededError, GislMultipartPartError, GislMultipartPartCountError, GislMultipartSessionNotFoundError, GislMultipartSessionOwnershipError, GislMultipartSessionAuthRequiredError, GislTimeoutError, GislFanOutTimeoutError, GislAbortError, GislNetworkError, GislTransportError, GislDownloadHttpError, GislRequestNotSentError, GislConfigError, GislMissingCredentialsError, GislStreamHostNotDeclaredError, GislFeatureRequiresAuthError, GislUndeclaredAssetError, GislUnusedAssetError, GislPerInputOptionsNotSupportedError, GislChainCardinalityMismatchError, GislBundleAlreadyArchivedError, GislNoSuchKeyError, GislSinkError, GislItemFailedError, GislResultNotReadyError, } from './errors.js';
 export type { GislApiErrorOptions, GislUploadCapKind } from './errors.js';
 export type { ErrorCategory } from './generated/sdk_spec/errors.js';
 export { RunResult } from './file-first.js';
@@ -33,7 +33,7 @@ export type { SseOperationProgressData, SseOperationCompletedData, SseOperationF
 export type { MultiOutputCompletion, PageIndexed, PositionIndexed, Unindexed, } from '@giveitsmaller/contracts/asyncapi';
 import type { MultiOutputCompletion as _MultiOutputCompletion } from '@giveitsmaller/contracts/asyncapi';
 export type OperationResultOutputEntry = _MultiOutputCompletion['outputs'][number];
-export type { CompressImageOptions, CompressImageJpegOptions, CompressImagePngOptions, CompressImageAvifOptions, CompressVideoOptions, CompressAudioOptions, CompressDocumentOfficeOptions, CompressDocumentOdfOptions, CompressDocumentEpubOptions, ThumbnailImageOptions, ThumbnailVideoOptions, ThumbnailDocumentOptions, TransformImageOptions, TransformImageGifOptions, TransformVideoOptions, TransformDocumentPdfOptions, ConvertImageOptions, ConvertVideoOptions, ConvertAudioOptions, ConvertDocumentPdfOptions, MergeImageOptions, MergeVideoOptions, MergeVideoPerInputOptions, MergeAudioOptions, MergeAudioPerInputOptions, ArchiveOptions, ImageWatermarkImageOptions, ImageWatermarkImageGifOptions, TextWatermarkImageOptions, CustomLumaVideoOptions, AudioOverlayAudioOptions, AudioOverlayVideoOptions, AudioWatermarkAudioOptions, AudioWatermarkVideoOptions, AudioToVideoAudioOptions, VideoWatermarkVideoOptions, VideoTextWatermarkVideoOptions, SplitImageGifOptions, SplitDocumentPdfOptions, SplitAudioOptions, SplitVideoOptions, } from '@giveitsmaller/contracts/operations';
+export type { CompressImageOptions, CompressImageJpegOptions, CompressImagePngOptions, CompressImageAvifOptions, CompressVideoOptions, CompressAudioOptions, CompressDocumentOfficeOptions, CompressDocumentOdfOptions, CompressDocumentEpubOptions, ThumbnailImageOptions, ThumbnailVideoOptions, ThumbnailDocumentOfficeOptions, ThumbnailDocumentPdfOptions, ThumbnailDocumentEpubOptions, TransformImageOptions, TransformImageGifOptions, TransformVideoOptions, TransformDocumentPdfOptions, ConvertImageOptions, ConvertVideoOptions, ConvertAudioOptions, ConvertDocumentPdfOptions, MergeImageOptions, MergeVideoOptions, MergeVideoPerInputOptions, MergeAudioOptions, MergeAudioPerInputOptions, ArchiveOptions, ImageWatermarkImageOptions, ImageWatermarkImageGifOptions, TextWatermarkImageOptions, CustomLumaVideoOptions, AudioOverlayAudioOptions, AudioOverlayVideoOptions, AudioWatermarkAudioOptions, AudioWatermarkVideoOptions, AudioToVideoAudioOptions, VideoWatermarkVideoOptions, VideoTextWatermarkVideoOptions, SplitImageGifOptions, SplitDocumentPdfOptions, SplitAudioOptions, SplitVideoOptions, } from '@giveitsmaller/contracts/operations';
 export { ImageWatermarkImageAnchor, ImageWatermarkImageGifAnchor, TextWatermarkImageAnchor, TextWatermarkImageFontFamily, TextWatermarkImageWatermarkMode, AudioOverlayAudioMode, AudioOverlayVideoMode, AudioOverlayVideoNoAudioTrackBehaviour, AudioWatermarkAudioMethod, AudioWatermarkAudioRobustness, AudioWatermarkAudioDensity, AudioWatermarkVideoMethod, AudioWatermarkVideoRobustness, AudioWatermarkVideoDensity, AudioToVideoAudioOutputResolution, AudioToVideoAudioImageFit, AudioToVideoAudioOutputFormat, VideoWatermarkVideoAnchor, VideoTextWatermarkVideoFontFamily, VideoTextWatermarkVideoWatermarkMode, VideoTextWatermarkVideoAnchor, SplitImageGifOutputFormat, SplitDocumentPdfMode, SplitAudioMode, SplitAudioPrecision, SplitVideoMode, SplitVideoPrecision, } from '@giveitsmaller/contracts/operations';
 export { archiveMetadata, audioOverlayMetadata, audioWatermarkMetadata, compressMetadata, convertMetadata, customLumaMetadata, imageWatermarkMetadata, mergeMetadata, textWatermarkMetadata, thumbnailMetadata, audioToVideoMetadata, videoWatermarkMetadata, videoTextWatermarkMetadata, splitMetadata, transformMetadata, } from '@giveitsmaller/contracts/operations';
 export type { ConvertOptions, ThumbnailOptions, TransformOptions, TextWatermarkOptions, WatermarkOptions, WatermarkOverlay, WatermarkAnchor, } from './ergonomic/option_types.js';

package/dist/index.core.js

@@ -15,11 +15,24 @@ GislMultipartSessionNotFoundError, GislMultipartSessionOwnershipError, GislMulti
 // 4G4FaA9X — mapEach fan-out timed out mid-batch; carries the completed
 // child ids + parent id so the caller can recover without a whole-batch re-run.
 GislFanOutTimeoutError, GislAbortError, 
-// FF2b / tywwynmN — transport-level failure (mirrors PHP GislNetworkError);
+// FF2b / tywwynmN — off-envelope failure base (mirrors PHP GislNetworkError);
 // raised by the file-first HttpDownloader when an output URL cannot be read.
+// t2qCrjdr: NEVER THROWN DIRECTLY any more — it is the hierarchy node the two
+// subclasses below share, kept so existing `instanceof GislNetworkError`
+// narrowing (including the SSE poll-fallback) is unchanged.
 GislNetworkError, 
+// t2qCrjdr — the split. One `retryable` could not be honest for both a DNS
+// failure and a 404, so each case is now its own class with its own answer.
+GislTransportError, GislDownloadHttpError, 
+// The request never left the client — never retryable. TS detects only what
+// it can see BEFORE the call (an unparseable URL); PHP also classifies
+// PSR-18's RequestExceptionInterface, which `fetch` gives no equivalent of.
+GislRequestNotSentError, 
 // T1 / wVU4xHx3 — local config-error tree (pre-I/O; sibling of GislApiError).
-GislConfigError, GislMissingCredentialsError, GislFeatureRequiresAuthError, 
+GislConfigError, GislMissingCredentialsError, 
+// VUozk5Bc — `streamEvents` on a client with no DECLARED stream host. The
+// SDK refuses to derive `stream.*` from `api.*`; `run()` polls instead.
+GislStreamHostNotDeclaredError, GislFeatureRequiresAuthError, 
 // T3 / cuecCmb5 — merge-compose local validation errors.
 GislUndeclaredAssetError, GislUnusedAssetError, GislPerInputOptionsNotSupportedError, 
 // T6 / aDR1jnyZ — chain-cardinality validation (dormant until chain