@ardennguyen/zalo-agent-cli 2.5.0 → 2.5.3

package/src/core/daemon-channel.js

@@ -81,6 +81,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { spawn, spawnSync } from "node:child_process";
 import { randomBytes, timingSafeEqual } from "node:crypto";
+import { maskSecretArgs } from "../utils/secrets.js";
 
 const CHANNEL_FILE = "daemon-channel.json";
 const LOCK_FILE = "daemon.lock";
@@ -291,6 +292,10 @@ function readJsonBody(req, reply) {
  * @param {() => void} [args.onStop] - graceful shutdown callback invoked by
  *   `POST /stop` so `--stop` runs the same teardown as `SIGINT` (stamping
  *   `markConnected`, flushing delivered receipts, releasing `daemon.lock`).
+ * @param {(params: object, signal: AbortSignal) => Promise<object>} [args.onWait] -
+ *   long-poll callback invoked by `POST /wait` (`zalo-agent mcp wait`).
+ * @param {(params: object) => Promise<object>} [args.onMarkRead] -
+ *   read-cursor callback invoked by `POST /mark-read` (`zalo-agent mcp mark-read`).
  * @returns {Promise<{port: number, stop: () => void}>}
  */
 export function startDaemonChannel({
@@ -300,6 +305,8 @@ export function startDaemonChannel({
     runners = {},
     lock = createStageLock(),
     onStop = null,
+    onWait = null,
+    onMarkRead = null,
 }) {
     const token = randomBytes(24).toString("hex");
 
@@ -416,6 +423,40 @@ export function startDaemonChannel({
         });
     };
 
+    /** Long-poll the MCP daemon's live message buffer (`zalo-agent mcp wait`). */
+    const serveWait = async (body, res, reply) => {
+        if (!tokenMatches(body.token, token)) return reply(403, { error: "bad token" });
+        if (typeof onWait !== "function") {
+            return reply(503, {
+                error: "this daemon does not have an MCP message buffer (run `zalo-agent mcp start` instead of `listen`)",
+            });
+        }
+        const ac = new AbortController();
+        res.on("close", () => ac.abort());
+        try {
+            const result = await onWait(body, ac.signal);
+            if (!res.writableEnded) reply(200, { ok: true, ...result });
+        } catch (e) {
+            if (!res.writableEnded) reply(200, { ok: false, error: e?.message || String(e) });
+        }
+    };
+
+    /** Advance one consumer's read cursor in the MCP daemon's buffer (`zalo-agent mcp mark-read`). */
+    const serveMarkRead = async (body, reply) => {
+        if (!tokenMatches(body.token, token)) return reply(403, { error: "bad token" });
+        if (typeof onMarkRead !== "function") {
+            return reply(503, {
+                error: "this daemon does not have an MCP message buffer (run `zalo-agent mcp start` instead of `listen`)",
+            });
+        }
+        try {
+            const result = await onMarkRead(body);
+            reply(200, { ok: true, ...result });
+        } catch (e) {
+            reply(200, { ok: false, error: e?.message || String(e) });
+        }
+    };
+
     const server = http.createServer(async (req, res) => {
         const reply = (code, body) => {
             res.writeHead(code, { "content-type": "application/json" });
@@ -424,11 +465,21 @@ export function startDaemonChannel({
         if (req.method !== "POST") return reply(404, { error: "not found" });
 
         const stage = SYNC_ROUTE.exec(req.url || "")?.[1];
-        if (req.url !== "/send-attachments" && req.url !== "/stop" && !stage) return reply(404, { error: "not found" });
+        if (
+            req.url !== "/send-attachments" &&
+            req.url !== "/stop" &&
+            req.url !== "/wait" &&
+            req.url !== "/mark-read" &&
+            !stage
+        ) {
+            return reply(404, { error: "not found" });
+        }
 
         const body = await readJsonBody(req, reply);
         if (!body) return; // already answered, or the request went away
         if (req.url === "/stop") return serveStop(body, reply);
+        if (req.url === "/wait") return serveWait(body, res, reply);
+        if (req.url === "/mark-read") return serveMarkRead(body, reply);
         return stage ? serveStage(stage, body, res, reply) : serveAttachments(body, reply);
     });
 
@@ -781,6 +832,143 @@ export function stopViaDaemon(accountDir, { timeoutMs = 3000 } = {}) {
     });
 }
 
+/**
+ * Long-poll the running MCP daemon's live message buffer (`zalo-agent mcp wait`),
+ * mirroring the `zalo_wait_for_message` MCP tool over the loopback channel.
+ *
+ * @param {string} accountDir
+ * @param {{threadId?: string|null, since?: number, timeoutSec?: number, consumer?: string}} [opts]
+ * @returns {Promise<{ok: boolean, status?: "message"|"timeout"|number, message?: object|null, cursor?: number, error?: string}|null>}
+ *   null when no daemon channel is published
+ */
+export function waitViaDaemon(accountDir, { threadId = null, since = undefined, timeoutSec = 55, consumer } = {}) {
+    const chan = getDaemonChannel(accountDir);
+    if (!chan) return Promise.resolve(null);
+
+    const clampedSec = Math.max(1, Math.min(300, Number(timeoutSec) || 55));
+    const payload = JSON.stringify({
+        token: chan.token,
+        ...(threadId ? { threadId: String(threadId) } : {}),
+        ...(typeof since === "number" && Number.isFinite(since) ? { since } : {}),
+        timeoutSec: clampedSec,
+        ...(consumer ? { consumer: String(consumer) } : {}),
+    });
+
+    return new Promise((resolve) => {
+        const r = http.request(
+            {
+                host: "127.0.0.1",
+                port: chan.port,
+                path: "/wait",
+                method: "POST",
+                headers: { "content-type": "application/json", "content-length": Buffer.byteLength(payload) },
+                timeout: (clampedSec + 10) * 1000,
+                agent: false,
+            },
+            (res) => {
+                let raw = "";
+                res.setEncoding("utf8");
+                res.on("data", (c) => (raw += c));
+                res.on("end", () => {
+                    let body = {};
+                    try {
+                        body = JSON.parse(raw);
+                    } catch {
+                        /* non-JSON response */
+                    }
+                    if (res.statusCode === 200 && body.ok) {
+                        resolve({
+                            ok: true,
+                            status: body.status,
+                            message: body.message ?? null,
+                            cursor: body.cursor,
+                        });
+                    } else {
+                        resolve({
+                            ok: false,
+                            status: res.statusCode,
+                            error: body.error || `HTTP ${res.statusCode}`,
+                        });
+                    }
+                });
+            },
+        );
+        r.on("timeout", () => {
+            r.destroy();
+            resolve({ ok: false, error: "timeout waiting for daemon response" });
+        });
+        r.on("error", (e) => resolve({ ok: false, error: e?.message || String(e) }));
+        r.end(payload);
+    });
+}
+
+/**
+ * Advance one consumer's read cursor in the running MCP daemon's live message
+ * buffer (`zalo-agent mcp mark-read`), mirroring the `zalo_mark_read` MCP tool.
+ *
+ * @param {string} accountDir
+ * @param {{cursor: number, consumer?: string}} opts
+ * @returns {Promise<{ok: boolean, marked?: number, readCursor?: number, consumer?: string, status?: number, error?: string}|null>}
+ *   null when no daemon channel is published
+ */
+export function markReadViaDaemon(accountDir, { cursor, consumer } = {}) {
+    const chan = getDaemonChannel(accountDir);
+    if (!chan) return Promise.resolve(null);
+
+    const payload = JSON.stringify({
+        token: chan.token,
+        cursor: Number(cursor),
+        ...(consumer ? { consumer: String(consumer) } : {}),
+    });
+
+    return new Promise((resolve) => {
+        const r = http.request(
+            {
+                host: "127.0.0.1",
+                port: chan.port,
+                path: "/mark-read",
+                method: "POST",
+                headers: { "content-type": "application/json", "content-length": Buffer.byteLength(payload) },
+                timeout: 5000,
+                agent: false,
+            },
+            (res) => {
+                let raw = "";
+                res.setEncoding("utf8");
+                res.on("data", (c) => (raw += c));
+                res.on("end", () => {
+                    let body = {};
+                    try {
+                        body = JSON.parse(raw);
+                    } catch {
+                        /* non-JSON response */
+                    }
+                    if (res.statusCode === 200 && body.ok) {
+                        resolve({
+                            ok: true,
+                            marked: body.marked ?? 0,
+                            readCursor: body.readCursor ?? Number(cursor),
+                            consumer: body.consumer || consumer || "default",
+                        });
+                    } else {
+                        resolve({
+                            ok: false,
+                            status: res.statusCode,
+                            error: body.error || `HTTP ${res.statusCode}`,
+                        });
+                    }
+                });
+            },
+        );
+        r.on("timeout", () => {
+            r.destroy();
+            resolve({ ok: false, error: "timeout waiting for daemon response" });
+        });
+        r.on("error", (e) => resolve({ ok: false, error: e?.message || String(e) }));
+        r.end(payload);
+    });
+}
+
 /**
  * Stop the running daemon for an account directory, preferring `POST /stop` so
  * the daemon runs its own graceful shutdown handler (`markConnected`, receipt
@@ -985,7 +1173,8 @@ export async function spawnDaemonProcess({ accountDir, args = process.argv.slice
     const filteredArgs = args.filter((a) => a !== "-d" && a !== "--daemon");
 
     const logFd = fs.openSync(logPath, "a", 0o600);
-    const header = `\n--- [${new Date().toISOString()}] starting daemon: ${filteredArgs.join(" ")} ---\n`;
+    // Never the secrets: --auth, --client-secret and --webhook-secret values are masked.
+    const header = `\n--- [${new Date().toISOString()}] starting daemon: ${maskSecretArgs(filteredArgs).join(" ")} ---\n`;
     fs.writeSync(logFd, header);
     let startOffset = 0;
     try {

package/src/core/friend-requests.js

@@ -0,0 +1,142 @@
+/**
+ * Friend requests, as the CLI's `friend` commands and the MCP tool `zalo_friend`
+ * both read them.
+ *
+ * Zalo has no "incoming requests" list of its own. Zalo Web shows them inside
+ * the recommendations feed: an item whose `recommType` is 2
+ * (`FriendRecommendationsType.ReceivedFriendRequest`) is a request someone
+ * sent us, with their message in `recommInfo.message`; type 1 is an ordinary
+ * suggestion. `friend recommendations` already labels them `[request]`.
+ *
+ * Nothing here talks to Zalo or writes zalo.db: these are pure reshapers of
+ * what the zca-js calls return, plus the error wording for the writes.
+ */
+
+/** zca-js FriendRecommendationsType.ReceivedFriendRequest. */
+export const RECEIVED_FRIEND_REQUEST = 2;
+
+/**
+ * The numeric error code in a zca-js error message such as "... (225)".
+ *
+ * @param {unknown} msg
+ * @returns {number|null}
+ */
+export function extractErrorCode(msg) {
+    const match = String(msg).match(/\((-?\d+)\)/);
+    return match ? Number(match[1]) : null;
+}
+
+/**
+ * What a failed friend request means, in words that say what to do next.
+ *
+ * @param {number|string|null|undefined} code - Zalo's error code
+ * @param {string} userId
+ * @returns {string|undefined} undefined for a code with no specific wording
+ */
+export function describeFriendAddError(code, userId) {
+    const map = {
+        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.`,
+        // Names from Zalo Web's own error table (TOO_MANY_REQUESTS, FULL_FRIEND_REQUESTING, FULL_FRIEND).
+        221: "Zalo says too many requests were sent: wait a while before sending more.",
+        223: "Zalo says the pending friend-request list is full (223).",
+        224: "Zalo says the friend list is full (224).",
+    };
+    return map[String(code)];
+}
+
+/**
+ * An epoch timestamp as ISO text, whether Zalo gave seconds or milliseconds.
+ *
+ * Which unit a friend-request time carries has not been measured on a live
+ * account; anything below 1e11 cannot be a millisecond time of this century,
+ * so it is read as seconds.
+ *
+ * @param {unknown} ts
+ * @returns {string|null} null when it is not a usable time
+ */
+export function toIso(ts) {
+    const n = Number(ts);
+    if (!Number.isFinite(n) || n <= 0) return null;
+    return new Date(n < 1e11 ? n * 1000 : n).toISOString();
+}
+
+const name = (u) => u?.displayName || u?.zaloName || null;
+
+/**
+ * Requests we sent, from `getSentFriendRequest()` (an object keyed by userId).
+ *
+ * @param {Record<string, object>|null|undefined} res
+ * @returns {Array<{userId: string, displayName: string|null, message: string, requestedAt: string|null}>}
+ */
+export function sentRequestsFrom(res) {
+    return Object.entries(res && typeof res === "object" ? res : {}).map(([userId, r]) => ({
+        userId: String(r?.userId ?? userId),
+        displayName: name(r),
+        message: r?.fReqInfo?.message ?? "",
+        requestedAt: toIso(r?.fReqInfo?.time),
+    }));
+}
+
+/**
+ * Requests sent to us, from `getFriendRecommendations()`: the items of type
+ * "received friend request", newest first. Suggestions are left out.
+ *
+ * @param {{recommItems?: Array<{dataInfo?: object}>}|null|undefined} res
+ * @returns {Array<{userId: string, displayName: string|null, message: string, receivedAt: string|null, seen: boolean}>}
+ */
+export function receivedRequestsFrom(res) {
+    const items = Array.isArray(res?.recommItems) ? res.recommItems : [];
+    return items
+        .map((i) => i?.dataInfo)
+        .filter((d) => d && Number(d.recommType) === RECEIVED_FRIEND_REQUEST && d.userId)
+        .map((d) => ({
+            userId: String(d.userId),
+            displayName: name(d),
+            message: d.recommInfo?.message ?? "",
+            receivedAt: toIso(d.recommTime),
+            seen: Boolean(d.isSeenFriendReq),
+            _t: Number(d.recommTime) || 0,
+        }))
+        .sort((a, b) => b._t - a._t)
+        .map(({ _t, ...rest }) => rest);
+}
+
+/**
+ * The relationship with one user, from `getFriendRequestStatus()`.
+ * Zalo answers 0 or 1 for each flag; these are booleans.
+ *
+ * @param {{is_friend?: number, is_requested?: number, is_requesting?: number}|null|undefined} res
+ * @param {string} userId
+ * @returns {{userId: string, is_friend: boolean, is_requested: boolean, is_requesting: boolean}}
+ */
+export function friendStatusFrom(res, userId) {
+    return {
+        userId: String(userId),
+        is_friend: Boolean(res?.is_friend),
+        is_requested: Boolean(res?.is_requested),
+        is_requesting: Boolean(res?.is_requesting),
+    };
+}
+
+/**
+ * Friends, most recently active first, as the CLI lists them, capped.
+ *
+ * @param {Array<object>|null|undefined} list - `getAllFriends()`
+ * @param {number} limit
+ * @returns {{total: number, friends: Array<{userId: string, displayName: string|null, lastActionTime: number|null}>}}
+ */
+export function friendsFrom(list, limit) {
+    const all = Array.isArray(list) ? list : [];
+    const sorted = [...all].sort((a, b) => (b?.lastActionTime || 0) - (a?.lastActionTime || 0));
+    return {
+        total: all.length,
+        friends: sorted.slice(0, limit).map((f) => ({
+            userId: String(f.userId),
+            displayName: name(f),
+            lastActionTime: f.lastActionTime || null,
+        })),
+    };
+}

package/src/core/friend-search.js

@@ -0,0 +1,41 @@
+/**
+ * Friend search, as `friend search` reads it.
+ *
+ * A friend can be known by three names: the profile name Zalo shows
+ * (`displayName`), the name they gave themselves (`zaloName`), and the alias
+ * the account owner set for them. The alias lives in a separate list
+ * (`getAliasList`), so `getAllFriends` alone never contains it, and a search
+ * on the first two names cannot find a friend the owner saved as "Arden AI".
+ * `zalo_search_threads` already honors aliases through the thread-name cache;
+ * this gives the CLI the same reach.
+ *
+ * Pure: nothing here talks to Zalo.
+ */
+
+/**
+ * The friends whose display name, Zalo name or alias contains `query`
+ * (case-insensitive substring, as before).
+ *
+ * Each match is a copy of the friend with an `alias` field added when the
+ * owner has set one, so callers can show why it matched.
+ *
+ * @param {object[]} friends - `getAllFriends` entries
+ * @param {Map<string, string>} aliases - uid → the owner's alias for that friend
+ * @param {string} query
+ * @returns {object[]}
+ */
+export function searchFriends(friends, aliases, query) {
+    const q = String(query).toLowerCase();
+    const hit = (s) =>
+        String(s || "")
+            .toLowerCase()
+            .includes(q);
+    const matches = [];
+    for (const f of Array.isArray(friends) ? friends : []) {
+        const alias = aliases?.get(String(f.userId)) ?? "";
+        if (hit(f.displayName) || hit(f.zaloName) || hit(alias)) {
+            matches.push(alias ? { ...f, alias } : f);
+        }
+    }
+    return matches;
+}

package/src/core/group-admin.js

@@ -0,0 +1,116 @@
+/**
+ * Group administration, as the MCP tool `zalo_group` reads Zalo's answers.
+ *
+ * Pure reshapers: nothing here talks to Zalo or writes zalo.db. Members are
+ * listed by `src/core/group-members.js`; this file covers what that one does
+ * not: a group's own details, and the outcome of creating a group or changing
+ * its membership.
+ */
+import { toIso } from "./friend-requests.js";
+
+/**
+ * Zalo's error codes for leaving a group the account is not in. 167 ("Không thể rời nhóm") was measured on a live
+ * account by leaving a group a second time; 166 is the code zca-js documents on `leaveGroup` for the same situation
+ * and has not been seen.
+ */
+export const NOT_A_MEMBER_CODES = Object.freeze([166, 167]);
+
+/** Zalo's code ("Nhóm không có thành viên.") for removing someone who is not in the group, measured live. */
+export const REMOVE_NOT_IN_GROUP = 165;
+
+/** `zalo_group` actions that cannot be undone from the tool, and so ask for `confirm: true`. */
+export const CONFIRMED_ACTIONS = Object.freeze(["leave", "remove_member"]);
+
+/**
+ * Whether `zalo_group` asks for `confirm: true` before an irreversible action.
+ *
+ * The check is a parameter, never a prompt: an automatic or headless caller
+ * either sends `confirm: true` or switches the check off, and nothing waits for
+ * a person. `ZALO_MCP_GROUP_CONFIRM` (`0`/`false`/`off`/`no` to disable,
+ * `1`/`true`/`on`/`yes` to enable) wins over `groupConfirm` in mcp-config.json,
+ * so a backend deployment can turn it off without editing the file. On by
+ * default; anything unrecognized leaves it on.
+ *
+ * @param {object} [sources]
+ * @param {{groupConfirm?: unknown}|null} [sources.config] - the loaded MCP config
+ * @param {NodeJS.ProcessEnv} [sources.env] - environment, process.env by default
+ * @returns {boolean}
+ */
+export function groupConfirmRequired({ config, env = process.env } = {}) {
+    const fromEnv = String(env?.ZALO_MCP_GROUP_CONFIRM ?? "")
+        .trim()
+        .toLowerCase();
+    if (["0", "false", "off", "no"].includes(fromEnv)) return false;
+    if (["1", "true", "on", "yes"].includes(fromEnv)) return true;
+    return config?.groupConfirm !== false;
+}
+
+/**
+ * The details of one group out of `getGroupInfo`'s answer.
+ *
+ * Zalo answers `getGroupInfo([id])` with `gridInfoMap` keyed by group id; a
+ * group the account is not in is simply absent. The member list is left out
+ * on purpose (`zalo_get_group_members` owns it, with names); only its size is
+ * reported.
+ *
+ * @param {object|null|undefined} result - what `api.getGroupInfo([groupId])` returned
+ * @param {string} groupId
+ * @returns {object|null} null when Zalo's answer does not include the group
+ */
+export function groupInfoFrom(result, groupId) {
+    const g = result?.gridInfoMap?.[groupId];
+    if (!g) return null;
+    return {
+        groupId: String(g.groupId ?? groupId),
+        name: g.name ?? null,
+        description: g.desc || null,
+        type: g.type ?? null,
+        creatorId: g.creatorId ?? null,
+        adminIds: Array.isArray(g.adminIds) ? g.adminIds.map(String) : [],
+        totalMember: g.totalMember ?? null,
+        maxMember: g.maxMember ?? null,
+        createdAt: toIso(g.createdTime),
+        avatar: g.fullAvt || g.avt || null,
+        visibility: g.visibility ?? null,
+        pendingApproval: Array.isArray(g.pendingApprove?.uids) ? g.pendingApprove.uids.length : 0,
+        settings: g.setting ?? null,
+    };
+}
+
+/**
+ * The outcome of `createGroup`.
+ *
+ * zca-js spells the success list `sucessMembers`; both spellings are read so a
+ * fixed typo upstream does not empty it. Zalo's list includes the account that
+ * created the group (measured live: asking for one member returns two ids), so
+ * `added` keeps only the members that were asked for.
+ *
+ * @param {object|null|undefined} result
+ * @param {string[]} requested - the member ids that were asked for
+ * @returns {{groupId: string|null, added: string[], failed: string[]}}
+ */
+export function createdGroupFrom(result, requested) {
+    const failed = (result?.errorMembers ?? []).map(String);
+    const given = result?.sucessMembers ?? result?.successMembers;
+    const added = Array.isArray(given)
+        ? given.map(String).filter((id) => requested.includes(id))
+        : requested.filter((id) => !failed.includes(id));
+    return { groupId: result?.groupId ? String(result.groupId) : null, added, failed };
+}
+
+/**
+ * The outcome of `addUserToGroup` / `removeUserFromGroup`: which of the
+ * requested members Zalo refused, and why.
+ *
+ * `error_data` (add only) maps an error code to the ids it applies to.
+ *
+ * @param {object|null|undefined} result
+ * @param {string[]} requested - the member ids that were asked for
+ * @returns {{done: string[], failed: string[], errorData: Record<string, string[]>|null}}
+ */
+export function memberChangeFrom(result, requested) {
+    const failed = (result?.errorMembers ?? []).map(String);
+    const data = result?.error_data;
+    const errorData = data && typeof data === "object" && Object.keys(data).length > 0 ? data : null;
+    return { done: requested.filter((id) => !failed.includes(id)), failed, errorData };
+}

package/src/core/group-invite.js

@@ -0,0 +1,53 @@
+/**
+ * A pending group invitation's details (`group invite-info`).
+ *
+ * zca-js's `getGroupInviteBoxInfo` reads `data.groupInfo.topic.params` without
+ * checking that the group has a topic. Most groups have no pinned message, so
+ * for them Zalo's answer carries no `topic` and zca-js throws "Cannot read
+ * properties of undefined (reading 'params')" after Zalo had answered fine.
+ * This makes the same request (GET {group}/api/group/inv-box/inv-info) on
+ * zca-js's own session envelope, and unpacks the topic's JSON-in-JSON params
+ * only when there is a topic.
+ */
+import { customCall, getWithParams } from "./zca-custom.js";
+
+/**
+ * Parse a topic's `params`, which Zalo sends as a JSON string whose `extra`
+ * field is itself a JSON string. Anything that does not parse is left as it came.
+ *
+ * @param {object} topic
+ * @returns {object} the same topic, with `params` unpacked when it could be
+ */
+export function unpackTopic(topic) {
+    if (!topic || typeof topic.params !== "string") return topic;
+    try {
+        const params = JSON.parse(topic.params);
+        if (typeof params?.extra === "string") {
+            try {
+                params.extra = JSON.parse(params.extra);
+            } catch {
+                /* keep the string */
+            }
+        }
+        return { ...topic, params };
+    } catch {
+        return topic;
+    }
+}
+
+/**
+ * @param {object} api - logged-in zca-js api
+ * @param {{groupId: string, mpage?: number, mcount?: number}} payload
+ * @returns {Promise<object>} Zalo's `data`: groupInfo, inviterInfo, grCreatorInfo, expiredTs, type
+ */
+export async function getInviteBoxInfo(api, { groupId, mpage = 1, mcount = 10 }) {
+    return customCall(api, async (_ctx, utils) => {
+        const data = await getWithParams(utils, `${api.zpwServiceMap.group[0]}/api/group/inv-box/inv-info`, {
+            grId: groupId,
+            mcount,
+            mpage,
+        });
+        if (data?.groupInfo?.topic) data.groupInfo.topic = unpackTopic(data.groupInfo.topic);
+        return data;
+    });
+}