@telnyx/react-voice-commons-sdk 0.4.3 → 1.1.0

package/lib/internal/session/session-manager.js

@@ -59,6 +59,9 @@ const TelnyxSDK = __importStar(require('@telnyx/react-native-voice-sdk'));
 const pkg = __importStar(require('../../../package.json'));
 const connection_state_1 = require('../../models/connection-state');
 const config_1 = require('../../models/config');
+const USE_TRICKLE_ICE_STORAGE_KEY = '@use_trickle_ice';
+const PUSH_WHEN_ACTIVE_STORAGE_KEY = '@push_when_active';
+const MISSED_CALL_NOTIFICATIONS_STORAGE_KEY = '@enable_missed_call_notifications';
 /**
  * Manages the connection lifecycle to the Telnyx platform.
  *
@@ -71,6 +74,8 @@ class SessionManager {
       connection_state_1.TelnyxConnectionState.DISCONNECTED
     );
     this._disposed = false;
+    this._disposing = false;
+    this._connectionGeneration = 0;
     this._sessionId = this._generateSessionId();
   }
   /**
@@ -110,25 +115,26 @@ class SessionManager {
   get telnyxClient() {
     return this._telnyxClient;
   }
+  get useTrickleIce() {
+    return Boolean(this._currentConfig?.useTrickleIce);
+  }
   /**
    * Connect using credential authentication
    */
   async connectWithCredential(config) {
-    if (this._disposed) {
-      throw new Error('SessionManager has been disposed');
-    }
+    this._assertCanStartConnection();
     this._currentConfig = config;
     await this._connect();
+    this._assertCanStartConnection();
   }
   /**
    * Connect using token authentication
    */
   async connectWithToken(config) {
-    if (this._disposed) {
-      throw new Error('SessionManager has been disposed');
-    }
+    this._assertCanStartConnection();
     this._currentConfig = config;
     await this._connect();
+    this._assertCanStartConnection();
   }
   /**
    * Disconnect from the Telnyx platform.
@@ -144,6 +150,7 @@ class SessionManager {
     if (this._disposed) {
       return;
     }
+    this._connectionGeneration += 1;
     this._currentConfig = undefined;
     this._connectionState.next(connection_state_1.TelnyxConnectionState.DISCONNECTED);
     if (this._onDisconnect) {
@@ -154,11 +161,7 @@ class SessionManager {
       }
     }
     if (this._telnyxClient) {
-      try {
-        await this._telnyxClient.disconnect();
-      } catch (error) {
-        console.error('Error during disconnect:', error);
-      }
+      await this._disconnectAndForgetClient(this._telnyxClient, 'Error during disconnect:');
     }
   }
   /**
@@ -168,6 +171,7 @@ class SessionManager {
    */
   disablePushNotifications() {
     if (
+      !this._isTeardownActive() &&
       this._telnyxClient &&
       this.currentState === connection_state_1.TelnyxConnectionState.CONNECTED
     ) {
@@ -181,7 +185,7 @@ class SessionManager {
    * Handle push notification with stored config
    */
   handlePushNotificationWithConfig(pushMetaData, config) {
-    if (this._disposed) {
+    if (this._isTeardownActive()) {
       return;
     }
     this._currentConfig = config;
@@ -193,7 +197,7 @@ class SessionManager {
    * Handle push notification (async version)
    */
   async handlePushNotification(payload) {
-    if (this._disposed) {
+    if (this._isTeardownActive()) {
       return;
     }
     console.log(
@@ -202,19 +206,33 @@ class SessionManager {
     );
     // Store the push notification payload for when the client is created
     this._pendingPushPayload = payload;
-    // Each push always rebuilds the TelnyxRTC client. The voice_sdk_id is
-    // baked into the WebSocket URL at socket-open time and can't be mutated
-    // mid-flight; reusing a connection from a previous push means the
-    // gateway routes THIS push's INVITE to a different (correctly-stamped)
-    // client and we sit on the wrong socket forever.
-    if (this._telnyxClient) {
-      try {
-        await this._telnyxClient.disconnect();
-      } catch (err) {
-        console.warn('SessionManager: disconnect of prior client threw:', err);
+    // A second-call push must stay on the client that owns the active/held
+    // call. Tearing it down destroys the first signaling session and clears
+    // the call collection before CallKit can complete Hold & Accept.
+    if (this._telnyxClient && this._hasActiveOrHeldCall(this._telnyxClient)) {
+      const actualPayload = this._extractPushPayload(payload);
+      const processVoIPNotification = this._telnyxClient.processVoIPNotification;
+      if (typeof processVoIPNotification !== 'function') {
+        throw new Error('TelnyxRTC client cannot process an active-call VoIP notification');
       }
+      console.log(
+        'SessionManager: Preserving active client while processing second-call push notification'
+      );
+      processVoIPNotification.call(this._telnyxClient, actualPayload);
+      this._pendingPushPayload = null;
+      return;
+    }
+    // The cold/no-active-call path still rebuilds the client so the socket is
+    // stamped with the push voice_sdk_id before connecting.
+    if (this._telnyxClient) {
+      await this._disconnectAndForgetClient(
+        this._telnyxClient,
+        'SessionManager: disconnect of prior client threw:'
+      );
+    }
+    if (this._isTeardownActive()) {
+      return;
     }
-    this._telnyxClient = undefined;
     if (this.currentState !== connection_state_1.TelnyxConnectionState.DISCONNECTED) {
       this._connectionState.next(connection_state_1.TelnyxConnectionState.DISCONNECTED);
     }
@@ -231,12 +249,26 @@ class SessionManager {
         const storedPassword = await AsyncStorage.getItem('@telnyx_password');
         const storedCredentialToken = await AsyncStorage.getItem('@credential_token');
         const storedPushToken = await AsyncStorage.getItem('@push_token');
+        const storedUseTrickleIce = await AsyncStorage.getItem(USE_TRICKLE_ICE_STORAGE_KEY);
+        const storedPushWhenActive = await AsyncStorage.getItem(PUSH_WHEN_ACTIVE_STORAGE_KEY);
+        const storedMissedCallNotifications = await AsyncStorage.getItem(
+          MISSED_CALL_NOTIFICATIONS_STORAGE_KEY
+        );
+        const useTrickleIce = storedUseTrickleIce === 'true';
+        const pushWhenActive = storedPushWhenActive === 'true';
+        const enableMissedCallNotifications = storedMissedCallNotifications === 'true';
+        if (this._isTeardownActive()) {
+          return;
+        }
         // Check if we have credential-based authentication data
         if (storedUsername && storedPassword) {
           console.log('SessionManager: RELEASE DEBUG - Found stored credentials, creating config');
           const { createCredentialConfig } = require('../../models/config');
           this._currentConfig = createCredentialConfig(storedUsername, storedPassword, {
             pushNotificationDeviceToken: storedPushToken,
+            useTrickleIce,
+            pushWhenActive,
+            enableMissedCallNotifications,
           });
         }
         // Check if we have token-based authentication data
@@ -245,6 +277,9 @@ class SessionManager {
           const { createTokenConfig } = require('../../models/config');
           this._currentConfig = createTokenConfig(storedCredentialToken, {
             pushNotificationDeviceToken: storedPushToken,
+            useTrickleIce,
+            pushWhenActive,
+            enableMissedCallNotifications,
           });
         }
         if (this._currentConfig) {
@@ -258,6 +293,9 @@ class SessionManager {
         console.warn('SessionManager: Failed to load stored config for push notification:', error);
       }
     }
+    if (this._isTeardownActive()) {
+      return;
+    }
     // If we already have a client, process the push notification immediately
     if (this._telnyxClient) {
       console.log(
@@ -302,10 +340,16 @@ class SessionManager {
         );
         try {
           await this._connect();
+          if (this._isTeardownActive()) {
+            return;
+          }
           console.log(
             'SessionManager: RELEASE DEBUG - Successfully connected after push notification trigger'
           );
         } catch (error) {
+          if (this._isTeardownActive()) {
+            return;
+          }
           console.error(
             'SessionManager: Failed to connect after push notification trigger:',
             error
@@ -325,73 +369,138 @@ class SessionManager {
     }
     console.log('SessionManager: RELEASE DEBUG - Push notification handling complete');
   }
+  _hasActiveOrHeldCall(client) {
+    const calls =
+      typeof client.getActiveCalls === 'function'
+        ? client.getActiveCalls()
+        : Array.from(client.calls?.values?.() || []);
+    return calls.some((call) => call?.state === 'active' || call?.state === 'held');
+  }
   /**
    * Dispose of the session manager and clean up resources
    */
-  dispose() {
+  async dispose() {
     if (this._disposed) {
       return;
     }
-    this._disposed = true;
-    this.disconnect();
-    this._connectionState.complete();
+    if (!this._disposePromise) {
+      this._disposePromise = this._dispose();
+    }
+    await this._disposePromise;
   }
   /**
    * Internal method to establish connection with or without push notification handling
    */
   async _connect() {
-    if (!this._currentConfig) {
+    const previousConnect = this._connectPromise;
+    if (previousConnect) {
+      try {
+        await previousConnect;
+      } catch (error) {
+        if (this._isTeardownActive()) {
+          throw error;
+        }
+      }
+    }
+    this._assertCanStartConnection();
+    const config = this._currentConfig;
+    if (!config) {
       throw new Error('No configuration provided');
     }
+    const connectionGeneration = (this._connectionGeneration += 1);
+    const connectPromise = this._runConnect(config, connectionGeneration);
+    this._connectPromise = connectPromise;
+    try {
+      await connectPromise;
+    } finally {
+      if (this._connectPromise === connectPromise) {
+        this._connectPromise = undefined;
+      }
+    }
+  }
+  async _dispose() {
+    this._disposing = true;
+    this._connectionGeneration += 1;
+    const inFlightConnect = this._connectPromise;
+    await this.disconnect();
+    if (inFlightConnect) {
+      try {
+        await inFlightConnect;
+      } catch {
+        // A connect canceled by disposal is expected; the cleanup path runs in _runConnect.
+      }
+    }
+    const client = this._telnyxClient;
+    if (client) {
+      await this._disconnectAndForgetClient(client, 'Error during dispose disconnect:');
+    }
+    this._currentConfig = undefined;
+    this._pendingPushPayload = null;
+    this._disposed = true;
+    this._disposing = false;
+    this._connectionState.complete();
+  }
+  async _runConnect(config, connectionGeneration) {
+    this._throwIfConnectCanceled(connectionGeneration);
     this._connectionState.next(connection_state_1.TelnyxConnectionState.CONNECTING);
+    let client;
+    let canceledConnectCleanupCompleted = false;
     try {
       // Clean up existing client
       if (this._telnyxClient) {
-        await this._telnyxClient.disconnect();
+        await this._disconnectClient(this._telnyxClient, 'Error during disconnect:');
       }
+      this._throwIfConnectCanceled(connectionGeneration);
       // Create new client instance with authentication options
       let clientOptions;
-      if ((0, config_1.isCredentialConfig)(this._currentConfig)) {
+      if ((0, config_1.isCredentialConfig)(config)) {
         clientOptions = {
-          login: this._currentConfig.sipUser,
-          password: this._currentConfig.sipPassword,
-          logLevel: this._currentConfig.debug ? 'debug' : 'warn',
-          debug: this._currentConfig.debug ?? false,
-          pushNotificationDeviceToken: this._currentConfig.pushNotificationDeviceToken,
-          enableCallReports: this._currentConfig.enableCallReports,
-          callReportInterval: this._currentConfig.callReportInterval,
-          callReportLogLevel: this._currentConfig.callReportLogLevel,
-          callReportMaxLogEntries: this._currentConfig.callReportMaxLogEntries,
+          login: config.sipUser,
+          password: config.sipPassword,
+          logLevel: config.debug ? 'debug' : 'warn',
+          debug: config.debug ?? false,
+          pushNotificationDeviceToken: config.pushNotificationDeviceToken,
+          pushWhenActive: config.pushWhenActive,
+          enableMissedCallNotifications: config.enableMissedCallNotifications ?? false,
+          useTrickleIce: config.useTrickleIce,
+          enableCallReports: config.enableCallReports,
+          callReportInterval: config.callReportInterval,
+          callReportLogLevel: config.callReportLogLevel,
+          callReportMaxLogEntries: config.callReportMaxLogEntries,
           sdkVersion: pkg.version,
         };
         console.log(
           '🔧 SessionManager: Creating TelnyxRTC with credential config, logLevel:',
           clientOptions.logLevel,
           'pushToken:',
-          !!this._currentConfig.pushNotificationDeviceToken
+          !!config.pushNotificationDeviceToken
         );
-      } else if ((0, config_1.isTokenConfig)(this._currentConfig)) {
+      } else if ((0, config_1.isTokenConfig)(config)) {
         clientOptions = {
-          login_token: this._currentConfig.token,
-          logLevel: this._currentConfig.debug ? 'debug' : 'warn',
-          debug: this._currentConfig.debug ?? false,
-          pushNotificationDeviceToken: this._currentConfig.pushNotificationDeviceToken,
-          enableCallReports: this._currentConfig.enableCallReports,
-          callReportInterval: this._currentConfig.callReportInterval,
-          callReportLogLevel: this._currentConfig.callReportLogLevel,
-          callReportMaxLogEntries: this._currentConfig.callReportMaxLogEntries,
+          login_token: config.token,
+          logLevel: config.debug ? 'debug' : 'warn',
+          debug: config.debug ?? false,
+          pushNotificationDeviceToken: config.pushNotificationDeviceToken,
+          pushWhenActive: config.pushWhenActive,
+          enableMissedCallNotifications: config.enableMissedCallNotifications ?? false,
+          useTrickleIce: config.useTrickleIce,
+          enableCallReports: config.enableCallReports,
+          callReportInterval: config.callReportInterval,
+          callReportLogLevel: config.callReportLogLevel,
+          callReportMaxLogEntries: config.callReportMaxLogEntries,
           sdkVersion: pkg.version,
         };
         console.log(
           '🔧 SessionManager: Creating TelnyxRTC with token config, logLevel:',
           clientOptions.logLevel,
           'pushToken:',
-          !!this._currentConfig.pushNotificationDeviceToken
+          !!config.pushNotificationDeviceToken
         );
       } else {
         throw new Error('Invalid configuration type');
       }
-      this._telnyxClient = new TelnyxSDK.TelnyxRTC(clientOptions);
+      client = new TelnyxSDK.TelnyxRTC(clientOptions);
+      this._telnyxClient = client;
       // CRITICAL: Process any pending push notification payload BEFORE connecting
       // This ensures voice_sdk_id and other payload variables are set before connect() is called
       const pendingPushPayload = this._pendingPushPayload;
@@ -418,7 +527,7 @@ class SessionManager {
         // Clear the pending payload
         this._pendingPushPayload = null;
       }
-      this._setupClientListeners();
+      this._setupClientListeners(client);
       // Set up CallStateController listeners immediately after client creation
       // This ensures they're ready before any incoming call events are emitted
       console.log(
@@ -432,15 +541,34 @@ class SessionManager {
       } else {
         console.log('🔧 SessionManager: No _onClientReady callback found');
       }
+      this._throwIfConnectCanceled(connectionGeneration);
       // Connect to the platform AFTER processing push notification
       console.log(
         'SessionManager: RELEASE DEBUG - About to call connect() after processing push notification'
       );
-      await this._telnyxClient.connect();
+      await client.connect();
+      if (this._isConnectCanceled(connectionGeneration)) {
+        await this._disconnectAndForgetClient(client, 'Error during dispose disconnect:');
+        canceledConnectCleanupCompleted = true;
+        throw this._createConnectCanceledError();
+      }
       // Notify that client is ready for event listeners
       console.log('🔧 SessionManager: Client connected successfully');
     } catch (error) {
+      if (this._isConnectCanceled(connectionGeneration)) {
+        if (client && !canceledConnectCleanupCompleted) {
+          await this._disconnectAndForgetClient(client, 'Error during dispose disconnect:');
+        }
+        throw this._createConnectCanceledError();
+      }
       console.error('Connection failed:', error);
+      if (client) {
+        try {
+          await this._disconnectAndForgetClient(client, 'Error during failed connect cleanup:');
+        } catch (cleanupError) {
+          console.error('Error during failed connect cleanup:', cleanupError);
+        }
+      }
       this._connectionState.next(connection_state_1.TelnyxConnectionState.ERROR);
       throw error;
     }
@@ -448,11 +576,14 @@ class SessionManager {
   /**
    * Set up event listeners for the Telnyx client
    */
-  _setupClientListeners() {
-    if (!this._telnyxClient) {
+  _setupClientListeners(client) {
+    if (!client) {
       return;
     }
-    this._telnyxClient.on('telnyx.client.ready', () => {
+    client.on('telnyx.client.ready', () => {
+      if (this._isTeardownActive() || this._telnyxClient !== client) {
+        return;
+      }
       console.log('Telnyx client ready');
       this._connectionState.next(connection_state_1.TelnyxConnectionState.CONNECTED);
       // Ensure CallStateController listeners are set up when client becomes ready
@@ -470,7 +601,10 @@ class SessionManager {
         console.log('🔧 SessionManager: No _onClientReady callback found in client ready event');
       }
     });
-    this._telnyxClient.on('telnyx.client.error', (error) => {
+    client.on('telnyx.client.error', (error) => {
+      if (this._isTeardownActive() || this._telnyxClient !== client) {
+        return;
+      }
       console.error('Telnyx client error:', error);
       this._connectionState.next(connection_state_1.TelnyxConnectionState.ERROR);
     });
@@ -526,5 +660,42 @@ class SessionManager {
   _generateSessionId() {
     return `session_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
   }
+  _assertCanStartConnection() {
+    if (this._isTeardownActive()) {
+      throw new Error('SessionManager has been disposed');
+    }
+  }
+  _isTeardownActive() {
+    return this._disposed || this._disposing;
+  }
+  _isConnectCanceled(connectionGeneration) {
+    return this._isTeardownActive() || this._connectionGeneration !== connectionGeneration;
+  }
+  _throwIfConnectCanceled(connectionGeneration) {
+    if (this._isConnectCanceled(connectionGeneration)) {
+      throw this._createConnectCanceledError();
+    }
+  }
+  _createConnectCanceledError() {
+    return new Error(
+      this._isTeardownActive()
+        ? 'SessionManager has been disposed'
+        : 'SessionManager connection has been canceled'
+    );
+  }
+  async _disconnectClient(client, errorMessage) {
+    try {
+      await client.disconnect();
+    } catch (error) {
+      console.error(errorMessage, error);
+      throw error;
+    }
+  }
+  async _disconnectAndForgetClient(client, errorMessage) {
+    await this._disconnectClient(client, errorMessage);
+    if (this._telnyxClient === client) {
+      this._telnyxClient = undefined;
+    }
+  }
 }
 exports.SessionManager = SessionManager;

package/lib/internal/voice-pn-bridge.d.ts

@@ -25,11 +25,18 @@ export interface VoicePnBridgeInterface {
   ): Promise<boolean>;
   hideOngoingCallNotification(): Promise<boolean>;
   hideIncomingCallNotification(): Promise<boolean>;
+  setIncomingCallRingtone(resourceName: string | null): Promise<boolean>;
+  getPendingCallKitAnswer(): Promise<string | null>;
+  clearPendingCallKitAnswer(): Promise<boolean>;
   getVoipToken(): Promise<string | null>;
   getPendingVoipPush(): Promise<string | null>;
   clearPendingVoipPush(): Promise<boolean>;
   getPendingVoipAction(): Promise<string | null>;
   clearPendingVoipAction(): Promise<boolean>;
+  setMissedCallNotificationsEnabled(enabled: boolean): Promise<boolean>;
+  getMissedCallNotificationsEnabled(): Promise<boolean>;
+  setSpeakerEnabled(enabled: boolean): Promise<boolean>;
+  isSpeakerEnabled(): Promise<boolean>;
 }
 declare const NativeBridge: VoicePnBridgeInterface;
 /**
@@ -87,6 +94,21 @@ export declare class VoicePnBridge {
    * Useful for dismissing notifications when call is answered/rejected in app
    */
   static hideIncomingCallNotification(): Promise<boolean>;
+  /**
+   * Configure Android's incoming-call ringtone using an app resource in `res/raw`.
+   * Pass no value to use the device's default phone ringtone.
+   */
+  static setIncomingCallRingtone(resourceName?: string): Promise<boolean>;
+  /**
+   * Get pending CallKit answer UUID from native storage (iOS only).
+   * When the user answers a CallKit call before JS listeners are ready,
+   * the native side persists the answer UUID in UserDefaults so JS can detect it.
+   */
+  static getPendingCallKitAnswer(): Promise<string | null>;
+  /**
+   * Clear pending CallKit answer from native storage (iOS only)
+   */
+  static clearPendingCallKitAnswer(): Promise<boolean>;
   /**
    * Get VoIP token from native storage
    */
@@ -107,6 +129,28 @@ export declare class VoicePnBridge {
    * Clear pending VoIP action from native storage (iOS only)
    */
   static clearPendingVoipAction(): Promise<boolean>;
+  /**
+   * Enable or disable local missed call notifications on iOS.
+   * Missed-call VoIP pushes are still handled through CallKit either way.
+   */
+  static setMissedCallNotificationsEnabled(enabled: boolean): Promise<boolean>;
+  /**
+   * Returns true by default, matching the sample-app behavior for missed calls.
+   */
+  static getMissedCallNotificationsEnabled(): Promise<boolean>;
+  /**
+   * Route call audio through the loudspeaker when enabled, or back to the
+   * platform default voice route when disabled.
+   */
+  static setSpeakerEnabled(enabled: boolean): Promise<boolean>;
+  /**
+   * Returns whether the current audio route is using the loudspeaker.
+   */
+  static isSpeakerEnabled(): Promise<boolean>;
+  /**
+   * Toggle between loudspeaker and the platform default voice route.
+   */
+  static toggleSpeaker(): Promise<boolean>;
   /**
    * Android → React Native: Listen for immediate call action events from notification buttons
    * Use this for active calls where immediate response is needed (e.g., ending ongoing calls)

package/lib/internal/voice-pn-bridge.js

@@ -124,6 +124,45 @@ class VoicePnBridge {
       return false;
     }
   }
+  /**
+   * Configure Android's incoming-call ringtone using an app resource in `res/raw`.
+   * Pass no value to use the device's default phone ringtone.
+   */
+  static async setIncomingCallRingtone(resourceName) {
+    if (react_native_1.Platform.OS !== 'android') return true;
+    try {
+      return await NativeBridge.setIncomingCallRingtone(resourceName?.trim() || null);
+    } catch (error) {
+      console.error('VoicePnBridge: Error setting incoming call ringtone:', error);
+      return false;
+    }
+  }
+  /**
+   * Get pending CallKit answer UUID from native storage (iOS only).
+   * When the user answers a CallKit call before JS listeners are ready,
+   * the native side persists the answer UUID in UserDefaults so JS can detect it.
+   */
+  static async getPendingCallKitAnswer() {
+    if (react_native_1.Platform.OS !== 'ios') return null;
+    try {
+      return await NativeBridge.getPendingCallKitAnswer();
+    } catch (error) {
+      console.error('VoicePnBridge: Error getting pending CallKit answer:', error);
+      return null;
+    }
+  }
+  /**
+   * Clear pending CallKit answer from native storage (iOS only)
+   */
+  static async clearPendingCallKitAnswer() {
+    if (react_native_1.Platform.OS !== 'ios') return true;
+    try {
+      return await NativeBridge.clearPendingCallKitAnswer();
+    } catch (error) {
+      console.error('VoicePnBridge: Error clearing pending CallKit answer:', error);
+      return false;
+    }
+  }
   /**
    * Get VoIP token from native storage
    */
@@ -184,6 +223,61 @@ class VoicePnBridge {
       return false;
     }
   }
+  /**
+   * Enable or disable local missed call notifications on iOS.
+   * Missed-call VoIP pushes are still handled through CallKit either way.
+   */
+  static async setMissedCallNotificationsEnabled(enabled) {
+    try {
+      return await NativeBridge.setMissedCallNotificationsEnabled(enabled);
+    } catch (error) {
+      console.error('VoicePnBridge: Error setting missed call notifications:', error);
+      return false;
+    }
+  }
+  /**
+   * Returns true by default, matching the sample-app behavior for missed calls.
+   */
+  static async getMissedCallNotificationsEnabled() {
+    try {
+      return await NativeBridge.getMissedCallNotificationsEnabled();
+    } catch (error) {
+      console.error('VoicePnBridge: Error getting missed call notifications setting:', error);
+      return true;
+    }
+  }
+  /**
+   * Route call audio through the loudspeaker when enabled, or back to the
+   * platform default voice route when disabled.
+   */
+  static async setSpeakerEnabled(enabled) {
+    try {
+      return await NativeBridge.setSpeakerEnabled(enabled);
+    } catch (error) {
+      console.error('VoicePnBridge: Error setting speaker route:', error);
+      throw error;
+    }
+  }
+  /**
+   * Returns whether the current audio route is using the loudspeaker.
+   */
+  static async isSpeakerEnabled() {
+    try {
+      return await NativeBridge.isSpeakerEnabled();
+    } catch (error) {
+      console.error('VoicePnBridge: Error getting speaker route:', error);
+      throw error;
+    }
+  }
+  /**
+   * Toggle between loudspeaker and the platform default voice route.
+   */
+  static async toggleSpeaker() {
+    // This is intentionally read-then-write because route changes can also come from
+    // the OS, Bluetooth, wired accessories, or the active call session.
+    const enabled = await VoicePnBridge.isSpeakerEnabled();
+    return VoicePnBridge.setSpeakerEnabled(!enabled);
+  }
   /**
    * Android → React Native: Listen for immediate call action events from notification buttons
    * Use this for active calls where immediate response is needed (e.g., ending ongoing calls)