@giveitsmaller/sdk 0.22.0 → 0.26.0

package/dist/merge.d.ts

@@ -123,8 +123,14 @@ export interface MergeOptions {
      * construction and two-pass target-size is unbuilt. The request fails during
      * execution, and the SDK cannot warn earlier: the routing decision is made
      * server-side at create-plan time, so there is nothing here to check it against.
-     * Short-form merges honour it normally. Tracked by `zJN6XIi5`, blocked on a
-     * contract that can express per-execution-path availability.
+     * Short-form merges 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 transitionDuration?: number;

package/dist/merge.js

@@ -26,7 +26,7 @@
  * assets both fail fast so the caller saves bandwidth on typo'd composes.
  */
 import { uploadSource, jobOutputSource } from './types.js';
-import { GislConfigError, GislNetworkError, GislPerInputOptionsNotSupportedError, GislTimeoutError, GislUndeclaredAssetError, GislUnusedAssetError, SseEndedWithoutTerminal, } from './errors.js';
+import { GislConfigError, GislNetworkError, GislPerInputOptionsNotSupportedError, GislTimeoutError, GislUndeclaredAssetError, GislUnusedAssetError, GislStreamHostNotDeclaredError, SseEndedWithoutTerminal, } from './errors.js';
 import { _cappedProbeTimeoutMs, _checkAborted, _consumeSseToTerminal, _detectCompressMedia, _parseMaxWait, _pollToTerminal, _projectResult, } from './builder.js';
 import { Handle } from './handle.js';
 /**
@@ -445,7 +445,17 @@ export class MergeBuilder {
                 // TDqmkWpX: poll-fallback ONLY on a clean SSE stream-end or a typed
                 // transport error; rethrow everything else (timeout, abort, API, an
                 // onProgress callback throw, anything unexpected) so it isn't masked.
-                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;
                 }
             }

package/dist/sse.d.ts

@@ -6,7 +6,29 @@ import type { GislSseEvent, GislSseParseFailure } from './types.js';
  * - Chunk boundary buffering (events split across chunks)
  * - Multi-line `data:` fields (concatenated with newlines)
  * - Comment lines (`:` prefix) used as keep-alives
- * - `retry:` field (ignored, SDK manages its own reconnection)
+ * - `id:` and `retry:` fields — IGNORED, and neither is surfaced on
+ *   `GislSseEvent`
+ *
+ * 🔴 THIS SDK DOES NOT RECONNECT. It opens ONE stream and yields frames until
+ * the server ends it, the caller breaks, or the signal aborts. There is no
+ * retry loop, no backoff, and **no `Last-Event-ID` resumption** — so a dropped
+ * connection loses every event published while it was down, and the server
+ * cannot replay them.
+ *
+ * ⚠️ AN EARLIER VERSION OF THIS LINE READ "ignored, SDK manages its own
+ * reconnection", WHICH IS FALSE AND SAYS THE OPPOSITE OF THE TRUTH. A reader
+ * meeting it concluded retries were handled here. The poll-fallback in `run()`
+ * is a DIFFERENT TRANSPORT — it abandons the stream and polls
+ * `getWorkflowStatus` — not a reconnection, and it exists only on the
+ * ergonomic path. A direct `streamEvents` caller gets no recovery of any kind.
+ *
+ * ⇒ If you need to survive a drop, wrap this in your own loop AND reconcile
+ * the terminal state via `getWorkflowStatus` afterwards, because the gap is
+ * unrecoverable from the stream alone. See `docs/typescript/sse.md`.
+ *
+ * PHP and Python have carried this disclaimer since B2.2; TypeScript is the
+ * reference implementation both mirror and was the only one asserting the
+ * opposite (hub audit, 2026-08-29).
  *
  * `opts.signal` (optional): when it aborts, the underlying body reader is
  * cancelled. This is the ONLY way to promptly stop a stream parked on a

package/dist/sse.js

@@ -5,7 +5,29 @@
  * - Chunk boundary buffering (events split across chunks)
  * - Multi-line `data:` fields (concatenated with newlines)
  * - Comment lines (`:` prefix) used as keep-alives
- * - `retry:` field (ignored, SDK manages its own reconnection)
+ * - `id:` and `retry:` fields — IGNORED, and neither is surfaced on
+ *   `GislSseEvent`
+ *
+ * 🔴 THIS SDK DOES NOT RECONNECT. It opens ONE stream and yields frames until
+ * the server ends it, the caller breaks, or the signal aborts. There is no
+ * retry loop, no backoff, and **no `Last-Event-ID` resumption** — so a dropped
+ * connection loses every event published while it was down, and the server
+ * cannot replay them.
+ *
+ * ⚠️ AN EARLIER VERSION OF THIS LINE READ "ignored, SDK manages its own
+ * reconnection", WHICH IS FALSE AND SAYS THE OPPOSITE OF THE TRUTH. A reader
+ * meeting it concluded retries were handled here. The poll-fallback in `run()`
+ * is a DIFFERENT TRANSPORT — it abandons the stream and polls
+ * `getWorkflowStatus` — not a reconnection, and it exists only on the
+ * ergonomic path. A direct `streamEvents` caller gets no recovery of any kind.
+ *
+ * ⇒ If you need to survive a drop, wrap this in your own loop AND reconcile
+ * the terminal state via `getWorkflowStatus` afterwards, because the gap is
+ * unrecoverable from the stream alone. See `docs/typescript/sse.md`.
+ *
+ * PHP and Python have carried this disclaimer since B2.2; TypeScript is the
+ * reference implementation both mirror and was the only one asserting the
+ * opposite (hub audit, 2026-08-29).
  *
  * `opts.signal` (optional): when it aborts, the underlying body reader is
  * cancelled. This is the ONLY way to promptly stop a stream parked on a
@@ -172,7 +194,10 @@ export async function* parseSseStream(response, opts = {}) {
                         dataLines.push(fieldValue);
                         break;
                     case 'retry':
-                        // Ignored — SDK manages its own polling/reconnection
+                        // Ignored — and NOT because something else honours it. This SDK
+                        // never reconnects, so a server-suggested retry interval has no
+                        // consumer here. (Was "SDK manages its own polling/reconnection",
+                        // which claimed a behaviour that does not exist.)
                         break;
                 }
             }

package/dist/types.d.ts

@@ -2,6 +2,24 @@ import type { OperationType, OperationsSchemaResponse, OperationCapability, Outp
 import type { JobInputV2RoleEnum, NotifyConfig } from '@giveitsmaller/contracts/openapi';
 export interface GislClientConfig {
     baseUrl: string;
+    /**
+     * Host for the **SSE event stream** (`streamEvents`). The stream is served
+     * from a SECOND public entry point, separate from `baseUrl`: the API host
+     * fronts an integration with no response-streaming mode.
+     *
+     * Setting this moves the stream and **nothing else** — uploads,
+     * workflow-create and downloads keep using `baseUrl`. That is the reason it
+     * exists as its own field rather than being expressed by overriding
+     * `baseUrl`, which moves every call.
+     *
+     * When omitted, `gisl.create()` resolves it from the `environment` against
+     * the contract-declared stream hosts. It is **never derived from `baseUrl`**
+     * — if nothing declares a stream host for your configuration, `streamEvents`
+     * throws `GislStreamHostNotDeclaredError` rather than silently reusing the
+     * API host, and `run()` falls back to polling. See
+     * `ENVIRONMENT_STREAM_ENDPOINTS`.
+     */
+    streamBaseUrl?: string;
     apiKey?: string;
     headers?: Record<string, string>;
     timeout?: number;
@@ -169,12 +187,25 @@ export interface WorkflowProcessingPayload {
 export interface WorkflowCreatePayload {
     jobs: JobDefinitionPayload[];
     /**
-     * Flat single-job form (with `operations`): top-level input source, exactly
-     * equivalent to `jobs: [{ source, operations }]` (contracts D0Gsri8V, v2.64.0).
-     * The spec's `oneOf` makes `jobs` and `source`+`operations` mutually exclusive;
-     * the SDK builders always emit the explicit `jobs[]` form, so these are typed
-     * optional for spec-completeness (a consumer hand-building the flat form omits
-     * `jobs`). Builder adoption of the flat form is a follow-up.
+     * Flat single-job form (with `operations`): top-level input source, described by
+     * the contract as equivalent to `jobs: [{ source, operations }]` (contracts
+     * D0Gsri8V, v2.64.0). The spec's `oneOf` makes `jobs` and `source`+`operations`
+     * mutually exclusive.
+     *
+     * 🔴 **DO NOT SEND IT. The flat form is `x-availability: planned` as of contracts
+     * v2.201.0 and the server does not accept it.** Send `jobs[]`, which is what both
+     * SDK builders always emit — these two fields are typed optional for
+     * spec-completeness only.
+     *
+     * ⚠️ **The equivalence above is the DESIGN, not observed behaviour**, and it
+     * carried no availability marker from v2.64.0 until 2026-09-10 — which per
+     * ADR-0001 §1.4 meant it read as `stable`, a GA claim about a shape nothing
+     * accepts. No shipped SDK was ever exposed; a hand-built payload was.
+     *
+     * ⚠️ **A flat request is rejected today with a generic "At least one job is
+     * required", not the `feature_not_available` 422 a `planned` shape owes you.**
+     * So do not read that message as a fault in your own payload. Tracked against
+     * `compression_api`.
      */
     source?: WorkflowSourcePayload;
     /** Flat-form operation set (with `source`); equivalent to one job's `operations`. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@giveitsmaller/sdk",
-  "version": "0.22.0",
+  "version": "0.26.0",
   "description": "Node.js SDK for the GISL (Give It Smaller) file compression and processing API",
   "license": "Apache-2.0",
   "type": "module",
@@ -31,7 +31,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@giveitsmaller/contracts": "^0.65.0"
+    "@giveitsmaller/contracts": "^0.70.0"
   },
   "devDependencies": {
     "@types/node": "^22",
@@ -47,5 +47,13 @@
     "test": "vitest run",
     "test:parity": "vitest run tests/parity",
     "parity:update": "UPDATE_PARITY_FIXTURES=1 vitest run tests/parity"
+  },
+  "homepage": "https://docs.giveitsmaller.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/giveitsmaller/typescript-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/giveitsmaller/typescript-sdk/issues"
   }
 }