@telnyx/react-voice-commons-sdk 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # CHANGELOG.md
 
+## [0.4.0] (2026-04-19)
+
+### Enhancement
+
+- **DTMF support.** Added `Call.dtmf(digits: string): Promise<void>` — sends DTMF tones on the current call as Verto `INFO` messages. Accepts a single digit (e.g. `"5"`) or a whole string (e.g. `"1234#"`). Valid characters are `0-9`, `A-D`, `*`, and `#`; anything else is silently dropped by the underlying SDK. Call state must be `ACTIVE` — will throw otherwise.
+
+### Bug Fixing
+
+- **Fixed `IllegalArgumentException: Could not find @ReactModule annotation in VoicePnBridgeModule` crash** on Android when the app is cold-started by a push notification action (Answer/Decline). React Native 0.79+ requires `@ReactModule(name = …)` on native modules that are looked up by class via `ReactContext.getNativeModule(Class)`. The annotation has been added to `VoicePnBridgeModule`, and the module name is now sourced from a single `NAME` constant.
+
+### Dependencies
+
+- Now requires `@telnyx/react-native-voice-sdk >= 0.4.2`, which fixes a bug where every `Call.dtmf()` invocation threw `Invalid DTMF response received` even though the tone was delivered. See the [voice-sdk 0.4.2 changelog](../package/CHANGELOG.md#042-2026-04-19) for details.
+
+## [0.3.1] (2026-04-16)
+
+### Bug Fixing
+
+- Fixed stale `CONNECTED` state during background disconnect: `SessionManager.disconnect()` now emits `DISCONNECTED` before awaiting the underlying client teardown. Previously, observers (including the auto-reconnect logic in `TelnyxVoiceApp`) could read a stale `CONNECTED` value while the socket was being torn down, causing auto-reconnection to be skipped and subsequent `newCall()` attempts to fail with `Cannot make call when connection state is: DISCONNECTED` or `No connection exists. Please connect first.`
+- Tracked calls are now cleared on disconnect. Previously, calls left in non-terminal states when the socket was torn down would accumulate across background/foreground cycles, since a dead socket never emits the `ENDED`/`FAILED` events that normally trigger per-call cleanup.
+
 ## [0.3.0] (2026-04-15)
 
 ### ⚠️ Breaking changes

package/README.md

@@ -118,9 +118,18 @@ call.callState$.subscribe((state) => {
 
 ### Navigation
 
-As of **v0.3.0**, the SDK no longer navigates the host app. Routing on state transitions (e.g. redirecting to a login screen on disconnect, surfacing a dialer screen after answering a call via CallKit) is entirely the host app's responsibility. Subscribe to `connectionState$` and `activeCall$` and invoke your own navigator.
+As of **v0.3.0**, the SDK no longer navigates the host app. Routing on state transitions (e.g. redirecting to a login screen on disconnect, surfacing an in-call screen when a call arrives via push) is entirely the host app's responsibility. Subscribe to the observables below and invoke your own navigator.
 
-Example using `expo-router`:
+**What to observe:**
+
+| Observable                    | Emits                                                                                        | Use it for                                                                                                                                                                        |
+| ----------------------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `voipClient.connectionState$` | `TelnyxConnectionState` (`CONNECTING`, `CONNECTED`, `RECONNECTING`, `DISCONNECTED`, `ERROR`) | Redirect to login on `DISCONNECTED`; gate outbound-call UI on `CONNECTED`. There is no separate `loginState$` — `CONNECTED` means the socket is up **and** authenticated.         |
+| `voipClient.activeCall$`      | `Call \| null`                                                                               | Navigate to your in-call screen when a call appears. Primary signal for push-launched cold starts — when the SDK finishes the push-driven login and the call arrives, this emits. |
+| `voipClient.calls$`           | `Call[]`                                                                                     | Multi-call UIs (call waiting, conference).                                                                                                                                        |
+| `call.callState$`             | `TelnyxCallState`                                                                            | Per-call transitions (ringing / active / held / ended).                                                                                                                           |
+
+#### Redirect to login on disconnect
 
 ```tsx
 import { router } from 'expo-router';
@@ -137,6 +146,43 @@ useEffect(() => {
 }, []);
 ```
 
+#### Navigate to in-call screen when a call arrives (push-launched or otherwise)
+
+This is the piece that pairs with the push flow: after `isLaunchedFromPushNotification()` tells you to skip manual login, the SDK drives login internally and the call shows up on `activeCall$`. The same subscription handles foreground pushes and outbound calls, so you only need one:
+
+```tsx
+import { router } from 'expo-router';
+import { useEffect } from 'react';
+
+useEffect(() => {
+  // Handle the cold-start race: if the call was already delivered before this
+  // component mounted (common on push-launched cold starts), read it synchronously.
+  if (voipClient.currentActiveCall) {
+    router.replace('/call');
+  }
+
+  const sub = voipClient.activeCall$.subscribe((call) => {
+    if (call) router.replace('/call');
+    else router.replace('/dialer');
+  });
+  return () => sub.unsubscribe();
+}, []);
+```
+
+**Note on CallKit / ConnectionService:** the native call UI (ringtone, answer/decline) is shown by the OS regardless — your RN screen is only visible once the user taps into the app. If you only need native UI, you can skip the navigation step entirely.
+
+#### Optional: gate outbound-call UI on CONNECTED
+
+```tsx
+import { canMakeCalls } from '@telnyx/react-voice-commons-sdk';
+
+const [canCall, setCanCall] = useState(false);
+useEffect(() => {
+  const sub = voipClient.connectionState$.subscribe((s) => setCanCall(canMakeCalls(s)));
+  return () => sub.unsubscribe();
+}, []);
+```
+
 The same pattern works with `react-navigation`, React Router, or any other navigator — the SDK is agnostic.
 
 ### 4. Call Management
@@ -152,8 +198,64 @@ await call.answer();
 await call.mute();
 await call.hold();
 await call.hangup();
+
+// Send DTMF tones (for IVRs, conference pins, etc.)
+await call.dtmf('1'); // single digit
+await call.dtmf('1234#'); // whole string
+```
+
+**DTMF:** `call.dtmf(digits)` sends each character as a Verto `INFO` message to the Telnyx platform. Valid characters are `0-9`, `A-D`, `*`, and `#`; any other characters are silently dropped by the underlying SDK. The call must be in the `ACTIVE` state — calling `dtmf()` in any other state throws. Safe to call with a single digit for dialpad presses or with a whole string for pre-recorded sequences.
+
+### Push Notification Flow
+
+You do not wire push handlers in JS. The native layer does the work:
+
+- **Android**: `TelnyxFirebaseMessagingService` receives the FCM message, posts the call notification, and launches `TelnyxMainActivity` with the intent on Answer/Decline.
+- **iOS**: `TelnyxVoipPushHandler` receives the PushKit payload and reports the call to CallKit.
+
+The SDK then connects the socket and restores the call internally. You observe `voipClient.calls$` to render UI.
+
+#### Detecting a Push-Launched Cold Start
+
+When the OS wakes the app from a terminated state to deliver a call, the SDK is already handling login via the push flow. If your app _also_ triggers a login on mount, you get two competing sessions (double-login), which causes the call to fail or the socket to churn.
+
+Use the static `TelnyxVoipClient.isLaunchedFromPushNotification()` to guard your login:
+
+```tsx
+import { TelnyxVoipClient } from '@telnyx/react-voice-commons-sdk';
+
+React.useEffect(() => {
+  TelnyxVoipClient.isLaunchedFromPushNotification().then((isFromPush) => {
+    if (isFromPush) return; // SDK is handling login via the push flow
+    voipClient.loginFromStoredConfig(); // Normal cold start
+  });
+}, []);
+```
+
+Returns `true` when a pending FCM intent (Android) or PushKit payload (iOS) has not yet been consumed.
+
+#### Common Mistake: Manual or Automatic Login on Push
+
+The single most common integration bug is re-logging in while the SDK is already handling a push:
+
+```tsx
+// WRONG — runs on every mount, including push-launched cold starts
+React.useEffect(() => {
+  voipClient.login(config); // or loginFromStoredConfig(), or loginWithToken()
+}, []);
+```
+
+```tsx
+// Right — guard the login on push-launched cold starts
+React.useEffect(() => {
+  TelnyxVoipClient.isLaunchedFromPushNotification().then((isFromPush) => {
+    if (!isFromPush) voipClient.loginFromStoredConfig();
+  });
+}, []);
 ```
 
+Symptoms of getting this wrong: the incoming call rings briefly then disappears, the socket disconnects mid-call, or CallKit shows a call that immediately ends.
+
 ### Authentication & Persistent Storage
 
 The library supports both credential-based and token-based authentication with automatic persistence for seamless reconnection.
@@ -273,17 +375,12 @@ The `TelnyxMainActivity` provides:
 
 ### 2. Push Notification Setup
 
-1. Place `google-services.json` in the project root
-2. Register background message handler:
+1. Place `google-services.json` in the project root.
+2. Create an FCM service that extends `TelnyxFirebaseMessagingService` and a notification action receiver that extends `TelnyxNotificationActionReceiver`, then register both in `AndroidManifest.xml`. See the [push notification app setup guide](../docs-markdown/push-notification/app-setup.md) for the full boilerplate.
 
-```tsx
-import messaging from '@react-native-firebase/messaging';
-import { TelnyxVoiceApp } from '@telnyx/react-voice-commons-sdk';
+> **Do not** register `messaging().setBackgroundMessageHandler(...)` from JS. Android push is handled entirely by the native `TelnyxFirebaseMessagingService` — adding a JS handler will fight the native layer and can double-process calls. There is no `TelnyxVoiceApp.handleBackgroundPush` step required on Android.
 
-messaging().setBackgroundMessageHandler(async (remoteMessage) => {
-  await TelnyxVoiceApp.handleBackgroundPush(remoteMessage.data);
-});
-```
+See [Push Notification Flow](#push-notification-flow) below for how to detect push-launched cold starts and avoid double-login.
 
 ### iOS Integration
 

package/android/src/main/java/com/telnyx/react_voice_commons/VoicePnBridgeModule.kt

@@ -9,17 +9,18 @@ import com.facebook.react.bridge.ReactMethod
 import com.facebook.react.bridge.Promise
 import com.facebook.react.bridge.WritableMap
 import com.facebook.react.bridge.Arguments
+import com.facebook.react.module.annotations.ReactModule
 import com.facebook.react.modules.core.DeviceEventManagerModule
 
+@ReactModule(name = VoicePnBridgeModule.NAME)
 class VoicePnBridgeModule(reactContext: ReactApplicationContext) : ReactContextBaseJavaModule(reactContext) {
     
     companion object {
+        const val NAME = "VoicePnBridge"
         private const val TAG = "VoicePnBridgeModule"
     }
-    
-    override fun getName(): String {
-        return "VoicePnBridge"
-    }
+
+    override fun getName(): String = NAME
     
     @ReactMethod
     fun getPendingPushAction(promise: Promise) {

package/lib/internal/calls/call-state-controller.d.ts

@@ -71,6 +71,13 @@ export declare class CallStateController {
     isWaitingForInvite: () => boolean;
     onInviteAutoAccepted: () => void;
   }): void;
+  /**
+   * Clear all tracked calls. Called when the session disconnects so that
+   * calls left in non-terminal states (because the socket died before
+   * their ENDED/FAILED events could arrive) don't accumulate as ghosts
+   * across reconnect cycles.
+   */
+  clearAllCalls(): void;
   /**
    * Dispose of the controller and clean up resources
    */

package/lib/internal/calls/call-state-controller.js

@@ -161,6 +161,29 @@ class CallStateController {
     this._isWaitingForInvite = callbacks.isWaitingForInvite;
     this._onInviteAutoAccepted = callbacks.onInviteAutoAccepted;
   }
+  /**
+   * Clear all tracked calls. Called when the session disconnects so that
+   * calls left in non-terminal states (because the socket died before
+   * their ENDED/FAILED events could arrive) don't accumulate as ghosts
+   * across reconnect cycles.
+   */
+  clearAllCalls() {
+    if (this._callMap.size === 0) {
+      return;
+    }
+    console.log(
+      `CallStateController: Clearing ${this._callMap.size} tracked call(s) on disconnect`
+    );
+    for (const call of this._callMap.values()) {
+      try {
+        call.dispose();
+      } catch (error) {
+        console.warn('CallStateController: Error disposing call during clear:', error);
+      }
+    }
+    this._callMap.clear();
+    this._calls.next([]);
+  }
   /**
    * Dispose of the controller and clean up resources
    */

package/lib/internal/session/session-manager.d.ts

@@ -15,6 +15,7 @@ export declare class SessionManager {
   private _sessionId;
   private _disposed;
   private _onClientReady?;
+  private _onDisconnect?;
   constructor();
   /**
    * Observable stream of connection state changes
@@ -24,6 +25,11 @@ export declare class SessionManager {
    * Set callback to be called when the Telnyx client is ready
    */
   setOnClientReady(callback: () => void): void;
+  /**
+   * Set callback to be called when the session disconnects, so dependent
+   * subsystems (e.g. the call state controller) can clear their state.
+   */
+  setOnDisconnect(callback: () => void): void;
   /**
    * Current connection state (synchronous access)
    */
@@ -45,7 +51,14 @@ export declare class SessionManager {
    */
   connectWithToken(config: TokenConfig): Promise<void>;
   /**
-   * Disconnect from the Telnyx platform
+   * Disconnect from the Telnyx platform.
+   *
+   * The DISCONNECTED state is emitted BEFORE awaiting the underlying
+   * client teardown so that observers (including the auto-reconnect logic
+   * in TelnyxVoiceApp) cannot read a stale CONNECTED value during the
+   * short window while the socket is being torn down. Tracked calls are
+   * cleared here too, since a torn-down socket will never emit the
+   * ENDED/FAILED events that normally trigger per-call cleanup.
    */
   disconnect(): Promise<void>;
   /**

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

@@ -85,6 +85,13 @@ class SessionManager {
   setOnClientReady(callback) {
     this._onClientReady = callback;
   }
+  /**
+   * Set callback to be called when the session disconnects, so dependent
+   * subsystems (e.g. the call state controller) can clear their state.
+   */
+  setOnDisconnect(callback) {
+    this._onDisconnect = callback;
+  }
   /**
    * Current connection state (synchronous access)
    */
@@ -124,13 +131,28 @@ class SessionManager {
     await this._connect();
   }
   /**
-   * Disconnect from the Telnyx platform
+   * Disconnect from the Telnyx platform.
+   *
+   * The DISCONNECTED state is emitted BEFORE awaiting the underlying
+   * client teardown so that observers (including the auto-reconnect logic
+   * in TelnyxVoiceApp) cannot read a stale CONNECTED value during the
+   * short window while the socket is being torn down. Tracked calls are
+   * cleared here too, since a torn-down socket will never emit the
+   * ENDED/FAILED events that normally trigger per-call cleanup.
    */
   async disconnect() {
     if (this._disposed) {
       return;
     }
     this._currentConfig = undefined;
+    this._connectionState.next(connection_state_1.TelnyxConnectionState.DISCONNECTED);
+    if (this._onDisconnect) {
+      try {
+        this._onDisconnect();
+      } catch (error) {
+        console.error('Error in onDisconnect callback:', error);
+      }
+    }
     if (this._telnyxClient) {
       try {
         await this._telnyxClient.disconnect();
@@ -138,7 +160,6 @@ class SessionManager {
         console.error('Error during disconnect:', error);
       }
     }
-    this._connectionState.next(connection_state_1.TelnyxConnectionState.DISCONNECTED);
   }
   /**
    * Disable push notifications for the current session.

package/lib/models/call.d.ts

@@ -171,6 +171,18 @@ export declare class Call {
    * Toggle mute state
    */
   toggleMute(): Promise<void>;
+  /**
+   * Send DTMF tones on this call.
+   *
+   * Each character in `digits` is sent as a Verto INFO message to the Telnyx
+   * platform. Valid characters are `0-9`, `A-D`, `*`, and `#`; any other
+   * characters are silently dropped by the underlying SDK.
+   *
+   * Only valid while the call is `ACTIVE` — will throw otherwise. Safe to call
+   * with a single digit (e.g. for IVR dialpad presses) or a whole string
+   * (e.g. `"123#"`).
+   */
+  dtmf(digits: string): Promise<void>;
   /**
    * Set the call to connecting state (used for push notification calls when answered via CallKit)
    * @internal

package/lib/models/call.js

@@ -374,6 +374,28 @@ class Call {
       await this.mute();
     }
   }
+  /**
+   * Send DTMF tones on this call.
+   *
+   * Each character in `digits` is sent as a Verto INFO message to the Telnyx
+   * platform. Valid characters are `0-9`, `A-D`, `*`, and `#`; any other
+   * characters are silently dropped by the underlying SDK.
+   *
+   * Only valid while the call is `ACTIVE` — will throw otherwise. Safe to call
+   * with a single digit (e.g. for IVR dialpad presses) or a whole string
+   * (e.g. `"123#"`).
+   */
+  async dtmf(digits) {
+    if (this.currentState !== call_state_1.TelnyxCallState.ACTIVE) {
+      throw new Error(`Cannot send DTMF in state: ${this.currentState}`);
+    }
+    try {
+      await this._telnyxCall.dtmf(digits);
+    } catch (error) {
+      console.error('Failed to send DTMF:', error);
+      throw error;
+    }
+  }
   /**
    * Set the call to connecting state (used for push notification calls when answered via CallKit)
    * @internal

package/lib/telnyx-voip-client.js

@@ -66,6 +66,11 @@ class TelnyxVoipClient {
       );
       this._callStateController.initializeClientListeners();
     });
+    // Clear any tracked calls when the session disconnects, so ghosts
+    // don't accumulate across background → foreground reconnect cycles.
+    this._sessionManager.setOnDisconnect(() => {
+      this._callStateController.clearAllCalls();
+    });
     if (this._options.debug) {
       console.log('TelnyxVoipClient initialized with options:', this._options);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telnyx/react-voice-commons-sdk",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "A high-level, state-agnostic, drop-in module for the Telnyx React Native SDK that simplifies WebRTC voice calling integration",
   "main": "lib/index.js",
   "module": "lib/index.js",
@@ -39,7 +39,7 @@
     "android": "expo run:android",
     "ios": "expo run:ios",
     "dev:local": "npm pkg set dependencies.@telnyx/react-native-voice-sdk=file:../package",
-    "dev:published": "npm pkg set \"dependencies.@telnyx/react-native-voice-sdk\"=\">=0.4.1\"",
+    "dev:published": "npm pkg set \"dependencies.@telnyx/react-native-voice-sdk\"=\">=0.4.2\"",
     "prepublishOnly": "npm run dev:published && npm install --legacy-peer-deps",
     "postpublish": "npm run dev:local && npm install --legacy-peer-deps"
   },
@@ -59,7 +59,7 @@
   "homepage": "https://github.com/team-telnyx/react-native-voice-commons",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/team-telnyx/react-native-voice-commons.git"
+    "url": "https://github.com/team-telnyx/react-native-voice-commons.git"
   },
   "bugs": {
     "url": "https://github.com/team-telnyx/react-native-voice-commons/issues"
@@ -86,7 +86,7 @@
   },
   "dependencies": {
     "@react-native-community/eslint-config": "^3.2.0",
-    "@telnyx/react-native-voice-sdk": ">=0.4.1",
+    "@telnyx/react-native-voice-sdk": ">=0.4.2",
     "eventemitter3": "^5.0.1",
     "expo": "~53.0.22",
     "react-native-url-polyfill": "^3.0.0",
@@ -112,6 +112,7 @@
     "node": ">=16"
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "provenance": true
   }
 }

package/src/internal/calls/call-state-controller.ts

@@ -190,6 +190,32 @@ export class CallStateController {
     this._onInviteAutoAccepted = callbacks.onInviteAutoAccepted;
   }
 
+  /**
+   * Clear all tracked calls. Called when the session disconnects so that
+   * calls left in non-terminal states (because the socket died before
+   * their ENDED/FAILED events could arrive) don't accumulate as ghosts
+   * across reconnect cycles.
+   */
+  clearAllCalls(): void {
+    if (this._callMap.size === 0) {
+      return;
+    }
+
+    console.log(
+      `CallStateController: Clearing ${this._callMap.size} tracked call(s) on disconnect`
+    );
+
+    for (const call of this._callMap.values()) {
+      try {
+        call.dispose();
+      } catch (error) {
+        console.warn('CallStateController: Error disposing call during clear:', error);
+      }
+    }
+    this._callMap.clear();
+    this._calls.next([]);
+  }
+
   /**
    * Dispose of the controller and clean up resources
    */

package/src/internal/session/session-manager.ts

@@ -26,6 +26,7 @@ export class SessionManager {
   private _sessionId: string;
   private _disposed = false;
   private _onClientReady?: () => void;
+  private _onDisconnect?: () => void;
 
   constructor() {
     this._sessionId = this._generateSessionId();
@@ -45,6 +46,14 @@ export class SessionManager {
     this._onClientReady = callback;
   }
 
+  /**
+   * Set callback to be called when the session disconnects, so dependent
+   * subsystems (e.g. the call state controller) can clear their state.
+   */
+  setOnDisconnect(callback: () => void): void {
+    this._onDisconnect = callback;
+  }
+
   /**
    * Current connection state (synchronous access)
    */
@@ -91,7 +100,14 @@ export class SessionManager {
   }
 
   /**
-   * Disconnect from the Telnyx platform
+   * Disconnect from the Telnyx platform.
+   *
+   * The DISCONNECTED state is emitted BEFORE awaiting the underlying
+   * client teardown so that observers (including the auto-reconnect logic
+   * in TelnyxVoiceApp) cannot read a stale CONNECTED value during the
+   * short window while the socket is being torn down. Tracked calls are
+   * cleared here too, since a torn-down socket will never emit the
+   * ENDED/FAILED events that normally trigger per-call cleanup.
    */
   async disconnect(): Promise<void> {
     if (this._disposed) {
@@ -99,6 +115,15 @@ export class SessionManager {
     }
 
     this._currentConfig = undefined;
+    this._connectionState.next(TelnyxConnectionState.DISCONNECTED);
+
+    if (this._onDisconnect) {
+      try {
+        this._onDisconnect();
+      } catch (error) {
+        console.error('Error in onDisconnect callback:', error);
+      }
+    }
 
     if (this._telnyxClient) {
       try {
@@ -107,8 +132,6 @@ export class SessionManager {
         console.error('Error during disconnect:', error);
       }
     }
-
-    this._connectionState.next(TelnyxConnectionState.DISCONNECTED);
   }
 
   /**

package/src/models/call.ts

@@ -353,6 +353,30 @@ export class Call {
     }
   }
 
+  /**
+   * Send DTMF tones on this call.
+   *
+   * Each character in `digits` is sent as a Verto INFO message to the Telnyx
+   * platform. Valid characters are `0-9`, `A-D`, `*`, and `#`; any other
+   * characters are silently dropped by the underlying SDK.
+   *
+   * Only valid while the call is `ACTIVE` — will throw otherwise. Safe to call
+   * with a single digit (e.g. for IVR dialpad presses) or a whole string
+   * (e.g. `"123#"`).
+   */
+  async dtmf(digits: string): Promise<void> {
+    if (this.currentState !== TelnyxCallState.ACTIVE) {
+      throw new Error(`Cannot send DTMF in state: ${this.currentState}`);
+    }
+
+    try {
+      await this._telnyxCall.dtmf(digits);
+    } catch (error) {
+      console.error('Failed to send DTMF:', error);
+      throw error;
+    }
+  }
+
   /**
    * Set the call to connecting state (used for push notification calls when answered via CallKit)
    * @internal

package/src/telnyx-voip-client.ts

@@ -82,6 +82,12 @@ export class TelnyxVoipClient {
       this._callStateController.initializeClientListeners();
     });
 
+    // Clear any tracked calls when the session disconnects, so ghosts
+    // don't accumulate across background → foreground reconnect cycles.
+    this._sessionManager.setOnDisconnect(() => {
+      this._callStateController.clearAllCalls();
+    });
+
     if (this._options.debug) {
       console.log('TelnyxVoipClient initialized with options:', this._options);
     }