Breaking: Move to a dynamic model of permission checks (#73)

Remove them from the connection status.

Check them before connect but also provide pre-flight API for UX flows.

This better matches the iOS/Android permission model and is easier for client
code to manage.

Author: microbit-matt-hillsdon

lib/availability.ts

@@ -0,0 +1,42 @@
+/**
+ * (c) 2021, Micro:bit Educational Foundation and contributors
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { ConnectionAvailabilityStatus, DeviceError } from "./device.js";
+
+/**
+ * Throws a DeviceError if the availability status indicates the connection is unavailable.
+ * The error codes align with ConnectionAvailabilityStatus values.
+ *
+ * @param status - The availability status to check.
+ * @throws {DeviceError} If status is not "available".
+ */
+export const throwIfUnavailable = (
+  status: ConnectionAvailabilityStatus,
+): void => {
+  switch (status) {
+    case "available":
+      return;
+    case "unsupported":
+      throw new DeviceError({
+        code: "unsupported",
+        message: "Connection type not supported",
+      });
+    case "disabled":
+      throw new DeviceError({
+        code: "disabled",
+        message: "Connection is disabled",
+      });
+    case "permission-denied":
+      throw new DeviceError({
+        code: "permission-denied",
+        message: "Permission denied",
+      });
+    case "location-disabled":
+      throw new DeviceError({
+        code: "location-disabled",
+        message: "Location services disabled",
+      });
+  }
+};

lib/bluetooth.ts

@@ -18,6 +18,7 @@ import {
   BeforeRequestDevice,
   BoardVersion,
   ConnectOptions,
+  ConnectionAvailabilityStatus,
   ConnectionStatus,
   ConnectionStatusEvent,
   DeviceConnection,
@@ -42,6 +43,8 @@ import {
   TypedServiceEvent,
 } from "./service-events.js";
 
+import { throwIfUnavailable } from "./availability.js";
+
 type BleClientError = { message: string; errorMessage: string };
 
 let bleClientInitialized = false;
@@ -181,7 +184,7 @@ class MicrobitWebBluetoothConnectionImpl
   extends TypedEventTarget<DeviceConnectionEventMap & ServiceConnectionEventMap>
   implements MicrobitWebBluetoothConnection
 {
-  status: ConnectionStatus = ConnectionStatus.SUPPORT_NOT_KNOWN;
+  status: ConnectionStatus = ConnectionStatus.NO_AUTHORIZED_DEVICE;
 
   /**
    * The USB device we last connected to.
@@ -192,12 +195,6 @@ class MicrobitWebBluetoothConnectionImpl
   private logging: Logging;
   private connection: BluetoothDeviceWrapper | undefined;
 
-  private availabilityListener = (e: Event) => {
-    // TODO: is this called? is `value` correct?
-    const value = (e as any).value as boolean;
-    this.availability = value;
-  };
-  private availability: boolean | undefined;
   private nameFilter: string | undefined;
   private deferStatusUpdates: boolean = false;
 
@@ -222,24 +219,73 @@ class MicrobitWebBluetoothConnectionImpl
     this.logging.error(message, e);
   }
 
-  async initialize(): Promise<void> {
-    navigator.bluetooth?.addEventListener(
-      "availabilitychanged",
-      this.availabilityListener,
-    );
-    this.availability = await navigator.bluetooth?.getAvailability();
-    this.setStatus(
-      this.availability
-        ? ConnectionStatus.NO_AUTHORIZED_DEVICE
-        : ConnectionStatus.NOT_SUPPORTED,
-    );
+  async initialize(): Promise<void> {}
+
+  dispose() {}
+
+  async checkAvailability(): Promise<ConnectionAvailabilityStatus> {
+    if (Capacitor.isNativePlatform()) {
+      return this.checkNativeBluetoothAvailability();
+    }
+    return this.checkWebBluetoothAvailability();
   }
 
-  dispose() {
-    navigator.bluetooth?.removeEventListener(
-      "availabilitychanged",
-      this.availabilityListener,
-    );
+  private async checkWebBluetoothAvailability(): Promise<ConnectionAvailabilityStatus> {
+    if (!navigator.bluetooth) {
+      return "unsupported";
+    }
+
+    try {
+      const available = await navigator.bluetooth.getAvailability();
+      return available ? "available" : "disabled";
+    } catch {
+      return "disabled";
+    }
+  }
+
+  private async checkNativeBluetoothAvailability(): Promise<ConnectionAvailabilityStatus> {
+    try {
+      // On Android, check if location services are enabled. This is only
+      // required on Android < 12 (API < 31), but isLocationEnabled() returns
+      // true on newer Android, so we can always check it.
+      if (isAndroid()) {
+        const isLocationEnabled = await BleClient.isLocationEnabled();
+        if (!isLocationEnabled) {
+          return "location-disabled";
+        }
+      }
+
+      // Initialize BLE (requests permissions automatically on first call).
+      if (!bleClientInitialized) {
+        await BleClient.initialize({ androidNeverForLocation: true });
+        bleClientInitialized = true;
+      }
+
+      // Check if Bluetooth is enabled.
+      const isBluetoothEnabled = await BleClient.isEnabled();
+      if (!isBluetoothEnabled) {
+        return "disabled";
+      }
+
+      return "available";
+    } catch (e) {
+      // Handle errors from BleClient.initialize() which rejects for permission
+      // or unsupported states. Error messages are hardcoded in the plugin:
+      // https://github.com/capacitor-community/bluetooth-le/blob/main/ios/Plugin/DeviceManager.swift
+      const errorMessage =
+        e instanceof Error ? e.message : (e as BleClientError)?.message ?? "";
+      this.log(`Bluetooth availability check failed: "${errorMessage}"`);
+
+      if (errorMessage === "BLE permission denied") {
+        return "permission-denied";
+      }
+      if (errorMessage === "BLE unsupported") {
+        return "unsupported";
+      }
+
+      // Unknown error - default to permission-denied
+      return "permission-denied";
+    }
   }
 
   getBoardVersion(): BoardVersion | undefined {
@@ -249,8 +295,10 @@ class MicrobitWebBluetoothConnectionImpl
   async connect(options?: ConnectOptions): Promise<void> {
     const progress = options?.progress ?? (() => {});
 
+    // Check availability before connecting. Done here rather than at initialize()
+    // because on Android/iOS that's the appropriate time to ask for permissions.
     progress(ProgressStage.Initializing);
-    await this.preConnectInitialization();
+    throwIfUnavailable(await this.checkAvailability());
 
     if (!this.connection) {
       progress(ProgressStage.FindingDevice);
@@ -276,53 +324,6 @@ class MicrobitWebBluetoothConnectionImpl
     await this.connection.connect();
   }
 
-  /**
-   * Initializes BLE.
-   *
-   * This must happen before requesting a device or connecting.
-   *
-   * We do this just before use not at connection initialize because on Android/iOS
-   * that's the appropriate time to ask for permissions.
-   */
-  private async preConnectInitialization(): Promise<void> {
-    try {
-      if (isAndroid()) {
-        const isLocationEnabled = await BleClient.isLocationEnabled();
-        if (!isLocationEnabled) {
-          throw new DeviceError({
-            code: "bluetooth-missing-permissions",
-            message: "Location services is disabled",
-          });
-        }
-      }
-      if (!bleClientInitialized) {
-        await BleClient.initialize({ androidNeverForLocation: true });
-        bleClientInitialized = true;
-      }
-      const isBluetoothEnabled = await BleClient.isEnabled();
-      if (!isBluetoothEnabled) {
-        throw new DeviceError({
-          code: "bluetooth-disabled",
-          message: "Bluetooth is disabled",
-        });
-      }
-    } catch (e: unknown) {
-      this.error("Error initializing Bluetooth", e);
-      const error = e as BleClientError;
-      if (error.message === "BLE permission denied") {
-        // Error thrown for iOS platform.
-        throw new DeviceError({
-          code: "bluetooth-disabled",
-          message: "Bluetooth is disabled",
-        });
-      }
-      throw new DeviceError({
-        code: "bluetooth-missing-permissions",
-        message: "Missing permissions",
-      });
-    }
-  }
-
   async disconnect(): Promise<void> {
     try {
       if (this.connection) {

lib/device.ts

@@ -5,6 +5,17 @@
  */
 import { TypedEventTarget, ValueIsEvent } from "./events.js";
 
+/**
+ * Connection availability status returned by checkAvailability().
+ * Used for pre-flight UX decisions before attempting to connect.
+ */
+export type ConnectionAvailabilityStatus =
+  | "available"
+  | "unsupported"
+  | "disabled"
+  | "permission-denied"
+  | "location-disabled";
+
 /**
  * Specific identified error types.
  *
@@ -47,14 +58,6 @@ export type DeviceErrorCode =
    * Failed to establish Bluetooth connection.
    */
   | "bluetooth-connection-failed"
-  /**
-   * Bluetooth is disabled on the device.
-   */
-  | "bluetooth-disabled"
-  /**
-   * Missing required Bluetooth permissions.
-   */
-  | "bluetooth-missing-permissions"
   /**
    * Partial flash operation failed.
    */
@@ -66,7 +69,27 @@ export type DeviceErrorCode =
   /**
    * Flash operation was cancelled.
    */
-  | "flash-cancelled";
+  | "flash-cancelled"
+  /**
+   * Connection type is not supported on this platform/browser.
+   * Aligns with ConnectionAvailabilityStatus "unsupported".
+   */
+  | "unsupported"
+  /**
+   * Connection is disabled (e.g., Bluetooth turned off).
+   * Aligns with ConnectionAvailabilityStatus "disabled".
+   */
+  | "disabled"
+  /**
+   * Required permissions were denied.
+   * Aligns with ConnectionAvailabilityStatus "permission-denied".
+   */
+  | "permission-denied"
+  /**
+   * Location services are disabled (Android < 12 only).
+   * Aligns with ConnectionAvailabilityStatus "location-disabled".
+   */
+  | "location-disabled";
 
 export enum ProgressStage {
   Initializing = "Initializing",
@@ -116,23 +139,17 @@ export class DeviceError extends Error {
 }
 
 /**
- * Tracks connection status,
+ * Tracks connection status.
  */
 export enum ConnectionStatus {
   /**
-   * Determining whether the connection type is supported requires
-   * initialize() to complete.
-   */
-  SUPPORT_NOT_KNOWN = "SUPPORT_NOT_KNOWN",
-  /**
-   * Not supported.
-   */
-  NOT_SUPPORTED = "NOT_SUPPORTED",
-  /**
-   * Supported but no device available.
+   * No device available.
+   *
+   * This is the initial status and will be the case even when a device is
+   * physically connected but has not been connected via the browser security UI.
    *
-   * This will be the case even when a device is physically connected
-   * but has not been connected via the browser security UI.
+   * Use checkAvailability() to determine whether the connection type is
+   * supported before attempting to connect.
    */
   NO_AUTHORIZED_DEVICE = "NO_AUTHORIZED_DEVICE",
   /**
@@ -237,6 +254,17 @@ export interface DeviceConnection<M extends ValueIsEvent<M>>
    * Initializes the device.
    */
   initialize(): Promise<void>;
+
+  /**
+   * Checks if this connection type is currently available.
+   *
+   * Use this for pre-flight UX decisions (e.g., showing "enable Bluetooth" dialog).
+   * Note: Even if this returns "available", connect() can still fail.
+   *
+   * @returns A promise resolving to the current availability status.
+   */
+  checkAvailability(): Promise<ConnectionAvailabilityStatus>;
+
   /**
    * Removes all listeners.
    */

lib/index.ts

@@ -12,6 +12,7 @@ import {
   BeforeRequestDevice,
   BoardVersion,
   ConnectOptions,
+  ConnectionAvailabilityStatus,
   ConnectionStatus,
   ConnectionStatusEvent,
   DeviceConnection,
@@ -80,6 +81,7 @@ export type {
   AccelerometerData,
   AccelerometerDataEvent,
   BoardVersion,
+  ConnectionAvailabilityStatus,
   ButtonEvent,
   ButtonEventType,
   ButtonState,

lib/usb-radio-bridge.ts

@@ -8,6 +8,7 @@ import { AccelerometerDataEvent } from "./accelerometer.js";
 import { ButtonEvent, ButtonState } from "./buttons.js";
 import {
   BoardVersion,
+  ConnectionAvailabilityStatus,
   ConnectionStatus,
   ConnectionStatusEvent,
   DeviceConnection,
@@ -130,6 +131,10 @@ class MicrobitRadioBridgeConnectionImpl
     this.delegate.addEventListener("status", this.delegateStatusListener);
   }
 
+  async checkAvailability(): Promise<ConnectionAvailabilityStatus> {
+    return this.delegate.checkAvailability();
+  }
+
   dispose(): void {
     this.delegate.removeEventListener("status", this.delegateStatusListener);
     this.delegate.dispose();

lib/usb.test.ts

@@ -27,10 +27,10 @@ const describeDeviceOnly = process.env.TEST_MODE_DEVICE
   : describe.skip;
 
 describe("MicrobitWebUSBConnection (WebUSB unsupported)", () => {
-  it("notices if WebUSB isn't supported", () => {
+  it("checkAvailability returns unsupported when WebUSB isn't available", async () => {
     vi.stubGlobal("navigator", {});
     const microbit = createWebUSBConnection();
-    expect(microbit.status).toBe(ConnectionStatus.NOT_SUPPORTED);
+    expect(await microbit.checkAvailability()).toBe("unsupported");
     vi.unstubAllGlobals();
   });
   it("still triggers afterrequestdevice if requestDevice throws", async () => {