@cg-devcenter/rtc-fpnn-webjs-sdk 1.0.0-cg.10

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/Data.md ADDED
@@ -0,0 +1,33 @@
1
+ # RTM Client Websocket SDK Data 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
+ * `dataSet(key, value, timeout, callback)`: 设置存储的数据信息(key:最长128字节,val:最长65535字节)
12
+ * `key`: **(Required | string)** 数据的key
13
+ * `value`: **(Optional | string)** 数据的value
14
+ * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
15
+ * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
16
+ * `err`: **(object[mid:Int64, error:Error])**
17
+ * `data`: **(object)**
18
+
19
+ * `dataGet(key, timeout, callback) `: 获取存储的数据信息(key:最长128字节,val:最长65535字节)
20
+ * `key`: **(Required | string)** 数据的key
21
+ * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
22
+ * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
23
+ * `err`: **(object[mid:Int64, error:Error])**
24
+ * `data`: **(object[val:string])**
25
+
26
+ * `dataDelete(key, timeout, callback)`: 删除存储的数据信息
27
+ * `key`: **(Required | string)** 数据的key
28
+ * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
29
+ * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
30
+ * `err`: **(object[mid:Int64, error:Error])**
31
+ * `data`: **(object)**
32
+
33
+
@@ -0,0 +1,126 @@
1
+ # RTM Client Websocket SDK Event Process 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
+ 请参考 `RTMConfig.SERVER_PUSH` 成员
12
+
13
+ > TLV v1 模式说明:网络 Push wire 为 `event.direct`、`event.group`、`event.room`、`event.broadcast`、`event.kicked`、`event.room_removed`,请通过 `RTMConfig.TLV_SERVER_PUSH` 订阅同名事件;data 使用新字段(例如 `message_ref`、`time_ms`、`payload`)。前四类会在回调前自动发送 `control.ack`,后两类不会 ACK。TLV 业务心跳改为 Client 主动 `control.ping`,不再依赖本页的服务端 `ping` Push。
14
+
15
+ * `kickout`: RTMGate主动断开
16
+ * `data`: **(object)**
17
+
18
+ * `kickoutroom`: RTMGate主动从Room移除
19
+ * `data.rid`: **(Int64)** Room id
20
+
21
+ * `ping`: RTMGate主动ping
22
+ * `data`: **(object)**
23
+
24
+ * `pushmsg`: RTMGate主动推送P2P消息
25
+ * `data.from`: **(Int64)** 发送者 id
26
+ * `data.mtype`: **(number)** 消息类型
27
+ * `data.mid`: **(Int64)** 消息 id, 当前链接会话内唯一
28
+ * `data.msg`: **(string)** 消息内容
29
+ * `data.attrs`: **(string)** 发送时附加的自定义内容
30
+ * `data.mtime`: **(Int64)**
31
+
32
+ * `pushgroupmsg`: RTMGate主动推送Group消息
33
+ * `data.from`: **(Int64)** 发送者 id
34
+ * `data.gid`: **(Int64)** Group id
35
+ * `data.mtype`: **(number)** 消息类型
36
+ * `data.mid`: **(Int64)** 消息 id, 当前链接会话内唯一
37
+ * `data.msg`: **(string)** 消息内容
38
+ * `data.attrs`: **(string)** 发送时附加的自定义内容
39
+ * `data.mtime`: **(Int64)**
40
+
41
+ * `pushroommsg`: RTMGate主动推送Room消息
42
+ * `data.from`: **(Int64)** 发送者 id
43
+ * `data.rid`: **(Int64)** Room id
44
+ * `data.mtype`: **(number)** 消息类型
45
+ * `data.mid`: **(Int64)** 消息 id, 当前链接会话内唯一
46
+ * `data.msg`: **(string)** 消息内容
47
+ * `data.attrs`: **(string)** 发送时附加的自定义内容
48
+ * `data.mtime`: **(Int64)**
49
+
50
+ * `pushbroadcastmsg`: RTMGate主动推送广播消息
51
+ * `data.from`: **(Int64)** 发送者 id
52
+ * `data.mtype`: **(number)** 消息类型
53
+ * `data.mid`: **(Int64)** 消息 id, 当前链接会话内唯一
54
+ * `data.msg`: **(string)** 消息内容
55
+ * `data.attrs`: **(string)** 发送时附加的自定义内容
56
+ * `data.mtime`: **(Int64)**
57
+
58
+ * `pushfile`: RTMGate主动推送P2P文件
59
+ * `data.from`: **(Int64)** 发送者 id
60
+ * `data.mtype`: **(number)** 文件类型, 请参考 `RTMConfig.FILE_TYPE` 成员
61
+ * `data.mid`: **(Int64)** 消息 id, 当前链接会话内唯一
62
+ * `data.msg`: **(string)** 文件获取地址(url)
63
+ * `data.attrs`: **(string)** 发送时附加的自定义内容
64
+ * `data.mtime`: **(Int64)**
65
+
66
+ * `pushgroupfile`: RTMGate主动推送Group文件
67
+ * `data.from`: **(Int64)** 发送者 id
68
+ * `data.gid`: **(Int64)** Group id
69
+ * `data.mtype`: **(number)** 文件类型, 请参考 `RTMConfig.FILE_TYPE` 成员
70
+ * `data.mid`: **(Int64)** 消息 id, 当前链接会话内唯一
71
+ * `data.msg`: **(string)** 文件获取地址(url)
72
+ * `data.attrs`: **(string)** 发送时附加的自定义内容
73
+ * `data.mtime`: **(Int64)**
74
+
75
+ * `pushroomfile`: RTMGate主动推送Room文件
76
+ * `data.from`: **(Int64)** 发送者 id
77
+ * `data.rid`: **(Int64)** Room id
78
+ * `data.mtype`: **(number)** 文件类型, 请参考 `RTMConfig.FILE_TYPE` 成员
79
+ * `data.mid`: **(Int64)** 消息 id, 当前链接会话内唯一
80
+ * `data.msg`: **(string)** 文件获取地址(url)
81
+ * `data.attrs`: **(string)** 发送时附加的自定义内容
82
+ * `data.mtime`: **(Int64)**
83
+
84
+ * `pushbroadcastfile`: RTMGate主动推送广播文件
85
+ * `data.from`: **(Int64)** 发送者 id
86
+ * `data.mtype`: **(number)** 文件类型, 请参考 `RTMConfig.FILE_TYPE` 成员
87
+ * `data.mid`: **(Int64)** 消息 id, 当前链接会话内唯一
88
+ * `data.msg`: **(string)** 文件获取地址(url)
89
+ * `data.attrs`: **(string)** 发送时附加的自定义内容
90
+ * `data.mtime`: **(Int64)**
91
+
92
+ * `pushchat`: RTMGate主动推送聊天消息
93
+ * 参数与pushmsg一致
94
+
95
+ * `pushaudio`: RTMGate主动推送语音聊天消息
96
+ * 参数与pushmsg一致
97
+
98
+ * `pushcmd`: RTMGate主动推送聊天控制命令
99
+ * 参数与pushmsg一致
100
+
101
+ * `pushgroupchat`: RTMGate主动推送组聊天消息
102
+ * 参数与pushgroupmsg一致
103
+
104
+ * `pushgroupaudio`: RTMGate主动推送组语音消息
105
+ * 参数与pushgroupmsg一致
106
+
107
+ * `pushgroupcmd`: RTMGate主动推送组聊天控制命令
108
+ * 参数与pushgroupmsg一致
109
+
110
+ * `pushroomchat`: RTMGate主动推送房间聊天消息
111
+ * 参数与pushroommsg一致
112
+
113
+ * `pushroomaudio`: RTMGate主动推送房间语音消息
114
+ * 参数与pushroommsg一致
115
+
116
+ * `pushroomcmd`: RTMGate主动推送房间聊天控制命令
117
+ * 参数与pushroommsg一致
118
+
119
+ * `pushbroadcastchat`: RTMGate主动推送广播聊天消息
120
+ * 参数与pushbroadcastchat一致
121
+
122
+ * `pushbroadcastaudio`: RTMGate主动推送广播语音消息
123
+ * 参数与pushbroadcastchat一致
124
+
125
+ * `pushbroadcastcmd`: RTMGate主动推送广播聊天控制命令
126
+ * 参数与pushbroadcastchat一致
package/docs/Files.md ADDED
@@ -0,0 +1,52 @@
1
+ # RTM Client Websocket SDK File API Docs
2
+
3
+ ## Index
4
+
5
+ [TOC]
6
+
7
+ ## Apis
8
+
9
+ FPNN 模式下,以下 API 同时适用于独立 `RTMClient` 和共享客户端(`createClient()` / `RTMSharedWorkerClient`),callback 与 Promise 结果沿用 SDK 约定。SharedWorker 通过结构化克隆接收 `File`,由内部 SDK 获取 token 并建立文件代理连接上传。现有上传会读取整个文件到内存;不承诺所有页面关闭或 Worker 被回收后仍能完成后台上传。TLV v1 的文件接口仍由底层协议契约拒绝。
10
+
11
+ * `fileToken(cmd, tos, to, rid, gid, timeout, callback)`: 获取发送文件的token
12
+ * `cmd`: **(Required | string)** 文件发送方式`sendfile | sendroomfile | sendgroupfile`
13
+ * `tos`: **(Optional | array[Int64])** 接收方 uids
14
+ * `to`: **(Optional | Int64)** 接收方 uid
15
+ * `rid`: **(Optional | Int64)** Room id
16
+ * `gid`: **(Optional | Int64)** Group id
17
+ * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
18
+ * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
19
+ * `err`: **(Error)**
20
+ * `data`: **(object[token:string, endpoint:string])**
21
+
22
+ * `sendFile(mtype, to, file, mid, timeout, callback)`: 发送文件
23
+ * `mtype`: **(Required | number)** 文件类型
24
+ * `to`: **(Required | Int64)** 接收者 id
25
+ * `file`: **(Required | File)** 要发送的文件
26
+ * `mid`: **(Optional | Int64)** 消息 id, 用于过滤重复消息, 非重发时为`Int64(0)`
27
+ * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
28
+ * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
29
+ * `err`: **(object[mid:Int64, error:Error])**
30
+ * `data`: **(object[mid:Int64, payload:object[mtime:Int64]])**
31
+
32
+ * `sendGroupFile(mtype, gid, file, mid, timeout, callback)`: 给Group发送文件
33
+ * `mtype`: **(Required | number)** 文件类型
34
+ * `gid`: **(Required | Int64)** Group id
35
+ * `file`: **(Required | File)** 要发送的文件
36
+ * `mid`: **(Optional | Int64)** 消息 id, 用于过滤重复消息, 非重发时为`Int64(0)`
37
+ * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
38
+ * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
39
+ * `err`: **(object[mid:Int64, error:Error])**
40
+ * `data`: **(object[mid:Int64, payload:object[mtime:Int64]])**
41
+
42
+ * `sendRoomFile(mtype, rid, file, mid, timeout, callback)`: 给Room发送文件
43
+ * `mtype`: **(Required | number)** 文件类型
44
+ * `rid`: **(Required | Int64)** Room id
45
+ * `file`: **(Required | File)** 要发送的文件
46
+ * `mid`: **(Optional | Int64)** 消息 id, 用于过滤重复消息, 非重发时为`Int64(0)`
47
+ * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
48
+ * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
49
+ * `err`: **(object[mid:Int64, error:Error])**
50
+ * `data`: **(object[mid:Int64, payload:object[mtime:Int64]])**
51
+
52
+
@@ -0,0 +1,50 @@
1
+ # RTM Client Websocket SDK Friends 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
+ * `addFriends(friends, timeout, callback)`: 添加好友
12
+ * `friends`: **(Required | array[Int64])** 多个好友 id
13
+ * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
14
+ * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
15
+ * `err`: **(Error)**
16
+ * `data`: **(object)**
17
+
18
+ * `deleteFriends(friends, timeout, callback)`: 删除好友
19
+ * `friends`: **(Required | array[Int64])** 多个好友 id
20
+ * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
21
+ * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
22
+ * `err`: **(Error)**
23
+ * `data`: **(object)**
24
+
25
+ * `getFriends(timeout, callback)`: 获取好友
26
+ * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
27
+ * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
28
+ * `err`: **(Error)**
29
+ * `data`: **(array[Int64])**
30
+
31
+ * `addBlacks(blacks, timeout, callback)`: 添加黑名单,每次最多添加100人,拉黑后对方不能给自己发消息,自己可以给对方发,双方能正常获取session及历史消息
32
+ * `blacks`: **(Required | array[Int64])** 多个用户id
33
+ * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
34
+ * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
35
+ * `err`: **(Error)**
36
+ * `data`: **(object)**
37
+
38
+ * `deleteBlacks(blacks, timeout, callback)`: 解除拉黑,每次最多解除100人
39
+ * `friends`: **(Required | array[Int64])** 多个用户id
40
+ * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
41
+ * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
42
+ * `err`: **(Error)**
43
+ * `data`: **(object)**
44
+
45
+ * `getBlacks(timeout, callback)`: 获取被我拉黑的用户列表
46
+ * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
47
+ * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
48
+ * `err`: **(Error)**
49
+ * `data`: **(array[Int64])**
50
+
package/docs/Groups.md ADDED
@@ -0,0 +1,64 @@
1
+ # RTM Client Websocket SDK Group 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
+ * `setGroupInfo(gid, oinfo, pinfo, timeout, callback) `: 设置组信息
12
+ * `gid`: **(Required | Int64)** 组id
13
+ * `oinfo`: **(Optional | string)** 公开信息
14
+ * `pinfo`: **(Optional | string)** 私有信息
15
+ * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
16
+ * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
17
+ * `err`: **(object[mid:Int64, error:Error])**
18
+ * `data`: **(object)**
19
+
20
+ * `getGroupInfo(gid, timeout, callback) `: 获取群组的公开信息和私有信息,会检查用户是否在组内
21
+ * `gid`: **(Required | Int64)** 组id
22
+ * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
23
+ * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
24
+ * `err`: **(object[mid:Int64, error:Error])**
25
+ * `data`: **(object[oinfo:string, pinfo:string])**
26
+
27
+ * `getGroupOpenInfo(gid, timeout, callback) `: 获取群组的公开信息
28
+ * `gid`: **(Required | Int64)** 组id
29
+ * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
30
+ * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
31
+ * `err`: **(object[mid:Int64, error:Error])**
32
+ * `data`: **(object[oinfo:string, pinfo:string])**
33
+
34
+ * `addGroupMembers(gid, uids, timeout, callback)`: 添加group成员
35
+ * `gid`: **(Required | Int64)** group id
36
+ * `uids`: **(Required | array[Int64])** 多个用户 id
37
+ * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
38
+ * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
39
+ * `err`: **(Error)**
40
+ * `data`: **(object)**
41
+
42
+ * `deleteGroupMembers(gid, uids, timeout, callback)`: 删除group成员
43
+ * `gid`: **(Required | Int64)** group id
44
+ * `uids`: **(Required | array[Int64])** 多个用户 id
45
+ * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
46
+ * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
47
+ * `err`: **(Error)**
48
+ * `data`: **(object)**
49
+
50
+ * `getGroupMembers(gid, online, timeout, callback)`: 获取group成员
51
+ * `gid`: **(Required | Int64)** group id
52
+ * `online`: **(Optional | Bool)** get online users
53
+ * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
54
+ * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
55
+ * `err`: **(Error)**
56
+ * `data`: **(array[Int64])**
57
+
58
+ * `getGroupCount(gid, online, timeout, callback)`: 获取group成员
59
+ * `gid`: **(Required | Int64)** group id
60
+ * `online`: **(Optional | Bool)** get online users count
61
+ * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
62
+ * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
63
+ * `err`: **(Error)**
64
+ * `data`: **(array[Int64])**
@@ -0,0 +1,188 @@
1
+ # 旧 RTM FPNN 项目迁移到 TLV
2
+
3
+ 本文说明如何用当前 SDK 的 `createClient()` 把上游 RTM JavaScript SDK 常用业务接口迁移到 TLV v1,同时保留旧 RTM 的方法名、Callback 参数顺序、主要返回结构和 Push 名称。
4
+
5
+ ## 适用范围
6
+
7
+ - 兼容基线是迁移档案固定的上游 RTM 源码 commit `afe69746fea1444687f8999e9de05cbbb4838400`。旧 npm 包、内部 fork 或带补丁构建可能不同;先列出项目实际调用的方法、Push 和返回字段,再按本文边界检查。
8
+ - `compatibility: 'legacy-rtm'` 选择旧 RTM 页面 API 契约。FPNN 本身已经使用该契约,不做二次转换;只有 `createClient({ protocol: 'tlv-v1', compatibility: 'legacy-rtm' })` 才会启用 TLV 到旧 API 的映射。默认协议仍是 FPNN,默认接口契约仍是 SDK 原生接口。
9
+ - 胶水层在页面 facade 中转换输入/结果/Push,不实现另一套 RTC 连接、TLV 编码、ACK、去重、重连或 Worker。SharedWorker、直连模式最终都使用 SDK 现有 TLV 实现。
10
+ - 兼容不是对所有上游 API 的无条件替换。TLV 未支持的方法会明确报本地兼容错误,不会偷偷改走 FPNN。
11
+
12
+ ## 最小迁移
13
+
14
+ 旧项目常见写法:
15
+
16
+ ```js
17
+ import rtm from 'rtm-fpnn-webjs-sdk';
18
+
19
+ const client = new rtm.RTMClient({ pid, endpoint: fpnnEndpoint });
20
+ client.processor.on(rtm.RTMConfig.SERVER_PUSH.recvChat, onChat);
21
+ client.login(uid, credential, onLogin, 30_000);
22
+ ```
23
+
24
+ 迁移为新包的工厂入口,明确选择 TLV 与旧业务契约:
25
+
26
+ ```js
27
+ import rtm from '@cg-devcenter/rtc-fpnn-webjs-sdk';
28
+
29
+ const uid = '91001'; // 大于 Number 安全整数范围时必须使用十进制字符串
30
+ const client = rtm.createClient({
31
+ pid: 80271,
32
+ uid,
33
+ protocol: 'tlv-v1',
34
+ tlvEndpoint: 'wss://<gate-host>/service/websocket',
35
+ compatibility: 'legacy-rtm',
36
+ autoReconnect: true,
37
+ });
38
+
39
+ client.processor.on(rtm.RTMConfig.SERVER_PUSH.recvChat, message => {
40
+ console.log(message.from.toString(), message.msg, message.mid.toString());
41
+ });
42
+ client.processor.on('CompatibilityError', error => {
43
+ // 本地适配错误;不是 Gate 返回的服务端错误。
44
+ console.error(error.code, error.method, error.message);
45
+ });
46
+
47
+ await client.promises.login(uid, await getCredentialFromYourServer(uid));
48
+ const sent = await client.promises.sendChat('91002', 'hello', '{}');
49
+ console.log(sent.mid.toString(), sent.payload.mtime?.toString());
50
+
51
+ // 单页/组件退出:释放本页。不要用 bye()/close() 清理一个共享页面。
52
+ client.destroy();
53
+ ```
54
+
55
+ credential 必须由业务服务端为该 UID 签发。项目 `SecretKey` 不应放入浏览器、URL、Demo 配置或日志。
56
+
57
+ ### 协议和接口契约是两个独立开关
58
+
59
+ | `protocol` | `compatibility` | 行为 |
60
+ | --- | --- | --- |
61
+ | 省略或 `fpnn` | 省略或 `native` | FPNN + 当前 SDK 原生接口,原有默认行为。 |
62
+ | 省略或 `fpnn` | `legacy-rtm` | 返回旧 RTM 页面 API 类型;FPNN 原本已使用该契约,不做二次转换。 |
63
+ | `tlv-v1` | 省略或 `native` | TLV v1 + 当前 SDK 原生返回与 Push。 |
64
+ | `tlv-v1` | `legacy-rtm` | TLV v1 网络协议 + 本文的旧 RTM 页面 API 适配。 |
65
+
66
+ `compatibility` 只接受 `native` 或 `legacy-rtm`;未知值在创建时抛 `TypeError`。它不推断协议,也不因 TLV 失败而回退到 FPNN。旧构造器 `RTMClient` 和 `RTMSharedWorkerClient` 不接受此选项。
67
+
68
+ TypeScript 中,省略协议或选择 FPNN 并设置 `legacy-rtm`,会得到 `RTMLegacyFpnnDefaultClient`;FPNN 原生支持的旧 RTM API 仍可用。显式选择 TLV 时会得到 `RTMLegacyDefaultClient`,类型会排除下方列出的 17 个 FPNN-only 方法,因为 TLV 兼容层会明确拒绝它们。若协议由变量在运行时选择,类型只提供两个协议共有的旧 RTM 方法。`compatibility: 'native'` 则保留当前 SDK 原生类型。
69
+
70
+ ## 保留的调用方式与结果
71
+
72
+ 兼容 facade 保留旧 RTM 方法名及参数顺序,并提供同名 `client.promises` API。Callback 方法仍按旧接口位置传 Callback;Promise 由同一适配路径产生,避免两种调用方式得到不同的数据结构。发送 API 的 `attrs` 按旧 RTM 接口要求传入字符串;没有附加信息时传 `''`(示例使用 `'{}'`)。
73
+
74
+ `close()`、`startAutoReconnect()`、`destroy()` 是客户端生命周期控制,不映射为 TLV 业务 route。`startAutoReconnect()` 由 facade 直接转发给底层客户端;共享模式下由 SharedWorker 客户端转发给 Worker 中的 RTMClient。它不会因 TLV 兼容层缺少业务 route 而被拒绝。
75
+
76
+ `getUnreadMessage` 保留 `withLogout` 布尔参数,`removeSession` 保留 `localOnly` 布尔参数;两者也兼容旧式的第二位 `timeout` 调用。传入布尔选项后,`timeout` 顺延一位。Callback 和 Promise 入口都遵循该参数顺序。
77
+
78
+ ### 消息发送
79
+
80
+ ```js
81
+ client.sendChat(peerUid, 'hello', '{}', undefined, 15_000, (error, result) => {
82
+ if (error) {
83
+ // 发送失败沿用旧的外层形状:{ mid, error }
84
+ console.error(error.mid?.toString(), error.error?.code);
85
+ return;
86
+ }
87
+ console.log(result.mid.toString(), result.payload);
88
+ });
89
+
90
+ const result = await client.promises.sendGroupChat(groupId, 'hello', '{}');
91
+ ```
92
+
93
+ - 成功为 `{ mid, payload }`;TLV 的 `message_ref` 映射到 `mid`,`time_ms` 映射到旧字段 `mtime`。
94
+ - 发送失败 Callback 为 `(errorObject, null)`;`errorObject` 保留 `{ mid, error }` 结构。Promise reject 同一个外层错误对象,错误码通常在 `error.error.code`,不是 `error.code`。
95
+ - 消息载荷有协议边界:FPNN 的 `legacy-rtm` 保留旧 RTM MessagePack 输入,可发送对象;TLV v1 的 `message.send.payload` 仅接受字符串或二进制。兼容层不会替业务把对象自动 `JSON.stringify`。迁移到 TLV 时,若旧业务发送对象,请显式传 `JSON.stringify(value)`;若业务定义了二进制协议,则传 `Uint8Array`。对应类型分别是 `RTMLegacyMessagePayload`(FPNN 兼容接口)和 `RTMLegacyTlvMessagePayload`(TLV 兼容接口)。
96
+
97
+ - 省略、`undefined`、空或零 `mid` 时,兼容层会在发请求前生成一个正的有符号 int64 ID;成功和失败都使用这个 ID。显式非零 `mid` 保持原值。ID 使用 `crypto.getRandomValues()` 的 63 位随机值,碰撞概率很低但不是数学上的零;环境不提供安全随机 API 时会本地拒绝发送。native TLV 仍保持原有 Gate 分配行为。
98
+ - 不会更改 TLV 支持的消息类型、大小、批量上限或权限。超出 TLV 合法值域的旧业务消息仍需迁移处理。
99
+
100
+ ### 历史和列表
101
+
102
+ 已映射的历史/消息响应会按旧 RTM 结构返回。历史响应的 TLV `size/items/next/first_ms/last_ms` 映射为旧 `num/msgs/lastid/begin/end`;`lastid` 作为不透明游标保留,时间单位仍为毫秒。八字段消息 tuple 会转换成 `id/mtype/mid/deleted/msg/binary/attrs/mtime`;私聊 tuple 的第二项是 `direction`,群组、房间和广播记录按对应响应的发送者语义转换。64 位 ID、消息 ID、时间和游标保留 SDK 的 int64 类型,不经过 JS `Number`。
103
+
104
+ 一对一、群组、房间、广播历史、按消息 ID 查询、会话列表、未读摘要等支持接口使用底层 TLV contract 中已有的 response schema 转换。遇到无法无损表达的结果(例如字段冲突、tuple 结构不符合预期、整数不精确),接口显式报 `RTM_COMPATIBILITY_MAPPING_FAILED`;不会返回伪造的旧对象。
105
+
106
+ 完整方法到 FPNN method/TLV URI 对照见 [协议迁移对照](PROTOCOL_MIGRATION.md);TLV schema 仍以 [TLV Client API 契约](TLV_CONTRACT.md) 为准。
107
+
108
+ ## Push 对照
109
+
110
+ TLV 的 Push 先按原始 TLV 事件和字段由 SDK 完成校验、ACK、去重及页面会话筛选,然后仅在当前页面转换成旧 RTM 事件。不会把 TLV 事件重放给 FPNN Processor。
111
+
112
+ | TLV Push | `legacy-rtm` 事件 | 主要转换 |
113
+ | --- | --- | --- |
114
+ | `event.direct` | `pushchat` (kind 30)、`pushcmd` (kind 32)、`pushfile` (kind 31 或文件 kind 40–50)、其他 kind 为 `pushmsg` | `sender→from`、`kind→mtype`、`message_ref→mid`、`payload→msg/binary`、`extra→attrs`、`time_ms→mtime`、`recipient→to`。 |
115
+ | `event.group` | `pushgroupchat`、`pushgroupcmd`、`pushgroupfile` 或 `pushgroupmsg` | 上述字段及 `group_ref→gid`。 |
116
+ | `event.room` | `pushroomchat`、`pushroomcmd`、`pushroomfile` 或 `pushroommsg` | 上述字段及 `room_ref→rid`。 |
117
+ | `event.broadcast` | `pushbroadcastchat`、`pushbroadcastcmd`、`pushbroadcastfile` 或 `pushbroadcastmsg` | 上述公共字段。 |
118
+ | `event.kicked` | `kickout` | 只传递实际存在字段,不补造原因。 |
119
+ | `event.room_removed` | `kickoutroom` | `room_ref→rid`。 |
120
+
121
+ 文本 30 走 chat,命令 32 走 cmd;固定旧 RTM Processor 将语音 31 与文件类型放在 `pushfile` 系列,兼容层照此行为处理。旧配置虽然声明了 `pushaudio` 等常量,但基线处理器没有发出这些事件;在兼容 TLV 模式订阅它们会收到 `RTM_COMPATIBILITY_UNSUPPORTED`,请订阅对应的 `pushfile`、`pushgroupfile`、`pushroomfile` 或 `pushbroadcastfile`。TLV 心跳没有等价的服务端 `ping` Push,兼容模式也不伪造该事件。
122
+
123
+ TLV 的原始事件名(例如 `event.direct`)不能在 `legacy-rtm` 页面直接订阅;若要消费原生 TLV 事件,使用 `compatibility: 'native'`。同一 Worker 可以同时服务 native 与 legacy 页面,每个页面只收到各自契约。
124
+
125
+ 全能力工具的 A→B 消息场景会根据接收页实际的协议、compatibility 和 createClient 入口选择监听事件;TLV legacy-rtm 接收页监听 `pushchat`,native TLV 接收页监听 `event.direct`。发送页和接收页可以使用不同页面契约,但仍需使用相同 PID、协议和服务端环境。
126
+
127
+ TypeScript 声明也按事件边界区分:`RTMLegacyTlvProcessor` 只接受旧 RTM Push 名称和本地 `CompatibilityError`;`RTMLegacyFpnnProcessor` 接受相同的旧 Push 名称,并保留原生 `ping`。两种 legacy 类型都不会把 raw TLV 名称、未发出的 `pushaudio` 或任意字符串事件放行到编译期。JavaScript 调用这些不支持的 TLV legacy 事件时,SDK 会同步抛出 `RTM_COMPATIBILITY_UNSUPPORTED`,并在该页触发 `CompatibilityError`。
128
+
129
+ ## 支持范围
130
+
131
+ 有等价 TLV route 的连接、用户资料、存储、黑名单、群组/房间、消息、历史、未读/会话、文本检查和翻译方法通过兼容 facade 映射旧结果。方法和 wire URI 逐项见 [RTM API / FPNN / TLV 对照表](PROTOCOL_MIGRATION.md#api-与-wire-名称对照);每个 URI 的 TLV 字段值域见 [TLV Client API 契约](TLV_CONTRACT.md)。服务端是否开通 URI、项目权限和数据语义仍由真实 Gate 决定。
132
+
133
+ 以下 17 个旧公开方法在当前 TLV contract 中没有可用等价能力,兼容层会在本地以 `RTM_COMPATIBILITY_UNSUPPORTED` 明确拒绝:
134
+
135
+ - 文件:`fileToken`、`sendFile`、`sendGroupFile`、`sendRoomFile`。
136
+ - 设备 Push 配置:`addDevice`、`removeDevice`、`addDevicePushOption`、`removeDevicePushOption`、`getDevicePushOption`。
137
+ - 好友:`addFriends`、`deleteFriends`、`getFriends`。
138
+ - 多媒体/内容服务:`profanity`、`imageCheck`、`audioCheck`、`videoCheck`、`speech2Text`。
139
+
140
+ 这些操作不能被 Demo、兼容层或调用方绕过错误改为成功,也不会退回 FPNN。若业务必须保留它们,应继续使用 FPNN,或另行确认 TLV 服务端能力后再扩展 adapter 与测试。
141
+
142
+ ## 错误识别
143
+
144
+ | 场景 | 结果 |
145
+ | --- | --- |
146
+ | Gate 返回错误 | 保留底层错误和真实服务端码;普通请求 Callback 为 `(error, null)`,Promise reject。 |
147
+ | 发送失败 | Callback 为 `({ mid, error }, null)`;Promise reject 外层对象。 |
148
+ | 本地不支持的业务方法 | `RTM_COMPATIBILITY_UNSUPPORTED`;Callback 收到 `(error, null)`,Promise reject;同时在 `client.processor` 发出页面本地 `CompatibilityError`。 |
149
+ | 本地不支持的 Push 名称 | `RTM_COMPATIBILITY_UNSUPPORTED`;`client.processor.on()` 同步抛错,不会注册监听器;同时发出页面本地 `CompatibilityError`。 |
150
+ | 本地结果无法转换 | `RTM_COMPATIBILITY_MAPPING_FAILED`;Callback 收到 `(error, null)`,Promise reject;错误含 `method`、`protocol`、`cause`,并通过 `client.processor` 的 `CompatibilityError` 报告。 |
151
+ | 登录拒绝 | Callback 仍是 `(false, errorCode)`;`client.promises.login()` reject。仅 `accepted === true` 才是登录成功。 |
152
+
153
+ ```js
154
+ client.processor.on('CompatibilityError', error => {
155
+ console.warn(error.code, error.method, error.message);
156
+ });
157
+
158
+ try {
159
+ await client.promises.sendFile(fileType, peerUid, file);
160
+ } catch (error) {
161
+ // 不支持时会在本地拒绝;不能据此判断 Gate 返回了错误。
162
+ console.error(error.code, error.method);
163
+ }
164
+ ```
165
+
166
+ `CompatibilityError` 是 `client.processor` 上的页面本地事件,不是 `ErrorRecorder` 的别名,也不是 Gate 错误。对于业务 API,始终处理该 API 自己的 Callback 或 Promise;只监听这个兼容错误事件会漏掉普通业务请求失败。
167
+
168
+ ## SharedWorker、页面身份和生命周期
169
+
170
+ - `compatibility` 在创建页面 facade 时消费,并在 Worker 初始化前剥离;它不加入 Worker 名称、共享身份或 `clientOptions`。
171
+ - 同 origin、PID、协议、UID、Gate 和其余连接参数一致时,native 与 legacy 页面仍共用同一个 SharedWorker 和底层 RTMClient / WebSocket。Push 只在各页面 facade 上分别转换;不会因兼容模式多建 RTC 连接。
172
+ - `getConnectionInfo()` 报告实际 shared/direct 模式和回退原因。它不表示 Gate 已连接或登录成功。配置不能安全跨 Worker 时,`createClient()` 按当前 SDK 规则回退为本页连接;此时其他页面不会自动共享登录。
173
+ - 工厂返回的是 facade,不保证 `instanceof RTMClient`。依赖 RTMClient 私有字段、修改 Processor 内部实现或直接检查构造器身份的代码需要调整。
174
+ - 组件卸载/单页关闭调用 `destroy()`,只释放当前页面。`bye()` / `close()` 会结束共享 RTC 会话,影响使用同一连接的其他页面。再次打开新页面按 SDK 会话状态复用;Worker 回收或 RTC 会话已结束时需重新登录并重新获取 credential。
175
+ - `processor.on/off/removeEvent/listenerCount` 使用旧事件名并保留页面 Callback 引用。`processor.emit()` 仍是本地事件,不会发网络消息、ACK 或验证 Gate。
176
+
177
+ ## 迁移验收清单
178
+
179
+ 1. 核对实际旧 SDK 来源、版本/commit、内部补丁和被调用 API 清单;确认业务只依赖本文支持范围。
180
+ 2. 替换包引用与创建入口,填写部署方提供的 TLV `wss://.../service/websocket`,显式传 `protocol: 'tlv-v1'` 和 `compatibility: 'legacy-rtm'`。
181
+ 3. 保留业务 Callback/Push 代码后,重点检查发送失败的嵌套错误、`mtime`、历史 tuple、二进制内容及 audio→pushfile 事件变化。
182
+ 4. 页面/组件清理改为 `destroy()`;只有用户要结束所有共享页面会话时才执行 `bye()` / `close()`。
183
+ 5. 在同 origin 中用 native 与 legacy 页面验证共享状态和各自 Push 契约;配置需完全一致。多端口、多浏览器配置文件或不同 UID 不共享。
184
+ 6. 先运行离线兼容测试,再用测试 Gate 验证真实登录、发送/接收、历史/权限和重连;离线 fixture 不代表真实 Gate 已开通。
185
+
186
+ ## 验收建议
187
+
188
+ 先按上面的兼容清单核对旧项目实际使用的 API 和消息字段,再在目标 Gate 环境验证登录、权限、消息投递、历史查询和重连。离线测试无法确认项目权限、服务端配置或真实消息投递;这些结果应在目标环境单独验收。