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

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

@@ -0,0 +1,71 @@
+package com.brickssoft.locationtracking.provider.hms
+
+import android.Manifest
+import android.content.Context
+import android.content.pm.PackageManager
+import android.os.Build
+import androidx.core.content.ContextCompat
+import com.brickssoft.locationtracking.core.Logger
+import com.brickssoft.locationtracking.model.ProviderKind
+import com.brickssoft.locationtracking.provider.ActivityBackend
+import com.huawei.hmf.tasks.TaskExecutors
+import com.huawei.hms.location.ActivityIdentification
+import com.huawei.hms.location.ActivityIdentificationService
+
+/**
+ * [ActivityBackend] over HMS activity identification. Results arrive as broadcasts to [HmsActivityReceiver] through
+ * [HmsPendingIntents.activity].
+ *
+ * `start` returns false when `ACTIVITY_RECOGNITION` is missing (API 29+) or the request cannot be submitted; an
+ * asynchronous HMS failure is only logged. The service is created lazily, on first use.
+ */
+internal class HmsActivityBackend(
+    private val context: Context,
+    serviceProvider: () -> ActivityIdentificationService = { ActivityIdentification.getService(context) },
+) : ActivityBackend {
+    override val kind: ProviderKind = ProviderKind.HMS
+    override val isSupported: Boolean = true
+
+    private val service: ActivityIdentificationService by lazy(serviceProvider)
+
+    override fun start(intervalMs: Long): Boolean {
+        if (!hasActivityPermission()) {
+            Logger.w(TAG, "activity identification not started: ACTIVITY_RECOGNITION permission is missing")
+            return false
+        }
+        return try {
+            service.createActivityIdentificationUpdates(intervalMs.coerceAtLeast(0L), HmsPendingIntents.activity(context))
+                .addOnFailureListener(TaskExecutors.immediate()) { e ->
+                    Logger.w(TAG, "createActivityIdentificationUpdates failed: ${describeHmsError(e)}", e)
+                }
+            true
+        } catch (e: Exception) {
+            Logger.e(TAG, "createActivityIdentificationUpdates failed: ${describeHmsError(e)}", e)
+            false
+        }
+    }
+
+    override fun stop() {
+        try {
+            service.deleteActivityIdentificationUpdates(HmsPendingIntents.activity(context))
+                .addOnFailureListener(TaskExecutors.immediate()) { e ->
+                    Logger.d(TAG, "deleteActivityIdentificationUpdates failed: ${describeHmsError(e)}")
+                }
+        } catch (e: Exception) {
+            Logger.w(TAG, "deleteActivityIdentificationUpdates failed: ${describeHmsError(e)}", e)
+        }
+    }
+
+    /**
+     * Below API 29 the permission is `com.huawei.hms.permission.ACTIVITY_RECOGNITION`, which the plugin treats as
+     * granted (architecture §7.6); HMS reports a real denial through the task, which is logged.
+     */
+    private fun hasActivityPermission(): Boolean =
+        Build.VERSION.SDK_INT < Build.VERSION_CODES.Q ||
+            ContextCompat.checkSelfPermission(context, Manifest.permission.ACTIVITY_RECOGNITION) ==
+            PackageManager.PERMISSION_GRANTED
+
+    private companion object {
+        const val TAG = "LT.HmsActivity"
+    }
+}

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

@@ -0,0 +1,57 @@
+package com.brickssoft.locationtracking.provider.hms
+
+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.huawei.hms.location.ActivityIdentificationData
+import com.huawei.hms.location.ActivityIdentificationResponse
+
+/**
+ * Delivers HMS activity-identification results to the engine (`Components.get(ctx).engine`, an `ActivitySink`).
+ * Declared in the manifest; it only fires for the PendingIntent registered by [HmsActivityBackend].
+ */
+class HmsActivityReceiver : BroadcastReceiver() {
+    override fun onReceive(context: Context, intent: Intent) {
+        val samples = parseActivitySamples(intent)
+        if (samples.isEmpty()) return
+        val components = Components.get(context)
+        deliverAsync(goAsync(), components.scope, TAG, "activity samples") {
+            components.engine.onActivitySamples(samples)
+        }
+    }
+
+    internal companion object {
+        private const val TAG = "LT.HmsActivityReceiver"
+
+        /** Samples in [intent], most probable first; empty if it carries no HMS activity result. */
+        fun parseActivitySamples(intent: Intent?): List<ActivitySample> {
+            val response = try {
+                if (intent == null) null else ActivityIdentificationResponse.getDataFromIntent(intent)
+            } catch (e: Exception) {
+                Logger.w(TAG, "unreadable activity identification result", e)
+                null
+            } ?: return emptyList()
+            return response.activityIdentificationDatas.orEmpty()
+                .mapNotNull { data -> data?.let(::toActivitySample) }
+                .sortedByDescending { it.confidence }
+        }
+
+        /** Maps one HMS identification; unknown types become [ActivityType.UNKNOWN]. Confidence is clamped to 0..100. */
+        fun toActivitySample(data: ActivityIdentificationData): ActivitySample =
+            ActivitySample(activityType(data.identificationActivity), data.possibility.coerceIn(0, 100))
+
+        fun activityType(hmsType: Int): ActivityType = when (hmsType) {
+            ActivityIdentificationData.VEHICLE -> ActivityType.IN_VEHICLE
+            ActivityIdentificationData.BIKE -> ActivityType.ON_BICYCLE
+            ActivityIdentificationData.FOOT -> ActivityType.ON_FOOT
+            ActivityIdentificationData.WALKING -> ActivityType.WALKING
+            ActivityIdentificationData.RUNNING -> ActivityType.RUNNING
+            ActivityIdentificationData.STILL -> ActivityType.STILL
+            else -> ActivityType.UNKNOWN // OTHERS and types added by newer HMS versions
+        }
+    }
+}

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

@@ -0,0 +1,76 @@
+package com.brickssoft.locationtracking.provider.hms
+
+import com.brickssoft.locationtracking.core.ErrorCode
+import com.brickssoft.locationtracking.core.TrackingException
+import com.huawei.hms.common.ApiException
+import com.huawei.hms.location.GeofenceErrorCodes
+
+/**
+ * HMS Location Kit status codes used for error mapping. The values mirror
+ * `com.huawei.hms.support.api.location.common.exception.LocationStatusCode` (shipped in a transitive artifact, so
+ * they are copied here) and [GeofenceErrorCodes].
+ */
+internal object HmsStatusCodes {
+    const val ARGUMENTS_EMPTY = 10100
+    const val ARGUMENTS_INVALID = 10101
+    const val NETWORK_LOCATION_SERVICES_DISABLED = 10105
+    const val LOCATION_ENABLE_OFF = 10106
+    const val PARAM_ERROR_EMPTY = 10801
+    const val PARAM_ERROR_INVALID = 10802
+    const val PERMISSION_DENIED = 10803
+    const val NO_PRECISE_LOCATION_PERMISSION = 10809
+
+    /** Like GMS `GEOFENCE_NOT_AVAILABLE`: typically location was switched off. */
+    const val GEOFENCE_UNAVAILABLE = GeofenceErrorCodes.GEOFENCE_UNAVAILABLE
+    const val GEOFENCE_NUMBER_OVER_LIMIT = GeofenceErrorCodes.GEOFENCE_NUMBER_OVER_LIMIT
+    const val GEOFENCE_PENDINGINTENT_OVER_LIMIT = GeofenceErrorCodes.GEOFENCE_PENDINGINTENT_OVER_LIMIT
+    const val GEOFENCE_INSUFFICIENT_PERMISSION = GeofenceErrorCodes.GEOFENCE_INSUFFICIENT_PERMISSION
+}
+
+/**
+ * Maps an HMS status code to the plugin's [ErrorCode]:
+ * permission errors → [ErrorCode.PERMISSION_DENIED], geofence limits → [ErrorCode.TOO_MANY_GEOFENCES],
+ * location (or network location, which geofencing needs) switched off → [ErrorCode.LOCATION_DISABLED],
+ * argument errors → [ErrorCode.INVALID_ARGUMENT],
+ * everything else (HMS Core missing or outdated, AppGallery Connect errors, …) → [ErrorCode.UNAVAILABLE].
+ */
+internal fun errorCodeForStatus(statusCode: Int): ErrorCode = when (statusCode) {
+    HmsStatusCodes.PERMISSION_DENIED,
+    HmsStatusCodes.NO_PRECISE_LOCATION_PERMISSION,
+    HmsStatusCodes.GEOFENCE_INSUFFICIENT_PERMISSION,
+    -> ErrorCode.PERMISSION_DENIED
+
+    HmsStatusCodes.GEOFENCE_NUMBER_OVER_LIMIT,
+    HmsStatusCodes.GEOFENCE_PENDINGINTENT_OVER_LIMIT,
+    -> ErrorCode.TOO_MANY_GEOFENCES
+
+    HmsStatusCodes.LOCATION_ENABLE_OFF,
+    HmsStatusCodes.NETWORK_LOCATION_SERVICES_DISABLED,
+    HmsStatusCodes.GEOFENCE_UNAVAILABLE,
+    -> ErrorCode.LOCATION_DISABLED
+
+    HmsStatusCodes.ARGUMENTS_EMPTY,
+    HmsStatusCodes.ARGUMENTS_INVALID,
+    HmsStatusCodes.PARAM_ERROR_EMPTY,
+    HmsStatusCodes.PARAM_ERROR_INVALID,
+    -> ErrorCode.INVALID_ARGUMENT
+
+    else -> ErrorCode.UNAVAILABLE
+}
+
+/** Converts a failure of an HMS call into the only exception type that crosses component boundaries. */
+internal fun Throwable.toTrackingException(operation: String): TrackingException = when (this) {
+    is TrackingException -> this
+    is SecurityException -> TrackingException(ErrorCode.PERMISSION_DENIED, "$operation: location permission denied", this)
+    is ApiException -> TrackingException(errorCodeForStatus(statusCode), "$operation failed: ${describeHmsError(this)}", this)
+    is IllegalArgumentException -> TrackingException(ErrorCode.INVALID_ARGUMENT, "$operation: ${message ?: "invalid argument"}", this)
+    else -> TrackingException(ErrorCode.UNAVAILABLE, "$operation failed: ${describeHmsError(this)}", this)
+}
+
+/** Short description for logs and messages, including the HMS status code when there is one. */
+internal fun describeHmsError(t: Throwable): String =
+    if (t is ApiException) {
+        "HMS status ${t.message ?: t.statusCode}" // ApiException's message is "<code>:<status message>"
+    } else {
+        "${t.javaClass.simpleName}: ${t.message}"
+    }

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

@@ -0,0 +1,116 @@
+package com.brickssoft.locationtracking.provider.hms
+
+import android.content.Context
+import com.brickssoft.locationtracking.core.Logger
+import com.brickssoft.locationtracking.model.ProviderKind
+import com.brickssoft.locationtracking.provider.GeofenceBackend
+import com.brickssoft.locationtracking.provider.OsGeofence
+import com.huawei.hmf.tasks.TaskExecutors
+import com.huawei.hms.location.Geofence
+import com.huawei.hms.location.GeofenceRequest
+import com.huawei.hms.location.GeofenceService
+import com.huawei.hms.location.LocationServices
+
+/**
+ * [GeofenceBackend] over the HMS geofence service. Transitions arrive as broadcasts to [HmsGeofenceReceiver]
+ * through [HmsPendingIntents.geofence].
+ *
+ * - Regions are circles that never expire; ENTER/EXIT/DWELL map to HMS conversions, and DWELL uses the region's
+ *   loitering delay.
+ * - `initialTriggerEntry` maps to the request's init conversions (ENTER and DWELL), so regions are sent in one
+ *   request per distinct value; if a later request fails, the earlier ones of the same call are deleted again.
+ *   Duplicate ids within one call keep the last region.
+ * - A region with no transition to report is skipped: HMS rejects geofences without conversions.
+ * - Every failure is thrown as a `TrackingException` (see [toTrackingException]).
+ *
+ * The service is created lazily, on first use.
+ */
+internal class HmsGeofenceBackend(
+    private val context: Context,
+    serviceProvider: () -> GeofenceService = { LocationServices.getGeofenceService(context) },
+) : GeofenceBackend {
+    override val kind: ProviderKind = ProviderKind.HMS
+    override val supportsDwell: Boolean = true
+
+    private val service: GeofenceService by lazy(serviceProvider)
+
+    override suspend fun add(regions: List<OsGeofence>) {
+        val (unique, silent) = regions.associateBy { it.id }.values.partition { hmsConversions(it) != 0 }
+        for (region in silent) Logger.w(TAG, "geofence '${region.id}' has no transition to report; not registered")
+        if (unique.isEmpty()) return
+        val registered = ArrayList<String>(unique.size)
+        for ((initConversions, group) in unique.groupBy(::hmsInitConversions)) {
+            try {
+                hmsCall("createGeofenceList") {
+                    val request = GeofenceRequest.Builder()
+                        .createGeofenceList(group.map(::buildHmsGeofence))
+                        .setInitConversions(initConversions)
+                        .setCoordinateType(GeofenceRequest.COORDINATE_TYPE_WGS_84)
+                        .build()
+                    service.createGeofenceList(request, HmsPendingIntents.geofence(context)).await()
+                }
+            } catch (e: Exception) {
+                rollBack(registered)
+                throw e
+            }
+            group.mapTo(registered) { it.id }
+        }
+        Logger.d(TAG, "registered ${registered.size} geofence(s)")
+    }
+
+    /** Best effort: a failed `add` must not leave the earlier requests of the same call registered. */
+    private fun rollBack(ids: List<String>) {
+        if (ids.isEmpty()) return
+        try {
+            service.deleteGeofenceList(ids).addOnFailureListener(TaskExecutors.immediate()) { e ->
+                Logger.w(TAG, "rolling back ${ids.size} geofence(s) failed: ${describeHmsError(e)}", e)
+            }
+        } catch (e: Exception) {
+            Logger.w(TAG, "rolling back ${ids.size} geofence(s) failed: ${describeHmsError(e)}", e)
+        }
+    }
+
+    override suspend fun remove(ids: List<String>) {
+        val unique = ids.distinct()
+        if (unique.isEmpty()) return
+        hmsCall("deleteGeofenceList") { service.deleteGeofenceList(unique).await() }
+    }
+
+    override suspend fun removeAll() {
+        hmsCall("deleteGeofenceList") { service.deleteGeofenceList(HmsPendingIntents.geofence(context)).await() }
+    }
+
+    private companion object {
+        const val TAG = "LT.HmsGeofence"
+    }
+}
+
+/** HMS conversion flags of a region (0 if it reports nothing). */
+internal fun hmsConversions(region: OsGeofence): Int {
+    var flags = 0
+    if (region.onEntry) flags = flags or Geofence.ENTER_GEOFENCE_CONVERSION
+    if (region.onExit) flags = flags or Geofence.EXIT_GEOFENCE_CONVERSION
+    if (region.onDwell) flags = flags or Geofence.DWELL_GEOFENCE_CONVERSION
+    return flags
+}
+
+/**
+ * Init conversions of the request that carries [region]: fire ENTER (and DWELL after the loitering delay) if the
+ * device is already inside when the region is registered, or nothing when `initialTriggerEntry` is off.
+ */
+internal fun hmsInitConversions(region: OsGeofence): Int =
+    if (region.initialTriggerEntry) {
+        GeofenceRequest.ENTER_INIT_CONVERSION or GeofenceRequest.DWELL_INIT_CONVERSION
+    } else {
+        0
+    }
+
+/** Builds the HMS geofence for [region]. */
+internal fun buildHmsGeofence(region: OsGeofence): Geofence =
+    Geofence.Builder()
+        .setUniqueId(region.id)
+        .setRoundArea(region.latitude, region.longitude, region.radius)
+        .setConversions(hmsConversions(region))
+        .setDwellDelayTime(region.loiteringDelayMs.coerceAtLeast(0))
+        .setValidContinueTime(Geofence.GEOFENCE_NEVER_EXPIRE)
+        .build()

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

@@ -0,0 +1,67 @@
+package com.brickssoft.locationtracking.provider.hms
+
+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.GeofenceAction
+import com.brickssoft.locationtracking.provider.OsGeofenceTransition
+import com.huawei.hms.location.Geofence
+import com.huawei.hms.location.GeofenceData
+
+/**
+ * Delivers HMS geofence transitions to the GeofenceManager (`Components.get(ctx).geofences`, a
+ * `GeofenceTransitionSink`). Declared in the manifest; it only fires for the PendingIntent registered by
+ * [HmsGeofenceBackend].
+ */
+class HmsGeofenceReceiver : BroadcastReceiver() {
+    override fun onReceive(context: Context, intent: Intent) {
+        val transitions = parseGeofenceTransitions(intent)
+        if (transitions.isEmpty()) return
+        val components = Components.get(context)
+        deliverAsync(goAsync(), components.scope, TAG, "geofence transitions") {
+            components.geofences.onGeofenceTransitions(transitions)
+        }
+    }
+
+    internal companion object {
+        private const val TAG = "LT.HmsGeofenceReceiver"
+
+        /** Transitions in [intent]; empty if it carries no HMS geofence event or reports an error. */
+        fun parseGeofenceTransitions(intent: Intent?): List<OsGeofenceTransition> {
+            val data = try {
+                GeofenceData.getDataFromIntent(intent)
+            } catch (e: Exception) {
+                Logger.w(TAG, "unreadable geofence event", e)
+                null
+            } ?: return emptyList()
+            return toTransitions(data)
+        }
+
+        /** One transition per distinct geofence id, all with the event's action and triggering fix. */
+        fun toTransitions(data: GeofenceData): List<OsGeofenceTransition> {
+            if (data.isFailure) {
+                Logger.w(TAG, "HMS geofence error ${data.errorCode}")
+                return emptyList()
+            }
+            val action = geofenceAction(data.conversion)
+            if (action == null) {
+                Logger.w(TAG, "ignoring geofence event with conversion ${data.conversion}")
+                return emptyList()
+            }
+            val location = data.convertingLocation?.let(::toTrackedLocation)
+            return data.convertingGeofenceList.orEmpty()
+                .mapNotNull { it?.uniqueId }
+                .distinct()
+                .map { id -> OsGeofenceTransition(id, action, location) }
+        }
+
+        fun geofenceAction(conversion: Int): GeofenceAction? = when (conversion) {
+            Geofence.ENTER_GEOFENCE_CONVERSION -> GeofenceAction.ENTER
+            Geofence.EXIT_GEOFENCE_CONVERSION -> GeofenceAction.EXIT
+            Geofence.DWELL_GEOFENCE_CONVERSION -> GeofenceAction.DWELL
+            else -> null
+        }
+    }
+}

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

@@ -0,0 +1,83 @@
+package com.brickssoft.locationtracking.provider.hms
+
+import android.app.PendingIntent
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import com.brickssoft.locationtracking.core.Constants
+import com.brickssoft.locationtracking.core.Logger
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.launch
+import java.util.concurrent.atomic.AtomicBoolean
+import kotlin.coroutines.cancellation.CancellationException
+
+/**
+ * PendingIntents handed to HMS. They are explicit broadcasts to our receivers and mutable (API 31+), because HMS
+ * fills in the result extras. Creating one again returns the same PendingIntent, which is what the delete calls need.
+ */
+internal object HmsPendingIntents {
+    fun activity(context: Context): PendingIntent = PendingIntent.getBroadcast(
+        context,
+        Constants.RC_HMS_ACTIVITY,
+        Intent(context, HmsActivityReceiver::class.java).setAction(Constants.ACTION_ACTIVITY),
+        Constants.piMutable(),
+    )
+
+    fun geofence(context: Context): PendingIntent = PendingIntent.getBroadcast(
+        context,
+        Constants.RC_HMS_GEOFENCE,
+        Intent(context, HmsGeofenceReceiver::class.java).setAction(Constants.ACTION_GEOFENCE),
+        Constants.piMutable(),
+    )
+}
+
+/** Receivers must finish within about 10 s (architecture §7.12); the broadcast is released before that. */
+internal const val BROADCAST_FINISH_DEADLINE_MS = 9_000L
+
+/**
+ * Runs [block] on [scope] for a broadcast kept alive with `goAsync()`. Failures are logged, never rethrown.
+ *
+ * [pending] is finished exactly once: when the job completes (including when it fails or is cancelled before it
+ * starts), or after [finishAfterMs] if it is still running. In that case the work goes on without holding the
+ * broadcast, so a slow sink cannot trigger a broadcast timeout.
+ */
+internal fun deliverAsync(
+    pending: BroadcastReceiver.PendingResult?,
+    scope: CoroutineScope,
+    tag: String,
+    what: String,
+    finishAfterMs: Long = BROADCAST_FINISH_DEADLINE_MS,
+    block: suspend () -> Unit,
+): Job {
+    val finished = AtomicBoolean(false)
+    fun finishOnce() {
+        if (!finished.compareAndSet(false, true)) return
+        try {
+            pending?.finish()
+        } catch (e: Exception) {
+            Logger.w(tag, "finishing the broadcast failed", e)
+        }
+    }
+
+    val job = scope.launch {
+        try {
+            block()
+        } catch (e: CancellationException) {
+            throw e
+        } catch (e: Exception) {
+            Logger.e(tag, "failed to deliver $what", e)
+        }
+    }
+    val deadline = scope.launch {
+        delay(finishAfterMs)
+        Logger.w(tag, "delivering $what takes longer than $finishAfterMs ms; releasing the broadcast")
+        finishOnce()
+    }
+    job.invokeOnCompletion {
+        deadline.cancel()
+        finishOnce()
+    }
+    return job
+}

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

@@ -0,0 +1,197 @@
+package com.brickssoft.locationtracking.provider.hms
+
+import android.content.Context
+import android.location.Location
+import android.os.Looper
+import com.brickssoft.locationtracking.core.Logger
+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 com.huawei.hmf.tasks.TaskExecutors
+import com.huawei.hms.location.FusedLocationProviderClient
+import com.huawei.hms.location.LocationCallback
+import com.huawei.hms.location.LocationRequest
+import com.huawei.hms.location.LocationResult
+import com.huawei.hms.location.LocationServices
+import kotlinx.coroutines.CompletableDeferred
+import kotlinx.coroutines.withTimeoutOrNull
+
+/**
+ * [LocationBackend] over the HMS fused location client.
+ *
+ * - Each listener gets its own [LocationCallback] on the main looper; requesting again with the same listener
+ *   replaces its request, and late fixes from a replaced callback are dropped.
+ * - `getCurrentLocation` is a one-shot request (`numUpdates = 1`) whose callback is always removed.
+ * - Permission failures surface as `TrackingException(PERMISSION_DENIED)`; other HMS failures are mapped by
+ *   [toTrackingException].
+ *
+ * The client is created lazily, on first use.
+ */
+internal class HmsLocationBackend(
+    clientProvider: () -> FusedLocationProviderClient,
+    private val looperProvider: () -> Looper = { Looper.getMainLooper() },
+) : LocationBackend {
+    constructor(context: Context) : this({ LocationServices.getFusedLocationProviderClient(context) })
+
+    override val kind: ProviderKind = ProviderKind.HMS
+
+    private val client: FusedLocationProviderClient by lazy(clientProvider)
+
+    /**
+     * Active callback per listener. Guarded by [lock], which is also held across the HMS request/remove calls so a
+     * concurrent request/remove for the same listener cannot leave an orphaned HMS registration. Those calls only
+     * submit work and return a task; callbacks never take the lock (they check [ListenerCallback.active]).
+     */
+    private val callbacks = HashMap<LocationListener, ListenerCallback>()
+    private val lock = Any()
+
+    override fun requestUpdates(spec: LocationRequestSpec, listener: LocationListener) {
+        val request = buildLocationRequest(spec)
+        synchronized(lock) {
+            callbacks.remove(listener)?.let(::deactivateAndRemove)
+            val callback = ListenerCallback(listener)
+            callbacks[listener] = callback
+            try {
+                client.requestLocationUpdates(request, callback, looperProvider())
+                    .addOnFailureListener(TaskExecutors.immediate()) { e ->
+                        Logger.e(TAG, "requestLocationUpdates failed: ${describeHmsError(e)}", e)
+                        forget(callback)
+                    }
+            } catch (e: Exception) {
+                Logger.e(TAG, "requestLocationUpdates failed: ${describeHmsError(e)}", e)
+                forget(callback)
+            }
+        }
+    }
+
+    override fun removeUpdates(listener: LocationListener) {
+        synchronized(lock) { callbacks.remove(listener)?.let(::deactivateAndRemove) }
+    }
+
+    override suspend fun getLastLocation(): TrackedLocation? = hmsCall("getLastLocation") {
+        val location: Location? = client.lastLocation.await()
+        location?.let(::toTrackedLocation)
+    }
+
+    override suspend fun getCurrentLocation(accuracy: DesiredAccuracy, timeoutMs: Long): TrackedLocation? {
+        val fix = CompletableDeferred<TrackedLocation>()
+        val callback = object : LocationCallback() {
+            override fun onLocationResult(result: LocationResult?) {
+                val location = result?.locations.orEmpty().lastOrNull { it != null } ?: return
+                fix.complete(toTrackedLocation(location))
+            }
+        }
+        var requested = false
+        try {
+            return withTimeoutOrNull(timeoutMs.coerceAtLeast(0)) {
+                hmsCall("getCurrentLocation") {
+                    requested = true
+                    client.requestLocationUpdates(buildOneShotRequest(accuracy), callback, looperProvider()).await()
+                }
+                fix.await()
+            }
+        } finally {
+            if (requested) removeQuietly(callback)
+        }
+    }
+
+    /** Number of listeners with an active request (for tests and diagnostics). */
+    internal val activeListenerCount: Int get() = synchronized(lock) { callbacks.size }
+
+    /** Drops [callback] after its request failed, unless it was already replaced or removed. */
+    private fun forget(callback: ListenerCallback) {
+        callback.active = false
+        synchronized(lock) { if (callbacks[callback.listener] === callback) callbacks.remove(callback.listener) }
+    }
+
+    private fun deactivateAndRemove(callback: ListenerCallback) {
+        callback.active = false
+        removeQuietly(callback)
+    }
+
+    private fun removeQuietly(callback: LocationCallback) {
+        try {
+            client.removeLocationUpdates(callback)
+                .addOnFailureListener(TaskExecutors.immediate()) { e ->
+                    Logger.d(TAG, "removeLocationUpdates failed: ${describeHmsError(e)}")
+                }
+        } catch (e: Exception) {
+            Logger.w(TAG, "removeLocationUpdates failed: ${describeHmsError(e)}", e)
+        }
+    }
+
+    /** Delivers to [listener] until replaced or removed; late fixes after that are dropped. */
+    private class ListenerCallback(val listener: LocationListener) : LocationCallback() {
+        @Volatile
+        var active = true
+
+        override fun onLocationResult(result: LocationResult?) {
+            if (!active) return
+            val fixes = result?.locations.orEmpty().mapNotNull { location -> location?.let(::toTrackedLocation) }
+            if (fixes.isEmpty()) return
+            try {
+                listener.onLocations(fixes)
+            } catch (e: Exception) {
+                Logger.e(TAG, "location listener failed", e)
+            }
+        }
+    }
+
+    companion object {
+        private const val TAG = "LT.HmsLocation"
+
+        /** Interval of the one-shot request behind `getCurrentLocation`. */
+        internal const val ONE_SHOT_INTERVAL_MS = 1_000L
+    }
+}
+
+/** HMS priority for a desired accuracy. */
+internal fun hmsPriority(accuracy: DesiredAccuracy): Int = when (accuracy) {
+    DesiredAccuracy.HIGH -> LocationRequest.PRIORITY_HIGH_ACCURACY
+    DesiredAccuracy.BALANCED -> LocationRequest.PRIORITY_BALANCED_POWER_ACCURACY
+    DesiredAccuracy.LOW -> LocationRequest.PRIORITY_LOW_POWER
+    DesiredAccuracy.PASSIVE -> LocationRequest.PRIORITY_NO_POWER
+}
+
+/** Continuous request: negative values are clamped to 0 and the fastest interval never exceeds the interval. */
+internal fun buildLocationRequest(spec: LocationRequestSpec): LocationRequest {
+    val interval = spec.intervalMs.coerceAtLeast(0L)
+    return LocationRequest.create()
+        .setPriority(hmsPriority(spec.accuracy))
+        .setInterval(interval)
+        .setFastestInterval(spec.fastestIntervalMs.coerceIn(0L, interval))
+        .setSmallestDisplacement(spec.distanceFilterM.coerceAtLeast(0f))
+}
+
+/** One-shot request for `getCurrentLocation`. */
+internal fun buildOneShotRequest(accuracy: DesiredAccuracy): LocationRequest =
+    LocationRequest.create()
+        .setPriority(hmsPriority(accuracy))
+        .setInterval(HmsLocationBackend.ONE_SHOT_INTERVAL_MS)
+        .setFastestInterval(HmsLocationBackend.ONE_SHOT_INTERVAL_MS / 2)
+        .setNumUpdates(1)
+
+/**
+ * [TrackedLocation.from] plus the extras HMS uses on some devices and API levels: `mockLocation` marks a mock fix
+ * and `verticalAccuracy` fills a missing altitude accuracy.
+ */
+@Suppress("DEPRECATION") // Bundle.get: the value types of these extras vary between HMS versions
+internal fun toTrackedLocation(location: Location): TrackedLocation {
+    val base = TrackedLocation.from(location)
+    val extras = try {
+        location.extras?.takeUnless { it.isEmpty }
+    } catch (_: RuntimeException) {
+        null // a bundle that cannot be unparcelled carries nothing we need
+    } ?: return base
+    val mock = extras.get(FusedLocationProviderClient.KEY_MOCK_LOCATION) as? Boolean ?: false
+    val verticalAccuracy = (extras.get(FusedLocationProviderClient.KEY_VERTICAL_ACCURACY) as? Number)
+        ?.toFloat()
+        ?.takeIf { it > 0f && it.isFinite() }
+    return base.copy(
+        isMock = base.isMock || mock,
+        altitudeAccuracy = base.altitudeAccuracy ?: verticalAccuracy,
+    )
+}