@16x/webphone-sdk 3.0.1

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# 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 次初始化、连接、拨号、结束和销毁生命周期资源回收测试。

package/LICENSE

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

package/README.md

@@ -0,0 +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.