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

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,20 @@
+import { describe, it, expect } from 'vitest'
+import { createPlatformProxy } from '../src/utils'
+
+describe('createPlatformProxy', () => {
+  it('returns Matter platform when preferMatter and enabled', () => {
+    class HAP {}
+    class Matter {}
+    const ProxyCtor: any = createPlatformProxy(HAP, Matter)
+    const impl = new (ProxyCtor as any)(console, { preferMatter: true, enableMatter: true }, undefined)
+    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)
+  })
+})

package/todo/COMPLETED.md

@@ -0,0 +1,189 @@
+# 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
+
+### 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
+
+---
+
+## 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

package/todo/README.md

@@ -0,0 +1,59 @@
+# TODO Documentation
+
+This directory contains all task tracking and planning documentation for the SwitchBot Homebridge Plugin.
+
+## Structure
+
+```
+todo/
+├── README.md           # This file
+├── TODO.md            # Active tasks and upcoming features
+├── COMPLETED.md       # Completed features and improvements
+└── mockups/           # UI design mockups
+    ├── signal-strength-visualization.svg
+    ├── filtering-sorting.svg
+    └── modal-switchbot-theme.svg
+```
+
+## Files
+
+### [TODO.md](TODO.md)
+Active tasks and features planned for future releases. Organized by priority:
+- **Must Do (Next Release)** - Critical features blocking next release
+- **Should Do (Soon)** - Important features for near-term releases
+- **Nice to Have (Future)** - Enhancement ideas for future consideration
+
+### [COMPLETED.md](COMPLETED.md)
+Archive of completed features and bug fixes. Each completed item includes:
+- Implementation details
+- Date completed
+- Links to related code/files
+- UI mockups (if applicable)
+
+### [mockups/](mockups/)
+SVG mockups showing UI designs for completed and planned features:
+- **signal-strength-visualization.svg** - RSSI bars and quality badges for BLE devices
+- **filtering-sorting.svg** - Discovery page filters, sort options, and search
+- **modal-switchbot-theme.svg** - Edit device modal with SwitchBot red theme
+
+## Workflow
+
+1. **Planning** - New features start as unchecked items in TODO.md
+2. **Development** - Mark items as in-progress while working
+3. **Completion** - When complete, move entire section to COMPLETED.md with implementation details
+4. **UI Features** - Create SVG mockup before or after implementation for documentation
+
+## Priority Levels
+
+- **Priority: Critical** - Bugs affecting functionality or compatibility
+- **Priority: High** - Features needed for next release
+- **Priority: Medium** - Quality of life improvements
+- **Priority: Low** - Nice-to-have enhancements
+
+## Notes
+
+- Always update COMPLETED.md when marking features as done
+- Include implementation details and learnings
+- Create mockups for all UI features
+- Keep TODO.md focused on active/upcoming work
+- Archive helps track project progress over time