@mentra/bluetooth-sdk 3.1.0-dev.7 → 3.1.0-dev.71

package/ios/Source/sgcs/MentraLive.swift

@@ -25,6 +25,35 @@ struct MentraLiveDevice {
     let address: String
 }
 
+enum MentraLivePendingPairingTarget {
+    static func matches(
+        connectedName: String,
+        connectedIdentifier: String,
+        pendingName: String,
+        pendingIdentifier: String
+    ) -> Bool {
+        if !pendingIdentifier.isEmpty {
+            return connectedIdentifier.caseInsensitiveCompare(pendingIdentifier) == .orderedSame
+        }
+        return !pendingName.isEmpty && connectedName == pendingName
+    }
+
+    static func shouldRecover(
+        isConnected: Bool,
+        connectedName: String,
+        connectedIdentifier: String,
+        pendingName: String,
+        pendingIdentifier: String
+    ) -> Bool {
+        isConnected && matches(
+            connectedName: connectedName,
+            connectedIdentifier: connectedIdentifier,
+            pendingName: pendingName,
+            pendingIdentifier: pendingIdentifier
+        )
+    }
+}
+
 // MARK: - BlePhotoUploadService
 
 class BlePhotoUploadService {
@@ -873,9 +902,10 @@ extension MentraLive: CBCentralManagerDelegate {
             if !isReconnectTarget && advertisesPairingFlag(advertisementData)
                 && !isPairingDiscoverable(advertisementData)
             {
-                // Nearby but not pairable: RN uses this for the empty-state hint, not the list.
+                // Keep nearby secure units visible with pairing-mode guidance, while RN blocks
+                // the connection until a pairable advertisement arrives.
                 Bridge.log(
-                    "LIVE: Nearby \(name) is secure firmware not in pairing mode — hiding from scan list"
+                    "LIVE: Nearby \(name) is secure firmware not in pairing mode — exposing as non-pairable"
                 )
                 discoveredPeripherals[name] = peripheral
                 cacheAdvPairing(
@@ -942,11 +972,32 @@ extension MentraLive: CBCentralManagerDelegate {
     nonisolated func centralManager(_: CBCentralManager, didConnect peripheral: CBPeripheral) {
         DispatchQueue.main.async { [weak self] in
             guard let self else { return }
+            let matchesActiveAttempt = self.connectingPeripheral === peripheral
+            guard MentraLiveConnectionAttemptPolicy.shouldAcceptDidConnect(
+                pairingYieldActive: self.pairingYieldActive,
+                matchesActiveAttempt: matchesActiveAttempt
+            ) else {
+                Bridge.log(
+                    "LIVE: Rejecting stale connection callback during pairing yield or after attempt replacement: \(peripheral.identifier)"
+                )
+                self.stopConnectionTimeout()
+                if self.connectingPeripheral === peripheral {
+                    self.connectingPeripheral = nil
+                }
+                if self.connectedPeripheral === peripheral {
+                    self.connectedPeripheral = nil
+                }
+                self.isConnecting = false
+                self.centralManager?.cancelPeripheralConnection(peripheral)
+                return
+            }
             Bridge.log("Connected to GATT server, discovering services...")
 
             self.stopConnectionTimeout()
             self.isConnecting = false
+            self.connectingPeripheral = nil
             self.connectedPeripheral = peripheral
+            self.emitConnectedPendingDeviceForPairingScan()
 
             // Save device name and address for future reconnection
             if let name = peripheral.name {
@@ -1345,56 +1396,17 @@ class MentraLive: NSObject, SGCManager {
     private let BLOCK_AUDIO_DUPLEX = false
     private static let voiceActivityDetectionSwitchType = 8
     private static let loudnessGateSwitchType = 10
-    private let mentraManufacturerId: UInt16 = 0xB822
-    // Payload-relative offset of the pairing flag, matching Android's index into the
-    // company-id-stripped manufacturer data from getManufacturerSpecificData().
-    private let advManufPairingFlagOffset = 5
-    // CoreBluetooth returns manufacturer data with the 2-byte company id prefix still attached,
-    // whereas Android strips it. Skip the prefix so both platforms read the same payload byte.
-    private let advManufCompanyIdLength = 2
-    private let advPairingDiscoverable: UInt8 = 0x01
-
-    // CoreBluetooth returns manufacturer data prefixed with the 2-byte company id
-    // (little-endian) and does NOT filter by company id itself (unlike Android's
-    // getManufacturerSpecificData(companyId)), so every reader of this data must
-    // verify the company id before trusting any flag/trailer byte.
-    private func mentraManufacturerData(_ advertisementData: [String: Any]) -> Data? {
-        guard let manufData = advertisementData[CBAdvertisementDataManufacturerDataKey] as? Data,
-              manufData.count >= advManufCompanyIdLength
-        else {
-            return nil
-        }
-        let companyId = UInt16(manufData[0]) | (UInt16(manufData[1]) << 8)
-        guard companyId == mentraManufacturerId else {
-            return nil
-        }
-        return manufData
-    }
-
-    /// OS-1615 ads append `flag | version | capability | code_lo | code_hi` after the
-    /// connected byte. Field firmware uses the same 0xB822 company id but then writes
-    /// the XOR'd Classic MAC at those offsets. Length alone is not a pairing flag.
-    private func hasSecurePairingTrailer(_ advertisementData: [String: Any]) -> Bool {
-        let flagIndex = advManufCompanyIdLength + advManufPairingFlagOffset
-        let trailerBase = flagIndex + 1
-        guard let manufData = mentraManufacturerData(advertisementData),
-              manufData.count >= trailerBase + 4
-        else {
-            return false
-        }
-        let version = Int(manufData[trailerBase])
-        let capability = Int(manufData[trailerBase + 1])
-        return (1...15).contains(version) && (capability & 0x01) != 0
+    private func pairingAdvertisement(
+        _ advertisementData: [String: Any]
+    ) -> MentraLivePairingAdvertisement? {
+        MentraLivePairingAdvertisement.parse(
+            coreBluetoothManufacturerData:
+            advertisementData[CBAdvertisementDataManufacturerDataKey] as? Data
+        )
     }
 
     private func isPairingDiscoverable(_ advertisementData: [String: Any]) -> Bool {
-        guard hasSecurePairingTrailer(advertisementData),
-              let manufData = mentraManufacturerData(advertisementData)
-        else {
-            return false
-        }
-        let flagIndex = advManufCompanyIdLength + advManufPairingFlagOffset
-        return manufData[flagIndex] == advPairingDiscoverable
+        pairingAdvertisement(advertisementData)?.pairingMode == true
     }
 
     private struct SecurePairingTrailer {
@@ -1403,24 +1415,19 @@ class MentraLive: NSObject, SGCManager {
         let secureCapable: Bool
     }
 
-    /// Trailer immediately after pairing flag: version | capability | code_lo | code_hi
     private func parseSecurePairingTrailer(_ advertisementData: [String: Any]) -> SecurePairingTrailer {
-        guard hasSecurePairingTrailer(advertisementData),
-              let manufData = mentraManufacturerData(advertisementData)
-        else {
+        guard let advertisement = pairingAdvertisement(advertisementData) else {
             return SecurePairingTrailer(pairingMode: false, pairingCode: nil, secureCapable: false)
         }
-        let flagIndex = advManufCompanyIdLength + advManufPairingFlagOffset
-        let trailerBase = flagIndex + 1
-        let pairingMode = manufData[flagIndex] == advPairingDiscoverable
-        let codeLo = Int(manufData[trailerBase + 2])
-        let codeHi = Int(manufData[trailerBase + 3])
-        let code = String(format: "%02X%02X", codeHi, codeLo)
-        return SecurePairingTrailer(pairingMode: pairingMode, pairingCode: code, secureCapable: true)
+        return SecurePairingTrailer(
+            pairingMode: advertisement.pairingMode,
+            pairingCode: advertisement.pairingCode,
+            secureCapable: true
+        )
     }
 
     private func advertisesPairingFlag(_ advertisementData: [String: Any]) -> Bool {
-        hasSecurePairingTrailer(advertisementData)
+        pairingAdvertisement(advertisementData) != nil
     }
 
     var connectionState: String = ConnTypes.DISCONNECTED
@@ -1642,6 +1649,7 @@ class MentraLive: NSObject, SGCManager {
 
     // State Tracking
     private var isScanning = false
+    private var manualDiscoveryActive = false
     private var isConnecting = false
     private var isKilled = false
     /// Glasses opened pairing window — stand down without forgetting identity/bonds.
@@ -1796,7 +1804,9 @@ class MentraLive: NSObject, SGCManager {
             // clear the saved device name:
             UserDefaults.standard.set("", forKey: PREFS_DEVICE_NAME)
 
+            manualDiscoveryActive = true
             startScan()
+            emitConnectedPendingDeviceForPairingScan()
         }
     }
 
@@ -2388,10 +2398,6 @@ class MentraLive: NSObject, SGCManager {
 
         centralManager?.scanForPeripherals(withServices: nil, options: scanOptions)
 
-        // Fresh advertisements refill pairing metadata. Re-emitting the last scan's
-        // cache would keep a unit pairable after it left pairing mode.
-        emitConnectedDeviceForPairingScan()
-
         // var dName = DeviceManager.shared.deviceName
         // if dName.isEmpty {
         //     dName = "MENTRA_LIVE"
@@ -2409,6 +2415,7 @@ class MentraLive: NSObject, SGCManager {
     }
 
     func stopScan() {
+        manualDiscoveryActive = false
         guard isScanning else { return }
 
         centralManager?.stopScan()
@@ -2914,25 +2921,20 @@ class MentraLive: NSObject, SGCManager {
             let windowMs = max(5_000, min(180_000, json["window_ms"] as? Int ?? 120_000))
             Bridge.log("LIVE: Glasses entering pairing mode — yield \(windowMs)ms (no forget)")
             enterPairingYield(windowMs: windowMs)
-            var body: [String: Any] = [
+            let body: [String: Any] = [
                 "window_ms": windowMs,
                 "reason": json["reason"] as? String ?? "user_gesture",
             ]
-            if let txn = json["txn"] {
-                body["txn"] = txn
-            }
             Bridge.sendTypedMessage("entering_pairing_mode", body: body)
 
         case "pairing_info":
             Bridge.sendPairingInfo(
                 hadPreviousBond: json["had_previous_bond"] as? Bool ?? false,
-                transferId: json["transfer_id"] as? String,
                 pairingCode: json["pairing_code"] as? String,
                 classicBondReady: json["classic_bond_ready"] as? Bool ?? false,
                 // Legacy firmware that omits this field is not secure-capable.
                 securePairingCapable: json["secure_pairing_capable"] as? Bool ?? false,
-                protocolVersion: json["protocol_version"] as? Int ?? 1,
-                binding: json["binding"] as? String
+                protocolVersion: json["protocol_version"] as? Int ?? 1
             )
 
         case "imu_response", "imu_stream_response", "imu_gesture_response",
@@ -5531,22 +5533,33 @@ class MentraLive: NSObject, SGCManager {
 
     // MARK: - Event Emission
 
-    /// Pairing scan listens for advertisements. A unit that is already GATT-connected
-    /// has stopped ADV, so emit it as pairable or the scan list stays empty.
-    private func emitConnectedDeviceForPairingScan() {
-        guard connected, let peripheral = connectedPeripheral, let name = peripheral.name,
-              name == "Xy_A" || name.hasPrefix("XyBLE_") || name.hasPrefix("MENTRA_LIVE_BLE")
-              || name.hasPrefix("MENTRA_LIVE_BT") || name.lowercased().hasPrefix("mentra_live")
+    /// A selected pairing target can stop advertising once GATT connects, before readiness
+    /// promotes it to the default device. Re-emit only that explicit pending target; an
+    /// established owner's connected glasses have no pending identity and remain hidden.
+    private func emitConnectedPendingDeviceForPairingScan() {
+        guard manualDiscoveryActive, !pairingYieldActive, let peripheral = connectedPeripheral,
+              let name = peripheral.name,
+              MentraLivePendingPairingTarget.shouldRecover(
+                  isConnected: peripheral.state == .connected,
+                  connectedName: name,
+                  connectedIdentifier: peripheral.identifier.uuidString,
+                  pendingName: DeviceStore.shared.get("bluetooth", "pending_device_name") as? String ?? "",
+                  pendingIdentifier: DeviceStore.shared.get("bluetooth", "pending_device_address") as? String ?? ""
+              )
         else {
             return
         }
-        Bridge.log("LIVE: Pairing scan: already GATT-connected to \(name) — emitting as pairable (ADV off while connected)")
+
+        Bridge.log("LIVE: Pairing scan: recovering connected pending target \(name) (\(peripheral.identifier))")
         emitDiscoveredDevice(
             name,
             identifier: peripheral.identifier.uuidString,
             pairingMode: true,
             pairingCode: nil,
-            securePairingCapable: discoveredAdvPairing[name]?.securePairingCapable ?? false
+            securePairingCapable: DeviceStore.shared.get(
+                "bluetooth",
+                "pending_device_secure_pairing_capable"
+            ) as? Bool
         )
     }
 

package/ios/Source/sgcs/MentraLivePairingAdvertisement.swift

@@ -0,0 +1,64 @@
+import Foundation
+
+struct MentraLivePairingAdvertisement: Equatable {
+    let pairingMode: Bool
+    let pairingCode: String
+
+    private static let manufacturerId: UInt16 = 0xB822
+    private static let companyIdLength = 2
+    private static let pairingFlagOffset = 5
+    private static let pairingDiscoverable: UInt8 = 0x01
+    private static let protocolVersionOffset = pairingFlagOffset + 1
+    private static let capabilityOffset = protocolVersionOffset + 1
+    private static let codeLowOffset = capabilityOffset + 1
+    private static let codeHighOffset = codeLowOffset + 1
+    private static let magicFirstOffset = codeHighOffset + 1
+    private static let magicSecondOffset = magicFirstOffset + 1
+    private static let protocolVersionRange = 2 ... 15
+    private static let securePairingCapability = 0x01
+    private static let magicFirst: UInt8 = 0x4D // M
+    private static let magicSecond: UInt8 = 0x50 // P
+
+    /// Parses CoreBluetooth manufacturer data, including its two-byte company-id prefix.
+    ///
+    /// Legacy firmware stores an XOR'd Classic MAC where the original pairing implementation
+    /// expected version and capability bytes. Requiring the `MP` marker makes the formats
+    /// unambiguous instead of probabilistically classifying MAC bytes as a secure trailer.
+    static func parse(coreBluetoothManufacturerData data: Data?) -> MentraLivePairingAdvertisement? {
+        guard let data, data.count > companyIdLength + magicSecondOffset else {
+            return nil
+        }
+
+        let companyId = UInt16(data[0]) | (UInt16(data[1]) << 8)
+        guard companyId == manufacturerId else {
+            return nil
+        }
+
+        let payloadBase = companyIdLength
+        let version = Int(data[payloadBase + protocolVersionOffset])
+        let capability = Int(data[payloadBase + capabilityOffset])
+        guard protocolVersionRange.contains(version),
+              capability & securePairingCapability != 0,
+              data[payloadBase + magicFirstOffset] == magicFirst,
+              data[payloadBase + magicSecondOffset] == magicSecond
+        else {
+            return nil
+        }
+
+        let codeLow = Int(data[payloadBase + codeLowOffset])
+        let codeHigh = Int(data[payloadBase + codeHighOffset])
+        return MentraLivePairingAdvertisement(
+            pairingMode: data[payloadBase + pairingFlagOffset] == pairingDiscoverable,
+            pairingCode: String(format: "%02X%02X", codeHigh, codeLow)
+        )
+    }
+}
+
+enum MentraLiveConnectionAttemptPolicy {
+    static func shouldAcceptDidConnect(
+        pairingYieldActive: Bool,
+        matchesActiveAttempt: Bool
+    ) -> Bool {
+        !pairingYieldActive && matchesActiveAttempt
+    }
+}

package/ios/Tests/MentraLivePairingAdvertisementTests.swift

@@ -0,0 +1,160 @@
+import Foundation
+@testable import MentraBluetoothSDK
+import XCTest
+
+final class MentraLivePairingAdvertisementTests: XCTestCase {
+    func testConnectedPairingRecoveryRequiresExplicitPendingTarget() {
+        XCTAssertFalse(
+            MentraLivePendingPairingTarget.matches(
+                connectedName: "MENTRA_LIVE_BLE_OWNER",
+                connectedIdentifier: "AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE",
+                pendingName: "",
+                pendingIdentifier: ""
+            )
+        )
+        XCTAssertTrue(
+            MentraLivePendingPairingTarget.matches(
+                connectedName: "MENTRA_LIVE_BLE_TARGET",
+                connectedIdentifier: "AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE",
+                pendingName: "MENTRA_LIVE_BLE_TARGET",
+                pendingIdentifier: ""
+            )
+        )
+        XCTAssertTrue(
+            MentraLivePendingPairingTarget.matches(
+                connectedName: "MENTRA_LIVE_BLE_TARGET",
+                connectedIdentifier: "AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE",
+                pendingName: "OTHER",
+                pendingIdentifier: "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
+            )
+        )
+        XCTAssertFalse(
+            MentraLivePendingPairingTarget.matches(
+                connectedName: "MENTRA_LIVE_BLE_TARGET",
+                connectedIdentifier: "AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE",
+                pendingName: "MENTRA_LIVE_BLE_TARGET",
+                pendingIdentifier: "11111111-2222-3333-4444-555555555555"
+            )
+        )
+    }
+
+    func testConnectedPairingRecoveryRequiresActiveGattConnection() {
+        XCTAssertFalse(
+            MentraLivePendingPairingTarget.shouldRecover(
+                isConnected: false,
+                connectedName: "MENTRA_LIVE_BLE_TARGET",
+                connectedIdentifier: "AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE",
+                pendingName: "MENTRA_LIVE_BLE_TARGET",
+                pendingIdentifier: "AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE"
+            )
+        )
+        XCTAssertTrue(
+            MentraLivePendingPairingTarget.shouldRecover(
+                isConnected: true,
+                connectedName: "MENTRA_LIVE_BLE_TARGET",
+                connectedIdentifier: "AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE",
+                pendingName: "MENTRA_LIVE_BLE_TARGET",
+                pendingIdentifier: "AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE"
+            )
+        )
+    }
+
+    func testConnectionCallbackPolicyRejectsPairingYieldAndStaleAttempts() {
+        XCTAssertFalse(
+            MentraLiveConnectionAttemptPolicy.shouldAcceptDidConnect(
+                pairingYieldActive: true,
+                matchesActiveAttempt: true
+            )
+        )
+        XCTAssertFalse(
+            MentraLiveConnectionAttemptPolicy.shouldAcceptDidConnect(
+                pairingYieldActive: false,
+                matchesActiveAttempt: false
+            )
+        )
+        XCTAssertTrue(
+            MentraLiveConnectionAttemptPolicy.shouldAcceptDidConnect(
+                pairingYieldActive: false,
+                matchesActiveAttempt: true
+            )
+        )
+    }
+
+    func testParsesMarkedSecurePairingAdvertisement() {
+        let result = MentraLivePairingAdvertisement.parse(
+            coreBluetoothManufacturerData: securePayload(pairingFlag: 1)
+        )
+
+        XCTAssertEqual(result?.pairingCode, "1234")
+        XCTAssertEqual(result?.pairingMode, true)
+    }
+
+    func testParsesMarkedOwnedAdvertisement() {
+        let result = MentraLivePairingAdvertisement.parse(
+            coreBluetoothManufacturerData: securePayload(pairingFlag: 0)
+        )
+
+        XCTAssertEqual(result?.pairingCode, "1234")
+        XCTAssertEqual(result?.pairingMode, false)
+    }
+
+    func testRejectsLegacyPayloadThatMatchesOldVersionCapabilityHeuristic() {
+        var payload = legacyPayload()
+        payload[2 + 5] = 0
+        payload[2 + 6] = 1
+        payload[2 + 7] = 1
+        payload[2 + 8] = 0x34
+        payload[2 + 9] = 0x12
+
+        XCTAssertNil(
+            MentraLivePairingAdvertisement.parse(coreBluetoothManufacturerData: payload)
+        )
+    }
+
+    func testRejectsUnmarkedFirstGenerationSecureTrailer() {
+        var payload = securePayload(pairingFlag: 1)
+        payload[2 + 10] = 0x11
+        payload[2 + 11] = 0x22
+
+        XCTAssertNil(
+            MentraLivePairingAdvertisement.parse(coreBluetoothManufacturerData: payload)
+        )
+    }
+
+    func testRejectsEveryLegacyVersionAndCapabilityCombination() {
+        for version in UInt8.min ... UInt8.max {
+            for capability in UInt8.min ... UInt8.max {
+                var payload = legacyPayload()
+                payload[2 + 5] = 1
+                payload[2 + 6] = version
+                payload[2 + 7] = capability
+                payload[2 + 10] = 0x4D
+                // Offset 11 is padding in the legacy format, so it cannot contain the second
+                // non-zero marker byte.
+                payload[2 + 11] = 0
+                XCTAssertNil(
+                    MentraLivePairingAdvertisement.parse(coreBluetoothManufacturerData: payload)
+                )
+            }
+        }
+    }
+
+    private func legacyPayload() -> Data {
+        var data = Data(repeating: 0, count: 29)
+        data[0] = 0x22
+        data[1] = 0xB8
+        return data
+    }
+
+    private func securePayload(pairingFlag: UInt8) -> Data {
+        var data = legacyPayload()
+        data[2 + 5] = pairingFlag
+        data[2 + 6] = 2
+        data[2 + 7] = 1
+        data[2 + 8] = 0x34
+        data[2 + 9] = 0x12
+        data[2 + 10] = 0x4D
+        data[2 + 11] = 0x50
+        return data
+    }
+}

package/ios/Tests/ReleaseChangelogTests.swift

@@ -0,0 +1,13 @@
+@testable import MentraBluetoothSDK
+import XCTest
+
+final class ReleaseChangelogTests: XCTestCase {
+    func testIncludesTargetNotesForTransitionWithinOneReleaseTrain() throws {
+        let changelogs = try ReleaseChangelogCatalog.select(
+            fromVersion: "3.1.0-dev.2",
+            toVersion: "3.1.0-beta.8"
+        )
+
+        XCTAssertEqual(changelogs.map(\.version), ["3.1.0"])
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mentra/bluetooth-sdk",
-  "version": "3.1.0-dev.7",
+  "version": "3.1.0-dev.71",
   "description": "SDK for communicating with smart glasses",
   "main": "build/index.js",
   "react-native": "src/index.ts",
@@ -32,6 +32,11 @@
       "types": "./build/photo-receiver/index.d.ts",
       "default": "./build/photo-receiver/index.js"
     },
+    "./ota-transport": {
+      "react-native": "./src/ota-transport/index.ts",
+      "types": "./build/ota-transport/index.d.ts",
+      "default": "./build/ota-transport/index.js"
+    },
     "./debug": {
       "react-native": "./src/debug.ts",
       "types": "./build/debug.d.ts",

package/scripts/public-ota-api.test.mjs

@@ -0,0 +1,37 @@
+import assert from "node:assert/strict"
+import {readFileSync} from "node:fs"
+import path from "node:path"
+import test from "node:test"
+import {fileURLToPath} from "node:url"
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..")
+
+test("publishes the supported OTA transport entrypoint", () => {
+  const manifest = JSON.parse(readFileSync(path.join(packageRoot, "package.json"), "utf8"))
+  assert.deepEqual(manifest.exports["./ota-transport"], {
+    "react-native": "./src/ota-transport/index.ts",
+    "types": "./build/ota-transport/index.d.ts",
+    "default": "./build/ota-transport/index.js",
+  })
+
+  const source = readFileSync(path.join(packageRoot, "src/ota-transport/index.ts"), "utf8")
+  assert.match(source, /export const otaLocalNetwork/)
+  assert.match(source, /export const otaServer/)
+  assert.doesNotMatch(source, /export \{default as Mentra(LocalNetwork|OtaServer)/)
+})
+
+test("keeps restart signals and correlated OTA status on the public root", () => {
+  const source = readFileSync(path.join(packageRoot, "src/index.ts"), "utf8")
+  for (const required of [
+    '"glasses_session_changed"',
+    '"mtk_update_complete"',
+    "queryOtaStatus",
+    "subscribeGlassesStatus",
+    "subscribeBluetoothStatus",
+    "setSystemTime",
+    "ping",
+  ]) {
+    assert.ok(source.includes(required), `missing public OTA primitive: ${required}`)
+  }
+  assert.match(source, /Unsupported BluetoothSdk event/)
+})

package/src/BluetoothSdk.types.ts

@@ -652,20 +652,15 @@ export type PairFailureEvent = {
 
 export type PairingInfoEvent = {
   had_previous_bond: boolean
-  /** 16-char uppercase hex transfer id when secure pairing is active. */
-  transfer_id?: string
   pairing_code?: string
   classic_bond_ready?: boolean
   secure_pairing_capable?: boolean
   protocol_version?: number
-  /** Credential binding mode negotiated for this transfer, when reported by the glasses. */
-  binding?: "ctkd" | "temporal" | "none" | string
 }
 
 export type EnteringPairingModeEvent = {
   window_ms: number
   reason?: string
-  txn?: number
 }
 
 export type OwnerReplacedEvent = {
@@ -1048,6 +1043,10 @@ export type BluetoothSdkEventMap = {
   mic_lc3: MicLc3Event
   mic_health: MicHealthEvent
   stream_status: StreamStatusEvent
+  /** Mentra Live MTK updater completed and the glasses are about to restart. */
+  mtk_update_complete: MtkUpdateCompleteEvent
+  /** The ASG process restarted while the BES kept the BLE connection alive. */
+  glasses_session_changed: GlassesSessionChangedEvent
   ota_start_ack: OtaStartAckEvent
   ota_status: OtaStatusEvent
   ar99_ota_status: Ar99OtaStatusEvent
@@ -1073,6 +1072,15 @@ export interface BluetoothSdkPublicModule {
     listener: BluetoothSdkEventListener<EventName>,
   ): BluetoothSdkSubscription
 
+  /** Read an immutable snapshot of the current glasses state. */
+  getGlassesStatus(): Promise<PublicGlassesStatus>
+  /** Read an immutable snapshot of the phone Bluetooth adapter state. */
+  getBluetoothStatus(): Promise<PublicBluetoothStatus>
+  /** Observe immutable glasses-state patches. Returns an unsubscribe function. */
+  subscribeGlassesStatus(listener: (changed: Partial<PublicGlassesStatus>) => void): () => void
+  /** Observe immutable Bluetooth-state patches. Returns an unsubscribe function. */
+  subscribeBluetoothStatus(listener: (changed: Partial<PublicBluetoothStatus>) => void): () => void
+
   getDefaultDevice(): Promise<Device | null>
   setDefaultDevice(device: Device | null): Promise<void>
   clearDefaultDevice(): Promise<void>
@@ -1094,11 +1102,15 @@ export interface BluetoothSdkPublicModule {
   setHeadUpAngle(angleDegrees: number): Promise<void>
   setImuEnabled(enabled: boolean): Promise<void>
   setScreenDisabled(disabled: boolean): Promise<void>
+  /** Keep legacy Mentra Live OTA sessions awake. Modern sessions normally do not require this. */
+  ping(): Promise<void>
 
   requestWifiScan(): Promise<WifiSearchResult[]>
   sendWifiCredentials(ssid: string, password: string): Promise<WifiStatusChangeEvent>
   forgetWifiNetwork(ssid: string): Promise<WifiStatusChangeEvent>
   setHotspotState(enabled: boolean): Promise<HotspotStatusChangeEvent>
+  /** Set the glasses clock from the phone after an OTA clock-skew failure. */
+  setSystemTime(timestampMs: number): Promise<void>
   /** Enable or disable Wi-Fi ADB on Mentra Live (no-op on other devices). */
   setWifiAdbState(enabled: boolean): Promise<void>
 
@@ -1187,8 +1199,12 @@ export interface BluetoothSdkPublicModule {
   getOtaVersionUrl(): string
   /** Fetch the configured OTA manifest and return whether any ASG/BES/MTK update is available. */
   checkForOtaUpdate(): Promise<boolean>
+  /** Return bundled release changelogs crossed between two coordinated product versions, newest first. */
+  getReleaseChangelogs(fromVersion?: string | null, toVersion?: string | null): ReleaseChangelog[]
   /** Start OTA from the configured or explicitly supplied manifest URL. */
   startOtaUpdate(otaVersionUrl?: string | null): Promise<OtaStartAckEvent>
+  /** Query the active OTA session and return the correlated status response. */
+  queryOtaStatus(): Promise<OtaQueryResult>
   startAr99OtaFromFile(path: string): Promise<boolean>
   cancelAr99Ota(): Promise<void>
   sendAr99FactoryReset(): Promise<void>
@@ -1267,6 +1283,13 @@ export interface OtaUpdateInfo {
   isDowngrade?: boolean
 }
 
+export interface ReleaseChangelog {
+  /** Base production version, for example `3.1.0`. */
+  version: string
+  /** Markdown body authored in `/changelogs/<version>.md`. */
+  markdown: string
+}
+
 export interface OtaProgress {
   stage: OtaStage
   status: OtaProgressStatus