examples: one runnable file per recipe on the 2.0 API, the 1.x files in examples/legacy

Ten recipes: lamp, colour lamp, thermostat, blind, lock (deferred), contact
sensor (ChangeReport), scene, doorbell (raise), typed errors, and a plug as an
ES module. Each reads ALEX2MQTT_USERNAME, _PASSWORD and _ROOT_TOPIC and names
the ones that are missing. The nine examples of 1.5.2 move to examples/legacy
unchanged.

test/examples.test.js starts every file with node, its broker connection sent
to a broker on 127.0.0.1 (test/helpers/loopback.js), discovers the device,
sends directives and checks the answers. A legacy file is started and its
discovery compared with the answer the 1.5.2 build gave, recorded in
test/fixtures/legacy-examples.

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

examples/legacy/ExamplePowerControllerWithErrors.js

@@ -0,0 +1,95 @@
+// Import the library ("alex2node" is the installed package; inside this checkout it resolves to the built dist/ via package.json "exports")
+const {
+  Alex2MQTT,
+  AlexaInterfaceType,
+  PowerController,
+  AlexaErrorType,
+  EndpointHealth,
+} = require("alex2node");
+
+require("dotenv").config();
+
+let outputState = PowerController.OFF;
+
+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);
+alex2NodeClient.connect();
+alex2NodeClient.on("error", (e) => console.error("broker:", e.message)); // Log broker errors (on 1.5.0 this listener is also what keeps an outage from killing the process)
+
+const errorLight = alex2NodeClient.registerDevice("bad light", "bad-light-1");
+errorLight.addCapability(AlexaInterfaceType.POWER_CONTROLLER);
+
+console.log(errorLight.getName());
+
+// Error cycling setup
+const errorCycle = [
+  AlexaErrorType.ENDPOINT_LOW_POWER,
+  AlexaErrorType.VALUE_OUT_OF_RANGE,
+  AlexaErrorType.HARDWARE_MALFUNCTION,
+  AlexaErrorType.BRIDGE_UNREACHABLE,
+  AlexaErrorType.FIRMWARE_OUT_OF_DATE,
+  AlexaErrorType.NOT_CALIBRATED,
+  AlexaErrorType.RATE_LIMIT_EXCEEDED,
+];
+let currentErrorIndex = 0;
+
+/**
+ * Always return HARDWARE_MALFUNCTION error on state queries.
+ */
+errorLight.on("ReportState", (payload) => {
+  console.log("ReportState received!", payload);
+
+  const { correlationToken } = payload.header;
+  const errorResponse = errorLight.getErrorMessage(correlationToken);
+
+  errorResponse.setErrorMessage(
+    AlexaErrorType.HARDWARE_MALFUNCTION,
+    "The device is currently busy and cannot report its state."
+  );
+  console.log("Sending error: HARDWARE_MALFUNCTION");
+  errorResponse.send();
+});
+
+/**
+ * Handle control directives with 90% error chance, cycling through fixed errors.
+ */
+errorLight.on("Event", (directive, interfaceType) => {
+  if (interfaceType === AlexaInterfaceType.POWER_CONTROLLER) {
+    const name = directive.header.name;
+    const token = directive.header.correlationToken;
+
+    const shouldError = Math.random() < 0.9;
+
+    if (shouldError) {
+      const errorType = errorCycle[currentErrorIndex];
+      currentErrorIndex = (currentErrorIndex + 1) % errorCycle.length;
+
+      const errorResponse = errorLight.getErrorMessage(token);
+      errorResponse.setErrorMessage(
+        errorType,
+        `Failed to process ${name} due to ${errorType.replace(/_/g, " ").toLowerCase()}.`
+      );
+      console.log(`Sending error: ${errorType}`);
+      errorResponse.send();
+      return;
+    }
+
+    // Success path
+    if (name === "TurnOn") {
+      outputState = PowerController.ON;
+      console.log("Turning ON the Light");
+    } else if (name === "TurnOff") {
+      outputState = PowerController.OFF;
+      console.log("Turning OFF the Light");
+    }
+
+    const status = errorLight.getStatusMessage(token, true);
+    status
+      .addHealthProp(EndpointHealth.OK)
+      .addPowerControllerProp(outputState)
+      .send();
+  }
+});