v4.0.0 (#330)

* Complete rewrite with unified hybrid BLE/API architecture
* No backward compatibility with v3.x - migration required
* Single `SwitchBot` class replaces `SwitchBotBLE` and `SwitchBotOpenAPI`
* Device access via `switchbot.devices` manager pattern
* Full TypeScript rewrite with comprehensive type definitions

* **Hybrid Architecture**: Unified BLE-first approach with automatic OpenAPI fallback
* **Automatic Discovery**: Combined BLE + OpenAPI device discovery in single call
* **Smart Fallback**: Commands automatically retry via API when BLE fails
* **Device Manager**: Centralized device management with `get()`, `list()`, and `clear()` methods
* **Expanded Device Coverage**: Added support and parsing updates across newly modeled devices and accessories in the v4 architecture.
* **macOS BLE Support**: Enabled BLE functionality on macOS in addition to Linux
  * Platform detection now includes macOS (`darwin`) using `@stoprocent/noble`
  * BLE now works on Linux and macOS systems
  * Windows remains unsupported for BLE operations
* **Bot Password Protection**: Added BLE password support for Bot (`WoHand`) devices
  * Password encryption using CRC32 checksums
  * Password validation for 4 alphanumeric characters, case-sensitive
  * Methods: `setPassword()`, `clearPassword()`, `hasPassword()`
  * Automatic encrypted command execution when password is set
  * Example: `examples/bot-password.js`
  * Based on [homebridge-switchbot PR #1337](OpenWonderLabs/homebridge-switchbot#1337)
* **Advanced Resilience Features**: Enterprise-grade reliability enhancements
  * Retry logic with exponential backoff and jitter
  * Circuit breaker pattern to prevent cascading failures
  * Connection intelligence tracking per-device success and failure rates
  * Custom fallback handler system for logging, metrics, and alerting
  * Intelligent connection selection based on historical performance
* **Event-Driven**: EventEmitter-based architecture for discovery and command events
* **TypeScript Native**: Written in TypeScript with full type safety and exports
* **Custom Errors**: Specific error classes for better error handling
* **BLE-Only Mode**: Works without OpenAPI credentials on Linux/macOS systems
* **API-Only Mode**: Works without BLE on Windows systems
* **Exports and API Surface Updates**: Updated `src/index.ts` exports for final v4 public API packaging.
* **Comprehensive Examples**: Updated and aligned example files for v4 usage patterns.

* Complete ES2022 module implementation
* Improved error handling with custom error classes
* Better connection management and timeout handling
* Enhanced logging with configurable log levels
* Hardened dependency graph with security overrides for vulnerable transitive packages
* Full JSDoc documentation coverage
* Comprehensive TypeScript type definitions for all devices
* Reworked test suite structure and coverage for APIs, devices, and utilities
* Auto-formatting and linting with @antfu/eslint-config

* Updated README with v4 quick start and migration guide
* 6 usage examples in `examples/` directory
* Migration guide from v3.x to v4.0.0
* Added password protection section to [BLE.md](BLE.md)
* Updated [README.md](README.md) with password examples
* Created comprehensive password protection example
* Updated examples index with `bot-password.js`
* Updated platform support documentation to reflect macOS BLE support
* Updated Linux-only references to Linux/macOS where applicable
* Added comprehensive prerequisites guidance for BLE setup on macOS and Linux
  * macOS: Xcode and Bluetooth permissions requirements
  * Linux: system packages, non-root setup, and Raspberry Pi notes
  * Based on [@stoprocent/noble prerequisites](https://github.com/stoprocent/noble?tab=readme-ov-file#prerequisites)
* Full API documentation via TypeDoc

* Added 14 comprehensive password protection tests
* Validation for CRC32 encryption, command building, and response parsing
* Extended fallback and retry behavior coverage across BLE/API paths
* 58 test files and 243 passing tests at release validation

**Full Changelog**: v3.6.8...v4.0.0

chore(release): v3.6.9 [skip ci]

Author: donavanbecker

.github/copilot-instructions.md

@@ -21,11 +21,25 @@ Always reference these instructions first and fallback to search or bash command
 - **Use lint:fix for automatic fixes**: `npm run lint:fix` to automatically fix ESLint issues
 
 ### Platform Requirements and Constraints
-- **BLE functionality requires Linux-based OS only** (Raspbian, Ubuntu, etc.)
-- **Windows and macOS are NOT supported** for BLE operations (use OpenAPI instead)
+- **BLE functionality requires Linux or macOS** (Raspbian, Ubuntu, macOS, etc.)
+- **Windows is NOT supported** for BLE operations (use OpenAPI instead)
 - **Node.js versions**: Must use ^20, ^22, or ^24 (currently using v20.19.4)
 - **ES Modules**: This project uses `"type": "module"` - always use ES import/export syntax
 
+#### BLE Prerequisites
+
+**macOS:**
+- Xcode installed
+- Bluetooth permissions enabled for terminal app in System Preferences
+
+**Linux (Ubuntu/Debian/Raspbian):**
+- Required packages: `sudo apt-get install bluetooth bluez libbluetooth-dev libudev-dev`
+- For non-root access: `sudo setcap cap_net_raw+eip $(eval readlink -f \`which node\`)`
+- Raspberry Pi: May need to disable pnat plugin in `/etc/bluetooth/main.conf`
+
+**Linux (Fedora/RPM):**
+- Required packages: `sudo yum install bluez bluez-libs bluez-libs-devel`
+
 ### Testing and Validation
 - **Basic functionality test**: After any changes to core classes, run this validation:
   ```javascript
@@ -116,9 +130,9 @@ Always reference these instructions first and fallback to search or bash command
 ## Troubleshooting Common Issues
 
 ### BLE Not Working
-- **Check OS**: BLE only works on Linux-based systems
+- **Check OS**: BLE works on Linux and macOS systems only
 - **Install noble prerequisites**: May need additional system libraries for @stoprocent/noble
-- **Use OpenAPI instead**: For Windows/macOS development, use SwitchBotOpenAPI class
+- **Use OpenAPI instead**: For Windows development, use SwitchBotOpenAPI class
 
 ### Build Failures
 - **Check Node.js version**: Must be ^20, ^22, or ^24
@@ -156,7 +170,7 @@ npm run watch       # Build and link for development
 - **Type definitions**: All device status and response types
 
 ### Dependencies Summary
-- **@stoprocent/noble**: BLE functionality (Linux only)
+- **@stoprocent/noble**: BLE functionality (Linux/macOS)
 - **undici**: HTTP client for API requests
 - **async-mutex**: Concurrency control
 - **TypeScript**: Language and compilation

.github/workflows/beta-release.yml

@@ -1,30 +1,78 @@
-name: Unified Release
+name: Release
 
 on:
   push:
     branches:
-      #- "alpha-*"
-      #- "beta-*"
-      - latest
+      - 'beta-*'
+      - 'beta'
+      - 'latest'
   workflow_dispatch:
 
 jobs:
+  # ─── BETA RELEASE (branches starting with "beta") ────────────────────────────
+
+  # 1️⃣ Build and test
+  build_and_test:
+    if: startsWith(github.ref_name, 'beta')
+    uses: homebridge/.github/.github/workflows/nodejs-build-and-test.yml@latest
+    with:
+      enable_coverage: false
+    secrets:
+      token: ${{ secrets.GITHUB_TOKEN }}
+
+  # 2️⃣ Lint
+  lint:
+    if: startsWith(github.ref_name, 'beta')
+    needs: build_and_test
+    uses: homebridge/.github/.github/workflows/eslint.yml@latest
+
+  # 3️⃣ Publish beta to NPM (OIDC — id-token required here and in the reusable workflow)
+  beta-publish:
+    if: startsWith(github.ref_name, 'beta')
+    needs: lint
+    permissions:
+      id-token: write
+    uses: homebridge/.github/.github/workflows/npm-publish-esm-oidc.yml@latest
+    with:
+      tag: 'beta'
+      dynamically_adjust_version: true
+      npm_version_command: 'pre'
+      pre_id: 'beta'
+
+  # 4️⃣ Create GitHub pre-release
+  beta-pre-release:
+    if: startsWith(github.ref_name, 'beta')
+    needs: beta-publish
+    uses: homebridge/.github/.github/workflows/pre-release.yml@latest
+    with:
+      npm_version: ${{ needs.beta-publish.outputs.NPM_VERSION }}
+      body: |
+        **Beta Release**
+        **Version**: v${{ needs.beta-publish.outputs.NPM_VERSION }}
+        [How To Test Beta Releases](https://github.com/OpenWonderLabs/homebridge-switchbot/wiki/Beta-Version)
+
+
+  # ─── STABLE RELEASE (branch: "latest") ───────────────────────────────────────
+
   # 1️⃣ Determine release type, ESM status, and branch name
   determine-release-type:
+    if: github.ref_name == 'latest'
     uses: homebridge/.github/.github/workflows/determine-release-type.yml@latest
     with:
       ref_name: ${{ github.ref_name }}
 
   # 2️⃣ Update version and changelog using the scripts
   update-version:
+    if: github.ref_name == 'latest'
     needs: determine-release-type
     uses: homebridge/.github/.github/workflows/update-version.yml@latest
     with:
       release_type: ${{ needs.determine-release-type.outputs.release_type }}
       is_esm: ${{ needs.determine-release-type.outputs.is_esm == 'true' }}
 
-  # 3️⃣ Publish to NPM and create GitHub release
+  # 3️⃣ Publish to NPM and create GitHub release (OIDC — id-token required here and in the reusable workflow)
   publish-release:
+    if: github.ref_name == 'latest'
     needs: [determine-release-type, update-version]
     permissions:
       id-token: write
@@ -39,33 +87,34 @@ jobs:
 
   # 4️⃣ Promote branch if this is a prerelease (alpha/beta)
   promote-branch:
+    if: ${{ github.ref_name == 'latest' && needs.determine-release-type.outputs.release_type != 'latest' && needs.determine-release-type.outputs.release_type != 'skip' }}
     needs: [determine-release-type, publish-release]
-    if: ${{ needs.determine-release-type.outputs.release_type != 'latest' && needs.determine-release-type.outputs.release_type != 'skip' }}
     uses: homebridge/.github/.github/workflows/promote-branch.yml@latest
     with:
       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' }}
 
-  # 5️⃣ Notify if any previous job fails
+  # 5️⃣ Notify if any stable-release job fails
   workflow-failure:
-    if: ${{ failure() }}
+    if: failure()
     needs: [determine-release-type, update-version, publish-release, promote-branch]
     uses: homebridge/.github/.github/workflows/report-failure.yml@latest
     with:
       workflow_name: ${{ github.workflow }}
       job_name: ${{ github.job }}
       run_url: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
 
-  # 6️⃣ Post to Discord
-  github-releases-to-discord:
-    name: Discord Webhooks
-    needs: [determine-release-type, update-version, publish-release]
+  # 6️⃣ Post to Discord (Beta + Stable)
+  discord:
+    name: Release Notifications
+    if: ${{ always() && ((startsWith(github.ref_name, 'beta') && needs.beta-publish.result == 'success') || (github.ref_name == 'latest' && needs.publish-release.result == 'success')) }}
+    needs: [beta-publish, update-version, publish-release]
     uses: homebridge/.github/.github/workflows/discord-webhooks.yml@latest
     with:
-      title: "Node-SwitchBot Module Release"
+      title: ${{ startsWith(github.ref_name, 'beta') && 'SwitchBot-Node Beta Release' || 'SwitchBot-Node Release' }}
       description: |
-        Version `v${{ needs.update-version.outputs.version }}`
-      url: "https://github.com/OpenWonderLabs/node-switchbot/releases/tag/v${{ needs.update-version.outputs.version }}"
+        Version `v${{ startsWith(github.ref_name, 'beta') && needs.beta-publish.outputs.NPM_VERSION || needs.update-version.outputs.version }}`
+      url: "https://github.com/OpenWonderLabs/node-switchbot/releases/tag/v${{ startsWith(github.ref_name, 'beta') && needs.beta-publish.outputs.NPM_VERSION || needs.update-version.outputs.version }}"
     secrets:
       DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK_URL_LATEST }}

.github/workflows/release.yml

@@ -3,10 +3,10 @@ name: Stale workflow
 on:
   workflow_dispatch:
   schedule:
-    - cron: '45 11 * * *'
+    - cron: '45 7 * * *'
 
 jobs:
   stale:
-    uses: OpenWonderLabs/.github/.github/workflows/stale.yml@latest
+    uses: homebridge/.github/.github/workflows/stale.yml@latest
     secrets:
       token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/stale.yml

@@ -2,6 +2,14 @@
 
 src
 
+# v4.0.0 additions
+test/
+examples/
+.dev-archive/
+vitest.config.ts
+typedoc.json
+eslint.config.js
+
 # ------------- Defaults -------------
 
 # eslint