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

package/dist/device.js

@@ -1,15 +1,52 @@
 import { Buffer } from 'node:buffer';
 import * as Crypto from 'node:crypto';
 import { EventEmitter } from 'node:events';
-import { parameterChecker } from './parameter-checker.js';
 import { CHAR_UUID_DEVICE, CHAR_UUID_NOTIFY, CHAR_UUID_WRITE, READ_TIMEOUT_MSEC, SERV_UUID_PRIMARY, WoSmartLockCommands, WoSmartLockProCommands, WRITE_TIMEOUT_MSEC } from './settings.js';
-const HUMIDIFIER_COMMAND_HEADER = '5701';
-const TURN_ON_KEY = `${HUMIDIFIER_COMMAND_HEADER}0101`;
-const TURN_OFF_KEY = `${HUMIDIFIER_COMMAND_HEADER}0102`;
-const INCREASE_KEY = `${HUMIDIFIER_COMMAND_HEADER}0103`;
-const DECREASE_KEY = `${HUMIDIFIER_COMMAND_HEADER}0104`;
-const SET_AUTO_MODE_KEY = `${HUMIDIFIER_COMMAND_HEADER}0105`;
-const SET_MANUAL_MODE_KEY = `${HUMIDIFIER_COMMAND_HEADER}0106`;
+/**
+ * Command constants for various SwitchBot devices.
+ * Using readonly arrays to ensure immutability and better type safety.
+ */
+const DEVICE_COMMANDS = {
+    BLIND_TILT: {
+        OPEN: [0x57, 0x0F, 0x45, 0x01, 0x05, 0xFF, 0x32],
+        CLOSE_UP: [0x57, 0x0F, 0x45, 0x01, 0x05, 0xFF, 0x64],
+        CLOSE_DOWN: [0x57, 0x0F, 0x45, 0x01, 0x05, 0xFF, 0x00],
+        PAUSE: [0x57, 0x0F, 0x45, 0x01, 0x00, 0xFF],
+    },
+    BULB: {
+        BASE: [0x57, 0x0F, 0x47, 0x01],
+        READ_STATE: [0x57, 0x0F, 0x48, 0x01],
+        TURN_ON: [0x01, 0x01],
+        TURN_OFF: [0x01, 0x02],
+        SET_BRIGHTNESS: [0x02, 0x14],
+        SET_COLOR_TEMP: [0x02, 0x17],
+        SET_RGB: [0x02, 0x12],
+    },
+    HUMIDIFIER: {
+        HEADER: '5701',
+        TURN_ON: '570101',
+        TURN_OFF: '570102',
+        INCREASE: '570103',
+        DECREASE: '570104',
+        SET_AUTO_MODE: '570105',
+        SET_MANUAL_MODE: '570106',
+    },
+    // Common commands used across multiple devices
+    COMMON: {
+        POWER_ON: [0x57, 0x01, 0x01],
+        POWER_OFF: [0x57, 0x01, 0x02],
+    },
+};
+// Legacy constants for backward compatibility
+const BLIND_TILT_COMMANDS = DEVICE_COMMANDS.BLIND_TILT;
+const BULB_COMMANDS = DEVICE_COMMANDS.BULB;
+const HUMIDIFIER_COMMAND_HEADER = DEVICE_COMMANDS.HUMIDIFIER.HEADER;
+const TURN_ON_KEY = DEVICE_COMMANDS.HUMIDIFIER.TURN_ON;
+const TURN_OFF_KEY = DEVICE_COMMANDS.HUMIDIFIER.TURN_OFF;
+const INCREASE_KEY = DEVICE_COMMANDS.HUMIDIFIER.INCREASE;
+const DECREASE_KEY = DEVICE_COMMANDS.HUMIDIFIER.DECREASE;
+const SET_AUTO_MODE_KEY = DEVICE_COMMANDS.HUMIDIFIER.SET_AUTO_MODE;
+const SET_MANUAL_MODE_KEY = DEVICE_COMMANDS.HUMIDIFIER.SET_MANUAL_MODE;
 export var SwitchBotModel;
 (function (SwitchBotModel) {
     SwitchBotModel["HubMini"] = "W0202200";
@@ -166,6 +203,176 @@ export var LogLevel;
     LogLevel["DEBUG"] = "debug";
     LogLevel["INFO"] = "info";
 })(LogLevel || (LogLevel = {}));
+/**
+ * Utility class for comprehensive input validation with improved error messages.
+ */
+export class ValidationUtils {
+    /**
+     * Validates percentage value (0-100).
+     * @param value - The value to validate
+     * @param paramName - The parameter name for error reporting
+     * @throws {RangeError} When value is not within valid range
+     * @throws {TypeError} When value is not a number
+     */
+    static validatePercentage(value, paramName = 'value') {
+        if (typeof value !== 'number' || Number.isNaN(value)) {
+            throw new TypeError(`${paramName} must be a valid number, got: ${value}`);
+        }
+        if (value < 0 || value > 100) {
+            throw new RangeError(`${paramName} must be between 0 and 100 inclusive, got: ${value}`);
+        }
+    }
+    /**
+     * Validates RGB color value (0-255).
+     * @param value - The color value to validate
+     * @param colorName - The color name for error reporting
+     * @throws {RangeError} When value is not within valid range
+     * @throws {TypeError} When value is not a number
+     */
+    static validateRGB(value, colorName = 'color') {
+        if (typeof value !== 'number' || Number.isNaN(value)) {
+            throw new TypeError(`${colorName} must be a valid number, got: ${value}`);
+        }
+        if (!Number.isInteger(value) || value < 0 || value > 255) {
+            throw new RangeError(`${colorName} must be an integer between 0 and 255 inclusive, got: ${value}`);
+        }
+    }
+    /**
+     * Validates buffer and throws descriptive error.
+     * @param buffer - The buffer to validate
+     * @param expectedLength - Optional expected length
+     * @param paramName - The parameter name for error reporting
+     * @throws {TypeError} When buffer is not a Buffer
+     * @throws {RangeError} When buffer length doesn't match expected
+     */
+    static validateBuffer(buffer, expectedLength, paramName = 'buffer') {
+        if (!Buffer.isBuffer(buffer)) {
+            throw new TypeError(`${paramName} must be a Buffer instance, got: ${typeof buffer}`);
+        }
+        if (expectedLength !== undefined && buffer.length !== expectedLength) {
+            throw new RangeError(`${paramName} must have exactly ${expectedLength} bytes, got: ${buffer.length} bytes`);
+        }
+    }
+    /**
+     * Validates string input with comprehensive checks.
+     * @param value - The value to validate
+     * @param paramName - The parameter name for error reporting
+     * @param minLength - Minimum required length
+     * @param maxLength - Optional maximum length
+     * @throws {TypeError} When value is not a string
+     * @throws {RangeError} When string length is invalid
+     */
+    static validateString(value, paramName = 'value', minLength = 1, maxLength) {
+        if (typeof value !== 'string') {
+            throw new TypeError(`${paramName} must be a string, got: ${typeof value}`);
+        }
+        if (value.length < minLength) {
+            throw new RangeError(`${paramName} must have at least ${minLength} character(s), got: ${value.length}`);
+        }
+        if (maxLength !== undefined && value.length > maxLength) {
+            throw new RangeError(`${paramName} must have at most ${maxLength} character(s), got: ${value.length}`);
+        }
+    }
+    /**
+     * Validates numeric range with enhanced checks.
+     * @param value - The value to validate
+     * @param min - Minimum allowed value
+     * @param max - Maximum allowed value
+     * @param paramName - The parameter name for error reporting
+     * @param mustBeInteger - Whether the value must be an integer
+     * @throws {TypeError} When value is not a number
+     * @throws {RangeError} When value is outside valid range
+     */
+    static validateRange(value, min, max, paramName = 'value', mustBeInteger = false) {
+        if (typeof value !== 'number' || Number.isNaN(value)) {
+            throw new TypeError(`${paramName} must be a valid number, got: ${value}`);
+        }
+        if (mustBeInteger && !Number.isInteger(value)) {
+            throw new TypeError(`${paramName} must be an integer, got: ${value}`);
+        }
+        if (value < min || value > max) {
+            throw new RangeError(`${paramName} must be between ${min} and ${max} inclusive, got: ${value}`);
+        }
+    }
+    /**
+     * Validates MAC address format.
+     * @param address - The MAC address to validate
+     * @param paramName - The parameter name for error reporting
+     * @throws {TypeError} When address is not a string
+     * @throws {Error} When address format is invalid
+     */
+    static validateMacAddress(address, paramName = 'address') {
+        if (typeof address !== 'string') {
+            throw new TypeError(`${paramName} must be a string`);
+        }
+        const macRegex = /^(?:[0-9A-F]{2}[:-]){5}[0-9A-F]{2}$|^[0-9A-F]{12}$/i;
+        if (!macRegex.test(address)) {
+            throw new Error(`${paramName} must be a valid MAC address format, got: ${address}`);
+        }
+    }
+    /**
+     * Validates that a value is one of the allowed enum values.
+     * @param value - The value to validate
+     * @param allowedValues - Array of allowed values
+     * @param paramName - The parameter name for error reporting
+     * @throws {Error} When value is not in allowed values
+     */
+    static validateEnum(value, allowedValues, paramName = 'value') {
+        if (!allowedValues.includes(value)) {
+            throw new Error(`${paramName} must be one of: ${allowedValues.join(', ')}, got: ${value}`);
+        }
+    }
+}
+/**
+ * Enhanced error handling utilities.
+ */
+export class ErrorUtils {
+    /**
+     * Creates a timeout error with context.
+     * @param operation - The operation that timed out
+     * @param timeoutMs - The timeout duration in milliseconds
+     * @returns A descriptive timeout error
+     */
+    static createTimeoutError(operation, timeoutMs) {
+        return new Error(`Operation '${operation}' timed out after ${timeoutMs}ms`);
+    }
+    /**
+     * Creates a connection error with context.
+     * @param deviceId - The device ID that failed to connect
+     * @param cause - The underlying cause of the connection failure
+     * @returns A descriptive connection error
+     */
+    static createConnectionError(deviceId, cause) {
+        const message = `Failed to connect to device ${deviceId}`;
+        return cause ? new Error(`${message}: ${cause.message}`) : new Error(message);
+    }
+    /**
+     * Creates a command error with context.
+     * @param command - The command that failed
+     * @param deviceId - The device ID
+     * @param cause - The underlying cause
+     * @returns A descriptive command error
+     */
+    static createCommandError(command, deviceId, cause) {
+        const message = `Command '${command}' failed for device ${deviceId}`;
+        return cause ? new Error(`${message}: ${cause.message}`) : new Error(message);
+    }
+    /**
+     * Wraps an async operation with timeout and enhanced error handling.
+     * @param operation - The async operation to wrap
+     * @param timeoutMs - Timeout in milliseconds
+     * @param operationName - Name of the operation for error messages
+     * @returns Promise that resolves with the operation result or rejects with timeout
+     */
+    static async withTimeout(operation, timeoutMs, operationName) {
+        const timeoutPromise = new Promise((_, reject) => {
+            setTimeout(() => {
+                reject(this.createTimeoutError(operationName, timeoutMs));
+            }, timeoutMs);
+        });
+        return Promise.race([operation, timeoutPromise]);
+    }
+}
 /**
  * Represents a Switchbot Device.
  */
@@ -345,8 +552,9 @@ export class SwitchbotDevice extends EventEmitter {
      * @param service The service to discover characteristics for.
      * @returns A Promise that resolves with the list of characteristics.
      */
-    async discoverCharacteristics(service) {
-        return await service.discoverCharacteristicsAsync([]);
+    // Discover characteristics without extra async/await
+    discoverCharacteristics(service) {
+        return service.discoverCharacteristicsAsync([]);
     }
     /**
      * Subscribes to the notify characteristic.
@@ -404,12 +612,20 @@ export class SwitchbotDevice extends EventEmitter {
      */
     async getDeviceName() {
         await this.internalConnect();
-        if (!this.characteristics?.device) {
-            throw new Error(`The device does not support the characteristic UUID 0x${CHAR_UUID_DEVICE}.`);
+        try {
+            if (!this.characteristics?.device) {
+                throw new Error(`Characteristic ${CHAR_UUID_DEVICE} not supported`);
+            }
+            const buf = await this.readCharacteristic(this.characteristics.device);
+            return buf.toString('utf8');
+        }
+        catch (error) {
+            const deviceContext = `device ${this.deviceId || 'unknown'}`;
+            throw ErrorUtils.createCommandError('getDeviceName', deviceContext, error);
+        }
+        finally {
+            await this.internalDisconnect();
         }
-        const buf = await this.readCharacteristic(this.characteristics.device);
-        await this.internalDisconnect();
-        return buf.toString('utf8');
     }
     /**
      * Sets the device name.
@@ -417,17 +633,26 @@ export class SwitchbotDevice extends EventEmitter {
      * @returns A Promise that resolves when the name is set.
      */
     async setDeviceName(name) {
-        const valid = parameterChecker.check({ name }, { name: { required: true, type: 'string', minBytes: 1, maxBytes: 100 } }, true);
-        if (!valid) {
-            throw new Error(parameterChecker.error.message);
+        ValidationUtils.validateString(name, 'name', 1);
+        // Additional validation for device name length
+        const nameBuffer = Buffer.from(name, 'utf8');
+        if (nameBuffer.length > 100) {
+            throw new RangeError('Device name cannot exceed 100 bytes when encoded as UTF-8');
         }
-        const buf = Buffer.from(name, 'utf8');
         await this.internalConnect();
-        if (!this.characteristics?.device) {
-            throw new Error(`The device does not support the characteristic UUID 0x${CHAR_UUID_DEVICE}.`);
+        try {
+            if (!this.characteristics?.device) {
+                throw new Error(`Characteristic ${CHAR_UUID_DEVICE} not supported`);
+            }
+            await this.writeCharacteristic(this.characteristics.device, nameBuffer);
+        }
+        catch (error) {
+            const deviceContext = `device ${this.deviceId || 'unknown'}`;
+            throw ErrorUtils.createCommandError('setDeviceName', deviceContext, error);
+        }
+        finally {
+            await this.internalDisconnect();
         }
-        await this.writeCharacteristic(this.characteristics.device, buf);
-        await this.internalDisconnect();
     }
     /**
      * Sends a command to the device and awaits a response.
@@ -435,17 +660,24 @@ export class SwitchbotDevice extends EventEmitter {
      * @returns A Promise that resolves with the response buffer.
      */
     async command(reqBuf) {
-        if (!Buffer.isBuffer(reqBuf)) {
-            throw new TypeError('The specified data is not acceptable for writing.');
-        }
+        ValidationUtils.validateBuffer(reqBuf, undefined, 'reqBuf');
         await this.internalConnect();
         if (!this.characteristics?.write) {
-            throw new Error('No characteristics available.');
+            throw new Error('No write characteristic available for command execution');
+        }
+        try {
+            await this.writeCharacteristic(this.characteristics.write, reqBuf);
+            const resBuf = await this.waitForCommandResponse();
+            return resBuf;
+        }
+        catch (error) {
+            const deviceContext = `device ${this.deviceId || 'unknown'}`;
+            // Use ErrorUtils for enriched error context
+            throw ErrorUtils.createCommandError('execute command', deviceContext, error);
+        }
+        finally {
+            await this.internalDisconnect();
         }
-        await this.writeCharacteristic(this.characteristics.write, reqBuf);
-        const resBuf = await this.waitForCommandResponse();
-        await this.internalDisconnect();
-        return resBuf;
     }
     /**
      * Waits for a response from the device after sending a command.
@@ -468,41 +700,33 @@ export class SwitchbotDevice extends EventEmitter {
         return await Promise.race([readPromise, timeoutPromise]);
     }
     /**
-     * Reads data from a characteristic with a timeout.
+     * Reads data from a characteristic with enhanced timeout and error handling.
      * @param char The characteristic to read from.
      * @returns A Promise that resolves with the data buffer.
      */
     async readCharacteristic(char) {
-        const timer = setTimeout(() => {
-            throw new Error('READ_TIMEOUT');
-        }, READ_TIMEOUT_MSEC);
         try {
-            const result = await char.readAsync();
-            clearTimeout(timer);
-            return result;
+            return await ErrorUtils.withTimeout(char.readAsync(), READ_TIMEOUT_MSEC, `read characteristic ${char.uuid}`);
         }
         catch (error) {
-            clearTimeout(timer);
-            throw error;
+            const deviceContext = `device ${this.deviceId || 'unknown'}`;
+            throw ErrorUtils.createCommandError(`read characteristic ${char.uuid}`, deviceContext, error);
         }
     }
     /**
-     * Writes data to a characteristic with a timeout.
+     * Writes data to a characteristic with enhanced timeout and error handling.
      * @param char The characteristic to write to.
      * @param buf The data buffer.
      * @returns A Promise that resolves when the write is complete.
      */
     async writeCharacteristic(char, buf) {
-        const timer = setTimeout(() => {
-            throw new Error('WRITE_TIMEOUT');
-        }, WRITE_TIMEOUT_MSEC);
+        ValidationUtils.validateBuffer(buf, undefined, 'write buffer');
         try {
-            await char.writeAsync(buf, false);
-            clearTimeout(timer);
+            return await ErrorUtils.withTimeout(char.writeAsync(buf, false), WRITE_TIMEOUT_MSEC, `write to characteristic ${char.uuid}`);
         }
         catch (error) {
-            clearTimeout(timer);
-            throw error;
+            const deviceContext = `device ${this.deviceId || 'unknown'}`;
+            throw ErrorUtils.createCommandError(`write to characteristic ${char.uuid}`, deviceContext, error);
         }
     }
 }
@@ -556,10 +780,11 @@ export class Advertising {
      * Validates if the buffer is a valid Buffer object with a minimum length.
      *
      * @param {any} buffer - The buffer to validate.
+     * @param {number} minLength - The minimum required length.
      * @returns {boolean} - True if the buffer is valid, false otherwise.
      */
-    static validateBuffer(buffer) {
-        return buffer && Buffer.isBuffer(buffer) && buffer.length >= 3;
+    static validateBuffer(buffer, minLength = 3) {
+        return buffer && Buffer.isBuffer(buffer) && buffer.length >= minLength;
     }
     /**
      * Parses the service data based on the device model.
@@ -696,21 +921,21 @@ export class WoBlindTilt extends SwitchbotDevice {
      * @returns {Promise<void>}
      */
     async open() {
-        await this.operateBlindTilt([0x57, 0x0F, 0x45, 0x01, 0x05, 0xFF, 0x32]);
+        await this.operateBlindTilt([...BLIND_TILT_COMMANDS.OPEN]);
     }
     /**
      * Closes the blind tilt up to the nearest endpoint.
      * @returns {Promise<void>}
      */
     async closeUp() {
-        await this.operateBlindTilt([0x57, 0x0F, 0x45, 0x01, 0x05, 0xFF, 0x64]);
+        await this.operateBlindTilt([...BLIND_TILT_COMMANDS.CLOSE_UP]);
     }
     /**
      * Closes the blind tilt down to the nearest endpoint.
      * @returns {Promise<void>}
      */
     async closeDown() {
-        await this.operateBlindTilt([0x57, 0x0F, 0x45, 0x01, 0x05, 0xFF, 0x00]);
+        await this.operateBlindTilt([...BLIND_TILT_COMMANDS.CLOSE_DOWN]);
     }
     /**
      * Closes the blind tilt to the nearest endpoint.
@@ -794,7 +1019,7 @@ export class WoBlindTilt extends SwitchbotDevice {
      * @returns {Promise<void>}
      */
     async pause() {
-        await this.operateBlindTilt([0x57, 0x0F, 0x45, 0x01, 0x00, 0xFF]);
+        await this.operateBlindTilt([...BLIND_TILT_COMMANDS.PAUSE]);
     }
     /**
      * Runs the blind tilt to the specified position.
@@ -803,13 +1028,10 @@ export class WoBlindTilt extends SwitchbotDevice {
      * @returns {Promise<void>}
      */
     async runToPos(percent, mode) {
-        if (typeof percent !== 'number' || percent < 0 || percent > 100) {
-            throw new RangeError('Percent must be a number between 0 and 100');
-        }
-        if (typeof mode !== 'number' || mode < 0 || mode > 1) {
-            throw new RangeError('Mode must be a number between 0 and 1');
-        }
-        await this.operateBlindTilt([0x57, 0x0F, 0x45, 0x01, 0x05, mode, percent]);
+        ValidationUtils.validatePercentage(percent, 'percent');
+        ValidationUtils.validateRange(mode, 0, 1, 'mode', true);
+        const adjustedPercent = this.reverse ? 100 - percent : percent;
+        await this.operateBlindTilt([0x57, 0x0F, 0x45, 0x01, 0x05, mode, adjustedPercent]);
     }
     /**
      * Sends a command to operate the blind tilt and handles the response.
@@ -876,7 +1098,7 @@ export class WoBulb extends SwitchbotDevice {
      * @returns {Promise<boolean>} - Resolves with a boolean indicating whether the bulb is ON (true) or OFF (false).
      */
     async readState() {
-        return this.operateBulb([0x57, 0x0F, 0x48, 0x01]);
+        return this.operateBulb([...BULB_COMMANDS.READ_STATE]);
     }
     /**
      * Sets the state of the bulb.
@@ -885,22 +1107,21 @@ export class WoBulb extends SwitchbotDevice {
      * @private
      */
     async setState(reqByteArray) {
-        const base = [0x57, 0x0F, 0x47, 0x01];
-        return this.operateBulb(base.concat(reqByteArray));
+        return this.operateBulb([...BULB_COMMANDS.BASE, ...reqByteArray]);
     }
     /**
      * Turns on the bulb.
      * @returns {Promise<boolean>} - Resolves with a boolean indicating whether the bulb is ON (true).
      */
     async turnOn() {
-        return this.setState([0x01, 0x01]);
+        return this.setState([...BULB_COMMANDS.TURN_ON]);
     }
     /**
      * Turns off the bulb.
      * @returns {Promise<boolean>} - Resolves with a boolean indicating whether the bulb is OFF (false).
      */
     async turnOff() {
-        return this.setState([0x01, 0x02]);
+        return this.setState([...BULB_COMMANDS.TURN_OFF]);
     }
     /**
      * Sets the brightness of the bulb.
@@ -908,10 +1129,8 @@ export class WoBulb extends SwitchbotDevice {
      * @returns {Promise<boolean>} - Resolves with a boolean indicating whether the operation was successful.
      */
     async setBrightness(brightness) {
-        if (brightness < 0 || brightness > 100) {
-            throw new RangeError('Brightness must be between 0 and 100');
-        }
-        return this.setState([0x02, 0x14, brightness]);
+        ValidationUtils.validatePercentage(brightness, 'brightness');
+        return this.setState([...BULB_COMMANDS.SET_BRIGHTNESS, brightness]);
     }
     /**
      * Sets the color temperature of the bulb.
@@ -919,10 +1138,8 @@ export class WoBulb extends SwitchbotDevice {
      * @returns {Promise<boolean>} - Resolves with a boolean indicating whether the operation was successful.
      */
     async setColorTemperature(color_temperature) {
-        if (color_temperature < 0 || color_temperature > 100) {
-            throw new RangeError('Color temperature must be between 0 and 100');
-        }
-        return this.setState([0x02, 0x17, color_temperature]);
+        ValidationUtils.validatePercentage(color_temperature, 'color_temperature');
+        return this.setState([...BULB_COMMANDS.SET_COLOR_TEMP, color_temperature]);
     }
     /**
      * Sets the RGB color of the bulb.
@@ -933,10 +1150,11 @@ export class WoBulb extends SwitchbotDevice {
      * @returns {Promise<boolean>} - Resolves with a boolean indicating whether the operation was successful.
      */
     async setRGB(brightness, red, green, blue) {
-        if (brightness < 0 || brightness > 100 || red < 0 || red > 255 || green < 0 || green > 255 || blue < 0 || blue > 255) {
-            throw new RangeError('Invalid RGB or brightness values');
-        }
-        return this.setState([0x02, 0x12, brightness, red, green, blue]);
+        ValidationUtils.validatePercentage(brightness, 'brightness');
+        ValidationUtils.validateRGB(red, 'red');
+        ValidationUtils.validateRGB(green, 'green');
+        ValidationUtils.validateRGB(blue, 'blue');
+        return this.setState([...BULB_COMMANDS.SET_RGB, brightness, red, green, blue]);
     }
     /**
      * Sends a command to the bulb.
@@ -2750,6 +2968,7 @@ export class WoStrip extends SwitchbotDevice {
             red: byte3,
             green: byte4,
             blue: byte5,
+            color_temperature: 0, // Add a default value or extract from serviceData if available
             delay: byte8 & 0b10000000,
             preset: byte8 & 0b00001000,
             color_mode: byte8 & 0b00000111,