@switchbot/homebridge-switchbot 5.0.0-beta.12 → 5.0.0-beta.121

package/todo/TODO.md

@@ -0,0 +1,190 @@
+# SwitchBot Plugin TODO List (2026)
+
+
+#### 8. Batch Import
+
+- [x] Add checkboxes to select multiple devices
+- [x] Add "Add Selected to Config" button
+- [x] Implement bulk configuration with smart defaults
+
+- [x] Show firmware update available indicators
+- [x] Show offline/unreachable warnings
+- [x] Add "Needs Attention" section at top
+- [ ] Implement battery level trending (if historical data available)
+
+#### 10. 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
+
+### Testing & Quality Assurance
+
+- [ ] **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. Better Loading States
+
+### Should Do (Soon)
+
+1. Connection Recommendations
+2. Device Grouping
+3. Test discovery with real hardware
+4. Update README with new features
+
+### Nice to Have (Future)
+
+1. Configurable BLE Scan
+2. Discovery History/Cache
+3. Connection Testing
+4. Batch Import
+5. Device Health Dashboard
+
+---
+
+## Notes
+
+- See [COMPLETED.md](COMPLETED.md) for all completed features
+- UI mockups available in [mockups/](mockups/) directory
+- 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
+# Integration: node-switchbot Beta Updates (March 2026)
+
+## Tasks to Integrate Latest node-switchbot Features
+
+
+## Next Features
+
+### Advanced Features (Priority: Low)
+
+
+
+
+#### 8. Batch Import
+
+- [ ] Add checkboxes to select multiple devices
+- [ ] Add "Add Selected to Config" button
+- [ ] Implement bulk configuration with smart defaults
+
+
+- [x] Show firmware update available indicators
+- [x] Show offline/unreachable warnings
+- [ ] Add "Needs Attention" section at top
+- [ ] Implement battery level trending (if historical data available)
+
+#### 10. 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
+
+### Testing & Quality Assurance
+
+- [ ] **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. Better Loading States
+
+### Should Do (Soon)
+
+1. Connection Recommendations
+2. Device Grouping
+3. Test discovery with real hardware
+4. Update README with new features
+
+### Nice to Have (Future)
+
+1. Configurable BLE Scan
+2. Discovery History/Cache
+3. Connection Testing
+4. Batch Import
+5. Device Health Dashboard
+
+---
+
+## Notes
+
+- See [COMPLETED.md](COMPLETED.md) for all completed features
+- UI mockups available in [mockups/](mockups/) directory
+- 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

package/todo/mockups/filtering-sorting.svg

@@ -0,0 +1,112 @@
+<svg width="700" height="500" xmlns="http://www.w3.org/2000/svg">
+  <!-- Background -->
+  <rect width="700" height="500" fill="#f5f5f5"/>
+  
+  <!-- Title -->
+  <text x="20" y="30" font-family="system-ui, -apple-system, Arial" font-size="18" font-weight="600" fill="#1a1a1a">
+    Discovery Results - Filtering &amp; Sorting
+  </text>
+  
+  <!-- Main Container -->
+  <rect x="20" y="50" width="660" height="430" rx="8" fill="#fff" stroke="#ddd" stroke-width="1"/>
+  
+  <!-- Filter Buttons -->
+  <g transform="translate(40, 75)">
+    <text x="0" y="0" font-family="system-ui" font-size="12" font-weight="600" fill="#666">Filter by Connection:</text>
+    
+    <!-- All Button (Active) -->
+    <rect x="0" y="10" width="60" height="32" rx="6" fill="#ef4444"/>
+    <text x="30" y="31" font-family="system-ui" font-size="13" font-weight="500" fill="#fff" text-anchor="middle">All</text>
+    
+    <!-- BLE Button -->
+    <rect x="70" y="10" width="80" height="32" rx="6" fill="#e5e7eb" stroke="#ddd" stroke-width="1"/>
+    <text x="110" y="31" font-family="system-ui" font-size="13" font-weight="500" fill="#4b5563" text-anchor="middle">BLE Only</text>
+    
+    <!-- API Button -->
+    <rect x="160" y="10" width="80" height="32" rx="6" fill="#e5e7eb" stroke="#ddd" stroke-width="1"/>
+    <text x="200" y="31" font-family="system-ui" font-size="13" font-weight="500" fill="#4b5563" text-anchor="middle">API Only</text>
+    
+    <!-- Both Button -->
+    <rect x="250" y="10" width="60" height="32" rx="6" fill="#e5e7eb" stroke="#ddd" stroke-width="1"/>
+    <text x="280" y="31" font-family="system-ui" font-size="13" font-weight="500" fill="#4b5563" text-anchor="middle">Both</text>
+    
+    <!-- IR Button -->
+    <rect x="320" y="10" width="100" height="32" rx="6" fill="#e5e7eb" stroke="#ddd" stroke-width="1"/>
+    <text x="370" y="31" font-family="system-ui" font-size="13" font-weight="500" fill="#4b5563" text-anchor="middle">IR Devices</text>
+  </g>
+  
+  <!-- Sort Dropdown and Search -->
+  <g transform="translate(40, 145)">
+    <text x="0" y="0" font-family="system-ui" font-size="12" font-weight="600" fill="#666">Sort by:</text>
+    
+    <!-- Sort Dropdown -->
+    <rect x="0" y="10" width="180" height="32" rx="6" fill="#fff" stroke="#d1d5db" stroke-width="1"/>
+    <text x="10" y="31" font-family="system-ui" font-size="13" fill="#1a1a1a">Signal Strength ▼</text>
+    
+    <!-- Search Box -->
+    <text x="210" y="0" font-family="system-ui" font-size="12" font-weight="600" fill="#666">Search:</text>
+    <rect x="210" y="10" width="410" height="32" rx="6" fill="#fff" stroke="#d1d5db" stroke-width="1"/>
+    <text x="220" y="31" font-family="system-ui" font-size="13" fill="#9ca3af">🔍 Search by name, ID, or type...</text>
+  </g>
+  
+  <!-- Status Line -->
+  <text x="40" y="210" font-family="system-ui" font-size="12" fill="#666">
+    Showing 12 of 12 device(s)
+  </text>
+  
+  <!-- Device List -->
+  <g transform="translate(40, 230)">
+    <!-- Device 1 -->
+    <rect x="0" y="0" width="620" height="50" rx="4" fill="#f9f9f9" stroke="#e0e0e0" stroke-width="1"/>
+    <text x="15" y="22" font-family="system-ui" font-size="14" font-weight="500" fill="#1a1a1a">Kitchen Hub</text>
+    <text x="15" y="38" font-family="monospace" font-size="11" fill="#666">B0E9FEC3F112 | Hub 2</text>
+    
+    <!-- Signal bars - 4 bars -->
+    <g transform="translate(500, 12)">
+      <rect x="0" y="12" width="6" height="3" rx="1" fill="#10b981"/>
+      <rect x="9" y="8" width="6" height="7" rx="1" fill="#10b981"/>
+      <rect x="18" y="4" width="6" height="11" rx="1" fill="#10b981"/>
+      <rect x="27" y="0" width="6" height="15" rx="1" fill="#10b981"/>
+    </g>
+    
+    <!-- Connection badge -->
+    <rect x="550" y="13" width="50" height="18" rx="4" fill="#fef3c7"/>
+    <text x="575" y="26" font-family="system-ui" font-size="10" font-weight="500" fill="#d97706" text-anchor="middle">Both</text>
+    
+    <!-- Device 2 -->
+    <rect x="0" y="60" width="620" height="50" rx="4" fill="#f9f9f9" stroke="#e0e0e0" stroke-width="1"/>
+    <text x="15" y="82" font-family="system-ui" font-size="14" font-weight="500" fill="#1a1a1a">Front Door Bot</text>
+    <text x="15" y="98" font-family="monospace" font-size="11" fill="#666">84F703B32E12 | Bot</text>
+    
+    <!-- Signal bars - 3 bars -->
+    <g transform="translate(500, 72)">
+      <rect x="0" y="12" width="6" height="3" rx="1" fill="#eab308"/>
+      <rect x="9" y="8" width="6" height="7" rx="1" fill="#eab308"/>
+      <rect x="18" y="4" width="6" height="11" rx="1" fill="#eab308"/>
+      <rect x="27" y="0" width="6" height="15" rx="1" fill="#e5e7eb"/>
+    </g>
+    
+    <!-- Connection badge -->
+    <rect x="550" y="73" width="50" height="18" rx="4" fill="#dbeafe"/>
+    <text x="575" y="86" font-family="system-ui" font-size="10" font-weight="500" fill="#3b82f6" text-anchor="middle">BLE</text>
+    
+    <!-- Device 3 -->
+    <rect x="0" y="120" width="620" height="50" rx="4" fill="#f9f9f9" stroke="#e0e0e0" stroke-width="1"/>
+    <text x="15" y="142" font-family="system-ui" font-size="14" font-weight="500" fill="#1a1a1a">Living Room TV</text>
+    <text x="15" y="158" font-family="monospace" font-size="11" fill="#666">IR-A1B2C3D4 | TV (IR)</text>
+    
+    <!-- No signal bars for IR -->
+    
+    <!-- Connection badge -->
+    <rect x="550" y="133" width="50" height="18" rx="4" fill="#fce7f3"/>
+    <text x="575" y="146" font-family="system-ui" font-size="10" font-weight="500" fill="#ec4899" text-anchor="middle">IR</text>
+  </g>
+  
+  <!-- Feature Labels -->
+  <g transform="translate(40, 450)">
+    <text x="0" y="0" font-family="system-ui" font-size="10" font-weight="600" fill="#9ca3af">Features:</text>
+    <text x="0" y="15" font-family="system-ui" font-size="9" fill="#9ca3af">✓ Real-time search with 300ms debounce</text>
+    <text x="200" y="15" font-family="system-ui" font-size="9" fill="#9ca3af">✓ Client-side filtering (instant)</text>
+    <text x="400" y="15" font-family="system-ui" font-size="9" fill="#9ca3af">✓ localStorage persistence</text>
+  </g>
+</svg>

package/todo/mockups/modal-switchbot-theme.svg

@@ -0,0 +1,66 @@
+<svg width="600" height="500" xmlns="http://www.w3.org/2000/svg">
+  <!-- Backdrop Overlay -->
+  <rect width="600" height="500" fill="rgba(0,0,0,0.7)"/>
+  
+  <!-- Modal Container -->
+  <g transform="translate(60, 80)">
+    <!-- Modal Background with Red Top Border -->
+    <rect x="0" y="4" width="480" height="370" rx="12" fill="#fff"/>
+    <rect x="0" y="0" width="480" height="4" rx="2" fill="#ef4444"/>
+    
+    <!-- Box Shadow Effect -->
+    <rect x="2" y="6" width="476" height="368" rx="12" fill="none" stroke="rgba(0,0,0,0.1)" stroke-width="2"/>
+    
+    <!-- Modal Header -->
+    <text x="24" y="50" font-family="system-ui, -apple-system, Arial" font-size="20" font-weight="600" fill="#ef4444">
+      Edit Device
+    </text>
+    
+    <!-- Content Area -->
+    <g transform="translate(24, 80)">
+      <!-- Device Name Field -->
+      <text x="0" y="0" font-family="system-ui" font-size="13" font-weight="500" fill="#374151">Device Name</text>
+      <rect x="0" y="8" width="432" height="40" rx="6" fill="#fff" stroke="#d1d5db" stroke-width="1"/>
+      <text x="10" y="33" font-family="system-ui" font-size="14" fill="#1a1a1a">Girl's Bedroom Hub</text>
+      
+      <!-- API Device Type Field (Read-only) -->
+      <text x="0" y="70" font-family="system-ui" font-size="13" font-weight="500" fill="#374151">Device Type (API - Read Only)</text>
+      <rect x="0" y="78" width="432" height="40" rx="6" fill="#f9fafb" stroke="#d1d5db" stroke-width="1"/>
+      <text x="10" y="103" font-family="system-ui" font-size="14" fill="#6b7280">Hub 2</text>
+      
+      <!-- Config Device Type Dropdown -->
+      <text x="0" y="140" font-family="system-ui" font-size="13" font-weight="500" fill="#374151">Config Device Type (Override)</text>
+      <rect x="0" y="148" width="432" height="40" rx="6" fill="#fff" stroke="#d1d5db" stroke-width="1"/>
+      <text x="10" y="173" font-family="system-ui" font-size="14" fill="#1a1a1a">Hub 2 ▼</text>
+      
+      <!-- Divider Line -->
+      <line x1="0" y1="220" x2="432" y2="220" stroke="rgba(0,0,0,0.1)" stroke-width="1"/>
+      
+      <!-- Button Group -->
+      <g transform="translate(0, 240)">
+        <!-- Cancel Button -->
+        <rect x="0" y="0" width="100" height="40" rx="6" fill="#6b7280"/>
+        <text x="50" y="25" font-family="system-ui" font-size="14" font-weight="500" fill="#fff" text-anchor="middle">Cancel</text>
+        
+        <!-- Save Button with Hover Effect -->
+        <g transform="translate(332, 0)">
+          <!-- Button Shadow -->
+          <rect x="0" y="2" width="100" height="40" rx="6" fill="rgba(239,68,68,0.2)"/>
+          <!-- Button -->
+          <rect x="0" y="0" width="100" height="40" rx="6" fill="#ef4444"/>
+          <text x="50" y="25" font-family="system-ui" font-size="14" font-weight="500" fill="#fff" text-anchor="middle">Save</text>
+        </g>
+      </g>
+    </g>
+  </g>
+  
+  <!-- Design Notes -->
+  <g transform="translate(20, 470)">
+    <text x="0" y="0" font-family="system-ui" font-size="10" font-weight="600" fill="#9ca3af">Design Elements:</text>
+    <text x="100" y="0" font-family="system-ui" font-size="9" fill="#9ca3af">● 4px SwitchBot Red top accent</text>
+    <text x="270" y="0" font-family="system-ui" font-size="9" fill="#9ca3af">● 12px border-radius</text>
+    <text x="380" y="0" font-family="system-ui" font-size="9" fill="#9ca3af">● Smooth shadows</text>
+    <text x="100" y="15" font-family="system-ui" font-size="9" fill="#9ca3af">● Red title and primary button</text>
+    <text x="270" y="15" font-family="system-ui" font-size="9" fill="#9ca3af">● Gray secondary button</text>
+  </g>
+</svg>

package/todo/mockups/signal-strength-visualization.svg

@@ -0,0 +1,94 @@
+<svg width="600" height="400" xmlns="http://www.w3.org/2000/svg">
+  <!-- Background -->
+  <rect width="600" height="400" fill="#f5f5f5"/>
+  
+  <!-- Title -->
+  <text x="20" y="30" font-family="system-ui, -apple-system, Arial" font-size="18" font-weight="600" fill="#1a1a1a">
+    Discovery Results - Signal Strength Visualization
+  </text>
+  
+  <!-- Device List Container -->
+  <rect x="20" y="50" width="560" height="330" rx="8" fill="#fff" stroke="#ddd" stroke-width="1"/>
+  
+  <!-- Device 1: Excellent Signal -->
+  <g transform="translate(40, 80)">
+    <text font-family="system-ui" font-size="14" font-weight="500" fill="#1a1a1a">Living Room Bot</text>
+    <text y="20" font-family="monospace" font-size="12" fill="#666">C1A2B3C4D5E6</text>
+    
+    <!-- RSSI Bars - 4 bars filled (Excellent) -->
+    <g transform="translate(0, 35)">
+      <rect x="0" y="12" width="8" height="4" rx="1" fill="#10b981"/>
+      <rect x="12" y="8" width="8" height="8" rx="1" fill="#10b981"/>
+      <rect x="24" y="4" width="8" height="12" rx="1" fill="#10b981"/>
+      <rect x="36" y="0" width="8" height="16" rx="1" fill="#10b981"/>
+    </g>
+    
+    <!-- Quality Badge -->
+    <rect x="60" y="35" width="80" height="20" rx="4" fill="#d1fae5"/>
+    <text x="100" y="49" font-family="system-ui" font-size="11" font-weight="500" fill="#10b981" text-anchor="middle">Excellent</text>
+    
+    <!-- RSSI Value -->
+    <text x="150" y="49" font-family="monospace" font-size="11" fill="#666">-55 dBm</text>
+    
+    <!-- Connection Badge -->
+    <rect x="220" y="35" width="45" height="20" rx="4" fill="#dbeafe"/>
+    <text x="242.5" y="49" font-family="system-ui" font-size="11" font-weight="500" fill="#3b82f6" text-anchor="middle">BLE</text>
+  </g>
+  
+  <!-- Device 2: Good Signal -->
+  <g transform="translate(40, 180)">
+    <text font-family="system-ui" font-size="14" font-weight="500" fill="#1a1a1a">Bedroom Curtain</text>
+    <text y="20" font-family="monospace" font-size="12" fill="#666">F7E8D9C0B1A2</text>
+    
+    <!-- RSSI Bars - 3 bars filled (Good) -->
+    <g transform="translate(0, 35)">
+      <rect x="0" y="12" width="8" height="4" rx="1" fill="#eab308"/>
+      <rect x="12" y="8" width="8" height="8" rx="1" fill="#eab308"/>
+      <rect x="24" y="4" width="8" height="12" rx="1" fill="#eab308"/>
+      <rect x="36" y="0" width="8" height="16" rx="1" fill="#e5e7eb"/>
+    </g>
+    
+    <!-- Quality Badge -->
+    <rect x="60" y="35" width="80" height="20" rx="4" fill="#fef9c3"/>
+    <text x="100" y="49" font-family="system-ui" font-size="11" font-weight="500" fill="#eab308" text-anchor="middle">Good</text>
+    
+    <!-- RSSI Value -->
+    <text x="150" y="49" font-family="monospace" font-size="11" fill="#666">-68 dBm</text>
+    
+    <!-- Connection Badge -->
+    <rect x="220" y="35" width="45" height="20" rx="4" fill="#dbeafe"/>
+    <text x="242.5" y="49" font-family="system-ui" font-size="11" font-weight="500" fill="#3b82f6" text-anchor="middle">BLE</text>
+  </g>
+  
+  <!-- Device 3: Fair Signal -->
+  <g transform="translate(40, 280)">
+    <text font-family="system-ui" font-size="14" font-weight="500" fill="#1a1a1a">Garage Lock</text>
+    <text y="20" font-family="monospace" font-size="12" fill="#666">A1B2C3D4E5F6</text>
+    
+    <!-- RSSI Bars - 2 bars filled (Fair) -->
+    <g transform="translate(0, 35)">
+      <rect x="0" y="12" width="8" height="4" rx="1" fill="#f97316"/>
+      <rect x="12" y="8" width="8" height="8" rx="1" fill="#f97316"/>
+      <rect x="24" y="4" width="8" height="12" rx="1" fill="#e5e7eb"/>
+      <rect x="36" y="0" width="8" height="16" rx="1" fill="#e5e7eb"/>
+    </g>
+    
+    <!-- Quality Badge -->
+    <rect x="60" y="35" width="80" height="20" rx="4" fill="#ffedd5"/>
+    <text x="100" y="49" font-family="system-ui" font-size="11" font-weight="500" fill="#f97316" text-anchor="middle">Fair</text>
+    
+    <!-- RSSI Value -->
+    <text x="150" y="49" font-family="monospace" font-size="11" fill="#666">-78 dBm</text>
+    
+    <!-- Connection Badge -->
+    <rect x="220" y="35" width="45" height="20" rx="4" fill="#dbeafe"/>
+    <text x="242.5" y="49" font-family="system-ui" font-size="11" font-weight="500" fill="#3b82f6" text-anchor="middle">BLE</text>
+  </g>
+  
+  <!-- Legend -->
+  <text x="400" y="100" font-family="system-ui" font-size="12" font-weight="600" fill="#666">Signal Quality:</text>
+  <text x="400" y="120" font-family="system-ui" font-size="11" fill="#10b981">● Excellent: &gt; -60 dBm</text>
+  <text x="400" y="140" font-family="system-ui" font-size="11" fill="#eab308">● Good: -60 to -75 dBm</text>
+  <text x="400" y="160" font-family="system-ui" font-size="11" fill="#f97316">● Fair: -75 to -85 dBm</text>
+  <text x="400" y="180" font-family="system-ui" font-size="11" fill="#ef4444">● Poor: &lt; -85 dBm</text>
+</svg>

package/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    include: ['test/**/*.spec.ts'],
+  },
+})