@switchbot/homebridge-switchbot 5.0.0-beta.29 → 5.0.0-beta.30

package/src/platform-matter.ts

@@ -39,7 +39,7 @@ import {
   WindowBlindAccessory,
 } from './devices-matter/index.js'
 import { PLATFORM_NAME, PLUGIN_NAME } from './settings.js'
-import { cleanDeviceConfig, createPlatformLogger, formatDeviceIdAsMac, hs2rgb, makeBLESender, makeOpenAPISender, rgb2hs, sleep } from './utils.js'
+import { ApiRequestTracker, cleanDeviceConfig, createPlatformLogger, formatDeviceIdAsMac, hs2rgb, makeBLESender, makeOpenAPISender, rgb2hs, sleep } from './utils.js'
 
 export class SwitchBotMatterPlatform implements DynamicPlatformPlugin {
   // Track restored HAP cached accessories (required for DynamicPlatformPlugin)
@@ -57,6 +57,12 @@ export class SwitchBotMatterPlatform implements DynamicPlatformPlugin {
   private accessoryInstances: Map<string, any> = new Map()
   // Refresh timers keyed by normalized deviceId
   private refreshTimers: Map<string, NodeJS.Timeout> = new Map()
+  // Platform-level refresh timer for batch status updates
+  private platformRefreshTimer?: NodeJS.Timeout
+  // Device status cache from last refresh
+  private deviceStatusCache: Map<string, any> = new Map()
+  // Devices that have explicit per-device refresh timers (normalized deviceId)
+  private perDeviceRefreshSet: Set<string> = new Set()
   // BLE event handlers keyed by device MAC (formatted)
   private bleEventHandler: { [x: string]: (context: any) => void } = {}
   // MQTT and Webhook properties (mirror HAP behavior so Matter platform can
@@ -68,6 +74,9 @@ export class SwitchBotMatterPlatform implements DynamicPlatformPlugin {
   // Use same shape as HAP platform: string values like 'debug', 'debugMode', 'standard', or 'none'
   private platformLogging?: string
 
+  // API request tracking (persistent across restarts)
+  private apiTracker?: ApiRequestTracker
+
   // Platform-provided logging helpers (attached in constructor)
   infoLog!: (...args: any[]) => void
   successLog!: (...args: any[]) => void
@@ -173,6 +182,14 @@ export class SwitchBotMatterPlatform implements DynamicPlatformPlugin {
         this.errorLog('Failed to initialize SwitchBot OpenAPI:', e?.message ?? e)
       }
 
+      // Initialize API request tracking
+      try {
+        this.apiTracker = new ApiRequestTracker(this.api, this.log, 'SwitchBot Matter')
+        this.apiTracker.startHourlyLogging()
+      } catch (e: any) {
+        this.errorLog('Failed to initialize API request tracking:', e?.message ?? e)
+      }
+
       try {
         this.switchBotBLE = new SwitchBotBLE()
         if (!this.config.options?.disableLogsforBLE && this.switchBotBLE?.on) {
@@ -211,6 +228,12 @@ export class SwitchBotMatterPlatform implements DynamicPlatformPlugin {
       this.api.on('shutdown', async () => {
         try {
           this.infoLog('Homebridge shutting down: clearing refresh timers and BLE handlers')
+
+          // Stop API tracking hourly logging
+          if (this.apiTracker) {
+            this.apiTracker.stopHourlyLogging()
+          }
+
           // Clear all refresh timers
           for (const [nid, t] of Array.from(this.refreshTimers.entries())) {
             try {
@@ -221,6 +244,16 @@ export class SwitchBotMatterPlatform implements DynamicPlatformPlugin {
             this.refreshTimers.delete(nid)
           }
 
+          // Clear platform-level refresh timer
+          try {
+            if (this.platformRefreshTimer) {
+              clearInterval(this.platformRefreshTimer)
+              this.platformRefreshTimer = undefined
+            }
+          } catch (e: any) {
+            this.debugLog(`Failed to clear platform refresh timer: ${e?.message ?? e}`)
+          }
+
           // Clear accessory instances registry
           try {
             this.accessoryInstances.clear()
@@ -290,6 +323,14 @@ export class SwitchBotMatterPlatform implements DynamicPlatformPlugin {
     return (deviceId ?? '').toUpperCase().replace(/[^A-Z0-9]+/g, '')
   }
 
+  /** Determine the platform-level batch interval in seconds */
+  private getPlatformBatchInterval(): number {
+    const opt = this.config.options
+    const val = opt?.matterBatchRefreshRate ?? opt?.refreshRate ?? 300
+    const n = Number(val)
+    return Number.isFinite(n) && n > 0 ? n : 300
+  }
+
   /**
    * Clear per-device resources: refresh timers, accessory instance registry, BLE handlers
    */
@@ -720,7 +761,9 @@ export class SwitchBotMatterPlatform implements DynamicPlatformPlugin {
 
             // Brightness
             if (parsed.brightness !== undefined) {
-              const level = Math.round((Number(parsed.brightness) / 100) * 254)
+              const rawLevel = Math.round((Number(parsed.brightness) / 100) * 254)
+              const level = Math.max(0, Math.min(254, rawLevel))
+              this.debugLog(`[BLE Brightness Debug] Device ${dev.deviceId}: rawBrightness=${parsed.brightness}, calculated=${rawLevel}, clamped=${level}`)
               await this.api.matter.updateAccessoryState(uuidLocal, this.api.matter.clusterNames.LevelControl, { currentLevel: level })
             }
 
@@ -728,31 +771,44 @@ export class SwitchBotMatterPlatform implements DynamicPlatformPlugin {
             if (parsed.color !== undefined) {
               const { r, g, b } = parsed.color
               const [h, s] = rgb2hs(r, g, b)
-              await this.api.matter.updateAccessoryState(uuidLocal, this.api.matter.clusterNames.ColorControl, { currentHue: Math.round((h / 360) * 254), currentSaturation: Math.round((s / 100) * 254) })
+              const rawHue = Math.round((h / 360) * 254)
+              const rawSat = Math.round((s / 100) * 254)
+              const hue = Math.max(0, Math.min(254, rawHue))
+              const sat = Math.max(0, Math.min(254, rawSat))
+              this.debugLog(`[BLE Color Debug] Device ${dev.deviceId}: RGB=[${r},${g},${b}], HS=[${h},${s}], Matter=[${rawHue},${rawSat}], clamped=[${hue},${sat}]`)
+              await this.api.matter.updateAccessoryState(uuidLocal, this.api.matter.clusterNames.ColorControl, { currentHue: hue, currentSaturation: sat })
             }
 
             // Battery -> powerSource cluster (common mapping)
             if (parsed.battery !== undefined) {
-              try {
-                const percentage = Number(parsed.battery)
-                const batPercentRemaining = Math.max(0, Math.min(200, Math.round(percentage * 2)))
-                let batChargeLevel = 0
-                if (percentage < 20) {
-                  batChargeLevel = 2
-                } else if (percentage < 40) {
-                  batChargeLevel = 1
-                }
+              // Skip battery updates for device types that don't support PowerSource cluster
+              const deviceType = String(dev?.deviceType ?? '')
+              const unsupportedTypes = ['Curtain', 'Curtain2', 'Curtain3', 'Curtain 2', 'Blind Tilt']
+
+              if (unsupportedTypes.includes(deviceType)) {
+                this.debugLog(`Device ${dev.deviceId} type ${deviceType} does not support PowerSource cluster, skipping BLE battery update`)
+              } else {
                 try {
-                  await this.api.matter.updateAccessoryState(uuidLocal, 'powerSource', { batPercentRemaining, batChargeLevel })
-                } catch (updateError: any) {
-                  // Silently skip if powerSource cluster doesn't exist on this device
-                  const msg = String(updateError?.message ?? updateError)
-                  if (!msg.includes('does not exist') && !msg.includes('not found')) {
-                    throw updateError
+                  const percentage = Number(parsed.battery)
+                  const batPercentRemaining = Math.max(0, Math.min(200, Math.round(percentage * 2)))
+                  let batChargeLevel = 0
+                  if (percentage < 20) {
+                    batChargeLevel = 2
+                  } else if (percentage < 40) {
+                    batChargeLevel = 1
                   }
+                  try {
+                    await this.api.matter.updateAccessoryState(uuidLocal, 'powerSource', { batPercentRemaining, batChargeLevel })
+                  } catch (updateError: any) {
+                    // Silently skip if powerSource cluster doesn't exist on this device
+                    const msg = String(updateError?.message ?? updateError)
+                    if (!msg.includes('does not exist') && !msg.includes('not found')) {
+                      throw updateError
+                    }
+                  }
+                } catch (e: any) {
+                  this.debugLog(`Failed to update battery state for ${dev.deviceId}: ${e?.message ?? e}`)
                 }
-              } catch (e: any) {
-                this.debugLog(`Failed to update battery state for ${dev.deviceId}: ${e?.message ?? e}`)
               }
             }
 
@@ -880,6 +936,7 @@ export class SwitchBotMatterPlatform implements DynamicPlatformPlugin {
           return
         }
         try {
+          this.apiTracker?.track()
           const { response, statusCode } = await this.switchBotAPI.getDeviceStatus(dev.deviceId, this.config.credentials?.token, this.config.credentials?.secret)
           const respAny: any = response
           const body = respAny?.body ?? respAny
@@ -914,12 +971,14 @@ export class SwitchBotMatterPlatform implements DynamicPlatformPlugin {
         this.refreshTimers.delete(nid)
       }
 
-      const refreshRateSec = dev.refreshRate ?? this.config.options?.refreshRate ?? 300
-      if (this.switchBotAPI && refreshRateSec && Number(refreshRateSec) > 0) {
+      const platformInterval = this.getPlatformBatchInterval()
+      const hasDeviceInterval = typeof dev.refreshRate === 'number' && Number(dev.refreshRate) > 0
+      if (this.switchBotAPI && (hasDeviceInterval || platformInterval > 0)) {
         // Immediate one-shot to populate initial state
         ;(async () => {
           try {
             this.infoLog(`Performing initial OpenAPI refresh for ${dev.deviceId}`)
+            this.apiTracker?.track()
             const { response, statusCode } = await this.switchBotAPI!.getDeviceStatus(dev.deviceId, this.config.credentials?.token, this.config.credentials?.secret)
             const respAny: any = response
             const body = respAny?.body ?? respAny
@@ -941,30 +1000,23 @@ export class SwitchBotMatterPlatform implements DynamicPlatformPlugin {
           }
         })()
 
-        const timer = setInterval(async () => {
-          try {
-            this.debugLog(`Performing periodic OpenAPI refresh for ${dev.deviceId}`)
-            const { response, statusCode } = await this.switchBotAPI!.getDeviceStatus(dev.deviceId, this.config.credentials?.token, this.config.credentials?.secret)
-            const respAny: any = response
-            const body = respAny?.body ?? respAny
+        if (hasDeviceInterval) {
+          // Create a per-device timer and exclude it from batch
+          const interval = Number(dev.refreshRate)
+          this.perDeviceRefreshSet.add(nid)
+          const timer = setInterval(async () => {
             try {
-              const s = JSON.stringify(body)
-              this.debugLog(`Periodic OpenAPI refresh for ${dev.deviceId} returned statusCode=${statusCode} body=${s}`)
-            } catch (e) {
-              this.debugLog(`Periodic OpenAPI refresh for ${dev.deviceId} returned statusCode=${statusCode} (body not stringifiable)`)
-            }
-            if (statusCode === 100 || statusCode === 200) {
-              const status = body?.status ?? body
-              await this.applyStatusToAccessory(uuid, dev, status)
-            } else {
-              this.debugLog(`Periodic OpenAPI refresh returned unexpected statusCode=${statusCode} for ${dev.deviceId}`)
+              await this.refreshSingleDeviceWithRetry(dev)
+            } catch (e: any) {
+              this.debugLog(`Per-device refresh failed for ${dev.deviceId}: ${e?.message ?? e}`)
             }
-          } catch (e: any) {
-            this.errorLog(`Periodic OpenAPI refresh failed for ${dev.deviceId}: ${e?.message ?? e}`)
-          }
-        }, Number(refreshRateSec) * 1000)
-
-        this.refreshTimers.set(nid, timer)
+          }, interval * 1000)
+          this.refreshTimers.set(nid, timer)
+          this.infoLog(`Started per-device refresh timer for ${dev.deviceId} at ${interval}s`)
+        } else {
+          // Start platform-level batched refresh timer (only once)
+          this.startPlatformRefreshTimer(platformInterval)
+        }
       }
     } catch (e: any) {
       this.debugLog(`Failed to schedule refresh for ${dev.deviceId}: ${e?.message ?? e}`)
@@ -983,6 +1035,7 @@ export class SwitchBotMatterPlatform implements DynamicPlatformPlugin {
     }
 
     try {
+      this.apiTracker?.track()
       const { response, statusCode } = await this.switchBotAPI.getDevices()
       this.debugLog(`SwitchBot getDevices response status: ${statusCode}`)
       if (statusCode === 100 || statusCode === 200) {
@@ -1082,6 +1135,7 @@ export class SwitchBotMatterPlatform implements DynamicPlatformPlugin {
         if (!this.switchBotAPI) {
           throw new Error('SwitchBot OpenAPI not initialized')
         }
+        this.apiTracker?.track()
         const { response, statusCode } = await this.switchBotAPI.controlDevice(
           deviceObj.deviceId,
           bodyChange.command,
@@ -1330,10 +1384,19 @@ export class SwitchBotMatterPlatform implements DynamicPlatformPlugin {
       // Brightness
       if (status?.brightness !== undefined) {
         const rawBrightness = Number(status.brightness)
-        const level = Math.round((rawBrightness / 100) * 254)
-        const clampedLevel = Math.max(0, Math.min(254, level))
-        this.debugLog(`[Brightness Debug] Device ${dev.deviceId}: rawBrightness=${rawBrightness}, calculated=${level}, clamped=${clampedLevel}`)
-        await safeUpdate(this.api.matter.clusterNames.LevelControl, { currentLevel: clampedLevel }, 'updateBrightness')
+        const clampedBrightness = Math.max(0, Math.min(100, rawBrightness))
+
+        // If instance has updateBrightness method, it expects percentage (0-100)
+        // Otherwise, updateAccessoryState expects Matter-scaled value (0-254)
+        if (instance && typeof instance.updateBrightness === 'function') {
+          this.debugLog(`[Brightness Debug] Device ${dev.deviceId}: calling updateBrightness with percent=${clampedBrightness}`)
+          await safeUpdate(this.api.matter.clusterNames.LevelControl, { currentLevel: clampedBrightness }, 'updateBrightness')
+        } else {
+          const level = Math.round((clampedBrightness / 100) * 254)
+          const clampedLevel = Math.max(0, Math.min(254, level))
+          this.debugLog(`[Brightness Debug] Device ${dev.deviceId}: calling updateAccessoryState with rawBrightness=${rawBrightness}, level=${clampedLevel}`)
+          await safeUpdate(this.api.matter.clusterNames.LevelControl, { currentLevel: clampedLevel })
+        }
       }
 
       // Color
@@ -1358,29 +1421,48 @@ export class SwitchBotMatterPlatform implements DynamicPlatformPlugin {
           b = Number.parseInt(hex.substring(4, 6), 16)
         }
         const [h, s] = rgb2hs(r, g, b)
-        const hue = Math.round((h / 360) * 254)
-        const sat = Math.round((s / 100) * 254)
-        const clampedHue = Math.max(0, Math.min(254, hue))
-        const clampedSat = Math.max(0, Math.min(254, sat))
-        this.debugLog(`[Color Debug] Device ${dev.deviceId}: color="${color}", RGB=[${r},${g},${b}], HS=[${h},${s}], Matter=[${hue},${sat}], clamped=[${clampedHue},${clampedSat}]`)
-        await safeUpdate(this.api.matter.clusterNames.ColorControl, { currentHue: clampedHue, currentSaturation: clampedSat }, 'updateHueSaturation')
+        const clampedH = Math.max(0, Math.min(360, h))
+        const clampedS = Math.max(0, Math.min(100, s))
+
+        // If instance has updateHueSaturation method, it expects raw values (h: 0-360, s: 0-100)
+        // Otherwise, updateAccessoryState expects Matter-scaled values (0-254)
+        if (instance && typeof instance.updateHueSaturation === 'function') {
+          this.debugLog(`[Color Debug] Device ${dev.deviceId}: calling updateHueSaturation with color="${color}", RGB=[${r},${g},${b}], HS=[${clampedH},${clampedS}]`)
+          await safeUpdate(this.api.matter.clusterNames.ColorControl, { currentHue: clampedH, currentSaturation: clampedS }, 'updateHueSaturation')
+        } else {
+          const hue = Math.round((clampedH / 360) * 254)
+          const sat = Math.round((clampedS / 100) * 254)
+          const clampedHue = Math.max(0, Math.min(254, hue))
+          const clampedSat = Math.max(0, Math.min(254, sat))
+          this.debugLog(`[Color Debug] Device ${dev.deviceId}: calling updateAccessoryState with color="${color}", RGB=[${r},${g},${b}], HS=[${h},${s}], Matter=[${clampedHue},${clampedSat}]`)
+          await safeUpdate(this.api.matter.clusterNames.ColorControl, { currentHue: clampedHue, currentSaturation: clampedSat })
+        }
       }
 
       // Battery/powerSource (support many possible field names)
+      // Note: Some device types like WindowBlind don't support PowerSource cluster
       if (status?.battery !== undefined || status?.batt !== undefined || status?.batteryLevel !== undefined || status?.batteryPercentage !== undefined || status?.battery_level !== undefined) {
-        try {
-          const percentage = Number(status?.battery ?? status?.batt ?? status?.batteryPercentage ?? status?.batteryLevel ?? status?.battery_level)
-          const batPercentRemaining = Math.max(0, Math.min(200, Math.round(percentage * 2)))
-          let batChargeLevel = 0
-          if (percentage < 20) {
-            batChargeLevel = 2
-          } else if (percentage < 40) {
-            batChargeLevel = 1
+        // Skip battery updates for device types that don't support PowerSource cluster
+        const deviceType = String(status?.deviceType ?? dev?.deviceType ?? '')
+        const unsupportedTypes = ['Curtain', 'Curtain2', 'Curtain3', 'Curtain 2', 'Blind Tilt']
+
+        if (unsupportedTypes.includes(deviceType)) {
+          this.debugLog(`Device ${dev.deviceId} type ${deviceType} does not support PowerSource cluster, skipping battery update`)
+        } else {
+          try {
+            const percentage = Number(status?.battery ?? status?.batt ?? status?.batteryPercentage ?? status?.batteryLevel ?? status?.battery_level)
+            const batPercentRemaining = Math.max(0, Math.min(200, Math.round(percentage * 2)))
+            let batChargeLevel = 0
+            if (percentage < 20) {
+              batChargeLevel = 2
+            } else if (percentage < 40) {
+              batChargeLevel = 1
+            }
+            const powerCluster = (this.api.matter?.clusterNames && (this.api.matter.clusterNames as any).PowerSource) ? (this.api.matter.clusterNames as any).PowerSource : 'powerSource'
+            await safeUpdate(powerCluster, { batPercentRemaining, batChargeLevel }, 'updateBatteryPercentage')
+          } catch (e: any) {
+            this.debugLog(`Failed to apply battery status for ${dev.deviceId}: ${e?.message ?? e}`)
           }
-          const powerCluster = (this.api.matter?.clusterNames && (this.api.matter.clusterNames as any).PowerSource) ? (this.api.matter.clusterNames as any).PowerSource : 'powerSource'
-          await safeUpdate(powerCluster, { batPercentRemaining, batChargeLevel }, 'updateBatteryPercentage')
-        } catch (e: any) {
-          this.debugLog(`Failed to apply battery status for ${dev.deviceId}: ${e?.message ?? e}`)
         }
       }
 
@@ -2042,4 +2124,118 @@ export class SwitchBotMatterPlatform implements DynamicPlatformPlugin {
       await this.api.matter.registerPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, accessories)
     }
   }
+
+  /**
+   * Start platform-level refresh timer to batch all device status updates
+   */
+  private startPlatformRefreshTimer(refreshRateSec: number): void {
+    // Only create timer once
+    if (this.platformRefreshTimer) {
+      return
+    }
+
+    this.debugLog(`Starting platform-level refresh timer with interval ${refreshRateSec}s`)
+    this.platformRefreshTimer = setInterval(async () => {
+      await this.batchRefreshAllDevices()
+    }, Number(refreshRateSec) * 1000)
+  }
+
+  /**
+   * Batch refresh all devices - still makes individual API calls but batches them together
+   * Note: SwitchBot API doesn't support true batch status calls, but we can parallelize them
+   */
+  private async batchRefreshAllDevices(): Promise<void> {
+    if (!this.switchBotAPI) {
+      return
+    }
+
+    this.debugLog('Performing batched periodic OpenAPI refresh for all devices')
+
+    // Build list from registered accessory instances (uuid) and discovered devices
+    const devicesToRefresh: Array<{ uuid: string, dev: device }> = []
+    try {
+      for (const [nid, instance] of this.accessoryInstances.entries()) {
+        const uuid = (instance as any)?.uuid as string | undefined
+        if (!uuid) {
+          continue
+        }
+        const dev = this.discoveredDevices.find(d => this.normalizeDeviceId(d.deviceId) === nid)
+        if (dev && !this.perDeviceRefreshSet.has(nid)) {
+          devicesToRefresh.push({ uuid, dev })
+        }
+      }
+    } catch (e: any) {
+      this.errorLog(`Failed to enumerate devices for batch refresh: ${e?.message ?? e}`)
+      return
+    }
+
+    if (devicesToRefresh.length === 0) {
+      this.debugLog('No devices to refresh')
+      return
+    }
+
+    this.debugLog(`Refreshing ${devicesToRefresh.length} devices in parallel batch`)
+
+    const concurrency = Number(this.config.options?.matterBatchConcurrency ?? 5)
+    await this.runWithConcurrency(devicesToRefresh, async ({ uuid, dev }) => {
+      try {
+        const status = await this.refreshSingleDeviceWithRetry(dev)
+        if (status) {
+          await this.applyStatusToAccessory(uuid, dev as any, status)
+        }
+      } catch (e: any) {
+        this.errorLog(`Periodic OpenAPI refresh failed for ${dev.deviceId}: ${e?.message ?? e}`)
+      }
+    }, Number.isFinite(concurrency) && concurrency > 0 ? concurrency : 5)
+    this.debugLog(`Batch refresh completed for ${devicesToRefresh.length} devices`)
+  }
+
+  /** Refresh a single device with retry and backoff; returns status object if successful */
+  private async refreshSingleDeviceWithRetry(dev: device, retries = 3, baseDelayMs = 500): Promise<any | null> {
+    const deviceId = dev.deviceId
+    let attempt = 0
+    while (attempt <= retries) {
+      try {
+        this.apiTracker?.track()
+        const { response, statusCode } = await this.switchBotAPI!.getDeviceStatus(deviceId, this.config.credentials?.token, this.config.credentials?.secret)
+        const respAny: any = response
+        const body = respAny?.body ?? respAny
+        if (statusCode === 100 || statusCode === 200) {
+          const status = body?.status ?? body
+          this.deviceStatusCache.set(this.normalizeDeviceId(deviceId), { status, timestamp: Date.now() })
+          this.debugLog(`OpenAPI refresh succeeded for ${deviceId} (attempt ${attempt + 1})`)
+          return status
+        }
+        this.debugLog(`OpenAPI refresh unexpected statusCode=${statusCode} for ${deviceId} (attempt ${attempt + 1})`)
+      } catch (e: any) {
+        this.debugLog(`OpenAPI refresh error for ${deviceId} (attempt ${attempt + 1}): ${e?.message ?? e}`)
+      }
+      // backoff before next retry if any left
+      attempt++
+      if (attempt <= retries) {
+        const delay = baseDelayMs * (2 ** (attempt - 1))
+        await sleep(delay)
+      }
+    }
+    return null
+  }
+
+  /** Simple concurrency limiter for an array of items */
+  private async runWithConcurrency<T>(items: T[], worker: (item: T) => Promise<void>, concurrency: number): Promise<void> {
+    const queue = items.slice()
+    const workers: Promise<void>[] = []
+    const runNext = async (): Promise<void> => {
+      const item = queue.shift()
+      if (!item) {
+        return
+      }
+      await worker(item)
+      return runNext()
+    }
+    const pool = Math.min(concurrency, Math.max(1, items.length))
+    for (let i = 0; i < pool; i++) {
+      workers.push(runNext())
+    }
+    await Promise.all(workers)
+  }
 }

package/src/settings.ts

@@ -61,6 +61,9 @@ export interface options {
   updateRate?: number
   pushRate?: number
   logging?: string
+  // Matter platform batch refresh options
+  matterBatchRefreshRate?: number
+  matterBatchConcurrency?: number
 };
 
 export type devicesConfig = botConfig | relaySwitch1Config | relaySwitch1PMConfig | meterConfig | meterProConfig | indoorOutdoorSensorConfig | humidifierConfig | curtainConfig | blindTiltConfig | contactConfig | motionConfig | waterDetectorConfig | plugConfig | colorBulbConfig | stripLightConfig | ceilingLightConfig | lockConfig | hubConfig

package/src/utils.ts

@@ -1,12 +1,15 @@
-/* Copyright(C) 2017-2024, donavanbecker (https://github.com/donavanbecker). All rights reserved.
- *
- * 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'
 
+/* Copyright(C) 2017-2024, donavanbecker (https://github.com/donavanbecker). All rights reserved.
+ *
+ * util.ts: @switchbot/homebridge-switchbot platform class.
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
 export enum BlindTiltMappingMode {
   OnlyUp = 'only_up',
   OnlyDown = 'only_down',
@@ -971,3 +974,133 @@ export function createPlatformProxy(HAPCtor: any, MatterCtor: any) {
     }
   }
 }
+
+/**
+ * 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
+  }
+}