@pmate/chat-sdk 0.9.7 → 0.9.9

package/lib/runtime/call.d.ts

@@ -1,3 +1,4 @@
+import type { OnlineReachEvent } from "./reach.js";
 export type MeetingRoom = {
     groupId: string;
     meetingId: string;
@@ -36,6 +37,7 @@ export type CallEnded = {
 };
 export type CallClientOptions = {
     profileId: string;
+    clientInstanceId?: string;
     token: string;
     url?: string;
     iceTransportPolicy?: RTCIceTransportPolicy;
@@ -58,6 +60,9 @@ export declare class CallClient {
     private generation;
     private closed;
     private capturePending;
+    private attachId?;
+    private attachWaiters;
+    private terminalCalls;
     private requestId?;
     private groupIds;
     private heartbeat?;
@@ -68,6 +73,14 @@ export declare class CallClient {
     snapshot(): CallSnapshot;
     subscribe(listener: (state: CallSnapshot) => void): () => void;
     connect(): void;
+    /** Notification/reach entry: query authoritative state before showing a call. */
+    attach(callId: string): void;
+    /** Resolves only after an authoritative response has been applied, never after socket send. */
+    attachAndWait(callId: string, timeoutMs?: number): Promise<"handled" | "suppressed">;
+    private settleAttach;
+    /** Pass only events received through the authenticated OnlineReachReceiver. */
+    handleReach(event: OnlineReachEvent): Promise<"handled" | "suppressed">;
+    private rememberTerminal;
     watchPeer(peerId?: string): void;
     watchGroups(groupIds: string[]): void;
     start(peerId: string): Promise<void>;

package/lib/runtime/call.js

@@ -12,6 +12,9 @@ export class CallClient {
     generation = 0;
     closed = false;
     capturePending = false;
+    attachId;
+    attachWaiters = new Map();
+    terminalCalls = new Map();
     requestId;
     groupIds = [];
     heartbeat;
@@ -29,7 +32,7 @@ export class CallClient {
         const ws = (this.options.createWebSocket ?? (url => new WebSocket(url)))(this.options.url ?? "wss://calls.pmate.chat/call");
         this.ws = ws;
         ws.onopen = () => { if (this.ws === ws)
-            this.send({ type: "auth", token: this.options.token, profileId: this.options.profileId }); };
+            this.send({ type: "auth", token: this.options.token, profileId: this.options.profileId, ...(this.options.clientInstanceId ? { clientInstanceId: this.options.clientInstanceId } : {}) }); };
         ws.onmessage = event => {
             if (this.ws !== ws)
                 return;
@@ -59,6 +62,87 @@ export class CallClient {
                 this.reconnect = setTimeout(() => this.connect(), 3000);
         };
     }
+    /** Notification/reach entry: query authoritative state before showing a call. */
+    attach(callId) {
+        if (this.closed || !callId || callId.length > 128)
+            throw new Error("INVALID_CALL_ID");
+        this.attachId = callId;
+        if (this.state.ready)
+            this.send({ type: "call.attach", callId });
+        else
+            this.connect();
+    }
+    /** Resolves only after an authoritative response has been applied, never after socket send. */
+    attachAndWait(callId, timeoutMs = 4000) {
+        if (this.closed || !callId || callId.length > 128)
+            return Promise.reject(new Error("INVALID_CALL_ID"));
+        if (this.terminalCalls.has(callId))
+            return Promise.resolve("suppressed");
+        return new Promise((resolve, reject) => {
+            const finish = () => {
+                clearTimeout(timer);
+                const waiters = this.attachWaiters.get(callId);
+                waiters?.delete(waiter);
+                if (!waiters?.size)
+                    this.attachWaiters.delete(callId);
+            };
+            const waiter = { resolve: (result) => { finish(); resolve(result); }, reject: (error) => { finish(); reject(error); } };
+            const timer = setTimeout(() => waiter.reject(new Error("CALL_ATTACH_TIMEOUT")), timeoutMs);
+            const waiters = this.attachWaiters.get(callId) ?? new Set();
+            waiters.add(waiter);
+            this.attachWaiters.set(callId, waiters);
+            try {
+                this.attach(callId);
+            }
+            catch (error) {
+                waiter.reject(error instanceof Error ? error : new Error("CALL_ATTACH_FAILED"));
+            }
+        });
+    }
+    settleAttach(callId, result) {
+        for (const waiter of [...(this.attachWaiters.get(callId) ?? [])]) {
+            if (result instanceof Error)
+                waiter.reject(result);
+            else
+                waiter.resolve(result);
+        }
+        if (this.attachId === callId)
+            this.attachId = undefined;
+    }
+    /** Pass only events received through the authenticated OnlineReachReceiver. */
+    async handleReach(event) {
+        if (this.closed)
+            throw new Error("CALL_CLIENT_CLOSED");
+        const { callId, callerId, calleeId, reason, winningClientInstanceId } = event.payload;
+        if (typeof callId !== "string" || !callId || callId.length > 128 || (callerId !== this.options.profileId && calleeId !== this.options.profileId))
+            throw new Error("INVALID_CALL_REACH");
+        if (event.expiresAtMs <= Date.now())
+            return "suppressed";
+        if (event.eventType === "call.incoming") {
+            if (calleeId !== this.options.profileId)
+                throw new Error("INVALID_CALL_RECIPIENT");
+            return this.attachAndWait(callId);
+        }
+        if (event.eventType !== "call.ended" || typeof reason !== "string" || !reason || reason.length > 128)
+            throw new Error("INVALID_CALL_REACH");
+        if (reason === "answered_elsewhere" && winningClientInstanceId && winningClientInstanceId === this.options.clientInstanceId)
+            return "suppressed";
+        this.rememberTerminal(callId);
+        if (this.state.callId === callId && !["idle", "ended"].includes(this.state.phase)) {
+            this.release();
+            this.update({ phase: "ended", reason });
+        }
+        this.settleAttach(callId, "suppressed");
+        return "handled";
+    }
+    rememberTerminal(callId) {
+        this.terminalCalls.set(callId, Date.now());
+        for (const [id, time] of this.terminalCalls)
+            if (Date.now() - time > 300000)
+                this.terminalCalls.delete(id);
+        while (this.terminalCalls.size > 2000)
+            this.terminalCalls.delete(this.terminalCalls.keys().next().value);
+    }
     watchPeer(peerId) {
         this.update({ watchedPeerId: peerId, peerOnline: undefined, peerInCall: undefined });
         if (this.state.ready)
@@ -113,6 +197,8 @@ export class CallClient {
         }
     }
     hangup() {
+        if (this.state.callId)
+            this.rememberTerminal(this.state.callId);
         if (this.state.callId && !["idle", "ended"].includes(this.state.phase))
             this.send({ type: "hangup", callId: this.state.callId });
         this.release();
@@ -186,6 +272,8 @@ export class CallClient {
         this.closed = true;
         clearTimeout(this.reconnect);
         clearInterval(this.heartbeat);
+        for (const callId of [...this.attachWaiters.keys()])
+            this.settleAttach(callId, new Error("CALL_CLIENT_CLOSED"));
         this.hangup();
         this.ws?.close();
         this.ws = undefined;
@@ -225,6 +313,8 @@ export class CallClient {
     async receive(message) {
         if (message.type === "ready") {
             this.update({ ready: true, error: undefined });
+            for (const callId of new Set([...this.attachWaiters.keys(), ...(this.attachId ? [this.attachId] : [])]))
+                this.send({ type: "call.attach", callId });
             if (this.state.watchedPeerId)
                 this.send({ type: "presence.watch", peerId: this.state.watchedPeerId });
             if (this.groupIds.length)
@@ -256,26 +346,63 @@ export class CallClient {
             }
             if (message.requestId && message.requestId !== this.requestId)
                 return;
+            if (typeof message.callId === "string" && this.attachWaiters.has(message.callId))
+                this.settleAttach(message.callId, new Error(message.code ?? "CALL_ATTACH_FAILED"));
             if (!message.callId || message.callId === this.state.callId)
                 this.fail(message.code);
             return;
         }
+        if (message.type === "call.status") {
+            if (message.callId !== this.attachId && !this.attachWaiters.has(message.callId))
+                return;
+            if (message.state === "ended") {
+                this.rememberTerminal(message.callId);
+                if (["idle", "ended"].includes(this.state.phase) || this.state.callId === message.callId) {
+                    this.release();
+                    this.update({ phase: "ended", callId: message.callId, reason: message.reason });
+                }
+            }
+            this.settleAttach(message.callId, message.state === "accepted" && message.callId === this.state.callId ? "handled" : "suppressed");
+            return;
+        }
         if (message.type === "ringing") {
+            if (this.terminalCalls.has(message.callId)) {
+                this.settleAttach(message.callId, "suppressed");
+                return;
+            }
+            if (message.callId === this.state.callId && ["incoming", "ringing", "connecting", "connected"].includes(this.state.phase)) {
+                this.settleAttach(message.callId, "handled");
+                return;
+            }
+            if (typeof message.expiresAt === "number" && message.expiresAt <= Date.now()) {
+                this.rememberTerminal(message.callId);
+                this.settleAttach(message.callId, "suppressed");
+                return;
+            }
+            if (this.attachId === message.callId)
+                this.attachId = undefined;
             if (message.direction === "outgoing" && (this.state.phase !== "requesting" || message.requestId !== this.requestId)) {
                 this.send({ type: "hangup", callId: message.callId });
                 return;
             }
             if (message.direction === "incoming" && !["idle", "ended"].includes(this.state.phase)) {
                 this.send({ type: "hangup", callId: message.callId });
+                this.settleAttach(message.callId, "suppressed");
                 return;
             }
             this.update({ phase: message.direction === "incoming" ? "incoming" : "ringing", callId: message.callId, peerId: message.peerId, direction: message.direction, error: undefined, reason: undefined, startedAt: undefined });
-            this.armTimeout(35000);
+            this.armTimeout(typeof message.expiresAt === "number" ? Math.max(1, message.expiresAt - Date.now()) : 35000);
+            this.settleAttach(message.callId, "handled");
             return;
         }
+        if (message.type === "ended" && typeof message.callId === "string") {
+            this.rememberTerminal(message.callId);
+            this.settleAttach(message.callId, "suppressed");
+        }
         if (message.callId !== this.state.callId)
             return;
         if (message.type === "ended") {
+            this.rememberTerminal(message.callId);
             const event = { callId: message.callId, peerId: this.state.peerId, direction: this.state.direction, reason: message.reason, durationMs: message.durationMs };
             this.release();
             this.update({ phase: "ended", reason: message.reason });

package/lib/runtime/chatClient.d.ts

@@ -1,3 +1,4 @@
+import { type OnlineReachHandler } from "./reach.js";
 import { type OnlineNotificationHandler } from "./notification.js";
 import { type ChatPresence } from "./presence.js";
 import { type ChatUpdate } from "./updates.js";
@@ -10,6 +11,7 @@ export type ChatConnectionState = "connecting" | "reconnecting" | "authenticatin
 export type ChatClientOptions = {
     appId: string;
     clientInstanceId?: string;
+    onReach?: OnlineReachHandler;
     onNotification?: OnlineNotificationHandler;
     profileId?: string;
     botKey?: PmateBotKeyFile | string | unknown;
@@ -27,6 +29,7 @@ export type ChatClientOptions = {
 export declare class ChatClient {
     private readonly options;
     private readonly instanceId;
+    private readonly reach;
     private readonly notifications;
     private presence?;
     private presenceProfiles;

package/lib/runtime/chatClient.js

@@ -1,3 +1,4 @@
+import { OnlineReachReceiver } from "./reach.js";
 import { OnlineNotificationReceiver } from "./notification.js";
 import { ChatPresenceClient } from "./presence.js";
 import { parseChatUpdate } from "./updates.js";
@@ -11,6 +12,7 @@ const DEFAULT_ACK_TIMEOUT_MS = 5_000;
 export class ChatClient {
     options;
     instanceId;
+    reach;
     notifications;
     presence;
     presenceProfiles = [];
@@ -36,6 +38,7 @@ export class ChatClient {
     constructor(options) {
         this.options = options;
         this.instanceId = options.clientInstanceId ?? crypto.randomUUID();
+        this.reach = new OnlineReachReceiver({ appId: options.appId, profileId: () => this.profileId(), send: message => this.requireClient().sendMsg(message), handler: options.onReach });
         this.notifications = new OnlineNotificationReceiver({ appId: options.appId, profileId: () => this.profileId(),
             send: message => this.requireClient().sendMsg(message), handler: options.onNotification });
         if (options.botKey) {
@@ -268,7 +271,7 @@ export class ChatClient {
         const auth = createRuntimeMsg(profileId, "@hub", ChatMsgOp.AUTH, {
             token,
             appId: this.options.appId,
-            notificationReceiver: !!this.options.onNotification,
+            notificationReceiver: !!(this.options.onNotification || this.options.onReach),
             as: "user",
             profileId,
             clientInstanceId: this.instanceId,
@@ -303,7 +306,7 @@ export class ChatClient {
     handleIncoming(message) {
         if (message.opcode === ChatMsgOp.NOTIFICATION) {
             if (this.connection === "connected")
-                void this.notifications.receive(message).catch(error => this.options.onActivityError?.(error));
+                void (message.from === "@hub/reach" ? this.reach.receive(message) : this.notifications.receive(message)).catch(error => this.options.onActivityError?.(error));
             return;
         }
         const update = parseChatUpdate(message, this.options.appId);

package/lib/runtime/index.d.ts

@@ -14,3 +14,4 @@ export * from "./presence.js";
 export * from "./meeting.js";
 export * from "./notification.js";
 export * from "./readSync.js";
+export * from "./reach.js";

package/lib/runtime/index.js

@@ -14,3 +14,4 @@ export * from "./presence.js";
 export * from "./meeting.js";
 export * from "./notification.js";
 export * from "./readSync.js";
+export * from "./reach.js";

package/lib/runtime/notification.d.ts

@@ -9,7 +9,7 @@ export type OnlineNotification = {
     createdAtMs?: number;
     expiresAtMs?: number;
 };
-export type NotificationHandling = "displayed" | "suppressed";
+export type NotificationHandling = "displayed" | "suppressed" | "handled";
 export type OnlineNotificationHandler = (notification: OnlineNotification) => Promise<NotificationHandling>;
 /** Device-local receipt and deduplication; only the host can confirm presentation. */
 export declare class OnlineNotificationReceiver {
@@ -20,6 +20,7 @@ export declare class OnlineNotificationReceiver {
         appId: string;
         profileId: () => string;
         send: (message: ChatRuntimeMessage) => Promise<void>;
+        source?: "@hub/notifications" | "@hub/reach";
         handler?: OnlineNotificationHandler;
         now?: () => number;
     });

package/lib/runtime/notification.js

@@ -8,13 +8,13 @@ export class OnlineNotificationReceiver {
         this.options = options;
     }
     async receive(message) {
-        if (message.opcode !== ChatMsgOp.NOTIFICATION || message.from !== "@hub/notifications" || message.to !== this.options.profileId())
+        if (message.opcode !== ChatMsgOp.NOTIFICATION || message.from !== (this.options.source ?? "@hub/notifications") || message.to !== this.options.profileId())
             return;
         const body = message.body;
         if (!body || body.kind !== "delivery" || typeof body.attemptId !== "string" || !body.attemptId
             || typeof body.notificationId !== "string" || !body.notificationId)
             return;
-        const ack = (status, code) => this.options.send(createRuntimeMsg(this.options.profileId(), "@hub/notifications", ChatMsgOp.NOTIFICATION, {
+        const ack = (status, code) => this.options.send(createRuntimeMsg(this.options.profileId(), this.options.source ?? "@hub/notifications", ChatMsgOp.NOTIFICATION, {
             kind: "ack", attemptId: body.attemptId, notificationId: body.notificationId, status,
             displayed: status === "displayed", code, receivedAtMs: this.now(),
         }));
@@ -44,7 +44,7 @@ export class OnlineNotificationReceiver {
                 if (!this.options.handler)
                     throw new Error("Notification host unavailable");
                 const status = await this.options.handler(structuredClone(body));
-                if (status !== "displayed" && status !== "suppressed")
+                if (status !== "displayed" && status !== "suppressed" && status !== "handled")
                     throw new Error("Invalid notification handling result");
                 if (this.handled.size >= 10_000)
                     this.handled.delete(this.handled.keys().next().value);

package/lib/runtime/reach.d.ts

@@ -0,0 +1,23 @@
+import type { ChatRuntimeMessage } from "./protocol.js";
+export type ReachEventType = "call.incoming" | "call.ended" | "social.readStateChanged" | "meeting.invitation" | "meeting.ended";
+export type OnlineReachEvent = {
+    eventId: string;
+    eventType: ReachEventType;
+    appId: string;
+    payload: Record<string, unknown>;
+    createdAtMs?: number;
+    expiresAtMs: number;
+};
+export type OnlineReachHandler = (event: OnlineReachEvent) => Promise<"handled" | "suppressed">;
+/** Uses the verified Hub envelope; handling confirms business processing, never reading. */
+export declare class OnlineReachReceiver {
+    private readonly receiver;
+    constructor(options: {
+        appId: string;
+        profileId: () => string;
+        send: (message: ChatRuntimeMessage) => Promise<void>;
+        handler?: OnlineReachHandler;
+        now?: () => number;
+    });
+    receive(message: ChatRuntimeMessage): Promise<void>;
+}

package/lib/runtime/reach.js

@@ -0,0 +1,18 @@
+import { OnlineNotificationReceiver } from "./notification.js";
+const types = ["call.incoming", "call.ended", "social.readStateChanged", "meeting.invitation", "meeting.ended"];
+/** Uses the verified Hub envelope; handling confirms business processing, never reading. */
+export class OnlineReachReceiver {
+    receiver;
+    constructor(options) {
+        this.receiver = new OnlineNotificationReceiver({ ...options, source: "@hub/reach", handler: async (notification) => {
+                const { eventId, eventType, appId, payload } = notification.data;
+                if (eventId !== notification.notificationId || !types.includes(eventType) || typeof appId !== "string"
+                    || !payload || typeof payload !== "object" || Array.isArray(payload) || !Number.isFinite(notification.expiresAtMs))
+                    throw new Error("INVALID_REACH_EVENT");
+                if (!options.handler)
+                    throw new Error("REACH_HANDLER_UNAVAILABLE");
+                return options.handler({ eventId: notification.notificationId, eventType: eventType, appId, payload: payload, createdAtMs: notification.createdAtMs, expiresAtMs: notification.expiresAtMs });
+            } });
+    }
+    receive(message) { return this.receiver.receive(message); }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmate/chat-sdk",
-  "version": "0.9.7",
+  "version": "0.9.9",
   "description": "Cross-platform PMate chat input components, voice input primitives, and ASR helpers",
   "type": "module",
   "main": "./lib/index.js",
@@ -28,15 +28,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "clean": "rimraf lib",
-    "build": "pnpm run clean && tsc -p tsconfig.build.json && cp src/voice/recorder-processor.js lib/voice/recorder-processor.js",
-    "prepack": "pnpm run build",
-    "npm:publish": "pnpm run build && npm publish --access public --registry https://registry.npmjs.org/",
-    "test": "vitest run",
-    "storybook": "storybook dev -p 6009",
-    "build-storybook": "storybook build --output-dir dist"
-  },
   "dependencies": {
     "@emoji-mart/data": "^1.2.1",
     "@emoji-mart/react": "^1.1.1",
@@ -51,16 +42,24 @@
   "devDependencies": {
     "@storybook/addon-docs": "^9.0.17",
     "@storybook/react-vite": "9.0.17",
-    "@tailwindcss/vite": "catalog:",
-    "@types/react": "catalog:",
-    "@types/react-dom": "catalog:",
+    "@tailwindcss/vite": "^4.1.3",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
     "fake-indexeddb": "^6.2.5",
-    "react": "catalog:",
-    "react-dom": "catalog:",
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1",
     "rimraf": "^6.1.2",
     "storybook": "^9.0.17",
-    "tailwindcss": "catalog:",
+    "tailwindcss": "^4.0.14",
     "typescript": "5.9.2",
     "vitest": "^4.0.17"
+  },
+  "scripts": {
+    "clean": "rimraf lib",
+    "build": "pnpm run clean && tsc -p tsconfig.build.json && cp src/voice/recorder-processor.js lib/voice/recorder-processor.js",
+    "npm:publish": "pnpm run build && npm publish --access public --registry https://registry.npmjs.org/",
+    "test": "vitest run",
+    "storybook": "storybook dev -p 6009",
+    "build-storybook": "storybook build --output-dir dist"
   }
-}
+}