@tokamakdev/plugin-location 0.1.0-beta.102 → 0.1.0-beta.104

package/android/LocationPlugin.kt

@@ -1,20 +1,29 @@
 package com.tokamak.plugins.location
 
 import android.Manifest
+import android.app.ForegroundServiceStartNotAllowedException
+import android.content.ComponentName
 import android.content.Context
+import android.content.Intent
 import android.content.pm.PackageManager
 import android.location.Location
 import android.location.LocationListener
 import android.location.LocationManager
+import android.net.Uri
 import android.os.Bundle
 import android.os.CancellationSignal
 import android.os.Handler
 import android.os.Looper
 import android.os.SystemClock
+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
 
 class TokamakLocationPlugin(
@@ -27,14 +36,62 @@ class TokamakLocationPlugin(
         context.getSystemService(Context.LOCATION_SERVICE) as LocationManager
     private val handler = Handler(Looper.getMainLooper())
 
+    /** The permissions the app's manifest requests. */
+    private val declared: Set<String> by lazy {
+        context.packageManager
+            .getPackageInfo(context.packageName, PackageManager.GET_PERMISSIONS)
+            .requestedPermissions
+            .orEmpty()
+            .toSet()
+    }
+
+    /** Foreground location permissions, which the `precision` build setting declares. */
+    private val foreground: Set<String> by lazy { setOf(COARSE, FINE).filter(declared::contains).toSet() }
+
+    private val updates = LocationUpdates(context, LocationUpdates.UPDATES)
+    private val significantChanges = LocationUpdates(context, LocationUpdates.SIGNIFICANT_CHANGES)
+    private val regions = LocationRegions(context)
+    private val events = LocationEvents(host)
+
+    /** Whether the app's manifest declares the foreground service, as the `background-updates` build setting does. */
+    private val declaresService: Boolean by lazy {
+        runCatching { context.packageManager.getServiceInfo(ComponentName(context, TokamakLocationService::class.java), 0) }
+            .isSuccess
+    }
+
+    init {
+        restore(updatesRemoved = false)
+    }
+
+    /** Starts the updates' foreground service again once the app is on screen. */
+    override fun onIntent(intent: Intent) {
+        if (host.isInForeground) startService()
+    }
+
     override fun call(method: String, arguments: Any?, reply: TokamakPluginReply) {
-        if (method != "getCurrentPosition") {
-            super.call(method, arguments, reply)
-            return
-        }
-        val options = arguments as? JSONObject
-        withPermission { granted ->
-            if (granted) currentPosition(options, reply) else reply(permissionDenied())
+        when (method) {
+            "setup" -> setup(requireObject(arguments), reply)
+            "getCurrentPosition" ->
+                withPermission { granted ->
+                    if (granted) currentPosition(arguments as? JSONObject, reply) else reply(Result.failure(permissionDenied()))
+                }
+            "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)
         }
     }
 
@@ -43,12 +100,13 @@ class TokamakLocationPlugin(
         arguments: Any?,
         reply: TokamakPluginReply,
     ): () -> Unit {
+        events.listen(method, reply)?.let { return it }
         if (method != "watchPosition") return super.subscribe(method, arguments, reply)
         var cancelled = false
         var stop = {}
         withPermission { granted ->
             if (!granted) {
-                reply(permissionDenied())
+                reply(Result.failure(permissionDenied()))
             } else if (!cancelled) {
                 stop = watchPosition(reply)
             }
@@ -64,11 +122,169 @@ class TokamakLocationPlugin(
      * Throws `NeedsUIError` when asking would show UI while the app is in the background.
      */
     private fun withPermission(action: (Boolean) -> Unit) {
-        if (PERMISSIONS.any { context.checkSelfPermission(it) == PackageManager.PERMISSION_GRANTED }) {
-            action(true)
-            return
+        if (hasForegroundPermission()) action(true) else askForeground(foreground, action)
+    }
+
+    /**
+     * Asks for the foreground [permissions], then passes [action] whether the app has one, first
+     * starting what waited for permission.
+     */
+    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)
         }
-        host.requestPermissions(PERMISSIONS) { granted -> action(granted.containsValue(true)) }
+    }
+
+    private fun granted(permission: String): Boolean =
+        context.checkSelfPermission(permission) == PackageManager.PERMISSION_GRANTED
+
+    private fun hasForegroundPermission(): Boolean = granted(FINE) || granted(COARSE)
+
+    /** 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"
+        val precise = granted(FINE) || (!granted(COARSE) && FINE in declared)
+        return JSONObject()
+            .put("inUse", inUse)
+            .put("background", background)
+            .put("precision", if (precise) "precise" else "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
+     * Android grants background permission only to an app with foreground permission.
+     */
+    private fun requestPermission(options: JSONObject, reply: TokamakPluginReply) {
+        val background = options.optBoolean("background")
+        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)) }
+        }
+    }
+
+    private fun requirePermission() {
+        if (!hasForegroundPermission()) throw TokamakPluginError("NotAllowedError", "Location permission has not been granted")
+    }
+
+    /** Starts updates in the foreground service when [options] name one, which stops otherwise. On failure, none run. */
+    private fun startUpdates(options: JSONObject, reply: TokamakPluginReply) {
+        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)))
+            }
+    }
+
+    private fun stopUpdates() {
+        updates.stop()
+        TokamakLocationService.stop(context)
+    }
+
+    private fun startService() {
+        updates.options?.optJSONObject("foregroundService")?.let { TokamakLocationService.start(context, it) }
+    }
+
+    /**
+     * 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))) }
+    }
+
+    /**
+     * Throws unless the app declares the foreground service and may start it now: Android 14 and
+     * later allow a location foreground service off screen only with background permission.
+     */
+    private fun requireService() {
+        if (!declaresService) {
+            throw TokamakPluginError.notSupported("The foreground service needs the location plugin's background-updates build setting")
+        }
+        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
+     * or an update with background permission. Reports a failure to `onLocationError`.
+     */
+    internal fun restore(updatesRemoved: Boolean) {
+        if (!hasForegroundPermission()) return
+        runCatching {
+            updates.restore(updatesRemoved)
+            significantChanges.restore(updatesRemoved)
+            if (host.isInForeground || (updatesRemoved && granted(BACKGROUND))) startService()
+        }.onFailure { events.fail(locationError(it)) }
+        runCatching { regions.restore() }.onFailure { events.fail(locationError(it)) }
+    }
+
+    /** Delivers the updates or region transition [intent] carries, then calls [finish]. Call it on the main thread. */
+    internal fun receive(intent: Intent, finish: () -> Unit) {
+        if (intent.action == LocationRegions.REGION_ACTION) return transition(intent, finish)
+        if (intent.hasExtra(LocationManager.KEY_PROVIDER_ENABLED)) {
+            if (intent.getBooleanExtra(LocationManager.KEY_PROVIDER_ENABLED, true)) return finish()
+            return events.fail(TokamakPluginError("NotReadableError", "The location provider was turned off"), finish)
+        }
+        val received = locations(intent).map(::position)
+        if (received.isEmpty()) return finish()
+        events.update(received, finish)
+    }
+
+    /** Delivers a region's entry or exit, when the region reports it. */
+    private fun transition(intent: Intent, finish: () -> Unit) {
+        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()
+        events.transition(id, entered, finish)
+    }
+
+    @Suppress("DEPRECATION")
+    private fun locations(intent: Intent): List<Location> =
+        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))
     }
 
     /**
@@ -147,29 +363,31 @@ class TokamakLocationPlugin(
         ).firstOrNull(manager::isProviderEnabled)
             ?: manager.getProviders(true).firstOrNull()
 
-    private fun position(location: Location): Map<String, Any?> =
-        mapOf(
-            "coords" to
-                mapOf(
-                    "latitude" to location.latitude,
-                    "longitude" to location.longitude,
-                    "accuracy" to location.accuracy.toDouble(),
-                    "altitude" to location.altitude.takeIf { location.hasAltitude() },
-                    "altitudeAccuracy" to
-                        location.verticalAccuracyMeters.toDouble()
-                            .takeIf { location.hasVerticalAccuracy() },
-                    "heading" to location.bearing.toDouble().takeIf { location.hasBearing() },
-                    "speed" to location.speed.toDouble().takeIf { location.hasSpeed() },
-                ),
-            "timestamp" to location.time,
-        )
-
-    private fun permissionDenied(): Result<Any?> =
-        Result.failure(TokamakPluginError("NotAllowedError", "Location permission was denied"))
+    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
+
+    private fun permissionDenied() = TokamakPluginError("NotAllowedError", "Location permission was denied")
 
     /** Why no fix came: Android gives none in the background without background location permission. */
     private fun missingFix(): Result<Any?> =
-        if (host.isInForeground || context.checkSelfPermission(BACKGROUND) == PackageManager.PERMISSION_GRANTED) {
+        if (host.isInForeground || granted(BACKGROUND)) {
             unavailable("Location is unavailable")
         } else {
             Result.failure(TokamakPluginError("NotAllowedError", "Location permission does not cover the background"))
@@ -178,14 +396,24 @@ class TokamakLocationPlugin(
     private fun unavailable(message: String): Result<Any?> =
         Result.failure(TokamakPluginError("NotReadableError", message))
 
-    private fun locationFailure(error: Throwable): Result<Any?> =
-        if (error is SecurityException) permissionDenied()
-        else unavailable(error.message ?: "Location is unavailable")
+    private fun locationFailure(error: Throwable): Result<Any?> = Result.failure(locationError(error))
+
+    private fun locationError(error: Throwable): TokamakPluginError =
+        when (error) {
+            is SecurityException -> permissionDenied()
+            // Off screen, Android starts a foreground service only in response to some events.
+            is ForegroundServiceStartNotAllowedException -> TokamakPluginError.needsUI()
+            else -> TokamakPluginError("NotReadableError", error.message ?: "Location is unavailable")
+        }
 
     private companion object {
         /** The `timeout` that never expires, as the page sends it. */
         const val UNLIMITED = 0xffffffffL
-        val PERMISSIONS = setOf(Manifest.permission.ACCESS_FINE_LOCATION, Manifest.permission.ACCESS_COARSE_LOCATION)
+        const val FINE = Manifest.permission.ACCESS_FINE_LOCATION
+        const val COARSE = Manifest.permission.ACCESS_COARSE_LOCATION
         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}"""
     }
 }

package/android/LocationReceiver.kt

@@ -0,0 +1,27 @@
+package com.tokamak.plugins.location
+
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import com.tokamak.runtime.tokamakPlugin
+
+/** Receives updates and region transitions, which Android sends even after the app's process ended. */
+class TokamakLocationReceiver : BroadcastReceiver() {
+    override fun onReceive(context: Context, intent: Intent) {
+        val plugin = context.tokamakPlugin("location") as? TokamakLocationPlugin ?: return
+        val pending = goAsync()
+        plugin.receive(intent) { pending.finish() }
+    }
+}
+
+/** Requests updates and regions again after a restart or an app update, which remove update requests. */
+class TokamakLocationBootReceiver : BroadcastReceiver() {
+    override fun onReceive(context: Context, intent: Intent) {
+        if (intent.action !in ACTIONS) return
+        (context.tokamakPlugin("location") as? TokamakLocationPlugin)?.restore(updatesRemoved = true)
+    }
+
+    private companion object {
+        val ACTIONS = setOf(Intent.ACTION_BOOT_COMPLETED, Intent.ACTION_MY_PACKAGE_REPLACED)
+    }
+}

package/android/LocationRegions.kt

@@ -0,0 +1,73 @@
+package com.tokamak.plugins.location
+
+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. */
+private const val PREFERENCES = "tokamak.location.regions"
+
+/**
+ * Circular regions, as proximity alerts that `LocationManager` sends to [TokamakLocationReceiver]
+ * through a `PendingIntent` per region, starting the app's process when it has ended. The regions
+ * persist until [remove], and [restore] adds them again where Android removed them. Use it on the
+ * main thread.
+ */
+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 get(id: String): JSONObject? = preferences.getString(id, null)?.let(::JSONObject)
+
+    /**
+     * 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))
+        manager.removeProximityAlert(alert)
+        manager.addProximityAlert(
+            region.getDouble("latitude"),
+            region.getDouble("longitude"),
+            region.getDouble("radius").toFloat(),
+            -1,
+            alert,
+        )
+        preferences.edit().putString(id, region.toString()).apply()
+    }
+
+    fun remove(id: String) {
+        preferences.edit().remove(id).apply()
+        pendingIntent(id, PendingIntent.FLAG_NO_CREATE)?.let {
+            manager.removeProximityAlert(it)
+            it.cancel()
+        }
+    }
+
+    /**
+     * Adds the regions whose `PendingIntent` no longer exists again, as after a restart or Android
+     * 15's force stop. Adding one resets its state. Throws `SecurityException` without precise
+     * location.
+     */
+    fun restore() {
+        all().filter { pendingIntent(it.getString("id"), PendingIntent.FLAG_NO_CREATE) == null }.forEach(::add)
+    }
+
+    /** The region [id]'s `PendingIntent`, mutable so `LocationManager` adds whether the device entered. */
+    private fun pendingIntent(id: String, flags: Int): PendingIntent? =
+        PendingIntent.getBroadcast(
+            context,
+            0,
+            Intent(context, TokamakLocationReceiver::class.java).setAction(REGION_ACTION).setIdentifier(id),
+            flags or PendingIntent.FLAG_MUTABLE,
+        )
+
+    companion object {
+        const val REGION_ACTION = "com.tokamak.plugins.location.REGION"
+    }
+}

package/android/LocationService.kt

@@ -0,0 +1,75 @@
+package com.tokamak.plugins.location
+
+import android.app.Notification
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.app.PendingIntent
+import android.app.Service
+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
+
+/**
+ * Runs while updates have a `foregroundService`. Android neither throttles location for an app with
+ * a location foreground service nor withholds it off screen. The service requests no location
+ * itself, and Android restarts it after ending it for memory.
+ */
+class TokamakLocationService : Service() {
+    override fun onBind(intent: Intent?): IBinder? = null
+
+    /** 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")
+        if (content == null) {
+            stopSelf()
+            return START_NOT_STICKY
+        }
+        startForeground(NOTIFICATION_ID, notification(content), ServiceInfo.FOREGROUND_SERVICE_TYPE_LOCATION)
+        return START_STICKY
+    }
+
+    /** 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)
+        getSystemService(NotificationManager::class.java).createNotificationChannel(channel)
+        val open =
+            packageManager.getLaunchIntentForPackage(packageName)?.let {
+                PendingIntent.getActivity(this, 0, it, PendingIntent.FLAG_IMMUTABLE)
+            }
+        return Notification.Builder(this, CHANNEL)
+            .setSmallIcon(icon())
+            .setContentTitle(content.getString("title"))
+            .setContentText(content.getString("body"))
+            .setContentIntent(open)
+            .setOngoing(true)
+            .build()
+    }
+
+    /** The app's monochrome `drawable/tokamak_notification`, or its launcher icon. */
+    private fun icon(): Int =
+        resources.getIdentifier("tokamak_notification", "drawable", packageName).takeIf { it != 0 }
+            ?: applicationInfo.icon.takeIf { it != 0 }
+            ?: android.R.drawable.sym_def_app_icon
+
+    companion object {
+        /** The start intent's notification, 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())
+            context.startForegroundService(start)
+        }
+
+        fun stop(context: Context) {
+            context.stopService(Intent(context, TokamakLocationService::class.java))
+        }
+    }
+}

package/android/LocationUpdates.kt

@@ -0,0 +1,120 @@
+package com.tokamak.plugins.location
+
+import android.app.ActivityManager
+import android.app.ApplicationExitInfo
+import android.app.PendingIntent
+import android.content.Context
+import android.content.Intent
+import android.location.LocationManager
+import android.location.LocationRequest
+import org.json.JSONObject
+
+/** The JSON of each kind of updates' options, by name. */
+private const val PREFERENCES = "tokamak.location"
+private const val DEFAULT_INTERVAL_MILLIS = 10_000L
+
+private val QUALITIES =
+    mapOf(
+        "high" to LocationRequest.QUALITY_HIGH_ACCURACY,
+        "balanced" to LocationRequest.QUALITY_BALANCED_POWER_ACCURACY,
+        "low" to LocationRequest.QUALITY_LOW_POWER,
+    )
+
+/**
+ * Location updates of one kind, [name]: `startUpdates`' or significant changes'. `LocationManager`
+ * sends them to [TokamakLocationReceiver] through a `PendingIntent`, starting the app's process when
+ * it has ended. Their options persist until [stop], and [restore] requests them where they are not
+ * running. Use it on the main thread.
+ */
+internal class LocationUpdates(private val context: Context, private val name: String) {
+    private val manager = context.getSystemService(LocationManager::class.java)
+    private val preferences = context.getSharedPreferences(PREFERENCES, Context.MODE_PRIVATE)
+
+    /** The options of the updates, or null. */
+    val options: JSONObject?
+        get() = preferences.getString(name, null)?.let(::JSONObject)
+
+    /** Keeps [options], which [restore] requests. */
+    fun keep(options: JSONObject) {
+        preferences.edit().putString(name, options.toString()).apply()
+    }
+
+    /**
+     * Keeps [options] and requests updates with them, replacing others; the same options running
+     * change nothing. Throws `SecurityException` without permission.
+     */
+    fun start(options: JSONObject) {
+        if (options.toString() == preferences.getString(name, null) && isRequested()) return
+        keep(options)
+        request(options)
+    }
+
+    fun stop() {
+        preferences.edit().remove(name).apply()
+        pendingIntent(PendingIntent.FLAG_NO_CREATE)?.let {
+            manager.removeUpdates(it)
+            it.cancel()
+        }
+    }
+
+    /**
+     * Requests the running updates again when Android [removed] the request, when their
+     * `PendingIntent` no longer exists, or after a force stop, which removes the request on Android
+     * 14. Throws `SecurityException` when the app no longer has permission.
+     */
+    fun restore(removed: Boolean) {
+        val options = options ?: return
+        if (removed || forceStopped() || !isRequested()) request(options)
+    }
+
+    private fun isRequested(): Boolean = pendingIntent(PendingIntent.FLAG_NO_CREATE) != null
+
+    /** Whether the app's process last ended by the user's force stop. */
+    private fun forceStopped(): Boolean =
+        context.getSystemService(ActivityManager::class.java)
+            .getHistoricalProcessExitReasons(null, 0, 1)
+            .firstOrNull()
+            ?.reason == ApplicationExitInfo.REASON_USER_REQUESTED
+
+    private fun request(options: JSONObject) {
+        val accuracy = options.optString("accuracy", "high")
+        val request =
+            LocationRequest.Builder(options.optLong("interval", DEFAULT_INTERVAL_MILLIS))
+                .setQuality(QUALITIES[accuracy] ?: LocationRequest.QUALITY_HIGH_ACCURACY)
+                .setMinUpdateDistanceMeters(options.optDouble("distance", 0.0).toFloat())
+                .build()
+        val updates = checkNotNull(pendingIntent(PendingIntent.FLAG_UPDATE_CURRENT))
+        try {
+            manager.requestLocationUpdates(provider(accuracy), request, updates)
+        } catch (error: Exception) {
+            // Without the `PendingIntent`, [restore] requests them again.
+            updates.cancel()
+            throw error
+        }
+    }
+
+    /** The fused provider when the device has one, and otherwise GPS for high accuracy and the network for less. */
+    private fun provider(accuracy: String): String =
+        when {
+            manager.hasProvider(LocationManager.FUSED_PROVIDER) -> LocationManager.FUSED_PROVIDER
+            accuracy == "high" -> LocationManager.GPS_PROVIDER
+            else -> LocationManager.NETWORK_PROVIDER
+        }
+
+    /** The updates' `PendingIntent`, mutable so `LocationManager` adds the locations. */
+    private fun pendingIntent(flags: Int): PendingIntent? =
+        PendingIntent.getBroadcast(
+            context,
+            0,
+            Intent(context, TokamakLocationReceiver::class.java).setAction("com.tokamak.plugins.location.${name.uppercase()}"),
+            flags or PendingIntent.FLAG_MUTABLE,
+        )
+
+    companion object {
+        /** `startUpdates`' updates. */
+        const val UPDATES = "updates"
+
+        /** Significant changes, as `setup` starts them. */
+        const val SIGNIFICANT_CHANGES = "significantChanges"
+    }
+}