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

package/android/src/main/java/com/brickssoft/locationtracking/core/Components.kt

@@ -0,0 +1,217 @@
+package com.brickssoft.locationtracking.core
+
+import android.annotation.SuppressLint
+import android.content.Context
+import androidx.annotation.VisibleForTesting
+import com.brickssoft.locationtracking.api.NativeListeners
+import com.brickssoft.locationtracking.config.ConfigStore
+import com.brickssoft.locationtracking.config.SharedPrefsConfigStore
+import com.brickssoft.locationtracking.data.GeofenceStore
+import com.brickssoft.locationtracking.data.LocationStore
+import com.brickssoft.locationtracking.data.SqliteGeofenceStore
+import com.brickssoft.locationtracking.data.SqliteLocationStore
+import com.brickssoft.locationtracking.data.TrackingDatabase
+import com.brickssoft.locationtracking.device.DefaultDeviceInfoProvider
+import com.brickssoft.locationtracking.device.DefaultDeviceMonitor
+import com.brickssoft.locationtracking.device.DeviceInfoProvider
+import com.brickssoft.locationtracking.device.DeviceMonitor
+import com.brickssoft.locationtracking.engine.DefaultTrackingEngine
+import com.brickssoft.locationtracking.engine.TrackingEngine
+import com.brickssoft.locationtracking.geofence.DefaultGeofenceManager
+import com.brickssoft.locationtracking.geofence.GeofenceManager
+import com.brickssoft.locationtracking.heartbeat.DefaultHeartbeatScheduler
+import com.brickssoft.locationtracking.heartbeat.HeartbeatScheduler
+import com.brickssoft.locationtracking.http.HttpSyncer
+import com.brickssoft.locationtracking.http.OkHttpSyncer
+import com.brickssoft.locationtracking.logging.FileLogger
+import com.brickssoft.locationtracking.logging.LogStore
+import com.brickssoft.locationtracking.permission.DefaultPermissionManager
+import com.brickssoft.locationtracking.permission.PermissionManager
+import com.brickssoft.locationtracking.position.DefaultPositionService
+import com.brickssoft.locationtracking.position.PositionService
+import com.brickssoft.locationtracking.processing.DefaultLocationProcessor
+import com.brickssoft.locationtracking.processing.DefaultOdometer
+import com.brickssoft.locationtracking.processing.DefaultRecordFactory
+import com.brickssoft.locationtracking.processing.LocationProcessor
+import com.brickssoft.locationtracking.processing.Odometer
+import com.brickssoft.locationtracking.processing.RecordFactory
+import com.brickssoft.locationtracking.provider.DefaultProviderFactory
+import com.brickssoft.locationtracking.provider.ProviderFactory
+import com.brickssoft.locationtracking.provider.StationaryRegionSink
+import com.brickssoft.locationtracking.record.DefaultRecordSink
+import com.brickssoft.locationtracking.record.RecordSink
+import com.brickssoft.locationtracking.service.DefaultServiceController
+import com.brickssoft.locationtracking.service.ServiceController
+import com.brickssoft.locationtracking.settings.DefaultDeviceSettings
+import com.brickssoft.locationtracking.settings.DeviceSettings
+import kotlinx.coroutines.CoroutineExceptionHandler
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.cancel
+import kotlinx.coroutines.flow.distinctUntilChanged
+import kotlinx.coroutines.flow.map
+import kotlinx.coroutines.launch
+import okhttp3.OkHttpClient
+
+/**
+ * Lazy service locator: the single place where every component is constructed. It fixes each unit's constructor
+ * signature. Dependency cycles are broken with [Lazy] parameters, which constructors must not touch.
+ *
+ * Obtain it with [Components.get] from any context (plugin, service, receivers).
+ */
+class Components private constructor(context: Context) {
+    /** The application context. */
+    val context: Context = context.applicationContext ?: context
+
+    val clock: Clock = SystemClockImpl(this.context)
+    val dispatchers: AppDispatchers = AppDispatchers.DEFAULT
+    val scope: CoroutineScope = CoroutineScope(
+        SupervisorJob() + dispatchers.engine + CoroutineExceptionHandler { _, t -> Logger.e("LT", "uncaught", t) },
+    )
+    val events: EventBus = SimpleEventBus()
+
+    /** Round 2: every queued record (sink and insertLocation) for the companion native API (unit 5). */
+    val recordHooks: RecordHooks = RecordHooks()
+    val http: OkHttpClient by lazy { OkHttpClient() }
+
+    // U17
+    val logStore: LogStore by lazy { FileLogger(this.context, clock, dispatchers, lazy { http }) }
+
+    // U3
+    val configStore: ConfigStore by lazy { SharedPrefsConfigStore(this.context, clock) }
+
+    // U15
+    val permissions: PermissionManager by lazy { DefaultPermissionManager(this.context) }
+    val deviceSettings: DeviceSettings by lazy { DefaultDeviceSettings(this.context) }
+
+    // U6
+    val providers: ProviderFactory by lazy { DefaultProviderFactory(this.context, configStore) }
+
+    // U14
+    val device: DeviceMonitor by lazy {
+        DefaultDeviceMonitor(
+            this.context, configStore, permissions, lazy { providers }, events, clock,
+            lazy { recordFactory }, lazy { recordSink }, scope,
+        )
+    }
+    val deviceInfo: DeviceInfoProvider by lazy { DefaultDeviceInfoProvider(this.context, lazy { providers }) }
+
+    // U10
+    private val database by lazy { TrackingDatabase(this.context) }
+    val locationStore: LocationStore by lazy { SqliteLocationStore(database, configStore, clock, dispatchers) }
+    val geofenceStore: GeofenceStore by lazy { SqliteGeofenceStore(database, dispatchers) }
+
+    // U9
+    val processor: LocationProcessor by lazy { DefaultLocationProcessor(configStore) }
+    val odometer: Odometer by lazy { DefaultOdometer(configStore) }
+    val recordFactory: RecordFactory by lazy { DefaultRecordFactory(configStore, device, providers, clock) }
+
+    // U11
+    val syncer: HttpSyncer by lazy {
+        OkHttpSyncer(configStore, locationStore, device, events, clock, http, dispatchers, scope)
+    }
+
+    // U12
+    val heartbeat: HeartbeatScheduler by lazy {
+        DefaultHeartbeatScheduler(
+            this.context, configStore, device, providers, locationStore, recordFactory, lazy { recordSink }, clock, scope,
+        )
+    }
+
+    // SCAFFOLD
+    val recordSink: RecordSink by lazy {
+        DefaultRecordSink(locationStore, configStore, heartbeat, syncer, events, recordHooks)
+    }
+
+    // U13 (round 2: STATIONARY_REGION_ID transitions go to the engine)
+    val geofences: GeofenceManager by lazy {
+        DefaultGeofenceManager(
+            geofenceStore, providers, configStore, recordFactory, recordSink, events, clock, scope,
+            lazy { stationarySink },
+        )
+    }
+
+    // U16
+    val positions: PositionService by lazy {
+        DefaultPositionService(providers, configStore, permissions, device, recordFactory, recordSink, clock, scope)
+    }
+
+    // U8
+    val serviceController: ServiceController by lazy { DefaultServiceController(this.context, configStore, events, clock) }
+
+    // U7
+    val engine: TrackingEngine by lazy {
+        DefaultTrackingEngine(
+            configStore, providers, processor, odometer, recordFactory, recordSink,
+            heartbeat, geofences, serviceController, device, syncer, permissions, events, clock, scope,
+            ForceStopProbe.system(this.context),
+        )
+    }
+
+    /** Round 2: the engine receives the transitions of its stationary region (unit 2). */
+    val stationarySink: StationaryRegionSink get() = engine
+
+    /**
+     * Runs once, right after construction: installs the file logger, keeps its level in sync with config and (round 2)
+     * installs the native companion listeners before any component can emit.
+     */
+    private fun bootstrap() {
+        Logger.sink = logStore
+        val store = configStore
+        val initial = store.config.value.logger
+        logStore.configure(initial.logLevel, initial.logMaxDays)
+        scope.launch {
+            store.config
+                .map { it.logger }
+                .distinctUntilChanged()
+                .collect { logStore.configure(it.logLevel, it.logMaxDays) }
+        }
+        try {
+            NativeListeners.install(context, this)
+        } catch (e: Exception) {
+            Logger.e(Constants.TAG, "failed to install native listeners", e)
+        }
+    }
+
+    companion object {
+        @SuppressLint("StaticFieldLeak") // holds the application context only
+        @Volatile
+        private var instance: Components? = null
+
+        /** The instance whose [bootstrap] is running; only read and written while holding the lock. */
+        @SuppressLint("StaticFieldLeak") // holds the application context only
+        private var constructing: Components? = null
+
+        /**
+         * Thread-safe; always uses the application context.
+         *
+         * The instance is published only after [bootstrap] has run, so no other thread can use it (and emit a record)
+         * before the manifest-declared native listeners are installed. Other threads wait on the lock meanwhile; a
+         * nested call on the constructing thread (the lock is reentrant) gets the instance under construction.
+         */
+        fun get(context: Context): Components {
+            instance?.let { return it }
+            return synchronized(this) {
+                instance ?: constructing ?: Components(context).also {
+                    constructing = it
+                    try {
+                        it.bootstrap()
+                    } finally {
+                        constructing = null
+                        instance = it
+                    }
+                }
+            }
+        }
+
+        /** Test hook: cancels the scope, detaches the log sink and forgets the instance. */
+        @VisibleForTesting
+        fun reset() {
+            synchronized(this) {
+                instance?.scope?.cancel()
+                instance = null
+                Logger.sink = null
+            }
+        }
+    }
+}

package/android/src/main/java/com/brickssoft/locationtracking/core/Constants.kt

@@ -0,0 +1,78 @@
+package com.brickssoft.locationtracking.core
+
+import android.app.PendingIntent
+import android.os.Build
+
+/** Shared names, ids and PendingIntent request codes. */
+object Constants {
+    /** Tag prefix for [Logger]. */
+    const val TAG = "LT"
+
+    const val PREFS_NAME = "location_tracking_prefs"
+    const val DATABASE_NAME = "location_tracking.db"
+    const val LOG_DIR = "location-tracking-logs"
+
+    /** Authority suffix of `LogFileProvider`: `${applicationId}.locationtracking.logs`. */
+    const val LOG_FILE_PROVIDER_SUFFIX = ".locationtracking.logs"
+
+    /** Maximum number of registered geofences. */
+    const val MAX_GEOFENCES = 100
+
+    /**
+     * Id of the engine's own OS geofence while STATIONARY (GPS off): a circle around the stationary anchor whose EXIT
+     * wakes the engine. It is never stored, never counted against [MAX_GEOFENCES], never recorded and never emitted;
+     * `DefaultGeofenceManager` routes its transitions to `StationaryRegionSink` (architecture round 2, §3).
+     */
+    const val STATIONARY_REGION_ID = "__lt_stationary__"
+
+    /** Maximum number of notification action buttons. */
+    const val MAX_NOTIFICATION_ACTIONS = 3
+
+    const val NOTIFICATION_ID = 7301
+
+    /** The resume notification (`notification.resume`) and its channel. */
+    const val RESUME_NOTIFICATION_ID = 7302
+    const val RESUME_CHANNEL_ID = "location_tracking_resume"
+
+    // PendingIntent request codes
+    const val RC_HEARTBEAT = 7310
+    const val RC_GMS_ACTIVITY = 7320
+    const val RC_GMS_GEOFENCE = 7321
+    const val RC_HMS_ACTIVITY = 7330
+    const val RC_HMS_GEOFENCE = 7331
+    const val RC_NOTIFICATION_CONTENT = 7349
+    const val RC_RESUME_NOTIFICATION = 7348
+
+    /** Notification action `i` uses `RC_NOTIFICATION_ACTION_BASE + i`. */
+    const val RC_NOTIFICATION_ACTION_BASE = 7350
+
+    /** Android proximity alerts; told apart by the data URI [geofenceUri]. */
+    const val RC_ANDROID_PROXIMITY = 7400
+
+    /** Scheme of the data URI that identifies an Android proximity-alert PendingIntent. */
+    const val GEOFENCE_URI_SCHEME = "lt-geofence"
+
+    // Intent actions / extras
+    const val ACTION_HEARTBEAT = "com.brickssoft.locationtracking.HEARTBEAT"
+    const val ACTION_NOTIFICATION_ACTION = "com.brickssoft.locationtracking.NOTIFICATION_ACTION"
+    const val ACTION_GEOFENCE = "com.brickssoft.locationtracking.GEOFENCE"
+    const val ACTION_ACTIVITY = "com.brickssoft.locationtracking.ACTIVITY"
+    const val EXTRA_ACTION_ID = "com.brickssoft.locationtracking.EXTRA_ACTION_ID"
+
+    /** `lt-geofence://<id>` */
+    fun geofenceUri(id: String): String = "$GEOFENCE_URI_SCHEME://${android.net.Uri.encode(id)}"
+
+    /**
+     * Flags for PendingIntents the OS must fill in (GMS/HMS activity and geofence, proximity alerts):
+     * `FLAG_UPDATE_CURRENT | FLAG_MUTABLE` on API 31+.
+     */
+    fun piMutable(): Int =
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
+            PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_MUTABLE
+        } else {
+            PendingIntent.FLAG_UPDATE_CURRENT
+        }
+
+    /** Flags for alarm, notification and action PendingIntents: `FLAG_UPDATE_CURRENT | FLAG_IMMUTABLE`. */
+    fun piImmutable(): Int = PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
+}

package/android/src/main/java/com/brickssoft/locationtracking/core/Errors.kt

@@ -0,0 +1,27 @@
+package com.brickssoft.locationtracking.core
+
+/** Rejection codes; `name` is the JS `code` of a failed promise. */
+enum class ErrorCode {
+    NOT_READY,
+    PERMISSION_DENIED,
+    LOCATION_DISABLED,
+    TIMEOUT,
+    UNAVAILABLE,
+    INVALID_ARGUMENT,
+    NOT_FOUND,
+    NO_URL,
+    HTTP_ERROR,
+    NETWORK_ERROR,
+    TOO_MANY_GEOFENCES,
+    NO_ACTIVITY,
+    IO_ERROR,
+    UNIMPLEMENTED,
+    INTERNAL,
+}
+
+/** The only exception type that crosses component boundaries; the bridge maps it to `call.reject(message, code.name)`. */
+class TrackingException(
+    val code: ErrorCode,
+    message: String,
+    cause: Throwable? = null,
+) : Exception(message, cause)

package/android/src/main/java/com/brickssoft/locationtracking/core/EventBus.kt

@@ -0,0 +1,39 @@
+package com.brickssoft.locationtracking.core
+
+import java.util.concurrent.CopyOnWriteArrayList
+
+/** Handle returned by [EventBus.subscribe]. */
+fun interface Subscription {
+    fun cancel()
+}
+
+/** In-process event bus. Delivery is synchronous, on the emitter's thread. */
+interface EventBus {
+    fun emit(event: TrackingEvent)
+
+    fun subscribe(listener: (TrackingEvent) -> Unit): Subscription
+}
+
+/** Default [EventBus]. A throwing listener is logged and does not affect other listeners. */
+class SimpleEventBus : EventBus {
+    private val listeners = CopyOnWriteArrayList<(TrackingEvent) -> Unit>()
+
+    override fun emit(event: TrackingEvent) {
+        for (listener in listeners) {
+            try {
+                listener(event)
+            } catch (e: Exception) {
+                Logger.e(TAG, "event listener failed for ${event::class.simpleName}", e)
+            }
+        }
+    }
+
+    override fun subscribe(listener: (TrackingEvent) -> Unit): Subscription {
+        listeners.add(listener)
+        return Subscription { listeners.remove(listener) }
+    }
+
+    private companion object {
+        const val TAG = "LT.EventBus"
+    }
+}

package/android/src/main/java/com/brickssoft/locationtracking/core/ForceStopProbe.kt

@@ -0,0 +1,63 @@
+package com.brickssoft.locationtracking.core
+
+import android.app.ActivityManager
+import android.app.ApplicationExitInfo
+import android.content.Context
+import android.os.Build
+
+/**
+ * Tells whether this process started after the user force-stopped the app (Settings → Force stop, `am force-stop`).
+ *
+ * Android cancels the app's alarms and does not restart its services after a force stop, so tracking stays off until
+ * the user opens the app again. A broadcast that was already on its way can still start the process (on the CI
+ * emulator a Play services activity update arrived 0.5 s after `am force-stop`, scenario P-L04). The engine asks this
+ * probe before a background trigger (activity update, stationary region EXIT) restores tracking.
+ */
+fun interface ForceStopProbe {
+    /** True when the previous process of this app ended with a user force stop. */
+    fun startedAfterForceStop(): Boolean
+
+    companion object {
+        private const val TAG = "LT.ForceStop"
+
+        /** Exit records read to find the main process's newest one (other processes of the app leave records too). */
+        private const val EXIT_RECORDS = 16
+
+        /** Never reports a force stop (tests, and Android 10 and older). */
+        val NEVER: ForceStopProbe = ForceStopProbe { false }
+
+        /**
+         * Reads `ActivityManager.getHistoricalProcessExitReasons` (Android 11+, no permission needed for the own
+         * package) once per process: the newest exit record of the app's main process is the previous process.
+         * Records of other processes are skipped: the WebView's isolated renderer runs under the app, and a force stop
+         * kills it a few milliseconds after the main process ("isolated not needed"), so its record can be the newest
+         * one (CI emulator, API 34, scenario P-L04: reading only the newest record missed the force stop).
+         */
+        fun system(context: Context): ForceStopProbe {
+            val app = context.applicationContext ?: context
+            val result by lazy(LazyThreadSafetyMode.SYNCHRONIZED) { lastExitWasForceStop(app) }
+            return ForceStopProbe { result }
+        }
+
+        private fun lastExitWasForceStop(context: Context): Boolean {
+            if (Build.VERSION.SDK_INT < Build.VERSION_CODES.R) return false
+            return try {
+                val manager = context.getSystemService(ActivityManager::class.java) ?: return false
+                val mainProcess = context.applicationInfo?.processName ?: context.packageName
+                val previous = manager.getHistoricalProcessExitReasons(context.packageName, 0, EXIT_RECORDS)
+                    .firstOrNull { it.processName == mainProcess }
+                    ?: return false
+                val forceStopped = previous.reason == ApplicationExitInfo.REASON_USER_REQUESTED
+                Logger.i(
+                    TAG,
+                    "previous process ${previous.pid} exited with reason ${previous.reason} " +
+                        "(${previous.description ?: "no description"}); force stop: $forceStopped",
+                )
+                forceStopped
+            } catch (e: Exception) {
+                Logger.w(TAG, "the previous process's exit reason is unknown", e)
+                false
+            }
+        }
+    }
+}

package/android/src/main/java/com/brickssoft/locationtracking/core/Iso8601.kt

@@ -0,0 +1,63 @@
+package com.brickssoft.locationtracking.core
+
+import java.text.ParsePosition
+import java.text.SimpleDateFormat
+import java.util.Date
+import java.util.Locale
+import java.util.TimeZone
+
+/**
+ * ISO-8601 formatting and parsing for API 24+ (no `java.time`).
+ * The output format is always `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'` in UTC.
+ */
+object Iso8601 {
+    private const val PATTERN = "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'"
+
+    private val formatter = threadLocalFormat(PATTERN)
+
+    /** Accepted input patterns, tried in order (UTC 'Z' with/without millis, numeric offsets). */
+    private val parsers = listOf(
+        threadLocalFormat(PATTERN),
+        threadLocalFormat("yyyy-MM-dd'T'HH:mm:ss'Z'"),
+        threadLocalFormat("yyyy-MM-dd'T'HH:mm:ss.SSSXXX"),
+        threadLocalFormat("yyyy-MM-dd'T'HH:mm:ssXXX"),
+    )
+
+    private fun threadLocalFormat(pattern: String): ThreadLocal<SimpleDateFormat> =
+        object : ThreadLocal<SimpleDateFormat>() {
+            override fun initialValue(): SimpleDateFormat = SimpleDateFormat(pattern, Locale.US).apply {
+                timeZone = TimeZone.getTimeZone("UTC")
+                isLenient = false
+            }
+        }
+
+    /** Formats epoch ms as `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'`. */
+    fun format(epochMs: Long): String = formatter.get()!!.format(Date(epochMs))
+
+    /** [format], or null for null input. */
+    fun formatOrNull(epochMs: Long?): String? = epochMs?.let { format(it) }
+
+    /** Parses an ISO-8601 timestamp to epoch ms, or returns null if it is not valid. */
+    fun parse(text: String?): Long? {
+        if (text.isNullOrBlank()) return null
+        val trimmed = normalizeFraction(text.trim())
+        for (parser in parsers) {
+            val position = ParsePosition(0)
+            val date = parser.get()!!.parse(trimmed, position)
+            if (date != null && position.index == trimmed.length) return date.time
+        }
+        return null
+    }
+
+    /** Pads or truncates the fractional seconds to exactly 3 digits so SimpleDateFormat parses them as ms. */
+    private fun normalizeFraction(text: String): String {
+        val dot = text.indexOf('.', startIndex = 19)
+        if (dot != 19) return text
+        var end = dot + 1
+        while (end < text.length && text[end].isDigit()) end++
+        val digits = text.substring(dot + 1, end)
+        if (digits.isEmpty()) return text
+        val ms = digits.padEnd(3, '0').substring(0, 3)
+        return text.substring(0, dot + 1) + ms + text.substring(end)
+    }
+}

package/android/src/main/java/com/brickssoft/locationtracking/core/Logger.kt

@@ -0,0 +1,68 @@
+package com.brickssoft.locationtracking.core
+
+import android.util.Log
+
+/** Log levels, ordered from least to most verbose. [wire] is the JS `LogLevel` value. */
+enum class LogLevel {
+    OFF,
+    ERROR,
+    WARN,
+    INFO,
+    DEBUG,
+    VERBOSE,
+    ;
+
+    val wire: String get() = name.lowercase()
+
+    /** True if a message at [level] passes a filter set to this level. */
+    fun allows(level: LogLevel): Boolean = level != OFF && this != OFF && level.ordinal <= ordinal
+
+    companion object {
+        fun fromWire(value: String?): LogLevel? = entries.firstOrNull { it.wire.equals(value, ignoreCase = true) }
+    }
+}
+
+/** Destination for log lines besides logcat (the file logger). */
+interface LogSink {
+    fun write(level: LogLevel, tag: String, message: String, error: Throwable?)
+}
+
+/**
+ * Global logger. Writes every message to logcat and to [sink] (set by `Components.bootstrap()`).
+ * Never throws: failures of the sink or of logcat are swallowed.
+ */
+object Logger {
+    @Volatile
+    var sink: LogSink? = null
+
+    fun e(tag: String, msg: String, t: Throwable? = null) = log(LogLevel.ERROR, tag, msg, t)
+
+    fun w(tag: String, msg: String, t: Throwable? = null) = log(LogLevel.WARN, tag, msg, t)
+
+    fun i(tag: String, msg: String, t: Throwable? = null) = log(LogLevel.INFO, tag, msg, t)
+
+    fun d(tag: String, msg: String, t: Throwable? = null) = log(LogLevel.DEBUG, tag, msg, t)
+
+    fun v(tag: String, msg: String, t: Throwable? = null) = log(LogLevel.VERBOSE, tag, msg, t)
+
+    fun log(level: LogLevel, tag: String, msg: String, t: Throwable? = null) {
+        if (level == LogLevel.OFF) return
+        try {
+            when (level) {
+                LogLevel.ERROR -> Log.e(tag, msg, t)
+                LogLevel.WARN -> Log.w(tag, msg, t)
+                LogLevel.INFO -> Log.i(tag, msg, t)
+                LogLevel.DEBUG -> Log.d(tag, msg, t)
+                LogLevel.VERBOSE -> Log.v(tag, msg, t)
+                LogLevel.OFF -> Unit
+            }
+        } catch (_: Throwable) {
+            // logcat unavailable (plain JVM); ignore
+        }
+        try {
+            sink?.write(level, tag, msg, t)
+        } catch (_: Throwable) {
+            // a broken sink must never break the caller
+        }
+    }
+}

package/android/src/main/java/com/brickssoft/locationtracking/core/RecordHooks.kt

@@ -0,0 +1,47 @@
+package com.brickssoft.locationtracking.core
+
+import com.brickssoft.locationtracking.model.Record
+import java.util.concurrent.CopyOnWriteArrayList
+
+/** Observes every record queued for upload. See [RecordHooks]. */
+fun interface RecordObserver {
+    fun onRecordQueued(record: Record)
+}
+
+/**
+ * Fan-out of every queued record to in-process observers (SCAFFOLD, round 2). The companion native API
+ * (`api/NativeListeners`, unit 5) registers the observer that forwards records to `LocationTrackingListener.onRecord`.
+ *
+ * Callers (unit 5 adds the calls):
+ * - `DefaultRecordSink.submit`, right after the insert (also when the insert failed: a companion listener keeps its
+ *   own audit trail, so a local database failure must not hide the record from it);
+ * - the bridge's `insertLocation`, right after its insert (inserted records bypass the sink).
+ *
+ * [dispatch] is synchronous on the caller's thread (the engine or an I/O coroutine), so observers must not block: they
+ * hand the record off to their own thread. A throwing observer is logged and does not affect the others.
+ */
+class RecordHooks {
+    private val observers = CopyOnWriteArrayList<RecordObserver>()
+
+    fun add(observer: RecordObserver): Subscription {
+        observers.add(observer)
+        return Subscription { observers.remove(observer) }
+    }
+
+    /** True when at least one observer is registered (lets callers skip work). */
+    val hasObservers: Boolean get() = observers.isNotEmpty()
+
+    fun dispatch(record: Record) {
+        for (observer in observers) {
+            try {
+                observer.onRecordQueued(record)
+            } catch (e: Exception) {
+                Logger.e(TAG, "record observer failed for ${record.event.wire} ${record.uuid}", e)
+            }
+        }
+    }
+
+    private companion object {
+        const val TAG = "LT.RecordHooks"
+    }
+}

package/android/src/main/java/com/brickssoft/locationtracking/core/TrackingEvent.kt

@@ -0,0 +1,64 @@
+package com.brickssoft.locationtracking.core
+
+import com.brickssoft.locationtracking.model.ActivitySample
+import com.brickssoft.locationtracking.model.Connectivity
+import com.brickssoft.locationtracking.model.GeofenceAction
+import com.brickssoft.locationtracking.model.GeofenceSpec
+import com.brickssoft.locationtracking.model.HttpResult
+import com.brickssoft.locationtracking.model.ProviderState
+import com.brickssoft.locationtracking.model.Record
+
+/**
+ * Events forwarded to JS. The JS event name and payload are built by
+ * [com.brickssoft.locationtracking.model.EventJson].
+ */
+sealed interface TrackingEvent {
+    /** "location" */
+    data class Location(val record: Record) : TrackingEvent
+
+    /** "motionchange" */
+    data class MotionChange(val isMoving: Boolean, val record: Record) : TrackingEvent
+
+    /** "activitychange" */
+    data class ActivityChange(val activity: ActivitySample) : TrackingEvent
+
+    /** "providerchange" */
+    data class ProviderChange(val state: ProviderState) : TrackingEvent
+
+    /** "heartbeat" */
+    data class Heartbeat(val record: Record) : TrackingEvent
+
+    /** "geofence"; [extras] is JSON object text. */
+    data class Geofence(
+        val identifier: String,
+        val action: GeofenceAction,
+        val record: Record,
+        val extras: String?,
+    ) : TrackingEvent
+
+    /** "geofenceschange" */
+    data class GeofencesChange(val on: List<GeofenceSpec>, val off: List<String>) : TrackingEvent
+
+    /** "http" */
+    data class Http(val result: HttpResult) : TrackingEvent
+
+    /** "connectivitychange" */
+    data class ConnectivityChange(val connectivity: Connectivity) : TrackingEvent
+
+    /** "powersavechange" */
+    data class PowerSaveChange(val isPowerSaveMode: Boolean) : TrackingEvent
+
+    /** "enabledchange" */
+    data class EnabledChange(val enabled: Boolean) : TrackingEvent
+
+    /** "notificationaction" */
+    data class NotificationAction(val id: String) : TrackingEvent
+
+    /** "authorization"; [responseJson] is JSON object text. */
+    data class Authorization(
+        val success: Boolean,
+        val status: Int,
+        val error: String?,
+        val responseJson: String?,
+    ) : TrackingEvent
+}