@kafitra/react-native-live-tracking 0.1.0

package/ios/ActivityRecognitionHandler.swift

@@ -0,0 +1,196 @@
+import Foundation
+import CoreMotion
+
+/**
+ * Activity types recognized by the handler.
+ */
+enum ActivityType {
+    case stationary
+    case walking
+    case automotive
+    case unknown
+}
+
+/**
+ * Protocol for receiving activity state changes from ActivityRecognitionHandler.
+ */
+protocol ActivityStateDelegate: AnyObject {
+    /**
+     * Called when the detected activity type changes.
+     *
+     * - Parameter activity: The new detected activity type
+     */
+    func onActivityChanged(activity: ActivityType)
+
+    /**
+     * Called when the stationary duration exceeds the configured threshold.
+     *
+     * - Parameter durationMs: The duration in milliseconds that the device has been stationary
+     */
+    func onStationaryDurationExceeded(durationMs: Int64)
+}
+
+/**
+ * iOS Activity Recognition Handler that wraps CMMotionActivityManager.
+ * Detects user activity (stationary, walking, automotive) and tracks stationary duration
+ * to support Motion Sleep Mode for battery optimization.
+ *
+ * Requirements: 8.1, 8.3
+ */
+class ActivityRecognitionHandler {
+
+    // MARK: - Properties
+
+    weak var delegate: ActivityStateDelegate?
+
+    /// Threshold in milliseconds for stationary duration notification (default: 3 minutes)
+    var stationaryThresholdMs: Int64 = 180_000
+
+    private let motionActivityManager: CMMotionActivityManager
+    private let operationQueue: OperationQueue
+
+    private var currentActivity: ActivityType = .unknown
+    private var stationaryStartTime: Date?
+    private var isStationary: Bool = false
+    private var isRunning: Bool = false
+    private var stationaryDurationExceededNotified: Bool = false
+
+    // MARK: - Initialization
+
+    init() {
+        motionActivityManager = CMMotionActivityManager()
+        operationQueue = OperationQueue()
+        operationQueue.name = "com.livetracking.activityRecognition"
+        operationQueue.maxConcurrentOperationCount = 1
+    }
+
+    // MARK: - Public Methods
+
+    /**
+     * Get the current detected activity type.
+     *
+     * - Returns: The current activity type
+     */
+    func getCurrentActivity() -> ActivityType {
+        return currentActivity
+    }
+
+    /**
+     * Get the current stationary duration in milliseconds.
+     * Returns 0 if the device is not currently stationary.
+     *
+     * - Returns: Duration in milliseconds that the device has been stationary, or 0
+     */
+    func getStationaryDurationMs() -> Int64 {
+        guard isStationary, let startTime = stationaryStartTime else {
+            return 0
+        }
+        return Int64(Date().timeIntervalSince(startTime) * 1000)
+    }
+
+    /**
+     * Check if the device is currently in stationary state.
+     *
+     * - Returns: true if the device is detected as stationary
+     */
+    func isDeviceStationary() -> Bool {
+        return isStationary
+    }
+
+    /**
+     * Start activity recognition updates.
+     * Uses CMMotionActivityManager to receive periodic activity detection updates.
+     *
+     * Note: Requires Motion & Fitness permission (NSMotionUsageDescription in Info.plist).
+     */
+    func startActivityRecognition() {
+        guard CMMotionActivityManager.isActivityAvailable() else {
+            print("[ActivityRecognitionHandler] Activity recognition is not available on this device")
+            return
+        }
+
+        if isRunning { return }
+
+        motionActivityManager.startActivityUpdates(to: operationQueue) { [weak self] activity in
+            guard let self = self, let activity = activity else { return }
+            self.handleActivityUpdate(activity)
+        }
+
+        isRunning = true
+    }
+
+    /**
+     * Stop activity recognition updates.
+     * Stops CMMotionActivityManager updates and resets internal state.
+     */
+    func stopActivityRecognition() {
+        if !isRunning { return }
+
+        motionActivityManager.stopActivityUpdates()
+
+        // Reset state
+        isRunning = false
+        isStationary = false
+        stationaryStartTime = nil
+        stationaryDurationExceededNotified = false
+        currentActivity = .unknown
+    }
+
+    // MARK: - Private Methods
+
+    private func handleActivityUpdate(_ activity: CMMotionActivity) {
+        let newActivity = mapToActivityType(activity)
+        let previousActivity = currentActivity
+        currentActivity = newActivity
+
+        if newActivity != previousActivity {
+            delegate?.onActivityChanged(activity: newActivity)
+        }
+
+        switch newActivity {
+        case .stationary:
+            handleStationaryState()
+        case .walking, .automotive:
+            handleMovingState()
+        case .unknown:
+            break
+        }
+    }
+
+    private func handleStationaryState() {
+        if !isStationary {
+            // Transition to stationary - start tracking duration
+            isStationary = true
+            stationaryStartTime = Date()
+            stationaryDurationExceededNotified = false
+        } else {
+            // Already stationary - check if threshold exceeded
+            let durationMs = getStationaryDurationMs()
+            if durationMs >= stationaryThresholdMs && !stationaryDurationExceededNotified {
+                stationaryDurationExceededNotified = true
+                delegate?.onStationaryDurationExceeded(durationMs: durationMs)
+            }
+        }
+    }
+
+    private func handleMovingState() {
+        if isStationary {
+            // Transition from stationary to moving
+            isStationary = false
+            stationaryStartTime = nil
+            stationaryDurationExceededNotified = false
+        }
+    }
+
+    private func mapToActivityType(_ activity: CMMotionActivity) -> ActivityType {
+        if activity.stationary {
+            return .stationary
+        } else if activity.walking || activity.running {
+            return .walking
+        } else if activity.automotive {
+            return .automotive
+        } else {
+            return .unknown
+        }
+    }
+}

package/ios/BackgroundModeHelper.swift

@@ -0,0 +1,132 @@
+import Foundation
+import CoreLocation
+
+/**
+ * BackgroundModeHelper
+ *
+ * Utility class that provides significant location change monitoring as a fallback
+ * mechanism when the app is terminated by the system. Significant location changes
+ * will relaunch the app, allowing tracking to resume.
+ *
+ * ## Important: Consuming App Configuration Required
+ *
+ * This library does NOT modify the consuming app's Info.plist. The consuming app
+ * MUST add the following entries to their Info.plist:
+ *
+ * ### 1. UIBackgroundModes
+ * Add `location` to the `UIBackgroundModes` array:
+ * ```xml
+ * <key>UIBackgroundModes</key>
+ * <array>
+ *     <string>location</string>
+ * </array>
+ * ```
+ *
+ * ### 2. Location Usage Descriptions
+ * Add both usage description keys:
+ * ```xml
+ * <key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
+ * <string>This app needs location access to track your position in the background.</string>
+ * <key>NSLocationWhenInUseUsageDescription</key>
+ * <string>This app needs location access to track your position.</string>
+ * ```
+ *
+ * ### How Significant Location Change Monitoring Works
+ *
+ * When the app is terminated by the system (e.g., due to memory pressure), iOS can
+ * still deliver significant location change events. These events will relaunch the app
+ * in the background with `UIApplication.LaunchOptionsKey.location` set in the launch
+ * options dictionary.
+ *
+ * The consuming app should check for this key in `application(_:didFinishLaunchingWithOptions:)`
+ * and restart location tracking if present:
+ *
+ * ```swift
+ * func application(_ application: UIApplication,
+ *                  didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
+ *     if launchOptions?[.location] != nil {
+ *         // App was relaunched due to a significant location change.
+ *         // Restart tracking here.
+ *     }
+ *     return true
+ * }
+ * ```
+ *
+ * Significant location changes are triggered by cell tower transitions and typically
+ * fire every 500 meters or more. This is less precise than continuous GPS but ensures
+ * the app can resume full-accuracy tracking after termination.
+ */
+@objc
+class BackgroundModeHelper: NSObject, SignificantLocationMonitoring {
+
+    // MARK: - Singleton
+
+    @objc static let shared = BackgroundModeHelper()
+
+    private override init() {
+        super.init()
+    }
+
+    // MARK: - Significant Location Monitoring
+
+    /**
+     * Starts significant location change monitoring as a fallback mechanism.
+     *
+     * This should be called when tracking begins so that if the app is terminated
+     * by the system, iOS will relaunch the app upon detecting a significant location
+     * change (typically cell tower transitions, ~500m or more).
+     *
+     * - Parameter locationManager: The CLLocationManager instance to use for monitoring.
+     *
+     * - Note: The consuming app must have `UIBackgroundModes` with `location` in Info.plist
+     *   and the user must have granted "Always" location permission for this to work
+     *   after app termination.
+     */
+    @objc
+    func startSignificantLocationMonitoring(locationManager: CLLocationManager) {
+        guard CLLocationManager.significantLocationChangeMonitoringAvailable() else {
+            return
+        }
+        locationManager.startMonitoringSignificantLocationChanges()
+    }
+
+    /**
+     * Stops significant location change monitoring.
+     *
+     * Call this when tracking is stopped to prevent unnecessary app relaunches
+     * after termination.
+     *
+     * - Parameter locationManager: The CLLocationManager instance to stop monitoring on.
+     */
+    @objc
+    func stopSignificantLocationMonitoring(locationManager: CLLocationManager) {
+        locationManager.stopMonitoringSignificantLocationChanges()
+    }
+
+    /**
+     * Checks whether significant location change monitoring is available on this device.
+     *
+     * Significant location monitoring may not be available on all devices (e.g., devices
+     * without cellular hardware). Always check availability before starting monitoring.
+     *
+     * - Returns: `true` if significant location change monitoring is available, `false` otherwise.
+     */
+    @objc
+    func isSignificantLocationMonitoringAvailable() -> Bool {
+        return CLLocationManager.significantLocationChangeMonitoringAvailable()
+    }
+
+    /**
+     * Checks if the app was launched due to a significant location change event.
+     *
+     * Call this from `application(_:didFinishLaunchingWithOptions:)` to determine
+     * if the app should restart tracking.
+     *
+     * - Parameter launchOptions: The launch options dictionary from AppDelegate.
+     * - Returns: `true` if the app was relaunched due to a location event.
+     */
+    @objc
+    func wasLaunchedDueToLocationEvent(launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
+        return launchOptions?[.location] != nil
+    }
+}

package/ios/FirebaseSyncEngine.swift

@@ -0,0 +1,276 @@
+import Foundation
+import FirebaseDatabase
+import FirebaseFirestore
+
+/**
+ * Protocol for Firebase sync operation callbacks.
+ */
+protocol SyncCallback: AnyObject {
+    func onSuccess()
+    func 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
+ *
+ * Requirements: 4.1, 4.3, 5.2, 10.4
+ */
+class FirebaseSyncEngine {
+
+    // MARK: - Constants
+
+    private static let baseDelayMs: Int = 1000
+    private static let multiplier: Double = 2.0
+    private static let jitterMs: Int = 200
+    private static let maxRetriesCurrent: Int = 3
+    private static let maxRetriesHistory: Int = 5
+
+    // MARK: - Properties
+
+    private let service: String
+    private let currentLocationPath: String?
+    private let historyPath: String?
+    private let syncQueue = DispatchQueue(label: "com.livetracking.firebase.sync", qos: .utility)
+
+    // MARK: - Initialization
+
+    /**
+     * Initialize the FirebaseSyncEngine.
+     *
+     * - Parameter service: Either "RTDB" or "Firestore"
+     * - Parameter currentLocationPath: Firebase path for current location (overwrite)
+     * - Parameter historyPath: Firebase path for history locations (append)
+     */
+    init(service: String, currentLocationPath: String?, historyPath: String?) {
+        self.service = service
+        self.currentLocationPath = currentLocationPath
+        self.historyPath = historyPath
+    }
+
+    // MARK: - Public Methods
+
+    /**
+     * Update the current location at the configured currentLocationPath.
+     * Uses set/update (overwrite) semantics.
+     * Retries up to 3 times with exponential backoff on failure.
+     *
+     * - Parameter latitude: Location latitude
+     * - Parameter longitude: Location longitude
+     * - Parameter timestamp: Unix timestamp in milliseconds
+     * - Parameter accuracy: Location accuracy in meters
+     * - Parameter speed: Speed in m/s, nullable
+     * - Parameter callback: SyncCallback for success/error notification
+     */
+    func updateCurrentLocation(
+        latitude: Double,
+        longitude: Double,
+        timestamp: Int64,
+        accuracy: Double,
+        speed: Double?,
+        callback: SyncCallback
+    ) {
+        guard let path = currentLocationPath else {
+            callback.onError(errorCode: "NO_PATH", message: "currentLocationPath is not configured")
+            return
+        }
+
+        var data: [String: Any] = [
+            "latitude": latitude,
+            "longitude": longitude,
+            "timestamp": timestamp,
+            "accuracy": accuracy,
+            "updatedAt": timestamp
+        ]
+        if let speed = speed {
+            data["speed"] = speed
+        }
+
+        syncQueue.async { [weak self] in
+            guard let self = self else { return }
+            self.executeWithRetry(
+                maxRetries: FirebaseSyncEngine.maxRetriesCurrent,
+                operation: { completion in
+                    self.performCurrentLocationWrite(path: path, data: data, completion: completion)
+                },
+                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.
+     *
+     * - Parameter locations: Array of location dictionaries to send
+     * - Parameter callback: SyncCallback for success/error notification
+     */
+    func pushHistoryBatch(locations: [[String: Any]], callback: SyncCallback) {
+        guard let path = historyPath else {
+            callback.onError(errorCode: "NO_PATH", message: "historyPath is not configured")
+            return
+        }
+
+        if locations.isEmpty {
+            callback.onSuccess()
+            return
+        }
+
+        syncQueue.async { [weak self] in
+            guard let self = self else { return }
+            self.executeWithRetry(
+                maxRetries: FirebaseSyncEngine.maxRetriesHistory,
+                operation: { completion in
+                    self.performHistoryBatchWrite(path: path, locations: locations, completion: completion)
+                },
+                callback: callback
+            )
+        }
+    }
+
+    // MARK: - Private Write Methods
+
+    private func performCurrentLocationWrite(
+        path: String,
+        data: [String: Any],
+        completion: @escaping (Bool, String?, String?) -> Void
+    ) {
+        switch service {
+        case "RTDB":
+            let reference = Database.database().reference(withPath: path)
+            reference.setValue(data) { error, _ in
+                if let error = error {
+                    completion(false, "FIREBASE_WRITE_FAILED", error.localizedDescription)
+                } else {
+                    completion(true, nil, nil)
+                }
+            }
+        case "Firestore":
+            let document = Firestore.firestore().document(path)
+            document.setData(data) { error in
+                if let error = error {
+                    completion(false, "FIREBASE_WRITE_FAILED", error.localizedDescription)
+                } else {
+                    completion(true, nil, nil)
+                }
+            }
+        default:
+            completion(false, "INVALID_SERVICE", "Unknown service: \(service). Use 'RTDB' or 'Firestore'.")
+        }
+    }
+
+    private func performHistoryBatchWrite(
+        path: String,
+        locations: [[String: Any]],
+        completion: @escaping (Bool, String?, String?) -> Void
+    ) {
+        switch service {
+        case "RTDB":
+            let reference = Database.database().reference(withPath: path)
+            var updates: [String: Any] = [:]
+
+            for location in locations {
+                let key = reference.childByAutoId().key ?? UUID().uuidString
+                updates[key] = location
+            }
+
+            if updates.isEmpty {
+                completion(true, nil, nil)
+                return
+            }
+
+            reference.updateChildValues(updates) { error, _ in
+                if let error = error {
+                    completion(false, "FIREBASE_WRITE_FAILED", error.localizedDescription)
+                } else {
+                    completion(true, nil, nil)
+                }
+            }
+
+        case "Firestore":
+            let firestore = Firestore.firestore()
+            let collection = firestore.collection(path)
+            let batch = firestore.batch()
+
+            for location in locations {
+                let docRef = collection.document()
+                batch.setData(location, forDocument: docRef)
+            }
+
+            batch.commit { error in
+                if let error = error {
+                    completion(false, "FIREBASE_WRITE_FAILED", error.localizedDescription)
+                } else {
+                    completion(true, nil, nil)
+                }
+            }
+
+        default:
+            completion(false, "INVALID_SERVICE", "Unknown service: \(service). Use 'RTDB' or 'Firestore'.")
+        }
+    }
+
+    // MARK: - Retry Logic
+
+    /**
+     * Execute an operation with exponential backoff retry.
+     *
+     * Retry delay formula: baseDelay × 2^(attempt-1) ± jitter
+     * - Base delay: 1000ms
+     * - Multiplier: 2x
+     * - Jitter: ±200ms (random)
+     *
+     * - Parameter maxRetries: Maximum number of retry attempts
+     * - Parameter operation: The Firebase write operation to execute, calls completion(success, errorCode, message)
+     * - Parameter callback: Final callback after all retries exhausted or success
+     */
+    private func executeWithRetry(
+        maxRetries: Int,
+        operation: @escaping (@escaping (Bool, String?, String?) -> Void) -> Void,
+        callback: SyncCallback
+    ) {
+        var attempt = 0
+
+        func tryOperation() {
+            attempt += 1
+            operation { success, errorCode, message in
+                if success {
+                    callback.onSuccess()
+                } else {
+                    if attempt >= maxRetries {
+                        callback.onError(
+                            errorCode: errorCode ?? "FIREBASE_WRITE_FAILED",
+                            message: "Failed after \(attempt) attempts: \(message ?? "Unknown error")"
+                        )
+                    } else {
+                        let delay = self.calculateBackoffDelay(attempt: attempt)
+                        Thread.sleep(forTimeInterval: Double(delay) / 1000.0)
+                        tryOperation()
+                    }
+                }
+            }
+        }
+
+        tryOperation()
+    }
+
+    /**
+     * Calculate exponential backoff delay with jitter.
+     *
+     * Formula: baseDelay × 2^(attempt-1) ± random jitter
+     *
+     * - Parameter attempt: Current attempt number (1-indexed)
+     * - Returns: Delay in milliseconds
+     */
+    func calculateBackoffDelay(attempt: Int) -> Int {
+        let exponentialDelay = Double(FirebaseSyncEngine.baseDelayMs) * pow(FirebaseSyncEngine.multiplier, Double(attempt - 1))
+        let jitter = Int.random(in: -FirebaseSyncEngine.jitterMs...FirebaseSyncEngine.jitterMs)
+        return max(0, Int(exponentialDelay) + jitter)
+    }
+}

package/ios/LiveTracking-Bridging-Header.h

@@ -0,0 +1,2 @@
+#import <React/RCTBridgeModule.h>
+#import <React/RCTEventEmitter.h>

package/ios/LiveTracking.m

@@ -0,0 +1,37 @@
+#import <React/RCTBridgeModule.h>
+#import <React/RCTEventEmitter.h>
+
+/**
+ * Objective-C bridge file for the LiveTracking Swift module.
+ *
+ * Uses RCT_EXTERN_MODULE to expose Swift methods to React Native.
+ * Also conforms to RCTTurboModule so the module is discoverable via
+ * TurboModuleRegistry in New Architecture / Bridgeless mode (RN 0.76+).
+ */
+@interface RCT_EXTERN_MODULE(LiveTracking, RCTEventEmitter)
+
+RCT_EXTERN_METHOD(configure:(NSString *)config
+                  resolve:(RCTPromiseResolveBlock)resolve
+                  reject:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(start:(RCTPromiseResolveBlock)resolve
+                  reject:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(stop:(RCTPromiseResolveBlock)resolve
+                  reject:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(getStatus:(RCTPromiseResolveBlock)resolve
+                  reject:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(getQueuedLocations:(RCTPromiseResolveBlock)resolve
+                  reject:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(getQueuedLocationsByTarget:(RCTPromiseResolveBlock)resolve
+                  reject:(RCTPromiseRejectBlock)reject)
+
++ (BOOL)requiresMainQueueSetup
+{
+    return NO;
+}
+
+@end