Releases · OpenWonderLabs/node-switchbot

11 Apr 01:26

github-actions

v4.0.0

3673b9c

v4.0.0 Latest

Latest

⚠ 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
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
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.

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
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

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
Added password protection section to BLE.md
Updated 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
Full API documentation via TypeDoc