@ardennguyen/zalo-agent-cli 1.0.7 → 2.0.0

package/src/core/socket-tap.js

@@ -0,0 +1,154 @@
+/**
+ * A raw reader on the listener's WebSocket that keeps what zca-js throws away.
+ *
+ * zca-js decodes each frame and emits typed events built from one or two of
+ * its arrays -- the 501 handler reads only `msgs`, the 521 handler only
+ * `groupMsgs`, the 510/511 `old_messages` handler only the message arrays --
+ * and keeps nothing of the handshake (cmd 1) but its cipher `key`. Everything
+ * else in the envelope is gone before our handlers run:
+ *
+ *   queueStatus {"<queue>": {ids, lastId, evict}}   the per-queue cursors
+ *   lastActionId, more                               offline-queue paging
+ *   resetLastActionId                                "start the cursor over"
+ *   clearUnreads, pageMsgs, delivereds, seens        read state, page messages
+ *   qCmds, ctrl_qCmds, bk_cmds (cmd 1)               which queues to drain
+ *
+ * Zalo Web reads all of it (bundle 1.e0ef5e98…: `processSuccessData` →
+ * `queueIds.addLastActionIds(o.queueStatus, …)` @~11109700, `onAuthenticated`
+ * reads `data.qCmds` @~11118700). So does this: it listens beside zca-js on the
+ * same raw `ws`, decodes each frame with the repo's own mirror of zca-js's
+ * decoder, and hands `{cmd, subCmd, body, data}` to whoever subscribed to that
+ * cmd. The reaction backlog drain has done this privately since 2026-09-28
+ * (./sync-v2/reactions.js); this is the same technique, shared, for everything
+ * that needs a field zca-js drops -- the offline-queue catch-up first
+ * (./self-heal.js), read-state sync and pageMsgs after it.
+ *
+ * It reads and routes; it never writes, never sends, and never needs a zca-js
+ * patch. `listen` and `mcp start` both attach it (AGENTS.md §13).
+ */
+import { decodeFrame } from "./sync-v2/index.js";
+
+/** The handshake: its answer carries the cipher key and the queue lists. */
+export const CMD_AUTHEN = 1;
+
+/**
+ * Read one raw socket frame: zca-js's 4-byte header, then its JSON body.
+ *
+ * The header is `[version, cmd as uint16 LE, subCmd]` (zca-js `getHeader`).
+ * A body of `{encrypt, data: <string>}` is decoded with the session's cipher
+ * key -- the handshake frame carries its own `key`, which zca-js adopts at the
+ * same moment -- and any other body is taken as it is.
+ *
+ * @param {Buffer} buf
+ * @param {string} [cipherKey]
+ * @returns {{version: number, cmd: number, subCmd: number, body: object, data: object|null}|null}
+ *   null for anything that is not a readable frame
+ */
+export function readFrame(buf, cipherKey) {
+    if (!Buffer.isBuffer(buf) || buf.length < 4) return null;
+    const version = buf[0];
+    const cmd = buf.readUInt16LE(1);
+    const subCmd = buf[3];
+    let parsed;
+    try {
+        parsed = JSON.parse(buf.subarray(4).toString("utf8"));
+    } catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== "object") return null;
+    let body = parsed;
+    if (typeof parsed.data === "string" && typeof parsed.encrypt === "number") {
+        try {
+            body = decodeFrame(parsed, parsed.key || cipherKey);
+        } catch {
+            return null;
+        }
+    }
+    const data = body && typeof body === "object" && body.data && typeof body.data === "object" ? body.data : null;
+    return { version, cmd, subCmd, body, data };
+}
+
+/**
+ * Build the tap. One per daemon: it outlives each socket and each re-login.
+ *
+ * @param {object} [opts]
+ * @param {(line: string) => void} [opts.log] - where a failing subscriber is reported
+ * @returns {{
+ *   attach: (listener: object) => void,
+ *   on: (cmd: number, fn: (frame: object, listener: object) => void) => () => void,
+ *   auth: () => object|null,
+ * }} `attach` taps the listener's current socket and every one it opens after;
+ *   `on` subscribes to one cmd and returns the unsubscribe; `auth` is the last
+ *   handshake's `data` (qCmds, ctrl_qCmds, bk_cmds), or null before the first
+ */
+export function createSocketTap({ log = (line) => console.error(line) } = {}) {
+    /** @type {Map<number, Set<Function>>} */
+    const subscribers = new Map();
+    /** Sockets already tapped: a re-login attaches again, and a frame must arrive once. */
+    const tapped = new WeakSet();
+    /** Listeners already watched for new sockets. */
+    const watched = new WeakSet();
+    let lastAuth = null;
+
+    function deliver(frame, listener) {
+        if (frame.cmd === CMD_AUTHEN && frame.data) lastAuth = frame.data;
+        const fns = subscribers.get(frame.cmd);
+        if (!fns) return;
+        for (const fn of [...fns]) {
+            try {
+                fn(frame, listener);
+            } catch (e) {
+                try {
+                    log(`socket tap: a cmd ${frame.cmd} handler failed: ${e?.message || e}`);
+                } catch {
+                    /* a broken logger must not break the socket either */
+                }
+            }
+        }
+    }
+
+    function tapSocket(listener) {
+        const ws = listener?.ws;
+        if (!ws || typeof ws.on !== "function" || tapped.has(ws)) return;
+        tapped.add(ws);
+        ws.on("message", (buf) => {
+            // Only cmds someone asked for are decoded, so a quiet tap costs
+            // one header read per frame; the handshake is always kept.
+            if (!Buffer.isBuffer(buf) || buf.length < 4) return;
+            const cmd = buf.readUInt16LE(1);
+            if (cmd !== CMD_AUTHEN && !subscribers.has(cmd)) return;
+            const frame = readFrame(buf, listener.cipherKey);
+            if (frame) deliver(frame, listener);
+        });
+    }
+
+    return {
+        attach(listener) {
+            if (!listener) return;
+            tapSocket(listener);
+            // zca-js opens a NEW ws on every retry and announces it with
+            // `connected` from its onopen, before any frame can arrive -- so
+            // re-arming there never misses the handshake.
+            if (!watched.has(listener) && typeof listener.on === "function") {
+                watched.add(listener);
+                listener.on("connected", () => tapSocket(listener));
+            }
+        },
+
+        on(cmd, fn) {
+            const key = Number(cmd);
+            if (!subscribers.has(key)) subscribers.set(key, new Set());
+            subscribers.get(key).add(fn);
+            return () => {
+                const set = subscribers.get(key);
+                if (!set) return;
+                set.delete(fn);
+                if (set.size === 0) subscribers.delete(key);
+            };
+        },
+
+        auth() {
+            return lastAuth;
+        },
+    };
+}

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

@@ -0,0 +1,181 @@
+/**
+ * transfer-sync-v2 crypto/codec assets.
+ *
+ * Zalo Web decrypts sync batches with a wasm-bindgen module (`libzproto`) and
+ * decodes them with google-protobuf ("jspb") message classes, both shipped in
+ * its public web bundle. Rather than vendor Zalo's proprietary binary into this
+ * package, we fetch those pieces from Zalo's own CDN on first use and cache the
+ * extracted modules locally (they are ~350 KB total and change only when Zalo
+ * ships a new web build). Everything runs in-process in Node — no browser.
+ *
+ * Pipeline these assets serve (see src/core/sync-v2/index.js):
+ *   msgUrl bytes -> [u32 LE len][payload] chunk -> zproto decrypt
+ *     (metadata: it.j(chunk, ikPub, ikPriv, ekPriv) -> sessionRecord + plaintext;
+ *      message:  it.i(chunk, sessionRecord) -> plaintext)
+ *   -> Zstd (node:zlib) -> protobuf SyncChunk.
+ */
+import fs from "node:fs";
+import { resolve } from "node:path";
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+const APP_ORIGIN = "https://chat.zalo.me";
+const UA = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131 Safari/537.36";
+
+/** Extract one webpack module body `"<id>":function(A,e,t){...}` (or `<id>:function…`) by brace matching. */
+function extractModule(src, id) {
+    let start = src.indexOf(`"${id}":function(`);
+    let sliceFrom = start;
+    if (start < 0) {
+        start = src.indexOf(`${id}:function(`);
+        sliceFrom = start;
+    }
+    if (start < 0) throw new Error(`webpack module ${id} not found (Zalo web build changed?)`);
+    const braceStart = src.indexOf("{", src.indexOf("function(", start));
+    let depth = 0;
+    for (let i = braceStart; i < src.length; i++) {
+        const c = src[i];
+        if (c === "{") depth++;
+        else if (c === "}") {
+            depth--;
+            if (depth === 0) return src.slice(sliceFrom, i + 1);
+        }
+    }
+    throw new Error(`webpack module ${id} not brace-balanced`);
+}
+
+async function fetchText(url) {
+    const r = await fetch(url, { headers: { "User-Agent": UA } });
+    if (!r.ok) throw new Error(`GET ${url} -> ${r.status}`);
+    return r.text();
+}
+async function fetchBytes(url) {
+    const r = await fetch(url, { headers: { "User-Agent": UA } });
+    if (!r.ok) throw new Error(`GET ${url} -> ${r.status}`);
+    return Buffer.from(await r.arrayBuffer());
+}
+
+/**
+ * Ensure the extracted assets exist under `cacheDir`, fetching from the CDN
+ * once and caching by the web build's worker hash. Returns absolute paths.
+ *
+ * @param {string} cacheDir
+ * @param {(m: string) => void} [log]
+ * @returns {Promise<{dir: string, wasm: string, glue: string, pbMsg: string, pbConv: string}>}
+ */
+export async function ensureAssets(cacheDir, log = () => {}) {
+    // Discover the sync-v2 worker filename from the app shell.
+    const html = await fetchText(`${APP_ORIGIN}/`);
+    const wm = /__SRC_SYNC_V2_WORKER__\s*=\s*'([^']+)'/.exec(html) || /(sync-v2-worker\.[0-9a-f]+\.js)/.exec(html);
+    if (!wm) throw new Error("could not locate sync-v2 worker in Zalo web shell");
+    const workerFile = wm[1];
+    const hash = (/\.([0-9a-f]{6,})\.js$/.exec(workerFile) || [, "unknown"])[1];
+    const dir = resolve(cacheDir, hash);
+    const paths = {
+        dir,
+        wasm: resolve(dir, "libzproto_bg.wasm"),
+        glue: resolve(dir, "vox7.glue.js"),
+        pbMsg: resolve(dir, "pb.message.js"),
+        pbConv: resolve(dir, "pb.conversation.js"),
+    };
+    if (
+        fs.existsSync(paths.wasm) &&
+        fs.existsSync(paths.glue) &&
+        fs.existsSync(paths.pbMsg) &&
+        fs.existsSync(paths.pbConv)
+    )
+        return paths;
+
+    log(`fetching transfer-sync-v2 assets (build ${hash}) from ${APP_ORIGIN}…`);
+    fs.mkdirSync(dir, { recursive: true });
+    const worker = await fetchText(`${APP_ORIGIN}/${workerFile}`);
+    // The libzproto glue module id used by Zalo web is "Vox7"; message/conversation protobufs are "1y5R"/"Ho1Y".
+    fs.writeFileSync(paths.glue, extractModule(worker, "Vox7"));
+    fs.writeFileSync(paths.pbMsg, extractModule(worker, "1y5R"));
+    fs.writeFileSync(paths.pbConv, extractModule(worker, "Ho1Y"));
+    const wasmRef = /libs\/libzproto_wasm_bg\.[0-9a-f]+\.wasm/.exec(worker);
+    if (!wasmRef) throw new Error("could not locate libzproto wasm filename in worker");
+    fs.writeFileSync(paths.wasm, await fetchBytes(`${APP_ORIGIN}/${wasmRef[0]}`));
+    log(`cached sync-v2 assets in ${dir}`);
+    return paths;
+}
+
+function stripModulePrefix(src, id) {
+    src = src.trim();
+    if (src.startsWith(`"${id}":`)) return src.slice(`"${id}":`.length);
+    if (src.startsWith(`${id}:`)) return src.slice(`${id}:`.length);
+    return src;
+}
+
+/** Minimal webpack __webpack_require__ shim covering what these modules use. */
+function makeRequire(extra) {
+    const t = (id) => {
+        if (id === "yLpj") return globalThis; // webpack global helper
+        if (id === "3UD+") return (m) => m; // wasm default-path helper (unused; we pass bytes)
+        if (id === "hRO2") return require("google-protobuf"); // jspb + goog runtime
+        if (id === "N3ek") return {}; // base proto namespace
+        if (extra && extra[id]) return extra[id];
+        throw new Error(`sync-v2 asset required an unmocked webpack module: ${id}`);
+    };
+    t.d = (e, name, getter) => {
+        if (!Object.prototype.hasOwnProperty.call(e, name))
+            Object.defineProperty(e, name, { enumerable: true, get: getter });
+    };
+    t.r = () => {};
+    t.n = (m) => () => m;
+    t.o = (o, k) => Object.prototype.hasOwnProperty.call(o, k);
+    return t;
+}
+
+function runModule(srcFile, id) {
+    const src = stripModulePrefix(fs.readFileSync(srcFile, "utf8"), id);
+    const factory = (0, eval)("(" + src + ")");
+    const mod = { exports: {} };
+    factory(mod, mod.exports, makeRequire());
+    return mod.exports;
+}
+
+/**
+ * Load the crypto (WASM) + protobuf codecs from cached assets.
+ *
+ * @param {{wasm: string, glue: string, pbMsg: string, pbConv: string}} paths
+ * @returns {Promise<{zproto: object, M: object, C: object}>}
+ */
+export async function loadCodecs(paths) {
+    // ---- libzproto WASM via the Vox7 wasm-bindgen glue ----
+    const it = runModule(paths.glue, "Vox7");
+    await it.b(fs.readFileSync(paths.wasm)); // e.b = init(module_or_path); accepts raw bytes
+    const u8 = (x) => (x instanceof Uint8Array ? x : new Uint8Array(x));
+    const zproto = {
+        generateKeyPair() {
+            const a = it.e();
+            const out = { publicKey: Buffer.from(a.publicKey.slice()), privateKey: Buffer.from(a.privateKey.slice()) };
+            a.free();
+            return out;
+        },
+        decryptMetadata(metaChunk, ikPub, ikPriv, ekPriv) {
+            const r = it.j(u8(metaChunk), u8(ikPub), u8(ikPriv), u8(ekPriv));
+            const out = {
+                plaintext: Buffer.from(r.plaintext.slice()),
+                sessionRecord: Buffer.from(r.sessionRecord.slice()),
+            };
+            r.free();
+            return out;
+        },
+        decryptMessage(msgChunk, sessionRecord) {
+            const r = it.i(u8(msgChunk), u8(sessionRecord));
+            const out = { plaintext: Buffer.from(r.plaintext.slice()) };
+            r.free();
+            return out;
+        },
+    };
+
+    // ---- protobuf (jspb) codecs; they register on a global `proto` namespace ----
+    if (!globalThis.proto) globalThis.proto = {};
+    runModule(paths.pbMsg, "1y5R");
+    runModule(paths.pbConv, "Ho1Y");
+    const M = globalThis.proto?.Sync2?.Message;
+    const C = globalThis.proto?.Sync2?.Conversation;
+    if (!M?.SyncChunk || !C?.SyncChunk) throw new Error("sync-v2 protobuf codecs failed to load");
+    return { zproto, M, C };
+}

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

@@ -0,0 +1,338 @@
+/**
+ * Sync the things that never travel in the message stream.
+ *
+ * transfer-sync-v2 carries messages and nothing else. Notes ("Ghi chú"),
+ * pinned messages, polls and reminders ("Nhắc hẹn") are *board* objects behind
+ * plain REST endpoints, one call per thread:
+ *
+ *   groups : {group_board}/api/board/list          -> notes + pinned + polls
+ *            {group_board}/api/board/listReminder  -> reminders
+ *   DMs    : {group_board}/api/board/oneone/list   -> the SAME board kinds
+ *            {friend_board}/api/friendboard/list   -> the friend board
+ *
+ * Boards are NOT a group-only feature. A 1-1 conversation has notes, pinned
+ * messages and reminders too, behind /api/board/oneone/* (list/create/update/
+ * remove, cmd 12430-12432). An earlier version of this module asked for
+ * reminders on a DM and nothing else, so every pinned message and note in a 1-1
+ * conversation was silently missing.
+ *
+ * The conversation *events* that announce these do arrive as messages — a
+ * reminder shows up as msgType 24, a closed poll as msgType 26 — but those are
+ * only announcements. The objects themselves exist solely here.
+ *
+ * Cost shapes the design: a full account is ~1500 threads and two-plus calls
+ * each, so this runs at low concurrency with a pause between calls, supports a
+ * thread cap, and skips threads synced recently. It is deliberately not part
+ * of the phone-backed restore — no confirmation is needed and nothing here
+ * touches the WebSocket.
+ */
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { ThreadType } from "zca-js";
+import { upsertBoardItem, upsertReminder } from "../db.js";
+
+const require = createRequire(import.meta.url);
+
+/** zca-js BoardType: what /api/board/list returns per item. */
+export const BOARD_TYPES = { 1: "note", 2: "pinned_message", 3: "poll" };
+
+let _utils = null;
+/** zca-js internals, located the same way ./gid.js does. */
+function zcaUtils() {
+    if (_utils) return _utils;
+    _utils = require(join(dirname(require.resolve("zca-js")), "utils.cjs"));
+    return _utils;
+}
+
+/**
+ * List a 1-1 conversation's board (notes, pinned messages, polls).
+ *
+ * zca-js exposes /api/board/oneone/list only through getListReminder, hardwired
+ * to board_type 1, so reminders were the only thing a DM ever returned. This
+ * asks the same endpoint for every board type, which is what Zalo Web does.
+ *
+ * @returns {Promise<{items: Array<object>}>}
+ */
+async function listOneOneBoard(api, threadId, page, pageSize) {
+    const zu = zcaUtils();
+    const base = `${api.zpwServiceMap.group_board[0]}/api/board/oneone/list`;
+    const call = zu.apiFactory()((_api, ctx, utils) => async () => {
+        const params = {
+            objectData: JSON.stringify({
+                uid: String(threadId),
+                board_type: 0, // 0 = every kind, not just reminders
+                page,
+                count: pageSize,
+                last_id: 0,
+                last_type: 0,
+            }),
+            imei: ctx.imei,
+        };
+        const enc = utils.encodeAES(JSON.stringify(params));
+        if (!enc) throw new Error("failed to encrypt oneone board params");
+        const resp = await utils.request(utils.makeURL(base, { params: enc }), { method: "GET" });
+        return utils.resolve(resp);
+    })(api.getContext(), api);
+
+    const raw = await call();
+    const parsed = typeof raw === "string" ? JSON.parse(raw) : raw;
+    const items = parsed?.items || parsed?.data?.items || (Array.isArray(parsed) ? parsed : []);
+    return { items };
+}
+
+/** Stringify an id Zalo may send as a number, or leave it null. */
+const str = (v) => (v === undefined || v === null ? null : String(v));
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/** Board/reminder payloads keep `params` as either an object or a JSON string. */
+function params(obj) {
+    const p = obj?.params;
+    if (!p) return {};
+    if (typeof p === "object") return p;
+    try {
+        return JSON.parse(p);
+    } catch {
+        return {};
+    }
+}
+
+/**
+ * Normalize one /api/board/list item. Polls carry a different shape from
+ * notes and pinned messages, so they are unpacked separately.
+ *
+ * @returns {object|null} a row for upsertBoardItem(), or null if unusable
+ */
+export function normalizeBoardItem(item, threadId, threadType) {
+    const type = Number(item?.boardType);
+    const d = item?.data;
+    if (!d || !type) return null;
+
+    if (type === 3) {
+        const id = d.poll_id ?? d.pollId;
+        if (id === undefined || id === null) return null;
+        return {
+            threadId,
+            threadType,
+            boardType: type,
+            itemId: String(id),
+            title: d.question ?? null,
+            creatorId: str(d.creator),
+            createTime: d.created_time,
+            editTime: d.updated_time,
+            startTime: d.created_time,
+            duration: d.expired_time ? d.expired_time - (d.created_time || 0) : null,
+            repeat: null,
+            emoji: null,
+            color: null,
+            raw_data: d,
+        };
+    }
+
+    if (d.id === undefined || d.id === null) return null;
+    return {
+        threadId,
+        threadType,
+        boardType: type,
+        itemId: String(d.id),
+        title: params(d).title ?? null,
+        creatorId: str(d.creatorId),
+        createTime: d.createTime,
+        editTime: d.editTime,
+        startTime: d.startTime,
+        duration: d.duration,
+        repeat: d.repeat,
+        emoji: d.emoji ?? null,
+        color: d.color,
+        raw_data: d,
+    };
+}
+
+/**
+ * Normalize one reminder. DM reminders (`ReminderUser`) and group reminders
+ * (`ReminderGroup`) name their creator and id differently.
+ *
+ * @returns {object|null} a row for upsertReminder(), or null if unusable
+ */
+export function normalizeReminder(r, threadId, threadType) {
+    const id = r?.reminderId ?? r?.id;
+    if (id === undefined || id === null) return null;
+    return {
+        reminderId: String(id),
+        threadId,
+        threadType,
+        title: params(r).title ?? null,
+        creatorId: str(r.creatorId) ?? str(r.creatorUid),
+        createTime: r.createTime,
+        editTime: r.editTime,
+        startTime: r.startTime,
+        duration: r.duration,
+        repeatMode: r.repeat,
+        emoji: r.emoji ?? null,
+        color: r.color,
+        eventType: r.eventType,
+        raw_data: r,
+    };
+}
+
+/** Reminder lists come back as an array, or wrapped in one of a few keys. */
+function asList(resp) {
+    if (Array.isArray(resp)) return resp;
+    for (const k of ["items", "list", "reminders", "data", "events"]) {
+        const v = resp?.[k];
+        if (Array.isArray(v)) return v;
+    }
+    if (Array.isArray(resp?.data?.items)) return resp.data.items;
+    if (Array.isArray(resp?.data?.list)) return resp.data.list;
+    return [];
+}
+
+/**
+ * Sync board items and reminders for the given threads.
+ *
+ * Every per-thread call is individually guarded: one thread that 403s (a group
+ * you were removed from, a DM with a blocked user) must not abort a run that
+ * covers hundreds of others.
+ *
+ * @param {object} opts
+ * @param {object} opts.api - logged-in zca-js api
+ * @param {Array<{threadId: string, type: "dm"|"group", name?: string}>} opts.threads
+ * @param {boolean} [opts.boards=true] - fetch notes/pinned/polls (groups only)
+ * @param {boolean} [opts.reminders=true] - fetch reminders
+ * @param {number} [opts.concurrency=3] - parallel threads; Zalo rate-limits hard
+ * @param {number} [opts.delayMs=120] - pause between calls within a worker
+ * @param {number} [opts.pageSize=50]
+ * @param {number} [opts.maxPages=10] - board pagination cap per thread
+ * @param {(p: object) => void} [opts.onProgress] - one `{phase: "thread",
+ *   threadId, ok}` event per finished thread, where `ok` is false if any of
+ *   that thread's own calls failed. Callers that clear per-thread state must
+ *   check it.
+ * @returns {Promise<{threads:number, boardItems:number, reminders:number, failed:number, failures:Array<object>}>}
+ */
+/**
+ * A failure reason someone can act on.
+ *
+ * zca-js builds its error from the server's error_message, which for these
+ * endpoints is often null -- so the message arrives as the literal string
+ * "null" and the only signal is the numeric code. A live board pass reported
+ * 165 failures, every one of them printed as "null".
+ *
+ * @param {unknown} e
+ * @returns {string}
+ */
+export function describeZaloError(e) {
+    const msg = e?.message;
+    const text = msg && msg !== "null" && msg !== "undefined" ? String(msg) : "";
+    const code = e?.code;
+    if (code !== undefined && code !== null) return text ? `${text} (code ${code})` : `code ${code}`;
+    return text || String(e);
+}
+
+export async function syncBoards(opts = {}) {
+    const {
+        api,
+        threads = [],
+        boards = true,
+        reminders = true,
+        concurrency = 3,
+        delayMs = 120,
+        pageSize = 50,
+        maxPages = 10,
+        onProgress = () => {},
+    } = opts;
+
+    const stats = { threads: 0, boardItems: 0, reminders: 0, failed: 0, failures: [] };
+    if (!api || !threads.length) return stats;
+
+    const note = (threadId, what, e) => {
+        stats.failed++;
+        if (stats.failures.length < 20) stats.failures.push({ threadId, what, reason: describeZaloError(e) });
+    };
+
+    let cursor = 0;
+    const worker = async () => {
+        for (;;) {
+            const t = threads[cursor++];
+            if (!t) return;
+            const isGroup = t.type === "group";
+
+            // Per-thread, not per-run: the caller clears a thread's "board
+            // changed" flag on the strength of this, and a run-wide failure
+            // count would clear the flag for a thread whose fetch actually
+            // failed -- losing the one signal that says to come back to it.
+            let hadFailure = false;
+            const noteHere = (what, e) => {
+                hadFailure = true;
+                note(t.threadId, what, e);
+            };
+
+            // Notes / pinned messages / polls, for BOTH thread kinds. A group
+            // uses /api/board/list; a 1-1 uses /api/board/oneone/list, which
+            // takes the same board_type filter.
+            if (boards) {
+                for (let page = 1; page <= maxPages; page++) {
+                    let resp;
+                    try {
+                        resp = isGroup
+                            ? await api.getListBoard({ page, count: pageSize }, t.threadId)
+                            : await listOneOneBoard(api, t.threadId, page, pageSize);
+                    } catch (e) {
+                        noteHere("board", e);
+                        break;
+                    }
+                    const items = resp?.items || resp?.data?.items || [];
+                    for (const item of items) {
+                        const row = normalizeBoardItem(item, t.threadId, t.type);
+                        if (!row) continue;
+                        try {
+                            upsertBoardItem(row);
+                            stats.boardItems++;
+                        } catch (e) {
+                            noteHere("board-write", e);
+                        }
+                    }
+                    if (items.length < pageSize) break;
+                    if (delayMs) await sleep(delayMs);
+                }
+            }
+
+            if (reminders) {
+                try {
+                    const resp = await api.getListReminder(
+                        { page: 1, count: pageSize },
+                        t.threadId,
+                        isGroup ? ThreadType.Group : ThreadType.User,
+                    );
+                    for (const r of asList(resp)) {
+                        const row = normalizeReminder(r, t.threadId, t.type);
+                        if (!row) continue;
+                        try {
+                            upsertReminder(row);
+                            stats.reminders++;
+                        } catch (e) {
+                            noteHere("reminder-write", e);
+                        }
+                    }
+                } catch (e) {
+                    noteHere("reminder", e);
+                }
+            }
+
+            stats.threads++;
+            onProgress({
+                phase: "thread",
+                threadId: t.threadId,
+                name: t.name,
+                ok: !hadFailure,
+                done: stats.threads,
+                total: threads.length,
+                boardItems: stats.boardItems,
+                reminders: stats.reminders,
+            });
+            if (delayMs) await sleep(delayMs);
+        }
+    };
+
+    await Promise.all(Array.from({ length: Math.max(1, Math.min(8, concurrency)) }, worker));
+    return stats;
+}