meross-iot 0.1.0

package/lib/model/http/exception.js

@@ -0,0 +1,151 @@
+'use strict';
+
+const { MerossError, AuthenticationError } = require('../exception');
+
+/**
+ * Base class for HTTP API errors
+ *
+ * Extends MerossError with HTTP status code information to distinguish between
+ * different types of HTTP failures (client errors, server errors, etc.).
+ *
+ * @class
+ * @extends MerossError
+ * @property {number|null} httpStatusCode - HTTP status code (e.g., 400, 500)
+ */
+class HttpApiError extends MerossError {
+    constructor(message, errorCode = null, httpStatusCode = null) {
+        super(message || 'HTTP API error occurred', errorCode);
+        this.httpStatusCode = httpStatusCode;
+    }
+}
+
+/**
+ * Unauthorized access error (HTTP 401 or similar)
+ *
+ * Thrown when an API request is made without proper authentication or with invalid
+ * credentials. Typically indicates token expiration or an invalid token that
+ * cannot be used for authorization.
+ *
+ * @class
+ * @extends HttpApiError
+ * @property {number} httpStatusCode - HTTP status code (typically 401)
+ */
+class UnauthorizedError extends HttpApiError {
+    constructor(message, errorCode = null, httpStatusCode = 401) {
+        super(message || 'Unauthorized access', errorCode, httpStatusCode);
+    }
+}
+
+/**
+ * Bad domain / region redirect error (error code 1030)
+ *
+ * Thrown when Meross API redirects to a different regional domain. This occurs
+ * when the account is registered in a different region than the one being used
+ * for API requests. The error response includes the correct regional endpoints
+ * that should be used for subsequent requests.
+ *
+ * @class
+ * @extends MerossError
+ * @property {number} errorCode - Always 1030
+ * @property {string|null} apiDomain - The correct API domain for this account
+ * @property {string|null} mqttDomain - The correct MQTT domain for this account
+ */
+class BadDomainError extends MerossError {
+    constructor(message, apiDomain = null, mqttDomain = null) {
+        super(message || 'Redirect app to login other than this region', 1030);
+        this.apiDomain = apiDomain;
+        this.mqttDomain = mqttDomain;
+    }
+}
+
+/**
+ * Token expired or invalid errors (error codes 1019, 1022, 1200)
+ *
+ * Thrown when the authentication token has expired or is invalid. Tokens
+ * expire after a period of inactivity or when explicitly invalidated by the
+ * authentication service.
+ *
+ * @class
+ * @extends MerossError
+ * @property {number} errorCode - API error code (1019, 1022, or 1200)
+ */
+class TokenExpiredError extends MerossError {
+    constructor(message, errorCode) {
+        super(message || 'Token has expired or is invalid', errorCode);
+    }
+}
+
+/**
+ * Too many tokens error (error code 1301)
+ *
+ * Thrown when too many authentication tokens have been issued without logging out.
+ * Meross enforces a limit on concurrent sessions per account, and exceeding this
+ * limit results in account-level restrictions until tokens are revoked.
+ *
+ * @class
+ * @extends MerossError
+ * @property {number} errorCode - Always 1301
+ */
+class TooManyTokensError extends MerossError {
+    constructor(message) {
+        super(message || 'You have issued too many tokens without logging out and your account might have been temporarily disabled.', 1301);
+    }
+}
+
+/**
+ * MFA code required error (error code 1033)
+ *
+ * Thrown when MFA (Multi-Factor Authentication) is enabled for the account but
+ * no MFA code was provided during login. The login process requires an additional
+ * authentication step that was not completed.
+ *
+ * @class
+ * @extends AuthenticationError
+ * @property {number} errorCode - Always 1033
+ */
+class MFARequiredError extends AuthenticationError {
+    constructor(message) {
+        super(message || 'MFA is activated for the account but MFA code not provided. Please provide a current MFA code.', 1033);
+    }
+}
+
+/**
+ * Alias for MFARequiredError
+ *
+ * Provided for backward compatibility and clearer naming in contexts where
+ * the error represents a missing MFA code rather than a general MFA requirement.
+ *
+ * @class
+ * @extends MFARequiredError
+ */
+class MissingMFAError extends MFARequiredError {
+}
+
+/**
+ * Wrong MFA code error (error code 1032)
+ *
+ * Thrown when an invalid or expired MFA code is provided during login.
+ * The code provided does not match the current valid code from the
+ * authenticator application.
+ *
+ * @class
+ * @extends AuthenticationError
+ * @property {number} errorCode - Always 1032
+ */
+class WrongMFAError extends AuthenticationError {
+    constructor(message) {
+        super(message || 'Invalid MFA code. Please use a current MFA code.', 1032);
+    }
+}
+
+module.exports = {
+    HttpApiError,
+    UnauthorizedError,
+    BadDomainError,
+    TokenExpiredError,
+    TooManyTokensError,
+    MFARequiredError,
+    MissingMFAError,
+    WrongMFAError
+};
+

package/lib/model/http/subdevice.js

@@ -0,0 +1,133 @@
+'use strict';
+
+/**
+ * Represents subdevice information from the HTTP API
+ *
+ * This class encapsulates subdevice metadata retrieved from the Meross HTTP API,
+ * including subdevice identification, type, vendor, and icon information.
+ *
+ * @class
+ * @example
+ * // Use fromDict() to create instances
+ * const subdeviceInfo = HttpSubdeviceInfo.fromDict({
+ *     sub_device_id: '12345',
+ *     true_id: '67890',
+ *     sub_device_type: 'ms130',
+ *     sub_device_vendor: 'meross',
+ *     sub_device_name: 'Temperature Sensor',
+ *     sub_device_icon_id: 'icon123'
+ * });
+ */
+class HttpSubdeviceInfo {
+    /**
+     * Creates an HttpSubdeviceInfo instance from a dictionary object.
+     * Normalizes incoming keys (handles camelCase, snake_case, and generic keys) to camelCase.
+     * This is the only way to create instances.
+     *
+     * @static
+     * @param {Object} jsonDict - Raw API response object with any key format
+     * @param {string} [jsonDict.subDeviceId] - Subdevice ID (camelCase)
+     * @param {string} [jsonDict.sub_device_id] - Subdevice ID (snake_case)
+     * @param {string} [jsonDict.id] - Generic ID key (mapped to subDeviceId)
+     * @param {string} [jsonDict.trueId] - True ID (camelCase)
+     * @param {string} [jsonDict.true_id] - True ID (snake_case)
+     * @param {string} [jsonDict.subDeviceType] - Subdevice type (camelCase)
+     * @param {string} [jsonDict.sub_device_type] - Subdevice type (snake_case)
+     * @param {string} [jsonDict.type] - Generic type key (mapped to subDeviceType)
+     * @param {string} [jsonDict.subDeviceVendor] - Subdevice vendor (camelCase)
+     * @param {string} [jsonDict.sub_device_vendor] - Subdevice vendor (snake_case)
+     * @param {string} [jsonDict.subDeviceName] - Subdevice name (camelCase)
+     * @param {string} [jsonDict.sub_device_name] - Subdevice name (snake_case)
+     * @param {string} [jsonDict.name] - Generic name key (mapped to subDeviceName)
+     * @param {string} [jsonDict.subDeviceIconId] - Subdevice icon ID (camelCase)
+     * @param {string} [jsonDict.sub_device_icon_id] - Subdevice icon ID (snake_case)
+     * @returns {HttpSubdeviceInfo} New HttpSubdeviceInfo instance
+     */
+    static fromDict(jsonDict) {
+        if (!jsonDict || typeof jsonDict !== 'object') {
+            throw new Error('Subdevice info dictionary is required');
+        }
+
+        // The Meross API returns properties in inconsistent formats (camelCase, snake_case, or generic keys).
+        // This mapping allows us to accept any format and normalize to camelCase for internal use.
+        // Generic keys like 'id', 'type', and 'name' are included as fallbacks for API variations.
+        const propertyMappings = {
+            subDeviceId: ['subDeviceId', 'sub_device_id', 'id'],
+            trueId: ['trueId', 'true_id'],
+            subDeviceType: ['subDeviceType', 'sub_device_type', 'type'],
+            subDeviceVendor: ['subDeviceVendor', 'sub_device_vendor'],
+            subDeviceName: ['subDeviceName', 'sub_device_name', 'name'],
+            subDeviceIconId: ['subDeviceIconId', 'sub_device_icon_id']
+        };
+
+        // Normalize properties by checking alternatives in priority order (camelCase, snake_case, then generic).
+        // This ensures consistent property names regardless of API response format.
+        const normalized = {};
+        for (const [camelKey, alternatives] of Object.entries(propertyMappings)) {
+            for (const key of alternatives) {
+                if (jsonDict[key] !== null && jsonDict[key] !== undefined) {
+                    normalized[camelKey] = jsonDict[key];
+                    break;
+                }
+            }
+        }
+
+        // Use Object.create() instead of a constructor to allow static factory pattern.
+        // This prevents accidental instantiation via 'new' and enforces use of fromDict().
+        const instance = Object.create(HttpSubdeviceInfo.prototype);
+        instance.subDeviceId = normalized.subDeviceId || null;
+        instance.trueId = normalized.trueId || null;
+        instance.subDeviceType = normalized.subDeviceType || null;
+        instance.subDeviceVendor = normalized.subDeviceVendor || null;
+        instance.subDeviceName = normalized.subDeviceName || null;
+        instance.subDeviceIconId = normalized.subDeviceIconId || null;
+
+        return instance;
+    }
+
+    /**
+     * Converts the instance to a plain object dictionary with camelCase keys
+     *
+     * @returns {Object} Plain object with camelCase property keys
+     */
+    toDict() {
+        return {
+            subDeviceId: this.subDeviceId,
+            trueId: this.trueId,
+            subDeviceType: this.subDeviceType,
+            subDeviceVendor: this.subDeviceVendor,
+            subDeviceName: this.subDeviceName,
+            subDeviceIconId: this.subDeviceIconId
+        };
+    }
+
+    /**
+     * Returns a string representation of the subdevice info
+     *
+     * Provides a human-readable format for logging and debugging. Includes
+     * name, type, and both device IDs to uniquely identify the subdevice.
+     *
+     * @returns {string} String representation in the format "Name (type, ID x, TRUE-ID y)"
+     */
+    toString() {
+        const name = this.subDeviceName || 'Unknown';
+        const type = this.subDeviceType || 'unknown';
+        const id = this.subDeviceId || 'N/A';
+        const trueId = this.trueId || 'N/A';
+        return `${name} (${type}, ID ${id}, TRUE-ID ${trueId})`;
+    }
+
+    /**
+     * Returns a JSON representation of the subdevice info
+     *
+     * Serializes the subdevice data to JSON format. Uses toDict() to ensure
+     * consistent camelCase property names in the output.
+     *
+     * @returns {string} JSON string representation of the subdevice data
+     */
+    toJSON() {
+        return JSON.stringify(this.toDict());
+    }
+}
+
+module.exports = HttpSubdeviceInfo;

package/lib/model/push/alarm.js

@@ -0,0 +1,112 @@
+'use strict';
+
+const GenericPushNotification = require('./generic');
+
+/**
+ * Push notification for device alarm events.
+ *
+ * Handles alarm notifications from both standalone devices and hub subdevices.
+ * The alarm data structure varies: standalone devices send alarm data directly,
+ * while hub sensors include interconnection data with source subdevice information.
+ *
+ * @class
+ * @extends GenericPushNotification
+ * @example
+ * device.on('pushNotification', (notification) => {
+ *     if (notification instanceof AlarmPushNotification) {
+ *         console.log('Alarm triggered on channel:', notification.channel);
+ *         console.log('Alarm value:', notification.value);
+ *         console.log('Timestamp:', notification.timestamp);
+ *         if (notification.subdevice_id) {
+ *             console.log('From subdevice:', notification.subdevice_id);
+ *         }
+ *     }
+ * });
+ */
+class AlarmPushNotification extends GenericPushNotification {
+    /**
+     * Creates a new AlarmPushNotification instance.
+     *
+     * @param {string} originatingDeviceUuid - UUID of the device that sent the notification
+     * @param {Object} rawData - Raw notification data from the device
+     * @param {Object|Array} [rawData.alarm] - Alarm event data (single object or array)
+     * @param {number} [rawData.alarm.channel] - Channel number where alarm occurred
+     * @param {Object} [rawData.alarm.event] - Alarm event details
+     * @param {Object} [rawData.alarm.event.interConn] - Interconnection data
+     * @param {*} [rawData.alarm.event.interConn.value] - Alarm value
+     * @param {number} [rawData.alarm.event.interConn.timestamp] - Alarm timestamp
+     * @param {Object|Array} [rawData.alarm.event.interConn.source] - Source device data
+     * @param {string|number} [rawData.alarm.event.interConn.source.subId] - Subdevice ID if from hub sensor
+     */
+    constructor(originatingDeviceUuid, rawData) {
+        super('Appliance.Control.Alarm', originatingDeviceUuid, rawData);
+
+        // Devices may send single objects or arrays; normalize to array for consistent processing
+        const alarmRaw = rawData?.alarm;
+        const alarm = GenericPushNotification.normalizeToArray(alarmRaw);
+
+        // Update rawData so routing logic receives normalized structure
+        if (rawData && alarmRaw !== alarm) {
+            rawData.alarm = alarm;
+        }
+
+        if (alarm && alarm.length > 0) {
+            const alarmEvent = alarm[0];
+            this._channel = alarmEvent?.channel;
+
+            const interConn = alarmEvent?.event?.interConn;
+            if (interConn) {
+                this._value = interConn.value;
+                this._timestamp = interConn.timestamp;
+
+                const { source } = interConn;
+                const sourceArray = GenericPushNotification.normalizeToArray(source);
+                if (sourceArray && sourceArray.length > 0) {
+                    this._subDeviceId = sourceArray[0]?.subId;
+                }
+            }
+        }
+    }
+
+    /**
+     * Gets the alarm value.
+     *
+     * @returns {*} Alarm value or undefined if not available
+     */
+    get value() {
+        return this._value;
+    }
+
+    /**
+     * Gets the alarm timestamp.
+     *
+     * @returns {number|undefined} Timestamp when alarm occurred or undefined if not available
+     */
+    get timestamp() {
+        return this._timestamp;
+    }
+
+    /**
+     * Gets the channel number where the alarm occurred.
+     *
+     * @returns {number|undefined} Channel number or undefined if not available
+     */
+    get channel() {
+        return this._channel;
+    }
+
+    /**
+     * Gets the subdevice ID if alarm originated from a hub subdevice.
+     *
+     * Only present when the alarm comes from a hub sensor subdevice, not standalone devices.
+     *
+     * @returns {string|number|undefined} Subdevice ID or undefined if not from a subdevice
+     */
+    // eslint-disable-next-line camelcase
+    get subdevice_id() {
+        return this._subDeviceId;
+    }
+}
+
+module.exports = AlarmPushNotification;
+

package/lib/model/push/bind.js

@@ -0,0 +1,97 @@
+'use strict';
+
+const GenericPushNotification = require('./generic');
+const { HardwareInfo, FirmwareInfo, TimeInfo } = require('./common');
+
+/**
+ * Push notification for device binding events.
+ *
+ * Emitted when a device is bound to a user account or when binding information is updated.
+ * The binding data includes hardware and firmware metadata that uniquely identifies the device
+ * and its capabilities, which is used for device registration and feature detection.
+ *
+ * @class
+ * @extends GenericPushNotification
+ * @example
+ * device.on('pushNotification', (notification) => {
+ *     if (notification instanceof BindPushNotification) {
+ *         const timeInfo = notification.time;
+ *         if (timeInfo) {
+ *             console.log('Device bound at:', timeInfo.timestamp, 'timezone:', timeInfo.timezone);
+ *         }
+ *         const hwInfo = notification.hwinfo;
+ *         if (hwInfo) {
+ *             console.log('Hardware version:', hwInfo.version, 'MAC:', hwInfo.macAddress);
+ *         }
+ *         const fwInfo = notification.fwinfo;
+ *         if (fwInfo) {
+ *             console.log('Firmware version:', fwInfo.version, 'WiFi MAC:', fwInfo.wifiMac);
+ *         }
+ *     }
+ * });
+ */
+class BindPushNotification extends GenericPushNotification {
+    /**
+     * Creates a new BindPushNotification instance.
+     *
+     * @param {string} originatingDeviceUuid - UUID of the device that sent the notification
+     * @param {Object} rawData - Raw notification data from the device
+     * @param {Object} [rawData.bind] - Binding data
+     * @param {Object} [rawData.bind.time] - Time information object (will be converted to TimeInfo instance)
+     * @param {Object} [rawData.bind.hardware] - Hardware information object (will be converted to HardwareInfo instance)
+     * @param {Object} [rawData.bind.firmware] - Firmware information object (will be converted to FirmwareInfo instance)
+     */
+    constructor(originatingDeviceUuid, rawData) {
+        super('Appliance.Control.Bind', originatingDeviceUuid, rawData);
+    }
+
+    /**
+     * Gets the binding timestamp information.
+     *
+     * Returns a TimeInfo instance that normalizes timezone and timestamp data from the raw payload.
+     *
+     * @returns {TimeInfo|null} TimeInfo instance or null if not available
+     */
+    get time() {
+        const timeData = this._rawData?.bind?.time;
+        if (!timeData) {
+            return null;
+        }
+        return TimeInfo.fromDict(timeData);
+    }
+
+    /**
+     * Gets the hardware information.
+     *
+     * Returns a HardwareInfo instance that normalizes hardware metadata (version, UUID, MAC, chip type)
+     * from the raw payload, handling both camelCase and snake_case property names.
+     *
+     * @returns {HardwareInfo|null} HardwareInfo instance or null if not available
+     */
+    get hwinfo() {
+        const hardwareData = this._rawData?.bind?.hardware;
+        if (!hardwareData) {
+            return null;
+        }
+        return HardwareInfo.fromDict(hardwareData);
+    }
+
+    /**
+     * Gets the firmware information.
+     *
+     * Returns a FirmwareInfo instance that normalizes firmware metadata (version, WiFi MAC, server info)
+     * from the raw payload, handling both camelCase and snake_case property names.
+     *
+     * @returns {FirmwareInfo|null} FirmwareInfo instance or null if not available
+     */
+    get fwinfo() {
+        const firmwareData = this._rawData?.bind?.firmware;
+        if (!firmwareData) {
+            return null;
+        }
+        return FirmwareInfo.fromDict(firmwareData);
+    }
+}
+
+module.exports = BindPushNotification;
+