@bglocation/capacitor 1.1.0

package/ios/Sources/BGLocationCore/Location/BGLLocationManager.swift

@@ -0,0 +1,268 @@
+import CoreLocation
+import Foundation
+
+/// Wrapper around CLLocationManager providing continuous background location tracking.
+///
+/// Key iOS requirements for background location:
+/// - `allowsBackgroundLocationUpdates = true` MUST be set BEFORE app enters background
+/// - `pausesLocationUpdatesAutomatically = false` is CRITICAL — prevents iOS from pausing GPS
+/// - `activityType = .otherNavigation` gives navigation-app priority
+/// - `showsBackgroundLocationIndicator = true` shows the blue pill on status bar
+public class BGLLocationManager: NSObject, CLLocationManagerDelegate, BGLLocationProvider {
+
+    /// Accuracy threshold above which a location is considered SLC-delivered (not standard GPS).
+    /// SLC typically delivers accuracy of ~500m; standard GPS is usually <100m after warm-up.
+    private static let slcAccuracyThreshold: CLLocationDistance = 200
+
+    /// Speed threshold (m/s) above which the device is considered moving.
+    /// Used to derive the `isMoving` flag sent to JS and HTTP layers.
+    public static let motionSpeedThreshold: Double = 0.5
+
+    /// Callback fired on each new location update.
+    public var onLocation: ((CLLocation, Bool) -> Void)?
+
+    /// Callback fired when authorization status changes.
+    public var onProviderChange: ((CLAuthorizationStatus) -> Void)?
+
+    /// Callback fired when accuracy authorization changes (iOS 14+).
+    public var onAccuracyChange: ((CLAccuracyAuthorization) -> Void)?
+
+    /// Callback fired when Significant Location Change wakes the app and restarts tracking.
+    public var onSignificantLocationChange: (() -> Void)?
+
+    /// Whether tracking is currently active.
+    public private(set) var isTracking = false
+
+    /// Guards against repeated SLC restart calls while GPS is warming up.
+    private var slcRestartFired = false
+
+    /// Last received location (used by heartbeat for force-emit).
+    public private(set) var lastKnownLocation: CLLocation?
+
+    /// Whether user has granted at least "When In Use" authorization.
+    public var isAuthorized: Bool {
+        let status = manager.authorizationStatus
+        return status == .authorizedAlways || status == .authorizedWhenInUse
+    }
+
+    /// Current authorization status (exposed for permission checks).
+    public var authorizationStatus: CLAuthorizationStatus {
+        manager.authorizationStatus
+    }
+
+    /// Current accuracy authorization (iOS 14+: fullAccuracy or reducedAccuracy).
+    public var accuracyAuthorization: CLAccuracyAuthorization {
+        manager.accuracyAuthorization
+    }
+
+    /// Whether the user has granted full accuracy (precise GPS).
+    public var isFullAccuracy: Bool {
+        accuracyAuthorization == .fullAccuracy
+    }
+
+    /// One-shot callback fired when authorization status is resolved after a request.
+    public var onAuthorizationResolved: ((CLAuthorizationStatus) -> Void)?
+
+    /// Request "Always" authorization (triggers the system prompt if status is .notDetermined).
+    public func requestWhenInUseAuthorization() {
+        manager.requestWhenInUseAuthorization()
+    }
+
+    public func requestAlwaysAuthorization() {
+        manager.requestAlwaysAuthorization()
+    }
+
+    /// Request temporary full accuracy when the user has granted only approximate location.
+    /// The `purposeKey` must match an entry in Info.plist `NSLocationTemporaryUsageDescriptionDictionary`.
+    /// Completion returns the resulting accuracy authorization.
+    public func requestTemporaryFullAccuracy(
+        purposeKey: String, completion: @escaping (CLAccuracyAuthorization) -> Void
+    ) {
+        manager.requestTemporaryFullAccuracyAuthorization(withPurposeKey: purposeKey) {
+            [weak self] error in
+            if let error = error {
+                print(
+                    "BGLocation: requestTemporaryFullAccuracy error — \(error.localizedDescription)"
+                )
+            }
+            let result = self?.accuracyAuthorization ?? .reducedAccuracy
+            completion(result)
+        }
+    }
+
+    private let manager = CLLocationManager()
+    private var previousIsMoving = false
+    private var pendingPositionCompletion: ((CLLocation?) -> Void)?
+
+    /// Current desired accuracy (exposed so callers can reconfigure distanceFilter without changing accuracy).
+    public private(set) var currentDesiredAccuracy: CLLocationAccuracy = kCLLocationAccuracyBest
+
+    public override init() {
+        super.init()
+        manager.delegate = self
+    }
+
+    // MARK: - Configuration
+
+    public func configure(distanceFilter: Double, desiredAccuracy: CLLocationAccuracy) {
+        currentDesiredAccuracy = desiredAccuracy
+        manager.desiredAccuracy = desiredAccuracy
+        manager.distanceFilter = distanceFilter
+
+        // CRITICAL: Must be set before app enters background.
+        // Only set when the host app declares "location" in UIBackgroundModes —
+        // setting this without the entitlement crashes (NSInternalInconsistencyException).
+        if let modes = Bundle.main.object(forInfoDictionaryKey: "UIBackgroundModes") as? [String],
+            modes.contains("location")
+        {
+            manager.allowsBackgroundLocationUpdates = true
+            manager.showsBackgroundLocationIndicator = true
+        }
+
+        // CRITICAL: false prevents iOS from auto-pausing location when stationary
+        manager.pausesLocationUpdatesAutomatically = false
+
+        // Navigation apps get higher priority for background execution
+        manager.activityType = .otherNavigation
+    }
+
+    /// Update only the distance filter without resetting other CLLocationManager properties.
+    /// Used by the adaptive distance filter to reconfigure on-the-fly.
+    public func updateDistanceFilter(_ distance: Double) {
+        manager.distanceFilter = distance
+    }
+
+    // MARK: - Tracking
+
+    public func startTracking() {
+        if manager.authorizationStatus == .notDetermined {
+            manager.requestWhenInUseAuthorization()
+        }
+        slcRestartFired = false
+        manager.startUpdatingLocation()
+
+        // C.1: Start Significant Location Change monitoring as a watchdog.
+        // SLC survives app termination by iOS. When the app is relaunched via SLC,
+        // didUpdateLocations fires → we restart standard location updates automatically.
+        manager.startMonitoringSignificantLocationChanges()
+
+        isTracking = true
+    }
+
+    public func stopTracking() {
+        manager.stopUpdatingLocation()
+        manager.stopMonitoringSignificantLocationChanges()
+        isTracking = false
+    }
+
+    /// Request the current position with a timeout.
+    ///
+    /// Returns the last known location if it's fresh enough (within `timeout` seconds),
+    /// otherwise triggers a one-shot `requestLocation()` and waits up to `timeout`
+    /// for a fresh fix.
+    public func requestCurrentPosition(
+        timeout: TimeInterval, completion: @escaping (CLLocation?) -> Void
+    ) {
+        // Return last known location if fresh enough
+        if let location = lastKnownLocation,
+            Date().timeIntervalSince(location.timestamp) < timeout
+        {
+            completion(location)
+            return
+        }
+
+        // Otherwise try manager's cached location
+        if let location = manager.location,
+            Date().timeIntervalSince(location.timestamp) < timeout
+        {
+            completion(location)
+            return
+        }
+
+        // Request a fresh fix via one-shot requestLocation()
+        pendingPositionCompletion = completion
+        manager.requestLocation()
+
+        // Timeout: if no location arrives within `timeout` seconds, return nil
+        let deadline = DispatchTime.now() + timeout
+        DispatchQueue.main.asyncAfter(deadline: deadline) { [weak self] in
+            guard let self = self, let pending = self.pendingPositionCompletion else { return }
+            self.pendingPositionCompletion = nil
+            pending(self.lastKnownLocation)
+        }
+    }
+
+    // MARK: - CLLocationManagerDelegate
+
+    public func locationManager(
+        _ manager: CLLocationManager, didUpdateLocations locations: [CLLocation]
+    ) {
+        guard let location = locations.last else { return }
+        lastKnownLocation = location
+
+        // C.1: If tracking was active but standard updates were stopped by iOS
+        // (e.g., app was suspended/terminated and relaunched via SLC), restart them.
+        if isTracking && !slcRestartFired {
+            let isSLCAccuracy = location.horizontalAccuracy > Self.slcAccuracyThreshold
+            if isSLCAccuracy {
+                slcRestartFired = true
+                manager.startUpdatingLocation()
+                onSignificantLocationChange?()
+                print("BGLocation: SLC watchdog fired — restarting standard location updates")
+            }
+        }
+
+        // Resolve pending getCurrentPosition() request
+        if let pending = pendingPositionCompletion {
+            pendingPositionCompletion = nil
+            pending(location)
+        }
+
+        let isMoving = location.speed > Self.motionSpeedThreshold
+        let motionChanged = isMoving != previousIsMoving
+        previousIsMoving = isMoving
+
+        #if DEBUG
+            if onLocation == nil {
+                print(
+                    "BGLocation: \u{26A0}\u{FE0F} location update received but no onLocation callback registered"
+                )
+            }
+        #endif
+        onLocation?(location, isMoving)
+
+        if motionChanged {
+            print("BGLocation: motion change — isMoving=\(isMoving)")
+        }
+    }
+
+    public func locationManager(_ manager: CLLocationManager, didFailWithError error: Error) {
+        print("BGLocation: location error — \(error.localizedDescription)")
+
+        // Resolve pending getCurrentPosition() on error
+        if let pending = pendingPositionCompletion {
+            pendingPositionCompletion = nil
+            pending(lastKnownLocation)
+        }
+    }
+
+    public func locationManagerDidChangeAuthorization(_ manager: CLLocationManager) {
+        let status = manager.authorizationStatus
+        let accuracy = manager.accuracyAuthorization
+        print(
+            "BGLocation: authorization changed — status=\(status.rawValue), accuracy=\(accuracy == .fullAccuracy ? "full" : "reduced")"
+        )
+        #if DEBUG
+            if onProviderChange == nil {
+                print(
+                    "BGLocation: \u{26A0}\u{FE0F} authorization changed but no onProviderChange callback registered"
+                )
+            }
+        #endif
+        onProviderChange?(status)
+        onAccuracyChange?(accuracy)
+        // Resolve pending requestPermissions() call
+        onAuthorizationResolved?(status)
+        onAuthorizationResolved = nil
+    }
+}

package/ios/Sources/BGLocationCore/Location/BGLPermissionManager.swift

@@ -0,0 +1,33 @@
+import CoreLocation
+import Foundation
+
+/// Maps CLAuthorizationStatus into JS-friendly permission status dictionaries.
+/// Extracted from BackgroundLocationPlugin to reduce bridge complexity.
+public enum BGLPermissionManager {
+
+    /// Build permission status dictionary from CLAuthorizationStatus.
+    public static func permissionStatusDict(_ status: CLAuthorizationStatus) -> [String: String] {
+        let locationState: String
+        let bgState: String
+
+        switch status {
+        case .authorizedAlways:
+            locationState = "granted"
+            bgState = "granted"
+        case .authorizedWhenInUse:
+            locationState = "granted"
+            bgState = "prompt"
+        case .denied, .restricted:
+            locationState = "denied"
+            bgState = "denied"
+        case .notDetermined:
+            locationState = "prompt"
+            bgState = "prompt"
+        @unknown default:
+            locationState = "prompt"
+            bgState = "prompt"
+        }
+
+        return ["location": locationState, "backgroundLocation": bgState]
+    }
+}