@bricks-soft/capacitor-location-tracking 0.0.0-stage → 8.0.1

package/android/src/main/java/com/brickssoft/locationtracking/provider/android/AndroidLocationBackend.kt

@@ -0,0 +1,265 @@
+package com.brickssoft.locationtracking.provider.android
+
+import android.annotation.SuppressLint
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import android.content.IntentFilter
+import android.location.Location
+import android.location.LocationManager
+import android.os.CancellationSignal
+import android.os.Looper
+import androidx.core.content.ContextCompat
+import androidx.core.location.LocationListenerCompat
+import androidx.core.location.LocationManagerCompat
+import androidx.core.location.LocationRequestCompat
+import com.brickssoft.locationtracking.core.ErrorCode
+import com.brickssoft.locationtracking.core.Logger
+import com.brickssoft.locationtracking.core.TrackingException
+import com.brickssoft.locationtracking.model.DesiredAccuracy
+import com.brickssoft.locationtracking.model.ProviderKind
+import com.brickssoft.locationtracking.model.TrackedLocation
+import com.brickssoft.locationtracking.provider.LocationBackend
+import com.brickssoft.locationtracking.provider.LocationListener
+import com.brickssoft.locationtracking.provider.LocationRequestSpec
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.suspendCancellableCoroutine
+import kotlinx.coroutines.withTimeoutOrNull
+import java.util.concurrent.ConcurrentHashMap
+import java.util.concurrent.Executor
+import java.util.concurrent.atomic.AtomicBoolean
+import kotlin.coroutines.resume
+import kotlin.coroutines.resumeWithException
+
+/**
+ * [LocationBackend] over the platform [LocationManager] (through `LocationManagerCompat`), used when neither GMS nor
+ * HMS is available.
+ *
+ * - Provider per accuracy: HIGH uses gps, BALANCED/LOW use network, each falling back to whichever is enabled;
+ *   PASSIVE uses the passive provider (see [LocationProviders.candidates]).
+ * - Updates arrive on the main looper. While any listener is registered, `PROVIDERS_CHANGED_ACTION` moves each
+ *   registration to its best enabled provider.
+ * - A [SecurityException] from the platform surfaces as a [TrackingException] with [ErrorCode.PERMISSION_DENIED].
+ */
+class AndroidLocationBackend(
+    context: Context,
+    private val locationManager: LocationManager? =
+        context.getSystemService(Context.LOCATION_SERVICE) as? LocationManager,
+) : LocationBackend {
+    private val appContext: Context = context.applicationContext ?: context
+    override val kind: ProviderKind = ProviderKind.ANDROID
+
+    /** Serializes (re-)registrations; [registrations] is also read lock-free by the delivery path. */
+    private val lock = Any()
+    private val registrations = ConcurrentHashMap<LocationListener, Registration>()
+    private var providersReceiver: BroadcastReceiver? = null
+
+    override fun requestUpdates(spec: LocationRequestSpec, listener: LocationListener) {
+        val lm = locationManager ?: return Logger.e(TAG, "no LocationManager: cannot request location updates")
+        synchronized(lock) {
+            val providers = LocationProviders.candidates(lm, spec.accuracy)
+            val registration = register(lm, spec, listener, providers)
+                ?: return Logger.e(TAG, "no usable location provider for ${spec.accuracy.wire} (tried $providers)")
+            registrations.put(listener, registration)?.let { unregister(lm, it) }
+            observeProviderChanges()
+            Logger.d(TAG, "requested ${registration.provider} updates: $spec")
+        }
+    }
+
+    override fun removeUpdates(listener: LocationListener) {
+        val lm = locationManager ?: return
+        synchronized(lock) {
+            val registration = registrations.remove(listener) ?: return
+            unregister(lm, registration)
+            if (registrations.isEmpty()) stopObservingProviderChanges()
+        }
+    }
+
+    override suspend fun getLastLocation(): TrackedLocation? {
+        val lm = locationManager ?: return null
+        return LocationProviders.freshestLastKnown(lm)?.let(TrackedLocation::from)
+    }
+
+    /**
+     * Requests one fix from the best enabled provider for [accuracy] (PASSIVE is treated as LOW). The platform gives
+     * up after about 30 s, so the request is repeated until [timeoutMs] elapses. Returns null on timeout or when no
+     * provider is enabled.
+     */
+    override suspend fun getCurrentLocation(accuracy: DesiredAccuracy, timeoutMs: Long): TrackedLocation? {
+        val lm = locationManager ?: return null
+        val effective = if (accuracy == DesiredAccuracy.PASSIVE) DesiredAccuracy.LOW else accuracy
+        return withTimeoutOrNull(timeoutMs.coerceAtLeast(0)) { awaitCurrentLocation(lm, effective) }
+            ?.let(TrackedLocation::from)
+    }
+
+    private suspend fun awaitCurrentLocation(lm: LocationManager, accuracy: DesiredAccuracy): Location? {
+        while (true) {
+            val enabled = LocationProviders.candidates(lm, accuracy, enabledOnly = true)
+            if (enabled.isEmpty()) return null
+            currentLocationFromFirst(lm, enabled)?.let { return it }
+            delay(CURRENT_LOCATION_RETRY_DELAY_MS)
+        }
+    }
+
+    /** Asks the first provider of [providers] that does not refuse with a [SecurityException]. */
+    private suspend fun currentLocationFromFirst(lm: LocationManager, providers: List<String>): Location? {
+        var denied: SecurityException? = null
+        for (provider in providers) {
+            try {
+                return currentLocation(lm, provider)
+            } catch (e: SecurityException) {
+                denied = e
+            } catch (e: IllegalArgumentException) {
+                Logger.w(TAG, "provider $provider rejected getCurrentLocation", e)
+            }
+        }
+        if (denied != null) throw TrackingException(ErrorCode.PERMISSION_DENIED, "Location permission denied", denied)
+        return null
+    }
+
+    @SuppressLint("MissingPermission")
+    private suspend fun currentLocation(lm: LocationManager, provider: String): Location? =
+        suspendCancellableCoroutine { cont ->
+            val signal = CancellationSignal()
+            val resumed = AtomicBoolean(false)
+            cont.invokeOnCancellation { signal.cancel() }
+            try {
+                LocationManagerCompat.getCurrentLocation(lm, provider, signal, DIRECT_EXECUTOR) { location ->
+                    if (resumed.compareAndSet(false, true)) cont.resume(location)
+                }
+            } catch (e: Exception) {
+                if (resumed.compareAndSet(false, true)) cont.resumeWithException(e)
+            }
+        }
+
+    /**
+     * Registers [listener] on the first of [providers] that accepts the request.
+     *
+     * @return null if no provider accepted it for a reason other than permissions.
+     * @throws TrackingException [ErrorCode.PERMISSION_DENIED] if a provider refused with a [SecurityException] and
+     *   no other accepted.
+     */
+    @SuppressLint("MissingPermission")
+    private fun register(
+        lm: LocationManager,
+        spec: LocationRequestSpec,
+        listener: LocationListener,
+        providers: List<String>,
+    ): Registration? {
+        var denied: SecurityException? = null
+        for (provider in providers) {
+            val registration = Registration(listener, spec, provider)
+            try {
+                LocationManagerCompat.requestLocationUpdates(
+                    lm, provider, requestFor(spec), registration, Looper.getMainLooper(),
+                )
+                return registration
+            } catch (e: SecurityException) {
+                Logger.w(TAG, "provider $provider refused location updates", e)
+                denied = e
+            } catch (e: IllegalArgumentException) {
+                Logger.w(TAG, "provider $provider rejected location updates", e)
+            }
+        }
+        if (denied != null) throw TrackingException(ErrorCode.PERMISSION_DENIED, "Location permission denied", denied)
+        return null
+    }
+
+    private fun unregister(lm: LocationManager, registration: Registration) {
+        try {
+            LocationManagerCompat.removeUpdates(lm, registration)
+        } catch (e: Exception) {
+            Logger.w(TAG, "removeUpdates failed for ${registration.provider}", e)
+        }
+    }
+
+    /** Moves every registration whose best enabled provider changed to that provider. Runs on the main thread. */
+    private fun onProvidersChanged() {
+        val lm = locationManager ?: return
+        synchronized(lock) {
+            for ((listener, current) in registrations.entries.toList()) {
+                val best = LocationProviders.candidates(lm, current.spec.accuracy, enabledOnly = true).firstOrNull()
+                if (best == null || best == current.provider) continue
+                val next = try {
+                    register(lm, current.spec, listener, listOf(best))
+                } catch (e: TrackingException) {
+                    null
+                } ?: continue
+                registrations[listener] = next
+                unregister(lm, current)
+                Logger.i(TAG, "location provider changed: ${current.provider} -> $best")
+            }
+        }
+    }
+
+    private fun observeProviderChanges() {
+        if (providersReceiver != null) return
+        val receiver = object : BroadcastReceiver() {
+            override fun onReceive(context: Context, intent: Intent) = onProvidersChanged()
+        }
+        try {
+            ContextCompat.registerReceiver(
+                appContext, receiver, IntentFilter(LocationManager.PROVIDERS_CHANGED_ACTION),
+                ContextCompat.RECEIVER_NOT_EXPORTED,
+            )
+            providersReceiver = receiver
+        } catch (e: Exception) {
+            Logger.w(TAG, "cannot observe location provider changes", e)
+        }
+    }
+
+    private fun stopObservingProviderChanges() {
+        val receiver = providersReceiver ?: return
+        providersReceiver = null
+        try {
+            appContext.unregisterReceiver(receiver)
+        } catch (e: Exception) {
+            Logger.w(TAG, "unregisterReceiver failed", e)
+        }
+    }
+
+    /** One platform registration of [listener] on [provider]; stale ones (replaced or removed) drop their fixes. */
+    private inner class Registration(
+        val listener: LocationListener,
+        val spec: LocationRequestSpec,
+        val provider: String,
+    ) : LocationListenerCompat {
+        override fun onLocationChanged(location: Location) = deliver(listOf(location))
+
+        override fun onLocationChanged(locations: MutableList<Location>) = deliver(locations)
+
+        private fun deliver(locations: List<Location>) {
+            if (locations.isEmpty() || registrations[listener] !== this) return
+            try {
+                listener.onLocations(locations.map(TrackedLocation::from))
+            } catch (e: Exception) {
+                Logger.e(TAG, "location listener failed", e)
+            }
+        }
+    }
+
+    internal companion object {
+        private const val TAG = "LT.AndroidLocation"
+
+        /** Pause between two platform `getCurrentLocation` attempts that returned no fix. */
+        const val CURRENT_LOCATION_RETRY_DELAY_MS = 1_000L
+
+        private val DIRECT_EXECUTOR = Executor { it.run() }
+
+        /** Maps [spec] to a platform request; values are clamped to what `LocationRequestCompat` accepts. */
+        fun requestFor(spec: LocationRequestSpec): LocationRequestCompat {
+            val interval = spec.intervalMs.coerceAtLeast(0)
+            val distance = spec.distanceFilterM.takeIf { it.isFinite() && it > 0f } ?: 0f
+            val quality = when (spec.accuracy) {
+                DesiredAccuracy.HIGH -> LocationRequestCompat.QUALITY_HIGH_ACCURACY
+                DesiredAccuracy.BALANCED -> LocationRequestCompat.QUALITY_BALANCED_POWER_ACCURACY
+                DesiredAccuracy.LOW, DesiredAccuracy.PASSIVE -> LocationRequestCompat.QUALITY_LOW_POWER
+            }
+            return LocationRequestCompat.Builder(interval)
+                .setQuality(quality)
+                .setMinUpdateIntervalMillis(spec.fastestIntervalMs.coerceIn(0, interval))
+                .setMinUpdateDistanceMeters(distance)
+                .build()
+        }
+    }
+}

package/android/src/main/java/com/brickssoft/locationtracking/provider/android/AndroidProviderBundle.kt

@@ -0,0 +1,31 @@
+package com.brickssoft.locationtracking.provider.android
+
+import android.content.Context
+import android.location.LocationManager
+import com.brickssoft.locationtracking.model.ProviderKind
+import com.brickssoft.locationtracking.provider.ActivityBackend
+import com.brickssoft.locationtracking.provider.GeofenceBackend
+import com.brickssoft.locationtracking.provider.LocationBackend
+import com.brickssoft.locationtracking.provider.ProviderBundle
+
+/**
+ * The platform `LocationManager` backends, the fallback when neither GMS nor HMS is usable. Created reflectively via
+ * its public (Context) constructor. Each backend is created once, on first use.
+ */
+class AndroidProviderBundle(context: Context) : ProviderBundle {
+    private val appContext: Context = context.applicationContext ?: context
+    override val kind: ProviderKind = ProviderKind.ANDROID
+
+    private val location by lazy { AndroidLocationBackend(appContext) }
+    private val activity by lazy { AndroidActivityBackend() }
+    private val geofence by lazy { AndroidGeofenceBackend(appContext) }
+
+    /** True if the device has a [LocationManager]. */
+    override fun isAvailable(): Boolean = appContext.getSystemService(Context.LOCATION_SERVICE) is LocationManager
+
+    override fun location(): LocationBackend = location
+
+    override fun activity(): ActivityBackend = activity
+
+    override fun geofence(): GeofenceBackend = geofence
+}

package/android/src/main/java/com/brickssoft/locationtracking/provider/android/LocationProviders.kt

@@ -0,0 +1,98 @@
+package com.brickssoft.locationtracking.provider.android
+
+import android.annotation.SuppressLint
+import android.location.Location
+import android.location.LocationManager
+import android.os.Build
+import androidx.core.location.LocationManagerCompat
+import com.brickssoft.locationtracking.core.ErrorCode
+import com.brickssoft.locationtracking.core.TrackingException
+import com.brickssoft.locationtracking.model.DesiredAccuracy
+
+/** Provider choice and last-known lookups over the platform [LocationManager]. */
+internal object LocationProviders {
+    /** `LocationManager.FUSED_PROVIDER` (public since API 31). */
+    private const val FUSED_PROVIDER = "fused"
+
+    /**
+     * Providers for [accuracy], most preferred first: HIGH prefers gps, BALANCED/LOW prefer network, each falling back
+     * to the other (then `fused` on API 31+); PASSIVE uses only the passive provider.
+     */
+    fun preferred(accuracy: DesiredAccuracy): List<String> {
+        val fused = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) listOf(FUSED_PROVIDER) else emptyList()
+        return when (accuracy) {
+            DesiredAccuracy.HIGH -> listOf(LocationManager.GPS_PROVIDER, LocationManager.NETWORK_PROVIDER) + fused
+            DesiredAccuracy.BALANCED, DesiredAccuracy.LOW ->
+                listOf(LocationManager.NETWORK_PROVIDER, LocationManager.GPS_PROVIDER) + fused
+            DesiredAccuracy.PASSIVE -> listOf(LocationManager.PASSIVE_PROVIDER)
+        }
+    }
+
+    /**
+     * The providers to try for [accuracy], in order: the enabled ones of [preferred], then (unless [enabledOnly]) the
+     * existing but disabled ones; a request on a disabled provider starts delivering once it is enabled. If none of
+     * them exists on the device, the passive provider is the last resort.
+     */
+    fun candidates(lm: LocationManager, accuracy: DesiredAccuracy, enabledOnly: Boolean = false): List<String> {
+        val existing = preferred(accuracy).filter { exists(lm, it) }
+        if (existing.isEmpty()) {
+            val passive = LocationManager.PASSIVE_PROVIDER
+            return if (accuracy != DesiredAccuracy.PASSIVE && exists(lm, passive)) listOf(passive) else emptyList()
+        }
+        val (enabled, disabled) = existing.partition { isEnabled(lm, it) }
+        return if (enabledOnly) enabled else enabled + disabled
+    }
+
+    fun exists(lm: LocationManager, provider: String): Boolean =
+        try {
+            LocationManagerCompat.hasProvider(lm, provider)
+        } catch (e: Exception) {
+            false
+        }
+
+    fun isEnabled(lm: LocationManager, provider: String): Boolean =
+        try {
+            lm.isProviderEnabled(provider)
+        } catch (e: Exception) {
+            false
+        }
+
+    /**
+     * The freshest `getLastKnownLocation` across the enabled providers, or null if none has a fix.
+     *
+     * @throws TrackingException [ErrorCode.PERMISSION_DENIED] if every provider refused with a [SecurityException].
+     */
+    @SuppressLint("MissingPermission")
+    fun freshestLastKnown(lm: LocationManager): Location? {
+        val providers = try {
+            lm.getProviders(true)
+        } catch (e: Exception) {
+            emptyList<String>()
+        }
+        var best: Location? = null
+        var denied: SecurityException? = null
+        var permitted = false
+        for (provider in providers) {
+            val location = try {
+                lm.getLastKnownLocation(provider).also { permitted = true }
+            } catch (e: SecurityException) {
+                denied = e
+                continue
+            } catch (e: IllegalArgumentException) {
+                continue
+            }
+            if (location != null && (best == null || isNewer(location, best))) best = location
+        }
+        if (!permitted && denied != null) {
+            throw TrackingException(ErrorCode.PERMISSION_DENIED, "Location permission denied", denied)
+        }
+        return best
+    }
+
+    /** Compares on the elapsed-realtime clock when both fixes carry it, else on wall time. */
+    fun isNewer(a: Location, b: Location): Boolean {
+        val an = a.elapsedRealtimeNanos
+        val bn = b.elapsedRealtimeNanos
+        return if (an > 0 && bn > 0) an > bn else a.time > b.time
+    }
+}

package/android/src/main/java/com/brickssoft/locationtracking/provider/gms/GmsActivityBackend.kt

@@ -0,0 +1,80 @@
+package com.brickssoft.locationtracking.provider.gms
+
+import android.Manifest
+import android.app.PendingIntent
+import android.content.Context
+import android.content.Intent
+import android.content.pm.PackageManager
+import android.os.Build
+import androidx.core.content.ContextCompat
+import com.brickssoft.locationtracking.core.Constants
+import com.brickssoft.locationtracking.core.Logger
+import com.brickssoft.locationtracking.model.ProviderKind
+import com.brickssoft.locationtracking.provider.ActivityBackend
+import com.google.android.gms.location.ActivityRecognitionClient
+
+/**
+ * Activity recognition through `ActivityRecognitionClient.requestActivityUpdates`. Results arrive at
+ * [GmsActivityReceiver] through a mutable, explicit broadcast PendingIntent.
+ */
+internal class GmsActivityBackend(
+    private val context: Context,
+    private val client: ActivityRecognitionClient,
+) : ActivityBackend {
+    override val kind: ProviderKind = ProviderKind.GMS
+    override val isSupported: Boolean = true
+
+    /**
+     * Returns false if the ACTIVITY_RECOGNITION runtime permission is missing (API 29+) or GMS rejects the call
+     * synchronously. The GMS Task completes later, so an asynchronous rejection can only be logged.
+     */
+    override fun start(intervalMs: Long): Boolean {
+        if (!hasPermission()) {
+            Logger.w(TAG, "activity updates not requested: ACTIVITY_RECOGNITION permission denied")
+            return false
+        }
+        return try {
+            client.requestActivityUpdates(intervalMs.coerceAtLeast(0), pendingIntent(context))
+                .logFailure(TAG, "requestActivityUpdates")
+            Logger.d(TAG, "activity updates requested every $intervalMs ms")
+            true
+        } catch (e: Exception) {
+            Logger.w(TAG, "requestActivityUpdates failed", e)
+            false
+        }
+    }
+
+    /** Removes the updates if their PendingIntent exists (GMS keeps it alive while registered, across restarts). */
+    override fun stop() {
+        try {
+            val pending = existingPendingIntent(context) ?: return
+            client.removeActivityUpdates(pending).logFailure(TAG, "removeActivityUpdates")
+        } catch (e: Exception) {
+            Logger.w(TAG, "removeActivityUpdates failed", e)
+        }
+    }
+
+    private fun hasPermission(): Boolean =
+        Build.VERSION.SDK_INT < Build.VERSION_CODES.Q ||
+            ContextCompat.checkSelfPermission(context, Manifest.permission.ACTIVITY_RECOGNITION) ==
+            PackageManager.PERMISSION_GRANTED
+
+    companion object {
+        private const val TAG = "LT.GmsActivity"
+
+        /** Explicit broadcast to [GmsActivityReceiver]; mutable because GMS fills in the result. */
+        fun pendingIntent(context: Context): PendingIntent =
+            PendingIntent.getBroadcast(context, Constants.RC_GMS_ACTIVITY, intent(context), Constants.piMutable())
+
+        /** The PendingIntent of [pendingIntent] if it exists, without creating it. */
+        fun existingPendingIntent(context: Context): PendingIntent? = PendingIntent.getBroadcast(
+            context,
+            Constants.RC_GMS_ACTIVITY,
+            intent(context),
+            Constants.piMutable() or PendingIntent.FLAG_NO_CREATE,
+        )
+
+        private fun intent(context: Context): Intent =
+            Intent(context, GmsActivityReceiver::class.java).setAction(Constants.ACTION_ACTIVITY)
+    }
+}

package/android/src/main/java/com/brickssoft/locationtracking/provider/gms/GmsActivityReceiver.kt

@@ -0,0 +1,62 @@
+package com.brickssoft.locationtracking.provider.gms
+
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import com.brickssoft.locationtracking.core.Components
+import com.brickssoft.locationtracking.core.Logger
+import com.brickssoft.locationtracking.model.ActivitySample
+import com.brickssoft.locationtracking.model.ActivityType
+import com.brickssoft.locationtracking.provider.ActivitySink
+import com.google.android.gms.location.ActivityRecognitionResult
+import com.google.android.gms.location.DetectedActivity
+
+/**
+ * Receives `ActivityRecognitionResult`s from the PendingIntent of [GmsActivityBackend] and delivers them to the
+ * engine ([ActivitySink]) with `goAsync()` on `Components.scope`.
+ */
+class GmsActivityReceiver internal constructor(
+    private val target: (Context) -> ReceiverTarget<ActivitySink>,
+) : BroadcastReceiver() {
+    constructor() : this({ ctx -> Components.get(ctx).let { ReceiverTarget(it.scope, it.engine) } })
+
+    override fun onReceive(context: Context, intent: Intent) {
+        val samples = parseActivitySamples(intent)
+        if (samples.isEmpty()) return
+        Logger.v(TAG, "activity: $samples")
+        deliverAsync(context, target, TAG, "activity delivery") { it.onActivitySamples(samples) }
+    }
+
+    internal companion object {
+        private const val TAG = "LT.GmsActivity"
+
+        /** The samples in [intent], most probable first; empty if it carries no result. */
+        fun parseActivitySamples(intent: Intent?): List<ActivitySample> {
+            val result = try {
+                intent?.let { ActivityRecognitionResult.extractResult(it) }
+            } catch (e: Exception) {
+                Logger.w(TAG, "unreadable activity result", e)
+                null
+            } ?: return emptyList()
+            return toActivitySamples(result.probableActivities.orEmpty())
+        }
+
+        /** Maps GMS activities, keeping the highest confidence per [ActivityType], sorted by confidence descending. */
+        fun toActivitySamples(activities: List<DetectedActivity>): List<ActivitySample> = activities
+            .map { ActivitySample(mapActivityType(it.type), it.confidence.coerceIn(0, 100)) }
+            .groupBy { it.type }
+            .map { (_, samples) -> samples.maxBy { it.confidence } }
+            .sortedByDescending { it.confidence }
+
+        /** TILTING, UNKNOWN and any future type map to [ActivityType.UNKNOWN]. */
+        fun mapActivityType(type: Int): ActivityType = when (type) {
+            DetectedActivity.IN_VEHICLE -> ActivityType.IN_VEHICLE
+            DetectedActivity.ON_BICYCLE -> ActivityType.ON_BICYCLE
+            DetectedActivity.ON_FOOT -> ActivityType.ON_FOOT
+            DetectedActivity.WALKING -> ActivityType.WALKING
+            DetectedActivity.RUNNING -> ActivityType.RUNNING
+            DetectedActivity.STILL -> ActivityType.STILL
+            else -> ActivityType.UNKNOWN
+        }
+    }
+}

package/android/src/main/java/com/brickssoft/locationtracking/provider/gms/GmsErrors.kt

@@ -0,0 +1,72 @@
+package com.brickssoft.locationtracking.provider.gms
+
+import com.brickssoft.locationtracking.core.ErrorCode
+import com.brickssoft.locationtracking.core.TrackingException
+import com.google.android.gms.common.api.ApiException
+import com.google.android.gms.common.api.CommonStatusCodes
+import com.google.android.gms.location.GeofenceStatusCodes
+
+/** Maps Google Play services failures to [TrackingException]. */
+internal object GmsErrors {
+    /**
+     * - [TrackingException] is returned unchanged.
+     * - [SecurityException] and `GEOFENCE_INSUFFICIENT_LOCATION_PERMISSION` become PERMISSION_DENIED.
+     * - `GEOFENCE_TOO_MANY_GEOFENCES` and `GEOFENCE_TOO_MANY_PENDING_INTENTS` become TOO_MANY_GEOFENCES.
+     * - `TIMEOUT` becomes TIMEOUT; `DEVELOPER_ERROR` and `INTERNAL_ERROR` become INTERNAL.
+     * - Every other [ApiException] (e.g. `GEOFENCE_NOT_AVAILABLE`, `API_NOT_CONNECTED`) and [IllegalStateException]
+     *   (GMS "not connected") become UNAVAILABLE.
+     * - [IllegalArgumentException] (rejected by a GMS builder) becomes INVALID_ARGUMENT; anything else INTERNAL.
+     */
+    fun map(error: Throwable, operation: String): TrackingException = when (error) {
+        is TrackingException -> error
+        is SecurityException -> TrackingException(
+            ErrorCode.PERMISSION_DENIED,
+            "$operation: location permission denied",
+            error,
+        )
+        is ApiException -> TrackingException(
+            codeFor(error.statusCode),
+            "$operation failed: ${describe(error.statusCode)}",
+            error,
+        )
+        is IllegalArgumentException -> TrackingException(
+            ErrorCode.INVALID_ARGUMENT,
+            "$operation: ${error.message ?: "invalid argument"}",
+            error,
+        )
+        is IllegalStateException -> TrackingException(
+            ErrorCode.UNAVAILABLE,
+            "$operation failed: ${reason(error)}",
+            error,
+        )
+        else -> TrackingException(ErrorCode.INTERNAL, "$operation failed: ${reason(error)}", error)
+    }
+
+    /** The [ErrorCode] for a GMS status code (see [map]). */
+    fun codeFor(statusCode: Int): ErrorCode = when (statusCode) {
+        GeofenceStatusCodes.GEOFENCE_INSUFFICIENT_LOCATION_PERMISSION -> ErrorCode.PERMISSION_DENIED
+        GeofenceStatusCodes.GEOFENCE_TOO_MANY_GEOFENCES,
+        GeofenceStatusCodes.GEOFENCE_TOO_MANY_PENDING_INTENTS,
+        -> ErrorCode.TOO_MANY_GEOFENCES
+        CommonStatusCodes.TIMEOUT -> ErrorCode.TIMEOUT
+        CommonStatusCodes.DEVELOPER_ERROR, CommonStatusCodes.INTERNAL_ERROR -> ErrorCode.INTERNAL
+        else -> ErrorCode.UNAVAILABLE
+    }
+
+    /** E.g. `GEOFENCE_TOO_MANY_GEOFENCES (1001)`, with a hint for `GEOFENCE_NOT_AVAILABLE`. */
+    fun describe(statusCode: Int): String {
+        val name = try {
+            GeofenceStatusCodes.getStatusCodeString(statusCode)
+        } catch (e: Exception) {
+            "status"
+        }
+        val hint = if (statusCode == GeofenceStatusCodes.GEOFENCE_NOT_AVAILABLE) {
+            "; location is off or Google Location Accuracy is disabled"
+        } else {
+            ""
+        }
+        return "$name ($statusCode)$hint"
+    }
+
+    private fun reason(error: Throwable): String = error.message ?: error::class.java.name
+}