@16x/webphone-sdk 3.1.11 → 3.1.13

package/README.md

@@ -1,219 +1,161 @@
-# 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。
-
-浏览器只应接收客户服务端下发的会话（已含短期 WSS ticket 与 SIP 凭证）。不要把 `appSecret`、AES 密钥、固定 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',
-  sessionProvider: {
-    // 你们自己的会话接口：返回一份 WebPhoneSession，签名与解密都留在服务端
-    createSession: async () => {
-      const response = await fetch('/get-session', { 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`
-
-构造参数里几个按需用的：`sessionProvider`（**必填**，4.0.0 起唯一会话来源，见下一节）、
-`sipKeepaliveSeconds`（3.1.1+，默认 25 秒重发 REGISTER 撑住 NAT/代理上的长连接，`0` 关闭）、
-`sharedWorker`（多标签页入口）、`baseUrl`、`maxConcurrentCalls`。
-
-拨号时 SDK 会在 `pcConfig` 里带上 `iceCandidatePoolSize: 2`（3.1.2+）：JsSIP 要等 ICE 收集完成才发
-INVITE，预收集候选才能做到「点完就出局」。
-
-PC Web 支持完整 Core 通话能力。移动 H5 首期仅承诺受支持系统浏览器中的前台单路外呼；来电、保持、转接、后台和锁屏通话不在承诺范围内。
-
-## 会话来源（sessionProvider）
-
-会话由接入方在自己的服务端拼好后交给 SDK：**4.0.0 起这是唯一的会话来源**（3.x 的 `tokenProvider`
-以及 SDK 自己请求平台会话接口的能力已移除，迁移方式见 `CHANGELOG.md` 的 4.0.0 条目）。
-
-```ts
-const client = new CCBarClient({
-  platform: 'web',
-  sessionProvider: {
-    // 必填：返回一份 WebPhoneSession（sip.uri / sip.registerTicket / transport.wssUrl / iceServers / capabilities…）
-    createSession: async () => {
-      const response = await fetch('/get-session', { method: 'POST', credentials: 'include' });
-      if (!response.ok) throw new Error('获取坐席账号失败');
-      return response.json();
-    },
-    // 可选：缺省时 SDK 用 createSession 重建会话（会话到期前会调用一次）
-    // refreshSession: async (sessionId) => { ... },
-    // 可选：缺省时 setAgentStatus 抛 CAPABILITY_NOT_SUPPORTED，不静默失败
-    // setAgentStatus: async ({ status, reason }) => { ... },
-  },
-});
-
-await client.connect({ extension: '8001' });
-```
-
-SDK 从会话里读的字段：
-
-| 字段 | 用途 |
-|---|---|
-| `sip.uri` / `sip.registrar` | REGISTER 的账号与 registrar |
-| `sip.registerTicket` | SIP 密码（旧平台就是服务端解出来的那个） |
-| `sip.registerExpires` | REGISTER 有效期（秒），没给或非正数按 300 |
-| `transport.wssUrl` | 软电话地址；只剥离 `ticket` 参数，`?token=` 原样保留 |
-| `transport.ticket` | 走 `xcall-ticket.<ticket>` 子协议；为空则只声明 `sip` |
-| `iceServers` / `capabilities` | ICE 配置 / 能力开关（outbound、inbound、mute、dtmf、hold、blind_transfer） |
-
-**密钥与密码都留在服务端**：签名的 appSecret、坐席密码的解密密钥都不要下发浏览器；
-会话（含 SIP 密码）在你们自己的服务端拼好，页面只拿结果。
-
-## Legacy Adapter
-
-只有显式导入 Legacy 子路径才会在浏览器附加 `window.CCBarSDK`；根入口没有该副作用。Legacy 子路径同样可以安全地在 SSR 中导入。
-
-```ts
-import { CCBarSDK } from '@16x/webphone-sdk/legacy';
-
-const legacy = new CCBarSDK({
-  platform: 'web',
-  sessionProvider: {
-    createSession: async () => fetch('/get-session', {
-      method: 'POST',
-      credentials: 'include',
-    }).then(response => response.json()),
-  },
-});
-
-await legacy.login();
-const call = await legacy.call('13800138000');
-await legacy.hangup();
-await legacy.signOut();
-```
-
-### `createLegacySessionProvider`：老平台的会话来源
-
-老平台（`token/fs` + `seat/account/get` 这一套）可以把「取 token → 取坐席账号 → 解 SIP 密码 → 组装会话」
-整段交给 SDK，页面只提供换票口子：
-
-```ts
-import { createLegacySessionProvider } from '@16x/webphone-sdk/legacy';
-
-const client = new CCBarClient({
-  sessionProvider: createLegacySessionProvider({
-    host: 'https://vxapi.yundianlab.com',
-    // 软电话 WSS 地址（必填）：wss:// 或 ws:// 开头的完整地址，SDK 只往上挂 ?token=
-    sipWsUrl: 'wss://your-sip-host/api/fs/sip-ws',
-    // 取 token 二选一：给函数，或给地址让 SDK 去 POST（都是你们自己的接口）
-    getToken: () => fetch('/get-token', { method: 'POST' }).then(response => response.json()),
-    // tokenUrl: '/get-token',
-  }),
-});
-```
-
-- **软电话地址由你们传**：`sipWsUrl` 必填（完整地址），SDK **不再**按坐席账号的 `domain` / `wssPort`
-  拼装，也不接受相对路径；缺了或不是 `wss://` / `ws://` 地址时，建会话会抛 `CONFIG_INVALID`。
-  SDK 只把 fs token 挂成 `?token=`（`attachTokenToWss: false` 可关掉）。
-- **SDK 不碰 API SECRET**：`/openapi/v1/token/fs` 的加签始终在你们服务端，SDK 只拿结果；
-- **AES key 会随包下发**：老平台那把 16 字节 key/iv 是固定值（旧版 `ccbar.js` 里同样是硬编码），
-  可用 `aesKey` / `aesIv` 覆盖；介意的话就走服务端拼会话（见下一节）；
-- 坐席状态：`client.setAgentStatus(...)` 打到 `{host}/openapi/token/v1/seats/set-status`，
-  其中 `extension` 传的是**坐席账号**（`username`，可能带企业前缀）；
-- **浏览器直连网关**：需要网关放行 CORS 与调用方 IP（`seat/account/get` 有 IP 白名单），部署前先确认；
-- 取票与 SIP 密码都按有效期提前换（`refreshBufferSeconds`，默认 180 秒）。
-
-### `decryptSipPassword`：解 `seat/account/get` 返回的 `password`
-
-`password`（或 `registerPassword`）是 **AES-128-CBC/Pkcs7 的密文、Base64 编码**，
-SDK 把解密单独导出，服务端（Node 18+）与页面都能用：
-
-```ts
-import { decryptSipPassword } from '@16x/webphone-sdk/legacy';
-
-const password = await decryptSipPassword(data.password);              // 明文 SIP 密码
-// 环境用的是别的 key/iv 时：await decryptSipPassword(data.password, { key, iv })
-```
-
-- key/iv 各 16 字节，**默认是平台内置固定值**（与旧版 `ccbar.js` 一致），可用 `key`/`iv` 覆盖；
-- 失败抛 `CCBarError`，可读原因在 `error.cause`（密文为空 / 不是合法 Base64 / 解密失败）；
-- 依赖 WebCrypto：浏览器需安全上下文（https / localhost），Node 需 18+；
-- `createLegacySessionProvider` 内部用的就是它。
-
-旧方法映射如下：
-
-| 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 呼叫（INVITE 上带 `X-XCall-Destination-Type: extension`），
-浏览器不拼接客户前缀；后端按当前会话租户解析分机并路由到同租户坐席。普通 `dial()` 不传 type，继续按外呼处理。
-
-注意：如果你们的网关只认「企业前缀 + 分机号」，`type: 'extension'` 这个头它不解析，
-就需要自己拼好前缀再拨（`dial({ destination: \`${prefix}${number}\` })`），
-具体见客户示例仓库的 `prefixExtension()`。
-
-`setBu()` 不会伪造 `busy`。该方法抛出 `DeprecatedError`，因为忙碌状态应由通话状态或服务端状态策略驱动。所有 Legacy 方法仅在开发构建中各警告一次，生产构建不输出弃用日志。`signOut()` 是终态操作；如需保留实例以便重新连接，请直接使用 Core 的 `disconnect()`。
-
-## 版本与更新记录
-
-当前版本见 `package.json`，每个版本改了什么见 [CHANGELOG.md](./CHANGELOG.md)。
-最近几个版本：4.0.0 移除 `tokenProvider`（只保留 `sessionProvider`，破坏性变更）；3.1.0 新增 `sessionProvider`；3.1.1 新增 SIP 保活；3.1.2 拨号带 ICE 候选池。
-
-## 开发与验收
-
-```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
+
+`@16x/webphone-sdk` 是浏览器软电话 SDK，提供 SIP 注册、呼入呼出、通话控制、坐席状态、媒体设备和生命周期管理。
+
+```bash
+npm install @16x/webphone-sdk@3.1.12
+```
+
+包信息：[https://www.npmjs.com/package/@16x/webphone-sdk](https://www.npmjs.com/package/@16x/webphone-sdk)。
+
+## 接入流程
+
+本接入方式由客户服务端负责取得平台 token、查询坐席账号并组装完整的 `WebPhoneSession`。浏览器只请求客户自己的会话接口；`APP Key`、`security` 和 SIP 密码处理都留在服务端。
+
+1. 向商务经理或对接人获取 HTTP `host`、SIP `sipWsUrl`、`APP Key`、`security` 和分机号码。
+2. 客户服务端使用 `APP Key`、`security` 和分机号取得 token，再查询坐席账号，按 SDK 会话契约组装 `WebPhoneSession`。
+3. 浏览器通过 `sessionProvider.createSession()` 请求客户服务端的会话接口，然后调用 `client.connect()`。
+4. 登录页面或进入拨打页面时调用 `connect()`；退出登录或离开拨打页面时调用 `disconnect()`。销毁应用级客户端时再调用 `dispose()`。
+
+服务端会话接口示意：
+
+```http
+POST /get-session
+Content-Type: application/json
+```
+
+接口返回完整的 `WebPhoneSession`，至少包括：
+
+| 字段 | 用途 |
+|---|---|
+| `sessionId`、`expiresAt` | 会话标识与到期时间 |
+| `agent` | 坐席 ID、分机号和当前坐席状态 |
+| `sip.uri`、`sip.registrar`、`sip.registerTicket` | SIP 注册账号、服务器和注册凭证 |
+| `sip.registerExpires` | SIP 注册有效期，秒 |
+| `transport.wssUrl`、`transport.ticket` | SIP WebSocket 地址与连接凭证 |
+| `iceServers` | ICE/STUN/TURN 配置 |
+| `policy`、`capabilities` | 呼入策略和当前会话支持的能力 |
+
+## 最简浏览器接入
+
+```ts
+import { CCBarClient } from '@16x/webphone-sdk';
+
+const client = new CCBarClient({
+  platform: 'web',
+  sessionProvider: {
+    createSession: async () => {
+      const response = await fetch('/get-session', {
+        method: 'POST',
+        credentials: 'include',
+      });
+      if (!response.ok) throw new Error(`获取软电话会话失败：HTTP ${response.status}`);
+      return response.json();
+    },
+  },
+});
+
+await client.initialize();
+await client.connect();
+
+const call = await client.dial({ destination: '9196' });
+await call.hangup();
+
+await client.disconnect();
+await client.dispose();
+```
+
+同一个 `CCBarClient` 应由应用级容器持有。重复调用进行中的 `connect()` 会复用同一个连接操作；已连接时再次调用不会重新创建 SIP 资源。
+
+## 状态、事件与通话控制
+
+通话状态通过 `call.state` 读取，也可监听 `call.stateChanged`：
+
+| 状态 | 含义 |
+|---|---|
+| `new` | 通话对象已创建 |
+| `dialing` | 已发起呼叫，等待对端响应 |
+| `ringing` | 对端正在振铃 |
+| `connecting` | 对端已接听，媒体连接建立中 |
+| `active` | 通话已接通 |
+| `held` | 通话保持中 |
+| `ended` | 通话正常结束 |
+| `failed` | 通话建立或进行失败 |
+
+```ts
+client.on('call.stateChanged', ({ callId, from, to }) => {
+  console.log(callId, from, to);
+});
+
+client.on('call.failed', ({ callId, error }) => {
+  console.error(callId, error.code, error.message);
+});
+
+await call.hold();
+await call.resume();
+await call.mute();
+await call.unmute();
+await call.hangup();
+```
+
+拨号附加信息可以通过 `userdata` 传递，SDK 会随呼叫发送，后续话单是否展示或支持查询取决于平台侧的话单接口：
+
+```ts
+await client.dial({
+  destination: '9196',
+  userdata: { orderId: 'order-20261006-001', source: 'web' },
+});
+```
+
+坐席状态使用 `available`、`break`、`offline`：
+
+```ts
+await client.setAgentStatus('available');
+await client.setAgentStatus('break');
+await client.setAgentStatus('offline');
+```
+
+登录、掉线和坐席状态也可通过 `client.on()` 监听：
+
+```ts
+client.on('connection.stateChanged', ({ state }) => console.log('SIP:', state));
+client.on('agent.statusChanged', ({ status }) => console.log('坐席:', status));
+client.on('error', ({ error }) => console.error(error.code, error.message));
+```
+
+## 错误处理
+
+SDK 错误提供稳定字符串 `code` 和可读 `message`；如果服务端返回平台数字错误码，可通过 `platformCode` 读取。业务逻辑应按 `code` 分支，向用户展示 `message`：
+
+```ts
+try {
+  await client.connect();
+} catch (error) {
+  if (error instanceof Error && 'code' in error) {
+    const sdkError = error as Error & { code: string; platformCode?: number };
+    console.error(sdkError.code, sdkError.message, sdkError.platformCode);
+  }
+}
+```
+
+常见错误包括 `CONFIG_INVALID`（会话或配置无效）、`AUTH_TOKEN_UNAVAILABLE`（服务端未取得登录凭证）、`REGISTRATION_FAILED`（SIP 注册失败）、`CALL_INVALID_DESTINATION`（被叫格式错误）、`CALL_NOT_CONNECTED`（当前没有可操作的通话）和 `CALL_OPERATION_NOT_ALLOWED`（当前通话状态不支持该操作）。
+
+## 资源释放
+
+退出坐席登录或离开拨打页面时调用 `disconnect()`。应用永久销毁客户端时调用 `dispose()`，释放定时器、事件监听、WebSocket、PeerConnection、音轨和音频资源。
+
+## 运行检查
+
+```bash
+npm run lint
+npm run typecheck
+npm test
+npm run build
+npm run pack:check
+```
+
+## License
+
+Copyright 16X. All rights reserved.
+
+Private customer distribution only. No redistribution or sublicensing without written permission.