@switchbot/homebridge-switchbot 5.0.0-beta.39 → 5.0.0-beta.40

package/src/settings.ts

@@ -59,6 +59,24 @@ export interface options {
   updateRate?: number
   pushRate?: number
   logging?: string
+  /**
+   * Maximum number of SwitchBot OpenAPI requests allowed per day.
+   * Defaults to 10,000 if not specified.
+   */
+  dailyApiLimit?: number
+  /**
+   * Number of daily API requests reserved for user-initiated commands.
+   * When remaining budget falls below this reserve, background polling and discovery
+   * are paused until the daily counter resets. Defaults to 1,000.
+   */
+  dailyApiReserveForCommands?: number
+  /**
+   * When true, the plugin will completely stop background polling/discovery
+   * once the remaining daily budget reaches the reserve (webhook-only mode).
+   * When false, polling continues until the hard daily limit is reached.
+   * Default: false.
+   */
+  webhookOnlyOnReserve?: boolean
   // Matter platform batch refresh options
   matterBatchRefreshRate?: number
   matterBatchConcurrency?: number

package/src/utils.ts

@@ -963,11 +963,20 @@ export class ApiRequestTracker {
   private date = ''
   private statsFile = ''
   private hourlyTimer?: NodeJS.Timeout
+  private midnightTimer?: NodeJS.Timeout
   private log: Logging
+  // Daily limits
+  private dailyLimit: number
+  private reserveForCommands: number
+  private lastWarn: Record<string, number> = {}
+  private pausePollingAtReserve = false
 
-  constructor(api: API, log: Logging, pluginName = 'SwitchBot') {
+  constructor(api: API, log: Logging, pluginName = 'SwitchBot', limits?: { dailyLimit?: number, reserveForCommands?: number, pausePollingAtReserve?: boolean }) {
     this.log = log
     this.statsFile = join(api.user.storagePath(), `${pluginName.toLowerCase()}-api-stats.json`)
+    this.dailyLimit = Math.max(0, Number(limits?.dailyLimit ?? 10000))
+    this.reserveForCommands = Math.max(0, Number(limits?.reserveForCommands ?? 1000))
+    this.pausePollingAtReserve = Boolean(limits?.pausePollingAtReserve ?? false)
     this.load()
   }
 
@@ -1038,6 +1047,50 @@ export class ApiRequestTracker {
     this.save()
   }
 
+  /**
+   * Attempt to spend from the daily budget for a request of a given kind.
+   * Kinds: 'command' (user actions), 'poll' (status refresh), 'discovery'.
+   * Returns true if allowed (and increments the counter), false if blocked.
+   */
+  public trySpend(kind: 'command' | 'poll' | 'discovery', n = 1): boolean {
+    const today = new Date().toISOString().split('T')[0]
+    if (this.date !== today) {
+      // Day rollover
+      this.log.debug?.(`[API Stats] Day rollover: ${this.count} requests on ${this.date}`)
+      this.count = 0
+      this.date = today
+      this.save()
+    }
+
+    const softCap = Math.max(0, this.dailyLimit - this.reserveForCommands)
+    const projected = this.count + n
+    const now = Date.now()
+    const overHardCap = projected > this.dailyLimit
+    const overSoftCap = projected > softCap
+    const shouldRateLimit = (kind === 'command')
+      ? overHardCap
+      : (this.pausePollingAtReserve ? overSoftCap : overHardCap)
+
+    if (shouldRateLimit) {
+      const warnKey = kind === 'command' ? 'hardcap' : 'softcap'
+      const last = this.lastWarn[warnKey] ?? 0
+      if (now - last > 10 * 60 * 1000) { // warn at most every 10 minutes
+        if (kind === 'command') {
+          this.log.error?.(`[API Stats] Daily limit (${this.dailyLimit}) reached. Blocking command requests until reset.`)
+        } else {
+          const remainingForCommands = Math.max(0, this.dailyLimit - this.count)
+          this.log.warn?.(`[API Stats] Near daily limit. Pausing ${kind} requests to reserve ~${this.reserveForCommands} calls for commands. Remaining today: ${remainingForCommands}`)
+        }
+        this.lastWarn[warnKey] = now
+      }
+      return false
+    }
+
+    this.count += n
+    this.save()
+    return true
+  }
+
   /**
    * Start hourly logging of API request count
    */
@@ -1054,9 +1107,13 @@ export class ApiRequestTracker {
         this.count = 0
         this.date = today
         this.save()
+        this.log.info?.('[API Stats] Polling resumed after daily reset')
       }
       this.log.info?.(`[API Stats] Today (${this.date}): ${this.count} API requests`)
     }, 60 * 60 * 1000) // Every hour
+
+    // Schedule an exact UTC midnight rollover log/reset
+    this.scheduleMidnightRollover()
   }
 
   /**
@@ -1067,6 +1124,10 @@ export class ApiRequestTracker {
       clearInterval(this.hourlyTimer)
       this.hourlyTimer = undefined
     }
+    if (this.midnightTimer) {
+      clearTimeout(this.midnightTimer)
+      this.midnightTimer = undefined
+    }
   }
 
   /**
@@ -1082,6 +1143,44 @@ export class ApiRequestTracker {
   public getDate(): string {
     return this.date
   }
+
+  /** Schedule a precise log/reset at the next UTC midnight */
+  private scheduleMidnightRollover(): void {
+    try {
+      // Clear any previous timer
+      if (this.midnightTimer) {
+        clearTimeout(this.midnightTimer)
+        this.midnightTimer = undefined
+      }
+      const now = new Date()
+      const nextUtcMidnightMs = Date.UTC(
+        now.getUTCFullYear(),
+        now.getUTCMonth(),
+        now.getUTCDate() + 1,
+        0,
+        0,
+        0,
+        0,
+      )
+      const delay = Math.max(1000, nextUtcMidnightMs - now.getTime())
+      this.midnightTimer = setTimeout(() => {
+        try {
+          const today = new Date().toISOString().split('T')[0]
+          if (this.date !== today) {
+            this.log.info?.(`[API Stats] Day rollover - Previous day (${this.date}): ${this.count} API requests`)
+            this.count = 0
+            this.date = today
+            this.save()
+          }
+          // Emit the precise resume line and a fresh today counter line
+          this.log.info?.('[API Stats] Polling resumed after daily reset')
+          this.log.info?.(`[API Stats] Today (${this.date}): ${this.count} API requests`)
+        } catch {}
+        // Reschedule for the next midnight
+        this.scheduleMidnightRollover()
+      }, delay)
+    } catch {}
+  }
 }
 
 /**