@bglocation/capacitor 1.1.0

package/ios/Sources/BGLocationCore/Geofence/BGLGeofenceManager.swift

@@ -0,0 +1,538 @@
+import CoreLocation
+import Foundation
+
+/// Provides the last known location for geofence event enrichment.
+/// Implemented by `BGLLocationManager` to avoid creating a second CLLocationManager.
+public protocol BGLLocationProvider: AnyObject {
+    var lastKnownLocation: CLLocation? { get }
+}
+
+/// Abstracts CLLocationManager region monitoring for testability.
+public protocol BGLRegionMonitoring: AnyObject {
+    var delegate: CLLocationManagerDelegate? { get set }
+    var monitoredRegions: Set<CLRegion> { get }
+    func startMonitoring(for region: CLRegion)
+    func stopMonitoring(for region: CLRegion)
+}
+
+extension CLLocationManager: BGLRegionMonitoring {}
+
+/// Manages iOS geofencing via CLLocationManager region monitoring with UserDefaults persistence.
+///
+/// - Persistence (UserDefaults) is the source of truth for `getGeofences()`.
+/// - CLLocationManager supports up to 20 monitored regions simultaneously.
+/// - Region monitoring works in background and after app termination.
+/// - `didStartMonitoringFor` / `monitoringDidFailFor` delegates handle async registration results.
+public class BGLGeofenceManager: NSObject, CLLocationManagerDelegate {
+
+    public static let maxGeofences = 20
+
+    private let regionMonitor: BGLRegionMonitoring
+    private let defaults: UserDefaults
+    private static let defaultsKey = "bgl_geofences_json"
+
+    /// External location provider (avoids a second CLLocationManager for location reads).
+    public weak var locationProvider: BGLLocationProvider?
+
+    /// Callback fired on geofence transitions.
+    public var onGeofenceEvent: ((GeofenceEventData) -> Void)?
+
+    /// Debug logger — set by the plugin bridge to enable geofence event logging.
+    public weak var debug: BGLDebugLogger?
+
+    /// In-memory cache — invalidated on every save. Avoids repeated JSON deserialization.
+    private var cachedGeofences: [GeofenceConfig]?
+
+    /// Pending async registration callbacks keyed by region identifier.
+    private var pendingRegistrations: [String: (onSuccess: () -> Void, onError: (String) -> Void)] =
+        [:]
+
+    /// Active dwell timers keyed by region identifier.
+    private var dwellTimers: [String: DispatchSourceTimer] = [:]
+
+    /// UserDefaults key prefix for dwell enter timestamps (retroactive dwell on app wake).
+    private static let dwellTimestampPrefix = "bgl_dwell_enter_"
+
+    /// When true, CLLocationManager operations and `pendingRegistrations` access
+    /// are dispatched to the main thread. Required because Capacitor calls plugin
+    /// methods on a background serial queue that has no run loop — without dispatch,
+    /// CLLocationManager delegate callbacks are never delivered.
+    /// Disabled when a custom (mock) `regionMonitor` is injected for tests.
+    private let useMainThreadDispatch: Bool
+
+    /// Whether any geofences are currently registered.
+    public var hasGeofences: Bool {
+        !getGeofences().isEmpty
+    }
+
+    public init(
+        defaults: UserDefaults = UserDefaults(suiteName: "dev.bglocation.geofences") ?? .standard,
+        regionMonitor: BGLRegionMonitoring? = nil,
+        useMainThreadDispatch: Bool? = nil
+    ) {
+        self.defaults = defaults
+        self.useMainThreadDispatch = useMainThreadDispatch ?? (regionMonitor == nil)
+
+        if let regionMonitor = regionMonitor {
+            self.regionMonitor = regionMonitor
+        } else {
+            // CLLocationManager must be created on the main thread — delegate
+            // callbacks are delivered on the creating thread's run loop.
+            // Capacitor's plugin call queue has no run loop.
+            if Thread.isMainThread {
+                self.regionMonitor = CLLocationManager()
+            } else {
+                var mgr: CLLocationManager!
+                DispatchQueue.main.sync { mgr = CLLocationManager() }
+                self.regionMonitor = mgr
+            }
+        }
+        super.init()
+        self.regionMonitor.delegate = self
+    }
+
+    /// Execute a block on the main thread (for CLLocationManager operations)
+    /// or synchronously when using a mock in tests.
+    private func dispatchOnMain(_ work: @escaping () -> Void) {
+        if useMainThreadDispatch && !Thread.isMainThread {
+            DispatchQueue.main.async(execute: work)
+        } else {
+            work()
+        }
+    }
+
+    // MARK: - Public API
+
+    /// Add a single geofence. Replaces existing geofence with the same identifier.
+    /// Success/error callbacks are fired asynchronously after the OS confirms registration.
+    public func addGeofence(
+        _ geofence: GeofenceConfig, onSuccess: @escaping () -> Void,
+        onError: @escaping (String) -> Void
+    ) {
+        var current = getGeofences()
+
+        // Replace existing with same identifier
+        current.removeAll { $0.identifier == geofence.identifier }
+
+        if current.count >= Self.maxGeofences {
+            onError("Cannot add geofence — limit of \(Self.maxGeofences) reached.")
+            return
+        }
+
+        current.append(geofence)
+        saveGeofences(current)
+
+        registerNativeGeofence(geofence, onSuccess: onSuccess, onError: onError)
+    }
+
+    /// Add multiple geofences atomically. If total would exceed limit, none are added.
+    /// The onSuccess callback fires only after all regions are confirmed by the OS.
+    public func addGeofences(
+        _ geofences: [GeofenceConfig], onSuccess: @escaping () -> Void,
+        onError: @escaping (String) -> Void
+    ) {
+        var current = getGeofences()
+
+        let newIdentifiers = Set(geofences.map { $0.identifier })
+        current.removeAll { newIdentifiers.contains($0.identifier) }
+
+        if current.count + geofences.count > Self.maxGeofences {
+            onError("Cannot add geofences — would exceed limit of \(Self.maxGeofences).")
+            return
+        }
+
+        current.append(contentsOf: geofences)
+        saveGeofences(current)
+
+        registerNativeGeofences(geofences, onSuccess: onSuccess, onError: onError)
+    }
+
+    /// Remove a geofence by identifier. No-op if not found.
+    public func removeGeofence(identifier: String) {
+        var current = getGeofences()
+        current.removeAll { $0.identifier == identifier }
+        saveGeofences(current)
+        cancelDwellTimer(for: identifier)
+
+        dispatchOnMain { [self] in
+            pendingRegistrations.removeValue(forKey: identifier)
+            for region in regionMonitor.monitoredRegions {
+                if region.identifier == identifier {
+                    regionMonitor.stopMonitoring(for: region)
+                    break
+                }
+            }
+        }
+        print("BGLocation: Geofence removed: \(identifier)")
+    }
+
+    /// Remove all registered geofences.
+    public func removeAllGeofences() {
+        let current = getGeofences()
+        saveGeofences([])
+        cancelAllDwellTimers()
+
+        dispatchOnMain { [self] in
+            pendingRegistrations.removeAll()
+            for region in regionMonitor.monitoredRegions {
+                if current.contains(where: { $0.identifier == region.identifier }) {
+                    regionMonitor.stopMonitoring(for: region)
+                }
+            }
+        }
+        print("BGLocation: All geofences removed (\(current.count))")
+    }
+
+    /// Get all registered geofences from the cache (backed by persistence).
+    public func getGeofences() -> [GeofenceConfig] {
+        if let cached = cachedGeofences { return cached }
+        let loaded = loadGeofences()
+        cachedGeofences = loaded
+        return loaded
+    }
+
+    /// Re-register all persisted geofences with the system.
+    /// Called after configure() to restore geofences (e.g. after app relaunch).
+    /// Also checks for retroactive dwell events from timestamps saved before termination.
+    public func reRegisterAllGeofences() {
+        let geofences = getGeofences()
+        guard !geofences.isEmpty else { return }
+
+        for geofence in geofences {
+            registerNativeGeofence(geofence)
+        }
+        checkPendingDwells()
+        print("BGLocation: Re-registered \(geofences.count) geofences")
+    }
+
+    // MARK: - Native Region Registration
+
+    /// Register a single geofence with optional async callbacks.
+    /// When callbacks are provided, they are stored as pending and resolved
+    /// by `didStartMonitoringFor` / `monitoringDidFailFor` delegate callbacks.
+    ///
+    /// All `pendingRegistrations` access and `regionMonitor` calls are dispatched
+    /// to the main thread to ensure CLLocationManager delegate delivery.
+    private func registerNativeGeofence(
+        _ geofence: GeofenceConfig,
+        onSuccess: (() -> Void)? = nil,
+        onError: ((String) -> Void)? = nil
+    ) {
+        let center = CLLocationCoordinate2D(
+            latitude: geofence.latitude, longitude: geofence.longitude)
+        let region = CLCircularRegion(
+            center: center, radius: geofence.radius, identifier: geofence.identifier)
+
+        region.notifyOnEntry = geofence.notifyOnEntry
+        region.notifyOnExit = geofence.notifyOnExit
+
+        dispatchOnMain { [self] in
+            if let onSuccess = onSuccess, let onError = onError {
+                pendingRegistrations[geofence.identifier] = (onSuccess: onSuccess, onError: onError)
+            }
+            regionMonitor.startMonitoring(for: region)
+        }
+    }
+
+    /// Register multiple geofences. onSuccess fires after all succeed, onError on first failure.
+    /// On failure, all batch identifiers are rolled back from persistence and already-registered
+    /// regions are stopped — matching Android's atomic `GeofencingClient.addGeofences()` behavior.
+    ///
+    /// Thread-safety note: All `pendingRegistrations` access and `regionMonitor` calls are
+    /// dispatched to the main thread via `dispatchOnMain`, so `remaining` / `failed` access
+    /// is race-free.
+    private func registerNativeGeofences(
+        _ geofences: [GeofenceConfig],
+        onSuccess: @escaping () -> Void,
+        onError: @escaping (String) -> Void
+    ) {
+        guard !geofences.isEmpty else {
+            onSuccess()
+            return
+        }
+
+        let batchIdentifiers = Set(geofences.map { $0.identifier })
+        var remaining = geofences.count
+        var failed = false
+        var succeededIdentifiers: [String] = []
+
+        for geofence in geofences {
+            // Skip remaining registrations if a previous one already failed
+            guard !failed else { break }
+
+            let wrappedError: (String) -> Void = { [weak self] errorMsg in
+                guard !failed else { return }
+                failed = true
+
+                // Roll back ALL batch identifiers from persistence
+                if let self = self {
+                    var current = self.getGeofences()
+                    current.removeAll { batchIdentifiers.contains($0.identifier) }
+                    self.saveGeofences(current)
+
+                    // Stop monitoring regions that already succeeded in this batch
+                    for region in self.regionMonitor.monitoredRegions
+                    where succeededIdentifiers.contains(region.identifier) {
+                        self.regionMonitor.stopMonitoring(for: region)
+                    }
+                }
+
+                onError(errorMsg)
+            }
+            let wrappedSuccess: () -> Void = { [weak self] in
+                guard !failed else { return }
+                if let identifier = self?.findGeofence(identifier: geofence.identifier)?.identifier
+                {
+                    succeededIdentifiers.append(identifier)
+                }
+                remaining -= 1
+                if remaining == 0 {
+                    onSuccess()
+                }
+            }
+            registerNativeGeofence(geofence, onSuccess: wrappedSuccess, onError: wrappedError)
+        }
+    }
+
+    // MARK: - CLLocationManagerDelegate — Region Monitoring
+
+    public func locationManager(
+        _ manager: CLLocationManager, didStartMonitoringFor region: CLRegion
+    ) {
+        if let pending = pendingRegistrations.removeValue(forKey: region.identifier) {
+            pending.onSuccess()
+        }
+        print("BGLocation: Geofence registered: \(region.identifier)")
+    }
+
+    public func locationManager(_ manager: CLLocationManager, didEnterRegion region: CLRegion) {
+        guard let circularRegion = region as? CLCircularRegion else { return }
+        let geofence = findGeofence(identifier: circularRegion.identifier)
+        emitEvent(identifier: circularRegion.identifier, action: "enter", extras: geofence?.extras)
+
+        // Start dwell timer if configured
+        if let geofence = geofence, geofence.notifyOnDwell {
+            startDwellTimer(for: geofence)
+        }
+    }
+
+    public func locationManager(_ manager: CLLocationManager, didExitRegion region: CLRegion) {
+        guard let circularRegion = region as? CLCircularRegion else { return }
+        let geofence = findGeofence(identifier: circularRegion.identifier)
+
+        // Cancel dwell timer — user left the region before dwell delay elapsed
+        cancelDwellTimer(for: circularRegion.identifier)
+
+        emitEvent(identifier: circularRegion.identifier, action: "exit", extras: geofence?.extras)
+    }
+
+    public func locationManager(
+        _ manager: CLLocationManager, monitoringDidFailFor region: CLRegion?, withError error: Error
+    ) {
+        let identifier = region?.identifier ?? "unknown"
+        print(
+            "BGLocation: Geofence monitoring failed for \(identifier): \(error.localizedDescription)"
+        )
+
+        // Reject pending registration callback and roll back persistence
+        if let pending = pendingRegistrations.removeValue(forKey: identifier) {
+            var current = getGeofences()
+            current.removeAll { $0.identifier == identifier }
+            saveGeofences(current)
+            pending.onError(
+                "Geofence monitoring failed for \(identifier): \(error.localizedDescription)")
+        }
+    }
+
+    private func emitEvent(identifier: String, action: String, extras: [String: String]?) {
+        let location: BGLLocationData?
+        if let clLocation = locationProvider?.lastKnownLocation {
+            location = BGLLocationHelpers.mapLocation(clLocation, isMoving: false)
+        } else {
+            location = nil
+        }
+
+        let event = GeofenceEventData(
+            identifier: identifier,
+            action: action,
+            location: location,
+            extras: extras,
+            timestamp: Date().timeIntervalSince1970 * 1000
+        )
+        debug?.logGeofenceEvent(identifier: identifier, action: action)
+        onGeofenceEvent?(event)
+    }
+
+    // MARK: - Dwell Timer (iOS-specific — no native dwell support in CLLocationManager)
+
+    /// Start a DispatchSourceTimer that fires a "dwell" event after `dwellDelay` seconds.
+    /// Also persists the enter timestamp in UserDefaults for retroactive dwell on app wake.
+    private func startDwellTimer(for geofence: GeofenceConfig) {
+        cancelDwellTimer(for: geofence.identifier)
+
+        // Persist enter timestamp for retroactive dwell after app termination
+        let key = Self.dwellTimestampPrefix + geofence.identifier
+        defaults.set(Date().timeIntervalSince1970, forKey: key)
+
+        let timer = DispatchSource.makeTimerSource(queue: .main)
+        timer.schedule(deadline: .now() + .seconds(geofence.dwellDelay))
+        timer.setEventHandler { [weak self] in
+            self?.dwellTimers.removeValue(forKey: geofence.identifier)
+            self?.defaults.removeObject(forKey: key)
+            self?.emitEvent(
+                identifier: geofence.identifier, action: "dwell", extras: geofence.extras)
+        }
+        dwellTimers[geofence.identifier] = timer
+        timer.resume()
+    }
+
+    /// Cancel a dwell timer and remove the persisted enter timestamp.
+    private func cancelDwellTimer(for identifier: String) {
+        if let timer = dwellTimers.removeValue(forKey: identifier) {
+            timer.cancel()
+        }
+        defaults.removeObject(forKey: Self.dwellTimestampPrefix + identifier)
+    }
+
+    /// Cancel all active dwell timers and remove all persisted enter timestamps.
+    private func cancelAllDwellTimers() {
+        for (identifier, timer) in dwellTimers {
+            timer.cancel()
+            defaults.removeObject(forKey: Self.dwellTimestampPrefix + identifier)
+        }
+        dwellTimers.removeAll()
+    }
+
+    /// Check persisted dwell enter timestamps and emit retroactive dwell events
+    /// for regions where the user has been inside longer than `dwellDelay`.
+    /// Called on app wake / reRegisterAllGeofences() — handles the case where
+    /// DispatchSourceTimer didn't survive app termination.
+    private func checkPendingDwells() {
+        let now = Date().timeIntervalSince1970
+        for geofence in getGeofences() where geofence.notifyOnDwell {
+            let key = Self.dwellTimestampPrefix + geofence.identifier
+            let enterTimestamp = defaults.double(forKey: key)
+            guard enterTimestamp > 0 else { continue }
+
+            let elapsed = now - enterTimestamp
+            if elapsed >= Double(geofence.dwellDelay) {
+                // Dwell time has elapsed while app was terminated — emit retroactive event
+                defaults.removeObject(forKey: key)
+                emitEvent(identifier: geofence.identifier, action: "dwell", extras: geofence.extras)
+                print(
+                    "BGLocation: Retroactive dwell event for \(geofence.identifier) (elapsed: \(Int(elapsed))s)"
+                )
+            }
+            // If elapsed < dwellDelay, the timer will be (re-)started when the next
+            // region event arrives. We don't restart timers here because we can't know
+            // for certain the user is still inside the region after termination.
+        }
+    }
+
+    // MARK: - Persistence (UserDefaults JSON)
+
+    private func loadGeofences() -> [GeofenceConfig] {
+        guard let data = defaults.data(forKey: Self.defaultsKey) else { return [] }
+        do {
+            return try JSONDecoder().decode([GeofenceConfig].self, from: data)
+        } catch {
+            print("BGLocation: Failed to decode geofences: \(error.localizedDescription)")
+            return []
+        }
+    }
+
+    private func saveGeofences(_ geofences: [GeofenceConfig]) {
+        cachedGeofences = geofences
+        do {
+            let data = try JSONEncoder().encode(geofences)
+            defaults.set(data, forKey: Self.defaultsKey)
+        } catch {
+            print("BGLocation: Failed to encode geofences: \(error.localizedDescription)")
+        }
+    }
+
+    private func findGeofence(identifier: String) -> GeofenceConfig? {
+        getGeofences().first { $0.identifier == identifier }
+    }
+}
+
+// MARK: - Data Models
+
+/// Geofence configuration stored in persistence.
+public struct GeofenceConfig: Codable, Equatable {
+    public let identifier: String
+    public let latitude: Double
+    public let longitude: Double
+    public let radius: Double
+    public let notifyOnEntry: Bool
+    public let notifyOnExit: Bool
+    public let notifyOnDwell: Bool
+    public let dwellDelay: Int
+    public let extras: [String: String]?
+
+    public init(
+        identifier: String,
+        latitude: Double,
+        longitude: Double,
+        radius: Double,
+        notifyOnEntry: Bool = true,
+        notifyOnExit: Bool = true,
+        notifyOnDwell: Bool = false,
+        dwellDelay: Int = 300,
+        extras: [String: String]? = nil
+    ) {
+        self.identifier = identifier
+        self.latitude = latitude
+        self.longitude = longitude
+        self.radius = radius
+        self.notifyOnEntry = notifyOnEntry
+        self.notifyOnExit = notifyOnExit
+        self.notifyOnDwell = notifyOnDwell
+        self.dwellDelay = dwellDelay
+        self.extras = extras
+    }
+
+    /// Convert to a dictionary suitable for the Capacitor JS bridge.
+    public func toDict() -> [String: Any] {
+        var dict: [String: Any] = [
+            "identifier": identifier,
+            "latitude": latitude,
+            "longitude": longitude,
+            "radius": radius,
+            "notifyOnEntry": notifyOnEntry,
+            "notifyOnExit": notifyOnExit,
+            "notifyOnDwell": notifyOnDwell,
+            "dwellDelay": dwellDelay,
+        ]
+        if let extras = extras {
+            dict["extras"] = extras
+        }
+        return dict
+    }
+}
+
+/// Geofence event emitted to JS layer.
+public struct GeofenceEventData {
+    public let identifier: String
+    public let action: String  // "enter", "exit", "dwell"
+    public let location: BGLLocationData?
+    public let extras: [String: String]?
+    public let timestamp: Double
+
+    public func toDict() -> [String: Any] {
+        var dict: [String: Any] = [
+            "identifier": identifier,
+            "action": action,
+            "timestamp": timestamp,
+        ]
+        if let location = location {
+            dict["location"] = location.toDict()
+        } else {
+            dict["location"] = NSNull()
+        }
+        if let extras = extras {
+            dict["extras"] = extras
+        }
+        return dict
+    }
+}