@switchbot/homebridge-switchbot 5.0.0-beta.98 → 5.0.0

package/src/switchbotClient.ts

@@ -1,50 +1,68 @@
 import type { SwitchBotPluginConfig } from './settings.js'
+import type { SwitchBot } from 'node-switchbot'
+
+import { getDeviceCommandHandler } from './deviceCommandMapper.js'
+import { CharacteristicMissingError, SwitchbotAuthenticationError, SwitchbotOperationError } from './errors.js'
 
 export interface ISwitchBotClient {
-  init(): Promise<void>
-  getDevice(id: string): Promise<any>
-  getDevices(): Promise<any[]>
-  setDeviceState(id: string, body: any): Promise<any>
-  destroy(): Promise<void>
+  init: () => Promise<void>
+  getDevice: (id: string) => Promise<any>
+  getDevices: () => Promise<any[]>
+  setDeviceState: (id: string, body: any) => Promise<any>
+  destroy: () => Promise<void>
 }
 
 /**
- * Thin wrapper around node-switchbot v4.0.0-beta.2+
+ * Thin wrapper around node-switchbot v4.0.0+
  * Leverages upstream resilience features (retry, circuit breaker, connection intelligence)
  * while maintaining plugin-specific features like write debouncing and OpenAPI fallback.
  */
 export class SwitchBotClient implements ISwitchBotClient {
   private cfg: SwitchBotPluginConfig
-  private client: any | null = null
-  private baseUrl = 'https://api.switch-bot.com/v1.0'
-  private requestTimeout = 5000
-  private maxRetries = 2
+  private client: SwitchBot | null = null
   private writeDebounceMs = 100
-  private logger: any
-  private pendingWrites: Map<string, { timer: any; body: any; resolvers: Array<{ resolve: (v:any)=>void; reject: (e:any)=>void }>; }> = new Map()
+  private discoveryCacheTtlMs = 30_000
+  private lastDiscoveryAt = 0
+  private logger: import('homebridge').Logger
+  private pendingWrites: Map<string, { timer: any, body: any, resolvers: Array<{ resolve: (v: any) => void, reject: (e: any) => void }> }> = new Map()
 
   constructor(cfg: SwitchBotPluginConfig) {
     this.cfg = cfg
-    this.logger = (cfg as any)?.logger ?? console
-    if (typeof (cfg as any)?.requestTimeout === 'number') this.requestTimeout = (cfg as any).requestTimeout
-    if (typeof (cfg as any)?.maxRetries === 'number') this.maxRetries = (cfg as any).maxRetries
-    if (typeof (cfg as any)?.writeDebounceMs === 'number') this.writeDebounceMs = (cfg as any).writeDebounceMs
+    this.logger = (cfg as any)?.logger as import('homebridge').Logger
+    if (!this.logger) {
+      throw new Error('SwitchBotClient requires a logger (Homebridge logger) in config')
+    }
+    if (typeof (cfg as any)?.writeDebounceMs === 'number') {
+      this.writeDebounceMs = (cfg as any).writeDebounceMs
+    }
+    if (typeof (cfg as any)?.discoveryCacheTtlMs === 'number') {
+      this.discoveryCacheTtlMs = Math.max(0, (cfg as any).discoveryCacheTtlMs)
+    }
   }
 
   async init(): Promise<void> {
+    if (this.client) {
+      return
+    }
+
     try {
       // Dynamic import of node-switchbot v4 with native resilience features
       const { SwitchBot } = await import('node-switchbot')
+      const rawNodeClientConfig = typeof (this.cfg as any)?.nodeClientConfig === 'object' ? (this.cfg as any).nodeClientConfig : {}
+      const scanTimeout = this.resolveScanTimeoutMs(rawNodeClientConfig)
       this.client = new SwitchBot({
         token: this.cfg.openApiToken,
         secret: this.cfg.openApiSecret,
-        // Enable all built-in resilience features from node-switchbot v4
-        enableFallback: true,        // Auto-fallback from BLE to API
-        enableRetry: true,            // Retry with exponential backoff
-        enableCircuitBreaker: true,   // Circuit breaker per connection type
-        enableMetrics: true,          // Connection tracking and statistics
-        ...(typeof (this.cfg as any)?.nodeClientConfig === 'object' && (this.cfg as any).nodeClientConfig),
+        // Enable built-in resilience features from node-switchbot v4.
+        enableFallback: true, // Auto-fallback from BLE to API
+        enableRetry: true, // Retry with exponential backoff
+        enableCircuitBreaker: true, // Circuit breaker per connection type
+        enableConnectionIntelligence: true, // Connection tracking and route preference
+        enableBLE: this.cfg.enableBLE !== false, // Use config value, default true
+        scanTimeout,
+        ...rawNodeClientConfig,
       })
+      this.lastDiscoveryAt = 0
       this.logger?.info?.('SwitchBot client initialized with native resilience features')
     } catch (e) {
       this.logger?.warn?.('Failed to load node-switchbot; will use OpenAPI fallback:', e)
@@ -52,77 +70,55 @@ export class SwitchBotClient implements ISwitchBotClient {
     }
   }
 
-  private async fetchWithTimeoutAndRetry(url: string, opts: any = {}, timeoutMs?: number, retries?: number) {
-    const to = typeof timeoutMs === 'number' ? timeoutMs : this.requestTimeout
-    const max = typeof retries === 'number' ? retries : this.maxRetries
-
-    let attempt = 0
-    while (true) {
-      attempt += 1
-      const controller = new AbortController()
-      const timer = setTimeout(() => controller.abort(), to)
+  async getDevice(id: string): Promise<any> {
+    if (this.client) {
       try {
-        const fetchOpts = Object.assign({}, opts)
-        try {
-          Object.defineProperty(fetchOpts, 'signal', { value: controller.signal, enumerable: false, configurable: true })
-        } catch (_e) {
-          // ignore
+        const fromManager = this.getManagedDevice(id)
+        if (fromManager) {
+          return fromManager
         }
-        const resp = await fetch(url, fetchOpts)
-        clearTimeout(timer)
-        if (resp.ok) return resp
-        // server error / rate limit: retry
-        if (resp.status >= 500 || resp.status === 429) {
-          throw new Error(`retriable response: ${resp.status}`)
+
+        const devices = await this.ensureDiscovered(false)
+        const fromDiscovery = devices.find((d: any) => d.id === id)
+        if (fromDiscovery) {
+          return fromDiscovery
         }
-        return resp
-      } catch (err: any) {
-        clearTimeout(timer)
-        if (attempt > max) throw err
-        // exponential backoff
-        const backoff = Math.min(100 * Math.pow(2, attempt - 1), 2000)
-        await new Promise((r) => setTimeout(r, backoff))
-      }
-    }
-  }
 
-  async getDevice(id: string): Promise<any> {
-    // Try client API first (with node-switchbot's smart fallback and retry)
-    if (this.client?.getDevice) {
-      try {
-        return await this.client.getDevice(id)
-      } catch (e) {
-        this.logger?.warn?.(`Client getDevice failed for ${id}, trying OpenAPI fallback:`, e)
+        const refreshDevices = await this.ensureDiscovered(true)
+        return refreshDevices.find((d: any) => d.id === id)
+      } catch (e: any) {
+        if (e instanceof SwitchbotAuthenticationError) {
+          this.logger?.error?.(`Authentication error for getDevice(${id}):`, e.message)
+          throw e
+        } else if (e instanceof SwitchbotOperationError) {
+          this.logger?.warn?.(`Operation error for getDevice(${id}):`, e.message, e.code)
+          throw e
+        } else if (e instanceof CharacteristicMissingError) {
+          this.logger?.warn?.(`Characteristic missing for getDevice(${id}):`, e.characteristic)
+          throw e
+        } else {
+          this.logger?.warn?.(`Client getDevice failed for ${id}:`, e)
+          throw e
+        }
       }
     }
-    // Fallback: call OpenAPI via HTTP
-    if (this.cfg.openApiToken) {
-      const url = `${this.baseUrl}/devices/${id}`
-      const opts = { headers: { Authorization: this.cfg.openApiToken } }
-      const resp = await this.fetchWithTimeoutAndRetry(url, opts)
-      return resp.json()
-    }
-    throw new Error('No SwitchBot client available')
+    throw new SwitchbotOperationError('No SwitchBot client available', 'no_client')
   }
 
   async getDevices(): Promise<any[]> {
-    // Try client API first
-    if (this.client?.getDevices) {
+    if (this.client) {
       try {
-        return await this.client.getDevices()
+        const fromManager = this.getManagedDevices()
+        if (fromManager.length > 0) {
+          return fromManager
+        }
+        return await this.ensureDiscovered(false)
       } catch (e) {
-        this.logger?.warn?.('Client getDevices failed, trying OpenAPI fallback:', e)
+        this.logger?.warn?.('Client getDevices failed:', e)
+        throw e
       }
     }
-    // Fallback: call OpenAPI
-    if (this.cfg.openApiToken) {
-      const url = `${this.baseUrl}/devices`
-      const opts = { headers: { Authorization: this.cfg.openApiToken } }
-      const resp = await this.fetchWithTimeoutAndRetry(url, opts)
-      const data = await resp.json()
-      return (data?.body || data) as any[]
-    }
-    return []
+    throw new SwitchbotOperationError('No SwitchBot client available', 'no_client')
   }
 
   async setDeviceState(id: string, body: any): Promise<any> {
@@ -139,15 +135,24 @@ export class SwitchBotClient implements ISwitchBotClient {
         return
       }
 
-      const resolvers: Array<{ resolve: (v:any)=>void; reject: (e:any)=>void }> = [{ resolve, reject }]
+      const resolvers: Array<{ resolve: (v: any) => void, reject: (e: any) => void }> = [{ resolve, reject }]
       const timer = setTimeout(async () => {
         const entry = this.pendingWrites.get(id)
-        if (!entry) return
+        if (!entry) {
+          return
+        }
         this.pendingWrites.delete(id)
         try {
           const out = await this._doSetDeviceState(id, entry.body)
           for (const r of entry.resolvers) r.resolve(out)
-        } catch (e) {
+        } catch (e: any) {
+          if (e instanceof SwitchbotAuthenticationError) {
+            this.logger?.error?.(`Authentication error for setDeviceState(${id}):`, e.message)
+          } else if (e instanceof SwitchbotOperationError) {
+            this.logger?.warn?.(`Operation error for setDeviceState(${id}):`, e.message, e.code)
+          } else if (e instanceof CharacteristicMissingError) {
+            this.logger?.warn?.(`Characteristic missing for setDeviceState(${id}):`, e.characteristic)
+          }
           for (const r of entry.resolvers) r.reject(e)
         }
       }, this.writeDebounceMs)
@@ -157,47 +162,105 @@ export class SwitchBotClient implements ISwitchBotClient {
   }
 
   private async _doSetDeviceState(id: string, body: any): Promise<any> {
-    // Prefer client API (which has node-switchbot's native resilience)
-    if (this.client?.setDeviceState) {
-      try {
-        return await this.client.setDeviceState(id, body)
-      } catch (e) {
-        this.logger?.warn?.(`Client setDeviceState failed for ${id}, trying fallback:`, e)
+    if (!this.client) {
+      throw new SwitchbotOperationError('No SwitchBot client available for setDeviceState', 'no_client')
+    }
+    try {
+      const device = await this.getDevice(id)
+      if (!device) {
+        throw new SwitchbotOperationError(`Device ${id} not found`, 'device_not_found')
+      }
+      const deviceType = (device.deviceType ?? '').toLowerCase()
+      const command = body?.command
+      if (!command) {
+        throw new SwitchbotOperationError('No command specified in body', 'no_command')
+      }
+      const handler = getDeviceCommandHandler(deviceType, command)
+      if (!handler) {
+        throw new SwitchbotOperationError(`Unsupported command '${command}' for device type '${deviceType}'`, 'unsupported_command')
+      }
+      this.logger?.debug?.(`[${id}] Calling mapped command '${command}' for device type '${deviceType}'`)
+      return await handler(device, body)
+    } catch (e: any) {
+      if (e instanceof SwitchbotAuthenticationError) {
+        this.logger?.error?.(`Authentication error for setDeviceState(${id}):`, e.message)
+        throw e
+      } else if (e instanceof SwitchbotOperationError) {
+        this.logger?.warn?.(`Operation error for setDeviceState(${id}):`, e.message, e.code)
+        throw e
+      } else if (e instanceof CharacteristicMissingError) {
+        this.logger?.warn?.(`Characteristic missing for setDeviceState(${id}):`, e.characteristic)
+        throw e
+      } else {
+        this.logger?.warn?.(`Device command failed for ${id}:`, e)
+        throw e
       }
     }
+  }
 
-    // Try generic sendCommand if available
-    if (this.client?.sendCommand) {
-      try {
-        return await this.client.sendCommand(id, body)
-      } catch (e) {
-        this.logger?.warn?.(`Client sendCommand failed for ${id}, trying OpenAPI:`, e)
+  async destroy(): Promise<void> {
+    for (const [, pending] of this.pendingWrites) {
+      clearTimeout(pending.timer)
+      const err = new SwitchbotOperationError('Client destroyed before pending write was sent', 'client_destroyed')
+      for (const r of pending.resolvers) {
+        r.reject(err)
       }
     }
+    this.pendingWrites.clear()
 
-    // OpenAPI fallback
-    if (this.cfg.openApiToken) {
-      const url = `${this.baseUrl}/devices/${id}/commands`
-      const opts = {
-        method: 'POST',
-        headers: {
-          Authorization: this.cfg.openApiToken,
-          'Content-Type': 'application/json',
-        },
-        body: JSON.stringify(body),
-      }
-      const resp = await this.fetchWithTimeoutAndRetry(url, opts)
-      return resp.json()
+    if (this.client?.cleanup) {
+      await this.client.cleanup()
+    }
+    this.client = null
+    this.lastDiscoveryAt = 0
+  }
+
+  private resolveScanTimeoutMs(rawNodeClientConfig: Record<string, any>): number {
+    if (typeof rawNodeClientConfig.scanTimeout === 'number' && Number.isFinite(rawNodeClientConfig.scanTimeout)) {
+      return Math.max(500, rawNodeClientConfig.scanTimeout)
+    }
+
+    if (typeof rawNodeClientConfig.scanDuration === 'number' && Number.isFinite(rawNodeClientConfig.scanDuration)) {
+      return Math.max(500, rawNodeClientConfig.scanDuration)
+    }
+
+    if (typeof (this.cfg as any)?.bleScanDurationSeconds === 'number') {
+      return Math.max(500, (this.cfg as any).bleScanDurationSeconds * 1000)
     }
 
-    throw new Error('No SwitchBot client available for setDeviceState')
+    return 5000
   }
 
-  async destroy(): Promise<void> {
-    if (this.client?.destroy) {
-      await this.client.destroy()
+  private getManagedDevice(id: string): any {
+    const manager = (this.client as any)?.devices
+    if (manager?.get) {
+      return manager.get(id)
     }
-    this.client = null
+    return undefined
+  }
+
+  private getManagedDevices(): any[] {
+    const manager = (this.client as any)?.devices
+    if (manager?.list) {
+      const list = manager.list()
+      return Array.isArray(list) ? list : []
+    }
+    return []
   }
-}
 
+  private async ensureDiscovered(force: boolean): Promise<any[]> {
+    if (!this.client) {
+      throw new SwitchbotOperationError('No SwitchBot client available', 'no_client')
+    }
+
+    const fromManager = this.getManagedDevices()
+    const cacheValid = this.discoveryCacheTtlMs > 0 && (Date.now() - this.lastDiscoveryAt) < this.discoveryCacheTtlMs
+    if (!force && cacheValid && fromManager.length > 0) {
+      return fromManager
+    }
+
+    const discovered = await this.client.discover()
+    this.lastDiscoveryAt = Date.now()
+    return discovered
+  }
+}