rns-nativecall 1.1.1 → 1.1.2

package/README.md

@@ -130,32 +130,31 @@ export default function App() {
 ### 📖 API Reference
 # rns-nativecall API Reference
 
-| Method | Platform | Description |
-| :--- | :--- | :--- |
-| **registerHeadlessTask(callback)** | Android | Registers background logic. `eventType` is `INCOMING_CALL` or `BUSY`. |
-| **checkOverlayPermission()** | Android | Returns true if the app can draw over other apps (Required for Android Lockscreen). |
-| **requestOverlayPermission()** | Android | Opens System Settings to let the user enable "Draw over other apps". |
-| **displayCall(uuid, name, type)** | All | Shows the native call UI (Standard Notification on Android / CallKit on iOS). |
-| **checkCallValidity(uuid)** | All | Returns boolean values for `isValid` and `isCanceled`. |
-| **stopForegroundService()** | Android | Stops the ongoing service and clears the persistent notification/pill. |
-| **destroyNativeCallUI(uuid)** | All | Dismisses the native call interface and stops the ringtone. |
-| **getInitialCallData()** | All | Returns call data if the app was launched by clicking `Answer` from a killed state. |
-| **subscribe(onAccept, onReject)** | All | Listens for native button presses (Answer/End). |
+| Method                       | Platform    | Description                                                                           |
+|:-----------------------------|:------------|:--------------------------------------------------------------------------------------|
+| checkFullScreenPermission()  | Android 14+ | Returns true if the app is allowed to show calls over the lockscreen (FSI).           |
+| openFullScreenSettings()     | Android 14+ | Deep-links the user to the specific system page to enable Full-Screen Intent.         |
+| checkOverlayPermission()     | Android     | Returns true if the app can draw over other apps (Overlay/Draw over apps).            |
+| requestOverlayPermission()   | Android     | Opens System Settings to let the user enable "Draw over other apps".                  |
+| displayCall(uuid, name, type)| All         | Launches the native call UI (CallStyle on Android / CallKit on iOS).                  |
+| checkCallValidity(uuid)      | All         | Returns boolean values for `isValid` and `isCanceled` to prevent "ghost" calls.        |
+| checkCallStatus(uuid)        | All         | Detailed check of a call's status; useful for determining if UI should remain active. |
+| reportRemoteEnded(uuid, res) | All         | Notifies the native side that the caller hung up (prevents infinite ringing).         |
+| destroyNativeCallUI(uuid)    | All         | Forcefully dismisses the native call interface and stops the ringtone immediately.    |
+| getInitialCallData()         | All         | Returns call data if the app was launched by clicking "Answer" from a killed state.   |
+| subscribe(onAccept, onReject)| All         | Listens for native button presses (Answer/End/Failed) and returns a cleanup function. |
 
 ---
 
 # Implementation Notes
 
-1. Android Persistence:
-Because this library uses a Foreground Service on Android, the notification will persist and show a "Call Pill" in the status bar. To remove this after the call ends or connects, you MUST call 'CallHandler.stopForegroundService()'.
-
-2. Android Overlay:
+1. Android Overlay:
 For your React Native call screen to show up when the phone is locked, the user must grant the "Overlay Permission". Use 'checkOverlayPermission()' and 'requestOverlayPermission()' during your app's onboarding or call initiation.
 
-3. iOS CallKit:
+2. iOS CallKit:
 On iOS, 'displayCall' uses the native system CallKit UI. This works automatically in the background and on the lockscreen without extra overlay permissions.
 
-4. Single Call Gate:
+3. Single Call Gate:
 The library automatically prevents multiple overlapping native UIs. If a call is already active, subsequent calls will trigger the 'BUSY' event in your Headless Task.
 ---
 

package/android/src/main/java/com/rnsnativecall/CallModule.kt

@@ -61,7 +61,6 @@ class CallModule(
         }
     }
 
-    // Inside your CallModule class
     @ReactMethod
     fun checkOverlayPermission(promise: Promise) {
         if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
@@ -71,6 +70,16 @@ class CallModule(
         }
     }
 
+    @ReactMethod
+    fun reportRemoteEnded(
+        uuid: String,
+        reason: String,
+        promise: Promise,
+    ) {
+        NativeCallManager.dismissIncomingCall(reactApplicationContext, uuid)
+        promise.resolve(true)
+    }
+
     @ReactMethod
     fun requestOverlayPermission() {
         if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
@@ -86,10 +95,39 @@ class CallModule(
         }
     }
 
-    /**
-     * Combined Validity Check:
-     * Used by Headless Task to see if it should proceed with the UI.
-     */
+    @ReactMethod
+    fun checkFullScreenIntentPermission(promise: Promise) {
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
+            val notificationManager = reactApplicationContext.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
+            promise.resolve(notificationManager.canUseFullScreenIntent())
+        } else {
+            // Automatically true for Android 13 and below
+            promise.resolve(true)
+        }
+    }
+
+    @ReactMethod
+    fun openFullScreenIntentSettings() {
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
+            try {
+                val intent =
+                    Intent(Settings.ACTION_MANAGE_APP_USE_FULL_SCREEN_INTENT).apply {
+                        data = Uri.fromParts("package", reactApplicationContext.packageName, null)
+                        addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
+                    }
+                reactApplicationContext.startActivity(intent)
+            } catch (e: Exception) {
+                // Fallback for some OEM skins that might not support the direct intent
+                val intent =
+                    Intent(Settings.ACTION_APPLICATION_DETAILS_SETTINGS).apply {
+                        data = Uri.fromParts("package", reactApplicationContext.packageName, null)
+                        addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
+                    }
+                reactApplicationContext.startActivity(intent)
+            }
+        }
+    }
+
     @ReactMethod
     fun checkCallValidity(
         uuid: String,
@@ -107,22 +145,6 @@ class CallModule(
         promise.resolve(map)
     }
 
-    @ReactMethod
-    fun stopForegroundService(promise: Promise) {
-        try {
-            // Using the current react context to stop the service
-            val intent = Intent(reactApplicationContext, CallForegroundService::class.java)
-            reactApplicationContext.stopService(intent)
-            promise.resolve(true)
-        } catch (e: Exception) {
-            promise.reject("SERVICE_STOP_ERROR", e.message)
-        }
-    }
-
-    /**
-     * General Status Check:
-     * Useful for checking if the UI is still relevant.
-     */
     @ReactMethod
     fun checkCallStatus(
         uuid: String,

package/index.d.ts

@@ -48,7 +48,7 @@ export interface CallHandlerType {
     /**
      * Registers the background "Headless" task.
      * This is the bridge between a Native push notification and your React Native UI.
-     * * @param callback Async function receiving call data and the event type.
+     * @param callback Async function receiving call data and the event type.
      */
     registerHeadlessTask(
         callback: (data: CallData, eventType: CallEventType) => Promise<void>
@@ -57,7 +57,7 @@ export interface CallHandlerType {
     /**
      * Displays the full-screen Native Incoming Call UI.
      * Usually called inside registerHeadlessTask after validating the call.
-     * * @param uuid The unique call ID.
+     * @param uuid The unique call ID.
      * @param name Name to display on the call screen.
      * @param callType Defaults to 'audio'.
      * @returns Promise resolving to true if the UI was successfully launched.
@@ -65,7 +65,7 @@ export interface CallHandlerType {
     displayCall(
         uuid: string,
         name: string,
-        callType: 'audio' | 'video',
+        callType?: 'audio' | 'video',
     ): Promise<boolean>;
 
     /** * Checks if a call is still valid and has not been canceled.
@@ -78,12 +78,36 @@ export interface CallHandlerType {
      */
     checkCallStatus(uuid: string): Promise<CallStatus>;
 
-    requestOverlayPermission(): Promise<boolean>;
+    /**
+     * [Android 14+] Checks if the user has granted the special "Full Screen Intent" permission.
+     * This is required for the call to show over the lockscreen.
+     */
+    checkFullScreenPermission(): Promise<boolean>;
 
-    reportRemoteEnded(uuid: string, reason: number): void;
+    /**
+     * [Android 14+] Opens the specific system settings page for the user to 
+     * manually enable "Full Screen Intent" if it was revoked.
+     */
+    openFullScreenSettings(): void;
 
+    /**
+     * Checks if the app has permission to draw over other apps (Overlay).
+     * Necessary for showing the "Pill" or answer buttons while the phone is unlocked.
+     */
     checkOverlayPermission(): Promise<boolean>;
 
+    /**
+     * Opens system settings to request the "Draw over other apps" (Overlay) permission.
+     */
+    requestOverlayPermission(): void;
+
+    /**
+     * Reports to the native side that the remote party has terminated the call.
+     * @param uuid The unique call ID.
+     * @param reason Custom string reason (e.g., "RemoteEnded", "TimedOut").
+     */
+    reportRemoteEnded(uuid: string, reason?: string): Promise<void>;
+
     /**
      * Forcefully dismisses the native call UI, stops the ringtone, and clears state.
      * Use this when the call is hung up or timed out.
@@ -105,7 +129,7 @@ export interface CallHandlerType {
 
     /**
      * Subscribes to user interactions on the Native Call UI.
-     * * @param onAccept Callback when user presses the Answer button.
+     * @param onAccept Callback when user presses the Answer button.
      * @param onReject Callback when user presses the Decline button.
      * @param onFailed Callback for system errors (optional).
      * @returns A cleanup function to unsubscribe.

package/index.js

@@ -2,12 +2,18 @@ import {
     NativeModules,
     NativeEventEmitter,
     AppRegistry,
+    Platform,
 } from 'react-native';
 
 const { CallModule } = NativeModules;
 const callEventEmitter = CallModule ? new NativeEventEmitter(CallModule) : null;
 
 export const CallHandler = {
+    /**
+     * REGISTER HEADLESS TASK
+     * This is the "Engine" that listens for incoming push notifications 
+     * while the app is killed or in the background.
+     */
     registerHeadlessTask: (onAction) => {
         AppRegistry.registerHeadlessTask('ColdStartCallTask', () => async (data) => {
             const { callUuid, isBusySignal } = data;
@@ -19,64 +25,81 @@ export const CallHandler = {
                     return;
                 }
 
-                // CallModule.checkCallValidity is now accessible via the native bridge
+                // Check if the call is still valid before showing UI
                 const status = await CallModule.checkCallValidity(uuid);
                 if (!status.isValid) {
                     if (onAction) await onAction(data, 'ABORTED_CALL');
                     return;
                 }
 
-                if (onAction) {
-                    await onAction(data, 'INCOMING_CALL');
-                }
+                if (onAction) await onAction(data, 'INCOMING_CALL');
             } catch (error) {
                 console.error('[RNSNativeCall] Headless Task Error:', error);
             }
         });
     },
 
-    // --- Added missing bridge methods ---
-    checkCallValidity: async (uuid) => {
-        if (!CallModule?.checkCallValidity) return { isValid: false, isCanceled: true };
-        return await CallModule.checkCallValidity(uuid.toLowerCase().trim());
-    },
-
-    checkCallStatus: async (uuid) => {
-        if (!CallModule?.checkCallStatus) return { isCanceled: true, isActive: false, shouldDisplay: false };
-        return await CallModule.checkCallStatus(uuid.toLowerCase().trim());
-    },
-    // ------------------------------------
+    // --- PERMISSION HEALTH CHECKS ---
 
-    reportRemoteEnded: async (uuid, endReason) => {
-        if (!CallModule?.reportRemoteEnded) return;
-        await CallModule.reportRemoteEnded(uuid.toLowerCase().trim(), endReason);
+    checkFullScreenPermission: async () => {
+        if (Platform.OS !== 'android' || !CallModule?.checkFullScreenIntentPermission) return true;
+        return await CallModule.checkFullScreenIntentPermission();
     },
 
-    requestOverlayPermission: async () => {
-        if (!CallModule?.requestOverlayPermission) return false;
-        return await CallModule.requestOverlayPermission();
+    openFullScreenSettings: () => {
+        if (Platform.OS === 'android' && CallModule?.openFullScreenIntentSettings) {
+            CallModule.openFullScreenIntentSettings();
+        }
     },
 
     checkOverlayPermission: async () => {
-        if (!CallModule?.checkOverlayPermission) return false;
+        if (Platform.OS !== 'android' || !CallModule?.checkOverlayPermission) return true;
         return await CallModule.checkOverlayPermission();
     },
 
+    requestOverlayPermission: () => {
+        if (Platform.OS === 'android' && CallModule?.requestOverlayPermission) {
+            CallModule.requestOverlayPermission();
+        }
+    },
+
+    // --- CALL LIFECYCLE ACTIONS ---
+
     displayCall: async (uuid, name, callType = "audio") => {
         if (!CallModule) return false;
         return await CallModule.displayIncomingCall(uuid.toLowerCase().trim(), name, callType);
     },
 
+    /** Stops the UI and the Foreground Service */
+    destroyNativeCallUI: (uuid) => {
+        if (CallModule?.endNativeCall) {
+            CallModule.endNativeCall(uuid.toLowerCase().trim());
+        }
+    },
+
+    /** Reports to the native side that the other person hung up */
+    reportRemoteEnded: async (uuid, endReason = "RemoteEnded") => {
+        if (CallModule?.reportRemoteEnded) {
+            await CallModule.reportRemoteEnded(uuid.toLowerCase().trim(), endReason);
+        }
+    },
+
     stopForegroundService: async () => {
         if (CallModule?.stopForegroundService) {
             await CallModule.stopForegroundService();
         }
     },
 
-    destroyNativeCallUI: (uuid) => {
-        if (CallModule?.endNativeCall) {
-            CallModule.endNativeCall(uuid.toLowerCase().trim());
-        }
+    // --- STATE VERIFICATION ---
+
+    checkCallValidity: async (uuid) => {
+        if (!CallModule?.checkCallValidity) return { isValid: false, isCanceled: true };
+        return await CallModule.checkCallValidity(uuid.toLowerCase().trim());
+    },
+
+    checkCallStatus: async (uuid) => {
+        if (!CallModule?.checkCallStatus) return { isCanceled: true, isActive: false, shouldDisplay: false };
+        return await CallModule.checkCallStatus(uuid.toLowerCase().trim());
     },
 
     getInitialCallData: async () => {
@@ -84,6 +107,8 @@ export const CallHandler = {
         return await CallModule.getInitialCallData();
     },
 
+    // --- EVENT SUBSCRIPTION ---
+
     subscribe: (onAccept, onReject, onFailed) => {
         if (!callEventEmitter) return () => { };
         const subs = [

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rns-nativecall",
-    "version": "1.1.1",
+    "version": "1.1.2",
     "description": "High-performance React Native module for handling native VoIP call UI on Android and iOS.",
     "main": "index.js",
     "types": "index.d.ts",