@ardennguyen/zalo-agent-cli 2.5.9 → 3.0.0

package/src/zalo/kernel/atomic-file.js

@@ -0,0 +1,217 @@
+/**
+ * Two small guarantees for the files that more than one process shares or that must never be half
+ * written: an atomic replace, and a cross-process lock for read-modify-write.
+ *
+ * `accounts.json` is written by every login, `account` command and name refresh, and a fleet of
+ * daemons refreshes names concurrently. It used to be read, changed in memory and written back with a
+ * plain `writeFileSync`: two writers silently lost each other's change, a reader could see a file
+ * the writer had truncated and not yet filled (and took it for "no accounts"), and a crash mid-write
+ * left JSON that the next `login` replaced with a one-account registry. Credentials had the same
+ * truncate-then-write window, plus a moment at default permissions before `chmod`.
+ *
+ *  - {@link writeFileAtomic}: write a temp file beside the target, flush it, rename it over the
+ *    target. A reader sees the old file or the new one, never a mix; a crash leaves the old one.
+ *  - {@link withFileLock}: `O_EXCL` lock file with the holder's pid; a lock whose holder died, or that
+ *    is older than any real critical section, is taken over.
+ *
+ * Both are synchronous because their callers are (the registry API is sync throughout).
+ */
+
+import {
+    closeSync,
+    fsyncSync,
+    mkdirSync,
+    openSync,
+    readdirSync,
+    readFileSync,
+    renameSync,
+    statSync,
+    unlinkSync,
+    writeSync,
+} from "node:fs";
+import { randomBytes } from "node:crypto";
+import { basename, dirname, join } from "node:path";
+
+/** Errors a rename can raise on Windows while another process has the target open for reading. */
+const TRANSIENT = new Set(["EPERM", "EBUSY", "EACCES"]);
+
+/**
+ * How long a rename keeps being retried before the error is surfaced (antivirus and indexers can hold a file for a
+ * moment). Kept under the 3 s a registry name refresh waits for the lock: a write that retries inside the lock for
+ * longer than that makes every other writer give up.
+ */
+const RENAME_RETRY_MS = 2000;
+
+/**
+ * Block this thread for `ms` without spinning.
+ * @param {number} ms
+ */
+export function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/**
+ * Replace `file` with `data` so no reader and no crash ever sees a partial write.
+ *
+ * The temp file is created exclusively with `mode` (so a secret is never readable by others, not
+ * even briefly), flushed to disk, then renamed over the target. On Windows a rename can fail while a
+ * reader (or an antivirus scan) has the target open, so it is retried with a growing pause for up to
+ * two seconds (a reader holds the file for microseconds, but a tight loop of them can keep one in the way).
+ *
+ * @param {string} file
+ * @param {string|Buffer} data
+ * @param {{ mode?: number, durable?: boolean }} [options] - `mode`: file mode of the result (default 0o600).
+ *   `durable: false` skips the flush to disk for a copy that is only a convenience (the registry's `.bak`)
+ */
+export function writeFileAtomic(file, data, { mode = 0o600, durable = true } = {}) {
+    mkdirSync(dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+    const fd = openSync(tmp, "wx", mode);
+    try {
+        writeSync(fd, data);
+        if (durable) fsyncSync(fd);
+    } catch (e) {
+        closeSync(fd);
+        try {
+            unlinkSync(tmp);
+        } catch {
+            /* nothing to clean */
+        }
+        throw e;
+    }
+    closeSync(fd);
+
+    const giveUpAt = Date.now() + RENAME_RETRY_MS;
+    for (let attempt = 0; ; attempt++) {
+        try {
+            renameSync(tmp, file);
+            return;
+        } catch (e) {
+            if (!TRANSIENT.has(e.code) || Date.now() >= giveUpAt) {
+                try {
+                    unlinkSync(tmp);
+                } catch {
+                    /* already gone */
+                }
+                throw e;
+            }
+            sleepSync(Math.min(250, 10 * 2 ** Math.min(attempt, 5)) + Math.floor(Math.random() * 40));
+        }
+    }
+}
+
+/**
+ * Delete the temp files that `writeFileAtomic(file, ...)` left when its process was killed between
+ * creating the temp file and renaming it. Only a temp file whose pid is dead is removed.
+ *
+ * @param {string} file - The target the temp files belong to
+ * @returns {number} How many were removed
+ */
+export function sweepStaleTemps(file) {
+    const prefix = `${basename(file)}.`;
+    let removed = 0;
+    try {
+        for (const name of readdirSync(dirname(file))) {
+            const m = name.startsWith(prefix) && /^(\d+)\.[0-9a-f]{8}\.tmp$/.exec(name.slice(prefix.length));
+            if (!m || alive(Number(m[1]))) continue;
+            try {
+                unlinkSync(join(dirname(file), name));
+                removed++;
+            } catch {
+                /* gone already */
+            }
+        }
+    } catch {
+        /* directory unreadable: nothing to sweep */
+    }
+    return removed;
+}
+
+/** @param {number} pid */
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    } catch (e) {
+        // EPERM: it exists, owned by someone else.
+        return e.code === "EPERM";
+    }
+}
+
+/**
+ * Run `fn` while holding an exclusive lock on `lockPath`.
+ *
+ * A held lock is waited for, up to `timeoutMs`. It is taken over when its holder is dead or when it
+ * is older than `staleMs` (a read-modify-write of a small file takes milliseconds, so anything older
+ * is a crashed holder, or a pid the OS reused). The lock is released when `fn` returns or throws.
+ *
+ * @template T
+ * @param {string} lockPath
+ * @param {() => T} fn
+ * @param {{ timeoutMs?: number, staleMs?: number }} [options]
+ * @returns {T}
+ */
+export function withFileLock(lockPath, fn, { timeoutMs = 10_000, staleMs = 30_000 } = {}) {
+    mkdirSync(dirname(lockPath), { recursive: true });
+    const started = Date.now();
+    const mine = JSON.stringify({ pid: process.pid, at: Date.now() });
+
+    for (;;) {
+        try {
+            const fd = openSync(lockPath, "wx", 0o600);
+            try {
+                writeSync(fd, mine);
+            } finally {
+                closeSync(fd);
+            }
+            break;
+        } catch (e) {
+            if (e.code !== "EEXIST" && !(process.platform === "win32" && TRANSIENT.has(e.code))) throw e;
+        }
+
+        // Held. Is the holder gone?
+        let seen = null;
+        let holder = null;
+        try {
+            seen = readFileSync(lockPath, "utf8");
+            holder = JSON.parse(seen)?.pid ?? null;
+        } catch {
+            /* released meanwhile, or torn: judged by age below */
+        }
+        let age = 0;
+        try {
+            age = Date.now() - statSync(lockPath).mtimeMs;
+        } catch {
+            continue; // released between the two looks: try to take it
+        }
+        if ((holder !== null && !alive(holder)) || age > staleMs) {
+            try {
+                // Only remove what was judged stale: a lock freed and retaken meanwhile is a live one.
+                if (readFileSync(lockPath, "utf8") === seen) unlinkSync(lockPath);
+            } catch {
+                /* someone else got there first */
+            }
+            continue;
+        }
+
+        if (Date.now() - started > timeoutMs) {
+            throw new Error(
+                `could not lock ${lockPath} within ${Math.round(timeoutMs / 1000)}s: held by pid ${holder ?? "unknown"}. ` +
+                    "If that process is gone, delete the lock file.",
+            );
+        }
+        // Short polls: a critical section is a few milliseconds, so a long wait leaves the lock idle.
+        sleepSync(2 + Math.floor(Math.random() * 8));
+    }
+
+    try {
+        return fn();
+    } finally {
+        try {
+            // Never remove a lock another process took over while this one was stuck.
+            if (readFileSync(lockPath, "utf8") === mine) unlinkSync(lockPath);
+        } catch {
+            /* already gone */
+        }
+    }
+}

package/src/zalo/kernel/bound.js

@@ -0,0 +1,46 @@
+/**
+ * The four helpers the engine's own hand-built calls use, bound to one session: build a URL, seal params, send a
+ * request, decode the reply. A drop-in for what those calls took from the previous engine's `apiFactory` (spec-kernel 9), so
+ * each caller changes one line.
+ *
+ * The session must be logged in (have its key): a session without one is refused with a plain "not logged in"
+ * error, which never carries the context (the previous engine put the whole context, imei and cookies included, into its text).
+ */
+import { openSession } from "./cipher.js";
+import { buildUrl, decodeReply, httpRequest, sealParams } from "./http.js";
+
+/**
+ * @typedef {object} BoundUtils
+ * @property {(base: string, params?: Record<string, unknown>) => string} makeURL - adds `zpw_ver`/`zpw_type` first
+ * @property {(text: string) => string} encodeAES - seals text with the session key
+ * @property {(data: string) => string|null} decodeAES - opens what the session key sealed
+ * @property {(url: string, init?: object) => Promise<Response>} request - the session's transport; no timeout
+ *   unless `init.timeoutMs` says so; a caller's `redirect: "manual"` has the redirects followed here, hop by hop
+ * @property {(res: Response, cb?: Function, isEncrypted?: boolean) => Promise<any>} resolve - the reply's data
+ */
+
+/**
+ * The helpers of one logged-in session.
+ *
+ * @param {{getContext: () => object}} api
+ * @returns {BoundUtils}
+ * @throws {Error} "Not logged in" when the session has no key
+ */
+export function boundUtils(api) {
+    const ctx = api?.getContext?.();
+    if (!ctx?.secretKey) throw new Error("Not logged in. Run: zalo-agent login");
+    return {
+        makeURL: (base, params = {}) => buildUrl(ctx, base, params),
+        encodeAES: (text) => sealParams(ctx, text),
+        decodeAES: (data) => openSession(ctx.secretKey, data),
+        request: (url, init = {}) => {
+            const { redirect, ...rest } = init;
+            const follow = rest.follow ?? (redirect === "manual" ? "jar" : "auto");
+            return httpRequest(ctx, url, { timeoutMs: 0, ...rest, follow });
+        },
+        resolve: async (res, cb, isEncrypted = true) => {
+            const data = await decodeReply(ctx, res, { encrypted: isEncrypted !== false });
+            return cb ? cb({ data, error: null }) : data;
+        },
+    };
+}

package/src/zalo/kernel/cipher.js

@@ -0,0 +1,88 @@
+/**
+ * The session cipher: how every request's `params` is sealed and every reply's `data` is opened once a login
+ * has handed out its key (`zpw_enk`).
+ *
+ * Wire facts (spec-kernel 10.2): the key is the base64-decoded `zpw_enk`
+ * (16 bytes, so AES-128); AES in CBC mode with an IV of 16 zero bytes and PKCS#7 padding; the plaintext is the
+ * caller's UTF-8 text (a JSON string); the ciphertext travels as standard base64 (`+`, `/`, `=`), and the URL or
+ * form encoder escapes it. Opening first undoes any URL escaping (`decodeURIComponent`), then reverses the rest.
+ *
+ * The kickout lookup's answer is sealed the same way under another key (`auth_ext_info.enk`), so both helpers take
+ * the key as an argument rather than reading a session.
+ *
+ * Nothing here retries: the cipher is deterministic, a second try gives the same answer.
+ */
+import { createCipheriv, createDecipheriv, createHash, randomUUID } from "node:crypto";
+
+/** A zero IV, as Zalo's session cipher uses. */
+const ZERO_IV = Buffer.alloc(16);
+
+/** The AES variant for a raw key of this many bytes. */
+const AES_BY_LENGTH = new Map([
+    [16, "aes-128-cbc"],
+    [24, "aes-192-cbc"],
+    [32, "aes-256-cbc"],
+]);
+
+/** UTF-8 that refuses malformed input, so a wrong key reads as a failure instead of as garbage text. */
+const STRICT_UTF8 = new TextDecoder("utf-8", { fatal: true });
+
+/**
+ * The algorithm and raw bytes of a base64 session key.
+ *
+ * @param {string} key - base64, as Zalo hands it out
+ * @returns {{algorithm: string, bytes: Buffer}|null} null for a key of no AES length
+ */
+function sessionKey(key) {
+    if (typeof key !== "string" || key === "") return null;
+    const bytes = Buffer.from(key, "base64");
+    const algorithm = AES_BY_LENGTH.get(bytes.length);
+    return algorithm ? { algorithm, bytes } : null;
+}
+
+/**
+ * Seal text with a session key.
+ *
+ * @param {string} key - the base64 key (`zpw_enk`, or the kickout `enk`)
+ * @param {string} text - usually `JSON.stringify(params)`
+ * @returns {string|null} standard base64, or null when the key is not a usable AES key
+ */
+export function sealSession(key, text) {
+    const k = sessionKey(key);
+    if (!k || typeof text !== "string") return null;
+    const cipher = createCipheriv(k.algorithm, k.bytes, ZERO_IV);
+    return Buffer.concat([cipher.update(text, "utf8"), cipher.final()]).toString("base64");
+}
+
+/**
+ * Open what {@link sealSession} sealed.
+ *
+ * @param {string} key - the base64 key it was sealed with
+ * @param {string} data - base64, URL-escaped or not
+ * @returns {string|null} the text, or null for any failure (wrong key, bad padding, not base64, not UTF-8)
+ */
+export function openSession(key, data) {
+    const k = sessionKey(key);
+    if (!k || typeof data !== "string" || data === "") return null;
+    try {
+        const raw = Buffer.from(decodeURIComponent(data), "base64");
+        if (raw.length === 0 || raw.length % 16 !== 0) return null;
+        const decipher = createDecipheriv(k.algorithm, k.bytes, ZERO_IV);
+        return STRICT_UTF8.decode(Buffer.concat([decipher.update(raw), decipher.final()]));
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * A new device id (the `imei` every request carries), in the shape Zalo expects: a random UUID, a dash, and the
+ * MD5 of the User-Agent in lowercase hex.
+ *
+ * @param {string} userAgent
+ * @returns {string}
+ */
+export function makeImei(userAgent) {
+    return `${randomUUID()}-${createHash("md5")
+        .update(String(userAgent ?? ""))
+        .digest("hex")}`;
+}

package/src/zalo/kernel/cookies.js

@@ -0,0 +1,125 @@
+/**
+ * The session's cookie jar (spec-kernel 13, option A): tough-cookie's `CookieJar`, so the on-disk format of every
+ * saved login stays exactly what it is (tough-cookie's serialized jar), and cookies follow RFC 6265 the way a
+ * browser's do.
+ *
+ * Credentials exist on disk in three shapes, all of which load:
+ *   - the serialized jar `{version, storeType, ..., cookies: [...]}` (what a login writes back),
+ *   - a bare array of serialized cookies (what the QR login returns),
+ *   - a browser-extension export: `name` instead of `key`, domains with a leading dot.
+ *
+ * Two behaviors differ from the previous engine's jar handling, and both follow the browser (spec-kernel D5, D6):
+ *   - the `Cookie` header is computed for the full request URL (domain and path), not for its origin only;
+ *   - a `Set-Cookie` is stored against the URL of the request that received it, so a cookie with no `Domain`
+ *     attribute is kept as a host-only cookie of that host (the previous engine filed it under host `null` and never sent it).
+ *
+ * Nothing here logs: a cookie value is a credential.
+ */
+import { Cookie, CookieJar } from "tough-cookie";
+
+/** Where a saved cookie with no domain at all is filed (what every saved login was made for). */
+const DEFAULT_COOKIE_HOST = "chat.zalo.me";
+
+/**
+ * An empty jar.
+ *
+ * @returns {CookieJar}
+ */
+export function newJar() {
+    return new CookieJar();
+}
+
+/**
+ * Load a saved jar in any of the three shapes. The input is never modified. An entry that cannot be read is
+ * skipped (one damaged cookie must not cost the whole login).
+ *
+ * @param {object|object[]|null|undefined} saved - `{cookies: [...]}`, a bare array, or nothing
+ * @returns {CookieJar}
+ */
+export function loadJar(saved) {
+    const jar = new CookieJar();
+    const list = Array.isArray(saved) ? saved : Array.isArray(saved?.cookies) ? saved.cookies : [];
+    for (const entry of list) {
+        if (!entry || typeof entry !== "object") continue;
+        const rawDomain = typeof entry.domain === "string" ? entry.domain : "";
+        const dotted = rawDomain.startsWith(".");
+        const domain = dotted ? rawDomain.slice(1) : rawDomain;
+        try {
+            const cookie = Cookie.fromJSON({ ...entry, key: entry.key ?? entry.name, domain: domain || null });
+            if (!cookie || !cookie.key) continue;
+            // A leading dot is the old way of saying "this domain and its subdomains".
+            if (dotted) cookie.hostOnly = false;
+            jar.setCookieSync(cookie, `https://${domain || DEFAULT_COOKIE_HOST}/`);
+        } catch {
+            /* a cookie the jar refuses is skipped, never logged: its value is a credential */
+        }
+    }
+    return jar;
+}
+
+/**
+ * The serialized form of a jar, as saved credentials hold it.
+ *
+ * @param {CookieJar} jar
+ * @returns {{cookies: object[]}} tough-cookie's serialized jar (`cookies` plus its own settings)
+ */
+export function saveJar(jar) {
+    return jar.toJSON();
+}
+
+/**
+ * The `Cookie` header a browser would send to this URL.
+ *
+ * @param {CookieJar|null|undefined} jar
+ * @param {string} url - the full request URL
+ * @returns {string} "" when no cookie applies
+ */
+export function cookieHeader(jar, url) {
+    if (!jar) return "";
+    try {
+        return jar.getCookieStringSync(String(url));
+    } catch {
+        return "";
+    }
+}
+
+/**
+ * The raw `Set-Cookie` values of a response. Uses `getSetCookie()` where the response has it; otherwise splits the
+ * joined header at commas that start a new cookie (never inside an `Expires` date).
+ *
+ * @param {{headers?: {getSetCookie?: Function, get?: Function}}} response
+ * @returns {string[]}
+ */
+export function setCookiesOf(response) {
+    const headers = response?.headers;
+    if (!headers) return [];
+    if (typeof headers.getSetCookie === "function") return headers.getSetCookie();
+    const joined = typeof headers.get === "function" ? headers.get("set-cookie") : null;
+    if (!joined) return [];
+    return String(joined)
+        .split(/,(?=\s*[^;,=\s]+=)/)
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+
+/**
+ * Store every `Set-Cookie` of a response, against the URL the request went to. A cookie the jar refuses (another
+ * site's domain, a public suffix) is dropped, as a browser drops it.
+ *
+ * @param {CookieJar|null|undefined} jar
+ * @param {string} url - the request URL
+ * @param {object} response
+ * @returns {number} how many cookies were stored
+ */
+export function storeSetCookies(jar, url, response) {
+    if (!jar) return 0;
+    let stored = 0;
+    for (const raw of setCookiesOf(response)) {
+        try {
+            if (jar.setCookieSync(raw, String(url))) stored++;
+        } catch {
+            /* refused, as a browser would; never logged */
+        }
+    }
+    return stored;
+}

package/src/zalo/kernel/endpoint.js

@@ -0,0 +1,211 @@
+/**
+ * The table runner: one endpoint definition in, one Zalo call out. Every area module (`src/zalo/api/*.js`) and the
+ * web-call tables (`reads.js`, `writes.js`) describe their calls as data and run them through here.
+ *
+ * An endpoint definition (design 1.2):
+ *
+ * ```
+ * { host, path, cmd,                       // service-map key (or a list, first present wins), path, command id
+ *   method: "get"|"post"|"query"|"multipart",
+ *   paramsFirst: true,                      // GET only: `params` before zpw_ver and zpw_type
+ *   body(args, ctx) -> object|string|null,  // sealed with the session key into `params`
+ *   query(args, ctx) -> object,             // plain query keys after zpw_ver, zpw_type, params (`extraQuery` too)
+ *   file(args) -> {field, filename, type, bytes},   // multipart only
+ *   fields(args) -> object,                 // multipart only: plain form fields before the file
+ *   headers(args) -> object,                // over the transport's defaults
+ *   reply: "session"|"plain",
+ *   okCodes: [n...],                        // inner codes that are an answer, not an error
+ *   emptyOn: {code: value},                 // a code that means "nothing", and what to return for it
+ *   bigIdKeys: [key...],                    // parse the reply losslessly for these keys (json-ids.js)
+ *   timeoutMs,                              // 10 s by default; none for a multipart body
+ *   swapHosts: true,                        // an HTTP 4xx/5xx moves on to the service map's next host,
+ *                                           // once per host the map lists
+ *   transform(data, args, {code, message}) -> value }
+ * ```
+ *
+ * The wire shape: a GET puts `params` in the query (`zpw_ver`, `zpw_type`, `params`, then `query`); a POST sends
+ * `params` as a URL-encoded form; a multipart call puts `params` in the query and the file in the body; `query`
+ * sends the body's keys as a plain, unsealed query.
+ */
+import { ZaloApiError } from "../errors.js";
+import { buildUrl, decodeReply, httpRequest, multipartBody, sealParams } from "./http.js";
+
+/** Where login and settings questions go: Zalo's auth domain. */
+export const AUTH_DOMAIN = "https://wpa.chat.zalo.me";
+
+/** Raised for an unknown name, a missing argument or a host the account lacks, before any request is made. */
+export class CallUsageError extends Error {
+    /** @param {string} message */
+    constructor(message) {
+        super(message);
+        this.name = "CallUsageError";
+    }
+}
+
+/**
+ * The base URL of a service-map key, without a trailing slash.
+ *
+ * @param {Record<string, string|string[]>|null|undefined} serviceMap
+ * @param {string|string[]} key - a key, or keys to try in order (`["group_poll", "group"]`); "auth" is the auth
+ *   domain
+ * @returns {string}
+ * @throws {CallUsageError} naming the key when the map has none of them
+ */
+export function hostOf(serviceMap, key) {
+    const keys = Array.isArray(key) ? key : [key];
+    for (const k of keys) {
+        if (k === "auth") return AUTH_DOMAIN;
+        const v = serviceMap?.[k];
+        const url = Array.isArray(v) ? v[0] : v;
+        if (url) return String(url).replace(/\/+$/, "");
+    }
+    throw new CallUsageError(`this account's service map has no "${keys.join('" or "')}" host`);
+}
+
+/**
+ * Every base URL a service-map key names, in the map's order, without trailing slashes: the hosts to move through
+ * after an HTTP 4xx/5xx. The first present key wins, as in {@link hostOf}.
+ *
+ * @param {Record<string, string|string[]>|null|undefined} serviceMap
+ * @param {string|string[]} key
+ * @returns {string[]} at least one
+ * @throws {CallUsageError} naming the key when the map has none of them
+ */
+export function hostsOf(serviceMap, key) {
+    const keys = Array.isArray(key) ? key : [key];
+    for (const k of keys) {
+        if (k === "auth") return [AUTH_DOMAIN];
+        const v = serviceMap?.[k];
+        const urls = (Array.isArray(v) ? v : [v]).filter(Boolean).map((u) => String(u).replace(/\/+$/, ""));
+        if (urls.length) return [...new Set(urls)];
+    }
+    throw new CallUsageError(`this account's service map has no "${keys.join('" or "')}" host`);
+}
+
+/** Whether an error is an HTTP 4xx/5xx answer (decodeReply's `HTTP <status>`), the case that moves to the next host. */
+function isHttpFailure(e) {
+    const status = Number(e?.status);
+    return e instanceof ZaloApiError && status >= 400 && status < 600;
+}
+
+/**
+ * Build the request of a definition without sending it.
+ *
+ * @param {object} ctx - the session
+ * @param {string} base - the full endpoint URL (host and path), no query
+ * @param {object} def - the definition
+ * @param {object} [args]
+ * @returns {{method: "GET"|"POST", url: string, body?: URLSearchParams|FormData, headers: Record<string, string>,
+ *   json: object|string|null, def: object}} `json` is what was sealed into `params`, before sealing
+ */
+export function buildRequest(ctx, base, def, args = {}) {
+    const body = def.body ? def.body(args, ctx) : null;
+    const headers = def.headers ? def.headers(args) : {};
+    const queryFn = def.query ?? def.extraQuery;
+    const extra = queryFn ? queryFn(args, ctx) : {};
+    const method = def.method ?? "get";
+
+    if (method === "query") {
+        const plain = {};
+        for (const [k, v] of Object.entries(body || {})) plain[k] = String(v);
+        return { method: "GET", url: buildUrl(ctx, base, { ...plain, ...extra }), headers, json: body, def };
+    }
+    if (body === null || body === undefined) {
+        if (method === "post") {
+            return { method: "POST", url: buildUrl(ctx, base, extra), headers, json: null, def };
+        }
+        return { method: "GET", url: buildUrl(ctx, base, extra), headers, json: null, def };
+    }
+    const params = sealParams(ctx, body);
+    if (method === "post") {
+        return {
+            method: "POST",
+            url: buildUrl(ctx, base, extra),
+            body: new URLSearchParams({ params }),
+            headers,
+            json: body,
+            def,
+        };
+    }
+    if (method === "multipart") {
+        if (!def.file) throw new CallUsageError("a multipart endpoint needs a file");
+        const form = multipartBody(def.file(args), def.fields ? def.fields(args) : {});
+        return { method: "POST", url: buildUrl(ctx, base, { params, ...extra }), body: form, headers, json: body, def };
+    }
+    if (def.paramsFirst) {
+        const query = { params, zpw_ver: ctx.API_VERSION, zpw_type: ctx.API_TYPE, ...extra };
+        return { method: "GET", url: buildUrl(ctx, base, query, { version: false }), headers, json: body, def };
+    }
+    return { method: "GET", url: buildUrl(ctx, base, { params, ...extra }), headers, json: body, def };
+}
+
+/** The lossless parser for a definition's `bigIdKeys` (json-ids.js, loaded only when an endpoint asks for it). */
+async function parserFor(def) {
+    if (!def.bigIdKeys?.length) return JSON.parse;
+    let mod;
+    try {
+        mod = await import("./json-ids.js");
+    } catch (e) {
+        throw new ZaloApiError(`bigIdKeys needs src/zalo/kernel/json-ids.js: ${e?.message ?? e}`);
+    }
+    return (text) => JSON.parse(mod.preParse(text, def.bigIdKeys));
+}
+
+/**
+ * Send a built request and decode its reply as its definition says.
+ *
+ * @param {object} ctx - the session
+ * @param {ReturnType<typeof buildRequest>} req
+ * @param {object} [args] - handed to `transform`
+ * @returns {Promise<any>}
+ * @throws {ZaloApiError} Zalo's own error, with its code on `.code`
+ */
+export async function sendRequest(ctx, req, args = {}) {
+    const def = req.def;
+    const init = { method: req.method, headers: req.headers };
+    if (req.body !== undefined) init.body = req.body;
+    init.timeoutMs = def.timeoutMs ?? (def.method === "multipart" ? 0 : undefined);
+    if (init.timeoutMs === undefined) delete init.timeoutMs;
+    const res = await httpRequest(ctx, req.url, init);
+    const reply = await decodeReply(ctx, res, {
+        encrypted: def.reply !== "plain",
+        okCodes: def.okCodes ?? [],
+        emptyOn: def.emptyOn ?? null,
+        parse: await parserFor(def),
+        envelope: true,
+    });
+    return def.transform ? def.transform(reply.data, args, { code: reply.code, message: reply.message }) : reply.data;
+}
+
+/**
+ * Run one endpoint definition.
+ *
+ * @param {{ctx?: object, host?: Function, api?: object}|object} target - a session handle `s` (`s.ctx`, `s.host`)
+ *   or a logged-in api (`getContext()`, `zpwServiceMap`)
+ * @param {object} def - the definition (see the module comment)
+ * @param {object} [args]
+ * @returns {Promise<any>}
+ * @throws {CallUsageError} for a host the account lacks; {@link ZaloApiError} for Zalo's own error
+ */
+export async function callEndpoint(target, def, args = {}) {
+    const ctx = target?.ctx ?? target?.getContext?.();
+    if (!ctx) throw new Error("Not logged in. Run: zalo-agent login");
+    const map = target.zpwServiceMap ?? target.api?.zpwServiceMap ?? ctx.loginInfo?.zpw_service_map_v3;
+    if (def.swapHosts) {
+        const bases = typeof target.hosts === "function" ? target.hosts(def.host) : hostsOf(map, def.host);
+        let last;
+        for (const base of bases) {
+            try {
+                return await sendRequest(ctx, buildRequest(ctx, `${base}${def.path}`, def, args), args);
+            } catch (e) {
+                if (!isHttpFailure(e)) throw e;
+                last = e;
+            }
+        }
+        if (bases.length > 1) last.message = `${last.message} (on each of the ${bases.length} hosts tried)`;
+        throw last;
+    }
+    const base = typeof target.host === "function" ? target.host(def.host) : hostOf(map, def.host);
+    const req = buildRequest(ctx, `${base}${def.path}`, def, args);
+    return sendRequest(ctx, req, args);
+}