@kapsula-chat/capacitor-push-calls 1.0.0

package/Package.swift

@@ -0,0 +1,31 @@
+// swift-tools-version: 5.9
+import PackageDescription
+
+let package = Package(
+    name: "CapacitorPushCalls",
+    platforms: [.iOS(.v13)],
+    products: [
+        .library(
+            name: "CapacitorPushCalls",
+            targets: ["CapacitorPushCallsPlugin"])
+    ],
+    dependencies: [
+        .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", branch: "main")
+    ],
+    targets: [
+        .target(
+            name: "CapacitorPushCallsPlugin",
+            dependencies: [
+                .product(name: "Capacitor", package: "capacitor-swift-pm"),
+                .product(name: "Cordova", package: "capacitor-swift-pm")
+            ],
+            path: "ios/Plugin",
+            exclude: ["Plugin.m"],
+            sources: [
+                "CallManager.swift",
+                "CapacitorVoipCallsPlugin.swift"
+            ],
+            publicHeadersPath: "."
+        )
+    ]
+)

package/README.md

@@ -0,0 +1,252 @@
+# Capacitor Push Calls Plugin
+
+`@kapsula-chat/capacitor-push-calls` is a unified Capacitor plugin for:
+- regular push notifications (API compatible in shape with `@capacitor/push-notifications`)
+- VoIP/telephony call handling
+
+Platform behavior:
+- iOS: regular push via APNS registration + VoIP via PushKit + CallKit UI
+- Android: single FCM router service inside this plugin (`type=message|call`) + ConnectionService UI for calls
+
+## Install
+
+```bash
+npm install @kapsula-chat/capacitor-push-calls
+npx cap sync
+```
+
+## Add Plugin To App (iOS + Android)
+
+1. Install and sync:
+```bash
+npm install @kapsula-chat/capacitor-push-calls
+npx cap sync
+```
+2. Open native projects at least once so Capacitor updates plugin wiring:
+```bash
+npx cap open ios
+npx cap open android
+```
+3. iOS:
+- Ensure VoIP background mode is enabled in `Info.plist` (see iOS section below).
+- If you use FCM for regular pushes on iOS, keep your APNs + Firebase setup configured in the app.
+4. Android:
+- Ensure your app is configured for Firebase Messaging (`google-services.json`, Firebase project).
+- Register the phone account once on app startup (recommended):
+
+```kotlin
+import com.capacitor.voipcalls.VoipConnectionService
+
+override fun onCreate(savedInstanceState: Bundle?) {
+    super.onCreate(savedInstanceState)
+    VoipConnectionService.registerPhoneAccount(this)
+}
+```
+
+## Import
+
+```ts
+import { CapacitorPushCalls } from '@kapsula-chat/capacitor-push-calls';
+```
+
+## Push API (regular notifications)
+
+### Register / permissions
+
+```ts
+const permissions = await CapacitorPushCalls.checkPermissions();
+if (permissions.receive !== 'granted') {
+  await CapacitorPushCalls.requestPermissions();
+}
+
+await CapacitorPushCalls.register();
+
+CapacitorPushCalls.addListener('registration', token => {
+  console.log('push token:', token.value);
+  // Send token to backend and bind with authenticated user/device
+});
+
+CapacitorPushCalls.addListener('registrationError', error => {
+  console.error('registration error:', error.error);
+});
+```
+
+### Receive and tap events
+
+```ts
+CapacitorPushCalls.addListener('pushNotificationReceived', notification => {
+  console.log('push received:', notification);
+});
+
+CapacitorPushCalls.addListener('pushNotificationActionPerformed', action => {
+  console.log('push action:', action.actionId, action.notification);
+});
+```
+
+### Delivered notifications and channels
+
+```ts
+const delivered = await CapacitorPushCalls.getDeliveredNotifications();
+await CapacitorPushCalls.removeAllDeliveredNotifications();
+
+await CapacitorPushCalls.createChannel({
+  id: 'messages',
+  name: 'Messages',
+  importance: 4,
+});
+
+const channels = await CapacitorPushCalls.listChannels();
+await CapacitorPushCalls.deleteChannel({ id: 'messages' });
+```
+
+Note: channel APIs are Android-only (iOS returns no-op / empty list).
+
+### Badge count
+
+```ts
+const current = await CapacitorPushCalls.getBadgeCount();
+await CapacitorPushCalls.setBadgeCount({ count: current.count + 1 });
+await CapacitorPushCalls.clearBadgeCount();
+```
+
+## Android Device Registration
+
+Recommended bootstrap flow on Android:
+
+```ts
+const permissions = await CapacitorPushCalls.checkPermissions();
+if (permissions.receive !== 'granted') {
+  await CapacitorPushCalls.requestPermissions();
+}
+
+await CapacitorPushCalls.register();
+
+CapacitorPushCalls.addListener('registration', async ({ value }) => {
+  // Persist FCM token on backend for this device/session
+  await api.registerPushDevice({ token: value, platform: 'android' });
+});
+```
+
+Use the same `registration` flow on iOS for regular push token registration.
+
+## VoIP / calls API
+
+### iOS VoIP registration
+
+```ts
+await CapacitorPushCalls.registerVoipNotifications();
+
+CapacitorPushCalls.addListener('voipPushToken', ({ token }) => {
+  console.log('voip token:', token);
+});
+```
+
+### Start / control calls
+
+```ts
+const { callId } = await CapacitorPushCalls.startCall({
+  handle: '+1234567890',
+  displayName: 'John Doe',
+  handleType: 'phone',
+  video: false,
+});
+
+await CapacitorPushCalls.setMuted({ muted: true });
+await CapacitorPushCalls.setAudioRoute({ route: 'speaker' });
+await CapacitorPushCalls.setCallOnHold({ callId, onHold: true });
+await CapacitorPushCalls.endCall({ callId });
+```
+
+### Call events
+
+```ts
+CapacitorPushCalls.addListener('incomingCall', call => {});
+CapacitorPushCalls.addListener('callStarted', call => {});
+CapacitorPushCalls.addListener('callAnswered', call => {});
+CapacitorPushCalls.addListener('callEnded', call => {});
+CapacitorPushCalls.addListener('callRejected', call => {});
+CapacitorPushCalls.addListener('callHeld', call => {});
+```
+
+## Android FCM routing contract
+
+This plugin owns one `FirebaseMessagingService` and routes by `data.type`.
+
+- `type=call` -> reported as incoming call to system UI
+- anything else (or missing `type`) -> emitted as `pushNotificationReceived`
+
+Example FCM message payloads:
+
+### Message push
+
+```json
+{
+  "data": {
+    "type": "message",
+    "messageId": "msg-123",
+    "chatId": "room-7"
+  },
+  "notification": {
+    "title": "New message",
+    "body": "Hello"
+  }
+}
+```
+
+### Call push
+
+```json
+{
+  "data": {
+    "type": "call",
+    "callId": "call-123",
+    "handle": "+1234567890",
+    "displayName": "John Doe",
+    "handleType": "phone",
+    "video": "false"
+  }
+}
+```
+
+## Foreground Service (Android)
+
+The plugin currently routes FCM and triggers ConnectionService/Call UI, but it does not run a long-lived custom foreground service for your app logic.
+
+Use your own foreground service if you need:
+- long-running signaling/reconnect loops in background,
+- persistent background media/session processing,
+- guaranteed ongoing processing beyond call UI handoff.
+
+Typical split:
+- plugin handles push ingress + system call UI bridge,
+- app service handles long-lived networking/media responsibilities.
+
+## iOS setup notes
+
+Add VoIP background mode in `Info.plist`:
+
+```xml
+<key>UIBackgroundModes</key>
+<array>
+  <string>voip</string>
+</array>
+```
+
+Server side:
+- regular push -> APNS/FCM token from `registration`
+- VoIP call push -> PushKit token from `voipPushToken`
+
+## Test app helper
+
+Use included helper scripts and UI:
+
+```bash
+npm run test:setup
+npm run test:update
+```
+
+The generated test app uses `scripts/test-app-ui.html`.
+
+## API Types
+
+See `/src/definitions.ts` for the complete TypeScript contract.

package/android/build.gradle

@@ -0,0 +1,46 @@
+apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
+
+android {
+    namespace "com.capacitor.voipcalls"
+    compileSdkVersion project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 33
+    defaultConfig {
+        minSdkVersion project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 23
+        targetSdkVersion project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 33
+        versionCode 1
+        versionName "1.0"
+        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
+    }
+    buildTypes {
+        release {
+            minifyEnabled false
+            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
+        }
+    }
+    lintOptions {
+        abortOnError false
+    }
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_17
+        targetCompatibility JavaVersion.VERSION_17
+    }
+    kotlinOptions {
+        jvmTarget = '17'
+    }
+}
+
+repositories {
+    google()
+    mavenCentral()
+}
+
+dependencies {
+    implementation fileTree(dir: 'libs', include: ['*.jar'])
+    implementation project(':capacitor-android')
+    implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
+    implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlinVersion"
+    compileOnly "com.google.firebase:firebase-messaging:24.1.2"
+    testImplementation "junit:junit:$junitVersion"
+    androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
+    androidTestImplementation "androidx.test.espresso:espresso-core:$androidxEspressoCoreVersion"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,31 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    package="com.capacitor.voipcalls">
+
+    <uses-permission android:name="android.permission.RECORD_AUDIO" />
+    <uses-permission android:name="android.permission.CAMERA" />
+    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+    <uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
+    <uses-permission android:name="android.permission.BLUETOOTH" />
+    <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
+    <uses-permission android:name="android.permission.READ_PHONE_STATE" />
+    <uses-permission android:name="android.permission.MANAGE_OWN_CALLS" />
+
+    <application>
+        <service
+            android:name=".VoipConnectionService"
+            android:permission="android.permission.BIND_TELECOM_CONNECTION_SERVICE"
+            android:exported="true">
+            <intent-filter>
+                <action android:name="android.telecom.ConnectionService" />
+            </intent-filter>
+        </service>
+
+        <service
+            android:name=".PushRouterMessagingService"
+            android:exported="false">
+            <intent-filter>
+                <action android:name="com.google.firebase.MESSAGING_EVENT" />
+            </intent-filter>
+        </service>
+    </application>
+</manifest>

package/android/src/main/java/com/capacitor/voipcalls/CallManager.kt

@@ -0,0 +1,213 @@
+package com.capacitor.voipcalls
+
+import android.content.Context
+import android.media.AudioManager
+import android.os.Build
+import android.telecom.*
+import androidx.annotation.RequiresApi
+import com.getcapacitor.JSObject
+
+@RequiresApi(Build.VERSION_CODES.M)
+class CallManager(
+    private val context: Context,
+    private val eventEmitter: ((String, JSObject) -> Unit)? = null
+) {
+    private val telecomManager: TelecomManager? = 
+        context.getSystemService(Context.TELECOM_SERVICE) as? TelecomManager
+    
+    private val activeCalls = mutableMapOf<String, VoipConnection>()
+    
+    data class CallData(
+        val callId: String,
+        val handle: String,
+        val displayName: String,
+        val handleType: String,
+        val video: Boolean,
+        val metadata: JSObject? = null
+    )
+
+    constructor(plugin: CapacitorVoipCallsPlugin) : this(plugin.context, plugin::emitEvent)
+
+    fun startCall(callId: String, handle: String, displayName: String, handleType: String, video: Boolean) {
+        val phoneAccount = VoipConnectionService.getPhoneAccount(context)
+        
+        val extras = android.os.Bundle().apply {
+            putString("callId", callId)
+            putString("handle", handle)
+            putString("displayName", displayName)
+            putString("handleType", handleType)
+            putBoolean("video", video)
+            putBoolean("isOutgoing", true)
+        }
+
+        val uri = android.net.Uri.fromParts("tel", handle, null)
+        val telecomExtras = android.os.Bundle().apply {
+            putParcelable(TelecomManager.EXTRA_PHONE_ACCOUNT_HANDLE, phoneAccount.accountHandle)
+            putInt(TelecomManager.EXTRA_START_CALL_WITH_VIDEO_STATE, 
+                if (video) VideoProfile.STATE_BIDIRECTIONAL else VideoProfile.STATE_AUDIO_ONLY)
+            putBundle(TelecomManager.EXTRA_OUTGOING_CALL_EXTRAS, extras)
+        }
+
+        try {
+            telecomManager?.placeCall(uri, telecomExtras)
+        } catch (e: SecurityException) {
+            notifyError("Failed to place call: ${e.message}")
+        }
+    }
+
+    fun reportIncomingCall(
+        callId: String,
+        handle: String,
+        displayName: String,
+        handleType: String,
+        video: Boolean,
+        metadata: JSObject?
+    ) {
+        val phoneAccount = VoipConnectionService.getPhoneAccount(context)
+        
+        val extras = android.os.Bundle().apply {
+            putString("callId", callId)
+            putString("handle", handle)
+            putString("displayName", displayName)
+            putString("handleType", handleType)
+            putBoolean("video", video)
+            if (metadata != null) {
+                putString("metadata", metadata.toString())
+            }
+        }
+
+        val uri = android.net.Uri.fromParts("tel", handle, null)
+        
+        try {
+            telecomManager?.addNewIncomingCall(phoneAccount.accountHandle, extras)
+            
+            // Notify JavaScript layer
+            val data = JSObject().apply {
+                put("callId", callId)
+                put("handle", handle)
+                put("displayName", displayName)
+                put("handleType", handleType)
+                put("video", video)
+                if (metadata != null) {
+                    put("metadata", metadata)
+                }
+            }
+            eventEmitter?.invoke("incomingCall", data)
+        } catch (e: SecurityException) {
+            notifyError("Failed to report incoming call: ${e.message}")
+        }
+    }
+
+    fun endCall(callId: String) {
+        activeCalls[callId]?.onDisconnect()
+        activeCalls.remove(callId)
+    }
+
+    fun answerCall(callId: String) {
+        activeCalls[callId]?.onAnswer()
+    }
+
+    fun rejectCall(callId: String) {
+        activeCalls[callId]?.onReject()
+        activeCalls.remove(callId)
+    }
+
+    fun setCallOnHold(callId: String, onHold: Boolean) {
+        if (onHold) {
+            activeCalls[callId]?.onHold()
+        } else {
+            activeCalls[callId]?.onUnhold()
+        }
+    }
+
+    fun setAudioRoute(route: String) {
+        val audioManager = context.getSystemService(Context.AUDIO_SERVICE) as AudioManager
+        
+        when (route) {
+            "speaker" -> {
+                audioManager.isSpeakerphoneOn = true
+            }
+            "earpiece" -> {
+                audioManager.isSpeakerphoneOn = false
+            }
+            "bluetooth" -> {
+                // Bluetooth routing is handled automatically when connected
+                audioManager.isBluetoothScoOn = true
+                audioManager.startBluetoothSco()
+            }
+        }
+    }
+
+    fun setMuted(muted: Boolean) {
+        val audioManager = context.getSystemService(Context.AUDIO_SERVICE) as AudioManager
+        audioManager.isMicrophoneMute = muted
+    }
+
+    fun updateCallStatus(callId: String, status: String) {
+        val connection = activeCalls[callId] ?: return
+        
+        when (status) {
+            "connecting" -> connection.setDialing()
+            "connected" -> connection.setActive()
+            "disconnected" -> {
+                connection.setDisconnected(DisconnectCause(DisconnectCause.LOCAL))
+                connection.destroy()
+                activeCalls.remove(callId)
+            }
+            "failed" -> {
+                connection.setDisconnected(DisconnectCause(DisconnectCause.ERROR))
+                connection.destroy()
+                activeCalls.remove(callId)
+            }
+        }
+    }
+
+    fun registerConnection(callId: String, connection: VoipConnection) {
+        activeCalls[callId] = connection
+    }
+
+    fun notifyCallStarted(callId: String) {
+        val data = JSObject().apply {
+            put("callId", callId)
+        }
+        eventEmitter?.invoke("callStarted", data)
+    }
+
+    fun notifyCallAnswered(callId: String) {
+        val data = JSObject().apply {
+            put("callId", callId)
+        }
+        eventEmitter?.invoke("callAnswered", data)
+    }
+
+    fun notifyCallEnded(callId: String, reason: String? = null) {
+        val data = JSObject().apply {
+            put("callId", callId)
+            if (reason != null) {
+                put("reason", reason)
+            }
+        }
+        eventEmitter?.invoke("callEnded", data)
+        activeCalls.remove(callId)
+    }
+
+    fun notifyCallRejected(callId: String) {
+        val data = JSObject().apply {
+            put("callId", callId)
+        }
+        eventEmitter?.invoke("callRejected", data)
+        activeCalls.remove(callId)
+    }
+
+    fun notifyCallHeld(callId: String, onHold: Boolean) {
+        val data = JSObject().apply {
+            put("callId", callId)
+            put("onHold", onHold)
+        }
+        eventEmitter?.invoke("callHeld", data)
+    }
+
+    private fun notifyError(message: String) {
+        android.util.Log.e("CallManager", message)
+    }
+}