@giveitsmaller/sdk 0.21.0 → 0.25.0

package/README.md

@@ -56,6 +56,90 @@ for (const artifact of many.artifacts) console.log(artifact.url);
 > only under the same auth that created it; the upload-then-create flow above is
 > consistent by construction. Anonymous-intake uploads are unaffected.
 
+## Known limitation — browser SSE is restricted to one origin
+
+**Applies to the browser build only** (`@giveitsmaller/sdk/browser`), and **only to live progress
+streaming** — `streamEvents()`, and the `run({ useSSE: true })` default that uses it.
+
+Live progress is served from a **separate host** to the rest of the API, and that host allows
+**exactly one browser origin**: the Give It Smaller web app. So from a browser on any other origin:
+
+| what you are doing | works? |
+|---|---|
+| Uploads, workflow create, status, downloads | **Yes** — these stay on the main API host, which allows a **list** of origins (per environment) |
+| `streamEvents()` / SSE progress | **No** — blocked at the CORS preflight |
+
+**Affected consumers:** third-party sites embedding the SDK, embedded/iframe use, and **local
+development against staging** — which is the one most likely to bite first, because it looks like a
+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 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 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*
+request additionally needs the browser to opt in and the server to answer with matching credential
+headers — cookie domain scope alone is not sufficient, and this path is not verified.
+
+**Node consumers are unaffected** — CORS is a browser mechanism. The PHP SDK is unaffected for the
+same reason.
+
+> ⚠️ This limitation is invisible to automated testing: our own app's origin is allowed, so every
+> 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, 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.
@@ -446,13 +456,38 @@ export class MapEachBuilder {
             _checkAborted(options.signal);
             const remaining = deadline - Date.now();
             if (remaining <= 0) {
-                throw new GislTimeoutError(`maxWait elapsed during fan-out (after ${collectedArtifacts.length} child runs)`);
+                // Clean timeout BETWEEN children (no child in flight): the parent + the
+                // children completed so far are recoverable — carry their ids so the
+                // caller polls them and re-runs ONLY the never-created children (4G4FaA9X).
+                throw new GislFanOutTimeoutError(`maxWait elapsed during fan-out (after ${collectedChildResults.length} child runs)`, {
+                    completedWorkflowIds: collectedChildResults.map((r) => r.workflowId),
+                    parentWorkflowId: parentResult.workflowId,
+                });
             }
             const childBuilder = this.fn(art);
-            const childResult = await childBuilder.run({
-                ...options,
-                maxWait: remaining,
-            });
+            let childResult;
+            try {
+                childResult = await childBuilder.run({
+                    ...options,
+                    maxWait: remaining,
+                });
+            }
+            catch (err) {
+                // A CHILD's own deadline elapsed mid-run — the COMMON fan-out timeout
+                // path. Re-throw as a fan-out timeout so the parent + already-completed
+                // children + this in-flight child are ALL recoverable, instead of losing
+                // them behind the child's bare GislTimeoutError (4G4FaA9X). Other errors
+                // (config / API / item failure) propagate unchanged.
+                if (err instanceof GislTimeoutError) {
+                    throw new GislFanOutTimeoutError(`maxWait elapsed during fan-out while a child was running (${collectedChildResults.length} completed)`, {
+                        completedWorkflowIds: collectedChildResults.map((r) => r.workflowId),
+                        parentWorkflowId: parentResult.workflowId,
+                        workflowId: err.workflowId,
+                        cause: err,
+                    });
+                }
+                throw err;
+            }
             collectedChildResults.push(childResult);
             for (const childArt of childResult.artifacts)
                 collectedArtifacts.push(childArt);
@@ -567,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;
         }
@@ -649,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/image_output_routes.d.ts

@@ -85,6 +85,24 @@ export declare function resolveOutputRoute(inputToken: string, outputFormat: str
  * `compressMetadata` `per_value_availability`; same_format only (the only route
  * where value-level options like `metadata` are honored). Returns false when the
  * option / value / group is unknown (no gate).
+ *
+ * PURELY ADDITIVE (SB1wmTJz): planned if ANY consulted group marks this value planned.
+ * The historical group is still consulted, so **every verdict this returned before still
+ * holds** — the change can only turn a missed gate into a gate, never a gate into a
+ * pass. That direction matters: a new false ACCEPT would send a request the server
+ * rejects, which is the failure this function exists to prevent.
+ *
+ * Why not "most specific wins", which reads cleaner: it would flip `webp` +
+ * `color_profile: 'srgb'` from gated to un-gated, because `image_webp` defines
+ * `color_profile` with an empty `per_value_availability`. `RecipeOutputTest`
+ * deliberately pins webp srgb as GATED (v2.134 added `srgb: planned` to the generic
+ * group), and whether webp srgb actually works on the server is not something this
+ * layer can know. Un-gating it on an inference would be exactly the "confident answer
+ * from a check that could not tell you otherwise" pattern. Raised as a question instead.
+ *
+ * What this DOES fix: `image_svg` marks `output_format: 'original'` planned and the
+ * generic group does not, so an SVG input previously sailed through the one marker that
+ * mattered for it — on this gate and on the `output()` gate that shares it.
  */
 export declare function isPlannedValue(inputToken: string, optionKey: string, value: unknown): boolean;
 /**
@@ -117,4 +135,53 @@ export declare const COMPRESS_OPTION_VALUES: Readonly<Record<string, Readonly<Re
  * treated as unknown rather than coerced to a match.
  */
 export declare function isUnknownEnumValue(inputToken: string, optionKey: string, value: unknown): boolean;
+/** A contract `depends_on` rule for a compress-image output option (ehHU08Hu). */
+type OutputDependsOnRule = {
+    readonly requiresKey: string;
+    readonly requiresValue: string;
+} | {
+    readonly requiresAnyOf: readonly string[];
+};
+/**
+ * Contract `depends_on` per compress-image output option, mirroring
+ * `availability.json` `operations.compress.mime_groups.<group>.options.<opt>.depends_on`
+ * (ehHU08Hu). The rule is option-consistent across every image group that carries
+ * the option, so this is a FLAT table (validated group-by-group by
+ * `output-route-conformance.test.ts` / PHP `ImageOutputRouteConformanceTest`).
+ *
+ * Kept as a hand table — NOT a runtime read of the ~238KB availability sidecar —
+ * so the gate stays browser-safe with no contracts-version coupling, exactly like
+ * {@link COMPRESS_OPTION_VALUES}. Mirrored by PHP
+ * `ImageOutputRoutes::OUTPUT_OPTION_DEPENDS_ON`.
+ *
+ * Generalises the 86gAu5Tr auto_quality gate: every option's dependency is
+ * checked uniformly, so quality/lossless/target_size_bytes under `auto_quality`,
+ * `target_size_bytes` without `target_size`, `fit` without width/height, etc. are
+ * all rejected pre-upload instead of only the one hand-coded case.
+ */
+export declare const OUTPUT_OPTION_DEPENDS_ON: Readonly<Record<string, OutputDependsOnRule>>;
+/**
+ * Default of each depended-on key — an ABSENT key resolves to this before the
+ * dependency check (the server applies the same default). `encoding_mode`
+ * defaults to `quality`, so `quality`/`lossless` are valid with no explicit mode,
+ * but `target_size_bytes` / `quality_preset` are not. Pinned to `availability.json`
+ * defaults by the conformance suite.
+ */
+export declare const DEPENDS_ON_KEY_DEFAULTS: Readonly<Record<string, string>>;
+/**
+ * The first contract `depends_on` an already-lowered compress-image wire-option
+ * set violates for the resolved `route`, or `undefined` when every dependency is
+ * satisfied (ehHU08Hu). The caller ({@link Recipe} output lowering) throws
+ * `invalid_option_combination` with the returned message + conflictingFields.
+ * Only options PRESENT in `wireOptions` are checked; a scalar dependency reads
+ * the depended-on key's effective value ({@link DEPENDS_ON_KEY_DEFAULTS} when
+ * absent). A scalar (encoding_mode) dependency is skipped on a `format_change`
+ * (convert has its own deps); universal deps (e.g. `fit → width|height`, identical
+ * in compress + convert) run on BOTH routes. Mirrored by PHP
+ * `ImageOutputRoutes::dependsOnViolation`.
+ */
+export declare function dependsOnViolation(wireOptions: Readonly<Record<string, unknown>>, route: 'same_format' | 'format_change'): {
+    readonly message: string;
+    readonly conflictingFields: readonly string[];
+} | undefined;
 export {};