@ardennguyen/zalo-agent-cli 1.0.7

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/bank-helpers.js

@@ -0,0 +1,233 @@
+/**
+ * Vietnamese bank BIN mapping + VietQR image generation via qr.sepay.vn.
+ */
+
+import { mkdtempSync, writeFileSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import nodefetch from "node-fetch";
+
+/** Bank name aliases (lowercase, no spaces) → BIN codes. */
+export const BANK_NAME_TO_BIN = {
+    abbank: 970425,
+    acb: 970416,
+    agribank: 970405,
+    bidv: 970418,
+    bvbank: 970454,
+    bacabank: 970409,
+    baoviet: 970438,
+    cake: 546034,
+    cbbank: 970444,
+    cimb: 422589,
+    coopbank: 970446,
+    dbs: 796500,
+    dongabank: 970406,
+    eximbank: 970431,
+    gpbank: 970408,
+    hdbank: 970437,
+    hsbc: 458761,
+    hongleong: 970442,
+    ibkhcm: 970456,
+    ibkhn: 970455,
+    indovina: 970434,
+    kbank: 668888,
+    kienlongbank: 970452,
+    kookminhcm: 970463,
+    kookminhn: 970462,
+    mbbank: 970422,
+    mb: 970422,
+    msb: 970426,
+    ncb: 970419,
+    namabank: 970428,
+    nonghyup: 801011,
+    ocb: 970448,
+    oceanbank: 970414,
+    pgbank: 970430,
+    pvcombank: 970412,
+    publicbank: 970439,
+    scb: 970429,
+    shb: 970443,
+    sacombank: 970403,
+    saigonbank: 970400,
+    seabank: 970440,
+    shinhan: 970424,
+    standardchartered: 970410,
+    tnex: 9704261,
+    tpbank: 970423,
+    techcombank: 970407,
+    timo: 963388,
+    ubank: 546035,
+    uob: 970458,
+    vib: 970441,
+    vpbank: 970432,
+    vrb: 970421,
+    vietabank: 970427,
+    vietbank: 970433,
+    vietcombank: 970436,
+    vcb: 970436,
+    vietinbank: 970415,
+    ctg: 970415,
+    woori: 970457,
+};
+
+/** BIN → display name. */
+export const BIN_TO_DISPLAY = {
+    970425: "ABBank",
+    970416: "ACB",
+    970405: "Agribank",
+    970418: "BIDV",
+    970454: "BVBank",
+    970409: "BacA Bank",
+    970438: "BaoViet Bank",
+    546034: "CAKE",
+    970444: "CB Bank",
+    422589: "CIMB",
+    970446: "Co-op Bank",
+    796500: "DBS",
+    970406: "DongA Bank",
+    970431: "Eximbank",
+    970408: "GPBank",
+    970437: "HDBank",
+    458761: "HSBC",
+    970442: "Hong Leong",
+    970456: "IBK HCM",
+    970455: "IBK HN",
+    970434: "Indovina",
+    668888: "KBank",
+    970452: "KienlongBank",
+    970463: "Kookmin HCM",
+    970462: "Kookmin HN",
+    970422: "MB Bank",
+    970426: "MSB",
+    970419: "NCB",
+    970428: "Nam A Bank",
+    801011: "NongHyup",
+    970448: "OCB",
+    970414: "OceanBank",
+    970430: "PGBank",
+    970412: "PVcomBank",
+    970439: "Public Bank",
+    970429: "SCB",
+    970443: "SHB",
+    970403: "Sacombank",
+    970400: "Saigon Bank",
+    970440: "SeABank",
+    970424: "Shinhan",
+    970410: "Standard Chartered",
+    9704261: "TNEX",
+    970423: "TPBank",
+    970407: "Techcombank",
+    963388: "Timo",
+    546035: "UBank",
+    970458: "UOB",
+    970441: "VIB",
+    970432: "VPBank",
+    970421: "VRB",
+    970427: "VietABank",
+    970433: "VietBank",
+    970436: "Vietcombank",
+    970415: "VietinBank",
+    970457: "Woori",
+};
+
+/** BIN → SePay short_name for qr.sepay.vn URL. */
+const BIN_TO_SEPAY = {
+    970415: "VietinBank",
+    970436: "Vietcombank",
+    970422: "MBBank",
+    970416: "ACB",
+    970432: "VPBank",
+    970423: "TPBank",
+    970426: "MSB",
+    970428: "NamABank",
+    970449: "LienVietPostBank",
+    970454: "VietCapitalBank",
+    970418: "BIDV",
+    970403: "Sacombank",
+    970441: "VIB",
+    970437: "HDBank",
+    970440: "SeABank",
+    970408: "GPBank",
+    970412: "PVcomBank",
+    970419: "NCB",
+    970424: "ShinhanBank",
+    970429: "SCB",
+    970430: "PGBank",
+    970405: "Agribank",
+    970407: "Techcombank",
+    970400: "SaigonBank",
+    970406: "DongABank",
+    970409: "BacABank",
+    970410: "StandardChartered",
+    970414: "Oceanbank",
+    970421: "VRB",
+    970425: "ABBANK",
+    970427: "VietABank",
+    970431: "Eximbank",
+    970433: "VietBank",
+    970434: "IndovinaBank",
+    970438: "BaoVietBank",
+    970439: "PublicBank",
+    970443: "SHB",
+    970444: "CBBank",
+    970448: "OCB",
+    970452: "KienLongBank",
+    422589: "CIMB",
+    458761: "HSBC",
+    796500: "DBSBank",
+    801011: "Nonghyup",
+    970442: "HongLeong",
+    970457: "Woori",
+    970458: "UnitedOverseas",
+    970462: "KookminHN",
+    970463: "KookminHCM",
+    970446: "COOPBANK",
+};
+
+/**
+ * Resolve bank name or BIN string to numeric BIN code.
+ * @param {string} input - Bank name alias or BIN number
+ * @returns {number|null}
+ */
+export function resolveBankBin(input) {
+    if (/^\d+$/.test(input)) {
+        const n = Number(input);
+        return BIN_TO_DISPLAY[n] ? n : null;
+    }
+    return BANK_NAME_TO_BIN[input.toLowerCase().replace(/[\s_]/g, "")] || null;
+}
+
+/**
+ * Download VietQR transfer image from qr.sepay.vn.
+ * @param {number} bin
+ * @param {string} accountNumber
+ * @param {number|null} amount
+ * @param {string|null} content - Max 50 chars, SePay param name is "des"
+ * @param {string} template - compact | print | qronly
+ * @returns {Promise<string|null>} Temp file path or null on failure
+ */
+export async function generateQrTransferImage(bin, accountNumber, amount = null, content = null, template = "compact") {
+    const sepayShort = BIN_TO_SEPAY[bin];
+    if (!sepayShort) return null;
+
+    const params = new URLSearchParams({ bank: sepayShort, acc: accountNumber, template });
+    if (amount !== null && amount !== undefined) params.set("amount", String(amount));
+    if (content) params.set("des", content);
+
+    const url = `https://qr.sepay.vn/img?${params}`;
+    const tmpDir = mkdtempSync(join(tmpdir(), "qr_transfer_"));
+    const outPath = join(tmpDir, "qr.png");
+
+    try {
+        const resp = await nodefetch(url, {
+            headers: { "User-Agent": "Mozilla/5.0" },
+            timeout: 15000,
+        });
+        if (!resp.ok) return null;
+        const buffer = Buffer.from(await resp.arrayBuffer());
+        writeFileSync(outPath, buffer);
+        return outPath;
+    } catch {
+        return null;
+    }
+}

package/src/utils/bank-helpers.test.js

@@ -0,0 +1,66 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { resolveBankBin, BIN_TO_DISPLAY, BANK_NAME_TO_BIN } from "./bank-helpers.js";
+
+describe("resolveBankBin", () => {
+    it("resolves OCB by name", () => {
+        assert.equal(resolveBankBin("ocb"), 970448);
+    });
+
+    it("resolves VCB alias", () => {
+        assert.equal(resolveBankBin("vcb"), 970436);
+    });
+
+    it("resolves Vietcombank full name", () => {
+        assert.equal(resolveBankBin("vietcombank"), 970436);
+    });
+
+    it("resolves BIDV by BIN string", () => {
+        assert.equal(resolveBankBin("970418"), 970418);
+    });
+
+    it("returns null for unknown name", () => {
+        assert.equal(resolveBankBin("unknown"), null);
+    });
+
+    it("returns null for unknown BIN", () => {
+        assert.equal(resolveBankBin("999999"), null);
+    });
+
+    it("is case insensitive", () => {
+        assert.equal(resolveBankBin("OCB"), 970448);
+        assert.equal(resolveBankBin("Vietcombank"), 970436);
+        assert.equal(resolveBankBin("BIDV"), 970418);
+    });
+
+    it("handles spaces and underscores", () => {
+        assert.equal(resolveBankBin("mb bank"), 970422);
+        assert.equal(resolveBankBin("mb_bank"), 970422);
+    });
+
+    it("resolves MB shorthand", () => {
+        assert.equal(resolveBankBin("mb"), 970422);
+    });
+
+    it("resolves CTG alias for VietinBank", () => {
+        assert.equal(resolveBankBin("ctg"), 970415);
+    });
+});
+
+describe("BIN_TO_DISPLAY", () => {
+    it("has at least 50 banks", () => {
+        assert.ok(Object.keys(BIN_TO_DISPLAY).length >= 50);
+    });
+
+    it("maps known BINs correctly", () => {
+        assert.equal(BIN_TO_DISPLAY[970448], "OCB");
+        assert.equal(BIN_TO_DISPLAY[970436], "Vietcombank");
+        assert.equal(BIN_TO_DISPLAY[970418], "BIDV");
+    });
+});
+
+describe("BANK_NAME_TO_BIN", () => {
+    it("has at least 50 aliases", () => {
+        assert.ok(Object.keys(BANK_NAME_TO_BIN).length >= 50);
+    });
+});

package/src/utils/extract-message-text.js

@@ -0,0 +1,21 @@
+/**
+ * Extract readable text from non-string Zalo message content.
+ * Handles reply/quote messages, bubble messages, recommendations, link previews, etc.
+ *
+ * Field priority: params.message → description → title → text → msg → href → content (string) → JSON fallback
+ */
+export function extractMessageText(content, msgType) {
+    if (!content || typeof content !== "object") return `[${msgType || "attachment"}]`;
+    if (content.params?.message) return content.params.message;
+    if (content.description) return content.description;
+    if (content.title) return content.title;
+    if (content.text) return content.text;
+    if (content.msg) return content.msg;
+    if (content.href) return content.href;
+    if (content.content && typeof content.content === "string") return content.content;
+    try {
+        const str = JSON.stringify(content);
+        if (str.length < 200) return `[${msgType || "object"}: ${str}]`;
+    } catch {}
+    return `[${msgType || "attachment"}]`;
+}

package/src/utils/output.js

@@ -0,0 +1,21 @@
+/**
+ * Output formatting utilities — JSON mode and colored human-readable output.
+ */
+
+import chalk from "chalk";
+
+/** Emit JSON or call human formatter based on --json flag. */
+export function output(data, jsonMode, humanFormatter) {
+    if (jsonMode) {
+        console.log(JSON.stringify(data, null, 2));
+    } else if (humanFormatter) {
+        humanFormatter(data);
+    } else {
+        console.log(JSON.stringify(data, null, 2));
+    }
+}
+
+export const success = (msg) => console.log(chalk.green("  ✓ " + msg));
+export const error = (msg) => console.log(chalk.red("  ✗ " + msg));
+export const info = (msg) => console.log(chalk.cyan("  ● " + msg));
+export const warning = (msg) => console.log(chalk.yellow("  ⚠ " + msg));

package/src/utils/proxy-helpers.js

@@ -0,0 +1,14 @@
+/**
+ * Proxy URL helpers — masking passwords for safe display.
+ */
+
+/**
+ * Mask password in proxy URL for safe display.
+ * Example: http://user:secret@host:8080 → http://user:***@host:8080
+ * @param {string|null} proxyUrl
+ * @returns {string}
+ */
+export function maskProxy(proxyUrl) {
+    if (!proxyUrl) return "none";
+    return proxyUrl.replace(/(\/\/[^:]+:)[^@]+(@)/, "$1***$2");
+}

package/src/utils/proxy-helpers.test.js

@@ -0,0 +1,36 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { maskProxy } from "./proxy-helpers.js";
+
+describe("maskProxy", () => {
+    it("masks password in http URL", () => {
+        assert.equal(maskProxy("http://user:secret@host:8080"), "http://user:***@host:8080");
+    });
+
+    it("masks password in socks5 URL", () => {
+        assert.equal(maskProxy("socks5://admin:p4ss@1.2.3.4:1080"), "socks5://admin:***@1.2.3.4:1080");
+    });
+
+    it("masks long password", () => {
+        assert.equal(
+            maskProxy("http://3AccFfq:pkLbHLRjhqids_session-Ntekoom2@geo.iproyal.com:12321"),
+            "http://3AccFfq:***@geo.iproyal.com:12321",
+        );
+    });
+
+    it("returns URL unchanged when no password", () => {
+        assert.equal(maskProxy("http://host:8080"), "http://host:8080");
+    });
+
+    it('returns "none" for null', () => {
+        assert.equal(maskProxy(null), "none");
+    });
+
+    it('returns "none" for empty string', () => {
+        assert.equal(maskProxy(""), "none");
+    });
+
+    it('returns "none" for undefined', () => {
+        assert.equal(maskProxy(undefined), "none");
+    });
+});