@poolse/react-native-calls 0.8.0 → 0.10.0

package/ios/Core/CallMachine.swift

@@ -36,6 +36,12 @@ public enum Event: Equatable {
   /// CONNECTING watchdog.
   case connectTimeout
   case lingerElapsed
+  /// Call waiting: leave the current call and answer the waiting one.
+  case userAnswerWaiting
+  /// Call waiting: turn the waiting call away — its caller hears busy.
+  case userDeclineWaiting
+  /// The waiting call's ring deadline passed.
+  case waitingDeadline
 }
 
 /// Abstract effects — each adapter maps them to its platform.
@@ -44,6 +50,10 @@ public enum Effect: Equatable {
   case httpAnswer, httpJoin, httpPlace, httpDecline
   case httpDeclineBusy(callId: String)
   case httpHangup, httpReconnect, mediaJoin, mediaLeave, callSessionStart, callSessionStop
+  case showWaiting, dismissWaiting
+  /// The waiting call becomes the current one: retire the old call's
+  /// grant/bundle/generation and take the waiting ring's.
+  case promoteWaiting
 
   public var wire: String {
     switch self {
@@ -64,6 +74,9 @@ public enum Effect: Equatable {
     case .mediaLeave: return "MEDIA_LEAVE"
     case .callSessionStart: return "CALL_SESSION_START"
     case .callSessionStop: return "CALL_SESSION_STOP"
+    case .showWaiting: return "SHOW_WAITING"
+    case .dismissWaiting: return "DISMISS_WAITING"
+    case .promoteWaiting: return "PROMOTE_WAITING"
     }
   }
 }
@@ -91,7 +104,80 @@ private extension MachineState {
 
 public enum CallMachine {
 
+  /// 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 static func canHoldWaiting(_ s: MachineState) -> Bool {
+    switch s.phase {
+    case .ringingOut, .connecting, .active, .reconnecting: return true
+    default: return false
+    }
+  }
+
+  /// The ring surface effects the end-and-answer composite skips: the
+  /// waiting call goes straight from waiting to connecting, never ringing.
+  private static let ringSurfaceEffects: [Effect] = [.showRing, .ringtoneStart, .ringtoneStop, .dismissRing]
+
   public static func transition(_ s: MachineState, _ e: Event) -> Transition {
+    guard let w = s.waiting else {
+      switch e {
+      case let .ring(callId, conversationId, media, stale)
+        where !stale && canHoldWaiting(s) && callId != s.callId:
+        var next = s
+        next.waiting = WaitingCall(callId: callId, conversationId: conversationId, media: media)
+        return Transition(next, [.showWaiting])
+      case .userAnswerWaiting, .userDeclineWaiting, .waitingDeadline:
+        return noop(s)
+      default:
+        return single(s, e)
+      }
+    }
+
+    var cleared = s
+    cleared.waiting = nil
+    switch e {
+    case let .ring(callId, _, _, stale):
+      if callId == w.callId || stale { return noop(s) }
+      if callId == s.callId { return carry(single(cleared, e), w) }
+      return Transition(s, [.httpDeclineBusy(callId: callId)])
+
+    case let .ringEnded(callId, _) where callId == w.callId:
+      return Transition(cleared, [.dismissWaiting])
+    case let .callFinished(callId, _) where callId == w.callId:
+      return Transition(cleared, [.dismissWaiting])
+    case .waitingDeadline:
+      return Transition(cleared, [.dismissWaiting])
+    case .userDeclineWaiting:
+      return Transition(cleared, [.httpDeclineBusy(callId: w.callId), .dismissWaiting])
+
+    case .userAnswerWaiting:
+      // Leaving rings the waiting call (below); answering it at once
+      // makes that ring a no-op the surface never sees.
+      let left = transition(s, .userHangup)
+      guard left.state.phase == .ringingIn, left.state.callId == w.callId else { return noop(s) }
+      let answered = single(left.state, .userAnswer)
+      let effects = (left.effects + answered.effects).filter { !ringSurfaceEffects.contains($0) }
+      return Transition(answered.state, effects)
+
+    default:
+      let t = single(cleared, e)
+      guard t.state.phase == .ended || t.state.phase == .idle else { return carry(t, w) }
+      // The current call is over while another rings beside it: that
+      // ring is now simply THE ring (no ended screen in between).
+      let ringing = MachineState(phase: .ringingIn, callId: w.callId, conversationId: w.conversationId,
+                                 direction: .incoming, media: w.media)
+      return Transition(ringing, t.effects + [.promoteWaiting, .showRing, .ringtoneStart])
+    }
+  }
+
+  private static func carry(_ t: Transition, _ w: WaitingCall) -> Transition {
+    var state = t.state
+    state.waiting = w
+    return Transition(state, t.effects)
+  }
+
+  /// The one-call machine: everything that is not about a waiting call.
+  private static func single(_ s: MachineState, _ e: Event) -> Transition {
     switch e {
 
     case let .ring(callId, conversationId, media, stale):
@@ -271,6 +357,9 @@ public enum CallMachine {
 
     case .lingerElapsed:
       return s.phase == .ended ? Transition(.IDLE, []) : noop(s)
+
+    case .userAnswerWaiting, .userDeclineWaiting, .waitingDeadline:
+      return noop(s) // handled by `transition`, which owns the waiting slot
     }
   }
 
@@ -285,7 +374,8 @@ public enum CallMachine {
                                      direction: .incoming, media: media),
                         [.showRing, .ringtoneStart])
     }
-    // Busy with another call: auto-decline the newcomer.
+    // Busy ringing another call (a call in progress holds it waiting
+    // instead — see `transition`): auto-decline the newcomer.
     return Transition(s, [.httpDeclineBusy(callId: callId)])
   }
 

package/ios/Core/Ports.swift

@@ -46,9 +46,12 @@ public struct CallSessionBundle: Equatable {
   public var livekitUrl: String
   public var livekitToken: String
   public var controlToken: String
+  /// `room` (rings nobody, CONTRACT.md §5.6) or `call`.
+  public var kind: String
 
   public init(callId: String, conversationId: String, conversationName: String?, media: String,
-              created: Bool, livekitUrl: String, livekitToken: String, controlToken: String) {
+              created: Bool, livekitUrl: String, livekitToken: String, controlToken: String,
+              kind: String = "call") {
     self.callId = callId
     self.conversationId = conversationId
     self.conversationName = conversationName
@@ -57,6 +60,7 @@ public struct CallSessionBundle: Equatable {
     self.livekitUrl = livekitUrl
     self.livekitToken = livekitToken
     self.controlToken = controlToken
+    self.kind = kind
   }
 }
 
@@ -90,6 +94,20 @@ public protocol RingSurfacePort: AnyObject {
   func ringtoneStop()
   func ringbackStart()
   func ringbackStop()
+  /// A call waiting beside the current one: its own quiet surface (iOS:
+  /// CallKit's call-waiting UI; Android: a heads-up with a waiting tone).
+  func showWaiting(ring: RingContext)
+  /// The waiting call is over (declined, cancelled, timed out).
+  func dismissWaiting(callId: String)
+  /// The waiting call becomes THE ring (SHOW_RING follows): drop its
+  /// waiting surface without resolving it.
+  func promoteWaiting(callId: String)
+}
+
+public extension RingSurfacePort {
+  func showWaiting(ring: RingContext) {}
+  func dismissWaiting(callId: String) {}
+  func promoteWaiting(callId: String) {}
 }
 
 public struct RingContext: Equatable {
@@ -173,6 +191,20 @@ public enum EndReason: String {
   public var wire: String { rawValue.lowercased() }
 }
 
+/// A second call ringing while this device is on one (CONTRACT.md §7,
+/// call waiting): shown beside the current call, never instead of it.
+public struct WaitingCall: Equatable {
+  public var callId: String
+  public var conversationId: String?
+  public var media: String
+
+  public init(callId: String, conversationId: String?, media: String) {
+    self.callId = callId
+    self.conversationId = conversationId
+    self.media = media
+  }
+}
+
 /// Everything the machine knows. Immutable value; transitions return a new one.
 public struct MachineState: Equatable {
   public var phase: Phase
@@ -183,10 +215,12 @@ public struct MachineState: Equatable {
   public var reason: EndReason?
   /// HTTP attempts made for the current connecting request (retry budget = 2).
   public var httpAttempts: Int
+  /// A second call ringing beside this one, if any.
+  public var waiting: WaitingCall?
 
   public init(phase: Phase = .idle, callId: String? = nil, conversationId: String? = nil,
               direction: Direction? = nil, media: String = "audio", reason: EndReason? = nil,
-              httpAttempts: Int = 0) {
+              httpAttempts: Int = 0, waiting: WaitingCall? = nil) {
     self.phase = phase
     self.callId = callId
     self.conversationId = conversationId
@@ -194,6 +228,7 @@ public struct MachineState: Equatable {
     self.media = media
     self.reason = reason
     self.httpAttempts = httpAttempts
+    self.waiting = waiting
   }
 
   public static var IDLE: MachineState { MachineState() }

package/ios/Core/SnapshotEncoding.swift

@@ -66,19 +66,22 @@ public extension MachineState {
   /// fields are merged in by the bridge from the media adapter.
   /// `conversationName` nil → NSNull; `reason`/`cameraFacing` omitted when nil.
   func toSnapshot(conversationName: String? = nil,
+                  kind: String = "call",
                   participants: [SnapshotParticipant] = [],
                   audioRoute: String = "earpiece",
                   audioOutputs: [AudioOutput] = [],
                   audioOutputId: String? = nil,
                   mutedSelf: Bool = false,
                   cameraOn: Bool = false,
-                  cameraFacing: String? = nil) -> [String: Any]? {
+                  cameraFacing: String? = nil,
+                  waiting: RingContext? = nil) -> [String: Any]? {
     if phase == .idle { return nil }
     var out: [String: Any] = [
       "cv": 1,
       "callId": callId.map { $0 as Any } ?? NSNull(),
       "conversationId": conversationId.map { $0 as Any } ?? NSNull(),
       "conversationName": conversationName.map { $0 as Any } ?? NSNull(),
+      "kind": kind,
       "direction": (direction ?? .incoming).wire,
       "media": media,
       "phase": phase.wire,
@@ -89,6 +92,18 @@ public extension MachineState {
       "mutedSelf": mutedSelf,
       "cameraOn": cameraOn,
     ]
+    // The call waiting beside this one: null when none.
+    if let w = self.waiting {
+      out["waiting"] = [
+        "callId": w.callId,
+        "conversationId": (waiting?.conversationId ?? w.conversationId).map { $0 as Any } ?? NSNull(),
+        "conversationName": waiting?.conversationName.map { $0 as Any } ?? NSNull(),
+        "callerName": waiting?.callerName.map { $0 as Any } ?? NSNull(),
+        "media": w.media,
+      ] as [String: Any]
+    } else {
+      out["waiting"] = NSNull()
+    }
     if let reason = reason { out["reason"] = reason.wire }
     // Optional in the contract: present only while a camera is published.
     if let cameraFacing = cameraFacing { out["cameraFacing"] = cameraFacing }

package/ios/Module/PoolseCallsModule.swift

@@ -66,6 +66,8 @@ public class PoolseCallsModule: Module {
     Function("answer") { onCore { $0.answer() } }
     Function("decline") { onCore { $0.decline() } }
     Function("hangUp") { onCore { $0.hangUp() } }
+    Function("answerWaiting") { (callId: String?) in onCore { $0.answerWaiting(callId: callId) } }
+    Function("declineWaiting") { (callId: String?) in onCore { $0.declineWaiting(callId: callId) } }
     Function("setMuted") { (muted: Bool) in onCore { $0.setMuted(muted) } }
     Function("setCamera") { (on: Bool) in onCore { $0.setCamera(on) } }
     Function("switchCamera") { onCore { $0.switchCamera() } }

package/ios/Platform/CallCore.swift

@@ -139,6 +139,7 @@ final class CallCore {
   private var extrasMedia: String?
   private var roster: [SnapshotParticipant] = []
   private var conversationName: String?
+  private var callKind = "call"
   private var mutedSelf = false
   private var cameraOn = false
   private var cameraFacing: String?
@@ -232,6 +233,24 @@ final class CallCore {
     }
   }
 
+  /// Call waiting: end this call, answer the waiting one. CallKit follows
+  /// from the resulting state (reconcileCallKit ends the old call, then
+  /// answers the new one).
+  func answerWaiting(callId: String? = nil) {
+    onMain { [self] in
+      localEnd = true
+      runtime.answerWaiting(callId: callId)
+    }
+  }
+
+  /// Call waiting: turn the waiting call away (its caller hears busy).
+  func declineWaiting(callId: String? = nil) {
+    onMain { [self] in runtime.declineWaiting(callId: callId) }
+  }
+
+  /// True while `callId` is the call waiting beside the current one. Main thread.
+  func isWaiting(_ callId: String) -> Bool { runtime.currentState().waiting?.callId == callId }
+
   func place(conversationId: String, media: String, sessionToken: String) {
     onMain { [self] in
       localEnd = false
@@ -299,6 +318,9 @@ final class CallCore {
         if let old = extrasCallId, let new = state.callId { callKit.rename(from: old, to: new) }
         extrasCallId = state.callId
       } else {
+        // A different call (a waiting one promoted): nothing of the last
+        // carries over — not even "the user ended it here".
+        if extrasCallId != nil { localEnd = false }
         resetExtras(state.callId, state.media)
       }
     }
@@ -307,16 +329,20 @@ final class CallCore {
       extrasMedia = state.media
     }
     if let name = runtime.conversationName { conversationName = name }
+    if let kind = runtime.callKind { callKind = kind }
 
     let snap = state.toSnapshot(
       conversationName: conversationName,
+      kind: callKind,
       participants: roster,
-      audioRoute: audioRoute ?? (state.media == "video" ? "speaker" : "earpiece"),
+      // Video calls and rooms default to the speaker (the media port agrees).
+      audioRoute: audioRoute ?? (state.media == "video" || callKind == "room" ? "speaker" : "earpiece"),
       audioOutputs: audioOutputs,
       audioOutputId: audioOutputId,
       mutedSelf: mutedSelf,
       cameraOn: cameraOn,
-      cameraFacing: cameraFacing
+      cameraFacing: cameraFacing,
+      waiting: runtime.waitingRing
     )
     snapshotLock.lock(); lastSnapshot = snap; snapshotLock.unlock()
     reconcileCallKit(state)
@@ -329,6 +355,7 @@ final class CallCore {
     extrasMedia = media
     roster = []
     conversationName = nil
+    callKind = "call"
     mutedSelf = false
     cameraOn = false
     cameraFacing = nil
@@ -340,25 +367,27 @@ final class CallCore {
   /// CallKit follows the FINAL state of each dispatch.
   private func reconcileCallKit(_ state: MachineState) {
     let terminal = state.phase == .idle || state.phase == .ended
-    for t in callKit.liveCalls {
-      let isCurrent = !terminal && t.callId == state.callId
-      if isCurrent {
-        switch state.phase {
-        case .connecting, .active, .reconnecting, .ringingOut:
-          // Answered from the app's own UI: tell CallKit (audio follows).
-          if !t.outgoing && !t.answered && state.direction == .incoming { callKit.requestAnswer(callId: t.callId) }
-          if t.outgoing && state.phase == .active { callKit.reportConnected(callId: t.callId) }
-          callKit.updateTitle(callId: t.callId, title: conversationName, video: state.media == "video")
-        default:
-          break
-        }
-        continue
-      }
+    // The call waiting beside this one stays on CallKit's call-waiting UI.
+    let live = callKit.liveCalls.filter { terminal || $0.callId != state.waiting?.callId }
+    // Ends first: answering the next call (end-and-answer) while CallKit
+    // still holds the last one would ask it for two calls at once.
+    for t in live where terminal || t.callId != state.callId {
       // Not the call the machine is in (ended, busy-declined, superseded).
       // Terminal: whatever CallKit still shows is the call that just ended.
       let reason = endReason(for: t, state: state, current: terminal || t.callId == state.callId)
       callKit.end(t, reason: reason)
     }
+    for t in live where !terminal && t.callId == state.callId {
+      switch state.phase {
+      case .connecting, .active, .reconnecting, .ringingOut:
+        // Answered from the app's own UI: tell CallKit (audio follows).
+        if !t.outgoing && !t.answered && state.direction == .incoming { callKit.requestAnswer(callId: t.callId) }
+        if t.outgoing && state.phase == .active { callKit.reportConnected(callId: t.callId) }
+        callKit.updateTitle(callId: t.callId, title: conversationName, video: state.media == "video")
+      default:
+        break
+      }
+    }
     if terminal {
       localEnd = false
       if let id = state.callId { ringEndReasons.removeValue(forKey: id) }
@@ -414,6 +443,13 @@ final class CallCore {
     callKit.reportIncoming(ring: ring)
   }
 
+  /// CallKit shows a second incoming call over a live one as call
+  /// waiting (End & Accept / Decline). Usually already reported by the
+  /// push path; idempotent.
+  fileprivate func showWaiting(_ ring: RingContext) {
+    callKit.reportIncoming(ring: ring)
+  }
+
   fileprivate var ringbackPlayer: Ringback { ringback }
 
   // MediaEvents → runtime
@@ -446,12 +482,24 @@ final class CallCore {
 extension CallCore: CallKitActions {
   func callKitAnswer(callId: String) {
     let s = runtime.currentState()
+    // End & Accept may answer the waiting call before ending the current
+    // one: answering it ends the current call itself.
+    if s.waiting?.callId == callId {
+      localEnd = true
+      runtime.answerWaiting(callId: callId)
+      return
+    }
     guard s.callId == callId, s.phase == .ringingIn else { return }
     runtime.answer()
   }
 
   func callKitEnd(callId: String) {
     let s = runtime.currentState()
+    // Decline on CallKit's call-waiting UI.
+    if s.waiting?.callId == callId {
+      runtime.declineWaiting(callId: callId)
+      return
+    }
     guard s.callId == callId || (s.callId?.hasPrefix("pending:") == true) else { return }
     localEnd = true
     if s.phase == .ringingIn { runtime.decline() } else { runtime.hangUp() }
@@ -489,6 +537,11 @@ private final class SurfaceAdapter: RingSurfacePort, CallSessionPort {
 
   func show(ring: RingContext) { core?.showRing(ring) }
   func dismiss(callId: String) {}
+  func showWaiting(ring: RingContext) { core?.showWaiting(ring) }
+  // Dismissal is reconciled from the final state; promotion keeps the
+  // CallKit call, which SHOW_RING then finds already reported.
+  func dismissWaiting(callId: String) {}
+  func promoteWaiting(callId: String) {}
   func ringtoneStart() {}
   func ringtoneStop() {}
   func ringbackStart() { core?.ringbackPlayer.start() }

package/ios/Platform/CallKitController.swift

@@ -124,7 +124,13 @@ final class CallKitController: NSObject, CXProviderDelegate {
       DispatchQueue.main.async {
         t.ended = true
         self?.calls.removeValue(forKey: t.uuid)
-        CallCore.peek()?.onRingEnded(callId: ring.callId, reason: "cancelled")
+        // A refused call-waiting report: the caller would ring on into
+        // a void — turn it away as busy instead.
+        if let core = CallCore.peek(), core.isWaiting(ring.callId) {
+          core.declineWaiting(callId: ring.callId)
+        } else {
+          CallCore.peek()?.onRingEnded(callId: ring.callId, reason: "cancelled")
+        }
       }
     }
   }

package/ios/Platform/LiveKitMediaPort.swift

@@ -66,6 +66,9 @@ final class LiveKitMediaPort: NSObject, MediaPort {
   private(set) var room: Room?
   private var observer: RoomObserver?
   private var media = "audio"
+  /// Speaker unless a headset is in: a video call, or a room (a drop-in
+  /// room is held like a meeting, not to the ear).
+  private var loud = false
   private var connectedRoom: ObjectIdentifier?
 
   /// Where the user asked the audio to go, for the CURRENT call.
@@ -209,6 +212,7 @@ final class LiveKitMediaPort: NSObject, MediaPort {
     detach()
     media = bundle.media
     let wantsVideo = bundle.media == "video"
+    loud = wantsVideo || bundle.kind == "room"
 
     // A 1:1/small call: never let the SFU pause a subscribed camera for
     // "not visible" — a view that mounts late would stay black.
@@ -398,7 +402,7 @@ final class LiveKitMediaPort: NSObject, MediaPort {
   /// the same; forcing the speaker over AirPods was a bug).
   private func resolvedChoice(_ s: AVAudioSession = .sharedInstance()) -> OutputChoice {
     if let wanted = outputWanted { return wanted }
-    return media == "video" && !externalConnected(s) ? .speaker : .privateRoute
+    return loud && !externalConnected(s) ? .speaker : .privateRoute
   }
 
   private func applyRoute() {
@@ -444,7 +448,7 @@ final class LiveKitMediaPort: NSObject, MediaPort {
 
   private func currentRoute() -> String {
     guard let port = AVAudioSession.sharedInstance().currentRoute.outputs.first?.portType else {
-      return media == "video" ? "speaker" : "earpiece"
+      return loud ? "speaker" : "earpiece"
     }
     return kind(of: port)
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poolse/react-native-calls",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Native call core for poolse — Kotlin/Swift calling engine with a thin React Native bridge. Ring, answer and carry audio with the app killed and the phone locked.",
   "license": "MIT",
   "type": "module",

package/src/index.ts

@@ -21,6 +21,12 @@ export interface Snapshot {
   conversationId: string;
   conversationName: string | null;
   direction: 'incoming' | 'outgoing' | 'joined';
+  /**
+   * `room` — rings nobody, joined and left at will (`startRoom`); `call`
+   * otherwise. Known once the server answered: a room being joined reads
+   * `call` while `connecting`. Absent before 0.9.0: treat as `call`.
+   */
+  kind?: 'call' | 'room';
   media: 'audio' | 'video';
   phase: 'ringing_in' | 'ringing_out' | 'connecting' | 'active' | 'reconnecting' | 'ended';
   reason?:
@@ -55,12 +61,29 @@ export interface Snapshot {
   mutedSelf: boolean;
   /** True only while the local camera track is actually published and enabled. */
   cameraOn: boolean;
+  /**
+   * A second call ringing while this one is in progress (call waiting).
+   * Offer `answerWaiting` ("End & answer" — this call ends) and
+   * `declineWaiting` (its caller hears busy). If this call ends first,
+   * the waiting one simply becomes the ringing call. null when none;
+   * absent before 0.10.0.
+   */
+  waiting?: WaitingCall | null;
   /** Facing of the published local camera; absent when the camera is off. */
   cameraFacing?: 'front' | 'back';
 }
 
 export type AudioOutputKind = 'earpiece' | 'speaker' | 'bluetooth' | 'headset';
 
+/** The call waiting beside the current one. */
+export interface WaitingCall {
+  callId: string;
+  conversationId: string | null;
+  conversationName: string | null;
+  callerName: string | null;
+  media: 'audio' | 'video';
+}
+
 /** One place call audio can play. */
 export interface AudioOutput {
   /** Opaque; stable while the device stays connected. */
@@ -122,6 +145,8 @@ interface PoolseCallsNative {
   answer(): void;
   decline(): void;
   hangUp(): void;
+  answerWaiting?(callId: string | null): void;
+  declineWaiting?(callId: string | null): void;
   setMuted(muted: boolean): void;
   setCamera(on: boolean): void;
   switchCamera(): void;
@@ -233,6 +258,16 @@ export async function startRoom(
 export const answer = (): void => native?.answer();
 export const decline = (): void => native?.decline();
 export const hangUp = (): void => native?.hangUp();
+
+/**
+ * Call waiting: end the current call and answer `snapshot.waiting`.
+ * Pass its `callId`: a tap on a card for a call that is no longer the
+ * one waiting is then ignored instead of answering a different call.
+ */
+export const answerWaiting = (callId?: string): void => native?.answerWaiting?.(callId ?? null);
+
+/** Call waiting: turn `snapshot.waiting` away — its caller hears busy. */
+export const declineWaiting = (callId?: string): void => native?.declineWaiting?.(callId ?? null);
 export const setMuted = (muted: boolean): void => native?.setMuted(muted);
 export const setCamera = (on: boolean): void => native?.setCamera(on);
 export const switchCamera = (): void => native?.switchCamera();