@pmate/chat-sdk 0.8.0 → 0.9.0

package/lib/runtime/chatClient.d.ts

@@ -1,4 +1,5 @@
 import { type ChatPresence } from "./presence.js";
+import { type ChatUpdate } from "./updates.js";
 import { ChatActivityPublisher, type ActivityTarget, type ChatActivity, type ChatActivityState, type ChatActivityUpdate } from "./activity.js";
 import type { ChatMention } from "../mentions/model";
 import { type BotLoginSession } from "./botAuth.js";
@@ -39,6 +40,8 @@ export declare class ChatClient {
     private readonly publishers;
     private readonly pendingAcks;
     private readonly messageHandlers;
+    private readonly updateHandlers;
+    watchUpdates(handler: (update: ChatUpdate) => void): () => void;
     constructor(options: ChatClientOptions);
     connect(): Promise<this>;
     private initialize;

package/lib/runtime/chatClient.js

@@ -1,4 +1,5 @@
 import { ChatPresenceClient } from "./presence.js";
+import { parseChatUpdate } from "./updates.js";
 import { ChatActivityStore, ChatActivityPublisher, createActivityMessage, parseChatActivity } from "./activity.js";
 import { loginPmateBot } from "./botAuth.js";
 import { parsePmateBotKeyJson } from "./botKey.js";
@@ -25,6 +26,11 @@ export class ChatClient {
     publishers = new Set();
     pendingAcks = new Map();
     messageHandlers = new Set();
+    updateHandlers = new Set();
+    watchUpdates(handler) {
+        this.updateHandlers.add(handler);
+        return () => { this.updateHandlers.delete(handler); };
+    }
     constructor(options) {
         this.options = options;
         if (options.botKey) {
@@ -288,6 +294,12 @@ export class ChatClient {
         return ack;
     }
     handleIncoming(message) {
+        const update = parseChatUpdate(message, this.options.appId);
+        if (update) {
+            for (const handler of this.updateHandlers)
+                handler(update);
+            return;
+        }
         if (message.opcode === ChatMsgOp.ACK) {
             const ack = message.body;
             const pending = this.pendingAcks.get(ack.ackOf);

package/lib/runtime/content.d.ts

@@ -0,0 +1,66 @@
+/** Explicit content protocol, transported inside the existing text envelope. */
+export type MarkdownBlock = {
+    id: string;
+    type: "markdown";
+    text: string;
+};
+export type ChartBlock = {
+    id: string;
+    type: "chart";
+    chart: {
+        type: "line" | "bar";
+        title: string;
+        x: string;
+        series: {
+            field: string;
+            label: string;
+            unit: string;
+        }[];
+        data: Record<string, string | number | null>[];
+        evidence: {
+            from: number;
+            to: number;
+            timezone: "UTC" | "Asia/Shanghai";
+            definition: string;
+            source: string;
+            queryId: string;
+            completeness: string;
+        };
+    };
+};
+export type MessageBlock = MarkdownBlock | ChartBlock;
+export type RichMessageContent = {
+    format: "blocks";
+    version: 1;
+    revision: number;
+    blocks: MessageBlock[];
+    text: string;
+};
+export declare const CONTENT_LIMITS: {
+    readonly bytes: 65536;
+    readonly blocks: 20;
+    readonly text: 16000;
+    readonly points: 100;
+    readonly series: 4;
+};
+export declare function safeContentUrl(value: string): string | undefined;
+export declare function validateMessageBlock(value: unknown): value is MessageBlock;
+export type ContentResult = {
+    kind: "legacy";
+} | {
+    kind: "invalid";
+    reason: string;
+} | {
+    kind: "rich";
+    content: RichMessageContent;
+};
+export declare function readMessageContent(value: unknown): ContentResult;
+/** Text projection is generated from blocks, never a second editable source. */
+export declare function messageBlocksText(blocks: MessageBlock[]): string;
+export declare function createRichMessageContent(blocks: MessageBlock[], revision?: number): RichMessageContent;
+/** Ordered updates: incomplete charts remain invisible, replay never duplicates a block. */
+export declare function applyContentUpdate(current: RichMessageContent, update: {
+    revision: number;
+    block: MessageBlock;
+    complete: boolean;
+}): RichMessageContent;

package/lib/runtime/content.js

@@ -0,0 +1,74 @@
+export const CONTENT_LIMITS = { bytes: 65536, blocks: 20, text: 16000, points: 100, series: 4 };
+const object = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+const label = (value, max = 200) => typeof value === "string" && value.trim().length > 0 && value.length <= max;
+export function safeContentUrl(value) {
+    try {
+        const url = new URL(value);
+        return ["https:", "http:", "mailto:"].includes(url.protocol) ? url.href : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function validateMessageBlock(value) {
+    if (!object(value) || !label(value.id, 100))
+        return false;
+    if (value.type === "markdown")
+        return typeof value.text === "string" && value.text.length <= CONTENT_LIMITS.text;
+    if (value.type !== "chart" || !object(value.chart))
+        return false;
+    const c = value.chart, e = c.evidence;
+    if (!["line", "bar"].includes(c.type) || !label(c.title) || !label(c.x, 100) || !Array.isArray(c.series) || !c.series.length || c.series.length > CONTENT_LIMITS.series || !Array.isArray(c.data) || c.data.length > CONTENT_LIMITS.points)
+        return false;
+    if (!c.series.every((s) => object(s) && label(s.field, 100) && label(s.label) && typeof s.unit === "string" && s.unit.length <= 50) || new Set(c.series.map((s) => s.field)).size !== c.series.length || c.series.some((s) => s.field === c.x))
+        return false;
+    if (!c.data.every((row) => object(row) && label(row[c.x]) && c.series.every((s) => row[s.field] === null || typeof row[s.field] === "number" && Number.isFinite(row[s.field]))))
+        return false;
+    return object(e) && Number.isSafeInteger(e.from) && Number.isSafeInteger(e.to) && e.from < e.to && ["UTC", "Asia/Shanghai"].includes(e.timezone) && label(e.definition, 2000) && label(e.completeness, 2000) && label(e.queryId) && label(e.source, 2048) && !!safeContentUrl(e.source);
+}
+export function readMessageContent(value) {
+    if (!object(value) || value.format === undefined)
+        return { kind: "legacy" };
+    if (value.format !== "blocks" || value.version !== 1)
+        return { kind: "invalid", reason: "Unsupported message content version" };
+    if (!Number.isSafeInteger(value.revision) || value.revision < 0 || !Array.isArray(value.blocks) || !value.blocks.length || value.blocks.length > CONTENT_LIMITS.blocks || typeof value.text !== "string" || value.text.length > CONTENT_LIMITS.text)
+        return { kind: "invalid", reason: "Invalid message content" };
+    try {
+        if (new TextEncoder().encode(JSON.stringify(value)).length > CONTENT_LIMITS.bytes)
+            return { kind: "invalid", reason: "Message content exceeds limit" };
+    }
+    catch {
+        return { kind: "invalid", reason: "Invalid message content" };
+    }
+    if (!value.blocks.every(validateMessageBlock) || new Set(value.blocks.map((b) => b.id)).size !== value.blocks.length)
+        return { kind: "invalid", reason: "Invalid or duplicate message block" };
+    return { kind: "rich", content: value };
+}
+/** Text projection is generated from blocks, never a second editable source. */
+export function messageBlocksText(blocks) {
+    return blocks.map(block => block.type === "markdown" ? block.text : [block.chart.title, [block.chart.x, ...block.chart.series.map(s => `${s.label}${s.unit ? ` (${s.unit})` : ""}`)].join("\t"), ...block.chart.data.map(row => [row[block.chart.x], ...block.chart.series.map(s => row[s.field] ?? "缺失 / Missing")].join("\t")), `${new Date(block.chart.evidence.from).toISOString()} – ${new Date(block.chart.evidence.to).toISOString()} (${block.chart.evidence.timezone})`, block.chart.evidence.definition, block.chart.evidence.completeness, block.chart.evidence.source].join("\n")).join("\n\n");
+}
+export function createRichMessageContent(blocks, revision = 0) {
+    const content = { format: "blocks", version: 1, revision, blocks, text: messageBlocksText(blocks) };
+    const result = readMessageContent(content);
+    if (result.kind !== "rich")
+        throw new Error(result.kind === "invalid" ? result.reason : "Invalid message content");
+    return content;
+}
+/** Ordered updates: incomplete charts remain invisible, replay never duplicates a block. */
+export function applyContentUpdate(current, update) {
+    if (update.revision <= current.revision)
+        return current;
+    if (update.revision !== current.revision + 1)
+        throw new Error("Content revision gap; fetch message snapshot");
+    if (!update.complete && update.block.type === "chart")
+        return { ...current, revision: update.revision };
+    if (!validateMessageBlock(update.block))
+        throw new Error("Invalid content update");
+    const blocks = current.blocks.slice(), index = blocks.findIndex(b => b.id === update.block.id);
+    if (index < 0)
+        blocks.push(update.block);
+    else
+        blocks[index] = update.block;
+    return createRichMessageContent(blocks, update.revision);
+}

package/lib/runtime/index.d.ts

@@ -2,8 +2,11 @@ export * from "./botAuth.js";
 export * from "./botKey.js";
 export * from "./chatClient.js";
 export * from "./protocol.js";
+export * from "./content.js";
 export * from "./readerClient.js";
 export * from "./thread.js";
+export * from "./updater.js";
+export * from "./updates.js";
 export * from "./activity.js";
 export * from "./call.js";
 export * from "./presence.js";

package/lib/runtime/index.js

@@ -2,8 +2,11 @@ export * from "./botAuth.js";
 export * from "./botKey.js";
 export * from "./chatClient.js";
 export * from "./protocol.js";
+export * from "./content.js";
 export * from "./readerClient.js";
 export * from "./thread.js";
+export * from "./updater.js";
+export * from "./updates.js";
 export * from "./activity.js";
 export * from "./call.js";
 export * from "./presence.js";

package/lib/runtime/updater.d.ts

@@ -0,0 +1,11 @@
+/** 按资源键合并刷新任务；聊天正文不经过此调度器。 */
+export declare class RefreshUpdater {
+    private readonly windowMs;
+    private readonly onError;
+    private tasks;
+    private closed;
+    constructor(windowMs?: number, onError?: (error: unknown, key: string) => void);
+    invalidate(key: string, refresh: () => Promise<void>): void;
+    close(): void;
+    private run;
+}

package/lib/runtime/updater.js

@@ -0,0 +1,55 @@
+/** 按资源键合并刷新任务；聊天正文不经过此调度器。 */
+export class RefreshUpdater {
+    windowMs;
+    onError;
+    tasks = new Map();
+    closed = false;
+    constructor(windowMs = 3_000, onError = () => { }) {
+        this.windowMs = windowMs;
+        this.onError = onError;
+    }
+    invalidate(key, refresh) {
+        if (this.closed)
+            return;
+        let task = this.tasks.get(key);
+        if (!task) {
+            task = { running: false, due: false, refresh };
+            this.tasks.set(key, task);
+        }
+        task.refresh = refresh;
+        if (task.timer || task.due)
+            return;
+        task.timer = setTimeout(() => {
+            task.timer = undefined;
+            task.due = true;
+            void this.run(key, task);
+        }, this.windowMs);
+    }
+    close() {
+        this.closed = true;
+        for (const task of this.tasks.values())
+            clearTimeout(task.timer);
+        this.tasks.clear();
+    }
+    async run(key, task) {
+        if (this.closed || task.running || !task.due)
+            return;
+        task.running = true;
+        task.due = false;
+        try {
+            await task.refresh();
+        }
+        catch (error) {
+            this.onError(error, key);
+            if (!this.closed)
+                this.invalidate(key, task.refresh);
+        }
+        finally {
+            task.running = false;
+            if (!this.closed && task.due)
+                void this.run(key, task);
+            else if (!task.timer)
+                this.tasks.delete(key);
+        }
+    }
+}

package/lib/runtime/updates.d.ts

@@ -0,0 +1,14 @@
+export type ChatUpdateType = "org.members.changed" | "org.profiles.changed";
+export type ChatUpdate = {
+    eventId: string;
+    appId: string;
+    orgId: string;
+    type: ChatUpdateType;
+    revision: string;
+};
+/** Accept only silent updater deliveries from the trusted Hub notification sender. */
+export declare function parseChatUpdate(message: {
+    opcode: number;
+    from: string;
+    body: unknown;
+}, appId: string): ChatUpdate | null;

package/lib/runtime/updates.js

@@ -0,0 +1,12 @@
+/** Accept only silent updater deliveries from the trusted Hub notification sender. */
+export function parseChatUpdate(message, appId) {
+    if (message.opcode !== 5 || message.from !== "@hub/notifications")
+        return null;
+    const body = message.body;
+    const data = body?.data;
+    if (body?.kind !== "delivery" || body.displayPolicy !== "silent" || !data || data.appId !== appId
+        || !["org.members.changed", "org.profiles.changed"].includes(String(data.type))
+        || typeof body.notificationId !== "string" || typeof data.orgId !== "string" || typeof data.revision !== "string")
+        return null;
+    return { eventId: body.notificationId, appId, orgId: data.orgId, type: data.type, revision: data.revision };
+}

package/package.json

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