@cg-devcenter/rtc-fpnn-webjs-sdk 1.0.0-cg.5 → 1.0.0-cg.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/docs/USAGE.md CHANGED
@@ -6,19 +6,23 @@
6
6
 
7
7
  | 入口 | 运行环境 | 能力范围 |
8
8
  | --- | --- | --- |
9
- | `RTMClient` + `protocol: 'tlv-v1'` | 浏览器;Node.js 需注入 `webSocketFactory` | 本文 TLV v1 支持矩阵列出的 API。新接入推荐此入口。 |
9
+ | `createClient()` | 浏览器 | 默认 FPNN;支持 SharedWorker 时共享同 UID 多窗口连接,不支持时自动使用独立连接。 |
10
+ | `createClient({protocol: 'tlv-v1'})` | 浏览器 | 显式选择 TLV v1;支持 SharedWorker 时共享连接,不支持时自动使用独立 TLV 连接;可调用本文支持矩阵列出的 API。 |
11
+ | `createClient({sharing: false, protocol: 'tlv-v1'})` / `RTMClient` + `protocol: 'tlv-v1'` | 浏览器;Node.js 需注入 `webSocketFactory` | 独立 TLV v1 连接;本文 TLV v1 支持矩阵列出的 API。 |
10
12
  | `RTMClient` + `protocol: 'fpnn'` | 浏览器 | 旧版兼容入口;兼容 API 仍受 FPNN 服务端能力和部署配置限制。 |
11
- | `RTMSharedWorkerClient` | 支持 SharedWorker 的浏览器、同源页面 | TLV v1 / FPNN;多个同源页面共享一个 UID 的 RTC 会话,并由 SDK 路由实时 Push。 |
13
+ | `RTMSharedWorkerClient` | 支持 SharedWorker 的浏览器、同源页面 | 显式创建 Worker 客户端;默认 FPNN,指定 TLV v1 时使用 TLV。多个同源页面共享一个 UID 的 RTC 会话,Worker 全量转发 SDK 事件。 |
12
14
 
13
15
  本文给出 TLV v1 方法参数和常见返回约定,不重复 TLV wire 字段的完整 schema。TLV Gate Answer 字段、数据类型和状态码以[TLV v1 Client 契约](TLV_CONTRACT.md)为准;TypeScript 完整声明见 [`dist/rtm.d.ts`](../dist/rtm.d.ts)。`fpnn` 的具体兼容范围以旧服务端为准;旧接口参数说明见[用户](Users.md)、[群组](Groups.md)、[房间](Rooms.md)、[消息](Messages.md)、[聊天](Chat.md)、[数据](Data.md)、[系统](System.md)、[文件](Files.md)、[好友](Friends.md)、[增值服务](ValueAdded.md)和[事件处理](EventProcess.md)文档。
14
16
 
15
17
  需要从 FPNN 迁移到 TLV v1 时,先看 [协议迁移对照](PROTOCOL_MIGRATION.md):它列出了相同 `RTMClient` 业务 API 对应的旧 FPNN method 与 TLV URI,并标明支持边界和兼容差异。
16
18
 
19
+ 如果是从上游 [`highras/rtm-client-sdk-websocket`](https://github.com/highras/rtm-client-sdk-websocket) 迁移,请先看[RTM SDK 迁移指南](RTM_MIGRATION.md)。该指南固定对照 GitHub `master` 的指定 commit;npm 包、fork 或内部构建可能与该源码不同。飞书统计中的服务端调用不属于本浏览器 SDK。
20
+
17
21
  ### 交给测试人员或 AI 接入前
18
22
 
19
23
  请随文提供以下环境信息,避免接入者猜测项目配置或尝试从浏览器获取项目密钥:
20
24
 
21
- - SDK 版本:本指南中的 Promise API、SharedWorker API 和 Vite 入口从 `1.0.0-cg.3` 起提供;此前发布的 `1.0.0-cg.2` 不包含这些能力。若 `.3` 尚未发布,需同时提供 `.tgz` 包或源码工作区。
25
+ - SDK:测试项目可安装 npm `latest` 标签对应的版本:`npm install @cg-devcenter/rtc-fpnn-webjs-sdk@latest`。若验证的功能尚未进入 npm `latest`,请同时提供 yalc 链接、本地 tarball 或源码工作区。
22
26
  - RTC 环境:`pid`、协议(通常为 `tlv-v1`)、完整 WebSocket endpoint,以及应用页面的 origin。
23
27
  - 测试身份:发送 UID、接收 UID、账号权限和预期验证场景;不要在文档或任务描述中粘贴长期凭证。
24
28
  - credential 获取方式:由哪个业务服务端接口签发、请求需要的登录态/参数、响应 JSON 字段名和 credential 有效期。项目 `SecretKey` 只保留在受控服务端或本机签发工具中。
@@ -26,20 +30,29 @@
26
30
 
27
31
  缺少以上信息时,接入者仍可完成 API 集成,但不能独立验证真实 Gate 登录和消息收发。
28
32
 
33
+ ### 用于实际项目的实时信令
34
+
35
+ - 先确认协议、PID、Gate 地址与签发 credential 的服务端属于同一环境。线上 HTTPS 页面使用 WSS;共享 Worker 应部署在应用同源地址,并被站点 CSP 的 `worker-src` 允许。现代 ESM 项目使用包根入口;Vite 项目增加一次 `/vite-plugin` 插件配置。
36
+ - 全局信令接收器保持 `conversation: null`;设置会话过滤后,该页面只收到匹配的消息 Push。UI 不可见或失去焦点不会改变 SDK 路由,但浏览器挂起页面会延后 JS 执行,静默回收 Worker 的恢复边界见下文。
37
+ - SDK 传送实时消息和信令,不提供音视频采集、编解码或媒体连接。业务应定义消息类型、业务 ID、有效期与处理确认;Gate 接受发送不等于对方业务已处理。
38
+ - 请求中断时发送结果可能未知,SDK 不自动重放。业务根据业务 ID 做幂等处理,并自行决定重试与断线补偿;需要历史补偿时也要确认项目启用对应服务能力。
39
+ - 每个业务调用都处理 callback / Promise 错误,不能只依赖全局事件。TLV 发送错误的嵌套结构、超时、鉴权与支持矩阵见本文对应章节。
40
+
29
41
  ## 2. 快速开始:登录、收 Push、发消息、关闭
30
42
 
31
43
  ### 默认共享接入(当前源码)
32
44
 
33
- 新入口 `createClient(options)` 默认启用 SharedWorker,默认使用 TLV;显式 `protocol: 'fpnn'` 也可共享。**已发布的 `1.0.0-cg.3` 尚不包含此入口和 FPNN 共享扩展**,请使用本地构建/yalc 或后续版本。旧 `RTMClient`、`RTMSharedWorkerClient` 的构造参数和行为保留。
45
+ 新入口 `createClient(options)` 在浏览器支持 SharedWorker 时默认共享连接;浏览器没有 SharedWorker API 时自动创建独立的 `RTMClient`,业务 API、事件和 Promise 接口保持可用,但页面之间不共享连接或登录态。Worker 脚本加载失败、初始化失败或超时时会报告错误,不会被当作“不支持 SharedWorker”而静默降级。显式设置 `sharing: false` 可始终使用独立连接。省略 `protocol` 时默认使用 FPNN,以便从旧 `RTMClient` 构造方式迁移时保持协议一致;直接构造 `RTMSharedWorkerClient` 表示明确要求 Worker,浏览器不支持时会报错。只有显式设置 `protocol: 'tlv-v1'` 才选择 TLV v1。请使用 npm `latest` 标签对应的版本;若该标签尚未包含此入口或 FPNN 共享扩展,请使用本地构建/yalc。旧 `RTMClient` 的业务 API 保留;共享连接按 PID、协议、UID 和 Gate endpoint 区分环境;两个共享入口在协议及其他连接参数一致时可复用同一会话。
34
46
 
35
- Vite 项目从 `/vite` 导入,普通 HTML 把 SDK 与 Worker bundle 部署到同源目录;业务不需要填写 Worker 名称。下面可作为 Vite 页面脚本使用,替换项目配置和 credential 接口:
47
+ 现代 ESM 项目从包根导入。Worker URL 按构建工具解析:Vite 在 `vite.config.js` 注册一次 SDK 插件;Webpack 4 注册 SDK 的 `/webpack4` 插件;Webpack 5 使用包根 ESM 入口和标准资源解析。普通 HTML 将 SDK 脚本和 Worker 文件放在同源同目录。上述常规方式都不需要业务传 `workerUrl`;只有自定义 Worker 部署位置时才需要覆盖它。旧 `/vite` 入口继续兼容。包根入口和插件是当前仓库实现,尚未发布到 npm;正式安装前请确认使用的版本已包含它们。下面可作为 Vite 页面脚本使用,替换项目配置和 credential 接口:
36
48
 
37
49
  ```js
38
- import rtm from '@cg-devcenter/rtc-fpnn-webjs-sdk/vite';
50
+ import rtm from '@cg-devcenter/rtc-fpnn-webjs-sdk';
39
51
 
40
52
  const uid = '10001';
41
53
  const peerUid = '10002';
42
54
  const client = rtm.createClient({
55
+ protocol: 'tlv-v1',
43
56
  pid: 12345,
44
57
  tlvEndpoint: 'wss://<gate-host>/service/websocket',
45
58
  autoReconnect: true,
@@ -53,7 +66,8 @@ client.on('SharedWorkerError', (error) => console.error('Shared connection', err
53
66
 
54
67
  async function start() {
55
68
  // 按 UID 挂接共享会话,尚未登录时不会建立 Gate WebSocket。
56
- const session = await client.whenReady(uid);
69
+ await client.whenReady(uid);
70
+ const session = client.getSharedSession();
57
71
  let credential;
58
72
  if (session.status === 'idle') {
59
73
  const response = await fetch('/api/rtc/credential?uid=' + encodeURIComponent(uid), {
@@ -77,17 +91,19 @@ UID 使用正整数或十进制字符串;超过 JavaScript 安全整数范围
77
91
 
78
92
  | 配置 / API | 默认与边界 |
79
93
  | --- | --- |
80
- | `createClient(options)` | 使用扁平客户端配置,默认 `sharing: true`、`protocol: 'tlv-v1'`;浏览器没有 SharedWorker 时明确抛出 `RTM_SHARED_WORKER_UNSUPPORTED`。 |
81
- | `sharing: false` | 返回独立的 `RTMClient`,新入口仍默认 TLV;Node.js 或需要文件上传/函数型配置时显式选择,FPNN 仍仅支持浏览器。不会因共享初始化失败自动降级。 |
94
+ | `createClient(options)` | 使用扁平客户端配置,默认 `sharing: true`、`protocol: 'fpnn'`;浏览器没有 SharedWorker API 时自动回退为当前页面的独立连接。 |
95
+ | `sharing: false` | 返回独立的 `RTMClient`,省略协议时仍默认 FPNN。Node.js 需显式设置 `protocol: 'tlv-v1'` 并提供 `webSocketFactory`;FPNN 仍仅支持浏览器。 |
82
96
  | `uid` | 可选;提供时立即挂接共享 Worker,适合收件箱自动观察其他页面登录。省略时在 `login()` / `loginIfNeeded()` / `whenReady(uid)` 时挂接。一个实例固定一个 UID;切换账号需 detach 后创建新实例。 |
83
- | `workerName` / `workerUrl` | 可选高级覆盖项;默认名字由 PID、协议、UID 生成,不包含 endpoint。默认路径沿用脚本同目录规则,Vite `/vite` 自动打包。`workerNamespace` 仍可隔离应用。 |
84
- | `whenReady(uid?)` | 返回本页挂接后的共享会话快照。尚未绑定 UID 且未传 UID 时立即 reject `RTM_SHARED_UID_REQUIRED`,不会无限等待。 |
97
+ | `workerName` / `workerUrl` | 可选高级覆盖项;常规接入不需要配置 `workerUrl`。默认共享身份由 PID、协议、UID 和 Gate endpoint 生成,endpoint 不需要单独配置。普通 HTML 使用脚本同目录规则;Vite 使用 `/vite-plugin`;Webpack 4 使用 `/webpack4`;Webpack 5 使用标准 ESM 资源解析。只有自定义 Worker 部署位置时才传同源 `workerUrl`。`workerNamespace` 仍可隔离应用。 |
98
+ | `whenReady(uid?)` | 等待首次挂接并返回当时的快照;后续状态用 `getSharedSession()` 或 `SharedSessionState` 读取。尚未绑定 UID 且未传 UID 时立即 reject `RTM_SHARED_UID_REQUIRED`,不会无限等待。 |
85
99
  | `promises.login(uid, credential?, timeout?)` | 成功 resolve `{accepted: true, errorCode}`,RTC 拒绝或本地/Worker 错误 reject;并发同 UID 登录只发一次鉴权。`loginIfNeeded()` 保留 `{accepted, errorCode, reused, uid}` 的结果约定。 |
86
- | `login(uid, credential?, callback?, timeout?)` | RTC 拒绝与本地/Worker 失败均回调 `callback(false, numericCode)`;本地/Worker 失败的详细错误通过 `SharedWorkerError` 事件提供。仅 `accepted === true` 表示登录成功;`promises.login()` 会 reject 详细错误。 |
87
- | `destroy()` | 只 detach 当前页面;最后一页离开后按 `idleShutdownTimeout` 回收共享连接。`bye()` / `close()` 才结束所有共享页面的会话。 |
88
- | 会话路由与业务 API | 沿用 `setConversation()`、`processor`、重连和原协议的业务返回;共享模式不支持文件发送或函数型配置。绑定 UID 前的业务请求明确报 `RTM_SHARED_UID_REQUIRED`。 |
100
+ | `login(uid, credential?, callback?, timeout?)` | RTC 拒绝回调 `callback(false, numericCode)`;共享模式的本地/Worker 失败会通过 `SharedWorkerError` 提供详情。仅 `accepted === true` 表示登录成功;`promises.login()` 会 reject 详细错误。 |
101
+ | `destroy()` | 共享模式只 detach 当前页面;最后一页离开后按 `idleShutdownTimeout` 回收共享连接。独立模式关闭本页的 RTMClient。`bye()` / `close()` 结束当前连接。 |
102
+ | 会话路由与业务 API | 沿用 `setConversation()`、`processor`、重连和原协议的业务返回;业务能力由底层 `RTMClient` 决定,FPNN 文件发送可用;函数型配置不能跨线程克隆。绑定 UID 前的业务请求明确报 `RTM_SHARED_UID_REQUIRED`。 |
89
103
 
90
- 共享还要求同一浏览器配置文件、origin 和 Worker URL。**同 PID、协议、UID 的页面必须使用相同服务端地址和 `clientOptions`**;地址、鉴权配置、重连策略或其他参数不同会初始化失败,不会覆盖已有连接。不同 PID、协议或 UID 自动分开。新入口的默认名称与旧 `RTMSharedWorkerClient` 的 endpoint 参与命名规则不同:同 UID 的各页应统一使用新入口,或显式传相同 Worker 名称和配置,不要在部分页面切换后假定已经共享。
104
+ 共享还要求同一浏览器配置文件、origin 和 Worker URL。同一浏览器配置文件、origin、Worker URL、PID、协议、UID 和 Gate endpoint 的页面会复用一条连接;Gate 地址不同会自动隔离。**同一共享身份下的 `clientOptions` 必须一致**;认证、重连或其他参数不同会初始化失败,不会覆盖已有连接。`createClient()` 和 `RTMSharedWorkerClient` 自动使用相同规则,同一应用混用入口也能加入同一会话。显式传入 `workerName` 或 `workerNamespace` 时,共享页面仍须保持一致。
105
+
106
+ Gate endpoint 已自动区分测试、预发和生产环境,通常不需要设置 `workerNamespace`。只有同一 endpoint 下确实需要两组独立登录态时,才为各组设置不同 namespace。
91
107
 
92
108
  ### 原有单连接接入
93
109
 
@@ -170,14 +186,49 @@ UID 使用正整数或十进制字符串;超过 JavaScript 安全整数范围
170
186
  const rtm = require('@cg-devcenter/rtc-fpnn-webjs-sdk');
171
187
  ```
172
188
 
173
- Vite 项目可从专用 ESM 入口导入;该入口会把 SharedWorker 脚本作为构建资源并自动传给 `RTMSharedWorkerClient`,不需要手动写 Worker 文件路径:
189
+ 现代 ESM 项目可从包根入口导入。Vite 项目在 `vite.config.js` 注册一次 SDK 插件,处理开发依赖预构建;SDK 的 ESM Worker 资源由 Vite 输出并自动传给 `RTMSharedWorkerClient`。应用代码不需要填写 Worker 路径:
174
190
 
175
191
  ```js
176
- import rtm from '@cg-devcenter/rtc-fpnn-webjs-sdk/vite';
192
+ import rtm from '@cg-devcenter/rtc-fpnn-webjs-sdk';
177
193
  ```
178
194
 
195
+ ```js
196
+ // vite.config.js
197
+ import { rtmSdkVitePlugin } from '@cg-devcenter/rtc-fpnn-webjs-sdk/vite-plugin';
198
+
199
+ export default {
200
+ plugins: [rtmSdkVitePlugin()],
201
+ };
202
+ ```
203
+
204
+ Vue 2 / Webpack 4 项目在 Webpack 配置中注册 SDK 插件一次。它会随构建输出 Worker 资源并处理 `publicPath`,业务代码仍从包根导入 SDK,也不需要传 `workerUrl`:
205
+
206
+ ```js
207
+ // webpack.config.js
208
+ const RTMSDKWebpack4Plugin = require('@cg-devcenter/rtc-fpnn-webjs-sdk/webpack4');
209
+
210
+ module.exports = {
211
+ plugins: [new RTMSDKWebpack4Plugin()],
212
+ };
213
+ ```
214
+
215
+ Webpack 5 项目从包根 ESM 入口导入即可使用标准资源解析,不需要 SDK 插件。无论使用 Vue、React 还是普通 JS,页面里的客户端创建方式相同。
216
+
179
217
  浏览器可加载 `dist/rtm.min.js` 并从 `window.rtm` 取 SDK。Node.js 仅支持 TLV v1;需要在 `RTMClient` 选项中传入 `webSocketFactory(url)`,返回对象须支持 `send(data)`、`close(code?, reason?)` 及 `onopen`、`onmessage`、`onerror`、`onclose`。SDK 不附带 Node WebSocket 实现。`fpnn` 和 SharedWorker 仅面向浏览器。
180
218
 
219
+ 若用 unpkg 或 jsDelivr 加载 `rtm.min.js`,不要让 SDK 自动推导共享 Worker 地址:推导出的 Worker 会落在 CDN 域名,与业务页面不同源。可把同版本的 `rtm.shared-worker.js` 部署到应用自己的同源静态目录,并显式传入 `workerUrl`;如果不需要多页面共享,可设置 `sharing: false`。例如:
220
+
221
+ ```js
222
+ const client = window.rtm.createClient({
223
+ pid,
224
+ endpoint,
225
+ uid,
226
+ workerUrl: '/sdk/rtm.shared-worker.js',
227
+ });
228
+ ```
229
+
230
+ SharedWorker 仍要求 Worker 与页面同源;仅配置跨域 CORS 不会满足此限制。常规 npm bundler 接入和应用同源 HTML 部署不受此 CDN 注意事项影响。
231
+
181
232
  ## 3. 生命周期与错误处理
182
233
 
183
234
  ### 初始化和生命周期 API
@@ -203,6 +254,8 @@ import rtm from '@cg-devcenter/rtc-fpnn-webjs-sdk/vite';
203
254
  | --- | --- | --- | --- |
204
255
  | `pid` | `number` | 必填 | RTC 项目 ID。 |
205
256
  | `protocol` | `'tlv-v1' \| 'fpnn'` | 默认 `'fpnn'` | 新接入请显式设为 `'tlv-v1'`。 |
257
+ | `endpoint` | `string` | FPNN 必填 | FPNN Gate 主机及可选端口(`host[:port]`),使用 `ws://`。 |
258
+ | `ssl_endpoint` | `string` | FPNN 可选 | FPNN Gate 主机及可选端口(`host[:port]`),使用 `wss://`;提供时优先于 `endpoint`。 |
206
259
  | `tlvEndpoint` | `string` | TLV 必填 | Gate 提供的完整 `ws://` 或 `wss://` URL,含部署要求的路径,通常以 `/service/websocket` 结尾。 |
207
260
  | `autoReconnect` | `boolean` | `true` | 自动重连开关。终止性鉴权错误不会无限重试。 |
208
261
  | `connectionTimeout` | `number` | `30000` | 建立 WebSocket 连接的超时。 |
@@ -232,7 +285,7 @@ import rtm from '@cg-devcenter/rtc-fpnn-webjs-sdk/vite';
232
285
 
233
286
  `ErrorRecorder(error)` 用于连接、协议、自动重连和登录错误,不会代替普通业务请求的 callback 或 Promise rejection。业务失败应检查各自调用结果。请求超时与连接中断会结束挂起调用;连接中断时写入结果可能未知,SDK 不自动重放,业务应按幂等规则决定是否重试。
234
287
 
235
- `bye()` 与普通业务调用不同,是异步的协议关闭握手。优先使用有超时的 Promise,并始终在 `finally` 中 `destroy()`;不必等待 `SessionClosed` 才能清理:
288
+ `bye()` 与普通业务调用不同,是异步的协议关闭握手。结束整个会话时,使用有超时的 Promise,并在 `finally` 中 `close()` 后 `destroy()`;不必等待 `SessionClosed` 才能清理:
236
289
 
237
290
  ```js
238
291
  try {
@@ -240,29 +293,31 @@ try {
240
293
  } catch (error) {
241
294
  console.warn('Gate did not confirm close', error);
242
295
  } finally {
243
- client.destroy();
296
+ try { client.close(); } finally { client.destroy(); }
244
297
  }
245
298
  ```
246
299
 
247
- Promise 成功表示 Gate 已应答关闭请求。若要直接断开,可调用 `close()` / `destroy()`;它们可能中止尚未完成的 `bye()`。
300
+ Promise 成功表示 Gate 已应答关闭请求。直接结束整个会话可调用 `close()`,这可能中止尚未完成的 `bye()`。共享模式下只关闭当前页面或卸载组件时仅调用 `destroy()`,不要调用 `bye()` / `close()`,其他页面会继续使用共享会话。独立 `RTMClient.destroy()` 则会关闭其自身连接。
248
301
 
249
302
  常用事件:`ErrorRecorder(error)`、`ReloginCompleted(successful, retryAgain, errorCode, retriedCount)`、`SessionClosed(errorCode)`。TLV 可靠 Push 由 SDK 自动 ACK,并按 `message_ref` 去重;这不等于离线补拉或业务存储。
250
303
 
251
304
  ## 4. 同 UID 多窗口:SharedWorker
252
305
 
253
- `RTMSharedWorkerClient` 是 SDK 提供的同源多页面连接复用能力。每个页面创建一个客户端端口,SDK 在 SharedWorker 内维护一个 `RTMClient` 和一条 WebSocket。普通浏览器脚本加载时,SDK 默认从主 SDK 脚本地址推导同目录下的 `rtm.shared-worker.js`;部署在其他位置时,需显式传入同源 `workerUrl`。Vite 项目推荐从 `@cg-devcenter/rtc-fpnn-webjs-sdk/vite` 导入,SDK 会自动把 Worker 作为构建资源并配置地址。其他构建工具可在其资源管线支持时导入 `@cg-devcenter/rtc-fpnn-webjs-sdk/shared-worker?url`,再将解析出的 URL 传给 `workerUrl`。共享身份需要相同浏览器配置文件、origin、解析后的 Worker URL、`workerName` 和结构一致的 `clientOptions`。一个 Worker 只登录一个 UID、使用一种协议;传入 `uid` 后 SDK 会根据协议、项目、UID、endpoint 和可选 `workerNamespace` 生成稳定名称。TLV 自动名称沿用此前规则,FPNN 名称单独隔离。
306
+ SharedWorker 是 SDK 实例和登录状态的共享底座:负责端口、同 UID 登录合并、调用转发和生命周期。协议实现、业务 API、文件上传、重连、ACK 和去重均由底层 `RTMClient` 执行,公开业务方法从 SDK 自动代理。Worker 不检查消息类型、不筛选业务事件,也不增加业务能力限制。`conversation` / `setConversation()` 是页面端的可选筛选工具。
307
+
308
+ `RTMSharedWorkerClient` 是 SDK 提供的同源多页面连接复用能力。每个页面创建一个客户端端口,SDK 在 SharedWorker 内维护一个 `RTMClient` 和一条 WebSocket。常规接入无需手写 `workerUrl`,Worker URL 按构建方式自动解析:普通 HTML 从主 SDK 脚本地址推导同目录下的 `rtm.shared-worker.js`;Vite 项目在配置中注册 `/vite-plugin`;Webpack 4 项目注册 `/webpack4` 插件;Webpack 5 项目从包根 ESM 入口使用标准资源解析。旧 `/vite` 入口继续兼容。只有自定义 Worker 部署位置时才显式传入同源 `workerUrl`。Vue、React 和普通 JS 使用相同的 SDK API,具体 Worker 配置由构建工具决定。共享身份需要相同浏览器配置文件、origin、解析后的 Worker URL、`workerName` 和结构一致的 `clientOptions`。一个 Worker 只登录一个 UID、使用一种协议;传入 `uid` 后,SDK 根据协议、PID、UID 和实际 Gate endpoint 自动生成稳定身份,因此不同 Gate 环境自动使用不同连接;同一名称下其他 `clientOptions` 不一致会明确报错。`createSharedWorkerName()` 可显式传 `endpoint` 构造隔离名称。SDK 升级后请关闭同一共享身份的所有旧页面,等待 `idleShutdownTimeout`(默认 5 秒)后重新打开,确保旧 Worker 结束并加载新脚本;新旧页面/Worker 版本混用不受支持。
254
309
 
255
310
  | API / 选项 | 参数与结果 |
256
311
  | --- | --- |
257
- | `new RTMSharedWorkerClient(options)` | `clientOptions` 必填;`protocol` 省略时仍为 TLV v1,提供 `pid` 和完整 `tlvEndpoint`。选择 FPNN 时显式设置 `protocol: 'fpnn'`,并提供 `endpoint` 或 `ssl_endpoint`(`host[:port]`,不含 URL scheme 和路径)。`workerUrl` 可选,同源 Worker 脚本 URL;普通浏览器脚本省略时 SDK 推导加载 SDK 的脚本同目录下的 `rtm.shared-worker.js`,Vite 项目应使用 `/vite` 入口自动打包 Worker。提供 `uid` 且省略 `workerName` 时,SDK 根据协议、`clientOptions.pid`、`uid`、实际连接地址和 `workerNamespace` 生成稳定名称;也可调用 `createSharedWorkerName({protocol, pid, uid, endpoint, namespace})` 自行取得名称。若 `uid` 和 `workerName` 都省略,会使用通用默认名称;多账号应用应传其中一个,避免不同 UID 页面加入同一个 Worker。`readyTimeout` 默认 10000 毫秒;`idleShutdownTimeout` 默认 5000 毫秒,最后一个页面 detach 后等待这段时间再关闭共享连接,设为 `0` 表示立即关闭;同一 Worker 的所有页面必须使用相同值。`conversation` 可选,默认 `null` 接收全部会话 Push。 |
258
- | `whenReady()` | 等 Worker 初始化并返回 `{status, uid}` 快照。初始化失败时 Promise reject,SDK 会自动 detach 并关闭当前页面的端口。 |
312
+ | `new RTMSharedWorkerClient(options)` | `clientOptions` 必填;`clientOptions.protocol` 省略时默认 FPNN,提供 `pid` 及 `endpoint` 或 `ssl_endpoint`(`host[:port]`,不含 URL scheme 和路径)。选择 TLV v1 时显式设置 `protocol: 'tlv-v1'`,并提供完整 `tlvEndpoint`。`workerUrl` 可选,同源 Worker 脚本 URL;普通浏览器脚本省略时 SDK 推导加载 SDK 的脚本同目录下的 `rtm.shared-worker.js`,现代 ESM 入口自动解析包内 Worker 资源。提供 `uid` 且省略 `workerName` 时,SDK 根据协议、`clientOptions.pid`、`uid`、实际 Gate endpoint 和 `workerNamespace` 生成稳定名称;若需要自行构造名称,可调用 `createSharedWorkerName({protocol, pid, uid, endpoint, namespace})`。若 `uid` 和 `workerName` 都省略,会使用通用默认名称;多账号应用应传其中一个,避免不同 UID 页面加入同一个 Worker。`readyTimeout` 默认 10000 毫秒;`idleShutdownTimeout` 默认 5000 毫秒,最后一个页面 detach 后等待这段时间再关闭共享连接,设为 `0` 表示立即关闭;同一 Worker 的所有页面必须使用相同值。`conversation` 可选,默认 `null` 接收全部会话 Push。 |
313
+ | `whenReady()` | 等 Worker 首次初始化并返回 `{status, uid}` 初始快照;再次调用不会刷新快照,当前状态用 `getSharedSession()`。初始化失败时 Promise reject,SDK 会自动 detach 并关闭当前页面的端口。 |
259
314
  | `getSharedSession()` | 同步返回本页面最近观察到的 `{status, uid}`。 |
260
315
  | `loginIfNeeded(uid, credential?, timeout?)` | 同 UID 会话已登录则复用;登录中则加入该登录;会话空闲时须提供服务端签发的 credential。resolve `{accepted, errorCode, reused, uid}`。 |
261
- | `setConversation(conversation, callback?)` | 修改当前页面 Push 路由;传 `null` 接收全部会话。出错时通过可选 callback 返回。 |
316
+ | `setConversation(conversation, callback?)` | 修改当前页面监听器的本地 Push 筛选;Worker 始终全量分发事件,传 `null` 接收全部会话。出错时通过可选 callback 返回。 |
262
317
  | `destroy()` | detach 当前页面端口;Worker 仍有其他页面时不关闭 RTC 连接。它会完成端口与监听器清理后再传播待处理业务回调抛出的异常。 |
263
- | `shared.promises.*` / `shared.*` | 可调用所选协议的 `RTMClient` 业务 API,参数、callback、返回对象和 Push 事件均沿用该协议;两种协议都不支持 `sendFile` / `sendGroupFile` / `sendRoomFile`。`bye()` / `close()` 影响所有共享页面。 |
318
+ | `shared.promises.*` / `shared.*` | 可调用所选协议的 `RTMClient` 业务 API,参数、callback、返回对象和 Push 事件均沿用该协议;业务方法自动代理,能力与协议错误由底层 SDK 决定;FPNN 支持 `sendFile` / `sendGroupFile` / `sendRoomFile`,TLV 由协议契约拒绝。`bye()` / `close()` 影响所有共享页面。 |
264
319
 
265
- 普通浏览器脚本部署时,把 `dist/rtm.min.js` 与 `dist/rtm.shared-worker.js` 放在同源静态目录的同一目录,SDK 会自动定位 Worker 文件。Vite 项目从包的 `/vite` 入口导入;SDK 会将 Worker 作为构建资源输出并自动配置地址,无需手动设置 `workerUrl`。其他构建工具需保证 Worker 最终同源可访问,并在自动推导不适用时显式传入 `workerUrl`。以下示例展示页面接入、首次登录、后续页面复用、Push 监听和当前页 detach。与快速开始相同,替换项目参数和 credential 接口:
320
+ 普通浏览器脚本部署时,把 `dist/rtm.min.js` 与 `dist/rtm.shared-worker.js` 放在同源静态目录的同一目录,SDK 会自动定位 Worker 文件。现代 ESM 项目从包根导入;Vite 使用 `/vite-plugin`,Webpack 4 使用 `/webpack4` 插件,Webpack 5 使用标准 ESM 资源解析。以上常规方式均无需手动设置 `workerUrl`;自定义 Worker 部署位置时才传同源覆盖地址。以下示例展示页面接入、首次登录、后续页面复用、Push 监听和当前页 detach。与快速开始相同,替换项目参数和 credential 接口:
266
321
 
267
322
  ```js
268
323
  const rtm = window.rtm;
@@ -277,54 +332,68 @@ async function getCredential() {
277
332
  return result.credential;
278
333
  }
279
334
 
280
- const shared = new rtm.RTMSharedWorkerClient({
281
- uid, // SDK 用 PID、UID 和 endpoint 生成稳定的 Worker 名称;仅用于命名,不会自动登录。
282
- clientOptions: {
283
- protocol: 'tlv-v1',
284
- pid: 12345,
285
- tlvEndpoint: 'wss://<gate-host>/service/websocket',
286
- autoReconnect: true,
287
- },
288
- conversation: null, // 收件箱接收所有会话;聊天页可只订阅一个会话。
289
- });
290
-
291
335
  function renderPush(event) { console.log('RTC Push', event); }
292
336
  function renderSession(session) { console.log('Shared RTC session', session); }
293
337
 
294
- [
295
- rtm.RTMConfig.TLV_SERVER_PUSH.recvMessage,
296
- rtm.RTMConfig.TLV_SERVER_PUSH.recvGroupMessage,
297
- rtm.RTMConfig.TLV_SERVER_PUSH.recvRoomMessage,
298
- rtm.RTMConfig.TLV_SERVER_PUSH.recvBroadcastMessage,
299
- ].forEach((name) => shared.processor.on(name, renderPush));
300
- shared.on('SharedSessionState', renderSession);
338
+ let shared = null;
339
+ function createSharedClient() {
340
+ const client = new rtm.RTMSharedWorkerClient({
341
+ uid, // SDK 自动按 PID、协议、UID 和 Gate endpoint 复用同环境会话;此 UID 仅用于挂接,不会自动登录。
342
+ clientOptions: {
343
+ protocol: 'tlv-v1',
344
+ pid: 12345,
345
+ tlvEndpoint: 'wss://<gate-host>/service/websocket',
346
+ autoReconnect: true,
347
+ },
348
+ conversation: null, // 收件箱接收所有会话;聊天页可只订阅一个会话。
349
+ });
350
+ [
351
+ rtm.RTMConfig.TLV_SERVER_PUSH.recvMessage,
352
+ rtm.RTMConfig.TLV_SERVER_PUSH.recvGroupMessage,
353
+ rtm.RTMConfig.TLV_SERVER_PUSH.recvRoomMessage,
354
+ rtm.RTMConfig.TLV_SERVER_PUSH.recvBroadcastMessage,
355
+ ].forEach((name) => client.processor.on(name, renderPush));
356
+ client.on('SharedSessionState', renderSession);
357
+ client.on('SharedWorkerError', (error) => {
358
+ console.error('SharedWorker client is no longer usable', error);
359
+ client.destroy();
360
+ if (shared === client) shared = null;
361
+ // 显示“重新连接”操作;用户触发后再次调用 connectInbox()。
362
+ });
363
+ return client;
364
+ }
301
365
 
302
366
  async function connectInbox() {
303
- const snapshot = await shared.whenReady();
367
+ if (!shared) shared = createSharedClient();
368
+ const client = shared;
369
+ await client.whenReady();
370
+ const snapshot = client.getSharedSession();
304
371
  // 建议先让一个页面登录,再打开其余页面。已登录/正在登录时无需再取 credential。
305
372
  const credential = snapshot.status === 'idle' ? await getCredential() : undefined;
306
- const result = await shared.loginIfNeeded(uid, credential);
373
+ const result = await client.loginIfNeeded(uid, credential);
307
374
  if (!result.accepted) throw Object.assign(new Error('RTM login rejected'), { code: result.errorCode });
308
375
  console.log('Shared session ready', result);
309
376
  }
310
377
 
311
378
  connectInbox().catch(console.error);
379
+ // 只有 SDK 报告 SharedWorkerError 后才重建 client;新 client 的登录快照可能是 idle,届时再取 credential。
312
380
  // 当前页关闭时 SDK 会自动 detach(BFCache 页面例外);应用也可主动调用:
313
- // shared.destroy();
381
+ // shared?.destroy();
314
382
  ```
315
383
 
316
384
  - 首个页面在 UID 尚未登录时传入服务端签发的 credential;其他同 UID 页面在已登录时不需要 credential。若它们赶在首次登录完成前打开,`loginIfNeeded()` 会加入同一次登录。
317
- - `whenReady()` 返回 `{status, uid}`;`loginIfNeeded(uid, credential?, timeout?)` 返回 `{accepted, errorCode, reused, uid}`。credential 不会广播到页面。
318
- - `conversation: {type: 'direct'|'group'|'room', id}` 只把匹配的私聊发送者、群或房间 Push 路由到该页面;`null` 接收全量会话 Push。运行中可调用 `setConversation(...)` 切换路由。
319
- - `event.broadcast` 和 `event.kicked` 发给全部页面;`event.room_removed` 发给订阅该房间的页面。页面自己的消息监听器由 SDK 端口分发。
385
+ - `whenReady()` 返回首次挂接快照 `{status, uid}`,当前状态用 `getSharedSession()`;`loginIfNeeded(uid, credential?, timeout?)` 返回 `{accepted, errorCode, reused, uid}`。credential 不会广播到页面。
386
+ - `conversation: {type: 'direct'|'group'|'room', id}` 在当前页面适配器中筛选私聊发送者、群或房间 Push;`null` 接收全部会话。Worker 始终向所有端口分发完整 SDK 事件,运行中可调用 `setConversation(...)` 修改本地筛选。
387
+ - 所有 SDK 事件由 Worker 原样分发到全部页面端口。页面适配器的可选 `conversation` 筛选会将 `event.room_removed` 限定为当前房间;`event.broadcast` 和 `event.kicked` 始终通知当前页面监听器。
320
388
  - `destroy()` 只 detach 当前页面;还有页面连接时共享连接继续运行。任一页面调用 `bye()` / `close()` 会结束所有页面共享的 RTC 会话。
321
- - 最后一个页面 detach 后,SDK 默认等待 5 秒再销毁 RTMClient 和连接;宽限期内新页面接入会取消回收。Worker 被浏览器提前回收时,业务仍需重新连接并按登录快照决定是否重新获取 credential。
322
- - SharedWorker 仅共享实时连接和 Push,不同步页面草稿、未读 UI 或消息列表,也不持久化登录态。它不跨 origin、浏览器配置文件或 InPrivate 窗口共享;不支持时 SDK 不静默降级为每页一条连接。
389
+ - 最后一个页面 detach 后,SDK 默认等待 5 秒再销毁 RTMClient 和连接;宽限期内新页面接入会取消回收。浏览器也可能在页面挂起或资源回收时结束 Worker,但 SDK 当前没有就绪后的心跳检测,浏览器静默回收不保证触发事件。
390
+ - 收到 `SharedWorkerError` 时,表示 SDK 检测到当前页面到 Worker 的错误(例如初始化失败、Worker `error` 或消息端口错误),可丢弃旧 client 并用相同连接配置创建新 client。此事件不是 Worker 被浏览器回收的通用通知;如果浏览器静默结束 Worker,页面可能无法及时获知。新 client 的登录快照若为 `idle`,重新登录时必须取得服务端为该 UID 签发的 credential。SDK 不在页面、Worker 或存储中持久化 credential,也不会在 Worker 进程丢失后自动重登。
391
+ - SharedWorker 仅共享实时连接和 Push,不同步页面草稿、未读 UI 或消息列表,也不持久化登录态。它不跨 origin、浏览器配置文件或 InPrivate 窗口共享;浏览器没有 SharedWorker API 时,`createClient()` 会改用每页一条独立连接,因此这些页面不能共享登录态。Worker 脚本加载或初始化失败仍会报告错误。
323
392
  - `clientOptions` 必须可结构化克隆;不能包含 `requestMetadataProvider`、元数据函数或 `webSocketFactory`。SharedWorker 只接受静态 `requestMetadata` 对象。
324
393
 
325
394
  ### FPNN 多窗口接入
326
395
 
327
- 此扩展目前在源码和本地构建中提供;已发布的 `1.0.0-cg.3` SharedWorker 仍仅支持 TLV,使用 FPNN 共享模式需要新版本或本地打包产物。Node.js 仍只支持 TLV。
396
+ FPNN SharedWorker 的可用性以 npm `latest` 标签对应的 SDK 版本为准;若该标签版本尚未包含此扩展,请使用本地构建或 yalc。Node.js 仍只支持 TLV。
328
397
 
329
398
  首次登录、后续窗口 `loginIfNeeded()`、`SharedSessionState`、路由和 detach 的使用方式与上面的 TLV 示例相同。FPNN 只改变连接配置和 Push 订阅;以下片段假定已加载 `rtm` 并取得 `pid`、`uid`、`peerUid`、FPNN Gate 地址及首次登录所需的 credential:
330
399
 
@@ -333,7 +402,7 @@ const shared = new rtm.RTMSharedWorkerClient({
333
402
  uid,
334
403
  conversation: { type: 'direct', id: peerUid },
335
404
  clientOptions: {
336
- protocol: 'fpnn', // 显式选择;省略时仍是 TLV。
405
+ protocol: 'fpnn', // 可省略;未指定协议时 RTMSharedWorkerClient 默认 FPNN。
337
406
  pid,
338
407
  ssl_endpoint: 'gate.example:13321', // wss;ws 使用 endpoint: 'gate.example:13321'
339
408
  autoReconnect: true,
@@ -352,9 +421,9 @@ await shared.promises.sendChat(peerUid, 'hello', '{}');
352
421
  // 页面离开时 SDK 自动 detach;也可显式 shared.destroy()。
353
422
  ```
354
423
 
355
- FPNN 的 `endpoint` / `ssl_endpoint` 接收 `host[:port]`,SDK 补上 `ws://` / `wss://` 和 `/service/websocket`;它与 TLV 的完整 URL 配置不同。自动 Worker identity 使用实际连接地址,同 UID 的 FPNN / TLV 页面不共享一条连接。若显式指定相同 `workerName` 却传入不同协议或配置,后加入页面初始化失败,不会覆盖已有会话。
424
+ FPNN 的 `endpoint` / `ssl_endpoint` 接收 `host[:port]`,SDK 补上 `ws://` / `wss://` 和 `/service/websocket`;它与 TLV 的完整 URL 配置不同。自动 Worker identity 包含协议,因此同 UID 的 FPNN / TLV 页面不会共享一条连接。若显式指定相同 `workerName` 却传入不同协议或配置,后加入页面初始化失败,不会覆盖已有会话。
356
425
 
357
- FPNN Push 保留 `SERVER_PUSH` 事件和 `from / gid / rid / mid / msg` 等字段;TLV 保留 `TLV_SERVER_PUSH` 事件及其字段。共享层只提取内部会话路由,不把 FPNN 业务数据包装成 TLV,也不执行额外的 ACK 或去重。FPNN 的聊天、命令、通用消息、文件接收事件均按会话过滤;广播和被踢下线事件发给所有页面。`sendFile` / `sendGroupFile` / `sendRoomFile` 在两种模式下都本地拒绝,文件接收和 FPNN `fileToken` 查询不在此限制内。传统参数与 Push 细节见 [协议迁移对照](PROTOCOL_MIGRATION.md) 和 [事件处理说明](EventProcess.md)。
426
+ FPNN Push 保留 `SERVER_PUSH` 事件和 `from / gid / rid / mid / msg` 等字段;TLV 保留 `TLV_SERVER_PUSH` 事件及其字段。Worker 原样分发所有 SDK 事件;ACK、去重、协议校验和业务请求都由底层 `RTMClient` 处理。页面适配器只在应用显式设置 `conversation` 时进行本地筛选。FPNN 的 `fileToken`、`sendFile`、`sendGroupFile`、`sendRoomFile` 都可通过共享调用使用,File 对象经结构化克隆交给 Worker,上传继续由 SDK 的文件代理连接完成。TLV 文件调用由底层协议契约返回 `200020`,共享层不维护业务 API 禁用名单。传统参数与 Push 细节见 [协议迁移对照](PROTOCOL_MIGRATION.md) 和 [事件处理说明](EventProcess.md)。
358
427
 
359
428
  ## 5. 参数与返回值约定
360
429
 
@@ -530,9 +599,9 @@ TLV 不支持的调用按实现分为三类:
530
599
 
531
600
  - TLV 合约中保留、但没有 Client API 路由的 wire(如 `filetoken`、`addfriends`、`acheck`)返回 `200020`(`RTM_EC_FORBIDDEN_METHOD`)。
532
601
  - 未登记且非保留的 wire 返回 `20004`(`RTM_EC_UNKNOWN_METHOD`)。
533
- - `RTMSharedWorkerClient` 的 `sendFile`、`sendGroupFile`、`sendRoomFile` 在本地拒绝;callback 收到 `{mid, error}`,其中 `error.code` 为 `200999`(`RTM_EC_UNKNOWN_ERROR`);Promise 版本 reject 同一个错误对象,不会发送 wire 请求。
602
+ - 共享客户端原样转发 SDK 请求及结果。TLV 文件发送由底层 `filetoken` 的契约校验拒绝;callback 收到 `{mid, error}`,其中 `error.code` 为 `200020`,Promise 版本 reject 同一对象。
534
603
 
535
- 这些错误都不会自动切换到 FPNN。SharedWorker 的 TLV 模式复用 TLV 支持范围;FPNN 模式可转发其兼容业务 API(文件发送除外)。两种模式都不接受函数型配置;`clientOptions` 必须可结构化克隆。FPNN 兼容能力列表见[能力总览](CAPABILITIES.md),服务端支持仍需单独确认。
604
+ 这些错误都不会自动切换到 FPNN。SharedWorker 的 TLV 模式复用 TLV 支持范围;FPNN 模式可转发其兼容业务 API,包括文件发送。两种模式都不接受函数型配置;`clientOptions` 必须可结构化克隆。FPNN 兼容能力列表见[能力总览](CAPABILITIES.md),服务端支持仍需单独确认。
536
605
 
537
606
  ## 7. 调试与参考
538
607
 
package/docs/Users.md ADDED
@@ -0,0 +1,48 @@
1
+ # RTM Client Websocket SDK User API Docs
2
+
3
+ ## Index
4
+
5
+ [TOC]
6
+
7
+ ## Apis
8
+
9
+ **协议范围:** 本页记录 FPNN 兼容 API 的参数和事件名称;列出的方法不一定都能通过 TLV v1 调用。请先核对 [TLV v1 支持矩阵](USAGE.md#6-tlv-v1-api-支持矩阵);两协议的 method、URI 和 Push 对照见[协议迁移说明](PROTOCOL_MIGRATION.md)。
10
+
11
+ * `getUserGroups(timeout, callback)`: 获取用户所在的Group
12
+ * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
13
+ * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
14
+ * `err`: **(Error)**
15
+ * `data`: **(array[Int64])**
16
+
17
+ * `getOnlineUsers(uids, timeout, callback)`: 获取在线用户
18
+ * `uids`: **(Required | array[Int64])** 多个用户 id
19
+ * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
20
+ * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
21
+ * `err`: **(Error)**
22
+ * `data`: **(array[Int64])**
23
+
24
+ * `setUserInfo(oinfo, pinfo, timeout, callback) `: 设置用户信息
25
+ * `oinfo`: **(Optional | string)** 公开信息
26
+ * `pinfo`: **(Optional | string)** 私有信息
27
+ * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
28
+ * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
29
+ * `err`: **(object[mid:Int64, error:Error])**
30
+ * `data`: **(object)**
31
+
32
+ * `getUserInfo(timeout, callback) `: 获取用户信息
33
+ * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
34
+ * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
35
+ * `err`: **(object[mid:Int64, error:Error])**
36
+ * `data`: **(object[oinfo:string, pinfo:string])**
37
+
38
+ * `getUserOpenInfo(uids, timeout, callback) `: 获取用户信息
39
+ * `uids`: **(Required | array(Int64))** 用户id列表
40
+ * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
41
+ * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
42
+ * `err`: **(object[mid:Int64, error:Error])**
43
+ * `data`: **(object[info:map<string, string>])**
44
+
45
+
46
+
47
+
48
+
@@ -0,0 +1,82 @@
1
+ # RTM Client Websocket SDK ValueAdded API Docs
2
+
3
+ ## Index
4
+
5
+ [TOC]
6
+
7
+ ## Apis
8
+
9
+ **协议范围:** 本页记录 FPNN 兼容 API 的参数和事件名称;列出的方法不一定都能通过 TLV v1 调用。请先核对 [TLV v1 支持矩阵](USAGE.md#6-tlv-v1-api-支持矩阵);两协议的 method、URI 和 Push 对照见[协议迁移说明](PROTOCOL_MIGRATION.md)。审核接口中的 `strategyId` 必须占据其参数位置;只传 timeout 时先传 `undefined`,例如 `imageCheck(image, type, undefined, timeout, callback)`。
10
+
11
+ * `translate(originalMessage, originalLanguage, targetLanguage, type, profanity, timeout, callback)`: 翻译消息
12
+ * `originalMessage`: **(Required | stirng)** 待翻译的原始消息
13
+ * `originalLanguage`: **(Optional | string)** 待翻译的消息的语言类型, 可为 `undefined`
14
+ * `targetLanguage`: **(Required | string)** 本次翻译的目标语言类型
15
+ * `type`: **(Required | string)** 可选值为chat或mail。如未指定,则默认使用chat
16
+ * `profanity`: **(Required | string)** 敏感语过滤。设置为以下3项之一: off, stop, censor,默认:off
17
+ * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
18
+ * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
19
+ * `err`: **(Error)**
20
+ * `data`: **(object[source:string, target:string, targetText:string, sourceText:string])**
21
+
22
+ * `textCheck(text, strategyId, timeout, callback)`: 文本审核;兼容简写 `textCheck(text, timeout, callback)`。
23
+ * `text`: **(Required | string)** 文本
24
+ * `strategyId`: **(Optional)** 审核策略 ID;不使用时传 `undefined`,旧式 timeout 简写不需要此参数
25
+ * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
26
+ * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
27
+ * `err`: **(Error)**
28
+ * `data`: **({ result: int32, ?text: string,?tags:list<int32>,?wlist:list<string> })**
29
+ * `result`: 0: 通过,2,不通过
30
+ * `text`: 敏感词过滤后的文本内容,含有的敏感词会被替换为*,如果没有被标星,则无此字段
31
+ * `tags`: 触发的分类,比如涉黄涉政等等,具体见文本审核分类
32
+ * `wlist`: 敏感词列表
33
+
34
+ * `imageCheck(image, type, strategyId, timeout, callback)`: 图片审核
35
+ * `image`: **(Required | string)** 图片的url 或者内容
36
+ * `type`: **(Required | number)** 1, url, 2, 内容
37
+ * `strategyId`: **(Optional)** 审核策略 ID;不使用时传 `undefined` 保留参数位置
38
+ * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
39
+ * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
40
+ * `err`: **(Error)**
41
+ * `data`: **({ result: int32, ?tags:list<int32> })**
42
+ * `result`: 0: 通过,2,不通过
43
+ * `tags`: 触发的分类,比如涉黄涉政等等,具体见文本审核分类
44
+
45
+ * `audioCheck(audio, type, lang, codec, srate, strategyId, timeout, callback)`: 音频审核
46
+ * `audio`: **(Required | string)** 音频的url 或者内容
47
+ * `type`: **(Required | number)** 1, url, 2, 内容
48
+ * `lang`: **(Required | string)** 音频语言
49
+ * `codec`: **(Optional | string)** 音频b编码, 默认AMR_WB
50
+ * `srate`: **(Optional | number)** 音频采样率, 16000
51
+ * `strategyId`: **(Optional)** 审核策略 ID;不使用时传 `undefined` 保留参数位置
52
+ * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
53
+ * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
54
+ * `err`: **(Error)**
55
+ * `data`: **({ result: int32, ?tags:list<int32> })**
56
+ * `result`: 0: 通过,2,不通过
57
+ * `tags`: 触发的分类,比如涉黄涉政等等,具体见文本审核分类
58
+
59
+ * `videoCheck(video, type, videoName, strategyId, timeout, callback)`: 视频审核
60
+ * `video`: **(Required | string)** 视频的url 或者内容
61
+ * `type`: **(Required | number)** 1, url, 2, 内容
62
+ * `videoName`: **(Required | string)** 音频文件名
63
+ * `strategyId`: **(Optional)** 审核策略 ID;不使用时传 `undefined` 保留参数位置
64
+ * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
65
+ * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
66
+ * `err`: **(Error)**
67
+ * `data`: **({ result: int32, ?tags:list<int32> })**
68
+ * `result`: 0: 通过,2,不通过
69
+ * `tags`: 触发的分类,比如涉黄涉政等等,具体见文本审核分类
70
+
71
+ * `speech2Text(audio, type, lang, codec, srate, timeout, callback)`: 语音转文字
72
+ * `audio`: **(Required | string)** 音频的url 或者内容
73
+ * `type`: **(Required | number)** 1, url, 2, 内容
74
+ * `lang`: **(Required | string)** 音频语言
75
+ * `codec`: **(Optional | string)** 音频b编码, 默认AMR_WB
76
+ * `srate`: **(Optional | number)** 音频采样率, 16000
77
+ * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
78
+ * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
79
+ * `err`: **(Error)**
80
+ * `data`: **({ text: string, lang: string })**
81
+ * `text`: 识别的结果
82
+ * `lang`: 识别的语言
package/package.json CHANGED
@@ -1,9 +1,10 @@
1
1
  {
2
2
  "name": "@cg-devcenter/rtc-fpnn-webjs-sdk",
3
- "version": "1.0.0-cg.5",
3
+ "version": "1.0.0-cg.7",
4
4
  "description": "Browser RTM SDK with FPNN and TLV v1 MessagePack WebSocket transports",
5
5
  "main": "./dist/rtm.min.js",
6
6
  "browser": "./dist/rtm.min.js",
7
+ "module": "./dist/rtm.mjs",
7
8
  "types": "./dist/rtm.d.ts",
8
9
  "unpkg": "./dist/rtm.min.js",
9
10
  "jsdelivr": "./dist/rtm.min.js",
@@ -14,19 +15,47 @@
14
15
  "docs/CAPABILITIES.md",
15
16
  "docs/TLV_LIVE_E2E_TEST.md",
16
17
  "docs/USAGE.md",
17
- "docs/PROTOCOL_MIGRATION.md"
18
+ "docs/RTM_MIGRATION.md",
19
+ "docs/NPM_MODERNIZATION_PLAN.md",
20
+ "docs/PROTOCOL_MIGRATION.md",
21
+ "docs/Users.md",
22
+ "docs/Groups.md",
23
+ "docs/Rooms.md",
24
+ "docs/Messages.md",
25
+ "docs/Chat.md",
26
+ "docs/Data.md",
27
+ "docs/System.md",
28
+ "docs/Files.md",
29
+ "docs/Friends.md",
30
+ "docs/ValueAdded.md",
31
+ "docs/EventProcess.md"
18
32
  ],
19
33
  "exports": {
20
34
  ".": {
21
- "types": "./dist/rtm.d.ts",
22
- "require": "./dist/rtm.min.js",
23
- "default": "./dist/rtm.min.js"
35
+ "import": {
36
+ "types": "./dist/rtm.d.mts",
37
+ "default": "./dist/rtm.mjs"
38
+ },
39
+ "require": {
40
+ "types": "./dist/rtm.d.cts",
41
+ "default": "./dist/rtm.min.js"
42
+ }
24
43
  },
25
44
  "./vite": {
26
45
  "types": "./dist/rtm.vite.d.ts",
27
46
  "import": "./dist/rtm.vite.mjs",
28
47
  "default": "./dist/rtm.vite.mjs"
29
48
  },
49
+ "./vite-plugin": {
50
+ "types": "./dist/rtm.vite-plugin.d.mts",
51
+ "import": "./dist/rtm.vite-plugin.mjs",
52
+ "default": "./dist/rtm.vite-plugin.mjs"
53
+ },
54
+ "./webpack4": {
55
+ "types": "./dist/rtm.webpack4-plugin.d.cts",
56
+ "require": "./dist/rtm.webpack4-plugin.cjs",
57
+ "default": "./dist/rtm.webpack4-plugin.cjs"
58
+ },
30
59
  "./shared-worker": "./dist/rtm.shared-worker.js",
31
60
  "./dist/*": "./dist/*",
32
61
  "./package.json": "./package.json"
@@ -34,10 +63,12 @@
34
63
  "author": "Dixun",
35
64
  "license": "MIT",
36
65
  "scripts": {
37
- "build": "webpack --mode production && webpack --config webpack.shared-worker.config.js --mode production",
66
+ "prebuild": "node scripts/check-build-node.mjs",
67
+ "build": "webpack --mode production && webpack --config webpack.shared-worker.config.js --mode production && node scripts/build-modern.mjs",
38
68
  "test": "npm run test:unit && npm run test:package",
39
- "test:unit": "node test/tlv/run.js && node test/tlv/documentation.js",
40
- "test:package": "npm run build && node test/package-smoke.js",
69
+ "test:unit": "node test/tlv/run.js && node test/tlv/documentation.js && node test/migration-compatibility.js && node test/demo-workflows.js && node test/vue-demo-state.js",
70
+ "test:package": "npm run build && node test/package-files.js && node test/package-tarball.js && node test/package-smoke.js && node test/package-esm-smoke.mjs && node test/package-webpack4.js && npm run test:types",
71
+ "test:types": "tsc --noEmit --module NodeNext --moduleResolution NodeNext --target ES2020 test/package-types/esm.mts test/package-types/cjs.cts",
41
72
  "demo:tlv-basic": "node examples/tlv-basic-demo/server.js",
42
73
  "demo:shared-worker": "node examples/shared-worker-demo/server.js",
43
74
  "prepack": "npm run build"
@@ -49,7 +80,9 @@
49
80
  "babel-preset-es2015": "^6.24.1",
50
81
  "babel-preset-stage-2": "^6.24.1",
51
82
  "buffer": "^5.1.0",
83
+ "esbuild": "^0.25.12",
52
84
  "int64-buffer": "^0.1.10",
85
+ "typescript": "^5.8.3",
53
86
  "webpack": "^4.1.1",
54
87
  "webpack-cli": "^3.3.12"
55
88
  },