@switchbot/homebridge-switchbot 5.0.0-beta.70 → 5.0.0-beta.72

package/src/settings.ts

@@ -1,358 +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[]
-  irdevices?: irDevicesConfig[]
-  allowInvalidCharacters?: boolean
-  // When true, devices declared in config.options.devices that are not
-  // discovered via the SwitchBot OpenAPI will still be included (config-only
-  // devices). Default: false.
-  allowConfigOnlyDevices?: boolean
-  /**
-   * When true, previously-registered accessories for devices that are no
-   * longer discovered or configured will be kept on the bridge. Default: false.
-   * When false (default), stale accessories are removed automatically.
-   */
-  keepStaleAccessories?: boolean
-  mqttURL?: string
-  mqttOptions?: IClientOptions
-  mqttPubOptions?: IClientOptions
-  BLE?: boolean
-  discoverBLE?: boolean
-  disableLogsforBLE?: boolean
-  disableLogsforOpenAPI?: boolean
-  hostname?: string
-  webhookURL?: string
-  /**
-   * When true, enables webhook support for all devices by default.
-   * Individual devices can override this with their own webhook setting.
-   * Requires webhookURL to be configured.
-   */
-  webhook?: boolean
-  maxRetries?: number
-  delayBetweenRetries?: number
-  refreshRate?: number
-  updateRate?: number
-  pushRate?: number
-  logging?: string
-  /**
-   * Maximum number of SwitchBot OpenAPI requests allowed per day.
-   * Defaults to 10,000 if not specified.
-   */
-  dailyApiLimit?: number
-  /**
-   * Number of daily API requests reserved for user-initiated commands.
-   * When remaining budget falls below this reserve, background polling and discovery
-   * are paused until the daily counter resets. Defaults to 1,000.
-   */
-  dailyApiReserveForCommands?: number
-  /**
-   * When true, the plugin will completely stop background polling/discovery
-   * once the remaining daily budget reaches the reserve (webhook-only mode).
-   * When false, polling continues until the hard daily limit is reached.
-   * Default: false.
-   */
-  webhookOnlyOnReserve?: boolean
-  /**
-   * When true, reset the daily API request counter at LOCAL midnight (system timezone).
-   * When false (default), reset at UTC midnight. Default: false.
-   */
-  dailyApiResetAtLocalMidnight?: boolean
-  /**
-   * When true, resets the daily API request counter to zero. This is useful for testing purposes.
-   */
-  resetDailyApiCounter?: boolean
-  /**
-   * When set, configures the batch refresh rate (in milliseconds) for Matter devices.  Default: 5000 ms.
-   */
-  matterBatchRefreshRate?: number
-  /**
-   * When true, enables batch processing for Matter devices.  Default: false.
-   */
-  matterBatchConcurrency?: number
-  /**
-   * When true, enables batch processing for Matter devices. Default: false.
-   */
-  matterBatchEnabled?: boolean
-  /**
-   * When set, adds a random delay (jitter) to batch requests to avoid thundering herd problems.
-   */
-  matterBatchJitter?: number
-  newFeatureEnabled?: boolean
-};
-
-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
-  /**
-   * When true, applies this device's configuration to all other devices
-   * of the same deviceType/configDeviceType (e.g., all Humidifiers).
-   * Specific per-device settings will override these template settings.
-   */
-  applyToAllDevicesOfType?: 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
-  /**
-   * When true (Humidifier2 only), exposes a Switch service in HomeKit
-   * to trigger the built-in Drying Filter mode via OpenAPI (setMode 8).
-   */
-  activate_dryingfilter?: boolean
-};
-
-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' | 'Smart Lock Ultra'
-  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
-  /**
-   * When true, applies this IR device's configuration to all other IR devices
-   * of the same remoteType/configRemoteType (e.g., all IR Fans).
-   * Specific per-device settings will override these template settings.
-   */
-  applyToAllDevicesOfType?: boolean
-  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,266 @@
+import type { SwitchBotPluginConfig } from './settings.js'
+
+export interface ISwitchBotClient {
+  init(): Promise<void>
+  getDevice(id: string): Promise<any>
+  destroy(): Promise<void>
+}
+
+// Adapter that tries to use the node-switchbot v4 hybrid API when available.
+export class SwitchBotClient implements ISwitchBotClient {
+  private cfg: SwitchBotPluginConfig
+  private client: any | null = null
+  private baseUrl = 'https://api.switch-bot.com/v1.0'
+  // configurable network options
+  private requestTimeout = 5000
+  private maxRetries = 2
+  private baseBackoffMs = 100
+  private maxBackoffMs = 2000
+  private backoffFactor = 2
+  private jitter = true
+  // per-device write debounce (ms). 0 = disabled. Configurable via plugin options.
+  // Default enabled to coalesce rapid writes and prevent command floods.
+  private writeDebounceMs = 100
+  // structured logger (expects info/warn/error/debug); defaults to console
+  private logger: any
+  // per-device retry tracking
+  private perDeviceRetries: Map<string, number> = new Map()
+  private perDeviceMaxRetries = 3
+  // per-device cooldown after exceeding retries (ms)
+  private perDeviceCooldownMs = 60_000
+  private perDeviceCooldownUntil: Map<string, number> = 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)?.perDeviceMaxRetries === 'number') this.perDeviceMaxRetries = (cfg as any).perDeviceMaxRetries
+    if (typeof (cfg as any)?.baseBackoffMs === 'number') this.baseBackoffMs = (cfg as any).baseBackoffMs
+    if (typeof (cfg as any)?.maxBackoffMs === 'number') this.maxBackoffMs = (cfg as any).maxBackoffMs
+    if (typeof (cfg as any)?.backoffFactor === 'number') this.backoffFactor = (cfg as any).backoffFactor
+    if (typeof (cfg as any)?.jitter === 'boolean') this.jitter = (cfg as any).jitter
+    if (typeof (cfg as any)?.perDeviceCooldownMs === 'number') this.perDeviceCooldownMs = (cfg as any).perDeviceCooldownMs
+    if (typeof (cfg as any)?.writeDebounceMs === 'number') this.writeDebounceMs = (cfg as any).writeDebounceMs
+  }
+
+  // pending writes coalescing: deviceId -> { timer, body, resolvers }
+  private pendingWrites: Map<string, { timer: any; body: any; resolvers: Array<{ resolve: (v:any)=>void; reject: (e:any)=>void }>; }> = new Map()
+
+  async init(): Promise<void> {
+    // Try to dynamically import the new node-switchbot package. If it exposes
+    // a hybrid client we will use it. Otherwise the consumer can implement
+    // OpenAPI fallback logic here.
+    try {
+      const mod = await import('node-switchbot')
+      // The new library may export a default or named client. Try common names.
+      const m: any = mod as any
+      this.client = m?.default ?? m?.SwitchBot ?? m
+      if (typeof this.client === 'function') {
+        // some builds export a constructor
+        this.client = new this.client({ token: this.cfg.openApiToken })
+      }
+    } catch (e) {
+      // If import fails, leave client null and rely on OpenAPI code paths later.
+      this.logger?.warn?.('node-switchbot import failed; falling back to OpenAPI when token available')
+      this.client = null
+    }
+  }
+
+  private async fetchWithTimeoutAndRetry(url: string, opts: any = {}, timeoutMs?: number, retries?: number, deviceId?: string) {
+    const to = typeof timeoutMs === 'number' ? timeoutMs : this.requestTimeout
+    const max = typeof retries === 'number' ? retries : this.maxRetries
+
+    // Check per-device cooldown
+    if (deviceId) {
+      const until = this.perDeviceCooldownUntil.get(deviceId) ?? 0
+      if (Date.now() < until) {
+        const ms = until - Date.now()
+        this.logger?.warn?.('device in cooldown, aborting fetch', { deviceId, cooldownMs: ms })
+        throw new Error(`device ${deviceId} in cooldown for ${ms}ms`)
+      }
+    }
+
+    let attempt = 0
+    while (true) {
+      attempt += 1
+      // AbortController-based timeout
+      const controller = new AbortController()
+      const timer = setTimeout(() => controller.abort(), to)
+      try {
+        this.logger?.debug?.('fetch', { url, attempt, deviceId })
+        const fetchOpts = Object.assign({}, opts)
+        try {
+          Object.defineProperty(fetchOpts, 'signal', { value: controller.signal, enumerable: false, configurable: true })
+        } catch (_e) {
+          // ignore environments where defineProperty may fail
+        }
+        const resp = await fetch(url, fetchOpts)
+        clearTimeout(timer)
+
+        // helper to safely read response body when available
+        const safeReadBody = async (r: any) => {
+          try {
+            if (!r) return ''
+            if (typeof r.text === 'function') return await r.text()
+            if (typeof r.json === 'function') {
+              const j = await r.json().catch(() => null)
+              return j ? JSON.stringify(j) : ''
+            }
+            return String(r)
+          } catch (_e) {
+            return ''
+          }
+        }
+
+        // Some tests/mocks provide response-like objects without numeric `status`.
+        // In those cases attempt to parse the body and return a Response-like
+        // object so callers (resp.json()) continue to work instead of forcing
+        // a retry path.
+        if (typeof (resp as any).status !== 'number') {
+          const bodyStr = await safeReadBody(resp)
+          try {
+            const parsed = bodyStr ? JSON.parse(bodyStr) : {}
+            if (deviceId) this.perDeviceRetries.set(deviceId, 0)
+            return { ok: true, status: 200, json: async () => parsed }
+          } catch (_e) {
+            if (deviceId) this.perDeviceRetries.set(deviceId, 0)
+            return { ok: true, status: 200, json: async () => ({ body: bodyStr }) }
+          }
+        }
+
+        // classify response
+        if (resp.ok) {
+          if (deviceId) this.perDeviceRetries.set(deviceId, 0)
+          return resp
+        }
+
+        // Do not retry on client errors (4xx), except 429 (rate limit)
+        if (resp.status >= 400 && resp.status < 500 && resp.status !== 429) {
+          const body = await safeReadBody(resp)
+          this.logger?.error?.('fetch non-retriable response', { url, status: resp.status, body })
+          const err = new Error(`HTTP ${resp.status}`)
+          ;(err as any).status = resp.status
+          throw err
+        }
+
+        // server error / rate limit: treat as retriable
+        const body = await safeReadBody(resp)
+        this.logger?.warn?.('fetch retriable response', { url, status: resp.status, body })
+        // throw to enter retry/catch logic below and apply backoff
+        throw new Error(`retriable response: ${resp.status || 'unknown'}`)
+      } catch (err: any) {
+        clearTimeout(timer)
+        const isAbort = err?.name === 'AbortError' || err?.message === 'The user aborted a request.' || err?.message === 'timeout'
+        const reason = isAbort ? 'timeout' : err?.message ?? String(err)
+        this.logger?.warn?.('fetch failed', { url, attempt, deviceId, reason })
+
+        // per-device retry guard
+        if (deviceId) {
+          const prev = this.perDeviceRetries.get(deviceId) ?? 0
+          const next = prev + 1
+          this.perDeviceRetries.set(deviceId, next)
+          if (next > this.perDeviceMaxRetries) {
+            this.logger?.error?.('per-device retry limit exceeded, entering cooldown', { deviceId, attempts: next })
+            this.perDeviceCooldownUntil.set(deviceId, Date.now() + this.perDeviceCooldownMs)
+            throw new Error(`per-device retry limit exceeded for ${deviceId}`)
+          }
+        }
+
+        if (attempt > max) throw err
+
+        // exponential backoff with optional jitter
+        let backoff = Math.min(this.baseBackoffMs * Math.pow(this.backoffFactor, attempt - 1), this.maxBackoffMs)
+        if (this.jitter) {
+          const jitterVal = Math.floor(Math.random() * backoff)
+          backoff = Math.floor(backoff / 2) + jitterVal
+        }
+        this.logger?.debug?.('backoff before retry', { url, attempt, backoff })
+        await new Promise((r) => setTimeout(r, backoff))
+      }
+    }
+  }
+
+  async getDevice(id: string): Promise<any> {
+    if (this.client && typeof this.client.getDevice === 'function') {
+      return this.client.getDevice(id)
+    }
+    // Fallback: call OpenAPI via HTTP using token if available.
+    if (this.cfg.openApiToken) {
+      const url = `${this.baseUrl}/devices/${id}`
+      const opts = { headers: { Authorization: this.cfg.openApiToken } }
+      const resp = await this.fetchWithTimeoutAndRetry(url, opts, undefined, undefined, id)
+      return resp.json()
+    }
+    throw new Error('No SwitchBot client available')
+  }
+
+  async setDeviceState(id: string, body: any): Promise<any> {
+    // If debounce is disabled do a direct write path
+    if (!this.writeDebounceMs || this.writeDebounceMs <= 0) {
+      return this._doSetDeviceState(id, body)
+    }
+
+    // Coalesce writes per-device within debounce window. Last write wins.
+    return new Promise((resolve, reject) => {
+      const existing = this.pendingWrites.get(id)
+      if (existing) {
+        existing.body = body
+        existing.resolvers.push({ resolve, reject })
+        // timer already scheduled
+        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) {
+          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
+    if (this.client && typeof this.client.setDeviceState === 'function') {
+      return this.client.setDeviceState(id, body)
+    }
+
+    // Try generic command methods
+    if (this.client && typeof this.client.sendCommand === 'function') {
+      return this.client.sendCommand(id, body)
+    }
+
+    // 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, undefined, undefined, id)
+      return resp.json()
+    }
+
+    throw new Error('No SwitchBot client available for setDeviceState')
+  }
+
+  async destroy(): Promise<void> {
+    if (this.client && typeof this.client.destroy === 'function') {
+      await this.client.destroy()
+    }
+    this.client = null
+  }
+}