@pmate/chat-sdk 0.2.3 → 0.4.0

package/lib/mentions/model.d.ts

@@ -0,0 +1,28 @@
+/** Host-owned identity; names need not be unique. */
+export type MentionCandidate = {
+    id: string;
+    name: string;
+    avatar?: string;
+    description?: string;
+};
+/** UTF-16 offsets [start, end) in the sent text, including @. */
+export type ChatMention = {
+    id: string;
+    name: string;
+    start: number;
+    end: number;
+};
+export type MentionQuery = {
+    start: number;
+    end: number;
+    query: string;
+};
+export type MentionConfig = {
+    candidates: MentionCandidate[];
+    label?: string;
+    emptyText?: string;
+};
+export declare function findMentionQuery(text: string, caret: number): MentionQuery | null;
+export declare function filterMentionCandidates(candidates: MentionCandidate[], query: string): MentionCandidate[];
+/** Rebase untouched mentions; editing any part of a mention removes its identity. */
+export declare function rebaseMentions(previous: string, next: string, mentions: ChatMention[]): ChatMention[];

package/lib/mentions/model.js

@@ -0,0 +1,40 @@
+export function findMentionQuery(text, caret) {
+    const before = text.slice(0, caret);
+    // Require a word boundary so email addresses and URLs remain ordinary text.
+    const match = /(?:^|[\s([{，。！？、：；])@([^\s@]{0,64})$/u.exec(before);
+    if (!match)
+        return null;
+    return { start: caret - match[1].length - 1, end: caret, query: match[1] };
+}
+export function filterMentionCandidates(candidates, query) {
+    const seen = new Set();
+    return candidates.filter(candidate => {
+        if (seen.has(candidate.id))
+            return false;
+        seen.add(candidate.id);
+        return candidate.name.toLocaleLowerCase().includes(query.toLocaleLowerCase());
+    });
+}
+/** Rebase untouched mentions; editing any part of a mention removes its identity. */
+export function rebaseMentions(previous, next, mentions) {
+    if (previous === next)
+        return mentions;
+    let start = 0;
+    while (start < previous.length && start < next.length && previous[start] === next[start])
+        start++;
+    let oldEnd = previous.length, newEnd = next.length;
+    while (oldEnd > start && newEnd > start && previous[oldEnd - 1] === next[newEnd - 1]) {
+        oldEnd--;
+        newEnd--;
+    }
+    const delta = newEnd - oldEnd;
+    return mentions.flatMap(mention => {
+        if (mention.end <= start)
+            return [mention];
+        if (mention.start >= oldEnd)
+            return [{ ...mention, start: mention.start + delta, end: mention.end + delta }];
+        return [];
+    }).filter(mention => next.slice(mention.start, mention.end) === `@${mention.name}`
+        && (mention.start === 0 || /[\s([{，。！？、：；]/u.test(next[mention.start - 1]))
+        && (mention.end === next.length || !/[\p{L}\p{N}_@]/u.test(next[mention.end])));
+}

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,5 @@
+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";
 import { type ChatBody, type ChatRuntimeMessage, type RealtimeClient } from "./protocol.js";
@@ -10,6 +12,7 @@ export type ChatClientOptions = {
     authBaseUrl?: string;
     realtimeClient?: RealtimeClient;
     fetchImpl?: typeof fetch;
+    onActivityError?: (error: unknown) => void;
     ackTimeoutMs?: number;
 };
 export declare class ChatClient {
@@ -18,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;
@@ -55,6 +68,7 @@ export declare class ChatClient {
         groupId: string;
         text: string;
         recipients?: string[];
+        mentions?: ChatMention[];
     }): Promise<ChatRuntimeMessage>;
     sendChat(to: string, body: ChatBody, recipients?: string[]): Promise<ChatRuntimeMessage>;
     private sendContactAction;

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,
@@ -104,7 +128,7 @@ export class ChatClient {
             kind: "message",
             threadKind: "group",
             contentKind: "text",
-            content: { appId: this.options.appId, groupId: input.groupId, text: input.text },
+            content: { appId: this.options.appId, groupId: input.groupId, text: input.text, ...(input.mentions?.length ? { mentions: input.mentions } : {}) },
         }, input.recipients);
     }
     async sendChat(to, body, recipients) {
@@ -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/lib/types/chatInput.d.ts

@@ -1,3 +1,4 @@
+import type { MentionConfig, ChatMention } from "../mentions/model";
 import type { ClipboardEventHandler, ComponentType, DragEventHandler, ReactNode } from "react";
 import type { ChatAttachment } from "./attachment";
 import type { ChatVoiceConfig } from "./voice";
@@ -120,6 +121,8 @@ export type ChatImageConfig = {
     uploadImage?: (file: File) => Promise<ChatImageUploadResult>;
 };
 export type ChatInputBaseProps = {
+    /** Group members supplied by the host; omit for ordinary text input. */
+    mentions?: MentionConfig;
     /** Use a taller composer with actions in a bottom toolbar. */
     multiline?: boolean;
     value?: string;
@@ -131,6 +134,7 @@ export type ChatInputBaseProps = {
     onDrop?: DragEventHandler<HTMLTextAreaElement>;
     onSend?: (payload: {
         text: string;
+        mentions?: ChatMention[];
         attachments: ChatAttachment[];
         transcript?: string;
         audio?: Blob;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmate/chat-sdk",
-  "version": "0.2.3",
+  "version": "0.4.0",
   "description": "Cross-platform PMate chat input components, voice input primitives, and ASR helpers",
   "type": "module",
   "main": "./lib/index.js",
@@ -29,15 +29,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": {
     "@noble/hashes": "^2.4.0",
     "@emoji-mart/data": "^1.2.1",
@@ -52,15 +43,23 @@
   "devDependencies": {
     "@storybook/addon-docs": "^9.0.17",
     "@storybook/react-vite": "9.0.17",
-    "@tailwindcss/vite": "catalog:",
-    "@types/react": "catalog:",
-    "@types/react-dom": "catalog:",
-    "react": "catalog:",
-    "react-dom": "catalog:",
+    "@tailwindcss/vite": "^4.1.3",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "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"
   }
-}
+}