zalo-agent-cli 1.2.0 → 1.4.0

package/src/mcp/notifier.test.js

@@ -0,0 +1,239 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { ZaloNotifier } from "./notifier.js";
+
+/** Create a spy api.sendMessage that records calls */
+function makeSpy() {
+    const calls = [];
+    const api = {
+        sendMessage: async (text, thread, type) => {
+            calls.push({ text, thread, type });
+        },
+    };
+    return { api, calls };
+}
+
+/** Minimal enabled config for ZaloNotifier */
+function enabledConfig(overrides = {}) {
+    return {
+        notify: {
+            enabled: true,
+            thread: "notify_group_123",
+            on: ["dm"],
+            cooldown: "10ms", // very short for tests
+            ...overrides,
+        },
+    };
+}
+
+/** Disabled config */
+function disabledConfig() {
+    return {
+        notify: {
+            enabled: false,
+            thread: "notify_group_123",
+            on: ["dm"],
+            cooldown: "10ms",
+        },
+    };
+}
+
+/** A normalised DM message */
+function dmMsg(text = "hello", overrides = {}) {
+    return { threadType: "dm", senderId: "user_1", senderName: "Alice", text, ...overrides };
+}
+
+/** Wait for ms milliseconds */
+function wait(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+
+describe("ZaloNotifier constructor", () => {
+    it("is disabled by default when config.notify.enabled=false", () => {
+        const { api } = makeSpy();
+        const n = new ZaloNotifier(api, disabledConfig());
+        assert.equal(n._enabled, false);
+    });
+
+    it("is enabled when config.notify.enabled=true", () => {
+        const { api } = makeSpy();
+        const n = new ZaloNotifier(api, enabledConfig());
+        assert.equal(n._enabled, true);
+    });
+
+    it("stores notify thread and onTypes from config", () => {
+        const { api } = makeSpy();
+        const n = new ZaloNotifier(api, enabledConfig({ thread: "grp_99", on: ["dm", "group"] }));
+        assert.equal(n._notifyThread, "grp_99");
+        assert.ok(n._onTypes.has("dm"));
+        assert.ok(n._onTypes.has("group"));
+    });
+
+    it("agentConnected starts as false", () => {
+        const { api } = makeSpy();
+        const n = new ZaloNotifier(api, enabledConfig());
+        assert.equal(n._agentConnected, false);
+    });
+});
+
+describe("ZaloNotifier onMessage - disabled", () => {
+    it("does not queue messages when disabled", async () => {
+        const { api, calls } = makeSpy();
+        const n = new ZaloNotifier(api, disabledConfig());
+        n.onMessage(dmMsg());
+        await wait(30);
+        assert.equal(calls.length, 0);
+        assert.equal(n._pending.length, 0);
+        n.destroy();
+    });
+});
+
+describe("ZaloNotifier onMessage - agent connected", () => {
+    it("does not notify when agent is connected", async () => {
+        const { api, calls } = makeSpy();
+        const n = new ZaloNotifier(api, enabledConfig());
+        n.setAgentConnected(true);
+        n.onMessage(dmMsg());
+        await wait(30);
+        assert.equal(calls.length, 0);
+        n.destroy();
+    });
+
+    it("notifies again after agent disconnects", async () => {
+        const { api, calls } = makeSpy();
+        const n = new ZaloNotifier(api, enabledConfig());
+        n.setAgentConnected(true);
+        n.onMessage(dmMsg("ignored"));
+        n.setAgentConnected(false);
+        n.onMessage(dmMsg("should notify"));
+        await wait(30);
+        assert.equal(calls.length, 1);
+        n.destroy();
+    });
+});
+
+describe("ZaloNotifier onMessage - type filtering", () => {
+    it("queues messages matching onTypes (dm)", async () => {
+        const { api, calls } = makeSpy();
+        const n = new ZaloNotifier(api, enabledConfig({ on: ["dm"] }));
+        n.onMessage(dmMsg("queued"));
+        await wait(30);
+        assert.equal(calls.length, 1);
+    });
+
+    it("ignores messages not matching onTypes", async () => {
+        const { api, calls } = makeSpy();
+        const n = new ZaloNotifier(api, enabledConfig({ on: ["dm"] }));
+        n.onMessage({ threadType: "group", senderId: "u1", senderName: "Bob", text: "hi" });
+        await wait(30);
+        assert.equal(calls.length, 0);
+    });
+
+    it("notifies for group type when configured", async () => {
+        const { api, calls } = makeSpy();
+        const n = new ZaloNotifier(api, enabledConfig({ on: ["group"] }));
+        n.onMessage({ threadType: "group", senderId: "u1", senderName: "Bob", text: "hi" });
+        await wait(30);
+        assert.equal(calls.length, 1);
+    });
+});
+
+describe("ZaloNotifier _flush notification format", () => {
+    it("sends to the configured notify thread", async () => {
+        const { api, calls } = makeSpy();
+        const n = new ZaloNotifier(api, enabledConfig({ thread: "grp_notify" }));
+        n.onMessage(dmMsg("test message"));
+        await wait(30);
+        assert.equal(calls[0].thread, "grp_notify");
+        assert.equal(calls[0].type, 1); // Group conversation type
+    });
+
+    it("notification text includes sender name and message preview", async () => {
+        const { api, calls } = makeSpy();
+        const n = new ZaloNotifier(api, enabledConfig());
+        n.onMessage(dmMsg("hello world", { senderName: "Alice" }));
+        await wait(30);
+        assert.ok(calls[0].text.includes("Alice"));
+        assert.ok(calls[0].text.includes("hello world"));
+    });
+
+    it("shows up to 3 message previews in a single flush", async () => {
+        const { api, calls } = makeSpy();
+        const n = new ZaloNotifier(api, enabledConfig());
+        n.onMessage(dmMsg("msg1", { senderName: "A" }));
+        n.onMessage(dmMsg("msg2", { senderName: "B" }));
+        n.onMessage(dmMsg("msg3", { senderName: "C" }));
+        await wait(30);
+        // Only one batched send
+        assert.equal(calls.length, 1);
+        assert.ok(calls[0].text.includes("msg1"));
+        assert.ok(calls[0].text.includes("msg2"));
+        assert.ok(calls[0].text.includes("msg3"));
+    });
+
+    it("includes overflow count when more than 3 messages", async () => {
+        const { api, calls } = makeSpy();
+        const n = new ZaloNotifier(api, enabledConfig());
+        for (let i = 1; i <= 5; i++) {
+            n.onMessage(dmMsg(`msg${i}`, { senderName: `User${i}` }));
+        }
+        await wait(30);
+        assert.equal(calls.length, 1);
+        // Should mention the extra 2 messages
+        assert.ok(calls[0].text.includes("2"));
+    });
+
+    it("sends total message count in notification text", async () => {
+        const { api, calls } = makeSpy();
+        const n = new ZaloNotifier(api, enabledConfig());
+        n.onMessage(dmMsg("one"));
+        n.onMessage(dmMsg("two"));
+        await wait(30);
+        assert.ok(calls[0].text.includes("2"));
+    });
+});
+
+describe("ZaloNotifier cooldown batching", () => {
+    it("batches multiple messages within cooldown into a single send", async () => {
+        const { api, calls } = makeSpy();
+        const n = new ZaloNotifier(api, enabledConfig({ cooldown: "20ms" }));
+        n.onMessage(dmMsg("first"));
+        n.onMessage(dmMsg("second"));
+        n.onMessage(dmMsg("third"));
+        await wait(50); // wait for cooldown to fire
+        assert.equal(calls.length, 1);
+    });
+
+    it("clears pending after flush so next batch is independent", async () => {
+        const { api, calls } = makeSpy();
+        const n = new ZaloNotifier(api, enabledConfig({ cooldown: "20ms" }));
+        n.onMessage(dmMsg("batch1"));
+        await wait(40); // first flush
+
+        n.onMessage(dmMsg("batch2"));
+        await wait(40); // second flush
+
+        assert.equal(calls.length, 2);
+    });
+});
+
+describe("ZaloNotifier destroy", () => {
+    it("flushes pending messages on destroy", async () => {
+        const { api, calls } = makeSpy();
+        // Long cooldown so timer wouldn't fire naturally
+        const n = new ZaloNotifier(api, enabledConfig({ cooldown: "60000ms" }));
+        n.onMessage(dmMsg("urgent"));
+        n.destroy(); // should flush immediately
+        // _flush is async, give it a tick
+        await wait(10);
+        assert.equal(calls.length, 1);
+    });
+
+    it("destroy with no pending messages does not send", async () => {
+        const { api, calls } = makeSpy();
+        const n = new ZaloNotifier(api, enabledConfig());
+        n.destroy(); // nothing pending, no timer
+        await wait(10);
+        assert.equal(calls.length, 0);
+    });
+});

package/src/mcp/thread-filter.js

@@ -0,0 +1,79 @@
+/**
+ * Filter which threads to watch and which messages to keep.
+ * Supports glob-like patterns for thread matching and noise reduction.
+ */
+
+/** System message types to drop (join, leave, pin, etc.) */
+const SYSTEM_MSG_TYPES = new Set(["system", "join", "leave", "pin", "unpin", "rename"]);
+
+export class ThreadFilter {
+    /**
+     * @param {object} config - MCP config object
+     * @param {string[]} config.watchThreads - Glob patterns like ["dm:*", "group:support"]
+     * @param {string[]} [config.triggerKeywords] - Keywords that trigger attention
+     */
+    constructor(config) {
+        this._watchPatterns = config.watchThreads || ["dm:*", "group:*"];
+        this._triggerKeywords = (config.triggerKeywords || []).map((k) => k.toLowerCase());
+    }
+
+    /**
+     * Check if a thread should be watched based on patterns.
+     * Pattern format: "dm:*", "group:*", "group:exact_id", "dm:exact_id"
+     * @param {string} threadId
+     * @param {"group"|"dm"} threadType
+     * @returns {boolean}
+     */
+    shouldWatch(threadId, threadType) {
+        const key = `${threadType}:${threadId}`;
+        for (const pattern of this._watchPatterns) {
+            if (this._matchPattern(pattern, key, threadType)) return true;
+        }
+        return false;
+    }
+
+    /**
+     * Check if a message passes noise filter (drop stickers, short emoji, system msgs).
+     * @param {object} message - Normalized message
+     * @returns {boolean}
+     */
+    shouldKeep(message) {
+        // Drop system messages
+        if (message.type && SYSTEM_MSG_TYPES.has(message.type)) return false;
+        // Drop sticker-only messages
+        if (message.type === "sticker") return false;
+        // Drop very short emoji-only messages (< 3 chars, all emoji/whitespace)
+        if (message.text && message.text.length < 3 && /^[\s\p{Emoji}]*$/u.test(message.text)) {
+            return false;
+        }
+        // Keep everything else (including images, files, links)
+        return true;
+    }
+
+    /**
+     * Check if a message is a trigger (contains keyword or @mention).
+     * @param {object} message - Normalized message
+     * @returns {boolean}
+     */
+    isTrigger(message) {
+        if (!message.text || this._triggerKeywords.length === 0) return false;
+        const lower = message.text.toLowerCase();
+        return this._triggerKeywords.some((kw) => lower.includes(kw));
+    }
+
+    /**
+     * Match a pattern against a thread key.
+     * @param {string} pattern - e.g. "dm:*", "group:support_123"
+     * @param {string} key - e.g. "dm:user_456", "group:support_123"
+     * @param {string} threadType - "dm" or "group"
+     * @returns {boolean}
+     */
+    _matchPattern(pattern, key, threadType) {
+        // Wildcard: "dm:*" matches all DMs, "group:*" matches all groups
+        if (pattern === `${threadType}:*`) return true;
+        // Catch-all patterns
+        if (pattern === "*" || pattern === "*:*") return true;
+        // Exact match
+        return pattern === key;
+    }
+}

package/src/mcp/thread-filter.test.js

@@ -0,0 +1,206 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { ThreadFilter } from "./thread-filter.js";
+
+/** Helper: create a ThreadFilter with given patterns and keywords */
+function makeFilter(watchThreads = ["dm:*", "group:*"], triggerKeywords = []) {
+    return new ThreadFilter({ watchThreads, triggerKeywords });
+}
+
+describe("ThreadFilter shouldWatch - glob patterns", () => {
+    it("dm:* matches any DM thread", () => {
+        const f = makeFilter(["dm:*"]);
+        assert.equal(f.shouldWatch("user_123", "dm"), true);
+        assert.equal(f.shouldWatch("abc", "dm"), true);
+    });
+
+    it("group:* matches any group thread", () => {
+        const f = makeFilter(["group:*"]);
+        assert.equal(f.shouldWatch("support_456", "group"), true);
+        assert.equal(f.shouldWatch("anything", "group"), true);
+    });
+
+    it("dm:* does not match group threads", () => {
+        const f = makeFilter(["dm:*"]);
+        assert.equal(f.shouldWatch("some_group", "group"), false);
+    });
+
+    it("group:* does not match dm threads", () => {
+        const f = makeFilter(["group:*"]);
+        assert.equal(f.shouldWatch("some_user", "dm"), false);
+    });
+});
+
+describe("ThreadFilter shouldWatch - exact match", () => {
+    it("exact group pattern matches only that thread id", () => {
+        const f = makeFilter(["group:support_123"]);
+        assert.equal(f.shouldWatch("support_123", "group"), true);
+        assert.equal(f.shouldWatch("support_456", "group"), false);
+    });
+
+    it("exact dm pattern matches only that thread id", () => {
+        const f = makeFilter(["dm:user_42"]);
+        assert.equal(f.shouldWatch("user_42", "dm"), true);
+        assert.equal(f.shouldWatch("user_99", "dm"), false);
+    });
+
+    it("exact match requires type prefix to align", () => {
+        const f = makeFilter(["group:support_123"]);
+        // same id but different type should not match
+        assert.equal(f.shouldWatch("support_123", "dm"), false);
+    });
+});
+
+describe("ThreadFilter shouldWatch - catch-all patterns", () => {
+    it("* matches any thread regardless of type", () => {
+        const f = makeFilter(["*"]);
+        assert.equal(f.shouldWatch("user_1", "dm"), true);
+        assert.equal(f.shouldWatch("group_1", "group"), true);
+    });
+
+    it("*:* matches any thread regardless of type", () => {
+        const f = makeFilter(["*:*"]);
+        assert.equal(f.shouldWatch("user_1", "dm"), true);
+        assert.equal(f.shouldWatch("group_1", "group"), true);
+    });
+});
+
+describe("ThreadFilter shouldWatch - unmatched patterns", () => {
+    it("returns false when no pattern matches", () => {
+        const f = makeFilter(["group:specific_only"]);
+        assert.equal(f.shouldWatch("other_group", "group"), false);
+        assert.equal(f.shouldWatch("any_user", "dm"), false);
+    });
+
+    it("empty watchThreads array never matches", () => {
+        const f = makeFilter([]);
+        assert.equal(f.shouldWatch("x", "dm"), false);
+        assert.equal(f.shouldWatch("y", "group"), false);
+    });
+});
+
+describe("ThreadFilter shouldKeep - system messages dropped", () => {
+    const SYSTEM_TYPES = ["system", "join", "leave", "pin", "unpin", "rename"];
+
+    for (const type of SYSTEM_TYPES) {
+        it(`drops message with type="${type}"`, () => {
+            const f = makeFilter();
+            assert.equal(f.shouldKeep({ type, text: "some text" }), false);
+        });
+    }
+});
+
+describe("ThreadFilter shouldKeep - sticker messages dropped", () => {
+    it("drops sticker-only messages", () => {
+        const f = makeFilter();
+        assert.equal(f.shouldKeep({ type: "sticker" }), false);
+    });
+});
+
+describe("ThreadFilter shouldKeep - short emoji-only messages dropped", () => {
+    it("drops single emoji (< 3 chars)", () => {
+        const f = makeFilter();
+        assert.equal(f.shouldKeep({ text: "👍" }), false);
+    });
+
+    it("drops two-char emoji message", () => {
+        const f = makeFilter();
+        assert.equal(f.shouldKeep({ text: "😂" }), false);
+    });
+
+    it("keeps messages with 3+ chars even if emoji", () => {
+        const f = makeFilter();
+        // Three emojis — length in JS may vary; use text that is clearly >= 3 code units
+        assert.equal(f.shouldKeep({ text: "hey" }), true);
+    });
+
+    it("drops whitespace-only short message", () => {
+        const f = makeFilter();
+        // 1-2 spaces are < 3 chars and match /^[\s\p{Emoji}]*$/u
+        assert.equal(f.shouldKeep({ text: " " }), false);
+    });
+});
+
+describe("ThreadFilter shouldKeep - kept messages", () => {
+    it("keeps normal text messages", () => {
+        const f = makeFilter();
+        assert.equal(f.shouldKeep({ type: "text", text: "Hello there!" }), true);
+    });
+
+    it("keeps image messages (no text)", () => {
+        const f = makeFilter();
+        assert.equal(f.shouldKeep({ type: "image" }), true);
+    });
+
+    it("keeps file messages", () => {
+        const f = makeFilter();
+        assert.equal(f.shouldKeep({ type: "file" }), true);
+    });
+
+    it("keeps link messages", () => {
+        const f = makeFilter();
+        assert.equal(f.shouldKeep({ type: "link", text: "https://example.com" }), true);
+    });
+
+    it("keeps message with no type field", () => {
+        const f = makeFilter();
+        assert.equal(f.shouldKeep({ text: "plain message" }), true);
+    });
+});
+
+describe("ThreadFilter isTrigger", () => {
+    it("detects keyword in message text (case-insensitive)", () => {
+        const f = makeFilter(["dm:*"], ["@bot"]);
+        assert.equal(f.isTrigger({ text: "Hey @BOT help me" }), true);
+    });
+
+    it("detects keyword at start of text", () => {
+        const f = makeFilter(["dm:*"], ["help"]);
+        assert.equal(f.isTrigger({ text: "help me please" }), true);
+    });
+
+    it("returns false when keyword not present", () => {
+        const f = makeFilter(["dm:*"], ["@bot"]);
+        assert.equal(f.isTrigger({ text: "just a normal message" }), false);
+    });
+
+    it("returns false when no keywords configured", () => {
+        const f = makeFilter(["dm:*"], []);
+        assert.equal(f.isTrigger({ text: "@bot trigger me" }), false);
+    });
+
+    it("returns false when text is empty string", () => {
+        const f = makeFilter(["dm:*"], ["@bot"]);
+        assert.equal(f.isTrigger({ text: "" }), false);
+    });
+
+    it("returns false when text property is missing", () => {
+        const f = makeFilter(["dm:*"], ["@bot"]);
+        assert.equal(f.isTrigger({}), false);
+    });
+
+    it("matches any of multiple keywords", () => {
+        const f = makeFilter(["dm:*"], ["urgent", "help", "broken"]);
+        assert.equal(f.isTrigger({ text: "system is broken" }), true);
+        assert.equal(f.isTrigger({ text: "need urgent attention" }), true);
+        assert.equal(f.isTrigger({ text: "everything is fine" }), false);
+    });
+});
+
+describe("ThreadFilter edge cases", () => {
+    it("shouldKeep handles empty message object", () => {
+        const f = makeFilter();
+        // No type, no text — should keep (default allow)
+        assert.equal(f.shouldKeep({}), true);
+    });
+
+    it("shouldKeep handles null text field gracefully", () => {
+        const f = makeFilter();
+        assert.equal(f.shouldKeep({ type: "text", text: null }), true);
+    });
+
+    it("isTrigger handles null text field", () => {
+        const f = makeFilter(["dm:*"], ["keyword"]);
+        assert.equal(f.isTrigger({ text: null }), false);
+    });
+});

package/src/mcp/thread-name-cache.js

@@ -0,0 +1,162 @@
+/**
+ * In-memory cache mapping threadId → {name, type, memberCount}.
+ * Built on startup by fetching all groups + friends from Zalo API.
+ * Provides fuzzy Vietnamese-aware search for thread discovery.
+ */
+
+/**
+ * Normalize Vietnamese text for fuzzy matching.
+ * Strips diacritics and lowercases for accent-insensitive comparison.
+ * @param {string} text
+ * @returns {string}
+ */
+function normalizeVietnamese(text) {
+    return text
+        .normalize("NFD")
+        .replace(/[\u0300-\u036f]/g, "")
+        .replace(/đ/g, "d")
+        .replace(/Đ/g, "D")
+        .toLowerCase();
+}
+
+export class ThreadNameCache {
+    constructor() {
+        /** @type {Map<string, { name: string, type: "group"|"dm", memberCount?: number }>} */
+        this._cache = new Map();
+        this._ready = false;
+    }
+
+    /**
+     * Initialize cache by fetching all groups and friends from Zalo API.
+     * Batches group info requests (50 per batch) to avoid rate limits.
+     * @param {object} api - zca-js API instance
+     */
+    async init(api) {
+        const start = Date.now();
+        let groupCount = 0;
+        let friendCount = 0;
+
+        // Load groups: getAllGroups() → IDs → batched getGroupInfo()
+        try {
+            const groupsResult = await api.getAllGroups();
+            const groupIds = Object.keys(groupsResult?.gridVerMap || {});
+            const batchSize = 50;
+
+            for (let i = 0; i < groupIds.length; i += batchSize) {
+                const batch = groupIds.slice(i, i + batchSize);
+                try {
+                    const info = await api.getGroupInfo(batch);
+                    const map = info?.gridInfoMap || {};
+                    for (const [gid, g] of Object.entries(map)) {
+                        this._cache.set(gid, {
+                            name: g.name || "?",
+                            type: "group",
+                            memberCount: g.totalMember || 0,
+                        });
+                        groupCount++;
+                    }
+                } catch (e) {
+                    console.error(`[thread-name-cache] Batch getGroupInfo failed (offset ${i}):`, e.message);
+                }
+            }
+        } catch (e) {
+            console.error("[thread-name-cache] getAllGroups failed:", e.message);
+        }
+
+        // Load friends (DM threads)
+        try {
+            const friends = await api.getAllFriends();
+            const list = Array.isArray(friends) ? friends : [];
+            for (const f of list) {
+                if (f.userId) {
+                    this._cache.set(f.userId, {
+                        name: f.displayName || f.zaloName || "?",
+                        type: "dm",
+                    });
+                    friendCount++;
+                }
+            }
+        } catch (e) {
+            console.error("[thread-name-cache] getAllFriends failed:", e.message);
+        }
+
+        this._ready = true;
+        const elapsed = Date.now() - start;
+        console.error(`[thread-name-cache] Ready: ${groupCount} groups, ${friendCount} friends (${elapsed}ms)`);
+    }
+
+    /**
+     * Get thread info by ID. Returns null if not cached.
+     * @param {string} threadId
+     * @returns {{ name: string, type: "group"|"dm", memberCount?: number } | null}
+     */
+    get(threadId) {
+        return this._cache.get(threadId) || null;
+    }
+
+    /**
+     * Get thread name by ID. Returns null if not cached.
+     * @param {string} threadId
+     * @returns {string | null}
+     */
+    getName(threadId) {
+        return this._cache.get(threadId)?.name || null;
+    }
+
+    /**
+     * Search threads by name with Vietnamese-aware fuzzy matching.
+     * @param {string} query - Search keyword
+     * @param {"group"|"dm"|"all"} [type="all"] - Filter by thread type
+     * @param {number} [limit=10] - Max results
+     * @returns {Array<{ threadId: string, name: string, type: "group"|"dm", memberCount?: number }>}
+     */
+    search(query, type = "all", limit = 10) {
+        const normalizedQuery = normalizeVietnamese(query);
+        const results = [];
+
+        for (const [threadId, info] of this._cache) {
+            if (type !== "all" && info.type !== type) continue;
+
+            const normalizedName = normalizeVietnamese(info.name);
+            if (normalizedName.includes(normalizedQuery)) {
+                results.push({ threadId, ...info });
+            }
+        }
+
+        // Sort: exact prefix match first, then alphabetical
+        results.sort((a, b) => {
+            const aNorm = normalizeVietnamese(a.name);
+            const bNorm = normalizeVietnamese(b.name);
+            const aPrefix = aNorm.startsWith(normalizedQuery) ? 0 : 1;
+            const bPrefix = bNorm.startsWith(normalizedQuery) ? 0 : 1;
+            if (aPrefix !== bPrefix) return aPrefix - bPrefix;
+            return aNorm.localeCompare(bNorm);
+        });
+
+        return results.slice(0, limit);
+    }
+
+    /**
+     * Update a single thread entry (e.g. on group rename event).
+     * @param {string} threadId
+     * @param {object} info - Partial update: { name?, type?, memberCount? }
+     */
+    set(threadId, info) {
+        const existing = this._cache.get(threadId);
+        if (existing) {
+            this._cache.set(threadId, { ...existing, ...info });
+        } else {
+            this._cache.set(threadId, { name: "?", type: "group", ...info });
+        }
+    }
+
+    /** @returns {boolean} Whether cache has been initialized */
+    get ready() {
+        return this._ready;
+    }
+
+    /** @returns {number} Total cached entries */
+    get size() {
+        return this._cache.size;
+    }
+}