meross-iot 0.3.1 → 0.5.0

package/CHANGELOG.md

@@ -5,6 +5,67 @@ 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).
 
+## [0.5.0] - 2026-01-19
+
+### Changed
+- **BREAKING**: Standardized error handling with MerossError* naming convention
+  - Renamed all error classes to use `MerossError*` prefix for consistency
+    - `AuthenticationError` → `MerossErrorAuthentication`
+    - `ConnectionError` → `MerossErrorConnection`
+    - `DeviceError` → `MerossErrorDevice`
+    - `HttpError` → `MerossErrorHttp`
+    - `MqttError` → `MerossErrorMqtt`
+    - `NetworkError` → `MerossErrorNetwork`
+    - `ProtocolError` → `MerossErrorProtocol`
+    - `TimeoutError` → `MerossErrorTimeout`
+    - `TokenError` → `MerossErrorToken`
+    - `ValidationError` → `MerossErrorValidation`
+  - All error classes now include `code`, `isOperational`, and `cause` properties
+  - Added `toJSON()` method to all error classes for serialization
+  - Updated TypeScript definitions to match new error structure
+  - Updated error-handling example to use new error class names
+- **BREAKING**: Split ManagerMeross into separate lazy-loaded manager modules
+  - Manager methods are now accessed via manager properties instead of direct methods:
+    - `manager.devices` - device discovery and initialization (ManagerDevices)
+    - `manager.mqtt` - MQTT connection management (ManagerMqtt)
+    - `manager.http` - LAN HTTP communication (ManagerHttp)
+    - `manager.transport` - transport mode selection and routing (ManagerTransport)
+    - `manager.statistics` - statistics tracking (ManagerStatistics)
+    - `manager.subscription` - device update subscriptions (ManagerSubscription)
+  - Extracted DeviceRegistry to standalone module
+  - Moved subscription manager to `managers/` directory
+  - Updated all examples and TypeScript definitions for new API
+
+### Added
+- Enhanced error context through error chaining via `cause` property
+- Error serialization support via `toJSON()` method on all error classes
+- Lazy-loaded manager modules for better code organization and performance
+
+## [0.4.0] - 2026-01-16
+
+### Changed
+- **BREAKING**: Renamed `getDevices()` to `initializeDevices()` in `ManagerMeross`
+  - The method name better reflects that it performs full device discovery, initialization, and connection setup, not just retrieval
+  - Updated `login()` and `connect()` to use `initializeDevices()`
+  - Updated all examples and TypeScript definitions
+- **BREAKING**: Simplified device API by establishing single source of truth
+  - Removed `deviceDef` parameter from `deviceInitialized` event - now just `(deviceId, device)`
+  - Removed `cachedHttpInfo` property; all properties are now directly accessible on `MerossDevice`
+  - Converted simple getters to direct properties (`macAddress`, `lanIp`, `mqttHost`, etc.)
+  - Updated all feature files to use public properties (`abilities`, `lastFullUpdateTimestamp`)
+  - Removed unnecessary defensive fallback patterns (`device.dev?.uuid` → `device.uuid`)
+  - Fixed subdevice property consistency
+- **BREAKING**: Removed snake_case handling, standardized on camelCase
+  - Removed snake_case property mappings from `HttpDeviceInfo`, `HttpSubdeviceInfo`, `HardwareInfo`, `FirmwareInfo`, and `TimeInfo`
+  - Updated filter parameters to camelCase (`deviceUuids`, `deviceType`, `onlineStatus`, etc.)
+  - Changed `subdevice_id` getter to `subdeviceId` in push notification classes
+  - Updated `TokenData` interface: `issued_on` → `issuedOn`
+  - All JSDoc comments now reflect direct camelCase acceptance
+
+### Updated
+- Updated all examples to use camelCase consistently
+- Updated all examples to use `initializeDevices()` instead of `getDevices()`
+
 ## [0.3.1] - 2026-01-15
 
 ### Fixed

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.3.1
+npm install meross-iot@0.5.0
 ```
 
 ## Usage & Documentation
@@ -51,8 +51,8 @@ const { ManagerMeross, MerossHttpClient } = require('meross-iot');
   });
 
   // Listen for device events
-  meross.on('deviceInitialized', (deviceId, deviceDef, device) => {
-    console.log(`Device found: ${deviceDef.devName} (${deviceDef.deviceType})`);
+  meross.on('deviceInitialized', (deviceId, device) => {
+    console.log(`Device found: ${device.name} (${device.deviceType})`);
   });
 
   // Connect and discover devices
@@ -84,6 +84,63 @@ The `example/` directory contains focused examples for different use cases:
 - **`multiple-accounts.js`** - Using multiple Meross accounts simultaneously
 - **`factory-pattern-usage.js`** - Recommended factory pattern for creating HTTP clients and managers
 - **`timer-usage.js`** - Creating and managing device timers
+- **`selective-initialization.js`** - Selectively initializing devices and subdevices
+
+## Adding and Removing Devices
+
+You can dynamically add and remove devices from the manager after initialization:
+
+```javascript
+// Add a single device
+const device = await manager.devices.initializeDevice('device-uuid');
+
+// Add a subdevice (hub will be auto-initialized if needed)
+const subdevice = await manager.devices.initializeDevice({ 
+  hubUuid: 'hub-uuid', 
+  id: 'subdevice-id' 
+});
+
+// Remove a device
+const removed = await manager.devices.remove('device-uuid');
+
+// Remove a subdevice
+const removed = await manager.devices.remove({ 
+  hubUuid: 'hub-uuid', 
+  id: 'subdevice-id' 
+});
+```
+
+When removing a hub device, all its subdevices are automatically removed as well.
+
+## API Organization
+
+The library follows a modular architecture with specialized managers for different concerns:
+
+- **`manager.devices`** - Device discovery, initialization, and lifecycle management
+- **`manager.mqtt`** - MQTT connection management and message publishing
+- **`manager.http`** - LAN HTTP communication with devices
+- **`manager.transport`** - Transport mode selection and message routing
+- **`manager.subscription`** - Automatic polling and unified update streams
+
+This organization makes the API more discoverable and easier to use. For example:
+
+```javascript
+// Discover devices without initializing
+const availableDevices = await manager.devices.discover({ onlineOnly: true });
+
+// Initialize devices
+const count = await manager.devices.initialize();
+
+// Encode and send a message via MQTT
+const data = manager.mqtt.encode('GET', 'Appliance.Control.ToggleX', {}, device.uuid);
+manager.mqtt.send(device, data);
+
+// Send a message via LAN HTTP
+await manager.http.send(device, '192.168.1.100', data);
+
+// Use transport manager for automatic routing
+await manager.transport.request(device, '192.168.1.100', data);
+```
 
 ## Supported Devices
 
@@ -120,14 +177,75 @@ Please create an issue on GitHub and include:
 
 ## Changelog
 
-### [0.3.1] - 2026-01-15
+### [0.5.0] - 2026-01-19
 
-#### Fixed
-- Fixed `ManagerSubscription` constructor bug: now properly calls `super()` before accessing `this` to correctly initialize EventEmitter parent class
+#### Changed
+- **BREAKING**: Standardized error handling with MerossError* naming convention
+  - Renamed all error classes to use `MerossError*` prefix for consistency
+    - `AuthenticationError` → `MerossErrorAuthentication`
+    - `ConnectionError` → `MerossErrorConnection`
+    - `DeviceError` → `MerossErrorDevice`
+    - `HttpError` → `MerossErrorHttp`
+    - `MqttError` → `MerossErrorMqtt`
+    - `NetworkError` → `MerossErrorNetwork`
+    - `ProtocolError` → `MerossErrorProtocol`
+    - `TimeoutError` → `MerossErrorTimeout`
+    - `TokenError` → `MerossErrorToken`
+    - `ValidationError` → `MerossErrorValidation`
+  - All error classes now include `code`, `isOperational`, and `cause` properties
+  - Added `toJSON()` method to all error classes for serialization
+  - Updated TypeScript definitions to match new error structure
+  - Updated error-handling example to use new error class names
+- **BREAKING**: Split ManagerMeross into separate lazy-loaded manager modules
+  - Manager methods are now accessed via manager properties instead of direct methods:
+    - `manager.devices` - device discovery and initialization (ManagerDevices)
+    - `manager.mqtt` - MQTT connection management (ManagerMqtt)
+    - `manager.http` - LAN HTTP communication (ManagerHttp)
+    - `manager.transport` - transport mode selection and routing (ManagerTransport)
+    - `manager.statistics` - statistics tracking (ManagerStatistics)
+    - `manager.subscription` - device update subscriptions (ManagerSubscription)
+  - Extracted DeviceRegistry to standalone module
+  - Moved subscription manager to `managers/` directory
+  - Updated all examples and TypeScript definitions for new API
+
+#### Added
+- Enhanced error context through error chaining via `cause` property
+- Error serialization support via `toJSON()` method on all error classes
+- Lazy-loaded manager modules for better code organization and performance
 
 <details>
 <summary>Older</summary>
 
+### [0.4.0] - 2026-01-16
+
+#### Changed
+- **BREAKING**: Renamed `getDevices()` to `initializeDevices()` in `ManagerMeross`
+  - The method name better reflects that it performs full device discovery, initialization, and connection setup, not just retrieval
+  - Updated `login()` and `connect()` to use `initializeDevices()`
+  - Updated all examples and TypeScript definitions
+- **BREAKING**: Simplified device API by establishing single source of truth
+  - Removed `deviceDef` parameter from `deviceInitialized` event - now just `(deviceId, device)`
+  - Removed `cachedHttpInfo` property; all properties are now directly accessible on `MerossDevice`
+  - Converted simple getters to direct properties (`macAddress`, `lanIp`, `mqttHost`, etc.)
+  - Updated all feature files to use public properties (`abilities`, `lastFullUpdateTimestamp`)
+  - Removed unnecessary defensive fallback patterns (`device.dev?.uuid` → `device.uuid`)
+  - Fixed subdevice property consistency
+- **BREAKING**: Removed snake_case handling, standardized on camelCase
+  - Removed snake_case property mappings from `HttpDeviceInfo`, `HttpSubdeviceInfo`, `HardwareInfo`, `FirmwareInfo`, and `TimeInfo`
+  - Updated filter parameters to camelCase (`deviceUuids`, `deviceType`, `onlineStatus`, etc.)
+  - Changed `subdevice_id` getter to `subdeviceId` in push notification classes
+  - Updated `TokenData` interface: `issued_on` → `issuedOn`
+  - All JSDoc comments now reflect direct camelCase acceptance
+
+#### Updated
+- Updated all examples to use camelCase consistently
+- Updated all examples to use `initializeDevices()` instead of `getDevices()`
+
+### [0.3.1] - 2026-01-15
+
+#### Fixed
+- Fixed `ManagerSubscription` constructor bug: now properly calls `super()` before accessing `this` to correctly initialize EventEmitter parent class
+
 ### [0.3.0] - 2026-01-15
 
 #### Changed