v4.0.0

feat: v4.0.0 - Complete rewrite with hybrid BLE/API architecture and advanced features

BREAKING CHANGES:
- 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

Major Features (v4.0.0):
- **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(), clear()
- **30 Device Types**: Full support for all SwitchBot devices
- **Event-Driven**: EventEmitter-based architecture for discovery and commands
- **TypeScript Native**: Full type safety and comprehensive type exports
- **Custom Errors**: Specific error classes (BLENotAvailableError, DeviceNotFoundError, etc.)
- **Flexible Modes**: BLE-only mode (Linux/macOS) or API-only mode (all platforms)

Additional Features (Post-4.0.0):
- **macOS BLE Support**: Enable BLE on macOS in addition to Linux
  * Platform detection now includes darwin (macOS)
  * Windows remains unsupported for BLE operations
- **Bot Password Protection**: BLE password support for Bot devices
  * CRC32 encryption for 4-char alphanumeric passwords
  * Methods: setPassword(), clearPassword(), hasPassword()
  * Automatic encrypted command execution
- **Advanced Resilience**: Enterprise-grade reliability features
  * Retry logic with exponential backoff and jitter
  * Circuit breaker pattern (CLOSED/OPEN/HALF_OPEN states)
  * Connection intelligence tracking per-device
  * Custom fallback handler system with logging, metrics, alerting

Technical Improvements:
- Complete ES2022 module implementation
- Improved error handling with custom error classes
- Better connection management and timeout handling
- Enhanced logging with configurable log levels
- Full JSDoc documentation coverage
- Comprehensive TypeScript type definitions
- Move regex patterns to module scope for performance
- Fix BLE Noble initialization race conditions
- Proper null checks to prevent "Cannot read properties of undefined"

Dependencies:
- Update @antfu/eslint-config from 5.4.1 to 7.7.0
- Update @types/node from 25.3.3 to 25.3.5
- Update eslint from 9.39.3 to 9.39.4
- Update @stoprocent/noble to ^2.3.17

Documentation:
- Add comprehensive prerequisites for BLE setup (macOS, Linux, Raspberry Pi)
- Update all "Linux-only" references to "Linux/macOS"
- Add password protection section to BLE.md
- Create bot-password.js example
- Add 6 example files covering all major use cases
- Generate TypeDoc API documentation

Tests:
- 108 comprehensive tests (up from 40 in v3.x)
- 14 new password protection tests
- Device manager tests
- Utilities tests
- Error handling tests
- Full validation of CRC32 encryption and command building

Files Changed: 431 files, 13,604 insertions(+), 12,376 deletions(-)

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

.npmignore

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

BLE.md

@@ -59,13 +59,61 @@ The `SwitchBot` class allows you to interact with SwitchBot devices using the Sw
 
 ### Supported OS
 
-The node-switchbot supports only Linux-based OSes, such as Raspbian, Ubuntu, and so on. This module does not support Windows and macOS for now. (If [@stoprocent/noble](https://github.com/stoprocent/noble#readme) is installed properly, this module might work well on such OSes.)
+The node-switchbot supports Linux-based OSes (such as Raspbian, Ubuntu) and macOS. Windows is not currently supported. BLE functionality requires [@stoprocent/noble](https://github.com/stoprocent/noble#readme) which works natively on Linux and macOS.
 
 ### Dependencies
 
-- [Node.js](https://nodejs.org/en/): ^20
-- [@stoprocent/noble](https://github.com/stoprocent/noble)
-  - Included as a dependency so no need to install manually however if for some reason your OS requires addtional libaries, see `@stoprocent/noble` [prerequisites](https://github.com/stoprocent/noble?tab=readme-ov-file#prerequisites), you will then need to reinstall `node-switchbot` or the package that you have `node-swtichbot` as a dependency.
+- [Node.js](https://nodejs.org/en/): ^20 || ^22 || ^24
+- [@stoprocent/noble](https://github.com/stoprocent/noble) - Included as a dependency
+
+### Prerequisites
+
+#### macOS
+
+- **Xcode**: Install from the App Store
+- **Bluetooth Permissions**: On newer versions of macOS, allow Bluetooth access for your terminal app:
+  1. Open "System Preferences" → "Security & Privacy" → "Privacy" → "Bluetooth"
+  2. Add and enable your terminal application (Terminal.app, iTerm.app, etc.)
+
+#### Linux (Ubuntu, Debian, Raspbian)
+
+- **Kernel**: Version 3.6 or above
+- **Required Packages**:
+
+  ```bash
+  sudo apt-get install bluetooth bluez libbluetooth-dev libudev-dev
+  ```
+
+- **Node Path**: Ensure `node` is on your PATH
+
+  ```bash
+  # If needed, symlink nodejs to node
+  sudo ln -s /usr/bin/nodejs /usr/bin/node
+  ```
+
+- **Running without sudo** (Recommended):
+
+  ```bash
+  sudo setcap cap_net_raw+eip $(eval readlink -f `which node`)
+  ```
+
+  This grants the `node` binary `cap_net_raw` privileges for BLE operations.
+
+  Required package: `sudo apt-get install libcap2-bin`
+
+- **Raspberry Pi Specific**: If having trouble connecting to BLE devices, disable the `pnat` plugin by adding this line to `/etc/bluetooth/main.conf`:
+  ```
+  DisablePlugins=pnat
+  ```
+  Then restart the system.
+
+#### Linux (Fedora and RPM-based)
+
+```bash
+sudo yum install bluez bluez-libs bluez-libs-devel
+```
+
+See [@stoprocent/noble prerequisites](https://github.com/stoprocent/noble?tab=readme-ov-file#prerequisites) for more detailed platform-specific instructions.
 
 ### Importing and Setting Up
 
@@ -587,6 +635,71 @@ switchbot
   });
 ```
 
+#### Password Protection
+
+The Bot (WoHand) supports password protection via BLE to prevent unauthorized control. When a password is set, all BLE commands (press, turnOn, turnOff, up, down) will be automatically encrypted.
+
+**Password Requirements:**
+
+- Exactly 4 characters
+- Alphanumeric only (letters and numbers)
+- Case-sensitive
+
+**Setting a Password:**
+
+```typescript
+// Using device options during construction
+const bot = new WoHand({
+  id: 'c1:2e:45:3e:20:08',
+  password: 'A1b2' // Your 4-character password
+})
+
+// Or set/change password on existing device
+await bot.setPassword('A1b2')
+```
+
+**Clearing a Password:**
+
+```typescript
+// Remove password protection
+await bot.clearPassword()
+```
+
+**Checking Password Status:**
+
+```typescript
+// Check if device has password configured
+if (bot.hasPassword()) {
+  console.log('Device is password protected')
+}
+```
+
+**Example with Password:**
+
+```typescript
+switchbot
+  .discover({ model: 'H', quick: true })
+  .then((device_list) => {
+    const bot = device_list[0]
+    // Set password for protected Bot
+    bot.setPassword('MyP4')
+    return bot.press()
+  })
+  .then(() => {
+    console.log('Password-protected Bot pressed successfully')
+  })
+  .catch((error) => {
+    console.error(error)
+  })
+```
+
+**Notes:**
+
+- Password encryption uses CRC32 checksums for secure command transmission
+- All control methods (press, turnOn, turnOff, up, down) automatically use encrypted commands when password is set
+- Password is stored in memory only and must be set each time the application starts
+- If the wrong password is configured, BLE commands will fail silently (Bot will not respond)
+
 ### `WoCurtain` Object
 
 The `WoCurtain` object represents a Curtain, which is created through the discovery process triggered by the [`switchBotBLE.discover()`](#discover-method) method.

CHANGELOG.md

@@ -2,6 +2,95 @@
 
 All notable changes to this project will be documented in this file. This project uses [Semantic Versioning](https://semver.org/)
 
+## [Unreleased]
+
+### Features
+
+* **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 (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](https://github.com/OpenWonderLabs/homebridge-switchbot/pull/1337)
+
+* **Advanced Resilience Features**: Enterprise-grade reliability enhancements
+  * Retry logic with exponential backoff and jitter (RetryExecutor)
+  * Circuit breaker pattern to prevent cascading failures (CLOSED/OPEN/HALF_OPEN states)
+  * Connection intelligence tracking per-device success/failure rates
+  * Custom fallback handler system with built-in logging, metrics, and alerting handlers
+  * Intelligent connection selection based on historical performance
+
+### Documentation
+
+* 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 all "Linux-only" references to "Linux/macOS"
+* **Added comprehensive prerequisites section** for BLE setup on macOS and Linux
+  * macOS: Xcode and Bluetooth permissions requirements
+  * Linux: System packages, non-root setup, and Raspberry Pi specific notes
+  * Based on [@stoprocent/noble prerequisites](https://github.com/stoprocent/noble?tab=readme-ov-file#prerequisites)
+
+### Tests
+
+* Added 14 comprehensive password protection tests
+* All 54 tests passing (up from 40 in v4.0.0)
+* Validation of CRC32 encryption, command building, and response parsing
+
+---
+
+## [4.0.0](https://github.com/OpenWonderLabs/node-switchbot/compare/v3.6.6...v4.0.0) (2026-03-03)
+
+### ⚠ BREAKING CHANGES
+
+* 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
+
+### Features
+
+* **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
+* **30 Device Types**: Full support for all SwitchBot devices (Bot, Curtain, Lock, Meter, Plug, Bulb, etc.)
+* **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 systems
+* **API-Only Mode**: Works without BLE on Windows/macOS
+* **Comprehensive Examples**: 6 example files covering all major use cases
+
+### Technical Improvements
+
+* Complete ES2022 module implementation
+* Improved error handling with custom error classes
+* Better connection management and timeout handling
+* Enhanced logging with configurable log levels
+* Full JSDoc documentation coverage
+* Comprehensive TypeScript type definitions for all devices
+* Production-ready test suite with Vitest
+* Auto-formatting and linting with @antfu/eslint-config
+
+### Documentation
+
+* Updated README with v4 quick start and migration guide
+* 6 usage examples in `examples/` directory
+* Migration guide from v3.x to v4.0.0
+* Full API documentation via TypeDoc
+
+---
+
 ## [3.6.6](https://github.com/OpenWonderLabs/node-switchbot/compare/v3.6.5...v3.6.6) (2026-02-25)