@switchbot/homebridge-switchbot 5.0.0-beta.3 → 5.0.0-beta.31

package/src/utils.ts

@@ -1,10 +1,14 @@
+import type { API, Logging } from 'homebridge'
+import type { blindTilt, curtain, curtain3, device } from 'node-switchbot'
+
+import type { devicesConfig } from './settings.js'
+
 /* Copyright(C) 2017-2024, donavanbecker (https://github.com/donavanbecker). All rights reserved.
  *
  * util.ts: @switchbot/homebridge-switchbot platform class.
  */
-import type { blindTilt, curtain, curtain3, device } from 'node-switchbot'
-
-import type { devicesConfig } from './settings.js'
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
 
 export enum BlindTiltMappingMode {
   OnlyUp = 'only_up',
@@ -716,3 +720,415 @@ 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'
+  }
+
+  const formatArgs = (args: any[]): string => {
+    return args
+      .map((a: any) => {
+        if (typeof a === 'string') {
+          return a
+        }
+        try {
+          return JSON.stringify(a)
+        } catch {
+          return String(a)
+        }
+      })
+      .join(' ')
+  }
+
+  return {
+    // Format arbitrary arguments into a single string to ensure values are not dropped
+    // when loggers only accept a single message parameter.
+    // Prefer readable JSON for objects, fall back to String() on errors.
+    // Example: infoLog('Loaded', accessory.displayName) => "Loaded My Light"
+    infoLog: async (...args: any[]) => {
+      if (await enablingPlatformLogging()) {
+        const msg = formatArgs(args)
+        log.info(msg)
+      }
+    },
+    successLog: async (...args: any[]) => {
+      if (await enablingPlatformLogging()) {
+        const msg = formatArgs(args)
+        // Some Logging implementations expose `success` — call if present
+        ;(log as any).success?.(msg) ?? log.info(msg)
+      }
+    },
+    debugSuccessLog: async (...args: any[]) => {
+      if (await enablingPlatformLogging()) {
+        if (await loggingIsDebug()) {
+          const msg = formatArgs(args)
+          ;(log as any).success?.(`[DEBUG] ${msg}`) ?? log.info(`[DEBUG] ${msg}`)
+        }
+      }
+    },
+    warnLog: async (...args: any[]) => {
+      if (await enablingPlatformLogging()) {
+        const msg = formatArgs(args)
+        log.warn(msg)
+      }
+    },
+    debugWarnLog: async (...args: any[]) => {
+      if (await enablingPlatformLogging()) {
+        if (await loggingIsDebug()) {
+          const msg = formatArgs(args)
+          log.warn(`[DEBUG] ${msg}`)
+        }
+      }
+    },
+    errorLog: async (...args: any[]) => {
+      if (await enablingPlatformLogging()) {
+        const msg = formatArgs(args)
+        log.error(msg)
+      }
+    },
+    debugErrorLog: async (...args: any[]) => {
+      if (await enablingPlatformLogging()) {
+        if (await loggingIsDebug()) {
+          const msg = formatArgs(args)
+          log.error(`[DEBUG] ${msg}`)
+        }
+      }
+    },
+    debugLog: async (...args: any[]) => {
+      if (await enablingPlatformLogging()) {
+        const pl = await getPL()
+        if (pl === 'debug') {
+          const msg = formatArgs(args)
+          log.info(`[DEBUG] ${msg}`)
+        } else if (pl === 'debugMode') {
+          const msg = formatArgs(args)
+          log.debug(msg)
+        }
+      }
+    },
+    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
+      }
+    }
+  }
+}
+
+/**
+ * API Request Tracker - Persistent tracking of SwitchBot API calls
+ * Tracks requests per day with automatic midnight rollover
+ */
+export class ApiRequestTracker {
+  private count = 0
+  private date = ''
+  private statsFile = ''
+  private hourlyTimer?: NodeJS.Timeout
+  private log: Logging
+
+  constructor(api: API, log: Logging, pluginName = 'SwitchBot') {
+    this.log = log
+    this.statsFile = join(api.user.storagePath(), `${pluginName.toLowerCase()}-api-stats.json`)
+    this.load()
+  }
+
+  /**
+   * Load API request statistics from persistent storage
+   */
+  private load(): void {
+    try {
+      const today = new Date().toISOString().split('T')[0]
+
+      if (existsSync(this.statsFile)) {
+        const data = JSON.parse(readFileSync(this.statsFile, 'utf8'))
+
+        // If it's a new day, reset the counter
+        if (data.date === today) {
+          this.count = data.count || 0
+          this.date = data.date
+          this.log.warn?.(`[API Stats] Loaded: ${this.count} requests today (${today})`)
+        } else {
+          this.log.error?.(`[API Stats] New day detected. Previous: ${data.count || 0} requests on ${data.date}`)
+          this.count = 0
+          this.date = today
+          this.save()
+        }
+      } else {
+        this.log.debug?.('[API Stats] No existing stats file, starting fresh')
+        this.count = 0
+        this.date = today
+        this.save()
+      }
+    } catch (e: any) {
+      this.log.error?.(`[API Stats] Failed to load stats: ${e?.message ?? e}`)
+      this.count = 0
+      this.date = new Date().toISOString().split('T')[0]
+    }
+  }
+
+  /**
+   * Save API request statistics to persistent storage
+   */
+  private save(): void {
+    try {
+      const data = {
+        date: this.date,
+        count: this.count,
+        lastUpdated: new Date().toISOString(),
+      }
+      writeFileSync(this.statsFile, JSON.stringify(data, null, 2), 'utf8')
+    } catch (e: any) {
+      this.log.debug?.(`[API Stats] Failed to save stats: ${e?.message ?? e}`)
+    }
+  }
+
+  /**
+   * Increment API request counter and save
+   */
+  public track(): void {
+    const today = new Date().toISOString().split('T')[0]
+
+    // Reset counter if it's a new day
+    if (this.date !== today) {
+      this.log.debug?.(`[API Stats] Day rollover: ${this.count} requests on ${this.date}`)
+      this.count = 0
+      this.date = today
+    }
+
+    this.count++
+    this.save()
+  }
+
+  /**
+   * Start hourly logging of API request count
+   */
+  public startHourlyLogging(): void {
+    // Log immediately on startup
+    this.log.info?.(`[API Stats] Today (${this.date}): ${this.count} API requests`)
+
+    // Then log every hour
+    this.hourlyTimer = setInterval(() => {
+      const today = new Date().toISOString().split('T')[0]
+      if (this.date !== today) {
+        // Day rollover
+        this.log.info?.(`[API Stats] Day rollover - Previous day (${this.date}): ${this.count} API requests`)
+        this.count = 0
+        this.date = today
+        this.save()
+      }
+      this.log.info?.(`[API Stats] Today (${this.date}): ${this.count} API requests`)
+    }, 60 * 60 * 1000) // Every hour
+  }
+
+  /**
+   * Stop hourly logging
+   */
+  public stopHourlyLogging(): void {
+    if (this.hourlyTimer) {
+      clearInterval(this.hourlyTimer)
+      this.hourlyTimer = undefined
+    }
+  }
+
+  /**
+   * Get current count
+   */
+  public getCount(): number {
+    return this.count
+  }
+
+  /**
+   * Get current date
+   */
+  public getDate(): string {
+    return this.date
+  }
+}

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)
   })
-})
+})