@bglocation/capacitor 1.1.0

package/android/src/main/kotlin/dev/bglocation/core/Models.kt

@@ -0,0 +1,76 @@
+package dev.bglocation.core
+
+import dev.bglocation.core.location.BGLAutoDistanceFilterConfig
+
+/**
+ * License mode for the plugin.
+ */
+enum class BGLLicenseMode {
+    FULL,
+    TRIAL
+}
+
+/**
+ * Result of license key validation.
+ */
+sealed class BGLLicenseResult {
+    data class Valid(val updatesUntil: Long?) : BGLLicenseResult()
+    data class Invalid(val reason: String) : BGLLicenseResult()
+    data class UpdatesExpired(val updatesUntil: Long) : BGLLicenseResult()
+}
+
+/**
+ * HTTP endpoint configuration for native location uploads.
+ */
+data class BGLHttpConfig(
+    val url: String,
+    val headers: Map<String, String> = emptyMap(),
+    val buffer: BGLLocationBufferConfig? = null
+)
+
+/**
+ * Offline buffer configuration for failed HTTP requests.
+ */
+data class BGLLocationBufferConfig(
+    val maxSize: Int = 1000
+)
+
+/**
+ * Foreground service notification configuration.
+ */
+data class BGLNotificationConfig(
+    val title: String = "Background Location",
+    val text: String = "Tracking your location"
+)
+
+/**
+ * Configuration for the background location plugin.
+ */
+data class BGLLocationConfig(
+    val distanceFilter: Float = 15f,
+    val distanceFilterMode: String = "fixed",
+    val autoDistanceFilter: BGLAutoDistanceFilterConfig? = null,
+    val desiredAccuracy: String = "high",
+    val locationUpdateInterval: Long = 5000L,
+    val fastestLocationUpdateInterval: Long = 2000L,
+    val heartbeatInterval: Int = 15,
+    val http: BGLHttpConfig? = null,
+    val notification: BGLNotificationConfig = BGLNotificationConfig(),
+    val debug: Boolean = false,
+    val debugSounds: Boolean = false
+)
+
+/**
+ * Normalized location data emitted to JS.
+ */
+data class BGLLocationData(
+    val latitude: Double,
+    val longitude: Double,
+    val accuracy: Float,
+    val speed: Float,
+    val heading: Float,
+    val altitude: Double,
+    val timestamp: Long,
+    val isMoving: Boolean,
+    val isMock: Boolean = false
+)

package/android/src/main/kotlin/dev/bglocation/core/battery/BGLBatteryHelper.kt

@@ -0,0 +1,127 @@
+package dev.bglocation.core.battery
+
+import android.content.Context
+import android.content.Intent
+import android.net.Uri
+import android.os.Build
+import android.os.PowerManager
+import android.provider.Settings
+import android.util.Log
+
+/**
+ * Helper for detecting and handling OEM battery optimization that may kill background tracking.
+ *
+ * Many Android OEMs (Xiaomi, Huawei, Samsung, OnePlus, Oppo, Vivo) implement aggressive
+ * battery optimization beyond stock Android Doze mode. This helper:
+ * 1. Checks if the app is exempt from battery optimization
+ * 2. Detects the device manufacturer to provide OEM-specific guidance
+ * 3. Provides dontkillmyapp.com URLs with per-OEM instructions
+ */
+class BGLBatteryHelper(
+    private val context: Context,
+    private val manufacturer: String = Build.MANUFACTURER.lowercase()
+) {
+
+    companion object {
+        private const val TAG = "BGLocation"
+        private const val BASE_URL = "https://dontkillmyapp.com"
+
+        /**
+         * Mapping of manufacturer names (lowercase) to dontkillmyapp.com slugs.
+         * Only OEMs with known aggressive battery management are listed.
+         */
+        private val OEM_SLUGS = mapOf(
+            "xiaomi" to "xiaomi",
+            "huawei" to "huawei",
+            "samsung" to "samsung",
+            "oneplus" to "oneplus",
+            "oppo" to "oppo",
+            "vivo" to "vivo",
+            "realme" to "realme",
+            "meizu" to "meizu",
+            "asus" to "asus",
+            "lenovo" to "lenovo",
+            "nokia" to "nokia",
+            "sony" to "sony",
+            "wiko" to "wiko"
+        )
+    }
+
+    /**
+     * Returns the device manufacturer in lowercase.
+     */
+    fun getManufacturer(): String = manufacturer
+
+    /**
+     * Check if the app is currently exempt from battery optimization.
+     * When true, Android Doze and App Standby will not restrict the app's background execution.
+     */
+    fun isIgnoringBatteryOptimizations(): Boolean {
+        val pm = context.getSystemService(Context.POWER_SERVICE) as? PowerManager
+            ?: return false
+        return pm.isIgnoringBatteryOptimizations(context.packageName)
+    }
+
+    /**
+     * Get the dontkillmyapp.com URL for the current device manufacturer.
+     * Returns the generic page if the manufacturer is not in the known OEM list.
+     */
+    fun getHelpUrl(): String {
+        val manufacturer = getManufacturer()
+        val slug = OEM_SLUGS[manufacturer]
+        return if (slug != null) "$BASE_URL/$slug" else BASE_URL
+    }
+
+    /**
+     * Whether this device's manufacturer is known to have aggressive battery management.
+     */
+    fun isAggressiveOem(): Boolean {
+        return OEM_SLUGS.containsKey(getManufacturer())
+    }
+
+    /**
+     * Build a BatteryWarningEvent-compatible map with current state.
+     */
+    fun checkState(): BGLBatteryState {
+        val isIgnoring = isIgnoringBatteryOptimizations()
+        val manufacturer = getManufacturer()
+        val helpUrl = getHelpUrl()
+        val isAggressive = isAggressiveOem()
+
+        val message = when {
+            isIgnoring -> "Battery optimization is disabled for this app. Background tracking is safe."
+            isAggressive -> "Battery optimization is active on $manufacturer. Background tracking may be killed. Please follow the instructions at $helpUrl to whitelist this app."
+            else -> "Battery optimization is active. Background tracking may be restricted. Consider disabling battery optimization for this app."
+        }
+
+        return BGLBatteryState(
+            isIgnoringOptimizations = isIgnoring,
+            manufacturer = manufacturer,
+            helpUrl = helpUrl,
+            message = message
+        )
+    }
+
+    /**
+     * Create an intent to request battery optimization exemption via system dialog.
+     * Returns null if the permission is already granted.
+     */
+    fun createBatteryOptimizationIntent(): Intent? {
+        if (isIgnoringBatteryOptimizations()) return null
+
+        return Intent(Settings.ACTION_REQUEST_IGNORE_BATTERY_OPTIMIZATIONS).apply {
+            data = Uri.parse("package:${context.packageName}")
+            addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
+        }
+    }
+}
+
+/**
+ * Represents the current battery optimization state.
+ */
+data class BGLBatteryState(
+    val isIgnoringOptimizations: Boolean,
+    val manufacturer: String,
+    val helpUrl: String,
+    val message: String
+)

package/android/src/main/kotlin/dev/bglocation/core/boot/BGLBootCompletedReceiver.kt

@@ -0,0 +1,32 @@
+package dev.bglocation.core.boot
+
+import dev.bglocation.core.geofence.BGLGeofenceManager
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import android.util.Log
+
+/**
+ * Re-registers persisted geofences after device boot.
+ *
+ * Android clears all registered geofences on reboot. This receiver fires on
+ * BOOT_COMPLETED and re-registers them from SharedPreferences persistence.
+ *
+ * Requires `<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />`
+ * in AndroidManifest.xml.
+ */
+class BGLBootCompletedReceiver : BroadcastReceiver() {
+
+    companion object {
+        private const val TAG = "BGLocation"
+    }
+
+    override fun onReceive(context: Context, intent: Intent) {
+        if (intent.action != Intent.ACTION_BOOT_COMPLETED) return
+
+        Log.d(TAG, "BGLBootCompletedReceiver: device booted — re-registering geofences")
+
+        val manager = BGLGeofenceManager(context)
+        manager.reRegisterAllGeofences()
+    }
+}

package/android/src/main/kotlin/dev/bglocation/core/config/BGLConfigParser.kt

@@ -0,0 +1,114 @@
+package dev.bglocation.core.config
+
+import dev.bglocation.core.location.BGLAutoDistanceFilterConfig
+import dev.bglocation.core.BGLHttpConfig
+import dev.bglocation.core.BGLLocationBufferConfig
+import dev.bglocation.core.BGLLocationConfig
+import dev.bglocation.core.BGLNotificationConfig
+import org.json.JSONObject
+
+/**
+ * Framework-agnostic parser: accepts [JSONObject] instead of Capacitor PluginCall.
+ */
+object BGLConfigParser {
+
+    /**
+     * Parse HTTP config from the "http" object.
+     * Returns null if no valid URL is provided.
+     */
+    fun parseHttpConfig(options: JSONObject): BGLHttpConfig? {
+        val httpObj = options.optJSONObject("http") ?: return null
+        if (!httpObj.has("url")) return null
+
+        val headers = mutableMapOf<String, String>()
+        httpObj.optJSONObject("headers")?.let { headersObj ->
+            headersObj.keys().forEach { key ->
+                headers[key] = headersObj.getString(key)
+            }
+        }
+        val bufferObj = httpObj.optJSONObject("buffer")
+        val bufferConfig = if (bufferObj != null) {
+            BGLLocationBufferConfig(
+                maxSize = bufferObj.optInt("maxSize", 1000)
+            )
+        } else {
+            null
+        }
+        return BGLHttpConfig(
+            url = httpObj.getString("url") ?: "",
+            headers = headers,
+            buffer = bufferConfig
+        )
+    }
+
+    /**
+     * Parse notification config from the "notification" object.
+     * Returns defaults if not provided.
+     */
+    fun parseNotificationConfig(options: JSONObject): BGLNotificationConfig {
+        val notifObj = options.optJSONObject("notification") ?: return BGLNotificationConfig()
+        return BGLNotificationConfig(
+            title = notifObj.optString("title", "Background Location"),
+            text = notifObj.optString("text", "Tracking your location")
+        )
+    }
+
+    /**
+     * Parse distance filter mode and value.
+     * Returns a pair of (distanceFilterMode, distanceFilter).
+     */
+    fun parseDistanceFilter(options: JSONObject): Pair<String, Float> {
+        val distanceFilterRaw = options.optString("distanceFilter", null)
+        val isAutoMode = distanceFilterRaw == "auto"
+        val mode = if (isAutoMode) "auto" else "fixed"
+        val value = if (isAutoMode) {
+            BGLAutoDistanceFilterConfig.DEFAULT_MIN_DISTANCE
+        } else {
+            options.optDouble("distanceFilter", 15.0).toFloat()
+        }
+        return Pair(mode, value)
+    }
+
+    /**
+     * Parse auto distance filter config.
+     * Returns null if not in auto mode.
+     */
+    fun parseAutoDistanceFilterConfig(options: JSONObject, isAutoMode: Boolean): BGLAutoDistanceFilterConfig? {
+        if (!isAutoMode) return null
+        val autoObj = options.optJSONObject("autoDistanceFilter")
+        return if (autoObj != null) {
+            BGLAutoDistanceFilterConfig(
+                targetInterval = autoObj.optDouble("targetInterval", BGLAutoDistanceFilterConfig.DEFAULT_TARGET_INTERVAL.toDouble()),
+                minDistance = autoObj.optDouble("minDistance", BGLAutoDistanceFilterConfig.DEFAULT_MIN_DISTANCE.toDouble()).toFloat(),
+                maxDistance = autoObj.optDouble("maxDistance", BGLAutoDistanceFilterConfig.DEFAULT_MAX_DISTANCE.toDouble()).toFloat()
+            )
+        } else {
+            BGLAutoDistanceFilterConfig()
+        }
+    }
+
+    /**
+     * Build the full BGLLocationConfig from a JSONObject options dictionary.
+     */
+    fun parseLocationConfig(options: JSONObject): BGLLocationConfig {
+        val httpConfig = parseHttpConfig(options)
+        val notificationConfig = parseNotificationConfig(options)
+        val (distanceFilterMode, distanceFilter) = parseDistanceFilter(options)
+        val isAutoMode = distanceFilterMode == "auto"
+        val autoDistanceFilterConfig = parseAutoDistanceFilterConfig(options, isAutoMode)
+
+        return BGLLocationConfig(
+            distanceFilter = distanceFilter,
+            distanceFilterMode = distanceFilterMode,
+            autoDistanceFilter = autoDistanceFilterConfig,
+            desiredAccuracy = options.optString("desiredAccuracy", "high"),
+            locationUpdateInterval = options.optLong("locationUpdateInterval", 5000L),
+            fastestLocationUpdateInterval = options.optLong("fastestLocationUpdateInterval", 2000L),
+            heartbeatInterval = options.optInt("heartbeatInterval", 15),
+            http = httpConfig,
+            notification = notificationConfig,
+            debug = options.optBoolean("debug", false),
+            debugSounds = options.optBoolean("debugSounds", false)
+        )
+    }
+}

package/android/src/main/kotlin/dev/bglocation/core/config/BGLVersion.kt

@@ -0,0 +1,6 @@
+package dev.bglocation.core.config
+
+/** Version constant for the BGLocationCore native library. */
+object BGLVersion {
+    const val VERSION = "1.0.2"
+}

package/android/src/main/kotlin/dev/bglocation/core/debug/BGLDebugLogger.kt

@@ -0,0 +1,174 @@
+package dev.bglocation.core.debug
+
+import android.media.ToneGenerator
+import android.media.AudioManager
+import android.util.Log
+
+/**
+ * Debug logger for the background location plugin.
+ *
+ * When [enabled], emits detailed logs via [Log.d] and fires [onDebug] callbacks
+ * with human-readable messages. Optionally plays short system sounds when
+ * [soundsEnabled] is true — useful for confirming background location events
+ * without looking at the screen.
+ */
+class BGLDebugLogger {
+
+    companion object {
+        private const val TAG = "BGL_DEBUG"
+    }
+
+    var enabled = false
+        private set
+    var soundsEnabled = false
+        private set
+
+    var onDebug: ((String) -> Unit)? = null
+
+    var locationCount = 0
+        private set
+    var heartbeatCount = 0
+        private set
+    var httpSuccessCount = 0
+        private set
+    var httpErrorCount = 0
+        private set
+
+    private var toneGenerator: ToneGenerator? = null
+
+    fun configure(debug: Boolean, debugSounds: Boolean) {
+        enabled = debug
+        soundsEnabled = debugSounds
+        if (debug && debugSounds) {
+            toneGenerator = try {
+                ToneGenerator(AudioManager.STREAM_MUSIC, 100)
+            } catch (_: Exception) {
+                null
+            }
+        } else {
+            toneGenerator?.release()
+            toneGenerator = null
+        }
+        reset()
+    }
+
+    fun reset() {
+        locationCount = 0
+        heartbeatCount = 0
+        httpSuccessCount = 0
+        httpErrorCount = 0
+    }
+
+    fun logConfigure(distanceFilter: Float, heartbeat: Int, httpUrl: String?) {
+        if (!enabled) return
+        val httpInfo = httpUrl ?: "disabled"
+        emit("CONFIGURE distance=${distanceFilter}m heartbeat=${heartbeat}s http=$httpInfo")
+    }
+
+    fun logStart() {
+        if (!enabled) return
+        reset()
+        emit("START tracking")
+        playTone(ToneGenerator.TONE_PROP_BEEP)
+    }
+
+    fun logStop() {
+        if (!enabled) return
+        emit("STOP tracking — locations=$locationCount heartbeats=$heartbeatCount http_ok=$httpSuccessCount http_err=$httpErrorCount")
+        playTone(ToneGenerator.TONE_PROP_BEEP2)
+    }
+
+    fun logLocation(lat: Double, lng: Double, accuracy: Float, speed: Float, isMoving: Boolean) {
+        if (!enabled) return
+        locationCount++
+        val moving = if (isMoving) "moving" else "stationary"
+        emit("LOCATION #$locationCount (${"%.5f".format(lat)}, ${"%.5f".format(lng)}) acc=${"%.1f".format(accuracy)}m spd=${"%.1f".format(speed)}m/s $moving")
+        playTone(ToneGenerator.TONE_PROP_ACK)
+    }
+
+    fun logHeartbeat(hasLocation: Boolean) {
+        if (!enabled) return
+        heartbeatCount++
+        val status = if (hasLocation) "with location" else "no location"
+        emit("HEARTBEAT #$heartbeatCount $status")
+        playTone(ToneGenerator.TONE_SUP_CONFIRM)
+    }
+
+    fun logHttp(statusCode: Int, success: Boolean, error: String?) {
+        if (!enabled) return
+        if (success) {
+            httpSuccessCount++
+            emit("HTTP OK #$httpSuccessCount status=$statusCode")
+        } else {
+            httpErrorCount++
+            val errMsg = error ?: "unknown"
+            emit("HTTP ERROR #$httpErrorCount status=$statusCode error=$errMsg")
+            playTone(ToneGenerator.TONE_SUP_ERROR)
+        }
+    }
+
+    fun logMessage(message: String) {
+        if (!enabled) return
+        emit(message)
+    }
+
+    // MARK: - Geofence Logging
+
+    fun logGeofenceAdd(identifier: String) {
+        if (!enabled) return
+        emit("GEOFENCE ADD $identifier")
+        playTone(ToneGenerator.TONE_PROP_ACK)
+    }
+
+    fun logGeofenceAddBatch(count: Int) {
+        if (!enabled) return
+        emit("GEOFENCE ADD_BATCH count=$count")
+        playTone(ToneGenerator.TONE_PROP_ACK)
+    }
+
+    fun logGeofenceRemove(identifier: String) {
+        if (!enabled) return
+        emit("GEOFENCE REMOVE $identifier")
+    }
+
+    fun logGeofenceRemoveAll(count: Int) {
+        if (!enabled) return
+        emit("GEOFENCE REMOVE_ALL count=$count")
+    }
+
+    fun logGeofenceEvent(identifier: String, action: String) {
+        if (!enabled) return
+        emit("GEOFENCE ${action.uppercase()} $identifier")
+        playTone(ToneGenerator.TONE_SUP_CONFIRM)
+    }
+
+    /** Build a summary line for the dynamic notification. */
+    fun notificationText(lat: Double?, lng: Double?, effectiveDistanceFilter: Float? = null): String {
+        val coordsPart = if (lat != null && lng != null) {
+            "${"%.4f".format(lat)}, ${"%.4f".format(lng)}"
+        } else {
+            "waiting for GPS"
+        }
+        val distPart = if (effectiveDistanceFilter != null) " df:${effectiveDistanceFilter.toInt()}m" else ""
+        return "$coordsPart | L:$locationCount H:$heartbeatCount OK:$httpSuccessCount ERR:$httpErrorCount$distPart"
+    }
+
+    private fun emit(message: String) {
+        Log.d(TAG, message)
+        onDebug?.invoke(message)
+    }
+
+    private fun playTone(tone: Int) {
+        if (!soundsEnabled) return
+        try {
+            toneGenerator?.startTone(tone, 150)
+        } catch (_: Exception) {
+            // Ignore — sound is best-effort
+        }
+    }
+
+    fun release() {
+        toneGenerator?.release()
+        toneGenerator = null
+    }
+}

package/android/src/main/kotlin/dev/bglocation/core/geofence/BGLGeofenceBroadcastReceiver.kt

@@ -0,0 +1,93 @@
+package dev.bglocation.core.geofence
+
+import dev.bglocation.core.debug.BGLDebugLogger
+import dev.bglocation.core.location.BGLLocationHelpers
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import android.util.Log
+import com.google.android.gms.location.Geofence
+import com.google.android.gms.location.GeofencingEvent
+
+/**
+ * BroadcastReceiver for geofence transition events from [GeofencingClient].
+ *
+ * Registered in AndroidManifest.xml as a static receiver so it fires even when the app
+ * is not in the foreground. The receiver resolves the [BGLGeofenceManager] singleton
+ * from the companion object (set by [BackgroundLocationPlugin] on configure).
+ */
+class BGLGeofenceBroadcastReceiver : BroadcastReceiver() {
+
+    companion object {
+        private const val TAG = "BGLocation"
+
+        /**
+         * Singleton reference set by [BackgroundLocationPlugin.configure].
+         * The receiver uses this to look up extras and emit events.
+         */
+        @Volatile
+        var geofenceManager: BGLGeofenceManager? = null
+
+        /**
+         * Debug logger reference set by [BackgroundLocationPlugin.configure].
+         * Used to log geofence transition events with sounds.
+         */
+        @Volatile
+        var debugLogger: BGLDebugLogger? = null
+    }
+
+    override fun onReceive(context: Context, intent: Intent) {
+        if (intent.action != BGLGeofenceManager.ACTION_GEOFENCE_EVENT) return
+
+        val event = GeofencingEvent.fromIntent(intent)
+        if (event == null) {
+            Log.w(TAG, "BGLGeofenceBroadcastReceiver: null GeofencingEvent")
+            return
+        }
+        if (event.hasError()) {
+            Log.e(TAG, "BGLGeofenceBroadcastReceiver error: ${event.errorCode}")
+            return
+        }
+
+        val triggeringGeofences = event.triggeringGeofences ?: return
+        val transitionType = event.geofenceTransition
+
+        val action = when (transitionType) {
+            Geofence.GEOFENCE_TRANSITION_ENTER -> "enter"
+            Geofence.GEOFENCE_TRANSITION_EXIT -> "exit"
+            Geofence.GEOFENCE_TRANSITION_DWELL -> "dwell"
+            else -> {
+                Log.w(TAG, "BGLGeofenceBroadcastReceiver: unknown transition type $transitionType")
+                return
+            }
+        }
+
+        val triggeringLocation = event.triggeringLocation
+        val locationData = if (triggeringLocation != null) {
+            BGLLocationHelpers.mapLocation(triggeringLocation)
+        } else {
+            null
+        }
+
+        val manager = geofenceManager
+        if (manager == null) {
+            Log.w(TAG, "BGLGeofenceBroadcastReceiver: geofenceManager is null — plugin not configured. Dropping ${triggeringGeofences.size} event(s).")
+            return
+        }
+        val now = System.currentTimeMillis()
+
+        for (geofence in triggeringGeofences) {
+            val config = manager.findGeofence(geofence.requestId)
+            val eventData = BGLGeofenceEventData(
+                identifier = geofence.requestId,
+                action = action,
+                location = locationData,
+                extras = config?.extras,
+                timestamp = now
+            )
+            Log.d(TAG, "Geofence $action: ${geofence.requestId}")
+            debugLogger?.logGeofenceEvent(geofence.requestId, action)
+            manager.onGeofenceEvent?.invoke(eventData)
+        }
+    }
+}