@switchbot/homebridge-switchbot 5.0.0-beta.5 → 5.0.0-beta.50

package/dist/platform-hap.js

@@ -36,7 +36,7 @@ import { TV } from './irdevice/tv.js';
 import { VacuumCleaner } from './irdevice/vacuumcleaner.js';
 import { WaterHeater } from './irdevice/waterheater.js';
 import { PLATFORM_NAME, PLUGIN_NAME } from './settings.js';
-import { cleanDeviceConfig, formatDeviceIdAsMac, isBlindTiltDevice, isCurtainDevice, safeStringify, sleep } from './utils.js';
+import { ApiRequestTracker, applyDeviceTypeTemplates, createPlatformLogger, formatDeviceIdAsMac, isBlindTiltDevice, isCurtainDevice, isSuccessfulStatusCode, logStatusCode, mergeByDeviceId, safeStringify, sleep } from './utils.js';
 /**
  * HomebridgePlatform
  * This class is the main constructor for your plugin, this is where you should
@@ -47,6 +47,17 @@ export class SwitchBotHAPPlatform {
     accessories = [];
     api;
     log;
+    // Logging helper functions (attached from utils.createPlatformLogger in constructor)
+    infoLog;
+    successLog;
+    debugSuccessLog;
+    warnLog;
+    debugWarnLog;
+    errorLog;
+    debugErrorLog;
+    debugLog;
+    loggingIsDebug;
+    enablingPlatformLogging;
     // Configuration properties
     platformConfig;
     platformLogging;
@@ -64,6 +75,8 @@ export class SwitchBotHAPPlatform {
     // SwitchBot APIs
     switchBotAPI;
     switchBotBLE;
+    // API request tracking
+    apiTracker;
     // External APIs
     eve;
     fakegatoAPI;
@@ -73,9 +86,21 @@ export class SwitchBotHAPPlatform {
     constructor(log, config, api) {
         this.api = api;
         this.log = log;
+        // Attach shared platform logging helpers (moved to utils for reuse)
+        const _pl = createPlatformLogger(async () => this.platformLogging, this.log);
+        this.infoLog = _pl.infoLog;
+        this.successLog = _pl.successLog;
+        this.debugSuccessLog = _pl.debugSuccessLog;
+        this.warnLog = _pl.warnLog;
+        this.debugWarnLog = _pl.debugWarnLog;
+        this.errorLog = _pl.errorLog;
+        this.debugErrorLog = _pl.debugErrorLog;
+        this.debugLog = _pl.debugLog;
+        this.loggingIsDebug = _pl.loggingIsDebug;
+        this.enablingPlatformLogging = _pl.enablingPlatformLogging;
         // only load if configured
         if (!config) {
-            this.log.error('No configuration found for the plugin, please check your config.');
+            this.errorLog('No configuration found for the plugin, please check your config.');
             return;
         }
         // Plugin options into our config variables.
@@ -86,23 +111,21 @@ export class SwitchBotHAPPlatform {
             options: config.options,
             devices: config.devices,
         };
-        // Normalize deviceConfig to remove UI-inserted defaults (lots of false/empty values)
+        // Determine platform logging preference (match HAP behaviour as closely as
+        // possible using config values. We default to 'standard' when unspecified.)
+        this.platformLogging = (this.config.options?.logging === 'debug' || this.config.options?.logging === 'standard' || this.config.options?.logging === 'none')
+            ? this.config.options.logging
+            : 'standard';
+        // Unconditional diagnostic using the raw Homebridge `log` so it always
+        // appears regardless of the platform logging helpers' gating logic.
         try {
-            if (this.config.options) {
-                const cleaned = cleanDeviceConfig(this.config.options.deviceConfig);
-                if (cleaned) {
-                    ;
-                    this.config.options.deviceConfig = cleaned;
-                }
-                else {
-                    // remove the empty deviceConfig so downstream checks treat it as absent
-                    delete this.config.options.deviceConfig;
-                }
-            }
+            this.log.debug?.(`[SwitchBot HAP] effective platformLogging=${String(this.platformLogging)}`);
         }
         catch (e) {
-            this.debugErrorLog(`Failed to clean deviceConfig: ${e}`);
+            // swallow any logging errors — diagnostics are best-effort
         }
+        // Note: deviceConfig and irdeviceConfig have been removed from the platform.
+        // All device-specific configuration should be done via options.devices and options.irdevices arrays.
         // Plugin Configuration
         this.getPlatformLogSettings();
         this.getPlatformRateSettings();
@@ -171,20 +194,36 @@ export class SwitchBotHAPPlatform {
         // to start discovery of new accessories.
         this.api.on('didFinishLaunching', async () => {
             this.debugLog('Executed didFinishLaunching callback');
+            // Initialize API request tracking
+            try {
+                const dailyApiLimit = this.config.options?.dailyApiLimit ?? 10000;
+                const dailyApiReserveForCommands = this.config.options?.dailyApiReserveForCommands ?? 1000;
+                const webhookOnlyOnReserve = this.config.options?.webhookOnlyOnReserve ?? false;
+                this.apiTracker = new ApiRequestTracker(this.api, this.log, 'SwitchBot HAP', {
+                    dailyLimit: dailyApiLimit,
+                    reserveForCommands: dailyApiReserveForCommands,
+                    pausePollingAtReserve: webhookOnlyOnReserve,
+                    resetAtLocalMidnight: this.config.options?.dailyApiResetAtLocalMidnight ?? false,
+                });
+                this.apiTracker.startHourlyLogging();
+            }
+            catch (e) {
+                this.errorLog(`Failed to initialize API request tracking: ${e.message ?? e}`);
+            }
             // run the method to discover / register your devices as accessories
             try {
                 // Does the user have a version of Homebridge that is compatible with matter?
                 if (!this.api.isMatterAvailable?.()) {
-                    this.log.debug(`Matter is not available in this version of Homebridge. Please update Homebridge to use this plugin, ${this.api.isMatterAvailable?.() ? '' : ' (Matter is not available in this version of Homebridge)'}`);
+                    this.debugLog(`Matter is not available in this version of Homebridge. Please update Homebridge to use this plugin, ${this.api.isMatterAvailable?.() ? '' : ' (Matter is not available in this version of Homebridge)'}`);
                 }
                 if (!this.api.isMatterEnabled?.()) {
-                    this.log.debug(`Matter is not enabled in Homebridge. Please enable Matter in the Homebridge settings to use this plugin, ${this.api.isMatterEnabled?.() ? '' : ' (Matter is not enabled in Homebridge)'}`);
+                    this.debugLog(`Matter is not enabled in Homebridge. Please enable Matter in the Homebridge settings to use this plugin, ${this.api.isMatterEnabled?.() ? '' : ' (Matter is not enabled in Homebridge)'}`);
                 }
                 if (!this.api.isMatterAvailable?.() && !this.api.isMatterEnabled?.()) {
                     await this.discoverDevices();
                 }
                 else {
-                    this.log.info('Matter is enabled in Homebridge. SwitchBot Matter devices will be handled by the Matter platform.');
+                    this.infoLog('Matter is enabled in Homebridge. SwitchBot Matter devices will be handled by the Matter platform.');
                 }
             }
             catch (e) {
@@ -413,19 +452,36 @@ export class SwitchBotHAPPlatform {
         let retryCount = 0;
         const maxRetries = this.platformMaxRetries ?? 5;
         const delayBetweenRetries = this.platformDelayBetweenRetries || 5000;
+        let rateLimitExceeded = false;
         this.debugWarnLog(`Retry Count: ${retryCount}`);
         this.debugWarnLog(`Max Retries: ${this.platformMaxRetries}`);
         this.debugWarnLog(`Delay Between Retries: ${this.platformDelayBetweenRetries}`);
         while (retryCount < maxRetries) {
             try {
+                if (!this.apiTracker?.trySpend('discovery')) {
+                    rateLimitExceeded = true;
+                    this.warnLog('OpenAPI daily budget reached (discovery blocked). Falling back to manual device configuration.');
+                    break;
+                }
                 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 {
+                    // Check if rate limit exceeded (429)
+                    if (statusCode === 429) {
+                        rateLimitExceeded = true;
+                        this.warnLog('OpenAPI rate limit (429) exceeded. Falling back to manual device configuration.');
+                        this.warnLog('Webhook functionality will still work if devices are configured manually.');
+                        break;
+                    }
                     await this.handleErrorResponse(statusCode, retryCount, maxRetries, delayBetweenRetries);
                     retryCount++;
                 }
@@ -436,8 +492,110 @@ export class SwitchBotHAPPlatform {
                 this.debugErrorLog(`Failed to Discover Devices, Error: ${e.message ?? e}`);
             }
         }
+        // If rate limit exceeded or retries exhausted, try to load from manual config or cached accessories
+        if (rateLimitExceeded || retryCount >= maxRetries) {
+            const hasCachedAccessories = this.accessories.length > 0;
+            const hasManualConfig = this.config.options?.devices || this.config.options?.irdevices;
+            if (hasManualConfig || hasCachedAccessories) {
+                if (hasCachedAccessories) {
+                    this.warnLog(`Found ${this.accessories.length} cached accessories from previous sessions.`);
+                    this.warnLog('Reinstantiating device classes to enable webhook handlers...');
+                    await this.restoreCachedAccessories();
+                }
+                if (hasManualConfig) {
+                    this.warnLog('Attempting to load devices from manual configuration...');
+                    await this.handleManualConfig();
+                }
+                if (hasCachedAccessories) {
+                    this.infoLog('Cached accessories restored. Webhook functionality is active.');
+                    this.infoLog('Device discovery will resume when API rate limit resets.');
+                }
+            }
+            else {
+                this.errorLog('OpenAPI unavailable and no cached accessories or manual device configuration found.');
+                this.errorLog('Please configure devices manually in the plugin settings to use webhook functionality.');
+            }
+        }
+    }
+    /**
+     * Restore cached accessories by reinstantiating their device classes
+     * This ensures webhook handlers and other functionality are properly set up
+     */
+    async restoreCachedAccessories() {
+        this.debugLog('Restoring cached accessories and setting up webhook handlers...');
+        for (const accessory of this.accessories) {
+            try {
+                const device = accessory.context.device;
+                const deviceType = accessory.context.deviceType || device?.deviceType;
+                const deviceId = accessory.context.deviceId || device?.deviceId;
+                if (!device || !deviceType || !deviceId) {
+                    this.debugWarnLog(`Skipping cached accessory ${accessory.displayName} - missing context data`);
+                    continue;
+                }
+                this.debugLog(`Reinstantiating ${deviceType} for cached accessory: ${accessory.displayName}`);
+                // Reinstantiate the device class based on deviceType
+                const deviceTypeHandlers = {
+                    'Humidifier': Humidifier,
+                    'Humidifier2': Humidifier,
+                    'Hub 2': Hub,
+                    'Hub 3': Hub,
+                    'Bot': Bot,
+                    'Relay Switch 1': RelaySwitch,
+                    'Relay Switch 1PM': RelaySwitch,
+                    'Meter': Meter,
+                    'MeterPlus': MeterPlus,
+                    'Meter Plus (JP)': MeterPlus,
+                    'MeterPro': MeterPro,
+                    'MeterPro(CO2)': MeterPro,
+                    'WoIOSensor': IOSensor,
+                    'Water Detector': WaterDetector,
+                    'Motion Sensor': Motion,
+                    'Contact Sensor': Contact,
+                    'Curtain': Curtain,
+                    'Curtain3': Curtain,
+                    'WoRollerShade': Curtain,
+                    'Roller Shade': Curtain,
+                    'Blind Tilt': BlindTilt,
+                    'Plug': Plug,
+                    'Plug Mini (US)': Plug,
+                    'Plug Mini (JP)': Plug,
+                    'Smart Lock': Lock,
+                    'Smart Lock Pro': Lock,
+                    'Smart Lock Ultra': Lock,
+                    'Color Bulb': ColorBulb,
+                    'K10+': RobotVacuumCleaner,
+                    'K10+ Pro': RobotVacuumCleaner,
+                    'WoSweeper': RobotVacuumCleaner,
+                    'WoSweeperMini': RobotVacuumCleaner,
+                    'Robot Vacuum Cleaner S1': RobotVacuumCleaner,
+                    'Robot Vacuum Cleaner S1 Plus': RobotVacuumCleaner,
+                    'Robot Vacuum Cleaner S10': RobotVacuumCleaner,
+                    'Ceiling Light': CeilingLight,
+                    'Ceiling Light Pro': CeilingLight,
+                    'Strip Light': StripLight,
+                    'Battery Circulator Fan': Fan,
+                    'Air Purifier PM2.5': AirPurifier,
+                    'Air Purifier Table PM2.5': AirPurifier,
+                    'Air Purifier VOC': AirPurifier,
+                    'Air Purifier Table VOC': AirPurifier,
+                };
+                const DeviceClass = deviceTypeHandlers[deviceType];
+                if (DeviceClass) {
+                    new DeviceClass(this, accessory, device);
+                    this.debugSuccessLog(`Successfully restored ${deviceType}: ${accessory.displayName}`);
+                }
+                else {
+                    this.debugLog(`No handler for device type: ${deviceType}`);
+                }
+            }
+            catch (e) {
+                this.errorLog(`Failed to restore cached accessory ${accessory.displayName}, Error: ${e.message ?? e}`);
+            }
+        }
+        this.infoLog(`Restored ${this.accessories.length} cached accessories with webhook support`);
     }
     async handleManualConfig() {
+        // Handle regular devices
         if (this.config.options?.devices) {
             this.debugLog(`SwitchBot Device Manual Config Set: ${JSON.stringify(this.config.options?.devices)}`);
             const devices = this.config.options.devices.map((v) => v);
@@ -456,15 +614,37 @@ export class SwitchBotHAPPlatform {
                 }
             }
         }
-        else {
+        // Handle IR devices
+        if (this.config.options?.irdevices) {
+            this.debugLog(`SwitchBot IR Device Manual Config Set: ${JSON.stringify(this.config.options?.irdevices)}`);
+            const irdevices = this.config.options.irdevices.map((v) => v);
+            for (const irdevice of irdevices) {
+                irdevice.remoteType = irdevice.configRemoteType !== undefined ? irdevice.configRemoteType : 'Unknown';
+                irdevice.deviceName = irdevice.configDeviceName !== undefined ? irdevice.configDeviceName : 'Unknown';
+                try {
+                    this.debugLog(`IR deviceId: ${irdevice.deviceId}`);
+                    if (irdevice.remoteType) {
+                        await this.createIRDevice(irdevice);
+                    }
+                }
+                catch (error) {
+                    this.errorLog(`failed to create IR device, Error: ${error}`);
+                }
+            }
+        }
+        if (!this.config.options?.devices && !this.config.options?.irdevices) {
             this.errorLog('Neither SwitchBot Token or Device Config are set.');
         }
     }
+    /**
+     * Check if an API status code indicates success
+     * @deprecated Use shared isSuccessfulStatusCode from utils.js instead
+     */
     isSuccessfulResponse(apiStatusCode) {
-        return (apiStatusCode === 200 || apiStatusCode === 100);
+        return isSuccessfulStatusCode(apiStatusCode);
     }
     async handleDevices(deviceLists) {
-        if (!this.config.options?.devices && !this.config.options?.deviceConfig) {
+        if (!this.config.options?.devices) {
             this.debugLog(`SwitchBot Device Config Not Set: ${JSON.stringify(this.config.options?.devices)}`);
             if (deviceLists.length === 0) {
                 this.debugLog('SwitchBot API Has No Devices With Cloud Services Enabled');
@@ -480,35 +660,48 @@ export class SwitchBotHAPPlatform {
                 }
             }
         }
-        else if (this.config.options?.devices || this.config.options?.deviceConfig) {
+        else {
             this.debugLog(`SwitchBot Device Config Set: ${JSON.stringify(this.config.options?.devices)}`);
-            // Step 1: Check and assign configDeviceType to deviceType if deviceType is not present
-            const devicesWithTypeConfigPromises = deviceLists.map(async (device) => {
+            // Check and assign configDeviceType to deviceType if deviceType is not present
+            const devicesWithTypeAssigned = deviceLists.map((device) => {
                 if (!device.deviceType) {
                     device.deviceType = device.configDeviceType !== undefined ? device.configDeviceType : 'Unknown';
                     this.warnLog(`API is displaying no deviceType: ${device.deviceType}, So using configDeviceType: ${device.configDeviceType}`);
                 }
-                // Retrieve deviceTypeConfig for each device and merge it
-                const deviceTypeConfig = this.config.options?.deviceConfig?.[device.deviceType] || {};
-                return Object.assign({}, device, deviceTypeConfig);
+                return device;
             });
-            // Wait for all promises to resolve
-            const devicesWithTypeConfig = (await Promise.all(devicesWithTypeConfigPromises)).filter(device => device !== null); // Filter out skipped devices
-            const devices = this.mergeByDeviceId(this.config.options.devices ?? [], devicesWithTypeConfig ?? []);
+            // Apply device-type templates from config entries with applyToAllDevicesOfType=true
+            const devicesWithTemplates = applyDeviceTypeTemplates(devicesWithTypeAssigned, this.config.options.devices, 'deviceType', msg => this.debugLog(msg));
+            const allowConfigOnly = Boolean(this.config.options?.allowConfigOnlyDevices);
+            const devices = mergeByDeviceId(this.config.options.devices ?? [], devicesWithTemplates ?? [], allowConfigOnly);
+            // Apply global webhook option to devices that don't have their own webhook setting
+            if (this.config.options?.webhook === true) {
+                for (const device of devices) {
+                    if (device.webhook === undefined) {
+                        device.webhook = true;
+                        this.debugLog(`Applying global webhook option to device: ${device.deviceName ?? device.deviceId}`);
+                    }
+                }
+            }
             this.debugLog(`SwitchBot Devices: ${JSON.stringify(devices)}`);
             for (const device of devices) {
-                const deviceIdConfig = this.config.options?.devices?.[device.deviceId] || {};
-                const deviceWithConfig = Object.assign({}, device, deviceIdConfig);
                 if (device.configDeviceName) {
                     device.deviceName = device.configDeviceName;
                 }
-                // Pass the merged device object to createDevice
-                await this.createDevice(deviceWithConfig);
+                // Log effective webhook setting for diagnostics
+                try {
+                    const effectiveWebhook = device.webhook !== undefined ? device.webhook : (this.config.options?.webhook === true ? true : undefined);
+                    this.debugLog(`Effective webhook for device ${device.deviceName ?? device.deviceId}: ${String(effectiveWebhook)}`);
+                }
+                catch (e) {
+                    this.debugLog(`Failed logging effective webhook for ${device.deviceName ?? device.deviceId}: ${e?.message ?? e}`);
+                }
+                await this.createDevice(device);
             }
         }
     }
     async handleIRDevices(irDeviceLists) {
-        if (!this.config.options?.irdevices && !this.config.options?.irdeviceConfig) {
+        if (!this.config.options?.irdevices) {
             this.debugLog(`IR Device Config Not Set: ${JSON.stringify(this.config.options?.irdevices)}`);
             for (const device of irDeviceLists) {
                 if (device.remoteType) {
@@ -516,43 +709,50 @@ export class SwitchBotHAPPlatform {
                 }
             }
         }
-        else if (this.config.options?.irdevices || this.config.options?.irdeviceConfig) {
+        else {
             this.debugLog(`IR Device Config Set: ${JSON.stringify(this.config.options?.irdevices)}`);
-            // Step 1: Check and assign configRemoteType to remoteType if remoteType is not present
-            const devicesWithTypeConfigPromises = irDeviceLists.map(async (device) => {
+            // Check and assign configRemoteType to remoteType if remoteType is not present
+            const devicesWithTypeAssigned = irDeviceLists.map((device) => {
                 if (!device.remoteType && device.configRemoteType) {
                     device.remoteType = device.configRemoteType;
                     this.warnLog(`API is displaying no remoteType: ${device.remoteType}, So using configRemoteType: ${device.configRemoteType}`);
                 }
                 else if (!device.remoteType && !device.configDeviceName) {
                     this.errorLog('No remoteType or configRemoteType for device. No device will be created.');
-                    return null; // Skip this device
+                    return null;
                 }
-                // Retrieve remoteTypeConfig for each device and merge it
-                const remoteTypeConfig = this.config.options?.irdeviceConfig?.[device.remoteType] || {};
-                return Object.assign({}, device, remoteTypeConfig);
-            });
-            // Wait for all promises to resolve
-            const devicesWithRemoteTypeConfig = (await Promise.all(devicesWithTypeConfigPromises)).filter(device => device !== null); // Filter out skipped devices
-            const devices = this.mergeByDeviceId(this.config.options.irdevices ?? [], devicesWithRemoteTypeConfig ?? []);
+                return device;
+            }).filter(device => device !== null); // Filter out skipped devices
+            // Apply remote-type templates from config entries with applyToAllDevicesOfType=true
+            const devicesWithTemplates = applyDeviceTypeTemplates(devicesWithTypeAssigned, this.config.options.irdevices, 'remoteType', msg => this.debugLog(msg));
+            const allowConfigOnly = Boolean(this.config.options?.allowConfigOnlyDevices);
+            const devices = mergeByDeviceId(this.config.options.irdevices ?? [], devicesWithTemplates ?? [], allowConfigOnly);
+            // Apply global webhook option to IR devices that don't have their own webhook setting
+            if (this.config.options?.webhook === true) {
+                for (const device of devices) {
+                    if (device.webhook === undefined) {
+                        device.webhook = true;
+                        this.debugLog(`Applying global webhook option to IR device: ${device.deviceName ?? device.deviceId}`);
+                    }
+                }
+            }
             this.debugLog(`IR Devices: ${JSON.stringify(devices)}`);
             for (const device of devices) {
-                const irdeviceIdConfig = this.config.options?.irdevices?.[device.deviceId] || {};
-                const irdeviceWithConfig = Object.assign({}, device, irdeviceIdConfig);
                 if (device.configDeviceName) {
                     device.deviceName = device.configDeviceName;
                 }
-                await this.createIRDevice(irdeviceWithConfig);
+                // Log effective webhook setting for diagnostics (IR devices)
+                try {
+                    const effectiveWebhook = device.webhook !== undefined ? device.webhook : (this.config.options?.webhook === true ? true : undefined);
+                    this.debugLog(`Effective webhook for IR device ${device.deviceName ?? device.deviceId}: ${String(effectiveWebhook)}`);
+                }
+                catch (e) {
+                    this.debugLog(`Failed logging effective webhook for IR ${device.deviceName ?? device.deviceId}: ${e?.message ?? e}`);
+                }
+                await this.createIRDevice(device);
             }
         }
     }
-    mergeByDeviceId(a1, a2) {
-        const normalizeDeviceId = (deviceId) => deviceId.toUpperCase().replace(/[^A-Z0-9]+/g, '');
-        return a1.map((itm) => {
-            const matchingItem = a2.find(item => normalizeDeviceId(item.deviceId) === normalizeDeviceId(itm.deviceId));
-            return { ...matchingItem, ...itm };
-        });
-    }
     async handleErrorResponse(apiStatusCode, retryCount, maxRetries, delayBetweenRetries) {
         await this.statusCode(apiStatusCode);
         if (apiStatusCode === 500) {
@@ -588,6 +788,7 @@ export class SwitchBotHAPPlatform {
             'Plug Mini (JP)': this.createPlug.bind(this),
             'Smart Lock': this.createLock.bind(this),
             'Smart Lock Pro': this.createLock.bind(this),
+            'Smart Lock Ultra': this.createLock.bind(this),
             'Color Bulb': this.createColorBulb.bind(this),
             'K10+': this.createRobotVacuumCleaner.bind(this),
             'K10+ Pro': this.createRobotVacuumCleaner.bind(this),
@@ -1550,7 +1751,7 @@ export class SwitchBotHAPPlatform {
                 existingAccessory.context.device = device;
                 existingAccessory.context.deviceId = device.deviceId;
                 existingAccessory.context.deviceType = device.deviceType;
-                existingAccessory.context.model = device.deviceType === 'Smart Lock Pro' ? SwitchBotModel.LockPro : SwitchBotModel.Lock;
+                existingAccessory.context.model = (device.deviceType === 'Smart Lock Pro' || device.deviceType === 'Smart Lock Ultra') ? SwitchBotModel.LockPro : SwitchBotModel.Lock;
                 existingAccessory.displayName = device.configDeviceName
                     ? await this.validateAndCleanDisplayName(device.configDeviceName, 'configDeviceName', device.configDeviceName)
                     : await this.validateAndCleanDisplayName(device.deviceName, 'deviceName', device.deviceName);
@@ -1577,7 +1778,7 @@ export class SwitchBotHAPPlatform {
             accessory.context.device = device;
             accessory.context.deviceId = device.deviceId;
             accessory.context.deviceType = device.deviceType;
-            accessory.context.model = device.deviceType === 'Smart Lock Pro' ? SwitchBotModel.LockPro : SwitchBotModel.Lock;
+            accessory.context.model = (device.deviceType === 'Smart Lock Pro' || device.deviceType === 'Smart Lock Ultra') ? SwitchBotModel.LockPro : SwitchBotModel.Lock;
             accessory.displayName = device.configDeviceName
                 ? await this.validateAndCleanDisplayName(device.configDeviceName, 'configDeviceName', device.configDeviceName)
                 : await this.validateAndCleanDisplayName(device.deviceName, 'deviceName', device.deviceName);
@@ -2608,42 +2809,29 @@ export class SwitchBotHAPPlatform {
      *
      * @param statusCode - The status code returned by the device.
      * @returns A promise that resolves when the logging is complete.
+     * @deprecated Use shared logStatusCode from utils.js instead
      */
     async statusCode(statusCode) {
-        const messages = {
-            151: `Command not supported by this device type, statusCode: ${statusCode}, Submit Feature Request Here: 
-            https://tinyurl.com/SwitchBotFeatureRequest`,
-            152: `Device not found, statusCode: ${statusCode}`,
-            160: `Command is not supported, statusCode: ${statusCode}, Submit Bugs Here: https://tinyurl.com/SwitchBotBug`,
-            161: `Device is offline, statusCode: ${statusCode}`,
-            171: `is offline, statusCode: ${statusCode}`,
-            190: `Requests reached the daily limit, statusCode: ${statusCode}`,
-            100: `Command successfully sent, statusCode: ${statusCode}`,
-            200: `Request successful, statusCode: ${statusCode}`,
-            400: `Bad Request, The client has issued an invalid request. This is commonly used to specify validation errors in a request payload, 
-            statusCode: ${statusCode}`,
-            401: `Unauthorized, Authorization for the API is required, but the request has not been authenticated, statusCode: ${statusCode}`,
-            403: `Forbidden, The request has been authenticated but does not have appropriate permissions, or a requested resource is not found, 
-            statusCode: ${statusCode}`,
-            404: `Not Found, Specifies the requested path does not exist, statusCode: ${statusCode}`,
-            406: `Not Acceptable, The client has requested a MIME type via the Accept header for a value not supported by the server, 
-            statusCode: ${statusCode}`,
-            415: `Unsupported Media Type, The client has defined a contentType header that is not supported by the server, statusCode: ${statusCode}`,
-            422: `Unprocessable Entity, The client has made a valid request, but the server cannot process it. This is often used for APIs for which 
-            certain limits have been exceeded, statusCode: ${statusCode}`,
-            429: `Too Many Requests, The client has exceeded the number of requests allowed for a given time window, statusCode: ${statusCode}`,
-            500: `Internal Server Error, An unexpected error on the SmartThings servers has occurred. These errors should be rare, 
-            statusCode: ${statusCode}`,
-        };
-        const message = messages[statusCode] ?? `Unknown statusCode, statusCode: ${statusCode}, Submit Bugs Here: https://tinyurl.com/SwitchBotBug`;
-        if ([100, 200].includes(statusCode)) {
-            this.debugLog(message);
-        }
-        else {
-            this.errorLog(message);
-        }
+        await logStatusCode(statusCode, {
+            debugLog: this.debugLog.bind(this),
+            errorLog: this.errorLog.bind(this),
+        });
     }
     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;
@@ -2674,6 +2862,9 @@ export class SwitchBotHAPPlatform {
         const delayBetweenRetries = deviceDelayBetweenRetries ?? 1000;
         while (retryCount < maxRetries) {
             try {
+                if (!this.apiTracker?.trySpend('command')) {
+                    return { response: {}, statusCode: 429 };
+                }
                 const { response, statusCode } = await this.switchBotAPI.controlDevice(device.deviceId, bodyChange.command, bodyChange.parameter, bodyChange.commandType, this.config.credentials?.token, this.config.credentials?.secret);
                 this.debugLog(`response: ${JSON.stringify(response)}`);
                 return { response, statusCode };
@@ -2761,6 +2952,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.
@@ -2796,66 +3034,5 @@ export class SwitchBotHAPPlatform {
             return value;
         }
     }
-    /**
-     * If device level logging is turned on, log to log.warn
-     * Otherwise send debug logs to log.debug
-     */
-    async infoLog(...log) {
-        if (await this.enablingPlatformLogging()) {
-            this.log.info(String(...log));
-        }
-    }
-    async successLog(...log) {
-        if (await this.enablingPlatformLogging()) {
-            this.log.success(String(...log));
-        }
-    }
-    async debugSuccessLog(...log) {
-        if (await this.enablingPlatformLogging()) {
-            if (await this.loggingIsDebug()) {
-                this.log.success('[DEBUG]', String(...log));
-            }
-        }
-    }
-    async warnLog(...log) {
-        if (await this.enablingPlatformLogging()) {
-            this.log.warn(String(...log));
-        }
-    }
-    async debugWarnLog(...log) {
-        if (await this.enablingPlatformLogging()) {
-            if (await this.loggingIsDebug()) {
-                this.log.warn('[DEBUG]', String(...log));
-            }
-        }
-    }
-    async errorLog(...log) {
-        if (await this.enablingPlatformLogging()) {
-            this.log.error(String(...log));
-        }
-    }
-    async debugErrorLog(...log) {
-        if (await this.enablingPlatformLogging()) {
-            if (await this.loggingIsDebug()) {
-                this.log.error('[DEBUG]', String(...log));
-            }
-        }
-    }
-    async debugLog(...log) {
-        if (await this.enablingPlatformLogging()) {
-            if (this.platformLogging === 'debug') {
-                this.log.info('[DEBUG]', String(...log));
-            }
-            else if (this.platformLogging === 'debugMode') {
-                this.log.debug(String(...log));
-            }
-        }
-    }
-    async loggingIsDebug() {
-        return this.platformLogging === 'debugMode' || this.platformLogging === 'debug';
-    }
-    async enablingPlatformLogging() {
-        return this.platformLogging === 'debugMode' || this.platformLogging === 'debug' || this.platformLogging === 'standard';
-    }
 }
 //# sourceMappingURL=platform-hap.js.map