@bubblsdk/react-native-sdk 4.1.7 → 5.0.0-alpha.2

package/ios-extension/Sources/BubblCore/Engine/Geofencing.swift

@@ -0,0 +1,170 @@
+import Foundation
+
+/// What sending the pending geofence transitions came to.
+package struct TransitionsSent: Sendable, Equatable {
+    package var outcome: WorkOutcome = .done
+    /// Notifications the server says to show now.
+    package var notifications: [JSONValue] = []
+    /// A transition was refused because its location has gone: check the geofences again.
+    package var recheck = false
+
+    package init(outcome: WorkOutcome = .done, notifications: [JSONValue] = [], recheck: Bool = false) {
+        self.outcome = outcome
+        self.notifications = notifications
+        self.recheck = recheck
+    }
+}
+
+/// Geofencing as work, as Android's GeofenceWork and receivers: the OS's region events and
+/// location fixes become transitions, which are saved before anything else (the app can be
+/// suspended or killed at any moment in the background) and then sent; checks watch the geofences
+/// and fetch them when due. The platform supplies the fixes and runs the work.
+extension EngineCore {
+    /// At most this many transitions wait to be sent; the oldest go first.
+    package static let maxPendingTransitions = 200
+
+    /// The OS says the device entered or left `regionIds` (Bubbl's region names; others are
+    /// ignored). Returns what to do next: its transitions are already saved for sending.
+    package func regionEvent(_ regionIds: [String], entered: Bool, fix: Fix?, deviceTimeMillis: Int64) async -> Outcome {
+        let geofenceEvents = regionIds.filter { $0.hasPrefix(GeofenceEngine.regionPrefix) && $0 != GeofenceEngine.refreshRegionId }.count
+        // Before the first unlock after a reboot nothing can be read, not even whether location
+        // is allowed: the event is lost (accepted), and counted for diagnostics.
+        guard let privacy = privacy.state else {
+            droppedWhileLocked(geofenceEvents)
+            return Outcome()
+        }
+        guard privacy.locationActive, isActive else { return Outcome() }
+
+        var outcome: Outcome
+        do {
+            outcome = try await geofences.onRegionEvent(regionIds, entered: entered, fix: fix, deviceTimeMillis: deviceTimeMillis)
+        } catch {
+            droppedWhileLocked(geofenceEvents)
+            return Outcome()
+        }
+        if !record(outcome.transitions) { outcome.transitions = [] }
+        return outcome
+    }
+
+    /// A location fix (significant change, in-use updates, one asked for). `osWatches`: the OS
+    /// watches the geofences ("Always"); otherwise entering and leaving are decided from the fix.
+    package func locationFix(_ fix: Fix, osWatches: Bool) async -> Outcome {
+        guard locationActive else { return Outcome() }
+        var outcome: Outcome
+        do {
+            outcome = osWatches ? try await geofences.onFix(fix) : try await geofences.onFixWithoutOs(fix)
+        } catch {
+            return Outcome()
+        }
+        if !record(outcome.transitions) { outcome.transitions = [] }
+        return outcome
+    }
+
+    /// Android's CheckGeofencesWorker: make sure the geofences are watched (`rewatch`: the OS
+    /// dropped them), check them against `fix`, and fetch them if due (or `force`).
+    package func checkGeofences(fix: Fix, force: Bool = false, rewatch: Bool = false, osWatches: Bool) async -> WorkOutcome {
+        guard locationActive else { return .done }
+        saveLockedDrops()
+        do {
+            _ = rewatch ? try await geofences.rewatch() : try await geofences.ensureWatching()
+        } catch {
+            BubblLog.warning("Couldn't watch the geofences: their state can't be read yet")
+        }
+
+        // Its transitions are saved for sending; its refresh is the one below.
+        _ = await locationFix(fix, osWatches: osWatches)
+
+        let result: RefreshResult
+        do {
+            result = try await geofences.refresh(fix, force: force)
+        } catch {
+            return .retry(afterSeconds: 30)
+        }
+        BubblLog.debug("Geofence check: \(result)")
+        if case .failed(let failure) = result { return await handle(failure, "Checking geofences") }
+        return .done
+    }
+
+    /// Send the saved transitions, oldest first, stopping at the first that has to wait. One
+    /// sending at a time: a retry and a new region event never send the same one twice.
+    package func sendTransitions() async -> TransitionsSent {
+        await sendingTransitions.withLock { await self.sendPendingTransitions() }
+    }
+
+    private func sendPendingTransitions() async -> TransitionsSent {
+        guard locationActive else { return TransitionsSent() }
+        saveLockedDrops()
+        let pending: [Transition]
+        do {
+            pending = try transitionsLock.sync { try stores.transitions.load() ?? [] }
+        } catch {
+            return TransitionsSent(outcome: .retry(afterSeconds: 30))
+        }
+
+        var sent = TransitionsSent()
+        var finished: Set<String> = []
+        loop: for transition in pending {
+            switch await geofences.send(transition) {
+            case .delivered(let notifications):
+                BubblLog.debug("Geofence \(transition.enter ? "entry" : "exit") sent: \(notifications.count) notification(s) to show")
+                sent.notifications += notifications
+                finished.insert(transition.key)
+            case .dropped(let reason):
+                sent.recheck = sent.recheck || reason == "unknown_location"
+                finished.insert(transition.key)
+            case .failed(let failure):
+                sent.outcome = await handle(failure, "Sending a geofence transition")
+                break loop
+            }
+        }
+
+        if !finished.isEmpty {
+            try? transitionsLock.sync {
+                let left = (try stores.transitions.load() ?? []).filter { !finished.contains($0.key) }
+                try stores.transitions.save(left)
+            }
+        }
+        return sent
+    }
+
+    /// Whether transitions are waiting to be sent (false while that can't be read).
+    package var hasPendingTransitions: Bool {
+        transitionsLock.sync { ((try? stores.transitions.load()) ?? nil)?.isEmpty == false }
+    }
+
+    /// Region events lost before the first unlock after a reboot, since this install began.
+    package var transitionsDroppedWhileLocked: Int {
+        let saved: Int?? = try? stores.lockedDrops.load()
+        return ((saved ?? nil) ?? 0) + unsavedLockedDrops.value
+    }
+
+    /// Save `transitions` to be sent. False (and counted as lost) when they can't be written.
+    private func record(_ transitions: [Transition]) -> Bool {
+        guard !transitions.isEmpty else { return true }
+        do {
+            try transitionsLock.sync {
+                let all = (try stores.transitions.load() ?? []) + transitions
+                try stores.transitions.save(Array(all.suffix(Self.maxPendingTransitions)))
+            }
+            return true
+        } catch {
+            droppedWhileLocked(transitions.count)
+            return false
+        }
+    }
+
+    private func droppedWhileLocked(_ count: Int) {
+        guard count > 0 else { return }
+        unsavedLockedDrops.add(count)
+        BubblLog.info("\(count) geofence event(s) before the first unlock since the phone restarted: not kept")
+        saveLockedDrops()
+    }
+
+    /// Adds the drops counted in memory to the saved count, once it can be written.
+    private func saveLockedDrops() {
+        try? unsavedLockedDrops.drain { count in
+            let saved = try stores.lockedDrops.load() ?? 0
+            try stores.lockedDrops.save(saved + count)
+        }
+    }
+}

package/ios-extension/Sources/BubblCore/Engine/Permissions.swift

@@ -0,0 +1,90 @@
+import Foundation
+
+/// Where the device stands on the permissions Bubbl uses: the contract's Permissions for PUT
+/// /device, and what the app sees (BubblPermissionStatus).
+package struct PermissionStatus: Sendable, Equatable {
+    package enum Notifications: String, Sendable {
+        case granted, denied
+        case notDetermined = "not_determined"
+    }
+
+    package enum Location: String, Sendable {
+        case always, denied
+        case whenInUse = "when_in_use"
+        case notDetermined = "not_determined"
+    }
+
+    package let notifications: Notifications
+    package let location: Location
+    /// Precise rather than approximate location.
+    package let preciseLocation: Bool
+
+    package init(notifications: Notifications, location: Location, preciseLocation: Bool) {
+        self.notifications = notifications
+        self.location = location
+        self.preciseLocation = preciseLocation
+    }
+
+    package var hasLocation: Bool { location == .always || location == .whenInUse }
+
+    /// As PUT /device takes it.
+    package var json: JSONValue {
+        ["notifications": .string(notifications.rawValue), "location": .string(location.rawValue), "precise_location": .bool(preciseLocation)]
+    }
+}
+
+/// What an app asks Bubbl to get permission for.
+package enum PermissionRequest: Sendable, Equatable {
+    case notifications, locationWhenInUse, locationAlways
+}
+
+/// One step of asking: explain first (the privacy view), or show the system's prompt.
+package enum PermissionStep: Sendable, Equatable {
+    /// The privacy view, for "notifications", "location" or "background_location".
+    case explain(String)
+    case ask(PermissionRequest)
+}
+
+/// The steps to get a permission on iOS, given where the device stands (Android's
+/// PermissionPlanner, with iOS's rules):
+///  - iOS prompts for each only once: a permission already refused (or "Always" already asked for
+///    and not given) has no steps; the app can send the person to Settings instead;
+///  - "Always" comes in two steps, as iOS expects: "While Using" first, then "Always" (asked for
+///    straight away, iOS gives only a provisional Always).
+/// The privacy view comes before each prompt as the dashboard's notice mode says: "never",
+/// "always", or "automatic" (the first time each kind is asked for).
+package enum PermissionPlanner {
+    package static func plan(_ request: PermissionRequest, status: PermissionStatus, notice: String, explained: Set<String>, askedAlways: Bool) -> [PermissionStep] {
+        var steps: [PermissionStep] = []
+        func explain(_ kind: String) {
+            if notice == "always" || (notice != "never" && !explained.contains(kind)) { steps.append(.explain(kind)) }
+        }
+
+        switch request {
+        case .notifications:
+            if status.notifications == .notDetermined {
+                explain("notifications")
+                steps.append(.ask(.notifications))
+            }
+        case .locationWhenInUse:
+            if status.location == .notDetermined {
+                explain("location")
+                steps.append(.ask(.locationWhenInUse))
+            }
+        case .locationAlways:
+            switch status.location {
+            case .notDetermined:
+                explain("location")
+                steps.append(.ask(.locationWhenInUse))
+                explain("background_location")
+                steps.append(.ask(.locationAlways))
+            case .whenInUse where !askedAlways:
+                explain("background_location")
+                steps.append(.ask(.locationAlways))
+            default:
+                break
+            }
+        }
+        return steps
+    }
+}

package/ios-extension/Sources/BubblCore/Engine/Privacy.swift

@@ -0,0 +1,64 @@
+import Foundation
+
+/// What the app's user has agreed to, and what the engine may do because of it (Android's
+/// PrivacyState).
+///
+///  - requireConsent: the app started Bubbl with consent required; nothing runs (no registration,
+///    no network, no location) until consent is true.
+///  - consent: nil until the user answers; false after opting out or erasing their data, which
+///    stops the engine whether or not consent was required.
+///  - locationEnabled: the app can turn location off (setLocationEnabled) while the rest runs.
+///  - pendingDelete: deleteMyData() was asked for and DELETE /device hasn't gone through yet.
+package struct PrivacyState: Sendable, Equatable, Codable {
+    package var requireConsent = false
+    package var consent: Bool?
+    package var locationEnabled = true
+    package var pendingDelete = false
+
+    package init(requireConsent: Bool = false, consent: Bool? = nil, locationEnabled: Bool = true, pendingDelete: Bool = false) {
+        self.requireConsent = requireConsent
+        self.consent = consent
+        self.locationEnabled = locationEnabled
+        self.pendingDelete = pendingDelete
+    }
+
+    /// The engine may run at all: register, send, fetch.
+    package var active: Bool { !pendingDelete && consent != false && (!requireConsent || consent == true) }
+
+    /// The engine may use location: geofences, fixes.
+    package var locationActive: Bool { active && locationEnabled }
+}
+
+/// PrivacyState kept between runs. While it can't be read (before the first unlock) the engine
+/// counts as not allowed to run: it never guesses a user's consent.
+package final class PrivacyStore: Sendable {
+    private let store: any ValueStore<PrivacyState>
+    private let cache = Cached<PrivacyState>()
+    private let lock = NSLock()
+
+    package init(store: any ValueStore<PrivacyState>) {
+        self.store = store
+    }
+
+    /// The state; nil while it can't be read.
+    package var state: PrivacyState? {
+        lock.sync {
+            do {
+                return try cache.value { try store.load() } ?? PrivacyState()
+            } catch {
+                return nil
+            }
+        }
+    }
+
+    @discardableResult
+    package func update(_ change: (inout PrivacyState) -> Void) throws -> PrivacyState {
+        try lock.sync {
+            var state = try cache.value { try store.load() } ?? PrivacyState()
+            change(&state)
+            try store.save(state)
+            cache.set(state)
+            return state
+        }
+    }
+}

package/ios-extension/Sources/BubblCore/Engine/PrivacyControls.swift

@@ -0,0 +1,184 @@
+import Foundation
+
+/// What an app's user can decide about Bubbl, and what each decision does to the engine (Android's
+/// PrivacyControls). The engine changes its state and stops what it must; the host runs the work
+/// each returns (and cancels its own), since only it knows how:
+///
+///  - consent given: everything runs (with consent required, nothing ran until now);
+///  - an opt-out (or consent refused): geofences stop, queued events are dropped, nothing more is
+///    sent or shown; a device the server knows is told, once (PUT /device consent=false);
+///  - deleteMyData: stops as for an opt-out, then DELETE /device erases the device and all that's
+///    recorded about it, and the engine's own data goes too; retried until done, and the engine
+///    stays stopped meanwhile and afterwards (consent given again starts afresh, as a new device);
+///  - location off: geofences and location stop; the rest carries on.
+///
+/// Each throws while the state can't be saved (before the first unlock after a reboot).
+extension EngineCore {
+    /// The user said yes (again, after an opt-out). False when nothing changed: a pending erasure
+    /// holds everything until it's done, then consent may be given again.
+    @discardableResult
+    package func grantConsent() throws -> Bool {
+        guard privacy.state?.pendingDelete != true else {
+            BubblLog.warning("Bubbl.setConsent(true) while the user's data is being erased: asked again once it's done")
+            return false
+        }
+        let before = privacy.state?.consent
+        try privacy.update { $0.consent = true }
+        return before != true
+    }
+
+    /// The user opted out. True when the server has to be told (Bubbl was running; then run
+    /// `consentWithdrawn` as work until it's done).
+    @discardableResult
+    package func optOut() async throws -> Bool {
+        let wasActive = privacy.state?.active == true
+        try privacy.update { $0.consent = false }
+        await stopWork()
+        return wasActive
+    }
+
+    /// PUT /device consent=false, the one call made after an opt-out. Nothing to tell for an install
+    /// that never registered; nothing left to tell once consent is back, or an erasure took over.
+    package func consentWithdrawn() async -> WorkOutcome {
+        guard let state = privacy.state else { return .retry(afterSeconds: 60) }
+        guard state.consent == false, !state.pendingDelete, everRegistered else { return .done }
+
+        switch await deviceSync.sync(["consent": .bool(false)]) {
+        case .failed(.backoff):
+            return .retry(afterSeconds: 30)
+        case .failed(.retryAfter(let seconds)):
+            return .retry(afterSeconds: seconds)
+        default:
+            // Told, or refused for good (paused, misconfigured): the device stays quiet either way.
+            return .done
+        }
+    }
+
+    /// The user asked for their data to be erased: stopped now; then run `eraseDevice` as work until
+    /// it's done.
+    package func requestErasure() async throws {
+        try privacy.update {
+            $0.consent = false
+            $0.pendingDelete = true
+        }
+        await stopWork()
+    }
+
+    /// DELETE /device, then the engine's own data. A revoked credential is replaced first by the
+    /// client (the install id names the same device), so the right device is erased; an install
+    /// that never registered has nothing on the server. Retried until done; given up only on an
+    /// error a retry can't fix, after `maxEraseAttempts`, and then said so rather than pretending
+    /// the data is gone.
+    package func eraseDevice() async -> WorkOutcome {
+        guard let state = privacy.state else { return .retry(afterSeconds: 60) }
+        guard state.pendingDelete else { return .done }
+
+        if everRegistered {
+            let response: ApiResponse
+            do {
+                response = try await api.request("DELETE", "api/v1/device")
+            } catch {
+                return .retry(afterSeconds: 30)
+            }
+            // Erased, or already gone.
+            if !response.isSuccessful && response.status != 404 {
+                switch ApiFailure.of(response) {
+                case .backoff: return .retry(afterSeconds: 30)
+                case .retryAfter(let seconds): return .retry(afterSeconds: seconds)
+                case .pause(let hours, _): return .retry(afterSeconds: hours * 3_600)
+                default:
+                    if eraseAttempts.next() < Self.maxEraseAttempts { return .retry(afterSeconds: 60) }
+                    BubblLog.error("Couldn't erase this device (HTTP \(response.status) \(response.code ?? "")): its data is still on the server")
+                    return .done
+                }
+            }
+        }
+
+        do {
+            try await wipeLocalData()
+            try privacy.update {
+                $0.pendingDelete = false
+                $0.consent = false
+            }
+        } catch {
+            BubblLog.warning("The device was erased on the server; its data here goes when it can be written")
+            return .retry(afterSeconds: 60)
+        }
+        BubblLog.info("This device's data was erased")
+        return .done
+    }
+
+    package static let maxEraseAttempts = 5
+
+    /// Location (geofences) off: they stop, the rest carries on. False when nothing changed.
+    @discardableResult
+    package func setLocationEnabled(_ enabled: Bool) async throws -> Bool {
+        let before = privacy.state?.locationEnabled
+        try privacy.update { $0.locationEnabled = enabled }
+        if !enabled { try? await geofences.stop() }
+        return before != enabled
+    }
+
+    /// Everything the engine keeps here, but what the user decided: the credential (the Keychain),
+    /// the install id (the next registration is a new device), the queue, geofences, and each saved
+    /// piece of state. Throws when something couldn't be removed.
+    package func wipeLocalData() async throws {
+        try stores.credentials.clear()
+        try await events.clear()
+        try await geofences.stop()
+        try configSync.forget()
+        try segments.forget()
+        deviceSync.forget()
+        try stores.recentNotifications.delete()
+        try stores.installId.delete()
+        try stores.clockOffset.delete()
+        try stores.pausedUntil.delete()
+        try stores.transitions.delete()
+        try stores.lockedDrops.delete()
+    }
+
+    /// Stops what the engine does and drops what's queued (geofences, events, unsent transitions).
+    private func stopWork() async {
+        try? await geofences.stop()
+        try? await events.clear()
+        try? stores.transitions.delete()
+    }
+}
+
+extension EngineCore {
+    /// A device started with a credential issued outside the app: that credential is this device's
+    /// (and its install id, the credential's), unless it's the one already kept. Throws while the
+    /// Keychain or the files can't be written.
+    package func useCredential(_ credential: IssuedCredential) throws {
+        if try stores.installId.load() != credential.installId { try stores.installId.save(credential.installId) }
+        if case .present(let kept) = stores.credentials.read(), kept.keyId == credential.keyId { return }
+        try stores.credentials.save(keyId: credential.keyId, secret: credential.secret)
+    }
+
+    /// This install's id as kept, without making one (diagnostics); nil before there is one or
+    /// while it can't be read.
+    package var keptInstallId: String? {
+        guard let id = (try? stores.installId.load()) ?? nil, !id.isEmpty else { return nil }
+        return id
+    }
+
+    /// Told when the server refuses the credential the device was started with (where an install
+    /// would register): the host stops Bubbl until the app starts it with a new one.
+    package func onCredentialRejected(_ handler: @escaping @Sendable () -> Void) {
+        hooks.credentialRejected = handler
+    }
+}
+
+/// Counts erasure attempts that failed for good, for the life of the process.
+final class AttemptCounter: @unchecked Sendable {
+    private let lock = NSLock()
+    private var count = 0
+
+    /// Counts one more; returns the count so far.
+    func next() -> Int {
+        lock.sync {
+            count += 1
+            return count
+        }
+    }
+}

package/ios-extension/Sources/BubblCore/Engine/Pushes.swift

@@ -0,0 +1,61 @@
+import Foundation
+
+/// What to do about a notification that has arrived (a push iOS handed the app, a pull, a geofence).
+package enum PushHandling: Sendable, Equatable {
+    /// Show this notification (Bubbl's screen, or the app's own listener). `received`: it arrived
+    /// just now for the first time (notification.received was recorded), rather than being opened
+    /// again.
+    case show(JSONValue, received: Bool)
+    /// A dashboard test push: there's nothing behind it to show or report.
+    case test(title: String, body: String)
+    /// Nothing to do: not Bubbl's, a newer format, already shown, gone, or Bubbl isn't active.
+    case nothing
+    /// It came without its notification and fetching it failed: try again (`failure` says when).
+    case fetchFailed(campaignNotificationId: String, failure: ApiFailure)
+}
+
+extension EngineCore {
+    /// A push iOS handed the app: its top-level data (beside aps), when it arrived with the app in
+    /// front (`opened` false) or when its notification was tapped (`opened` true).
+    ///
+    /// Unlike Android, where the SDK draws every push, iOS shows the alert itself and the app
+    /// hears of it only then. The first time a notification arrives, notification.received is
+    /// recorded and it's to be shown; after that (a push and a pull, the same push in front and
+    /// then tapped) it's shown again only when tapped: the person asked for it.
+    package func receivedPush(_ data: [String: JSONValue], opened: Bool) async -> PushHandling {
+        guard let message = PushMessage.parse(data) else { return .nothing }
+
+        switch message {
+        case .test(let title, let body):
+            return .test(title: title, body: body)
+        case .unsupported:
+            return .nothing
+        case .full(_, let notification):
+            return await notificationArrived(notification, opened: opened)
+        case .reference(let id):
+            guard isActive else { return .nothing }
+            switch await notifications.fetch(id) {
+            case .found(let found):
+                guard let notification = found.first else { return .nothing }
+                return await notificationArrived(notification, opened: opened)
+            case .gone:
+                BubblLog.info("Notification \(id) is no longer available (deleted, or its campaign ended)")
+                return .nothing
+            case .failed(let failure):
+                return .fetchFailed(campaignNotificationId: id, failure: failure)
+            }
+        }
+    }
+
+    /// A notification that has arrived, however it came: recorded as received and to be shown the
+    /// first time; shown again only when `opened` (tapped). Nothing is shown or recorded without
+    /// consent, after an opt-out, or paused.
+    package func notificationArrived(_ notification: JSONValue, opened: Bool) async -> PushHandling {
+        guard isActive, let id = notification["campaign_notification_id"]?.nonEmptyString else { return .nothing }
+        let first = recentNotifications.firstTime(id)
+        if first {
+            _ = try? await events.enqueue("notification.received", data: ["campaign_notification_id": .string(id)])
+        }
+        return first || opened ? .show(notification, received: first) : .nothing
+    }
+}