@telnyx/react-voice-commons-sdk 1.1.1 → 1.2.0

package/src/internal/signaling-environment.ts

@@ -0,0 +1,20 @@
+import { TelnyxEnvironment } from '../models/config';
+
+export const SIGNALING_ENVIRONMENT_STORAGE_KEY = '@telnyx_signaling_environment';
+
+/**
+ * Resolves the signaling environment for a stored-config restore.
+ *
+ * An explicit stored selection always wins. A missing or invalid stored value
+ * (e.g. credentials persisted by an older Commons version) falls back to the
+ * client's configured default, and only then to production.
+ */
+export function resolveStoredEnvironment(
+  storedEnvironment: string | null | undefined,
+  defaultEnvironment?: TelnyxEnvironment
+): TelnyxEnvironment {
+  if (storedEnvironment === 'development' || storedEnvironment === 'production') {
+    return storedEnvironment;
+  }
+  return defaultEnvironment ?? 'production';
+}

package/src/models/call.ts

@@ -2,6 +2,7 @@ import { BehaviorSubject, Observable } from 'rxjs';
 import { distinctUntilChanged, map } from 'rxjs/operators';
 import { TelnyxCallState, CallStateHelpers } from './call-state';
 import { Call as TelnyxCall } from '@telnyx/react-native-voice-sdk';
+import type { CallQualityMetrics } from '@telnyx/react-native-voice-sdk';
 import { Platform } from 'react-native';
 
 /**
@@ -16,6 +17,10 @@ export class Call {
   private readonly _isMuted = new BehaviorSubject<boolean>(false);
   private readonly _isHeld = new BehaviorSubject<boolean>(false);
   private readonly _duration = new BehaviorSubject<number>(0);
+  private readonly _qualityMetrics = new BehaviorSubject<CallQualityMetrics | null>(null);
+  private readonly _onQualityMetrics = (metrics: CallQualityMetrics) => {
+    this._qualityMetrics.next(metrics);
+  };
 
   private _durationTimer?: NodeJS.Timeout;
   private _startTime?: Date;
@@ -113,7 +118,7 @@ export class Call {
   /**
    * Custom headers received from the WebRTC INVITE message.
    * These headers are passed during call initiation and can contain application-specific information.
-   * Format should be [{"name": "X-Header-Name", "value": "Value"}] where header names must start with "X-".
+   * Format: `[{"name": "X-Header-Name", "value": "Value"}]`; header names must start with `X-`.
    */
   get inviteCustomHeaders(): { name: string; value: string }[] | null {
     return this._telnyxCall.inviteCustomHeaders;
@@ -122,7 +127,7 @@ export class Call {
   /**
    * Custom headers received from the WebRTC ANSWER message.
    * These headers are passed during call acceptance and can contain application-specific information.
-   * Format should be [{"name": "X-Header-Name", "value": "Value"}] where header names must start with "X-".
+   * Format: `[{"name": "X-Header-Name", "value": "Value"}]`; header names must start with `X-`.
    */
   get answerCustomHeaders(): { name: string; value: string }[] | null {
     return this._telnyxCall.answerCustomHeaders;
@@ -136,6 +141,19 @@ export class Call {
     return this._telnyxCall;
   }
 
+  /**
+   * Inject an ICE failure into the underlying SDK recovery flow for manual
+   * testing. The underlying SDK accepts this only when debug mode is enabled.
+   *
+   * @returns true when a recovery episode was started.
+   */
+  simulateIceFailureForTesting(): boolean {
+    const testableCall = this._telnyxCall as TelnyxCall & {
+      simulateIceFailureForTesting?: () => boolean;
+    };
+    return testableCall.simulateIceFailureForTesting?.() ?? false;
+  }
+
   /**
    * Observable stream of call state changes
    */
@@ -164,6 +182,23 @@ export class Call {
     return this._duration.asObservable().pipe(distinctUntilChanged());
   }
 
+  /**
+   * Observable stream of call quality metrics updates.
+   * Emits `null` initially, then a {@link CallQualityMetrics} object
+   * each time the underlying SDK collects a new sample.
+   */
+  get qualityMetrics$(): Observable<CallQualityMetrics | null> {
+    return this._qualityMetrics.asObservable().pipe(distinctUntilChanged());
+  }
+
+  /**
+   * Current call quality metrics (synchronous access).
+   * Returns `null` until the first metrics sample is collected.
+   */
+  get currentQualityMetrics(): CallQualityMetrics | null {
+    return this._qualityMetrics.value;
+  }
+
   /**
    * Observable that emits true when the call can be answered
    */
@@ -413,10 +448,12 @@ export class Call {
    */
   dispose(): void {
     this._stopDurationTimer();
+    this._telnyxCall.off?.('telnyx.call.qualityMetrics', this._onQualityMetrics);
     this._callState.complete();
     this._isMuted.complete();
     this._isHeld.complete();
     this._duration.complete();
+    this._qualityMetrics.complete();
   }
 
   /**
@@ -518,6 +555,11 @@ export class Call {
         }
       }
     });
+
+    // Forward quality metrics from the underlying SDK
+    // Subscribe to the event rather than the single onQualityMetrics slot, so
+    // an app can still set that callback on the underlying call.
+    this._telnyxCall.on('telnyx.call.qualityMetrics', this._onQualityMetrics);
   }
 
   /**

package/src/models/config.ts

@@ -1,6 +1,10 @@
+import type { TelnyxIceServer } from '@telnyx/react-native-voice-sdk';
+
 /**
  * Configuration for credential-based authentication
  */
+export type TelnyxEnvironment = 'production' | 'development';
+
 export interface CredentialConfig {
   type: 'credential';
   sipUser: string;
@@ -15,14 +19,27 @@ export interface CredentialConfig {
   incomingCallRingtone?: string;
   /** Enable Trickle ICE. Default: false */
   useTrickleIce?: boolean;
+  /** Signaling environment. Default: production */
+  environment?: TelnyxEnvironment;
   /** Enable automatic call quality reporting. Default: true */
   enableCallReports?: boolean;
+  /**
+   * Deliver real-time call quality metrics on `Call.qualityMetrics$` while a
+   * call is active. Also enabled by `debug`. Default: false
+   */
+  enableQualityMetrics?: boolean;
   /** Stats collection interval in seconds. Default: 5 */
   callReportInterval?: number;
   /** Minimum log level for call reports: 'debug' | 'info' | 'warn' | 'error'. Default: 'debug' */
   callReportLogLevel?: string;
   /** Max log entries per call. Default: 1000 */
   callReportMaxLogEntries?: number;
+  /**
+   * Custom ICE servers (STUN/TURN) for WebRTC peer connections.
+   * When provided, overrides the Telnyx production defaults.
+   * When omitted, the SDK uses Telnyx defaults (STUN → TURN UDP → TURN TCP → TURNS 443).
+   */
+  iceServers?: TelnyxIceServer[];
 }
 
 /**
@@ -41,14 +58,27 @@ export interface TokenConfig {
   incomingCallRingtone?: string;
   /** Enable Trickle ICE. Default: false */
   useTrickleIce?: boolean;
+  /** Signaling environment. Default: production */
+  environment?: TelnyxEnvironment;
   /** Enable automatic call quality reporting. Default: true */
   enableCallReports?: boolean;
+  /**
+   * Deliver real-time call quality metrics on `Call.qualityMetrics$` while a
+   * call is active. Also enabled by `debug`. Default: false
+   */
+  enableQualityMetrics?: boolean;
   /** Stats collection interval in seconds. Default: 5 */
   callReportInterval?: number;
   /** Minimum log level for call reports: 'debug' | 'info' | 'warn' | 'error'. Default: 'debug' */
   callReportLogLevel?: string;
   /** Max log entries per call. Default: 1000 */
   callReportMaxLogEntries?: number;
+  /**
+   * Custom ICE servers (STUN/TURN) for WebRTC peer connections.
+   * When provided, overrides the Telnyx production defaults.
+   * When omitted, the SDK uses Telnyx defaults (STUN → TURN UDP → TURN TCP → TURNS 443).
+   */
+  iceServers?: TelnyxIceServer[];
 }
 
 /**

package/src/telnyx-voip-client.ts

@@ -3,14 +3,26 @@ import { Platform } from 'react-native';
 import { TelnyxConnectionState } from './models/connection-state';
 import { Call } from './models/call';
 import { TelnyxCallState } from './models/call-state';
-import { Config, CredentialConfig, TokenConfig, validateConfig } from './models/config';
+import {
+  Config,
+  CredentialConfig,
+  TelnyxEnvironment,
+  TokenConfig,
+  validateConfig,
+} from './models/config';
 import { SessionManager } from './internal/session/session-manager';
+import {
+  SIGNALING_ENVIRONMENT_STORAGE_KEY,
+  resolveStoredEnvironment,
+} from './internal/signaling-environment';
 import { CallStateController, type CustomHeaders } from './internal/calls/call-state-controller';
 import { VoicePnBridge } from './internal/voice-pn-bridge';
+import { ICE_SERVERS_STORAGE_KEY, parseStoredIceServers } from './internal/ice-servers-storage';
 
 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';
+const QUALITY_METRICS_STORAGE_KEY = '@enable_quality_metrics';
 const LEGACY_CALLKIT_ANSWER_KEY = '__legacy_callkit_answer__';
 
 interface PendingCallKitAnswer {
@@ -30,6 +42,9 @@ export interface TelnyxVoipClientOptions {
 
   /** Enable Trickle ICE for calls created by this client */
   useTrickleIce?: boolean;
+
+  /** Signaling environment used for connections - default: production */
+  environment?: TelnyxEnvironment;
 }
 
 /**
@@ -84,11 +99,12 @@ export class TelnyxVoipClient {
       enableAppStateManagement: true,
       debug: false,
       useTrickleIce: false,
+      environment: 'production',
       ...options,
     };
 
     // Initialize core components
-    this._sessionManager = new SessionManager();
+    this._sessionManager = new SessionManager({ defaultEnvironment: this._options.environment });
     this._callStateController = new CallStateController(this._sessionManager);
 
     // Set up callback to initialize call state controller listeners when client is ready
@@ -304,6 +320,7 @@ export class TelnyxVoipClient {
     const loginConfig = await this._withNativeVoipPushToken({
       ...config,
       useTrickleIce: config.useTrickleIce ?? this._options.useTrickleIce,
+      environment: config.environment ?? this._options.environment,
     });
 
     await VoicePnBridge.setIncomingCallRingtone(loginConfig.incomingCallRingtone);
@@ -338,6 +355,7 @@ export class TelnyxVoipClient {
     const loginConfig = await this._withNativeVoipPushToken({
       ...config,
       useTrickleIce: config.useTrickleIce ?? this._options.useTrickleIce,
+      environment: config.environment ?? this._options.environment,
     });
 
     await VoicePnBridge.setIncomingCallRingtone(loginConfig.incomingCallRingtone);
@@ -372,7 +390,7 @@ export class TelnyxVoipClient {
    * This method is used for auto-reconnection scenarios where the app
    * comes back to the foreground and needs to restore the connection.
    *
-   * @returns Promise<boolean> - true if reconnection was successful, false otherwise
+   * @returns Whether reconnection was successful.
    */
   async loginFromStoredConfig(): Promise<boolean> {
     this._throwIfDisposed();
@@ -394,10 +412,15 @@ export class TelnyxVoipClient {
       const storedMissedCallNotifications = await AsyncStorage.getItem(
         MISSED_CALL_NOTIFICATIONS_STORAGE_KEY
       );
+      const storedEnvironment = await AsyncStorage.getItem(SIGNALING_ENVIRONMENT_STORAGE_KEY);
+      const storedQualityMetrics = await AsyncStorage.getItem(QUALITY_METRICS_STORAGE_KEY);
+      const iceServers = parseStoredIceServers(await AsyncStorage.getItem(ICE_SERVERS_STORAGE_KEY));
       const useTrickleIce =
         storedUseTrickleIce === null ? this._options.useTrickleIce : storedUseTrickleIce === 'true';
       const pushWhenActive = storedPushWhenActive === 'true';
       const enableMissedCallNotifications = storedMissedCallNotifications === 'true';
+      const enableQualityMetrics = storedQualityMetrics === 'true';
+      const environment = resolveStoredEnvironment(storedEnvironment, this._options.environment);
       const nativePushToken =
         Platform.OS === 'ios' ? (await VoicePnBridge.getVoipToken())?.trim() : null;
       const pushNotificationDeviceToken = nativePushToken || storedPushToken;
@@ -415,6 +438,9 @@ export class TelnyxVoipClient {
           useTrickleIce,
           pushWhenActive,
           enableMissedCallNotifications,
+          enableQualityMetrics,
+          environment,
+          iceServers,
         });
 
         if (this._options.debug) {
@@ -437,6 +463,9 @@ export class TelnyxVoipClient {
           useTrickleIce,
           pushWhenActive,
           enableMissedCallNotifications,
+          enableQualityMetrics,
+          environment,
+          iceServers,
         });
 
         if (this._options.debug) {
@@ -750,6 +779,20 @@ export class TelnyxVoipClient {
         MISSED_CALL_NOTIFICATIONS_STORAGE_KEY,
         String(config.enableMissedCallNotifications ?? false)
       );
+      await AsyncStorage.setItem(
+        QUALITY_METRICS_STORAGE_KEY,
+        String(config.enableQualityMetrics ?? false)
+      );
+      await AsyncStorage.setItem(
+        SIGNALING_ENVIRONMENT_STORAGE_KEY,
+        config.environment ?? this._options.environment ?? 'production'
+      );
+
+      if (config.iceServers) {
+        await AsyncStorage.setItem(ICE_SERVERS_STORAGE_KEY, JSON.stringify(config.iceServers));
+      } else {
+        await AsyncStorage.removeItem(ICE_SERVERS_STORAGE_KEY);
+      }
 
       if (config.pushNotificationDeviceToken) {
         await AsyncStorage.setItem('@push_token', config.pushNotificationDeviceToken);
@@ -789,6 +832,20 @@ export class TelnyxVoipClient {
         MISSED_CALL_NOTIFICATIONS_STORAGE_KEY,
         String(config.enableMissedCallNotifications ?? false)
       );
+      await AsyncStorage.setItem(
+        QUALITY_METRICS_STORAGE_KEY,
+        String(config.enableQualityMetrics ?? false)
+      );
+      await AsyncStorage.setItem(
+        SIGNALING_ENVIRONMENT_STORAGE_KEY,
+        config.environment ?? this._options.environment ?? 'production'
+      );
+
+      if (config.iceServers) {
+        await AsyncStorage.setItem(ICE_SERVERS_STORAGE_KEY, JSON.stringify(config.iceServers));
+      } else {
+        await AsyncStorage.removeItem(ICE_SERVERS_STORAGE_KEY);
+      }
 
       if (config.pushNotificationDeviceToken) {
         await AsyncStorage.setItem('@push_token', config.pushNotificationDeviceToken);

package/src/types/telnyx-sdk.d.ts

@@ -24,7 +24,15 @@ declare module '@telnyx/react-native-voice-sdk' {
     };
   }
 
+  /** A STUN/TURN server for WebRTC peer connections (core `TelnyxIceServer`). */
+  export interface TelnyxIceServer {
+    urls: string;
+    username?: string;
+    credential?: string;
+  }
+
   export interface ClientOptions {
+    environment?: 'production' | 'development';
     login?: string;
     password?: string;
     token?: string;
@@ -38,9 +46,13 @@ declare module '@telnyx/react-native-voice-sdk' {
     enableMissedCallNotifications?: boolean;
     useTrickleIce?: boolean;
     enableCallReports?: boolean;
+    enableQualityMetrics?: boolean;
     callReportInterval?: number;
     callReportLogLevel?: string;
     callReportMaxLogEntries?: number;
+    /** Custom ICE servers (STUN/TURN) for WebRTC peer connections */
+    iceServers?: TelnyxIceServer[];
+    sdkName?: string;
     sdkVersion?: string;
   }
 
@@ -55,6 +67,52 @@ declare module '@telnyx/react-native-voice-sdk' {
     PURGE = 'purge',
   }
 
+  /**
+   * Quality rating derived from the MOS score (same bands as iOS and Android).
+   */
+  export enum CallQualityLevel {
+    EXCELLENT = 'excellent',
+    GOOD = 'good',
+    FAIR = 'fair',
+    POOR = 'poor',
+    BAD = 'bad',
+    UNKNOWN = 'unknown',
+  }
+
+  /** A raw WebRTC stats report, copied as a plain object. */
+  export type QualityStatsRecord = Record<string, unknown>;
+
+  /**
+   * Snapshot of call quality metrics at a single sampling point. Field names
+   * and units match iOS `CallQualityMetrics`.
+   */
+  export interface CallQualityMetrics {
+    /** The call identifier this metrics snapshot belongs to. */
+    callId: string;
+    /** ISO-8601 timestamp of when the metrics were collected. */
+    timestamp: string;
+    /** Jitter in seconds, or null when unavailable. */
+    jitter: number | null;
+    /** Round-trip time in seconds, or null when unavailable. */
+    rtt: number | null;
+    /** Mean Opinion Score (1.0–5.0), or null when it cannot be calculated. */
+    mos: number | null;
+    /** Quality rating derived from `mos`; UNKNOWN when `mos` is null. */
+    quality: CallQualityLevel;
+    /** Instantaneous inbound (remote) audio level, 0.0–1.0. */
+    inboundAudioLevel: number;
+    /** Instantaneous outbound (local) audio level, 0.0–1.0. */
+    outboundAudioLevel: number;
+    /** Raw `inbound-rtp` audio stats, or null when unavailable. */
+    inboundAudio: QualityStatsRecord | null;
+    /** Raw `outbound-rtp` audio stats, or null when unavailable. */
+    outboundAudio: QualityStatsRecord | null;
+    /** Raw `remote-inbound-rtp` audio stats, or null when unavailable. */
+    remoteInboundAudio: QualityStatsRecord | null;
+    /** Raw `remote-outbound-rtp` audio stats, or null when unavailable. */
+    remoteOutboundAudio: QualityStatsRecord | null;
+  }
+
   export class Call extends EventEmitter {
     callId: string;
     state: CallState;
@@ -67,17 +125,24 @@ declare module '@telnyx/react-native-voice-sdk' {
     /**
      * Custom headers received from the WebRTC INVITE message.
      * These headers are passed during call initiation and can contain application-specific information.
-     * Format should be [{"name": "X-Header-Name", "value": "Value"}] where header names must start with "X-".
+     * Format: `[{"name": "X-Header-Name", "value": "Value"}]`; header names must start with `X-`.
      */
     inviteCustomHeaders: { name: string; value: string }[] | null;
 
     /**
      * Custom headers received from the WebRTC ANSWER message.
      * These headers are passed during call acceptance and can contain application-specific information.
-     * Format should be [{"name": "X-Header-Name", "value": "Value"}] where header names must start with "X-".
+     * Format: `[{"name": "X-Header-Name", "value": "Value"}]`; header names must start with `X-`.
      */
     answerCustomHeaders: { name: string; value: string }[] | null;
 
+    /**
+     * Callback invoked with each call quality metrics snapshot (every 200 ms by
+     * default) while collection is active. Snapshots are also emitted as the
+     * `telnyx.call.qualityMetrics` event.
+     */
+    onQualityMetrics: ((metrics: CallQualityMetrics) => void) | null;
+
     constructor(options: any);
 
     answer(customHeaders?: { name: string; value: string }[]): Promise<void>;