sse-stream-plugin-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ryan
+
+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

@@ -0,0 +1,318 @@
+# sse-stream-plugin-sdk
+
+插件化跨端 SSE 核心 SDK。框架无关，零运行时依赖，提供可插拔的传输层、解析器、请求/事件中间件和统一插件契约。
+
+## 安装
+
+```bash
+npm install sse-stream-plugin-sdk
+# 或
+pnpm add sse-stream-plugin-sdk
+```
+
+## 快速开始
+
+### 浏览器（自动探测 fetch）
+
+```ts
+import { PluginSSE, recommendedPlugins } from 'sse-stream-plugin-sdk'
+
+const sse = new PluginSSE({
+  url: 'https://api.example.com/stream',
+  method: 'POST',
+  body: JSON.stringify({ prompt: '你好' }),
+  headers: { 'Content-Type': 'application/json' },
+  plugins: recommendedPlugins(), // 重连 + 心跳 + 节流
+})
+
+sse.on('message', (data) => console.log('收到：', data))
+sse.on('error', (err) => console.error(err))
+sse.on('end', () => console.log('流结束'))
+
+sse.connect()
+```
+
+### 小程序（通过 `createMpTransport` 注入平台 API）
+
+```ts
+import { PluginSSE, createMpTransport, recommendedPlugins } from 'sse-stream-plugin-sdk'
+
+const sse = new PluginSSE({
+  url: 'https://api.example.com/stream',
+  method: 'POST',
+  body: JSON.stringify({ prompt: '你好' }),
+  // 微信：wx；抖音：tt；快手：ks；百度：swan；QQ：qq
+  transport: createMpTransport(() => wx),
+  plugins: recommendedPlugins(),
+})
+
+sse.on('message', (data) => { /* 处理流式文本 */ })
+sse.connect()
+```
+
+## 核心 API
+
+### `PluginSSE`
+
+```ts
+new PluginSSE(options: PluginSSEOptions)
+```
+
+#### 配置项 `PluginSSEOptions`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `url` | `string` | 请求地址（必填） |
+| `method` | `'GET' \| 'POST'` | 请求方法，默认 `GET` |
+| `body` | `string` | 请求体字符串，POST 时发送 |
+| `headers` | `Record<string, string>` | 自定义请求头 |
+| `transport` | `string \| TransportFactory` | 传输层：名称（`web`/`mock` 或插件注册的名称）或工厂；省略则自动探测 `fetch` |
+| `plugins` | `SSEPlugin[]` | 初始插件列表 |
+| `parser` | `ParserFactory` | 自定义解析器，默认标准 SSE |
+
+#### 实例方法
+
+| 方法 | 说明 |
+|------|------|
+| `connect()` | 建立连接 |
+| `destroy()` | 永久销毁：中止连接、释放插件资源、清空订阅 |
+| `use(plugin)` | 注册插件（链式调用） |
+| `on(event, listener)` | 订阅事件，返回取消订阅函数 |
+| `once(event, listener)` | 订阅一次 |
+| `off(event, listener)` | 取消订阅 |
+
+#### 事件
+
+| 事件 | 参数 | 说明 |
+|------|------|------|
+| `connecting` | `{ session }` | 开始连接 |
+| `open` | `{ transport }` | 连接已打开，传输层名称 |
+| `response` | `{ status, headers? }` | 收到响应头 |
+| `data` | `chunk: string` | 收到原始文本分片 |
+| `event` | `ParsedEvent` | 解析出的结构化事件 |
+| `message` | `data: string, event: ParsedEvent` | `message` 事件（默认事件类型） |
+| `end` | — | 流正常结束 |
+| `error` | `err: unknown` | 连接/读取错误 |
+| `reconnect` | `{ attempt, inMs }` | 即将重连 |
+| `reconnect-failed` | `err` | 达到最大重试次数 |
+| `heartbeat-lost` | — | 心跳超时 |
+| `closed` | — | 实例已销毁 |
+
+### 推荐插件组合
+
+```ts
+import { recommendedPlugins } from 'sse-stream-plugin-sdk'
+
+// 自动重连 + 心跳检测 + 消息节流
+const plugins = recommendedPlugins()
+```
+
+## 传输层
+
+### 内置传输层
+
+| 名称 | 说明 |
+|------|------|
+| `web` | 基于 `fetch` + `ReadableStream`，浏览器/H5 环境 |
+| `mock` | 按脚本定时产出 SSE 文本，用于测试和演示 |
+
+### 小程序传输层（工厂模式）
+
+core 不绑定任何具体小程序平台，通过 `createMpTransport` 工厂注入平台 `request` API：
+
+```ts
+import { createMpTransport } from 'sse-stream-plugin-sdk'
+
+// 微信
+createMpTransport(() => wx)
+// 抖音
+createMpTransport(() => tt)
+// 快手
+createMpTransport(() => ks)
+// 百度
+createMpTransport(() => swan)
+// QQ
+createMpTransport(() => qq)
+```
+
+> 微信/抖音/快手/百度/QQ 的 `request` API 同构，均支持 `enableChunked` + `onChunkReceived`，因此一个工厂覆盖全部。
+
+### 作为插件注册（命名引用）
+
+```ts
+import { PluginSSE, createMpTransport } from 'sse-stream-plugin-sdk'
+
+const sse = new PluginSSE({ url })
+
+sse.use({
+  name: 'wx-transport',
+  install(ctx) {
+    ctx.registerTransport('wx', createMpTransport(() => wx))
+  },
+})
+
+// 之后用名称引用
+const sse2 = new PluginSSE({ url, transport: 'wx' })
+```
+
+### 自定义传输层
+
+实现 `Transport` 接口即可接入任何运行环境：
+
+```ts
+import type { Transport, TransportFactory, TransportEvents, RequestConfig } from 'sse-stream-plugin-sdk'
+
+const myTransport: TransportFactory = (): Transport => ({
+  name: 'my-transport',
+  connect(req: RequestConfig, events: TransportEvents) {
+    // 发起请求，通过 events.data / events.end / events.error 回调
+  },
+  abort() {
+    // 中止连接
+  },
+})
+```
+
+## 内置插件
+
+### `reconnectPlugin` — 自动重连 + 断线续传
+
+```ts
+reconnectPlugin({
+  maxRetries: 3,   // 最大重试次数，默认 3
+  delay: 1500,     // 重试等待毫秒，默认 1500
+})
+```
+
+自动记忆最近事件 `id`，重连时注入 `Last-Event-ID` 请求头实现续传。
+
+### `heartbeatPlugin` — 心跳检测
+
+```ts
+heartbeatPlugin({
+  interval: 10000, // 心跳超时毫秒，默认 10000
+})
+```
+
+任意数据到达即续命；超时未收到数据则触发 `heartbeat-lost` 并走错误流程（可由重连插件接管）。
+
+### `throttlePlugin` — 消息节流
+
+```ts
+throttlePlugin({
+  windowMs: 100, // 合并窗口毫秒，默认 100
+})
+```
+
+按时间窗口合并 `message` 事件数据，高频流式场景下显著减少渲染次数。被合并事件保留最后一个 `id`，续传位点不丢失。
+
+### `authPlugin` — 鉴权注入与自动刷新
+
+```ts
+authPlugin({
+  getToken: () => localStorage.getItem('token') || '',
+  refreshToken: async () => {
+    const res = await fetch('/api/refresh')
+    const { token } = await res.json()
+    localStorage.setItem('token', token)
+    return token
+  },
+  header: 'Authorization', // 默认 Authorization
+  scheme: 'Bearer',        // 默认 Bearer；传空串表示不加前缀
+})
+```
+
+每次连接前注入鉴权头；收到 401 时自动刷新令牌并重连（仅刷新一次防止死循环）。
+
+### `loggerPlugin` — 生命周期日志
+
+```ts
+loggerPlugin({
+  sink: (msg) => console.log(msg), // 默认 console.log
+})
+```
+
+### `statsPlugin` — 统计（自定义插件示例）
+
+```ts
+statsPlugin({
+  keyword: '✅', // 命中关键字时派发 keyword 事件，默认 ✅
+})
+```
+
+统计消息条数与字符数，通过 `stats` 事件广播；是"第三方风格"插件的范例。
+
+## 开发自定义插件
+
+插件统一实现 `SSEPlugin` 接口，通过 `PluginContext` 扩展能力：
+
+```ts
+import type { SSEPlugin, PluginContext } from 'sse-stream-plugin-sdk'
+
+const myPlugin: SSEPlugin = {
+  name: 'my-plugin',
+
+  install(ctx: PluginContext) {
+    // 1. 注册请求中间件（改写请求：加头、改 URL 等）
+    ctx.addRequestMiddleware(async (req, next) => {
+      req.headers['X-Custom'] = 'value'
+      return next(req)
+    })
+
+    // 2. 注册事件中间件（改写/拦截事件）
+    ctx.addEventMiddleware((event, next) => {
+      if (event.name === 'ping') return // 丢弃 ping 事件
+      next(event)
+    })
+
+    // 3. 注册命名传输层
+    ctx.registerTransport('custom', myTransportFactory)
+
+    // 4. 替换解析器
+    ctx.setParser(myParserFactory)
+
+    // 5. 订阅事件总线
+    ctx.emitter.on('message', (data) => { /* ... */ })
+
+    // 6. 主动发起重连
+    // ctx.start()
+
+    // 7. 主动上报错误
+    // ctx.fail(new Error('...'))
+
+    // 8. 注册销毁回调
+    ctx.onDispose(() => { /* 释放资源 */ })
+  },
+}
+```
+
+`PluginContext` 完整能力：
+
+| 方法/属性 | 说明 |
+|-----------|------|
+| `emitter` | 事件总线 |
+| `request` | 当前请求配置（只读） |
+| `addRequestMiddleware(mw)` | 注册请求中间件 |
+| `addEventMiddleware(mw)` | 注册事件中间件 |
+| `setParser(factory)` | 替换流解析器 |
+| `registerTransport(name, factory)` | 注册命名传输层 |
+| `start()` | 发起（重）连接 |
+| `fail(err)` | 上报错误并走错误流程 |
+| `getState()` | 获取内核状态 |
+| `isDead()` | 是否已销毁 |
+| `onDispose(fn)` | 注册销毁回调 |
+
+## 平台兼容性
+
+| 平台 | 传输层 | 流式支持 |
+|------|--------|---------|
+| 浏览器 / H5 | `webFetchTransport`（fetch） | ✅ |
+| 微信小程序 | `createMpTransport(() => wx)` | ✅ |
+| 抖音小程序 | `createMpTransport(() => tt)` | ✅ |
+| 快手小程序 | `createMpTransport(() => ks)` | ✅ |
+| 百度小程序 | `createMpTransport(() => swan)` | ✅ |
+| QQ 小程序 | `createMpTransport(() => qq)` | ✅ |
+
+## License
+
+MIT