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

package/dist/platform-matter.d.ts

@@ -172,6 +172,11 @@ export declare class SwitchBotMatterPlatform implements DynamicPlatformPlugin {
     private batchRefreshAllDevices;
     /** Refresh a single device with retry and backoff; returns status object if successful */
     private refreshSingleDeviceWithRetry;
+    /**
+     * Validate that the user's configuration won't exceed API limits
+     * Warn if device count × polling frequency will hit daily limits
+     */
+    private validateApiUsageConfig;
     /** Simple concurrency limiter for an array of items */
     private runWithConcurrency;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"platform-matter.d.ts","sourceRoot":"","sources":["../src/platform-matter.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"platform-matter.d.ts","sourceRoot":"","sources":["../src/platform-matter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,GAAG,EACH,qBAAqB,EACrB,OAAO,EAEP,yBAAyB,EAC1B,MAAM,YAAY,CAAA;AAEnB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,EAAY,MAAM,gBAAgB,CAAA;AAElE,OAAO,KAAK,EAAkC,uBAAuB,EAAE,MAAM,eAAe,CAAA;AAkC5F,qBAAa,uBAAwB,YAAW,qBAAqB;aAsDjD,GAAG,EAAE,OAAO;aACZ,MAAM,EAAE,uBAAuB;aAC/B,GAAG,EAAE,GAAG;IAlD1B,SAAgB,iBAAiB,EAAE,GAAG,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAY;IAErF,OAAO,CAAC,YAAY,CAAC,CAAkB;IACvC,OAAO,CAAC,YAAY,CAAC,CAAc;IAEnC,OAAO,CAAC,iBAAiB,CAAe;IAExC,OAAO,CAAC,mBAAmB,CAAiB;IAE5C,OAAO,CAAC,kBAAkB,CAA8B;IAExD,OAAO,CAAC,aAAa,CAAyC;IAE9D,OAAO,CAAC,oBAAoB,CAAC,CAAgB;IAE7C,OAAO,CAAC,iBAAiB,CAA8B;IAEvD,OAAO,CAAC,gBAAgB,CAAiC;IACzD,OAAO,CAAC,eAAe,CAAC,CAAQ;IAEhC,OAAO,CAAC,mBAAmB,CAAyB;IAEpD,OAAO,CAAC,eAAe,CAA8C;IAGrE,OAAO,CAAC,UAAU,CAA0B;IAC5C,OAAO,CAAC,oBAAoB,CAAsB;IAClD,OAAO,CAAC,mBAAmB,CAA8C;IAGzE,OAAO,CAAC,eAAe,CAAC,CAAQ;IAGhC,OAAO,CAAC,UAAU,CAAC,CAAmB;IAGtC,OAAO,EAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;IAClC,UAAU,EAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;IACrC,eAAe,EAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;IAC1C,OAAO,EAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;IAClC,YAAY,EAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;IACvC,QAAQ,EAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;IACnC,aAAa,EAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;IACxC,QAAQ,EAAG,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;IACnC,cAAc,EAAG,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;IACvC,uBAAuB,EAAG,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;gBAG9B,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,uBAAuB,EAC/B,GAAG,EAAE,GAAG;IAmQ1B;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAIzB,6DAA6D;IAC7D,OAAO,CAAC,wBAAwB;IAOhC;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAoC5B;;;OAGG;YACW,sBAAsB;IAwCpC;;;OAGG;YACW,wBAAwB;IA4CtC;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAW5B;;;OAGG;YACW,yBAAyB;IAumBvC;;OAEG;YACW,eAAe;IA4C7B;;;OAGG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IA8BhC;;;OAGG;IACG,YAAY;IAkClB;;OAEG;IACG,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,SAAI,EAAE,mBAAmB,SAAO,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,GAAG,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IA+BzJ;;;OAGG;IACH,OAAO,CAAC,2BAA2B;IA6InC;;;;OAIG;YACW,sBAAsB;IAwXpC;;;OAGG;IACH,kBAAkB;IAMlB;;;;;OAKG;IACH,wBAAwB,CAAC,SAAS,EAAE,yBAAyB;IAK7D;;OAEG;YACW,yBAAyB;IAwJvC;;;OAGG;YACW,oCAAoC;IAkDlD;;OAEG;YACW,yBAAyB;IA8CvC;;OAEG;YACW,wBAAwB;IA8CtC;;OAEG;YACW,0BAA0B;IAsBxC;;OAEG;YACW,wBAAwB;IAsBtC;;OAEG;YACW,uBAAuB;IA0DrC;;OAEG;YACW,uBAAuB;IAkCrC;;OAEG;YACW,oBAAoB;IA4BlC;;;;;OAKG;YACW,wBAAwB;IAsBtC;;;;;;OAMG;YACW,qBAAqB;IAsBnC;;OAEG;IACH,OAAO,CAAC,yBAAyB;IA0BjC;;;OAGG;YACW,sBAAsB;IAsDpC,0FAA0F;YAC5E,4BAA4B;IA0C1C;;;OAGG;IACH,OAAO,CAAC,sBAAsB;IA+C9B,uDAAuD;YACzC,kBAAkB;CAiBjC"}

package/dist/platform-matter.js

@@ -139,6 +139,7 @@ export class SwitchBotMatterPlatform {
                     dailyLimit: this.config.options?.dailyApiLimit ?? 10000,
                     reserveForCommands: this.config.options?.dailyApiReserveForCommands ?? 1000,
                     pausePollingAtReserve: this.config.options?.webhookOnlyOnReserve ?? false,
+                    resetAtLocalMidnight: this.config.options?.dailyApiResetAtLocalMidnight ?? false,
                 });
                 this.apiTracker.startHourlyLogging();
             }
@@ -384,6 +385,15 @@ export class SwitchBotMatterPlatform {
         // Merge per-device overrides by matching deviceId
         const allowConfigOnly = Boolean(this.config.options?.allowConfigOnlyDevices);
         const merged = mergeByDeviceId(this.config.options?.devices ?? [], devicesWithTemplates ?? [], allowConfigOnly);
+        // Apply global webhook setting if not explicitly set on individual devices
+        if (this.config.options?.webhook === true) {
+            merged.forEach((device) => {
+                if (device.webhook === undefined) {
+                    device.webhook = true;
+                    this.debugLog(`Applied global webhook setting to Matter device: ${device.deviceId}`);
+                }
+            });
+        }
         return merged;
     }
     /**
@@ -412,6 +422,15 @@ export class SwitchBotMatterPlatform {
         // Merge per-device overrides by matching deviceId
         const allowConfigOnly = Boolean(this.config.options?.allowConfigOnlyDevices);
         const merged = mergeByDeviceId(this.config.options?.irdevices ?? [], devicesWithTemplates ?? [], allowConfigOnly);
+        // Apply global webhook setting if not explicitly set on individual IR devices
+        if (this.config.options?.webhook === true) {
+            merged.forEach((device) => {
+                if (device.webhook === undefined) {
+                    device.webhook = true;
+                    this.debugLog(`Applied global webhook setting to Matter IR device: ${device.deviceId}`);
+                }
+            });
+        }
         return merged;
     }
     /**
@@ -460,8 +479,19 @@ export class SwitchBotMatterPlatform {
                 // so accessories can decide how verbose they should be.
                 deviceLogging: dev?.logging,
                 platformLogging: this.platformLogging,
+                // Expose effective webhook setting for parity with HAP base device logic
+                // Prefer explicit per-device setting; otherwise fall back to global option
+                webhook: dev?.webhook !== undefined ? dev.webhook : (this.config.options?.webhook === true ? true : undefined),
             },
         };
+        // Log effective webhook for diagnostics
+        try {
+            const effectiveWebhook = dev?.webhook !== undefined ? dev.webhook : (this.config.options?.webhook === true ? true : undefined);
+            this.debugLog(`Effective webhook for Matter device ${displayName} (${dev.deviceId}): ${String(effectiveWebhook)}`);
+        }
+        catch (e) {
+            this.debugLog(`Failed logging effective webhook for Matter device ${displayName} (${dev.deviceId}): ${e?.message ?? e}`);
+        }
         // Build platform-side helpers using shared factories so they can be reused/tested
         const sendOpenAPI = makeOpenAPISender(this.retryCommand.bind(this), dev, { maxRetries: this.config.options?.maxRetries ?? 1, delayBetweenRetries: this.config.options?.delayBetweenRetries ?? 1000 });
         const sendBLE = makeBLESender(this.switchBotBLE, dev, { bleRetries: this.config.options?.bleRetries ?? 2, bleRetryDelay: this.config.options?.bleRetryDelay ?? 500 });
@@ -536,6 +566,7 @@ export class SwitchBotMatterPlatform {
             // Locks
             'Smart Lock': DoorLockAccessory,
             'Smart Lock Pro': DoorLockAccessory,
+            'Smart Lock Ultra': DoorLockAccessory,
             // Sensors
             'Motion Sensor': OccupancySensorAccessory,
             'Contact Sensor': ContactSensorAccessory,
@@ -1060,6 +1091,8 @@ export class SwitchBotMatterPlatform {
                 for (const d of irDeviceList) {
                     this.debugLog(`  - ${d.deviceName} (${d.remoteType}) id=${d.deviceId}`);
                 }
+                // Diagnostic: warn users if their device count + refresh rate may exceed daily limits
+                this.validateApiUsageConfig(deviceList.length, irDeviceList.length);
             }
             else {
                 this.warnLog(`SwitchBot getDevices returned status ${statusCode}`);
@@ -1153,15 +1186,16 @@ export class SwitchBotMatterPlatform {
      * Retry wrapper for control commands using SwitchBot OpenAPI
      */
     async retryCommand(deviceObj, bodyChange, maxRetries = 1, delayBetweenRetries = 1000) {
+        // Check API budget BEFORE attempting any retries
+        if (!this.apiTracker?.trySpend('command')) {
+            return { response: {}, statusCode: 429 };
+        }
         let retryCount = 0;
         while (retryCount < maxRetries) {
             try {
                 if (!this.switchBotAPI) {
                     throw new Error('SwitchBot OpenAPI not initialized');
                 }
-                if (!this.apiTracker?.trySpend('command')) {
-                    return { response: {}, statusCode: 429 };
-                }
                 const { response, statusCode } = await this.switchBotAPI.controlDevice(deviceObj.deviceId, bodyChange.command, bodyChange.parameter, bodyChange.commandType, this.config.credentials?.token, this.config.credentials?.secret);
                 return { response, statusCode };
             }
@@ -1412,6 +1446,41 @@ export class SwitchBotMatterPlatform {
                     this.debugLog(`Failed to apply runState for ${dev.deviceId}: ${e?.message ?? e}`);
                 }
             }
+            // Robot vacuum: some firmwares expose 'taskType' or 'task' with similar semantics
+            // to runState (e.g., 'cleaning', 'mapping', 'idle'). Map to rvcRunMode accordingly.
+            if (status?.taskType !== undefined || status?.task_type !== undefined || status?.task !== undefined) {
+                try {
+                    const raw = status?.taskType ?? status?.task_type ?? status?.task;
+                    let mode;
+                    if (typeof raw === 'number') {
+                        mode = Number(raw);
+                    }
+                    else if (typeof raw === 'string') {
+                        const s = raw.toLowerCase();
+                        if (s.includes('clean')) {
+                            mode = 1; // Cleaning
+                        }
+                        else if (s.includes('map')) {
+                            mode = 2; // Mapping
+                        }
+                        else if (s.includes('idle') || s.includes('stop') || s.includes('dock') || s.includes('charge') || s.includes('docked')) {
+                            mode = 0; // Idle
+                        }
+                        else {
+                            const n = Number(raw);
+                            if (!Number.isNaN(n)) {
+                                mode = n;
+                            }
+                        }
+                    }
+                    if (mode !== undefined) {
+                        await safeUpdate('rvcRunMode', { currentMode: Number(mode) }, 'updateRunMode');
+                    }
+                }
+                catch (e) {
+                    this.debugLog(`Failed to apply taskType for ${dev.deviceId}: ${e?.message ?? e}`);
+                }
+            }
             // Brightness
             if (status?.brightness !== undefined) {
                 const rawBrightness = Number(status.brightness);
@@ -1473,7 +1542,8 @@ export class SwitchBotMatterPlatform {
             }
             // 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) {
+            if (status?.battery !== undefined || status?.batt !== undefined || status?.batteryLevel !== undefined || status?.batteryPercentage !== undefined || status?.battery_level !== undefined
+                || status?.baseBattery !== undefined || status?.base_battery !== undefined || status?.stationBattery !== undefined || status?.waterBaseBattery !== undefined || status?.dockBattery !== undefined) {
                 // 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'];
@@ -1482,7 +1552,8 @@ export class SwitchBotMatterPlatform {
                 }
                 else {
                     try {
-                        const percentage = Number(status?.battery ?? status?.batt ?? status?.batteryPercentage ?? status?.batteryLevel ?? status?.battery_level);
+                        const percentage = Number(status?.battery ?? status?.batt ?? status?.batteryPercentage ?? status?.batteryLevel ?? status?.battery_level
+                            ?? status?.baseBattery ?? status?.base_battery ?? status?.stationBattery ?? status?.waterBaseBattery ?? status?.dockBattery);
                         const batPercentRemaining = Math.max(0, Math.min(200, Math.round(percentage * 2)));
                         let batChargeLevel = 0;
                         if (percentage < 20) {
@@ -2250,12 +2321,14 @@ export class SwitchBotMatterPlatform {
     /** Refresh a single device with retry and backoff; returns status object if successful */
     async refreshSingleDeviceWithRetry(dev, retries = 3, baseDelayMs = 500) {
         const deviceId = dev.deviceId;
+        // 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 null;
+        }
         let attempt = 0;
         while (attempt <= retries) {
             try {
-                if (!this.apiTracker?.trySpend('poll')) {
-                    return null;
-                }
                 const { response, statusCode } = await this.switchBotAPI.getDeviceStatus(deviceId, this.config.credentials?.token, this.config.credentials?.secret);
                 const respAny = response;
                 const body = respAny?.body ?? respAny;
@@ -2287,6 +2360,54 @@ export class SwitchBotMatterPlatform {
         catch { }
         return null;
     }
+    /**
+     * 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;
+            }
+            // For Matter platform, use matterBatchRefreshRate or fallback to refreshRate
+            const refreshRate = this.getPlatformBatchInterval(); // 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 matterBatchRefreshRate 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 matterBatchRefreshRate 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.debugLog(`Failed to validate API usage config: ${e?.message ?? e}`);
+        }
+    }
     /** Simple concurrency limiter for an array of items */
     async runWithConcurrency(items, worker, concurrency) {
         const queue = items.slice();