@ardennguyen/zalo-agent-cli 1.0.7 → 2.1.0

package/src/core/forward.js

@@ -0,0 +1,112 @@
+/**
+ * Forward a text message the way Zalo Web 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. The web builds it as
+ *
+ *     id = md5(cliMsgId + senderUid + conversationKey)
+ *
+ * with senderUid the source sender's numeric uid (its own uid when the web
+ * holds the sender as "0") and conversationKey the web's 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 against the 2026-09-29 capture: the captured
+ * group-source forward's id is exactly that md5
+ * (agent/work/zalo-web-capture-2026-09-29/comparison-vs-zca-js.md §5.16).
+ *
+ * `ts` is the source message's send time -- `sendDttm` in the web's message
+ * model, which for any message the web did not send itself is the server
+ * timestamp (`sendDttm: e.ts`). `logSrcType` classifies the source
+ * conversation, and the decorLog's `st` IS that logSrcType (the web maps
+ * st -> logSrcType), so it is 2 for a group source and 1 for a 1-1.
+ * zca-js's forwardMessage hardcodes `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 makes the web carry
+ * the original root and raise fwLvl; the local cache does not keep a message's
+ * own reference, so that cannot be reproduced.
+ */
+import { createHash } from "node:crypto";
+import { customCall, postWithParams } from "./zca-custom.js";
+
+/** Zalo Web's source-conversation kinds for a forward (its `logSrcType` enum). */
+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 web'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 zca-js's forwardMessage (and as the
+ * capture): `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 patches/zca-js+2.2.0.patch does for
+ * forwardMessage, so the caller can report the {msgId, cliMsgId} pair that
+ * `msg undo` needs.
+ *
+ * @param {object} api - a logged-in zca-js API
+ * @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/core/group-history.js

@@ -0,0 +1,248 @@
+/**
+ * Group chat history from Zalo's cloud-message store.
+ *
+ * zca-js's getGroupChatHistory asks `{group}/api/group/history`, which Zalo
+ * answers with HTTP 404. Zalo Web reads a group's history from a different
+ * service -- the cloud-message ("cm") store:
+ *
+ *   GET {group_cloud_message}/api/cm/getrecentv2?nretry=0     (cmd 12506)
+ *   GET {group_cloud_message}/api/cm/getoldv2?nretry=0        (cmd 12507)
+ *       params = AES({groupId, globalMsgId, count, msgIds, imei, src})
+ *
+ * Sources, all under agent/work/zalo-web-capture-2026-09-29/: the web
+ * client's own `getCM` (bundles/1.*.js @11028626), the captures in
+ * live/group.A1-A4.json, comparison-vs-zca-js.md §3e and §5.30, FINDINGS §13.
+ *
+ * What the evidence establishes, and what it does not:
+ *
+ * - The newest page is `getrecentv2` with globalMsgId 2^63 -- Zalo Web's
+ *   MessageConstants.MAX_MSG_ID -- and `src: 1`, as sent when a group is
+ *   opened (FINDINGS §13).
+ * - Older pages follow Zalo Web's own client loop (`getCloudMessage`,
+ *   bundles/1.*.js @6637459): the next globalMsgId is the response's
+ *   `lastMsgId`, the request goes to `getoldv2` only when the response says
+ *   `isOld`, and it carries `src: 3` (LOADMORE) -- the shape of every captured
+ *   scroll-up request. No captured response ever carried messages, `hasMore`
+ *   or `isOld`, so paging is implemented to that specification and is NOT yet
+ *   verified against the live server.
+ * - The response's `data` is a JSON string. Zalo Web quotes bare numbers in
+ *   `uidFrom`, `uidTo`, `uid` and `ownerId` before parsing it (`preParse`),
+ *   because uids run past 2^53. So does this.
+ * - Recall (`chat.undo`) and delete (`chat.delete`) events and rows without
+ *   content are dropped, and rows are de-duplicated on cliMsgId + sender, as
+ *   Zalo Web's `checkDupMessageFromCloud` does.
+ *
+ * `group_cloud_message` is declared in zca-js's own LoginInfo type
+ * (zpw_service_map_v3, dist/context.d.ts). A session whose map lacks it gets a
+ * clear error rather than a request to "undefined".
+ *
+ * Read-only: this module fetches and writes nothing. `msg history` caches what
+ * it returns through storeHistoryMessage (./live-store.js). The listener, sync
+ * and msg history's fetch write Zalo-reported rows; history writes
+ * insert-if-absent; msg send writes nothing (AGENTS.md §13).
+ */
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { GroupMessage } from "zca-js";
+
+const require = createRequire(import.meta.url);
+
+/** Zalo Web's MessageConstants.MAX_MSG_ID, `(BigInt(2) ** BigInt(63)).toString()`: start from the newest. */
+export const NEWEST_MSG_ID = "9223372036854775808";
+
+/**
+ * Messages asked for per request. Zalo Web sends its server-configured
+ * `cloud.countP.WEB`, which was 50 in every capture; nothing else has been seen.
+ */
+export const CM_PAGE_SIZE = 50;
+
+/** Zalo Web's cloud-load `src`: OVERFLOW (opening a conversation) and LOADMORE (scrolling up). */
+const SRC_OPEN = 1;
+const SRC_LOAD_MORE = 3;
+
+/** Pause between pages. Zalo rate-limits hard (see ./sync-v2/board.js). */
+const PAGE_DELAY_MS = 150;
+
+/**
+ * `"uidFrom": 1234…` (or `\"uidFrom\": 1234…` inside an escaped string) with a
+ * bare integer. Group 1 is the escaping; the key must close with the same.
+ */
+const UID_SCALAR = /(\\*)"(uidFrom|uidTo|uid|ownerId)\1"(\s*):(\s*)(-?\d+)(?![\d.eE])/g;
+/** The same keys holding an array of bare integers. */
+const UID_ARRAY = /(\\*)"(uidFrom|uidTo|uid|ownerId)\1"(\s*):(\s*)\[([^[\]{}"]*)\]/g;
+
+let _utils = null;
+/** zca-js internals (apiFactory, makeURL, request, resolve), located as ./sync-v2/gid.js does. */
+function zcaUtils() {
+    if (_utils) return _utils;
+    _utils = require(join(dirname(require.resolve("zca-js")), "utils.cjs"));
+    return _utils;
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * Quote bare integers under `uidFrom`, `uidTo`, `uid` and `ownerId` in a JSON
+ * text, so JSON.parse keeps every digit of a uid past 2^53. The same job as
+ * Zalo Web's `preParse`, which runs over every cloud-message response,
+ * including those keys inside escaped JSON held in a string value.
+ *
+ * @param {string} json
+ * @returns {string}
+ */
+export function quoteUids(json) {
+    return json
+        .replace(UID_SCALAR, (_m, esc, key, s1, s2, num) => `${esc}"${key}${esc}"${s1}:${s2}${esc}"${num}${esc}"`)
+        .replace(
+            UID_ARRAY,
+            (_m, esc, key, s1, s2, items) =>
+                `${esc}"${key}${esc}"${s1}:${s2}[${items.replace(/-?\d+/g, (n) => `${esc}"${n}${esc}"`)}]`,
+        );
+}
+
+/** A msgId as a BigInt, or null when it is not a plain decimal id. */
+function msgIdOf(v) {
+    const s = String(v ?? "");
+    return /^\d+$/.test(s) ? BigInt(s) : null;
+}
+
+/** Newest first: by msgId, which is what the server pages on, then by timestamp. */
+function newestFirst(a, b) {
+    const x = msgIdOf(a.data.msgId);
+    const y = msgIdOf(b.data.msgId);
+    if (x !== null && y !== null && x !== y) return x > y ? -1 : 1;
+    return Number(b.data.ts || 0) - Number(a.data.ts || 0);
+}
+
+/** Zalo Web's `_validCloudMsg`: a real message, not a recall or delete event, with content. */
+function isMessage(data) {
+    return (
+        Boolean(data) &&
+        typeof data === "object" &&
+        data.msgType !== "chat.undo" &&
+        data.msgType !== "chat.delete" &&
+        Boolean(data.content)
+    );
+}
+
+/** getrecentv2's `data`, parsed. It arrives as a JSON string. */
+function parsePage(raw) {
+    if (raw === null || raw === undefined || raw === "") return {};
+    const page = typeof raw === "string" ? JSON.parse(quoteUids(raw)) : raw;
+    return page && typeof page === "object" ? page : {};
+}
+
+/** One request to the cloud-message store. */
+async function fetchPage(api, host, { groupId, globalMsgId, src, old }) {
+    const url = `${host}/api/cm/${old ? "getoldv2" : "getrecentv2"}`;
+    const call = zcaUtils().apiFactory()((_api, ctx, utils) => async () => {
+        // Key order as Zalo Web builds it.
+        const params = { groupId, globalMsgId, count: CM_PAGE_SIZE, msgIds: [], imei: ctx.imei, src };
+        const enc = utils.encodeAES(JSON.stringify(params));
+        if (!enc) throw new Error("failed to encrypt group history params");
+        const resp = await utils.request(utils.makeURL(url, { nretry: 0, params: enc }), { method: "GET" });
+        return utils.resolve(resp);
+    })(api.getContext(), api);
+    return parsePage(await call());
+}
+
+/**
+ * Fetch a group's newest messages from Zalo's cloud-message store.
+ *
+ * A drop-in for zca-js's `getGroupChatHistory(groupId, count)`, whose endpoint
+ * is retired: it resolves to `{groupMsgs, more}` with each message a zca-js
+ * `GroupMessage` (`.data`, `.isSelf`, `.threadId`), so a caller that read the
+ * old call's `groupMsgs` and `more` reads this unchanged.
+ *
+ * @param {object} api - a logged-in zca-js API
+ * @param {string} groupId - numeric group id; a leading "g" is stripped, as Zalo Web does
+ * @param {number} [count=50] - how many of the newest messages to return, a whole number >= 1
+ * @param {object} [opts]
+ * @param {number} [opts.delayMs=150] - pause between pages
+ * @returns {Promise<{groupMsgs: Array<object>, more: 0|1, pages: number, filtered: boolean}>}
+ *   `groupMsgs` newest first; `more` is 1 when older messages can be fetched beyond those
+ *   returned; `pages` is the number of requests made; `filtered` is true when Zalo withheld
+ *   older messages (the page said `isFiltered`) — they exist but this store will not serve
+ *   them, so `more` is 0
+ * @throws {Error} when `count` is not a whole number >= 1, the session has no
+ *   group_cloud_message host, a request fails, or the store reports an error and returns nothing
+ */
+export async function getGroupHistory(api, groupId, count = CM_PAGE_SIZE, { delayMs = PAGE_DELAY_MS } = {}) {
+    if (!Number.isInteger(count) || count < 1) {
+        throw new Error(`count must be a whole number of at least 1, got ${count}`);
+    }
+    const host = api?.zpwServiceMap?.group_cloud_message?.[0];
+    if (!host) {
+        throw new Error(
+            'Zalo did not include the "group_cloud_message" service in this session\'s service map ' +
+                "(zpw_service_map_v3), so group history is unavailable for this login.",
+        );
+    }
+
+    const gid = String(groupId).replace(/^g/, "");
+    const ownId = String(api.getContext().uid ?? "");
+    // Enough for `count`, plus slack for pages thinned out by dropped events.
+    const maxPages = Math.ceil(count / CM_PAGE_SIZE) + 2;
+
+    const kept = [];
+    const seen = new Set();
+    let cursor = NEWEST_MSG_ID;
+    let old = false;
+    let src = SRC_OPEN;
+    let hasMore = false;
+    let filtered = false;
+    let pages = 0;
+
+    while (pages < maxPages) {
+        if (pages > 0 && delayMs) await sleep(delayMs);
+        const page = await fetchPage(api, host, { groupId: gid, globalMsgId: cursor, src, old });
+        pages++;
+
+        const rows = Array.isArray(page.groupMsgs) ? page.groupMsgs : [];
+        if (page.error && !rows.length) {
+            if (!kept.length) throw new Error(`Zalo's group message store answered error ${page.error}`);
+            hasMore = true; // an older page failed; do not claim the history ends here
+            break;
+        }
+
+        for (const data of rows) {
+            if (!isMessage(data)) continue;
+            // Keyed before GroupMessage rewrites a self uidFrom of "0".
+            const byId = `m:${data.msgId}`;
+            const byClient = `c:${data.cliMsgId}_${data.uidFrom}`;
+            if (seen.has(byId) || seen.has(byClient)) continue;
+            seen.add(byId);
+            seen.add(byClient);
+
+            const msg = new GroupMessage(ownId, data);
+            // Zalo marks our own messages with uidFrom "0"; the store may use the uid itself.
+            if (!msg.isSelf && ownId && String(msg.data.uidFrom) === ownId) msg.isSelf = true;
+            kept.push(msg);
+        }
+
+        hasMore = Number(page.hasMore) > 0;
+        // Zalo withholds what it filters, and the filter is a point in time
+        // (measured live 2026-09-30: only messages since this device's login
+        // came back; everything older read `isFiltered: 1`, 0 rows, `hasMore:
+        // 1`, page after page). Every older page is past the same point, so
+        // walking on only fetched empty pages and then claimed "more".
+        if (Number(page.isFiltered) > 0) {
+            filtered = true;
+            hasMore = false;
+            break;
+        }
+        if (kept.length >= count || !hasMore) break;
+
+        // Zalo Web's loop: the next page starts at the lastMsgId the server
+        // returned. A cursor that does not move older would ask for the same
+        // page forever, so it ends the walk.
+        const next = msgIdOf(page.lastMsgId);
+        if (next === null || next === 0n || next >= BigInt(cursor)) break;
+        cursor = next.toString();
+        old = Number(page.isOld) > 0;
+        src = SRC_LOAD_MORE;
+    }
+
+    kept.sort(newestFirst);
+    return { groupMsgs: kept.slice(0, count), more: kept.length > count || hasMore ? 1 : 0, pages, filtered };
+}

package/src/core/group-members.js

@@ -0,0 +1,68 @@
+/**
+ * Who is in a group, and what Zalo calls them.
+ *
+ * `group members` and the MCP tool `zalo_get_group_members` list members
+ * through the same function, and `msg send` and that tool name uncached
+ * members through the same lookup, so the CLI and an agent see one answer.
+ * Nothing here writes zalo.db: its only writers are the listener, sync and
+ * `msg history`'s fetch (AGENTS.md §13), so a name looked up here is used for
+ * the call that looked it up and then forgotten.
+ */
+
+/**
+ * A group's member uids, the way `group members` lists them.
+ *
+ * `getGroupInfo` takes an array, not a bare id. Its `memberIds` field is
+ * always empty; the uids ride in `memVerList` as `"<uid>_<version>"` strings
+ * (e.g. `"1000000000000000001_0"`).
+ *
+ * @param {object} api - logged-in zca-js api
+ * @param {string} groupId
+ * @returns {Promise<{found: boolean, name: string|null, uids: string[], totalMember: number}>}
+ *   `found` is false when Zalo's answer does not include the group at all;
+ *   `totalMember` is Zalo's own count, which can exceed `uids.length`
+ */
+export async function groupMemberUids(api, groupId) {
+    const result = await api.getGroupInfo([groupId]);
+    const groupData = result?.gridInfoMap?.[groupId];
+    const memVerList = groupData?.memVerList || [];
+    const uids = memVerList.map((mv) => mv.split("_")[0]).filter(Boolean);
+    const totalMember = groupData?.totalMember ?? uids.length;
+    return { found: Boolean(groupData), name: groupData?.name ?? null, uids, totalMember };
+}
+
+/**
+ * Ask Zalo for the display names of some users (`getGroupMembersInfo`).
+ *
+ * Zalo Web fetches member profiles the same way when it shows a member list:
+ * one request at a time, a bounded number of ids per request. zca-js sends
+ * the ids in the request URL, so `batchSize` keeps a large group's lookup from
+ * outgrowing one URL. Keys come back as the uid, sometimes with zca-js's
+ * `_0` version suffix; the name is `displayName`, else `zaloName`.
+ *
+ * Never throws. A batch that fails leaves its uids unnamed and is reported in
+ * `errors`, and the batches after it still run.
+ *
+ * @param {object} api - logged-in zca-js api
+ * @param {string[]} uids
+ * @param {{batchSize?: number}} [opts] - ids per request; all of them in one request by default
+ * @returns {Promise<{names: Map<string, string>, errors: string[]}>} uid → display name, for those found
+ */
+export async function fetchMemberNames(api, uids, { batchSize = Infinity } = {}) {
+    const names = new Map();
+    const errors = [];
+    const size = Number.isFinite(batchSize) && batchSize > 0 ? Math.floor(batchSize) : uids.length;
+    for (let i = 0; i < uids.length; i += size) {
+        try {
+            const profiles = (await api.getGroupMembersInfo(uids.slice(i, i + size)))?.profiles || {};
+            for (const [key, profile] of Object.entries(profiles)) {
+                const uid = String(key).replace(/_0$/, "");
+                const name = profile?.displayName || profile?.zaloName;
+                if (name) names.set(uid, name);
+            }
+        } catch (e) {
+            errors.push(e?.message || String(e));
+        }
+    }
+    return { names, errors };
+}

package/src/core/group-settings.js

@@ -0,0 +1,250 @@
+/**
+ * `group settings` as a read-modify-write.
+ *
+ * Zalo's setting update (GET {group}/api/group/setting/update, cmd 11816) takes
+ * the group's WHOLE setting object. Nothing in it means "leave this alone", so
+ * a field sent wrong is a field changed. The command used to send `opts.X ??
+ * false` for its eight toggles, which turned every toggle the user did not name
+ * OFF. zca-js's `updateGroupSettings` then sent `setTopicOnly` (never exposed
+ * by the CLI) as 0, left `addMemberOnly` out, and hard-coded `bannFeature: 0,
+ * dirtyMedia: 0, banDuration: 0, blocked_members: []` on every call.
+ *
+ * What Zalo Web sends instead (bundle 1.e0ef5e98f8f9d8970e2c.js, 2026-09-29
+ * capture; byte offsets into that file):
+ *
+ *   ~10948180  the request builder: `{...setting, grid, imei}`, AES-encrypted
+ *              into `params=` on a GET. The same request zca-js builds.
+ *   ~4235006   the settings panel: its state starts as
+ *              `{...groupInfo.setting, blocked_members: []}` and is refreshed
+ *              from a forced re-read of the group.
+ *   ~4238633   `_setGroup`: `Object.assign({}, this.state)`, flip ONE key,
+ *              send the lot.
+ *   ~6778552   the member-list "hide members" toggle:
+ *              `{...getSettingsGroup(gid), lockViewMember}`, and it sends
+ *              nothing when there are no settings to spread.
+ *   ~4300286   after success the web stores what it sent as the group's new
+ *              setting, wholesale. It treats the request as a full replace.
+ *
+ * So this module does the same: read the current setting, overlay only the
+ * changes the user asked for, send everything else back as Zalo reported it —
+ * including keys this CLI does not know. It refuses rather than guess: no
+ * change asked for, or a setting it could not read completely, and nothing is
+ * sent.
+ *
+ * Two fields needed a decision:
+ *
+ *   blocked_members — NOT sent. The panel sends `[]` (its state never holds
+ *   the real list: that lives in a separate hook, ~4185295); the member-list
+ *   toggle omits the key altogether; nothing in the web ever sends a populated
+ *   list. So the server accepts a request without it. Omitting it is safe under
+ *   every reading of the field under which `[]` is safe, and also under the
+ *   one where `[]` means "replace the block list with nothing". Unverified live.
+ *
+ *   addMemberOnly — carried at its current value, as both web paths do.
+ *   zca-js comments it out ("very tricky, any idea?"); the web never changes it
+ *   directly, and its panel shows join approval as on when either it or
+ *   joinAppr is set.
+ *
+ * `dirtyMedia`/`banDuration` are Zalo's own media-ban state (the web's banned
+ * group manager, ~3673605, reads them to hide media: `dirtyMedia` 1 or 2 is
+ * banned, `banDuration` is seconds). `bannFeature` never appears in the web
+ * bundles by name. All three are sent back exactly as read.
+ */
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+
+const require = createRequire(import.meta.url);
+
+let _utils = null;
+/** zca-js internals, located the same way ./sync-v2/gid.js does. */
+function zcaUtils() {
+    if (_utils) return _utils;
+    _utils = require(join(dirname(require.resolve("zca-js")), "utils.cjs"));
+    return _utils;
+}
+
+/**
+ * CLI flag -> the GroupSetting key it toggles. Each flag also has a `--no-`
+ * form. `topic-only` is Zalo Web's ONLY_ADMIN_SET_TOPIC: when 1, only the
+ * owner and admins can pin messages, notes and polls to the top of the chat
+ * (the web's `checkAuth` denies a plain member `allowPin` then, ~2668943).
+ */
+export const SETTING_FLAGS = Object.freeze({
+    "block-name": "blockName",
+    "sign-admin": "signAdminMsg",
+    "msg-history": "enableMsgHistory",
+    "join-appr": "joinAppr",
+    "lock-post": "lockCreatePost",
+    "lock-poll": "lockCreatePoll",
+    "lock-msg": "lockSendMsg",
+    "lock-view-member": "lockViewMember",
+    "topic-only": "setTopicOnly",
+});
+
+/**
+ * Every field of zca-js's `GroupSetting` (models/Group.d.ts, none optional).
+ * Each one is sent back verbatim, so each one has to have been read: a setting
+ * missing any of them is refused. If a live read shows Zalo legitimately omits
+ * one, relax it here and in tests/unit/group-settings.test.js together.
+ */
+export const GROUP_SETTING_FIELDS = Object.freeze([
+    "blockName",
+    "signAdminMsg",
+    "addMemberOnly",
+    "setTopicOnly",
+    "enableMsgHistory",
+    "joinAppr",
+    "lockCreatePost",
+    "lockCreatePoll",
+    "lockSendMsg",
+    "lockViewMember",
+    "bannFeature",
+    "dirtyMedia",
+    "banDuration",
+]);
+
+/** The refusal for an invocation that names no setting. */
+export const NOTHING_TO_CHANGE =
+    "nothing to change: pass at least one setting flag, e.g. --join-appr or --no-join-appr " +
+    "(`group info <groupId>` shows the current settings); nothing was sent";
+
+/** Commander's option key for a flag: "lock-view-member" -> "lockViewMember". */
+const optionKey = (flag) => flag.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+
+/** A toggle as Zalo stores it. */
+const bit = (value) => (Number(value) ? 1 : 0);
+
+/**
+ * The setting changes the user actually asked for.
+ *
+ * Commander leaves an option undefined when neither `--X` nor `--no-X` was
+ * typed (`--X` is declared first, so it has no default). That undefined is the
+ * whole difference between "leave it" and "turn it off", so it must never be
+ * collapsed into false.
+ *
+ * @param {object} opts - the `group settings` Commander options
+ * @returns {Record<string, 0|1>} GroupSetting key -> requested value, only for flags given
+ */
+export function settingChangesFromOptions(opts) {
+    const changes = {};
+    for (const [flag, key] of Object.entries(SETTING_FLAGS)) {
+        const value = opts?.[optionKey(flag)];
+        if (value === undefined) continue;
+        changes[key] = value ? 1 : 0;
+    }
+    return changes;
+}
+
+/**
+ * The group's current setting object, exactly as Zalo reports it.
+ *
+ * @param {object} api - logged-in zca-js api
+ * @param {string} groupId
+ * @returns {Promise<object>} a copy of `gridInfoMap[groupId].setting`
+ * @throws {Error} when the setting cannot be read completely
+ */
+export async function readGroupSetting(api, groupId) {
+    const refuse = (why) =>
+        new Error(`could not read the current settings of group ${groupId} (${why}); nothing was sent`);
+    let info;
+    try {
+        info = await api.getGroupInfo([groupId]);
+    } catch (e) {
+        throw refuse(e.message);
+    }
+    const entry = info?.gridInfoMap?.[groupId];
+    if (!entry) throw refuse("Zalo's answer does not include this group");
+    const setting = entry.setting;
+    if (!setting || typeof setting !== "object" || Array.isArray(setting)) {
+        throw refuse("Zalo returned no setting object");
+    }
+    const missing = GROUP_SETTING_FIELDS.filter((key) => setting[key] === undefined || setting[key] === null);
+    if (missing.length) {
+        throw refuse(`missing ${missing.join(", ")}; sending the update without them could reset them`);
+    }
+    return { ...setting };
+}
+
+/**
+ * Send a complete setting object: zca-js's updateGroupSettings request, minus
+ * the fields it hard-codes. Same endpoint, same service, same envelope.
+ *
+ * @param {object} api - logged-in zca-js api
+ * @param {string} groupId
+ * @param {object} setting - the full setting to store
+ * @returns {Promise<*>} Zalo's `data` (an empty string for this endpoint)
+ */
+function sendGroupSetting(api, groupId, setting) {
+    const zu = zcaUtils();
+    const base = `${api.zpwServiceMap.group[0]}/api/group/setting/update`;
+    const call = zu.apiFactory()((_api, ctx, utils) => async () => {
+        const params = { ...setting, grid: groupId, imei: ctx.imei };
+        const enc = utils.encodeAES(JSON.stringify(params));
+        if (!enc) throw new Error("failed to encrypt group setting params");
+        const resp = await utils.request(utils.makeURL(base, { params: enc }), { method: "GET" });
+        return utils.resolve(resp);
+    })(api.getContext(), api);
+    return call();
+}
+
+/**
+ * Change the named settings of a group and send every other field back as it was.
+ *
+ * Refuses, sending nothing, when no change is asked for or the current setting
+ * cannot be read completely. When every requested value is already in place
+ * nothing is sent either — that is reported, not refused.
+ *
+ * @param {object} api - logged-in zca-js api
+ * @param {string} groupId
+ * @param {Record<string, 0|1>} changes - from settingChangesFromOptions()
+ * @returns {Promise<{groupId: string, sent: boolean, changed: object, unchanged: object, settings: object,
+ *   response?: *, verified?: boolean, sideEffects?: object, notApplied?: object}>}
+ *   `changed` maps key -> {from, to}; `unchanged` maps key -> the value it already had;
+ *   `settings` is the full setting as sent (or as found, when nothing was sent). After a
+ *   send, the group is read back: `verified` says whether that worked, `sideEffects`
+ *   maps key -> {from, to} for fields Zalo changed on its own, and `notApplied` maps
+ *   key -> {asked, now} for a requested change that did not stick
+ */
+export async function applyGroupSettingChanges(api, groupId, changes) {
+    const requested = Object.entries(changes ?? {});
+    if (requested.length === 0) throw new Error(NOTHING_TO_CHANGE);
+
+    const current = await readGroupSetting(api, groupId);
+    const changed = {};
+    const unchanged = {};
+    for (const [key, to] of requested) {
+        if (bit(current[key]) === to) unchanged[key] = to;
+        else changed[key] = { from: current[key], to };
+    }
+    if (Object.keys(changed).length === 0) {
+        return { groupId, sent: false, changed, unchanged, settings: current };
+    }
+
+    // Overlay only what actually changes, so an already-set toggle keeps the
+    // exact value Zalo reported rather than our 0/1 rendering of it.
+    const settings = { ...current };
+    for (const [key, { to }] of Object.entries(changed)) settings[key] = to;
+    const response = await sendGroupSetting(api, groupId, settings);
+
+    // Read back what Zalo now holds. Measured live 2026-09-30: turning join
+    // approval on also set addMemberOnly, which we had sent at its current 0,
+    // and turning it off cleared both — a change the command could not report
+    // without looking. Best-effort: the write already went out.
+    const sideEffects = {};
+    const notApplied = {};
+    let verified = false;
+    try {
+        const after = await readGroupSetting(api, groupId);
+        verified = true;
+        for (const key of new Set([...Object.keys(settings), ...Object.keys(after)])) {
+            if (key in changed) {
+                if (bit(after[key]) !== changed[key].to) notApplied[key] = { asked: changed[key].to, now: after[key] };
+            } else if (JSON.stringify(after[key]) !== JSON.stringify(settings[key])) {
+                sideEffects[key] = { from: settings[key], to: after[key] };
+            }
+        }
+    } catch {
+        /* the read-back failed; `verified` stays false */
+    }
+    return { groupId, sent: true, changed, unchanged, settings, response, verified, sideEffects, notApplied };
+}