@ardennguyen/zalo-agent-cli 2.5.8 → 3.0.0

package/src/mcp/tool-presence.js

@@ -0,0 +1,153 @@
+/**
+ * Each MCP tool's presence class (on-demand presence, src/core/presence.js and src/core/daemon-presence.js): what a
+ * call does when the account's socket is parked, waking, yielded or signed out. Every tool registerTools registers
+ * must have one (tests/unit/tool-presence.test.js).
+ *
+ *   none     runs at once; the wake runs beside it (sends, lookups, everything that is plain HTTP)
+ *   fresh    reads the local cache: waits up to `presence.warmWait` for the socket and its catch-up, then answers
+ *            anyway, with a `presence` block {state, catchUp, coveredUntil} when it is still warming
+ *   socket   needs the socket itself (a sync stage, an upload): waits up to `presence.warmWait`, then the retryable
+ *            error WARMING with `retryAfterSec`
+ *   wait     a long-poll: holds the socket while it waits (presence.waitHoldsSocket)
+ *
+ * Every class is refused while the account is yielded (YIELDED) or signed out (SIGNED_OUT), except the one call that
+ * ends a yield, zalo_profile `presence_resume`, and zalo_official, which never uses the account's socket.
+ */
+
+/** A file, a video or a voice clip goes up through the socket's upload callbacks; text, links and cards do not. */
+const sendClass = (a) => (a?.filePath || (Array.isArray(a?.files) && a.files.length) || a?.video ? "socket" : "none");
+
+/** Tool name -> class, or a function of the call's arguments. */
+export const TOOL_PRESENCE = Object.freeze({
+    zalo_get_messages: "fresh",
+    zalo_send_message: sendClass,
+    zalo_list_threads: "none",
+    zalo_search_threads: "none",
+    zalo_mark_read: "none",
+    zalo_get_history: "fresh",
+    zalo_view_media: "none",
+    zalo_react: "none",
+    zalo_undo: "none",
+    zalo_get_group_members: "none",
+    zalo_list_conversations: "fresh",
+    zalo_coverage: "fresh",
+    zalo_sync: "socket",
+    zalo_sync_status: "none",
+    zalo_search_messages: "fresh",
+    zalo_lookup_user: "none",
+    zalo_forward_message: "socket",
+    zalo_delete_message: "none",
+    zalo_reminder: "none",
+    zalo_note: "none",
+    zalo_poll: "none",
+    zalo_wait_for_message: "wait",
+    zalo_label: "none",
+    zalo_friend: "none",
+    zalo_group: "none",
+    zalo_read: "none",
+    zalo_write: "none",
+    zalo_conversation: "none",
+    zalo_profile: "none",
+    zalo_auto_reply: "none",
+    zalo_quick_message: "none",
+    zalo_catalog: "none",
+    zalo_bank: "none",
+    zalo_cloud: "none",
+    zalo_sticker: "none",
+    zalo_link: "none",
+    zalo_official: "none",
+});
+
+/**
+ * The calls that skip presence: the one that ends a yield, and zalo_official, which uses the official APIs' own logins
+ * and never the account's socket.
+ */
+const passesRefusal = (tool, args) =>
+    (tool === "zalo_profile" && args?.action === "presence_resume") || tool === "zalo_official";
+
+/**
+ * The class of one call.
+ *
+ * @param {string} tool
+ * @param {object} [args]
+ * @returns {"none"|"fresh"|"socket"|"wait"}
+ */
+export function presenceClassOf(tool, args) {
+    const c = TOOL_PRESENCE[tool];
+    if (typeof c === "function") return c(args);
+    return c ?? "none";
+}
+
+/** An MCP error reply for a refused call: the code first, then the words, as `Error: CODE: …`. */
+function refusalReply(e) {
+    const text =
+        `Error: ${e.code}: ${e.message}` + (e.retryAfterSec !== undefined ? ` (retryAfterSec ${e.retryAfterSec})` : "");
+    return {
+        content: [
+            { type: "text", text },
+            {
+                type: "text",
+                text: JSON.stringify({
+                    error: e.message,
+                    code: e.code,
+                    ...(e.state ? { state: e.state } : {}),
+                    ...(e.retryAfterSec !== undefined ? { retryAfterSec: e.retryAfterSec } : {}),
+                }),
+            },
+        ],
+        isError: true,
+    };
+}
+
+/** Add `presence` to a JSON reply (a warming answer); a reply that is not one JSON object is left as it is. */
+function withPresence(reply, block) {
+    const first = reply?.content?.[0];
+    if (!block || reply?.isError || first?.type !== "text") return reply;
+    try {
+        const body = JSON.parse(first.text);
+        if (!body || typeof body !== "object" || Array.isArray(body)) return reply;
+        return { ...reply, content: [{ ...first, text: JSON.stringify({ ...body, presence: block }) }] };
+    } catch {
+        return reply;
+    }
+}
+
+/**
+ * Wrap one tool's handler in the daemon's presence: refused while yielded or signed out, a hold for the call, and the
+ * warming behavior of its class.
+ *
+ * @param {string} tool
+ * @param {Function} handler - `(args, extra) => reply`
+ * @param {{admit: Function}} daemonPresence - src/core/daemon-presence.js
+ * @returns {Function}
+ */
+export function presenceGatedHandler(tool, handler, daemonPresence) {
+    return async (args, extra) => {
+        if (passesRefusal(tool, args)) return handler(args, extra);
+        const cls = presenceClassOf(tool, args);
+        let ticket;
+        try {
+            ticket = await daemonPresence.admit({ kind: "tool", cls });
+        } catch (e) {
+            if (e?.code) return refusalReply(e);
+            throw e;
+        }
+        try {
+            return withPresence(await handler(args, extra), ticket.warming);
+        } finally {
+            ticket.release();
+        }
+    };
+}
+
+/**
+ * Make every tool registered on `server` from now on go through the daemon's presence.
+ *
+ * @param {{registerTool: Function}} server
+ * @param {object|null} daemonPresence - null: no presence (the tools run as they are)
+ */
+export function gateToolsByPresence(server, daemonPresence) {
+    if (!daemonPresence || typeof server?.registerTool !== "function") return;
+    const raw = server.registerTool.bind(server);
+    server.registerTool = (name, meta, handler) => raw(name, meta, presenceGatedHandler(name, handler, daemonPresence));
+}

package/src/mcp/wait-batch.js

@@ -0,0 +1,27 @@
+/**
+ * The batch settings of a "wait for messages" call (`limit`, `settleMs`), apart from ./wait-result.js so the
+ * message buffer can clamp them without loading the alias book (and through it the account database).
+ */
+
+/** Longest a call waits for company after the first message. */
+export const MAX_SETTLE_MS = 5000;
+
+/**
+ * Clamp the caller's batch settings. No `limit` (or an unusable one) is null: every message already waiting, up to
+ * what the buffer holds (`limits.bufferMaxSize`); a `limit` is a bound with no cap of its own. An unusable
+ * `settleMs` is 0 (no settling).
+ *
+ * @param {{ limit?: unknown, settleMs?: unknown }} [raw]
+ * @returns {{ limit: number|null, settleMs: number }}
+ */
+export function batchParams({ limit, settleMs } = {}) {
+    const l = Number(limit);
+    const s = Number(settleMs);
+    return {
+        limit:
+            limit !== undefined && limit !== null && limit !== "" && Number.isFinite(l) && l >= 1
+                ? Math.floor(l)
+                : null,
+        settleMs: Number.isFinite(s) && s > 0 ? Math.min(MAX_SETTLE_MS, Math.floor(s)) : 0,
+    };
+}

package/src/mcp/wait-result.js

@@ -2,35 +2,33 @@
  * What a "wait for messages" call returns, in one place: the HTTP route `GET /events/wait`, the MCP tool
  * `zalo_wait_for_message` and `mcp wait` over the daemon channel all build it here, so they cannot drift.
  *
- * It used to hand back one message per call, so a bot behind a busy account made one round trip per
- * message. `limit` (1-100, default 1) returns up to that many buffered messages at once, in cursor order,
- * and `settleMs` waits that long after the first arrives so a burst lands in one reply.
+ * A call returns every message already waiting (up to what the buffer holds), in cursor order; `limit`
+ * is an opt-in bound, and `settleMs` waits that long after the first arrives so a burst lands in one reply.
+ * Until 3.0.0 the default was one message per call; a client that read only `message` and continued from
+ * `cursor` now skips every message after the first: read `messages`, or pass `limit` 1.
  *
- * The single-message fields are unchanged and still filled (`message` is the first, `cursor` the last
- * one returned, so `since=cursor` continues exactly where the batch ended); `messages`, `count` and
- * `hasMore` are added. With `limit` 1 the reply is what it always was, plus those three fields.
+ * `message` is the first message returned and `cursor` the last one's, so `since=cursor` continues exactly
+ * where the batch ended; `messages`, `count` and `hasMore` describe the whole batch.
  */
 
-/** Most messages one call returns. */
-export const MAX_BATCH = 100;
-/** Longest a call waits for company after the first message. */
-export const MAX_SETTLE_MS = 5000;
+import { senderNameFields } from "../core/contact-names.js";
 
 /**
- * Clamp the caller's batch settings; anything unusable is the default (one message, no settling).
+ * A buffered message with its sender named as of now: the owner's alias when one is set, else the name the message
+ * carried. The buffer keeps the name from when the message arrived, and an alias set or changed since (a rename while
+ * parked comes back in the same catch-up as the messages, and is read about two seconds after them) would otherwise
+ * show the old name, where Zalo shows the current alias.
  *
- * @param {{ limit?: unknown, settleMs?: unknown }} [raw]
- * @returns {{ limit: number, settleMs: number }}
+ * @param {object} m
+ * @returns {object}
  */
-export function batchParams({ limit, settleMs } = {}) {
-    const l = Number(limit);
-    const s = Number(settleMs);
-    return {
-        limit: Number.isFinite(l) && l >= 1 ? Math.min(MAX_BATCH, Math.floor(l)) : 1,
-        settleMs: Number.isFinite(s) && s > 0 ? Math.min(MAX_SETTLE_MS, Math.floor(s)) : 0,
-    };
+function withCurrentSender(m) {
+    if (!m || m.system || m.senderId === undefined || m.senderId === null) return m;
+    return { ...m, ...senderNameFields(m.senderId, m.senderZaloName ?? m.senderName ?? null) };
 }
 
+export { MAX_SETTLE_MS, batchParams } from "./wait-batch.js";
+
 /**
  * @param {object} args
  * @param {object[]} args.messages - Buffered messages, in cursor order (empty on timeout)
@@ -40,7 +38,7 @@ export function batchParams({ limit, settleMs } = {}) {
  * @returns {{ status: "message"|"timeout", message: object|null, messages: object[], count: number, hasMore: boolean, cursor: number }}
  */
 export function waitResult({ messages, hasMore = false, cursorWhenEmpty, decorate = (m) => m }) {
-    const out = messages.map(decorate);
+    const out = messages.map((m) => decorate(withCurrentSender(m)));
     return {
         status: out.length ? "message" : "timeout",
         message: out[0] ?? null,

package/src/utils/bank-helpers.js

@@ -9,7 +9,10 @@ import { tmpdir } from "os";
 // no need for the `node-fetch` package, which drags in a deprecated
 // node-domexception polyfill via formdata-polyfill/fetch-blob.
 
-/** Bank name aliases (lowercase, no spaces) → BIN codes. */
+/**
+ * Bank name aliases (lowercase, no spaces) → BIN codes. The BINs follow the "Danh sách BIN CODE" appendix of
+ * Zalo's ZBS docs (each short name there resolves here), plus TNEX and Timo.
+ */
 export const BANK_NAME_TO_BIN = {
     abbank: 970425,
     acb: 970416,
@@ -70,6 +73,28 @@ export const BANK_NAME_TO_BIN = {
     vietinbank: 970415,
     ctg: 970415,
     woori: 970457,
+    // From the ZBS BIN appendix
+    cathay: 168999,
+    cathayunited: 168999,
+    citibank: 533948,
+    citi: 533948,
+    liobank: 963369,
+    bnpparibashcm: 963666,
+    bnpparibashn: 963668,
+    lpbank: 970449,
+    lienvietpostbank: 970449,
+    lienviet: 970449,
+    kebhanahcm: 970466,
+    kebhanahn: 970467,
+    hanahcm: 970466,
+    hanahn: 970467,
+    // The appendix's short names for banks already above
+    dbsbank: 796500,
+    indovinabank: 970434,
+    shinhanbank: 970424,
+    unitedoverseas: 970458,
+    vietcapitalbank: 970454,
+    baovietbank: 970438,
 };
 
 /** BIN → display name. */
@@ -130,6 +155,14 @@ export const BIN_TO_DISPLAY = {
     970436: "Vietcombank",
     970415: "VietinBank",
     970457: "Woori",
+    168999: "Cathay United",
+    533948: "Citibank",
+    963369: "Liobank",
+    963666: "BNP Paribas HCM",
+    963668: "BNP Paribas HN",
+    970449: "LPBank",
+    970466: "KEB Hana HCM",
+    970467: "KEB Hana HN",
 };
 
 /** BIN → SePay short_name for qr.sepay.vn URL. */
@@ -236,3 +269,21 @@ export async function generateQrTransferImage(bin, accountNumber, amount = null,
         return null;
     }
 }
+
+/**
+ * The caption `msg send-qr-transfer` puts under its VietQR image: bank and account, then the amount and the note
+ * when given.
+ *
+ * @param {number} bin
+ * @param {{accountNumber: string, amount?: number|null, content?: string|null}} transfer
+ * @returns {string}
+ */
+export function qrTransferCaption(bin, { accountNumber, amount = null, content = null }) {
+    return [
+        `QR chuyển khoản ${BIN_TO_DISPLAY[bin]} - ${accountNumber}`,
+        amount ? `${amount.toLocaleString()}đ` : null,
+        content || null,
+    ]
+        .filter(Boolean)
+        .join(" - ");
+}

package/src/utils/cli-args.js

@@ -1,11 +1,11 @@
 /**
- * Small argument parsers for the commands that wrap a zca-js call taking an
+ * Small argument parsers for the commands that wrap a session call taking an
  * enum or a boolean: typing indicator, report, active status, language.
  *
  * Each throws an Error whose message says what was accepted, so the command's
  * catch block can print it as the usage error. None touches Zalo.
  */
-import { ReportReason, UpdateLangAvailableLanguages } from "zca-js";
+import { REPORT_REASON, UPDATE_LANG } from "../zalo/enums.js";
 
 /**
  * `--type <n>`: 0 = user, 1 = group.
@@ -37,30 +37,30 @@ export function parseOnOff(value, what = "value") {
 }
 
 /**
- * `vi` / `en`, as zca-js's `updateLang` takes them (it sends `VI` / `EN`).
+ * `vi` / `en`, as the session's `updateLang` takes them (it sends `VI` / `EN`).
  *
  * @param {string} value
- * @returns {string} an UpdateLangAvailableLanguages value
+ * @returns {string} an UPDATE_LANG value
  * @throws {Error} for any other language
  */
 export function parseLanguage(value) {
     const key = String(value).trim().toUpperCase();
-    if (key in UpdateLangAvailableLanguages) return UpdateLangAvailableLanguages[key];
-    throw new Error(`language must be one of: ${Object.keys(UpdateLangAvailableLanguages).join(", ").toLowerCase()}`);
+    if (key in UPDATE_LANG) return UPDATE_LANG[key];
+    throw new Error(`language must be one of: ${Object.keys(UPDATE_LANG).join(", ").toLowerCase()}`);
 }
 
 /** The reasons `msg report` accepts, by name. */
 export const REPORT_REASONS = Object.freeze({
-    sensitive: ReportReason.Sensitive,
-    annoy: ReportReason.Annoy,
-    fraud: ReportReason.Fraud,
-    other: ReportReason.Other,
+    sensitive: REPORT_REASON.SENSITIVE,
+    annoy: REPORT_REASON.ANNOY,
+    fraud: REPORT_REASON.FRAUD,
+    other: REPORT_REASON.OTHER,
 });
 
 /**
- * The options object zca-js's `sendReport` takes.
+ * The options object the session's `sendReport` takes.
  *
- * `other` is the only reason that carries text, and zca-js sends it only for
+ * `other` is the only reason that carries text, and the session sends it only for
  * that reason, so a text given with another reason would be dropped without a
  * word: refuse it instead of pretending it was reported.
  *

package/src/utils/date-range.js

@@ -0,0 +1,50 @@
+/**
+ * Date options for search (`--since`, `--until`, `--last`): what a person types, as the epoch milliseconds the cache
+ * is queried with.
+ */
+
+const HOUR = 3_600_000;
+const DAY = 24 * HOUR;
+/** Period units. A month is 30 days and a year 365: a search window, not a calendar. */
+const UNITS = Object.freeze({ h: HOUR, d: DAY, w: 7 * DAY, m: 30 * DAY, y: 365 * DAY });
+
+/**
+ * The start of a period that ends now: `7d`, `2w`, `3m`, `1y`, `12h` (Zalo's own presets are 1 week, 1 month, 3 months).
+ *
+ * @param {string} text
+ * @param {number} [now]
+ * @returns {number} epoch ms
+ * @throws {Error} for anything else
+ */
+export function parsePeriod(text, now = Date.now()) {
+    const m = /^(\d{1,4})\s*([hdwmy])$/i.exec(String(text ?? "").trim());
+    if (!m || Number(m[1]) < 1) throw new Error(`Expected a period like 7d, 2w, 3m or 1y, got "${text}".`);
+    return now - Number(m[1]) * UNITS[m[2].toLowerCase()];
+}
+
+/**
+ * A date as a bound of a search. `2026-10-01` means that whole local day: its first millisecond as a lower bound
+ * (`edge` "start"), its last as an upper one ("end"). A full date and time (`2026-10-01T09:30`, with or without a zone)
+ * is taken as it is.
+ *
+ * @param {string} text
+ * @param {"start"|"end"} edge
+ * @returns {number} epoch ms
+ * @throws {Error} for a date that is not one
+ */
+export function parseDateBound(text, edge) {
+    const s = String(text ?? "").trim();
+    const day = /^(\d{4})-(\d{2})-(\d{2})$/.exec(s);
+    if (day) {
+        const [y, mo, d] = [Number(day[1]), Number(day[2]), Number(day[3])];
+        const start = new Date(y, mo - 1, d);
+        // new Date rolls 2026-02-31 into March: that is not a date the person meant.
+        if (start.getFullYear() !== y || start.getMonth() !== mo - 1 || start.getDate() !== d) {
+            throw new Error(`Not a date: "${text}" (use YYYY-MM-DD).`);
+        }
+        return edge === "end" ? new Date(y, mo - 1, d, 23, 59, 59, 999).getTime() : start.getTime();
+    }
+    const t = Date.parse(s);
+    if (!Number.isFinite(t)) throw new Error(`Not a date: "${text}" (use YYYY-MM-DD or a full date and time).`);
+    return t;
+}

package/src/utils/hidden-access.js

@@ -0,0 +1,141 @@
+/**
+ * Hidden chats on the command line: which threads a command leaves out, and the PIN that lets one command show them.
+ *
+ * The CLI follows its flags, not mcp-config.json: hidden chats are left out unless the command is run with
+ * `--include-hidden`, which asks for the PIN at a prompt that does not echo (src/utils/secret-input.js), or reads it
+ * from standard input with `--pin-stdin`. The PIN is never a command-line argument, never printed, stored or logged;
+ * it is checked against the hash Zalo gave this process (src/core/hidden-chats.js) and dropped. Without a terminal and
+ * without `--pin-stdin` the command does not hang: it prints a "needs PIN" reply and exits 2.
+ */
+
+import { getAccountDir } from "../core/credentials.js";
+import { CONFIRM_EXIT_CODE } from "../core/confirm-guard.js";
+import { hiddenChatsFor, pinFailureLine } from "../core/hidden-chats.js";
+import { promptSecret, readSecretFromStream } from "./secret-input.js";
+import { error } from "./output.js";
+
+/** The exit code of a command that needs the PIN and could not ask for it (as an unconfirmed guarded command). */
+export const PIN_REQUIRED_EXIT_CODE = CONFIRM_EXIT_CODE;
+
+/** The flags every command that can show hidden chats takes. */
+export function addHiddenOptions(command, { include = true } = {}) {
+    if (include) {
+        command.option(
+            "--include-hidden",
+            "Show hidden conversations too: asks for the hidden-chat PIN (never pass it on the command line)",
+        );
+    }
+    command.option("--pin-stdin", "Read the hidden-chat PIN from standard input instead of a prompt");
+    return command;
+}
+
+/**
+ * The account's hidden set for a CLI command: read fresh from Zalo when a session is at hand, else the id mirror the
+ * daemon keeps. Never throws.
+ *
+ * @param {string} ownId
+ * @param {object|null} api - a logged-in session, or null for a cache-only command
+ * @param {{preferMirror?: boolean}} [how] - a cache answer: use the id mirror when there is one, and ask Zalo only
+ *   when there is none yet (the mirror is written by every read of the list, and kept current by the listener)
+ * @returns {Promise<import("../core/hidden-chats.js").HiddenChats>}
+ */
+export async function hiddenSetForCli(ownId, api, { preferMirror = false } = {}) {
+    const set = hiddenChatsFor(ownId, { stateDir: getAccountDir(ownId) });
+    if (preferMirror && set.known) return set;
+    if (api?.getHiddenConversations) {
+        try {
+            await set.refresh(api);
+        } catch (e) {
+            console.error(`[hidden-chats] could not read the hidden conversations: ${e.message}`);
+        }
+    }
+    return set;
+}
+
+/**
+ * Read one PIN: from standard input (`--pin-stdin`, its first line) or a prompt. Returns null when there is no way to
+ * ask (no terminal and no `--pin-stdin`).
+ *
+ * @param {{pinStdin?: boolean, prompt?: string, lines?: string[]|null}} how
+ * @returns {Promise<string|null>}
+ */
+export async function readPin({ pinStdin = false, prompt = "Hidden-chat PIN: ", lines = null } = {}) {
+    if (pinStdin) {
+        if (lines) return lines.shift() ?? "";
+        return (await readSecretFromStream()).split(/\r?\n/)[0].trim();
+    }
+    if (!process.stdin.isTTY) return null;
+    return promptSecret(prompt);
+}
+
+/** The lines of standard input, for a command that reads several PINs (`conv hidden-pin --pin-stdin`). */
+export async function readPinLines() {
+    return (await readSecretFromStream()).split(/\r?\n/).map((l) => l.trim());
+}
+
+/**
+ * Print the "needs PIN" reply and exit 2 (no terminal to ask on and no `--pin-stdin`).
+ *
+ * @param {boolean} json
+ * @param {object} [extra] - fields to add (count, hasPin)
+ */
+export function exitPinRequired(json, extra = {}) {
+    const why =
+        "Not done: this needs the hidden-chat PIN, and there is no terminal to ask on. Pipe it to standard input " +
+        "with --pin-stdin (never pass it as an argument).";
+    if (json)
+        console.log(JSON.stringify({ error: why, pinRequired: true, retryWith: "--pin-stdin", ...extra }, null, 2));
+    else error(why);
+    process.exit(PIN_REQUIRED_EXIT_CODE);
+}
+
+/**
+ * Ask for the PIN and check it; exits on failure (2 when it cannot ask, 1 for a wrong PIN or a lockout).
+ *
+ * @param {import("../core/hidden-chats.js").HiddenChats} set
+ * @param {{pinStdin?: boolean, json?: boolean, extra?: object}} how
+ * @returns {Promise<true>}
+ */
+export async function unlockOrExit(set, { pinStdin = false, json = false, extra = {} } = {}) {
+    if (!set.hasPin) {
+        error(pinFailureLine({ reason: "no-pin" }));
+        process.exit(1);
+    }
+    const locked = set.lockoutStatus();
+    if (locked.retryAfterMs > 0) {
+        error(pinFailureLine({ reason: "locked", ...locked }));
+        process.exit(1);
+    }
+    let pin;
+    try {
+        pin = await readPin({ pinStdin });
+    } catch (e) {
+        error(`Could not read the PIN: ${e.message}`);
+        process.exit(1);
+    }
+    if (pin === null) exitPinRequired(json, extra);
+    const r = set.verifyPin(pin);
+    pin = null;
+    if (!r.ok) {
+        error(pinFailureLine(r));
+        process.exit(1);
+    }
+    return true;
+}
+
+/**
+ * What one command shows: `exclude` unless `--include-hidden` and the PIN checks out (then `include`).
+ *
+ * @param {object} opts - the command's options (`includeHidden`, `pinStdin`)
+ * @param {{ownId: string, api: object|null, json?: boolean}} ctx
+ * @returns {Promise<{set: import("../core/hidden-chats.js").HiddenChats, mode: "exclude"|"include", ids: string[]}>}
+ */
+export async function hiddenAccess(opts, { ownId, api, json = false }) {
+    // Unlocking needs the PIN hash, which only Zalo's answer carries; leaving out needs only the ids.
+    const set = await hiddenSetForCli(ownId, api, { preferMirror: !opts?.includeHidden });
+    if (opts?.includeHidden) {
+        await unlockOrExit(set, { pinStdin: Boolean(opts.pinStdin), json });
+        return { set, mode: "include", ids: [] };
+    }
+    return { set, mode: "exclude", ids: [...set.ids] };
+}

package/src/utils/interrupt.js

@@ -0,0 +1,37 @@
+/**
+ * Let a long run be stopped with Ctrl+C without leaving work half-done.
+ *
+ * The first Ctrl+C asks the run to stop (it aborts the signal the run was given, and the run puts its own
+ * house in order: a restore releases the sessions it opened on the phone). A second Ctrl+C is the way out when
+ * that is stuck, and exits at once with the conventional 130.
+ */
+
+/**
+ * Run `run(signal)` with a SIGINT handler installed for exactly as long as it takes.
+ *
+ * @template T
+ * @param {(signal: AbortSignal) => Promise<T>} run
+ * @param {object} [opts]
+ * @param {() => void} [opts.onStop] called on the first Ctrl+C (say what is happening)
+ * @param {{on: Function, off: Function, exit: (code: number) => void}} [opts.proc] the process, replaceable in a test
+ * @returns {Promise<T>} what `run` resolved to
+ */
+export async function whileInterruptible(run, { onStop = () => {}, proc = process } = {}) {
+    const controller = new AbortController();
+    let presses = 0;
+    const onSigint = () => {
+        presses++;
+        if (presses === 1) {
+            onStop();
+            controller.abort();
+        } else {
+            proc.exit(130);
+        }
+    };
+    proc.on("SIGINT", onSigint);
+    try {
+        return await run(controller.signal);
+    } finally {
+        proc.off("SIGINT", onSigint);
+    }
+}

package/src/utils/json-input.js

@@ -0,0 +1,41 @@
+/**
+ * One way to read a JSON argument or option, for every `oa` and `zbs` command that takes JSON.
+ *
+ * Accepted forms:
+ * - inline JSON: the value starts with `{` or `[`;
+ * - `@path`: the JSON is read from that file;
+ * - anything else is taken as the path of a JSON file.
+ *
+ * A UTF-8 byte-order mark (as some Windows editors save) is dropped before parsing.
+ */
+
+import fs from "node:fs";
+import { resolve } from "node:path";
+
+/**
+ * Read a JSON value given inline, as `@file`, or as a file path.
+ *
+ * @param {string} value - the argument or option as typed
+ * @param {string} [what] - what it is, for the error message (e.g. "template_data", "--data")
+ * @returns {any} the parsed JSON
+ * @throws {Error} when the file cannot be read or the text is not JSON; the message names `what` and the source
+ */
+export function readJsonInput(value, what = "JSON") {
+    const s = String(value ?? "").trim();
+    let text = s;
+    let source = "inline";
+    if (!s.startsWith("{") && !s.startsWith("[")) {
+        const path = s.startsWith("@") ? s.slice(1) : s;
+        try {
+            text = fs.readFileSync(resolve(path), "utf8");
+            source = path;
+        } catch {
+            throw new Error(`${what}: not inline JSON and no such file: ${path}`);
+        }
+    }
+    try {
+        return JSON.parse(text.replace(/^/, ""));
+    } catch (e) {
+        throw new Error(`${what} (${source}) is not valid JSON: ${e.message}`);
+    }
+}