apps/Alex2Node
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

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

Browse source 
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
David 2026-09-22 19:29:38 +00:00
parent e96850bdd6
commit 717af632de
16 changed files with 2080 additions and 225 deletions
Download patch file Download diff file Expand all files Collapse all files

163
dist/Alex2Node.js vendored
View file

@ -3,12 +3,28 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
return (mod && mod.__esModule) ? mod : { "default": mod };
};
Object.defineProperty(exports, "__esModule", { value: true });
exports.DEFAULT_HOST = void 0;
const mqtt_1 = __importDefault(require("mqtt"));
const Device_1 = __importDefault(require("./Device"));
const events_1 = require("events");
const DisplayCategory_1 = require("./DisplayCategory");
exports.DEFAULT_HOST = "mqtt://Alex2MQTT.stormysdream.club:1883";
/**
* The Alexa-to-MQTT bridge: one broker connection for a user's root topic, a set of registered devices, discovery and
* directive dispatch.
*
* Events (all optional to listen to - since 1.5.1 a broker outage never throws out of the library):
* "connect" connected (or reconnected) and subscribed to <root>/#
* "offline" the connection dropped; mqtt.js reconnects on its own (reconnectPeriod, default 1 s)
* "reconnect" a reconnect attempt starts
* "close" the connection closed
* "error" (err) a connection or publish error. Emitted ONLY when a listener is attached (1.4.0 emitted it
* unconditionally, and Node kills a process that has an unhandled "error" event)
* "discover" (n) a discovery request was answered with n devices
* "directive" (info) a directive was dispatched to a device: { endpointId, namespace, name }
*/
class Alex2MQTT extends events_1.EventEmitter {
constructor(username, password, rootTopic, debugLogging) {
constructor(username, password, rootTopic, debugLogging = false, options = {}) {
super(); // Initialize EventEmitter
this.username = username;
this.password = password;
@ -16,62 +32,73 @@ class Alex2MQTT extends events_1.EventEmitter {
this.debugLogging = debugLogging;
this.client = null;
this.devices = [];
this.MqttHost = "mqtt://Alex2MQTT.stormysdream.club";
/** true while the broker connection is up. */
this.connected = false;
/** ISO time of the last discovery request answered, null before the first. */
this.lastDiscoveryAt = null;
this.options = options || {};
this.MqttHost = this.options.host || exports.DEFAULT_HOST;
}
log(message, detail) {
if (this.options.log)
this.options.log(message, detail);
else if (this.debugLogging) {
if (detail === undefined)
console.log(`[Alex2Node.ts] ${message}`);
else
console.log(`[Alex2Node.ts] ${message}`, detail);
}
}
/** Emit "error" only when somebody listens: an unhandled "error" event would crash the host process. */
fail(err) {
this.log("error: " + err.message);
if (this.listenerCount("error") > 0)
this.emit("error", err);
}
connect() {
const options = {
username: this.username,
password: this.password,
};
if (this.client)
return;
const options = Object.assign({ username: this.username, password: this.password, reconnectPeriod: 1000, connectTimeout: 10000 }, (this.options.mqtt || {}));
this.client = mqtt_1.default.connect(this.MqttHost, options);
this.client.on("connect", () => {
if (this.debugLogging) {
console.log("[Alex2Node.ts] Connected to MQTT broker");
}
this.connected = true;
this.log("Connected to MQTT broker");
this.client.subscribe(this.rootTopic + "/#", (err) => {
if (this.debugLogging && !err) {
console.log("[Alex2Node.ts] Subscribed to topics");
}
if (err) {
console.error("[Alex2Node.ts] MQTT connection error:", err);
this.emit("error", err);
this.fail(err);
return;
}
this.log("Subscribed to topics");
this.emit("connect");
});
});
this.client.on("offline", () => { this.connected = false; this.log("offline"); this.emit("offline"); });
this.client.on("reconnect", () => { this.log("reconnecting"); this.emit("reconnect"); });
this.client.on("close", () => { this.connected = false; this.emit("close"); });
this.client.on("error", (err) => { this.connected = false; this.fail(err); });
this.client.on("message", (topic, message) => {
if (this.debugLogging) {
console.log(`[Alex2Node.ts] MQTT Message Received`);
console.log(` Topic: ${topic}`);
console.log(` Payload: ${message.toString()}`);
}
this.log(`MQTT Message Received`, { topic, payload: message.toString() });
if (topic == `${this.rootTopic}/discover`) {
if (this.debugLogging) {
console.log("[Alex2Node.ts] Discovery request received, getting device json...");
}
this.log("Discovery request received, getting device json...");
const deviceArray = this.devices.map((device) => device.getJSON());
if (deviceArray.length > 0) {
this.client.publish(topic + "_r", JSON.stringify(deviceArray), (err) => {
if (err) {
console.error("[Alex2Node.ts] MQTT connection error:", err);
this.emit("error", err);
}
else if (this.debugLogging) {
console.log(`[Alex2Node.ts] Discovery payloads published to ${topic + "_r"}`);
console.log(JSON.stringify(deviceArray, null, 2));
}
});
}
this.lastDiscoveryAt = new Date().toISOString();
this.client.publish(topic + "_r", JSON.stringify(deviceArray), (err) => {
if (err) {
this.fail(err);
return;
}
this.log(`Discovery payloads published to ${topic + "_r"}`, deviceArray);
this.emit("discover", deviceArray.length);
});
}
else if (topic.split("/").length == 3) {
const [root, endpointId, directiveType] = topic.split("/");
const [, endpointId, directiveType] = topic.split("/");
if (directiveType != "alexaDirective") {
return;
}
const device = this.devices.find((d) => d.endpointId === endpointId);
if (!device) {
if (this.debugLogging) {
console.warn(`[Alex2Node.ts] No device found for endpointId: ${endpointId}`);
}
this.log(`No device found for endpointId: ${endpointId}`);
return;
}
let payload;
@ -79,15 +106,14 @@ class Alex2MQTT extends events_1.EventEmitter {
payload = JSON.parse(message.toString());
}
catch (e) {
console.error(`[Alex2Node.ts] Failed to parse payload JSON`, e);
this.log(`Failed to parse payload JSON`, e);
return;
}
if (payload.header &&
payload.header.namespace === "Alexa" &&
payload.header.name === "ReportState") {
if (this.debugLogging) {
console.log(`[Alex2Node.ts] ReportState directive for device ${endpointId}`);
}
if (!payload || !payload.header)
return;
this.emit("directive", { endpointId, namespace: payload.header.namespace, name: payload.header.name });
if (payload.header.namespace === "Alexa" && payload.header.name === "ReportState") {
this.log(`ReportState directive for device ${endpointId}`);
device.emit("ReportState", payload);
}
else {
@ -95,21 +121,23 @@ class Alex2MQTT extends events_1.EventEmitter {
}
}
});
this.client.on("error", (err) => {
if (this.debugLogging) {
console.error("[Alex2Node.ts] Connection failed:", err);
}
console.error("[Alex2Node.ts] MQTT connection error:", err);
this.emit("error", err);
}
/** Close the broker connection (resolves once closed). The devices stay registered; connect() again reuses them. */
disconnect() {
return new Promise((resolve) => {
const c = this.client;
if (!c)
return resolve();
this.client = null;
this.connected = false;
c.end(true, {}, () => resolve());
});
}
registerDevice(name, endpointId, displayCategory) {
if (!this.client) {
throw new Error("Must call connect before creating devices");
}
if (this.debugLogging) {
console.log(`[Alex2Node.ts] Creating new device with endpoint: ${endpointId}`);
}
this.log(`Creating new device with endpoint: ${endpointId}`);
const normalizedCategory = displayCategory === null
? [DisplayCategory_1.DisplayCategory.LIGHT]
: Array.isArray(displayCategory)
@ -119,5 +147,32 @@ class Alex2MQTT extends events_1.EventEmitter {
this.devices.push(device);
return device;
}
/** Forget a device (its listeners with it). Returns false when there was none. */
unregisterDevice(endpointId) {
const i = this.devices.findIndex((d) => d.endpointId === endpointId);
if (i === -1)
return false;
this.devices[i].removeAllListeners();
this.devices.splice(i, 1);
return true;
}
/** Forget every device. */
clearDevices() {
for (const d of this.devices)
d.removeAllListeners();
this.devices = [];
}
getDevices() {
return this.devices.slice();
}
getDevice(endpointId) {
return this.devices.find((d) => d.endpointId === endpointId);
}
getRootTopic() {
return this.rootTopic;
}
getHost() {
return this.MqttHost;
}
}
exports.default = Alex2MQTT;