@switchbot/homebridge-switchbot 5.0.0-beta.15 → 5.0.0-beta.150

package/src/settings.ts

@@ -1,283 +1,20 @@
-/* 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
+  enableBLE?: boolean // Enable or disable BLE support
+  // 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,
+  enableBLE: 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,181 @@
+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>
+}
+
+/**
+ * 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: SwitchBot | null = null
+  private writeDebounceMs = 100
+  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 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
+    }
+  }
+
+  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: this.cfg.enableBLE !== false, // Use config value, default true
+        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
+    }
+  }
+
+  async getDevice(id: string): Promise<any> {
+    if (this.client) {
+      try {
+        const devices = await this.client.discover()
+        return devices.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
+        }
+      }
+    }
+    throw new SwitchbotOperationError('No SwitchBot client available', 'no_client')
+  }
+
+  async getDevices(): Promise<any[]> {
+    if (this.client) {
+      try {
+        return await this.client.discover()
+      } catch (e) {
+        this.logger?.warn?.('Client getDevices failed:', e)
+        throw e
+      }
+    }
+    throw new SwitchbotOperationError('No SwitchBot client available', 'no_client')
+  }
+
+  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> {
+    if (!this.client) {
+      throw new SwitchbotOperationError('No SwitchBot client available for setDeviceState', 'no_client')
+    }
+    try {
+      const devices = await this.client.discover()
+      const device = devices.find((d: any) => d.id === 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
+      }
+    }
+  }
+
+  async destroy(): Promise<void> {
+    if (this.client?.cleanup) {
+      await this.client.cleanup()
+    }
+    this.client = null
+  }
+}