@zyratalk1/zyra-twilio-wrapper 1.2.0

package/README.md

@@ -0,0 +1,75 @@
+### React Native VOIP SDK
+
+React Native VOIP SDK architecture with:
+- JS public API layer
+- RN bridge layer
+- Twilio native Voice SDK adapter for Android and iOS
+- Core auth/call/conference/retry/config modules
+
+### Technical Design
+
+- `react-native-voip-sdk-design.md`
+- `react-native-voip-sdk-design.docx`
+- `react-native-voip-sdk-design.pdf`
+
+### Consumer Initialization
+
+Consumer app must provide `sdkToken`.  
+`accessToken` is optional at constructor time and can be supplied later in `authenticate`.
+
+```ts
+const sdk = new ZyraTwilioWrapper({
+  serverUrl: "https://your-backend.com",
+  identity: "user_123",
+  sdkToken: "YOUR_SDK_TOKEN",
+  // optional:
+  // accessToken: "TWILIO_ACCESS_TOKEN",
+});
+
+// Optional: provide access token during authenticate
+await sdk.authenticate({ accessToken: "TWILIO_ACCESS_TOKEN" });
+```
+
+### Android App Setup (Consumer App)
+
+Update `MainActivity.kt` with `VoiceActivityProxy` hooks:
+
+```kotlin
+private val activityProxy = VoiceActivityProxy(this) { permission -> /* optional UX */ }
+
+override fun onCreate(savedInstanceState: Bundle?) {
+    super.onCreate(savedInstanceState)
+    activityProxy.onCreate(savedInstanceState)
+}
+
+override fun onStart() { super.onStart(); activityProxy.onStart() }
+override fun onStop() { activityProxy.onStop(); super.onStop() }
+override fun onNewIntent(intent: Intent?) { super.onNewIntent(intent); activityProxy.onNewIntent(intent) }
+override fun onDestroy() { activityProxy.onDestroy(); super.onDestroy() }
+```
+
+Update `MainApplication.kt` with `VoiceApplicationProxy` hooks:
+
+```kotlin
+private val voiceApplicationProxy = VoiceApplicationProxy(this)
+
+override fun onCreate() {
+    super.onCreate()
+    voiceApplicationProxy.onCreate()
+}
+
+override fun onTerminate() {
+    voiceApplicationProxy.onTerminate()
+    super.onTerminate()
+}
+```
+
+### iOS App Setup (Consumer App)
+
+Enable the following Xcode capabilities for the app target:
+- Background Modes:
+  - Audio, AirPlay, and Picture in Picture
+  - Voice over IP
+- Push Notifications
+
+Use physical iOS devices for end-to-end call testing.

package/dist/index.d.mts

@@ -0,0 +1,407 @@
+interface Config {
+    serverUrl: string;
+    identity: string;
+    waitUrl?: string;
+    sdkToken: string;
+    accessToken?: string;
+    requestTimeoutMs?: number;
+    retry?: {
+        maxRetries?: number;
+        baseDelayMs?: number;
+        maxDelayMs?: number;
+        jitterRatio?: number;
+        circuitBreakerThreshold?: number;
+        circuitBreakerCooldownMs?: number;
+    };
+}
+interface TwilioConferenceParticipant {
+    accountSid: string;
+    callSid: string;
+    callSidToCoach: string | null;
+    coaching: boolean;
+    conferenceSid: string;
+    dateCreated: string;
+    dateUpdated: string;
+    endConferenceOnExit: boolean;
+    hold: boolean;
+    label: string | null;
+    muted: boolean;
+    queueTime: string | null;
+    startConferenceOnEnter: boolean;
+    status: 'queued' | 'ringing' | 'in-progress' | 'connected' | 'completed' | string;
+    uri: string;
+}
+interface TwilioConference {
+    conferenceSid: string;
+    conferences: TwilioConferenceDetails;
+}
+interface TwilioConferenceDetails {
+    accountSid: string;
+    apiVersion: string;
+    callSidEndingConference: string | null;
+    dateCreated: string;
+    dateUpdated: string;
+    friendlyName: string;
+    reasonConferenceEnded: string | null;
+    region: string;
+    sid: string;
+    status: 'init' | 'in-progress' | 'completed' | 'terminated' | string;
+    subresourceUris: {
+        participants: string;
+        recordings: string;
+        [key: string]: string;
+    };
+    uri: string;
+}
+interface WebhookConfigResult {
+    configured: boolean;
+    webhookUrl: string | null;
+}
+type CallResponse<T = void> = {
+    success: true;
+    message: string;
+    data: T;
+} | {
+    success: false;
+    error: Error;
+};
+/**
+ * Input types
+ */
+type WelcomeType = "audio" | "tts";
+/**
+ * Output type (matches backend output)
+ */
+interface WelcomeConfigResult {
+    success: boolean;
+    message: string;
+    welcomeType: WelcomeType;
+    routingConfigId: number;
+}
+/**
+ * Routing Config
+ */
+type RoutingStrategy = "RING_ALL" | "RING_SEQUENCE";
+type FallbackActionType = "TRANSFER" | "AI" | "VOICEMAIL";
+interface FallbackAction {
+    type: FallbackActionType;
+    target: {
+        phoneNumber: string;
+    } | null;
+}
+interface RoutingMember {
+    id: number;
+    priorityOrder: number;
+    isEnabled: boolean;
+    userType: "PHONE" | "DESKTOP";
+    identifier: string | null;
+    email: string | null;
+    phoneNumber: string | null;
+    ringDuration: number | null;
+}
+interface GetRoutingConfigResult {
+    strategy: RoutingStrategy;
+    defaultRingTimeout: number | null;
+    maxAttempts: number | null;
+    fallbackAction: FallbackAction;
+    members: RoutingMember[];
+}
+interface SetRoutingMember {
+    priorityOrder: number;
+    enabled: boolean;
+    userType: "PHONE" | "DESKTOP";
+    identifier: string;
+    ringDuration: number;
+    contact: {
+        email: string | null;
+        phoneNumber: string | null;
+    };
+}
+interface SetRoutingConfigInput {
+    strategy: {
+        type: RoutingStrategy;
+        defaultRingTimeout?: number;
+        maxAttempts?: number;
+    };
+    routingMembers: SetRoutingMember[];
+    fallbackAction: FallbackAction;
+}
+interface SetRoutingConfigResult {
+    success: boolean;
+    message: string;
+    strategy: RoutingStrategy;
+    memberCount: number;
+}
+interface CreateParseRuleEntry {
+    dataType: "rule" | "parseData";
+    fieldName: string;
+    parseOptions?: unknown;
+    parseOptionCode?: unknown;
+    fieldRules?: unknown;
+}
+interface ParseRuleRow {
+    id: number;
+    userId: number;
+    dataType: string | string[];
+    fieldName: string[];
+    fieldRules: string | null;
+    fieldRulesParsed: Record<string, any> | null;
+    parseOptions?: string | null;
+    parseOptionCode?: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface ListParseRulesInput {
+    page?: number;
+    limit?: number;
+    dataType?: "rule" | "parseData";
+    activeOnly?: boolean;
+}
+interface ListParseRulesResult {
+    data: ParseRuleRow[];
+    total: number;
+    page: number;
+    limit: number;
+}
+interface CreateParseRuleInput {
+    parseDataEntries: CreateParseRuleEntry[];
+}
+interface CreateParseRuleResult {
+    id: number;
+    userId: number;
+    dataType: string;
+    fieldName: string[];
+    fieldRules: string | null;
+    fieldRulesParsed?: Record<string, unknown> | null;
+    parseOptions?: string | null;
+    parseOptionCode?: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+
+type CallDirection = "INBOUND" | "OUTBOUND";
+type InboundCallState = "RINGING" | "ANSWERED" | "ON_HOLD" | "RESUMED" | "ENDED" | "FAILED";
+type OutboundCallState = "INITIATED" | "DIALING" | "RINGING" | "CONNECTED" | "MERGED" | "ENDED" | "FAILED";
+type CallState = InboundCallState | OutboundCallState;
+interface ConsumerAuth {
+    consumerId: string;
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt: number;
+    scopes: string[];
+}
+interface Participant {
+    id: string;
+    name?: string;
+    number?: string;
+    status: string;
+}
+interface CallSession {
+    callId: string;
+    direction: CallDirection;
+    status: CallState;
+    participants: Participant[];
+    conferenceRoomId: string | null;
+}
+interface RetryPolicyConfig {
+    maxRetries: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+    jitterRatio: number;
+    circuitBreakerThreshold: number;
+    circuitBreakerCooldownMs: number;
+}
+interface SDKConfig {
+    serverUrl: string;
+    consumerId: string;
+    sdkToken: string;
+    accessToken?: string;
+    identity?: string;
+    waitUrl?: string;
+    enableAndroidVoiceRegister?: boolean;
+    requestTimeoutMs?: number;
+    retry?: Partial<RetryPolicyConfig>;
+}
+interface AuthPayload {
+    accessToken?: string;
+    assertion?: string;
+    metadata?: Record<string, unknown>;
+}
+interface NativeCommandResult<T = Record<string, unknown>> {
+    success: boolean;
+    data?: T;
+    error?: string;
+}
+interface NativeModule {
+    initializeSDK(config: SDKConfig): Promise<NativeCommandResult>;
+    authenticate(payload?: AuthPayload): Promise<NativeCommandResult<ConsumerAuth>>;
+    refreshAuth?(): Promise<NativeCommandResult<ConsumerAuth>>;
+    startCall(input: {
+        number: string;
+        callId: string;
+    }): Promise<NativeCommandResult<CallSession>>;
+    answerCall(input: {
+        callId: string;
+    }): Promise<NativeCommandResult>;
+    rejectCall?(input: {
+        callId: string;
+    }): Promise<NativeCommandResult>;
+    endCall(input: {
+        callId: string;
+    }): Promise<NativeCommandResult>;
+    holdCall(input: {
+        callId: string;
+    }): Promise<NativeCommandResult>;
+    resumeCall(input: {
+        callId: string;
+    }): Promise<NativeCommandResult>;
+    mergeCall(input: {
+        callId: string;
+    }): Promise<NativeCommandResult<CallSession>>;
+    toggleMute?(input: {
+        callId: string;
+        mute: boolean;
+    }): Promise<NativeCommandResult>;
+    addNewCallee?(input: {
+        callId: string;
+        newParticipantNo: string;
+    }): Promise<NativeCommandResult>;
+    getConferenceId?(input: {
+        conferenceName: string;
+    }): Promise<NativeCommandResult<Record<string, unknown>>>;
+    getParticipants(input: {
+        callId: string;
+    }): Promise<NativeCommandResult<Participant[]>>;
+    getParticipantsByCallSid?(input: {
+        callSid: string;
+    }): Promise<NativeCommandResult<Participant[]>>;
+    disconnectParticipant(input: {
+        participantId: string;
+    }): Promise<NativeCommandResult>;
+    removeParticipant?(input: {
+        conferenceSid: string;
+        callSid: string;
+    }): Promise<NativeCommandResult>;
+    addListener?(eventName: string, callback: (payload: Record<string, unknown>) => void): {
+        remove: () => void;
+    };
+}
+type SDKEventName = "onReady" | "onCallRinging" | "onCallConnected" | "onParticipantJoined" | "onParticipantLeft" | "onCallEnded" | "onCallStateChanged" | "onAuthStateChanged" | "onMissedCall" | "onError";
+/**
+ * Options for {@link ReactNativeVoipSdk.makeCall}.
+ * - `parallel`: start a second Twilio `voice.connect` leg while another call is active (independent lifecycle).
+ * - Omitted / false: if a call is already active, add a conference participant via `addNewCallee` (existing behavior).
+ */
+interface MakeCallOptions {
+    parallel?: boolean;
+}
+
+type EventPayload = Record<string, unknown>;
+type Listener = (payload: EventPayload) => void;
+declare class BridgeEventEmitter {
+    private listeners;
+    on(eventName: SDKEventName | string, listener: Listener): () => void;
+    off(eventName: SDKEventName | string, listener: Listener): void;
+    emit(eventName: SDKEventName | string, payload: EventPayload): void;
+    removeAllListeners(): void;
+}
+
+declare class BridgeClient {
+    readonly events: BridgeEventEmitter;
+    readonly nativeModule: NativeModule;
+    private nativeSubscriptions;
+    constructor(nativeModule?: NativeModule);
+    on(eventName: SDKEventName | string, listener: (payload: Record<string, unknown>) => void): () => void;
+    emit(eventName: SDKEventName | string, payload: Record<string, unknown>): void;
+    destroy(): void;
+    private subscribeToNativeEvents;
+}
+
+declare class ReactNativeVoipSdk {
+    private readonly sdkConfig;
+    protected readonly bridge: BridgeClient;
+    private readonly retry;
+    private readonly authManager;
+    private readonly callEngine;
+    private readonly conferenceManager;
+    private readonly configService;
+    private initialized;
+    protected activeCallId: string | null;
+    /** Tracks every in-flight call leg (parallel or single); kept in sync with native `onCallEnded`. */
+    protected activeCallIds: Set<string>;
+    private unsubscribeOnCallEnded;
+    protected internalConferenceName: string;
+    constructor(config: Config, nativeModule?: NativeModule);
+    on(eventName: SDKEventName | string, listener: (payload: Record<string, unknown>) => void): () => void;
+    initializeSDK(config?: Partial<SDKConfig>): Promise<void>;
+    authenticate(payload?: AuthPayload): Promise<ConsumerAuth>;
+    startCall(number: string): Promise<CallSession>;
+    answerCall(callId: string): Promise<void>;
+    endCall(callId: string): Promise<void>;
+    holdCall(callId: string): Promise<void>;
+    resumeCall(callId: string): Promise<void>;
+    mergeCall(callId: string): Promise<CallSession>;
+    getParticipants(callId: string): Promise<Participant[]>;
+    disconnectParticipant(participantId: string): Promise<void>;
+    init(): Promise<void>;
+    verifySDKToken(): Promise<boolean>;
+    /**
+     * Start a call or add to a conference.
+     * Use `makeCall(to, { parallel: true })` (or `addCall(to)`) while a call is active to open a second
+     * independent leg; failures on that leg are isolated to its `callId` in `onError` / `onCallEnded`.
+     */
+    makeCall(to: string, options?: MakeCallOptions): Promise<CallResponse<CallSession>>;
+    /** Start a parallel outbound call while another call is active (alias for `makeCall(to, { parallel: true })`). */
+    addCall(to: string): Promise<CallResponse<CallSession>>;
+    /** All active call legs (parallel-aware). */
+    getActiveCallIds(): string[];
+    acceptCall(callId?: string): Promise<CallResponse<null>>;
+    rejectCall(callId: string): Promise<CallResponse<null>>;
+    hangup(callId?: string): Promise<CallResponse<null>>;
+    hold(callId: string): Promise<CallResponse<null>>;
+    resume(callId: string): Promise<CallResponse<null>>;
+    merge(callId: string): Promise<CallResponse<CallSession>>;
+    toggleMute(mute: boolean, callId?: string): Promise<CallResponse<null>>;
+    makeCallIncoming(to: string, callSid: string): Promise<CallResponse<CallSession>>;
+    holdAndAddParticipant(callSid: string, number: string): Promise<CallResponse<unknown>>;
+    holdAndAddParticipantIncoming(callSid: string, number: string): Promise<CallResponse<unknown>>;
+    getConferenceId(): Promise<CallResponse<unknown>>;
+    getParticipantsIncoming(callSid: string): Promise<CallResponse<unknown>>;
+    getParticipantsOutgoing(callSid: string): Promise<CallResponse<unknown>>;
+    removeParticipant(conferenceSid: string, callSid: string): Promise<CallResponse<unknown>>;
+    getRoutingConfig(): Promise<CallResponse<GetRoutingConfigResult>>;
+    setRoutingConfig(input: SetRoutingConfigInput): Promise<CallResponse<SetRoutingConfigResult>>;
+    createParseRule(input: CreateParseRuleInput): Promise<CallResponse<CreateParseRuleResult[]>>;
+    listParseRules(input?: ListParseRulesInput): Promise<CallResponse<ListParseRulesResult>>;
+    registerWebhook(webhookUrl: string): Promise<CallResponse<{
+        webhookUrl: string;
+    }>>;
+    deregisterWebhook(): Promise<CallResponse<null>>;
+    isWebhookConfigured(): Promise<CallResponse<WebhookConfigResult>>;
+    welcomeMessageConfig(welcomeType: "audio" | "tts", welcomeMessage: string): Promise<CallResponse<WelcomeConfigResult>>;
+    destroy(): void;
+    private pickNextActiveCallId;
+    private ensureAuthenticated;
+}
+
+/**
+ * Backward-compatible wrapper class retaining the original export name.
+ * Existing consumers can continue to construct `new ZyraTwilioWrapper(config)`.
+ */
+declare class ZyraTwilioWrapper extends ReactNativeVoipSdk {
+    activeCallSid: string | null;
+    conferenceName: string;
+    conferenceDetail: TwilioConference | null;
+    participants: TwilioConferenceParticipant[];
+    waitUrl: string;
+    onReady?: () => void;
+    onIncoming?: (payload: Record<string, unknown>) => void;
+    onDisconnect?: () => void;
+    onError?: (error: Error) => void;
+    onConnect?: (payload: Record<string, unknown>) => void;
+    onMissedCall?: () => void;
+    constructor(config: Config, nativeModule?: NativeModule);
+    destroy(): void;
+}
+
+export { type AuthPayload, type CallSession, type ConsumerAuth, type MakeCallOptions, type NativeModule, type Participant, ReactNativeVoipSdk, type SDKConfig, type SDKEventName, ZyraTwilioWrapper as default };