@nice2dev/ui-communication 1.0.4 → 1.0.6

package/dist/services/pstnGatewayService.d.ts

@@ -0,0 +1,341 @@
+/**
+ * @file pstnGatewayService.ts
+ * @module @nice2dev/ui-communication
+ * @description PRO-20.2 — PSTN Dial-in Gateway Service
+ *
+ * Enables phone dial-in for video conferences:
+ * - Generate dial-in numbers
+ * - PIN/access code management
+ * - Participant bridging
+ * - Audio mixing with WebRTC
+ */
+/** Phone number region/country code */
+export type PhoneRegion = 'US' | 'CA' | 'UK' | 'DE' | 'FR' | 'PL' | 'ES' | 'IT' | 'AU' | 'JP' | 'IN' | 'BR' | 'MX';
+/** Dial-in phone number details */
+export interface DialInNumber {
+    /** Full E.164 phone number */
+    number: string;
+    /** Country/region code */
+    region: PhoneRegion;
+    /** Display number (formatted) */
+    displayNumber: string;
+    /** Is toll-free */
+    tollFree: boolean;
+    /** Number type */
+    type: 'local' | 'toll-free' | 'premium';
+    /** SIP URI for direct VoIP */
+    sipUri?: string;
+}
+/** Meeting dial-in info */
+export interface MeetingDialInInfo {
+    /** Unique meeting ID */
+    meetingId: string;
+    /** Available dial-in numbers */
+    dialInNumbers: DialInNumber[];
+    /** Access pin code */
+    accessPin: string;
+    /** Meeting passcode (optional extra security) */
+    passcode?: string;
+    /** Meeting title for IVR */
+    meetingTitle: string;
+    /** Host pin for host controls */
+    hostPin?: string;
+    /** Expires at timestamp */
+    expiresAt: number;
+}
+/** PSTN participant state */
+export type PstnParticipantState = 'connecting' | 'waiting-pin' | 'joined' | 'on-hold' | 'muted' | 'speaking' | 'disconnected';
+/** PSTN participant info */
+export interface PstnParticipant {
+    /** Unique call ID */
+    callId: string;
+    /** Caller phone number (if available) */
+    callerNumber?: string;
+    /** Caller ID name */
+    callerName?: string;
+    /** Current state */
+    state: PstnParticipantState;
+    /** Join timestamp */
+    joinedAt: number;
+    /** Audio stats */
+    audioStats: {
+        /** Current volume level (0-100) */
+        volume: number;
+        /** Is currently muted */
+        isMuted: boolean;
+        /** Packet loss percentage */
+        packetLoss: number;
+        /** Audio quality score (1-5) */
+        quality: number;
+    };
+    /** Is host caller */
+    isHost: boolean;
+    /** Is moderator */
+    isModerator: boolean;
+}
+/** Gateway configuration */
+export interface PstnGatewayConfig {
+    /** SIP trunk provider */
+    provider: 'twilio' | 'vonage' | 'plivo' | 'telnyx' | 'custom';
+    /** Account SID */
+    accountSid: string;
+    /** Auth token */
+    authToken: string;
+    /** SIP domain */
+    sipDomain: string;
+    /** Default region */
+    defaultRegion: PhoneRegion;
+    /** Enabled regions */
+    enabledRegions: PhoneRegion[];
+    /** Max participants per meeting */
+    maxParticipants: number;
+    /** Recording mode */
+    recordingMode: 'none' | 'audio-only' | 'full';
+    /** Custom IVR text */
+    ivrText?: {
+        welcome: string;
+        enterPin: string;
+        invalidPin: string;
+        joined: string;
+        muted: string;
+        unmuted: string;
+        onHold: string;
+        goodbye: string;
+    };
+}
+/** DTMF command mapping */
+export interface DtmfCommands {
+    /** Mute/unmute self */
+    toggleMute: string;
+    /** Raise/lower hand */
+    raiseHand: string;
+    /** Leave meeting */
+    leave: string;
+    /** Request help */
+    help: string;
+    /** Host: mute all */
+    hostMuteAll: string;
+    /** Host: unmute all */
+    hostUnmuteAll: string;
+    /** Host: end meeting */
+    hostEndMeeting: string;
+}
+/** Gateway events */
+export interface PstnGatewayEvents {
+    /** Participant joined */
+    onParticipantJoined: (participant: PstnParticipant) => void;
+    /** Participant left */
+    onParticipantLeft: (participant: PstnParticipant) => void;
+    /** Participant state changed */
+    onParticipantStateChanged: (participant: PstnParticipant, oldState: PstnParticipantState) => void;
+    /** DTMF received */
+    onDtmfReceived: (participant: PstnParticipant, digit: string) => void;
+    /** Error occurred */
+    onError: (error: PstnGatewayError) => void;
+    /** Connection status changed */
+    onStatusChanged: (status: 'connected' | 'disconnected' | 'reconnecting') => void;
+}
+/** Gateway error */
+export interface PstnGatewayError {
+    code: string;
+    message: string;
+    participant?: PstnParticipant;
+    timestamp: number;
+}
+/** Default DTMF commands */
+export declare const DEFAULT_DTMF_COMMANDS: DtmfCommands;
+/** Default IVR messages */
+export declare const DEFAULT_IVR_TEXT: {
+    welcome: string;
+    enterPin: string;
+    invalidPin: string;
+    joined: string;
+    muted: string;
+    unmuted: string;
+    onHold: string;
+    goodbye: string;
+};
+/** Region phone codes */
+export declare const REGION_CODES: Record<PhoneRegion, string>;
+/**
+ * PSTN Dial-in Gateway Service for video conferences.
+ *
+ * Manages phone dial-in participants, audio bridging, and IVR interactions.
+ */
+export declare class PstnGatewayService {
+    private config;
+    private eventHandlers;
+    private participants;
+    private meetingDialIns;
+    private dtmfCommands;
+    private connectionStatus;
+    private ivrText;
+    constructor(config?: Partial<PstnGatewayConfig>);
+    /**
+     * Set event handler.
+     */
+    on<K extends keyof PstnGatewayEvents>(event: K, handler: PstnGatewayEvents[K]): void;
+    /**
+     * Remove event handler.
+     */
+    off<K extends keyof PstnGatewayEvents>(event: K): void;
+    private emit;
+    /**
+     * Generate dial-in info for a meeting.
+     */
+    generateDialInInfo(meetingId: string, meetingTitle: string): MeetingDialInInfo;
+    /**
+     * Get dial-in info for a meeting.
+     */
+    getDialInInfo(meetingId: string): MeetingDialInInfo | undefined;
+    /**
+     * Get available dial-in numbers for enabled regions.
+     */
+    getAvailableNumbers(): DialInNumber[];
+    private generatePhoneNumber;
+    private formatPhoneNumber;
+    private generateAccessPin;
+    /**
+     * Handle incoming call.
+     */
+    handleIncomingCall(callId: string, callerNumber?: string, callerName?: string): Promise<PstnParticipant>;
+    /**
+     * Validate PIN and join meeting.
+     */
+    validatePinAndJoin(callId: string, meetingId: string, pin: string): Promise<{
+        success: boolean;
+        isHost: boolean;
+    }>;
+    /**
+     * Get participant by call ID.
+     */
+    getParticipant(callId: string): PstnParticipant | undefined;
+    /**
+     * Get all participants for a meeting.
+     */
+    getParticipants(): PstnParticipant[];
+    /**
+     * Update participant state.
+     */
+    private updateParticipantState;
+    /**
+     * Mute a participant.
+     */
+    muteParticipant(callId: string): Promise<void>;
+    /**
+     * Unmute a participant.
+     */
+    unmuteParticipant(callId: string): Promise<void>;
+    /**
+     * Toggle mute for a participant.
+     */
+    toggleMute(callId: string): Promise<boolean>;
+    /**
+     * Put participant on hold.
+     */
+    putOnHold(callId: string): Promise<void>;
+    /**
+     * Remove participant from hold.
+     */
+    removeFromHold(callId: string): Promise<void>;
+    /**
+     * Mute all participants (host control).
+     */
+    muteAll(excludeHosts?: boolean): Promise<void>;
+    /**
+     * Unmute all participants (host control).
+     */
+    unmuteAll(): Promise<void>;
+    /**
+     * Handle DTMF input from participant.
+     */
+    handleDtmf(callId: string, digits: string): Promise<void>;
+    /**
+     * Configure DTMF commands.
+     */
+    setDtmfCommands(commands: Partial<DtmfCommands>): void;
+    /**
+     * Play IVR message to participant.
+     */
+    playIvr(callId: string, messageKey: keyof typeof DEFAULT_IVR_TEXT): Promise<void>;
+    /**
+     * Play custom TTS message.
+     */
+    playCustomMessage(callId: string, text: string): Promise<void>;
+    /**
+     * Play help instructions.
+     */
+    playHelp(callId: string): Promise<void>;
+    /**
+     * Disconnect a participant.
+     */
+    disconnectParticipant(callId: string): Promise<void>;
+    /**
+     * End meeting for all PSTN participants.
+     */
+    endMeeting(): Promise<void>;
+    /**
+     * Get connection status.
+     */
+    getStatus(): 'connected' | 'disconnected' | 'reconnecting';
+    /**
+     * Connect to PSTN gateway.
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from PSTN gateway.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Get audio mixer configuration for WebRTC bridge.
+     */
+    getAudioBridgeConfig(): {
+        sampleRate: number;
+        channels: number;
+        codec: string;
+        bitrate: number;
+    };
+    /**
+     * Get SDP offer for audio bridging.
+     */
+    getSdpOffer(): string;
+    /**
+     * Process SDP answer from WebRTC peer.
+     */
+    processSdpAnswer(sdp: string): void;
+}
+/**
+ * Get the default PSTN gateway instance.
+ */
+export declare function getPstnGateway(config?: Partial<PstnGatewayConfig>): PstnGatewayService;
+/**
+ * Create a new PSTN gateway instance.
+ */
+export declare function createPstnGateway(config: Partial<PstnGatewayConfig>): PstnGatewayService;
+export interface UsePstnGatewayReturn {
+    /** Gateway connection status */
+    status: 'connected' | 'disconnected' | 'reconnecting';
+    /** List of PSTN participants */
+    participants: PstnParticipant[];
+    /** Generate dial-in info for a meeting */
+    generateDialIn: (meetingId: string, title: string) => MeetingDialInInfo;
+    /** Get dial-in info */
+    getDialIn: (meetingId: string) => MeetingDialInInfo | undefined;
+    /** Mute a participant */
+    mute: (callId: string) => Promise<void>;
+    /** Unmute a participant */
+    unmute: (callId: string) => Promise<void>;
+    /** Disconnect a participant */
+    disconnect: (callId: string) => Promise<void>;
+    /** Mute all participants */
+    muteAll: () => Promise<void>;
+    /** End meeting for all PSTN participants */
+    endMeeting: () => Promise<void>;
+    /** Connect to gateway */
+    connect: () => Promise<void>;
+}
+/**
+ * React hook for PSTN gateway management.
+ */
+export declare function usePstnGateway(config?: Partial<PstnGatewayConfig>): UsePstnGatewayReturn;
+export default PstnGatewayService;