@ardennguyen/zalo-agent-cli 2.5.8 → 3.0.0

package/src/zalo/custom/pin.js

@@ -0,0 +1,220 @@
+/**
+ * Pin and unpin a message the way Zalo does.
+ *
+ * The session has no area method for these, so they are custom calls on its
+ * envelope (src/zalo/session-call.js). Each shape is the one the server expects:
+ *
+ *   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
+ * (which also hands back the `boardVersion` unpinv2 needs)
+ * and getFriendBoardList for a 1-1 (which returns the `version`
+ * create and multi_unpin need). A stale group board version is error 183;
+ * Zalo then refetches once and retries, and so does this.
+ *
+ * Only text messages: text is the kind that has been checked, and every other
+ * kind carries its own params blob.
+ */
+import { customCall, getWithParams, postWithParams } from "../session-call.js";
+
+/** A pinned message's board topic type. */
+export const PINNED_MESSAGE_TOPIC = 2;
+
+/** Zalo's error for a group board version that moved on. */
+export const INVALID_BOARD_VERSION = 183;
+
+/** #222222 -- the default `settings.group.topic_colors[0]`. */
+const DEFAULT_TOPIC_COLOR = -14540254;
+
+/** The emoji Zalo gives a pinned text message (`:pushpin:`). */
+const TEXT_PIN_EMOJI = "📌";
+
+/**
+ * The `params` of a text message's pin topic, in the expected 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 session
+ * @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 session
+ * @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/zalo/custom/renewlink.js

@@ -0,0 +1,115 @@
+/**
+ * Refresh an expired media URL — the same call Zalo makes when a photo,
+ * video or file in the timeline has aged past its signed URL.
+ *
+ *   POST {fileDomain}/api/message/renewlink   (cmd 12094)
+ *     params = AES({ toId, msgType, msgInfo, clientId, imei, isGroup })
+ *     msgInfo = JSON({ normalUrl, hdUrl, thumbUrl, oriUrl, isE2EE, isOriginal })
+ *
+ * Zalo media lives in three places, and this covers only the first:
+ *
+ *   1. Zalo's CDN — the `href`/`thumb` in the sync payload. The signature has
+ *      a lifetime tied to the message's age; while the server still holds the
+ *      file, renewlink hands back fresh URLs. That is this module.
+ *   2. zCloud (personal cloud) — a per-message E2EE backup, looked up by msgId.
+ *      See ../zcloud.js.
+ *   3. The sending device itself. No server path exists; the phone's own
+ *      re-upload hints (`fileUrlToRenew`, `video_url_to_renew`) ride along in
+ *      the sync payload and are preserved on the attachment record, but only
+ *      the Zalo mobile client can act on them.
+ *
+ * Built on the kernel's bound session helpers so the authenticated envelope
+ * matches what the file service expects, the same way ./gid.js reaches
+ * /api/gid/decrypt.
+ */
+import { boundUtils } from "../kernel/bound.js";
+
+/**
+ * Zalo strips its internal `jxl` marker before sending a URL back for
+ * renewal. Our URLs come straight off the wire and normally have none, so this
+ * is defensive rather than load-bearing.
+ */
+function removeJxlProtocol(url) {
+    if (typeof url !== "string") return url;
+    return url.replace(/^jxl:\/\//i, "").replace(/\/jxl\//i, "/");
+}
+
+/** Group threads (and the self-chat) take the group form of the request. */
+function isGroupThread(threadType) {
+    return threadType === "group";
+}
+
+/**
+ * Build a renewlink caller bound to this session.
+ *
+ * @param {object} api - logged-in session api
+ * @returns {(req: object) => Promise<object>}
+ */
+export function makeRenewLink(api) {
+    const base = `${api.zpwServiceMap.file[0]}/api/message/renewlink`;
+    const utils = boundUtils(api);
+    const ctx = api.getContext();
+    return async ({ threadId, threadType, msgType, msgInfo, clientId }) => {
+        const info = {
+            ...msgInfo,
+            normalUrl: removeJxlProtocol(msgInfo.normalUrl),
+            hdUrl: removeJxlProtocol(msgInfo.hdUrl),
+            thumbUrl: removeJxlProtocol(msgInfo.thumbUrl),
+            oriUrl: removeJxlProtocol(msgInfo.oriUrl),
+            isE2EE: 0,
+            isOriginal: 0,
+        };
+        for (const k of Object.keys(info)) if (info[k] === undefined) delete info[k];
+
+        const params = {
+            toId: String(threadId),
+            msgType: Number(msgType) || 0,
+            msgInfo: JSON.stringify(info),
+            clientId: String(clientId || Date.now()),
+            imei: ctx.imei,
+            isGroup: isGroupThread(threadType) ? 1 : 0,
+        };
+        const enc = utils.encodeAES(JSON.stringify(params));
+        const resp = await utils.request(utils.makeURL(base), {
+            method: "POST",
+            body: new URLSearchParams({ params: enc }),
+        });
+        return utils.resolve(resp);
+    };
+}
+
+/**
+ * Pull refreshed URLs out of a renewlink response.
+ *
+ * The response envelope is not documented anywhere and Zalo has more than one
+ * shape for "here is the message again", so this reads defensively: it accepts
+ * the URL bag at the top level, under `data`, or nested one level deeper, and
+ * returns null when it finds nothing it recognises rather than guessing.
+ *
+ * @param {object} resp
+ * @returns {{normalUrl?: string, hdUrl?: string, thumbUrl?: string, oriUrl?: string}|null}
+ */
+export function extractRenewedUrls(resp) {
+    const KEYS = ["normalUrl", "hdUrl", "thumbUrl", "oriUrl", "url", "href"];
+    const candidates = [resp, resp?.data, resp?.data?.data, resp?.data?.msgInfo, resp?.msgInfo];
+    for (let c of candidates) {
+        if (typeof c === "string") {
+            try {
+                c = JSON.parse(c);
+            } catch {
+                continue;
+            }
+        }
+        if (!c || typeof c !== "object") continue;
+        const found = {};
+        for (const k of KEYS) if (typeof c[k] === "string" && /^https?:\/\//.test(c[k])) found[k] = c[k];
+        if (Object.keys(found).length) {
+            // `url`/`href` are aliases for the main download link.
+            if (!found.normalUrl && (found.url || found.href)) found.normalUrl = found.url || found.href;
+            delete found.url;
+            delete found.href;
+            return found;
+        }
+    }
+    return null;
+}

package/src/zalo/device-fingerprint.js

@@ -0,0 +1,33 @@
+/**
+ * Picks a randomized, plausible browser User-Agent for the one-time QR login handshake.
+ *
+ * Why this exists: a User-Agent that is byte-identical on every install is a correlatable signal, and Zalo's server
+ * reads the Client Hints that go with it for the "Thiết bị" device label on the phone's QR-confirm screen. Only
+ * the User-Agent is chosen here. The Client Hints of every request (the QR login's and the session's after it) are
+ * derived from it by `src/zalo/headers.js` (`secChUaFor`), so they always match. The legacy QR flow, which needed
+ * the hints handed over as separate fields, was removed in 3.0.0.
+ *
+ * Scope: this only matters for the INITIAL QR-login handshake. Once logged in, the chosen userAgent is persisted
+ * in that account's credentials file (see extractCredentials()/loginWithCredentials() in zalo-client.js) and
+ * reused for every later API call, so a fresh, plausible choice made once here, at first login, is enough. Logging
+ * into the same account again later (after a full logout, not just a session resume) gets a fresh one, as a real
+ * user occasionally updating their browser would.
+ */
+
+import { CHROME_VERSIONS, UA_PLATFORMS, buildUserAgent } from "./profile.js";
+
+/**
+ * Chrome-only presets, built from the protocol profile (src/zalo/profile.js), which owns the Chrome builds and
+ * platforms. Not Firefox or Safari: those send no Client Hints, and Zalo's device label is read from them.
+ * Varying the version and the OS is enough to avoid every install presenting an identical fingerprint.
+ */
+const PRESETS = UA_PLATFORMS.flatMap((platform) => CHROME_VERSIONS.map((v) => buildUserAgent(platform, v)));
+
+/**
+ * Pick a random fingerprint for a fresh QR login.
+ *
+ * @returns {{userAgent: string}}
+ */
+export function generateDeviceFingerprint() {
+    return { userAgent: PRESETS[Math.floor(Math.random() * PRESETS.length)] };
+}

package/src/zalo/download-fetch.js

@@ -0,0 +1,45 @@
+/**
+ * The fetch the restore's batch downloads and the media downloads go through (plan item ZP-01).
+ *
+ * Both used the global `fetch` with no headers at all: undici's default User-Agent, no `Referer`, and, for an account
+ * with a proxy, a direct connection from this machine's own address while the session, the socket and the zCloud calls
+ * went through the proxy. The batch host expects a `User-Agent` and a `Referer`, and the CDN a full browser header set
+ * (no cookie). This is the same fetch with those headers, over the same proxy and the same User-Agent as the
+ * account's session.
+ *
+ * It carries no cookie: neither the batch host nor the CDN is given the session (the batch URL and the media URLs are
+ * signed).
+ */
+import { withBrowserHeaders } from "./headers.js";
+
+/** The `Referer` the download requests carry. */
+export const WEB_REFERER = "https://chat.zalo.me/";
+
+/**
+ * A fetch for downloads, in the account's own identity.
+ *
+ * @param {object|null|undefined} api - a logged-in session; anything without a usable context gets the plain
+ *   global fetch (a unit test's stand-in, a run with no session)
+ * @param {typeof fetch} [fallback] - what to call when the account has no fetch of its own
+ * @returns {typeof fetch}
+ */
+export function createDownloadFetch(api, fallback = (...a) => fetch(...a)) {
+    let ctx = null;
+    try {
+        ctx = typeof api?.getContext === "function" ? api.getContext() : null;
+    } catch {
+        ctx = null;
+    }
+    const userAgent = ctx?.userAgent;
+    if (!userAgent) return fallback;
+    // The account's own fetch: the proxy-aware one when a proxy is configured, the session's default otherwise.
+    const inner = typeof ctx?.options?.polyfill === "function" ? ctx.options.polyfill : fallback;
+    const identified = (input, init = {}) => {
+        const headers = { ...(init.headers ?? {}) };
+        const have = new Set(Object.keys(headers).map((k) => k.toLowerCase()));
+        if (!have.has("user-agent")) headers["user-agent"] = userAgent;
+        if (!have.has("referer")) headers.referer = WEB_REFERER;
+        return inner(input, { ...init, headers });
+    };
+    return withBrowserHeaders(identified, userAgent);
+}

package/src/zalo/enums.js

@@ -0,0 +1,25 @@
+/**
+ * The small number tables the protocol uses, as Zalo sends them (spec-kernel 15). Frozen plain objects: nothing
+ * in the engine indexes them backwards.
+ */
+
+/** A conversation's kind, as every send and read takes it. */
+export const THREAD_TYPE = Object.freeze({ USER: 0, GROUP: 1 });
+
+/** `setMute`'s action. */
+export const MUTE_ACTION = Object.freeze({ MUTE: 1, UNMUTE: 3 });
+
+/** `sendReport`'s reason. */
+export const REPORT_REASON = Object.freeze({ OTHER: 0, SENSITIVE: 1, ANNOY: 2, FRAUD: 3 });
+
+/** The languages `updateLang` accepts, as the strings it sends. */
+export const UPDATE_LANG = Object.freeze({ VI: "VI", EN: "EN" });
+
+/** What the QR login tells its caller, in the order a login goes through them. */
+export const QR_EVENT = Object.freeze({
+    QR_GENERATED: 0,
+    QR_EXPIRED: 1,
+    QR_SCANNED: 2,
+    QR_DECLINED: 3,
+    GOT_LOGIN_INFO: 4,
+});

package/src/zalo/errors.js

@@ -0,0 +1,195 @@
+/**
+ * What Zalo's error numbers mean, in one place (plan item L4).
+ *
+ * Four number spaces meet in a Zalo client, and they used to be handled by
+ * matching words in an error message:
+ *
+ *   - **server codes**: the `error_code` of an HTTP answer or of a socket frame
+ *     (70 maintenance, 600 kicked out, 102 session timeout, ...);
+ *   - **socket error codes**: what the client itself raises about its own
+ *     socket (a missing pong, an auth timeout, ...), numbered 5001 and up;
+ *   - **close codes**: the WebSocket close code (1000 normal, 1006 abnormal,
+ *     3000 and up are Zalo's);
+ *   - **retry keys**: the names under which the server's retry table is keyed.
+ *
+ * Each is a table here, and `classifyServerError` turns a server code into what
+ * the caller should DO about it, so no caller decides from a message again.
+ */
+
+/** Socket error codes the client raises about its own socket. */
+export const SOCKET_ERROR = Object.freeze({
+    KICKOUT: 600,
+    UNKNOWN: 5000,
+    WSS_ERROR: 5001,
+    UNZIP: 5002,
+    INVALID_DATA: 5003,
+    INVALID_CMD: 5004,
+    INVALID_CONFIG: 5005,
+    UNCLEAN_CLOSE: 5006,
+    INVALID_AUTH_DATA: 5007,
+    KEY_INVALID: 5008,
+    DECRYPT_FAILED: 5009,
+    INVALID_GET_OFFLINE: 5010,
+    PING_TIMEOUT: 5011,
+    ESTABLISH_TIMEOUT: 5012,
+    PING_PONG: 5013,
+    OFFLINE_TIMEOUT: 5014,
+    AUTH_TIMEOUT: 5015,
+    ABNORMAL_STOP_PING: 5016,
+    OFFLINE_CTRL_TIMEOUT: 5017,
+    INVALID_GET_CTRL_OFFLINE: 5018,
+    CLOSE_TIMEOUT: 5019,
+    RECONNECT_ESTABLISH_TIMEOUT: 5020,
+});
+
+/** WebSocket close codes: the standard ones and Zalo's own (3000 and up). */
+export const CLOSE_CODE = Object.freeze({
+    NORMAL: 1000,
+    GOING_AWAY: 1001,
+    PROTOCOL_ERROR: 1002,
+    UNSUPPORTED_DATA: 1003,
+    NO_STATUS: 1005,
+    ABNORMAL: 1006,
+    INVALID_PAYLOAD: 1007,
+    POLICY_VIOLATION: 1008,
+    MESSAGE_TOO_BIG: 1009,
+    MANDATORY_EXTENSION: 1010,
+    INTERNAL_ERROR: 1011,
+    SERVER_RESTART: 1012,
+    TRY_AGAIN_LATER: 1013,
+    TLS_HANDSHAKE_FAIL: 1015,
+    NOT_AUTHENTICATED: 3000,
+    READ_MAX_CONNECTION: 3001,
+    NOT_FOUND_WORKER: 3002,
+    KICK_CONNECTION: 3003,
+});
+
+/**
+ * The retry keys. A key is either a number (a close or error code, looked up
+ * as its decimal string in the server's retry table) or a name. The numbers
+ * after the names are what Zalo's own app logs them as.
+ */
+export const RETRY_KEY = Object.freeze({
+    MANUAL: "manual",
+    INTERNAL: "internal", // 5021: a close code 1001-1015
+    INTERVAL_CHECK: "interval_check", // 5022
+    CANNOT_REACH_SERVER: 4001, // a 1006 whose probe worked
+    NO_NETWORK: "no_network", // 5024
+    SWAP_ENDPOINT: 4002, // the endpoint went back to the first one
+    SYSTEM_RESUME: "system_resume", // 5026: the machine woke up
+});
+
+/** The numbers Zalo's own app logs the named retry keys as. */
+export const RETRY_KEY_NUMBER = Object.freeze({
+    internal: 5021,
+    interval_check: 5022,
+    cannot_reach_server: 5023,
+    no_network: 5024,
+    swap_endpoint: 5025,
+    system_resume: 5026,
+});
+
+/**
+ * What the caller should do about a server `error_code`.
+ *
+ * - `maintenance`: Zalo is in maintenance; wait, do not retry on a ladder
+ * - `maintenance-notice`: a maintenance window was announced but has not started
+ * - `kicked`: another session took this account; end, never reconnect
+ * - `session-invalid`: this session is no longer valid; log in again
+ * - `invalid-account`: the account itself is refused; log in again will not help
+ * - `retry`: ask again after a delay
+ * - `encryption-off`: the server turned parameter encryption off; resend unencrypted
+ * - `stop-retry`: the server says stop asking
+ * - `up-to-date`: not an error (the update check's "nothing newer")
+ *
+ * @typedef {"maintenance"|"maintenance-notice"|"kicked"|"session-invalid"|"invalid-account"|"retry"|"encryption-off"|"stop-retry"|"up-to-date"} ErrorKind
+ */
+const SERVER_ERRORS = new Map([
+    [70, { name: "MAINTENANCE", kind: "maintenance" }],
+    // 71 is accepted by the maintenance poller beside 0 and 70. The official
+    // client treats it as maintenance too; what separates it from 70 is not
+    // known, so it is kept apart and polled slowly rather than blocked on.
+    [71, { name: "MAINTENANCE_NOTICE", kind: "maintenance-notice" }],
+    [102, { name: "SESSION_TIMEOUT", kind: "session-invalid" }],
+    [112, { name: "SERVER_STOP", kind: "retry" }],
+    [210, { name: "INVALID_ACCOUNT", kind: "invalid-account" }],
+    [212, { name: "INVALID_ACCOUNT", kind: "invalid-account" }],
+    [600, { name: "KICKED_OUT", kind: "kicked" }],
+    [19000, { name: "ENCRYPTION_DISABLED", kind: "encryption-off" }],
+    [-69, { name: "STOP_RETRY", kind: "stop-retry" }],
+    [1001, { name: "UP_TO_DATE", kind: "up-to-date" }],
+]);
+
+/**
+ * Classify a server `error_code`.
+ *
+ * @param {number|string|null|undefined} code
+ * @returns {{code: number|null, name: string, kind: ErrorKind|"unknown"}}
+ *   `kind` is "unknown" for a code this table does not name: the caller decides,
+ *   and should treat it as an ordinary failure, not as a state
+ */
+export function classifyServerError(code) {
+    const n = typeof code === "string" && code.trim() !== "" ? Number(code) : code;
+    if (typeof n !== "number" || !Number.isFinite(n)) return { code: null, name: "NONE", kind: "unknown" };
+    const known = SERVER_ERRORS.get(n);
+    return known ? { code: n, ...known } : { code: n, name: "UNKNOWN", kind: "unknown" };
+}
+
+/**
+ * The code an error carries, whichever way the library reports it.
+ *
+ * A `ZaloApiError` puts the server's code on `.code`; a hand-built error
+ * may use `.error_code`; a code can also be the only thing a message says.
+ *
+ * @param {unknown} err
+ * @returns {number|null}
+ */
+export function errorCodeOf(err) {
+    if (!err || typeof err !== "object") return null;
+    for (const key of ["code", "error_code", "errorCode"]) {
+        const v = err[key];
+        if (typeof v === "number" && Number.isFinite(v)) return v;
+        if (typeof v === "string" && /^-?\d+$/.test(v.trim())) return Number(v);
+    }
+    return null;
+}
+
+/**
+ * An error Zalo answered (or the transport hit on the way), with Zalo's own `error_code` on `.code`.
+ *
+ * `code` is null when there is none (an HTTP failure, an undecryptable reply); a number is kept as given, 0
+ * included. An HTTP failure also carries `.status`. An error envelope's own `data` is kept on `.data` when it had
+ * one: some answers are read by it (a list's end is an error whose `data` is the string `"[]"`). The message
+ * never holds the session context.
+ */
+export class ZaloApiError extends Error {
+    /**
+     * @param {string} message
+     * @param {number|null} [code]
+     * @param {unknown} [data] - the error envelope's `data`; left off the error when undefined
+     */
+    constructor(message, code = null, data = undefined) {
+        super(message);
+        this.name = "ZaloApiError";
+        this.code = typeof code === "number" || typeof code === "string" ? code : null;
+        if (data !== undefined) this.data = data;
+    }
+}
+
+/** The QR login was abandoned on purpose (the caller's `abort()`). */
+export class QrLoginAborted extends ZaloApiError {
+    /** @param {string} [message] */
+    constructor(message = "Operation aborted") {
+        super(message);
+        this.name = "QrLoginAborted";
+    }
+}
+
+/** The person declined the QR login on their phone. */
+export class QrLoginDeclined extends ZaloApiError {
+    /** @param {string} [message] */
+    constructor(message = "Login QR request declined") {
+        super(message);
+        this.name = "QrLoginDeclined";
+    }
+}