@softtynet/zca-js 2.3.3 → 2.3.5

package/README.md

@@ -2,10 +2,22 @@
 
 <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://softtyos.github.io/zca-js-docs/"><img src="https://img.shields.io/badge/Docs-VitePress-646cff.svg" alt="Documentation" /></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 client hỗ trợ kết nối và tương tác Zalo dành cho Node.js, TypeScript và Bun, được duy trì nội bộ bởi **Softtynet Co., Ltd.**
+**`@softtynet/zca-js`** là bộ thư viện SDK kết nối và tương tác Zalo dành cho **Node.js**, **TypeScript** và **Bun**, được phát triển và duy trì bởi **Softtynet Co., Ltd.** dựa trên phân tích giao thức Zalo PC `26.7.10`.
+
+- **Trang tài liệu chính thức (Documentation)**: [**https://softtyos.github.io/zca-js-docs/**](https://softtyos.github.io/zca-js-docs/)
+
+---
+
+## Điểm nổi bật
+
+- **Kiến trúc 12 Domains (`252 API nguyên bản`)**: Tổ chức trực quan qua `api.auth`, `api.chat`, `api.group`, `api.friend`, `api.profile`, `api.sync`, `api.zcloud`, `api.call`, `api.media`, `api.sticker`, `api.board`, `api.business` (vẫn hỗ trợ gọi phẳng `api.<method>` tương thích ngược 100%).
+- **Đồng bộ lịch sử Mobile (`ZDB 4.0`) & Catch-up Sync**: Hỗ trợ đầy đủ luồng `requestSyncFromPhone` $\rightarrow$ `getSyncData` (giải mã RSA-2048 OAEP/PKCS1 + ZDB 4.0 64KB multi-chunk AES-256-CBC + Deflate) & `pullMobile`.
+- **ZCloud, MediaStore & Bảo toàn Số nguyên 64-bit (`preParseJsonIds`)**: Tự động giữ nguyên độ chính xác chuỗi 19 chữ số cho `owner_id`, `group_id`, `globalMsgId`, `cliMsgId` trước khi `JSON.parse()` và tích hợp bộ mã hóa `98yS` AES-256-CBC cho ZCloud/ZFamily.
+- **Zalo Call Engine thuần TypeScript (`30 API` trong `api.call` + `ZaloRtcSession` / `ZaloCallController`)**: Hỗ trợ đầy đủ cả **Gọi Đi** và **Nhận Cuộc Gọi Đến** (Thoại 1-1, Video Call H.264 FU-A Annex-B 2 chiều, Gọi Nhóm), nâng cấp Thoại $\rightarrow$ Video giữa cuộc gọi, bật/tắt Camera/Mic, Tạm giữ (Hold/Unhold), Tái kết nối UDP (`reconnectUdp`), và **Bàn giao kết nối UDP trực tiếp cho Mobile App (`signalingOnly` / `handoffUdpToExternal`)**.
 
 ---
 
@@ -19,8 +31,6 @@ bun add @softtynet/zca-js
 
 ### Cấu hình `imageMetadataGetter` (Tùy chọn khi gửi ảnh từ file nội bộ)
 
-Nếu ứng dụng cần gửi ảnh hoặc GIF từ đường dẫn file trên máy, bạn có thể truyền hàm `imageMetadataGetter` (ví dụ sử dụng `sharp`):
-
 ```ts
 import { Zalo } from "@softtynet/zca-js";
 import sharp from "sharp";
@@ -41,6 +51,27 @@ const zalo = new Zalo({ imageMetadataGetter });
 
 ---
 
+## Kiến trúc 12 Phân hệ (Domains)
+
+| Phân hệ | Namespace | Số lượng API | Tài liệu chi tiết |
+| :--- | :--- | :---: | :--- |
+| **Xác thực & Phiên** | `api.auth` | 14 | [`docs/api/auth.md`](docs/api/auth.md) |
+| **Tin nhắn & Hội thoại** | `api.chat` | 41 | [`docs/api/chat.md`](docs/api/chat.md) |
+| **Nhóm & Cộng đồng** | `api.group` | 44 | [`docs/api/group.md`](docs/api/group.md) |
+| **Bạn bè & Danh bạ** | `api.friend` | 33 | [`docs/api/friend.md`](docs/api/friend.md) |
+| **Hồ sơ cá nhân** | `api.profile` | 16 | [`docs/api/profile.md`](docs/api/profile.md) |
+| **Đồng bộ Mobile ZDB 4.0** | `api.sync` | 5 | [`docs/api/sync.md`](docs/api/sync.md) |
+| **Đám mây ZCloud & ZFamily** | `api.zcloud` | 9 | [`docs/api/zcloud.md`](docs/api/zcloud.md) |
+| **Gọi thoại, Video & Gọi nhóm** | `api.call` | 30 | [`docs/api/call.md`](docs/api/call.md) |
+| **Kho lưu trữ & Voice-to-Text** | `api.media` | 8 | [`docs/api/media.md`](docs/api/media.md) |
+| **Nhãn dán & Biểu cảm** | `api.sticker` | 10 | [`docs/api/sticker.md`](docs/api/sticker.md) |
+| **Bảng tin, Bình chọn & Lịch hẹn** | `api.board` | 16 | [`docs/api/board.md`](docs/api/board.md) |
+| **Zalo Business & Danh mục** | `api.business` | 26 | [`docs/api/business.md`](docs/api/business.md) |
+
+> Xem tổng quan toàn bộ tài liệu tại [`docs/api/index.md`](docs/api/index.md) hoặc chạy trang tài liệu VitePress cục bộ bằng lệnh `npm run docs:dev`.
+
+---
+
 ## Sử dụng cơ bản
 
 ### 1. Đăng nhập bằng mã QR
@@ -53,7 +84,7 @@ const api = await zalo.loginQR();
 console.log("Đã đăng nhập:", api.getOwnId());
 ```
 
-### 2. Lắng nghe tin nhắn
+### 2. Lắng nghe sự kiện WebSocket thời gian thực
 
 ```ts
 import { Zalo, ThreadType } from "@softtynet/zca-js";
@@ -74,25 +105,72 @@ api.listener.on("message", (message) => {
 api.listener.start({ retryOnClose: true });
 ```
 
-### 3. Gửi tin nhắn văn bản & Sticker
+### 3. Gọi API theo Domain Namespace
 
 ```ts
-// Trả lời tin nhắn văn bản
-await api.sendMessage(
-    {
-        msg: "Xin chào!",
-        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]);
-    await api.sendMessageSticker(stickerObject, message.threadId, message.type);
-}
+// Nhóm & Lịch sử tin nhắn Cloud
+const groupInfo = await api.group.getGroupInfo("888999000");
+const history = await api.group.getGroupChatHistory("888999000", { count: 50, cursor: 0 });
+const msgStatus = await api.group.getGroupMessageStatus("888999000", ["1000000000000000001"]);
+
+// Kho lưu trữ Media / File / Link
+const mediaPreview = await api.media.getMediaStorePreview("888999000", 50);
+const mediaList = await api.media.getConversationMedia({
+    groupId: "888999000",
+    mediaType: "media",
+    limit: 50,
+});
+
+// Giải mã thông tin thành viên hàng loạt
+const profiles = await api.group.getGroupMembersInfo(["1000000000000000001"]);
+```
+
+### 4. Gọi Thoại, Video Call 2 chiều & Nhận Cuộc Gọi Đến (`ZaloRtcSession`)
+
+```ts
+import { CallType } from "@softtynet/zca-js";
+
+const session = api.call.createRtcSession({ autoAttachListener: true });
+
+// 1) Gọi đi (Audio hoặc Video Call)
+const params = await session.startOutgoingCall("5249661060655759359", {
+    callType: CallType.Video,
+});
+
+// 2) Nhận luồng Audio Opus & Video H.264 Annex-B thời gian thực
+session.on("audio_frame", (frame) => {
+    // frame.payload: Buffer (Opus 16kHz mono)
+});
+session.on("video_annexb_frame", (frame) => {
+    // frame.annexB: Buffer (00 00 00 01 + SPS/PPS/IDR/P-Slice), frame.isKeyframe: boolean
+});
+
+// 3) Nhận cuộc gọi đến từ sự kiện WebSocket `call_event`
+api.listener.on("call_event", async (ev) => {
+    if (ev.act === "request" || ev.act === "group_request") {
+        await session.ringIncomingCall(ev); // Báo máy đang đổ chuông (402 / 502)
+        const incomingParams = await session.acceptIncomingCall(ev, { skipRingRing: true });
+        console.log("Đã bắt máy cuộc gọi đến:", incomingParams.callId, incomingParams.rtpAddress);
+    }
+});
+
+// 4) Chế độ Worker tạo cuộc gọi và bàn giao gói UDP trực tiếp cho Mobile App:
+const handoffParams = await session.startOutgoingCall("5249661060655759359", {
+    callType: CallType.Audio,
+    signalingOnly: true, // Worker không mở UDP, xuất sẵn gói `params.mobileDirectHandoff` cho Mobile
+});
+```
+
+---
+
+## Chạy trang Tài liệu (VitePress Docs)
+
+```bash
+# Khởi chạy máy chủ tài liệu VitePress cục bộ (http://localhost:5173)
+npm run docs:dev
+
+# Sinh lại tài liệu từ mã nguồn src/apis/* và đóng gói tĩnh
+npm run docs:build
 ```
 
 ---

package/dist/apis/auth/exportSession.d.ts

@@ -0,0 +1,7 @@
+import type toughCookie from "tough-cookie";
+import type { Credentials } from "../../zalo.js";
+export type ExportedSession = Credentials & {
+    uid: string;
+    cookie: toughCookie.SerializedCookie[];
+};
+export declare const exportSessionFactory: (ctx: import("../../context.js").ContextBase, api: import("../../apis.js").API) => () => ExportedSession;

package/dist/apis/auth/exportSession.js

@@ -0,0 +1,17 @@
+import { apiFactory } from "../../utils.js";
+export const exportSessionFactory = apiFactory()((_api, ctx) => {
+    /**
+     * Xuất toàn bộ thông tin phiên đăng nhập hiện tại (`uid`, `imei`, `userAgent`, `language`, `cookie`)
+     * dưới định dạng chuẩn `Credentials` để lưu trữ (JSON/Database) và truyền trực tiếp vào `zalo.login(session)`.
+     */
+    return function exportSession() {
+        const serializedJar = ctx.cookie?.toJSON();
+        return {
+            uid: ctx.uid,
+            imei: ctx.imei,
+            userAgent: ctx.userAgent,
+            language: ctx.language || "vi",
+            cookie: serializedJar?.cookies ?? [],
+        };
+    };
+});

package/dist/apis/call/addUserGroupCall.d.ts

@@ -0,0 +1,11 @@
+import { CallType } from "./sendVoiceCall.js";
+export type AddUserGroupCallOptions = {
+    calleeId?: string;
+    callType?: CallType | number;
+    hostCall: string;
+    data?: string | Record<string, unknown>;
+    session: string;
+    partners: string[];
+};
+export type AddUserGroupCallResponse = Record<string, unknown>;
+export declare const addUserGroupCallFactory: (ctx: import("../../context.js").ContextBase, api: import("../../apis.js").API) => (callId: number, options: AddUserGroupCallOptions) => Promise<AddUserGroupCallResponse>;

package/dist/apis/call/addUserGroupCall.js

@@ -0,0 +1,48 @@
+import { ZaloApiError } from "../../Errors/ZaloApiError.js";
+import { apiFactory } from "../../utils.js";
+import { CallType } from "./sendVoiceCall.js";
+export const addUserGroupCallFactory = apiFactory()((api, _ctx, utils) => {
+    const voiceCallService = api.zpwServiceMap.voice_call?.[0];
+    /**
+     * Mời thêm thành viên vào cuộc gọi nhóm đang diễn ra (`/api/voicecall/group/adduser`, command `12435`).
+     *
+     * @param callId ID của cuộc gọi nhóm
+     * @param options Thông tin `hostCall`, `session`, `partners`, `calleeId`, `callType` và `data`
+     * @throws {ZaloApiError}
+     */
+    return async function addUserGroupCall(callId, options) {
+        if (!callId)
+            throw new ZaloApiError("Missing callId");
+        if (!options?.hostCall)
+            throw new ZaloApiError("Missing hostCall");
+        if (!options?.session)
+            throw new ZaloApiError("Missing session");
+        if (!voiceCallService)
+            throw new ZaloApiError("Missing voice_call service URL in zpwServiceMap");
+        const dataStr = options.data === undefined
+            ? "{}"
+            : typeof options.data === "string"
+                ? options.data
+                : JSON.stringify(options.data);
+        const params = {
+            calleeId: options.calleeId ?? "",
+            callId,
+            callType: options.callType ?? CallType.GroupAudio,
+            hostCall: String(options.hostCall),
+            data: dataStr,
+            session: options.session,
+            partners: (options.partners ?? []).map(String),
+        };
+        const encryptedParams = utils.encodeAES(JSON.stringify(params));
+        if (!encryptedParams)
+            throw new ZaloApiError("Failed to encrypt addUserGroupCall params");
+        const url = utils.makeURL(`${voiceCallService}/api/voicecall/group/adduser`, {
+            zpw_type: 24,
+            params: encryptedParams,
+        });
+        const response = await utils.request(url, {
+            method: "GET",
+        });
+        return utils.resolve(response);
+    };
+});

package/dist/apis/call/answerAckVoiceCall.d.ts

@@ -0,0 +1,5 @@
+export type AnswerAckVoiceCallOptions = {
+    status?: number;
+};
+export type AnswerAckVoiceCallResponse = Record<string, unknown>;
+export declare const answerAckVoiceCallFactory: (ctx: import("../../context.js").ContextBase, api: import("../../apis.js").API) => (calleeId: string, callId: number, options?: AnswerAckVoiceCallOptions) => Promise<AnswerAckVoiceCallResponse>;

package/dist/apis/call/answerAckVoiceCall.js

@@ -0,0 +1,38 @@
+import { ZaloApiError } from "../../Errors/ZaloApiError.js";
+import { apiFactory } from "../../utils.js";
+export const answerAckVoiceCallFactory = apiFactory()((api, ctx, utils) => {
+    const voiceCallService = api.zpwServiceMap.voice_call?.[0];
+    /**
+     * Xác nhận bắt tay hoàn tất từ phía người gọi sau khi người nhận bắt máy (`/api/voicecall/answerack`, command `11304`, signal `408`).
+     *
+     * @param calleeId User ID của người nhận cuộc gọi
+     * @param callId ID của cuộc gọi
+     * @param options Tuỳ chọn mã trạng thái (`status`, mặc định `0`)
+     * @throws {ZaloApiError}
+     */
+    return async function answerAckVoiceCall(calleeId, callId, options = {}) {
+        if (!calleeId)
+            throw new ZaloApiError("Missing calleeId");
+        if (!callId)
+            throw new ZaloApiError("Missing callId");
+        if (!voiceCallService)
+            throw new ZaloApiError("Missing voice_call service URL in zpwServiceMap");
+        const params = {
+            calleeId: String(calleeId),
+            callId,
+            status: options.status ?? 0,
+            imei: ctx.imei,
+        };
+        const encryptedParams = utils.encodeAES(JSON.stringify(params));
+        if (!encryptedParams)
+            throw new ZaloApiError("Failed to encrypt answerAckVoiceCall params");
+        const url = utils.makeURL(`${voiceCallService}/api/voicecall/answerack`, {
+            zpw_type: 24,
+            params: encryptedParams,
+        });
+        const response = await utils.request(url, {
+            method: "GET",
+        });
+        return utils.resolve(response);
+    };
+});

package/dist/apis/call/answerGroupCall.d.ts

@@ -0,0 +1,10 @@
+import { CallType } from "./sendVoiceCall.js";
+export type AnswerGroupCallOptions = {
+    calleeId?: string;
+    callType?: CallType | number;
+    hostCall: string;
+    data?: string | Record<string, unknown>;
+    partners?: string[];
+};
+export type AnswerGroupCallResponse = Record<string, unknown>;
+export declare const answerGroupCallFactory: (ctx: import("../../context.js").ContextBase, api: import("../../apis.js").API) => (callId: number, options: AnswerGroupCallOptions) => Promise<AnswerGroupCallResponse>;

package/dist/apis/call/answerGroupCall.js

@@ -0,0 +1,45 @@
+import { ZaloApiError } from "../../Errors/ZaloApiError.js";
+import { apiFactory } from "../../utils.js";
+import { CallType } from "./sendVoiceCall.js";
+export const answerGroupCallFactory = apiFactory()((api, ctx, utils) => {
+    const voiceCallService = api.zpwServiceMap.voice_call?.[0];
+    /**
+     * Chấp nhận / Nghe cuộc gọi nhóm đến (`/api/voicecall/group/answer`, command `12436`).
+     *
+     * @param callId ID của cuộc gọi nhóm
+     * @param options Thông tin `hostCall`, `calleeId`, `callType`, `partners` và `data`
+     * @throws {ZaloApiError}
+     */
+    return async function answerGroupCall(callId, options) {
+        if (!callId)
+            throw new ZaloApiError("Missing callId");
+        if (!options?.hostCall)
+            throw new ZaloApiError("Missing hostCall");
+        if (!voiceCallService)
+            throw new ZaloApiError("Missing voice_call service URL in zpwServiceMap");
+        const dataStr = options.data === undefined
+            ? "{}"
+            : typeof options.data === "string"
+                ? options.data
+                : JSON.stringify(options.data);
+        const params = {
+            calleeId: String(options.calleeId ?? ctx.uid),
+            callId,
+            callType: options.callType ?? CallType.GroupAudio,
+            hostCall: String(options.hostCall),
+            data: dataStr,
+            partners: (options.partners ?? []).map(String),
+        };
+        const encryptedParams = utils.encodeAES(JSON.stringify(params));
+        if (!encryptedParams)
+            throw new ZaloApiError("Failed to encrypt answerGroupCall params");
+        const url = utils.makeURL(`${voiceCallService}/api/voicecall/group/answer`, {
+            zpw_type: 24,
+            params: encryptedParams,
+        });
+        const response = await utils.request(url, {
+            method: "GET",
+        });
+        return utils.resolve(response);
+    };
+});

package/dist/apis/call/answerVoiceCall.d.ts

@@ -0,0 +1,11 @@
+export type AnswerVoiceCallOptions = {
+    status?: number;
+    codec?: string;
+    rtcpAddress?: string;
+    rtpAddress?: string;
+    sessionId?: string;
+    extendData?: string | Record<string, unknown>;
+    subCommand?: number;
+};
+export type AnswerVoiceCallResponse = Record<string, unknown>;
+export declare const answerVoiceCallFactory: (ctx: import("../../context.js").ContextBase, api: import("../../apis.js").API) => (callerId: string, callId: number, options?: AnswerVoiceCallOptions) => Promise<AnswerVoiceCallResponse>;

package/dist/apis/call/answerVoiceCall.js

@@ -0,0 +1,50 @@
+import { ZaloApiError } from "../../Errors/ZaloApiError.js";
+import { apiFactory } from "../../utils.js";
+export const answerVoiceCallFactory = apiFactory()((api, _ctx, utils) => {
+    const voiceCallService = api.zpwServiceMap.voice_call?.[0];
+    /**
+     * Chấp nhận / Nghe cuộc gọi thoại hoặc video đến (`/api/voicecall/answer`, command `11303`, signal `402`).
+     *
+     * @param callerId User ID của người gọi đến
+     * @param callId ID của cuộc gọi
+     * @param options Thông tin `sessionId`, `rtpAddress`, `rtcpAddress`, `codec`, `extendData` và `status`
+     * @throws {ZaloApiError}
+     */
+    return async function answerVoiceCall(callerId, callId, options = {}) {
+        if (!callerId)
+            throw new ZaloApiError("Missing callerId");
+        if (!callId)
+            throw new ZaloApiError("Missing callId");
+        if (!voiceCallService)
+            throw new ZaloApiError("Missing voice_call service URL in zpwServiceMap");
+        const extendDataStr = options.extendData === undefined
+            ? undefined
+            : typeof options.extendData === "string"
+                ? options.extendData
+                : JSON.stringify(options.extendData);
+        const params = {
+            callerId: String(callerId),
+            callId,
+            status: options.status ?? 0,
+            codec: options.codec ?? "",
+            rtcpAddress: options.rtcpAddress ?? "",
+            rtpAddress: options.rtpAddress ?? "",
+            session_id: options.sessionId ?? "",
+        };
+        if (extendDataStr) {
+            params.extendData = extendDataStr;
+            params.subCommand = options.subCommand ?? 3;
+        }
+        const encryptedParams = utils.encodeAES(JSON.stringify(params));
+        if (!encryptedParams)
+            throw new ZaloApiError("Failed to encrypt answerVoiceCall params");
+        const url = utils.makeURL(`${voiceCallService}/api/voicecall/answer`, {
+            zpw_type: 24,
+            params: encryptedParams,
+        });
+        const response = await utils.request(url, {
+            method: "GET",
+        });
+        return utils.resolve(response);
+    };
+});

package/dist/apis/call/broadcastGroupCallState.d.ts

@@ -0,0 +1,10 @@
+export type BroadcastGroupCallStateOptions = {
+    hostCall: string;
+    userId?: string;
+    callState?: number;
+    audioState?: number;
+    videoState?: number;
+    params?: string | Record<string, unknown>;
+};
+export type BroadcastGroupCallStateResponse = Record<string, unknown>;
+export declare const broadcastGroupCallStateFactory: (ctx: import("../../context.js").ContextBase, api: import("../../apis.js").API) => (callId: number, options: BroadcastGroupCallStateOptions) => Promise<BroadcastGroupCallStateResponse>;

package/dist/apis/call/broadcastGroupCallState.js

@@ -0,0 +1,45 @@
+import { ZaloApiError } from "../../Errors/ZaloApiError.js";
+import { apiFactory } from "../../utils.js";
+export const broadcastGroupCallStateFactory = apiFactory()((api, ctx, utils) => {
+    const voiceCallService = api.zpwServiceMap.voice_call?.[0];
+    /**
+     * Phát (broadcast) trạng thái âm thanh / hình ảnh của thành viên trong cuộc gọi nhóm (`/api/voicecall/group/broadcast`, command `12098`).
+     *
+     * @param callId ID của cuộc gọi nhóm
+     * @param options Thông tin `hostCall`, `userId`, `callState`, `audioState`, `videoState` và `params`
+     * @throws {ZaloApiError}
+     */
+    return async function broadcastGroupCallState(callId, options) {
+        if (!callId)
+            throw new ZaloApiError("Missing callId");
+        if (!options?.hostCall)
+            throw new ZaloApiError("Missing hostCall");
+        if (!voiceCallService)
+            throw new ZaloApiError("Missing voice_call service URL in zpwServiceMap");
+        const paramsStr = options.params === undefined
+            ? "{}"
+            : typeof options.params === "string"
+                ? options.params
+                : JSON.stringify(options.params);
+        const payload = {
+            callId,
+            hostCall: String(options.hostCall),
+            userId: String(options.userId ?? ctx.uid),
+            callstate: options.callState ?? 1,
+            audiostate: options.audioState ?? 1,
+            videostate: options.videoState ?? 0,
+            params: paramsStr,
+        };
+        const encryptedParams = utils.encodeAES(JSON.stringify(payload));
+        if (!encryptedParams)
+            throw new ZaloApiError("Failed to encrypt broadcastGroupCallState params");
+        const url = utils.makeURL(`${voiceCallService}/api/voicecall/group/broadcast`, {
+            zpw_type: 24,
+            params: encryptedParams,
+        });
+        const response = await utils.request(url, {
+            method: "GET",
+        });
+        return utils.resolve(response);
+    };
+});

package/dist/apis/call/cancelGroupCall.d.ts

@@ -0,0 +1,10 @@
+import { CallType } from "./sendVoiceCall.js";
+export type CancelGroupCallOptions = {
+    calleeId?: string;
+    callType?: CallType | number;
+    hostCall: string;
+    data?: string | Record<string, unknown>;
+    partners?: string[];
+};
+export type CancelGroupCallResponse = Record<string, unknown>;
+export declare const cancelGroupCallFactory: (ctx: import("../../context.js").ContextBase, api: import("../../apis.js").API) => (callId: number, options: CancelGroupCallOptions) => Promise<CancelGroupCallResponse>;

package/dist/apis/call/cancelGroupCall.js

@@ -0,0 +1,45 @@
+import { ZaloApiError } from "../../Errors/ZaloApiError.js";
+import { apiFactory } from "../../utils.js";
+import { CallType } from "./sendVoiceCall.js";
+export const cancelGroupCallFactory = apiFactory()((api, ctx, utils) => {
+    const voiceCallService = api.zpwServiceMap.voice_call?.[0];
+    /**
+     * Từ chối / Huỷ lời mời tham gia cuộc gọi nhóm (`/api/voicecall/group/cancel`, command `12437`).
+     *
+     * @param callId ID của cuộc gọi nhóm
+     * @param options Thông tin `hostCall`, `calleeId`, `callType`, `partners` và `data`
+     * @throws {ZaloApiError}
+     */
+    return async function cancelGroupCall(callId, options) {
+        if (!callId)
+            throw new ZaloApiError("Missing callId");
+        if (!options?.hostCall)
+            throw new ZaloApiError("Missing hostCall");
+        if (!voiceCallService)
+            throw new ZaloApiError("Missing voice_call service URL in zpwServiceMap");
+        const dataStr = options.data === undefined
+            ? "{}"
+            : typeof options.data === "string"
+                ? options.data
+                : JSON.stringify(options.data);
+        const params = {
+            calleeId: String(options.calleeId ?? ctx.uid),
+            callId,
+            callType: options.callType ?? CallType.GroupAudio,
+            hostCall: String(options.hostCall),
+            data: dataStr,
+            partners: (options.partners ?? []).map(String),
+        };
+        const encryptedParams = utils.encodeAES(JSON.stringify(params));
+        if (!encryptedParams)
+            throw new ZaloApiError("Failed to encrypt cancelGroupCall params");
+        const url = utils.makeURL(`${voiceCallService}/api/voicecall/group/cancel`, {
+            zpw_type: 24,
+            params: encryptedParams,
+        });
+        const response = await utils.request(url, {
+            method: "GET",
+        });
+        return utils.resolve(response);
+    };
+});

package/dist/apis/call/cancelVoiceCall.d.ts

@@ -1,6 +1,6 @@
 import { CallType } from "./sendVoiceCall.js";
 export type CancelVoiceCallOptions = {
-    callType?: CallType;
+    callType?: CallType | number;
     status?: number;
 };
 export type CancelVoiceCallResponse = Record<string, unknown>;

package/dist/apis/call/cancelVoiceCall.js

@@ -18,10 +18,14 @@ export const cancelVoiceCallFactory = apiFactory()((api, ctx, utils) => {
             throw new ZaloApiError("Missing callId");
         if (!voiceCallService)
             throw new ZaloApiError("Missing voice_call service URL in zpwServiceMap");
+        const rawCallType = options.callType ?? CallType.Audio;
+        // Khớp với ZMessageSerializer::sendCancelCall (0x100026acc): callType = (callType != 1 ? 1 : 0)
+        // Cho phép truyền trực tiếp 0 (Audio) hoặc 1 (Video), hoặc CallType.Audio (1) -> 0, CallType.Video (3) -> 1
+        const normalizedCallType = rawCallType === 0 || rawCallType === CallType.Audio ? 0 : 1;
         const params = {
             callerId: String(calleeId),
             callId,
-            callType: options.callType ?? CallType.Audio,
+            callType: normalizedCallType,
             status: options.status ?? 0,
             imei: ctx.imei,
         };

package/dist/apis/call/createController.d.ts

@@ -0,0 +1,7 @@
+import type { API } from "../../apis.js";
+import { ZaloCallController, type ZaloCallControllerOptions } from "../../call-engine/ZaloCallController.js";
+import type { ContextSession } from "../../context.js";
+/**
+ * Khởi tạo bộ điều phối cuộc gọi thuần TypeScript `ZaloCallController` (tích hợp `ZaloRtcSession` và kênh IPC `ZaloCallTransport`).
+ */
+export declare function createControllerFactory(_ctx: ContextSession, api: API): (options?: ZaloCallControllerOptions) => ZaloCallController;

package/dist/apis/call/createController.js

@@ -0,0 +1,9 @@
+import { ZaloCallController } from "../../call-engine/ZaloCallController.js";
+/**
+ * Khởi tạo bộ điều phối cuộc gọi thuần TypeScript `ZaloCallController` (tích hợp `ZaloRtcSession` và kênh IPC `ZaloCallTransport`).
+ */
+export function createControllerFactory(_ctx, api) {
+    return function createController(options = {}) {
+        return new ZaloCallController(api, options);
+    };
+}

package/dist/apis/call/createRtcSession.d.ts

@@ -0,0 +1,8 @@
+import type { API } from "../../apis.js";
+import { ZaloRtcSession, type ZaloRtcSessionOptions } from "../../call-engine/ZaloRtcSession.js";
+import type { ContextSession } from "../../context.js";
+/**
+ * Khởi tạo phiên gọi Thoại & Video thuần TypeScript / Node.js (`ZaloRtcSession` — UDP `ZRTPPacket` + `SRTP`)
+ * hoạt động độc lập 100% trên Worker / Server / Desktop / Mobile Bridge mà không cần cài đặt Zalo PC.
+ */
+export declare function createRtcSessionFactory(_ctx: ContextSession, api: API): (options?: ZaloRtcSessionOptions) => ZaloRtcSession;

package/dist/apis/call/createRtcSession.js

@@ -0,0 +1,10 @@
+import { ZaloRtcSession } from "../../call-engine/ZaloRtcSession.js";
+/**
+ * Khởi tạo phiên gọi Thoại & Video thuần TypeScript / Node.js (`ZaloRtcSession` — UDP `ZRTPPacket` + `SRTP`)
+ * hoạt động độc lập 100% trên Worker / Server / Desktop / Mobile Bridge mà không cần cài đặt Zalo PC.
+ */
+export function createRtcSessionFactory(_ctx, api) {
+    return function createRtcSession(options = {}) {
+        return new ZaloRtcSession(api, options);
+    };
+}

package/dist/apis/call/endGroupCall.d.ts

@@ -0,0 +1,10 @@
+import { CallType } from "./sendVoiceCall.js";
+export type EndGroupCallOptions = {
+    calleeId?: string;
+    callType?: CallType | number;
+    hostCall: string;
+    data?: string | Record<string, unknown>;
+    partners?: string[];
+};
+export type EndGroupCallResponse = Record<string, unknown>;
+export declare const endGroupCallFactory: (ctx: import("../../context.js").ContextBase, api: import("../../apis.js").API) => (callId: number, options: EndGroupCallOptions) => Promise<EndGroupCallResponse>;