@switchbot/homebridge-switchbot 5.0.0-beta.98 → 5.0.0

package/MIGRATION.md

@@ -1,6 +1,6 @@
-# Migration notes — v4.3.x → beta
+# Migration notes — v4.3.x → v5.x
 
-This document highlights important changes and recommended actions before upgrading to the beta containing Matter and `node-switchbot@4` support.
+This document highlights important changes and recommended actions before upgrading to the release that includes Matter and stable `node-switchbot@4` support.
 
 1. Matter-first behavior
    - The plugin will prefer registering accessories with Homebridge's Matter child-bridge when `enableMatter: true` and the Homebridge Matter API is available.
@@ -9,13 +9,13 @@ This document highlights important changes and recommended actions before upgrad
 2. Configuration keys
    - `enableMatter` (boolean) — enable Matter child-bridge registration.
    - `preferMatter` (boolean) — prefer Matter for devices that support Matter descriptors; HAP fallback still available.
-   - `openApiToken` (string) — when present the plugin may prefer OpenAPI calls for cloud-reachable devices.
+   - `openApiToken` + `openApiSecret` (string) — both are required for OpenAPI discovery/calls for cloud-reachable devices.
    - `perDeviceMaxRetries`, `requestTimeout`, `maxRetries` — network retry/timing options for OpenAPI fallback.
 
    - `writeDebounceMs` (number, milliseconds, default 100) — global write coalescing debounce window. Commands sent to the same device within this window are coalesced (last-write-wins) to reduce duplicate network/API commands. Set to `0` to disable coalescing if you require immediate, per-command delivery.
 
 3. Hybrid client
-   - The plugin dynamically imports `node-switchbot` when available and falls back to OpenAPI when an `openApiToken` is configured.
+   - The plugin dynamically imports `node-switchbot` when available and uses OpenAPI fallback when both `openApiToken` and `openApiSecret` are configured.
    - If you rely on BLE-only operation, ensure devices and the host have BLE available.
 
 4. UI changes
@@ -28,8 +28,18 @@ This document highlights important changes and recommended actions before upgrad
    - Run the local test suite before upgrading to confirm TypeScript and unit tests pass: `npm run build && npm run test`.
 
 6. Rollback plan
-   - If the beta causes issues, revert to the previous stable plugin version by reinstalling the prior package or checking out the stable branch.
+   - If the upgrade causes issues, revert to the previous plugin version by reinstalling the prior package version.
 
+
+8. BLE encryption key and keyId fields
+
+- The plugin now supports BLE encryption for devices that require it (e.g., SwitchBot Lock, Curtain 3, and some sensors).
+- New config fields: `encryptionKey` and `keyId` can be set per-device in the Homebridge UI or config.json.
+- To upgrade, obtain your device's BLE encryption key and keyId from the SwitchBot app (see README for instructions) and add them to your device config if required.
+- Devices that do not require encryption can leave these fields blank.
+
+---
+ 
 7. Regenerating Matter ID maps
 
 - A helper script `scripts/generate-matter-maps.js` is included to generate `src/matter-maps.generated.ts` from official zap/matter JSON metadata. The script expects a JSON input with a `clusters` array and will write mapped `MATTER_CLUSTER_IDS` and `MATTER_ATTRIBUTE_IDS` constants.
@@ -41,4 +51,4 @@ node scripts/generate-matter-maps.js ./zap-matter.json
 
 Place the official metadata JSON as `zap-matter.json` at the repo root (or pass a path) and commit the generated `src/matter-maps.generated.ts` to keep maps up to date.
 
-If you want, I can open a PR with these notes and the changelog stub targeting a beta branch I create next.
+These notes should be kept in sync with README and CHANGELOG updates for each release.

package/README.md

@@ -21,8 +21,31 @@
    - See noble [prerequisites](https://github.com/abandonware/noble#prerequisites) for your OS. (This is used for BLE connection.)
 3. Click **Install**
 
+
 ## Configuration
 
+### OpenAPI Polling/Rate Advanced Settings (UI)
+
+You can now configure global OpenAPI polling and rate-limiting options directly from the Homebridge UI:
+
+- Go to the SwitchBot plugin settings in Homebridge Config UI X.
+- Scroll to the **Advanced Settings** section at the bottom of the page.
+- Adjust the following options as needed:
+  - **OpenAPI Polling Interval (seconds):** How often to poll devices via OpenAPI for status. Default: 300 (5 min). Min: 30. Can be overridden per device.
+  - **Enable Batched OpenAPI Polling:** Poll all OpenAPI devices in a single batch at the configured interval. Devices with per-device refreshRate are excluded from the batch.
+  - **OpenAPI Batch Polling Interval (seconds):** Interval for batched OpenAPI polling. Falls back to OpenAPI Polling Interval if not set. Default: 300.
+  - **OpenAPI Daily Request Limit:** Maximum OpenAPI requests per day allowed by the plugin. Default: 10000.
+  - **OpenAPI Reserve for Commands:** Requests reserved for user actions. When remaining budget reaches this value, background polling pauses. Default: 1000.
+  - **Reset OpenAPI Counter at Local Midnight:** If true, resets the daily OpenAPI request counter at local midnight. If false, resets at UTC midnight.
+  - **Only Allow Webhooks on Reserve:** When remaining OpenAPI budget reaches the reserve, only webhooks and user commands are allowed. Background polling/discovery pauses.
+  - **OpenAPI Batch Concurrency:** Maximum number of parallel OpenAPI status calls during a batch. Default: 5.
+  - **OpenAPI Batch Jitter (seconds):** Random startup delay before the first batch to reduce synchronized spikes. Default: 0.
+
+Click **Save Advanced Settings** to apply changes. These settings match the options available in `config.schema.json` and can be overridden per device.
+
+<!-- Optionally add a screenshot here -->
+
+
 - ### If using OpenAPI Connection
   1. Download SwitchBot App on App Store or Google Play Store
   2. Register a SwitchBot account and log in into your account
@@ -168,6 +191,9 @@
 - [SwitchBot Hub 2](https://us.switch-bot.com/products/switchbot-hub-2)
   - Supports OpenAPI & Bluetooth Low Energy (BLE) Connections
     - Enables Humidity, Temperature, and Light Sensor
+- [SwitchBot Hub Mini 2](https://us.switch-bot.com/products/switchbot-hub-mini-2)
+  - Supports OpenAPI & Bluetooth Low Energy (BLE) Connections
+    - Enables Humidity, Temperature, and Light Sensor
 - [SwitchBot Hub 3](https://us.switch-bot.com/products/switchbot-hub-3)
   - Supports OpenAPI & Bluetooth Low Energy (BLE) Connections
     - Enables Humidity, Temperature, and Light Sensor
@@ -176,9 +202,52 @@
 - [SwitchBot Water Leak Detector](https://us.switch-bot.com/products/switchbot-water-leak-detector)
   - Supports OpenAPI & Bluetooth Low Energy (BLE) Connections
 
+
+## BLE Encryption Support
+
+### BLE Encryption Key and Key ID
+
+Some SwitchBot devices (notably newer locks, curtains, and select sensors) require a BLE encryption key and keyId for secure Bluetooth communication. This plugin supports configuring these fields for each device.
+
+#### How to Obtain BLE Encryption Key and Key ID
+
+1. **Open the SwitchBot App** and select your device.
+2. Go to **Device Settings** (gear icon).
+3. Tap **Device Info**.
+4. If your device supports BLE encryption, you will see fields for **Encryption Key** and **Key ID**. (If not visible, your device may not require encryption or may need a firmware update.)
+5. Copy the **Encryption Key** and **Key ID** values.
+
+#### How to Configure in Homebridge
+
+In the Homebridge UI, when adding or editing a SwitchBot device, enter the **Encryption Key** and **Key ID** in the provided fields. These values will be securely used for BLE communication with your device.
+
+**Example device config excerpt:**
+
+```json
+{
+  "deviceId": "E7F8A1B2C3D4",
+  "deviceName": "SwitchBot Lock",
+  "enableBLE": true,
+  "encryptionKey": "0123456789abcdef0123456789abcdef",
+  "keyId": "01"
+}
+```
+
+#### Which Devices Require BLE Encryption?
+
+- SwitchBot Lock (and Lock Pro)
+- SwitchBot Curtain 3 (and some Curtain 2 with updated firmware)
+- Some sensors and new device models (see device info in app)
+
+If you are unsure, check your device's info in the SwitchBot app. If the fields are present, copy them into the plugin config.
+
+**Note:** If you enter an incorrect key or keyId, BLE communication will fail for that device. Double-check values if you encounter connection issues.
+
+---
+
 ## Supported IR Devices
 
-### _(All IR Devices require [SwitchBot Hub 2](https://us.switch-bot.com/products/switchbot-hub-2), [SwitchBot Hub 3](https://us.switch-bot.com/products/switchbot-hub-3), or [Hub Mini](https://www.switch-bot.com/products/switchbot-hub-mini))_
+### _(All IR Devices require [SwitchBot Hub 2](https://us.switch-bot.com/products/switchbot-hub-2), [SwitchBot Hub Mini 2](https://us.switch-bot.com/products/switchbot-hub-mini-2), [SwitchBot Hub 3](https://us.switch-bot.com/products/switchbot-hub-3), or [Hub Mini](https://www.switch-bot.com/products/switchbot-hub-mini))_
 
 - TV
   - Allows for On/Off and Volume Controls
@@ -238,12 +307,14 @@ Reliability and rate-limiting:
 
 These controls keep API usage smooth and predictable while preserving per-device control when needed.
 
-## What's new in the v4 beta (summary)
+## What's new with node-switchbot v4.0.0
 
 - Matter-first: when Homebridge Matter is available the plugin now prefers registering Matter accessories (with HAP fallback).
-- Hybrid client: the plugin dynamically imports `node-switchbot@4` if available and falls back to OpenAPI when `openApiToken` is configured.
+- Hybrid client: the plugin uses `node-switchbot@^4.0.0` with BLE + OpenAPI discovery and OpenAPI fallback.
+- OpenAPI credentials: cloud discovery and cloud fallback paths require both `openApiToken` and `openApiSecret`.
 - UI always served: the plugin UI is packaged into `dist/homebridge-ui` and is always served when Homebridge UI support is present; there is no platform-level opt-out.
 - OpenAPI hardening: OpenAPI calls have AbortController timeouts, jittered exponential backoff, per-device retry limits and cooldowns, and safe response parsing for resilient behavior.
+- v4 resilience enabled in discovery: plugin discovery enables retry, circuit-breaker, and connection-intelligence flags from `node-switchbot` v4.
 
 - Write coalescing (debounce): command writes to the same device are coalesced by default to avoid command floods. Configure with `writeDebounceMs` (milliseconds, default 100). Set to `0` to disable coalescing.
 
@@ -277,6 +348,16 @@ Example (excerpt):
   - [OpenWonderLabs/SwitchBotAPI](https://github.com/OpenWonderLabs/SwitchBotAPI)
   - [OpenWonderLabs/SwitchBotAPI-BLE](https://github.com/OpenWonderLabs/SwitchBotAPI-BLE)
 
+## Development / Tests
+
+- Run unit tests:
+  ```bash
+  npm run test
+  ```
+
+- Notes:
+  - Added Lock Ultra (Cloud + BLE) support with `node-switchbot` v4.
+
 ## Community
 
 - [SwitchBot (Official website)](https://www.switch-bot.com/)

package/TODO.md

@@ -0,0 +1,263 @@
+# SwitchBot Plugin TODO List
+
+## Code Refactoring & Architecture
+
+### Server-Side Refactoring (Priority: High)
+
+- [x] **Split `server.ts` into modular structure** ✅ COMPLETED
+  - [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 (Priority: Critical)
+
+### Matter Window Covering Conformance Issue
+
+- [ ] **Fix Matter window covering Drapery enum validation error**
+  - [ ] **Issue:** Matter accessory registration fails for Curtain devices
+  - [ ] **Error:** `Conformance "LF & !TL": Matter does not allow enum value Drapery (ID 4) here`
+  - [ ] **Root Cause:** windowCovering.state.type is set to "Drapery" but Matter spec requires "LF & !TL" conformance (Lift Fail without Tilt)
+  - [ ] **Solution:** Need to validate/correct window covering type mappings for Matter compatibility
+  - [ ] **Affected Devices:** Curtain-type devices (e.g., "Master Bathroom Left Curtain")
+  - [ ] **Steps to Fix:**
+    - [ ] Check Matter window covering specification for valid type combinations
+    - [ ] Update device type mapping to use compliant enum values
+    - [ ] Validate conformance rules for Lift/Tilt combinations
+    - [ ] Test with Curtain, Curtain3, and Roller Shade devices
+
+---
+
+### 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 (Priority: Medium)
+
+#### Phase 1: Quick Wins
+
+- [x] **Extract DEVICE_TYPES constant** (~100 lines) ✅ 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.
+
+
+
+# SwitchBot Plugin TODO List (2026)
+
+---
+
+## PRIORITY: HIGH (Start Here)
+
+- [ ] **One-Click Device Import**  
+    Add "Add to Config" button next to each discovered device. Dramatically speeds up onboarding, reduces manual steps for users.
+- [ ] **Auto-populate Device Config Modal**  
+    When importing, auto-fill the config modal with discovered values. Reduces user error, makes adding devices nearly frictionless.
+- [ ] **Pre-fill MAC Address for BLE Devices**  
+    Ensure BLE devices are always added with correct MAC, avoids connection issues.
+- [ ] **Duplicate Detection**  
+    Check if discovered device ID already exists in config. Prevents duplicate entries, avoids user confusion.
+
+---
+
+## PRIORITY: MEDIUM
+
+- [ ] **Confirmation Toast on Import**  
+    Show a toast message on successful import for user feedback.
+- [ ] **Loading States for Discovery**  
+    Show progress indicator, spinner, and allow cancel during discovery. Improves perceived performance and transparency.
+- [ ] **Device Grouping**  
+    Group devices by hub or connection type. Useful for users with many devices/hubs.
+- [ ] **Connection Recommendations**  
+    Show badges for recommended connection (BLE/API) based on signal/device type.
+
+---
+
+## PRIORITY: LOW
+
+- [ ] **UI Polish: Badges, View in Config, Group Headers**  
+    Add badges for "Already Added"/"New Device", view-in-config links, expandable group headers, device count per group, and remember expanded/collapsed state.
+- [ ] **Configurable BLE Scan**  
+    Add scan duration, BLE timeout, and Bluetooth availability status in settings. Remember user preferences in localStorage.
+- [ ] **Discovery History/Cache**  
+    Cache last discovery results, show last scanned timestamp, refresh button, and auto-refresh option.
+
+---
+
+**Recommendation:**
+
+Start with the HIGH priority section—these features have the biggest impact on user experience and onboarding. MEDIUM priority items improve polish and usability for power users. LOW priority items are mostly UI/UX enhancements and advanced options.
+
+- [ ] **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.ts`
+  - [ ] 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