@ardennguyen/zalo-agent-cli 2.5.8 → 3.0.0

package/src/core/profile-settings.js

@@ -0,0 +1,243 @@
+/**
+ * The account's privacy settings and profile fields, as `profile` (src/commands/profile.js) and the MCP tool
+ * `zalo_profile` read and write them: both call the functions here, so both answer the same JSON.
+ */
+
+/**
+ * The settings `profile set` changes, by the name the CLI and `zalo_profile` use: Zalo's key as `getSettings` reads
+ * it (`key`), the key `/api/setting/update` takes when it differs (`writeKey`; the Focused/Other switch is written
+ * as `archivedChatStatus` and read back as `archived_chat_status`), a label, and the values with their
+ * meaning.
+ */
+export const SETTING_MAP = {
+    "online-status": {
+        key: "show_online_status",
+        label: "Show online status",
+        values: { 0: "hidden", 1: "visible" },
+    },
+    "seen-status": {
+        key: "display_seen_status",
+        label: "Display seen status",
+        values: { 0: "hidden", 1: "visible" },
+    },
+    birthday: {
+        key: "view_birthday",
+        label: "Birthday visibility",
+        values: { 0: "hidden", 1: "full (day/month/year)", 2: "partial (day/month)" },
+    },
+    "receive-msg": {
+        key: "receive_message",
+        label: "Receive messages from",
+        values: { 1: "everyone", 2: "friends only" },
+    },
+    "accept-call": {
+        key: "accept_stranger_call",
+        label: "Accept calls from",
+        values: { 2: "friends only", 3: "everyone", 4: "friends + contacted" },
+    },
+    "add-by-phone": {
+        key: "add_friend_via_phone",
+        label: "Find by phone number",
+        values: { 0: "disabled", 1: "enabled" },
+    },
+    "add-by-qr": {
+        key: "add_friend_via_qr",
+        label: "Find by QR code",
+        values: { 0: "disabled", 1: "enabled" },
+    },
+    "add-by-group": {
+        key: "add_friend_via_group",
+        label: "Find via group",
+        values: { 0: "disabled", 1: "enabled" },
+    },
+    "add-by-card": {
+        key: "add_friend_via_contact",
+        label: "Find via a shared contact card",
+        values: { 0: "disabled", 1: "enabled" },
+    },
+    recommend: {
+        key: "display_on_recommend_friend",
+        label: "Show in friend recommendations",
+        values: { 0: "disabled", 1: "enabled" },
+    },
+    "focused-tabs": {
+        key: "archived_chat_status",
+        writeKey: "archivedChatStatus",
+        label: "Focused and Other tabs",
+        values: { 0: "off (one list)", 1: "on (Focused and Other)" },
+    },
+};
+
+/**
+ * Settings `profile settings` shows but `profile set` does not change: Zalo only reads the first two, and quick
+ * messages are switched with `quick-msg enable|disable` (written as `quickMessageStatus`).
+ */
+export const READ_ONLY_SETTINGS = {
+    "stranger-messages": {
+        key: "setting_show_stranger_msg_directly",
+        label: "Show strangers' messages directly",
+        values: { 0: "no (message requests)", 1: "yes" },
+    },
+    "two-factor": {
+        key: "setting_2FA_status",
+        label: "Two-factor authentication",
+        values: { 0: "off", 1: "on" },
+    },
+    "quick-messages": {
+        key: "quick_message_status",
+        label: "Quick messages",
+        values: { 0: "off", 1: "on" },
+        changeWith: "quick-msg enable|disable",
+    },
+};
+
+/** The key `/api/setting/update` takes for quick messages (`updateSettings({quickMessageStatus})`). */
+export const QUICK_MESSAGE_WRITE_KEY = "quickMessageStatus";
+
+/**
+ * A setting's value as a number: Zalo answers a bool for some settings, which is 1 or 0 here.
+ *
+ * @param {unknown} raw
+ * @returns {number|string|null}
+ */
+export function settingValue(raw) {
+    if (raw === true) return 1;
+    if (raw === false) return 0;
+    if (raw === undefined || raw === null || raw === "") return null;
+    const n = Number(raw);
+    return Number.isFinite(n) ? n : String(raw);
+}
+
+/** One row of {@link describeSettings}. */
+function settingRow(setting, meta, raw) {
+    const value = settingValue(raw?.[meta.key]);
+    return {
+        setting,
+        key: meta.key,
+        label: meta.label,
+        value,
+        meaning: value === null ? null : (meta.values[value] ?? null),
+        ...(meta.changeWith && { changeWith: meta.changeWith }),
+    };
+}
+
+/**
+ * `getSettings()` as `profile settings` and `zalo_profile` `settings` report it: the settings `profile set` changes,
+ * the read-only ones, and every other key Zalo sent, as it sent it, under `other`.
+ *
+ * @param {object|null|undefined} raw - `getSettings()`
+ * @returns {{settings: object[], readOnly: object[], other: object}}
+ */
+export function describeSettings(raw) {
+    const res = raw && typeof raw === "object" ? raw : {};
+    const settings = Object.entries(SETTING_MAP).map(([slug, meta]) => settingRow(slug, meta, res));
+    const readOnly = Object.entries(READ_ONLY_SETTINGS).map(([slug, meta]) => settingRow(slug, meta, res));
+    const mapped = new Set([...Object.values(SETTING_MAP), ...Object.values(READ_ONLY_SETTINGS)].map((m) => m.key));
+    const other = Object.fromEntries(Object.entries(res).filter(([k]) => !mapped.has(k)));
+    return { settings, readOnly, other };
+}
+
+/**
+ * The settings a change names (a `my_settings` control's data), each one this client knows with its name, value and
+ * meaning. A key is matched by the name Zalo reads it by or the one it writes it by.
+ *
+ * @param {object} changes - Zalo's keys and their new values
+ * @returns {Array<{setting: string, key: string, value: number|string|null, meaning: string|null}>}
+ */
+export function describeSettingChanges(changes) {
+    const out = [];
+    const all = [...Object.entries(SETTING_MAP), ...Object.entries(READ_ONLY_SETTINGS)];
+    for (const [key, raw] of Object.entries(changes || {})) {
+        const hit =
+            all.find(([, m]) => m.key === key || m.writeKey === key) ??
+            (key === QUICK_MESSAGE_WRITE_KEY ? ["quick-messages", READ_ONLY_SETTINGS["quick-messages"]] : null);
+        if (!hit) continue;
+        const value = settingValue(raw);
+        out.push({ setting: hit[0], key, value, meaning: value === null ? null : (hit[1].values[value] ?? null) });
+    }
+    return out;
+}
+
+/**
+ * Why a `profile set` value is refused, or undefined when it is valid.
+ *
+ * @param {string} setting - a {@link SETTING_MAP} name
+ * @param {unknown} value
+ * @returns {string|undefined}
+ */
+export function settingValueError(setting, value) {
+    const meta = SETTING_MAP[setting];
+    if (!meta) {
+        const readOnly = READ_ONLY_SETTINGS[setting];
+        if (readOnly) {
+            return readOnly.changeWith
+                ? `${setting} is changed with \`${readOnly.changeWith}\`, not \`profile set\`.`
+                : `${setting} is read-only here: Zalo does not change it either.`;
+        }
+        return `Unknown setting: "${setting}". Valid: ${Object.keys(SETTING_MAP).join(", ")}.`;
+    }
+    const text = String(value ?? "");
+    if (/^\d+$/.test(text) && Object.hasOwn(meta.values, String(Number(text)))) return undefined;
+    const valid = Object.entries(meta.values)
+        .map(([k, v]) => `${k}=${v}`)
+        .join(", ");
+    return `Invalid value for ${setting}. Valid: ${valid}.`;
+}
+
+/**
+ * Change one setting (`profile set`, `zalo_profile` `set`). Zalo answers with an empty body, so the reply is what
+ * was set.
+ *
+ * @param {object} api - logged-in session
+ * @param {string} setting - a {@link SETTING_MAP} name
+ * @param {number|string} value
+ * @returns {Promise<{success: true, setting: string, value: number, meaning: string}>}
+ * @throws {Error} for an unknown setting or value, before any request
+ */
+export async function updateSetting(api, setting, value) {
+    const why = settingValueError(setting, value);
+    if (why) throw new Error(why);
+    const meta = SETTING_MAP[setting];
+    const n = Number(value);
+    await api.updateSettings(meta.writeKey ?? meta.key, n);
+    return { success: true, setting, value: n, meaning: meta.values[n] };
+}
+
+/**
+ * Turn quick messages on or off for this account (`quick-msg enable|disable`, `zalo_quick_message`
+ * `enable`/`disable`), as Zalo's quick-message switch does: `/api/setting/update` with `quickMessageStatus`.
+ * Unverified live.
+ *
+ * @param {object} api - logged-in session
+ * @param {boolean} enabled
+ * @returns {Promise<{success: true, enabled: boolean}>}
+ */
+export async function setQuickMessageStatus(api, enabled) {
+    await api.updateSettings(QUICK_MESSAGE_WRITE_KEY, enabled ? 1 : 0);
+    return { success: true, enabled: Boolean(enabled) };
+}
+
+/**
+ * The `updateProfile` payload: Zalo takes the name, birthday and gender together, so the ones not being changed are
+ * filled in from the current profile.
+ *
+ * @param {object} current - `fetchAccountInfo().profile`
+ * @param {{name?: string, dob?: string, gender?: number|string}} change - dob as YYYY-MM-DD, gender 0 (male) or 1
+ * @returns {{profile: {name: string, dob: string, gender: number}}}
+ */
+export function profileUpdatePayload(current, change) {
+    const p = current || {};
+    // Convert sdob (DD/MM/YYYY) to YYYY-MM-DD format required by API
+    let currentDob = "2000-01-01";
+    if (p.sdob) {
+        const parts = p.sdob.split("/");
+        if (parts.length === 3) currentDob = `${parts[2]}-${parts[1]}-${parts[0]}`;
+    }
+    return {
+        profile: {
+            name: change.name || p.displayName || p.zaloName,
+            dob: change.dob || currentDob,
+            gender: change.gender !== undefined ? Number(change.gender) : (p.gender ?? 0),
+        },
+    };
+}

package/src/core/qr-login-flow.js

@@ -0,0 +1,237 @@
+/**
+ * One QR login, as `login` and `account login` both run it: the QR in the terminal and on the local page, who scanned
+ * it, a decline, and what happens when a code expires.
+ *
+ * An expired code is not replaced on its own while someone is there to ask for one, as in Zalo's own QR login: the page
+ * shows "QR code expired" with a button, and the terminal waits for Enter. Nobody asking within `ASK_WINDOW_MS` ends
+ * the login. With no one to ask (--json, or no terminal: an agent, a background `login --qr-url &`) the code is
+ * replaced at once, up to `MAX_CODES` codes, and then the login ends. Either way it never waits forever.
+ */
+
+import { QR_EVENT } from "../zalo/enums.js";
+import { loginWithQR } from "./zalo-client.js";
+import { displayQR, getQRPath } from "../utils/qr-display.js";
+import {
+    QR_LINK_TTL_MS,
+    getQrPage,
+    noteQrExpired,
+    noteQrOutcome,
+    noteQrScanned,
+    startQrServer,
+} from "../utils/qr-http-server.js";
+import { info, warning } from "../utils/output.js";
+import { resolvePublicUrl } from "./deploy-policy.js";
+import { loadMCPConfig } from "../mcp/mcp-config.js";
+
+/** How many codes a login shows when nobody can be asked for a new one (Zalo's codes last 100 s each). */
+export const MAX_CODES = 5;
+
+/** How long an expired code waits for someone to ask for a new one. */
+export const ASK_WINDOW_MS = 5 * 60_000;
+
+/** Why a login ended without a scan; the commands print it instead of the bare "aborted". */
+export class QrLoginTimedOut extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "QrLoginTimedOut";
+    }
+}
+
+/**
+ * The public address a login prints its QR link under: `--public-url`, else `ZALO_MCP_PUBLIC_URL`, else `publicUrl`
+ * in mcp-config.json (no account is known before the scan, so no per-account layer, and not the deprecated
+ * issuer names). Null keeps the localhost page.
+ * @param {string|undefined} flag
+ * @param {{env?: NodeJS.ProcessEnv, config?: object}} [o]
+ * @returns {{publicUrl: string|null, source: string, error: string|null}}
+ */
+export function resolveLoginPublicUrl(flag, { env = process.env, config } = {}) {
+    return resolvePublicUrl({ flag, env, config: config ?? loadMCPConfig(), aliases: false });
+}
+
+/**
+ * Wait for Enter on the terminal, once. Returns a cancel function; stdin is released either way, so it never holds
+ * the process open.
+ * @param {() => void} onEnter
+ * @param {NodeJS.ReadStream} [stdin]
+ * @returns {() => void}
+ */
+export function onceEnter(onEnter, stdin = process.stdin) {
+    const done = () => {
+        stdin.removeListener("data", listener);
+        stdin.pause();
+    };
+    const listener = () => {
+        done();
+        onEnter();
+    };
+    stdin.on("data", listener);
+    stdin.resume();
+    return done;
+}
+
+/**
+ * Run a QR login to the end.
+ * @param {object} p
+ * @param {string|null} [p.proxy]
+ * @param {boolean} [p.jsonMode] - print events as JSON lines
+ * @param {number} [p.qrPort] - the page's first port
+ * @param {boolean} [p.qrUrl] - offer the page to the LAN (--qr-url)
+ * @param {string|null} [p.publicUrl] - the validated public address (resolvePublicUrl): the page is also at the
+ *   one-time link `<publicUrl>/zalo/qr/<token>`, which is what is printed
+ * @param {import("../utils/qr-http-server.js").QrPage} [p.qrPage] - the process's QR page; when an HTTP server
+ *   already serves it (`mcp start --http`, `mounted`), the login uses that server's one-time link and starts none
+ * @param {boolean} [p.interactive] - someone at a terminal can ask for a new code (default: a TTY and not --json)
+ * @param {Function} [p.login] - `loginWithQR`, replaceable in tests
+ * @param {Function} [p.waitForEnter] - `onceEnter`, replaceable in tests
+ * @param {number} [p.maxCodes]
+ * @param {number} [p.askWindowMs]
+ * @returns {Promise<{ownId: string, finish: (outcome: "done"|"failed", message?: string) => Promise<void>}>} `finish`
+ *   tells the page how the login ended and closes it once the page has seen it; on a failure the error is thrown with
+ *   a `finish` property instead.
+ */
+export async function runQrLogin({
+    proxy = null,
+    jsonMode = false,
+    qrPort = 18927,
+    qrUrl = false,
+    publicUrl = null,
+    qrPage = getQrPage(),
+    interactive = !jsonMode && Boolean(process.stdin.isTTY),
+    login = loginWithQR,
+    waitForEnter = onceEnter,
+    maxCodes = MAX_CODES,
+    askWindowMs = ASK_WINDOW_MS,
+} = {}) {
+    let server = null;
+    let codes = 0;
+    let timedOut = null;
+    let pending = null; // the open "ask for a new code" offer: { cancel }
+
+    const closeOffer = () => {
+        if (!pending) return;
+        pending.cancel();
+        pending = null;
+    };
+    const finish = async (outcome, message = "") => {
+        closeOffer();
+        noteQrOutcome(outcome, message);
+        if (server) await server.finish();
+        server = null;
+    };
+
+    const openPage = () => {
+        if (!qrPage.mounted) {
+            return startQrServer(getQRPath(), qrPort, [qrPort, 8080, 3000, 9000], qrUrl, { publicUrl, qrPage });
+        }
+        // Served by the MCP HTTP server already: its one-time link, built from publicUrl or its local address.
+        const link = qrPage.open({ qrImagePath: getQRPath() });
+        if (jsonMode) {
+            console.log(JSON.stringify({ event: "qr_page", url: link.url, imageUrl: link.imageUrl }));
+        } else {
+            info(`QR available at: ${link.url} (this login only)`);
+        }
+        // Its finish ends the link once the page has read how the login ended.
+        return link;
+    };
+
+    const onEvent = (event) => {
+        switch (event.type) {
+            case QR_EVENT.QR_GENERATED:
+                closeOffer();
+                codes++;
+                displayQR(event);
+                // The QR is a login token, so the page binds loopback unless --qr-url asks for the LAN.
+                if (!server) server = openPage();
+                // The one-time link lives as long as a code is on screen.
+                else qrPage.extend(QR_LINK_TTL_MS);
+                break;
+
+            case QR_EVENT.QR_SCANNED: {
+                // What Zalo shows the moment the phone scans: the account's name.
+                const name = event.data?.display_name || "unknown";
+                noteQrScanned(event.data?.display_name || "");
+                if (jsonMode) {
+                    console.log(JSON.stringify({ event: "qr_scanned", name, avatar: event.data?.avatar || null }));
+                } else {
+                    info(`Scanned by ${name} — confirm on your phone to finish logging in.`);
+                    if (event.data?.avatar) info(`Avatar: ${event.data.avatar}`);
+                }
+                break;
+            }
+
+            case QR_EVENT.QR_DECLINED:
+                // The login rejects right after this; this is the immediate heads-up.
+                if (jsonMode) console.log(JSON.stringify({ event: "qr_declined" }));
+                else warning("Login declined on phone.");
+                break;
+
+            case QR_EVENT.QR_EXPIRED:
+                onExpired(event.actions);
+                break;
+
+            default:
+                break;
+        }
+    };
+
+    // A callback login never replaces an expired code by itself: without an answer here it would wait forever.
+    const onExpired = (actions) => {
+        const retry = () => actions?.retry?.();
+        const giveUp = (message) => {
+            timedOut = message;
+            actions?.abort?.();
+        };
+        if (jsonMode)
+            console.log(JSON.stringify({ event: "qr_expired", codes, maxCodes: interactive ? null : maxCodes }));
+
+        if (!interactive) {
+            if (codes >= maxCodes) {
+                giveUp(`the QR code expired ${codes} times without a scan. Run the login again.`);
+                return;
+            }
+            if (!jsonMode) info(`QR expired — generating a new one (${codes + 1} of ${maxCodes})...`);
+            retry();
+            return;
+        }
+
+        // As in Zalo's own QR login: wait for someone to ask, from the page or the terminal, and only for so long.
+        let used = false;
+        const once = () => {
+            if (used) return;
+            used = true;
+            closeOffer();
+            retry();
+        };
+        const stopEnter = waitForEnter(once);
+        const timer = setTimeout(() => {
+            if (used) return;
+            used = true;
+            closeOffer();
+            noteQrExpired(null);
+            giveUp(
+                `the QR code expired and no new one was asked for within ${Math.round(askWindowMs / 60_000)} minutes. Run the login again.`,
+            );
+        }, askWindowMs);
+        pending = {
+            cancel: () => {
+                clearTimeout(timer);
+                stopEnter();
+            },
+        };
+        noteQrExpired(once);
+        qrPage.extend(askWindowMs);
+        info('QR expired. Press Enter for a new one, or click "Get a new code" on the QR page.');
+    };
+
+    try {
+        const { ownId } = await login(proxy, onEvent);
+        closeOffer();
+        return { ownId, finish };
+    } catch (e) {
+        closeOffer();
+        const err = timedOut ? new QrLoginTimedOut(`Login timed out: ${timedOut}`) : e;
+        err.finish = finish;
+        throw err;
+    }
+}