@softtynet/zca-js 2.2.7 → 2.2.9

package/README.md

@@ -1,54 +1,73 @@
-# ZCA-JS (Forked Version)
+# @softtynet/zca-js — Softtynet Zalo API SDK for Node.js & Bun
 
-> [!NOTE]
-> **This is a forked version of the original [zca-js](https://github.com/RFS-ADRENO/zca-js) project by RFS-ADRENO.** This package (`@softtynet/zca-js`) is maintained separately for quick hotfixes.
-> 
-> This is an unofficial Zalo API for personal account. It work by simulating the browser to interact with Zalo Web.
+<p align="left">
+  <a href="https://www.npmjs.com/package/@softtynet/zca-js"><img src="https://img.shields.io/npm/v/@softtynet/zca-js.svg?label=%40softtynet%2Fzca-js&color=0068ff" alt="npm version" /></a>
+  <a href="https://github.com/softtyos/zca-js"><img src="https://img.shields.io/badge/Maintained%20by-Softtynet%20Co.%2C%20Ltd.-0a7cff" alt="Maintained by Softtynet" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License: MIT" /></a>
+</p>
+
+**`@softtynet/zca-js`** là bộ thư viện Zalo API nâng cao dành cho Node.js / TypeScript / Bun, được phát triển, tối ưu hoá và duy trì bởi **Softtynet Co., Ltd.** nhằm đáp ứng các bài toán tích hợp chuyên sâu: **Đồng bộ dữ liệu đa thiết bị (Offline Catch-up & Mobile Backup Sync `ZDB4.0`)**, **Tín hiệu Gọi Thoại & Gọi Video (Voice / Video Call Signaling)**, và **Xử lý WebSocket thời gian thực độ tin cậy cao**.
 
 > [!WARNING]
-> Using this API could get your account locked or banned. We are not responsible for any issues that may happen. Use it at your own risk.
+> Đây là thư viện tương tác không chính thức thông qua giao thức Zalo Web / Zalo PC dành cho tài khoản cá nhân. Vui lòng sử dụng có trách nhiệm và tuân thủ quy định an toàn tài khoản.
+
+---
+
+## Mục lục
+
+- [Điểm nổi bật trên phiên bản Softtynet (`@softtynet/zca-js`)](#-điểm-nổi-bật-trên-phiên-bản-softtynet-softtynetzca-js)
+- [Cài đặt](#-cài-đặt)
+- [Tài liệu chuyên sâu](#-tài-liệu-chuyên-sâu)
+- [Hướng dẫn sử dụng nhanh](#-hướng-dẫn-sử-dụng-nhanh)
+  - [1. Đăng nhập & Lưu phiên](#1-đăng-nhập--lưu-phiên)
+  - [2. Lắng nghe tin nhắn thời gian thực](#2-lắng-nghe-tin-nhắn-thời-gian-thực)
+  - [3. Đồng bộ bù tin nhắn khi Offline (Catch-up Sync)](#3-đồng-bộ-bù-tin-nhắn-khi-offline-catch-up-sync)
+  - [4. Đồng bộ lịch sử sao lưu từ Điện thoại (`ZDB4.0`)](#4-đồng-bộ-lịch-sử-sao-lưu-từ-điện-thoại-zdb40)
+  - [5. Khởi tạo Cuộc gọi Thoại & Gọi Video](#5-khởi-tạo-cuộc-gọi-thoại--gọi-video)
+  - [6. Gửi tin nhắn & Sticker](#6-gửi-tin-nhắn--sticker)
+- [Kiểm định & Chạy thử nghiệm](#-kiểm-định--chạy-thử-nghiệm)
+- [Nguồn gốc & Ghi nhận (Credits & Attribution)](#-nguồn-gốc--ghi-nhận-credits--attribution)
+- [Giấy phép (License)](#-giấy-phép-license)
 
 ---
 
-## Table of Contents
-
--   [Installation](#installation)
-    - [Migrate to V2](#migrate-to-v2)
--   [Documentation](#documentation)
--   [Basic Usages](#basic-usages)
-    -   [Login](#login)
-    -   [Listen for new messages](#listen-for-new-messages)
-    -   [Synchronize Messages from Mobile](#synchronize-messages-from-mobile)
-    -   [Send a message](#send-a-message)
-    -   [Get/Send a sticker](#getsend-a-sticker)
--   [Example](#example)
--   [Projects & Useful Resources](#projects--useful-resources)
--   [Contributing](#contributing)
--   [License](#license)
--   [Support Us](#support-us)
-
-## Installation
+## 🚀 Điểm nổi bật trên phiên bản Softtynet (`@softtynet/zca-js`)
+
+So với phiên bản cộng đồng tiêu chuẩn, **`@softtynet/zca-js`** bổ sung các phân hệ cốt lõi đã được kiểm định trực tiếp trên máy chủ Zalo thật:
+
+| Phân hệ | Tính năng trên `@softtynet/zca-js` |
+| :--- | :--- |
+| **Đồng bộ bù khi Offline (Catch-up Sync)** | Hỗ trợ [`api.preloadConversations()`](src/apis/preloadConversations.ts) (`cmd 10053`), kéo hàng đợi tin nhắn cá nhân & nhóm qua [`api.listener.requestOldMessages()`](src/apis/listen.ts) (`cmd 510` / `511`, cả `subCmd 0` & `1`), kèm cờ phân trang `hasMore`, tách biệt sự kiện thu hồi `undo` và đồng bộ trạng thái đã đọc `unread_cleared` (`cmd 504` / `524`). |
+| **Đồ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ố. |
+
+---
+
+## 📦 Cài đặt
 
 ```bash
-bun add zca-js # or npm install zca-js
+npm install @softtynet/zca-js
+# hoặc dùng Bun
+bun add @softtynet/zca-js
 ```
 
-### Migrate to V2
+### Cấu hình `imageMetadataGetter` (Khi gửi ảnh từ đường dẫn file)
 
-Since official version 2.0.0, `zca-js` has removed sharp dependency for image metadata extraction. It now requires users to provide their own `imageMetadataGetter` function when initializing the `Zalo` class if they want to send images/gifs by file path.
-
-Example of custom `imageMetadataGetter` using `sharp`:
+Từ kiến trúc V2, thư viện tách rời phụ thuộc xử lý ảnh để giữ dung lượng gọn nhẹ. Nếu ứng dụng của bạn gửi ảnh/GIF từ file nội bộ, hãy truyền hàm `imageMetadataGetter` (ví dụ dùng `sharp`):
 
 ```bash
-bun add sharp # or npm install sharp
+npm install sharp
 ```
 
-```javascript
-import { Zalo } from "zca-js";
+```ts
+import { Zalo } from "@softtynet/zca-js";
 import sharp from "sharp";
 import fs from "node:fs";
 
-async function imageMetadataGetter(filePath) {
+async function imageMetadataGetter(filePath: string) {
     const data = await fs.promises.readFile(filePath);
     const metadata = await sharp(data).metadata();
     return {
@@ -58,80 +77,75 @@ async function imageMetadataGetter(filePath) {
     };
 }
 
-const zalo = new Zalo({
-    imageMetadataGetter,
-});
+const zalo = new Zalo({ imageMetadataGetter });
 ```
 
 ---
 
-## Documentation
+## 📚 Tài liệu chuyên sâu
 
-- [API Documentation](https://zca-js.tdung.com)
-- [Hướng dẫn Tích hợp: Đồng bộ Tin nhắn Đa Thiết bị (`ZDB4.0`) & Gọi Thoại / Video](docs/INTEGRATION_GUIDE_SYNC_AND_CALL.md)
-- [Kế hoạch & Hướng dẫn Dịch ngược Zalo bằng REA (`morluto/rea`)](docs/REA_REVERSE_ENGINEERING_PLAN.md)
+- **[Hướng dẫn Tích hợp: Đồng bộ Tin nhắn Đa Thiết bị (`ZDB4.0`) & Gọi Thoại / Video](docs/INTEGRATION_GUIDE_SYNC_AND_CALL.md)** — Tài liệu đầy đủ kèm sơ đồ kiến trúc và code mẫu tích hợp thực tế của Softtynet.
+- **[Kế hoạch & Hướng dẫn Dịch ngược Zalo bằng REA (`morluto/rea`)](docs/REA_REVERSE_ENGINEERING_PLAN.md)** — Tài liệu quy trình phân tích tĩnh Binary C++ (`ZaloCall`, `libzdatabase.dylib`) và ASAR.
+- **[API Reference Cơ bản](https://zca-js.tdung.com)** — Tra cứu danh mục các API cơ bản.
 
 ---
 
-## Basic Usages
+## ⚡ Hướng dẫn sử dụng nhanh
 
-### Login
+### 1. Đăng nhập & Lưu phiên
 
-```javascript
-import { Zalo } from "zca-js";
+```ts
+import { Zalo } from "@softtynet/zca-js";
 
-const zalo = new Zalo();
+const zalo = new Zalo({ selfListen: true });
 const api = await zalo.loginQR();
+console.log("Đã đăng nhập với UID:", api.getOwnId());
 ```
 
-### Listen for new messages
+### 2. Lắng nghe tin nhắn thời gian thực
 
-```javascript
-import { Zalo, ThreadType } from "zca-js";
+```ts
+import { Zalo, ThreadType } from "@softtynet/zca-js";
 
-const zalo = new Zalo();
+const zalo = new Zalo({ selfListen: true });
 const api = await zalo.loginQR();
 
 api.listener.on("message", (message) => {
     const isPlainText = typeof message.data.content === "string";
+    if (!isPlainText) return;
 
-    switch (message.type) {
-        case ThreadType.User: {
-            if (isPlainText) {
-                // received plain text direct message
-            }
-            break;
-        }
-        case ThreadType.Group: {
-            if (isPlainText) {
-                // received plain text group message
-            }
-            break;
-        }
+    if (message.type === ThreadType.User) {
+        console.log(`[Cá nhân] ${message.data.dName}: ${message.data.content}`);
+    } else if (message.type === ThreadType.Group) {
+        console.log(`[Nhóm ${message.threadId}] ${message.data.dName}: ${message.data.content}`);
     }
 });
 
-api.listener.start();
+api.listener.start({ retryOnClose: true });
 ```
 
 > [!IMPORTANT]
-> Only one web listener can run per account at a time. If you open Zalo in the browser while the listener is active, the listener will be automatically stopped.
+> Mỗi tài khoản Zalo chỉ duy trì một kết nối WebSocket Web tại một thời điểm. Nếu bạn mở thêm tab Zalo Web trên trình duyệt, kết nối WebSocket cũ sẽ nhận sự kiện `duplicate_connection`.
 
-### Synchronize Messages & Offline Catch-up
+### 3. Đồng bộ bù tin nhắn khi Offline (Catch-up Sync)
 
-`zca-js` supports both **offline message catch-up** (when reconnecting or restarting your app) and **full mobile backup synchronization** (`ZDB4.0`) from the Zalo mobile app:
-
-#### 1. Catch Up Missed Messages After Reconnect / Restart
-```javascript
-import { Zalo, ThreadType } from "zca-js";
+```ts
+import { ThreadType } from "@softtynet/zca-js";
 
+// 1. Lấy nhanh các tin nhắn mới nhất & danh sách đã đọc qua HTTP (cmd 10053)
 const preload = await api.preloadConversations();
-console.log(`Preloaded ${preload.messages.length} latest messages`);
+console.log(`Preloaded: ${preload.messages.length} tin nhắn, ${preload.unreadCleared.length} trạng thái đã đọc`);
 
+// 2. Nhận tin nhắn từ hàng đợi WebSocket (cmd 510 & 511)
 api.listener.on("old_messages", (messages, type, hasMore) => {
-    console.log(`Received ${messages.length} queued offline messages (type=${type}, hasMore=${hasMore})`);
+    console.log(`Nhận ${messages.length} tin nhắn cũ (type=${type}, hasMore=${hasMore})`);
+    if (hasMore && messages.length > 0) {
+        const lastMsgId = messages[messages.length - 1].data.msgId;
+        api.listener.requestOldMessages(type, lastMsgId);
+    }
 });
 
+// 3. Kích hoạt kéo hàng đợi ngay khi nhận khoá giải mã WebSocket
 api.listener.on("cipher_key", () => {
     api.listener.requestOldMessages(ThreadType.User);
     api.listener.requestOldMessages(ThreadType.Group);
@@ -140,155 +154,122 @@ api.listener.on("cipher_key", () => {
 api.listener.start({ retryOnClose: true });
 ```
 
-#### 2. Trigger Mobile Backup Sync (`pull_mobile_msg`)
-```javascript
-import { SyncEventType, decryptWithPrivateKey, deriveZdbAesKey, decryptZdbBuffer } from "zca-js";
+### 4. Đồng bộ lịch sử sao lưu từ Điện thoại (`ZDB4.0`)
+
+```ts
+import fs from "node:fs";
+import {
+    SyncEventType,
+    decryptWithPrivateKey,
+    deriveZdbAesKey,
+    decryptZdbBuffer,
+    parseZdbHeader,
+} from "@softtynet/zca-js";
 
 let privateKey = "";
 
 api.listener.on("sync_event", async (event) => {
     if (event.type === SyncEventType.USER_CONFIRM) {
-        console.log("User confirmed sync on phone, waiting for backup upload...");
+        console.log("Người dùng đã bấm xác nhận trên điện thoại, đang chờ tải gói sao lưu...");
     } else if (event.type === SyncEventType.SYNCMSG_INFO) {
         const res = await api.getSyncData({ ...event.data, savePath: "./sync_data" });
         if (res.success && res.data && privateKey) {
             const rawRsa = decryptWithPrivateKey(privateKey, res.data.encrypted_key);
             const aesKey = deriveZdbAesKey(rawRsa);
-            console.log("Downloaded backup:", res.data.file_path, "AES key length:", aesKey.length);
+            const zdbPlain = decryptZdbBuffer(fs.readFileSync(res.data.file_path), aesKey);
+            const toc = parseZdbHeader(zdbPlain);
+            console.log(`Giải mã thành công ZDB4.0 (${toc.entries.length} hội thoại SQLite):`, toc.entries.slice(0, 5));
         }
     }
 });
 
-api.listener.on("connected", async () => {
-    const session = await api.requestSyncFromPhone();
+api.listener.on("cipher_key", async () => {
+    const session = await api.requestSyncFromPhone({ pcName: "Web" });
     privateKey = session.privateKey;
-    console.log("Please tap 'Sync now' on your phone!");
+    console.log("Vui lòng mở điện thoại và bấm 'Đồng bộ ngay' trên thông báo Zalo!");
 });
-
-api.listener.start();
 ```
 
-### Voice / Video Call Signaling
+### 5. Khởi tạo Cuộc gọi Thoại & Gọi Video
 
-```javascript
-import { CallType } from "zca-js";
+```ts
+import { CallType } from "@softtynet/zca-js";
 
-// Ring a user's phone (Audio or Video call)
-const call = await api.sendVoiceCall("target_user_id", { callType: CallType.Audio });
-console.log("Ringing callId:", call.callId, "session:", call.sessId);
-
-// Cancel ringing or end an active call
-await api.cancelVoiceCall("target_user_id", call.callId);
-```
+const targetUid = "5249661060655759359"; // Chuỗi UID 19 chữ số
 
-### Send a message
-
-```javascript
-import { Zalo, ThreadType } from "zca-js";
-
-const zalo = new Zalo();
-const api = await zalo.loginQR();
+// Gọi Video (CallType.Video = 3, tự động đính kèm H.264 payload 97)
+const videoCall = await api.sendVoiceCall(targetUid, {
+    callType: CallType.Video,
+});
+console.log("Đang đổ chuông Video:", videoCall.callId, videoCall.rtpServer);
 
-// Echo bot
-api.listener.on("message", (message) => {
-    const isPlainText = typeof message.data.content === "string";
-    if (message.isSelf || !isPlainText) return;
-
-    switch (message.type) {
-        case ThreadType.User: {
-            api.sendMessage(
-                {
-                    msg: "echo: " + message.data.content,
-                    quote: message.data, // the message to reply to (optional)
-                },
-                message.threadId,
-                message.type, // ThreadType.User
-            );
-            break;
-        }
-        case ThreadType.Group: {
-            api.sendMessage(
-                {
-                    msg: "echo: " + message.data.content,
-                    quote: message.data, // the message to reply to (optional)
-                },
-                message.threadId,
-                message.type, // ThreadType.Group
-            );
-            break;
-        }
-    }
+// Huỷ cuộc gọi khi đang đổ chuông
+await api.cancelVoiceCall(targetUid, videoCall.callId, {
+    callType: CallType.Video,
 });
 
-api.listener.start();
+// Hoặc gọi Thoại (CallType.Audio = 1)
+const audioCall = await api.sendVoiceCall(targetUid, {
+    callType: CallType.Audio,
+});
+await api.cancelVoiceCall(targetUid, audioCall.callId);
 ```
 
-### Get/Send a sticker
-
-```javascript
-api.getStickers("hello").then(async (stickerIds) => {
-    // Get the first sticker
+### 6. Gửi tin nhắn & Sticker
+
+```ts
+// Trả lời tin nhắn văn bản
+await api.sendMessage(
+    {
+        msg: "Xin chào từ hệ thống Softtynet!",
+        quote: message.data,
+    },
+    message.threadId,
+    message.type,
+);
+
+// Tìm và gửi Sticker
+const stickerIds = await api.getStickers("xin chào");
+if (stickerIds.length > 0) {
     const stickerObject = await api.getStickersDetail(stickerIds[0]);
-    api.sendMessageSticker(
-        stickerObject,
-        message.threadId,
-        message.type, // ThreadType.User or ThreadType.Group
-    );
-});
+    await api.sendMessageSticker(stickerObject, message.threadId, message.type);
+}
 ```
 
 ---
 
-## Example
-
-See [examples](examples) folder for more details.
-
----
+## 🧪 Kiểm định & Chạy thử nghiệm
 
-## Projects & Useful Resources
+Dự án đi kèm bộ kiểm định 2 lớp trong thư mục [`test/`](test):
 
-<div align="center">
+1. **Kiểm định tự động (Offline / Unit Verification Suite)**:
+   ```bash
+   npm run test:verify
+   ```
+   Kiểm tra tự động toàn bộ 6 hạng mục: `preloadConversations`, `requestSyncFromPhone` / `pullMobile` / `cancelPullMobile`, `getNoisedIds` / `decryptGids`, giải mã `RSA-2048` + `ZDB4.0` đa khối 64KB, `sendVoiceCall` (Audio & Video) / `cancelVoiceCall` / `endVoiceCall`, và các sự kiện WebSocket (`510`, `511`, `504`, `601`).
 
-| Repository | Description |
-|    :---    |    :---     |
-| [**ZaloDataExtractor**](https://github.com/JustKemForFun/ZaloDataExtractor) | A browser `Extension` to extract IMEI, cookies, and user agent from Zalo Web. |
-| [**MultiZlogin**](https://github.com/ChickenAI/multizlogin) | A multi-account Zalo management system that lets you log in to and manage multiple accounts simultaneously, with proxy and webhook integration. |
-| [**n8n-nodes-zalo-tools**](https://github.com/ChickenAI/zalo-node) | N8N node for personal Zalo account. |
-| [**Zalo-F12**](https://github.com/ElectroHeavenVN/Zalo-F12) | A collection of JavaScript code snippets to paste into DevTools to change how Zalo Web/PC works. |
-| [**Zalo-F12-Tools**](https://github.com/JustKemForFun/Zalo-F12-Tools) | Toggle hidden modes for Zalo Web. |
+2. **Kiểm định trực tiếp trên tài khoản Zalo thật (Live Verification Suite)**:
+   ```bash
+   # Chạy toàn bộ 6 bước (Quét QR -> Preload -> ZNoise -> OldMessages -> Đồng bộ ZDB4.0 từ ĐT -> Voice/Video Call)
+   npm run test:live
 
-</div>
+   # Chỉ test nhanh Gọi Thoại + Gọi Video tới 1 UID bạn bè
+   npm run test:live -- --only-call --call <UID_BAN_BE>
+   ```
 
 ---
 
-## Contributing
-
-We welcome contributions from the community! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details on how to:
-
-- 🐛 Report bugs and issues
-- ✨ Suggest new features
-- 🔧 Submit code contributions
-- 📚 Improve documentation
-- 🧪 Add or improve tests
-- 🔒 Report security vulnerabilities
+## 🤝 Nguồn gốc & Ghi nhận (Credits & Attribution)
 
-For more information, please read our [Code of Conduct](CODE_OF_CONDUCT.md) and [Security Policy](SECURITY.md) before participating.
-
----
+Dự án **`@softtynet/zca-js`** được phát triển, nâng cấp và duy trì bởi **Softtynet Co., Ltd.** ([`softtyos/zca-js`](https://github.com/softtyos/zca-js)), kế thừa nền tảng mã nguồn mở từ dự án gốc:
 
-## License
+- **Dự án gốc**: [RFS-ADRENO/zca-js](https://github.com/RFS-ADRENO/zca-js)
+- **Tác giả nền tảng gốc**: RFS-ADRENO, truong9c2208, JustKemForFun cùng các thành viên đóng góp từ cộng đồng mã nguồn mở.
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+Chúng tôi trân trọng cảm ơn các tác giả của dự án gốc đã xây dựng nền tảng ban đầu cho cộng đồng JavaScript/TypeScript.
 
 ---
 
-## **Support Us**
+## 📄 Giấy phép (License)
 
-- ⭐ **Star our repositories** if you find them useful!  
-- 🔄 **Share** with your network to help us grow  
-- 💡 **Contribute** your ideas and code    
-- ☕ **A coffee**:
-    - [Buy Me a Coffee](https://ko-fi.com/grosse)
-    - [Paypal](https://www.paypal.com/paypalme/dungto213)
-    - [VietQR](https://github.com/user-attachments/assets/e1f319d6-9d11-4082-8248-55b55e645caa)
-    - [Momo](https://me.momo.vn/gMIMulsaUqsbf6iAiXt3)
+Phát hành theo giấy phép [MIT License](LICENSE).

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);
+    };
+});