@softtynet/zca-js 2.3.4 → 2.3.5

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export * from "./models/index.js";
 export * from "./constants/index.js";
 export * from "./crypto/index.js";
 export * from "./core/index.js";
+export * from "./realtime/index.js";
 export * from "./zalo.js";
 export type { AuthDomainAPI, BoardDomainAPI, BusinessDomainAPI, CallDomainAPI, ChatDomainAPI, FriendDomainAPI, GroupDomainAPI, MediaDomainAPI, ProfileDomainAPI, StickerDomainAPI, SyncDomainAPI, ZcloudDomainAPI, } from "./apis.js";
 export type { ContextSession, ContextBase, AppContextExtended, AppContextBase, Options, ZPWServiceMap, ImageMetadataGetter, ImageMetadataGetterResponse, ViewerKeyCacheEntry } from "./context.js";
@@ -100,6 +101,7 @@ export type { GetListBankResponse } from "./apis/business/getListBank.js";
 export type { GetListBankAccountResponse } from "./apis/business/getListBankAccount.js";
 export type { BoardItem, GetListBoardResponse, ListBoardOptions } from "./apis/board/getListBoard.js";
 export type { GetListDeviceResponse } from "./apis/auth/getListDevice.js";
+export type { GetListPinTopicsResponse } from "./apis/board/getListPinTopics.js";
 export type { GetListReminderResponse, ListReminderOptions, ReminderListGroup, ReminderListUser } from "./apis/board/getListReminder.js";
 export type { GetMultiUsersByPhonesResponse } from "./apis/friend/getMultiUsersByPhones.js";
 export type { GetMuteResponse, MuteEntriesInfo } from "./apis/chat/getMute.js";
@@ -160,7 +162,7 @@ export type { SendStickerResponse, SendStickerPayload } from "./apis/chat/sendSt
 export type { SendTypingEventResponse } from "./apis/chat/sendTypingEvent.js";
 export type { SendVideoOptions, SendVideoResponse } from "./apis/chat/sendVideo.js";
 export type { SendVoiceOptions, SendVoiceResponse } from "./apis/chat/sendVoice.js";
-export type { RequestCallServerInfo, SendVoiceCallOptions, SendVoiceCallResponse } from "./apis/call/sendVoiceCall.js";
+export type { RequestCallServerEntry, RequestCallServerInfo, SendVoiceCallOptions, SendVoiceCallResponse } from "./apis/call/sendVoiceCall.js";
 export type { SetHiddenConversationsResponse } from "./apis/chat/setHiddenConversations.js";
 export type { SetMuteParams, SetMuteResponse } from "./apis/chat/setMute.js";
 export type { SetPinnedConversationsResponse } from "./apis/chat/setPinnedConversations.js";
@@ -190,15 +192,15 @@ export type { VotePollResponse } from "./apis/board/votePoll.js";
 export type { CustomAPICallback, CustomAPIProps } from "./apis/custom.js";
 export type { ClearUnreadFriendRequestsResponse } from "./apis/friend/clearUnreadFriendRequests.js";
 export type { EncryptGidsResponse } from "./apis/auth/encryptGids.js";
-export type { GetAliasListV2Response } from "./apis/friend/getAliasListV2.js";
+export type { AliasItemV2, GetAliasListV2Response } from "./apis/friend/getAliasListV2.js";
 export type { GetBlockFriendsResponse } from "./apis/friend/getBlockFriends.js";
 export type { GetCloudInfoResponse } from "./apis/zcloud/getCloudInfo.js";
 export type { GetCloudSettingsResponse } from "./apis/zcloud/getCloudSettings.js";
 export type { GetCloudViewerKeyResponse } from "./apis/zcloud/getCloudViewerKey.js";
 export type { GetConversationMediaOptions, GetConversationMediaResponse, MediaStoreItem, MediaStoreType, } from "./apis/media/getConversationMedia.js";
-export type { GetEmojiStatusConfigResponse } from "./apis/profile/getEmojiStatusConfig.js";
+export type { EmojiStatusItem, GetEmojiStatusConfigResponse } from "./apis/profile/getEmojiStatusConfig.js";
 export type { GetExtraFriendInfoResponse } from "./apis/friend/getExtraFriendInfo.js";
-export type { GetExtraGroupInfoResponse } from "./apis/group/getExtraGroupInfo.js";
+export type { ExtraContextInfo, GetExtraGroupInfoResponse } from "./apis/group/getExtraGroupInfo.js";
 export type { GetFamilyProfileResponse } from "./apis/zcloud/getFamilyProfile.js";
 export type { GetFamilyUsageResponse } from "./apis/zcloud/getFamilyUsage.js";
 export type { GetFamilyViewerKeyResponse } from "./apis/zcloud/getFamilyViewerKey.js";
@@ -229,6 +231,31 @@ export type { UpdateRecentSearchOptions, UpdateRecentSearchResponse } from "./ap
 export type { VerifyCloudMediaOptions, VerifyCloudMediaResponse } from "./apis/zcloud/verifyCloudMedia.js";
 export type { VoiceToTextResponse } from "./apis/media/voiceToText.js";
 export type { Voice2TextEvent, Voice2TextEventData } from "./apis/listen.js";
+export type { AddUserGroupCallOptions, AddUserGroupCallResponse } from "./apis/call/addUserGroupCall.js";
+export type { AnswerAckVoiceCallOptions, AnswerAckVoiceCallResponse } from "./apis/call/answerAckVoiceCall.js";
+export type { AnswerGroupCallOptions, AnswerGroupCallResponse } from "./apis/call/answerGroupCall.js";
+export type { AnswerVoiceCallOptions, AnswerVoiceCallResponse } from "./apis/call/answerVoiceCall.js";
+export type { BroadcastGroupCallStateOptions, BroadcastGroupCallStateResponse } from "./apis/call/broadcastGroupCallState.js";
+export type { CancelGroupCallOptions, CancelGroupCallResponse } from "./apis/call/cancelGroupCall.js";
+export type { EndGroupCallOptions, EndGroupCallResponse } from "./apis/call/endGroupCall.js";
+export type { FinishGroupCallOptions, FinishGroupCallResponse } from "./apis/call/finishGroupCall.js";
+export type { GetGroupCallStateResponse } from "./apis/call/getGroupCallState.js";
+export type { HoldVoiceCallOptions, HoldVoiceCallResponse } from "./apis/call/holdVoiceCall.js";
+export type { JoinGroupCallOptions, JoinGroupCallResponse } from "./apis/call/joinGroupCall.js";
+export type { LogEndVoiceCallOptions, LogEndVoiceCallResponse } from "./apis/call/logEndVoiceCall.js";
+export type { NotifyGroupCallOptions, NotifyGroupCallResponse } from "./apis/call/notifyGroupCall.js";
+export type { PingGroupCallOptions, PingGroupCallResponse } from "./apis/call/pingGroupCall.js";
+export type { RequestAudioToVideoCallOptions, RequestAudioToVideoCallResponse } from "./apis/call/requestAudioToVideoCall.js";
+export type { RequestGroupCallOptions, RequestGroupCallResponse } from "./apis/call/requestGroupCall.js";
+export type { RequestShareScreenCallOptions, RequestShareScreenCallResponse } from "./apis/call/requestShareScreenCall.js";
+export type { RequestVoiceCallOptions, RequestVoiceCallResponse } from "./apis/call/requestVoiceCall.js";
+export type { RingRingGroupCallOptions, RingRingGroupCallResponse } from "./apis/call/ringRingGroupCall.js";
+export type { RingRingVoiceCallOptions, RingRingVoiceCallResponse } from "./apis/call/ringRingVoiceCall.js";
+export type { SendRequestGroupCallOptions, SendRequestGroupCallResponse } from "./apis/call/sendRequestGroupCall.js";
+export type { SendRequestVoiceCallOptions, SendRequestVoiceCallResponse } from "./apis/call/sendRequestVoiceCall.js";
+export type { ShareScreenGroupCallOptions, ShareScreenGroupCallResponse } from "./apis/call/shareScreenGroupCall.js";
+export type { UnholdVoiceCallOptions, UnholdVoiceCallResponse } from "./apis/call/unholdVoiceCall.js";
+export type { UpdateCallMediaStateOptions, UpdateCallMediaStateResponse } from "./apis/call/updateCallMediaState.js";
 export { CloseReason } from "./apis/listen.js";
 export { LoginQRCallbackEventType } from "./apis/loginQR.js";
 export { FriendRecommendationsType } from "./apis/friend/getFriendRecommendations.js";
@@ -240,4 +267,5 @@ export { ChatTTL } from "./apis/chat/updateAutoDeleteChat.js";
 export { UpdateLangAvailableLanguages } from "./apis/auth/updateLang.js";
 export { UpdateSettingsType } from "./apis/profile/updateSettings.js";
 export { CallType } from "./apis/call/sendVoiceCall.js";
+export { DEFAULT_ZALOCALL_IPC_KEY_BASE64, DEFAULT_ZALO_AUDIO_CODEC, DEFAULT_ZALO_VIDEO_CODEC, ZRTCMediaSubCommand, ZRTPControlCommand, ZRTPForwardSubCommand, ZRTPLegacyMediaType, ZRTCRole, ZaloCallController, ZaloCallTransport, ZaloRtcSession, ZaloSrtpSession, buildEchoRequest, buildEndCallRequest, buildInitCallRequest, buildInitCallResponse, buildPingRequest, buildPingResponse, buildRelayPingRequest, buildRequestForwardPacket, buildRtpPacket, buildZrtcExtendData, deriveSrtpSessionKey, generateSrtpMasterKeyBase64, parseIncomingCallEvent, parseRtpPacket, parseZRTPPacket, uidToUint32, wrapLegacyMediaPacket, wrapZrtcMediaPacket, type AcceptIncomingCallOptions, type BuildRtpPacketOptions, type IncomingAudioFrameEvent, type IncomingRtcpEvent, type IncomingRtpEvent, type IncomingVideoAnnexBFrameEvent, type IncomingVideoFrameEvent, type JoinGroupCallSessionOptions, type MakeDesktopCallOptions, type MakeDesktopGroupCallOptions, type ParsedIncomingCallInfo, type ParsedRtpPacket, type ParsedZRTPPacket, type RejectIncomingCallOptions, type SrtpCryptoSuite, type StartGroupCallOptions, type StartOutgoingCallOptions, type ZRTCMultiplexedMediaPacket, type ZRTCP2PPacket, type ZRTPControlPacket, type ZRTPEchoRequestOptions, type ZRTPEndCallRequestOptions, type ZRTPInitCallRequestOptions, type ZRTPInitCallResponseOptions, type ZRTPLegacyMediaPacket, type ZRTPPingRequestOptions, type ZRTPRawPacket, type ZRTPRelayPingRequestOptions, type ZRTPRequestForwardOptions, type ZaloCallConnectionParams, type ZaloCallControllerEvents, type ZaloCallControllerOptions, type ZaloCallIpcMessage, type ZaloCallMediaStateEvent, type ZaloCallSignalPayload, type ZaloCallTransportEvents, type ZaloCallTransportOptions, type ZaloMobileDirectHandoffBundle, type ZaloRtcSessionEvents, type ZaloRtcSessionOptions, type ZaloRtcSessionState, type ZrtcExtendDataOptions, } from "./call-engine/index.js";
 export { generateRSAKeyPair, decryptWithPrivateKey, deriveZdbAesKey, decryptZdbBuffer, parseZdbHeader, encryptZCloudAES, decryptZCloudAES, preParseJsonIds, type ZdbTocEntry, } from "./utils.js";

package/dist/index.js

@@ -3,6 +3,7 @@ export * from "./models/index.js";
 export * from "./constants/index.js";
 export * from "./crypto/index.js";
 export * from "./core/index.js";
+export * from "./realtime/index.js";
 export * from "./zalo.js";
 // Others (Enum)
 export { CloseReason } from "./apis/listen.js";
@@ -16,4 +17,5 @@ export { ChatTTL } from "./apis/chat/updateAutoDeleteChat.js";
 export { UpdateLangAvailableLanguages } from "./apis/auth/updateLang.js";
 export { UpdateSettingsType } from "./apis/profile/updateSettings.js";
 export { CallType } from "./apis/call/sendVoiceCall.js";
+export { DEFAULT_ZALOCALL_IPC_KEY_BASE64, DEFAULT_ZALO_AUDIO_CODEC, DEFAULT_ZALO_VIDEO_CODEC, ZRTCMediaSubCommand, ZRTPControlCommand, ZRTPForwardSubCommand, ZRTPLegacyMediaType, ZRTCRole, ZaloCallController, ZaloCallTransport, ZaloRtcSession, ZaloSrtpSession, buildEchoRequest, buildEndCallRequest, buildInitCallRequest, buildInitCallResponse, buildPingRequest, buildPingResponse, buildRelayPingRequest, buildRequestForwardPacket, buildRtpPacket, buildZrtcExtendData, deriveSrtpSessionKey, generateSrtpMasterKeyBase64, parseIncomingCallEvent, parseRtpPacket, parseZRTPPacket, uidToUint32, wrapLegacyMediaPacket, wrapZrtcMediaPacket, } from "./call-engine/index.js";
 export { generateRSAKeyPair, decryptWithPrivateKey, deriveZdbAesKey, decryptZdbBuffer, parseZdbHeader, encryptZCloudAES, decryptZCloudAES, preParseJsonIds, } from "./utils.js";

package/dist/models/CallEvent.d.ts

@@ -1,11 +1,24 @@
 export declare enum CallEventType {
     REQUEST = "request",
     ANSWER = "answer",
+    ANSWER_ACK = "answer_ack",
     CANCEL = "cancel",
     END = "end",
     RINGRING = "ringring",
+    ONOFF_CAMERA = "onoff_camera",
+    MUTE_AUDIO = "mute_audio",
+    AUDIO_TO_VIDEO = "audio_to_video",
+    SHARE_SCREEN = "share_screen",
     GROUP_REQUEST = "group_request",
+    GROUP_RINGRING = "group_ring_ring",
     GROUP_ANSWER = "group_answer",
+    GROUP_ANSWER_ACK = "group_answer_ack",
+    GROUP_CANCEL = "group_cancel",
+    GROUP_END = "group_end_call",
+    GROUP_ADD_USER = "group_add_user",
+    GROUP_NOTIFY = "group_notify",
+    GROUP_BROADCAST = "group_broadcast",
+    GROUP_BROADCAST_CONFIG = "group_broadcast_config",
     UNKNOWN = "unknown"
 }
 export type TCallEventData = {
@@ -18,6 +31,8 @@ export type TCallEventData = {
     sessId?: string;
     status?: number;
     callType?: number;
+    codec?: string;
+    params?: string | Record<string, unknown>;
     ts?: number | string;
     [key: string]: unknown;
 };

package/dist/models/CallEvent.js

@@ -2,11 +2,24 @@ export var CallEventType;
 (function (CallEventType) {
     CallEventType["REQUEST"] = "request";
     CallEventType["ANSWER"] = "answer";
+    CallEventType["ANSWER_ACK"] = "answer_ack";
     CallEventType["CANCEL"] = "cancel";
     CallEventType["END"] = "end";
     CallEventType["RINGRING"] = "ringring";
+    CallEventType["ONOFF_CAMERA"] = "onoff_camera";
+    CallEventType["MUTE_AUDIO"] = "mute_audio";
+    CallEventType["AUDIO_TO_VIDEO"] = "audio_to_video";
+    CallEventType["SHARE_SCREEN"] = "share_screen";
     CallEventType["GROUP_REQUEST"] = "group_request";
+    CallEventType["GROUP_RINGRING"] = "group_ring_ring";
     CallEventType["GROUP_ANSWER"] = "group_answer";
+    CallEventType["GROUP_ANSWER_ACK"] = "group_answer_ack";
+    CallEventType["GROUP_CANCEL"] = "group_cancel";
+    CallEventType["GROUP_END"] = "group_end_call";
+    CallEventType["GROUP_ADD_USER"] = "group_add_user";
+    CallEventType["GROUP_NOTIFY"] = "group_notify";
+    CallEventType["GROUP_BROADCAST"] = "group_broadcast";
+    CallEventType["GROUP_BROADCAST_CONFIG"] = "group_broadcast_config";
     CallEventType["UNKNOWN"] = "unknown";
 })(CallEventType || (CallEventType = {}));
 export function initializeCallEvent(data, act, act_type) {
@@ -18,30 +31,111 @@ export function initializeCallEvent(data, act, act_type) {
         case "answer":
             type = CallEventType.ANSWER;
             break;
+        case "answer_ack":
+        case "answerack":
+            type = CallEventType.ANSWER_ACK;
+            break;
         case "cancel":
             type = CallEventType.CANCEL;
             break;
         case "end":
         case "endcall":
+        case "end_call":
             type = CallEventType.END;
             break;
         case "ringring":
+        case "ring_ring":
             type = CallEventType.RINGRING;
             break;
+        case "onoff_camera":
+            type = CallEventType.ONOFF_CAMERA;
+            break;
+        case "mute_audio":
+            type = CallEventType.MUTE_AUDIO;
+            break;
+        case "audio_to_video":
+            type = CallEventType.AUDIO_TO_VIDEO;
+            break;
+        case "share_screen":
+            type = CallEventType.SHARE_SCREEN;
+            break;
         case "group_request":
             type = CallEventType.GROUP_REQUEST;
             break;
+        case "group_ring_ring":
+        case "group_ringring":
+            type = CallEventType.GROUP_RINGRING;
+            break;
         case "group_answer":
             type = CallEventType.GROUP_ANSWER;
             break;
+        case "group_answer_ack":
+            type = CallEventType.GROUP_ANSWER_ACK;
+            break;
+        case "group_cancel":
+            type = CallEventType.GROUP_CANCEL;
+            break;
+        case "group_end_call":
+        case "group_endcall":
+        case "group_end":
+            type = CallEventType.GROUP_END;
+            break;
+        case "group_add_user":
+            type = CallEventType.GROUP_ADD_USER;
+            break;
+        case "group_notify":
+            type = CallEventType.GROUP_NOTIFY;
+            break;
+        case "group_broadcast":
+            type = CallEventType.GROUP_BROADCAST;
+            break;
+        case "group_broadcast_config":
+            type = CallEventType.GROUP_BROADCAST_CONFIG;
+            break;
         default:
             type = CallEventType.UNKNOWN;
             break;
     }
+    const enrichedData = { ...data };
+    let parsedParams;
+    if (typeof enrichedData.params === "string") {
+        try {
+            const p = JSON.parse(enrichedData.params);
+            if (p && typeof p === "object")
+                parsedParams = p;
+        }
+        catch {
+            // Ignore invalid JSON
+        }
+    }
+    else if (enrichedData.params && typeof enrichedData.params === "object") {
+        parsedParams = enrichedData.params;
+    }
+    if (enrichedData.callId === undefined) {
+        const extractedCallId = Number(enrichedData.call_id ??
+            enrichedData.id ??
+            parsedParams?.callId ??
+            parsedParams?.call_id ??
+            parsedParams?.id ??
+            0);
+        if (extractedCallId > 0) {
+            enrichedData.callId = extractedCallId;
+        }
+    }
+    if (enrichedData.callerId === undefined) {
+        const extractedCallerId = enrichedData.uidN ??
+            parsedParams?.uidN ??
+            enrichedData.uidFrom ??
+            enrichedData.fromId ??
+            parsedParams?.uidFrom;
+        if (extractedCallerId !== undefined) {
+            enrichedData.callerId = String(extractedCallerId);
+        }
+    }
     return {
         type,
         act,
         act_type,
-        data,
+        data: enrichedData,
     };
 }

package/dist/realtime/handlers/control.handler.js

@@ -4,10 +4,15 @@ import { initializeGroupEvent } from "../../models/GroupEvent.js";
 import { initializeSyncEvent } from "../../models/SyncEvent.js";
 import { decodeEventData, getFriendEventType, getGroupEventType } from "../../utils.js";
 export async function handleRealtimeControlPacket(listener, ctx, selfListen, version, cmd, subCmd, parsed, cipherKey) {
-    if (version == 1 && cmd == 601 && subCmd == 0) {
-        const parsedData = (await decodeEventData(parsed, cipherKey)).data;
-        const { controls } = parsedData;
+    if (version == 1 && (cmd == 601 || cmd == 603 || cmd == 604) && subCmd == 0) {
+        const decoded = await decodeEventData(parsed, cipherKey);
+        const parsedData = decoded?.data;
+        const controls = parsedData?.controls;
+        if (!Array.isArray(controls))
+            return false;
         for (const control of controls) {
+            if (!control?.content)
+                continue;
             if (control.content.act_type == "file_done") {
                 const data = {
                     fileUrl: control.content.data.url,
@@ -58,6 +63,15 @@ export async function handleRealtimeControlPacket(listener, ctx, selfListen, ver
                 const callEventData = typeof control.content.data == "string"
                     ? JSON.parse(control.content.data)
                     : control.content.data;
+                // Bỏ qua các gói mời gọi cũ (> 60s) nằm trong hàng đợi offline (cmd 603 / 604)
+                if ((cmd == 603 || cmd == 604) &&
+                    (control.content.act == "request" || control.content.act == "group_request") &&
+                    callEventData?.ts) {
+                    const eventTs = Number.parseInt(String(callEventData.ts), 10);
+                    if (Number.isFinite(eventTs) && Date.now() - eventTs > 60_000) {
+                        continue;
+                    }
+                }
                 const callEvent = initializeCallEvent(callEventData, control.content.act, control.content.act_type);
                 listener.emit("call_event", callEvent);
             }

package/dist/realtime/listener.d.ts

@@ -66,5 +66,10 @@ export declare class Listener extends EventEmitter<ListenerEvents> {
      * @param lastMsgId Optional cursor message ID
      */
     requestOldReactions(threadType: ThreadType, lastMsgId?: string | null): void;
+    /**
+     * Kích hoạt và kéo hàng đợi sự kiện điều khiển / VoIP (`cmd 603` CTRL_PULL_CTRL và `cmd 604` CTRL_PULL_VOIP).
+     * Giúp nhận ngay các cuộc gọi đến đang đổ chuông ngay cả khi vừa mở kết nối WebSocket.
+     */
+    requestOfflineVoipControls(): void;
     private reset;
 }

package/dist/realtime/listener.js

@@ -253,6 +253,7 @@ export class Listener extends EventEmitter {
                 if (version == 1 && cmd == 1 && subCmd == 1 && hasOwn(parsed, "key")) {
                     this.cipherKey = parsed.key;
                     this.emit("cipher_key", this.cipherKey);
+                    this.requestOfflineVoipControls();
                     if (this.pingInterval)
                         clearInterval(this.pingInterval);
                     const ping = () => {
@@ -358,6 +359,24 @@ export class Listener extends EventEmitter {
         };
         this.sendWs(payload);
     }
+    /**
+     * Kích hoạt và kéo hàng đợi sự kiện điều khiển / VoIP (`cmd 603` CTRL_PULL_CTRL và `cmd 604` CTRL_PULL_VOIP).
+     * Giúp nhận ngay các cuộc gọi đến đang đổ chuông ngay cả khi vừa mở kết nối WebSocket.
+     */
+    requestOfflineVoipControls() {
+        this.sendWs({
+            version: 1,
+            cmd: 604,
+            subCmd: 0,
+            data: { first: true, lastId: 1, preIds: [] },
+        });
+        this.sendWs({
+            version: 1,
+            cmd: 603,
+            subCmd: 0,
+            data: { first: true, lastId: "1", preIds: [] },
+        });
+    }
     reset() {
         this.ws = null;
         this.cipherKey = undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@softtynet/zca-js",
-    "version": "2.3.4",
+    "version": "2.3.5",
     "description": "Zalo API client library for Node.js and Bun, maintained by Softtynet.",
     "main": "dist/cjs/index.cjs",
     "module": "dist/index.js",
@@ -29,6 +29,7 @@
         "typecheck": "tsc --noEmit && tsc -p test/tsconfig.json --noEmit && tsc -p examples/tsconfig.json --noEmit && tsc -p docs/tsconfig.json --noEmit",
         "test:verify": "npm run typecheck && npx --yes tsx test/verify_upgrades.ts",
         "test:live": "npx --yes tsx test/verify_live.ts",
+        "test:call-studio": "npm run build && npx --yes tsx test/call_studio_server.ts",
         "docs:gen": "node scripts/generateDocs.js",
         "docs:dev": "node scripts/generateDocs.js && vitepress dev docs",
         "docs:build": "node scripts/generateDocs.js && vitepress build docs",