@kafitra/react-native-live-tracking 0.1.0

package/ios/LocationDataPoint.swift

@@ -0,0 +1,56 @@
+import Foundation
+
+/**
+ * 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 nil, they should be omitted or written as null
+ * in the Firebase payload — never as placeholder values (0, -1, etc.).
+ *
+ * Requirements: 9.3
+ */
+struct LocationDataPoint {
+    /// Location latitude in degrees
+    let latitude: Double
+
+    /// Location longitude in degrees
+    let longitude: Double
+
+    /// Unix timestamp in milliseconds
+    let timestamp: Int64
+
+    /// Location accuracy in meters
+    let accuracy: Double
+
+    /// Speed in m/s, or nil if unavailable
+    let speed: Double?
+
+    /// Altitude in meters, or nil if unavailable
+    let altitude: Double?
+
+    /// Bearing in degrees, or nil if unavailable
+    let bearing: Double?
+
+    init(
+        latitude: Double,
+        longitude: Double,
+        timestamp: Int64,
+        accuracy: Double,
+        speed: Double? = nil,
+        altitude: Double? = nil,
+        bearing: Double? = nil
+    ) {
+        self.latitude = latitude
+        self.longitude = longitude
+        self.timestamp = timestamp
+        self.accuracy = accuracy
+        self.speed = speed
+        self.altitude = altitude
+        self.bearing = bearing
+    }
+}

package/ios/LocationEngine.swift

@@ -0,0 +1,160 @@
+import Foundation
+import CoreLocation
+
+/**
+ * Protocol for receiving location updates and errors from the LocationEngine.
+ */
+protocol LocationUpdateDelegate: AnyObject {
+    func onLocationReceived(location: CLLocation)
+    func onLocationError(errorCode: String, message: String)
+}
+
+/**
+ * Default implementation for optional delegate method so existing code keeps compiling.
+ */
+extension LocationUpdateDelegate {
+    func onLocationError(errorCode: String, message: String) {
+        // No-op by default
+    }
+}
+
+/**
+ * iOS Location Engine that wraps CLLocationManager.
+ * Provides high-accuracy location updates for live tracking with background support.
+ *
+ * Requirements: 3.1, 3.2
+ */
+class LocationEngine: NSObject, CLLocationManagerDelegate {
+
+    private var locationManager: CLLocationManager!
+
+    weak var delegate: LocationUpdateDelegate?
+
+    override init() {
+        super.init()
+        let initOnMain = { [self] in
+            self.locationManager = CLLocationManager()
+            self.locationManager.delegate = self
+        }
+        if Thread.isMainThread {
+            initOnMain()
+        } else {
+            DispatchQueue.main.sync(execute: initOnMain)
+        }
+    }
+
+    // MARK: - Public Methods
+
+    func requestAlwaysAuthorization() {
+        if Thread.isMainThread {
+            self.locationManager.requestAlwaysAuthorization()
+        } else {
+            DispatchQueue.main.async { [weak self] in
+                self?.locationManager.requestAlwaysAuthorization()
+            }
+        }
+    }
+
+    func getAuthorizationStatus() -> CLAuthorizationStatus {
+        if #available(iOS 14.0, *) {
+            return locationManager.authorizationStatus
+        } else {
+            return CLLocationManager.authorizationStatus()
+        }
+    }
+
+    /**
+     * Start receiving location updates with the specified interval and distance filter.
+     * Uses kCLLocationAccuracyBest for best possible location accuracy.
+     *
+     * - Parameter intervalMs: The desired interval for location updates in milliseconds (used for time-based filtering at a higher level)
+     * - Parameter distanceFilter: The minimum distance between updates in meters
+     */
+    func startLocationUpdates(intervalMs: Int, distanceFilter: Double) {
+        startLocationUpdates(intervalMs: intervalMs, distanceFilter: distanceFilter, accuracy: kCLLocationAccuracyBest)
+    }
+
+    /**
+     * Start receiving location updates with the specified interval, distance filter, and accuracy.
+     * Allows configurable accuracy for scenarios like sleep mode where lower accuracy saves battery.
+     *
+     * - Parameter intervalMs: The desired interval for location updates in milliseconds (used for time-based filtering at a higher level)
+     * - Parameter distanceFilter: The minimum distance between updates in meters
+     * - Parameter accuracy: The desired location accuracy (e.g., kCLLocationAccuracyBest or kCLLocationAccuracyKilometer)
+     */
+    func startLocationUpdates(intervalMs: Int, distanceFilter: Double, accuracy: CLLocationAccuracy) {
+        let setup = { [weak self] in
+            guard let self = self else { return }
+            self.locationManager.desiredAccuracy = accuracy
+            self.locationManager.distanceFilter = distanceFilter
+            self.locationManager.allowsBackgroundLocationUpdates = true
+            self.locationManager.pausesLocationUpdatesAutomatically = false
+            // Use otherNavigation so iOS does not throttle/suspend updates when device is stationary
+            self.locationManager.activityType = .otherNavigation
+            self.locationManager.showsBackgroundLocationIndicator = true
+            self.locationManager.startUpdatingLocation()
+        }
+        if Thread.isMainThread {
+            setup()
+        } else {
+            DispatchQueue.main.async(execute: setup)
+        }
+    }
+
+    /**
+     * Stop receiving location updates.
+     */
+    func stopLocationUpdates() {
+        if Thread.isMainThread {
+            locationManager.stopUpdatingLocation()
+        } else {
+            DispatchQueue.main.async { [weak self] in
+                self?.locationManager.stopUpdatingLocation()
+            }
+        }
+    }
+
+    // MARK: - CLLocationManagerDelegate
+
+    func locationManager(_ manager: CLLocationManager, didUpdateLocations locations: [CLLocation]) {
+        guard let location = locations.last else { return }
+        print("[LocationEngine] 📡 didUpdateLocations called — delegate alive=\(delegate != nil) lat=\(location.coordinate.latitude) ts=\(Int64(location.timestamp.timeIntervalSince1970 * 1000))")
+        delegate?.onLocationReceived(location: location)
+    }
+
+    func locationManagerDidPauseLocationUpdates(_ manager: CLLocationManager) {
+        print("[LocationEngine] ⚠️ CLLocationManager PAUSED location updates!")
+    }
+
+    func locationManagerDidResumeLocationUpdates(_ manager: CLLocationManager) {
+        print("[LocationEngine] ✅ CLLocationManager RESUMED location updates")
+    }
+
+    func locationManager(_ manager: CLLocationManager, didFailWithError error: Error) {
+        let errorCode: String
+        let message: String
+
+        if let clError = error as? CLError {
+            switch clError.code {
+            case .denied:
+                errorCode = "PERMISSION_DENIED"
+                message = "Location updates failed: permission denied."
+            case .locationUnknown:
+                errorCode = "LOCATION_UNKNOWN"
+                message = "Location temporarily unavailable: \(error.localizedDescription)"
+            case .network:
+                errorCode = "NETWORK_ERROR"
+                message = "Location network error: \(error.localizedDescription)"
+            default:
+                errorCode = "LOCATION_ERROR"
+                message = "Location update failed: \(error.localizedDescription)"
+            }
+        } else {
+            errorCode = "LOCATION_ERROR"
+            message = "Location update failed: \(error.localizedDescription)"
+        }
+
+        delegate?.onLocationError(errorCode: errorCode, message: message)
+        print("[LocationEngine] \(errorCode): \(message)")
+    }
+}

package/ios/MotionSleepManager.swift

@@ -0,0 +1,151 @@
+import Foundation
+import CoreLocation
+
+/**
+ * Protocol for receiving motion sleep mode state changes.
+ */
+protocol MotionSleepDelegate: AnyObject {
+    /**
+     * Called when sleep mode is activated (device stationary > 3 minutes).
+     */
+    func onSleepModeActivated()
+
+    /**
+     * Called when sleep mode is deactivated (movement detected).
+     */
+    func onSleepModeDeactivated()
+}
+
+/**
+ * Manages Motion Sleep Mode for battery optimization on iOS.
+ *
+ * When the device is detected as stationary for more than 3 minutes and `stopWhenStill` is enabled,
+ * this manager switches location updates to kCLDesiredAccuracyKilometer (low-power mode).
+ * When movement is detected again, it restores kCLDesiredAccuracyBest location updates.
+ *
+ * Requirements: 8.1, 8.2, 8.4
+ */
+class MotionSleepManager {
+
+    // MARK: - Constants
+
+    /// Duration threshold in milliseconds before entering sleep mode.
+    /// Device must be stationary for more than 3 minutes (180,000 ms).
+    static let STILL_THRESHOLD_MS: Int64 = 180_000
+
+    // MARK: - Properties
+
+    weak var delegate: MotionSleepDelegate?
+
+    private let locationEngine: LocationEngine
+    private let stopWhenStill: Bool
+    private let intervalMs: Int
+    private let distanceFilter: Double
+
+    private var inSleepMode: Bool = false
+    private var stationaryStartTime: Date?
+    private var isStationary: Bool = false
+
+    // MARK: - Initialization
+
+    /**
+     * Initialize the MotionSleepManager.
+     *
+     * - Parameter locationEngine: The location engine to control GPS accuracy
+     * - Parameter stopWhenStill: Whether motion sleep mode is enabled
+     * - Parameter intervalMs: The configured location update interval in milliseconds
+     * - Parameter distanceFilter: The configured distance filter in meters
+     */
+    init(locationEngine: LocationEngine, stopWhenStill: Bool, intervalMs: Int, distanceFilter: Double) {
+        self.locationEngine = locationEngine
+        self.stopWhenStill = stopWhenStill
+        self.intervalMs = intervalMs
+        self.distanceFilter = distanceFilter
+    }
+
+    // MARK: - Public Methods
+
+    /**
+     * Called when an activity detection update is received.
+     *
+     * If `stopWhenStill` is false, this method is a no-op.
+     *
+     * Behavior:
+     * - stationary detected: starts tracking duration. If stationary > 3 minutes, enters sleep mode.
+     * - walking or automotive detected: exits sleep mode if active, resets stationary tracking.
+     *
+     * - Parameter activity: The detected activity type from ActivityRecognitionHandler
+     */
+    func onActivityDetected(activity: ActivityType) {
+        if !stopWhenStill {
+            return
+        }
+
+        switch activity {
+        case .stationary:
+            if !isStationary {
+                // Start tracking stationary duration
+                isStationary = true
+                stationaryStartTime = Date()
+            } else {
+                // Already stationary, check if threshold exceeded
+                guard let startTime = stationaryStartTime else { return }
+                let stationaryDurationMs = Int64(Date().timeIntervalSince(startTime) * 1000)
+                if stationaryDurationMs > MotionSleepManager.STILL_THRESHOLD_MS && !inSleepMode {
+                    enterSleepMode()
+                }
+            }
+
+        case .walking, .automotive:
+            isStationary = false
+            stationaryStartTime = nil
+            if inSleepMode {
+                exitSleepMode()
+            }
+
+        case .unknown:
+            break
+        }
+    }
+
+    /**
+     * Returns whether the manager is currently in sleep mode (low-power location).
+     *
+     * - Returns: true if sleep mode is active, false otherwise
+     */
+    func isInSleepMode() -> Bool {
+        return inSleepMode
+    }
+
+    // MARK: - Private Methods
+
+    /**
+     * Enter sleep mode: stop current location updates and restart with kCLDesiredAccuracyKilometer.
+     * This reduces GPS usage when the device is stationary.
+     */
+    private func enterSleepMode() {
+        inSleepMode = true
+        locationEngine.stopLocationUpdates()
+        locationEngine.startLocationUpdates(
+            intervalMs: intervalMs,
+            distanceFilter: distanceFilter,
+            accuracy: kCLLocationAccuracyKilometer
+        )
+        delegate?.onSleepModeActivated()
+    }
+
+    /**
+     * Exit sleep mode: stop current location updates and restart with kCLDesiredAccuracyBest.
+     * This restores full GPS accuracy when movement is detected.
+     */
+    private func exitSleepMode() {
+        inSleepMode = false
+        locationEngine.stopLocationUpdates()
+        locationEngine.startLocationUpdates(
+            intervalMs: intervalMs,
+            distanceFilter: distanceFilter,
+            accuracy: kCLLocationAccuracyBest
+        )
+        delegate?.onSleepModeDeactivated()
+    }
+}

package/ios/NetworkListener.swift

@@ -0,0 +1,105 @@
+import Foundation
+import Network
+
+/**
+ * Protocol for receiving network state change notifications.
+ * Implementations receive callbacks when connectivity is gained or lost.
+ */
+protocol NetworkStateDelegate: AnyObject {
+    /**
+     * Called when network connectivity is restored.
+     * Use this to trigger queue flush for pending location data.
+     */
+    func onNetworkAvailable()
+
+    /**
+     * Called when network connectivity is lost.
+     */
+    func onNetworkLost()
+}
+
+/**
+ * NetworkListener monitors device network connectivity using NWPathMonitor.
+ * When connectivity is restored after being offline, it notifies the registered delegate
+ * so that pending queued locations can be flushed to Firebase.
+ *
+ * Conforms to NetworkStatusProvider for use with SyncEngineController.
+ *
+ * Requirements: 6.2, 6.4
+ *
+ * Usage:
+ * ```
+ * let listener = NetworkListener()
+ * listener.delegate = self
+ * listener.startListening()
+ * // ...
+ * listener.stopListening()
+ * ```
+ */
+class NetworkListener: NetworkStatusProvider {
+
+    // MARK: - Properties
+
+    private let monitor: NWPathMonitor
+    private let monitorQueue: DispatchQueue
+    private var isListening: Bool = false
+    private var currentlyOnline: Bool = false
+
+    weak var delegate: NetworkStateDelegate?
+
+    // MARK: - Initialization
+
+    init() {
+        monitor = NWPathMonitor()
+        monitorQueue = DispatchQueue(label: "com.livetracking.network.monitor", qos: .utility)
+    }
+
+    // MARK: - Public Methods
+
+    /**
+     * Start listening for network connectivity changes.
+     * Starts NWPathMonitor on a background queue.
+     * If already listening, this is a no-op.
+     */
+    func startListening() {
+        guard !isListening else { return }
+
+        monitor.pathUpdateHandler = { [weak self] path in
+            guard let self = self else { return }
+
+            let wasOnline = self.currentlyOnline
+            let isNowOnline = path.status == .satisfied
+
+            self.currentlyOnline = isNowOnline
+
+            if isNowOnline && !wasOnline {
+                self.delegate?.onNetworkAvailable()
+            } else if !isNowOnline && wasOnline {
+                self.delegate?.onNetworkLost()
+            }
+        }
+
+        monitor.start(queue: monitorQueue)
+        isListening = true
+    }
+
+    /**
+     * Stop listening for network connectivity changes.
+     * Cancels the NWPathMonitor.
+     * If not currently listening, this is a no-op.
+     */
+    func stopListening() {
+        guard isListening else { return }
+        monitor.cancel()
+        isListening = false
+    }
+
+    /**
+     * Returns the current network connectivity state.
+     *
+     * - Returns: true if the device currently has network connectivity, false otherwise
+     */
+    func isOnline() -> Bool {
+        return currentlyOnline
+    }
+}