@giveitsmaller/sdk 0.26.0 → 0.28.0

package/dist/_audit.js

@@ -75,12 +75,90 @@ export function _runAudit() {
     // methods EXIST and their signatures/return types match (indexed access errors
     // if a method is missing; the typed LHS errors if the signature drifts). The
     // RHS is a type-only cast (`null as unknown as …`) — no runtime property read.
-    const _creditsSig = null;
-    const _creditsUsageSig = null;
-    const _limitsSig = null;
+    //
+    // 🔴 THE ASSIGNMENT FORM BELOW WAS WEAKER THAN IT LOOKED, AND IS NOW FIXED.
+    // A single assignment tests ONE-WAY assignability, so a drift to `any` — or to any
+    // broader callable — stays assignable and PASSES. Assigning both ways does not fix
+    // it either: `any` is assignable in both directions. Real equality needs a
+    // conditional-type helper, and this repo already had one in
+    // `ergonomic/option_types.ts`, used there to pin option key-sets to the contract.
+    // ⇒ These three have been decorative since 8yqUXLCS shipped them. Tightened here
+    // rather than left one-way beside sixteen correct ones.
+    const _creditsSig = true;
+    const _creditsUsageSig = true;
+    const _limitsSig = true;
     void _creditsSig;
     void _creditsUsageSig;
     void _limitsSig;
+    // ── BQXpFV2R — the thirteen unpinned ergonomic symbols ────────────────────────
+    //
+    // ⚠️ EXISTENCE IS NOW THE SNAPSHOT'S JOB, not this list's.
+    // `tests/api-surface.test.ts` computes all 381 exports from source and compares
+    // them to a committed file, so a symbol cannot go unpinned because nobody
+    // remembered it — which is exactly how these thirteen were missed, alongside the
+    // whole `Gisl*Error` tree and `GislClient` itself. What remains here is the part a
+    // name-and-kind snapshot CANNOT express: SIGNATURES.
+    //
+    // ⚠️ COVERAGE BOUNDARY, stated so the gate is not mistaken for complete:
+    // signatures are pinned for the nine builders' execution methods and the three
+    // ErgonomicClient accessors above. A signature change to `GislClient`, `gisl`,
+    // `create` or `parseSseStream` is caught by NOTHING here. That is a deliberate
+    // scope line — widening it is ticket `YebCTMuY`.
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    const _recipeRun = true;
+    const _recipeSubmit = true;
+    const _filesRun = true;
+    const _filesSubmit = true;
+    const _mergedRun = true;
+    const _mergedSubmit = true;
+    const _archivedRun = true;
+    const _archivedSubmit = true;
+    const _watermarkedRun = true;
+    const _watermarkedSubmit = true;
+    const _batchRun = true;
+    const _opRun = true;
+    const _opSubmit = true;
+    const _mergeRun = true;
+    const _mergeSubmit = true;
+    // ⚠️ `Promise<Result>`, NOT `Promise<Result[]>`. A fan-out returns ONE aggregate
+    // result carrying `childWorkflowIds`, not an array. I wrote `Result[]` from
+    // assumption and this pin failed on its first compile — the gate catching a wrong
+    // belief before any mutation test, which is the whole point of writing it out.
+    const _mapEachRun = true;
+    void _recipeRun;
+    void _recipeSubmit;
+    void _filesRun;
+    void _filesSubmit;
+    void _mergedRun;
+    void _mergedSubmit;
+    void _archivedRun;
+    void _archivedSubmit;
+    void _watermarkedRun;
+    void _watermarkedSubmit;
+    void _batchRun;
+    void _opRun;
+    void _opSubmit;
+    void _mergeRun;
+    void _mergeSubmit;
+    void _mapEachRun;
     accept();
     accept();
     accept();

package/dist/builder.d.ts

@@ -20,9 +20,11 @@
  *   `SseOperationProgressData`. The `phase` discriminator is SDK-added;
  *   `status` values pass through verbatim from `SseOperationProgressDataStatusEnum`.
  *   The wire does NOT carry a `phase` field — see karen reality-check 2026-05-23.
- * - `.run()` requires `maxWait` (no default). The underlying `waitForWorkflow`
- *   has a 600s default for the poll fallback path; the ergonomic layer makes
- *   it MANDATORY in the type so callers consciously choose a deadline.
+ * - `.run()` takes an OPTIONAL options bag; `maxWait` defaults to
+ *   `DEFAULT_POLL_TIMEOUT_MS`, the same constant the poll fallback and every
+ *   file-first builder use. It was mandatory until 36AZ98FV, on the grounds
+ *   that inheriting that default would "leak silently" — while the SDK applied
+ *   it at fourteen sites regardless.
  */
 import type { GislClient } from './client.js';
 import type { OperationDownload, WorkflowStatusResponse, SseOperationProgressDataStatusEnum } from '@giveitsmaller/contracts/openapi';
@@ -235,12 +237,17 @@ export type ProgressEvent = UploadProgressEvent | ProcessingProgressEvent;
 export interface RunOptions {
     /**
      * Wall-clock deadline for the entire run (upload + create + wait + downloads).
-     * MANDATORY — the SDK does NOT supply a default because the underlying
-     * `waitForWorkflow` poll path has a 600s default that would otherwise
-     * leak silently. Pass `'2h'` / `'30m'` / `'120s'` as a string suffix or
-     * a number of milliseconds.
+     * Optional; defaults to {@link DEFAULT_POLL_TIMEOUT_MS}. Pass `'2h'` / `'30m'` /
+     * `'120s'` as a string suffix or a number of milliseconds.
+     *
+     * ⚠️ THIS WAS MANDATORY, on the stated grounds that a 600s default "would
+     * otherwise leak silently" (36AZ98FV). The same tree applied exactly that
+     * default at FOURTEEN sites across both SDKs, so the prohibition was refuted
+     * by the code it protected — and the file-first spelling of the same task
+     * accepted no arguments at all. One shared constant is what makes the rule
+     * unnecessary rather than what breaks it.
      */
-    readonly maxWait: string | number;
+    readonly maxWait?: string | number;
     /** Abort signal — terminates upload, SSE, and poll cleanly. */
     readonly signal?: AbortSignal;
     /** Progress callback receiving the SDK-synthesised discriminated union. */
@@ -265,8 +272,18 @@ export interface RunOptions {
     readonly probeTimeoutMs?: number;
 }
 export interface SubmitOptions {
-    /** Webhook URL — wired to `WorkflowCreateRequest.callback_url`. */
-    readonly webhook: string;
+    /**
+     * Webhook URL — wired to `WorkflowCreateRequest.callback_url`.
+     *
+     * Optional. `callback_url` is not in `WorkflowCreateRequest`'s required set and
+     * is typed `string | null`, so omitting it is contract-valid. It was mandatory
+     * here because the returned {@link Handle} carried no client and its
+     * `status()`/`wait()`/`result()` threw `no_client` — the webhook was the only
+     * channel by which the outcome could be learned. The handle is bound now
+     * (36AZ98FV), so omitting the webhook leaves a usable handle rather than a
+     * dead end.
+     */
+    readonly webhook?: string;
     /**
      * Best-effort probe-before-create for a VIDEO upload that went multipart.
      * Default `true`; set `false` to skip the wait. See {@link RunOptions}.
@@ -341,14 +358,14 @@ export declare class OperationBuilder {
      * fetches downloads, and projects to a flat `Result`. Throws
      * `GislTimeoutError` if `maxWait` elapses before terminal status.
      */
-    run(options: RunOptions): Promise<Result>;
+    run(options?: RunOptions): Promise<Result>;
     /**
      * Fire-and-forget: upload the input + create the workflow with a
      * `callback_url` wired to the supplied `webhook`, then return a
      * `Handle` (workflowId + webhookSecret) without waiting. The webhook
      * receives completion + the `webhookSecret` is the verifier seed.
      */
-    submit(options: SubmitOptions): Promise<Handle>;
+    submit(options?: SubmitOptions): Promise<Handle>;
     /**
      * Fan-out chain: run this builder to completion, then for each artifact
      * in the resulting `Result`, call `fn(artifactRef)` to construct a
@@ -391,8 +408,25 @@ export declare class MapEachBuilder {
      * run + every child's full run — each child sees the REMAINING budget
      * after the parent and prior children completed. Signal aborts cascade.
      */
-    run(options: RunOptions): Promise<Result>;
+    run(options?: RunOptions): Promise<Result>;
 }
+/**
+ * The clamp itself, exported for an EXACT test (codex d218bd6a0c62).
+ *
+ * ⚠️ **A behavioural test cannot pin this number, and that is why this seam
+ * exists.** Counting requests over a real deadline discriminates 1000 ms from
+ * 100 and from 500, but it cannot tell 1000 from 750 — the counts collide inside
+ * scheduler jitter. Widening the window to separate them makes the suite slower
+ * and the test flakier, in exchange for a weaker claim.
+ *
+ * ⇒ So the two tests do different jobs and neither is redundant: this one pins
+ * the VALUE exactly, and the `run()` test proves the clamp is on the path a
+ * caller actually travels. A value test alone would pass while nothing called
+ * it; a path test alone would pass at 750 ms.
+ *
+ * @internal — not re-exported from the package barrel.
+ */
+export declare function _clampPollIntervalMs(requested: number | undefined): number;
 /** @internal — exported for reuse by `merge.ts` (T3) and future builders. */
 export declare function _consumeSseToTerminal(client: GislClient, args: {
     workflowId: string;

package/dist/builder.js

@@ -20,10 +20,13 @@
  *   `SseOperationProgressData`. The `phase` discriminator is SDK-added;
  *   `status` values pass through verbatim from `SseOperationProgressDataStatusEnum`.
  *   The wire does NOT carry a `phase` field — see karen reality-check 2026-05-23.
- * - `.run()` requires `maxWait` (no default). The underlying `waitForWorkflow`
- *   has a 600s default for the poll fallback path; the ergonomic layer makes
- *   it MANDATORY in the type so callers consciously choose a deadline.
+ * - `.run()` takes an OPTIONAL options bag; `maxWait` defaults to
+ *   `DEFAULT_POLL_TIMEOUT_MS`, the same constant the poll fallback and every
+ *   file-first builder use. It was mandatory until 36AZ98FV, on the grounds
+ *   that inheriting that default would "leak silently" — while the SDK applied
+ *   it at fourteen sites regardless.
  */
+import { DEFAULT_POLL_TIMEOUT_MS } from './client.js';
 import { SseEventType, SseOperationProgressDataFromJSON, } from '@giveitsmaller/contracts/openapi';
 import { uploadSource } from './types.js';
 import { GislTimeoutError, GislFanOutTimeoutError, GislNetworkError, GislStreamHostNotDeclaredError, GislTransportError, SseEndedWithoutTerminal } from './errors.js';
@@ -253,8 +256,8 @@ export class OperationBuilder {
      * fetches downloads, and projects to a flat `Result`. Throws
      * `GislTimeoutError` if `maxWait` elapses before terminal status.
      */
-    async run(options) {
-        const deadline = Date.now() + _parseMaxWait(options.maxWait);
+    async run(options = {}) {
+        const deadline = Date.now() + _parseMaxWait(options.maxWait ?? DEFAULT_POLL_TIMEOUT_MS);
         const signal = options.signal;
         const onProgress = options.onProgress;
         const useSSE = options.useSSE ?? true;
@@ -333,7 +336,7 @@ export class OperationBuilder {
      * `Handle` (workflowId + webhookSecret) without waiting. The webhook
      * receives completion + the `webhookSecret` is the verifier seed.
      */
-    async submit(options) {
+    async submit(options = {}) {
         // Resolve presets before any I/O so a GislConfigError fails the
         // call before the upload — same fail-early contract as run().
         const resolved = this._resolve();
@@ -350,14 +353,22 @@ export class OperationBuilder {
             source: uploadSource(uploadResp.fileId),
             operations: [{ type: this.opType, options: resolved.wireOptions }],
         };
+        // ⚠️ OMIT THE KEY, do not set it to `undefined`. `JSON.stringify` drops an
+        // undefined value so the wire is the same either way — but an own property
+        // that exists with no value makes `'callback_url' in payload` TRUE, so any
+        // test asserting omission by key passes vacuously (codex 4763eb48189a).
         const payload = {
             jobs: [job],
-            callback_url: options.webhook,
+            ...(options.webhook !== undefined ? { callback_url: options.webhook } : {}),
         };
         const created = await this.client.createWorkflow(payload);
-        // No client passed → the returned Handle's status()/wait()/result()
-        // throw `no_client`; the operation-first submit reconciles via webhook.
-        return new Handle(created.workflowId, created.webhookSecret != null ? created.webhookSecret : undefined);
+        // ⚠️ THE CLIENT IS THE POINT (36AZ98FV). Without it the returned Handle's
+        // status()/wait()/result() throw `no_client`, which made `webhook` the only
+        // channel for this call's outcome and is why it used to be mandatory. The
+        // file-first path has always passed it (`file-first.ts`); the operation-first
+        // path did not, which is the same "demands what file-first does not" defect
+        // this ticket is about, one layer down.
+        return new Handle(created.workflowId, created.webhookSecret != null ? created.webhookSecret : undefined, this.client, null);
     }
     /**
      * Fan-out chain: run this builder to completion, then for each artifact
@@ -438,8 +449,8 @@ export class MapEachBuilder {
      * run + every child's full run — each child sees the REMAINING budget
      * after the parent and prior children completed. Signal aborts cascade.
      */
-    async run(options) {
-        const deadline = Date.now() + _parseMaxWait(options.maxWait);
+    async run(options = {}) {
+        const deadline = Date.now() + _parseMaxWait(options.maxWait ?? DEFAULT_POLL_TIMEOUT_MS);
         // 1. Run the parent.
         const remainingForParent = Math.max(1, deadline - Date.now());
         const parentResult = await this.parent.run({
@@ -540,6 +551,82 @@ function aggregateWorkflowStatus(statuses) {
 // ---------------------------------------------------------------------------
 // Internals — SSE + poll
 // ---------------------------------------------------------------------------
+/**
+ * Poll-fallback interval bounds, in milliseconds.
+ *
+ * 🔴 **THE FLOOR IS SIZED AGAINST A PUBLISHED RATE LIMIT, NOT AGAINST A
+ * BUSY-LOOP.** Its predecessor was 100 ms and its comment said it guarded
+ * against values "that would hammer getWorkflowStatus" — which is what you
+ * write when you are stopping a `0`/`NaN` spin, not when you have asked what
+ * the server allows. Same words, different standard, and nothing recorded
+ * which one applied (`r7bpd7MY`).
+ *
+ * The limit, read from `compression_api` rather than relayed:
+ * `Identity/Application/RateLimiting/TieredRateLimiterService.php:37-39`
+ * declares the `status_poll` family — guarding `GET /api/workflows/{id}/status`
+ * and `/downloads` — as a **sliding window of 60 requests per minute**, scaled
+ * at consume time (`:177`, `:188`) by `UserTier::rateLimitMultiplier()`
+ * (`Identity/Domain/Enums/UserTier.php:186-194`): Free and Basic ×1, Pro ×5,
+ * Max ×15, Enterprise ×20.
+ *
+ * ⇒ 100 ms is **600 requests/minute**: ten times the Free ceiling, twice Pro's,
+ * and inside budget only on Max and Enterprise. 1000 ms is the minimum legal
+ * interval on the tightest tier, so it is correct on every tier and needs no
+ * tier knowledge in the SDK.
+ *
+ * ⚠️ **THE WINDOW IS SLIDING, SO IT PUNISHES BURSTS, NOT JUST AVERAGES** — ten
+ * polls in the first second genuinely consume ten of the sixty.
+ *
+ * 📌 **AND THE BUDGET IS SHARED**: keyed per user id when authenticated, per IP
+ * when not. N SDK instances under one account spend one allowance between them,
+ * which is the argument for the conservative floor even on a paid tier — this
+ * process cannot see the other two.
+ *
+ * A tier-aware floor would need the caller's tier, which neither SDK reads
+ * today, and api has carded the effective-limits field as `4cHoxAcm` (Backlog,
+ * unscheduled — deliberately, because this flat floor ships without it).
+ *
+ * ⛔ **WHAT THIS DOES NOT DO, STATED SO NOBODY READS IT AS A GUARANTEE (codex
+ * 6b56d75f126d).** This is a PER-CALL floor, not a per-credential budget:
+ *
+ *   - **Two concurrent `run()`s under one credential issue ~120 requests/minute**
+ *     and blow a 60/minute bucket. Bounding that needs coordination the SDK does
+ *     not have — a shared limiter across calls, processes and machines.
+ *   - **`getWorkflowDownloads` draws on the SAME `status_poll` family**, so a run
+ *     that spends the last token on a status poll can be 429'd on the terminal
+ *     downloads call it needs to finish.
+ *
+ * ⇒ This change makes a SINGLE run legal on every tier. It does not make the SDK
+ * rate-limit-safe under concurrency, and the honest next step is retry-on-429
+ * with `Retry-After`, not a larger number here. Tracked separately.
+ */
+const MIN_POLL_INTERVAL_MS = 1_000;
+const DEFAULT_POLL_INTERVAL_MS = 2_000;
+/**
+ * The clamp itself, exported for an EXACT test (codex d218bd6a0c62).
+ *
+ * ⚠️ **A behavioural test cannot pin this number, and that is why this seam
+ * exists.** Counting requests over a real deadline discriminates 1000 ms from
+ * 100 and from 500, but it cannot tell 1000 from 750 — the counts collide inside
+ * scheduler jitter. Widening the window to separate them makes the suite slower
+ * and the test flakier, in exchange for a weaker claim.
+ *
+ * ⇒ So the two tests do different jobs and neither is redundant: this one pins
+ * the VALUE exactly, and the `run()` test proves the clamp is on the path a
+ * caller actually travels. A value test alone would pass while nothing called
+ * it; a path test alone would pass at 750 ms.
+ *
+ * @internal — not re-exported from the package barrel.
+ */
+export function _clampPollIntervalMs(requested) {
+    if (requested === undefined) {
+        return DEFAULT_POLL_INTERVAL_MS;
+    }
+    if (!Number.isFinite(requested) || requested < MIN_POLL_INTERVAL_MS) {
+        return MIN_POLL_INTERVAL_MS;
+    }
+    return requested;
+}
 const TERMINAL_STATUS = new Set([
     'completed',
     'failed',
@@ -705,20 +792,11 @@ export async function _consumeSseToTerminal(client, args) {
 export async function _pollToTerminal(client, args) {
     // Codex r1 medium 89130e3ea75d — guard against 0/negative/NaN/Infinity
     // pollIntervalMs values that would hammer getWorkflowStatus until maxWait.
-    const requested = args.pollIntervalMs;
-    let intervalMs;
-    if (requested === undefined) {
-        intervalMs = 2_000;
-    }
-    else if (!Number.isFinite(requested) || requested < 100) {
-        // Clamp to a safe minimum (100ms) rather than throw — small/zero/NaN
-        // were almost certainly a caller mistake, but ergonomic-layer
-        // shouldn't crash an otherwise valid run on this.
-        intervalMs = 100;
-    }
-    else {
-        intervalMs = requested;
-    }
+    // Clamp rather than throw — a zero/NaN/tiny value is a caller mistake, and the
+    // ergonomic layer should not crash an otherwise valid run over it. ONE call
+    // site, so the exact test above and the behavioural test below are talking
+    // about the same code.
+    const intervalMs = _clampPollIntervalMs(args.pollIntervalMs);
     while (true) {
         _checkAborted(args.signal);
         if (Date.now() >= args.deadline) {

package/dist/client.d.ts

@@ -2,6 +2,19 @@ import type { AudioWatermarkDecodeRequest, AudioWatermarkDecodeResponse, Externa
 import type { CreditsUsageOptions, ListWorkflowsOptions, GetSchemaOptions, GetSchemaResult, GislClientConfig, GislSseEvent, GislSseParseFailure, PreflightClipsResult, ProbeWaitOptions, ProbeWaitResult, ReadCapabilityOptions, UploadOptions, WaitOptions, WorkflowCreatePayload, _Sdk3HandCodedKeepaliveResult, _Sdk3HandCodedMultipartStatusResult, _Sdk3HandCodedPresignPartsResult } from './types.js';
 export declare const MULTIPART_CONCURRENCY_DEFAULT: 4;
 export declare const DEFAULT_MULTIPART_FIRST_CHUNK_SIZE: number;
+/**
+ * THE ONE DEADLINE DEFAULT (36AZ98FV). One wall-clock deadline covers the whole
+ * operation — upload, create, wait, downloads. Every entry point that takes a
+ * `maxWait` defaults to THIS value; a caller who passes one overrides it, and a
+ * caller who does not gets the same deadline whichever spelling they used.
+ *
+ * ⚠️ EXPORTED FOR REUSE, NOT FOR CONSUMERS. It is deliberately absent from the
+ * package entry points, so it does not reach the public API surface and the
+ * committed export snapshots do not move. Before this ticket the number was
+ * already named here and in PHP's `WorkflowConstants`, and hard-coded at
+ * FOURTEEN defaulting sites anyway — which is the duplication this replaces.
+ */
+export declare const DEFAULT_POLL_TIMEOUT_MS = 600000;
 export interface ValidationDetail {
     message: string;
     field?: string;

package/dist/client.js

@@ -63,7 +63,19 @@ const S3_MAX_MULTIPART_PARTS = 10_000;
 // exists to prevent). codex review (high).
 const RECOMMENDED_CHUNK_SIZE_MAX_BYTES = 104_857_600; // 100 MiB
 const DEFAULT_POLL_INTERVAL_MS = 2_000;
-const DEFAULT_POLL_TIMEOUT_MS = 600_000; // 10 min
+/**
+ * THE ONE DEADLINE DEFAULT (36AZ98FV). One wall-clock deadline covers the whole
+ * operation — upload, create, wait, downloads. Every entry point that takes a
+ * `maxWait` defaults to THIS value; a caller who passes one overrides it, and a
+ * caller who does not gets the same deadline whichever spelling they used.
+ *
+ * ⚠️ EXPORTED FOR REUSE, NOT FOR CONSUMERS. It is deliberately absent from the
+ * package entry points, so it does not reach the public API surface and the
+ * committed export snapshots do not move. Before this ticket the number was
+ * already named here and in PHP's `WorkflowConstants`, and hard-coded at
+ * FOURTEEN defaulting sites anyway — which is the duplication this replaces.
+ */
+export const DEFAULT_POLL_TIMEOUT_MS = 600_000; // 10 min
 /**
  * Re-tag a bare per-request transport {@link GislTimeoutError} with the workflow
  * it was scoped to, so a timed-out workflow read (status / downloads) stays

package/dist/credentials.d.ts

@@ -21,10 +21,10 @@ 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`.
  */
-export declare const ENVIRONMENT_ENDPOINTS: {
+export declare const ENVIRONMENT_ENDPOINTS: Readonly<{
     readonly prod: "https://api.giveitsmaller.com";
     readonly staging: "https://api.staging.giveitsmaller.com";
-};
+}>;
 export type Environment = keyof typeof ENVIRONMENT_ENDPOINTS;
 export declare const DEFAULT_ENDPOINT: "https://api.giveitsmaller.com";
 /**
@@ -61,8 +61,15 @@ export declare const DEFAULT_ENDPOINT: "https://api.giveitsmaller.com";
  * `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`.
+ * ⚠️ **FROZEN, AND PART OF THE PUBLIC SURFACE.** Both tables are exported from the
+ * package barrel because the SDK requires callers on the low-level surface to
+ * supply `streamBaseUrl` and previously published no way to learn the declared
+ * hosts. They are the SAME objects this module's resolvers read, so a consumer
+ * mutating one would have repointed the SDK's own resolution — hence
+ * `Object.freeze`, which makes that a no-op in sloppy mode and a `TypeError`
+ * under `'use strict'` (every ES module) rather than a silent redirection.
  */
-export declare const ENVIRONMENT_STREAM_ENDPOINTS: Partial<Record<Environment, string>>;
+export declare const ENVIRONMENT_STREAM_ENDPOINTS: Readonly<Partial<Record<Environment, string>>>;
 export interface ResolveCredentialsOptions {
     /** Explicit API key — highest precedence. */
     readonly apiKey?: string;

package/dist/credentials.js

@@ -25,10 +25,10 @@ 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`.
  */
-export const ENVIRONMENT_ENDPOINTS = {
+export const ENVIRONMENT_ENDPOINTS = Object.freeze({
     prod: 'https://api.giveitsmaller.com',
     staging: 'https://api.staging.giveitsmaller.com',
-};
+});
 export const DEFAULT_ENDPOINT = ENVIRONMENT_ENDPOINTS.prod;
 /**
  * Named environments → **SSE stream host**. A SECOND host, deliberately
@@ -64,11 +64,18 @@ export const DEFAULT_ENDPOINT = ENVIRONMENT_ENDPOINTS.prod;
  * `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`.
+ * ⚠️ **FROZEN, AND PART OF THE PUBLIC SURFACE.** Both tables are exported from the
+ * package barrel because the SDK requires callers on the low-level surface to
+ * supply `streamBaseUrl` and previously published no way to learn the declared
+ * hosts. They are the SAME objects this module's resolvers read, so a consumer
+ * mutating one would have repointed the SDK's own resolution — hence
+ * `Object.freeze`, which makes that a no-op in sloppy mode and a `TypeError`
+ * under `'use strict'` (every ES module) rather than a silent redirection.
  */
-export const ENVIRONMENT_STREAM_ENDPOINTS = {
+export const ENVIRONMENT_STREAM_ENDPOINTS = Object.freeze({
     prod: 'https://stream.giveitsmaller.com',
     staging: 'https://stream.staging.giveitsmaller.com',
-};
+});
 // ---------------------------------------------------------------------------
 // Public resolvers
 // ---------------------------------------------------------------------------
@@ -241,7 +248,29 @@ function readEnv(name) {
         return null;
     }
     const value = process.env[name];
-    return typeof value === 'string' && value.length > 0 ? value : null;
+    // 🔴 A WHITESPACE-ONLY ENV VAR IS UNSET, and the presence check is what says
+    // so — the value itself is returned UNTOUCHED.
+    //
+    // `resolveStreamEndpoint` already trims the `streamBaseUrl` OPTION before its
+    // presence check (codex a7f5ec9f0d32) and this path did not, so the two
+    // disagreed about the same question: `GISL_STREAM_BASE_URL='   '` was returned
+    // verbatim as the stream host — a URL made of spaces — while the equivalent
+    // option resolved to the environment's declared host. The same asymmetry let a
+    // blank `GISL_BASE_URL` count as "the API host was configured" and suppress
+    // the production stream fallback.
+    //
+    // ⚠️ Presence only. A non-blank value is NOT trimmed here: silently altering a
+    // value the caller supplied is how you end up connecting somewhere they did
+    // not name. Blank means unset; anything else means what it says.
+    //
+    // Reported by compression_e2e, 2026-09-15: a whitespace-only value is TRUTHY
+    // in JavaScript, so a consumer's `if (url)` guard passes and the SDK then
+    // fails downstream — the mismatch only exists because the two sides answer
+    // "is this set?" differently.
+    if (typeof value !== 'string' || value.trim() === '') {
+        return null;
+    }
+    return value;
 }
 function defaultProfilePath() {
     const homeDir = readEnv('HOME') ?? readEnv('USERPROFILE');

package/dist/ergonomic/option_types.d.ts

@@ -215,6 +215,7 @@ export interface OutputOptions {
     /** JPEG/WebP lossless. Honored: same_format jpeg/webp (stable since v2.101.0). */
     lossless?: boolean;
 }
+export type Equal<A, B> = (<T>() => T extends A ? 1 : 2) extends (<T>() => T extends B ? 1 : 2) ? true : false;
 /**
  * The user-supplyable option keys per verb (excludes positional-owned keys).
  * Exported for the wire-key conformance guard, which asserts each tuple ∪ its

package/dist/file-first.d.ts

@@ -492,8 +492,12 @@ export declare class Recipe {
      * Composite an image OVERLAY onto this file (a multi-input op). `overlay` is a
      * secondary file-NODE (a {@link Recipe} — e.g. `client.file('logo.png')`),
      * itself optionally processed first. Routes by THIS file's effective media:
-     * image base → `image_watermark` (stable), video base → `video_watermark`
-     * (beta). Audio/document/animated-GIF/unsupported-subtype/undetectable bases
+     * image base → `image_watermark` (stable).
+     * A VIDEO base is REFUSED: `video_watermark` was withdrawn to `planned`
+     * by contracts v2.203.0, so this verb throws before any upload rather than
+     * building a workflow the server would reject. The routing is unchanged and
+     * returns when the operation is re-listed.
+     * Audio/document/animated-GIF/unsupported-subtype/undetectable bases
      * throw locally BEFORE any upload (the planned-op gate). `options` carries the
      * wire watermark options (`anchor`, `opacity`, `margin_x`, `margin_y`,
      * `overlay_width`, or `overlays[]` for the multi-overlay stack). Returns a
@@ -671,7 +675,7 @@ export declare const WATERMARK_CAPABILITY: {
     readonly video_watermark: {
         readonly video: {
             readonly mimes: readonly ["video/mp4", "video/webm"];
-            readonly availability: "stable";
+            readonly availability: "planned";
         };
     };
 };

package/dist/file-first.js

@@ -11,6 +11,7 @@
  */
 import { GislConfigError, GislItemFailedError, GislNetworkError, GislNoSuchKeyError, GislSinkError, GislStreamHostNotDeclaredError, GislTimeoutError, SseEndedWithoutTerminal } from './errors.js';
 import { _detectCompressMedia, _detectAudioLossless, _consumeSseToTerminal, _pollToTerminal, _parseMaxWait, _checkAborted, _cappedProbeTimeoutMs, } from './builder.js';
+import { DEFAULT_POLL_TIMEOUT_MS } from './client.js';
 import { LazyHttpDownloader } from './lazy-downloader.js';
 import { resolveCompressOptions, } from './ergonomic/preset_resolver.js';
 import { validateVerbOptions, assertThumbnailDimensions } from './ergonomic/option_validation.js';
@@ -821,8 +822,12 @@ export class Recipe {
      * Composite an image OVERLAY onto this file (a multi-input op). `overlay` is a
      * secondary file-NODE (a {@link Recipe} — e.g. `client.file('logo.png')`),
      * itself optionally processed first. Routes by THIS file's effective media:
-     * image base → `image_watermark` (stable), video base → `video_watermark`
-     * (beta). Audio/document/animated-GIF/unsupported-subtype/undetectable bases
+     * image base → `image_watermark` (stable).
+     * A VIDEO base is REFUSED: `video_watermark` was withdrawn to `planned`
+     * by contracts v2.203.0, so this verb throws before any upload rather than
+     * building a workflow the server would reject. The routing is unchanged and
+     * returns when the operation is re-listed.
+     * Audio/document/animated-GIF/unsupported-subtype/undetectable bases
      * throw locally BEFORE any upload (the planned-op gate). `options` carries the
      * wire watermark options (`anchor`, `opacity`, `margin_x`, `margin_y`,
      * `overlay_width`, or `overlays[]` for the multi-overlay stack). Returns a
@@ -920,7 +925,7 @@ export class Recipe {
         if (this.client === undefined) {
             throw new GislConfigError('Recipe.run() requires a client; build the recipe via gisl().file(...) rather than constructing Recipe directly.', { reason: 'no_client' });
         }
-        const deadline = Date.now() + _parseMaxWait(options.maxWait ?? 600_000);
+        const deadline = Date.now() + _parseMaxWait(options.maxWait ?? DEFAULT_POLL_TIMEOUT_MS);
         // 1+2. Upload (when required) + create the workflow. Shared with submit()
         // (which passes a webhook → callback_url). run() passes no webhook.
         const created = await this._uploadAndCreate(undefined, deadline, onProgress, signal, options.probeBeforeCreate, options.probeTimeoutMs);
@@ -1372,7 +1377,14 @@ export const WATERMARK_CAPABILITY = {
         image_bmp: { mimes: ['image/bmp'], availability: 'stable' },
     },
     video_watermark: {
-        video: { mimes: ['video/mp4', 'video/webm'], availability: 'stable' },
+        // 🔴 WITHDRAWN to `planned` by contracts v2.203.0 — withdrawn 2026-09-15, tag cut 2026-09-16 —
+        // after three measured staging proofs. It was `stable` — a worker EXISTS,
+        // and it cannot serve the ceiling this contract advertised. That is a
+        // different kind of `planned` from `image_gif` below, where nothing is built
+        // yet, and the two have opposite remedies; no contract field separates them
+        // (contracts SYQhXb6R). `_WATERMARK_SHIPPABLE` treats both as not-shippable,
+        // which is right for the gate and worth knowing when rendering a reason.
+        video: { mimes: ['video/mp4', 'video/webm'], availability: 'planned' },
     },
 };
 const _WATERMARK_SHIPPABLE = new Set(['stable', 'beta']);
@@ -1472,8 +1484,19 @@ function _resolveWatermarkWireOp(base) {
                 if (group.mimes.includes(mime)) {
                     if (_WATERMARK_SHIPPABLE.has(group.availability))
                         return wireOp;
-                    throw new GislConfigError(`watermark for ${mime} bases is not yet available (${wireOp} is '${group.availability}'). ` +
-                        'The contract schema is defined but the server returns feature_not_available until it ships.', { reason: 'feature_not_available' });
+                    // ⚠️ "NOT YET" WAS A PROMISE THE CONTRACT DOES NOT MAKE. This message
+                    // used to say the schema "is defined but the server returns
+                    // feature_not_available until it ships" — true for a capability nobody
+                    // has built, and FALSE for one that was `stable` last week and has been
+                    // WITHDRAWN (contracts v2.203.0 did exactly that to `video_watermark`).
+                    // Telling a user to wait for something that shipped and was pulled is
+                    // worse than telling them nothing. No contract field separates the two
+                    // kinds yet (contracts SYQhXb6R), so the wording states only what is
+                    // true of both.
+                    throw new GislConfigError(`watermark for ${mime} bases is not available (${wireOp} is ` +
+                        `'${group.availability}' in the contract this SDK was built against). ` +
+                        'Workflow-create would return feature_not_available, so this is refused ' +
+                        'before any upload. Check getSchema() for the current server answer.', { reason: 'feature_not_available' });
                 }
             }
         }
@@ -1754,7 +1777,7 @@ export class FilesRecipe {
         if (this.client === undefined) {
             throw new GislConfigError('FilesRecipe.run() requires a client; build the fan-out via gisl().files(...) rather than constructing FilesRecipe directly.', { reason: 'no_client' });
         }
-        const deadline = Date.now() + _parseMaxWait(options.maxWait ?? 600_000);
+        const deadline = Date.now() + _parseMaxWait(options.maxWait ?? DEFAULT_POLL_TIMEOUT_MS);
         // 1+2. Upload EVERY input + create ONE multi-job workflow. Shared with
         // submit() (which passes a webhook → callback_url and no deadline).
         const created = await this._uploadAllAndCreate(undefined, deadline, onProgress, signal, options.probeBeforeCreate, options.probeTimeoutMs);
@@ -1983,7 +2006,7 @@ export class MergedRecipe {
         if (this.client === undefined) {
             throw new GislConfigError('MergedRecipe.run() requires a client; build the merge via gisl().files(...).merge(...) rather than constructing MergedRecipe directly.', { reason: 'no_client' });
         }
-        const deadline = Date.now() + _parseMaxWait(options.maxWait ?? 600_000);
+        const deadline = Date.now() + _parseMaxWait(options.maxWait ?? DEFAULT_POLL_TIMEOUT_MS);
         const created = await this._uploadAllAndCreate(undefined, deadline, onProgress, signal, options.probeBeforeCreate, options.probeTimeoutMs);
         const finalStatus = await _awaitTerminal(this.client, {
             workflowId: created.workflowId,
@@ -2196,7 +2219,7 @@ export class ArchivedRecipe {
         if (this.client === undefined) {
             throw new GislConfigError('ArchivedRecipe.run() requires a client; build the bundle via gisl().files(...).archive(...) rather than constructing ArchivedRecipe directly.', { reason: 'no_client' });
         }
-        const deadline = Date.now() + _parseMaxWait(options.maxWait ?? 600_000);
+        const deadline = Date.now() + _parseMaxWait(options.maxWait ?? DEFAULT_POLL_TIMEOUT_MS);
         const created = await this._uploadAllAndCreate(undefined, deadline, onProgress, signal, options.probeBeforeCreate, options.probeTimeoutMs);
         const finalStatus = await _awaitTerminal(this.client, {
             workflowId: created.workflowId,
@@ -2409,7 +2432,7 @@ export class WatermarkedRecipe {
         if (this.client === undefined) {
             throw new GislConfigError('WatermarkedRecipe.run() requires a client; build the watermark via gisl().file(...).watermark(...) rather than constructing WatermarkedRecipe directly.', { reason: 'no_client' });
         }
-        const deadline = Date.now() + _parseMaxWait(options.maxWait ?? 600_000);
+        const deadline = Date.now() + _parseMaxWait(options.maxWait ?? DEFAULT_POLL_TIMEOUT_MS);
         const created = await this._uploadAllAndCreate(undefined, deadline, onProgress, signal, options.probeBeforeCreate, options.probeTimeoutMs);
         const finalStatus = await _awaitTerminal(this.client, {
             workflowId: created.workflowId,
@@ -2597,7 +2620,7 @@ export class BatchRecipe {
         // FilesRecipe behavior and is intentionally NOT closed here — a TS
         // path-precheck would diverge batch from FilesRecipe.)
         this.validatePreUpload();
-        const deadline = Date.now() + _parseMaxWait(options.maxWait ?? 600_000);
+        const deadline = Date.now() + _parseMaxWait(options.maxWait ?? DEFAULT_POLL_TIMEOUT_MS);
         // 1+2. Upload each entry's input + create ONE multi-job workflow. batch v1
         // sends NO webhook (run()-only), so `callback_url` is omitted from the
         // payload (the closure receives `callbackUrl` undefined).

package/dist/handle.js

@@ -32,6 +32,7 @@
  *
  * Mirrors the PHP `Gisl\Sdk\Ergonomic\Handle` + `Gisl\Sdk\Ergonomic\StatusSnapshot`.
  */
+import { DEFAULT_POLL_TIMEOUT_MS } from './client.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';
@@ -154,7 +155,7 @@ export class Handle {
      * @throws {GislConfigError} reason `no_client` when no client is bound.
      * @throws {GislTimeoutError} when `maxWait` elapses before terminal.
      */
-    async wait(maxWait = 600_000, onProgress) {
+    async wait(maxWait = DEFAULT_POLL_TIMEOUT_MS, onProgress) {
         const client = this.requireClient();
         const deadline = Date.now() + _parseMaxWait(maxWait);
         let finalStatus;

package/dist/index.core.d.ts

@@ -19,6 +19,7 @@ export type { WatermarkWireOp } from './file-first.js';
 export { BatchRecipe } from './file-first.js';
 export { Handle, StatusSnapshot } from './handle.js';
 export { gisl, create } from './gisl.js';
+export { ENVIRONMENT_ENDPOINTS, ENVIRONMENT_STREAM_ENDPOINTS } from './credentials.js';
 export type { GislCreateOptions, Environment, ErgonomicClient, SingleInputOperationType, MultiInputOperationType, } from './gisl.js';
 export { presetDefaults, PresetDefaults, type PresetMedia, type PresetOp, type AnyPresetOptions, ImageCompressPresetOptions, type ImageCompressPresetOptionsInput, AudioCompressPresetOptions, type AudioCompressPresetOptionsInput, VideoCompressPresetOptions, type VideoCompressPresetOptionsInput, DocumentOfficeCompressPresetOptions, type DocumentOfficeCompressPresetOptionsInput, DocumentOdfCompressPresetOptions, type DocumentOdfCompressPresetOptionsInput, DocumentEpubCompressPresetOptions, type DocumentEpubCompressPresetOptionsInput, OptimizeFor, ImageMetadataPolicy, ImageFormat, VideoCodec, VideoPreset, VideoFit, AudioBitrate, AudioCodec, AudioSampleRate, } from './ergonomic/presets/index.js';
 export { OperationBuilder, MapEachBuilder } from './builder.js';

package/dist/index.core.js

@@ -90,6 +90,31 @@ export { Handle, StatusSnapshot } from './handle.js';
 // credential-chain types. `gisl.anonymous()` (public export) lands once
 // the anonymous-capable operation allowlist is non-empty (plan §12).
 export { gisl, create } from './gisl.js';
+// 🔑 THE TWO ENDPOINT TABLES, EXPORTED BECAUSE THE SDK DEMANDS A VALUE IT DID
+// NOT PUBLISH (e2e, 2026-09-15).
+//
+// `streamEvents()` fails CLOSED: `resolveStreamEndpoint` returns `null` rather
+// than deriving a stream host from `baseUrl`, because deriving one is what put
+// production on the gateway path. That design is right and is not changing.
+//
+// But its consequence is that a low-level `new GislClient({…})` caller MUST
+// supply `streamBaseUrl` — and until now the table of declared hosts was
+// reachable by no import a consumer could write: the `exports` map admits only
+// `.` and `./browser`, and neither barrel re-exported these. ⇒ Every such
+// consumer hard-codes the hosts. A library that fails closed on a value and
+// does not export the value converts good design into N private copies that
+// drift, and the copies are invisible until one is wrong.
+//
+// ⚠️ A SET OF HOSTS IS NOT ENOUGH, WHICH IS WHY THIS EXPORTS THE OBJECTS
+// RATHER THAN A LIST. e2e's interim guard read our shipped `dist` as text and
+// compared host sets in both directions — it could not have caught staging and
+// prod being SWAPPED, which is the exact mistake that sends a credentialed
+// stream request to the wrong environment. The PAIRING is the thing worth
+// exporting.
+//
+// Frozen at their definition: these are the same objects the resolver reads, so
+// a consumer mutating one would have repointed the SDK's own resolution.
+export { ENVIRONMENT_ENDPOINTS, ENVIRONMENT_STREAM_ENDPOINTS } from './credentials.js';
 // Ergonomic preset defaults (T4a / VhIj4S7T) — typed leaf DTOs + immutable
 // `PresetDefaults` builder + `presetDefaults()` factory + ergonomic enum
 // re-exports. Resolver wiring (T4b) consumes `PresetDefaults.cellFor()`.

package/dist/merge.d.ts

@@ -168,8 +168,8 @@ export declare class MergeBuilder {
      * and deduped on upload (one upload per unique declared asset).
      */
     sequence(...entries: SequenceEntry[]): this;
-    run(options: RunOptions): Promise<Result>;
-    submit(options: SubmitOptions): Promise<Handle>;
+    run(options?: RunOptions): Promise<Result>;
+    submit(options?: SubmitOptions): Promise<Handle>;
     /**
      * Resolve the declared assets + sequence (or fall back to declared order),
      * dedupe by identity, and run the local validators. The returned plan

package/dist/merge.js

@@ -25,6 +25,7 @@
  * Local validation runs BEFORE any upload — undeclared refs and unused
  * assets both fail fast so the caller saves bandwidth on typo'd composes.
  */
+import { DEFAULT_POLL_TIMEOUT_MS } from './client.js';
 import { uploadSource, jobOutputSource } from './types.js';
 import { GislConfigError, GislNetworkError, GislPerInputOptionsNotSupportedError, GislTimeoutError, GislUndeclaredAssetError, GislUnusedAssetError, GislStreamHostNotDeclaredError, SseEndedWithoutTerminal, } from './errors.js';
 import { _cappedProbeTimeoutMs, _checkAborted, _consumeSseToTerminal, _detectCompressMedia, _parseMaxWait, _pollToTerminal, _projectResult, } from './builder.js';
@@ -82,8 +83,8 @@ export class MergeBuilder {
         this.sequenceEntries = entries;
         return this;
     }
-    async run(options) {
-        const deadline = Date.now() + _parseMaxWait(options.maxWait);
+    async run(options = {}) {
+        const deadline = Date.now() + _parseMaxWait(options.maxWait ?? DEFAULT_POLL_TIMEOUT_MS);
         const signal = options.signal;
         const onProgress = options.onProgress;
         const useSSE = options.useSSE ?? true;
@@ -146,7 +147,7 @@ export class MergeBuilder {
         const mergeDownloads = downloads.downloads.filter((d) => d.ref === 'merge');
         return _projectResult(finalStatus, mergeDownloads, this.opOptionsForResolved(plan.mediaKind));
     }
-    async submit(options) {
+    async submit(options = {}) {
         const plan = this.planSequence();
         const probeTargets = [];
         const uploadedByAssetId = await this.uploadUniqueAssets(plan.uniqueAssets, { probeTargets });
@@ -154,11 +155,17 @@ export class MergeBuilder {
         // Fire-and-forget — no deadline, so no cap (mirrors Recipe::submit()).
         await this.waitForVideoProbes(probeTargets, options.probeBeforeCreate, options.probeTimeoutMs, undefined, undefined);
         const payload = this.buildPayload(plan, uploadedByAssetId);
-        payload.callback_url = options.webhook;
+        // Set only when present — an own `callback_url: undefined` would make a
+        // key-presence assertion pass vacuously. See builder.ts.
+        if (options.webhook !== undefined)
+            payload.callback_url = options.webhook;
         const created = await this.client.createWorkflow(payload);
-        // No client passed → the returned Handle's status()/wait()/result()
-        // throw `no_client`; the merge submit reconciles via webhook.
-        return new Handle(created.workflowId, created.webhookSecret != null ? created.webhookSecret : undefined);
+        // ⚠️ The client is passed so the returned Handle is usable (36AZ98FV). This
+        // comment previously read "No client passed → the returned Handle's
+        // status()/wait()/result() throw `no_client`; the merge submit reconciles via
+        // webhook" — an accurate description of a defect. `webhook` is optional now,
+        // so an unbound handle here would leave a submit with no outcome channel at all.
+        return new Handle(created.workflowId, created.webhookSecret != null ? created.webhookSecret : undefined, this.client, null);
     }
     // ---------------------------------------------------------------------------
     /**

package/dist/types.d.ts

@@ -361,7 +361,7 @@ export interface ReadCapabilityOptions {
 export interface WaitOptions {
     /** Poll interval in milliseconds (default: 2000) */
     intervalMs?: number;
-    /** Maximum wait time in milliseconds (default: 600000 = 10 min) */
+    /** Maximum wait time in milliseconds (default: `DEFAULT_POLL_TIMEOUT_MS`, 10 min). */
     timeoutMs?: number;
     /** Called after each poll with current status */
     onPoll?: (status: string) => void;

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@giveitsmaller/sdk",
-  "version": "0.26.0",
+  "version": "0.28.0",
+  "gislContractsSpec": "v2.203.0",
   "description": "Node.js SDK for the GISL (Give It Smaller) file compression and processing API",
   "license": "Apache-2.0",
   "type": "module",
@@ -31,7 +32,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@giveitsmaller/contracts": "^0.70.0"
+    "@giveitsmaller/contracts": "^0.72.0"
   },
   "devDependencies": {
     "@types/node": "^22",
@@ -46,7 +47,8 @@
     "check": "tsc --noEmit",
     "test": "vitest run",
     "test:parity": "vitest run tests/parity",
-    "parity:update": "UPDATE_PARITY_FIXTURES=1 vitest run tests/parity"
+    "parity:update": "UPDATE_PARITY_FIXTURES=1 vitest run tests/parity",
+    "api:update": "UPDATE_API_SNAPSHOT=1 vitest run tests/api-surface.test.ts"
   },
   "homepage": "https://docs.giveitsmaller.com",
   "repository": {