@giveitsmaller/sdk 0.22.0 → 0.25.0

package/README.md

@@ -74,23 +74,26 @@ development against staging** — which is the one most likely to bite first, be
 bug in your code.
 
 ⚠️ **Local dev against staging is the sharp edge, and the reason is worth stating:** the two hosts
-have *different* CORS policies, for a platform reason rather than an oversight. The main API host
-allows a **list** of origins — and the **staging** list includes the usual localhost dev ports — so a
-browser on `localhost` works against staging today. The stream host allows exactly **one** origin,
-because it is a different API product with no native CORS configuration and nowhere to put a second
-value. So everything keeps working right up until live progress, and then fails with a CORS error —
-which reads like a mistake in your own application rather than a platform limitation.
+have *different* CORS policies today. The main API host allows a **list** of origins — and the
+**staging** list includes the usual localhost dev ports — so a browser on `localhost` works against
+staging today. The stream host is configured with exactly **one** origin. So everything keeps
+working right up until live progress, and then fails with a CORS error — which reads like a mistake
+in your own application rather than a deployment setting.
 
 **Production allows only the production web app on both hosts**, and always has.
 
 **Workaround:** pass `useSSE: false` to `run()`. The SDK falls back to polling, which goes to the
 main API host and is unaffected. Everything else about the call is identical.
 
-**Why it cannot simply be widened:** the stream is cookie-credentialed, and the CORS specification
-forbids combining `Access-Control-Allow-Credentials: true` with `Access-Control-Allow-Origin: *`.
-The header also accepts exactly one origin — a comma-separated list is not valid. Supporting more
-origins requires the server to validate and echo the request's `Origin`, which is planned but not
-shipped.
+**Why it is not a one-line config change — and why it is NOT impossible.** An earlier version of
+this section said multi-origin support could not be done on this host. **That was wrong, and it is
+corrected here.** What is true: `Access-Control-Allow-Origin` accepts exactly one origin (a
+comma-separated list is not valid), and because the stream can be cookie-credentialed, the CORS
+specification also forbids answering `*` alongside `Access-Control-Allow-Credentials: true`. What
+does **not** follow is that more origins are unreachable. The server can validate the request's
+`Origin` and echo it back, which is how every multi-origin credentialed endpoint works. That is a
+**change somebody has to build and get right**, not a platform prohibition — so treat this as
+unshipped work with its own correctness risk, not as a closed door.
 
 **On authentication:** prefer an API key (`bearerAuth`) or the anonymous capability token on the
 stream host. Cookie/session auth is accepted by the endpoint but a *credentialed cross-origin*
@@ -104,6 +107,39 @@ same reason.
 > test and canary we run passes while a consumer on another origin fails. It is written here because
 > nothing else would tell you.
 
+## Pointing the event stream at its own host
+
+Live progress is served from a **second host**, separate from `baseUrl`. The SDK reads that host
+from the contract's declaration — it **never derives** `stream.*` from `api.*`.
+
+```ts
+// Resolved from the environment's declared stream host.
+const client = await gisl.create({ apiKey, environment: 'staging' });
+
+// Or point it explicitly. This moves the STREAM only — uploads, workflow-create
+// and downloads still go to baseUrl.
+const client = await gisl.create({
+  apiKey,
+  environment: 'staging',
+  streamBaseUrl: 'https://stream.example.com',
+});
+```
+
+`GISL_STREAM_BASE_URL` does the same thing from the environment. Precedence matches `baseUrl`:
+explicit argument, then `environment`, then the env var.
+
+⚠️ **If nothing declares a stream host, the SDK does not fall back to `baseUrl`.** `streamEvents()`
+throws `GislStreamHostNotDeclaredError` (a `GislConfigError`), and `run()` silently uses polling
+instead, which is a working transport. **This is deliberate.** Guessing the stream host from the API
+host is a convention, and the last time a client did that it streamed into a gateway that cannot
+stream, invisibly — a silent fallback looks exactly like a working one.
+
+Both `prod` and `staging` resolve to their contract-declared hosts (production landed with
+contracts `v2.195.0`), and an **unconfigured** client resolves production for the stream just as it
+already did for the API. What still fails closed is a **custom** host: pass your own `baseUrl` (or
+set `GISL_BASE_URL`) with no `streamBaseUrl` and `streamEvents()` raises rather than guessing that
+your proxy's stream lives at production.
+
 ## Documentation
 
 Full documentation — getting started and concepts, the `GislClient` reference and operation

package/dist/builder.js

@@ -26,7 +26,7 @@
  */
 import { SseEventType, SseOperationProgressDataFromJSON, } from '@giveitsmaller/contracts/openapi';
 import { uploadSource } from './types.js';
-import { GislTimeoutError, GislFanOutTimeoutError, GislNetworkError, SseEndedWithoutTerminal } from './errors.js';
+import { GislTimeoutError, GislFanOutTimeoutError, GislNetworkError, GislStreamHostNotDeclaredError, GislTransportError, SseEndedWithoutTerminal } from './errors.js';
 // Deferred-usage-only import: `Handle` is constructed inside submit() at call
 // time, not at module load, so the builder.ts <-> handle.ts cycle is safe
 // under ESM (handle.ts imports the await-primitives from this module).
@@ -403,7 +403,17 @@ export class OperationBuilder {
                 // Everything else — timeout, abort, API error, 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;
                 }
                 // Genuine SSE stream-end / transport error — fall through to poll fallback.
@@ -592,7 +602,7 @@ export async function _consumeSseToTerminal(client, args) {
             // GislNetworkError so the await-terminal callers poll-fallback on it
             // (and ONLY on it / a clean stream-end), never on an onProgress throw.
             if (err instanceof TypeError) {
-                throw new GislNetworkError(`SSE connect to workflow ${args.workflowId} events failed: ${err.message}`);
+                throw new GislTransportError(`SSE connect to workflow ${args.workflowId} events failed: ${err.message}`);
             }
             throw err;
         }
@@ -674,11 +684,12 @@ export async function _consumeSseToTerminal(client, args) {
                 throw new GislTimeoutError(`Workflow ${args.workflowId} did not complete before maxWait deadline`, args.workflowId);
             }
             // A genuine mid-stream TRANSPORT failure (reader disconnect) surfaces as a
-            // raw `TypeError` from the iterator — wrap as GislNetworkError so callers
+            // raw `TypeError` from the iterator — wrap as GislTransportError so callers
             // poll-fallback. (An onProgress throw was already handled above, so a
-            // TypeError here is unambiguously transport.)
+            // TypeError here is unambiguously transport.) It stays a GislNetworkError
+            // by inheritance, so the poll-fallback gates below are unchanged.
             if (innerErr instanceof TypeError) {
-                throw new GislNetworkError(`SSE stream for workflow ${args.workflowId} failed mid-stream: ${innerErr.message}`);
+                throw new GislTransportError(`SSE stream for workflow ${args.workflowId} failed mid-stream: ${innerErr.message}`);
             }
             throw innerErr;
         }

package/dist/client.d.ts

@@ -13,6 +13,13 @@ export interface ValidationDetail {
 }
 export declare class GislClient {
     private readonly baseUrl;
+    /**
+     * Declared SSE stream host, or `null` when nothing declares one for this
+     * configuration. `null` is a legitimate state, not a misconfiguration —
+     * see `streamEvents`, which fails closed on it rather than falling back to
+     * `baseUrl`.
+     */
+    private readonly streamBaseUrl;
     private readonly headers;
     private readonly timeoutMs;
     private readonly multipartThreshold;

package/dist/client.js

@@ -5,7 +5,11 @@
 // dynamic one) so `vi.mock('node:fs/promises')` still intercepts it in tests.
 import { open, stat, basename } from './node-fs.js';
 import { AudioWatermarkDecodeRequestToJSON, AudioWatermarkDecodeResponseFromJSON, ExternalImportCreatedResponseFromJSON, ExternalImportRequestToJSON, LoginUser200ResponseDataFromJSON, AccountLimitsFromJSON, CreditsBalanceResponseFromJSON, CreditsUsageResponseFromJSON, UploadResponseFromJSON, UploadProbeResponseFromJSON, MultipartInitiateResponseFromJSON, MultipartInitiateRequestMetadataHintToJSON, MultipartCompleteResponseFromJSON, MultipartCompleteRequestToJSON, WorkflowCancelResponseFromJSON, WorkflowCreateResponseFromJSON, WorkflowResumeResponseFromJSON, WorkflowStatusResponseFromJSON, WorkflowListResponseFromJSON, WorkflowDownloadResponseFromJSON, MetadataResponseFromJSON, OperationsSchemaResponseFromJSON, RetryResponseFromJSON, WorkflowStatus, AuthErrorResponseFromJSON, AuthErrorType, AuthRejectionEnvelopeFromJSON, AuthRejectionEnvelopeErrorTypeEnum, BalanceExhaustedResponseFromJSON, BalanceExhaustedResponseRequiredActionEnum, FeatureNotAvailableResponseFromJSON, FeatureTierRestrictedResponseFromJSON, LongFormConcurrencyLimitResponseFromJSON, TierRestrictionKind, TierRestrictionResponseFromJSON, UserTier, WorkflowExpiredResponseFromJSON, ProbePendingResponseFromJSON, UploadSizeExceedsTierResponseFromJSON, UploadDurationExceedsTierResponseFromJSON, UploadConstraintsAppliedProcessingClassPreAssignmentEnum, UploadThresholdsSingleShotMaxBytesEnum, UploadThresholdsMultipartChunkSizeEnum, UploadThresholdsMultipartConcurrencyDefaultEnum, } from '@giveitsmaller/contracts/openapi';
-import { GislAbortError, GislApiError, GislAuthError, GislAuthRejectionError, GislBalanceExhaustedError, GislError, GislFeatureNotAvailableError, GislFeatureTierRestrictedError, GislLongFormConcurrencyError, GislMultipartPartCountError, GislMultipartPartError, GislMultipartSessionNotFoundError, GislMultipartSessionOwnershipError, GislMultipartSessionAuthRequiredError, GislTierRestrictedError, GislTimeoutError, GislProbePendingError, GislUploadCapExceededError, GislValidationError, GislWorkflowExpiredError, } from './errors.js';
+import { GislAbortError, GislApiError, GislAuthError, GislAuthRejectionError, GislBalanceExhaustedError, GislConfigError, GislError, GislFeatureNotAvailableError, GislFeatureTierRestrictedError, GislLongFormConcurrencyError, GislMultipartPartCountError, GislMultipartPartError, GislMultipartSessionNotFoundError, GislMultipartSessionOwnershipError, GislMultipartSessionAuthRequiredError, GislTierRestrictedError, GislTimeoutError, GislProbePendingError, GislStreamHostNotDeclaredError, GislUploadCapExceededError, GislValidationError, GislWorkflowExpiredError, } from './errors.js';
+// Stream-host vocabulary for the fail-closed `streamEvents` guard. The
+// resolver itself runs in `gisl.create()`; the client only reports what a
+// caller can do about an absent host.
+import { declaredStreamEnvironments, GISL_STREAM_BASE_URL_ENV, } from './credentials.js';
 // The `Retry-After` millisecond parser lives in the shared retry-metadata
 // module (extracted to break the client ↔ errors circular import); re-imported
 // here so the retry-loop timing stays byte-identical.
@@ -350,8 +354,60 @@ function fileByteSource(path, size) {
         },
     };
 }
+/**
+ * Normalise a configured stream host to an absolute origin, or `null` when
+ * none was supplied. Trailing slashes are stripped so path concatenation does
+ * not double-separate.
+ *
+ * ⚠️ **A PRESENT-BUT-MALFORMED VALUE THROWS RATHER THAN DEGRADING TO `null`,
+ * and the distinction is deliberate.** Absent means "nobody declared one" — a
+ * legitimate state that `run()` handles by polling. A caller who passed
+ * `'/'` or `'stream.example.com'` did declare one, and got it wrong.
+ * Quietly converting that to "absent" would send their stream somewhere they
+ * did not choose (a bare `'/'` normalises to `''`, which concatenates into a
+ * RELATIVE url) and hand them a poll they never asked for — the silent
+ * degradation this whole mechanism exists to refuse, one layer further down.
+ *
+ * An empty OR WHITESPACE-ONLY string is treated as unset — the two are
+ * indistinguishable in intent — matching how `locale` handles `''` elsewhere in
+ * this config.
+ */
+function normaliseStreamBaseUrl(value) {
+    if (value === undefined)
+        return null;
+    const trimmed = value.trim();
+    if (trimmed === '')
+        return null;
+    let parsed;
+    try {
+        parsed = new URL(trimmed);
+    }
+    catch {
+        throw new GislConfigError(`streamBaseUrl must be an absolute http(s) URL (e.g. https://stream.example.com); got '${value}'.`);
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        throw new GislConfigError(`streamBaseUrl must use http or https; got protocol '${parsed.protocol}' in '${value}'.`);
+    }
+    // A query or fragment cannot survive path concatenation: the events path
+    // is appended as a STRING, so `https://host?token=x` would request `/`
+    // with the whole events path buried inside the query value. Rejecting is
+    // right rather than stripping — a caller who put a token there meant it to
+    // be sent, and silently dropping it would fail later and further away.
+    // codex 5793a3be0f7b.
+    if (parsed.search !== '' || parsed.hash !== '') {
+        throw new GislConfigError(`streamBaseUrl must not carry a query or fragment (the events path is appended to it); got '${value}'.`);
+    }
+    return trimmed.replace(/\/+$/, '');
+}
 export class GislClient {
     baseUrl;
+    /**
+     * Declared SSE stream host, or `null` when nothing declares one for this
+     * configuration. `null` is a legitimate state, not a misconfiguration —
+     * see `streamEvents`, which fails closed on it rather than falling back to
+     * `baseUrl`.
+     */
+    streamBaseUrl;
     headers;
     timeoutMs;
     multipartThreshold;
@@ -361,6 +417,11 @@ export class GislClient {
     useSessionCookie;
     constructor(config) {
         this.baseUrl = config.baseUrl.replace(/\/+$/, '');
+        // NOT defaulted to `baseUrl`. An absent stream host stays absent so
+        // `streamEvents` can fail closed and name the missing declaration; a
+        // default here would be the silent derivation this whole mechanism exists
+        // to prevent, hidden one layer deeper than the resolver.
+        this.streamBaseUrl = normaliseStreamBaseUrl(config.streamBaseUrl);
         this.timeoutMs = config.timeout ?? DEFAULT_TIMEOUT_MS;
         this.useSessionCookie = config.useSessionCookie ?? false;
         // Floor the threshold at the first-chunk size: the multipart initiate
@@ -399,7 +460,7 @@ export class GislClient {
         if (opts.signal?.aborted) {
             throw new GislAbortError(`Request to ${method} ${path} aborted`);
         }
-        const url = `${this.baseUrl}${path}`;
+        const url = `${opts.baseUrl ?? this.baseUrl}${path}`;
         const headers = { ...this.headers, ...opts.headers };
         let body;
         if (opts.json !== false && opts.body && !(opts.body instanceof FormData)) {
@@ -1748,6 +1809,24 @@ export class GislClient {
      */
     async streamEvents(workflowId, opts = {}) {
         const eventsPath = `/api/workflows/${encodeURIComponent(workflowId)}/events`;
+        // FAIL CLOSED. The stream lives on a second host and this SDK will not
+        // guess it. Falling back to `this.baseUrl` here would be the one line that
+        // re-creates, inside a published SDK, the failure this mechanism exists to
+        // prevent: production had no stream host configured, fell back to the API
+        // host by convention, and streamed into a gateway that cannot stream —
+        // invisibly, because a silent fallback looks exactly like a working one.
+        // `run()` handles this case by polling; a direct `streamEvents` caller
+        // asked for the stream specifically and is told plainly that there isn't
+        // one.
+        if (this.streamBaseUrl === null) {
+            const declared = declaredStreamEnvironments();
+            throw new GislStreamHostNotDeclaredError('No SSE stream host is declared for this configuration, and the SDK does not derive one ' +
+                `from baseUrl. ${declared.length > 0
+                    ? `Environments that declare a stream host: ${declared.join(', ')}.`
+                    : 'No environment currently declares a stream host.'} Pass {streamBaseUrl} to gisl.create() / new GislClient(), set ` +
+                `${GISL_STREAM_BASE_URL_ENV}, or construct with an {environment} that declares one. ` +
+                'Hosts are read from the contract declaration and are never derived from baseUrl.');
+        }
         // SSE-lifetime AbortController. `request()` builds its own controller
         // and tears it down (`clearTimeout(timer); unbind()`) in its `finally`
         // the instant the response headers arrive — BEFORE the SSE body
@@ -1771,6 +1850,8 @@ export class GislClient {
                 rawResponse: true,
                 signal: controller.signal,
                 headers: workflowCapabilityHeaders(opts.capability),
+                // The one call in the SDK that does NOT go to `baseUrl`.
+                baseUrl: this.streamBaseUrl,
             });
         }
         catch (err) {

package/dist/credentials.d.ts

@@ -16,6 +16,7 @@
 export declare const GISL_API_KEY_ENV = "GISL_API_KEY";
 export declare const GISL_BASE_URL_ENV = "GISL_BASE_URL";
 export declare const GISL_ENVIRONMENT_ENV = "GISL_ENVIRONMENT";
+export declare const GISL_STREAM_BASE_URL_ENV = "GISL_STREAM_BASE_URL";
 /**
  * Named environments → base URLs. Kept colocated with the resolver so the
  * mapping table doesn't leak into `gisl.ts`.
@@ -26,6 +27,42 @@ export declare const ENVIRONMENT_ENDPOINTS: {
 };
 export type Environment = keyof typeof ENVIRONMENT_ENDPOINTS;
 export declare const DEFAULT_ENDPOINT: "https://api.giveitsmaller.com";
+/**
+ * Named environments → **SSE stream host**. A SECOND host, deliberately
+ * separate from {@link ENVIRONMENT_ENDPOINTS}: the API host fronts an
+ * integration with no response-streaming mode, so the event stream lives on
+ * its own public entry point.
+ *
+ * ⚠️ **DECLARED, NEVER DERIVED.** This table exists because the alternative —
+ * transforming `api.*` into `stream.*` by string surgery — is a *convention*,
+ * and a convention is exactly what put production on the gateway path: the
+ * frontend's prod build had no `VITE_SSE_BASE_URL`, silently fell back to the
+ * API host, and nobody could see it. A host is a fact somebody states, not a
+ * pattern somebody guesses.
+ *
+ * PINNED to the generated `availability.json`
+ * `endpoints['GET /api/workflows/{id}/events'].servers` by
+ * `tests/unit/stream-host-conformance.test.ts`, which fails **closed**: if the
+ * contract declares a host this table does not carry (or vice versa), the
+ * build breaks. Hand-maintained rather than read at runtime because the SDK
+ * ships a browser entry point and does not load `availability.json` — the same
+ * table+conformance shape used by `COMPRESS_OPTION_VALUES`,
+ * `OUTPUT_OPTION_DEPENDS_ON`, the preset planned gate and the watermark gate.
+ *
+ * `prod` landed with contracts `v2.195.0` (#410), which declared the production
+ * stream host. It is here because the CONTRACT declares it — the entry and the
+ * vendored declaration moved in the same change, never ahead of it.
+ *
+ * ⚠️ **A CONFIGURATION WITH NO DECLARED HOST STILL FAILS CLOSED.** Both entries
+ * being present does not soften the rule: {@link resolveStreamEndpoint} returns
+ * `null` for anything it cannot resolve from a declaration, and
+ * `GislClient.streamEvents` raises rather than quietly reusing `baseUrl`.
+ *
+ * `localhost` is intentionally absent too: it is declared in the contract as a
+ * development server, but there is no `localhost` *environment* name to key it
+ * off. Local callers pass `{streamBaseUrl}` or set `GISL_STREAM_BASE_URL`.
+ */
+export declare const ENVIRONMENT_STREAM_ENDPOINTS: Partial<Record<Environment, string>>;
 export interface ResolveCredentialsOptions {
     /** Explicit API key — highest precedence. */
     readonly apiKey?: string;
@@ -44,6 +81,12 @@ export interface ResolveCredentialsOptions {
 export interface ResolveEndpointOptions {
     readonly baseUrl?: string;
     readonly environment?: Environment;
+    /**
+     * Explicit SSE stream host. Highest precedence for stream resolution, and
+     * the ONLY knob that moves the stream **without** moving every other call —
+     * overriding `baseUrl` moves uploads, workflow-create and downloads too.
+     */
+    readonly streamBaseUrl?: string;
 }
 /**
  * Resolve the API key via the credential chain. Returns the resolved key,
@@ -59,3 +102,34 @@ export declare function resolveApiKey(opts?: ResolveCredentialsOptions): Promise
  * resolves to a usable URL.
  */
 export declare function resolveEndpoint(opts?: ResolveEndpointOptions): string;
+/**
+ * Resolve the **SSE stream host**, or `null` when no host is declared for this
+ * configuration. Explicit `streamBaseUrl` wins; otherwise an explicit
+ * `environment` name; otherwise `GISL_STREAM_BASE_URL`; otherwise the
+ * `GISL_ENVIRONMENT` env var.
+ *
+ * ⚠️ **RETURNS `null` RATHER THAN FALLING BACK TO `baseUrl`, AND THAT IS THE
+ * WHOLE POINT OF THIS FUNCTION.** Deriving the stream host from the API host
+ * would reproduce, inside a published SDK, the exact failure this resolver
+ * exists to prevent: prod had no stream host configured, fell back to the API
+ * host by convention, and landed on the gateway path where the stream cannot
+ * work. A silent fallback is not a lenient control — it is the absence of one
+ * wearing the control's name. Callers decide what `null` means; see
+ * `GislClient.streamEvents`, which fails closed and names the missing
+ * declaration.
+ *
+ * Unlike {@link resolveEndpoint}, there is no default: prod has no declared
+ * stream host yet (see {@link ENVIRONMENT_STREAM_ENDPOINTS}), so a default
+ * could only be a guess.
+ *
+ * Throws `GislConfigError` on an unknown explicit `environment` name — the
+ * same fail-closed behaviour as {@link resolveEndpoint}, for the same reason
+ * (a typo must not silently re-route a stream).
+ */
+export declare function resolveStreamEndpoint(opts?: ResolveEndpointOptions): string | null;
+/**
+ * Human-readable list of the environments that currently declare a stream
+ * host. Used in the fail-closed error message so the caller is told what IS
+ * available rather than only what is missing.
+ */
+export declare function declaredStreamEnvironments(): readonly string[];

package/dist/credentials.js

@@ -20,6 +20,7 @@ import { GislConfigError } from './errors.js';
 export const GISL_API_KEY_ENV = 'GISL_API_KEY';
 export const GISL_BASE_URL_ENV = 'GISL_BASE_URL';
 export const GISL_ENVIRONMENT_ENV = 'GISL_ENVIRONMENT';
+export const GISL_STREAM_BASE_URL_ENV = 'GISL_STREAM_BASE_URL';
 /**
  * Named environments → base URLs. Kept colocated with the resolver so the
  * mapping table doesn't leak into `gisl.ts`.
@@ -29,6 +30,45 @@ export const ENVIRONMENT_ENDPOINTS = {
     staging: 'https://api.staging.giveitsmaller.com',
 };
 export const DEFAULT_ENDPOINT = ENVIRONMENT_ENDPOINTS.prod;
+/**
+ * Named environments → **SSE stream host**. A SECOND host, deliberately
+ * separate from {@link ENVIRONMENT_ENDPOINTS}: the API host fronts an
+ * integration with no response-streaming mode, so the event stream lives on
+ * its own public entry point.
+ *
+ * ⚠️ **DECLARED, NEVER DERIVED.** This table exists because the alternative —
+ * transforming `api.*` into `stream.*` by string surgery — is a *convention*,
+ * and a convention is exactly what put production on the gateway path: the
+ * frontend's prod build had no `VITE_SSE_BASE_URL`, silently fell back to the
+ * API host, and nobody could see it. A host is a fact somebody states, not a
+ * pattern somebody guesses.
+ *
+ * PINNED to the generated `availability.json`
+ * `endpoints['GET /api/workflows/{id}/events'].servers` by
+ * `tests/unit/stream-host-conformance.test.ts`, which fails **closed**: if the
+ * contract declares a host this table does not carry (or vice versa), the
+ * build breaks. Hand-maintained rather than read at runtime because the SDK
+ * ships a browser entry point and does not load `availability.json` — the same
+ * table+conformance shape used by `COMPRESS_OPTION_VALUES`,
+ * `OUTPUT_OPTION_DEPENDS_ON`, the preset planned gate and the watermark gate.
+ *
+ * `prod` landed with contracts `v2.195.0` (#410), which declared the production
+ * stream host. It is here because the CONTRACT declares it — the entry and the
+ * vendored declaration moved in the same change, never ahead of it.
+ *
+ * ⚠️ **A CONFIGURATION WITH NO DECLARED HOST STILL FAILS CLOSED.** Both entries
+ * being present does not soften the rule: {@link resolveStreamEndpoint} returns
+ * `null` for anything it cannot resolve from a declaration, and
+ * `GislClient.streamEvents` raises rather than quietly reusing `baseUrl`.
+ *
+ * `localhost` is intentionally absent too: it is declared in the contract as a
+ * development server, but there is no `localhost` *environment* name to key it
+ * off. Local callers pass `{streamBaseUrl}` or set `GISL_STREAM_BASE_URL`.
+ */
+export const ENVIRONMENT_STREAM_ENDPOINTS = {
+    prod: 'https://stream.giveitsmaller.com',
+    staging: 'https://stream.staging.giveitsmaller.com',
+};
 // ---------------------------------------------------------------------------
 // Public resolvers
 // ---------------------------------------------------------------------------
@@ -105,6 +145,89 @@ export function resolveEndpoint(opts = {}) {
     }
     return DEFAULT_ENDPOINT;
 }
+/**
+ * Resolve the **SSE stream host**, or `null` when no host is declared for this
+ * configuration. Explicit `streamBaseUrl` wins; otherwise an explicit
+ * `environment` name; otherwise `GISL_STREAM_BASE_URL`; otherwise the
+ * `GISL_ENVIRONMENT` env var.
+ *
+ * ⚠️ **RETURNS `null` RATHER THAN FALLING BACK TO `baseUrl`, AND THAT IS THE
+ * WHOLE POINT OF THIS FUNCTION.** Deriving the stream host from the API host
+ * would reproduce, inside a published SDK, the exact failure this resolver
+ * exists to prevent: prod had no stream host configured, fell back to the API
+ * host by convention, and landed on the gateway path where the stream cannot
+ * work. A silent fallback is not a lenient control — it is the absence of one
+ * wearing the control's name. Callers decide what `null` means; see
+ * `GislClient.streamEvents`, which fails closed and names the missing
+ * declaration.
+ *
+ * Unlike {@link resolveEndpoint}, there is no default: prod has no declared
+ * stream host yet (see {@link ENVIRONMENT_STREAM_ENDPOINTS}), so a default
+ * could only be a guess.
+ *
+ * Throws `GislConfigError` on an unknown explicit `environment` name — the
+ * same fail-closed behaviour as {@link resolveEndpoint}, for the same reason
+ * (a typo must not silently re-route a stream).
+ */
+export function resolveStreamEndpoint(opts = {}) {
+    // TRIM BEFORE THE PRESENCE CHECK. A whitespace-only value is unset (the
+    // client normaliser treats it that way too), and if it were allowed to
+    // count as "supplied" here it would SUPPRESS the environment's declared
+    // host and then normalise to nothing — silently disabling a stream that
+    // was perfectly well declared. codex a7f5ec9f0d32.
+    const explicit = opts.streamBaseUrl?.trim() ?? '';
+    if (explicit !== '') {
+        return explicit;
+    }
+    if (typeof opts.environment === 'string') {
+        if (!(opts.environment in ENVIRONMENT_ENDPOINTS)) {
+            throw new GislConfigError(`Unknown environment '${opts.environment}'. Valid values: ${Object.keys(ENVIRONMENT_ENDPOINTS).join(', ')}.`);
+        }
+        // A KNOWN environment with no declared stream host resolves to `null`, not
+        // to an error and not to `baseUrl`: the config is valid, the declaration is
+        // simply missing upstream. Both current environments declare one.
+        return ENVIRONMENT_STREAM_ENDPOINTS[opts.environment] ?? null;
+    }
+    const envStreamBaseUrl = readEnv(GISL_STREAM_BASE_URL_ENV);
+    if (envStreamBaseUrl !== null && envStreamBaseUrl.length > 0) {
+        return envStreamBaseUrl;
+    }
+    const envEnvironment = readEnv(GISL_ENVIRONMENT_ENV);
+    if (envEnvironment !== null) {
+        const envMapped = ENVIRONMENT_STREAM_ENDPOINTS[envEnvironment];
+        if (envMapped !== undefined) {
+            return envMapped;
+        }
+    }
+    // SYMMETRY WITH `resolveEndpoint`, and a correctness fix rather than a
+    // convenience (codex 480e8b865b90). `resolveEndpoint` FALLS THROUGH to the
+    // production API host when nothing is configured — so an unconfigured
+    // `gisl.create({apiKey})` already talks to production, while its stream
+    // resolved to `null`. That made THE DEFAULT CONFIGURATION the one that could
+    // not stream: `streamEvents()` threw and `run()` silently polled, against a
+    // production host whose stream IS declared. The two resolvers have to agree
+    // about what "unconfigured" means.
+    //
+    // ⚠️ ONLY when the API host ALSO defaulted. An explicit `baseUrl` (or
+    // `GISL_BASE_URL`) names a host we were told about and cannot reason about —
+    // a proxy, a self-host, a test double — so we still refuse rather than assume
+    // production's stream host. Assuming there would be deriving one host from
+    // another, which is precisely what this mechanism exists to refuse.
+    const apiHostWasConfigured = (typeof opts.baseUrl === 'string' && opts.baseUrl.trim() !== '') ||
+        readEnv(GISL_BASE_URL_ENV) !== null;
+    if (!apiHostWasConfigured) {
+        return ENVIRONMENT_STREAM_ENDPOINTS.prod ?? null;
+    }
+    return null;
+}
+/**
+ * Human-readable list of the environments that currently declare a stream
+ * host. Used in the fail-closed error message so the caller is told what IS
+ * available rather than only what is missing.
+ */
+export function declaredStreamEnvironments() {
+    return Object.keys(ENVIRONMENT_STREAM_ENDPOINTS);
+}
 // ---------------------------------------------------------------------------
 // Internals
 // ---------------------------------------------------------------------------

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

@@ -11,9 +11,15 @@ export interface VideoCompressPresetOptionsInput {
      * single-pass-CRF by construction and two-pass target-size is unbuilt. The request
      * fails during execution, and the SDK cannot warn earlier — routing is decided
      * server-side at create-plan time, so there is nothing here to check it against.
-     * Short-form compresses honour it normally. Tracked by `zJN6XIi5`, blocked on a
-     * contract that can express per-execution-path availability. The same limit applies
-     * to {@link MergeOptions.targetSize}.
+     * The same limit applies to {@link MergeOptions.targetSize}.
+     * Short-form compresses honour it normally.
+     *
+     * The contract CAN now express this — `per_class_availability` scopes an option to
+     * a processing class, vendored at v2.195.0 and pinned by
+     * `tests/unit/per-class-availability-conformance.test.ts`. That buys an honest 422
+     * from the API at CREATE rather than a job dying mid-execution; it does NOT become
+     * a client-side gate, because routing is still decided server-side and a duration
+     * heuristic here would be wrong at the boundary. Tracked by `zJN6XIi5`.
      */
     readonly targetSize?: string | number;
     readonly crf?: number;