@poolse/react-native-calls 0.1.2 → 0.2.0

package/android/src/main/java/dev/poolse/callcore/android/IncomingCallActivity.kt

@@ -2,11 +2,17 @@ package dev.poolse.callcore.android
 
 import android.animation.ValueAnimator
 import android.app.Activity
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import android.content.IntentFilter
 import android.graphics.Color
 import android.graphics.Typeface
 import android.graphics.drawable.GradientDrawable
 import android.os.Build
 import android.os.Bundle
+import android.os.Handler
+import android.os.Looper
 import android.view.Gravity
 import android.view.View
 import android.view.WindowManager
@@ -14,6 +20,10 @@ import android.view.animation.LinearInterpolator
 import android.widget.FrameLayout
 import android.widget.LinearLayout
 import android.widget.TextView
+import androidx.core.content.ContextCompat
+import dev.poolse.callcore.RingContext
+import dev.poolse.callcore.android.AndroidRingSurface.Companion.ACTION_RING_CLOSED
+import dev.poolse.callcore.android.AndroidRingSurface.Companion.EXTRA_CALL_ID
 import dev.poolse.callcore.android.AndroidRingSurface.Companion.EXTRA_RING
 
 /**
@@ -23,31 +33,118 @@ import dev.poolse.callcore.android.AndroidRingSurface.Companion.EXTRA_RING
  * ground, brand glow, a breathing ring) in plain views. The buttons
  * resolve into [CallCore], the same entry point every other surface
  * uses; answering brings the app forward over the keyguard.
+ *
+ * It closes itself when the ring ends anywhere else (caller cancelled,
+ * answered on another device, deadline) via the package-local
+ * [ACTION_RING_CLOSED] broadcast — before, a remotely-ended ring left
+ * this screen up with dead buttons.
  */
 class IncomingCallActivity : Activity() {
 
   private var pulse: ValueAnimator? = null
   private val density by lazy { resources.displayMetrics.density }
   private fun px(v: Int): Int = (v * density).toInt()
+  private val main = Handler(Looper.getMainLooper())
+
+  /** The ring on screen. */
+  private var ring: RingContext? = null
+
+  /**
+   * Answered: we are only waiting for the app to come forward over us.
+   * Our own DISMISS_RING broadcast must not close us before it does —
+   * finishing first left the app behind the keyguard.
+   */
+  private var awaitingForward = false
+
+  private val ringClosed = object : BroadcastReceiver() {
+    override fun onReceive(context: Context, intent: Intent) {
+      val callId = intent.getStringExtra(EXTRA_CALL_ID) ?: return
+      if (callId == ring?.callId && !awaitingForward) finish()
+    }
+  }
 
   override fun onCreate(savedInstanceState: Bundle?) {
     super.onCreate(savedInstanceState)
     showOverKeyguard()
+    ContextCompat.registerReceiver(
+      this,
+      ringClosed,
+      IntentFilter(ACTION_RING_CLOSED),
+      ContextCompat.RECEIVER_NOT_EXPORTED,
+    )
+    handle(intent)
+  }
+
+  /** singleInstance: a new ring (or the answer action) arrives here, not in onCreate. */
+  override fun onNewIntent(intent: Intent) {
+    super.onNewIntent(intent)
+    setIntent(intent)
+    handle(intent)
+  }
 
-    val ring = intent.getBundleExtra(EXTRA_RING)?.toRingContext()
-    if (ring == null) { finish(); return }
+  private fun handle(intent: Intent) {
+    val next = intent.getBundleExtra(EXTRA_RING)?.toRingContext()
+    if (next == null) { if (ring == null) finish(); return }
+    val core = CallCore.getOrNull(this)
+    if (core == null) { finish(); return }
+
+    // Answered from the notification: this activity exists only to be the
+    // foreground context that is ALLOWED to bring the app up (a
+    // background receiver is not).
+    if (intent.getBooleanExtra(AndroidRingSurface.EXTRA_AUTO_ANSWER, false)) {
+      ring = next
+      answerAndForward(core, next)
+      return
+    }
 
-    val title = ring.conversationName ?: ring.callerName ?: "Incoming call"
-    val body = if (ring.media == "video") "Incoming video call" else "Incoming call"
-    setContentView(buildScene(title, body, ring))
+    // A stale tap (the ring resolved, or the process restarted after it
+    // ended): there is nothing to answer.
+    if (!core.isRingLive(next)) {
+      if (ring == null || ring?.callId == next.callId) finish()
+      return
+    }
+    ring = next
+    awaitingForward = false
+    pulse?.cancel()
+    val title = next.conversationName ?: next.callerName ?: "Incoming call"
+    val body = if (next.media == "video") "Incoming video call" else "Incoming call"
+    setContentView(buildScene(title, body, next))
+  }
+
+  /**
+   * Answer, then bring the app forward FROM THIS ACTIVITY, and stay
+   * (as a plain dark window) until the app is in front — finishing at
+   * once dropped the start on some OEMs and left the call audible
+   * behind the lock screen. onStop (we got covered) finishes us; a
+   * timer is the fallback.
+   */
+  private fun answerAndForward(core: CallCore, ring: RingContext) {
+    awaitingForward = true
+    pulse?.cancel()
+    pulse = null
+    setContentView(View(this).apply { setBackgroundColor(Color.parseColor("#0B0B14")) })
+    val launched = core.onUserAnswer(ring, this)
+    if (!launched) { finish(); return }
+    main.postDelayed({ if (!isFinishing) finish() }, FORWARD_FALLBACK_MS)
+  }
+
+  override fun onStop() {
+    super.onStop()
+    if (awaitingForward && !isFinishing) finish()
   }
 
   override fun onDestroy() {
+    main.removeCallbacksAndMessages(null)
+    runCatching { unregisterReceiver(ringClosed) }
     pulse?.cancel()
     pulse = null
     super.onDestroy()
   }
 
+  private companion object {
+    const val FORWARD_FALLBACK_MS = 4_000L
+  }
+
   private fun showOverKeyguard() {
     if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O_MR1) {
       setShowWhenLocked(true)
@@ -62,7 +159,7 @@ class IncomingCallActivity : Activity() {
     window.addFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON)
   }
 
-  private fun buildScene(title: String, body: String, ring: dev.poolse.callcore.RingContext): View {
+  private fun buildScene(title: String, body: String, ring: RingContext): View {
     val root = FrameLayout(this).apply { setBackgroundColor(Color.parseColor("#0B0B14")) }
 
     root.addView(
@@ -137,10 +234,11 @@ class IncomingCallActivity : Activity() {
       layoutParams = LinearLayout.LayoutParams(LinearLayout.LayoutParams.MATCH_PARENT, wrap())
     }
     val decline = actionButton("Decline", "✕", "#EF4444") {
-      CallCore.get(this).onUserDecline(ring); finish()
+      CallCore.getOrNull(this)?.onUserDecline(ring); finish()
     }
     val accept = actionButton("Answer", "✓", "#22C55E") {
-      CallCore.get(this).onUserAnswer(ring); finish()
+      val core = CallCore.getOrNull(this)
+      if (core == null) finish() else answerAndForward(core, ring)
     }
     buttons.addView(decline, LinearLayout.LayoutParams(wrap(), wrap()).apply { rightMargin = px(52) })
     buttons.addView(accept, LinearLayout.LayoutParams(wrap(), wrap()).apply { leftMargin = px(52) })

package/android/src/main/java/expo/modules/poolsecalls/PoolseCallsModule.kt

@@ -1,7 +1,13 @@
 package expo.modules.poolsecalls
 
+import android.app.NotificationManager
+import android.content.Context
+import android.content.Intent
+import android.net.Uri
+import android.os.Build
+import android.provider.Settings
+import android.util.Log
 import dev.poolse.callcore.android.CallCore
-import dev.poolse.callcore.android.toSnapshot
 import expo.modules.kotlin.modules.Module
 import expo.modules.kotlin.modules.ModuleDefinition
 
@@ -15,6 +21,9 @@ import expo.modules.kotlin.modules.ModuleDefinition
  * the JS side needs no R references. The SFU factory defaults to the
  * shipped LiveKit adapter when present, else a no-op (audio-less), so a
  * build without the LiveKit source set still rings and signals.
+ *
+ * Nothing here throws before `configure`: reads return idle, commands
+ * no-op (a fresh install renders its UI before JS has configured).
  */
 class PoolseCallsModule : Module() {
 
@@ -24,44 +33,93 @@ class PoolseCallsModule : Module() {
     Events("onCallState")
 
     // Snapshots → the single JS event. Null (idle) becomes an explicit
-    // cleared payload so the JS side always has a definite state.
+    // cleared payload so the JS side always has a definite state. The
+    // listener is process-level, so subscribing before configure works.
     OnStartObserving {
-      CallCore.get(context).snapshotListener = { state ->
-        sendEvent("onCallState", mapOf("snapshot" to state.toSnapshot()))
-      }
+      CallCore.listener = { snapshot -> sendEvent("onCallState", mapOf("snapshot" to snapshot)) }
     }
     OnStopObserving {
-      CallCore.get(context).snapshotListener = null
+      CallCore.listener = null
     }
 
     AsyncFunction("configure") { apiBaseUrl: String, options: Map<String, Any?>? ->
+      val ctx = context ?: return@AsyncFunction null
       // Resource NAMES go to the core, which resolves + persists them —
       // so a killed app woken by a ring can rebuild this without JS.
       CallCore.configure(
-        context,
+        ctx,
         apiBaseUrl,
         options?.get("smallIcon") as? String,
         options?.get("ringback") as? String,
       )
+      // Materialise the core now, so a call already in flight (cold
+      // answer) is visible to the first getCallState.
+      CallCore.getOrNull(ctx)
+      null
     }
 
     Function("getCallState") {
-      mapOf("snapshot" to CallCore.get(context).snapshot().toSnapshot())
+      mapOf("snapshot" to (CallCore.peek() ?: context?.let(CallCore::getOrNull))?.snapshot())
     }
 
     AsyncFunction("place") { conversationId: String, media: String, sessionToken: String ->
-      CallCore.get(context).place(conversationId, media, sessionToken)
+      core()?.place(conversationId, media, sessionToken)
     }
     AsyncFunction("join") { callId: String, conversationId: String?, sessionToken: String ->
-      CallCore.get(context).join(callId, conversationId, sessionToken)
+      core()?.join(callId, conversationId, sessionToken)
+    }
+    Function("answer") { core()?.answer() }
+    Function("decline") { core()?.decline() }
+    Function("hangUp") { core()?.hangUp() }
+    Function("setMuted") { muted: Boolean -> core()?.setMuted(muted) }
+    Function("setCamera") { on: Boolean -> core()?.setCamera(on) }
+    Function("switchCamera") { core()?.switchCamera() }
+    Function("setSpeaker") { on: Boolean -> core()?.setSpeaker(on) }
+
+    // Socket forwarding (open app): idempotent with the FCM path.
+    Function("onRingEnded") { callId: String, reason: String -> core()?.onRingEnded(callId, reason) }
+    Function("onCallFinished") { callId: String, reason: String? ->
+      core()?.onCallFinished(callId, reason?.ifEmpty { null })
+    }
+
+    // Android 14+: full-screen intents need a user grant for non-dialer apps.
+    Function("canUseFullScreenIntent") {
+      val ctx = context ?: return@Function true
+      if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
+        ctx.getSystemService(NotificationManager::class.java).canUseFullScreenIntent()
+      } else {
+        true
+      }
+    }
+    Function("openFullScreenIntentSettings") {
+      val ctx = context ?: return@Function null
+      val pkg = Uri.parse("package:${ctx.packageName}")
+      val intents = buildList {
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
+          add(Intent(Settings.ACTION_MANAGE_APP_USE_FULL_SCREEN_INTENT, pkg))
+        }
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+          add(Intent(Settings.ACTION_APP_NOTIFICATION_SETTINGS).putExtra(Settings.EXTRA_APP_PACKAGE, ctx.packageName))
+        }
+        add(Intent(Settings.ACTION_APPLICATION_DETAILS_SETTINGS, pkg))
+      }
+      val opener = appContext.currentActivity
+      for (intent in intents) {
+        val ok = runCatching {
+          if (opener != null) opener.startActivity(intent)
+          else ctx.startActivity(intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK))
+        }.onFailure { Log.w(TAG, "settings intent ${intent.action} unavailable", it) }.isSuccess
+        if (ok) break
+      }
+      null
     }
-    Function("answer") { CallCore.get(context).answer() }
-    Function("decline") { CallCore.get(context).decline() }
-    Function("hangUp") { CallCore.get(context).hangUp() }
-    Function("setMuted") { muted: Boolean -> CallCore.get(context).setMuted(muted) }
-    Function("setCamera") { on: Boolean -> CallCore.get(context).setCamera(on) }
-    Function("switchCamera") { CallCore.get(context).switchCamera() }
   }
 
-  private val context get() = requireNotNull(appContext.reactContext) { "no react context" }
+  private val context: Context? get() = appContext.reactContext
+
+  private fun core(): CallCore? = context?.let(CallCore::getOrNull)
+
+  private companion object {
+    const val TAG = "PoolseCalls"
+  }
 }

package/android/src/main/livekit/java/dev/poolse/callcore/livekit/LiveKitMediaPort.kt

@@ -1,20 +1,26 @@
 package dev.poolse.callcore.livekit
 
 import android.content.Context
+import android.util.Log
+import com.twilio.audioswitch.AudioDevice
 import dev.poolse.callcore.CallSessionBundle
 import dev.poolse.callcore.MediaPort
 import dev.poolse.callcore.android.MediaEvents
 import dev.poolse.callcore.android.MediaParticipant
 import io.livekit.android.LiveKit
+import io.livekit.android.audio.AudioSwitchHandler
+import io.livekit.android.events.DisconnectReason
 import io.livekit.android.events.RoomEvent
 import io.livekit.android.events.collect
 import io.livekit.android.room.Room
+import io.livekit.android.room.participant.Participant
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.Job
 import kotlinx.coroutines.SupervisorJob
 import kotlinx.coroutines.cancel
 import kotlinx.coroutines.launch
+import org.json.JSONObject
 
 /**
  * The shipped [MediaPort], over LiveKit's native Android SDK. Wire it
@@ -24,8 +30,14 @@ import kotlinx.coroutines.launch
  * lives in its own source set (`src/main/livekit`) kept off the core
  * library's classpath. Lifecycle and signaling are not its concern — it
  * joins a room with the server-minted token, publishes the mic (and
- * camera for video), and reports room transitions back through
- * [MediaEvents]. The runtime decides everything else.
+ * camera for video), routes audio, and reports room transitions back
+ * through [MediaEvents]. The runtime decides everything else.
+ *
+ * Threading: every method is called on the main thread (the runtime's
+ * thread) and every coroutine runs on Main.immediate, so [room] is only
+ * ever touched on main. Coroutines still re-check that the room they
+ * captured is the current one — a join/leave may have replaced it
+ * while they were suspended.
  */
 class LiveKitMediaPort(
   private val context: Context,
@@ -33,37 +45,96 @@ class LiveKitMediaPort(
 ) : MediaPort {
 
   private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Main.immediate)
-  private var room: Room? = null
+  @Volatile private var room: Room? = null
   private var eventJob: Job? = null
+  private var media: String = "audio"
+
+  /** Speaker forced by the user; null = the media-type default. */
+  private var speakerWanted: Boolean? = null
+
+  /**
+   * The user's mute / camera choices for the CURRENT call. They survive
+   * a rejoin: /reconnect rebuilds the room, and blindly re-enabling the
+   * mic there went live while the UI still showed "muted". Reset only
+   * when the call ends ([leave]) or a different call joins.
+   */
+  private var mutedWanted = false
+  private var cameraWanted: Boolean? = null
+  private var joinedCallId: String? = null
 
   override fun join(bundle: CallSessionBundle) {
-    leave()
+    // Rejoin of the same call keeps the user's choices; so do choices
+    // made while this call was still connecting (joinedCallId null). A
+    // different call joining without a leave starts clean.
+    if (joinedCallId != null && bundle.callId != joinedCallId) resetWanted()
+    joinedCallId = bundle.callId
+    detach()
+    media = bundle.media
     val wantsVideo = bundle.media == "video"
     val newRoom = LiveKit.create(appContext = context.applicationContext)
+    configureAudio(newRoom, wantsVideo)
     room = newRoom
     eventJob = scope.launch { observe(newRoom) }
     scope.launch {
       runCatching {
         newRoom.connect(bundle.livekitUrl, bundle.livekitToken)
-        newRoom.localParticipant.setMicrophoneEnabled(true)
-        if (wantsVideo) newRoom.localParticipant.setCameraEnabled(true)
-      }.onFailure { events.onFailed() }
+        if (room !== newRoom) return@runCatching
+        newRoom.localParticipant.setMicrophoneEnabled(!mutedWanted)
+        if (cameraWanted ?: wantsVideo) newRoom.localParticipant.setCameraEnabled(true)
+      }.onFailure {
+        Log.w(TAG, "connect failed", it)
+        if (room === newRoom) {
+          // Don't leave a half-open room (and its audio mode) behind.
+          eventJob?.cancel()
+          eventJob = null
+          teardown(newRoom)
+          room = null
+          events.onFailed()
+        }
+      }
     }
   }
 
+  /** The call is over for this device: drop the room AND the call's choices. */
   override fun leave() {
+    detach()
+    resetWanted()
+    joinedCallId = null
+  }
+
+  private fun resetWanted() {
+    mutedWanted = false
+    cameraWanted = null
+    speakerWanted = null
+  }
+
+  /** Drop the current room only (a rejoin replaces it). */
+  private fun detach() {
     eventJob?.cancel()
     eventJob = null
-    room?.disconnect()
+    val r = room ?: return
     room = null
+    teardown(r)
+  }
+
+  private fun teardown(r: Room) {
+    runCatching { r.disconnect() }
+    // disconnect() keeps the room's engine, capturer and audio handler
+    // alive for a later reconnect; this port never reuses a room, so
+    // release it or every call leaks a PeerConnectionFactory.
+    runCatching { r.release() }
   }
 
   override fun setMuted(muted: Boolean) {
-    scope.launch { room?.localParticipant?.setMicrophoneEnabled(!muted) }
+    mutedWanted = muted
+    val r = room ?: return
+    scope.launch { runCatching { r.localParticipant.setMicrophoneEnabled(!muted) } }
   }
 
   override fun setCamera(on: Boolean) {
-    scope.launch { room?.localParticipant?.setCameraEnabled(on) }
+    cameraWanted = on
+    val r = room ?: return
+    scope.launch { runCatching { r.localParticipant.setCameraEnabled(on) } }
   }
 
   override fun switchCamera() {
@@ -71,37 +142,140 @@ class LiveKitMediaPort(
     // control here keeps the port surface complete.
   }
 
+  override fun setSpeaker(on: Boolean) {
+    speakerWanted = on
+    val handler = room?.audioHandler as? AudioSwitchHandler ?: return
+    applyRoute(handler)
+  }
+
+  // ── audio routing ───────────────────────────────────────────────────
+
+  /**
+   * A voice call is held to the ear: earpiece by default (a connected
+   * headset or Bluetooth device first); video defaults to the speaker.
+   * Set before connect — the handler starts during connect.
+   */
+  private fun configureAudio(r: Room, video: Boolean) {
+    val handler = r.audioHandler as? AudioSwitchHandler ?: return
+    handler.preferredDeviceList = if (video) {
+      listOf(
+        AudioDevice.BluetoothHeadset::class.java,
+        AudioDevice.WiredHeadset::class.java,
+        AudioDevice.Speakerphone::class.java,
+        AudioDevice.Earpiece::class.java,
+      )
+    } else {
+      listOf(
+        AudioDevice.BluetoothHeadset::class.java,
+        AudioDevice.WiredHeadset::class.java,
+        AudioDevice.Earpiece::class.java,
+        AudioDevice.Speakerphone::class.java,
+      )
+    }
+    handler.audioDeviceChangeListener = { devices, selected ->
+      // A user's speaker choice survives device-list changes, except
+      // that plugging in a headset always wins (as the dialer does).
+      val wanted = speakerWanted
+      if (wanted != null && selected != null && room?.audioHandler === handler) {
+        val external = selected is AudioDevice.BluetoothHeadset || selected is AudioDevice.WiredHeadset
+        val isSpeaker = selected is AudioDevice.Speakerphone
+        if (!external && isSpeaker != wanted) devices.pick(wanted)?.let(handler::selectDevice)
+      }
+      events.onAudioRoute(routeOf(handler.selectedAudioDevice ?: selected))
+    }
+  }
+
+  private fun applyRoute(handler: AudioSwitchHandler) {
+    val want = speakerWanted ?: (media == "video")
+    handler.availableAudioDevices.pick(want)?.let(handler::selectDevice)
+    events.onAudioRoute(routeOf(handler.selectedAudioDevice))
+  }
+
+  /** Speaker, or the best private route: Bluetooth → wired → earpiece. */
+  private fun List<AudioDevice>.pick(speaker: Boolean): AudioDevice? =
+    if (speaker) firstOrNull { it is AudioDevice.Speakerphone }
+    else firstOrNull { it is AudioDevice.BluetoothHeadset }
+      ?: firstOrNull { it is AudioDevice.WiredHeadset }
+      ?: firstOrNull { it is AudioDevice.Earpiece }
+
+  private fun routeOf(d: AudioDevice?): String = when (d) {
+    is AudioDevice.Speakerphone -> "speaker"
+    is AudioDevice.BluetoothHeadset -> "bluetooth"
+    is AudioDevice.WiredHeadset -> "headset"
+    is AudioDevice.Earpiece -> "earpiece"
+    null -> if (media == "video") "speaker" else "earpiece"
+  }
+
+  // ── room events ─────────────────────────────────────────────────────
+
   private suspend fun observe(room: Room) {
     room.events.collect { event ->
+      if (this.room !== room) return@collect
       when (event) {
-        is RoomEvent.Connected -> events.onConnected()
-        is RoomEvent.Reconnecting, is RoomEvent.Disconnected -> events.onLost()
+        is RoomEvent.Connected -> {
+          (room.audioHandler as? AudioSwitchHandler)?.let { if (speakerWanted != null) applyRoute(it) }
+          events.onConnected()
+          // Somebody may already be in (a late join, or a callee who
+          // answered before our media came up): they will not "connect".
+          if (room.remoteParticipants.isNotEmpty()) events.onRemoteJoined()
+          emit(room)
+        }
+        // LiveKit is resuming the SAME session (ICE restart / signal
+        // resume). Only reflect it: tearing the room down here fought
+        // its own recovery and turned every network blip into a rejoin.
+        is RoomEvent.Reconnecting -> events.onReconnecting()
         is RoomEvent.Reconnected -> events.onRecovered()
+        // LiveKit gave up (or the server removed us). Our own leave()
+        // never gets here — the collector is cancelled first.
+        is RoomEvent.Disconnected -> {
+          if (event.reason != DisconnectReason.CLIENT_INITIATED) events.onLost()
+        }
         is RoomEvent.ParticipantConnected -> { events.onRemoteJoined(); emit(room) }
         is RoomEvent.ParticipantDisconnected,
         is RoomEvent.ActiveSpeakersChanged,
         is RoomEvent.TrackMuted,
-        is RoomEvent.TrackUnmuted -> emit(room)
+        is RoomEvent.TrackUnmuted,
+        is RoomEvent.TrackPublished,
+        is RoomEvent.TrackUnpublished,
+        is RoomEvent.ParticipantMetadataChanged,
+        is RoomEvent.ParticipantAttributesChanged -> emit(room)
         else -> Unit
       }
+      Unit
     }
   }
 
+  /** The REMOTE roster — the local participant is never included. */
   private fun emit(room: Room) {
     events.onParticipants(
       room.remoteParticipants.values.map {
+        val identity = it.identity?.value ?: ""
         MediaParticipant(
-          identity = it.identity?.value ?: "",
+          identity = identity,
           speaking = it.isSpeaking,
-          muted = it.audioTrackPublications.firstOrNull()?.first?.muted ?: true,
+          muted = !it.isMicrophoneEnabled(),
+          cameraOn = it.isCameraEnabled(),
+          externalId = externalIdOf(it) ?: identity,
         )
       },
     )
   }
 
-  fun dispose() = scope.cancel()
+  /** The host's own user id, if the server put it in attributes/metadata. */
+  private fun externalIdOf(p: Participant): String? =
+    runCatching { p.attributes["external_id"] }.getOrNull()?.ifEmpty { null }
+      ?: p.metadata?.let { m ->
+        runCatching { JSONObject(m).optString("external_id", "") }.getOrNull()?.ifEmpty { null }
+      }
+
+  fun dispose() {
+    leave()
+    scope.cancel()
+  }
 
   companion object {
+    private const val TAG = "PoolseLiveKit"
+
     /** Pass as `mediaFactory` in CallCoreConfig. */
     val factory: (Context, MediaEvents) -> MediaPort = { ctx, ev -> LiveKitMediaPort(ctx, ev) }
   }

package/android/src/test/java/dev/poolse/callcore/android/CallHttpClientTest.kt

@@ -0,0 +1,61 @@
+package dev.poolse.callcore.android
+
+import dev.poolse.callcore.CallSessionBundle
+import dev.poolse.callcore.HttpResult
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * The HTTP classifier/parser, without a network: status + body →
+ * HttpResult exactly as CONTRACT.md §4 maps them.
+ */
+class CallHttpClientTest {
+
+  private val full = """
+    {"cv":1,"created":false,
+     "call":{"id":"c1","conversation_id":"v1","conversation_name":"Boiler","media":"video"},
+     "livekit":{"url":"wss://sfu","token":"lk-new"},
+     "control_token":"ctl-new"}
+  """.trimIndent()
+
+  private val current = CallSessionBundle(
+    callId = "c1", conversationId = "v1", conversationName = "Boiler", media = "audio",
+    created = true, livekitUrl = "wss://old", livekitToken = "lk-old", controlToken = "ctl-old",
+  )
+
+  @Test fun `full bundle parses (answer, join, place and now reconnect)`() {
+    val r = CallHttpClient.classify(200, full, current) as HttpResult.Ok
+    assertEquals("c1", r.bundle.callId)
+    assertEquals("lk-new", r.bundle.livekitToken)
+    assertEquals("ctl-new", r.bundle.controlToken)
+    assertEquals("video", r.bundle.media)
+    assertEquals(false, r.bundle.created)
+  }
+
+  @Test fun `old reconnect shape is applied onto the current bundle`() {
+    val r = CallHttpClient.classify(200, """{"cv":1,"livekit":{"url":"wss://sfu2","token":"lk-2"}}""", current)
+      as HttpResult.Ok
+    assertEquals(current.copy(livekitUrl = "wss://sfu2", livekitToken = "lk-2"), r.bundle)
+  }
+
+  @Test fun `unparseable 2xx is a failure, not a retry`() {
+    assertTrue(CallHttpClient.classify(200, "<html>", null) is HttpResult.Failed)
+    assertTrue(CallHttpClient.classify(200, """{"livekit":{"token":"x"}}""", null) is HttpResult.Failed)
+  }
+
+  @Test fun `error envelope code is read`() {
+    val r = CallHttpClient.classify(401, """{"error":{"code":"grant_spent","message":"…"}}""")
+    assertEquals(HttpResult.AuthFailed("grant_spent"), r)
+    assertEquals(HttpResult.AuthFailed("http_403"), CallHttpClient.classify(403, null))
+  }
+
+  @Test fun `status mapping`() {
+    assertEquals(HttpResult.Gone, CallHttpClient.classify(410, null))
+    assertEquals(HttpResult.Gone, CallHttpClient.classify(404, """{"error":{"code":"no_call"}}"""))
+    assertEquals(HttpResult.Failed("http_503"), CallHttpClient.classify(503, null))
+    assertEquals(HttpResult.Timeout, CallHttpClient.classify(502, null))
+    assertEquals(HttpResult.Timeout, CallHttpClient.classify(429, null))
+    assertEquals(HttpResult.Failed("bad"), CallHttpClient.classify(422, """{"error":{"code":"bad"}}"""))
+  }
+}