@ardennguyen/zalo-agent-cli 1.0.7

package/src/mcp/message-buffer.js

@@ -0,0 +1,127 @@
+/**
+ * Ring buffer storing messages per thread with cursor-based incremental reads.
+ * Shared by both stdio and HTTP MCP transports.
+ */
+
+export class MessageBuffer {
+    /**
+     * @param {number} maxSize - Max messages per thread before eviction
+     * @param {number} maxAge - Max message age in ms before eviction (default 2h)
+     */
+    constructor(maxSize = 500, maxAge = 2 * 60 * 60 * 1000) {
+        /** @type {Map<string, { messages: Array, lastActivity: number }>} */
+        this._threads = new Map();
+        this._maxSize = maxSize;
+        this._maxAge = maxAge;
+        this._globalCursor = 0;
+    }
+
+    /**
+     * Add message to thread buffer. Auto-evicts stale messages.
+     * @param {string} threadId
+     * @param {object} message - Normalized message object
+     */
+    push(threadId, message) {
+        if (!this._threads.has(threadId)) {
+            this._threads.set(threadId, { messages: [], lastActivity: Date.now() });
+        }
+        const thread = this._threads.get(threadId);
+        // Assign global cursor for incremental reads
+        message._cursor = ++this._globalCursor;
+        thread.messages.push(message);
+        thread.lastActivity = Date.now();
+        this._evict(threadId);
+    }
+
+    /**
+     * Read messages from a thread, optionally since a cursor.
+     * @param {string} [threadId] - If omitted, reads from all threads
+     * @param {number} [since=0] - Cursor to read from (exclusive)
+     * @param {number} [maxCount=20] - Max messages to return
+     * @returns {{ messages: Array, cursor: number, hasMore: boolean }}
+     */
+    read(threadId, since = 0, maxCount = 20) {
+        const sources = threadId ? [this._threads.get(threadId)].filter(Boolean) : Array.from(this._threads.values());
+
+        // Collect all messages after cursor, sorted by cursor
+        const all = [];
+        for (const thread of sources) {
+            for (const msg of thread.messages) {
+                if (msg._cursor > since) all.push(msg);
+            }
+        }
+        all.sort((a, b) => a._cursor - b._cursor);
+
+        const hasMore = all.length > maxCount;
+        const messages = all.slice(0, maxCount);
+        const cursor = messages.length > 0 ? messages[messages.length - 1]._cursor : since;
+
+        return { messages, cursor, hasMore };
+    }
+
+    /**
+     * Advance read cursor — discard messages at or before given cursor.
+     * @param {number} cursor
+     * @returns {number} Count of discarded messages
+     */
+    markRead(cursor) {
+        let discarded = 0;
+        for (const [, thread] of this._threads) {
+            const before = thread.messages.length;
+            thread.messages = thread.messages.filter((m) => m._cursor > cursor);
+            discarded += before - thread.messages.length;
+        }
+        return discarded;
+    }
+
+    /**
+     * Get stats for all threads with buffered messages.
+     * @param {number} [readCursor=0] - Messages after this cursor are "unread"
+     * @returns {Array<{ threadId: string, unread: number, total: number, lastActivity: number }>}
+     */
+    getStats(readCursor = 0) {
+        const stats = [];
+        for (const [threadId, thread] of this._threads) {
+            if (thread.messages.length === 0) continue;
+            const unread = thread.messages.filter((m) => m._cursor > readCursor).length;
+            stats.push({
+                threadId,
+                unread,
+                total: thread.messages.length,
+                lastActivity: thread.lastActivity,
+            });
+        }
+        return stats;
+    }
+
+    /**
+     * Get thread type from first buffered message.
+     * @param {string} threadId
+     * @returns {string|null}
+     */
+    getThreadType(threadId) {
+        const thread = this._threads.get(threadId);
+        return thread?.messages?.[0]?.threadType ?? null;
+    }
+
+    /**
+     * Evict messages that exceed maxSize or maxAge for a given thread.
+     * @param {string} threadId
+     */
+    _evict(threadId) {
+        const thread = this._threads.get(threadId);
+        if (!thread) return;
+
+        const now = Date.now();
+        // Remove messages older than maxAge
+        thread.messages = thread.messages.filter((m) => now - m.timestamp < this._maxAge);
+        // Trim to maxSize (keep newest)
+        if (thread.messages.length > this._maxSize) {
+            thread.messages = thread.messages.slice(thread.messages.length - this._maxSize);
+        }
+        // Clean up empty threads
+        if (thread.messages.length === 0) {
+            this._threads.delete(threadId);
+        }
+    }
+}

package/src/mcp/message-buffer.test.js

@@ -0,0 +1,308 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { MessageBuffer } from "./message-buffer.js";
+
+/** Helper: create a message with a timestamp (default = now) */
+function msg(text, timestamp = Date.now()) {
+    return { text, timestamp };
+}
+
+describe("MessageBuffer constructor", () => {
+    it("uses default maxSize=500 and maxAge=2h", () => {
+        const buf = new MessageBuffer();
+        assert.equal(buf._maxSize, 500);
+        assert.equal(buf._maxAge, 2 * 60 * 60 * 1000);
+    });
+
+    it("accepts custom maxSize and maxAge", () => {
+        const buf = new MessageBuffer(10, 5000);
+        assert.equal(buf._maxSize, 10);
+        assert.equal(buf._maxAge, 5000);
+    });
+
+    it("starts with empty threads and cursor at 0", () => {
+        const buf = new MessageBuffer();
+        assert.equal(buf._threads.size, 0);
+        assert.equal(buf._globalCursor, 0);
+    });
+});
+
+describe("MessageBuffer push + read", () => {
+    it("push stores message and read returns it", () => {
+        const buf = new MessageBuffer();
+        buf.push("thread-1", msg("hello"));
+        const { messages, cursor } = buf.read("thread-1");
+        assert.equal(messages.length, 1);
+        assert.equal(messages[0].text, "hello");
+        assert.equal(cursor, 1);
+    });
+
+    it("multiple pushes to same thread are all returned", () => {
+        const buf = new MessageBuffer();
+        buf.push("t1", msg("a"));
+        buf.push("t1", msg("b"));
+        buf.push("t1", msg("c"));
+        const { messages } = buf.read("t1");
+        assert.equal(messages.length, 3);
+    });
+
+    it("assigns monotonically increasing cursors", () => {
+        const buf = new MessageBuffer();
+        buf.push("t1", msg("x"));
+        buf.push("t1", msg("y"));
+        const { messages } = buf.read("t1");
+        assert.ok(messages[0]._cursor < messages[1]._cursor);
+    });
+
+    it("read without threadId returns messages from all threads", () => {
+        const buf = new MessageBuffer();
+        buf.push("t1", msg("a"));
+        buf.push("t2", msg("b"));
+        const { messages } = buf.read();
+        assert.equal(messages.length, 2);
+    });
+
+    it("read from non-existent thread returns empty array", () => {
+        const buf = new MessageBuffer();
+        const { messages, cursor } = buf.read("no-such-thread");
+        assert.deepEqual(messages, []);
+        assert.equal(cursor, 0);
+    });
+});
+
+describe("MessageBuffer cursor-based incremental reads", () => {
+    it("since parameter excludes already-seen messages", () => {
+        const buf = new MessageBuffer();
+        buf.push("t1", msg("first"));
+        const { cursor: c1 } = buf.read("t1");
+
+        buf.push("t1", msg("second"));
+        const { messages } = buf.read("t1", c1);
+        assert.equal(messages.length, 1);
+        assert.equal(messages[0].text, "second");
+    });
+
+    it("since=cursor of last message returns empty array", () => {
+        const buf = new MessageBuffer();
+        buf.push("t1", msg("only"));
+        const { cursor } = buf.read("t1");
+        const { messages } = buf.read("t1", cursor);
+        assert.deepEqual(messages, []);
+    });
+
+    it("respects maxCount limit and sets hasMore=true", () => {
+        const buf = new MessageBuffer();
+        for (let i = 0; i < 5; i++) buf.push("t1", msg(`m${i}`));
+        const { messages, hasMore } = buf.read("t1", 0, 3);
+        assert.equal(messages.length, 3);
+        assert.equal(hasMore, true);
+    });
+
+    it("hasMore=false when all messages fit", () => {
+        const buf = new MessageBuffer();
+        buf.push("t1", msg("a"));
+        buf.push("t1", msg("b"));
+        const { hasMore } = buf.read("t1", 0, 20);
+        assert.equal(hasMore, false);
+    });
+});
+
+describe("MessageBuffer markRead", () => {
+    it("discards messages at or before cursor and returns count", () => {
+        const buf = new MessageBuffer();
+        buf.push("t1", msg("a"));
+        buf.push("t1", msg("b"));
+        const { cursor } = buf.read("t1");
+        const discarded = buf.markRead(cursor);
+        assert.equal(discarded, 2);
+    });
+
+    it("messages after cursor are kept", () => {
+        const buf = new MessageBuffer();
+        buf.push("t1", msg("a"));
+        const { cursor: c1 } = buf.read("t1");
+        buf.push("t1", msg("b"));
+
+        buf.markRead(c1);
+        const { messages } = buf.read("t1");
+        assert.equal(messages.length, 1);
+        assert.equal(messages[0].text, "b");
+    });
+
+    it("double markRead at same cursor returns 0 on second call", () => {
+        const buf = new MessageBuffer();
+        buf.push("t1", msg("a"));
+        const { cursor } = buf.read("t1");
+        buf.markRead(cursor);
+        const second = buf.markRead(cursor);
+        assert.equal(second, 0);
+    });
+
+    it("markRead across multiple threads discards from all", () => {
+        const buf = new MessageBuffer();
+        buf.push("t1", msg("a"));
+        buf.push("t2", msg("b"));
+        const { cursor } = buf.read(); // reads all
+        const discarded = buf.markRead(cursor);
+        assert.equal(discarded, 2);
+    });
+});
+
+describe("MessageBuffer eviction by maxSize", () => {
+    it("oldest messages are evicted when maxSize exceeded", () => {
+        const buf = new MessageBuffer(3, 99999999);
+        for (let i = 1; i <= 5; i++) buf.push("t1", msg(`m${i}`));
+        const { messages } = buf.read("t1");
+        assert.equal(messages.length, 3);
+        // Newest 3 kept
+        assert.equal(messages[0].text, "m3");
+        assert.equal(messages[2].text, "m5");
+    });
+});
+
+describe("MessageBuffer eviction by maxAge", () => {
+    it("stale messages are removed after maxAge expires", async () => {
+        const buf = new MessageBuffer(500, 50); // 50ms maxAge
+        buf.push("t1", { text: "old", timestamp: Date.now() });
+
+        await new Promise((r) => setTimeout(r, 80)); // wait for expiry
+
+        // Trigger eviction by pushing another message
+        buf.push("t1", { text: "new", timestamp: Date.now() });
+
+        const { messages } = buf.read("t1");
+        assert.equal(messages.length, 1);
+        assert.equal(messages[0].text, "new");
+    });
+
+    it("thread is removed when all messages evicted by age", async () => {
+        const buf = new MessageBuffer(500, 30); // 30ms maxAge
+        buf.push("t1", { text: "gone", timestamp: Date.now() });
+
+        await new Promise((r) => setTimeout(r, 60));
+
+        // Push to a different thread to avoid triggering eviction on t1
+        buf.push("t2", { text: "trigger", timestamp: Date.now() });
+
+        // t1 still has stale message but won't be cleaned unless _evict("t1") runs
+        // Push to t1 to trigger cleanup
+        buf.push("t1", { text: "trigger-clean", timestamp: Date.now() });
+
+        const { messages } = buf.read("t1");
+        // Only new message should remain
+        assert.equal(messages.length, 1);
+        assert.equal(messages[0].text, "trigger-clean");
+    });
+});
+
+describe("MessageBuffer multi-thread isolation", () => {
+    it("messages in different threads are independent", () => {
+        const buf = new MessageBuffer();
+        buf.push("t1", msg("from-t1"));
+        buf.push("t2", msg("from-t2"));
+
+        const r1 = buf.read("t1");
+        const r2 = buf.read("t2");
+
+        assert.equal(r1.messages.length, 1);
+        assert.equal(r1.messages[0].text, "from-t1");
+        assert.equal(r2.messages.length, 1);
+        assert.equal(r2.messages[0].text, "from-t2");
+    });
+
+    it("markRead on shared cursor only keeps messages after it in each thread", () => {
+        const buf = new MessageBuffer();
+        buf.push("t1", msg("t1-a"));
+        const { cursor: midCursor } = buf.read();
+        buf.push("t2", msg("t2-b")); // cursor after midCursor
+
+        buf.markRead(midCursor);
+
+        const r1 = buf.read("t1");
+        const r2 = buf.read("t2");
+        assert.equal(r1.messages.length, 0);
+        assert.equal(r2.messages.length, 1);
+    });
+});
+
+describe("MessageBuffer getStats", () => {
+    it("returns unread/total/lastActivity per thread", () => {
+        const buf = new MessageBuffer();
+        buf.push("t1", msg("a"));
+        buf.push("t1", msg("b"));
+        buf.push("t2", msg("c"));
+
+        const stats = buf.getStats(0);
+        assert.equal(stats.length, 2);
+
+        const t1 = stats.find((s) => s.threadId === "t1");
+        assert.ok(t1);
+        assert.equal(t1.total, 2);
+        assert.equal(t1.unread, 2);
+        assert.ok(typeof t1.lastActivity === "number");
+    });
+
+    it("respects readCursor when computing unread count", () => {
+        const buf = new MessageBuffer();
+        buf.push("t1", msg("a"));
+        const { cursor } = buf.read("t1");
+        buf.push("t1", msg("b")); // unread
+
+        const stats = buf.getStats(cursor);
+        const t1 = stats.find((s) => s.threadId === "t1");
+        assert.equal(t1.unread, 1);
+        assert.equal(t1.total, 2);
+    });
+
+    it("excludes threads with no messages", () => {
+        const buf = new MessageBuffer(500, 999999);
+        buf.push("t1", msg("a"));
+        const { cursor } = buf.read("t1");
+        buf.markRead(cursor); // discards all messages
+
+        const stats = buf.getStats(0);
+        assert.equal(stats.length, 0);
+    });
+});
+
+describe("MessageBuffer getThreadType", () => {
+    it("returns threadType from first buffered message", () => {
+        const buf = new MessageBuffer();
+        buf.push("t1", { text: "hi", threadType: "dm", timestamp: Date.now() });
+        buf.push("t1", { text: "hey", threadType: "dm", timestamp: Date.now() });
+        assert.equal(buf.getThreadType("t1"), "dm");
+    });
+
+    it("returns null for unknown thread", () => {
+        const buf = new MessageBuffer();
+        assert.equal(buf.getThreadType("nonexistent"), null);
+    });
+
+    it("returns null when thread exists but messages have no threadType", () => {
+        const buf = new MessageBuffer();
+        buf.push("t1", { text: "hi", timestamp: Date.now() });
+        assert.equal(buf.getThreadType("t1"), null);
+    });
+
+    it("returns group for group thread", () => {
+        const buf = new MessageBuffer();
+        buf.push("g1", { text: "hello", threadType: "group", timestamp: Date.now() });
+        assert.equal(buf.getThreadType("g1"), "group");
+    });
+});
+
+describe("MessageBuffer edge cases", () => {
+    it("empty read on fresh buffer returns empty array and cursor 0", () => {
+        const buf = new MessageBuffer();
+        const { messages, cursor } = buf.read("nowhere");
+        assert.deepEqual(messages, []);
+        assert.equal(cursor, 0);
+    });
+
+    it("global cursor increments across different threads", () => {
+        const buf = new MessageBuffer();
+        buf.push("t1", msg("x"));
+        buf.push("t2", msg("y"));
+        assert.equal(buf._globalCursor, 2);
+    });
+});

package/src/mcp/notifier.js

@@ -0,0 +1,141 @@
+/**
+ * Sends notification to a configured Zalo group when DMs arrive
+ * and no MCP agent is connected. Batches messages within a cooldown window.
+ */
+
+import { parseDuration } from "./mcp-config.js";
+
+/** Emoji prefix per message type for notification previews */
+const TYPE_EMOJI = {
+    text: "💬",
+    image: "📷",
+    file: "📎",
+    link: "🔗",
+    video: "🎬",
+    audio: "🎵",
+    voice: "🎤",
+    gif: "🎞️",
+};
+
+/** Vietnamese label per message type for notification breakdown */
+const TYPE_LABEL = {
+    text: "text",
+    image: "ảnh",
+    file: "file",
+    link: "link",
+    video: "video",
+    audio: "audio",
+    voice: "voice",
+    gif: "gif",
+};
+
+export class ZaloNotifier {
+    /**
+     * @param {object} api - zca-js API instance
+     * @param {object} config - Full MCP config (uses config.notify section)
+     * @param {boolean} config.notify.enabled
+     * @param {string|null} config.notify.thread - Group ID to send notifications to
+     * @param {string[]} config.notify.on - Event types to notify on (e.g. ["dm"])
+     * @param {string} config.notify.cooldown - Debounce window (e.g. "5m")
+     */
+    constructor(api, config) {
+        this._api = api;
+        this._enabled = config.notify?.enabled || false;
+        this._notifyThread = config.notify?.thread || null;
+        this._onTypes = new Set(config.notify?.on || ["dm"]);
+        this._cooldownMs = parseDuration(config.notify?.cooldown || "5m");
+        this._pending = []; // Messages queued during cooldown window
+        this._timer = null;
+        this._agentConnected = false;
+    }
+
+    /** Mark agent as connected/disconnected — suppresses notifications when connected */
+    setAgentConnected(connected) {
+        this._agentConnected = connected;
+    }
+
+    /**
+     * Called when a new message arrives. Queues notification if conditions are met.
+     * @param {object} message - Normalized message object
+     */
+    onMessage(message) {
+        if (!this._shouldNotify(message)) return;
+        this._pending.push(message);
+        // Start cooldown timer only once per batch window
+        if (!this._timer) {
+            this._timer = setTimeout(() => this._flush(), this._cooldownMs);
+        }
+    }
+
+    /**
+     * Determine whether this message warrants a notification.
+     * @param {object} message
+     * @returns {boolean}
+     */
+    _shouldNotify(message) {
+        if (!this._enabled || !this._notifyThread) return false;
+        if (this._agentConnected) return false;
+        return this._onTypes.has(message.threadType);
+    }
+
+    /** Flush pending notifications as a single batched message to the notify thread */
+    async _flush() {
+        this._timer = null;
+        if (this._pending.length === 0) return;
+
+        const count = this._pending.length;
+        const typeBreakdown = this._buildTypeBreakdown(this._pending);
+        const preview = this._pending
+            .slice(0, 3) // Show at most 3 message previews
+            .map((m) => {
+                const type = m.type || "text";
+                const prefix = TYPE_EMOJI[type] || "💬";
+                const sender = m.senderName || m.senderId;
+                const body = type === "text" ? (m.text || "").slice(0, 50) : `[${TYPE_LABEL[type] || type}]`;
+                return `- ${sender}: ${prefix} ${body}`;
+            })
+            .join("\n");
+
+        const suffix = count > 3 ? `\n...và ${count - 3} tin nhắn khác` : "";
+        const text = `🔔 ${count} tin nhắn mới [${typeBreakdown}] trong ${this._formatWindow()}:\n${preview}${suffix}`;
+
+        try {
+            // threadType 1 = Group conversation
+            await this._api.sendMessage(text, this._notifyThread, 1);
+        } catch (err) {
+            console.error("Notifier send failed:", err.message);
+        }
+
+        this._pending = [];
+    }
+
+    /**
+     * Build a human-readable type breakdown string, e.g. "2 text, 1 ảnh".
+     * @param {object[]} messages - Array of normalized messages
+     * @returns {string}
+     */
+    _buildTypeBreakdown(messages) {
+        const counts = {};
+        for (const m of messages) {
+            const t = m.type || "text";
+            counts[t] = (counts[t] || 0) + 1;
+        }
+        return Object.entries(counts)
+            .map(([type, n]) => `${n} ${TYPE_LABEL[type] || type}`)
+            .join(", ");
+    }
+
+    /** Format cooldown duration as human-readable string (e.g. "5 phút", "1h") */
+    _formatWindow() {
+        const mins = Math.round(this._cooldownMs / 60000);
+        return mins >= 60 ? `${Math.round(mins / 60)}h` : `${mins} phút`;
+    }
+
+    /** Clean up pending timer on shutdown and attempt final flush */
+    destroy() {
+        if (this._timer) {
+            clearTimeout(this._timer);
+            this._flush();
+        }
+    }
+}