meross-iot 0.1.0

package/lib/utilities/debug.js

@@ -0,0 +1,165 @@
+'use strict';
+
+const { MqttStatsCounter, HttpStatsCounter } = require('./stats');
+
+/**
+ * Debugging utilities for Meross manager development and troubleshooting.
+ *
+ * Provides access to internal debugging methods that expose implementation details
+ * useful for development and troubleshooting. These methods are not part of the
+ * stable public API and may change between versions.
+ *
+ * @module utilities/debug
+ */
+
+/**
+ * Creates debugging utilities for a MerossManager instance
+ *
+ * @param {MerossManager} manager - MerossManager instance
+ * @returns {Object} Debug utilities object
+ */
+function createDebugUtils(manager) {
+    return {
+        /**
+         * Gets the current error budget for a device.
+         *
+         * Error budgets prevent repeated failed communication attempts from consuming
+         * excessive resources. When the budget is exhausted, LAN HTTP communication is
+         * temporarily disabled for that device to avoid flooding the network with failed requests.
+         *
+         * @param {string} deviceUuid - Device UUID
+         * @returns {number} Current error budget (number of errors remaining)
+         */
+        getErrorBudget(deviceUuid) {
+            return manager._errorBudgetManager.getBudget(deviceUuid);
+        },
+
+        /**
+         * Resets the error budget for a device.
+         *
+         * Manually resets a device's error budget, immediately re-enabling LAN HTTP
+         * communication. Useful when a device's budget was exhausted due to temporary
+         * network issues that have since been resolved.
+         *
+         * @param {string} deviceUuid - Device UUID
+         */
+        resetErrorBudget(deviceUuid) {
+            manager._errorBudgetManager.resetBudget(deviceUuid);
+        },
+
+        /**
+         * Gets MQTT statistics for a given time window.
+         *
+         * Returns aggregated statistics about MQTT API calls if statistics tracking is enabled.
+         * Statistics include total calls, calls grouped by method/namespace combination, and
+         * calls grouped by device. Useful for monitoring API usage patterns and identifying
+         * potential bottlenecks.
+         *
+         * @param {number} [timeWindowMs=60000] - Time window in milliseconds (default: 1 minute)
+         * @returns {ApiStatsResult|null} Statistics result object or null if statistics not enabled
+         */
+        getMqttStats(timeWindowMs = 60000) {
+            if (!manager._mqttStatsCounter) {
+                return null;
+            }
+            return manager._mqttStatsCounter.getApiStats(timeWindowMs);
+        },
+
+        /**
+         * Gets HTTP statistics for a given time window.
+         *
+         * Returns aggregated statistics about HTTP API calls if statistics tracking is enabled.
+         * Statistics include total calls, calls grouped by HTTP status code, calls grouped by
+         * Meross API status code, and calls grouped by URL. Useful for monitoring API health
+         * and identifying error patterns.
+         *
+         * @param {number} [timeWindowMs=60000] - Time window in milliseconds (default: 1 minute)
+         * @returns {HttpStatsResult|null} Statistics result object or null if statistics not enabled
+         */
+        getHttpStats(timeWindowMs = 60000) {
+            if (!manager.httpClient || !manager.httpClient.stats) {
+                return null;
+            }
+            return manager.httpClient.stats.getStats(timeWindowMs);
+        },
+
+        /**
+         * Gets delayed MQTT statistics for a given time window.
+         *
+         * Returns statistics about MQTT API calls that were delayed (e.g., due to rate limiting
+         * or queue management) if statistics tracking is enabled. High numbers of delayed calls
+         * may indicate that request rates exceed device capabilities or queue capacity limits.
+         *
+         * @param {number} [timeWindowMs=60000] - Time window in milliseconds (default: 1 minute)
+         * @returns {ApiStatsResult|null} Statistics result object or null if statistics not enabled
+         */
+        getDelayedMqttStats(timeWindowMs = 60000) {
+            if (!manager._mqttStatsCounter) {
+                return null;
+            }
+            return manager._mqttStatsCounter.getDelayedApiStats(timeWindowMs);
+        },
+
+        /**
+         * Gets dropped MQTT statistics for a given time window.
+         *
+         * Returns statistics about MQTT API calls that were dropped (e.g., due to queue overflow
+         * or resource constraints) if statistics tracking is enabled. Dropped calls indicate that
+         * the system could not process all requests, potentially requiring queue size adjustments
+         * or reduced request rates.
+         *
+         * @param {number} [timeWindowMs=60000] - Time window in milliseconds (default: 1 minute)
+         * @returns {ApiStatsResult|null} Statistics result object or null if statistics not enabled
+         */
+        getDroppedMqttStats(timeWindowMs = 60000) {
+            if (!manager._mqttStatsCounter) {
+                return null;
+            }
+            return manager._mqttStatsCounter.getDroppedApiStats(timeWindowMs);
+        },
+
+        /**
+         * Enables statistics tracking for HTTP and MQTT requests.
+         *
+         * Initializes statistics collection for both HTTP and MQTT communication channels.
+         * Statistics are stored in memory with a configurable limit to prevent unbounded growth.
+         *
+         * @param {number} [maxStatsSamples=1000] - Maximum number of samples to keep in statistics
+         */
+        enableStats(maxStatsSamples = 1000) {
+            if (!manager._mqttStatsCounter) {
+                manager._mqttStatsCounter = new MqttStatsCounter(maxStatsSamples);
+            }
+            if (!manager.httpClient.stats) {
+                manager.httpClient._httpStatsCounter = new HttpStatsCounter(maxStatsSamples);
+            }
+        },
+
+        /**
+         * Disables statistics tracking for HTTP and MQTT requests.
+         *
+         * Stops collecting statistics and releases associated memory. Existing statistics
+         * are discarded when tracking is disabled.
+         */
+        disableStats() {
+            manager._mqttStatsCounter = null;
+            if (manager.httpClient) {
+                manager.httpClient._httpStatsCounter = null;
+            }
+        },
+
+        /**
+         * Checks if statistics tracking is enabled.
+         *
+         * @returns {boolean} True if statistics tracking is enabled, false otherwise
+         */
+        isStatsEnabled() {
+            return manager._mqttStatsCounter !== null && manager.httpClient && manager.httpClient.stats !== null;
+        }
+    };
+}
+
+module.exports = {
+    createDebugUtils
+};
+

package/lib/utilities/mqtt.js

@@ -0,0 +1,152 @@
+'use strict';
+
+const crypto = require('crypto');
+const { v4: uuidv4 } = require('uuid');
+
+/**
+ * Builds the MQTT topic where commands should be sent to specific devices.
+ *
+ * Meross devices subscribe to this topic pattern to receive commands. The topic structure
+ * follows the Meross protocol convention: /appliance/{deviceUuid}/subscribe
+ *
+ * @param {string} clientUuid - Device UUID
+ * @returns {string} MQTT topic string
+ * @example
+ * const topic = buildDeviceRequestTopic('device-uuid-123');
+ * // Returns: '/appliance/device-uuid-123/subscribe'
+ */
+function buildDeviceRequestTopic(clientUuid) {
+    return `/appliance/${clientUuid}/subscribe`;
+}
+
+/**
+ * Builds the MQTT topic where devices send acknowledgment responses to commands.
+ *
+ * The client application subscribes to this topic to receive responses from devices.
+ * The topic combines userId and appId to create a unique subscription channel per application instance.
+ *
+ * @param {string} userId - User ID
+ * @param {string} appId - Application ID
+ * @returns {string} MQTT topic string
+ * @example
+ * const topic = buildClientResponseTopic('user123', 'app456');
+ * // Returns: '/app/user123-app456/subscribe'
+ */
+function buildClientResponseTopic(userId, appId) {
+    return `/app/${userId}-${appId}/subscribe`;
+}
+
+/**
+ * Builds the MQTT topic where user push notifications are received.
+ *
+ * This topic is used for device-initiated push notifications (e.g., state changes, alerts)
+ * that are broadcast to all of a user's applications, as opposed to command responses
+ * which are sent to a specific app instance.
+ *
+ * @param {string} userId - User ID
+ * @returns {string} MQTT topic string
+ * @example
+ * const topic = buildClientUserTopic('user123');
+ * // Returns: '/app/user123/subscribe'
+ */
+function buildClientUserTopic(userId) {
+    return `/app/${userId}/subscribe`;
+}
+
+/**
+ * Extracts the device UUID from the "from" header of received messages.
+ *
+ * Meross MQTT messages include a "from" field containing the topic path. The device UUID
+ * is located at a fixed position in this path, allowing extraction without full topic parsing.
+ *
+ * @param {string} fromTopic - The "from" topic string from message header
+ * @returns {string} Device UUID
+ * @example
+ * const uuid = deviceUuidFromPushNotification('/appliance/device-uuid-123/subscribe');
+ * // Returns: 'device-uuid-123'
+ */
+function deviceUuidFromPushNotification(fromTopic) {
+    return fromTopic.split('/')[2];
+}
+
+/**
+ * Generates a new app ID and client ID for MQTT connection.
+ *
+ * Meross MQTT protocol requires unique identifiers for each application instance. This function
+ * generates a random UUID, hashes it with MD5 (as required by the protocol), and formats the
+ * client ID with the 'app:' prefix that Meross servers expect.
+ *
+ * @returns {Object} Object with appId and clientId properties
+ * @returns {string} returns.appId - Application ID (MD5 hash)
+ * @returns {string} returns.clientId - Client ID in format 'app:{appId}'
+ * @example
+ * const { appId, clientId } = generateClientAndAppId();
+ * // appId: 'a1b2c3d4e5f6...'
+ * // clientId: 'app:a1b2c3d4e5f6...'
+ */
+function generateClientAndAppId() {
+    const md5Hash = crypto.createHash('md5');
+    const rndUuid = uuidv4();
+    md5Hash.update(`API${rndUuid}`);
+    const appId = md5Hash.digest('hex');
+    const clientId = `app:${appId}`;
+    return { appId, clientId };
+}
+
+/**
+ * Generates the MQTT password for connecting to Meross MQTT servers.
+ *
+ * Meross requires passwords to be MD5 hashes of the concatenated userId and cloud key.
+ * This matches the authentication mechanism used by the official Meross mobile app.
+ *
+ * @param {string} userId - User ID
+ * @param {string} key - Meross cloud key
+ * @returns {string} MD5 hash of userId + key
+ * @example
+ * const password = generateMqttPassword('user123', 'secret-key');
+ * // Returns: 'a1b2c3d4e5f6...' (MD5 hash)
+ */
+function generateMqttPassword(userId, key) {
+    const md5Hash = crypto.createHash('md5');
+    const clearPwd = `${userId}${key}`;
+    md5Hash.update(clearPwd);
+    return md5Hash.digest('hex');
+}
+
+/**
+ * Verifies if a message header has a valid signature.
+ *
+ * Meross messages include signatures to prevent tampering. The signature is computed as
+ * MD5(messageId + key + timestamp) and must match the sign field in the header. Comparison
+ * is case-insensitive to handle variations in how signatures are encoded.
+ *
+ * @param {Object} header - Message header object
+ * @param {string} header.messageId - Message ID
+ * @param {string} header.sign - Signature to verify
+ * @param {number} header.timestamp - Timestamp
+ * @param {string} key - Meross cloud key
+ * @returns {boolean} True if signature is valid, false otherwise
+ * @example
+ * const isValid = verifyMessageSignature(
+ *     { messageId: 'abc123', sign: 'def456', timestamp: 1234567890 },
+ *     'secret-key'
+ * );
+ */
+function verifyMessageSignature(header, key) {
+    const messageHash = crypto.createHash('md5');
+    const strToHash = `${header.messageId}${key}${header.timestamp}`;
+    messageHash.update(strToHash);
+    const expectedSignature = messageHash.digest('hex').toLowerCase();
+    return expectedSignature === header.sign.toLowerCase();
+}
+
+module.exports = {
+    buildDeviceRequestTopic,
+    buildClientResponseTopic,
+    buildClientUserTopic,
+    deviceUuidFromPushNotification,
+    generateClientAndAppId,
+    generateMqttPassword,
+    verifyMessageSignature
+};
+

package/lib/utilities/network.js

@@ -0,0 +1,53 @@
+'use strict';
+
+/**
+ * Extracts the domain/hostname from an address string.
+ *
+ * Parses addresses that may include port numbers, returning only the hostname portion.
+ * Used when separating hostname and port information from Meross device addresses.
+ *
+ * @param {string} address - Address string in format "hostname:port" or just "hostname"
+ * @returns {string|null} Domain/hostname portion, or null if address is empty
+ * @example
+ * const host = extractDomain('iot.meross.com:2001'); // Returns 'iot.meross.com'
+ * const host2 = extractDomain('iot.meross.com'); // Returns 'iot.meross.com'
+ */
+function extractDomain(address) {
+    if (!address) {
+        return null;
+    }
+    const tokens = address.split(':');
+    return tokens[0];
+}
+
+/**
+ * Extracts the port from an address string.
+ *
+ * Parses addresses that may include port numbers, returning the port if present or
+ * falling back to the provided default. Handles invalid port values gracefully by
+ * returning the default rather than throwing errors.
+ *
+ * @param {string} address - Address string in format "hostname:port" or just "hostname"
+ * @param {number} defaultPort - Default port to return if no port is specified
+ * @returns {number} Port number
+ * @example
+ * const port = extractPort('iot.meross.com:2001', 2001); // Returns 2001
+ * const port2 = extractPort('iot.meross.com', 2001); // Returns 2001 (default)
+ */
+function extractPort(address, defaultPort) {
+    if (!address) {
+        return defaultPort;
+    }
+    const tokens = address.split(':');
+    if (tokens.length > 1) {
+        const port = parseInt(tokens[1], 10);
+        return isNaN(port) ? defaultPort : port;
+    }
+    return defaultPort;
+}
+
+module.exports = {
+    extractDomain,
+    extractPort
+};
+

package/lib/utilities/options.js

@@ -0,0 +1,64 @@
+'use strict';
+
+/**
+ * Options normalization utilities.
+ *
+ * Provides helper functions for normalizing and validating options objects used across
+ * feature methods. These utilities ensure consistent handling of optional parameters,
+ * default values, and required field validation.
+ *
+ * @module utilities/options
+ */
+
+/**
+ * Normalizes channel parameter from options object.
+ *
+ * Many Meross devices support multiple channels (e.g., multi-outlet power strips).
+ * This function extracts the channel number from options, defaulting to 0 (first channel)
+ * if not specified. Handles null or non-object inputs gracefully.
+ *
+ * @param {Object} options - Options object
+ * @param {number} [defaultChannel=0] - Default channel value if not specified
+ * @returns {number} Channel number
+ * @example
+ * normalizeChannel({channel: 1}); // Returns 1
+ * normalizeChannel({}); // Returns 0
+ * normalizeChannel({}, 1); // Returns 1
+ */
+function normalizeChannel(options = {}, defaultChannel = 0) {
+    if (options === null || typeof options !== 'object') {
+        return defaultChannel;
+    }
+    return options.channel !== undefined ? options.channel : defaultChannel;
+}
+
+/**
+ * Validates that required fields are present in options object.
+ *
+ * Ensures that all specified required fields exist in the options object before
+ * proceeding with operations that depend on them. Provides clear error messages
+ * listing all missing fields when validation fails.
+ *
+ * @param {Object} options - Options object to validate
+ * @param {Array<string>} requiredFields - Array of required field names
+ * @throws {Error} If any required field is missing
+ * @example
+ * validateRequired({onoff: true}, ['onoff']); // OK
+ * validateRequired({}, ['onoff']); // Throws error
+ */
+function validateRequired(options = {}, requiredFields = []) {
+    if (!options || typeof options !== 'object') {
+        throw new Error('Options must be an object');
+    }
+
+    const missing = requiredFields.filter(field => options[field] === undefined);
+    if (missing.length > 0) {
+        throw new Error(`Missing required fields: ${missing.join(', ')}`);
+    }
+}
+
+module.exports = {
+    normalizeChannel,
+    validateRequired
+};
+

package/lib/utilities/request-queue.js

@@ -0,0 +1,161 @@
+'use strict';
+
+/**
+ * Manages per-device request queues with batch processing and inter-batch delays.
+ *
+ * Meross devices enforce rate limits on API requests. This class throttles requests
+ * per device by processing them in configurable batches with delays between batches,
+ * preventing rate limit violations while maintaining reasonable throughput. Each device
+ * has an isolated queue to ensure fair resource allocation.
+ *
+ * @module utilities/request-queue
+ */
+class RequestQueue {
+    /**
+     * Creates a new RequestQueue instance.
+     *
+     * @param {Object} options - Configuration options
+     * @param {number} [options.batchSize=3] - Maximum concurrent requests per device per batch.
+     *     Higher values increase throughput but risk hitting rate limits.
+     * @param {number} [options.batchDelay=100] - Delay in milliseconds between batches.
+     *     Prevents overwhelming devices with rapid successive batches.
+     * @param {Function} [options.logger] - Optional logger function for debugging
+     */
+    constructor(options = {}) {
+        this.batchSize = options.batchSize || 3;
+        this.batchDelay = options.batchDelay || 100;
+        this.logger = options.logger;
+
+        this._queues = new Map();
+        this._processing = new Map();
+    }
+
+    /**
+     * Enqueues a request for asynchronous processing.
+     *
+     * Adds a request to the device's queue and returns a promise that resolves when
+     * the request completes. The queue handles throttling and ordering automatically,
+     * allowing callers to await results without managing rate limits directly.
+     *
+     * @param {string} deviceUuid - Device UUID
+     * @param {Function} requestFn - Function that returns a Promise
+     * @returns {Promise} Promise that resolves when the request completes
+     */
+    enqueue(deviceUuid, requestFn) {
+        return new Promise((resolve, reject) => {
+            const queueEntry = {
+                requestFn,
+                resolve,
+                reject
+            };
+
+            if (!this._queues.has(deviceUuid)) {
+                this._queues.set(deviceUuid, []);
+            }
+            const queue = this._queues.get(deviceUuid);
+            queue.push(queueEntry);
+
+            if (!this._processing.get(deviceUuid)) {
+                this._processQueue(deviceUuid);
+            }
+        });
+    }
+
+    /**
+     * Processes queued requests for a device in batches with delays.
+     *
+     * Uses a processing flag to prevent concurrent execution, ensuring only one
+     * batch processor runs per device at a time. This prevents race conditions
+     * and ensures requests are processed in order.
+     *
+     * @private
+     * @param {string} deviceUuid - Device UUID
+     */
+    async _processQueue(deviceUuid) {
+        this._processing.set(deviceUuid, true);
+
+        try {
+            const queue = this._queues.get(deviceUuid);
+            if (!queue || queue.length === 0) {
+                return;
+            }
+
+            while (queue.length > 0) {
+                const batch = queue.splice(0, this.batchSize);
+
+                await this._processBatch(deviceUuid, batch);
+
+                if (queue.length > 0) {
+                    await new Promise(resolve => setTimeout(resolve, this.batchDelay));
+                }
+            }
+        } finally {
+            this._processing.set(deviceUuid, false);
+
+            const queue = this._queues.get(deviceUuid);
+            if (!queue || queue.length === 0) {
+                this._queues.delete(deviceUuid);
+            }
+        }
+    }
+
+    /**
+     * Executes a batch of requests concurrently and forwards results to callers.
+     *
+     * Each request's promise is resolved or rejected individually, allowing partial
+     * success within a batch without affecting other requests. This ensures that
+     * one failed request doesn't prevent others in the same batch from completing.
+     *
+     * @private
+     * @param {string} deviceUuid - Device UUID
+     * @param {Array} batch - Array of queue entries
+     */
+    async _processBatch(deviceUuid, batch) {
+        const promises = batch.map(entry => {
+            return Promise.resolve(entry.requestFn())
+                .then(result => {
+                    entry.resolve(result);
+                    return { success: true, result };
+                })
+                .catch(error => {
+                    entry.reject(error);
+                    return { success: false, error };
+                });
+        });
+
+        await Promise.all(promises);
+    }
+
+    /**
+     * Clears all pending requests for a device and rejects their promises.
+     *
+     * Useful when a device disconnects or needs to be reset, preventing
+     * stale requests from executing after the device is no longer available.
+     *
+     * @param {string} deviceUuid - Device UUID
+     */
+    clearQueue(deviceUuid) {
+        const queue = this._queues.get(deviceUuid);
+        if (queue) {
+            queue.forEach(entry => {
+                entry.reject(new Error(`Queue cleared for device ${deviceUuid}`));
+            });
+            this._queues.delete(deviceUuid);
+        }
+        this._processing.delete(deviceUuid);
+    }
+
+    /**
+     * Returns the number of pending requests for a device.
+     *
+     * @param {string} deviceUuid - Device UUID
+     * @returns {number} Number of queued requests, or 0 if no queue exists
+     */
+    getQueueLength(deviceUuid) {
+        const queue = this._queues.get(deviceUuid);
+        return queue ? queue.length : 0;
+    }
+}
+
+module.exports = RequestQueue;
+

package/lib/utilities/ssid.js

@@ -0,0 +1,37 @@
+'use strict';
+
+/**
+ * Decodes a base64-encoded SSID string.
+ *
+ * Meross devices store WiFi SSIDs as base64-encoded strings in their configuration.
+ * This function decodes them to their original UTF-8 representation for display or
+ * comparison purposes. Returns the original string if decoding fails, allowing the
+ * function to handle both encoded and already-decoded SSIDs gracefully.
+ *
+ * @param {string} encodedSSID - Base64-encoded SSID string
+ * @returns {string} Decoded SSID string, or original string if decoding fails
+ * @example
+ * const decoded = decodeSSID('SG9tZQ=='); // Returns "Home"
+ * const decoded2 = decodeSSID('not-base64'); // Returns "not-base64" (not valid base64)
+ */
+function decodeSSID(encodedSSID) {
+    if (!encodedSSID || typeof encodedSSID !== 'string') {
+        return encodedSSID || '';
+    }
+
+    try {
+        const decoded = Buffer.from(encodedSSID, 'base64').toString('utf-8');
+        if (decoded && decoded.length > 0) {
+            return decoded;
+        }
+    } catch (error) {
+        // Decoding failed, return original string
+    }
+
+    return encodedSSID;
+}
+
+module.exports = {
+    decodeSSID
+};
+