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

package/android/src/main/java/com/brickssoft/locationtracking/processing/DefaultRecordFactory.kt

@@ -0,0 +1,166 @@
+package com.brickssoft.locationtracking.processing
+
+import com.brickssoft.locationtracking.config.ConfigStore
+import com.brickssoft.locationtracking.core.Clock
+import com.brickssoft.locationtracking.core.ErrorCode
+import com.brickssoft.locationtracking.core.Iso8601
+import com.brickssoft.locationtracking.core.Logger
+import com.brickssoft.locationtracking.core.TrackingException
+import com.brickssoft.locationtracking.device.DeviceMonitor
+import com.brickssoft.locationtracking.model.BatterySnapshot
+import com.brickssoft.locationtracking.model.GeofenceHit
+import com.brickssoft.locationtracking.model.JsonUtil
+import com.brickssoft.locationtracking.model.ProviderKind
+import com.brickssoft.locationtracking.model.ProviderState
+import com.brickssoft.locationtracking.model.Record
+import com.brickssoft.locationtracking.model.RecordEvent
+import com.brickssoft.locationtracking.model.TrackedLocation
+import com.brickssoft.locationtracking.provider.ProviderFactory
+import org.json.JSONObject
+import java.util.UUID
+
+/**
+ * Builds records: uuid v4, clock and boot metadata, runtime state (isMoving, odometer, activity), battery and
+ * the current provider state (unless the caller passes one, as `providerchange` does) from [device], backend from
+ * [providers], and `extras` = `persistence.extras` merged with the per-call extras (per-call keys win; null when
+ * both are empty).
+ */
+class DefaultRecordFactory(
+    private val configStore: ConfigStore,
+    private val device: DeviceMonitor,
+    private val providers: ProviderFactory,
+    private val clock: Clock,
+) : RecordFactory {
+    override fun create(
+        event: RecordEvent,
+        location: TrackedLocation?,
+        extras: String?,
+        geofence: GeofenceHit?,
+        provider: ProviderState?,
+        reason: String?,
+    ): Record {
+        val runtime = configStore.runtime.value
+        return Record(
+            uuid = UUID.randomUUID().toString(),
+            event = event,
+            location = location,
+            recordedAt = clock.now(),
+            elapsedRealtimeMs = clock.elapsedRealtime(),
+            bootCount = clock.bootCount(),
+            isMoving = runtime.isMoving,
+            odometer = runtime.odometer,
+            activity = runtime.activity,
+            battery = battery(),
+            backend = backend(),
+            extras = mergeExtras(configStore.config.value.persistence.extras, extras),
+            geofence = geofence,
+            provider = provider ?: providerState(),
+            reason = reason,
+        )
+    }
+
+    /**
+     * Parses a JS `InsertLocationInput`: `{coords:{latitude, longitude, accuracy?, altitude?, ...}, timestamp?,
+     * event?, is_moving?, extras?}`. `accuracy` defaults to 0; negative optional accuracies, speed and heading
+     * (the "unknown" sentinel of some platforms) become null.
+     *
+     * @throws TrackingException INVALID_ARGUMENT if coords, latitude or longitude are missing or invalid, if
+     *   accuracy is negative, or if `timestamp`, `event`, `is_moving` or `extras` are given but invalid.
+     */
+    override fun fromExternal(input: JSONObject): Record {
+        val coords = input.optJSONObject("coords") ?: invalid("location.coords is required")
+        val latitude = JsonUtil.optDouble(coords, "latitude") ?: invalid("coords.latitude is required")
+        val longitude = JsonUtil.optDouble(coords, "longitude") ?: invalid("coords.longitude is required")
+        if (!Geo.isValid(latitude, longitude)) invalid("coords ($latitude, $longitude) are out of range")
+
+        val time = if (input.isNull("timestamp")) {
+            clock.now()
+        } else {
+            val text = JsonUtil.optString(input, "timestamp")
+            Iso8601.parse(text) ?: invalid("timestamp '$text' is not an ISO-8601 date")
+        }
+        val event = if (input.isNull("event")) {
+            RecordEvent.LOCATION
+        } else {
+            val wire = JsonUtil.optString(input, "event")
+            RecordEvent.fromWire(wire) ?: invalid("unknown event '$wire'")
+        }
+        val isMoving = if (input.isNull("is_moving")) {
+            null
+        } else {
+            JsonUtil.optBoolean(input, "is_moving") ?: invalid("is_moving must be a boolean")
+        }
+        val accuracy = JsonUtil.optFloat(coords, "accuracy") ?: 0f
+        if (accuracy < 0) invalid("coords.accuracy must be >= 0")
+        val extras = if (input.isNull("extras")) {
+            null
+        } else {
+            input.optJSONObject("extras")?.toString() ?: invalid("extras must be an object")
+        }
+        val location = TrackedLocation(
+            latitude = latitude,
+            longitude = longitude,
+            accuracy = accuracy,
+            altitude = JsonUtil.optDouble(coords, "altitude"),
+            altitudeAccuracy = nonNegative(coords, "altitude_accuracy"),
+            speed = nonNegative(coords, "speed"),
+            speedAccuracy = nonNegative(coords, "speed_accuracy"),
+            heading = nonNegative(coords, "heading"),
+            headingAccuracy = nonNegative(coords, "heading_accuracy"),
+            time = time,
+        )
+        val record = create(event, location, extras)
+        return if (isMoving == null) record else record.copy(isMoving = isMoving)
+    }
+
+    private fun nonNegative(json: JSONObject, key: String): Float? = JsonUtil.optFloat(json, key)?.takeIf { it >= 0 }
+
+    private fun battery(): BatterySnapshot = try {
+        device.battery()
+    } catch (e: Exception) {
+        Logger.w(TAG, "battery unavailable", e)
+        BatterySnapshot.UNKNOWN
+    }
+
+    // Read live, not the persisted runtime.providerState, which lags until the next provider check.
+    private fun providerState(): ProviderState? = try {
+        device.providerState()
+    } catch (e: Exception) {
+        Logger.w(TAG, "provider state unavailable", e)
+        null
+    }
+
+    private fun backend(): ProviderKind? = try {
+        providers.kind
+    } catch (e: Exception) {
+        Logger.w(TAG, "backend unavailable", e)
+        null
+    }
+
+    private fun invalid(message: String): Nothing = throw TrackingException(ErrorCode.INVALID_ARGUMENT, message)
+
+    internal companion object {
+        private const val TAG = "LT.RecordFactory"
+
+        /**
+         * Shallow merge of two JSON object texts; keys of [perCall] win over [base]. Invalid text is logged
+         * and ignored. Returns null when the result has no keys.
+         */
+        fun mergeExtras(base: String?, perCall: String?): String? {
+            val merged = parseExtras(base, "persistence.extras") ?: JSONObject()
+            parseExtras(perCall, "extras")?.let { overrides ->
+                val keys = overrides.keys()
+                while (keys.hasNext()) {
+                    val key = keys.next()
+                    merged.put(key, overrides.opt(key))
+                }
+            }
+            return if (merged.length() == 0) null else merged.toString()
+        }
+
+        private fun parseExtras(text: String?, name: String): JSONObject? {
+            if (text.isNullOrBlank()) return null
+            return JsonUtil.parseObject(text).also { if (it == null) Logger.w(TAG, "ignoring $name: not a JSON object") }
+        }
+    }
+}

package/android/src/main/java/com/brickssoft/locationtracking/processing/Geo.kt

@@ -0,0 +1,56 @@
+package com.brickssoft.locationtracking.processing
+
+import com.brickssoft.locationtracking.model.TrackedLocation
+import kotlin.math.asin
+import kotlin.math.cos
+import kotlin.math.min
+import kotlin.math.sin
+import kotlin.math.sqrt
+
+/** Great-circle geometry on a spherical Earth. */
+internal object Geo {
+    /** Mean Earth radius (IUGG), meters. */
+    const val EARTH_RADIUS_M = 6_371_008.8
+
+    /** Haversine distance in meters between two points given in degrees. */
+    fun haversine(lat1: Double, lng1: Double, lat2: Double, lng2: Double): Double {
+        val phi1 = Math.toRadians(lat1)
+        val phi2 = Math.toRadians(lat2)
+        val dPhi = Math.toRadians(lat2 - lat1)
+        val dLambda = Math.toRadians(lng2 - lng1)
+        val sinPhi = sin(dPhi / 2)
+        val sinLambda = sin(dLambda / 2)
+        val h = sinPhi * sinPhi + cos(phi1) * cos(phi2) * sinLambda * sinLambda
+        // Clamp: rounding can push h slightly above 1 for antipodal points.
+        return 2 * EARTH_RADIUS_M * asin(sqrt(min(1.0, h)))
+    }
+
+    /** Haversine distance in meters between two fixes. */
+    fun distance(a: TrackedLocation, b: TrackedLocation): Double =
+        haversine(a.latitude, a.longitude, b.latitude, b.longitude)
+
+    /** True if both coordinates are finite and within the valid latitude / longitude ranges. */
+    fun isValid(latitude: Double, longitude: Double): Boolean =
+        latitude.isFinite() && longitude.isFinite() && latitude in -90.0..90.0 && longitude in -180.0..180.0
+
+    /** Wraps a longitude difference into [-180, 180), so steps across the antimeridian stay short. */
+    fun wrapLongitudeDelta(delta: Double): Double {
+        val wrapped = (delta + 180.0) % 360.0
+        return (if (wrapped < 0) wrapped + 360.0 else wrapped) - 180.0
+    }
+
+    /** Normalizes a longitude into [-180, 180]. */
+    fun normalizeLongitude(longitude: Double): Double =
+        if (longitude in -180.0..180.0) longitude else wrapLongitudeDelta(longitude)
+
+    /**
+     * Milliseconds from [from] to [to]: on the monotonic elapsed-realtime clock when both fixes carry it,
+     * otherwise on the wall clock (`time`).
+     */
+    fun elapsedMs(from: TrackedLocation, to: TrackedLocation): Long =
+        if (from.elapsedRealtimeNanos > 0 && to.elapsedRealtimeNanos > 0) {
+            (to.elapsedRealtimeNanos - from.elapsedRealtimeNanos) / 1_000_000
+        } else {
+            to.time - from.time
+        }
+}

package/android/src/main/java/com/brickssoft/locationtracking/processing/KalmanFilter.kt

@@ -0,0 +1,72 @@
+package com.brickssoft.locationtracking.processing
+
+import com.brickssoft.locationtracking.model.TrackedLocation
+import kotlin.math.max
+
+/**
+ * 1-D constant-position Kalman filter applied per axis to latitude and longitude.
+ *
+ * - Measurement variance is `accuracy²` (m², accuracy floored at [MIN_ACCURACY_M]).
+ * - Process noise per step is `q = speed² · dt` (m², dt in seconds). `speed` is the fix's speed floored at
+ *   [MIN_SPEED_MPS] (so the estimate never freezes), or [DEFAULT_SPEED_MPS] when the fix has none. For gaps
+ *   over 1 s, `q` grows as `(speed · dt)²` because displacement grows linearly with time.
+ * - Both axes share one variance because `accuracy` is a horizontal radius. Longitude steps are wrapped, so
+ *   tracks across the antimeridian are smoothed correctly.
+ * - `dt` uses the elapsed-realtime clock when both fixes carry it (see [Geo.elapsedMs]).
+ * - The filter restarts from the measurement when the gap exceeds [resetAfterMs], when time goes
+ *   backwards, or after [reset].
+ *
+ * Only latitude and longitude are replaced; every other field of the fix is returned unchanged.
+ * Not thread-safe: [DefaultLocationProcessor] serializes access.
+ */
+internal class KalmanFilter(
+    private val resetAfterMs: Long = DEFAULT_RESET_AFTER_MS,
+) {
+    /** The last measurement (time reference), or null before the first fix / after [reset]. */
+    private var last: TrackedLocation? = null
+    private var latitude = 0.0
+    private var longitude = 0.0
+
+    /** Estimate variance, m². */
+    private var variance = 0.0
+
+    /** Returns [location] with smoothed latitude / longitude. */
+    fun filter(location: TrackedLocation): TrackedLocation {
+        val accuracy = location.accuracy.toDouble().takeIf { it.isFinite() && it > MIN_ACCURACY_M } ?: MIN_ACCURACY_M
+        val measurementVariance = accuracy * accuracy
+        val previous = last
+        val dtMs = previous?.let { Geo.elapsedMs(it, location) }
+        if (dtMs == null || dtMs < 0 || dtMs > resetAfterMs) {
+            last = location
+            latitude = location.latitude
+            longitude = location.longitude
+            variance = measurementVariance
+            return location
+        }
+        last = location
+        if (dtMs > 0) {
+            val reported = location.speed?.toDouble()?.takeIf { it.isFinite() && it >= 0 }
+            val speed = reported?.let { max(it, MIN_SPEED_MPS) } ?: DEFAULT_SPEED_MPS
+            val dt = dtMs / 1000.0
+            variance += speed * speed * dt * max(1.0, dt)
+        }
+        val gain = variance / (variance + measurementVariance)
+        latitude += gain * (location.latitude - latitude)
+        longitude = Geo.normalizeLongitude(longitude + gain * Geo.wrapLongitudeDelta(location.longitude - longitude))
+        variance *= 1 - gain
+        return location.copy(latitude = latitude, longitude = longitude)
+    }
+
+    /** Forgets all history; the next fix is returned unchanged. */
+    fun reset() {
+        last = null
+        variance = 0.0
+    }
+
+    companion object {
+        const val DEFAULT_RESET_AFTER_MS = 60_000L
+        const val DEFAULT_SPEED_MPS = 3.0
+        const val MIN_SPEED_MPS = 1.0
+        const val MIN_ACCURACY_M = 1.0
+    }
+}

package/android/src/main/java/com/brickssoft/locationtracking/processing/Processing.kt

@@ -0,0 +1,48 @@
+package com.brickssoft.locationtracking.processing
+
+import com.brickssoft.locationtracking.model.GeofenceHit
+import com.brickssoft.locationtracking.model.ProviderState
+import com.brickssoft.locationtracking.model.Record
+import com.brickssoft.locationtracking.model.RecordEvent
+import com.brickssoft.locationtracking.model.TrackedLocation
+import org.json.JSONObject
+
+sealed interface FilterResult {
+    data class Accepted(val location: TrackedLocation) : FilterResult
+
+    data class Rejected(val reason: String) : FilterResult
+}
+
+/** Accuracy / implied-speed / identical / mock filters and optional Kalman smoothing. */
+interface LocationProcessor {
+    fun process(raw: TrackedLocation, isMoving: Boolean): FilterResult
+
+    fun reset()
+}
+
+/** Distance accumulator; persists its value via `configStore.updateRuntime`. */
+interface Odometer {
+    val value: Double
+
+    fun onLocation(location: TrackedLocation)
+
+    fun set(value: Double)
+
+    fun reset()
+}
+
+/** Builds records with uuid, clock/boot metadata, runtime state, battery and backend. */
+interface RecordFactory {
+    /** Merges `persistence.extras`; reads runtime (isMoving, odometer, activity), battery and clock. */
+    fun create(
+        event: RecordEvent,
+        location: TrackedLocation?,
+        extras: String? = null,
+        geofence: GeofenceHit? = null,
+        provider: ProviderState? = null,
+        reason: String? = null,
+    ): Record
+
+    /** `insertLocation`: builds a record from a JS `InsertLocationInput`. */
+    fun fromExternal(input: JSONObject): Record
+}

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

@@ -0,0 +1,187 @@
+package com.brickssoft.locationtracking.provider
+
+import com.brickssoft.locationtracking.model.ActivitySample
+import com.brickssoft.locationtracking.model.DesiredAccuracy
+import com.brickssoft.locationtracking.model.GeofenceAction
+import com.brickssoft.locationtracking.model.ProviderKind
+import com.brickssoft.locationtracking.model.TrackedLocation
+
+/** A continuous location request. */
+data class LocationRequestSpec(
+    val accuracy: DesiredAccuracy,
+    val intervalMs: Long,
+    val fastestIntervalMs: Long,
+    val distanceFilterM: Float,
+)
+
+/** Receives batches of fixes, on any thread. */
+fun interface LocationListener {
+    fun onLocations(locations: List<TrackedLocation>)
+}
+
+/** Location updates and one-shot fixes from one backend. */
+interface LocationBackend {
+    val kind: ProviderKind
+
+    /**
+     * Supports multiple listeners; requesting again with the same listener replaces its request. A `distanceFilterM`
+     * of 0 means no distance filter (the engine applies its own elastic filter). Never throws: failures such as a
+     * missing permission are logged and the listener receives nothing.
+     */
+    fun requestUpdates(spec: LocationRequestSpec, listener: LocationListener)
+
+    fun removeUpdates(listener: LocationListener)
+
+    /** The OS's cached last location. Implementations may throw `TrackingException(PERMISSION_DENIED)`; callers catch. */
+    suspend fun getLastLocation(): TrackedLocation?
+
+    /** Returns null on timeout. @throws com.brickssoft.locationtracking.core.TrackingException PERMISSION_DENIED */
+    suspend fun getCurrentLocation(accuracy: DesiredAccuracy, timeoutMs: Long): TrackedLocation?
+}
+
+/** Activity recognition. Samples are delivered through a PendingIntent receiver to [ActivitySink]. */
+interface ActivityBackend {
+    val kind: ProviderKind
+    val isSupported: Boolean
+
+    /** Returns false if updates could not be requested. */
+    fun start(intervalMs: Long): Boolean
+
+    fun stop()
+}
+
+/** A geofence as registered with the OS. */
+data class OsGeofence(
+    val id: String,
+    val latitude: Double,
+    val longitude: Double,
+    val radius: Float,
+    val onEntry: Boolean,
+    val onExit: Boolean,
+    val onDwell: Boolean,
+    val loiteringDelayMs: Int,
+    val initialTriggerEntry: Boolean,
+)
+
+/** A transition reported by the OS; [location] is the triggering fix if the backend provides one. */
+data class OsGeofenceTransition(val id: String, val action: GeofenceAction, val location: TrackedLocation?)
+
+/** OS geofencing. Transitions are delivered through a PendingIntent receiver to [GeofenceTransitionSink]. */
+interface GeofenceBackend {
+    val kind: ProviderKind
+    val supportsDwell: Boolean
+
+    /** @throws com.brickssoft.locationtracking.core.TrackingException */
+    suspend fun add(regions: List<OsGeofence>)
+
+    /** @throws com.brickssoft.locationtracking.core.TrackingException */
+    suspend fun remove(ids: List<String>)
+
+    /** @throws com.brickssoft.locationtracking.core.TrackingException */
+    suspend fun removeAll()
+}
+
+/**
+ * The three backends of one SDK. Implementations are created only by reflection through a public
+ * `(android.content.Context)` constructor; see [ProviderBundles].
+ */
+interface ProviderBundle {
+    val kind: ProviderKind
+
+    /** True if the SDK is packaged and usable on this device (e.g. `GoogleApiAvailability` SUCCESS). */
+    fun isAvailable(): Boolean
+
+    fun location(): LocationBackend
+
+    fun activity(): ActivityBackend
+
+    fun geofence(): GeofenceBackend
+}
+
+/** Selects the active backend from config `locationProvider` (see architecture "GMS/HMS selection"). */
+interface ProviderFactory {
+    val kind: ProviderKind
+
+    fun location(): LocationBackend
+
+    fun activity(): ActivityBackend
+
+    fun geofence(): GeofenceBackend
+
+    fun isAvailable(kind: ProviderKind): Boolean
+
+    /** Re-evaluates the selection (e.g. after setConfig). Returns true if [kind] changed. */
+    fun reselect(): Boolean
+}
+
+/** Implemented by the TrackingEngine. */
+interface ActivitySink {
+    suspend fun onActivitySamples(samples: List<ActivitySample>)
+}
+
+/** Implemented by the GeofenceManager. */
+interface GeofenceTransitionSink {
+    suspend fun onGeofenceTransitions(transitions: List<OsGeofenceTransition>)
+}
+
+/**
+ * Implemented by the TrackingEngine (round 2, stationary GPS-off mode). While STATIONARY the engine registers one OS
+ * geofence with id [com.brickssoft.locationtracking.core.Constants.STATIONARY_REGION_ID] directly with
+ * `providers.geofence()`. The GeofenceManager forwards every transition with that id here, and never stores, records
+ * or emits it.
+ */
+interface StationaryRegionSink {
+    suspend fun onStationaryRegionTransition(transition: OsGeofenceTransition)
+
+    companion object {
+        /** Ignores every transition (tests and callers without an engine). */
+        val NONE: StationaryRegionSink = object : StationaryRegionSink {
+            override suspend fun onStationaryRegionTransition(transition: OsGeofenceTransition) = Unit
+        }
+    }
+}
+
+/** Fully qualified class names used for reflective loading. Strings only: never reference SDK types here. */
+object ProviderBundles {
+    const val GMS_BUNDLE = "com.brickssoft.locationtracking.provider.gms.GmsProviderBundle"
+    const val HMS_BUNDLE = "com.brickssoft.locationtracking.provider.hms.HmsProviderBundle"
+    const val ANDROID_BUNDLE = "com.brickssoft.locationtracking.provider.android.AndroidProviderBundle"
+
+    /** Present only when play-services-location is packaged. */
+    const val GMS_SDK_CLASS = "com.google.android.gms.location.LocationServices"
+
+    /** Present only when com.huawei.hms:location is packaged. */
+    const val HMS_SDK_CLASS = "com.huawei.hms.location.LocationServices"
+
+    /** The receivers the GMS backend's activity and geofence results are delivered to. */
+    val GMS_RECEIVERS = listOf(
+        "com.brickssoft.locationtracking.provider.gms.GmsActivityReceiver",
+        "com.brickssoft.locationtracking.provider.gms.GmsGeofenceReceiver",
+    )
+
+    /** The receivers the HMS backend's activity and geofence results are delivered to. */
+    val HMS_RECEIVERS = listOf(
+        "com.brickssoft.locationtracking.provider.hms.HmsActivityReceiver",
+        "com.brickssoft.locationtracking.provider.hms.HmsGeofenceReceiver",
+    )
+
+    /** The SDK class whose presence means [kind]'s SDK is in the APK; null for ANDROID (part of the platform). */
+    fun sdkClassName(kind: ProviderKind): String? = when (kind) {
+        ProviderKind.GMS -> GMS_SDK_CLASS
+        ProviderKind.HMS -> HMS_SDK_CLASS
+        ProviderKind.ANDROID -> null
+    }
+
+    /** The receivers [kind]'s backend needs in the merged manifest; none for ANDROID. */
+    fun receiverClassNames(kind: ProviderKind): List<String> = when (kind) {
+        ProviderKind.GMS -> GMS_RECEIVERS
+        ProviderKind.HMS -> HMS_RECEIVERS
+        ProviderKind.ANDROID -> emptyList()
+    }
+
+    fun bundleClassName(kind: ProviderKind): String = when (kind) {
+        ProviderKind.GMS -> GMS_BUNDLE
+        ProviderKind.HMS -> HMS_BUNDLE
+        ProviderKind.ANDROID -> ANDROID_BUNDLE
+    }
+}