@kafitra/react-native-live-tracking 0.1.0

package/android/src/main/java/com/livetracking/service/TrackingForegroundService.kt

@@ -0,0 +1,145 @@
+package com.livetracking.service
+
+import android.app.Notification
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.app.Service
+import android.content.Context
+import android.content.Intent
+import android.os.Build
+import android.os.IBinder
+import androidx.core.app.NotificationCompat
+
+/**
+ * Android Foreground Service for persistent location tracking.
+ * Keeps the app alive in the background with a persistent notification,
+ * preventing the OS from killing the process.
+ *
+ * Requirements: 2.1, 2.4, 2.5
+ */
+class TrackingForegroundService : Service() {
+
+    companion object {
+        const val DEFAULT_CHANNEL_ID = "live_tracking_channel"
+        const val DEFAULT_CHANNEL_NAME = "Live Tracking"
+        const val NOTIFICATION_ID = 1001
+
+        private const val EXTRA_NOTIFICATION_TITLE = "extra_notification_title"
+        private const val EXTRA_NOTIFICATION_TEXT = "extra_notification_text"
+        private const val EXTRA_NOTIFICATION_ICON = "extra_notification_icon"
+        private const val EXTRA_CHANNEL_ID = "extra_channel_id"
+        private const val EXTRA_CHANNEL_NAME = "extra_channel_name"
+
+        /**
+         * Start the foreground service with notification configuration.
+         */
+        fun start(
+            context: Context,
+            title: String = "Live Tracking",
+            text: String = "Tracking your location",
+            icon: String? = null,
+            channelId: String = DEFAULT_CHANNEL_ID,
+            channelName: String = DEFAULT_CHANNEL_NAME
+        ) {
+            val intent = Intent(context, TrackingForegroundService::class.java).apply {
+                putExtra(EXTRA_NOTIFICATION_TITLE, title)
+                putExtra(EXTRA_NOTIFICATION_TEXT, text)
+                putExtra(EXTRA_CHANNEL_ID, channelId)
+                putExtra(EXTRA_CHANNEL_NAME, channelName)
+                if (icon != null) {
+                    putExtra(EXTRA_NOTIFICATION_ICON, icon)
+                }
+            }
+
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+                context.startForegroundService(intent)
+            } else {
+                context.startService(intent)
+            }
+        }
+
+        /**
+         * Stop the foreground service.
+         */
+        fun stop(context: Context) {
+            val intent = Intent(context, TrackingForegroundService::class.java)
+            context.stopService(intent)
+        }
+    }
+
+    override fun onBind(intent: Intent?): IBinder? {
+        // Not a bound service
+        return null
+    }
+
+    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
+        val title = intent?.getStringExtra(EXTRA_NOTIFICATION_TITLE) ?: "Live Tracking"
+        val text = intent?.getStringExtra(EXTRA_NOTIFICATION_TEXT) ?: "Tracking your location"
+        val iconName = intent?.getStringExtra(EXTRA_NOTIFICATION_ICON)
+        val channelId = intent?.getStringExtra(EXTRA_CHANNEL_ID) ?: DEFAULT_CHANNEL_ID
+        val channelName = intent?.getStringExtra(EXTRA_CHANNEL_NAME) ?: DEFAULT_CHANNEL_NAME
+
+        createNotificationChannel(channelId, channelName)
+
+        val notification = buildNotification(title, text, iconName, channelId)
+        startForeground(NOTIFICATION_ID, notification)
+
+        return START_STICKY
+    }
+
+    override fun onDestroy() {
+        super.onDestroy()
+        stopForeground(STOP_FOREGROUND_REMOVE)
+    }
+
+    /**
+     * Creates the notification channel for Android O and above.
+     */
+    private fun createNotificationChannel(channelId: String, channelName: String) {
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+            val channel = NotificationChannel(
+                channelId,
+                channelName,
+                NotificationManager.IMPORTANCE_LOW
+            ).apply {
+                description = "Notification channel for live location tracking"
+                setShowBadge(false)
+            }
+
+            val notificationManager = getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
+            notificationManager.createNotificationChannel(channel)
+        }
+    }
+
+    /**
+     * Builds the persistent notification displayed while tracking is active.
+     */
+    private fun buildNotification(
+        title: String,
+        text: String,
+        iconName: String?,
+        channelId: String
+    ): Notification {
+        val iconResId = if (iconName != null) {
+            resources.getIdentifier(iconName, "drawable", packageName)
+        } else {
+            0
+        }
+
+        // Fallback to app icon if custom icon not found
+        val finalIconResId = if (iconResId != 0) {
+            iconResId
+        } else {
+            applicationInfo.icon
+        }
+
+        return NotificationCompat.Builder(this, channelId)
+            .setContentTitle(title)
+            .setContentText(text)
+            .setSmallIcon(finalIconResId)
+            .setOngoing(true)
+            .setPriority(NotificationCompat.PRIORITY_LOW)
+            .setCategory(NotificationCompat.CATEGORY_SERVICE)
+            .build()
+    }
+}

package/android/src/main/java/com/livetracking/sync/FirebaseSyncEngine.kt

@@ -0,0 +1,277 @@
+package com.livetracking.sync
+
+import com.google.firebase.database.FirebaseDatabase
+import com.google.firebase.firestore.FirebaseFirestore
+import com.livetracking.queue.QueuedLocation
+import java.util.concurrent.ExecutorService
+import java.util.concurrent.Executors
+import kotlin.math.pow
+import kotlin.random.Random
+
+/**
+ * Callback interface for Firebase sync operations.
+ */
+interface SyncCallback {
+    fun onSuccess()
+    fun onError(errorCode: String, message: String)
+}
+
+/**
+ * FirebaseSyncEngine handles writing location data to Firebase.
+ *
+ * Supports both Firebase Realtime Database (RTDB) and Cloud Firestore.
+ * Implements retry with exponential backoff for resilient writes.
+ *
+ * - updateCurrentLocation: overwrites the current location at currentLocationPath
+ * - pushHistoryBatch: appends a batch of locations to historyPath
+ *
+ * @param service Either "RTDB" or "Firestore"
+ * @param currentLocationPath Firebase path for current location (overwrite)
+ * @param historyPath Firebase path for history locations (append)
+ */
+class FirebaseSyncEngine(
+    private val service: String,
+    private val currentLocationPath: String?,
+    private val historyPath: String?
+) {
+
+    companion object {
+        private const val BASE_DELAY_MS = 1000L
+        private const val MULTIPLIER = 2.0
+        private const val JITTER_MS = 200L
+        private const val MAX_RETRIES_CURRENT = 3
+        private const val MAX_RETRIES_HISTORY = 5
+    }
+
+    private val executor: ExecutorService = Executors.newSingleThreadExecutor()
+
+    /**
+     * Update the current location at the configured currentLocationPath.
+     * Uses set/update (overwrite) semantics.
+     * Retries up to 3 times with exponential backoff on failure.
+     *
+     * @param latitude Location latitude
+     * @param longitude Location longitude
+     * @param timestamp Unix timestamp in milliseconds
+     * @param accuracy Location accuracy in meters
+     * @param speed Speed in m/s, nullable
+     * @param callback SyncCallback for success/error notification
+     */
+    fun updateCurrentLocation(
+        latitude: Double,
+        longitude: Double,
+        timestamp: Long,
+        accuracy: Float,
+        speed: Float?,
+        callback: SyncCallback
+    ) {
+        if (currentLocationPath == null) {
+            callback.onError("NO_PATH", "currentLocationPath is not configured")
+            return
+        }
+
+        val data = hashMapOf<String, Any>(
+            "latitude" to latitude,
+            "longitude" to longitude,
+            "timestamp" to timestamp,
+            "accuracy" to accuracy.toDouble(),
+            "updatedAt" to timestamp
+        )
+        speed?.let { data["speed"] = it.toDouble() }
+
+        executor.execute {
+            executeWithRetry(
+                maxRetries = MAX_RETRIES_CURRENT,
+                operation = { attemptCallback ->
+                    writeCurrentLocation(data, attemptCallback)
+                },
+                callback = callback
+            )
+        }
+    }
+
+    /**
+     * Push a batch of locations to the configured historyPath.
+     * Uses push/append semantics (each location gets a unique key).
+     * Retries up to 5 times with exponential backoff on failure.
+     *
+     * @param locations List of QueuedLocation to send
+     * @param callback SyncCallback for success/error notification
+     */
+    fun pushHistoryBatch(locations: List<QueuedLocation>, callback: SyncCallback) {
+        if (historyPath == null) {
+            callback.onError("NO_PATH", "historyPath is not configured")
+            return
+        }
+
+        if (locations.isEmpty()) {
+            callback.onSuccess()
+            return
+        }
+
+        executor.execute {
+            executeWithRetry(
+                maxRetries = MAX_RETRIES_HISTORY,
+                operation = { attemptCallback ->
+                    writeHistoryBatch(locations, attemptCallback)
+                },
+                callback = callback
+            )
+        }
+    }
+
+    /**
+     * Shutdown the executor service. Call when the engine is no longer needed.
+     */
+    fun shutdown() {
+        executor.shutdown()
+    }
+
+    // --- Private implementation ---
+
+    private fun writeCurrentLocation(data: Map<String, Any>, callback: SyncCallback) {
+        when (service) {
+            "RTDB" -> writeCurrentLocationRTDB(data, callback)
+            "Firestore" -> writeCurrentLocationFirestore(data, callback)
+            else -> callback.onError("INVALID_SERVICE", "Unknown service: $service. Use 'RTDB' or 'Firestore'.")
+        }
+    }
+
+    private fun writeCurrentLocationRTDB(data: Map<String, Any>, callback: SyncCallback) {
+        val reference = FirebaseDatabase.getInstance().getReference(currentLocationPath!!)
+        reference.setValue(data)
+            .addOnSuccessListener { callback.onSuccess() }
+            .addOnFailureListener { e ->
+                callback.onError("FIREBASE_WRITE_FAILED", e.message ?: "RTDB write failed")
+            }
+    }
+
+    private fun writeCurrentLocationFirestore(data: Map<String, Any>, callback: SyncCallback) {
+        val document = FirebaseFirestore.getInstance().document(currentLocationPath!!)
+        document.set(data)
+            .addOnSuccessListener { callback.onSuccess() }
+            .addOnFailureListener { e ->
+                callback.onError("FIREBASE_WRITE_FAILED", e.message ?: "Firestore write failed")
+            }
+    }
+
+    private fun writeHistoryBatch(locations: List<QueuedLocation>, callback: SyncCallback) {
+        when (service) {
+            "RTDB" -> writeHistoryBatchRTDB(locations, callback)
+            "Firestore" -> writeHistoryBatchFirestore(locations, callback)
+            else -> callback.onError("INVALID_SERVICE", "Unknown service: $service. Use 'RTDB' or 'Firestore'.")
+        }
+    }
+
+    private fun writeHistoryBatchRTDB(locations: List<QueuedLocation>, callback: SyncCallback) {
+        val reference = FirebaseDatabase.getInstance().getReference(historyPath!!)
+        val updates = hashMapOf<String, Any>()
+
+        for (location in locations) {
+            val key = reference.push().key ?: continue
+            updates[key] = locationToMap(location)
+        }
+
+        if (updates.isEmpty()) {
+            callback.onSuccess()
+            return
+        }
+
+        reference.updateChildren(updates)
+            .addOnSuccessListener { callback.onSuccess() }
+            .addOnFailureListener { e ->
+                callback.onError("FIREBASE_WRITE_FAILED", e.message ?: "RTDB batch write failed")
+            }
+    }
+
+    private fun writeHistoryBatchFirestore(locations: List<QueuedLocation>, callback: SyncCallback) {
+        val firestore = FirebaseFirestore.getInstance()
+        val collection = firestore.collection(historyPath!!)
+        val batch = firestore.batch()
+
+        for (location in locations) {
+            val docRef = collection.document()
+            batch.set(docRef, locationToMap(location))
+        }
+
+        batch.commit()
+            .addOnSuccessListener { callback.onSuccess() }
+            .addOnFailureListener { e ->
+                callback.onError("FIREBASE_WRITE_FAILED", e.message ?: "Firestore batch write failed")
+            }
+    }
+
+    private fun locationToMap(location: QueuedLocation): Map<String, Any?> {
+        val map = hashMapOf<String, Any?>(
+            "latitude" to location.latitude,
+            "longitude" to location.longitude,
+            "timestamp" to location.timestamp,
+            "accuracy" to location.accuracy.toDouble(),
+            "speed" to location.speed?.toDouble()
+        )
+        location.altitude?.let { map["altitude"] = it }
+        location.bearing?.let { map["bearing"] = it.toDouble() }
+        return map
+    }
+
+    /**
+     * Execute an operation with exponential backoff retry.
+     *
+     * Retry delay formula: baseDelay * 2^(attempt-1) ± jitter
+     * - Base delay: 1000ms
+     * - Multiplier: 2x
+     * - Jitter: ±200ms (random)
+     *
+     * @param maxRetries Maximum number of retry attempts
+     * @param operation The Firebase write operation to execute
+     * @param callback Final callback after all retries exhausted or success
+     */
+    private fun executeWithRetry(
+        maxRetries: Int,
+        operation: (SyncCallback) -> Unit,
+        callback: SyncCallback
+    ) {
+        var attempt = 0
+
+        fun tryOperation() {
+            attempt++
+            operation(object : SyncCallback {
+                override fun onSuccess() {
+                    callback.onSuccess()
+                }
+
+                override fun onError(errorCode: String, message: String) {
+                    if (attempt >= maxRetries) {
+                        callback.onError(errorCode, "Failed after $attempt attempts: $message")
+                    } else {
+                        val delay = calculateBackoffDelay(attempt)
+                        try {
+                            Thread.sleep(delay)
+                        } catch (e: InterruptedException) {
+                            Thread.currentThread().interrupt()
+                            callback.onError("INTERRUPTED", "Retry interrupted")
+                            return
+                        }
+                        tryOperation()
+                    }
+                }
+            })
+        }
+
+        tryOperation()
+    }
+
+    /**
+     * Calculate exponential backoff delay with jitter.
+     *
+     * Formula: baseDelay * 2^(attempt-1) ± random jitter
+     *
+     * @param attempt Current attempt number (1-indexed)
+     * @return Delay in milliseconds
+     */
+    internal fun calculateBackoffDelay(attempt: Int): Long {
+        val exponentialDelay = (BASE_DELAY_MS * MULTIPLIER.pow((attempt - 1).toDouble())).toLong()
+        val jitter = Random.nextLong(-JITTER_MS, JITTER_MS + 1)
+        return maxOf(0L, exponentialDelay + jitter)
+    }
+}

package/android/src/main/java/com/livetracking/sync/LocationDataPoint.kt

@@ -0,0 +1,31 @@
+package com.livetracking.sync
+
+/**
+ * Represents a single location data point dispatched to sync targets.
+ *
+ * Required fields (always available from device sensors):
+ * - latitude, longitude, timestamp, accuracy
+ *
+ * Optional fields (may be unavailable depending on device/sensor state):
+ * - speed, altitude, bearing
+ *
+ * When optional fields are null, they should be omitted or written as null
+ * in the Firebase payload — never as placeholder values (0, -1, etc.).
+ *
+ * @param latitude Location latitude in degrees
+ * @param longitude Location longitude in degrees
+ * @param timestamp Unix timestamp in milliseconds
+ * @param accuracy Location accuracy in meters
+ * @param speed Speed in m/s, or null if unavailable
+ * @param altitude Altitude in meters, or null if unavailable
+ * @param bearing Bearing in degrees, or null if unavailable
+ */
+data class LocationDataPoint(
+    val latitude: Double,
+    val longitude: Double,
+    val timestamp: Long,
+    val accuracy: Float,
+    val speed: Float? = null,
+    val altitude: Double? = null,
+    val bearing: Float? = null
+)

package/android/src/main/java/com/livetracking/sync/SyncEngineController.kt

@@ -0,0 +1,220 @@
+package com.livetracking.sync
+
+import org.json.JSONArray
+import org.json.JSONException
+import org.json.JSONObject
+import java.util.concurrent.ExecutorService
+import java.util.concurrent.Executors
+
+/**
+ * SyncEngineController replaces the monolithic FirebaseSyncEngine.
+ *
+ * It manages a list of TargetHandler instances — one per configured sync target.
+ * When a location arrives, it fans out to all handlers in parallel.
+ * Each handler independently manages batching, retry, and offline queue logic.
+ *
+ * Responsibilities:
+ * - Parse targets JSON and instantiate one TargetHandler per target
+ * - Dispatch location data to all handlers concurrently
+ * - Flush all partial batches on stop
+ * - Report per-target queued location counts
+ * - Clean up all handlers on shutdown
+ *
+ * @param targetsJson JSON array string of sync target configurations
+ * @param firebaseService The Firebase service type ("RTDB" or "Firestore")
+ * @param networkChecker Function that returns current online status
+ * @param offlineQueueProvider Optional provider for offline persistence
+ * @param eventListener Listener for error/warning events
+ * @throws IllegalArgumentException if targetsJson fails to parse or contains invalid targets
+ */
+class SyncEngineController(
+    targetsJson: String,
+    private val firebaseService: String,
+    private val networkChecker: () -> Boolean,
+    private val offlineQueueProvider: OfflineQueueProvider? = null,
+    private val eventListener: TargetEventListener? = null
+) {
+
+    private val handlers: List<TargetHandler>
+    private val dispatchExecutor: ExecutorService = Executors.newCachedThreadPool()
+
+    init {
+        handlers = parseAndCreateHandlers(targetsJson)
+    }
+
+    /**
+     * Dispatch a location data point to all configured sync targets in parallel.
+     *
+     * Each target handler receives the location independently and decides
+     * whether to accumulate (batch), write immediately, or queue offline.
+     * A failure in one target does not block others.
+     *
+     * @param location The location data point to dispatch
+     */
+    fun dispatchLocation(location: LocationDataPoint) {
+        for (handler in handlers) {
+            dispatchExecutor.execute {
+                handler.dispatch(location)
+            }
+        }
+    }
+
+    /**
+     * Flush all partially-filled batches for all targets.
+     *
+     * Called during stop() to ensure no accumulated data is lost.
+     * Blocks until all handlers have completed their flush.
+     */
+    fun flushAll() {
+        for (handler in handlers) {
+            handler.flush()
+        }
+    }
+
+    /**
+     * Get the number of queued locations for each configured target.
+     *
+     * Returns a map of target path → queued count.
+     * Targets with offlineQueue disabled report 0.
+     *
+     * @return Map of target path to queued location count
+     */
+    fun getQueuedCounts(): Map<String, Int> {
+        val counts = mutableMapOf<String, Int>()
+        for (handler in handlers) {
+            counts[handler.targetPath] = handler.getQueuedCount()
+        }
+        return counts
+    }
+
+    /**
+     * Shutdown all handlers and release resources.
+     *
+     * Cancels any in-progress retries and batch timers.
+     * After shutdown, no further dispatches will be processed.
+     */
+    fun shutdown() {
+        for (handler in handlers) {
+            handler.shutdown()
+        }
+        dispatchExecutor.shutdown()
+    }
+
+    /**
+     * Flush offline queues for all targets that have offlineQueue enabled.
+     * Called when network connectivity is restored.
+     */
+    fun flushOfflineQueues() {
+        for (handler in handlers) {
+            handler.flushOfflineQueue()
+        }
+    }
+
+    /**
+     * Get the list of configured target paths.
+     *
+     * @return List of target path strings
+     */
+    fun getTargetPaths(): List<String> {
+        return handlers.map { it.targetPath }
+    }
+
+    // --- Private implementation ---
+
+    /**
+     * Parse the targets JSON array and create one TargetHandler per target.
+     *
+     * @param targetsJson JSON array string of sync target configurations
+     * @return List of TargetHandler instances
+     * @throws IllegalArgumentException if JSON is invalid or targets are missing required fields
+     */
+    private fun parseAndCreateHandlers(targetsJson: String): List<TargetHandler> {
+        val configs = parseTargetsJson(targetsJson)
+        return configs.map { config ->
+            val queueProvider = if (config.offlineQueue) offlineQueueProvider else null
+            TargetHandler(
+                config = config,
+                firebaseService = firebaseService,
+                networkChecker = networkChecker,
+                offlineQueueProvider = queueProvider,
+                eventListener = eventListener
+            )
+        }
+    }
+
+    /**
+     * Parse a JSON array string into a list of SyncTargetConfig objects.
+     *
+     * Each target must have:
+     * - "path" (string, required)
+     * - "method" (string, required: "set", "push", or "update")
+     * - "batchSize" (int, optional, defaults to 1)
+     * - "offlineQueue" (boolean, optional, defaults to false)
+     *
+     * @param json JSON array string
+     * @return List of SyncTargetConfig
+     * @throws IllegalArgumentException if parsing fails or required fields are missing
+     */
+    private fun parseTargetsJson(json: String): List<SyncTargetConfig> {
+        val jsonArray: JSONArray
+        try {
+            jsonArray = JSONArray(json)
+        } catch (e: JSONException) {
+            throw IllegalArgumentException(
+                "Failed to parse targets JSON: ${e.message}"
+            )
+        }
+
+        if (jsonArray.length() == 0) {
+            throw IllegalArgumentException(
+                "Targets array is empty — at least one sync target is required"
+            )
+        }
+
+        val configs = mutableListOf<SyncTargetConfig>()
+
+        for (i in 0 until jsonArray.length()) {
+            val obj: JSONObject
+            try {
+                obj = jsonArray.getJSONObject(i)
+            } catch (e: JSONException) {
+                throw IllegalArgumentException(
+                    "Target at index $i is not a valid JSON object: ${e.message}"
+                )
+            }
+
+            val path = obj.optString("path", "")
+            if (path.isEmpty()) {
+                throw IllegalArgumentException(
+                    "Target at index $i is missing required field 'path'"
+                )
+            }
+
+            val method = obj.optString("method", "")
+            if (method.isEmpty()) {
+                throw IllegalArgumentException(
+                    "Target at index $i is missing required field 'method'"
+                )
+            }
+            if (method !in listOf("set", "push", "update")) {
+                throw IllegalArgumentException(
+                    "Target at index $i has invalid method '$method'. Must be 'set', 'push', or 'update'"
+                )
+            }
+
+            val batchSize = obj.optInt("batchSize", 1)
+            val offlineQueue = obj.optBoolean("offlineQueue", false)
+
+            configs.add(
+                SyncTargetConfig(
+                    path = path,
+                    method = method,
+                    batchSize = batchSize,
+                    offlineQueue = offlineQueue
+                )
+            )
+        }
+
+        return configs
+    }
+}

package/android/src/main/java/com/livetracking/sync/SyncTargetConfig.kt

@@ -0,0 +1,20 @@
+package com.livetracking.sync
+
+/**
+ * Configuration for a single sync target.
+ *
+ * Each sync target defines a Firebase path, write method, optional batch size,
+ * and optional offline queue preference. The native SyncEngineController
+ * instantiates one TargetHandler per SyncTargetConfig.
+ *
+ * @param path Firebase path to write location data to
+ * @param method Write method: "set" (overwrite), "push" (append), or "update" (merge)
+ * @param batchSize Number of location points to accumulate before writing. Default: 1 (immediate write)
+ * @param offlineQueue Whether to persist data locally when offline. Default: false
+ */
+data class SyncTargetConfig(
+    val path: String,
+    val method: String,
+    val batchSize: Int = 1,
+    val offlineQueue: Boolean = false
+)