@switchbot/homebridge-switchbot 5.0.0-beta.11 → 5.0.0-beta.111

package/test/matter-integration.spec.ts

@@ -0,0 +1,111 @@
+import { describe, it, expect } from 'vitest'
+import { createPlatformProxy } from '../src/utils'
+import { makeFakeApiWithMatter, makeFakeApiWithoutMatter, makeFakeMatterApi } from './helpers/matter-harness'
+import SwitchBotHAPPlatform, { SwitchBotMatterPlatform } from '../src/platform'
+
+// Expanded Matter integration harness tests
+
+describe('Matter integration harness', () => {
+  it('normalizes Color Bulb and Motion Sensor to Matter-supported categories', async () => {
+    const matterApi = makeFakeMatterApi()
+    const api = makeFakeApiWithMatter(matterApi)
+
+    const platform = new SwitchBotMatterPlatform(console as any, {
+      devices: [
+        { id: 'cb-1', type: 'Color Bulb', name: 'Color Bulb 1' },
+        { id: 'ms-1', type: 'Motion Sensor', name: 'Motion Sensor 1' },
+      ],
+      enableMatter: true,
+      preferMatter: true,
+    } as any, api as any)
+
+    await (platform as any).registerMatterAccessories()
+
+    const regs = matterApi.getRegistered()
+    expect(regs.length).toBeGreaterThanOrEqual(2)
+    const ids = regs.map((r: any) => r?.context?.deviceId)
+    expect(ids).toContain('cb-1')
+    expect(ids).toContain('ms-1')
+  })
+
+  it('uses conformant window covering type for curtain Matter registration', async () => {
+    const matterApi = makeFakeMatterApi()
+    const api = makeFakeApiWithMatter(matterApi)
+
+    const platform = new SwitchBotMatterPlatform(console as any, {
+      devices: [{ id: 'curtain-1', type: 'curtain', name: 'Curtain 1' }],
+      enableMatter: true,
+      preferMatter: true,
+    } as any, api as any)
+
+    await (platform as any).registerMatterAccessories()
+
+    const regs = matterApi.getRegistered()
+    expect(regs.length).toBeGreaterThanOrEqual(1)
+    const wcType = regs[0]?.clusters?.windowCovering?.type
+    expect(wcType).toBe(0)
+    expect(wcType).not.toBe(4)
+  })
+
+  it('registers Matter accessories when Matter API available', async () => {
+    // Instantiate the real Matter platform directly to test its registration path
+    const matterApi = makeFakeMatterApi()
+    const api = makeFakeApiWithMatter(matterApi)
+
+    const platform = new SwitchBotMatterPlatform(console as any, { devices: [{ id: 'm-1', type: 'light', name: 'L1' }], enableMatter: true, preferMatter: true } as any, api as any)
+
+    // Call register path directly
+    if (typeof (platform as any).registerMatterAccessories === 'function') {
+      await (platform as any).registerMatterAccessories()
+    } else if (typeof (platform as any).loadDevices === 'function') {
+      await (platform as any).loadDevices()
+    }
+
+    const regs = matterApi.getRegistered()
+    expect(regs.length).toBeGreaterThanOrEqual(1)
+    // The platform registers serialized accessories; ensure deviceId is present in context
+    expect(regs[0]).toHaveProperty('context')
+    expect(regs[0].context).toHaveProperty('deviceId', 'm-1')
+  })
+
+  it('falls back to HAP when Matter API unavailable', async () => {
+    // Directly instantiate the HAP platform to exercise HAP fallback
+    const api = makeFakeApiWithoutMatter()
+    const platform = new SwitchBotHAPPlatform(console as any, { devices: [{ id: 'h-1', type: 'light', name: 'H1' }], enableMatter: true, preferMatter: true } as any, api as any)
+
+    // call loadDevices for HAP flow
+    if (typeof (platform as any).loadDevices === 'function') await (platform as any).loadDevices()
+
+    // Platform should have an accessories map populated
+    const accMap = (platform as any).accessories
+    expect(accMap).toBeDefined()
+    const keys = Array.from(accMap.keys())
+    expect(keys.length).toBeGreaterThanOrEqual(1)
+  })
+
+  it('reuses restored Matter accessories instead of registering duplicates', async () => {
+    const matterApi = makeFakeMatterApi()
+    const api = makeFakeApiWithMatter(matterApi)
+
+    const platform = new SwitchBotMatterPlatform(console as any, { devices: [{ id: 'r-1', type: 'light', name: 'R1' }], enableMatter: true, preferMatter: true } as any, api as any)
+
+    // Simulate a restored accessory present before registration
+    const restored = { uuid: matterApi.uuid.generate('r-1'), displayName: 'Restored R1', context: { deviceId: 'r-1' } }
+    if (typeof (platform as any).configureMatterAccessory === 'function') {
+      await (platform as any).configureMatterAccessory(restored)
+    } else if (typeof (platform as any).configureAccessory === 'function') {
+      await (platform as any).configureAccessory(restored)
+    }
+
+    // Now call register path
+    if (typeof (platform as any).registerMatterAccessories === 'function') await (platform as any).registerMatterAccessories()
+    else if (typeof (platform as any).loadDevices === 'function') {
+      await (platform as any).loadDevices()
+      if (typeof (platform as any).registerMatterAccessories === 'function') await (platform as any).registerMatterAccessories()
+    }
+
+    const accs = (platform as any).accessories
+    const found = Array.from(accs.values()).some((a: any) => a && (a.uuid === restored.uuid || a.UUID === restored.uuid))
+    expect(found).toBeTruthy()
+  })
+})

package/test/platform.integration.spec.ts

@@ -0,0 +1,55 @@
+import { describe, it, expect } from 'vitest'
+import { SwitchBotHAPPlatform } from '../src/platform'
+
+// Minimal mock logger
+const log = {
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+  debug: () => {},
+}
+
+describe('platform integration (HAP)', () => {
+  it('registers HAP accessories using Homebridge API', async () => {
+    const registered: any[] = []
+
+    // Minimal hap stub
+    const hap = {
+      uuid: { generate: (s: string) => `uuid-${s}` },
+      Service: { Switch: 'Switch', Lightbulb: 'Lightbulb' },
+      Characteristic: { On: 'On', Brightness: 'Brightness' },
+    }
+
+    // Simple platformAccessory constructor
+    function PlatformAccessory(name: string, uuid: string) {
+      this.displayName = name
+      this.UUID = uuid
+      this.services = []
+      this.getService = (type: any) => this.services.find((s: any) => s.type === type)
+      this.addService = (type: any) => {
+        const s: any = { type, characteristics: {} }
+        this.services.push(s)
+        return s
+      }
+    }
+
+    const api: any = {
+      hap,
+      platformAccessory: PlatformAccessory as any,
+      registerPlatformAccessories: (_p: string, _n: string, accs: any[]) => registered.push(...accs),
+      on: (_ev: string, cb: Function) => { /* do not auto-run */ },
+    }
+
+    const config: any = { devices: [{ id: 'dev1', type: 'light', name: 'L1' }] }
+
+    const platform = new SwitchBotHAPPlatform(log as any, config, api)
+
+    // call loadDevices directly to control flow
+    await (platform as any).loadDevices()
+
+    // Expect accessory created and registered
+    expect(registered.length).toBeGreaterThanOrEqual(1)
+    const keys = Array.from((platform as any).accessories.keys())
+    expect(keys.some((k: string) => k.includes('dev1'))).toBeTruthy()
+  })
+})

package/test/switchbot-client-debounce.spec.ts

@@ -0,0 +1,131 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { SwitchBotClient } from '../src/switchbotClient'
+
+describe('SwitchBotClient debounce/coalesce', () => {
+  let origFetch: any
+
+  beforeEach(() => {
+    origFetch = (global as any).fetch
+    vi.useFakeTimers()
+  })
+
+  afterEach(() => {
+    (global as any).fetch = origFetch
+    vi.restoreAllMocks()
+    vi.useRealTimers()
+  })
+
+  it('coalesces rapid writes for the same device (last write wins)', async () => {
+    const respBody = { status: 'ok' }
+    const fetchMock = vi.fn(async (url: string, opts: any) => ({ json: async () => respBody }))
+    ;(global as any).fetch = fetchMock
+
+    // Set a short debounce in config to keep the test fast
+    const c = new SwitchBotClient({ openApiToken: 't', writeDebounceMs: 10 } as any)
+    await c.init()
+
+    const body1 = { command: 'one' }
+    const body2 = { command: 'two' }
+
+    const p1 = c.setDeviceState('d-debounce', body1)
+    const p2 = c.setDeviceState('d-debounce', body2)
+
+    // Fast-forward timers past debounce window
+    vi.advanceTimersByTime(20)
+    // Allow pending microtasks to resolve
+    await Promise.resolve()
+    await Promise.resolve()
+
+    const [r1, r2] = await Promise.all([p1, p2])
+    expect(r1).toEqual(respBody)
+    expect(r2).toEqual(respBody)
+
+    // Only one network call should have been made
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+    const calledBody = JSON.parse(fetchMock.mock.calls[0][1].body)
+    expect(calledBody).toEqual(body2)
+  })
+
+  it('does not coalesce writes for different devices', async () => {
+    const respBody = { status: 'ok' }
+    const fetchMock = vi.fn(async (url: string, opts: any) => ({ json: async () => respBody }))
+    ;(global as any).fetch = fetchMock
+
+    const c = new SwitchBotClient({ openApiToken: 't', writeDebounceMs: 10 } as any)
+    await c.init()
+
+    const p1 = c.setDeviceState('d-A', { command: 'a' })
+    const p2 = c.setDeviceState('d-B', { command: 'b' })
+
+    vi.advanceTimersByTime(20)
+    await Promise.resolve()
+    await Promise.resolve()
+
+    await Promise.all([p1, p2])
+
+    expect(fetchMock).toHaveBeenCalledTimes(2)
+    const b1 = JSON.parse(fetchMock.mock.calls[0][1].body)
+    const b2 = JSON.parse(fetchMock.mock.calls[1][1].body)
+    expect(b1).toEqual({ command: 'a' })
+    expect(b2).toEqual({ command: 'b' })
+  })
+
+  it('coalesces multiple rapid writes (three) and resolves all promises with last response', async () => {
+    const respBody = { status: 'ok', val: 'last' }
+    const fetchMock = vi.fn(async (url: string, opts: any) => ({ json: async () => respBody }))
+    ;(global as any).fetch = fetchMock
+
+    const c = new SwitchBotClient({ openApiToken: 't', writeDebounceMs: 10 } as any)
+    await c.init()
+
+    const p1 = c.setDeviceState('d-debounce', { command: 'one' })
+    const p2 = c.setDeviceState('d-debounce', { command: 'two' })
+    const p3 = c.setDeviceState('d-debounce', { command: 'three' })
+
+    vi.advanceTimersByTime(20)
+    await Promise.resolve()
+    await Promise.resolve()
+
+    const [r1, r2, r3] = await Promise.all([p1, p2, p3])
+    expect(r1).toEqual(respBody)
+    expect(r2).toEqual(respBody)
+    expect(r3).toEqual(respBody)
+
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+    const calledBody = JSON.parse(fetchMock.mock.calls[0][1].body)
+    expect(calledBody).toEqual({ command: 'three' })
+  })
+
+  it('separate writes outside debounce window produce multiple network calls', async () => {
+    const respBody1 = { status: 'ok', seq: 1 }
+    const respBody2 = { status: 'ok', seq: 2 }
+    const fetchMock = vi.fn()
+      .mockImplementationOnce(async () => ({ json: async () => respBody1 }))
+      .mockImplementationOnce(async () => ({ json: async () => respBody2 }))
+    ;(global as any).fetch = fetchMock
+
+    const c = new SwitchBotClient({ openApiToken: 't', writeDebounceMs: 10 } as any)
+    await c.init()
+
+    const p1 = c.setDeviceState('d-debounce', { command: 'one' })
+    vi.advanceTimersByTime(20)
+    await Promise.resolve()
+    await Promise.resolve()
+
+    const p2 = c.setDeviceState('d-debounce', { command: 'two' })
+    vi.advanceTimersByTime(20)
+    await Promise.resolve()
+    await Promise.resolve()
+
+    const r1 = await p1
+    const r2 = await p2
+
+    expect(fetchMock).toHaveBeenCalledTimes(2)
+    const b1 = JSON.parse(fetchMock.mock.calls[0][1].body)
+    const b2 = JSON.parse(fetchMock.mock.calls[1][1].body)
+    expect(b1).toEqual({ command: 'one' })
+    expect(b2).toEqual({ command: 'two' })
+    expect(r1).toEqual(respBody1)
+    expect(r2).toEqual(respBody2)
+  })
+})

package/test/switchbot-client-openapi.spec.ts

@@ -0,0 +1,56 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { SwitchBotClient } from '../src/switchbotClient'
+
+describe('SwitchBotClient OpenAPI fallback', () => {
+  let origFetch: any
+
+  beforeEach(() => {
+    origFetch = (global as any).fetch
+  })
+
+  afterEach(() => {
+    (global as any).fetch = origFetch
+    vi.restoreAllMocks()
+  })
+
+  it('throws when no client and no token', async () => {
+    const c = new SwitchBotClient({} as any)
+    await c.init()
+    await expect(c.getDevice('nope')).rejects.toThrow('No SwitchBot client available')
+  })
+
+  it('uses OpenAPI when token provided for getDevice', async () => {
+    const fakeResp = { body: { device: { id: 'd1', state: 'ok' } } }
+    const fetchMock = vi.fn(async (url: string, opts: any) => ({ json: async () => fakeResp }))
+    ;(global as any).fetch = fetchMock
+
+    const c = new SwitchBotClient({ openApiToken: 'token-123' } as any)
+    await c.init()
+    const res = await c.getDevice('d1')
+    expect(res).toEqual(fakeResp)
+    expect(fetchMock).toHaveBeenCalledWith('https://api.switch-bot.com/v1.0/devices/d1', { headers: { Authorization: 'token-123' } })
+  })
+
+  it('posts commands to OpenAPI for setDeviceState', async () => {
+    const respBody = { status: 'ok' }
+    const fetchMock = vi.fn(async (url: string, opts: any) => ({ json: async () => respBody }))
+    ;(global as any).fetch = fetchMock
+
+    const c = new SwitchBotClient({ openApiToken: 't' } as any)
+    await c.init()
+    const body = { command: 'turnOn', parameter: 'default', commandType: 'command' }
+    const out = await c.setDeviceState('d2', body)
+    expect(out).toEqual(respBody)
+    expect(fetchMock).toHaveBeenCalledWith('https://api.switch-bot.com/v1.0/devices/d2/commands', expect.objectContaining({ method: 'POST' }))
+    const calledBody = JSON.parse((fetchMock.mock.calls[0][1].body))
+    expect(calledBody).toEqual(body)
+  })
+
+  it('propagates fetch errors', async () => {
+    const fetchMock = vi.fn(async () => { throw new Error('network') })
+    ;(global as any).fetch = fetchMock
+    const c = new SwitchBotClient({ openApiToken: 't' } as any)
+    await c.init()
+    await expect(c.getDevice('x')).rejects.toThrow('network')
+  })
+})

package/test/switchbotClient.spec.ts

@@ -0,0 +1,10 @@
+import { describe, it, expect } from 'vitest'
+import { SwitchBotClient } from '../src/switchbotClient'
+
+describe('SwitchBotClient', () => {
+  it('init does not throw and getDevice throws when no token/client', async () => {
+    const c = new SwitchBotClient({})
+    await c.init()
+    await expect(c.getDevice('nope')).rejects.toThrow()
+  })
+})

package/test/utils.spec.ts

@@ -0,0 +1,36 @@
+import { describe, it, expect } from 'vitest'
+import { createPlatformProxy } from '../src/utils'
+
+describe('createPlatformProxy', () => {
+  it('returns Matter platform when preferMatter, enabled, and Matter API is available', () => {
+    class HAP {}
+    class Matter {}
+    const ProxyCtor: any = createPlatformProxy(HAP, Matter)
+    const api = {
+      isMatterAvailable: () => true,
+      isMatterEnabled: () => true,
+    }
+    const impl = new (ProxyCtor as any)(console, { preferMatter: true, enableMatter: true }, api)
+    expect(impl).toBeInstanceOf(Matter)
+  })
+
+  it('returns HAP platform when preferMatter is false', () => {
+    class HAP {}
+    class Matter {}
+    const ProxyCtor: any = createPlatformProxy(HAP, Matter)
+    const impl = new (ProxyCtor as any)(console, { preferMatter: false, enableMatter: true }, undefined)
+    expect(impl).toBeInstanceOf(HAP)
+  })
+
+  it('returns HAP platform when Matter API is unavailable', () => {
+    class HAP {}
+    class Matter {}
+    const ProxyCtor: any = createPlatformProxy(HAP, Matter)
+    const api = {
+      isMatterAvailable: () => false,
+      isMatterEnabled: () => false,
+    }
+    const impl = new (ProxyCtor as any)(console, { preferMatter: true, enableMatter: true }, api)
+    expect(impl).toBeInstanceOf(HAP)
+  })
+})

package/todo/COMPLETED.md

@@ -0,0 +1,229 @@
+# Completed TODOs
+
+This file tracks all completed features and improvements for the SwitchBot Homebridge Plugin.
+
+---
+
+## Code Refactoring & Architecture
+
+### Server-Side Refactoring ✅ COMPLETED
+
+- [x] **Split `server.ts` into modular structure**
+  - [x] Created `src/homebridge-ui/endpoints/discovery.ts` - Discovery endpoint
+  - [x] Created `src/homebridge-ui/endpoints/config.ts` - Config management endpoint
+  - [x] Created `src/homebridge-ui/endpoints/devices.ts` - Device CRUD operations
+  - [x] Created `src/homebridge-ui/endpoints/credentials.ts` - Credentials endpoint
+  - [x] Created `src/homebridge-ui/utils/config-parser.ts` - Config parsing helpers
+  - [x] Created `src/homebridge-ui/utils/logger.ts` - Logging utility
+  - [x] Updated `src/homebridge-ui/server.ts` - Main entry point (imports and registers endpoints)
+
+  **Status:** Server endpoints are fully modularized and organized by concern.
+
+---
+
+## Bug Fixes
+
+### Matter Window Covering Conformance ✅ COMPLETED
+
+- [x] **Fix Matter window covering Drapery enum validation error**
+  - [x] **Issue:** Matter accessory registration failed for Curtain devices
+  - [x] **Error:** `Conformance "LF & !TL": Matter does not allow enum value Drapery (ID 4) here`
+  - [x] **Related Runtime Failure:** `[Matter/Server] Failed to register Matter accessory ... [endpoint-behaviors] Behaviors have errors` with rollback from Matter transaction initialization
+  - [x] **Root Cause:** `windowCovering.type` used `Drapery` for lift-only curtain mappings
+  - [x] **Fix:** Updated curtain Matter default to a compliant lift-only covering enum and added regression coverage
+
+  **Status:** Curtain-type Matter accessories now register without the Drapery conformance failure.
+
+### Invalid Device Type Validation ✅ COMPLETED
+
+- [x] **Fix invalid device type in config schema validation**
+  - [x] **Issue:** Config validation rejects devices with invalid `configDeviceType` values (e.g., "Lock Vision Pro" is not in valid enum)
+  - [x] **Error:** "Value is not accepted. Valid values: ..." error shown in Homebridge UI
+  - [x] **Root Cause:** Device types in existing configs may not match current DEVICE_TYPES enum (legacy names, typos, or renamed devices)
+  - [x] **Affected Devices:** Any device with `configDeviceType` not matching DEVICE_TYPES enum
+  - [x] **Solution:** Implemented device type validation migration and auto-correction
+
+  **Implementation:**
+  - Added `normalizeDeviceType()` — Validates and maps invalid types to valid equivalents
+  - Added `isValidDeviceType()` — Checks if device type is in DEVICE_TYPES enum
+  - Added `getValidDeviceTypes()` — Returns set of all valid device types
+  - Created `src/homebridge-ui/utils/device-migration.ts` — Migration utilities for batch validation
+  - Updated `src/homebridge-ui/endpoints/config.ts` — Device loading now validates types and warns about invalid ones
+  - Added migration mapping: `"Lock Vision Pro"` → `"Keypad Vision Pro"` (and others)
+  - Config endpoint returns `validationWarnings` with invalid device types and suggestions
+
+  **Status:** Device type validation is now automatic. Invalid types are detected and suggestions provided to users. Auto-correction mappings handle legacy/typo device names.
+
+---
+
+### Client-Side Refactoring
+
+#### Phase 1: Quick Wins
+
+##### Extract DEVICE_TYPES constant ✅ COMPLETED
+
+- [x] Created `src/device-types.ts` as single source of truth
+- [x] Updated `src/homebridge-ui/public/js/constants.ts` to import from shared source
+- [x] Added `DEVICE_TYPE_NORMALIZATION_MAP` for plugin type lookups
+- [x] Updated `src/deviceFactory.ts` to use normalized type mappings
+- [x] Created `scripts/sync-device-types.mjs` to auto-sync config.schema.json
+- [x] Integrated sync into build process (runs before tsc)
+
+**Status:** Device types now single-sourced with auto-sync. Config schema, UI dropdown, and plugin type handling all stay aligned automatically.
+
+##### Extract CSS styles ✅ COMPLETED
+
+![Modal Theme Mockup](mockups/modal-switchbot-theme.svg)
+
+- [x] Created `src/homebridge-ui/public/css/styles.css`
+- [x] Moved all inline styles from `src/homebridge-ui/public/index.html` (2.3kb)
+- [x] Updated HTML to `<link rel="stylesheet" href="css/styles.css">`
+- [x] Verified build copies CSS to dist/
+- [x] Tested in browser to confirm styles still work
+- [x] Added SwitchBot red color variables and theme
+- [x] Enhanced modal styling with red accent borders
+- [x] Improved button styling with hover animations
+
+**Status:** CSS now externalized and properly linked. Build copies files correctly to dist/. Modal uses SwitchBot red theme with Homebridge-like appearance.
+
+#### Phase 2: JavaScript Modularization ✅ COMPLETED
+
+- [x] Created `src/homebridge-ui/public/js/api.ts` - API client functions
+- [x] Created `src/homebridge-ui/public/js/discovery.ts` - Discovery UI rendering
+- [x] Created `src/homebridge-ui/public/js/modals.ts` - Modal management
+- [x] Created `src/homebridge-ui/public/js/credentials.ts` - Credentials UI
+- [x] Created `src/homebridge-ui/public/js/toast.ts` & `modal.ts` - UI helpers
+- [x] Created `src/homebridge-ui/public/js/app.ts` - Main app init
+- [x] Updated `src/homebridge-ui/public/index.html` to use bundled app.js
+
+**Status:** UI is modularized in TypeScript. Build bundles into app.js (47.0kb). Direct TypeScript imports provide type safety.
+
+---
+
+## Discovery System Enhancements
+
+### Signal Strength Visualization ✅ COMPLETED
+
+![Signal Strength Mockup](mockups/signal-strength-visualization.svg)
+
+- [x] Implement RSSI color-coding system:
+  - [x] Green: > -60 dBm (excellent)
+  - [x] Yellow: -60 to -75 dBm (good)
+  - [x] Orange: -75 to -85 dBm (fair)
+  - [x] Red: < -85 dBm (poor/unreliable)
+- [x] Add signal strength bars visual indicator (4-bar system)
+- [x] Add tooltip explaining signal quality
+
+**Implementation:**
+- Added `getRssiSignalQuality()` — Determines RSSI level, color, description, and bar count
+- Added `renderSignalBars()` — Visual 4-bar indicator (filled based on signal strength)
+- Added `renderSignalQualityBadge()` — Color-coded badge showing quality level (Excellent/Good/Fair/Poor)
+- Updated `renderDiscoveredDevices()` — Displays bars and badges next to device names for BLE/wireless devices
+- Tooltips show detailed signal info on hover
+
+**Status:** Signal visualization now displays for all discovered devices with RSSI data. Color-coded bars and badges provide instant visual feedback about connection quality.
+
+### Filtering & Sorting ✅ COMPLETED
+
+![Filtering & Sorting Mockup](mockups/filtering-sorting.svg)
+
+- [x] Add filter buttons: "All | BLE Only | API Only | Both | IR Devices"
+- [x] Add sort dropdown: "Signal Strength | Name | Type | Connection"
+- [x] Add search box to filter by name/ID/type (real-time filtering)
+- [x] Persist filter/sort preferences in localStorage
+
+**Implementation:**
+- Added `filterDevices()` — Filters by connection type (BLE/API/Both/IR) and search query (matches name/id/type/model)
+- Added `sortDevices()` — Sorts by name (alphabetical), signal strength (RSSI descending), device type, or connection type
+- Added `getDiscoveryPreferences()` & `setDiscoveryPreferences()` — Persist user preferences in localStorage
+- Updated `discovery.ts` — Creates filter buttons, sort dropdown, and search input dynamically
+- All filtering/sorting is client-side (instant, no API calls)
+- Search is debounced (300ms) for smooth typing
+- Filter buttons highlight active selection
+- Status shows "Showing X of Y device(s)" when filtered
+
+**Status:** Full filtering and sorting implemented with localStorage persistence. Discovery page now shows:
+- Filter bar with 5 buttons (All/BLE/API/Both/IR)
+- Sort dropdown with 4 options (Name/Signal Strength/Type/Connection)
+- Real-time search box
+- All preferences saved and restored on next discovery
+
+### One-Click Device Import ✅ COMPLETED
+
+- [x] Added "Add to Config" button for each discovered device
+- [x] Added auto-populated import modal with discovered name/type defaults
+- [x] Added BLE MAC pre-fill in import flow and persistence to config on single add
+- [x] Added confirmation toast/status messaging on successful import
+
+**Implementation:**
+- Updated discovery row action in `render.ts` to use explicit "Add to Config" CTA
+- Added `importDiscoveredDevice()` modal in `modals.ts` for prefilled import settings
+- Extended single-add client payload in `api.ts` to include optional `address`, `model`, and `rssi`
+- Extended `/add-device` endpoint in `devices.ts` to persist discovered metadata (MAC/model/RSSI)
+
+**Status:** One-click import now supports prefilled configuration and BLE MAC carry-through for direct connection setup.
+
+### Duplicate Detection ✅ COMPLETED
+
+- [x] Check if discovered device ID already exists in config
+- [x] Show badge: "✓ Already Added" (green) or "➕ New Device" (blue)
+- [x] Disable/hide "Add" button for already-added devices
+- [x] Add "View in Config" link for existing devices
+
+**Implementation:**
+- Discovery view now fetches configured device IDs and tags discovered rows as existing/new
+- Existing devices show `Already Added` state with disabled add action
+- Existing devices include a `View in Config` action that scrolls and highlights the configured entry
+
+**Status:** Duplicate devices are clearly identified at discovery time, preventing accidental re-adds and improving navigation to existing config entries.
+
+---
+
+## Bug Fixes & Technical Debt
+
+### Fix lint & lint:fix scripts ✅ COMPLETED
+
+- [x] Update ESLint configuration to include `src/homebridge-ui/**/*.ts` files
+- [x] Add HTML linting for `src/homebridge-ui/**/*.html` files
+- [x] Installed `eslint-plugin-html` for inline JavaScript in HTML
+- [x] Update `npm run lint` script to lint both plugin and UI code
+- [x] Update `npm run lint:fix` script to auto-fix both plugin and UI code
+- [x] Fixed existing ESLint errors (regex patterns, multi-statement lines)
+- [x] Lint now passes successfully
+- [x] Test that `npm run lint` runs successfully without errors
+
+**Changes Made:**
+- Installed `eslint-plugin-html` package
+- Updated `eslint.config.js` to import and configure HTML plugin
+- Added `html: true` to formatters in ESLint config
+- Updated package.json scripts: `lint` and `lint:fix` now include `src/homebridge-ui/**/*.html`
+- Moved regex patterns to module scope in `server.ts` and `genericDevice.ts`
+- Split multi-statement lines to comply with `style/max-statements-per-line` rule
+- All lint errors fixed - `npm run lint` passes with 0 errors
+
+### Fix TypeScript compilation errors in discovery endpoint ✅ COMPLETED
+
+- [x] Fixed: Changed `discover({ duration: 5000 })` to `discover({ timeout: 5000 })`
+- [x] Fixed: Changed `switchbot.getDevices()` to use `switchbot.getAPIClient()?.getDevices()`
+- [x] Reviewed node-switchbot v4.0.0-beta.3 API documentation and type definitions
+- [x] Updated discovery implementation to use correct API types (APIDevice, APIInfraredRemote)
+- [x] Fixed property names: `deviceId`, `deviceName`, `deviceType`, `remoteType`
+- [x] Removed references to non-existent properties (`id`, `name`, `type`, `model`, `deviceModel`)
+
+**Changes Made:**
+- Updated BLE discovery to use `timeout` parameter instead of `duration`
+- Changed OpenAPI access to use `switchbot.getAPIClient()?.getDevices()`
+- Simplified response parsing: `apiData.deviceList` and `apiData.infraredRemoteList` (no `body` wrapper)
+- Fixed all property accesses to match APIDevice and APIInfraredRemote interfaces
+- Build now succeeds with 0 TypeScript errors
+- All 39 tests still pass
+
+---
+
+## Notes
+
+- All completed features have been tested and verified working
+- Bundle size increased from 35.8kb → 47.0kb with new features
+- Zero TypeScript compilation errors
+- All lint checks passing
+- UI mockups available in `todo/mockups/` directory