@softtynet/zca-js 2.2.9 → 2.3.1

package/dist/cjs/zalo.cjs

@@ -8,11 +8,14 @@ var toughCookie = require('tough-cookie');
 var ZaloApiError = require('./Errors/ZaloApiError.cjs');
 var update = require('./update.cjs');
 var apis = require('./apis.cjs');
+var domains = require('./constants/domains.cjs');
+var defaults = require('./constants/defaults.cjs');
 
 class Zalo {
+    options;
+    enableEncryptParam = true;
     constructor(options = {}) {
         this.options = options;
-        this.enableEncryptParam = true;
     }
     parseCookies(cookie) {
         const cookieArr = Array.isArray(cookie) ? cookie : cookie.cookies;
@@ -23,9 +26,12 @@ class Zalo {
         const jar = new toughCookie.CookieJar();
         for (const each of cookieArr) {
             try {
-                const cookieObj = toughCookie.Cookie.fromJSON(Object.assign(Object.assign({}, each), { key: each.key || each.name }));
+                const cookieObj = toughCookie.Cookie.fromJSON({
+                    ...each,
+                    key: each.key || each.name,
+                });
                 if (cookieObj) {
-                    const domain = cookieObj.domain || "chat.zalo.me";
+                    const domain = cookieObj.domain || domains.ZALO_DOMAINS.DEFAULT_COOKIE_DOMAIN;
                     const url = `https://${domain.startsWith(".") ? domain.slice(1) : domain}`;
                     jar.setCookieSync(cookieObj, url);
                 }
@@ -56,10 +62,10 @@ class Zalo {
         ctx.imei = credentials.imei;
         ctx.cookie = this.parseCookies(credentials.cookie);
         ctx.userAgent = credentials.userAgent;
-        ctx.language = credentials.language || "vi";
+        ctx.language = credentials.language || defaults.ZALO_DEFAULTS.BROWSER.DEFAULT_LANGUAGE;
         const loginData = await login.login(ctx, this.enableEncryptParam);
         const serverInfo = await login.getServerInfo(ctx, this.enableEncryptParam);
-        const loginInfo = loginData === null || loginData === void 0 ? void 0 : loginData.data;
+        const loginInfo = loginData?.data;
         if (!loginData || !loginInfo || !serverInfo)
             throw new ZaloApiError.ZaloApiError("Đăng nhập thất bại");
         ctx.secretKey = loginInfo.zpw_enk;
@@ -78,10 +84,9 @@ class Zalo {
         if (!options)
             options = {};
         if (!options.userAgent)
-            options.userAgent =
-                "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36";
+            options.userAgent = defaults.ZALO_DEFAULTS.BROWSER.DEFAULT_USER_AGENT;
         if (!options.language)
-            options.language = "vi";
+            options.language = defaults.ZALO_DEFAULTS.BROWSER.DEFAULT_LANGUAGE;
         const ctx = context.createContext(this.options.apiType, this.options.apiVersion);
         Object.assign(ctx.options, this.options);
         const loginQRResult = await loginQR.loginQR(ctx, options, callback);

package/dist/constants/defaults.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Tập trung toàn bộ các hằng số vận hành, giới hạn phân trang, thời gian chờ (Timeouts)
+ * và cấu hình Codec mặc định cho Gọi Thoại / Video.
+ */
+export declare const ZALO_DEFAULTS: {
+    readonly OPTIONS: {
+        readonly SELF_LISTEN: false;
+        readonly CHECK_UPDATE: true;
+        readonly LOGGING: true;
+    };
+    readonly BROWSER: {
+        readonly DEFAULT_LANGUAGE: "vi";
+        readonly DEFAULT_PLATFORM: "Windows";
+        readonly DEFAULT_CHROME_VERSION: "133";
+        readonly COMPUTER_NAME: "Web";
+        readonly DEFAULT_USER_AGENT: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36";
+        readonly ACCEPT_LANGUAGE_VI: "vi-VN,vi;q=0.9,en-US;q=0.8,en;q=0.7";
+        readonly ACCEPT_LANGUAGE_EN: "en-US,en;q=0.9,vi;q=0.8";
+    };
+    readonly CHAT: {
+        readonly MAX_MESSAGES_PER_SEND: 50;
+    };
+    readonly SOCKET: {
+        /** Khoảng thời gian tối thiểu gửi gói tin Ping (ms) */
+        readonly MIN_PING_INTERVAL_MS: 10000;
+        readonly PING_INTERVAL_MIN_MS: 10000;
+        /** Khoảng thời gian tối đa gửi gói tin Ping (ms) */
+        readonly MAX_PING_INTERVAL_MS: 25000;
+        readonly PING_INTERVAL_MAX_MS: 25000;
+        readonly DEFAULT_PING_INTERVAL_MS: 25000;
+        /** Thời gian Watchdog tự động ép kết nối lại nếu không nhận được gói tin nào (ms) */
+        readonly WATCHDOG_TIMEOUT_MS: 50000;
+        /** Thời gian chờ tối đa khi xoay vòng thử lại kết nối (ms) */
+        readonly MAX_RETRY_BACKOFF_MS: 30000;
+        /** 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 UPLOAD: {
+        /** Thời gian sống tối đa của uploadCallback trong bộ nhớ trước khi tự hủy (5 phút) */
+        readonly CALLBACK_TTL_MS: number;
+        /** Kích thước mỗi khối tính MD5 cho file lớn (2MB) */
+        readonly MD5_CHUNK_SIZE_BYTES: number;
+    };
+    readonly ZCLOUD: {
+        /** Thời gian cache cặp khóa { viewer_key, enk } trong phiên (15 phút) */
+        readonly VIEWER_KEY_CACHE_TTL_MS: number;
+    };
+    readonly PAGINATION: {
+        /** Kích thước ảnh đại diện mặc định (px) */
+        readonly DEFAULT_AVATAR_SIZE: 120;
+        /** Số lượng tin nhắn lịch sử nhóm mặc định mỗi lần tải */
+        readonly DEFAULT_GROUP_HISTORY_COUNT: 50;
+        /** Giới hạn an toàn tối đa khi tải lịch sử tin nhắn nhóm */
+        readonly MAX_GROUP_HISTORY_COUNT: 200;
+        /** Số lượng tin nhắn tối đa mỗi trang của Zalo Cloud Message */
+        readonly GROUP_CLOUD_PAGE_SIZE: 50;
+    };
+    readonly VOICECALL: {
+        /** Danh sách Audio Codec chuẩn của binary C++ ZaloCall */
+        readonly AUDIO_CODECS: readonly [{
+            readonly channels: 1;
+            readonly clockrate: 16000;
+            readonly name: "speex";
+            readonly payload: 99;
+        }, {
+            readonly channels: 1;
+            readonly clockrate: 8000;
+            readonly name: "speex";
+            readonly payload: 98;
+        }, {
+            readonly channels: 1;
+            readonly clockrate: 8000;
+            readonly name: "opus";
+            readonly payload: 109;
+        }, {
+            readonly channels: 1;
+            readonly clockrate: 8000;
+            readonly name: "AMR-NB";
+            readonly payload: 106;
+        }, {
+            readonly channels: 1;
+            readonly clockrate: 16000;
+            readonly name: "opus";
+            readonly payload: 112;
+        }];
+        /** Danh sách Video Codec H.264 chuẩn của binary C++ ZaloCall */
+        readonly VIDEO_CODECS: readonly [{
+            readonly clockrate: 90000;
+            readonly name: "h264";
+            readonly payload: 97;
+        }];
+    };
+};

package/dist/constants/defaults.js

@@ -0,0 +1,73 @@
+/**
+ * Tập trung toàn bộ các hằng số vận hành, giới hạn phân trang, thời gian chờ (Timeouts)
+ * và cấu hình Codec mặc định cho Gọi Thoại / Video.
+ */
+export const ZALO_DEFAULTS = {
+    OPTIONS: {
+        SELF_LISTEN: false,
+        CHECK_UPDATE: true,
+        LOGGING: true,
+    },
+    BROWSER: {
+        DEFAULT_LANGUAGE: "vi",
+        DEFAULT_PLATFORM: "Windows",
+        DEFAULT_CHROME_VERSION: "133",
+        COMPUTER_NAME: "Web",
+        DEFAULT_USER_AGENT: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36",
+        ACCEPT_LANGUAGE_VI: "vi-VN,vi;q=0.9,en-US;q=0.8,en;q=0.7",
+        ACCEPT_LANGUAGE_EN: "en-US,en;q=0.9,vi;q=0.8",
+    },
+    CHAT: {
+        MAX_MESSAGES_PER_SEND: 50,
+    },
+    SOCKET: {
+        /** Khoảng thời gian tối thiểu gửi gói tin Ping (ms) */
+        MIN_PING_INTERVAL_MS: 10_000,
+        PING_INTERVAL_MIN_MS: 10_000,
+        /** Khoảng thời gian tối đa gửi gói tin Ping (ms) */
+        MAX_PING_INTERVAL_MS: 25_000,
+        PING_INTERVAL_MAX_MS: 25_000,
+        DEFAULT_PING_INTERVAL_MS: 25_000,
+        /** Thời gian Watchdog tự động ép kết nối lại nếu không nhận được gói tin nào (ms) */
+        WATCHDOG_TIMEOUT_MS: 50_000,
+        /** Thời gian chờ tối đa khi xoay vòng thử lại kết nối (ms) */
+        MAX_RETRY_BACKOFF_MS: 30_000,
+        /** 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",
+    },
+    UPLOAD: {
+        /** Thời gian sống tối đa của uploadCallback trong bộ nhớ trước khi tự hủy (5 phút) */
+        CALLBACK_TTL_MS: 5 * 60 * 1000,
+        /** Kích thước mỗi khối tính MD5 cho file lớn (2MB) */
+        MD5_CHUNK_SIZE_BYTES: 2 * 1024 * 1024,
+    },
+    ZCLOUD: {
+        /** Thời gian cache cặp khóa { viewer_key, enk } trong phiên (15 phút) */
+        VIEWER_KEY_CACHE_TTL_MS: 15 * 60 * 1000,
+    },
+    PAGINATION: {
+        /** Kích thước ảnh đại diện mặc định (px) */
+        DEFAULT_AVATAR_SIZE: 120,
+        /** Số lượng tin nhắn lịch sử nhóm mặc định mỗi lần tải */
+        DEFAULT_GROUP_HISTORY_COUNT: 50,
+        /** Giới hạn an toàn tối đa khi tải lịch sử tin nhắn nhóm */
+        MAX_GROUP_HISTORY_COUNT: 200,
+        /** Số lượng tin nhắn tối đa mỗi trang của Zalo Cloud Message */
+        GROUP_CLOUD_PAGE_SIZE: 50,
+    },
+    VOICECALL: {
+        /** Danh sách Audio Codec chuẩn của binary C++ ZaloCall */
+        AUDIO_CODECS: [
+            { channels: 1, clockrate: 16000, name: "speex", payload: 99 },
+            { channels: 1, clockrate: 8000, name: "speex", payload: 98 },
+            { channels: 1, clockrate: 8000, name: "opus", payload: 109 },
+            { channels: 1, clockrate: 8000, name: "AMR-NB", payload: 106 },
+            { channels: 1, clockrate: 16000, name: "opus", payload: 112 },
+        ],
+        /** Danh sách Video Codec H.264 chuẩn của binary C++ ZaloCall */
+        VIDEO_CODECS: [{ clockrate: 90000, name: "h264", payload: 97 }],
+    },
+};

package/dist/constants/domains.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Danh mục tập trung toàn bộ các Domain gốc & Domain dự phòng (Fallback) của Zalo.
+ * Thay vì viết cứng rải rác trong hàng trăm file API, toàn bộ hệ thống tham chiếu từ đây.
+ */
+export declare const ZALO_DOMAINS: {
+    /** Domain gốc của Zalo Chat Web (dùng cho Cookie, Origin, Referer) */
+    readonly CHAT_WEB: "https://chat.zalo.me";
+    readonly DEFAULT_COOKIE_DOMAIN: "chat.zalo.me";
+    /** Domain xác thực tài khoản và đăng nhập QR */
+    readonly AUTH_ID: "https://id.zalo.me";
+    readonly ID_ZALO: "https://id.zalo.me";
+    /** Domain WPA mặc định (dùng cho login, getServerInfo, getCloudViewerKey, getFamilyViewerKey) */
+    readonly WPA_CHAT: "https://wpa.chat.zalo.me";
+    /** Domain dự phòng (Fallback) cho dịch vụ ánh xạ ZNoise ID (command 12390) */
+    readonly ZWID_API: "https://zwid.api.zalo.me";
+    readonly ZNOISE_FALLBACK: "https://zwid.api.zalo.me";
+    /** Domain mặc định cho hệ sinh thái ZCloud (nếu zpwServiceMap.zcloud chưa trả về) */
+    readonly ZCLOUD_FALLBACK: "https://zcld.chat.zalo.me";
+    readonly ZCLOUD_DEFAULT: "https://zcld.chat.zalo.me";
+    /** Domain mặc định cho hệ sinh thái ZFamily (nếu zpwServiceMap.zfamily chưa trả về) */
+    readonly ZFAMILY_FALLBACK: "https://zfml.chat.zalo.me";
+    readonly ZFAMILY_DEFAULT: "https://zfml.chat.zalo.me";
+    /** Domain mặc định cho tính năng AI (Voice-to-Text command 13394) */
+    readonly AI_FEATURES_FALLBACK: "https://tt-ai-features-wpa.chat.zalo.me";
+    readonly AI_FEATURES_DEFAULT: "https://tt-ai-features-wpa.chat.zalo.me";
+    /** Domain mặc định cho dịch vụ Emoji Status (command 16300 / 16301) */
+    readonly EMOJI_STATUS_FALLBACK: "https://emoji-status.chat.zalo.me";
+    readonly EMOJI_STATUS_DEFAULT: "https://emoji-status.chat.zalo.me";
+    /** Domain TransferSync tải file sao lưu .db.crypt từ điện thoại */
+    readonly TRANSFER_SYNC: "https://transfersync.zaloapp.com";
+    /** Domain kiểm tra phiên bản NPM */
+    readonly NPM_REGISTRY: "https://registry.npmjs.org/@softtynet/zca-js";
+    readonly NPM_REGISTRY_PACKAGE: "https://registry.npmjs.org/@softtynet/zca-js";
+};

package/dist/constants/domains.js

@@ -0,0 +1,34 @@
+/**
+ * Danh mục tập trung toàn bộ các Domain gốc & Domain dự phòng (Fallback) của Zalo.
+ * Thay vì viết cứng rải rác trong hàng trăm file API, toàn bộ hệ thống tham chiếu từ đây.
+ */
+export const ZALO_DOMAINS = {
+    /** Domain gốc của Zalo Chat Web (dùng cho Cookie, Origin, Referer) */
+    CHAT_WEB: "https://chat.zalo.me",
+    DEFAULT_COOKIE_DOMAIN: "chat.zalo.me",
+    /** Domain xác thực tài khoản và đăng nhập QR */
+    AUTH_ID: "https://id.zalo.me",
+    ID_ZALO: "https://id.zalo.me",
+    /** Domain WPA mặc định (dùng cho login, getServerInfo, getCloudViewerKey, getFamilyViewerKey) */
+    WPA_CHAT: "https://wpa.chat.zalo.me",
+    /** Domain dự phòng (Fallback) cho dịch vụ ánh xạ ZNoise ID (command 12390) */
+    ZWID_API: "https://zwid.api.zalo.me",
+    ZNOISE_FALLBACK: "https://zwid.api.zalo.me",
+    /** Domain mặc định cho hệ sinh thái ZCloud (nếu zpwServiceMap.zcloud chưa trả về) */
+    ZCLOUD_FALLBACK: "https://zcld.chat.zalo.me",
+    ZCLOUD_DEFAULT: "https://zcld.chat.zalo.me",
+    /** Domain mặc định cho hệ sinh thái ZFamily (nếu zpwServiceMap.zfamily chưa trả về) */
+    ZFAMILY_FALLBACK: "https://zfml.chat.zalo.me",
+    ZFAMILY_DEFAULT: "https://zfml.chat.zalo.me",
+    /** Domain mặc định cho tính năng AI (Voice-to-Text command 13394) */
+    AI_FEATURES_FALLBACK: "https://tt-ai-features-wpa.chat.zalo.me",
+    AI_FEATURES_DEFAULT: "https://tt-ai-features-wpa.chat.zalo.me",
+    /** Domain mặc định cho dịch vụ Emoji Status (command 16300 / 16301) */
+    EMOJI_STATUS_FALLBACK: "https://emoji-status.chat.zalo.me",
+    EMOJI_STATUS_DEFAULT: "https://emoji-status.chat.zalo.me",
+    /** Domain TransferSync tải file sao lưu .db.crypt từ điện thoại */
+    TRANSFER_SYNC: "https://transfersync.zaloapp.com",
+    /** Domain kiểm tra phiên bản NPM */
+    NPM_REGISTRY: "https://registry.npmjs.org/@softtynet/zca-js",
+    NPM_REGISTRY_PACKAGE: "https://registry.npmjs.org/@softtynet/zca-js",
+};

package/dist/constants/endpoints.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Bảng định danh đường dẫn Endpoint (Endpoint Registry) theo từng miền dịch vụ của Zalo PC 26.7.10.
+ * Giúp tra cứu nhanh và cập nhật tập trung khi Zalo thay đổi đường dẫn API.
+ */
+export declare const ZALO_ENDPOINTS: {
+    readonly WPA: {
+        readonly LOGIN_GET_LOGIN_INFO: "/api/login/getLoginInfo";
+        readonly LOGIN_GET_SERVER_INFO: "/api/login/getServerInfo";
+        readonly SETTING_ME: "/api/setting/me";
+        readonly SETTING_UPDATE: "/api/setting/update";
+        readonly GET_CLOUD_VIEWER_KEY: "/api/getCloudViewerKey";
+        readonly GET_FAMILY_VIEWER_KEY: "/api/getFamilyViewerKey";
+    };
+    readonly ZWID: {
+        readonly ZNOISE: "/api/znoise";
+    };
+    readonly TRANSFER_SYNC: {
+        readonly DOWNLOAD_V2: "/api/transfer-sync-v2/download";
+    };
+    readonly AUTH: {
+        readonly LOGIN_GET_LOGIN_INFO: "/api/login/getLoginInfo";
+        readonly LOGIN_GET_SERVER_INFO: "/api/login/getServerInfo";
+        readonly KEEP_ALIVE: "/keepalive";
+    };
+    readonly ZCLOUD: {
+        readonly GET_CLOUD_VIEWER_KEY: "/api/getCloudViewerKey";
+        readonly GET_FAMILY_VIEWER_KEY: "/api/getFamilyViewerKey";
+        readonly USAGE_V2: "/cloudmedia/info/pc/v2/usage";
+        readonly USAGE_MYCLOUD: "/cloudmedia/info/pc/v1/usage-mycloud";
+        readonly CLOUD_SETTINGS: "/cloudmedia/info/pc/v1/cloud-settings";
+        readonly CLOUD_INFO: "/zalocloud/cloudinfopcweb/v1/info";
+        readonly FAMILY_USAGE: "/cloudmedia/info/pc/v1/family-usage";
+        readonly VERIFY_QUEUE: "/cloudmedia/queue/pc/verify";
+        readonly FAMILY_PROFILE: "/zfamily/pc/family-profile/v1/family";
+    };
+    readonly SYNC: {
+        readonly PRELOAD_CONVERSATIONS: "/api/preloadconvers/get-last-msgs";
+        readonly GET_LAST_SEEN: "/api/preloadconvers/get-last-seen";
+        readonly PULL_MOBILE_MSG: "/api/message/pull_mobile_msg";
+        readonly CANCEL_PULL_MOBILE_MSG: "/api/message/cancel_pull_mobile_msg";
+        readonly ZNOISE: "/api/znoise";
+        readonly ENCRYPT_GIDS: "/api/gid/encrypt";
+        readonly DECRYPT_GIDS: "/api/gid/decrypt";
+    };
+    readonly CALL: {
+        readonly REQUEST_CALL: "/api/voicecall/requestcall";
+        readonly SEND_REQUEST: "/api/voicecall/request";
+        readonly CANCEL_CALL: "/api/voicecall/cancel";
+        readonly END_CALL: "/api/voicecall/endcall";
+    };
+    readonly AI: {
+        readonly VOICE_TO_TEXT: "/api/aifeatures/voice2text";
+    };
+    readonly EMOJI_STATUS: {
+        readonly RESOURCE_CONFIG: "/api/v1/emoji-status/resource-config";
+        readonly FRIENDS_LIST: "/api/v1/emoji-status/friends";
+    };
+    readonly MEDIA_STORE: {
+        readonly LIST: "/api/mediastore/list";
+        readonly PREVIEW: "/api/mediastore/preview";
+        readonly REMOVE: "/api/mediastore/remove";
+    };
+    readonly RECENT_SEARCH: {
+        readonly LIST: "/api/recentsearch/list";
+        readonly UPDATE: "/api/recentsearch/update";
+    };
+};

package/dist/constants/endpoints.js

@@ -0,0 +1,67 @@
+/**
+ * Bảng định danh đường dẫn Endpoint (Endpoint Registry) theo từng miền dịch vụ của Zalo PC 26.7.10.
+ * Giúp tra cứu nhanh và cập nhật tập trung khi Zalo thay đổi đường dẫn API.
+ */
+export const ZALO_ENDPOINTS = {
+    WPA: {
+        LOGIN_GET_LOGIN_INFO: "/api/login/getLoginInfo",
+        LOGIN_GET_SERVER_INFO: "/api/login/getServerInfo",
+        SETTING_ME: "/api/setting/me",
+        SETTING_UPDATE: "/api/setting/update",
+        GET_CLOUD_VIEWER_KEY: "/api/getCloudViewerKey",
+        GET_FAMILY_VIEWER_KEY: "/api/getFamilyViewerKey",
+    },
+    ZWID: {
+        ZNOISE: "/api/znoise",
+    },
+    TRANSFER_SYNC: {
+        DOWNLOAD_V2: "/api/transfer-sync-v2/download",
+    },
+    AUTH: {
+        LOGIN_GET_LOGIN_INFO: "/api/login/getLoginInfo",
+        LOGIN_GET_SERVER_INFO: "/api/login/getServerInfo",
+        KEEP_ALIVE: "/keepalive",
+    },
+    ZCLOUD: {
+        GET_CLOUD_VIEWER_KEY: "/api/getCloudViewerKey",
+        GET_FAMILY_VIEWER_KEY: "/api/getFamilyViewerKey",
+        USAGE_V2: "/cloudmedia/info/pc/v2/usage",
+        USAGE_MYCLOUD: "/cloudmedia/info/pc/v1/usage-mycloud",
+        CLOUD_SETTINGS: "/cloudmedia/info/pc/v1/cloud-settings",
+        CLOUD_INFO: "/zalocloud/cloudinfopcweb/v1/info",
+        FAMILY_USAGE: "/cloudmedia/info/pc/v1/family-usage",
+        VERIFY_QUEUE: "/cloudmedia/queue/pc/verify",
+        FAMILY_PROFILE: "/zfamily/pc/family-profile/v1/family",
+    },
+    SYNC: {
+        PRELOAD_CONVERSATIONS: "/api/preloadconvers/get-last-msgs",
+        GET_LAST_SEEN: "/api/preloadconvers/get-last-seen",
+        PULL_MOBILE_MSG: "/api/message/pull_mobile_msg",
+        CANCEL_PULL_MOBILE_MSG: "/api/message/cancel_pull_mobile_msg",
+        ZNOISE: "/api/znoise",
+        ENCRYPT_GIDS: "/api/gid/encrypt",
+        DECRYPT_GIDS: "/api/gid/decrypt",
+    },
+    CALL: {
+        REQUEST_CALL: "/api/voicecall/requestcall",
+        SEND_REQUEST: "/api/voicecall/request",
+        CANCEL_CALL: "/api/voicecall/cancel",
+        END_CALL: "/api/voicecall/endcall",
+    },
+    AI: {
+        VOICE_TO_TEXT: "/api/aifeatures/voice2text",
+    },
+    EMOJI_STATUS: {
+        RESOURCE_CONFIG: "/api/v1/emoji-status/resource-config",
+        FRIENDS_LIST: "/api/v1/emoji-status/friends",
+    },
+    MEDIA_STORE: {
+        LIST: "/api/mediastore/list",
+        PREVIEW: "/api/mediastore/preview",
+        REMOVE: "/api/mediastore/remove",
+    },
+    RECENT_SEARCH: {
+        LIST: "/api/recentsearch/list",
+        UPDATE: "/api/recentsearch/update",
+    },
+};

package/dist/constants/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./protocol.js";
+export * from "./domains.js";
+export * from "./defaults.js";
+export * from "./endpoints.js";

package/dist/constants/index.js

@@ -0,0 +1,4 @@
+export * from "./protocol.js";
+export * from "./domains.js";
+export * from "./defaults.js";
+export * from "./endpoints.js";

package/dist/constants/protocol.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Chuẩn tham số giao thức cốt lõi của Zalo Web / Zalo PC (Single Source of Truth)
+ * Khi Zalo nâng cấp phiên bản giao thức mới, chỉ cần cập nhật tại file này.
+ */
+export declare const ZALO_PROTOCOL: {
+    /** Loại thiết bị mặc định (30 = Zalo Web / PC) */
+    readonly API_TYPE: 30;
+    readonly DEFAULT_API_TYPE: 30;
+    /** Phiên bản giao thức mặc định (689 = Zalo PC 26.7.10) */
+    readonly API_VERSION: 689;
+    readonly DEFAULT_API_VERSION: 689;
+    /** Phiên bản SDK hiện tại */
+    readonly SDK_VERSION: "2.3.1";
+    /** 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) */
+    readonly ENCRYPT_VERSION: "v2";
+    /** Tiền tố khóa ký MD5 cho tham số đăng nhập */
+    readonly SIGN_KEY_PREFIX: "zsecure";
+    /** Khóa tĩnh dùng để mã hóa ZCID trong ParamCipher của Zalo PC */
+    readonly PARAM_CIPHER_KEY: "3FC4F0D2AB50057BCE0D90D9187A22B1";
+    /** Chữ ký nhận diện định dạng container sao lưu từ điện thoại */
+    readonly ZDB_MAGIC_HEADER: "ZDB4.0";
+    /** Kích thước mỗi khối (chunk) giải mã AES-256-CBC của file sao lưu .db.crypt (64KB) */
+    readonly ZDB_CHUNK_SIZE: 65536;
+    /** Độ dài Vector khởi tạo ngẫu nhiên (IV) ghép ở đầu bản mã ZCloud / ZFamily (module 98yS) */
+    readonly ZCLOUD_IV_BYTE_LENGTH: 16;
+    /** Độ dài khóa AES-256 tính theo byte */
+    readonly AES_256_KEY_BYTE_LENGTH: 32;
+};

package/dist/constants/protocol.js

@@ -0,0 +1,30 @@
+/**
+ * Chuẩn tham số giao thức cốt lõi của Zalo Web / Zalo PC (Single Source of Truth)
+ * Khi Zalo nâng cấp phiên bản giao thức mới, chỉ cần cập nhật tại file này.
+ */
+export const ZALO_PROTOCOL = {
+    /** Loại thiết bị mặc định (30 = Zalo Web / PC) */
+    API_TYPE: 30,
+    DEFAULT_API_TYPE: 30,
+    /** Phiên bản giao thức mặc định (689 = Zalo PC 26.7.10) */
+    API_VERSION: 689,
+    DEFAULT_API_VERSION: 689,
+    /** Phiên bản SDK hiện tại */
+    SDK_VERSION: "2.3.1",
+    /** 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) */
+    ENCRYPT_VERSION: "v2",
+    /** Tiền tố khóa ký MD5 cho tham số đăng nhập */
+    SIGN_KEY_PREFIX: "zsecure",
+    /** Khóa tĩnh dùng để mã hóa ZCID trong ParamCipher của Zalo PC */
+    PARAM_CIPHER_KEY: "3FC4F0D2AB50057BCE0D90D9187A22B1",
+    /** Chữ ký nhận diện định dạng container sao lưu từ điện thoại */
+    ZDB_MAGIC_HEADER: "ZDB4.0",
+    /** Kích thước mỗi khối (chunk) giải mã AES-256-CBC của file sao lưu .db.crypt (64KB) */
+    ZDB_CHUNK_SIZE: 0x10000,
+    /** Độ dài Vector khởi tạo ngẫu nhiên (IV) ghép ở đầu bản mã ZCloud / ZFamily (module 98yS) */
+    ZCLOUD_IV_BYTE_LENGTH: 16,
+    /** Độ dài khóa AES-256 tính theo byte */
+    AES_256_KEY_BYTE_LENGTH: 32,
+};

package/dist/context.d.ts

@@ -167,11 +167,18 @@ declare class CallbacksMap extends Map<string, UploadCallback> {
      */
     set(key: string, value: UploadCallback, ttl?: number): this;
 }
+export type ViewerKeyCacheEntry = {
+    viewer_key: string;
+    enk: string;
+    expiresAt: number;
+};
 export type AppContextExtended = {
     uploadCallbacks: CallbacksMap;
     options: Options;
     readonly API_TYPE: number;
     readonly API_VERSION: number;
+    zcloudViewerKeyCache?: ViewerKeyCacheEntry;
+    zfamilyViewerKeyCache?: ViewerKeyCacheEntry;
 };
 export type ContextBase = Partial<AppContextBase> & AppContextExtended;
 export declare const createContext: (apiType?: number, apiVersion?: number) => ContextBase;
@@ -179,5 +186,5 @@ export type ContextSession = AppContextBase & AppContextExtended & {
     secretKey: string;
 };
 export declare function isContextSession(ctx: ContextBase): ctx is ContextSession;
-export declare const MAX_MESSAGES_PER_SEND = 50;
+export declare const MAX_MESSAGES_PER_SEND: 50;
 export {};

package/dist/context.js

@@ -1,4 +1,5 @@
-const _5_MINUTES = 5 * 60 * 1000;
+import { ZALO_DEFAULTS, ZALO_PROTOCOL } from "./constants/index.js";
+const _5_MINUTES = ZALO_DEFAULTS.UPLOAD.CALLBACK_TTL_MS;
 class CallbacksMap extends Map {
     /**
      * @param ttl Time to live in milliseconds. Default is 5 minutes.
@@ -10,14 +11,14 @@ class CallbacksMap extends Map {
         return super.set(key, value);
     }
 }
-export const createContext = (apiType = 30, apiVersion = 689) => ({
+export const createContext = (apiType = ZALO_PROTOCOL.API_TYPE, apiVersion = ZALO_PROTOCOL.API_VERSION) => ({
     API_TYPE: apiType,
     API_VERSION: apiVersion,
     uploadCallbacks: new CallbacksMap(),
     options: {
-        selfListen: false,
-        checkUpdate: true,
-        logging: true,
+        selfListen: ZALO_DEFAULTS.OPTIONS.SELF_LISTEN,
+        checkUpdate: ZALO_DEFAULTS.OPTIONS.CHECK_UPDATE,
+        logging: ZALO_DEFAULTS.OPTIONS.LOGGING,
         polyfill: global.fetch,
     },
     secretKey: null,
@@ -25,4 +26,4 @@ export const createContext = (apiType = 30, apiVersion = 689) => ({
 export function isContextSession(ctx) {
     return !!ctx.secretKey;
 }
-export const MAX_MESSAGES_PER_SEND = 50;
+export const MAX_MESSAGES_PER_SEND = ZALO_DEFAULTS.CHAT.MAX_MESSAGES_PER_SEND;

package/dist/core/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./service-router.js";
+export * from "./zcloud-client.js";

package/dist/core/index.js

@@ -0,0 +1,2 @@
+export * from "./service-router.js";
+export * from "./zcloud-client.js";

package/dist/core/service-router.d.ts

@@ -0,0 +1,10 @@
+import type { ZPWServiceMap } from "../context.js";
+/**
+ * Lấy danh sách toàn bộ các endpoint của một service từ `zpwServiceMap` (hoặc fallback về domain mặc định).
+ * Hỗ trợ cơ chế Multi-Endpoint Failover khi endpoint đầu tiên gặp sự cố mạng hoặc bảo trì.
+ */
+export declare function getServiceEndpoints<K extends keyof ZPWServiceMap>(zpwServiceMap: Partial<ZPWServiceMap> | undefined, serviceKey: K, fallbackDomain: string): string[];
+/**
+ * Lấy endpoint chính (primary) của một service từ `zpwServiceMap` (hoặc fallback về domain mặc định).
+ */
+export declare function getServiceEndpoint<K extends keyof ZPWServiceMap>(zpwServiceMap: Partial<ZPWServiceMap> | undefined, serviceKey: K, fallbackDomain: string): string;

package/dist/core/service-router.js

@@ -0,0 +1,17 @@
+/**
+ * Lấy danh sách toàn bộ các endpoint của một service từ `zpwServiceMap` (hoặc fallback về domain mặc định).
+ * Hỗ trợ cơ chế Multi-Endpoint Failover khi endpoint đầu tiên gặp sự cố mạng hoặc bảo trì.
+ */
+export function getServiceEndpoints(zpwServiceMap, serviceKey, fallbackDomain) {
+    const list = zpwServiceMap?.[serviceKey];
+    if (Array.isArray(list) && list.length > 0) {
+        return list;
+    }
+    return [fallbackDomain];
+}
+/**
+ * Lấy endpoint chính (primary) của một service từ `zpwServiceMap` (hoặc fallback về domain mặc định).
+ */
+export function getServiceEndpoint(zpwServiceMap, serviceKey, fallbackDomain) {
+    return getServiceEndpoints(zpwServiceMap, serviceKey, fallbackDomain)[0];
+}

package/dist/core/zcloud-client.d.ts

@@ -0,0 +1,31 @@
+import type { FactoryUtils } from "../utils.js";
+import type { API } from "../apis.js";
+import type { GetCloudViewerKeyResponse } from "../apis/zcloud/getCloudViewerKey.js";
+import type { GetFamilyViewerKeyResponse } from "../apis/zcloud/getFamilyViewerKey.js";
+export type ZCloudRequestOptions = {
+    url: string;
+    method?: "GET" | "POST";
+    body?: URLSearchParams | string;
+    paramsPayload?: Record<string, unknown>;
+    viewerKeyInfo?: GetCloudViewerKeyResponse;
+    allowEmptyDataOn904?: boolean;
+};
+/**
+ * Thực thi request tới hệ sinh thái ZCloud (`zcld.chat.zalo.me`) kèm cơ chế:
+ * 1. Tự động lấy `viewer_key` & `enk` từ bộ nhớ đệm (`ctx.zcloudViewerKeyCache`) nếu người dùng không truyền.
+ * 2. Tự động thử lại (Auto-Retry 1 lần với `forceRefresh = true`) nếu khóa `viewer_key` trong cache bị máy chủ từ chối do hết hạn sớm.
+ * 3. Tự động giải mã payload AES-256-CBC (Random 16-byte IV - module `98yS`).
+ */
+export declare function requestZCloudDecrypted<T>(api: API, utils: Pick<FactoryUtils<T>, "makeURL" | "request">, options: ZCloudRequestOptions): Promise<T>;
+export type ZFamilyRequestOptions = {
+    url: string;
+    method?: "GET" | "POST";
+    body?: URLSearchParams | string;
+    viewerKeyInfo?: GetFamilyViewerKeyResponse;
+    allowEmptyDataOn904?: boolean;
+};
+/**
+ * Thực thi request tới hệ sinh thái ZFamily (`zfml.chat.zalo.me`) kèm cơ chế tự động quản lý khóa,
+ * tự động làm mới khi khóa hết hạn và giải mã AES-256-CBC (Random 16-byte IV - module `98yS`).
+ */
+export declare function requestZFamilyDecrypted<T>(api: API, utils: Pick<FactoryUtils<T>, "makeURL" | "request">, options: ZFamilyRequestOptions): Promise<T>;