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

package/src/devices/genericDevice.ts

@@ -1,12 +1,189 @@
+// Utility: Validate BLE response length before parsing
 /* eslint-disable style/max-statements-per-line, unused-imports/no-unused-vars */
+
+/**
+ * Status Update Strategy for BLE and OpenAPI
+ *
+ * BLE (Bluetooth Low Energy):
+ * - Primary: Subscribes to device notifications for real-time state updates using _subscribeBLENotifications().
+ * - Fallback: (Recommended) Optionally, a low-frequency polling timer (e.g., every 5–10 minutes) can call getState() to recover from missed notifications or connection loss.
+ *   - This ensures state stays in sync even if notifications are unreliable or the device reconnects.
+ *   - Polling should be infrequent to avoid battery drain and BLE congestion.
+ *
+ * BLE Polling Options (config & per-device):
+ * - blePollingEnabled (boolean): Enable/disable BLE polling fallback (default: true).
+ * - blePollIntervalMs (integer): Polling interval in ms (default: 600000, min: 60000).
+ *   - These can be set globally in config or overridden per device.
+ *   - Setting a lower interval increases update frequency but may drain battery faster.
+ *   - Setting a higher interval reduces battery impact but may delay state recovery.
+ *
+ * OpenAPI (Cloud):
+ * - Uses periodic polling to fetch device status at a configurable interval (default: 300 seconds, can be set per device or platform).
+ * - Platform supports batched refresh (matterBatchEnabled, matterBatchRefreshRate, etc.) and per-device refreshRate overrides.
+ * - Rate limiting:
+ *   - Default daily limit: 10,000 OpenAPI requests (configurable via options.dailyApiLimit).
+ *   - Reserve: 1,000 requests for user commands (options.dailyApiReserveForCommands).
+ *   - When the remaining budget reaches the reserve, background polling/discovery pauses, but user commands and webhooks continue.
+ *   - Counter resets at local or UTC midnight (options.dailyApiResetLocalMidnight).
+ *
+ * Best Practices:
+ * - BLE: Use notifications for instant updates, add periodic polling as a safety net.
+ * - OpenAPI: Tune polling intervals to balance freshness and rate limit budget.
+ * - Both: Document and expose polling intervals and rate limit settings in config.
+ *
+ * See README.md and docs for more details.
+ */
 import type { SwitchBotPluginConfig } from '../settings.js'
 
+import { Buffer } from 'node:buffer'
+
 import { MATTER_ATTRIBUTE_IDS, MATTER_CLUSTER_IDS } from '../utils.js'
 import { DeviceBase } from './deviceBase.js'
 
+function validateBLEResponseLength(buf: Buffer | Uint8Array | any[], expected: number, context = '', log: import('homebridge').Logger): boolean {
+  if (!buf || typeof buf.length !== 'number' || buf.length !== expected) {
+    log.warn(`[BLE] Invalid response length${context ? ` for ${context}` : ''}: expected ${expected}, got ${buf?.length}`)
+    return false
+  }
+  return true
+}
+
+// BLE notification handling: per-command notification futures and unsolicited notification logging
+const BLE_NOTIFICATION_HANDLERS = new Map<string, (payload: Buffer) => void>()
+
+// Module-scope regex pattern to avoid recompilation
+const HEX_COLOR_REGEX = /^#?[0-9A-F]{6}$/i
+
 export class GenericDevice extends DeviceBase {
+  protected log: import('homebridge').Logger
+  private _blePollTimer: NodeJS.Timeout | null = null
+  private _blePollIntervalMs: number
+  private _blePollingEnabled: boolean
+
   constructor(opts: any, cfg: SwitchBotPluginConfig) {
     super(opts, cfg)
+    // Require logger from opts or cfg
+    this.log = opts?.log || cfg?.log
+    if (!this.log) {
+      throw new Error('Device requires a logger (Homebridge logger) in opts or cfg')
+    }
+    // If BLE encryptionKey/keyId provided, set on node-switchbot device instance if possible
+    if (opts.encryptionKey && this.client && typeof this.client.devices?.get === 'function') {
+      try {
+        const dev = this.client.devices.get(opts.id)
+        if (dev && typeof dev.setKey === 'function') {
+          dev.setKey({
+            encryptionKey: opts.encryptionKey,
+            keyId: opts.keyId || undefined,
+          })
+        }
+      } catch (e) {
+        // ignore if device not found or setKey not available
+      }
+    }
+    // BLE polling config: allow override via opts.blePollingEnabled/blePollIntervalMs or cfg.blePollingEnabled/blePollIntervalMs
+    this._blePollingEnabled = opts?.blePollingEnabled ?? cfg?.blePollingEnabled ?? true
+    let pollMs = opts?.blePollIntervalMs ?? cfg?.blePollIntervalMs ?? 10 * 60 * 1000 // default: 10 min
+    if (typeof pollMs !== 'number' || Number.isNaN(pollMs) || pollMs < 60000) {
+      this.log.warn(`[BLE] Invalid blePollIntervalMs (${pollMs}), using minimum 60000ms`)
+      pollMs = 60000
+    }
+    this._blePollIntervalMs = pollMs
+    // Subscribe to BLE notifications if supported (node-switchbot v4+)
+    this._subscribeBLENotifications()
+    // Start BLE polling fallback if enabled
+    if (this._blePollingEnabled) {
+      this._startBlePolling()
+    }
+  }
+
+  /**
+   * Start periodic BLE polling as a fallback to notifications.
+   */
+  private _startBlePolling() {
+    if (this._blePollTimer) {
+      clearInterval(this._blePollTimer)
+    }
+    this._blePollTimer = setInterval(async () => {
+      try {
+        this.log.debug(`[BLE] Polling getState() for device ${this.opts.id}`)
+        await this.getState()
+      } catch (e) {
+        this.log.debug(`[BLE] Polling getState() failed for device ${this.opts.id}:`, (e as Error)?.message)
+      }
+    }, this._blePollIntervalMs)
+  }
+
+  /**
+   * Clean up BLE polling timer on destroy.
+   */
+  async destroy(): Promise<void> {
+    if (this._blePollTimer) {
+      clearInterval(this._blePollTimer)
+      this._blePollTimer = null
+    }
+    // Only call super.destroy if DeviceBase.prototype.destroy is a function and not this method itself
+    const baseProto = Object.getPrototypeOf(GenericDevice.prototype)
+    if (typeof baseProto.destroy === 'function' && baseProto.destroy !== GenericDevice.prototype.destroy) {
+      await super.destroy()
+    }
+  }
+
+  /**
+   * Subscribe to BLE notifications for this device (if supported by node-switchbot)
+   * Logs unsolicited notifications and enables per-command notification futures.
+   */
+  private async _subscribeBLENotifications() {
+    if (!this.client || typeof this.client.devices?.get !== 'function') { return }
+    const dev = this.client.devices.get(this.opts.id)
+    if (!dev || typeof dev.mac !== 'string' || !dev.mac) { return }
+    // Only subscribe once per device
+    if (BLE_NOTIFICATION_HANDLERS.has(dev.mac)) { return }
+    if (typeof dev.subscribeNotifications === 'function') {
+      const handler = (payload: Buffer) => {
+        // If a per-command notification future is waiting, let node-switchbot handle it
+        // Otherwise, log unsolicited notification
+        if (payload && payload.length > 0) {
+          // Unsolicited notification logging
+          // (node-switchbot will resolve per-command futures internally)
+          this.log.debug(`[BLE] Unsolicited notification from ${dev.mac}: ${payload.toString('hex')}`)
+        }
+      }
+      try {
+        // Subscribe and remember handler for possible cleanup
+        await dev.subscribeNotifications(handler)
+        BLE_NOTIFICATION_HANDLERS.set(dev.mac, handler)
+      } catch (e) {
+        // ignore if subscription fails
+      }
+    }
+  }
+
+  /**
+   * Await a BLE notification for this device (for advanced use in subclasses)
+   * Returns the notification payload or throws on timeout.
+   */
+  protected async _awaitBLENotification(timeoutMs = 5000): Promise<Buffer> {
+    if (!this.client || typeof this.client.devices?.get !== 'function') { throw new Error('No BLE client/device') }
+    const dev = this.client.devices.get(this.opts.id)
+    if (!dev || typeof dev.mac !== 'string' || !dev.mac) { throw new Error('No BLE MAC for device') }
+    if (typeof dev.bleConnection?.sendCommand !== 'function') { throw new TypeError('BLE connection does not support sendCommand') }
+    // This is a low-level utility; in most cases, node-switchbot handles notification futures for commands
+    // Here, we expose a direct await for advanced use
+    return new Promise<Buffer>((resolve, reject) => {
+      let timer: NodeJS.Timeout | undefined
+      const handler = (payload: Buffer) => {
+        clearTimeout(timer)
+        dev.bleConnection?.unsubscribeNotifications(dev.mac, handler)
+        resolve(payload)
+      }
+      dev.bleConnection?.subscribeNotifications(dev.mac, handler).then(() => {
+        timer = setTimeout(() => {
+          dev.bleConnection?.unsubscribeNotifications(dev.mac, handler)
+          reject(new Error('BLE notification timeout'))
+        }, timeoutMs)
+      }).catch(reject)
+    })
   }
 
   async getState(): Promise<any> {
@@ -14,6 +191,13 @@ export class GenericDevice extends DeviceBase {
     if (this.client && typeof this.client.getDevice === 'function') {
       try {
         const raw = await this.client.getDevice(this.opts.id)
+        // If this is a BLE buffer/array, validate length (common BLE status: 12 bytes, but may vary by device)
+        if (raw && (raw instanceof Buffer || Array.isArray(raw) || raw instanceof Uint8Array)) {
+          // Default to 12, override per device if needed
+          if (!validateBLEResponseLength(raw, 12, this.opts.type, this.log)) {
+            return { id: this.opts.id, type: this.opts.type, error: 'invalid_ble_response_length', raw }
+          }
+        }
         // Normalize common response shapes
         try {
           const device = raw?.body ?? raw
@@ -127,62 +311,163 @@ export class GenericDevice extends DeviceBase {
   // platform can construct a Matter accessory representation when
   // Homebridge Matter APIs are available. Device subclasses may override
   // this to provide Matter-specific clusters/attributes if desired.
-  createMatterAccessory(api: any): any {
-    const hapDesc = this.createHAPAccessory(api)
-
+  async createMatterAccessory(api: any): Promise<any> {
+    // Dynamically detect features from getState()
+    const state = await this.getState()
     const clusters: any[] = []
-    const mapCharacteristic = (charName: string) => {
-      switch (charName) {
-        case 'On':
-          return { attr: 'onOff', get: async () => { const s = await this.getState(); return !!(s && (s.on === true || s.state === 'on' || s.power === 'on')) }, set: async (v: any) => this.setState({ on: !!v }) }
-        case 'Brightness':
-          return { attr: 'brightness', get: async () => { const s = await this.getState(); return typeof s.brightness === 'number' ? s.brightness : 100 }, set: async (v: any) => this.setState({ brightness: Number(v) }) }
-        case 'Hue':
-          return { attr: 'colorHue', get: async () => { const s = await this.getState(); return typeof s.hue === 'number' ? s.hue : 0 }, set: async (v: any) => this.setState({ hue: Number(v) }) }
-        case 'Saturation':
-          return { attr: 'colorSaturation', get: async () => { const s = await this.getState(); return typeof s.saturation === 'number' ? s.saturation : 0 }, set: async (v: any) => this.setState({ saturation: Number(v) }) }
-        case 'ColorTemperature':
-          return { attr: 'colorTemperature', get: async () => {
-            const s = await this.getState(); if (typeof s.colorTemperature === 'number') { return s.colorTemperature } if (typeof s.kelvin === 'number') { return Math.round(1000000 / s.kelvin) } return 400
-          }, set: async (v: any) => this.setState({ colorTemperature: Number(v) }) }
-        case 'RotationSpeed':
-          return { attr: 'rotationSpeed', get: async () => { const s = await this.getState(); return typeof s.speed === 'number' ? s.speed : 0 }, set: async (v: any) => this.setState({ speed: Number(v) }) }
-        case 'TargetPosition':
-        case 'CurrentPosition':
-          return { attr: 'position', get: async () => { const s = await this.getState(); return typeof s.position === 'number' ? s.position : 0 }, set: async (v: any) => this.setState({ position: Number(v) }) }
-        case 'LockCurrentState':
-        case 'LockTargetState':
-          return { attr: 'locked', get: async () => { const s = await this.getState(); return !!(s && s.locked) }, set: async (v: any) => this.setState({ locked: !!v }) }
-        case 'MotionDetected':
-          return { attr: 'motionDetected', get: async () => { const s = await this.getState(); return !!(s && s.motion === true) }, set: undefined }
-        case 'ContactSensorState':
-          return { attr: 'contact', get: async () => { const s = await this.getState(); return s && s.open ? 1 : 0 }, set: undefined }
-        default:
-          return null
-      }
+
+    // On/Off (Switch/Plug/Generic)
+    if ('on' in state || 'power' in state || 'state' in state) {
+      clusters.push({
+        type: 'OnOff',
+        clusterId: MATTER_CLUSTER_IDS.OnOff,
+        attributes: {
+          onOff: { read: async () => !!(await this.getState()).on || (await this.getState()).power === 'on' || (await this.getState()).state === 'on', write: async (v: any) => this.setState({ on: !!v }) },
+          [MATTER_ATTRIBUTE_IDS.OnOff.OnOff]: { read: async () => !!(await this.getState()).on || (await this.getState()).power === 'on' || (await this.getState()).state === 'on', write: async (v: any) => this.setState({ on: !!v }) },
+        },
+      })
     }
 
-    for (const s of (hapDesc.services || [])) {
-      const clusterType = (() => {
-        switch ((s.type || '').toLowerCase()) {
-          case 'lightbulb': return 'OnOff/LevelControl/ColorControl'
-          case 'fan': return 'FanControl'
-          case 'windowscovering': return 'Shade'
-          case 'motionsensor': return 'OccupancySensing'
-          case 'contactsensor': return 'DoorState'
-          case 'lockmechanism': return 'DoorLock'
-          case 'switch': return 'OnOff'
-          default: return s.type || 'Generic'
-        }
-      })()
+    // Brightness (Light)
+    if ('brightness' in state) {
+      clusters.push({
+        type: 'LevelControl',
+        clusterId: MATTER_CLUSTER_IDS.LevelControl,
+        attributes: {
+          currentLevel: { read: async () => (await this.getState()).brightness ?? 100, write: async (v: any) => this.setState({ brightness: Number(v) }) },
+          [MATTER_ATTRIBUTE_IDS.LevelControl.CurrentLevel]: { read: async () => (await this.getState()).brightness ?? 100, write: async (v: any) => this.setState({ brightness: Number(v) }) },
+        },
+      })
+    }
 
-      const attributes: Record<string, any> = {}
-      for (const [charName] of Object.entries(s.characteristics || {})) {
-        const mapped = mapCharacteristic(charName)
-        if (mapped) { attributes[mapped.attr] = { read: typeof mapped.get === 'function' ? mapped.get : undefined, write: typeof mapped.set === 'function' ? mapped.set : undefined } }
-      }
+    // Color (Light)
+    if ('hue' in state && 'saturation' in state) {
+      clusters.push({
+        type: 'ColorControl',
+        clusterId: MATTER_CLUSTER_IDS.ColorControl,
+        attributes: {
+          colorMode: { read: async () => 0 },
+          colorHue: { read: async () => (await this.getState()).hue ?? 0, write: async (v: any) => this.setState({ hue: Number(v) }) },
+          [MATTER_ATTRIBUTE_IDS.ColorControl.CurrentHue]: { read: async () => (await this.getState()).hue ?? 0, write: async (v: any) => this.setState({ hue: Number(v) }) },
+          colorSaturation: { read: async () => (await this.getState()).saturation ?? 0, write: async (v: any) => this.setState({ saturation: Number(v) }) },
+          [MATTER_ATTRIBUTE_IDS.ColorControl.CurrentSaturation]: { read: async () => (await this.getState()).saturation ?? 0, write: async (v: any) => this.setState({ saturation: Number(v) }) },
+          ...(typeof state.colorTemperature === 'number' || typeof state.kelvin === 'number'
+            ? {
+                colorTemperature: { read: async () => typeof (await this.getState()).colorTemperature === 'number' ? (await this.getState()).colorTemperature : Math.round(1000000 / ((await this.getState()).kelvin ?? 2500)), write: async (v: any) => this.setState({ colorTemperature: Number(v) }) },
+                [MATTER_ATTRIBUTE_IDS.ColorControl.ColorTemperatureMireds]: { read: async () => typeof (await this.getState()).colorTemperature === 'number' ? (await this.getState()).colorTemperature : Math.round(1000000 / ((await this.getState()).kelvin ?? 2500)), write: async (v: any) => this.setState({ colorTemperature: Number(v) }) },
+              }
+            : {}),
+        },
+      })
+    }
+
+    // Temperature sensor
+    if ('temperature' in state) {
+      clusters.push({
+        type: 'TemperatureMeasurement',
+        // No clusterId, not present in MATTER_CLUSTER_IDS
+        attributes: {
+          measuredValue: { read: async () => (await this.getState()).temperature ?? 0 },
+        },
+      })
+    }
+
+    // Humidity sensor
+    if ('humidity' in state) {
+      clusters.push({
+        type: 'RelativeHumidityMeasurement',
+        clusterId: MATTER_CLUSTER_IDS.RelativeHumidityMeasurement,
+        attributes: {
+          measuredValue: { read: async () => (await this.getState()).humidity ?? 0 },
+        },
+      })
+    }
+
+    // CO2 sensor
+    if ('CO2' in state) {
+      clusters.push({
+        type: 'AirQuality',
+        attributes: {
+          CO2: { read: async () => (await this.getState()).CO2 ?? 0 },
+        },
+      })
+    }
+
+    // Lock
+    if ('lockState' in state || 'locked' in state) {
+      clusters.push({
+        type: 'DoorLock',
+        clusterId: MATTER_CLUSTER_IDS.DoorLock,
+        attributes: {
+          lockState: { read: async () => (await this.getState()).lockState ?? (await this.getState()).locked ? 1 : 0, write: async (v: any) => this.setState({ locked: !!v }) },
+        },
+      })
+    }
+
+    // Motion sensor
+    if ('moveDetected' in state || 'motion' in state) {
+      clusters.push({
+        type: 'OccupancySensing',
+        // No clusterId, not present in MATTER_CLUSTER_IDS
+        attributes: {
+          occupancy: { read: async () => (await this.getState()).moveDetected === true || (await this.getState()).motion === true ? 1 : 0 },
+        },
+      })
+    }
+
+    // Contact sensor
+    if ('openState' in state || 'contact' in state || 'open' in state) {
+      clusters.push({
+        type: 'BooleanState',
+        // No clusterId, not present in MATTER_CLUSTER_IDS
+        attributes: {
+          stateValue: { read: async () => (await this.getState()).openState === 'open' || (await this.getState()).open === true ? 1 : 0 },
+        },
+      })
+    }
+
+    // Leak sensor
+    if ('leak' in state || 'status' in state) {
+      clusters.push({
+        type: 'LeakSensor',
+        attributes: {
+          leakDetected: { read: async () => (await this.getState()).leak === true || (await this.getState()).status === 1 ? 1 : 0 },
+        },
+      })
+    }
+
+    // Energy monitoring (Plug)
+    if ('voltage' in state || 'power' in state || 'electricCurrent' in state) {
+      clusters.push({
+        type: 'ElectricalMeasurement',
+        // No clusterId, not present in MATTER_CLUSTER_IDS
+        attributes: {
+          voltage: { read: async () => (await this.getState()).voltage ?? 0 },
+          power: { read: async () => (await this.getState()).power ?? 0 },
+          electricCurrent: { read: async () => (await this.getState()).electricCurrent ?? 0 },
+        },
+      })
+    }
+
+    // Fan
+    if ('speed' in state || 'fanSpeed' in state) {
+      clusters.push({
+        type: 'FanControl',
+        clusterId: MATTER_CLUSTER_IDS.FanControl,
+        attributes: {
+          speedCurrent: { read: async () => (await this.getState()).speed ?? (await this.getState()).fanSpeed ?? 0, write: async (v: any) => this.setState({ speed: Number(v) }) },
+        },
+      })
+    }
 
-      clusters.push({ type: clusterType, attributes })
+    // Vacuum
+    if ('workingStatus' in state) {
+      clusters.push({
+        type: 'RobotVacuumCleaner',
+        attributes: {
+          workingStatus: { read: async () => (await this.getState()).workingStatus ?? 'StandBy' },
+        },
+      })
     }
 
     return {
@@ -225,25 +510,80 @@ export class CurtainDevice extends GenericDevice {
     }
   }
 
-  // Matter-specific descriptor for Curtain (Shade cluster)
-  createMatterAccessory(api: any): any {
+  // Matter-specific descriptor for Curtain (WindowCovering cluster) with new attributes
+  async createMatterAccessory(api: any): Promise<any> {
+    // Get current state for dynamic attributes
+    const state = await this.getState()
+    // Compose attributes for Matter WindowCovering cluster
+    const attributes: Record<string, any> = {
+      currentPositionLiftPercent100ths: {
+        read: async () => {
+          const s = await this.getState()
+          return typeof s.position === 'number' ? Math.round(s.position * 100) : 0
+        },
+        write: undefined,
+      },
+      targetPositionLiftPercent100ths: {
+        read: async () => {
+          const s = await this.getState()
+          return typeof s.position === 'number' ? Math.round(s.position * 100) : 0
+        },
+        write: async (v: any) => this.setState({ position: Math.round(Number(v) / 100) }),
+      },
+      operationalStatus: {
+        read: async () => state.operationalStatus ?? { global: 0, lift: 0, tilt: 0 },
+        write: undefined,
+      },
+      endProductType: {
+        read: async () => state.endProductType ?? 0,
+        write: undefined,
+      },
+      configStatus: {
+        read: async () => state.configStatus ?? {
+          operational: true,
+          onlineReserved: true,
+          liftMovementReversed: false,
+          liftPositionAware: true,
+          tiltPositionAware: false,
+          liftEncoderControlled: true,
+          tiltEncoderControlled: false,
+        },
+        write: undefined,
+      },
+    }
+    // If tilt is supported, add tilt attributes
+    if (typeof state.tilt === 'number') {
+      attributes.currentPositionTiltPercent100ths = {
+        read: async () => {
+          const s = await this.getState()
+          return typeof s.tilt === 'number' ? Math.round(s.tilt * 100) : 0
+        },
+        write: undefined,
+      }
+      attributes.targetPositionTiltPercent100ths = {
+        read: async () => {
+          const s = await this.getState()
+          return typeof s.tilt === 'number' ? Math.round(s.tilt * 100) : 0
+        },
+        write: async (v: any) => this.setState({ tilt: Math.round(Number(v) / 100) }),
+      }
+    }
+    const windowCoveringCluster = {
+      type: 'WindowCovering',
+      clusterId: MATTER_CLUSTER_IDS.WindowCovering,
+      attributes,
+    }
+    // Provide both array and named property for clusters for compatibility with test expectations
+    const clustersArr: any[] = [windowCoveringCluster]
+    const clusters: any = [...clustersArr]
+    // Always set clusters.windowCovering to the WindowCovering cluster by clusterId
+    const foundWC = clustersArr.find((c: any) => c && c.clusterId === MATTER_CLUSTER_IDS.WindowCovering)
+    clusters.windowCovering = foundWC || null
     return {
       id: this.opts.id,
       name: this.opts.name ?? this.opts.type,
       protocol: 'matter',
-      clusters: [
-        {
-          // Shade cluster
-          type: 'Shade',
-          clusterId: MATTER_CLUSTER_IDS.WindowCovering,
-          attributes: {
-            currentPosition: { read: async () => { const s = await this.getState(); return typeof s.position === 'number' ? s.position : 0 }, write: undefined },
-            [MATTER_ATTRIBUTE_IDS.WindowCovering.CurrentPosition]: { read: async () => { const s = await this.getState(); return typeof s.position === 'number' ? s.position : 0 }, write: undefined },
-            targetPosition: { read: async () => { const s = await this.getState(); return typeof s.position === 'number' ? s.position : 0 }, write: async (v: any) => this.setState({ position: Number(v) }) },
-            [MATTER_ATTRIBUTE_IDS.WindowCovering.TargetPosition]: { read: async () => { const s = await this.getState(); return typeof s.position === 'number' ? s.position : 0 }, write: async (v: any) => this.setState({ position: Number(v) }) },
-          },
-        },
-      ],
+      clusters,
     }
   }
 }
@@ -384,7 +724,7 @@ export class LightDevice extends GenericDevice {
                 if (s && typeof s.hue === 'number') { return s.hue }
                 // try HSV from color hex
                 const hex = s?.color || s?.colorHex || s?.colour
-                if (typeof hex === 'string' && /^#?[0-9A-F]{6}$/i.test(hex)) {
+                if (typeof hex === 'string' && HEX_COLOR_REGEX.test(hex)) {
                   const h = (() => {
                     const hsl = (h: number, s: number, l: number) => ({ h, s, l })
                     // convert hex -> rgb -> hsv
@@ -420,7 +760,7 @@ export class LightDevice extends GenericDevice {
                 if (s && typeof s.saturation === 'number') { return s.saturation }
                 // if color hex is available, derive saturation from rgb
                 const hex = s?.color || s?.colorHex || s?.colour
-                if (typeof hex === 'string' && /^#?[0-9A-F]{6}$/i.test(hex)) {
+                if (typeof hex === 'string' && HEX_COLOR_REGEX.test(hex)) {
                   const cleaned = hex.replace('#', '')
                   const r = Number.parseInt(cleaned.substr(0, 2), 16) / 255
                   const g = Number.parseInt(cleaned.substr(2, 2), 16) / 255
@@ -537,6 +877,8 @@ export class LightDevice extends GenericDevice {
           type: 'ColorControl',
           clusterId: MATTER_CLUSTER_IDS.ColorControl,
           attributes: {
+            // Required colorMode attribute for Matter conformance (0 = currentHueAndSaturation)
+            colorMode: { read: async () => 0 },
             colorHue: { read: async () => { const s = await this.getState(); return typeof s.hue === 'number' ? s.hue : 0 }, write: async (v: any) => this.setState({ hue: Number(v) }) },
             [MATTER_ATTRIBUTE_IDS.ColorControl.CurrentHue]: { read: async () => { const s = await this.getState(); return typeof s.hue === 'number' ? s.hue : 0 }, write: async (v: any) => this.setState({ hue: Number(v) }) },
             colorSaturation: { read: async () => { const s = await this.getState(); return typeof s.saturation === 'number' ? s.saturation : 0 }, write: async (v: any) => this.setState({ saturation: Number(v) }) },
@@ -844,7 +1186,7 @@ export class HumidifierDevice extends GenericDevice {
 
 // Provide Matter descriptor for humidifier (humidity and on/off)
 export class HumidifierMatterDevice extends HumidifierDevice {
-  createMatterAccessory(api: any) {
+  async createMatterAccessory(api: any): Promise<any> {
     return {
       id: this.opts.id,
       name: this.opts.name ?? this.opts.type,

package/src/errors.js

@@ -0,0 +1,32 @@
+// Error classes for node-switchbot v4 compatibility
+// Always use local fallback classes for compatibility; upstream error classes are not guaranteed to exist
+const SwitchbotOperationError = class extends Error {
+    code;
+    cause;
+    constructor(message, code, cause) {
+        super(message);
+        this.name = 'SwitchbotOperationError';
+        this.code = code;
+        this.cause = cause;
+    }
+};
+const SwitchbotAuthenticationError = class extends Error {
+    code;
+    cause;
+    constructor(message, code, cause) {
+        super(message);
+        this.name = 'SwitchbotAuthenticationError';
+        this.code = code;
+        this.cause = cause;
+    }
+};
+const CharacteristicMissingError = class extends Error {
+    characteristic;
+    constructor(message, characteristic) {
+        super(message);
+        this.name = 'CharacteristicMissingError';
+        this.characteristic = characteristic;
+    }
+};
+export { CharacteristicMissingError, SwitchbotAuthenticationError, SwitchbotOperationError };
+//# sourceMappingURL=errors.js.map

package/src/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["errors.ts"],"names":[],"mappings":"AAAA,oDAAoD;AACpD,0GAA0G;AAE1G,MAAM,uBAAuB,GAAG,KAAM,SAAQ,KAAK;IACjD,IAAI,CAAS;IACb,KAAK,CAAQ;IACb,YAAY,OAAe,EAAE,IAAa,EAAE,KAAa;QACvD,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAA;QACrC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;IACpB,CAAC;CACF,CAAA;AAED,MAAM,4BAA4B,GAAG,KAAM,SAAQ,KAAK;IACtD,IAAI,CAAS;IACb,KAAK,CAAQ;IACb,YAAY,OAAe,EAAE,IAAa,EAAE,KAAa;QACvD,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,8BAA8B,CAAA;QAC1C,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;IACpB,CAAC;CACF,CAAA;AAED,MAAM,0BAA0B,GAAG,KAAM,SAAQ,KAAK;IACpD,cAAc,CAAQ;IACtB,YAAY,OAAe,EAAE,cAAsB;QACjD,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAA;QACxC,IAAI,CAAC,cAAc,GAAG,cAAc,CAAA;IACtC,CAAC;CACF,CAAA;AAED,OAAO,EAAE,0BAA0B,EAAE,4BAA4B,EAAE,uBAAuB,EAAE,CAAA"}

package/src/errors.ts

@@ -0,0 +1,35 @@
+// Error classes for node-switchbot v4 compatibility
+// Always use local fallback classes for compatibility; upstream error classes are not guaranteed to exist
+
+const SwitchbotOperationError = class extends Error {
+  code?: string
+  cause?: Error
+  constructor(message: string, code?: string, cause?: Error) {
+    super(message)
+    this.name = 'SwitchbotOperationError'
+    this.code = code
+    this.cause = cause
+  }
+}
+
+const SwitchbotAuthenticationError = class extends Error {
+  code?: string
+  cause?: Error
+  constructor(message: string, code?: string, cause?: Error) {
+    super(message)
+    this.name = 'SwitchbotAuthenticationError'
+    this.code = code
+    this.cause = cause
+  }
+}
+
+const CharacteristicMissingError = class extends Error {
+  characteristic: string
+  constructor(message: string, characteristic: string) {
+    super(message)
+    this.name = 'CharacteristicMissingError'
+    this.characteristic = characteristic
+  }
+}
+
+export { CharacteristicMissingError, SwitchbotAuthenticationError, SwitchbotOperationError }