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

package/android/build.gradle

@@ -0,0 +1,106 @@
+ext {
+    junitVersion = project.hasProperty('junitVersion') ? rootProject.ext.junitVersion : '4.13.2'
+    androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.7.1'
+    androidxCoreKTXVersion = project.hasProperty('androidxCoreKTXVersion') ? rootProject.ext.androidxCoreKTXVersion : '1.17.0'
+    playServicesLocationVersion = project.hasProperty('playServicesLocationVersion') ? rootProject.ext.playServicesLocationVersion : '21.3.0'
+    hmsLocationVersion = project.hasProperty('hmsLocationVersion') ? rootProject.ext.hmsLocationVersion : '6.16.0.302'
+    kotlinxCoroutinesVersion = project.hasProperty('kotlinxCoroutinesVersion') ? rootProject.ext.kotlinxCoroutinesVersion : '1.10.2'
+    okhttpVersion = '4.12.0'
+}
+
+buildscript {
+    ext.kotlin_version = project.hasProperty('kotlin_version') ? rootProject.ext.kotlin_version : '2.2.20'
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath 'com.android.tools.build:gradle:8.13.0'
+        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
+    }
+}
+
+apply plugin: 'com.android.library'
+if (project.extensions.findByName('kotlin') == null) {
+    apply plugin: 'kotlin-android'
+}
+
+// Which location SDKs are packaged into the app: -PlocationTracking.providers=gms,hms (default: gms).
+// The plugin always compiles against both (compileOnly) and selects one at runtime via reflection.
+// An app with Play and AppGallery product flavors sets `none` and adds the SDKs per flavor itself (README).
+def ltProviders = (project.findProperty('locationTracking.providers') ?: 'gms').toString()
+    .split(',').collect { it.trim().toLowerCase() }.findAll { it && it != 'none' }.toSet()
+
+android {
+    namespace = 'com.brickssoft.locationtracking'
+    compileSdk = project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 36
+    resourcePrefix 'lt_'
+    defaultConfig {
+        minSdkVersion project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 24
+        targetSdkVersion project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 36
+        consumerProguardFiles 'consumer-rules.pro'
+        buildConfigField 'String', 'PLUGIN_VERSION', '"8.0.0"'
+    }
+    buildFeatures {
+        buildConfig = true
+    }
+    buildTypes {
+        release {
+            minifyEnabled false
+        }
+    }
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_21
+        targetCompatibility JavaVersion.VERSION_21
+    }
+    lint {
+        abortOnError = false
+    }
+    testOptions {
+        unitTests {
+            includeAndroidResources = true
+            returnDefaultValues = true
+            all {
+                maxHeapSize = '1024m'
+                maxParallelForks = 1
+                jvmArgs '-XX:+UseSerialGC', '-XX:+EnableDynamicAgentLoading'
+                testLogging {
+                    events 'failed'
+                    exceptionFormat 'full'
+                }
+            }
+        }
+    }
+}
+
+kotlin {
+    jvmToolchain(21)
+}
+
+repositories {
+    google()
+    mavenCentral()
+    maven { url = 'https://developer.huawei.com/repo/' }
+}
+
+dependencies {
+    implementation project(':capacitor-android')
+    implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
+    implementation "androidx.core:core-ktx:$androidxCoreKTXVersion"
+    implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:$kotlinxCoroutinesVersion"
+    implementation "com.squareup.okhttp3:okhttp:$okhttpVersion"
+
+    compileOnly "com.google.android.gms:play-services-location:$playServicesLocationVersion"
+    compileOnly "com.huawei.hms:location:$hmsLocationVersion"
+    if (ltProviders.contains('gms')) implementation "com.google.android.gms:play-services-location:$playServicesLocationVersion"
+    if (ltProviders.contains('hms')) implementation "com.huawei.hms:location:$hmsLocationVersion"
+
+    testImplementation "junit:junit:$junitVersion"
+    testImplementation 'org.robolectric:robolectric:4.16.1'
+    testImplementation 'androidx.test:core-ktx:1.7.0'
+    testImplementation 'io.mockk:mockk:1.14.6'
+    testImplementation "org.jetbrains.kotlinx:kotlinx-coroutines-test:$kotlinxCoroutinesVersion"
+    testImplementation "com.squareup.okhttp3:mockwebserver:$okhttpVersion"
+    testImplementation "com.google.android.gms:play-services-location:$playServicesLocationVersion"
+    testImplementation "com.huawei.hms:location:$hmsLocationVersion"
+}

package/android/consumer-rules.pro

@@ -0,0 +1,42 @@
+# Consumer ProGuard/R8 rules for @bricks-soft/capacitor-location-tracking.
+
+# The plugin compiles against both location SDKs (compileOnly); an app may package only one of them.
+-dontwarn com.google.android.gms.**
+-dontwarn com.huawei.**
+
+# Provider bundles are instantiated reflectively by DefaultProviderFactory.
+-keep class com.brickssoft.locationtracking.provider.**.*ProviderBundle {
+    public <init>(android.content.Context);
+}
+
+# DefaultProviderFactory probes for the packaged SDKs by class name (Class.forName). Keep those names, or a
+# minified release app would never detect Google Play services and fall back to the Android backend.
+-keepnames class com.google.android.gms.location.LocationServices
+-keepnames class com.google.android.gms.common.GoogleApiAvailability
+-keepnames class com.huawei.hms.location.LocationServices
+
+# Companion native API (docs/native-api.md): companion plugins and app code call these classes and interfaces. Keep
+# every public member of the package, and the error type its callbacks deliver (TrackingException with an ErrorCode),
+# so a companion library that is shrunk separately still finds them.
+-keep class com.brickssoft.locationtracking.api.** { public *; }
+-keep class com.brickssoft.locationtracking.core.TrackingException { public *; }
+-keep class com.brickssoft.locationtracking.core.ErrorCode { public *; }
+
+# Listener classes named in <meta-data android:name="com.brickssoft.locationtracking.LISTENER[.suffix]"> are created
+# by reflection (Class.forName with the manifest name, then the public no-arg constructor). Keep the class names,
+# that constructor and the listener methods of every implementation.
+-keep class * implements com.brickssoft.locationtracking.api.LocationTrackingListener {
+    public <init>();
+    public void onRecord(android.content.Context, org.json.JSONObject);
+    public void onEvent(android.content.Context, java.lang.String, org.json.JSONObject);
+}
+
+# Huawei HMS recommended keeps.
+-keep class com.huawei.hms.** { *; }
+-keep class com.huawei.hianalytics.** { *; }
+-keep class com.huawei.updatesdk.** { *; }
+-keepattributes *Annotation*
+-keepattributes Exceptions
+-keepattributes InnerClasses,EnclosingMethod
+-keepattributes Signature
+-keepattributes SourceFile,LineNumberTable

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,52 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+  <uses-permission android:name="android.permission.INTERNET"/>
+  <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
+  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
+  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
+  <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION"/>
+  <uses-permission android:name="android.permission.ACTIVITY_RECOGNITION"/>
+  <uses-permission android:name="com.google.android.gms.permission.ACTIVITY_RECOGNITION" android:maxSdkVersion="28"/>
+  <uses-permission android:name="com.huawei.hms.permission.ACTIVITY_RECOGNITION" android:maxSdkVersion="28"/>
+  <uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>
+  <uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION"/>
+  <uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>
+  <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>
+  <uses-permission android:name="android.permission.WAKE_LOCK"/>
+  <!-- intentionally NOT declared: SCHEDULE_EXACT_ALARM, USE_EXACT_ALARM, REQUEST_IGNORE_BATTERY_OPTIMIZATIONS -->
+  <uses-feature android:name="android.hardware.location.gps" android:required="false"/>
+  <queries>
+    <intent><action android:name="android.intent.action.SENDTO"/><data android:scheme="mailto"/></intent>
+    <package android:name="com.huawei.systemmanager"/><package android:name="com.hihonor.systemmanager"/>
+    <package android:name="com.miui.securitycenter"/><package android:name="com.miui.powerkeeper"/>
+    <package android:name="com.coloros.safecenter"/><package android:name="com.oppo.safe"/><package android:name="com.coloros.oppoguardelf"/>
+    <package android:name="com.iqoo.secure"/><package android:name="com.vivo.permissionmanager"/>
+    <package android:name="com.samsung.android.lool"/><package android:name="com.samsung.android.sm"/>
+    <package android:name="com.oneplus.security"/><package android:name="com.asus.mobilemanager"/>
+    <package android:name="com.letv.android.letvsafe"/><package android:name="com.htc.pitroad"/>
+    <package android:name="com.meizu.safe"/><package android:name="com.evenwell.powersaving.g3"/>
+  </queries>
+  <application>
+    <service android:name="com.brickssoft.locationtracking.service.LocationTrackingService"
+        android:exported="false" android:foregroundServiceType="location" android:stopWithTask="false"/>
+    <receiver android:name="com.brickssoft.locationtracking.service.BootReceiver" android:exported="true">
+      <intent-filter>
+        <action android:name="android.intent.action.BOOT_COMPLETED"/>
+        <action android:name="android.intent.action.MY_PACKAGE_REPLACED"/>
+        <action android:name="android.intent.action.QUICKBOOT_POWERON"/>
+        <action android:name="com.htc.intent.action.QUICKBOOT_POWERON"/>
+      </intent-filter>
+    </receiver>
+    <receiver android:name="com.brickssoft.locationtracking.heartbeat.HeartbeatAlarmReceiver" android:exported="false"/>
+    <receiver android:name="com.brickssoft.locationtracking.service.NotificationActionReceiver" android:exported="false"/>
+    <receiver android:name="com.brickssoft.locationtracking.provider.gms.GmsActivityReceiver" android:exported="false"/>
+    <receiver android:name="com.brickssoft.locationtracking.provider.gms.GmsGeofenceReceiver" android:exported="false"/>
+    <receiver android:name="com.brickssoft.locationtracking.provider.hms.HmsActivityReceiver" android:exported="false"/>
+    <receiver android:name="com.brickssoft.locationtracking.provider.hms.HmsGeofenceReceiver" android:exported="false"/>
+    <receiver android:name="com.brickssoft.locationtracking.provider.android.AndroidGeofenceReceiver" android:exported="false"/>
+    <provider android:name="com.brickssoft.locationtracking.logging.LogFileProvider"
+        android:authorities="${applicationId}.locationtracking.logs" android:exported="false" android:grantUriPermissions="true">
+      <meta-data android:name="android.support.FILE_PROVIDER_PATHS" android:resource="@xml/lt_file_paths"/>
+    </provider>
+  </application>
+</manifest>

package/android/src/main/java/com/brickssoft/locationtracking/LocationTrackingPlugin.kt

@@ -0,0 +1,431 @@
+package com.brickssoft.locationtracking
+
+import android.Manifest
+import com.brickssoft.locationtracking.bridge.CallResponder
+import com.brickssoft.locationtracking.bridge.CallWatchTarget
+import com.brickssoft.locationtracking.bridge.ComponentServices
+import com.brickssoft.locationtracking.bridge.PermissionRequestLauncher
+import com.brickssoft.locationtracking.bridge.PluginHandlers
+import com.brickssoft.locationtracking.bridge.PluginPermissionHost
+import com.brickssoft.locationtracking.core.Components
+import com.brickssoft.locationtracking.core.Logger
+import com.brickssoft.locationtracking.core.Subscription
+import com.brickssoft.locationtracking.permission.CurrentActivityTracker
+import com.getcapacitor.JSObject
+import com.getcapacitor.Plugin
+import com.getcapacitor.PluginCall
+import com.getcapacitor.PluginMethod
+import com.getcapacitor.annotation.CapacitorPlugin
+import com.getcapacitor.annotation.Permission
+import com.getcapacitor.annotation.PermissionCallback
+import kotlinx.coroutines.CancellationException
+import kotlinx.coroutines.CoroutineStart
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.isActive
+import kotlinx.coroutines.launch
+import org.json.JSONObject
+import java.util.concurrent.ConcurrentHashMap
+
+/**
+ * Capacitor bridge for `LocationTracking`. A thin adapter: every method runs the matching [PluginHandlers] function
+ * on `Components.scope` and settles the call (TrackingException -> `reject(message, code)`, anything else ->
+ * INTERNAL). Tracking events from the EventBus are forwarded to JS listeners.
+ */
+@CapacitorPlugin(
+    name = "LocationTracking",
+    permissions = [
+        Permission(
+            strings = [Manifest.permission.ACCESS_COARSE_LOCATION, Manifest.permission.ACCESS_FINE_LOCATION],
+            alias = "location",
+        ),
+        Permission(strings = [Manifest.permission.ACCESS_BACKGROUND_LOCATION], alias = "backgroundLocation"),
+        Permission(strings = [Manifest.permission.ACTIVITY_RECOGNITION], alias = "activityRecognition"),
+        Permission(strings = [Manifest.permission.POST_NOTIFICATIONS], alias = "notifications"),
+    ],
+)
+class LocationTrackingPlugin : Plugin() {
+    private lateinit var components: Components
+    private lateinit var handlers: PluginHandlers
+
+    @Volatile
+    private var eventSubscription: Subscription? = null
+
+    /** `onDone` of the in-flight permission request of each call, by callback id. */
+    private val pendingPermissionRequests = ConcurrentHashMap<String, () -> Unit>()
+
+    /** Running `requestPermissions` coroutines by callback id, cancelled in [handleOnDestroy]. */
+    private val permissionJobs = ConcurrentHashMap<String, Job>()
+
+    @Volatile
+    private var destroyed = false
+
+    override fun load() {
+        components = Components.get(context)
+        // The Activity is already created when plugins load, so the permission manager's lifecycle tracker would
+        // only learn about it at its next lifecycle event; seed it for rationale checks in checkPermissions().
+        activity?.let { CurrentActivityTracker.attach(context).remember(it) }
+        handlers = PluginHandlers(
+            ComponentServices(components),
+            activityProvider = { PluginPermissionHost.usableActivity(this) },
+        )
+        eventSubscription = handlers.forwardEvents { name, payload -> notifyOnBridgeThread(name, payload) }
+    }
+
+    override fun handleOnResume() {
+        super.handleOnResume()
+        if (!::handlers.isInitialized) return
+        components.scope.launch { handlers.onResume() }
+    }
+
+    /**
+     * Stops event forwarding, releases every watch and ends in-flight permission requests: their calls are
+     * abandoned (the WebView is going away), but each pending `onDone` still runs so the PermissionManager's request
+     * completes; later steps of it complete at once because the host has no usable activity and no launcher.
+     */
+    override fun handleOnDestroy() {
+        destroyed = true
+        eventSubscription?.cancel()
+        eventSubscription = null
+        if (::handlers.isInitialized) handlers.releaseAllWatches()
+        for (id in pendingPermissionRequests.keys.toList()) {
+            val onDone = pendingPermissionRequests.remove(id) ?: continue
+            try {
+                onDone()
+            } catch (t: Throwable) {
+                Logger.w(TAG, "completing permission request $id on destroy failed", t)
+            }
+        }
+        permissionJobs.values.forEach { it.cancel() }
+        permissionJobs.clear()
+        super.handleOnDestroy()
+    }
+
+    // ---- lifecycle and config
+
+    @PluginMethod
+    fun ready(call: PluginCall) {
+        respond(call) { handlers.ready(it) }
+    }
+
+    @PluginMethod
+    fun setConfig(call: PluginCall) {
+        respond(call) { handlers.setConfig(it) }
+    }
+
+    @PluginMethod
+    fun reset(call: PluginCall) {
+        respond(call) { handlers.reset(it) }
+    }
+
+    @PluginMethod
+    fun getState(call: PluginCall) {
+        respond(call) { handlers.getState() }
+    }
+
+    @PluginMethod
+    fun start(call: PluginCall) {
+        respond(call) { handlers.start() }
+    }
+
+    @PluginMethod
+    fun startGeofences(call: PluginCall) {
+        respond(call) { handlers.startGeofences() }
+    }
+
+    @PluginMethod
+    fun stop(call: PluginCall) {
+        respond(call) { handlers.stop() }
+    }
+
+    @PluginMethod
+    fun changePace(call: PluginCall) {
+        respond(call) { handlers.changePace(it) }
+    }
+
+    // ---- positions
+
+    @PluginMethod
+    fun getCurrentPosition(call: PluginCall) {
+        respond(call) { handlers.getCurrentPosition(it) }
+    }
+
+    /**
+     * Kept alive until `clearWatch`: the bridge saves the call and every location/error invokes the JS callback.
+     * Kept alive before registering so an early delivery cannot release the call.
+     */
+    @PluginMethod(returnType = PluginMethod.RETURN_CALLBACK)
+    fun watchPosition(call: PluginCall) {
+        call.setKeepAlive(true)
+        try {
+            handlers.watchPosition(call.callbackId, optionsOf(call), CallWatchTarget(call) { bridge })
+        } catch (t: Throwable) { // also Errors (e.g. NoClassDefFoundError of a missing SDK): never crash the bridge
+            call.setKeepAlive(false)
+            CallResponder.reject(call, t)
+        }
+    }
+
+    @PluginMethod
+    fun clearWatch(call: PluginCall) {
+        respond(call) { handlers.clearWatch(it) }
+    }
+
+    // ---- odometer
+
+    @PluginMethod
+    fun getOdometer(call: PluginCall) {
+        respond(call) { handlers.getOdometer() }
+    }
+
+    @PluginMethod
+    fun setOdometer(call: PluginCall) {
+        respond(call) { handlers.setOdometer(it) }
+    }
+
+    @PluginMethod
+    fun resetOdometer(call: PluginCall) {
+        respond(call) { handlers.resetOdometer() }
+    }
+
+    // ---- records
+
+    @PluginMethod
+    fun getLocations(call: PluginCall) {
+        respond(call) { handlers.getLocations(it) }
+    }
+
+    @PluginMethod
+    fun getCount(call: PluginCall) {
+        respond(call) { handlers.getCount() }
+    }
+
+    @PluginMethod
+    fun insertLocation(call: PluginCall) {
+        respond(call) { handlers.insertLocation(it) }
+    }
+
+    @PluginMethod
+    fun destroyLocations(call: PluginCall) {
+        respond(call) { handlers.destroyLocations() }
+    }
+
+    @PluginMethod
+    fun destroyLocation(call: PluginCall) {
+        respond(call) { handlers.destroyLocation(it) }
+    }
+
+    @PluginMethod
+    fun sync(call: PluginCall) {
+        respond(call) { handlers.sync() }
+    }
+
+    // ---- geofences
+
+    @PluginMethod
+    fun addGeofence(call: PluginCall) {
+        respond(call) { handlers.addGeofence(it) }
+    }
+
+    @PluginMethod
+    fun addGeofences(call: PluginCall) {
+        respond(call) { handlers.addGeofences(it) }
+    }
+
+    @PluginMethod
+    fun removeGeofence(call: PluginCall) {
+        respond(call) { handlers.removeGeofence(it) }
+    }
+
+    @PluginMethod
+    fun removeGeofences(call: PluginCall) {
+        respond(call) { handlers.removeGeofences(it) }
+    }
+
+    @PluginMethod
+    fun getGeofences(call: PluginCall) {
+        respond(call) { handlers.getGeofences() }
+    }
+
+    @PluginMethod
+    fun getGeofence(call: PluginCall) {
+        respond(call) { handlers.getGeofence(it) }
+    }
+
+    @PluginMethod
+    fun geofenceExists(call: PluginCall) {
+        respond(call) { handlers.geofenceExists(it) }
+    }
+
+    // ---- heartbeat and device
+
+    @PluginMethod
+    fun getHeartbeatStatus(call: PluginCall) {
+        respond(call) { handlers.getHeartbeatStatus() }
+    }
+
+    @PluginMethod
+    fun getProviderState(call: PluginCall) {
+        respond(call) { handlers.getProviderState() }
+    }
+
+    @PluginMethod
+    fun isPowerSaveMode(call: PluginCall) {
+        respond(call) { handlers.isPowerSaveMode() }
+    }
+
+    @PluginMethod
+    fun getBatteryOptimizationStatus(call: PluginCall) {
+        respond(call) { handlers.getBatteryOptimizationStatus() }
+    }
+
+    @PluginMethod
+    fun openBatteryOptimizationSettings(call: PluginCall) {
+        respond(call) { handlers.openBatteryOptimizationSettings() }
+    }
+
+    @PluginMethod
+    fun getPowerManagerInfo(call: PluginCall) {
+        respond(call) { handlers.getPowerManagerInfo() }
+    }
+
+    @PluginMethod
+    fun openPowerManagerSettings(call: PluginCall) {
+        respond(call) { handlers.openPowerManagerSettings() }
+    }
+
+    @PluginMethod
+    fun openLocationSettings(call: PluginCall) {
+        respond(call) { handlers.openLocationSettings() }
+    }
+
+    @PluginMethod
+    fun openAppSettings(call: PluginCall) {
+        respond(call) { handlers.openAppSettings() }
+    }
+
+    @PluginMethod
+    fun getDeviceInfo(call: PluginCall) {
+        respond(call) { handlers.getDeviceInfo() }
+    }
+
+    @PluginMethod
+    fun getSensors(call: PluginCall) {
+        respond(call) { handlers.getSensors() }
+    }
+
+    // ---- permissions
+
+    @PluginMethod
+    override fun checkPermissions(call: PluginCall) {
+        respond(call) { handlers.checkPermissions() }
+    }
+
+    @PluginMethod
+    override fun requestPermissions(call: PluginCall) {
+        val id = call.callbackId
+        val host = PluginPermissionHost(
+            this,
+            launcher = PermissionRequestLauncher { aliases, onDone -> launchPermissionRequest(call, aliases, onDone) },
+        )
+        val job = respond(call, CoroutineStart.LAZY) { handlers.requestPermissions(it, host) }
+        permissionJobs[id] = job
+        job.invokeOnCompletion {
+            permissionJobs.remove(id, job)
+            pendingPermissionRequests.remove(id)
+        }
+        job.start()
+    }
+
+    /** Main thread (called by the PermissionManager through [PluginPermissionHost]). */
+    private fun launchPermissionRequest(call: PluginCall, aliases: List<String>, onDone: () -> Unit) {
+        if (destroyed) {
+            onDone()
+            return
+        }
+        val id = call.callbackId
+        pendingPermissionRequests[id] = onDone
+        try {
+            requestPermissionForAliases(aliases.toTypedArray(), call, PERMISSION_CALLBACK)
+        } catch (e: Exception) {
+            pendingPermissionRequests.remove(id)
+            throw e
+        }
+    }
+
+    /** Resolved by name ([PERMISSION_CALLBACK]) through reflection by Capacitor; main thread. */
+    @Suppress("unused")
+    @PermissionCallback
+    private fun onPermissionRequestResult(call: PluginCall?) {
+        val id = call?.callbackId ?: return
+        val onDone = pendingPermissionRequests.remove(id) ?: return
+        onDone()
+    }
+
+    // ---- log
+
+    @PluginMethod
+    fun log(call: PluginCall) {
+        respond(call) { handlers.log(it) }
+    }
+
+    @PluginMethod
+    fun getLog(call: PluginCall) {
+        respond(call) { handlers.getLog(it) }
+    }
+
+    @PluginMethod
+    fun destroyLog(call: PluginCall) {
+        respond(call) { handlers.destroyLog() }
+    }
+
+    @PluginMethod
+    fun uploadLog(call: PluginCall) {
+        respond(call) { handlers.uploadLog(it) }
+    }
+
+    @PluginMethod
+    fun emailLog(call: PluginCall) {
+        respond(call) { handlers.emailLog(it) }
+    }
+
+    // ---- plumbing
+
+    /** Runs [block] on `Components.scope` and settles [call] with its result (null = void) or error. */
+    private fun respond(
+        call: PluginCall,
+        start: CoroutineStart = CoroutineStart.DEFAULT,
+        block: suspend (JSONObject) -> JSONObject?,
+    ): Job = components.scope.launch(start = start) {
+        try {
+            CallResponder.resolve(call, block(optionsOf(call)))
+        } catch (t: Throwable) { // also Errors (e.g. NoClassDefFoundError of a missing SDK): always settle the call
+            // Our own cancellation (plugin destroyed / scope cancelled): nobody is listening any more.
+            if (t is CancellationException && !isActive) return@launch
+            CallResponder.reject(call, t)
+        }
+    }
+
+    /**
+     * Emits on the bridge's plugin thread, where Capacitor also adds and removes listeners, so the listener list is
+     * never read and modified concurrently. The payload is built only if JS listens; events are dropped while no
+     * bridge is attached.
+     */
+    private fun notifyOnBridgeThread(name: String, payload: () -> JSONObject) {
+        val b = bridge ?: return
+        b.execute {
+            try {
+                if (hasListeners(name)) notifyListeners(name, JSObject.fromJSONObject(payload()))
+            } catch (t: Throwable) {
+                Logger.e(TAG, "notifyListeners($name) failed", t)
+            }
+        }
+    }
+
+    private fun optionsOf(call: PluginCall): JSONObject = call.data ?: JSObject()
+
+    private companion object {
+        const val TAG = "LT.Plugin"
+
+        /** Name of the `@PermissionCallback` method; Capacitor looks it up by name. */
+        const val PERMISSION_CALLBACK = "onPermissionRequestResult"
+    }
+}

package/android/src/main/java/com/brickssoft/locationtracking/api/LocationTrackingListener.kt

@@ -0,0 +1,52 @@
+// CONTRACT (scaffold, round 2): signatures fixed by docs/e2e/architecture.md §2. Owned by Unit 5 (Companion native
+// API) for KDoc and behavior only; do not change the signatures.
+package com.brickssoft.locationtracking.api
+
+import android.content.Context
+import org.json.JSONObject
+
+/**
+ * Receives every queued record and every tracking event natively, also in processes where no WebView (and no JS)
+ * exists: after a reboot, a heartbeat alarm or a `START_STICKY` restart.
+ *
+ * Register it in one of two ways:
+ * - **Manifest** (recommended for a companion plugin that must never miss an event): a `<meta-data>` inside
+ *   `<application>` whose name is [LocationTrackingNative.LISTENER_META_DATA] (or starts with it followed by `.`, for
+ *   a second listener) and whose value is the fully qualified class name. The class needs a public no-arg
+ *   constructor. It is instantiated once per process in `Components.bootstrap()`, which every entry point runs
+ *   (plugin load, service, receivers) before the engine can emit anything.
+ * - **Programmatically**: [LocationTrackingNative.addListener]; receives only what is emitted after the call.
+ *
+ * Methods run on the plugin's single `LT-native` background thread, in emission order (a record's [onRecord] comes
+ * before the events that carry it). Every exception (also an Error) thrown by a method is caught and logged, and the
+ * other listeners still receive the call. Delivery never blocks the engine, but one slow listener delays every later
+ * delivery to every listener: keep the methods short and hand long work (I/O, uploads) to your own executor.
+ *
+ * Both methods receive the application context and a JSONObject built for this listener alone (changing it does not
+ * affect other listeners). Guide: `docs/native-api.md`.
+ */
+interface LocationTrackingListener {
+    /**
+     * Every record queued for upload, including `tracking_start`/`tracking_stop`, `providerchange`, `heartbeat`,
+     * `geofence` and `insertLocation()` records: the wire JSON of `RecordJson.toJson(record)` (no `sent_at`). A record
+     * the plugin creates is delivered also when the plugin failed to store it in its database; an `insertLocation()`
+     * whose insert fails is rejected instead and not delivered.
+     */
+    fun onRecord(context: Context, record: JSONObject) {}
+
+    /** Every JS event, with the same name and payload as the JS `addListener` API (`EventJson.name` / `payload`). */
+    fun onEvent(context: Context, name: String, payload: JSONObject) {}
+}
+
+/** Returned by [LocationTrackingNative.addListener]. Idempotent. */
+fun interface NativeSubscription {
+    fun remove()
+}
+
+/**
+ * Result of a [LocationTrackingNative] call, always invoked on the `LT-native` thread. A failure carries a
+ * `com.brickssoft.locationtracking.core.TrackingException` whose `code` is the JS `ErrorCode`.
+ */
+fun interface NativeCallback<T> {
+    fun onResult(result: Result<T>)
+}