@switchbot/homebridge-switchbot 5.0.0-beta.6 → 5.0.0-beta.61

package/src/platform-hap.ts

@@ -55,7 +55,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
@@ -68,6 +68,18 @@ export class SwitchBotHAPPlatform implements DynamicPlatformPlugin {
   public readonly api: API
   public readonly log: Logging
 
+  // Logging helper functions (attached from utils.createPlatformLogger in constructor)
+  infoLog!: (...log: any[]) => Promise<void>
+  successLog!: (...log: any[]) => Promise<void>
+  debugSuccessLog!: (...log: any[]) => Promise<void>
+  warnLog!: (...log: any[]) => Promise<void>
+  debugWarnLog!: (...log: any[]) => Promise<void>
+  errorLog!: (...log: any[]) => Promise<void>
+  debugErrorLog!: (...log: any[]) => Promise<void>
+  debugLog!: (...log: any[]) => Promise<void>
+  loggingIsDebug!: () => Promise<boolean>
+  enablingPlatformLogging!: () => Promise<boolean>
+
   // Configuration properties
   platformConfig!: SwitchBotPlatformConfig
   platformLogging!: options['logging']
@@ -88,6 +100,9 @@ export class SwitchBotHAPPlatform implements DynamicPlatformPlugin {
   switchBotAPI!: SwitchBotOpenAPI
   switchBotBLE!: SwitchBotBLE
 
+  // API request tracking
+  private apiTracker?: ApiRequestTracker
+
   // External APIs
   public readonly eve: any
   public readonly fakegatoAPI: any
@@ -104,9 +119,22 @@ export class SwitchBotHAPPlatform implements DynamicPlatformPlugin {
     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
     }
 
@@ -119,21 +147,23 @@ export class SwitchBotHAPPlatform implements DynamicPlatformPlugin {
       devices: config.devices as { deviceId: string }[],
     }
 
-    // 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 as any).options) {
-        const cleaned = cleanDeviceConfig((this.config as any).options.deviceConfig)
-        if (cleaned) {
-          ;(this.config as any).options.deviceConfig = cleaned
-        } else {
-          // remove the empty deviceConfig so downstream checks treat it as absent
-          delete (this.config as any).options.deviceConfig
-        }
-      }
-    } catch (e) {
-      this.debugErrorLog(`Failed to clean deviceConfig: ${e}`)
+      this.log.debug?.(`[SwitchBot HAP] effective platformLogging=${String(this.platformLogging)}`)
+    } catch (e: any) {
+      // 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()
@@ -203,19 +233,39 @@ export class SwitchBotHAPPlatform implements DynamicPlatformPlugin {
     // to start discovery of new accessories.
     this.api.on('didFinishLaunching', async () => {
       this.debugLog('Executed didFinishLaunching callback')
+
+      // Initialize API request tracking
+      if (this.switchBotAPI) {
+        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()
+          this.debugLog('API request tracking initialized for OpenAPI usage')
+        } catch (e: any) {
+          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: any) {
         this.errorLog(`Failed to Discover, Error Message: ${e.message ?? e}, Submit Bugs Here: ` + 'https://tinyurl.com/SwitchBotBug')
@@ -444,6 +494,7 @@ export class SwitchBotHAPPlatform implements DynamicPlatformPlugin {
     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}`)
@@ -451,13 +502,29 @@ export class SwitchBotHAPPlatform implements DynamicPlatformPlugin {
 
     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++
         }
@@ -467,9 +534,117 @@ export class SwitchBotHAPPlatform implements DynamicPlatformPlugin {
         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
+   */
+  private 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: { [key: string]: new (platform: any, accessory: PlatformAccessory, device: any) => any } = {
+          '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: any) {
+        this.errorLog(`Failed to restore cached accessory ${accessory.displayName}, Error: ${e.message ?? e}`)
+      }
+    }
+
+    this.infoLog(`Restored ${this.accessories.length} cached accessories with webhook support`)
   }
 
   private 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: any) => v)
@@ -486,17 +661,41 @@ export class SwitchBotHAPPlatform implements DynamicPlatformPlugin {
           this.errorLog(`failed to format device ID as MAC, Error: ${error}`)
         }
       }
-    } 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: any) => 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
+   */
   private isSuccessfulResponse(apiStatusCode: number): boolean {
-    return (apiStatusCode === 200 || apiStatusCode === 100)
+    return isSuccessfulStatusCode(apiStatusCode)
   }
 
   private async handleDevices(deviceLists: any[]) {
-    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')
@@ -510,92 +709,118 @@ export class SwitchBotHAPPlatform implements DynamicPlatformPlugin {
           }
         }
       }
-    } 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: any) {
+          this.debugLog(`Failed logging effective webhook for ${device.deviceName ?? device.deviceId}: ${e?.message ?? e}`)
+        }
+        await this.createDevice(device)
       }
     }
   }
 
   private async handleIRDevices(irDeviceLists: any[]) {
-    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) {
           await this.createIRDevice(device)
         }
       }
-    } 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: any) {
+          this.debugLog(`Failed logging effective webhook for IR ${device.deviceName ?? device.deviceId}: ${e?.message ?? e}`)
+        }
+        await this.createIRDevice(device)
       }
     }
   }
 
-  private mergeByDeviceId(a1: { deviceId: string }[], a2: any[]) {
-    const normalizeDeviceId = (deviceId: string) => 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 }
-    })
-  }
-
   private async handleErrorResponse(apiStatusCode: number, retryCount: number, maxRetries: number, delayBetweenRetries: number) {
     await this.statusCode(apiStatusCode)
     if (apiStatusCode === 500) {
@@ -632,6 +857,7 @@ export class SwitchBotHAPPlatform implements DynamicPlatformPlugin {
       '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),
@@ -1627,7 +1853,7 @@ export class SwitchBotHAPPlatform implements DynamicPlatformPlugin {
         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)
@@ -1653,7 +1879,7 @@ export class SwitchBotHAPPlatform implements DynamicPlatformPlugin {
       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)
@@ -2720,44 +2946,31 @@ export class SwitchBotHAPPlatform implements DynamicPlatformPlugin {
    *
    * @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: number): Promise<void> {
-    const messages: { [key: number]: string } = {
-      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: (device & devicesConfig) | (irdevice & irDevicesConfig), deviceMaxRetries: number, deviceDelayBetweenRetries: number): Promise<{ response: any, statusCode: deviceStatusRequest['statusCode'] }> {
+    // 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
@@ -2788,6 +3001,9 @@ export class SwitchBotHAPPlatform implements DynamicPlatformPlugin {
     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,
@@ -2886,6 +3102,56 @@ export class SwitchBotHAPPlatform implements DynamicPlatformPlugin {
     this.version = version
   }
 
+  /**
+   * Validate that the user's configuration won't exceed API limits
+   * Warn if device count × polling frequency will hit daily limits
+   */
+  private validateApiUsageConfig(deviceCount: number, irDeviceCount: number): void {
+    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: any) {
+      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.
@@ -2924,74 +3190,4 @@ export class SwitchBotHAPPlatform implements DynamicPlatformPlugin {
       return value
     }
   }
-
-  /**
-   * If device level logging is turned on, log to log.warn
-   * Otherwise send debug logs to log.debug
-   */
-  async infoLog(...log: any[]): Promise<void> {
-    if (await this.enablingPlatformLogging()) {
-      this.log.info(String(...log))
-    }
-  }
-
-  async successLog(...log: any[]): Promise<void> {
-    if (await this.enablingPlatformLogging()) {
-      this.log.success(String(...log))
-    }
-  }
-
-  async debugSuccessLog(...log: any[]): Promise<void> {
-    if (await this.enablingPlatformLogging()) {
-      if (await this.loggingIsDebug()) {
-        this.log.success('[DEBUG]', String(...log))
-      }
-    }
-  }
-
-  async warnLog(...log: any[]): Promise<void> {
-    if (await this.enablingPlatformLogging()) {
-      this.log.warn(String(...log))
-    }
-  }
-
-  async debugWarnLog(...log: any[]): Promise<void> {
-    if (await this.enablingPlatformLogging()) {
-      if (await this.loggingIsDebug()) {
-        this.log.warn('[DEBUG]', String(...log))
-      }
-    }
-  }
-
-  async errorLog(...log: any[]): Promise<void> {
-    if (await this.enablingPlatformLogging()) {
-      this.log.error(String(...log))
-    }
-  }
-
-  async debugErrorLog(...log: any[]): Promise<void> {
-    if (await this.enablingPlatformLogging()) {
-      if (await this.loggingIsDebug()) {
-        this.log.error('[DEBUG]', String(...log))
-      }
-    }
-  }
-
-  async debugLog(...log: any[]): Promise<void> {
-    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(): Promise<boolean> {
-    return this.platformLogging === 'debugMode' || this.platformLogging === 'debug'
-  }
-
-  async enablingPlatformLogging(): Promise<boolean> {
-    return this.platformLogging === 'debugMode' || this.platformLogging === 'debug' || this.platformLogging === 'standard'
-  }
 }