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

package/android/LocationPlugin.kt

@@ -13,12 +13,12 @@ import android.provider.Settings
 import com.tokamak.runtime.TokamakHost
 import com.tokamak.runtime.TokamakPlugin
 import com.tokamak.runtime.TokamakPluginError
-import com.tokamak.runtime.TokamakPluginReply
-import com.tokamak.runtime.optionalString
-import com.tokamak.runtime.requireObject
-import com.tokamak.runtime.requireString
-import org.json.JSONArray
-import org.json.JSONObject
+import kotlin.coroutines.cancellation.CancellationException
+import kotlin.coroutines.resume
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.catch
+import kotlinx.coroutines.flow.map
+import kotlinx.coroutines.suspendCancellableCoroutine
 
 class TokamakLocationPlugin(
     private val host: TokamakHost,
@@ -45,6 +45,7 @@ class TokamakLocationPlugin(
     private val significantChanges = LocationUpdates(context, LocationUpdates.SIGNIFICANT_CHANGES)
     private val regions = LocationRegions(context)
     private val events = LocationEvents(host)
+    private val positions = LocationPositions(context, manager)
 
     /** Whether the provider was on when last reported, as each request reports its changes. */
     private var providerEnabled = true
@@ -64,134 +65,119 @@ class TokamakLocationPlugin(
         if (host.isInForeground) startService()
     }
 
-    override fun call(method: String, arguments: Any?, reply: TokamakPluginReply): (() -> Unit)? {
-        when (method) {
-            "setup" -> setup(requireObject(arguments), reply)
-            "permission" -> reply(Result.success(permission()))
-            "requestPermission" -> requestPermission(requireObject(arguments), reply)
-            "servicesEnabled" -> reply(Result.success(manager.isLocationEnabled))
-            "openSettings" -> openSettings(reply)
-            "startUpdates" -> startUpdates(requireObject(arguments), reply)
-            "stopUpdates" -> {
-                stopUpdates()
-                reply(Result.success(null))
-            }
-            "getUpdates" -> reply(Result.success(updates.options))
-            "addRegion" -> addRegion(requireObject(arguments), reply)
-            "getRegions" -> reply(Result.success(JSONArray(regions.all())))
-            "removeRegion" -> {
-                regions.remove(requireObject(arguments).requireString("id"))
-                reply(Result.success(null))
-            }
-            else -> super.call(method, arguments, reply)
-        }
-        return null
-    }
-
-    override fun subscribe(
-        method: String,
-        arguments: Any?,
-        reply: TokamakPluginReply,
-    ): () -> Unit = events.listen(method, reply) ?: super.subscribe(method, arguments, reply)
-
-    /**
-     * Passes [action] whether the app may read fine or coarse location, asking when it may not.
-     * Throws `NeedsUIError` when asking would show UI while the app is in the background.
-     */
     /**
-     * Asks for the foreground [permissions], then passes [action] whether the app has one, first
-     * starting what waited for permission.
+     * Starts significant changes when [config] names them, and stops them otherwise. Without
+     * permission they start once the app has it.
      */
-    private fun askForeground(permissions: Set<String>, action: (Boolean) -> Unit) {
-        host.requestPermissions(permissions) { granted ->
-            val allowed = granted.containsValue(true)
-            if (allowed) restore(updatesRemoved = false)
-            action(allowed)
+    fun setup(config: SetupConfig) =
+        located {
+            when {
+                config.significantChanges != true -> significantChanges.stop()
+                hasForegroundPermission() -> significantChanges.start(SIGNIFICANT_CHANGES)
+                else -> significantChanges.keep(SIGNIFICANT_CHANGES)
+            }
         }
-    }
 
-    private fun granted(permission: String): Boolean =
-        context.checkSelfPermission(permission) == PackageManager.PERMISSION_GRANTED
+    /** The provider's last known position when it is no older than [maximumAge] milliseconds, or null. */
+    fun recentPosition(maximumAge: Double): Position? = located { positions.recent(maximumAge)?.let(::Position) }
 
-    private fun hasForegroundPermission(): Boolean = granted(FINE) || granted(COARSE)
+    /** A new fix, or null when Android finds none. */
+    suspend fun currentPosition(): Position? = located { positions.current()?.let(::Position) }
+
+    /** Each position as the device moves, until the provider turns off. */
+    fun watchPosition(): Flow<Position> = positions.watch().map(::Position).catch { throw locationError(it) }
 
     /** The app's in-use and background permission, and the precision it gets, or would get once allowed. */
-    private fun permission(): JSONObject {
-        val inUse = if (hasForegroundPermission()) "granted" else state(COARSE)
-        val background = if (BACKGROUND in declared) state(BACKGROUND) else "denied"
+    fun permission(): LocationPermission {
+        val inUse = if (hasForegroundPermission()) Permission.granted else state(COARSE)
+        val background = if (BACKGROUND in declared) state(BACKGROUND) else Permission.denied
         val precise = granted(FINE) || (!granted(COARSE) && FINE in declared)
-        return JSONObject()
-            .put("inUse", inUse)
-            .put("background", background)
-            .put("precision", if (precise) "precise" else "approximate")
+        return LocationPermission(inUse, background, if (precise) Precision.precise else Precision.approximate)
     }
 
-    private fun state(permission: String): String =
-        when {
-            granted(permission) -> "granted"
-            host.wouldPrompt(permission) -> "prompt"
-            else -> "denied"
-        }
-
     /**
-     * Asks for foreground permission, then for background permission when [options] ask for it, as
+     * Asks for foreground permission, then for background permission when [request] asks for it, as
      * Android grants background permission only to an app with foreground permission.
      */
-    private fun requestPermission(options: JSONObject, reply: TokamakPluginReply) {
-        val background = options.optBoolean("background")
+    suspend fun requestPermission(request: PermissionRequest?): LocationPermission {
+        val background = request?.background == true
         if (background && BACKGROUND !in declared) {
             throw TokamakPluginError.notSupported("Background location needs the location plugin's background build setting")
         }
-        val asked = if (options.optionalString("precision") == "approximate") setOf(COARSE) else foreground
-        askForeground(asked) { allowed ->
-            if (!background || !allowed) return@askForeground reply(Result.success(permission()))
-            runCatching { host.requestPermissions(setOf(BACKGROUND)) { reply(Result.success(permission())) } }
-                .onFailure { reply(Result.failure(it)) }
-        }
+        val asked = if (request?.precision == Precision.approximate) setOf(COARSE) else foreground
+        val allowed = ask(asked).containsValue(true)
+        if (allowed) restore(updatesRemoved = false)
+        if (background && allowed) ask(setOf(BACKGROUND))
+        return permission()
     }
 
-    private fun requirePermission() {
-        if (!hasForegroundPermission()) throw TokamakPluginError("NotAllowedError", "Location permission has not been granted")
+    fun servicesEnabled(): Boolean = manager.isLocationEnabled
+
+    fun openSettings() {
+        val app = Uri.fromParts("package", context.packageName, null)
+        host.requireForegroundActivity().startActivity(Intent(Settings.ACTION_APPLICATION_DETAILS_SETTINGS, app))
     }
 
     /** Starts updates in the foreground service when [options] name one, which stops otherwise. On failure, none run. */
-    private fun startUpdates(options: JSONObject, reply: TokamakPluginReply) {
+    fun startUpdates(options: UpdateOptions?) {
+        val running = options ?: UpdateOptions(null, null, null, null)
         requirePermission()
-        val notification = options.optJSONObject("foregroundService")
-        if (notification != null) requireService()
-        runCatching {
-            if (notification == null) TokamakLocationService.stop(context) else TokamakLocationService.start(context, notification)
-            updates.start(options)
-        }.onSuccess { reply(Result.success(null)) }
-            .onFailure {
-                stopUpdates()
-                reply(Result.failure(locationError(it)))
-            }
+        if (running.foregroundService != null) requireService()
+        try {
+            if (running.foregroundService == null) TokamakLocationService.stop(context) else TokamakLocationService.start(context, running)
+            updates.start(running)
+        } catch (error: Exception) {
+            stopUpdates()
+            throw locationError(error)
+        }
     }
 
-    private fun stopUpdates() {
+    fun stopUpdates() {
         updates.stop()
         TokamakLocationService.stop(context)
     }
 
-    private fun startService() {
-        updates.options?.optJSONObject("foregroundService")?.let { TokamakLocationService.start(context, it) }
+    fun getUpdates(): UpdateOptions? = updates.options
+
+    /** Monitors a region, which needs precise location. */
+    fun addRegion(region: Region) {
+        if (!granted(FINE)) throw TokamakPluginError("NotAllowedError", "Regions need precise location")
+        located { regions.add(region) }
     }
 
-    /**
-     * Starts significant changes when [config] names them, and stops them otherwise. Without
-     * permission they start once the app has it.
-     */
-    private fun setup(config: JSONObject, reply: TokamakPluginReply) {
-        val options = JSONObject(SIGNIFICANT_CHANGE_OPTIONS)
-        runCatching {
-            when {
-                !config.optBoolean("significantChanges") -> significantChanges.stop()
-                hasForegroundPermission() -> significantChanges.start(options)
-                else -> significantChanges.keep(options)
-            }
-        }.onSuccess { reply(Result.success(null)) }
-            .onFailure { reply(Result.failure(locationError(it))) }
+    fun getRegions(): List<MonitoredRegion> =
+        regions.all().map { MonitoredRegion(it.id, it.latitude, it.longitude, it.radius, it.onEntry ?: true, it.onExit ?: true) }
+
+    fun removeRegion(id: String) = regions.remove(id)
+
+    fun onLocationUpdate(): Flow<LocationUpdate> = events.updates.stream()
+
+    fun onRegionTransition(): Flow<RegionTransition> = events.transitions.stream()
+
+    fun onLocationError(): Flow<LocationErrorEvent> = events.errors.stream()
+
+    /** Asks the user for [permissions], returning whether each is granted. */
+    private suspend fun ask(permissions: Set<String>): Map<String, Boolean> =
+        suspendCancellableCoroutine { continuation -> host.requestPermissions(permissions) { continuation.resume(it) } }
+
+    private fun granted(permission: String): Boolean =
+        context.checkSelfPermission(permission) == PackageManager.PERMISSION_GRANTED
+
+    private fun hasForegroundPermission(): Boolean = granted(FINE) || granted(COARSE)
+
+    private fun state(permission: String): Permission =
+        when {
+            granted(permission) -> Permission.granted
+            host.wouldPrompt(permission) -> Permission.prompt
+            else -> Permission.denied
+        }
+
+    private fun requirePermission() {
+        if (!hasForegroundPermission()) throw TokamakPluginError("NotAllowedError", "Location permission has not been granted")
+    }
+
+    private fun startService() {
+        updates.options?.takeIf { it.foregroundService != null }?.let { TokamakLocationService.start(context, it) }
     }
 
     /**
@@ -205,14 +191,6 @@ class TokamakLocationPlugin(
         if (!host.isInForeground && !granted(BACKGROUND)) throw TokamakPluginError.needsUI()
     }
 
-    /** Monitors a region, which needs precise location. */
-    private fun addRegion(region: JSONObject, reply: TokamakPluginReply) {
-        if (!granted(FINE)) throw TokamakPluginError("NotAllowedError", "Regions need precise location")
-        runCatching { regions.add(region) }
-            .onSuccess { reply(Result.success(null)) }
-            .onFailure { reply(Result.failure(locationError(it))) }
-    }
-
     /**
      * Restores updates, significant changes and regions where the app has permission, as Android
      * pauses them without it, and starts the updates' foreground service on screen, or after a restart
@@ -238,7 +216,7 @@ class TokamakLocationPlugin(
             if (!turnedOff) return finish()
             return events.fail(TokamakPluginError("NotReadableError", "The location provider was turned off"), finish)
         }
-        events.update(locations(intent).map(::position), finish)
+        events.update(locations(intent).map(::Position), finish)
     }
 
     /** Delivers a region's entry or exit, when the region reports it. */
@@ -246,7 +224,7 @@ class TokamakLocationPlugin(
         val id = intent.identifier ?: return finish()
         val entered = intent.getBooleanExtra(LocationManager.KEY_PROXIMITY_ENTERING, false)
         val region = regions.get(id) ?: return finish()
-        if (!region.optBoolean(if (entered) "onEntry" else "onExit", true)) return finish()
+        if ((if (entered) region.onEntry else region.onExit) == false) return finish()
         events.transition(id, entered, finish)
     }
 
@@ -255,36 +233,21 @@ class TokamakLocationPlugin(
         intent.getParcelableArrayExtra(LocationManager.KEY_LOCATIONS)?.filterIsInstance<Location>()
             ?: listOfNotNull(intent.getParcelableExtra(LocationManager.KEY_LOCATION_CHANGED))
 
-    private fun openSettings(reply: TokamakPluginReply) {
-        val app = Uri.fromParts("package", context.packageName, null)
-        host.requireForegroundActivity().startActivity(Intent(Settings.ACTION_APPLICATION_DETAILS_SETTINGS, app))
-        reply(Result.success(null))
-    }
-
-    private fun position(location: Location): JSONObject =
-        JSONObject()
-            .put(
-                "coords",
-                JSONObject()
-                    .put("latitude", location.latitude)
-                    .put("longitude", location.longitude)
-                    .put("accuracy", location.accuracy.toDouble())
-                    .put("altitude", nullable(location.hasAltitude(), location.altitude))
-                    .put(
-                        "altitudeAccuracy",
-                        nullable(location.hasVerticalAccuracy(), location.verticalAccuracyMeters.toDouble()),
-                    )
-                    .put("heading", nullable(location.hasBearing(), location.bearing.toDouble()))
-                    .put("speed", nullable(location.hasSpeed(), location.speed.toDouble())),
-            )
-            .put("timestamp", location.time)
-
-    private fun nullable(available: Boolean, value: Double): Any = if (available) value else JSONObject.NULL
+    /** Runs [operation], translating its failure into the error the Worker receives. */
+    private inline fun <T> located(operation: () -> T): T =
+        try {
+            operation()
+        } catch (error: CancellationException) {
+            throw error
+        } catch (error: Exception) {
+            throw locationError(error)
+        }
 
     private fun permissionDenied() = TokamakPluginError("NotAllowedError", "Location permission was denied")
 
     private fun locationError(error: Throwable): TokamakPluginError =
         when (error) {
+            is TokamakPluginError -> error
             is SecurityException -> permissionDenied()
             // Off screen, Android starts a foreground service only in response to some events.
             is ForegroundServiceStartNotAllowedException -> TokamakPluginError.needsUI()
@@ -297,6 +260,6 @@ class TokamakLocationPlugin(
         const val BACKGROUND = Manifest.permission.ACCESS_BACKGROUND_LOCATION
 
         /** Apple's significant-change service's thresholds: 500 metres or more, at most every 5 minutes, without GPS. */
-        const val SIGNIFICANT_CHANGE_OPTIONS = """{"accuracy":"low","interval":300000,"distance":500}"""
+        val SIGNIFICANT_CHANGES = UpdateOptions(Accuracy.low, distance = 500.0, interval = 300_000, foregroundService = null)
     }
 }

package/android/LocationPositions.kt

@@ -0,0 +1,67 @@
+package com.tokamak.plugins.location
+
+import android.content.Context
+import android.location.Location
+import android.location.LocationListener
+import android.location.LocationManager
+import android.location.LocationRequest
+import android.os.CancellationSignal
+import android.os.SystemClock
+import com.tokamak.runtime.TokamakPluginError
+import kotlin.coroutines.resume
+import kotlinx.coroutines.channels.SendChannel
+import kotlinx.coroutines.channels.awaitClose
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.callbackFlow
+import kotlinx.coroutines.suspendCancellableCoroutine
+
+/**
+ * Positions for `getCurrentPosition` and `watchPosition`, at the provider's highest accuracy, from
+ * the first enabled of the fused provider, which combines GPS with Wi-Fi and cell signals, GPS and
+ * the network, or any other enabled provider. Each throws `SecurityException` without permission.
+ */
+internal class LocationPositions(private val context: Context, private val manager: LocationManager) {
+    /** The provider's last known position when it is no older than [maximumAge] milliseconds. */
+    fun recent(maximumAge: Double): Location? = manager.getLastKnownLocation(provider())?.takeIf { age(it) <= maximumAge }
+
+    /** A new fix, or null when Android finds none. */
+    suspend fun current(): Location? =
+        suspendCancellableCoroutine { continuation ->
+            val signal = CancellationSignal()
+            continuation.invokeOnCancellation { signal.cancel() }
+            manager.getCurrentLocation(provider(), highAccuracy(0), signal, context.mainExecutor) { continuation.resume(it) }
+        }
+
+    /** Each position as the device moves, until the provider turns off. */
+    fun watch(): Flow<Location> =
+        callbackFlow {
+            val listener = Forwarder(this)
+            manager.requestLocationUpdates(provider(), highAccuracy(1000), context.mainExecutor, listener)
+            awaitClose { manager.removeUpdates(listener) }
+        }
+
+    private fun provider(): String =
+        listOf(LocationManager.FUSED_PROVIDER, LocationManager.GPS_PROVIDER, LocationManager.NETWORK_PROVIDER)
+            .firstOrNull(manager::isProviderEnabled)
+            ?: manager.getProviders(true).firstOrNull()
+            ?: throw TokamakPluginError("NotReadableError", "No location provider is available")
+
+    /** A request for the most accurate fixes the provider gives, every [interval] milliseconds. */
+    private fun highAccuracy(interval: Long): LocationRequest =
+        LocationRequest.Builder(interval).setQuality(LocationRequest.QUALITY_HIGH_ACCURACY).build()
+
+    /** The milliseconds since Android took [location]. */
+    private fun age(location: Location): Double =
+        (SystemClock.elapsedRealtimeNanos() - location.elapsedRealtimeNanos) / 1_000_000.0
+}
+
+/** Sends each location to [positions], which a disabled provider closes. */
+private class Forwarder(private val positions: SendChannel<Location>) : LocationListener {
+    override fun onLocationChanged(location: Location) {
+        positions.trySend(location)
+    }
+
+    override fun onProviderDisabled(provider: String) {
+        positions.close(TokamakPluginError("NotReadableError", "Location provider is unavailable"))
+    }
+}

package/android/LocationRegions.kt

@@ -4,9 +4,8 @@ import android.app.PendingIntent
 import android.content.Context
 import android.content.Intent
 import android.location.LocationManager
-import org.json.JSONObject
 
-/** The JSON of each monitored region, as `addRegion` received it, by id. */
+/** The JSON of each monitored region, by id. */
 private const val PREFERENCES = "tokamak.location.regions"
 
 /**
@@ -19,26 +18,19 @@ internal class LocationRegions(private val context: Context) {
     private val manager = context.getSystemService(LocationManager::class.java)
     private val preferences = context.getSharedPreferences(PREFERENCES, Context.MODE_PRIVATE)
 
-    fun all(): List<JSONObject> = preferences.all.values.map { JSONObject(it as String) }
+    fun all(): List<Region> = preferences.all.values.map { Region.from(it as String) }
 
-    fun get(id: String): JSONObject? = preferences.getString(id, null)?.let(::JSONObject)
+    fun get(id: String): Region? = preferences.getString(id, null)?.let(Region::from)
 
     /**
      * Monitors [region], replacing one with the same id. It starts in an unknown state, so a device
      * already inside reports an entry. Throws `SecurityException` without precise location.
      */
-    fun add(region: JSONObject) {
-        val id = region.getString("id")
-        val alert = checkNotNull(pendingIntent(id, PendingIntent.FLAG_UPDATE_CURRENT))
+    fun add(region: Region) {
+        val alert = checkNotNull(pendingIntent(region.id, PendingIntent.FLAG_UPDATE_CURRENT))
         manager.removeProximityAlert(alert)
-        manager.addProximityAlert(
-            region.getDouble("latitude"),
-            region.getDouble("longitude"),
-            region.getDouble("radius").toFloat(),
-            -1,
-            alert,
-        )
-        preferences.edit().putString(id, region.toString()).apply()
+        manager.addProximityAlert(region.latitude, region.longitude, region.radius.toFloat(), -1, alert)
+        preferences.edit().putString(region.id, region.json().toString()).apply()
     }
 
     fun remove(id: String) {
@@ -55,7 +47,7 @@ internal class LocationRegions(private val context: Context) {
      * location.
      */
     fun restore() {
-        all().filter { pendingIntent(it.getString("id"), PendingIntent.FLAG_NO_CREATE) == null }.forEach(::add)
+        all().filter { pendingIntent(it.id, PendingIntent.FLAG_NO_CREATE) == null }.forEach(::add)
     }
 
     /** The region [id]'s `PendingIntent`, mutable so `LocationManager` adds whether the device entered. */

package/android/LocationService.kt

@@ -9,7 +9,6 @@ import android.content.Context
 import android.content.Intent
 import android.content.pm.ServiceInfo
 import android.os.IBinder
-import org.json.JSONObject
 
 private const val CHANNEL = "tokamak.location"
 private const val NOTIFICATION_ID = 1
@@ -25,8 +24,8 @@ class TokamakLocationService : Service() {
     /** Shows the notification the start [intent] carries, or on a restart, the running updates'. */
     override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
         val content =
-            intent?.getStringExtra(NOTIFICATION_EXTRA)?.let(::JSONObject)
-                ?: LocationUpdates(this, LocationUpdates.UPDATES).options?.optJSONObject("foregroundService")
+            intent?.getStringExtra(NOTIFICATION_EXTRA)?.let { UpdateOptions.from(it).foregroundService }
+                ?: LocationUpdates(this, LocationUpdates.UPDATES).options?.foregroundService
         if (content == null) {
             stopSelf()
             return START_NOT_STICKY
@@ -36,8 +35,8 @@ class TokamakLocationService : Service() {
     }
 
     /** The notification [content] describes, in the location channel it names, opening the app. */
-    private fun notification(content: JSONObject): Notification {
-        val channel = NotificationChannel(CHANNEL, content.getString("channel"), NotificationManager.IMPORTANCE_LOW)
+    private fun notification(content: ServiceNotification): Notification {
+        val channel = NotificationChannel(CHANNEL, content.channel, NotificationManager.IMPORTANCE_LOW)
         getSystemService(NotificationManager::class.java).createNotificationChannel(channel)
         val open =
             packageManager.getLaunchIntentForPackage(packageName)?.let {
@@ -45,8 +44,8 @@ class TokamakLocationService : Service() {
             }
         return Notification.Builder(this, CHANNEL)
             .setSmallIcon(icon())
-            .setContentTitle(content.getString("title"))
-            .setContentText(content.getString("body"))
+            .setContentTitle(content.title)
+            .setContentText(content.body)
             .setContentIntent(open)
             .setOngoing(true)
             .build()
@@ -59,12 +58,12 @@ class TokamakLocationService : Service() {
             ?: android.R.drawable.sym_def_app_icon
 
     companion object {
-        /** The start intent's notification, as JSON. */
+        /** The start intent's updates' options, as JSON. */
         private const val NOTIFICATION_EXTRA = "com.tokamak.plugins.location.NOTIFICATION"
 
-        /** Starts the service showing [notification], or shows it in the running service. */
-        fun start(context: Context, notification: JSONObject) {
-            val start = Intent(context, TokamakLocationService::class.java).putExtra(NOTIFICATION_EXTRA, notification.toString())
+        /** Starts the service showing the notification of [options], or shows it in the running service. */
+        fun start(context: Context, options: UpdateOptions) {
+            val start = Intent(context, TokamakLocationService::class.java).putExtra(NOTIFICATION_EXTRA, options.json().toString())
             context.startForegroundService(start)
         }
 

package/android/LocationTypes.kt

@@ -0,0 +1,132 @@
+package com.tokamak.plugins.location
+
+import android.location.Location
+import com.tokamak.runtime.TokamakValue
+import org.json.JSONObject
+
+data class Coordinates(
+    val latitude: Double,
+    val longitude: Double,
+    val accuracy: Double,
+    val altitude: Double?,
+    val altitudeAccuracy: Double?,
+    val heading: Double?,
+    val speed: Double?,
+)
+
+data class Position(val coords: Coordinates, val timestamp: Long) {
+    constructor(location: Location) : this(
+        Coordinates(
+            latitude = location.latitude,
+            longitude = location.longitude,
+            accuracy = location.accuracy.toDouble(),
+            altitude = location.altitude.takeIf { location.hasAltitude() },
+            altitudeAccuracy = location.verticalAccuracyMeters.toDouble().takeIf { location.hasVerticalAccuracy() },
+            heading = location.bearing.toDouble().takeIf { location.hasBearing() },
+            speed = location.speed.toDouble().takeIf { location.hasSpeed() },
+        ),
+        location.time,
+    )
+}
+
+data class LocationUpdate(val positions: List<Position>)
+
+enum class Transition { enter, exit }
+
+data class RegionTransition(val id: String, val transition: Transition, val timestamp: Long)
+
+data class LocationErrorEvent(val name: String, val message: String)
+
+enum class Permission { granted, denied, prompt }
+
+enum class Precision { precise, approximate }
+
+data class LocationPermission(val inUse: Permission, val background: Permission, val precision: Precision)
+
+data class PermissionRequest(val background: Boolean?, val precision: Precision?)
+
+data class SetupConfig(val significantChanges: Boolean?)
+
+/** The request's quality, precision traded against battery use. */
+enum class Accuracy { high, balanced, low }
+
+/** The foreground service's notification, set from JavaScript so apps can translate it. */
+data class ServiceNotification(val title: String, val body: String, val channel: String)
+
+data class UpdateOptions(
+    val accuracy: Accuracy?,
+    /** Metres the device moves before the next update. */
+    val distance: Double?,
+    /** Milliseconds between updates. */
+    val interval: Long?,
+    val foregroundService: ServiceNotification?,
+) {
+    fun json(): JSONObject {
+        val notification =
+            foregroundService?.let { JSONObject().put("title", it.title).put("body", it.body).put("channel", it.channel) }
+        return JSONObject()
+            .putOpt("accuracy", accuracy?.name)
+            .putOpt("distance", distance)
+            .putOpt("interval", interval)
+            .putOpt("foregroundService", notification)
+    }
+
+    companion object {
+        /** The options [json] holds, as [json] wrote them. */
+        fun from(json: String): UpdateOptions {
+            val options = TokamakValue(JSONObject(json), "")
+            return UpdateOptions(
+                accuracy = options["accuracy"].nullable { it.enum(Accuracy.entries) },
+                distance = options["distance"].nullable { it.double() },
+                interval = options["interval"].nullable { it.long() },
+                foregroundService =
+                    options["foregroundService"].nullable {
+                        ServiceNotification(it["title"].string(), it["body"].string(), it["channel"].string())
+                    },
+            )
+        }
+    }
+}
+
+data class Region(
+    val id: String,
+    val latitude: Double,
+    val longitude: Double,
+    /** In metres. */
+    val radius: Double,
+    val onEntry: Boolean?,
+    val onExit: Boolean?,
+) {
+    fun json(): JSONObject =
+        JSONObject()
+            .put("id", id)
+            .put("latitude", latitude)
+            .put("longitude", longitude)
+            .put("radius", radius)
+            .putOpt("onEntry", onEntry)
+            .putOpt("onExit", onExit)
+
+    companion object {
+        /** The region [json] holds, as [json] wrote it. */
+        fun from(json: String): Region {
+            val region = TokamakValue(JSONObject(json), "")
+            return Region(
+                id = region["id"].string(),
+                latitude = region["latitude"].double(),
+                longitude = region["longitude"].double(),
+                radius = region["radius"].double(),
+                onEntry = region["onEntry"].nullable { it.boolean() },
+                onExit = region["onExit"].nullable { it.boolean() },
+            )
+        }
+    }
+}
+
+data class MonitoredRegion(
+    val id: String,
+    val latitude: Double,
+    val longitude: Double,
+    val radius: Double,
+    val onEntry: Boolean,
+    val onExit: Boolean,
+)