@bglocation/capacitor 1.1.0

package/ios/Sources/BackgroundLocationPlugin/BackgroundLocationPlugin.swift

@@ -0,0 +1,657 @@
+import BGLocationCore
+import Capacitor
+import CoreLocation
+import Foundation
+
+/// Capacitor plugin bridging JS ↔ iOS native background location tracking.
+@objc(BackgroundLocationPlugin)
+public class BackgroundLocationPlugin: CAPPlugin, CAPBridgedPlugin {
+
+    public let identifier = "BackgroundLocationPlugin"
+    public let jsName = "BackgroundLocation"
+
+    public let pluginMethods: [CAPPluginMethod] = [
+        .init(name: "getVersion", returnType: CAPPluginReturnPromise),
+        .init(name: "checkPermissions", returnType: CAPPluginReturnPromise),
+        .init(name: "requestPermissions", returnType: CAPPluginReturnPromise),
+        .init(name: "configure", returnType: CAPPluginReturnPromise),
+        .init(name: "start", returnType: CAPPluginReturnPromise),
+        .init(name: "stop", returnType: CAPPluginReturnPromise),
+        .init(name: "getState", returnType: CAPPluginReturnPromise),
+        .init(name: "getCurrentPosition", returnType: CAPPluginReturnPromise),
+        .init(name: "checkBatteryOptimization", returnType: CAPPluginReturnPromise),
+        .init(name: "requestBatteryOptimization", returnType: CAPPluginReturnPromise),
+        .init(name: "addGeofence", returnType: CAPPluginReturnPromise),
+        .init(name: "addGeofences", returnType: CAPPluginReturnPromise),
+        .init(name: "removeGeofence", returnType: CAPPluginReturnPromise),
+        .init(name: "removeAllGeofences", returnType: CAPPluginReturnPromise),
+        .init(name: "getGeofences", returnType: CAPPluginReturnPromise),
+    ]
+
+    private let locationManager = BGLLocationManager()
+    internal var heartbeatTimer: BGLHeartbeatTimer?
+    private var heartbeatInterval: Int = 15
+    private var pendingPermissionCall: CAPPluginCall?
+    private var isConfigured = false
+    private lazy var geofenceManager = BGLGeofenceManager()
+    /// Timeout for iOS permission resolution fallback.
+    /// iOS 13.4+ may grant provisional "Always" without triggering a delegate callback.
+    private static let permissionTimeoutSeconds: TimeInterval = 3.0
+
+    internal var httpSender: BGLHttpSender = BGLHttpSender()
+    internal var locationBuffer: BGLLocationBuffer?
+    internal var debug: BGLDebugLogger = BGLDebugLogger()
+
+    // Adaptive distance filter
+    internal var adaptiveFilter: BGLAdaptiveFilter?
+    private var distanceFilterMode: String = "fixed"
+
+    // Licensing
+    internal lazy var licenseEnforcer = BGLLicenseEnforcer(
+        defaults: UserDefaults(suiteName: "dev.bglocation.license")!
+    )
+    internal var licenseMode: LicenseMode { licenseEnforcer.licenseMode }
+    internal var trialTimer: BGLTrialTimer? { licenseEnforcer.trialTimer }
+
+    /// Build epoch for update gating. Updated by pre-build script before release.
+    /// GENERATED — do not edit manually
+    private static let pluginBuildEpoch: Int = 1774777856
+
+    // MARK: - Version
+
+    @objc func getVersion(_ call: CAPPluginCall) {
+        call.resolve([
+            "pluginVersion": "1.1.0",
+            "coreVersion": BGLVersion.version,
+        ])
+    }
+
+    // MARK: - Permission Methods
+
+    @objc public override func checkPermissions(_ call: CAPPluginCall) {
+        let status = locationManager.authorizationStatus
+        call.resolve(BGLPermissionManager.permissionStatusDict(status))
+    }
+
+    @objc public override func requestPermissions(_ call: CAPPluginCall) {
+        let permissions = call.getArray("permissions", String.self) ?? ["location"]
+        let requestBackground = permissions.contains("backgroundLocation")
+        let status = locationManager.authorizationStatus
+
+        if requestBackground {
+            // Step 2: Escalate from "When In Use" → "Always"
+            if status == .authorizedWhenInUse {
+                pendingPermissionCall = call
+                locationManager.onAuthorizationResolved = { [weak self] newStatus in
+                    guard let self = self, let pending = self.pendingPermissionCall else { return }
+                    pending.resolve(BGLPermissionManager.permissionStatusDict(newStatus))
+                    self.pendingPermissionCall = nil
+                }
+                locationManager.requestAlwaysAuthorization()
+
+                // Fallback: resolve after timeout for iOS 13.4+ provisional grant.
+                DispatchQueue.main.asyncAfter(deadline: .now() + Self.permissionTimeoutSeconds) {
+                    [weak self] in
+                    guard let self = self, let pending = self.pendingPermissionCall else { return }
+                    let currentStatus = self.locationManager.authorizationStatus
+                    pending.resolve(BGLPermissionManager.permissionStatusDict(currentStatus))
+                    self.pendingPermissionCall = nil
+                    self.locationManager.onAuthorizationResolved = nil
+                }
+            } else {
+                // Already "Always", denied, or not determined — return current status
+                checkPermissions(call)
+            }
+        } else {
+            // Step 1: Request "When In Use"
+            if status == .notDetermined {
+                pendingPermissionCall = call
+                locationManager.onAuthorizationResolved = { [weak self] newStatus in
+                    guard let self = self, let pending = self.pendingPermissionCall else { return }
+                    pending.resolve(BGLPermissionManager.permissionStatusDict(newStatus))
+                    self.pendingPermissionCall = nil
+                }
+                locationManager.requestWhenInUseAuthorization()
+            } else {
+                checkPermissions(call)
+            }
+        }
+    }
+
+    // MARK: - Plugin Methods
+
+    @objc func configure(_ call: CAPPluginCall) {
+        BGLBuildConfig.buildEpoch = Self.pluginBuildEpoch
+        let parsed = BGLConfigParser.parse(call.options as? [String: Any] ?? [:])
+        heartbeatInterval = parsed.heartbeatInterval
+        distanceFilterMode = parsed.distanceFilterMode
+
+        // Adaptive distance filter setup
+        if let autoConfig = parsed.autoDistanceFilterConfig {
+            adaptiveFilter = BGLAdaptiveFilter(config: autoConfig)
+        } else {
+            adaptiveFilter = nil
+        }
+
+        // Debug config
+        debug.configure(debug: parsed.isDebug, debugSounds: parsed.debugSounds)
+        debug.onDebug = { [weak self] message in
+            self?.notifyListeners(
+                "onDebug",
+                data: [
+                    "message": message,
+                    "timestamp": Date().timeIntervalSince1970 * 1000,
+                ])
+        }
+
+        // HTTP config
+        if let url = parsed.httpUrl {
+            httpSender.configure(url: url, headers: parsed.httpHeaders)
+            httpSender.onFlushProgress = { [weak self] result in
+                DispatchQueue.main.async {
+                    self?.emitHttp(result)
+                }
+            }
+            if let maxSize = parsed.bufferMaxSize {
+                locationBuffer?.close()
+                locationBuffer = BGLLocationBuffer(maxSize: maxSize)
+                locationBuffer?.onOverflow = { [weak self] dropped in
+                    self?.debug.logMessage("BUFFER_OVERFLOW dropped=\(dropped) maxSize=\(maxSize)")
+                }
+                httpSender.setBuffer(locationBuffer)
+                print("BGLocation: Offline buffer configured — maxSize=\(maxSize)")
+            } else {
+                locationBuffer = nil
+                httpSender.setBuffer(nil)
+            }
+        } else {
+            httpSender.configure(url: nil, headers: [:])
+            locationBuffer = nil
+            httpSender.setBuffer(nil)
+        }
+
+        locationManager.configure(
+            distanceFilter: parsed.distanceFilter,
+            desiredAccuracy: BGLLocationHelpers.mapAccuracy(parsed.desiredAccuracy)
+        )
+
+        debug.logConfigure(
+            distanceFilter: parsed.distanceFilter, heartbeat: heartbeatInterval,
+            httpUrl: parsed.httpUrl)
+        print(
+            "BGLocation: BackgroundLocation configured — distanceFilter=\(parsed.distanceFilter), heartbeat=\(heartbeatInterval)s, http=\(parsed.httpUrl ?? "disabled")"
+        )
+
+        // --- License validation ---
+        let licenseKey = getConfig().getString("licenseKey")
+        var configureResult: [String: Any] = [:]
+        configureResult["distanceFilterMode"] = distanceFilterMode
+
+        licenseEnforcer.validateLicense(
+            licenseKey: licenseKey,
+            isDebug: parsed.isDebug,
+            debugSounds: parsed.debugSounds,
+            debug: debug,
+            configureResult: &configureResult,
+            onTrialExpired: { [weak self] in self?.onTrialExpired() }
+        )
+
+        call.resolve(configureResult)
+
+        isConfigured = true
+
+        // Set up geofence event callback and re-register persisted geofences
+        geofenceManager.locationProvider = locationManager
+        geofenceManager.debug = debug
+        geofenceManager.onGeofenceEvent = { [weak self] event in
+            self?.notifyListeners("onGeofence", data: event.toDict())
+        }
+        geofenceManager.reRegisterAllGeofences()
+    }
+
+    @objc func start(_ call: CAPPluginCall) {
+        let status = locationManager.authorizationStatus
+        if status == .denied || status == .restricted {
+            call.reject("Location permission not granted")
+            return
+        }
+
+        // Trial mode: check cooldown before allowing start
+        if let cooldown = licenseEnforcer.checkCooldown() {
+            call.reject(
+                cooldown.message,
+                "TRIAL_COOLDOWN",
+                nil,
+                ["remainingSeconds": cooldown.remainingSeconds, "message": cooldown.message]
+            )
+            return
+        }
+
+        locationManager.onLocation = { [weak self] location, isMoving in
+            self?.emitLocation(location, isMoving: isMoving)
+        }
+
+        locationManager.onProviderChange = { [weak self] status in
+            self?.emitProviderChange(status)
+        }
+
+        locationManager.onAccuracyChange = { [weak self] accuracy in
+            DispatchQueue.main.async {
+                self?.emitAccuracyWarning(authorization: accuracy)
+            }
+        }
+
+        locationManager.onSignificantLocationChange = { [weak self] in
+            DispatchQueue.main.async {
+                self?.debug.logMessage(
+                    "SLC_RESTART — Significant Location Change watchdog restarted standard updates")
+            }
+        }
+
+        locationManager.startTracking()
+        startHeartbeat()
+
+        // Start trial timer if in trial mode
+        licenseEnforcer.startTrialIfNeeded()
+
+        // B.2: Check accuracy authorization and emit warning if approximate
+        checkAndEmitAccuracyWarning()
+
+        debug.logStart()
+        print("BGLocation: BackgroundLocation started")
+        call.resolve(["enabled": true, "tracking": true])
+    }
+
+    /// Internal stop — tears down tracking, clears callbacks, stops heartbeat.
+    /// Shared by stop() and onTrialExpired() to avoid duplicating cleanup logic.
+    private func performStopTracking() {
+        locationManager.stopTracking()
+        locationManager.onAccuracyChange = nil
+        locationManager.onSignificantLocationChange = nil
+        stopHeartbeat()
+    }
+
+    @objc func stop(_ call: CAPPluginCall) {
+        // Only stop the trial timer if no geofences are active
+        licenseEnforcer.stopTrialIfNoGeofences(hasGeofences: geofenceManager.hasGeofences)
+        performStopTracking()
+        adaptiveFilter?.reset()
+
+        debug.logStop()
+        print("BGLocation: BackgroundLocation stopped")
+        call.resolve(["enabled": locationManager.isAuthorized, "tracking": false])
+    }
+
+    @objc func getState(_ call: CAPPluginCall) {
+        call.resolve([
+            "enabled": locationManager.isAuthorized,
+            "tracking": locationManager.isTracking,
+        ])
+    }
+
+    @objc func getCurrentPosition(_ call: CAPPluginCall) {
+        let timeout = call.getDouble("timeout") ?? 20000
+
+        locationManager.requestCurrentPosition(timeout: timeout / 1000.0) { location in
+            if let location = location {
+                call.resolve(BGLLocationHelpers.locationToDict(location, isMoving: false))
+            } else {
+                call.reject(
+                    "Unable to get current position \u{2014} no location available and request timed out"
+                )
+            }
+        }
+    }
+
+    // MARK: - Battery Optimization (B.1 — no-op on iOS)
+
+    @objc func checkBatteryOptimization(_ call: CAPPluginCall) {
+        // iOS does not have OEM battery optimization like Android.
+        // Always return "safe" state.
+        call.resolve([
+            "isIgnoringOptimizations": true,
+            "manufacturer": "",
+            "helpUrl": "",
+            "message": "Battery optimization is not applicable on iOS.",
+        ])
+    }
+
+    @objc func requestBatteryOptimization(_ call: CAPPluginCall) {
+        checkBatteryOptimization(call)
+    }
+
+    // MARK: - Accuracy Warning (B.2)
+
+    /// Check if the user has granted only approximate location, and emit onAccuracyWarning if so.
+    /// If approximate, also attempts to request temporary full accuracy.
+    private func checkAndEmitAccuracyWarning() {
+        guard !locationManager.isFullAccuracy else { return }
+
+        // Emit immediate warning — the user currently has approximate location
+        emitAccuracyWarning(authorization: .reducedAccuracy)
+
+        // Attempt to request temporary full accuracy.
+        // NOTE: If the user grants it, locationManagerDidChangeAuthorization fires
+        // → onAccuracyChange callback → emitAccuracyWarning. We do NOT emit here
+        // to avoid duplicate events.
+        locationManager.requestTemporaryFullAccuracy(purposeKey: "PreciseLocation") { result in
+            DispatchQueue.main.async {
+                if result == .reducedAccuracy {
+                    print(
+                        "BGLocation: User declined temporary full accuracy — tracking with approximate location"
+                    )
+                } else {
+                    print("BGLocation: Temporary full accuracy granted")
+                }
+            }
+        }
+    }
+
+    private func emitAccuracyWarning(authorization: CLAccuracyAuthorization) {
+        let authString = authorization == .fullAccuracy ? "full" : "approximate"
+        let message =
+            authorization == .fullAccuracy
+            ? "Full accuracy location is available."
+            : "Approximate location is active. GPS tracking accuracy is significantly degraded. Please grant precise location in Settings."
+
+        notifyListeners(
+            "onAccuracyWarning",
+            data: [
+                "accuracyAuthorization": authString,
+                "message": message,
+            ])
+    }
+
+    // MARK: - Heartbeat
+
+    private func startHeartbeat() {
+        stopHeartbeat()
+        heartbeatTimer = BGLHeartbeatTimer(intervalSeconds: heartbeatInterval) { [weak self] in
+            // Dispatch to main queue — BGLHeartbeatTimer fires on a .utility background queue
+            // but Capacitor's notifyListeners and debug callbacks must run on main.
+            DispatchQueue.main.async {
+                guard let self = self else { return }
+                let now = Date().timeIntervalSince1970 * 1000
+                let hasLocation = self.locationManager.lastKnownLocation != nil
+                if let location = self.locationManager.lastKnownLocation {
+                    self.notifyListeners(
+                        "onHeartbeat",
+                        data: [
+                            "location": BGLLocationHelpers.mapLocation(location, isMoving: false)
+                                .toDict(),
+                            "timestamp": now,
+                        ])
+                } else {
+                    self.notifyListeners(
+                        "onHeartbeat",
+                        data: [
+                            "location": NSNull(),
+                            "timestamp": now,
+                        ])
+                }
+                self.debug.logHeartbeat(hasLocation: hasLocation)
+            }
+        }
+        heartbeatTimer?.start()
+    }
+
+    private func stopHeartbeat() {
+        heartbeatTimer?.stop()
+        heartbeatTimer = nil
+    }
+
+    // MARK: - Event Emission
+
+    private func emitLocation(_ location: CLLocation, isMoving: Bool) {
+        // Adaptive distance filter — update and reconfigure if needed
+        if let filter = adaptiveFilter {
+            let speed = max(location.speed, 0)
+            let shouldReconfigure = filter.update(speedMps: speed)
+            if shouldReconfigure {
+                let newDistance = filter.effectiveDistanceFilter
+                locationManager.updateDistanceFilter(newDistance)
+                debug.logMessage(
+                    "Auto distance filter: \(Int(newDistance))m (speed: \(String(format: "%.1f", speed))m/s)"
+                )
+            }
+        }
+
+        let locationData = BGLLocationHelpers.mapLocation(location, isMoving: isMoving)
+        var dict = locationData.toDict()
+        if let filter = adaptiveFilter {
+            dict["effectiveDistanceFilter"] = filter.effectiveDistanceFilter
+        }
+        notifyListeners("onLocation", data: dict)
+
+        debug.logLocation(
+            lat: location.coordinate.latitude,
+            lng: location.coordinate.longitude,
+            accuracy: location.horizontalAccuracy,
+            speed: max(location.speed, 0),
+            isMoving: isMoving
+        )
+
+        httpSender.sendLocation(locationData) { [weak self] result in
+            DispatchQueue.main.async {
+                self?.debug.logHttp(
+                    statusCode: result.statusCode, success: result.success, error: result.error)
+                self?.emitHttp(result)
+            }
+        }
+    }
+
+    private func emitProviderChange(_ status: CLAuthorizationStatus) {
+        let enabled: Bool
+        switch status {
+        case .authorizedAlways, .authorizedWhenInUse:
+            enabled = true
+        default:
+            enabled = false
+        }
+
+        notifyListeners(
+            "onProviderChange",
+            data: [
+                "gps": enabled,
+                "network": enabled,
+                "enabled": enabled,
+                "status": status.rawValue,
+            ])
+    }
+
+    private func emitHttp(_ result: BGLHttpResult) {
+        var data: [String: Any] = [
+            "statusCode": result.statusCode,
+            "success": result.success,
+            "responseText": result.responseText,
+            "bufferedCount": result.bufferedCount,
+        ]
+        if let error = result.error {
+            data["error"] = error
+        }
+        notifyListeners("onHttp", data: data)
+    }
+
+    // MARK: - Geofencing Methods
+
+    /// Common guard for all geofence methods: checks isConfigured and trial cooldown.
+    /// Returns `true` if the call should proceed, or rejects and returns `false`.
+    private func guardGeofenceCall(_ call: CAPPluginCall, checkCooldown: Bool = false) -> Bool {
+        guard isConfigured else {
+            call.reject("Plugin not configured. Call configure() first.", "NOT_CONFIGURED")
+            return false
+        }
+        if checkCooldown, let cooldown = licenseEnforcer.checkCooldown() {
+            call.reject(
+                cooldown.message,
+                "TRIAL_COOLDOWN",
+                nil,
+                ["remainingSeconds": cooldown.remainingSeconds]
+            )
+            return false
+        }
+        return true
+    }
+
+    @objc func addGeofence(_ call: CAPPluginCall) {
+        guard guardGeofenceCall(call, checkCooldown: true) else { return }
+
+        guard let identifier = call.getString("identifier") else {
+            call.reject("Missing required parameter: identifier")
+            return
+        }
+        guard let latitude = call.getDouble("latitude"),
+            let longitude = call.getDouble("longitude"),
+            let radius = call.getDouble("radius")
+        else {
+            call.reject("Missing required parameters: latitude, longitude, radius")
+            return
+        }
+
+        var extras: [String: String]?
+        if let extrasObj = call.getObject("extras") {
+            extras = extrasObj.compactMapValues { $0 as? String }
+        }
+
+        let geofence = GeofenceConfig(
+            identifier: identifier,
+            latitude: latitude,
+            longitude: longitude,
+            radius: radius,
+            notifyOnEntry: call.getBool("notifyOnEntry") ?? true,
+            notifyOnExit: call.getBool("notifyOnExit") ?? true,
+            notifyOnDwell: call.getBool("notifyOnDwell") ?? false,
+            dwellDelay: call.getInt("dwellDelay") ?? 300,
+            extras: extras
+        )
+
+        geofenceManager.addGeofence(
+            geofence,
+            onSuccess: { [weak self] in
+                self?.licenseEnforcer.startTrialIfNeeded()
+                self?.debug.logGeofenceAdd(identifier: identifier)
+                call.resolve()
+            },
+            onError: { errorMsg in
+                let code = errorMsg.contains("limit") ? "GEOFENCE_LIMIT_EXCEEDED" : "GEOFENCE_ERROR"
+                call.reject(errorMsg, code)
+            }
+        )
+    }
+
+    @objc func addGeofences(_ call: CAPPluginCall) {
+        guard guardGeofenceCall(call, checkCooldown: true) else { return }
+
+        guard let geofencesArray = call.getArray("geofences") as? [[String: Any]] else {
+            call.reject("Missing required parameter: geofences")
+            return
+        }
+
+        var geofences: [GeofenceConfig] = []
+        for (index, obj) in geofencesArray.enumerated() {
+            guard let identifier = obj["identifier"] as? String,
+                let latitude = obj["latitude"] as? Double,
+                let longitude = obj["longitude"] as? Double,
+                let radius = obj["radius"] as? Double
+            else {
+                call.reject(
+                    "Geofence at index \(index) missing required fields (identifier, latitude, longitude, radius)"
+                )
+                return
+            }
+
+            let extras = obj["extras"] as? [String: String]
+
+            geofences.append(
+                GeofenceConfig(
+                    identifier: identifier,
+                    latitude: latitude,
+                    longitude: longitude,
+                    radius: radius,
+                    notifyOnEntry: obj["notifyOnEntry"] as? Bool ?? true,
+                    notifyOnExit: obj["notifyOnExit"] as? Bool ?? true,
+                    notifyOnDwell: obj["notifyOnDwell"] as? Bool ?? false,
+                    dwellDelay: obj["dwellDelay"] as? Int ?? 300,
+                    extras: extras
+                ))
+        }
+
+        geofenceManager.addGeofences(
+            geofences,
+            onSuccess: { [weak self] in
+                self?.licenseEnforcer.startTrialIfNeeded()
+                self?.debug.logGeofenceAddBatch(count: geofences.count)
+                call.resolve()
+            },
+            onError: { errorMsg in
+                let code = errorMsg.contains("limit") ? "GEOFENCE_LIMIT_EXCEEDED" : "GEOFENCE_ERROR"
+                call.reject(errorMsg, code)
+            }
+        )
+    }
+
+    @objc func removeGeofence(_ call: CAPPluginCall) {
+        guard guardGeofenceCall(call) else { return }
+
+        guard let identifier = call.getString("identifier") else {
+            call.reject("Missing required parameter: identifier")
+            return
+        }
+
+        geofenceManager.removeGeofence(identifier: identifier)
+        debug.logGeofenceRemove(identifier: identifier)
+
+        licenseEnforcer.stopTrialIfIdle(
+            hasGeofences: geofenceManager.hasGeofences,
+            isTracking: locationManager.isTracking
+        )
+
+        call.resolve()
+    }
+
+    @objc func removeAllGeofences(_ call: CAPPluginCall) {
+        guard guardGeofenceCall(call) else { return }
+
+        let count = geofenceManager.getGeofences().count
+        geofenceManager.removeAllGeofences()
+        debug.logGeofenceRemoveAll(count: count)
+
+        licenseEnforcer.stopTrialIfIdle(
+            hasGeofences: false,
+            isTracking: locationManager.isTracking
+        )
+
+        call.resolve()
+    }
+
+    @objc func getGeofences(_ call: CAPPluginCall) {
+        guard guardGeofenceCall(call) else { return }
+
+        let geofences = geofenceManager.getGeofences()
+        let result = geofences.map { $0.toDict() }
+        call.resolve(["geofences": result])
+    }
+
+    // MARK: - Trial Expiration
+
+    /// Called by BGLTrialTimer when the 30-minute trial period expires.
+    /// Auto-stops tracking and emits onTrialExpired event.
+    private func onTrialExpired() {
+        performStopTracking()
+        geofenceManager.removeAllGeofences()
+
+        let cooldownMinutes = BGLTrialTimer.cooldownDurationSeconds / 60
+        notifyListeners(
+            "onTrialExpired",
+            data: [
+                "elapsed": BGLTrialTimer.trialDurationSeconds,
+                "cooldownSeconds": BGLTrialTimer.cooldownDurationSeconds,
+                "message":
+                    "Trial expired. Next start available in \(cooldownMinutes) minutes. Purchase a license for unlimited use.",
+            ])
+        print(
+            "BGLocation: Trial expired — tracking auto-stopped, cooldown started (\(BGLTrialTimer.cooldownDurationSeconds)s)"
+        )
+    }
+
+}