@ardennguyen/zalo-agent-cli 2.5.8 → 3.0.0

package/src/core/sync-action.js

@@ -0,0 +1,180 @@
+/**
+ * Zalo's `sync_action` media reports (D31, research row ZP-13), built and kept unwired.
+ *
+ * What they are: when the person opens a media message, the client tells the `sync_action` host that this media was
+ * taken on this device, so the account's other devices can pull the list (`pullSyncResource`) and fetch the same files.
+ * Each entry is `{fromUid, destId, isGroup, cmi}`: the sender (the account itself for its own messages), the
+ * conversation without the group prefix, 1 for a group, and the client message id as a number. Entries are
+ * de-duplicated on `fromUid_destId_cmi`, sent at most 50 per request through `POST /api/sync_action/media` (`{syncList:
+ * JSON, imei}`, cmd 16213; this client's `sync-action-media` write), with a trailing throttle
+ * (`syncActionMedia.submitActionThrottle`), and put back for a retry when the request fails. It runs only when the
+ * server's `syncActionMedia.enable` is on and the person has automatic downloads turned on. Automatic downloads
+ * themselves report nothing: only an opened media message does.
+ *
+ * Why nothing calls this yet: the endpoint answers an empty list (verified), but what a non-empty list makes the
+ * account's other devices do has never been captured, and this client's only "opened" media path (`zalo_view_media`)
+ * downloads a whole conversation's pending media rather than one item. Until the request and its effect are seen
+ * live, this module is the tested half: the entry, the gate and the batching.
+ */
+import { callWrite } from "../zalo/writes.js";
+
+/** Entries per request. */
+export const BATCH_MAX = 50;
+/** The throttle used when the server names none (the paid account's setting, 2026-10-28). */
+export const DEFAULT_THROTTLE_MS = 5000;
+
+/**
+ * The server's switch for these reports, from the login answer's `settings.features.syncActionMedia`.
+ *
+ * @param {object} api
+ * @returns {{enable: boolean, throttleMs: number}} `enable` is false when the setting is missing
+ */
+export function syncActionSettings(api) {
+    let s = null;
+    try {
+        s = api?.getContext?.()?.settings?.features?.syncActionMedia ?? null;
+    } catch {
+        s = null;
+    }
+    const throttle = Number(s?.submitActionThrottle);
+    return {
+        enable: Boolean(s) && Number(s.enable) === 1,
+        throttleMs: Number.isFinite(throttle) && throttle > 0 ? throttle : DEFAULT_THROTTLE_MS,
+    };
+}
+
+/**
+ * One report entry.
+ *
+ * @param {{threadId: string, isGroup: boolean, senderId?: string|null, cliMsgId: string|number}} msg
+ * @param {string} ownId - stands in for the sender of the account's own messages
+ * @returns {{fromUid: string, destId: string, isGroup: 0|1, cmi: number}|null} null without a usable client message id
+ *   or conversation
+ */
+export function syncActionItem(msg, ownId) {
+    const cmi = Number.parseInt(String(msg?.cliMsgId ?? ""), 10);
+    if (!Number.isFinite(cmi) || cmi <= 0) return null;
+    let destId = String(msg?.threadId ?? "");
+    if (!destId) return null;
+    if (msg.isGroup && destId.startsWith("g")) destId = destId.slice(1);
+    const sender = msg.senderId === undefined || msg.senderId === null ? "0" : String(msg.senderId);
+    return {
+        fromUid: sender !== "0" && sender !== "" ? sender : String(ownId),
+        destId,
+        isGroup: msg.isGroup ? 1 : 0,
+        cmi,
+    };
+}
+
+const keyOf = (e) => `${e.fromUid}_${e.destId}_${e.cmi}`;
+
+/**
+ * A batching reporter: entries are queued (de-duplicated), and sent at most {@link BATCH_MAX} per request once
+ * `throttleMs` has passed since the last entry was added. A failed request puts its entries back and is tried again
+ * after `retryMs`, once at a time.
+ *
+ * @param {object} args
+ * @param {(items: object[]) => Promise<unknown>} args.submit - sends one batch
+ * @param {number} [args.throttleMs]
+ * @param {number} [args.retryMs=30000]
+ * @param {() => boolean} [args.enabled] - checked before every request; false keeps the queue and sends nothing
+ * @param {(line: string) => void} [args.log]
+ * @param {typeof setTimeout} [args.setTimer]
+ * @param {typeof clearTimeout} [args.clearTimer]
+ * @returns {{add: (items: object[]) => number, flush: () => Promise<number>, pending: () => number, stop: () => void}}
+ *   `add` returns how many entries were new; `flush` sends everything queued now and returns how many were sent
+ */
+export function createSyncActionReporter({
+    submit,
+    throttleMs = DEFAULT_THROTTLE_MS,
+    retryMs = 30000,
+    enabled = () => true,
+    log = () => {},
+    setTimer = setTimeout,
+    clearTimer = clearTimeout,
+}) {
+    const queue = [];
+    const keys = new Set();
+    let timer = null;
+    let sending = null;
+
+    const schedule = (ms) => {
+        if (timer) clearTimer(timer);
+        timer = setTimer(() => {
+            timer = null;
+            void flush();
+        }, ms);
+        timer?.unref?.();
+    };
+
+    async function sendOne() {
+        const batch = queue.splice(0, BATCH_MAX);
+        for (const e of batch) keys.delete(keyOf(e));
+        try {
+            await submit(batch);
+            return batch.length;
+        } catch (e) {
+            add(batch, { quiet: true });
+            try {
+                log(`sync_action: a report of ${batch.length} item(s) failed (${e?.message || e}); retrying later`);
+            } catch {
+                /* a broken logger changes nothing */
+            }
+            schedule(retryMs);
+            return -1;
+        }
+    }
+
+    async function flush() {
+        if (sending) return sending;
+        sending = (async () => {
+            let sent = 0;
+            try {
+                if (!enabled()) return 0;
+                while (queue.length) {
+                    const n = await sendOne();
+                    if (n < 0) break;
+                    sent += n;
+                }
+            } finally {
+                sending = null;
+            }
+            return sent;
+        })();
+        return sending;
+    }
+
+    function add(items, { quiet = false } = {}) {
+        let fresh = 0;
+        for (const e of Array.isArray(items) ? items : []) {
+            if (!e) continue;
+            const k = keyOf(e);
+            if (keys.has(k)) continue;
+            keys.add(k);
+            queue.push(e);
+            fresh++;
+        }
+        if (fresh && !quiet) schedule(throttleMs);
+        return fresh;
+    }
+
+    return {
+        add: (items) => add(items),
+        flush,
+        pending: () => queue.length,
+        stop() {
+            if (timer) clearTimer(timer);
+            timer = null;
+        },
+    };
+}
+
+/**
+ * The `submit` that sends a batch through this client's `sync-action-media` write.
+ *
+ * @param {object} api
+ * @returns {(items: object[]) => Promise<unknown>}
+ */
+export function submitThrough(api) {
+    return (items) => callWrite(api, "sync-action-media", { actions: items });
+}

package/src/core/sync-v2/auto-sync.js

@@ -0,0 +1,356 @@
+/**
+ * Auto sync after a QR login (plan item Y8).
+ *
+ * When the person ticks "auto sync" on the phone while confirming a QR login, the phone puts a
+ * `transfer_sync2 / transfer_after_login` control in the account's control queue, `{temp_key, imei, pc}`. A browser
+ * client takes the latest one of those that is meant for it (`pc` 0) and has a key, and sends the key as `tempKey` in
+ * its conversation request: the phone then does not ask for a tap (measured live, 2026-10-26: the request went out 15
+ * seconds after the login and the phone showed no prompt; a key 765 seconds old got the prompt as usual).
+ *
+ * `zalo-agent login` always looks for that control after a QR login and says whether the box was ticked. The tick IS
+ * the person's consent, given on the phone at the login itself, so a ticked offer is restored at once with its key
+ * (`--no-sync` declines; `--sync` is the older spelling of the default). This is the only restore that
+ * starts without a `sync` someone typed, and it never runs in a daemon (AGENTS.md section 13). The key is short-lived,
+ * so it is read from the control queue the moment the socket is up.
+ */
+import { createSocketTap } from "../../zalo/listener/socket-tap.js";
+import { nextReqId } from "../../zalo/req-id.js";
+import { controlQueuesFrom } from "../../zalo/queues/offline-queue.js";
+import { SyncV2 } from "./index.js";
+
+/** The control that carries the key. */
+export const TRANSFER_AFTER_LOGIN = "transfer_after_login";
+
+/** A key older than this is not used: the phone stops honoring it long before 765 s. */
+export const AUTO_SYNC_MAX_AGE_MS = 120_000;
+
+/** `pc` of a control meant for a browser client (the desktop app is 1). */
+const FOR_WEB = 0;
+
+/**
+ * What the controls say about the phone's "sync messages to this device" box at the QR confirmation.
+ *
+ * - `ticked`: a `transfer_after_login` for a browser client (`pc` 0) with a key, recent enough to use (`tempKey`,
+ *   `ageMs`).
+ * - `late`: the same, but older than `maxAgeMs` (the phone asks for a tap again by then).
+ * - `other-client`: only offers for the desktop app (`pc` not 0), which this client must not use.
+ * - `none`: no offer at all: the box was not ticked.
+ *
+ * @param {object[]} controls - `controls[]` entries of 601/603 frames
+ * @param {object} [opts]
+ * @param {number} [opts.now]
+ * @param {number} [opts.maxAgeMs]
+ * @returns {{status: "ticked"|"late"|"other-client"|"none", tempKey?: string, ageMs?: number}}
+ */
+export function classifyLoginOffer(controls, { now = Date.now(), maxAgeMs = AUTO_SYNC_MAX_AGE_MS } = {}) {
+    let best = null;
+    let otherClient = false;
+    for (const c of Array.isArray(controls) ? controls : []) {
+        const content = c?.content;
+        if (content?.act !== TRANSFER_AFTER_LOGIN) continue;
+        let data;
+        try {
+            data = typeof content.data === "string" ? JSON.parse(content.data) : content.data;
+        } catch {
+            continue;
+        }
+        if (typeof data?.temp_key !== "string" || data.temp_key === "") continue;
+        const ts = Number(content.ts);
+        if (!Number.isFinite(ts) || ts <= 0) continue;
+        if (data.pc !== FOR_WEB) {
+            otherClient = true;
+            continue;
+        }
+        if (!best || ts > best.ts) best = { ts, tempKey: data.temp_key };
+    }
+    if (!best) return { status: otherClient ? "other-client" : "none" };
+    const ageMs = now - best.ts;
+    return ageMs <= maxAgeMs ? { status: "ticked", tempKey: best.tempKey, ageMs } : { status: "late", ageMs };
+}
+
+/**
+ * Which control to use: the latest `transfer_after_login` whose data has a key and is for a browser client, and
+ * recent (within `maxAgeMs`).
+ *
+ * @param {object[]} controls - `controls[]` entries of 601/603 frames: `{actionId, content: {act, data, ts}}`
+ * @param {object} [opts]
+ * @param {number} [opts.now]
+ * @param {number} [opts.maxAgeMs]
+ * @returns {{tempKey: string, ageMs: number}|null}
+ */
+export function pickTransferAfterLogin(controls, opts = {}) {
+    const offer = classifyLoginOffer(controls, opts);
+    return offer.status === "ticked" ? { tempKey: offer.tempKey, ageMs: offer.ageMs } : null;
+}
+
+/** The control queues to read when the handshake names none: what every handshake seen so far named. */
+export const DEFAULT_CONTROL_QUEUES = Object.freeze([
+    Object.freeze({ cmd: 603, subCmd: 1, queueName: "603_1" }),
+    Object.freeze({ cmd: 603, subCmd: 0, queueName: "603_0" }),
+]);
+
+/** Pages read from a saved cursor, and from the start of a queue (50 controls a page): no cap -- a read goes on
+ * until the offer is found, the server says no more, or its cursor stops moving (`stalled`). */
+const CURSOR_PAGES = Infinity;
+const START_PAGES = Infinity;
+
+/**
+ * Ask a control queue for one page and wait for its answer: the answer to this request (by `reqId`), or one that
+ * carries no `reqId` at all. Nothing else reads the control queue while a login looks at it.
+ *
+ * @returns {Promise<object|null>} the answer's body, or null when none came in `timeoutMs`
+ */
+function askPage(listener, tap, queue, data, timeoutMs) {
+    return new Promise((resolve) => {
+        let off = () => {};
+        const timer = setTimeout(() => {
+            off();
+            resolve(null);
+        }, timeoutMs);
+        off = tap.on(queue.cmd, (frame) => {
+            if (frame.subCmd !== queue.subCmd) return;
+            const reqId = frame.data?.reqId;
+            if (reqId !== undefined && reqId !== null && String(reqId) !== data.reqId) return;
+            clearTimeout(timer);
+            off();
+            resolve(frame.body || {});
+        });
+        try {
+            listener.sendWs({ version: 1, cmd: queue.cmd, subCmd: queue.subCmd, data });
+        } catch {
+            clearTimeout(timer);
+            off();
+            resolve(null);
+        }
+    });
+}
+
+/**
+ * Read one control queue from a cursor (or from its start: `lastId` null), page by page while the server says
+ * `more`. The pages reach the caller through the tap; this only
+ * drives the paging. It moves no saved cursor and acknowledges nothing (a read does not consume a control).
+ *
+ * @returns {Promise<{pages: number, reason: "drained"|"found"|"timeout"|"stalled"|"page-cap"|"reset"|"error"}>}
+ */
+async function readControlQueue({ listener, tap, queue, lastId, maxPages, pageTimeoutMs, found }) {
+    let cursor = lastId === null || lastId === undefined ? null : String(lastId);
+    let first = true;
+    let pages = 0;
+    while (pages < maxPages) {
+        const data = { first, reqId: nextReqId(), lastId: cursor, preIds: [] };
+        const body = await askPage(listener, tap, queue, data, pageTimeoutMs);
+        if (!body) return { pages, reason: "timeout" };
+        pages++;
+        if (Number(body.error_code)) return { pages, reason: "error" };
+        const d = body.data || {};
+        const reset = d.resetLastActionId;
+        if (reset !== undefined && reset !== null && reset !== "" && reset !== 0 && reset !== "0") {
+            return { pages, reason: "reset" };
+        }
+        if (found()) return { pages, reason: "found" };
+        if (!Number(d.more)) return { pages, reason: "drained" };
+        const next = d.lastActionId;
+        // A cursor that does not move would ask for the same page forever.
+        if (next === undefined || next === null || String(next) === cursor) return { pages, reason: "stalled" };
+        cursor = String(next);
+        first = false;
+    }
+    return { pages, reason: "page-cap" };
+}
+
+/**
+ * What `login --verbose` shows of each control seen while looking for the offer: its queue, act type, act, `pc`,
+ * whether it carries a key, and its age. Never the key itself.
+ *
+ * @param {Array<{queue: string, control: object}>} entries - in the order they arrived
+ * @param {number} now
+ * @returns {Array<{queue: string, actionId: string|null, actType: string|null, act: string|null, pc: unknown,
+ *   hasKey: boolean, ageMs: number|null}>} one per distinct control (by queue and action id)
+ */
+export function describeLoginControls(entries, now) {
+    const out = [];
+    const seen = new Set();
+    for (const { queue, control } of Array.isArray(entries) ? entries : []) {
+        const content = control?.content;
+        if (!content || typeof content !== "object") continue;
+        const rawId = control.actionId ?? control.controlId ?? null;
+        const actionId = rawId === null || rawId === undefined ? null : String(rawId);
+        if (actionId !== null) {
+            const id = `${queue}:${actionId}`;
+            if (seen.has(id)) continue;
+            seen.add(id);
+        }
+        let data = content.data;
+        if (typeof data === "string") {
+            try {
+                data = JSON.parse(data);
+            } catch {
+                data = null;
+            }
+        }
+        const ts = Number(content.ts);
+        out.push({
+            queue,
+            actionId,
+            actType: typeof content.act_type === "string" ? content.act_type : null,
+            act: typeof content.act === "string" ? content.act : null,
+            pc: data && typeof data === "object" && "pc" in data ? data.pc : null,
+            hasKey: typeof data?.temp_key === "string" && data.temp_key !== "",
+            ageMs: Number.isFinite(ts) && ts > 0 ? now - ts : null,
+        });
+    }
+    return out;
+}
+
+/**
+ * Open the socket of a fresh login, read the key the phone offered, and restore with it.
+ *
+ * Where the offer is: the phone puts it in the control queues at the QR confirmation, before this socket exists, so
+ * it is read from the queues (a live `601` push is taken too, if one comes). A QR re-login that keeps the device id
+ * (src/zalo/qr-login.js `deviceImeiFor`) keeps the control queue with everything it held, so the offer is at its END.
+ * Each queue is therefore read from the cursor this account saved (`cursorOf`, the one
+ * `listen` keeps), page by page while the server says `more`; a queue with no saved cursor, or one the cursor did not
+ * find it in, is read from its start the same way. (A single page asked without a cursor found the offer while every
+ * QR login made a new device; on a kept device that page is the oldest one, and the offer was never seen.)
+ *
+ * @param {object} api - a logged-in session
+ * @param {string} ownId
+ * @param {object} [opts]
+ * @param {number|null} [opts.days] - restrict the restore to the last N days (default: full history)
+ * @param {number} [opts.waitMs] - the restore's wait budget
+ * @param {(e: {phase: string, detail?: string}) => void} [opts.onStatus]
+ * @param {number} [opts.connectTimeoutMs]
+ * @param {number} [opts.authWaitMs] - how long to wait for the handshake that names the control queues
+ * @param {number} [opts.pageTimeoutMs] - how long one page is given to answer (a cold control queue once took more
+ *   than 10 s, live)
+ * @param {number} [opts.pullWaitMs] - a last wait for a live push when the queues held no offer
+ * @param {(queueName: string) => (string|{id: string}|null)} [opts.cursorOf] - the saved cursor of a control queue
+ * @param {(o: object) => Promise<object>} [opts.restore] - the restore, replaceable in a test
+ * @param {boolean} [opts.restoreWhenTicked=true] - false only reports what the phone offered (`login --no-sync`)
+ * @param {() => number} [opts.now]
+ * @returns {Promise<{offered: boolean, status: "ticked"|"late"|"other-client"|"none"|"no-socket", ageMs?: number,
+ *   reason?: string, result?: object, controls?: ReturnType<typeof describeLoginControls>,
+ *   pulls?: Array<{queue: string, from: "cursor"|"start", pages: number, reason: string}>}>} `offered` true when a
+ *   restore ran with the phone's key; `status` says what the phone offered (`no-socket`: the socket could not be
+ *   opened, so nothing is known); `controls` and `pulls` say what was seen and asked (`login --verbose`)
+ */
+export async function autoSyncAfterLogin(
+    api,
+    ownId,
+    {
+        days = null,
+        waitMs,
+        onStatus = () => {},
+        connectTimeoutMs = 30_000,
+        authWaitMs = 5000,
+        pageTimeoutMs = 15_000,
+        pullWaitMs = 1500,
+        cursorOf = () => null,
+        restore = (o) => new SyncV2(api, ownId).restore(o),
+        restoreWhenTicked = true,
+        now = () => Date.now(),
+    } = {},
+) {
+    const tap = createSocketTap();
+    tap.attach(api.listener);
+    const entries = [];
+    const collect = (frame) => {
+        const queue = `${frame.cmd}_${frame.subCmd}`;
+        for (const control of frame.data?.controls ?? []) entries.push({ queue, control });
+    };
+    tap.on(601, collect);
+    tap.on(603, collect);
+    const connected = await new Promise((resolve) => {
+        const timer = setTimeout(() => resolve({ ok: false, reason: "timeout" }), connectTimeoutMs);
+        api.listener.once("connected", () => {
+            clearTimeout(timer);
+            resolve({ ok: true });
+        });
+        api.listener.once("error", (e) => {
+            clearTimeout(timer);
+            resolve({ ok: false, reason: e?.message || "socket error" });
+        });
+        api.listener.start({ retryOnClose: false });
+    });
+    if (!connected.ok) {
+        return { offered: false, status: "no-socket", reason: `could not open the socket (${connected.reason})` };
+    }
+    const pulls = [];
+    try {
+        const read = () =>
+            classifyLoginOffer(
+                entries.map((e) => e.control),
+                { now: now() },
+            );
+        const ticked = () => read().status === "ticked";
+        // The handshake names the control queues (`ctrl_qCmds`); a request sent before it waits for it anyway.
+        for (let waited = 0; !tap.auth() && waited < authWaitMs; waited += 50) {
+            await new Promise((r) => setTimeout(r, 50));
+        }
+        const named = controlQueuesFrom(tap.auth()?.ctrl_qCmds);
+        const queues = named.length ? named : DEFAULT_CONTROL_QUEUES;
+        for (const queue of queues) {
+            if (ticked()) break;
+            let saved = null;
+            try {
+                const c = cursorOf(queue.queueName);
+                saved = typeof c === "string" ? c : (c?.id ?? null);
+            } catch {
+                saved = null;
+            }
+            const plan = [["start", null, START_PAGES]];
+            if (saved) plan.unshift(["cursor", saved, CURSOR_PAGES]);
+            for (const [from, lastId, maxPages] of plan) {
+                if (ticked()) break;
+                const r = await readControlQueue({
+                    listener: api.listener,
+                    tap,
+                    queue,
+                    lastId,
+                    maxPages,
+                    pageTimeoutMs,
+                    found: ticked,
+                });
+                pulls.push({ queue: queue.queueName, from, pages: r.pages, reason: r.reason });
+            }
+        }
+        if (!ticked()) await new Promise((r) => setTimeout(r, pullWaitMs));
+        const offer = read();
+        const diag = { controls: describeLoginControls(entries, now()), pulls };
+        if (offer.status !== "ticked") {
+            const reason = {
+                late: `the phone offered auto sync ${Math.round((offer.ageMs ?? 0) / 1000)} s ago, too long ago to use without a tap`,
+                "other-client": "the phone's auto sync offer was for Zalo's desktop app, not this client",
+                none: "auto sync was not ticked on the phone at the QR confirmation",
+            }[offer.status];
+            return { offered: false, status: offer.status, ageMs: offer.ageMs, reason, ...diag };
+        }
+        if (!restoreWhenTicked) {
+            return {
+                offered: false,
+                status: "ticked",
+                ageMs: offer.ageMs,
+                reason: "auto sync was ticked on the phone, and declined here (--no-sync)",
+                ...diag,
+            };
+        }
+        onStatus({
+            phase: "info",
+            detail: `the phone offered auto sync ${(offer.ageMs / 1000).toFixed(0)} s ago; using its key, no tap needed`,
+        });
+        const result = await restore({
+            days,
+            tempKey: offer.tempKey,
+            waitMs,
+            onStatus,
+            keepAlive: true,
+        });
+        return { offered: true, status: "ticked", ageMs: offer.ageMs, result, ...diag };
+    } finally {
+        try {
+            api.listener.stop();
+        } catch {
+            /* already closed */
+        }
+    }
+}