Phase 2

Author: donavanbecker

src/ble.ts

@@ -457,6 +457,7 @@ export class BLEConnection {
   private disconnectTimers: Map<string, NodeJS.Timeout> = new Map()
   private operationLocks: Map<string, Promise<void>> = new Map()
   private encryptionConfig: Map<string, { key: Buffer, iv: Buffer, mode: 'ctr' | 'gcm' }> = new Map()
+  private notificationHandlers: Map<string, Set<(payload: Buffer) => void>> = new Map()
   private persistentConnectionMs = 8500
   private noblePromise: Promise<any> | null = null
 
@@ -676,6 +677,62 @@ export class BLEConnection {
     })
   }
 
+  async subscribeNotifications(mac: string, handler: (payload: Buffer) => void): Promise<void> {
+    const normalizedMac = normalizeMAC(mac)
+
+    if (!this.connections.has(normalizedMac)) {
+      await this.connect(normalizedMac)
+    }
+
+    const chars = this.characteristics.get(normalizedMac)
+    if (!chars?.notify) {
+      throw new CommandFailedError(`Notify characteristic not available for ${normalizedMac}`, 'ble')
+    }
+
+    if (!this.notificationHandlers.has(normalizedMac)) {
+      this.notificationHandlers.set(normalizedMac, new Set())
+
+      if (typeof chars.notify.on === 'function') {
+        chars.notify.on('data', (payload: Buffer) => {
+          const handlers = this.notificationHandlers.get(normalizedMac)
+          if (!handlers) {
+            return
+          }
+          for (const listener of handlers) {
+            listener(payload)
+          }
+        })
+      }
+    }
+
+    this.notificationHandlers.get(normalizedMac)!.add(handler)
+
+    if (typeof chars.notify.subscribe === 'function') {
+      await new Promise<void>((resolve, reject) => {
+        chars.notify.subscribe((error: Error) => {
+          if (error) {
+            reject(error)
+          } else {
+            resolve()
+          }
+        })
+      })
+    }
+  }
+
+  unsubscribeNotifications(mac: string, handler: (payload: Buffer) => void): void {
+    const normalizedMac = normalizeMAC(mac)
+    const handlers = this.notificationHandlers.get(normalizedMac)
+    if (!handlers) {
+      return
+    }
+
+    handlers.delete(handler)
+    if (handlers.size === 0) {
+      this.notificationHandlers.delete(normalizedMac)
+    }
+  }
+
   /**
    * Connect to a device
    */
@@ -788,6 +845,7 @@ export class BLEConnection {
     const peripheral = this.connections.get(normalizedMac)
     this.clearDisconnectTimer(normalizedMac)
     this.clearEncryption(normalizedMac)
+    this.notificationHandlers.delete(normalizedMac)
 
     if (!peripheral) {
       return

src/devices/base.ts

@@ -240,6 +240,7 @@ export abstract class SwitchBotDevice extends EventEmitter {
       const startTime = Date.now()
       const mac = this.info.mac ?? `id:${this.info.bleId}`
 
+      let response: Buffer | undefined
       if (this.info.encryptionKey && this.info.encryptionIV && this.bleConnection?.setEncryption) {
         this.bleConnection.setEncryption(
           mac,
@@ -250,7 +251,7 @@ export abstract class SwitchBotDevice extends EventEmitter {
       }
 
       if (this.bleConnection?.sendCommand) {
-        await this.bleConnection.sendCommand(mac, buffer, {
+        response = await this.bleConnection.sendCommand(mac, buffer, {
           expectResponse: true,
           validateResponse: true,
           responseTimeoutMs: 1200,
@@ -275,6 +276,7 @@ export abstract class SwitchBotDevice extends EventEmitter {
       return {
         success: true,
         connectionType: 'ble' as const,
+        data: response,
       }
     }
 

src/devices/wo-bulb.ts

@@ -13,6 +13,29 @@ import { SwitchBotDevice } from './base.js'
  * Color Bulb Device
  */
 export class WoBulb extends SwitchBotDevice implements BulbCommands {
+  private static readonly EFFECTS: Record<string, number> = {
+    christmas: 0x00,
+    candle: 0x01,
+    halloween: 0x02,
+    sunset: 0x03,
+    party: 0x04,
+    reading: 0x05,
+    rainbow: 0x06,
+    forest: 0x07,
+    ocean: 0x08,
+    spring: 0x09,
+    summer: 0x0A,
+    autumn: 0x0B,
+    winter: 0x0C,
+    aurora: 0x0D,
+    meteor: 0x0E,
+    firework: 0x0F,
+    breathe: 0x10,
+    pulse: 0x11,
+    flicker: 0x12,
+    pet: 0x13,
+  }
+
   /**
    * Turn on
    */
@@ -87,6 +110,26 @@ export class WoBulb extends SwitchBotDevice implements BulbCommands {
     return result.success
   }
 
+  /**
+   * Set preset light effect
+   */
+  async setEffect(effectName: string, speed = 100): Promise<boolean> {
+    const effectId = WoBulb.EFFECTS[effectName.toLowerCase()]
+    if (effectId === undefined) {
+      throw new Error(`Unsupported effect: ${effectName}`)
+    }
+
+    const effectSpeed = clamp(speed, 1, 100)
+    const bleCommand = [...DEVICE_COMMANDS.BULB.BASE, effectId, 0xFF, effectSpeed, 0x00, 0x00, 0x00]
+
+    const result = await this.sendCommand(
+      bleCommand,
+      'setEffect',
+      `${effectName}:${effectSpeed}`,
+    )
+    return result.success
+  }
+
   /**
    * Get device status
    */

src/devices/wo-hand.ts

@@ -99,6 +99,54 @@ export class WoHand extends SwitchBotDevice implements BotCommands {
     return result.success
   }
 
+  /**
+   * Set Bot mode
+   */
+  async setMode(mode: 'press' | 'switch'): Promise<boolean> {
+    const modeByte = mode === 'switch' ? 0x01 : 0x00
+    const result = await this.sendCommand(
+      [...DEVICE_COMMANDS.BOT.SET_MODE, modeByte],
+      'setMode',
+      mode,
+    )
+    return result.success
+  }
+
+  /**
+   * Set Bot long-press duration (1-255 deciseconds)
+   */
+  async setLongPress(duration: number): Promise<boolean> {
+    const clampedDuration = Math.min(255, Math.max(1, Math.trunc(duration)))
+    const result = await this.sendCommand(
+      [...DEVICE_COMMANDS.BOT.SET_LONG_PRESS, clampedDuration],
+      'setLongPress',
+      clampedDuration,
+    )
+    return result.success
+  }
+
+  /**
+   * Raise Bot arm
+   */
+  async handUp(): Promise<boolean> {
+    const result = await this.sendCommand(
+      DEVICE_COMMANDS.BOT.UP,
+      'turnOff',
+    )
+    return result.success
+  }
+
+  /**
+   * Lower Bot arm
+   */
+  async handDown(): Promise<boolean> {
+    const result = await this.sendCommand(
+      DEVICE_COMMANDS.BOT.DOWN,
+      'turnOn',
+    )
+    return result.success
+  }
+
   /**
    * Execute password-protected Bot command
    * @param action - Bot action to perform

src/devices/wo-lock-pro.ts

@@ -3,6 +3,8 @@
  * devices/wo-lock-pro.ts: SwitchBot v4.0.0 - Smart Lock Pro Device
  */
 
+import type { Buffer } from 'node:buffer'
+
 import type { LockCommands, LockStatus } from '../types/device.js'
 
 import { WoSmartLockProCommands } from '../settings.js'
@@ -12,10 +14,21 @@ import { SwitchBotDevice } from './base.js'
  * Smart Lock Pro Device (with unlatch support)
  */
 export class WoSmartLockPro extends SwitchBotDevice implements LockCommands {
+  private lockNotificationHandlers = new Set<(payload: Buffer) => void>()
+
   /**
    * Lock the lock
    */
   async lock(): Promise<boolean> {
+    try {
+      const status = await this.getStatus()
+      if (status.lockState === 'locked') {
+        return true
+      }
+    } catch {
+      // Best effort status check before command
+    }
+
     const result = await this.sendCommand(
       WoSmartLockProCommands.LOCK,
       'lock',
@@ -27,13 +40,34 @@ export class WoSmartLockPro extends SwitchBotDevice implements LockCommands {
    * Unlock the lock
    */
   async unlock(): Promise<boolean> {
+    try {
+      const status = await this.getStatus()
+      if (status.lockState === 'unlocked') {
+        return true
+      }
+    } catch {
+      // Best effort status check before command
+    }
+
     const result = await this.sendCommand(
       WoSmartLockProCommands.UNLOCK,
       'unlock',
     )
     return result.success
   }
 
+  /**
+   * Unlock without unlatching the door
+   */
+  async unlockWithoutUnlatch(): Promise<boolean> {
+    const result = await this.sendCommand(
+      WoSmartLockProCommands.UNLOCK,
+      'unlock',
+      'withoutUnlatch',
+    )
+    return result.success
+  }
+
   /**
    * Unlatch the lock (Lock Pro only)
    */
@@ -45,6 +79,48 @@ export class WoSmartLockPro extends SwitchBotDevice implements LockCommands {
     return result.success
   }
 
+  async getLockInfo(): Promise<Record<string, unknown>> {
+    if (this.hasAPI()) {
+      const status = await this.getAPIStatus()
+      return {
+        lockState: status.lockState,
+        doorState: status.doorState,
+        calibrate: status.calibrate,
+        battery: status.battery,
+        version: status.version,
+      }
+    }
+
+    const ble = await this.getBLEStatus().catch(() => this.normalizeBLEStatusData(undefined))
+    return {
+      lockState: ble.lockState,
+      doorOpen: ble.doorOpen,
+      calibration: ble.calibration,
+      battery: ble.battery,
+      sequenceNumber: ble.sequenceNumber,
+    }
+  }
+
+  async onLockNotification(handler: (payload: Buffer) => void): Promise<void> {
+    if (!this.hasBLE()) {
+      throw new Error('BLE not available for lock notifications')
+    }
+
+    const mac = this.info.mac ?? `id:${this.info.bleId}`
+    await this.bleConnection!.subscribeNotifications(mac, handler)
+    this.lockNotificationHandlers.add(handler)
+  }
+
+  offLockNotification(handler: (payload: Buffer) => void): void {
+    if (!this.hasBLE()) {
+      return
+    }
+
+    const mac = this.info.mac ?? `id:${this.info.bleId}`
+    this.bleConnection?.unsubscribeNotifications(mac, handler)
+    this.lockNotificationHandlers.delete(handler)
+  }
+
   /**
    * Get device status
    */