meross-iot 0.1.0

package/lib/model/push/unbind.js

@@ -0,0 +1,34 @@
+'use strict';
+
+const GenericPushNotification = require('./generic');
+
+/**
+ * Push notification for device unbinding events.
+ *
+ * Emitted when a device is unbound from a user account. Typically occurs when
+ * a device is removed from the account or factory reset.
+ *
+ * @class
+ * @extends GenericPushNotification
+ * @example
+ * device.on('pushNotification', (notification) => {
+ *     if (notification instanceof UnbindPushNotification) {
+ *         console.log('Device unbound:', notification.originatingDeviceUuid);
+ *         // Device is no longer associated with this account
+ *     }
+ * });
+ */
+class UnbindPushNotification extends GenericPushNotification {
+    /**
+     * Creates a new UnbindPushNotification instance.
+     *
+     * @param {string} originatingDeviceUuid - UUID of the device that sent the notification
+     * @param {Object} rawData - Raw notification data from the device
+     */
+    constructor(originatingDeviceUuid, rawData) {
+        super('Appliance.Control.Unbind', originatingDeviceUuid, rawData);
+    }
+}
+
+module.exports = UnbindPushNotification;
+

package/lib/model/push/water-leak.js

@@ -0,0 +1,107 @@
+'use strict';
+
+const GenericPushNotification = require('./generic');
+
+/**
+ * Push notification for water leak sensor events from hub subdevices.
+ *
+ * Emitted when a water leak sensor (hub subdevice) detects a leak or sends sensor updates.
+ * Routed to the appropriate subdevice by the hub device.
+ *
+ * @class
+ * @extends GenericPushNotification
+ * @example
+ * hubDevice.on('pushNotification', (notification) => {
+ *     if (notification instanceof WaterLeakPushNotification) {
+ *         console.log('Water leak sensor update from subdevice:', notification.subdevice_id);
+ *         console.log('Latest sample indicates leak:', notification.latestSampleIsLeak);
+ *         console.log('Sample time:', notification.latestSampleTime);
+ *     }
+ * });
+ */
+class WaterLeakPushNotification extends GenericPushNotification {
+    /**
+     * Creates a new WaterLeakPushNotification 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.waterLeak] - Water leak sensor data (single object or array)
+     * @param {string|number} [rawData.waterLeak.id] - Subdevice ID
+     * @param {boolean} [rawData.waterLeak.latestWaterLeak] - Whether latest sample indicates leak
+     * @param {number} [rawData.waterLeak.latestSampleTime] - Timestamp of latest sample
+     * @param {number} [rawData.waterLeak.syncedTime] - Synchronization timestamp
+     * @param {Array} [rawData.waterLeak.sample] - Array of sensor samples
+     */
+    constructor(originatingDeviceUuid, rawData) {
+        super('Appliance.Hub.Sensor.WaterLeak', originatingDeviceUuid, rawData);
+
+        // Devices may send single objects or arrays; normalize to array for consistent processing
+        const waterLeakRaw = rawData?.waterLeak;
+        const waterLeak = GenericPushNotification.normalizeToArray(waterLeakRaw);
+
+        // Update rawData so routing logic receives normalized structure
+        if (rawData && waterLeakRaw !== waterLeak) {
+            rawData.waterLeak = waterLeak;
+        }
+
+        if (waterLeak && waterLeak.length > 0) {
+            const event = waterLeak[0];
+            this._subDeviceId = event?.id;
+            this._latestWaterLeak = event?.latestWaterLeak;
+            this._latestSampleTime = event?.latestSampleTime;
+            this._syncedTime = event?.syncedTime;
+            this._samples = event?.sample;
+        }
+    }
+
+    /**
+     * Gets the synchronization timestamp.
+     *
+     * @returns {number|undefined} Sync timestamp or undefined if not available
+     */
+    get syncedTime() {
+        return this._syncedTime;
+    }
+
+    /**
+     * Gets the timestamp of the latest sample.
+     *
+     * @returns {number|undefined} Latest sample timestamp or undefined if not available
+     */
+    get latestSampleTime() {
+        return this._latestSampleTime;
+    }
+
+    /**
+     * Gets whether the latest sample indicates a water leak.
+     *
+     * @returns {boolean|undefined} True if leak detected, false if no leak, undefined if not available
+     */
+    get latestSampleIsLeak() {
+        return this._latestWaterLeak;
+    }
+
+    /**
+     * Gets the subdevice ID of the water leak sensor.
+     *
+     * @returns {string|number|undefined} Subdevice ID or undefined if not available
+     */
+    // eslint-disable-next-line camelcase
+    get subdevice_id() {
+        return this._subDeviceId;
+    }
+
+    /**
+     * Gets the array of sensor samples.
+     *
+     * Contains historical sensor readings for analysis.
+     *
+     * @returns {Array|undefined} Array of sample data or undefined if not available
+     */
+    get samples() {
+        return this._samples;
+    }
+}
+
+module.exports = WaterLeakPushNotification;
+

package/lib/model/states/diffuser-light-state.js

@@ -0,0 +1,119 @@
+'use strict';
+
+const { intToRgb } = require('../../utilities/conversion');
+
+/**
+ * Represents the light state of a diffuser device channel.
+ *
+ * Encapsulates state information for diffuser light devices, including color, brightness,
+ * mode, and on/off state. State instances are managed by device controllers and updated
+ * automatically when device responses or push notifications are received.
+ *
+ * @class
+ * @example
+ * const diffuserLightState = device.getCachedDiffuserLightState(0);
+ * if (diffuserLightState) {
+ *     console.log('Light is on:', diffuserLightState.isOn);
+ *     console.log('Mode:', diffuserLightState.mode);
+ *     console.log('RGB color:', diffuserLightState.rgbTuple);
+ *     console.log('Brightness:', diffuserLightState.luminance);
+ * }
+ */
+class DiffuserLightState {
+    /**
+     * Creates a new DiffuserLightState instance.
+     *
+     * @param {Object} [state=null] - Initial state object
+     * @param {number} [state.onoff] - On/off state (0=off, 1=on)
+     * @param {number} [state.mode] - Light mode (from DiffuserLightMode enum: ROTATING_COLORS=0, FIXED_RGB=1, FIXED_LUMINANCE=2)
+     * @param {number} [state.rgb] - RGB color as integer
+     * @param {number} [state.luminance] - Brightness value (0-100)
+     */
+    constructor(state = null) {
+        this._state = state || {};
+    }
+
+    /**
+     * Updates the state with new data.
+     *
+     * Merges new state data into the existing state using Object.assign to preserve
+     * properties not included in the update. Called automatically by device controllers
+     * when state updates are received from device responses or push notifications.
+     *
+     * @param {Object} state - New state data to merge
+     */
+    update(state) {
+        if (state) {
+            Object.assign(this._state, state);
+        }
+    }
+
+    /**
+     * Gets whether the light is on.
+     *
+     * Converts the device's numeric on/off state (0 or 1) to a boolean for easier
+     * conditional logic in application code.
+     *
+     * @returns {boolean|undefined} True if on, false if off, undefined if state not available
+     */
+    get isOn() {
+        const { onoff } = this._state;
+        if (onoff === undefined || onoff === null) {return undefined;}
+        return onoff === 1;
+    }
+
+    /**
+     * Gets the light mode.
+     *
+     * @returns {number|undefined} Light mode value (0=rotating colors, 1=fixed RGB, 2=fixed luminance) or undefined if not available
+     * @see {@link module:lib/enums.DiffuserLightMode} for mode constants
+     */
+    get mode() {
+        const { mode } = this._state;
+        if (mode === undefined || mode === null) {return undefined;}
+        return mode;
+    }
+
+    /**
+     * Gets the RGB color as a tuple [r, g, b].
+     *
+     * The device stores RGB as a single integer value. This getter converts it to
+     * a tuple format for easier color manipulation and integration with graphics
+     * libraries that expect separate R, G, B components.
+     *
+     * @returns {Array<number>|undefined} RGB tuple [r, g, b] where each value is 0-255, or undefined if not available
+     */
+    get rgbTuple() {
+        const { rgb } = this._state;
+        if (rgb === undefined || rgb === null) {return undefined;}
+        return intToRgb(rgb);
+    }
+
+    /**
+     * Gets the RGB color as an integer.
+     *
+     * Returns the raw RGB value as stored by the device. Use this when you need
+     * the exact format used in device communication protocols.
+     *
+     * @returns {number|undefined} RGB color as integer or undefined if not available
+     */
+    get rgbInt() {
+        const { rgb } = this._state;
+        if (rgb === undefined || rgb === null) {return undefined;}
+        return rgb;
+    }
+
+    /**
+     * Gets the brightness/luminance value.
+     *
+     * @returns {number|undefined} Brightness value (0-100) or undefined if not available
+     */
+    get luminance() {
+        const { luminance } = this._state;
+        if (luminance === undefined || luminance === null) {return undefined;}
+        return luminance;
+    }
+}
+
+module.exports = DiffuserLightState;
+

package/lib/model/states/diffuser-spray-state.js

@@ -0,0 +1,58 @@
+'use strict';
+
+/**
+ * Represents the spray state of a diffuser device channel.
+ *
+ * Encapsulates state information for diffuser spray/mist functionality. State instances
+ * are managed by device controllers and updated automatically when device responses or
+ * push notifications are received.
+ *
+ * @class
+ * @example
+ * const diffuserSprayState = device.getCachedDiffuserSprayState(0);
+ * if (diffuserSprayState) {
+ *     console.log('Spray mode:', diffuserSprayState.mode);
+ * }
+ */
+class DiffuserSprayState {
+    /**
+     * Creates a new DiffuserSprayState instance.
+     *
+     * @param {Object} [state=null] - Initial state object
+     * @param {number} [state.mode] - Spray mode (from DiffuserSprayMode enum: LIGHT=0, STRONG=1, OFF=2)
+     * @param {number} [state.channel] - Channel number
+     */
+    constructor(state = null) {
+        this._state = state || {};
+    }
+
+    /**
+     * Updates the state with new data.
+     *
+     * Merges new state data into the existing state using Object.assign to preserve
+     * properties not included in the update. Called automatically by device controllers
+     * when state updates are received from device responses or push notifications.
+     *
+     * @param {Object} state - New state data to merge
+     */
+    update(state) {
+        if (state) {
+            Object.assign(this._state, state);
+        }
+    }
+
+    /**
+     * Gets the spray mode.
+     *
+     * @returns {number|undefined} Spray mode value (0=light, 1=strong, 2=off) or undefined if not available
+     * @see {@link module:lib/enums.DiffuserSprayMode} for mode constants
+     */
+    get mode() {
+        const { mode } = this._state;
+        if (mode === undefined || mode === null) {return undefined;}
+        return mode;
+    }
+}
+
+module.exports = DiffuserSprayState;
+

package/lib/model/states/garage-door-state.js

@@ -0,0 +1,71 @@
+'use strict';
+
+/**
+ * Represents the state of a garage door device channel.
+ *
+ * Encapsulates state information for garage door opener devices. State instances are
+ * managed by device controllers and updated automatically when device responses or
+ * push notifications are received.
+ *
+ * @class
+ * @example
+ * const garageDoorState = device.getCachedGarageDoorState(0);
+ * if (garageDoorState) {
+ *     console.log('Garage door is open:', garageDoorState.isOpen);
+ * }
+ */
+class GarageDoorState {
+    /**
+     * Creates a new GarageDoorState instance.
+     *
+     * @param {Object} [state=null] - Initial state object
+     * @param {number} [state.open] - Open/closed state (0=closed, 1=open)
+     * @param {number} [state.channel] - Channel number
+     */
+    constructor(state = null) {
+        this._state = state || {};
+    }
+
+    /**
+     * Updates the state with new data.
+     *
+     * Merges new state data into the existing state using Object.assign to preserve
+     * properties not included in the update. Called automatically by device controllers
+     * when state updates are received from device responses or push notifications.
+     *
+     * @param {Object} state - New state data to merge
+     */
+    update(state) {
+        if (state) {
+            Object.assign(this._state, state);
+        }
+    }
+
+    /**
+     * Gets whether the garage door is open.
+     *
+     * Converts the device's numeric open/closed state (0 or 1) to a boolean for easier
+     * conditional logic in application code.
+     *
+     * @returns {boolean|undefined} True if open, false if closed, undefined if state not available
+     */
+    get isOpen() {
+        const { open } = this._state;
+        if (open === undefined || open === null) {return undefined;}
+        return open === 1;
+    }
+
+    /**
+     * Gets the channel number.
+     *
+     * @returns {number|undefined} Channel number or undefined if not available
+     */
+    get channel() {
+        const { channel } = this._state;
+        if (channel === undefined || channel === null) {return undefined;}
+        return channel;
+    }
+}
+
+module.exports = GarageDoorState;
+

package/lib/model/states/index.js

@@ -0,0 +1,38 @@
+'use strict';
+
+/**
+ * @module lib/model/states
+ * @description State classes for device channels.
+ *
+ * This module exports state classes that encapsulate device channel state information.
+ * Each state class provides a consistent interface for accessing and updating device
+ * state. State instances are managed by device controllers and updated automatically
+ * when device responses or push notifications are received.
+ */
+
+const LightState = require('./light-state');
+const ThermostatState = require('./thermostat-state');
+const DiffuserLightState = require('./diffuser-light-state');
+const DiffuserSprayState = require('./diffuser-spray-state');
+const SprayState = require('./spray-state');
+const RollerShutterState = require('./roller-shutter-state');
+const GarageDoorState = require('./garage-door-state');
+const TimerState = require('./timer-state');
+const TriggerState = require('./trigger-state');
+const ToggleState = require('./toggle-state');
+const PresenceSensorState = require('./presence-sensor-state');
+
+module.exports = {
+    LightState,
+    ThermostatState,
+    DiffuserLightState,
+    DiffuserSprayState,
+    SprayState,
+    RollerShutterState,
+    GarageDoorState,
+    TimerState,
+    TriggerState,
+    ToggleState,
+    PresenceSensorState
+};
+

package/lib/model/states/light-state.js

@@ -0,0 +1,134 @@
+'use strict';
+
+const { intToRgb } = require('../../utilities/conversion');
+
+/**
+ * Represents the light state of a device channel.
+ *
+ * Encapsulates state information for light devices, including color, brightness,
+ * temperature, and on/off state. State instances are managed by device controllers
+ * and updated automatically when device responses or push notifications are received.
+ *
+ * @class
+ * @example
+ * const lightState = device.getCachedLightState(0);
+ * if (lightState) {
+ *     console.log('Light is on:', lightState.isOn);
+ *     console.log('RGB color:', lightState.rgbTuple);
+ *     console.log('Brightness:', lightState.luminance);
+ * }
+ */
+class LightState {
+    /**
+     * Creates a new LightState instance.
+     *
+     * @param {Object} [state=null] - Initial state object
+     * @param {number} [state.onoff] - On/off state (0=off, 1=on)
+     * @param {number} [state.channel] - Channel number
+     * @param {number} [state.rgb] - RGB color as integer
+     * @param {number} [state.luminance] - Brightness value (0-100)
+     * @param {number} [state.temperature] - Color temperature value
+     * @param {number} [state.capacity] - Light mode/capacity flags
+     */
+    constructor(state = null) {
+        this._state = state || {};
+    }
+
+    /**
+     * Updates the state with new data.
+     *
+     * Merges new state data into the existing state using Object.assign to preserve
+     * properties not included in the update. Called automatically by device controllers
+     * when state updates are received from device responses or push notifications.
+     *
+     * @param {Object} state - New state data to merge
+     */
+    update(state) {
+        if (state) {
+            Object.assign(this._state, state);
+        }
+    }
+
+    /**
+     * Gets whether the light is on.
+     *
+     * Converts the device's numeric on/off state (0 or 1) to a boolean for easier
+     * conditional logic in application code.
+     *
+     * @returns {boolean|undefined} True if on, false if off, undefined if state not available
+     */
+    get isOn() {
+        const { onoff } = this._state;
+        if (onoff === undefined || onoff === null) {return undefined;}
+        return onoff === 1;
+    }
+
+    /**
+     * Gets the RGB color as a tuple [r, g, b].
+     *
+     * The device stores RGB as a single integer value. This getter converts it to
+     * a tuple format for easier color manipulation and integration with graphics
+     * libraries that expect separate R, G, B components.
+     *
+     * @returns {Array<number>|undefined} RGB tuple [r, g, b] where each value is 0-255, or undefined if not available
+     */
+    get rgbTuple() {
+        const { rgb } = this._state;
+        if (rgb === undefined || rgb === null) {return undefined;}
+        return intToRgb(rgb);
+    }
+
+    /**
+     * Gets the RGB color as an integer.
+     *
+     * Returns the raw RGB value as stored by the device. Use this when you need
+     * the exact format used in device communication protocols.
+     *
+     * @returns {number|undefined} RGB color as integer or undefined if not available
+     */
+    get rgbInt() {
+        const { rgb } = this._state;
+        if (rgb === undefined || rgb === null) {return undefined;}
+        return rgb;
+    }
+
+    /**
+     * Gets the brightness/luminance value.
+     *
+     * @returns {number|undefined} Brightness value (0-100) or undefined if not available
+     */
+    get luminance() {
+        const { luminance } = this._state;
+        if (luminance === undefined || luminance === null) {return undefined;}
+        return luminance;
+    }
+
+    /**
+     * Gets the color temperature value.
+     *
+     * @returns {number|undefined} Temperature value or undefined if not available
+     */
+    get temperature() {
+        const { temperature } = this._state;
+        if (temperature === undefined || temperature === null) {return undefined;}
+        return temperature;
+    }
+
+    /**
+     * Gets the light mode/capacity flags.
+     *
+     * Capacity is a bitmask indicating which light modes the device supports
+     * (RGB, luminance, temperature). Use bitwise operations to check for specific
+     * capabilities.
+     *
+     * @returns {number|undefined} Capacity flags or undefined if not available
+     */
+    get capacity() {
+        const { capacity } = this._state;
+        if (capacity === undefined || capacity === null) {return undefined;}
+        return capacity;
+    }
+}
+
+module.exports = LightState;
+