@stream-io/react-native-callingx 0.1.1-beta.0 → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+This file was generated using [@jscutlery/semver](https://github.com/jscutlery/semver).
+
+## [0.1.1](https://github.com/GetStream/stream-video-js/compare/@stream-io/react-native-callingx-0.1.0...@stream-io/react-native-callingx-0.1.1) (2026-04-09)
+
+### Bug Fixes
+
+- callingx docs update ([#2195](https://github.com/GetStream/stream-video-js/issues/2195)) ([7a6b632](https://github.com/GetStream/stream-video-js/commit/7a6b632270ec1187236a0e4e5c5396a98a20fd16))
+
+## 0.1.0 (2026-04-09)
+
+### Features
+
+- callkit/telecom integration ([#2028](https://github.com/GetStream/stream-video-js/issues/2028)) ([d579acd](https://github.com/GetStream/stream-video-js/commit/d579acd1975fb4945e40452b27e372694c737628))

package/README.md

@@ -1,395 +1,83 @@
-# react-native-callingx
+# @stream-io/react-native-callingx
 
-A React Native Turbo Module for seamless native calling integration. This library provides a unified API to integrate with **CallKit** on iOS and the **Telecom/ConnectionService** API on Android, enabling your app to display system-level calling UI and interact with native call controls.
+React Native native-calling bridge for:
 
-## Features
+- iOS CallKit
+- Android Telecom/ConnectionService
 
-- 📞 **Incoming call UI** — Display native incoming call screens (even when the app is killed)
-- 📲 **Outgoing call registration** — Register outgoing calls with the system
-- 🎛️ **Call controls** — Mute, hold, end calls with native system integration
-- 🔔 **Custom notifications** — Configurable Android notification channels
-- ⚡ **Turbo Module** — Built with the New Architecture for optimal performance
-- 📱 **Background support** — Handle calls when the app is backgrounded or killed
-
-## Requirements
-
-- React Native 0.73+ (New Architecture / Turbo Modules)
-- iOS 13.0+
-- Android API 26+ (Android 8.0 Oreo)
-
-## Installation
+## Install
 
 ```sh
-npm install @stream-io/react-native-callingx
-# or
 yarn add @stream-io/react-native-callingx
 ```
 
-### iOS Setup
-
-1. Add the required background modes to your `Info.plist`:
-
-```xml
-<key>UIBackgroundModes</key>
-<array>
-  <string>voip</string>
-  <string>audio</string>
-</array>
-```
-
-2. Run pod install:
+Then run iOS pods:
 
 ```sh
 cd ios && pod install
 ```
 
-3. For VoIP push notifications, configure your `AppDelegate` to report incoming calls:
-
-```objc
-#import <Callingx/CallingxPublic.h>
-
-- (void)pushRegistry:(PKPushRegistry *)registry
-didReceiveIncomingPushWithPayload:(PKPushPayload *)payload
-             forType:(PKPushType)type
-withCompletionHandler:(void (^)(void))completion {
-
-    // Extract call information from payload
-    NSString *callId = payload.dictionaryPayload[@"call_id"];
-    NSString *callerName = payload.dictionaryPayload[@"caller_name"];
-    NSString *handle = payload.dictionaryPayload[@"handle"];
-    BOOL hasVideo = [payload.dictionaryPayload[@"has_video"] boolValue];
-
-    [Callingx reportNewIncomingCall:callId
-                             handle:handle
-                         handleType:@"generic"
-                           hasVideo:hasVideo
-                localizedCallerName:callerName
-                    supportsHolding:YES
-                       supportsDTMF:NO
-                   supportsGrouping:NO
-                 supportsUngrouping:NO
-                            payload:payload.dictionaryPayload
-              withCompletionHandler:completion];
-}
-```
-
-### Android Setup
+## Quick start
 
-## Usage
+```ts
+import { CallingxModule } from '@stream-io/react-native-callingx';
 
-### Setup
-
-Initialize the module with platform-specific configuration:
-
-```typescript
-import { CallingxModule } from 'react-native-callingx';
-
-// Setup must be called before any other method
 CallingxModule.setup({
   ios: {
-    appName: 'My App',
     supportsVideo: true,
-    maximumCallsPerCallGroup: 1,
-    maximumCallGroups: 1,
-    handleType: 'generic', // 'generic' | 'number' | 'phone' | 'email'
+    callsHistory: false,
   },
   android: {
     incomingChannel: {
-      id: 'incoming_calls',
-      name: 'Incoming Calls',
-      sound: 'ringtone', // optional custom sound
-      vibration: true,
+      id: 'incoming_calls_channel',
+      name: 'Incoming calls',
     },
-    outgoingChannel: {
-      id: 'ongoing_calls',
-      name: 'Ongoing Calls',
-    },
-    // Optional: transform display text
-    titleTransformer: (name) => `Call from ${name}`,
-    subtitleTransformer: (phoneNumber) => phoneNumber,
   },
 });
-```
-
-### Request Permissions
 
-Before displaying calls, request the required permissions:
-
-```typescript
-const permissions = await CallingxModule.requestPermissions();
-console.log('Audio permission:', permissions.recordAudio);
-console.log('Notification permission:', permissions.postNotifications);
-```
-
-### Display Incoming Call
-
-Show the native incoming call UI:
-
-```typescript
 await CallingxModule.displayIncomingCall(
-  'unique-call-id',
-  '+1234567890', // phone number / handle
-  'John Doe', // caller name
-  true, // has video
-);
-```
-
-### Start Outgoing Call
-
-Register an outgoing call with the system:
-
-```typescript
-await CallingxModule.startCall(
-  'unique-call-id',
-  '+1234567890',
+  'call-id',
+  '+123456789',
   'John Doe',
-  false, // audio only
+  true,
 );
 ```
 
-### Answer Call
-
-Answer an incoming call programmatically:
-
-```typescript
-await CallingxModule.answerIncomingCall('unique-call-id');
-```
-
-### Activate Call
-
-Mark a call as active (connected):
-
-```typescript
-await CallingxModule.setCurrentCallActive('unique-call-id');
-```
-
-### End Call
-
-End a call with a specific reason:
-
-```typescript
-import type { EndCallReason } from 'react-native-callingx';
-
-// Available reasons:
-//   'local' | 'remote' | 'rejected' | 'busy' | 'answeredElsewhere' |
-//   'missed' | 'error' | 'canceled' | 'restricted' | 'unknown'
-await CallingxModule.endCallWithReason('unique-call-id', 'remote');
-```
-
-### Mute/Unmute
-
-Toggle call mute state:
-
-```typescript
-await CallingxModule.setMutedCall('unique-call-id', true); // mute
-await CallingxModule.setMutedCall('unique-call-id', false); // unmute
-```
-
-### Hold/Unhold
-
-Toggle call hold state:
-
-```typescript
-await CallingxModule.setOnHoldCall('unique-call-id', true); // hold
-await CallingxModule.setOnHoldCall('unique-call-id', false); // unhold
-```
-
-### Update Display
-
-Update the caller information during a call:
-
-```typescript
-await CallingxModule.updateDisplay(
-  'unique-call-id',
-  '+1234567890',
-  'Updated Name',
-);
-```
-
-### Event Listeners
-
-Subscribe to call events:
-
-```typescript
-import { CallingxModule } from 'react-native-callingx';
-import type { EventName } from 'react-native-callingx';
-
-// Answer event - user answered from system UI
-const answerSubscription = CallingxModule.addEventListener(
-  'answerCall',
-  (params) => {
-    console.log('Call answered:', params.callId);
-  },
-);
-
-// End event - call ended
-const endSubscription = CallingxModule.addEventListener('endCall', (params) => {
-  console.log('Call ended:', params.callId, 'Cause:', params.cause);
-});
-
-// Hold toggle event
-const holdSubscription = CallingxModule.addEventListener(
-  'didToggleHoldCallAction',
-  (params) => {
-    console.log('Hold toggled:', params.callId, 'On hold:', params.hold);
-  },
-);
-
-// Mute toggle event
-const muteSubscription = CallingxModule.addEventListener(
-  'didPerformSetMutedCallAction',
-  (params) => {
-    console.log('Mute toggled:', params.callId, 'Muted:', params.muted);
-  },
-);
-
-// Start call action (outgoing call initiated from system)
-const startSubscription = CallingxModule.addEventListener(
-  'didReceiveStartCallAction',
-  (params) => {
-    console.log('Start call action:', params.callId);
-  },
-);
-
-// Clean up when done
-answerSubscription.remove();
-endSubscription.remove();
-// ... remove other subscriptions
-```
-
-### Handle Initial Events
-
-When the app is launched from a killed state by a call action, retrieve queued events:
-
-```typescript
-// Get events that occurred before the module was initialized
-const initialEvents = CallingxModule.getInitialEvents();
-initialEvents.forEach((event) => {
-  console.log('Initial event:', event.eventName, event.params);
-});
-
-// Clear initial events after processing
-await CallingxModule.clearInitialEvents();
-```
-
-### Background Tasks (Android)
-
-Run background tasks for call-related operations:
-
-```typescript
-// Start a managed background task
-await CallingxModule.startBackgroundTask(async (taskData, stopTask) => {
-  try {
-    // Perform background work (e.g., connect to call server)
-    await connectToCallServer();
-  } finally {
-    stopTask(); // Always call when done
-  }
-});
-
-// Or stop manually
-await CallingxModule.stopBackgroundTask();
-```
-
-## API Reference
-
-### CallingxModule
-
-| Method                                                           | Description                                          |
-| ---------------------------------------------------------------- | ---------------------------------------------------- |
-| `setup(options)`                                                 | Initialize the module with platform-specific options |
-| `requestPermissions()`                                           | Request required permissions (audio, notifications)  |
-| `checkPermissions()`                                             | Check current permission status                      |
-| `displayIncomingCall(callId, phoneNumber, callerName, hasVideo)` | Display incoming call UI                             |
-| `answerIncomingCall(callId)`                                     | Answer an incoming call                              |
-| `startCall(callId, phoneNumber, callerName, hasVideo)`           | Register an outgoing call                            |
-| `setCurrentCallActive(callId)`                                   | Mark call as active/connected                        |
-| `updateDisplay(callId, phoneNumber, callerName)`                 | Update caller display info                           |
-| `endCallWithReason(callId, reason)`                              | End call with specified reason                       |
-| `setMutedCall(callId, isMuted)`                                  | Toggle call mute state                               |
-| `setOnHoldCall(callId, isOnHold)`                                | Toggle call hold state                               |
-| `addEventListener(eventName, callback)`                          | Subscribe to call events                             |
-| `getInitialEvents()`                                             | Get queued events from app launch                    |
-| `clearInitialEvents()`                                           | Clear queued initial events                          |
-| `startBackgroundTask(taskProvider)`                              | Start Android background task                        |
-| `stopBackgroundTask()`                                           | Stop Android background task                         |
-| `log(message, level)`                                            | Log message to native console                        |
-
-### Events
-
-| Event                          | Parameters          | Description                       |
-| ------------------------------ | ------------------- | --------------------------------- |
-| `answerCall`                   | `{ callId }`        | User answered call from system UI |
-| `endCall`                      | `{ callId, cause }` | Call ended                        |
-| `didToggleHoldCallAction`      | `{ callId, hold }`  | Hold state changed                |
-| `didPerformSetMutedCallAction` | `{ callId, muted }` | Mute state changed                |
-| `didReceiveStartCallAction`    | `{ callId }`        | Outgoing call action received     |
-
-### Types
-
-```typescript
-type EndCallReason =
-  | 'local' // Call ended by the local user (e.g., hanging up)
-  | 'remote' // Call ended by the remote party, or outgoing not answered
-  | 'rejected' // Call was rejected/declined
-  | 'busy' // Remote party was busy
-  | 'answeredElsewhere' // Answered on another device
-  | 'missed' // No response to an incoming call
-  | 'error' // Call failed due to an error (e.g., network issue)
-  | 'canceled' // Call canceled before the remote party could answer
-  | 'restricted' // Call restricted (e.g., airplane mode)
-  | 'unknown'; // Unknown or unspecified disconnect reason
-
-type CallingExpiOSOptions = {
-  appName: string;
-  supportsVideo?: boolean;
-  maximumCallsPerCallGroup?: number;
-  maximumCallGroups?: number;
-  handleType?: 'generic' | 'number' | 'phone' | 'email';
-};
-
-type CallingExpAndroidOptions = {
-  incomingChannel?: {
-    id: string;
-    name: string;
-    sound?: string;
-    vibration?: boolean;
-  };
-  outgoingChannel?: {
-    id: string;
-    name: string;
-    sound?: string;
-    vibration?: boolean;
-  };
-};
-
-type PermissionsResult = {
-  recordAudio: boolean;
-  postNotifications: boolean;
-};
-```
-
-## Troubleshooting
-
-### iOS
-
-- **Incoming call not showing**: Ensure `voip` background mode is enabled and VoIP push certificate is configured
-- **CallKit errors**: Check that `appName` is set in setup options
-- **Audio issues**: The module automatically configures the audio session, but ensure no conflicts with other audio libraries
+## Main APIs
 
-### Android
+- `setup(options)` - required before any call action.
+- `displayIncomingCall(callId, phoneNumber, callerName, hasVideo)`.
+- `startCall(callId, phoneNumber, callerName, hasVideo)`.
+- `setCurrentCallActive(callId)`.
+- `updateDisplay(callId, phoneNumber, callerName, incoming)`.
+- `endCallWithReason(callId, reason)`.
+- `setMutedCall(callId, isMuted)`.
+- `setOnHoldCall(callId, isOnHold)`.
+- `addEventListener(eventName, callback)`.
+- `getInitialEvents()` and `getInitialVoipEvents()`.
+- `registerBackgroundTask(taskProvider)` / `startBackgroundTask()` / `stopBackgroundTask()` (Android).
 
-- **Notifications not showing**: Check POST_NOTIFICATIONS permission on Android 13+
-- **Call not answered on tap**: Ensure `handleCallingIntent` is called in both `onCreate` and `onNewIntent` in your MainActivity
+## Event names
 
-## Contributing
+Call events:
 
-See the [contributing guide](CONTRIBUTING.md) to learn how to contribute to the repository and the development workflow.
+- `answerCall`
+- `endCall`
+- `didDisplayIncomingCall`
+- `didToggleHoldCallAction`
+- `didPerformSetMutedCallAction`
+- `didChangeAudioRoute`
+- `didReceiveStartCallAction`
+- `didActivateAudioSession`
+- `didDeactivateAudioSession`
 
-## License
+VoIP events:
 
-MIT
+- `voipNotificationsRegistered`
+- `voipNotificationReceived`
 
----
+## Notes
 
-Made with [create-react-native-library](https://github.com/callstack/react-native-builder-bob)
+- Import from `@stream-io/react-native-callingx`.
+- iOS-only helpers: `registerVoipToken`, `fulfillAnswerCallAction`, `fulfillEndCallAction`.
+- Android helpers: `canPostNotifications`, `isOngoingCallsEnabled`.

package/android/src/main/java/io/getstream/rn/callingx/CallRegistrationStore.kt

@@ -2,9 +2,11 @@ package io.getstream.rn.callingx
 
 import android.os.Handler
 import android.os.Looper
-import android.util.Log
 import com.facebook.react.bridge.Promise
+import io.getstream.rn.callingx.model.CallAction
+import java.util.Collections
 import java.util.concurrent.ConcurrentHashMap
+import kotlin.collections.emptyList
 
 object CallRegistrationStore {
 
@@ -13,10 +15,8 @@ object CallRegistrationStore {
 
     private val trackedCallIds: MutableSet<String> = ConcurrentHashMap.newKeySet()
 
-    /** Pending disconnect cause code (android.telecom.DisconnectCause code) per callId. */
-    private val pendingDisconnectCauseByCallId = ConcurrentHashMap<String, Int>()
-    private val pendingAnswerByCallId = ConcurrentHashMap<String, Boolean>()
-    private val pendingMuteByCallId = ConcurrentHashMap<String, Boolean>()
+    /** Pending actions per callId, queued until the call is registered in Telecom. */
+    private val pendingActionsByCallId = ConcurrentHashMap<String, MutableList<CallAction>>()
 
     // Per-callId pending promises for displayIncomingCall awaiting CALL_REGISTERED_INCOMING_ACTION
     private val pendingPromises = mutableMapOf<String, Promise>()
@@ -24,7 +24,10 @@ object CallRegistrationStore {
     private val mainHandler = Handler(Looper.getMainLooper())
 
     fun trackCallRegistration(callId: String, promise: Promise?) {
-        debugLog(TAG, "[store] trackCallRegistration: Tracking call registration for callId: $callId")
+        debugLog(
+                TAG,
+                "[store] trackCallRegistration: Tracking call registration for callId: $callId"
+        )
         trackedCallIds.add(callId)
 
         if (promise == null) return
@@ -38,10 +41,9 @@ object CallRegistrationStore {
 
             val timeoutRunnable = Runnable {
                 synchronized(pendingPromises) {
-                    pendingPromises.remove(callId)?.reject(
-                        "TIMEOUT",
-                        "Timed out waiting for call registration: $callId"
-                    )
+                    pendingPromises
+                            .remove(callId)
+                            ?.reject("TIMEOUT", "Timed out waiting for call registration: $callId")
                     pendingTimeouts.remove(callId)
                     trackedCallIds.remove(callId)
                 }
@@ -60,24 +62,25 @@ object CallRegistrationStore {
 
     fun onRegistrationFailed(callId: String) {
         reportRegistrationFail(
-            callId,
-            "REGISTRATION_FAILED",
-            "Failed to register call with telecom: $callId",
-            null
+                callId,
+                "REGISTRATION_FAILED",
+                "Failed to register call with telecom: $callId",
+                null
         )
     }
 
     fun reportRegistrationFail(
-        callId: String,
-        code: String,
-        message: String?,
-        throwable: Throwable?
+            callId: String,
+            code: String,
+            message: String?,
+            throwable: Throwable?
     ) {
         trackedCallIds.remove(callId)
 
         synchronized(pendingPromises) {
             pendingTimeouts.remove(callId)?.let { mainHandler.removeCallbacks(it) }
             val promise = pendingPromises.remove(callId)
+            pendingActionsByCallId.remove(callId)
             if (promise != null) {
                 if (throwable != null) {
                     promise.reject(code, message, throwable)
@@ -111,50 +114,23 @@ object CallRegistrationStore {
     }
 
     /**
-     * Records that a disconnect was requested for this call before it was registered.
-     * When the call becomes registered, the service should take this and run the disconnect action.
+     * Queues an action for a call that is not yet registered.
+     * Pending actions are drained and executed once registration completes.
      */
-    fun setPendingDisconnect(callId: String, disconnectCauseCode: Int) {
-        debugLog(TAG, "[store] setPendingDisconnect: callId=$callId causeCode=$disconnectCauseCode")
-        pendingDisconnectCauseByCallId[callId] = disconnectCauseCode
-    }
-
-    fun setPendingAnswer(callId: String, isAudioCall: Boolean) {
-        debugLog(TAG, "[store] setPendingAnswer: callId=$callId")
-        pendingAnswerByCallId[callId] = isAudioCall
-    }
-
-    fun setPendingMute(callId: String, isMute: Boolean) {
-        debugLog(TAG, "[store] setPendingMute: callId=$callId isMute=$isMute")
-        pendingMuteByCallId[callId] = isMute
+    fun addPendingAction(callId: String, action: CallAction) {
+        debugLog(TAG, "[store] addPendingAction: callId=$callId action=${action::class.simpleName}")
+        pendingActionsByCallId
+                .computeIfAbsent(callId) { Collections.synchronizedList(mutableListOf()) }
+                .add(action)
     }
 
     /**
-     * Returns and removes the pending disconnect cause code for this call, if any.
-     * Used when the call has just become registered so the service can run the disconnect action.
+     * Returns and removes all queued actions for this call.
+     * Used once a call is registered so the service can replay pending actions.
      */
-    fun takePendingDisconnect(callId: String): Int? {
-        val code = pendingDisconnectCauseByCallId.remove(callId)
-        if (code != null) {
-            debugLog(TAG, "[store] takePendingDisconnect: callId=$callId causeCode=$code")
-        }
-        return code
-    }
-
-    fun takePendingAnswer(callId: String): Boolean? {
-        val isAudioCall = pendingAnswerByCallId.remove(callId)
-        if (isAudioCall != null) {
-            debugLog(TAG, "[store] takePendingAnswer: callId=$callId isAudioCall=$isAudioCall")
-        }
-        return isAudioCall
-    }
-
-    fun takePendingMute(callId: String): Boolean? {
-        val isMute = pendingMuteByCallId.remove(callId)
-        if (isMute != null) {
-            debugLog(TAG, "[store] takePendingMute: callId=$callId isMute=$isMute")
-        }
-        return isMute
+    fun takePendingActions(callId: String): List<CallAction> {
+        val list = pendingActionsByCallId.remove(callId) ?: return emptyList()
+        synchronized(list) { return list.toList() }
     }
 
     fun clearAll() {
@@ -164,13 +140,6 @@ object CallRegistrationStore {
             pendingPromises.clear()
         }
         trackedCallIds.clear()
-        pendingDisconnectCauseByCallId.clear()
-        pendingAnswerByCallId.clear()
-        pendingMuteByCallId.clear()
-    }
-
-    private fun debugLog(tag: String, message: String) {
-        Log.d(tag, message)
+        pendingActionsByCallId.clear()
     }
 }
-