@ardennguyen/zalo-agent-cli 1.0.7 → 2.1.0

package/src/core/lock.js

@@ -0,0 +1,129 @@
+/**
+ * src/core/lock.js
+ *
+ * Cross-process locking mechanism for Zalo Agent CLI.
+ * Ensures only one daemon writes to the SQLite database per account.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+const LOCK_FILE_NAME = "daemon.lock";
+
+/**
+ * Checks if a process is running given its PID.
+ * @param {number} pid
+ * @returns {boolean}
+ */
+function isProcessAlive(pid) {
+    try {
+        // process.kill(pid, 0) throws an error if the process does not exist.
+        // It does not actually kill the process.
+        process.kill(pid, 0);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Checks the lock status for a given account directory.
+ * @param {string} accountDir
+ * @returns {{ locked: boolean, pid?: number, stale?: boolean }}
+ */
+export function checkLock(accountDir) {
+    const lockPath = path.join(accountDir, LOCK_FILE_NAME);
+    try {
+        if (!fs.existsSync(lockPath)) {
+            return { locked: false };
+        }
+
+        const pidStr = fs.readFileSync(lockPath, "utf8").trim();
+        const pid = parseInt(pidStr, 10);
+
+        if (Number.isNaN(pid)) {
+            // Corrupted lock file
+            return { locked: false, stale: true };
+        }
+
+        if (isProcessAlive(pid)) {
+            return { locked: true, pid };
+        } else {
+            return { locked: false, stale: true, pid };
+        }
+    } catch {
+        // Handle unexpected read errors
+        return { locked: false };
+    }
+}
+
+/**
+ * Acquires a lock for the given account directory.
+ * @param {string} accountDir
+ * @returns {boolean} True if lock was successfully acquired, false otherwise.
+ */
+export function acquireLock(accountDir) {
+    const lockPath = path.join(accountDir, LOCK_FILE_NAME);
+
+    // Ensure the account directory exists
+    if (!fs.existsSync(accountDir)) {
+        fs.mkdirSync(accountDir, { recursive: true });
+    }
+
+    // Check for existing lock and handle stale locks
+    const status = checkLock(accountDir);
+    if (status.locked) {
+        return false;
+    }
+
+    if (status.stale) {
+        try {
+            // Double-check the pid to prevent race conditions during deletion
+            const currentPidStr = fs.readFileSync(lockPath, "utf8").trim();
+            const currentPid = parseInt(currentPidStr, 10);
+            if (currentPid === status.pid || Number.isNaN(currentPid)) {
+                fs.unlinkSync(lockPath);
+            } else {
+                return false; // Replaced by a different, likely alive process
+            }
+        } catch {
+            // Ignore ENOENT if already deleted by another process trying to acquire lock
+        }
+    }
+
+    try {
+        // 'wx' flag ensures it fails if the file already exists (atomic operation)
+        fs.writeFileSync(lockPath, process.pid.toString(), { flag: "wx" });
+        return true;
+    } catch (e) {
+        if (e.code === "EEXIST") {
+            // Another process created it right after we checked/deleted
+            return false;
+        }
+        throw e; // Other unexpected errors
+    }
+}
+
+/**
+ * Releases the lock for the given account directory.
+ * @param {string} accountDir
+ * @returns {boolean} True if successfully released, false otherwise.
+ */
+export function releaseLock(accountDir) {
+    const lockPath = path.join(accountDir, LOCK_FILE_NAME);
+    try {
+        if (!fs.existsSync(lockPath)) return true;
+
+        const pidStr = fs.readFileSync(lockPath, "utf8").trim();
+        const pid = parseInt(pidStr, 10);
+
+        // Only remove the lock if it belongs to the current process
+        if (pid === process.pid) {
+            fs.unlinkSync(lockPath);
+            return true;
+        }
+        return false; // We don't own this lock
+    } catch (e) {
+        if (e.code === "ENOENT") return true;
+        return false;
+    }
+}

package/src/core/logout.js

@@ -0,0 +1,289 @@
+/**
+ * End a Zalo session at Zalo's servers, the way Zalo Web does.
+ *
+ * Zalo Web's logout is `GET https://wpa.chat.zalo.me/api/login/logOut` (cmd
+ * 11135): the common params plus `{time, client_version, type, imei,
+ * computer_name}` as a PLAIN query string. The web builds it with `_get()`, which
+ * URL-encodes the object as-is — no AES `params=` — and `time` is unix seconds.
+ *
+ * The web also calls `logoutV2` — POST /api/v2/login/logOut on whatever
+ * `getDevDomainV3()` returns, which live is the staging host `stg-wpa` — but only
+ * as an extra step behind a server flag. Our patched zca-js implements that one,
+ * and until 2026-09-30 it was the only call `logout` and `account remove` made.
+ * The session survived it (tier 5). docs/agent-notes.md has how that went
+ * unnoticed; the short version is that "ended" was claimed without looking.
+ *
+ * So "ended" is claimed here only after Zalo rejects a follow-up call —
+ * `fetchAccountInfo`, the same call `whoami` makes — with the session error Zalo
+ * answered right after a proven logout on 2026-09-19. Anything else is reported
+ * as what it is.
+ */
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { existsSync, rmSync } from "node:fs";
+import { CONFIG_DIR, deleteCredentials } from "./credentials.js";
+import { checkLock } from "./lock.js";
+
+const require = createRequire(import.meta.url);
+
+/** Zalo Web's logout endpoint: the auth domain, not a service-map host. */
+export const PRODUCTION_LOGOUT_URL = "https://wpa.chat.zalo.me/api/login/logOut";
+
+/**
+ * Error codes that mean "this session is no longer valid". 600 ("zpw_sek bị
+ * thiếu hoặc không đúng") is what Zalo returned on the first authenticated call
+ * after a proven logout. Only codes actually observed belong here: guessing more
+ * would let an unrelated failure read as proof of logout.
+ */
+const SESSION_REJECTED = new Set([600]);
+
+let _utils = null;
+/** zca-js internals, located the same way ./sync-v2/board.js does. */
+function zcaUtils() {
+    if (_utils) return _utils;
+    _utils = require(join(dirname(require.resolve("zca-js")), "utils.cjs"));
+    return _utils;
+}
+
+/**
+ * Send Zalo Web's production logout.
+ *
+ * @param {object} api - a logged-in zca-js API
+ * @returns {Promise<*>} the response's `data`, decoded if it arrives encrypted
+ * @throws {Error} carrying `.code` when Zalo answers with a non-zero error_code
+ */
+async function productionLogout(api) {
+    const zu = zcaUtils();
+    const call = zu.apiFactory()((_api, ctx, utils) => async () => {
+        const url = utils.makeURL(PRODUCTION_LOGOUT_URL, {
+            time: Math.floor(Date.now() / 1000),
+            client_version: ctx.API_VERSION,
+            type: ctx.API_TYPE,
+            imei: ctx.imei,
+            computer_name: "Web",
+        });
+        const resp = await utils.request(url, { method: "GET" });
+        // Nobody has captured this call's response. logoutV2 answered in plain
+        // JSON, so read it unencrypted; if `data` turns out to be an encrypted
+        // string, decode it and honour an error code inside it.
+        const data = await utils.resolve(resp, undefined, false);
+        if (typeof data !== "string" || !data) return data;
+        let inner;
+        try {
+            inner = JSON.parse(zu.decodeAES(ctx.secretKey, data));
+        } catch {
+            return data; // not an encrypted payload
+        }
+        if (inner?.error_code !== undefined && Number(inner.error_code) !== 0) {
+            throw Object.assign(new Error(inner.error_message || `error_code ${inner.error_code}`), {
+                code: inner.error_code,
+            });
+        }
+        return inner?.data ?? inner;
+    })(api.getContext(), api);
+    return call();
+}
+
+/**
+ * End this session at Zalo's servers.
+ *
+ * The production logout runs FIRST, while the session key is still valid, then
+ * the optional staging `logoutV2` (best-effort), then a `fetchAccountInfo`
+ * probe. Order matters: measured live 2026-09-30, running `logoutV2` first
+ * kills the in-process session key, and the production call then answers
+ * "Invalid Param". Sent first, the production call succeeds ("Successful.").
+ *
+ * What this does NOT do, also measured 2026-09-30: end the login. Both calls
+ * end only this device's session key. The saved login (cookie) still
+ * auto-logs-in on the next command, and the web session stays listed on the
+ * phone as signed in until it is removed from the phone's device list. So the
+ * `logout` command deletes the local credentials on top of this, and points
+ * the user at the phone for a server-side revoke. This helper only reports what
+ * the server calls did; it never claims the login ended.
+ *
+ * @param {object} api - a logged-in zca-js API
+ * @returns {Promise<{
+ *   v2: {ok: boolean, error?: string},
+ *   production: {ok: boolean, error?: string, code?: number|null},
+ *   verdict: "ended"|"still-answers"|"unverified",
+ *   probeError?: string,
+ * }>}
+ */
+export async function serverLogout(api) {
+    const result = { v2: null, production: null, verdict: "unverified" };
+
+    try {
+        await productionLogout(api);
+        result.production = { ok: true };
+    } catch (e) {
+        result.production = { ok: false, error: e.message, code: e.code ?? null };
+    }
+
+    if (typeof api.logoutV2 === "function") {
+        try {
+            await api.logoutV2();
+            result.v2 = { ok: true };
+        } catch (e) {
+            result.v2 = { ok: false, error: e.message };
+        }
+    } else {
+        result.v2 = { ok: false, error: "logoutV2 is not available (unpatched zca-js)" };
+    }
+
+    // The probe is expected to fail after a working logout, and zca-js logs
+    // that failure with a raw stack trace (measured 2026-09-30: an empty reply,
+    // "Failed to parse response data", every time). Its logger reads
+    // ctx.options.logging on each call, so silence it for this call only.
+    const options = typeof api.getContext === "function" ? api.getContext()?.options : null;
+    const logging = options?.logging;
+    if (options) options.logging = false;
+    try {
+        await api.fetchAccountInfo();
+        result.verdict = "still-answers";
+    } catch (e) {
+        if (SESSION_REJECTED.has(Number(e?.code))) result.verdict = "ended";
+        else result.probeError = e.message;
+    } finally {
+        if (options) options.logging = logging;
+    }
+
+    return result;
+}
+
+/** zca-js's words for a reply with no body — what the probe got after every successful logout. */
+const EMPTY_REPLY = /Failed to parse response data/;
+
+/**
+ * Delete the local chat cache (zalo.db + WAL/SHM sidecars) and downloaded media
+ * for one account. Mirrors Zalo Web's "Xóa lịch sử trò chuyện khi đăng xuất"
+ * checkbox — a purely local operation there too (a z_cleardata localStorage
+ * flag consumed by the web's own deleteAllData(), no server call), so no
+ * network round trip here either.
+ *
+ * @param {string} ownId
+ * @returns {{dbDeleted: boolean, mediaDeleted: boolean}}
+ */
+export function deleteLocalHistory(ownId) {
+    const accountDir = join(CONFIG_DIR, "accounts", ownId);
+    let dbDeleted = false;
+    let mediaDeleted = false;
+    if (existsSync(accountDir)) {
+        for (const suffix of ["", "-wal", "-shm", "-journal"]) {
+            const p = join(accountDir, `zalo.db${suffix}`);
+            if (existsSync(p)) {
+                rmSync(p, { force: true });
+                dbDeleted = true;
+            }
+        }
+        const mediaDir = join(accountDir, "media");
+        if (existsSync(mediaDir)) {
+            rmSync(mediaDir, { recursive: true, force: true });
+            mediaDeleted = true;
+        }
+    }
+    return { dbDeleted, mediaDeleted };
+}
+
+/**
+ * The PID of the `listen`/`mcp` daemon holding this account's `daemon.lock`, or
+ * null. `logout` checks this before anything else: with a daemon up, the server
+ * logout would end the session that daemon is using, and deleting the
+ * credentials would leave it unable to re-auth.
+ *
+ * @param {string} ownId
+ * @returns {number|null}
+ */
+export function lockHolder(ownId) {
+    const lock = checkLock(join(CONFIG_DIR, "accounts", ownId));
+    return lock.locked ? lock.pid : null;
+}
+
+/**
+ * Whether `logout` needs a live session at all — decided before the entry
+ * point's auto-login. It does not with `--no-remote` (no server call), nor
+ * while a daemon holds the account (logout then refuses, changing nothing).
+ * Measured 2026-09-30: both used to log in first, contacting Zalo for nothing.
+ *
+ * @param {{remote?: boolean}} opts - the `logout` Commander options
+ * @param {{ownId: string}|null} active - the active account, if any
+ * @returns {boolean}
+ */
+export function logoutNeedsSession(opts, active) {
+    if (opts?.remote === false) return false;
+    if (active?.ownId && lockHolder(active.ownId) !== null) return false;
+    return true;
+}
+
+/**
+ * Finish a real (non-purge) logout on this machine: delete the saved
+ * credentials so nothing auto-logs-in, keeping the chat cache unless
+ * `deleteHistory` is set. This is what makes `logout` a logout rather than a
+ * pause — without it the next command logs straight back in from the saved
+ * cookie (measured 2026-09-30).
+ *
+ * Guarded by the account's `daemon.lock`, the same way `removeAccount` guards
+ * the credential delete: pulling credentials out from under a running
+ * `listen`/`mcp` daemon would leave it unable to re-auth after a drop. When a
+ * daemon holds the lock nothing is deleted and `blockedPid` names it.
+ *
+ * @param {string} ownId
+ * @param {{deleteHistory?: boolean}} [opts]
+ * @returns {{blockedPid: number} | {credentialsDeleted: boolean, history: {dbDeleted: boolean, mediaDeleted: boolean}}}
+ */
+export function finishLocalLogout(ownId, { deleteHistory = false } = {}) {
+    const holder = lockHolder(ownId);
+    if (holder !== null) return { blockedPid: holder };
+
+    const history = deleteHistory ? deleteLocalHistory(ownId) : { dbDeleted: false, mediaDeleted: false };
+    const credentialsDeleted = deleteCredentials(ownId);
+    return { credentialsDeleted, history };
+}
+
+/**
+ * What to tell the user about a serverLogout result, one line per fact.
+ *
+ * "Ended" is printed only for a verified end. A session that still answers is a
+ * warning, never a success line — printing success unconditionally is exactly
+ * how the staging-only logout passed for correct.
+ *
+ * @param {Awaited<ReturnType<typeof serverLogout>>} r - serverLogout's result
+ * @returns {{level: "success"|"warning"|"info", text: string}[]}
+ */
+export function describeLogout(r) {
+    const lines = [];
+    if (!r.production.ok) {
+        lines.push({ level: "warning", text: `Zalo's logout call failed: ${r.production.error}` });
+        if (!r.v2.ok) lines.push({ level: "info", text: `The secondary logoutV2 call failed too: ${r.v2.error}` });
+    }
+    if (r.verdict === "ended") {
+        lines.push({
+            level: "success",
+            text: "Zalo ended this session's key — the next call on it was rejected.",
+        });
+    } else if (r.verdict === "still-answers") {
+        lines.push({
+            level: "warning",
+            text: "Zalo accepted the logout, but this session still answers — it may still be valid at Zalo.",
+        });
+    } else if (r.production.ok && EMPTY_REPLY.test(String(r.probeError))) {
+        // Not proof (an empty reply can have other causes), so not a success
+        // line; but it is what every successful logout produced in testing.
+        lines.push({
+            level: "info",
+            text: "Zalo accepted the logout, and the next call on this session came back empty, as it did after every successful logout in testing: this session's key is most likely gone.",
+        });
+    } else {
+        lines.push({ level: "info", text: `Logout sent; could not confirm the session key died: ${r.probeError}` });
+    }
+    return lines;
+}
+
+/**
+ * Print a serverLogout result through the caller's output helpers.
+ *
+ * @param {Awaited<ReturnType<typeof serverLogout>>} r - serverLogout's result
+ * @param {{success: Function, warning: Function, info: Function}} out - src/utils/output.js helpers
+ */
+export function reportLogout(r, out) {
+    for (const { level, text } of describeLogout(r)) out[level](text);
+}

package/src/core/offline-queue.js

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