@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/System.md ADDED
@@ -0,0 +1,49 @@
1
+ # RTM Client Websocket SDK System 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
+ * `addAttrs(attrs, timeout, callback)`: 设置客户端信息, 保存在当前链接中, 客户端可以获取到
12
+ * `attrs`: **(Required | object[string, string])** key-value形式的变量
13
+ * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
14
+ * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
15
+ * `err`: **(Error)**
16
+ * `data`: **(object)**
17
+
18
+ * `getAttrs(timeout, callback)`: 获取客户端信息
19
+ * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
20
+ * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
21
+ * `err`: **(Error)**
22
+ * `data`: **(object[attrs:array[Map])**
23
+ * `Map.login` **(string)** 登录时间, UTC时间戳
24
+ * `Map.my` **(string)** 当前链接的`attrs`
25
+
26
+ * `addDebugLog(msg, attrs, timeout, callback)`: 添加debug日志
27
+ * `msg`: **(Required | string)** 调试信息msg
28
+ * `attrs`: **(Required | string)** 调试信息attrs
29
+ * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
30
+ * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
31
+ * `err`: **(Error)**
32
+ * `data`: **(object)**
33
+
34
+ * `addDevice(apptype, devicetoken, timeout, callback)`: 添加设备, 应用信息
35
+ * `apptype`: **(Required | string)** 应用信息
36
+ * `devicetoken`: **(Required | string)** 设备信息
37
+ * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
38
+ * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
39
+ * `err`: **(Error)**
40
+ * `data`: **(object)**
41
+
42
+ * `removeDevice(devicetoken, timeout, callback)`: 删除设备, 应用信息
43
+ * `devicetoken`: **(Required | string)** 设备信息
44
+ * `timeout`: **(Optional | number)** 超时时间(ms), 默认: `20 * 1000`
45
+ * `callback`: **(Optional | function)** 回调方法, `callback(err, data)`
46
+ * `err`: **(Error)**
47
+ * `data`: **(object)**
48
+
49
+
package/docs/TLV.md ADDED
@@ -0,0 +1,62 @@
1
+ # TLV v1 传输 API
2
+
3
+ TLV v1 使用 MessagePack over WebSocket。公开方法见 [SDK API](USAGE.md),完整 URI 与字段见
4
+ [TLV v1 Client 契约](TLV_CONTRACT.md)。
5
+
6
+ ## 连接接口
7
+
8
+ | 项目 | 规则 |
9
+ | --- | --- |
10
+ | 协议模式 | `protocol: 'tlv-v1'` |
11
+ | 端点 | `tlvEndpoint` 为完整 `ws://` 或 `wss://` URL |
12
+ | WebSocket | 每个 binary message 恰好一个完整 TLV frame |
13
+ | 非浏览器运行时 | 提供 `webSocketFactory(url)`;旧 `fpnn` 不可用 |
14
+ | 鉴权 | `login(uid, credential, callback, timeout)`;仅 `accepted === true` 进入登录态 |
15
+
16
+ ## Frame 接口
17
+
18
+ | 字段 | 规则 |
19
+ | --- | --- |
20
+ | Header | `magic=0xCC`、`version=1`、`flags=0x04`、正整数 little-endian `sequence` |
21
+ | Metadata | 唯一 `mt`,值为 `'0'`、`'1'` 或 `'2'` |
22
+ | Message | 唯一 URI、空 `passThrough`、MessagePack map body |
23
+ | WebSocket body | 仅 binary;不含 TCP length header |
24
+
25
+ | 方向 | `mt` | URI |
26
+ | --- | --- | --- |
27
+ | Client → Gate 请求 | `'1'` | 业务 URI、`control.ping`、`connection.close` |
28
+ | Gate → Client 应答 | `'2'` | 原请求 URI 或 `control.error` |
29
+ | Gate → Client 可靠 Push | `'1'` | `event.direct`、`event.group`、`event.room`、`event.broadcast` |
30
+ | Client → Gate Push ACK | `'2'` | `control.ack` |
31
+ | Gate → Client 控制 Push | `'0'` | `event.kicked`、`event.room_removed` |
32
+
33
+ ## 编码接口
34
+
35
+ - body 必须是 string-keyed MessagePack map;无参数 body 为 `{}`。
36
+ - 整数使用安全 JavaScript 整数或 `RTMConfig.Int64`;不得以十进制字符串替代整数。
37
+ - `payload` 支持 string、MessagePack bin 或 Chat map;按实际 MessagePack 类型读取。
38
+ - `Uint8Array`、`ArrayBuffer`、`Buffer` 和 typed array 编码为 MessagePack bin。
39
+ - `requestMetadata()` 可附加 `trace:string`、`sent_ms:int64`。
40
+
41
+ ## 控制 API
42
+
43
+ | URI | 请求/响应 body | 行为 |
44
+ | --- | --- | --- |
45
+ | `control.ping` | `{}` / `{ts?:int64}` | SDK 空闲心跳;Gate 可在 Answer 中返回时间戳。 |
46
+ | `control.ack` | `{}` | 复用可靠 Push sequence;无需应答。 |
47
+ | `control.error` | `{status:int32, reason:string}` | Gate 请求失败应答。 |
48
+ | `connection.close` | `{}` / `{}` | Gate 应答后关闭连接。 |
49
+
50
+ ## Push 接口
51
+
52
+ | URI | SDK 事件 | ACK |
53
+ | --- | --- | --- |
54
+ | `event.direct` | `TLV_SERVER_PUSH.recvMessage` | 自动 |
55
+ | `event.group` | `TLV_SERVER_PUSH.recvGroupMessage` | 自动 |
56
+ | `event.room` | `TLV_SERVER_PUSH.recvRoomMessage` | 自动 |
57
+ | `event.broadcast` | `TLV_SERVER_PUSH.recvBroadcastMessage` | 自动 |
58
+ | `event.kicked` | `TLV_SERVER_PUSH.kickOut` | 不发送 |
59
+ | `event.room_removed` | `TLV_SERVER_PUSH.kickOutRoom` | 不发送 |
60
+
61
+ 可靠 Push 以 `message_ref` 去重;每次重传仍发送 ACK。协议错误、心跳失败或连接关闭会失败当前
62
+ pending 请求;SDK 不重放结果未知的修改请求。
@@ -0,0 +1,180 @@
1
+ # TLV v1 Client API 契约
2
+
3
+ 本页定义 `RTMClient` 的 TLV v1 URI、请求字段与成功返回字段。公开方法参数见
4
+ [SDK API](USAGE.md),传输规则见 [TLV v1 传输 API](TLV.md)。
5
+
6
+ ## 类型与回调
7
+
8
+ | 标记 | 含义 |
9
+ | --- | --- |
10
+ | `id` / `i64` | `id` 为正整数,`i64` 为 signed int64;超出安全整数范围使用 `RTMConfig.Int64`。 |
11
+ | `i32` | MessagePack integer。 |
12
+ | `str` | UTF-8 string。 |
13
+ | `bin` | MessagePack binary。 |
14
+ | `id[]` | ID 数组;请求是否允许空数组由对应 URI 规定。 |
15
+ | `str-map` | `map<string, string>`。 |
16
+ | `tuple8` | `[cursor_id, sender_or_direction, kind, message_ref, deleted, payload, extra, time_ms]`;`cursor_id` 为不透明 int64 游标,不是 `message_ref`。 |
17
+ | `?` | 可选字段;未标记 `?` 的字段为必填。 |
18
+
19
+ 表中的 `Gate Answer` 是 Gate 的 TLV body;除特别说明的兼容包装外,SDK 将其作为 `data`
20
+ 传给 `callback(err, data)`。`login` 为 `callback(accepted, errorCode)`。所有请求可由
21
+ `requestMetadata` 附加 `trace:str`、`sent_ms:i64`。
22
+
23
+ ## 控制 URI 与 Push
24
+
25
+ | URI | `mt` | body |
26
+ | --- | --- | --- |
27
+ | `control.ping` | `'1'` / `'2'` | request `{}`; Answer `{ts?:i64}` |
28
+ | `control.ack` | `'2'` | `{}` |
29
+ | `control.error` | `'2'` | `{status:i32, reason:str}` |
30
+ | `event.direct` | `'1'` | `recipient, sender, message_ref, kind, payload, extra, time_ms` |
31
+ | `event.group` | `'1'` | `group_ref, sender, message_ref, kind, payload, extra, time_ms` |
32
+ | `event.room` | `'1'` | `room_ref, sender, message_ref, kind, payload, extra, time_ms` |
33
+ | `event.broadcast` | `'1'` | `sender, message_ref, kind, payload, extra, time_ms` |
34
+ | `event.kicked` | `'0'` | `{}` |
35
+ | `event.room_removed` | `'0'` | `{room_ref:id}` |
36
+
37
+ 可靠 Push 自动回复 `control.ack` 并按 `message_ref` 去重;`event.kicked` 与
38
+ `event.room_removed` 不回复 ACK。
39
+
40
+ ## Auth、连接与系统
41
+
42
+ | SDK API | Gate URI | 请求字段 | Gate Answer |
43
+ | --- | --- | --- | --- |
44
+ | `login` | `auth.login` | `project, user, credential, client_ver, auth_sec?, auth_ver?, locale?, props?` | `accepted, telemetry_on?` |
45
+ | `bye` | `connection.close` | 无 | 无 |
46
+ | `getServerTime` | `system.time` | 无 | `server_ms` |
47
+ | `addAttrs` | `connection.set_props` | `props` | 无 |
48
+ | `getAttrs` | `connection.get_props` | 无 | `props` |
49
+ | `addDebugLog` | `system.debug` | `entry, context` | 无 |
50
+
51
+ `auth_sec` 与 `auth_ver` 必须同时存在或同时省略;存在时 `auth_ver` 必须为 `2`。
52
+
53
+ ## 用户、存储与黑名单
54
+
55
+ | SDK API | Gate URI | 请求字段 | Gate Answer |
56
+ | --- | --- | --- | --- |
57
+ | `getOnlineUsers` | `presence.online` | `users` | `online_users` |
58
+ | `setUserInfo` | `user.set_profile` | `public_data?, private_data?` | 无 |
59
+ | `getUserInfo` | `user.get_profile` | 无 | `public_data, private_data` |
60
+ | `getUserOpenInfo` | `user.get_public` | `users` | `profiles` |
61
+ | `setTranslationLanguage` | `user.set_locale` | `locale` | `updated` |
62
+ | `dataGet` | `storage.get` | `slot` | `value` |
63
+ | `dataSet` | `storage.set` | `slot, value` | 无 |
64
+ | `dataDelete` | `storage.delete` | `slot` | 无 |
65
+ | `addBlacks` | `blacklist.add` | `blocked_users` | 无 |
66
+ | `deleteBlacks` | `blacklist.remove` | `blocked_users` | 无 |
67
+ | `getBlacks` | `blacklist.list` | 无 | `blocked_users` |
68
+
69
+ `getOnlineUsers`、`getBlacks` 的 SDK 回调 data 均为 `RTMConfig.Int64[]`,不是 Gate Answer map。
70
+
71
+ ## 群组
72
+
73
+ | SDK API | Gate URI | 请求字段 | Gate Answer |
74
+ | --- | --- | --- | --- |
75
+ | `addGroupMembers` | `group.add` | `group_ref, members` | 无 |
76
+ | `deleteGroupMembers` | `group.remove` | `group_ref, members` | 无 |
77
+ | `getGroupMembers` | `group.members` | `group_ref, with_online?` | `members, active_members?` |
78
+ | `getGroupCount` | `group.count` | `group_ref, with_online?` | `total, active_total?` |
79
+ | `getUserGroups` | `group.joined` | 无 | `group_refs` |
80
+ | `setGroupInfo` | `group.set_profile` | `group_ref, public_data?, private_data?` | 无 |
81
+ | `getGroupInfo` | `group.get_profile` | `group_ref` | `public_data, private_data` |
82
+ | `getGroupOpenInfo` | `group.get_public` | `group_ref` | `public_data` |
83
+ | `getGroupsOpenInfo` | `group.get_public_batch` | `group_refs` | `profiles` |
84
+
85
+ `getUserGroups` 的 SDK 回调 data 为 `RTMConfig.Int64[]`,不是 `{group_refs}`。
86
+
87
+ ## 房间
88
+
89
+ | SDK API | Gate URI | 请求字段 | Gate Answer |
90
+ | --- | --- | --- | --- |
91
+ | `enterRoom` | `room.join` | `room_ref` | 无 |
92
+ | `enterRooms` | `room.join_batch` | `room_refs` | 无 |
93
+ | `leaveRoom` | `room.leave` | `room_ref` | 无 |
94
+ | `getUserRooms` | `room.joined` | 无 | `room_refs` |
95
+ | `getRoomMembers` | `room.members` | `room_ref` | `members` |
96
+ | `getRoomCount` | `room.counts` | `room_refs` | `totals` |
97
+ | `setRoomInfo` / `setRoomProfile` | `room.set_profile` | `room_ref, public_data?, private_data?, label?, avatar?` | 无 |
98
+ | `getRoomInfo` | `room.get_profile` | `room_ref` | `public_data, private_data` |
99
+ | `getRoomOpenInfo` | `room.get_public` | `room_ref` | `public_data` |
100
+ | `getRoomsOpenInfo` | `room.get_public_batch` | `room_refs` | `profiles` |
101
+ | `getUserRoomsAndLastMessage` | `room.last_messages` | `kinds?` | `last_by_room` |
102
+
103
+ `last_by_room` 的 key 为十进制房间 ID,value 为 `tuple8`。
104
+ `getUserRooms` 的 SDK 回调 data 为 `RTMConfig.Int64[]`,不是 `{room_refs}`。
105
+
106
+ ## 消息发送、审核与翻译
107
+
108
+ | SDK API | Gate URI | 请求字段 | Gate Answer |
109
+ | --- | --- | --- | --- |
110
+ | `sendMessage` | `message.send` | `recipient, message_ref, kind, payload, extra, strategyid?, checkParams?` | `message_ref, time_ms` |
111
+ | `sendMessages` | `message.send_batch` | `recipients, message_ref, kind, payload, extra` | `message_ref, time_ms` |
112
+ | `sendGroupMessage` | `message.send_group` | `group_ref, message_ref, kind, payload, extra, strategyid?, checkParams?` | `message_ref, time_ms` |
113
+ | `sendRoomMessage` | `message.send_room` | `room_ref, message_ref, kind, payload, extra, strategyid?, checkParams?` | `message_ref, time_ms` |
114
+ | `textCheck` | `moderation.check` | `payload, strategyId?, checkParams?, zone?` | `decision, filtered, detected_locale, matches?` |
115
+ | `translate` | `translation.run` | `input, to_locale, from_locale?, format, filter_mode` | `detected_locale, resolved_locale, original, translated, from_locale, to_locale, input, output` |
116
+
117
+ `sendMessage`、`sendMessages`、`sendGroupMessage`、`sendRoomMessage` 的 SDK 成功回调为
118
+ `callback(null, {message_ref, payload: {message_ref, time_ms}})`;失败回调为
119
+ `callback({message_ref, error}, null)`。
120
+
121
+ ## 历史、单条消息与撤回
122
+
123
+ 历史分页字段:`reverse, limit, start_ms, end_ms, cursor, kinds?`;返回 `HistoryResult`:
124
+ `size, items, next, first_ms, last_ms`。`items` 的元素为 `tuple8`。
125
+
126
+ | SDK API | Gate URI | 额外请求字段 | Gate Answer |
127
+ | --- | --- | --- | --- |
128
+ | `getP2PMessage` | `history.direct` | `peer` | `HistoryResult` |
129
+ | `getGroupMessage` | `history.group` | `group_ref` | `HistoryResult` |
130
+ | `getRoomMessage` | `history.room` | `room_ref` | `HistoryResult` |
131
+ | `getBroadcastMessage` | `history.broadcast` | 无 | `HistoryResult` |
132
+ | `getP2PMessageByMessageId` | `history.direct_anchor` | `peer, anchor, reverse, limit, start_ms, end_ms, kinds?` | `HistoryResult` |
133
+ | `getGroupMessageByMessageId` | `history.group_anchor` | `group_ref, anchor, reverse, limit, start_ms, end_ms, kinds?` | `HistoryResult` |
134
+ | `getRoomMessageByMessageId` | `history.room_anchor` | `room_ref, anchor, reverse, limit, start_ms, end_ms, kinds?` | `HistoryResult` |
135
+ | `getBroadcastMessageByMessageId` | `history.broadcast_anchor` | `anchor, reverse, limit, start_ms, end_ms, kinds?` | `HistoryResult` |
136
+ | `getP2PMessageCount` | `history.direct_count` | `peer, start_ms, end_ms, kinds?` | `total` |
137
+ | `getGroupMessageCount` | `history.group_count` | `group_ref, start_ms, end_ms, kinds?` | `total` |
138
+ | `getRoomMessageCount` | `history.room_count` | `room_ref, start_ms, end_ms, kinds?` | `total` |
139
+ | `getBroadcastMessageCount` | `history.broadcast_count` | `start_ms, end_ms, kinds?` | `total` |
140
+ | `getMessage` | `message.get` | `sender, message_ref, target_ref, channel` | `sequence, message_ref, sender, kind, payload, extra, time_ms` |
141
+ | `deleteMessage` | `message.revoke` | `sender, message_ref, target_ref, channel` | 无 |
142
+
143
+ `getP2PChat`、`getGroupChat`、`getRoomChat`、`getBroadcastChat` 复用相应 history URI;
144
+ `getChat`、`deleteChat` 分别复用 `message.get`、`message.revoke`。
145
+
146
+ ## 未读、会话与会话列表
147
+
148
+ | SDK API | Gate URI | 请求字段 | Gate Answer |
149
+ | --- | --- | --- | --- |
150
+ | `getUnreadMessage` | `unread.summary` | `mark_read, with_logout?` | `peers, group_refs, logout_sec?` |
151
+ | `getSession` | `session.list` | 无 | `peers, group_refs` |
152
+ | `cleanUnreadMessage` | `unread.clear` | 无 | 无 |
153
+ | `setSessionRead` | `session.read` | `channel, target_ref, through` | 无 |
154
+ | `getP2PUnreadMessageNum` | `unread.direct` | `peers, since_ms?, kinds?` | `counts, times` |
155
+ | `getGroupUnreadMessageNum` | `unread.group` | `group_refs, since_ms?, kinds?` | `counts, times` |
156
+ | `removeSession` | `session.remove` | `peer, local_only` | 无 |
157
+ | `getP2PConversationList` | `conversation.direct` | `since_ms?, kinds?` | `peers, badges, last_items` |
158
+ | `getP2PUnreadConversationList` | `conversation.direct_unread` | `since_ms?, kinds?` | `peers, badges, last_items` |
159
+ | `getGroupConversationList` | `conversation.group` | `since_ms?, kinds?` | `group_refs, badges, last_items` |
160
+ | `getGroupUnreadConversationList` | `conversation.group_unread` | `since_ms?, kinds?` | `group_refs, badges, last_items` |
161
+ | `getUnreadConversationList` | `conversation.unread` | `mark_read, since_ms?, kinds?` | `group_refs, group_badges, group_last, peers, peer_badges, peer_last` |
162
+
163
+ ## 状态
164
+
165
+ | status | 接口含义 |
166
+ | ---: | --- |
167
+ | `10009` / `10010` | 字段缺失或类型不匹配。 |
168
+ | `200010` | 限流。 |
169
+ | `200020` | TLV 未开放能力。 |
170
+ | `200021` | 权限不足。 |
171
+ | `200022` | 未鉴权。 |
172
+ | `200023` | 重复鉴权。 |
173
+ | `200024` / `200027` | credential 拒绝或失效。 |
174
+ | `200030` | payload 或 extra 超限。 |
175
+ | `200032` / `200033` | 批量或空参数非法。 |
176
+ | `200034` | 契约字段、类型或范围非法。 |
177
+ | `200040` / `200041` | 房间或群组成员状态不满足。 |
178
+ | `200053` | `message_ref` 重复。 |
179
+ | `200070` | `anchor` 不存在。 |
180
+ | `200999` | 连接、超时或内部错误。 |