@songfreedom/sse-client 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 songfreedom
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,302 @@
-# Temporary Holding Version
+# @songfreedom/sse-client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/%40songfreedom%2Fsse-client)](https://www.npmjs.com/package/@songfreedom/sse-client)
+[![license](https://img.shields.io/npm/l/%40songfreedom%2Fsse-client)](./LICENSE)
+[![minzip size](https://img.shields.io/bundlephobia/minzip/%40songfreedom%2Fsse-client)](https://bundlephobia.com/package/@songfreedom/sse-client)
+
+A small, dependency-free Server-Sent Events client for the browser.
+`fetch` transport, typed event routing, automatic reconnection with `Last-Event-ID` resume,
+an idle watchdog and shared connections.
+
+```ts
+import { SSEClient } from "@songfreedom/sse-client";
+
+const client = new SSEClient({
+  url: "/api/push/subscribe",
+  body: { topics: ["alarm"] },
+  headers: () => ({ authorization: `Bearer ${getToken()}` }),
+  parse: (raw) => JSON.parse(raw),
+});
+
+client.on("ALARM", (alarm) => console.log(alarm.level));
+```
+
+## Why not `EventSource`?
+
+| Option | Problem |
+| --- | --- |
+| Native `EventSource` | Cannot set request headers (no way to send an auth token), GET only, no request body, no control over reconnection |
+| [`@microsoft/fetch-event-source`](https://github.com/Azure/fetch-event-source) | Archived. Non-2xx responses must be rejected by hand in `onopen`, otherwise it silently reconnects forever; fixed retry interval; no `Last-Event-ID` persistence |
+| `axios` | Cannot read a streaming response in the browser (`responseType: "stream"` is Node-only). Concatenating `responseText` in `onDownloadProgress` corrupts multi-byte characters |
+
+This library is roughly 3 kB gzipped, has no runtime dependencies, and only needs `fetch`
+and `ReadableStream`.
+
+## Features
+
+- **POST + JSON body**, arbitrary headers, and header functions re-evaluated on every reconnect
+- **Reconnects** with exponential backoff and jitter; terminal errors (401/403/404) stop immediately
+- **Resume** with `Last-Event-ID`, so a reconnect can pick up where it left off
+- **Typed event routing**: one connection serves many subscribers, `on()` infers payload types from an event map
+- **Idle watchdog** for streams that go quiet, and **proactive rotation** for connections that stay open but stop receiving data
+- **Offline-aware**: pauses while the network is down, reconnects as soon as it is back
+- **Pluggable retry policy**, including async policies such as "refresh the token, then retry"
+- **Shared connections** by key with reference counting
+- Optional **Vue 3** composable in a separate entry point
+
+## Installation
+
+```bash
+pnpm add @songfreedom/sse-client
+# or
+npm install @songfreedom/sse-client
+```
+
+The Vue entry needs `vue` as a peer dependency (it is optional, so non-Vue users do not install it):
+
+```bash
+pnpm add @songfreedom/sse-client vue
+```
+
+Requires a browser with `fetch` and `ReadableStream` (all evergreen browsers), or Node 18+ for SSR and tests.
+
+## Quick start
+
+### Framework-agnostic
+
+```ts
+import { SSEClient } from "@songfreedom/sse-client";
+
+interface Events {
+  ALARM: { level: "high" | "low"; deviceId: string };
+  IOT: { objectId: string; value: string };
+}
+
+const client = new SSEClient<Events>({
+  url: `${gateway}/server-event/sse/subscribe`,
+  method: "POST",
+  body: [{ subscribeType: "SE", instanceType: "PROJECT" }],
+  headers: () => authHeaders(),          // re-evaluated before every attempt
+  parse: (raw) => JSON.parse(raw),
+  idleTimeout: 45_000,                   // if the server sends a heartbeat every 15s
+});
+
+const off = client.on("ALARM", (alarm) => {
+  // `alarm` is typed as Events["ALARM"]
+  console.log(alarm.deviceId);
+});
+
+// Later
+off();
+client.close();
+```
+
+### Vue 3
+
+```vue
+<script setup lang="ts">
+import { computed } from "vue";
+import { useSSE } from "@songfreedom/sse-client/vue";
+
+interface Events {
+  ALARM: { level: "high" | "low"; deviceId: string };
+}
+
+const { status, lastEvent, on } = useSSE<Events>({
+  url: "/api/push/alarm",
+  body: { topics: ["alarm"] },
+  parse: (raw) => JSON.parse(raw),
+});
+
+on("ALARM", (alarm) => {
+  // unsubscribed automatically on unmount
+  console.log(alarm.level);
+});
+
+const connected = computed(() => status.value === "open");
+</script>
+```
+
+`useSSE` adds two things on top of the client: a ring buffer of recent messages
+(`lastEvent`, `events`, `maxEvents`) and scope-bound cleanup — unmounting the component,
+or a qiankun sub-app, closes the connection.
+
+## API
+
+### `new SSEClient(options)`
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `url` | `string` | — | Request URL, including your gateway prefix |
+| `method` | `"GET" \| "POST"` | `"POST"` | HTTP method |
+| `body` | `unknown` | — | Serialized as JSON; strings, `Blob` and `FormData` are sent as-is |
+| `headers` | `HeadersInit \| () => HeadersInit \| Promise<HeadersInit>` | — | Pass a function to recompute headers on every (re)connect |
+| `parse` | `(raw: string) => unknown` | identity | Payload decoder |
+| `idleTimeout` | `number` | `0` | Reconnect when no bytes arrive for this long. Set it to ~3× the heartbeat interval |
+| `rotateInterval` | `number` | `0` | Reconnect on a schedule, even if the connection looks healthy |
+| `retry` | `(ctx) => number \| false \| Promise<number \| false>` | — | Custom retry policy, overrides the built-in backoff |
+| `maxRetry` | `number` | `Infinity` | Retry limit (only when `retry` is omitted) |
+| `retryBaseDelay` | `number` | `1000` | Delay before the first retry (ms) |
+| `retryMaxDelay` | `number` | `30000` | Upper bound for backoff (ms) |
+| `reconnectOnEnd` | `boolean` | `true` | Reconnect when the server ends the stream normally |
+| `stableAfter` | `number` | `10000` | An attempt that lived this long resets the retry counter |
+| `strictContentType` | `boolean` | `true` | Require `content-type: text/event-stream` |
+| `maxBufferSize` | `number` | `1MB` | Cap for a single message buffer (characters) |
+| `endSignal` | `string` | — | Treat this `data` value as end-of-stream, e.g. `"[DONE]"` |
+| `events` | `string[]` | — | Allow-list of event names |
+| `pauseWhenHidden` | `boolean` | `false` | Suspend while the page is hidden, reconnect when visible |
+| `autoStart` | `boolean` | `true` | Connect in the constructor |
+| `fetch` | `FetchLike` | global `fetch` | Custom transport |
+| `onHandlerError` | `(error) => void` | `console.error` | Fallback when a callback throws |
+
+Lifecycle hooks can be passed as options (`onOpen`, `onMessage`, `onStatus`, `onError`,
+`onClose`) or subscribed later; both forms are equivalent.
+
+#### Properties
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `status` | `SSEStatus` | `idle` · `connecting` · `open` · `reconnecting` · `closed` |
+| `closed` | `boolean` | Terminal state; the client will not reconnect |
+| `attempts` | `number` | Consecutive retries; resets after a stable connection |
+| `lastEventId` | `string` | Latest event id, sent back on reconnect |
+| `done` | `Promise<void>` | Resolves when the connection terminates; never rejects |
+
+#### Methods
+
+| Method | Description |
+| --- | --- |
+| `start()` | Open the connection (no-op while running or suspended) |
+| `close()` | Close and stop reconnecting |
+| `restart()` | Close, then reconnect while keeping `lastEventId` |
+| `on(event, handler)` | Subscribe to one event name; returns an unsubscribe function |
+| `on("*", handler)` | Subscribe to every message |
+| `once(event, handler)` | Subscribe for a single delivery |
+| `onMessage` / `onStatus` / `onError` / `onOpen` / `onClose` | Lifecycle subscriptions |
+
+### `SSEMessage`
+
+```ts
+interface SSEMessage<T = unknown> {
+  id: string;          // event id, inherited from the previous event when omitted
+  event: string;       // "message" when the server sends no `event:` field
+  data: T;             // `parse` output
+  raw: string;         // raw payload text
+  receivedAt: number;  // client receive timestamp
+}
+```
+
+### Error kinds
+
+`SSEError.kind` is meant for logging and for branching inside a retry policy:
+
+| `kind` | Meaning | Retried by default |
+| --- | --- | --- |
+| `http` | Non-2xx response (`status` is set) | Yes for 408/425/429/5xx, otherwise no |
+| `network` | DNS failure, connection reset, … | Yes |
+| `heartbeat` | Idle timeout, the connection looks zombie | Yes |
+| `protocol` | Wrong `content-type`, buffer overflow, unreadable body | No |
+| `aborted` | Interrupted (hidden page, offline, manual close) | No |
+| `retry-exhausted` | Retry budget spent | No |
+
+## Recipes
+
+### Refresh the token on 401
+
+A retry policy may be async, so the refresh can complete before the next attempt:
+
+```ts
+let refreshed = false;
+
+const client = new SSEClient({
+  url,
+  retry: async ({ error, attempt }) => {
+    if (error?.status === 401 && !refreshed) {
+      await refreshToken();
+      refreshed = true;
+      return 0; // retry immediately
+    }
+    return attempt > 5 ? false : Math.min(30_000, 1000 * 2 ** attempt);
+  },
+});
+```
+
+### Share one connection
+
+HTTP/1.1 allows six connections per origin, and a push channel holds one open indefinitely.
+Share it instead of opening one per component:
+
+```ts
+import { acquireSSEClient } from "@songfreedom/sse-client";
+
+const { client, release } = acquireSSEClient("alarm", () => new SSEClient({ url, body }));
+onScopeDispose(release); // closes when the last consumer releases
+```
+
+### Batch high-frequency updates
+
+When the same entity is pushed every few hundred milliseconds, coalesce before writing to state:
+
+```ts
+import { createBatcher } from "@songfreedom/sse-client";
+
+const batcher = createBatcher<string, Point>({
+  key: (point) => `${point.objectId}::${point.code}`,
+  interval: 300,
+  onFlush: (points) => store.applyPoints(points),
+});
+
+client.on("IOT", (payload) => payload.data.forEach((p) => batcher.push(p)));
+```
+
+### Rotation vs reconnect
+
+A connection can stay alive while the server-side subscription is already gone. Rotation
+reconnects on a schedule (`rotateInterval`) to avoid such zombie connections, keeping
+`lastEventId` so nothing is missed:
+
+```ts
+new SSEClient({ url, rotateInterval: 30 * 60_000 });
+```
+
+This relies on the server honouring `Last-Event-ID`. An alternative is overlapping
+connections (open a replacement, then close the old one), which avoids the gap but can
+deliver duplicates when the server pushes per connection.
+
+## Low-level building blocks
+
+The client is assembled from small pieces that are exported for advanced use:
+
+```ts
+import { createSSEParser, createSSEMessageStream, createBatcher } from "@songfreedom/sse-client";
+
+// bytes → messages, as a standard TransformStream
+const messages = response.body!.pipeThrough(createSSEMessageStream({ parse: JSON.parse }));
+
+// raw frames, if you want to drive the loop yourself
+const parser = createSSEParser({ onEvent: (event) => console.log(event) });
+parser.feed("event: ping\ndata: 1\n\n");
+```
+
+## Server requirements
+
+- Respond with `Content-Type: text/event-stream` (a `;charset=UTF-8` suffix is fine).
+- Do not buffer the response: `proxy_buffering off; proxy_cache off;` at the gateway,
+  and do not gzip the stream.
+- Send a heartbeat comment (`: ping\n\n`) every 15–30s, otherwise most load balancers
+  close the connection after 60s of silence. Pair it with `idleTimeout`.
+- Support `Last-Event-ID` if you want gap-free reconnects; the client sends the header but
+  does not de-duplicate events.
+
+## Design notes
+
+- No business logic: the client does not know about tokens, stores, toasts or routing.
+  Authentication is injected through `headers`.
+- Errors never escape as exceptions from callbacks; a throwing handler is isolated and
+  reported through `onHandlerError` while the stream keeps flowing.
+- Timers are always cleared on close, and the connection loop only exits when the client is
+  finally closed, so suspending and resuming cannot leak a loop.
+
+## License
+
+[MIT](./LICENSE)

package/batch.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Coalescing window for high-frequency streams.
+ *
+ * A single entity is often pushed several times within a few hundred
+ * milliseconds (IoT points, device state). Writing every message to state
+ * causes render storms, so messages are merged by a business key while keeping
+ * the latest value, and flushed once per window.
+ *
+ * ```ts
+ * const batcher = createBatcher<number, Point>({
+ *   key: (p) => p.pointId,
+ *   interval: 300,
+ *   onFlush: (points) => store.applyPoints(points),
+ * });
+ * client.on("IOT", (p) => batcher.push(p));
+ * ```
+ */
+export interface BatcherOptions<K, V> {
+    /** Business key used to merge values; only the last value per key survives. */
+    key: (value: V) => K;
+    /** Coalescing window in milliseconds (default 300). */
+    interval?: number;
+    /** Called once per window with the latest value per key, in first-seen order. */
+    onFlush: (values: V[]) => void;
+}
+export interface Batcher<V> {
+    /** Accept a value; replaces any pending value with the same key. */
+    push: (value: V) => void;
+    /** Flush immediately and cancel the pending window. */
+    flush: () => void;
+    /** Drop pending values without flushing. */
+    clear: () => void;
+    /** Flush and release the timer (call on unmount). */
+    dispose: () => void;
+    /** Number of values waiting to be flushed. */
+    readonly pending: number;
+}
+export declare function createBatcher<K, V>(options: BatcherOptions<K, V>): Batcher<V>;
+//# sourceMappingURL=batch.d.ts.map

package/batch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch.d.ts","sourceRoot":"","sources":["../src/batch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,EAAE,CAAC;IAClC,+EAA+E;IAC/E,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC;IACrB,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iFAAiF;IACjF,OAAO,EAAE,CAAC,MAAM,EAAE,CAAC,EAAE,KAAK,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,OAAO,CAAC,CAAC;IACxB,oEAAoE;IACpE,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;IACzB,uDAAuD;IACvD,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,4CAA4C;IAC5C,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,qDAAqD;IACrD,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,8CAA8C;IAC9C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAgB,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CA4C7E"}

package/batch.js

@@ -0,0 +1,44 @@
+export function createBatcher(options) {
+    const interval = options.interval ?? 300;
+    const buffer = new Map();
+    let timer = null;
+    const flush = () => {
+        if (timer) {
+            clearTimeout(timer);
+            timer = null;
+        }
+        if (!buffer.size) {
+            return;
+        }
+        const values = [...buffer.values()];
+        buffer.clear();
+        options.onFlush(values);
+    };
+    return {
+        push(value) {
+            buffer.set(options.key(value), value);
+            if (timer) {
+                return;
+            }
+            timer = setTimeout(() => {
+                timer = null;
+                flush();
+            }, interval);
+        },
+        flush,
+        clear() {
+            if (timer) {
+                clearTimeout(timer);
+                timer = null;
+            }
+            buffer.clear();
+        },
+        dispose() {
+            flush();
+        },
+        get pending() {
+            return buffer.size;
+        },
+    };
+}
+//# sourceMappingURL=batch.js.map

package/batch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch.js","sourceRoot":"","sources":["../src/batch.ts"],"names":[],"mappings":"AAuCA,MAAM,UAAU,aAAa,CAAO,OAA6B;IAC/D,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,GAAG,CAAC;IACzC,MAAM,MAAM,GAAG,IAAI,GAAG,EAAQ,CAAC;IAC/B,IAAI,KAAK,GAAyC,IAAI,CAAC;IAEvD,MAAM,KAAK,GAAG,GAAG,EAAE;QACjB,IAAI,KAAK,EAAE,CAAC;YACV,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,KAAK,GAAG,IAAI,CAAC;QACf,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;YACjB,OAAO;QACT,CAAC;QACD,MAAM,MAAM,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;QACpC,MAAM,CAAC,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1B,CAAC,CAAC;IAEF,OAAO;QACL,IAAI,CAAC,KAAQ;YACX,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC;YACtC,IAAI,KAAK,EAAE,CAAC;gBACV,OAAO;YACT,CAAC;YACD,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;gBACtB,KAAK,GAAG,IAAI,CAAC;gBACb,KAAK,EAAE,CAAC;YACV,CAAC,EAAE,QAAQ,CAAC,CAAC;QACf,CAAC;QACD,KAAK;QACL,KAAK;YACH,IAAI,KAAK,EAAE,CAAC;gBACV,YAAY,CAAC,KAAK,CAAC,CAAC;gBACpB,KAAK,GAAG,IAAI,CAAC;YACf,CAAC;YACD,MAAM,CAAC,KAAK,EAAE,CAAC;QACjB,CAAC;QACD,OAAO;YACL,KAAK,EAAE,CAAC;QACV,CAAC;QACD,IAAI,OAAO;YACT,OAAO,MAAM,CAAC,IAAI,CAAC;QACrB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/client.d.ts

@@ -0,0 +1,197 @@
+import { SSEError } from "./errors.js";
+import type { SSECloseReason, SSEEventMap, SSEMessage, SSEStatus, Unsubscribe } from "./types.js";
+/** Same shape as `fetch`; inject a custom transport for SSR, tests or signed requests. */
+export type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
+/** Context passed to a retry policy. */
+export interface RetryContext {
+    /** Retry number, starting at 1. */
+    attempt: number;
+    /** Why the reconnect happens; `undefined` when the server closed the stream normally. */
+    error?: SSEError;
+    /** How long the attempt was alive, in milliseconds. */
+    elapsed: number;
+}
+/**
+ * Custom retry policy: return the delay in milliseconds before the next attempt,
+ * or `false` to give up. May be async, which makes flows such as
+ * "401 → refresh the token → retry" straightforward. When omitted, the built-in
+ * exponential backoff with jitter and a max attempt count is used.
+ */
+export type RetryPolicy = (context: RetryContext) => number | false | Promise<number | false>;
+/** Client options. */
+export interface SSEClientOptions {
+    /** Request URL (include your gateway prefix yourself). */
+    url: string;
+    /** HTTP method; business push endpoints usually use POST. */
+    method?: "GET" | "POST";
+    /** Request body. Serialized as JSON, or passed through when it is a string / Blob / FormData. */
+    body?: unknown;
+    /**
+     * Extra headers. Pass a function to recompute them before every (re)connect,
+     * which is the recommended way to pick up a refreshed token:
+     * `() => getAuthHeaders()`.
+     */
+    headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+    /** Payload decoder, e.g. `(raw) => JSON.parse(raw)`. Defaults to the raw string. */
+    parse?: (raw: string) => unknown;
+    /**
+     * Idle timeout in milliseconds: reconnect when no bytes arrived for this long.
+     * `0` disables it. Two to three times the server heartbeat interval is a good value.
+     */
+    idleTimeout?: number;
+    /** Proactive rotation interval in milliseconds: reconnect on schedule to avoid zombie connections. `0` disables it. */
+    rotateInterval?: number;
+    /** Custom retry policy, overrides the built-in backoff. */
+    retry?: RetryPolicy;
+    /** Maximum retry count, unlimited by default (only used when `retry` is not provided). */
+    maxRetry?: number;
+    /** Delay before the first retry in milliseconds, defaults to 1000. */
+    retryBaseDelay?: number;
+    /** Upper bound for reconnect delays in milliseconds, defaults to 30000. */
+    retryMaxDelay?: number;
+    /** Reconnect when the server closes the stream normally, defaults to true. */
+    reconnectOnEnd?: boolean;
+    /** An attempt that lived at least this long resets the retry counter, defaults to 10000. */
+    stableAfter?: number;
+    /**
+     * Require the response `content-type` to be `text/event-stream`, defaults to true.
+     * This catches silent failures such as a gateway returning a 200 HTML page;
+     * disable it for non-compliant backends.
+     */
+    strictContentType?: boolean;
+    /** Cap for a single message buffer in characters, defaults to 1MB, guards against runaway streams. */
+    maxBufferSize?: number;
+    /**
+     * Stream-end sentinel: when `data` equals this value the stream is treated as
+     * finished (OpenAI / AI SDK style `[DONE]`) and no reconnect happens.
+     * Disabled by default.
+     */
+    endSignal?: string;
+    /** Event allow-list: only these event names are dispatched. All events are dispatched when omitted. */
+    events?: string[];
+    /**
+     * Suspend the connection while the page is hidden and reconnect when it becomes
+     * visible again. Defaults to false; recommended for WebViews and mobile, where
+     * the OS freezes background pages and leaves zombie connections behind.
+     */
+    pauseWhenHidden?: boolean;
+    /** Connect in the constructor, defaults to true. */
+    autoStart?: boolean;
+    /** Inject a fetch implementation, defaults to the global `fetch`. */
+    fetch?: FetchLike;
+    /** Fallback when a handler throws, defaults to `console.error`. */
+    onHandlerError?: (error: unknown) => void;
+    /** Fired once the connection is established (response headers received). Same as `client.onOpen()`. */
+    onOpen?: (response: Response) => void;
+    /** Fired for every message. Same as `client.onMessage()`. */
+    onMessage?: (message: SSEMessage) => void;
+    /** Fired on every state change. Same as `client.onStatus()`. */
+    onStatus?: (status: SSEStatus) => void;
+    /** Fired for every failed attempt. Same as `client.onError()`. */
+    onError?: (error: SSEError, attempt: number) => void;
+    /** Fired once when the connection is finally closed. Same as `client.onClose()`. */
+    onClose?: (reason: SSECloseReason, error?: SSEError) => void;
+}
+/**
+ * Server-Sent Events client.
+ *
+ * - Built on `fetch` + `ReadableStream`, so custom headers and POST bodies work
+ * - Reconnects automatically (exponential backoff with jitter); terminal errors
+ *   such as 401 stop immediately
+ * - Resumes with `Last-Event-ID`
+ * - Routes events by name to multiple subscribers, so one connection serves many components
+ * - Idle watchdog, proactive rotation, offline/background suspension, shared
+ *   connections (see `acquireSSEClient`)
+ */
+export declare class SSEClient<E extends object = SSEEventMap> {
+    private readonly options;
+    private readonly parser;
+    private readonly eventFilter;
+    private state;
+    private finished;
+    private running;
+    private suspended;
+    private attempt;
+    private lastEventIdValue;
+    private serverRetryDelay;
+    private idleTimedOut;
+    private rotating;
+    private idleTimer;
+    private rotateTimer;
+    private cancelController;
+    private attemptController;
+    private runPromise;
+    private resumeWaiter;
+    private lifecycleBound;
+    private onVisibilityChange?;
+    private onOffline?;
+    private onOnline?;
+    private readonly messageHandlers;
+    private readonly eventHandlers;
+    private readonly statusHandlers;
+    private readonly errorHandlers;
+    private readonly openHandlers;
+    private readonly closeHandlers;
+    constructor(options: SSEClientOptions);
+    /** Current state. */
+    get status(): SSEStatus;
+    /** Whether the client is finally closed and will not reconnect. */
+    get closed(): boolean;
+    /** Consecutive retry count; resets once a connection proves stable. */
+    get attempts(): number;
+    /** Latest event id, sent back as `Last-Event-ID` on reconnect. */
+    get lastEventId(): string;
+    /** Resolves when the connection terminates (closed or retries exhausted). Never rejects. */
+    get done(): Promise<void>;
+    /** Open the connection. No-op while already running or suspended. */
+    start(): this;
+    /** Close the connection and stop reconnecting. */
+    close(): void;
+    /** Reconnect after closing, keeping `lastEventId` so the server can resume. */
+    restart(): this;
+    /** Subscribe to one event name; returns an unsubscribe function. */
+    on<K extends Extract<keyof E, string>>(event: K, handler: (data: E[K], message: SSEMessage) => void): Unsubscribe;
+    /** Subscribe to every message by passing `"*"`. */
+    on(event: "*", handler: (data: unknown, message: SSEMessage) => void): Unsubscribe;
+    /** Subscribe to one event name for a single delivery. */
+    once<K extends Extract<keyof E, string>>(event: K, handler: (data: E[K], message: SSEMessage) => void): Unsubscribe;
+    /** Subscribe to every message regardless of event name. */
+    onMessage(handler: (message: SSEMessage) => void): Unsubscribe;
+    onStatus(handler: (status: SSEStatus) => void): Unsubscribe;
+    onError(handler: (error: SSEError, attempt: number) => void): Unsubscribe;
+    onOpen(handler: (response: Response) => void): Unsubscribe;
+    onClose(handler: (reason: SSECloseReason, error?: SSEError) => void): Unsubscribe;
+    private get retryBaseDelay();
+    private get retryMaxDelay();
+    private get maxRetry();
+    private get stableAfter();
+    private get reconnectOnEnd();
+    private reset;
+    private connect;
+    /** Open one connection and read it until the stream ends (throws on failure). */
+    private openOnce;
+    private resolveHeaders;
+    private handleParsedEvent;
+    private dispatch;
+    private emit;
+    private safeCall;
+    private reportHandlerError;
+    private decideDelay;
+    /** Reconnect delay: the server's `retry:` wins, otherwise exponential backoff with ±20% jitter. */
+    private nextDelay;
+    private sleep;
+    private waitForResume;
+    private armIdle;
+    private armRotate;
+    private clearIdle;
+    private clearRotate;
+    private clearTimers;
+    private setState;
+    /** Network state is always observed: no reconnects while offline, an immediate one when back online. */
+    private bindLifecycle;
+    private unbindLifecycle;
+    private suspend;
+    private resume;
+    private finish;
+}
+//# sourceMappingURL=client.d.ts.map

package/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}