@giveitsmaller/sdk 0.21.0 → 0.25.0

package/dist/handle.js

@@ -32,7 +32,7 @@
  *
  * Mirrors the PHP `Gisl\Sdk\Ergonomic\Handle` + `Gisl\Sdk\Ergonomic\StatusSnapshot`.
  */
-import { GislConfigError, GislNetworkError, GislResultNotReadyError, GislTimeoutError, SseEndedWithoutTerminal, } from './errors.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';
 import { LazyHttpDownloader } from './lazy-downloader.js';
@@ -172,7 +172,17 @@ export class Handle {
             // (GislNetworkError). Everything else (timeout, abort, API, 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;
             }
             finalStatus = await _pollToTerminal(client, {

package/dist/http-downloader.js

@@ -7,7 +7,7 @@
 import { createWriteStream } from 'node:fs';
 import { Readable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
-import { GislNetworkError, GislSinkError } from './errors.js';
+import { GislDownloadHttpError, GislRequestNotSentError, GislSinkError, GislTransportError, } from './errors.js';
 /**
  * Streams a (typically pre-signed) URL to a local path without buffering the
  * whole body in memory. Pre-signed download URLs require no SDK auth, so this
@@ -21,22 +21,40 @@ export class HttpDownloader {
         // on the RunResult sink side. Parity-critical: the FF1 sink contract tells
         // callers to narrow with instanceof, so the source-read error type must
         // match across languages.
+        // codex f46340e1d58a: a malformed URL fails DETERMINISTICALLY, so it must
+        // not land in the always-retryable bucket with DNS and TLS. `fetch` rejects
+        // both with an indistinguishable TypeError, so the only way to tell them
+        // apart is to check BEFORE the call — which also gives
+        // GislRequestNotSentError a real throw site in TypeScript rather than
+        // leaving it declared-but-dormant.
+        try {
+            new URL(url);
+        }
+        catch {
+            throw new GislRequestNotSentError(`Download source is not a valid URL: ${url}`);
+        }
         let res;
         try {
             res = await fetch(url);
         }
         catch (cause) {
             // A rejected fetch (DNS, TCP, TLS, mid-flight disconnect) must surface as
-            // GislNetworkError too — not the raw TypeError — so callers can narrow
-            // every download-source failure with `instanceof GislNetworkError`
-            // (codex review medium).
-            throw new GislNetworkError(`Failed to fetch download source: ${cause instanceof Error ? cause.message : String(cause)}`);
+            // a typed error — not the raw TypeError — so callers can narrow every
+            // download-source failure with `instanceof GislNetworkError`
+            // (codex review medium). t2qCrjdr: TRANSPORT specifically, so the
+            // retry advice is `true` here and status-derived below.
+            throw new GislTransportError(`Failed to fetch download source: ${cause instanceof Error ? cause.message : String(cause)}`);
         }
         if (!res.ok) {
-            throw new GislNetworkError(`Download failed with status ${res.status}`);
+            // t2qCrjdr: the server was REACHED and refused. Carries the status so a
+            // consumer telling a permanent 404 from a transient 503 never has to
+            // parse the message.
+            throw new GislDownloadHttpError(`Download failed with status ${res.status}`, res.status);
         }
         if (res.body === null) {
-            throw new GislNetworkError('Download response had no body');
+            // 2xx with nothing in it — the server did not refuse, it under-delivered.
+            // Transport rather than HTTP, and retrying is the right advice.
+            throw new GislTransportError('Download response had no body');
         }
         // `fetch`'s WHATWG ReadableStream and Node's `stream/web` ReadableStream
         // are structurally the same at runtime but typed in two different lib

package/dist/index.core.d.ts

@@ -3,7 +3,7 @@ export { parseSseStream } from './sse.js';
 export type { CreditsUsageOptions, ListWorkflowsOptions, GetSchemaOptions, GetSchemaResult, CapabilitiesSnapshot, PreflightClipError, PreflightClipsResult, ProbeWaitOptions, ProbeWaitResult, GislClientConfig, GislSseEvent, GislSseParseFailure, UploadOptions, WaitOptions, WorkflowCreatePayload, OperationDef, WorkflowSourcePayload, MultiInputSourcePayload, UploadSourcePayload, JobOutputSourcePayload, ExternalImportSourcePayload, ConnectionSourcePayload, JobInputV2Payload, JobDefinitionPayload, ExternalDestinationPayload, DeliveryPayload, DeliveryModePayload, DeliveryBundleFormatPayload, DeliverySelectionPayload, DeliverySelectionTypePayload, DeliveryOutputRefPayload, WorkflowProcessingPayload, ProcessingClassHintPayload, MultipartCheckpointState, _Sdk3HandCodedUploadedPart, _Sdk3HandCodedMultipartStatusResult, _Sdk3HandCodedPresignedPart, _Sdk3HandCodedPresignPartsResult, _Sdk3HandCodedKeepaliveResult, } from './types.js';
 export { uploadSource, jobOutputSource, externalImportSource, connectionSource, } from './types.js';
 export type { GislConfigErrorMetadata } from './errors.js';
-export { GislError, GislApiError, GislValidationError, GislBalanceExhaustedError, GislLongFormConcurrencyError, GislTierRestrictedError, GislFeatureTierRestrictedError, GislFeatureNotAvailableError, GislWorkflowExpiredError, GislProbePendingError, GislAuthError, GislUploadCapExceededError, GislMultipartPartError, GislMultipartPartCountError, GislMultipartSessionNotFoundError, GislMultipartSessionOwnershipError, GislMultipartSessionAuthRequiredError, GislTimeoutError, GislAbortError, GislNetworkError, GislConfigError, GislMissingCredentialsError, GislFeatureRequiresAuthError, GislUndeclaredAssetError, GislUnusedAssetError, GislPerInputOptionsNotSupportedError, GislChainCardinalityMismatchError, GislBundleAlreadyArchivedError, GislNoSuchKeyError, GislSinkError, GislItemFailedError, GislResultNotReadyError, } from './errors.js';
+export { GislError, GislApiError, GislValidationError, GislBalanceExhaustedError, GislLongFormConcurrencyError, GislTierRestrictedError, GislFeatureTierRestrictedError, GislFeatureNotAvailableError, GislWorkflowExpiredError, GislProbePendingError, GislAuthError, GislUploadCapExceededError, GislMultipartPartError, GislMultipartPartCountError, GislMultipartSessionNotFoundError, GislMultipartSessionOwnershipError, GislMultipartSessionAuthRequiredError, GislTimeoutError, GislFanOutTimeoutError, GislAbortError, GislNetworkError, GislTransportError, GislDownloadHttpError, GislRequestNotSentError, GislConfigError, GislMissingCredentialsError, GislStreamHostNotDeclaredError, GislFeatureRequiresAuthError, GislUndeclaredAssetError, GislUnusedAssetError, GislPerInputOptionsNotSupportedError, GislChainCardinalityMismatchError, GislBundleAlreadyArchivedError, GislNoSuchKeyError, GislSinkError, GislItemFailedError, GislResultNotReadyError, } from './errors.js';
 export type { GislApiErrorOptions, GislUploadCapKind } from './errors.js';
 export type { ErrorCategory } from './generated/sdk_spec/errors.js';
 export { RunResult } from './file-first.js';
@@ -33,7 +33,7 @@ export type { SseOperationProgressData, SseOperationCompletedData, SseOperationF
 export type { MultiOutputCompletion, PageIndexed, PositionIndexed, Unindexed, } from '@giveitsmaller/contracts/asyncapi';
 import type { MultiOutputCompletion as _MultiOutputCompletion } from '@giveitsmaller/contracts/asyncapi';
 export type OperationResultOutputEntry = _MultiOutputCompletion['outputs'][number];
-export type { CompressImageOptions, CompressImageJpegOptions, CompressImagePngOptions, CompressImageAvifOptions, CompressVideoOptions, CompressAudioOptions, CompressDocumentOfficeOptions, CompressDocumentOdfOptions, CompressDocumentEpubOptions, ThumbnailImageOptions, ThumbnailVideoOptions, ThumbnailDocumentOptions, TransformImageOptions, TransformImageGifOptions, TransformVideoOptions, TransformDocumentPdfOptions, ConvertImageOptions, ConvertVideoOptions, ConvertAudioOptions, ConvertDocumentPdfOptions, MergeImageOptions, MergeVideoOptions, MergeVideoPerInputOptions, MergeAudioOptions, MergeAudioPerInputOptions, ArchiveOptions, ImageWatermarkImageOptions, ImageWatermarkImageGifOptions, TextWatermarkImageOptions, CustomLumaVideoOptions, AudioOverlayAudioOptions, AudioOverlayVideoOptions, AudioWatermarkAudioOptions, AudioWatermarkVideoOptions, AudioToVideoAudioOptions, VideoWatermarkVideoOptions, VideoTextWatermarkVideoOptions, SplitImageGifOptions, SplitDocumentPdfOptions, SplitAudioOptions, SplitVideoOptions, } from '@giveitsmaller/contracts/operations';
+export type { CompressImageOptions, CompressImageJpegOptions, CompressImagePngOptions, CompressImageAvifOptions, CompressVideoOptions, CompressAudioOptions, CompressDocumentOfficeOptions, CompressDocumentOdfOptions, CompressDocumentEpubOptions, ThumbnailImageOptions, ThumbnailVideoOptions, ThumbnailDocumentOfficeOptions, ThumbnailDocumentPdfOptions, ThumbnailDocumentEpubOptions, TransformImageOptions, TransformImageGifOptions, TransformVideoOptions, TransformDocumentPdfOptions, ConvertImageOptions, ConvertVideoOptions, ConvertAudioOptions, ConvertDocumentPdfOptions, MergeImageOptions, MergeVideoOptions, MergeVideoPerInputOptions, MergeAudioOptions, MergeAudioPerInputOptions, ArchiveOptions, ImageWatermarkImageOptions, ImageWatermarkImageGifOptions, TextWatermarkImageOptions, CustomLumaVideoOptions, AudioOverlayAudioOptions, AudioOverlayVideoOptions, AudioWatermarkAudioOptions, AudioWatermarkVideoOptions, AudioToVideoAudioOptions, VideoWatermarkVideoOptions, VideoTextWatermarkVideoOptions, SplitImageGifOptions, SplitDocumentPdfOptions, SplitAudioOptions, SplitVideoOptions, } from '@giveitsmaller/contracts/operations';
 export { ImageWatermarkImageAnchor, ImageWatermarkImageGifAnchor, TextWatermarkImageAnchor, TextWatermarkImageFontFamily, TextWatermarkImageWatermarkMode, AudioOverlayAudioMode, AudioOverlayVideoMode, AudioOverlayVideoNoAudioTrackBehaviour, AudioWatermarkAudioMethod, AudioWatermarkAudioRobustness, AudioWatermarkAudioDensity, AudioWatermarkVideoMethod, AudioWatermarkVideoRobustness, AudioWatermarkVideoDensity, AudioToVideoAudioOutputResolution, AudioToVideoAudioImageFit, AudioToVideoAudioOutputFormat, VideoWatermarkVideoAnchor, VideoTextWatermarkVideoFontFamily, VideoTextWatermarkVideoWatermarkMode, VideoTextWatermarkVideoAnchor, SplitImageGifOutputFormat, SplitDocumentPdfMode, SplitAudioMode, SplitAudioPrecision, SplitVideoMode, SplitVideoPrecision, } from '@giveitsmaller/contracts/operations';
 export { archiveMetadata, audioOverlayMetadata, audioWatermarkMetadata, compressMetadata, convertMetadata, customLumaMetadata, imageWatermarkMetadata, mergeMetadata, textWatermarkMetadata, thumbnailMetadata, audioToVideoMetadata, videoWatermarkMetadata, videoTextWatermarkMetadata, splitMetadata, transformMetadata, } from '@giveitsmaller/contracts/operations';
 export type { ConvertOptions, ThumbnailOptions, TransformOptions, TextWatermarkOptions, WatermarkOptions, WatermarkOverlay, WatermarkAnchor, } from './ergonomic/option_types.js';

package/dist/index.core.js

@@ -11,12 +11,28 @@ export { uploadSource, jobOutputSource, externalImportSource, connectionSource,
 // Errors
 export { GislError, GislApiError, GislValidationError, GislBalanceExhaustedError, GislLongFormConcurrencyError, GislTierRestrictedError, GislFeatureTierRestrictedError, GislFeatureNotAvailableError, GislWorkflowExpiredError, GislProbePendingError, GislAuthError, GislUploadCapExceededError, GislMultipartPartError, GislMultipartPartCountError, 
 // SDK-3 (Wb6ebOMM) — typed errors for the 3 resume-support endpoints.
-GislMultipartSessionNotFoundError, GislMultipartSessionOwnershipError, GislMultipartSessionAuthRequiredError, GislTimeoutError, GislAbortError, 
-// FF2b / tywwynmN — transport-level failure (mirrors PHP GislNetworkError);
+GislMultipartSessionNotFoundError, GislMultipartSessionOwnershipError, GislMultipartSessionAuthRequiredError, GislTimeoutError, 
+// 4G4FaA9X — mapEach fan-out timed out mid-batch; carries the completed
+// child ids + parent id so the caller can recover without a whole-batch re-run.
+GislFanOutTimeoutError, GislAbortError, 
+// FF2b / tywwynmN — off-envelope failure base (mirrors PHP GislNetworkError);
 // raised by the file-first HttpDownloader when an output URL cannot be read.
+// t2qCrjdr: NEVER THROWN DIRECTLY any more — it is the hierarchy node the two
+// subclasses below share, kept so existing `instanceof GislNetworkError`
+// narrowing (including the SSE poll-fallback) is unchanged.
 GislNetworkError, 
+// t2qCrjdr — the split. One `retryable` could not be honest for both a DNS
+// failure and a 404, so each case is now its own class with its own answer.
+GislTransportError, GislDownloadHttpError, 
+// The request never left the client — never retryable. TS detects only what
+// it can see BEFORE the call (an unparseable URL); PHP also classifies
+// PSR-18's RequestExceptionInterface, which `fetch` gives no equivalent of.
+GislRequestNotSentError, 
 // T1 / wVU4xHx3 — local config-error tree (pre-I/O; sibling of GislApiError).
-GislConfigError, GislMissingCredentialsError, GislFeatureRequiresAuthError, 
+GislConfigError, GislMissingCredentialsError, 
+// VUozk5Bc — `streamEvents` on a client with no DECLARED stream host. The
+// SDK refuses to derive `stream.*` from `api.*`; `run()` polls instead.
+GislStreamHostNotDeclaredError, GislFeatureRequiresAuthError, 
 // T3 / cuecCmb5 — merge-compose local validation errors.
 GislUndeclaredAssetError, GislUnusedAssetError, GislPerInputOptionsNotSupportedError, 
 // T6 / aDR1jnyZ — chain-cardinality validation (dormant until chain

package/dist/merge.d.ts

@@ -103,6 +103,35 @@ export interface MergeOptions {
     readonly preset?: string;
     /** Video output dimensions `WxH` (e.g. `"1920x1080"`); omit to inherit from inputs. Video merge only. */
     readonly targetResolution?: string;
+    /**
+     * Target output size (bytes, or a `'50MB'`-style string). Lowered to wire
+     * `target_size_bytes`, and the SDK also sets `encoding_mode: 'target_size'` alongside
+     * it. Video merge only.
+     *
+     * **UNITS ARE DECIMAL HERE (1 KB = 1000), UNLIKE `compress`.** `compress`'s
+     * `targetSize` parses the same strings as BINARY (1 KB = 1024), so `'50MB'` means
+     * 50,000,000 bytes on a merge and 52,428,800 bytes on a compress. That divergence is
+     * NOT deliberate — it contradicts the pinned convention that every human-readable
+     * size string in this SDK is binary — and it has a sharp edge: the contract floor for
+     * `target_size_bytes` is 1 MiB (1,048,576), so `'1MB'` here resolves to 1,000,000 and
+     * is rejected as below the minimum. Prefer an explicit byte count until this is
+     * reconciled. Tracked by `YOCz0i74`; changing it moves bytes for existing callers, so
+     * it is a deliberate decision rather than a silent correction.
+     *
+     * **NOT AVAILABLE FOR LONG INPUTS.** Merges whose summed input duration routes to
+     * the long-form Fargate path reject both keys — that path is single-pass-CRF by
+     * 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.
+     *
+     * 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;
     readonly fps?: 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
@@ -105,7 +127,55 @@ export async function* parseSseStream(response, opts = {}) {
                     continue;
                 }
                 if (line.startsWith(':')) {
-                    // Comment line (keep-alive), skip
+                    // Comment line (keep-alive), skip.
+                    //
+                    // ⚠️ DO NOT "FIX" THIS INTO SURFACING COMMENT FRAMES WITHOUT READING
+                    // THIS. Dropping them is CORRECT per the SSE spec — a comment carries
+                    // no event — but it is also LOAD-BEARING FOR A CONSUMER, and that
+                    // consumer is in another repo.
+                    //
+                    // The frontend does NOT close its SSE reader on the terminal event:
+                    // `workflow_completed` patches status and breaks WITHOUT aborting.
+                    // What actually closes the stream is an IDLE WATCHDOG at 20s. That
+                    // watchdog only fires because heartbeats are never yielded here, so
+                    // they never re-arm it — roughly 20s after the last real event the
+                    // reader closes and the PHP worker is released.
+                    //
+                    // HEARTBEAT ~16s vs IDLE TIMEOUT 20s: a FOUR-SECOND MARGIN that holds
+                    // only while the heartbeats are invisible. Surfacing comment frames —
+                    // a completely reasonable change, since EventSource semantics treat
+                    // keep-alive comments as liveness signals that legitimately reset
+                    // timeouts — would CONTINUOUSLY re-arm the watchdog. The stream would
+                    // never go idle, and every completed job left on screen would hold a
+                    // PHP worker for the full 570s. That is worker exhaustion from
+                    // ordinary users leaving tabs open.
+                    //
+                    // A ONE-LINE CHANGE HERE SILENTLY CONVERTS THE FRONTEND FROM BOUNDED
+                    // TO UNBOUNDED, and nothing on either side would flag it.
+                    //
+                    // ⚠️ THIS NOTE IS PERMANENT. DO NOT DELETE IT WHEN THE FRONTEND
+                    // ADDS AN EXPLICIT CLOSE-ON-TERMINAL. That fix removes the TERMINAL
+                    // case and does NOT remove the dependency, because closing finished
+                    // streams was never the watchdog's job — that was a side effect
+                    // nobody knew about until 2026-08-12.
+                    //
+                    // THE WATCHDOG'S ACTUAL JOB IS DETECTING A STREAM THAT HAS GONE
+                    // SILENT WHILE THE WORKFLOW IS STILL RUNNING, and resuming the
+                    // fallback poll. That case survives every fix in flight, and it is
+                    // not exotic: a long operation between progress events produces it
+                    // exactly — heartbeats flowing, no data frames, job still running.
+                    //
+                    // If this parser surfaced comment frames, heartbeats at ~16s would
+                    // re-arm the 20s watchdog FOREVER and STALL DETECTION WOULD NEVER
+                    // FIRE AT ALL, on a stream that is genuinely stuck. The UI would go
+                    // on believing a dead job is fine. That is worse than the worker
+                    // leak: a leak is bounded by 570s, a missed stall is not bounded at
+                    // all.
+                    //
+                    // The PHP SDK does the same thing at GislClient.php (`$line[0] === ':'`),
+                    // verified 2026-08-12 — the two languages agree on this axis, and
+                    // they must stay agreed: this property governs whether a stuck
+                    // stream is EVER detected, so a divergence here is not cosmetic.
                     continue;
                 }
                 const colonIndex = line.indexOf(':');
@@ -124,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.21.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.59.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"
   }
 }