@appthen/sdk-web 0.0.2 → 0.0.3

package/dist/index.d.ts

@@ -47,12 +47,31 @@ export interface ConversationSocketEvent {
 export interface SocketIoConversationRealtimeAdapterOptions {
     url: string;
     account?: () => string | null | Promise<string | null>;
+    /**
+     * JWT 提供者（2026-09-21 修复）：socket 的身份**只在握手时**由 query.token 建立，
+     * 服务端 join 是 fail-closed 的——没带 token 的连接会被拒绝加入任何房间（收不到
+     * 实时事件）。此前 token 只能经 connect(token) 显式传入，而宿主普遍不会调它，
+     * 首个 joinRoom/subscribeConversation 会以**无 token** 连接固化 ⇒ 审批卡原地
+     * 收敛（message.updated）永远到不了已打开的页面，卡片卡死在"Applying..."。
+     * 提供 getter 后每次 ensureSocket 都取当前 token；socket 已存在但 token 变化
+     * （含从无到有）时重建连接，activeRooms 会在 connect 后自动重新加入。
+     */
+    token?: () => string | null | Promise<string | null>;
     roomPrefix?: string;
     eventName?: string;
+    /**
+     * 持久房间（P1.5 投递模型）：每次连接建立后自动 join 的房间列表。
+     * 用于「个人房间」`hub:subject:<subjectId>` —— 投递目标是「人」不是「房间」，
+     * 收件箱增量/通知请求由服务端扇出到该房间，客户端必须始终在线才能收到；
+     * 与 subscribeConversation 的引用计数房间不同，这里每次 connect 重放 join
+     * （服务端 socket.join 幂等），不参与 activeRooms 计数。
+     */
+    persistentRooms?: () => string[];
 }
 export declare class SocketIoConversationRealtimeAdapter implements RealtimeAdapter {
     private readonly options;
     private socket;
+    private socketToken;
     private connectPromise;
     private activeRooms;
     private subscriptions;
@@ -62,10 +81,17 @@ export declare class SocketIoConversationRealtimeAdapter implements RealtimeAdap
     private get messageEventName();
     private getConversationRoom;
     private getAccount;
+    private resolveSocketToken;
     private ensureSocket;
     private emitJoin;
     private emitLeave;
     private joinActiveRooms;
+    /**
+     * 持久房间（P1.5）：每次连接后重放 join。个人房间 `hub:subject:<subjectId>`
+     * 承担「投递给人」的职责（收件箱增量/通知请求/未来投递路由），必须随连接常驻；
+     * 服务端 socket.join 幂等，重复 join 无副作用。
+     */
+    private joinPersistentRooms;
     connect(token?: string | null): Promise<void>;
     disconnect(): Promise<void>;
     /**
@@ -81,6 +107,28 @@ export declare class SocketIoConversationRealtimeAdapter implements RealtimeAdap
     onGlobalEvent(handler: (event: Record<string, unknown>) => void): () => void;
     subscribeConversation(conversationId: string): Promise<RealtimeSubscription<ConversationSocketEvent>>;
     publishConversationEvent(conversationId: string, event: Record<string, unknown>): Promise<void>;
+    /**
+     * 客户端活性上报（P0 状态层，SC-69 ClientPresence）：前台/后台 + 当前聚焦会话。
+     * 服务端据此决定投递出口（在线免打扰等，SC-70 通知决策器）。
+     * 连接未就绪时先 ensureSocket；仍不可用则静默跳过（下次活性变化再上报）。
+     */
+    reportPresence(activity: {
+        appState?: 'foreground' | 'background';
+        focusConversation?: string | null;
+    }): Promise<void>;
+    private autoVisibilityBound;
+    /**
+     * 客户端设备 id 提供器（SC-74）：设置后每次活性上报都附带 `deviceId`，
+     * 服务端据此刷新**设备粒度**在线态（SC-69 扩展 / SC-75 客户端管理 / 逐端推送）。
+     * 用 provider 而非固定值：宿主解析设备身份是异步的，后置写入也要生效。
+     */
+    clientDeviceIdProvider?: () => string | undefined;
+    /**
+     * 自动按页面可见性上报前台/后台（visibilitychange → foreground/background）。
+     * 幂等；浏览器环境才生效（无 document 时静默跳过）。聚焦会话由宿主
+     * 在会话切换时调 reportPresence({ focusConversation }) 补充。
+     */
+    enableAutoPageVisibility(): void;
 }
 export interface CreateWebChatHubClientOptions {
     baseUrl: string;

package/dist/index.js

@@ -172,10 +172,12 @@ export class SocketIoConversationRealtimeAdapter {
     constructor(options) {
         this.options = options;
         this.socket = null;
+        this.socketToken = null;
         this.connectPromise = null;
         this.activeRooms = new Map();
         this.subscriptions = new Map();
         this.globalListeners = new Set();
+        this.autoVisibilityBound = false;
     }
     get roomPrefix() {
         return this.options.roomPrefix || 'hub:conversation:';
@@ -189,7 +191,32 @@ export class SocketIoConversationRealtimeAdapter {
     async getAccount() {
         return (await this.options.account?.()) || 'anonymous';
     }
+    async resolveSocketToken(explicit) {
+        if (explicit !== undefined)
+            return explicit;
+        try {
+            return (await this.options.token?.()) ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
     async ensureSocket(token) {
+        const resolvedToken = await this.resolveSocketToken(token);
+        // token 变化（尤其是"无 → 有"）必须重建连接：身份只在握手时建立，
+        // 复用一条无 token 的旧连接会让所有 join 继续 fail-closed。
+        if (this.socket && this.socketToken !== (resolvedToken || null)) {
+            const stale = this.socket;
+            this.socket = null;
+            this.connectPromise = null;
+            try {
+                stale.removeAllListeners();
+                stale.disconnect();
+            }
+            catch {
+                // 忽略销毁失败——下面的新连接会自愈
+            }
+        }
         if (this.socket?.connected) {
             return this.socket;
         }
@@ -197,11 +224,14 @@ export class SocketIoConversationRealtimeAdapter {
             await this.connectPromise;
             return this.socket;
         }
+        this.socketToken = resolvedToken || null;
         this.connectPromise = new Promise((resolve, reject) => {
             const socket = io(this.options.url, {
                 autoConnect: false,
+                // 纯 WebSocket：禁止 polling/HTTP 轮询绕路。桌面端 local-server 对
+                // /socket.io upgrade 请求做 TCP 隧道转发，握手失败应直接暴露而非静默降级。
                 transports: ['websocket'],
-                query: token ? { token } : {},
+                query: resolvedToken ? { token: resolvedToken } : {},
             });
             const cleanup = () => {
                 socket.off('connect', handleConnect);
@@ -210,6 +240,13 @@ export class SocketIoConversationRealtimeAdapter {
             const handleConnect = async () => {
                 cleanup();
                 this.socket = socket;
+                if (typeof console !== 'undefined') {
+                    const transportName = socket.io?.engine?.transport?.name || 'unknown';
+                    console.info(`[chat-hub-realtime] connected via transport: ${transportName}`);
+                    socket.io.engine?.on?.('upgrade', (transport) => {
+                        console.info(`[chat-hub-realtime] transport upgraded to: ${transport.name}`);
+                    });
+                }
                 socket.on(this.messageEventName, (payload) => {
                     const evtName = payload && typeof payload === 'object'
                         ? payload.eventName
@@ -232,8 +269,10 @@ export class SocketIoConversationRealtimeAdapter {
                 });
                 socket.on('connect', async () => {
                     await this.joinActiveRooms();
+                    await this.joinPersistentRooms();
                 });
                 await this.joinActiveRooms();
+                await this.joinPersistentRooms();
                 resolve();
             };
             const handleError = (error) => {
@@ -300,12 +339,26 @@ export class SocketIoConversationRealtimeAdapter {
     async joinActiveRooms() {
         await Promise.all(Array.from(this.activeRooms.keys()).map((room) => this.emitJoin(room)));
     }
+    /**
+     * 持久房间（P1.5）：每次连接后重放 join。个人房间 `hub:subject:<subjectId>`
+     * 承担「投递给人」的职责（收件箱增量/通知请求/未来投递路由），必须随连接常驻；
+     * 服务端 socket.join 幂等，重复 join 无副作用。
+     */
+    async joinPersistentRooms() {
+        const rooms = this.options.persistentRooms?.() || [];
+        for (const room of rooms) {
+            if (!room)
+                continue;
+            await this.emitJoin(room);
+        }
+    }
     async connect(token) {
         await this.ensureSocket(token);
     }
     async disconnect() {
         const socket = this.socket;
         this.socket = null;
+        this.socketToken = null;
         this.connectPromise = null;
         this.globalListeners.clear();
         if (socket) {
@@ -385,6 +438,61 @@ export class SocketIoConversationRealtimeAdapter {
             ...event,
         });
     }
+    /**
+     * 客户端活性上报（P0 状态层，SC-69 ClientPresence）：前台/后台 + 当前聚焦会话。
+     * 服务端据此决定投递出口（在线免打扰等，SC-70 通知决策器）。
+     * 连接未就绪时先 ensureSocket；仍不可用则静默跳过（下次活性变化再上报）。
+     */
+    async reportPresence(activity) {
+        const socket = this.socket;
+        if (!socket?.connected) {
+            try {
+                await this.ensureSocket();
+            }
+            catch {
+                return;
+            }
+        }
+        if (!this.socket?.connected)
+            return;
+        const payload = {};
+        if (activity.appState === 'foreground' || activity.appState === 'background') {
+            payload.appState = activity.appState;
+        }
+        if (activity.focusConversation !== undefined) {
+            payload.focusConversation = activity.focusConversation;
+        }
+        // 设备粒度在线态（SC-69 扩展）：每次上报都读一次 provider，
+        // 宿主后置写入 deviceId（如桌面壳 nodeId 解析完成）后照样生效。
+        const deviceId = this.clientDeviceIdProvider?.();
+        if (deviceId) {
+            payload.deviceId = deviceId;
+        }
+        this.socket.emit('presence.update', payload);
+    }
+    /**
+     * 自动按页面可见性上报前台/后台（visibilitychange → foreground/background）。
+     * 幂等；浏览器环境才生效（无 document 时静默跳过）。聚焦会话由宿主
+     * 在会话切换时调 reportPresence({ focusConversation }) 补充。
+     */
+    enableAutoPageVisibility() {
+        if (this.autoVisibilityBound)
+            return;
+        if (typeof document === 'undefined')
+            return;
+        const handleVisibility = () => {
+            const visible = document.visibilityState === 'visible';
+            void this.reportPresence({
+                appState: visible ? 'foreground' : 'background',
+            });
+        };
+        document.addEventListener('visibilitychange', handleVisibility);
+        // 立即上报一次当前状态（连接可能已就绪）
+        void this.reportPresence({
+            appState: document.visibilityState === 'visible' ? 'foreground' : 'background',
+        });
+        this.autoVisibilityBound = true;
+    }
 }
 export function createChatHubClient(options) {
     const clientOptions = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appthen/sdk-web",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "AppThen Conversation Hub SDK - Web platform adapter (fetch + socket.io-client)",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,7 +17,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@appthen/sdk-core": "0.0.2"
+    "@appthen/sdk-core": "0.0.3"
   },
   "peerDependencies": {
     "socket.io-client": "^4.7.0"