meross-iot 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -5,6 +5,42 @@ 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

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.4.0
+npm install meross-iot@0.5.0
 ```
 
 ## Usage & Documentation
@@ -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,6 +177,45 @@ Please create an issue on GitHub and include:
 
 ## Changelog
 
+### [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
+
+<details>
+<summary>Older</summary>
+
 ### [0.4.0] - 2026-01-16
 
 #### Changed
@@ -145,9 +241,6 @@ Please create an issue on GitHub and include:
 - Updated all examples to use camelCase consistently
 - Updated all examples to use `initializeDevices()` instead of `getDevices()`
 
-<details>
-<summary>Older</summary>
-
 ### [0.3.1] - 2026-01-15
 
 #### Fixed