Fix macOS BLE Bot control (#334)

## Summary

- Allows macOS BLE-only SwitchBot Bot devices to be controlled when
noble exposes a peripheral ID but no usable MAC address.
- Passes live BLE/API handles into discovered device instances so
BLE-capable devices are actually commandable after discovery.
- Lets device implementations explicitly mark BLE commands as
write-only, and applies that to standard Bot action commands.
- Avoids fatal unhandled EventEmitter `error` events when device command
failures are already returned to the caller.

## Root Cause

On macOS, noble may discover a SwitchBot Bot by peripheral ID rather
than MAC address and stores discovered peripherals in its private
`_peripherals` map. The existing BLE availability and connect paths
assumed a MAC/public peripheral list. Standard Bot action commands also
do not provide the response expected by the response-validating command
path, so they need to be sent as write-only BLE commands.

Separately, command failures logged and returned failure objects but
also emitted EventEmitter `error` events. In consumers without an
`error` listener, Node treats that as fatal and can crash the process
instead of letting the integration handle the returned command failure.

## Changes

- Treat `bleId` as sufficient for BLE availability when a MAC address is
unavailable.
- Pass the initialized `BLEConnection` and `OpenAPIClient` into created
device instances.
- Read known peripherals from noble `peripherals` or `_peripherals`,
including array, map, and object forms.
- Add an internal `writeOnly` boolean for BLE commands.
- Mark standard Bot action commands as write-only while leaving other
BLE commands on the normal response-validating path.
- Emit device `error` events only when a listener is registered.

## Validation

- `npm run lint`
- `npm run build`
- `npm test`

## Notes

- This is the lower-level BLE fix.

Author: rmehta33

src/ble.ts

@@ -619,6 +619,24 @@ export class BLEConnection {
     this.encryptionConfig.delete(normalizeMAC(mac))
   }
 
+  private getKnownPeripherals(): any[] {
+    const candidates = [this.noble?.peripherals, this.noble?._peripherals]
+
+    for (const peripherals of candidates) {
+      if (Array.isArray(peripherals)) {
+        return peripherals
+      }
+      if (peripherals instanceof Map) {
+        return [...peripherals.values()]
+      }
+      if (peripherals && typeof peripherals === 'object') {
+        return Object.values(peripherals)
+      }
+    }
+
+    return []
+  }
+
   private incrementIv(iv: Buffer): Buffer {
     const nextIv = Buffer.from(iv)
     for (let i = nextIv.length - 1; i >= 0; i--) {
@@ -831,7 +849,7 @@ export class BLEConnection {
     this.logger.info(`Connecting to ${mac}`)
 
     // Find peripheral (by address or ID)
-    const peripherals = await this.noble.peripherals || []
+    const peripherals = this.getKnownPeripherals()
     let peripheral: any
 
     // Try to find by normalized MAC first

src/devices/base.ts

@@ -310,7 +310,7 @@ export abstract class SwitchBotDevice extends EventEmitter {
    * Check if BLE is available for this device
    */
   hasBLE(): boolean {
-    return this.info.connectionTypes.includes('ble') && !!this.bleConnection && !!this.info.mac
+    return this.info.connectionTypes.includes('ble') && !!this.bleConnection && (!!this.info.mac || !!this.info.bleId)
   }
 
   /**
@@ -320,6 +320,12 @@ export abstract class SwitchBotDevice extends EventEmitter {
     return this.info.connectionTypes.includes('api') && !!this.apiClient && this.info.cloudServiceEnabled !== false
   }
 
+  protected emitError(payload: Record<string, unknown>): void {
+    if (this.listenerCount('error') > 0) {
+      this.emit('error', payload)
+    }
+  }
+
   /**
    * Get device status (abstract - implemented by subclasses)
    */
@@ -368,6 +374,7 @@ export abstract class SwitchBotDevice extends EventEmitter {
    */
   protected async sendBLECommand(
     command: readonly number[] | number[] | Buffer,
+    writeOnly = false,
   ): Promise<CommandResult> {
     if (!this.hasBLE()) {
       return {
@@ -394,7 +401,7 @@ export abstract class SwitchBotDevice extends EventEmitter {
       const buffer = Buffer.isBuffer(command) ? command : Buffer.from(command)
 
       const startTime = Date.now()
-      const mac = this.info.mac ?? `id:${this.info.bleId}`
+      const mac = this.info.mac && this.info.mac.length > 0 ? this.info.mac : `id:${this.info.bleId}`
 
       let response: Buffer | undefined
       if (this.info.encryptionKey && this.info.encryptionIV && this.bleConnection?.setEncryption) {
@@ -406,7 +413,9 @@ export abstract class SwitchBotDevice extends EventEmitter {
         )
       }
 
-      if (this.bleConnection?.sendCommand) {
+      if (writeOnly) {
+        await this.bleConnection!.write(mac, buffer)
+      } else if (this.bleConnection?.sendCommand) {
         response = await this.bleConnection.sendCommand(mac, buffer, {
           expectResponse: true,
           validateResponse: true,
@@ -459,7 +468,7 @@ export abstract class SwitchBotDevice extends EventEmitter {
       }
 
       this.logger.error('BLE command failed', error)
-      this.emit('error', { type: 'ble', error })
+      this.emitError({ type: 'ble', error })
 
       return {
         success: false,
@@ -540,7 +549,7 @@ export abstract class SwitchBotDevice extends EventEmitter {
       }
 
       this.logger.error('API command failed', error)
-      this.emit('error', { type: 'api', error })
+      this.emitError({ type: 'api', error })
 
       return {
         success: false,
@@ -587,6 +596,7 @@ export abstract class SwitchBotDevice extends EventEmitter {
     bleCommand: readonly number[] | number[] | Buffer,
     apiCommand: string,
     apiParameter?: any,
+    writeOnly = false,
   ): Promise<CommandResult> {
     // Determine connection strategy
     let primaryConnection = this.preferredConnection
@@ -628,7 +638,7 @@ export abstract class SwitchBotDevice extends EventEmitter {
     let fallbackUsed = false
 
     if (primaryConnection === 'ble') {
-      result = await this.sendBLECommand(bleCommand)
+      result = await this.sendBLECommand(bleCommand, writeOnly)
     } else {
       result = await this.sendAPICommand(apiCommand, apiParameter)
     }
@@ -652,7 +662,7 @@ export abstract class SwitchBotDevice extends EventEmitter {
       await this.fallbackHandlerManager.emit(fallbackEvent)
 
       if (secondaryConnection === 'ble') {
-        result = await this.sendBLECommand(bleCommand)
+        result = await this.sendBLECommand(bleCommand, writeOnly)
       } else {
         result = await this.sendAPICommand(apiCommand, apiParameter)
       }

src/devices/wo-hand.ts

@@ -12,6 +12,8 @@ import { DEVICE_COMMANDS } from '../settings.js'
 import { BOT_BLE_ACTIONS, buildBotBleCommand, parseBotBleResponse, validateBotPassword } from '../utils/index.js'
 import { DeviceOverrideStateDuringConnection } from './device-override-state-during-connection.js'
 
+const BOT_BLE_COMMAND_WRITE_ONLY = true
+
 /**
  * Bot (WoHand) Device - Press or switch button device
  * Supports optional BLE password protection
@@ -89,6 +91,8 @@ export class WoHand extends DeviceOverrideStateDuringConnection implements BotCo
     const result = await this.sendCommand(
       DEVICE_COMMANDS.BOT.TURN_ON,
       'turnOn',
+      undefined,
+      BOT_BLE_COMMAND_WRITE_ONLY,
     )
     return result.success
   }
@@ -106,6 +110,8 @@ export class WoHand extends DeviceOverrideStateDuringConnection implements BotCo
     const result = await this.sendCommand(
       DEVICE_COMMANDS.BOT.TURN_OFF,
       'turnOff',
+      undefined,
+      BOT_BLE_COMMAND_WRITE_ONLY,
     )
     return result.success
   }
@@ -123,6 +129,8 @@ export class WoHand extends DeviceOverrideStateDuringConnection implements BotCo
     const result = await this.sendCommand(
       DEVICE_COMMANDS.BOT.PRESS,
       'press',
+      undefined,
+      BOT_BLE_COMMAND_WRITE_ONLY,
     )
     return result.success
   }
@@ -159,6 +167,8 @@ export class WoHand extends DeviceOverrideStateDuringConnection implements BotCo
     const result = await this.sendCommand(
       DEVICE_COMMANDS.BOT.UP,
       'turnOff',
+      undefined,
+      BOT_BLE_COMMAND_WRITE_ONLY,
     )
     return result.success
   }
@@ -170,6 +180,8 @@ export class WoHand extends DeviceOverrideStateDuringConnection implements BotCo
     const result = await this.sendCommand(
       DEVICE_COMMANDS.BOT.DOWN,
       'turnOn',
+      undefined,
+      BOT_BLE_COMMAND_WRITE_ONLY,
     )
     return result.success
   }
@@ -209,7 +221,7 @@ export class WoHand extends DeviceOverrideStateDuringConnection implements BotCo
       return true
     } catch (error) {
       this.logger.error('Password-protected command failed', error)
-      this.emit('error', { type: 'ble', error, encrypted: true })
+      this.emitError({ type: 'ble', error, encrypted: true })
       throw error
     }
   }

src/switchbot.ts

@@ -549,6 +549,8 @@ export class SwitchBot extends EventEmitter {
       const { extractDeviceOptionsFromConfig } = await import('./utils/index.js')
       return new DeviceClass(info, {
         ...extractDeviceOptionsFromConfig(this.config),
+        apiClient: this.apiClient,
+        bleConnection: this.bleConnection,
       })
     } catch (error) {
       this.logger.error(`createDevice: Failed to create device ${className}`, error)