@pmate/chat-sdk 0.3.0 → 0.4.0

package/lib/runtime/activity.d.ts

@@ -0,0 +1,68 @@
+import { type ChatRuntimeMessage } from "./protocol.js";
+export type ChatActivityState = "thinking" | "searching" | "reading" | "typing" | "idle";
+export type ChatActivityBody = {
+    kind: "activity";
+    appId: string;
+    threadKind: "dm" | "group";
+    activityId: string;
+    seq: number;
+    state: ChatActivityState;
+    ttlMs: number;
+    /** Short public operation label, never private model reasoning. */
+    detail?: string;
+};
+export type ChatActivity = ChatActivityBody & {
+    from: string;
+    to: string;
+    threadId: string;
+    updatedAt: number;
+    expiresAt: number;
+};
+export type ActivityTarget = {
+    to: string;
+    threadKind?: "dm" | "group";
+    recipients?: string[];
+};
+export declare const ACTIVITY_TTL_MS = 15000;
+export declare function createActivityMessage(input: ActivityTarget & {
+    from: string;
+    appId: string;
+    activityId: string;
+    seq: number;
+    state: ChatActivityState;
+    detail?: string;
+}): ChatRuntimeMessage;
+export declare function parseChatActivity(message: ChatRuntimeMessage, appId: string, profileId: string, now?: number): ChatActivity | null;
+/** Keeps ordering tombstones after completion so a late heartbeat cannot revive an activity. */
+export declare class ChatActivityStore {
+    private records;
+    private listeners;
+    private timer;
+    watch(listener: (activities: ChatActivity[]) => void): () => void;
+    snapshot(now?: number): ChatActivity[];
+    accept(activity: ChatActivity): void;
+    completeMessage(message: ChatRuntimeMessage, appId: string): void;
+    clear(): void;
+    private emit;
+}
+/** Coalesced, serialized, best-effort progress; transport failures never reject the chat task. */
+export declare class ChatActivityPublisher {
+    private readonly send;
+    private readonly onError;
+    private seq;
+    private stopped;
+    private state;
+    private detail;
+    private pending;
+    private sending;
+    private timer;
+    constructor(send: (value: {
+        state: ChatActivityState;
+        detail?: string;
+        seq: number;
+    }) => Promise<unknown>, onError?: (error: unknown) => void);
+    update(state: Exclude<ChatActivityState, "idle">, detail?: string): void;
+    stop(): Promise<void>;
+    private enqueue;
+    private flush;
+}

package/lib/runtime/activity.js

@@ -0,0 +1,121 @@
+import { ChatMsgOp, createRuntimeMsg } from "./protocol.js";
+import { dmThreadId, groupThreadId } from "./thread.js";
+export const ACTIVITY_TTL_MS = 15_000;
+export function createActivityMessage(input) {
+    const body = { kind: "activity", appId: input.appId, threadKind: input.threadKind ?? "dm", activityId: input.activityId, seq: input.seq, state: input.state, ttlMs: ACTIVITY_TTL_MS,
+        ...(input.detail ? { detail: Array.from(input.detail).slice(0, 120).join("") } : {}) };
+    const message = createRuntimeMsg(input.from, input.to, ChatMsgOp.CHAT, body);
+    if (body.threadKind === "group")
+        message.recipients = input.recipients ?? [];
+    return message;
+}
+export function parseChatActivity(message, appId, profileId, now = Date.now()) {
+    const body = message.body;
+    if (message.opcode !== ChatMsgOp.CHAT || body?.kind !== "activity" || body.appId !== appId || !message.from || message.from === profileId || !message.to
+        || (body.threadKind !== "dm" && body.threadKind !== "group")
+        || (body.threadKind === "dm" ? message.to !== profileId : !message.recipients?.includes(profileId))
+        || typeof body.activityId !== "string" || !body.activityId || body.activityId.length > 128
+        || !Number.isSafeInteger(body.seq) || body.seq < 0
+        || !["thinking", "searching", "reading", "typing", "idle"].includes(body.state ?? "")
+        || !Number.isFinite(body.ttlMs) || body.ttlMs < 1000 || body.ttlMs > ACTIVITY_TTL_MS
+        || !Number.isFinite(message.t) || message.t > now + ACTIVITY_TTL_MS || message.t + body.ttlMs <= now
+        || (body.detail !== undefined && (typeof body.detail !== "string" || Array.from(body.detail).length > 120)))
+        return null;
+    return { ...body, from: message.from, to: message.to,
+        threadId: body.threadKind === "dm" ? dmThreadId(appId, message.from, profileId) : groupThreadId(appId, message.to),
+        updatedAt: message.t, expiresAt: Math.min(message.t + body.ttlMs, now + ACTIVITY_TTL_MS) };
+}
+/** Keeps ordering tombstones after completion so a late heartbeat cannot revive an activity. */
+export class ChatActivityStore {
+    records = new Map();
+    listeners = new Set();
+    timer;
+    watch(listener) { this.listeners.add(listener); listener(this.snapshot()); return () => { this.listeners.delete(listener); }; }
+    snapshot(now = Date.now()) { return [...this.records.values()].filter(a => a.state !== "idle" && a.expiresAt > now); }
+    accept(activity) {
+        const key = JSON.stringify([activity.threadId, activity.from, activity.activityId]);
+        const previous = this.records.get(key);
+        if (previous && (previous.state === "idle" || previous.seq >= activity.seq))
+            return;
+        this.records.set(key, activity);
+        // Bound memory for long-running clients. Expired tombstones are retained for five minutes.
+        for (const [id, record] of this.records)
+            if (record.expiresAt + 300_000 < Date.now())
+                this.records.delete(id);
+        while (this.records.size > 1000)
+            this.records.delete(this.records.keys().next().value);
+        this.emit();
+    }
+    completeMessage(message, appId) {
+        const body = message.body;
+        if (body?.kind !== "message" || body.content?.appId !== appId)
+            return;
+        let changed = false;
+        for (const [key, record] of this.records) {
+            if (record.from === message.from && record.to === message.to && record.threadKind === body.threadKind && record.updatedAt <= message.t && record.state !== "idle") {
+                this.records.set(key, { ...record, state: "idle" });
+                changed = true;
+            }
+        }
+        if (changed)
+            this.emit();
+    }
+    clear() { this.records.clear(); this.emit(); }
+    emit() {
+        clearTimeout(this.timer);
+        const active = this.snapshot();
+        for (const listener of this.listeners)
+            listener(active);
+        if (active.length)
+            this.timer = setTimeout(() => this.emit(), Math.max(1, Math.min(...active.map(a => a.expiresAt)) - Date.now()));
+    }
+}
+/** Coalesced, serialized, best-effort progress; transport failures never reject the chat task. */
+export class ChatActivityPublisher {
+    send;
+    onError;
+    seq = 0;
+    stopped = false;
+    state = "thinking";
+    detail;
+    pending;
+    sending;
+    timer;
+    constructor(send, onError = () => { }) {
+        this.send = send;
+        this.onError = onError;
+        this.timer = setInterval(() => this.enqueue(this.state, this.detail), 5000);
+    }
+    update(state, detail) {
+        if (this.stopped)
+            return;
+        this.state = state;
+        this.detail = detail;
+        this.enqueue(state, detail);
+    }
+    async stop() {
+        if (!this.stopped) {
+            this.stopped = true;
+            clearInterval(this.timer);
+            this.enqueue("idle");
+        }
+        await this.sending;
+    }
+    enqueue(state, detail) {
+        this.pending = { state, detail };
+        if (!this.sending)
+            this.sending = this.flush().finally(() => { this.sending = undefined; });
+    }
+    async flush() {
+        while (this.pending) {
+            const current = this.pending;
+            this.pending = undefined;
+            try {
+                await this.send({ ...current, seq: this.seq++ });
+            }
+            catch (error) {
+                this.onError(error);
+            }
+        }
+    }
+}

package/lib/runtime/chatClient.d.ts

@@ -1,3 +1,4 @@
+import { ChatActivityPublisher, type ActivityTarget, type ChatActivity, type ChatActivityState } from "./activity.js";
 import type { ChatMention } from "../mentions/model";
 import { type BotLoginSession } from "./botAuth.js";
 import { type PmateBotKeyFile } from "./botKey.js";
@@ -11,6 +12,7 @@ export type ChatClientOptions = {
     authBaseUrl?: string;
     realtimeClient?: RealtimeClient;
     fetchImpl?: typeof fetch;
+    onActivityError?: (error: unknown) => void;
     ackTimeoutMs?: number;
 };
 export declare class ChatClient {
@@ -19,12 +21,22 @@ export declare class ChatClient {
     private session;
     private profileIdValue;
     private botKey;
+    private readonly activities;
+    private readonly publishers;
     private readonly pendingAcks;
     private readonly messageHandlers;
     constructor(options: ChatClientOptions);
     connect(): Promise<this>;
     close(): void;
     watchMessages(handler: (message: ChatRuntimeMessage) => void): () => boolean;
+    watchActivities(handler: (activities: ChatActivity[]) => void): () => void;
+    sendActivity(input: ActivityTarget & {
+        activityId: string;
+        seq: number;
+        state: ChatActivityState;
+        detail?: string;
+    }): Promise<ChatRuntimeMessage>;
+    startActivity(target: ActivityTarget, state?: Exclude<ChatActivityState, "idle">): ChatActivityPublisher;
     requestFriend(input: {
         to: string;
         message?: string;

package/lib/runtime/chatClient.js

@@ -1,3 +1,4 @@
+import { ChatActivityStore, ChatActivityPublisher, createActivityMessage, parseChatActivity } from "./activity.js";
 import { loginPmateBot } from "./botAuth.js";
 import { parsePmateBotKeyJson } from "./botKey.js";
 import { ChatMsgKind, ChatMsgOp, ChatRealtimeEvents, RuntimeWebsocketClient, createRuntimeMsg, } from "./protocol.js";
@@ -10,6 +11,8 @@ export class ChatClient {
     session = null;
     profileIdValue = null;
     botKey = null;
+    activities = new ChatActivityStore();
+    publishers = new Set();
     pendingAcks = new Map();
     messageHandlers = new Set();
     constructor(options) {
@@ -39,11 +42,17 @@ export class ChatClient {
         this.client.on(ChatRealtimeEvents.Message, (message) => {
             this.handleIncoming(message);
         });
+        this.client.on(ChatRealtimeEvents.Connected, (connected) => { if (!connected)
+            this.activities.clear(); });
         await this.waitUntilConnected();
         await this.sendAuth();
         return this;
     }
     close() {
+        for (const publisher of this.publishers)
+            void publisher.stop();
+        this.publishers.clear();
+        this.activities.clear();
         this.client?.close();
         this.client = null;
         for (const pending of this.pendingAcks.values()) {
@@ -56,6 +65,21 @@ export class ChatClient {
         this.messageHandlers.add(handler);
         return () => this.messageHandlers.delete(handler);
     }
+    watchActivities(handler) { return this.activities.watch(handler); }
+    async sendActivity(input) {
+        const message = createActivityMessage({ ...input, from: this.profileId(), appId: this.options.appId });
+        await this.sendAndWaitForAck(message);
+        return message;
+    }
+    startActivity(target, state = "typing") {
+        const activityId = createRuntimeMsg(this.profileId(), target.to, ChatMsgOp.CHAT, null).hash;
+        const publisher = new ChatActivityPublisher(value => this.sendActivity({ ...target, activityId, ...value }), error => this.options.onActivityError?.(error));
+        this.publishers.add(publisher);
+        const stop = publisher.stop.bind(publisher);
+        publisher.stop = async () => { await stop(); this.publishers.delete(publisher); };
+        publisher.update(state);
+        return publisher;
+    }
     async requestFriend(input) {
         return this.sendContactAction(input.to, "friendRequest", {
             message: input.message,
@@ -145,7 +169,17 @@ export class ChatClient {
             }, this.options.ackTimeoutMs ?? DEFAULT_ACK_TIMEOUT_MS);
             this.pendingAcks.set(msg.hash, { resolve, reject, timer });
         });
-        await client.sendMsg(msg);
+        try {
+            await client.sendMsg(msg);
+        }
+        catch (error) {
+            const pending = this.pendingAcks.get(msg.hash);
+            if (pending) {
+                clearTimeout(pending.timer);
+                this.pendingAcks.delete(msg.hash);
+                pending.reject(error instanceof Error ? error : new Error("Send failed"));
+            }
+        }
         return ack;
     }
     handleIncoming(message) {
@@ -165,6 +199,13 @@ export class ChatClient {
             return;
         }
         if (message.opcode === ChatMsgOp.CHAT) {
+            if (message.body?.kind === "activity") {
+                const activity = parseChatActivity(message, this.options.appId, this.profileId());
+                if (activity)
+                    this.activities.accept(activity);
+                return;
+            }
+            this.activities.completeMessage(message, this.options.appId);
             for (const handler of this.messageHandlers) {
                 handler(message);
             }

package/lib/runtime/index.d.ts

@@ -4,3 +4,4 @@ export * from "./chatClient.js";
 export * from "./protocol.js";
 export * from "./readerClient.js";
 export * from "./thread.js";
+export * from "./activity.js";

package/lib/runtime/index.js

@@ -4,3 +4,4 @@ export * from "./chatClient.js";
 export * from "./protocol.js";
 export * from "./readerClient.js";
 export * from "./thread.js";
+export * from "./activity.js";

package/lib/runtime/protocol.d.ts

@@ -1,3 +1,4 @@
+import type { ChatActivityBody } from "./activity.js";
 export declare const ChatMsgOp: {
     readonly CHAT: 1;
     readonly ACK: 3;
@@ -12,7 +13,7 @@ export declare const ChatRealtimeEvents: {
     readonly Error: "error";
     readonly Message: "message";
 };
-export type ChatBody = {
+export type ChatBody = ChatActivityBody | {
     kind: "message";
     threadKind: "dm" | "group";
     contentKind: "text" | "image" | "emoji";

package/package.json

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