meross-iot 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -5,7 +5,37 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.3.0] - 2026-01-15
+
+### Changed
+- **BREAKING**: Renamed core classes to follow Manager-prefix naming pattern
+  - `MerossManager` → `ManagerMeross` (all imports/exports)
+  - `SubscriptionManager` → `ManagerSubscription` (all imports/exports)
+- **BREAKING**: Replaced method-based access with property-based access patterns
+  - Removed `getSubscriptionManager()` method - use `meross.subscription` property instead
+  - Removed wrapper methods - use `meross.devices.*` instead:
+    - `getDevice(uuid)` → `meross.devices.get(uuid)`
+    - `findDevices(filters)` → `meross.devices.find(filters)`
+    - `getAllDevices()` → `meross.devices.list()`
+- **BREAKING**: Unified device lookup API in DeviceRegistry
+  - Removed `lookupByUuid()` and `lookupByInternalId()` from public API
+  - Added unified `get(identifier)` method that handles both base devices and subdevices:
+    - Base devices: `meross.devices.get('device-uuid')`
+    - Subdevices: `meross.devices.get({ hubUuid: 'hub-uuid', id: 'subdevice-id' })`
+- **BREAKING**: Renamed DeviceRegistry methods for cleaner API
+  - `getAllDevices()` → `list()` (returns all devices)
+  - `findDevices(filters)` → `find(filters)` (search/filter devices)
+
+### Added
+- Property access to subscription manager: `meross.subscription` returns `ManagerSubscription` instance
+- Property access to device registry: `meross.devices` returns `DeviceRegistry` instance with full API access
+- Unified `get()` method in DeviceRegistry supporting both base devices and subdevices
+- Constructor option `subscription` for configuring subscription manager during initialization
+
+## [0.2.1] - 2026-01-14
+
+### Fixed
+- Fixed syntax error in `example/device-control.js` - missing closing brace for `deviceInitialized` event handler
 
 ## [0.2.0] - 2026-01-14
 

package/README.md

@@ -26,7 +26,7 @@ The library can control devices locally via HTTP or via cloud MQTT server.
 npm install meross-iot@alpha
 
 # Or install specific version
-npm install meross-iot@0.1.0
+npm install meross-iot@0.3.0
 ```
 
 ## Usage & Documentation
@@ -36,7 +36,7 @@ Refer to the [example/README.md](example/README.md) for detailed usage instructi
 If you are really impatient to use this library, refer to the following snippet of code that looks for a device and turns it on/off.
 
 ```javascript
-const { MerossManager, MerossHttpClient } = require('meross-iot');
+const { ManagerMeross, MerossHttpClient } = require('meross-iot');
 
 (async () => {
   // Create HTTP client using factory method
@@ -46,7 +46,7 @@ const { MerossManager, MerossHttpClient } = require('meross-iot');
   });
 
   // Create manager with HTTP client
-  const meross = new MerossManager({
+  const meross = new ManagerMeross({
     httpClient: httpClient
   });
 
@@ -59,7 +59,7 @@ const { MerossManager, MerossHttpClient } = require('meross-iot');
   await meross.connect();
   
   // Find a device and control it
-  const devices = meross.getAllDevices();
+  const devices = meross.devices.list();
   if (devices.length > 0) {
     const device = devices[0];
     
@@ -75,7 +75,7 @@ The `example/` directory contains focused examples for different use cases:
 - **`basic-usage.js`** - Simple connection and device discovery
 - **`device-control.js`** - Controlling switches, lights, and monitoring devices
 - **`event-handling.js`** - Handling events from devices and the manager
-- **`subscription-manager.js`** - Automatic polling and unified update streams with SubscriptionManager
+- **`subscription-manager.js`** - Automatic polling and unified update streams with ManagerSubscription
 - **`token-reuse.js`** - Saving and reusing authentication tokens
 - **`statistics.js`** - Enabling and viewing API call statistics
 - **`error-handling.js`** - Comprehensive error handling and MFA
@@ -120,6 +120,54 @@ Please create an issue on GitHub and include:
 
 ## Changelog
 
+### [0.3.0] - 2026-01-15
+
+#### Changed
+- **BREAKING**: Renamed core classes to follow Manager-prefix naming pattern
+  - `MerossManager` → `ManagerMeross` (all imports/exports)
+  - `SubscriptionManager` → `ManagerSubscription` (all imports/exports)
+- **BREAKING**: Replaced method-based access with property-based access patterns
+  - Removed `getSubscriptionManager()` method - use `meross.subscription` property instead
+  - Removed wrapper methods - use `meross.devices.*` instead:
+    - `getDevice(uuid)` → `meross.devices.get(uuid)`
+    - `findDevices(filters)` → `meross.devices.find(filters)`
+    - `getAllDevices()` → `meross.devices.list()`
+- **BREAKING**: Unified device lookup API in DeviceRegistry
+  - Removed `lookupByUuid()` and `lookupByInternalId()` from public API
+  - Added unified `get(identifier)` method that handles both base devices and subdevices:
+    - Base devices: `meross.devices.get('device-uuid')`
+    - Subdevices: `meross.devices.get({ hubUuid: 'hub-uuid', id: 'subdevice-id' })`
+- **BREAKING**: Renamed DeviceRegistry methods for cleaner API
+  - `getAllDevices()` → `list()` (returns all devices)
+  - `findDevices(filters)` → `find(filters)` (search/filter devices)
+
+#### Added
+- Property access to subscription manager: `meross.subscription` returns `ManagerSubscription` instance
+- Property access to device registry: `meross.devices` returns `DeviceRegistry` instance with full API access
+- Unified `get()` method in DeviceRegistry supporting both base devices and subdevices
+- Constructor option `subscription` for configuring subscription manager during initialization
+
+### [0.2.1] - 2026-01-14
+
+#### Fixed
+- Fixed syntax error in `device-control.js` example - missing closing brace for `deviceInitialized` event handler
+
+### [0.2.0] - 2026-01-14
+
+#### Changed
+- **BREAKING**: `SubscriptionManager` now uses EventEmitter pattern instead of callbacks
+  - `subscribe(device, config, onUpdate)` → `subscribe(device, config)` (no callback, no return value)
+  - `unsubscribe(deviceUuid, subscriptionId)` → `unsubscribe(deviceUuid)` (no subscription ID needed)
+  - `subscribeToDeviceList(onUpdate)` → `subscribeToDeviceList()` (no callback, no return value)
+  - `unsubscribeFromDeviceList(subscriptionId)` → `unsubscribeFromDeviceList()` (no subscription ID needed)
+  - Listen for updates using: `on('deviceUpdate:${deviceUuid}', handler)` and `on('deviceListUpdate', handler)`
+  - Use standard EventEmitter methods: `on()`, `once()`, `off()`, `removeAllListeners()`
+  - Configuration is now per-device subscription (merged aggressively) rather than per-listener
+
+#### Added
+- `subscription-manager.js` example demonstrating EventEmitter-based SubscriptionManager usage
+- Enhanced documentation for SubscriptionManager with JSDoc comments explaining implementation rationale
+
 ### [0.1.0] - 2026-01-10
 
 #### Added

package/index.d.ts

@@ -436,7 +436,7 @@ declare module 'meross-iot' {
     }
 
     /**
-     * Configuration options for MerossManager cloud manager.
+     * Configuration options for ManagerMeross cloud manager.
      * 
      * @example
      * ```typescript
@@ -445,7 +445,7 @@ declare module 'meross-iot' {
      *   password: 'password'
      * });
      * 
-     * const manager = new MerossManager({
+     * const manager = new ManagerMeross({
      *   httpClient,
      *   transportMode: TransportMode.LAN_HTTP_FIRST,
      *   logger: console.log
@@ -476,7 +476,9 @@ declare module 'meross-iot' {
         /** Delay in milliseconds between batches (default: 200) */
         requestBatchDelay?: number,
         /** Enable/disable request throttling (default: true) */
-        enableRequestThrottling?: boolean
+        enableRequestThrottling?: boolean,
+        /** Subscription manager options for automatic polling and data provisioning */
+        subscription?: ManagerSubscriptionOptions
     }
 
     export interface LightData {
@@ -1115,18 +1117,18 @@ declare module 'meross-iot' {
     /**
      * Filter options for finding devices.
      * 
-     * Used with MerossManager.findDevices() to filter the device list.
+     * Used with DeviceRegistry.find() to filter the device list.
      * 
      * @example
      * ```typescript
      * // Find online devices
-     * const onlineDevices = manager.findDevices({ online_status: 1 });
+     * const onlineDevices = manager.devices.find({ online_status: 1 });
      * 
      * // Find specific device types
-     * const plugs = manager.findDevices({ device_type: 'mss310' });
+     * const plugs = manager.devices.find({ device_type: 'mss310' });
      * 
      * // Find by custom filter function
-     * const customDevices = manager.findDevices({
+     * const customDevices = manager.devices.find({
      *   device_class: (device) => device.deviceType.startsWith('mss')
      * });
      * ```
@@ -1146,6 +1148,102 @@ declare module 'meross-iot' {
         device_class?: string | ((device: MerossDevice) => boolean) | Array<string | ((device: MerossDevice) => boolean)>;
     }
 
+    /**
+     * Registry for managing Meross devices and subdevices.
+     * 
+     * Maintains indexes for efficient device lookups across base devices and subdevices.
+     * Base devices can be looked up by UUID, while internal IDs enable unified lookup
+     * for both base devices and subdevices.
+     * 
+     * Internal IDs unify device identification:
+     * - Base devices: `#BASE:{uuid}`
+     * - Subdevices: `#SUB:{hubUuid}:{subdeviceId}`
+     * 
+     * @example
+     * ```typescript
+     * // Look up device by UUID
+     * const device = manager.devices.get('device-uuid');
+     * 
+     * // Look up subdevice by hub UUID and subdevice ID
+     * const subdevice = manager.devices.get({ hubUuid: 'hub-uuid', id: 'subdevice-id' });
+     * 
+     * // Find devices matching filters
+     * const lights = manager.devices.find({ device_class: 'light' });
+     * 
+     * // Get all devices
+     * const allDevices = manager.devices.list();
+     * ```
+     */
+    export class DeviceRegistry {
+        /**
+         * Generates an internal ID for a device or subdevice.
+         * 
+         * @param uuid - Device UUID (for base devices) or hub UUID (for subdevices)
+         * @param isSubdevice - Whether this is a subdevice
+         * @param hubUuid - Hub UUID (required if isSubdevice is true)
+         * @param subdeviceId - Subdevice ID (required if isSubdevice is true)
+         * @returns Internal ID string
+         */
+        static generateInternalId(uuid: string, isSubdevice?: boolean, hubUuid?: string | null, subdeviceId?: string | null): string
+        
+        /**
+         * Registers a device in the registry.
+         * 
+         * @param device - Device instance to register
+         */
+        registerDevice(device: MerossDevice | MerossHubDevice | MerossSubDevice): void
+        
+        /**
+         * Removes a device from the registry.
+         * 
+         * @param device - Device instance to remove
+         */
+        removeDevice(device: MerossDevice | MerossHubDevice | MerossSubDevice): void
+        
+        /**
+         * Unified method to get a device by identifier.
+         * 
+         * Supports both base devices (by UUID string) and subdevices (by object with hubUuid and id).
+         * Internally converts the identifier to an internal ID format and performs the lookup.
+         * 
+         * @param identifier - Device identifier
+         * @returns Device instance, or null if not found
+         * @example
+         * // Get base device by UUID
+         * const device = registry.get('device-uuid');
+         * 
+         * @example
+         * // Get subdevice by hub UUID and subdevice ID
+         * const subdevice = registry.get({ hubUuid: 'hub-uuid', id: 'subdevice-id' });
+         */
+        get(identifier: string | { hubUuid: string; id: string }): MerossDevice | MerossHubDevice | MerossSubDevice | null
+        
+        /**
+         * Gets all registered devices.
+         * 
+         * @returns Array of all registered devices
+         */
+        list(): Array<MerossDevice | MerossHubDevice | MerossSubDevice>
+        
+        /**
+         * Finds devices matching the specified filters.
+         * 
+         * @param filters - Optional filter criteria
+         * @returns Array of matching devices
+         */
+        find(filters?: FindDevicesFilters): Array<MerossDevice | MerossHubDevice | MerossSubDevice>
+        
+        /**
+         * Clears all devices from the registry.
+         */
+        clear(): void
+        
+        /**
+         * Gets the total number of devices registered (including subdevices).
+         */
+        readonly size: number
+    }
+
     // Statistics types
     export class HttpRequestSample {
         readonly url: string;
@@ -1335,9 +1433,9 @@ declare module 'meross-iot' {
         isStatsEnabled(): boolean;
     }
 
-    export function createDebugUtils(manager: MerossManager): DebugUtils;
+    export function createDebugUtils(manager: ManagerMeross): DebugUtils;
 
-    export interface SubscriptionManagerOptions {
+    export interface ManagerSubscriptionOptions {
         /** Logger function for debug output */
         logger?: Logger;
         deviceStateInterval?: number;
@@ -1372,9 +1470,9 @@ declare module 'meross-iot' {
         timestamp: number
     }
 
-    export class SubscriptionManager extends EventEmitter {
-        constructor(manager: MerossManager, options?: SubscriptionManagerOptions);
-        subscribe(device: MerossDevice, config?: SubscriptionManagerOptions): void;
+    export class ManagerSubscription extends EventEmitter {
+        constructor(manager: ManagerMeross, options?: ManagerSubscriptionOptions);
+        subscribe(device: MerossDevice, config?: ManagerSubscriptionOptions): void;
         unsubscribe(deviceUuid: string): void;
         subscribeToDeviceList(): void;
         unsubscribeFromDeviceList(): void;
@@ -1399,19 +1497,19 @@ declare module 'meross-iot' {
      *   password: 'password'
      * });
      * 
-     * const manager = new MerossManager({ httpClient });
+     * const manager = new ManagerMeross({ httpClient });
      * await manager.connect();
      * 
      * manager.on('deviceInitialized', (deviceId, deviceDef, device) => {
      *   console.log(`Device ${deviceId} initialized`);
      * });
      * 
-     * const devices = manager.getAllDevices();
+     * const devices = manager.devices.list();
      * ```
      */
-    export class MerossManager extends EventEmitter {
+    export class ManagerMeross extends EventEmitter {
         /**
-         * Creates a new MerossManager instance.
+         * Creates a new ManagerMeross instance.
          * 
          * @param options - Configuration options
          */
@@ -1466,35 +1564,6 @@ declare module 'meross-iot' {
          */
         disconnectAll(force: boolean): void
         
-        /**
-         * Gets a device by UUID.
-         * 
-         * @param uuid - Device UUID
-         * @returns Device instance or null if not found
-         */
-        getDevice(uuid: string): MerossDevice | null
-        
-        /**
-         * Finds devices matching the specified filters.
-         * 
-         * @param filters - Optional filter criteria
-         * @returns Array of matching device instances
-         * 
-         * @example
-         * ```typescript
-         * const onlineDevices = manager.findDevices({ online_status: 1 });
-         * const plugs = manager.findDevices({ device_type: 'mss310' });
-         * ```
-         */
-        findDevices(filters?: FindDevicesFilters): MerossDevice[]
-        
-        /**
-         * Gets all initialized devices.
-         * 
-         * @returns Array of all device instances
-         */
-        getAllDevices(): MerossDevice[]
-        
         /**
          * Gets the current token data.
          * 
@@ -1504,6 +1573,12 @@ declare module 'meross-iot' {
         
         /** HTTP client instance */
         readonly httpClient: MerossHttpClient
+        
+        /** Subscription manager instance for automatic polling and data provisioning */
+        readonly subscription: ManagerSubscription
+        
+        /** Device registry instance for device lookups and queries */
+        readonly devices: DeviceRegistry
     }
 
 
@@ -1684,7 +1759,7 @@ declare module 'meross-iot' {
      * 
      * @example
      * ```typescript
-     * const device = manager.getDevice('device-uuid');
+     * const device = manager.devices.get('device-uuid');
      * 
      * device.on('connected', () => {
      *   console.log('Device connected');
@@ -2359,5 +2434,5 @@ declare module 'meross-iot' {
         mqttDomain?: string
     }): MerossError
 
-    export default MerossManager
+    export default ManagerMeross
 }

package/index.js

@@ -1,14 +1,14 @@
 'use strict';
 
 // Main entry point - re-export everything from new modular structure
-const MerossManager = require('./lib/manager');
+const ManagerMeross = require('./lib/manager');
 const enums = require('./lib/model/enums');
 const errors = require('./lib/model/exception');
 const states = require('./lib/model/states');
 const push = require('./lib/model/push');
 
 // Export main class
-module.exports = MerossManager;
+module.exports = ManagerMeross;
 
 // Export error classes
 const httpExceptions = require('./lib/model/http/exception');
@@ -126,6 +126,6 @@ module.exports.HubSmokeDetector = subdevice.HubSmokeDetector;
 const MerossHttpClient = require('./lib/http-api');
 module.exports.MerossHttpClient = MerossHttpClient;
 
-// Export SubscriptionManager class
-const SubscriptionManager = require('./lib/subscription');
-module.exports.SubscriptionManager = SubscriptionManager;
+// Export ManagerSubscription class
+const ManagerSubscription = require('./lib/subscription');
+module.exports.ManagerSubscription = ManagerSubscription;

package/lib/controller/device.js

@@ -3,8 +3,8 @@
 const EventEmitter = require('events');
 const { OnlineStatus } = require('../model/enums');
 const { parsePushNotification } = require('../model/push');
-// DeviceRegistry is nested in MerossManager but exported separately to avoid circular dependencies
-const { MerossManager } = require('../manager');
+// DeviceRegistry is nested in ManagerMeross but exported separately to avoid circular dependencies
+const { ManagerMeross } = require('../manager');
 const ChannelInfo = require('../model/channel-info');
 const HttpDeviceInfo = require('../model/http/device');
 const {
@@ -299,7 +299,7 @@ class MerossDevice extends EventEmitter {
             throw new UnknownDeviceTypeError('Cannot generate internal ID: device missing UUID');
         }
 
-        this._internalId = MerossManager.DeviceRegistry.generateInternalId(this.uuid);
+        this._internalId = ManagerMeross.DeviceRegistry.generateInternalId(this.uuid);
         return this._internalId;
     }
 

package/lib/controller/features/light-feature.js

@@ -307,7 +307,7 @@ module.exports = {
         }
 
         lightPayload.channel = channel;
-        
+
         // Handle gradual transition parameter
         if (gradual !== undefined) {
             // Allow both boolean and number (0/1) for convenience

package/lib/controller/subdevice.js

@@ -2,8 +2,8 @@
 
 const { MerossDevice } = require('./device');
 const { OnlineStatus, SmokeAlarmStatus } = require('../model/enums');
-// DeviceRegistry is nested in MerossManager but exported separately to avoid circular dependencies
-const { MerossManager } = require('../manager');
+// DeviceRegistry is nested in ManagerMeross but exported separately to avoid circular dependencies
+const { ManagerMeross } = require('../manager');
 const { UnknownDeviceTypeError, CommandError } = require('../model/exception');
 
 /**
@@ -42,7 +42,7 @@ class MerossSubDevice extends MerossDevice {
      */
     constructor(hubDeviceUuid, subdeviceId, manager, kwargs = {}) {
         // eslint-disable-next-line camelcase
-        const hubs = manager.findDevices({ device_uuids: [hubDeviceUuid] });
+        const hubs = manager.devices.find({ device_uuids: [hubDeviceUuid] });
         if (!hubs || hubs.length < 1) {
             throw new UnknownDeviceTypeError(`Specified hub device ${hubDeviceUuid} is not present`);
         }
@@ -137,7 +137,7 @@ class MerossSubDevice extends MerossDevice {
             throw new UnknownDeviceTypeError('Cannot generate internal ID: hub missing UUID');
         }
 
-        this._internalId = MerossManager.DeviceRegistry.generateInternalId(hubUuid, true, hubUuid, this._subdeviceId);
+        this._internalId = ManagerMeross.DeviceRegistry.generateInternalId(hubUuid, true, hubUuid, this._subdeviceId);
         return this._internalId;
     }
 

package/lib/manager.js

@@ -34,9 +34,9 @@ const { HttpApiError } = require('./model/http/exception');
  * @class
  * @extends EventEmitter
  */
-class MerossManager extends EventEmitter {
+class ManagerMeross extends EventEmitter {
     /**
-     * Creates a new MerossManager instance
+     * Creates a new ManagerMeross instance
      *
      * @param {Object} options - Configuration options
      * @param {MerossHttpClient} options.httpClient - HTTP client instance (required)
@@ -94,7 +94,7 @@ class MerossManager extends EventEmitter {
 
         this.mqttConnections = {};
         this._mqttConnectionPromises = new Map();
-        this._deviceRegistry = new MerossManager.DeviceRegistry();
+        this._deviceRegistry = new ManagerMeross.DeviceRegistry();
         this._appId = null;
         this.clientResponseTopic = null;
         this._pendingMessagesFutures = new Map();
@@ -104,6 +104,9 @@ class MerossManager extends EventEmitter {
 
         this.httpClient = options.httpClient;
 
+        // Store subscription options from constructor for lazy initialization
+        this._subscriptionOptions = options.subscription || {};
+
         // Reuse authentication from HTTP client if already authenticated to avoid
         // redundant authentication and share credentials between HTTP and MQTT connections
         if (this.httpClient.token) {
@@ -490,51 +493,6 @@ class MerossManager extends EventEmitter {
         return response;
     }
 
-    /**
-     * Gets a device by UUID
-     *
-     * @param {string} uuid - Device UUID
-     * @returns {MerossDevice|MerossHubDevice|undefined} Device instance or undefined if not found
-     */
-    getDevice(uuid) {
-        return this._deviceRegistry.lookupByUuid(uuid);
-    }
-
-    /**
-     * Finds devices matching the specified filters
-     *
-     * @param {Object} [filters={}] - Filter criteria
-     * @param {string[]} [filters.device_uuids] - Array of device UUIDs to match (snake_case to match API)
-     * @param {string[]} [filters.internal_ids] - Array of internal IDs to match
-     * @param {string} [filters.device_type] - Device type to match (e.g., 'mss310')
-     * @param {string} [filters.device_name] - Device name to match
-     * @param {number} [filters.online_status] - Online status to match (from OnlineStatus enum)
-     * @param {string|Function|Array} [filters.device_class] - Device class filter (string, function, or array)
-     * @returns {Array<MerossDevice|MerossHubDevice>} Array of matching devices
-     */
-    findDevices(filters = {}) {
-        return this._deviceRegistry.findDevices(filters);
-    }
-
-    /**
-     * Gets all registered devices
-     *
-     * @returns {Array<MerossDevice|MerossHubDevice>} Array of all devices
-     */
-    getAllDevices() {
-        return this._deviceRegistry.getAllDevices();
-    }
-
-    /**
-     * Gets a device by UUID (internal helper method)
-     *
-     * @param {string} uuid - Device UUID
-     * @returns {MerossDevice|MerossHubDevice|undefined} Device instance or undefined if not found
-     * @private
-     */
-    _getDeviceByUuid(uuid) {
-        return this._deviceRegistry.lookupByUuid(uuid);
-    }
 
     /**
      * Disconnects all devices and closes all MQTT connections
@@ -547,7 +505,7 @@ class MerossManager extends EventEmitter {
      */
     disconnectAll(force) {
         // Retrieve devices before clearing registry to allow queue cleanup
-        const devices = this._deviceRegistry.getAllDevices();
+        const devices = this._deviceRegistry.list();
         this._deviceRegistry.clear();
 
         if (this._requestQueue) {
@@ -650,7 +608,7 @@ class MerossManager extends EventEmitter {
             }
 
             this.mqttConnections[domain].deviceList.forEach(devId => {
-                const device = this._getDeviceByUuid(devId);
+                const device = this._deviceRegistry._devicesByUuid.get(devId) || null;
                 if (device) {
                     device.emit('connected');
                 }
@@ -660,7 +618,7 @@ class MerossManager extends EventEmitter {
         client.on('error', (error) => {
             // MQTT client handles reconnection automatically via reconnectPeriod option
             this.mqttConnections[domain].deviceList.forEach(devId => {
-                const device = this._getDeviceByUuid(devId);
+                const device = this._deviceRegistry._devicesByUuid.get(devId) || null;
                 if (device) {
                     device.emit('error', error ? error.toString() : null);
                 }
@@ -669,7 +627,7 @@ class MerossManager extends EventEmitter {
 
         client.on('close', (error) => {
             this.mqttConnections[domain].deviceList.forEach(devId => {
-                const device = this._getDeviceByUuid(devId);
+                const device = this._deviceRegistry._devicesByUuid.get(devId) || null;
                 if (device) {
                     device.emit('close', error ? error.toString() : null);
                 }
@@ -678,7 +636,7 @@ class MerossManager extends EventEmitter {
 
         client.on('reconnect', () => {
             this.mqttConnections[domain].deviceList.forEach(devId => {
-                const device = this._getDeviceByUuid(devId);
+                const device = this._deviceRegistry._devicesByUuid.get(devId) || null;
                 if (device) {
                     device.emit('reconnect');
                 }
@@ -734,7 +692,7 @@ class MerossManager extends EventEmitter {
 
             if (!message.header.from) {return;}
             const deviceUuid = deviceUuidFromPushNotification(message.header.from);
-            const device = this._getDeviceByUuid(deviceUuid);
+            const device = this._deviceRegistry._devicesByUuid.get(deviceUuid) || null;
             if (device) {
                 device.handleMessage(message);
             }
@@ -831,7 +789,7 @@ class MerossManager extends EventEmitter {
         const topic = buildDeviceRequestTopic(device.uuid);
         this.mqttConnections[domain].client.publish(topic, JSON.stringify(data), undefined, err => {
             if (err) {
-                const deviceObj = this._getDeviceByUuid(device.uuid);
+                const deviceObj = this._deviceRegistry._devicesByUuid.get(device.uuid) || null;
                 if (deviceObj) {
                     deviceObj.emit('error', err);
                 }
@@ -1230,25 +1188,40 @@ class MerossManager extends EventEmitter {
     }
 
     /**
-     * Gets or creates the SubscriptionManager instance
+     * Gets or creates the ManagerSubscription instance
      *
      * Provides automatic polling and data provisioning for devices.
      * Uses lazy initialization to create the manager only when needed.
+     * Merges constructor subscription options with any additional options.
      *
-     * @param {Object} [options={}] - Configuration options for SubscriptionManager
-     * @returns {SubscriptionManager} SubscriptionManager instance
+     * @returns {ManagerSubscription} ManagerSubscription instance
      */
-    getSubscriptionManager(options = {}) {
+    get subscription() {
         if (!this._subscriptionManager) {
-            const SubscriptionManager = require('./subscription');
-            this._subscriptionManager = new SubscriptionManager(this, {
+            const ManagerSubscription = require('./subscription');
+            this._subscriptionManager = new ManagerSubscription(this, {
                 logger: this.options?.logger,
-                ...options
+                ...this._subscriptionOptions
             });
         }
         return this._subscriptionManager;
     }
 
+    /**
+     * Gets the DeviceRegistry instance for device management
+     *
+     * Provides direct access to DeviceRegistry methods for device lookups and queries.
+     * Use this property to access device registry functionality:
+     * - `meross.devices.get(identifier)` - Get a device by UUID or subdevice identifier
+     * - `meross.devices.find(filters)` - Find devices matching filters
+     * - `meross.devices.list()` - Get all registered devices
+     *
+     * @returns {DeviceRegistry} DeviceRegistry instance
+     */
+    get devices() {
+        return this._deviceRegistry;
+    }
+
 }
 
 /**
@@ -1342,29 +1315,38 @@ class DeviceRegistry {
     }
 
     /**
-     * Looks up a device by its internal ID.
+     * Unified method to get a device by identifier.
      *
-     * Uses the unified internal ID format to support lookups for both base devices and subdevices
-     * through a single method, eliminating the need for type-specific lookup logic.
+     * Supports both base devices (by UUID string) and subdevices (by object with hubUuid and id).
+     * Internally converts the identifier to an internal ID format and performs the lookup.
      *
-     * @param {string} internalId - Internal ID (e.g., "#BASE:{uuid}" or "#SUB:{hubUuid}:{subdeviceId}")
+     * @param {string|Object} identifier - Device identifier
+     * @param {string} identifier - For base devices: device UUID string (e.g., 'device-uuid')
+     * @param {Object} identifier - For subdevices: object with hubUuid and id properties
+     * @param {string} identifier.hubUuid - Hub UUID that the subdevice belongs to
+     * @param {string} identifier.id - Subdevice ID
      * @returns {MerossDevice|MerossHubDevice|MerossSubDevice|null} Device instance, or null if not found
-     */
-    lookupByInternalId(internalId) {
-        return this._devicesByInternalId.get(internalId) || null;
-    }
-
-    /**
-     * Looks up a base device by its UUID.
-     *
-     * Provides O(1) lookup for base devices using the UUID index. Subdevices do not have
-     * unique UUIDs and must be looked up by internal ID instead.
+     * @example
+     * // Get base device by UUID
+     * const device = registry.get('device-uuid');
      *
-     * @param {string} uuid - Device UUID
-     * @returns {MerossDevice|MerossHubDevice|null} Device instance, or null if not found
+     * @example
+     * // Get subdevice by hub UUID and subdevice ID
+     * const subdevice = registry.get({ hubUuid: 'hub-uuid', id: 'subdevice-id' });
      */
-    lookupByUuid(uuid) {
-        return this._devicesByUuid.get(uuid) || null;
+    get(identifier) {
+        if (typeof identifier === 'string') {
+            // Base device lookup by UUID
+            return this._devicesByUuid.get(identifier) || null;
+        } else if (identifier && typeof identifier === 'object') {
+            // Subdevice lookup by hubUuid and id
+            const { hubUuid, id } = identifier;
+            if (hubUuid && id) {
+                const internalId = ManagerMeross.DeviceRegistry.generateInternalId(hubUuid, true, hubUuid, id);
+                return this._devicesByInternalId.get(internalId) || null;
+            }
+        }
+        return null;
     }
 
     /**
@@ -1375,7 +1357,7 @@ class DeviceRegistry {
      *
      * @returns {Array<MerossDevice|MerossHubDevice|MerossSubDevice>} Array of all registered devices
      */
-    getAllDevices() {
+    list() {
         return Array.from(this._devicesByInternalId.values());
     }
 
@@ -1398,8 +1380,8 @@ class DeviceRegistry {
      *                                                                  - Function: custom filter function that receives device and returns boolean
      * @returns {Array<MerossDevice|MerossHubDevice|MerossSubDevice>} Array of matching devices
      */
-    findDevices(filters = {}) {
-        let devices = this.getAllDevices();
+    find(filters = {}) {
+        let devices = this.list();
 
         if (filters.device_uuids && Array.isArray(filters.device_uuids) && filters.device_uuids.length > 0) {
             const uuidSet = new Set(filters.device_uuids);
@@ -1513,7 +1495,7 @@ class DeviceRegistry {
                 throw new UnknownDeviceTypeError('Cannot generate internal ID for subdevice: missing hub UUID or subdevice ID');
             }
 
-            const internalId = MerossManager.DeviceRegistry.generateInternalId(hubUuid, true, hubUuid, subdeviceId);
+            const internalId = ManagerMeross.DeviceRegistry.generateInternalId(hubUuid, true, hubUuid, subdeviceId);
             device._internalId = internalId;
             return internalId;
         }
@@ -1523,7 +1505,7 @@ class DeviceRegistry {
             throw new UnknownDeviceTypeError('Cannot generate internal ID: device missing UUID');
         }
 
-        const internalId = MerossManager.DeviceRegistry.generateInternalId(uuid);
+        const internalId = ManagerMeross.DeviceRegistry.generateInternalId(uuid);
         device._internalId = internalId;
         return internalId;
     }
@@ -1551,7 +1533,7 @@ class DeviceRegistry {
      * @returns {void}
      */
     clear() {
-        const devices = this.getAllDevices();
+        const devices = this.list();
         devices.forEach(device => {
             if (device.disconnect) {
                 device.disconnect();
@@ -1571,11 +1553,11 @@ class DeviceRegistry {
     }
 }
 
-// Attach DeviceRegistry as nested class to MerossManager
-MerossManager.DeviceRegistry = DeviceRegistry;
+// Attach DeviceRegistry as nested class to ManagerMeross
+ManagerMeross.DeviceRegistry = DeviceRegistry;
 
 /**
- * Events emitted by MerossManager instance
+ * Events emitted by ManagerMeross instance
  *
  * @typedef {Object} MerossCloudEvents
  * @property {Function} deviceInitialized - Emitted when a device is initialized
@@ -1604,6 +1586,6 @@ MerossManager.DeviceRegistry = DeviceRegistry;
  *   @param {Object} message - Raw message object
  */
 
-module.exports = MerossManager;
+module.exports = ManagerMeross;
 module.exports.DeviceRegistry = DeviceRegistry;
 

package/lib/subscription.js

@@ -12,9 +12,9 @@ const EventEmitter = require('events');
  * @class
  * @extends EventEmitter
  */
-class SubscriptionManager extends EventEmitter {
+class ManagerSubscription extends EventEmitter {
     /**
-     * Creates a new SubscriptionManager instance.
+     * Creates a new ManagerSubscription instance.
      *
      * @param {Object} manager - MerossManager instance that provides device access
      * @param {Object} [options={}] - Configuration options
@@ -184,7 +184,7 @@ class SubscriptionManager extends EventEmitter {
      * Initialize subscription state and register device event handlers.
      *
      * Sets up event listeners on the device to capture push notifications and state
-     * changes, which are then distributed to SubscriptionManager listeners via events.
+     * changes, which are then distributed to ManagerSubscription listeners via events.
      *
      * @private
      * @param {MerossDevice} device - Device to create subscription for
@@ -612,5 +612,5 @@ class SubscriptionManager extends EventEmitter {
 
 }
 
-module.exports = SubscriptionManager;
+module.exports = ManagerSubscription;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "meross-iot",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Control Meross cloud devices using nodejs",
   "author": "Abe Haverkamp",
   "contributors": [