node-switchbot 4.0.0-beta.1 → 4.0.0-beta.3

package/BLE.md

@@ -587,6 +587,69 @@ 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.

package/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 All notable changes to this project will be documented in this file. This project uses [Semantic Versioning](https://semver.org/)
 
+## [Unreleased]
+
+### Features
+
+* **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
+
+### 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

package/README.md

@@ -66,6 +66,12 @@ await bot.turnOn()
 await bot.turnOff()
 await bot.press()
 
+// Bot with Password Protection (BLE only)
+const protectedBot = new WoHand({ id: 'YOUR_BOT_ID', password: 'A1b2' })
+await protectedBot.setPassword('A1b2')  // Set 4-char alphanumeric password
+await protectedBot.press()              // Commands are automatically encrypted
+await protectedBot.clearPassword()      // Remove password protection
+
 // Curtain - Position control
 await curtain.open()
 await curtain.close()

package/dist/devices/base.d.ts

@@ -1,12 +1,13 @@
 import type { OpenAPIClient } from '../api.js';
 import type { BLEConnection } from '../ble.js';
 import type { CommandResult, ConnectionType, DeviceInfo, DeviceStatus } from '../types/index.js';
+import type { CircuitBreakerConfig, FallbackHandler, FallbackHandlerOptions, RetryConfig } from '../utils/index.js';
 import { Buffer } from 'node:buffer';
 import { EventEmitter } from 'node:events';
-import { Logger } from '../utils/index.js';
+import { CircuitBreaker, ConnectionTracker, FallbackHandlerManager, Logger, RetryExecutor } from '../utils/index.js';
 /**
  * Base class for all SwitchBot devices
- * Provides hybrid BLE/API functionality with automatic fallback
+ * Provides hybrid BLE/API functionality with automatic fallback, circuit breaker, and connection intelligence
  */
 export declare abstract class SwitchBotDevice extends EventEmitter {
     protected info: DeviceInfo;
@@ -15,11 +16,24 @@ export declare abstract class SwitchBotDevice extends EventEmitter {
     protected apiClient?: OpenAPIClient;
     protected enableFallback: boolean;
     protected preferredConnection: ConnectionType;
+    protected connectionTracker: ConnectionTracker;
+    protected circuitBreakerBLE: CircuitBreaker;
+    protected circuitBreakerAPI: CircuitBreaker;
+    protected fallbackHandlerManager: FallbackHandlerManager;
+    protected retryExecutor: RetryExecutor;
+    protected enableConnectionIntelligence: boolean;
+    protected enableCircuitBreaker: boolean;
+    protected enableRetry: boolean;
     constructor(info: DeviceInfo, options?: {
         bleConnection?: BLEConnection;
         apiClient?: OpenAPIClient;
         enableFallback?: boolean;
         preferredConnection?: ConnectionType;
+        enableConnectionIntelligence?: boolean;
+        enableCircuitBreaker?: boolean;
+        enableRetry?: boolean;
+        retryConfig?: RetryConfig;
+        circuitBreakerConfig?: CircuitBreakerConfig;
         logLevel?: number;
     });
     /**
@@ -59,15 +73,19 @@ export declare abstract class SwitchBotDevice extends EventEmitter {
      */
     abstract getStatus(): Promise<DeviceStatus>;
     /**
-     * Send a command via BLE
+     * Send a command via BLE with circuit breaker and retry logic
      */
     protected sendBLECommand(command: readonly number[] | number[] | Buffer): Promise<CommandResult>;
     /**
-     * Send a command via OpenAPI
+     * Send a command via OpenAPI with circuit breaker and retry logic
      */
     protected sendAPICommand(command: string, parameter?: any): Promise<CommandResult>;
     /**
-     * Send a command with automatic BLE/API fallback
+     * Get best connection type based on intelligence tracking
+     */
+    private getBestConnection;
+    /**
+     * Send a command with automatic BLE/API fallback, circuit breaker, and retry logic
      */
     protected sendCommand(bleCommand: readonly number[] | number[] | Buffer, apiCommand: string, apiParameter?: any): Promise<CommandResult>;
     /**
@@ -90,6 +108,42 @@ export declare abstract class SwitchBotDevice extends EventEmitter {
      * Enable or disable fallback
      */
     setFallbackEnabled(enabled: boolean): void;
+    /**
+     * Enable or disable connection intelligence
+     */
+    setConnectionIntelligenceEnabled(enabled: boolean): void;
+    /**
+     * Enable or disable circuit breaker
+     */
+    setCircuitBreakerEnabled(enabled: boolean): void;
+    /**
+     * Enable or disable retry logic
+     */
+    setRetryEnabled(enabled: boolean): void;
+    /**
+     * Get connection tracker for this device
+     */
+    getConnectionTracker(): ConnectionTracker;
+    /**
+     * Get circuit breaker for BLE
+     */
+    getCircuitBreakerBLE(): CircuitBreaker;
+    /**
+     * Get circuit breaker for API
+     */
+    getCircuitBreakerAPI(): CircuitBreaker;
+    /**
+     * Register a custom fallback handler
+     */
+    registerFallbackHandler(handler: FallbackHandler, options?: FallbackHandlerOptions): string;
+    /**
+     * Unregister a fallback handler
+     */
+    unregisterFallbackHandler(id: string): boolean;
+    /**
+     * Get fallback handler manager
+     */
+    getFallbackHandlerManager(): FallbackHandlerManager;
 }
 /**
  * Device Manager for managing multiple devices

package/dist/devices/base.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/devices/base.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/devices/base.ts"],"names":[],"mappings":"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"}

package/dist/devices/base.js

@@ -5,10 +5,10 @@
 import { Buffer } from 'node:buffer';
 import { EventEmitter } from 'node:events';
 import { APINotAvailableError, BLENotAvailableError } from '../errors.js';
-import { Logger } from '../utils/index.js';
+import { CircuitBreaker, CircuitBreakerState, ConnectionTracker, FallbackHandlerManager, Logger, RetryExecutor, } from '../utils/index.js';
 /**
  * Base class for all SwitchBot devices
- * Provides hybrid BLE/API functionality with automatic fallback
+ * Provides hybrid BLE/API functionality with automatic fallback, circuit breaker, and connection intelligence
  */
 export class SwitchBotDevice extends EventEmitter {
     info;
@@ -17,6 +17,15 @@ export class SwitchBotDevice extends EventEmitter {
     apiClient;
     enableFallback;
     preferredConnection;
+    // Advanced features
+    connectionTracker;
+    circuitBreakerBLE;
+    circuitBreakerAPI;
+    fallbackHandlerManager;
+    retryExecutor;
+    enableConnectionIntelligence;
+    enableCircuitBreaker;
+    enableRetry;
     constructor(info, options = {}) {
         super();
         this.info = info;
@@ -25,6 +34,19 @@ export class SwitchBotDevice extends EventEmitter {
         this.apiClient = options.apiClient;
         this.enableFallback = options.enableFallback ?? true;
         this.preferredConnection = options.preferredConnection ?? 'ble';
+        // Initialize advanced features
+        this.enableConnectionIntelligence = options.enableConnectionIntelligence ?? true;
+        this.enableCircuitBreaker = options.enableCircuitBreaker ?? true;
+        this.enableRetry = options.enableRetry ?? true;
+        // Create connection tracker for this device
+        this.connectionTracker = new ConnectionTracker(info.id, options.logLevel);
+        // Create circuit breakers for each connection type
+        this.circuitBreakerBLE = new CircuitBreaker(`${info.deviceType}:${info.id}:BLE`, options.circuitBreakerConfig, options.logLevel);
+        this.circuitBreakerAPI = new CircuitBreaker(`${info.deviceType}:${info.id}:API`, options.circuitBreakerConfig, options.logLevel);
+        // Create retry executor
+        this.retryExecutor = new RetryExecutor(options.retryConfig, options.logLevel);
+        // Create fallback handler manager
+        this.fallbackHandlerManager = new FallbackHandlerManager(options.logLevel);
     }
     /**
      * Get device information
@@ -75,7 +97,7 @@ export class SwitchBotDevice extends EventEmitter {
         return this.info.connectionTypes.includes('api') && !!this.apiClient && this.info.cloudServiceEnabled !== false;
     }
     /**
-     * Send a command via BLE
+     * Send a command via BLE with circuit breaker and retry logic
      */
     async sendBLECommand(command) {
         if (!this.hasBLE()) {
@@ -85,18 +107,57 @@ export class SwitchBotDevice extends EventEmitter {
                 error: 'BLE not available for this device',
             };
         }
-        try {
+        // Check circuit breaker
+        if (this.enableCircuitBreaker && !this.circuitBreakerBLE.canExecute()) {
+            const state = this.circuitBreakerBLE.getState();
+            if (state === CircuitBreakerState.OPEN) {
+                return {
+                    success: false,
+                    connectionType: 'ble',
+                    error: 'BLE circuit breaker is OPEN (too many failures)',
+                };
+            }
+        }
+        const executeCommand = async () => {
             this.logger.debug('Sending BLE command', command);
             const buffer = Buffer.isBuffer(command) ? command : Buffer.from(command);
+            const startTime = Date.now();
             await this.bleConnection.write(this.info.mac, buffer);
+            const latencyMs = Date.now() - startTime;
+            // Record success
+            if (this.enableConnectionIntelligence) {
+                this.connectionTracker.recordSuccess('ble', latencyMs);
+            }
+            if (this.enableCircuitBreaker) {
+                this.circuitBreakerBLE.recordSuccess();
+            }
             this.info.activeConnection = 'ble';
             this.emit('command', { type: 'ble', success: true });
             return {
                 success: true,
                 connectionType: 'ble',
             };
+        };
+        try {
+            if (this.enableRetry) {
+                this.circuitBreakerBLE.markHalfOpenAttempt();
+                return await this.retryExecutor.executeOrThrow(executeCommand, `BLE command for ${this.info.id}`);
+            }
+            else {
+                if (this.enableCircuitBreaker) {
+                    this.circuitBreakerBLE.markHalfOpenAttempt();
+                }
+                return await executeCommand();
+            }
         }
         catch (error) {
+            // Record failure
+            if (this.enableConnectionIntelligence) {
+                this.connectionTracker.recordFailure('ble');
+            }
+            if (this.enableCircuitBreaker) {
+                this.circuitBreakerBLE.recordFailure();
+            }
             this.logger.error('BLE command failed', error);
             this.emit('error', { type: 'ble', error });
             return {
@@ -107,7 +168,7 @@ export class SwitchBotDevice extends EventEmitter {
         }
     }
     /**
-     * Send a command via OpenAPI
+     * Send a command via OpenAPI with circuit breaker and retry logic
      */
     async sendAPICommand(command, parameter) {
         if (!this.hasAPI()) {
@@ -117,9 +178,29 @@ export class SwitchBotDevice extends EventEmitter {
                 error: 'API not available for this device',
             };
         }
-        try {
+        // Check circuit breaker
+        if (this.enableCircuitBreaker && !this.circuitBreakerAPI.canExecute()) {
+            const state = this.circuitBreakerAPI.getState();
+            if (state === CircuitBreakerState.OPEN) {
+                return {
+                    success: false,
+                    connectionType: 'api',
+                    error: 'API circuit breaker is OPEN (too many failures)',
+                };
+            }
+        }
+        const executeCommand = async () => {
             this.logger.debug('Sending API command', { command, parameter });
+            const startTime = Date.now();
             const response = await this.apiClient.sendCommand(this.info.id, command, parameter);
+            const latencyMs = Date.now() - startTime;
+            // Record success
+            if (this.enableConnectionIntelligence) {
+                this.connectionTracker.recordSuccess('api', latencyMs);
+            }
+            if (this.enableCircuitBreaker) {
+                this.circuitBreakerAPI.recordSuccess();
+            }
             this.info.activeConnection = 'api';
             this.emit('command', { type: 'api', success: true });
             return {
@@ -127,8 +208,27 @@ export class SwitchBotDevice extends EventEmitter {
                 connectionType: 'api',
                 data: response,
             };
+        };
+        try {
+            if (this.enableRetry) {
+                this.circuitBreakerAPI.markHalfOpenAttempt();
+                return await this.retryExecutor.executeOrThrow(executeCommand, `API command for ${this.info.id}`);
+            }
+            else {
+                if (this.enableCircuitBreaker) {
+                    this.circuitBreakerAPI.markHalfOpenAttempt();
+                }
+                return await executeCommand();
+            }
         }
         catch (error) {
+            // Record failure
+            if (this.enableConnectionIntelligence) {
+                this.connectionTracker.recordFailure('api');
+            }
+            if (this.enableCircuitBreaker) {
+                this.circuitBreakerAPI.recordFailure();
+            }
             this.logger.error('API command failed', error);
             this.emit('error', { type: 'api', error });
             return {
@@ -139,37 +239,104 @@ export class SwitchBotDevice extends EventEmitter {
         }
     }
     /**
-     * Send a command with automatic BLE/API fallback
+     * Get best connection type based on intelligence tracking
+     */
+    getBestConnection() {
+        if (!this.enableConnectionIntelligence) {
+            return this.preferredConnection;
+        }
+        const availableTypes = [];
+        if (this.hasBLE()) {
+            availableTypes.push('ble');
+        }
+        if (this.hasAPI()) {
+            availableTypes.push('api');
+        }
+        if (availableTypes.length === 0) {
+            return this.preferredConnection;
+        }
+        // Get best connection based on statistics
+        const best = this.connectionTracker.getBestConnection(availableTypes);
+        if (best) {
+            return best;
+        }
+        return availableTypes.length > 0 ? availableTypes[0] : this.preferredConnection;
+    }
+    /**
+     * Send a command with automatic BLE/API fallback, circuit breaker, and retry logic
      */
     async sendCommand(bleCommand, apiCommand, apiParameter) {
-        // Try preferred connection first
-        if (this.preferredConnection === 'ble') {
-            const bleResult = await this.sendBLECommand(bleCommand);
-            if (bleResult.success) {
-                return bleResult;
+        // Determine connection strategy
+        let primaryConnection = this.preferredConnection;
+        let secondaryConnection;
+        if (this.enableConnectionIntelligence) {
+            primaryConnection = this.getBestConnection();
+            if (this.preferredConnection === 'ble' && primaryConnection === 'api' && this.hasBLE()) {
+                secondaryConnection = 'ble';
             }
-            // Fallback to API if enabled
-            if (this.enableFallback && this.hasAPI()) {
-                this.logger.warn('BLE failed, falling back to API');
-                const apiResult = await this.sendAPICommand(apiCommand, apiParameter);
-                return { ...apiResult, usedFallback: true };
+            else if (this.preferredConnection === 'api' && primaryConnection === 'ble' && this.hasAPI()) {
+                secondaryConnection = 'api';
             }
-            return bleResult;
         }
         else {
-            // Prefer API
-            const apiResult = await this.sendAPICommand(apiCommand, apiParameter);
-            if (apiResult.success) {
-                return apiResult;
+            // Fallback based on preferred connection
+            if (this.preferredConnection === 'ble' && this.hasBLE()) {
+                primaryConnection = 'ble';
+                if (this.enableFallback && this.hasAPI()) {
+                    secondaryConnection = 'api';
+                }
+            }
+            else if (this.preferredConnection === 'api' && this.hasAPI()) {
+                primaryConnection = 'api';
+                if (this.enableFallback && this.hasBLE()) {
+                    secondaryConnection = 'ble';
+                }
+            }
+            else if (this.hasBLE()) {
+                primaryConnection = 'ble';
+                if (this.enableFallback && this.hasAPI()) {
+                    secondaryConnection = 'api';
+                }
+            }
+            else {
+                primaryConnection = 'api';
+                secondaryConnection = undefined;
+            }
+        }
+        // Try primary connection
+        let result;
+        let fallbackUsed = false;
+        if (primaryConnection === 'ble') {
+            result = await this.sendBLECommand(bleCommand);
+        }
+        else {
+            result = await this.sendAPICommand(apiCommand, apiParameter);
+        }
+        // Try fallback if primary failed and fallback is enabled
+        if (!result.success && this.enableFallback && secondaryConnection) {
+            fallbackUsed = true;
+            this.logger.warn(`${primaryConnection} failed, attempting fallback to ${secondaryConnection}`);
+            // Emit fallback event
+            const fallbackEvent = {
+                deviceId: this.info.id,
+                primaryConnection,
+                fallbackConnection: secondaryConnection,
+                reason: result.error || 'Connection failed',
+                timestamp: new Date(),
+                totalTimeMs: 0,
+            };
+            await this.fallbackHandlerManager.emit(fallbackEvent);
+            if (secondaryConnection === 'ble') {
+                result = await this.sendBLECommand(bleCommand);
             }
-            // Fallback to BLE if enabled
-            if (this.enableFallback && this.hasBLE()) {
-                this.logger.warn('API failed, falling back to BLE');
-                const bleResult = await this.sendBLECommand(bleCommand);
-                return { ...bleResult, usedFallback: true };
+            else {
+                result = await this.sendAPICommand(apiCommand, apiParameter);
             }
-            return apiResult;
         }
+        if (fallbackUsed) {
+            result.usedFallback = true;
+        }
+        return result;
     }
     /**
      * Get device status via BLE
@@ -180,11 +347,25 @@ export class SwitchBotDevice extends EventEmitter {
         }
         try {
             this.logger.debug('Reading BLE status');
+            const startTime = Date.now();
             const data = await this.bleConnection.read(this.info.mac);
+            const latencyMs = Date.now() - startTime;
+            if (this.enableConnectionIntelligence) {
+                this.connectionTracker.recordSuccess('ble', latencyMs);
+            }
+            if (this.enableCircuitBreaker) {
+                this.circuitBreakerBLE.recordSuccess();
+            }
             this.info.activeConnection = 'ble';
             return data;
         }
         catch (error) {
+            if (this.enableConnectionIntelligence) {
+                this.connectionTracker.recordFailure('ble');
+            }
+            if (this.enableCircuitBreaker) {
+                this.circuitBreakerBLE.recordFailure();
+            }
             this.logger.error('Failed to read BLE status', error);
             throw error;
         }
@@ -198,11 +379,25 @@ export class SwitchBotDevice extends EventEmitter {
         }
         try {
             this.logger.debug('Reading API status');
+            const startTime = Date.now();
             const data = await this.apiClient.getStatus(this.info.id);
+            const latencyMs = Date.now() - startTime;
+            if (this.enableConnectionIntelligence) {
+                this.connectionTracker.recordSuccess('api', latencyMs);
+            }
+            if (this.enableCircuitBreaker) {
+                this.circuitBreakerAPI.recordSuccess();
+            }
             this.info.activeConnection = 'api';
             return data;
         }
         catch (error) {
+            if (this.enableConnectionIntelligence) {
+                this.connectionTracker.recordFailure('api');
+            }
+            if (this.enableCircuitBreaker) {
+                this.circuitBreakerAPI.recordFailure();
+            }
             this.logger.error('Failed to read API status', error);
             throw error;
         }
@@ -228,6 +423,63 @@ export class SwitchBotDevice extends EventEmitter {
         this.enableFallback = enabled;
         this.logger.info(`Fallback ${enabled ? 'enabled' : 'disabled'}`);
     }
+    /**
+     * Enable or disable connection intelligence
+     */
+    setConnectionIntelligenceEnabled(enabled) {
+        this.enableConnectionIntelligence = enabled;
+        this.logger.info(`Connection intelligence ${enabled ? 'enabled' : 'disabled'}`);
+    }
+    /**
+     * Enable or disable circuit breaker
+     */
+    setCircuitBreakerEnabled(enabled) {
+        this.enableCircuitBreaker = enabled;
+        this.logger.info(`Circuit breaker ${enabled ? 'enabled' : 'disabled'}`);
+    }
+    /**
+     * Enable or disable retry logic
+     */
+    setRetryEnabled(enabled) {
+        this.enableRetry = enabled;
+        this.logger.info(`Retry logic ${enabled ? 'enabled' : 'disabled'}`);
+    }
+    /**
+     * Get connection tracker for this device
+     */
+    getConnectionTracker() {
+        return this.connectionTracker;
+    }
+    /**
+     * Get circuit breaker for BLE
+     */
+    getCircuitBreakerBLE() {
+        return this.circuitBreakerBLE;
+    }
+    /**
+     * Get circuit breaker for API
+     */
+    getCircuitBreakerAPI() {
+        return this.circuitBreakerAPI;
+    }
+    /**
+     * Register a custom fallback handler
+     */
+    registerFallbackHandler(handler, options) {
+        return this.fallbackHandlerManager.register(handler, options);
+    }
+    /**
+     * Unregister a fallback handler
+     */
+    unregisterFallbackHandler(id) {
+        return this.fallbackHandlerManager.unregister(id);
+    }
+    /**
+     * Get fallback handler manager
+     */
+    getFallbackHandlerManager() {
+        return this.fallbackHandlerManager;
+    }
 }
 /**
  * Device Manager for managing multiple devices