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

package/README.md

@@ -20,6 +20,23 @@ Node.js 使用 TLV v1 时，需自行提供 `webSocketFactory(url)`。SDK 不携
 
 ## Quick Start
 
+### 默认共享入口（当前源码）
+
+`createClient()` 默认共享连接，默认协议为 TLV。Worker 名称由 SDK 按 **PID + 协议 + UID** 自动生成，UID 可直接从 `login()` 获取，业务无需维护 `workerName`。已发布 `.3` 不包含这个入口；请先使用本地构建或后续版本。
+
+```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();
+```
+
+片段中的 `rtm`、项目参数、credential 和 `renderMessage` 由应用提供；完整流程和能力边界见 [默认共享接入](docs/USAGE.md#默认共享接入当前源码)。设置 `sharing: false` 创建独立连接；旧 `new RTMClient()` 的默认行为保持不变。Vite 项目从包的 `/vite` 入口导入，SDK 自动打包 Worker。
+
+### 原有单连接入口
+
 从业务服务端取得当前 UID 的 credential，然后连接 Gate。credential 必须由服务端签发；项目 SecretKey 不要放进浏览器。
 
 ```js
@@ -53,9 +70,11 @@ async function startChat(rtm, { pid, endpoint, uid, peerUid, credential }) {
 
 ## 同 UID 多窗口
 
-需要同一浏览器内多个同源页面共用一个 UID 的 RTC 登录和 WebSocket 时，使用 SDK 的 `RTMSharedWorkerClient`。SDK 默认从主 SDK 脚本旁自动定位 `rtm.shared-worker.js`，业务代码无需维护 `workerUrl`；部署时将两个文件放在同一同源目录即可。首次登录需要 credential；同 UID 后续页面复用共享会话。部署和 Push 路由示例见 [SharedWorker 接入说明](docs/USAGE.md#4-同-uid-多窗口sharedworker)。
+需要同一浏览器内多个同源页面共用一个 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` 中。
 
-Vite 项目应从 `@cg-devcenter/rtc-fpnn-webjs-sdk/vite` 导入 ESM 入口，由 SDK 自动打包和配置 Worker 文件；传入 `uid` 可自动生成稳定的 Worker 名称。多账号应用应传 `uid` 或显式 `workerName`，避免多个账号共用默认名称。最后一个页面 detach 后默认 5 秒关闭共享连接。
+当前源码的 SharedWorker 也支持显式选择 `clientOptions.protocol: 'fpnn'`，登录共享和会话路由沿用同一套 API。已发布的 `1.0.0-cg.3` 尚不含 FPNN 共享扩展；本地构建或后续版本的用法与限制见 [FPNN 多窗口接入](docs/USAGE.md#fpnn-多窗口接入)。
 
 仓库的演示页面可用以下命令启动：
 
@@ -66,7 +85,7 @@ 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)。
+另有使用 Vue 3、Vite 和 npm 包导入方式的同功能示例；本次新入口需先通过 yalc 链接本地构建：[Vue 3 SharedWorker Demo](examples/vue3-shared-worker-demo/README.md)。
 
 ## TLV v1 最小接入 Demo
 
@@ -75,6 +94,7 @@ npm run demo:shared-worker
 ## 文档
 
 - [接入指南与 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)

package/dist/rtm.d.ts

@@ -31,6 +31,11 @@ declare namespace rtm {
 
     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;
         maxIntervalSeconds: number;
@@ -188,12 +193,9 @@ declare namespace rtm {
         removeEvent();
     }
 
-    export interface RTMSharedWorkerClientOptions {
+    export interface RTMSharedWorkerBaseClientOptions {
         pid: number;
-        /** SharedWorker supports the TLV transport only. */
-        protocol?: 'tlv-v1';
-        /** Required full ws:// or wss:// WebSocket URL. */
-        tlvEndpoint: string;
+        maxPingIntervalSeconds?: number;
         autoReconnect?: boolean;
         connectionTimeout?: number;
         requestTimeout?: number;
@@ -210,6 +212,14 @@ declare namespace rtm {
         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 {
@@ -221,7 +231,7 @@ declare namespace rtm {
     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. */
+        /** 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;
@@ -231,12 +241,34 @@ declare namespace rtm {
         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. */
+        /** 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. */
@@ -260,7 +292,7 @@ declare namespace rtm {
 
     export class RTMSharedWorkerClient {
         constructor(options: RTMSharedWorkerOptions);
-        /** Creates a stable name for the same project, UID, endpoint, and optional application/environment namespace. */
+        /** 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;
@@ -283,6 +315,8 @@ declare namespace rtm {
     }
 
     export interface RTMSharedWorkerIdentity {
+        /** Defaults to tlv-v1. FPNN names are isolated from TLV names. */
+        protocol?: RTMProtocol;
         pid: string | number;
         uid: RTMId;
         endpoint?: string;