@mentra/bluetooth-sdk 3.2.0-dev.180 → 3.2.0-dev.187

package/android/src/test/java/com/mentra/bluetoothsdk/ConnectedDeviceMatcherTest.kt

@@ -0,0 +1,161 @@
+package com.mentra.bluetoothsdk
+
+import org.assertj.core.api.Assertions.assertThat
+import org.junit.Test
+
+class ConnectedDeviceMatcherTest {
+    private val savedLive =
+        Device(
+            model = DeviceModel.MENTRA_LIVE,
+            name = "Mentra Live 4X2A",
+            address = "AA:BB:CC:DD:EE:FF",
+        )
+
+    @Test
+    fun `matches Mentra Live advertised name prefixes`() {
+        for (name in listOf("Xy_A", "XyBLE_1234", "MENTRA_LIVE_BLE_9", "MENTRA_LIVE_BT_9", "mentra_live_abc")) {
+            assertThat(
+                ConnectedDeviceMatcher.matches(
+                    model = DeviceModel.MENTRA_LIVE,
+                    defaultDevice = null,
+                    candidateName = name,
+                    candidateAddress = null,
+                ),
+            ).describedAs(name).isTrue()
+        }
+    }
+
+    @Test
+    fun `matches Mentra Nex advertised name prefixes`() {
+        for (name in listOf("Nex1-77", "MENTRA_DISPLAY_02")) {
+            assertThat(
+                ConnectedDeviceMatcher.matches(
+                    model = DeviceModel.MENTRA_NEX,
+                    defaultDevice = null,
+                    candidateName = name,
+                    candidateAddress = null,
+                ),
+            ).describedAs(name).isTrue()
+        }
+    }
+
+    @Test
+    fun `name prefixes are scoped to the scanned model`() {
+        // A held Mentra Live can never explain an empty Nex (or G1) scan.
+        assertThat(
+            ConnectedDeviceMatcher.matches(
+                model = DeviceModel.MENTRA_NEX,
+                defaultDevice = null,
+                candidateName = "XyBLE_1234",
+                candidateAddress = null,
+            ),
+        ).isFalse()
+        assertThat(
+            ConnectedDeviceMatcher.matches(
+                model = DeviceModel.G1,
+                defaultDevice = null,
+                candidateName = "MENTRA_LIVE_BT_9",
+                candidateAddress = null,
+            ),
+        ).isFalse()
+    }
+
+    @Test
+    fun `rejects non-Mentra peripherals`() {
+        for (name in listOf("Even G1_22_L_", "Pixel Watch", "MX Master 3S")) {
+            assertThat(
+                ConnectedDeviceMatcher.matches(
+                    model = DeviceModel.MENTRA_LIVE,
+                    defaultDevice = savedLive,
+                    candidateName = name,
+                    candidateAddress = "11:22:33:44:55:66",
+                ),
+            ).describedAs(name).isFalse()
+        }
+    }
+
+    @Test
+    fun `matches the saved default by exact name`() {
+        assertThat(
+            ConnectedDeviceMatcher.matches(
+                model = DeviceModel.MENTRA_LIVE,
+                defaultDevice = savedLive,
+                candidateName = "Mentra Live 4X2A",
+                candidateAddress = null,
+            ),
+        ).isTrue()
+    }
+
+    @Test
+    fun `matches the saved default by address ignoring case`() {
+        // Stored addresses can arrive lowercase from the JS side.
+        assertThat(
+            ConnectedDeviceMatcher.matches(
+                model = DeviceModel.MENTRA_LIVE,
+                defaultDevice = savedLive.copy(address = "aa:bb:cc:dd:ee:ff"),
+                candidateName = null,
+                candidateAddress = "AA:BB:CC:DD:EE:FF",
+            ),
+        ).isTrue()
+    }
+
+    @Test
+    fun `saved default only counts for its own model`() {
+        // Scanning for G1 while the saved default is a Mentra Live.
+        assertThat(
+            ConnectedDeviceMatcher.matches(
+                model = DeviceModel.G1,
+                defaultDevice = savedLive,
+                candidateName = "Mentra Live 4X2A",
+                candidateAddress = "AA:BB:CC:DD:EE:FF",
+            ),
+        ).isFalse()
+    }
+
+    @Test
+    fun `models without a branded name rely on the saved default`() {
+        val savedG1 = Device(model = DeviceModel.G1, name = "Even G1_22_L_", address = null)
+        assertThat(
+            ConnectedDeviceMatcher.matches(
+                model = DeviceModel.G1,
+                defaultDevice = savedG1,
+                candidateName = "Even G1_22_L_",
+                candidateAddress = null,
+            ),
+        ).isTrue()
+    }
+
+    @Test
+    fun `simulated model never matches`() {
+        assertThat(
+            ConnectedDeviceMatcher.matches(
+                model = DeviceModel.SIMULATED,
+                defaultDevice = savedLive,
+                candidateName = "Mentra Live 4X2A",
+                candidateAddress = "AA:BB:CC:DD:EE:FF",
+            ),
+        ).isFalse()
+    }
+    @Test
+    fun `blank saved identities never identify an unrelated connection`() {
+        val saved = Device(DeviceModel.G1, name = "", address = "")
+        assertThat(ConnectedDeviceMatcher.matches(DeviceModel.G1, saved, "", "")).isFalse()
+        assertThat(ConnectedDeviceMatcher.matches(DeviceModel.G1, saved, null, null)).isFalse()
+    }
+
+    @Test
+    fun `different known addresses override a matching saved name`() {
+        val saved = Device(DeviceModel.G1, name = "Even G1", address = "AA:BB:CC:DD:EE:FF")
+        assertThat(
+            ConnectedDeviceMatcher.matches(DeviceModel.G1, saved, "Even G1", "11:22:33:44:55:66"),
+        ).isFalse()
+    }
+
+    @Test
+    fun `a branded candidate can still match its model without being the saved device`() {
+        assertThat(
+            ConnectedDeviceMatcher.matches(DeviceModel.MENTRA_LIVE, savedLive, "XyBLE_5678", "11:22:33:44:55:66"),
+        ).isTrue()
+    }
+
+}

package/android/src/test/java/com/mentra/bluetoothsdk/ScanCompletionTest.kt

@@ -0,0 +1,87 @@
+package com.mentra.bluetoothsdk
+
+import org.assertj.core.api.Assertions.assertThat
+import org.junit.Test
+
+class ScanCompletionTest {
+    private val hint = ScanDiagnostic("device_connected_on_phone", "A matching device is connected to this phone.")
+
+    @Test
+    fun `empty completed scan delivers diagnostic then completion without error`() {
+        val events = mutableListOf<String>()
+        val callback = object : MentraBluetoothScanCallback() {
+            override fun onDiagnostic(diagnostic: ScanDiagnostic) {
+                assertThat(diagnostic).isEqualTo(hint)
+                events.add("diagnostic")
+            }
+            override fun onComplete(devices: List<Device>) {
+                assertThat(devices).isEmpty()
+                events.add("complete")
+            }
+            override fun onError(error: BluetoothError) {
+                events.add("error")
+            }
+        }
+        callback.completeScan(ScanStopReason.COMPLETED, emptyList()) { hint }
+        assertThat(events).containsExactly("diagnostic", "complete")
+    }
+
+    @Test
+    fun `legacy callbacks complete without querying diagnostics`() {
+        var completed = false
+        // Implement only the pre-existing interface; it gains no abstract method.
+        val callback = object : ScanCallback {
+            override fun onComplete(devices: List<Device>) { completed = true }
+        }
+        callback.completeScan(ScanStopReason.COMPLETED, emptyList()) {
+            error("Legacy callbacks must not query diagnostics")
+        }
+        assertThat(completed).isTrue()
+        assertThat(ScanCallback::class.java.declaredMethods.map { it.name })
+            .containsExactlyInAnyOrder("onResults", "onComplete", "onError")
+    }
+
+    @Test
+    fun `cancelled scans and nonempty scans never query diagnostics`() {
+        val device = Device(DeviceModel.MENTRA_LIVE, "XyBLE_1234")
+        val completed = mutableListOf<List<Device>>()
+        val callback = object : MentraBluetoothScanCallback() {
+            override fun onComplete(devices: List<Device>) { completed.add(devices) }
+            override fun onDiagnostic(diagnostic: ScanDiagnostic) { error("Unexpected diagnostic") }
+        }
+        for ((reason, devices) in listOf(
+            ScanStopReason.CANCELLED to emptyList(),
+            ScanStopReason.COMPLETED to listOf(device),
+        )) {
+            callback.completeScan(reason, devices) { error("Unexpected diagnostic query") }
+        }
+        assertThat(completed).containsExactly(emptyList(), listOf(device))
+    }
+
+    @Test
+    fun `missing diagnostic leaves an ordinary empty completion`() {
+        val events = mutableListOf<String>()
+        val callback = object : MentraBluetoothScanCallback() {
+            override fun onComplete(devices: List<Device>) { events.add("complete") }
+            override fun onDiagnostic(diagnostic: ScanDiagnostic) { events.add("diagnostic") }
+            override fun onError(error: BluetoothError) { events.add("error") }
+        }
+        callback.completeScan(ScanStopReason.COMPLETED, emptyList()) { null }
+        assertThat(events).containsExactly("complete")
+    }
+
+    @Test
+    fun `completion still runs if the diagnostic handler throws`() {
+        var completed = false
+        val failure = IllegalStateException("consumer diagnostic handler failed")
+        val callback = object : MentraBluetoothScanCallback() {
+            override fun onComplete(devices: List<Device>) { completed = true }
+            override fun onDiagnostic(diagnostic: ScanDiagnostic) { throw failure }
+        }
+        val thrown = runCatching {
+            callback.completeScan(ScanStopReason.COMPLETED, emptyList()) { hint }
+        }.exceptionOrNull()
+        assertThat(thrown).isSameAs(failure)
+        assertThat(completed).isTrue()
+    }
+}

package/android/src/test/java/com/mentra/bluetoothsdk/sgcs/EvenFileServiceTest.kt

@@ -0,0 +1,153 @@
+package com.mentra.bluetoothsdk.sgcs
+
+import com.mentra.bluetoothsdk.NativeNotificationConfig
+import java.io.IOException
+import kotlinx.coroutines.CompletableDeferred
+import kotlinx.coroutines.async
+import kotlinx.coroutines.cancelAndJoin
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.runBlocking
+import org.junit.Assert.*
+import org.junit.Test
+
+class EvenFileServiceTest {
+    @Test fun `upload arms fast acknowledgements and only checks result after data`() = runBlocking {
+        lateinit var files: EvenFileService
+        val frames = mutableListOf<Pair<Byte, ByteArray>>()
+        files = EvenFileService { service, data ->
+            frames += service to data
+            when {
+                service == 0xC5.toByte() -> files.acceptAck(byteArrayOf(1, 0))
+                data[0] == 0.toByte() -> files.acceptAck(byteArrayOf(0, 0))
+                data[0] == 2.toByte() -> files.acceptAck(byteArrayOf(2, 0))
+            }
+        }
+        assertEquals(0, files.transfer(1, FileService.PATH_NOTIFY, byteArrayOf(7, 8)))
+        assertEquals(listOf(0xC4.toByte(), 0xC4.toByte(), 0xC5.toByte(), 0xC4.toByte()), frames.map { it.first })
+        assertEquals(93, frames[0].second.size)
+        assertArrayEquals(byteArrayOf(7, 8), frames[2].second)
+        assertFalse(files.needsReconnect)
+    }
+
+    @Test fun `start refusal stops before sending content`() = runBlocking {
+        lateinit var files: EvenFileService
+        var writes = 0
+        files = EvenFileService { _, _ -> writes++; files.acceptAck(byteArrayOf(0, 1)) }
+        assertEquals(1, files.transfer(1, "n", byteArrayOf(1)))
+        assertEquals(1, writes)
+    }
+
+    @Test fun `CRC rejection is observable and never reported delivered`() = runBlocking {
+        lateinit var files: EvenFileService
+        files = EvenFileService { service, data ->
+            val cid = if (service == 0xC5.toByte()) 1 else data[0].toInt()
+            if (service == 0xC5.toByte() || cid != 1) files.acceptAck(byteArrayOf(cid.toByte(), if (cid == 2) 2 else 0))
+        }
+        assertEquals(2, files.transfer(1, "n", byteArrayOf(9)))
+    }
+
+    @Test fun `wrong phase and echoed payload cannot satisfy a pending ACK`() = runBlocking {
+        val sent = CompletableDeferred<Unit>()
+        val files = EvenFileService { _, _ -> sent.complete(Unit) }
+        val transfer = async { files.transfer(1, "n", byteArrayOf(1)) }
+        sent.await()
+        files.acceptAck(byteArrayOf(1, 0))
+        files.acceptAck(byteArrayOf(0, 0, 0))
+        assertFalse(transfer.isCompleted)
+        transfer.cancelAndJoin()
+        assertTrue(files.needsReconnect)
+    }
+
+    @Test fun `disable cancels wait and blocks ambiguous reuse until reconnect`() = runBlocking {
+        val sent = CompletableDeferred<Unit>()
+        val files = EvenFileService { _, _ -> sent.complete(Unit) }
+        val transfer = launch { files.transfer(1, "n", byteArrayOf(1)) }
+        sent.await(); transfer.cancelAndJoin()
+        files.acceptAck(byteArrayOf(0, 0)) // late old response
+        try { files.transfer(1, "n", byteArrayOf(2)); fail("ambiguous channel was reused") } catch (_: IllegalStateException) {}
+        files.resetConnection()
+        assertFalse(files.needsReconnect)
+    }
+
+    @Test fun `connection reset cancels old wait without tainting new connection`() = runBlocking {
+        val sent = CompletableDeferred<Unit>()
+        val files = EvenFileService { _, _ -> sent.complete(Unit) }
+        val transfer = launch { files.transfer(1, "n", byteArrayOf(1)) }
+        sent.await(); files.resetConnection(); transfer.join()
+        assertTrue(transfer.isCancelled)
+        assertFalse(files.needsReconnect)
+    }
+
+    @Test fun `ack timeout prevents the next upload from consuming a late response`() = runBlocking {
+        val files = EvenFileService(timeoutMs = 1) { _, _ -> }
+        try { files.transfer(1, "n", byteArrayOf(1)); fail("expected timeout") } catch (_: IOException) {}
+        assertTrue(files.needsReconnect)
+    }
+
+    @Test fun `start struct encodes unsigned little endian sizes and zero padded filename`() {
+        val data = FileService.sendStart(1, 0x01020304, 0x11223344, "n")
+        assertEquals(93, data.size)
+        assertArrayEquals(byteArrayOf(0, 1, 0, 0, 0, 4, 3, 2, 1, 0x44, 0x33, 0x22, 0x11), data.copyOfRange(0, 13))
+        assertEquals('n'.code.toByte(), data[13])
+        assertTrue(data.drop(14).all { it == 0.toByte() })
+    }
+
+    @Test fun `corrupt or truncated BLE acknowledgements cannot complete a transfer`() {
+        val valid = byteArrayOf(0xAA.toByte(), 0x12, 1, 4, 1, 1, 0xC4.toByte(), 0, 0, 0, 0x0F, 0x1D)
+        assertArrayEquals(byteArrayOf(0, 0), EvenFileService.decodeAckFrame(valid))
+        assertNull(EvenFileService.decodeAckFrame(valid.copyOf(11)))
+        valid[10] = 0
+        assertNull(EvenFileService.decodeAckFrame(valid))
+    }
+
+    @Test fun `Even CRC uses the non reflected zero seed variant`() {
+        assertEquals(0, EvenFileService.crc32(byteArrayOf()))
+        assertEquals(0xC052A8C8.toInt(), EvenFileService.crc32("123456789".toByteArray()))
+    }
+
+    @Test fun `updates reuse ids without colliding with numeric phone ids`() {
+        val ids = NotificationIds()
+        val first = ids.forPhoneId("app-key")
+        assertEquals(first, ids.forPhoneId("app-key"))
+        assertNotEquals(first, ids.forPhoneId(first.toString()))
+        assertNotEquals(ids.forPhoneId(""), ids.forPhoneId(""))
+        repeat(1000) { ids.forPhoneId("other-$it") }
+        assertEquals(first, ids.forPhoneId("app-key"))
+    }
+
+    @Test fun `capacity never evicts known ids or reuses anonymous ids`() {
+        val ids = NotificationIds()
+        val known = ids.forPhoneId("retained-card")
+        val allocated = mutableSetOf(known)
+        repeat(7999) { assertTrue(allocated.add(ids.forPhoneId(""))) }
+        assertEquals(8000, allocated.size)
+        assertEquals(2000, allocated.minOrNull())
+        assertEquals(9999, allocated.maxOrNull())
+        assertEquals("notification_id_capacity_exhausted",
+            assertThrows(IllegalStateException::class.java) { ids.forPhoneId("new-card") }.message)
+        assertThrows(IllegalStateException::class.java) { ids.forPhoneId("") }
+        assertEquals(known, ids.forPhoneId("retained-card"))
+    }
+
+    @Test fun `all named ids remain stable when capacity is exhausted`() {
+        val ids = NotificationIds()
+        val allocated = (0 until 8000).associate { it.toString() to ids.forPhoneId(it.toString()) }
+        assertEquals(8000, allocated.values.toSet().size)
+        assertThrows(IllegalStateException::class.java) { ids.forPhoneId("new") }
+        allocated.forEach { (key, value) -> assertEquals(value, ids.forPhoneId(key)) }
+    }
+
+    @Test fun `disabled controls stop presentation without changing the whitelist`() {
+        val commands = NotificationProto.controls(NativeNotificationConfig(enabled = false), 11, 12)
+        assertEquals(listOf(11), commands.map { it.first })
+        assertArrayEquals(byteArrayOf(8, 1, 16, 11, 26, 8, 8, 0, 16, 1, 24, 5, 40, 0), commands.single().second)
+    }
+
+    @Test fun `enabled controls include the phone-side filtering override`() {
+        val commands = NotificationProto.controls(NativeNotificationConfig(enabled = true), 11, 12)
+        assertEquals(listOf(11, 12), commands.map { it.first })
+        assertArrayEquals(byteArrayOf(8, 1, 16, 11, 26, 8, 8, 1, 16, 1, 24, 5, 40, 0), commands.first().second)
+        assertArrayEquals(byteArrayOf(8, 3, 16, 12, 50, 2, 8, 1), commands.last().second)
+    }
+
+}

package/build/BluetoothSdk.types.d.ts

@@ -776,6 +776,8 @@ export type BluetoothSdkModuleEvents = {
     speaking_status: (event: SpeakingStatusEvent) => void;
     battery_status: (event: BatteryStatusEvent) => void;
     local_transcription: (event: LocalTranscriptionEvent) => void;
+    native_notification_status: (event: NativeNotificationStatus) => void;
+    native_notification_delivery: (event: NativeNotificationDelivery) => void;
     phone_notification: (event: PhoneNotificationEvent) => void;
     phone_notification_dismissed: (event: PhoneNotificationDismissedEvent) => void;
     wifi_status_change: (event: WifiStatusChangeEvent) => void;
@@ -851,9 +853,55 @@ export interface PhoneNotificationDismissedEvent {
     packageName: string;
     timestamp: number;
 }
+/**
+ * Outbound payload for `sendPhoneNotification` — a notification pushed INTO the glasses' own
+ * notification centre. The inverse of {@link PhoneNotificationEvent}, which reports
+ * notifications the glasses relayed TO the phone (iOS/ANCS). Drivers map these keys onto
+ * whatever their firmware expects.
+ */
+export interface NativeNotificationConfig {
+    enabled: boolean;
+    autoDisplay: boolean;
+    durationSeconds: number;
+    doNotDisturb: boolean;
+    /** Android package names. iOS rejects nonempty lists; its ANCS filter is firmware-owned. */
+    blockedApps: string[];
+}
+export interface NativeNotificationStatus {
+    supported: boolean;
+    source: "phone" | "ancs" | "unsupported";
+    authorization: "system" | "authorized" | "not_authorized" | "unknown";
+    /** `submitted` is not a firmware-confirmed acknowledgement. */
+    state: "unavailable" | "disabled" | "configuring" | "submitted" | "needs_reconnect" | "failed";
+    config: NativeNotificationConfig;
+    error: string;
+}
+export interface NativeNotificationDelivery {
+    notificationId: string;
+    status: "delivered" | "failed" | "cancelled" | "dropped";
+    reason: string;
+}
+export interface NativePhoneNotification {
+    /** Stable id from the phone's notification listener; parsed to an int where firmware needs one. */
+    notificationId: string;
+    /** Reverse-DNS package id of the originating app. */
+    packageName: string;
+    /** Human app name (e.g. "Messages"). */
+    appName: string;
+    title: string;
+    /** Android `android.subText`. Empty when the listener didn't capture one. */
+    subtitle: string;
+    body: string;
+    /** Unix ms post time. */
+    timestampMs: number;
+    /** Posted or updated. Removal is not supported by the verified protocol. */
+    action: 0;
+}
 export type PublicGlassesStatus = Omit<GlassesStatus, "otaUpdateAvailable" | "otaProgress" | "otaInProgress" | "otaVersionUrl">;
 export type PublicBluetoothStatus = Pick<BluetoothStatus, "searching" | "searchingController" | "systemMicUnavailable" | "micRanking" | "currentMic" | "searchResults" | "wifiScanResults" | "lastLog" | "otherBtConnected" | "galleryModeEnabled">;
 export type BluetoothSdkEventMap = {
+    native_notification_status: NativeNotificationStatus;
+    native_notification_delivery: NativeNotificationDelivery;
     log: LogEvent;
     device_discovered: Device;
     default_device_changed: {
@@ -912,6 +960,8 @@ export type BluetoothSdkSubscription = {
 };
 export type BluetoothSdkEvent = BluetoothSdkEventMap[BluetoothSdkEventName];
 export interface BluetoothSdkPublicModule {
+    configureNativeNotifications(config: NativeNotificationConfig): Promise<void>;
+    getNativeNotificationStatus(): Promise<NativeNotificationStatus>;
     addListener<EventName extends BluetoothSdkEventName>(eventName: EventName, listener: BluetoothSdkEventListener<EventName>): BluetoothSdkSubscription;
     /** Read an immutable snapshot of the current glasses state. */
     getGlassesStatus(): Promise<PublicGlassesStatus>;
@@ -1178,6 +1228,11 @@ export interface ConnectOptions {
     cancelExistingConnectionAttempt?: boolean;
 }
 export type ScanResultsCallback = (devices: Device[]) => void;
+/** Advisory for an empty scan. System connection state does not identify an owning app. */
+export interface ScanDiagnostic {
+    code: string;
+    message: string;
+}
 export interface ScanOptions {
     model: DeviceModel;
     /** Defaults to 15000. */
@@ -1186,6 +1241,8 @@ export interface ScanOptions {
     timeout?: number;
     /** Called every time the discovered device list changes during the scan. */
     onResults?: ScanResultsCallback;
+    /** Optional non-fatal hint before an empty scan resolves, on Android and iOS. */
+    onDiagnostic?: (diagnostic: ScanDiagnostic) => void;
 }
 export type ScanModelOptions = Omit<ScanOptions, "model">;
 export interface WifiSearchResult {