@switchbot/homebridge-switchbot 5.0.0-beta.13 → 5.0.0-beta.131

package/src/settings.ts

@@ -1,283 +1,18 @@
-/* Copyright(C) 2017-2024, donavanbecker (https://github.com/donavanbecker). All rights reserved.
- *
- * settings.ts: @switchbot/homebridge-switchbot platform class.
- */
-import type { IClientOptions } from 'async-mqtt'
-import type { PlatformConfig } from 'homebridge'
-/*
-* For Testing Locally:
-* import type { device, irdevice, SwitchBotBLEModel, SwitchBotBLEModelFriendlyName, SwitchBotBLEModelName } from '/Users/Shared/GitHub/OpenWonderLabs/node-switchbot/dist/index.js';
-*/
-import type { device, irdevice, SwitchBotBLEModel, SwitchBotBLEModelFriendlyName, SwitchBotBLEModelName, SwitchBotModel } from 'node-switchbot'
-/**
- * This is the name of the platform that users will use to register the plugin in the Homebridge config.json
- */
-export const PLATFORM_NAME = 'SwitchBot'
-
-/**
- * This must match the name of your plugin as defined the package.json
- */
 export const PLUGIN_NAME = '@switchbot/homebridge-switchbot'
+export const PLATFORM_NAME = 'SwitchBot'
 
-// Config
-export interface SwitchBotPlatformConfig extends PlatformConfig {
-  credentials?: credentials
-  options?: options
-}
-interface credentials {
-  token?: string
-  secret?: string
-  notice?: string
-}
-
-export interface options {
-  devices?: devicesConfig[]
-  deviceConfig?: { [deviceType: string]: devicesConfig }
-  irdevices?: irDevicesConfig[]
-  irdeviceConfig?: { [remoteType: string]: irDevicesConfig }
-  allowInvalidCharacters?: boolean
-  mqttURL?: string
-  mqttOptions?: IClientOptions
-  mqttPubOptions?: IClientOptions
-  BLE?: boolean
-  discoverBLE?: boolean
-  disableLogsforBLE?: boolean
-  disableLogsforOpenAPI?: boolean
-  hostname?: string
-  webhookURL?: string
-  maxRetries?: number
-  delayBetweenRetries?: number
-  refreshRate?: number
-  updateRate?: number
-  pushRate?: number
-  logging?: string
-};
-
-export type devicesConfig = botConfig | relaySwitch1Config | relaySwitch1PMConfig | meterConfig | meterProConfig | indoorOutdoorSensorConfig | humidifierConfig | curtainConfig | blindTiltConfig | contactConfig | motionConfig | waterDetectorConfig | plugConfig | colorBulbConfig | stripLightConfig | ceilingLightConfig | lockConfig | hubConfig
-
-export interface BaseDeviceConfig extends device {
-  bleMac?: string
-  model: SwitchBotModel
-  bleModel: SwitchBotBLEModel
-  bleModelName: SwitchBotBLEModelName
-  bleModelFriednlyName: SwitchBotBLEModelFriendlyName
-  configDeviceType: string
-  configDeviceName?: string
-  deviceId: string
-  external?: boolean
-  refreshRate?: number
-  updateRate?: number
-  pushRate?: number
-  firmware?: string
-  logging?: string
-  connectionType?: string
-  customBLEaddress?: string
-  scanDuration?: number
-  hide_device?: boolean
-  offline?: boolean
-  maxRetry?: number
-  maxRetries?: number
-  delayBetweenRetries?: number
-  disableCaching?: boolean
-  disablePlatformBLE?: boolean
-  mqttURL?: string
-  mqttOptions?: IClientOptions
-  mqttPubOptions?: IClientOptions
-  history?: boolean
-  webhook?: boolean
+export interface SwitchBotPluginConfig {
+  openApiToken?: string
+  openApiSecret?: string
+  preferMatter?: boolean
+  enableMatter?: boolean
+  // other plugin-specific configuration
+  [key: string]: any
 }
 
-export interface botConfig extends BaseDeviceConfig {
-  configDeviceType: 'Bot'
-  mode?: string
-  type: string
-  doublePress?: number
-  pushRatePress?: number
-  allowPush?: boolean
-  multiPress?: boolean
-};
-
-export interface relaySwitch1Config extends BaseDeviceConfig {
-  configDeviceType: 'Relay Switch 1'
-  type: string
-  allowPush?: boolean
-};
-
-export interface relaySwitch1PMConfig extends BaseDeviceConfig {
-  configDeviceType: 'Relay Switch 1PM'
-  type: string
-  allowPush?: boolean
-};
-
-export interface meterConfig extends BaseDeviceConfig {
-  configDeviceType: 'Meter' | 'MeterPlus'
-  hide_temperature?: boolean
-  convertUnitTo?: string
-  hide_humidity?: boolean
-};
-
-export interface meterProConfig extends BaseDeviceConfig {
-  configDeviceType: 'Meter Pro' | 'MeterPro(CO2)'
-  hide_temperature?: boolean
-  convertUnitTo?: string
-  hide_humidity?: boolean
-  hide_co2?: boolean
-};
-
-export interface indoorOutdoorSensorConfig extends BaseDeviceConfig {
-  configDeviceType: 'WoIOSensor'
-  hide_temperature?: boolean
-  convertUnitTo?: string
-  hide_humidity?: boolean
-};
-
-export interface humidifierConfig extends BaseDeviceConfig {
-  configDeviceType: 'Humidifier' | 'Humidifier2'
-  hide_temperature?: boolean
-  convertUnitTo?: string
-  set_minStep?: number
-};
-
-export interface curtainConfig extends BaseDeviceConfig {
-  configDeviceType: 'Curtain' | 'Curtain3' | 'WoRollerShade' | 'Roller Shade'
-  disable_group?: boolean
-  hide_lightsensor?: boolean
-  set_minLux?: number
-  set_maxLux?: number
-  set_max?: number
-  set_min?: number
-  set_minStep?: number
-  setCloseMode?: string
-  setOpenMode?: string
-  silentModeSwitch?: boolean
-};
-
-export interface blindTiltConfig extends BaseDeviceConfig {
-  configDeviceType: 'Blind Tilt'
-  disable_group?: boolean
-  mapping?: string
-  hide_lightsensor?: boolean
-  set_minLux?: number
-  set_maxLux?: number
-  set_max?: number
-  set_min?: number
-  set_minStep?: number
-  setCloseMode?: string
-  setOpenMode?: string
-  silentModeSwitch?: boolean
-};
-
-export interface contactConfig extends BaseDeviceConfig {
-  configDeviceType: 'Contact Sensor'
-  hide_lightsensor?: boolean
-  set_minLux?: number
-  set_maxLux?: number
-  hide_motionsensor?: boolean
-};
-
-export interface motionConfig extends BaseDeviceConfig {
-  configDeviceType: 'Motion Sensor'
-  hide_lightsensor?: boolean
-  set_minLux?: number
-  set_maxLux?: number
-};
-
-export interface waterDetectorConfig extends BaseDeviceConfig {
-  configDeviceType: 'Water Detector'
-  hide_leak?: boolean
-  dry?: boolean
-};
-
-export interface plugConfig extends BaseDeviceConfig {
-  configDeviceType: 'Plug' | 'Plug Mini (US)' | 'Plug Mini (JP)'
-};
-
-export interface colorBulbConfig extends BaseDeviceConfig {
-  configDeviceType: 'Color Bulb'
-  set_minStep?: number
-  adaptiveLightingShift?: number
-};
-
-export interface stripLightConfig extends BaseDeviceConfig {
-  configDeviceType: 'Strip Light'
-  set_minStep?: number
-  adaptiveLightingShift?: number
-};
-
-export interface ceilingLightConfig extends BaseDeviceConfig {
-  configDeviceType: 'Ceiling Light' | 'Ceiling Light Pro'
-  set_minStep?: number
-  adaptiveLightingShift?: number
-};
-
-export interface lockConfig extends BaseDeviceConfig {
-  configDeviceType: 'Smart Lock' | 'Smart Lock Pro'
-  hide_contactsensor?: boolean
-  activate_latchbutton?: boolean
-};
-
-export interface hubConfig extends BaseDeviceConfig {
-  configDeviceType: 'Hub 2'
-  hide_temperature?: boolean
-  convertUnitTo?: string
-  hide_humidity?: boolean
-  hide_lightsensor?: boolean
-  set_minLux?: number
-  set_maxLux?: number
-};
-
-export type irDevicesConfig = irFanConfig | irLightConfig | irAirConfig | irOtherConfig
-
-export interface irBaseDeviceConfig extends irdevice {
-  configDeviceName?: string
-  configRemoteType?: string
-  connectionType?: string
-  hide_device?: boolean
-  external?: boolean
-  refreshRate?: number
-  updateRate?: number
-  pushRate?: number
-  maxRetries?: number
-  delayBetweenRetries?: number
-  firmware?: string
-  deviceId: string
-  logging?: string
-  customOn?: string
-  customOff?: string
-  customize?: boolean
-  commandType?: string
-  disablePushOn?: boolean
-  disablePushOff?: boolean
-  disablePushDetail?: boolean
+export const DEFAULT_CONFIG: Partial<SwitchBotPluginConfig> = {
+  preferMatter: true,
+  enableMatter: true,
 }
 
-export interface irFanConfig extends irBaseDeviceConfig {
-  configRemoteType?: 'Fan' | 'DIY Fan'
-  swing_mode?: boolean
-  rotation_speed?: boolean
-  set_minStep?: number
-  set_max?: number
-  set_min?: number
-};
-
-export interface irLightConfig extends irBaseDeviceConfig {
-  configRemoteType?: 'Light' | 'DIY Light'
-  stateless?: boolean
-};
-
-export interface irAirConfig extends irBaseDeviceConfig {
-  configRemoteType?: 'Air Conditioner' | 'DIY Air Conditioner'
-  hide_automode?: boolean
-  set_max_heat?: number
-  set_min_heat?: number
-  set_max_cool?: number
-  set_min_cool?: number
-  meterType?: string
-  meterId?: string
-  meterUuid?: string
-};
-
-export interface irOtherConfig extends irBaseDeviceConfig {
-  configRemoteType?: 'Others'
-  type?: string
-};
+export type DeviceType = string

package/src/switchbotClient.ts

@@ -0,0 +1,251 @@
+import type { SwitchBotPluginConfig } from './settings.js'
+import { SwitchbotOperationError, SwitchbotAuthenticationError, CharacteristicMissingError } 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>
+}
+
+/**
+ * Thin wrapper around node-switchbot v4.0.0-beta.2+
+ * 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 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()
+
+  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
+  }
+
+  async init(): Promise<void> {
+    try {
+      // Dynamic import of node-switchbot v4 with native resilience features
+      const { SwitchBot } = await import('node-switchbot')
+      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
+        enableBLE: true,              // Enable BLE scanning by default
+        scanDuration: 5000,           // BLE scan duration in milliseconds
+        ...(typeof (this.cfg as any)?.nodeClientConfig === 'object' && (this.cfg as any).nodeClientConfig),
+      })
+      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)
+      this.client = null
+    }
+  }
+
+  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)
+      try {
+        const fetchOpts = Object.assign({}, opts)
+        try {
+          Object.defineProperty(fetchOpts, 'signal', { value: controller.signal, enumerable: false, configurable: true })
+        } catch (_e) {
+          // ignore
+        }
+        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}`)
+        }
+        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: 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)
+        } else if (e instanceof CharacteristicMissingError) {
+          this.logger?.warn?.(`Characteristic missing for getDevice(${id}):`, e.characteristic)
+        } else {
+          this.logger?.warn?.(`Client getDevice failed for ${id}, trying OpenAPI fallback:`, 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 SwitchbotOperationError('No SwitchBot client available', 'no_client')
+  }
+
+  async getDevices(): Promise<any[]> {
+    // Try client API first
+    if (this.client?.getDevices) {
+      try {
+        return await this.client.getDevices()
+      } catch (e) {
+        this.logger?.warn?.('Client getDevices failed, trying OpenAPI fallback:', 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 []
+  }
+
+  async setDeviceState(id: string, body: any): Promise<any> {
+    // Plugin-level debounce: coalesce rapid writes per device
+    if (!this.writeDebounceMs || this.writeDebounceMs <= 0) {
+      return this._doSetDeviceState(id, body)
+    }
+
+    return new Promise((resolve, reject) => {
+      const existing = this.pendingWrites.get(id)
+      if (existing) {
+        existing.body = body
+        existing.resolvers.push({ resolve, reject })
+        return
+      }
+
+      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
+        this.pendingWrites.delete(id)
+        try {
+          const out = await this._doSetDeviceState(id, entry.body)
+          for (const r of entry.resolvers) r.resolve(out)
+        } 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)
+
+      this.pendingWrites.set(id, { timer, body, resolvers })
+    })
+  }
+
+  private async _doSetDeviceState(id: string, body: any): Promise<any> {
+    // Prefer client API (which has node-switchbot's native resilience)
+    if (this.client?.setDeviceState) {
+      try {
+        this.logger?.debug?.(`[${id}] Using client.setDeviceState()`)
+        const result = await this.client.setDeviceState(id, body)
+        this.logger?.debug?.(`[${id}] client.setDeviceState() response:`, result)
+        return result
+      } 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)
+        } else if (e instanceof CharacteristicMissingError) {
+          this.logger?.warn?.(`Characteristic missing for setDeviceState(${id}):`, e.characteristic)
+        } else {
+          this.logger?.warn?.(`Client setDeviceState failed for ${id}, trying fallback:`, e)
+        }
+      }
+    }
+
+    // Try generic sendCommand if available
+    if (this.client?.sendCommand) {
+      try {
+        this.logger?.debug?.(`[${id}] Using client.sendCommand()`)
+        const result = await this.client.sendCommand(id, body)
+        this.logger?.debug?.(`[${id}] client.sendCommand() response:`, result)
+        return result
+      } catch (e: any) {
+        if (e instanceof SwitchbotAuthenticationError) {
+          this.logger?.error?.(`Authentication error for sendCommand(${id}):`, e.message)
+          throw e
+        } else if (e instanceof SwitchbotOperationError) {
+          this.logger?.warn?.(`Operation error for sendCommand(${id}):`, e.message, e.code)
+        } else if (e instanceof CharacteristicMissingError) {
+          this.logger?.warn?.(`Characteristic missing for sendCommand(${id}):`, e.characteristic)
+        } else {
+          this.logger?.warn?.(`Client sendCommand failed for ${id}, trying OpenAPI:`, e)
+        }
+      }
+    }
+
+    // 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),
+      }
+      this.logger?.debug?.(`[${id}] Using OpenAPI fallback POST ${url}`)
+      this.logger?.debug?.(`[${id}] Request body:`, body)
+      const resp = await this.fetchWithTimeoutAndRetry(url, opts)
+      const result = await resp.json()
+      this.logger?.debug?.(`[${id}] OpenAPI response:`, result)
+      this.logger?.debug?.(`[${id}] Response status:`, resp.status, resp.statusText)
+      return result
+    }
+
+    throw new SwitchbotOperationError('No SwitchBot client available for setDeviceState', 'no_client')
+  }
+
+  async destroy(): Promise<void> {
+    if (this.client?.destroy) {
+      await this.client.destroy()
+    }
+    this.client = null
+  }
+}
+