@switchbot/homebridge-switchbot 5.0.0-beta.42 → 5.0.0-beta.43

package/CHANGELOG.md

@@ -14,6 +14,8 @@ All notable changes to this project will be documented in this file. This projec
  - Centralize OpenAPI/BLE -> Matter mapping and expand BLE/OpenAPI parsing to include PM2.5/PM10/VOC/CO2, temperature/humidity, improved color parsing, and additional sensor/robot-vacuum fields.
  - Prefer accessory-specific update helpers where available; fall back to generic Matter updates otherwise.
  - Add unit tests covering BLE parsing, stale-accessory behavior, mapping helpers, and lifecycle cleanup.
+ - Add `options.dailyApiResetLocalMidnight` (boolean) to control whether the daily API budget resets at local midnight (true) or UTC midnight (false, default).
+ - Fix configuration schema placement for the "Reset Daily Counter at Local Midnight" option: remove erroneous insertion inside IR remote type list and expose it correctly under platform `options`.
 
 ## [4.3.1](https://github.com/OpenWonderLabs/homebridge-switchbot/releases/tag/v4.3.1) (2025-03-04)
 

package/README.md

@@ -238,6 +238,28 @@ Reliability and rate-limiting:
 
 These controls keep API usage smooth and predictable while preserving per-device control when needed.
 
+## OpenAPI rate limiting and daily budget
+
+To prevent hitting SwitchBot’s daily OpenAPI limit, the plugin provides several platform-level options under `options`:
+
+- `dailyApiLimit` (number, default 10000): maximum OpenAPI requests per day that the plugin will allow.
+- `dailyApiReserveForCommands` (number, default 1000): requests reserved for user actions so background polling pauses before the hard limit.
+- `webhookOnlyOnReserve` (boolean, default false): when remaining budget reaches the reserve, pause background polling/discovery; webhooks and commands continue until the hard limit.
+- `dailyApiResetLocalMidnight` (boolean, default false): if true, resets the daily counter at local midnight; when false, resets at UTC midnight.
+
+Example (excerpt):
+
+```json
+{
+  "options": {
+    "dailyApiLimit": 10000,
+    "dailyApiReserveForCommands": 1000,
+    "webhookOnlyOnReserve": false,
+    "dailyApiResetLocalMidnight": true
+  }
+}
+```
+
 ## SwitchBot APIs
 
 - [OpenWonderLabs/node-switchbot](https://github.com/OpenWonderLabs/node-switchbot)

package/config.schema.json

@@ -1593,6 +1593,12 @@
             "default": false,
             "description": "If true, completely stop background polling/discovery once the remaining budget hits the reserve. Webhooks and commands still work until the hard limit."
           },
+          "dailyApiResetLocalMidnight": {
+            "title": "Reset Daily Counter at Local Midnight",
+            "type": "boolean",
+            "default": false,
+            "description": "If enabled, the daily API counter resets at local (system timezone) midnight. When disabled, it resets at UTC midnight."
+          },
           "logging": {
             "title": "Logging Setting",
             "type": "string",
@@ -1858,6 +1864,10 @@
           "key": "options.keepStaleAccessories",
           "description": "<em class='primary-text'>If true, previously-registered accessories for devices that are no longer discovered or configured will be kept on the bridge. Default: false (stale accessories are removed automatically).</em>"
         },
+        {
+          "key": "options.dailyApiResetLocalMidnight",
+          "description": "<em class='primary-text'>If true, the daily API request counter will reset at local midnight (system timezone). If false (default), it will reset at UTC midnight.</em>"
+        },
         {
           "key": "options.allowInvalidCharacters",
           "description": "<em class='primary-text'>Allows device names with characters that are normally invalid in HomeKit. Use with caution, as this may lead to unexpected behavior.</em>"

package/dist/platform-hap.d.ts

@@ -143,6 +143,11 @@ export declare class SwitchBotHAPPlatform implements DynamicPlatformPlugin {
      * @returns {Promise<void>} A promise that resolves when the version has been retrieved and logged.
      */
     getVersion(): Promise<void>;
+    /**
+     * Validate that the user's configuration won't exceed API limits
+     * Warn if device count × polling frequency will hit daily limits
+     */
+    private validateApiUsageConfig;
     /**
      * Validate and clean a string value for a Name Characteristic.
      * @param displayName - The display name of the accessory.

package/dist/platform-hap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"platform-hap.d.ts","sourceRoot":"","sources":["../src/platform-hap.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"platform-hap.d.ts","sourceRoot":"","sources":["../src/platform-hap.ts"],"names":[],"mappings":"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"}

package/dist/platform-hap.js

@@ -203,6 +203,7 @@ export class SwitchBotHAPPlatform {
                     dailyLimit: dailyApiLimit,
                     reserveForCommands: dailyApiReserveForCommands,
                     pausePollingAtReserve: webhookOnlyOnReserve,
+                    resetAtLocalMidnight: this.config.options?.dailyApiResetAtLocalMidnight ?? false,
                 });
                 this.apiTracker.startHourlyLogging();
             }
@@ -465,8 +466,12 @@ export class SwitchBotHAPPlatform {
                 const { response, statusCode } = await this.switchBotAPI.getDevices();
                 this.debugLog(`response: ${JSON.stringify(response)}`);
                 if (this.isSuccessfulResponse(statusCode)) {
-                    await this.handleDevices(Array.isArray(response.body.deviceList) ? response.body.deviceList : []);
-                    await this.handleIRDevices(Array.isArray(response.body.infraredRemoteList) ? response.body.infraredRemoteList : []);
+                    const deviceList = Array.isArray(response.body.deviceList) ? response.body.deviceList : [];
+                    const irDeviceList = Array.isArray(response.body.infraredRemoteList) ? response.body.infraredRemoteList : [];
+                    await this.handleDevices(deviceList);
+                    await this.handleIRDevices(irDeviceList);
+                    // Diagnostic: warn users if their device count + refresh rate may exceed daily limits
+                    this.validateApiUsageConfig(deviceList.length, irDeviceList.length);
                     break;
                 }
                 else {
@@ -2777,23 +2782,25 @@ export class SwitchBotHAPPlatform {
         });
     }
     async retryRequest(device, deviceMaxRetries, deviceDelayBetweenRetries) {
+        // Check API budget BEFORE attempting any retries - don't waste cycles on blocked requests
+        if (!this.apiTracker?.trySpend('poll')) {
+            // Don't log on every blocked request - the ApiRequestTracker handles periodic warnings
+            return {
+                response: {
+                    deviceId: '',
+                    deviceType: '',
+                    hubDeviceId: '',
+                    version: 0,
+                    deviceName: '',
+                },
+                statusCode: 429,
+            };
+        }
         let retryCount = 0;
         const maxRetries = deviceMaxRetries;
         const delayBetweenRetries = deviceDelayBetweenRetries;
         while (retryCount < maxRetries) {
             try {
-                if (!this.apiTracker?.trySpend('poll')) {
-                    return {
-                        response: {
-                            deviceId: '',
-                            deviceType: '',
-                            hubDeviceId: '',
-                            version: 0,
-                            deviceName: '',
-                        },
-                        statusCode: 429,
-                    };
-                }
                 const { response, statusCode } = await this.switchBotAPI.getDeviceStatus(device.deviceId, this.config.credentials?.token, this.config.credentials?.secret);
                 this.debugLog(`response: ${JSON.stringify(response)}`);
                 return { response, statusCode };
@@ -2909,6 +2916,53 @@ export class SwitchBotHAPPlatform {
         this.debugLog(`Plugin Version: ${version}`);
         this.version = version;
     }
+    /**
+     * Validate that the user's configuration won't exceed API limits
+     * Warn if device count × polling frequency will hit daily limits
+     */
+    validateApiUsageConfig(deviceCount, irDeviceCount) {
+        try {
+            const totalDevices = deviceCount + irDeviceCount;
+            if (totalDevices === 0) {
+                return;
+            }
+            const refreshRate = this.platformRefreshRate ?? 300; // seconds
+            const dailyLimit = this.config.options?.dailyApiLimit ?? 10000;
+            const reserveForCommands = this.config.options?.dailyApiReserveForCommands ?? 1000;
+            // Calculate polls per day (86400 seconds in a day)
+            const pollsPerDevicePerDay = Math.floor(86400 / refreshRate);
+            const totalPollsPerDay = pollsPerDevicePerDay * totalDevices;
+            // Add discovery calls (typically 1-2 per day)
+            const estimatedDiscoveryCalls = 2;
+            const totalEstimatedCalls = totalPollsPerDay + estimatedDiscoveryCalls;
+            const usableLimit = dailyLimit - reserveForCommands;
+            const percentOfLimit = Math.round((totalEstimatedCalls / usableLimit) * 100);
+            this.debugLog(`[API Usage Diagnostic] ${totalDevices} devices × ${pollsPerDevicePerDay} polls/day = ${totalPollsPerDay} estimated daily polls`);
+            this.debugLog(`[API Usage Diagnostic] With ${reserveForCommands} reserved for commands, usable limit is ${usableLimit}`);
+            if (totalEstimatedCalls > dailyLimit) {
+                this.errorLog(`⚠️ API LIMIT WARNING: Your configuration will exceed the daily API limit!`);
+                this.errorLog(`   Devices: ${totalDevices} | Refresh rate: ${refreshRate}s | Estimated daily polls: ${totalEstimatedCalls}`);
+                this.errorLog(`   Daily limit: ${dailyLimit} | You will use ${percentOfLimit}% of available budget`);
+                this.errorLog(`   SOLUTION: Increase refreshRate to ${Math.ceil((totalDevices * 86400) / usableLimit)} seconds or higher`);
+                this.errorLog(`   OR: Enable webhooks and set 'webhookOnlyOnReserve: true' to reduce polling`);
+            }
+            else if (totalEstimatedCalls > usableLimit) {
+                this.warnLog(`⚠️ API USAGE WARNING: Configuration may exceed usable daily API budget`);
+                this.warnLog(`   Devices: ${totalDevices} | Refresh rate: ${refreshRate}s | Estimated daily polls: ${totalEstimatedCalls}`);
+                this.warnLog(`   Usable limit (after reserve): ${usableLimit} | You will use ${percentOfLimit}% of budget`);
+                this.warnLog(`   Polling may pause when approaching limit. Consider increasing refreshRate to ${Math.ceil((totalDevices * 86400) / usableLimit)}s`);
+            }
+            else if (percentOfLimit > 75) {
+                this.infoLog(`[API Usage] Using ${percentOfLimit}% of daily budget (${totalEstimatedCalls}/${usableLimit} calls). Monitor usage if adding more devices.`);
+            }
+            else {
+                this.debugLog(`[API Usage] Configuration looks good: ${percentOfLimit}% of daily budget (${totalEstimatedCalls}/${usableLimit} calls)`);
+            }
+        }
+        catch (e) {
+            this.debugErrorLog(`Failed to validate API usage config: ${e.message ?? e}`);
+        }
+    }
     /**
      * Validate and clean a string value for a Name Characteristic.
      * @param displayName - The display name of the accessory.