@ardennguyen/zalo-agent-cli 2.5.8 → 3.0.0

package/src/zalo/custom/group-history.js

@@ -0,0 +1,246 @@
+/**
+ * Group chat history from Zalo's cloud-message store.
+ *
+ * The previous engine's getGroupChatHistory asked `{group}/api/group/history`, which Zalo
+ * answers with HTTP 404. Zalo serves 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})
+ *
+ * What is established, and what is not:
+ *
+ * - The newest page is `getrecentv2` with globalMsgId 2^63 (the largest
+ *   message id) and `src: 1`, as sent when a group is opened.
+ * - Older pages: the next globalMsgId is the response's `lastMsgId`, the
+ *   request goes to `getoldv2` only when the response says `isOld`, and it
+ *   carries `src: 3` (load more). No observed 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. Bare numbers in `uidFrom`,
+ *   `uidTo`, `uid` and `ownerId` are quoted before parsing it, because uids
+ *   run past 2^53.
+ * - Recall (`chat.undo`) and delete (`chat.delete`) events and rows without
+ *   content are dropped, and rows are de-duplicated on cliMsgId + sender.
+ *
+ * `group_cloud_message` was declared in the previous engine'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 (src/core/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 { boundUtils } from "../kernel/bound.js";
+import { GroupMessage } from "../listener/models.js";
+
+/** The largest message id, `(BigInt(2) ** BigInt(63)).toString()`: start from the newest. */
+export const NEWEST_MSG_ID = "9223372036854775808";
+
+/**
+ * Messages asked for per request: the server-configured page size, 50 in
+ * every observed case; nothing else has been seen.
+ */
+export const CM_PAGE_SIZE = 50;
+
+/** The cloud-load `src`: opening a conversation, and loading more (scrolling up). */
+const SRC_OPEN = 1;
+const SRC_LOAD_MORE = 3;
+
+/** Pause between pages. Zalo rate-limits hard (see src/core/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;
+
+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. It 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);
+}
+
+/** 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 utils = boundUtils(api);
+    // Key order as the server expects it.
+    const params = { groupId, globalMsgId, count: CM_PAGE_SIZE, msgIds: [], imei: api.getContext().imei, src };
+    const enc = utils.encodeAES(JSON.stringify(params));
+    const resp = await utils.request(utils.makeURL(url, { nretry: 0, params: enc }), { method: "GET" });
+    return parsePage(await utils.resolve(resp));
+}
+
+/**
+ * Fetch a group's newest messages from Zalo's cloud-message store.
+ *
+ * A drop-in for the previous engine's `getGroupChatHistory(groupId, count)`, whose endpoint
+ * is retired: it resolves to `{groupMsgs, more}` with each message a listener
+ * `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 session
+ * @param {string} groupId - numeric group id; a leading "g" is stripped
+ * @param {number} [count=50] - how many of the newest messages to return, a whole number >= 1, or `Infinity` for
+ *   everything the store serves: pages of 50, one after another, until it says `hasMore: 0`, as Zalo pages a group
+ * @param {object} [opts]
+ * @param {number} [opts.delayMs=150] - pause between pages
+ * @param {number} [opts.untilTs] - stop after the first page that reaches back to this time (ms): a caller that
+ *   only needs what came after it
+ * @returns {Promise<{groupMsgs: Array<object>, more: 0|1, pages: number, filtered: boolean, stalled: 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; `stalled` is true when the store said more follows but its cursor
+ *   did not move older (the walk stopped there instead of asking for the same page again)
+ * @throws {Error} when `count` is not a whole number >= 1 (or Infinity), 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, untilTs = null } = {},
+) {
+    if (count !== Infinity && (!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; no cap when everything is asked for.
+    const maxPages = count === Infinity ? Infinity : Math.ceil(count / CM_PAGE_SIZE) + 2;
+    let stalled = false;
+
+    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;
+        if (untilTs !== null && rows.some((d) => Number(d?.ts) <= untilTs)) break;
+
+        // 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)) {
+            stalled = true;
+            break;
+        }
+        cursor = next.toString();
+        old = Number(page.isOld) > 0;
+        src = SRC_LOAD_MORE;
+    }
+
+    kept.sort(newestFirst);
+    return {
+        groupMsgs: count === Infinity ? kept : kept.slice(0, count),
+        more: kept.length > count || hasMore ? 1 : 0,
+        pages,
+        filtered,
+        stalled,
+    };
+}

package/src/zalo/custom/group-invite.js

@@ -0,0 +1,53 @@
+/**
+ * A pending group invitation's details (`group invite-info`).
+ *
+ * The previous engine's `getGroupInviteBoxInfo` read `data.groupInfo.topic.params` without
+ * checking that the group has a topic. Most groups have no pinned message, so
+ * for them Zalo's answer carries no `topic` and that call threw "Cannot read
+ * properties of undefined (reading 'params')" after Zalo had answered fine.
+ * This makes the same request (GET {group}/api/group/inv-box/inv-info) on
+ * the session envelope, and unpacks the topic's JSON-in-JSON params
+ * only when there is a topic.
+ */
+import { customCall, getWithParams } from "../session-call.js";
+
+/**
+ * Parse a topic's `params`, which Zalo sends as a JSON string whose `extra`
+ * field is itself a JSON string. Anything that does not parse is left as it came.
+ *
+ * @param {object} topic
+ * @returns {object} the same topic, with `params` unpacked when it could be
+ */
+export function unpackTopic(topic) {
+    if (!topic || typeof topic.params !== "string") return topic;
+    try {
+        const params = JSON.parse(topic.params);
+        if (typeof params?.extra === "string") {
+            try {
+                params.extra = JSON.parse(params.extra);
+            } catch {
+                /* keep the string */
+            }
+        }
+        return { ...topic, params };
+    } catch {
+        return topic;
+    }
+}
+
+/**
+ * @param {object} api - logged-in session
+ * @param {{groupId: string, mpage?: number, mcount?: number}} payload
+ * @returns {Promise<object>} Zalo's `data`: groupInfo, inviterInfo, grCreatorInfo, expiredTs, type
+ */
+export async function getInviteBoxInfo(api, { groupId, mpage = 1, mcount = 10 }) {
+    return customCall(api, async (_ctx, utils) => {
+        const data = await getWithParams(utils, `${api.zpwServiceMap.group[0]}/api/group/inv-box/inv-info`, {
+            grId: groupId,
+            mcount,
+            mpage,
+        });
+        if (data?.groupInfo?.topic) data.groupInfo.topic = unpackTopic(data.groupInfo.topic);
+        return data;
+    });
+}

package/src/zalo/custom/group-settings.js

@@ -0,0 +1,186 @@
+/**
+ * `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. The previous engine'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 the server expects instead:
+ *
+ *   - the request is `{...setting, grid, imei}`, AES-encrypted into `params=`
+ *     on a GET (the same request the previous engine built);
+ *   - `setting` is the group's whole current setting, freshly re-read, with
+ *     ONE key flipped -- everything else sent back as it was;
+ *   - nothing is sent when there are no settings to spread;
+ *   - after success, what was sent is the group's new setting, wholesale:
+ *     the request is 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. Zalo's own apps send `[]` or omit the key
+ *   altogether, and never send 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. The previous engine
+ *   commented it out; Zalo never changes it directly, and shows join approval
+ *   as on when either it or joinAppr is set.
+ *
+ * `dirtyMedia`/`banDuration` are Zalo's own media-ban state (`dirtyMedia` 1
+ * or 2 hides the group's media, `banDuration` is seconds). `bannFeature`'s
+ * meaning is unknown. All three are sent back exactly as read.
+ */
+import { boundUtils } from "../kernel/bound.js";
+
+/**
+ * Every field of a group's `setting` as Zalo reports it (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";
+
+/** A toggle as Zalo stores it. */
+const bit = (value) => (Number(value) ? 1 : 0);
+
+/**
+ * The group's current setting object, exactly as Zalo reports it.
+ *
+ * @param {object} api - logged-in session
+ * @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: the previous engine's updateGroupSettings request, minus
+ * the fields it hard-codes. Same endpoint, same service, same envelope.
+ *
+ * @param {object} api - logged-in session
+ * @param {string} groupId
+ * @param {object} setting - the full setting to store
+ * @returns {Promise<*>} Zalo's `data` (an empty string for this endpoint)
+ */
+async function sendGroupSetting(api, groupId, setting) {
+    const base = `${api.zpwServiceMap.group[0]}/api/group/setting/update`;
+    const utils = boundUtils(api);
+    const params = { ...setting, grid: groupId, imei: api.getContext().imei };
+    const resp = await utils.request(utils.makeURL(base, { params: utils.encodeAES(JSON.stringify(params)) }), {
+        method: "GET",
+    });
+    return utils.resolve(resp);
+}
+
+/**
+ * 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 session
+ * @param {string} groupId
+ * @param {Record<string, 0|1>} changes - GroupSetting key -> 0|1 (the CLI builds it with settingChangesFromOptions
+ *   in src/core/group-settings.js)
+ * @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 };
+}

package/src/zalo/custom/group-visibility.js

@@ -0,0 +1,71 @@
+/**
+ * A group's own `visibility`, for the recall (`undo`) of a message in it.
+ *
+ * A group recall (cmd 11192) carries the group's `visibility` from the group's info, 0 when it is unknown; the
+ * previous engine always sent 0 (spec-actions 1.3, open question 4). `msg undo` and `zalo_undo` use what they
+ * have: the MCP server's thread cache when it holds the value, else the group's info from Zalo
+ * (`getGroupInfo`). When neither answers, the payload carries no
+ * `visibility` and the engine sends 0, as before.
+ *
+ * Nothing here writes or logs.
+ */
+
+/** Zalo's thread type for a group. */
+const THREAD_GROUP = 1;
+
+/**
+ * A visibility value as a number, or undefined when there is none.
+ *
+ * @param {unknown} v
+ * @returns {number|undefined}
+ */
+function visibilityOf(v) {
+    if (v === undefined || v === null || v === "") return undefined;
+    const n = Number(v);
+    return Number.isInteger(n) && n >= 0 ? n : undefined;
+}
+
+/**
+ * The group's `visibility`: from `cache` when it holds the value, else from `api.getGroupInfo`.
+ *
+ * @param {object} api - a logged-in api
+ * @param {string} groupId - the group id (a `g` prefix is ignored)
+ * @param {object} [opts]
+ * @param {{get: (id: string) => object|null|undefined}} [opts.cache] - the MCP thread cache
+ * @returns {Promise<number|undefined>} undefined when nothing knows it
+ */
+export async function groupVisibility(api, groupId, { cache } = {}) {
+    const gid = String(groupId ?? "").replace(/^g(?=\d+$)/, "");
+    if (!gid) return undefined;
+    let cached;
+    try {
+        cached = visibilityOf(cache?.get?.(gid)?.visibility);
+    } catch {
+        cached = undefined;
+    }
+    if (cached !== undefined) return cached;
+    if (typeof api?.getGroupInfo !== "function") return undefined;
+    try {
+        const info = await api.getGroupInfo([gid]);
+        return visibilityOf(info?.gridInfoMap?.[gid]?.visibility);
+    } catch {
+        return undefined;
+    }
+}
+
+/**
+ * The recall payload for `api.undo`: `{msgId, cliMsgId}`, plus the group's `visibility` for a group message when it
+ * is known. A 1-1 recall is returned as it came.
+ *
+ * @param {object} api
+ * @param {{msgId: string, cliMsgId: string}} payload
+ * @param {string} threadId
+ * @param {number} threadType - 0 a person, 1 a group
+ * @param {object} [opts] - `{cache}`, as {@link groupVisibility}
+ * @returns {Promise<{msgId: string, cliMsgId: string, visibility?: number}>}
+ */
+export async function undoPayload(api, payload, threadId, threadType, opts = {}) {
+    if (Number(threadType) !== THREAD_GROUP) return payload;
+    const visibility = await groupVisibility(api, threadId, opts);
+    return visibility === undefined ? payload : { ...payload, visibility };
+}