@ardennguyen/zalo-agent-cli 1.0.7 → 2.1.0

package/src/core/accounts.js

@@ -3,8 +3,10 @@
  * Maps each account to its own proxy (1:1) and tracks active account.
  */
 
-import { readFileSync, writeFileSync, existsSync, mkdirSync, chmodSync } from "fs";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, chmodSync, rmSync } from "fs";
+import { join } from "path";
 import { CONFIG_DIR, deleteCredentials } from "./credentials.js";
+import { checkLock } from "./lock.js";
 
 const ACCOUNTS_FILE = `${CONFIG_DIR}/accounts.json`;
 
@@ -53,32 +55,93 @@ export function setActive(ownId) {
     return found;
 }
 
-/** Register a new account or update existing. New account becomes active. */
+/**
+ * Register a new account or update existing — either way, the account just
+ * logged into always becomes the active one and every other entry is
+ * deactivated to match.
+ *
+ * (Previously, re-logging into an account that was *already* registered
+ * left `active` untouched on every entry — so logging back into account B,
+ * while account A was still flagged active from an earlier session, would
+ * silently leave A as the "active" account in accounts.json. Since each CLI
+ * invocation is its own process, the next command — logout included — would
+ * then auto-login into and operate on A, not the B you'd just authenticated
+ * as. `account switch` already did this correctly via an explicit
+ * `setActive()` call after login; this brings plain `login`/`account login`
+ * in line with it.)
+ */
 export function addAccount(ownId, name = "", proxy = null) {
     const accounts = load();
     const existing = accounts.find((a) => a.ownId === ownId);
+    for (const a of accounts) a.active = a.ownId === ownId;
     if (existing) {
         existing.name = name || existing.name || "";
         existing.proxy = proxy;
     } else {
-        for (const a of accounts) a.active = false;
         accounts.push({ ownId, name, proxy, active: true });
     }
     save(accounts);
 }
 
-/** Remove account from registry and delete its credentials. */
+/**
+ * Remove this account's entire per-account data directory —
+ * ~/.zalo-agent-cli/accounts/<ownId>/ — not just the chat cache: zalo.db,
+ * media/, the sync/ subfolder (RSA keys + any old sync dumps), and
+ * daemon.lock. Credentials themselves live elsewhere, under
+ * CREDENTIALS_DIR, and are handled separately (see removeAccount below).
+ *
+ * Refuses to touch the directory while a `listen` daemon actively holds
+ * its lock (deleting a directory a running process has files open in can
+ * fail outright on Windows, and is asking for trouble even where it
+ * "succeeds") — reports the PID instead so the caller can decide.
+ *
+ * Shared by `logout --purge` (scoped to whichever account is active) and
+ * `account remove <id>` (scoped to an explicit account), so both commands
+ * wipe local data the same way.
+ * @param {string} ownId
+ * @returns {{wiped: boolean, skippedLocked?: {pid: number}}}
+ */
+export function wipeAccountDir(ownId) {
+    const accountDir = join(CONFIG_DIR, "accounts", ownId);
+    if (!existsSync(accountDir)) return { wiped: false };
+
+    const lockStatus = checkLock(accountDir);
+    if (lockStatus.locked) {
+        return { wiped: false, skippedLocked: { pid: lockStatus.pid } };
+    }
+
+    rmSync(accountDir, { recursive: true, force: true });
+    return { wiped: true };
+}
+
+/**
+ * Fully remove an account from this machine: wipes its local data
+ * directory (see wipeAccountDir), deletes its credentials file, and drops
+ * it from the registry (activating the first remaining account, if any,
+ * when the removed one was active). Aborts entirely — leaving credentials
+ * and the registry entry untouched — if a `listen` daemon still holds the
+ * lock on that account's data directory, so credentials are never deleted
+ * out from under a running process.
+ * @param {string} ownId
+ * @returns {{removed: boolean, wiped?: boolean, skippedLocked?: {pid: number}}}
+ */
 export function removeAccount(ownId) {
     const accounts = load();
+    if (!accounts.some((a) => a.ownId === ownId)) return { removed: false };
+
+    const { wiped, skippedLocked } = wipeAccountDir(ownId);
+    if (skippedLocked) {
+        return { removed: false, skippedLocked };
+    }
+
     const filtered = accounts.filter((a) => a.ownId !== ownId);
-    if (filtered.length === accounts.length) return false;
     // If removed was active, activate first remaining
     if (filtered.length && !filtered.some((a) => a.active)) {
         filtered[0].active = true;
     }
     save(filtered);
     deleteCredentials(ownId);
-    return true;
+    return { removed: true, wiped };
 }
 
 /** Get account by ownId. */

package/src/core/cached-message.js

@@ -0,0 +1,200 @@
+/**
+ * Read what a cached `messages` row can tell a command that acts on it.
+ *
+ * Reacting, forwarding and pinning all name their target by more than its
+ * msgId: the client id only the sender ever minted, the sender's numeric uid,
+ * the exact text. None of that is in any CLI output; it lives in the row the
+ * listener or the mobile sync wrote. Read-only: nothing here writes zalo.db.
+ *
+ * `msg react`/`msg undo`/`msg delete` and the MCP tools `zalo_react`/
+ * `zalo_undo` share the lookups below, so a message one of them can act on is
+ * a message the other can too. Opening the db is the caller's: the CLI opens
+ * the active account's first, and `mcp start` opened it at start-up.
+ */
+
+import { getMessageById } from "./db.js";
+
+/**
+ * `raw_data` as an object, whatever shape its writer used.
+ *
+ * The live path stores the payload directly, some rows nest it under `data`,
+ * and an old writer stored a bare string -- which is "no metadata", not an error.
+ *
+ * @param {string|null|undefined} rawData
+ * @returns {object}
+ */
+export function parseRawData(rawData) {
+    try {
+        const parsed = JSON.parse(rawData || "{}");
+        if (!parsed || typeof parsed !== "object") return {};
+        return parsed.data && typeof parsed.data === "object" ? parsed.data : parsed;
+    } catch {
+        return {};
+    }
+}
+
+/**
+ * The row's cliMsgId, or null when it was never cached.
+ *
+ * @param {object} row - a `messages` row
+ * @returns {string|null}
+ */
+export function cachedCliMsgId(row) {
+    const id = parseRawData(row?.raw_data).cliMsgId;
+    return id === undefined || id === null || id === "" ? null : String(id);
+}
+
+/**
+ * The message's text as it was sent.
+ *
+ * The listener trims the `text` column; the payload keeps the original string,
+ * which is what Zalo Web forwards and pins.
+ *
+ * @param {object} row - a `messages` row
+ * @returns {string}
+ */
+export function cachedText(row) {
+    const content = parseRawData(row?.raw_data).content;
+    return typeof content === "string" && content.length > 0 ? content : row?.text || "";
+}
+
+/**
+ * Look one message up in the local SQLite cache by its global msgId.
+ *
+ * `deleteMessage`, `undo` and `addReaction` need the message's `cliMsgId`
+ * (and delete its `uidFrom`), neither of which can be derived from the msgId
+ * — cliMsgId is client-generated and only the sender ever saw it. Anything
+ * `listen`, `mcp start`, `sync` or a prior `msg history` wrote is here, so a
+ * message seen before does not need the ids passed by hand. Returns null when
+ * the message is not cached (a just-sent one will not be — `msg send` does not
+ * write to the db), is cached under a different conversation, or the db is
+ * not open.
+ *
+ * A direct lookup by msgId, checked against the thread. This used to scan the
+ * thread's newest 200 rows, so anything older was reported as uncached.
+ *
+ * Never throws.
+ *
+ * @param {string} threadId
+ * @param {string} msgId
+ * @returns {{cliMsgId: string, uidFrom: string|null}|null}
+ */
+export function cachedMessageById(threadId, msgId) {
+    try {
+        const row = getMessageById(msgId);
+        // msgIds are account-wide: a row from another conversation must not
+        // lend its ids to an action aimed at this one.
+        if (!row || (row.threadId && String(row.threadId) !== String(threadId))) return null;
+
+        const data = parseRawData(row.raw_data);
+        const cliMsgId = cachedCliMsgId(row);
+        const uidFrom = row.senderId ?? data.uidFrom;
+        return cliMsgId ? { cliMsgId, uidFrom: uidFrom ? String(uidFrom) : null } : null;
+    } catch {
+        return null; // no db open in this process
+    }
+}
+
+/**
+ * The cliMsgId an action on one message carries: the caller's own, else the
+ * cached row's, else null. Never a guess.
+ *
+ * @param {{msgId: string, threadId: string, cliMsgId?: string|number|null}} target
+ * @param {(threadId: string, msgId: string) => ({cliMsgId: string}|null)} lookup
+ * @returns {string|null}
+ */
+function targetCliMsgId({ msgId, threadId, cliMsgId }, lookup) {
+    if (cliMsgId) return String(cliMsgId);
+    return lookup(threadId, msgId)?.cliMsgId || null;
+}
+
+/**
+ * The cliMsgId a reaction must carry, or why there is none.
+ *
+ * Zalo keys a reaction on the target's cliMsgId as well as its msgId. Given
+ * the msgId in its place, it answers "Successful." and the reaction never
+ * appears for anyone, so a guess is worse than a refusal: the caller's id
+ * first, then the cache, then stop.
+ *
+ * @param {{msgId: string, threadId: string, cliMsgId?: string|number|null}} target
+ * @param {object} [opts]
+ * @param {(threadId: string, msgId: string) => ({cliMsgId: string}|null)} [opts.lookup] - the cache
+ *   lookup; the CLI passes one that opens the active account's db first
+ * @param {string} [opts.passItAs] - how the refusal tells the caller to supply the id themselves
+ * @returns {{cliMsgId: string}|{error: string}}
+ */
+export function reactionCliMsgId(target, { lookup = cachedMessageById, passItAs = "-c <cliMsgId>" } = {}) {
+    const cliMsgId = targetCliMsgId(target, lookup);
+    if (cliMsgId) return { cliMsgId };
+    const { msgId, threadId } = target;
+    return {
+        error:
+            `Message ${msgId} is not in the local cache for ${threadId}, so its cliMsgId is unknown — and a ` +
+            `reaction keyed on the msgId is accepted by Zalo but never shown, so none was sent. ` +
+            `\`listen\` caches messages as they arrive and \`sync\` restores older ones; ` +
+            `or pass the id yourself with ${passItAs}.`,
+    };
+}
+
+/**
+ * The cliMsgId a recall (`undo`) must carry, or why there is none.
+ *
+ * Zalo's recall names the message by msgId and cliMsgId both, and the
+ * cliMsgId is not derivable from the msgId. The same precedence as a
+ * reaction: the caller's id, then the cache, then a refusal.
+ *
+ * @param {{msgId: string, threadId: string, cliMsgId?: string|number|null}} target
+ * @param {object} [opts]
+ * @param {(threadId: string, msgId: string) => ({cliMsgId: string}|null)} [opts.lookup] - the cache lookup
+ * @param {string} [opts.passItAs] - how the refusal tells the caller to supply the id themselves
+ * @returns {{cliMsgId: string}|{error: string}}
+ */
+export function recallCliMsgId(
+    target,
+    { lookup = cachedMessageById, passItAs = "--cli-msg-id (from `listen --json`)" } = {},
+) {
+    const cliMsgId = targetCliMsgId(target, lookup);
+    if (cliMsgId) return { cliMsgId };
+    return {
+        error: `cliMsgId is required to recall a message and is not in the local cache. Pass ${passItAs}.`,
+    };
+}
+
+/** True for a numeric Zalo uid, as opposed to a sync row's noised sender id. */
+export function isNumericUid(id) {
+    return /^\d+$/.test(String(id ?? ""));
+}
+
+/**
+ * The sender's real numeric uid.
+ *
+ * A listener row already holds it (zca-js rewrites the own "0" to the uid). A
+ * row the mobile sync restored holds a noised id instead, which Zalo will not
+ * accept in a pin or a forward reference; it decodes through the same
+ * /api/gid/decrypt the sync path uses for conversation ids. gid.js is imported
+ * lazily so the common path pays nothing for it.
+ *
+ * @param {object} api - a logged-in zca-js API (only used for a noised id)
+ * @param {string|null} senderId - the row's senderId
+ * @param {string|null} ownId - this account's uid
+ * @returns {Promise<{uid: string}|{error: string}>}
+ */
+export async function resolveSenderUid(api, senderId, ownId) {
+    const id = String(senderId ?? "").trim();
+    if (id === "0" && ownId) return { uid: String(ownId) };
+    if (isNumericUid(id) && id !== "0") return { uid: id };
+    if (!id) return { error: "its sender is not in the cache" };
+
+    try {
+        const { resolveNonFriendDms } = await import("./sync-v2/gid.js");
+        const hit = (await resolveNonFriendDms(api, [id])).get(id);
+        if (hit?.id && isNumericUid(hit.id)) return { uid: String(hit.id) };
+    } catch {
+        /* reported below */
+    }
+    return {
+        error:
+            "it was restored by sync with a noised sender id that Zalo could not decode " +
+            "(/api/gid/decrypt), so its sender's uid is unknown",
+    };
+}

package/src/core/coverage.js

@@ -0,0 +1,90 @@
+/**
+ * How complete the local message cache is, in the terms the daemon already
+ * records it in: coverage gaps.
+ *
+ * A gap is a window in which this account's socket was down (`listen` and
+ * `mcp start` file one through src/core/listener-lifecycle.js), so whatever
+ * arrived in it may be missing from zalo.db. The self-heal closes what Zalo's
+ * offline queue still holds; what it cannot reach stays `pending` until a
+ * phone-backed `zalo-agent sync` covers it. This module reads that bookkeeping
+ * and says it in plain words, with the exact `sync --from` run that restores
+ * the gaps — the same advice `listen` prints, from src/core/sync-v2/gap-advice.js.
+ *
+ * Read-only: nothing here writes zalo.db or contacts Zalo.
+ */
+
+import { getPendingSyncGaps, countSyncGaps } from "./db.js";
+import { describeGap } from "./sync-v2/gap-advice.js";
+
+/**
+ * The coverage report for the account whose db is open.
+ *
+ * `command` restores every pending gap in one run: gaps are listed oldest
+ * first, and a restore resolves each gap lying wholly inside its window, so
+ * the window has to start on the oldest gap's (UTC) day — which is how
+ * `describeGap` dates it. A later date would run, succeed, and leave the
+ * older gaps pending.
+ *
+ * Throws "Database not initialized" when no db is open, as db.js does.
+ *
+ * @returns {{
+ *   pendingCount: number,
+ *   resolvedCount: number,
+ *   pending: Array<{id: number, reason: string, from: string, to: string, fromTs: number, toTs: number,
+ *     span: string, recordedAt: string|null, command: string}>,
+ *   command: string|null,
+ *   hint: string
+ * }}
+ */
+export function coverageReport() {
+    const rows = getPendingSyncGaps();
+    const { resolved } = countSyncGaps();
+
+    const pending = rows.map((g) => {
+        const advice = describeGap({
+            fromTs: g.fromTs,
+            toTs: g.toTs,
+            reason: g.reason || undefined,
+            pendingGaps: rows,
+        });
+        return {
+            id: g.id,
+            reason: advice.reason,
+            from: advice.from,
+            to: advice.to,
+            fromTs: Number(g.fromTs) || 0,
+            toTs: Number(g.toTs) || 0,
+            span: advice.span,
+            recordedAt: g.createdAt ? new Date(Number(g.createdAt)).toISOString() : null,
+            // Restores this gap alone (and any later one).
+            command: advice.command,
+        };
+    });
+
+    if (rows.length === 0) {
+        return {
+            pendingCount: 0,
+            resolvedCount: resolved,
+            pending,
+            command: null,
+            hint:
+                "No coverage gap is pending: no window in which this account's connection to Zalo was down is " +
+                "waiting to be restored.",
+        };
+    }
+
+    const oldest = describeGap({ ...rows[0], reason: rows[0].reason || undefined, pendingGaps: rows });
+    const command = oldest.allCommand ?? oldest.command;
+    return {
+        pendingCount: rows.length,
+        resolvedCount: resolved,
+        pending,
+        command,
+        hint:
+            `${rows.length} coverage gap(s) pending: windows in which this account's connection to Zalo was down, ` +
+            "so messages from them may be missing from the local cache. " +
+            `\`${command}\` restores them from the owner's phone — the phone asks for a tap on "ĐỒNG BỘ NGAY" — ` +
+            "and a run that completes resolves every gap that starts on or after that date. Nothing has to be " +
+            "stopped first: a running `mcp start` or `listen` performs the restore on its own socket.",
+    };
+}

package/src/core/current-user-names.js

@@ -0,0 +1,104 @@
+/**
+ * Read the account's complete alias snapshot. Do not reuse a previous snapshot:
+ * an absent entry means the owner removed that alias. Failed/partial reads do
+ * not pretend an old alias is current. Diagnostics never include identities.
+ * @param {object} api - current authenticated API
+ * @param {Function} [log] - diagnostic sink
+ * @returns {Promise<Map<string, string>>} UID -> account-owned alias
+ */
+export async function readUserAliases(api, log = () => {}) {
+    const aliases = new Map();
+    try {
+        if (typeof api?.getAliasList !== "function") return aliases;
+        for (let page = 1; page <= 1000; page++) {
+            const result = await api.getAliasList(100, page);
+            if (!Array.isArray(result?.items)) throw new Error("invalid alias page");
+            let added = 0;
+            for (const item of result.items) {
+                if (item.userId && typeof item.alias === "string" && item.alias.trim()) {
+                    const uid = String(item.userId);
+                    if (!aliases.has(uid)) added++;
+                    aliases.set(uid, item.alias);
+                }
+            }
+            if (result.items.length < 100) return aliases;
+            if (!added) throw new Error("alias pagination did not advance");
+        }
+        throw new Error("alias pagination limit reached");
+    } catch {
+        log("current aliases unavailable; falling back to profile names or UIDs");
+        return new Map();
+    }
+}
+
+/**
+ * Select a current label independently of any per-message historical name.
+ * @param {string} uid - canonical user ID
+ * @param {object} [profile] - fresh Zalo profile
+ * @param {Map<string, string>} [aliases] - account-owned aliases
+ * @returns {{name: string, source: string}} label and provenance
+ */
+export function currentUserName(uid, profile, aliases = new Map()) {
+    const id = String(uid || "");
+    const alias = aliases.get(id);
+    if (alias) return { name: alias, source: "alias" };
+    // displayName can itself be an alias. Only zaloName establishes the
+    // profile-name fallback independently of the owner's alias snapshot.
+    const name = profile?.zaloName;
+    return name ? { name, source: "zalo" } : { name: id, source: "uid" };
+}
+
+/**
+ * Resolve current names in batches, with no cross-request/account name cache.
+ * Failures degrade to UID, never to a historical senderName. Profiles can be
+ * supplied by a fresh friend-list response to avoid fetching them twice.
+ * @param {object} api - current authenticated API
+ * @param {string[]} uids - IDs to display
+ * @param {object} [options]
+ * @returns {Promise<Map<string, {name: string, source: string}>>} UID -> current label
+ */
+export async function resolveCurrentUserNames(api, uids, { aliases, profiles = new Map(), log = () => {} } = {}) {
+    const ids = [...new Set(uids.filter(Boolean).map(String))];
+    if (!ids.length) return new Map();
+    const aliasRequest = aliases ? Promise.resolve(aliases) : readUserAliases(api, log);
+    const fresh = new Map(profiles);
+    const missing = ids.filter((id) => /^[1-9][0-9]*$/.test(id) && !fresh.has(id));
+    for (let i = 0; i < missing.length; i += 100) {
+        try {
+            if (typeof api?.getUserInfo !== "function") break;
+            const result = await api.getUserInfo(missing.slice(i, i + 100));
+            for (const bag of [result?.changed_profiles, result?.unchanged_profiles]) {
+                for (const [uid, profile] of Object.entries(bag || {})) {
+                    if (profile) fresh.set(uid, profile);
+                }
+            }
+        } catch {
+            log("current profiles unavailable; falling back to aliases or UIDs");
+        }
+    }
+    const ownedAliases = await aliasRequest;
+    return new Map(ids.map((id) => [id, currentUserName(id, fresh.get(id), ownedAliases)]));
+}
+
+/**
+ * Decorate copied messages with current labels; senderName stays historical.
+ * DM titles use the peer's UID, including for an outgoing message from self.
+ * @param {object} api - current authenticated API
+ * @param {object[]} messages - cached or live rows
+ * @param {string[]} [dmThreadIds] - known DM peer IDs, never group IDs
+ * @returns {Promise<object[]>} detached display rows
+ */
+export async function withCurrentSenderNames(api, messages, dmThreadIds = []) {
+    const peers = new Set(dmThreadIds.map(String));
+    const names = await resolveCurrentUserNames(api, [...messages.map((m) => m.senderId), ...peers]);
+    return messages.map((m) => {
+        const sender = names.get(String(m.senderId)) || { name: null, source: "uid" };
+        const peer = peers.has(String(m.threadId)) && names.get(String(m.threadId));
+        return {
+            ...m,
+            senderDisplayName: sender.name,
+            senderDisplayNameSource: sender.source,
+            ...(peer && { threadName: peer.name }),
+        };
+    });
+}

package/src/core/daemon-account.js

@@ -0,0 +1,61 @@
+import { InvalidArgumentError } from "commander";
+import { getActive, getAccount } from "./accounts.js";
+import { loadCredentials } from "./credentials.js";
+import { loginWithCredentials, clearSession } from "./zalo-client.js";
+
+/** Validate a full numeric account ID without number coercion, names, or prefix matching. */
+export function parseAccountId(value) {
+    if (typeof value !== "string" || !/^[1-9][0-9]*$/.test(value)) {
+        throw new InvalidArgumentError("--account requires a full numeric account ID, not a name or partial ID");
+    }
+    return value;
+}
+
+/**
+ * Snapshot one daemon's account at startup without changing the shared registry.
+ * Even an implicit active-account selection stays pinned for this process.
+ * @param {string} [id] - exact registered account ID, never a display name
+ * @param {object} [deps] - offline-test collaborators
+ * @returns {Readonly<object>} frozen account identity and proxy configuration
+ */
+export function selectDaemonAccount(id, { active = getActive, lookup = getAccount } = {}) {
+    const selected = id === undefined ? active() : lookup(parseAccountId(id));
+    if (!selected) {
+        throw new Error(
+            id === undefined
+                ? "No active account. Please login first. You can also pass --account <ID>."
+                : "Account ID is not registered. Use `zalo-agent account list` to find the full ID.",
+        );
+    }
+    const ownId = parseAccountId(selected.ownId);
+    if (id !== undefined && ownId !== id) throw new Error("Account lookup returned a different ID; refusing to start");
+    return Object.freeze({ ...selected, ownId });
+}
+
+/**
+ * Authenticate only the daemon's pinned account, including after a disconnect.
+ * Never consult the active registry or retain a session for a different user.
+ * The caller must hold this account's daemon lock before invoking this function.
+ * @param {object} account - selectDaemonAccount() snapshot
+ * @param {object} [deps] - offline-test collaborators
+ * @returns {Promise<object>} authenticated API/ownId result
+ */
+export async function loginDaemonAccount(
+    account,
+    { read = loadCredentials, login = loginWithCredentials, reset = clearSession } = {},
+) {
+    const id = parseAccountId(account.ownId);
+    reset();
+    const credentials = read(id);
+    if (!credentials) throw new Error("No saved credentials for the pinned account. Log in to that account first.");
+    try {
+        const session = await login(credentials, account.proxy || null);
+        if (String(session?.ownId || "") !== id) {
+            throw new Error("Authenticated account does not match the pinned ID; refusing to attach its listener");
+        }
+        return session;
+    } catch (e) {
+        reset();
+        throw e;
+    }
+}