@songfreedom/sse-client 0.0.0-stage → 0.1.0

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,295 @@
-# Temporary Holding Version
+# @songfreedom/sse-client
+
+零依赖的 SSE 客户端：核心只有 `fetch` + `ReadableStream` + 自研帧解析，Vue 适配层单独入口。
+
+## 安装
+
+```bash
+pnpm add @songfreedom/sse-client
+```
+
+Vue 入口需要项目里已有 `vue`（可选 peer，非 Vue 项目不会被强制拉取）：
+
+```bash
+pnpm add @songfreedom/sse-client vue
+```
+
+```ts
+import { SSEClient, createBatcher } from "@songfreedom/sse-client";      // 框架无关
+import { useSSE } from "@songfreedom/sse-client/vue";                    // Vue 入口
+```
+
+零运行时依赖；核心只有 `fetch` + `ReadableStream` + 自研帧解析。
+
+## 为什么不用现成库
+
+| 方案 | 问题 |
+| --- | --- |
+| 原生 `EventSource` | 不能自定义请求头（鉴权 token 无处安放）、只能 GET、不能带 body、重连策略不可控 |
+| `@microsoft/fetch-event-source` | 已归档；`onopen` 里非 2xx 必须手动抛错，否则静默死循环重连；重连间隔固定；无 `Last-Event-ID` 持久化 |
+| axios | 浏览器端读不到流式响应（`responseType: "stream"` 仅 Node 有效），`onDownloadProgress` 拼字符串会在多字节字符边界处截断 |
+
+## 设计分层
+
+```
+parser.ts    纯函数：字节流 → 事件（data/event/id/retry、CRLF、注释行、跨块半行）
+client.ts    连接生命周期：建连、重连退避、空闲超时、主动轮换、事件路由、多订阅者
+share.ts     按 key 共享连接（引用计数）
+vue.ts       useSSE：状态/事件缓存 + 作用域自动清理（peer: vue，可选）
+```
+
+库本身不知道 token、不知道 store、不弹 toast、不打日志（除回调抛错的兜底）。业务侧的鉴权头由调用方通过 `headers` 注入。
+
+## 快速开始
+
+```ts
+import { SSEClient } from "@songfreedom/sse-client";
+
+interface AlarmEvent { ALARM: { level: "high" | "low"; deviceId: string } }
+
+const client = new SSEClient<AlarmEvent>({
+  url: "/api/push/alarm/subscribe",
+  body: { topics: ["alarm"] },
+  headers: () => ({ token: localStorage.getItem("token") ?? "" }), // 每次重连都重新取
+  parse: (raw) => JSON.parse(raw),
+  idleTimeout: 45_000, // 服务端心跳 15s 时取 3 倍
+});
+
+// 按事件名订阅，一条连接服务多个业务方
+const off = client.on("ALARM", (alarm) => console.log(alarm.level));
+client.on("*", (data, message) => console.log(message.event, data));
+
+// 组件卸载时
+off();
+client.close();
+```
+
+### Vue
+
+```ts
+import { useSSE } from "@songfreedom/sse-client/vue";
+
+const { status, lastEvent, on } = useSSE<{ ALARM: AlarmEvent }>({
+  url: "/api/push/alarm/subscribe",
+  body: { topics: ["alarm"] },
+  parse: (raw) => JSON.parse(raw),
+});
+on("ALARM", (alarm) => { /* 组件卸载时自动退订 */ });
+```
+
+## API
+
+### `new SSEClient(options)`
+
+| 选项 | 说明 |
+| --- | --- |
+| `url` / `method` / `body` | 请求目标，默认 `POST` + JSON body；body 支持对象、字符串、Blob、FormData |
+| `headers` | `HeadersInit` 或返回它的函数；传函数则每次（重）连重新取，token 刷新后自动生效 |
+| `parse` | `data` 解析函数，默认原样字符串 |
+| `idleTimeout` | 多久没收到任何字节就重连，`0` 关闭（服务端有心跳时建议设成心跳间隔的 3 倍） |
+| `rotateInterval` | 主动轮换间隔，`0` 关闭（见下） |
+| `retry` | 自定义重试策略 `(ctx) => 延迟ms \| false`，覆盖内置退避 |
+| `maxRetry` / `retryBaseDelay` / `retryMaxDelay` | 内置退避参数（初始化 1s，上限 30s，±20% 抖动，下限 200ms） |
+| `reconnectOnEnd` | 服务端正常结束流后是否重连，默认 `true` |
+| `strictContentType` | 强校验响应必须是 `text/event-stream`，默认 `true`；可拦住「网关返回 200 HTML」 |
+| `maxBufferSize` | 单条消息缓冲上限（字符数），默认 1MB，超过直接判定协议错误 |
+| `endSignal` | 流结束哨兵，data 等于该值（如 `[DONE]`）时按正常结束收尾且不重连 |
+| `events` | 事件白名单，只投递这些事件名；缺省全投 |
+| `pauseWhenHidden` | 页面隐藏时挂起、回前台自动重连，默认 `false`；WebView / 移动端建议开 |
+| `fetch` | 注入 fetch 实现，便于 SSR / 测试 / 自定义 transport |
+| `onHandlerError` | 回调抛错兜底，默认 `console.error`（不会中断连接） |
+
+实例方法：`on(event, handler)`（返回退订函数）、`once(event, handler)`、`on("*")`、`onMessage`、`onStatus`、`onError`、`onOpen`、`onClose`、`start`、`close`、`restart`；getter：`status`、`closed`、`attempts`、`lastEventId`、`done`。
+
+消息结构：`{ id, event, data, raw, receivedAt }`，`receivedAt` 便于做本地过期判断。
+
+状态流转：`idle → connecting → open → reconnecting → closed`，`connecting/open/closed` 可直接绑 UI；断网或切后台挂起时回到 `idle`。
+
+### 断网与前后台（默认行为）
+
+- **断网**（`offline` 事件）：立即中断当前连接并停止重连，不再打服务端；`online` 后立刻重连（带 `Last-Event-ID`）。避免离线期间的重试风暴。
+- **切后台**：默认不影响连接；`pauseWhenHidden: true` 时页面隐藏即挂起、回到前台重连。WebView 后台会被系统挂起，留着连接只会变僵尸，移动端建议开启。
+- 主动 `close()` 会解绑这些全局监听，不留残留。
+
+### 错误分类
+
+`SSEError.kind` 用于日志聚合和策略分支：
+
+| kind | 含义 | 默认是否重连 |
+| --- | --- | --- |
+| `http` | 非 2xx（`status` 有值） | 408/425/429/5xx 重连，其余终止 |
+| `network` | DNS / 连接重置等 | 是 |
+| `heartbeat` | 静默超时，连接疑似僵死 | 是 |
+| `protocol` | content-type 不符、缓冲溢出、body 不可读 | 否 |
+| `aborted` | 被中断（切后台、断网、主动关闭） | 否 |
+| `retry-exhausted` | 重试次数耗尽 | 否 |
+
+### 重试策略（扩展点）
+
+内置策略对 401/403/404 等 4xx 直接终止，只重试 408/425/429/5xx 与网络异常。需要「401 刷新 token 再重试」这类逻辑时：
+
+```ts
+let refreshed = false;
+const client = new SSEClient({
+  url,
+  // 支持 async：401 时先真正刷新 token，再决定是否重连
+  retry: async ({ error, attempt }) => {
+    if (error?.status === 401 && !refreshed) {
+      await refreshToken();
+      refreshed = true;
+      return 0; // 立即重试
+    }
+    return attempt > 5 ? false : Math.min(30_000, 1000 * 2 ** attempt);
+  },
+});
+```
+
+## 与 AI SDK 的对照
+
+AI SDK（[Stream Protocols](https://ai-sdk.dev/docs/ai-sdk-ui/stream-protocol)）的流是「一条 SSE 承载多种 `data.type` part」，客户端按 part 建状态机；业务推送是「按 `event:` 路由 + 业务归并」。目标不同，但有几处可以直接借：
+
+| AI SDK 的做法 | 这里怎么处理 |
+| --- | --- |
+| `[DONE]` 终止哨兵 | 提供 `endSignal: "[DONE]"`。差异：AI SDK 只是**丢弃**这条、等连接关闭；我们**主动结束**，避免 `reconnectOnEnd` 下反复重连 |
+| 每条 data 过 schema 校验，失败不抛而是作为值下传 | 用 `parse` 抛错即可：只丢这一条并回调 `onHandlerError`，流不中断；不引入 zod |
+| `pipeThrough` 组合式（`TextDecoderStream` → `EventSourceParserStream` → `TransformStream`） | 提供 `createSSEMessageStream()`，用于自定义 transport / Service Worker / Edge |
+| `retryWithExponentialBackoff`：`shouldRetry` 可 async、延迟可插拔、耗尽时聚合 errors | `RetryPolicy` 支持 async 与完全自定义延迟；错误不聚合，靠 `SSEError.kind` 区分 |
+| `text-start/delta/end` 按 id 合并成 part | 推送不是 delta 协议；等价的「按 key 合并取最新」用 `createBatcher()` |
+| `useChat` 的 `status` 状态机 + `onData` 瞬时数据 | 已有 `status` 枚举 + 事件路由 |
+| transport 抽象（`prepareSendMessagesRequest` 等） | `fetch` 注入 + `headers` 函数足够 |
+| `smoothStream`、断点重放、message parts 持久化 | 未采纳——属于聊天产品语义，不是连接层能力 |
+
+### 连接共享
+
+同一份订阅被多个组件消费时，只建一条连接：
+
+```ts
+const { client, release } = acquireSSEClient("alarm", () => new SSEClient({ url, body }));
+onScopeDispose(release); // 最后一个引用释放时自动 close
+```
+
+## 数据层放哪
+
+库只负责连接，**不持有业务数据**。`meos-control-web` 的做法可以拿来对照：
+
+| 维度 | meos-control-web | 本库 + 应用层建议 |
+| --- | --- | --- |
+| 连接 | 每个组件 `new SSEClient`，N 个组件 = N 条连接 | `acquireSSEClient(key)` 引用计数，同 key 只有一条 |
+| 数据 | 模块级单例 `DockSingleton`（内部一个全局 `ref`，按 objectId 归并） | pinia store，按业务域拆分 |
+| 过期 | 单例 `IotExpireManager` + 15s 轮询 + `expire` 事件 | 用消息上的 `receivedAt` 在 getter 里算，或 store 内自己的定时器 |
+| 合并 | `useResponsiveDockSSEHandle` 里 300ms 窗口，按 `objectId::infoCode` 去重取最新 | `createBatcher()` |
+| 生命周期 | `onMounted` 注册、`onBeforeUnmount` 反注册，手动配对 | `onScopeDispose` + 引用计数自动配对 |
+
+**值得借的三点**
+
+1. 按业务 key 增量合并（`Object.assign` 覆盖字段），避免整对象替换导致组件全量重渲染。
+2. 合并窗口（300ms）——高频推送下这是必须的，否则每次推都是「写库 → 触发渲染」。
+3. 数据过期标记：推送类数据一定有「多久没更新就算失效」的语义，UI 要能显示「暂无数据」而不是永远显示上次的值。
+
+**不要照搬的四点**
+
+1. 全局单例当数据总线：qiankun 子应用卸载后模块级 `ref` 还在，重新挂载会带着上次的脏数据；而且没有引用计数，谁都能写、没人负责清。
+2. `window.iotHandle = ...` 这类调试钩子——应该由调试工具或 devtools 提供。
+3. 模块导入即启动定时器（`IotExpireManager.getInstance()` 在 import 时就 `startExpireCheck()`），副作用不可控。
+4. 每组件一条连接：HTTP/1.1 同域只有 6 个并发，推送通道很容易把其他接口挤排队。
+
+推荐的组合是 pinia（数据域）+ 本库（连接）+ 消费者引用计数（谁用谁 retain）：
+
+```ts
+// stores/alarm.ts
+export const useAlarmStore = defineStore("alarm", () => {
+  const items = shallowRef<Map<string, Alarm>>(new Map());
+
+  const batcher = createBatcher<string, Alarm>({
+    key: (alarm) => alarm.id,
+    interval: 300,
+    onFlush: (list) => {
+      const next = new Map(items.value);
+      list.forEach((alarm) => next.set(alarm.id, alarm));
+      items.value = next; // 替换引用，shallowRef 才会触发更新
+    },
+  });
+
+  const client = new SSEClient<{ ALARM: Alarm }>({ url, body, autoStart: false });
+  client.on("ALARM", (alarm) => batcher.push(alarm));
+
+  let refs = 0;
+  function retain() {
+    refs += 1;
+    if (refs === 1) client.start();
+  }
+  function release() {
+    refs = Math.max(0, refs - 1);
+    if (refs === 0) {
+      batcher.dispose(); // 冲刷窗口内剩余数据
+      client.close();
+    }
+  }
+
+  return { items, retain, release };
+});
+
+// 组件里
+const alarmStore = useAlarmStore();
+alarmStore.retain();
+onScopeDispose(() => alarmStore.release());
+```
+
+如果同一条订阅要跨多个 store / 模块共享，把 `new SSEClient` 换成 `acquireSSEClient(key, factory)`，它的引用计数语义相同、且按 key 全局唯一。
+
+## 服务端与网关约定
+
+- 响应头必须是 `Content-Type: text/event-stream`（可能带 `;charset=UTF-8`，校验按前缀匹配），并且 **不能被代理层缓冲**：`proxy_buffering off; proxy_cache off;`，该路径不要开 gzip。
+- 建议每 15s 发一次 `: ping\n\n` 心跳，否则多数云 LB 的 60s idle 会断开；配合 `idleTimeout` 使用。
+- 事件 id 建议单调递增（或至少唯一）。重连时客户端会带 `Last-Event-ID`，服务端按语义只补发其后的消息；客户端不做去重。
+- 事件类型通过 `event:` 字段下发，客户端按该字段路由。
+
+## 主动轮换 vs 断线重连
+
+轮换是为了防止「TCP 活着、心跳还在，但服务端订阅已失效」的假活连接：到 `rotateInterval` 后客户端主动断开并立即重连（保留 `lastEventId`，不走退避）。
+
+对比双连接 overlap 方案（新连接 open 后再切旧连接）：overlap 能消除重连窗口，但要求服务端按连接推送而非按事件流推送，否则同一事件会被两条连接各推一次；本实现选择「断开 + `Last-Event-ID` 续传」，实现简单且不产生重复推送，代价是需要服务端支持续传语义。
+
+## 开发
+
+```bash
+pnpm --filter @songfreedom/sse-client test
+pnpm --filter @songfreedom/sse-client typecheck
+pnpm --filter @songfreedom/sse-client lint
+```
+
+## 构建与发布
+
+**双入口设计**，开发时零构建、发布时只发产物：
+
+| 场景 | 走哪里 | 原因 |
+| --- | --- | --- |
+| 仓库内（`apps/web` 等） | `exports` → `./src/*.ts` | Vite 直接编译源码，改库代码立即 HMR |
+| npm 包 | `dist/` + `dist/package.json` | 消费方拿到 JS + `.d.ts`，不需要编译 TS |
+
+`pnpm build` 做两件事：`tsc` 把 `src` 编译成 ESM + `.d.ts` + sourcemap 到 `dist/`，然后由 `scripts/build-package.mjs` 生成 `dist/package.json` 并拷入 README。
+
+发布到 npmjs（`publishConfig` 已指向 `registry.npmjs.org` + `access: public`）：
+
+```bash
+npm login --registry https://registry.npmjs.org   # 只需一次
+pnpm --filter @songfreedom/sse-client publish:npm  # build + publish
+```
+
+只想先看打包内容不发布：
+
+```bash
+pnpm --filter @songfreedom/sse-client publish --dry-run --no-git-checks
+```
+
+约定：
+
+- 发布走 `publishConfig.directory: dist`，所以**必须先 build**（`publish:npm` 已包含）。
+- `vue` 是 **optional peer**，非 Vue 项目安装不会被迫拉 vue。
+- `sideEffects: false`，消费方可 tree-shaking。
+- 版本号每次发布必须递增，npm 不允许覆盖已有版本。
+
+## License
+
+[MIT](./LICENSE)
 
-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.

package/batch.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 高频推送的合并窗口。
+ *
+ * 业务推送常见「同一对象在几百毫秒内连推多次」的场景（IOT 点位、设备状态），
+ * 逐条写库会引发渲染风暴。这里按业务 key 合并、保留最新值，在一个时间窗后统一回调。
+ *
+ * ```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> {
+    /** 合并用的业务键，同一 key 只保留最后一次的值 */
+    key: (value: V) => K;
+    /** 合并窗口（毫秒），默认 300 */
+    interval?: number;
+    /** 窗口结束时的回调，按首次出现的顺序给出每个 key 的最新值 */
+    onFlush: (values: V[]) => void;
+}
+export interface Batcher<V> {
+    /** 写入一条数据；同一 key 覆盖旧值 */
+    push: (value: V) => void;
+    /** 立即冲刷并取消本次窗口 */
+    flush: () => void;
+    /** 丢弃尚未冲刷的数据 */
+    clear: () => void;
+    /** 冲刷并释放定时器（组件卸载时调用） */
+    dispose: () => void;
+    /** 待冲刷的数据条数 */
+    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;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,EAAE,CAAC;IAClC,+BAA+B;IAC/B,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC;IACrB,sBAAsB;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qCAAqC;IACrC,OAAO,EAAE,CAAC,MAAM,EAAE,CAAC,EAAE,KAAK,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,OAAO,CAAC,CAAC;IACxB,yBAAyB;IACzB,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;IACzB,kBAAkB;IAClB,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,gBAAgB;IAChB,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,wBAAwB;IACxB,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,eAAe;IACf,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":"AAqCA,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,187 @@
+import { SSEError } from "./errors.js";
+import type { SSECloseReason, SSEEventMap, SSEMessage, SSEStatus, Unsubscribe } from "./types.js";
+/** 与 `fetch` 同形，便于注入自定义 transport（SSR、测试、带签名的请求） */
+export type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
+/** 重试决策上下文 */
+export interface RetryContext {
+    /** 第几次重试，从 1 开始 */
+    attempt: number;
+    /** 触发重连的原因；服务端正常结束流时为 undefined */
+    error?: SSEError;
+    /** 本次连接存活时长（毫秒） */
+    elapsed: number;
+}
+/**
+ * 自定义重试策略：返回下次重连延迟（毫秒），返回 `false` 表示终止。
+ * 支持 async，便于「401 → 先刷新 token → 再重试」这类需要等待的决策。
+ * 不传则使用内置的「指数退避 + 抖动 + 最大次数」。
+ */
+export type RetryPolicy = (context: RetryContext) => number | false | Promise<number | false>;
+/** 客户端配置 */
+export interface SSEClientOptions {
+    /** 请求地址（需自行带上网关前缀） */
+    url: string;
+    /** 请求方法，业务推送一般用 POST */
+    method?: "GET" | "POST";
+    /** 请求体，非 GET 时按 JSON 序列化；也支持直接传字符串 / Blob / FormData */
+    body?: unknown;
+    /**
+     * 额外请求头。传函数则每次（重）连都重新取，
+     * 便于拿到最新 token，因此推荐 `() => getCommonHeaders()`。
+     */
+    headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+    /** data 解析，例如 `(raw) => JSON.parse(raw)`；不传则 data 为原始字符串 */
+    parse?: (raw: string) => unknown;
+    /** 空闲超时（毫秒）：多久没收到任何字节就断开重连，0 表示关闭。建议取心跳间隔的 2~3 倍 */
+    idleTimeout?: number;
+    /** 主动轮换间隔（毫秒）：到点后主动重连，防止连接假活，0 表示关闭 */
+    rotateInterval?: number;
+    /** 自定义重试策略，覆盖内置退避 */
+    retry?: RetryPolicy;
+    /** 最大重试次数，默认无限（仅在未传 `retry` 时生效） */
+    maxRetry?: number;
+    /** 首次重连延迟（毫秒），默认 1000 */
+    retryBaseDelay?: number;
+    /** 重连延迟上限（毫秒），默认 30000 */
+    retryMaxDelay?: number;
+    /** 服务端正常结束流后是否自动重连，默认 true */
+    reconnectOnEnd?: boolean;
+    /** 连接存活超过该时长即视为稳定，重置重试计数，默认 10000 */
+    stableAfter?: number;
+    /**
+     * 强校验响应 `content-type` 必须是 `text/event-stream`，默认 true。
+     * 能拦住「网关/鉴权页返回 200 HTML」这类静默失败；后端不规范时可关闭。
+     */
+    strictContentType?: boolean;
+    /** 单条消息缓冲上限（字符数），默认 1MB，防止异常流撑爆内存 */
+    maxBufferSize?: number;
+    /**
+     * 流结束哨兵：data 等于该值时视为正常结束（OpenAI / AI SDK 风格用 `[DONE]`），
+     * 触发后按「正常结束」收尾且不再重连。默认不启用。
+     */
+    endSignal?: string;
+    /** 事件白名单：只投递这些事件名，缺省全部投递 */
+    events?: string[];
+    /**
+     * 页面隐藏时挂起连接、回到前台自动重连，默认 false。
+     * WebView / 移动端建议开启（后台会被系统挂起，留着连接只会变僵尸）。
+     */
+    pauseWhenHidden?: boolean;
+    /** 是否在构造后立即连接，默认 true */
+    autoStart?: boolean;
+    /** 注入 fetch 实现，默认使用全局 fetch */
+    fetch?: FetchLike;
+    /** 事件处理函数抛错时的兜底，默认打到控制台 */
+    onHandlerError?: (error: unknown) => void;
+    /** 连接建立（已收到响应头）时触发，等价于 `client.onOpen()` */
+    onOpen?: (response: Response) => void;
+    /** 所有消息都会触发，等价于 `client.onMessage()` */
+    onMessage?: (message: SSEMessage) => void;
+    /** 状态变化，等价于 `client.onStatus()` */
+    onStatus?: (status: SSEStatus) => void;
+    /** 每次失败触发，等价于 `client.onError()` */
+    onError?: (error: SSEError, attempt: number) => void;
+    /** 最终关闭时触发一次，等价于 `client.onClose()` */
+    onClose?: (reason: SSECloseReason, error?: SSEError) => void;
+}
+/**
+ * SSE 客户端。
+ *
+ * - 基于 `fetch` + `ReadableStream`，支持自定义请求头与 POST body
+ * - 断线自动重连（指数退避 + 抖动），401 等不可重试错误直接终止
+ * - 用 `Last-Event-ID` 做断点续传
+ * - 按事件名路由到多个订阅者，一条连接服务多个组件
+ * - 空闲看门狗、主动轮换、断网/切后台挂起、连接共享（见 `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);
+    /** 当前状态 */
+    get status(): SSEStatus;
+    /** 是否已最终关闭（不会再重连） */
+    get closed(): boolean;
+    /** 连续重试次数，连接稳定后归零 */
+    get attempts(): number;
+    /** 最近一次事件 id，重连时通过 Last-Event-ID 带给服务端 */
+    get lastEventId(): string;
+    /** 连接终止（无论正常关闭还是放弃重连）后 resolve，不会 reject */
+    get done(): Promise<void>;
+    /** 建立连接；已连接或已挂起时调用无副作用 */
+    start(): this;
+    /** 主动关闭，不再重连 */
+    close(): void;
+    /** 关闭后重新连接，保留 lastEventId 以便续传 */
+    restart(): this;
+    /** 订阅指定事件名的消息，返回取消订阅函数 */
+    on<K extends Extract<keyof E, string>>(event: K, handler: (data: E[K], message: SSEMessage) => void): Unsubscribe;
+    /** 订阅所有消息（event 为 "*"） */
+    on(event: "*", handler: (data: unknown, message: SSEMessage) => void): Unsubscribe;
+    /** 只订阅一次，触发后自动退订 */
+    once<K extends Extract<keyof E, string>>(event: K, handler: (data: E[K], message: SSEMessage) => void): Unsubscribe;
+    /** 订阅所有消息（不区分事件名） */
+    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;
+    /** 建立一次连接并持续读取，直到流结束（失败时抛错） */
+    private openOnce;
+    private resolveHeaders;
+    private handleParsedEvent;
+    private dispatch;
+    private emit;
+    private safeCall;
+    private reportHandlerError;
+    private decideDelay;
+    /** 重连延迟：服务端 `retry:` 优先，否则指数退避 + ±20% 抖动 */
+    private nextDelay;
+    private sleep;
+    private waitForResume;
+    private armIdle;
+    private armRotate;
+    private clearIdle;
+    private clearRotate;
+    private clearTimers;
+    private setState;
+    /** 网络上下线始终启用：断网期间不重连，恢复后立即重连 */
+    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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"}