@bricks-soft/capacitor-location-tracking 8.0.1 → 8.1.0

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

@@ -9,6 +9,9 @@ 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.brickssoft.locationtracking.provider.LocationSubscriptions
+import com.brickssoft.locationtracking.provider.OsRegistration
+import com.brickssoft.locationtracking.provider.RegistrationEvents
 import com.google.android.gms.location.CurrentLocationRequest
 import com.google.android.gms.location.FusedLocationProviderClient
 import com.google.android.gms.location.LocationAvailability
@@ -25,11 +28,12 @@ import kotlin.coroutines.cancellation.CancellationException
 /**
  * Fused location provider backend.
  *
- * Every [LocationListener] gets its own [LocationCallback] on the main looper. Requesting again with the same
- * listener reuses its callback, which GMS treats as a replacement of the previous request.
+ * Listener bookkeeping is [LocationSubscriptions]: every request gets its own [LocationCallback] on the main looper,
+ * a request for the same listener removes the previous callback first, and a failure of `requestLocationUpdates`
+ * (thrown, or reported later by its Task) reaches the listener's `onError` (recommendation 3).
+ * `onLocationAvailability` is kept as [availabilityHint].
  *
- * Only [getCurrentLocation] throws: the [LocationBackend] contract declares no exception for the other methods, so
- * their failures are logged (a missing permission also shows in the provider state).
+ * Only [getCurrentLocation] throws: the [LocationBackend] contract declares no exception for the other methods.
  */
 internal class GmsLocationBackend(
     private val client: FusedLocationProviderClient,
@@ -37,40 +41,48 @@ internal class GmsLocationBackend(
 ) : LocationBackend {
     override val kind: ProviderKind = ProviderKind.GMS
 
-    /** Guarded by itself; GMS registration calls are made under the same lock so add/remove cannot interleave. */
-    private val callbacks = HashMap<LocationListener, ListenerCallback>()
+    private val subscriptions = LocationSubscriptions(TAG) { GmsErrors.map(it, "requestLocationUpdates") }
+
+    override val availabilityHint: Boolean? get() = subscriptions.availabilityHint
 
-    /**
-     * Never throws. A synchronous rejection (e.g. `SecurityException` without location permission) is logged and
-     * leaves a new listener unregistered, or a replaced listener on its previous request. Asynchronous failures of
-     * the GMS Task are logged too.
-     */
     override fun requestUpdates(spec: LocationRequestSpec, listener: LocationListener) {
         val request = try {
             buildLocationRequest(spec)
         } catch (e: Exception) {
             Logger.e(TAG, "invalid location request $spec", e)
+            listener.onError(GmsErrors.map(e, "requestLocationUpdates"))
             return
         }
-        synchronized(callbacks) {
-            val existing = callbacks[listener]
-            val callback = existing ?: ListenerCallback(listener)
-            try {
-                client.requestLocationUpdates(request, callback, looper()).logFailure(TAG, "requestLocationUpdates")
-            } catch (e: Exception) {
-                val mapped = GmsErrors.map(e, "requestLocationUpdates")
-                Logger.e(TAG, "${mapped.code}: ${mapped.message}", e)
-                return
-            }
-            if (existing == null) callbacks[listener] = callback
-            Logger.d(TAG, "location updates ${if (existing == null) "requested" else "replaced"}: $spec")
-        }
+        subscriptions.request(listener, spec) { events -> Registration(request, events) }
+        Logger.d(TAG, "location updates requested: $spec")
     }
 
     override fun removeUpdates(listener: LocationListener) {
-        synchronized(callbacks) {
-            val callback = callbacks.remove(listener) ?: return
-            callback.active = false
+        subscriptions.remove(listener)
+    }
+
+    /** One `requestLocationUpdates` with its own callback. */
+    private inner class Registration(
+        private val request: LocationRequest,
+        private val events: RegistrationEvents,
+    ) : OsRegistration {
+        private val callback = object : LocationCallback() {
+            override fun onLocationResult(result: LocationResult) {
+                events.locations(result.locations.map(TrackedLocation::from))
+            }
+
+            override fun onLocationAvailability(availability: LocationAvailability) {
+                events.availability(availability.isLocationAvailable)
+            }
+        }
+
+        override fun start(done: (Exception?) -> Unit) {
+            client.requestLocationUpdates(request, callback, looper()).addOnCompleteListener(DirectExecutor) { task ->
+                done(task.exception ?: if (task.isCanceled) IllegalStateException("request cancelled by GMS") else null)
+            }
+        }
+
+        override fun remove() {
             try {
                 client.removeLocationUpdates(callback).logFailure(TAG, "removeLocationUpdates")
             } catch (e: Exception) {
@@ -126,30 +138,6 @@ internal class GmsLocationBackend(
         }
     }
 
-    /**
-     * Forwards fixes to one listener until [removeUpdates] deactivates it. Best effort: a batch whose delivery already
-     * started on the looper thread may still reach the listener while [removeUpdates] runs on another thread.
-     */
-    private class ListenerCallback(private val listener: LocationListener) : LocationCallback() {
-        @Volatile
-        var active = true
-
-        override fun onLocationResult(result: LocationResult) {
-            if (!active) return
-            val locations = result.locations.map(TrackedLocation::from)
-            if (locations.isEmpty()) return
-            try {
-                listener.onLocations(locations)
-            } catch (e: Exception) {
-                Logger.e(TAG, "location listener failed", e)
-            }
-        }
-
-        override fun onLocationAvailability(availability: LocationAvailability) {
-            Logger.v(TAG, "location available: ${availability.isLocationAvailable}")
-        }
-    }
-
     companion object {
         private const val TAG = "LT.GmsLocation"
 

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

@@ -40,16 +40,24 @@ class GmsProviderBundle @JvmOverloads constructor(
     private val activityBackend by lazy { GmsActivityBackend(appContext, activityClient(appContext)) }
     private val geofenceBackend by lazy { GmsGeofenceBackend(appContext, geofencingClient(appContext)) }
 
+    @Volatile
+    private var lastStatus: Int? = null
+
     /** True if `GoogleApiAvailability` reports SUCCESS; false on any other result or failure. */
     override fun isAvailable(): Boolean = try {
         val status = availabilityCheck(appContext)
+        lastStatus = status
         if (status != ConnectionResult.SUCCESS) Logger.d(TAG, "Google Play services unavailable: status $status")
         status == ConnectionResult.SUCCESS
     } catch (t: Throwable) {
+        lastStatus = null
         Logger.w(TAG, "Google Play services availability check failed", t)
         false
     }
 
+    /** The `GoogleApiAvailability` result of the last [isAvailable] (`ConnectionResult` code), or null. */
+    override fun availabilityStatus(): Int? = lastStatus
+
     override fun location(): LocationBackend = locationBackend
 
     override fun activity(): ActivityBackend = activityBackend

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

@@ -10,8 +10,12 @@ 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.brickssoft.locationtracking.provider.LocationSubscriptions
+import com.brickssoft.locationtracking.provider.OsRegistration
+import com.brickssoft.locationtracking.provider.RegistrationEvents
 import com.huawei.hmf.tasks.TaskExecutors
 import com.huawei.hms.location.FusedLocationProviderClient
+import com.huawei.hms.location.LocationAvailability
 import com.huawei.hms.location.LocationCallback
 import com.huawei.hms.location.LocationRequest
 import com.huawei.hms.location.LocationResult
@@ -22,9 +26,14 @@ 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.
+ * - Listener bookkeeping is [LocationSubscriptions]: each request gets its own [LocationCallback] on the main looper; a
+ *   request for the same listener removes the previous callback first, and late fixes of a replaced callback are
+ *   dropped. A failure of `requestLocationUpdates` (thrown, or reported later by its task) reaches the listener's
+ *   `onError` (recommendation 3). The first delivered fix counts as a successful registration: Huawei does not
+ *   guarantee that the task succeeds before the first result.
+ * - `getCurrentLocation` is a one-shot request (`numUpdates = 1`) whose callback is always removed. It returns the
+ *   first fix even while the request task has not completed, and a failed request ends it at once with the error
+ *   instead of waiting for the timeout.
  * - Permission failures surface as `TrackingException(PERMISSION_DENIED)`; other HMS failures are mapped by
  *   [toTrackingException].
  *
@@ -40,35 +49,17 @@ internal class HmsLocationBackend(
 
     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()
+    private val subscriptions = LocationSubscriptions(TAG) { it.toTrackingException("requestLocationUpdates") }
+
+    override val availabilityHint: Boolean? get() = subscriptions.availabilityHint
 
     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)
-            }
-        }
+        subscriptions.request(listener, spec) { events -> Registration(request, events) }
     }
 
     override fun removeUpdates(listener: LocationListener) {
-        synchronized(lock) { callbacks.remove(listener)?.let(::deactivateAndRemove) }
+        subscriptions.remove(listener)
     }
 
     override suspend fun getLastLocation(): TrackedLocation? = hmsCall("getLastLocation") {
@@ -87,9 +78,15 @@ internal class HmsLocationBackend(
         var requested = false
         try {
             return withTimeoutOrNull(timeoutMs.coerceAtLeast(0)) {
-                hmsCall("getCurrentLocation") {
+                val task = hmsCall("getCurrentLocation") {
                     requested = true
-                    client.requestLocationUpdates(buildOneShotRequest(accuracy), callback, looperProvider()).await()
+                    client.requestLocationUpdates(buildOneShotRequest(accuracy), callback, looperProvider())
+                }
+                task.addOnFailureListener(TaskExecutors.immediate()) { e ->
+                    fix.completeExceptionally(e.toTrackingException("getCurrentLocation"))
+                }
+                task.addOnCanceledListener(TaskExecutors.immediate()) {
+                    fix.completeExceptionally(HmsTaskCanceledException().toTrackingException("getCurrentLocation"))
                 }
                 fix.await()
             }
@@ -99,18 +96,7 @@ internal class HmsLocationBackend(
     }
 
     /** 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)
-    }
+    internal val activeListenerCount: Int get() = subscriptions.count
 
     private fun removeQuietly(callback: LocationCallback) {
         try {
@@ -123,21 +109,29 @@ internal class HmsLocationBackend(
         }
     }
 
-    /** 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)
+    /** One `requestLocationUpdates` with its own callback. */
+    private inner class Registration(
+        private val request: LocationRequest,
+        private val events: RegistrationEvents,
+    ) : OsRegistration {
+        private val callback = object : LocationCallback() {
+            override fun onLocationResult(result: LocationResult?) {
+                events.locations(result?.locations.orEmpty().mapNotNull { location -> location?.let(::toTrackedLocation) })
+            }
+
+            override fun onLocationAvailability(availability: LocationAvailability?) {
+                availability?.let { events.availability(it.isLocationAvailable) }
             }
         }
+
+        override fun start(done: (Exception?) -> Unit) {
+            client.requestLocationUpdates(request, callback, looperProvider())
+                .addOnSuccessListener(TaskExecutors.immediate()) { done(null) }
+                .addOnFailureListener(TaskExecutors.immediate()) { e -> done(e) }
+                .addOnCanceledListener(TaskExecutors.immediate()) { done(HmsTaskCanceledException()) }
+        }
+
+        override fun remove() = removeQuietly(callback)
     }
 
     companion object {

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

@@ -23,6 +23,10 @@ class HmsProviderBundle @JvmOverloads constructor(
     private val availabilityCheck: (Context) -> Int = { ctx ->
         HuaweiApiAvailability.getInstance().isHuaweiMobileServicesAvailable(ctx)
     },
+    /** `isHuaweiMobileServicesAvailable(context, minimumVersion)`; injectable for tests. */
+    private val versionCheck: (Context, Int) -> Int = { ctx, minimum ->
+        HuaweiApiAvailability.getInstance().isHuaweiMobileServicesAvailable(ctx, minimum)
+    },
 ) : ProviderBundle {
     private val appContext: Context = context.applicationContext ?: context
 
@@ -32,24 +36,52 @@ class HmsProviderBundle @JvmOverloads constructor(
     private val activityBackend by lazy { HmsActivityBackend(appContext) }
     private val geofenceBackend by lazy { HmsGeofenceBackend(appContext) }
 
+    @Volatile
+    private var lastStatus: Int? = null
+
     /** True if HMS Core reports SUCCESS; any failure (including a missing SDK class) counts as unavailable. */
     override fun isAvailable(): Boolean =
         try {
             val result = availabilityCheck(appContext)
+            lastStatus = result
             if (result != ConnectionResult.SUCCESS) Logger.d(TAG, "HMS Core unavailable: result $result")
             result == ConnectionResult.SUCCESS
         } catch (t: Throwable) {
+            lastStatus = null
             Logger.w(TAG, "HMS availability check failed", t)
             false
         }
 
+    /** The `HuaweiApiAvailability` result of the last [isAvailable], or null. */
+    override fun availabilityStatus(): Int? = lastStatus
+
+    /**
+     * A diagnostic when HMS Core is older than 6.3.0.301 ([MIN_RECOMMENDED_HMS_CORE]), the version Huawei's Location
+     * Kit documentation asks for (recommendation 15). It does not change the provider choice. Null when HMS Core is
+     * that version or newer, or the check fails.
+     */
+    override fun versionDiagnostic(): String? = try {
+        val result = versionCheck(appContext, MIN_RECOMMENDED_HMS_CORE)
+        if (result == ConnectionResult.SUCCESS) {
+            null
+        } else {
+            "HMS Core is older than 6.3.0.301 or needs an update (isHuaweiMobileServicesAvailable result $result)"
+        }
+    } catch (t: Throwable) {
+        Logger.w(TAG, "HMS Core version check failed", t)
+        null
+    }
+
     override fun location(): LocationBackend = locationBackend
 
     override fun activity(): ActivityBackend = activityBackend
 
     override fun geofence(): GeofenceBackend = geofenceBackend
 
-    private companion object {
-        const val TAG = "LT.HmsBundle"
+    internal companion object {
+        private const val TAG = "LT.HmsBundle"
+
+        /** HMS Core 6.3.0.301, as `isHuaweiMobileServicesAvailable` expects a version (60300301). */
+        const val MIN_RECOMMENDED_HMS_CORE = 60300301
     }
 }

package/android/src/main/java/com/brickssoft/locationtracking/record/RecordSink.kt

@@ -1,5 +1,6 @@
 package com.brickssoft.locationtracking.record
 
+import android.database.sqlite.SQLiteFullException
 import com.brickssoft.locationtracking.config.ConfigStore
 import com.brickssoft.locationtracking.core.EventBus
 import com.brickssoft.locationtracking.core.Logger
@@ -29,7 +30,8 @@ interface RecordSink {
  * 5. `syncer.onRecordInserted(record)`.
  *
  * If the insert fails, the failure is logged, steps 2-4 still run (live listeners still get the record) and
- * step 5 is skipped because the record is not queued.
+ * step 5 is skipped because the record is not queued. A failure because the storage is full (`SQLiteFullException`)
+ * also emits a `StorageFull` event (recommendation 16), so the app can tell the user.
  *
  * Round 2: [hooks] receives every record right after step 1, also when the insert failed or the caller was cancelled
  * during the insert (a companion listener keeps its own audit trail, so a local database failure must not hide the
@@ -43,6 +45,8 @@ class DefaultRecordSink(
     private val syncer: HttpSyncer,
     private val events: EventBus,
     private val hooks: RecordHooks = RecordHooks(),
+    /** Free bytes of the app's storage, for the `StorageFull` event; null if unknown. */
+    private val diskFreeBytes: () -> Long? = { null },
 ) : RecordSink {
     override suspend fun submit(record: Record): Record {
         val stored = try {
@@ -56,6 +60,14 @@ class DefaultRecordSink(
             throw e
         } catch (e: Exception) {
             Logger.e(TAG, "failed to persist ${record.event.wire} record ${record.uuid}", e)
+            if (isStorageFull(e)) {
+                val free = try {
+                    diskFreeBytes()
+                } catch (x: Exception) {
+                    null
+                }
+                events.emit(TrackingEvent.StorageFull(record.uuid, record.event, free))
+            }
             false
         }
 
@@ -91,5 +103,11 @@ class DefaultRecordSink(
 
     private companion object {
         const val TAG = "LT.RecordSink"
+
+        /** True if [e] or one of its causes is `SQLiteFullException` (or an "out of disk space" I/O error). */
+        fun isStorageFull(e: Throwable): Boolean = generateSequence(e) { it.cause }.take(8).any {
+            it is SQLiteFullException || it.message?.contains("SQLITE_FULL") == true ||
+                it.message?.contains("ENOSPC") == true
+        }
     }
 }

package/android/src/main/java/com/brickssoft/locationtracking/service/BootCountStore.kt

@@ -37,6 +37,13 @@ internal class BootCountStore(context: Context) {
     private fun read(key: String): Int? = if (prefs.contains(key)) prefs.getInt(key, -1) else null
 
     companion object {
+        /** Forgets every stored boot count (the state was restored onto another installation). */
+        @SuppressLint("ApplySharedPref")
+        fun clear(context: Context) {
+            (context.applicationContext ?: context).getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+                .edit().clear().commit()
+        }
+
         const val PREFS_NAME = "location_tracking_boot"
         private const val KEY_LAST_HANDLED = "last_handled_boot_count"
         private const val KEY_LAST_SERVICE_START = "last_service_start_boot_count"

package/android/src/main/res/xml/lt_file_paths.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
 <paths>
-    <files-path name="lt_logs" path="location-tracking-logs/" />
+    <!-- Only the gzipped copy in the cache is shared (emailLog); the daily files are under noBackupFilesDir. -->
     <cache-path name="lt_logs_cache" path="location-tracking-logs/" />
 </paths>

package/dist/esm/definitions.d.ts

@@ -121,6 +121,12 @@ export interface HeartbeatConfig {
      * @default 300
      */
     maxInterval?: number;
+    /**
+     * seconds, 0..60. After a heartbeat is queued, keep the phone awake until its upload has finished, or at most this
+     * long, so it reaches the server on time while tracking is on. 0 = do not keep the phone awake.
+     * @default 10
+     */
+    uploadKeepAwake?: number;
 }
 export interface AuthorizationConfig {
     /** @default 'JWT' */
@@ -186,6 +192,11 @@ export interface HttpConfig {
      * @default 60000
      */
     timeout?: number;
+    /**
+     * seconds, >= 0. The longest wait that a `Retry-After` header of a 429 or 503 answer can impose on automatic uploads.
+     * @default 3600
+     */
+    maxRetryAfter?: number;
     authorization?: AuthorizationConfig | null;
 }
 export interface PersistenceConfig {
@@ -301,8 +312,22 @@ export interface State {
     odometer: number;
     backend: LocationBackend;
     lastRecordAt: string | null;
-    /** fully populated with defaults */
+    /** reason of the last `tracking_stop` record (the `tracking_stop` reasons of `Location.reason`); null if none */
+    lastStopReason: string | null;
+    /** when tracking stopped for `lastStopReason` (ISO-8601 UTC ms); null if none */
+    lastStopAt: string | null;
+    /**
+     * fully populated with defaults. On Android the `http.authorization` secrets (`accessToken`, `refreshToken`, the
+     * values of `refreshPayload` and `refreshHeaders`) are masked: `***`, or `***` plus the last 4 characters for values
+     * longer than 8 characters; a `refreshPayload` value that contains `{refreshToken}` is shown. Passing a masked value
+     * back to `setConfig` keeps the stored one. The web stub returns them as given.
+     */
     config: Config;
+    /**
+     * `ready()`, `setConfig()` and `reset()` only: what the given config contains that was accepted but is probably
+     * wrong (for example an `http://` upload URL).
+     */
+    warnings?: string[];
 }
 export interface Coords {
     latitude: number;
@@ -343,10 +368,16 @@ export interface Location {
         type: ActivityType;
         confidence: number;
     };
-    /** level 0..1, -1 unknown */
+    /**
+     * level 0..1, -1 unknown. Heartbeat records also carry `temperature` (°C), `health` and `plugged` when the device
+     * reports them.
+     */
     battery: {
         level: number;
         is_charging: boolean;
+        temperature?: number;
+        health?: 'good' | 'overheat' | 'dead' | 'over_voltage' | 'cold' | 'failure' | 'unknown';
+        plugged?: 'ac' | 'usb' | 'wireless' | 'dock' | 'none' | 'other';
     };
     backend: LocationBackend | null;
     extras?: Record<string, unknown>;
@@ -360,11 +391,45 @@ export interface Location {
     provider?: ProviderState;
     /**
      * tracking_start: start|start_geofences|boot|restore|package_replaced|resume_notification;
-     * tracking_stop: stop|stop_on_stationary|stop_after_elapsed|terminate|permission_denied|service_start_failed|reboot|package_replaced
+     * tracking_stop: stop|stop_on_stationary|stop_after_elapsed|terminate|permission_denied|service_start_failed|reboot|package_replaced|user_stopped
      */
     reason?: string;
+    /** event 'tracking_stop' with reason 'user_stopped' only: when the user stopped the app (ISO-8601 UTC ms) */
+    stopped_at?: string;
     /** event 'heartbeat' only, optional: how the heartbeat is scheduled */
     heartbeat?: HeartbeatMeta;
+    /** connection type when the record was created */
+    network?: ConnectivityType;
+    /** the device id on every record; more readings on 'heartbeat' and 'tracking_start' records (see `DeviceReadings`) */
+    device?: DeviceReadings;
+}
+/**
+ * The `device` object of records; a reading is present only when the device provides it.
+ * Every record: `device_id`.
+ * Heartbeat records: `background_restricted`, `standby_bucket`, `disk_free_bytes`, `thermal_status`.
+ * `tracking_start` records: `manufacturer`, `model`, `os_version`, `sdk_int`, `low_ram_device`, `ram_total_bytes`.
+ */
+export interface DeviceReadings {
+    /**
+     * the device id: on Android, `Settings.Secure.ANDROID_ID`; other platforms will fill it with their own id.
+     * Absent in records queued by an older version. Declare "Device or other IDs" in Google Play's Data safety form.
+     */
+    device_id?: string;
+    /** the user set the app's battery use to "Restricted" (Android 9+) */
+    background_restricted?: boolean;
+    /** App Standby bucket (Android 9+) */
+    standby_bucket?: 'exempted' | 'active' | 'working_set' | 'frequent' | 'rare' | 'restricted';
+    /** free space on the storage that holds the app's files */
+    disk_free_bytes?: number;
+    /** Android 10+ */
+    thermal_status?: 'none' | 'light' | 'moderate' | 'severe' | 'critical' | 'emergency' | 'shutdown' | 'unknown';
+    manufacturer?: string;
+    model?: string;
+    /** Android version, e.g. "14" */
+    os_version?: string;
+    sdk_int?: number;
+    low_ram_device?: boolean;
+    ram_total_bytes?: number;
 }
 /** Scheduling metadata of a `heartbeat` record (snake_case = wire format). */
 export interface HeartbeatMeta {
@@ -382,7 +447,8 @@ export interface HeartbeatMeta {
 }
 export type LocationRecord = Location;
 export interface InsertLocationInput {
-    coords: Pick<Coords, 'latitude' | 'longitude'> & Partial<Coords>;
+    /** `accuracy` (m) is required and must be greater than 0; otherwise the call rejects with `INVALID_ARGUMENT`. */
+    coords: Pick<Coords, 'latitude' | 'longitude' | 'accuracy'> & Partial<Coords>;
     timestamp?: string;
     event?: RecordEvent;
     is_moving?: boolean;
@@ -449,6 +515,25 @@ export interface PowerSaveChangeEvent {
 }
 export interface EnabledChangeEvent {
     enabled: boolean;
+    /**
+     * why: a `tracking_start` reason when tracking was switched on (start, start_geofences, resume_notification), a
+     * `tracking_stop` reason when it was switched off; the same values as `Location.reason`
+     */
+    reason: string | null;
+}
+/** The location request failed (no permission, Play services or HMS Core refused it, no usable provider). */
+export interface LocationErrorEvent {
+    code: ErrorCode;
+    message: string;
+    backend: LocationBackend;
+    /** the plugin requests location updates again after this many ms; null if it does not */
+    retryInMs: number | null;
+}
+/** A record could not be stored because the device storage is full. */
+export interface StorageFullEvent {
+    uuid: string;
+    event: RecordEvent;
+    diskFreeBytes: number | null;
 }
 export interface NotificationActionEvent {
     id: string;
@@ -473,6 +558,8 @@ export interface LocationTrackingEventMap {
     enabledchange: EnabledChangeEvent;
     notificationaction: NotificationActionEvent;
     authorization: AuthorizationEvent;
+    locationerror: LocationErrorEvent;
+    storagefull: StorageFullEvent;
 }
 export type LocationTrackingEventName = keyof LocationTrackingEventMap;
 export interface CurrentPositionOptions {
@@ -545,6 +632,20 @@ export interface DeviceInfo {
     hmsAvailable: boolean;
     backend: LocationBackend;
     packagedProviders: string[];
+    /** why a better location backend is not used (for example "gms: unavailable (status 2)"); null when none is better */
+    backendFallbackReason: string | null;
+    /** raw GoogleApiAvailability result (0 = success); null if GMS is not packaged or not checked yet */
+    gmsStatus: number | null;
+    /** raw HuaweiApiAvailability result (0 = success); null if HMS is not packaged or not checked yet */
+    hmsStatus: number | null;
+    /** true when HMS Core is older than 6.3.0.301; null if HMS is not packaged */
+    hmsCoreOutdated: boolean | null;
+    /** last LocationAvailability reported by GMS or HMS; only a hint (it can be wrong both ways); null if none */
+    locationAvailableHint: boolean | null;
+    /** number of CPU cores */
+    cpuCores: number;
+    /** CPU types (Build.SUPPORTED_ABIS), e.g. ["arm64-v8a"] */
+    supportedAbis: string[];
 }
 export interface Sensors {
     accelerometer: boolean;
@@ -715,5 +816,7 @@ export interface LocationTrackingPlugin {
     addListener(eventName: 'enabledchange', listenerFunc: (e: EnabledChangeEvent) => void): Promise<PluginListenerHandle>;
     addListener(eventName: 'notificationaction', listenerFunc: (e: NotificationActionEvent) => void): Promise<PluginListenerHandle>;
     addListener(eventName: 'authorization', listenerFunc: (e: AuthorizationEvent) => void): Promise<PluginListenerHandle>;
+    addListener(eventName: 'locationerror', listenerFunc: (e: LocationErrorEvent) => void): Promise<PluginListenerHandle>;
+    addListener(eventName: 'storagefull', listenerFunc: (e: StorageFullEvent) => void): Promise<PluginListenerHandle>;
     removeAllListeners(): Promise<void>;
 }