@telnyx/react-voice-commons-sdk 0.3.1 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # CHANGELOG.md
 
+## [0.4.1] (2026-04-27)
+
+### Bug Fixing
+
+- **Recover from stale TelnyxRTC client on incoming VoIP push.** `SessionManager.handlePushNotification` now calls `client.isFresh(30_000)` before reusing an existing client. If the socket has been silent past the threshold (typical after an iOS app freeze), the client is disposed, state is flipped to `DISCONNECTED`, and the push falls through to the full `_connect()` path so login runs with the new push's `voice_sdk_id`. This resolves the case where an answered call would hang on "connecting" until CallKit timed out, because `processVoIPNotification()` was being called on a socket that had silently died.
+- Widened the reconnect-trigger state check in `handlePushNotification` to include `ERROR`, not only `DISCONNECTED`, so a push that arrives after a failed session re-establishes the connection instead of being dropped.
+
+### Dependencies
+
+- Now requires `@telnyx/react-native-voice-sdk >= 0.4.3`, which adds the `isFresh()` / `connectionIdleMs` API and auto-reconnects on unexpected socket errors. See the [voice-sdk 0.4.3 changelog](../package/CHANGELOG.md#043-2026-04-27) for details.
+
+## [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

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/session/session-manager.js

@@ -202,6 +202,39 @@ class SessionManager {
     );
     // Store the push notification payload for when the client is created
     this._pendingPushPayload = payload;
+    // If we have a TelnyxRTC instance but its socket isn't fresh — either not
+    // connected at all, or connected but with no traffic for longer than the
+    // threshold — dispose it so we go through the full _connect() path below
+    // instead of calling processVoIPNotification on a stale client.
+    //
+    // This handles two cases iOS gives us with the same code path:
+    //   1. Terminated-then-cold-launched: a client exists (constructed at
+    //      app boot) but its connection was never opened (idleMs=Infinity).
+    //   2. Suspended-then-thawed: a client exists with `connected=true`,
+    //      but the kernel killed the TLS session during freeze without
+    //      notifying the JS WebSocket wrapper, so no error event fired.
+    //
+    // 30s threshold matches the server's keep-alive ping cadence (~20s),
+    // so a live session always remains fresh.
+    const STALE_THRESHOLD_MS = 30000;
+    if (this._telnyxClient) {
+      const client = this._telnyxClient;
+      const isFresh =
+        typeof client.isFresh === 'function'
+          ? client.isFresh(STALE_THRESHOLD_MS)
+          : !!client.connected;
+      if (!isFresh) {
+        try {
+          await this._telnyxClient.disconnect();
+        } catch (err) {
+          console.warn('SessionManager: disconnect of stale client threw:', err);
+        }
+        this._telnyxClient = undefined;
+        if (this.currentState !== connection_state_1.TelnyxConnectionState.DISCONNECTED) {
+          this._connectionState.next(connection_state_1.TelnyxConnectionState.DISCONNECTED);
+        }
+      }
+    }
     // If we don't have a config yet but we're processing a push notification,
     // attempt to load stored config first (for terminated app startup)
     if (!this._currentConfig && !this._telnyxClient) {
@@ -269,11 +302,16 @@ class SessionManager {
       console.log(
         'SessionManager: RELEASE DEBUG - No client available, checking if we can trigger immediate connection'
       );
-      // If we have config (either existing or newly loaded from storage) and are disconnected, trigger immediate connection
-      // The _connect() method will process the pending push payload BEFORE calling connect()
+      // If we have config (either existing or newly loaded from storage) and
+      // are not currently connected/connecting, trigger immediate connection.
+      // We accept DISCONNECTED and ERROR (a socket failure bumps state to
+      // ERROR) so a push after a failed session still re-establishes the
+      // connection. The _connect() method will process the pending push
+      // payload BEFORE calling connect().
       if (
         this._currentConfig &&
-        this.currentState === connection_state_1.TelnyxConnectionState.DISCONNECTED
+        (this.currentState === connection_state_1.TelnyxConnectionState.DISCONNECTED ||
+          this.currentState === connection_state_1.TelnyxConnectionState.ERROR)
       ) {
         console.log(
           'SessionManager: RELEASE DEBUG - Triggering immediate connection for push notification with config type:',

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telnyx/react-voice-commons-sdk",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "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"
   },
@@ -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",

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

@@ -178,6 +178,40 @@ export class SessionManager {
     // Store the push notification payload for when the client is created
     (this as any)._pendingPushPayload = payload;
 
+    // If we have a TelnyxRTC instance but its socket isn't fresh — either not
+    // connected at all, or connected but with no traffic for longer than the
+    // threshold — dispose it so we go through the full _connect() path below
+    // instead of calling processVoIPNotification on a stale client.
+    //
+    // This handles two cases iOS gives us with the same code path:
+    //   1. Terminated-then-cold-launched: a client exists (constructed at
+    //      app boot) but its connection was never opened (idleMs=Infinity).
+    //   2. Suspended-then-thawed: a client exists with `connected=true`,
+    //      but the kernel killed the TLS session during freeze without
+    //      notifying the JS WebSocket wrapper, so no error event fired.
+    //
+    // 30s threshold matches the server's keep-alive ping cadence (~20s),
+    // so a live session always remains fresh.
+    const STALE_THRESHOLD_MS = 30000;
+    if (this._telnyxClient) {
+      const client = this._telnyxClient as any;
+      const isFresh =
+        typeof client.isFresh === 'function'
+          ? client.isFresh(STALE_THRESHOLD_MS)
+          : !!client.connected;
+      if (!isFresh) {
+        try {
+          await this._telnyxClient.disconnect();
+        } catch (err) {
+          console.warn('SessionManager: disconnect of stale client threw:', err);
+        }
+        this._telnyxClient = undefined;
+        if (this.currentState !== TelnyxConnectionState.DISCONNECTED) {
+          this._connectionState.next(TelnyxConnectionState.DISCONNECTED);
+        }
+      }
+    }
+
     // If we don't have a config yet but we're processing a push notification,
     // attempt to load stored config first (for terminated app startup)
     if (!this._currentConfig && !this._telnyxClient) {
@@ -255,9 +289,17 @@ export class SessionManager {
         'SessionManager: RELEASE DEBUG - No client available, checking if we can trigger immediate connection'
       );
 
-      // If we have config (either existing or newly loaded from storage) and are disconnected, trigger immediate connection
-      // The _connect() method will process the pending push payload BEFORE calling connect()
-      if (this._currentConfig && this.currentState === TelnyxConnectionState.DISCONNECTED) {
+      // If we have config (either existing or newly loaded from storage) and
+      // are not currently connected/connecting, trigger immediate connection.
+      // We accept DISCONNECTED and ERROR (a socket failure bumps state to
+      // ERROR) so a push after a failed session still re-establishes the
+      // connection. The _connect() method will process the pending push
+      // payload BEFORE calling connect().
+      if (
+        this._currentConfig &&
+        (this.currentState === TelnyxConnectionState.DISCONNECTED ||
+          this.currentState === TelnyxConnectionState.ERROR)
+      ) {
         console.log(
           'SessionManager: RELEASE DEBUG - Triggering immediate connection for push notification with config type:',
           (this._currentConfig as any).type || 'credential'

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