@ardennguyen/zalo-agent-cli 2.5.8 → 3.0.0

package/src/core/offline-queue.js

@@ -1,194 +0,0 @@
-/**
- * Zalo's offline message queues: ask what this session missed since a cursor.
- *
- * What Zalo Web does on every authenticated connect (bundle
- * 1.e0ef5e98f8f9d8970e2c.js, character offsets):
- *
- *   `_doAfterAuth` hands the handshake to each handler (@~2698600); the chat
- *   handler's `onAuthenticated` (@~11118700) takes the queue list from the
- *   handshake's `data.qCmds` and calls `signalGetOffline` (@~3209700), which
- *   sends `doGetOffline(cmd, subCmd, first=true)` for every queue (@~3210267):
- *
- *     {cmd, subCmd, data: {first, reqId, lastId, preIds}}
- *
- *   `lastId` is that queue's saved cursor (`queueIds.getLastActionIdsForSocket`
- *   @~1391535; "1" when it has none). `onGotOffline` (@~3210990) pages while
- *   the answer says `data.more`, asking again with `first:false` from the
- *   answer's `lastActionId`, and `checkQueueOverflow` reads
- *   `queueStatus[q].evict` -- the server's word that it dropped queued items.
- *
- * Captured on the wire (agent/work/transfer-sync-v2/zalo-cap-sync.decoded.jsonl):
- * the handshake lists `510_1` (1-1) and `511_1` (group) among its `qCmds`; the
- * web asks both within a millisecond of each other with `first:true`, a
- * msgId-shaped `lastId` and `preIds:[]`; each answer arrives in ~100 ms as
- * `{lastActionId, more, msgs|groupMsgs, queueStatus: {"511_1": {ids, lastId,
- * evict}}, reqId}`. Live pushes carry the same `queueStatus`, and for these
- * two queues its `lastId` is the pushed message's msgId
- * (live/socket.L1_group_echo.json, socket.L4_dm_echo.json).
- *
- * zca-js already sends this request shape (`listener.requestOldMessages`) but
- * only ever with `first:true`, and its `old_messages` event drops `more`,
- * `lastActionId` and `queueStatus` -- so a queue longer than one page could
- * never be finished. This module sends through `listener.sendWs` and reads
- * the answers off the raw socket (./socket-tap.js).
- */
-
-/** zca-js ThreadType values. */
-const THREAD_USER = 0;
-const THREAD_GROUP = 1;
-
-/**
- * The offline queues this module can drain, keyed by cmd: the two that carry
- * plaintext messages. The handshake also lists 515/517/518 -- the E2EE
- * session and ack queues in Zalo Web's SignalCommands (516 SESSION_OFFLINE,
- * 517 SESSION_OFFLINE_WEB, 518 OFFLINE_ACK_ONE_ONE) -- which we do not decode.
- */
-const MESSAGE_QUEUES = new Map([
-    [510, { threadType: THREAD_USER, rows: "msgs" }],
-    [511, { threadType: THREAD_GROUP, rows: "groupMsgs" }],
-]);
-
-/** What the captured handshake lists for them, used until a handshake has been read. */
-export const DEFAULT_MESSAGE_QUEUES = Object.freeze([
-    Object.freeze({ cmd: 510, subCmd: 1, queueName: "510_1", threadType: THREAD_USER }),
-    Object.freeze({ cmd: 511, subCmd: 1, queueName: "511_1", threadType: THREAD_GROUP }),
-]);
-
-/** Answer wait per page. The web's came back in ~100 ms. */
-export const DEFAULT_PAGE_TIMEOUT_MS = 10_000;
-
-/** Pages per queue: the runaway stop, as in the reaction drain. */
-export const DEFAULT_MAX_PAGES = 20;
-
-let reqSeq = 0;
-/** Zalo Web's `reqId` shape, `req_<n>`; answers echo it. */
-const nextReqId = () => `req_${1_000_000 + ++reqSeq}`;
-
-/**
- * The message queues a handshake names, in its order.
- *
- * Follows `qCmds` rather than assuming 510/511, as the web does, and keeps only
- * the queues whose answers this module can store. With no handshake to go on,
- * the captured pair.
- *
- * @param {Array<{cmd: number, subCmd: number, queueName?: string}>} [qCmds]
- * @returns {Array<{cmd: number, subCmd: number, queueName: string, threadType: number}>}
- */
-export function messageQueuesFrom(qCmds) {
-    if (!Array.isArray(qCmds) || qCmds.length === 0) return [...DEFAULT_MESSAGE_QUEUES];
-    const out = [];
-    for (const q of qCmds) {
-        const cmd = Number(q?.cmd);
-        const kind = MESSAGE_QUEUES.get(cmd);
-        if (!kind) continue;
-        const subCmd = Number(q?.subCmd) || 0;
-        out.push({ cmd, subCmd, queueName: String(q?.queueName || `${cmd}_${subCmd}`), threadType: kind.threadType });
-    }
-    return out;
-}
-
-/**
- * Ask once and wait for the answer to THIS request.
- *
- * @returns {Promise<object|null>} the decoded answer body, or null on timeout
- */
-function request({ listener, tap, queue, data, timeoutMs }) {
-    return new Promise((resolve) => {
-        let off = () => {};
-        const timer = setTimeout(() => {
-            off();
-            resolve(null);
-        }, timeoutMs);
-        off = tap.on(queue.cmd, (frame, from) => {
-            if (from && from !== listener) return;
-            if (frame.subCmd !== queue.subCmd) return;
-            // Only the answer to THIS request. The server echoes reqId (every
-            // captured 510/511 answer does), while another reader of the same
-            // stream -- zalo_get_history, or `msg history`'s scan, which page it
-            // through zca-js outside this request -- gets answers without ours.
-            // Taking one of those would store the wrong page and claim coverage
-            // from it; an answer we cannot match is a timeout instead.
-            if (String(frame.data?.reqId ?? "") !== data.reqId) return;
-            clearTimeout(timer);
-            off();
-            resolve(frame.body || {});
-        });
-        try {
-            // requireId false: the web's request carries `reqId`, not zca-js's `req_id`.
-            listener.sendWs({ version: 1, cmd: queue.cmd, subCmd: queue.subCmd, data }, false);
-        } catch {
-            clearTimeout(timer);
-            off();
-            resolve(null);
-        }
-    });
-}
-
-/**
- * Drain one offline queue from a cursor, as `doGetOffline` / `onGotOffline` do.
- *
- * @param {object} args
- * @param {object} args.listener - a zca-js Listener whose socket is open and authenticated
- * @param {ReturnType<import("./socket-tap.js").createSocketTap>} args.tap - attached to that listener
- * @param {{cmd: number, subCmd: number, queueName: string}} args.queue
- * @param {string} args.lastId - the cursor: the last queue id this session holds
- * @param {number} [args.timeoutMs]
- * @param {number} [args.maxPages]
- * @returns {Promise<{rows: object[], pages: number, complete: boolean,
- *   reason: "drained"|"timeout"|"stalled"|"page-cap"|"reset"|"error",
- *   evicted: boolean, resetTo: string|null, lastActionId: string|null}>}
- *   `rows` are the server's raw message rows, oldest page first. `complete`
- *   is true only when the server said there is nothing more; `evicted` is
- *   its word that it dropped queued items, `resetTo` a cursor it told us to
- *   start over from (`resetLastActionId`).
- */
-export async function drainOfflineQueue({
-    listener,
-    tap,
-    queue,
-    lastId,
-    timeoutMs = DEFAULT_PAGE_TIMEOUT_MS,
-    maxPages = DEFAULT_MAX_PAGES,
-}) {
-    const kind = MESSAGE_QUEUES.get(Number(queue.cmd));
-    const rowsKey = kind?.rows || "msgs";
-    const out = {
-        rows: [],
-        pages: 0,
-        complete: false,
-        reason: "page-cap",
-        evicted: false,
-        resetTo: null,
-        lastActionId: null,
-    };
-    let cursor = String(lastId);
-    let first = true;
-
-    while (out.pages < maxPages) {
-        const data = { first, reqId: nextReqId(), lastId: cursor, preIds: [] };
-        const body = await request({ listener, tap, queue, data, timeoutMs });
-        if (!body) return { ...out, reason: "timeout" };
-        out.pages++;
-        if (Number(body.error_code) && Number(body.error_code) !== 0) return { ...out, reason: "error" };
-        const d = body.data || {};
-
-        // `processSuccessData` resets its cursors and processes nothing else
-        // when the server sends this (@~11109800).
-        const reset = d.resetLastActionId;
-        if (reset !== undefined && reset !== null && reset !== "" && reset !== 0 && reset !== "0") {
-            return { ...out, reason: "reset", resetTo: String(reset) };
-        }
-
-        if (Array.isArray(d[rowsKey])) out.rows.push(...d[rowsKey]);
-        if (Number(d.queueStatus?.[queue.queueName]?.evict) === 1) out.evicted = true;
-        if (d.lastActionId !== undefined && d.lastActionId !== null) out.lastActionId = String(d.lastActionId);
-
-        if (!Number(d.more)) return { ...out, complete: true, 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 { ...out, reason: "stalled" };
-        cursor = String(next);
-        first = false;
-    }
-    return out;
-}

package/src/core/pin.js

@@ -1,222 +0,0 @@
-/**
- * Pin and unpin a message the way Zalo Web does.
- *
- * zca-js has none of these endpoints, so they are custom calls on its session
- * envelope (./zca-custom.js). Each shape is the one captured from Zalo Web on
- * 2026-09-29 (agent/work/zalo-web-capture-2026-09-29/live/group.A9_pin_message,
- * group.A9b_unpin_message, dm.D9_pin_message, dm.D9b_unpin_message):
- *
- *   group pin    POST {group_board}/api/board/topic/createv2
- *   group unpin  GET  {group_board}/api/board/unpinv2
- *   1-1 pin      GET  {friend_board}/api/friendboard/create
- *   1-1 unpin    GET  {friend_board}/api/friendboard/multi_unpin
- *
- * A pinned message is a board "topic" of type 2 whose `params` name the
- * message. Unpinning takes the topic's id, not the message's, so both unpins
- * start by listing the pinned topics: `/api/board/pin/list` for a group (the
- * web's fetchTopics, which also hands back the `boardVersion` unpinv2 needs)
- * and zca-js's getFriendBoardList for a 1-1 (which returns the `version`
- * create and multi_unpin need). A stale group board version is error 183; the
- * web then refetches once and retries, and so does this.
- *
- * Only text messages: text is the kind the capture covers, and every other
- * kind carries its own params blob.
- */
-import { customCall, getWithParams, postWithParams } from "./zca-custom.js";
-
-/** A pinned message's board topic type (the web's MSG_TOPIC). */
-export const PINNED_MESSAGE_TOPIC = 2;
-
-/** Zalo's error for a group board version that moved on (the web's INVALID_BOARD_VERSION). */
-export const INVALID_BOARD_VERSION = 183;
-
-/** #222222 -- the web's `settings.group.topic_colors[0]` in the capture. */
-const DEFAULT_TOPIC_COLOR = -14540254;
-
-/** The emoji the web gives a pinned text message (`:pushpin:`). */
-const TEXT_PIN_EMOJI = "📌";
-
-/**
- * The `params` of a text message's pin topic, in the web's field order.
- *
- * @param {object} m
- * @param {string} m.cliMsgId
- * @param {string} m.msgId
- * @param {string} m.senderUid - the sender's numeric uid
- * @param {string} [m.senderName]
- * @param {string} m.text
- * @returns {string} the JSON string Zalo expects
- */
-export function textPinParams({ cliMsgId, msgId, senderUid, senderName, text }) {
-    return JSON.stringify({
-        client_msg_id: String(cliMsgId),
-        global_msg_id: String(msgId),
-        senderUid: String(senderUid),
-        senderName: senderName || "",
-        title: text,
-        msg_type: 1,
-    });
-}
-
-/** The topic color the server config asks for, else the captured one. */
-function topicColor(ctx) {
-    const color = ctx?.settings?.group?.topic_colors?.[0];
-    return Number.isFinite(color) ? color : DEFAULT_TOPIC_COLOR;
-}
-
-/** A topic's params as an object, whichever form the server sent. */
-function topicParams(topic) {
-    const p = topic?.params;
-    if (p && typeof p === "object") return p;
-    try {
-        return JSON.parse(p || "{}") || {};
-    } catch {
-        return {};
-    }
-}
-
-/**
- * The pinned-message topic that pins `msgId`, from a board listing.
- *
- * @param {Array<object>|undefined} topics
- * @param {string} msgId
- * @returns {object|null}
- */
-export function findPinnedTopic(topics, msgId) {
-    for (const topic of Array.isArray(topics) ? topics : []) {
-        if (Number(topic?.type) !== PINNED_MESSAGE_TOPIC) continue;
-        if (String(topicParams(topic).global_msg_id ?? "") === String(msgId)) return topic;
-    }
-    return null;
-}
-
-/**
- * Pin a text message.
- *
- * @param {object} api - a logged-in zca-js API
- * @param {object} target
- * @param {string} target.threadId
- * @param {boolean} target.isGroup
- * @param {string} target.params - from {@link textPinParams}
- * @returns {Promise<unknown>} the created topic, as Zalo returns it
- */
-export async function pinMessage(api, { threadId, isGroup, params }) {
-    if (isGroup) {
-        return customCall(api, (ctx, utils) =>
-            postWithParams(utils, `${api.zpwServiceMap.group_board[0]}/api/board/topic/createv2`, {
-                grid: String(threadId),
-                type: PINNED_MESSAGE_TOPIC,
-                color: topicColor(ctx),
-                emoji: TEXT_PIN_EMOJI,
-                startTime: -1,
-                duration: -1,
-                params,
-                repeat: 0,
-                src: -1,
-                imei: ctx.imei,
-                pinAct: 1,
-            }),
-        );
-    }
-    const conversationId = String(threadId);
-    const board = await api.getFriendBoardList(conversationId);
-    return customCall(api, (ctx, utils) =>
-        getWithParams(utils, `${api.zpwServiceMap.friend_board[0]}/api/friendboard/create`, {
-            conversationId,
-            topic: {
-                color: topicColor(ctx),
-                duration: -1,
-                emoji: TEXT_PIN_EMOJI,
-                params,
-                repeat: 0,
-                startTime: -1,
-                type: PINNED_MESSAGE_TOPIC,
-                src: -1,
-                pinAct: 1,
-            },
-            version: Number(board?.version) || 0,
-            lang: ctx.language || "vi",
-            imei: ctx.imei,
-        }),
-    );
-}
-
-/** A group's pinned topics and the board version that goes with them. */
-function listGroupPins(api, groupId) {
-    return customCall(api, (ctx, utils) =>
-        getWithParams(utils, `${api.zpwServiceMap.group_board[0]}/api/board/pin/list`, {
-            groupId: String(groupId),
-            boardVersion: 0,
-            imei: ctx.imei,
-        }),
-    );
-}
-
-/**
- * Unpin whatever topic pins `msgId` in a group.
- *
- * @param {object} api
- * @param {string} groupId
- * @param {string} msgId
- * @param {boolean} retry - refetch and retry once on a stale board version
- * @returns {Promise<{topicId?: string, notPinned?: boolean}>}
- */
-async function unpinGroupMessage(api, groupId, msgId, retry) {
-    const board = await listGroupPins(api, groupId);
-    const topic = findPinnedTopic(board?.items ?? board?.topics, msgId);
-    if (!topic) return { notPinned: true };
-    try {
-        await customCall(api, (ctx, utils) =>
-            getWithParams(utils, `${api.zpwServiceMap.group_board[0]}/api/board/unpinv2`, {
-                grid: String(groupId),
-                imei: ctx.imei,
-                topic: { topicId: String(topic.id), topicType: PINNED_MESSAGE_TOPIC },
-                boardVersion: board?.boardVersion ?? 0,
-            }),
-        );
-    } catch (e) {
-        if (retry && Number(e?.code) === INVALID_BOARD_VERSION) return unpinGroupMessage(api, groupId, msgId, false);
-        throw e;
-    }
-    return { topicId: String(topic.id) };
-}
-
-/**
- * Unpin whatever topic pins `msgId` in a 1-1 conversation.
- *
- * @param {object} api
- * @param {string} conversationId - the peer's uid
- * @param {string} msgId
- * @returns {Promise<{topicId?: string, notPinned?: boolean}>}
- */
-async function unpinOneToOneMessage(api, conversationId, msgId) {
-    const board = await api.getFriendBoardList(conversationId);
-    const topic = findPinnedTopic(board?.data, msgId);
-    if (!topic) return { notPinned: true };
-    await customCall(api, (ctx, utils) =>
-        getWithParams(utils, `${api.zpwServiceMap.friend_board[0]}/api/friendboard/multi_unpin`, {
-            conversationId,
-            topics: [{ topicId: String(topic.id), topicType: PINNED_MESSAGE_TOPIC }],
-            version: Number(board?.version) || 0,
-            lang: ctx.language || "vi",
-            imei: ctx.imei,
-        }),
-    );
-    return { topicId: String(topic.id) };
-}
-
-/**
- * Unpin a message.
- *
- * @param {object} api - a logged-in zca-js API
- * @param {object} target
- * @param {string} target.threadId
- * @param {boolean} target.isGroup
- * @param {string} target.msgId
- * @returns {Promise<{topicId?: string, notPinned?: boolean}>} `notPinned` when no topic pins it
- */
-export async function unpinMessage(api, { threadId, isGroup, msgId }) {
-    return isGroup
-        ? unpinGroupMessage(api, String(threadId), String(msgId), true)
-        : unpinOneToOneMessage(api, String(threadId), String(msgId));
-}

package/src/core/socket-tap.js

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