meross-iot 0.1.0

package/lib/model/push/generic.js

@@ -0,0 +1,115 @@
+'use strict';
+
+/**
+ * Base class for all push notifications from Meross devices.
+ *
+ * Push notifications are emitted by devices via MQTT to notify about state changes, alarms,
+ * online status changes, and other events. All specific notification types extend this base class.
+ *
+ * @class
+ * @example
+ * device.on('pushNotification', (notification) => {
+ *     if (notification instanceof GenericPushNotification) {
+ *         console.log('Notification from:', notification.originatingDeviceUuid);
+ *         console.log('Namespace:', notification.namespace);
+ *     }
+ * });
+ */
+class GenericPushNotification {
+    /**
+     * Creates a new GenericPushNotification instance.
+     *
+     * @param {string} namespace - The namespace of the notification (e.g., 'Appliance.Control.ToggleX')
+     * @param {string} originatingDeviceUuid - UUID of the device that sent the notification
+     * @param {Object} [rawData={}] - Raw notification data from the device
+     */
+    constructor(namespace, originatingDeviceUuid, rawData) {
+        this._namespace = namespace;
+        this._originatingDeviceUuid = originatingDeviceUuid;
+        this._rawData = rawData || {};
+    }
+
+    /**
+     * Gets the namespace of the notification.
+     *
+     * @returns {string} Namespace string (e.g., 'Appliance.Control.ToggleX')
+     */
+    get namespace() {
+        return this._namespace;
+    }
+
+    /**
+     * Gets the UUID of the device that sent the notification.
+     *
+     * @returns {string} Device UUID
+     */
+    get originatingDeviceUuid() {
+        return this._originatingDeviceUuid;
+    }
+
+    /**
+     * Gets the raw notification data.
+     *
+     * @returns {Object} Raw data object from the device
+     */
+    get rawData() {
+        return this._rawData;
+    }
+
+    /**
+     * Routes this notification to the appropriate subdevices if it's a hub notification.
+     *
+     * Delegates to the factory's routing helper to avoid circular dependencies between
+     * this module and the factory module. Can be overridden by specific notification
+     * classes for custom routing logic.
+     *
+     * @param {MerossHubDevice} hubDevice - The hub device instance
+     */
+    routeToSubdevices(hubDevice) {
+        // Import here to avoid circular dependency
+        const { routeToSubdevices: routeToSubdevicesHelper } = require('./factory');
+        routeToSubdevicesHelper(this, hubDevice);
+    }
+
+    /**
+     * Extracts state changes from this notification.
+     *
+     * Returns an object describing what changed, keyed by feature type. Each notification
+     * type should override this method to extract its specific changes. Used by subscription
+     * managers to identify what changed in a push notification.
+     *
+     * @returns {Object} Changes object, e.g., { toggle: { 0: true }, presence: { 0: {...} } }
+     * @example
+     * const changes = notification.extractChanges();
+     * if (changes.toggle) {
+     *     console.log('Toggle changed:', changes.toggle);
+     * }
+     */
+    extractChanges() {
+        return {};
+    }
+
+    /**
+     * Normalizes data structure to ensure consistent array format for routing.
+     *
+     * Converts single objects to arrays, keeps arrays as-is, and returns empty arrays
+     * for null/undefined. This normalization is necessary because Meross devices may send
+     * either single objects or arrays for the same data structure, and routing logic
+     * expects arrays for consistent iteration.
+     *
+     * @param {*} data - The data to normalize (can be object, array, null, or undefined)
+     * @returns {Array} Normalized array
+     */
+    static normalizeToArray(data) {
+        if (Array.isArray(data)) {
+            return data;
+        }
+        if (data !== null && data !== undefined) {
+            return [data];
+        }
+        return [];
+    }
+}
+
+module.exports = GenericPushNotification;
+

package/lib/model/push/hub-battery.js

@@ -0,0 +1,59 @@
+'use strict';
+
+const GenericPushNotification = require('./generic');
+
+/**
+ * Push notification for hub subdevice battery status updates.
+ *
+ * Emitted when a hub subdevice's battery status changes or is updated.
+ * Routed to the appropriate subdevice by the hub device.
+ *
+ * @class
+ * @extends GenericPushNotification
+ * @example
+ * hubDevice.on('pushNotification', (notification) => {
+ *     if (notification instanceof HubBatteryPushNotification) {
+ *         const batteryData = notification.batteryData;
+ *         batteryData.forEach(device => {
+ *             console.log('Subdevice battery:', device.id, device.battery, '%');
+ *         });
+ *     }
+ * });
+ */
+class HubBatteryPushNotification extends GenericPushNotification {
+    /**
+     * Creates a new HubBatteryPushNotification instance.
+     *
+     * @param {string} originatingDeviceUuid - UUID of the hub device that sent the notification
+     * @param {Object} rawData - Raw notification data from the device
+     * @param {Object|Array} [rawData.battery] - Battery status data (single object or array)
+     * @param {string|number} [rawData.battery.id] - Subdevice ID
+     * @param {number} [rawData.battery.battery] - Battery level (typically 0-100)
+     */
+    constructor(originatingDeviceUuid, rawData) {
+        super('Appliance.Hub.Battery', originatingDeviceUuid, rawData);
+
+        // Devices may send single objects or arrays; normalize to array for consistent processing
+        const batteryRaw = rawData?.battery;
+        const battery = GenericPushNotification.normalizeToArray(batteryRaw);
+
+        // Update rawData so routing logic receives normalized structure
+        if (rawData && batteryRaw !== battery) {
+            rawData.battery = battery;
+        }
+
+        this._batteryData = battery;
+    }
+
+    /**
+     * Gets the battery status data array.
+     *
+     * @returns {Array} Array of battery status objects (empty array if no data)
+     */
+    get batteryData() {
+        return this._batteryData;
+    }
+}
+
+module.exports = HubBatteryPushNotification;
+

package/lib/model/push/hub-mts100-all.js

@@ -0,0 +1,64 @@
+'use strict';
+
+const GenericPushNotification = require('./generic');
+
+/**
+ * Push notification for hub MTS100 thermostat valve complete state updates.
+ *
+ * Emitted when a hub MTS100 thermostat valve sends a complete state update (all parameters).
+ * Routed to the appropriate subdevice by the hub device.
+ *
+ * @class
+ * @extends GenericPushNotification
+ * @example
+ * hubDevice.on('pushNotification', (notification) => {
+ *     if (notification instanceof HubMts100AllPushNotification) {
+ *         const allData = notification.allData;
+ *         allData.forEach(thermostat => {
+ *             console.log('MTS100 thermostat update:', thermostat.id);
+ *             console.log('Mode:', thermostat.mode);
+ *             console.log('Temperature:', thermostat.currentTemp);
+ *         });
+ *     }
+ * });
+ */
+class HubMts100AllPushNotification extends GenericPushNotification {
+    /**
+     * Creates a new HubMts100AllPushNotification instance.
+     *
+     * @param {string} originatingDeviceUuid - UUID of the hub device that sent the notification
+     * @param {Object} rawData - Raw notification data from the device
+     * @param {Object|Array} [rawData.all] - Complete thermostat state data (single object or array)
+     * @param {string|number} [rawData.all.id] - Subdevice ID
+     * @param {number} [rawData.all.mode] - Thermostat mode
+     * @param {number} [rawData.all.targetTemp] - Target temperature
+     * @param {number} [rawData.all.currentTemp] - Current temperature
+     * @param {number} [rawData.all.working] - Working mode
+     */
+    constructor(originatingDeviceUuid, rawData) {
+        super('Appliance.Hub.Mts100.All', originatingDeviceUuid, rawData);
+
+        // Devices may send single objects or arrays; normalize to array for consistent processing
+        const allRaw = rawData?.all;
+        const all = GenericPushNotification.normalizeToArray(allRaw);
+
+        // Update rawData so routing logic receives normalized structure
+        if (rawData && allRaw !== all) {
+            rawData.all = all;
+        }
+
+        this._allData = all;
+    }
+
+    /**
+     * Gets the complete thermostat state data array.
+     *
+     * @returns {Array} Array of thermostat state objects (empty array if no data)
+     */
+    get allData() {
+        return this._allData;
+    }
+}
+
+module.exports = HubMts100AllPushNotification;
+

package/lib/model/push/hub-mts100-mode.js

@@ -0,0 +1,59 @@
+'use strict';
+
+const GenericPushNotification = require('./generic');
+
+/**
+ * Push notification for hub MTS100 thermostat valve mode changes.
+ *
+ * Emitted when a hub MTS100 thermostat valve's mode changes.
+ * Routed to the appropriate subdevice by the hub device.
+ *
+ * @class
+ * @extends GenericPushNotification
+ * @example
+ * hubDevice.on('pushNotification', (notification) => {
+ *     if (notification instanceof HubMts100ModePushNotification) {
+ *         const modeData = notification.modeData;
+ *         modeData.forEach(thermostat => {
+ *             console.log('MTS100 mode changed:', thermostat.id, thermostat.mode);
+ *         });
+ *     }
+ * });
+ */
+class HubMts100ModePushNotification extends GenericPushNotification {
+    /**
+     * Creates a new HubMts100ModePushNotification instance.
+     *
+     * @param {string} originatingDeviceUuid - UUID of the hub device that sent the notification
+     * @param {Object} rawData - Raw notification data from the device
+     * @param {Object|Array} [rawData.mode] - Thermostat mode data (single object or array)
+     * @param {string|number} [rawData.mode.id] - Subdevice ID
+     * @param {number} [rawData.mode.mode] - Thermostat mode value
+     */
+    constructor(originatingDeviceUuid, rawData) {
+        super('Appliance.Hub.Mts100.Mode', originatingDeviceUuid, rawData);
+
+        // Devices may send single objects or arrays; normalize to array for consistent processing
+        const modeRaw = rawData?.mode;
+        const mode = GenericPushNotification.normalizeToArray(modeRaw);
+
+        // Update rawData so routing logic receives normalized structure
+        if (rawData && modeRaw !== mode) {
+            rawData.mode = mode;
+        }
+
+        this._modeData = mode;
+    }
+
+    /**
+     * Gets the thermostat mode data array.
+     *
+     * @returns {Array} Array of mode objects (empty array if no data)
+     */
+    get modeData() {
+        return this._modeData;
+    }
+}
+
+module.exports = HubMts100ModePushNotification;
+

package/lib/model/push/hub-mts100-temperature.js

@@ -0,0 +1,62 @@
+'use strict';
+
+const GenericPushNotification = require('./generic');
+
+/**
+ * Push notification for hub MTS100 thermostat valve temperature updates.
+ *
+ * Emitted when a hub MTS100 thermostat valve's temperature reading changes.
+ * Routed to the appropriate subdevice by the hub device.
+ *
+ * @class
+ * @extends GenericPushNotification
+ * @example
+ * hubDevice.on('pushNotification', (notification) => {
+ *     if (notification instanceof HubMts100TemperaturePushNotification) {
+ *         const tempData = notification.temperatureData;
+ *         tempData.forEach(thermostat => {
+ *             console.log('MTS100 temperature update:', thermostat.id);
+ *             console.log('Current temp:', thermostat.currentTemp);
+ *             console.log('Target temp:', thermostat.targetTemp);
+ *         });
+ *     }
+ * });
+ */
+class HubMts100TemperaturePushNotification extends GenericPushNotification {
+    /**
+     * Creates a new HubMts100TemperaturePushNotification instance.
+     *
+     * @param {string} originatingDeviceUuid - UUID of the hub device that sent the notification
+     * @param {Object} rawData - Raw notification data from the device
+     * @param {Object|Array} [rawData.temperature] - Temperature data (single object or array)
+     * @param {string|number} [rawData.temperature.id] - Subdevice ID
+     * @param {number} [rawData.temperature.currentTemp] - Current temperature reading
+     * @param {number} [rawData.temperature.targetTemp] - Target temperature setting
+     */
+    constructor(originatingDeviceUuid, rawData) {
+        super('Appliance.Hub.Mts100.Temperature', originatingDeviceUuid, rawData);
+
+        // Devices may send single objects or arrays; normalize to array for consistent processing
+        const temperatureRaw = rawData?.temperature;
+        const temperature = GenericPushNotification.normalizeToArray(temperatureRaw);
+
+        // Update rawData so routing logic receives normalized structure
+        if (rawData && temperatureRaw !== temperature) {
+            rawData.temperature = temperature;
+        }
+
+        this._temperatureData = temperature;
+    }
+
+    /**
+     * Gets the temperature data array.
+     *
+     * @returns {Array} Array of temperature objects (empty array if no data)
+     */
+    get temperatureData() {
+        return this._temperatureData;
+    }
+}
+
+module.exports = HubMts100TemperaturePushNotification;
+

package/lib/model/push/hub-online.js

@@ -0,0 +1,59 @@
+'use strict';
+
+const GenericPushNotification = require('./generic');
+
+/**
+ * Push notification for hub subdevice online status changes.
+ *
+ * Emitted when a hub subdevice's online status changes.
+ * Routed to the appropriate subdevice by the hub device.
+ *
+ * @class
+ * @extends GenericPushNotification
+ * @example
+ * hubDevice.on('pushNotification', (notification) => {
+ *     if (notification instanceof HubOnlinePushNotification) {
+ *         const onlineData = notification.onlineData;
+ *         onlineData.forEach(device => {
+ *             console.log('Subdevice online status:', device.id, device.status);
+ *         });
+ *     }
+ * });
+ */
+class HubOnlinePushNotification extends GenericPushNotification {
+    /**
+     * Creates a new HubOnlinePushNotification instance.
+     *
+     * @param {string} originatingDeviceUuid - UUID of the hub device that sent the notification
+     * @param {Object} rawData - Raw notification data from the device
+     * @param {Object|Array} [rawData.online] - Online status data (single object or array)
+     * @param {string|number} [rawData.online.id] - Subdevice ID
+     * @param {number} [rawData.online.status] - Online status value
+     */
+    constructor(originatingDeviceUuid, rawData) {
+        super('Appliance.Hub.Online', originatingDeviceUuid, rawData);
+
+        // Devices may send single objects or arrays; normalize to array for consistent processing
+        const onlineRaw = rawData?.online;
+        const online = GenericPushNotification.normalizeToArray(onlineRaw);
+
+        // Update rawData so routing logic receives normalized structure
+        if (rawData && onlineRaw !== online) {
+            rawData.online = online;
+        }
+
+        this._onlineData = online;
+    }
+
+    /**
+     * Gets the online status data array.
+     *
+     * @returns {Array} Array of online status objects (empty array if no data)
+     */
+    get onlineData() {
+        return this._onlineData;
+    }
+}
+
+module.exports = HubOnlinePushNotification;
+

package/lib/model/push/hub-sensor-alert.js

@@ -0,0 +1,61 @@
+'use strict';
+
+const GenericPushNotification = require('./generic');
+
+/**
+ * Push notification for hub sensor alert events.
+ *
+ * Emitted when a hub sensor subdevice triggers an alert (e.g., temperature threshold exceeded,
+ * humidity alert, etc.). Routed to the appropriate subdevice by the hub device.
+ *
+ * @class
+ * @extends GenericPushNotification
+ * @example
+ * hubDevice.on('pushNotification', (notification) => {
+ *     if (notification instanceof HubSensorAlertPushNotification) {
+ *         const alertData = notification.alertData;
+ *         alertData.forEach(alert => {
+ *             console.log('Sensor alert from subdevice:', alert.id);
+ *             console.log('Alert type:', alert.type);
+ *             console.log('Alert value:', alert.value);
+ *         });
+ *     }
+ * });
+ */
+class HubSensorAlertPushNotification extends GenericPushNotification {
+    /**
+     * Creates a new HubSensorAlertPushNotification instance.
+     *
+     * @param {string} originatingDeviceUuid - UUID of the hub device that sent the notification
+     * @param {Object} rawData - Raw notification data from the device
+     * @param {Object|Array} [rawData.alert] - Alert data (single object or array)
+     * @param {string|number} [rawData.alert.id] - Subdevice ID
+     * @param {*} [rawData.alert.*] - Alert-specific data fields
+     */
+    constructor(originatingDeviceUuid, rawData) {
+        super('Appliance.Hub.Sensor.Alert', originatingDeviceUuid, rawData);
+
+        // Devices may send single objects or arrays; normalize to array for consistent processing
+        const alertRaw = rawData?.alert;
+        const alert = GenericPushNotification.normalizeToArray(alertRaw);
+
+        // Update rawData so routing logic receives normalized structure
+        if (rawData && alertRaw !== alert) {
+            rawData.alert = alert;
+        }
+
+        this._alertData = alert;
+    }
+
+    /**
+     * Gets the alert data array.
+     *
+     * @returns {Array} Array of alert objects (empty array if no data)
+     */
+    get alertData() {
+        return this._alertData;
+    }
+}
+
+module.exports = HubSensorAlertPushNotification;
+

package/lib/model/push/hub-sensor-all.js

@@ -0,0 +1,59 @@
+'use strict';
+
+const GenericPushNotification = require('./generic');
+
+/**
+ * Push notification for hub sensor complete state updates.
+ *
+ * Emitted when a hub sensor subdevice sends a complete state update (all sensor parameters).
+ * Routed to the appropriate subdevice by the hub device.
+ *
+ * @class
+ * @extends GenericPushNotification
+ * @example
+ * hubDevice.on('pushNotification', (notification) => {
+ *     if (notification instanceof HubSensorAllPushNotification) {
+ *         const allData = notification.allData;
+ *         allData.forEach(sensor => {
+ *             console.log('Sensor complete update:', sensor.id);
+ *         });
+ *     }
+ * });
+ */
+class HubSensorAllPushNotification extends GenericPushNotification {
+    /**
+     * Creates a new HubSensorAllPushNotification instance.
+     *
+     * @param {string} originatingDeviceUuid - UUID of the hub device that sent the notification
+     * @param {Object} rawData - Raw notification data from the device
+     * @param {Object|Array} [rawData.all] - Complete sensor state data (single object or array)
+     * @param {string|number} [rawData.all.id] - Subdevice ID
+     * @param {*} [rawData.all.*] - Various sensor-specific data fields
+     */
+    constructor(originatingDeviceUuid, rawData) {
+        super('Appliance.Hub.Sensor.All', originatingDeviceUuid, rawData);
+
+        // Devices may send single objects or arrays; normalize to array for consistent processing
+        const allRaw = rawData?.all;
+        const all = GenericPushNotification.normalizeToArray(allRaw);
+
+        // Update rawData so routing logic receives normalized structure
+        if (rawData && allRaw !== all) {
+            rawData.all = all;
+        }
+
+        this._allData = all;
+    }
+
+    /**
+     * Gets the complete sensor state data array.
+     *
+     * @returns {Array} Array of sensor state objects (empty array if no data)
+     */
+    get allData() {
+        return this._allData;
+    }
+}
+
+module.exports = HubSensorAllPushNotification;
+

package/lib/model/push/hub-sensor-smoke.js

@@ -0,0 +1,110 @@
+'use strict';
+
+const GenericPushNotification = require('./generic');
+
+/**
+ * Push notification for hub smoke detector alarm events.
+ *
+ * Emitted when a hub smoke detector subdevice triggers an alarm or sends status updates.
+ * Routed to the appropriate subdevice by the hub device.
+ *
+ * @class
+ * @extends GenericPushNotification
+ * @example
+ * hubDevice.on('pushNotification', (notification) => {
+ *     if (notification instanceof HubSensorSmokePushNotification) {
+ *         console.log('Smoke alarm from subdevice:', notification.subdevice_id);
+ *         console.log('Status:', notification.status);
+ *         console.log('Timestamp:', notification.timestamp);
+ *         if (notification.testEvent) {
+ *             console.log('This is a test event');
+ *         }
+ *     }
+ * });
+ */
+class HubSensorSmokePushNotification extends GenericPushNotification {
+    /**
+     * Creates a new HubSensorSmokePushNotification instance.
+     *
+     * @param {string} originatingDeviceUuid - UUID of the hub device that sent the notification
+     * @param {Object} rawData - Raw notification data from the device
+     * @param {Object|Array} [rawData.smokeAlarm] - Smoke alarm data (single object or array)
+     * @param {string|number} [rawData.smokeAlarm.id] - Subdevice ID
+     * @param {number} [rawData.smokeAlarm.status] - Alarm status (from SmokeAlarmStatus enum)
+     * @param {Object} [rawData.smokeAlarm.interConn] - Interconnection data
+     * @param {number} [rawData.smokeAlarm.timestamp] - Alarm timestamp
+     * @param {Object} [rawData.smokeAlarm.event] - Event details
+     * @param {boolean} [rawData.smokeAlarm.event.test] - Whether this is a test event
+     */
+    constructor(originatingDeviceUuid, rawData) {
+        super('Appliance.Hub.Sensor.Smoke', originatingDeviceUuid, rawData);
+
+        // Devices may send single objects or arrays; normalize to array for consistent processing
+        const smokeAlarmRaw = rawData?.smokeAlarm;
+        const smokeAlarm = GenericPushNotification.normalizeToArray(smokeAlarmRaw);
+
+        // Update rawData so routing logic receives normalized structure
+        if (rawData && smokeAlarmRaw !== smokeAlarm) {
+            rawData.smokeAlarm = smokeAlarm;
+        }
+
+        if (smokeAlarm && smokeAlarm.length > 0) {
+            const event = smokeAlarm[0];
+            this._subDeviceId = event?.id;
+            this._status = event?.status;
+            this._interConn = event?.interConn;
+            this._timestamp = event?.timestamp;
+            this._testEvent = event?.event?.test;
+        }
+    }
+
+    /**
+     * Gets the subdevice ID of the smoke detector.
+     *
+     * @returns {string|number|undefined} Subdevice ID or undefined if not available
+     */
+    // eslint-disable-next-line camelcase
+    get subdevice_id() {
+        return this._subDeviceId;
+    }
+
+    /**
+     * Gets the alarm status.
+     *
+     * @returns {number|undefined} Status value (from SmokeAlarmStatus enum) or undefined if not available
+     * @see {@link module:lib/enums.SmokeAlarmStatus} for status constants
+     */
+    get status() {
+        return this._status;
+    }
+
+    /**
+     * Gets the interconnection data.
+     *
+     * @returns {Object|undefined} Interconnection data object or undefined if not available
+     */
+    get interConn() {
+        return this._interConn;
+    }
+
+    /**
+     * Gets the alarm timestamp.
+     *
+     * @returns {number|undefined} Timestamp when alarm occurred or undefined if not available
+     */
+    get timestamp() {
+        return this._timestamp;
+    }
+
+    /**
+     * Gets whether this is a test event.
+     *
+     * @returns {boolean|undefined} True if test event, false if real alarm, undefined if not available
+     */
+    get testEvent() {
+        return this._testEvent;
+    }
+}
+
+module.exports = HubSensorSmokePushNotification;
+