@softtynet/zca-js 2.3.4 → 2.3.6

package/README.md

@@ -14,10 +14,10 @@
 
 ## Điểm nổi bật
 
-- **Kiến trúc 12 Domains (`224 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%).
+- **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.
-- **Tín hiệu Gọi Thoại & Video Call 1-1**: Điều khiển trọn vẹn vòng đời cuộc gọi (`11300` $\rightarrow$ `11306`: `sendVoiceCall`, `cancelVoiceCall`, `endVoiceCall`) và lắng nghe `call_event` thời gian thực.
+- **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`)**.
 
 ---
 
@@ -55,18 +55,18 @@ const zalo = new Zalo({ imageMetadataGetter });
 
 | Phân hệ | Namespace | Số lượng API | Tài liệu chi tiết |
 | :--- | :--- | :---: | :--- |
-| **Xác thực & Phiên** | `api.auth` | 8 | [`docs/api/auth.md`](docs/api/auth.md) |
-| **Tin nhắn & Hội thoại** | `api.chat` | 35 | [`docs/api/chat.md`](docs/api/chat.md) |
-| **Nhóm & Cộng đồng** | `api.group` | 48 | [`docs/api/group.md`](docs/api/group.md) |
-| **Bạn bè & Danh bạ** | `api.friend` | 26 | [`docs/api/friend.md`](docs/api/friend.md) |
-| **Hồ sơ cá nhân** | `api.profile` | 18 | [`docs/api/profile.md`](docs/api/profile.md) |
+| **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 1-1** | `api.call` | 3 | [`docs/api/call.md`](docs/api/call.md) |
-| **Kho lưu trữ & Voice-to-Text** | `api.media` | 7 | [`docs/api/media.md`](docs/api/media.md) |
-| **Nhãn dán & Biểu cảm** | `api.sticker` | 8 | [`docs/api/sticker.md`](docs/api/sticker.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` | 41 | [`docs/api/business.md`](docs/api/business.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`.
 
@@ -125,6 +125,42 @@ const mediaList = await api.media.getConversationMedia({
 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)

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>;

package/dist/apis/call/endGroupCall.js

@@ -0,0 +1,45 @@
+import { ZaloApiError } from "../../Errors/ZaloApiError.js";
+import { apiFactory } from "../../utils.js";
+import { CallType } from "./sendVoiceCall.js";
+export const endGroupCallFactory = apiFactory()((api, ctx, utils) => {
+    const voiceCallService = api.zpwServiceMap.voice_call?.[0];
+    /**
+     * Rời khỏi hoặc kết thúc cuộc gọi nhóm (`/api/voicecall/group/endcall`, command `12438`).
+     *
+     * @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 endGroupCall(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 endGroupCall params");
+        const url = utils.makeURL(`${voiceCallService}/api/voicecall/group/endcall`, {
+            zpw_type: 24,
+            params: encryptedParams,
+        });
+        const response = await utils.request(url, {
+            method: "GET",
+        });
+        return utils.resolve(response);
+    };
+});

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

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

package/dist/apis/call/finishGroupCall.js

@@ -0,0 +1,47 @@
+import { ZaloApiError } from "../../Errors/ZaloApiError.js";
+import { apiFactory } from "../../utils.js";
+import { CallType } from "./sendVoiceCall.js";
+export const finishGroupCallFactory = apiFactory()((api, _ctx, utils) => {
+    const voiceCallService = api.zpwServiceMap.voice_call?.[0];
+    /**
+     * Gửi báo cáo hoàn tất / kết thúc phiên gọi nhóm (`/api/voicecall/group/finish`, command `12446`).
+     *
+     * @param callId ID của cuộc gọi nhóm
+     * @param options Thông tin `hostCall`, `duration`, `joinTime`, `status`, `partners` và `data`
+     * @throws {ZaloApiError}
+     */
+    return async function finishGroupCall(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 = {
+            callId,
+            callType: options.callType ?? CallType.GroupAudio,
+            data: dataStr,
+            duration: options.duration ?? 0,
+            hostCall: String(options.hostCall),
+            partners: (options.partners ?? []).map(String),
+            status: options.status ?? 0,
+            joinTime: options.joinTime ?? 0,
+        };
+        const encryptedParams = utils.encodeAES(JSON.stringify(params));
+        if (!encryptedParams)
+            throw new ZaloApiError("Failed to encrypt finishGroupCall params");
+        const url = utils.makeURL(`${voiceCallService}/api/voicecall/group/finish`, {
+            zpw_type: 24,
+            params: encryptedParams,
+        });
+        const response = await utils.request(url, {
+            method: "GET",
+        });
+        return utils.resolve(response);
+    };
+});

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

@@ -0,0 +1,3 @@
+import { CallType } from "./sendVoiceCall.js";
+export type GetGroupCallStateResponse = Record<string, unknown>;
+export declare const getGroupCallStateFactory: (ctx: import("../../context.js").ContextBase, api: import("../../apis.js").API) => (callId: number, hostCall: string, callType?: CallType | number) => Promise<GetGroupCallStateResponse>;