meross-iot 0.1.0

package/lib/model/push/common.js

@@ -0,0 +1,282 @@
+'use strict';
+
+/**
+ * Represents hardware information from device binding data.
+ *
+ * Encapsulates hardware metadata from device binding notifications. The API may return
+ * properties in either camelCase or snake_case format, so this class normalizes them
+ * to camelCase for consistent access.
+ *
+ * @class
+ * @example
+ * // Use fromDict() to create instances
+ * const hardwareInfo = HardwareInfo.fromDict({
+ *     version: '1.0.0',
+ *     uuid: '12345',
+ *     type: 'mss310',
+ *     sub_type: 'v1',
+ *     mac_address: 'AA:BB:CC:DD:EE:FF',
+ *     chip_type: 'ESP32'
+ * });
+ */
+class HardwareInfo {
+    /**
+     * Creates a HardwareInfo instance from a dictionary object.
+     *
+     * Normalizes property names from both camelCase and snake_case formats to ensure
+     * consistent access regardless of API response format. Uses Object.create() instead
+     * of a constructor to allow static factory pattern.
+     *
+     * @static
+     * @param {Object} jsonDict - Raw API response object with any key format
+     * @param {string} [jsonDict.version] - Hardware version
+     * @param {string} [jsonDict.uuid] - Device UUID
+     * @param {string} [jsonDict.type] - Hardware type
+     * @param {string} [jsonDict.subType] - Hardware sub-type (camelCase)
+     * @param {string} [jsonDict.sub_type] - Hardware sub-type (snake_case)
+     * @param {string} [jsonDict.macAddress] - MAC address (camelCase)
+     * @param {string} [jsonDict.mac_address] - MAC address (snake_case)
+     * @param {string} [jsonDict.chipType] - Chip type (camelCase)
+     * @param {string} [jsonDict.chip_type] - Chip type (snake_case)
+     * @param {string} [jsonDict.chip_time] - Chip time (snake_case, mapped to chipType)
+     * @returns {HardwareInfo} New HardwareInfo instance
+     */
+    static fromDict(jsonDict) {
+        if (!jsonDict || typeof jsonDict !== 'object') {
+            return null;
+        }
+
+        // Map camelCase keys to their possible API variants (camelCase, snake_case)
+        const propertyMappings = {
+            version: ['version'],
+            uuid: ['uuid'],
+            type: ['type'],
+            subType: ['subType', 'sub_type'],
+            macAddress: ['macAddress', 'mac_address'],
+            chipType: ['chipType', 'chip_type', 'chip_time']
+        };
+
+        // Check each mapping in priority order to find the first non-null value
+        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() to avoid constructor, allowing static factory pattern
+        const instance = Object.create(HardwareInfo.prototype);
+        instance.version = normalized.version || null;
+        instance.uuid = normalized.uuid || null;
+        instance.type = normalized.type || null;
+        instance.subType = normalized.subType || null;
+        instance.macAddress = normalized.macAddress || null;
+        instance.chipType = normalized.chipType || null;
+
+        return instance;
+    }
+
+    /**
+     * Converts the instance to a plain object dictionary with camelCase keys.
+     *
+     * @returns {Object} Plain object with camelCase property keys
+     */
+    toDict() {
+        return {
+            version: this.version,
+            uuid: this.uuid,
+            type: this.type,
+            subType: this.subType,
+            macAddress: this.macAddress,
+            chipType: this.chipType
+        };
+    }
+}
+
+/**
+ * Represents firmware information from device binding data.
+ *
+ * Encapsulates firmware metadata from device binding notifications. The API may return
+ * properties in either camelCase or snake_case format, so this class normalizes them
+ * to camelCase for consistent access.
+ *
+ * @class
+ * @example
+ * // Use fromDict() to create instances
+ * const firmwareInfo = FirmwareInfo.fromDict({
+ *     wifi_mac: 'AA:BB:CC:DD:EE:FF',
+ *     version: '2.0.0',
+ *     user_id: 'user123',
+ *     server: 'mqtt.meross.com',
+ *     port: 443,
+ *     inner_ip: '192.168.1.100',
+ *     compile_time: '2024-01-01'
+ * });
+ */
+class FirmwareInfo {
+    /**
+     * Creates a FirmwareInfo instance from a dictionary object.
+     *
+     * Normalizes property names from both camelCase and snake_case formats to ensure
+     * consistent access regardless of API response format. Uses Object.create() instead
+     * of a constructor to allow static factory pattern.
+     *
+     * @static
+     * @param {Object} jsonDict - Raw API response object with any key format
+     * @param {string} [jsonDict.wifiMac] - WiFi MAC address (camelCase)
+     * @param {string} [jsonDict.wifi_mac] - WiFi MAC address (snake_case)
+     * @param {string} [jsonDict.version] - Firmware version
+     * @param {string} [jsonDict.userId] - User ID (camelCase)
+     * @param {string} [jsonDict.user_id] - User ID (snake_case)
+     * @param {string} [jsonDict.server] - Server address
+     * @param {number} [jsonDict.port] - Port number
+     * @param {string} [jsonDict.innerIp] - Inner IP address (camelCase)
+     * @param {string} [jsonDict.inner_ip] - Inner IP address (snake_case)
+     * @param {string} [jsonDict.compileTime] - Compile time (camelCase)
+     * @param {string} [jsonDict.compile_time] - Compile time (snake_case)
+     * @returns {FirmwareInfo} New FirmwareInfo instance
+     */
+    static fromDict(jsonDict) {
+        if (!jsonDict || typeof jsonDict !== 'object') {
+            return null;
+        }
+
+        // Map camelCase keys to their possible API variants (camelCase, snake_case)
+        const propertyMappings = {
+            wifiMac: ['wifiMac', 'wifi_mac'],
+            version: ['version'],
+            userId: ['userId', 'user_id'],
+            server: ['server'],
+            port: ['port'],
+            innerIp: ['innerIp', 'inner_ip'],
+            compileTime: ['compileTime', 'compile_time']
+        };
+
+        // Check each mapping in priority order to find the first non-null value
+        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() to avoid constructor, allowing static factory pattern
+        const instance = Object.create(FirmwareInfo.prototype);
+        instance.wifiMac = normalized.wifiMac || null;
+        instance.version = normalized.version || null;
+        instance.userId = normalized.userId || null;
+        instance.server = normalized.server || null;
+        instance.port = normalized.port || null;
+        instance.innerIp = normalized.innerIp || null;
+        instance.compileTime = normalized.compileTime || null;
+
+        return instance;
+    }
+
+    /**
+     * Converts the instance to a plain object dictionary with camelCase keys.
+     *
+     * @returns {Object} Plain object with camelCase property keys
+     */
+    toDict() {
+        return {
+            wifiMac: this.wifiMac,
+            version: this.version,
+            userId: this.userId,
+            server: this.server,
+            port: this.port,
+            innerIp: this.innerIp,
+            compileTime: this.compileTime
+        };
+    }
+}
+
+/**
+ * Represents time information from device binding data.
+ *
+ * Encapsulates time metadata from device binding notifications. The API may return
+ * properties in either camelCase or snake_case format, so this class normalizes them
+ * to camelCase for consistent access.
+ *
+ * @class
+ * @example
+ * // Use fromDict() to create instances
+ * const timeInfo = TimeInfo.fromDict({
+ *     timezone: 'America/New_York',
+ *     timestamp: 1234567890,
+ *     time_rule: 'DST'
+ * });
+ */
+class TimeInfo {
+    /**
+     * Creates a TimeInfo instance from a dictionary object.
+     *
+     * Normalizes property names from both camelCase and snake_case formats to ensure
+     * consistent access regardless of API response format. Uses Object.create() instead
+     * of a constructor to allow static factory pattern.
+     *
+     * @static
+     * @param {Object} jsonDict - Raw API response object with any key format
+     * @param {string} [jsonDict.timezone] - Timezone string
+     * @param {number} [jsonDict.timestamp] - Unix timestamp
+     * @param {string} [jsonDict.timeRule] - Time rule (camelCase)
+     * @param {string} [jsonDict.time_rule] - Time rule (snake_case)
+     * @returns {TimeInfo} New TimeInfo instance
+     */
+    static fromDict(jsonDict) {
+        if (!jsonDict || typeof jsonDict !== 'object') {
+            return null;
+        }
+
+        // Map camelCase keys to their possible API variants (camelCase, snake_case)
+        const propertyMappings = {
+            timezone: ['timezone'],
+            timestamp: ['timestamp'],
+            timeRule: ['timeRule', 'time_rule']
+        };
+
+        // Check each mapping in priority order to find the first non-null value
+        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() to avoid constructor, allowing static factory pattern
+        const instance = Object.create(TimeInfo.prototype);
+        instance.timezone = normalized.timezone || null;
+        instance.timestamp = normalized.timestamp || null;
+        instance.timeRule = normalized.timeRule || null;
+
+        return instance;
+    }
+
+    /**
+     * Converts the instance to a plain object dictionary with camelCase keys.
+     *
+     * @returns {Object} Plain object with camelCase property keys
+     */
+    toDict() {
+        return {
+            timezone: this.timezone,
+            timestamp: this.timestamp,
+            timeRule: this.timeRule
+        };
+    }
+}
+
+module.exports = {
+    HardwareInfo,
+    FirmwareInfo,
+    TimeInfo
+};

package/lib/model/push/diffuser-light.js

@@ -0,0 +1,100 @@
+'use strict';
+
+const GenericPushNotification = require('./generic');
+
+/**
+ * Push notification for diffuser light state changes.
+ *
+ * Emitted when a diffuser device's light settings change (on/off, mode, color, brightness).
+ * Contains the updated light state for one or more channels.
+ *
+ * @class
+ * @extends GenericPushNotification
+ * @example
+ * device.on('pushNotification', (notification) => {
+ *     if (notification instanceof DiffuserLightPushNotification) {
+ *         const lightData = notification.lightData;
+ *         lightData.forEach(light => {
+ *             console.log(`Channel ${light.channel} light is ${light.onoff === 1 ? 'on' : 'off'}`);
+ *         });
+ *     }
+ * });
+ */
+class DiffuserLightPushNotification extends GenericPushNotification {
+    /**
+     * Creates a new DiffuserLightPushNotification 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.light] - Light state data (single object or array)
+     * @param {number} [rawData.light.channel] - Channel number
+     * @param {number} [rawData.light.onoff] - On/off state (0=off, 1=on)
+     * @param {number} [rawData.light.mode] - Light mode
+     * @param {number} [rawData.light.rgb] - RGB color value
+     * @param {number} [rawData.light.luminance] - Brightness value
+     */
+    constructor(originatingDeviceUuid, rawData) {
+        super('Appliance.Control.Diffuser.Light', originatingDeviceUuid, rawData);
+
+        // Devices may send single objects or arrays; normalize to array for consistent processing
+        const lightRaw = rawData?.light;
+        const light = GenericPushNotification.normalizeToArray(lightRaw);
+
+        // Update rawData so routing logic receives normalized structure
+        if (rawData && lightRaw !== light) {
+            rawData.light = light;
+        }
+
+        this._lightData = light;
+    }
+
+    /**
+     * Gets the light state data array.
+     *
+     * @returns {Array} Array of light state objects (empty array if no data)
+     */
+    get lightData() {
+        return this._lightData;
+    }
+
+    /**
+     * Extracts diffuser light changes from this notification.
+     *
+     * Converts raw device data format (onoff, mode, rgb, luminance) to normalized change
+     * format used by subscription managers. Maps onoff (0/1) to boolean isOn for consistency.
+     *
+     * @returns {Object} Changes object with light state, e.g., { diffuserLight: { 0: {...} } }
+     */
+    extractChanges() {
+        const changes = {};
+        if (!this._lightData || this._lightData.length === 0) {
+            return changes;
+        }
+
+        changes.diffuserLight = {};
+        this._lightData.forEach(item => {
+            const channel = item.channel !== undefined ? item.channel : 0;
+            const lightChange = {};
+            if (item.onoff !== undefined) {
+                lightChange.isOn = item.onoff === 1;
+            }
+            if (item.mode !== undefined) {
+                lightChange.mode = item.mode;
+            }
+            if (item.rgb !== undefined) {
+                lightChange.rgb = item.rgb;
+            }
+            if (item.luminance !== undefined) {
+                lightChange.luminance = item.luminance;
+            }
+            if (Object.keys(lightChange).length > 0) {
+                changes.diffuserLight[channel] = lightChange;
+            }
+        });
+
+        return changes;
+    }
+}
+
+module.exports = DiffuserLightPushNotification;
+

package/lib/model/push/diffuser-spray.js

@@ -0,0 +1,83 @@
+'use strict';
+
+const GenericPushNotification = require('./generic');
+
+/**
+ * Push notification for diffuser spray state changes.
+ *
+ * Emitted when a diffuser device's spray mode changes.
+ * Contains the updated spray state for one or more channels.
+ *
+ * @class
+ * @extends GenericPushNotification
+ * @example
+ * device.on('pushNotification', (notification) => {
+ *     if (notification instanceof DiffuserSprayPushNotification) {
+ *         const sprayData = notification.sprayData;
+ *         sprayData.forEach(spray => {
+ *             console.log(`Channel ${spray.channel} spray mode: ${spray.mode}`);
+ *         });
+ *     }
+ * });
+ */
+class DiffuserSprayPushNotification extends GenericPushNotification {
+    /**
+     * Creates a new DiffuserSprayPushNotification 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.spray] - Spray state data (single object or array)
+     * @param {number} [rawData.spray.channel] - Channel number
+     * @param {number} [rawData.spray.mode] - Spray mode value
+     */
+    constructor(originatingDeviceUuid, rawData) {
+        super('Appliance.Control.Diffuser.Spray', originatingDeviceUuid, rawData);
+
+        // Devices may send single objects or arrays; normalize to array for consistent processing
+        const sprayRaw = rawData?.spray;
+        const spray = GenericPushNotification.normalizeToArray(sprayRaw);
+
+        // Update rawData so routing logic receives normalized structure
+        if (rawData && sprayRaw !== spray) {
+            rawData.spray = spray;
+        }
+
+        this._sprayData = spray;
+    }
+
+    /**
+     * Gets the spray state data array.
+     *
+     * @returns {Array} Array of spray state objects (empty array if no data)
+     */
+    get sprayData() {
+        return this._sprayData;
+    }
+
+    /**
+     * Extracts diffuser spray changes from this notification.
+     *
+     * Converts raw device data format to normalized change format used by subscription managers.
+     *
+     * @returns {Object} Changes object with spray state, e.g., { diffuserSpray: { 0: { mode: 1 } } }
+     */
+    extractChanges() {
+        const changes = {};
+        if (!this._sprayData || this._sprayData.length === 0) {
+            return changes;
+        }
+
+        changes.diffuserSpray = {};
+        this._sprayData.forEach(item => {
+            const channel = item.channel !== undefined ? item.channel : 0;
+            if (item.mode !== undefined) {
+                changes.diffuserSpray[channel] = { mode: item.mode };
+            }
+        });
+
+        return changes;
+    }
+}
+
+module.exports = DiffuserSprayPushNotification;
+

package/lib/model/push/factory.js

@@ -0,0 +1,229 @@
+'use strict';
+
+const GenericPushNotification = require('./generic');
+const OnlinePushNotification = require('./online');
+const AlarmPushNotification = require('./alarm');
+const BindPushNotification = require('./bind');
+const UnbindPushNotification = require('./unbind');
+const WaterLeakPushNotification = require('./water-leak');
+const HubOnlinePushNotification = require('./hub-online');
+const HubToggleXPushNotification = require('./hub-togglex');
+const HubBatteryPushNotification = require('./hub-battery');
+const HubSensorAllPushNotification = require('./hub-sensor-all');
+const HubSensorTempHumPushNotification = require('./hub-sensor-temphum');
+const HubSensorAlertPushNotification = require('./hub-sensor-alert');
+const HubSensorSmokePushNotification = require('./hub-sensor-smoke');
+const HubMts100AllPushNotification = require('./hub-mts100-all');
+const HubMts100ModePushNotification = require('./hub-mts100-mode');
+const HubMts100TemperaturePushNotification = require('./hub-mts100-temperature');
+const HubSubdeviceListPushNotification = require('./hub-subdevicelist');
+const SensorLatestXPushNotification = require('./sensor-latestx');
+const TimerXPushNotification = require('./timerx');
+const TriggerXPushNotification = require('./triggerx');
+const ToggleXPushNotification = require('./togglex');
+const PresenceStudyPushNotification = require('./presence-study');
+const DiffuserLightPushNotification = require('./diffuser-light');
+const DiffuserSprayPushNotification = require('./diffuser-spray');
+
+const PUSH_NOTIFICATION_BINDING = {
+    'Appliance.System.Online': OnlinePushNotification,
+    'Appliance.Control.Alarm': AlarmPushNotification,
+    'Appliance.Control.Bind': BindPushNotification,
+    'Appliance.Control.Unbind': UnbindPushNotification,
+    'Appliance.Control.ToggleX': ToggleXPushNotification,
+    'Appliance.Control.TimerX': TimerXPushNotification,
+    'Appliance.Control.TriggerX': TriggerXPushNotification,
+    'Appliance.Hub.Sensor.WaterLeak': WaterLeakPushNotification,
+    'Appliance.Hub.Online': HubOnlinePushNotification,
+    'Appliance.Hub.ToggleX': HubToggleXPushNotification,
+    'Appliance.Hub.Battery': HubBatteryPushNotification,
+    'Appliance.Hub.Sensor.All': HubSensorAllPushNotification,
+    'Appliance.Hub.Sensor.TempHum': HubSensorTempHumPushNotification,
+    'Appliance.Hub.Sensor.Alert': HubSensorAlertPushNotification,
+    'Appliance.Hub.Sensor.Smoke': HubSensorSmokePushNotification,
+    'Appliance.Hub.Mts100.All': HubMts100AllPushNotification,
+    'Appliance.Hub.Mts100.Mode': HubMts100ModePushNotification,
+    'Appliance.Hub.Mts100.Temperature': HubMts100TemperaturePushNotification,
+    'Appliance.Hub.SubdeviceList': HubSubdeviceListPushNotification,
+    'Appliance.Control.Sensor.LatestX': SensorLatestXPushNotification,
+    'Appliance.Control.Presence.Study': PresenceStudyPushNotification,
+    'Appliance.Control.Diffuser.Light': DiffuserLightPushNotification,
+    'Appliance.Control.Diffuser.Spray': DiffuserSprayPushNotification
+};
+
+/**
+ * Maps hub notification namespaces to their corresponding data keys in raw payloads.
+ *
+ * Hub notifications use different top-level keys in their payloads (e.g., 'online', 'togglex', 'battery').
+ * This mapping allows extraction of the correct data array for routing to subdevices.
+ */
+const HUB_NAMESPACE_DATA_KEY_MAP = {
+    'Appliance.Hub.Online': 'online',
+    'Appliance.Hub.ToggleX': 'togglex',
+    'Appliance.Hub.Battery': 'battery',
+    'Appliance.Hub.Sensor.All': 'all',
+    'Appliance.Hub.Sensor.TempHum': 'tempHum',
+    'Appliance.Hub.Sensor.Alert': 'alert',
+    'Appliance.Hub.Sensor.Smoke': 'smokeAlarm',
+    'Appliance.Hub.Sensor.WaterLeak': 'waterLeak',
+    'Appliance.Hub.Mts100.All': 'all',
+    'Appliance.Hub.Mts100.Mode': 'mode',
+    'Appliance.Hub.Mts100.Temperature': 'temperature',
+    'Appliance.Hub.SubdeviceList': 'subdeviceList',
+    'Appliance.Control.Sensor.LatestX': 'latest'
+};
+
+/**
+ * Strategy functions for extracting data arrays from raw payloads.
+ *
+ * Some hub notifications have non-standard data structures that don't follow the standard
+ * namespace-to-key mapping. These strategies handle special cases like nested structures
+ * or inconsistent property names. Data normalization (single object to array) happens
+ * at parse time in constructors.
+ */
+const DATA_EXTRACTION_STRATEGIES = {
+    /**
+     * Extracts subdevice list data.
+     *
+     * Handles the inconsistent structure where subdevices may be nested in a 'subdevice'
+     * property or directly in 'subdeviceList'.
+     */
+    'Appliance.Hub.SubdeviceList': (rawData) => {
+        if (rawData.subdeviceList) {
+            return rawData.subdeviceList.subdevice || rawData.subdeviceList;
+        }
+        return rawData.subdeviceList;
+    }
+};
+
+/**
+ * Parses a push notification from raw MQTT message data.
+ *
+ * Factory function that instantiates the appropriate notification class based on namespace.
+ * Falls back to GenericPushNotification if no specific class exists or if instantiation fails,
+ * ensuring all notifications can be handled even for unknown or malformed payloads.
+ *
+ * @param {string} namespace - The namespace of the push notification (e.g., 'Appliance.Control.ToggleX')
+ * @param {Object} messagePayload - The raw message payload from MQTT
+ * @param {string} deviceUuid - The UUID of the device that originated the notification
+ * @returns {GenericPushNotification|null} The parsed notification object, or null if invalid
+ * @example
+ * const notification = parsePushNotification(
+ *     'Appliance.Control.ToggleX',
+ *     { togglex: [{ channel: 0, onoff: 1 }] },
+ *     'device-uuid-123'
+ * );
+ * if (notification instanceof ToggleXPushNotification) {
+ *     console.log('Toggle state changed');
+ * }
+ */
+function parsePushNotification(namespace, messagePayload, deviceUuid) {
+    if (!namespace || typeof namespace !== 'string') {
+        return null;
+    }
+
+    if (!deviceUuid || typeof deviceUuid !== 'string') {
+        return null;
+    }
+
+    const NotificationClass = PUSH_NOTIFICATION_BINDING[namespace];
+
+    if (NotificationClass) {
+        try {
+            return new NotificationClass(deviceUuid, messagePayload);
+        } catch (error) {
+            // Fall back to generic notification if specific class fails to parse
+            return new GenericPushNotification(namespace, deviceUuid, messagePayload);
+        }
+    }
+
+    // Return generic notification for unmapped namespaces (unknown notification types)
+    return new GenericPushNotification(namespace, deviceUuid, messagePayload);
+}
+
+/**
+ * Extracts the data array from a raw payload based on namespace.
+ *
+ * Uses namespace-specific extraction strategies for non-standard structures, otherwise
+ * falls back to the standard data key mapping. Returns null if extraction fails.
+ *
+ * @param {string} namespace - The namespace of the push notification
+ * @param {Object} rawData - The raw data payload
+ * @returns {Array|null} Data array or null if extraction fails
+ * @private
+ */
+function extractDataArray(namespace, rawData) {
+    // Check for custom extraction strategy first (handles non-standard structures)
+    const extractionStrategy = DATA_EXTRACTION_STRATEGIES[namespace];
+    if (extractionStrategy) {
+        return extractionStrategy(rawData);
+    }
+
+    // Fall back to standard namespace-to-key mapping
+    const dataKey = HUB_NAMESPACE_DATA_KEY_MAP[namespace];
+    if (!dataKey) {
+        return null;
+    }
+
+    return rawData[dataKey];
+}
+
+/**
+ * Routes a hub push notification to the appropriate subdevices.
+ *
+ * Extracts subdevice data from a hub notification and forwards it to the corresponding
+ * subdevice instances. Each subdevice processes the notification asynchronously via
+ * handleSubdeviceNotification. Skips unregistered subdevices and logs warnings.
+ *
+ * @param {GenericPushNotification} notification - The push notification instance
+ * @param {MerossHubDevice} hubDevice - The hub device instance
+ * @example
+ * const notification = parsePushNotification(namespace, payload, hubUuid);
+ * if (notification.namespace.startsWith('Appliance.Hub.')) {
+ *     routeToSubdevices(notification, hubDevice);
+ * }
+ */
+function routeToSubdevices(notification, hubDevice) {
+    if (!notification || !hubDevice || typeof hubDevice.getSubdevice !== 'function') {
+        return;
+    }
+
+    const { namespace } = notification;
+    const rawData = notification.rawData || {};
+
+    // Extract data array using namespace-specific extraction logic
+    const dataArray = extractDataArray(namespace, rawData);
+
+    if (!Array.isArray(dataArray)) {
+        return;
+    }
+
+    for (const item of dataArray) {
+        // Handle inconsistent subdevice ID field names across notification types
+        const subdeviceId = item.subId || item.id;
+        if (!subdeviceId) {
+            continue;
+        }
+
+        const subdevice = hubDevice.getSubdevice(subdeviceId);
+        if (!subdevice) {
+            const logger = hubDevice.cloudInst?.options?.logger || console.warn;
+            logger(`Received update for subdevice (id ${subdeviceId}) that has not been registered with hub ${hubDevice.uuid}. Update will be skipped.`);
+            continue;
+        }
+
+        // Process asynchronously and catch errors to prevent one failure from blocking others
+        if (typeof subdevice.handleSubdeviceNotification === 'function') {
+            subdevice.handleSubdeviceNotification(namespace, item).catch(err => {
+                const logger = hubDevice.cloudInst?.options?.logger || console.error;
+                logger(`Error routing hub ${namespace} notification to subdevice ${subdeviceId}: ${err.message}`);
+            });
+        }
+    }
+}
+
+module.exports = {
+    parsePushNotification,
+    routeToSubdevices
+};
+