1.5.1: broker errors as events that never crash the host (error only when listened to; connect/offline/reconnect/close; connected flag), configurable broker host + mqtt options + log hook, Alexa.ChangeReport via Device.getChangeReport (<root>/changeReport), SceneController discovery + sendSceneResponse, addCapability options (proactivelyReported), unregisterDevice/clearDevices/getDevices/disconnect, discover/directive events, promise-returning quiet send(); tests on an in-process broker (aedes); readme

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

readme.md

@@ -13,6 +13,41 @@ For more details on how to configure Alex2MQTT, visit [Alex2MQTT Documentation](
 - Easily configure devices and their capabilities via simple API.
 
 
+## What is new in 1.5.1
+
+- **A broker outage no longer crashes your process.** 1.4.0 emitted `error` unconditionally, and Node terminates a
+  process that has an unhandled `error` event, so every reconnect failure killed the host. 1.5.1 emits `error` only
+  when you listen for it, keeps reconnecting on its own (mqtt.js, 1 s), and reports `connect`, `offline`, `reconnect`
+  and `close`. `bridge.connected` says where you stand.
+- **Configurable broker.** `new Alex2MQTT(user, pass, rootTopic, debug, { host: "mqtt://broker:1883", mqtt: { ... } })`
+  (the default is still the public Alex2MQTT broker). `options.mqtt` is merged over the mqtt.js client options;
+  `options.log` replaces the console output.
+- **Proactive state (ChangeReport).** `device.getChangeReport(cause)` builds an `Alexa.ChangeReport`: the
+  `add*Prop` calls describe what changed, `.unchanged()` switches the following calls to the context, `.send()`
+  publishes it to `<rootTopic>/changeReport`, which Alex2MQTT forwards to the Alexa event gateway with your account's
+  token. Register the capability with `{ proactivelyReported: true }` so Alexa accepts it.
+- **Scenes.** `Alexa.SceneController` discovers correctly (`supportsDeactivation`), and
+  `device.sendSceneResponse(correlationToken, activated)` answers Activate / Deactivate with ActivationStarted /
+  DeactivationStarted.
+- **Device management.** `unregisterDevice(endpointId)`, `clearDevices()`, `getDevices()`, `getDevice(id)`,
+  `disconnect()`; `discover` (device count) and `directive` ({ endpointId, namespace, name }) events;
+  `lastDiscoveryAt`. `addCapability(type, { retrievable, proactivelyReported, instance })`.
+- `send()` on every message returns a promise (resolves with the topic) and no longer logs to the console.
+- Tests: `npm test` runs the library against an in-process MQTT broker (aedes, a dev dependency).
+
+```js
+const { Alex2MQTT, AlexaInterfaceType, DisplayCategory, PowerController } = require("alex2node");
+const bridge = new Alex2MQTT(user, pass, rootTopic, false, { host: process.env.MQTT_URL });
+bridge.on("error", (e) => console.warn("broker:", e.message)); // optional - without it the error is swallowed, never thrown
+bridge.on("connect", () => console.log("connected"));
+bridge.connect();
+const lamp = bridge.registerDevice("Dining Room Light", "5020AA", DisplayCategory.LIGHT);
+lamp.addCapability(AlexaInterfaceType.POWER_CONTROLLER, { proactivelyReported: true });
+lamp.on("Event", (directive) => { /* ... act, then: */ lamp.getStatusMessage(directive.header.correlationToken, true).addPowerControllerProp(PowerController.ON).send(); });
+// later, when the light changes locally:
+lamp.getChangeReport("PHYSICAL_INTERACTION").addPowerControllerProp(PowerController.OFF).send();
+```
+
 ## Quick Start
 
 ### Installation
@@ -54,7 +89,7 @@ const username = process.env.MQTT_USERNAME;
 const password = process.env.MQTT_PASSWORD;
 const rootTopic = process.env.MQTT_ROOT_TOPIC;
 
-const alex2NodeClient = new Alex2MQTT(username, password, rootTopic, false);
+const alex2NodeClient = new Alex2MQTT(username, password, rootTopic, false); // 1.5.1: add { host } as a fifth argument for another broker
 alex2NodeClient.connect(); // Connect to the MQTT broker
 ```