@kafitra/react-native-live-tracking 0.1.0

package/android/src/main/java/com/livetracking/permissions/PermissionHandler.kt

@@ -0,0 +1,145 @@
+package com.livetracking.permissions
+
+import android.Manifest
+import android.content.Context
+import android.content.pm.PackageManager
+import android.location.LocationManager
+import android.os.Build
+import androidx.core.content.ContextCompat
+
+/**
+ * Represents the result of a permission check.
+ */
+sealed class PermissionResult {
+    /** All required permissions are granted. */
+    object Granted : PermissionResult()
+
+    /** One or more permissions are denied or a required service is disabled. */
+    data class Denied(
+        val errorCode: String,
+        val message: String
+    ) : PermissionResult()
+}
+
+/**
+ * Handles location permission checks for the LiveTracking library.
+ * Provides clear error codes when permissions are denied or GPS is disabled.
+ *
+ * Validates: Requirements 10.1, 10.2
+ */
+class PermissionHandler {
+
+    companion object {
+        const val ERROR_PERMISSION_DENIED = "PERMISSION_DENIED"
+        const val ERROR_GPS_DISABLED = "GPS_DISABLED"
+    }
+
+    /**
+     * Checks if fine and coarse location permissions are granted.
+     *
+     * @param context Android context used for permission checks
+     * @return [PermissionResult.Granted] if both ACCESS_FINE_LOCATION and ACCESS_COARSE_LOCATION
+     *         are granted, [PermissionResult.Denied] otherwise with error code PERMISSION_DENIED
+     */
+    fun checkLocationPermissions(context: Context): PermissionResult {
+        val fineLocationGranted = ContextCompat.checkSelfPermission(
+            context,
+            Manifest.permission.ACCESS_FINE_LOCATION
+        ) == PackageManager.PERMISSION_GRANTED
+
+        val coarseLocationGranted = ContextCompat.checkSelfPermission(
+            context,
+            Manifest.permission.ACCESS_COARSE_LOCATION
+        ) == PackageManager.PERMISSION_GRANTED
+
+        return if (fineLocationGranted && coarseLocationGranted) {
+            PermissionResult.Granted
+        } else {
+            val deniedPermissions = mutableListOf<String>()
+            if (!fineLocationGranted) deniedPermissions.add("ACCESS_FINE_LOCATION")
+            if (!coarseLocationGranted) deniedPermissions.add("ACCESS_COARSE_LOCATION")
+
+            PermissionResult.Denied(
+                errorCode = ERROR_PERMISSION_DENIED,
+                message = "Location permissions denied: ${deniedPermissions.joinToString(", ")}. " +
+                    "Please grant location permissions to enable tracking."
+            )
+        }
+    }
+
+    /**
+     * Checks if background location permission is granted (Android 10+ / API 29+).
+     * On devices below Android 10, background location is implicitly granted
+     * when foreground location is granted.
+     *
+     * @param context Android context used for permission checks
+     * @return [PermissionResult.Granted] if background location is available,
+     *         [PermissionResult.Denied] otherwise with error code PERMISSION_DENIED
+     */
+    fun checkBackgroundLocationPermission(context: Context): PermissionResult {
+        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.Q) {
+            // Below Android 10, background location is granted with foreground location
+            return PermissionResult.Granted
+        }
+
+        val backgroundLocationGranted = ContextCompat.checkSelfPermission(
+            context,
+            Manifest.permission.ACCESS_BACKGROUND_LOCATION
+        ) == PackageManager.PERMISSION_GRANTED
+
+        return if (backgroundLocationGranted) {
+            PermissionResult.Granted
+        } else {
+            PermissionResult.Denied(
+                errorCode = ERROR_PERMISSION_DENIED,
+                message = "Background location permission denied: ACCESS_BACKGROUND_LOCATION. " +
+                    "Please grant 'Allow all the time' location permission for background tracking."
+            )
+        }
+    }
+
+    /**
+     * Checks if GPS/location services are enabled on the device.
+     *
+     * @param context Android context used to access LocationManager
+     * @return true if GPS provider is enabled, false otherwise
+     */
+    fun isGpsEnabled(context: Context): Boolean {
+        val locationManager = context.getSystemService(Context.LOCATION_SERVICE) as? LocationManager
+            ?: return false
+        return locationManager.isProviderEnabled(LocationManager.GPS_PROVIDER)
+    }
+
+    /**
+     * Performs a comprehensive check of all permissions and services required for tracking.
+     * Checks location permissions, background location, and GPS status in order.
+     *
+     * @param context Android context
+     * @return [PermissionResult.Granted] if all checks pass, or the first
+     *         [PermissionResult.Denied] encountered
+     */
+    fun checkAllTrackingRequirements(context: Context): PermissionResult {
+        // Check foreground location permissions first
+        val locationResult = checkLocationPermissions(context)
+        if (locationResult is PermissionResult.Denied) {
+            return locationResult
+        }
+
+        // Check background location permission
+        val backgroundResult = checkBackgroundLocationPermission(context)
+        if (backgroundResult is PermissionResult.Denied) {
+            return backgroundResult
+        }
+
+        // Check GPS is enabled
+        if (!isGpsEnabled(context)) {
+            return PermissionResult.Denied(
+                errorCode = ERROR_GPS_DISABLED,
+                message = "GPS/Location services are disabled. " +
+                    "Please enable location services in device settings."
+            )
+        }
+
+        return PermissionResult.Granted
+    }
+}

package/android/src/main/java/com/livetracking/queue/QueueEngine.kt

@@ -0,0 +1,167 @@
+package com.livetracking.queue
+
+import android.content.Context
+import com.livetracking.sync.OfflineQueueProvider
+import java.util.UUID
+import java.util.concurrent.Callable
+import java.util.concurrent.ExecutorService
+import java.util.concurrent.Executors
+import java.util.concurrent.Future
+
+/**
+ * QueueEngine manages the offline location queue using SQLite.
+ * All database operations run on a dedicated background thread.
+ *
+ * Implements [OfflineQueueProvider] to provide per-target offline queue
+ * operations used by [TargetHandler] for target-scoped persistence.
+ */
+class QueueEngine(context: Context) : OfflineQueueProvider {
+
+    private val db: TrackingDatabase = TrackingDatabase.getInstance(context)
+    private val executor: ExecutorService = Executors.newSingleThreadExecutor()
+
+    // --- Legacy methods (backward-compatible, operate without target_path filter) ---
+
+    fun enqueue(
+        latitude: Double,
+        longitude: Double,
+        timestamp: Long,
+        accuracy: Float,
+        speed: Float?,
+        altitude: Double?,
+        bearing: Float?
+    ): Future<Unit> {
+        return executor.submit(Callable {
+            val location = QueuedLocation(
+                id = UUID.randomUUID().toString(),
+                latitude = latitude,
+                longitude = longitude,
+                timestamp = timestamp,
+                accuracy = accuracy,
+                speed = speed,
+                altitude = altitude,
+                bearing = bearing,
+                createdAt = System.currentTimeMillis()
+            )
+            db.insert(location)
+        })
+    }
+
+    fun dequeueBatch(size: Int): Future<List<QueuedLocation>> {
+        return executor.submit(Callable {
+            db.getOldestBatch(size)
+        })
+    }
+
+    fun removeBatch(ids: List<String>): Future<Unit> {
+        return executor.submit(Callable {
+            db.deleteByIds(ids)
+        })
+    }
+
+    fun count(): Future<Int> {
+        return executor.submit(Callable {
+            db.getCount()
+        })
+    }
+
+    // --- Per-target methods (OfflineQueueProvider implementation) ---
+
+    /**
+     * Enqueue a location data point for a specific target path.
+     * Delegates to [TrackingDatabase.insertForTarget] which enforces the
+     * 10,000 data point cap per target with oldest-eviction.
+     */
+    override fun enqueueForTarget(
+        targetPath: String,
+        latitude: Double,
+        longitude: Double,
+        timestamp: Long,
+        accuracy: Float,
+        speed: Float?,
+        altitude: Double?,
+        bearing: Float?
+    ): Future<Unit> {
+        return executor.submit(Callable {
+            val location = QueuedLocation(
+                id = UUID.randomUUID().toString(),
+                latitude = latitude,
+                longitude = longitude,
+                timestamp = timestamp,
+                accuracy = accuracy,
+                speed = speed,
+                altitude = altitude,
+                bearing = bearing,
+                createdAt = System.currentTimeMillis()
+            )
+            db.insertForTarget(location, targetPath)
+        })
+    }
+
+    /**
+     * Dequeue the oldest batch of queued locations for a specific target path.
+     * Results are ordered chronologically (oldest first).
+     *
+     * @param targetPath The target path to dequeue from
+     * @param size Maximum number of locations to dequeue
+     * @return Future resolving to the list of queued locations
+     */
+    override fun dequeueBatchForTarget(targetPath: String, size: Int): Future<List<QueuedLocation>> {
+        return executor.submit(Callable {
+            db.getOldestBatchForTarget(targetPath, size)
+        })
+    }
+
+    /**
+     * Get the count of queued locations for a specific target path.
+     *
+     * @param targetPath The target path to count
+     * @return Future resolving to the count of queued locations
+     */
+    override fun countForTarget(targetPath: String): Future<Int> {
+        return executor.submit(Callable {
+            db.getCountForTarget(targetPath)
+        })
+    }
+
+    /**
+     * Get the count of queued locations grouped by target path.
+     *
+     * @return Future resolving to a map of target_path → count
+     */
+    fun countsByTarget(): Future<Map<String, Int>> {
+        return executor.submit(Callable {
+            db.getCountsByTarget()
+        })
+    }
+
+    /**
+     * Evict the oldest queued location for a specific target path.
+     * Used to enforce the 10,000 data point cap per target.
+     *
+     * @param targetPath The target path to evict from
+     * @return Future resolving when eviction is complete
+     */
+    override fun evictOldestForTarget(targetPath: String): Future<Unit> {
+        return executor.submit(Callable {
+            db.evictOldestForTarget(targetPath)
+        })
+    }
+
+    /**
+     * Remove a batch of queued locations by their IDs.
+     * Used after successful write confirmation during offline queue flush.
+     *
+     * @param ids List of location IDs to remove
+     * @return Future resolving when removal is complete
+     */
+    override fun removeBatchForTarget(ids: List<String>): Future<Unit> {
+        return executor.submit(Callable {
+            db.deleteByIds(ids)
+        })
+    }
+
+    fun shutdown() {
+        executor.shutdown()
+    }
+}

package/android/src/main/java/com/livetracking/queue/QueuedLocation.kt

@@ -0,0 +1,16 @@
+package com.livetracking.queue
+
+/**
+ * Data class representing a queued location entry.
+ */
+data class QueuedLocation(
+    val id: String,
+    val latitude: Double,
+    val longitude: Double,
+    val timestamp: Long,
+    val accuracy: Float,
+    val speed: Float?,
+    val altitude: Double?,
+    val bearing: Float?,
+    val createdAt: Long
+)

package/android/src/main/java/com/livetracking/queue/TrackingDatabase.kt

@@ -0,0 +1,239 @@
+package com.livetracking.queue
+
+import android.content.ContentValues
+import android.content.Context
+import android.database.sqlite.SQLiteDatabase
+import android.database.sqlite.SQLiteOpenHelper
+
+/**
+ * SQLite database helper for the location queue.
+ * Supports per-target offline queues with a target_path column.
+ * Replaces Room to avoid kapt/ksp annotation processor dependency issues.
+ */
+class TrackingDatabase(context: Context) : SQLiteOpenHelper(
+    context, DATABASE_NAME, null, DATABASE_VERSION
+) {
+    companion object {
+        private const val DATABASE_NAME = "live_tracking_db"
+        private const val DATABASE_VERSION = 2
+        private const val TABLE_NAME = "queued_locations"
+        private const val INDEX_NAME = "idx_queued_target_path"
+
+        /**
+         * Maximum number of queued data points per target.
+         * When this limit is reached, the oldest data point is evicted.
+         */
+        const val MAX_QUEUE_SIZE_PER_TARGET = 10_000
+
+        @Volatile
+        private var INSTANCE: TrackingDatabase? = null
+
+        fun getInstance(context: Context): TrackingDatabase {
+            return INSTANCE ?: synchronized(this) {
+                INSTANCE ?: TrackingDatabase(context.applicationContext).also { INSTANCE = it }
+            }
+        }
+    }
+
+    override fun onCreate(db: SQLiteDatabase) {
+        db.execSQL("""
+            CREATE TABLE $TABLE_NAME (
+                id TEXT PRIMARY KEY,
+                latitude REAL NOT NULL,
+                longitude REAL NOT NULL,
+                timestamp INTEGER NOT NULL,
+                accuracy REAL NOT NULL,
+                speed REAL,
+                altitude REAL,
+                bearing REAL,
+                createdAt INTEGER NOT NULL,
+                target_path TEXT NOT NULL DEFAULT ''
+            )
+        """.trimIndent())
+        db.execSQL(
+            "CREATE INDEX $INDEX_NAME ON $TABLE_NAME(target_path, createdAt ASC)"
+        )
+    }
+
+    override fun onUpgrade(db: SQLiteDatabase, oldVersion: Int, newVersion: Int) {
+        if (oldVersion < 2) {
+            // Migration v1 → v2: add target_path column with default empty string
+            db.execSQL(
+                "ALTER TABLE $TABLE_NAME ADD COLUMN target_path TEXT NOT NULL DEFAULT ''"
+            )
+            db.execSQL(
+                "CREATE INDEX $INDEX_NAME ON $TABLE_NAME(target_path, createdAt ASC)"
+            )
+        }
+    }
+
+    // --- Legacy methods (backward-compatible, operate without target_path filter) ---
+
+    fun insert(location: QueuedLocation) {
+        val values = ContentValues().apply {
+            put("id", location.id)
+            put("latitude", location.latitude)
+            put("longitude", location.longitude)
+            put("timestamp", location.timestamp)
+            put("accuracy", location.accuracy)
+            put("speed", location.speed)
+            put("altitude", location.altitude)
+            put("bearing", location.bearing)
+            put("createdAt", location.createdAt)
+        }
+        writableDatabase.insert(TABLE_NAME, null, values)
+    }
+
+    fun getOldestBatch(limit: Int): List<QueuedLocation> {
+        val locations = mutableListOf<QueuedLocation>()
+        val cursor = readableDatabase.query(
+            TABLE_NAME, null, null, null, null, null,
+            "createdAt ASC", limit.toString()
+        )
+        cursor.use {
+            while (it.moveToNext()) {
+                locations.add(cursorToQueuedLocation(it))
+            }
+        }
+        return locations
+    }
+
+    fun deleteByIds(ids: List<String>) {
+        if (ids.isEmpty()) return
+        val placeholders = ids.joinToString(",") { "?" }
+        writableDatabase.delete(TABLE_NAME, "id IN ($placeholders)", ids.toTypedArray())
+    }
+
+    fun getCount(): Int {
+        val cursor = readableDatabase.rawQuery("SELECT COUNT(*) FROM $TABLE_NAME", null)
+        cursor.use {
+            it.moveToFirst()
+            return it.getInt(0)
+        }
+    }
+
+    // --- Per-target methods ---
+
+    /**
+     * Insert a location for a specific target path.
+     * Enforces the 10,000 data point cap per target by evicting the oldest
+     * entry when the limit is reached.
+     */
+    fun insertForTarget(location: QueuedLocation, targetPath: String) {
+        val db = writableDatabase
+        // Enforce cap: evict oldest if at limit
+        val currentCount = getCountForTarget(targetPath)
+        if (currentCount >= MAX_QUEUE_SIZE_PER_TARGET) {
+            evictOldestForTarget(targetPath)
+        }
+
+        val values = ContentValues().apply {
+            put("id", location.id)
+            put("latitude", location.latitude)
+            put("longitude", location.longitude)
+            put("timestamp", location.timestamp)
+            put("accuracy", location.accuracy)
+            put("speed", location.speed)
+            put("altitude", location.altitude)
+            put("bearing", location.bearing)
+            put("createdAt", location.createdAt)
+            put("target_path", targetPath)
+        }
+        db.insert(TABLE_NAME, null, values)
+    }
+
+    /**
+     * Get the oldest batch of queued locations for a specific target path.
+     * Results are ordered by createdAt ASC (oldest first).
+     */
+    fun getOldestBatchForTarget(targetPath: String, limit: Int): List<QueuedLocation> {
+        val locations = mutableListOf<QueuedLocation>()
+        val cursor = readableDatabase.query(
+            TABLE_NAME,
+            null,
+            "target_path = ?",
+            arrayOf(targetPath),
+            null,
+            null,
+            "createdAt ASC",
+            limit.toString()
+        )
+        cursor.use {
+            while (it.moveToNext()) {
+                locations.add(cursorToQueuedLocation(it))
+            }
+        }
+        return locations
+    }
+
+    /**
+     * Get the count of queued locations for a specific target path.
+     */
+    fun getCountForTarget(targetPath: String): Int {
+        val cursor = readableDatabase.rawQuery(
+            "SELECT COUNT(*) FROM $TABLE_NAME WHERE target_path = ?",
+            arrayOf(targetPath)
+        )
+        cursor.use {
+            it.moveToFirst()
+            return it.getInt(0)
+        }
+    }
+
+    /**
+     * Get the count of queued locations grouped by target path.
+     * Returns a map of target_path → count.
+     */
+    fun getCountsByTarget(): Map<String, Int> {
+        val counts = mutableMapOf<String, Int>()
+        val cursor = readableDatabase.rawQuery(
+            "SELECT target_path, COUNT(*) FROM $TABLE_NAME GROUP BY target_path",
+            null
+        )
+        cursor.use {
+            while (it.moveToNext()) {
+                val path = it.getString(0)
+                val count = it.getInt(1)
+                counts[path] = count
+            }
+        }
+        return counts
+    }
+
+    /**
+     * Evict the oldest queued location for a specific target path.
+     * Used to enforce the 10,000 data point cap per target.
+     */
+    fun evictOldestForTarget(targetPath: String) {
+        writableDatabase.execSQL(
+            """
+            DELETE FROM $TABLE_NAME WHERE id = (
+                SELECT id FROM $TABLE_NAME
+                WHERE target_path = ?
+                ORDER BY createdAt ASC
+                LIMIT 1
+            )
+            """.trimIndent(),
+            arrayOf(targetPath)
+        )
+    }
+
+    // --- Private helpers ---
+
+    private fun cursorToQueuedLocation(cursor: android.database.Cursor): QueuedLocation {
+        return QueuedLocation(
+            id = cursor.getString(cursor.getColumnIndexOrThrow("id")),
+            latitude = cursor.getDouble(cursor.getColumnIndexOrThrow("latitude")),
+            longitude = cursor.getDouble(cursor.getColumnIndexOrThrow("longitude")),
+            timestamp = cursor.getLong(cursor.getColumnIndexOrThrow("timestamp")),
+            accuracy = cursor.getFloat(cursor.getColumnIndexOrThrow("accuracy")),
+            speed = if (cursor.isNull(cursor.getColumnIndexOrThrow("speed"))) null
+                else cursor.getFloat(cursor.getColumnIndexOrThrow("speed")),
+            altitude = if (cursor.isNull(cursor.getColumnIndexOrThrow("altitude"))) null
+                else cursor.getDouble(cursor.getColumnIndexOrThrow("altitude")),
+            bearing = if (cursor.isNull(cursor.getColumnIndexOrThrow("bearing"))) null
+                else cursor.getFloat(cursor.getColumnIndexOrThrow("bearing")),
+            createdAt = cursor.getLong(cursor.getColumnIndexOrThrow("createdAt"))
+        )
+    }
+}

package/android/src/main/java/com/livetracking/receiver/BootReceiver.kt

@@ -0,0 +1,53 @@
+package com.livetracking.receiver
+
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import android.content.SharedPreferences
+import com.livetracking.service.TrackingForegroundService
+
+/**
+ * BroadcastReceiver that listens for BOOT_COMPLETED to auto-restart
+ * location tracking after device reboot.
+ *
+ * Requirements: 2.3
+ */
+class BootReceiver : BroadcastReceiver() {
+
+    override fun onReceive(context: Context, intent: Intent) {
+        if (intent.action == Intent.ACTION_BOOT_COMPLETED) {
+            if (TrackingStateStore.isTrackingActive(context)) {
+                TrackingForegroundService.start(context)
+            }
+        }
+    }
+}
+
+/**
+ * Helper object for persisting tracking state across device reboots.
+ * Uses SharedPreferences to store whether tracking was active before reboot.
+ */
+object TrackingStateStore {
+
+    private const val PREFS_NAME = "live_tracking_prefs"
+    private const val KEY_IS_TRACKING_ACTIVE = "is_tracking_active"
+
+    private fun getPrefs(context: Context): SharedPreferences {
+        return context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+    }
+
+    /**
+     * Save the current tracking active state.
+     * Call with `true` when tracking starts, `false` when tracking stops.
+     */
+    fun saveTrackingActive(context: Context, isActive: Boolean) {
+        getPrefs(context).edit().putBoolean(KEY_IS_TRACKING_ACTIVE, isActive).apply()
+    }
+
+    /**
+     * Check if tracking was active before the last reboot/shutdown.
+     */
+    fun isTrackingActive(context: Context): Boolean {
+        return getPrefs(context).getBoolean(KEY_IS_TRACKING_ACTIVE, false)
+    }
+}