@ardennguyen/zalo-agent-cli 2.5.8 → 3.0.0

package/src/zalo/api.js

@@ -0,0 +1,117 @@
+/**
+ * The session object the engine uses: every Zalo call by name, the listener, the context.
+ *
+ * `createApi(ctx, serviceMap, wsUrls)` builds a session handle `s` (design 1.2), hands it to every area module's
+ * factory (`src/zalo/api/<area>.js`, each exporting one `<name>Methods(s)` factory), and returns one plain object
+ * with ordinary own properties: `zpwServiceMap`, `listener`, `getContext()`, `getOwnId()`, every method of the area
+ * factories, and the composed `sendMessage(message, threadId, type)`.
+ */
+import { createClientIds } from "./kernel/session.js";
+import { callEndpoint, hostOf, hostsOf } from "./kernel/endpoint.js";
+import { sessionMethods } from "./api/session.js";
+import { messageMethods } from "./api/messages.js";
+import { uploadMethods } from "./api/upload.js";
+import { actionMethods } from "./api/actions.js";
+import { conversationMethods } from "./api/conversations.js";
+import { groupMethods } from "./api/groups.js";
+import { peopleMethods } from "./api/people.js";
+import { profileMethods } from "./api/profile.js";
+import { businessMethods } from "./api/business.js";
+import { boardMethods } from "./api/boards.js";
+import { createListener } from "./listener/listener.js";
+
+/**
+ * @typedef {object} Session
+ * @property {object} ctx - the live context (the same object for the session's life)
+ * @property {(key: string|string[]) => string} host - a service-map base URL, no trailing slash; throws
+ *   `CallUsageError` naming the key when the map lacks it
+ * @property {(key: string|string[]) => string[]} hosts - every base URL the key names, in the map's order
+ * @property {(def: object, args?: object) => Promise<any>} call - run an endpoint definition (kernel/endpoint.js)
+ * @property {() => number} now - the clock
+ * @property {() => number} nextClientId - monotonic client ids: `max(now, last + 1)`
+ * @property {import("./kernel/session.js").UploadRegistry} uploads - `ctx.uploadCallbacks`
+ * @property {object} api - the composed session object
+ */
+
+/** The area modules under ./api/, in the order their factories run. */
+export const AREAS = Object.freeze([
+    { name: "messages", factories: [messageMethods] },
+    { name: "upload", factories: [uploadMethods] },
+    { name: "actions", factories: [actionMethods] },
+    { name: "conversations", factories: [conversationMethods] },
+    { name: "groups", factories: [groupMethods] },
+    { name: "people", factories: [peopleMethods] },
+    { name: "profile", factories: [profileMethods] },
+    { name: "business", factories: [businessMethods] },
+    { name: "boards", factories: [boardMethods] },
+]);
+
+/** Names the session object defines itself; no area may define them. */
+const RESERVED = new Set(["zpwServiceMap", "listener", "getContext", "getOwnId", "sendMessage"]);
+
+/**
+ * Build the session object.
+ *
+ * @param {object} ctx - a logged-in context (kernel/session.js)
+ * @param {Record<string, string[]>} serviceMap - the login's `zpw_service_map_v3`
+ * @param {string[]} wsUrls - the login's `zpw_ws`
+ * @param {object} [opts]
+ * @param {() => number} [opts.now] - the clock
+ * @param {Array<{name: string, factories: Function[]}>} [opts.areas] - the area modules (tests); {@link AREAS}
+ *   otherwise
+ * @param {(ctx: object, wsUrls: string[]) => object} [opts.createListener] - the listener's builder (tests); ours
+ *   (./listener/listener.js) otherwise
+ * @returns {object}
+ * @throws {Error} when two area modules define one name, or an area defines a reserved one
+ */
+export function createApi(ctx, serviceMap, wsUrls, opts = {}) {
+    const now = opts.now ?? Date.now;
+    const areas = opts.areas ?? AREAS;
+    const buildListener = opts.createListener ?? createListener;
+
+    const api = {};
+    /** @type {Session} */
+    const s = {
+        ctx,
+        host: (key) => hostOf(api.zpwServiceMap ?? serviceMap, key),
+        hosts: (key) => hostsOf(api.zpwServiceMap ?? serviceMap, key),
+        call: (def, args) => callEndpoint(s, def, args),
+        now,
+        nextClientId: createClientIds(now),
+        uploads: ctx.uploadCallbacks,
+        api,
+    };
+
+    api.zpwServiceMap = serviceMap;
+    api.getContext = () => ctx;
+    api.getOwnId = () => String(ctx.uid);
+    const defined = new Set();
+    for (const area of [{ name: "session", factories: [sessionMethods] }, ...areas]) {
+        for (const factory of area.factories) {
+            for (const [name, fn] of Object.entries(factory(s))) {
+                if (RESERVED.has(name)) throw new Error(`${name} is the session's own; area ${area.name} redefines it`);
+                if (defined.has(name)) throw new Error(`${name} is defined by two area modules`);
+                defined.add(name);
+                api[name] = fn;
+            }
+        }
+    }
+
+    /**
+     * Send a message: with attachments it goes up as files (the text, if any, as their caption), any other as text.
+     *
+     * @param {string|{msg?: string, attachments?: string|string[], quote?: object, mentions?: object[],
+     *   styles?: object[], urgency?: number, ttl?: number}} message - text, or text with its options
+     * @param {string} threadId - the user or group id
+     * @param {0|1} [type] - 0 user (default), 1 group
+     * @returns {Promise<{message: object|null, attachment: object[]}>}
+     */
+    api.sendMessage = (message, threadId, type) => {
+        const attachments = message && typeof message === "object" ? message.attachments : undefined;
+        const count = Array.isArray(attachments) ? attachments.length : attachments ? 1 : 0;
+        return count ? api.sendAttachments(message, threadId, type) : api.sendText(message, threadId, type);
+    };
+
+    api.listener = buildListener(ctx, wsUrls);
+    return api;
+}

package/src/zalo/client.js

@@ -0,0 +1,206 @@
+/**
+ * Making a session: the options a session is built with (proxy, image metadata, what is announced), a login from a
+ * saved login, and a QR login.
+ *
+ * The caller keeps the session and the paths: where a login's server settings (`drStoreFor`) and companion-device
+ * identity (`trustStore`) live are the caller's to hand in. The CLI's single-session holder is
+ * src/core/zalo-client.js.
+ */
+
+import fs from "node:fs";
+import { basename } from "node:path";
+import { imageSizeFromFile } from "image-size/fromFile";
+import { HttpsProxyAgent } from "https-proxy-agent";
+import { ProxyAgent, fetch as undiciFetch } from "undici";
+import { API_TYPE, resolveApiVersion } from "./profile.js";
+import { qrLogin } from "./qr-login.js";
+import { loginWithSession } from "./login.js";
+
+/**
+ * Read image dimensions for the session's `imageMetadataGetter`.
+ *
+ * The engine has no image library of its own and asks the caller for this. It
+ * is consumed for the inline-image upload paths —
+ * jpg/jpeg/png/webp via getImageMetaData(), gif via getGifMetaData() — and
+ * the width/height go straight into the upload params the recipient's
+ * client uses to lay the message out.
+ *
+ * Two deliberate choices here:
+ *
+ * 1. **Dimensions come from `image-size`, not hand-rolled header parsing.**
+ *    Zalo restricts only executables (`restricted_ext_file` is exe, cmd,
+ *    bat, …), so a user can hand `send-image` a bmp, tiff, heic or avif.
+ *    Parsing four formats by hand and returning null for the rest turned an
+ *    unusual input into an opaque "Failed to get image metadata". image-size
+ *    is pure JS with zero dependencies and covers ~20 formats.
+ *
+ * 2. **EXIF orientation is applied.** image-size *reports* `orientation` but
+ *    does not act on it. Orientations 5–8 are the 90° rotations, where the
+ *    stored dimensions are transposed relative to how the image displays —
+ *    the common case being a phone photo. Sending stored dimensions there
+ *    makes the recipient's layout box the wrong way round, so they are
+ *    swapped.
+ *
+ * Throws rather than returning null: a falsy return would become a
+ * generic ZaloApiError, which tells the user nothing about which file was
+ * the problem or why.
+ *
+ * @param {string} filePath
+ * @returns {Promise<{width: number, height: number, size: number}>}
+ * @throws {Error} when the file is unreadable or is not a recognized image
+ */
+export async function readImageMetadata(filePath) {
+    const stat = await fs.promises.stat(filePath);
+
+    let dims;
+    try {
+        // Reads incrementally rather than slurping the file, which matters
+        // because Zalo permits attachments up to 1 GB.
+        dims = await imageSizeFromFile(filePath);
+    } catch (e) {
+        throw new Error(
+            `Could not read image dimensions from "${basename(filePath)}": ${e.message}. ` +
+                `Zalo renders jpg/jpeg/png/webp/gif inline; other formats are sent as file attachments.`,
+        );
+    }
+
+    if (!dims || !dims.width || !dims.height) {
+        throw new Error(`Could not read image dimensions from "${basename(filePath)}": no usable size in the header.`);
+    }
+
+    // EXIF orientations 5-8 rotate by 90°, transposing width and height.
+    const transposed = dims.orientation >= 5 && dims.orientation <= 8;
+
+    return {
+        width: transposed ? dims.height : dims.width,
+        height: transposed ? dims.width : dims.height,
+        size: stat.size,
+    };
+}
+
+/**
+ * Create a proxy-aware fetch that uses undici ProxyAgent dispatcher.
+ * Native Node.js fetch ignores the `agent` option — must use `dispatcher`.
+ *
+ * The fetch is undici's own, not the global one: Node bundles its own undici (7.30 in Node 24.22), the package
+ * here is another (8.x), and a dispatcher from one handed to the fetch of the other fails every request with
+ * "invalid onRequestStart method". A proxied account could not log in at all.
+ *
+ * @param {string} proxyUrl
+ * @returns {typeof fetch}
+ */
+export function createProxyFetch(proxyUrl) {
+    const dispatcher = new ProxyAgent(proxyUrl);
+    return (url, init = {}) => undiciFetch(url, { ...init, dispatcher });
+}
+
+/**
+ * The session options a session is built with: what the client announces, whether the session logs, what it delivers,
+ * and the proxy when there is one.
+ *
+ * @param {string|null} proxyUrl
+ * @param {object} [opts]
+ * @param {boolean} [opts.logging=true] - the session's own logging (the CLI turns it off in JSON mode)
+ * @param {object} [opts.env] - where ZALO_API_VERSION is read, `process.env` by default (./profile.js)
+ * @returns {object}
+ * @throws {Error} when the proxy URL is not http:// or https://
+ * @throws {Error} when ZALO_API_VERSION is invalid -- before any request is made
+ */
+export function buildSessionOptions(proxyUrl, { logging = true, env } = {}) {
+    const opts = {
+        // What the client announces, from the protocol profile (./profile.js).
+        // The login builds every URL's zpw_ver and the login calls'
+        // client_version from these.
+        apiType: API_TYPE,
+        apiVersion: env === undefined ? resolveApiVersion() : resolveApiVersion(env),
+        // The session's logging (the protocol layer writes nothing either way)
+        logging,
+        imageMetadataGetter: readImageMetadata,
+        // Deliver our own traffic too. Off would be
+        // right for a bot that would otherwise answer itself, and wrong for a
+        // local cache: without it, everything the owner sends -- from their
+        // phone, from Zalo in a browser, from this CLI -- is dropped before any handler
+        // sees it, so every conversation in zalo.db holds one side of itself.
+        // It also made the new delivery receipts inert, since a receipt updates
+        // the row of a message WE sent and that row was never written.
+        // `listen --no-self` still hides self messages from stdout/webhook/JSONL.
+        selfListen: true,
+    };
+    if (proxyUrl) {
+        // Both agents speak HTTP CONNECT only: a SOCKS URL would fail later with an unclear socket error.
+        const scheme = /^([a-z][a-z0-9+.-]*):\/\//i.exec(String(proxyUrl))?.[1]?.toLowerCase();
+        if (scheme !== "http" && scheme !== "https") {
+            const what = scheme ? `proxy scheme "${scheme}"` : "proxy URL without a scheme";
+            throw new Error(`Unsupported ${what}: use an http:// or https:// proxy URL`);
+        }
+        // HttpsProxyAgent for WebSocket (ws lib), ProxyAgent dispatcher for HTTP fetch
+        opts.agent = new HttpsProxyAgent(proxyUrl);
+        opts.polyfill = createProxyFetch(proxyUrl);
+    }
+    return opts;
+}
+
+/**
+ * Log in with a saved login: the session object, logged in, with its upkeep timers running unless `upkeep` is false.
+ *
+ * @param {object} creds - {imei, cookie, userAgent, language?}
+ * @param {object} opts
+ * @param {object} opts.zaloOptions - from {@link buildSessionOptions}
+ * @param {string|null} [opts.ownId] - the account the login belongs to, when the caller knows it
+ * @param {((ownId: string|null) => object|null)|null} [opts.drStoreFor] - where an account's server settings are
+ *   kept (`createDrStore(<file>)` of ./login.js); the caller owns the path
+ * @param {boolean} [opts.upkeep] - false: no timers (a one-off probe)
+ * @returns {Promise<object>} the session object
+ */
+export function openSession(creds, { zaloOptions, ownId = null, drStoreFor = null, upkeep } = {}) {
+    return loginWithSession(creds, {
+        apiType: zaloOptions.apiType,
+        apiVersion: zaloOptions.apiVersion,
+        zaloOptions,
+        ownId,
+        drStoreFor,
+        ...(upkeep === undefined ? {} : { upkeep }),
+    });
+}
+
+/**
+ * Log in by QR code, Zalo's own QR sequence (./qr-login.js), then open the session it produced.
+ *
+ * @param {object} opts
+ * @param {object} opts.zaloOptions - from {@link buildSessionOptions}
+ * @param {string} opts.userAgent - the browser this client presents (./device-fingerprint.js picks one)
+ * @param {Function|null} [opts.onEvent] - called with every QR event (generated, scanned, declined, expired)
+ * @param {object} opts.trustStore - where the companion-device identity is kept (`createTrustStore` of
+ *   ./trust-store.js)
+ * @param {((ownId: string|null) => object|null)|null} [opts.drStoreFor] - see {@link openSession}
+ * @param {((uid: string) => ({imei: string, userAgent: string}|null))|null} [opts.deviceFor] - the device id already
+ *   used here for an account, to log in with again (see `qrLogin`)
+ * @returns {Promise<object>} the session object
+ */
+export async function openQrSession({
+    zaloOptions,
+    userAgent,
+    onEvent = null,
+    trustStore,
+    drStoreFor = null,
+    deviceFor = null,
+}) {
+    const session = await qrLogin({
+        userAgent,
+        zaloOptions,
+        apiType: zaloOptions.apiType,
+        apiVersion: zaloOptions.apiVersion,
+        onEvent,
+        trustStore,
+        deviceFor,
+    });
+    return loginWithSession(
+        { imei: session.imei, cookie: session.cookies, userAgent: session.userAgent, language: session.language },
+        {
+            apiType: zaloOptions.apiType,
+            apiVersion: zaloOptions.apiVersion,
+            zaloOptions,
+            drStoreFor,
+        },
+    );
+}

package/src/zalo/custom/forward.js

@@ -0,0 +1,199 @@
+/**
+ * Forward a text message the way Zalo does: as a forward, not a copy.
+ *
+ * A forward is the source text plus a `reference` that names the source
+ * message, and a `decorLog` that repeats it. Without them the copy arrives as
+ * plain text with no "forwarded" badge, which is what `msg forward` sent until
+ * this module existed.
+ *
+ * The reference id is derived, not looked up. It is built as
+ *
+ *     id = md5(cliMsgId + senderUid + conversationKey)
+ *
+ * with senderUid the source sender's numeric uid (the own uid when the sender
+ * is held as "0") and conversationKey the conversation id: "g" plus the group
+ * id for a group, the peer's uid for a 1-1, the send2me id for My Documents.
+ * Verified offline: a group-source forward's id is exactly that md5.
+ *
+ * `ts` is the source message's send time -- for any message this client did
+ * not send itself, the server timestamp. `logSrcType` classifies the source
+ * conversation, and the decorLog's `st` IS that logSrcType, so it is 2 for a
+ * group source and 1 for a 1-1.
+ * The previous engine's forwardMessage hardcoded `st: 1`, which is right only for a 1-1
+ * source; that is why the request is sent from here instead.
+ *
+ * Only a first-level forward is built (fwLvl 1, rootMsgRef = the source
+ * itself). Forwarding something that was itself a forward carries the
+ * original root and raises fwLvl; the local cache does not keep a message's
+ * own reference, so that cannot be reproduced.
+ *
+ * A voice or video message is not forwarded this way: it is re-sent by its
+ * hosted URL (`sendVoice` / `sendVideo`). `voiceResendOptions` and
+ * `videoResendOptions` read what those need out of the cached message, so a
+ * video re-send does not ask the CDN for a size the cache already knows (the
+ * HEAD the engine otherwise makes), and a HEAD that is still needed is bounded.
+ * A voice re-send makes no HEAD at all.
+ */
+import { createHash } from "node:crypto";
+import { statSync } from "node:fs";
+import { customCall, postWithParams } from "../session-call.js";
+import { HEAD_TIMEOUT_MS } from "../api/messages.js";
+
+/** A forwarded video with no geometry in its cached params goes out as this (Zalo refuses one without any). */
+export const FORWARD_VIDEO_FALLBACK = Object.freeze({ width: 1280, height: 720 });
+
+/**
+ * A cached attachment's `params`: JSON text on the wire, sometimes already an object.
+ *
+ * @param {object|null} content
+ * @returns {object}
+ */
+function paramsOf(content) {
+    const p = content?.params;
+    if (p && typeof p === "object") return p;
+    if (typeof p !== "string" || !p) return {};
+    try {
+        const parsed = JSON.parse(p);
+        return parsed && typeof parsed === "object" ? parsed : {};
+    } catch {
+        return {};
+    }
+}
+
+/**
+ * The size of a cached attachment, when something already knows it: the size its params give, else the size of the
+ * copy downloaded locally (given as a number by a caller whose copy is encrypted, as a path by one whose copy is
+ * plaintext). Undefined leaves the engine to ask the host.
+ *
+ * @param {unknown} declared
+ * @param {string|number|null|undefined} localPath - a plaintext file's path, or the plaintext size itself
+ * @returns {number|undefined}
+ */
+function knownSize(declared, localPath) {
+    const n = Number(declared);
+    if (Number.isFinite(n) && n > 0) return n;
+    if (typeof localPath === "number") return Number.isFinite(localPath) && localPath > 0 ? localPath : undefined;
+    if (!localPath) return undefined;
+    try {
+        const size = statSync(localPath).size;
+        return size > 0 ? size : undefined;
+    } catch {
+        return undefined;
+    }
+}
+
+/**
+ * The `sendVoice` options that re-send a cached voice message: its URL and the m4a copy Zalo keeps beside it
+ * (`m4aUrl: params.m4a`). No size: none is sent for a voice, so the engine asks the host for nothing.
+ *
+ * @param {object|null} content - the cached message's `content` (`{href, params}`)
+ * @returns {{voiceUrl: string|undefined, m4aUrl?: string}}
+ */
+export function voiceResendOptions(content) {
+    const p = paramsOf(content);
+    return {
+        voiceUrl: content?.href,
+        ...(typeof p.m4a === "string" && p.m4a ? { m4aUrl: p.m4a } : {}),
+    };
+}
+
+/**
+ * The `sendVideo` options that re-send a cached video: URL, thumbnail, duration and geometry from its params (a
+ * missing width or height falls back to {@link FORWARD_VIDEO_FALLBACK}), the size when the cache knows it, and a
+ * bound on the HEAD when it does not.
+ *
+ * @param {object|null} content - the cached message's `content` (`{href, thumb, params}`)
+ * @param {string|number|null} [localPath] - the downloaded copy's path (plaintext), or its plaintext size
+ * @returns {{videoUrl: string|undefined, thumbnailUrl: string, duration: number, width: number, height: number,
+ *   fileSize?: number, timeoutMs: number}}
+ */
+export function videoResendOptions(content, localPath = null) {
+    const p = paramsOf(content);
+    const fileSize = knownSize(p.fileSize ?? p.video_file_size, localPath);
+    return {
+        videoUrl: content?.href,
+        thumbnailUrl: content?.thumb || "",
+        duration: Number(p.duration) || 0,
+        width: Number(p.video_width || p.video_original_width) || FORWARD_VIDEO_FALLBACK.width,
+        height: Number(p.video_height || p.video_original_height) || FORWARD_VIDEO_FALLBACK.height,
+        ...(fileSize !== undefined ? { fileSize } : {}),
+        timeoutMs: HEAD_TIMEOUT_MS,
+    };
+}
+
+/** Zalo's source-conversation kinds for a forward (the `logSrcType` values). */
+export const LOG_SRC_TYPE = Object.freeze({ UNKNOWN: 0, ONE_ONE: 1, GROUP: 2, COMMUNITY: 3, OA: 4, MY_CLOUD: 5 });
+
+/**
+ * The reference and decorLog of a first-level forward.
+ *
+ * @param {object} source
+ * @param {string} source.cliMsgId - the source message's client id
+ * @param {string} source.senderUid - the source sender's numeric uid
+ * @param {string} source.threadId - the source conversation's id
+ * @param {boolean} source.isGroup - whether that conversation is a group
+ * @param {number} source.ts - the source message's send time (server timestamp)
+ * @param {number} [source.logSrcType] - overrides the group/1-1 default (My Documents is 5)
+ * @returns {{reference: object, decorLog: object}}
+ */
+export function buildForwardReference({ cliMsgId, senderUid, threadId, isGroup, ts, logSrcType }) {
+    const kind = logSrcType ?? (isGroup ? LOG_SRC_TYPE.GROUP : LOG_SRC_TYPE.ONE_ONE);
+    const conversationKey = isGroup ? `g${threadId}` : String(threadId);
+    const id = createHash("md5").update(`${cliMsgId}${senderUid}${conversationKey}`).digest("hex");
+    // Key order is the server's, and it matters: every level is serialized to a
+    // JSON string, so the order is part of the bytes Zalo receives.
+    const self = { id, ts, logSrcType: kind };
+    return {
+        reference: { ...self, fwLvl: 1, rootMsgRef: self },
+        decorLog: { fw: { pmsg: { st: kind, ts, id }, rmsg: { st: kind, ts, id }, fwLvl: 1 } },
+    };
+}
+
+/**
+ * Send one mforward request with `reference` and `decorLog` exactly as given.
+ *
+ * Same endpoint and parameter layout as the previous engine's forwardMessage:
+ * `grids[]` for groups, `toIds[]` plus `imei` for 1-1s, the message
+ * info as nested JSON strings. The clientId that went on the wire is stamped
+ * onto the result as `cliMsgId`, as every send of the session does, so the caller can report the {msgId, cliMsgId} pair that
+ * `msg undo` needs.
+ *
+ * @param {object} api - a logged-in session
+ * @param {{message: string, reference: object, decorLog: object, ttl?: number}} payload
+ * @param {string[]} threadIds - the targets, all of one kind
+ * @param {number} type - 0 for users, 1 for groups
+ * @returns {Promise<object>} Zalo's `{success, failed}` plus `cliMsgId`
+ */
+export async function sendForward(api, { message, reference, decorLog, ttl = 0 }, threadIds, type) {
+    const isGroup = Number(type) === 1;
+    const clientId = String(Date.now());
+    const msgInfo = JSON.stringify({
+        message,
+        reference: JSON.stringify({ type: 3, data: JSON.stringify(reference) }),
+    });
+    const decor = JSON.stringify(decorLog);
+    return customCall(api, async (ctx, utils) => {
+        const params = isGroup
+            ? {
+                  grids: threadIds.map((grid) => ({ clientId, grid: String(grid), ttl })),
+                  ttl,
+                  msgType: "1",
+                  totalIds: threadIds.length,
+                  msgInfo,
+                  decorLog: decor,
+              }
+            : {
+                  toIds: threadIds.map((toUid) => ({ clientId, toUid: String(toUid), ttl })),
+                  imei: ctx.imei,
+                  ttl,
+                  msgType: "1",
+                  totalIds: threadIds.length,
+                  msgInfo,
+                  decorLog: decor,
+              };
+        const base = `${api.zpwServiceMap.file[0]}/api/${isGroup ? "group" : "message"}/mforward`;
+        const result = await postWithParams(utils, base, params);
+        if (result && typeof result === "object") result.cliMsgId = clientId;
+        return result;
+    });
+}

package/src/zalo/custom/gid.js

@@ -0,0 +1,123 @@
+/**
+ * Tier-3 conversation-id resolution — the path Zalo uses for peers not in the
+ * local friend/group cache.
+ *
+ * A synced conversation is keyed by an opaque "global noised id". Friends and
+ * current groups are resolved from their lists (both carry `globalId`). Everyone
+ * else — non-friend 1-1s, OA/bot accounts — falls back to Zalo's profile server:
+ *
+ *   GET {profileDomain}/api/gid/decrypt   (cmd 12054)
+ *     params = AES({ globalUids: JSON.stringify([id, …]) })
+ *     -> { <globalNoisedId>: <userId> }
+ *
+ * We then batch `getUserInfo(userIds)` for display names. Left groups have no
+ * per-item endpoint server-side, so they stay unresolved.
+ *
+ * Built on the kernel's bound session helpers (src/zalo/kernel/bound.js), so the
+ * authenticated envelope is the one every session call sends.
+ */
+import { boundUtils } from "../kernel/bound.js";
+import { isRateLimitError, runPacedBatches } from "./user-info.js";
+
+/** A failed `gid/decrypt` batch is asked for twice more, after these pauses, before it counts as failed (Y9). */
+export const GID_RETRY_DELAYS_MS = Object.freeze([500, 1500]);
+
+/**
+ * Run `fn`, and again after each pause while it throws. A rate limit is not retried here: the paced batches back
+ * off for those, and asking again at once would only make it worse.
+ *
+ * @template T
+ * @param {() => Promise<T>} fn
+ * @param {(ms: number) => Promise<void>} [sleep]
+ * @param {readonly number[]} [delays]
+ * @returns {Promise<T>}
+ */
+export async function retrying(
+    fn,
+    sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
+    delays = GID_RETRY_DELAYS_MS,
+) {
+    for (let attempt = 0; ; attempt++) {
+        try {
+            return await fn();
+        } catch (e) {
+            if (isRateLimitError(e) || attempt >= delays.length) throw e;
+            await sleep(delays[attempt]);
+        }
+    }
+}
+
+const GID_BATCH = 50;
+const NAME_BATCH = 100;
+
+/** Build the authenticated `/api/gid/decrypt` caller bound to this session. */
+function makeGidDecrypt(api) {
+    const base = `${api.zpwServiceMap.profile[0]}/api/gid/decrypt`;
+    // Built now, so a session that cannot make the call is refused here, before any batch.
+    const utils = boundUtils(api);
+    const ctx = api.getContext();
+    return async (globalIds) => {
+        const enc = utils.encodeAES(JSON.stringify({ globalUids: JSON.stringify(globalIds), imei: ctx.imei }));
+        const resp = await utils.request(utils.makeURL(base, { params: enc }), { method: "GET" });
+        const result = await utils.resolve(resp);
+        // response shape: resolve() -> { data: { <globalId>: <userId> } } (or the map directly)
+        return result && typeof result.data === "object" ? result.data : result || {};
+    };
+}
+
+/**
+ * Resolve opaque 1-1 global-noised ids to real numeric user ids + names.
+ *
+ * @param {object} api - logged-in session
+ * @param {string[]} globalIds - the 32-char ids (partition without the `oneone/` prefix)
+ * @param {(m: string) => void} [log]
+ * @returns {Promise<Map<string, {id: string, name: string}>>} globalId -> {id, name}
+ */
+export async function resolveNonFriendDms(api, globalIds, log = () => {}) {
+    const out = new Map();
+    if (!globalIds || !globalIds.length) return out;
+
+    // 1. globalId -> userId via /api/gid/decrypt (cmd 12054), batched.
+    let gidDecrypt;
+    try {
+        gidDecrypt = makeGidDecrypt(api);
+    } catch (e) {
+        log(`gid/decrypt unavailable (${e.message}); non-friend 1-1s stay opaque`);
+        return out;
+    }
+    const idToUser = new Map();
+    const decrypted = await runPacedBatches(globalIds, {
+        batchSize: GID_BATCH,
+        label: "gid/decrypt",
+        log,
+        call: (batch) => retrying(() => gidDecrypt(batch)),
+    });
+    for (const map of decrypted.results) {
+        for (const [gid, uid] of Object.entries(map || {})) if (uid) idToUser.set(gid, String(uid));
+    }
+    if (!idToUser.size) return out;
+
+    // 2. userId -> display name via getUserInfo (batched). Best-effort.
+    const names = new Map();
+    const zaloNames = new Map();
+    const uids = [...new Set([...idToUser.values()])];
+    const named = await runPacedBatches(uids, {
+        batchSize: NAME_BATCH,
+        label: "getUserInfo",
+        log,
+        call: (batch) => api.getUserInfo(batch),
+    });
+    for (const info of named.results) {
+        for (const bag of [info?.changed_profiles, info?.unchanged_profiles]) {
+            for (const [uid, p] of Object.entries(bag || {})) {
+                if (!names.has(uid) && p) names.set(uid, p.zaloName || p.displayName || "");
+                if (p?.zaloName) zaloNames.set(uid, p.zaloName);
+            }
+        }
+    }
+    if (named.failed || named.skippedIds) log("some names may be blank (getUserInfo did not answer for every batch)");
+
+    for (const [gid, uid] of idToUser)
+        out.set(gid, { id: uid, name: names.get(uid) || "", zaloName: zaloNames.get(uid) || "" });
+    return out;
+}