@softtynet/zca-js 2.3.3 → 2.3.5

package/dist/call-engine/ZRTPPacketCodec.d.ts

@@ -0,0 +1,262 @@
+import { Buffer } from "node:buffer";
+/**
+ * Các mã lệnh điều khiển UDP trong `zrtc::ZRTPPacket` (`_buildPacketInternal` @ `0x10015830c`)
+ */
+export declare enum ZRTPControlCommand {
+    RelayPing = 2,
+    EndCall = 3,
+    Ping = 5,
+    InitCallCaller = 11,
+    InitCallCallee = 12,
+    RequestForward = 32,
+    InitZaviPing = 51
+}
+/**
+ * Sub-command cho gói tin điều khiển `RequestForward` (`cmd = 32` / `0x0020`, `byte[20]`)
+ * dùng để Ping/Pong kiểm tra kết nối 2 chiều qua máy chủ Relay và điều khiển Audio/Video.
+ */
+export declare enum ZRTPForwardSubCommand {
+    OnMic = 5,
+    OffMic = 6,
+    OnCamera = 7,
+    OffCamera = 8,
+    OffCameraCallKit = 9,
+    VideoControl = 10,
+    Ping = 11,
+    Pong = 16,
+    PartnerSuspendVideo = 17
+}
+/**
+ * Loại gói tin Media qua máy chủ Relay:
+ * - Gửi đi (5-byte header `[type(1B)] + [routingToken(4B LE)] + [RTP/RTCP]`): `{3, 5, 7, 13, 15}`
+ * - Nhận về từ Relay (1-byte header `[type(1B)] + [RTP]`): `{4, 7, 14}`
+ * - Nhận về RTCP từ Relay (5-byte header `[type(1B)] + [routingToken(4B LE)] + [RTCP]`): `{5, 15}`
+ */
+export declare enum ZRTPLegacyMediaType {
+    AudioRtp = 3,
+    IncomingAudioRtp = 4,
+    AudioRtcp = 5,
+    AudioFec = 7,
+    VideoRtp = 13,
+    IncomingVideoRtp = 14,
+    VideoRtcp = 15
+}
+/**
+ * Sub-command cho gói tin ZRTC Multiplexed Media (`byte[0] == 0x7f`, 9-byte header)
+ */
+export declare enum ZRTCMediaSubCommand {
+    P2PPingRequest = 1,
+    P2PPingResponse = 2,
+    P2PInitCaller = 3,
+    P2PInitCallee = 4,
+    AudioRtp = 6,
+    AudioRtcp = 7,
+    VideoRtp = 8,
+    VideoRtcp = 9,
+    AudioFec = 10
+}
+export declare enum ZRTCRole {
+    Caller = 0,
+    Callee = 1
+}
+export type ZRTPInitCallRequestOptions = {
+    isCaller?: boolean;
+    seqNum?: number;
+    headerCallId?: number;
+    callId: number;
+    fromUid?: number;
+    toUid?: number;
+    flags?: number;
+    subFlags?: number;
+    sessId: string;
+    zrtcConfig?: string;
+};
+export type ZRTPInitCallResponseOptions = {
+    isCaller?: boolean;
+    seqNum?: number;
+    headerCallId?: number;
+    callId: number;
+    fromUid?: number;
+    toUid?: number;
+    flags?: number;
+    errorCode?: number;
+    routingToken: number;
+    sessId: string;
+};
+export type ZRTPPingRequestOptions = {
+    seqNum: number;
+    callId: number;
+    fromUid?: number;
+    toUid?: number;
+    elapsedMs: number | string;
+    minByteLength?: number;
+};
+export type ZRTPRelayPingRequestOptions = {
+    seqNum?: number;
+    callId?: number;
+    fromUid: number;
+    routingToken: number;
+    sessId: string;
+};
+export type ZRTPRequestForwardOptions = {
+    seqNum?: number;
+    seqId: number;
+    fromUid: number;
+    routingToken: number;
+    subCmd: ZRTPForwardSubCommand | number;
+    payload?: string | Buffer;
+};
+export type ZRTPEchoRequestOptions = {
+    seqNum: number;
+    callId: number;
+    fromUid?: number;
+    toUid?: number;
+    token: number;
+};
+export type ZRTPEndCallRequestOptions = {
+    seqNum?: number;
+    callId: number;
+    fromUid?: number;
+    toUid?: number;
+    routingToken?: number;
+    flags?: number;
+};
+export type ZRTPControlPacket = {
+    family: "control";
+    isResponse: boolean;
+    packetType: 1 | 2;
+    subType: number;
+    seqNum: number;
+    headerCallId: number;
+    fromUid: number;
+    toUid: number;
+    cmd: number;
+    flags: number;
+    callId?: number;
+    subFlags?: number;
+    errorCode?: number;
+    routingToken?: number;
+    sessId?: string;
+    zrtcConfig?: string;
+    pingString?: string;
+    forwardPayload?: Buffer;
+    echoToken?: number;
+    rawBody: Buffer;
+};
+export type ZRTPLegacyMediaPacket = {
+    family: "legacy_media";
+    mediaType: ZRTPLegacyMediaType;
+    isVideo: boolean;
+    isRtcp: boolean;
+    isFec: boolean;
+    routingId: number;
+    rtpPayload: Buffer;
+};
+export type ZRTCMultiplexedMediaPacket = {
+    family: "zrtc_media";
+    version: number;
+    role: ZRTCRole;
+    routingToken: number;
+    subCmd: ZRTCMediaSubCommand;
+    isVideo: boolean;
+    isRtcp: boolean;
+    isFec: boolean;
+    rtpPayload: Buffer;
+};
+export type ZRTCP2PPacket = {
+    family: "zrtc_p2p";
+    version: number;
+    role: ZRTCRole;
+    routingToken: number;
+    subCmd: number;
+    seqNum: number;
+    callId: number;
+    payload: Buffer;
+};
+export type ZRTPRawPacket = {
+    family: "raw";
+    raw: Buffer;
+};
+export type ParsedZRTPPacket = ZRTPControlPacket | ZRTPLegacyMediaPacket | ZRTCMultiplexedMediaPacket | ZRTCP2PPacket | ZRTPRawPacket;
+/**
+ * Chuỗi codec Opus chuẩn được `ZaloCall` tạo trong `sendSignal 416`
+ */
+export declare const DEFAULT_ZALO_AUDIO_CODEC: string;
+/**
+ * Chuỗi codec Audio + Video H264 chuẩn cho cuộc gọi Video
+ */
+export declare const DEFAULT_ZALO_VIDEO_CODEC: string;
+export type ZrtcExtendDataOptions = {
+    rtpAddress: string;
+    rtcpAddress: string;
+    isVideo?: boolean;
+    srtpMode?: number;
+    srtpKey?: string;
+    platform?: number;
+    packetMode?: number;
+};
+/**
+ * Tạo cấu trúc `extendData` chuẩn xác theo `ZaloCall` (`sendSignal 416` / `answer 402`).
+ */
+export declare function buildZrtcExtendData(options: ZrtcExtendDataOptions): Record<string, unknown>;
+/**
+ * Rút gọn UID 64-bit dạng chuỗi của Zalo về `uint32` dùng trong header `ZRTPPacket`
+ */
+export declare function uidToUint32(uid: string | number | undefined): number;
+/**
+ * Đóng gói gói tin UDP `InitCall` (`0x01 0x7e`, `cmd = 11` cho Caller hoặc `12` cho Callee)
+ * gửi tới máy chủ `rtpaddr` của Zalo (`zrtc::ZRTPPacket::_buildPacketInternal` @ `0x10015830c`).
+ */
+export declare function buildInitCallRequest(options: ZRTPInitCallRequestOptions): Buffer;
+/**
+ * Đóng gói gói tin UDP phản hồi `InitCall` (`0x02 0x7e`, `cmd = 11 | 12`)
+ * khớp chính xác với `zrtc::ZRTPPacket::_parsePacketInternal` (`0x100158db8`)
+ * và `zrtc::CallController` (`0x100177920`).
+ */
+export declare function buildInitCallResponse(options: ZRTPInitCallResponseOptions): Buffer;
+/**
+ * Đóng gói gói tin UDP `Ping` (`0x01 0x01`, `cmd = 5`) gửi định kỳ tới máy chủ relay của Zalo.
+ */
+export declare function buildPingRequest(options: ZRTPPingRequestOptions): Buffer;
+/**
+ * Đóng gói gói tin UDP phản hồi `Ping` (`0x02 0x01`, `cmd = 5`).
+ */
+export declare function buildPingResponse(options: ZRTPPingRequestOptions & {
+    errorCode?: number;
+}): Buffer;
+/**
+ * Đóng gói gói tin UDP `RequestPing` (`0x01 0x01`, `cmd = 2`) gửi tới máy chủ Relay Zalo
+ * (`zrtc::ZRTPPacket::initZRTPPacketRequestPing` @ `0x100157b88`).
+ */
+export declare function buildRelayPingRequest(options: ZRTPRelayPingRequestOptions): Buffer;
+/**
+ * Đóng gói gói tin UDP `RequestForward` (`0x01 0x01`, `cmd = 32` / `0x0020`)
+ * dùng cho Ping (`subCmd = 11`) / Pong (`subCmd = 16`) giữa 2 đầu qua máy chủ Relay
+ * (`zrtc::ZRTPPacket::initZRTPPacketRequestForward` @ `0x100157c4c`).
+ */
+export declare function buildRequestForwardPacket(options: ZRTPRequestForwardOptions): Buffer;
+/**
+ * Đóng gói gói tin UDP `Echo` (`cmd = 3`)
+ */
+export declare function buildEchoRequest(options: ZRTPEchoRequestOptions): Buffer;
+/**
+ * Đóng gói gói tin UDP `RequestEndCall` (`0x01 0x7e`, `cmd = 3`, 25 bytes)
+ * khớp với `zrtc::ZRTPPacket::initZRTPPacketRequestEndCall` (`0x100157b44`)
+ * và `_buildPacketInternal` (`0x10015830c`).
+ */
+export declare function buildEndCallRequest(options: ZRTPEndCallRequestOptions): Buffer;
+/**
+ * Bọc gói tin chuẩn WebRTC RTP/RTCP/SRTP vào khung 5-byte Legacy Media của Zalo
+ * (`byte[0]` in `{3, 5, 7, 13, 15}` + `routingId` 4B LE).
+ */
+export declare function wrapLegacyMediaPacket(mediaType: ZRTPLegacyMediaType, routingId: number, rtpOrRtcpPayload: Buffer): Buffer;
+/**
+ * Bọc gói tin chuẩn WebRTC RTP/RTCP/SRTP vào khung 9-byte ZRTC Multiplexed Media (`0x7f`)
+ * (`[0x7f, 0x00, role, routingToken(4B LE), subCmd(2B LE)] + [RTP/RTCP]`).
+ */
+export declare function wrapZrtcMediaPacket(subCmd: ZRTCMediaSubCommand, routingToken: number, rtpOrRtcpPayload: Buffer, role?: ZRTCRole): Buffer;
+/**
+ * Giải mã bất kỳ gói tin UDP `ZRTPPacket` nào nhận được từ máy chủ Relay Zalo hoặc Peer
+ * (`zrtc::ZRTPPacket::_parsePacketInternal` @ `0x1001589e8`).
+ */
+export declare function parseZRTPPacket(buf: Buffer): ParsedZRTPPacket;