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

package/ios-sdk/BubblSDK/Engine/EngineHost.swift

@@ -0,0 +1,356 @@
+import Foundation
+#if canImport(UIKit)
+import UIKit
+#endif
+#if !COCOAPODS
+import BubblCore
+import BubblLaunch
+#endif
+
+/// Found by name by BubblLaunch's +load (which can't import this module): the end of launch.
+@available(iOS 17, *)
+@objc(BubblLaunchHook)
+final class BubblLaunchHook: NSObject {
+    @objc static func applicationDidFinishLaunching() {
+        EngineHost.shared.applicationDidFinishLaunching()
+    }
+
+    /// From +load, before main(): iOS wants background task handlers registered before launch ends.
+    @objc static func registerBackgroundTasks() {
+        #if os(iOS)
+        BackgroundRefresh.register()
+        #endif
+    }
+}
+
+/// Holds the engine for the life of the process and runs its work: on start, when the app comes to
+/// the front, and when it goes to the back (with the few seconds iOS gives). Work waits while the
+/// engine's data can't be read (before the first unlock after a reboot).
+@available(iOS 17, *)
+final class EngineHost: @unchecked Sendable {
+    static let shared = EngineHost()
+
+    let runner = WorkRunner(dataReadable: { EngineHost.dataReadable() })
+    let platform = AppleDevicePlatform()
+    /// Shows notifications: Bubbl's screen in front, a system notification in the background.
+    #if os(iOS)
+    let presenter: any NotificationPresenting = ScreenPresenter()
+    #else
+    let presenter: any NotificationPresenting = SystemAlertPresenter()
+    #endif
+    private let lock = NSLock()
+    private var core: EngineCore?
+    private var observing = false
+    private var listener: (@MainActor @Sendable (BubblMessage) -> Bool)?
+
+    var current: EngineCore? { lock.sync { core } }
+
+    /// The app's say over each notification before Bubbl shows it (Bubbl.setNotificationListener).
+    var notificationListener: (@MainActor @Sendable (BubblMessage) -> Bool)? {
+        get { lock.sync { listener } }
+        set { lock.sync { listener = newValue } }
+    }
+
+    /// What `start` was called with, kept so Bubbl can start itself at a later launch.
+    struct Started: Codable, Equatable {
+        let config: EngineConfig
+        let logLevel: BubblOptions.LogLevel
+    }
+
+    /// Starts (or keeps) the engine for `config`, with an API key or a credential issued outside the
+    /// app (Android's Bubbl.begin): the same again changes nothing; a different identity (another
+    /// credential, or switching between an API key and a credential) wipes what's kept here first
+    /// and starts as a new device.
+    func start(_ config: EngineConfig, credential: IssuedCredential? = nil, options: BubblOptions) -> EngineCore? {
+        SystemLog.use(options.logLevel)
+        let identity = EngineStart.identity(config, credential)
+        let afresh = EngineStart.startsAfresh(previous: previousIdentity(), next: identity)
+        guard let core = engine(for: config, fresh: afresh) else { return nil }
+        try? identityStore()?.save(identity)
+        try? rejectedStore()?.delete()
+        try? startedStore()?.save(Started(config: config, logLevel: options.logLevel))
+
+        guard afresh || credential != nil else {
+            proceed(core, options)
+            return core
+        }
+        // A new identity (wiped first) or a credential to keep, before anything of the engine's runs.
+        Task {
+            if afresh {
+                BubblLog.info("Bubbl starts afresh as a new device")
+                await runner.cancelAll()
+                do { try await core.wipeLocalData() } catch { BubblLog.warning("What an earlier device kept here couldn't all be removed yet") }
+            }
+            if let credential {
+                do { try core.useCredential(credential) } catch { BubblLog.warning("The credential can't be kept until the device is unlocked") }
+            }
+            proceed(core, options)
+        }
+        return core
+    }
+
+    /// What every start does once the engine is set up: the app's options, then whatever may run.
+    private func proceed(_ core: EngineCore, _ options: BubblOptions) {
+        do {
+            try core.privacy.update { $0.requireConsent = options.requireConsent }
+        } catch {
+            BubblLog.info("Bubbl's settings can't be read until the device is unlocked: it starts then")
+        }
+        if let segments = options.segments { _ = try? core.segments.set(segments) }
+        run(core, launchFinished: false)
+    }
+
+    /// What the device was started as before; an install from before identities were kept, started
+    /// with an API key, counts as one.
+    /// An identity kept before it named the key ("api_key" alone) is read with the key the last
+    /// start saved, so a key change is seen from the first update too.
+    private func previousIdentity() -> String? {
+        let started = (try? startedStore()?.load()) ?? nil
+        let lastKey = started?.config.apiKey.map { EngineStart.identity(EngineConfig(apiKey: $0, baseUrl: ""), nil) }
+        if let kept = (try? identityStore()?.load()) ?? nil { return kept == EngineStart.apiKey ? lastKey ?? kept : kept }
+        return lastKey
+    }
+
+    /// The server refused the credential Bubbl was started with: stopped, and staying stopped (no
+    /// self-restart) until the app starts Bubbl with a new one. Nothing is wiped: that start decides.
+    /// The app is told (BubblEvent.credentialRejected) and diagnostics say so.
+    func credentialRejected(_ core: EngineCore) {
+        guard current === core else { return }
+        try? rejectedStore()?.save(true)
+        BubblLog.error("The device's credential was refused: Bubbl has stopped until it's started with a new one")
+        stop()
+        BubblEvents.shared.emit(.credentialRejected)
+    }
+
+    /// Started with a credential the server has refused.
+    var isCredentialRejected: Bool { ((try? rejectedStore()?.load()) ?? nil) == true }
+
+    /// The end of every launch (BubblLaunch's +load watches for it): when an earlier launch started
+    /// Bubbl and it wasn't stopped since, it starts again now, as it was, so an app launched for a
+    /// geofence, a push or a tap has it before the app's own code (a wrapper's JavaScript or Dart)
+    /// runs. The app's own `start` later changes nothing, or applies its new options.
+    func applicationDidFinishLaunching() {
+        guard current == nil else { return }
+        // Before the first unlock after a reboot it can't be read: nothing starts (such events are lost).
+        guard let saved = (try? startedStore()?.load()) ?? nil else { return }
+        SystemLog.use(saved.logLevel)
+        guard let core = engine(for: saved.config) else { return }
+        BubblLog.info("Bubbl started itself for this launch, as the app last started it")
+        run(core, launchFinished: true)
+    }
+
+    /// The engine for `config`: the running one if it's for the same (and not `fresh`), a new one
+    /// otherwise.
+    private func engine(for config: EngineConfig, fresh: Bool = false) -> EngineCore? {
+        BubblLaunchLinked()
+        guard let directory = Self.directory() else {
+            BubblLog.error("Bubbl couldn't create its folder in Application Support")
+            return nil
+        }
+        return lock.sync {
+            if !fresh, let existing = self.core, existing.config == config { return existing }
+            let stores = EngineStores.files(in: directory, writeOptions: Self.writeOptions, credentials: KeychainCredentialStore())
+            let created = EngineCore(config: config, stores: stores, platform: platform, http: URLSessionHttpClient(), monitor: Self.regionMonitor())
+            created.onCredentialRejected { [weak created] in
+                guard let created else { return }
+                EngineHost.shared.credentialRejected(created)
+            }
+            self.core = created
+            return created
+        }
+    }
+
+    /// Location, push and the app's comings and goings, then whatever work the engine may do.
+    private func run(_ core: EngineCore, launchFinished: Bool) {
+        startLocation()
+        #if os(iOS)
+        PushIntegration.installWhenLaunched(launchFinished: launchFinished)
+        refreshPermissions()
+        #endif
+        observeTheApp()
+        resume(core)
+    }
+
+    private func startedStore() -> FileValueStore<Started>? {
+        Self.directory().map { FileValueStore(url: $0.appendingPathComponent("started.json"), writeOptions: Self.writeOptions) }
+    }
+
+    /// What the device was last started as (EngineStart.identity); outlives `stop`.
+    private func identityStore() -> FileValueStore<String>? {
+        Self.directory().map { FileValueStore(url: $0.appendingPathComponent("identity.json"), writeOptions: Self.writeOptions) }
+    }
+
+    private func rejectedStore() -> FileValueStore<Bool>? {
+        Self.directory().map { FileValueStore(url: $0.appendingPathComponent("credential_rejected.json"), writeOptions: Self.writeOptions) }
+    }
+
+    /// Stop until start is called again: nothing more runs, no geofences are watched, and Bubbl
+    /// doesn't start itself at the next launch (what it was started as is kept, so the next start
+    /// still knows whether it's the same device); nothing is dropped or told to the server.
+    func stop() {
+        try? startedStore()?.delete()
+        let stopped: EngineCore? = lock.sync {
+            defer { core = nil }
+            return core
+        }
+        Task {
+            await runner.cancelAll()
+            try? await stopped?.geofences.stop()
+        }
+    }
+
+    /// Whatever the engine may do now: the device, the queue, segments, the config.
+    func resume(_ core: EngineCore) {
+        if !core.sdkSupported {
+            BubblLog.error("This SDK (\(BubblVersion.sdk)) is older than the workspace's minimum: update it to use Bubbl")
+        } else if !core.isActive {
+            BubblLog.info(core.privacy.state?.active == true ? "Bubbl is paused by the server" : "Bubbl is waiting for consent")
+        }
+        resumePrivacyWork(core)
+        // Maintenance runs whatever the state: it's how an SDK below the minimum comes back.
+        submit("maintenance") { await $0.maintenance(configMaxAgeSeconds: EngineCore.openConfigMaxAgeSeconds) }
+        guard core.isActive else { return }
+        submit("device") { await $0.syncDevice() }
+        submit("events") { await $0.flushEvents() }
+        submit("segments") { await $0.pushSegments() }
+        if core.locationActive { checkGeofences() }
+    }
+
+    /// Runs `work` against whichever engine is current when it runs (none after `stop`).
+    func submit(_ name: String, _ work: @escaping @Sendable (EngineCore) async -> WorkOutcome) {
+        Task {
+            await runner.submit(name) {
+                guard let core = self.current else { return .done }
+                return await work(core)
+            }
+        }
+    }
+
+    // MARK: - The app
+
+    private func observeTheApp() {
+        let first: Bool = lock.sync {
+            defer { observing = true }
+            return !observing
+        }
+        guard first else { return }
+
+        #if canImport(UIKit) && !os(watchOS)
+        let center = NotificationCenter.default
+        // Every unlock, the first after a reboot included: held work may be able to run now. (Not
+        // protectedDataWillBecomeUnavailable, nor isProtectedDataAvailable: those follow the
+        // Complete class, which closes at every lock, while the engine's data stays readable.)
+        center.addObserver(forName: UIApplication.protectedDataDidBecomeAvailableNotification, object: nil, queue: nil) { [weak self] _ in
+            guard let self else { return }
+            Task { await self.runner.recheck() }
+        }
+        center.addObserver(forName: UIApplication.willEnterForegroundNotification, object: nil, queue: nil) { [weak self] _ in
+            self?.appOpened()
+        }
+        center.addObserver(forName: UIApplication.didEnterBackgroundNotification, object: nil, queue: .main) { [weak self] _ in
+            MainActor.assumeIsolated { self?.appWentToTheBack() }
+        }
+        Task { @MainActor [weak self] in
+            // Launched into the front (not woken in the background): that's an app open.
+            if UIApplication.shared.applicationState != .background { self?.appOpened() }
+        }
+        #endif
+    }
+
+    /// Where the device stands on permissions, for PUT /device and `permissions.status()` (the
+    /// person may have changed them in Settings while the app was away).
+    func refreshPermissions() {
+        #if os(iOS)
+        Task { @MainActor in _ = await PermissionFlow.shared.status() }
+        #endif
+    }
+
+    /// The app came to the front: app.opened, the queue, and the config if it's due.
+    private func appOpened() {
+        refreshPermissions()
+        #if os(iOS)
+        // Notifications may have been allowed since (by the app, a plugin, Settings): the device token
+        // then, not only at the next launch. (With the integration off, the app hands it over.)
+        PushIntegration.registerIfAllowed()
+        #endif
+        submit("app.opened") { core in
+            // Pushes iOS never delivered: pulled, and shown in front.
+            for notification in await core.appOpened(pull: true) {
+                _ = await self.show(notification, received: true, opened: false)
+            }
+            return .done
+        }
+        submit("events") { await $0.flushEvents() }
+        submit("maintenance") { await $0.maintenance(configMaxAgeSeconds: EngineCore.openConfigMaxAgeSeconds) }
+        appOpenedForLocation()
+    }
+
+    #if canImport(UIKit) && !os(watchOS)
+    /// The app went to the back: send what's queued in the time iOS allows.
+    @MainActor
+    private func appWentToTheBack() {
+        appWentToTheBackForLocation()
+        guard let core = current, core.isActive else { return }
+        BackgroundRefresh.schedule()
+        let time = BackgroundTime("tech.bubbl.sdk.flush")
+        Task {
+            // Not sent in time: the runner retries it, with its backoff, when the app next runs.
+            if case .retry = await core.flushEvents() { submit("events") { await $0.flushEvents() } }
+            time.end()
+        }
+    }
+    #endif
+
+    // MARK: - Files
+
+    /// Application Support/tech.bubbl.sdk, kept out of backups: a restored install id would make two
+    /// phones one device, and a restored geofence state would claim places the device isn't in.
+    static func directory() -> URL? {
+        guard let base = FileManager.default.urls(for: .applicationSupportDirectory, in: .userDomainMask).first else { return nil }
+        var directory = base.appendingPathComponent("tech.bubbl.sdk", isDirectory: true)
+        do {
+            try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
+            var values = URLResourceValues()
+            values.isExcludedFromBackup = true
+            try directory.setResourceValues(values)
+        } catch {
+            // Already there (and excluded), or not writable yet: the stores say which when used.
+        }
+        return directory
+    }
+
+    /// Whether the engine's files (and the Keychain item, whose class matches) can be read now,
+    /// tried on a file of their protection class: before the first unlock after a reboot an
+    /// existing one can't be read and a new one can't be made.
+    static func dataReadable(in directory: URL? = directory()) -> Bool {
+        guard let directory else { return false }
+        let probe = directory.appendingPathComponent("readable")
+        if (try? Data(contentsOf: probe)) != nil { return true }
+        guard !FileManager.default.fileExists(atPath: probe.path) else { return false }
+        do {
+            try Data([1]).write(to: probe, options: writeOptions.union(.atomic))
+            return true
+        } catch {
+            return false
+        }
+    }
+
+    /// Readable from the first unlock after a reboot until the next reboot (region events in the
+    /// background need that); unreadable before it.
+    static var writeOptions: Data.WritingOptions {
+        #if os(iOS)
+        [.completeFileProtectionUntilFirstUserAuthentication]
+        #else
+        []
+        #endif
+    }
+}
+
+/// Region monitoring until the location slice (7): watches nothing, as for a user who allowed
+/// location only while the app is in use.
+@available(iOS 17, *)
+struct InactiveRegionMonitor: RegionMonitor {
+    func capacity() async -> Int { 0 }
+    func watch(_ regions: [WatchedRegion]) async -> Bool { true }
+    func stop() async {}
+}

package/ios-sdk/BubblSDK/Engine/SupportedBubbl.swift

@@ -0,0 +1,320 @@
+import Foundation
+#if canImport(UIKit)
+import UIKit
+#endif
+#if canImport(UserNotifications)
+import UserNotifications
+#endif
+#if !COCOAPODS
+import BubblCore
+#endif
+
+/// `Bubbl`'s calls on iOS 17 and later: the engine.
+@available(iOS 17, *)
+struct SupportedBubbl: BubblBackend {
+    var isSupported: Bool { true }
+
+    // MARK: - Starting
+
+    func start(apiKey: String, options: BubblOptions) {
+        let key = apiKey.trimmingCharacters(in: .whitespacesAndNewlines)
+        var baseUrl = options.baseUrl.trimmingCharacters(in: .whitespacesAndNewlines)
+        while baseUrl.hasSuffix("/") { baseUrl.removeLast() }
+
+        guard !key.isEmpty else {
+            SystemLog.use(options.logLevel)
+            return BubblLog.error("Bubbl.start: the API key is empty")
+        }
+        guard Bubbl.isAllowedBaseUrl(baseUrl) else {
+            SystemLog.use(options.logLevel)
+            return BubblLog.error("Bubbl.start: baseUrl must be https:// (http:// only for localhost or a .test host)")
+        }
+
+        guard let core = EngineHost.shared.start(EngineConfig(apiKey: key, baseUrl: baseUrl), options: options) else { return }
+        BubblLog.info("Bubbl \(BubblVersion.sdk) started")
+        if let warning = EngineStart.keyWarning(apiKey: key, debugBuild: Self.debugBuild) { BubblLog.warning(warning) }
+        core.announceSandbox()
+    }
+
+    /// The app's build, as the SDK was built with it (a Swift package builds in the app's
+    /// configuration): for the key-and-build warning.
+    static var debugBuild: Bool {
+        #if DEBUG
+        true
+        #else
+        false
+        #endif
+    }
+
+    func start(credential: BubblCredential, options: BubblOptions) {
+        var baseUrl = options.baseUrl.trimmingCharacters(in: .whitespacesAndNewlines)
+        while baseUrl.hasSuffix("/") { baseUrl.removeLast() }
+
+        guard [credential.keyId, credential.secret, credential.installId].allSatisfy({ !$0.trimmingCharacters(in: .whitespaces).isEmpty }) else {
+            SystemLog.use(options.logLevel)
+            return BubblLog.error("Bubbl.start: the credential is incomplete")
+        }
+        guard Bubbl.isAllowedBaseUrl(baseUrl) else {
+            SystemLog.use(options.logLevel)
+            return BubblLog.error("Bubbl.start: baseUrl must be https:// (http:// only for localhost or a .test host)")
+        }
+
+        guard let core = EngineHost.shared.start(EngineConfig(apiKey: nil, baseUrl: baseUrl), credential: credential.issued, options: options) else { return }
+        BubblLog.info("Bubbl \(BubblVersion.sdk) started with a credential")
+        core.announceSandbox()
+    }
+
+    func stop() {
+        EngineHost.shared.stop()
+    }
+
+    // MARK: - Consent and privacy
+
+    func setConsent(_ granted: Bool) {
+        guard granted else { return optOut() }
+        guard let core = started("setConsent") else { return }
+        do {
+            if try core.grantConsent() { EngineHost.shared.consentGiven(core) }
+        } catch {
+            BubblLog.warning("Bubbl.setConsent can't be saved until the device is unlocked: ask again then")
+        }
+    }
+
+    func optOut() {
+        guard let core = started("optOut") else { return }
+        EngineHost.shared.optOut(core)
+    }
+
+    func deleteMyData() {
+        guard let core = started("deleteMyData") else { return }
+        EngineHost.shared.erase(core)
+    }
+
+    func setLocationEnabled(_ enabled: Bool) {
+        guard let core = started("setLocationEnabled") else { return }
+        EngineHost.shared.setLocationEnabled(enabled, core)
+    }
+
+    func registerTestDevice(_ code: String) async -> BubblTestDeviceResult {
+        guard let core = started("registerTestDevice") else {
+            return BubblTestDeviceResult(approved: false, message: "Bubbl.start hasn't been called")
+        }
+        let result = await core.registerTestDevice(code)
+        return BubblTestDeviceResult(approved: result.approved, message: result.message)
+    }
+
+    // MARK: - Targeting and events
+
+    func setSegments(_ segments: [String]) {
+        guard let core = started("setSegments") else { return }
+        do {
+            if try core.segments.set(segments) { EngineHost.shared.submit("segments") { await $0.pushSegments() } }
+        } catch {
+            BubblLog.warning("Bubbl.setSegments: they can't be saved until the device is unlocked")
+        }
+    }
+
+    func track(_ name: String, properties: [String: Any?]) {
+        guard let core = started("track") else { return }
+        var converted: [String: JSONValue] = [:]
+        for (key, value) in properties {
+            if let json = JSONValue(app: value) { converted[key] = json } else {
+                BubblLog.warning("Bubbl.track: a property that isn't text, a number or true/false was left out")
+            }
+        }
+        Task {
+            if await core.track(name, properties: converted) {
+                EngineHost.shared.submit("events") { await $0.flushEvents() }
+            }
+        }
+    }
+
+    // MARK: - Notifications
+
+    func setNotificationListener(_ listener: (@MainActor @Sendable (BubblMessage) -> Bool)?) {
+        EngineHost.shared.notificationListener = listener
+    }
+
+    func addEventListener(_ listener: @escaping @MainActor @Sendable (BubblEvent) -> Void) -> BubblEventToken {
+        BubblEvents.shared.add(listener)
+    }
+
+    func removeEventListener(_ token: BubblEventToken) {
+        BubblEvents.shared.remove(token)
+    }
+
+    func present(_ message: BubblMessage) {
+        guard started("present") != nil else { return }
+        Task { _ = await EngineHost.shared.presenter.present(message.notification.json, opened: false) }
+    }
+
+    /// Records a notification event the app reports (and tells its event listeners), then sends
+    /// the queue.
+    func report(_ call: String, _ record: @escaping @Sendable (NotificationEvents) async throws -> Void) {
+        guard let core = started(call), core.isActive else { return }
+        let events = EngineHost.shared.notificationEvents(core)
+        Task {
+            do {
+                try await record(events)
+                EngineHost.shared.submit("events") { await $0.flushEvents() }
+            } catch {
+                BubblLog.warning("Bubbl.\(call): not recorded (\(type(of: error)))")
+            }
+        }
+    }
+
+    func submitSurvey(_ message: BubblMessage, answers: [String: Any?]) -> Bool {
+        var converted: [String: JSONValue] = [:]
+        for (id, value) in answers {
+            guard let json = JSONValue(app: value) else {
+                BubblLog.warning("Bubbl.submitSurvey: the answer to \(id) isn't a choice id, a list of them, a number, true/false or text")
+                return false
+            }
+            converted[id] = json
+        }
+        switch SurveyForm.fromAnswers(message.notification.questions, converted) {
+        case .failure(let problem):
+            BubblLog.warning("Bubbl.submitSurvey: \(problem)")
+            return false
+        case .success(let form):
+            report("submitSurvey") { try await $0.surveySubmitted(message.notification, form) }
+            return true
+        }
+    }
+
+    func openCta(_ message: BubblMessage) {
+        guard let link = message.ctaUrl, LinkPolicy.canOpen(link), let url = URL(string: link) else { return }
+        report("reportCtaClicked") { try await $0.ctaClicked(message.notification) }
+        #if canImport(UIKit) && !os(watchOS)
+        Task { @MainActor in UIApplication.shared.open(url) }
+        #endif
+    }
+
+    // MARK: - Push
+
+    func isBubblMessage(_ userInfo: [AnyHashable: Any]) -> Bool {
+        PushMessage.isBubbl(EngineHost.pushData(userInfo))
+    }
+
+    #if os(iOS)
+    func setPushToken(_ deviceToken: Data) {
+        EngineHost.shared.pushTokenReceived(deviceToken)
+    }
+
+    func willPresent(_ notification: UNNotification, completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) -> Bool {
+        NotificationDelegateHooks.willPresent(notification, completionHandler)
+    }
+
+    func didReceive(_ response: UNNotificationResponse, completionHandler: @escaping () -> Void) -> Bool {
+        NotificationDelegateHooks.didReceive(response, completionHandler)
+    }
+    #endif
+
+    // MARK: - Permissions
+
+    func permissionStatus() -> BubblPermissionStatus? {
+        guard EngineHost.shared.current != nil else { return nil }
+        return EngineHost.shared.platform.permissionStatus.map(BubblPermissionStatus.init)
+    }
+
+    func requestPermission(_ request: PermissionRequest, _ call: String) async -> BubblPermissionStatus? {
+        guard EngineHost.shared.current != nil else {
+            BubblLog.warning("Bubbl.\(call) before Bubbl.start: ignored")
+            return nil
+        }
+        #if os(iOS)
+        return BubblPermissionStatus(await PermissionFlow.shared.request(request))
+        #else
+        return nil
+        #endif
+    }
+
+    /// No engine needed, so no `start` check: an app can send the user to its settings page before
+    /// starting Bubbl.
+    func openSettings() {
+        #if os(iOS)
+        Task { @MainActor in PermissionFlow.openSettings() }
+        #endif
+    }
+
+    // MARK: - Diagnostics
+
+    func diagnostics() async -> Bubbl.Diagnostics {
+        let backgroundRefresh = await Self.backgroundRefreshAvailable()
+        let lowPower = ProcessInfo.processInfo.isLowPowerModeEnabled
+        guard let core = EngineHost.shared.current else {
+            return Bubbl.Diagnostics(
+                started: false, supported: true, sdkVersion: Bubbl.sdkVersion, sdkSupported: true, registered: false, installId: nil, active: false,
+                pausedUntil: nil, consentRequired: false, consent: nil, locationEnabled: true, permissions: nil, hasPushToken: false,
+                geofences: 0, queuedEvents: 0, lastError: BubblLog.lastError, credentialRejected: EngineHost.shared.isCredentialRejected, backgroundLocation: false,
+                transitionsDroppedWhileLocked: 0, backgroundRefreshAvailable: backgroundRefresh, lowPowerMode: lowPower,
+                osWatchesGeofences: false, environment: nil, testDevice: nil
+            )
+        }
+        let privacy = core.privacy.state
+        return Bubbl.Diagnostics(
+            started: true,
+            supported: true,
+            sdkVersion: Bubbl.sdkVersion,
+            sdkSupported: core.sdkSupported,
+            registered: core.everRegistered,
+            installId: core.keptInstallId,
+            active: core.isActive,
+            pausedUntil: core.pausedUntilSeconds,
+            consentRequired: privacy?.requireConsent ?? false,
+            consent: privacy?.consent,
+            locationEnabled: privacy?.locationEnabled ?? true,
+            permissions: permissionStatus(),
+            hasPushToken: EngineHost.shared.platform.pushToken() != nil,
+            geofences: (try? await core.geofences.geofenceCount()) ?? 0,
+            queuedEvents: (try? await core.events.size()) ?? 0,
+            lastError: BubblLog.lastError,
+            credentialRejected: EngineHost.shared.isCredentialRejected,
+            backgroundLocation: await Self.backgroundLocation(),
+            transitionsDroppedWhileLocked: core.transitionsDroppedWhileLocked,
+            backgroundRefreshAvailable: backgroundRefresh,
+            lowPowerMode: lowPower,
+            osWatchesGeofences: await Self.osWatchesGeofences(),
+            environment: core.workspace?.environment,
+            testDevice: core.workspace?.testDevice.map { Bubbl.Diagnostics.TestDevice(status: $0.status, code: $0.code) }
+        )
+    }
+
+    // MARK: - Internals
+
+    private func started(_ call: String) -> EngineCore? {
+        guard let core = EngineHost.shared.current else {
+            BubblLog.warning("Bubbl.\(call) before Bubbl.start: ignored")
+            return nil
+        }
+        return core
+    }
+
+    /// "Always", with precise location: iOS watches the geofences with the app closed.
+    @MainActor
+    private static func backgroundLocation() -> Bool {
+        #if os(iOS)
+        LocationService.shared.access == .always
+        #else
+        false
+        #endif
+    }
+
+    @MainActor
+    private static func osWatchesGeofences() -> Bool {
+        #if os(iOS)
+        LocationService.shared.osWatches
+        #else
+        false
+        #endif
+    }
+
+    @MainActor
+    private static func backgroundRefreshAvailable() -> Bool {
+        #if canImport(UIKit) && !os(watchOS)
+        UIApplication.shared.backgroundRefreshStatus == .available
+        #else
+        false
+        #endif
+    }
+}