@switchbot/homebridge-switchbot 5.0.0-beta.7 → 5.0.0-beta.70

package/src/settings.ts

@@ -32,10 +32,18 @@ interface credentials {
 
 export interface options {
   devices?: devicesConfig[]
-  deviceConfig?: { [deviceType: string]: devicesConfig }
   irdevices?: irDevicesConfig[]
-  irdeviceConfig?: { [remoteType: string]: irDevicesConfig }
   allowInvalidCharacters?: boolean
+  // When true, devices declared in config.options.devices that are not
+  // discovered via the SwitchBot OpenAPI will still be included (config-only
+  // devices). Default: false.
+  allowConfigOnlyDevices?: boolean
+  /**
+   * When true, previously-registered accessories for devices that are no
+   * longer discovered or configured will be kept on the bridge. Default: false.
+   * When false (default), stale accessories are removed automatically.
+   */
+  keepStaleAccessories?: boolean
   mqttURL?: string
   mqttOptions?: IClientOptions
   mqttPubOptions?: IClientOptions
@@ -45,12 +53,62 @@ export interface options {
   disableLogsforOpenAPI?: boolean
   hostname?: string
   webhookURL?: string
+  /**
+   * When true, enables webhook support for all devices by default.
+   * Individual devices can override this with their own webhook setting.
+   * Requires webhookURL to be configured.
+   */
+  webhook?: boolean
   maxRetries?: number
   delayBetweenRetries?: number
   refreshRate?: number
   updateRate?: number
   pushRate?: number
   logging?: string
+  /**
+   * Maximum number of SwitchBot OpenAPI requests allowed per day.
+   * Defaults to 10,000 if not specified.
+   */
+  dailyApiLimit?: number
+  /**
+   * Number of daily API requests reserved for user-initiated commands.
+   * When remaining budget falls below this reserve, background polling and discovery
+   * are paused until the daily counter resets. Defaults to 1,000.
+   */
+  dailyApiReserveForCommands?: number
+  /**
+   * When true, the plugin will completely stop background polling/discovery
+   * once the remaining daily budget reaches the reserve (webhook-only mode).
+   * When false, polling continues until the hard daily limit is reached.
+   * Default: false.
+   */
+  webhookOnlyOnReserve?: boolean
+  /**
+   * When true, reset the daily API request counter at LOCAL midnight (system timezone).
+   * When false (default), reset at UTC midnight. Default: false.
+   */
+  dailyApiResetAtLocalMidnight?: boolean
+  /**
+   * When true, resets the daily API request counter to zero. This is useful for testing purposes.
+   */
+  resetDailyApiCounter?: boolean
+  /**
+   * When set, configures the batch refresh rate (in milliseconds) for Matter devices.  Default: 5000 ms.
+   */
+  matterBatchRefreshRate?: number
+  /**
+   * When true, enables batch processing for Matter devices.  Default: false.
+   */
+  matterBatchConcurrency?: number
+  /**
+   * When true, enables batch processing for Matter devices. Default: false.
+   */
+  matterBatchEnabled?: boolean
+  /**
+   * When set, adds a random delay (jitter) to batch requests to avoid thundering herd problems.
+   */
+  matterBatchJitter?: number
+  newFeatureEnabled?: boolean
 };
 
 export type devicesConfig = botConfig | relaySwitch1Config | relaySwitch1PMConfig | meterConfig | meterProConfig | indoorOutdoorSensorConfig | humidifierConfig | curtainConfig | blindTiltConfig | contactConfig | motionConfig | waterDetectorConfig | plugConfig | colorBulbConfig | stripLightConfig | ceilingLightConfig | lockConfig | hubConfig
@@ -85,6 +143,12 @@ export interface BaseDeviceConfig extends device {
   mqttPubOptions?: IClientOptions
   history?: boolean
   webhook?: boolean
+  /**
+   * When true, applies this device's configuration to all other devices
+   * of the same deviceType/configDeviceType (e.g., all Humidifiers).
+   * Specific per-device settings will override these template settings.
+   */
+  applyToAllDevicesOfType?: boolean
 }
 
 export interface botConfig extends BaseDeviceConfig {
@@ -136,6 +200,11 @@ export interface humidifierConfig extends BaseDeviceConfig {
   hide_temperature?: boolean
   convertUnitTo?: string
   set_minStep?: number
+  /**
+   * When true (Humidifier2 only), exposes a Switch service in HomeKit
+   * to trigger the built-in Drying Filter mode via OpenAPI (setMode 8).
+   */
+  activate_dryingfilter?: boolean
 };
 
 export interface curtainConfig extends BaseDeviceConfig {
@@ -211,7 +280,7 @@ export interface ceilingLightConfig extends BaseDeviceConfig {
 };
 
 export interface lockConfig extends BaseDeviceConfig {
-  configDeviceType: 'Smart Lock' | 'Smart Lock Pro'
+  configDeviceType: 'Smart Lock' | 'Smart Lock Pro' | 'Smart Lock Ultra'
   hide_contactsensor?: boolean
   activate_latchbutton?: boolean
 };
@@ -244,6 +313,12 @@ export interface irBaseDeviceConfig extends irdevice {
   logging?: string
   customOn?: string
   customOff?: string
+  /**
+   * When true, applies this IR device's configuration to all other IR devices
+   * of the same remoteType/configRemoteType (e.g., all IR Fans).
+   * Specific per-device settings will override these template settings.
+   */
+  applyToAllDevicesOfType?: boolean
   customize?: boolean
   commandType?: string
   disablePushOn?: boolean

package/src/test/apiRequestTracker.test.ts

@@ -0,0 +1,417 @@
+import type { API, Logging } from 'homebridge'
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmdirSync, unlinkSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { describe, expect, it, vi } from 'vitest'
+
+import { ApiRequestTracker } from '../utils.js'
+
+// Helper to create isolated test environment for each test
+function createTestEnvironment(pluginName = 'SwitchBotTest') {
+  const testId = Math.random().toString(36).substring(7)
+  const testDir = join(tmpdir(), `switchbot-test-${testId}`)
+
+  // Create test directory
+  if (!existsSync(testDir)) {
+    mkdirSync(testDir, { recursive: true })
+  }
+
+  const testStatsFile = join(testDir, `${pluginName.toLowerCase()}-api-stats.json`)
+
+  // Mock API with a unique storage path per test
+  const mockApi = {
+    user: {
+      storagePath: () => testDir,
+    },
+  } as unknown as API
+
+  // Mock logger
+  const mockLog = {
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    debug: vi.fn(),
+  } as unknown as Logging
+
+  return { mockApi, mockLog, testStatsFile, testDir }
+}
+
+// Cleanup helper
+function cleanup(testDir: string) {
+  try {
+    if (existsSync(testDir)) {
+      const files = readdirSync(testDir)
+      for (const file of files) {
+        try {
+          unlinkSync(join(testDir, file))
+        } catch {
+          // ignore
+        }
+      }
+      rmdirSync(testDir)
+    }
+  } catch {
+    // ignore
+  }
+}
+
+describe('apiRequestTracker', () => {
+  describe('initialization', () => {
+    it('should create a new tracker with default limits', () => {
+      const { mockApi, mockLog, testDir } = createTestEnvironment()
+      try {
+        const tracker = new ApiRequestTracker(mockApi, mockLog, 'SwitchBotTest')
+        expect(tracker).toBeDefined()
+        expect(tracker.getCount()).toBe(0)
+        expect(tracker.getDate()).toBe(new Date().toISOString().split('T')[0])
+      } finally {
+        cleanup(testDir)
+      }
+    })
+
+    it('should respect custom daily limit', () => {
+      const { mockApi, mockLog, testDir } = createTestEnvironment()
+      try {
+        const tracker = new ApiRequestTracker(mockApi, mockLog, 'SwitchBotTest', {
+          dailyLimit: 5000,
+          reserveForCommands: 500,
+        })
+        expect(tracker).toBeDefined()
+      } finally {
+        cleanup(testDir)
+      }
+    })
+
+    it('should load existing stats from file', () => {
+      const { mockApi, mockLog, testDir } = createTestEnvironment()
+      try {
+        // Create a tracker, increment, and verify persistence
+        const tracker1 = new ApiRequestTracker(mockApi, mockLog, 'SwitchBotTest')
+        tracker1.track()
+        tracker1.track()
+        expect(tracker1.getCount()).toBe(2)
+
+        // Create a new tracker instance and verify it loads the count
+        const tracker2 = new ApiRequestTracker(mockApi, mockLog, 'SwitchBotTest')
+        expect(tracker2.getCount()).toBe(2)
+      } finally {
+        cleanup(testDir)
+      }
+    })
+  })
+
+  describe('track() - legacy method', () => {
+    it('should increment the counter', () => {
+      const { mockApi, mockLog, testDir } = createTestEnvironment()
+      try {
+        const tracker = new ApiRequestTracker(mockApi, mockLog, 'SwitchBotTest')
+        expect(tracker.getCount()).toBe(0)
+        tracker.track()
+        expect(tracker.getCount()).toBe(1)
+        tracker.track()
+        expect(tracker.getCount()).toBe(2)
+      } finally {
+        cleanup(testDir)
+      }
+    })
+
+    it('should persist count to file', () => {
+      const { mockApi, mockLog, testStatsFile, testDir } = createTestEnvironment()
+      try {
+        const tracker = new ApiRequestTracker(mockApi, mockLog, 'SwitchBotTest')
+        tracker.track()
+        tracker.track()
+        tracker.track()
+
+        // Read the stats file directly
+        const statsContent = readFileSync(testStatsFile, 'utf8')
+        const stats = JSON.parse(statsContent)
+        expect(stats.count).toBe(3)
+        expect(stats.date).toBe(new Date().toISOString().split('T')[0])
+      } finally {
+        cleanup(testDir)
+      }
+    })
+  })
+
+  describe('trySpend() - budget enforcement', () => {
+    it('should allow commands when under soft cap', () => {
+      const { mockApi, mockLog, testDir } = createTestEnvironment()
+      try {
+        const tracker = new ApiRequestTracker(mockApi, mockLog, 'SwitchBotTest', {
+          dailyLimit: 100,
+          reserveForCommands: 20,
+        })
+        // Use 50 requests (well under soft cap of 80)
+        for (let i = 0; i < 50; i++) {
+          expect(tracker.trySpend('command')).toBe(true)
+        }
+        expect(tracker.getCount()).toBe(50)
+      } finally {
+        cleanup(testDir)
+      }
+    })
+
+    it('should allow polling when under soft cap', () => {
+      const { mockApi, mockLog, testDir } = createTestEnvironment()
+      try {
+        const tracker = new ApiRequestTracker(mockApi, mockLog, 'SwitchBotTest', {
+          dailyLimit: 100,
+          reserveForCommands: 20,
+        })
+        // Use 50 requests
+        for (let i = 0; i < 50; i++) {
+          expect(tracker.trySpend('poll')).toBe(true)
+        }
+        expect(tracker.getCount()).toBe(50)
+      } finally {
+        cleanup(testDir)
+      }
+    })
+
+    it('should block polling at soft cap when pausePollingAtReserve is true', () => {
+      const { mockApi, mockLog, testDir } = createTestEnvironment()
+      try {
+        const tracker = new ApiRequestTracker(mockApi, mockLog, 'SwitchBotTest', {
+          dailyLimit: 100,
+          reserveForCommands: 20,
+          pausePollingAtReserve: true, // Enable soft cap blocking
+        })
+        // Use up to soft cap (80 requests)
+        for (let i = 0; i < 80; i++) {
+          tracker.track()
+        }
+        expect(tracker.getCount()).toBe(80)
+
+        // Polling should be blocked at soft cap
+        expect(tracker.trySpend('poll')).toBe(false)
+        expect(tracker.trySpend('discovery')).toBe(false)
+
+        // Commands should still work
+        expect(tracker.trySpend('command')).toBe(true)
+        expect(tracker.getCount()).toBe(81)
+      } finally {
+        cleanup(testDir)
+      }
+    })
+
+    it('should block all requests at hard cap', () => {
+      const { mockApi, mockLog, testDir } = createTestEnvironment()
+      try {
+        const tracker = new ApiRequestTracker(mockApi, mockLog, 'SwitchBotTest', {
+          dailyLimit: 100,
+          reserveForCommands: 20,
+        })
+        // Use up to hard cap
+        for (let i = 0; i < 100; i++) {
+          tracker.track()
+        }
+        expect(tracker.getCount()).toBe(100)
+
+        // All request types should be blocked
+        expect(tracker.trySpend('poll')).toBe(false)
+        expect(tracker.trySpend('discovery')).toBe(false)
+        expect(tracker.trySpend('command')).toBe(false)
+        expect(tracker.getCount()).toBe(100)
+      } finally {
+        cleanup(testDir)
+      }
+    })
+
+    it('should support batch spending', () => {
+      const { mockApi, mockLog, testDir } = createTestEnvironment()
+      try {
+        const tracker = new ApiRequestTracker(mockApi, mockLog, 'SwitchBotTest', {
+          dailyLimit: 100,
+          reserveForCommands: 20,
+        })
+        expect(tracker.trySpend('poll', 10)).toBe(true)
+        expect(tracker.getCount()).toBe(10)
+
+        expect(tracker.trySpend('command', 5)).toBe(true)
+        expect(tracker.getCount()).toBe(15)
+      } finally {
+        cleanup(testDir)
+      }
+    })
+  })
+
+  describe('webhookOnlyOnReserve mode', () => {
+    it('should continue polling beyond soft cap when pausePollingAtReserve is false', () => {
+      const { mockApi, mockLog, testDir } = createTestEnvironment()
+      try {
+        const tracker = new ApiRequestTracker(mockApi, mockLog, 'SwitchBotTest', {
+          dailyLimit: 100,
+          reserveForCommands: 20,
+          pausePollingAtReserve: false,
+        })
+        // Use 85 requests (past soft cap)
+        for (let i = 0; i < 85; i++) {
+          tracker.track()
+        }
+        expect(tracker.getCount()).toBe(85)
+
+        // Polling should still work (not paused at reserve)
+        expect(tracker.trySpend('poll')).toBe(true)
+        expect(tracker.getCount()).toBe(86)
+      } finally {
+        cleanup(testDir)
+      }
+    })
+
+    it('should stop polling at soft cap when pausePollingAtReserve is true', () => {
+      const { mockApi, mockLog, testDir } = createTestEnvironment()
+      try {
+        const tracker = new ApiRequestTracker(mockApi, mockLog, 'SwitchBotTest', {
+          dailyLimit: 100,
+          reserveForCommands: 20,
+          pausePollingAtReserve: true,
+        })
+        // Use up to soft cap
+        for (let i = 0; i < 80; i++) {
+          tracker.track()
+        }
+        expect(tracker.getCount()).toBe(80)
+
+        // Polling should be blocked
+        expect(tracker.trySpend('poll')).toBe(false)
+        expect(tracker.getCount()).toBe(80)
+
+        // Commands should still work
+        expect(tracker.trySpend('command')).toBe(true)
+        expect(tracker.getCount()).toBe(81)
+      } finally {
+        cleanup(testDir)
+      }
+    })
+  })
+
+  describe('warning logs', () => {
+    it('should log warning when reaching soft cap with pausePollingAtReserve enabled', () => {
+      const { mockApi, mockLog, testDir } = createTestEnvironment()
+      try {
+        const tracker = new ApiRequestTracker(mockApi, mockLog, 'SwitchBotTest', {
+          dailyLimit: 100,
+          reserveForCommands: 20,
+          pausePollingAtReserve: true, // Enable soft cap warning
+        })
+        // Use up to soft cap
+        for (let i = 0; i < 80; i++) {
+          tracker.track()
+        }
+
+        // Trigger soft cap warning by attempting poll (will be blocked)
+        tracker.trySpend('poll')
+        expect(mockLog.warn).toHaveBeenCalledWith(
+          expect.stringContaining('Near daily limit'),
+        )
+      } finally {
+        cleanup(testDir)
+      }
+    })
+
+    it('should log error when reaching hard cap', () => {
+      const { mockApi, mockLog, testDir } = createTestEnvironment()
+      try {
+        const tracker = new ApiRequestTracker(mockApi, mockLog, 'SwitchBotTest', {
+          dailyLimit: 100,
+          reserveForCommands: 20,
+        })
+        // Use up to hard cap
+        for (let i = 0; i < 100; i++) {
+          tracker.track()
+        }
+
+        // Trigger hard cap error
+        tracker.trySpend('command')
+        expect(mockLog.error).toHaveBeenCalledWith(
+          expect.stringContaining('Daily limit'),
+        )
+      } finally {
+        cleanup(testDir)
+      }
+    })
+  })
+
+  describe('hourly logging', () => {
+    it('should log immediately on startup', () => {
+      const { mockApi, mockLog, testDir } = createTestEnvironment()
+      try {
+        const tracker = new ApiRequestTracker(mockApi, mockLog, 'SwitchBotTest')
+        tracker.startHourlyLogging()
+        tracker.stopHourlyLogging()
+        expect(mockLog.info).toHaveBeenCalledWith(
+          expect.stringContaining('[API Stats] Today'),
+        )
+      } finally {
+        cleanup(testDir)
+      }
+    })
+
+    it('should stop logging when stopHourlyLogging is called', () => {
+      const { mockApi, mockLog, testDir } = createTestEnvironment()
+      try {
+        const tracker = new ApiRequestTracker(mockApi, mockLog, 'SwitchBotTest')
+        tracker.startHourlyLogging()
+        tracker.stopHourlyLogging()
+        // Should not throw
+        expect(true).toBe(true)
+      } finally {
+        cleanup(testDir)
+      }
+    })
+  })
+
+  describe('edge cases', () => {
+    it('should handle zero daily limit', () => {
+      const { mockApi, mockLog, testDir } = createTestEnvironment()
+      try {
+        const tracker = new ApiRequestTracker(mockApi, mockLog, 'SwitchBotTest', {
+          dailyLimit: 0,
+          reserveForCommands: 0,
+        })
+        // All requests should be blocked immediately
+        expect(tracker.trySpend('poll')).toBe(false)
+        expect(tracker.trySpend('command')).toBe(false)
+        expect(tracker.getCount()).toBe(0)
+      } finally {
+        cleanup(testDir)
+      }
+    })
+
+    it('should handle reserve larger than limit', () => {
+      const { mockApi, mockLog, testDir } = createTestEnvironment()
+      try {
+        const tracker = new ApiRequestTracker(mockApi, mockLog, 'SwitchBotTest', {
+          dailyLimit: 100,
+          reserveForCommands: 150,
+          pausePollingAtReserve: true, // Enable soft cap blocking
+        })
+        // Soft cap would be negative (100 - 150 = -50), clamped to 0
+        // With pausePollingAtReserve=true, polling should be blocked immediately
+        expect(tracker.trySpend('poll')).toBe(false)
+        // Commands up to hard cap should work
+        expect(tracker.trySpend('command')).toBe(true)
+      } finally {
+        cleanup(testDir)
+      }
+    })
+
+    it('should handle negative values in config', () => {
+      const { mockApi, mockLog, testDir } = createTestEnvironment()
+      try {
+        const tracker = new ApiRequestTracker(mockApi, mockLog, 'SwitchBotTest', {
+          dailyLimit: -100,
+          reserveForCommands: -50,
+        })
+        // Should be treated as 0
+        expect(tracker.trySpend('poll')).toBe(false)
+        expect(tracker.trySpend('command')).toBe(false)
+      } finally {
+        cleanup(testDir)
+      }
+    })
+  })
+})

package/src/test/hap/device-webhook-context.test.ts

@@ -0,0 +1,136 @@
+/* eslint-disable import/first */
+import { describe, expect, it, vi } from 'vitest'
+// Mock modules used by HAP device base occasionally via platform
+vi.mock('fakegato-history', () => ({ default: () => ({}) }))
+vi.mock('homebridge-lib/EveHomeKitTypes', () => ({ EveHomeKitTypes: class { constructor() {} } }))
+
+import { deviceBase } from '../../devices-hap/device.js'
+
+// Minimal HAP stub to satisfy deviceBase constructor operations
+function makeHapStub() {
+  class Service {
+    private _chars: Record<string, any> = {}
+    setCharacteristic(k: any, v: any) {
+      this._chars[k] = v
+      return this
+    }
+
+    getCharacteristic(k: any) {
+      return {
+        updateValue: (v: any) => {
+          this._chars[k] = v
+          return this
+        },
+      } as any
+    }
+  }
+  const Characteristic: any = {
+    Manufacturer: 'Manufacturer',
+    AppMatchingIdentifier: 'AppMatchingIdentifier',
+    Name: 'Name',
+    ConfiguredName: 'ConfiguredName',
+    Model: 'Model',
+    ProductData: 'ProductData',
+    SerialNumber: 'SerialNumber',
+    HardwareRevision: 'HardwareRevision',
+    SoftwareRevision: 'SoftwareRevision',
+    FirmwareRevision: 'FirmwareRevision',
+    On: 'On',
+  }
+  ;(Service as any).AccessoryInformation = class extends Service {}
+  ;(Service as any).Outlet = class extends Service {}
+  return { Service, Characteristic, Categories: { OUTLET: 7 } }
+}
+
+// Minimal PlatformAccessory stub
+function makeAccessoryStub(hap: any, name = 'Test Accessory') {
+  const services: any[] = []
+  return {
+    displayName: name,
+    category: 0,
+    context: {},
+    getService(cls: any) {
+      // find existing or create
+      const svc = services.find(s => s instanceof cls)
+      if (svc) {
+        return svc
+      }
+      const s = new cls()
+      services.push(s)
+      return s
+    },
+    addService(cls: any) {
+      const s = new cls()
+      services.push(s)
+      return s
+    },
+  }
+}
+
+// Minimal SwitchBotHAPPlatform-like stub with required surface
+function makePlatformStub(options: any, hap: any) {
+  const log = { info: vi.fn(), warn: vi.fn(), debug: vi.fn(), error: vi.fn(), success: vi.fn() }
+  return {
+    api: { hap },
+    log,
+    config: { options, credentials: {} },
+    debugMode: false,
+    // logging helpers used by deviceBase
+    infoLog: () => {},
+    successLog: () => {},
+    debugSuccessLog: () => {},
+    warnLog: () => {},
+    debugWarnLog: () => {},
+    errorLog: () => {},
+    debugErrorLog: () => {},
+    debugLog: () => {},
+    loggingIsDebug: async () => false,
+    enablingPlatformLogging: async () => true,
+    connectBLE: vi.fn(),
+    bleEventHandler: {},
+    webhookEventHandler: {},
+  }
+}
+
+// Create a tiny concrete subclass to instantiate deviceBase
+class TestHAPDevice extends deviceBase {
+  // Override any methods that may be invoked by tests if needed
+}
+
+describe('hap device base webhook context', () => {
+  it('sets accessory.context.webhook=true when global webhook is enabled and device.webhook is undefined', async () => {
+    const hap = makeHapStub()
+    const accessory: any = makeAccessoryStub(hap, 'Plug Device')
+    const platform: any = makePlatformStub({ webhook: true, logging: 'debug' }, hap)
+
+    const dev: any = {
+      deviceId: 'DEV-HAP-1',
+      deviceType: 'Plug',
+      connectionType: 'OpenAPI',
+      // webhook intentionally undefined
+    }
+
+    const d = new TestHAPDevice(platform, accessory, dev)
+    // Assert context
+    expect(accessory.context.webhook).toBe(true)
+    // ensure no unused var warning
+    expect(d).toBeDefined()
+  })
+
+  it('keeps accessory.context.webhook=false when device.webhook=false even if global is true', async () => {
+    const hap = makeHapStub()
+    const accessory: any = makeAccessoryStub(hap, 'Plug Device 2')
+    const platform: any = makePlatformStub({ webhook: true, logging: 'debug' }, hap)
+
+    const dev: any = {
+      deviceId: 'DEV-HAP-2',
+      deviceType: 'Plug',
+      connectionType: 'OpenAPI',
+      webhook: false,
+    }
+
+    const d = new TestHAPDevice(platform, accessory, dev)
+    expect(accessory.context.webhook).toBe(false)
+    expect(d).toBeDefined()
+  })
+})