@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/README.md ADDED
@@ -0,0 +1,113 @@
1
+ # @cg-devcenter/rtc-fpnn-webjs-sdk
2
+
3
+ RTC WebSocket Client SDK。新接入建议使用 `protocol: 'tlv-v1'`;`fpnn` 用于兼容已有浏览器接入。完整接入说明和 API 参数见 [USAGE.md](docs/USAGE.md)。
4
+
5
+ ## 安装
6
+
7
+ ```bash
8
+ npm install @cg-devcenter/rtc-fpnn-webjs-sdk@latest
9
+ ```
10
+
11
+ 包根 ESM 入口和 `/vite-plugin` 已包含在 npm `latest` 中。普通业务项目和三个框架 Demo 直接从 npm 安装 SDK;HTML Demo 使用仓库构建出的 UMD 文件。各环境的接入方法见下方接入指南。
12
+
13
+ 本地构建版本由根目录 `package.json` 管理;框架 Demo 从 npm 安装已发布的版本。通过 `@latest` 安装时,npm 会选择 registry 当前发布的最新版本。
14
+
15
+ ## 本地构建
16
+
17
+ 从源码构建或打包 SDK 需要 Node.js 18 或更高版本(`esbuild` 的构建工具要求);这是仓库维护和发包环境要求,不会提高浏览器 SDK 使用方的 Node.js 运行时要求。运行 `npm run build` 会生成 UMD、SharedWorker、ESM、Vite/Webpack 插件和类型声明产物。
18
+
19
+ 浏览器可加载 `dist/rtm.min.js` 并从 `window.rtm` 使用;CommonJS:
20
+
21
+ ```js
22
+ const rtm = require('@cg-devcenter/rtc-fpnn-webjs-sdk');
23
+ ```
24
+
25
+ Node.js 使用 TLV v1 时,需自行提供 `webSocketFactory(url)`。SDK 不携带 Node WebSocket 实现。`fpnn` 和 `RTMSharedWorkerClient` 仅适用于浏览器。
26
+
27
+ ## Quick Start
28
+
29
+ ### 默认共享入口
30
+
31
+ `createClient()` 在浏览器支持 SharedWorker 且配置可安全传递时默认共享连接;浏览器不支持或配置含页面运行时值时自动使用当前页面的独立连接。`client.getConnectionInfo()` 可报告所选模式和回退原因。省略 `protocol` 时默认使用 FPNN,以兼容旧 `RTMClient` 接入。新项目使用 TLV 时请显式设置 `protocol: 'tlv-v1'`。支持共享的环境中,SDK 自动按 PID、协议、UID 和 Gate 地址隔离会话;同一环境的页面自动复用,业务无需配置 Worker 名称或路径。UID 可直接从 `login()` 获取。
32
+
33
+ ```js
34
+ const client = rtm.createClient({ protocol: 'tlv-v1', pid, tlvEndpoint: endpoint });
35
+ client.processor.on(rtm.RTMConfig.TLV_SERVER_PUSH.recvMessage, renderMessage);
36
+ await client.promises.login(uid, credential); // 同 UID 已登录时 credential 可省略
37
+ await client.promises.sendChat(peerUid, 'hello', '{}');
38
+ // 离开页面只释放本页,其他页面继续收发。
39
+ client.destroy();
40
+ ```
41
+
42
+ 片段中的 `rtm`、项目参数、credential 和 `renderMessage` 由应用提供;完整流程和能力边界见 [默认共享接入](docs/USAGE.md#默认共享接入)。从旧 `new RTMClient()` 迁移且继续使用 FPNN 时,可将构造器替换为 `createClient()` 并沿用 `endpoint` 配置;工厂默认协议为 FPNN。在浏览器支持 SharedWorker 且配置可传递时自动共享;配置不可传递或浏览器不支持时自动使用独立连接,并可通过 `client.getConnectionInfo()` 查看实际模式和回退原因。显式设置 `sharing: false` 也会选择独立连接。现代 ESM 项目从包根导入;Vite 项目另在配置中注册 `/vite-plugin`,避免开发依赖预构建改写 SDK 的 Worker URL;Worker 资源由 Vite 构建输出。详见 [接入指南](docs/USAGE.md)。
43
+
44
+ ### 原有单连接入口
45
+
46
+ 从业务服务端取得当前 UID 的 credential,然后连接 Gate。credential 必须由服务端签发;项目 SecretKey 不要放进浏览器。
47
+
48
+ ```js
49
+ async function startChat(rtm, { pid, endpoint, uid, peerUid, credential }) {
50
+ const client = new rtm.RTMClient({
51
+ protocol: 'tlv-v1',
52
+ pid,
53
+ tlvEndpoint: endpoint,
54
+ });
55
+ let loggedIn = false;
56
+
57
+ client.processor.on(rtm.RTMConfig.TLV_SERVER_PUSH.recvMessage, (event) => {
58
+ console.log('Direct message', event);
59
+ });
60
+
61
+ try {
62
+ await client.promises.login(uid, credential);
63
+ loggedIn = true;
64
+ return await client.promises.sendChat(peerUid, 'hello', '{}');
65
+ } finally {
66
+ try {
67
+ if (loggedIn) await client.promises.bye(5000);
68
+ } finally {
69
+ try { client.close(); } finally { client.destroy(); }
70
+ }
71
+ }
72
+ }
73
+ ```
74
+
75
+ 此片段假定调用方已加载 SDK,并取得 `pid`、完整 WebSocket endpoint、`uid`、`peerUid` 和服务端签发的 `credential`。带 credential 获取方式、错误处理、关闭流程、参数和返回值的完整示例见 [SDK 接入指南](docs/USAGE.md#2-快速开始登录收-push发消息关闭)。
76
+
77
+ ## 同 UID 多窗口
78
+
79
+ 需要同一浏览器内多个同源页面共用一个 UID 的 RTC 登录和 WebSocket 时,新接入推荐使用 SDK 的 `createClient()` 默认共享入口。支持 SharedWorker 时,SDK 按 PID、协议、UID 和 Gate 地址确定共享会话,业务代码无需维护 Worker 配置;普通浏览器部署时将 `rtm.min.js` 和 `rtm.shared-worker.js` 放在同一同源目录即可。浏览器不支持 SharedWorker 时,`createClient()` 自动改用当前页面的独立连接,各页面不共享登录态。首次登录需要 credential;同 UID 后续页面在支持共享的环境中复用会话。完整说明见 [默认共享接入](docs/USAGE.md#默认共享接入)。
80
+
81
+ Vite 项目从 `@cg-devcenter/rtc-fpnn-webjs-sdk` 导入 ESM 入口,并在 Vite 配置中增加一次 `rtmSdkVitePlugin()`;Worker 由构建流程打包,业务无需填写路径。旧 `/vite` 导入仍保留兼容。若使用底层 `RTMSharedWorkerClient` 构造器,可通过 `uid` 自动生成 Worker 名称,或显式传入 `workerName`;`createClient()` 会按登录 UID 自动绑定,不要求手动设置名称。最后一个页面 detach 后默认 5 秒关闭共享连接。
82
+
83
+ 常规接入不需要传 `workerUrl`:普通 HTML 将 `rtm.min.js` 与 `rtm.shared-worker.js` 放在同源同目录;Vite 项目在开发配置中注册上述插件;Webpack 4 项目配置 SDK 的 `/webpack4` 插件。Vue、React 或普通 JS 使用相同的 SDK API,Worker 资源由对应的构建方式定位和输出。只有自定义 Worker 部署位置时,才需要用 `workerUrl` 覆盖默认解析结果。详见[接入指南的 SharedWorker 章节](docs/USAGE.md#4-同-uid-多窗口sharedworker)。
84
+
85
+ 如果直接从 unpkg 或 jsDelivr 加载 UMD,默认 Worker URL 会指向 CDN,无法用于页面的 SharedWorker。请把同版本 Worker 放到应用同源目录并传入 `workerUrl`,或设置 `sharing: false`。详见[CDN 与 Worker 同源要求](docs/USAGE.md#引用与运行环境)。
86
+
87
+ `createClient()` 和直接构造 `RTMSharedWorkerClient` 都默认使用 FPNN;只有显式设置 `protocol: 'tlv-v1'` 才使用 TLV。登录共享和会话路由沿用同一套业务 API。用法与限制见 [FPNN 多窗口接入](docs/USAGE.md#fpnn-多窗口接入)。
88
+
89
+ SharedWorker 共享底层 SDK 实例和登录状态,业务 API 自动转发给 `RTMClient`,包括 FPNN 文件发送。Worker 原样广播 SDK 事件;`conversation` / `setConversation()` 只在页面端执行可选筛选。协议校验、上传、重连、ACK 和去重均由底层 SDK 处理。
90
+
91
+ 仓库的演示页面可用以下命令启动:
92
+
93
+ ```bash
94
+ npm run build
95
+ npm run demo:shared-worker
96
+ ```
97
+
98
+ HTML/JavaScript、Vue 3、Vue 2.7 和 React 的发送台与收件箱 Demo 见源码仓库 `examples/README.md`(仅源码仓库,不包含在 npm 包中)。该指南列出各框架的 SDK import、Vite 插件和启动方式。四种页面覆盖相同的发送账号、credential、收件箱、历史、Push 路由、回复、重试和本地模拟流程;Vue 3、Vue 2 与 React 共用同一框架适配层、RTC 工作流和样式,HTML 继续共用底层配置与控制器。Demo 不复制 SDK 的 SharedWorker 连接、登录态复用或 Push 分发逻辑。窗口内的消息列表、草稿和未读展示仍属于页面状态,不会由 SDK 跨窗口同步。详细职责见 `examples/shared-worker-demo/README.md`(仅源码仓库)。
99
+
100
+ ## TLV v1 最小接入 Demo
101
+
102
+ 需要在浏览器里手动验证普通 `RTMClient` 接入时,在仓库根目录运行 `npm run build` 后执行 `npm run demo:tlv-basic`,再打开 `http://127.0.0.1:4174`。Demo 使用本机静态服务器;PID、WebSocket endpoint、UID 和服务端签发的 credential 由接入者填写,不会保存到浏览器存储。详见 `examples/tlv-basic-demo/README.md`(仅源码仓库)。
103
+
104
+ ## 文档
105
+
106
+ - [接入指南与 API 参数](docs/USAGE.md)
107
+ - [从 GitHub 上游 SDK 迁移:新增 API、签名变化与兼容差异](docs/RTM_MIGRATION.md)
108
+ - [保留旧 RTM API 并迁移到 TLV:兼容层接入与边界](docs/LEGACY_RTM_TLV_COMPATIBILITY.md)
109
+ - [FPNN 与 TLV v1 迁移对照](docs/PROTOCOL_MIGRATION.md)
110
+ - [能力总览与典型业务流程](docs/CAPABILITIES.md)
111
+ - [TLV v1 URI、请求字段与返回值](docs/TLV_CONTRACT.md)
112
+ - [TLV v1 传输规则](docs/TLV.md)
113
+ - [TypeScript 声明](dist/rtm.d.ts)
package/dist/rtm.d.cts ADDED
@@ -0,0 +1,3 @@
1
+ import rtm = require('./rtm');
2
+
3
+ export = rtm;
package/dist/rtm.d.mts ADDED
@@ -0,0 +1,59 @@
1
+ import rtm = require('./rtm');
2
+
3
+ declare const sdk: typeof rtm;
4
+
5
+ export default sdk;
6
+ export type RTMProtocol = rtm.RTMProtocol;
7
+ export type RTMCompatibility = rtm.RTMCompatibility;
8
+ export type RTMCompatibilityError = rtm.RTMCompatibilityError;
9
+ export type RTMId = rtm.RTMId;
10
+ export type RTMLegacyMessagePayload = rtm.RTMLegacyMessagePayload;
11
+ export type RTMLegacyTlvMessagePayload = rtm.RTMLegacyTlvMessagePayload;
12
+ export type RTMLegacySendResult = rtm.RTMLegacySendResult;
13
+ export type RTMLegacySendError = rtm.RTMLegacySendError;
14
+ export type RTMLegacyHistoryMessage = rtm.RTMLegacyHistoryMessage;
15
+ export type RTMLegacyHistoryResponse = rtm.RTMLegacyHistoryResponse;
16
+ export type RTMLegacyPushMessage = rtm.RTMLegacyPushMessage;
17
+ export type RTMLoginPromiseResult = rtm.RTMLoginPromiseResult;
18
+ export type RTMPromiseApi = rtm.RTMPromiseApi;
19
+ export type RTMSharedWorkerPromiseApi = rtm.RTMSharedWorkerPromiseApi;
20
+ export type RTMDefaultPromiseApi = rtm.RTMDefaultPromiseApi;
21
+ export type RTMRegressiveStrategy = rtm.RTMRegressiveStrategy;
22
+ export type RTMClientBaseOptions = rtm.RTMClientBaseOptions;
23
+ export type RTMClientOptions = rtm.RTMClientOptions;
24
+ export type RTMSharedWorkerBaseClientOptions = rtm.RTMSharedWorkerBaseClientOptions;
25
+ export type RTMSharedWorkerClientOptions = rtm.RTMSharedWorkerClientOptions;
26
+ export type RTMConversationType = rtm.RTMConversationType;
27
+ export type RTMConversation = rtm.RTMConversation;
28
+ export type RTMSharedWorkerOptions = rtm.RTMSharedWorkerOptions;
29
+ export type RTMSharedCreateClientOptions = rtm.RTMSharedCreateClientOptions;
30
+ export type RTMIndependentCreateClientOptions = rtm.RTMIndependentCreateClientOptions;
31
+ export type RTMCreateClientOptions = rtm.RTMCreateClientOptions;
32
+ export type RTMFactoryCompatibilityOptions = rtm.RTMFactoryCompatibilityOptions;
33
+ export type RTMConnectionInfo = rtm.RTMConnectionInfo;
34
+ export type RTMConnectionInfoProvider = rtm.RTMConnectionInfoProvider;
35
+ export type RTMDefaultClient = rtm.RTMDefaultClient;
36
+ export type RTMLegacyPromiseApi = rtm.RTMLegacyPromiseApi;
37
+ export type RTMLegacyFpnnPromiseApi = rtm.RTMLegacyFpnnPromiseApi;
38
+ export type RTMLegacyProcessor = rtm.RTMLegacyProcessor;
39
+ export type RTMLegacyTlvProcessor = rtm.RTMLegacyTlvProcessor;
40
+ export type RTMLegacyFpnnProcessor = rtm.RTMLegacyFpnnProcessor;
41
+ export type RTMLegacyDefaultClient = rtm.RTMLegacyDefaultClient;
42
+ export type RTMLegacyFpnnDefaultClient = rtm.RTMLegacyFpnnDefaultClient;
43
+ export type RTMSharedSessionSnapshot = rtm.RTMSharedSessionSnapshot;
44
+ export type RTMSharedLoginResult = rtm.RTMSharedLoginResult;
45
+ export type RTMSharedWorkerIdentity = rtm.RTMSharedWorkerIdentity;
46
+ export type RTMClient = rtm.RTMClient;
47
+ export type RTMSharedWorkerClient = rtm.RTMSharedWorkerClient;
48
+ export type RTMConfig = rtm.RTMConfig;
49
+ export type RTMProcessor = rtm.RTMProcessor;
50
+ export type TLVCodec = rtm.TLVCodec;
51
+ export type TLVWebSocketClient = rtm.TLVWebSocketClient;
52
+ export const RTMClient: typeof rtm.RTMClient;
53
+ export const createClient: typeof rtm.createClient;
54
+ export const RTMSharedWorkerClient: typeof rtm.RTMSharedWorkerClient;
55
+ export const RTMConfig: typeof rtm.RTMConfig;
56
+ export const RTMProcessor: typeof rtm.RTMProcessor;
57
+ export const TLVCodec: typeof rtm.TLVCodec;
58
+ export const TLVWebSocketClient: typeof rtm.TLVWebSocketClient;
59
+ export const createSharedWorkerName: typeof rtm.createSharedWorkerName;