@tokamakdev/plugin-location 0.1.0-beta.128 → 0.1.0-beta.129

package/README.md

@@ -52,7 +52,7 @@ default. The timeout starts once the user allows location. Android takes
 positions from its fused provider at high accuracy, which combines GPS with
 Wi-Fi and cell signals.
 
-`watchPosition()` returns a byte stream of JSON positions. `decodeValues<Position>`
+`watchPosition()` resolves to a byte stream of JSON positions. `decodeValues<Position>`
 decodes them. Cancelling the stream ends the native watch; errors terminate it.
 
 Both ask for in-use permission when the user has not answered. Off screen
@@ -134,7 +134,7 @@ event:
 |---|---|
 | `onLocationUpdate` | `{ positions, stationary? }` from updates and significant changes. |
 | `onRegionTransition` | `{ id, transition, timestamp }`, where `transition` is `"enter"` or `"exit"`. |
-| `onVisit` | Apple only: `{ latitude, longitude, accuracy, arrival, departure }`, times in milliseconds or null when unknown. |
+| `onVisit` | Apple only: `{ latitude, longitude, accuracy, arrival, departure }`, times in milliseconds, absent when unknown. |
 | `onLocationError` | `{ name, message, id? }` when a background service fails, with the region's `id` when it concerns one. |
 
 In Doze, the idle state of an unplugged Android device left still with its

package/android/Exports.generated.kt

@@ -0,0 +1,264 @@
+// Generated by `tok plugin generate android`. Do not edit.
+package com.tokamak.plugins.location
+
+import com.tokamak.runtime.TokamakDispatch
+import com.tokamak.runtime.TokamakHost
+import com.tokamak.runtime.TokamakPluginBytesReply
+import com.tokamak.runtime.TokamakPluginError
+import com.tokamak.runtime.TokamakValue
+import kotlin.reflect.KClass
+import org.json.JSONArray
+import org.json.JSONObject
+
+/** Routes the Worker's requests to the methods [TokamakLocationPlugin] exports, and encodes the events it emits. */
+class TokamakLocationPluginDispatch(host: TokamakHost) : TokamakDispatch<TokamakLocationPlugin>(TokamakLocationPlugin(host), host) {
+    override fun callBytes(method: String, payload: ByteArray, reply: TokamakPluginBytesReply): (() -> Unit)? {
+        val arguments by lazy(LazyThreadSafetyMode.NONE) { TokamakValue.arguments(payload) }
+        return when (method) {
+            "setup" -> respond(reply) { plugin.setup(config = arguments["config"].asSetupConfig()) }
+            "recentPosition" -> respond(reply) {
+                val result = plugin.recentPosition(
+                    maximumAge = arguments["maximumAge"].double(),
+                )
+                result?.let { json(it) }
+            }
+            "currentPosition" -> launch(method, reply) { plugin.currentPosition()?.let { json(it) } }
+            "permission" -> respond(reply) { json(plugin.permission()) }
+            "requestPermission" -> launch(method, reply) {
+                val result = plugin.requestPermission(
+                    request = arguments["request"].nullable { it.asPermissionRequest() },
+                )
+                json(result)
+            }
+            "servicesEnabled" -> respond(reply) { plugin.servicesEnabled() }
+            "openSettings" -> respond(reply) { plugin.openSettings() }
+            "startUpdates" -> respond(reply) {
+                plugin.startUpdates(
+                    options = arguments["options"].nullable { it.asUpdateOptions() },
+                )
+            }
+            "stopUpdates" -> respond(reply) { plugin.stopUpdates() }
+            "getUpdates" -> respond(reply) { plugin.getUpdates()?.let { json(it) } }
+            "addRegion" -> respond(reply) { plugin.addRegion(region = arguments["region"].asRegion()) }
+            "getRegions" -> respond(reply) { JSONArray(plugin.getRegions().map { json(it) }) }
+            "removeRegion" -> respond(reply) { plugin.removeRegion(id = arguments["id"].string()) }
+            else -> throw TokamakPluginError.notSupported("$id.$method is not supported")
+        }
+    }
+
+    override fun subscribeBytes(method: String, payload: ByteArray, reply: TokamakPluginBytesReply): () -> Unit {
+        return when (method) {
+            "watchPosition" -> collect(method, reply, plugin.watchPosition()) { json(it) }
+            "onLocationUpdate" -> collect(method, reply, plugin.onLocationUpdate()) { json(it) }
+            "onRegionTransition" -> collect(method, reply, plugin.onRegionTransition()) { json(it) }
+            "onLocationError" -> collect(method, reply, plugin.onLocationError()) { json(it) }
+            else -> throw TokamakPluginError.notSupported("$id.$method is not supported")
+        }
+    }
+
+    override fun eventPayload(name: String, event: Any): ByteArray =
+        when (name) {
+            "update" -> encodeEvent(name, event, LocationUpdate::class) { json(it) }
+            "region" -> encodeEvent(name, event, RegionTransition::class) { json(it) }
+            "error" -> encodeEvent(name, event, LocationErrorEvent::class) { json(it) }
+            else -> super.eventPayload(name, event)
+        }
+
+    override fun encodeValue(value: Any): Any =
+        when (value) {
+            is Coordinates -> json(value)
+            is LocationErrorEvent -> json(value)
+            is LocationPermission -> json(value)
+            is LocationUpdate -> json(value)
+            is MonitoredRegion -> json(value)
+            is PermissionRequest -> json(value)
+            is Position -> json(value)
+            is Region -> json(value)
+            is RegionTransition -> json(value)
+            is ServiceNotification -> json(value)
+            is SetupConfig -> json(value)
+            is UpdateOptions -> json(value)
+            else -> super.encodeValue(value)
+        }
+
+    override fun decodeValue(json: TokamakValue, type: KClass<*>): Any =
+        when (type) {
+            Coordinates::class -> json.asCoordinates()
+            LocationErrorEvent::class -> json.asLocationErrorEvent()
+            LocationPermission::class -> json.asLocationPermission()
+            LocationUpdate::class -> json.asLocationUpdate()
+            MonitoredRegion::class -> json.asMonitoredRegion()
+            PermissionRequest::class -> json.asPermissionRequest()
+            Position::class -> json.asPosition()
+            Region::class -> json.asRegion()
+            RegionTransition::class -> json.asRegionTransition()
+            ServiceNotification::class -> json.asServiceNotification()
+            SetupConfig::class -> json.asSetupConfig()
+            UpdateOptions::class -> json.asUpdateOptions()
+            else -> super.decodeValue(json, type)
+        }
+
+    private fun TokamakValue.asCoordinates(): Coordinates =
+        Coordinates(
+            latitude = this["latitude"].double(),
+            longitude = this["longitude"].double(),
+            accuracy = this["accuracy"].double(),
+            altitude = this["altitude"].nullable { it.double() },
+            altitudeAccuracy = this["altitudeAccuracy"].nullable { it.double() },
+            heading = this["heading"].nullable { it.double() },
+            speed = this["speed"].nullable { it.double() },
+        )
+
+    private fun json(value: Coordinates): JSONObject =
+        JSONObject()
+            .put("latitude", value.latitude)
+            .put("longitude", value.longitude)
+            .put("accuracy", value.accuracy)
+            .putOpt("altitude", value.altitude)
+            .putOpt("altitudeAccuracy", value.altitudeAccuracy)
+            .putOpt("heading", value.heading)
+            .putOpt("speed", value.speed)
+
+    private fun TokamakValue.asLocationErrorEvent(): LocationErrorEvent =
+        LocationErrorEvent(
+            name = this["name"].string(),
+            message = this["message"].string(),
+        )
+
+    private fun json(value: LocationErrorEvent): JSONObject =
+        JSONObject()
+            .put("name", value.name)
+            .put("message", value.message)
+
+    private fun TokamakValue.asLocationPermission(): LocationPermission =
+        LocationPermission(
+            inUse = this["inUse"].enum(Permission.entries),
+            background = this["background"].enum(Permission.entries),
+            precision = this["precision"].enum(Precision.entries),
+        )
+
+    private fun json(value: LocationPermission): JSONObject =
+        JSONObject()
+            .put("inUse", value.inUse.name)
+            .put("background", value.background.name)
+            .put("precision", value.precision.name)
+
+    private fun TokamakValue.asLocationUpdate(): LocationUpdate =
+        LocationUpdate(
+            positions = this["positions"].list { it.asPosition() },
+        )
+
+    private fun json(value: LocationUpdate): JSONObject =
+        JSONObject()
+            .put("positions", JSONArray(value.positions.map { json(it) }))
+
+    private fun TokamakValue.asMonitoredRegion(): MonitoredRegion =
+        MonitoredRegion(
+            id = this["id"].string(),
+            latitude = this["latitude"].double(),
+            longitude = this["longitude"].double(),
+            radius = this["radius"].double(),
+            onEntry = this["onEntry"].boolean(),
+            onExit = this["onExit"].boolean(),
+        )
+
+    private fun json(value: MonitoredRegion): JSONObject =
+        JSONObject()
+            .put("id", value.id)
+            .put("latitude", value.latitude)
+            .put("longitude", value.longitude)
+            .put("radius", value.radius)
+            .put("onEntry", value.onEntry)
+            .put("onExit", value.onExit)
+
+    private fun TokamakValue.asPermissionRequest(): PermissionRequest =
+        PermissionRequest(
+            background = this["background"].nullable { it.boolean() },
+            precision = this["precision"].nullable { it.enum(Precision.entries) },
+        )
+
+    private fun json(value: PermissionRequest): JSONObject =
+        JSONObject()
+            .putOpt("background", value.background)
+            .putOpt("precision", value.precision?.name)
+
+    private fun TokamakValue.asPosition(): Position =
+        Position(
+            coords = this["coords"].asCoordinates(),
+            timestamp = this["timestamp"].long(),
+        )
+
+    private fun json(value: Position): JSONObject =
+        JSONObject()
+            .put("coords", json(value.coords))
+            .put("timestamp", value.timestamp)
+
+    private fun TokamakValue.asRegion(): Region =
+        Region(
+            id = this["id"].string(),
+            latitude = this["latitude"].double(),
+            longitude = this["longitude"].double(),
+            radius = this["radius"].double(),
+            onEntry = this["onEntry"].nullable { it.boolean() },
+            onExit = this["onExit"].nullable { it.boolean() },
+        )
+
+    private fun json(value: Region): JSONObject =
+        JSONObject()
+            .put("id", value.id)
+            .put("latitude", value.latitude)
+            .put("longitude", value.longitude)
+            .put("radius", value.radius)
+            .putOpt("onEntry", value.onEntry)
+            .putOpt("onExit", value.onExit)
+
+    private fun TokamakValue.asRegionTransition(): RegionTransition =
+        RegionTransition(
+            id = this["id"].string(),
+            transition = this["transition"].enum(Transition.entries),
+            timestamp = this["timestamp"].long(),
+        )
+
+    private fun json(value: RegionTransition): JSONObject =
+        JSONObject()
+            .put("id", value.id)
+            .put("transition", value.transition.name)
+            .put("timestamp", value.timestamp)
+
+    private fun TokamakValue.asServiceNotification(): ServiceNotification =
+        ServiceNotification(
+            title = this["title"].string(),
+            body = this["body"].string(),
+            channel = this["channel"].string(),
+        )
+
+    private fun json(value: ServiceNotification): JSONObject =
+        JSONObject()
+            .put("title", value.title)
+            .put("body", value.body)
+            .put("channel", value.channel)
+
+    private fun TokamakValue.asSetupConfig(): SetupConfig =
+        SetupConfig(
+            significantChanges = this["significantChanges"].nullable { it.boolean() },
+        )
+
+    private fun json(value: SetupConfig): JSONObject =
+        JSONObject()
+            .putOpt("significantChanges", value.significantChanges)
+
+    private fun TokamakValue.asUpdateOptions(): UpdateOptions =
+        UpdateOptions(
+            accuracy = this["accuracy"].nullable { it.enum(Accuracy.entries) },
+            distance = this["distance"].nullable { it.double() },
+            interval = this["interval"].nullable { it.long() },
+            foregroundService = this["foregroundService"].nullable { it.asServiceNotification() },
+        )
+
+    private fun json(value: UpdateOptions): JSONObject =
+        JSONObject()
+            .putOpt("accuracy", value.accuracy?.name)
+            .putOpt("distance", value.distance)
+            .putOpt("interval", value.interval)
+            .putOpt("foregroundService", value.foregroundService?.let { json(it) })
+}

package/android/Exports.kt

@@ -0,0 +1,30 @@
+package com.tokamak.plugins.location
+
+import com.tokamak.runtime.TokamakExporter
+import com.tokamak.runtime.TokamakExports
+import com.tokamak.runtime.TokamakOverflow
+
+object LocationExports : TokamakExports<TokamakLocationPlugin> {
+    override fun exports(e: TokamakExporter<TokamakLocationPlugin>) {
+        e.call(TokamakLocationPlugin::setup, doc = "Applies long-term location awareness, replacing the previous configuration.")
+        e.call(TokamakLocationPlugin::recentPosition, doc = "The provider's last known position, when it is no older than `maximumAge`.")
+        e.call(TokamakLocationPlugin::currentPosition, doc = "A new fix, or null when Android finds none. Cancelling the call stops locating.")
+        e.stream(TokamakLocationPlugin::watchPosition, overflow = TokamakOverflow.DROP_OLDEST, doc = "Positions as the device moves.")
+        e.call(TokamakLocationPlugin::permission, doc = "The app's in-use and background permission, and the precision it gets.")
+        e.call(TokamakLocationPlugin::requestPermission, doc = "Asks for the permission `request` names where the user has not answered.")
+        e.call(TokamakLocationPlugin::servicesEnabled, doc = "Whether location services are on for the device.")
+        e.call(TokamakLocationPlugin::openSettings, doc = "Opens the app's page in the system settings.")
+        e.call(TokamakLocationPlugin::startUpdates, doc = "Starts continuous updates, replacing any running, until `stopUpdates`.")
+        e.call(TokamakLocationPlugin::stopUpdates)
+        e.call(TokamakLocationPlugin::getUpdates, doc = "The options of the running updates, or null when none are running.")
+        e.call(TokamakLocationPlugin::addRegion, doc = "Monitors a circular region, replacing one with the same `id`.")
+        e.call(TokamakLocationPlugin::getRegions, doc = "The monitored regions.")
+        e.call(TokamakLocationPlugin::removeRegion)
+        e.stream(TokamakLocationPlugin::onLocationUpdate, overflow = TokamakOverflow.DROP_OLDEST, doc = "The updates the Worker's listeners receive.")
+        e.stream(TokamakLocationPlugin::onRegionTransition, doc = "The transitions the Worker's listeners receive.")
+        e.stream(TokamakLocationPlugin::onLocationError, doc = "The failures the Worker's listeners receive.")
+        e.event("update", LocationUpdate::class, doc = "Receives continuous updates and significant changes, including those that start the app.")
+        e.event("region", RegionTransition::class, doc = "Receives each region entry or exit, including one that starts the app.")
+        e.event("error", LocationErrorEvent::class, doc = "Receives failures of background services, such as a region Android cannot monitor.")
+    }
+}

package/android/LocationEvents.kt

@@ -2,83 +2,69 @@ package com.tokamak.plugins.location
 
 import android.util.Log
 import com.tokamak.runtime.TokamakHost
+import com.tokamak.runtime.TokamakListeners
 import com.tokamak.runtime.TokamakPluginError
-import com.tokamak.runtime.TokamakPluginReply
-import org.json.JSONArray
-import org.json.JSONObject
 
 /** How long the Worker's listeners have for an event, within the time Android gives a broadcast. */
 private const val EVENT_DEADLINE_MILLIS = 8_000L
 
-/** The listener methods, which receive the Worker's events. */
-private val LISTENERS = setOf("onLocationUpdate", "onRegionTransition", "onVisit", "onLocationError")
-
 /** Delivers the plugin's events to the Worker's listeners and the page's. Use it on the main thread. */
 internal class LocationEvents(private val host: TokamakHost) {
-    private val listeners = mutableMapOf<String, MutableMap<Int, TokamakPluginReply>>()
-    private var nextListener = 0
+    val updates = TokamakListeners<LocationUpdate>()
+    val transitions = TokamakListeners<RegionTransition>()
+    val errors = TokamakListeners<LocationErrorEvent>()
 
     /** Positions that arrived while the Worker handled the previous update, and the broadcasts to finish once it has them. */
-    private val positions = mutableListOf<JSONObject>()
+    private val positions = mutableListOf<Position>()
     private val finishes = mutableListOf<() -> Unit>()
     private var updating = false
 
     /** The time of the newest position delivered, as requests that run together receive the same positions. */
     private var latest = Long.MIN_VALUE
 
-    /** Adds a page's or Worker's listener of [method], returning its removal, or null for another method. */
-    fun listen(method: String, reply: TokamakPluginReply): (() -> Unit)? {
-        if (method !in LISTENERS) return null
-        val key = nextListener++
-        listeners.getOrPut(method, ::mutableMapOf)[key] = reply
-        return { listeners[method]?.remove(key) }
-    }
-
     /**
      * Delivers the [received] positions newer than those delivered, then calls [finish]. Positions
      * that arrive while the Worker handles an update reach it together as the next.
      */
-    fun update(received: List<JSONObject>, finish: () -> Unit) {
-        val newer = received.filter { it.getLong("timestamp") > latest }
+    fun update(received: List<Position>, finish: () -> Unit) {
+        val newer = received.filter { it.timestamp > latest }
         if (newer.isEmpty()) return finish()
-        latest = newer.maxOf { it.getLong("timestamp") }
+        latest = newer.maxOf { it.timestamp }
         positions += newer
         finishes += finish
         if (!updating) sendUpdate()
     }
 
     fun transition(id: String, entered: Boolean, finish: () -> Unit) {
-        val event =
-            JSONObject()
-                .put("id", id)
-                .put("transition", if (entered) "enter" else "exit")
-                .put("timestamp", System.currentTimeMillis())
-        send("onRegionTransition", "region", event, finish)
+        val transition = RegionTransition(id, if (entered) Transition.enter else Transition.exit, System.currentTimeMillis())
+        transitions.send(transition)
+        send("region", transition, finish)
     }
 
     /** Reports a background service's failure, then calls [finish]. */
     fun fail(error: TokamakPluginError, finish: () -> Unit = {}) {
-        val event = JSONObject().put("name", error.errorName).put("message", error.message)
-        send("onLocationError", "error", event, finish)
+        val event = LocationErrorEvent(error.errorName, error.message.orEmpty())
+        errors.send(event)
+        send("error", event, finish)
     }
 
     /** Sends the waiting positions as one update, then the positions that arrive meanwhile as the next. */
     private fun sendUpdate() {
         updating = positions.isNotEmpty()
         if (!updating) return
-        val event = JSONObject().put("positions", JSONArray(positions.toList()))
+        val update = LocationUpdate(positions.toList())
         val delivered = finishes.toList()
         positions.clear()
         finishes.clear()
-        send("onLocationUpdate", "update", event) {
+        updates.send(update)
+        send("update", update) {
             delivered.forEach { it() }
             sendUpdate()
         }
     }
 
-    /** Delivers [event] to the page's [method] listeners and the Worker's [name] listeners, then calls [finish]. */
-    private fun send(method: String, name: String, event: JSONObject, finish: () -> Unit) {
-        listeners[method].orEmpty().values.toList().forEach { it(Result.success(event)) }
+    /** Delivers [event] to the Worker's [name] listeners, then calls [finish]. */
+    private fun send(name: String, event: Any, finish: () -> Unit) {
         Thread {
             runCatching { host.emit(name, event, EVENT_DEADLINE_MILLIS) }
                 .onFailure { Log.w("tokamak", "location $name failed: ${it.message}") }