@softtynet/zca-js 2.2.8 → 2.2.9

package/README.md

@@ -41,6 +41,7 @@ So với phiên bản cộng đồng tiêu chuẩn, **`@softtynet/zca-js`** bổ
 | **Đồng bộ sao lưu từ Điện thoại (`ZDB4.0`)** | Hỗ trợ trọn vẹn chu trình [`api.requestSyncFromPhone()`](src/apis/requestSyncFromPhone.ts) (`cmd 12000`), [`api.cancelPullMobile()`](src/apis/cancelPullMobile.ts) (`cmd 12700`), sự kiện `sync_event` (`user_confirm`, `syncmsg_info`, `transfer_after_login`), tải gói `.db.crypt` qua [`api.getSyncData()`](src/apis/getSyncData.ts) và giải mã RSA-2048 PKCS#1 v1.5 + AES-256-CBC đa khối 64KB + đọc mục lục SQLite (`parseZdbHeader`). |
 | **Ánh xạ ID ẩn danh (Noised / Global ID)** | Hỗ trợ [`api.getNoisedIds()`](src/apis/getNoisedIds.ts) (`cmd 12390` kèm cơ chế tự động fallback sang `zwid.api.zalo.me`) và [`api.decryptGids()`](src/apis/decryptGids.ts) (`cmd 12054`) để ánh xạ tên file SQLite `3_<me>_<peer>.db` về User ID / Group ID thật. |
 | **Gọi Thoại & Gọi Video (Signaling 2 bước)** | Hỗ trợ [`api.sendVoiceCall()`](src/apis/sendVoiceCall.ts) (`cmd 11300` + `11301`), [`api.cancelVoiceCall()`](src/apis/cancelVoiceCall.ts) (`cmd 11305`), [`api.endVoiceCall()`](src/apis/endVoiceCall.ts) (`cmd 11306`) và sự kiện `call_event` chuẩn giao thức C++ `ZaloCall` cho cả **Gọi Thoại (`CallType.Audio = 1`)** lẫn **Gọi Video (`CallType.Video = 3`, H.264)**. |
+| **Hệ sinh thái ZCloud, ZFamily & AI (`26.7.10`)** | Hỗ trợ chuẩn mã hóa `98yS` (AES-256-CBC với 16-byte Random IV) cho ZCloud & ZFamily ([`getCloudViewerKey`](src/apis/getCloudViewerKey.ts), [`getUsageZCloud`](src/apis/getUsageZCloud.ts), [`getUsageMyCloud`](src/apis/getUsageMyCloud.ts), [`getCloudSettings`](src/apis/getCloudSettings.ts), [`getCloudInfo`](src/apis/getCloudInfo.ts), [`getFamilyUsage`](src/apis/getFamilyUsage.ts), [`verifyCloudMedia`](src/apis/verifyCloudMedia.ts), [`getFamilyViewerKey`](src/apis/getFamilyViewerKey.ts), [`getFamilyProfile`](src/apis/getFamilyProfile.ts)), AI chuyển giọng nói thành văn bản [`voiceToText`](src/apis/voiceToText.ts) (`cmd 13394` + `voice2text_event`), Emoji Status ([`getEmojiStatusConfig`](src/apis/getEmojiStatusConfig.ts), [`getFriendsEmojiStatus`](src/apis/getFriendsEmojiStatus.ts)), Kho Lưu Trữ Hội Thoại ([`getConversationMedia`](src/apis/getConversationMedia.ts), [`getMediaStorePreview`](src/apis/getMediaStorePreview.ts), [`removeConversationMedia`](src/apis/removeConversationMedia.ts)), Lịch sử tìm kiếm ([`getRecentSearchList`](src/apis/getRecentSearchList.ts), [`updateRecentSearch`](src/apis/updateRecentSearch.ts)) cùng 25+ API Nhóm, Hồ sơ, Danh bạ & Nhãn dán V2 đã kiểm định Live 100%. |
 | **Độ ổn định & Bảo vệ bộ nhớ** | Tự động giải phóng bộ nhớ `uploadCallbacks` sau 5 phút trong [`uploadAttachment`](src/apis/uploadAttachment.ts), xử lý phản hồi rỗng hợp lệ (`error_code === 0, data === ""`) và bảo toàn độ chính xác chuỗi UID 19 chữ số. |
 
 ---

package/dist/apis/clearUnreadFriendRequests.d.ts

@@ -0,0 +1,2 @@
+export type ClearUnreadFriendRequestsResponse = Record<string, unknown> | string;
+export declare const clearUnreadFriendRequestsFactory: (ctx: import("../context.js").ContextBase, api: import("../apis.js").API) => (uidsSeen?: string[]) => Promise<ClearUnreadFriendRequestsResponse>;

package/dist/apis/clearUnreadFriendRequests.js

@@ -0,0 +1,29 @@
+import { ZaloApiError } from "../Errors/ZaloApiError.js";
+import { apiFactory } from "../utils.js";
+export const clearUnreadFriendRequestsFactory = apiFactory()((api, _ctx, utils) => {
+    const serviceURL = utils.makeURL(`${api.zpwServiceMap.friend[0]}/api/friend/recommendsv2/read-requests`);
+    /**
+     * Đánh dấu đã xem danh sách lời mời kết bạn chưa đọc (command 12232)
+     *
+     * @param uidsSeen Danh sách UID đã xem lời mời kết bạn (mặc định `[]`)
+     * @throws {ZaloApiError}
+     */
+    return async function clearUnreadFriendRequests(uidsSeen = []) {
+        if (!uidsSeen || uidsSeen.length === 0) {
+            return {};
+        }
+        const params = {
+            uids_seen: uidsSeen,
+        };
+        const encryptedParams = utils.encodeAES(JSON.stringify(params));
+        if (!encryptedParams)
+            throw new ZaloApiError("Failed to encrypt params");
+        const response = await utils.request(serviceURL, {
+            method: "POST",
+            body: new URLSearchParams({
+                params: encryptedParams,
+            }),
+        });
+        return utils.resolve(response);
+    };
+});

package/dist/apis/encryptGids.d.ts

@@ -0,0 +1,4 @@
+export type EncryptGidsResponse = {
+    data: Record<string, string>;
+};
+export declare const encryptGidsFactory: (ctx: import("../context.js").ContextBase, api: import("../apis.js").API) => (uids: string[]) => Promise<EncryptGidsResponse>;

package/dist/apis/encryptGids.js

@@ -0,0 +1,24 @@
+import { ZaloApiError } from "../Errors/ZaloApiError.js";
+import { apiFactory } from "../utils.js";
+export const encryptGidsFactory = apiFactory()((api, _ctx, utils) => {
+    const serviceURL = utils.makeURL(`${api.zpwServiceMap.profile[0]}/api/gid/encrypt`);
+    /**
+     * Mã hóa danh sách UID thật sang định danh ẩn danh Global Noise ID (`OTDAKO...`) (command 12053)
+     *
+     * @param uids Mảng chuỗi các UID cần mã hóa
+     * @throws {ZaloApiError}
+     */
+    return async function encryptGids(uids) {
+        if (!Array.isArray(uids) || uids.length === 0) {
+            return { data: {} };
+        }
+        const encryptedParams = utils.encodeAES(JSON.stringify({ noiseUids: uids }));
+        if (!encryptedParams) {
+            throw new ZaloApiError("Failed to encrypt params");
+        }
+        const response = await utils.request(utils.makeURL(serviceURL, { params: encryptedParams }), {
+            method: "GET",
+        });
+        return utils.resolve(response);
+    };
+});

package/dist/apis/getAliasListV2.d.ts

@@ -0,0 +1,10 @@
+export type AliasItemV2 = {
+    userId: string;
+    alias: string;
+};
+export type GetAliasListV2Response = {
+    items: AliasItemV2[];
+    updateTime?: string;
+    [key: string]: unknown;
+};
+export declare const getAliasListV2Factory: (ctx: import("../context.js").ContextBase, api: import("../apis.js").API) => (page?: number, count?: number) => Promise<GetAliasListV2Response>;

package/dist/apis/getAliasListV2.js

@@ -0,0 +1,28 @@
+import { ZaloApiError } from "../Errors/ZaloApiError.js";
+import { apiFactory } from "../utils.js";
+export const getAliasListV2Factory = apiFactory()((api, ctx, utils) => {
+    const serviceURL = utils.makeURL(`${api.zpwServiceMap.alias[0]}/api/alias/list/v2`);
+    /**
+     * Lấy danh sách tên gợi nhớ (Alias) của bạn bè chuẩn V2 có hỗ trợ phân trang (command 12205)
+     *
+     * @param page Trang cần lấy (mặc định: 1)
+     * @param count Số lượng mục mỗi trang (mặc định: 100)
+     * @throws {ZaloApiError}
+     */
+    return async function getAliasListV2(page = 1, count = 100) {
+        const params = {
+            page,
+            count,
+            src: -1,
+            imei: ctx.imei,
+        };
+        const encryptedParams = utils.encodeAES(JSON.stringify(params));
+        if (!encryptedParams) {
+            throw new ZaloApiError("Failed to encrypt params");
+        }
+        const response = await utils.request(utils.makeURL(serviceURL, { params: encryptedParams }), {
+            method: "GET",
+        });
+        return utils.resolve(response);
+    };
+});

package/dist/apis/getBlockFriends.d.ts

@@ -0,0 +1,6 @@
+export type GetBlockFriendsResponse = {
+    profiles: Record<string, unknown>[];
+    version: number;
+    hasMore: number;
+};
+export declare const getBlockFriendsFactory: (ctx: import("../context.js").ContextBase, api: import("../apis.js").API) => (page?: number, count?: number, avatarSize?: number) => Promise<GetBlockFriendsResponse>;

package/dist/apis/getBlockFriends.js

@@ -0,0 +1,28 @@
+import { ZaloApiError } from "../Errors/ZaloApiError.js";
+import { apiFactory } from "../utils.js";
+export const getBlockFriendsFactory = apiFactory()((api, _ctx, utils) => {
+    const serviceURL = utils.makeURL(`${api.zpwServiceMap.friend[0]}/api/friend/blocklistv2`);
+    /**
+     * Lấy danh sách người dùng đang bị chặn chuẩn V2 (command 11429)
+     *
+     * @param page Trang cần lấy (mặc định: 1)
+     * @param count Số lượng mỗi trang (mặc định: 50)
+     * @param avatarSize Kích thước ảnh đại diện (mặc định: 120)
+     * @throws {ZaloApiError}
+     */
+    return async function getBlockFriends(page = 1, count = 50, avatarSize = 120) {
+        const params = {
+            page,
+            count,
+            avatar: avatarSize,
+        };
+        const encryptedParams = utils.encodeAES(JSON.stringify(params));
+        if (!encryptedParams) {
+            throw new ZaloApiError("Failed to encrypt params");
+        }
+        const response = await utils.request(utils.makeURL(serviceURL, { params: encryptedParams }), {
+            method: "GET",
+        });
+        return utils.resolve(response);
+    };
+});

package/dist/apis/getCloudInfo.d.ts

@@ -0,0 +1,3 @@
+import type { GetCloudViewerKeyResponse } from "./getCloudViewerKey.js";
+export type GetCloudInfoResponse = Record<string, unknown>;
+export declare const getCloudInfoFactory: (ctx: import("../context.js").ContextBase, api: import("../apis.js").API) => (viewerKeyInfo?: GetCloudViewerKeyResponse) => Promise<GetCloudInfoResponse>;

package/dist/apis/getCloudInfo.js

@@ -0,0 +1,34 @@
+import { ZaloApiError } from "../Errors/ZaloApiError.js";
+import { apiFactory, decryptZCloudAES } from "../utils.js";
+export const getCloudInfoFactory = apiFactory()((api, _ctx, utils) => {
+    var _a;
+    const baseDomain = ((_a = api.zpwServiceMap.zcloud) === null || _a === void 0 ? void 0 : _a[0]) || "https://zcld.chat.zalo.me";
+    const serviceURL = utils.makeURL(`${baseDomain}/zalocloud/cloudinfopcweb/v1/info`);
+    /**
+     * Lấy thông tin gói thuê bao Zalo Cloud (command 12754)
+     *
+     * @param viewerKeyInfo (Tùy chọn) Cặp `{ viewer_key, enk }` từ `api.getCloudViewerKey()`.
+     * @throws {ZaloApiError}
+     */
+    return async function getCloudInfo(viewerKeyInfo) {
+        const keyInfo = viewerKeyInfo !== null && viewerKeyInfo !== void 0 ? viewerKeyInfo : (await api.getCloudViewerKey());
+        if (!(keyInfo === null || keyInfo === void 0 ? void 0 : keyInfo.viewer_key) || !(keyInfo === null || keyInfo === void 0 ? void 0 : keyInfo.enk)) {
+            throw new ZaloApiError("Invalid CloudViewerKey");
+        }
+        const response = await utils.request(serviceURL, {
+            method: "GET",
+            headers: {
+                "cloud-viewer-key": keyInfo.viewer_key,
+            },
+        });
+        const json = (await response.json());
+        if (json.error_code !== 0 && json.error_code !== -904) {
+            throw new ZaloApiError(json.error_message || "getCloudInfo failed", json.error_code);
+        }
+        if (!json.data) {
+            return {};
+        }
+        const decrypted = decryptZCloudAES(json.data, keyInfo.enk);
+        return JSON.parse(decrypted);
+    };
+});

package/dist/apis/getCloudSettings.d.ts

@@ -0,0 +1,10 @@
+import type { GetCloudViewerKeyResponse } from "./getCloudViewerKey.js";
+export type GetCloudSettingsResponse = {
+    cloud_media_file_size_limit: number;
+    enable_community: number;
+    my_cloud_file_size_limit: number;
+    opt_in: number;
+    key_export: Record<string, unknown>;
+    enable_offload: number;
+};
+export declare const getCloudSettingsFactory: (ctx: import("../context.js").ContextBase, api: import("../apis.js").API) => (viewerKeyInfo?: GetCloudViewerKeyResponse) => Promise<GetCloudSettingsResponse>;

package/dist/apis/getCloudSettings.js

@@ -0,0 +1,34 @@
+import { ZaloApiError } from "../Errors/ZaloApiError.js";
+import { apiFactory, decryptZCloudAES } from "../utils.js";
+export const getCloudSettingsFactory = apiFactory()((api, _ctx, utils) => {
+    var _a;
+    const baseDomain = ((_a = api.zpwServiceMap.zcloud) === null || _a === void 0 ? void 0 : _a[0]) || "https://zcld.chat.zalo.me";
+    const serviceURL = utils.makeURL(`${baseDomain}/cloudmedia/info/pc/v1/cloud-settings`);
+    /**
+     * Lấy cấu hình giới hạn tệp và cài đặt ZCloud của tài khoản (command 12756)
+     *
+     * @param viewerKeyInfo (Tùy chọn) Cặp `{ viewer_key, enk }` từ `api.getCloudViewerKey()`. Nếu không truyền sẽ tự động lấy mới.
+     * @throws {ZaloApiError}
+     */
+    return async function getCloudSettings(viewerKeyInfo) {
+        const keyInfo = viewerKeyInfo !== null && viewerKeyInfo !== void 0 ? viewerKeyInfo : (await api.getCloudViewerKey());
+        if (!(keyInfo === null || keyInfo === void 0 ? void 0 : keyInfo.viewer_key) || !(keyInfo === null || keyInfo === void 0 ? void 0 : keyInfo.enk)) {
+            throw new ZaloApiError("Invalid CloudViewerKey");
+        }
+        const response = await utils.request(serviceURL, {
+            method: "GET",
+            headers: {
+                "cloud-viewer-key": keyInfo.viewer_key,
+            },
+        });
+        const json = (await response.json());
+        if (json.error_code !== 0 && json.error_code !== -904) {
+            throw new ZaloApiError(json.error_message || "getCloudSettings failed", json.error_code);
+        }
+        if (!json.data) {
+            throw new ZaloApiError("Empty ZCloud settings data", json.error_code);
+        }
+        const decrypted = decryptZCloudAES(json.data, keyInfo.enk);
+        return JSON.parse(decrypted);
+    };
+});

package/dist/apis/getCloudViewerKey.d.ts

@@ -0,0 +1,5 @@
+export type GetCloudViewerKeyResponse = {
+    viewer_key: string;
+    enk: string;
+};
+export declare const getCloudViewerKeyFactory: (ctx: import("../context.js").ContextBase, api: import("../apis.js").API) => () => Promise<GetCloudViewerKeyResponse>;

package/dist/apis/getCloudViewerKey.js

@@ -0,0 +1,25 @@
+import { ZaloApiError } from "../Errors/ZaloApiError.js";
+import { apiFactory } from "../utils.js";
+export const getCloudViewerKeyFactory = apiFactory()((_api, _ctx, utils) => {
+    const serviceURL = utils.makeURL("https://wpa.chat.zalo.me/api/getCloudViewerKey");
+    /**
+     * Lấy cặp khóa phiên (`viewer_key` và khóa giải mã AES-256 `enk`) cho hệ thống ZCloud / MyCloud (command 12741)
+     *
+     * @throws {ZaloApiError}
+     */
+    return async function getCloudViewerKey() {
+        const response = await utils.request(serviceURL, {
+            method: "GET",
+        });
+        const res = await utils.resolve(response);
+        if (typeof res === "string") {
+            try {
+                return JSON.parse(res);
+            }
+            catch (_a) {
+                throw new ZaloApiError("Failed to parse CloudViewerKey response");
+            }
+        }
+        return res;
+    };
+});

package/dist/apis/getConversationMedia.d.ts

@@ -0,0 +1,26 @@
+export type MediaStoreType = "media" | "file" | "link";
+export type GetConversationMediaOptions = {
+    groupId?: string;
+    threadId?: string;
+    mediaType?: MediaStoreType;
+    limit?: number;
+    lastId?: number | string;
+    lastFetchId?: number;
+};
+export type MediaStoreItem = {
+    id: number | string;
+    type: string;
+    title?: string;
+    src_url?: string;
+    thumb_url?: string;
+    previewThumb?: string | null;
+    created_time?: number;
+    [key: string]: unknown;
+};
+export type GetConversationMediaResponse = {
+    items: MediaStoreItem[];
+    isLimitPermission: boolean;
+    last_id: number | string;
+    has_more: number;
+};
+export declare const getConversationMediaFactory: (ctx: import("../context.js").ContextBase, api: import("../apis.js").API) => (options: GetConversationMediaOptions) => Promise<GetConversationMediaResponse>;

package/dist/apis/getConversationMedia.js

@@ -0,0 +1,39 @@
+import { ZaloApiError } from "../Errors/ZaloApiError.js";
+import { apiFactory } from "../utils.js";
+export const getConversationMediaFactory = apiFactory()((api, ctx, utils) => {
+    const serviceURL = utils.makeURL(`${api.zpwServiceMap.media_store[0]}/api/mediastore/list`);
+    /**
+     * Lấy danh sách Kho Lưu Trữ (Ảnh/Video `"media"`, File `"file"`, hoặc Link `"link"`) trong hội thoại nhóm (command 11841)
+     *
+     * @param options Tùy chọn truy vấn (`groupId`, `mediaType`, `limit`, `lastId`, `lastFetchId`)
+     * @throws {ZaloApiError}
+     */
+    return async function getConversationMedia(options) {
+        var _a, _b;
+        const rawGroupId = options.groupId || options.threadId;
+        if (!rawGroupId) {
+            throw new ZaloApiError("Missing groupId");
+        }
+        const groupId = rawGroupId.startsWith("g") ? rawGroupId.slice(1) : rawGroupId;
+        const params = {
+            media_type: (_a = options.mediaType) !== null && _a !== void 0 ? _a : "media",
+            group_id: groupId,
+            limit: (_b = options.limit) !== null && _b !== void 0 ? _b : 20,
+            imei: ctx.imei,
+        };
+        if (options.lastId !== undefined) {
+            params.last_id = options.lastId;
+        }
+        if (options.lastFetchId !== undefined && !Number.isNaN(options.lastFetchId)) {
+            params.lastFetchId = options.lastFetchId;
+        }
+        const encryptedParams = utils.encodeAES(JSON.stringify(params));
+        if (!encryptedParams) {
+            throw new ZaloApiError("Failed to encrypt params");
+        }
+        const response = await utils.request(utils.makeURL(serviceURL, { params: encryptedParams }), {
+            method: "GET",
+        });
+        return utils.resolve(response);
+    };
+});

package/dist/apis/getEmojiStatusConfig.d.ts

@@ -0,0 +1,17 @@
+export type EmojiStatusItem = {
+    id: number;
+    caption: {
+        vi: string;
+        en: string;
+    };
+    thumb: string;
+    full: string;
+};
+export type GetEmojiStatusConfigResponse = {
+    expireTime: number;
+    config: {
+        emojis: EmojiStatusItem[];
+        [key: string]: unknown;
+    };
+};
+export declare const getEmojiStatusConfigFactory: (ctx: import("../context.js").ContextBase, api: import("../apis.js").API) => (version?: number) => Promise<GetEmojiStatusConfigResponse>;

package/dist/apis/getEmojiStatusConfig.js

@@ -0,0 +1,23 @@
+import { ZaloApiError } from "../Errors/ZaloApiError.js";
+import { apiFactory } from "../utils.js";
+export const getEmojiStatusConfigFactory = apiFactory()((api, _ctx, utils) => {
+    var _a;
+    const baseDomain = ((_a = api.zpwServiceMap.emoji_stt) === null || _a === void 0 ? void 0 : _a[0]) || "https://emoji-status.chat.zalo.me";
+    const serviceURL = utils.makeURL(`${baseDomain}/api/v1/emoji-status/resource-config`);
+    /**
+     * Lấy cấu hình và danh sách bộ biểu tượng Trạng thái Emoji (Emoji Status - command 16300)
+     *
+     * @param version Phiên bản bộ nhớ đệm (mặc định: 0 để lấy đầy đủ danh sách)
+     * @throws {ZaloApiError}
+     */
+    return async function getEmojiStatusConfig(version = 0) {
+        const encryptedParams = utils.encodeAES(JSON.stringify({ version }));
+        if (!encryptedParams) {
+            throw new ZaloApiError("Failed to encrypt params");
+        }
+        const response = await utils.request(utils.makeURL(serviceURL, { params: encryptedParams }), {
+            method: "GET",
+        });
+        return utils.resolve(response);
+    };
+});

package/dist/apis/getExtraFriendInfo.d.ts

@@ -0,0 +1,3 @@
+import type { ExtraContextInfo } from "./getExtraGroupInfo.js";
+export type GetExtraFriendInfoResponse = Record<string, ExtraContextInfo>;
+export declare const getExtraFriendInfoFactory: (ctx: import("../context.js").ContextBase, api: import("../apis.js").API) => (friendIds: string[]) => Promise<GetExtraFriendInfoResponse>;

package/dist/apis/getExtraFriendInfo.js

@@ -0,0 +1,31 @@
+import { ZaloApiError } from "../Errors/ZaloApiError.js";
+import { apiFactory } from "../utils.js";
+export const getExtraFriendInfoFactory = apiFactory()((api, ctx, utils) => {
+    const serviceURL = utils.makeURL(`${api.zpwServiceMap.friend[0]}/api/friend/context/multiget`);
+    /**
+     * Lấy ngữ cảnh và vai trò mở rộng (ví dụ `role: ["boss"]`) của danh sách bạn bè (command 11442)
+     *
+     * @param friendIds Mảng UID cần truy vấn
+     * @throws {ZaloApiError}
+     */
+    return async function getExtraFriendInfo(friendIds) {
+        if (!Array.isArray(friendIds) || friendIds.length === 0) {
+            return {};
+        }
+        const params = {
+            fids: friendIds,
+            imei: ctx.imei,
+        };
+        const encryptedParams = utils.encodeAES(JSON.stringify(params));
+        if (!encryptedParams) {
+            throw new ZaloApiError("Failed to encrypt params");
+        }
+        const response = await utils.request(serviceURL, {
+            method: "POST",
+            body: new URLSearchParams({
+                params: encryptedParams,
+            }),
+        });
+        return utils.resolve(response);
+    };
+});

package/dist/apis/getExtraGroupInfo.d.ts

@@ -0,0 +1,7 @@
+export type ExtraContextInfo = {
+    purpose: string;
+    role: string[];
+    [key: string]: unknown;
+};
+export type GetExtraGroupInfoResponse = Record<string, ExtraContextInfo>;
+export declare const getExtraGroupInfoFactory: (ctx: import("../context.js").ContextBase, api: import("../apis.js").API) => (groupIds: string[]) => Promise<GetExtraGroupInfoResponse>;

package/dist/apis/getExtraGroupInfo.js

@@ -0,0 +1,32 @@
+import { ZaloApiError } from "../Errors/ZaloApiError.js";
+import { apiFactory } from "../utils.js";
+export const getExtraGroupInfoFactory = apiFactory()((api, ctx, utils) => {
+    const serviceURL = utils.makeURL(`${api.zpwServiceMap.group[0]}/api/group/userctx/multiget`);
+    /**
+     * Lấy ngữ cảnh và vai trò mở rộng của người dùng đối với nhiều nhóm (command 12607)
+     *
+     * @param groupIds Mảng ID các nhóm cần truy vấn
+     * @throws {ZaloApiError}
+     */
+    return async function getExtraGroupInfo(groupIds) {
+        if (!Array.isArray(groupIds) || groupIds.length === 0) {
+            return {};
+        }
+        const cleanGroupIds = groupIds.map((g) => (g.startsWith("g") ? g.slice(1) : g));
+        const params = {
+            grids: cleanGroupIds,
+            imei: ctx.imei,
+        };
+        const encryptedParams = utils.encodeAES(JSON.stringify(params));
+        if (!encryptedParams) {
+            throw new ZaloApiError("Failed to encrypt params");
+        }
+        const response = await utils.request(serviceURL, {
+            method: "POST",
+            body: new URLSearchParams({
+                params: encryptedParams,
+            }),
+        });
+        return utils.resolve(response);
+    };
+});

package/dist/apis/getFamilyProfile.d.ts

@@ -0,0 +1,3 @@
+import type { GetFamilyViewerKeyResponse } from "./getFamilyViewerKey.js";
+export type GetFamilyProfileResponse = Record<string, unknown>;
+export declare const getFamilyProfileFactory: (ctx: import("../context.js").ContextBase, api: import("../apis.js").API) => (familyKeyInfo?: GetFamilyViewerKeyResponse) => Promise<GetFamilyProfileResponse>;

package/dist/apis/getFamilyProfile.js

@@ -0,0 +1,34 @@
+import { ZaloApiError } from "../Errors/ZaloApiError.js";
+import { apiFactory, decryptZCloudAES } from "../utils.js";
+export const getFamilyProfileFactory = apiFactory()((api, _ctx, utils) => {
+    var _a;
+    const baseDomain = ((_a = api.zpwServiceMap.zfamily) === null || _a === void 0 ? void 0 : _a[0]) || "https://zfml.chat.zalo.me";
+    const serviceURL = utils.makeURL(`${baseDomain}/zfamily/pc/family-profile/v1/family`);
+    /**
+     * Lấy thông tin nhóm gia đình ZFamily (command 12757)
+     *
+     * @param familyKeyInfo (Tùy chọn) Cặp `{ viewer_key, enk }` từ `api.getFamilyViewerKey()`.
+     * @throws {ZaloApiError}
+     */
+    return async function getFamilyProfile(familyKeyInfo) {
+        const keyInfo = familyKeyInfo !== null && familyKeyInfo !== void 0 ? familyKeyInfo : (await api.getFamilyViewerKey());
+        if (!(keyInfo === null || keyInfo === void 0 ? void 0 : keyInfo.viewer_key) || !(keyInfo === null || keyInfo === void 0 ? void 0 : keyInfo.enk)) {
+            throw new ZaloApiError("Invalid FamilyViewerKey");
+        }
+        const response = await utils.request(serviceURL, {
+            method: "GET",
+            headers: {
+                "zfamily-viewer-key": keyInfo.viewer_key,
+            },
+        });
+        const json = (await response.json());
+        if (json.error_code !== 0 && json.error_code !== -904) {
+            throw new ZaloApiError(json.error_message || "getFamilyProfile failed", json.error_code);
+        }
+        if (!json.data) {
+            return {};
+        }
+        const decrypted = decryptZCloudAES(json.data, keyInfo.enk);
+        return JSON.parse(decrypted);
+    };
+});

package/dist/apis/getFamilyUsage.d.ts

@@ -0,0 +1,7 @@
+import type { GetCloudViewerKeyResponse } from "./getCloudViewerKey.js";
+export type GetFamilyUsageResponse = {
+    usage: number;
+    quota: number;
+    lastUpdated: number;
+};
+export declare const getFamilyUsageFactory: (ctx: import("../context.js").ContextBase, api: import("../apis.js").API) => (viewerKeyInfo?: GetCloudViewerKeyResponse) => Promise<GetFamilyUsageResponse>;

package/dist/apis/getFamilyUsage.js

@@ -0,0 +1,34 @@
+import { ZaloApiError } from "../Errors/ZaloApiError.js";
+import { apiFactory, decryptZCloudAES } from "../utils.js";
+export const getFamilyUsageFactory = apiFactory()((api, _ctx, utils) => {
+    var _a;
+    const baseDomain = ((_a = api.zpwServiceMap.zcloud) === null || _a === void 0 ? void 0 : _a[0]) || "https://zcld.chat.zalo.me";
+    const serviceURL = utils.makeURL(`${baseDomain}/cloudmedia/info/pc/v1/family-usage`);
+    /**
+     * Kiểm tra dung lượng sử dụng gói ZCloud Gia đình (Family Usage - command 12758)
+     *
+     * @param viewerKeyInfo (Tùy chọn) Cặp `{ viewer_key, enk }` từ `api.getCloudViewerKey()`. Nếu không truyền sẽ tự động lấy mới.
+     * @throws {ZaloApiError}
+     */
+    return async function getFamilyUsage(viewerKeyInfo) {
+        const keyInfo = viewerKeyInfo !== null && viewerKeyInfo !== void 0 ? viewerKeyInfo : (await api.getCloudViewerKey());
+        if (!(keyInfo === null || keyInfo === void 0 ? void 0 : keyInfo.viewer_key) || !(keyInfo === null || keyInfo === void 0 ? void 0 : keyInfo.enk)) {
+            throw new ZaloApiError("Invalid CloudViewerKey");
+        }
+        const response = await utils.request(serviceURL, {
+            method: "GET",
+            headers: {
+                "cloud-viewer-key": keyInfo.viewer_key,
+            },
+        });
+        const json = (await response.json());
+        if (json.error_code !== 0 && json.error_code !== -904) {
+            throw new ZaloApiError(json.error_message || "getFamilyUsage failed", json.error_code);
+        }
+        if (!json.data) {
+            throw new ZaloApiError("Empty FamilyUsage data", json.error_code);
+        }
+        const decrypted = decryptZCloudAES(json.data, keyInfo.enk);
+        return JSON.parse(decrypted);
+    };
+});

package/dist/apis/getFamilyViewerKey.d.ts

@@ -0,0 +1,5 @@
+export type GetFamilyViewerKeyResponse = {
+    viewer_key: string;
+    enk: string;
+};
+export declare const getFamilyViewerKeyFactory: (ctx: import("../context.js").ContextBase, api: import("../apis.js").API) => () => Promise<GetFamilyViewerKeyResponse>;

package/dist/apis/getFamilyViewerKey.js

@@ -0,0 +1,25 @@
+import { ZaloApiError } from "../Errors/ZaloApiError.js";
+import { apiFactory } from "../utils.js";
+export const getFamilyViewerKeyFactory = apiFactory()((_api, _ctx, utils) => {
+    const serviceURL = utils.makeURL("https://wpa.chat.zalo.me/api/getFamilyViewerKey");
+    /**
+     * Lấy cặp khóa phiên (`viewer_key` và khóa giải mã AES-256 `enk`) cho gói gia đình ZFamily (command 12759)
+     *
+     * @throws {ZaloApiError}
+     */
+    return async function getFamilyViewerKey() {
+        const response = await utils.request(serviceURL, {
+            method: "GET",
+        });
+        const res = await utils.resolve(response);
+        if (typeof res === "string") {
+            try {
+                return JSON.parse(res);
+            }
+            catch (_a) {
+                throw new ZaloApiError("Failed to parse FamilyViewerKey response");
+            }
+        }
+        return res;
+    };
+});

package/dist/apis/getFriendsEmojiStatus.d.ts

@@ -0,0 +1,17 @@
+export type GetFriendsEmojiStatusOptions = {
+    version?: number;
+    fromUid?: string;
+    maxEmojiStatusId?: string | number;
+    page?: number;
+};
+export type GetFriendsEmojiStatusResponse = {
+    expireTime: number;
+    emojiStatuses: Record<string, unknown>[];
+    version: number;
+    type: number;
+    maxEmojiStatusId: number;
+    loadMore: boolean;
+    lastUid: string;
+    page: number;
+};
+export declare const getFriendsEmojiStatusFactory: (ctx: import("../context.js").ContextBase, api: import("../apis.js").API) => (options?: GetFriendsEmojiStatusOptions) => Promise<GetFriendsEmojiStatusResponse>;

package/dist/apis/getFriendsEmojiStatus.js

@@ -0,0 +1,30 @@
+import { ZaloApiError } from "../Errors/ZaloApiError.js";
+import { apiFactory } from "../utils.js";
+export const getFriendsEmojiStatusFactory = apiFactory()((api, _ctx, utils) => {
+    var _a;
+    const baseDomain = ((_a = api.zpwServiceMap.emoji_stt) === null || _a === void 0 ? void 0 : _a[0]) || "https://emoji-status.chat.zalo.me";
+    const serviceURL = utils.makeURL(`${baseDomain}/api/v1/emoji-status/friends`);
+    /**
+     * Lấy danh sách trạng thái Emoji (Emoji Status) hiện tại của bạn bè (command 16301)
+     *
+     * @param options Tùy chọn phân trang (`version`, `fromUid`, `maxEmojiStatusId`, `page`)
+     * @throws {ZaloApiError}
+     */
+    return async function getFriendsEmojiStatus(options = {}) {
+        var _a, _b, _c, _d;
+        const params = {
+            version: (_a = options.version) !== null && _a !== void 0 ? _a : 0,
+            fromUid: (_b = options.fromUid) !== null && _b !== void 0 ? _b : "0",
+            maxEmojiStatusId: String((_c = options.maxEmojiStatusId) !== null && _c !== void 0 ? _c : "0"),
+            page: (_d = options.page) !== null && _d !== void 0 ? _d : 1,
+        };
+        const encryptedParams = utils.encodeAES(JSON.stringify(params));
+        if (!encryptedParams) {
+            throw new ZaloApiError("Failed to encrypt params");
+        }
+        const response = await utils.request(utils.makeURL(serviceURL, { params: encryptedParams }), {
+            method: "GET",
+        });
+        return utils.resolve(response);
+    };
+});

package/dist/apis/getGroupCloudMessageJump.d.ts

@@ -0,0 +1,3 @@
+import type { GetGroupChatHistoryResponse } from "./getGroupChatHistory.js";
+export type GetGroupCloudMessageJumpResponse = GetGroupChatHistoryResponse;
+export declare const getGroupCloudMessageJumpFactory: (ctx: import("../context.js").ContextBase, api: import("../apis.js").API) => (groupId: string, globalMsgId: string | number, count?: number, msgJump?: number, msgIds?: Array<string | number>) => Promise<GetGroupChatHistoryResponse>;