@boy-offi9-inc/reqkit 0.5.0 → 0.6.0

package/README.md

@@ -48,14 +48,14 @@ const pages = await limit.map(urls, (url) =>
   )
 );
 ```
+
 ---
 
 ## Playground
 
-Try everything in your browser — retries obeying `Retry-After`, rate limiting, the circuit breaker, caching, SSE streaming and a resumable download that survives a dropped connection. It runs against a fake in-memory server, so there's nothing to install and no network involved.
-
-Run it locally: `npm run build && python3 -m http.server -d docs` → open `http://localhost:8000`. (ES modules don't load from `file://`, so it needs a server.) The repo's `pages.yml` workflow publishes the same folder to GitHub Pages — enable it once under Settings → Pages → Source: "GitHub Actions".
+Try everything in your browser — retries obeying `Retry-After`, rate limiting, the circuit breaker, caching, SSE streaming, an SSE stream that reconnects itself, and a resumable download that survives a dropped connection. It runs against a fake in-memory server, so there's nothing to install and no network involved.
 
+Run it locally: `npm run build && python3 -m http.server -d docs` → open `http://localhost:8000`. (ES modules don't load from `file://`, so it needs a server.)
 ## Works with what you already use
 
 Recipes for **axios, ky, got, undici/node-fetch**, testing, and LLM streaming live in [RECIPES.md](./RECIPES.md): keep your client, bolt on just the piece you're missing (`Retry-After`-aware retries, a rate limiter, a circuit breaker).
@@ -91,6 +91,7 @@ Recipes for **axios, ky, got, undici/node-fetch**, testing, and LLM streaming li
 | Stop hammering a service that keeps failing | [`createCircuitBreaker`](#createcircuitbreakeropts) |
 | Cache GETs (TTL, stale-while-revalidate, ETag/304) | [`createFetch` → `cache`](#caching) |
 | Resume a download after the connection drops | [`downloadResumable`](#downloadresumableurl-opts) |
+| Stay connected to an SSE endpoint (auto-reconnect, `Last-Event-ID`) | [`streamSSE`](#auto-reconnecting-sse-streamsse) |
 | Read SSE / NDJSON / lines from a streamed body (LLM tokens!) | [`readSSE` / `readNDJSON` / `readLines`](#streaming-readsse-readndjson-readlines) |
 | Test retry/timeout code without a network | [`createMockFetch`](#createmockfetch) |
 | All of the above, wired up | [`createFetch`](#createfetchdefaults) |
@@ -360,6 +361,33 @@ for await (const line of readLines(response)) console.log(line);
 
 `readSSE` follows the spec: multi-line `data:` is joined with `\n`, comments are ignored, `event` defaults to `"message"`, `id` carries over, `retry` is parsed, and an event cut off by the end of the stream is dropped. `readNDJSON` skips blank lines and names the bad line on a parse error (or pass `skipInvalid: true`). Line splitting handles `\n`, `\r\n`, `\r`, a BOM, and multi-byte characters split across chunks.
 
+### Auto-reconnecting SSE: `streamSSE`
+
+`readSSE` parses a stream you already have; **`streamSSE` opens it for you and keeps it open.** When the connection drops (or the server closes it) it reconnects by itself and sends `Last-Event-ID`, so the server can resume where you left off — what the browser's `EventSource` does, but built on `fetch`: custom headers, POST bodies, `AbortSignal`, your own client.
+
+```js
+import { streamSSE } from "@boy-offi9-inc/reqkit";
+
+for await (const { id, data } of streamSSE("https://api.example.com/events", {
+  headers: () => ({ authorization: `Bearer ${getToken()}` }), // re-evaluated on every reconnect
+  onReconnect: ({ reason, delayMs, lastEventId }) => console.log(`reconnecting in ${delayMs}ms from id ${lastEventId}`),
+  signal,
+})) {
+  handle(data);
+}
+```
+
+| Behavior | Details |
+|---|---|
+| Resume | `Last-Event-ID` (the last `id:` seen) is sent on every reconnect; `lastEventId` option resumes on the first connect too |
+| Delay | the server's `retry: <ms>` field sets the base delay (like `EventSource`); waits then back off exponentially up to `maxDelayMs` while connecting keeps failing; `Retry-After` on 429/503 is honored |
+| Giving up | `retries` (default 10) counts consecutive attempts **without progress** — a connection that delivered an event resets it. Then it throws the last error |
+| Stopping | HTTP `204` ends the stream (the standard "don't reconnect"); `stopWhen: e => e.data === "[DONE]"`; `break`ing out of the loop or aborting `signal` closes the connection |
+| Fatal | a non-retryable status (401, 404…) throws `HTTPError` right away; a response that isn't `text/event-stream` throws (`code: "SSE_BAD_CONTENT_TYPE"`) |
+| POST streams | **only GET reconnects by default** — re-sending a POST (say, an LLM prompt) could repeat side effects, so POST streams just end or throw unless you pass `reconnect: true` |
+
+It takes any fetch: `streamSSE(url, { fetch: api })` with a `createFetch` instance works too.
+
 ### `downloadResumable(url, opts?)`
 
 Downloads into memory and, if the connection drops mid-body, **resumes with an HTTP `Range` request** instead of starting over. It sends `If-Range` with the first response's strong ETag (or `Last-Modified`), so a file that changed on the server is restarted rather than stitched together wrongly; if the server ignores `Range`, it restarts from zero.

package/dist/reqkit.mjs

@@ -1,4 +1,4 @@
-/*! @boy-offi9-inc/reqkit v0.5.0 — ESM bundle (generated by scripts/build-esm.js, do not edit) */
+/*! @boy-offi9-inc/reqkit v0.6.0 — ESM bundle (generated by scripts/build-esm.js, do not edit) */
 const __defs = {
 "./HTTPError": function (module, exports, require) {
 class HTTPError extends Error {
@@ -1413,6 +1413,7 @@ const { createMemoryCache } = require("./createMemoryCache");
 const { createMockFetch } = require("./createMockFetch");
 const { downloadResumable } = require("./downloadResumable");
 const { readLines, readNDJSON, readSSE } = require("./streams");
+const { streamSSE } = require("./streamSSE");
 
 module.exports = {
   withRetry,
@@ -1441,6 +1442,7 @@ module.exports = {
   readLines,
   readNDJSON,
   readSSE,
+  streamSSE,
 };
 
 },
@@ -1501,7 +1503,7 @@ function isNetworkCode(code) {
 
 // Browsers and Node throw a bare TypeError for network-level fetch failures.
 const FETCH_NETWORK_MESSAGE =
-  /fetch failed|failed to fetch|network ?request failed|load failed|networkerror when attempting to fetch/i;
+  /fetch failed|failed to fetch|network ?request failed|load failed|networkerror when attempting to fetch|^terminated$|^network error$/i;
 
 function isFetchNetworkTypeError(err) {
   return err.name === "TypeError" && FETCH_NETWORK_MESSAGE.test(err.message || "");
@@ -1677,6 +1679,206 @@ function retryAfterAware(fn, opts = {}) {
 
 module.exports = { retryAfterAware, parseRetryAfter, getWaitMsFromHeaders };
 
+},
+"./streamSSE": function (module, exports, require) {
+const { readSSE } = require("./streams");
+const { HTTPError } = require("./HTTPError");
+const { normalizeError } = require("./normalizeError");
+const { getWaitMsFromHeaders, discardBody } = require("./_http");
+const { abortableSleep } = require("./_sleep");
+
+function isRetryableStatus(status) {
+  return status === 408 || status === 425 || status === 429 || status >= 500;
+}
+
+function isRetryableError(err) {
+  const n = normalizeError(err);
+  return !n.isAborted && (n.isNetworkError || n.isTimeout);
+}
+
+async function resolveHeaders(source) {
+  const value = typeof source === "function" ? await source() : source;
+  return new Headers(value || undefined);
+}
+
+/**
+ * Connects to a Server-Sent Events endpoint and yields its events — and when
+ * the connection drops (or the server closes it), reconnects by itself,
+ * sending `Last-Event-ID` so the server can resume where you left off. This is
+ * what the browser's `EventSource` does, but with `fetch`: custom headers,
+ * POST bodies, AbortSignal, your own retry/backoff rules.
+ *
+ * ```js
+ * for await (const { data } of streamSSE("https://api.example.com/events", { signal })) {
+ *   console.log(data);
+ * }
+ * ```
+ *
+ * Reconnect behavior:
+ *  - `Last-Event-ID` is sent on every reconnect (the last `id:` seen).
+ *  - A server `retry: <ms>` field sets the base reconnect delay, like EventSource.
+ *  - Waits back off exponentially (capped at `maxDelayMs`) while connecting keeps
+ *    failing; 429/503 `Retry-After` is honored. A connection that delivered at
+ *    least one event resets the failure count (only no-progress attempts count
+ *    toward `retries`).
+ *  - HTTP 204 means "stop reconnecting" (iteration ends). A non-retryable
+ *    status (e.g. 401/404) or a wrong content-type throws immediately.
+ *  - Only GET reconnects by default. For other methods (e.g. a POST that starts
+ *    an LLM stream) re-sending the request could repeat side effects, so
+ *    nothing is retried unless you pass `reconnect: true`.
+ *  - Breaking out of the loop, or aborting `signal`, closes the connection.
+ *
+ * @param {string} url
+ * @param {object} [opts]
+ * @param {typeof fetch} [opts.fetch=globalThis.fetch] - e.g. a createFetch() instance
+ * @param {string} [opts.method="GET"]
+ * @param {HeadersInit | (() => HeadersInit | Promise<HeadersInit>)} [opts.headers] -
+ *   a function is called before every (re)connect — handy for refreshing a token
+ * @param {BodyInit} [opts.body]
+ * @param {AbortSignal} [opts.signal]
+ * @param {string} [opts.lastEventId] - resume from here on the very first connect
+ * @param {boolean} [opts.reconnect] - default: true for GET/HEAD, false otherwise
+ * @param {number} [opts.retries=10] - consecutive failed connections before giving up (Infinity = never)
+ * @param {number} [opts.reconnectDelayMs=1000] - base delay (the server's `retry:` overrides it)
+ * @param {number} [opts.maxDelayMs=30000]
+ * @param {(event: object) => boolean} [opts.stopWhen] - end the stream (no reconnect) after this event, e.g. `e => e.data === "[DONE]"`
+ * @param {(info: {connections: number, lastEventId: string}) => void} [opts.onOpen]
+ * @param {(info: {reason: "error"|"end"|"status", error?: any, status?: number, attempt: number, delayMs: number, lastEventId: string}) => void} [opts.onReconnect]
+ * @returns {AsyncGenerator<{event: string, data: string, id: string, retry: number|undefined}>}
+ */
+async function* streamSSE(url, opts = {}) {
+  const {
+    fetch: fetchFn = globalThis.fetch,
+    method = "GET",
+    headers,
+    body,
+    signal,
+    reconnect = method === "GET" || method === "HEAD",
+    retries = 10,
+    reconnectDelayMs = 1000,
+    maxDelayMs = 30000,
+    stopWhen,
+    onOpen,
+    onReconnect,
+  } = opts;
+
+  let lastId = opts.lastEventId || "";
+  let baseDelay = reconnectDelayMs;
+  let failures = 0; // consecutive connections that delivered nothing
+  let connections = 0;
+
+  for (;;) {
+    signal?.throwIfAborted?.();
+    let failure = null; // { reason, error?, status?, response? }
+    let res = null;
+
+    // ---- connect -----------------------------------------------------------
+    try {
+      const h = await resolveHeaders(headers);
+      if (!h.has("accept")) h.set("accept", "text/event-stream");
+      if (!h.has("cache-control")) h.set("cache-control", "no-cache");
+      if (lastId) h.set("last-event-id", lastId);
+      res = await fetchFn(url, { method, headers: h, body, signal });
+    } catch (err) {
+      if (signal?.aborted) throw signal.reason ?? err;
+      if (err instanceof HTTPError) {
+        if (!isRetryableStatus(err.status)) throw err;
+        failure = { reason: "status", status: err.status, response: err.response, error: err };
+      } else if (isRetryableError(err)) {
+        failure = { reason: "error", error: err };
+      } else {
+        throw err;
+      }
+    }
+
+    // ---- inspect the response ---------------------------------------------
+    if (!failure) {
+      if (res.status === 204) {
+        await discardBody(res);
+        return; // the server's way of saying "don't reconnect"
+      }
+      if (!res.ok) {
+        if (!isRetryableStatus(res.status)) {
+          await discardBody(res);
+          throw new HTTPError(res, { method, url });
+        }
+        failure = { reason: "status", status: res.status, response: res };
+      } else {
+        const type = res.headers.get("content-type") || "";
+        if (!/text\/event-stream/i.test(type)) {
+          await discardBody(res);
+          throw Object.assign(new Error(`streamSSE: expected "text/event-stream" but the server sent "${type || "no content-type"}"`), {
+            code: "SSE_BAD_CONTENT_TYPE",
+          });
+        }
+      }
+    }
+
+    // ---- stream ------------------------------------------------------------
+    let gotEvent = false;
+    if (!failure) {
+      connections++;
+      if (onOpen) onOpen({ connections, lastEventId: lastId });
+      try {
+        for await (const event of readSSE(res, { signal })) {
+          gotEvent = true;
+          lastId = event.id;
+          if (event.retry !== undefined) baseDelay = event.retry;
+          yield event;
+          if (stopWhen && stopWhen(event)) return;
+        }
+        failure = { reason: "end" };
+      } catch (err) {
+        if (signal?.aborted) throw signal.reason ?? err;
+        if (!isRetryableError(err)) throw err;
+        failure = { reason: "error", error: err };
+      }
+    }
+
+    // ---- decide whether and when to reconnect ------------------------------
+    if (!reconnect) {
+      if (failure.reason === "end") return;
+      if (failure.reason === "status") {
+        throw failure.error || new HTTPError(failure.response, { method, url });
+      }
+      throw failure.error;
+    }
+
+    // A connection that delivered events made progress: reconnect promptly and
+    // start the failure count over. Only no-progress attempts count toward `retries`.
+    failures = gotEvent ? 0 : failures + 1;
+    if (failures > retries) {
+      if (failure.reason === "status") throw failure.error || new HTTPError(failure.response, { method, url });
+      if (failure.reason === "error") throw failure.error;
+      throw Object.assign(new Error(`streamSSE: the server keeps closing the stream without sending events — gave up after ${retries} retries`), {
+        code: "SSE_GAVE_UP",
+      });
+    }
+
+    let delayMs = Math.min(baseDelay * 2 ** Math.max(failures - 1, 0), maxDelayMs);
+    if (failure.reason === "status" && failure.response) {
+      const headerMs = getWaitMsFromHeaders(failure.response.headers);
+      if (headerMs !== null) delayMs = Math.min(headerMs, 60000);
+      await discardBody(failure.response);
+    }
+    delayMs += Math.random() * delayMs * 0.1; // a little jitter so clients don't reconnect in lockstep
+
+    if (onReconnect) {
+      onReconnect({
+        reason: failure.reason,
+        error: failure.error,
+        status: failure.status,
+        attempt: Math.max(failures, 1),
+        delayMs,
+        lastEventId: lastId,
+      });
+    }
+    await abortableSleep(delayMs, signal);
+  }
+}
+
+module.exports = { streamSSE };
+
 },
 "./streams": function (module, exports, require) {
 const encoder = new TextEncoder();
@@ -2296,6 +2498,7 @@ export const {
   readNDJSON,
   readSSE,
   retryAfterAware,
+  streamSSE,
   withDedupe,
   withProgress,
   withRetry,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boy-offi9-inc/reqkit",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Small, composable HTTP helpers — retry with backoff and Retry-After, timeouts, normalized errors, rate limiter, circuit breaker, response cache, resumable downloads, SSE/NDJSON streams, mock fetch, and an opt-in createFetch. Not a client; works alongside fetch/axios/anything.",
   "main": "./src/index.js",
   "types": "./types/index.d.ts",

package/src/index.js

@@ -14,6 +14,7 @@ const { createMemoryCache } = require("./createMemoryCache");
 const { createMockFetch } = require("./createMockFetch");
 const { downloadResumable } = require("./downloadResumable");
 const { readLines, readNDJSON, readSSE } = require("./streams");
+const { streamSSE } = require("./streamSSE");
 
 module.exports = {
   withRetry,
@@ -42,4 +43,5 @@ module.exports = {
   readLines,
   readNDJSON,
   readSSE,
+  streamSSE,
 };

package/src/index.mjs

@@ -27,6 +27,7 @@ export const {
   readLines,
   readNDJSON,
   readSSE,
+  streamSSE,
 } = reqkit;
 
 export default reqkit;

package/src/normalizeError.js

@@ -54,7 +54,7 @@ function isNetworkCode(code) {
 
 // Browsers and Node throw a bare TypeError for network-level fetch failures.
 const FETCH_NETWORK_MESSAGE =
-  /fetch failed|failed to fetch|network ?request failed|load failed|networkerror when attempting to fetch/i;
+  /fetch failed|failed to fetch|network ?request failed|load failed|networkerror when attempting to fetch|^terminated$|^network error$/i;
 
 function isFetchNetworkTypeError(err) {
   return err.name === "TypeError" && FETCH_NETWORK_MESSAGE.test(err.message || "");

package/src/streamSSE.js

@@ -0,0 +1,197 @@
+const { readSSE } = require("./streams");
+const { HTTPError } = require("./HTTPError");
+const { normalizeError } = require("./normalizeError");
+const { getWaitMsFromHeaders, discardBody } = require("./_http");
+const { abortableSleep } = require("./_sleep");
+
+function isRetryableStatus(status) {
+  return status === 408 || status === 425 || status === 429 || status >= 500;
+}
+
+function isRetryableError(err) {
+  const n = normalizeError(err);
+  return !n.isAborted && (n.isNetworkError || n.isTimeout);
+}
+
+async function resolveHeaders(source) {
+  const value = typeof source === "function" ? await source() : source;
+  return new Headers(value || undefined);
+}
+
+/**
+ * Connects to a Server-Sent Events endpoint and yields its events — and when
+ * the connection drops (or the server closes it), reconnects by itself,
+ * sending `Last-Event-ID` so the server can resume where you left off. This is
+ * what the browser's `EventSource` does, but with `fetch`: custom headers,
+ * POST bodies, AbortSignal, your own retry/backoff rules.
+ *
+ * ```js
+ * for await (const { data } of streamSSE("https://api.example.com/events", { signal })) {
+ *   console.log(data);
+ * }
+ * ```
+ *
+ * Reconnect behavior:
+ *  - `Last-Event-ID` is sent on every reconnect (the last `id:` seen).
+ *  - A server `retry: <ms>` field sets the base reconnect delay, like EventSource.
+ *  - Waits back off exponentially (capped at `maxDelayMs`) while connecting keeps
+ *    failing; 429/503 `Retry-After` is honored. A connection that delivered at
+ *    least one event resets the failure count (only no-progress attempts count
+ *    toward `retries`).
+ *  - HTTP 204 means "stop reconnecting" (iteration ends). A non-retryable
+ *    status (e.g. 401/404) or a wrong content-type throws immediately.
+ *  - Only GET reconnects by default. For other methods (e.g. a POST that starts
+ *    an LLM stream) re-sending the request could repeat side effects, so
+ *    nothing is retried unless you pass `reconnect: true`.
+ *  - Breaking out of the loop, or aborting `signal`, closes the connection.
+ *
+ * @param {string} url
+ * @param {object} [opts]
+ * @param {typeof fetch} [opts.fetch=globalThis.fetch] - e.g. a createFetch() instance
+ * @param {string} [opts.method="GET"]
+ * @param {HeadersInit | (() => HeadersInit | Promise<HeadersInit>)} [opts.headers] -
+ *   a function is called before every (re)connect — handy for refreshing a token
+ * @param {BodyInit} [opts.body]
+ * @param {AbortSignal} [opts.signal]
+ * @param {string} [opts.lastEventId] - resume from here on the very first connect
+ * @param {boolean} [opts.reconnect] - default: true for GET/HEAD, false otherwise
+ * @param {number} [opts.retries=10] - consecutive failed connections before giving up (Infinity = never)
+ * @param {number} [opts.reconnectDelayMs=1000] - base delay (the server's `retry:` overrides it)
+ * @param {number} [opts.maxDelayMs=30000]
+ * @param {(event: object) => boolean} [opts.stopWhen] - end the stream (no reconnect) after this event, e.g. `e => e.data === "[DONE]"`
+ * @param {(info: {connections: number, lastEventId: string}) => void} [opts.onOpen]
+ * @param {(info: {reason: "error"|"end"|"status", error?: any, status?: number, attempt: number, delayMs: number, lastEventId: string}) => void} [opts.onReconnect]
+ * @returns {AsyncGenerator<{event: string, data: string, id: string, retry: number|undefined}>}
+ */
+async function* streamSSE(url, opts = {}) {
+  const {
+    fetch: fetchFn = globalThis.fetch,
+    method = "GET",
+    headers,
+    body,
+    signal,
+    reconnect = method === "GET" || method === "HEAD",
+    retries = 10,
+    reconnectDelayMs = 1000,
+    maxDelayMs = 30000,
+    stopWhen,
+    onOpen,
+    onReconnect,
+  } = opts;
+
+  let lastId = opts.lastEventId || "";
+  let baseDelay = reconnectDelayMs;
+  let failures = 0; // consecutive connections that delivered nothing
+  let connections = 0;
+
+  for (;;) {
+    signal?.throwIfAborted?.();
+    let failure = null; // { reason, error?, status?, response? }
+    let res = null;
+
+    // ---- connect -----------------------------------------------------------
+    try {
+      const h = await resolveHeaders(headers);
+      if (!h.has("accept")) h.set("accept", "text/event-stream");
+      if (!h.has("cache-control")) h.set("cache-control", "no-cache");
+      if (lastId) h.set("last-event-id", lastId);
+      res = await fetchFn(url, { method, headers: h, body, signal });
+    } catch (err) {
+      if (signal?.aborted) throw signal.reason ?? err;
+      if (err instanceof HTTPError) {
+        if (!isRetryableStatus(err.status)) throw err;
+        failure = { reason: "status", status: err.status, response: err.response, error: err };
+      } else if (isRetryableError(err)) {
+        failure = { reason: "error", error: err };
+      } else {
+        throw err;
+      }
+    }
+
+    // ---- inspect the response ---------------------------------------------
+    if (!failure) {
+      if (res.status === 204) {
+        await discardBody(res);
+        return; // the server's way of saying "don't reconnect"
+      }
+      if (!res.ok) {
+        if (!isRetryableStatus(res.status)) {
+          await discardBody(res);
+          throw new HTTPError(res, { method, url });
+        }
+        failure = { reason: "status", status: res.status, response: res };
+      } else {
+        const type = res.headers.get("content-type") || "";
+        if (!/text\/event-stream/i.test(type)) {
+          await discardBody(res);
+          throw Object.assign(new Error(`streamSSE: expected "text/event-stream" but the server sent "${type || "no content-type"}"`), {
+            code: "SSE_BAD_CONTENT_TYPE",
+          });
+        }
+      }
+    }
+
+    // ---- stream ------------------------------------------------------------
+    let gotEvent = false;
+    if (!failure) {
+      connections++;
+      if (onOpen) onOpen({ connections, lastEventId: lastId });
+      try {
+        for await (const event of readSSE(res, { signal })) {
+          gotEvent = true;
+          lastId = event.id;
+          if (event.retry !== undefined) baseDelay = event.retry;
+          yield event;
+          if (stopWhen && stopWhen(event)) return;
+        }
+        failure = { reason: "end" };
+      } catch (err) {
+        if (signal?.aborted) throw signal.reason ?? err;
+        if (!isRetryableError(err)) throw err;
+        failure = { reason: "error", error: err };
+      }
+    }
+
+    // ---- decide whether and when to reconnect ------------------------------
+    if (!reconnect) {
+      if (failure.reason === "end") return;
+      if (failure.reason === "status") {
+        throw failure.error || new HTTPError(failure.response, { method, url });
+      }
+      throw failure.error;
+    }
+
+    // A connection that delivered events made progress: reconnect promptly and
+    // start the failure count over. Only no-progress attempts count toward `retries`.
+    failures = gotEvent ? 0 : failures + 1;
+    if (failures > retries) {
+      if (failure.reason === "status") throw failure.error || new HTTPError(failure.response, { method, url });
+      if (failure.reason === "error") throw failure.error;
+      throw Object.assign(new Error(`streamSSE: the server keeps closing the stream without sending events — gave up after ${retries} retries`), {
+        code: "SSE_GAVE_UP",
+      });
+    }
+
+    let delayMs = Math.min(baseDelay * 2 ** Math.max(failures - 1, 0), maxDelayMs);
+    if (failure.reason === "status" && failure.response) {
+      const headerMs = getWaitMsFromHeaders(failure.response.headers);
+      if (headerMs !== null) delayMs = Math.min(headerMs, 60000);
+      await discardBody(failure.response);
+    }
+    delayMs += Math.random() * delayMs * 0.1; // a little jitter so clients don't reconnect in lockstep
+
+    if (onReconnect) {
+      onReconnect({
+        reason: failure.reason,
+        error: failure.error,
+        status: failure.status,
+        attempt: Math.max(failures, 1),
+        delayMs,
+        lastEventId: lastId,
+      });
+    }
+    await abortableSleep(delayMs, signal);
+  }
+}
+
+module.exports = { streamSSE };

package/types/index.d.ts

@@ -405,3 +405,39 @@ export function readNDJSON<T = unknown>(
   opts?: StreamOptions & { skipInvalid?: boolean }
 ): AsyncGenerator<T, void, undefined>;
 export function readSSE(source: StreamSource, opts?: StreamOptions): AsyncGenerator<SSEEvent, void, undefined>;
+
+export interface StreamSSEOptions {
+  /** e.g. a createFetch() instance. Default: globalThis.fetch. */
+  fetch?: typeof fetch;
+  /** Default "GET". Only GET/HEAD reconnect unless `reconnect: true`. */
+  method?: string;
+  /** A function is re-evaluated before every (re)connect — handy for refreshing a token. */
+  headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+  body?: BodyInit | null;
+  signal?: AbortSignal;
+  /** Resume from this id on the very first connect. */
+  lastEventId?: string;
+  /** Default: true for GET/HEAD, false otherwise. */
+  reconnect?: boolean;
+  /** Consecutive no-progress connection failures before giving up. Default 10 (Infinity = never). */
+  retries?: number;
+  /** Base reconnect delay; the server's `retry:` field overrides it. Default 1000. */
+  reconnectDelayMs?: number;
+  /** Cap on the exponential backoff. Default 30000. */
+  maxDelayMs?: number;
+  /** End the stream (no reconnect) after this event, e.g. `e => e.data === "[DONE]"`. */
+  stopWhen?: (event: SSEEvent) => boolean;
+  onOpen?: (info: { connections: number; lastEventId: string }) => void;
+  onReconnect?: (info: {
+    reason: "error" | "end" | "status";
+    error?: unknown;
+    status?: number;
+    /** Consecutive reconnects without progress (at least 1). */
+    attempt: number;
+    delayMs: number;
+    lastEventId: string;
+  }) => void;
+}
+
+/** Auto-reconnecting SSE: resumes with Last-Event-ID, honors `retry:` and Retry-After. */
+export function streamSSE(url: string, opts?: StreamSSEOptions): AsyncGenerator<SSEEvent, void, undefined>;