@telnyx/react-voice-commons-sdk 0.1.0

package/src/callkit/callkit.ts

@@ -0,0 +1,322 @@
+import { Platform, NativeModules, NativeEventEmitter } from 'react-native';
+
+interface CallKitBridgeInterface {
+  startOutgoingCall(
+    callUUID: string,
+    handle: string,
+    displayName: string
+  ): Promise<{ success: boolean; callUUID: string }>;
+  reportIncomingCall(
+    callUUID: string,
+    handle: string,
+    displayName: string
+  ): Promise<{ success: boolean; callUUID: string }>;
+  answerCall(callUUID: string): Promise<{ success: boolean; callUUID: string }>;
+  endCall(callUUID: string): Promise<{ success: boolean; callUUID: string }>;
+  reportCallConnected(callUUID: string): Promise<{ success: boolean }>;
+  reportCallEnded(callUUID: string, reason: number): Promise<{ success: boolean }>;
+  updateCall(callUUID: string, displayName: string, handle: string): Promise<{ success: boolean }>;
+  getActiveCalls(): Promise<any[]>;
+}
+
+// Call end reasons
+export enum CallEndReason {
+  Failed = 1,
+  RemoteEnded = 2,
+  Unanswered = 3,
+  AnsweredElsewhere = 4,
+  DeclinedElsewhere = 5,
+}
+
+// CallKit event types
+export interface CallKitEvent {
+  callUUID: string;
+  [key: string]: any;
+}
+
+class CallKitManager {
+  private bridge: CallKitBridgeInterface | null = null;
+  private eventEmitter: NativeEventEmitter | null = null;
+  private listeners: Map<string, (event: CallKitEvent) => void> = new Map();
+
+  /**
+   * Normalize UUID to lowercase for consistent handling in React Native
+   * iOS CallKit provides UUIDs in uppercase, but we want to use lowercase throughout React Native
+   */
+  private normalizeUUID(uuid: string): string {
+    return uuid.toLowerCase();
+  }
+
+  /**
+   * Denormalize UUID back to uppercase for iOS CallKit bridge calls
+   * iOS CallKit expects UUIDs in uppercase format
+   */
+  private denormalizeUUID(uuid: string): string {
+    return uuid.toUpperCase();
+  }
+
+  /**
+   * Normalize event object by converting callUUID to lowercase
+   */
+  private normalizeEvent(event: CallKitEvent): CallKitEvent {
+    return {
+      ...event,
+      callUUID: this.normalizeUUID(event.callUUID),
+    };
+  }
+
+  constructor() {
+    if (Platform.OS === 'ios') {
+      const { CallKitBridge } = NativeModules;
+      if (CallKitBridge) {
+        this.bridge = CallKitBridge;
+        this.eventEmitter = new NativeEventEmitter(CallKitBridge);
+        this.setupEventListeners();
+      } else {
+        console.warn('CallKit: CallKitBridge not available');
+      }
+    }
+  }
+
+  private setupEventListeners() {
+    if (!this.eventEmitter) return;
+
+    // Listen for CallKit actions - normalize UUIDs to lowercase for React Native
+    this.eventEmitter.addListener('CallKitDidReceiveStartCallAction', (event) => {
+      const normalizedEvent = this.normalizeEvent(event);
+      console.log('CallKit: Received start call action', normalizedEvent);
+      this.notifyListeners('startCall', normalizedEvent);
+    });
+
+    this.eventEmitter.addListener('CallKitDidPerformAnswerCallAction', (event) => {
+      const normalizedEvent = this.normalizeEvent(event);
+      console.log('CallKit: Received answer call action', normalizedEvent);
+      this.notifyListeners('answerCall', normalizedEvent);
+    });
+
+    this.eventEmitter.addListener('CallKitDidPerformEndCallAction', (event) => {
+      const normalizedEvent = this.normalizeEvent(event);
+      console.log('CallKit: Received end call action', normalizedEvent);
+      this.notifyListeners('endCall', normalizedEvent);
+    });
+
+    this.eventEmitter.addListener('CallKitDidReceivePush', (event) => {
+      const normalizedEvent = this.normalizeEvent(event);
+      console.log('CallKit: Received push notification event', normalizedEvent);
+      this.notifyListeners('receivePush', normalizedEvent);
+    });
+  }
+
+  private notifyListeners(eventType: string, event: CallKitEvent) {
+    const listener = this.listeners.get(eventType);
+    if (listener) {
+      listener(event);
+    }
+  }
+
+  // Public API methods
+
+  public async startOutgoingCall(
+    callUUID: string,
+    handle: string,
+    displayName: string
+  ): Promise<boolean> {
+    if (!this.bridge || Platform.OS !== 'ios') {
+      console.warn('CallKit: Not available on this platform');
+      return false;
+    }
+
+    try {
+      // Convert to uppercase for iOS CallKit bridge
+      const uppercaseUUID = this.denormalizeUUID(callUUID);
+      console.log('CallKit: Starting outgoing call', {
+        callUUID: uppercaseUUID,
+        handle,
+        displayName,
+      });
+      const result = await this.bridge.startOutgoingCall(uppercaseUUID, handle, displayName);
+      console.log('CallKit: Outgoing call started successfully', result);
+      return result.success;
+    } catch (error) {
+      console.error('CallKit: Failed to start outgoing call', error);
+      return false;
+    }
+  }
+
+  public async reportIncomingCall(
+    callUUID: string,
+    handle: string,
+    displayName: string
+  ): Promise<boolean> {
+    if (!this.bridge || Platform.OS !== 'ios') {
+      console.warn('CallKit: Not available on this platform');
+      return false;
+    }
+
+    try {
+      // Convert to uppercase for iOS CallKit bridge
+      const uppercaseUUID = this.denormalizeUUID(callUUID);
+      console.log('CallKit: Reporting incoming call', {
+        callUUID: uppercaseUUID,
+        handle,
+        displayName,
+      });
+      const result = await this.bridge.reportIncomingCall(uppercaseUUID, handle, displayName);
+      console.log('CallKit: Incoming call reported successfully', result);
+      return result.success;
+    } catch (error) {
+      console.error('CallKit: Failed to report incoming call', error);
+      return false;
+    }
+  }
+
+  public async answerCall(callUUID: string): Promise<boolean> {
+    if (!this.bridge || Platform.OS !== 'ios') {
+      console.warn('CallKit: Not available on this platform');
+      return false;
+    }
+
+    try {
+      // Convert to uppercase for iOS CallKit bridge
+      const uppercaseUUID = this.denormalizeUUID(callUUID);
+      console.log('CallKit: Answering call', { callUUID: uppercaseUUID });
+      const result = await this.bridge.answerCall(uppercaseUUID);
+      console.log('CallKit: Call answered successfully', result);
+      return result.success;
+    } catch (error) {
+      console.error('CallKit: Failed to answer call', error);
+      return false;
+    }
+  }
+
+  public async endCall(callUUID: string): Promise<boolean> {
+    if (!this.bridge || Platform.OS !== 'ios') {
+      console.warn('CallKit: Not available on this platform');
+      return false;
+    }
+
+    try {
+      // Convert to uppercase for iOS CallKit bridge
+      const uppercaseUUID = this.denormalizeUUID(callUUID);
+      console.log('CallKit: Ending call', { callUUID: uppercaseUUID });
+      const result = await this.bridge.endCall(uppercaseUUID);
+      console.log('CallKit: Call ended successfully', result);
+      return result.success;
+    } catch (error) {
+      console.error('CallKit: Failed to end call', error);
+      return false;
+    }
+  }
+
+  public async reportCallConnected(callUUID: string): Promise<boolean> {
+    if (!this.bridge || Platform.OS !== 'ios') {
+      return false;
+    }
+
+    try {
+      // Convert to uppercase for iOS CallKit bridge
+      const uppercaseUUID = this.denormalizeUUID(callUUID);
+      console.log('CallKit: Reporting call connected', { callUUID: uppercaseUUID });
+      const result = await this.bridge.reportCallConnected(uppercaseUUID);
+      console.log('CallKit: Call connected reported successfully', result);
+      return result.success;
+    } catch (error) {
+      console.error('CallKit: Failed to report call connected', error);
+      return false;
+    }
+  }
+
+  public async reportCallEnded(
+    callUUID: string,
+    reason: CallEndReason = CallEndReason.RemoteEnded
+  ): Promise<boolean> {
+    if (!this.bridge || Platform.OS !== 'ios') {
+      return false;
+    }
+
+    try {
+      // Convert to uppercase for iOS CallKit bridge
+      const uppercaseUUID = this.denormalizeUUID(callUUID);
+      console.log('CallKit: Reporting call ended', { callUUID: uppercaseUUID, reason });
+      const result = await this.bridge.reportCallEnded(uppercaseUUID, reason);
+      console.log('CallKit: Call ended reported successfully', result);
+      return result.success;
+    } catch (error) {
+      console.error('CallKit: Failed to report call ended', error);
+      return false;
+    }
+  }
+
+  public async updateCall(callUUID: string, displayName: string, handle: string): Promise<boolean> {
+    if (!this.bridge || Platform.OS !== 'ios') {
+      return false;
+    }
+
+    try {
+      // Convert to uppercase for iOS CallKit bridge
+      const uppercaseUUID = this.denormalizeUUID(callUUID);
+      console.log('CallKit: Updating call', { callUUID: uppercaseUUID, displayName, handle });
+      const result = await this.bridge.updateCall(uppercaseUUID, displayName, handle);
+      console.log('CallKit: Call updated successfully', result);
+      return result.success;
+    } catch (error) {
+      console.error('CallKit: Failed to update call', error);
+      return false;
+    }
+  }
+
+  public async getActiveCalls(): Promise<any[]> {
+    if (!this.bridge || Platform.OS !== 'ios') {
+      return [];
+    }
+
+    try {
+      const calls = await this.bridge.getActiveCalls();
+      console.log('CallKit: Active calls retrieved', calls);
+      return calls;
+    } catch (error) {
+      console.error('CallKit: Failed to get active calls', error);
+      return [];
+    }
+  }
+
+  // Event listener management
+
+  public onStartCall(listener: (event: CallKitEvent) => void): () => void {
+    this.listeners.set('startCall', listener);
+    return () => this.listeners.delete('startCall');
+  }
+
+  public onAnswerCall(listener: (event: CallKitEvent) => void): () => void {
+    this.listeners.set('answerCall', listener);
+    return () => this.listeners.delete('answerCall');
+  }
+
+  public onEndCall(listener: (event: CallKitEvent) => void): () => void {
+    this.listeners.set('endCall', listener);
+    return () => this.listeners.delete('endCall');
+  }
+
+  public onReceivePush(listener: (event: CallKitEvent) => void): () => void {
+    this.listeners.set('receivePush', listener);
+    return () => this.listeners.delete('receivePush');
+  }
+
+  // Utility methods
+
+  public generateCallUUID(): string {
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function (c) {
+      const r = (Math.random() * 16) | 0;
+      const v = c === 'x' ? r : (r & 0x3) | 0x8;
+      return v.toString(16);
+    });
+  }
+
+  public isAvailable(): boolean {
+    return Platform.OS === 'ios' && this.bridge !== null;
+  }
+}
+
+// Export singleton instance
+export const CallKit = new CallKitManager();
+export default CallKit;

package/src/callkit/index.ts

@@ -0,0 +1,4 @@
+export { default as CallKit, CallEndReason, type CallKitEvent } from './callkit';
+export { default as callKitCoordinator } from './callkit-coordinator';
+export { useCallKit } from './use-callkit';
+export { useCallKitCoordinator } from '../hooks/use-callkit-coordinator';

package/src/callkit/use-callkit.ts

@@ -0,0 +1,345 @@
+import { useState, useEffect, useCallback, useRef } from 'react';
+import { Call } from '@telnyx/react-native-voice-sdk';
+import CallKit, { CallEndReason, CallKitEvent } from './callkit';
+
+interface UseCallKitOptions {
+  onAnswerCall?: (callUUID: string) => void;
+  onEndCall?: (callUUID: string) => void;
+  onStartCall?: (callUUID: string) => void;
+}
+
+interface CallKitCall {
+  uuid: string;
+  handle: string;
+  displayName: string;
+  isActive: boolean;
+  direction: 'incoming' | 'outgoing';
+}
+
+export function useCallKit(options: UseCallKitOptions = {}) {
+  const { onAnswerCall, onEndCall, onStartCall } = options;
+  const [activeCalls, setActiveCalls] = useState<CallKitCall[]>([]);
+  const [isAvailable, setIsAvailable] = useState(false);
+
+  // Use refs to store stable callback references and current state
+  const onAnswerCallRef = useRef(onAnswerCall);
+  const onEndCallRef = useRef(onEndCall);
+  const onStartCallRef = useRef(onStartCall);
+  const activeCallsRef = useRef(activeCalls);
+
+  // Update refs when callbacks change
+  useEffect(() => {
+    onAnswerCallRef.current = onAnswerCall;
+  }, [onAnswerCall]);
+
+  useEffect(() => {
+    onEndCallRef.current = onEndCall;
+  }, [onEndCall]);
+
+  useEffect(() => {
+    onStartCallRef.current = onStartCall;
+  }, [onStartCall]);
+
+  // Update active calls ref
+  useEffect(() => {
+    activeCallsRef.current = activeCalls;
+  }, [activeCalls]);
+
+  useEffect(() => {
+    setIsAvailable(CallKit.isAvailable());
+
+    if (!CallKit.isAvailable()) {
+      console.log('CallKit: Not available on this platform');
+      return;
+    }
+
+    // Load existing active calls only once
+    const loadActiveCalls = async () => {
+      const calls = await CallKit.getActiveCalls();
+      setActiveCalls(
+        calls.map((call) => ({
+          uuid: call.uuid,
+          handle: call.handle || call.caller || 'Unknown',
+          displayName: call.caller || call.displayName || 'Unknown Caller',
+          isActive: true,
+          direction: call.direction || 'incoming',
+        }))
+      );
+    };
+
+    loadActiveCalls();
+
+    // Set up event listeners using stable refs
+    const unsubscribeAnswer = CallKit.onAnswerCall((event: CallKitEvent) => {
+      console.log('useCallKit: Call answered via CallKit', event);
+      onAnswerCallRef.current?.(event.callUUID);
+    });
+
+    const unsubscribeEnd = CallKit.onEndCall((event: CallKitEvent) => {
+      console.log('useCallKit: Call ended via CallKit', event);
+      setActiveCalls((prev) => prev.filter((call) => call.uuid !== event.callUUID));
+      onEndCallRef.current?.(event.callUUID);
+    });
+
+    const unsubscribeStart = CallKit.onStartCall((event: CallKitEvent) => {
+      console.log('useCallKit: Call started via CallKit', event);
+      onStartCallRef.current?.(event.callUUID);
+    });
+
+    return () => {
+      unsubscribeAnswer();
+      unsubscribeEnd();
+      unsubscribeStart();
+    };
+  }, []); // Empty dependency array - only run once
+
+  // Start an outgoing call
+  const startOutgoingCall = useCallback(
+    async (call: Call, handle?: string, displayName?: string): Promise<string | null> => {
+      if (!CallKit.isAvailable()) {
+        console.warn('CallKit: Not available, cannot start outgoing call');
+        return null;
+      }
+
+      const callUUID = CallKit.generateCallUUID();
+      const callHandle = handle || (call as any).destinationNumber || 'Unknown';
+      const callDisplayName = displayName || callHandle;
+
+      console.log('useCallKit: Starting outgoing call', {
+        callUUID,
+        callHandle,
+        callDisplayName,
+        telnyxCallId: call.callId,
+      });
+
+      const success = await CallKit.startOutgoingCall(callUUID, callHandle, callDisplayName);
+
+      if (success) {
+        const newCall: CallKitCall = {
+          uuid: callUUID,
+          handle: callHandle,
+          displayName: callDisplayName,
+          isActive: false,
+          direction: 'outgoing',
+        };
+
+        setActiveCalls((prev) => [...prev, newCall]);
+
+        // Store mapping between CallKit UUID and Telnyx call for later reference
+        (call as any)._callKitUUID = callUUID;
+
+        return callUUID;
+      }
+
+      return null;
+    },
+    []
+  );
+
+  // Report an incoming call
+  const reportIncomingCall = useCallback(
+    async (call: Call, handle?: string, displayName?: string): Promise<string | null> => {
+      if (!CallKit.isAvailable()) {
+        console.warn('CallKit: Not available, cannot report incoming call');
+        return null;
+      }
+
+      const callUUID = CallKit.generateCallUUID();
+      const callHandle = handle || (call as any).destinationNumber || call.callId || 'Unknown';
+      const callDisplayName = displayName || callHandle;
+
+      console.log('useCallKit: Reporting incoming call', {
+        callUUID,
+        callHandle,
+        callDisplayName,
+        telnyxCallId: call.callId,
+      });
+
+      const success = await CallKit.reportIncomingCall(callUUID, callHandle, callDisplayName);
+
+      if (success) {
+        const newCall: CallKitCall = {
+          uuid: callUUID,
+          handle: callHandle,
+          displayName: callDisplayName,
+          isActive: false,
+          direction: 'incoming',
+        };
+
+        setActiveCalls((prev) => [...prev, newCall]);
+
+        // Store mapping between CallKit UUID and Telnyx call for later reference
+        (call as any)._callKitUUID = callUUID;
+
+        return callUUID;
+      }
+
+      return null;
+    },
+    []
+  );
+
+  // End a call
+  const endCall = useCallback(
+    async (
+      callUUID: string,
+      reason: CallEndReason = CallEndReason.RemoteEnded
+    ): Promise<boolean> => {
+      if (!CallKit.isAvailable()) {
+        return false;
+      }
+
+      console.log('useCallKit: Ending call', { callUUID, reason });
+
+      try {
+        // For incoming calls, we should use reportCallEnded (which dismisses the UI)
+        // For outgoing calls, we should use endCall (which sends the end request)
+
+        // Check if this is likely an incoming call by looking at our active calls
+        const activeCall = activeCallsRef.current.find((call) => call.uuid === callUUID);
+        const isIncomingCall = activeCall?.direction === 'incoming';
+
+        if (isIncomingCall) {
+          await CallKit.reportCallEnded(callUUID, reason);
+        } else {
+          await CallKit.endCall(callUUID);
+        }
+
+        // Update our local state
+        setActiveCalls((prev) => prev.filter((call) => call.uuid !== callUUID));
+        return true;
+      } catch (error) {
+        console.log('useCallKit: Error ending call (may already be ended):', error);
+
+        // Still remove from our local state even if CallKit operation failed
+        // This ensures our UI stays in sync
+        setActiveCalls((prev) => prev.filter((call) => call.uuid !== callUUID));
+
+        // Return true since the call is effectively ended from our perspective
+        return true;
+      }
+    },
+    []
+  );
+
+  // Report call connected
+  const reportCallConnected = useCallback(async (callUUID: string): Promise<boolean> => {
+    if (!CallKit.isAvailable()) {
+      return false;
+    }
+
+    console.log('useCallKit: Reporting call connected', { callUUID });
+
+    const success = await CallKit.reportCallConnected(callUUID);
+
+    if (success) {
+      // Update our local state to mark the call as active
+      setActiveCalls((prev) =>
+        prev.map((call) => (call.uuid === callUUID ? { ...call, isActive: true } : call))
+      );
+    }
+
+    return success;
+  }, []);
+
+  // Update call information
+  const updateCall = useCallback(
+    async (callUUID: string, displayName: string, handle: string): Promise<boolean> => {
+      if (!CallKit.isAvailable()) {
+        return false;
+      }
+
+      console.log('useCallKit: Updating call', { callUUID, displayName, handle });
+
+      const success = await CallKit.updateCall(callUUID, displayName, handle);
+
+      if (success) {
+        // Update our local state
+        setActiveCalls((prev) =>
+          prev.map((call) => (call.uuid === callUUID ? { ...call, displayName, handle } : call))
+        );
+      }
+
+      return success;
+    },
+    []
+  );
+
+  // Answer a call
+  const answerCall = useCallback(async (callUUID: string): Promise<boolean> => {
+    if (!CallKit.isAvailable()) {
+      return false;
+    }
+
+    console.log('useCallKit: Answering call', { callUUID });
+
+    const success = await CallKit.answerCall(callUUID);
+
+    if (success) {
+      // Update our local state to mark call as active
+      setActiveCalls((prev) =>
+        prev.map((call) => (call.uuid === callUUID ? { ...call, isActive: true } : call))
+      );
+    }
+
+    return success;
+  }, []);
+
+  // Get CallKit UUID for a Telnyx call
+  const getCallKitUUID = useCallback((call: Call): string | null => {
+    return (call as any)._callKitUUID || null;
+  }, []);
+
+  // Set up automatic CallKit integration for a Telnyx call
+  const integrateCall = useCallback(
+    async (call: Call, direction: 'incoming' | 'outgoing') => {
+      if (!CallKit.isAvailable()) {
+        return null;
+      }
+
+      let callUUID: string | null = null;
+
+      if (direction === 'incoming') {
+        callUUID = await reportIncomingCall(call);
+      } else {
+        callUUID = await startOutgoingCall(call);
+      }
+
+      if (callUUID) {
+        // Set up automatic state reporting
+        const handleStateChange = async (call: Call, state: string) => {
+          if (state === 'active') {
+            await reportCallConnected(callUUID!);
+          } else if (state === 'ended' || state === 'failed') {
+            const reason = state === 'failed' ? CallEndReason.Failed : CallEndReason.RemoteEnded;
+            await endCall(callUUID!, reason);
+          }
+        };
+
+        call.on('telnyx.call.state', handleStateChange);
+      }
+
+      return callUUID;
+    },
+    [reportIncomingCall, startOutgoingCall, reportCallConnected, endCall]
+  );
+
+  return {
+    // State
+    isAvailable,
+    activeCalls,
+
+    // Methods
+    startOutgoingCall,
+    reportIncomingCall,
+    answerCall,
+    endCall,
+    reportCallConnected,
+    updateCall,
+    getCallKitUUID,
+    integrateCall,
+
+    // Utility
+    generateCallUUID: CallKit.generateCallUUID,
+  };
+}

package/src/context/TelnyxVoiceContext.tsx

@@ -0,0 +1,33 @@
+import React, { createContext, useContext } from 'react';
+import { TelnyxVoipClient } from '../telnyx-voip-client';
+import { TelnyxConnectionState } from '../models/connection-state';
+
+interface TelnyxVoiceContextValue {
+  voipClient: TelnyxVoipClient;
+  // Add methods that CallKitHandler expects (these can be no-ops for now)
+  connectionState?: TelnyxConnectionState;
+  setConnectionState?: (state: TelnyxConnectionState) => void;
+  connect?: (payload: any) => Promise<any>;
+  client?: any;
+  setClient?: (client: any) => void;
+  enableAutoReconnect?: (enabled: boolean) => void;
+}
+
+const TelnyxVoiceContext = createContext<TelnyxVoiceContextValue | null>(null);
+
+export const TelnyxVoiceProvider: React.FC<{
+  voipClient: TelnyxVoipClient;
+  children: React.ReactNode;
+}> = ({ voipClient, children }) => {
+  return (
+    <TelnyxVoiceContext.Provider value={{ voipClient }}>{children}</TelnyxVoiceContext.Provider>
+  );
+};
+
+export const useTelnyxVoice = (): TelnyxVoiceContextValue => {
+  const context = useContext(TelnyxVoiceContext);
+  if (!context) {
+    throw new Error('useTelnyxVoice must be used within a TelnyxVoiceProvider');
+  }
+  return context;
+};