@ardennguyen/zalo-agent-cli 2.5.1 → 2.5.4

package/src/commands/bank.js

@@ -0,0 +1,126 @@
+/**
+ * Bank commands — the account's saved bank accounts, and the banks Zalo supports.
+ *
+ * `msg send-bank` and `msg send-qr-transfer` send a card or a QR to a thread;
+ * these manage the accounts saved in Zalo's own "bank" list and read its bank
+ * directory.
+ */
+
+import { getApi } from "../core/zalo-client.js";
+import { success, error, info, output } from "../utils/output.js";
+import { parseIntOption, parseIntAtLeast } from "../utils/parse-options.js";
+import { resolveBankBin, BIN_TO_DISPLAY } from "../utils/bank-helpers.js";
+import { findBankAccount, filterBanks } from "../core/bank-accounts.js";
+
+/**
+ * A bank name or BIN as the BIN Zalo wants.
+ *
+ * @param {string} input
+ * @returns {number}
+ * @throws {Error} for an unknown bank
+ */
+function binOrThrow(input) {
+    const bin = resolveBankBin(String(input));
+    if (!bin) throw new Error(`Unknown bank: '${input}'. "bank list" shows the banks Zalo supports.`);
+    return bin;
+}
+
+/** One saved account as a line of text. */
+function accountLine(a) {
+    const bank = BIN_TO_DISPLAY[a.bin] || a.bin;
+    return `  ${a.account_id}  ${bank}  ${a.bank_number}  ${a.holder_name}${a.default ? "  (default)" : ""}`;
+}
+
+export function registerBankCommands(program) {
+    const bank = program.command("bank").description("Manage your saved bank accounts and list supported banks");
+
+    bank.command("list")
+        .description("List the banks Zalo supports (name, short name and BIN)")
+        .option("-q, --query <text>", "Only banks whose name, short name or BIN contains this text")
+        .action(async (opts) => {
+            try {
+                const result = await getApi().getListBank();
+                const banks = filterBanks(result?.banks, opts.query);
+                output({ ...result, banks }, program.opts().json, () => {
+                    info(`${banks.length} bank(s)`);
+                    for (const b of banks) console.log(`  ${b.bin}  ${b.short_name || "?"}  ${b.name}`);
+                });
+            } catch (e) {
+                error(`Get banks failed: ${e.message}`);
+            }
+        });
+
+    bank.command("accounts")
+        .description("List your saved bank accounts")
+        .option("-p, --page <n>", "Page number (starts at 0)", parseIntAtLeast(0), 0)
+        .option("-l, --limit <n>", "Accounts per page", parseIntAtLeast(1), 20)
+        .action(async (opts) => {
+            try {
+                const result = await getApi().getListBankAccount(opts.page, opts.limit);
+                output(result, program.opts().json, () => {
+                    const accounts = result?.myBanks ?? [];
+                    info(`${accounts.length} account(s) on this page (total: ${result?.total ?? accounts.length})`);
+                    for (const a of accounts) console.log(accountLine(a));
+                    if (result?.hasMore) info("More accounts exist: use --page to see them.");
+                });
+            } catch (e) {
+                error(`Get bank accounts failed: ${e.message}`);
+            }
+        });
+
+    bank.command("add <accountNumber>")
+        .description("Save a bank account to your Zalo bank list")
+        .requiredOption("-b, --bank <name>", "Bank name (ocb, vcb, bidv, ...) or BIN code")
+        .requiredOption("-n, --name <holder>", "Account holder name")
+        .action(async (accountNumber, opts) => {
+            try {
+                const bin = binOrThrow(opts.bank);
+                const result = await getApi().createBankAccount({
+                    binBank: bin,
+                    numAccBank: accountNumber,
+                    nameAccBank: opts.name,
+                });
+                output(result, program.opts().json, () =>
+                    success(`Bank account saved: ${BIN_TO_DISPLAY[bin] || bin} / ${accountNumber}`),
+                );
+            } catch (e) {
+                error(`Add bank account failed: ${e.message}`);
+            }
+        });
+
+    bank.command("update <accountId> <accountNumber>")
+        .description('Change a saved bank account (get <accountId> from "bank accounts")')
+        .requiredOption("-b, --bank <name>", "Bank name or BIN code")
+        .requiredOption("-n, --name <holder>", "Account holder name")
+        .action(async (accountId, accountNumber, opts) => {
+            try {
+                const result = await getApi().updateBankAccount({
+                    accountId: parseIntOption(accountId),
+                    binBank: binOrThrow(opts.bank),
+                    numAccBank: accountNumber,
+                    nameAccBank: opts.name,
+                });
+                output(result, program.opts().json, () => success("Bank account updated"));
+            } catch (e) {
+                error(`Update bank account failed: ${e.message}`);
+            }
+        });
+
+    bank.command("remove <accountId>")
+        .description('Delete a saved bank account (get <accountId> from "bank accounts")')
+        .action(async (accountId) => {
+            try {
+                const id = parseIntOption(accountId);
+                // Zalo wants to know whether the account is the default one, and only the list knows.
+                const found = await findBankAccount(getApi(), id);
+                if (!found) {
+                    error(`No saved bank account with id ${id}. "bank accounts" lists them.`);
+                    return;
+                }
+                const result = await getApi().deleteBankAccount({ accountId: id, isDefault: Boolean(found.default) });
+                output(result, program.opts().json, () => success(`Bank account ${id} deleted`));
+            } catch (e) {
+                error(`Delete bank account failed: ${e.message}`);
+            }
+        });
+}

package/src/commands/catalog.js

@@ -6,6 +6,7 @@ import { resolve } from "path";
 import { getApi } from "../core/zalo-client.js";
 import { success, error, info, output } from "../utils/output.js";
 import { parseIntOption } from "../utils/parse-options.js";
+import { parseOnOff } from "../utils/cli-args.js";
 
 export function registerCatalogCommands(program) {
     const catalog = program.command("catalog").description("Manage Zalo Shop catalogs and products");
@@ -141,4 +142,17 @@ export function registerCatalogCommands(program) {
                 error(`Upload photo failed: ${e.message}`);
             }
         });
+
+    catalog
+        .command("register <on|off>")
+        .description("Turn the Zalo Shop catalog feature on or off for this account")
+        .action(async (state) => {
+            try {
+                const enable = parseOnOff(state, "catalog");
+                const result = await getApi().registerCatalog(enable);
+                output(result, program.opts().json, () => success(`Catalog ${enable ? "enabled" : "disabled"}`));
+            } catch (e) {
+                error(e.message);
+            }
+        });
 }

package/src/commands/conv.js

@@ -802,4 +802,23 @@ export function registerConvCommands(program, deps = {}) {
             info("Nothing was sent to Zalo; this only cleared the local cache.");
             process.exit(0);
         });
+
+    conv.command("muted")
+        .description("List the conversations and groups you have muted")
+        .action(async () => {
+            try {
+                const result = await getApi().getMute();
+                output(result, program.opts().json, () => {
+                    for (const [label, entries] of [
+                        ["chat", result?.chatEntries ?? []],
+                        ["group", result?.groupChatEntries ?? []],
+                    ]) {
+                        info(`${entries.length} muted ${label}(s)`);
+                        for (const m of entries) console.log(`  ${m.id}  mode=${m.muteMode}  duration=${m.duration}`);
+                    }
+                });
+            } catch (e) {
+                error(`Get muted conversations failed: ${e.message}`);
+            }
+        });
 }

package/src/commands/friend.js

@@ -5,12 +5,9 @@
 import { getApi } from "../core/zalo-client.js";
 import { success, error, info, output } from "../utils/output.js";
 import { parseIntOption } from "../utils/parse-options.js";
-
-/** Extract numeric error code from zca-js error message string. */
-function extractErrorCode(msg) {
-    const match = String(msg).match(/\((\-?\d+)\)/);
-    return match ? Number(match[1]) : null;
-}
+import { describeFriendAddError, extractErrorCode } from "../core/friend-requests.js";
+import { readUserAliases } from "../core/current-user-names.js";
+import { searchFriends } from "../core/friend-search.js";
 
 export function registerFriendCommands(program) {
     const friend = program.command("friend").description("Manage friends and contacts");
@@ -59,17 +56,14 @@ export function registerFriendCommands(program) {
 
     friend
         .command("search <name>")
-        .description("Search friends by name (returns thread_id for messaging)")
+        .description("Search friends by name or alias (returns thread_id for messaging)")
         .action(async (name) => {
             try {
                 const result = await getApi().getAllFriends();
                 const friends = Array.isArray(result) ? result : [];
-                const query = name.toLowerCase();
-                const matches = friends.filter((f) => {
-                    const dn = (f.displayName || "").toLowerCase();
-                    const zn = (f.zaloName || "").toLowerCase();
-                    return dn.includes(query) || zn.includes(query);
-                });
+                // The alias you set for a friend is not in the friend list; it comes from the alias list.
+                const aliases = await readUserAliases(getApi(), (m) => info(`${m}; matching names only`));
+                const matches = searchFriends(friends, aliases, name);
                 output(matches, program.opts().json, () => {
                     if (matches.length === 0) {
                         error(`No friends matching "${name}". Use "friend list" to see all.`);
@@ -79,7 +73,8 @@ export function registerFriendCommands(program) {
                     console.log();
                     for (const f of matches) {
                         const display = f.displayName || f.zaloName || "?";
-                        console.log(`  ${f.userId}  ${display}`);
+                        const aka = f.alias && f.alias !== display ? `  (alias: ${f.alias})` : "";
+                        console.log(`  ${f.userId}  ${display}${aka}`);
                     }
                     console.log();
                     info("Use the ID above as thread_id for messaging commands.");
@@ -142,13 +137,7 @@ export function registerFriendCommands(program) {
             } catch (e) {
                 // Map Zalo error codes to actionable messages
                 const code = e.code || extractErrorCode(e.message);
-                const errMap = {
-                    225: `Already friends with ${userId}. Use "friend list" to verify.`,
-                    215: `User ${userId} may have blocked you or is unreachable.`,
-                    222: `User ${userId} already sent you a friend request. Use "friend accept ${userId}" instead.`,
-                    "-1": `Invalid userId "${userId}". Use "friend find <phone>" to get the correct userId first.`,
-                };
-                error(errMap[code] || `Friend request failed (code ${code}): ${e.message}`);
+                error(describeFriendAddError(code, userId) || `Friend request failed (code ${code}): ${e.message}`);
             }
         });
 
@@ -393,4 +382,60 @@ export function registerFriendCommands(program) {
                 error(`Find by phone failed: ${e.message}`);
             }
         });
+
+    friend
+        .command("qr <userIds...>")
+        .description("Get the QR code image URL of one or more users")
+        .action(async (userIds) => {
+            try {
+                const result = await getApi().getQR(userIds);
+                output(result, program.opts().json, () => {
+                    for (const [uid, url] of Object.entries(result ?? {})) console.log(`  ${uid}  ${url}`);
+                });
+            } catch (e) {
+                error(`Get QR failed: ${e.message}`);
+            }
+        });
+
+    friend
+        .command("common-groups <friendIds...>")
+        .description("List the groups you share with one or more friends")
+        .action(async (friendIds) => {
+            try {
+                const result = await getApi().getRelatedFriendGroup(friendIds);
+                output(result, program.opts().json, () => {
+                    for (const [fid, groups] of Object.entries(result?.groupRelateds ?? {})) {
+                        info(`${fid}: ${groups.length} group(s)`);
+                        for (const g of groups) console.log(`  ${g}`);
+                    }
+                });
+            } catch (e) {
+                error(`Get shared groups failed: ${e.message}`);
+            }
+        });
+
+    friend
+        .command("biz <friendId>")
+        .description("Show the business account details of a user (category, address, website, email)")
+        .action(async (friendId) => {
+            try {
+                const result = await getApi().getBizAccount(friendId);
+                output(result, program.opts().json);
+            } catch (e) {
+                error(`Get business account failed: ${e.message}`);
+            }
+        });
+
+    friend
+        .command("block-feed <userId>")
+        .description("Hide a user's posts from your feed (or show them again with --unblock)")
+        .option("--unblock", "Show this user's feed again")
+        .action(async (userId, opts) => {
+            try {
+                const result = await getApi().blockViewFeed(!opts.unblock, userId);
+                output(result, program.opts().json, () => success(opts.unblock ? "Feed shown again" : "Feed hidden"));
+            } catch (e) {
+                error(`Block feed failed: ${e.message}`);
+            }
+        });
 }

package/src/commands/group.js

@@ -5,6 +5,7 @@
 
 import { resolve } from "path";
 import { getApi } from "../core/zalo-client.js";
+import { getInviteBoxInfo } from "../core/group-invite.js";
 import { getGroupHistory } from "../core/group-history.js";
 import { groupMemberUids } from "../core/group-members.js";
 import { success, error, info, warning, output } from "../utils/output.js";
@@ -336,9 +337,10 @@ export function registerGroupCommands(program) {
     group
         .command("leave <groupId>")
         .description("Leave a group")
-        .action(async (groupId) => {
+        .option("-s, --silent", "Leave without the usual notice to ordinary members (the owner still sees it)")
+        .action(async (groupId, opts) => {
             try {
-                const result = await getApi().leaveGroup(groupId);
+                const result = await getApi().leaveGroup(groupId, Boolean(opts.silent));
                 output(result, program.opts().json, () => success("Left group"));
             } catch (e) {
                 error(e.message);
@@ -654,4 +656,38 @@ export function registerGroupCommands(program) {
                 error(`Disperse group failed: ${e.message}`);
             }
         });
+
+    group
+        .command("link-preview <link>")
+        .description("Show a group's details from its invite link, before joining (does not join)")
+        .option("-p, --member-page <n>", "Member page to show", parseIntAtLeast(1), 1)
+        .action(async (link, opts) => {
+            try {
+                const result = await getApi().getGroupLinkInfo({ link, memberPage: opts.memberPage });
+                output(result, program.opts().json);
+            } catch (e) {
+                error(`Group link preview failed: ${e.message}`);
+            }
+        });
+
+    group
+        .command("invite-info <groupId>")
+        .description(
+            'Show a pending group invitation: the group, who invited you and when it expires (see "invite-boxes")',
+        )
+        .option("--member-page <n>", "Member page to show", parseIntAtLeast(1), 1)
+        .option("--member-count <n>", "Members per page", parseIntAtLeast(1), 10)
+        .action(async (groupId, opts) => {
+            try {
+                // zca-js's own call throws when the group has no topic; see core/group-invite.js.
+                const result = await getInviteBoxInfo(getApi(), {
+                    groupId,
+                    mpage: opts.memberPage,
+                    mcount: opts.memberCount,
+                });
+                output(result, program.opts().json);
+            } catch (e) {
+                error(`Group invite info failed: ${e.message}`);
+            }
+        });
 }

package/src/commands/listen.js

@@ -8,6 +8,7 @@ import { appendFileSync, mkdirSync, existsSync } from "fs";
 import { resolve, join } from "path";
 import { getApi, clearSession } from "../core/zalo-client.js";
 import { success, error, info, warning, output } from "../utils/output.js";
+import { resolveWebhookSecret } from "../utils/secrets.js";
 import { parseAccountId, selectDaemonAccount, loginDaemonAccount } from "../core/daemon-account.js";
 import { updateAccountName } from "../core/accounts.js";
 import { getAccountDir } from "../core/credentials.js";
@@ -20,6 +21,8 @@ import {
     spawnDaemonProcess,
 } from "../core/daemon-channel.js";
 import { createSyncRunners } from "../core/daemon-sync.js";
+import { createSocketContext, startEventLoopMonitor } from "../core/daemon-log.js";
+import { setUserInfoLogger } from "../core/user-info.js";
 import { createSocketTap } from "../core/socket-tap.js";
 import { createSelfHeal } from "../core/self-heal.js";
 import { createReadStateSync, readStateEvent } from "../core/read-state.js";
@@ -75,11 +78,15 @@ export function registerListenCommand(program) {
         )
         .option(
             "-e, --events <types>",
-            "Comma-separated event types: message,friend,group,reaction,read (default: message,friend,group,reaction,read)",
+            "Comma-separated event types: message,friend,group,reaction,read (default), plus the opt-in typing (someone is typing) and upload (Zalo finished processing a video or file you uploaded)",
             "message,friend,group,reaction,read",
         )
         .option("-f, --filter <type>", "Message filter: user (DM only), group (groups only), all", "all")
         .option("-w, --webhook <url>", "POST each event as JSON to this URL (for n8n, Make, etc.)")
+        .option(
+            "--webhook-secret <secret>",
+            "Sign webhook POSTs: sent as `Authorization: Bearer <secret>` and `X-Zalo-Signature: sha256=<HMAC of the body>`. Prefer the ZALO_WEBHOOK_SECRET[_<ownId>] environment variable: a flag is visible in the process list",
+        )
         .option("--no-self", "Exclude self-sent messages")
         .option("--auto-accept", "Auto-accept incoming friend requests")
         .option("--save <dir>", "Save messages locally as JSONL files (one file per thread, e.g. --save ./zalo-logs)")
@@ -96,6 +103,15 @@ export function registerListenCommand(program) {
         .option("--status", "Show background daemon status for this account")
         .action(async (opts) => {
             const jsonMode = program.opts().json;
+            // An empty secret is refused before anything else: see resolveWebhookSecret().
+            let cliWebhookSecret;
+            try {
+                if (opts.webhookSecret !== undefined)
+                    cliWebhookSecret = resolveWebhookSecret({ flag: opts.webhookSecret });
+            } catch (e) {
+                error(e.message);
+                process.exit(1);
+            }
             let activeAcc;
             try {
                 const requestedAccount =
@@ -384,7 +400,13 @@ export function registerListenCommand(program) {
             }
 
             const webhookUrl = opts.webhook?.trim() || envForAccount("ZALO_WEBHOOK_URL", activeAcc.ownId) || null;
-            const webhookSecret = envForAccount("ZALO_WEBHOOK_SECRET", activeAcc.ownId) || null;
+            const webhookSecret = resolveWebhookSecret({
+                flag: cliWebhookSecret,
+                env: envForAccount("ZALO_WEBHOOK_SECRET", activeAcc.ownId),
+            });
+            if (webhookSecret && !webhookUrl) {
+                warning("A webhook secret is set but no webhook URL: nothing will be signed or sent. Pass -w <url>.");
+            }
 
             /** Fire-and-forget webhook POST — never blocks event processing */
             function postWebhook(data) {
@@ -501,6 +523,17 @@ export function registerListenCommand(program) {
             // and one raw reader on the socket for the fields zca-js drops.
             // Built once, like the receipter: they outlive every re-login.
             const stageLock = createStageLock();
+            // See mcp.js: stage progress, event-loop stalls and refused lookups belong in the log too.
+            const daemonLog = (m) => console.error(`[listen] ${m}`);
+            const loopMonitor = startEventLoopMonitor({
+                log: daemonLog,
+                context: () => {
+                    const held = stageLock.current();
+                    return held ? `the ${held.stage} stage was running` : "";
+                },
+            });
+            const socketContext = createSocketContext({ lock: stageLock, monitor: loopMonitor });
+            setUserInfoLogger(daemonLog);
             const socketTap = createSocketTap({ log: (line) => console.error(`[listen] ${line}`) });
             // Read state other devices report -- a conversation read on the
             // phone, an unread mark set or cleared there -- which zca-js
@@ -655,6 +688,35 @@ export function registerListenCommand(program) {
                     });
                 }
 
+                // --- Typing and upload events (opt-in) ---
+                // Not in the default --events: typing is constant noise, and upload
+                // only matters to a caller that is uploading. Neither is stored.
+                // zca-js also emits `cipher_key`, the session's key material; it is
+                // deliberately never subscribed to, so it can reach no log, file or webhook.
+                if (enabledEvents.has("typing")) {
+                    api.listener.on("typing", (t) => {
+                        emitEvent(
+                            {
+                                event: "typing",
+                                threadId: t.threadId,
+                                isGroup: t.type === THREAD_GROUP,
+                                uid: t.data?.uid ?? null,
+                                isPC: Boolean(t.data?.isPC),
+                                data: t.data,
+                            },
+                            `Typing: ${t.data?.uid ?? "?"} in ${t.threadId}`,
+                        );
+                    });
+                }
+                if (enabledEvents.has("upload")) {
+                    api.listener.on("upload_attachment", (u) => {
+                        emitEvent(
+                            { event: "upload_attachment", fileId: u?.fileId ?? null, fileUrl: u?.fileUrl ?? null },
+                            `Upload finished: ${u?.fileId ?? "?"}`,
+                        );
+                    });
+                }
+
                 // --- Group events ---
                 // Also ungated for storage, for the same reason: with the
                 // default --events, being removed from a group was never
@@ -763,6 +825,7 @@ export function registerListenCommand(program) {
 
                 // --- Lifecycle events (MUST be on same listener for reconnect to work) ---
                 api.listener.on("connected", () => {
+                    socketContext.markUp();
                     if (reconnectCount > 0) {
                         info(`Reconnected (#${reconnectCount}, uptime: ${uptime()}, events: ${eventCount})`);
                     }
@@ -785,7 +848,7 @@ export function registerListenCommand(program) {
 
                 api.listener.on("disconnected", (code, _reason) => {
                     if (stopping) return;
-                    warning(`Disconnected (code: ${code}). Auto-retrying...`);
+                    warning(`Disconnected (code: ${code}). Auto-retrying... (${socketContext.describe()})`);
                     // First drop wins: a flapping socket that emits several
                     // `disconnected` before one `connected` is ONE outage, and the
                     // gap must span from the start of it.
@@ -805,7 +868,9 @@ export function registerListenCommand(program) {
                     reconnectCount++;
                     if (downSince === null) downSince = Date.now();
                     syncManager.markDisconnected();
-                    warning(`Connection closed (code: ${code}). Re-login in 5s... (uptime: ${uptime()})`);
+                    warning(
+                        `Connection closed (code: ${code}). Re-login in 5s... (uptime: ${uptime()}; ${socketContext.describe()})`,
+                    );
                     await new Promise((r) => setTimeout(r, 5000));
                     try {
                         clearSession();
@@ -926,6 +991,8 @@ export function registerListenCommand(program) {
                     runners: createSyncRunners({
                         getApi,
                         accountName: activeAcc.ownId,
+                        log: daemonLog,
+                        monitor: loopMonitor,
                         onSelfName: (name) => updateAccountName(activeAcc.ownId, name),
                     }),
                     // The self-heal's lock: a stage and a catch-up never share the socket.