@bglocation/capacitor 1.1.0

package/android/src/main/kotlin/dev/bglocation/core/location/BGLLocationForegroundService.kt

@@ -0,0 +1,289 @@
+package dev.bglocation.core.location
+
+import dev.bglocation.core.BGLLocationConfig
+import dev.bglocation.core.BGLLocationData
+import dev.bglocation.core.debug.BGLDebugLogger
+import dev.bglocation.core.http.BGLHttpResult
+import dev.bglocation.core.http.BGLHttpSender
+import dev.bglocation.core.http.BGLLocationBuffer
+import dev.bglocation.core.notification.BGLNotificationHelper
+import android.annotation.SuppressLint
+import android.app.Service
+import android.content.Intent
+import android.content.pm.ServiceInfo
+import android.os.Binder
+import android.os.Build
+import android.os.IBinder
+import android.util.Log
+import com.google.android.gms.location.FusedLocationProviderClient
+import com.google.android.gms.location.LocationCallback
+import com.google.android.gms.location.LocationRequest
+import com.google.android.gms.location.LocationResult
+import com.google.android.gms.location.LocationServices
+import com.google.android.gms.location.Priority
+
+/**
+ * Foreground Service that keeps GPS running in the background.
+ *
+ * Android 8+ (API 26) requires a Foreground Service with a persistent notification
+ * to maintain background execution. Android 14+ also requires `foregroundServiceType="location"`.
+ *
+ * Dependencies are exposed as `internal var` for testability (Android Service
+ * does not support constructor injection).
+ */
+class BGLLocationForegroundService : Service() {
+
+    companion object {
+        private const val TAG = "BGLocation"
+    }
+
+    inner class LocalBinder : Binder() {
+        fun getService(): BGLLocationForegroundService = this@BGLLocationForegroundService
+    }
+
+    private val binder = LocalBinder()
+
+    // --- Injected dependencies (var for bridge/testing access) ---
+    internal var fusedClient: FusedLocationProviderClient? = null
+    internal var httpSender: BGLHttpSender? = null
+    internal var notificationHelper: BGLNotificationHelper? = null
+    internal var heartbeatTimer: BGLHeartbeatTimer? = null
+    internal var locationBuffer: BGLLocationBuffer? = null
+    var debug: BGLDebugLogger = BGLDebugLogger()
+
+    private var config = BGLLocationConfig()
+    @Volatile
+    private var lastLocation: BGLLocationData? = null
+    var adaptiveFilter: BGLAdaptiveFilter? = null
+
+    var isTracking = false
+        private set
+
+    // Callbacks — set by BackgroundLocationPlugin
+    var onLocation: ((BGLLocationData) -> Unit)? = null
+    var onProviderChange: ((Boolean) -> Unit)? = null
+    var onHeartbeat: ((BGLLocationData?) -> Unit)? = null
+    var onHttp: ((BGLHttpResult) -> Unit)? = null
+    var onMockLocation: ((BGLLocationData) -> Unit)? = null
+    @Volatile
+    private var mockLocationEmitted = false
+
+    private val locationCallback = object : LocationCallback() {
+        override fun onLocationResult(result: LocationResult) {
+            val location = result.lastLocation ?: return
+            val data = BGLLocationHelpers.mapLocation(location)
+            lastLocation = data
+            onLocation?.invoke(data)
+
+            // C.3: Emit mock location warning once per tracking session
+            if (data.isMock && !mockLocationEmitted) {
+                mockLocationEmitted = true
+                onMockLocation?.invoke(data)
+            }
+
+            // Adaptive distance filter: update EMA and reconfigure if needed
+            val filter = adaptiveFilter
+            if (filter != null) {
+                val shouldReconfigure = filter.update(data.speed)
+                if (shouldReconfigure) {
+                    reconfigureLocationRequest()
+                    debug.logMessage("Auto distance filter: ${filter.effectiveDistanceFilter.toInt()}m (speed: ${"%.1f".format(data.speed)}m/s)")
+                }
+            }
+
+            debug.logLocation(
+                lat = data.latitude,
+                lng = data.longitude,
+                accuracy = data.accuracy,
+                speed = data.speed,
+                isMoving = data.isMoving
+            )
+            updateDebugNotification()
+
+            httpSender?.sendLocation(data) { httpResult ->
+                debug.logHttp(
+                    statusCode = httpResult.statusCode,
+                    success = httpResult.success,
+                    error = httpResult.error
+                )
+                updateDebugNotification()
+                onHttp?.invoke(httpResult)
+            }
+        }
+    }
+
+    override fun onCreate() {
+        super.onCreate()
+        if (fusedClient == null) {
+            fusedClient = LocationServices.getFusedLocationProviderClient(this)
+        }
+        if (httpSender == null) {
+            httpSender = BGLHttpSender()
+        }
+        httpSender?.onFlushProgress = { result ->
+            onHttp?.invoke(result)
+        }
+        if (heartbeatTimer == null) {
+            heartbeatTimer = BGLHeartbeatTimer()
+        }
+        if (notificationHelper == null) {
+            notificationHelper = BGLNotificationHelper(this)
+        }
+        val helper = notificationHelper!!
+        helper.createChannel()
+        val notification = helper.buildNotification(config.notification)
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
+            startForeground(BGLNotificationHelper.NOTIFICATION_ID, notification, ServiceInfo.FOREGROUND_SERVICE_TYPE_LOCATION)
+        } else {
+            startForeground(BGLNotificationHelper.NOTIFICATION_ID, notification)
+        }
+        Log.d(TAG, "BGLLocationForegroundService created")
+    }
+
+    override fun onBind(intent: Intent?): IBinder = binder
+
+    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
+        return START_STICKY
+    }
+
+    fun configure(newConfig: BGLLocationConfig) {
+        config = newConfig
+        httpSender?.configure(newConfig.http)
+
+        // Initialize adaptive filter if in auto mode
+        if (newConfig.distanceFilterMode == "auto") {
+            val autoConfig = newConfig.autoDistanceFilter ?: BGLAutoDistanceFilterConfig()
+            adaptiveFilter = BGLAdaptiveFilter(autoConfig)
+        } else {
+            adaptiveFilter = null
+        }
+
+        // Set up offline buffer if HTTP + buffer config is provided
+        if (newConfig.http != null && newConfig.http.buffer != null) {
+            if (locationBuffer == null) {
+                locationBuffer = BGLLocationBuffer(this)
+            }
+            locationBuffer?.configure(newConfig.http.buffer)
+            locationBuffer?.onOverflow = { dropped ->
+                debug.logMessage("BUFFER_OVERFLOW dropped=$dropped maxSize=${newConfig.http.buffer?.maxSize ?: 1000}")
+            }
+            httpSender?.setBuffer(locationBuffer)
+        } else {
+            httpSender?.setBuffer(null)
+            locationBuffer?.close()
+            locationBuffer = null
+        }
+
+        debug.configure(debug = newConfig.debug, debugSounds = newConfig.debugSounds)
+        debug.logConfigure(
+            distanceFilter = newConfig.distanceFilter,
+            heartbeat = newConfig.heartbeatInterval,
+            httpUrl = newConfig.http?.url
+        )
+        notificationHelper?.updateNotification(config.notification)
+    }
+
+    @SuppressLint("MissingPermission")
+    fun startTracking() {
+        if (isTracking) return
+        mockLocationEmitted = false
+
+        val initialDistanceFilter = adaptiveFilter?.effectiveDistanceFilter ?: config.distanceFilter
+
+        val request = buildLocationRequest(initialDistanceFilter)
+
+        fusedClient?.requestLocationUpdates(request, locationCallback, mainLooper)
+        heartbeatTimer?.start(config.heartbeatInterval) {
+            onHeartbeat?.invoke(lastLocation)
+            debug.logHeartbeat(hasLocation = lastLocation != null)
+            updateDebugNotification()
+        }
+        isTracking = true
+        debug.logStart()
+        val modeInfo = if (adaptiveFilter != null) "auto (initial=${initialDistanceFilter.toInt()}m)" else "${config.distanceFilter}m"
+        Log.d(TAG, "Location tracking started — interval=${config.locationUpdateInterval}ms, distance=$modeInfo")
+    }
+
+    fun stopTracking() {
+        if (!isTracking) return
+
+        fusedClient?.removeLocationUpdates(locationCallback)
+        heartbeatTimer?.stop()
+        adaptiveFilter?.reset()
+        isTracking = false
+        debug.logStop()
+        Log.d(TAG, "Location tracking stopped")
+    }
+
+    /**
+     * Reconfigure the FusedLocationProviderClient with a new distance filter.
+     * Called by the adaptive filter when the effective distance changes significantly.
+     */
+    @SuppressLint("MissingPermission")
+    private fun reconfigureLocationRequest() {
+        if (!isTracking) return
+        val filter = adaptiveFilter ?: return
+
+        fusedClient?.removeLocationUpdates(locationCallback)
+
+        val request = buildLocationRequest(filter.effectiveDistanceFilter)
+
+        fusedClient?.requestLocationUpdates(request, locationCallback, mainLooper)
+        Log.d(TAG, "Adaptive filter reconfigured — new distance=${filter.effectiveDistanceFilter.toInt()}m")
+    }
+
+    private fun buildLocationRequest(distanceFilter: Float): LocationRequest {
+        val priority = when (config.desiredAccuracy) {
+            "high" -> Priority.PRIORITY_HIGH_ACCURACY
+            "balanced" -> Priority.PRIORITY_BALANCED_POWER_ACCURACY
+            "low" -> Priority.PRIORITY_LOW_POWER
+            else -> {
+                Log.w(TAG, "Unknown desiredAccuracy '${config.desiredAccuracy}', falling back to 'high'")
+                Priority.PRIORITY_HIGH_ACCURACY
+            }
+        }
+        return LocationRequest.Builder(priority, config.locationUpdateInterval)
+            .setMinUpdateDistanceMeters(distanceFilter)
+            .setMinUpdateIntervalMillis(config.fastestLocationUpdateInterval)
+            .build()
+    }
+
+    @SuppressLint("MissingPermission")
+    fun getCurrentPosition(callback: (BGLLocationData?) -> Unit) {
+        val client = fusedClient
+        if (client == null) {
+            callback(lastLocation)
+            return
+        }
+        client.getCurrentLocation(Priority.PRIORITY_HIGH_ACCURACY, null)
+            .addOnSuccessListener { location ->
+                if (location != null) {
+                    callback(BGLLocationHelpers.mapLocation(location))
+                } else {
+                    callback(lastLocation)
+                }
+            }
+            .addOnFailureListener {
+                callback(lastLocation)
+            }
+    }
+
+    override fun onDestroy() {
+        stopTracking()
+        httpSender?.shutdown()
+        debug.release()
+        Log.d(TAG, "BGLLocationForegroundService destroyed")
+        super.onDestroy()
+    }
+
+    private fun updateDebugNotification() {
+        if (!debug.enabled) return
+
+        val text = debug.notificationText(
+            lat = lastLocation?.latitude,
+            lng = lastLocation?.longitude,
+            effectiveDistanceFilter = adaptiveFilter?.effectiveDistanceFilter
+        )
+        notificationHelper?.updateDebugNotification(config.notification, text)
+    }
+}

package/android/src/main/kotlin/dev/bglocation/core/location/BGLLocationHelpers.kt

@@ -0,0 +1,72 @@
+package dev.bglocation.core.location
+
+import android.location.Location
+import android.os.Build
+import dev.bglocation.core.BGLLocationData
+import org.json.JSONObject
+
+/**
+ * Pure helper functions for location data transformation.
+ * Centralizes field mapping to avoid duplication across plugin, service, and HTTP layer.
+ */
+object BGLLocationHelpers {
+
+    /** Speed threshold (m/s) above which the device is considered moving. */
+    const val MOTION_SPEED_THRESHOLD = 0.5f
+
+    /**
+     * Map an Android [Location] to a normalized [BGLLocationData].
+     */
+    internal fun mapLocation(location: Location): BGLLocationData {
+        return BGLLocationData(
+            latitude = location.latitude,
+            longitude = location.longitude,
+            accuracy = location.accuracy,
+            speed = maxOf(location.speed, 0f),
+            heading = if (location.hasBearing()) location.bearing else -1f,
+            altitude = location.altitude,
+            timestamp = location.time,
+            isMoving = location.speed > MOTION_SPEED_THRESHOLD,
+            isMock = isMockLocation(location)
+        )
+    }
+
+    /**
+     * Detect whether a [Location] was generated by a mock/test provider.
+     */
+    @Suppress("DEPRECATION")
+    internal fun isMockLocation(location: Location): Boolean {
+        return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
+            location.isMock
+        } else {
+            location.isFromMockProvider
+        }
+    }
+
+    /**
+     * Convert [BGLLocationData] to a [JSONObject] for event emission.
+     * Single source of truth for the 9 location fields exposed to JS.
+     */
+    fun toJSONObject(location: BGLLocationData): JSONObject {
+        return JSONObject().apply {
+            put("latitude", location.latitude)
+            put("longitude", location.longitude)
+            put("accuracy", location.accuracy.toDouble())
+            put("speed", location.speed.toDouble())
+            put("heading", location.heading.toDouble())
+            put("altitude", location.altitude)
+            put("timestamp", location.timestamp)
+            put("isMoving", location.isMoving)
+            put("isMock", location.isMock)
+        }
+    }
+
+    /**
+     * Build the HTTP POST body wrapping location in a `{ "location": { ... } }` envelope.
+     */
+    internal fun buildLocationBody(location: BGLLocationData): JSONObject {
+        return JSONObject().apply {
+            put("location", toJSONObject(location))
+        }
+    }
+}

package/android/src/main/kotlin/dev/bglocation/core/location/BGLPermissionManager.kt

@@ -0,0 +1,99 @@
+package dev.bglocation.core.location
+
+import android.Manifest
+import android.app.Activity
+import android.content.Context
+import android.content.pm.PackageManager
+import android.os.Build
+import android.util.Log
+import androidx.core.app.ActivityCompat
+import org.json.JSONObject
+
+/**
+ * Handles permission checking and rationale emission logic.
+ */
+class BGLPermissionManager {
+
+    companion object {
+        private const val TAG = "BGLocation"
+    }
+
+    /**
+     * Build permission status from current permission state.
+     */
+    fun buildPermissionStatus(
+        context: Context,
+        activity: Activity?,
+        capPermissionState: String?
+    ): JSONObject {
+        val fineGranted = ActivityCompat.checkSelfPermission(
+            context, Manifest.permission.ACCESS_FINE_LOCATION
+        ) == PackageManager.PERMISSION_GRANTED
+
+        val bgGranted = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
+            ActivityCompat.checkSelfPermission(
+                context, Manifest.permission.ACCESS_BACKGROUND_LOCATION
+            ) == PackageManager.PERMISSION_GRANTED
+        } else {
+            fineGranted
+        }
+
+        val locationState = when {
+            fineGranted -> "granted"
+            activity != null && ActivityCompat.shouldShowRequestPermissionRationale(
+                activity, Manifest.permission.ACCESS_FINE_LOCATION
+            ) -> "prompt"
+            else -> {
+                if (capPermissionState == "denied") "denied" else "prompt"
+            }
+        }
+
+        val bgState = when {
+            bgGranted -> "granted"
+            !fineGranted -> locationState
+            else -> "prompt"
+        }
+
+        return JSONObject().apply {
+            put("location", locationState)
+            put("backgroundLocation", bgState)
+        }
+    }
+
+    /**
+     * Build rationale for background location permission on Android 11+.
+     * Returns the rationale data if it should be emitted, or null if not applicable.
+     */
+    fun buildBackgroundRationale(
+        context: Context,
+        activity: Activity?,
+        permissions: List<String>
+    ): JSONObject? {
+        val requestingBackground = permissions.contains("backgroundLocation")
+        if (!requestingBackground || Build.VERSION.SDK_INT < Build.VERSION_CODES.R) return null
+
+        val fineGranted = ActivityCompat.checkSelfPermission(
+            context, Manifest.permission.ACCESS_FINE_LOCATION
+        ) == PackageManager.PERMISSION_GRANTED
+
+        val bgGranted = ActivityCompat.checkSelfPermission(
+            context, Manifest.permission.ACCESS_BACKGROUND_LOCATION
+        ) == PackageManager.PERMISSION_GRANTED
+
+        if (!fineGranted || bgGranted) return null
+
+        val shouldShow = activity?.let {
+            ActivityCompat.shouldShowRequestPermissionRationale(
+                it, Manifest.permission.ACCESS_BACKGROUND_LOCATION
+            )
+        } ?: false
+
+        Log.d(TAG, "Emitted onPermissionRationale before background location request (shouldShowRationale=$shouldShow)")
+
+        return JSONObject().apply {
+            put("permission", "backgroundLocation")
+            put("shouldShowRationale", shouldShow)
+            put("message", "Background location permission is required for continuous tracking. On Android 11+, please select \"Allow all the time\" in the app's location settings.")
+        }
+    }
+}

package/android/src/main/kotlin/dev/bglocation/core/notification/BGLNotificationHelper.kt

@@ -0,0 +1,77 @@
+package dev.bglocation.core.notification
+
+import dev.bglocation.core.BGLNotificationConfig
+import android.app.Notification
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.content.Context
+import androidx.core.app.NotificationCompat
+
+/**
+ * Manages the foreground service notification for background location tracking.
+ *
+ * Extracted from BGLLocationForegroundService (SRP) — handles channel creation,
+ * notification building, and debug info display.
+ */
+class BGLNotificationHelper(private val context: Context) {
+
+    companion object {
+        const val CHANNEL_ID = "bgl_location_channel"
+        const val NOTIFICATION_ID = 1001
+    }
+
+    fun createChannel() {
+        val channel = NotificationChannel(
+            CHANNEL_ID,
+            "Location Tracking",
+            NotificationManager.IMPORTANCE_LOW
+        ).apply {
+            description = "Background location tracking for tour"
+        }
+        val manager = context.getSystemService(NotificationManager::class.java)
+        manager.createNotificationChannel(channel)
+    }
+
+    fun buildNotification(config: BGLNotificationConfig): Notification {
+        return baseBuilder()
+            .setContentTitle(config.title)
+            .setContentText(config.text)
+            .build()
+    }
+
+    fun updateNotification(config: BGLNotificationConfig) {
+        val manager = context.getSystemService(NotificationManager::class.java) ?: return
+        manager.notify(NOTIFICATION_ID, buildNotification(config))
+    }
+
+    fun updateDebugNotification(config: BGLNotificationConfig, debugText: String) {
+        val notification = baseBuilder()
+            .setContentTitle("${config.title} [DEBUG]")
+            .setContentText(debugText)
+            .build()
+        val manager = context.getSystemService(NotificationManager::class.java)
+        manager.notify(NOTIFICATION_ID, notification)
+    }
+
+    /**
+     * Resolve a valid notification small icon.
+     *
+     * Adaptive (mipmap) launcher icons cannot be used as notification small icons —
+     * they render as blank squares on most Android versions.
+     * Try a dedicated drawable first, then fall back to a system icon.
+     */
+    internal fun getNotificationIcon(): Int {
+        val custom = context.resources.getIdentifier(
+            "ic_notification", "drawable", context.packageName
+        )
+        if (custom != 0) return custom
+        return android.R.drawable.ic_menu_mylocation
+    }
+
+    private fun baseBuilder(): NotificationCompat.Builder {
+        return NotificationCompat.Builder(context, CHANNEL_ID)
+            .setSmallIcon(getNotificationIcon())
+            .setOngoing(true)
+            .setForegroundServiceBehavior(NotificationCompat.FOREGROUND_SERVICE_IMMEDIATE)
+    }
+}