@giveitsmaller/sdk 0.22.0 → 0.25.0

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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@giveitsmaller/sdk",
-  "version": "0.22.0",
+  "version": "0.25.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.69.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"
   }
 }