@switchbot/homebridge-switchbot 5.0.0-beta.108 → 5.0.0-beta.109

package/TODO.md

@@ -0,0 +1,564 @@
+# SwitchBot Plugin TODO List
+
+## Code Refactoring & Architecture
+
+### Server-Side Refactoring (Priority: High)
+
+- [ ] **Split `server.ts` into modular structure**
+  - [ ] Create `src/homebridge-ui/endpoints/discovery.ts` - Discovery endpoint (~140 lines)
+  - [ ] Create `src/homebridge-ui/endpoints/config.ts` - Config management endpoint
+  - [ ] Create `src/homebridge-ui/endpoints/devices.ts` - Device CRUD operations
+  - [ ] Create `src/homebridge-ui/utils/switchbot-client.ts` - SwitchBot client initialization
+  - [ ] Create `src/homebridge-ui/utils/config-parser.ts` - Config parsing helpers
+  - [ ] Update `src/homebridge-ui/server.ts` - Main entry point (import and register endpoints)
+
+### Client-Side Refactoring (Priority: Medium)
+
+#### Phase 1: Quick Wins
+
+- [ ] **Extract DEVICE_TYPES constant** (~100 lines)
+  - [ ] Create `src/homebridge-ui/public/js/constants.js` with device types
+  - [ ] Update `index.html` to import constants
+
+- [ ] **Extract CSS styles**
+  - [ ] Create `src/homebridge-ui/public/css/styles.css`
+  - [ ] Move all inline styles from `index.html`
+  - [ ] Update HTML to link stylesheet
+
+#### Phase 2: JavaScript Modularization
+
+- [ ] **Create JavaScript modules**
+  - [ ] Create `src/homebridge-ui/public/js/api.js` - API client functions
+  - [ ] Create `src/homebridge-ui/public/js/discovery.js` - Discovery UI rendering
+  - [ ] Create `src/homebridge-ui/public/js/modals.js` - Modal management
+  - [ ] Create `src/homebridge-ui/public/js/forms.js` - Form handling
+  - [ ] Update `index.html` to use ES modules or add bundler
+
+- [ ] **Update build process**
+  - [ ] Ensure `npm run plugin-ui` copies all new files
+  - [ ] Consider adding bundler (webpack/rollup) if needed
+  - [ ] Test that UI still works after refactoring
+
+---
+
+## Discovery System Enhancements
+
+### Quick Wins (Priority: High)
+
+#### 1. One-Click Device Import
+
+- [ ] Add "Add to Config" button next to each discovered device
+- [ ] Implement auto-populate device configuration modal with discovered values
+- [ ] Pre-fill MAC address for BLE devices to enable direct connection
+- [ ] Add confirmation toast message on successful import
+
+#### 2. Signal Strength Visualization
+
+- [ ] Implement RSSI color-coding system:
+  - [ ] Green: > -60 dBm (excellent)
+  - [ ] Yellow: -60 to -75 dBm (good)
+  - [ ] Orange: -75 to -85 dBm (fair)
+  - [ ] Red: < -85 dBm (poor/unreliable)
+- [ ] Add signal strength bars visual indicator
+- [ ] Add tooltip explaining signal quality
+
+#### 3. Duplicate Detection
+
+- [ ] Check if discovered device ID already exists in config
+- [ ] Show badge: "✓ Already Added" (green) or "➕ New Device" (blue)
+- [ ] Disable/hide "Add" button for already-added devices
+- [ ] Add "View in Config" link for existing devices
+
+#### 4. Filtering & Sorting
+
+- [ ] Add filter buttons: "All | BLE Only | API Only | Both | IR Devices"
+- [ ] Add sort dropdown: "Signal Strength | Name | Type | Connection"
+- [ ] Add search box to filter by name/ID/type (real-time filtering)
+- [ ] Persist filter/sort preferences in localStorage
+
+#### 5. Better Loading States
+
+- [ ] Show progress indicator: "Scanning BLE... (5s)" → "Fetching OpenAPI..." → "Complete"
+- [ ] Add progress bar or spinner for each discovery phase
+- [ ] Display partial results as they arrive (streaming)
+- [ ] Show elapsed time for each phase
+- [ ] Add "Cancel" button to abort long scans
+
+### Medium Effort (Priority: Medium)
+
+#### 6. Device Grouping
+
+- [ ] Implement grouping by Hub (show which devices are on which hub)
+- [ ] Implement grouping by Connection Type
+- [ ] Add expandable/collapsible group headers
+- [ ] Show device count per group
+- [ ] Remember expanded/collapsed state
+
+#### 7. Connection Recommendations
+
+- [ ] Add badge: "⚡ Recommended: BLE" for devices with strong signal (> -70 dBm)
+- [ ] Add badge: "☁️ Recommended: API" for hub-dependent devices
+- [ ] Show tooltip explaining why recommendation is made
+- [ ] Consider device type (some work better with BLE vs API)
+
+#### 8. Configurable BLE Scan
+
+- [ ] Add settings panel with scan duration options (3s/5s/10s/15s)
+- [ ] Add option to disable BLE scanning if no Bluetooth adapter
+- [ ] Add option to adjust BLE timeout
+- [ ] Remember user preferences in localStorage
+- [ ] Show system Bluetooth availability status
+
+#### 9. Discovery History/Cache
+
+- [ ] Cache last discovery results for 5 minutes
+- [ ] Show "Last scanned: X minutes ago" with timestamp
+- [ ] Add "Refresh" button to re-scan
+- [ ] Show cached results immediately on page load
+- [ ] Auto-refresh option with configurable interval
+
+#### 10. Detailed Device Info Panel
+
+- [ ] Add click-to-expand device details panel
+- [ ] Show extended information:
+  - [ ] Battery level (if available)
+  - [ ] Firmware version
+  - [ ] Cloud service enabled/disabled status
+  - [ ] Last seen timestamp
+  - [ ] Full MAC address
+  - [ ] Device capabilities/features
+- [ ] Add "Copy ID" and "Copy MAC" buttons
+
+### Advanced Features (Priority: Low)
+
+#### 11. Real-Time BLE Scanning
+
+- [ ] Show devices as they're discovered (streaming results)
+- [ ] Add animated "pulsing" indicator for active BLE scan
+- [ ] Update RSSI values in real-time during scan
+- [ ] Show "X devices found..." counter during scan
+
+#### 12. Connection Testing
+
+- [ ] Add "Test Connection" button per device
+- [ ] Attempt to connect and read basic device status
+- [ ] Show success/failure indicator with details
+- [ ] Display connection latency
+- [ ] Show which connection method succeeded (BLE/API)
+
+#### 13. Batch Import
+
+- [ ] Add checkboxes to select multiple devices
+- [ ] Add "Add Selected to Config" button
+- [ ] Implement bulk configuration with smart defaults
+- [ ] Show progress for batch operations
+- [ ] Allow batch enable/disable of devices
+
+#### 14. Device Health Dashboard
+
+- [ ] Show battery warnings (< 20%) with yellow/red indicators
+- [ ] Show firmware update available indicators
+- [ ] Show offline/unreachable warnings
+- [ ] Add "Needs Attention" section at top
+- [ ] Implement battery level trending (if historical data available)
+
+#### 15. Export/Import Discovery
+
+- [ ] Add "Export Results" button (JSON format)
+- [ ] Add "Import Results" for comparison or troubleshooting
+- [ ] Share with support for debugging
+- [ ] Compare current vs previous discovery (show differences)
+- [ ] Generate discovery report (formatted summary)
+
+---
+
+## Bug Fixes & Technical Debt
+
+### Critical Issues (Priority: Critical)
+
+- [x] **Fix lint & lint:fix scripts to cover all code** ✅ 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
+
+### Current Issues
+
+- [x] **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
+
+- [ ] **Test discovery with real hardware**
+  - [ ] Test BLE discovery with nearby devices
+  - [ ] Test OpenAPI discovery with cloud-registered devices
+  - [ ] Test with mixed BLE+API devices
+  - [ ] Test connection type badge display
+  - [ ] Verify deduplication works correctly
+
+- [ ] **Add error handling improvements**
+  - [ ] Better error messages for users
+  - [ ] Retry logic with exponential backoff
+  - [ ] Graceful degradation when BLE unavailable
+  - [ ] Network timeout handling
+
+---
+
+## Documentation
+
+- [ ] **Update README with discovery features**
+  - [ ] Document BLE vs OpenAPI discovery
+  - [ ] Add screenshots of new UI features
+  - [ ] Explain connection type badges
+  - [ ] Add troubleshooting guide for discovery issues
+
+- [ ] **Create developer documentation**
+  - [ ] Document new modular structure
+  - [ ] API documentation for endpoints
+  - [ ] Contributing guidelines for UI changes
+
+---
+
+## Priority Summary
+
+### Must Do (Next Release)
+
+1. **Fix lint & lint:fix scripts** (blocks clean CI/CD)
+2. Fix TypeScript compilation errors in discovery
+3. One-Click Device Import
+4. Duplicate Detection
+5. Signal Strength Visualization
+6. Better Loading States
+
+### Should Do (Soon)
+
+1. Split server.ts into modules
+2. Extract DEVICE_TYPES constant
+3. Filtering & Sorting
+4. Connection Recommendations
+5. Device Grouping
+
+### Nice to Have (Future)
+
+1. Extract all CSS and JavaScript
+2. Configurable BLE Scan
+3. Discovery History/Cache
+4. Connection Testing
+5. Batch Import
+
+---
+
+## Notes
+
+- Consider user feedback on most-wanted features
+- Test all changes with real SwitchBot devices
+- Maintain backwards compatibility with existing configs
+- Keep UI responsive and fast (< 500ms interactions)
+- Follow Homebridge UI/UX conventions
+
+---
+
+## Detailed Implementation Steps: HTML/CSS/JS Split
+
+### Overview
+
+Split `src/homebridge-ui/public/index.html` (764 lines) into modular structure using native ES6 modules (no bundler required).
+
+**Target Structure:**
+
+```
+src/homebridge-ui/public/
+├── index.html           # Clean HTML structure (~100 lines)
+├── css/
+│   └── styles.css      # All styles (~150 lines)
+└── js/
+    ├── constants.js    # Device types (~100 lines)
+    ├── api.js          # API client (~150 lines)
+    ├── discovery.js    # Discovery rendering (~200 lines)
+    ├── modals.js       # Modal management (~100 lines)
+    ├── forms.js        # Form handling (~50 lines)
+    └── app.js          # Main entry point (~50 lines)
+```
+
+### Step 1: Extract CSS Styles
+
+**Goal:** Move all inline styles to external stylesheet
+
+- [ ] **Create CSS file**
+  - [ ] Create `src/homebridge-ui/public/css/styles.css`
+  - [ ] Copy entire `<style>` block contents from `index.html` (~100 lines)
+  - [ ] Verify no dynamic styles are being generated (all should be static CSS)
+
+- [ ] **Update HTML**
+  - [ ] Remove `<style>` block from `index.html`
+  - [ ] Add `<link rel="stylesheet" href="css/styles.css">` to `<head>`
+  - [ ] Test that styles still load correctly
+
+- [ ] **Build & Test**
+  - [ ] Run `npm run build`
+  - [ ] Verify `dist/homebridge-ui/public/css/styles.css` exists
+  - [ ] Test UI in browser (all styles should work)
+
+### Step 2: Extract DEVICE_TYPES Constant
+
+**Goal:** Extract large device types constant to separate module
+
+- [ ] **Create constants module**
+  - [ ] Create `src/homebridge-ui/public/js/constants.js`
+  - [ ] Copy DEVICE_TYPES constant (~100 lines)
+  - [ ] Add `export` statement: `export const DEVICE_TYPES = { ... }`
+  - [ ] Add any other constants currently in HTML
+
+- [ ] **Update HTML**
+  - [ ] Remove DEVICE_TYPES constant from `<script>` block
+  - [ ] Add at top of script block: `import { DEVICE_TYPES } from './js/constants.js'`
+  - [ ] Change `<script>` to `<script type="module">`
+  - [ ] Verify all DEVICE_TYPES references still work
+
+- [ ] **Build & Test**
+  - [ ] Run `npm run build`
+  - [ ] Verify `dist/homebridge-ui/public/js/constants.js` exists
+  - [ ] Test device type dropdown still populates correctly
+
+### Step 3: Extract API Functions
+
+**Goal:** Move all API/fetch functions to dedicated module
+
+- [ ] **Create API module**
+  - [ ] Create `src/homebridge-ui/public/js/api.js`
+  - [ ] Extract and export these functions:
+    - [ ] `loadConfig()` - Fetch platform config
+    - [ ] `saveConfig(config)` - Save platform config
+    - [ ] `discoverDevices()` - Trigger device discovery
+    - [ ] `addDevice(device)` - Add device to config
+    - [ ] `updateDevice(device)` - Update device in config
+    - [ ] `deleteDevice(id)` - Remove device from config
+  - [ ] Keep error handling in each function
+  - [ ] Add JSDoc comments for each function
+
+- [ ] **Update HTML**
+  - [ ] Remove API functions from `<script>` block
+  - [ ] Add import: `import * as api from './js/api.js'`
+  - [ ] Update all function calls: `loadConfig()` → `api.loadConfig()`
+  - [ ] Test all API interactions work
+
+- [ ] **Build & Test**
+  - [ ] Run `npm run build`
+  - [ ] Test load config on page load
+  - [ ] Test save config
+  - [ ] Test discovery
+
+### Step 4: Extract Discovery Rendering
+
+**Goal:** Move discovery UI rendering logic to separate module
+
+- [ ] **Create discovery module**
+  - [ ] Create `src/homebridge-ui/public/js/discovery.js`
+  - [ ] Extract and export these functions:
+    - [ ] `renderDiscoveredDevices(devices, irDevices)` - Main render function
+    - [ ] `createDeviceListItem(device)` - Create single device element
+    - [ ] `createConnectionBadge(type)` - Create connection type badge
+    - [ ] `createIRBadge()` - Create IR device badge
+    - [ ] `formatDeviceDetails(device)` - Format detail text
+  - [ ] Keep all DOM manipulation in this module
+
+- [ ] **Update HTML**
+  - [ ] Remove discovery rendering functions from `<script>` block
+  - [ ] Add import: `import * as discovery from './js/discovery.js'`
+  - [ ] Update function calls to use imported module
+  - [ ] Test discovery results render correctly
+
+- [ ] **Build & Test**
+  - [ ] Run `npm run build`
+  - [ ] Test discovery UI rendering
+  - [ ] Verify badges display correctly
+  - [ ] Test with empty results
+
+### Step 5: Extract Modal Management
+
+**Goal:** Move modal logic to dedicated module
+
+- [ ] **Create modals module**
+  - [ ] Create `src/homebridge-ui/public/js/modals.js`
+  - [ ] Extract and export these functions:
+    - [ ] `showEditModal(device)` - Show edit/add device modal
+    - [ ] `hideEditModal()` - Close edit modal
+    - [ ] `showDeleteModal(device)` - Show delete confirmation
+    - [ ] `hideDeleteModal()` - Close delete modal
+    - [ ] `populateModalForm(device)` - Fill form with device data
+    - [ ] `getModalFormData()` - Extract form data
+  - [ ] Keep modal state management in module
+
+- [ ] **Update HTML**
+  - [ ] Remove modal functions from `<script>` block
+  - [ ] Add import: `import * as modals from './js/modals.js'`
+  - [ ] Update all modal calls to use imported module
+  - [ ] Test modal open/close/submit
+
+- [ ] **Build & Test**
+  - [ ] Run `npm run build`
+  - [ ] Test add device modal
+  - [ ] Test edit device modal
+  - [ ] Test delete confirmation modal
+  - [ ] Verify form validation works
+
+### Step 6: Extract Form Handling
+
+**Goal:** Move form validation and submission logic
+
+- [ ] **Create forms module**
+  - [ ] Create `src/homebridge-ui/public/js/forms.js`
+  - [ ] Extract and export these functions:
+    - [ ] `validateDeviceForm(formData)` - Validate form inputs
+    - [ ] `handleDeviceSubmit(formData)` - Process form submission
+    - [ ] `resetForm()` - Clear form fields
+    - [ ] `formatFormData(rawData)` - Format form data for API
+    - [ ] `showFormError(field, message)` - Display validation error
+    - [ ] `clearFormErrors()` - Clear all validation errors
+
+- [ ] **Update HTML**
+  - [ ] Remove form handling functions from `<script>` block
+  - [ ] Add import: `import * as forms from './js/forms.js'`
+  - [ ] Update event handlers to use imported functions
+  - [ ] Test form validation and submission
+
+- [ ] **Build & Test**
+  - [ ] Run `npm run build`
+  - [ ] Test form validation (empty fields, invalid data)
+  - [ ] Test form submission (add/edit device)
+  - [ ] Verify error messages display correctly
+
+### Step 7: Create Main App Module
+
+**Goal:** Create central app initialization and coordination
+
+- [ ] **Create app module**
+  - [ ] Create `src/homebridge-ui/public/js/app.js`
+  - [ ] Export `init()` function that:
+    - [ ] Loads initial config on page load
+    - [ ] Sets up all event listeners
+    - [ ] Initializes UI components
+    - [ ] Handles global state
+  - [ ] Move event listeners from HTML to app.js
+  - [ ] Coordinate between all other modules
+
+- [ ] **Update HTML**
+  - [ ] Remove all remaining JavaScript from `<script>` block
+  - [ ] Keep only imports and single line: `import { init } from './js/app.js'; init();`
+  - [ ] Or use DOMContentLoaded: `document.addEventListener('DOMContentLoaded', () => init())`
+  - [ ] Remove now-empty `<script>` block if all code moved
+
+- [ ] **Build & Test**
+  - [ ] Run `npm run build`
+  - [ ] Test complete page load and initialization
+  - [ ] Test all features end-to-end
+  - [ ] Verify no console errors
+
+### Step 8: Final Cleanup and Verification
+
+**Goal:** Ensure everything works and clean up
+
+- [ ] **Verify build output**
+  - [ ] Check all files copied to `dist/homebridge-ui/public/`
+  - [ ] Verify file structure matches source
+  - [ ] Check file sizes (modules should be reasonable)
+
+- [ ] **Test all functionality**
+  - [ ] Load config on page open
+  - [ ] Add new device
+  - [ ] Edit existing device
+  - [ ] Delete device
+  - [ ] Run discovery
+  - [ ] Test all filters/sorting (if implemented)
+  - [ ] Test on different browsers (Chrome, Safari, Firefox)
+
+- [ ] **Code cleanup**
+  - [ ] Remove any unused functions
+  - [ ] Add JSDoc comments to all exports
+  - [ ] Ensure consistent code style
+  - [ ] Remove console.log statements (or convert to proper logging)
+
+- [ ] **Documentation**
+  - [ ] Update comments in code
+  - [ ] Document module dependencies
+  - [ ] Add README in `src/homebridge-ui/public/js/` if needed
+  - [ ] Update main README if UI architecture changed significantly
+
+### Step 9: Optional Enhancements
+
+**Goal:** Further improvements after basic split
+
+- [ ] **Add TypeScript for UI code**
+  - [ ] Rename `.js` files to `.ts`
+  - [ ] Add type definitions
+  - [ ] Update build to compile UI TypeScript
+  - [ ] Add type checking to lint scripts
+
+- [ ] **Add minification**
+  - [ ] Consider adding Terser for JS minification
+  - [ ] Consider adding cssnano for CSS minification
+  - [ ] Update build script for production builds
+
+- [ ] **Add source maps**
+  - [ ] Generate source maps for easier debugging
+  - [ ] Configure build to include maps
+  - [ ] Test debugging in browser DevTools
+
+---
+
+## Implementation Notes
+
+### Why Native ES6 Modules?
+
+- ✅ No bundler needed (simpler build process)
+- ✅ Native browser support (Safari 11+, Chrome 61+, Firefox 60+)
+- ✅ Easier debugging (direct source code visibility)
+- ✅ Suitable for local Homebridge UI (no network latency concerns)
+- ✅ Hot reload friendly (just refresh browser)
+
+### Browser Compatibility
+
+- ES6 modules work in all modern browsers (2017+)
+- Homebridge UI runs locally, so old browser support not critical
+- Most Homebridge users have up-to-date browsers
+
+### Build Process
+
+- Current: `npm run plugin-ui` copies `src/homebridge-ui/public` → `dist/homebridge-ui/public`
+- After split: Same command, just copies more files (no changes needed)
+- Glob pattern `**/*` already handles subdirectories
+
+### Testing Checklist
+
+Each step should be tested before moving to next:
+
+1. Build succeeds without errors
+2. Files copied to dist/ correctly
+3. UI loads in browser without errors
+4. All functionality works as before
+5. No console errors or warnings
+6. Performance is same or better