meross-iot 0.9.1 → 0.10.0

package/CHANGELOG.md

@@ -5,6 +5,61 @@ 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.10.0] - 2026-05-19
+
+### Added
+- `Meross.authenticate()` — authenticate and return a manager without connecting to the cloud or initializing devices
+- `Meross.connect()` — static entry point that authenticates and connects in one step
+- Multi-channel helpers on toggle, timer, and trigger abilities: `getAll()` aggregates state across all device channels; timer and trigger also expose `count()`
+- `getDeviceChannelIds()` utility for consistent channel enumeration from capabilities or device metadata
+- Namespace dispatcher with header-timestamp ordering gate for SETACK, GETACK, and PUSH state updates
+- Shared cache helpers (`readCache`, `getCachedOrFetch`) used by ability `get()` methods
+- Unit test suite (198 tests) covering abilities, dispatcher, push notifications, authentication, and public module surface
+- `manager.mqtt.connections` — exposes active MQTT connection map for diagnostics
+
+### Changed
+- **BREAKING**: Renamed `ManagerMeross` to `Meross` (default export)
+  - `const Meross = require('meross-iot')` replaces `const ManagerMeross = require('meross-iot')`
+  - Direct construction requires an authenticated HTTP client; use `Meross.authenticate()` or `Meross.connect()` as entry points
+- **BREAKING**: Removed public `MerossHttpClient` export
+  - Use `Meross.authenticate()` for credential exchange and token reuse via `meross.getTokenData()`
+- **BREAKING**: Consolidated error classes into a smaller hierarchy with string `code` discriminators
+  - Exported: `MerossError`, `MerossAuthError`, `MerossDeviceError`, `MerossApiError`, `MerossNetworkError`
+  - Removed granular exports such as `MerossErrorAuthentication`, `MerossErrorTokenExpired`, `MerossErrorCommandTimeout`, `MerossErrorValidation`, etc.
+  - Catch category errors with `instanceof` and inspect `error.code` for specific handling (e.g. `TOKEN_EXPIRED`, `VALIDATION_ERROR`, `COMMAND_TIMEOUT`)
+  - Removed public `mapErrorCodeToError` export
+- **BREAKING**: Renamed `device.getUnifiedState()` to `device.getState()`
+  - State is now derived from dispatcher namespace descriptors rather than hand-maintained aggregation
+- **BREAKING**: Unified device initialization events
+  - Device emits `ready` (replacing `deviceInitialized`); manager emits `deviceReady` when a device finishes bootstrap
+  - `device.ready()` promise API unchanged
+- **BREAKING**: Device abilities are initialized conditionally based on supported namespaces
+  - Unsupported features are absent (`undefined`) rather than present with stub methods
+- **BREAKING**: Transport and statistics are accessed exclusively via sub-managers
+  - Use `meross.transport` for mode selection, error budgets, and request queuing
+  - Use `meross.statistics` for HTTP/MQTT stats (`enable()`, `getHttpStats()`, `getMqttStats()`)
+- **BREAKING**: Trimmed public module exports to documented API surface
+  - Removed exports for state classes, push notification classes, `TimerUtils`, `TriggerUtils`, `createDebugUtils`, `ManagerSubscription`, and `MerossHttpClient`
+  - Removed `ThermostatWorkingMode` and `ThermostatModeBState` from package root exports (still available internally)
+- **BREAKING**: Internal package layout restructured (no import-path stability for deep requires)
+  - `lib/controller/features/` → `lib/abilities/`
+  - `lib/managers/` → `manager/`
+  - `lib/controller/` → `lib/device/`
+  - `lib/http-api.js` → `lib/api/client.js`
+- Subdevice state updates now pass through the same ordering gate as base devices, preventing stale hub sensor payloads from overwriting fresher per-namespace data
+- Rewrote TypeScript definitions to match the simplified public API
+- Updated all examples for the new connect/authenticate flow and ability-based device control
+
+### Fixed
+- Rewrote `publishMessage` without an async Promise executor
+- HTTP API status errors are routed through `mapErrorCodeToError` consistently
+- Exposed `manager.mqtt.connections` and aligned `disconnectAll()` routing through the mqtt getter
+
+### Removed
+- Standalone `lib/error-budget.js` (error budget logic lives on `ManagerTransport`)
+- `lib/utilities/debug.js` and `createDebugUtils` export
+- Internal ability `_update*` test hooks; state is exercised through dispatcher shims in tests
+
 ## [0.9.1] - 2026-01-22
 
 ### Fixed

package/README.md

@@ -26,65 +26,42 @@ 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.9.1
+npm install meross-iot@0.10.0
 ```
 
 ## Usage & Documentation
 
-Refer to the [example/README.md](example/README.md) for detailed usage instructions, or simply have a look at the `/example` directory.
+Runnable examples live in the GitHub repo under [`packages/meross-iot/example/`](https://github.com/Doekse/merossiot/tree/main/packages/meross-iot/example). See [example/README.md](https://github.com/Doekse/merossiot/blob/main/packages/meross-iot/example/README.md) for the full table (not included in the npm tarball).
 
 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 { ManagerMeross, MerossHttpClient } = require('meross-iot');
+const Meross = require('meross-iot');
 
 (async () => {
-  // Create HTTP client using factory method
-  const httpClient = await MerossHttpClient.fromUserPassword({
+  const meross = await Meross.connect({
     email: 'your@email.com',
-    password: 'yourpassword'
+    password: 'yourpassword',
   });
 
-  // Create manager with HTTP client
-  const meross = new ManagerMeross({
-    httpClient: httpClient
-  });
-
-  // Listen for device events
-  meross.on('deviceInitialized', (deviceId, device) => {
-    console.log(`Device found: ${device.name} (${device.deviceType})`);
-  });
-
-  // Connect and discover devices
-  await meross.connect();
-  
-  // Find a device and control it
   const devices = meross.devices.list();
   if (devices.length > 0) {
     const device = devices[0];
-    
-    // Example: Toggle a switch
     if (device.toggle) {
-      await device.toggle.set({ channel: 0, on: true }); // Turn on channel 0
+      await device.toggle.set({ channel: 0, on: true });
     }
   }
 })();
 ```
 
-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 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
-- **`hub-devices.js`** - Working with hub devices and subdevices
-- **`transport-modes.js`** - Understanding different transport modes
-- **`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
+Clone the repo or browse GitHub for runnable scripts. Highlights:
+
+- **`basic-usage.js`** — `Meross.connect()` and list devices
+- **`authenticate.js`** — `Meross.authenticate()` then selective `connect()`
+- **`device-control.js`** — Feature objects: `toggle`, `light`, `electricity`, `system`
+- **`device-discovery.js`** — `discover` / `discoverSubdevices` and `initializeDevice`
+- **`subscription-manager.js`** — `meross.subscription` polling and list updates
+- **`token-reuse.js`** — Persist `getTokenData()` between runs
 
 ## Adding and Removing Devices
 
@@ -92,21 +69,21 @@ 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');
+const device = await meross.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' 
+const subdevice = await meross.devices.initializeDevice({
+  hubUuid: 'hub-uuid',
+  id: 'subdevice-id'
 });
 
 // Remove a device
-const removed = await manager.devices.remove('device-uuid');
+const removed = await meross.devices.remove('device-uuid');
 
 // Remove a subdevice
-const removed = await manager.devices.remove({ 
-  hubUuid: 'hub-uuid', 
-  id: 'subdevice-id' 
+const removed = await meross.devices.remove({
+  hubUuid: 'hub-uuid',
+  id: 'subdevice-id'
 });
 ```
 
@@ -114,32 +91,29 @@ 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:
+The library follows a modular architecture with specialized managers on the connected `Meross` instance:
 
-- **`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
+- **`meross.devices`** — device discovery, initialization, and lifecycle management
+- **`meross.mqtt`** — MQTT connection management and message publishing
+- **`meross.http`** — LAN HTTP communication with devices
+- **`meross.transport`** — transport mode selection and message routing
+- **`meross.subscription`** — automatic polling and unified update streams
+- **`meross.statistics`** — optional HTTP/MQTT request diagnostics
 
-This organization makes the API more discoverable and easier to use. For example:
+Most apps use feature objects on devices (`device.toggle.set()`, etc.). Lower-level managers (`mqtt`, `http`, `transport`) remain available for advanced use:
 
 ```javascript
-// Discover devices without initializing
-const availableDevices = await manager.devices.discover({ onlineOnly: true });
+// Discover devices without initializing (after Meross.authenticate)
+const availableDevices = await meross.devices.discover({ onlineOnly: true });
 
-// Initialize devices
-const count = await manager.devices.initialize();
+// Initialize all or selected devices
+const count = await meross.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);
+// Prefer feature API for everyday control
+await device.toggle.set({ channel: 0, on: true });
 
-// 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);
+// Transport mode (MQTT vs LAN-first)
+meross.transport.defaultMode = Meross.TransportMode.LAN_HTTP_FIRST;
 ```
 
 ## Supported Devices
@@ -177,14 +151,33 @@ Please create an issue on GitHub and include:
 
 ## Changelog
 
+See **[CHANGELOG.md](CHANGELOG.md)** for the full release history.
+
+### [0.10.0] - 2026-05-19
+
+Major API simplification release. Highlights:
+
+#### Added
+- `Meross.authenticate()` and `Meross.connect()` static entry points
+- Multi-channel `getAll()` on toggle, timer, and trigger abilities
+- Namespace dispatcher with header-timestamp ordering for state updates
+- Unit test suite (198 tests)
+
+#### Changed
+- **BREAKING**: `ManagerMeross` → `Meross`; removed public `MerossHttpClient` export
+- **BREAKING**: Consolidated error classes (`MerossAuthError`, `MerossDeviceError`, etc.) with string `code` discriminators
+- **BREAKING**: `device.getUnifiedState()` → `device.getState()`; `deviceInitialized` → `ready` / `deviceReady`
+- **BREAKING**: Conditional ability initialization; trimmed public module exports
+- Internal layout: `lib/abilities/`, `manager/`, `lib/device/`
+
+<details>
+<summary>Older releases</summary>
+
 ### [0.9.1] - 2026-01-22
 
 #### Fixed
 - Improve heartbeat offline detection by using response silence (≥ heartbeat interval) instead of treating individual command errors/timeouts as offline signals
 
-<details>
-<summary>Older</summary>
-
 ### [0.9.0] - 2026-01-22
 
 #### Added