rns-nativecall 0.9.7 → 0.9.9

package/README.md

@@ -49,8 +49,8 @@ CallHandler.registerHeadlessTask(async (data, eventType) => {
 
 AppRegistry.registerComponent('main', () => App);
 ```
-### 2. Handling Events (Index.js/App.js)
-Use the subscribe method to handle user interaction (Accept/Reject) from the native UI.
+## Handling Events (Index.js)
+
 ```javascript
 // Index.js Setup Foreground Listeners
 CallHandler.subscribe(
@@ -79,8 +79,7 @@ CallHandler.subscribe(
 
 ````
 
-## App.js version
-
+## Handling Events (App.js)
 
 ```javascript
 import React, { useEffect } from 'react';
@@ -112,14 +111,129 @@ export default function App() {
 ```
 ---
 ### 📖 API Reference
-| Method | Description |
-| :--- | :--- |
-| **registerHeadlessTask(callback)** | Registers background logic. `eventType` is `'INCOMING_CALL'` or `'BUSY'`. |
-| **displayCall(uuid, name, type)** | Shows the native call UI. Type is `'audio'` or `'video'`. |
-| **destroyNativeCallUI(uuid)** | Dismisses the native call interface. |
-| **getInitialCallData()** | Returns call data if the app was launched by clicking "Answer". |
-| **subscribe(onAccept, onReject)** | Listens for native button presses (Answer/End). |
+# 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). |
+
+---
+
+# 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:
+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:
+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:
+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.
 ---
 
+## FULL Example Use Case
+```javascript
+import React, { useEffect, useState } from 'react';
+import { StyleSheet, Text, View, TouchableOpacity, Alert } from 'react-native';
+import { CallHandler } from 'rns-nativecall';
+
+export default function App() {
+  const [activeCall, setActiveCall] = useState(null);
+
+  useEffect(() => {
+    // 1. Handle app launched from a notification "Answer" click
+    CallHandler.getInitialCallData().then((data) => {
+      if (data && data.default) {
+        console.log("App launched from call:", data.default);
+        setActiveCall(data.default);
+      }
+    });
+
+    // 2. Subscribe to foreground events
+    const unsubscribe = CallHandler.subscribe(
+      (data) => {
+        console.log("Call Accepted:", data.callUuid);
+        setActiveCall(data);
+        // Logic: Open your Video/Audio Call UI here
+      },
+      (data) => {
+        console.log("Call Rejected/Ended:", data.callUuid);
+        setActiveCall(null);
+      }
+    );
+
+    return () => unsubscribe();
+  }, []);
+
+  const startTestCall = async () => {
+    // Android Only: Check for overlay permission to show UI over lockscreen
+    const hasPermission = await CallHandler.checkOverlayPermission();
+    if (!hasPermission) {
+      Alert.alert(
+        "Permission Required",
+        "Please enable 'Draw over other apps' to see calls while the phone is locked.",
+        [
+          { text: "Cancel" },
+          { text: "Settings", onPress: () => CallHandler.requestOverlayPermission() }
+        ]
+      );
+      return;
+    }
+
+    // Trigger the native UI
+    CallHandler.displayCall(
+      "test-uuid-" + Date.now(),
+      "John Doe",
+      "video"
+    );
+  };
+
+  const endCallManually = () => {
+    if (activeCall) {
+      CallHandler.stopForegroundService();
+      setActiveCall(null);
+    }
+  };
+
+  return (
+    <View style={styles.container}>
+      <Text style={styles.title}>RNS Native Call Pro</Text>
+      
+      {activeCall ? (
+        <View style={styles.callBox}>
+          <Text>Active Call with: {activeCall.name}</Text>
+          <TouchableOpacity style={styles.btnEnd} onPress={endCallManually}>
+            <Text style={styles.btnText}>End Call</Text>
+          </TouchableOpacity>
+        </View>
+      ) : (
+        <TouchableOpacity style={styles.btnStart} onPress={startTestCall}>
+          <Text style={styles.btnText}>Simulate Incoming Call</Text>
+        </TouchableOpacity>
+      )}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: { flex: 1, justifyContent: 'center', alignItems: 'center', backgroundColor: '#F5FCFF' },
+  title: { fontSize: 20, fontWeight: 'bold', marginBottom: 20 },
+  callBox: { padding: 20, backgroundColor: '#e1f5fe', borderRadius: 10, alignItems: 'center' },
+  btnStart: { backgroundColor: '#4CAF50', padding: 15, borderRadius: 5 },
+  btnEnd: { backgroundColor: '#F44336', padding: 15, borderRadius: 5, marginTop: 10 },
+  btnText: { color: 'white', fontWeight: 'bold' }
+});
+```
 ## 🛡 License
 ---

package/package.json

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