@pmate/chat-sdk 0.6.2 → 0.6.3

package/README.md

@@ -32,3 +32,11 @@ must preserve the text offsets if transforming the message before transport.
 Storybook: `GroupMentions`, `MobileGroupMentions`, and `DarkGroupMentions` use the
 production components, include duplicate names and scrolling, and support empty
 results by typing an unmatched query.
+
+## Connection recovery
+
+A dropped socket (including a network change or a suspended laptop) previously required callers to recreate the client. The runtime now reconnects with capped exponential backoff, probes the Hub with its binary heartbeat, and authenticates each replacement socket before sending chat traffic.
+
+`client.watchConnection(handler)` immediately reports the current state and returns an unsubscribe function. States are `connecting`, `reconnecting`, `authenticating`, `connected`, `authentication_required`, and `closed`. Only `connected` means the Hub acknowledged authentication. A rejected authentication stops retries; supply a fresh login session using a new client. `close()` cancels retries, heartbeat timers and browser wake listeners.
+
+Messages sent without an acknowledgement are rejected on disconnect and are **not replayed**: delivery is uncertain, so automatic retries could duplicate them. Callers should preserve drafts, display a reconnecting state, and refresh message history after recovery. No durable offline outbox is provided. An initial `connect()` wait times out after 30 seconds, but recovery continues until explicitly closed; retain the client and observe its connection state.

package/lib/runtime/chatClient.d.ts

@@ -3,6 +3,7 @@ import type { ChatMention } from "../mentions/model";
 import { type BotLoginSession } from "./botAuth.js";
 import { type PmateBotKeyFile } from "./botKey.js";
 import { type ChatBody, type ChatRuntimeMessage, type RealtimeClient } from "./protocol.js";
+export type ChatConnectionState = "connecting" | "reconnecting" | "authenticating" | "connected" | "authentication_required" | "closed";
 export type ChatClientOptions = {
     appId: string;
     profileId?: string;
@@ -17,6 +18,11 @@ export type ChatClientOptions = {
 };
 export declare class ChatClient {
     private readonly options;
+    private connection;
+    private readonly connectionHandlers;
+    private subscriptions;
+    private generation;
+    private connectPromise?;
     private client;
     private session;
     private profileIdValue;
@@ -27,7 +33,13 @@ export declare class ChatClient {
     private readonly messageHandlers;
     constructor(options: ChatClientOptions);
     connect(): Promise<this>;
+    private initialize;
     close(): void;
+    connectionState(): ChatConnectionState;
+    watchConnection(handler: (state: ChatConnectionState) => void): () => void;
+    private setConnection;
+    private rejectPending;
+    private authenticate;
     watchMessages(handler: (message: ChatRuntimeMessage) => void): () => boolean;
     watchActivities(handler: (activities: ChatActivity[]) => void): () => void;
     sendActivity(input: ActivityTarget & {
@@ -76,7 +88,7 @@ export declare class ChatClient {
     private sendAuth;
     private sendAndWaitForAck;
     private handleIncoming;
-    private waitUntilConnected;
+    private waitUntilReady;
     private accountId;
     private resolveProfileId;
     private profileId;

package/lib/runtime/chatClient.js

@@ -7,6 +7,11 @@ const DEFAULT_AUTH_API_BASE_URL = "https://auth-api-v2.pmate.chat";
 const DEFAULT_ACK_TIMEOUT_MS = 5_000;
 export class ChatClient {
     options;
+    connection = "closed";
+    connectionHandlers = new Set();
+    subscriptions = [];
+    generation = 0;
+    connectPromise;
     client = null;
     session = null;
     profileIdValue = null;
@@ -23,7 +28,20 @@ export class ChatClient {
         this.session = options.session ?? null;
         this.client = options.realtimeClient ?? null;
     }
-    async connect() {
+    connect() {
+        if (this.connectPromise)
+            return this.connectPromise;
+        if (this.connection === "connected")
+            return Promise.resolve(this);
+        const generation = this.generation;
+        this.setConnection("connecting");
+        const promise = this.initialize(generation);
+        this.connectPromise = promise;
+        void promise.finally(() => { if (this.connectPromise === promise)
+            this.connectPromise = undefined; }).catch(() => { });
+        return promise;
+    }
+    async initialize(generation) {
         if (!this.session) {
             if (!this.botKey) {
                 throw new Error("ChatClient requires either session or PMate bot key JSON");
@@ -35,35 +53,87 @@ export class ChatClient {
             });
         }
         const profileId = await this.resolveProfileId();
+        if (generation !== this.generation)
+            throw new Error("ChatClient closed");
         if (!this.client) {
             const hubUrl = normalizeWsUrl(this.options.hubUrl ?? DEFAULT_HUB_URL, profileId);
             this.client = new RuntimeWebsocketClient(hubUrl);
         }
-        this.client.on(ChatRealtimeEvents.Message, (message) => {
-            this.handleIncoming(message);
-        });
-        this.client.on(ChatRealtimeEvents.Connected, (connected) => { if (!connected) {
-            for (const publisher of this.publishers)
-                void publisher.stop();
-            this.activities.clear();
-        } });
-        await this.waitUntilConnected();
-        await this.sendAuth();
+        if (!this.subscriptions.length) {
+            this.subscriptions.push(this.client.on(ChatRealtimeEvents.Message, message => this.handleIncoming(message)), this.client.on(ChatRealtimeEvents.Connected, connected => {
+                if (connected)
+                    void this.authenticate();
+                else {
+                    this.generation++;
+                    this.setConnection("reconnecting");
+                    this.rejectPending(new Error("聊天连接已断开，消息尚未确认送达"));
+                    for (const publisher of this.publishers)
+                        void publisher.stop();
+                    this.activities.clear();
+                }
+            }));
+        }
+        if (this.client.isConnected())
+            void this.authenticate();
+        await this.waitUntilReady();
         return this;
     }
     close() {
+        this.generation++;
+        for (const off of this.subscriptions.splice(0))
+            off();
+        this.setConnection("closed");
         for (const publisher of this.publishers)
             void publisher.stop();
         this.publishers.clear();
         this.activities.clear();
         this.client?.close();
         this.client = null;
+        this.connectPromise = undefined;
+        this.rejectPending(new Error("ChatClient closed"));
+    }
+    connectionState() { return this.connection; }
+    watchConnection(handler) {
+        this.connectionHandlers.add(handler);
+        handler(this.connection);
+        return () => { this.connectionHandlers.delete(handler); };
+    }
+    setConnection(state) {
+        if (this.connection === state)
+            return;
+        this.connection = state;
+        for (const handler of this.connectionHandlers)
+            handler(state);
+    }
+    rejectPending(error) {
         for (const pending of this.pendingAcks.values()) {
-            pending.reject(new Error("ChatClient closed"));
+            pending.reject(error);
             clearTimeout(pending.timer);
         }
         this.pendingAcks.clear();
     }
+    async authenticate() {
+        if (this.connection === "authenticating" || this.connection === "connected")
+            return;
+        const generation = this.generation;
+        this.setConnection("authenticating");
+        try {
+            await this.sendAuth();
+            if (generation === this.generation)
+                this.setConnection("connected");
+        }
+        catch (error) {
+            if (generation !== this.generation)
+                return;
+            if (error instanceof ChatAckError) {
+                this.close();
+                this.setConnection("authentication_required");
+            }
+            else {
+                this.client?.close(false);
+            }
+        }
+    }
     watchMessages(handler) {
         this.messageHandlers.add(handler);
         return () => this.messageHandlers.delete(handler);
@@ -165,6 +235,9 @@ export class ChatClient {
     }
     async sendAndWaitForAck(msg) {
         const client = this.requireClient();
+        if (msg.opcode !== ChatMsgOp.AUTH && this.connection !== "connected") {
+            throw new Error(this.connection === "authentication_required" ? "登录已失效，请重新登录" : "聊天连接正在恢复，请稍后重试");
+        }
         const ack = new Promise((resolve, reject) => {
             const timer = setTimeout(() => {
                 this.pendingAcks.delete(msg.hash);
@@ -196,7 +269,7 @@ export class ChatClient {
                     pending.resolve(ack);
                 }
                 else {
-                    pending.reject(new Error(ack.message || ack.code || "Ack failed"));
+                    pending.reject(new ChatAckError(ack.message || ack.code || "Ack failed"));
                 }
             }
             return;
@@ -214,24 +287,26 @@ export class ChatClient {
             }
         }
     }
-    waitUntilConnected() {
-        const client = this.requireClient();
-        if (client.isConnected()) {
+    waitUntilReady() {
+        if (this.connection === "connected")
             return Promise.resolve();
-        }
         return new Promise((resolve, reject) => {
-            const offConnected = client.on(ChatRealtimeEvents.Connected, (connected) => {
-                if (connected) {
-                    offConnected();
-                    offError();
+            const timer = setTimeout(() => {
+                this.connectionHandlers.delete(check);
+                reject(new Error("聊天连接正在恢复，请稍后重试"));
+            }, 30_000);
+            const check = (state) => {
+                if (!["connected", "closed", "authentication_required"].includes(state))
+                    return;
+                clearTimeout(timer);
+                this.connectionHandlers.delete(check);
+                if (state === "connected")
                     resolve();
-                }
-            });
-            const offError = client.on(ChatRealtimeEvents.Error, (error) => {
-                offConnected();
-                offError();
-                reject(error instanceof Error ? error : new Error("WebSocket connection failed"));
-            });
+                else
+                    reject(new Error(state === "authentication_required" ? "登录已失效，请重新登录" : "ChatClient closed"));
+            };
+            this.connectionHandlers.add(check);
+            check(this.connection);
         });
     }
     accountId() {
@@ -292,6 +367,8 @@ export class ChatClient {
         return this.client;
     }
 }
+class ChatAckError extends Error {
+}
 export function createChatClient(options) {
     return new ChatClient(options);
 }

package/lib/runtime/protocol.d.ts

@@ -72,13 +72,24 @@ export declare class RuntimeWebsocketClient implements RealtimeClient {
     private readonly wsUrl;
     private ws;
     private connected;
+    private closed;
+    private attempt;
+    private retryTimer?;
+    private connectTimer?;
+    private heartbeatTimer?;
+    private pongTimer?;
     private readonly listeners;
+    private readonly onWake;
     constructor(wsUrl: string);
     on<T>(topic: string, handler: (value: T) => void): () => boolean;
     isConnected(): boolean;
-    close(): void;
+    close(manual?: boolean): void;
     sendMsg(msg: ChatRuntimeMessage): Promise<void>;
     getConnectionType(): "websocket";
     private connect;
+    private ping;
+    private dropSocket;
+    private clearRetry;
+    private scheduleReconnect;
     private emit;
 }

package/lib/runtime/protocol.js

@@ -32,9 +32,31 @@ export class RuntimeWebsocketClient {
     wsUrl;
     ws = null;
     connected = false;
+    closed = false;
+    attempt = 0;
+    retryTimer;
+    connectTimer;
+    heartbeatTimer;
+    pongTimer;
     listeners = new Map();
+    onWake = () => {
+        if (this.closed || (typeof document !== "undefined" && document.hidden))
+            return;
+        if (this.connected)
+            this.ping();
+        else {
+            this.clearRetry();
+            if (!this.ws)
+                this.connect();
+        }
+    };
     constructor(wsUrl) {
         this.wsUrl = wsUrl;
+        if (typeof window !== "undefined") {
+            window.addEventListener("online", this.onWake);
+            window.addEventListener("pageshow", this.onWake);
+            document.addEventListener("visibilitychange", this.onWake);
+        }
         this.connect();
     }
     on(topic, handler) {
@@ -46,10 +68,17 @@ export class RuntimeWebsocketClient {
     isConnected() {
         return this.connected;
     }
-    close() {
-        this.ws?.close();
-        this.ws = null;
-        this.connected = false;
+    close(manual = true) {
+        this.closed = manual;
+        this.clearRetry();
+        this.dropSocket();
+        if (manual && typeof window !== "undefined") {
+            window.removeEventListener("online", this.onWake);
+            window.removeEventListener("pageshow", this.onWake);
+            document.removeEventListener("visibilitychange", this.onWake);
+        }
+        if (!manual)
+            this.scheduleReconnect();
     }
     async sendMsg(msg) {
         if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
@@ -61,20 +90,53 @@ export class RuntimeWebsocketClient {
         return "websocket";
     }
     connect() {
-        this.ws = new WebSocket(this.wsUrl);
-        this.ws.binaryType = "arraybuffer";
-        this.ws.onopen = () => {
+        if (this.closed || this.ws)
+            return;
+        let ws;
+        try {
+            ws = new WebSocket(this.wsUrl);
+        }
+        catch (error) {
+            this.emit(ChatRealtimeEvents.Error, error);
+            this.scheduleReconnect();
+            return;
+        }
+        this.ws = ws;
+        ws.binaryType = "arraybuffer";
+        this.connectTimer = setTimeout(() => this.close(false), 10_000);
+        ws.onopen = () => {
+            if (this.ws !== ws)
+                return;
+            clearTimeout(this.connectTimer);
             this.connected = true;
+            this.attempt = 0;
+            this.heartbeatTimer = setInterval(() => this.ping(), 20_000);
             this.emit(ChatRealtimeEvents.Connected, true);
         };
-        this.ws.onclose = () => {
-            this.connected = false;
-            this.emit(ChatRealtimeEvents.Connected, false);
-        };
-        this.ws.onerror = (event) => {
+        ws.onclose = () => { if (this.ws === ws)
+            this.close(false); };
+        ws.onerror = (event) => {
+            if (this.ws !== ws)
+                return;
             this.emit(ChatRealtimeEvents.Error, event);
+            this.close(false);
         };
-        this.ws.onmessage = (event) => {
+        ws.onmessage = (event) => {
+            if (this.ws !== ws)
+                return;
+            // Hub uses single-byte binary PING/PONG frames, separate from MessagePack.
+            const bytes = event.data instanceof ArrayBuffer ? new Uint8Array(event.data) : event.data;
+            if (bytes instanceof Uint8Array && bytes.length === 1) {
+                if (bytes[0] === 2) {
+                    clearTimeout(this.pongTimer);
+                    this.pongTimer = undefined;
+                    return;
+                }
+                if (bytes[0] === 1) {
+                    ws.send(new Uint8Array([2]));
+                    return;
+                }
+            }
             try {
                 this.emit(ChatRealtimeEvents.Message, decodeWireMessage(event.data));
             }
@@ -83,6 +145,41 @@ export class RuntimeWebsocketClient {
             }
         };
     }
+    ping() {
+        if (!this.connected || this.pongTimer || !this.ws)
+            return;
+        this.pongTimer = setTimeout(() => this.close(false), 10_000);
+        try {
+            this.ws.send(new Uint8Array([1]));
+        }
+        catch {
+            this.close(false);
+        }
+    }
+    dropSocket() {
+        clearTimeout(this.connectTimer);
+        clearInterval(this.heartbeatTimer);
+        clearTimeout(this.pongTimer);
+        this.pongTimer = undefined;
+        const ws = this.ws;
+        this.ws = null;
+        this.connected = false;
+        if (ws) {
+            ws.onopen = ws.onclose = ws.onerror = ws.onmessage = null;
+            ws.close();
+        }
+        this.emit(ChatRealtimeEvents.Connected, false);
+    }
+    clearRetry() { clearTimeout(this.retryTimer); this.retryTimer = undefined; }
+    scheduleReconnect() {
+        if (this.closed || this.retryTimer)
+            return;
+        const delay = Math.min(30_000, 500 * 2 ** Math.min(this.attempt++, 6));
+        this.retryTimer = setTimeout(() => {
+            this.retryTimer = undefined;
+            this.connect();
+        }, delay * (0.8 + Math.random() * 0.2));
+    }
     emit(topic, value) {
         for (const handler of this.listeners.get(topic) ?? []) {
             handler(value);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmate/chat-sdk",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "description": "Cross-platform PMate chat input components, voice input primitives, and ASR helpers",
   "type": "module",
   "main": "./lib/index.js",