@switchbot/homebridge-switchbot 5.0.0-beta.2 → 5.0.0-beta.21

package/src/platform-matter.unregister.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { SwitchBotMatterPlatform } from './platform-matter.js'
+import { formatDeviceIdAsMac } from './utils.js'
+
+describe('removeDisabledAccessories and unregister edge cases', () => {
+  it('clears resources and unregisters accessory even with invalid timer and non-MAC deviceId', async () => {
+    // Prepare API stub
+    const unregister = vi.fn()
+    const api: any = {
+      matter: {
+        uuid: { generate: (s: string) => `uuid-${s}` },
+        unregisterPlatformAccessories: unregister,
+      },
+      isMatterAvailable: () => true,
+      isMatterEnabled: () => true,
+      on: () => {},
+    }
+
+    const log: any = { info: vi.fn(), warn: vi.fn(), debug: vi.fn(), error: vi.fn(), success: vi.fn() }
+    const platform = new SwitchBotMatterPlatform(log as any, { enableOnOffLight: false } as any, api)
+
+    // Build a fake serialized accessory matching the generated UUID for OnOff Light
+    const uuid = api.matter.uuid.generate('matter-onoff-light')
+    const accessory: any = { uuid, displayName: 'OnOff Light', context: { deviceId: 'NOT-A-MAC' } }
+
+    // Put invalid timer object into refreshTimers to ensure code handles it
+    const nid = (platform as any).normalizeDeviceId(accessory.context.deviceId)
+    ;(platform as any).refreshTimers.set(nid, null as any)
+    ;(platform as any).accessoryInstances.set(nid, { dummy: true })
+
+    // Insert accessory into matterAccessories so removeDisabledAccessories will see it
+    ;(platform as any).matterAccessories.set(uuid, accessory)
+
+    // Spy on clearDeviceResources
+    const spyClear = vi.spyOn(platform as any, 'clearDeviceResources')
+
+    // Call removeDisabledAccessories directly
+    await (platform as any).removeDisabledAccessories()
+
+    // Expect unregister was called and matterAccessories cleared
+    expect(unregister).toHaveBeenCalled()
+    expect((platform as any).matterAccessories.get(uuid)).toBeUndefined()
+
+    // clearDeviceResources should have been called with the accessory.deviceId
+    expect(spyClear).toHaveBeenCalledWith(accessory.context.deviceId)
+  })
+})

package/src/settings.ts

@@ -36,6 +36,10 @@ export interface options {
   irdevices?: irDevicesConfig[]
   irdeviceConfig?: { [remoteType: string]: 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
   mqttURL?: string
   mqttOptions?: IClientOptions
   mqttPubOptions?: IClientOptions

package/src/utils.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { createPlatformProxy, detectMatter } from './utils.js'
+
+describe('detectMatter', () => {
+  it('returns enabled true when api.isMatterEnabled is a function that returns true', () => {
+    const api: any = { isMatterEnabled: () => true }
+    const info = detectMatter(api)
+    expect(info.enabled).toBe(true)
+    expect(info.reason).toMatch(/isMatterEnabled\(\)/)
+  })
+
+  it('returns enabled true when api.isMatterEnabled is a truthy property', () => {
+    const api: any = { isMatterEnabled: true }
+    const info = detectMatter(api)
+    expect(info.enabled).toBe(true)
+    expect(info.reason).toMatch(/property present/)
+  })
+
+  it('uses server fallback when present', () => {
+    const api: any = { server: { isMatterEnabled: () => false } }
+    const info = detectMatter(api)
+    expect(info.enabled).toBe(false)
+    expect(info.reason).toMatch(/server.isMatterEnabled\(\)/)
+  })
+
+  it('returns enabled false with a reason when no API is present', () => {
+    const api: any = {}
+    const info = detectMatter(api)
+    expect(info.enabled).toBe(false)
+    expect(typeof info.reason).toBe('string')
+  })
+})
+
+describe('createPlatformProxy', () => {
+  it('selects HAP platform when Matter is disabled and delegates configureAccessory', () => {
+    class HapStub {
+      public static created = false
+      public configured: any = undefined
+      constructor(public log: any, public config: any, public api: any) {
+        HapStub.created = true
+      }
+
+      configureAccessory(acc: any) {
+        this.configured = acc
+      }
+    }
+
+    class MatterStub {
+      constructor() {
+        throw new Error('should not be constructed')
+      }
+    }
+
+    const ProxyCtor = createPlatformProxy(HapStub as any, MatterStub as any)
+    const log = { info: vi.fn() }
+    const api = { isMatterEnabled: false }
+    const proxy = new (ProxyCtor as any)(log, {}, api)
+
+    // delegate should be instance of HapStub
+    expect(HapStub.created).toBe(true)
+    expect(typeof proxy.delegate.configureAccessory).toBe('function')
+    proxy.configureAccessory('accessory')
+    expect(proxy.delegate.configured).toBe('accessory')
+    // log should mention HAP
+    expect((log.info as any).mock.calls[0][0]).toMatch(/HAP/)
+  })
+
+  it('selects Matter platform when isMatterEnabled is true', () => {
+    class HapStub2 {
+      constructor() {
+        throw new Error('should not be constructed')
+      }
+    }
+
+    class MatterStub2 {
+      public configured: any = undefined
+      constructor(public log: any, public config: any, public api: any) {}
+
+      configureMatterAccessory(acc: any) {
+        this.configured = acc
+      }
+    }
+
+    const ProxyCtor = createPlatformProxy(HapStub2 as any, MatterStub2 as any)
+    const log = { info: vi.fn() }
+    const api = { isMatterEnabled: () => true }
+    const proxy = new (ProxyCtor as any)(log, {}, api)
+
+    // delegate should be instance of MatterStub2
+    expect(typeof proxy.delegate.configureMatterAccessory).toBe('function')
+    ;(proxy as any).configureMatterAccessory('macc')
+    expect(proxy.delegate.configured).toBe('macc')
+    expect((log.info as any).mock.calls[0][0]).toMatch(/Matter/)
+  })
+})

package/src/utils.ts

@@ -2,6 +2,7 @@
  *
  * util.ts: @switchbot/homebridge-switchbot platform class.
  */
+import type { API, Logging } from 'homebridge'
 import type { blindTilt, curtain, curtain3, device } from 'node-switchbot'
 
 import type { devicesConfig } from './settings.js'
@@ -716,3 +717,257 @@ export function cleanDeviceConfig(deviceConfig?: Record<string, Record<string, a
   }
   return undefined
 }
+
+/**
+ * Factory that returns a function to send OpenAPI commands using a retry wrapper.
+ *
+ * @param retryCommandFunc - bound function that calls platform.retryCommand(device, bodyChange, maxRetries, delay)
+ * @param deviceObj - the device object to operate on
+ * @param opts - optional overrides for maxRetries and delayBetweenRetries
+ * @param opts.maxRetries - override for maxRetries
+ * @param opts.delayBetweenRetries - override for delayBetweenRetries
+ */
+export function makeOpenAPISender(retryCommandFunc: any, deviceObj: any, opts?: { maxRetries?: number, delayBetweenRetries?: number }) {
+  return async (command: string, parameter = 'default') => {
+    const bodyChange: any = { command, parameter, commandType: 'command' }
+    return retryCommandFunc(deviceObj, bodyChange, opts?.maxRetries, opts?.delayBetweenRetries)
+  }
+}
+
+/**
+ * Factory that returns a function to perform BLE actions using a SwitchBotBLE client.
+ * Handles discovery retries and method invocation on the discovered device instance.
+ *
+ * @param switchBotBLE - instance of SwitchBotBLE (may be undefined)
+ * @param deviceObj - the device object (used to obtain bleModel/deviceId)
+ * @param opts - optional retry settings
+ * @param opts.bleRetries - number of BLE discovery retries
+ * @param opts.bleRetryDelay - delay between BLE retries in ms
+ */
+export function makeBLESender(switchBotBLE: any, deviceObj: any, opts?: { bleRetries?: number, bleRetryDelay?: number }) {
+  return async (methodName: string, ...args: any[]) => {
+    if (!switchBotBLE) {
+      throw new Error('Platform BLE not available')
+    }
+    const id = formatDeviceIdAsMac(deviceObj.deviceId)
+    const maxRetries = opts?.bleRetries ?? 2
+    const retryDelay = opts?.bleRetryDelay ?? 500
+    let attempt = 0
+    while (attempt < maxRetries) {
+      try {
+        const list = await switchBotBLE.discover({ model: (deviceObj as any).bleModel, id })
+        if (!Array.isArray(list) || list.length === 0) {
+          throw new Error('BLE device not found')
+        }
+        const deviceInst: any = list[0]
+        if (typeof deviceInst[methodName] !== 'function') {
+          throw new TypeError(`BLE method ${methodName} not available on device`)
+        }
+        return await deviceInst[methodName](...args)
+      } catch (e: any) {
+        attempt++
+        if (attempt >= maxRetries) {
+          throw e
+        }
+        await sleep(retryDelay)
+      }
+    }
+    throw new Error('BLE operation failed')
+  }
+}
+
+/**
+ * Decide effective connection type for a device given platform options.
+ * Mirrors the logic previously in platform-matter.
+ */
+export function chooseConnectionType(platformOptions: any, deviceObj: any): 'BLE' | 'OpenAPI' {
+  if (deviceObj?.connectionType) {
+    return deviceObj.connectionType === 'BLE' ? 'BLE' : 'OpenAPI'
+  }
+  if (platformOptions?.BLE && (deviceObj?.bleModel || (typeof deviceObj?.deviceId === 'string' && deviceObj.deviceId.length > 0))) {
+    return 'BLE'
+  }
+  return 'OpenAPI'
+}
+
+/**
+ * Detect whether Matter is enabled/available on the provided Homebridge API object.
+ * This encapsulates the multi-fallback detection used across the project.
+ */
+/**
+ * Detect whether Matter is enabled on the provided Homebridge API object.
+ * Returns an object with an `enabled` boolean and an optional `reason` string
+ * describing which check matched (useful for diagnostics).
+ */
+export function detectMatter(apiObj: API): { enabled: boolean, reason?: string } {
+  try {
+    const maybe = (apiObj as any).isMatterEnabled
+    if (typeof maybe === 'function') {
+      return { enabled: Boolean(maybe.call(apiObj)), reason: 'api.isMatterEnabled() returned truthy' }
+    }
+    if (typeof maybe !== 'undefined') {
+      return { enabled: Boolean(maybe), reason: 'api.isMatterEnabled property present' }
+    }
+
+    const server = (apiObj as any).server ?? (apiObj as any).homebridgeServer ?? (apiObj as any).homebridge_server
+    const serverMaybe = server?.isMatterEnabled
+    if (typeof serverMaybe === 'function') {
+      return { enabled: Boolean(serverMaybe.call(server)), reason: 'server.isMatterEnabled() returned truthy' }
+    }
+    if (typeof server?.isMatterEnabled !== 'undefined') {
+      return { enabled: Boolean(server.isMatterEnabled), reason: 'server.isMatterEnabled property present' }
+    }
+  } catch (e: any) {
+    return { enabled: false, reason: `error during detection: ${String(e?.message ?? e)}` }
+  }
+  return { enabled: false, reason: 'no isMatterEnabled API or server fallback detected' }
+}
+
+/**
+ * Backwards-compatible boolean wrapper for detectMatter.
+ */
+export function detectMatterEnabled(apiObj: API): boolean {
+  return detectMatter(apiObj).enabled
+}
+
+/**
+ * Create platform logging helpers used by both HAP and Matter platforms.
+ *
+ * getPlatformLogging may be either a synchronous string-returning function or an
+ * async function that resolves to the current platform logging setting. The
+ * returned helpers mirror the instance methods previously implemented on the
+ * HAP platform (infoLog, warnLog, errorLog, debugLog, etc.).
+ */
+export function createPlatformLogger(getPlatformLogging: () => string | Promise<string | undefined>, log: Logging) {
+  const getPL = async () => {
+    try {
+      return await getPlatformLogging()
+    } catch {
+      return undefined
+    }
+  }
+
+  const loggingIsDebug = async () => {
+    const pl = await getPL()
+    return pl === 'debugMode' || pl === 'debug'
+  }
+
+  const enablingPlatformLogging = async () => {
+    const pl = await getPL()
+    return pl === 'debugMode' || pl === 'debug' || pl === 'standard'
+  }
+
+  return {
+    infoLog: async (...args: any[]) => {
+      if (await enablingPlatformLogging()) {
+        log.info(String(...args))
+      }
+    },
+    successLog: async (...args: any[]) => {
+      if (await enablingPlatformLogging()) {
+        // Some Logging implementations expose `success` — call if present
+        ;(log as any).success?.(String(...args)) ?? log.info(String(...args))
+      }
+    },
+    debugSuccessLog: async (...args: any[]) => {
+      if (await enablingPlatformLogging()) {
+        if (await loggingIsDebug()) {
+          ;(log as any).success?.('[DEBUG]', String(...args)) ?? log.info('[DEBUG]', String(...args))
+        }
+      }
+    },
+    warnLog: async (...args: any[]) => {
+      if (await enablingPlatformLogging()) {
+        log.warn(String(...args))
+      }
+    },
+    debugWarnLog: async (...args: any[]) => {
+      if (await enablingPlatformLogging()) {
+        if (await loggingIsDebug()) {
+          log.warn('[DEBUG]', String(...args))
+        }
+      }
+    },
+    errorLog: async (...args: any[]) => {
+      if (await enablingPlatformLogging()) {
+        log.error(String(...args))
+      }
+    },
+    debugErrorLog: async (...args: any[]) => {
+      if (await enablingPlatformLogging()) {
+        if (await loggingIsDebug()) {
+          log.error('[DEBUG]', String(...args))
+        }
+      }
+    },
+    debugLog: async (...args: any[]) => {
+      if (await enablingPlatformLogging()) {
+        const pl = await getPL()
+        if (pl === 'debug') {
+          log.info('[DEBUG]', String(...args))
+        } else if (pl === 'debugMode') {
+          log.debug(String(...args))
+        }
+      }
+    },
+    loggingIsDebug,
+    enablingPlatformLogging,
+  }
+}
+
+/**
+ * Create a Platform proxy class that selects between two platform constructors
+ * (HAP vs Matter) at runtime using `detectMatter`. Returns a class suitable
+ * for passing to `api.registerPlatform`.
+ */
+export function createPlatformProxy(HAPCtor: any, MatterCtor: any) {
+  return class PlatformProxy {
+    delegate: any
+
+    constructor(public readonly log: any, public readonly config: any, public readonly api: API) {
+      const matterInfo = detectMatter(this.api)
+      const isMatter = matterInfo.enabled
+      const reason = matterInfo.reason ? ` Reason: ${matterInfo.reason}` : ''
+      this.log.info?.(`Homebridge SwitchBot Plugin initializing in ${isMatter ? 'Matter' : 'HAP'} mode.`)
+      this.log.debug?.(`Homebridge SwitchBot Plugin initializing in ${isMatter ? 'Matter' : 'HAP'} mode.${reason}`)
+      const PlatformCtor = isMatter ? MatterCtor : HAPCtor
+      this.delegate = new PlatformCtor(this.log, this.config, this.api)
+    }
+
+    configureAccessory(accessory: any): void {
+      try {
+        if (this.delegate && typeof this.delegate.configureAccessory === 'function') {
+          return this.delegate.configureAccessory(accessory)
+        }
+      } catch (e) {
+        // swallow — preserve previous behaviour where delegate errors don't bubble here
+      }
+    }
+
+    configureMatterAccessory?(accessory: any): void {
+      try {
+        if (this.delegate && typeof this.delegate.configureMatterAccessory === 'function') {
+          return this.delegate.configureMatterAccessory(accessory)
+        }
+      } catch (e) {
+        // swallow — delegate may not implement this or may throw
+      }
+    }
+
+    get accessories(): any {
+      try {
+        return this.delegate?.accessories
+      } catch (e) {
+        return undefined
+      }
+    }
+
+    get matterAccessories(): any {
+      try {
+        return this.delegate?.matterAccessories
+      } catch (e) {
+        return undefined
+      }
+    }
+  }
+}

package/src/verifyconfig.test.ts

@@ -1,6 +1,7 @@
-import { describe, expect, it, vi } from 'vitest'
 import type { SwitchBotPlatformConfig } from './settings.js'
 
+import { describe, expect, it } from 'vitest'
+
 // Create a minimal mock of the SwitchBotPlatform to test verifyConfig
 class MockSwitchBotPlatform {
   config: SwitchBotPlatformConfig
@@ -102,10 +103,10 @@ describe('verifyConfig fix for reboot loop', () => {
 
     // This should NOT throw an error anymore - it should log instead
     await expect(platform.verifyConfig()).resolves.not.toThrow()
-    
+
     // Verify that the error was logged instead of thrown
     expect(platform.errorLogCalls).toContain(
-      'The devices config section is missing the *Device ID* in the config. Please check your config.'
+      'The devices config section is missing the *Device ID* in the config. Please check your config.',
     )
   })
 
@@ -132,10 +133,10 @@ describe('verifyConfig fix for reboot loop', () => {
 
     // This should NOT throw an error anymore - it should log instead
     await expect(platform.verifyConfig()).resolves.not.toThrow()
-    
+
     // Verify that the error was logged instead of thrown
     expect(platform.errorLogCalls).toContain(
-      'The devices config section is missing the *Device Type* in the config. Please check your config.'
+      'The devices config section is missing the *Device Type* in the config. Please check your config.',
     )
   })
 
@@ -187,11 +188,11 @@ describe('verifyConfig fix for reboot loop', () => {
 
     // Should not throw or log device config errors with valid config
     await expect(platform.verifyConfig()).resolves.not.toThrow()
-    
+
     // Should not have device config errors
-    expect(platform.errorLogCalls.filter(msg => 
-      msg.includes('missing the *Device ID*') || 
-      msg.includes('missing the *Device Type*')
+    expect(platform.errorLogCalls.filter(msg =>
+      msg.includes('missing the *Device ID*')
+      || msg.includes('missing the *Device Type*'),
     )).toHaveLength(0)
   })
-})
+})