@ardennguyen/zalo-agent-cli 2.5.9 → 3.0.0

package/src/cli.test.js

@@ -1,127 +0,0 @@
-/**
- * CLI interface tests — verify command parsing, help output, and basic behavior
- * without requiring a Zalo session.
- */
-
-import { describe, it } from "node:test";
-import assert from "node:assert/strict";
-import { execFileSync } from "child_process";
-import { resolve } from "path";
-
-const CLI = resolve(import.meta.dirname, "index.js");
-
-/**
- * Per-spawn timeout. Every assertion here boots a real `node` process, so a
- * cold start competing with other work on the machine can blow a tight limit
- * and fail a *different* `--help` test on each run — a load symptom that reads
- * exactly like a CLI regression. Generous by default; override with
- * ZALO_TEST_CLI_TIMEOUT_MS when you are genuinely chasing a hang.
- */
-const SPAWN_TIMEOUT_MS = Number(process.env.ZALO_TEST_CLI_TIMEOUT_MS) || 30_000;
-
-function run(...args) {
-    try {
-        return execFileSync("node", [CLI, ...args], {
-            encoding: "utf-8",
-            timeout: SPAWN_TIMEOUT_MS,
-            env: {
-                ...process.env,
-                HOME: "/tmp/zalo-agent-cli-test-home",
-                USERPROFILE: "/tmp/zalo-agent-cli-test-home",
-                LOCALAPPDATA: "/tmp/zalo-agent-cli-test-home",
-                APPDATA: "/tmp/zalo-agent-cli-test-home",
-            },
-        });
-    } catch (e) {
-        // Say which it is, so the next reader does not go hunting for a
-        // regression in a command that is merely slow to start.
-        if (e.code === "ETIMEDOUT") {
-            throw new Error(
-                `\`${args.join(" ")}\` did not finish within ${SPAWN_TIMEOUT_MS}ms. That is usually ` +
-                    `machine load, not a CLI regression — re-run this file on its own, or raise ` +
-                    `ZALO_TEST_CLI_TIMEOUT_MS.`,
-                { cause: e },
-            );
-        }
-        throw e;
-    }
-}
-
-describe("CLI interface", () => {
-    it("--version outputs 1.0.0", () => {
-        const out = run("--version");
-        assert.match(out.trim(), /^\d+\.\d+\.\d+$/);
-    });
-
-    it("--help lists all command groups", () => {
-        const out = run("--help");
-        assert.match(out, /login/);
-        assert.match(out, /msg/);
-        assert.match(out, /friend/);
-        assert.match(out, /group/);
-        assert.match(out, /conv/);
-        assert.match(out, /account/);
-    });
-
-    it("msg --help lists all subcommands", () => {
-        const out = run("msg", "--help");
-        assert.match(out, /send /);
-        assert.match(out, /send-image/);
-        assert.match(out, /send-file/);
-        assert.match(out, /send-card/);
-        assert.match(out, /send-bank/);
-        assert.match(out, /send-qr-transfer/);
-        assert.match(out, /sticker/);
-        assert.match(out, /react/);
-        assert.match(out, /delete/);
-        assert.match(out, /forward/);
-    });
-
-    it("friend --help lists subcommands", () => {
-        const out = run("friend", "--help");
-        assert.match(out, /list/);
-        assert.match(out, /find/);
-        assert.match(out, /info/);
-        assert.match(out, /block/);
-    });
-
-    it("group --help lists subcommands", () => {
-        const out = run("group", "--help");
-        assert.match(out, /create/);
-        assert.match(out, /members/);
-        assert.match(out, /rename/);
-    });
-
-    it("conv --help lists subcommands", () => {
-        const out = run("conv", "--help");
-        assert.match(out, /mute/);
-        assert.match(out, /pinned/);
-        assert.match(out, /archived/);
-    });
-
-    it("account --help lists subcommands", () => {
-        const out = run("account", "--help");
-        assert.match(out, /login/);
-        assert.match(out, /switch/);
-        assert.match(out, /export/);
-        assert.match(out, /remove/);
-    });
-
-    it("login --help shows all flags", () => {
-        const out = run("login", "--help");
-        assert.match(out, /--proxy/);
-        assert.match(out, /--credentials/);
-        assert.match(out, /--qr-url/);
-        assert.match(out, /--qr-port/);
-    });
-
-    it("logout --help shows --purge", () => {
-        const out = run("logout", "--help");
-        assert.match(out, /--purge/);
-    });
-
-    it("account list on clean state shows no accounts", () => {
-        const out = run("account", "list");
-        assert.match(out, /No accounts/);
-    });
-});

package/src/core/forward.js

@@ -1,112 +0,0 @@
-/**
- * Forward a text message the way Zalo Web does: as a forward, not a copy.
- *
- * A forward is the source text plus a `reference` that names the source
- * message, and a `decorLog` that repeats it. Without them the copy arrives as
- * plain text with no "forwarded" badge, which is what `msg forward` sent until
- * this module existed.
- *
- * The reference id is derived, not looked up. The web builds it as
- *
- *     id = md5(cliMsgId + senderUid + conversationKey)
- *
- * with senderUid the source sender's numeric uid (its own uid when the web
- * holds the sender as "0") and conversationKey the web's conversation id: "g"
- * plus the group id for a group, the peer's uid for a 1-1, the send2me id for
- * My Documents. Verified offline against the 2026-09-29 capture: the captured
- * group-source forward's id is exactly that md5
- * (agent/work/zalo-web-capture-2026-09-29/comparison-vs-zca-js.md §5.16).
- *
- * `ts` is the source message's send time -- `sendDttm` in the web's message
- * model, which for any message the web did not send itself is the server
- * timestamp (`sendDttm: e.ts`). `logSrcType` classifies the source
- * conversation, and the decorLog's `st` IS that logSrcType (the web maps
- * st -> logSrcType), so it is 2 for a group source and 1 for a 1-1.
- * zca-js's forwardMessage hardcodes `st: 1`, which is right only for a 1-1
- * source; that is why the request is sent from here instead.
- *
- * Only a first-level forward is built (fwLvl 1, rootMsgRef = the source
- * itself). Forwarding something that was itself a forward makes the web carry
- * the original root and raise fwLvl; the local cache does not keep a message's
- * own reference, so that cannot be reproduced.
- */
-import { createHash } from "node:crypto";
-import { customCall, postWithParams } from "./zca-custom.js";
-
-/** Zalo Web's source-conversation kinds for a forward (its `logSrcType` enum). */
-export const LOG_SRC_TYPE = Object.freeze({ UNKNOWN: 0, ONE_ONE: 1, GROUP: 2, COMMUNITY: 3, OA: 4, MY_CLOUD: 5 });
-
-/**
- * The reference and decorLog of a first-level forward.
- *
- * @param {object} source
- * @param {string} source.cliMsgId - the source message's client id
- * @param {string} source.senderUid - the source sender's numeric uid
- * @param {string} source.threadId - the source conversation's id
- * @param {boolean} source.isGroup - whether that conversation is a group
- * @param {number} source.ts - the source message's send time (server timestamp)
- * @param {number} [source.logSrcType] - overrides the group/1-1 default (My Documents is 5)
- * @returns {{reference: object, decorLog: object}}
- */
-export function buildForwardReference({ cliMsgId, senderUid, threadId, isGroup, ts, logSrcType }) {
-    const kind = logSrcType ?? (isGroup ? LOG_SRC_TYPE.GROUP : LOG_SRC_TYPE.ONE_ONE);
-    const conversationKey = isGroup ? `g${threadId}` : String(threadId);
-    const id = createHash("md5").update(`${cliMsgId}${senderUid}${conversationKey}`).digest("hex");
-    // Key order is the web's, and it matters: every level is serialized to a
-    // JSON string, so the order is part of the bytes Zalo receives.
-    const self = { id, ts, logSrcType: kind };
-    return {
-        reference: { ...self, fwLvl: 1, rootMsgRef: self },
-        decorLog: { fw: { pmsg: { st: kind, ts, id }, rmsg: { st: kind, ts, id }, fwLvl: 1 } },
-    };
-}
-
-/**
- * Send one mforward request with `reference` and `decorLog` exactly as given.
- *
- * Same endpoint and parameter layout as zca-js's forwardMessage (and as the
- * capture): `grids[]` for groups, `toIds[]` plus `imei` for 1-1s, the message
- * info as nested JSON strings. The clientId that went on the wire is stamped
- * onto the result as `cliMsgId`, as patches/zca-js+2.2.0.patch does for
- * forwardMessage, so the caller can report the {msgId, cliMsgId} pair that
- * `msg undo` needs.
- *
- * @param {object} api - a logged-in zca-js API
- * @param {{message: string, reference: object, decorLog: object, ttl?: number}} payload
- * @param {string[]} threadIds - the targets, all of one kind
- * @param {number} type - 0 for users, 1 for groups
- * @returns {Promise<object>} Zalo's `{success, failed}` plus `cliMsgId`
- */
-export async function sendForward(api, { message, reference, decorLog, ttl = 0 }, threadIds, type) {
-    const isGroup = Number(type) === 1;
-    const clientId = String(Date.now());
-    const msgInfo = JSON.stringify({
-        message,
-        reference: JSON.stringify({ type: 3, data: JSON.stringify(reference) }),
-    });
-    const decor = JSON.stringify(decorLog);
-    return customCall(api, async (ctx, utils) => {
-        const params = isGroup
-            ? {
-                  grids: threadIds.map((grid) => ({ clientId, grid: String(grid), ttl })),
-                  ttl,
-                  msgType: "1",
-                  totalIds: threadIds.length,
-                  msgInfo,
-                  decorLog: decor,
-              }
-            : {
-                  toIds: threadIds.map((toUid) => ({ clientId, toUid: String(toUid), ttl })),
-                  imei: ctx.imei,
-                  ttl,
-                  msgType: "1",
-                  totalIds: threadIds.length,
-                  msgInfo,
-                  decorLog: decor,
-              };
-        const base = `${api.zpwServiceMap.file[0]}/api/${isGroup ? "group" : "message"}/mforward`;
-        const result = await postWithParams(utils, base, params);
-        if (result && typeof result === "object") result.cliMsgId = clientId;
-        return result;
-    });
-}

package/src/core/group-history.js

@@ -1,248 +0,0 @@
-/**
- * Group chat history from Zalo's cloud-message store.
- *
- * zca-js's getGroupChatHistory asks `{group}/api/group/history`, which Zalo
- * answers with HTTP 404. Zalo Web reads a group's history from a different
- * service -- the cloud-message ("cm") store:
- *
- *   GET {group_cloud_message}/api/cm/getrecentv2?nretry=0     (cmd 12506)
- *   GET {group_cloud_message}/api/cm/getoldv2?nretry=0        (cmd 12507)
- *       params = AES({groupId, globalMsgId, count, msgIds, imei, src})
- *
- * Sources, all under agent/work/zalo-web-capture-2026-09-29/: the web
- * client's own `getCM` (bundles/1.*.js @11028626), the captures in
- * live/group.A1-A4.json, comparison-vs-zca-js.md §3e and §5.30, FINDINGS §13.
- *
- * What the evidence establishes, and what it does not:
- *
- * - The newest page is `getrecentv2` with globalMsgId 2^63 -- Zalo Web's
- *   MessageConstants.MAX_MSG_ID -- and `src: 1`, as sent when a group is
- *   opened (FINDINGS §13).
- * - Older pages follow Zalo Web's own client loop (`getCloudMessage`,
- *   bundles/1.*.js @6637459): the next globalMsgId is the response's
- *   `lastMsgId`, the request goes to `getoldv2` only when the response says
- *   `isOld`, and it carries `src: 3` (LOADMORE) -- the shape of every captured
- *   scroll-up request. No captured response ever carried messages, `hasMore`
- *   or `isOld`, so paging is implemented to that specification and is NOT yet
- *   verified against the live server.
- * - The response's `data` is a JSON string. Zalo Web quotes bare numbers in
- *   `uidFrom`, `uidTo`, `uid` and `ownerId` before parsing it (`preParse`),
- *   because uids run past 2^53. So does this.
- * - Recall (`chat.undo`) and delete (`chat.delete`) events and rows without
- *   content are dropped, and rows are de-duplicated on cliMsgId + sender, as
- *   Zalo Web's `checkDupMessageFromCloud` does.
- *
- * `group_cloud_message` is declared in zca-js's own LoginInfo type
- * (zpw_service_map_v3, dist/context.d.ts). A session whose map lacks it gets a
- * clear error rather than a request to "undefined".
- *
- * Read-only: this module fetches and writes nothing. `msg history` caches what
- * it returns through storeHistoryMessage (./live-store.js). The listener, sync
- * and msg history's fetch write Zalo-reported rows; history writes
- * insert-if-absent; msg send writes nothing (AGENTS.md §13).
- */
-import { createRequire } from "node:module";
-import { dirname, join } from "node:path";
-import { GroupMessage } from "zca-js";
-
-const require = createRequire(import.meta.url);
-
-/** Zalo Web's MessageConstants.MAX_MSG_ID, `(BigInt(2) ** BigInt(63)).toString()`: start from the newest. */
-export const NEWEST_MSG_ID = "9223372036854775808";
-
-/**
- * Messages asked for per request. Zalo Web sends its server-configured
- * `cloud.countP.WEB`, which was 50 in every capture; nothing else has been seen.
- */
-export const CM_PAGE_SIZE = 50;
-
-/** Zalo Web's cloud-load `src`: OVERFLOW (opening a conversation) and LOADMORE (scrolling up). */
-const SRC_OPEN = 1;
-const SRC_LOAD_MORE = 3;
-
-/** Pause between pages. Zalo rate-limits hard (see ./sync-v2/board.js). */
-const PAGE_DELAY_MS = 150;
-
-/**
- * `"uidFrom": 1234…` (or `\"uidFrom\": 1234…` inside an escaped string) with a
- * bare integer. Group 1 is the escaping; the key must close with the same.
- */
-const UID_SCALAR = /(\\*)"(uidFrom|uidTo|uid|ownerId)\1"(\s*):(\s*)(-?\d+)(?![\d.eE])/g;
-/** The same keys holding an array of bare integers. */
-const UID_ARRAY = /(\\*)"(uidFrom|uidTo|uid|ownerId)\1"(\s*):(\s*)\[([^[\]{}"]*)\]/g;
-
-let _utils = null;
-/** zca-js internals (apiFactory, makeURL, request, resolve), located as ./sync-v2/gid.js does. */
-function zcaUtils() {
-    if (_utils) return _utils;
-    _utils = require(join(dirname(require.resolve("zca-js")), "utils.cjs"));
-    return _utils;
-}
-
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-
-/**
- * Quote bare integers under `uidFrom`, `uidTo`, `uid` and `ownerId` in a JSON
- * text, so JSON.parse keeps every digit of a uid past 2^53. The same job as
- * Zalo Web's `preParse`, which runs over every cloud-message response,
- * including those keys inside escaped JSON held in a string value.
- *
- * @param {string} json
- * @returns {string}
- */
-export function quoteUids(json) {
-    return json
-        .replace(UID_SCALAR, (_m, esc, key, s1, s2, num) => `${esc}"${key}${esc}"${s1}:${s2}${esc}"${num}${esc}"`)
-        .replace(
-            UID_ARRAY,
-            (_m, esc, key, s1, s2, items) =>
-                `${esc}"${key}${esc}"${s1}:${s2}[${items.replace(/-?\d+/g, (n) => `${esc}"${n}${esc}"`)}]`,
-        );
-}
-
-/** A msgId as a BigInt, or null when it is not a plain decimal id. */
-function msgIdOf(v) {
-    const s = String(v ?? "");
-    return /^\d+$/.test(s) ? BigInt(s) : null;
-}
-
-/** Newest first: by msgId, which is what the server pages on, then by timestamp. */
-function newestFirst(a, b) {
-    const x = msgIdOf(a.data.msgId);
-    const y = msgIdOf(b.data.msgId);
-    if (x !== null && y !== null && x !== y) return x > y ? -1 : 1;
-    return Number(b.data.ts || 0) - Number(a.data.ts || 0);
-}
-
-/** Zalo Web's `_validCloudMsg`: a real message, not a recall or delete event, with content. */
-function isMessage(data) {
-    return (
-        Boolean(data) &&
-        typeof data === "object" &&
-        data.msgType !== "chat.undo" &&
-        data.msgType !== "chat.delete" &&
-        Boolean(data.content)
-    );
-}
-
-/** getrecentv2's `data`, parsed. It arrives as a JSON string. */
-function parsePage(raw) {
-    if (raw === null || raw === undefined || raw === "") return {};
-    const page = typeof raw === "string" ? JSON.parse(quoteUids(raw)) : raw;
-    return page && typeof page === "object" ? page : {};
-}
-
-/** One request to the cloud-message store. */
-async function fetchPage(api, host, { groupId, globalMsgId, src, old }) {
-    const url = `${host}/api/cm/${old ? "getoldv2" : "getrecentv2"}`;
-    const call = zcaUtils().apiFactory()((_api, ctx, utils) => async () => {
-        // Key order as Zalo Web builds it.
-        const params = { groupId, globalMsgId, count: CM_PAGE_SIZE, msgIds: [], imei: ctx.imei, src };
-        const enc = utils.encodeAES(JSON.stringify(params));
-        if (!enc) throw new Error("failed to encrypt group history params");
-        const resp = await utils.request(utils.makeURL(url, { nretry: 0, params: enc }), { method: "GET" });
-        return utils.resolve(resp);
-    })(api.getContext(), api);
-    return parsePage(await call());
-}
-
-/**
- * Fetch a group's newest messages from Zalo's cloud-message store.
- *
- * A drop-in for zca-js's `getGroupChatHistory(groupId, count)`, whose endpoint
- * is retired: it resolves to `{groupMsgs, more}` with each message a zca-js
- * `GroupMessage` (`.data`, `.isSelf`, `.threadId`), so a caller that read the
- * old call's `groupMsgs` and `more` reads this unchanged.
- *
- * @param {object} api - a logged-in zca-js API
- * @param {string} groupId - numeric group id; a leading "g" is stripped, as Zalo Web does
- * @param {number} [count=50] - how many of the newest messages to return, a whole number >= 1
- * @param {object} [opts]
- * @param {number} [opts.delayMs=150] - pause between pages
- * @returns {Promise<{groupMsgs: Array<object>, more: 0|1, pages: number, filtered: boolean}>}
- *   `groupMsgs` newest first; `more` is 1 when older messages can be fetched beyond those
- *   returned; `pages` is the number of requests made; `filtered` is true when Zalo withheld
- *   older messages (the page said `isFiltered`) — they exist but this store will not serve
- *   them, so `more` is 0
- * @throws {Error} when `count` is not a whole number >= 1, the session has no
- *   group_cloud_message host, a request fails, or the store reports an error and returns nothing
- */
-export async function getGroupHistory(api, groupId, count = CM_PAGE_SIZE, { delayMs = PAGE_DELAY_MS } = {}) {
-    if (!Number.isInteger(count) || count < 1) {
-        throw new Error(`count must be a whole number of at least 1, got ${count}`);
-    }
-    const host = api?.zpwServiceMap?.group_cloud_message?.[0];
-    if (!host) {
-        throw new Error(
-            'Zalo did not include the "group_cloud_message" service in this session\'s service map ' +
-                "(zpw_service_map_v3), so group history is unavailable for this login.",
-        );
-    }
-
-    const gid = String(groupId).replace(/^g/, "");
-    const ownId = String(api.getContext().uid ?? "");
-    // Enough for `count`, plus slack for pages thinned out by dropped events.
-    const maxPages = Math.ceil(count / CM_PAGE_SIZE) + 2;
-
-    const kept = [];
-    const seen = new Set();
-    let cursor = NEWEST_MSG_ID;
-    let old = false;
-    let src = SRC_OPEN;
-    let hasMore = false;
-    let filtered = false;
-    let pages = 0;
-
-    while (pages < maxPages) {
-        if (pages > 0 && delayMs) await sleep(delayMs);
-        const page = await fetchPage(api, host, { groupId: gid, globalMsgId: cursor, src, old });
-        pages++;
-
-        const rows = Array.isArray(page.groupMsgs) ? page.groupMsgs : [];
-        if (page.error && !rows.length) {
-            if (!kept.length) throw new Error(`Zalo's group message store answered error ${page.error}`);
-            hasMore = true; // an older page failed; do not claim the history ends here
-            break;
-        }
-
-        for (const data of rows) {
-            if (!isMessage(data)) continue;
-            // Keyed before GroupMessage rewrites a self uidFrom of "0".
-            const byId = `m:${data.msgId}`;
-            const byClient = `c:${data.cliMsgId}_${data.uidFrom}`;
-            if (seen.has(byId) || seen.has(byClient)) continue;
-            seen.add(byId);
-            seen.add(byClient);
-
-            const msg = new GroupMessage(ownId, data);
-            // Zalo marks our own messages with uidFrom "0"; the store may use the uid itself.
-            if (!msg.isSelf && ownId && String(msg.data.uidFrom) === ownId) msg.isSelf = true;
-            kept.push(msg);
-        }
-
-        hasMore = Number(page.hasMore) > 0;
-        // Zalo withholds what it filters, and the filter is a point in time
-        // (measured live 2026-09-30: only messages since this device's login
-        // came back; everything older read `isFiltered: 1`, 0 rows, `hasMore:
-        // 1`, page after page). Every older page is past the same point, so
-        // walking on only fetched empty pages and then claimed "more".
-        if (Number(page.isFiltered) > 0) {
-            filtered = true;
-            hasMore = false;
-            break;
-        }
-        if (kept.length >= count || !hasMore) break;
-
-        // Zalo Web's loop: the next page starts at the lastMsgId the server
-        // returned. A cursor that does not move older would ask for the same
-        // page forever, so it ends the walk.
-        const next = msgIdOf(page.lastMsgId);
-        if (next === null || next === 0n || next >= BigInt(cursor)) break;
-        cursor = next.toString();
-        old = Number(page.isOld) > 0;
-        src = SRC_LOAD_MORE;
-    }
-
-    kept.sort(newestFirst);
-    return { groupMsgs: kept.slice(0, count), more: kept.length > count || hasMore ? 1 : 0, pages, filtered };
-}

package/src/core/group-invite.js

@@ -1,53 +0,0 @@
-/**
- * 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;
-    });
-}