@switchbot/homebridge-switchbot 5.0.0-beta.15 → 5.0.0-beta.150

package/.changeset/config.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@2.3.0/schema.json",
+  "changelog": [
+    "@changesets/cli/changelog",
+    { "repo": "OpenWonderLabs/homebridge-switchbot" }
+  ],
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "latest",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

package/.github/ISSUE_TEMPLATE/e2e-verification.md

@@ -0,0 +1,36 @@
+---
+name: E2E Verification Results
+about: Submit manual E2E test results for homebridge-switchbot changes (Matter + node-switchbot v4)
+title: "[E2E] <device-type> verification"
+labels: e2e, testing
+assignees: ''
+---
+
+### Environment
+- Homebridge version:
+- Plugin commit / branch:
+- macOS version:
+- Bluetooth available: (yes/no)
+- openApiToken used: (yes/no)
+
+### Device under test
+- Device type: (Light / Fan / Curtain / Lock)
+- Device model:
+- Connection used: (BLE / OpenAPI)
+
+### Steps performed
+- Start Homebridge with plugin linked/built
+- Verified Matter registration: (yes/no)
+- Verified HAP fallback when Matter unavailable: (yes/no)
+- Operations tested: (list)
+
+### Results
+- Observed behavior (brief):
+- Any errors in plugin logs (paste relevant snippets):
+
+### Verdict
+- Pass/Fail:
+- Notes and follow-ups:
+
+### Attachments
+- Logs, screenshots, videos

package/.github/copilot-instructions.md

@@ -2,6 +2,45 @@
 
 Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.
 
+## Topic-Based Reference Priority
+
+When a prompt includes the topics below, consult these upstream references first before implementation decisions.
+
+### Matter (keyword examples: "Matter", "child bridge", "cluster", "conformance")
+
+Primary references:
+- https://github.com/homebridge-plugins/homebridge-matter
+- https://github.com/homebridge/homebridge/ - only if latest is 2.0.0 or later and contains Matter-related code or reference: 
+   - https://github.com/homebridge/homebridge/tree/beta-2.0.0/
+- https://github.com/matter-js/matter.js
+
+Usage rule:
+- For Matter behavior, conformance, clustering, or registration logic, align implementation with these references before applying local changes.
+
+### SwitchBot BLE (keyword examples: "BLE", "Bluetooth", "RSSI", "advertisement", "scan")
+
+Primary references:
+- https://github.com/OpenWonderLabs/SwitchBotAPI-BLE
+- https://github.com/sblibs/pySwitchbot
+
+Usage rule:
+- For BLE command/state/scan behavior, prefer these references for protocol expectations and payload shape.
+
+### SwitchBot OpenAPI (keyword examples: "OpenAPI", "cloud API", "device list", "command")
+
+Primary reference:
+- https://github.com/OpenWonderLabs/SwitchBotAPI
+
+Usage rule:
+- For OpenAPI device models, commands, and response fields, prioritize this reference for compatibility.
+
+### Conflict Resolution
+
+If references conflict:
+1. Prefer official upstream docs/API specs.
+2. Keep existing plugin behavior unless a clear bug is identified.
+3. Document any intentional deviation in PR notes.
+
 ## Branch Targeting Strategy
 
 When creating pull requests, ALWAYS follow this branch targeting strategy:

package/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: ["main", "latest", "beta-*"]
+  pull_request:
+    branches: ["main", "latest"]
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [22, 24]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci --legacy-peer-deps
+
+      - name: Build
+        run: npm run build
+
+      - name: Run tests
+        run: npm run test

package/.github/workflows/manual-e2e.yml

@@ -0,0 +1,115 @@
+name: Manual E2E (build + optional E2E)
+
+on:
+  workflow_dispatch:
+    inputs:
+      run_e2e:
+        description: 'Set to true to run the E2E scripts (requires network-accessible Homebridge and valid tokens)'
+        required: false
+        default: 'false'
+      hb_url:
+        description: 'Homebridge UI URL (e.g. http://host:8581)'
+        required: false
+      hb_token:
+        description: 'Homebridge UI token (store as secret or pass here)'
+        required: false
+      light_accessory_id:
+        description: 'Accessory ID for light (when running E2E)'
+        required: false
+      fan_accessory_id:
+        description: 'Accessory ID for fan (when running E2E)'
+        required: false
+      curtain_accessory_id:
+        description: 'Accessory ID for curtain (when running E2E)'
+        required: false
+      lock_accessory_id:
+        description: 'Accessory ID for lock (when running E2E)'
+        required: false
+      light_accessory_name:
+        description: 'Accessory display name for light (optional, used to resolve ID)'
+        required: false
+      fan_accessory_name:
+        description: 'Accessory display name for fan (optional, used to resolve ID)'
+        required: false
+      curtain_accessory_name:
+        description: 'Accessory display name for curtain (optional, used to resolve ID)'
+        required: false
+      lock_accessory_name:
+        description: 'Accessory display name for lock (optional, used to resolve ID)'
+        required: false
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+
+      - name: Install dependencies
+        run: npm ci --prefer-offline --no-audit --progress=false
+
+      - name: Build
+        run: npm run build
+
+      - name: Run unit tests
+        run: npm run test
+
+      - name: "Optional: Run E2E scripts"
+        if: ${{ github.event.inputs.run_e2e == 'true' }}
+        env:
+          HB_URL: ${{ github.event.inputs.hb_url }}
+          HB_TOKEN: ${{ github.event.inputs.hb_token }}
+          LIGHT_ACCESSORY_ID: ${{ github.event.inputs.light_accessory_id }}
+          FAN_ACCESSORY_ID: ${{ github.event.inputs.fan_accessory_id }}
+          CURTAIN_ACCESSORY_ID: ${{ github.event.inputs.curtain_accessory_id }}
+          LOCK_ACCESSORY_ID: ${{ github.event.inputs.lock_accessory_id }}
+          LIGHT_ACCESSORY_NAME: ${{ github.event.inputs.light_accessory_name }}
+          FAN_ACCESSORY_NAME: ${{ github.event.inputs.fan_accessory_name }}
+          CURTAIN_ACCESSORY_NAME: ${{ github.event.inputs.curtain_accessory_name }}
+          LOCK_ACCESSORY_NAME: ${{ github.event.inputs.lock_accessory_name }}
+        run: |
+          echo "Running E2E scripts on runner ($HB_URL) - ensure the runner can access Homebridge and devices"
+          # resolve accessory IDs from names when IDs not provided
+          echo "Resolving accessory IDs from names (if provided)..."
+          rm -f resolved_ids.env || true
+          touch resolved_ids.env
+
+          resolve() {
+            idvar="$1"
+            namevar="$2"
+            nameval="$(eval echo \"\$$namevar\")"
+            idval="$(eval echo \"\$$idvar\")"
+            if [[ -z "$idval" && -n "$nameval" ]]; then
+              resp=$(curl -sS -H "Authorization: Bearer ${HB_TOKEN}" "${HB_URL}/api/accessories" || true)
+              found=$(printf '%s' "$resp" | node -e "const fs=require('fs');const name=process.argv[1];try{const j=JSON.parse(fs.readFileSync(0,'utf8'));const arr=Array.isArray(j)?j:(j.accessories||j)||[];for(const a of arr){if(a.displayName===name||a.name===name||(a.context&&a.context.deviceId===name)){if(a.aid){console.log(a.aid);process.exit(0);}else if(a.UUID){console.log(a.UUID);process.exit(0);}}} }catch(e){}" "$nameval" )
+              if [[ -n "$found" ]]; then
+                echo "Resolved $idvar=$found"
+                echo "$idvar=$found" >> resolved_ids.env
+                export "$idvar"="$found"
+              else
+                echo "Could not resolve $namevar='$nameval' to an id"
+              fi
+            fi
+          }
+
+          resolve LIGHT_ACCESSORY_ID LIGHT_ACCESSORY_NAME
+          resolve FAN_ACCESSORY_ID FAN_ACCESSORY_NAME
+          resolve CURTAIN_ACCESSORY_ID CURTAIN_ACCESSORY_NAME
+          resolve LOCK_ACCESSORY_ID LOCK_ACCESSORY_NAME
+
+          # set RUN_E2E so the conditional Vitest harness executes
+          export RUN_E2E=true
+          npm run test
+
+      - name: Upload logs (if any)
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-logs
+          path: |
+            test-output.log

package/.github/workflows/release.yml

@@ -22,8 +22,6 @@ jobs:
     with:
       release_type: ${{ needs.determine-release-type.outputs.release_type }}
       is_esm: ${{ needs.determine-release-type.outputs.is_esm == 'true' }}
-    secrets:
-      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
 
   # 3️⃣ Publish to NPM and create GitHub release
   publish-release:
@@ -48,8 +46,6 @@ jobs:
       branch_name: ${{ needs.determine-release-type.outputs.branch_name }}
       release_type: ${{ needs.determine-release-type.outputs.release_type }}
       is_esm: ${{ needs.determine-release-type.outputs.is_esm == 'true' }}
-    secrets:
-      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
 
   # 5️⃣ Notify if any previous job fails
   workflow-failure:

package/.husky/pre-push

@@ -0,0 +1,15 @@
+#!/bin/sh
+. "$(dirname "$0")/_/husky.sh"
+
+echo "Running changeset version before push..."
+if npx @changesets/cli version --yes; then
+  git add package.json package-lock.json CHANGELOG.md || true
+  if ! git diff --staged --quiet; then
+    echo "Committing version and changelog updates"
+    git commit -m "chore(release): version packages [skip ci]" || true
+  else
+    echo "No version changes to commit"
+  fi
+else
+  echo "changeset version failed or no changesets present"
+fi

package/CHANGELOG.md

@@ -1,7 +1,42 @@
 # Changelog
 
+## Unreleased — beta-4.3.3
+
+### Added
+- Matter support (child-bridge) with Matter-first registration and HAP fallback.
+- Hybrid `node-switchbot@4` client adapter (BLE + OpenAPI) with OpenAPI fallback.
+- Manual and automated E2E scripts for lights, fans, curtains, and locks (`scripts/e2e/*`).
+- Conditional Vitest E2E harness (`RUN_E2E=true`) and a manual GitHub Actions workflow to run E2E.
+
+### Changed
+- Centralized Matter cluster/attribute numeric ID maps in `src/utils.ts`.
+- Device descriptors refactored to use canonical Matter IDs.
+- OpenAPI fallback hardened with timeouts, retries, backoff, and per-device retry limits.
+
+### Tests
+- Added integration tests and a Matter test harness under `test/`.
+
+### Notes
+- This is a beta release; follow migration notes in MIGRATION.md before upgrading.
+# Changelog
+
 All notable changes to this project will be documented in this file. This project uses [Semantic Versioning](https://semver.org/)
 
+## [Unreleased]
+
+### What's Changed
+- Matter platform: register only devices discovered via the SwitchBot OpenAPI by default. Per-device config overrides (by deviceId) are correctly merged into discovered devices.
+- Add `options.allowConfigOnlyDevices` (boolean) to opt-in to registering devices that exist only in config (not discovered).
+- Add unit tests for per-device merging and config-only behavior.
+ - Matter (Matter platform): default to discovery-first registration and automatically remove previously-registered "stale" accessories that are no longer discovered or configured.
+ - Add `options.keepStaleAccessories` (Advanced Settings) — opt-in to preserve previously-registered accessories when set to true. Default: false (stale accessories are removed automatically).
+ - Implement per-device OpenAPI polling with tracked timers and proper lifecycle cleanup (timers and BLE handlers cleared on unregister/shutdown).
+ - Centralize OpenAPI/BLE -> Matter mapping and expand BLE/OpenAPI parsing to include PM2.5/PM10/VOC/CO2, temperature/humidity, improved color parsing, and additional sensor/robot-vacuum fields.
+ - Prefer accessory-specific update helpers where available; fall back to generic Matter updates otherwise.
+ - Add unit tests covering BLE parsing, stale-accessory behavior, mapping helpers, and lifecycle cleanup.
+ - Add `options.dailyApiResetLocalMidnight` (boolean) to control whether the daily API budget resets at local midnight (true) or UTC midnight (false, default).
+ - Fix configuration schema placement for the "Reset Daily Counter at Local Midnight" option: remove erroneous insertion inside IR remote type list and expose it correctly under platform `options`.
+
 ## [4.3.1](https://github.com/OpenWonderLabs/homebridge-switchbot/releases/tag/v4.3.1) (2025-03-04)
 
 # *No New Releases During Lent*

package/E2E-VERIFICATION.md

@@ -0,0 +1,121 @@
+# Manual End-to-End Verification
+
+This guide walks through manual end-to-end verification for representative devices (light, fan, curtain, lock) across BLE and OpenAPI paths, and verifies Matter-first behavior with HAP fallback.
+
+## Prerequisites
+
+- macOS with Bluetooth (for BLE verification)
+- Local development environment set up (Node.js, npm)
+- Homebridge installed locally or available (for running a test instance)
+- SwitchBot devices available (at least one light, one fan, one curtain, one lock) OR corresponding cloud-hub access
+- `openApiToken` when testing OpenAPI path
+
+## Quick setup
+
+1. Install dependencies:
+
+```bash
+npm install --legacy-peer-deps
+```
+
+2. Build the plugin:
+
+```bash
+npm run build
+```
+
+3. Recommended: run the watch task which links the plugin and restarts on changes (requires a local Homebridge installation):
+
+```bash
+npm run watch
+```
+
+Alternative (manual linking):
+
+```bash
+npm run build && npm link
+# then run your Homebridge instance (system/homebridge UI) so it picks up the linked plugin
+```
+
+## Example platform config snippets
+
+OpenAPI (cloud) path — enable Matter preference:
+
+```json
+{
+  "platform": "SwitchBot",
+  "openApiToken": "<YOUR_OPENAPI_TOKEN>",
+  "enableMatter": true,
+  "preferMatter": true
+}
+```
+
+BLE (direct) path — specify device by MAC address and prefer Matter:
+
+```json
+{
+  "platform": "SwitchBot",
+  "devices": [
+    { "deviceId": "AA:BB:CC:DD:EE:FF", "type": "Light" }
+  ],
+  "enableMatter": true,
+  "preferMatter": true
+}
+```
+
+## Verification checklist
+
+Run the steps below for each device type; repeat once using BLE and once using OpenAPI (where applicable).
+
+- Start Homebridge (with the plugin linked) and verify the plugin logs indicate Matter registration attempt.
+  - Look for log lines: `Attempting Matter registration for ...` or `Homebridge Matter API not available; will fallback to HAP`.
+- Confirm accessories are registered in Matter (if Homebridge Matter child-bridge present) or appear as HAP accessories otherwise.
+
+Device-specific tests
+
+- Light
+  - Toggle On/Off from Home app (or Homebridge UI) and confirm device responds.
+  - Set brightness to 25%, 50%, 100% and confirm device reports matching levels.
+  - If supported, change color temperature and/or color; confirm device applies new values.
+
+- Fan
+  - Toggle On/Off and verify.
+  - Change rotation speed in steps (e.g., 25%, 50%, 100%).
+  - Toggle oscillation / swing and verify position changes.
+
+- Curtain
+  - Open and Close via Home app / controller and verify movement.
+  - Set specific position (e.g., 50%) and verify accurate reporting.
+
+- Lock
+  - Lock and Unlock from controller and verify state.
+  - If lock user management supported, add/remove a test user per plugin UI and verify expected behavior.
+
+## Logs & debugging
+
+- Enable verbose logs from Homebridge or the plugin. Example: start Homebridge with a higher log level, or watch console output from `npm run watch`.
+- Capture logs while you perform each operation; note the request path used by the plugin:
+  - For OpenAPI: logs will show `https://api.switch-bot.com/v1.0/...` calls.
+  - For BLE: logs will show local device discovery / BLE connect attempts.
+
+## Run validation script (optional)
+
+You can run the TypeScript build and unit tests to confirm the codebase is healthy before manual tests:
+
+```bash
+npm run build && npm run test
+```
+
+## Expected outcomes
+
+- Matter-first registration: when Homebridge Matter API is available and `enableMatter` is true, accessories should be registered as Matter child-bridge accessories and re-used if restored from cache.
+- HAP fallback: when Matter API is not available, the plugin must continue to register HAP accessories and reuse restored accessories by `accessory.context.deviceId`.
+- Hybrid client paths: when `openApiToken` present the plugin should prefer OpenAPI for devices reachable via cloud; when BLE is available and configured the plugin should connect directly via BLE.
+- Logs should show robust retry attempts for transient network errors and per-device retry throttling if configured.
+
+## Next steps I can take
+
+- Create small automated verification scripts that use the Homebridge API test harness to toggle characteristic values (requires more test harness code).
+- Generate a printable checklist or a GitHub issue template for manual verification results.
+
+If you want, I can add the automated verification scripts now — would you prefer a simple script that exercises On/Off and Brightness for lights, or a broader script covering all device types?

package/MIGRATION.md

@@ -0,0 +1,54 @@
+# Migration notes — v4.3.x → beta
+
+This document highlights important changes and recommended actions before upgrading to the beta containing Matter and `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.
+   - If Matter is not available, the plugin falls back to HAP and will reuse restored accessories by `accessory.context.deviceId`.
+
+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.
+   - `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.
+   - If you rely on BLE-only operation, ensure devices and the host have BLE available.
+
+4. UI changes
+   - A small plugin UI was added; it's only enabled/copied into `dist/homebridge-ui` when `npm run build` is run and the UI files exist in `src/homebridge-ui/public`.
+
+   - The UI is always served when Homebridge UI support is present; there is no opt-out flag in the platform config. The server-side guard that previously allowed disabling the UI has been removed—if you need to restrict access, manage it via Homebridge UI / host network access controls.
+
+5. Tests and verification
+   - Manual E2E scripts are provided in `scripts/e2e/` and a GitHub `workflow_dispatch` job can optionally run them against a reachable Homebridge.
+   - 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.
+
+
+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.
+- Usage example:
+
+```bash
+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.