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

package/README.md

@@ -1,61 +1,102 @@
 # @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`、消息 ID、群 ID、房间 ID 和时间游标超出安全整数范围时使用 `RTMConfig.Int64`。
+`createClient()` 默认共享连接，默认协议为 TLV。Worker 名称由 SDK 按 **PID + 协议 + UID** 自动生成，UID 可直接从 `login()` 获取，业务无需维护 `workerName`。已发布 `.3` 不包含这个入口；请先使用本地构建或后续版本。
 
-## Push API
+```js
+const client = rtm.createClient({ pid, tlvEndpoint: endpoint });
+client.processor.on(rtm.RTMConfig.TLV_SERVER_PUSH.recvMessage, renderMessage);
+await client.promises.login(uid, credential); // 同 UID 已登录时 credential 可省略
+await client.promises.sendChat(peerUid, 'hello', '{}');
+// 离开页面只释放本页，其他页面继续收发。
+client.destroy();
+```
 
-通过 `client.processor.on(name, callback)` 注册：
+片段中的 `rtm`、项目参数、credential 和 `renderMessage` 由应用提供；完整流程和能力边界见 [默认共享接入](docs/USAGE.md#默认共享接入当前源码)。设置 `sharing: false` 创建独立连接；旧 `new RTMClient()` 的默认行为保持不变。Vite 项目从包的 `/vite` 入口导入，SDK 自动打包 Worker。
 
-- `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`
+### 原有单连接入口
 
-可靠消息 Push 由 SDK 自动 ACK 并按 `message_ref` 去重。
+从业务服务端取得当前 UID 的 credential，然后连接 Gate。credential 必须由服务端签发；项目 SecretKey 不要放进浏览器。
 
-## API 文档
+```js
+async function startChat(rtm, { pid, endpoint, uid, peerUid, credential }) {
+  const client = new rtm.RTMClient({
+    protocol: 'tlv-v1',
+    pid,
+    tlvEndpoint: endpoint,
+  });
+  let loggedIn = false;
 
-- [公开方法与参数](docs/USAGE.md)
-- [TLV v1 wire 契约](docs/TLV_CONTRACT.md)
+  client.processor.on(rtm.RTMConfig.TLV_SERVER_PUSH.recvMessage, (event) => {
+    console.log('Direct message', event);
+  });
+
+  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();
+    }
+  }
+}
+```
+
+此片段假定调用方已加载 SDK，并取得 `pid`、完整 WebSocket endpoint、`uid`、`peerUid` 和服务端签发的 `credential`。带 credential 获取方式、错误处理、关闭流程、参数和返回值的完整示例见 [SDK 接入指南](docs/USAGE.md#2-快速开始登录收-push发消息关闭)。
+
+## 同 UID 多窗口
+
+需要同一浏览器内多个同源页面共用一个 UID 的 RTC 登录和 WebSocket 时，新接入推荐使用 SDK 的 `createClient()` 默认共享入口。SDK 按 PID、协议和 UID 确定共享会话，业务代码无需维护 `workerName`；普通浏览器部署时将 `rtm.min.js` 和 `rtm.shared-worker.js` 放在同一同源目录即可。首次登录需要 credential；同 UID 后续页面复用共享会话。完整说明见 [默认共享接入](docs/USAGE.md#默认共享接入当前源码)。
+
+Vite 项目从 `@cg-devcenter/rtc-fpnn-webjs-sdk/vite` 导入 ESM 入口，SDK 会自动打包和配置 Worker 文件。若使用底层 `RTMSharedWorkerClient` 构造器，可通过 `uid` 自动生成 Worker 名称，或显式传入 `workerName`；`createClient()` 会按登录 UID 自动绑定，不要求手动设置名称。最后一个页面 detach 后默认 5 秒关闭共享连接。需要固定在已发布 `.3` 上时仍可直接使用 `RTMSharedWorkerClient`；当前源码新增的 `createClient()` 尚未包含在 `.3` 中。
+
+当前源码的 SharedWorker 也支持显式选择 `clientOptions.protocol: 'fpnn'`，登录共享和会话路由沿用同一套 API。已发布的 `1.0.0-cg.3` 尚不含 FPNN 共享扩展；本地构建或后续版本的用法与限制见 [FPNN 多窗口接入](docs/USAGE.md#fpnn-多窗口接入)。
+
+仓库的演示页面可用以下命令启动：
+
+```bash
+npm run build
+npm run demo:shared-worker
+```
+
+发送台和收件箱 demo 地址、真实 Gate 配置方式见 [Demo 使用说明](examples/shared-worker-demo/README.md)。
+
+另有使用 Vue 3、Vite 和 npm 包导入方式的同功能示例；本次新入口需先通过 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)
+- [FPNN 与 TLV v1 迁移对照](docs/PROTOCOL_MIGRATION.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,39 @@ 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;
+
+    export type RTMDefaultPromiseApi = Omit<RTMPromiseApi, 'login'> & {
+        /** Only the first same-UID page requires a credential. */
+        login(uid: RTMId, credential?: string, timeout?: number): Promise<RTMLoginPromiseResult>;
+    };
 
     interface RTMRegressiveStrategy {
         startConnectFailedCount: number;
@@ -33,7 +66,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 +79,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 +110,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 +193,143 @@ declare namespace rtm {
         removeEvent();
     }
 
+    export interface RTMSharedWorkerBaseClientOptions {
+        pid: number;
+        maxPingIntervalSeconds?: number;
+        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;
+    }
+
+    /** Defaults to TLV; FPNN must be explicitly selected. Functions cannot cross the Worker boundary. */
+    export type RTMSharedWorkerClientOptions = RTMSharedWorkerBaseClientOptions & (
+        { protocol?: 'tlv-v1'; tlvEndpoint: string }
+        | ({ protocol: 'fpnn' } & (
+            { endpoint: string; ssl_endpoint?: string } | { ssl_endpoint: string; endpoint?: string }
+        ))
+    );
+
+    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 protocol, 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 RTM options. Supports TLV and FPNN; file uploads remain unsupported. */
+        clientOptions: RTMSharedWorkerClientOptions;
+        /** Optional route for this page. When omitted, this page receives all conversation Push events. */
+        conversation?: RTMConversation | null;
+    }
+
+    /** Flat client options. Browser sharing defaults to true; protocol defaults to TLV in both modes. */
+    export type RTMCreateClientOptions = RTMSharedWorkerClientOptions &
+        Omit<RTMSharedWorkerOptions, 'clientOptions'> & { sharing?: true };
+
+    /** Default shared facade. Worker is attached on login, or immediately when options.uid is set. */
+    export interface RTMDefaultClient extends Omit<RTMSharedWorkerClient, 'promises' | 'login' | 'whenReady'> {
+        readonly promises: RTMDefaultPromiseApi;
+        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;
+        setConversation(conversation: RTMConversation | null, callback?: (error?: Error | null) => void): this;
+        /** All callback failures use (false, numericCode); local/Worker details are emitted as SharedWorkerError. */
+        login(uid: RTMId, credential?: string, callback?: (accepted: boolean, errorCode?: number) => void, timeout?: number): void;
+        /** Requires a UID from options.uid, login(), or this argument. Never waits for an unspecified UID. */
+        whenReady(uid?: RTMId): Promise<RTMSharedSessionSnapshot>;
+        emit(type: string, ...args: any[]): void;
+    }
+
+    export function createClient(options: RTMClientOptions & { sharing: false }): RTMClient;
+    export function createClient(options: RTMCreateClientOptions): RTMDefaultClient;
+
+    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 protocol, 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 {
+        /** Defaults to tlv-v1. FPNN names are isolated from TLV names. */
+        protocol?: RTMProtocol;
+        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;