@mentra/bluetooth-sdk 3.3.0-dev.822 → 3.3.0-dev.825

package/ios/Source/internal/BluetoothSdkUsageTracker.swift

@@ -0,0 +1,428 @@
+import Foundation
+
+/// Pure decision logic for the Mentra Live usage events: one event per photo,
+/// recording, stream, mic session, setup attempt, OTA attempt and timed-out
+/// glasses command. It owns no threads and no I/O; `BluetoothSdkAnalytics` feeds
+/// it facts and captures what it returns, and only when analytics is enabled.
+///
+/// Durations are measured on the phone's clock between the start and end
+/// statuses it observes. A recording or stream whose end never reaches this
+/// process (the app was killed mid-stream) produces only its start.
+struct BluetoothSdkUsageTracker {
+    static let eventPhotoTaken = "bluetooth_sdk_photo_taken"
+    static let eventVideoRecorded = "bluetooth_sdk_video_recorded"
+    static let eventStreamStarted = "bluetooth_sdk_stream_started"
+    static let eventStreamEnded = "bluetooth_sdk_stream_ended"
+    static let eventMicSession = "bluetooth_sdk_mic_session"
+    static let eventWifiSetup = "bluetooth_sdk_wifi_setup"
+    static let eventHotspotStarted = "bluetooth_sdk_hotspot_started"
+    static let eventOtaFinished = "bluetooth_sdk_ota_finished"
+    static let eventRequestFailed = "bluetooth_sdk_request_failed"
+
+    static let maxRequestTimeoutsDefault = 100
+    /// Glasses report button-capture photo failures under this request id (ASG MediaCaptureService).
+    static let localPhotoRequestId = "local"
+    /// Button-started recordings use `local_video_<ts>_<rand>` request ids on the glasses.
+    static let localVideoRequestPrefix = "local_video_"
+
+    private static let maxOpenRecordings = 16
+    private static let maxOtaSessions = 16
+    private static let maxDetailLength = 200
+    private static let triggerApi = "api"
+    private static let triggerButton = "button"
+    private static let otaComplete = "complete"
+    private static let otaFailed = "failed"
+    private static let otaIdle = "idle"
+    private static let legacyTerminalStreamStates: Set<String> = ["stopped", "reconnect_failed"]
+    private static let liveStreamStates: Set<String> = ["streaming", "reconnected"]
+    private static let urlPattern = try! NSRegularExpression(pattern: #"[A-Za-z][A-Za-z0-9+.\-]*://\S+"#)
+
+    private struct OpenRecording {
+        var startedAtMs: Int64?
+        var width: Int?
+        var height: Int?
+        var fps: Int?
+        var save: Bool?
+        var maxDurationMinutes: Int?
+        var stoppedByApp = false
+    }
+
+    private struct OpenStream {
+        let streamId: String
+        let streamProtocol: String
+        /// Set by the first live status; nil while the start is still pending.
+        var startedAtMs: Int64?
+        var reconnectAttempts = 0
+        var stoppedByApp = false
+        var bitrate: Int64?
+        var fps: Double?
+        var droppedFrames: Int64?
+        var temperatureC: Double?
+    }
+
+    private struct OpenOta {
+        let startedAtMs: Int64
+        let fromBuildNumber: String
+        let fromBesFirmwareVersion: String
+        let fromMtkFirmwareVersion: String
+    }
+
+    private let maxRequestTimeouts: Int
+    private var recordings = BoundedMap<String, OpenRecording>(capacity: BluetoothSdkUsageTracker.maxOpenRecordings)
+    private var stream: OpenStream?
+    private var micSource: String?
+    private var micStartedAtMs: Int64 = 0
+    private var micTranscribed = false
+    private var otaSessions = BoundedMap<String, OpenOta>(capacity: BluetoothSdkUsageTracker.maxOtaSessions)
+    private var finishedOtaSessions = BoundedMap<String, Bool>(capacity: BluetoothSdkUsageTracker.maxOtaSessions)
+    private var requestTimeouts = 0
+
+    init(maxRequestTimeouts: Int = BluetoothSdkUsageTracker.maxRequestTimeoutsDefault) {
+        self.maxRequestTimeouts = maxRequestTimeouts
+    }
+
+    func photoSettled(
+        size: String,
+        mode: String,
+        compress: String,
+        save: Bool,
+        transferMethod: String,
+        latencyMs: Int64,
+        fileSizeBytes: Int64?,
+        errorCode: String?
+    ) -> AnalyticsEvent {
+        var properties: [String: Any] = ["trigger": Self.triggerApi]
+        Self.putOutcome(&properties, errorCode)
+        properties["latency_ms"] = latencyMs
+        properties["photo_size"] = size
+        properties["photo_mode"] = mode
+        properties["compress"] = compress
+        properties["save_to_gallery"] = save
+        properties["transfer_method"] = transferMethod
+        if let fileSizeBytes, fileSizeBytes > 0 { properties["file_size_bytes"] = fileSizeBytes }
+        return AnalyticsEvent(name: Self.eventPhotoTaken, properties: properties)
+    }
+
+    /// A button photo the glasses could not take; successful button photos never reach the phone.
+    func buttonPhotoFailed(errorCode: String?) -> AnalyticsEvent {
+        var properties: [String: Any] = ["trigger": Self.triggerButton]
+        Self.putOutcome(&properties, errorCode ?? "photo_request_failed")
+        return AnalyticsEvent(name: Self.eventPhotoTaken, properties: properties)
+    }
+
+    /// Records the API parameters of a recording so its end event can report them.
+    mutating func videoRequested(requestId: String, width: Int, height: Int, fps: Int, save: Bool, maxDurationMinutes: Int) {
+        recordings[requestId] = OpenRecording(
+            width: width > 0 ? width : nil,
+            height: height > 0 ? height : nil,
+            fps: fps > 0 ? fps : nil,
+            save: save,
+            maxDurationMinutes: maxDurationMinutes > 0 ? maxDurationMinutes : nil
+        )
+    }
+
+    mutating func videoStopRequested(requestId: String) {
+        guard var recording = recordings[requestId] else { return }
+        recording.stoppedByApp = true
+        recordings[requestId] = recording
+    }
+
+    /// Glasses report every recording, button-started ones included, through
+    /// `video_recording_status`. A recording is reported once: when it stops, or
+    /// when a command for it fails. `not_recording` answers a stop for a recording
+    /// that already ended and is not a recording of its own.
+    mutating func videoStatus(requestId: String, status: String, success: Bool, nowMs: Int64) -> AnalyticsEvent? {
+        guard !requestId.isBlank else { return nil }
+        if success {
+            switch status {
+            case "recording_started":
+                var recording = recordings[requestId] ?? OpenRecording()
+                if recording.startedAtMs == nil { recording.startedAtMs = nowMs }
+                recordings[requestId] = recording
+                return nil
+            case "recording_stopped":
+                guard let recording = recordings.removeValue(forKey: requestId) else { return nil }
+                return videoEvent(requestId: requestId, recording: recording, nowMs: nowMs, errorCode: nil)
+            default:
+                return nil
+            }
+        }
+        if status == "not_recording" {
+            recordings.removeValue(forKey: requestId)
+            return nil
+        }
+        let recording = recordings.removeValue(forKey: requestId) ?? OpenRecording()
+        return videoEvent(
+            requestId: requestId,
+            recording: recording,
+            nowMs: nowMs,
+            errorCode: status.isBlank ? "video_recording_failed" : status
+        )
+    }
+
+    private func videoEvent(requestId: String, recording: OpenRecording, nowMs: Int64, errorCode: String?) -> AnalyticsEvent {
+        var properties: [String: Any] = [
+            "trigger": requestId.hasPrefix(Self.localVideoRequestPrefix) ? Self.triggerButton : Self.triggerApi,
+        ]
+        Self.putOutcome(&properties, errorCode)
+        if let startedAtMs = recording.startedAtMs { properties["duration_ms"] = max(nowMs - startedAtMs, 0) }
+        if let width = recording.width { properties["width"] = width }
+        if let height = recording.height { properties["height"] = height }
+        if let fps = recording.fps { properties["fps"] = fps }
+        if let save = recording.save { properties["save_to_gallery"] = save }
+        if let maxDurationMinutes = recording.maxDurationMinutes { properties["max_duration_minutes"] = maxDurationMinutes }
+        properties["stopped_by_app"] = recording.stoppedByApp
+        return AnalyticsEvent(name: Self.eventVideoRecorded, properties: properties)
+    }
+
+    /// Opens the stream as its start command is sent, so a status that arrives
+    /// before `startStream` returns is still attributed to it. A new start
+    /// supersedes a stream that was live (the glasses stop it), so that stream is
+    /// reported as `replaced`.
+    mutating func streamRequested(streamId: String, streamUrl: String, nowMs: Int64) -> AnalyticsEvent? {
+        var replaced: AnalyticsEvent?
+        if let open = stream, open.startedAtMs != nil, open.streamId != streamId {
+            replaced = Self.streamEndedEvent(open, endState: "replaced", errorDetails: nil, nowMs: nowMs)
+        }
+        stream = OpenStream(streamId: streamId, streamProtocol: Self.streamProtocol(streamUrl))
+        return replaced
+    }
+
+    func streamStartSettled(
+        streamUrl: String,
+        width: Int?,
+        height: Int?,
+        fps: Int?,
+        bitrate: Int?,
+        captureAudio: Bool,
+        glassesNetwork: String,
+        latencyMs: Int64,
+        errorCode: String?
+    ) -> AnalyticsEvent {
+        var properties: [String: Any] = [:]
+        Self.putOutcome(&properties, errorCode)
+        properties["protocol"] = Self.streamProtocol(streamUrl)
+        if let width { properties["width"] = width }
+        if let height { properties["height"] = height }
+        if let fps { properties["fps"] = fps }
+        if let bitrate { properties["bitrate"] = bitrate }
+        properties["capture_audio"] = captureAudio
+        properties["glasses_network"] = glassesNetwork
+        properties["latency_ms"] = latencyMs
+        return AnalyticsEvent(name: Self.eventStreamStarted, properties: properties)
+    }
+
+    mutating func streamStopRequested() {
+        stream?.stoppedByApp = true
+    }
+
+    /// Folds one accepted `stream_status` into the open stream and reports the
+    /// stream once, on its terminal status. Glasses with stream revisions flag the
+    /// terminal status; older glasses only send a final `stopped` or
+    /// `reconnect_failed`. A stream that never went live ends silently: its
+    /// `bluetooth_sdk_stream_started` already reported the failure.
+    mutating func streamStatus(
+        streamId: String?,
+        state: String,
+        terminal: Bool?,
+        reconnectAttempt: Int?,
+        bitrate: Int64?,
+        fps: Double?,
+        droppedFrames: Int64?,
+        temperatureC: Double?,
+        errorDetails: String?,
+        nowMs: Int64
+    ) -> AnalyticsEvent? {
+        guard var open = stream else { return nil }
+        if let streamId, !streamId.isBlank, streamId != open.streamId { return nil }
+        if Self.liveStreamStates.contains(state), open.startedAtMs == nil { open.startedAtMs = nowMs }
+        if let reconnectAttempt { open.reconnectAttempts = max(open.reconnectAttempts, reconnectAttempt) }
+        if let bitrate { open.bitrate = bitrate }
+        if let fps { open.fps = fps }
+        if let droppedFrames { open.droppedFrames = droppedFrames }
+        if let temperatureC { open.temperatureC = temperatureC }
+        let ended = terminal == true || (terminal == nil && Self.legacyTerminalStreamStates.contains(state))
+        guard ended else {
+            stream = open
+            return nil
+        }
+        stream = nil
+        guard open.startedAtMs != nil else { return nil }
+        return Self.streamEndedEvent(open, endState: state, errorDetails: errorDetails, nowMs: nowMs)
+    }
+
+    private static func streamEndedEvent(_ open: OpenStream, endState: String, errorDetails: String?, nowMs: Int64) -> AnalyticsEvent {
+        var properties: [String: Any] = [
+            "protocol": open.streamProtocol,
+            "end_state": endState,
+            "stopped_by_app": open.stoppedByApp,
+            "reconnect_attempts": open.reconnectAttempts,
+        ]
+        if let startedAtMs = open.startedAtMs { properties["duration_ms"] = max(nowMs - startedAtMs, 0) }
+        if let detail = Self.sanitizedDetail(errorDetails) { properties["error_code"] = detail }
+        if let bitrate = open.bitrate { properties["bitrate"] = bitrate }
+        if let fps = open.fps { properties["fps"] = fps }
+        if let droppedFrames = open.droppedFrames { properties["dropped_frames"] = droppedFrames }
+        if let temperatureC = open.temperatureC { properties["temperature_c"] = temperatureC }
+        return AnalyticsEvent(name: Self.eventStreamEnded, properties: properties)
+    }
+
+    /// Follows the active mic source. A session ends when the source turns off or
+    /// changes; `local_transcription` is true if on-device transcription ran at
+    /// any point during it.
+    mutating func observeMic(currentMic: String, transcribing: Bool, nowMs: Int64) -> AnalyticsEvent? {
+        let next: String? = currentMic.isBlank ? nil : currentMic
+        let previous = micSource
+        if next == previous {
+            if next != nil, transcribing { micTranscribed = true }
+            return nil
+        }
+        let ended = previous.map {
+            AnalyticsEvent(
+                name: Self.eventMicSession,
+                properties: [
+                    "duration_ms": max(nowMs - micStartedAtMs, 0),
+                    "mic_source": $0,
+                    "local_transcription": micTranscribed,
+                ]
+            )
+        }
+        micSource = next
+        micStartedAtMs = nowMs
+        micTranscribed = next != nil && transcribing
+        return ended
+    }
+
+    func wifiSetupSettled(latencyMs: Int64, errorCode: String?) -> AnalyticsEvent {
+        var properties: [String: Any] = [:]
+        Self.putOutcome(&properties, errorCode)
+        properties["latency_ms"] = latencyMs
+        return AnalyticsEvent(name: Self.eventWifiSetup, properties: properties)
+    }
+
+    func hotspotStartSettled(latencyMs: Int64, errorCode: String?) -> AnalyticsEvent {
+        var properties: [String: Any] = [:]
+        Self.putOutcome(&properties, errorCode)
+        properties["latency_ms"] = latencyMs
+        return AnalyticsEvent(name: Self.eventHotspotStarted, properties: properties)
+    }
+
+    /// One event per OTA session, on `complete` or `failed`. The "from" versions are
+    /// the glasses versions when this process first saw the session in progress.
+    mutating func otaStatus(
+        sessionId: String,
+        status: String,
+        stepType: String,
+        totalSteps: Int,
+        errorMessage: String?,
+        fromBuildNumber: String,
+        fromBesFirmwareVersion: String,
+        fromMtkFirmwareVersion: String,
+        nowMs: Int64
+    ) -> AnalyticsEvent? {
+        if finishedOtaSessions.contains(sessionId) { return nil }
+        if status != Self.otaComplete, status != Self.otaFailed {
+            if status != Self.otaIdle, !otaSessions.contains(sessionId) {
+                otaSessions[sessionId] = OpenOta(
+                    startedAtMs: nowMs,
+                    fromBuildNumber: fromBuildNumber,
+                    fromBesFirmwareVersion: fromBesFirmwareVersion,
+                    fromMtkFirmwareVersion: fromMtkFirmwareVersion
+                )
+            }
+            return nil
+        }
+        finishedOtaSessions[sessionId] = true
+        let open = otaSessions.removeValue(forKey: sessionId)
+        let success = status == Self.otaComplete
+        var properties: [String: Any] = ["success": success]
+        if !success {
+            if !stepType.isBlank { properties["failed_step_type"] = stepType }
+            if let detail = Self.sanitizedDetail(errorMessage) { properties["error_message"] = detail }
+        }
+        if totalSteps > 0 { properties["total_steps"] = totalSteps }
+        if let open {
+            properties["duration_ms"] = max(nowMs - open.startedAtMs, 0)
+            if !open.fromBuildNumber.isBlank { properties["from_build_number"] = open.fromBuildNumber }
+            if !open.fromBesFirmwareVersion.isBlank { properties["from_bes_firmware_version"] = open.fromBesFirmwareVersion }
+            if !open.fromMtkFirmwareVersion.isBlank { properties["from_mtk_firmware_version"] = open.fromMtkFirmwareVersion }
+        }
+        return AnalyticsEvent(name: Self.eventOtaFinished, properties: properties)
+    }
+
+    /// At most `maxRequestTimeouts` per SDK instance, so a failure loop cannot run up event volume.
+    mutating func requestTimedOut(operation: String) -> AnalyticsEvent? {
+        guard requestTimeouts < maxRequestTimeouts else { return nil }
+        requestTimeouts += 1
+        return AnalyticsEvent(
+            name: Self.eventRequestFailed,
+            properties: ["operation": operation, "error_code": "request_timeout"]
+        )
+    }
+
+    /// Mirrors the glasses' scheme mapping in ASG StreamCommandHandler.
+    static func streamProtocol(_ streamUrl: String) -> String {
+        let trimmed = streamUrl.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard let separator = trimmed.range(of: "://") else { return "unknown" }
+        switch trimmed[..<separator.lowerBound].lowercased() {
+        case "srt": return "srt"
+        case "rtmp", "rtmps": return "rtmp"
+        case "http", "https": return "whip"
+        default: return "unknown"
+        }
+    }
+
+    /// Free-text details may carry stream or upload URLs; those never leave the phone.
+    static func sanitizedDetail(_ value: String?) -> String? {
+        guard let value else { return nil }
+        let range = NSRange(value.startIndex..., in: value)
+        let replaced = urlPattern.stringByReplacingMatches(in: value, range: range, withTemplate: "<url>")
+        let trimmed = replaced.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return nil }
+        return String(trimmed.prefix(maxDetailLength))
+    }
+
+    private static func putOutcome(_ properties: inout [String: Any], _ errorCode: String?) {
+        properties["success"] = errorCode == nil
+        if let detail = sanitizedDetail(errorCode) { properties["error_code"] = detail }
+    }
+}
+
+/// Insertion-ordered map that drops its oldest entry beyond `capacity`, so a
+/// stream of ids whose end never arrives cannot grow without bound.
+private struct BoundedMap<Key: Hashable, Value> {
+    private let capacity: Int
+    private var order: [Key] = []
+    private var storage: [Key: Value] = [:]
+
+    init(capacity: Int) {
+        self.capacity = capacity
+    }
+
+    func contains(_ key: Key) -> Bool {
+        storage[key] != nil
+    }
+
+    subscript(key: Key) -> Value? {
+        get { storage[key] }
+        set {
+            guard let newValue else {
+                removeValue(forKey: key)
+                return
+            }
+            if storage.updateValue(newValue, forKey: key) == nil {
+                order.append(key)
+                if order.count > capacity {
+                    storage.removeValue(forKey: order.removeFirst())
+                }
+            }
+        }
+    }
+
+    @discardableResult
+    mutating func removeValue(forKey key: Key) -> Value? {
+        guard let removed = storage.removeValue(forKey: key) else { return nil }
+        order.removeAll { $0 == key }
+        return removed
+    }
+}

package/ios/Tests/BluetoothSdkAnalyticsTrackerTests.swift

@@ -4,8 +4,59 @@ import XCTest
 final class BluetoothSdkAnalyticsTrackerTests: XCTestCase {
     private var tracker = BluetoothSdkAnalyticsTracker(simulatedModel: "Simulated Glasses")
 
-    private func snapshot(connected: Bool, model: String = "Mentra Live", serial: String = "") -> AnalyticsGlassesSnapshot {
-        AnalyticsGlassesSnapshot(connected: connected, fullyBooted: connected, model: model, serialNumber: serial)
+    private func snapshot(
+        connected: Bool,
+        model: String = "Mentra Live",
+        serial: String = "",
+        battery: Int = -1,
+        charging: Bool = false
+    ) -> AnalyticsGlassesSnapshot {
+        var snapshot = AnalyticsGlassesSnapshot(connected: connected, fullyBooted: connected, model: model, serialNumber: serial)
+        snapshot.batteryLevel = battery
+        snapshot.charging = charging
+        return snapshot
+    }
+
+    func testCountedConnectionReportsItsLengthReasonAndBatteryWhenItEnds() throws {
+        tracker.initialize(snapshot(connected: false), reportingDay: 100)
+        _ = tracker.observe(snapshot(connected: true), reportingDay: 100, nowMs: 1000)
+        _ = tracker.observe(snapshot(connected: true, battery: 80), reportingDay: 100, nowMs: 2000)
+        _ = tracker.observe(snapshot(connected: true, battery: 71, charging: true), reportingDay: 100, nowMs: 3000)
+
+        let ended = tracker.observe(snapshot(connected: false), reportingDay: 100, nowMs: 61000) {
+            BluetoothSdkAnalyticsTracker.disconnectUser
+        }
+        XCTAssertEqual(ended.count, 1)
+        let disconnected = try XCTUnwrap(ended.first)
+        XCTAssertEqual(disconnected.name, "bluetooth_sdk_glasses_disconnected")
+        XCTAssertEqual(disconnected.properties["session_duration_ms"] as? Int64, 60000)
+        XCTAssertEqual(disconnected.properties["disconnect_reason"] as? String, "user_disconnect")
+        XCTAssertEqual(disconnected.properties["battery_level_at_connect"] as? Int, 80)
+        XCTAssertEqual(disconnected.properties["battery_level_at_disconnect"] as? Int, 71)
+        XCTAssertEqual(disconnected.properties["charging"] as? Bool, true)
+        XCTAssertEqual(disconnected.properties["glasses_model"] as? String, "Mentra Live")
+
+        // Further disconnected updates do not report the connection again.
+        XCTAssertTrue(tracker.observe(snapshot(connected: false), reportingDay: 100, nowMs: 62000).isEmpty)
+    }
+
+    func testConnectionAlreadyUpWhenTheSdkStartedIsNotReportedAsEnding() {
+        tracker.initialize(snapshot(connected: true, serial: "MLAB0001"), reportingDay: 100)
+        XCTAssertTrue(tracker.observe(snapshot(connected: false), reportingDay: 100, nowMs: 5000).isEmpty)
+    }
+
+    func testBatteryFromAPreviousConnectionDoesNotLeakIntoTheNextOne() throws {
+        tracker.initialize(snapshot(connected: false), reportingDay: 100)
+        _ = tracker.observe(snapshot(connected: true, battery: 90), reportingDay: 100, nowMs: 0)
+        _ = tracker.observe(snapshot(connected: false), reportingDay: 100, nowMs: 1000)
+        _ = tracker.observe(snapshot(connected: true), reportingDay: 100, nowMs: 2000)
+        let ended = tracker.observe(snapshot(connected: false), reportingDay: 100, nowMs: 3000)
+        XCTAssertEqual(ended.count, 1)
+        let second = try XCTUnwrap(ended.first)
+        XCTAssertNil(second.properties["battery_level_at_connect"])
+        XCTAssertNil(second.properties["battery_level_at_disconnect"])
+        XCTAssertNil(second.properties["charging"])
+        XCTAssertEqual(second.properties["disconnect_reason"] as? String, "unknown")
     }
 
     func testConnectThenSerialEmitsEachOncePerConnection() {
@@ -40,7 +91,7 @@ final class BluetoothSdkAnalyticsTrackerTests: XCTestCase {
         tracker.initialize(snapshot(connected: false), reportingDay: 100)
         _ = tracker.observe(snapshot(connected: true, model: ""), reportingDay: 100)
         let ended = tracker.observe(snapshot(connected: false, model: ""), reportingDay: 100)
-        XCTAssertEqual(ended.map(\.name), ["bluetooth_sdk_glasses_connected"])
+        XCTAssertEqual(ended.map(\.name), ["bluetooth_sdk_glasses_connected", "bluetooth_sdk_glasses_disconnected"])
         XCTAssertEqual(ended[0].properties["glasses_model_unresolved"] as? Bool, true)
         XCTAssertNil(ended[0].properties["glasses_model"])
     }

package/ios/Tests/BluetoothSdkUpdateCheckTests.swift

@@ -0,0 +1,153 @@
+@testable import MentraBluetoothSDK
+import XCTest
+
+final class BluetoothSdkUpdateCheckTests: XCTestCase {
+    /// Collects values handed to `@Sendable` callbacks from the check's queue.
+    private final class Recorder<Value>: @unchecked Sendable {
+        private let lock = NSLock()
+        private var stored: [Value] = []
+
+        var values: [Value] {
+            lock.lock()
+            defer { lock.unlock() }
+            return stored
+        }
+
+        func append(_ value: Value) {
+            lock.lock()
+            stored.append(value)
+            lock.unlock()
+        }
+    }
+
+    private final class CheckBox: @unchecked Sendable {
+        var check: BluetoothSdkUpdateCheck?
+    }
+
+    private func result(
+        _ status: String,
+        latest: String? = "3.2.1",
+        minimum: String? = nil
+    ) -> BluetoothSdkUpdateCheckResult {
+        BluetoothSdkUpdateCheckResult(status: status, channel: "latest", latestVersion: latest, minimumSupportedVersion: minimum)
+    }
+
+    func testParsesTheCoreResponseTreatingNullAndBlankVersionsAsUnknown() {
+        let parsed = BluetoothSdkUpdateCheckResult.parse(
+            #"{"status":"update_available","channel":"dev","latestVersion":"3.3.0-dev.821","minimumSupportedVersion":null}"#
+        )
+        XCTAssertEqual(
+            parsed,
+            BluetoothSdkUpdateCheckResult(status: "update_available", channel: "dev", latestVersion: "3.3.0-dev.821", minimumSupportedVersion: nil)
+        )
+        XCTAssertNil(BluetoothSdkUpdateCheckResult.parse(#"{"status":"current","latestVersion":""}"#)?.latestVersion)
+        XCTAssertNotNil(BluetoothSdkUpdateCheckResult.parse(#"{"status":"current","latestVersion":""}"#))
+        XCTAssertNil(BluetoothSdkUpdateCheckResult.parse("<html>502</html>"))
+    }
+
+    func testBannerNamesInstalledAndLatestVersionsAndTheSurfaceUpdateCommand() throws {
+        let reactNative = try XCTUnwrap(BluetoothSdkUpdateNotice.banner(installedVersion: "3.1.0", result: result("update_available"), surface: "react_native"))
+        XCTAssertTrue(reactNative.contains("MENTRA BLUETOOTH SDK UPDATE AVAILABLE"))
+        XCTAssertTrue(reactNative.contains("Installed: 3.1.0"))
+        XCTAssertTrue(reactNative.contains("Latest: 3.2.1"))
+        XCTAssertTrue(reactNative.contains("bun add @mentra/bluetooth-sdk@3.2.1"))
+        XCTAssertFalse(reactNative.contains("NO LONGER SUPPORTED"))
+        XCTAssertTrue(reactNative.hasPrefix("=================================================================="))
+        XCTAssertTrue(reactNative.hasSuffix("=================================================================="))
+
+        let ios = try XCTUnwrap(BluetoothSdkUpdateNotice.banner(installedVersion: "3.1.0", result: result("update_available"), surface: "ios"))
+        XCTAssertTrue(ios.contains("MentraBluetoothSDK Swift package at 3.2.1"))
+        let android = try XCTUnwrap(BluetoothSdkUpdateNotice.banner(installedVersion: "3.1.0", result: result("update_available"), surface: "android"))
+        XCTAssertTrue(android.contains("com.mentraglass:bluetooth-sdk:3.2.1"))
+    }
+
+    func testUnsupportedVersionGetsTheStrongerBanner() throws {
+        let banner = try XCTUnwrap(BluetoothSdkUpdateNotice.banner(
+            installedVersion: "3.0.5",
+            result: result("unsupported", minimum: "3.1.0"),
+            surface: "ios"
+        ))
+        XCTAssertTrue(banner.contains("MENTRA BLUETOOTH SDK 3.0.5 IS NO LONGER SUPPORTED"))
+        XCTAssertTrue(banner.contains("known issues"))
+    }
+
+    func testNoBannerWhenCurrentUnknownOrNoLatestVersionToPointAt() {
+        XCTAssertNil(BluetoothSdkUpdateNotice.banner(installedVersion: "3.2.1", result: result("current"), surface: "ios"))
+        XCTAssertNil(BluetoothSdkUpdateNotice.banner(installedVersion: "3.2.1", result: result("unknown", latest: nil), surface: "ios"))
+        XCTAssertNil(BluetoothSdkUpdateNotice.banner(installedVersion: "3.2.1", result: result("update_available", latest: nil), surface: "ios"))
+    }
+
+    func testSurfaceFollowsTheIntegration() {
+        XCTAssertEqual(BluetoothSdkUpdateCheck.surface(forAnalyticsSurface: "react_native"), "react_native")
+        XCTAssertEqual(BluetoothSdkUpdateCheck.surface(forAnalyticsSurface: "ios"), "ios")
+        XCTAssertEqual(BluetoothSdkUpdateCheck.surface(forAnalyticsSurface: "macos"), "ios")
+    }
+
+    func testRequestIdentifiesTheInstallAppAndSdk() throws {
+        let check = BluetoothSdkUpdateCheck(surface: "react_native", sdkVersion: "3.1.0", transport: { _, completion in completion(nil) }) { _, _ in }
+        let body = check.requestBody()
+        let installId = try XCTUnwrap(body["install_id"] as? String)
+        XCTAssertEqual(installId, BluetoothSdkInstallId.get())
+        XCTAssertTrue(installId.hasPrefix("mentra-bt-sdk-"))
+        XCTAssertEqual(body["app_identifier"] as? String, Bundle.main.bundleIdentifier ?? "")
+        XCTAssertEqual(body["sdk_version"] as? String, "3.1.0")
+        XCTAssertEqual(body["sdk_platform"] as? String, "ios")
+        XCTAssertEqual(body["sdk_surface"] as? String, "react_native")
+        XCTAssertNotNil(body["app_build_type"])
+        XCTAssertNotNil(body["app_install_source"])
+        XCTAssertTrue(JSONSerialization.isValidJSONObject(body))
+    }
+
+    func testOutOfDateSdkPrintsTheBannerOnceAtStartAndStopsOnClose() throws {
+        let notices = Recorder<String>()
+        let sentBodies = Recorder<Data>()
+        let check = BluetoothSdkUpdateCheck(
+            surface: "ios",
+            sdkVersion: "3.1.0",
+            transport: { body, completion in
+                sentBodies.append(body)
+                completion(Data(#"{"status":"update_available","channel":"latest","latestVersion":"3.2.1","minimumSupportedVersion":null}"#.utf8))
+            }
+        ) { banner, _ in notices.append(banner) }
+        check.start()
+        BluetoothSdkUpdateCheck.awaitIdle()
+        XCTAssertEqual(notices.values.count, 1)
+        XCTAssertTrue(notices.values.first?.contains("Latest: 3.2.1") == true)
+        let sentBody = try XCTUnwrap(sentBodies.values.first)
+        let sent = try XCTUnwrap(JSONSerialization.jsonObject(with: sentBody) as? [String: Any])
+        XCTAssertEqual(sent["sdk_version"] as? String, "3.1.0")
+        check.stop()
+    }
+
+    func testFailuresAndUnknownVersionsAreSilent() {
+        let notices = Recorder<String>()
+        let calls = Recorder<Bool>()
+        let checks = [
+            BluetoothSdkUpdateCheck(surface: "ios", sdkVersion: "3.1.0", transport: { _, completion in completion(nil) }) { banner, _ in notices.append(banner) },
+            BluetoothSdkUpdateCheck(surface: "ios", sdkVersion: "3.1.0", transport: { _, completion in completion(Data("<html>502</html>".utf8)) }) { banner, _ in notices.append(banner) },
+            BluetoothSdkUpdateCheck(surface: "ios", sdkVersion: "unknown", transport: { _, completion in calls.append(true); completion(nil) }) { banner, _ in notices.append(banner) },
+            BluetoothSdkUpdateCheck(surface: "ios", sdkVersion: nil, transport: { _, completion in calls.append(true); completion(nil) }) { banner, _ in notices.append(banner) },
+        ]
+        checks.forEach { $0.start() }
+        BluetoothSdkUpdateCheck.awaitIdle()
+        XCTAssertTrue(notices.values.isEmpty)
+        XCTAssertTrue(calls.values.isEmpty)
+    }
+
+    func testCheckStoppedBeforeTheResponseArrivesPrintsNothing() {
+        let notices = Recorder<String>()
+        let box = CheckBox()
+        let check = BluetoothSdkUpdateCheck(
+            surface: "ios",
+            sdkVersion: "3.1.0",
+            transport: { _, completion in
+                box.check?.stop()
+                completion(Data(#"{"status":"update_available","latestVersion":"3.2.1"}"#.utf8))
+            }
+        ) { banner, _ in notices.append(banner) }
+        box.check = check
+        check.start()
+        BluetoothSdkUpdateCheck.awaitIdle()
+        XCTAssertTrue(notices.values.isEmpty)
+    }
+}