@softtynet/zca-js 2.3.6 → 2.3.7

package/dist/cjs/realtime/handlers/message.handler.cjs

@@ -17,64 +17,130 @@ require('../../models/CallEvent.cjs');
 var utils = require('../../utils.cjs');
 var wsCipher = require('../../crypto/ws-cipher.cjs');
 
-async function handleRealtimeMessagePacket(listener, ctx, selfListen, onMessageCallback, version, cmd, subCmd, parsed, cipherKey) {
-    if (version == 1 && [501, 551].includes(cmd) && subCmd == 0) {
-        const parsedData = (await wsCipher.decodeEventData(parsed, cipherKey)).data;
-        const { msgs } = parsedData;
-        for (const msg of msgs) {
-            if (typeof msg.content == "object" && utils.hasOwn(msg.content, "deleteMsg")) {
-                const undoObject = new Undo.Undo(ctx.uid, msg, false);
-                if (undoObject.isSelf && !selfListen)
-                    continue;
-                listener.emit("undo", undoObject);
-            }
-            else {
-                const messageObject = new Message.UserMessage(ctx.uid, msg);
-                if (messageObject.isSelf && !selfListen)
-                    continue;
-                onMessageCallback(messageObject);
-                listener.emit("message", messageObject);
+function processIncomingUserMessages(listener, ctx, selfListen, onMessageCallback, messages, isPageMsg = false) {
+    for (const msg of messages) {
+        if (!msg)
+            continue;
+        if (typeof msg.content == "object" && msg.content !== null && utils.hasOwn(msg.content, "deleteMsg")) {
+            const undoObject = new Undo.Undo(ctx.uid, msg, false);
+            if (undoObject.isSelf && !selfListen)
+                continue;
+            listener.emit("undo", undoObject);
+        }
+        else {
+            const messageObject = new Message.UserMessage(ctx.uid, msg, isPageMsg);
+            if (messageObject.isSelf && !selfListen)
+                continue;
+            onMessageCallback(messageObject);
+            listener.emit("message", messageObject);
+            if (messageObject.isOAMessage()) {
+                listener.emit("oa_message", messageObject);
             }
         }
+    }
+}
+function processIncomingGroupMessages(listener, ctx, selfListen, onMessageCallback, groupMessages) {
+    for (const msg of groupMessages) {
+        if (!msg)
+            continue;
+        if (typeof msg.content == "object" && msg.content !== null && utils.hasOwn(msg.content, "deleteMsg")) {
+            const undoObject = new Undo.Undo(ctx.uid, msg, true);
+            if (undoObject.isSelf && !selfListen)
+                continue;
+            listener.emit("undo", undoObject);
+        }
+        else {
+            const messageObject = new Message.GroupMessage(ctx.uid, msg);
+            if (messageObject.isSelf && !selfListen)
+                continue;
+            onMessageCallback(messageObject);
+            listener.emit("message", messageObject);
+        }
+    }
+}
+async function handleRealtimeMessagePacket(listener, ctx, selfListen, onMessageCallback, version, cmd, subCmd, parsed, cipherKey) {
+    if (version == 1 && [501, 551].includes(cmd) && subCmd == 0) {
+        const decoded = await wsCipher.decodeEventData(parsed, cipherKey);
+        const parsedData = decoded?.data ?? decoded;
+        const msgs = (Array.isArray(parsedData?.msgs) ? parsedData.msgs : []);
+        const pageMsgs = (Array.isArray(parsedData?.pageMsgs) ? parsedData.pageMsgs : []);
+        if (msgs.length > 0)
+            processIncomingUserMessages(listener, ctx, selfListen, onMessageCallback, msgs, false);
+        if (pageMsgs.length > 0)
+            processIncomingUserMessages(listener, ctx, selfListen, onMessageCallback, pageMsgs, true);
         return true;
     }
     if (version == 1 && cmd == 521 && subCmd == 0) {
-        const parsedData = (await wsCipher.decodeEventData(parsed, cipherKey)).data;
-        const { groupMsgs } = parsedData;
-        for (const msg of groupMsgs) {
-            if (typeof msg.content == "object" && utils.hasOwn(msg.content, "deleteMsg")) {
-                const undoObject = new Undo.Undo(ctx.uid, msg, true);
-                if (undoObject.isSelf && !selfListen)
-                    continue;
-                listener.emit("undo", undoObject);
-            }
-            else {
-                const messageObject = new Message.GroupMessage(ctx.uid, msg);
-                if (messageObject.isSelf && !selfListen)
-                    continue;
-                onMessageCallback(messageObject);
-                listener.emit("message", messageObject);
-            }
+        const decoded = await wsCipher.decodeEventData(parsed, cipherKey);
+        const parsedData = decoded?.data ?? decoded;
+        const groupMsgs = (Array.isArray(parsedData?.groupMsgs) ? parsedData.groupMsgs : []);
+        processIncomingGroupMessages(listener, ctx, selfListen, onMessageCallback, groupMsgs);
+        return true;
+    }
+    // HAS_MSG (cmd = 533): Server báo có tin nhắn đang chờ (thường gặp với OA / Missed Queue) -> kéo ngay qua cmd = 570 (GET_MSG)
+    if (cmd == 533 && subCmd == 0) {
+        const decoded = await wsCipher.decodeEventData(parsed, cipherKey);
+        const parsedData = (decoded?.data ?? decoded);
+        if (parsedData?.queueId && Array.isArray(parsedData.ids) && parsedData.ids.length > 0) {
+            listener.requestMessagesByIds(parsedData.queueId, parsedData.ids);
+        }
+        return true;
+    }
+    // PUSH_MISS_MSG (cmd = 534) & GET_MSG (cmd = 570): Gói tin trả về các tin nhắn OA (`pageMsgs`), User (`msgs`) và Group (`groupMsgs`)
+    if ((cmd == 534 || cmd == 570) && subCmd == 0) {
+        const decoded = await wsCipher.decodeEventData(parsed, cipherKey);
+        const parsedData = decoded?.data ?? decoded;
+        const msgs = (Array.isArray(parsedData?.msgs) ? parsedData.msgs : []);
+        const pageMsgs = (Array.isArray(parsedData?.pageMsgs) ? parsedData.pageMsgs : []);
+        const groupMsgs = (Array.isArray(parsedData?.groupMsgs) ? parsedData.groupMsgs : []);
+        if (msgs.length > 0) {
+            processIncomingUserMessages(listener, ctx, selfListen, onMessageCallback, msgs, false);
+        }
+        if (pageMsgs.length > 0) {
+            processIncomingUserMessages(listener, ctx, selfListen, onMessageCallback, pageMsgs, true);
+        }
+        if (groupMsgs.length > 0) {
+            processIncomingGroupMessages(listener, ctx, selfListen, onMessageCallback, groupMsgs);
         }
         return true;
     }
     if (cmd == 510 && (subCmd == 0 || subCmd == 1)) {
         const decoded = await wsCipher.decodeEventData(parsed, cipherKey);
         const parsedData = decoded?.data ?? decoded;
-        const msgs = (parsedData?.msgs ?? []);
+        const msgs = (Array.isArray(parsedData?.msgs) ? parsedData.msgs : []);
+        const pageMsgs = (Array.isArray(parsedData?.pageMsgs) ? parsedData.pageMsgs : []);
         const responseMsgs = [];
         for (const msg of msgs) {
-            if (typeof msg.content == "object" && utils.hasOwn(msg.content, "deleteMsg")) {
+            if (typeof msg.content == "object" && msg.content !== null && utils.hasOwn(msg.content, "deleteMsg")) {
+                const undoObject = new Undo.Undo(ctx.uid, msg, false);
+                if (undoObject.isSelf && !selfListen)
+                    continue;
+                listener.emit("undo", undoObject);
+            }
+            else {
+                const userMsg = new Message.UserMessage(ctx.uid, msg, false);
+                responseMsgs.push(userMsg);
+                if (userMsg.isOAMessage() && (!userMsg.isSelf || selfListen)) {
+                    listener.emit("oa_message", userMsg);
+                }
+            }
+        }
+        for (const msg of pageMsgs) {
+            if (typeof msg.content == "object" && msg.content !== null && utils.hasOwn(msg.content, "deleteMsg")) {
                 const undoObject = new Undo.Undo(ctx.uid, msg, false);
                 if (undoObject.isSelf && !selfListen)
                     continue;
                 listener.emit("undo", undoObject);
             }
             else {
-                responseMsgs.push(new Message.UserMessage(ctx.uid, msg));
+                const oaUserMsg = new Message.UserMessage(ctx.uid, msg, true);
+                responseMsgs.push(oaUserMsg);
+                if (oaUserMsg.isOAMessage() && (!oaUserMsg.isSelf || selfListen)) {
+                    listener.emit("oa_message", oaUserMsg);
+                }
             }
         }
-        if (responseMsgs.length > 0 || msgs.length === 0) {
+        if (responseMsgs.length > 0 || (msgs.length === 0 && pageMsgs.length === 0)) {
             listener.emit("old_messages", responseMsgs, Enum.ThreadType.User, parsedData?.more === 1);
         }
         return true;

package/dist/cjs/realtime/listener.cjs

@@ -330,18 +330,19 @@ class Listener extends EventEmitter {
     }
     sendWs(payload, requireId = true) {
         if (this.ws && (this.ws.readyState === undefined || this.ws.readyState === WebSocket.OPEN)) {
-            if (requireId)
-                payload.data["req_id"] = `req_${this.id++}`;
+            if (requireId) {
+                const reqId = `req_${this.id++}`;
+                payload.data["req_id"] = reqId;
+                payload.data["reqId"] = reqId;
+            }
             const encodedData = new TextEncoder().encode(JSON.stringify(payload.data));
             const dataLength = encodedData.length;
-            const data = new DataView(Buffer.alloc(4 + dataLength).buffer);
-            data.setUint8(0, payload.version);
-            data.setInt32(1, payload.cmd, true);
-            data.setInt8(3, payload.subCmd);
-            encodedData.forEach((e, i) => {
-                data.setUint8(4 + i, e);
-            });
-            this.ws.send(data);
+            const buf = Buffer.alloc(4 + dataLength);
+            buf.writeUInt8(payload.version, 0);
+            buf.writeUInt16LE(payload.cmd, 1);
+            buf.writeInt8(payload.subCmd, 3);
+            Buffer.from(encodedData).copy(buf, 4);
+            this.ws.send(buf);
         }
     }
     /**
@@ -376,16 +377,36 @@ class Listener extends EventEmitter {
         this.sendWs(payload);
     }
     /**
-     * Kích hoạt và kéo hàng đợi sự kiện điều khiển / VoIP (`cmd 603` CTRL_PULL_CTRL và `cmd 604` CTRL_PULL_VOIP).
-     * Giúp nhận ngay các cuộc gọi đến đang đổ chuông ngay cả khi vừa mở kết nối WebSocket.
+     * Kéo danh sách tin nhắn cụ thể theo `queueId` và mảng `ids` (`cmd 570` GET_MSG)
+     * khi nhận tín hiệu `cmd 533` (`HAS_MSG`) từ Zalo WebSocket (thường dùng cho tin nhắn OA / ZNS / Missed Queue).
+     * Tự động chia batch tối đa 20 ID mỗi gói theo đúng cấu hình `max_msg_get = 20` trên Zalo Desktop.
+     */
+    requestMessagesByIds(queueId, ids, lastId = "0") {
+        if (!queueId || !Array.isArray(ids) || ids.length === 0)
+            return;
+        const maxBatchSize = 20;
+        for (let i = 0; i < ids.length; i += maxBatchSize) {
+            const chunk = ids.slice(i, i + maxBatchSize);
+            const reqId = `req_${this.id++}`;
+            this.sendWs({
+                version: 1,
+                cmd: 570,
+                subCmd: 0,
+                data: {
+                    queueId,
+                    ids: chunk,
+                    lastId,
+                    reqId,
+                    req_id: reqId,
+                },
+            }, false);
+        }
+    }
+    /**
+     * Kích hoạt và kéo hàng đợi sự kiện điều khiển / VoIP (`cmd 603` CTRL_PULL_CTRL).
+     * Giúp nhận ngay các cuộc gọi đến đang đổ chuông và sự kiện điều khiển ngay cả khi vừa mở kết nối WebSocket.
      */
     requestOfflineVoipControls() {
-        this.sendWs({
-            version: 1,
-            cmd: 604,
-            subCmd: 0,
-            data: { first: true, lastId: 1, preIds: [] },
-        });
         this.sendWs({
             version: 1,
             cmd: 603,

package/dist/cjs/utils.cjs

@@ -17,6 +17,25 @@ var defaults = require('./constants/defaults.cjs');
 var aes = require('./crypto/aes.cjs');
 var wsCipher = require('./crypto/ws-cipher.cjs');
 
+function _interopNamespaceDefault(e) {
+    var n = Object.create(null);
+    if (e) {
+        Object.keys(e).forEach(function (k) {
+            if (k !== 'default') {
+                var d = Object.getOwnPropertyDescriptor(e, k);
+                Object.defineProperty(n, k, d.get ? d : {
+                    enumerable: true,
+                    get: function () { return e[k]; }
+                });
+            }
+        });
+    }
+    n.default = e;
+    return Object.freeze(n);
+}
+
+var toughCookie__namespace = /*#__PURE__*/_interopNamespaceDefault(toughCookie);
+
 const isBun = typeof Bun !== "undefined";
 function hasOwn(obj, key) {
     return Object.prototype.hasOwnProperty.call(obj, key);
@@ -143,7 +162,7 @@ async function getDefaultHeaders(ctx, origin = domains.ZALO_DOMAINS.CHAT_WEB) {
 }
 async function request(ctx, url, options, raw = false) {
     if (!ctx.cookie)
-        ctx.cookie = new toughCookie.CookieJar();
+        ctx.cookie = new toughCookie__namespace.CookieJar();
     const origin = new URL(url).origin;
     const defaultHeaders = await getDefaultHeaders(ctx, origin);
     if (!raw) {
@@ -208,7 +227,7 @@ async function request(ctx, url, options, raw = false) {
             cookieStrings = setCookieRaw.split(/,\s*(?=[a-zA-Z0-9_-]+\s*=)/);
         }
         for (const cookie of cookieStrings) {
-            const parsed = toughCookie.Cookie.parse(cookie);
+            const parsed = toughCookie__namespace.Cookie.parse(cookie);
             try {
                 if (parsed)
                     await ctx.cookie.setCookie(parsed, parsed.domain != "zalo.me" ? `https://${parsed.domain}` : origin);

package/dist/cjs/zalo.cjs

@@ -11,6 +11,25 @@ var apis = require('./apis.cjs');
 var domains = require('./constants/domains.cjs');
 var defaults = require('./constants/defaults.cjs');
 
+function _interopNamespaceDefault(e) {
+    var n = Object.create(null);
+    if (e) {
+        Object.keys(e).forEach(function (k) {
+            if (k !== 'default') {
+                var d = Object.getOwnPropertyDescriptor(e, k);
+                Object.defineProperty(n, k, d.get ? d : {
+                    enumerable: true,
+                    get: function () { return e[k]; }
+                });
+            }
+        });
+    }
+    n.default = e;
+    return Object.freeze(n);
+}
+
+var toughCookie__namespace = /*#__PURE__*/_interopNamespaceDefault(toughCookie);
+
 class Zalo {
     options;
     enableEncryptParam = true;
@@ -23,10 +42,10 @@ class Zalo {
             if (typeof e.domain == "string" && e.domain.startsWith("."))
                 cookieArr[i].domain = e.domain.slice(1);
         });
-        const jar = new toughCookie.CookieJar();
+        const jar = new toughCookie__namespace.CookieJar();
         for (const each of cookieArr) {
             try {
-                const cookieObj = toughCookie.Cookie.fromJSON({
+                const cookieObj = toughCookie__namespace.Cookie.fromJSON({
                     ...each,
                     key: each.key || each.name,
                 });

package/dist/constants/defaults.d.ts

@@ -35,8 +35,8 @@ export declare const ZALO_DEFAULTS: {
         /** Số lần lỗi 1006 liên tiếp trước khi xoay sang WebSocket endpoint tiếp theo */
         readonly CONSECUTIVE_1006_ROTATE_THRESHOLD: 2;
         /** Con trỏ mặc định khi bắt đầu kéo hàng đợi tin nhắn cũ (cmd 510 / 511) */
-        readonly OLD_MSG_INITIAL_CURSOR: "10000000000000000";
-        readonly INITIAL_OLD_MESSAGES_CURSOR: "10000000000000000";
+        readonly OLD_MSG_INITIAL_CURSOR: "1";
+        readonly INITIAL_OLD_MESSAGES_CURSOR: "1";
     };
     readonly UPLOAD: {
         /** Thời gian sống tối đa của uploadCallback trong bộ nhớ trước khi tự hủy (5 phút) */

package/dist/constants/defaults.js

@@ -35,8 +35,8 @@ export const ZALO_DEFAULTS = {
         /** Số lần lỗi 1006 liên tiếp trước khi xoay sang WebSocket endpoint tiếp theo */
         CONSECUTIVE_1006_ROTATE_THRESHOLD: 2,
         /** Con trỏ mặc định khi bắt đầu kéo hàng đợi tin nhắn cũ (cmd 510 / 511) */
-        OLD_MSG_INITIAL_CURSOR: "10000000000000000",
-        INITIAL_OLD_MESSAGES_CURSOR: "10000000000000000",
+        OLD_MSG_INITIAL_CURSOR: "1",
+        INITIAL_OLD_MESSAGES_CURSOR: "1",
     },
     UPLOAD: {
         /** Thời gian sống tối đa của uploadCallback trong bộ nhớ trước khi tự hủy (5 phút) */

package/dist/constants/protocol.d.ts

@@ -10,7 +10,7 @@ export declare const ZALO_PROTOCOL: {
     readonly API_VERSION: 689;
     readonly DEFAULT_API_VERSION: 689;
     /** Phiên bản SDK hiện tại */
-    readonly SDK_VERSION: "2.3.6";
+    readonly SDK_VERSION: "2.3.7";
     /** Mã zpw_type đặc thù dành riêng cho phân hệ Gọi Thoại & Video (binary C++ ZaloCall) */
     readonly VOICECALL_API_TYPE: 24;
     /** Phiên bản mã hóa ZCID (ParamDecryptor) */

package/dist/constants/protocol.js

@@ -10,7 +10,7 @@ export const ZALO_PROTOCOL = {
     API_VERSION: 689,
     DEFAULT_API_VERSION: 689,
     /** Phiên bản SDK hiện tại */
-    SDK_VERSION: "2.3.6",
+    SDK_VERSION: "2.3.7",
     /** Mã zpw_type đặc thù dành riêng cho phân hệ Gọi Thoại & Video (binary C++ ZaloCall) */
     VOICECALL_API_TYPE: 24,
     /** Phiên bản mã hóa ZCID (ParamDecryptor) */

package/dist/index.d.ts

@@ -256,6 +256,10 @@ export type { SendRequestVoiceCallOptions, SendRequestVoiceCallResponse } from "
 export type { ShareScreenGroupCallOptions, ShareScreenGroupCallResponse } from "./apis/call/shareScreenGroupCall.js";
 export type { UnholdVoiceCallOptions, UnholdVoiceCallResponse } from "./apis/call/unholdVoiceCall.js";
 export type { UpdateCallMediaStateOptions, UpdateCallMediaStateResponse } from "./apis/call/updateCallMediaState.js";
+export type { BlockOAResponse } from "./apis/business/blockOA.js";
+export type { UnblockOAResponse } from "./apis/business/unblockOA.js";
+export type { ConvertOAIdsResponse } from "./apis/business/convertOAIds.js";
+export type { GetOAProfileOptions, GetOAProfileResponse } from "./apis/business/getOAProfile.js";
 export { CloseReason } from "./apis/listen.js";
 export { LoginQRCallbackEventType } from "./apis/loginQR.js";
 export { FriendRecommendationsType } from "./apis/friend/getFriendRecommendations.js";

package/dist/models/Message.d.ts

@@ -1,4 +1,5 @@
 import { ThreadType } from "./Enum.js";
+import { type ParsedOAMessage } from "./OAMessage.js";
 export type TAttachmentContent = {
     title: string;
     description: string;
@@ -76,7 +77,17 @@ export declare class UserMessage {
      * true if the message is sent by the logged in account
      */
     isSelf: boolean;
-    constructor(uid: string, data: TMessage);
+    /**
+     * Dữ liệu đã giải mã nếu đây là tin nhắn từ Zalo Official Account (OA) (`pageMsgs`, `footerv2`, `chat.list.action`, `msginfo.actionlist`, hoặc `chat.ecard`).
+     */
+    oaData?: ParsedOAMessage;
+    constructor(uid: string, data: TMessage, isPageMsg?: boolean);
+    /**
+     * Kiểm tra xem tin nhắn có phải là tin nhắn Zalo Official Account (OA) hay không.
+     */
+    isOAMessage(): this is UserMessage & {
+        oaData: ParsedOAMessage;
+    };
 }
 export declare class GroupMessage {
     type: ThreadType.Group;

package/dist/models/Message.js

@@ -1,4 +1,5 @@
 import { ThreadType } from "./Enum.js";
+import { parseOAMessage } from "./OAMessage.js";
 export class UserMessage {
     type = ThreadType.User;
     data;
@@ -7,7 +8,11 @@ export class UserMessage {
      * true if the message is sent by the logged in account
      */
     isSelf;
-    constructor(uid, data) {
+    /**
+     * Dữ liệu đã giải mã nếu đây là tin nhắn từ Zalo Official Account (OA) (`pageMsgs`, `footerv2`, `chat.list.action`, `msginfo.actionlist`, hoặc `chat.ecard`).
+     */
+    oaData;
+    constructor(uid, data, isPageMsg = false) {
         this.data = data;
         this.threadId = data.uidFrom == "0" ? data.idTo : data.uidFrom;
         this.isSelf = data.uidFrom == "0";
@@ -18,6 +23,16 @@ export class UserMessage {
         if (data.quote) {
             data.quote.ownerId = String(data.quote.ownerId);
         }
+        const parsedOA = parseOAMessage(data, { isPageMsg });
+        if (parsedOA) {
+            this.oaData = parsedOA;
+        }
+    }
+    /**
+     * Kiểm tra xem tin nhắn có phải là tin nhắn Zalo Official Account (OA) hay không.
+     */
+    isOAMessage() {
+        return this.oaData !== undefined;
     }
 }
 export class GroupMessage {

package/dist/models/OAMessage.d.ts

@@ -0,0 +1,221 @@
+export type OAHighlightItem = string | number | {
+    type?: number;
+    uid?: string;
+    dpn?: string;
+    text?: string;
+    value?: string;
+    ts?: number;
+    [key: string]: unknown;
+};
+export type OACustomMessage = {
+    msg?: {
+        vi?: string;
+        en?: string;
+        [lang: string]: string | undefined;
+    };
+    previewTxt?: string;
+    highLightsV2?: OAHighlightItem[];
+    [key: string]: unknown;
+};
+export type OAListActionItem = {
+    type?: string;
+    title?: string;
+    description?: string;
+    thumb?: string;
+    href?: string;
+    childnumber?: number;
+    action?: string;
+    params?: string | Record<string, unknown>;
+    childAction?: unknown[];
+    [key: string]: unknown;
+};
+export type OAFooterItem = {
+    title?: string;
+    label?: string;
+    text?: string;
+    type?: number | string;
+    action?: string;
+    href?: string;
+    url?: string;
+    data?: unknown;
+    [key: string]: unknown;
+};
+export type OAFooterData = {
+    type?: number;
+    canForward: boolean;
+    footerList: OAFooterItem[];
+    raw?: unknown;
+};
+export type OAMessageKind = "oa_chat" | "oa_list" | "info_chat" | "ecard";
+export type ParsedOAMessage = {
+    /**
+     * Phân loại tin nhắn Zalo Official Account (OA):
+     * - `"oa_chat"`: Tin nhắn hội thoại trực tiếp 2 chiều từ/đến Zalo OA (`pageMsgs`, có `footerv2`, hoặc `topOut === "1"`).
+     * - `"oa_list"`: `msgType === "chat.list.action"` (Danh sách bài viết / thẻ hành động đa phương tiện từ OA).
+     * - `"info_chat"`: `msgType === "webchat"` với `content.action === "msginfo.actionlist"` hoặc `"msginfo.action"` (Thông báo sự kiện/trạng thái OA).
+     * - `"ecard"`: `msgType === "chat.ecard"` (Thiệp chúc mừng / thông báo sinh nhật / sự kiện OA).
+     */
+    kind: OAMessageKind;
+    /**
+     * Nội dung văn bản hiển thị đã được giải mã và điền đầy đủ các biến `%1$s` / `$1$s`.
+     */
+    text: string;
+    /**
+     * Văn bản thông báo tiếng Việt (nếu có trong `customMsg.msg.vi`).
+     */
+    textVi?: string;
+    /**
+     * Văn bản thông báo tiếng Anh (nếu có trong `customMsg.msg.en`).
+     */
+    textEn?: string;
+    /**
+     * Dữ liệu chi tiết đính kèm trong `content` / `params` của tin nhắn OA.
+     */
+    bundleData: Record<string, unknown>;
+    /**
+     * Danh sách các thẻ bài viết / nút hành động (dành cho `chat.list.action`).
+     */
+    items?: OAListActionItem[];
+    /**
+     * Cấu hình chân trang tương tác (`footerv2`) đính kèm tin nhắn OA (danh sách nút bấm `footerList`, cờ `canForward`).
+     */
+    footer?: OAFooterData;
+    /**
+     * Cờ đánh dấu tin nhắn nổi bật từ OA (`topOut === "1"`).
+     */
+    topOut?: boolean;
+    /**
+     * Cờ cho phép trả lời trực tiếp tin nhắn OA.
+     */
+    canReply?: boolean;
+    /**
+     * Dữ liệu `customMsg` / `params` nguyên bản sau khi parse JSON.
+     */
+    metadata?: {
+        customMsg?: OACustomMessage;
+        [key: string]: unknown;
+    };
+};
+export type OAFieldEntry = {
+    label?: string;
+    value?: string;
+    icon?: string;
+    [key: string]: unknown;
+};
+export type OARawInfo = {
+    description?: string | null;
+    appUrl?: string | null;
+    hotline?: OAFieldEntry | null;
+    category?: OAFieldEntry | null;
+    website?: OAFieldEntry | null;
+    address?: OAFieldEntry | null;
+    openTime?: OAFieldEntry | null;
+    group_msg?: number;
+    [key: string]: unknown;
+};
+export type OADnrStatus = {
+    isBlocked: boolean;
+    enableDnr: boolean;
+    dnrType: number | null;
+    dnrText: string | null;
+    raw?: unknown;
+};
+export type OAProfileInfo = {
+    oaId: string;
+    displayName: string;
+    zaloName: string;
+    username: string;
+    avatar: string;
+    cover: string;
+    globalId: string;
+    type: number;
+    isOA: boolean;
+    isVerified: boolean;
+    isZaloBot: boolean;
+    isBlocked: boolean;
+    isGroupedMsg: boolean;
+    description: string;
+    category: string;
+    address: string;
+    website: string;
+    hotline: string;
+    openTime: string;
+    email: string;
+    appUrl: string | null;
+    dnrStatus: OADnrStatus;
+    oaInfo: OARawInfo | null;
+    rawProfile: Record<string, unknown>;
+    bizAccount?: Record<string, unknown> | null;
+};
+export type TOAEventData = {
+    uids: string[];
+    [key: string]: unknown;
+};
+export type OAEvent = {
+    act: "block" | "unblock" | string;
+    act_type: "oa";
+    data: TOAEventData;
+    isBlocked: boolean;
+    oaIds: string[];
+};
+/**
+ * Điền các biến `%1$s`, `%2$s`... và `$1$s`, `$2$s`... trong mẫu chuỗi thông báo Zalo OA
+ * theo chuẩn hàm `_renderItemReplace` trên Zalo PC.
+ */
+export declare function formatOAHighlightText(templateText?: string, highLightsV2?: OAHighlightItem[]): string;
+/**
+ * Bóc tách cấu hình chân trang tương tác `footerv2` / `footer` của tin nhắn Zalo OA
+ * (`footerList`, `canForward`, `type`).
+ */
+export declare function parseOAFooter(rawFooter: unknown): OAFooterData | undefined;
+/**
+ * Kiểm tra xem một hồ sơ người dùng có phải là Zalo Official Account (OA) hay không.
+ * Theo chuẩn `isOA(profile)` trên Zalo PC: `profile.type > 0` hoặc có `profile.oaInfo`.
+ */
+export declare function isOAProfile(profile: {
+    type?: number;
+    oaInfo?: unknown;
+} | null | undefined): boolean;
+/**
+ * Kiểm tra xem Zalo OA có tích vàng xác thực (Verified OA) hay không.
+ * Theo chuẩn `isOAVerifiedByInfo(profile)` trên Zalo PC (`@10388120`):
+ * Chuyển `profile.type` sang nhị phân (`Number(type).toString(2)`), kiểm tra độ dài >= 3 và ký tự index `2` là `"1"`.
+ * Ví dụ: `type = 7` (`"111"`) -> Verified OA; `type = 5` (`"101"`) -> Verified OA.
+ */
+export declare function isOAVerified(profileOrType: {
+    type?: number;
+} | number | null | undefined): boolean;
+/**
+ * Kiểm tra xem tài khoản có phải là Zalo Bot hay không.
+ * Theo chuẩn `isZaloBotByInfo(profile)` trên Zalo PC (`@10388180`):
+ * Chuyển `profile.type` sang nhị phân (`Number(type).toString(2)`), kiểm tra độ dài >= 4 và ký tự đầu tiên là `"1"`.
+ */
+export declare function isZaloBot(profileOrType: {
+    type?: number;
+} | number | null | undefined): boolean;
+/**
+ * Giải mã trạng thái chặn & Do-Not-Disturb (`oa_status`) của Zalo OA
+ * theo chuẩn `_getOAStatus` trên Zalo PC (`@1719856`).
+ */
+export declare function parseOADnrStatus(oaStatus: unknown, fallbackIsBlocked?: number | boolean): OADnrStatus;
+/**
+ * Chuẩn hóa dữ liệu hồ sơ Zalo Official Account (`getUserInfo` + `getBizAccount`) thành cấu trúc `OAProfileInfo` đồng nhất.
+ */
+export declare function normalizeOAProfile(oaId: string, rawProfile?: Record<string, unknown> | null, bizAccount?: Record<string, unknown> | null): OAProfileInfo;
+/**
+ * Bóc tách và giải mã các loại tin nhắn từ Zalo Official Account (OA):
+ * - Danh sách bài viết / thẻ hành động OA (`chat.list.action`, bao gồm `l.a.header.full`, `l.a.normal`)
+ * - Thông báo sự kiện OA (`webchat` với `action === "msginfo.actionlist"` hoặc `"msginfo.action"`)
+ * - Thiệp chúc mừng / sự kiện OA (`chat.ecard`)
+ * - Tin nhắn hội thoại trực tiếp 2 chiều với OA (`pageMsgs`, có `footerv2`, hoặc `topOut === "1"`)
+ *
+ * Trả về `undefined` nếu tin nhắn là tin nhắn cá nhân thông thường không thuộc Zalo OA.
+ */
+export declare function parseOAMessage(msg: {
+    msgType: string;
+    content: unknown;
+    [key: string]: unknown;
+}, options?: {
+    isPageMsg?: boolean;
+}): ParsedOAMessage | undefined;
+export declare function initializeOAEvent(data: TOAEventData, act: string): OAEvent;