@poolse/react-native-calls 0.8.0 → 0.10.0

package/README.md

@@ -44,6 +44,33 @@ await calls.join(call.id, conversationId, sessionToken);
 calls.hangUp(); // leaves — the room ends once it has been empty a moment
 ```
 
+`snapshot.kind` is `'room'` for a room (`'call'` otherwise), so a host
+can show it differently from a call — Loop shows a bar over the chat
+with mute, camera, audio output and Leave rather than the call screen.
+A room plays on the speaker unless a headset or Bluetooth device is in,
+and turning the camera on (`setCamera(true)`) is all it takes to go from
+voice to video.
+
+### Call waiting
+
+A call that rings while one is in progress (or while you sit in a room)
+waits beside it instead of being refused: `snapshot.waiting` carries it
+(`callId`, names, media), and the native side shows its own surface —
+CallKit's call-waiting screen on iOS, a heads-up with Decline / End &
+answer and the call-waiting beep on Android.
+
+```ts
+if (s.waiting) {
+  calls.answerWaiting(s.waiting.callId);  // ends this call, answers that one
+  calls.declineWaiting(s.waiting.callId); // its caller hears "Busy"
+}
+```
+
+Pass the `callId`: a tap that lands after the waiting call changed is
+then ignored rather than acting on a different one. If the current call
+ends on its own, the waiting call simply becomes the ringing call; left
+alone it times out as missed. A third call while one waits is busy.
+
 ### Chat notifications
 
 poolse sends message notifications itself, with the push credentials you

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

@@ -43,6 +43,9 @@ class CallCoreRuntime(
   /** Grants of rings auto-declined busy, kept until the decline fires. */
   private val busyRings = mutableMapOf<String, RingContext>()
 
+  /** The ring of the call waiting beside the current one (its grant answers or busy-declines it). */
+  private var waitingRingCtx: RingContext? = null
+
   /** The session bundle of the current call, once the server accepted. */
   private var bundle: CallSessionBundle? = null
 
@@ -110,6 +113,7 @@ class CallCoreRuntime(
     private const val T_RECONNECT = "reconnect_budget"
     private const val T_CONNECT = "connect_watchdog"
     private const val T_RING_OUT = "ring_out_backstop"
+    private const val T_WAITING = "waiting_deadline"
   }
 
   // ── inputs from adapters ────────────────────────────────────────────
@@ -119,6 +123,12 @@ class CallCoreRuntime(
   /** Best name for the current call: the server's bundle, else the ring's. Runtime thread only. */
   val conversationName: String? get() = bundle?.conversationName ?: ring?.conversationName
 
+  /** `room` or `call`, once the server's bundle says; null before. Runtime thread only. */
+  val callKind: String? get() = bundle?.kind
+
+  /** The call waiting beside the current one, with its caller's names. Runtime thread only. */
+  val waitingRing: RingContext? get() = if (state.waiting == null) null else waitingRingCtx
+
   /** True if [callId] was already resolved here — its ring must never surface again. */
   fun isResolved(callId: String): Boolean = synchronized(resolved) { resolved.containsKey(callId) }
 
@@ -165,6 +175,18 @@ class CallCoreRuntime(
   fun answer() = post { dispatch(Event.UserAnswer) }
   fun decline() = post { dispatch(Event.UserDecline) }
   fun hangUp() = post { dispatch(Event.UserHangup) }
+  /**
+   * Call waiting: end this call and answer the one waiting. With
+   * [callId], only if that is still the call waiting (a stale tap on a
+   * surface for an earlier one must not answer a different call).
+   */
+  fun answerWaiting(callId: String? = null) = post {
+    if (callId == null || state.waiting?.callId == callId) dispatch(Event.UserAnswerWaiting)
+  }
+  /** Call waiting: turn the waiting call away (its caller hears busy). */
+  fun declineWaiting(callId: String? = null) = post {
+    if (callId == null || state.waiting?.callId == callId) dispatch(Event.UserDeclineWaiting)
+  }
 
   fun place(conversationId: String, media: String, sessionToken: String) = post {
     if (state.phase != Phase.IDLE && state.phase != Phase.ENDED) return@post
@@ -213,23 +235,30 @@ class CallCoreRuntime(
       gen++
       markResolved(before.callId)
     }
-    for (effect in effects) execute(effect, ringCtx)
+    for (effect in effects) execute(effect, ringCtx, before)
     // Retire the ring grant only after EVERY effect has had its chance
     // to use it. CONNECTING keeps it (answer + the no-bundle hangup
     // fallback still need it); CallSessionStop clears it with the rest.
     if (isTerminal(next.phase)) ring = null
     // A bundle never outlives its call — whatever ended it.
     if (isTerminal(next.phase)) { bundle = null; sessionToken = null }
+    // A waiting call that went away without becoming the current one
+    // (declined, cancelled, timed out) is resolved: its ring never again.
+    before.waiting?.let { w ->
+      if (next.waiting?.callId != w.callId && next.callId != w.callId) markResolved(w.callId)
+    }
+    if (next.waiting == null) waitingRingCtx = null
     runTimers(before, next)
     if (next != before || effects.isNotEmpty()) sink.emit(next)
   }
 
-  private fun execute(effect: Effect, ringCtx: RingContext?) {
+  private fun execute(effect: Effect, ringCtx: RingContext?, before: MachineState) {
     val g = gen
     when (effect) {
       Effect.ShowRing -> {
-        ring = ringCtx
-        ringCtx?.let(surface::show)
+        // A promoted waiting call rings with the ring already on file.
+        if (ringCtx != null) ring = ringCtx
+        ring?.let(surface::show)
       }
       Effect.DismissRing -> {
         (ring ?: ringCtx)?.let { surface.dismiss(it.callId) }
@@ -266,7 +295,8 @@ class CallCoreRuntime(
         ring?.let { http.decline(it.callId, it.grant, busy = false) }
       }
       is Effect.HttpDeclineBusy -> {
-        busyRings[effect.callId]?.let { http.decline(it.callId, it.grant, busy = true) }
+        val waitingMatch = waitingRingCtx?.takeIf { it.callId == effect.callId }
+        (busyRings[effect.callId] ?: waitingMatch)?.let { http.decline(it.callId, it.grant, busy = true) }
         markResolved(effect.callId)
       }
       Effect.HttpHangup -> {
@@ -297,6 +327,23 @@ class CallCoreRuntime(
         ring = null
         sessionToken = null
       }
+
+      Effect.ShowWaiting -> {
+        waitingRingCtx = ringCtx
+        ringCtx?.let(surface::showWaiting)
+      }
+      // The grant is NOT retired here: HTTP_DECLINE_BUSY may precede or follow.
+      Effect.DismissWaiting -> before.waiting?.let { surface.dismissWaiting(it.callId) }
+      Effect.PromoteWaiting -> {
+        // The old call is over: nothing it started may land on this one.
+        markResolved(before.callId)
+        gen++
+        bundle = null
+        sessionToken = null
+        ring = waitingRingCtx
+        waitingRingCtx = null
+        before.waiting?.let { surface.promoteWaiting(it.callId) }
+      }
     }
   }
 
@@ -366,7 +413,10 @@ class CallCoreRuntime(
   }
 
   private fun runTimers(before: MachineState, after: MachineState) {
-    if (before.phase == after.phase) return
+    runWaitingTimer(before, after)
+    // A different call in the same phase (end-and-answer while connecting)
+    // needs its own timers: the old ones belong to a retired generation.
+    if (before.phase == after.phase && before.callId == after.callId) return
     when (before.phase) {
       Phase.RINGING_IN -> timers.cancel(T_DEADLINE)
       Phase.ENDED -> timers.cancel(T_LINGER)
@@ -390,4 +440,17 @@ class CallCoreRuntime(
       else -> Unit
     }
   }
+
+  private fun runWaitingTimer(before: MachineState, after: MachineState) {
+    val was = before.waiting?.callId
+    val now = after.waiting?.callId
+    if (was == now) return
+    if (was != null) timers.cancel(T_WAITING)
+    val deadline = waitingRingCtx?.ringDeadlineEpochMs
+    if (now == null || deadline == null) return
+    val delay = (deadline - timers.nowMs()).coerceAtLeast(CLOCK_SLACK_MS)
+    // Keyed to the waiting call, not the generation: the current call may
+    // move on (connect, reconnect) while this one keeps waiting.
+    timers.schedule(T_WAITING, delay) { post { if (state.waiting?.callId == now) dispatch(Event.WaitingDeadline) } }
+  }
 }

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

@@ -24,6 +24,16 @@ enum class EndReason {
   val wire: String get() = name.lowercase()
 }
 
+/**
+ * A second call ringing while this device is on one (CONTRACT.md §7,
+ * call waiting): shown beside the current call, never instead of it.
+ */
+data class WaitingCall(
+  val callId: String,
+  val conversationId: String?,
+  val media: String,
+)
+
 /** Everything the machine knows. Immutable; transitions return a new one. */
 data class MachineState(
   val phase: Phase = Phase.IDLE,
@@ -34,6 +44,8 @@ data class MachineState(
   val reason: EndReason? = null,
   /** HTTP attempts made for the current connecting request (retry budget = 2). */
   val httpAttempts: Int = 0,
+  /** A second call ringing beside this one, if any. */
+  val waiting: WaitingCall? = null,
 ) {
   companion object { val IDLE = MachineState() }
 }
@@ -90,6 +102,13 @@ sealed interface Event {
   /** CONNECTING watchdog: neither the server nor the SFU got us in. */
   data object ConnectTimeout : Event
   data object LingerElapsed : Event
+
+  /** Call waiting: leave the current call and answer the waiting one. */
+  data object UserAnswerWaiting : Event
+  /** Call waiting: turn the waiting call away — its caller hears busy. */
+  data object UserDeclineWaiting : Event
+  /** The waiting call's ring deadline passed. */
+  data object WaitingDeadline : Event
 }
 
 /** Abstract effects — each adapter maps them to its platform. */
@@ -113,13 +132,95 @@ sealed interface Effect {
   data object MediaLeave : Effect { override val wire = "MEDIA_LEAVE" }
   data object CallSessionStart : Effect { override val wire = "CALL_SESSION_START" }
   data object CallSessionStop : Effect { override val wire = "CALL_SESSION_STOP" }
+  data object ShowWaiting : Effect { override val wire = "SHOW_WAITING" }
+  data object DismissWaiting : Effect { override val wire = "DISMISS_WAITING" }
+  /**
+   * The waiting call becomes the current one: retire the old call's
+   * grant/bundle/generation and take the waiting ring's.
+   */
+  data object PromoteWaiting : Effect { override val wire = "PROMOTE_WAITING" }
 }
 
 data class Transition(val state: MachineState, val effects: List<Effect>)
 
 object CallMachine {
 
-  fun transition(s: MachineState, e: Event): Transition = when (e) {
+  /**
+   * Phases that can hold a call waiting beside them: this device is on
+   * (or placing, or joining) a call. A second ring while one is ringING
+   * in is still busy — two rings at once is not a choice anyone can make.
+   */
+  private fun canHoldWaiting(s: MachineState) = when (s.phase) {
+    Phase.RINGING_OUT, Phase.CONNECTING, Phase.ACTIVE, Phase.RECONNECTING -> true
+    else -> false
+  }
+
+  /**
+   * The ring surface effects the end-and-answer composite skips: the
+   * waiting call goes straight from waiting to connecting, never ringing.
+   */
+  private val ringSurfaceEffects =
+    setOf<Effect>(Effect.ShowRing, Effect.RingtoneStart, Effect.RingtoneStop, Effect.DismissRing)
+
+  fun transition(s: MachineState, e: Event): Transition {
+    val w = s.waiting
+    if (w == null) {
+      return when {
+        e is Event.Ring && !e.stale && canHoldWaiting(s) && e.callId != s.callId -> Transition(
+          s.copy(waiting = WaitingCall(e.callId, e.conversationId, e.media)),
+          listOf(Effect.ShowWaiting),
+        )
+        e == Event.UserAnswerWaiting || e == Event.UserDeclineWaiting || e == Event.WaitingDeadline -> noop(s)
+        else -> single(s, e)
+      }
+    }
+
+    val cleared = s.copy(waiting = null)
+    return when {
+      e is Event.Ring -> when (e.callId) {
+        w.callId -> noop(s)
+        s.callId -> carry(single(cleared, e), w)
+        else -> if (e.stale) noop(s) else Transition(s, listOf(Effect.HttpDeclineBusy(e.callId)))
+      }
+      e is Event.RingEnded && e.callId == w.callId -> Transition(cleared, listOf(Effect.DismissWaiting))
+      e is Event.CallFinished && e.callId == w.callId -> Transition(cleared, listOf(Effect.DismissWaiting))
+      e == Event.WaitingDeadline -> Transition(cleared, listOf(Effect.DismissWaiting))
+      e == Event.UserDeclineWaiting ->
+        Transition(cleared, listOf(Effect.HttpDeclineBusy(w.callId), Effect.DismissWaiting))
+      e == Event.UserAnswerWaiting -> {
+        // Leaving rings the waiting call (below); answering it at once
+        // makes that ring a no-op the surface never sees.
+        val left = transition(s, Event.UserHangup)
+        if (left.state.phase != Phase.RINGING_IN || left.state.callId != w.callId) {
+          noop(s)
+        } else {
+          val answered = single(left.state, Event.UserAnswer)
+          Transition(answered.state, (left.effects + answered.effects).filterNot { it in ringSurfaceEffects })
+        }
+      }
+      else -> {
+        val t = single(cleared, e)
+        if (t.state.phase != Phase.ENDED && t.state.phase != Phase.IDLE) {
+          carry(t, w)
+        } else {
+          // The current call is over while another rings beside it: that
+          // ring is now simply THE ring (no ended screen in between).
+          Transition(
+            MachineState(
+              phase = Phase.RINGING_IN, callId = w.callId, conversationId = w.conversationId,
+              direction = Direction.INCOMING, media = w.media,
+            ),
+            t.effects + listOf(Effect.PromoteWaiting, Effect.ShowRing, Effect.RingtoneStart),
+          )
+        }
+      }
+    }
+  }
+
+  private fun carry(t: Transition, w: WaitingCall) = Transition(t.state.copy(waiting = w), t.effects)
+
+  /** The one-call machine: everything that is not about a waiting call. */
+  private fun single(s: MachineState, e: Event): Transition = when (e) {
 
     is Event.Ring -> ring(s, e)
 
@@ -351,6 +452,9 @@ object CallMachine {
 
     Event.LingerElapsed ->
       if (s.phase == Phase.ENDED) Transition(MachineState.IDLE, emptyList()) else noop(s)
+
+    // Handled by `transition`, which owns the waiting slot.
+    Event.UserAnswerWaiting, Event.UserDeclineWaiting, Event.WaitingDeadline -> noop(s)
   }
 
   private fun ring(s: MachineState, e: Event.Ring): Transition = when {
@@ -369,8 +473,9 @@ object CallMachine {
       listOf(Effect.ShowRing, Effect.RingtoneStart),
     )
 
-    // Busy with another call, in any phase: auto-decline the newcomer,
-    // whose banner still offers Join later. (Contract §7, scenario s9.)
+    // Busy ringing another call (a call in progress holds it waiting
+    // instead — see `transition`): auto-decline the newcomer, whose
+    // banner still offers Join later. (Contract §7, scenario s9.)
     else -> Transition(s, listOf(Effect.HttpDeclineBusy(e.callId)))
   }
 

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

@@ -53,6 +53,8 @@ data class CallSessionBundle(
   val livekitUrl: String,
   val livekitToken: String,
   val controlToken: String,
+  /** `room` (rings nobody, CONTRACT.md §5.6) or `call`. */
+  val kind: String = "call",
 )
 
 /** LiveKit (or any SFU) — media only, no lifecycle opinions. */
@@ -84,6 +86,18 @@ interface RingSurfacePort {
   fun ringtoneStop()
   fun ringbackStart()
   fun ringbackStop()
+  /**
+   * A call waiting beside the current one: its own quiet surface (a
+   * heads-up with a waiting tone; iOS: CallKit's call-waiting UI).
+   */
+  fun showWaiting(ring: RingContext) {}
+  /** The waiting call is over (declined, cancelled, timed out). */
+  fun dismissWaiting(callId: String) {}
+  /**
+   * The waiting call becomes THE ring (SHOW_RING follows): drop its
+   * waiting surface without resolving it.
+   */
+  fun promoteWaiting(callId: String) {}
 }
 
 data class RingContext(

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

@@ -6,7 +6,11 @@ import android.app.PendingIntent
 import android.content.Context
 import android.content.Intent
 import android.media.AudioAttributes
+import android.media.AudioManager
 import android.media.MediaPlayer
+import android.media.ToneGenerator
+import android.os.Handler
+import android.os.Looper
 import android.media.Ringtone
 import android.media.RingtoneManager
 import android.os.Build
@@ -50,6 +54,18 @@ internal class AndroidRingSurface(
   private var ringbackWanted = false
   private var communicationReady = false
 
+  /** The call waiting beside the current one, while its surface is up. */
+  private var waitingCallId: String? = null
+  private var waitingTone: ToneGenerator? = null
+  private val main = Handler(Looper.getMainLooper())
+  private val waitingBeep = object : Runnable {
+    override fun run() {
+      if (waitingCallId == null) return
+      runCatching { waitingTone?.startTone(ToneGenerator.TONE_SUP_CALL_WAITING, WAITING_BEEP_MS) }
+      main.postDelayed(this, WAITING_BEEP_EVERY_MS)
+    }
+  }
+
   /**
    * The call's audio path is (or is no longer) in communication mode.
    * A ringback requested earlier starts now, through the call route.
@@ -134,7 +150,106 @@ internal class AndroidRingSurface(
     }
   }
 
+  /**
+   * A call waiting beside the one in progress: a quiet heads-up — not
+   * the full-screen ring, which would cover the call — with Decline and
+   * End & answer, and the call-waiting beep through the call's own
+   * audio route (the ringtone would blare over the conversation).
+   */
+  override fun showWaiting(ring: RingContext) {
+    ensureWaitingChannel()
+    val extras = ring.toBundle()
+
+    fun actionPending(action: String, requestOffset: Int): PendingIntent {
+      val intent = Intent(context, CallActionReceiver::class.java)
+        .setAction("$ACTION_PREFIX.$action")
+        .putExtra(EXTRA_RING, extras)
+      return PendingIntent.getBroadcast(
+        context,
+        ring.callId.hashCode() + requestOffset,
+        intent,
+        PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE,
+      )
+    }
+
+    val open = context.packageManager.getLaunchIntentForPackage(context.packageName)?.let {
+      PendingIntent.getActivity(
+        context,
+        ring.callId.hashCode() + 5,
+        it.addFlags(Intent.FLAG_ACTIVITY_SINGLE_TOP or Intent.FLAG_ACTIVITY_REORDER_TO_FRONT),
+        PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE,
+      )
+    }
+
+    val who = ring.conversationName ?: ring.callerName ?: "Someone"
+    val what = if (ring.media == "video") "video call" else "call"
+    val notification = NotificationCompat.Builder(context, WAITING_CHANNEL_ID)
+      .setSmallIcon(config.smallIcon)
+      .setCategory(NotificationCompat.CATEGORY_CALL)
+      .setPriority(NotificationCompat.PRIORITY_HIGH)
+      .setVisibility(NotificationCompat.VISIBILITY_PUBLIC)
+      .setContentTitle("$who — incoming $what")
+      .setContentText("You're on a call. Answering ends it.")
+      .setOngoing(true)
+      .setAutoCancel(false)
+      .setOnlyAlertOnce(true)
+      .apply { if (open != null) setContentIntent(open) }
+      .addAction(0, "Decline", actionPending(ACTION_WAITING_DECLINE, 3))
+      .addAction(0, "End & answer", actionPending(ACTION_WAITING_ANSWER, 4))
+      .build()
+
+    waitingCallId = ring.callId
+    try {
+      NotificationManagerCompat.from(context).notify(ring.callId.notificationId(), notification)
+    } catch (e: SecurityException) {
+      Log.e(TAG, "call-waiting notification refused (POST_NOTIFICATIONS?)", e)
+    }
+    startWaitingBeep()
+  }
+
+  override fun dismissWaiting(callId: String) {
+    if (waitingCallId != callId) return
+    stopWaitingBeep()
+    runCatching { NotificationManagerCompat.from(context).cancel(callId.notificationId()) }
+  }
+
+  /** SHOW_RING follows, reposting under the same id as the full ring. */
+  override fun promoteWaiting(callId: String) = dismissWaiting(callId)
+
+  private fun startWaitingBeep() {
+    main.removeCallbacks(waitingBeep)
+    if (waitingTone == null) {
+      waitingTone = runCatching { ToneGenerator(AudioManager.STREAM_VOICE_CALL, WAITING_BEEP_VOLUME) }.getOrNull()
+    }
+    main.post(waitingBeep)
+  }
+
+  private fun stopWaitingBeep() {
+    waitingCallId = null
+    main.removeCallbacks(waitingBeep)
+    runCatching { waitingTone?.stopTone(); waitingTone?.release() }
+    waitingTone = null
+  }
+
+  private fun ensureWaitingChannel() {
+    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) return
+    val manager = context.getSystemService(NotificationManager::class.java)
+    if (manager.getNotificationChannel(WAITING_CHANNEL_ID) != null) return
+    // Silent: the beep is ours, through the call route. A channel sound
+    // would play on the notification stream over the conversation.
+    manager.createNotificationChannel(
+      NotificationChannel(WAITING_CHANNEL_ID, "Calls while on a call", NotificationManager.IMPORTANCE_HIGH).apply {
+        setSound(null, null)
+        enableVibration(false)
+        lockscreenVisibility = NotificationCompat.VISIBILITY_PUBLIC
+      },
+    )
+  }
+
   override fun dismiss(callId: String) {
+    // Every teardown for a call (ring_ended, finished) also ends its
+    // waiting surface, even after a restart lost the in-memory state.
+    if (waitingCallId == callId) stopWaitingBeep()
     if (shownRing?.first == callId) shownRing = null
     runCatching { NotificationManagerCompat.from(context).cancel(callId.notificationId()) }
     // The full-screen activity is its own window: tell it to close.
@@ -222,6 +337,12 @@ internal class AndroidRingSurface(
     const val ACTION_ANSWER = "ANSWER"
     const val ACTION_DECLINE = "DECLINE"
     const val ACTION_OPEN = "OPEN"
+    const val ACTION_WAITING_ANSWER = "WAITING_ANSWER"
+    const val ACTION_WAITING_DECLINE = "WAITING_DECLINE"
+    const val WAITING_CHANNEL_ID = "poolse_call_waiting"
+    private const val WAITING_BEEP_MS = 400
+    private const val WAITING_BEEP_EVERY_MS = 3_000L
+    private const val WAITING_BEEP_VOLUME = 70
     const val EXTRA_RING = "poolse_ring"
     const val EXTRA_AUTO_ANSWER = "poolse_auto_answer"
     /** Package-local broadcast: the ring for [EXTRA_CALL_ID] is over. */

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

@@ -3,11 +3,15 @@ package dev.poolse.callcore.android
 import android.content.BroadcastReceiver
 import android.content.Context
 import android.content.Intent
+import androidx.core.app.NotificationManagerCompat
 import dev.poolse.callcore.android.AndroidRingSurface.Companion.ACTION_ANSWER
 import dev.poolse.callcore.android.AndroidRingSurface.Companion.ACTION_DECLINE
 import dev.poolse.callcore.android.AndroidRingSurface.Companion.ACTION_OPEN
 import dev.poolse.callcore.android.AndroidRingSurface.Companion.ACTION_PREFIX
+import dev.poolse.callcore.android.AndroidRingSurface.Companion.ACTION_WAITING_ANSWER
+import dev.poolse.callcore.android.AndroidRingSurface.Companion.ACTION_WAITING_DECLINE
 import dev.poolse.callcore.android.AndroidRingSurface.Companion.EXTRA_RING
+import dev.poolse.callcore.android.AndroidRingSurface.Companion.notificationId
 
 /**
  * Answer / Decline taps on the CallStyle notification land here, as do
@@ -24,6 +28,18 @@ class CallActionReceiver : BroadcastReceiver() {
       "$ACTION_PREFIX.$ACTION_ANSWER" -> core.onUserAnswer(ring)
       "$ACTION_PREFIX.$ACTION_DECLINE" -> core.onUserDecline(ring)
       "$ACTION_PREFIX.$ACTION_OPEN" -> core.onUserOpen(ring)
+      // Call waiting: keyed to THIS call, so a stale notification can
+      // never act on a different one — and one outliving its call (a
+      // process restart) is simply taken down.
+      "$ACTION_PREFIX.$ACTION_WAITING_ANSWER", "$ACTION_PREFIX.$ACTION_WAITING_DECLINE" -> {
+        if (core.state().waiting?.callId != ring.callId) {
+          NotificationManagerCompat.from(context).cancel(ring.callId.notificationId())
+        } else if (intent.action == "$ACTION_PREFIX.$ACTION_WAITING_ANSWER") {
+          core.answerWaiting(ring.callId)
+        } else {
+          core.declineWaiting(ring.callId)
+        }
+      }
     }
   }
 }

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

@@ -65,6 +65,10 @@ class CallCore private constructor(context: Context) {
   private var extrasMedia: String? = null
   private var roster: List<MediaParticipant> = emptyList()
   private var conversationName: String? = null
+  private var callKind: String = "call"
+
+  // Video calls and rooms default to the speaker (the media port agrees).
+  private fun loud(state: MachineState) = state.media == "video" || callKind == "room"
   private var mutedSelf = false
   private var cameraOn = false
   private var cameraFacing: String? = null
@@ -138,6 +142,10 @@ class CallCore private constructor(context: Context) {
   fun answer() = runtime.answer()
   fun decline() = runtime.decline()
   fun hangUp() = runtime.hangUp()
+  /** Call waiting: end this call, answer the waiting one ([callId]: only if still that one). */
+  fun answerWaiting(callId: String? = null) = runtime.answerWaiting(callId)
+  /** Call waiting: turn the waiting call away — its caller hears busy. */
+  fun declineWaiting(callId: String? = null) = runtime.declineWaiting(callId)
   fun place(conversationId: String, media: String, sessionToken: String) =
     runtime.place(conversationId, media, sessionToken)
   fun join(callId: String, conversationId: String?, sessionToken: String) =
@@ -211,9 +219,11 @@ class CallCore private constructor(context: Context) {
       extrasMedia = state.media
     }
     runtime.conversationName?.let { conversationName = it }
+    runtime.callKind?.let { callKind = it }
 
     val snap = state.toSnapshot(
       conversationName = conversationName,
+      kind = callKind,
       participants = roster.map {
         mapOf(
           "userId" to it.identity,
@@ -223,12 +233,13 @@ class CallCore private constructor(context: Context) {
           "cameraOn" to it.cameraOn,
         )
       },
-      audioRoute = audioRoute ?: if (state.media == "video") "speaker" else "earpiece",
+      audioRoute = audioRoute ?: if (loud(state)) "speaker" else "earpiece",
       audioOutputs = audioOutputs.map { mapOf("id" to it.id, "kind" to it.kind, "name" to it.name) },
       audioOutputId = audioOutputId,
       mutedSelf = mutedSelf,
       cameraOn = cameraOn,
       cameraFacing = cameraFacing,
+      waitingRing = runtime.waitingRing,
     )
     lastSnapshot = snap
     reconcileAndroid(state)
@@ -240,6 +251,7 @@ class CallCore private constructor(context: Context) {
     extrasMedia = media
     roster = emptyList()
     conversationName = null
+    callKind = "call"
     mutedSelf = false
     // Reported by the media adapter once the camera is really published.
     cameraOn = false
@@ -268,7 +280,7 @@ class CallCore private constructor(context: Context) {
     // Screen off at the ear: only for an audio call on the earpiece.
     val inCall = state.phase == Phase.ACTIVE || state.phase == Phase.RECONNECTING ||
       state.phase == Phase.RINGING_OUT || state.phase == Phase.CONNECTING
-    val earpiece = (audioRoute ?: if (state.media == "video") "speaker" else "earpiece") == "earpiece"
+    val earpiece = (audioRoute ?: if (loud(state)) "speaker" else "earpiece") == "earpiece"
     setProximity(inCall && state.media == "audio" && earpiece)
   }
 

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

@@ -185,6 +185,7 @@ internal class CallHttpClient(
         livekitToken = livekit.getString("token"),
         controlToken = root.optStringOrNull("control_token")
           ?: requireNotNull(current?.controlToken) { "bundle without control_token" },
+        kind = call.optStringOrNull("kind") ?: current?.kind ?: "call",
       )
     }
 

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

@@ -16,6 +16,7 @@ import dev.poolse.callcore.Phase
  */
 internal fun MachineState.toSnapshot(
   conversationName: String? = null,
+  kind: String = "call",
   participants: List<Map<String, Any>> = emptyList(),
   audioRoute: String = "earpiece",
   audioOutputs: List<Map<String, Any>> = emptyList(),
@@ -23,14 +24,30 @@ internal fun MachineState.toSnapshot(
   mutedSelf: Boolean = false,
   cameraOn: Boolean = false,
   cameraFacing: String? = null,
+  /** The waiting call's ring (names); the machine's [MachineState.waiting] says whether there is one. */
+  waitingRing: dev.poolse.callcore.RingContext? = null,
 ): Map<String, Any?>? {
   if (phase == Phase.IDLE) return null
   return buildMap {
     putAll(snapshotCore(conversationName, participants, audioRoute, mutedSelf, cameraOn))
+    put("kind", kind)
     put("audioOutputs", audioOutputs)
     put("audioOutputId", audioOutputId)
     // Optional in the contract: present only while a camera is published.
     if (cameraFacing != null) put("cameraFacing", cameraFacing)
+    // The call waiting beside this one: null when none.
+    put(
+      "waiting",
+      waiting?.let { w ->
+        mapOf(
+          "callId" to w.callId,
+          "conversationId" to (waitingRing?.conversationId ?: w.conversationId),
+          "conversationName" to waitingRing?.conversationName,
+          "callerName" to waitingRing?.callerName,
+          "media" to w.media,
+        )
+      },
+    )
   }
 }
 

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

@@ -83,6 +83,8 @@ class PoolseCallsModule : Module() {
     Function("answer") { core()?.answer() }
     Function("decline") { core()?.decline() }
     Function("hangUp") { core()?.hangUp() }
+    Function("answerWaiting") { callId: String? -> core()?.answerWaiting(callId) }
+    Function("declineWaiting") { callId: String? -> core()?.declineWaiting(callId) }
     Function("setMuted") { muted: Boolean -> core()?.setMuted(muted) }
     Function("setCamera") { on: Boolean -> core()?.setCamera(on) }
     Function("switchCamera") { core()?.switchCamera() }