zalo-agent-cli 1.3.0 → 1.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zalo-agent-cli",
-  "version": "1.3.0",
+  "version": "1.4.2",
   "description": "CLI tool for Zalo automation — multi-account, proxy, bank transfers, QR payments, Official Account API v3.0",
   "type": "module",
   "bin": {

package/src/commands/group.js

@@ -12,11 +12,75 @@ export function registerGroupCommands(program) {
 
     group
         .command("list")
-        .description("List all groups")
-        .action(async () => {
-            try {
-                const result = await getApi().getAllGroups();
-                output(result, program.opts().json);
+        .description("List all groups with names and member counts")
+        .option("-q, --query <text>", "Filter groups by name (case-insensitive, accent-insensitive)")
+        .action(async (opts) => {
+            try {
+                const api = getApi();
+                const groupsResult = await api.getAllGroups();
+                const groupIds = Object.keys(groupsResult?.gridVerMap || {});
+
+                if (groupIds.length === 0) {
+                    info("No groups found.");
+                    return;
+                }
+
+                // Batch fetch group info (50 per batch) to get names
+                const groups = [];
+                const batchSize = 50;
+                for (let i = 0; i < groupIds.length; i += batchSize) {
+                    const batch = groupIds.slice(i, i + batchSize);
+                    try {
+                        const groupInfo = await api.getGroupInfo(batch);
+                        const map = groupInfo?.gridInfoMap || {};
+                        for (const [gid, g] of Object.entries(map)) {
+                            groups.push({
+                                threadId: gid,
+                                name: g.name || "?",
+                                memberCount: g.totalMember || 0,
+                            });
+                        }
+                    } catch {
+                        // Skip failed batch, add IDs without names
+                        for (const id of batch) {
+                            groups.push({ threadId: id, name: "?", memberCount: 0 });
+                        }
+                    }
+                }
+
+                // Apply name filter if --query provided
+                let filtered = groups;
+                if (opts.query) {
+                    const q = opts.query
+                        .normalize("NFD")
+                        .replace(/[\u0300-\u036f]/g, "")
+                        .replace(/đ/g, "d")
+                        .replace(/Đ/g, "D")
+                        .toLowerCase();
+                    filtered = groups.filter((g) => {
+                        const normalized = g.name
+                            .normalize("NFD")
+                            .replace(/[\u0300-\u036f]/g, "")
+                            .replace(/đ/g, "d")
+                            .replace(/Đ/g, "D")
+                            .toLowerCase();
+                        return normalized.includes(q);
+                    });
+                }
+
+                output(filtered, program.opts().json, () => {
+                    info(
+                        `${filtered.length} group(s)${opts.query ? ` matching "${opts.query}"` : ""} (${groupIds.length} total)`,
+                    );
+                    console.log();
+                    console.log("  THREAD_ID               MEMBERS  NAME");
+                    console.log("  " + "-".repeat(65));
+                    for (const g of filtered) {
+                        const id = g.threadId.padEnd(22);
+                        const members = String(g.memberCount).padStart(5);
+                        console.log(`  ${id}  ${members}    ${g.name}`);
+                    }
+                });
             } catch (e) {
                 error(e.message);
             }

package/src/commands/mcp.js

@@ -13,6 +13,7 @@ import { createMCPServer } from "../mcp/mcp-server.js";
 import { registerTools } from "../mcp/mcp-tools.js";
 import { createHTTPServer } from "../mcp/mcp-http-transport.js";
 import { ZaloNotifier } from "../mcp/notifier.js";
+import { ThreadNameCache } from "../mcp/thread-name-cache.js";
 
 /** Zalo close code for duplicate web session — fatal, do not retry */
 const CLOSE_DUPLICATE = 3000;
@@ -31,9 +32,7 @@ function normalizeMessage(msg) {
         threadType: msg.type === 0 ? "dm" : "group",
         senderId: msg.data.uidFrom || null,
         senderName: msg.data.dName || null,
-        text: isText
-            ? rawContent
-            : rawContent?.title || rawContent?.href || `[${msg.data.msgType || "attachment"}]`,
+        text: isText ? rawContent : rawContent?.title || rawContent?.href || `[${msg.data.msgType || "attachment"}]`,
         timestamp: Date.now(),
         type: isText ? "text" : msg.data.msgType || "attachment",
         attachment:
@@ -75,15 +74,23 @@ export function registerMCPCommands(program) {
             const buffer = new MessageBuffer(maxSize, maxAge);
             const filter = new ThreadFilter(config);
 
+            // Build thread name cache (groups + friends → in-memory index)
+            const nameCache = new ThreadNameCache();
+            try {
+                await nameCache.init(getApi());
+            } catch (e) {
+                console.error("[mcp] Thread name cache init failed (non-fatal):", e.message);
+            }
+
             // Start MCP server — stdio (default) or HTTP
             try {
                 if (opts.http) {
                     const port = Number(opts.http);
-                    const deps = { api: getApi(), buffer, filter, config };
+                    const deps = { api: getApi(), buffer, filter, config, nameCache };
                     createHTTPServer(registerTools, deps, port, opts.auth || null);
                     console.error(`[mcp] HTTP server started on port ${port}`);
                 } else {
-                    await createMCPServer(getApi(), buffer, filter, config);
+                    await createMCPServer(getApi(), buffer, filter, config, nameCache);
                 }
             } catch (e) {
                 console.error("[mcp] Failed to start MCP server:", e.message);
@@ -115,9 +122,7 @@ export function registerMCPCommands(program) {
 
                     buffer.push(normalized.threadId, normalized);
                     notifier.onMessage(normalized);
-                    console.error(
-                        `[mcp] Buffered ${normalized.threadType} msg from ${normalized.threadId}`,
-                    );
+                    console.error(`[mcp] Buffered ${normalized.threadType} msg from ${normalized.threadId}`);
                 });
 
                 api.listener.on("connected", () => {

package/src/commands/oa-init.js

@@ -140,7 +140,7 @@ function createWebhookServer(oaId) {
                     const msg = event.message?.text || "";
                     if (eventName === "user_send_text") info(`[text] ${sender}: ${msg}`);
                     else info(`[${eventName}] from ${sender}`);
-                } catch (_) {
+                } catch {
                     /* test ping */
                 }
                 res.writeHead(200, { "Content-Type": "application/json" });

package/src/commands/oa.js

@@ -10,7 +10,6 @@ import {
     saveOAToken,
     saveOACreds,
     loadOACreds,
-    loadOAToken,
     getOAuthUrl,
     exchangeCode,
     refreshAccessToken,
@@ -208,7 +207,7 @@ export function registerOACommands(program) {
                     const d = result.data || result;
                     info(`OA: ${d.name || "N/A"} (ID: ${d.oa_id || "N/A"})`);
                     if (d.description) info(`Description: ${d.description}`);
-                    if (d.num_follower != null) info(`Followers: ${d.num_follower}`);
+                    if (d.num_follower !== null && d.num_follower !== undefined) info(`Followers: ${d.num_follower}`);
                 });
             } catch (e) {
                 error(e.message);

package/src/commands/poll.js

@@ -38,7 +38,7 @@ export function registerPollCommands(program) {
                     success(`Poll created: "${question}"`);
                     info(`Poll ID: ${result.poll_id}`);
                     if (result.options) {
-                        result.options.forEach((o, i) => console.log(`  [${o.option_id}] ${o.content}`));
+                        result.options.forEach((o) => console.log(`  [${o.option_id}] ${o.content}`));
                     }
                 });
             } catch (e) {

package/src/core/oa-client.js

@@ -271,7 +271,6 @@ export async function removeFollowerFromTag(userId, tagName, oaId = "default") {
 /** Upload image to OA (returns attachment_id). */
 export async function uploadImage(filePath, oaId = "default") {
     const token = getToken(oaId);
-    const { default: FormData } = await import("node-fetch");
     // Use native FormData-like via node-fetch's Blob
     const fileData = fs.readFileSync(filePath);
     const blob = new (await import("node:buffer")).Blob([fileData]);

package/src/mcp/mcp-http-transport.js

@@ -35,7 +35,7 @@ export function createHTTPServer(registerToolsFn, deps, port, authToken) {
     app.post("/mcp", async (req, res) => {
         try {
             const server = new McpServer({ name: "zalo-agent", version: "1.0.0" });
-            registerToolsFn(server, deps.api, deps.buffer, deps.filter, deps.config);
+            registerToolsFn(server, deps.api, deps.buffer, deps.filter, deps.config, deps.nameCache);
 
             const transport = new StreamableHTTPServerTransport({
                 sessionIdGenerator: undefined, // stateless mode

package/src/mcp/mcp-server.js

@@ -14,15 +14,16 @@ import { registerTools } from "./mcp-tools.js";
  * @param {import("./message-buffer.js").MessageBuffer} buffer
  * @param {import("./thread-filter.js").ThreadFilter} filter
  * @param {object} config - MCP config
+ * @param {import("./thread-name-cache.js").ThreadNameCache} [nameCache] - Thread name cache
  * @returns {Promise<McpServer>}
  */
-export async function createMCPServer(api, buffer, filter, config) {
+export async function createMCPServer(api, buffer, filter, config, nameCache) {
     const server = new McpServer({
         name: "zalo-agent",
         version: "1.0.0",
     });
 
-    registerTools(server, api, buffer, filter, config);
+    registerTools(server, api, buffer, filter, config, nameCache);
 
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/src/mcp/mcp-tools.js

@@ -1,13 +1,12 @@
 /**
  * MCP tool registrations for Zalo message access and sending.
- * Registers 4 tools: zalo_get_messages, zalo_send_message, zalo_list_threads, zalo_mark_read.
+ * Registers 5 tools: zalo_get_messages, zalo_send_message, zalo_list_threads, zalo_search_threads, zalo_mark_read.
  */
 
 import { z } from "zod";
 
 /** Thread type constants matching zca-js ThreadType enum */
 const THREAD_USER = 0;
-const THREAD_GROUP = 1;
 
 /**
  * Wrap a result object into MCP tool content format.
@@ -34,8 +33,9 @@ function err(message) {
  * @param {import("./message-buffer.js").MessageBuffer} buffer
  * @param {import("./thread-filter.js").ThreadFilter} filter
  * @param {object} config - MCP config
+ * @param {import("./thread-name-cache.js").ThreadNameCache} [nameCache] - Thread name cache
  */
-export function registerTools(server, api, buffer, filter, config) {
+export function registerTools(server, api, buffer, filter, config, nameCache) {
     const maxPerPoll = config.limits?.maxMessagesPerPoll ?? 20;
 
     // --- zalo_get_messages ---
@@ -46,28 +46,21 @@ export function registerTools(server, api, buffer, filter, config) {
             description:
                 "Get messages from Zalo threads (DMs and groups). Returns buffered messages since last read. Use 'since' cursor from previous response for incremental polling.",
             inputSchema: z.object({
-                threadId: z
-                    .string()
-                    .optional()
-                    .describe("Thread ID to read from. Omit for all watched threads."),
-                since: z
-                    .number()
-                    .int()
-                    .min(0)
-                    .default(0)
-                    .describe("Cursor from previous read for incremental polling"),
-                limit: z
-                    .number()
-                    .int()
-                    .min(1)
-                    .max(100)
-                    .default(maxPerPoll)
-                    .describe("Max messages to return"),
+                threadId: z.string().optional().describe("Thread ID to read from. Omit for all watched threads."),
+                since: z.number().int().min(0).default(0).describe("Cursor from previous read for incremental polling"),
+                limit: z.number().int().min(1).max(100).default(maxPerPoll).describe("Max messages to return"),
             }),
         },
         async ({ threadId, since, limit }) => {
             try {
                 const result = buffer.read(threadId, since, limit);
+                // Enrich messages with thread name from cache
+                if (nameCache) {
+                    for (const msg of result.messages) {
+                        const info = nameCache.get(msg.threadId);
+                        if (info) msg.threadName = info.name;
+                    }
+                }
                 return ok(result);
             } catch (e) {
                 console.error("[mcp-tools] zalo_get_messages error:", e.message);
@@ -81,8 +74,7 @@ export function registerTools(server, api, buffer, filter, config) {
         "zalo_send_message",
         {
             title: "Send Zalo Message",
-            description:
-                "Send a text message to a Zalo thread (DM or group). threadType: 0=DM(User), 1=Group.",
+            description: "Send a text message to a Zalo thread (DM or group). threadType: 0=DM(User), 1=Group.",
             inputSchema: z.object({
                 threadId: z.string().describe("Thread ID to send message to"),
                 text: z.string().min(1).describe("Message text to send"),
@@ -129,12 +121,15 @@ export function registerTools(server, api, buffer, filter, config) {
                 const enriched = stats.map((t) => {
                     const thread = buffer._threads.get(t.threadId);
                     const threadType = thread?.messages?.[0]?.threadType ?? "unknown";
-                    return { ...t, threadType };
+                    const cached = nameCache?.get(t.threadId);
+                    return {
+                        ...t,
+                        threadType,
+                        name: cached?.name ?? null,
+                        ...(cached?.memberCount !== undefined && { memberCount: cached.memberCount }),
+                    };
                 });
-                const filtered =
-                    type === "all"
-                        ? enriched
-                        : enriched.filter((t) => t.threadType === type);
+                const filtered = type === "all" ? enriched : enriched.filter((t) => t.threadType === type);
                 return ok({ threads: filtered, total: filtered.length });
             } catch (e) {
                 console.error("[mcp-tools] zalo_list_threads error:", e.message);
@@ -143,6 +138,36 @@ export function registerTools(server, api, buffer, filter, config) {
         },
     );
 
+    // --- zalo_search_threads ---
+    server.registerTool(
+        "zalo_search_threads",
+        {
+            title: "Search Zalo Threads",
+            description:
+                "Search threads (groups/DMs) by name. Uses fuzzy Vietnamese-aware matching. Useful for finding a thread ID by name.",
+            inputSchema: z.object({
+                query: z.string().min(1).describe("Search keyword (fuzzy match, case-insensitive, accent-insensitive)"),
+                type: z
+                    .enum(["group", "dm", "all"])
+                    .default("all")
+                    .describe("Filter by thread type: 'dm', 'group', or 'all'"),
+                limit: z.number().int().min(1).max(50).default(10).describe("Max results to return"),
+            }),
+        },
+        async ({ query, type, limit }) => {
+            try {
+                if (!nameCache?.ready) {
+                    return err("Thread name cache not initialized yet. Try again shortly.");
+                }
+                const results = nameCache.search(query, type, limit);
+                return ok({ results, total: results.length });
+            } catch (e) {
+                console.error("[mcp-tools] zalo_search_threads error:", e.message);
+                return err(e.message);
+            }
+        },
+    );
+
     // --- zalo_mark_read ---
     server.registerTool(
         "zalo_mark_read",

package/src/mcp/message-buffer.js

@@ -41,12 +41,10 @@ export class MessageBuffer {
      * @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());
+        const sources = threadId ? [this._threads.get(threadId)].filter(Boolean) : Array.from(this._threads.values());
 
         // Collect all messages after cursor, sorted by cursor
-        let all = [];
+        const all = [];
         for (const thread of sources) {
             for (const msg of thread.messages) {
                 if (msg._cursor > since) all.push(msg);

package/src/mcp/notifier.js

@@ -5,6 +5,20 @@
 
 import { parseDuration } from "./mcp-config.js";
 
+/** Emoji prefix per message type for notification previews */
+const TYPE_EMOJI = { text: "💬", image: "📷", file: "📎", link: "🔗", video: "🎬", audio: "🎵", gif: "🎞️" };
+
+/** Vietnamese label per message type for notification breakdown */
+const TYPE_LABEL = {
+    text: "text",
+    image: "ảnh",
+    file: "file",
+    link: "link",
+    video: "video",
+    audio: "audio",
+    gif: "gif",
+};
+
 export class ZaloNotifier {
     /**
      * @param {object} api - zca-js API instance
@@ -60,13 +74,20 @@ export class ZaloNotifier {
         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) => `- ${m.senderName || m.senderId}: ${(m.text || "").slice(0, 50)}`)
+            .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 trong ${this._formatWindow()}:\n${preview}${suffix}`;
+        const text = `🔔 ${count} tin nhắn mới [${typeBreakdown}] trong ${this._formatWindow()}:\n${preview}${suffix}`;
 
         try {
             // threadType 1 = Group conversation
@@ -78,6 +99,22 @@ export class ZaloNotifier {
         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);

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;
+    }
+}

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

@@ -0,0 +1,139 @@
+import { describe, it, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+import { ThreadNameCache } from "./thread-name-cache.js";
+
+/** Create a mock API that returns predictable group/friend data */
+function createMockApi(groups = {}, friends = []) {
+    return {
+        getAllGroups: async () => ({
+            gridVerMap: Object.fromEntries(Object.keys(groups).map((id) => [id, 1])),
+        }),
+        getGroupInfo: async (ids) => ({
+            gridInfoMap: Object.fromEntries(ids.filter((id) => groups[id]).map((id) => [id, groups[id]])),
+        }),
+        getAllFriends: async () => friends,
+    };
+}
+
+describe("ThreadNameCache", () => {
+    let cache;
+
+    beforeEach(() => {
+        cache = new ThreadNameCache();
+    });
+
+    it("starts empty and not ready", () => {
+        assert.equal(cache.ready, false);
+        assert.equal(cache.size, 0);
+        assert.equal(cache.get("any"), null);
+        assert.equal(cache.getName("any"), null);
+    });
+
+    it("loads groups and friends on init", async () => {
+        const api = createMockApi(
+            {
+                g1: { name: "Nhóm Chờ Báo Giá", totalMember: 20 },
+                g2: { name: "Soạn hàng Q. Vũ", totalMember: 15 },
+            },
+            [
+                { userId: "u1", displayName: "Viet Anh", zaloName: "VA" },
+                { userId: "u2", zaloName: "Bob" },
+            ],
+        );
+
+        await cache.init(api);
+
+        assert.equal(cache.ready, true);
+        assert.equal(cache.size, 4);
+        assert.deepEqual(cache.get("g1"), { name: "Nhóm Chờ Báo Giá", type: "group", memberCount: 20 });
+        assert.equal(cache.getName("g2"), "Soạn hàng Q. Vũ");
+        assert.deepEqual(cache.get("u1"), { name: "Viet Anh", type: "dm" });
+        assert.equal(cache.getName("u2"), "Bob");
+    });
+
+    it("handles API failures gracefully", async () => {
+        const api = {
+            getAllGroups: async () => {
+                throw new Error("network error");
+            },
+            getAllFriends: async () => {
+                throw new Error("network error");
+            },
+        };
+
+        await cache.init(api);
+
+        assert.equal(cache.ready, true);
+        assert.equal(cache.size, 0);
+    });
+
+    describe("search", () => {
+        beforeEach(async () => {
+            const api = createMockApi(
+                {
+                    g1: { name: "Nhóm Chờ Báo Giá", totalMember: 20 },
+                    g2: { name: "Soạn hàng Q. Vũ - QV", totalMember: 15 },
+                    g3: { name: "Soạn hàng kho 2", totalMember: 8 },
+                    g4: { name: "Admin Team", totalMember: 5 },
+                },
+                [{ userId: "u1", displayName: "Soạn Văn", zaloName: "SV" }],
+            );
+            await cache.init(api);
+        });
+
+        it("finds groups by Vietnamese name (accent-insensitive)", () => {
+            const results = cache.search("soan hang");
+            assert.equal(results.length, 2);
+            assert.equal(results[0].name, "Soạn hàng kho 2");
+            assert.equal(results[1].name, "Soạn hàng Q. Vũ - QV");
+        });
+
+        it("finds with exact Vietnamese diacritics", () => {
+            const results = cache.search("Soạn hàng");
+            assert.equal(results.length, 2);
+            assert.ok(results.every((r) => r.type === "group"));
+        });
+
+        it("filters by type", () => {
+            const groups = cache.search("Soạn", "group");
+            assert.equal(groups.length, 2);
+            assert.ok(groups.every((r) => r.type === "group"));
+
+            const dms = cache.search("Soạn", "dm");
+            assert.equal(dms.length, 1);
+            assert.equal(dms[0].name, "Soạn Văn");
+        });
+
+        it("respects limit parameter", () => {
+            const results = cache.search("Soạn", "all", 1);
+            assert.equal(results.length, 1);
+        });
+
+        it("returns empty for no match", () => {
+            const results = cache.search("xyz_nonexistent");
+            assert.equal(results.length, 0);
+        });
+
+        it("prioritizes prefix matches", () => {
+            const results = cache.search("Admin");
+            assert.equal(results[0].name, "Admin Team");
+        });
+    });
+
+    describe("set (update)", () => {
+        it("updates existing entry", async () => {
+            const api = createMockApi({ g1: { name: "Old Name", totalMember: 5 } }, []);
+            await cache.init(api);
+
+            cache.set("g1", { name: "New Name" });
+            assert.equal(cache.getName("g1"), "New Name");
+            assert.equal(cache.get("g1").type, "group");
+            assert.equal(cache.get("g1").memberCount, 5);
+        });
+
+        it("adds new entry", () => {
+            cache.set("new1", { name: "New Group", type: "group", memberCount: 3 });
+            assert.deepEqual(cache.get("new1"), { name: "New Group", type: "group", memberCount: 3 });
+        });
+    });
+});

package/src/utils/qr-display.js

@@ -59,12 +59,14 @@ export function displayQR(event) {
     // JSON mode: structured output for AI agents — no terminal escapes, no noise
     if (jsonMode) {
         if (imageB64) {
-            console.log(JSON.stringify({
-                event: "qr",
-                image: imageB64,
-                file: QR_PATH,
-                dataUrl: `data:image/png;base64,${imageB64}`,
-            }));
+            console.log(
+                JSON.stringify({
+                    event: "qr",
+                    image: imageB64,
+                    file: QR_PATH,
+                    dataUrl: `data:image/png;base64,${imageB64}`,
+                }),
+            );
         }
         return;
     }

package/src/utils/qr-display.test.js

@@ -9,8 +9,7 @@ import { existsSync, unlinkSync, mkdirSync } from "fs";
 import { dirname } from "path";
 
 // Tiny valid 1x1 white PNG as base64 (for testing without real QR)
-const TINY_PNG_B64 =
-    "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==";
+const TINY_PNG_B64 = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==";
 
 describe("displayQR", () => {
     let originalLog;

package/src/utils/qr-http-server.js

@@ -99,6 +99,20 @@ setInterval(async()=>{
 },2000);
 </script>
 </body></html>`);
+        } else if (req.url === "/qr.png") {
+            // Raw PNG image endpoint — for agents to send direct image link
+            if (!existsSync(qrImagePath)) {
+                res.writeHead(404, { "Content-Type": "text/plain" });
+                res.end("QR not generated yet");
+                return;
+            }
+            const img = readFileSync(qrImagePath);
+            res.writeHead(200, {
+                "Content-Type": "image/png",
+                "Content-Length": img.length,
+                "Cache-Control": "no-cache, no-store",
+            });
+            res.end(img);
         } else if (req.url === "/status") {
             // Login status endpoint for browser polling
             let loggedIn = false;
@@ -134,12 +148,16 @@ setInterval(async()=>{
         } catch {}
 
         if (jsonMode) {
-            console.log(JSON.stringify({
-                event: "qr_server",
-                port: actualPort,
-                localUrl: `http://localhost:${actualPort}/qr`,
-                publicUrl: publicIp ? `http://${publicIp}:${actualPort}/qr` : null,
-            }));
+            console.log(
+                JSON.stringify({
+                    event: "qr_server",
+                    port: actualPort,
+                    localUrl: `http://localhost:${actualPort}/qr`,
+                    imageUrl: `http://localhost:${actualPort}/qr.png`,
+                    publicUrl: publicIp ? `http://${publicIp}:${actualPort}/qr` : null,
+                    publicImageUrl: publicIp ? `http://${publicIp}:${actualPort}/qr.png` : null,
+                }),
+            );
         } else {
             info(`QR available at: http://localhost:${actualPort}/qr`);
             if (publicIp) info(`On VPS, open: http://${publicIp}:${actualPort}/qr`);