expo-callkit-telecom 0.1.0

package/android/src/main/java/expo/modules/callkittelecom/managers/FulfillRequestManager.kt

@@ -0,0 +1,150 @@
+package expo.modules.callkittelecom.managers
+
+import expo.modules.callkittelecom.utils.CallKitTelecomLog
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.launch
+import java.util.UUID
+
+/**
+ * Pending fulfill request metadata for answered incoming calls.
+ *
+ * `requestId` is sent to JS and must be fulfilled once media is connected.
+ */
+data class FulfillRequest(
+    val requestId: UUID,
+    val callId: UUID,
+)
+
+/** Result of a fulfill request. */
+sealed interface FulfillResult {
+    /** The request was successfully fulfilled, includes the associated call ID. */
+    data class Fulfilled(
+        val callId: UUID,
+    ) : FulfillResult
+
+    /** The request timed out before being fulfilled. */
+    data object TimedOut : FulfillResult
+}
+
+/**
+ * Tracks pending answer fulfill requests with timeout behavior.
+ *
+ * Semantics:
+ * - create request on answer
+ * - resolve via fulfill(requestId)
+ * - auto-timeout if JS never fulfills
+ *
+ * All mutable state is guarded by [lock] for thread safety.
+ */
+object FulfillRequestManager {
+    private const val TAG = "ExpoCallKitTelecom.Fulfill"
+
+    private val lock = Any()
+    private val scope = CoroutineScope(Dispatchers.Main + SupervisorJob())
+    private val requests = mutableMapOf<UUID, UUID>()
+    private val timeoutJobs = mutableMapOf<UUID, Job>()
+
+    /**
+     * Creates a pending fulfill request for a call.
+     *
+     * @param callId Call UUID associated with this request.
+     * @param timeoutMs Maximum wait time before automatic timeout.
+     * @param onTimeout Callback invoked with the call UUID when request expires.
+     */
+    fun createRequest(
+        callId: UUID,
+        timeoutMs: Long,
+        onTimeout: (UUID) -> Unit,
+    ): FulfillRequest {
+        val requestId = UUID.randomUUID()
+
+        val job =
+            scope.launch {
+                delay(timeoutMs)
+                val removedCallId =
+                    synchronized(lock) {
+                        timeoutJobs.remove(requestId)
+                        requests.remove(requestId)
+                    }
+                if (removedCallId != null) {
+                    CallKitTelecomLog.d(TAG) { "Fulfill request timed out - requestId: $requestId, callId: $removedCallId" }
+                    onTimeout(removedCallId)
+                }
+            }
+
+        synchronized(lock) {
+            requests[requestId] = callId
+            timeoutJobs[requestId] = job
+        }
+
+        CallKitTelecomLog.d(TAG) { "Created fulfill request - requestId: $requestId, callId: $callId, timeout: ${timeoutMs}ms" }
+        return FulfillRequest(requestId = requestId, callId = callId)
+    }
+
+    /**
+     * Fulfills a request by ID.
+     *
+     * @return associated call UUID when request exists, else null (already timed out/handled).
+     */
+    fun fulfill(requestId: UUID): UUID? {
+        val job: Job?
+        val callId: UUID?
+        synchronized(lock) {
+            job = timeoutJobs.remove(requestId)
+            callId = requests.remove(requestId)
+        }
+        job?.cancel()
+
+        if (callId != null) {
+            CallKitTelecomLog.d(TAG) { "Fulfill request succeeded - requestId: $requestId, callId: $callId" }
+        } else {
+            CallKitTelecomLog.d(TAG) { "Fulfill request not found (likely timed out) - requestId: $requestId" }
+        }
+        return callId
+    }
+
+    /**
+     * Cancels a pending request by request ID without fulfilling it.
+     *
+     * Use when the request should be aborted (e.g., call ended before connection).
+     */
+    fun cancel(requestId: UUID) {
+        val job: Job?
+        synchronized(lock) {
+            job = timeoutJobs.remove(requestId)
+            requests.remove(requestId)
+        }
+        job?.cancel()
+        if (job != null) {
+            CallKitTelecomLog.d(TAG) { "Fulfill request cancelled - requestId: $requestId" }
+        }
+    }
+
+    /**
+     * Cancels any pending fulfill request associated with a specific call.
+     *
+     * Used when a call ends before JS fulfills the answer request.
+     * This is a convenience for the call-end path where only the call ID
+     * is available rather than the request ID.
+     */
+    fun cancelForCall(callId: UUID) {
+        val entriesToCancel: List<Pair<UUID, Job?>>
+        synchronized(lock) {
+            val requestIds = requests.entries.filter { it.value == callId }.map { it.key }
+            entriesToCancel =
+                requestIds.map { reqId ->
+                    val job = timeoutJobs.remove(reqId)
+                    requests.remove(reqId)
+                    reqId to job
+                }
+        }
+        entriesToCancel.forEach { (reqId, job) ->
+            job?.cancel()
+            CallKitTelecomLog.d(TAG) { "Fulfill request cancelled for call - requestId: $reqId, callId: $callId" }
+        }
+    }
+}

package/android/src/main/java/expo/modules/callkittelecom/managers/VoIPPushManager.kt

@@ -0,0 +1,54 @@
+package expo.modules.callkittelecom.managers
+
+import android.util.Log
+import com.google.firebase.messaging.FirebaseMessaging
+import expo.modules.callkittelecom.events.CallEventEmitter
+import expo.modules.callkittelecom.events.CallEvents
+import expo.modules.callkittelecom.utils.CallKitTelecomLog
+
+/**
+ * Manages FCM push token registration and storage.
+ *
+ * This singleton mirrors iOS's VoIPPushManager and handles:
+ * - Registering for FCM push tokens
+ * - Storing and exposing the current push token
+ * - Emitting events when the token updates
+ */
+object VoIPPushManager {
+    private const val TAG = "ExpoCallKitTelecom.VoIPPush"
+
+    /** The current FCM push token, if available. */
+    @Volatile
+    var token: String? = null
+        private set
+
+    /** Registers for FCM push tokens by fetching the current token. */
+    fun register() {
+        FirebaseMessaging
+            .getInstance()
+            .token
+            .addOnSuccessListener { newToken ->
+                updateToken(newToken)
+            }.addOnFailureListener { error ->
+                Log.e(TAG, "Failed to get FCM token: ${error.message}", error)
+            }
+    }
+
+    /**
+     * Updates the stored token and emits an event to JS.
+     *
+     * @param newToken The new token string, or null if invalidated.
+     */
+    fun updateToken(newToken: String?) {
+        val oldToken = token
+        token = newToken
+
+        if (oldToken != newToken) {
+            CallKitTelecomLog.d(TAG) { "VoIP token updated - hasToken: ${newToken != null}" }
+            CallEventEmitter.send(
+                CallEvents.VOIP_PUSH_TOKEN_UPDATED,
+                mapOf("token" to newToken, "type" to "FCM"),
+            )
+        }
+    }
+}

package/android/src/main/java/expo/modules/callkittelecom/models/CallModels.kt

@@ -0,0 +1,269 @@
+package expo.modules.callkittelecom.models
+
+import java.time.Instant
+import java.time.format.DateTimeFormatter
+import java.util.UUID
+
+/** Source/origin of a call session from the app/system perspective. */
+enum class CallSessionOrigin(
+    val value: String,
+) {
+    INCOMING("incoming"),
+    OUTGOING_APP("outgoingApp"),
+    OUTGOING_SYSTEM("outgoingSystem"),
+}
+
+/** Lifecycle status of a native call session. */
+enum class CallSessionStatus(
+    val value: String,
+) {
+    REQUESTING("requesting"),
+    CONNECTING("connecting"),
+    RINGING("ringing"),
+    CONNECTED("connected"),
+    ENDED("ended"),
+}
+
+/** Call-level options shared with JS and stored in session state. */
+data class CallOptions(
+    val hasVideo: Boolean,
+)
+
+/** Remote participant identity and optional contact/display details. */
+data class CallParticipant(
+    val id: String,
+    val phoneNumber: String? = null,
+    val email: String? = null,
+    val displayName: String? = null,
+    val avatarUrl: String? = null,
+) {
+    /** Serializes participant data into the JS-facing event/session shape. */
+    fun toMap(): Map<String, Any?> =
+        mapOf(
+            "id" to id,
+            "phoneNumber" to phoneNumber,
+            "email" to email,
+            "displayName" to displayName,
+            "avatarUrl" to avatarUrl,
+        ).filterValues { it != null }
+
+    companion object {
+        /** Parses a JS/record dictionary into a strongly-typed participant model. */
+        fun fromMap(map: Map<String, Any?>): CallParticipant =
+            CallParticipant(
+                id = map["id"] as? String ?: "",
+                phoneNumber = map["phoneNumber"] as? String,
+                email = map["email"] as? String,
+                displayName = map["displayName"] as? String,
+                avatarUrl = map["avatarUrl"] as? String,
+            )
+    }
+}
+
+/**
+ * Validated incoming call event.
+ *
+ * Mirrors the TS `IncomingCallEvent` in `src/Calls.types.ts`.
+ *
+ * Two construction paths:
+ * - [fromMap]: parses JS camelCase dictionaries (used by `reportIncomingCall`).
+ * - [fromPayload]: parses a push payload that wraps the event under the
+ *   top-level `incoming_call` key (used by VoIP push handling).
+ */
+data class IncomingCallEvent(
+    val eventId: String,
+    /** Server-assigned id for this call (distinct from the native UUID). */
+    val serverCallId: String,
+    val caller: Caller,
+    val hasVideo: Boolean,
+    /** Optional; defaults to now if absent. */
+    val startedAt: Instant,
+    /** App-defined extra fields forwarded verbatim from the push payload. */
+    val metadata: Map<String, Any?>? = null,
+) {
+    /** Caller information embedded in incoming call events. */
+    data class Caller(
+        val id: String,
+        val displayName: String? = null,
+        val phoneNumber: String? = null,
+        val email: String? = null,
+        val avatarUrl: String? = null,
+    ) {
+        /** Serializes caller data into JS-facing payload shape. */
+        fun toMap(): Map<String, Any?> =
+            mapOf(
+                "id" to id,
+                "displayName" to displayName,
+                "phoneNumber" to phoneNumber,
+                "email" to email,
+                "avatarUrl" to avatarUrl,
+            ).filterValues { it != null }
+
+        companion object {
+            /** Parses caller dictionaries (camelCase). */
+            fun fromMap(map: Map<String, Any?>): Caller =
+                Caller(
+                    id = map["id"] as? String ?: "",
+                    displayName = map["displayName"] as? String,
+                    phoneNumber = map["phoneNumber"] as? String,
+                    email = map["email"] as? String,
+                    avatarUrl = map["avatarUrl"] as? String,
+                )
+        }
+    }
+
+    /** Serializes the event into the session payload shape expected by JS. */
+    fun toMap(): Map<String, Any?> {
+        val map =
+            mutableMapOf<String, Any?>(
+                "eventId" to eventId,
+                "serverCallId" to serverCallId,
+                "caller" to caller.toMap(),
+                "hasVideo" to hasVideo,
+                "startedAt" to DateTimeFormatter.ISO_INSTANT.format(startedAt),
+            )
+        if (metadata != null) {
+            map["metadata"] = metadata
+        }
+        return map
+    }
+
+    companion object {
+        /**
+         * Parses and validates a JS-supplied event dictionary (camelCase keys).
+         *
+         * Required: `eventId`, `serverCallId`, `caller.id`.
+         */
+        fun fromMap(map: Map<String, Any?>): IncomingCallEvent {
+            val callerMap = map["caller"] as? Map<String, Any?> ?: emptyMap()
+            val startedAt =
+                (map["startedAt"] as? String)?.let {
+                    try {
+                        Instant.parse(it)
+                    } catch (_: Throwable) {
+                        Instant.now()
+                    }
+                } ?: Instant.now()
+
+            val eventId = map["eventId"] as? String ?: ""
+            val serverCallId = map["serverCallId"] as? String ?: ""
+            val callerId = callerMap["id"] as? String ?: ""
+
+            require(eventId.isNotBlank()) { "IncomingCallEvent.eventId is required" }
+            require(serverCallId.isNotBlank()) { "IncomingCallEvent.serverCallId is required" }
+            require(callerId.isNotBlank()) { "IncomingCallEvent.caller.id is required" }
+
+            @Suppress("UNCHECKED_CAST")
+            val metadata = map["metadata"] as? Map<String, Any?>
+
+            return IncomingCallEvent(
+                eventId = eventId,
+                serverCallId = serverCallId,
+                caller = Caller.fromMap(callerMap),
+                hasVideo = map["hasVideo"] as? Boolean ?: false,
+                startedAt = startedAt,
+                metadata = metadata,
+            )
+        }
+
+        /**
+         * Parses an `IncomingCallEvent` from a push payload.
+         *
+         * The payload MUST wrap the event under the top-level key `incoming_call`.
+         * There is no fallback to a flat top-level shape. Inner keys are
+         * camelCase, matching the TS contract and the example server.
+         *
+         * Returns `null` if the envelope is missing or required fields are
+         * absent.
+         */
+        @Suppress("UNCHECKED_CAST")
+        fun fromPayload(payload: Map<String, Any?>): IncomingCallEvent? {
+            val event = payload["incoming_call"] as? Map<String, Any?> ?: return null
+
+            val eventId = event["eventId"] as? String ?: ""
+            val serverCallId = event["serverCallId"] as? String ?: ""
+            val callerMap = event["caller"] as? Map<String, Any?> ?: return null
+            val callerId = callerMap["id"] as? String ?: ""
+
+            if (eventId.isBlank() || serverCallId.isBlank() || callerId.isBlank()) {
+                return null
+            }
+
+            val startedAt =
+                (event["startedAt"] as? String)?.let {
+                    try {
+                        Instant.parse(it)
+                    } catch (_: Throwable) {
+                        null
+                    }
+                } ?: Instant.now()
+
+            return IncomingCallEvent(
+                eventId = eventId,
+                serverCallId = serverCallId,
+                caller = Caller.fromMap(callerMap),
+                hasVideo = event["hasVideo"] as? Boolean ?: false,
+                startedAt = startedAt,
+                metadata = event["metadata"] as? Map<String, Any?>,
+            )
+        }
+    }
+}
+
+/** In-memory representation of an active native call session. */
+data class CallSession(
+    val id: UUID,
+    val options: CallOptions,
+    val origin: CallSessionOrigin,
+    val remoteParticipants: List<CallParticipant>,
+    val incomingCallEvent: IncomingCallEvent? = null,
+    val status: CallSessionStatus,
+    val connectedAt: Instant? = null,
+    val isMuted: Boolean = false,
+    val isOnHold: Boolean = false,
+    val dtmfDigits: String? = null,
+) {
+    /** Serializes session state into the exact JS-facing `CallSession` shape. */
+    fun toMap(): Map<String, Any?> {
+        val map =
+            mutableMapOf<String, Any?>(
+                "id" to id.toString(),
+                "options" to mapOf("hasVideo" to options.hasVideo),
+                "origin" to origin.value,
+                "remoteParticipants" to remoteParticipants.map { it.toMap() },
+                "status" to status.value,
+                "isMuted" to isMuted,
+                "isOnHold" to isOnHold,
+            )
+
+        if (dtmfDigits != null) {
+            map["dtmfDigits"] = dtmfDigits
+        }
+        if (connectedAt != null) {
+            map["connectedAt"] = DateTimeFormatter.ISO_INSTANT.format(connectedAt)
+        }
+        if (incomingCallEvent != null) {
+            map["incomingCallEvent"] = incomingCallEvent.toMap()
+        }
+
+        return map
+    }
+}
+
+/** Normalized call end reasons supported by the shared JS API. */
+enum class CallEndedReason(
+    val value: String,
+) {
+    FAILED("failed"),
+    REMOTE_ENDED("remoteEnded"),
+    UNANSWERED("unanswered"),
+    ANSWERED_ELSEWHERE("answeredElsewhere"),
+    DECLINED_ELSEWHERE("declinedElsewhere"),
+    UNKNOWN("unknown"),
+    ;
+
+    companion object {
+        /** Safely maps a reason string to enum, defaulting to `UNKNOWN`. */
+        fun fromValue(value: String): CallEndedReason = entries.firstOrNull { it.value == value } ?: UNKNOWN
+    }
+}

package/android/src/main/java/expo/modules/callkittelecom/services/CallNotificationReceiver.kt

@@ -0,0 +1,54 @@
+package expo.modules.callkittelecom.services
+
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import expo.modules.callkittelecom.managers.CallManager
+import expo.modules.callkittelecom.utils.CallKitTelecomLog
+import java.util.UUID
+
+/**
+ * Handles decline actions from call notifications.
+ *
+ * Answer actions use PendingIntent.getActivity() to bring the app to the
+ * foreground directly (required on Android 12+), and are handled by
+ * [ExpoCallKitTelecomModule.OnNewIntent]. This receiver only handles decline.
+ */
+class CallNotificationReceiver : BroadcastReceiver() {
+    companion object {
+        private const val TAG = "ExpoCallKitTelecom.NotifReceiver"
+
+        const val ACTION_ANSWER = "expo.modules.callkittelecom.ACTION_ANSWER"
+        const val ACTION_DECLINE = "expo.modules.callkittelecom.ACTION_DECLINE"
+        const val EXTRA_CALL_ID = "expo.modules.callkittelecom.EXTRA_CALL_ID"
+    }
+
+    override fun onReceive(
+        context: Context,
+        intent: Intent,
+    ) {
+        val callIdStr = intent.getStringExtra(EXTRA_CALL_ID) ?: return
+        val callId =
+            try {
+                UUID.fromString(callIdStr)
+            } catch (_: IllegalArgumentException) {
+                CallKitTelecomLog.e(TAG) { "Invalid call ID in notification action: $callIdStr" }
+                return
+            }
+
+        when (intent.action) {
+            ACTION_ANSWER -> {
+                // Answer action is handled by OnNewIntent in ExpoCallKitTelecomModule
+                // since the PendingIntent launches the Activity directly.
+                // This branch only fires for legacy broadcast-based answer actions.
+                CallKitTelecomLog.d(TAG) { "Notification answer action (broadcast) - callId: $callId" }
+                CallManager.shared.answerCall(callId)
+            }
+
+            ACTION_DECLINE -> {
+                CallKitTelecomLog.d(TAG) { "Notification decline action - callId: $callId" }
+                CallManager.shared.endCall(callId)
+            }
+        }
+    }
+}

package/android/src/main/java/expo/modules/callkittelecom/services/ExpoCallKitTelecomMessagingService.kt

@@ -0,0 +1,161 @@
+package expo.modules.callkittelecom.services
+
+import android.os.Handler
+import android.os.Looper
+import android.util.Log
+import com.google.firebase.messaging.RemoteMessage
+import expo.modules.callkittelecom.managers.CallManager
+import expo.modules.callkittelecom.managers.VoIPPushManager
+import expo.modules.callkittelecom.models.IncomingCallEvent
+import expo.modules.notifications.service.ExpoFirebaseMessagingService
+import org.json.JSONArray
+import org.json.JSONObject
+import java.util.concurrent.ConcurrentHashMap
+
+/**
+ * Android FCM entry point for incoming call payloads.
+ *
+ * Extends expo-notifications' [ExpoFirebaseMessagingService] so that non-call
+ * messages are handled by the existing notification delegate via [super], and
+ * call payloads are routed directly to Telecom.
+ *
+ * Wire format (matches example/server/lib/fcm.ts):
+ *   data["messageType"]   = "incoming_call"
+ *   data["incoming_call"] = JSON string of the IncomingCallEvent (camelCase)
+ */
+class ExpoCallKitTelecomMessagingService : ExpoFirebaseMessagingService() {
+    companion object {
+        private const val TAG = "ExpoCallKitTelecom.FCM"
+        private const val KEY_MESSAGE_TYPE = "messageType"
+        private const val MESSAGE_TYPE_INCOMING_CALL = "incoming_call"
+        private const val KEY_INCOMING_CALL = "incoming_call"
+        private const val DEDUP_WINDOW_MS = 120_000L
+
+        private val dedupeLock = Any()
+        private val recentMessages = ConcurrentHashMap<String, Long>()
+    }
+
+    override fun onMessageReceived(message: RemoteMessage) {
+        val data = message.data
+
+        // Try to parse as an incoming call payload.
+        val eventMap = if (data.isNotEmpty()) parseIncomingCallEvent(data) else null
+        if (eventMap == null) {
+            // Not a call push — let expo-notifications handle it.
+            super.onMessageReceived(message)
+            return
+        }
+
+        val dedupeKey = dedupeKey(eventMap) ?: return
+        if (!markMessageAsNew(dedupeKey)) {
+            Log.d(TAG, "Dropping duplicate incoming call push - key: $dedupeKey")
+            return
+        }
+
+        Handler(Looper.getMainLooper()).post {
+            processIncomingCall(eventMap)
+        }
+    }
+
+    override fun onNewToken(token: String) {
+        VoIPPushManager.updateToken(token)
+
+        // Let expo-notifications update its own token listeners.
+        super.onNewToken(token)
+    }
+
+    private fun processIncomingCall(eventMap: Map<String, Any?>) {
+        try {
+            CallManager.shared.initialize(applicationContext)
+
+            // Wrap under the envelope so we go through the same parser path as iOS.
+            val event = IncomingCallEvent.fromPayload(mapOf(KEY_INCOMING_CALL to eventMap))
+            if (event == null) {
+                Log.w(TAG, "Failed to validate incoming call event from FCM payload")
+                return
+            }
+
+            CallManager.shared.reportIncomingCall(event)
+            Log.d(TAG, "Reported incoming call from FCM payload")
+        } catch (error: IllegalStateException) {
+            Log.w(
+                TAG,
+                "Ignoring incoming call push while another session exists: ${error.message}",
+            )
+        } catch (error: Throwable) {
+            Log.e(TAG, "Failed to process incoming call push: ${error.message}", error)
+        }
+    }
+
+    private fun parseIncomingCallEvent(data: Map<String, String>): Map<String, Any?>? {
+        if (data[KEY_MESSAGE_TYPE] != MESSAGE_TYPE_INCOMING_CALL) {
+            return null
+        }
+
+        val nestedPayload = data[KEY_INCOMING_CALL] ?: return null
+        return try {
+            jsonObjectToMap(JSONObject(nestedPayload))
+        } catch (error: Throwable) {
+            Log.w(TAG, "Failed to parse incoming_call JSON payload: ${error.message}")
+            null
+        }
+    }
+
+    private fun dedupeKey(eventMap: Map<String, Any?>): String? {
+        val eventId = eventMap["eventId"] as? String
+        if (!eventId.isNullOrBlank()) {
+            return "event:$eventId"
+        }
+
+        val serverCallId = eventMap["serverCallId"] as? String
+        if (!serverCallId.isNullOrBlank()) {
+            return "call:$serverCallId"
+        }
+
+        return null
+    }
+
+    private fun markMessageAsNew(key: String): Boolean {
+        val now = System.currentTimeMillis()
+        synchronized(dedupeLock) {
+            recentMessages.entries.removeIf { (_, seenAt) -> now - seenAt > DEDUP_WINDOW_MS }
+            val seenAt = recentMessages[key]
+            if (seenAt != null && now - seenAt <= DEDUP_WINDOW_MS) {
+                return false
+            }
+            recentMessages[key] = now
+            return true
+        }
+    }
+
+    private fun jsonObjectToMap(jsonObject: JSONObject): Map<String, Any?> {
+        val result = mutableMapOf<String, Any?>()
+        val iterator = jsonObject.keys()
+        while (iterator.hasNext()) {
+            val key = iterator.next()
+            result[key] = jsonValueToAny(jsonObject.opt(key))
+        }
+        return result
+    }
+
+    private fun jsonArrayToList(array: JSONArray): List<Any?> {
+        val result = mutableListOf<Any?>()
+        for (index in 0 until array.length()) {
+            result.add(jsonValueToAny(array.opt(index)))
+        }
+        return result
+    }
+
+    private fun jsonValueToAny(value: Any?): Any? =
+        when (value) {
+            null,
+            JSONObject.NULL,
+            -> null
+
+            is JSONObject -> jsonObjectToMap(value)
+
+            is JSONArray -> jsonArrayToList(value)
+
+            else -> value
+        }
+}