@bricks-soft/capacitor-location-tracking 8.1.0 → 8.2.0

package/ios/Sources/LocationTrackingPlugin/Core/TrackingCore.swift

@@ -0,0 +1,298 @@
+import Foundation
+import CoreLocation
+import CoreMotion
+import UIKit
+import Network
+
+final class TrackingCore {
+    let queue: DispatchQueue
+    let store: TrackingStore
+    let config: TrackingConfig
+    let log: TrackingLog
+    let logExport = LogExport()
+    let permissions: Permissions
+    let positions: Positions
+    let emit: (String, TrackingJSON) -> Void
+    let record: (TrackingJSON) -> Void
+    var ready = false
+    var odometer: Double { runtime.number("odometer") }
+    var runtime: TrackingJSON
+    let clock: () -> TrackingInstant
+    let automaticTimers: Bool
+    var routeSource: RouteSource?
+    lazy var engine = TrackingEngine(core: self)
+    private var network = "other"
+    private var watchIDs = Set<String>()
+    private let monitor = NWPathMonitor()
+    lazy var syncer = Syncer(queue: queue, store: store, config: config, emit: emit)
+
+    init(queue: DispatchQueue, permissions: Permissions, positions: Positions, emit: @escaping (String, TrackingJSON) -> Void, record: @escaping (TrackingJSON) -> Void, url: URL? = nil, clock: @escaping () -> TrackingInstant = TrackingClock.now, automaticTimers: Bool = true, geofenceBackend: GeofenceBackend? = nil) throws {
+        self.clock = clock; self.automaticTimers = automaticTimers
+        self.queue = queue; self.permissions = permissions; self.positions = positions; self.emit = emit; self.record = record
+        let path = try url ?? FileManager.default.url(for: .applicationSupportDirectory, in: .userDomainMask, appropriateFor: nil, create: true).appendingPathComponent("LocationTracking/tracking.sqlite")
+        store = try TrackingStore(url: path)
+        log = TrackingLog(store: store)
+        config = try TrackingConfig(store: store, secrets: SecretStore())
+        log.configure(config.value.object("logger"))
+        let persistence = config.value.object("persistence")
+        try store.prune(days: Int(persistence.number("maxDaysToPersist", 7)), maximum: Int(persistence.number("maxRecordsToPersist", -1)), now: Date(timeIntervalSince1970: clock().wall / 1000))
+        runtime = try store.load("runtime") ?? [:]
+        if !(TrackingInstant.from(runtime.object("clockCheckpoint")).map { clock().continues($0) } ?? false), var stored = TrackedLocation.from(runtime.object("lastLocation")), stored.elapsed != nil {
+            stored.elapsed = nil; runtime["lastLocation"] = stored.json
+        }
+        monitor.pathUpdateHandler = { [weak self] path in
+            guard let self else { return }
+            self.network = path.status != .satisfied ? "none" : path.usesInterfaceType(.cellular) ? "cellular" : path.usesInterfaceType(.wifi) ? "wifi" : path.usesInterfaceType(.wiredEthernet) ? "ethernet" : "other"
+            self.syncer.connectivity(connected: path.status == .satisfied, cellular: path.usesInterfaceType(.cellular))
+            self.emit("connectivitychange", ["connected": self.syncer.connected, "type": self.network])
+        }
+        monitor.start(queue: queue)
+        if let geofenceBackend { attachGeofences(geofenceBackend) }
+        else if #available(iOS 17.0, *) {
+            let manager = permissions.manager
+            attachGeofences(GeofenceMonitor.shared(queue: queue) { manager.authorizationStatus })
+        }
+    }
+    var geofences: GeofenceManager? { engine.geofences }
+    private func attachGeofences(_ backend: GeofenceBackend) {
+        let manager = GeofenceManager(store: SQLiteGeofenceStore(store: store), backend: backend, queue: queue, now: { [unowned self] in self.clock().wall }, automaticTimers: automaticTimers, initialTriggerEntry: { [unowned self] in self.config.value.object("geofence").flag("initialTriggerEntry", true) }, enabled: { [unowned self] in self.runtime.flag("enabled") }, storedLocation: { [unowned self] in TrackedLocation.from(self.runtime.object("lastLocation")) }, notify: { [unowned self] in self.engine.recordGeofence($0, $1, $2) }, changed: { [unowned self] on, off in self.emit("geofenceschange", ["on": on.map(\.json), "off": off]) }, log: { [unowned self] level, message in self.log.write(level, "Geofences: " + message) })
+        manager.demandChanged = { [unowned self] in self.engine.geofenceDemandChanged($0) }
+        manager.blocked = { [unowned self] in self.engine.geofencesBlocked() }
+        if let monitor = backend as? GeofenceMonitor {
+            monitor.transitions = { [weak manager] in manager?.onTransitions($0) }
+            monitor.failures = { [weak self] in self?.engine.geofenceFailures($0) }
+        }
+        engine.geofences = manager
+    }
+    private func geofenceManager() throws -> GeofenceManager {
+        guard let geofences else { throw TrackingError("UNAVAILABLE", "Geofencing requires iOS 17") }
+        return geofences
+    }
+    deinit { monitor.cancel() }
+    static let allowed = Set(["ready", "getState", "checkPermissions", "requestPermissions", "getDeviceInfo", "getSensors", "log", "getLog", "getProviderState", "openBatteryOptimizationSettings", "openPowerManagerSettings", "openLocationSettings", "openAppSettings"])
+    func state() -> TrackingJSON {
+        ["enabled": runtime.flag("enabled"), "trackingMode": runtime.text("trackingMode", "location"), "isMoving": runtime.flag("isMoving"), "odometer": odometer, "backend": PluginInfo.backend, "lastRecordAt": runtime["lastRecordAt"] ?? NSNull(), "lastStopReason": runtime["lastStopReason"] ?? NSNull(), "lastStopAt": runtime["lastStopAt"] ?? NSNull(), "config": config.masked]
+    }
+    func call(_ method: String, _ options: TrackingJSON, native: Bool = false, callback: @escaping (Result<TrackingJSON, Error>) -> Void) {
+        do {
+            guard native || ready || Self.allowed.contains(method) else { throw TrackingError("NOT_READY", "Call ready() before using this method") }
+            try Options.validate(method, options)
+            switch method {
+            case "ready", "reset", "setConfig":
+                let patch = method == "setConfig" ? try options.requiringObject("config") : options.object("config")
+                let resetting = method == "reset" || (method == "ready" && options.flag("reset", true))
+                let existing = try store.load("config")
+                let shouldApply = method != "ready" || resetting || existing == nil
+                let warnings = shouldApply ? try config.apply(patch, reset: resetting) : []
+                log.configure(config.value.object("logger"))
+                if shouldApply { engine.configChanged() }
+                if method == "ready" && !native { ready = true }
+                var result = state(); result["warnings"] = warnings
+                callback(.success(result)); syncer.automatic()
+            case "getState": callback(.success(state()))
+            case "start", "startGeofences":
+                let mode = method == "start" ? "location" : "geofences"
+                if mode == "geofences" { _ = try geofenceManager() }
+                DispatchQueue.main.async {
+                    let provider = self.permissions.provider
+                    let foreground = UIApplication.shared.applicationState != .background
+                    let lastLocation = self.routeSource?.lastLocation
+                    self.queue.async {
+                        do { self.engine.context(provider: provider, foreground: foreground); self.engine.offerLastLocation(lastLocation); try self.engine.start(mode: mode); callback(.success(self.state())) }
+                        catch { callback(.failure(error)) }
+                    }
+                }
+            case "stop": try engine.stop(); callback(.success(state()))
+            case "changePace":
+                guard let moving = options["isMoving"] as? Bool else { throw TrackingError("INVALID_ARGUMENT", "isMoving is required") }
+                engine.changePace(moving); callback(.success([:]))
+            case "getHeartbeatStatus": callback(.success(engine.heartbeatStatus()))
+            case "getOdometer": callback(.success(["odometer": odometer]))
+            case "setOdometer", "resetOdometer":
+                let value = method == "resetOdometer" ? 0 : options.number("odometer", -1)
+                guard value.isFinite && value >= 0 else { throw TrackingError("INVALID_ARGUMENT", "odometer must be a finite number >= 0") }
+                try updateRuntime(["odometer": value])
+                if method == "resetOdometer" { engine.odometer.reset(session: runtime["trackingStartedAt"] as? Double) }
+                callback(.success(["odometer": value]))
+            case "getLocations": callback(.success(["locations": try store.locations(limit: max(0, Int(options.number("limit"))))]))
+            case "getCount": callback(.success(["count": try store.count]))
+            case "destroyLocations": callback(.success(["count": try store.clear()]))
+            case "destroyLocation": callback(.success(["deleted": try store.delete(options.requiringString("uuid"))]))
+            case "insertLocation": insert(try options.requiringObject("location"), callback: callback)
+            case "sync": syncer.run { callback($0.map { ["locations": $0] }) }
+            case "getCurrentPosition", "watchPosition":
+                let watch = method == "watchPosition"
+                let id = options.text("_watchId", UUID().uuidString)
+                if watch { watchIDs.insert(id) }
+                var request = options
+                request["_rejectMock"] = config.value.object("geolocation").object("filter").flag("rejectMockLocations")
+                if !watch && request["timeout"] == nil { request["timeout"] = config.value.object("geolocation").number("locationTimeout", 30000) }
+                guard request.number("timeout", 30000) > 0, request.number("samples", 3) >= 1, request.number("maximumAge") >= 0, request.number("interval", 1000) >= 0 else { throw TrackingError("INVALID_ARGUMENT", "Invalid position options") }
+                DispatchQueue.main.async {
+                    self.positions.request(id: id, options: request, watch: watch) { result in
+                        let provider = self.permissions.provider
+                        self.queue.async {
+                            if watch && !self.watchIDs.contains(id) { return }
+                            do {
+                                let fix = try result.get()
+                                if watch && self.config.value.object("geolocation").object("filter").flag("rejectMockLocations") && fix.sourceInformation?.isSimulatedBySoftware == true { return }
+                                let extras = self.config.value.object("persistence").object("extras").merging(options.object("extras")) { _, new in new }
+                                var location = TrackedLocation(fix)
+                                if self.runtime.flag("enabled") { location.session = self.runtime["trackingStartedAt"] as? Double }
+                                let wire = self.makeRecord(event: watch ? "watch_position" : "current_position", fix: location, extras: extras, provider: provider)
+                                if options.flag("persist", !watch) { self.deliver(wire, location: location) }
+                                callback(.success(wire))
+                            } catch { callback(.failure(error)) }
+                        }
+                    }
+                }
+            case "clearWatch":
+                let id = try options.requiringString("id")
+                watchIDs.remove(id)
+                DispatchQueue.main.async { self.positions.clear(id) }
+                callback(.success([:]))
+            case "getProviderState": DispatchQueue.main.async { LocationServices.shared.whenReady { callback(.success(self.permissions.provider)) } }
+            case "checkPermissions": DispatchQueue.main.async { self.permissions.status { callback(.success($0)) } }
+            case "requestPermissions":
+                let types = options["permissions"] as? [String] ?? Permissions.order
+                guard types.allSatisfy({ Permissions.order.contains($0) }) else { throw TrackingError("INVALID_ARGUMENT", "Unknown permission") }
+                let ordered = Permissions.order.filter { types.contains($0) }
+                DispatchQueue.main.async { self.permissions.request(ordered) { callback(.success($0)) } }
+            case "isPowerSaveMode": callback(.success(["isPowerSaveMode": ProcessInfo.processInfo.isLowPowerModeEnabled]))
+            case "getBatteryOptimizationStatus": callback(.success(["isIgnoringBatteryOptimizations": false, "canScheduleExactAlarms": false, "isDeviceIdleMode": false]))
+            case "getPowerManagerInfo": callback(.success(["manufacturer": "Apple", "available": false]))
+            case "openBatteryOptimizationSettings", "openPowerManagerSettings": callback(.success(["opened": false]))
+            case "openAppSettings", "openLocationSettings":
+                DispatchQueue.main.async { UIApplication.shared.open(URL(string: UIApplication.openSettingsURLString)!) { callback(.success(["opened": $0])) } }
+            case "getDeviceInfo":
+                DispatchQueue.main.async {
+                    callback(.success(["platform": "ios", "manufacturer": "Apple", "model": UIDevice.current.model, "brand": "Apple", "osVersion": UIDevice.current.systemVersion, "sdkInt": 0, "pluginVersion": PluginInfo.version, "gmsAvailable": false, "hmsAvailable": false, "backend": PluginInfo.backend, "packagedProviders": [PluginInfo.backend], "backendFallbackReason": NSNull(), "gmsStatus": NSNull(), "hmsStatus": NSNull(), "hmsCoreOutdated": NSNull(), "locationAvailableHint": NSNull(), "cpuCores": ProcessInfo.processInfo.processorCount, "supportedAbis": []]))
+                }
+            case "getSensors":
+                let motion = CMMotionManager()
+                callback(.success(["accelerometer": motion.isAccelerometerAvailable, "gyroscope": motion.isGyroAvailable, "magnetometer": motion.isMagnetometerAvailable, "significantMotion": CMMotionActivityManager.isActivityAvailable(), "stepCounter": CMPedometer.isStepCountingAvailable(), "stepDetector": CMPedometer.isStepCountingAvailable(), "barometer": CMAltimeter.isRelativeAltitudeAvailable()]))
+            case "log":
+                guard let message = options["message"] as? String else { throw TrackingError("INVALID_ARGUMENT", "message must be a string") }
+                log.write(try options.requiringString("level"), message); callback(.success([:]))
+            case "getLog": callback(.success(["log": log.read(options)]))
+            case "destroyLog": try log.clear(); callback(.success([:]))
+            case "addGeofence": try geofenceManager().add([GeofenceSpec.parse(options.requiringObject("geofence"))]); callback(.success([:]))
+            case "addGeofences":
+                let manager = try geofenceManager()
+                guard let array = options["geofences"] as? [Any] else { throw TrackingError("INVALID_ARGUMENT", "geofences must be an array") }
+                let specs = try array.enumerated().map { index, item -> GeofenceSpec in
+                    guard let object = item as? TrackingJSON else { throw TrackingError("INVALID_ARGUMENT", "geofences[\(index)] must be an object") }
+                    return try GeofenceSpec.parse(object)
+                }
+                if !specs.isEmpty { try manager.add(specs) }
+                callback(.success([:]))
+            case "removeGeofence": try geofenceManager().remove([options.requiringString("identifier")]); callback(.success([:]))
+            case "removeGeofences":
+                let manager = try geofenceManager()
+                if options["identifiers"] == nil || options["identifiers"] is NSNull { try manager.removeAll() }
+                else {
+                    guard let array = options["identifiers"] as? [Any] else { throw TrackingError("INVALID_ARGUMENT", "identifiers must be an array") }
+                    let ids = try array.enumerated().map { index, item -> String in
+                        guard let id = item as? String, !id.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty else { throw TrackingError("INVALID_ARGUMENT", "identifiers[\(index)] must be a non-empty string") }
+                        return id
+                    }
+                    if !ids.isEmpty { try manager.remove(ids) }
+                }
+                callback(.success([:]))
+            case "getGeofences": callback(.success(["geofences": try geofenceManager().list().map(\.json)]))
+            case "getGeofence": callback(.success(["geofence": try geofenceManager().get(options.requiringString("identifier"))?.json ?? NSNull()]))
+            case "geofenceExists": callback(.success(["exists": try geofenceManager().get(options.requiringString("identifier")) != nil]))
+            case "uploadLog": try logExport.upload(log.read([:]), options: options, completion: callback)
+            case "emailLog":
+                let text = log.read([:])
+                DispatchQueue.main.async { self.logExport.email(text, options: options, completion: callback) }
+            default: throw TrackingError("UNIMPLEMENTED", "Unknown method: \(method)")
+            }
+        } catch { callback(.failure(error)) }
+    }
+    private func insert(_ input: TrackingJSON, callback: @escaping (Result<TrackingJSON, Error>) -> Void) {
+        do {
+            let now = clock()
+            let parsed = try ExternalRecord(input, now: now.wall)
+            let extras = config.value.object("persistence").object("extras").merging(parsed.extras) { _, new in new }
+            let capturedOdometer = odometer
+            let capturedNetwork = network
+            let capturedMoving = runtime.flag("isMoving")
+            let capturedActivity = runtime["activity"] ?? ["type": "unknown", "confidence": 0]
+            DispatchQueue.main.async {
+                let provider = self.permissions.provider
+                var wire = RecordFactory.make(event: parsed.event, fix: parsed.location.location, extras: extras, odometer: capturedOdometer, provider: provider, network: capturedNetwork)
+                wire["is_moving"] = parsed.moving ?? capturedMoving
+                wire["activity"] = capturedActivity
+                wire["coords"] = parsed.coordinates
+                wire["recorded_at"] = iso(Date(timeIntervalSince1970: now.wall / 1000))
+                wire["elapsed_realtime_ms"] = now.elapsed
+                self.queue.async {
+                    do { try self.persist(wire, updateRuntime: false); self.record(wire); self.syncer.automatic(); callback(.success(["uuid": wire.text("uuid")])) }
+                    catch { callback(.failure(error)) }
+                }
+            }
+        } catch { callback(.failure(error)) }
+    }
+    func updateRuntime(_ changes: TrackingJSON) throws {
+        var next = runtime.merging(changes) { _, new in new }
+        next["clockCheckpoint"] = clock().json
+        try store.save("runtime", next)
+        runtime = next
+    }
+    func makeRecord(event: String, fix: TrackedLocation?, extras: TrackingJSON? = nil, provider: TrackingJSON? = nil) -> TrackingJSON {
+        var wire = RecordFactory.make(event: event, fix: fix?.location, extras: extras ?? config.value.object("persistence").object("extras"), odometer: odometer, provider: provider ?? engine.provider, network: network)
+        wire["is_moving"] = runtime.flag("isMoving")
+        wire["activity"] = runtime["activity"] ?? ["type": "unknown", "confidence": 0]
+        wire["mock"] = fix?.isMock ?? false
+        let now = clock()
+        wire["recorded_at"] = iso(Date(timeIntervalSince1970: now.wall / 1000))
+        wire["elapsed_realtime_ms"] = now.elapsed
+        return wire
+    }
+    private func recordedRuntime(_ wire: TrackingJSON, location: TrackedLocation?) -> TrackingJSON {
+        var next = runtime
+        next["lastRecordAt"] = wire["recorded_at"]
+        next["lastRecordElapsed"] = wire["elapsed_realtime_ms"] ?? clock().elapsed
+        next["clockCheckpoint"] = clock().json
+        if let location { next["lastLocation"] = location.json }
+        if wire.text("event") == "heartbeat" { next["lastHeartbeatAt"] = wire["recorded_at"] }
+        return next
+    }
+    func deliver(_ wire: TrackingJSON, location: TrackedLocation? = nil, onUpload: (() -> Void)? = nil) {
+        var stored = false
+        do { try persist(wire, updateRuntime: true, location: location); stored = true }
+        catch {
+            log.write("error", "Failed to persist position")
+            if (error as? TrackingError)?.storageFull == true { emit("storagefull", ["uuid": wire.text("uuid"), "event": wire.text("event"), "diskFreeBytes": NSNull()]) }
+            runtime = recordedRuntime(wire, location: location)
+        }
+        record(wire)
+        switch wire.text("event") {
+        case "location", "current_position", "watch_position": emit("location", wire)
+        case "motionchange": emit("location", wire); emit("motionchange", ["isMoving": wire.flag("is_moving"), "location": wire])
+        case "heartbeat": emit("heartbeat", ["location": wire])
+        case "geofence":
+            let hit = wire.object("geofence")
+            var payload: TrackingJSON = ["identifier": hit["identifier"] ?? NSNull(), "action": hit["action"] ?? NSNull(), "location": wire]
+            if let extras = hit["extras"] { payload["extras"] = extras }
+            emit("geofence", payload)
+        default: break
+        }
+        engine.recorded()
+        if stored {
+            if let onUpload { syncer.automatic { _ in onUpload() } }
+            else { syncer.automatic() }
+        } else { onUpload?() }
+    }
+    private func persist(_ wire: TrackingJSON, updateRuntime: Bool, location: TrackedLocation? = nil) throws {
+        let next = recordedRuntime(wire, location: location)
+        let persistence = config.value.object("persistence")
+        try store.transaction {
+            try store.insert(wire)
+            if updateRuntime { try store.save("runtime", next) }
+            try store.enforceRetention(days: Int(persistence.number("maxDaysToPersist", 7)), maximum: Int(persistence.number("maxRecordsToPersist", -1)), now: Date(timeIntervalSince1970: clock().wall / 1000))
+        }
+        if updateRuntime { runtime = next }
+    }
+}

package/ios/Sources/LocationTrackingPlugin/Data/TrackingStore.swift

@@ -0,0 +1,155 @@
+import Foundation
+import SQLite3
+
+final class TrackingStore {
+    private var db: OpaquePointer?
+    private let transient = unsafeBitCast(-1, to: sqlite3_destructor_type.self)
+
+    init(url: URL) throws {
+        var directory = url.deletingLastPathComponent()
+        try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true, attributes: [.protectionKey: FileProtectionType.completeUntilFirstUserAuthentication])
+        var resources = URLResourceValues()
+        resources.isExcludedFromBackup = true
+        try directory.setResourceValues(resources)
+        guard sqlite3_open_v2(url.path, &db, SQLITE_OPEN_CREATE | SQLITE_OPEN_READWRITE | SQLITE_OPEN_FULLMUTEX, nil) == SQLITE_OK else {
+            sqlite3_close(db)
+            throw TrackingError("IO_ERROR", "Cannot open tracking database")
+        }
+        sqlite3_busy_timeout(db, 1000)
+        do {
+            try execute("PRAGMA journal_mode=WAL")
+            try execute("PRAGMA synchronous=FULL")
+            try execute("CREATE TABLE IF NOT EXISTS metadata (key TEXT PRIMARY KEY, value TEXT NOT NULL)")
+            try execute("CREATE TABLE IF NOT EXISTS records (id INTEGER PRIMARY KEY AUTOINCREMENT, uuid TEXT UNIQUE NOT NULL, value TEXT NOT NULL)")
+            try execute("CREATE INDEX IF NOT EXISTS records_recorded_at ON records(json_extract(value,'$.recorded_at'), id)")
+            try FileManager.default.setAttributes([.protectionKey: FileProtectionType.completeUntilFirstUserAuthentication], ofItemAtPath: url.path)
+        } catch { sqlite3_close(db); db = nil; throw error }
+    }
+
+    deinit { sqlite3_close(db) }
+
+    private func databaseError(_ message: String) -> TrackingError {
+        var error = TrackingError("IO_ERROR", message)
+        error.storageFull = sqlite3_errcode(db) == SQLITE_FULL
+        return error
+    }
+
+    func execute(_ sql: String) throws {
+        guard sqlite3_exec(db, sql, nil, nil, nil) == SQLITE_OK else { throw databaseError("Database operation failed") }
+    }
+
+    private func statement(_ sql: String, _ values: [String] = []) throws -> OpaquePointer {
+        var query: OpaquePointer?
+        guard sqlite3_prepare_v2(db, sql, -1, &query, nil) == SQLITE_OK, let query else { throw databaseError("Cannot prepare database operation") }
+        for (index, value) in values.enumerated() {
+            guard sqlite3_bind_text(query, Int32(index + 1), value, -1, transient) == SQLITE_OK else {
+                sqlite3_finalize(query)
+                throw TrackingError("IO_ERROR", "Cannot bind database value")
+            }
+        }
+        return query
+    }
+
+    private func write(_ sql: String, _ values: [String]) throws {
+        let query = try statement(sql, values)
+        defer { sqlite3_finalize(query) }
+        guard sqlite3_step(query) == SQLITE_DONE else { throw databaseError("Cannot write database value") }
+    }
+
+    func transaction<T>(_ action: () throws -> T) throws -> T {
+        try execute("BEGIN IMMEDIATE")
+        do {
+            let result = try action()
+            try execute("COMMIT")
+            return result
+        } catch { try? execute("ROLLBACK"); throw error }
+    }
+
+    func save(_ key: String, _ value: TrackingJSON) throws {
+        try write("INSERT OR REPLACE INTO metadata(key,value) VALUES(?,?)", [key, String(decoding: try jsonData(value), as: UTF8.self)])
+    }
+
+    func load(_ key: String) throws -> TrackingJSON? {
+        let query = try statement("SELECT value FROM metadata WHERE key=?", [key])
+        defer { sqlite3_finalize(query) }
+        let status = sqlite3_step(query)
+        if status == SQLITE_DONE { return nil }
+        guard status == SQLITE_ROW, let value = sqlite3_column_text(query, 0) else { throw TrackingError("IO_ERROR", "Cannot read database value") }
+        return try jsonObject(Data(String(cString: value).utf8))
+    }
+
+    func insert(_ record: TrackingJSON) throws {
+        try write("INSERT INTO records(uuid,value) VALUES(?,?)", [try record.requiringString("uuid"), String(decoding: try jsonData(record), as: UTF8.self)])
+    }
+
+    func locations(limit: Int = 0) throws -> [TrackingJSON] {
+        try records("SELECT value FROM records ORDER BY json_extract(value,'$.recorded_at') ASC, id ASC" + (limit > 0 ? " LIMIT \(limit)" : ""), [])
+    }
+
+    func locations(events: Set<String>) throws -> [TrackingJSON] {
+        let names = events.sorted()
+        guard !names.isEmpty else { return [] }
+        return try records("SELECT value FROM records WHERE json_extract(value,'$.event') IN (" + names.map { _ in "?" }.joined(separator: ",") + ") ORDER BY json_extract(value,'$.recorded_at') ASC, id ASC", names)
+    }
+
+    func contains(events: Set<String>) throws -> Bool {
+        let names = events.sorted()
+        guard !names.isEmpty else { return false }
+        let query = try statement("SELECT EXISTS(SELECT 1 FROM records WHERE json_extract(value,'$.event') IN (" + names.map { _ in "?" }.joined(separator: ",") + "))", names)
+        defer { sqlite3_finalize(query) }
+        guard sqlite3_step(query) == SQLITE_ROW else { throw TrackingError("IO_ERROR", "Cannot read queued records") }
+        return sqlite3_column_int64(query, 0) != 0
+    }
+
+    private func records(_ sql: String, _ values: [String]) throws -> [TrackingJSON] {
+        let query = try statement(sql, values)
+        defer { sqlite3_finalize(query) }
+        var result: [TrackingJSON] = []
+        while true {
+            let status = sqlite3_step(query)
+            if status == SQLITE_DONE { return result }
+            guard status == SQLITE_ROW, let value = sqlite3_column_text(query, 0) else { throw TrackingError("IO_ERROR", "Cannot read queued records") }
+            result.append(try jsonObject(Data(String(cString: value).utf8)))
+        }
+    }
+
+    var count: Int {
+        get throws {
+            let query = try statement("SELECT COUNT(*) FROM records")
+            defer { sqlite3_finalize(query) }
+            guard sqlite3_step(query) == SQLITE_ROW else { throw TrackingError("IO_ERROR", "Cannot count records") }
+            return Int(sqlite3_column_int64(query, 0))
+        }
+    }
+
+    func count(event: String) throws -> Int {
+        let query = try statement("SELECT COUNT(*) FROM records WHERE json_extract(value,'$.event')=?", [event])
+        defer { sqlite3_finalize(query) }
+        guard sqlite3_step(query) == SQLITE_ROW else { throw TrackingError("IO_ERROR", "Cannot count queued records") }
+        return Int(sqlite3_column_int64(query, 0))
+    }
+
+    @discardableResult func delete(_ uuid: String) throws -> Bool {
+        try write("DELETE FROM records WHERE uuid=?", [uuid])
+        return sqlite3_changes(db) > 0
+    }
+
+    func clear() throws -> Int {
+        try execute("DELETE FROM records")
+        return Int(sqlite3_changes(db))
+    }
+
+    func prune(days: Int, maximum: Int, now: Date = Date()) throws {
+        try transaction { try enforceRetention(days: days, maximum: maximum, now: now) }
+    }
+
+    func enforceRetention(days: Int, maximum: Int, now: Date = Date()) throws {
+            if days >= 0 {
+                let cutoff = iso(now.addingTimeInterval(-Double(days) * 86400))
+                try write("DELETE FROM records WHERE json_extract(value,'$.recorded_at') < ?", [cutoff])
+            }
+            if maximum > 0 {
+                try execute("DELETE FROM records WHERE id NOT IN (SELECT id FROM records ORDER BY json_extract(value,'$.recorded_at') DESC, id DESC LIMIT \(maximum))")
+            }
+    }
+}

package/ios/Sources/LocationTrackingPlugin/Device/DeviceReadings.swift

@@ -0,0 +1,43 @@
+import Foundation
+import UIKit
+
+final class DeviceReadings {
+    static let shared = DeviceReadings()
+    private let lock = NSLock()
+    private var identifier: String?
+    private var model = "iPhone"
+    private var version = ""
+    private var level: Float = -1
+    private var charging = false
+    private var observers: [NSObjectProtocol] = []
+    private init() {}
+    func start() {
+        precondition(Thread.isMainThread)
+        UIDevice.current.isBatteryMonitoringEnabled = true
+        refresh()
+        guard observers.isEmpty else { return }
+        for name in [UIDevice.batteryLevelDidChangeNotification, UIDevice.batteryStateDidChangeNotification, UIApplication.didBecomeActiveNotification, UIApplication.protectedDataDidBecomeAvailableNotification] {
+            observers.append(NotificationCenter.default.addObserver(forName: name, object: nil, queue: .main) { [weak self] _ in self?.refresh() })
+        }
+    }
+    private func refresh() {
+        let device = UIDevice.current
+        let identifier = device.identifierForVendor?.uuidString, model = device.model, version = device.systemVersion
+        let level = device.batteryLevel, state = device.batteryState
+        lock.lock(); defer { lock.unlock() }
+        self.identifier = identifier; self.model = model; self.version = version
+        self.level = level; charging = state == .charging || state == .full
+    }
+    func snapshot(event: String) -> (device: TrackingJSON, battery: TrackingJSON) {
+        lock.lock(); defer { lock.unlock() }
+        var device: TrackingJSON = [:]
+        if let identifier { device["device_id"] = identifier }
+        if event == "tracking_start" { device.merge(["manufacturer": "Apple", "model": model, "os_version": version, "ram_total_bytes": ProcessInfo.processInfo.physicalMemory]) { _, new in new } }
+        if event == "heartbeat" {
+            let thermal: String
+            switch ProcessInfo.processInfo.thermalState { case .nominal: thermal = "none"; case .fair: thermal = "light"; case .serious: thermal = "severe"; case .critical: thermal = "critical"; @unknown default: thermal = "unknown" }
+            device["thermal_status"] = thermal
+        }
+        return (device, ["level": level, "is_charging": charging])
+    }
+}

package/ios/Sources/LocationTrackingPlugin/Engine/CheckInNotifier.swift

@@ -0,0 +1,92 @@
+import Foundation
+import UserNotifications
+
+protocol CheckInCenter {
+    func authorized(_ completion: @escaping (Bool) -> Void)
+    func add(_ request: UNNotificationRequest, completion: @escaping (Error?) -> Void)
+    func cancel()
+    func clearDelivered()
+}
+
+struct SystemCheckInCenter: CheckInCenter {
+    private let center = UNUserNotificationCenter.current()
+    func authorized(_ completion: @escaping (Bool) -> Void) {
+        center.getNotificationSettings { completion([.authorized, .provisional, .ephemeral].contains($0.authorizationStatus)) }
+    }
+    func add(_ request: UNNotificationRequest, completion: @escaping (Error?) -> Void) { center.add(request, withCompletionHandler: completion) }
+    func cancel() { center.removePendingNotificationRequests(withIdentifiers: [CheckInNotifier.identifier]) }
+    func clearDelivered() { center.removeDeliveredNotifications(withIdentifiers: [CheckInNotifier.identifier]) }
+}
+
+final class CheckInNotifier {
+    static let identifier = "com.brickssoft.locationtracking.check-in"
+    private let queue: DispatchQueue
+    private let clock: () -> TrackingInstant
+    private let center: CheckInCenter
+    private let warning: (String) -> Void
+    private let appName: String
+    private var generation = 0
+    private var lastChecked: Double?
+    private var enabled = false
+    private var scheduling = false
+    private var latest: (TrackingJSON, Double?)?
+    init(queue: DispatchQueue, clock: @escaping () -> TrackingInstant, center: CheckInCenter = SystemCheckInCenter(), appName: String? = nil, warning: @escaping (String) -> Void) {
+        self.queue = queue; self.clock = clock; self.center = center; self.warning = warning
+        self.appName = appName ?? Bundle.main.object(forInfoDictionaryKey: "CFBundleDisplayName") as? String ?? Bundle.main.object(forInfoDictionaryKey: "CFBundleName") as? String ?? "Location tracking"
+    }
+    func start() { center.clearDelivered(); lastChecked = nil }
+    func cancel() {
+        generation += 1; enabled = false; latest = nil; lastChecked = nil
+        center.cancel()
+    }
+    func touch(_ settings: TrackingJSON, deadlineElapsed: Double?, force: Bool = false) {
+        guard settings.flag("enabled") else { cancel(); return }
+        let deadlineChanged = latest.map { $0.1 != deadlineElapsed } ?? false
+        enabled = true
+        latest = (settings, deadlineElapsed)
+        if force || deadlineChanged { generation += 1 }
+        if force { lastChecked = nil }
+        drain()
+    }
+    private func drain() {
+        guard enabled, !scheduling, let (settings, deadline) = latest else { return }
+        let now = clock()
+        let delay = settings.number("delay", 600)
+        guard deadline == nil || now.elapsed + delay * 1000 <= deadline! else { cancel(); return }
+        if let lastChecked, now.elapsed - lastChecked < 60000 { return }
+        let previous = lastChecked
+        let mark = now.elapsed
+        lastChecked = mark
+        scheduling = true
+        let captured = generation
+        center.authorized { allowed in
+            self.queue.async {
+                guard captured == self.generation, self.enabled, let (settings, deadline) = self.latest else {
+                    if self.lastChecked == mark { self.lastChecked = previous }
+                    self.scheduling = false; self.drain(); return
+                }
+                let now = self.clock()
+                let delay = settings.number("delay", 600)
+                guard allowed, deadline == nil || now.elapsed + delay * 1000 <= deadline! else {
+                    self.scheduling = false; self.center.cancel(); return
+                }
+                let content = UNMutableNotificationContent()
+                let title = settings.text("title")
+                content.title = title.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty ? self.appName : title
+                content.body = settings.text("text", "Location tracking is paused. Tap to resume.")
+                content.sound = .default
+                let request = UNNotificationRequest(identifier: Self.identifier, content: content, trigger: UNTimeIntervalNotificationTrigger(timeInterval: max(1, delay), repeats: false))
+                self.center.add(request) { error in
+                    self.queue.async {
+                        self.scheduling = false
+                        if captured == self.generation && self.enabled {
+                            if error == nil { self.lastChecked = self.clock().elapsed }
+                            else { self.warning("Check-in notification could not be scheduled") }
+                        } else if !self.enabled { self.center.cancel() }
+                        if captured != self.generation { self.drain() }
+                    }
+                }
+            }
+        }
+    }
+}