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

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

@@ -0,0 +1,169 @@
+package com.brickssoft.locationtracking.provider
+
+import android.content.Context
+import com.brickssoft.locationtracking.config.ConfigStore
+import com.brickssoft.locationtracking.core.Logger
+import com.brickssoft.locationtracking.model.LocationProviderSetting
+import com.brickssoft.locationtracking.model.ProviderKind
+import com.brickssoft.locationtracking.provider.android.AndroidProviderBundle
+
+/**
+ * Selects GMS, HMS or the platform `LocationManager` from config `locationProvider`:
+ * - `auto`: GMS if it is packaged ([ProviderPackaging]: allowed by the app's `PROVIDERS` meta-data, SDK class present,
+ *   receivers declared) and its bundle is available; else HMS likewise; else ANDROID.
+ * - `gms` / `hms`: that backend, or ANDROID (with a warning) if it is not packaged or not available.
+ * - `android`: always ANDROID.
+ *
+ * Bundles are created only by reflection ([ProviderBundles]) and cached; any [Throwable] while probing or creating
+ * one (e.g. [NoClassDefFoundError]) marks it unavailable. Selection is lazy (first access), thread-safe, and
+ * re-evaluated only by [reselect].
+ *
+ * @param classPresent whether a class can be loaded; defaults to `Class.forName(name, false, loader)`.
+ * @param createBundle instantiates a bundle class by name; defaults to its public (Context) constructor.
+ * @param receiverDeclared whether a receiver is declared in the merged manifest; defaults to `getReceiverInfo`.
+ * @param providersMetaData the app's `PROVIDERS` meta-data value, or null; defaults to the application's meta-data.
+ */
+class DefaultProviderFactory(
+    context: Context,
+    private val configStore: ConfigStore,
+    classPresent: (String) -> Boolean = reflectiveClassPresent(context.classLoader),
+    private val createBundle: (String) -> ProviderBundle = reflectiveBundleCreator(context),
+    receiverDeclared: (String) -> Boolean = ProviderPackaging.receiverDeclaredIn(context.applicationContext ?: context),
+    providersMetaData: () -> String? = ProviderPackaging.providersMetaDataIn(context.applicationContext ?: context),
+) : ProviderFactory {
+    private val appContext: Context = context.applicationContext ?: context
+
+    private val packaging = ProviderPackaging(classPresent, receiverDeclared, providersMetaData)
+
+    private val lock = Any()
+
+    @Volatile
+    private var selection: Selection? = null
+
+    /** Created bundles; a null value means the bundle could not be loaded. Guarded by [lock]. */
+    private val bundles = HashMap<ProviderKind, ProviderBundle?>()
+
+    override val kind: ProviderKind get() = current().kind
+
+    override fun location(): LocationBackend = current().bundle.location()
+
+    override fun activity(): ActivityBackend = current().bundle.activity()
+
+    override fun geofence(): GeofenceBackend = current().bundle.geofence()
+
+    override fun isAvailable(kind: ProviderKind): Boolean {
+        val bundle = synchronized(lock) { bundleLocked(kind) } ?: return false
+        return isUsable(bundle)
+    }
+
+    override fun reselect(): Boolean = synchronized(lock) {
+        val previous = selection
+        val next = selectLocked()
+        selection = next
+        previous != null && previous.kind != next.kind
+    }
+
+    private fun current(): Selection =
+        selection ?: synchronized(lock) { selection ?: selectLocked().also { selection = it } }
+
+    private fun selectLocked(): Selection {
+        val setting = configStore.config.value.locationProvider
+        val kind = when (setting) {
+            LocationProviderSetting.AUTO -> when {
+                availableLocked(ProviderKind.GMS) -> ProviderKind.GMS
+                availableLocked(ProviderKind.HMS) -> ProviderKind.HMS
+                else -> ProviderKind.ANDROID
+            }
+            LocationProviderSetting.GMS -> explicitLocked(ProviderKind.GMS)
+            LocationProviderSetting.HMS -> explicitLocked(ProviderKind.HMS)
+            LocationProviderSetting.ANDROID -> ProviderKind.ANDROID
+        }
+        val bundle = if (kind == ProviderKind.ANDROID) androidBundleLocked() else checkNotNull(bundles[kind])
+        if (selection?.kind != kind) Logger.i(TAG, "location backend: ${kind.wire} (locationProvider=${setting.wire})")
+        return Selection(kind, bundle)
+    }
+
+    private fun explicitLocked(kind: ProviderKind): ProviderKind {
+        if (availableLocked(kind)) return kind
+        Logger.w(TAG, "locationProvider=${kind.wire} is not packaged or not available; falling back to android")
+        return ProviderKind.ANDROID
+    }
+
+    private fun availableLocked(kind: ProviderKind): Boolean = bundleLocked(kind)?.let(::isUsable) ?: false
+
+    /** The cached bundle of [kind], loading it on first use; null if its SDK or bundle class cannot be loaded. */
+    private fun bundleLocked(kind: ProviderKind): ProviderBundle? {
+        if (bundles.containsKey(kind)) return bundles[kind]
+        val bundle = loadBundle(kind)
+        bundles[kind] = bundle
+        return bundle
+    }
+
+    private fun loadBundle(kind: ProviderKind): ProviderBundle? {
+        val reason = when (packaging.status(kind)) {
+            ProviderPackaging.Status.PACKAGED -> null
+            ProviderPackaging.Status.NOT_LISTED -> "not listed in ${ProviderPackaging.PROVIDERS_META_DATA}"
+            ProviderPackaging.Status.SDK_MISSING -> "SDK is not packaged"
+            ProviderPackaging.Status.RECEIVERS_REMOVED -> "SDK is present but its receivers are not in the manifest"
+        }
+        if (reason != null) {
+            // Listed in the app's PROVIDERS meta-data but unusable is a setup error; otherwise it is expected.
+            if (packaging.listedExplicitly(kind)) {
+                Logger.w(TAG, "${kind.wire} is listed in ${ProviderPackaging.PROVIDERS_META_DATA} but not used: $reason")
+            } else {
+                Logger.i(TAG, "${kind.wire} is not used: $reason")
+            }
+            return null
+        }
+        val name = ProviderBundles.bundleClassName(kind)
+        val bundle = guard("create $name") { createBundle(name) }
+        if (bundle == null && kind == ProviderKind.ANDROID) {
+            // The last resort must always exist; it lives in this module, so it can be constructed directly.
+            Logger.e(TAG, "reflective creation of the android bundle failed; constructing it directly")
+            return AndroidProviderBundle(appContext)
+        }
+        return bundle
+    }
+
+    private fun androidBundleLocked(): ProviderBundle = checkNotNull(bundleLocked(ProviderKind.ANDROID))
+
+    private fun isUsable(bundle: ProviderBundle): Boolean =
+        guard("${bundle.javaClass.name}.isAvailable") { bundle.isAvailable() } == true
+
+    /** Runs [block]; any failure except a VM error (out of memory, stack overflow) is logged and yields null. */
+    private inline fun <T> guard(what: String, block: () -> T): T? =
+        try {
+            block()
+        } catch (e: VirtualMachineError) {
+            throw e
+        } catch (t: Throwable) {
+            Logger.w(TAG, "$what failed: ${t.javaClass.name}: ${t.message}", t)
+            null
+        }
+
+    private data class Selection(val kind: ProviderKind, val bundle: ProviderBundle)
+
+    companion object {
+        private const val TAG = "LT.ProviderFactory"
+
+        /** `Class.forName(name, false, loader)`: true if the class exists, without initializing it. */
+        fun reflectiveClassPresent(loader: ClassLoader?): (String) -> Boolean = { name ->
+            try {
+                Class.forName(name, false, loader ?: DefaultProviderFactory::class.java.classLoader)
+                true
+            } catch (e: ClassNotFoundException) {
+                false
+            } catch (e: LinkageError) {
+                false
+            }
+        }
+
+        /** Instantiates a [ProviderBundle] class through its public (Context) constructor, with the app context. */
+        fun reflectiveBundleCreator(context: Context): (String) -> ProviderBundle = { name ->
+            val appContext = context.applicationContext ?: context
+            val loader = appContext.classLoader ?: DefaultProviderFactory::class.java.classLoader
+            Class.forName(name, true, loader).getConstructor(Context::class.java).newInstance(appContext)
+                as ProviderBundle
+        }
+    }
+}

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

@@ -0,0 +1,135 @@
+package com.brickssoft.locationtracking.provider
+
+import android.content.ComponentName
+import android.content.Context
+import android.content.pm.ApplicationInfo
+import android.content.pm.PackageManager
+import android.os.Build
+import com.brickssoft.locationtracking.core.Logger
+import com.brickssoft.locationtracking.model.ProviderKind
+
+/**
+ * Whether the GMS or HMS backend may be used in this APK. ANDROID always may. GMS or HMS is packaged when:
+ * 1. the app's `<meta-data android:name="com.brickssoft.locationtracking.PROVIDERS">` ([PROVIDERS_META_DATA]) lists
+ *    it, or the app declares no such entry;
+ * 2. its SDK class is present; and
+ * 3. the receivers its activity and geofence results are delivered to are declared in the app's merged manifest.
+ *
+ * An app that publishes one APK per store declares the entry in each flavor's manifest (`gms` or `hms`) and removes
+ * the other provider's receivers with `tools:node="remove"` (README, "Separate Play and AppGallery APKs"). The other
+ * provider's SDK classes can still reach the APK through other libraries; the entry and the missing receivers both
+ * keep the plugin from using it.
+ *
+ * The entry's value is a comma-separated list of `gms`, `hms` and `android` (case and spaces are ignored); `android`
+ * alone means neither GMS nor HMS. Unknown names are logged and ignored. A value with no known name is logged as an
+ * error and the entry is ignored.
+ *
+ * A check that throws (anything except a VM error) reads as not packaged and is logged.
+ *
+ * @param classPresent whether a class can be loaded (see [DefaultProviderFactory.reflectiveClassPresent]).
+ * @param receiverDeclared whether a receiver class is declared in the merged manifest (see [receiverDeclaredIn]).
+ * @param providersMetaData the raw value of the [PROVIDERS_META_DATA] entry, or null if the app declares none (see
+ *   [providersMetaDataIn]).
+ */
+class ProviderPackaging(
+    private val classPresent: (String) -> Boolean,
+    private val receiverDeclared: (String) -> Boolean,
+    providersMetaData: () -> String? = { null },
+) {
+    enum class Status { PACKAGED, NOT_LISTED, SDK_MISSING, RECEIVERS_REMOVED }
+
+    /** The providers the app's entry lists, or null if there is no usable entry. Read once. */
+    private val listed: Set<ProviderKind>? by lazy {
+        val raw = passesOrNull("read meta-data $PROVIDERS_META_DATA") { providersMetaData() }
+        raw?.let(::parseProviders)
+    }
+
+    /** True if the app's [PROVIDERS_META_DATA] entry names [kind]; false without an entry. */
+    fun listedExplicitly(kind: ProviderKind): Boolean = listed?.contains(kind) == true
+
+    fun status(kind: ProviderKind): Status {
+        val sdkClass = ProviderBundles.sdkClassName(kind) ?: return Status.PACKAGED
+        listed?.let { if (kind !in it) return Status.NOT_LISTED }
+        if (!passes("probe $sdkClass") { classPresent(sdkClass) }) return Status.SDK_MISSING
+        val receivers = ProviderBundles.receiverClassNames(kind)
+        if (!receivers.all { passes("look up receiver $it") { receiverDeclared(it) } }) return Status.RECEIVERS_REMOVED
+        return Status.PACKAGED
+    }
+
+    fun isPackaged(kind: ProviderKind): Boolean = status(kind) == Status.PACKAGED
+
+    private fun parseProviders(raw: String): Set<ProviderKind>? {
+        val names = raw.split(',').map { it.trim().lowercase() }.filter { it.isNotEmpty() }
+        val kinds = names.mapNotNull { name ->
+            ProviderKind.fromWire(name) ?: null.also {
+                Logger.w(TAG, "$PROVIDERS_META_DATA: unknown provider '$name' ignored (use gms, hms or android)")
+            }
+        }.toSet()
+        if (kinds.isEmpty()) {
+            Logger.e(TAG, "$PROVIDERS_META_DATA='$raw' names no provider (use gms, hms or android); entry ignored")
+            return null
+        }
+        return kinds
+    }
+
+    private inline fun passes(what: String, block: () -> Boolean): Boolean = passesOrNull(what, block) ?: false
+
+    private inline fun <T> passesOrNull(what: String, block: () -> T): T? =
+        try {
+            block()
+        } catch (e: VirtualMachineError) {
+            throw e
+        } catch (t: Throwable) {
+            Logger.w(TAG, "$what failed: ${t.javaClass.name}: ${t.message}", t)
+            null
+        }
+
+    companion object {
+        private const val TAG = "LT.ProviderPackaging"
+
+        /**
+         * Name of the `<meta-data>` in the app's `<application>` that lists the providers the plugin may use:
+         * `<meta-data android:name="com.brickssoft.locationtracking.PROVIDERS" android:value="hms"/>`.
+         */
+        const val PROVIDERS_META_DATA = "com.brickssoft.locationtracking.PROVIDERS"
+
+        /** Flags of the receiver lookup: disabled receivers and both direct-boot states count as declared. */
+        const val RECEIVER_LOOKUP_FLAGS = PackageManager.MATCH_DISABLED_COMPONENTS or
+            PackageManager.MATCH_DIRECT_BOOT_AWARE or
+            PackageManager.MATCH_DIRECT_BOOT_UNAWARE
+
+        /**
+         * `PackageManager.getReceiverInfo` for a receiver of this app: true if the merged manifest declares it.
+         * [RECEIVER_LOOKUP_FLAGS] make the answer independent of whether the receiver is enabled and of whether the
+         * user has unlocked the phone since boot (before that, Android hides components that are not direct-boot
+         * aware, which the plugin's receivers are not).
+         */
+        fun receiverDeclaredIn(context: Context): (String) -> Boolean = { name ->
+            try {
+                @Suppress("DEPRECATION") // the ComponentInfoFlags overload needs API 33
+                context.packageManager.getReceiverInfo(ComponentName(context.packageName, name), RECEIVER_LOOKUP_FLAGS)
+                true
+            } catch (e: PackageManager.NameNotFoundException) {
+                false
+            }
+        }
+
+        /** The string value of the app's [PROVIDERS_META_DATA] entry, or null if it declares none. */
+        fun providersMetaDataIn(context: Context): () -> String? = {
+            applicationInfo(context).metaData?.getString(PROVIDERS_META_DATA)
+        }
+
+        private fun applicationInfo(context: Context): ApplicationInfo {
+            val pm = context.packageManager
+            return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+                pm.getApplicationInfo(
+                    context.packageName,
+                    PackageManager.ApplicationInfoFlags.of(PackageManager.GET_META_DATA.toLong()),
+                )
+            } else {
+                @Suppress("DEPRECATION")
+                pm.getApplicationInfo(context.packageName, PackageManager.GET_META_DATA)
+            }
+        }
+    }
+}

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

@@ -0,0 +1,25 @@
+package com.brickssoft.locationtracking.provider.android
+
+import com.brickssoft.locationtracking.core.Logger
+import com.brickssoft.locationtracking.model.ProviderKind
+import com.brickssoft.locationtracking.provider.ActivityBackend
+
+/**
+ * The platform has no activity recognition without GMS or HMS: [isSupported] is false and [start] always returns
+ * false, so motion detection relies on location distance (`stationaryRadius`) alone.
+ */
+class AndroidActivityBackend : ActivityBackend {
+    override val kind: ProviderKind = ProviderKind.ANDROID
+    override val isSupported: Boolean = false
+
+    override fun start(intervalMs: Long): Boolean {
+        Logger.d(TAG, "activity recognition is not supported by the android backend")
+        return false
+    }
+
+    override fun stop() = Unit
+
+    private companion object {
+        const val TAG = "LT.AndroidActivity"
+    }
+}

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

@@ -0,0 +1,181 @@
+package com.brickssoft.locationtracking.provider.android
+
+import android.annotation.SuppressLint
+import android.app.PendingIntent
+import android.content.Context
+import android.content.Intent
+import android.content.SharedPreferences
+import android.location.LocationManager
+import android.net.Uri
+import com.brickssoft.locationtracking.core.Constants
+import com.brickssoft.locationtracking.core.ErrorCode
+import com.brickssoft.locationtracking.core.Logger
+import com.brickssoft.locationtracking.core.TrackingException
+import com.brickssoft.locationtracking.model.ProviderKind
+import com.brickssoft.locationtracking.provider.GeofenceBackend
+import com.brickssoft.locationtracking.provider.OsGeofence
+
+/** Seam over the platform proximity-alert API (`LocationManager.addProximityAlert` / `removeProximityAlert`). */
+interface ProximityAlerts {
+    /** Registers a circular alert that never expires. May throw [SecurityException] without fine location. */
+    fun add(latitude: Double, longitude: Double, radius: Float, intent: PendingIntent)
+
+    fun remove(intent: PendingIntent)
+}
+
+/** [ProximityAlerts] backed by the platform [LocationManager]. */
+internal class LocationManagerProximityAlerts(context: Context) : ProximityAlerts {
+    private val lm = context.getSystemService(Context.LOCATION_SERVICE) as? LocationManager
+
+    @SuppressLint("MissingPermission")
+    override fun add(latitude: Double, longitude: Double, radius: Float, intent: PendingIntent) {
+        val manager = lm ?: throw TrackingException(ErrorCode.UNAVAILABLE, "LocationManager is unavailable")
+        manager.addProximityAlert(latitude, longitude, radius, NO_EXPIRATION, intent)
+    }
+
+    override fun remove(intent: PendingIntent) {
+        lm?.removeProximityAlert(intent)
+    }
+
+    private companion object {
+        const val NO_EXPIRATION = -1L
+    }
+}
+
+/**
+ * [GeofenceBackend] over `LocationManager` proximity alerts.
+ *
+ * - One mutable broadcast PendingIntent per region: explicit [AndroidGeofenceReceiver] component, action
+ *   [Constants.ACTION_GEOFENCE], data URI [Constants.geofenceUri] and request code [Constants.RC_ANDROID_PROXIMITY].
+ *   The region's `onEntry`/`onExit` flags travel as extras; the receiver drops unwanted transitions.
+ * - No dwell ([supportsDwell] is false). The platform always reports ENTER when the device is already inside, so
+ *   `initialTriggerEntry` is left to the GeofenceManager.
+ * - Registered ids are kept in memory and mirrored to SharedPreferences, so [removeAll] also clears alerts that were
+ *   registered before a process restart. [remove] re-creates each PendingIntent from its id.
+ * - [add] validates every region before touching the OS ([ErrorCode.INVALID_ARGUMENT]). If the platform then fails,
+ *   the regions that call introduced are removed again; a region that was already registered keeps its new circle if
+ *   it was re-added, or is dropped if re-adding it failed (its previous circle is already gone).
+ * - Calls run on the caller's thread: a few binder calls per region, no disk I/O after the first preferences load
+ *   (started in the background at construction).
+ */
+class AndroidGeofenceBackend(
+    context: Context,
+    private val alerts: ProximityAlerts = LocationManagerProximityAlerts(context),
+) : GeofenceBackend {
+    private val appContext: Context = context.applicationContext ?: context
+    override val kind: ProviderKind = ProviderKind.ANDROID
+    override val supportsDwell: Boolean = false
+
+    private val lock = Any()
+    private val prefs: SharedPreferences = appContext.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+    private var ids: MutableSet<String>? = null
+
+    /** Ids currently registered with the OS (as far as this backend knows). */
+    internal val registeredIds: Set<String> get() = synchronized(lock) { registered().toSet() }
+
+    override suspend fun add(regions: List<OsGeofence>) {
+        for (region in regions) {
+            invalidReason(region)?.let {
+                throw TrackingException(ErrorCode.INVALID_ARGUMENT, "Invalid geofence '${region.id}': $it")
+            }
+        }
+        synchronized(lock) {
+            val before = registered().toSet()
+            val added = ArrayList<String>(regions.size)
+            for (region in regions) {
+                val intent = pendingIntentFor(region)
+                try {
+                    // The platform keys alerts by (PendingIntent, circle): drop the previous circle of this id first.
+                    alerts.remove(intent)
+                    alerts.add(region.latitude, region.longitude, region.radius, intent)
+                } catch (e: Exception) {
+                    (added.filter { it !in before } + region.id).forEach(::removeLocked)
+                    persist()
+                    throw toTrackingException(e)
+                }
+                added += region.id
+                registered() += region.id
+            }
+            persist()
+            if (regions.isNotEmpty()) Logger.d(TAG, "added ${regions.size} proximity alert(s)")
+        }
+    }
+
+    override suspend fun remove(ids: List<String>) {
+        synchronized(lock) {
+            ids.forEach(::removeLocked)
+            persist()
+        }
+    }
+
+    override suspend fun removeAll() {
+        synchronized(lock) {
+            registered().toList().forEach(::removeLocked)
+            persist()
+        }
+    }
+
+    private fun removeLocked(id: String) {
+        existingPendingIntent(id)?.let { intent ->
+            try {
+                alerts.remove(intent)
+            } catch (e: Exception) {
+                Logger.w(TAG, "removeProximityAlert failed for $id", e)
+            }
+            intent.cancel()
+        }
+        registered() -= id
+    }
+
+    private fun registered(): MutableSet<String> =
+        ids ?: HashSet(prefs.getStringSet(KEY_IDS, null).orEmpty()).also { ids = it }
+
+    private fun persist() {
+        prefs.edit().putStringSet(KEY_IDS, HashSet(registered())).apply()
+    }
+
+    private fun pendingIntentFor(region: OsGeofence): PendingIntent {
+        val intent = baseIntent(region.id)
+            .putExtra(EXTRA_NOTIFY_ENTRY, region.onEntry)
+            .putExtra(EXTRA_NOTIFY_EXIT, region.onExit)
+        return PendingIntent.getBroadcast(appContext, Constants.RC_ANDROID_PROXIMITY, intent, Constants.piMutable())
+    }
+
+    /** The PendingIntent registered for [id], if any; same identity (intent, request code, mutability) as created. */
+    private fun existingPendingIntent(id: String): PendingIntent? {
+        val flags = PendingIntent.FLAG_NO_CREATE or (Constants.piMutable() and PendingIntent.FLAG_UPDATE_CURRENT.inv())
+        return PendingIntent.getBroadcast(appContext, Constants.RC_ANDROID_PROXIMITY, baseIntent(id), flags)
+    }
+
+    private fun baseIntent(id: String): Intent =
+        Intent(appContext, AndroidGeofenceReceiver::class.java)
+            .setAction(Constants.ACTION_GEOFENCE)
+            .setData(Uri.parse(Constants.geofenceUri(id)))
+
+    private fun invalidReason(region: OsGeofence): String? = when {
+        region.id.isEmpty() -> "empty identifier"
+        region.latitude !in -90.0..90.0 -> "latitude ${region.latitude} out of range"
+        region.longitude !in -180.0..180.0 -> "longitude ${region.longitude} out of range"
+        !region.radius.isFinite() || region.radius <= 0f -> "radius ${region.radius} must be > 0"
+        else -> null
+    }
+
+    private fun toTrackingException(e: Exception): TrackingException = when (e) {
+        is TrackingException -> e
+        is SecurityException ->
+            TrackingException(ErrorCode.PERMISSION_DENIED, "Proximity alerts need fine location permission", e)
+        is IllegalArgumentException ->
+            TrackingException(ErrorCode.INVALID_ARGUMENT, "Invalid geofence: ${e.message}", e)
+        else -> TrackingException(ErrorCode.UNAVAILABLE, "Cannot add proximity alert: ${e.message}", e)
+    }
+
+    internal companion object {
+        private const val TAG = "LT.AndroidGeofence"
+        private const val PREFS_NAME = "location_tracking_android_geofences"
+        private const val KEY_IDS = "registered_ids"
+
+        /** Boolean extras of the proximity PendingIntent: whether ENTER / EXIT should be delivered (default true). */
+        const val EXTRA_NOTIFY_ENTRY = "com.brickssoft.locationtracking.provider.android.NOTIFY_ENTRY"
+        const val EXTRA_NOTIFY_EXIT = "com.brickssoft.locationtracking.provider.android.NOTIFY_EXIT"
+    }
+}

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

@@ -0,0 +1,115 @@
+package com.brickssoft.locationtracking.provider.android
+
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import android.location.LocationManager
+import android.net.Uri
+import com.brickssoft.locationtracking.core.Clock
+import com.brickssoft.locationtracking.core.Components
+import com.brickssoft.locationtracking.core.Constants
+import com.brickssoft.locationtracking.core.Logger
+import com.brickssoft.locationtracking.model.GeofenceAction
+import com.brickssoft.locationtracking.model.TrackedLocation
+import com.brickssoft.locationtracking.provider.GeofenceTransitionSink
+import com.brickssoft.locationtracking.provider.OsGeofenceTransition
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.launch
+import kotlin.coroutines.cancellation.CancellationException
+
+/**
+ * Delivers `LocationManager` proximity alerts (see [AndroidGeofenceBackend]) to the GeofenceManager.
+ *
+ * The id comes from the data URI `lt-geofence://<id>` and the action from [LocationManager.KEY_PROXIMITY_ENTERING].
+ * The alert carries no fix, so the transition gets the freshest last known location if it is at most
+ * [MAX_TRIGGER_FIX_AGE_MS] old, else null.
+ */
+class AndroidGeofenceReceiver : BroadcastReceiver() {
+    override fun onReceive(context: Context, intent: Intent) {
+        val transition = parse(intent) ?: return
+        val components = Components.get(context)
+        val sink = components.geofences
+        val pending = goAsync()
+        deliver(transition, components.scope, sink, { recentLastKnown(components.context, components.clock) }) {
+            pending.finish()
+        }
+    }
+
+    internal companion object {
+        private const val TAG = "LT.AndroidGeofenceRx"
+
+        /** A last known fix older than this is not attached to a transition. */
+        const val MAX_TRIGGER_FIX_AGE_MS = 2 * 60_000L
+
+        /**
+         * The transition described by a proximity-alert [intent] (location = null), or null if the intent is not one
+         * of ours or its action was not requested for the region.
+         */
+        fun parse(intent: Intent): OsGeofenceTransition? {
+            val id = idFrom(intent.data) ?: return null
+            if (!intent.hasExtra(LocationManager.KEY_PROXIMITY_ENTERING)) return null
+            val entering = intent.getBooleanExtra(LocationManager.KEY_PROXIMITY_ENTERING, false)
+            val wantedExtra = if (entering) {
+                AndroidGeofenceBackend.EXTRA_NOTIFY_ENTRY
+            } else {
+                AndroidGeofenceBackend.EXTRA_NOTIFY_EXIT
+            }
+            if (!intent.getBooleanExtra(wantedExtra, true)) return null
+            return OsGeofenceTransition(id, if (entering) GeofenceAction.ENTER else GeofenceAction.EXIT, null)
+        }
+
+        /** Decodes `<id>` of [Constants.geofenceUri]. */
+        fun idFrom(uri: Uri?): String? {
+            if (uri == null || uri.scheme != Constants.GEOFENCE_URI_SCHEME) return null
+            val encoded = uri.encodedSchemeSpecificPart?.removePrefix("//") ?: return null
+            return Uri.decode(encoded).takeIf { it.isNotEmpty() }
+        }
+
+        /**
+         * Adds the location from [locate] (null if it fails) and hands [transition] to [sink] on [scope].
+         * [finish] runs exactly once when the job completes, even if [scope] is already cancelled.
+         */
+        fun deliver(
+            transition: OsGeofenceTransition,
+            scope: CoroutineScope,
+            sink: GeofenceTransitionSink,
+            locate: () -> TrackedLocation?,
+            finish: () -> Unit,
+        ): Job {
+            val job = scope.launch {
+                try {
+                    val location = try {
+                        locate()
+                    } catch (e: Exception) {
+                        Logger.w(TAG, "no last known location for geofence ${transition.id}", e)
+                        null
+                    }
+                    sink.onGeofenceTransitions(listOf(transition.copy(location = location)))
+                } catch (e: CancellationException) {
+                    throw e
+                } catch (e: Exception) {
+                    Logger.e(TAG, "failed to deliver ${transition.action} of geofence ${transition.id}", e)
+                }
+            }
+            job.invokeOnCompletion { finish() }
+            return job
+        }
+
+        /** True if [fix] is at most [MAX_TRIGGER_FIX_AGE_MS] old (elapsed-realtime clock when the fix carries it). */
+        fun isRecent(fix: TrackedLocation, clock: Clock): Boolean {
+            val ageMs = if (fix.elapsedRealtimeNanos > 0) {
+                clock.elapsedRealtime() - fix.elapsedRealtimeNanos / 1_000_000
+            } else {
+                clock.now() - fix.time
+            }
+            return ageMs <= MAX_TRIGGER_FIX_AGE_MS
+        }
+
+        private fun recentLastKnown(context: Context, clock: Clock): TrackedLocation? {
+            val lm = context.getSystemService(Context.LOCATION_SERVICE) as? LocationManager ?: return null
+            val fix = LocationProviders.freshestLastKnown(lm)?.let(TrackedLocation::from) ?: return null
+            return fix.takeIf { isRecent(it, clock) }
+        }
+    }
+}