@cg-devcenter/rtc-fpnn-webjs-sdk 1.0.0-cg.2 → 1.0.0-cg.3

package/README.md

@@ -1,61 +1,82 @@
 # @cg-devcenter/rtc-fpnn-webjs-sdk
 
-RTC WebSocket Client SDK。新接入使用 `tlv-v1`；`fpnn` 仅保留浏览器兼容能力。
+RTC WebSocket Client SDK。新接入建议使用 `protocol: 'tlv-v1'`；`fpnn` 用于兼容已有浏览器接入。完整接入说明和 API 参数见 [USAGE.md](docs/USAGE.md)。
 
-## 模块导出
+## 安装
 
-- `RTMClient`
-- `RTMConfig`
-- `RTMProcessor`
-- `TLVCodec`
-- `TLVWebSocketClient`
+```bash
+npm install @cg-devcenter/rtc-fpnn-webjs-sdk@1.0.0-cg.3
+```
 
-## 客户端构造
+本文档中的 Promise API、`RTMSharedWorkerClient` 和 Vite 入口从 `1.0.0-cg.3` 起提供；此前发布的 `1.0.0-cg.2` 不包含这些能力。若 `.3` 尚未发布到 npm，可让测试项目安装本地 tarball：`npm install ./cg-devcenter-rtc-fpnn-webjs-sdk-1.0.0-cg.3.tgz`。
 
-`new rtm.RTMClient(options)`
+浏览器可加载 `dist/rtm.min.js` 并从 `window.rtm` 使用；CommonJS：
 
-| 参数 | 类型 | TLV v1 规则 |
-| --- | --- | --- |
-| `pid` | `number` | 必填。 |
-| `protocol` | `'tlv-v1' \| 'fpnn'` | 新接入为 `'tlv-v1'`。 |
-| `tlvEndpoint` | `string` | 必填完整 WebSocket URL。 |
-| `autoReconnect` | `boolean` | 缺省为 `true`。 |
-| `connectionTimeout` | `number` | 毫秒。 |
-| `requestMetadata` | `() => Record<string, unknown>` | 可返回 `trace`、`sent_ms`。 |
-| `webSocketFactory` | `(url) => RTMWebSocket` | 无全局 `WebSocket` 时必填。 |
-| `locale` | `string` | 映射为 `auth.login.locale`。 |
-| `clientVersion` | `string` | 映射为 `auth.login.client_ver`。 |
+```js
+const rtm = require('@cg-devcenter/rtc-fpnn-webjs-sdk');
+```
 
-`fpnn` 仅支持浏览器。TLV credential 由业务服务端签发，项目密钥不属于客户端参数。
+Node.js 使用 TLV v1 时，需自行提供 `webSocketFactory(url)`。SDK 不携带 Node WebSocket 实现。`fpnn` 和 `RTMSharedWorkerClient` 仅适用于浏览器。
 
-## 生命周期 API
+## Quick Start
 
-| API | 回调/结果 |
-| --- | --- |
-| `login(uid, credential, callback, timeout)` | `callback(accepted, errorCode)` |
-| `bye()` | 发送 `connection.close`。 |
-| `close()` | 主动关闭。 |
-| `startAutoReconnect()` | 关闭当前连接后重新登录。 |
-| `destroy()` | 释放客户端资源。 |
-| `getServerTime(timeout, callback)` | `callback(err, data)` |
+从业务服务端取得当前 UID 的 credential，然后连接 Gate。credential 必须由服务端签发；项目 SecretKey 不要放进浏览器。
 
-`uid`、消息 ID、群 ID、房间 ID 和时间游标超出安全整数范围时使用 `RTMConfig.Int64`。
+```js
+async function startChat(rtm, { pid, endpoint, uid, peerUid, credential }) {
+  const client = new rtm.RTMClient({
+    protocol: 'tlv-v1',
+    pid,
+    tlvEndpoint: endpoint,
+  });
+  let loggedIn = false;
 
-## Push API
+  client.processor.on(rtm.RTMConfig.TLV_SERVER_PUSH.recvMessage, (event) => {
+    console.log('Direct message', event);
+  });
 
-通过 `client.processor.on(name, callback)` 注册：
+  try {
+    await client.promises.login(uid, credential);
+    loggedIn = true;
+    return await client.promises.sendChat(peerUid, 'hello', '{}');
+  } finally {
+    try {
+      if (loggedIn) await client.promises.bye(5000);
+    } finally {
+      client.destroy();
+    }
+  }
+}
+```
 
-- `RTMConfig.TLV_SERVER_PUSH.recvMessage`：`event.direct`
-- `RTMConfig.TLV_SERVER_PUSH.recvGroupMessage`：`event.group`
-- `RTMConfig.TLV_SERVER_PUSH.recvRoomMessage`：`event.room`
-- `RTMConfig.TLV_SERVER_PUSH.recvBroadcastMessage`：`event.broadcast`
-- `RTMConfig.TLV_SERVER_PUSH.kickOut`：`event.kicked`
-- `RTMConfig.TLV_SERVER_PUSH.kickOutRoom`：`event.room_removed`
+此片段假定调用方已加载 SDK，并取得 `pid`、完整 WebSocket endpoint、`uid`、`peerUid` 和服务端签发的 `credential`。带 credential 获取方式、错误处理、关闭流程、参数和返回值的完整示例见 [SDK 接入指南](docs/USAGE.md#2-快速开始登录收-push发消息关闭)。
 
-可靠消息 Push 由 SDK 自动 ACK 并按 `message_ref` 去重。
+## 同 UID 多窗口
 
-## API 文档
+需要同一浏览器内多个同源页面共用一个 UID 的 RTC 登录和 WebSocket 时，使用 SDK 的 `RTMSharedWorkerClient`。SDK 默认从主 SDK 脚本旁自动定位 `rtm.shared-worker.js`，业务代码无需维护 `workerUrl`；部署时将两个文件放在同一同源目录即可。首次登录需要 credential；同 UID 后续页面复用共享会话。部署和 Push 路由示例见 [SharedWorker 接入说明](docs/USAGE.md#4-同-uid-多窗口sharedworker)。
 
-- [公开方法与参数](docs/USAGE.md)
-- [TLV v1 wire 契约](docs/TLV_CONTRACT.md)
+Vite 项目应从 `@cg-devcenter/rtc-fpnn-webjs-sdk/vite` 导入 ESM 入口，由 SDK 自动打包和配置 Worker 文件；传入 `uid` 可自动生成稳定的 Worker 名称。多账号应用应传 `uid` 或显式 `workerName`，避免多个账号共用默认名称。最后一个页面 detach 后默认 5 秒关闭共享连接。
+
+仓库的演示页面可用以下命令启动：
+
+```bash
+npm run build
+npm run demo:shared-worker
+```
+
+发送台和收件箱 demo 地址、真实 Gate 配置方式见 [Demo 使用说明](examples/shared-worker-demo/README.md)。
+
+另有使用 Vue 3、Vite 和 npm 包导入方式的同功能示例，SDK 尚未发布时通过 yalc 本地安装和验证：[Vue 3 SharedWorker Demo](examples/vue3-shared-worker-demo/README.md)。
+
+## TLV v1 最小接入 Demo
+
+需要在浏览器里手动验证普通 `RTMClient` 接入时，在仓库根目录运行 `npm run build` 后执行 `npm run demo:tlv-basic`，再打开 `http://127.0.0.1:4174`。Demo 使用本机静态服务器；PID、WebSocket endpoint、UID 和服务端签发的 credential 由接入者填写，不会保存到浏览器存储。详见 [Demo 使用说明](examples/tlv-basic-demo/README.md)。
+
+## 文档
+
+- [接入指南与 API 参数](docs/USAGE.md)
+- [能力总览与典型业务流程](docs/CAPABILITIES.md)
+- [TLV v1 URI、请求字段与返回值](docs/TLV_CONTRACT.md)
 - [TLV v1 传输规则](docs/TLV.md)
+- [在线 Gate 验证](docs/TLV_LIVE_E2E_TEST.md)
+- [TypeScript 声明](dist/rtm.d.ts)

package/dist/rtm.d.ts

@@ -2,6 +2,34 @@ export as namespace rtm;
 
 declare namespace rtm {
     type RTMProtocol = 'fpnn' | 'tlv-v1';
+    export type RTMId = string | number | { toString(): string };
+
+    export interface RTMLoginPromiseResult {
+        accepted: true;
+        errorCode: number;
+    }
+
+    type RTMPromiseExcludedMethod = 'close' | 'destroy' | 'emit' | 'off' | 'on'
+        | 'removeEvent' | 'startAutoReconnect' | 'promises' | 'processor';
+
+    /** Promise versions of callback-based RTM requests. Parameters keep the original order, without callback. */
+    export type RTMPromiseApi = {
+        [Method in Exclude<keyof RTMClient, RTMPromiseExcludedMethod>]:
+            RTMClient[Method] extends (...args: any[]) => any ? (...args: any[]) => Promise<any> : never;
+    } & {
+        login(uid: RTMId, credential: string, timeout?: number): Promise<RTMLoginPromiseResult>;
+        bye(timeout?: number): Promise<any>;
+        sendChat(to: RTMId, msg: string | ArrayBuffer | Uint8Array, attrs?: string, mid?: RTMId, timeout?: number): Promise<any>;
+        sendGroupChat(gid: RTMId, msg: string | ArrayBuffer | Uint8Array, attrs?: string, mid?: RTMId, timeout?: number): Promise<any>;
+        sendRoomChat(rid: RTMId, msg: string | ArrayBuffer | Uint8Array, attrs?: string, mid?: RTMId, timeout?: number): Promise<any>;
+        getP2PMessage(ouid: RTMId, desc?: boolean, num?: number, begin?: RTMId, end?: RTMId, lastid?: RTMId, mtypes?: number[], timeout?: number): Promise<any>;
+        getGroupMessage(gid: RTMId, desc?: boolean, num?: number, begin?: RTMId, end?: RTMId, lastid?: RTMId, mtypes?: number[], timeout?: number): Promise<any>;
+        getRoomMessage(rid: RTMId, desc?: boolean, num?: number, begin?: RTMId, end?: RTMId, lastid?: RTMId, mtypes?: number[], timeout?: number): Promise<any>;
+        getSession(timeout?: number): Promise<any>;
+        getUnreadMessage(clear?: boolean, withLogout?: boolean, timeout?: number): Promise<any>;
+    };
+
+    export type RTMSharedWorkerPromiseApi = RTMPromiseApi;
 
     interface RTMRegressiveStrategy {
         startConnectFailedCount: number;
@@ -33,7 +61,7 @@ declare namespace rtm {
         clientVersion?: string;
         authSec?: number;
         authVer?: 2;
-        requestMetadata?: () => Record<string, unknown>;
+        requestMetadata?: Record<string, unknown> | (() => Record<string, unknown>);
         requestMetadataProvider?: () => Record<string, unknown>;
         webSocketFactory?: (url: string) => RTMWebSocket;
         attrs?: Record<string, string>;
@@ -46,6 +74,8 @@ declare namespace rtm {
 
     export class RTMClient {
         constructor(options: RTMClientOptions);
+        /** Promise facade for callback-based business request methods. */
+        readonly promises: RTMPromiseApi;
         processor;
         login(uid, token, callback, timeout);
         destroy();
@@ -75,7 +105,8 @@ declare namespace rtm {
         fileToken(cmd, tos, to, rid, gid, timeout, callback);
         close();
         startAutoReconnect();
-        bye();
+        bye(callback?: (err?: Error | null, data?: any) => void): void;
+        bye(timeout?: number, callback?: (err?: Error | null, data?: any) => void): void;
         addAttrs(attrs, timeout, callback);
         getAttrs(timeout, callback);
         addDebugLog(msg, attrs, timeout, callback);
@@ -157,6 +188,114 @@ declare namespace rtm {
         removeEvent();
     }
 
+    export interface RTMSharedWorkerClientOptions {
+        pid: number;
+        /** SharedWorker supports the TLV transport only. */
+        protocol?: 'tlv-v1';
+        /** Required full ws:// or wss:// WebSocket URL. */
+        tlvEndpoint: string;
+        autoReconnect?: boolean;
+        connectionTimeout?: number;
+        requestTimeout?: number;
+        /** Static TLV metadata; only trace and sent_ms are sent on the wire. */
+        requestMetadata?: Record<string, unknown>;
+        locale?: string;
+        clientVersion?: string;
+        authSec?: number;
+        authVer?: 2;
+        attrs?: Record<string, string>;
+        tlvHeartbeatIdleMs?: number;
+        tlvHeartbeatTimeoutMs?: number;
+        pushDedupTtlMs?: number;
+        regressiveStrategy?: RTMRegressiveStrategy;
+    }
+
+    export type RTMConversationType = 'direct' | 'group' | 'room';
+
+    export interface RTMConversation {
+        type: RTMConversationType;
+        /** Use a decimal string for IDs larger than Number.MAX_SAFE_INTEGER. */
+        id: string | number | { toString(): string };
+    }
+
+    export interface RTMSharedWorkerOptions {
+        /** Optional same-origin Worker URL. The classic entry defaults beside its script; the Vite entry bundles this resource automatically. */
+        workerUrl?: string;
+        /** Explicit stable name. When omitted and uid is provided, the SDK derives one from pid, uid, endpoint, and workerNamespace. */
+        workerName?: string;
+        /** UID used only to derive workerName when workerName is omitted; it does not log in automatically. */
+        uid?: RTMId;
+        /** Optional application/environment scope included in the derived workerName. */
+        workerNamespace?: string;
+        /** Maximum time to wait for the SharedWorker init response; defaults to 10000 ms. */
+        readyTimeout?: number;
+        /** Close and release the RTC session after the last page detaches; defaults to 5000 ms. Use 0 to close immediately. All tabs sharing a Worker must use the same value. */
+        idleShutdownTimeout?: number;
+        /** Structured-cloneable options supported by the SharedWorker TLV transport. */
+        clientOptions: RTMSharedWorkerClientOptions;
+        /** Optional route for this page. When omitted, this page receives all conversation Push events. */
+        conversation?: RTMConversation | null;
+    }
+
+    export interface RTMSharedSessionSnapshot {
+        status: 'idle' | 'connecting' | 'authenticated';
+        /** Decimal UID string for the shared session; null while idle. */
+        uid: string | null;
+    }
+
+    export interface RTMSharedLoginResult {
+        accepted: boolean;
+        errorCode: number;
+        /** True when this call reused an authenticated session or joined its login attempt. */
+        reused: boolean;
+        /** Decimal UID of the resulting or conflicting shared session. */
+        uid: string | null;
+    }
+
+    interface RTMSharedProcessor {
+        on(type: string, callback: (...args: any[]) => void): this;
+        off(type: string, callback?: (...args: any[]) => void): this;
+        removeEvent(type?: string, callback?: (...args: any[]) => void): this;
+    }
+
+    export class RTMSharedWorkerClient {
+        constructor(options: RTMSharedWorkerOptions);
+        /** Creates a stable name for the same project, UID, endpoint, and optional application/environment namespace. */
+        static createWorkerName(identity: RTMSharedWorkerIdentity): string;
+        /** Promise facade for callback-based business request methods. */
+        readonly promises: RTMSharedWorkerPromiseApi;
+        processor: RTMSharedProcessor;
+        /** Resolves with the session snapshot after this page attaches to the Worker. */
+        whenReady(): Promise<RTMSharedSessionSnapshot>;
+        /** Returns the latest session snapshot observed by this page. */
+        getSharedSession(): RTMSharedSessionSnapshot;
+        /** Reuses/joins a same-UID login; credential is required only when the shared session is idle. */
+        loginIfNeeded(uid: string | number | { toString(): string }, credential?: string, timeout?: number): Promise<RTMSharedLoginResult>;
+        /** Receives the current snapshot on ready and whenever a shared tab's login state changes. */
+        on(type: 'SharedWorkerReady' | 'SharedSessionState', callback: (session: RTMSharedSessionSnapshot) => void): this;
+        on(type: string, callback: (...args: any[]) => void): this;
+        off(type: string, callback?: (...args: any[]) => void): this;
+        removeEvent(type?: string, callback?: (...args: any[]) => void): this;
+        /** Route matching conversation Push events to this page; pass null to receive all conversations. */
+        setConversation(conversation: RTMConversation | null, callback?: (error?: Error | null) => void): this;
+        /** Detaches this page; also called automatically on pagehide (except BFCache). It does not close the shared connection. */
+        destroy(): void;
+    }
+
+    export interface RTMSharedWorkerIdentity {
+        pid: string | number;
+        uid: RTMId;
+        endpoint?: string;
+        namespace?: string;
+    }
+
+    export function createSharedWorkerName(identity: RTMSharedWorkerIdentity): string;
+
+    type RTMSharedWorkerClientMethods = Pick<RTMClient, Exclude<keyof RTMClient,
+        'emit' | 'promises'>>;
+
+    export interface RTMSharedWorkerClient extends RTMSharedWorkerClientMethods {}
+
     export class RTMConfig {
         static ERROR_CODE;
         static Int64;