@ardennguyen/zalo-agent-cli 2.5.1 → 2.5.3

package/src/commands/mcp.js

@@ -20,8 +20,11 @@ import {
     getDaemonStatus,
     stopDaemon,
     spawnDaemonProcess,
+    waitViaDaemon,
+    markReadViaDaemon,
 } from "../core/daemon-channel.js";
 import { success, error, info, output } from "../utils/output.js";
+import { resolveWebhookSecret } from "../utils/secrets.js";
 import { createSyncRunners } from "../core/daemon-sync.js";
 import { createSyncJobs } from "../mcp/sync-jobs.js";
 import { createSocketTap } from "../core/socket-tap.js";
@@ -211,6 +214,10 @@ export function registerMCPCommands(program) {
             "-w, --webhook <url>",
             "POST each watched incoming message as JSON to this URL (or set webhook in mcp-config.json)",
         )
+        .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 (or set webhookSecret in mcp-config.json)",
+        )
         .option(
             "--no-delivered-receipts",
             "Do not acknowledge received messages as delivered (every Zalo client does; seen receipts are never sent)",
@@ -237,6 +244,14 @@ export function registerMCPCommands(program) {
                 // An empty --auth is a token that went missing -- an unset variable
                 // in a unit file -- not a request for no auth, and it used to start
                 // the server open, saying nothing. Refused before anything logs in.
+                // The same for a webhook secret: empty must not mean "unsigned".
+                if (opts.webhookSecret !== undefined) {
+                    try {
+                        resolveWebhookSecret({ flag: opts.webhookSecret });
+                    } catch (e) {
+                        failStart(e.message);
+                    }
+                }
                 if (opts.http && opts.auth !== undefined && !String(opts.auth).trim()) {
                     failStart(
                         "--auth was given an empty token. Refusing to start: that would serve this account's " +
@@ -557,8 +572,14 @@ export function registerMCPCommands(program) {
                 envForAccount("ZALO_WEBHOOK_URL", activeAcc.ownId) ||
                 config.webhook?.trim() ||
                 null;
-            const webhookSecret =
-                envForAccount("ZALO_WEBHOOK_SECRET", activeAcc.ownId) || config?.webhookSecret?.trim() || null;
+            const webhookSecret = resolveWebhookSecret({
+                flag: opts.webhookSecret,
+                env: envForAccount("ZALO_WEBHOOK_SECRET", activeAcc.ownId),
+                config: config?.webhookSecret,
+            });
+            if (webhookSecret && !webhookUrl) {
+                console.error("[mcp] A webhook secret is set but no webhook URL: nothing will be signed or sent.");
+            }
             if (webhookUrl) {
                 console.error(`[mcp] Webhook enabled: ${webhookUrl}${webhookSecret ? " (signed)" : ""}`);
             }
@@ -874,6 +895,70 @@ export function registerMCPCommands(program) {
                         // The self-heal's lock: a stage and a catch-up never share the socket.
                         lock: stageLock,
                         onStop: shutdown,
+                        onWait: async (params, signal) => {
+                            const cleanThreadId =
+                                typeof params?.threadId === "string" && params.threadId.trim()
+                                    ? params.threadId.trim()
+                                    : null;
+                            const consumer =
+                                typeof params?.consumer === "string" && params.consumer.trim()
+                                    ? params.consumer.trim()
+                                    : undefined;
+                            const clampedSec = Math.max(1, Math.min(300, Number(params?.timeoutSec) || 55));
+                            const explicitSince =
+                                typeof params?.since === "number" && Number.isFinite(params.since)
+                                    ? params.since
+                                    : undefined;
+                            const effectiveSince =
+                                explicitSince !== undefined
+                                    ? explicitSince
+                                    : consumer
+                                      ? buffer.readCursor(consumer)
+                                      : undefined;
+                            const msg = await buffer.waitForMessage({
+                                threadId: cleanThreadId,
+                                since: effectiveSince,
+                                timeoutMs: clampedSec * 1000,
+                                signal,
+                            });
+                            if (msg) {
+                                const tid = String(msg.threadId || "");
+                                const threadName = nameCache?.get(tid)?.name || null;
+                                return {
+                                    status: "message",
+                                    message: {
+                                        ...msg,
+                                        ...(threadName ? { threadName } : {}),
+                                    },
+                                    cursor: msg._cursor,
+                                };
+                            }
+                            return {
+                                status: "timeout",
+                                message: null,
+                                cursor: Math.max(
+                                    effectiveSince ?? 0,
+                                    Number(buffer._globalCursor) || 0,
+                                    buffer.readCursor(consumer),
+                                ),
+                            };
+                        },
+                        onMarkRead: async (params) => {
+                            const cursorNum = Number(params?.cursor);
+                            if (!Number.isInteger(cursorNum) || cursorNum < 0) {
+                                throw new Error("cursor must be a non-negative integer");
+                            }
+                            const consumer =
+                                typeof params?.consumer === "string" && params.consumer.trim()
+                                    ? params.consumer.trim()
+                                    : undefined;
+                            const marked = buffer.markRead(cursorNum, consumer);
+                            return {
+                                marked,
+                                readCursor: buffer.readCursor(consumer),
+                                consumer: consumer || "default",
+                            };
+                        },
                     });
                     console.error(`[mcp] Sync & upload channel ready on 127.0.0.1:${channel.port}`);
                 } catch (e) {
@@ -896,4 +981,149 @@ export function registerMCPCommands(program) {
             // Keep process alive (MCP server runs on stdio — process must not exit)
             await new Promise(() => {});
         });
+
+    mcp.command("wait [since]")
+        .description(
+            "Zero-CPU long-poll on the running MCP server's live message buffer (CLI equivalent of zalo_wait_for_message)",
+        )
+        .option("--account <id>", "Target a specific registered account ID (default: active account)", parseAccountId)
+        .option("-s, --since <cursor>", "Return immediately if a buffered message after this cursor already exists")
+        .option("-t, --thread <threadId>", "Only wake on messages from this thread ID")
+        .option("--timeout <seconds>", "Maximum seconds to wait before returning timeout (1-300, default: 55)", "55")
+        .option(
+            "-c, --consumer <name>",
+            "Consumer name whose read cursor is used when --since is omitted (matches zalo_mark_read)",
+        )
+        .action(async (sinceArg, opts) => {
+            const jsonMode = program.opts().json;
+            const rawSince = opts.since !== undefined ? opts.since : sinceArg;
+            let parsedSince;
+            if (rawSince !== undefined) {
+                const n = Number(rawSince);
+                if (!Number.isInteger(n) || n < 0 || !/^\d+$/.test(String(rawSince).trim())) {
+                    error(`Invalid cursor "${rawSince}": must be a non-negative integer.`);
+                    process.exit(1);
+                }
+                parsedSince = n;
+            }
+            const rawTimeout = Number(opts.timeout);
+            if (!Number.isInteger(rawTimeout) || rawTimeout < 1 || rawTimeout > 300) {
+                error(`Invalid --timeout "${opts.timeout}": must be an integer between 1 and 300 seconds.`);
+                process.exit(1);
+            }
+            const consumer = opts.consumer?.trim() || undefined;
+            if (consumer && !/^[A-Za-z0-9._:@-]{1,64}$/.test(consumer)) {
+                error(`Invalid --consumer "${consumer}": must be 1-64 characters matching [A-Za-z0-9._:@-].`);
+                process.exit(1);
+            }
+
+            let activeAcc;
+            try {
+                const requestedAccount =
+                    opts.account ?? program.opts().account ?? (process.env.ZALO_ACCOUNT?.trim() || undefined);
+                activeAcc = selectDaemonAccount(requestedAccount);
+            } catch (e) {
+                error(`Account selection failed: ${e.message}`);
+                process.exit(1);
+            }
+            const accountDir = getAccountDir(activeAcc.ownId);
+            const res = await waitViaDaemon(accountDir, {
+                threadId: opts.thread?.trim() || null,
+                since: parsedSince,
+                timeoutSec: rawTimeout,
+                consumer,
+            });
+            if (!res) {
+                error(
+                    `No running MCP server found for account ${activeAcc.ownId}. Start one with: zalo-agent mcp start`,
+                );
+                process.exit(1);
+            }
+            if (!res.ok) {
+                error(`Wait failed: ${res.error}`);
+                process.exit(1);
+            }
+            output(
+                {
+                    status: res.status,
+                    message: res.message,
+                    cursor: res.cursor,
+                },
+                jsonMode,
+                () => {
+                    if (res.status === "message" && res.message) {
+                        const m = res.message;
+                        const label = m.threadName ? `${m.threadName} (${m.threadId})` : m.threadId;
+                        success(
+                            `[cursor ${res.cursor}] ${m.senderName || m.senderId} in ${label}: ${m.text || `(${m.type})`}`,
+                        );
+                    } else {
+                        info(`Timeout after ${rawTimeout}s (cursor: ${res.cursor})`);
+                    }
+                },
+            );
+        });
+
+    mcp.command("mark-read <cursor>")
+        .description(
+            "Advance a consumer's read cursor in the running MCP server's live buffer (CLI equivalent of zalo_mark_read)",
+        )
+        .option("--account <id>", "Target a specific registered account ID (default: active account)", parseAccountId)
+        .option(
+            "-c, --consumer <name>",
+            'Consumer name whose read cursor to advance (default: "default"; deletes nothing for other consumers)',
+        )
+        .action(async (cursorArg, opts) => {
+            const jsonMode = program.opts().json;
+            const trimmedCursor = String(cursorArg ?? "").trim();
+            const parsedCursor = Number(trimmedCursor);
+            if (!Number.isInteger(parsedCursor) || parsedCursor < 0 || !/^\d+$/.test(trimmedCursor)) {
+                error(`Invalid cursor "${cursorArg}": must be a non-negative integer.`);
+                process.exit(1);
+            }
+            const consumer = opts.consumer?.trim() || undefined;
+            if (consumer && !/^[A-Za-z0-9._:@-]{1,64}$/.test(consumer)) {
+                error(`Invalid --consumer "${consumer}": must be 1-64 characters matching [A-Za-z0-9._:@-].`);
+                process.exit(1);
+            }
+
+            let activeAcc;
+            try {
+                const requestedAccount =
+                    opts.account ?? program.opts().account ?? (process.env.ZALO_ACCOUNT?.trim() || undefined);
+                activeAcc = selectDaemonAccount(requestedAccount);
+            } catch (e) {
+                error(`Account selection failed: ${e.message}`);
+                process.exit(1);
+            }
+            const accountDir = getAccountDir(activeAcc.ownId);
+            const res = await markReadViaDaemon(accountDir, {
+                cursor: parsedCursor,
+                consumer,
+            });
+            if (!res) {
+                error(
+                    `No running MCP server found for account ${activeAcc.ownId}. Start one with: zalo-agent mcp start`,
+                );
+                process.exit(1);
+            }
+            if (!res.ok) {
+                error(`Mark-read failed: ${res.error}`);
+                process.exit(1);
+            }
+            output(
+                {
+                    success: true,
+                    marked: res.marked,
+                    readCursor: res.readCursor,
+                    consumer: res.consumer,
+                },
+                jsonMode,
+                () => {
+                    success(
+                        `Marked ${res.marked} message(s) read for consumer "${res.consumer}" (readCursor: ${res.readCursor})`,
+                    );
+                },
+            );
+        });
 }

package/src/commands/msg.js

@@ -10,6 +10,7 @@ import { getApi, getOwnId } from "../core/zalo-client.js";
 import { withCurrentSenderNames } from "../core/current-user-names.js";
 import { success, error, info, output, warning } from "../utils/output.js";
 import { parseIntOption } from "../utils/parse-options.js";
+import { parseThreadTypeArg, parseReportReason } from "../utils/cli-args.js";
 import { getActive } from "../core/accounts.js";
 import { getAccountDir, getAccountDbPath } from "../core/credentials.js";
 import { initDb, getMessages, getMessageById, getDisplayName, getThreadType } from "../core/db.js";
@@ -1753,4 +1754,63 @@ export function registerMsgCommands(program) {
                 process.exit(1);
             }
         });
+
+    msg.command("typing <threadId>")
+        .description('Show the "typing…" indicator in a conversation')
+        .option("-t, --type <n>", "Thread type: 0=User, 1=Group", "0")
+        .action(async (threadId, opts) => {
+            try {
+                const result = await getApi().sendTypingEvent(threadId, parseThreadTypeArg(opts.type));
+                output(result, program.opts().json, () => success("Typing indicator sent"));
+            } catch (e) {
+                error(e.message);
+            }
+        });
+
+    msg.command("report <threadId>")
+        .description("Report a user (-t 0) or a group (-t 1) to Zalo")
+        .requiredOption("-r, --reason <reason>", "sensitive, annoy, fraud or other")
+        .option("-c, --content <text>", "What happened (required with --reason other, refused otherwise)")
+        .option("-t, --type <n>", "Thread type: 0=User, 1=Group", "0")
+        .action(async (threadId, opts) => {
+            try {
+                const options = parseReportReason(opts.reason, opts.content);
+                const result = await getApi().sendReport(options, threadId, parseThreadTypeArg(opts.type));
+                output(result, program.opts().json, () => success(`Report sent (id ${result?.reportId ?? "?"})`));
+            } catch (e) {
+                error(e.message);
+            }
+        });
+
+    msg.command("link-preview <url>")
+        .description("Fetch the preview Zalo would show for a link (title, description, thumbnail)")
+        .action(async (url) => {
+            try {
+                const result = await getApi().parseLink(url);
+                output(result, program.opts().json, () => {
+                    const d = result?.data ?? {};
+                    info(`Title: ${d.title || "-"}`);
+                    info(`Description: ${d.desc || "-"}`);
+                    info(`Source: ${d.src || d.href || "-"}`);
+                    if (d.thumb) info(`Thumbnail: ${d.thumb}`);
+                });
+            } catch (e) {
+                error(`Link preview failed: ${e.message}`);
+            }
+        });
+
+    msg.command("scan-url <url>")
+        .description("Ask Zalo whether a URL is safe to open")
+        .action(async (url) => {
+            try {
+                const result = await getApi().scanURL(url);
+                output(result, program.opts().json, () =>
+                    result?.isSafe
+                        ? success("Zalo reports this URL as safe")
+                        : warning("Zalo flags this URL as unsafe"),
+                );
+            } catch (e) {
+                error(`URL scan failed: ${e.message}`);
+            }
+        });
 }

package/src/commands/profile.js

@@ -7,6 +7,7 @@ import { getApi, getOwnId } from "../core/zalo-client.js";
 import { updateAccountName } from "../core/accounts.js";
 import { success, error, info, output } from "../utils/output.js";
 import { parseIntOption } from "../utils/parse-options.js";
+import { parseOnOff, parseLanguage } from "../utils/cli-args.js";
 
 /** Valid privacy setting keys and their human-readable labels + value descriptions. */
 const SETTING_MAP = {
@@ -276,4 +277,42 @@ export function registerProfileCommands(program) {
                 error(`Setting update failed: ${e.message}`);
             }
         });
+
+    profile
+        .command("active <on|off>")
+        .description("Turn your online (active) status on or off")
+        .action(async (state) => {
+            try {
+                const active = parseOnOff(state, "active");
+                const result = await getApi().updateActiveStatus(active);
+                output(result, program.opts().json, () => success(`Active status: ${active ? "on" : "off"}`));
+            } catch (e) {
+                error(e.message);
+            }
+        });
+
+    profile
+        .command("lang <language>")
+        .description("Set the account language: vi or en")
+        .action(async (language) => {
+            try {
+                const lang = parseLanguage(language);
+                const result = await getApi().updateLang(lang);
+                output(result, program.opts().json, () => success(`Language set to ${lang}`));
+            } catch (e) {
+                error(e.message);
+            }
+        });
+
+    profile
+        .command("lost-focus")
+        .description("Tell Zalo this client moved to the background (what Zalo Web sends when its tab loses focus)")
+        .action(async () => {
+            try {
+                const result = await getApi().lostFocus();
+                output(result, program.opts().json, () => success("Sent"));
+            } catch (e) {
+                error(`Lost focus failed: ${e.message}`);
+            }
+        });
 }

package/src/commands/sync.js

@@ -119,8 +119,7 @@ export function registerSyncCommands(program) {
             "Restore message history from your phone into the local cache (zalo.db). " +
                 "This IS the real phone-backed restore (transfer-sync-v2) by default: it sends one " +
                 "sync request your phone confirms, then decrypts and stores your history. " +
-                "--socket asks for the old server backfill instead (measured empty); --legacy tries an old " +
-                "endpoint Zalo Web no longer calls (it answers empty).",
+                "--socket asks for the old server backfill instead (measured empty).",
         )
         .option(
             "-t, --transfer",
@@ -147,11 +146,6 @@ export function registerSyncCommands(program) {
                 "The default is already everything your phone still holds, so this is for deliberately " +
                 "narrowing a run, not widening it",
         )
-        .option(
-            "-L, --legacy",
-            "Try the old pull_mobile_msg/get_crossdb phone-transfer endpoint instead, which Zalo Web no longer " +
-                "calls and which answers empty. One attempt only — it pings your mobile app",
-        )
         .option(
             "-M, --messages-only",
             "Restore messages but do NOT fetch their media. By default a transfer sync downloads the attachments it " +
@@ -195,10 +189,6 @@ export function registerSyncCommands(program) {
                 process.exit(1);
             }
 
-            if (opts.legacy) {
-                await runLegacySync(activeAcc, opts);
-                return;
-            }
             if (opts.socket) {
                 await runSocketBackfill(activeAcc, opts);
                 return;
@@ -1995,60 +1985,3 @@ async function runSocketBackfill(activeAcc, opts) {
 
     process.exit(exitCode);
 }
-
-/**
- * The retired path, kept behind --legacy so the behavior stays inspectable.
- *
- * `/api/message/pull_mobile_msg` and `/api/message/get_crossdb` are still
- * present in Zalo Web's own bundle but have ZERO call sites in it — the client
- * moved to a WebSocket protocol (cmd 590/591, "transfer-sync-v2"). The
- * endpoints answer with an empty payload rather than an error, which is why
- * this used to look like "the phone hasn't replied yet" and retry for two
- * minutes, putting a notification on the owner's phone each time.
- *
- * It runs exactly once now.
- *
- * @param {{ownId: string}} activeAcc
- * @param {{force?: boolean}} opts
- */
-async function runLegacySync(activeAcc, opts) {
-    warning(
-        "--legacy uses an endpoint Zalo Web no longer calls; it answers empty. This pings your mobile app " +
-            "and will most likely find nothing.",
-    );
-    try {
-        const syncManager = new SyncManager(getApi(), activeAcc.ownId);
-        const res = await syncManager.pollSync(0, 0, { force: !!opts.force });
-
-        switch (res.status) {
-            case "already-synced":
-                success("Already synced — no known missed messages since the last successful sync.");
-                info("Pass --force to check anyway.");
-                process.exit(0);
-                break;
-            case "saved":
-                success(`Synced ${res.saved}/${res.total} message(s) from mobile into the local cache.`);
-                process.exit(0);
-                break;
-            case "empty-or-unrecognized":
-                success("Sync round-trip completed — nothing new to save.");
-                process.exit(0);
-                break;
-            case "legacy-retired":
-                error("The legacy mobile-sync endpoint returned nothing, as it now always does.");
-                info("Run `zalo-agent sync-mobile` without --legacy to backfill over the WebSocket instead.");
-                process.exit(1);
-                break;
-            case "crossdb-error":
-                error(`Sync failed: ${res.error}`);
-                process.exit(1);
-                break;
-            default:
-                error(`Unrecognized sync result: ${res.status}`);
-                process.exit(1);
-        }
-    } catch (err) {
-        error(`Failed: ${err.message}`);
-        process.exit(1);
-    }
-}

package/src/core/bank-accounts.js

@@ -0,0 +1,52 @@
+/**
+ * The account's saved bank accounts (`bank` commands).
+ *
+ * Pure of side effects except the reads it is handed an api for.
+ */
+
+/** Page size used when scanning the saved-account list. */
+const SCAN_BATCH = 50;
+
+/**
+ * Find one saved bank account by its `account_id`.
+ *
+ * `deleteBankAccount` needs `isDefault`, which only the list knows, so removing
+ * an account starts by finding it. Scans page by page while Zalo says there are
+ * more, with a cap so a server that never stops saying so cannot loop us.
+ *
+ * @param {object} api - logged-in zca-js api
+ * @param {number} accountId
+ * @returns {Promise<object|null>} the saved account, or null when no page has it
+ */
+export async function findBankAccount(api, accountId) {
+    for (let page = 0; page < 100; page++) {
+        const res = await api.getListBankAccount(page, SCAN_BATCH);
+        const hit = (res?.myBanks ?? []).find((b) => Number(b.account_id) === Number(accountId));
+        if (hit) return hit;
+        if (!res?.hasMore) return null;
+    }
+    return null;
+}
+
+/**
+ * The banks whose name, short name, English name or search keywords contain `query`
+ * (case-insensitive substring); all of them for an empty query.
+ *
+ * @param {object[]} banks - `getListBank` entries
+ * @param {string} [query]
+ * @returns {object[]}
+ */
+export function filterBanks(banks, query) {
+    const q = String(query ?? "")
+        .trim()
+        .toLowerCase();
+    const list = Array.isArray(banks) ? banks : [];
+    if (!q) return list;
+    return list.filter((b) =>
+        [b.name, b.short_name, b.name_eng, b.search_key_word, String(b.bin)].some((s) =>
+            String(s ?? "")
+                .toLowerCase()
+                .includes(q),
+        ),
+    );
+}