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/ExamplePowerControllerDeferred.js

@@ -0,0 +1,92 @@
+// 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,
+    EndpointHealth
+} = require("alex2node");
+
+require("dotenv").config(); // Load environment variables from .env file
+
+// Simulated in-memory device state (used for example/demo purposes)
+let outputState = PowerController.OFF; // Initialize the power state to OFF
+
+// Load MQTT connection credentials and root topic from environment variables
+const username = process.env.MQTT_USERNAME;
+const password = process.env.MQTT_PASSWORD;
+const rootTopic = process.env.MQTT_ROOT_TOPIC;
+
+// Create and initialize a new Alexa-to-MQTT client
+const alex2NodeClient = new Alex2MQTT(username, password, rootTopic, false);
+alex2NodeClient.connect(); // Connect to the MQTT broker
+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)
+
+// Define the device name (deferred light)
+const deviceName = "Deferred Light";
+
+// Register the device with a unique endpoint ID (unique per root topic, e.g. "deferred-light-1")
+const deferredLight = alex2NodeClient.registerDevice(deviceName, "deferred-light-1");
+
+// Add the PowerController capability (for turning on/off the device)
+deferredLight.addCapability(AlexaInterfaceType.POWER_CONTROLLER);
+
+// Log the device name to verify registration
+console.log(deferredLight.getName());
+
+/**
+ * Handle Alexa's ReportState directive.
+ * This occurs when Alexa queries the current state of the device (e.g., during routines or device status checks).
+ */
+deferredLight.on("ReportState", (payload) => {
+  console.log("ReportState received!", payload);
+
+  const { correlationToken } = payload.header;
+
+  // Step 1: Send a DeferredResponse after ~2 seconds
+  setTimeout(() => {
+    const deferred = deferredLight.getStatusMessage(correlationToken, false, true); // isDeferred = true
+    deferred.addEstimatedDeferralTime(20).send();
+    console.log("Sent DeferredResponse");
+  }, 2000); // simulate slight delay before deferred response
+
+  // Step 2: Send actual StateReport after 10 seconds
+  setTimeout(() => {
+    const status = deferredLight.getStatusMessage(correlationToken,false,false); // normal StateReport
+    status
+      .addHealthProp(EndpointHealth.OK)
+      .addPowerControllerProp(outputState)
+      .send(true);
+    console.log("Sent actual StateReport with device status");
+  }, 8000);
+});
+
+
+/**
+ * Handle incoming control directives (e.g., TurnOn, TurnOff).
+ * These directives come from Alexa when a user issues a command.
+ */
+deferredLight.on("Event", (directive, interfaceType) => {
+  console.log("Event received", { directive, interfaceType });
+
+  // Ensure the interfaceType is either PowerController or other valid interfaces
+  if (interfaceType === AlexaInterfaceType.POWER_CONTROLLER) {
+    const name = directive.header.name;
+    const token = directive.header.correlationToken;
+
+    // Update the internal state based on the command (TurnOn / TurnOff)
+    if (name === "TurnOn") {
+      outputState = PowerController.ON;
+      console.log("Turning ON the Deferred Light");
+    } else if (name === "TurnOff") {
+      outputState = PowerController.OFF;
+      console.log("Turning OFF the Deferred Light");
+    }
+
+    // Respond to the directive with the updated device status
+    const status = deferredLight.getStatusMessage(token, true);
+    status
+      .addHealthProp(EndpointHealth.OK)
+      .addPowerControllerProp(outputState)
+      .send();
+  }
+});