@16x/webphone-sdk 3.0.1 → 3.1.0

package/CHANGELOG.md

@@ -1,22 +1,39 @@
-# Changelog
-
-## Unreleased
-
-- 新增 SharedWorker 多标签页协调能力的公开配置、worker 构建产物、调用归属事件和单标签页 fallback scaffolding。
-- 新增 SharedWorker 多标签页 smoke/soak 验收脚本；连接建立速率上限为每秒 30 次。
-- 该能力不改变 3.0.1 的单标签页兼容 API；生产跨标签页矩阵验证完成后建议随下一个 minor 版本发布。
-
-## 3.0.1 - 2026-09-19
-
-- 发布 WebPhone SDK 3.0.1，包含 WSS ticket 通过 `Sec-WebSocket-Protocol` 传递及 API 主机相对路径解析修复。
-
-## 0.1.0 - 2026-09-18
-
-- 完成 Headless Core 生命周期、SIP/通话控制、媒体设备、重连与脱敏诊断能力。
-- 提供 ESM、CJS、UMD、类型声明及根入口、`/ui`、`/legacy`、`/diagnostics`、`/styles.css` 导出。
-- 新增旧 `CCBarSDK` 兼容层，按设计映射连接、拨号、当前通话控制和坐席状态方法。
-- `insideCall(number)` 在当前 `DialOptions` 不支持 `type` 时保留原目标号码，不添加隐式前缀。
-- `setBu()` 改为抛出明确的 `DeprecatedError`，不允许浏览器伪造忙碌状态。
-- Legacy 弃用警告仅在开发构建中按方法输出一次；生产构建保持安静。
-- 显式导入 `/legacy` 时才在浏览器附加 `window.CCBarSDK`，并保持 SSR 导入安全。
-- 增加 50 次初始化、连接、拨号、结束和销毁生命周期资源回收测试。
+# Changelog
+
+## 3.1.0 - 2026-09-21
+
+- 新增可选构造参数 `sessionProvider`：由接入方提供会话（`createSession` / 可选 `refreshSession`
+  / `setAgentStatus`），SDK 不再要求必须存在 `/webphone/v1/sessions`。用于把 SDK 接到自建或旧平台
+  （例如 `token/fs` + `seat/account/get` 那一套）上，`tokenProvider` 与 `sessionProvider` 二选一。
+- `sessionProvider` 缺省 `refreshSession` 时用 `createSession` 重建；缺省 `setAgentStatus` 时抛
+  `CAPABILITY_NOT_SUPPORTED`，不静默失败；没有提供任何来源时构造即报 `CONFIG_INVALID`。
+- `transport.ticket` 为空时不再声明 `xcall-ticket.` 子协议，只发 `sip`：旧平台把凭据放在
+  WSS URL 的 `?token=` 上，多余子协议会让握手带上一个平台不认识的协议名。
+- REGISTER 的 `register_expires` 改为按 `session.sip.registerExpires` 走（原先前端写死 300 秒），
+  会话没给或给了非正数时才回退 300。平台侧要按自己的注册策略下发这个值。
+- 打包脚本在缺少 `zip` 命令的环境（如未装 zip 的 Windows）回退到系统自带 `tar`，交付包仍为 `.zip`。
+
+## 3.0.2 - 2026-09-21
+
+- 修复 disconnect 后仍挂着的 `online`/`offline` 监听，以及 `deletedSessions` 墓碑无限增长。
+- `CallManager` 在通话结束通知完成后删除 terminal 记账；`dispose` 仍会清空剩余 maps。
+- `WebPhoneApi` 的 fetch 使用 `credentials: 'omit'`；SIP `wssUrl` 仅允许 `wss:` 或 loopback `ws:`。
+- React / Vue 在应用卸载时 `dispose()`；Vanilla default-ui 与 Mobile H5 通过 `ownsClient` 在组件卸载时释放。
+- 传入 `sharedWorker` 时 `CCBarClient` 会 attach 同源 Worker，并在 `dispose()` 时先 detach 再关闭端口；SIP 仍是单标签页。
+- 诊断报告中的 SDK 版本与 `@16x/webphone-sdk@3.0.2` 对齐。
+
+## 3.0.1 - 2026-09-19
+
+- 以 `@16x/webphone-sdk` 发布到 npmjs：https://www.npmjs.com/package/@16x/webphone-sdk
+- 发布 WebPhone SDK 3.0.1，包含 WSS ticket 通过 `Sec-WebSocket-Protocol` 传递及 API 主机相对路径解析修复。
+
+## 0.1.0 - 2026-09-18
+
+- 完成 Headless Core 生命周期、SIP/通话控制、媒体设备、重连与脱敏诊断能力。
+- 提供 ESM、CJS、UMD、类型声明及根入口、`/ui`、`/legacy`、`/diagnostics`、`/styles.css` 导出。
+- 新增旧 `CCBarSDK` 兼容层，按设计映射连接、拨号、当前通话控制和坐席状态方法。
+- `insideCall(number)` 在当前 `DialOptions` 不支持 `type` 时保留原目标号码，不添加隐式前缀。
+- `setBu()` 改为抛出明确的 `DeprecatedError`，不允许浏览器伪造忙碌状态。
+- Legacy 弃用警告仅在开发构建中按方法输出一次；生产构建保持安静。
+- 显式导入 `/legacy` 时才在浏览器附加 `window.CCBarSDK`，并保持 SSR 导入安全。
+- 增加 50 次初始化、连接、拨号、结束和销毁生命周期资源回收测试。

package/LICENSE

@@ -1,2 +1 @@
-Copyright 16X. All rights reserved.
-Private customer distribution only. No redistribution or sublicensing without written permission.
+Copyright 16X. All rights reserved.

package/README.md

@@ -1,113 +1,113 @@
-# CCBar WebPhone SDK Core
-
-`@16x/webphone-sdk` 是 CCBar WebPhone 的 TypeScript SDK。Core 提供无 UI 的连接、通话、媒体设备、重连和脱敏诊断能力，可用于 Vue、React、原生 Web 与受支持的移动浏览器。
-
-## 安装
-
-```bash
-npm install @16x/webphone-sdk
-```
-
-包发布在 npmjs，npm 组织是 `16x`。任何人都可以直接安装，不需要 token。
-
-浏览器只应接收客户服务端签发的短期 WebPhone Access Token。不要把 `appSecret`、固定 SIP 密码或 TURN 密码写入前端代码、示例、日志或构建产物。客户从安装到首通的完整路径见 `docs/quick-start.md`，PC/H5 选择见 `docs/guides/mobile-h5.md`。
-
-## Core 快速开始
-
-```ts
-import { CCBarClient } from '@16x/webphone-sdk';
-
-const client = new CCBarClient({
-  platform: 'web',
-  tokenProvider: async () => {
-    const response = await fetch('/api/webphone-token', {
-      method: 'POST',
-      credentials: 'include',
-    });
-    if (!response.ok) throw new Error('获取外呼凭证失败');
-    return response.json();
-  },
-});
-
-await client.initialize();
-await client.connect();
-
-const call = await client.dial({ destination: '13800138000' });
-await call.hangup();
-
-await client.disconnect();
-await client.dispose();
-```
-
-在 SPA 中应由应用级容器持有一个 `CCBarClient`。`connect()`、`disconnect()` 和 `dispose()` 支持幂等调用；组件卸载或应用退出时必须调用 `dispose()` 释放 Timer、Listener、WebSocket、PeerConnection、Track 和 Audio 资源。
-
-根入口与 `/diagnostics` 可在 SSR/Node 导入阶段安全加载，不会访问 `window`、`document` 或 `navigator`。浏览器媒体能力只在初始化或后续操作时检测。
-
-## 主要 API
-
-- `CCBarClient.initialize/connect/disconnect/dispose`
-- `CCBarClient.dial/getCalls/getActiveCall/setActiveCall`
-- `CCBarClient.setAgentStatus`
-- `CCBarClient.media` 设备与音频控制
-- `CCBarClient.on/off` 类型化事件
-- `CCBarClient.getDiagnostics` 脱敏诊断报告
-- `CCBarCall.mute/unmute/hold/resume/sendDtmf/transfer/hangup`
-
-PC Web 支持完整 Core 通话能力。移动 H5 首期仅承诺受支持系统浏览器中的前台单路外呼；来电、保持、转接、后台和锁屏通话不在承诺范围内。
-
-## Legacy Adapter
-
-只有显式导入 Legacy 子路径才会在浏览器附加 `window.CCBarSDK`；根入口没有该副作用。Legacy 子路径同样可以安全地在 SSR 中导入。
-
-```ts
-import { CCBarSDK } from '@16x/webphone-sdk/legacy';
-
-const legacy = new CCBarSDK({
-  platform: 'web',
-  tokenProvider: async () => fetch('/api/webphone-token', {
-    method: 'POST',
-    credentials: 'include',
-  }).then(response => response.json()),
-});
-
-await legacy.login();
-const call = await legacy.call('13800138000');
-await legacy.hangup();
-await legacy.signOut();
-```
-
-旧方法映射如下：
-
-| Legacy | Core |
-|---|---|
-| `getToken()` / `getAccount()` / `login()` | `client.connect()` |
-| `call(number)` | `client.dial({ destination: number })` |
-| `insideCall(number)` | `client.dial({ destination: number, type: 'extension' })` |
-| `answer()` | 当前 `call.answer()` |
-| `hangup()` | 当前 `call.hangup()` |
-| `holdCall()` / `unholdCall()` | 当前 `call.hold()` / `call.resume()` |
-| `transSo(number)` | 当前 `call.transfer({ target: number, type: 'blind' })` |
-| `setId()` / `setRe()` | `client.setAgentStatus('available' / 'break')` |
-| `signOut()` | `client.disconnect()` 后 `client.dispose()` |
-
-`insideCall(number)` 会使用 `type: 'extension'` 标记 SIP 呼叫，浏览器不拼接客户前缀；后端按当前会话租户解析分机并路由到同租户坐席。普通 `dial()` 不传 type，继续按外呼处理。
-
-`setBu()` 不会伪造 `busy`。该方法抛出 `DeprecatedError`，因为忙碌状态应由通话状态或服务端状态策略驱动。所有 Legacy 方法仅在开发构建中各警告一次，生产构建不输出弃用日志。`signOut()` 是终态操作；如需保留实例以便重新连接，请直接使用 Core 的 `disconnect()`。
-
-## 开发与验收
-
-```bash
-npm run lint
-npm run typecheck
-npm test
-npm run build
-npm run pack:check
-```
-
-正式包通过 `exports` 提供根入口、`/ui`、`/legacy`、`/diagnostics` 和 `/styles.css`，不包含测试、示例、Source Map 或凭证文件。
-
-## License
-
-Copyright 16X. All rights reserved.
-
-Private customer distribution only. No redistribution or sublicensing without written permission.
+# CCBar WebPhone SDK Core
+
+`@16x/webphone-sdk` 是 CCBar WebPhone 的 TypeScript SDK。Core 提供无 UI 的连接、通话、媒体设备、重连和脱敏诊断能力，可用于 Vue、React、原生 Web 与受支持的移动浏览器。
+
+## 安装
+
+```bash
+npm install @16x/webphone-sdk
+```
+
+公开包地址：[https://www.npmjs.com/package/@16x/webphone-sdk](https://www.npmjs.com/package/@16x/webphone-sdk)。任何人都可以直接安装，不需要 token。
+
+浏览器只应接收客户服务端签发的短期 WebPhone Access Token。不要把 `appSecret`、固定 SIP 密码或 TURN 密码写入前端代码、示例、日志或构建产物。客户从安装到首通的完整路径见 `docs/quick-start.md`，PC/H5 选择见 `docs/guides/mobile-h5.md`。
+
+## Core 快速开始
+
+```ts
+import { CCBarClient } from '@16x/webphone-sdk';
+
+const client = new CCBarClient({
+  platform: 'web',
+  tokenProvider: async () => {
+    const response = await fetch('/api/webphone-token', {
+      method: 'POST',
+      credentials: 'include',
+    });
+    if (!response.ok) throw new Error('获取外呼凭证失败');
+    return response.json();
+  },
+});
+
+await client.initialize();
+await client.connect();
+
+const call = await client.dial({ destination: '13800138000' });
+await call.hangup();
+
+await client.disconnect();
+await client.dispose();
+```
+
+在 SPA 中应由应用级容器持有一个 `CCBarClient`。`connect()`、`disconnect()` 和 `dispose()` 支持幂等调用；组件卸载或应用退出时必须调用 `dispose()` 释放 Timer、Listener、WebSocket、PeerConnection、Track 和 Audio 资源。
+
+根入口与 `/diagnostics` 可在 SSR/Node 导入阶段安全加载，不会访问 `window`、`document` 或 `navigator`。浏览器媒体能力只在初始化或后续操作时检测。
+
+## 主要 API
+
+- `CCBarClient.initialize/connect/disconnect/dispose`
+- `CCBarClient.dial/getCalls/getActiveCall/setActiveCall`
+- `CCBarClient.setAgentStatus`
+- `CCBarClient.media` 设备与音频控制
+- `CCBarClient.on/off` 类型化事件
+- `CCBarClient.getDiagnostics` 脱敏诊断报告
+- `CCBarCall.mute/unmute/hold/resume/sendDtmf/transfer/hangup`
+
+PC Web 支持完整 Core 通话能力。移动 H5 首期仅承诺受支持系统浏览器中的前台单路外呼；来电、保持、转接、后台和锁屏通话不在承诺范围内。
+
+## Legacy Adapter
+
+只有显式导入 Legacy 子路径才会在浏览器附加 `window.CCBarSDK`；根入口没有该副作用。Legacy 子路径同样可以安全地在 SSR 中导入。
+
+```ts
+import { CCBarSDK } from '@16x/webphone-sdk/legacy';
+
+const legacy = new CCBarSDK({
+  platform: 'web',
+  tokenProvider: async () => fetch('/api/webphone-token', {
+    method: 'POST',
+    credentials: 'include',
+  }).then(response => response.json()),
+});
+
+await legacy.login();
+const call = await legacy.call('13800138000');
+await legacy.hangup();
+await legacy.signOut();
+```
+
+旧方法映射如下：
+
+| Legacy | Core |
+|---|---|
+| `getToken()` / `getAccount()` / `login()` | `client.connect()` |
+| `call(number)` | `client.dial({ destination: number })` |
+| `insideCall(number)` | `client.dial({ destination: number, type: 'extension' })` |
+| `answer()` | 当前 `call.answer()` |
+| `hangup()` | 当前 `call.hangup()` |
+| `holdCall()` / `unholdCall()` | 当前 `call.hold()` / `call.resume()` |
+| `transSo(number)` | 当前 `call.transfer({ target: number, type: 'blind' })` |
+| `setId()` / `setRe()` | `client.setAgentStatus('available' / 'break')` |
+| `signOut()` | `client.disconnect()` 后 `client.dispose()` |
+
+`insideCall(number)` 会使用 `type: 'extension'` 标记 SIP 呼叫，浏览器不拼接客户前缀；后端按当前会话租户解析分机并路由到同租户坐席。普通 `dial()` 不传 type，继续按外呼处理。
+
+`setBu()` 不会伪造 `busy`。该方法抛出 `DeprecatedError`，因为忙碌状态应由通话状态或服务端状态策略驱动。所有 Legacy 方法仅在开发构建中各警告一次，生产构建不输出弃用日志。`signOut()` 是终态操作；如需保留实例以便重新连接，请直接使用 Core 的 `disconnect()`。
+
+## 开发与验收
+
+```bash
+npm run lint
+npm run typecheck
+npm test
+npm run build
+npm run pack:check
+```
+
+正式包通过 `exports` 提供根入口、`/ui`、`/legacy`、`/diagnostics` 和 `/styles.css`，不包含测试、示例、Source Map 或凭证文件。
+
+## License
+
+Copyright 16X. All rights reserved.
+
+Private customer distribution only. No redistribution or sublicensing without written permission.