@mentra/bluetooth-sdk 3.2.0-dev.209 → 3.2.0-dev.210

package/build/generated/changelogCatalog.js.map

@@ -1 +1 @@
-{"version":3,"file":"changelogCatalog.js","sourceRoot":"","sources":["../../src/generated/changelogCatalog.ts"],"names":[],"mappings":"AAAA,wDAAwD;AACxD,MAAM,CAAC,MAAM,4BAA4B,GAAG,MAAM,CAAC,MAAM,CACzD;IACE;QACE,SAAS,EAAE,OAAO;QAClB,UAAU,EAAE,maAAma;KAChb;IACD;QACE,SAAS,EAAE,OAAO;QAClB,UAAU,EAAE,+cAA+c;KAC5d;CACO,CACT,CAAA","sourcesContent":["/** Generated from /changelogs. Do not edit directly. */\nexport const GENERATED_RELEASE_CHANGELOGS = Object.freeze(\n[\n  {\n    \"version\": \"3.2.0\",\n    \"markdown\": \"This release is under active development. User-facing changes will be documented as they land.\\n\\n- Breaking Bluetooth SDK change: `forgetWifiNetwork(ssid)` now returns `WifiForgetResult` instead of `WifiStatusChangeEvent`. Migrate status-only consumers to the semantic `outcome`; the requested network remains `ssid`, while optional post-command connectivity is reported by `connected`, `currentSsid`, and `localIp`.\"\n  },\n  {\n    \"version\": \"3.1.0\",\n    \"markdown\": \"Software updates are more reliable, with clearer progress and recovery when the glasses restart.\\n\\n- MentraOS, Mentra Engine, the Bluetooth SDK, and the glasses client now share one coordinated release version.\\n- Mentra Live updates can continue across APK, system, and firmware restarts without asking the user to start the same update again.\\n- Bluetooth photo capture and transfer diagnostics are more precise and less disruptive to normal glasses traffic.\"\n  }\n] as const,\n)\n"]}
+{"version":3,"file":"changelogCatalog.js","sourceRoot":"","sources":["../../src/generated/changelogCatalog.ts"],"names":[],"mappings":"AAAA,wDAAwD;AACxD,MAAM,CAAC,MAAM,4BAA4B,GAAG,MAAM,CAAC,MAAM,CACzD;IACE;QACE,SAAS,EAAE,OAAO;QAClB,UAAU,EAAE,maAAma;KAChb;IACD;QACE,SAAS,EAAE,OAAO;QAClB,UAAU,EAAE,u4BAAu4B;KACp5B;CACO,CACT,CAAA","sourcesContent":["/** Generated from /changelogs. Do not edit directly. */\nexport const GENERATED_RELEASE_CHANGELOGS = Object.freeze(\n[\n  {\n    \"version\": \"3.2.0\",\n    \"markdown\": \"This release is under active development. User-facing changes will be documented as they land.\\n\\n- Breaking Bluetooth SDK change: `forgetWifiNetwork(ssid)` now returns `WifiForgetResult` instead of `WifiStatusChangeEvent`. Migrate status-only consumers to the semantic `outcome`; the requested network remains `ssid`, while optional post-command connectivity is reported by `connected`, `currentSsid`, and `localIp`.\"\n  },\n  {\n    \"version\": \"3.1.0\",\n    \"markdown\": \"Software updates are more reliable, with clearer progress and recovery when the glasses restart.\\n\\n- MentraOS, Mentra Engine, the Bluetooth SDK, and the glasses client now share one coordinated release version.\\n- Mentra Live updates can continue across APK, system, and firmware restarts without asking the user to start the same update again.\\n- Bluetooth photo capture and transfer diagnostics are more precise and less disruptive to normal glasses traffic.\\n- Bluetooth SDK usage analytics now report the host app's version, build type, and install source (store, TestFlight, sideload, simulator), plus the glasses firmware versions on identification, so store usage can be measured separately from development builds.\\n- Bluetooth SDK usage analytics now identify G2 glasses by serial, keep long-lived connections visible across day boundaries, and retry failed uploads instead of dropping them.\"\n  }\n] as const,\n)\n"]}

package/build/generated/releaseMetadata.js

@@ -1,10 +1,10 @@
 export const BLUETOOTH_SDK_RELEASE_METADATA = Object.freeze({
     "schemaVersion": 1,
     "familyBaseVersion": "3.2.0",
-    "releaseIdentity": "3.2.0-dev.209",
-    "releaseSetId": "mentra-3.2.0-dev.209",
-    "sourceCommit": "b1606374e1508f0993d1a7e391fddeb4f8fac5bd",
-    "otaManifestUrl": "https://github.com/Mentra-Community/MentraOS/releases/download/mentra-builds-v3.2.0/mentra-live-ota-3.2.0-dev.209.json",
-    "otaManifestSha256": "de5936b765f7deb07a1fd448bb4e9c00f36e1b1313d16c021aff843cf801b489"
+    "releaseIdentity": "3.2.0-dev.210",
+    "releaseSetId": "mentra-3.2.0-dev.210",
+    "sourceCommit": "259fb93fd2ecae4ed7bf280fe3b4e2b2cc594611",
+    "otaManifestUrl": "https://github.com/Mentra-Community/MentraOS/releases/download/mentra-builds-v3.2.0/mentra-live-ota-3.2.0-dev.210.json",
+    "otaManifestSha256": "7d8fb1f69ca9a0a6b9d00f87a60694e74aa5377776d1818a7b982b09d9bb65dc"
 });
 //# sourceMappingURL=releaseMetadata.js.map

package/build/generated/releaseMetadata.js.map

@@ -1 +1 @@
-{"version":3,"file":"releaseMetadata.js","sourceRoot":"","sources":["../../src/generated/releaseMetadata.ts"],"names":[],"mappings":"AAWA,MAAM,CAAC,MAAM,8BAA8B,GAA0C,MAAM,CAAC,MAAM,CAAC;IACjG,eAAe,EAAE,CAAC;IAClB,mBAAmB,EAAE,OAAO;IAC5B,iBAAiB,EAAE,eAAe;IAClC,cAAc,EAAE,sBAAsB;IACtC,cAAc,EAAE,0CAA0C;IAC1D,gBAAgB,EAAE,wHAAwH;IAC1I,mBAAmB,EAAE,kEAAkE;CACxF,CAAC,CAAA","sourcesContent":["/** Generated by release CI. Do not edit in a release checkout. */\nexport interface BluetoothSdkReleaseMetadata {\n  schemaVersion: 1\n  familyBaseVersion: string | null\n  releaseIdentity: string | null\n  releaseSetId: string | null\n  sourceCommit: string | null\n  otaManifestUrl: string | null\n  otaManifestSha256: string | null\n}\n\nexport const BLUETOOTH_SDK_RELEASE_METADATA: Readonly<BluetoothSdkReleaseMetadata> = Object.freeze({\n  \"schemaVersion\": 1,\n  \"familyBaseVersion\": \"3.2.0\",\n  \"releaseIdentity\": \"3.2.0-dev.209\",\n  \"releaseSetId\": \"mentra-3.2.0-dev.209\",\n  \"sourceCommit\": \"b1606374e1508f0993d1a7e391fddeb4f8fac5bd\",\n  \"otaManifestUrl\": \"https://github.com/Mentra-Community/MentraOS/releases/download/mentra-builds-v3.2.0/mentra-live-ota-3.2.0-dev.209.json\",\n  \"otaManifestSha256\": \"de5936b765f7deb07a1fd448bb4e9c00f36e1b1313d16c021aff843cf801b489\"\n})\n"]}
+{"version":3,"file":"releaseMetadata.js","sourceRoot":"","sources":["../../src/generated/releaseMetadata.ts"],"names":[],"mappings":"AAWA,MAAM,CAAC,MAAM,8BAA8B,GAA0C,MAAM,CAAC,MAAM,CAAC;IACjG,eAAe,EAAE,CAAC;IAClB,mBAAmB,EAAE,OAAO;IAC5B,iBAAiB,EAAE,eAAe;IAClC,cAAc,EAAE,sBAAsB;IACtC,cAAc,EAAE,0CAA0C;IAC1D,gBAAgB,EAAE,wHAAwH;IAC1I,mBAAmB,EAAE,kEAAkE;CACxF,CAAC,CAAA","sourcesContent":["/** Generated by release CI. Do not edit in a release checkout. */\nexport interface BluetoothSdkReleaseMetadata {\n  schemaVersion: 1\n  familyBaseVersion: string | null\n  releaseIdentity: string | null\n  releaseSetId: string | null\n  sourceCommit: string | null\n  otaManifestUrl: string | null\n  otaManifestSha256: string | null\n}\n\nexport const BLUETOOTH_SDK_RELEASE_METADATA: Readonly<BluetoothSdkReleaseMetadata> = Object.freeze({\n  \"schemaVersion\": 1,\n  \"familyBaseVersion\": \"3.2.0\",\n  \"releaseIdentity\": \"3.2.0-dev.210\",\n  \"releaseSetId\": \"mentra-3.2.0-dev.210\",\n  \"sourceCommit\": \"259fb93fd2ecae4ed7bf280fe3b4e2b2cc594611\",\n  \"otaManifestUrl\": \"https://github.com/Mentra-Community/MentraOS/releases/download/mentra-builds-v3.2.0/mentra-live-ota-3.2.0-dev.210.json\",\n  \"otaManifestSha256\": \"7d8fb1f69ca9a0a6b9d00f87a60694e74aa5377776d1818a7b982b09d9bb65dc\"\n})\n"]}

package/ios/Source/BluetoothSdkDefaults.swift

@@ -11,7 +11,7 @@ enum BluetoothSdkDefaults {
     static let voiceActivityDetectionEnabled = false
     static let loudnessGateEnabled = false
     private static let infoSdkVersionKey = "MentraBluetoothSdkVersion"
-    private static let swiftPackageSdkVersion = "3.2.0-dev.209"
+    private static let swiftPackageSdkVersion = "3.2.0-dev.210"
     private static let swiftPackageSdkVersionPlaceholder = "__MENTRA" + "_BLUETOOTH_SDK_VERSION__"
 
     private static func normalizedSdkVersion(_ value: String?) -> String? {

package/ios/Source/GeneratedChangelogCatalog.swift

@@ -3,5 +3,5 @@ import Foundation
 /// Generated from /changelogs. Do not edit directly.
 let generatedReleaseChangelogs: [ReleaseChangelog] = [
     ReleaseChangelog(version: "3.2.0", markdown: "This release is under active development. User-facing changes will be documented as they land.\n\n- Breaking Bluetooth SDK change: `forgetWifiNetwork(ssid)` now returns `WifiForgetResult` instead of `WifiStatusChangeEvent`. Migrate status-only consumers to the semantic `outcome`; the requested network remains `ssid`, while optional post-command connectivity is reported by `connected`, `currentSsid`, and `localIp`."),
-    ReleaseChangelog(version: "3.1.0", markdown: "Software updates are more reliable, with clearer progress and recovery when the glasses restart.\n\n- MentraOS, Mentra Engine, the Bluetooth SDK, and the glasses client now share one coordinated release version.\n- Mentra Live updates can continue across APK, system, and firmware restarts without asking the user to start the same update again.\n- Bluetooth photo capture and transfer diagnostics are more precise and less disruptive to normal glasses traffic."),
+    ReleaseChangelog(version: "3.1.0", markdown: "Software updates are more reliable, with clearer progress and recovery when the glasses restart.\n\n- MentraOS, Mentra Engine, the Bluetooth SDK, and the glasses client now share one coordinated release version.\n- Mentra Live updates can continue across APK, system, and firmware restarts without asking the user to start the same update again.\n- Bluetooth photo capture and transfer diagnostics are more precise and less disruptive to normal glasses traffic.\n- Bluetooth SDK usage analytics now report the host app's version, build type, and install source (store, TestFlight, sideload, simulator), plus the glasses firmware versions on identification, so store usage can be measured separately from development builds.\n- Bluetooth SDK usage analytics now identify G2 glasses by serial, keep long-lived connections visible across day boundaries, and retry failed uploads instead of dropping them."),
 ]

package/ios/Source/GeneratedReleaseMetadata.swift

@@ -3,9 +3,9 @@ import Foundation
 /// Generated by release CI. Do not edit in a release checkout.
 enum GeneratedReleaseMetadata {
     static let familyBaseVersion = "3.2.0"
-    static let releaseIdentity = "3.2.0-dev.209"
-    static let releaseSetId = "mentra-3.2.0-dev.209"
-    static let sourceCommit = "b1606374e1508f0993d1a7e391fddeb4f8fac5bd"
-    static let otaManifestUrl = "https://github.com/Mentra-Community/MentraOS/releases/download/mentra-builds-v3.2.0/mentra-live-ota-3.2.0-dev.209.json"
-    static let otaManifestSha256 = "de5936b765f7deb07a1fd448bb4e9c00f36e1b1313d16c021aff843cf801b489"
+    static let releaseIdentity = "3.2.0-dev.210"
+    static let releaseSetId = "mentra-3.2.0-dev.210"
+    static let sourceCommit = "259fb93fd2ecae4ed7bf280fe3b4e2b2cc594611"
+    static let otaManifestUrl = "https://github.com/Mentra-Community/MentraOS/releases/download/mentra-builds-v3.2.0/mentra-live-ota-3.2.0-dev.210.json"
+    static let otaManifestSha256 = "7d8fb1f69ca9a0a6b9d00f87a60694e74aa5377776d1818a7b982b09d9bb65dc"
 }

package/ios/Source/internal/BluetoothSdkAnalytics.swift

@@ -39,11 +39,22 @@ final class BluetoothSdkAnalytics {
     private static let defaultPostHogApiKey = "phc_FCweXVAxVgU7wZK4Fk3okOx4RmyNqVHJf62YpZSfJt5"
     private static let defaultPostHogHost = "https://us.i.posthog.com"
     private let stateQueue = DispatchQueue(label: "com.mentra.bluetoothsdk.analytics.state")
-    private let transportQueue = DispatchQueue(label: "com.mentra.bluetoothsdk.analytics.transport")
+    // Delivery is process-wide (see BluetoothSdkAnalyticsTransport); this instance only tracks its connection.
+    private let transportQueue = BluetoothSdkAnalyticsTransport.queue
     private let configuration: BluetoothSdkAnalyticsConfiguration
+    private var tracker = BluetoothSdkAnalyticsTracker(simulatedModel: DeviceTypes.SIMULATED)
     private var startedCaptured = false
-    private var lastConnected = false
-    private var identifiedCapturedForConnection = false
+    // Touched only on transportQueue, which serializes access.
+    private var resolvedHostProperties: [String: Any]?
+    private var retryQueue: BluetoothSdkAnalyticsQueue? {
+        BluetoothSdkAnalyticsTransport.retryQueue
+    }
+
+    private let isoFormatter: ISO8601DateFormatter = {
+        let formatter = ISO8601DateFormatter()
+        formatter.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
+        return formatter
+    }()
 
     init(configuration: BluetoothSdkAnalyticsConfiguration) {
         self.configuration = configuration.resolvedForApp()
@@ -51,71 +62,27 @@ final class BluetoothSdkAnalytics {
 
     func initializeGlassesStatus(_ status: GlassesStatus) {
         stateQueue.sync {
-            lastConnected = status.analyticsConnected
-            // Only treat identification as already captured when a valid serial is
-            // present at init. If the glasses are connected but the serial has not
-            // arrived yet (Mentra Live fills it via version_info after connect), leave
-            // this false so the identify event still fires once the serial arrives.
-            identifiedCapturedForConnection =
-                status.analyticsConnected && status.serialNumber.validManufacturingSerial != nil
+            tracker.initialize(status.analyticsSnapshot, reportingDay: BluetoothSdkAnalyticsTracker.reportingDay())
         }
     }
 
     func captureStarted() {
         stateQueue.sync {
-            captureStartedLocked()
+            guard !startedCaptured, configuration.isReady else { return }
+            startedCaptured = true
+            capture(event: "bluetooth_sdk_started", properties: ["event_kind": "sdk_started"], configuration: configuration)
+            // A fresh runtime is the natural moment to retry what an earlier one could not deliver.
+            transportQueue.async { self.drainRetryQueue(now: Date()) }
         }
     }
 
-    private func captureStartedLocked() {
-        guard !startedCaptured, configuration.isReady else { return }
-        startedCaptured = true
-        capture(
-            event: "bluetooth_sdk_started",
-            properties: ["event_kind": "sdk_started"],
-            configuration: configuration
-        )
-    }
-
     func observeGlassesStatus(_ status: GlassesStatus) {
         stateQueue.sync {
-            let isConnected = status.analyticsConnected
-            let wasConnected = lastConnected
-            lastConnected = isConnected
+            let events = tracker.observe(status.analyticsSnapshot, reportingDay: BluetoothSdkAnalyticsTracker.reportingDay())
             guard configuration.isReady else { return }
-            guard isConnected else {
-                identifiedCapturedForConnection = false
-                return
-            }
-            if isConnected, !wasConnected {
-                identifiedCapturedForConnection = false
-                var properties: [String: Any] = [
-                    "event_kind": "glasses_connected",
-                    "fully_booted": status.fullyBooted,
-                ]
-                if !status.deviceModel.isEmpty {
-                    properties["glasses_model"] = status.deviceModel
-                }
-                capture(event: "bluetooth_sdk_glasses_connected", properties: properties, configuration: configuration)
-                // Fall through: a serial already present at connect time (G1/Ar99
-                // report it in the advertisement) should be identified now rather than
-                // waiting for some later, unrelated glasses-store update to run.
+            for event in events {
+                capture(event: event.name, properties: event.properties, configuration: configuration)
             }
-
-            guard !identifiedCapturedForConnection,
-                  let serialNumber = status.serialNumber.validManufacturingSerial
-            else { return }
-            identifiedCapturedForConnection = true
-            var properties: [String: Any] = [
-                "event_kind": "glasses_identified",
-                "fully_booted": status.fullyBooted,
-                "glasses_device_id": serialNumber,
-                "glasses_device_id_type": "manufacturing_serial",
-            ]
-            if !status.deviceModel.isEmpty {
-                properties["glasses_model"] = status.deviceModel
-            }
-            capture(event: "bluetooth_sdk_glasses_identified", properties: properties, configuration: configuration)
         }
     }
 
@@ -125,25 +92,72 @@ final class BluetoothSdkAnalytics {
         configuration activeConfiguration: BluetoothSdkAnalyticsConfiguration
     ) {
         guard activeConfiguration.isReady else { return }
+        // Identity and time are fixed at capture, not at (re)send, so a retried
+        // event neither double counts nor drifts into a later week.
+        let uuid = UUID().uuidString.lowercased()
+        let capturedAt = Date()
 
         transportQueue.async {
+            // Host facts are resolved once, on the transport queue: Bundle lookups
+            // must not run on the caller (often the Bluetooth status thread).
+            let host = self.transportQueueHostProperties()
             let payload: [String: Any] = [
                 "api_key": Self.defaultPostHogApiKey,
+                "uuid": uuid,
                 "event": event,
                 "distinct_id": self.distinctId(),
-                "properties": self.baseProperties(configuration: activeConfiguration).merging(properties) { _, new in new },
+                "timestamp": self.isoFormatter.string(from: capturedAt),
+                "properties": self.baseProperties(configuration: activeConfiguration)
+                    .merging(host) { _, new in new }
+                    .merging(properties) { _, new in new },
             ]
-            guard let body = try? JSONSerialization.data(withJSONObject: payload) else { return }
-            guard let captureURL = self.captureURL() else { return }
-            var request = URLRequest(url: captureURL)
-            request.httpMethod = "POST"
-            request.timeoutInterval = 4
-            request.setValue("application/json", forHTTPHeaderField: "Content-Type")
-            request.httpBody = body
-            URLSession.shared.dataTask(with: request).resume()
+            switch self.send(payload) {
+            case .delivered: self.drainRetryQueue(now: capturedAt)
+            case .retry: self.retryQueue?.enqueue(payload, now: capturedAt)
+            case .discard: break
+            }
         }
     }
 
+    /// Only ever called from `transportQueue`.
+    private func drainRetryQueue(now: Date) {
+        retryQueue?.drain(now: now) { payload in self.send(payload) }
+    }
+
+    /// Synchronous on purpose: it runs on the transport queue, and one request in
+    /// flight at a time keeps retry ordering trivial. The completion handler owns the
+    /// outcome; if it has not fired by the deadline the task is cancelled and the
+    /// payload is treated as retryable (its uuid makes a late duplicate harmless).
+    private func send(_ payload: [String: Any]) -> SendOutcome {
+        guard JSONSerialization.isValidJSONObject(payload),
+              let body = try? JSONSerialization.data(withJSONObject: payload),
+              let captureURL = captureURL()
+        else { return .discard }
+        var request = URLRequest(url: captureURL)
+        request.httpMethod = "POST"
+        request.timeoutInterval = 4
+        request.setValue("application/json", forHTTPHeaderField: "Content-Type")
+        request.httpBody = body
+
+        let result = SendResult()
+        let task = URLSession.shared.dataTask(with: request) { _, response, error in
+            let outcome: SendOutcome
+            if error != nil {
+                outcome = .retry
+            } else if let http = response as? HTTPURLResponse {
+                outcome = SendOutcome.fromHTTPStatus(http.statusCode)
+            } else {
+                outcome = .retry
+            }
+            result.complete(outcome)
+        }
+        task.resume()
+        if result.wait(timeout: .now() + 6) == .timedOut {
+            task.cancel()
+        }
+        return result.outcome
+    }
+
     private func baseProperties(configuration: BluetoothSdkAnalyticsConfiguration) -> [String: Any] {
         #if os(macOS)
         let platform = "macos"
@@ -160,12 +174,20 @@ final class BluetoothSdkAnalytics {
             "os_platform": platform,
             "os_version": ProcessInfo.processInfo.operatingSystemVersionString,
         ]
-        if let sdkVersion = BluetoothSdkDefaults.sdkVersion {
-            properties["sdk_version"] = sdkVersion
-        }
+        // Always present so version cohorts never collapse into a null bucket. The
+        // placeholder shows up only for unstamped source builds (plain SwiftPM checkout).
+        properties["sdk_version"] = BluetoothSdkDefaults.sdkVersion ?? "unknown"
         return properties
     }
 
+    /// Only ever called from `transportQueue`, which serializes access.
+    private func transportQueueHostProperties() -> [String: Any] {
+        if let resolvedHostProperties { return resolvedHostProperties }
+        let resolved = BluetoothSdkAnalyticsHost.resolve().properties
+        resolvedHostProperties = resolved
+        return resolved
+    }
+
     private func distinctId() -> String {
         let key = "mentra_bluetooth_sdk_analytics_distinct_id"
         if let existing = UserDefaults.standard.string(forKey: key), !existing.isEmpty {
@@ -182,17 +204,46 @@ final class BluetoothSdkAnalytics {
     }
 }
 
-private extension GlassesStatus {
-    var analyticsConnected: Bool {
-        connectionState.isConnected || connected || fullyBooted
+/// Completion-owned send result: the outcome is written once, under a lock, and
+/// read only after the semaphore says it is settled (or after a timeout, in which
+/// case it stays `.retry`).
+private final class SendResult {
+    private let lock = NSLock()
+    private let semaphore = DispatchSemaphore(value: 0)
+    private var settled: SendOutcome = .retry
+
+    var outcome: SendOutcome {
+        lock.lock()
+        defer { lock.unlock() }
+        return settled
+    }
+
+    func complete(_ outcome: SendOutcome) {
+        lock.lock()
+        settled = outcome
+        lock.unlock()
+        semaphore.signal()
+    }
+
+    func wait(timeout: DispatchTime) -> DispatchTimeoutResult {
+        semaphore.wait(timeout: timeout)
     }
 }
 
-private extension String {
-    var validManufacturingSerial: String? {
-        let normalized = trimmingCharacters(in: .whitespacesAndNewlines)
-        guard !normalized.isEmpty, normalized.contains(where: { $0 != "0" }) else { return nil }
-        return normalized
+private extension GlassesStatus {
+    var analyticsSnapshot: AnalyticsGlassesSnapshot {
+        AnalyticsGlassesSnapshot(
+            connected: connectionState.isConnected || connected || fullyBooted,
+            fullyBooted: fullyBooted,
+            model: deviceModel,
+            serialNumber: serialNumber,
+            firmwareVersion: firmwareVersion,
+            besFirmwareVersion: besFirmwareVersion,
+            mtkFirmwareVersion: mtkFirmwareVersion,
+            androidVersion: androidVersion,
+            appVersion: appVersion,
+            buildNumber: buildNumber
+        )
     }
 }
 

package/ios/Source/internal/BluetoothSdkAnalyticsHost.swift

@@ -0,0 +1,91 @@
+import Foundation
+
+/// Host-app facts attached to every analytics event so Mentra can separate
+/// store installs from TestFlight, ad-hoc, development, and simulator builds.
+struct BluetoothSdkAnalyticsHostProperties {
+    let appVersion: String?
+    let appBuild: String?
+    let buildType: String
+    let installSource: String
+    let environment: String?
+
+    var properties: [String: Any] {
+        var values: [String: Any] = [
+            "app_build_type": buildType,
+            "app_install_source": installSource,
+        ]
+        if let appVersion { values["app_version"] = appVersion }
+        if let appBuild { values["app_build"] = appBuild }
+        if let environment { values["app_environment"] = environment }
+        return values
+    }
+}
+
+enum BluetoothSdkAnalyticsHost {
+    /// Optional host-declared lane (`dev`, `staging`, `prod`, ...). Stamped by the
+    /// Expo config plugin's `analytics.environment` option; native apps may set it directly.
+    static let infoEnvironmentKey = "MentraBluetoothSdkAnalyticsEnvironment"
+
+    /// An embedded provisioning profile only exists in development, ad-hoc, and
+    /// enterprise builds, so it is checked before the receipt: TestFlight and App
+    /// Store builds carry no profile, and the receipt file name then tells them
+    /// apart (`sandboxReceipt` vs `receipt`). Missing or unrecognized evidence is
+    /// reported as `unknown` rather than guessed, because this value decides
+    /// whether an install counts as production.
+    static func installSource(
+        isSimulator: Bool,
+        hasEmbeddedProvisioningProfile: Bool,
+        receiptFileName: String?
+    ) -> String {
+        if isSimulator { return "simulator" }
+        if hasEmbeddedProvisioningProfile { return "adhoc_or_dev" }
+        switch receiptFileName {
+        case "sandboxReceipt": return "testflight"
+        case "receipt": return "app_store"
+        default: return "unknown"
+        }
+    }
+
+    static func normalizedEnvironment(_ raw: String?) -> String? {
+        guard let raw else { return nil }
+        let value = raw.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+        guard !value.isEmpty, value.count <= 32 else { return nil }
+        let allowed = CharacterSet(charactersIn: "abcdefghijklmnopqrstuvwxyz0123456789_-")
+        guard value.unicodeScalars.allSatisfy({ allowed.contains($0) }),
+              let first = value.unicodeScalars.first,
+              first != "_", first != "-"
+        else { return nil }
+        return value
+    }
+
+    static func resolve(bundle: Bundle = .main) -> BluetoothSdkAnalyticsHostProperties {
+        #if targetEnvironment(simulator)
+            let isSimulator = true
+        #else
+            let isSimulator = false
+        #endif
+        #if DEBUG
+            let buildType = "debug"
+        #else
+            let buildType = "release"
+        #endif
+        let info = bundle.infoDictionary ?? [:]
+        return BluetoothSdkAnalyticsHostProperties(
+            appVersion: nonBlank(info["CFBundleShortVersionString"] as? String),
+            appBuild: nonBlank(info["CFBundleVersion"] as? String),
+            buildType: buildType,
+            installSource: installSource(
+                isSimulator: isSimulator,
+                hasEmbeddedProvisioningProfile: bundle.path(forResource: "embedded", ofType: "mobileprovision") != nil,
+                receiptFileName: bundle.appStoreReceiptURL?.lastPathComponent
+            ),
+            environment: normalizedEnvironment(info[infoEnvironmentKey] as? String)
+        )
+    }
+
+    private static func nonBlank(_ value: String?) -> String? {
+        guard let value else { return nil }
+        let trimmed = value.trimmingCharacters(in: .whitespacesAndNewlines)
+        return trimmed.isEmpty ? nil : trimmed
+    }
+}

package/ios/Source/internal/BluetoothSdkAnalyticsQueue.swift

@@ -0,0 +1,117 @@
+import Foundation
+
+enum SendOutcome {
+    case delivered
+    case retry
+    case discard
+
+    /// 2xx is delivered. A 4xx other than 408/429 means PostHog rejected this payload
+    /// for good (bad key, malformed body) and retrying it would only block the queue.
+    /// Everything else (5xx, 408, 429) is worth retrying later.
+    static func fromHTTPStatus(_ code: Int) -> SendOutcome {
+        switch code {
+        case 200 ..< 300: return .delivered
+        case 408, 429: return .retry
+        case 400 ..< 500: return .discard
+        default: return .retry
+        }
+    }
+}
+
+/// Bounded on-disk retry queue for analytics payloads whose upload failed.
+/// One JSON object per line. Oldest entries are dropped past `maxEntries`; entries
+/// older than `maxAge` are discarded on drain. Every payload carries its own
+/// `uuid` and `timestamp`, so a retried event neither double counts nor moves in time.
+///
+/// Not thread-safe by itself: callers serialize access on the analytics transport queue.
+final class BluetoothSdkAnalyticsQueue {
+    static let defaultMaxEntries = 100
+    static let defaultMaxAge: TimeInterval = 7 * 24 * 60 * 60
+    static let fileName = "mentra_bluetooth_sdk_analytics_queue.jsonl"
+
+    static func defaultFileURL(fileManager: FileManager = .default) -> URL? {
+        guard let base = fileManager.urls(for: .applicationSupportDirectory, in: .userDomainMask).first else { return nil }
+        return base.appendingPathComponent("MentraBluetoothSdk", isDirectory: true).appendingPathComponent(fileName)
+    }
+
+    private let fileURL: URL
+    private let maxEntries: Int
+    private let maxAge: TimeInterval
+
+    init(fileURL: URL, maxEntries: Int = BluetoothSdkAnalyticsQueue.defaultMaxEntries, maxAge: TimeInterval = BluetoothSdkAnalyticsQueue.defaultMaxAge) {
+        self.fileURL = fileURL
+        self.maxEntries = maxEntries
+        self.maxAge = maxAge
+    }
+
+    func enqueue(_ payload: [String: Any], now: Date) {
+        var entries = read()
+        entries.append(["enqueued_at": now.timeIntervalSince1970, "payload": payload])
+        while entries.count > maxEntries {
+            entries.removeFirst()
+        }
+        write(entries)
+    }
+
+    var count: Int {
+        read().count
+    }
+
+    /// Sends queued payloads oldest-first through `send`. Delivered and permanently
+    /// rejected entries are dropped; the first retryable failure stops the drain so
+    /// ordering is preserved and a dead network does not burn through every entry.
+    func drain(now: Date, send: ([String: Any]) -> SendOutcome) {
+        let entries = read()
+        guard !entries.isEmpty else { return }
+        var remaining: [[String: Any]] = []
+        var blocked = false
+        for entry in entries {
+            let enqueuedAt = (entry["enqueued_at"] as? TimeInterval) ?? now.timeIntervalSince1970
+            if now.timeIntervalSince1970 - enqueuedAt > maxAge { continue }
+            guard let payload = entry["payload"] as? [String: Any] else { continue }
+            if blocked {
+                remaining.append(entry)
+                continue
+            }
+            if send(payload) == .retry {
+                blocked = true
+                remaining.append(entry)
+            }
+        }
+        write(remaining)
+    }
+
+    private func read() -> [[String: Any]] {
+        guard let data = try? Data(contentsOf: fileURL), let text = String(data: data, encoding: .utf8) else { return [] }
+        return text.split(separator: "\n").compactMap { line in
+            guard !line.trimmingCharacters(in: .whitespaces).isEmpty,
+                  let lineData = line.data(using: .utf8),
+                  let object = try? JSONSerialization.jsonObject(with: lineData) as? [String: Any]
+            else { return nil }
+            return object
+        }
+    }
+
+    private func write(_ entries: [[String: Any]]) {
+        let fileManager = FileManager.default
+        if entries.isEmpty {
+            try? fileManager.removeItem(at: fileURL)
+            return
+        }
+        do {
+            try fileManager.createDirectory(at: fileURL.deletingLastPathComponent(), withIntermediateDirectories: true)
+            var lines: [String] = []
+            for entry in entries {
+                guard JSONSerialization.isValidJSONObject(entry),
+                      let data = try? JSONSerialization.data(withJSONObject: entry),
+                      let line = String(data: data, encoding: .utf8)
+                else { continue }
+                lines.append(line)
+            }
+            let text = lines.joined(separator: "\n") + "\n"
+            try text.data(using: .utf8)?.write(to: fileURL, options: .atomic)
+        } catch {
+            // A queue write failure only loses retries, never live behavior.
+        }
+    }
+}