@pmate/chat-sdk 0.9.6 → 0.9.8

package/lib/runtime/call.d.ts

@@ -58,6 +58,8 @@ export declare class CallClient {
     private generation;
     private closed;
     private capturePending;
+    private attachId?;
+    private terminalCalls;
     private requestId?;
     private groupIds;
     private heartbeat?;
@@ -68,6 +70,9 @@ 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;
+    private rememberTerminal;
     watchPeer(peerId?: string): void;
     watchGroups(groupIds: string[]): void;
     start(peerId: string): Promise<void>;

package/lib/runtime/call.js

@@ -12,6 +12,8 @@ export class CallClient {
     generation = 0;
     closed = false;
     capturePending = false;
+    attachId;
+    terminalCalls = new Map();
     requestId;
     groupIds = [];
     heartbeat;
@@ -59,6 +61,24 @@ 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();
+    }
+    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 +133,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();
@@ -225,6 +247,8 @@ export class CallClient {
     async receive(message) {
         if (message.type === "ready") {
             this.update({ ready: true, error: undefined });
+            if (this.attachId)
+                this.send({ type: "call.attach", callId: this.attachId });
             if (this.state.watchedPeerId)
                 this.send({ type: "presence.watch", peerId: this.state.watchedPeerId });
             if (this.groupIds.length)
@@ -260,7 +284,30 @@ export class CallClient {
                 this.fail(message.code);
             return;
         }
+        if (message.type === "call.status") {
+            if (message.callId !== this.attachId)
+                return;
+            this.attachId = undefined;
+            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 });
+                }
+            }
+            return;
+        }
         if (message.type === "ringing") {
+            if (this.terminalCalls.has(message.callId))
+                return;
+            if (message.callId === this.state.callId && ["incoming", "ringing", "connecting", "connected"].includes(this.state.phase))
+                return;
+            if (typeof message.expiresAt === "number" && message.expiresAt <= Date.now()) {
+                this.rememberTerminal(message.callId);
+                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;
@@ -270,12 +317,15 @@ export class CallClient {
                 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);
             return;
         }
+        if (message.type === "ended" && typeof message.callId === "string")
+            this.rememberTerminal(message.callId);
         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/lib/runtime/readSync.js

@@ -1,4 +1,4 @@
-import { createReadIndex, installReadSnapshot } from "./readIndex.js";
+import { applyReadChange, ReadSyncGap, createReadIndex, installReadSnapshot } from "./readIndex.js";
 /** Keeps local operations until an authoritative projection covers them. */
 export class ReadSyncClient {
     options;
@@ -57,6 +57,31 @@ export class ReadSyncClient {
             this.readAfter = Math.max(this.readAfter, receipt.acceptedAt);
         }
         const query = new URLSearchParams({ appId, profileId });
+        if (!this.readAfter && current.syncCursor !== "0") {
+            const delta = await this.request(`/api/social/reading/changes?${new URLSearchParams({ appId, profileId, after: current.syncCursor })}`);
+            if (delta.appId !== appId || delta.profileId !== profileId || typeof delta.syncCursor !== "string"
+                || typeof delta.snapshotRequired !== "boolean" || !Array.isArray(delta.changes))
+                throw new Error("INVALID_READ_DELTA");
+            if (!delta.snapshotRequired) {
+                try {
+                    if (this.controller.signal.aborted)
+                        throw new Error("READ_SYNC_STOPPED");
+                    const next = await persistence.update(appId, profileId, state => {
+                        const applied = delta.changes.reduce(applyReadChange, state);
+                        if (applied.syncCursor !== delta.syncCursor)
+                            throw new ReadSyncGap(applied.syncCursor);
+                        return applied;
+                    });
+                    if (!this.controller.signal.aborted)
+                        this.options.onChange?.(next);
+                    return next;
+                }
+                catch (error) {
+                    if (!(error instanceof ReadSyncGap))
+                        throw error;
+                }
+            }
+        }
         const snapshot = await this.request(`/api/social/reading/snapshot?${query}`, {
             headers: this.readAfter ? { "x-pmate-read-after-time": String(this.readAfter) } : {},
         });
@@ -64,6 +89,8 @@ export class ReadSyncClient {
             throw new Error("READ_SYNC_STOPPED");
         // Merge into the latest transaction, including reads made while HTTP was pending.
         const next = await persistence.update(appId, profileId, state => installReadSnapshot(state, snapshot));
+        if (!next.pending.length)
+            this.readAfter = 0;
         if (!this.controller.signal.aborted)
             this.options.onChange?.(next);
         return next;

package/package.json

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