@switchbot/homebridge-switchbot 5.0.0-beta.4 → 5.0.0-beta.41

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
@@ -51,6 +59,29 @@ export interface options {
   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
+  // Matter platform batch refresh options
+  matterBatchRefreshRate?: number
+  matterBatchConcurrency?: number
+  matterBatchEnabled?: boolean
+  matterBatchJitter?: number
 };
 
 export type devicesConfig = botConfig | relaySwitch1Config | relaySwitch1PMConfig | meterConfig | meterProConfig | indoorOutdoorSensorConfig | humidifierConfig | curtainConfig | blindTiltConfig | contactConfig | motionConfig | waterDetectorConfig | plugConfig | colorBulbConfig | stripLightConfig | ceilingLightConfig | lockConfig | hubConfig
@@ -85,6 +116,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 {
@@ -244,6 +281,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/platform-hap.logging.test.ts

@@ -0,0 +1,36 @@
+/* eslint-disable import/first */
+import { describe, expect, it, vi } from 'vitest'
+// Mock modules used by the HAP platform constructor to avoid requiring a real Homebridge API
+vi.mock('fakegato-history', () => ({ default: () => ({}) }))
+vi.mock('homebridge-lib/EveHomeKitTypes', () => ({ EveHomeKitTypes: class { constructor() {} } }))
+
+import { SwitchBotHAPPlatform } from '../../platform-hap.js'
+import { makeLogStub } from '../helpers/platform-fixtures.js'
+
+/**
+ * Verifies that HAP platform debug logger includes the accessory displayName
+ * when loading an accessory from the cache.
+ */
+describe('platform-hap logging', () => {
+  it('prints accessory name when loading HAP cached accessory', async () => {
+    const api: any = { on: vi.fn() }
+    const log: any = makeLogStub()
+
+    const platform = new SwitchBotHAPPlatform(log as any, {
+      name: 'SwitchBot',
+      credentials: {},
+      options: { logging: 'debug' },
+      devices: [],
+    } as any, api)
+
+    const accessory: any = { displayName: 'Test HAP Device' }
+    await (platform as any).configureAccessory(accessory)
+
+    // Allow async logger to flush
+    await new Promise(resolve => setTimeout(resolve, 0))
+
+    const calls = (log.info as any).mock.calls as Array<string[]>
+    const hasLine = calls.some(args => String(args[0]).includes('Loading accessory from cache: Test HAP Device'))
+    expect(hasLine).toBe(true)
+  })
+})

package/src/test/hap/platform-hap.test.ts

@@ -0,0 +1,70 @@
+/* eslint-disable import/first */
+import { describe, expect, it, vi } from 'vitest'
+// Mock modules used by the HAP platform constructor to avoid requiring a real Homebridge API
+vi.mock('fakegato-history', () => ({ default: () => ({}) }))
+vi.mock('homebridge-lib/EveHomeKitTypes', () => ({ EveHomeKitTypes: class { constructor() {} } }))
+
+import { SwitchBotHAPPlatform } from '../../platform-hap.js'
+import { makeLogStub } from '../helpers/platform-fixtures.js'
+
+/**
+ * High-level smoke tests for the HAP platform to ensure it initializes,
+ * subscribes to lifecycle events, and handles cached accessories.
+ */
+describe('platform-hap (smoke)', () => {
+  it('initializes and subscribes to didFinishLaunching', async () => {
+    const api: any = { on: vi.fn() }
+    const log: any = makeLogStub()
+
+    // Enable debug so debug* logs print via our shared logger
+    // Construct the platform (smoke)
+    new SwitchBotHAPPlatform(log as any, {
+      name: 'SwitchBot',
+      credentials: {},
+      options: { logging: 'debug' },
+      devices: [],
+    } as any, api)
+
+    // Should register didFinishLaunching handler
+    expect(api.on).toHaveBeenCalled()
+    const calledWithDL = (api.on as any).mock.calls.some((args: any[]) => args[0] === 'didFinishLaunching' && typeof args[1] === 'function')
+    expect(calledWithDL).toBe(true)
+
+    // Should log effective platform logging at startup
+    const debugCalls = (log.debug as any).mock.calls as Array<string[]>
+    const hasStartupLine = debugCalls.some(args => String(args[0]).includes('[SwitchBot HAP] effective platformLogging='))
+    expect(hasStartupLine).toBe(true)
+
+    // Missing credentials results in a debug error log
+    // Allow async platform logger to flush
+    await new Promise(resolve => setTimeout(resolve, 0))
+    const errorCalls = (log.error as any).mock.calls as Array<string[]>
+    const hasMissingCreds = errorCalls.some(args => String(args[0]).includes('Missing SwitchBot API credentials'))
+    expect(hasMissingCreds).toBe(true)
+  })
+
+  it('adds cached accessories via configureAccessory', async () => {
+    const api: any = { on: vi.fn() }
+    const log: any = makeLogStub()
+
+    const platform = new SwitchBotHAPPlatform(log as any, {
+      name: 'SwitchBot',
+      credentials: {},
+      options: { logging: 'debug' },
+      devices: [],
+    } as any, api)
+
+    const accessory: any = { displayName: 'Cached Device' }
+    await (platform as any).configureAccessory(accessory)
+
+    // Should be stored in platform.accessories
+    expect(Array.isArray((platform as any).accessories)).toBe(true)
+    expect((platform as any).accessories.length).toBe(1)
+
+    // And should log the cache load message including device name
+    await new Promise(resolve => setTimeout(resolve, 0))
+    const infoCalls = (log.info as any).mock.calls as Array<string[]>
+    const hasLine = infoCalls.some(args => String(args[0]).includes('Loading accessory from cache: Cached Device'))
+    expect(hasLine).toBe(true)
+  })
+})

package/src/test/helpers/platform-fixtures.ts

@@ -0,0 +1,33 @@
+import { vi } from 'vitest'
+
+// Shared test helpers for platform-matter tests
+export function makeApiStub(matterProps: Record<string, any> = {}) {
+  const handlers: Record<string, (...args: any[]) => any> = {}
+
+  const api: any = {
+    matter: {
+      uuid: { generate: (s: string) => `uuid-${s}` },
+      registerPlatformAccessories: matterProps.registerPlatformAccessories ?? vi.fn(),
+      unregisterPlatformAccessories: matterProps.unregisterPlatformAccessories ?? vi.fn(),
+      updateAccessoryState: matterProps.updateAccessoryState ?? vi.fn(),
+      clusterNames: matterProps.clusterNames ?? {},
+      deviceTypes: matterProps.deviceTypes ?? {},
+    },
+    isMatterAvailable: matterProps.isMatterAvailable ?? (() => true),
+    isMatterEnabled: matterProps.isMatterEnabled ?? (() => true),
+    on: (ev: string, fn: (...args: any[]) => any) => { handlers[ev] = fn },
+    _handlers: handlers,
+  }
+
+  return api
+}
+
+export function makeLogStub() {
+  return {
+    info: vi.fn(),
+    warn: vi.fn(),
+    debug: vi.fn(),
+    error: vi.fn(),
+    success: vi.fn(),
+  }
+}