@poolse/react-native-calls 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,151 @@
+package dev.poolse.callcore.android
+
+import dev.poolse.callcore.CallSessionBundle
+import dev.poolse.callcore.HttpPort
+import dev.poolse.callcore.HttpResult
+import java.io.IOException
+import okhttp3.Call
+import okhttp3.Callback
+import okhttp3.MediaType.Companion.toMediaType
+import okhttp3.OkHttpClient
+import okhttp3.Request
+import okhttp3.RequestBody.Companion.toRequestBody
+import okhttp3.Response
+import org.json.JSONObject
+
+/**
+ * The HTTP adapter for the contract's three token doors
+ * (CONTRACT.md §4). Every call is a bare REST request with a bearer
+ * token — no session state, no SDK coupling — so the core can answer a
+ * call on a cold process with nothing but the grant from the push.
+ *
+ * Fire-and-forget methods (`decline`, `hangup`) retry transient
+ * failures a few times on OkHttp's dispatcher; request/response methods
+ * surface `HttpResult` to the runtime, which owns the retry policy for
+ * those (one retry, then media decides).
+ */
+internal class CallHttpClient(
+  private val baseUrl: String,
+  private val client: OkHttpClient = defaultClient(),
+) : HttpPort {
+
+  override fun answer(callId: String, grant: String, cb: (HttpResult) -> Unit) =
+    post("calls/$callId/answer", grant, body = null, cb = cb)
+
+  override fun join(callId: String, sessionToken: String, cb: (HttpResult) -> Unit) =
+    post("calls/$callId/join", sessionToken, body = null, cb = cb)
+
+  override fun place(
+    conversationId: String,
+    media: String,
+    sessionToken: String,
+    cb: (HttpResult) -> Unit,
+  ) = post(
+    "conversations/$conversationId/calls",
+    sessionToken,
+    body = JSONObject().put("media", media),
+    cb = cb,
+  )
+
+  override fun reconnect(callId: String, controlToken: String, cb: (HttpResult) -> Unit) =
+    post("calls/$callId/reconnect", controlToken, body = null, cb = cb)
+
+  override fun decline(callId: String, auth: String, busy: Boolean) =
+    postBestEffort(
+      "calls/$callId/decline",
+      auth,
+      JSONObject().put("reason", if (busy) "busy" else "declined"),
+    )
+
+  override fun hangup(callId: String, controlToken: String) =
+    postBestEffort("calls/$callId/hangup", controlToken, body = null)
+
+  // ── request/response ────────────────────────────────────────────────
+
+  private fun post(path: String, token: String, body: JSONObject?, cb: (HttpResult) -> Unit) {
+    client.newCall(request(path, token, body)).enqueue(object : Callback {
+      override fun onFailure(call: Call, e: IOException) = cb(HttpResult.Timeout)
+
+      override fun onResponse(call: Call, response: Response) {
+        response.use {
+          val payload = it.body?.string()
+          cb(
+            when (it.code) {
+              in 200..299 -> runCatching { HttpResult.Ok(parseBundle(payload)) }
+                .getOrElse { HttpResult.Timeout }
+              410 -> HttpResult.Gone
+              401, 403 -> HttpResult.AuthFailed(reasonOf(payload, it.code))
+              408, 429, in 500..599 -> HttpResult.Timeout
+              else -> HttpResult.AuthFailed("http_${it.code}")
+            },
+          )
+        }
+      }
+    })
+  }
+
+  // ── fire-and-forget with bounded retry ──────────────────────────────
+
+  private fun postBestEffort(path: String, token: String, body: JSONObject?, attempt: Int = 0) {
+    client.newCall(request(path, token, body)).enqueue(object : Callback {
+      override fun onFailure(call: Call, e: IOException) {
+        if (attempt < MAX_BEST_EFFORT_RETRIES) postBestEffort(path, token, body, attempt + 1)
+      }
+
+      override fun onResponse(call: Call, response: Response) {
+        response.use {
+          // 2xx and 4xx are both terminal here — the server either acted
+          // or will never act. Only transient 5xx/timeout retries.
+          if ((it.code == 408 || it.code == 429 || it.code in 500..599) &&
+            attempt < MAX_BEST_EFFORT_RETRIES
+          ) {
+            postBestEffort(path, token, body, attempt + 1)
+          }
+        }
+      }
+    })
+  }
+
+  private fun request(path: String, token: String, body: JSONObject?): Request =
+    Request.Builder()
+      .url("$baseUrl/v1/$path")
+      .header("Authorization", "Bearer $token")
+      .header("Accept", "application/json")
+      .post((body?.toString() ?: "{}").toRequestBody(JSON))
+      .build()
+
+  private fun parseBundle(payload: String?): CallSessionBundle {
+    val root = JSONObject(requireNotNull(payload) { "empty success body" })
+    val call = root.getJSONObject("call")
+    val livekit = root.getJSONObject("livekit")
+    return CallSessionBundle(
+      callId = call.getString("id"),
+      conversationId = call.getString("conversation_id"),
+      conversationName = call.optStringOrNull("conversation_name"),
+      media = call.optString("media", "audio"),
+      created = root.optBoolean("created", true),
+      livekitUrl = livekit.getString("url"),
+      livekitToken = livekit.getString("token"),
+      controlToken = root.getString("control_token"),
+    )
+  }
+
+  private fun reasonOf(payload: String?, code: Int): String =
+    payload?.let { runCatching { JSONObject(it).optStringOrNull("error") }.getOrNull() }
+      ?: "http_$code"
+
+  private fun JSONObject.optStringOrNull(key: String): String? =
+    if (isNull(key)) null else optString(key, "").ifEmpty { null }
+
+  private companion object {
+    const val MAX_BEST_EFFORT_RETRIES = 3
+    val JSON = "application/json; charset=utf-8".toMediaType()
+
+    fun defaultClient(): OkHttpClient = OkHttpClient.Builder()
+      // A call action must not hang the ring surface. Short, deliberate
+      // ceilings; the runtime retries answer/place once on top of these.
+      .callTimeout(java.time.Duration.ofSeconds(12))
+      .connectTimeout(java.time.Duration.ofSeconds(6))
+      .build()
+  }
+}

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

@@ -0,0 +1,99 @@
+package dev.poolse.callcore.android
+
+import com.google.firebase.messaging.FirebaseMessagingService
+import com.google.firebase.messaging.RemoteMessage
+import dev.poolse.callcore.RingContext
+
+/**
+ * Native FCM intake — the point of the whole architecture. A call data
+ * message is handled here, in native code, the instant it arrives: no
+ * headless JS, no boot race, no millisecond budget spent waiting for
+ * Hermes. Non-call messages are forwarded to the host app's own
+ * messaging service (declared via metadata), so chat notifications and
+ * everything else keep working unchanged.
+ *
+ * Contract: data-only messages with `type: "call"` (CONTRACT.md §5).
+ */
+class CallMessagingService : FirebaseMessagingService() {
+
+  override fun onNewToken(token: String) {
+    // Registration is the app's concern (it knows the session); it reads
+    // the fresh token from the bridge's token API. Nothing to do here.
+    forwardToHost { it.onNewToken(token) }
+  }
+
+  override fun onMessageReceived(message: RemoteMessage) {
+    val data = message.data
+    if (data["type"] != "call") {
+      forwardToHost { it.onMessageReceived(message) }
+      return
+    }
+
+    when (data["event"]) {
+      "ring" -> data.toRingContext()?.let { CallCore.get(this).onRing(it) }
+      "ring_ended" -> {
+        val callId = data["call_id"] ?: return
+        CallCore.get(this).onRingEnded(callId, data["reason"] ?: "finished")
+      }
+    }
+  }
+
+  private fun Map<String, String>.toRingContext(): RingContext? {
+    val callId = this["call_id"] ?: return null
+    val conversationId = this["conversation_id"] ?: return null
+    val grant = this["grant"] ?: return null
+    return RingContext(
+      callId = callId,
+      conversationId = conversationId,
+      conversationName = this["conversation_name"]?.ifEmpty { null },
+      callerName = this["caller_name"]?.ifEmpty { null },
+      media = this["media"] ?: "audio",
+      grant = grant,
+      ringDeadlineEpochMs = this["ring_deadline"]?.toLongOrNull() ?: 0L,
+    )
+  }
+
+  /**
+   * Forward to the host app's declared FirebaseMessagingService so its
+   * own (non-call) pushes still arrive. The host names its class in the
+   * manifest: `<meta-data android:name="dev.poolse.callcore.delegate"
+   * android:value="com.app.MyMessagingService"/>`.
+   */
+  private fun forwardToHost(block: (FirebaseMessagingService) -> Unit) {
+    val name = runCatching {
+      packageManager.getServiceInfo(
+        android.content.ComponentName(this, CallMessagingService::class.java),
+        android.content.pm.PackageManager.GET_META_DATA,
+      ).metaData?.getString(DELEGATE_META)
+    }.getOrNull() ?: return
+
+    runCatching {
+      val delegate = Class.forName(name).getDeclaredConstructor().newInstance()
+      if (delegate is FirebaseMessagingService) {
+        // The delegate needs our context to do anything useful; FCM's
+        // base class resolves it from the running service, so we attach
+        // ours. Kept behind runCatching: a misconfigured delegate must
+        // never crash the call path.
+        delegate.attachForDelegation(this)
+        block(delegate)
+      }
+    }
+  }
+
+  private companion object {
+    const val DELEGATE_META = "dev.poolse.callcore.delegate"
+  }
+}
+
+/**
+ * Minimal context attach so a delegated [FirebaseMessagingService] can
+ * run outside its own lifecycle. Uses the base ContextWrapper hook.
+ */
+private fun FirebaseMessagingService.attachForDelegation(host: FirebaseMessagingService) {
+  runCatching {
+    val m = android.content.ContextWrapper::class.java
+      .getDeclaredMethod("attachBaseContext", android.content.Context::class.java)
+    m.isAccessible = true
+    m.invoke(this, host.applicationContext)
+  }
+}

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

@@ -0,0 +1,42 @@
+package dev.poolse.callcore.android
+
+import android.os.Handler
+import android.os.Looper
+import dev.poolse.callcore.TimerPort
+
+/**
+ * The real [TimerPort]: a single main-looper Handler keyed by token, so
+ * the runtime's timers (ring deadline, ended-linger, reconnect budget)
+ * fire on one predictable thread and rescheduling a key cleanly
+ * replaces its pending callback.
+ *
+ * [nowMs] is wall-clock epoch, because the one value it is compared
+ * against — the push's `ring_deadline` — is epoch, minted by the
+ * server (CONTRACT.md §5.1). The actual scheduling delay is handed to
+ * [Handler.postDelayed], which counts down monotonically regardless of
+ * clock changes, so a mid-ring NTP correction shifts the deadline by at
+ * most the drift, never breaks it.
+ */
+internal class HandlerTimerPort(
+  private val handler: Handler = Handler(Looper.getMainLooper()),
+) : TimerPort {
+
+  private val pending = mutableMapOf<String, Runnable>()
+
+  override fun nowMs(): Long = System.currentTimeMillis()
+
+  override fun schedule(key: String, delayMs: Long, fire: () -> Unit) {
+    cancel(key)
+    val runnable = Runnable {
+      synchronized(pending) { pending.remove(key) }
+      fire()
+    }
+    synchronized(pending) { pending[key] = runnable }
+    handler.postDelayed(runnable, delayMs.coerceAtLeast(0))
+  }
+
+  override fun cancel(key: String) {
+    val runnable = synchronized(pending) { pending.remove(key) } ?: return
+    handler.removeCallbacks(runnable)
+  }
+}

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

@@ -0,0 +1,209 @@
+package dev.poolse.callcore.android
+
+import android.animation.ValueAnimator
+import android.app.Activity
+import android.graphics.Color
+import android.graphics.Typeface
+import android.graphics.drawable.GradientDrawable
+import android.os.Build
+import android.os.Bundle
+import android.view.Gravity
+import android.view.View
+import android.view.WindowManager
+import android.view.animation.LinearInterpolator
+import android.widget.FrameLayout
+import android.widget.LinearLayout
+import android.widget.TextView
+import dev.poolse.callcore.android.AndroidRingSurface.Companion.EXTRA_RING
+
+/**
+ * The full-screen ring a locked phone shows. Native and dependency-free
+ * so it is on screen within the OS's full-screen-intent budget, long
+ * before any JS could load — carrying the call scene's look (dark
+ * 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.
+ */
+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()
+
+  override fun onCreate(savedInstanceState: Bundle?) {
+    super.onCreate(savedInstanceState)
+    showOverKeyguard()
+
+    val ring = intent.getBundleExtra(EXTRA_RING)?.toRingContext()
+    if (ring == null) { finish(); 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))
+  }
+
+  override fun onDestroy() {
+    pulse?.cancel()
+    pulse = null
+    super.onDestroy()
+  }
+
+  private fun showOverKeyguard() {
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O_MR1) {
+      setShowWhenLocked(true)
+      setTurnScreenOn(true)
+    } else {
+      @Suppress("DEPRECATION")
+      window.addFlags(
+        WindowManager.LayoutParams.FLAG_SHOW_WHEN_LOCKED or
+          WindowManager.LayoutParams.FLAG_TURN_SCREEN_ON,
+      )
+    }
+    window.addFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON)
+  }
+
+  private fun buildScene(title: String, body: String, ring: dev.poolse.callcore.RingContext): View {
+    val root = FrameLayout(this).apply { setBackgroundColor(Color.parseColor("#0B0B14")) }
+
+    root.addView(
+      View(this).apply {
+        background = GradientDrawable(
+          GradientDrawable.Orientation.TOP_BOTTOM,
+          intArrayOf(Color.parseColor("#875B54E8"), Color.parseColor("#000B0B14")),
+        ).apply {
+          gradientType = GradientDrawable.RADIAL_GRADIENT
+          gradientRadius = 560 * density
+          setGradientCenter(0.5f, 0.3f)
+        }
+      },
+      FrameLayout.LayoutParams.MATCH_PARENT, FrameLayout.LayoutParams.MATCH_PARENT,
+    )
+
+    val column = LinearLayout(this).apply {
+      orientation = LinearLayout.VERTICAL
+      gravity = Gravity.CENTER_HORIZONTAL
+      setPadding(px(32), px(110), px(32), px(72))
+    }
+
+    val stage = FrameLayout(this).apply {
+      layoutParams = LinearLayout.LayoutParams(px(176), px(176)).apply { bottomMargin = px(30) }
+    }
+    val ringView = View(this).apply {
+      background = GradientDrawable().apply {
+        shape = GradientDrawable.OVAL
+        setColor(Color.TRANSPARENT)
+        setStroke(px(2), Color.parseColor("#805B54E8"))
+      }
+    }
+    stage.addView(ringView, FrameLayout.LayoutParams(px(176), px(176), Gravity.CENTER))
+    stage.addView(
+      TextView(this).apply {
+        text = title.trim().take(1).uppercase()
+        textSize = 48f
+        setTextColor(Color.WHITE)
+        typeface = Typeface.create(Typeface.DEFAULT, Typeface.BOLD)
+        gravity = Gravity.CENTER
+        background = GradientDrawable(
+          GradientDrawable.Orientation.TL_BR,
+          intArrayOf(Color.parseColor("#7D76FF"), Color.parseColor("#5B54E8")),
+        ).apply { shape = GradientDrawable.OVAL }
+      },
+      FrameLayout.LayoutParams(px(124), px(124), Gravity.CENTER),
+    )
+
+    val name = TextView(this).apply {
+      text = title
+      textSize = 32f
+      setTextColor(Color.WHITE)
+      typeface = Typeface.create(Typeface.DEFAULT, Typeface.BOLD)
+      gravity = Gravity.CENTER
+    }
+    val sub = TextView(this).apply {
+      text = body
+      textSize = 15f
+      setTextColor(Color.parseColor("#B8B8C6"))
+      gravity = Gravity.CENTER
+      background = GradientDrawable().apply {
+        cornerRadius = 999f
+        setColor(Color.parseColor("#14FFFFFF"))
+      }
+      setPadding(px(16), px(8), px(16), px(8))
+      layoutParams = LinearLayout.LayoutParams(wrap(), wrap()).apply { topMargin = px(12) }
+    }
+
+    val buttons = LinearLayout(this).apply {
+      orientation = LinearLayout.HORIZONTAL
+      gravity = Gravity.CENTER
+      layoutParams = LinearLayout.LayoutParams(LinearLayout.LayoutParams.MATCH_PARENT, wrap())
+    }
+    val decline = actionButton("Decline", "✕", "#EF4444") {
+      CallCore.get(this).onUserDecline(ring); finish()
+    }
+    val accept = actionButton("Answer", "✓", "#22C55E") {
+      CallCore.get(this).onUserAnswer(ring); finish()
+    }
+    buttons.addView(decline, LinearLayout.LayoutParams(wrap(), wrap()).apply { rightMargin = px(52) })
+    buttons.addView(accept, LinearLayout.LayoutParams(wrap(), wrap()).apply { leftMargin = px(52) })
+
+    column.addView(stage)
+    column.addView(name)
+    column.addView(sub)
+    column.addView(View(this).apply { layoutParams = LinearLayout.LayoutParams(0, 0, 1f) })
+    column.addView(buttons)
+    root.addView(
+      column,
+      FrameLayout.LayoutParams(FrameLayout.LayoutParams.MATCH_PARENT, FrameLayout.LayoutParams.MATCH_PARENT),
+    )
+
+    pulse = ValueAnimator.ofFloat(0f, 1f).apply {
+      duration = 1800
+      repeatCount = ValueAnimator.INFINITE
+      interpolator = LinearInterpolator()
+      addUpdateListener {
+        val t = it.animatedValue as Float
+        ringView.scaleX = 1f + 0.28f * t
+        ringView.scaleY = 1f + 0.28f * t
+        ringView.alpha = 1f - t
+      }
+      start()
+    }
+    return root
+  }
+
+  private fun actionButton(
+    label: String,
+    glyph: String,
+    color: String,
+    onClick: () -> Unit,
+  ): LinearLayout = LinearLayout(this).apply {
+    orientation = LinearLayout.VERTICAL
+    gravity = Gravity.CENTER_HORIZONTAL
+    addView(
+      TextView(this@IncomingCallActivity).apply {
+        text = glyph
+        textSize = 30f
+        setTextColor(Color.WHITE)
+        gravity = Gravity.CENTER
+        background = GradientDrawable().apply {
+          shape = GradientDrawable.OVAL
+          setColor(Color.parseColor(color))
+        }
+        layoutParams = LinearLayout.LayoutParams(px(82), px(82))
+        isClickable = true
+        isFocusable = true
+        setOnClickListener { onClick() }
+      },
+    )
+    addView(
+      TextView(this@IncomingCallActivity).apply {
+        text = label
+        textSize = 14f
+        setTextColor(Color.parseColor("#B8B8C6"))
+        gravity = Gravity.CENTER
+        layoutParams = LinearLayout.LayoutParams(wrap(), wrap()).apply { topMargin = px(10) }
+      },
+    )
+  }
+
+  private fun wrap() = LinearLayout.LayoutParams.WRAP_CONTENT
+}

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

@@ -0,0 +1,42 @@
+package dev.poolse.callcore.android
+
+import android.os.Bundle
+import dev.poolse.callcore.RingContext
+
+/**
+ * [RingContext] ⇄ [Bundle]. A ring crosses process boundaries as
+ * PendingIntent extras (the notification lives on even when our process
+ * is dead), so it must round-trip through a Bundle losslessly.
+ */
+internal fun RingContext.toBundle(): Bundle = Bundle().apply {
+  putString(K_CALL_ID, callId)
+  putString(K_CONVERSATION_ID, conversationId)
+  putString(K_CONVERSATION_NAME, conversationName)
+  putString(K_CALLER_NAME, callerName)
+  putString(K_MEDIA, media)
+  putString(K_GRANT, grant)
+  putLong(K_DEADLINE, ringDeadlineEpochMs)
+}
+
+internal fun Bundle.toRingContext(): RingContext? {
+  val callId = getString(K_CALL_ID) ?: return null
+  val conversationId = getString(K_CONVERSATION_ID) ?: return null
+  val grant = getString(K_GRANT) ?: return null
+  return RingContext(
+    callId = callId,
+    conversationId = conversationId,
+    conversationName = getString(K_CONVERSATION_NAME),
+    callerName = getString(K_CALLER_NAME),
+    media = getString(K_MEDIA) ?: "audio",
+    grant = grant,
+    ringDeadlineEpochMs = getLong(K_DEADLINE),
+  )
+}
+
+private const val K_CALL_ID = "callId"
+private const val K_CONVERSATION_ID = "conversationId"
+private const val K_CONVERSATION_NAME = "conversationName"
+private const val K_CALLER_NAME = "callerName"
+private const val K_MEDIA = "media"
+private const val K_GRANT = "grant"
+private const val K_DEADLINE = "ringDeadline"

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

@@ -0,0 +1,57 @@
+package dev.poolse.callcore.android
+
+import dev.poolse.callcore.Direction
+import dev.poolse.callcore.MachineState
+import dev.poolse.callcore.Phase
+
+/**
+ * The one place a [MachineState] becomes the contract's `Snapshot`
+ * (CONTRACT.md §8). Both the Android bridge and — mirrored — the JS
+ * machine produce this exact shape, so a UI reads identically wherever
+ * it runs. Returns `null` for idle: the bridge maps that to a cleared
+ * call state.
+ *
+ * The participant roster is merged in by the bridge from the media
+ * adapter's reports; the machine itself does not carry it.
+ */
+internal fun MachineState.toSnapshot(
+  conversationName: String? = null,
+  participants: List<Map<String, Any>> = emptyList(),
+  audioRoute: String = "earpiece",
+  mutedSelf: Boolean = false,
+  cameraOn: Boolean = false,
+): Map<String, Any?>? {
+  if (phase == Phase.IDLE) return null
+  return mapOf(
+    "cv" to 1,
+    "callId" to callId,
+    "conversationId" to conversationId,
+    "conversationName" to conversationName,
+    "direction" to (direction?.wire ?: Direction.INCOMING.wire),
+    "media" to media,
+    "phase" to phase.wire,
+    "reason" to reason?.wire,
+    "participants" to participants,
+    "audioRoute" to audioRoute,
+    "mutedSelf" to mutedSelf,
+    "cameraOn" to cameraOn,
+  )
+}
+
+private val Phase.wire: String
+  get() = when (this) {
+    Phase.IDLE -> "idle"
+    Phase.RINGING_IN -> "ringing_in"
+    Phase.RINGING_OUT -> "ringing_out"
+    Phase.CONNECTING -> "connecting"
+    Phase.ACTIVE -> "active"
+    Phase.RECONNECTING -> "reconnecting"
+    Phase.ENDED -> "ended"
+  }
+
+private val Direction.wire: String
+  get() = when (this) {
+    Direction.INCOMING -> "incoming"
+    Direction.OUTGOING -> "outgoing"
+    Direction.JOINED -> "joined"
+  }

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

@@ -0,0 +1,67 @@
+package expo.modules.poolsecalls
+
+import dev.poolse.callcore.android.CallCore
+import dev.poolse.callcore.android.toSnapshot
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+
+/**
+ * The React Native face of the native call core. Deliberately thin: it
+ * forwards commands to [CallCore] and streams snapshots out. All call
+ * logic lives in the core; this class only crosses the JS boundary.
+ *
+ * `configure` is the single required setup call — the host passes the
+ * API base URL; the icon and ringback resources are resolved by name so
+ * 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.
+ */
+class PoolseCallsModule : Module() {
+
+  override fun definition() = ModuleDefinition {
+    Name("PoolseCalls")
+
+    Events("onCallState")
+
+    // Snapshots → the single JS event. Null (idle) becomes an explicit
+    // cleared payload so the JS side always has a definite state.
+    OnStartObserving {
+      CallCore.get(context).snapshotListener = { state ->
+        sendEvent("onCallState", mapOf("snapshot" to state.toSnapshot()))
+      }
+    }
+    OnStopObserving {
+      CallCore.get(context).snapshotListener = null
+    }
+
+    AsyncFunction("configure") { apiBaseUrl: String, options: Map<String, Any?>? ->
+      // 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,
+        apiBaseUrl,
+        options?.get("smallIcon") as? String,
+        options?.get("ringback") as? String,
+      )
+    }
+
+    Function("getCallState") {
+      mapOf("snapshot" to CallCore.get(context).snapshot().toSnapshot())
+    }
+
+    AsyncFunction("place") { conversationId: String, media: String, sessionToken: String ->
+      CallCore.get(context).place(conversationId, media, sessionToken)
+    }
+    AsyncFunction("join") { callId: String, conversationId: String?, sessionToken: String ->
+      CallCore.get(context).join(callId, conversationId, sessionToken)
+    }
+    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" }
+}