discovery: generate capability JSON from the registry

A capability is a descriptor plus what the endpoint declares (device/Capability.ts), and its discovery object is
generated from the two. The new API is bridge.addDevice({ endpointId, name, categories, ... }) and
device.add(PowerController, options): both throw a DeclarationError that names the endpoint, the interface and
the instance (device/validate.ts), and leave the bridge and the device as they were. AlexaInterface is the same
Capability with the 1.x methods on it; it, ActionMapping and the enums moved to src/compat/, Device to src/device/.

What a 1.x caller can observe:
- every endpoint ends with { type: "AlexaInterface", interface: "Alexa", version: "3" } (alexa-interface.html);
  new Alex2MQTT(..., { alexaInterface: false }) leaves it out
- the fields of a capability object come in the order of Amazon's examples; their content is unchanged
- addCapability() with a name that is not an interface throws (1.5.2 announced it with the version "UNKNOWN")
- ActionMapping takes the payload as an object; a JSON string is parsed (1.5.2 sent the string), any other throws
- what Alexa would reject in a 1.x declaration is not refused: device.check() lists it and the bridge logs each
  line once, as "warning: ..." through the log hook, when it answers a discovery
- a device whose JSON cannot be built is left out of the answer and reported as an error event
- PowerController and EndpointHealth are the descriptors and keep ON/OFF and OK/UNREACHABLE; PowerState is new

Tests: six zoo devices declared the 1.x way give the JSON that Alexa accepted from 1.5.2 on 2026-09-28, plus the
Alexa capability. npm test: 85 pass (was 57) in 10-12 s, also on Node 18.20.8 and 20.20.2.

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

dist/cjs/ActionMapping.js

@@ -1,32 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ActionMapping = exports.AlexaActions = void 0;
-var AlexaActions;
-(function (AlexaActions) {
-    AlexaActions["Open"] = "Alexa.Actions.Open";
-    AlexaActions["Close"] = "Alexa.Actions.Close";
-    AlexaActions["Raise"] = "Alexa.Actions.Raise";
-    AlexaActions["Lower"] = "Alexa.Actions.Lower";
-    AlexaActions["SetEcoOn"] = "Alexa.Actions.SetEcoOn";
-    AlexaActions["SetEcoOff"] = "Alexa.Actions.SetEcoOff";
-})(AlexaActions || (exports.AlexaActions = AlexaActions = {}));
-class ActionMapping {
-    constructor(actions, directiveName, directivePayload) {
-        this.type = "ActionsToDirective";
-        this.actions = actions;
-        this.directive = {
-            name: directiveName,
-        };
-        if (directivePayload) {
-            this.directive.payload = directivePayload;
-        }
-    }
-    toJSON() {
-        return {
-            "@type": this.type,
-            actions: this.actions,
-            directive: this.directive,
-        };
-    }
-}
-exports.ActionMapping = ActionMapping;

dist/cjs/Alex2Node.js

@@ -6,11 +6,17 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_HOST = void 0;
 // mqtt reaches Node as CommonJS: the default import works from both builds, a named one needs Node to detect it.
 const mqtt_1 = __importDefault(require("mqtt"));
-const Device_js_1 = __importDefault(require("./Device.js"));
+const Device_js_1 = __importDefault(require("./device/Device.js"));
+const validate_js_1 = require("./device/validate.js");
 const events_1 = require("events");
-const DisplayCategory_js_1 = require("./DisplayCategory.js");
-const AlexaInterface_js_1 = require("./AlexaInterface.js");
+const enums_js_1 = require("./compat/enums.js");
+const types_js_1 = require("./registry/types.js");
 exports.DEFAULT_HOST = "mqtt://Alex2MQTT.stormysdream.club:1883";
+// What addDevice() copies from the definition to the device
+const DESCRIBED = [
+    "description", "manufacturerName", "manufacturer", "model", "serialNumber", "firmwareVersion", "softwareVersion",
+    "customIdentifier", "cookie",
+];
 /**
  * The Alexa-to-MQTT bridge: one broker connection for a user's root topic, a set of registered devices, discovery and
  * directive dispatch.
@@ -34,6 +40,8 @@ class Alex2MQTT extends events_1.EventEmitter {
         this.debugLogging = debugLogging;
         this.client = null;
         this.devices = [];
+        // The lines of check() that were logged. Discovery comes every few minutes: a line is logged once.
+        this.logged = new Set();
         /** true while the broker connection is up. */
         this.connected = false;
         /** ISO time of the last discovery request answered, null before the first. */
@@ -90,12 +98,8 @@ class Alex2MQTT extends events_1.EventEmitter {
             this.log(`MQTT Message Received`, { topic, payload: message.toString() });
             if (topic == `${this.rootTopic}/discover`) {
                 this.log("Discovery request received, getting device json...");
-                const deviceArray = this.devices.map((device) => device.getJSON());
+                const deviceArray = this.describeDevices();
                 this.lastDiscoveryAt = new Date().toISOString();
-                for (const device of this.devices) // a capability the library has no property list for goes out with supported: []
-                    for (const cap of device.getCapabilities())
-                        if (cap.getProps().length === 0 && cap.getType() !== AlexaInterface_js_1.AlexaInterfaceType.SCENE_CONTROLLER)
-                            this.log(`${device.endpointId}: no property list known for ${cap.getTypeString()}, discovery lists it with no supported properties`);
                 this.client.publish(topic + "_r", JSON.stringify(deviceArray), (err) => {
                     if (err) {
                         this.fail(err);
@@ -136,6 +140,26 @@ class Alex2MQTT extends events_1.EventEmitter {
             }
         });
     }
+    // The endpoint objects of a discovery answer. What check() says about a device is logged, each line once. A device
+    // that cannot be described is left out and reported as an error: the others are still announced.
+    describeDevices() {
+        const endpoints = [];
+        for (const device of this.devices) {
+            try {
+                endpoints.push(device.getJSON());
+                for (const line of device.check()) {
+                    if (this.logged.has(line))
+                        continue;
+                    this.logged.add(line);
+                    this.log(`warning: ${line}`);
+                }
+            }
+            catch (err) {
+                this.fail(new Error(`${device.endpointId} is not in the discovery answer: ${err instanceof Error ? err.message : err}`));
+            }
+        }
+        return endpoints;
+    }
     /** Close the broker connection (resolves once closed). The devices stay registered; connect() again reuses them. */
     disconnect() {
         return new Promise((resolve) => {
@@ -147,6 +171,36 @@ class Alex2MQTT extends events_1.EventEmitter {
             c.end(true, {}, () => resolve());
         });
     }
+    /**
+     * Declare a device:
+     *
+     *   const blinds = bridge.addDevice({ endpointId: "bedroom-blinds", name: "Bedroom Blinds",
+     *     categories: ["INTERIOR_BLIND"], manufacturerName: "Acme", description: "Roller blind by Acme" });
+     *
+     * Throws a DeclarationError when Alexa would reject the endpoint (an endpointId with a slash, a name with
+     * punctuation) or when the endpointId is registered already. Discovery lists Alexa.EndpointHealth for the device
+     * unless endpointHealth is false.
+     */
+    addDevice(definition) {
+        if (!this.client) {
+            throw new Error("Must call connect before creating devices");
+        }
+        const { endpointId, name, categories, endpointHealth, ...described } = definition;
+        // Without categories the device would take LIGHT, the default of registerDevice: here it is a mistake
+        const device = new Device_js_1.default(this.client, this.rootTopic, name, endpointId, (categories ?? []));
+        for (const [field, value] of Object.entries(described)) {
+            if (!DESCRIBED.includes(field))
+                throw new types_js_1.DeclarationError({ endpointId }, `${field} is not a field of an endpoint`);
+            if (value !== undefined)
+                Object.assign(device, { [field]: value });
+        }
+        (0, validate_js_1.checkEndpoint)(device.getJSON());
+        const existing = this.getDevice(endpointId);
+        if (existing)
+            throw new types_js_1.DeclarationError({ endpointId }, `is registered already, as "${existing.name}"`);
+        this.register(device, endpointHealth !== false);
+        return device;
+    }
     registerDevice(name, endpointId, displayCategory) {
         if (!this.client) {
             throw new Error("Must call connect before creating devices");
@@ -161,15 +215,16 @@ class Alex2MQTT extends events_1.EventEmitter {
             return existing;
         }
         this.log(`Creating new device with endpoint: ${endpointId}`);
-        const normalizedCategory = displayCategory === null
-            ? [DisplayCategory_js_1.DisplayCategory.LIGHT]
-            : Array.isArray(displayCategory)
-                ? displayCategory
-                : [displayCategory || DisplayCategory_js_1.DisplayCategory.LIGHT];
+        const normalizedCategory = Array.isArray(displayCategory) ? displayCategory : [displayCategory || enums_js_1.DisplayCategory.LIGHT];
         const device = new Device_js_1.default(this.client, this.rootTopic, name, endpointId, normalizedCategory);
+        this.register(device, false);
+        return device;
+    }
+    register(device, endpointHealth) {
+        device.alexaInterface = this.options.alexaInterface !== false;
+        device.endpointHealth = endpointHealth;
         device.onPublishError = (err) => this.fail(err); // a failed publish is an "error" event (when listened to), never a rejected send()
         this.devices.push(device);
-        return device;
     }
     /** Forget a device (its listeners with it). Returns false when there was none. */
     unregisterDevice(endpointId) {

dist/cjs/AlexaStatusMessage.js

@@ -1,13 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AlexaStatusMessage = exports.TemperatureSensorScale = exports.PowerController = exports.ThermostatMode = exports.EndpointHealth = void 0;
+exports.AlexaStatusMessage = exports.TemperatureSensorScale = exports.ThermostatMode = void 0;
 const crypto_1 = require("crypto");
-const AlexaInterface_js_1 = require("./AlexaInterface.js");
-var EndpointHealth;
-(function (EndpointHealth) {
-    EndpointHealth["OK"] = "OK";
-    EndpointHealth["UNREACHABLE"] = "UNREACHABLE";
-})(EndpointHealth || (exports.EndpointHealth = EndpointHealth = {}));
+const enums_js_1 = require("./compat/enums.js");
 var ThermostatMode;
 (function (ThermostatMode) {
     ThermostatMode["OFF"] = "OFF";
@@ -17,11 +12,6 @@ var ThermostatMode;
     ThermostatMode["ECO"] = "ECO";
     ThermostatMode["CUSTOM"] = "CUSTOM";
 })(ThermostatMode || (exports.ThermostatMode = ThermostatMode = {}));
-var PowerController;
-(function (PowerController) {
-    PowerController["ON"] = "ON";
-    PowerController["OFF"] = "OFF";
-})(PowerController || (exports.PowerController = PowerController = {}));
 var TemperatureSensorScale;
 (function (TemperatureSensorScale) {
     TemperatureSensorScale["CELSIUS"] = "CELSIUS";
@@ -102,10 +92,10 @@ class AlexaStatusMessage {
         return { context: this.isDeferred ? null : this.context, event: this.event };
     }
     addModeControllerProp(instance, value, uncertaintyInMs = 0) {
-        return this.addProperty(AlexaInterface_js_1.AlexaInterfaceType.MODE_CONTROLLER, "mode", value, uncertaintyInMs, instance);
+        return this.addProperty(enums_js_1.AlexaInterfaceType.MODE_CONTROLLER, "mode", value, uncertaintyInMs, instance);
     }
     addThermostatModeProp(mode, uncertaintyInMs = 0) {
-        return this.addProperty(AlexaInterface_js_1.AlexaInterfaceType.THERMOSTAT_CONTROLLER, "thermostatMode", mode, uncertaintyInMs);
+        return this.addProperty(enums_js_1.AlexaInterfaceType.THERMOSTAT_CONTROLLER, "thermostatMode", mode, uncertaintyInMs);
     }
     addEstimatedDeferralTime(seconds) {
         if (this.isDeferred) {
@@ -125,14 +115,14 @@ class AlexaStatusMessage {
                 : value,
             scale: "CELSIUS",
         };
-        return this.addProperty(AlexaInterface_js_1.AlexaInterfaceType.THERMOSTAT_CONTROLLER, name, tempValue, uncertaintyInMs);
+        return this.addProperty(enums_js_1.AlexaInterfaceType.THERMOSTAT_CONTROLLER, name, tempValue, uncertaintyInMs);
     }
     /** Alexa.EndpointHealth connectivity: EndpointHealth.OK / UNREACHABLE (the plain strings "OK" / "UNREACHABLE" are accepted too). */
     addHealthProp(health, uncertaintyInMs = 0) {
-        return this.addProperty(AlexaInterface_js_1.AlexaInterfaceType.ENDPOINT_HEALTH, "connectivity", { value: health }, uncertaintyInMs);
+        return this.addProperty(enums_js_1.AlexaInterfaceType.ENDPOINT_HEALTH, "connectivity", { value: health }, uncertaintyInMs);
     }
     addPowerControllerProp(power, uncertaintyInMs = 0) {
-        return this.addProperty(AlexaInterface_js_1.AlexaInterfaceType.POWER_CONTROLLER, "powerState", power, uncertaintyInMs);
+        return this.addProperty(enums_js_1.AlexaInterfaceType.POWER_CONTROLLER, "powerState", power, uncertaintyInMs);
     }
     addTemperatureSensorProp(scale, value, uncertaintyInMs = 0) {
         const tempValue = {
@@ -141,16 +131,16 @@ class AlexaStatusMessage {
                 : value,
             scale: "CELSIUS",
         };
-        return this.addProperty(AlexaInterface_js_1.AlexaInterfaceType.TEMPERATURE_SENSOR, "temperature", tempValue, uncertaintyInMs);
+        return this.addProperty(enums_js_1.AlexaInterfaceType.TEMPERATURE_SENSOR, "temperature", tempValue, uncertaintyInMs);
     }
     addBrightnessControllerProp(brightness, uncertaintyInMs = 0) {
-        return this.addProperty(AlexaInterface_js_1.AlexaInterfaceType.BRIGHTNESS_CONTROLLER, "brightness", brightness, uncertaintyInMs);
+        return this.addProperty(enums_js_1.AlexaInterfaceType.BRIGHTNESS_CONTROLLER, "brightness", brightness, uncertaintyInMs);
     }
     addColorTemperatureControllerProp(colorTemp, uncertaintyInMs = 0) {
-        return this.addProperty(AlexaInterface_js_1.AlexaInterfaceType.COLOR_TEMPERATURE_CONTROLLER, "colorTemperatureInKelvin", colorTemp, uncertaintyInMs);
+        return this.addProperty(enums_js_1.AlexaInterfaceType.COLOR_TEMPERATURE_CONTROLLER, "colorTemperatureInKelvin", colorTemp, uncertaintyInMs);
     }
     addToggleControllerProp(state, instance, uncertaintyInMs = 0) {
-        return this.addProperty(AlexaInterface_js_1.AlexaInterfaceType.TOGGLE_CONTROLLER, "toggleState", state, uncertaintyInMs, instance);
+        return this.addProperty(enums_js_1.AlexaInterfaceType.TOGGLE_CONTROLLER, "toggleState", state, uncertaintyInMs, instance);
     }
     addContextProp(prop) {
         this.context.properties.push(prop);

dist/cjs/Device.js

@@ -1,145 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const AlexaInterface_js_1 = require("./AlexaInterface.js");
-const DisplayCategory_js_1 = require("./DisplayCategory.js");
-const events_1 = require("events");
-const crypto_1 = require("crypto");
-const AlexaStatusMessage_js_1 = require("./AlexaStatusMessage.js");
-const AlexaErrorResponse_js_1 = require("./AlexaErrorResponse.js");
-class Device extends events_1.EventEmitter {
-    constructor(mqttClient, rootTopic, name, endpointId, displayCategory, description = "Alexa to Node.js bridge", manufacturerName = "Alex2Node", manufacturer = "Alex2Node", model = "Alex2Node_v1.0.0") {
-        super();
-        this.mqttClient = mqttClient;
-        this.rootTopic = rootTopic;
-        this.name = name;
-        this.endpointId = endpointId;
-        this.displayCategory = displayCategory;
-        this.description = description;
-        this.manufacturerName = manufacturerName;
-        this.manufacturer = manufacturer;
-        this.model = model;
-        this.softwareVersion = "1.0.0";
-        this.capabilities = [];
-    }
-    /** Internal (1.5.2): Alex2MQTT.connect() re-binds every registered device to its new broker client after a disconnect(). */
-    setMqttClient(client) {
-        this.mqttClient = client;
-    }
-    getName() {
-        return this.name;
-    }
-    setName(name) {
-        this.name = name;
-    }
-    getEndpointId() {
-        return this.endpointId;
-    }
-    setDisplayCategory(category) {
-        this.displayCategory = Array.isArray(category) ? category : [category];
-    }
-    getDisplayCategory() {
-        return this.displayCategory || [DisplayCategory_js_1.DisplayCategory.LIGHT];
-    }
-    setDescription(description) {
-        this.description = description;
-    }
-    getDescription() {
-        return this.description;
-    }
-    getErrorMessage(correlationToken) {
-        const msg = new AlexaErrorResponse_js_1.AlexaErrorResponse(correlationToken, this.rootTopic, this.endpointId, this.mqttClient);
-        msg.onPublishError = this.onPublishError;
-        return msg;
-    }
-    getStatusMessage(correlationToken, isResponse = false, isDeferred = false) {
-        const msg = new AlexaStatusMessage_js_1.AlexaStatusMessage(correlationToken, this.rootTopic, this.endpointId, this.mqttClient, isResponse, isDeferred);
-        msg.onPublishError = this.onPublishError;
-        return msg;
-    }
-    /**
-     * A proactive Alexa.ChangeReport (1.5.1): add the changed properties (the default target), optionally
-     * .unchanged() then the others, and .send() - it goes to <root>/changeReport, which Alex2MQTT forwards to the Alexa
-     * event gateway with the user's token. Alexa only accepts it for capabilities registered with proactivelyReported.
-     */
-    getChangeReport(cause = "PHYSICAL_INTERACTION") {
-        const msg = new AlexaStatusMessage_js_1.AlexaStatusMessage("", this.rootTopic, this.endpointId, this.mqttClient, false, false, cause);
-        msg.onPublishError = this.onPublishError;
-        return msg;
-    }
-    /**
-     * Alexa.SceneController: answer an Activate / Deactivate directive with ActivationStarted / DeactivationStarted
-     * (1.5.1). Resolves with the topic published to, or "" when the publish failed (never rejects, 1.5.2).
-     */
-    sendSceneResponse(correlationToken, activated, cause = "VOICE_INTERACTION", sendAsync = false) {
-        const payload = {
-            context: {},
-            event: {
-                header: { namespace: "Alexa.SceneController", name: activated ? "ActivationStarted" : "DeactivationStarted", messageId: (0, crypto_1.randomUUID)(), correlationToken, payloadVersion: "3" },
-                endpoint: { endpointId: this.endpointId },
-                payload: { cause: { type: cause }, timestamp: new Date().toISOString() },
-            },
-        };
-        const topic = `${this.rootTopic}/${this.endpointId}/${sendAsync ? "deferredResponse" : "alexaResponce"}`;
-        return new Promise((resolve) => {
-            this.mqttClient.publish(topic, JSON.stringify(payload), (err) => {
-                if (!err)
-                    return resolve(topic);
-                if (this.onPublishError)
-                    this.onPublishError(err); // -> the bridge's "error" event (when somebody listens)
-                resolve(""); // 1.5.1 rejected here, and an un-caught send() then killed the host on any broker hiccup
-            });
-        });
-    }
-    getCapabilities() {
-        return this.capabilities.slice();
-    }
-    setManufacturerName(name) {
-        this.manufacturerName = name;
-    }
-    getManufacturerName() {
-        return this.manufacturerName;
-    }
-    setManufacturer(manufacturer) {
-        this.manufacturer = manufacturer;
-    }
-    getManufacturer() {
-        return this.manufacturer;
-    }
-    setModel(model) {
-        this.model = model;
-    }
-    getModel() {
-        return this.model;
-    }
-    getSoftwareVersion() {
-        return this.softwareVersion;
-    }
-    /** Add a capability. 1.5.1: options.retrievable / proactivelyReported / instance (a change report needs proactivelyReported). */
-    addCapability(type, options = {}) {
-        const newCapability = new AlexaInterface_js_1.AlexaInterface(type, options.retrievable ?? true, options.proactivelyReported ?? false, options.instance ?? "");
-        this.capabilities.push(newCapability);
-        // console.log(
-        //   `Created new interface with type: ${newCapability.getTypeString()}`
-        // );
-        return newCapability;
-    }
-    getJSON() {
-        return {
-            endpointId: this.endpointId,
-            friendlyName: this.name,
-            description: this.description,
-            manufacturerName: this.manufacturerName,
-            displayCategories: this.getDisplayCategory(),
-            additionalAttributes: {
-                manufacturer: this.manufacturer,
-                model: this.model,
-                serialNumber: "Alex2Node",
-                firmwareVersion: "1.0.0",
-                softwareVersion: this.softwareVersion,
-                customIdentifier: "Alex2Node",
-            },
-            capabilities: this.capabilities.map((cap) => cap.getJSON()),
-        };
-    }
-}
-exports.default = Device;

dist/cjs/DisplayCategory.js

@@ -1,64 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DisplayCategory = void 0;
-var DisplayCategory;
-(function (DisplayCategory) {
-    DisplayCategory["ACTIVITY_TRIGGER"] = "ACTIVITY_TRIGGER";
-    DisplayCategory["AIR_CONDITIONER"] = "AIR_CONDITIONER";
-    DisplayCategory["AIR_FRESHENER"] = "AIR_FRESHENER";
-    DisplayCategory["AIR_PURIFIER"] = "AIR_PURIFIER";
-    DisplayCategory["AIR_QUALITY_MONITOR"] = "AIR_QUALITY_MONITOR";
-    DisplayCategory["ALEXA_VOICE_ENABLED"] = "ALEXA_VOICE_ENABLED";
-    DisplayCategory["AUTO_ACCESSORY"] = "AUTO_ACCESSORY";
-    DisplayCategory["BLUETOOTH_SPEAKER"] = "BLUETOOTH_SPEAKER";
-    DisplayCategory["CAMERA"] = "CAMERA";
-    DisplayCategory["CHRISTMAS_TREE"] = "CHRISTMAS_TREE";
-    DisplayCategory["COFFEE_MAKER"] = "COFFEE_MAKER";
-    DisplayCategory["COMPUTER"] = "COMPUTER";
-    DisplayCategory["CONTACT_SENSOR"] = "CONTACT_SENSOR";
-    DisplayCategory["DISHWASHER"] = "DISHWASHER";
-    DisplayCategory["DOOR"] = "DOOR";
-    DisplayCategory["DOORBELL"] = "DOORBELL";
-    DisplayCategory["DRYER"] = "DRYER";
-    DisplayCategory["EXTERIOR_BLIND"] = "EXTERIOR_BLIND";
-    DisplayCategory["FAN"] = "FAN";
-    DisplayCategory["GAME_CONSOLE"] = "GAME_CONSOLE";
-    DisplayCategory["GARAGE_DOOR"] = "GARAGE_DOOR";
-    DisplayCategory["HEADPHONES"] = "HEADPHONES";
-    DisplayCategory["HUB"] = "HUB";
-    DisplayCategory["INTERIOR_BLIND"] = "INTERIOR_BLIND";
-    DisplayCategory["LAPTOP"] = "LAPTOP";
-    DisplayCategory["LIGHT"] = "LIGHT";
-    DisplayCategory["MICROWAVE"] = "MICROWAVE";
-    DisplayCategory["MOBILE_PHONE"] = "MOBILE_PHONE";
-    DisplayCategory["MOTION_SENSOR"] = "MOTION_SENSOR";
-    DisplayCategory["MUSIC_SYSTEM"] = "MUSIC_SYSTEM";
-    DisplayCategory["NETWORK_HARDWARE"] = "NETWORK_HARDWARE";
-    DisplayCategory["OTHER"] = "OTHER";
-    DisplayCategory["OVEN"] = "OVEN";
-    DisplayCategory["PHONE"] = "PHONE";
-    DisplayCategory["PRINTER"] = "PRINTER";
-    DisplayCategory["REMOTE"] = "REMOTE";
-    DisplayCategory["ROUTER"] = "ROUTER";
-    DisplayCategory["SCENE_TRIGGER"] = "SCENE_TRIGGER";
-    DisplayCategory["SCREEN"] = "SCREEN";
-    DisplayCategory["SECURITY_PANEL"] = "SECURITY_PANEL";
-    DisplayCategory["SECURITY_SYSTEM"] = "SECURITY_SYSTEM";
-    DisplayCategory["SLOW_COOKER"] = "SLOW_COOKER";
-    DisplayCategory["SMARTLOCK"] = "SMARTLOCK";
-    DisplayCategory["SMARTPLUG"] = "SMARTPLUG";
-    DisplayCategory["SPEAKER"] = "SPEAKER";
-    DisplayCategory["STREAMING_DEVICE"] = "STREAMING_DEVICE";
-    DisplayCategory["SWITCH"] = "SWITCH";
-    DisplayCategory["TABLET"] = "TABLET";
-    DisplayCategory["TEMPERATURE_SENSOR"] = "TEMPERATURE_SENSOR";
-    DisplayCategory["THERMOSTAT"] = "THERMOSTAT";
-    DisplayCategory["TV"] = "TV";
-    DisplayCategory["VACUUM_CLEANER"] = "VACUUM_CLEANER";
-    DisplayCategory["VACUUM"] = "VACUUM";
-    /** Not on the list of display categories any more; kept for 1.x callers. */
-    DisplayCategory["VEHICLE"] = "VEHICLE";
-    DisplayCategory["WASHER"] = "WASHER";
-    DisplayCategory["WATER_HEATER"] = "WATER_HEATER";
-    DisplayCategory["WEARABLE"] = "WEARABLE";
-})(DisplayCategory || (exports.DisplayCategory = DisplayCategory = {}));

dist/cjs/compat/ActionMapping.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ActionMapping = void 0;
+const types_js_1 = require("../registry/types.js");
+/**
+ * A semantics action mapping of 1.x: the phrases "open", "close", "raise", "lower" for one directive of the
+ * capability it is added to.
+ *
+ *   toggle.addActionMapping(new ActionMapping([AlexaActions.Close], "TurnOff"));
+ *   lift.addActionMapping(new ActionMapping([AlexaActions.Open], "SetRangeValue", { rangeValue: 100 }));
+ */
+class ActionMapping {
+    /**
+     * directivePayload is the payload object of the directive (alexa-discovery-objects.html, "ActionMappings object").
+     * 1.x took a string and put it into discovery as one. A string that holds a JSON object is parsed; any other
+     * string throws a DeclarationError.
+     */
+    constructor(actions, directiveName, directivePayload) {
+        this.type = "ActionsToDirective";
+        this.actions = actions;
+        this.directive = { name: directiveName };
+        if (typeof directivePayload === "string") {
+            if (directivePayload === "")
+                return;
+            this.directive.payload = objectIn(directivePayload, directiveName);
+            this.deprecation = `the payload of the action mapping for ${directiveName} is a JSON string, pass the object`;
+        }
+        else if (directivePayload) {
+            this.directive.payload = directivePayload;
+        }
+    }
+    toJSON() {
+        return { "@type": this.type, actions: this.actions, directive: this.directive };
+    }
+}
+exports.ActionMapping = ActionMapping;
+function objectIn(text, directiveName) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        value = undefined;
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new types_js_1.DeclarationError({}, `the payload of the action mapping for ${directiveName} is an object, got the string ${JSON.stringify(text)}`);
+    }
+    return value;
+}

dist/cjs/compat/AlexaInterface.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AlexaInterface = void 0;
+const Capability_js_1 = require("../device/Capability.js");
+const index_js_1 = require("../registry/index.js");
+const resources_js_1 = require("../registry/resources.js");
+/**
+ * A capability as 1.x declares it: device.addCapability(type, options), then the add and set methods below. It is a
+ * Capability, so what the methods set reaches discovery the same way as the options of device.add(). Nothing is
+ * refused here except an interface name the registry does not have: what Alexa would reject is logged by the bridge
+ * when it answers a discovery.
+ */
+class AlexaInterface extends Capability_js_1.Capability {
+    constructor(type, retrievable = true, proactivelyReported = false, instance = "") {
+        super(index_js_1.registry.get(type), { retrievable, proactivelyReported, instance, options: {} });
+    }
+    /** The namespace of the interface, which is the value of its AlexaInterfaceType member. */
+    get type() {
+        return this.descriptor.namespace;
+    }
+    addActionMapping(mapping) {
+        var _a;
+        const semantics = ((_a = this.options).semantics ?? (_a.semantics = {}));
+        (semantics.actionMappings ?? (semantics.actionMappings = [])).push(mapping.toJSON());
+        if (mapping.deprecation)
+            this.notes.push(mapping.deprecation);
+    }
+    addFriendlyName(name, locale) {
+        this.friendlyNames.push((0, resources_js_1.text)(name, locale));
+    }
+    /** The modes of a ModeController, as { value, modeResources } objects. */
+    addSupportedModes(modes) {
+        this.options.supportedModes = modes;
+    }
+    setInstance(name) {
+        this.instance = name;
+    }
+    getType() {
+        return this.type;
+    }
+    /** @deprecated The same as getType(). */
+    getTypeString() {
+        return this.type;
+    }
+    /** @deprecated Read descriptor.version. */
+    getVersion() {
+        return this.descriptor.version;
+    }
+    /** @deprecated Read the keys of descriptor.properties. */
+    getProps() {
+        return Object.keys(this.descriptor.properties);
+    }
+    getJSON() {
+        return super.toJSON();
+    }
+    // 1.x callers corrected the discovery JSON by replacing getJSON on the object: discovery goes through it
+    toJSON() {
+        return this.getJSON();
+    }
+}
+exports.AlexaInterface = AlexaInterface;

dist/cjs/compat/enums.js

@@ -1,7 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AlexaInterface = exports.AlexaInterfaceType = void 0;
-const index_js_1 = require("./registry/index.js");
+exports.EndpointHealth = exports.PowerController = exports.PowerState = exports.AlexaActions = exports.DisplayCategory = exports.AlexaInterfaceType = void 0;
+// The enums of 1.x, under their 1.x names.
+const EndpointHealth_js_1 = require("../registry/interfaces/EndpointHealth.js");
+const PowerController_js_1 = require("../registry/interfaces/PowerController.js");
+/** Every interface name of 1.x. registry.get() takes a member as it takes the namespace, which is its value. */
 var AlexaInterfaceType;
 (function (AlexaInterfaceType) {
     AlexaInterfaceType["APPLICATION_STATE_REPORTER"] = "Alexa.ApplicationStateReporter";
@@ -73,97 +76,88 @@ var AlexaInterfaceType;
     AlexaInterfaceType["USER_PREFERENCE"] = "Alexa.UserPreference";
     AlexaInterfaceType["VIDEO_RECORDER"] = "Alexa.VideoRecorder";
     AlexaInterfaceType["WAKE_ON_LAN_CONTROLLER"] = "Alexa.WakeOnLANController";
+    /** Not an interface: declaring it throws a DeclarationError. Kept because 1.x had it. */
     AlexaInterfaceType["UNKNOWN"] = "UNKNOWN";
 })(AlexaInterfaceType || (exports.AlexaInterfaceType = AlexaInterfaceType = {}));
-class AlexaInterface {
-    constructor(type, retrievable = true, proactivelyReported = false, instance = "") {
-        this.type = type;
-        this.retrievable = retrievable;
-        this.proactivelyReported = proactivelyReported;
-        this.instance = instance;
-        this.friendlyNames = [];
-        this.actionMappings = [];
-        this.supportedModes = [];
-    }
-    addActionMapping(mapping) {
-        this.actionMappings.push(mapping);
-    }
-    addFriendlyName(name, locale) {
-        this.friendlyNames.push({ text: name, locale });
-    }
-    /** The modes of a ModeController: { value, modeResources } objects as Alexa wants them (plain strings pass through as given). */
-    addSupportedModes(modes) {
-        this.supportedModes = modes;
-    }
-    setInstance(name) {
-        this.instance = name;
-    }
-    getType() {
-        return this.type;
-    }
-    getTypeString() {
-        return this.type;
-    }
-    /** The version of the interface, from its descriptor. "UNKNOWN" for a name the registry does not have. */
-    getVersion() {
-        return index_js_1.registry.has(this.type) ? index_js_1.registry.get(this.type).version : "UNKNOWN";
-    }
-    /** The names of the properties the interface reports, from its descriptor. */
-    getProps() {
-        return index_js_1.registry.has(this.type) ? Object.keys(index_js_1.registry.get(this.type).properties) : [];
-    }
-    getJSON() {
-        const doc = {
-            interface: this.getTypeString(),
-            version: this.getVersion(),
-            type: "AlexaInterface",
-            properties: {
-                retrievable: this.retrievable,
-                proactivelyReported: this.proactivelyReported,
-                supported: this.getProps().map(name => ({ name })),
-            },
-        };
-        if (this.type == AlexaInterfaceType.SCENE_CONTROLLER) {
-            // Alexa.SceneController v3 carries no properties block: supportsDeactivation + proactivelyReported at the top level
-            delete doc.properties;
-            doc.supportsDeactivation = true;
-            doc.proactivelyReported = this.proactivelyReported;
-        }
-        else if (this.type == AlexaInterfaceType.THERMOSTAT_CONTROLLER) {
-            doc.configuration = {
-                "supportedModes": ["HEAT", "COOL", "AUTO", "OFF"],
-                "supportsScheduling": false
-            };
-        }
-        else if (this.supportedModes.length > 0) {
-            doc["configuration"] = {
-                ordered: true,
-                supportedModes: this.supportedModes,
-            };
-        }
-        if (this.instance) {
-            doc.instance = this.instance;
-        }
-        if (this.friendlyNames.length > 0) {
-            const capabilityResources = doc["capabilityResources"] || {};
-            const friendlyNamesArray = capabilityResources["friendlyNames"] || [];
-            this.friendlyNames.forEach((fn) => {
-                const friendlyNameObj = { "@type": "text" };
-                friendlyNameObj["value"] = {
-                    text: fn.text,
-                    locale: fn.locale,
-                };
-                friendlyNamesArray.push(friendlyNameObj);
-            });
-            capabilityResources.friendlyNames = friendlyNamesArray;
-            doc["capabilityResources"] = capabilityResources;
-        }
-        if (this.actionMappings.length > 0) {
-            doc.semantics = {
-                actionMappings: this.actionMappings.map((am) => am.toJSON()),
-            };
-        }
-        return doc;
-    }
-}
-exports.AlexaInterface = AlexaInterface;
+var DisplayCategory;
+(function (DisplayCategory) {
+    DisplayCategory["ACTIVITY_TRIGGER"] = "ACTIVITY_TRIGGER";
+    DisplayCategory["AIR_CONDITIONER"] = "AIR_CONDITIONER";
+    DisplayCategory["AIR_FRESHENER"] = "AIR_FRESHENER";
+    DisplayCategory["AIR_PURIFIER"] = "AIR_PURIFIER";
+    DisplayCategory["AIR_QUALITY_MONITOR"] = "AIR_QUALITY_MONITOR";
+    DisplayCategory["ALEXA_VOICE_ENABLED"] = "ALEXA_VOICE_ENABLED";
+    DisplayCategory["AUTO_ACCESSORY"] = "AUTO_ACCESSORY";
+    DisplayCategory["BLUETOOTH_SPEAKER"] = "BLUETOOTH_SPEAKER";
+    DisplayCategory["CAMERA"] = "CAMERA";
+    DisplayCategory["CHRISTMAS_TREE"] = "CHRISTMAS_TREE";
+    DisplayCategory["COFFEE_MAKER"] = "COFFEE_MAKER";
+    DisplayCategory["COMPUTER"] = "COMPUTER";
+    DisplayCategory["CONTACT_SENSOR"] = "CONTACT_SENSOR";
+    DisplayCategory["DISHWASHER"] = "DISHWASHER";
+    DisplayCategory["DOOR"] = "DOOR";
+    DisplayCategory["DOORBELL"] = "DOORBELL";
+    DisplayCategory["DRYER"] = "DRYER";
+    DisplayCategory["EXTERIOR_BLIND"] = "EXTERIOR_BLIND";
+    DisplayCategory["FAN"] = "FAN";
+    DisplayCategory["GAME_CONSOLE"] = "GAME_CONSOLE";
+    DisplayCategory["GARAGE_DOOR"] = "GARAGE_DOOR";
+    DisplayCategory["HEADPHONES"] = "HEADPHONES";
+    DisplayCategory["HUB"] = "HUB";
+    DisplayCategory["INTERIOR_BLIND"] = "INTERIOR_BLIND";
+    DisplayCategory["LAPTOP"] = "LAPTOP";
+    DisplayCategory["LIGHT"] = "LIGHT";
+    DisplayCategory["MICROWAVE"] = "MICROWAVE";
+    DisplayCategory["MOBILE_PHONE"] = "MOBILE_PHONE";
+    DisplayCategory["MOTION_SENSOR"] = "MOTION_SENSOR";
+    DisplayCategory["MUSIC_SYSTEM"] = "MUSIC_SYSTEM";
+    DisplayCategory["NETWORK_HARDWARE"] = "NETWORK_HARDWARE";
+    DisplayCategory["OTHER"] = "OTHER";
+    DisplayCategory["OVEN"] = "OVEN";
+    DisplayCategory["PHONE"] = "PHONE";
+    DisplayCategory["PRINTER"] = "PRINTER";
+    DisplayCategory["REMOTE"] = "REMOTE";
+    DisplayCategory["ROUTER"] = "ROUTER";
+    DisplayCategory["SCENE_TRIGGER"] = "SCENE_TRIGGER";
+    DisplayCategory["SCREEN"] = "SCREEN";
+    DisplayCategory["SECURITY_PANEL"] = "SECURITY_PANEL";
+    DisplayCategory["SECURITY_SYSTEM"] = "SECURITY_SYSTEM";
+    DisplayCategory["SLOW_COOKER"] = "SLOW_COOKER";
+    DisplayCategory["SMARTLOCK"] = "SMARTLOCK";
+    DisplayCategory["SMARTPLUG"] = "SMARTPLUG";
+    DisplayCategory["SPEAKER"] = "SPEAKER";
+    DisplayCategory["STREAMING_DEVICE"] = "STREAMING_DEVICE";
+    DisplayCategory["SWITCH"] = "SWITCH";
+    DisplayCategory["TABLET"] = "TABLET";
+    DisplayCategory["TEMPERATURE_SENSOR"] = "TEMPERATURE_SENSOR";
+    DisplayCategory["THERMOSTAT"] = "THERMOSTAT";
+    DisplayCategory["TV"] = "TV";
+    DisplayCategory["VACUUM_CLEANER"] = "VACUUM_CLEANER";
+    DisplayCategory["VACUUM"] = "VACUUM";
+    /** Not on the list of display categories any more; kept for 1.x callers. */
+    DisplayCategory["VEHICLE"] = "VEHICLE";
+    DisplayCategory["WASHER"] = "WASHER";
+    DisplayCategory["WATER_HEATER"] = "WATER_HEATER";
+    DisplayCategory["WEARABLE"] = "WEARABLE";
+})(DisplayCategory || (exports.DisplayCategory = DisplayCategory = {}));
+var AlexaActions;
+(function (AlexaActions) {
+    AlexaActions["Open"] = "Alexa.Actions.Open";
+    AlexaActions["Close"] = "Alexa.Actions.Close";
+    AlexaActions["Raise"] = "Alexa.Actions.Raise";
+    AlexaActions["Lower"] = "Alexa.Actions.Lower";
+    AlexaActions["SetEcoOn"] = "Alexa.Actions.SetEcoOn";
+    AlexaActions["SetEcoOff"] = "Alexa.Actions.SetEcoOff";
+})(AlexaActions || (exports.AlexaActions = AlexaActions = {}));
+/** The values of powerState and toggleState. */
+exports.PowerState = { ON: "ON", OFF: "OFF" };
+const Connectivity = { OK: "OK", UNREACHABLE: "UNREACHABLE" };
+// PowerController and EndpointHealth were enums in 1.x and are the names of two interfaces. One export serves both:
+// the descriptor, which also has the members of the enum, and a type of the same name for the values.
+/**
+ * The Alexa.PowerController interface, for device.add(). PowerController.ON and PowerController.OFF are the 1.x enum
+ * of power states and stay until 3.0: PowerState has the same two members.
+ */
+exports.PowerController = Object.assign(PowerController_js_1.PowerController, exports.PowerState);
+/** The Alexa.EndpointHealth interface, for device.add(). EndpointHealth.OK and EndpointHealth.UNREACHABLE are the 1.x enum of connectivity values. */
+exports.EndpointHealth = Object.assign(EndpointHealth_js_1.EndpointHealth, Connectivity);

dist/cjs/device/Capability.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Capability = exports.commonOptions = void 0;
+const schema_js_1 = require("../registry/schema.js");
+/** The same as a schema. The friendly names are checked with the instance, by the rules of the interface. */
+exports.commonOptions = schema_js_1.s.object({
+    instance: schema_js_1.s.optional(schema_js_1.s.string()),
+    friendlyNames: schema_js_1.s.optional(schema_js_1.s.array(schema_js_1.s.unknown())),
+    retrievable: schema_js_1.s.optional(schema_js_1.s.boolean()),
+    proactivelyReported: schema_js_1.s.optional(schema_js_1.s.boolean()),
+    nonControllable: schema_js_1.s.optional(schema_js_1.s.boolean()),
+});
+/** One interface as an endpoint declares it: the descriptor, and what the declaration says about this endpoint. */
+class Capability {
+    constructor(descriptor, declared) {
+        this.descriptor = descriptor;
+        /** The endpoint the capability is declared on; the device sets it. */
+        this.endpointId = "";
+        /** What the bridge logs about the declaration, once, when it answers a discovery. */
+        this.notes = [];
+        this.instance = declared.instance ?? "";
+        this.friendlyNames = declared.friendlyNames ?? [];
+        this.retrievable = declared.retrievable ?? true;
+        this.proactivelyReported = declared.proactivelyReported ?? false;
+        this.nonControllable = declared.nonControllable;
+        this.options = declared.options;
+    }
+    get namespace() {
+        return this.descriptor.namespace;
+    }
+    /** Mappings of "open", "close", "raise", "lower" and of states, when the declaration has any. */
+    get semantics() {
+        const { semantics } = this.options;
+        const mapped = (semantics?.actionMappings?.length ?? 0) + (semantics?.stateMappings?.length ?? 0);
+        return mapped > 0 ? semantics : undefined;
+    }
+    /** The capability object for discovery, its fields in the order of the example on alexa-discovery-objects.html. */
+    toJSON() {
+        const { descriptor, semantics } = this;
+        const extras = descriptor.discovery ? descriptor.discovery(this) : {};
+        const json = {
+            type: "AlexaInterface",
+            interface: descriptor.namespace,
+            ...(this.instance ? { instance: this.instance } : {}),
+            version: descriptor.version,
+        };
+        if (extras.properties !== false) {
+            json.properties = {
+                supported: Object.keys(descriptor.properties).map((name) => ({ name })),
+                proactivelyReported: this.proactivelyReported,
+                retrievable: this.retrievable,
+            };
+            if (this.nonControllable !== undefined)
+                json.properties.nonControllable = this.nonControllable;
+        }
+        if (this.friendlyNames.length > 0)
+            json.capabilityResources = { friendlyNames: this.friendlyNames };
+        if (extras.configuration)
+            json.configuration = extras.configuration;
+        if (extras.configurations)
+            json.configurations = extras.configurations;
+        if (semantics)
+            json.semantics = semantics;
+        return { ...json, ...extras.topLevel };
+    }
+}
+exports.Capability = Capability;

dist/cjs/device/Device.js

@@ -0,0 +1,270 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const events_1 = require("events");
+const crypto_1 = require("crypto");
+const AlexaErrorResponse_js_1 = require("../AlexaErrorResponse.js");
+const AlexaStatusMessage_js_1 = require("../AlexaStatusMessage.js");
+const AlexaInterface_js_1 = require("../compat/AlexaInterface.js");
+const enums_js_1 = require("../compat/enums.js");
+const Alexa_js_1 = require("../registry/interfaces/Alexa.js");
+const EndpointHealth_js_1 = require("../registry/interfaces/EndpointHealth.js");
+const schema_js_1 = require("../registry/schema.js");
+const types_js_1 = require("../registry/types.js");
+const Capability_js_1 = require("./Capability.js");
+const validate_js_1 = require("./validate.js");
+class Device extends events_1.EventEmitter {
+    constructor(mqttClient, rootTopic, name, endpointId, displayCategory, description = "Alexa to Node.js bridge", manufacturerName = "Alex2Node", manufacturer = "Alex2Node", model = "Alex2Node_v1.0.0") {
+        super();
+        this.mqttClient = mqttClient;
+        this.rootTopic = rootTopic;
+        this.name = name;
+        this.endpointId = endpointId;
+        this.displayCategory = displayCategory;
+        this.description = description;
+        this.manufacturerName = manufacturerName;
+        this.manufacturer = manufacturer;
+        this.model = model;
+        this.softwareVersion = "1.0.0";
+        this.serialNumber = "Alex2Node";
+        this.firmwareVersion = "1.0.0";
+        this.customIdentifier = "Alex2Node";
+        /**
+         * Discovery lists the Alexa interface on the endpoint (alexa-interface.html: "You must explicitly identify your
+         * support for the Alexa interface"). The bridge sets it from its alexaInterface option.
+         */
+        this.alexaInterface = true;
+        /**
+         * Discovery lists Alexa.EndpointHealth when the device did not declare it and is not a scene. On for a device of
+         * bridge.addDevice(), off for one of registerDevice(), which is announced as 1.x announced it.
+         */
+        this.endpointHealth = false;
+        this.capabilities = [];
+    }
+    /** Internal (1.5.2): Alex2MQTT.connect() re-binds every registered device to its new broker client after a disconnect(). */
+    setMqttClient(client) {
+        this.mqttClient = client;
+    }
+    getName() {
+        return this.name;
+    }
+    setName(name) {
+        this.name = name;
+    }
+    getEndpointId() {
+        return this.endpointId;
+    }
+    setDisplayCategory(category) {
+        this.displayCategory = Array.isArray(category) ? category : [category];
+    }
+    getDisplayCategory() {
+        return this.displayCategory || [enums_js_1.DisplayCategory.LIGHT];
+    }
+    setDescription(description) {
+        this.description = description;
+    }
+    getDescription() {
+        return this.description;
+    }
+    getErrorMessage(correlationToken) {
+        const msg = new AlexaErrorResponse_js_1.AlexaErrorResponse(correlationToken, this.rootTopic, this.endpointId, this.mqttClient);
+        msg.onPublishError = this.onPublishError;
+        return msg;
+    }
+    getStatusMessage(correlationToken, isResponse = false, isDeferred = false) {
+        const msg = new AlexaStatusMessage_js_1.AlexaStatusMessage(correlationToken, this.rootTopic, this.endpointId, this.mqttClient, isResponse, isDeferred);
+        msg.onPublishError = this.onPublishError;
+        return msg;
+    }
+    /**
+     * A proactive Alexa.ChangeReport (1.5.1): add the changed properties (the default target), optionally
+     * .unchanged() then the others, and .send() - it goes to <root>/changeReport, which Alex2MQTT forwards to the Alexa
+     * event gateway with the user's token. Alexa only accepts it for capabilities registered with proactivelyReported.
+     */
+    getChangeReport(cause = "PHYSICAL_INTERACTION") {
+        const msg = new AlexaStatusMessage_js_1.AlexaStatusMessage("", this.rootTopic, this.endpointId, this.mqttClient, false, false, cause);
+        msg.onPublishError = this.onPublishError;
+        return msg;
+    }
+    /**
+     * Alexa.SceneController: answer an Activate / Deactivate directive with ActivationStarted / DeactivationStarted
+     * (1.5.1). Resolves with the topic published to, or "" when the publish failed (never rejects, 1.5.2).
+     */
+    sendSceneResponse(correlationToken, activated, cause = "VOICE_INTERACTION", sendAsync = false) {
+        const payload = {
+            context: {},
+            event: {
+                header: { namespace: "Alexa.SceneController", name: activated ? "ActivationStarted" : "DeactivationStarted", messageId: (0, crypto_1.randomUUID)(), correlationToken, payloadVersion: "3" },
+                endpoint: { endpointId: this.endpointId },
+                payload: { cause: { type: cause }, timestamp: new Date().toISOString() },
+            },
+        };
+        const topic = `${this.rootTopic}/${this.endpointId}/${sendAsync ? "deferredResponse" : "alexaResponce"}`;
+        return new Promise((resolve) => {
+            this.mqttClient.publish(topic, JSON.stringify(payload), (err) => {
+                if (!err)
+                    return resolve(topic);
+                if (this.onPublishError)
+                    this.onPublishError(err); // -> the bridge's "error" event (when somebody listens)
+                resolve(""); // 1.5.1 rejected here, and an un-caught send() then killed the host on any broker hiccup
+            });
+        });
+    }
+    /** The capabilities the device declared, in the order it declared them. */
+    getCapabilities() {
+        return this.capabilities.slice();
+    }
+    setManufacturerName(name) {
+        this.manufacturerName = name;
+    }
+    getManufacturerName() {
+        return this.manufacturerName;
+    }
+    setManufacturer(manufacturer) {
+        this.manufacturer = manufacturer;
+    }
+    getManufacturer() {
+        return this.manufacturer;
+    }
+    setModel(model) {
+        this.model = model;
+    }
+    getModel() {
+        return this.model;
+    }
+    getSoftwareVersion() {
+        return this.softwareVersion;
+    }
+    /**
+     * Declare an interface of the device:
+     *
+     *   lamp.add(PowerController, { proactivelyReported: true });
+     *   blinds.add(RangeController, { instance: "Blind.Lift", friendlyNames: [asset("Alexa.Setting.Opening")],
+     *     range: { min: 0, max: 100, precision: 1 } });
+     *
+     * Throws a DeclarationError that names the endpoint, the interface and the instance when Alexa would reject the
+     * capability; the device is then as it was before the call.
+     */
+    add(descriptor, ...[options]) {
+        const where = { endpointId: this.endpointId, namespace: descriptor.namespace, instance: "" };
+        if (options !== undefined && (typeof options !== "object" || options === null)) {
+            throw new types_js_1.DeclarationError(where, "the options of a declaration are an object");
+        }
+        try {
+            const { instance, friendlyNames, retrievable, proactivelyReported, nonControllable, ...given } = Capability_js_1.commonOptions.parse(options ?? {});
+            where.instance = instance ?? "";
+            const common = { instance, friendlyNames: friendlyNames, retrievable, proactivelyReported, nonControllable };
+            const capability = new Capability_js_1.Capability(descriptor, { ...common, options: interfaceOptions(descriptor, given) });
+            capability.endpointId = this.endpointId;
+            (0, validate_js_1.checkCapability)(capability, descriptor, this.view(this.capabilities));
+            (0, validate_js_1.checkCapabilityCount)(this.endpointId, this.announced([...this.capabilities, capability]).length);
+            this.capabilities.push(capability);
+            return capability;
+        }
+        catch (err) {
+            throw err instanceof schema_js_1.SchemaError ? new types_js_1.DeclarationError(where, err.message) : err;
+        }
+    }
+    /**
+     * Declare an interface the 1.x way, by its name: options.retrievable / proactivelyReported / instance, then the
+     * add and set methods of the capability that is returned. Throws for a name that is not an interface. Anything
+     * else Alexa would reject is not refused here: check() lists it.
+     */
+    addCapability(type, options = {}) {
+        let capability;
+        try {
+            capability = new AlexaInterface_js_1.AlexaInterface(type, options.retrievable ?? true, options.proactivelyReported ?? false, options.instance ?? "");
+        }
+        catch (err) {
+            throw err instanceof types_js_1.DeclarationError ? new types_js_1.DeclarationError({ endpointId: this.endpointId }, err.problem) : err;
+        }
+        capability.endpointId = this.endpointId;
+        this.capabilities.push(capability);
+        return capability;
+    }
+    /**
+     * What Alexa would reject in the device as it is declared now, one line for each: a name with punctuation, an
+     * interface declared twice. Also what a capability noted about its declaration. Empty when there is nothing.
+     * The bridge logs the lines when it answers a discovery.
+     */
+    check() {
+        const lines = [];
+        const attempt = (rule) => {
+            try {
+                rule();
+            }
+            catch (err) {
+                if (!(err instanceof types_js_1.DeclarationError))
+                    throw err;
+                lines.push(err.message);
+            }
+        };
+        attempt(() => (0, validate_js_1.checkEndpoint)(this.fields()));
+        this.capabilities.forEach((capability, i) => {
+            capability.endpointId = this.endpointId;
+            attempt(() => (0, validate_js_1.checkCapability)(capability, capability.descriptor, this.view(this.capabilities.slice(0, i))));
+            const notes = [...capability.notes];
+            const { tier, properties } = capability.descriptor;
+            if (tier === 3 && Object.keys(properties).length === 0 && capability.toJSON().properties) {
+                notes.push("no property list known, discovery lists it with no supported properties");
+            }
+            for (const note of notes)
+                lines.push(new types_js_1.DeclarationError(capability, note).message);
+        });
+        attempt(() => (0, validate_js_1.checkCapabilityCount)(this.endpointId, this.announced(this.capabilities).length));
+        return lines;
+    }
+    /** The endpoint object for discovery. */
+    getJSON() {
+        return { ...this.fields(), capabilities: this.announced(this.capabilities).map((capability) => capability.toJSON()) };
+    }
+    fields() {
+        return {
+            endpointId: this.endpointId,
+            friendlyName: this.name,
+            description: this.description,
+            manufacturerName: this.manufacturerName,
+            displayCategories: this.getDisplayCategory(),
+            additionalAttributes: {
+                manufacturer: this.manufacturer,
+                model: this.model,
+                serialNumber: this.serialNumber,
+                firmwareVersion: this.firmwareVersion,
+                softwareVersion: this.softwareVersion,
+                customIdentifier: this.customIdentifier,
+            },
+            ...(this.cookie ? { cookie: this.cookie } : {}),
+        };
+    }
+    // The endpoint as the rules of a capability see it
+    view(declaredBefore) {
+        return {
+            endpointId: this.endpointId,
+            friendlyName: this.name,
+            description: this.description,
+            displayCategories: this.getDisplayCategory(),
+            capabilities: declaredBefore,
+        };
+    }
+    // What discovery lists: the declared capabilities, then the ones the library adds
+    announced(declared) {
+        const has = (namespace) => declared.some((capability) => capability.namespace === namespace);
+        const added = [];
+        // alexa-scenecontroller.html, "Discovery": a scene is not a physical device and has no Alexa.EndpointHealth
+        if (this.endpointHealth && !has(EndpointHealth_js_1.EndpointHealth.namespace) && !has("Alexa.SceneController")) {
+            added.push(new Capability_js_1.Capability(EndpointHealth_js_1.EndpointHealth, { options: {} }));
+        }
+        if (this.alexaInterface && !has(Alexa_js_1.Alexa.namespace))
+            added.push(new Capability_js_1.Capability(Alexa_js_1.Alexa, { options: {} }));
+        return [...declared, ...added];
+    }
+}
+// The options of the interface itself, checked by the schema of its descriptor
+function interfaceOptions(descriptor, given) {
+    if (descriptor.options)
+        return descriptor.options.parse(given);
+    const [unknown] = Object.keys(given);
+    if (unknown !== undefined)
+        throw new schema_js_1.SchemaError(unknown, "not an option of the interface");
+    return {};
+}
+exports.default = Device;

dist/cjs/device/validate.js

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkEndpoint = checkEndpoint;
+exports.checkCapabilityCount = checkCapabilityCount;
+exports.checkCapability = checkCapability;
+// What Alexa rejects at discovery, checked where a device is declared. Alexa gives no reason when it drops an
+// endpoint: the user hears "no new devices found". Each rule names the page it is from.
+const catalog_js_1 = require("../registry/catalog.js");
+const resources_js_1 = require("../registry/resources.js");
+const schema_js_1 = require("../registry/schema.js");
+const types_js_1 = require("../registry/types.js");
+// alexa-discovery-objects.html, "Endpoint object details": "letters, numbers, spaces, and the following special
+// characters: _ - = # ; : ? @ &"
+const ENDPOINT_ID = /^[A-Za-z0-9 _\-=#;:?@&]+$/;
+// Same table: "alphanumeric characters and spaces". Letters of any script: Alexa speaks Hindi and Japanese too.
+const FRIENDLY_NAME = /^[\p{L}\p{M}\p{N} ]+$/u;
+const isText = (value) => typeof value === "string" && value.length > 0;
+/** Throws the first rule of the Endpoint object that the fields break. */
+function checkEndpoint(endpoint) {
+    const where = { endpointId: isText(endpoint.endpointId) ? endpoint.endpointId : undefined };
+    function refuse(problem) {
+        throw new types_js_1.DeclarationError(where, problem);
+    }
+    const { endpointId, friendlyName, description, manufacturerName, displayCategories, additionalAttributes, cookie } = endpoint;
+    if (!isText(endpointId))
+        refuse("an endpoint needs an endpointId");
+    if (endpointId.length > catalog_js_1.LIMITS.endpointIdLength || !ENDPOINT_ID.test(endpointId)) {
+        refuse(`the endpointId takes up to ${catalog_js_1.LIMITS.endpointIdLength} letters, digits, spaces and _ - = # ; : ? @ &`);
+    }
+    if (!isText(friendlyName))
+        refuse("an endpoint needs a name");
+    if (friendlyName.length > catalog_js_1.LIMITS.friendlyNameLength || !FRIENDLY_NAME.test(friendlyName)) {
+        refuse(`the name ${JSON.stringify(friendlyName)} takes up to ${catalog_js_1.LIMITS.friendlyNameLength} letters, digits and spaces, no punctuation`);
+    }
+    if (!isText(manufacturerName) || manufacturerName.length > catalog_js_1.LIMITS.manufacturerNameLength) {
+        refuse(`the manufacturerName takes 1 to ${catalog_js_1.LIMITS.manufacturerNameLength} characters`);
+    }
+    if (!isText(description) || description.length > catalog_js_1.LIMITS.descriptionLength) {
+        refuse(`the description takes 1 to ${catalog_js_1.LIMITS.descriptionLength} characters`);
+    }
+    if (!Array.isArray(displayCategories) || displayCategories.length === 0)
+        refuse("an endpoint needs a display category");
+    const known = catalog_js_1.DISPLAY_CATEGORIES;
+    for (const category of displayCategories) {
+        if (!known.includes(category))
+            refuse(`${JSON.stringify(category)} is not a display category`);
+    }
+    for (const [name, value] of Object.entries(additionalAttributes)) {
+        if (typeof value !== "string" || value.length > catalog_js_1.LIMITS.additionalAttributeLength) {
+            refuse(`${name} takes up to ${catalog_js_1.LIMITS.additionalAttributeLength} characters`);
+        }
+    }
+    if (cookie !== undefined) {
+        const bytes = Buffer.byteLength(JSON.stringify(cookie) ?? "");
+        if (bytes > catalog_js_1.LIMITS.cookieBytes)
+            refuse(`the cookie is ${bytes} bytes, ${catalog_js_1.LIMITS.cookieBytes} is the most`);
+    }
+}
+/** alexa-discovery.html, "Interface limits". count includes the capabilities the library adds. */
+function checkCapabilityCount(endpointId, count) {
+    if (count > catalog_js_1.LIMITS.capabilitiesPerEndpoint) {
+        throw new types_js_1.DeclarationError({ endpointId }, `${count} capabilities, an endpoint takes ${catalog_js_1.LIMITS.capabilitiesPerEndpoint}`);
+    }
+}
+// Two names are the same name when the app would show the same: the asset, or the text in one locale.
+function nameKey(name) {
+    return name["@type"] === "asset" ? `asset ${name.value.assetId}` : `text ${name.value.locale} ${name.value.text.toLowerCase()}`;
+}
+function phrases(capability) {
+    const { semantics } = capability.options;
+    return (semantics?.actionMappings ?? []).flatMap((mapping) => mapping.actions);
+}
+/**
+ * Throws the first rule that a capability breaks on its endpoint. endpoint.capabilities are the ones declared
+ * before it. A stub is checked for being declared twice and for nothing else: the library does not know its rules.
+ */
+function checkCapability(capability, descriptor, endpoint) {
+    function refuse(problem) {
+        throw new types_js_1.DeclarationError(capability, problem);
+    }
+    const { namespace, instance, friendlyNames } = capability;
+    // generic-controllers.html, "Multiple instances": one capability of an interface, or one per instance name
+    if (endpoint.capabilities.some((other) => other.namespace === namespace && other.instance === instance)) {
+        refuse(instance ? "the instance is declared twice" : "the interface is declared twice");
+    }
+    if (descriptor.tier === 3)
+        return;
+    if (descriptor.instanced) {
+        // alexa-rangecontroller.html, "Capabilities array": instance and capabilityResources are required
+        if (!isText(instance))
+            refuse("needs an instance name, like Blind.Lift");
+        try {
+            resources_js_1.labels.parse(friendlyNames, "friendlyNames");
+        }
+        catch (err) {
+            refuse(err instanceof schema_js_1.SchemaError && err.path === "friendlyNames" ? "needs a friendly name, from text() or asset()" : err.message);
+        }
+        // resources-and-assets.html, "CapabilityResources": "The first friendly name in the array must be unique for
+        // the endpoint."
+        const first = nameKey(friendlyNames[0]);
+        const taken = endpoint.capabilities.find((other) => other.friendlyNames.length > 0 && nameKey(other.friendlyNames[0]) === first);
+        if (taken) {
+            refuse(`the first friendly name, ${(0, resources_js_1.shownAs)(friendlyNames[0])}, is the first of ${taken.namespace} ${JSON.stringify(taken.instance)} too`);
+        }
+    }
+    else {
+        if (instance)
+            refuse("takes no instance name: an endpoint has the interface once");
+        if (friendlyNames.length > 0)
+            refuse("takes no friendly names");
+    }
+    // generic-controllers.html, "Semantics for user utterances": "Each semantic phrase must be unique across all
+    // controller instances for each endpoint"
+    const used = new Map();
+    for (const other of endpoint.capabilities)
+        for (const phrase of phrases(other))
+            used.set(phrase, other);
+    for (const phrase of phrases(capability)) {
+        const owner = used.get(phrase);
+        if (owner) {
+            const place = owner === capability ? "twice" : `here and on ${owner.namespace} ${JSON.stringify(owner.instance)}`;
+            refuse(`${phrase} is mapped ${place}, an endpoint maps a phrase once`);
+        }
+        used.set(phrase, capability);
+    }
+    if (descriptor.validate)
+        descriptor.validate(capability, endpoint);
+}

dist/cjs/index.js

@@ -3,38 +3,51 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DisplayCategories = exports.States = exports.Actions = exports.Units = exports.Assets = exports.SchemaError = exports.DeclarationError = exports.registry = exports.AlexaErrorResponse = exports.AlexaErrorType = exports.ThermostatMode = exports.TemperatureSensorScale = exports.EndpointHealth = exports.PowerController = exports.AlexaStatusMessage = exports.DisplayCategory = exports.AlexaActions = exports.ActionMapping = exports.AlexaInterfaceType = exports.AlexaInterface = exports.Device = exports.DEFAULT_HOST = exports.Alex2MQTT = void 0;
+exports.AlexaErrorResponse = exports.AlexaErrorType = exports.ThermostatMode = exports.TemperatureSensorScale = exports.AlexaStatusMessage = exports.PowerState = exports.DisplayCategory = exports.AlexaInterfaceType = exports.AlexaActions = exports.ActionMapping = exports.AlexaInterface = exports.DisplayCategories = exports.States = exports.Actions = exports.Units = exports.Assets = exports.text = exports.asset = exports.EndpointHealth = exports.PowerController = exports.TemperatureSensor = exports.BrightnessController = exports.Alexa = exports.SchemaError = exports.DeclarationError = exports.registry = exports.Capability = exports.Device = exports.DEFAULT_HOST = exports.Alex2MQTT = void 0;
 // Relative specifiers carry ".js": Node's ES module loader resolves no extension, and TypeScript maps it back to the .ts.
 var Alex2Node_js_1 = require("./Alex2Node.js");
 Object.defineProperty(exports, "Alex2MQTT", { enumerable: true, get: function () { return __importDefault(Alex2Node_js_1).default; } });
 Object.defineProperty(exports, "DEFAULT_HOST", { enumerable: true, get: function () { return Alex2Node_js_1.DEFAULT_HOST; } });
-var Device_js_1 = require("./Device.js");
+var Device_js_1 = require("./device/Device.js");
 Object.defineProperty(exports, "Device", { enumerable: true, get: function () { return __importDefault(Device_js_1).default; } });
-var AlexaInterface_js_1 = require("./AlexaInterface.js");
-Object.defineProperty(exports, "AlexaInterface", { enumerable: true, get: function () { return AlexaInterface_js_1.AlexaInterface; } });
-Object.defineProperty(exports, "AlexaInterfaceType", { enumerable: true, get: function () { return AlexaInterface_js_1.AlexaInterfaceType; } });
-var ActionMapping_js_1 = require("./ActionMapping.js");
-Object.defineProperty(exports, "ActionMapping", { enumerable: true, get: function () { return ActionMapping_js_1.ActionMapping; } });
-Object.defineProperty(exports, "AlexaActions", { enumerable: true, get: function () { return ActionMapping_js_1.AlexaActions; } });
-var DisplayCategory_js_1 = require("./DisplayCategory.js");
-Object.defineProperty(exports, "DisplayCategory", { enumerable: true, get: function () { return DisplayCategory_js_1.DisplayCategory; } });
-var AlexaStatusMessage_js_1 = require("./AlexaStatusMessage.js");
-Object.defineProperty(exports, "AlexaStatusMessage", { enumerable: true, get: function () { return AlexaStatusMessage_js_1.AlexaStatusMessage; } });
-Object.defineProperty(exports, "PowerController", { enumerable: true, get: function () { return AlexaStatusMessage_js_1.PowerController; } });
-Object.defineProperty(exports, "EndpointHealth", { enumerable: true, get: function () { return AlexaStatusMessage_js_1.EndpointHealth; } });
-Object.defineProperty(exports, "TemperatureSensorScale", { enumerable: true, get: function () { return AlexaStatusMessage_js_1.TemperatureSensorScale; } });
-Object.defineProperty(exports, "ThermostatMode", { enumerable: true, get: function () { return AlexaStatusMessage_js_1.ThermostatMode; } });
-var AlexaErrorResponse_js_1 = require("./AlexaErrorResponse.js");
-Object.defineProperty(exports, "AlexaErrorType", { enumerable: true, get: function () { return AlexaErrorResponse_js_1.AlexaErrorType; } });
-Object.defineProperty(exports, "AlexaErrorResponse", { enumerable: true, get: function () { return AlexaErrorResponse_js_1.AlexaErrorResponse; } });
-// The interface registry and the vocabularies of the Smart Home API
+var Capability_js_1 = require("./device/Capability.js");
+Object.defineProperty(exports, "Capability", { enumerable: true, get: function () { return Capability_js_1.Capability; } });
+// The interfaces, for device.add(), and the registry that holds them by name
 var index_js_1 = require("./registry/index.js");
 Object.defineProperty(exports, "registry", { enumerable: true, get: function () { return index_js_1.registry; } });
 Object.defineProperty(exports, "DeclarationError", { enumerable: true, get: function () { return index_js_1.DeclarationError; } });
 Object.defineProperty(exports, "SchemaError", { enumerable: true, get: function () { return index_js_1.SchemaError; } });
 var index_js_2 = require("./registry/index.js");
-Object.defineProperty(exports, "Assets", { enumerable: true, get: function () { return index_js_2.ASSETS; } });
-Object.defineProperty(exports, "Units", { enumerable: true, get: function () { return index_js_2.UNITS_OF_MEASURE; } });
-Object.defineProperty(exports, "Actions", { enumerable: true, get: function () { return index_js_2.ACTIONS; } });
-Object.defineProperty(exports, "States", { enumerable: true, get: function () { return index_js_2.STATES; } });
-Object.defineProperty(exports, "DisplayCategories", { enumerable: true, get: function () { return index_js_2.DISPLAY_CATEGORIES; } });
+Object.defineProperty(exports, "Alexa", { enumerable: true, get: function () { return index_js_2.Alexa; } });
+Object.defineProperty(exports, "BrightnessController", { enumerable: true, get: function () { return index_js_2.BrightnessController; } });
+Object.defineProperty(exports, "TemperatureSensor", { enumerable: true, get: function () { return index_js_2.TemperatureSensor; } });
+var enums_js_1 = require("./compat/enums.js");
+Object.defineProperty(exports, "PowerController", { enumerable: true, get: function () { return enums_js_1.PowerController; } });
+Object.defineProperty(exports, "EndpointHealth", { enumerable: true, get: function () { return enums_js_1.EndpointHealth; } });
+var resources_js_1 = require("./registry/resources.js");
+Object.defineProperty(exports, "asset", { enumerable: true, get: function () { return resources_js_1.asset; } });
+Object.defineProperty(exports, "text", { enumerable: true, get: function () { return resources_js_1.text; } });
+// The vocabularies of the Smart Home API
+var index_js_3 = require("./registry/index.js");
+Object.defineProperty(exports, "Assets", { enumerable: true, get: function () { return index_js_3.ASSETS; } });
+Object.defineProperty(exports, "Units", { enumerable: true, get: function () { return index_js_3.UNITS_OF_MEASURE; } });
+Object.defineProperty(exports, "Actions", { enumerable: true, get: function () { return index_js_3.ACTIONS; } });
+Object.defineProperty(exports, "States", { enumerable: true, get: function () { return index_js_3.STATES; } });
+Object.defineProperty(exports, "DisplayCategories", { enumerable: true, get: function () { return index_js_3.DISPLAY_CATEGORIES; } });
+// 1.x
+var AlexaInterface_js_1 = require("./compat/AlexaInterface.js");
+Object.defineProperty(exports, "AlexaInterface", { enumerable: true, get: function () { return AlexaInterface_js_1.AlexaInterface; } });
+var ActionMapping_js_1 = require("./compat/ActionMapping.js");
+Object.defineProperty(exports, "ActionMapping", { enumerable: true, get: function () { return ActionMapping_js_1.ActionMapping; } });
+var enums_js_2 = require("./compat/enums.js");
+Object.defineProperty(exports, "AlexaActions", { enumerable: true, get: function () { return enums_js_2.AlexaActions; } });
+Object.defineProperty(exports, "AlexaInterfaceType", { enumerable: true, get: function () { return enums_js_2.AlexaInterfaceType; } });
+Object.defineProperty(exports, "DisplayCategory", { enumerable: true, get: function () { return enums_js_2.DisplayCategory; } });
+Object.defineProperty(exports, "PowerState", { enumerable: true, get: function () { return enums_js_2.PowerState; } });
+var AlexaStatusMessage_js_1 = require("./AlexaStatusMessage.js");
+Object.defineProperty(exports, "AlexaStatusMessage", { enumerable: true, get: function () { return AlexaStatusMessage_js_1.AlexaStatusMessage; } });
+Object.defineProperty(exports, "TemperatureSensorScale", { enumerable: true, get: function () { return AlexaStatusMessage_js_1.TemperatureSensorScale; } });
+Object.defineProperty(exports, "ThermostatMode", { enumerable: true, get: function () { return AlexaStatusMessage_js_1.ThermostatMode; } });
+var AlexaErrorResponse_js_1 = require("./AlexaErrorResponse.js");
+Object.defineProperty(exports, "AlexaErrorType", { enumerable: true, get: function () { return AlexaErrorResponse_js_1.AlexaErrorType; } });
+Object.defineProperty(exports, "AlexaErrorResponse", { enumerable: true, get: function () { return AlexaErrorResponse_js_1.AlexaErrorResponse; } });

dist/cjs/registry/interfaces/stubs.js

@@ -80,6 +80,20 @@ const TABLE = [
     ["Alexa.VideoRecorder", "1", [], "alexa-videorecorder.html"],
     ["Alexa.WakeOnLANController", "1", [], "alexa-wakeonlancontroller.html"],
 ];
+// What 1.5.2 added to the capability object of three of them
+const EXTRAS = {
+    // No properties object; supportsDeactivation and proactivelyReported on the capability itself
+    "Alexa.SceneController": ({ proactivelyReported }) => ({
+        properties: false,
+        topLevel: { supportsDeactivation: true, proactivelyReported },
+    }),
+    "Alexa.ThermostatController": () => ({
+        configuration: { supportedModes: ["HEAT", "COOL", "AUTO", "OFF"], supportsScheduling: false },
+    }),
+    "Alexa.ModeController": ({ options }) => (options.supportedModes?.length > 0
+        ? { configuration: { ordered: true, supportedModes: options.supportedModes } }
+        : {}),
+};
 function kindOf(namespace) {
     if (namespace.endsWith("Sensor"))
         return "sensor";
@@ -97,6 +111,7 @@ function stub([namespace, version, properties, page]) {
         instanced: false,
         properties: Object.fromEntries(properties.map((name) => [name, { name, value: schema_js_1.s.unknown() }])),
         directives: {},
+        discovery: EXTRAS[namespace],
     };
 }
 exports.STUBS = TABLE.map(stub);

dist/cjs/registry/resources.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.labels = exports.label = void 0;
+exports.text = text;
+exports.asset = asset;
+exports.shownAs = shownAs;
+// Friendly names: what the user calls an instance, a mode or a preset (resources-and-assets.html).
+const catalog_js_1 = require("./catalog.js");
+const schema_js_1 = require("./schema.js");
+/** A friendly name as text, in one locale. */
+function text(name, locale = "en-US") {
+    return { "@type": "text", value: { text: name, locale } };
+}
+/** A friendly name from the global Alexa catalog: one id, several names, every language Alexa speaks. */
+function asset(assetId) {
+    return { "@type": "asset", value: { assetId } };
+}
+const LOCALE = /^[a-z]{2}-[A-Z]{2}$/;
+const textValue = schema_js_1.s.object({
+    text: schema_js_1.s.string({ min: 1 }),
+    locale: schema_js_1.s.string({ pattern: LOCALE, expects: "a locale like en-US" }),
+});
+const assetValue = schema_js_1.s.object({ assetId: schema_js_1.s.oneOf(catalog_js_1.ASSETS, "an id of the global Alexa catalog, like Alexa.Setting.Opening") });
+const typed = schema_js_1.s.object({ "@type": schema_js_1.s.enum("text", "asset"), value: schema_js_1.s.unknown() });
+const reserved = catalog_js_1.RESERVED_WORDS;
+/** One friendly name. An asset has to be in the catalog, a text must not be a word Alexa keeps for itself. */
+exports.label = {
+    expects: "a friendly name, from text() or asset()",
+    parse(input, path = "") {
+        const { "@type": type, value } = typed.parse(input, path);
+        if (type === "asset")
+            return { "@type": type, value: assetValue.parse(value, (0, schema_js_1.at)(path, "value")) };
+        const named = textValue.parse(value, (0, schema_js_1.at)(path, "value"));
+        if (reserved.includes(named.text.trim().toLowerCase())) {
+            throw new schema_js_1.SchemaError((0, schema_js_1.at)(path, "value.text"), `${JSON.stringify(named.text)} is a reserved word, not to be used as a friendly name`);
+        }
+        return { "@type": type, value: named };
+    },
+};
+/** The friendly names of an instance, a mode or a preset: at least one. */
+exports.labels = schema_js_1.s.array(exports.label, { min: 1 });
+/** What the user is shown for a friendly name: the text, or the id of the asset. */
+function shownAs(name) {
+    return name["@type"] === "text" ? name.value.text : name.value.assetId;
+}

dist/cjs/registry/schema.js

@@ -3,7 +3,8 @@
 // and declaration options with these; parse() returns the value or throws a SchemaError that names where it went
 // wrong. Written here rather than taken from a package: mqtt stays the only runtime dependency.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.s = exports.SchemaError = void 0;
+exports.s = exports.at = exports.SchemaError = void 0;
+exports.mismatch = mismatch;
 /** A value that does not fit its schema: path is where ("payload.targetSetpoint.scale"), problem is what. */
 class SchemaError extends Error {
     constructor(path, problem) {
@@ -23,10 +24,13 @@ function shown(input) {
     const text = JSON.stringify(input) ?? String(input);
     return text.length > 60 ? `${text.slice(0, 57)}...` : text;
 }
+/** The error of a value that is not what a schema expects. */
 function mismatch(path, expects, input) {
     return new SchemaError(path, `expected ${expects}, got ${shown(input)}`);
 }
+/** The path of a key of the object at path. */
 const at = (path, key) => (path ? `${path}.${key}` : key);
+exports.at = at;
 function isRecord(input) {
     return typeof input === "object" && input !== null && !Array.isArray(input);
 }
@@ -69,7 +73,11 @@ function literal(value) {
     return schema(JSON.stringify(value), (input) => input === value);
 }
 function enumeration(...values) {
-    return { ...schema(values.join(" | "), (input) => values.includes(input)), values };
+    return oneOf(values, values.join(" | "));
+}
+/** One of a list too long to print in an error message: expects says what the list is. */
+function oneOf(values, expects) {
+    return { ...schema(expects, (input) => values.includes(input)), values };
 }
 function unknown() {
     return schema("any value", () => true);
@@ -127,11 +135,11 @@ function object(shape, rules = {}) {
                 throw mismatch(path, expects, input);
             const others = Object.keys(input).filter((key) => !known.includes(key));
             if (others.length > 0 && rules.unknownKeys === "reject") {
-                throw new SchemaError(at(path, others[0]), `unknown key, the known ones are ${known.join(", ") || "none"}`);
+                throw new SchemaError((0, exports.at)(path, others[0]), `unknown key, the known ones are ${known.join(", ") || "none"}`);
             }
             const parsed = {};
             for (const key of known) {
-                const value = shape[key].parse(input[key], at(path, key));
+                const value = shape[key].parse(input[key], (0, exports.at)(path, key));
                 if (value !== undefined)
                     parsed[key] = value;
             }
@@ -178,6 +186,7 @@ exports.s = {
     boolean,
     literal,
     enum: enumeration,
+    oneOf,
     unknown,
     optional,
     nullable,

dist/esm/ActionMapping.d.ts

@@ -1,20 +0,0 @@
-export declare enum AlexaActions {
-    Open = "Alexa.Actions.Open",
-    Close = "Alexa.Actions.Close",
-    Raise = "Alexa.Actions.Raise",
-    Lower = "Alexa.Actions.Lower",
-    SetEcoOn = "Alexa.Actions.SetEcoOn",
-    SetEcoOff = "Alexa.Actions.SetEcoOff"
-}
-interface Directive {
-    name: string;
-    payload?: string;
-}
-export declare class ActionMapping {
-    type: string;
-    actions: AlexaActions[];
-    directive: Directive;
-    constructor(actions: AlexaActions[], directiveName: string, directivePayload?: string);
-    toJSON(): object;
-}
-export {};

dist/esm/ActionMapping.js

@@ -1,28 +0,0 @@
-export var AlexaActions;
-(function (AlexaActions) {
-    AlexaActions["Open"] = "Alexa.Actions.Open";
-    AlexaActions["Close"] = "Alexa.Actions.Close";
-    AlexaActions["Raise"] = "Alexa.Actions.Raise";
-    AlexaActions["Lower"] = "Alexa.Actions.Lower";
-    AlexaActions["SetEcoOn"] = "Alexa.Actions.SetEcoOn";
-    AlexaActions["SetEcoOff"] = "Alexa.Actions.SetEcoOff";
-})(AlexaActions || (AlexaActions = {}));
-export class ActionMapping {
-    constructor(actions, directiveName, directivePayload) {
-        this.type = "ActionsToDirective";
-        this.actions = actions;
-        this.directive = {
-            name: directiveName,
-        };
-        if (directivePayload) {
-            this.directive.payload = directivePayload;
-        }
-    }
-    toJSON() {
-        return {
-            "@type": this.type,
-            actions: this.actions,
-            directive: this.directive,
-        };
-    }
-}

dist/esm/Alex2Node.d.ts

@@ -1,7 +1,8 @@
 import type { IClientOptions } from "mqtt";
-import Device from "./Device.js";
+import Device from "./device/Device.js";
+import type { EndpointDefinition } from "./device/Device.js";
 import { EventEmitter } from "events";
-import { DisplayCategory } from "./DisplayCategory.js";
+import { DisplayCategory } from "./compat/enums.js";
 /** Optional settings for the bridge (1.5.1). Everything has the 1.4.0 behaviour as its default. */
 export interface Alex2MQTTOptions {
     /** The broker URL. Default: the public Alex2MQTT broker, mqtt://Alex2MQTT.stormysdream.club:1883. */
@@ -10,6 +11,11 @@ export interface Alex2MQTTOptions {
     mqtt?: IClientOptions;
     /** Where log lines go. Default: console (only when debugLogging is on). */
     log?: (message: string, detail?: unknown) => void;
+    /**
+     * false: discovery does not list the Alexa interface on the endpoints. Default: every endpoint ends with
+     * { type: "AlexaInterface", interface: "Alexa", version: "3" }, which Amazon requires and 1.x left out.
+     */
+    alexaInterface?: boolean;
 }
 export declare const DEFAULT_HOST = "mqtt://Alex2MQTT.stormysdream.club:1883";
 /**
@@ -35,6 +41,7 @@ declare class Alex2MQTT extends EventEmitter {
     private devices;
     private MqttHost;
     private options;
+    private logged;
     /** true while the broker connection is up. */
     connected: boolean;
     /** ISO time of the last discovery request answered, null before the first. */
@@ -44,9 +51,22 @@ declare class Alex2MQTT extends EventEmitter {
     /** Emit "error" only when somebody listens: an unhandled "error" event would crash the host process. */
     private fail;
     connect(): void;
+    private describeDevices;
     /** Close the broker connection (resolves once closed). The devices stay registered; connect() again reuses them. */
     disconnect(): Promise<void>;
-    registerDevice(name: string, endpointId: string, displayCategory: DisplayCategory | DisplayCategory[] | null): Device;
+    /**
+     * Declare a device:
+     *
+     *   const blinds = bridge.addDevice({ endpointId: "bedroom-blinds", name: "Bedroom Blinds",
+     *     categories: ["INTERIOR_BLIND"], manufacturerName: "Acme", description: "Roller blind by Acme" });
+     *
+     * Throws a DeclarationError when Alexa would reject the endpoint (an endpointId with a slash, a name with
+     * punctuation) or when the endpointId is registered already. Discovery lists Alexa.EndpointHealth for the device
+     * unless endpointHealth is false.
+     */
+    addDevice(definition: EndpointDefinition): Device;
+    registerDevice(name: string, endpointId: string, displayCategory?: DisplayCategory | DisplayCategory[] | null): Device;
+    private register;
     /** Forget a device (its listeners with it). Returns false when there was none. */
     unregisterDevice(endpointId: string): boolean;
     /** Forget every device. */

dist/esm/Alex2Node.js

@@ -1,10 +1,16 @@
 // mqtt reaches Node as CommonJS: the default import works from both builds, a named one needs Node to detect it.
 import mqtt from "mqtt";
-import Device from "./Device.js";
+import Device from "./device/Device.js";
+import { checkEndpoint } from "./device/validate.js";
 import { EventEmitter } from "events";
-import { DisplayCategory } from "./DisplayCategory.js";
-import { AlexaInterfaceType } from "./AlexaInterface.js";
+import { DisplayCategory } from "./compat/enums.js";
+import { DeclarationError } from "./registry/types.js";
 export const DEFAULT_HOST = "mqtt://Alex2MQTT.stormysdream.club:1883";
+// What addDevice() copies from the definition to the device
+const DESCRIBED = [
+    "description", "manufacturerName", "manufacturer", "model", "serialNumber", "firmwareVersion", "softwareVersion",
+    "customIdentifier", "cookie",
+];
 /**
  * The Alexa-to-MQTT bridge: one broker connection for a user's root topic, a set of registered devices, discovery and
  * directive dispatch.
@@ -28,6 +34,8 @@ class Alex2MQTT extends EventEmitter {
         this.debugLogging = debugLogging;
         this.client = null;
         this.devices = [];
+        // The lines of check() that were logged. Discovery comes every few minutes: a line is logged once.
+        this.logged = new Set();
         /** true while the broker connection is up. */
         this.connected = false;
         /** ISO time of the last discovery request answered, null before the first. */
@@ -84,12 +92,8 @@ class Alex2MQTT extends EventEmitter {
             this.log(`MQTT Message Received`, { topic, payload: message.toString() });
             if (topic == `${this.rootTopic}/discover`) {
                 this.log("Discovery request received, getting device json...");
-                const deviceArray = this.devices.map((device) => device.getJSON());
+                const deviceArray = this.describeDevices();
                 this.lastDiscoveryAt = new Date().toISOString();
-                for (const device of this.devices) // a capability the library has no property list for goes out with supported: []
-                    for (const cap of device.getCapabilities())
-                        if (cap.getProps().length === 0 && cap.getType() !== AlexaInterfaceType.SCENE_CONTROLLER)
-                            this.log(`${device.endpointId}: no property list known for ${cap.getTypeString()}, discovery lists it with no supported properties`);
                 this.client.publish(topic + "_r", JSON.stringify(deviceArray), (err) => {
                     if (err) {
                         this.fail(err);
@@ -130,6 +134,26 @@ class Alex2MQTT extends EventEmitter {
             }
         });
     }
+    // The endpoint objects of a discovery answer. What check() says about a device is logged, each line once. A device
+    // that cannot be described is left out and reported as an error: the others are still announced.
+    describeDevices() {
+        const endpoints = [];
+        for (const device of this.devices) {
+            try {
+                endpoints.push(device.getJSON());
+                for (const line of device.check()) {
+                    if (this.logged.has(line))
+                        continue;
+                    this.logged.add(line);
+                    this.log(`warning: ${line}`);
+                }
+            }
+            catch (err) {
+                this.fail(new Error(`${device.endpointId} is not in the discovery answer: ${err instanceof Error ? err.message : err}`));
+            }
+        }
+        return endpoints;
+    }
     /** Close the broker connection (resolves once closed). The devices stay registered; connect() again reuses them. */
     disconnect() {
         return new Promise((resolve) => {
@@ -141,6 +165,36 @@ class Alex2MQTT extends EventEmitter {
             c.end(true, {}, () => resolve());
         });
     }
+    /**
+     * Declare a device:
+     *
+     *   const blinds = bridge.addDevice({ endpointId: "bedroom-blinds", name: "Bedroom Blinds",
+     *     categories: ["INTERIOR_BLIND"], manufacturerName: "Acme", description: "Roller blind by Acme" });
+     *
+     * Throws a DeclarationError when Alexa would reject the endpoint (an endpointId with a slash, a name with
+     * punctuation) or when the endpointId is registered already. Discovery lists Alexa.EndpointHealth for the device
+     * unless endpointHealth is false.
+     */
+    addDevice(definition) {
+        if (!this.client) {
+            throw new Error("Must call connect before creating devices");
+        }
+        const { endpointId, name, categories, endpointHealth, ...described } = definition;
+        // Without categories the device would take LIGHT, the default of registerDevice: here it is a mistake
+        const device = new Device(this.client, this.rootTopic, name, endpointId, (categories ?? []));
+        for (const [field, value] of Object.entries(described)) {
+            if (!DESCRIBED.includes(field))
+                throw new DeclarationError({ endpointId }, `${field} is not a field of an endpoint`);
+            if (value !== undefined)
+                Object.assign(device, { [field]: value });
+        }
+        checkEndpoint(device.getJSON());
+        const existing = this.getDevice(endpointId);
+        if (existing)
+            throw new DeclarationError({ endpointId }, `is registered already, as "${existing.name}"`);
+        this.register(device, endpointHealth !== false);
+        return device;
+    }
     registerDevice(name, endpointId, displayCategory) {
         if (!this.client) {
             throw new Error("Must call connect before creating devices");
@@ -155,15 +209,16 @@ class Alex2MQTT extends EventEmitter {
             return existing;
         }
         this.log(`Creating new device with endpoint: ${endpointId}`);
-        const normalizedCategory = displayCategory === null
-            ? [DisplayCategory.LIGHT]
-            : Array.isArray(displayCategory)
-                ? displayCategory
-                : [displayCategory || DisplayCategory.LIGHT];
+        const normalizedCategory = Array.isArray(displayCategory) ? displayCategory : [displayCategory || DisplayCategory.LIGHT];
         const device = new Device(this.client, this.rootTopic, name, endpointId, normalizedCategory);
+        this.register(device, false);
+        return device;
+    }
+    register(device, endpointHealth) {
+        device.alexaInterface = this.options.alexaInterface !== false;
+        device.endpointHealth = endpointHealth;
         device.onPublishError = (err) => this.fail(err); // a failed publish is an "error" event (when listened to), never a rejected send()
         this.devices.push(device);
-        return device;
     }
     /** Forget a device (its listeners with it). Returns false when there was none. */
     unregisterDevice(endpointId) {

dist/esm/AlexaInterface.d.ts

@@ -1,109 +0,0 @@
-import type { ActionMapping } from "./ActionMapping.js";
-export declare enum AlexaInterfaceType {
-    APPLICATION_STATE_REPORTER = "Alexa.ApplicationStateReporter",
-    AUDIO_PLAY_QUEUE = "Alexa.Audio.PlayQueue",
-    AUTHORIZATION_CONTROLLER = "Alexa.AuthorizationController",
-    AUTOMATION_MANAGEMENT = "Alexa.AutomationManagement",
-    AUTOMOTIVE_VEHICLE_DATA = "Alexa.Automotive.VehicleData",
-    BRIGHTNESS_CONTROLLER = "Alexa.BrightnessController",
-    CAMERA_LIVE_VIEW_CONTROLLER = "Alexa.Camera.LiveViewController",
-    CAMERA_STREAM_CONTROLLER = "Alexa.CameraStreamController",
-    CHANNEL_CONTROLLER = "Alexa.ChannelController",
-    COLOR_CONTROLLER = "Alexa.ColorController",
-    COLOR_TEMPERATURE_CONTROLLER = "Alexa.ColorTemperatureController",
-    COMMISSIONABLE = "Alexa.Commissionable",
-    CONSENT_MANAGEMENT_CONSENT_REQUIRED_REPORTER = "Alexa.ConsentManagement.ConsentRequiredReporter",
-    CONTACT_SENSOR = "Alexa.ContactSensor",
-    COOKING = "Alexa.Cooking",
-    COOKING_FOOD_TEMPERATURE_CONTROLLER = "Alexa.Cooking.FoodTemperatureController",
-    COOKING_FOOD_TEMPERATURE_SENSOR = "Alexa.Cooking.FoodTemperatureSensor",
-    COOKING_PRESET_CONTROLLER = "Alexa.Cooking.PresetController",
-    COOKING_TEMPERATURE_CONTROLLER = "Alexa.Cooking.TemperatureController",
-    COOKING_TEMPERATURE_SENSOR = "Alexa.Cooking.TemperatureSensor",
-    COOKING_TIME_CONTROLLER = "Alexa.Cooking.TimeController",
-    DATA_CONTROLLER = "Alexa.DataController",
-    DEVICE_USAGE_ESTIMATION = "Alexa.DeviceUsage.Estimation",
-    DEVICE_USAGE_METER = "Alexa.DeviceUsage.Meter",
-    DOORBELL_EVENT_SOURCE = "Alexa.DoorbellEventSource",
-    ENDPOINT_HEALTH = "Alexa.EndpointHealth",
-    EQUALIZER_CONTROLLER = "Alexa.EqualizerController",
-    INPUT_CONTROLLER = "Alexa.InputController",
-    INVENTORY_LEVEL_SENSOR = "Alexa.InventoryLevelSensor",
-    INVENTORY_LEVEL_USAGE_SENSOR = "Alexa.InventoryLevelUsageSensor",
-    INVENTORY_USAGE_SENSOR = "Alexa.InventoryUsageSensor",
-    KEYPAD_CONTROLLER = "Alexa.KeypadController",
-    LAUNCHER = "Alexa.Launcher",
-    LOCK_CONTROLLER = "Alexa.LockController",
-    MEDIA_PLAYBACK = "Alexa.Media.Playback",
-    MEDIA_PLAY_QUEUE = "Alexa.Media.PlayQueue",
-    MEDIA_SEARCH = "Alexa.Media.Search",
-    MODE_CONTROLLER = "Alexa.ModeController",
-    MOTION_SENSOR = "Alexa.MotionSensor",
-    PERCENTAGE_CONTROLLER = "Alexa.PercentageController",
-    PLAYBACK_CONTROLLER = "Alexa.PlaybackController",
-    PLAYBACK_STATE_REPORTER = "Alexa.PlaybackStateReporter",
-    POWER_CONTROLLER = "Alexa.PowerController",
-    POWER_LEVEL_CONTROLLER = "Alexa.PowerLevelController",
-    PROACTIVE_NOTIFICATION_SOURCE = "Alexa.ProactiveNotificationSource",
-    RANGE_CONTROLLER = "Alexa.RangeController",
-    RECORD_CONTROLLER = "Alexa.RecordController",
-    REMOTE_VIDEO_PLAYER = "Alexa.RemoteVideoPlayer",
-    RTC_SESSION_CONTROLLER = "Alexa.RTCSessionController",
-    SCENE_CONTROLLER = "Alexa.SceneController",
-    SECURITY_PANEL_CONTROLLER = "Alexa.SecurityPanelController",
-    SECURITY_PANEL_CONTROLLER_ALERT = "Alexa.SecurityPanelController.Alert",
-    SEEK_CONTROLLER = "Alexa.SeekController",
-    SIMPLE_EVENT_SOURCE = "Alexa.SimpleEventSource",
-    SMART_VISION_OBJECT_DETECTION_SENSOR = "Alexa.SmartVision.ObjectDetectionSensor",
-    SMART_VISION_SNAPSHOT_PROVIDER = "Alexa.SmartVision.SnapshotProvider",
-    SPEAKER = "Alexa.Speaker",
-    STEP_SPEAKER = "Alexa.StepSpeaker",
-    TEMPERATURE_SENSOR = "Alexa.TemperatureSensor",
-    THERMOSTAT_CONTROLLER = "Alexa.ThermostatController",
-    THERMOSTAT_CONTROLLER_CONFIGURATION = "Alexa.ThermostatController.Configuration",
-    THERMOSTAT_CONTROLLER_HVAC_COMPONENTS = "Alexa.ThermostatController.HVAC.Components",
-    THERMOSTAT_CONTROLLER_SCHEDULE = "Alexa.ThermostatController.Schedule",
-    TIME_HOLD_CONTROLLER = "Alexa.TimeHoldController",
-    TOGGLE_CONTROLLER = "Alexa.ToggleController",
-    UI_CONTROLLER = "Alexa.UIController",
-    USER_PREFERENCE = "Alexa.UserPreference",
-    VIDEO_RECORDER = "Alexa.VideoRecorder",
-    WAKE_ON_LAN_CONTROLLER = "Alexa.WakeOnLANController",
-    UNKNOWN = "UNKNOWN"
-}
-/** One ModeController mode as discovery lists it (configuration.supportedModes): the value plus its friendly names. */
-export interface SupportedMode {
-    value: string;
-    modeResources?: {
-        friendlyNames: Array<{
-            "@type": string;
-            value: {
-                text?: string;
-                locale?: string;
-                assetId?: string;
-            };
-        }>;
-    };
-}
-export declare class AlexaInterface {
-    type: AlexaInterfaceType;
-    retrievable: boolean;
-    proactivelyReported: boolean;
-    instance: string;
-    private friendlyNames;
-    private actionMappings;
-    private supportedModes;
-    constructor(type: AlexaInterfaceType, retrievable?: boolean, proactivelyReported?: boolean, instance?: string);
-    addActionMapping(mapping: ActionMapping): void;
-    addFriendlyName(name: string, locale: string): void;
-    /** The modes of a ModeController: { value, modeResources } objects as Alexa wants them (plain strings pass through as given). */
-    addSupportedModes(modes: Array<string | SupportedMode>): void;
-    setInstance(name: string): void;
-    getType(): AlexaInterfaceType;
-    getTypeString(): string;
-    /** The version of the interface, from its descriptor. "UNKNOWN" for a name the registry does not have. */
-    getVersion(): string;
-    /** The names of the properties the interface reports, from its descriptor. */
-    getProps(): string[];
-    getJSON(): object;
-}

dist/esm/AlexaStatusMessage.d.ts

@@ -1,8 +1,5 @@
+import type { EndpointHealth, PowerController } from "./compat/enums.js";
 import type { MqttClient } from "mqtt";
-export declare enum EndpointHealth {
-    OK = "OK",
-    UNREACHABLE = "UNREACHABLE"
-}
 export declare enum ThermostatMode {
     OFF = "OFF",
     HEAT = "HEAT",
@@ -11,10 +8,6 @@ export declare enum ThermostatMode {
     ECO = "ECO",
     CUSTOM = "CUSTOM"
 }
-export declare enum PowerController {
-    ON = "ON",
-    OFF = "OFF"
-}
 export declare enum TemperatureSensorScale {
     CELSIUS = "CELSIUS",
     FAHRENHEIT = "FAHRENHEIT"

dist/esm/AlexaStatusMessage.js

@@ -1,10 +1,5 @@
 import { randomUUID } from "crypto";
-import { AlexaInterfaceType } from "./AlexaInterface.js";
-export var EndpointHealth;
-(function (EndpointHealth) {
-    EndpointHealth["OK"] = "OK";
-    EndpointHealth["UNREACHABLE"] = "UNREACHABLE";
-})(EndpointHealth || (EndpointHealth = {}));
+import { AlexaInterfaceType } from "./compat/enums.js";
 export var ThermostatMode;
 (function (ThermostatMode) {
     ThermostatMode["OFF"] = "OFF";
@@ -14,11 +9,6 @@ export var ThermostatMode;
     ThermostatMode["ECO"] = "ECO";
     ThermostatMode["CUSTOM"] = "CUSTOM";
 })(ThermostatMode || (ThermostatMode = {}));
-export var PowerController;
-(function (PowerController) {
-    PowerController["ON"] = "ON";
-    PowerController["OFF"] = "OFF";
-})(PowerController || (PowerController = {}));
 export var TemperatureSensorScale;
 (function (TemperatureSensorScale) {
     TemperatureSensorScale["CELSIUS"] = "CELSIUS";

dist/esm/Device.d.ts

@@ -1,62 +0,0 @@
-import { AlexaInterface } from "./AlexaInterface.js";
-import type { AlexaInterfaceType } from "./AlexaInterface.js";
-import { DisplayCategory } from "./DisplayCategory.js";
-import { EventEmitter } from "events";
-import type { MqttClient } from "mqtt";
-import { AlexaStatusMessage } from "./AlexaStatusMessage.js";
-import type { ChangeCause } from "./AlexaStatusMessage.js";
-import { AlexaErrorResponse } from "./AlexaErrorResponse.js";
-declare class Device extends EventEmitter {
-    private mqttClient;
-    private rootTopic;
-    name: string;
-    endpointId: string;
-    displayCategory: Array<DisplayCategory> | null;
-    description: string;
-    manufacturerName: string;
-    manufacturer: string;
-    model: string;
-    protected softwareVersion: string;
-    private capabilities;
-    /** Where a failed publish from this device or a message it built is reported; Alex2MQTT sets it (1.5.2). */
-    onPublishError?: (err: Error) => void;
-    constructor(mqttClient: MqttClient, rootTopic: string, name: string, endpointId: string, displayCategory: Array<DisplayCategory> | null, description?: string, manufacturerName?: string, manufacturer?: string, model?: string);
-    /** Internal (1.5.2): Alex2MQTT.connect() re-binds every registered device to its new broker client after a disconnect(). */
-    setMqttClient(client: MqttClient): void;
-    getName(): string;
-    setName(name: string): void;
-    getEndpointId(): string;
-    setDisplayCategory(category: DisplayCategory | DisplayCategory[]): void;
-    getDisplayCategory(): Array<DisplayCategory>;
-    setDescription(description: string): void;
-    getDescription(): string;
-    getErrorMessage(correlationToken: string): AlexaErrorResponse;
-    getStatusMessage(correlationToken: string, isResponse?: boolean, isDeferred?: boolean): AlexaStatusMessage;
-    /**
-     * A proactive Alexa.ChangeReport (1.5.1): add the changed properties (the default target), optionally
-     * .unchanged() then the others, and .send() - it goes to <root>/changeReport, which Alex2MQTT forwards to the Alexa
-     * event gateway with the user's token. Alexa only accepts it for capabilities registered with proactivelyReported.
-     */
-    getChangeReport(cause?: ChangeCause): AlexaStatusMessage;
-    /**
-     * Alexa.SceneController: answer an Activate / Deactivate directive with ActivationStarted / DeactivationStarted
-     * (1.5.1). Resolves with the topic published to, or "" when the publish failed (never rejects, 1.5.2).
-     */
-    sendSceneResponse(correlationToken: string, activated: boolean, cause?: ChangeCause, sendAsync?: boolean): Promise<string>;
-    getCapabilities(): AlexaInterface[];
-    setManufacturerName(name: string): void;
-    getManufacturerName(): string;
-    setManufacturer(manufacturer: string): void;
-    getManufacturer(): string;
-    setModel(model: string): void;
-    getModel(): string;
-    getSoftwareVersion(): string;
-    /** Add a capability. 1.5.1: options.retrievable / proactivelyReported / instance (a change report needs proactivelyReported). */
-    addCapability(type: AlexaInterfaceType, options?: {
-        retrievable?: boolean;
-        proactivelyReported?: boolean;
-        instance?: string;
-    }): AlexaInterface;
-    getJSON(): Record<string, any>;
-}
-export default Device;

dist/esm/Device.js

@@ -1,143 +0,0 @@
-import { AlexaInterface } from "./AlexaInterface.js";
-import { DisplayCategory } from "./DisplayCategory.js";
-import { EventEmitter } from "events";
-import { randomUUID } from "crypto";
-import { AlexaStatusMessage } from "./AlexaStatusMessage.js";
-import { AlexaErrorResponse } from "./AlexaErrorResponse.js";
-class Device extends EventEmitter {
-    constructor(mqttClient, rootTopic, name, endpointId, displayCategory, description = "Alexa to Node.js bridge", manufacturerName = "Alex2Node", manufacturer = "Alex2Node", model = "Alex2Node_v1.0.0") {
-        super();
-        this.mqttClient = mqttClient;
-        this.rootTopic = rootTopic;
-        this.name = name;
-        this.endpointId = endpointId;
-        this.displayCategory = displayCategory;
-        this.description = description;
-        this.manufacturerName = manufacturerName;
-        this.manufacturer = manufacturer;
-        this.model = model;
-        this.softwareVersion = "1.0.0";
-        this.capabilities = [];
-    }
-    /** Internal (1.5.2): Alex2MQTT.connect() re-binds every registered device to its new broker client after a disconnect(). */
-    setMqttClient(client) {
-        this.mqttClient = client;
-    }
-    getName() {
-        return this.name;
-    }
-    setName(name) {
-        this.name = name;
-    }
-    getEndpointId() {
-        return this.endpointId;
-    }
-    setDisplayCategory(category) {
-        this.displayCategory = Array.isArray(category) ? category : [category];
-    }
-    getDisplayCategory() {
-        return this.displayCategory || [DisplayCategory.LIGHT];
-    }
-    setDescription(description) {
-        this.description = description;
-    }
-    getDescription() {
-        return this.description;
-    }
-    getErrorMessage(correlationToken) {
-        const msg = new AlexaErrorResponse(correlationToken, this.rootTopic, this.endpointId, this.mqttClient);
-        msg.onPublishError = this.onPublishError;
-        return msg;
-    }
-    getStatusMessage(correlationToken, isResponse = false, isDeferred = false) {
-        const msg = new AlexaStatusMessage(correlationToken, this.rootTopic, this.endpointId, this.mqttClient, isResponse, isDeferred);
-        msg.onPublishError = this.onPublishError;
-        return msg;
-    }
-    /**
-     * A proactive Alexa.ChangeReport (1.5.1): add the changed properties (the default target), optionally
-     * .unchanged() then the others, and .send() - it goes to <root>/changeReport, which Alex2MQTT forwards to the Alexa
-     * event gateway with the user's token. Alexa only accepts it for capabilities registered with proactivelyReported.
-     */
-    getChangeReport(cause = "PHYSICAL_INTERACTION") {
-        const msg = new AlexaStatusMessage("", this.rootTopic, this.endpointId, this.mqttClient, false, false, cause);
-        msg.onPublishError = this.onPublishError;
-        return msg;
-    }
-    /**
-     * Alexa.SceneController: answer an Activate / Deactivate directive with ActivationStarted / DeactivationStarted
-     * (1.5.1). Resolves with the topic published to, or "" when the publish failed (never rejects, 1.5.2).
-     */
-    sendSceneResponse(correlationToken, activated, cause = "VOICE_INTERACTION", sendAsync = false) {
-        const payload = {
-            context: {},
-            event: {
-                header: { namespace: "Alexa.SceneController", name: activated ? "ActivationStarted" : "DeactivationStarted", messageId: randomUUID(), correlationToken, payloadVersion: "3" },
-                endpoint: { endpointId: this.endpointId },
-                payload: { cause: { type: cause }, timestamp: new Date().toISOString() },
-            },
-        };
-        const topic = `${this.rootTopic}/${this.endpointId}/${sendAsync ? "deferredResponse" : "alexaResponce"}`;
-        return new Promise((resolve) => {
-            this.mqttClient.publish(topic, JSON.stringify(payload), (err) => {
-                if (!err)
-                    return resolve(topic);
-                if (this.onPublishError)
-                    this.onPublishError(err); // -> the bridge's "error" event (when somebody listens)
-                resolve(""); // 1.5.1 rejected here, and an un-caught send() then killed the host on any broker hiccup
-            });
-        });
-    }
-    getCapabilities() {
-        return this.capabilities.slice();
-    }
-    setManufacturerName(name) {
-        this.manufacturerName = name;
-    }
-    getManufacturerName() {
-        return this.manufacturerName;
-    }
-    setManufacturer(manufacturer) {
-        this.manufacturer = manufacturer;
-    }
-    getManufacturer() {
-        return this.manufacturer;
-    }
-    setModel(model) {
-        this.model = model;
-    }
-    getModel() {
-        return this.model;
-    }
-    getSoftwareVersion() {
-        return this.softwareVersion;
-    }
-    /** Add a capability. 1.5.1: options.retrievable / proactivelyReported / instance (a change report needs proactivelyReported). */
-    addCapability(type, options = {}) {
-        const newCapability = new AlexaInterface(type, options.retrievable ?? true, options.proactivelyReported ?? false, options.instance ?? "");
-        this.capabilities.push(newCapability);
-        // console.log(
-        //   `Created new interface with type: ${newCapability.getTypeString()}`
-        // );
-        return newCapability;
-    }
-    getJSON() {
-        return {
-            endpointId: this.endpointId,
-            friendlyName: this.name,
-            description: this.description,
-            manufacturerName: this.manufacturerName,
-            displayCategories: this.getDisplayCategory(),
-            additionalAttributes: {
-                manufacturer: this.manufacturer,
-                model: this.model,
-                serialNumber: "Alex2Node",
-                firmwareVersion: "1.0.0",
-                softwareVersion: this.softwareVersion,
-                customIdentifier: "Alex2Node",
-            },
-            capabilities: this.capabilities.map((cap) => cap.getJSON()),
-        };
-    }
-}
-export default Device;

dist/esm/DisplayCategory.d.ts

@@ -1,60 +0,0 @@
-export declare enum DisplayCategory {
-    ACTIVITY_TRIGGER = "ACTIVITY_TRIGGER",
-    AIR_CONDITIONER = "AIR_CONDITIONER",
-    AIR_FRESHENER = "AIR_FRESHENER",
-    AIR_PURIFIER = "AIR_PURIFIER",
-    AIR_QUALITY_MONITOR = "AIR_QUALITY_MONITOR",
-    ALEXA_VOICE_ENABLED = "ALEXA_VOICE_ENABLED",
-    AUTO_ACCESSORY = "AUTO_ACCESSORY",
-    BLUETOOTH_SPEAKER = "BLUETOOTH_SPEAKER",
-    CAMERA = "CAMERA",
-    CHRISTMAS_TREE = "CHRISTMAS_TREE",
-    COFFEE_MAKER = "COFFEE_MAKER",
-    COMPUTER = "COMPUTER",
-    CONTACT_SENSOR = "CONTACT_SENSOR",
-    DISHWASHER = "DISHWASHER",
-    DOOR = "DOOR",
-    DOORBELL = "DOORBELL",
-    DRYER = "DRYER",
-    EXTERIOR_BLIND = "EXTERIOR_BLIND",
-    FAN = "FAN",
-    GAME_CONSOLE = "GAME_CONSOLE",
-    GARAGE_DOOR = "GARAGE_DOOR",
-    HEADPHONES = "HEADPHONES",
-    HUB = "HUB",
-    INTERIOR_BLIND = "INTERIOR_BLIND",
-    LAPTOP = "LAPTOP",
-    LIGHT = "LIGHT",
-    MICROWAVE = "MICROWAVE",
-    MOBILE_PHONE = "MOBILE_PHONE",
-    MOTION_SENSOR = "MOTION_SENSOR",
-    MUSIC_SYSTEM = "MUSIC_SYSTEM",
-    NETWORK_HARDWARE = "NETWORK_HARDWARE",
-    OTHER = "OTHER",
-    OVEN = "OVEN",
-    PHONE = "PHONE",
-    PRINTER = "PRINTER",
-    REMOTE = "REMOTE",
-    ROUTER = "ROUTER",
-    SCENE_TRIGGER = "SCENE_TRIGGER",
-    SCREEN = "SCREEN",
-    SECURITY_PANEL = "SECURITY_PANEL",
-    SECURITY_SYSTEM = "SECURITY_SYSTEM",
-    SLOW_COOKER = "SLOW_COOKER",
-    SMARTLOCK = "SMARTLOCK",
-    SMARTPLUG = "SMARTPLUG",
-    SPEAKER = "SPEAKER",
-    STREAMING_DEVICE = "STREAMING_DEVICE",
-    SWITCH = "SWITCH",
-    TABLET = "TABLET",
-    TEMPERATURE_SENSOR = "TEMPERATURE_SENSOR",
-    THERMOSTAT = "THERMOSTAT",
-    TV = "TV",
-    VACUUM_CLEANER = "VACUUM_CLEANER",
-    VACUUM = "VACUUM",
-    /** Not on the list of display categories any more; kept for 1.x callers. */
-    VEHICLE = "VEHICLE",
-    WASHER = "WASHER",
-    WATER_HEATER = "WATER_HEATER",
-    WEARABLE = "WEARABLE"
-}

dist/esm/DisplayCategory.js

@@ -1,61 +0,0 @@
-export var DisplayCategory;
-(function (DisplayCategory) {
-    DisplayCategory["ACTIVITY_TRIGGER"] = "ACTIVITY_TRIGGER";
-    DisplayCategory["AIR_CONDITIONER"] = "AIR_CONDITIONER";
-    DisplayCategory["AIR_FRESHENER"] = "AIR_FRESHENER";
-    DisplayCategory["AIR_PURIFIER"] = "AIR_PURIFIER";
-    DisplayCategory["AIR_QUALITY_MONITOR"] = "AIR_QUALITY_MONITOR";
-    DisplayCategory["ALEXA_VOICE_ENABLED"] = "ALEXA_VOICE_ENABLED";
-    DisplayCategory["AUTO_ACCESSORY"] = "AUTO_ACCESSORY";
-    DisplayCategory["BLUETOOTH_SPEAKER"] = "BLUETOOTH_SPEAKER";
-    DisplayCategory["CAMERA"] = "CAMERA";
-    DisplayCategory["CHRISTMAS_TREE"] = "CHRISTMAS_TREE";
-    DisplayCategory["COFFEE_MAKER"] = "COFFEE_MAKER";
-    DisplayCategory["COMPUTER"] = "COMPUTER";
-    DisplayCategory["CONTACT_SENSOR"] = "CONTACT_SENSOR";
-    DisplayCategory["DISHWASHER"] = "DISHWASHER";
-    DisplayCategory["DOOR"] = "DOOR";
-    DisplayCategory["DOORBELL"] = "DOORBELL";
-    DisplayCategory["DRYER"] = "DRYER";
-    DisplayCategory["EXTERIOR_BLIND"] = "EXTERIOR_BLIND";
-    DisplayCategory["FAN"] = "FAN";
-    DisplayCategory["GAME_CONSOLE"] = "GAME_CONSOLE";
-    DisplayCategory["GARAGE_DOOR"] = "GARAGE_DOOR";
-    DisplayCategory["HEADPHONES"] = "HEADPHONES";
-    DisplayCategory["HUB"] = "HUB";
-    DisplayCategory["INTERIOR_BLIND"] = "INTERIOR_BLIND";
-    DisplayCategory["LAPTOP"] = "LAPTOP";
-    DisplayCategory["LIGHT"] = "LIGHT";
-    DisplayCategory["MICROWAVE"] = "MICROWAVE";
-    DisplayCategory["MOBILE_PHONE"] = "MOBILE_PHONE";
-    DisplayCategory["MOTION_SENSOR"] = "MOTION_SENSOR";
-    DisplayCategory["MUSIC_SYSTEM"] = "MUSIC_SYSTEM";
-    DisplayCategory["NETWORK_HARDWARE"] = "NETWORK_HARDWARE";
-    DisplayCategory["OTHER"] = "OTHER";
-    DisplayCategory["OVEN"] = "OVEN";
-    DisplayCategory["PHONE"] = "PHONE";
-    DisplayCategory["PRINTER"] = "PRINTER";
-    DisplayCategory["REMOTE"] = "REMOTE";
-    DisplayCategory["ROUTER"] = "ROUTER";
-    DisplayCategory["SCENE_TRIGGER"] = "SCENE_TRIGGER";
-    DisplayCategory["SCREEN"] = "SCREEN";
-    DisplayCategory["SECURITY_PANEL"] = "SECURITY_PANEL";
-    DisplayCategory["SECURITY_SYSTEM"] = "SECURITY_SYSTEM";
-    DisplayCategory["SLOW_COOKER"] = "SLOW_COOKER";
-    DisplayCategory["SMARTLOCK"] = "SMARTLOCK";
-    DisplayCategory["SMARTPLUG"] = "SMARTPLUG";
-    DisplayCategory["SPEAKER"] = "SPEAKER";
-    DisplayCategory["STREAMING_DEVICE"] = "STREAMING_DEVICE";
-    DisplayCategory["SWITCH"] = "SWITCH";
-    DisplayCategory["TABLET"] = "TABLET";
-    DisplayCategory["TEMPERATURE_SENSOR"] = "TEMPERATURE_SENSOR";
-    DisplayCategory["THERMOSTAT"] = "THERMOSTAT";
-    DisplayCategory["TV"] = "TV";
-    DisplayCategory["VACUUM_CLEANER"] = "VACUUM_CLEANER";
-    DisplayCategory["VACUUM"] = "VACUUM";
-    /** Not on the list of display categories any more; kept for 1.x callers. */
-    DisplayCategory["VEHICLE"] = "VEHICLE";
-    DisplayCategory["WASHER"] = "WASHER";
-    DisplayCategory["WATER_HEATER"] = "WATER_HEATER";
-    DisplayCategory["WEARABLE"] = "WEARABLE";
-})(DisplayCategory || (DisplayCategory = {}));

dist/esm/compat/ActionMapping.d.ts

@@ -0,0 +1,23 @@
+import type { ActionsToDirective } from "../registry/types.js";
+import type { AlexaActions } from "./enums.js";
+/**
+ * A semantics action mapping of 1.x: the phrases "open", "close", "raise", "lower" for one directive of the
+ * capability it is added to.
+ *
+ *   toggle.addActionMapping(new ActionMapping([AlexaActions.Close], "TurnOff"));
+ *   lift.addActionMapping(new ActionMapping([AlexaActions.Open], "SetRangeValue", { rangeValue: 100 }));
+ */
+export declare class ActionMapping {
+    type: "ActionsToDirective";
+    actions: AlexaActions[];
+    directive: ActionsToDirective["directive"];
+    /** Set when the mapping was built in a way that 3.0 will refuse; the bridge logs it at the next discovery. */
+    readonly deprecation?: string;
+    /**
+     * directivePayload is the payload object of the directive (alexa-discovery-objects.html, "ActionMappings object").
+     * 1.x took a string and put it into discovery as one. A string that holds a JSON object is parsed; any other
+     * string throws a DeclarationError.
+     */
+    constructor(actions: AlexaActions[], directiveName: string, directivePayload?: Record<string, unknown> | string);
+    toJSON(): ActionsToDirective;
+}

dist/esm/compat/ActionMapping.js

@@ -0,0 +1,45 @@
+import { DeclarationError } from "../registry/types.js";
+/**
+ * A semantics action mapping of 1.x: the phrases "open", "close", "raise", "lower" for one directive of the
+ * capability it is added to.
+ *
+ *   toggle.addActionMapping(new ActionMapping([AlexaActions.Close], "TurnOff"));
+ *   lift.addActionMapping(new ActionMapping([AlexaActions.Open], "SetRangeValue", { rangeValue: 100 }));
+ */
+export class ActionMapping {
+    /**
+     * directivePayload is the payload object of the directive (alexa-discovery-objects.html, "ActionMappings object").
+     * 1.x took a string and put it into discovery as one. A string that holds a JSON object is parsed; any other
+     * string throws a DeclarationError.
+     */
+    constructor(actions, directiveName, directivePayload) {
+        this.type = "ActionsToDirective";
+        this.actions = actions;
+        this.directive = { name: directiveName };
+        if (typeof directivePayload === "string") {
+            if (directivePayload === "")
+                return;
+            this.directive.payload = objectIn(directivePayload, directiveName);
+            this.deprecation = `the payload of the action mapping for ${directiveName} is a JSON string, pass the object`;
+        }
+        else if (directivePayload) {
+            this.directive.payload = directivePayload;
+        }
+    }
+    toJSON() {
+        return { "@type": this.type, actions: this.actions, directive: this.directive };
+    }
+}
+function objectIn(text, directiveName) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        value = undefined;
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new DeclarationError({}, `the payload of the action mapping for ${directiveName} is an object, got the string ${JSON.stringify(text)}`);
+    }
+    return value;
+}

dist/esm/compat/AlexaInterface.d.ts

@@ -0,0 +1,49 @@
+import { Capability } from "../device/Capability.js";
+import type { CapabilityJson } from "../device/Capability.js";
+import type { Semantics } from "../registry/types.js";
+import type { ActionMapping } from "./ActionMapping.js";
+import type { AlexaInterfaceType } from "./enums.js";
+/** One ModeController mode as discovery lists it (configuration.supportedModes): the value plus its friendly names. */
+export interface SupportedMode {
+    value: string;
+    modeResources?: {
+        friendlyNames: Array<{
+            "@type": string;
+            value: {
+                text?: string;
+                locale?: string;
+                assetId?: string;
+            };
+        }>;
+    };
+}
+interface Options {
+    semantics?: Semantics;
+    supportedModes?: Array<string | SupportedMode>;
+}
+/**
+ * A capability as 1.x declares it: device.addCapability(type, options), then the add and set methods below. It is a
+ * Capability, so what the methods set reaches discovery the same way as the options of device.add(). Nothing is
+ * refused here except an interface name the registry does not have: what Alexa would reject is logged by the bridge
+ * when it answers a discovery.
+ */
+export declare class AlexaInterface extends Capability<any, any, Options> {
+    constructor(type: AlexaInterfaceType | string, retrievable?: boolean, proactivelyReported?: boolean, instance?: string);
+    /** The namespace of the interface, which is the value of its AlexaInterfaceType member. */
+    get type(): AlexaInterfaceType;
+    addActionMapping(mapping: ActionMapping): void;
+    addFriendlyName(name: string, locale: string): void;
+    /** The modes of a ModeController, as { value, modeResources } objects. */
+    addSupportedModes(modes: Array<string | SupportedMode>): void;
+    setInstance(name: string): void;
+    getType(): AlexaInterfaceType;
+    /** @deprecated The same as getType(). */
+    getTypeString(): string;
+    /** @deprecated Read descriptor.version. */
+    getVersion(): string;
+    /** @deprecated Read the keys of descriptor.properties. */
+    getProps(): string[];
+    getJSON(): CapabilityJson;
+    toJSON(): CapabilityJson;
+}
+export {};

dist/esm/compat/AlexaInterface.js

@@ -0,0 +1,57 @@
+import { Capability } from "../device/Capability.js";
+import { registry } from "../registry/index.js";
+import { text } from "../registry/resources.js";
+/**
+ * A capability as 1.x declares it: device.addCapability(type, options), then the add and set methods below. It is a
+ * Capability, so what the methods set reaches discovery the same way as the options of device.add(). Nothing is
+ * refused here except an interface name the registry does not have: what Alexa would reject is logged by the bridge
+ * when it answers a discovery.
+ */
+export class AlexaInterface extends Capability {
+    constructor(type, retrievable = true, proactivelyReported = false, instance = "") {
+        super(registry.get(type), { retrievable, proactivelyReported, instance, options: {} });
+    }
+    /** The namespace of the interface, which is the value of its AlexaInterfaceType member. */
+    get type() {
+        return this.descriptor.namespace;
+    }
+    addActionMapping(mapping) {
+        var _a;
+        const semantics = ((_a = this.options).semantics ?? (_a.semantics = {}));
+        (semantics.actionMappings ?? (semantics.actionMappings = [])).push(mapping.toJSON());
+        if (mapping.deprecation)
+            this.notes.push(mapping.deprecation);
+    }
+    addFriendlyName(name, locale) {
+        this.friendlyNames.push(text(name, locale));
+    }
+    /** The modes of a ModeController, as { value, modeResources } objects. */
+    addSupportedModes(modes) {
+        this.options.supportedModes = modes;
+    }
+    setInstance(name) {
+        this.instance = name;
+    }
+    getType() {
+        return this.type;
+    }
+    /** @deprecated The same as getType(). */
+    getTypeString() {
+        return this.type;
+    }
+    /** @deprecated Read descriptor.version. */
+    getVersion() {
+        return this.descriptor.version;
+    }
+    /** @deprecated Read the keys of descriptor.properties. */
+    getProps() {
+        return Object.keys(this.descriptor.properties);
+    }
+    getJSON() {
+        return super.toJSON();
+    }
+    // 1.x callers corrected the discovery JSON by replacing getJSON on the object: discovery goes through it
+    toJSON() {
+        return this.getJSON();
+    }
+}

dist/esm/compat/enums.d.ts

@@ -0,0 +1,193 @@
+/** Every interface name of 1.x. registry.get() takes a member as it takes the namespace, which is its value. */
+export declare enum AlexaInterfaceType {
+    APPLICATION_STATE_REPORTER = "Alexa.ApplicationStateReporter",
+    AUDIO_PLAY_QUEUE = "Alexa.Audio.PlayQueue",
+    AUTHORIZATION_CONTROLLER = "Alexa.AuthorizationController",
+    AUTOMATION_MANAGEMENT = "Alexa.AutomationManagement",
+    AUTOMOTIVE_VEHICLE_DATA = "Alexa.Automotive.VehicleData",
+    BRIGHTNESS_CONTROLLER = "Alexa.BrightnessController",
+    CAMERA_LIVE_VIEW_CONTROLLER = "Alexa.Camera.LiveViewController",
+    CAMERA_STREAM_CONTROLLER = "Alexa.CameraStreamController",
+    CHANNEL_CONTROLLER = "Alexa.ChannelController",
+    COLOR_CONTROLLER = "Alexa.ColorController",
+    COLOR_TEMPERATURE_CONTROLLER = "Alexa.ColorTemperatureController",
+    COMMISSIONABLE = "Alexa.Commissionable",
+    CONSENT_MANAGEMENT_CONSENT_REQUIRED_REPORTER = "Alexa.ConsentManagement.ConsentRequiredReporter",
+    CONTACT_SENSOR = "Alexa.ContactSensor",
+    COOKING = "Alexa.Cooking",
+    COOKING_FOOD_TEMPERATURE_CONTROLLER = "Alexa.Cooking.FoodTemperatureController",
+    COOKING_FOOD_TEMPERATURE_SENSOR = "Alexa.Cooking.FoodTemperatureSensor",
+    COOKING_PRESET_CONTROLLER = "Alexa.Cooking.PresetController",
+    COOKING_TEMPERATURE_CONTROLLER = "Alexa.Cooking.TemperatureController",
+    COOKING_TEMPERATURE_SENSOR = "Alexa.Cooking.TemperatureSensor",
+    COOKING_TIME_CONTROLLER = "Alexa.Cooking.TimeController",
+    DATA_CONTROLLER = "Alexa.DataController",
+    DEVICE_USAGE_ESTIMATION = "Alexa.DeviceUsage.Estimation",
+    DEVICE_USAGE_METER = "Alexa.DeviceUsage.Meter",
+    DOORBELL_EVENT_SOURCE = "Alexa.DoorbellEventSource",
+    ENDPOINT_HEALTH = "Alexa.EndpointHealth",
+    EQUALIZER_CONTROLLER = "Alexa.EqualizerController",
+    INPUT_CONTROLLER = "Alexa.InputController",
+    INVENTORY_LEVEL_SENSOR = "Alexa.InventoryLevelSensor",
+    INVENTORY_LEVEL_USAGE_SENSOR = "Alexa.InventoryLevelUsageSensor",
+    INVENTORY_USAGE_SENSOR = "Alexa.InventoryUsageSensor",
+    KEYPAD_CONTROLLER = "Alexa.KeypadController",
+    LAUNCHER = "Alexa.Launcher",
+    LOCK_CONTROLLER = "Alexa.LockController",
+    MEDIA_PLAYBACK = "Alexa.Media.Playback",
+    MEDIA_PLAY_QUEUE = "Alexa.Media.PlayQueue",
+    MEDIA_SEARCH = "Alexa.Media.Search",
+    MODE_CONTROLLER = "Alexa.ModeController",
+    MOTION_SENSOR = "Alexa.MotionSensor",
+    PERCENTAGE_CONTROLLER = "Alexa.PercentageController",
+    PLAYBACK_CONTROLLER = "Alexa.PlaybackController",
+    PLAYBACK_STATE_REPORTER = "Alexa.PlaybackStateReporter",
+    POWER_CONTROLLER = "Alexa.PowerController",
+    POWER_LEVEL_CONTROLLER = "Alexa.PowerLevelController",
+    PROACTIVE_NOTIFICATION_SOURCE = "Alexa.ProactiveNotificationSource",
+    RANGE_CONTROLLER = "Alexa.RangeController",
+    RECORD_CONTROLLER = "Alexa.RecordController",
+    REMOTE_VIDEO_PLAYER = "Alexa.RemoteVideoPlayer",
+    RTC_SESSION_CONTROLLER = "Alexa.RTCSessionController",
+    SCENE_CONTROLLER = "Alexa.SceneController",
+    SECURITY_PANEL_CONTROLLER = "Alexa.SecurityPanelController",
+    SECURITY_PANEL_CONTROLLER_ALERT = "Alexa.SecurityPanelController.Alert",
+    SEEK_CONTROLLER = "Alexa.SeekController",
+    SIMPLE_EVENT_SOURCE = "Alexa.SimpleEventSource",
+    SMART_VISION_OBJECT_DETECTION_SENSOR = "Alexa.SmartVision.ObjectDetectionSensor",
+    SMART_VISION_SNAPSHOT_PROVIDER = "Alexa.SmartVision.SnapshotProvider",
+    SPEAKER = "Alexa.Speaker",
+    STEP_SPEAKER = "Alexa.StepSpeaker",
+    TEMPERATURE_SENSOR = "Alexa.TemperatureSensor",
+    THERMOSTAT_CONTROLLER = "Alexa.ThermostatController",
+    THERMOSTAT_CONTROLLER_CONFIGURATION = "Alexa.ThermostatController.Configuration",
+    THERMOSTAT_CONTROLLER_HVAC_COMPONENTS = "Alexa.ThermostatController.HVAC.Components",
+    THERMOSTAT_CONTROLLER_SCHEDULE = "Alexa.ThermostatController.Schedule",
+    TIME_HOLD_CONTROLLER = "Alexa.TimeHoldController",
+    TOGGLE_CONTROLLER = "Alexa.ToggleController",
+    UI_CONTROLLER = "Alexa.UIController",
+    USER_PREFERENCE = "Alexa.UserPreference",
+    VIDEO_RECORDER = "Alexa.VideoRecorder",
+    WAKE_ON_LAN_CONTROLLER = "Alexa.WakeOnLANController",
+    /** Not an interface: declaring it throws a DeclarationError. Kept because 1.x had it. */
+    UNKNOWN = "UNKNOWN"
+}
+export declare enum DisplayCategory {
+    ACTIVITY_TRIGGER = "ACTIVITY_TRIGGER",
+    AIR_CONDITIONER = "AIR_CONDITIONER",
+    AIR_FRESHENER = "AIR_FRESHENER",
+    AIR_PURIFIER = "AIR_PURIFIER",
+    AIR_QUALITY_MONITOR = "AIR_QUALITY_MONITOR",
+    ALEXA_VOICE_ENABLED = "ALEXA_VOICE_ENABLED",
+    AUTO_ACCESSORY = "AUTO_ACCESSORY",
+    BLUETOOTH_SPEAKER = "BLUETOOTH_SPEAKER",
+    CAMERA = "CAMERA",
+    CHRISTMAS_TREE = "CHRISTMAS_TREE",
+    COFFEE_MAKER = "COFFEE_MAKER",
+    COMPUTER = "COMPUTER",
+    CONTACT_SENSOR = "CONTACT_SENSOR",
+    DISHWASHER = "DISHWASHER",
+    DOOR = "DOOR",
+    DOORBELL = "DOORBELL",
+    DRYER = "DRYER",
+    EXTERIOR_BLIND = "EXTERIOR_BLIND",
+    FAN = "FAN",
+    GAME_CONSOLE = "GAME_CONSOLE",
+    GARAGE_DOOR = "GARAGE_DOOR",
+    HEADPHONES = "HEADPHONES",
+    HUB = "HUB",
+    INTERIOR_BLIND = "INTERIOR_BLIND",
+    LAPTOP = "LAPTOP",
+    LIGHT = "LIGHT",
+    MICROWAVE = "MICROWAVE",
+    MOBILE_PHONE = "MOBILE_PHONE",
+    MOTION_SENSOR = "MOTION_SENSOR",
+    MUSIC_SYSTEM = "MUSIC_SYSTEM",
+    NETWORK_HARDWARE = "NETWORK_HARDWARE",
+    OTHER = "OTHER",
+    OVEN = "OVEN",
+    PHONE = "PHONE",
+    PRINTER = "PRINTER",
+    REMOTE = "REMOTE",
+    ROUTER = "ROUTER",
+    SCENE_TRIGGER = "SCENE_TRIGGER",
+    SCREEN = "SCREEN",
+    SECURITY_PANEL = "SECURITY_PANEL",
+    SECURITY_SYSTEM = "SECURITY_SYSTEM",
+    SLOW_COOKER = "SLOW_COOKER",
+    SMARTLOCK = "SMARTLOCK",
+    SMARTPLUG = "SMARTPLUG",
+    SPEAKER = "SPEAKER",
+    STREAMING_DEVICE = "STREAMING_DEVICE",
+    SWITCH = "SWITCH",
+    TABLET = "TABLET",
+    TEMPERATURE_SENSOR = "TEMPERATURE_SENSOR",
+    THERMOSTAT = "THERMOSTAT",
+    TV = "TV",
+    VACUUM_CLEANER = "VACUUM_CLEANER",
+    VACUUM = "VACUUM",
+    /** Not on the list of display categories any more; kept for 1.x callers. */
+    VEHICLE = "VEHICLE",
+    WASHER = "WASHER",
+    WATER_HEATER = "WATER_HEATER",
+    WEARABLE = "WEARABLE"
+}
+export declare enum AlexaActions {
+    Open = "Alexa.Actions.Open",
+    Close = "Alexa.Actions.Close",
+    Raise = "Alexa.Actions.Raise",
+    Lower = "Alexa.Actions.Lower",
+    SetEcoOn = "Alexa.Actions.SetEcoOn",
+    SetEcoOff = "Alexa.Actions.SetEcoOff"
+}
+/** The values of powerState and toggleState. */
+export declare const PowerState: {
+    readonly ON: "ON";
+    readonly OFF: "OFF";
+};
+export type PowerState = (typeof PowerState)[keyof typeof PowerState];
+declare const Connectivity: {
+    readonly OK: "OK";
+    readonly UNREACHABLE: "UNREACHABLE";
+};
+/**
+ * The Alexa.PowerController interface, for device.add(). PowerController.ON and PowerController.OFF are the 1.x enum
+ * of power states and stay until 3.0: PowerState has the same two members.
+ */
+export declare const PowerController: import("../index.js").InterfaceDescriptor<{
+    powerState: {
+        name: string;
+        value: import("../registry/schema.js").EnumSchema<"ON" | "OFF">;
+    };
+}, {
+    TurnOn: {
+        name: string;
+        payload: import("../index.js").Schema<import("../registry/schema.js").InferShape<{}>>;
+    };
+    TurnOff: {
+        name: string;
+        payload: import("../index.js").Schema<import("../registry/schema.js").InferShape<{}>>;
+    };
+}, import("../registry/schema.js").InferShape<{
+    verificationsRequired: import("../registry/schema.js").OptionalSchema<("TurnOn" | "TurnOff")[]>;
+}>, false> & {
+    readonly ON: "ON";
+    readonly OFF: "OFF";
+};
+export type PowerController = PowerState;
+/** The Alexa.EndpointHealth interface, for device.add(). EndpointHealth.OK and EndpointHealth.UNREACHABLE are the 1.x enum of connectivity values. */
+export declare const EndpointHealth: import("../index.js").InterfaceDescriptor<{
+    connectivity: {
+        name: string;
+        value: import("../index.js").Schema<import("../registry/schema.js").InferShape<{
+            value: import("../registry/schema.js").EnumSchema<"OK" | "UNREACHABLE">;
+            reason: import("../registry/schema.js").OptionalSchema<"WIFI_BAD_PASSWORD" | "WIFI_AP_NOT_FOUND" | "WIFI_ROUTER_UNREACHABLE" | "WIFI_AP_CHANNEL_QUALITY_LOW" | "INTERNET_UNREACHABLE" | "CAPTIVE_PORTAL_CHECK_FAILED" | "UNKNOWN">;
+        }>>;
+        note: string;
+    };
+}, {}, {}, false> & {
+    readonly OK: "OK";
+    readonly UNREACHABLE: "UNREACHABLE";
+};
+export type EndpointHealth = (typeof Connectivity)[keyof typeof Connectivity];
+export {};

dist/esm/compat/enums.js

@@ -1,4 +1,7 @@
-import { registry } from "./registry/index.js";
+// The enums of 1.x, under their 1.x names.
+import { EndpointHealth as EndpointHealthInterface } from "../registry/interfaces/EndpointHealth.js";
+import { PowerController as PowerControllerInterface } from "../registry/interfaces/PowerController.js";
+/** Every interface name of 1.x. registry.get() takes a member as it takes the namespace, which is its value. */
 export var AlexaInterfaceType;
 (function (AlexaInterfaceType) {
     AlexaInterfaceType["APPLICATION_STATE_REPORTER"] = "Alexa.ApplicationStateReporter";
@@ -70,96 +73,88 @@ export var AlexaInterfaceType;
     AlexaInterfaceType["USER_PREFERENCE"] = "Alexa.UserPreference";
     AlexaInterfaceType["VIDEO_RECORDER"] = "Alexa.VideoRecorder";
     AlexaInterfaceType["WAKE_ON_LAN_CONTROLLER"] = "Alexa.WakeOnLANController";
+    /** Not an interface: declaring it throws a DeclarationError. Kept because 1.x had it. */
     AlexaInterfaceType["UNKNOWN"] = "UNKNOWN";
 })(AlexaInterfaceType || (AlexaInterfaceType = {}));
-export class AlexaInterface {
-    constructor(type, retrievable = true, proactivelyReported = false, instance = "") {
-        this.type = type;
-        this.retrievable = retrievable;
-        this.proactivelyReported = proactivelyReported;
-        this.instance = instance;
-        this.friendlyNames = [];
-        this.actionMappings = [];
-        this.supportedModes = [];
-    }
-    addActionMapping(mapping) {
-        this.actionMappings.push(mapping);
-    }
-    addFriendlyName(name, locale) {
-        this.friendlyNames.push({ text: name, locale });
-    }
-    /** The modes of a ModeController: { value, modeResources } objects as Alexa wants them (plain strings pass through as given). */
-    addSupportedModes(modes) {
-        this.supportedModes = modes;
-    }
-    setInstance(name) {
-        this.instance = name;
-    }
-    getType() {
-        return this.type;
-    }
-    getTypeString() {
-        return this.type;
-    }
-    /** The version of the interface, from its descriptor. "UNKNOWN" for a name the registry does not have. */
-    getVersion() {
-        return registry.has(this.type) ? registry.get(this.type).version : "UNKNOWN";
-    }
-    /** The names of the properties the interface reports, from its descriptor. */
-    getProps() {
-        return registry.has(this.type) ? Object.keys(registry.get(this.type).properties) : [];
-    }
-    getJSON() {
-        const doc = {
-            interface: this.getTypeString(),
-            version: this.getVersion(),
-            type: "AlexaInterface",
-            properties: {
-                retrievable: this.retrievable,
-                proactivelyReported: this.proactivelyReported,
-                supported: this.getProps().map(name => ({ name })),
-            },
-        };
-        if (this.type == AlexaInterfaceType.SCENE_CONTROLLER) {
-            // Alexa.SceneController v3 carries no properties block: supportsDeactivation + proactivelyReported at the top level
-            delete doc.properties;
-            doc.supportsDeactivation = true;
-            doc.proactivelyReported = this.proactivelyReported;
-        }
-        else if (this.type == AlexaInterfaceType.THERMOSTAT_CONTROLLER) {
-            doc.configuration = {
-                "supportedModes": ["HEAT", "COOL", "AUTO", "OFF"],
-                "supportsScheduling": false
-            };
-        }
-        else if (this.supportedModes.length > 0) {
-            doc["configuration"] = {
-                ordered: true,
-                supportedModes: this.supportedModes,
-            };
-        }
-        if (this.instance) {
-            doc.instance = this.instance;
-        }
-        if (this.friendlyNames.length > 0) {
-            const capabilityResources = doc["capabilityResources"] || {};
-            const friendlyNamesArray = capabilityResources["friendlyNames"] || [];
-            this.friendlyNames.forEach((fn) => {
-                const friendlyNameObj = { "@type": "text" };
-                friendlyNameObj["value"] = {
-                    text: fn.text,
-                    locale: fn.locale,
-                };
-                friendlyNamesArray.push(friendlyNameObj);
-            });
-            capabilityResources.friendlyNames = friendlyNamesArray;
-            doc["capabilityResources"] = capabilityResources;
-        }
-        if (this.actionMappings.length > 0) {
-            doc.semantics = {
-                actionMappings: this.actionMappings.map((am) => am.toJSON()),
-            };
-        }
-        return doc;
-    }
-}
+export var DisplayCategory;
+(function (DisplayCategory) {
+    DisplayCategory["ACTIVITY_TRIGGER"] = "ACTIVITY_TRIGGER";
+    DisplayCategory["AIR_CONDITIONER"] = "AIR_CONDITIONER";
+    DisplayCategory["AIR_FRESHENER"] = "AIR_FRESHENER";
+    DisplayCategory["AIR_PURIFIER"] = "AIR_PURIFIER";
+    DisplayCategory["AIR_QUALITY_MONITOR"] = "AIR_QUALITY_MONITOR";
+    DisplayCategory["ALEXA_VOICE_ENABLED"] = "ALEXA_VOICE_ENABLED";
+    DisplayCategory["AUTO_ACCESSORY"] = "AUTO_ACCESSORY";
+    DisplayCategory["BLUETOOTH_SPEAKER"] = "BLUETOOTH_SPEAKER";
+    DisplayCategory["CAMERA"] = "CAMERA";
+    DisplayCategory["CHRISTMAS_TREE"] = "CHRISTMAS_TREE";
+    DisplayCategory["COFFEE_MAKER"] = "COFFEE_MAKER";
+    DisplayCategory["COMPUTER"] = "COMPUTER";
+    DisplayCategory["CONTACT_SENSOR"] = "CONTACT_SENSOR";
+    DisplayCategory["DISHWASHER"] = "DISHWASHER";
+    DisplayCategory["DOOR"] = "DOOR";
+    DisplayCategory["DOORBELL"] = "DOORBELL";
+    DisplayCategory["DRYER"] = "DRYER";
+    DisplayCategory["EXTERIOR_BLIND"] = "EXTERIOR_BLIND";
+    DisplayCategory["FAN"] = "FAN";
+    DisplayCategory["GAME_CONSOLE"] = "GAME_CONSOLE";
+    DisplayCategory["GARAGE_DOOR"] = "GARAGE_DOOR";
+    DisplayCategory["HEADPHONES"] = "HEADPHONES";
+    DisplayCategory["HUB"] = "HUB";
+    DisplayCategory["INTERIOR_BLIND"] = "INTERIOR_BLIND";
+    DisplayCategory["LAPTOP"] = "LAPTOP";
+    DisplayCategory["LIGHT"] = "LIGHT";
+    DisplayCategory["MICROWAVE"] = "MICROWAVE";
+    DisplayCategory["MOBILE_PHONE"] = "MOBILE_PHONE";
+    DisplayCategory["MOTION_SENSOR"] = "MOTION_SENSOR";
+    DisplayCategory["MUSIC_SYSTEM"] = "MUSIC_SYSTEM";
+    DisplayCategory["NETWORK_HARDWARE"] = "NETWORK_HARDWARE";
+    DisplayCategory["OTHER"] = "OTHER";
+    DisplayCategory["OVEN"] = "OVEN";
+    DisplayCategory["PHONE"] = "PHONE";
+    DisplayCategory["PRINTER"] = "PRINTER";
+    DisplayCategory["REMOTE"] = "REMOTE";
+    DisplayCategory["ROUTER"] = "ROUTER";
+    DisplayCategory["SCENE_TRIGGER"] = "SCENE_TRIGGER";
+    DisplayCategory["SCREEN"] = "SCREEN";
+    DisplayCategory["SECURITY_PANEL"] = "SECURITY_PANEL";
+    DisplayCategory["SECURITY_SYSTEM"] = "SECURITY_SYSTEM";
+    DisplayCategory["SLOW_COOKER"] = "SLOW_COOKER";
+    DisplayCategory["SMARTLOCK"] = "SMARTLOCK";
+    DisplayCategory["SMARTPLUG"] = "SMARTPLUG";
+    DisplayCategory["SPEAKER"] = "SPEAKER";
+    DisplayCategory["STREAMING_DEVICE"] = "STREAMING_DEVICE";
+    DisplayCategory["SWITCH"] = "SWITCH";
+    DisplayCategory["TABLET"] = "TABLET";
+    DisplayCategory["TEMPERATURE_SENSOR"] = "TEMPERATURE_SENSOR";
+    DisplayCategory["THERMOSTAT"] = "THERMOSTAT";
+    DisplayCategory["TV"] = "TV";
+    DisplayCategory["VACUUM_CLEANER"] = "VACUUM_CLEANER";
+    DisplayCategory["VACUUM"] = "VACUUM";
+    /** Not on the list of display categories any more; kept for 1.x callers. */
+    DisplayCategory["VEHICLE"] = "VEHICLE";
+    DisplayCategory["WASHER"] = "WASHER";
+    DisplayCategory["WATER_HEATER"] = "WATER_HEATER";
+    DisplayCategory["WEARABLE"] = "WEARABLE";
+})(DisplayCategory || (DisplayCategory = {}));
+export var AlexaActions;
+(function (AlexaActions) {
+    AlexaActions["Open"] = "Alexa.Actions.Open";
+    AlexaActions["Close"] = "Alexa.Actions.Close";
+    AlexaActions["Raise"] = "Alexa.Actions.Raise";
+    AlexaActions["Lower"] = "Alexa.Actions.Lower";
+    AlexaActions["SetEcoOn"] = "Alexa.Actions.SetEcoOn";
+    AlexaActions["SetEcoOff"] = "Alexa.Actions.SetEcoOff";
+})(AlexaActions || (AlexaActions = {}));
+/** The values of powerState and toggleState. */
+export const PowerState = { ON: "ON", OFF: "OFF" };
+const Connectivity = { OK: "OK", UNREACHABLE: "UNREACHABLE" };
+// PowerController and EndpointHealth were enums in 1.x and are the names of two interfaces. One export serves both:
+// the descriptor, which also has the members of the enum, and a type of the same name for the values.
+/**
+ * The Alexa.PowerController interface, for device.add(). PowerController.ON and PowerController.OFF are the 1.x enum
+ * of power states and stay until 3.0: PowerState has the same two members.
+ */
+export const PowerController = Object.assign(PowerControllerInterface, PowerState);
+/** The Alexa.EndpointHealth interface, for device.add(). EndpointHealth.OK and EndpointHealth.UNREACHABLE are the 1.x enum of connectivity values. */
+export const EndpointHealth = Object.assign(EndpointHealthInterface, Connectivity);

dist/esm/device/Capability.d.ts

@@ -0,0 +1,79 @@
+import type { Declared, Directives, InterfaceDescriptor, Label, Properties, Semantics } from "../registry/types.js";
+/** What a declaration can set for any interface. */
+export interface CommonOptions {
+    /** The name of the instance of a generic controller: "Blind.Lift", "Fan.Speed". */
+    instance?: string;
+    /** What the user calls the instance; the first name is the one the Alexa app shows. */
+    friendlyNames?: Label[];
+    /** The properties are in the answer to ReportState. Default: true. */
+    retrievable?: boolean;
+    /** A change of the properties is sent to Alexa as a ChangeReport. Default: false. */
+    proactivelyReported?: boolean;
+    /** The user can ask for the properties and cannot set them. Left out of discovery when not given. */
+    nonControllable?: boolean;
+}
+/** The same as a schema. The friendly names are checked with the instance, by the rules of the interface. */
+export declare const commonOptions: import("../registry/schema.js").Schema<import("../registry/schema.js").InferShape<{
+    instance: import("../registry/schema.js").OptionalSchema<string>;
+    friendlyNames: import("../registry/schema.js").OptionalSchema<unknown[]>;
+    retrievable: import("../registry/schema.js").OptionalSchema<boolean>;
+    proactivelyReported: import("../registry/schema.js").OptionalSchema<boolean>;
+    nonControllable: import("../registry/schema.js").OptionalSchema<boolean>;
+}>>;
+type Naming<I extends boolean> = I extends true ? {
+    instance: string;
+    friendlyNames: Label[];
+} : {
+    instance?: string;
+    friendlyNames?: Label[];
+};
+/** The options of device.add() for one interface: its own, and the ones every interface has. */
+export type Declaration<O, I extends boolean> = O & Omit<CommonOptions, "instance" | "friendlyNames"> & Naming<I>;
+/** A capability object of a discovery answer (alexa-discovery-objects.html, "Capability object"). */
+export interface CapabilityJson {
+    type: "AlexaInterface";
+    interface: string;
+    instance?: string;
+    version: string;
+    properties?: {
+        supported: Array<{
+            name: string;
+        }>;
+        proactivelyReported: boolean;
+        retrievable: boolean;
+        nonControllable?: boolean;
+    };
+    capabilityResources?: {
+        friendlyNames: Label[];
+    };
+    configuration?: Record<string, unknown>;
+    configurations?: Record<string, unknown>;
+    semantics?: Semantics;
+    [field: string]: unknown;
+}
+/** One interface as an endpoint declares it: the descriptor, and what the declaration says about this endpoint. */
+export declare class Capability<P extends Properties = Properties, D extends Directives = Directives, O = {}> implements Declared<O> {
+    readonly descriptor: InterfaceDescriptor<P, D, O, boolean>;
+    /** The endpoint the capability is declared on; the device sets it. */
+    endpointId: string;
+    /** "" for an interface without instances. */
+    instance: string;
+    friendlyNames: Label[];
+    retrievable: boolean;
+    proactivelyReported: boolean;
+    nonControllable?: boolean;
+    /** The options of the interface: a range, the supported modes, the semantics. */
+    options: O;
+    /** What the bridge logs about the declaration, once, when it answers a discovery. */
+    readonly notes: string[];
+    constructor(descriptor: InterfaceDescriptor<P, D, O, boolean>, declared: CommonOptions & {
+        options: O;
+    });
+    get namespace(): string;
+    /** Mappings of "open", "close", "raise", "lower" and of states, when the declaration has any. */
+    get semantics(): Semantics | undefined;
+    /** The capability object for discovery, its fields in the order of the example on alexa-discovery-objects.html. */
+    toJSON(): CapabilityJson;
+}
+export type AnyCapability = Capability<any, any, any>;
+export {};

dist/esm/device/Capability.js

@@ -0,0 +1,63 @@
+import { s } from "../registry/schema.js";
+/** The same as a schema. The friendly names are checked with the instance, by the rules of the interface. */
+export const commonOptions = s.object({
+    instance: s.optional(s.string()),
+    friendlyNames: s.optional(s.array(s.unknown())),
+    retrievable: s.optional(s.boolean()),
+    proactivelyReported: s.optional(s.boolean()),
+    nonControllable: s.optional(s.boolean()),
+});
+/** One interface as an endpoint declares it: the descriptor, and what the declaration says about this endpoint. */
+export class Capability {
+    constructor(descriptor, declared) {
+        this.descriptor = descriptor;
+        /** The endpoint the capability is declared on; the device sets it. */
+        this.endpointId = "";
+        /** What the bridge logs about the declaration, once, when it answers a discovery. */
+        this.notes = [];
+        this.instance = declared.instance ?? "";
+        this.friendlyNames = declared.friendlyNames ?? [];
+        this.retrievable = declared.retrievable ?? true;
+        this.proactivelyReported = declared.proactivelyReported ?? false;
+        this.nonControllable = declared.nonControllable;
+        this.options = declared.options;
+    }
+    get namespace() {
+        return this.descriptor.namespace;
+    }
+    /** Mappings of "open", "close", "raise", "lower" and of states, when the declaration has any. */
+    get semantics() {
+        const { semantics } = this.options;
+        const mapped = (semantics?.actionMappings?.length ?? 0) + (semantics?.stateMappings?.length ?? 0);
+        return mapped > 0 ? semantics : undefined;
+    }
+    /** The capability object for discovery, its fields in the order of the example on alexa-discovery-objects.html. */
+    toJSON() {
+        const { descriptor, semantics } = this;
+        const extras = descriptor.discovery ? descriptor.discovery(this) : {};
+        const json = {
+            type: "AlexaInterface",
+            interface: descriptor.namespace,
+            ...(this.instance ? { instance: this.instance } : {}),
+            version: descriptor.version,
+        };
+        if (extras.properties !== false) {
+            json.properties = {
+                supported: Object.keys(descriptor.properties).map((name) => ({ name })),
+                proactivelyReported: this.proactivelyReported,
+                retrievable: this.retrievable,
+            };
+            if (this.nonControllable !== undefined)
+                json.properties.nonControllable = this.nonControllable;
+        }
+        if (this.friendlyNames.length > 0)
+            json.capabilityResources = { friendlyNames: this.friendlyNames };
+        if (extras.configuration)
+            json.configuration = extras.configuration;
+        if (extras.configurations)
+            json.configurations = extras.configurations;
+        if (semantics)
+            json.semantics = semantics;
+        return { ...json, ...extras.topLevel };
+    }
+}

dist/esm/device/Device.d.ts

@@ -0,0 +1,135 @@
+import { EventEmitter } from "events";
+import type { MqttClient } from "mqtt";
+import { AlexaErrorResponse } from "../AlexaErrorResponse.js";
+import { AlexaStatusMessage } from "../AlexaStatusMessage.js";
+import type { ChangeCause } from "../AlexaStatusMessage.js";
+import { AlexaInterface } from "../compat/AlexaInterface.js";
+import { DisplayCategory } from "../compat/enums.js";
+import type { AlexaInterfaceType } from "../compat/enums.js";
+import type { DisplayCategoryName } from "../registry/catalog.js";
+import type { Directives, InterfaceDescriptor, Properties } from "../registry/types.js";
+import { Capability } from "./Capability.js";
+import type { AnyCapability, CapabilityJson, Declaration } from "./Capability.js";
+import type { EndpointFields } from "./validate.js";
+/** An endpoint as bridge.addDevice() takes it. */
+export interface EndpointDefinition {
+    /** Up to 256 letters, digits, spaces and _ - = # ; : ? @ &. The same id at every discovery. */
+    endpointId: string;
+    /** What the user calls the device: letters, digits and spaces. */
+    name: string;
+    /** The first one is the category the Alexa app shows the device under. */
+    categories: Array<DisplayCategoryName | DisplayCategory>;
+    /** Shown in the Alexa app, up to 128 characters. Default: "Alexa to Node.js bridge". */
+    description?: string;
+    /** Up to 128 characters. Default: "Alex2Node". */
+    manufacturerName?: string;
+    manufacturer?: string;
+    model?: string;
+    serialNumber?: string;
+    firmwareVersion?: string;
+    softwareVersion?: string;
+    customIdentifier?: string;
+    /** Returned with every directive to the endpoint. Up to 5000 bytes; not a place for state. */
+    cookie?: Record<string, string>;
+    /** false: the device gets no Alexa.EndpointHealth unless it declares one. */
+    endpointHealth?: boolean;
+}
+/** An endpoint object of a discovery answer (alexa-discovery-objects.html, "Endpoint object"). */
+export interface EndpointJson extends EndpointFields {
+    capabilities: CapabilityJson[];
+}
+type DeclarationArguments<O, I extends boolean> = {} extends Declaration<O, I> ? [options?: Declaration<O, I>] : [options: Declaration<O, I>];
+declare class Device extends EventEmitter {
+    private mqttClient;
+    private rootTopic;
+    name: string;
+    endpointId: string;
+    displayCategory: Array<DisplayCategory> | null;
+    description: string;
+    manufacturerName: string;
+    manufacturer: string;
+    model: string;
+    softwareVersion: string;
+    serialNumber: string;
+    firmwareVersion: string;
+    customIdentifier: string;
+    cookie?: Record<string, string>;
+    /**
+     * Discovery lists the Alexa interface on the endpoint (alexa-interface.html: "You must explicitly identify your
+     * support for the Alexa interface"). The bridge sets it from its alexaInterface option.
+     */
+    alexaInterface: boolean;
+    /**
+     * Discovery lists Alexa.EndpointHealth when the device did not declare it and is not a scene. On for a device of
+     * bridge.addDevice(), off for one of registerDevice(), which is announced as 1.x announced it.
+     */
+    endpointHealth: boolean;
+    private capabilities;
+    /** Where a failed publish from this device or a message it built is reported; Alex2MQTT sets it (1.5.2). */
+    onPublishError?: (err: Error) => void;
+    constructor(mqttClient: MqttClient, rootTopic: string, name: string, endpointId: string, displayCategory: Array<DisplayCategory> | null, description?: string, manufacturerName?: string, manufacturer?: string, model?: string);
+    /** Internal (1.5.2): Alex2MQTT.connect() re-binds every registered device to its new broker client after a disconnect(). */
+    setMqttClient(client: MqttClient): void;
+    getName(): string;
+    setName(name: string): void;
+    getEndpointId(): string;
+    setDisplayCategory(category: DisplayCategory | DisplayCategory[]): void;
+    getDisplayCategory(): Array<DisplayCategory>;
+    setDescription(description: string): void;
+    getDescription(): string;
+    getErrorMessage(correlationToken: string): AlexaErrorResponse;
+    getStatusMessage(correlationToken: string, isResponse?: boolean, isDeferred?: boolean): AlexaStatusMessage;
+    /**
+     * A proactive Alexa.ChangeReport (1.5.1): add the changed properties (the default target), optionally
+     * .unchanged() then the others, and .send() - it goes to <root>/changeReport, which Alex2MQTT forwards to the Alexa
+     * event gateway with the user's token. Alexa only accepts it for capabilities registered with proactivelyReported.
+     */
+    getChangeReport(cause?: ChangeCause): AlexaStatusMessage;
+    /**
+     * Alexa.SceneController: answer an Activate / Deactivate directive with ActivationStarted / DeactivationStarted
+     * (1.5.1). Resolves with the topic published to, or "" when the publish failed (never rejects, 1.5.2).
+     */
+    sendSceneResponse(correlationToken: string, activated: boolean, cause?: ChangeCause, sendAsync?: boolean): Promise<string>;
+    /** The capabilities the device declared, in the order it declared them. */
+    getCapabilities(): AnyCapability[];
+    setManufacturerName(name: string): void;
+    getManufacturerName(): string;
+    setManufacturer(manufacturer: string): void;
+    getManufacturer(): string;
+    setModel(model: string): void;
+    getModel(): string;
+    getSoftwareVersion(): string;
+    /**
+     * Declare an interface of the device:
+     *
+     *   lamp.add(PowerController, { proactivelyReported: true });
+     *   blinds.add(RangeController, { instance: "Blind.Lift", friendlyNames: [asset("Alexa.Setting.Opening")],
+     *     range: { min: 0, max: 100, precision: 1 } });
+     *
+     * Throws a DeclarationError that names the endpoint, the interface and the instance when Alexa would reject the
+     * capability; the device is then as it was before the call.
+     */
+    add<P extends Properties, D extends Directives, O, I extends boolean>(descriptor: InterfaceDescriptor<P, D, O, I>, ...[options]: DeclarationArguments<O, I>): Capability<P, D, O>;
+    /**
+     * Declare an interface the 1.x way, by its name: options.retrievable / proactivelyReported / instance, then the
+     * add and set methods of the capability that is returned. Throws for a name that is not an interface. Anything
+     * else Alexa would reject is not refused here: check() lists it.
+     */
+    addCapability(type: AlexaInterfaceType | string, options?: {
+        retrievable?: boolean;
+        proactivelyReported?: boolean;
+        instance?: string;
+    }): AlexaInterface;
+    /**
+     * What Alexa would reject in the device as it is declared now, one line for each: a name with punctuation, an
+     * interface declared twice. Also what a capability noted about its declaration. Empty when there is nothing.
+     * The bridge logs the lines when it answers a discovery.
+     */
+    check(): string[];
+    /** The endpoint object for discovery. */
+    getJSON(): EndpointJson;
+    private fields;
+    private view;
+    private announced;
+}
+export default Device;

dist/esm/device/Device.js

@@ -0,0 +1,268 @@
+import { EventEmitter } from "events";
+import { randomUUID } from "crypto";
+import { AlexaErrorResponse } from "../AlexaErrorResponse.js";
+import { AlexaStatusMessage } from "../AlexaStatusMessage.js";
+import { AlexaInterface } from "../compat/AlexaInterface.js";
+import { DisplayCategory } from "../compat/enums.js";
+import { Alexa } from "../registry/interfaces/Alexa.js";
+import { EndpointHealth } from "../registry/interfaces/EndpointHealth.js";
+import { SchemaError } from "../registry/schema.js";
+import { DeclarationError } from "../registry/types.js";
+import { Capability, commonOptions } from "./Capability.js";
+import { checkCapability, checkCapabilityCount, checkEndpoint } from "./validate.js";
+class Device extends EventEmitter {
+    constructor(mqttClient, rootTopic, name, endpointId, displayCategory, description = "Alexa to Node.js bridge", manufacturerName = "Alex2Node", manufacturer = "Alex2Node", model = "Alex2Node_v1.0.0") {
+        super();
+        this.mqttClient = mqttClient;
+        this.rootTopic = rootTopic;
+        this.name = name;
+        this.endpointId = endpointId;
+        this.displayCategory = displayCategory;
+        this.description = description;
+        this.manufacturerName = manufacturerName;
+        this.manufacturer = manufacturer;
+        this.model = model;
+        this.softwareVersion = "1.0.0";
+        this.serialNumber = "Alex2Node";
+        this.firmwareVersion = "1.0.0";
+        this.customIdentifier = "Alex2Node";
+        /**
+         * Discovery lists the Alexa interface on the endpoint (alexa-interface.html: "You must explicitly identify your
+         * support for the Alexa interface"). The bridge sets it from its alexaInterface option.
+         */
+        this.alexaInterface = true;
+        /**
+         * Discovery lists Alexa.EndpointHealth when the device did not declare it and is not a scene. On for a device of
+         * bridge.addDevice(), off for one of registerDevice(), which is announced as 1.x announced it.
+         */
+        this.endpointHealth = false;
+        this.capabilities = [];
+    }
+    /** Internal (1.5.2): Alex2MQTT.connect() re-binds every registered device to its new broker client after a disconnect(). */
+    setMqttClient(client) {
+        this.mqttClient = client;
+    }
+    getName() {
+        return this.name;
+    }
+    setName(name) {
+        this.name = name;
+    }
+    getEndpointId() {
+        return this.endpointId;
+    }
+    setDisplayCategory(category) {
+        this.displayCategory = Array.isArray(category) ? category : [category];
+    }
+    getDisplayCategory() {
+        return this.displayCategory || [DisplayCategory.LIGHT];
+    }
+    setDescription(description) {
+        this.description = description;
+    }
+    getDescription() {
+        return this.description;
+    }
+    getErrorMessage(correlationToken) {
+        const msg = new AlexaErrorResponse(correlationToken, this.rootTopic, this.endpointId, this.mqttClient);
+        msg.onPublishError = this.onPublishError;
+        return msg;
+    }
+    getStatusMessage(correlationToken, isResponse = false, isDeferred = false) {
+        const msg = new AlexaStatusMessage(correlationToken, this.rootTopic, this.endpointId, this.mqttClient, isResponse, isDeferred);
+        msg.onPublishError = this.onPublishError;
+        return msg;
+    }
+    /**
+     * A proactive Alexa.ChangeReport (1.5.1): add the changed properties (the default target), optionally
+     * .unchanged() then the others, and .send() - it goes to <root>/changeReport, which Alex2MQTT forwards to the Alexa
+     * event gateway with the user's token. Alexa only accepts it for capabilities registered with proactivelyReported.
+     */
+    getChangeReport(cause = "PHYSICAL_INTERACTION") {
+        const msg = new AlexaStatusMessage("", this.rootTopic, this.endpointId, this.mqttClient, false, false, cause);
+        msg.onPublishError = this.onPublishError;
+        return msg;
+    }
+    /**
+     * Alexa.SceneController: answer an Activate / Deactivate directive with ActivationStarted / DeactivationStarted
+     * (1.5.1). Resolves with the topic published to, or "" when the publish failed (never rejects, 1.5.2).
+     */
+    sendSceneResponse(correlationToken, activated, cause = "VOICE_INTERACTION", sendAsync = false) {
+        const payload = {
+            context: {},
+            event: {
+                header: { namespace: "Alexa.SceneController", name: activated ? "ActivationStarted" : "DeactivationStarted", messageId: randomUUID(), correlationToken, payloadVersion: "3" },
+                endpoint: { endpointId: this.endpointId },
+                payload: { cause: { type: cause }, timestamp: new Date().toISOString() },
+            },
+        };
+        const topic = `${this.rootTopic}/${this.endpointId}/${sendAsync ? "deferredResponse" : "alexaResponce"}`;
+        return new Promise((resolve) => {
+            this.mqttClient.publish(topic, JSON.stringify(payload), (err) => {
+                if (!err)
+                    return resolve(topic);
+                if (this.onPublishError)
+                    this.onPublishError(err); // -> the bridge's "error" event (when somebody listens)
+                resolve(""); // 1.5.1 rejected here, and an un-caught send() then killed the host on any broker hiccup
+            });
+        });
+    }
+    /** The capabilities the device declared, in the order it declared them. */
+    getCapabilities() {
+        return this.capabilities.slice();
+    }
+    setManufacturerName(name) {
+        this.manufacturerName = name;
+    }
+    getManufacturerName() {
+        return this.manufacturerName;
+    }
+    setManufacturer(manufacturer) {
+        this.manufacturer = manufacturer;
+    }
+    getManufacturer() {
+        return this.manufacturer;
+    }
+    setModel(model) {
+        this.model = model;
+    }
+    getModel() {
+        return this.model;
+    }
+    getSoftwareVersion() {
+        return this.softwareVersion;
+    }
+    /**
+     * Declare an interface of the device:
+     *
+     *   lamp.add(PowerController, { proactivelyReported: true });
+     *   blinds.add(RangeController, { instance: "Blind.Lift", friendlyNames: [asset("Alexa.Setting.Opening")],
+     *     range: { min: 0, max: 100, precision: 1 } });
+     *
+     * Throws a DeclarationError that names the endpoint, the interface and the instance when Alexa would reject the
+     * capability; the device is then as it was before the call.
+     */
+    add(descriptor, ...[options]) {
+        const where = { endpointId: this.endpointId, namespace: descriptor.namespace, instance: "" };
+        if (options !== undefined && (typeof options !== "object" || options === null)) {
+            throw new DeclarationError(where, "the options of a declaration are an object");
+        }
+        try {
+            const { instance, friendlyNames, retrievable, proactivelyReported, nonControllable, ...given } = commonOptions.parse(options ?? {});
+            where.instance = instance ?? "";
+            const common = { instance, friendlyNames: friendlyNames, retrievable, proactivelyReported, nonControllable };
+            const capability = new Capability(descriptor, { ...common, options: interfaceOptions(descriptor, given) });
+            capability.endpointId = this.endpointId;
+            checkCapability(capability, descriptor, this.view(this.capabilities));
+            checkCapabilityCount(this.endpointId, this.announced([...this.capabilities, capability]).length);
+            this.capabilities.push(capability);
+            return capability;
+        }
+        catch (err) {
+            throw err instanceof SchemaError ? new DeclarationError(where, err.message) : err;
+        }
+    }
+    /**
+     * Declare an interface the 1.x way, by its name: options.retrievable / proactivelyReported / instance, then the
+     * add and set methods of the capability that is returned. Throws for a name that is not an interface. Anything
+     * else Alexa would reject is not refused here: check() lists it.
+     */
+    addCapability(type, options = {}) {
+        let capability;
+        try {
+            capability = new AlexaInterface(type, options.retrievable ?? true, options.proactivelyReported ?? false, options.instance ?? "");
+        }
+        catch (err) {
+            throw err instanceof DeclarationError ? new DeclarationError({ endpointId: this.endpointId }, err.problem) : err;
+        }
+        capability.endpointId = this.endpointId;
+        this.capabilities.push(capability);
+        return capability;
+    }
+    /**
+     * What Alexa would reject in the device as it is declared now, one line for each: a name with punctuation, an
+     * interface declared twice. Also what a capability noted about its declaration. Empty when there is nothing.
+     * The bridge logs the lines when it answers a discovery.
+     */
+    check() {
+        const lines = [];
+        const attempt = (rule) => {
+            try {
+                rule();
+            }
+            catch (err) {
+                if (!(err instanceof DeclarationError))
+                    throw err;
+                lines.push(err.message);
+            }
+        };
+        attempt(() => checkEndpoint(this.fields()));
+        this.capabilities.forEach((capability, i) => {
+            capability.endpointId = this.endpointId;
+            attempt(() => checkCapability(capability, capability.descriptor, this.view(this.capabilities.slice(0, i))));
+            const notes = [...capability.notes];
+            const { tier, properties } = capability.descriptor;
+            if (tier === 3 && Object.keys(properties).length === 0 && capability.toJSON().properties) {
+                notes.push("no property list known, discovery lists it with no supported properties");
+            }
+            for (const note of notes)
+                lines.push(new DeclarationError(capability, note).message);
+        });
+        attempt(() => checkCapabilityCount(this.endpointId, this.announced(this.capabilities).length));
+        return lines;
+    }
+    /** The endpoint object for discovery. */
+    getJSON() {
+        return { ...this.fields(), capabilities: this.announced(this.capabilities).map((capability) => capability.toJSON()) };
+    }
+    fields() {
+        return {
+            endpointId: this.endpointId,
+            friendlyName: this.name,
+            description: this.description,
+            manufacturerName: this.manufacturerName,
+            displayCategories: this.getDisplayCategory(),
+            additionalAttributes: {
+                manufacturer: this.manufacturer,
+                model: this.model,
+                serialNumber: this.serialNumber,
+                firmwareVersion: this.firmwareVersion,
+                softwareVersion: this.softwareVersion,
+                customIdentifier: this.customIdentifier,
+            },
+            ...(this.cookie ? { cookie: this.cookie } : {}),
+        };
+    }
+    // The endpoint as the rules of a capability see it
+    view(declaredBefore) {
+        return {
+            endpointId: this.endpointId,
+            friendlyName: this.name,
+            description: this.description,
+            displayCategories: this.getDisplayCategory(),
+            capabilities: declaredBefore,
+        };
+    }
+    // What discovery lists: the declared capabilities, then the ones the library adds
+    announced(declared) {
+        const has = (namespace) => declared.some((capability) => capability.namespace === namespace);
+        const added = [];
+        // alexa-scenecontroller.html, "Discovery": a scene is not a physical device and has no Alexa.EndpointHealth
+        if (this.endpointHealth && !has(EndpointHealth.namespace) && !has("Alexa.SceneController")) {
+            added.push(new Capability(EndpointHealth, { options: {} }));
+        }
+        if (this.alexaInterface && !has(Alexa.namespace))
+            added.push(new Capability(Alexa, { options: {} }));
+        return [...declared, ...added];
+    }
+}
+// The options of the interface itself, checked by the schema of its descriptor
+function interfaceOptions(descriptor, given) {
+    if (descriptor.options)
+        return descriptor.options.parse(given);
+    const [unknown] = Object.keys(given);
+    if (unknown !== undefined)
+        throw new SchemaError(unknown, "not an option of the interface");
+    return {};
+}
+export default Device;

dist/esm/device/validate.d.ts

@@ -0,0 +1,20 @@
+import type { AnyDescriptor, Declared, EndpointView } from "../registry/types.js";
+/** An endpoint as discovery sends it, without its capabilities. */
+export interface EndpointFields {
+    endpointId: string;
+    friendlyName: string;
+    description: string;
+    manufacturerName: string;
+    displayCategories: readonly string[];
+    additionalAttributes: Readonly<Record<string, string>>;
+    cookie?: Readonly<Record<string, string>>;
+}
+/** Throws the first rule of the Endpoint object that the fields break. */
+export declare function checkEndpoint(endpoint: EndpointFields): void;
+/** alexa-discovery.html, "Interface limits". count includes the capabilities the library adds. */
+export declare function checkCapabilityCount(endpointId: string, count: number): void;
+/**
+ * Throws the first rule that a capability breaks on its endpoint. endpoint.capabilities are the ones declared
+ * before it. A stub is checked for being declared twice and for nothing else: the library does not know its rules.
+ */
+export declare function checkCapability(capability: Declared<unknown>, descriptor: AnyDescriptor, endpoint: EndpointView): void;

dist/esm/device/validate.js

@@ -0,0 +1,123 @@
+// What Alexa rejects at discovery, checked where a device is declared. Alexa gives no reason when it drops an
+// endpoint: the user hears "no new devices found". Each rule names the page it is from.
+import { DISPLAY_CATEGORIES, LIMITS } from "../registry/catalog.js";
+import { labels, shownAs } from "../registry/resources.js";
+import { SchemaError } from "../registry/schema.js";
+import { DeclarationError } from "../registry/types.js";
+// alexa-discovery-objects.html, "Endpoint object details": "letters, numbers, spaces, and the following special
+// characters: _ - = # ; : ? @ &"
+const ENDPOINT_ID = /^[A-Za-z0-9 _\-=#;:?@&]+$/;
+// Same table: "alphanumeric characters and spaces". Letters of any script: Alexa speaks Hindi and Japanese too.
+const FRIENDLY_NAME = /^[\p{L}\p{M}\p{N} ]+$/u;
+const isText = (value) => typeof value === "string" && value.length > 0;
+/** Throws the first rule of the Endpoint object that the fields break. */
+export function checkEndpoint(endpoint) {
+    const where = { endpointId: isText(endpoint.endpointId) ? endpoint.endpointId : undefined };
+    function refuse(problem) {
+        throw new DeclarationError(where, problem);
+    }
+    const { endpointId, friendlyName, description, manufacturerName, displayCategories, additionalAttributes, cookie } = endpoint;
+    if (!isText(endpointId))
+        refuse("an endpoint needs an endpointId");
+    if (endpointId.length > LIMITS.endpointIdLength || !ENDPOINT_ID.test(endpointId)) {
+        refuse(`the endpointId takes up to ${LIMITS.endpointIdLength} letters, digits, spaces and _ - = # ; : ? @ &`);
+    }
+    if (!isText(friendlyName))
+        refuse("an endpoint needs a name");
+    if (friendlyName.length > LIMITS.friendlyNameLength || !FRIENDLY_NAME.test(friendlyName)) {
+        refuse(`the name ${JSON.stringify(friendlyName)} takes up to ${LIMITS.friendlyNameLength} letters, digits and spaces, no punctuation`);
+    }
+    if (!isText(manufacturerName) || manufacturerName.length > LIMITS.manufacturerNameLength) {
+        refuse(`the manufacturerName takes 1 to ${LIMITS.manufacturerNameLength} characters`);
+    }
+    if (!isText(description) || description.length > LIMITS.descriptionLength) {
+        refuse(`the description takes 1 to ${LIMITS.descriptionLength} characters`);
+    }
+    if (!Array.isArray(displayCategories) || displayCategories.length === 0)
+        refuse("an endpoint needs a display category");
+    const known = DISPLAY_CATEGORIES;
+    for (const category of displayCategories) {
+        if (!known.includes(category))
+            refuse(`${JSON.stringify(category)} is not a display category`);
+    }
+    for (const [name, value] of Object.entries(additionalAttributes)) {
+        if (typeof value !== "string" || value.length > LIMITS.additionalAttributeLength) {
+            refuse(`${name} takes up to ${LIMITS.additionalAttributeLength} characters`);
+        }
+    }
+    if (cookie !== undefined) {
+        const bytes = Buffer.byteLength(JSON.stringify(cookie) ?? "");
+        if (bytes > LIMITS.cookieBytes)
+            refuse(`the cookie is ${bytes} bytes, ${LIMITS.cookieBytes} is the most`);
+    }
+}
+/** alexa-discovery.html, "Interface limits". count includes the capabilities the library adds. */
+export function checkCapabilityCount(endpointId, count) {
+    if (count > LIMITS.capabilitiesPerEndpoint) {
+        throw new DeclarationError({ endpointId }, `${count} capabilities, an endpoint takes ${LIMITS.capabilitiesPerEndpoint}`);
+    }
+}
+// Two names are the same name when the app would show the same: the asset, or the text in one locale.
+function nameKey(name) {
+    return name["@type"] === "asset" ? `asset ${name.value.assetId}` : `text ${name.value.locale} ${name.value.text.toLowerCase()}`;
+}
+function phrases(capability) {
+    const { semantics } = capability.options;
+    return (semantics?.actionMappings ?? []).flatMap((mapping) => mapping.actions);
+}
+/**
+ * Throws the first rule that a capability breaks on its endpoint. endpoint.capabilities are the ones declared
+ * before it. A stub is checked for being declared twice and for nothing else: the library does not know its rules.
+ */
+export function checkCapability(capability, descriptor, endpoint) {
+    function refuse(problem) {
+        throw new DeclarationError(capability, problem);
+    }
+    const { namespace, instance, friendlyNames } = capability;
+    // generic-controllers.html, "Multiple instances": one capability of an interface, or one per instance name
+    if (endpoint.capabilities.some((other) => other.namespace === namespace && other.instance === instance)) {
+        refuse(instance ? "the instance is declared twice" : "the interface is declared twice");
+    }
+    if (descriptor.tier === 3)
+        return;
+    if (descriptor.instanced) {
+        // alexa-rangecontroller.html, "Capabilities array": instance and capabilityResources are required
+        if (!isText(instance))
+            refuse("needs an instance name, like Blind.Lift");
+        try {
+            labels.parse(friendlyNames, "friendlyNames");
+        }
+        catch (err) {
+            refuse(err instanceof SchemaError && err.path === "friendlyNames" ? "needs a friendly name, from text() or asset()" : err.message);
+        }
+        // resources-and-assets.html, "CapabilityResources": "The first friendly name in the array must be unique for
+        // the endpoint."
+        const first = nameKey(friendlyNames[0]);
+        const taken = endpoint.capabilities.find((other) => other.friendlyNames.length > 0 && nameKey(other.friendlyNames[0]) === first);
+        if (taken) {
+            refuse(`the first friendly name, ${shownAs(friendlyNames[0])}, is the first of ${taken.namespace} ${JSON.stringify(taken.instance)} too`);
+        }
+    }
+    else {
+        if (instance)
+            refuse("takes no instance name: an endpoint has the interface once");
+        if (friendlyNames.length > 0)
+            refuse("takes no friendly names");
+    }
+    // generic-controllers.html, "Semantics for user utterances": "Each semantic phrase must be unique across all
+    // controller instances for each endpoint"
+    const used = new Map();
+    for (const other of endpoint.capabilities)
+        for (const phrase of phrases(other))
+            used.set(phrase, other);
+    for (const phrase of phrases(capability)) {
+        const owner = used.get(phrase);
+        if (owner) {
+            const place = owner === capability ? "twice" : `here and on ${owner.namespace} ${JSON.stringify(owner.instance)}`;
+            refuse(`${phrase} is mapped ${place}, an endpoint maps a phrase once`);
+        }
+        used.set(phrase, capability);
+    }
+    if (descriptor.validate)
+        descriptor.validate(capability, endpoint);
+}

dist/esm/index.d.ts

@@ -1,13 +1,19 @@
 export { default as Alex2MQTT, DEFAULT_HOST } from "./Alex2Node.js";
 export type { Alex2MQTTOptions } from "./Alex2Node.js";
-export { default as Device } from "./Device.js";
-export { AlexaInterface, AlexaInterfaceType } from "./AlexaInterface.js";
-export type { SupportedMode } from "./AlexaInterface.js";
-export { ActionMapping, AlexaActions } from "./ActionMapping.js";
-export { DisplayCategory } from "./DisplayCategory.js";
-export { AlexaStatusMessage, PowerController, EndpointHealth, TemperatureSensorScale, ThermostatMode } from "./AlexaStatusMessage.js";
+export { default as Device } from "./device/Device.js";
+export type { EndpointDefinition, EndpointJson } from "./device/Device.js";
+export { Capability } from "./device/Capability.js";
+export type { CapabilityJson, CommonOptions, Declaration } from "./device/Capability.js";
+export { registry, DeclarationError, SchemaError } from "./registry/index.js";
+export { Alexa, BrightnessController, TemperatureSensor } from "./registry/index.js";
+export { PowerController, EndpointHealth } from "./compat/enums.js";
+export { asset, text } from "./registry/resources.js";
+export { ASSETS as Assets, UNITS_OF_MEASURE as Units, ACTIONS as Actions, STATES as States, DISPLAY_CATEGORIES as DisplayCategories, } from "./registry/index.js";
+export type { ActionId, AssetId, DisplayCategoryName, StateId, UnitOfMeasure, ActionsToDirective, AnyDescriptor, CapabilityExtras, Declared, DirectiveDescriptor, EndpointView, EventDescriptor, InterfaceDescriptor, Label, PropertyDescriptor, Semantics, StatesToRange, StatesToValue, Infer, Schema, Temperature, TimeInterval, } from "./registry/index.js";
+export { AlexaInterface } from "./compat/AlexaInterface.js";
+export type { SupportedMode } from "./compat/AlexaInterface.js";
+export { ActionMapping } from "./compat/ActionMapping.js";
+export { AlexaActions, AlexaInterfaceType, DisplayCategory, PowerState } from "./compat/enums.js";
+export { AlexaStatusMessage, TemperatureSensorScale, ThermostatMode } from "./AlexaStatusMessage.js";
 export type { ChangeCause } from "./AlexaStatusMessage.js";
 export { AlexaErrorType, AlexaErrorResponse } from "./AlexaErrorResponse.js";
-export { registry, DeclarationError, SchemaError } from "./registry/index.js";
-export { ASSETS as Assets, UNITS_OF_MEASURE as Units, ACTIONS as Actions, STATES as States, DISPLAY_CATEGORIES as DisplayCategories, } from "./registry/index.js";
-export type { ActionId, AssetId, DisplayCategoryName, StateId, UnitOfMeasure, AnyDescriptor, CapabilityExtras, Declared, DirectiveDescriptor, EndpointView, EventDescriptor, InterfaceDescriptor, Label, PropertyDescriptor, Infer, Schema, Temperature, TimeInterval, } from "./registry/index.js";

dist/esm/index.js

@@ -1,11 +1,17 @@
 // Relative specifiers carry ".js": Node's ES module loader resolves no extension, and TypeScript maps it back to the .ts.
 export { default as Alex2MQTT, DEFAULT_HOST } from "./Alex2Node.js";
-export { default as Device } from "./Device.js";
-export { AlexaInterface, AlexaInterfaceType } from "./AlexaInterface.js";
-export { ActionMapping, AlexaActions } from "./ActionMapping.js";
-export { DisplayCategory } from "./DisplayCategory.js";
-export { AlexaStatusMessage, PowerController, EndpointHealth, TemperatureSensorScale, ThermostatMode } from "./AlexaStatusMessage.js";
-export { AlexaErrorType, AlexaErrorResponse } from "./AlexaErrorResponse.js";
-// The interface registry and the vocabularies of the Smart Home API
+export { default as Device } from "./device/Device.js";
+export { Capability } from "./device/Capability.js";
+// The interfaces, for device.add(), and the registry that holds them by name
 export { registry, DeclarationError, SchemaError } from "./registry/index.js";
+export { Alexa, BrightnessController, TemperatureSensor } from "./registry/index.js";
+export { PowerController, EndpointHealth } from "./compat/enums.js";
+export { asset, text } from "./registry/resources.js";
+// The vocabularies of the Smart Home API
 export { ASSETS as Assets, UNITS_OF_MEASURE as Units, ACTIONS as Actions, STATES as States, DISPLAY_CATEGORIES as DisplayCategories, } from "./registry/index.js";
+// 1.x
+export { AlexaInterface } from "./compat/AlexaInterface.js";
+export { ActionMapping } from "./compat/ActionMapping.js";
+export { AlexaActions, AlexaInterfaceType, DisplayCategory, PowerState } from "./compat/enums.js";
+export { AlexaStatusMessage, TemperatureSensorScale, ThermostatMode } from "./AlexaStatusMessage.js";
+export { AlexaErrorType, AlexaErrorResponse } from "./AlexaErrorResponse.js";

dist/esm/registry/index.d.ts

@@ -14,7 +14,7 @@ export declare const registry: {
 };
 export { Alexa, BrightnessController, EndpointHealth, PowerController, TemperatureSensor };
 export { DeclarationError, defineInterface } from "./types.js";
-export type { AnyDescriptor, CapabilityExtras, Declared, DirectiveDescriptor, EndpointView, EventDescriptor, InterfaceDescriptor, Label, PropertyDescriptor, } from "./types.js";
+export type { ActionsToDirective, AnyDescriptor, CapabilityExtras, Declared, DirectiveDescriptor, EndpointView, EventDescriptor, InterfaceDescriptor, Label, PropertyDescriptor, Semantics, StatesToRange, StatesToValue, } from "./types.js";
 export { s, SchemaError } from "./schema.js";
 export type { Infer, Schema, Temperature, TimeInterval } from "./schema.js";
 export * from "./catalog.js";

dist/esm/registry/interfaces/stubs.js

@@ -77,6 +77,20 @@ const TABLE = [
     ["Alexa.VideoRecorder", "1", [], "alexa-videorecorder.html"],
     ["Alexa.WakeOnLANController", "1", [], "alexa-wakeonlancontroller.html"],
 ];
+// What 1.5.2 added to the capability object of three of them
+const EXTRAS = {
+    // No properties object; supportsDeactivation and proactivelyReported on the capability itself
+    "Alexa.SceneController": ({ proactivelyReported }) => ({
+        properties: false,
+        topLevel: { supportsDeactivation: true, proactivelyReported },
+    }),
+    "Alexa.ThermostatController": () => ({
+        configuration: { supportedModes: ["HEAT", "COOL", "AUTO", "OFF"], supportsScheduling: false },
+    }),
+    "Alexa.ModeController": ({ options }) => (options.supportedModes?.length > 0
+        ? { configuration: { ordered: true, supportedModes: options.supportedModes } }
+        : {}),
+};
 function kindOf(namespace) {
     if (namespace.endsWith("Sensor"))
         return "sensor";
@@ -94,6 +108,7 @@ function stub([namespace, version, properties, page]) {
         instanced: false,
         properties: Object.fromEntries(properties.map((name) => [name, { name, value: s.unknown() }])),
         directives: {},
+        discovery: EXTRAS[namespace],
     };
 }
 export const STUBS = TABLE.map(stub);

dist/esm/registry/resources.d.ts

@@ -0,0 +1,13 @@
+import type { AssetId } from "./catalog.js";
+import type { Schema } from "./schema.js";
+import type { Label } from "./types.js";
+/** A friendly name as text, in one locale. */
+export declare function text(name: string, locale?: string): Label;
+/** A friendly name from the global Alexa catalog: one id, several names, every language Alexa speaks. */
+export declare function asset(assetId: AssetId): Label;
+/** One friendly name. An asset has to be in the catalog, a text must not be a word Alexa keeps for itself. */
+export declare const label: Schema<Label>;
+/** The friendly names of an instance, a mode or a preset: at least one. */
+export declare const labels: Schema<Label[]>;
+/** What the user is shown for a friendly name: the text, or the id of the asset. */
+export declare function shownAs(name: Label): string;

dist/esm/registry/resources.js

@@ -0,0 +1,39 @@
+// Friendly names: what the user calls an instance, a mode or a preset (resources-and-assets.html).
+import { ASSETS, RESERVED_WORDS } from "./catalog.js";
+import { at, s, SchemaError } from "./schema.js";
+/** A friendly name as text, in one locale. */
+export function text(name, locale = "en-US") {
+    return { "@type": "text", value: { text: name, locale } };
+}
+/** A friendly name from the global Alexa catalog: one id, several names, every language Alexa speaks. */
+export function asset(assetId) {
+    return { "@type": "asset", value: { assetId } };
+}
+const LOCALE = /^[a-z]{2}-[A-Z]{2}$/;
+const textValue = s.object({
+    text: s.string({ min: 1 }),
+    locale: s.string({ pattern: LOCALE, expects: "a locale like en-US" }),
+});
+const assetValue = s.object({ assetId: s.oneOf(ASSETS, "an id of the global Alexa catalog, like Alexa.Setting.Opening") });
+const typed = s.object({ "@type": s.enum("text", "asset"), value: s.unknown() });
+const reserved = RESERVED_WORDS;
+/** One friendly name. An asset has to be in the catalog, a text must not be a word Alexa keeps for itself. */
+export const label = {
+    expects: "a friendly name, from text() or asset()",
+    parse(input, path = "") {
+        const { "@type": type, value } = typed.parse(input, path);
+        if (type === "asset")
+            return { "@type": type, value: assetValue.parse(value, at(path, "value")) };
+        const named = textValue.parse(value, at(path, "value"));
+        if (reserved.includes(named.text.trim().toLowerCase())) {
+            throw new SchemaError(at(path, "value.text"), `${JSON.stringify(named.text)} is a reserved word, not to be used as a friendly name`);
+        }
+        return { "@type": type, value: named };
+    },
+};
+/** The friendly names of an instance, a mode or a preset: at least one. */
+export const labels = s.array(label, { min: 1 });
+/** What the user is shown for a friendly name: the text, or the id of the asset. */
+export function shownAs(name) {
+    return name["@type"] === "text" ? name.value.text : name.value.assetId;
+}

dist/esm/registry/schema.d.ts

@@ -44,6 +44,10 @@ export interface TimeInterval {
     end?: string;
     duration?: string;
 }
+/** The error of a value that is not what a schema expects. */
+export declare function mismatch(path: string, expects: string, input: unknown): SchemaError;
+/** The path of a key of the object at path. */
+export declare const at: (path: string, key: string) => string;
 declare function number(rules?: NumberRules): Schema<number>;
 declare function string(rules?: {
     min?: number;
@@ -54,6 +58,8 @@ declare function string(rules?: {
 declare function boolean(): Schema<boolean>;
 declare function literal<V extends string | number | boolean | null>(value: V): Schema<V>;
 declare function enumeration<V extends readonly string[]>(...values: V): EnumSchema<V[number]>;
+/** One of a list too long to print in an error message: expects says what the list is. */
+declare function oneOf<V extends string>(values: readonly V[], expects: string): EnumSchema<V>;
 declare function unknown(): Schema<unknown>;
 declare function optional<T>(inner: Schema<T>): OptionalSchema<T>;
 declare function nullable<T>(inner: Schema<T>): Schema<T | null>;
@@ -78,6 +84,7 @@ export declare const s: {
     boolean: typeof boolean;
     literal: typeof literal;
     enum: typeof enumeration;
+    oneOf: typeof oneOf;
     unknown: typeof unknown;
     optional: typeof optional;
     nullable: typeof nullable;

dist/esm/registry/schema.js

@@ -19,10 +19,12 @@ function shown(input) {
     const text = JSON.stringify(input) ?? String(input);
     return text.length > 60 ? `${text.slice(0, 57)}...` : text;
 }
-function mismatch(path, expects, input) {
+/** The error of a value that is not what a schema expects. */
+export function mismatch(path, expects, input) {
     return new SchemaError(path, `expected ${expects}, got ${shown(input)}`);
 }
-const at = (path, key) => (path ? `${path}.${key}` : key);
+/** The path of a key of the object at path. */
+export const at = (path, key) => (path ? `${path}.${key}` : key);
 function isRecord(input) {
     return typeof input === "object" && input !== null && !Array.isArray(input);
 }
@@ -65,7 +67,11 @@ function literal(value) {
     return schema(JSON.stringify(value), (input) => input === value);
 }
 function enumeration(...values) {
-    return { ...schema(values.join(" | "), (input) => values.includes(input)), values };
+    return oneOf(values, values.join(" | "));
+}
+/** One of a list too long to print in an error message: expects says what the list is. */
+function oneOf(values, expects) {
+    return { ...schema(expects, (input) => values.includes(input)), values };
 }
 function unknown() {
     return schema("any value", () => true);
@@ -174,6 +180,7 @@ export const s = {
     boolean,
     literal,
     enum: enumeration,
+    oneOf,
     unknown,
     optional,
     nullable,

dist/esm/registry/types.d.ts

@@ -15,6 +15,35 @@ export type Label = {
         assetId: string;
     };
 };
+/** Phrases ("open", "lower") mapped to one directive (alexa-discovery-objects.html, "ActionMappings object"). */
+export interface ActionsToDirective {
+    "@type": "ActionsToDirective";
+    actions: string[];
+    directive: {
+        name: string;
+        payload?: Record<string, unknown>;
+    };
+}
+/** States ("open", "closed") mapped to a value of the property (same page, "StateMappings object"). */
+export interface StatesToValue {
+    "@type": "StatesToValue";
+    states: string[];
+    value: unknown;
+}
+/** States mapped to a range of values of the property. */
+export interface StatesToRange {
+    "@type": "StatesToRange";
+    states: string[];
+    range: {
+        minimumValue: number;
+        maximumValue: number;
+    };
+}
+/** The semantics object of a generic controller: at least one of the two lists. */
+export interface Semantics {
+    actionMappings?: ActionsToDirective[];
+    stateMappings?: Array<StatesToValue | StatesToRange>;
+}
 export interface PropertyDescriptor<V> {
     name: string;
     value: Schema<V>;
@@ -49,7 +78,7 @@ export interface CapabilityExtras {
     properties?: false;
 }
 /** A capability as declared on an endpoint: what discovery() and validate() of its descriptor are given. */
-export interface Declared<O = Record<string, unknown>> {
+export interface Declared<O = unknown> {
     readonly endpointId: string;
     readonly namespace: string;
     /** "" when the interface is declared without an instance. */
@@ -67,7 +96,7 @@ export interface EndpointView {
     readonly friendlyName: string;
     readonly description: string;
     readonly displayCategories: readonly string[];
-    /** The other capabilities of the endpoint. */
+    /** The capabilities declared on the endpoint before this one. */
     readonly capabilities: readonly Declared[];
 }
 export type Properties = Record<string, PropertyDescriptor<any>>;

dist/types/ActionMapping.d.ts

@@ -1,20 +0,0 @@
-export declare enum AlexaActions {
-    Open = "Alexa.Actions.Open",
-    Close = "Alexa.Actions.Close",
-    Raise = "Alexa.Actions.Raise",
-    Lower = "Alexa.Actions.Lower",
-    SetEcoOn = "Alexa.Actions.SetEcoOn",
-    SetEcoOff = "Alexa.Actions.SetEcoOff"
-}
-interface Directive {
-    name: string;
-    payload?: string;
-}
-export declare class ActionMapping {
-    type: string;
-    actions: AlexaActions[];
-    directive: Directive;
-    constructor(actions: AlexaActions[], directiveName: string, directivePayload?: string);
-    toJSON(): object;
-}
-export {};

dist/types/Alex2Node.d.ts

@@ -1,7 +1,8 @@
 import type { IClientOptions } from "mqtt";
-import Device from "./Device.js";
+import Device from "./device/Device.js";
+import type { EndpointDefinition } from "./device/Device.js";
 import { EventEmitter } from "events";
-import { DisplayCategory } from "./DisplayCategory.js";
+import { DisplayCategory } from "./compat/enums.js";
 /** Optional settings for the bridge (1.5.1). Everything has the 1.4.0 behaviour as its default. */
 export interface Alex2MQTTOptions {
     /** The broker URL. Default: the public Alex2MQTT broker, mqtt://Alex2MQTT.stormysdream.club:1883. */
@@ -10,6 +11,11 @@ export interface Alex2MQTTOptions {
     mqtt?: IClientOptions;
     /** Where log lines go. Default: console (only when debugLogging is on). */
     log?: (message: string, detail?: unknown) => void;
+    /**
+     * false: discovery does not list the Alexa interface on the endpoints. Default: every endpoint ends with
+     * { type: "AlexaInterface", interface: "Alexa", version: "3" }, which Amazon requires and 1.x left out.
+     */
+    alexaInterface?: boolean;
 }
 export declare const DEFAULT_HOST = "mqtt://Alex2MQTT.stormysdream.club:1883";
 /**
@@ -35,6 +41,7 @@ declare class Alex2MQTT extends EventEmitter {
     private devices;
     private MqttHost;
     private options;
+    private logged;
     /** true while the broker connection is up. */
     connected: boolean;
     /** ISO time of the last discovery request answered, null before the first. */
@@ -44,9 +51,22 @@ declare class Alex2MQTT extends EventEmitter {
     /** Emit "error" only when somebody listens: an unhandled "error" event would crash the host process. */
     private fail;
     connect(): void;
+    private describeDevices;
     /** Close the broker connection (resolves once closed). The devices stay registered; connect() again reuses them. */
     disconnect(): Promise<void>;
-    registerDevice(name: string, endpointId: string, displayCategory: DisplayCategory | DisplayCategory[] | null): Device;
+    /**
+     * Declare a device:
+     *
+     *   const blinds = bridge.addDevice({ endpointId: "bedroom-blinds", name: "Bedroom Blinds",
+     *     categories: ["INTERIOR_BLIND"], manufacturerName: "Acme", description: "Roller blind by Acme" });
+     *
+     * Throws a DeclarationError when Alexa would reject the endpoint (an endpointId with a slash, a name with
+     * punctuation) or when the endpointId is registered already. Discovery lists Alexa.EndpointHealth for the device
+     * unless endpointHealth is false.
+     */
+    addDevice(definition: EndpointDefinition): Device;
+    registerDevice(name: string, endpointId: string, displayCategory?: DisplayCategory | DisplayCategory[] | null): Device;
+    private register;
     /** Forget a device (its listeners with it). Returns false when there was none. */
     unregisterDevice(endpointId: string): boolean;
     /** Forget every device. */

dist/types/AlexaInterface.d.ts

@@ -1,109 +0,0 @@
-import type { ActionMapping } from "./ActionMapping.js";
-export declare enum AlexaInterfaceType {
-    APPLICATION_STATE_REPORTER = "Alexa.ApplicationStateReporter",
-    AUDIO_PLAY_QUEUE = "Alexa.Audio.PlayQueue",
-    AUTHORIZATION_CONTROLLER = "Alexa.AuthorizationController",
-    AUTOMATION_MANAGEMENT = "Alexa.AutomationManagement",
-    AUTOMOTIVE_VEHICLE_DATA = "Alexa.Automotive.VehicleData",
-    BRIGHTNESS_CONTROLLER = "Alexa.BrightnessController",
-    CAMERA_LIVE_VIEW_CONTROLLER = "Alexa.Camera.LiveViewController",
-    CAMERA_STREAM_CONTROLLER = "Alexa.CameraStreamController",
-    CHANNEL_CONTROLLER = "Alexa.ChannelController",
-    COLOR_CONTROLLER = "Alexa.ColorController",
-    COLOR_TEMPERATURE_CONTROLLER = "Alexa.ColorTemperatureController",
-    COMMISSIONABLE = "Alexa.Commissionable",
-    CONSENT_MANAGEMENT_CONSENT_REQUIRED_REPORTER = "Alexa.ConsentManagement.ConsentRequiredReporter",
-    CONTACT_SENSOR = "Alexa.ContactSensor",
-    COOKING = "Alexa.Cooking",
-    COOKING_FOOD_TEMPERATURE_CONTROLLER = "Alexa.Cooking.FoodTemperatureController",
-    COOKING_FOOD_TEMPERATURE_SENSOR = "Alexa.Cooking.FoodTemperatureSensor",
-    COOKING_PRESET_CONTROLLER = "Alexa.Cooking.PresetController",
-    COOKING_TEMPERATURE_CONTROLLER = "Alexa.Cooking.TemperatureController",
-    COOKING_TEMPERATURE_SENSOR = "Alexa.Cooking.TemperatureSensor",
-    COOKING_TIME_CONTROLLER = "Alexa.Cooking.TimeController",
-    DATA_CONTROLLER = "Alexa.DataController",
-    DEVICE_USAGE_ESTIMATION = "Alexa.DeviceUsage.Estimation",
-    DEVICE_USAGE_METER = "Alexa.DeviceUsage.Meter",
-    DOORBELL_EVENT_SOURCE = "Alexa.DoorbellEventSource",
-    ENDPOINT_HEALTH = "Alexa.EndpointHealth",
-    EQUALIZER_CONTROLLER = "Alexa.EqualizerController",
-    INPUT_CONTROLLER = "Alexa.InputController",
-    INVENTORY_LEVEL_SENSOR = "Alexa.InventoryLevelSensor",
-    INVENTORY_LEVEL_USAGE_SENSOR = "Alexa.InventoryLevelUsageSensor",
-    INVENTORY_USAGE_SENSOR = "Alexa.InventoryUsageSensor",
-    KEYPAD_CONTROLLER = "Alexa.KeypadController",
-    LAUNCHER = "Alexa.Launcher",
-    LOCK_CONTROLLER = "Alexa.LockController",
-    MEDIA_PLAYBACK = "Alexa.Media.Playback",
-    MEDIA_PLAY_QUEUE = "Alexa.Media.PlayQueue",
-    MEDIA_SEARCH = "Alexa.Media.Search",
-    MODE_CONTROLLER = "Alexa.ModeController",
-    MOTION_SENSOR = "Alexa.MotionSensor",
-    PERCENTAGE_CONTROLLER = "Alexa.PercentageController",
-    PLAYBACK_CONTROLLER = "Alexa.PlaybackController",
-    PLAYBACK_STATE_REPORTER = "Alexa.PlaybackStateReporter",
-    POWER_CONTROLLER = "Alexa.PowerController",
-    POWER_LEVEL_CONTROLLER = "Alexa.PowerLevelController",
-    PROACTIVE_NOTIFICATION_SOURCE = "Alexa.ProactiveNotificationSource",
-    RANGE_CONTROLLER = "Alexa.RangeController",
-    RECORD_CONTROLLER = "Alexa.RecordController",
-    REMOTE_VIDEO_PLAYER = "Alexa.RemoteVideoPlayer",
-    RTC_SESSION_CONTROLLER = "Alexa.RTCSessionController",
-    SCENE_CONTROLLER = "Alexa.SceneController",
-    SECURITY_PANEL_CONTROLLER = "Alexa.SecurityPanelController",
-    SECURITY_PANEL_CONTROLLER_ALERT = "Alexa.SecurityPanelController.Alert",
-    SEEK_CONTROLLER = "Alexa.SeekController",
-    SIMPLE_EVENT_SOURCE = "Alexa.SimpleEventSource",
-    SMART_VISION_OBJECT_DETECTION_SENSOR = "Alexa.SmartVision.ObjectDetectionSensor",
-    SMART_VISION_SNAPSHOT_PROVIDER = "Alexa.SmartVision.SnapshotProvider",
-    SPEAKER = "Alexa.Speaker",
-    STEP_SPEAKER = "Alexa.StepSpeaker",
-    TEMPERATURE_SENSOR = "Alexa.TemperatureSensor",
-    THERMOSTAT_CONTROLLER = "Alexa.ThermostatController",
-    THERMOSTAT_CONTROLLER_CONFIGURATION = "Alexa.ThermostatController.Configuration",
-    THERMOSTAT_CONTROLLER_HVAC_COMPONENTS = "Alexa.ThermostatController.HVAC.Components",
-    THERMOSTAT_CONTROLLER_SCHEDULE = "Alexa.ThermostatController.Schedule",
-    TIME_HOLD_CONTROLLER = "Alexa.TimeHoldController",
-    TOGGLE_CONTROLLER = "Alexa.ToggleController",
-    UI_CONTROLLER = "Alexa.UIController",
-    USER_PREFERENCE = "Alexa.UserPreference",
-    VIDEO_RECORDER = "Alexa.VideoRecorder",
-    WAKE_ON_LAN_CONTROLLER = "Alexa.WakeOnLANController",
-    UNKNOWN = "UNKNOWN"
-}
-/** One ModeController mode as discovery lists it (configuration.supportedModes): the value plus its friendly names. */
-export interface SupportedMode {
-    value: string;
-    modeResources?: {
-        friendlyNames: Array<{
-            "@type": string;
-            value: {
-                text?: string;
-                locale?: string;
-                assetId?: string;
-            };
-        }>;
-    };
-}
-export declare class AlexaInterface {
-    type: AlexaInterfaceType;
-    retrievable: boolean;
-    proactivelyReported: boolean;
-    instance: string;
-    private friendlyNames;
-    private actionMappings;
-    private supportedModes;
-    constructor(type: AlexaInterfaceType, retrievable?: boolean, proactivelyReported?: boolean, instance?: string);
-    addActionMapping(mapping: ActionMapping): void;
-    addFriendlyName(name: string, locale: string): void;
-    /** The modes of a ModeController: { value, modeResources } objects as Alexa wants them (plain strings pass through as given). */
-    addSupportedModes(modes: Array<string | SupportedMode>): void;
-    setInstance(name: string): void;
-    getType(): AlexaInterfaceType;
-    getTypeString(): string;
-    /** The version of the interface, from its descriptor. "UNKNOWN" for a name the registry does not have. */
-    getVersion(): string;
-    /** The names of the properties the interface reports, from its descriptor. */
-    getProps(): string[];
-    getJSON(): object;
-}

dist/types/AlexaStatusMessage.d.ts

@@ -1,8 +1,5 @@
+import type { EndpointHealth, PowerController } from "./compat/enums.js";
 import type { MqttClient } from "mqtt";
-export declare enum EndpointHealth {
-    OK = "OK",
-    UNREACHABLE = "UNREACHABLE"
-}
 export declare enum ThermostatMode {
     OFF = "OFF",
     HEAT = "HEAT",
@@ -11,10 +8,6 @@ export declare enum ThermostatMode {
     ECO = "ECO",
     CUSTOM = "CUSTOM"
 }
-export declare enum PowerController {
-    ON = "ON",
-    OFF = "OFF"
-}
 export declare enum TemperatureSensorScale {
     CELSIUS = "CELSIUS",
     FAHRENHEIT = "FAHRENHEIT"

dist/types/Device.d.ts

@@ -1,62 +0,0 @@
-import { AlexaInterface } from "./AlexaInterface.js";
-import type { AlexaInterfaceType } from "./AlexaInterface.js";
-import { DisplayCategory } from "./DisplayCategory.js";
-import { EventEmitter } from "events";
-import type { MqttClient } from "mqtt";
-import { AlexaStatusMessage } from "./AlexaStatusMessage.js";
-import type { ChangeCause } from "./AlexaStatusMessage.js";
-import { AlexaErrorResponse } from "./AlexaErrorResponse.js";
-declare class Device extends EventEmitter {
-    private mqttClient;
-    private rootTopic;
-    name: string;
-    endpointId: string;
-    displayCategory: Array<DisplayCategory> | null;
-    description: string;
-    manufacturerName: string;
-    manufacturer: string;
-    model: string;
-    protected softwareVersion: string;
-    private capabilities;
-    /** Where a failed publish from this device or a message it built is reported; Alex2MQTT sets it (1.5.2). */
-    onPublishError?: (err: Error) => void;
-    constructor(mqttClient: MqttClient, rootTopic: string, name: string, endpointId: string, displayCategory: Array<DisplayCategory> | null, description?: string, manufacturerName?: string, manufacturer?: string, model?: string);
-    /** Internal (1.5.2): Alex2MQTT.connect() re-binds every registered device to its new broker client after a disconnect(). */
-    setMqttClient(client: MqttClient): void;
-    getName(): string;
-    setName(name: string): void;
-    getEndpointId(): string;
-    setDisplayCategory(category: DisplayCategory | DisplayCategory[]): void;
-    getDisplayCategory(): Array<DisplayCategory>;
-    setDescription(description: string): void;
-    getDescription(): string;
-    getErrorMessage(correlationToken: string): AlexaErrorResponse;
-    getStatusMessage(correlationToken: string, isResponse?: boolean, isDeferred?: boolean): AlexaStatusMessage;
-    /**
-     * A proactive Alexa.ChangeReport (1.5.1): add the changed properties (the default target), optionally
-     * .unchanged() then the others, and .send() - it goes to <root>/changeReport, which Alex2MQTT forwards to the Alexa
-     * event gateway with the user's token. Alexa only accepts it for capabilities registered with proactivelyReported.
-     */
-    getChangeReport(cause?: ChangeCause): AlexaStatusMessage;
-    /**
-     * Alexa.SceneController: answer an Activate / Deactivate directive with ActivationStarted / DeactivationStarted
-     * (1.5.1). Resolves with the topic published to, or "" when the publish failed (never rejects, 1.5.2).
-     */
-    sendSceneResponse(correlationToken: string, activated: boolean, cause?: ChangeCause, sendAsync?: boolean): Promise<string>;
-    getCapabilities(): AlexaInterface[];
-    setManufacturerName(name: string): void;
-    getManufacturerName(): string;
-    setManufacturer(manufacturer: string): void;
-    getManufacturer(): string;
-    setModel(model: string): void;
-    getModel(): string;
-    getSoftwareVersion(): string;
-    /** Add a capability. 1.5.1: options.retrievable / proactivelyReported / instance (a change report needs proactivelyReported). */
-    addCapability(type: AlexaInterfaceType, options?: {
-        retrievable?: boolean;
-        proactivelyReported?: boolean;
-        instance?: string;
-    }): AlexaInterface;
-    getJSON(): Record<string, any>;
-}
-export default Device;

dist/types/DisplayCategory.d.ts

@@ -1,60 +0,0 @@
-export declare enum DisplayCategory {
-    ACTIVITY_TRIGGER = "ACTIVITY_TRIGGER",
-    AIR_CONDITIONER = "AIR_CONDITIONER",
-    AIR_FRESHENER = "AIR_FRESHENER",
-    AIR_PURIFIER = "AIR_PURIFIER",
-    AIR_QUALITY_MONITOR = "AIR_QUALITY_MONITOR",
-    ALEXA_VOICE_ENABLED = "ALEXA_VOICE_ENABLED",
-    AUTO_ACCESSORY = "AUTO_ACCESSORY",
-    BLUETOOTH_SPEAKER = "BLUETOOTH_SPEAKER",
-    CAMERA = "CAMERA",
-    CHRISTMAS_TREE = "CHRISTMAS_TREE",
-    COFFEE_MAKER = "COFFEE_MAKER",
-    COMPUTER = "COMPUTER",
-    CONTACT_SENSOR = "CONTACT_SENSOR",
-    DISHWASHER = "DISHWASHER",
-    DOOR = "DOOR",
-    DOORBELL = "DOORBELL",
-    DRYER = "DRYER",
-    EXTERIOR_BLIND = "EXTERIOR_BLIND",
-    FAN = "FAN",
-    GAME_CONSOLE = "GAME_CONSOLE",
-    GARAGE_DOOR = "GARAGE_DOOR",
-    HEADPHONES = "HEADPHONES",
-    HUB = "HUB",
-    INTERIOR_BLIND = "INTERIOR_BLIND",
-    LAPTOP = "LAPTOP",
-    LIGHT = "LIGHT",
-    MICROWAVE = "MICROWAVE",
-    MOBILE_PHONE = "MOBILE_PHONE",
-    MOTION_SENSOR = "MOTION_SENSOR",
-    MUSIC_SYSTEM = "MUSIC_SYSTEM",
-    NETWORK_HARDWARE = "NETWORK_HARDWARE",
-    OTHER = "OTHER",
-    OVEN = "OVEN",
-    PHONE = "PHONE",
-    PRINTER = "PRINTER",
-    REMOTE = "REMOTE",
-    ROUTER = "ROUTER",
-    SCENE_TRIGGER = "SCENE_TRIGGER",
-    SCREEN = "SCREEN",
-    SECURITY_PANEL = "SECURITY_PANEL",
-    SECURITY_SYSTEM = "SECURITY_SYSTEM",
-    SLOW_COOKER = "SLOW_COOKER",
-    SMARTLOCK = "SMARTLOCK",
-    SMARTPLUG = "SMARTPLUG",
-    SPEAKER = "SPEAKER",
-    STREAMING_DEVICE = "STREAMING_DEVICE",
-    SWITCH = "SWITCH",
-    TABLET = "TABLET",
-    TEMPERATURE_SENSOR = "TEMPERATURE_SENSOR",
-    THERMOSTAT = "THERMOSTAT",
-    TV = "TV",
-    VACUUM_CLEANER = "VACUUM_CLEANER",
-    VACUUM = "VACUUM",
-    /** Not on the list of display categories any more; kept for 1.x callers. */
-    VEHICLE = "VEHICLE",
-    WASHER = "WASHER",
-    WATER_HEATER = "WATER_HEATER",
-    WEARABLE = "WEARABLE"
-}

dist/types/compat/ActionMapping.d.ts

@@ -0,0 +1,23 @@
+import type { ActionsToDirective } from "../registry/types.js";
+import type { AlexaActions } from "./enums.js";
+/**
+ * A semantics action mapping of 1.x: the phrases "open", "close", "raise", "lower" for one directive of the
+ * capability it is added to.
+ *
+ *   toggle.addActionMapping(new ActionMapping([AlexaActions.Close], "TurnOff"));
+ *   lift.addActionMapping(new ActionMapping([AlexaActions.Open], "SetRangeValue", { rangeValue: 100 }));
+ */
+export declare class ActionMapping {
+    type: "ActionsToDirective";
+    actions: AlexaActions[];
+    directive: ActionsToDirective["directive"];
+    /** Set when the mapping was built in a way that 3.0 will refuse; the bridge logs it at the next discovery. */
+    readonly deprecation?: string;
+    /**
+     * directivePayload is the payload object of the directive (alexa-discovery-objects.html, "ActionMappings object").
+     * 1.x took a string and put it into discovery as one. A string that holds a JSON object is parsed; any other
+     * string throws a DeclarationError.
+     */
+    constructor(actions: AlexaActions[], directiveName: string, directivePayload?: Record<string, unknown> | string);
+    toJSON(): ActionsToDirective;
+}

dist/types/compat/AlexaInterface.d.ts

@@ -0,0 +1,49 @@
+import { Capability } from "../device/Capability.js";
+import type { CapabilityJson } from "../device/Capability.js";
+import type { Semantics } from "../registry/types.js";
+import type { ActionMapping } from "./ActionMapping.js";
+import type { AlexaInterfaceType } from "./enums.js";
+/** One ModeController mode as discovery lists it (configuration.supportedModes): the value plus its friendly names. */
+export interface SupportedMode {
+    value: string;
+    modeResources?: {
+        friendlyNames: Array<{
+            "@type": string;
+            value: {
+                text?: string;
+                locale?: string;
+                assetId?: string;
+            };
+        }>;
+    };
+}
+interface Options {
+    semantics?: Semantics;
+    supportedModes?: Array<string | SupportedMode>;
+}
+/**
+ * A capability as 1.x declares it: device.addCapability(type, options), then the add and set methods below. It is a
+ * Capability, so what the methods set reaches discovery the same way as the options of device.add(). Nothing is
+ * refused here except an interface name the registry does not have: what Alexa would reject is logged by the bridge
+ * when it answers a discovery.
+ */
+export declare class AlexaInterface extends Capability<any, any, Options> {
+    constructor(type: AlexaInterfaceType | string, retrievable?: boolean, proactivelyReported?: boolean, instance?: string);
+    /** The namespace of the interface, which is the value of its AlexaInterfaceType member. */
+    get type(): AlexaInterfaceType;
+    addActionMapping(mapping: ActionMapping): void;
+    addFriendlyName(name: string, locale: string): void;
+    /** The modes of a ModeController, as { value, modeResources } objects. */
+    addSupportedModes(modes: Array<string | SupportedMode>): void;
+    setInstance(name: string): void;
+    getType(): AlexaInterfaceType;
+    /** @deprecated The same as getType(). */
+    getTypeString(): string;
+    /** @deprecated Read descriptor.version. */
+    getVersion(): string;
+    /** @deprecated Read the keys of descriptor.properties. */
+    getProps(): string[];
+    getJSON(): CapabilityJson;
+    toJSON(): CapabilityJson;
+}
+export {};

dist/types/compat/enums.d.ts

@@ -0,0 +1,193 @@
+/** Every interface name of 1.x. registry.get() takes a member as it takes the namespace, which is its value. */
+export declare enum AlexaInterfaceType {
+    APPLICATION_STATE_REPORTER = "Alexa.ApplicationStateReporter",
+    AUDIO_PLAY_QUEUE = "Alexa.Audio.PlayQueue",
+    AUTHORIZATION_CONTROLLER = "Alexa.AuthorizationController",
+    AUTOMATION_MANAGEMENT = "Alexa.AutomationManagement",
+    AUTOMOTIVE_VEHICLE_DATA = "Alexa.Automotive.VehicleData",
+    BRIGHTNESS_CONTROLLER = "Alexa.BrightnessController",
+    CAMERA_LIVE_VIEW_CONTROLLER = "Alexa.Camera.LiveViewController",
+    CAMERA_STREAM_CONTROLLER = "Alexa.CameraStreamController",
+    CHANNEL_CONTROLLER = "Alexa.ChannelController",
+    COLOR_CONTROLLER = "Alexa.ColorController",
+    COLOR_TEMPERATURE_CONTROLLER = "Alexa.ColorTemperatureController",
+    COMMISSIONABLE = "Alexa.Commissionable",
+    CONSENT_MANAGEMENT_CONSENT_REQUIRED_REPORTER = "Alexa.ConsentManagement.ConsentRequiredReporter",
+    CONTACT_SENSOR = "Alexa.ContactSensor",
+    COOKING = "Alexa.Cooking",
+    COOKING_FOOD_TEMPERATURE_CONTROLLER = "Alexa.Cooking.FoodTemperatureController",
+    COOKING_FOOD_TEMPERATURE_SENSOR = "Alexa.Cooking.FoodTemperatureSensor",
+    COOKING_PRESET_CONTROLLER = "Alexa.Cooking.PresetController",
+    COOKING_TEMPERATURE_CONTROLLER = "Alexa.Cooking.TemperatureController",
+    COOKING_TEMPERATURE_SENSOR = "Alexa.Cooking.TemperatureSensor",
+    COOKING_TIME_CONTROLLER = "Alexa.Cooking.TimeController",
+    DATA_CONTROLLER = "Alexa.DataController",
+    DEVICE_USAGE_ESTIMATION = "Alexa.DeviceUsage.Estimation",
+    DEVICE_USAGE_METER = "Alexa.DeviceUsage.Meter",
+    DOORBELL_EVENT_SOURCE = "Alexa.DoorbellEventSource",
+    ENDPOINT_HEALTH = "Alexa.EndpointHealth",
+    EQUALIZER_CONTROLLER = "Alexa.EqualizerController",
+    INPUT_CONTROLLER = "Alexa.InputController",
+    INVENTORY_LEVEL_SENSOR = "Alexa.InventoryLevelSensor",
+    INVENTORY_LEVEL_USAGE_SENSOR = "Alexa.InventoryLevelUsageSensor",
+    INVENTORY_USAGE_SENSOR = "Alexa.InventoryUsageSensor",
+    KEYPAD_CONTROLLER = "Alexa.KeypadController",
+    LAUNCHER = "Alexa.Launcher",
+    LOCK_CONTROLLER = "Alexa.LockController",
+    MEDIA_PLAYBACK = "Alexa.Media.Playback",
+    MEDIA_PLAY_QUEUE = "Alexa.Media.PlayQueue",
+    MEDIA_SEARCH = "Alexa.Media.Search",
+    MODE_CONTROLLER = "Alexa.ModeController",
+    MOTION_SENSOR = "Alexa.MotionSensor",
+    PERCENTAGE_CONTROLLER = "Alexa.PercentageController",
+    PLAYBACK_CONTROLLER = "Alexa.PlaybackController",
+    PLAYBACK_STATE_REPORTER = "Alexa.PlaybackStateReporter",
+    POWER_CONTROLLER = "Alexa.PowerController",
+    POWER_LEVEL_CONTROLLER = "Alexa.PowerLevelController",
+    PROACTIVE_NOTIFICATION_SOURCE = "Alexa.ProactiveNotificationSource",
+    RANGE_CONTROLLER = "Alexa.RangeController",
+    RECORD_CONTROLLER = "Alexa.RecordController",
+    REMOTE_VIDEO_PLAYER = "Alexa.RemoteVideoPlayer",
+    RTC_SESSION_CONTROLLER = "Alexa.RTCSessionController",
+    SCENE_CONTROLLER = "Alexa.SceneController",
+    SECURITY_PANEL_CONTROLLER = "Alexa.SecurityPanelController",
+    SECURITY_PANEL_CONTROLLER_ALERT = "Alexa.SecurityPanelController.Alert",
+    SEEK_CONTROLLER = "Alexa.SeekController",
+    SIMPLE_EVENT_SOURCE = "Alexa.SimpleEventSource",
+    SMART_VISION_OBJECT_DETECTION_SENSOR = "Alexa.SmartVision.ObjectDetectionSensor",
+    SMART_VISION_SNAPSHOT_PROVIDER = "Alexa.SmartVision.SnapshotProvider",
+    SPEAKER = "Alexa.Speaker",
+    STEP_SPEAKER = "Alexa.StepSpeaker",
+    TEMPERATURE_SENSOR = "Alexa.TemperatureSensor",
+    THERMOSTAT_CONTROLLER = "Alexa.ThermostatController",
+    THERMOSTAT_CONTROLLER_CONFIGURATION = "Alexa.ThermostatController.Configuration",
+    THERMOSTAT_CONTROLLER_HVAC_COMPONENTS = "Alexa.ThermostatController.HVAC.Components",
+    THERMOSTAT_CONTROLLER_SCHEDULE = "Alexa.ThermostatController.Schedule",
+    TIME_HOLD_CONTROLLER = "Alexa.TimeHoldController",
+    TOGGLE_CONTROLLER = "Alexa.ToggleController",
+    UI_CONTROLLER = "Alexa.UIController",
+    USER_PREFERENCE = "Alexa.UserPreference",
+    VIDEO_RECORDER = "Alexa.VideoRecorder",
+    WAKE_ON_LAN_CONTROLLER = "Alexa.WakeOnLANController",
+    /** Not an interface: declaring it throws a DeclarationError. Kept because 1.x had it. */
+    UNKNOWN = "UNKNOWN"
+}
+export declare enum DisplayCategory {
+    ACTIVITY_TRIGGER = "ACTIVITY_TRIGGER",
+    AIR_CONDITIONER = "AIR_CONDITIONER",
+    AIR_FRESHENER = "AIR_FRESHENER",
+    AIR_PURIFIER = "AIR_PURIFIER",
+    AIR_QUALITY_MONITOR = "AIR_QUALITY_MONITOR",
+    ALEXA_VOICE_ENABLED = "ALEXA_VOICE_ENABLED",
+    AUTO_ACCESSORY = "AUTO_ACCESSORY",
+    BLUETOOTH_SPEAKER = "BLUETOOTH_SPEAKER",
+    CAMERA = "CAMERA",
+    CHRISTMAS_TREE = "CHRISTMAS_TREE",
+    COFFEE_MAKER = "COFFEE_MAKER",
+    COMPUTER = "COMPUTER",
+    CONTACT_SENSOR = "CONTACT_SENSOR",
+    DISHWASHER = "DISHWASHER",
+    DOOR = "DOOR",
+    DOORBELL = "DOORBELL",
+    DRYER = "DRYER",
+    EXTERIOR_BLIND = "EXTERIOR_BLIND",
+    FAN = "FAN",
+    GAME_CONSOLE = "GAME_CONSOLE",
+    GARAGE_DOOR = "GARAGE_DOOR",
+    HEADPHONES = "HEADPHONES",
+    HUB = "HUB",
+    INTERIOR_BLIND = "INTERIOR_BLIND",
+    LAPTOP = "LAPTOP",
+    LIGHT = "LIGHT",
+    MICROWAVE = "MICROWAVE",
+    MOBILE_PHONE = "MOBILE_PHONE",
+    MOTION_SENSOR = "MOTION_SENSOR",
+    MUSIC_SYSTEM = "MUSIC_SYSTEM",
+    NETWORK_HARDWARE = "NETWORK_HARDWARE",
+    OTHER = "OTHER",
+    OVEN = "OVEN",
+    PHONE = "PHONE",
+    PRINTER = "PRINTER",
+    REMOTE = "REMOTE",
+    ROUTER = "ROUTER",
+    SCENE_TRIGGER = "SCENE_TRIGGER",
+    SCREEN = "SCREEN",
+    SECURITY_PANEL = "SECURITY_PANEL",
+    SECURITY_SYSTEM = "SECURITY_SYSTEM",
+    SLOW_COOKER = "SLOW_COOKER",
+    SMARTLOCK = "SMARTLOCK",
+    SMARTPLUG = "SMARTPLUG",
+    SPEAKER = "SPEAKER",
+    STREAMING_DEVICE = "STREAMING_DEVICE",
+    SWITCH = "SWITCH",
+    TABLET = "TABLET",
+    TEMPERATURE_SENSOR = "TEMPERATURE_SENSOR",
+    THERMOSTAT = "THERMOSTAT",
+    TV = "TV",
+    VACUUM_CLEANER = "VACUUM_CLEANER",
+    VACUUM = "VACUUM",
+    /** Not on the list of display categories any more; kept for 1.x callers. */
+    VEHICLE = "VEHICLE",
+    WASHER = "WASHER",
+    WATER_HEATER = "WATER_HEATER",
+    WEARABLE = "WEARABLE"
+}
+export declare enum AlexaActions {
+    Open = "Alexa.Actions.Open",
+    Close = "Alexa.Actions.Close",
+    Raise = "Alexa.Actions.Raise",
+    Lower = "Alexa.Actions.Lower",
+    SetEcoOn = "Alexa.Actions.SetEcoOn",
+    SetEcoOff = "Alexa.Actions.SetEcoOff"
+}
+/** The values of powerState and toggleState. */
+export declare const PowerState: {
+    readonly ON: "ON";
+    readonly OFF: "OFF";
+};
+export type PowerState = (typeof PowerState)[keyof typeof PowerState];
+declare const Connectivity: {
+    readonly OK: "OK";
+    readonly UNREACHABLE: "UNREACHABLE";
+};
+/**
+ * The Alexa.PowerController interface, for device.add(). PowerController.ON and PowerController.OFF are the 1.x enum
+ * of power states and stay until 3.0: PowerState has the same two members.
+ */
+export declare const PowerController: import("../index.js").InterfaceDescriptor<{
+    powerState: {
+        name: string;
+        value: import("../registry/schema.js").EnumSchema<"ON" | "OFF">;
+    };
+}, {
+    TurnOn: {
+        name: string;
+        payload: import("../index.js").Schema<import("../registry/schema.js").InferShape<{}>>;
+    };
+    TurnOff: {
+        name: string;
+        payload: import("../index.js").Schema<import("../registry/schema.js").InferShape<{}>>;
+    };
+}, import("../registry/schema.js").InferShape<{
+    verificationsRequired: import("../registry/schema.js").OptionalSchema<("TurnOn" | "TurnOff")[]>;
+}>, false> & {
+    readonly ON: "ON";
+    readonly OFF: "OFF";
+};
+export type PowerController = PowerState;
+/** The Alexa.EndpointHealth interface, for device.add(). EndpointHealth.OK and EndpointHealth.UNREACHABLE are the 1.x enum of connectivity values. */
+export declare const EndpointHealth: import("../index.js").InterfaceDescriptor<{
+    connectivity: {
+        name: string;
+        value: import("../index.js").Schema<import("../registry/schema.js").InferShape<{
+            value: import("../registry/schema.js").EnumSchema<"OK" | "UNREACHABLE">;
+            reason: import("../registry/schema.js").OptionalSchema<"WIFI_BAD_PASSWORD" | "WIFI_AP_NOT_FOUND" | "WIFI_ROUTER_UNREACHABLE" | "WIFI_AP_CHANNEL_QUALITY_LOW" | "INTERNET_UNREACHABLE" | "CAPTIVE_PORTAL_CHECK_FAILED" | "UNKNOWN">;
+        }>>;
+        note: string;
+    };
+}, {}, {}, false> & {
+    readonly OK: "OK";
+    readonly UNREACHABLE: "UNREACHABLE";
+};
+export type EndpointHealth = (typeof Connectivity)[keyof typeof Connectivity];
+export {};

dist/types/device/Capability.d.ts

@@ -0,0 +1,79 @@
+import type { Declared, Directives, InterfaceDescriptor, Label, Properties, Semantics } from "../registry/types.js";
+/** What a declaration can set for any interface. */
+export interface CommonOptions {
+    /** The name of the instance of a generic controller: "Blind.Lift", "Fan.Speed". */
+    instance?: string;
+    /** What the user calls the instance; the first name is the one the Alexa app shows. */
+    friendlyNames?: Label[];
+    /** The properties are in the answer to ReportState. Default: true. */
+    retrievable?: boolean;
+    /** A change of the properties is sent to Alexa as a ChangeReport. Default: false. */
+    proactivelyReported?: boolean;
+    /** The user can ask for the properties and cannot set them. Left out of discovery when not given. */
+    nonControllable?: boolean;
+}
+/** The same as a schema. The friendly names are checked with the instance, by the rules of the interface. */
+export declare const commonOptions: import("../registry/schema.js").Schema<import("../registry/schema.js").InferShape<{
+    instance: import("../registry/schema.js").OptionalSchema<string>;
+    friendlyNames: import("../registry/schema.js").OptionalSchema<unknown[]>;
+    retrievable: import("../registry/schema.js").OptionalSchema<boolean>;
+    proactivelyReported: import("../registry/schema.js").OptionalSchema<boolean>;
+    nonControllable: import("../registry/schema.js").OptionalSchema<boolean>;
+}>>;
+type Naming<I extends boolean> = I extends true ? {
+    instance: string;
+    friendlyNames: Label[];
+} : {
+    instance?: string;
+    friendlyNames?: Label[];
+};
+/** The options of device.add() for one interface: its own, and the ones every interface has. */
+export type Declaration<O, I extends boolean> = O & Omit<CommonOptions, "instance" | "friendlyNames"> & Naming<I>;
+/** A capability object of a discovery answer (alexa-discovery-objects.html, "Capability object"). */
+export interface CapabilityJson {
+    type: "AlexaInterface";
+    interface: string;
+    instance?: string;
+    version: string;
+    properties?: {
+        supported: Array<{
+            name: string;
+        }>;
+        proactivelyReported: boolean;
+        retrievable: boolean;
+        nonControllable?: boolean;
+    };
+    capabilityResources?: {
+        friendlyNames: Label[];
+    };
+    configuration?: Record<string, unknown>;
+    configurations?: Record<string, unknown>;
+    semantics?: Semantics;
+    [field: string]: unknown;
+}
+/** One interface as an endpoint declares it: the descriptor, and what the declaration says about this endpoint. */
+export declare class Capability<P extends Properties = Properties, D extends Directives = Directives, O = {}> implements Declared<O> {
+    readonly descriptor: InterfaceDescriptor<P, D, O, boolean>;
+    /** The endpoint the capability is declared on; the device sets it. */
+    endpointId: string;
+    /** "" for an interface without instances. */
+    instance: string;
+    friendlyNames: Label[];
+    retrievable: boolean;
+    proactivelyReported: boolean;
+    nonControllable?: boolean;
+    /** The options of the interface: a range, the supported modes, the semantics. */
+    options: O;
+    /** What the bridge logs about the declaration, once, when it answers a discovery. */
+    readonly notes: string[];
+    constructor(descriptor: InterfaceDescriptor<P, D, O, boolean>, declared: CommonOptions & {
+        options: O;
+    });
+    get namespace(): string;
+    /** Mappings of "open", "close", "raise", "lower" and of states, when the declaration has any. */
+    get semantics(): Semantics | undefined;
+    /** The capability object for discovery, its fields in the order of the example on alexa-discovery-objects.html. */
+    toJSON(): CapabilityJson;
+}
+export type AnyCapability = Capability<any, any, any>;
+export {};

dist/types/device/Device.d.ts

@@ -0,0 +1,135 @@
+import { EventEmitter } from "events";
+import type { MqttClient } from "mqtt";
+import { AlexaErrorResponse } from "../AlexaErrorResponse.js";
+import { AlexaStatusMessage } from "../AlexaStatusMessage.js";
+import type { ChangeCause } from "../AlexaStatusMessage.js";
+import { AlexaInterface } from "../compat/AlexaInterface.js";
+import { DisplayCategory } from "../compat/enums.js";
+import type { AlexaInterfaceType } from "../compat/enums.js";
+import type { DisplayCategoryName } from "../registry/catalog.js";
+import type { Directives, InterfaceDescriptor, Properties } from "../registry/types.js";
+import { Capability } from "./Capability.js";
+import type { AnyCapability, CapabilityJson, Declaration } from "./Capability.js";
+import type { EndpointFields } from "./validate.js";
+/** An endpoint as bridge.addDevice() takes it. */
+export interface EndpointDefinition {
+    /** Up to 256 letters, digits, spaces and _ - = # ; : ? @ &. The same id at every discovery. */
+    endpointId: string;
+    /** What the user calls the device: letters, digits and spaces. */
+    name: string;
+    /** The first one is the category the Alexa app shows the device under. */
+    categories: Array<DisplayCategoryName | DisplayCategory>;
+    /** Shown in the Alexa app, up to 128 characters. Default: "Alexa to Node.js bridge". */
+    description?: string;
+    /** Up to 128 characters. Default: "Alex2Node". */
+    manufacturerName?: string;
+    manufacturer?: string;
+    model?: string;
+    serialNumber?: string;
+    firmwareVersion?: string;
+    softwareVersion?: string;
+    customIdentifier?: string;
+    /** Returned with every directive to the endpoint. Up to 5000 bytes; not a place for state. */
+    cookie?: Record<string, string>;
+    /** false: the device gets no Alexa.EndpointHealth unless it declares one. */
+    endpointHealth?: boolean;
+}
+/** An endpoint object of a discovery answer (alexa-discovery-objects.html, "Endpoint object"). */
+export interface EndpointJson extends EndpointFields {
+    capabilities: CapabilityJson[];
+}
+type DeclarationArguments<O, I extends boolean> = {} extends Declaration<O, I> ? [options?: Declaration<O, I>] : [options: Declaration<O, I>];
+declare class Device extends EventEmitter {
+    private mqttClient;
+    private rootTopic;
+    name: string;
+    endpointId: string;
+    displayCategory: Array<DisplayCategory> | null;
+    description: string;
+    manufacturerName: string;
+    manufacturer: string;
+    model: string;
+    softwareVersion: string;
+    serialNumber: string;
+    firmwareVersion: string;
+    customIdentifier: string;
+    cookie?: Record<string, string>;
+    /**
+     * Discovery lists the Alexa interface on the endpoint (alexa-interface.html: "You must explicitly identify your
+     * support for the Alexa interface"). The bridge sets it from its alexaInterface option.
+     */
+    alexaInterface: boolean;
+    /**
+     * Discovery lists Alexa.EndpointHealth when the device did not declare it and is not a scene. On for a device of
+     * bridge.addDevice(), off for one of registerDevice(), which is announced as 1.x announced it.
+     */
+    endpointHealth: boolean;
+    private capabilities;
+    /** Where a failed publish from this device or a message it built is reported; Alex2MQTT sets it (1.5.2). */
+    onPublishError?: (err: Error) => void;
+    constructor(mqttClient: MqttClient, rootTopic: string, name: string, endpointId: string, displayCategory: Array<DisplayCategory> | null, description?: string, manufacturerName?: string, manufacturer?: string, model?: string);
+    /** Internal (1.5.2): Alex2MQTT.connect() re-binds every registered device to its new broker client after a disconnect(). */
+    setMqttClient(client: MqttClient): void;
+    getName(): string;
+    setName(name: string): void;
+    getEndpointId(): string;
+    setDisplayCategory(category: DisplayCategory | DisplayCategory[]): void;
+    getDisplayCategory(): Array<DisplayCategory>;
+    setDescription(description: string): void;
+    getDescription(): string;
+    getErrorMessage(correlationToken: string): AlexaErrorResponse;
+    getStatusMessage(correlationToken: string, isResponse?: boolean, isDeferred?: boolean): AlexaStatusMessage;
+    /**
+     * A proactive Alexa.ChangeReport (1.5.1): add the changed properties (the default target), optionally
+     * .unchanged() then the others, and .send() - it goes to <root>/changeReport, which Alex2MQTT forwards to the Alexa
+     * event gateway with the user's token. Alexa only accepts it for capabilities registered with proactivelyReported.
+     */
+    getChangeReport(cause?: ChangeCause): AlexaStatusMessage;
+    /**
+     * Alexa.SceneController: answer an Activate / Deactivate directive with ActivationStarted / DeactivationStarted
+     * (1.5.1). Resolves with the topic published to, or "" when the publish failed (never rejects, 1.5.2).
+     */
+    sendSceneResponse(correlationToken: string, activated: boolean, cause?: ChangeCause, sendAsync?: boolean): Promise<string>;
+    /** The capabilities the device declared, in the order it declared them. */
+    getCapabilities(): AnyCapability[];
+    setManufacturerName(name: string): void;
+    getManufacturerName(): string;
+    setManufacturer(manufacturer: string): void;
+    getManufacturer(): string;
+    setModel(model: string): void;
+    getModel(): string;
+    getSoftwareVersion(): string;
+    /**
+     * Declare an interface of the device:
+     *
+     *   lamp.add(PowerController, { proactivelyReported: true });
+     *   blinds.add(RangeController, { instance: "Blind.Lift", friendlyNames: [asset("Alexa.Setting.Opening")],
+     *     range: { min: 0, max: 100, precision: 1 } });
+     *
+     * Throws a DeclarationError that names the endpoint, the interface and the instance when Alexa would reject the
+     * capability; the device is then as it was before the call.
+     */
+    add<P extends Properties, D extends Directives, O, I extends boolean>(descriptor: InterfaceDescriptor<P, D, O, I>, ...[options]: DeclarationArguments<O, I>): Capability<P, D, O>;
+    /**
+     * Declare an interface the 1.x way, by its name: options.retrievable / proactivelyReported / instance, then the
+     * add and set methods of the capability that is returned. Throws for a name that is not an interface. Anything
+     * else Alexa would reject is not refused here: check() lists it.
+     */
+    addCapability(type: AlexaInterfaceType | string, options?: {
+        retrievable?: boolean;
+        proactivelyReported?: boolean;
+        instance?: string;
+    }): AlexaInterface;
+    /**
+     * What Alexa would reject in the device as it is declared now, one line for each: a name with punctuation, an
+     * interface declared twice. Also what a capability noted about its declaration. Empty when there is nothing.
+     * The bridge logs the lines when it answers a discovery.
+     */
+    check(): string[];
+    /** The endpoint object for discovery. */
+    getJSON(): EndpointJson;
+    private fields;
+    private view;
+    private announced;
+}
+export default Device;

dist/types/device/validate.d.ts

@@ -0,0 +1,20 @@
+import type { AnyDescriptor, Declared, EndpointView } from "../registry/types.js";
+/** An endpoint as discovery sends it, without its capabilities. */
+export interface EndpointFields {
+    endpointId: string;
+    friendlyName: string;
+    description: string;
+    manufacturerName: string;
+    displayCategories: readonly string[];
+    additionalAttributes: Readonly<Record<string, string>>;
+    cookie?: Readonly<Record<string, string>>;
+}
+/** Throws the first rule of the Endpoint object that the fields break. */
+export declare function checkEndpoint(endpoint: EndpointFields): void;
+/** alexa-discovery.html, "Interface limits". count includes the capabilities the library adds. */
+export declare function checkCapabilityCount(endpointId: string, count: number): void;
+/**
+ * Throws the first rule that a capability breaks on its endpoint. endpoint.capabilities are the ones declared
+ * before it. A stub is checked for being declared twice and for nothing else: the library does not know its rules.
+ */
+export declare function checkCapability(capability: Declared<unknown>, descriptor: AnyDescriptor, endpoint: EndpointView): void;

dist/types/index.d.ts

@@ -1,13 +1,19 @@
 export { default as Alex2MQTT, DEFAULT_HOST } from "./Alex2Node.js";
 export type { Alex2MQTTOptions } from "./Alex2Node.js";
-export { default as Device } from "./Device.js";
-export { AlexaInterface, AlexaInterfaceType } from "./AlexaInterface.js";
-export type { SupportedMode } from "./AlexaInterface.js";
-export { ActionMapping, AlexaActions } from "./ActionMapping.js";
-export { DisplayCategory } from "./DisplayCategory.js";
-export { AlexaStatusMessage, PowerController, EndpointHealth, TemperatureSensorScale, ThermostatMode } from "./AlexaStatusMessage.js";
+export { default as Device } from "./device/Device.js";
+export type { EndpointDefinition, EndpointJson } from "./device/Device.js";
+export { Capability } from "./device/Capability.js";
+export type { CapabilityJson, CommonOptions, Declaration } from "./device/Capability.js";
+export { registry, DeclarationError, SchemaError } from "./registry/index.js";
+export { Alexa, BrightnessController, TemperatureSensor } from "./registry/index.js";
+export { PowerController, EndpointHealth } from "./compat/enums.js";
+export { asset, text } from "./registry/resources.js";
+export { ASSETS as Assets, UNITS_OF_MEASURE as Units, ACTIONS as Actions, STATES as States, DISPLAY_CATEGORIES as DisplayCategories, } from "./registry/index.js";
+export type { ActionId, AssetId, DisplayCategoryName, StateId, UnitOfMeasure, ActionsToDirective, AnyDescriptor, CapabilityExtras, Declared, DirectiveDescriptor, EndpointView, EventDescriptor, InterfaceDescriptor, Label, PropertyDescriptor, Semantics, StatesToRange, StatesToValue, Infer, Schema, Temperature, TimeInterval, } from "./registry/index.js";
+export { AlexaInterface } from "./compat/AlexaInterface.js";
+export type { SupportedMode } from "./compat/AlexaInterface.js";
+export { ActionMapping } from "./compat/ActionMapping.js";
+export { AlexaActions, AlexaInterfaceType, DisplayCategory, PowerState } from "./compat/enums.js";
+export { AlexaStatusMessage, TemperatureSensorScale, ThermostatMode } from "./AlexaStatusMessage.js";
 export type { ChangeCause } from "./AlexaStatusMessage.js";
 export { AlexaErrorType, AlexaErrorResponse } from "./AlexaErrorResponse.js";
-export { registry, DeclarationError, SchemaError } from "./registry/index.js";
-export { ASSETS as Assets, UNITS_OF_MEASURE as Units, ACTIONS as Actions, STATES as States, DISPLAY_CATEGORIES as DisplayCategories, } from "./registry/index.js";
-export type { ActionId, AssetId, DisplayCategoryName, StateId, UnitOfMeasure, AnyDescriptor, CapabilityExtras, Declared, DirectiveDescriptor, EndpointView, EventDescriptor, InterfaceDescriptor, Label, PropertyDescriptor, Infer, Schema, Temperature, TimeInterval, } from "./registry/index.js";

dist/types/registry/index.d.ts

@@ -14,7 +14,7 @@ export declare const registry: {
 };
 export { Alexa, BrightnessController, EndpointHealth, PowerController, TemperatureSensor };
 export { DeclarationError, defineInterface } from "./types.js";
-export type { AnyDescriptor, CapabilityExtras, Declared, DirectiveDescriptor, EndpointView, EventDescriptor, InterfaceDescriptor, Label, PropertyDescriptor, } from "./types.js";
+export type { ActionsToDirective, AnyDescriptor, CapabilityExtras, Declared, DirectiveDescriptor, EndpointView, EventDescriptor, InterfaceDescriptor, Label, PropertyDescriptor, Semantics, StatesToRange, StatesToValue, } from "./types.js";
 export { s, SchemaError } from "./schema.js";
 export type { Infer, Schema, Temperature, TimeInterval } from "./schema.js";
 export * from "./catalog.js";

dist/types/registry/resources.d.ts

@@ -0,0 +1,13 @@
+import type { AssetId } from "./catalog.js";
+import type { Schema } from "./schema.js";
+import type { Label } from "./types.js";
+/** A friendly name as text, in one locale. */
+export declare function text(name: string, locale?: string): Label;
+/** A friendly name from the global Alexa catalog: one id, several names, every language Alexa speaks. */
+export declare function asset(assetId: AssetId): Label;
+/** One friendly name. An asset has to be in the catalog, a text must not be a word Alexa keeps for itself. */
+export declare const label: Schema<Label>;
+/** The friendly names of an instance, a mode or a preset: at least one. */
+export declare const labels: Schema<Label[]>;
+/** What the user is shown for a friendly name: the text, or the id of the asset. */
+export declare function shownAs(name: Label): string;

dist/types/registry/schema.d.ts

@@ -44,6 +44,10 @@ export interface TimeInterval {
     end?: string;
     duration?: string;
 }
+/** The error of a value that is not what a schema expects. */
+export declare function mismatch(path: string, expects: string, input: unknown): SchemaError;
+/** The path of a key of the object at path. */
+export declare const at: (path: string, key: string) => string;
 declare function number(rules?: NumberRules): Schema<number>;
 declare function string(rules?: {
     min?: number;
@@ -54,6 +58,8 @@ declare function string(rules?: {
 declare function boolean(): Schema<boolean>;
 declare function literal<V extends string | number | boolean | null>(value: V): Schema<V>;
 declare function enumeration<V extends readonly string[]>(...values: V): EnumSchema<V[number]>;
+/** One of a list too long to print in an error message: expects says what the list is. */
+declare function oneOf<V extends string>(values: readonly V[], expects: string): EnumSchema<V>;
 declare function unknown(): Schema<unknown>;
 declare function optional<T>(inner: Schema<T>): OptionalSchema<T>;
 declare function nullable<T>(inner: Schema<T>): Schema<T | null>;
@@ -78,6 +84,7 @@ export declare const s: {
     boolean: typeof boolean;
     literal: typeof literal;
     enum: typeof enumeration;
+    oneOf: typeof oneOf;
     unknown: typeof unknown;
     optional: typeof optional;
     nullable: typeof nullable;

dist/types/registry/types.d.ts

@@ -15,6 +15,35 @@ export type Label = {
         assetId: string;
     };
 };
+/** Phrases ("open", "lower") mapped to one directive (alexa-discovery-objects.html, "ActionMappings object"). */
+export interface ActionsToDirective {
+    "@type": "ActionsToDirective";
+    actions: string[];
+    directive: {
+        name: string;
+        payload?: Record<string, unknown>;
+    };
+}
+/** States ("open", "closed") mapped to a value of the property (same page, "StateMappings object"). */
+export interface StatesToValue {
+    "@type": "StatesToValue";
+    states: string[];
+    value: unknown;
+}
+/** States mapped to a range of values of the property. */
+export interface StatesToRange {
+    "@type": "StatesToRange";
+    states: string[];
+    range: {
+        minimumValue: number;
+        maximumValue: number;
+    };
+}
+/** The semantics object of a generic controller: at least one of the two lists. */
+export interface Semantics {
+    actionMappings?: ActionsToDirective[];
+    stateMappings?: Array<StatesToValue | StatesToRange>;
+}
 export interface PropertyDescriptor<V> {
     name: string;
     value: Schema<V>;
@@ -49,7 +78,7 @@ export interface CapabilityExtras {
     properties?: false;
 }
 /** A capability as declared on an endpoint: what discovery() and validate() of its descriptor are given. */
-export interface Declared<O = Record<string, unknown>> {
+export interface Declared<O = unknown> {
     readonly endpointId: string;
     readonly namespace: string;
     /** "" when the interface is declared without an instance. */
@@ -67,7 +96,7 @@ export interface EndpointView {
     readonly friendlyName: string;
     readonly description: string;
     readonly displayCategories: readonly string[];
-    /** The other capabilities of the endpoint. */
+    /** The capabilities declared on the endpoint before this one. */
     readonly capabilities: readonly Declared[];
 }
 export type Properties = Record<string, PropertyDescriptor<any>>;

src/ActionMapping.ts

@@ -1,41 +0,0 @@
-export enum AlexaActions {
-  Open = "Alexa.Actions.Open",
-  Close = "Alexa.Actions.Close",
-  Raise = "Alexa.Actions.Raise",
-  Lower = "Alexa.Actions.Lower",
-  SetEcoOn = "Alexa.Actions.SetEcoOn",
-  SetEcoOff = "Alexa.Actions.SetEcoOff",
-}
-
-interface Directive {
-  name: string;
-  payload?: string;
-}
-
-export class ActionMapping {
-  type: string = "ActionsToDirective";
-  actions: AlexaActions[];
-  directive: Directive;
-
-  constructor(
-    actions: AlexaActions[],
-    directiveName: string,
-    directivePayload?: string
-  ) {
-    this.actions = actions;
-    this.directive = {
-      name: directiveName,
-    };
-    if (directivePayload) {
-      this.directive.payload = directivePayload;
-    }
-  }
-
-  toJSON(): object {
-    return {
-      "@type": this.type,
-      actions: this.actions,
-      directive: this.directive,
-    };
-  }
-}

src/Alex2Node.ts

@@ -1,10 +1,12 @@
 // mqtt reaches Node as CommonJS: the default import works from both builds, a named one needs Node to detect it.
 import mqtt from "mqtt";
 import type { MqttClient, IClientOptions } from "mqtt";
-import Device from "./Device.js";
+import Device from "./device/Device.js";
+import type { EndpointDefinition, EndpointJson } from "./device/Device.js";
+import { checkEndpoint } from "./device/validate.js";
 import { EventEmitter } from "events";
-import { DisplayCategory } from "./DisplayCategory.js";
-import { AlexaInterfaceType } from "./AlexaInterface.js";
+import { DisplayCategory } from "./compat/enums.js";
+import { DeclarationError } from "./registry/types.js";
 
 /** Optional settings for the bridge (1.5.1). Everything has the 1.4.0 behaviour as its default. */
 export interface Alex2MQTTOptions {
@@ -14,10 +16,21 @@ export interface Alex2MQTTOptions {
   mqtt?: IClientOptions;
   /** Where log lines go. Default: console (only when debugLogging is on). */
   log?: (message: string, detail?: unknown) => void;
+  /**
+   * false: discovery does not list the Alexa interface on the endpoints. Default: every endpoint ends with
+   * { type: "AlexaInterface", interface: "Alexa", version: "3" }, which Amazon requires and 1.x left out.
+   */
+  alexaInterface?: boolean;
 }
 
 export const DEFAULT_HOST = "mqtt://Alex2MQTT.stormysdream.club:1883";
 
+// What addDevice() copies from the definition to the device
+const DESCRIBED = [
+  "description", "manufacturerName", "manufacturer", "model", "serialNumber", "firmwareVersion", "softwareVersion",
+  "customIdentifier", "cookie",
+];
+
 /**
  * The Alexa-to-MQTT bridge: one broker connection for a user's root topic, a set of registered devices, discovery and
  * directive dispatch.
@@ -37,6 +50,8 @@ class Alex2MQTT extends EventEmitter {
   private devices: Device[] = [];
   private MqttHost: string;
   private options: Alex2MQTTOptions;
+  // The lines of check() that were logged. Discovery comes every few minutes: a line is logged once.
+  private logged = new Set<string>();
   /** true while the broker connection is up. */
   public connected = false;
   /** ISO time of the last discovery request answered, null before the first. */
@@ -98,12 +113,8 @@ class Alex2MQTT extends EventEmitter {
       this.log(`MQTT Message Received`, { topic, payload: message.toString() });
       if (topic == `${this.rootTopic}/discover`) {
         this.log("Discovery request received, getting device json...");
-        const deviceArray = this.devices.map((device) => device.getJSON());
+        const deviceArray = this.describeDevices();
         this.lastDiscoveryAt = new Date().toISOString();
-        for (const device of this.devices) // a capability the library has no property list for goes out with supported: []
-          for (const cap of device.getCapabilities())
-            if (cap.getProps().length === 0 && cap.getType() !== AlexaInterfaceType.SCENE_CONTROLLER)
-              this.log(`${device.endpointId}: no property list known for ${cap.getTypeString()}, discovery lists it with no supported properties`);
         this.client!.publish(topic + "_r", JSON.stringify(deviceArray), (err) => {
           if (err) { this.fail(err); return; }
           this.log(`Discovery payloads published to ${topic + "_r"}`, deviceArray);
@@ -138,6 +149,25 @@ class Alex2MQTT extends EventEmitter {
     });
   }
 
+  // The endpoint objects of a discovery answer. What check() says about a device is logged, each line once. A device
+  // that cannot be described is left out and reported as an error: the others are still announced.
+  private describeDevices(): EndpointJson[] {
+    const endpoints: EndpointJson[] = [];
+    for (const device of this.devices) {
+      try {
+        endpoints.push(device.getJSON());
+        for (const line of device.check()) {
+          if (this.logged.has(line)) continue;
+          this.logged.add(line);
+          this.log(`warning: ${line}`);
+        }
+      } catch (err) {
+        this.fail(new Error(`${device.endpointId} is not in the discovery answer: ${err instanceof Error ? err.message : err}`));
+      }
+    }
+    return endpoints;
+  }
+
   /** Close the broker connection (resolves once closed). The devices stay registered; connect() again reuses them. */
   disconnect(): Promise<void> {
     return new Promise((resolve) => {
@@ -149,10 +179,38 @@ class Alex2MQTT extends EventEmitter {
     });
   }
 
+  /**
+   * Declare a device:
+   *
+   *   const blinds = bridge.addDevice({ endpointId: "bedroom-blinds", name: "Bedroom Blinds",
+   *     categories: ["INTERIOR_BLIND"], manufacturerName: "Acme", description: "Roller blind by Acme" });
+   *
+   * Throws a DeclarationError when Alexa would reject the endpoint (an endpointId with a slash, a name with
+   * punctuation) or when the endpointId is registered already. Discovery lists Alexa.EndpointHealth for the device
+   * unless endpointHealth is false.
+   */
+  addDevice(definition: EndpointDefinition): Device {
+    if (!this.client) {
+      throw new Error("Must call connect before creating devices");
+    }
+    const { endpointId, name, categories, endpointHealth, ...described } = definition;
+    // Without categories the device would take LIGHT, the default of registerDevice: here it is a mistake
+    const device = new Device(this.client, this.rootTopic, name, endpointId, (categories ?? []) as DisplayCategory[]);
+    for (const [field, value] of Object.entries(described)) {
+      if (!DESCRIBED.includes(field)) throw new DeclarationError({ endpointId }, `${field} is not a field of an endpoint`);
+      if (value !== undefined) Object.assign(device, { [field]: value });
+    }
+    checkEndpoint(device.getJSON());
+    const existing = this.getDevice(endpointId);
+    if (existing) throw new DeclarationError({ endpointId }, `is registered already, as "${existing.name}"`);
+    this.register(device, endpointHealth !== false);
+    return device;
+  }
+
   registerDevice(
     name: string,
     endpointId: string,
-    displayCategory: DisplayCategory | DisplayCategory[] | null
+    displayCategory?: DisplayCategory | DisplayCategory[] | null
   ): Device {
     if (!this.client) {
       throw new Error("Must call connect before creating devices");
@@ -164,23 +222,17 @@ class Alex2MQTT extends EventEmitter {
       return existing;
     }
     this.log(`Creating new device with endpoint: ${endpointId}`);
-    const normalizedCategory =
-      displayCategory === null
-        ? [DisplayCategory.LIGHT]
-        : Array.isArray(displayCategory)
-        ? displayCategory
-        : [displayCategory || DisplayCategory.LIGHT];
+    const normalizedCategory = Array.isArray(displayCategory) ? displayCategory : [displayCategory || DisplayCategory.LIGHT];
+    const device = new Device(this.client, this.rootTopic, name, endpointId, normalizedCategory);
+    this.register(device, false);
+    return device;
+  }
 
-    const device = new Device(
-      this.client!,
-      this.rootTopic,
-      name,
-      endpointId,
-      normalizedCategory
-    );
+  private register(device: Device, endpointHealth: boolean): void {
+    device.alexaInterface = this.options.alexaInterface !== false;
+    device.endpointHealth = endpointHealth;
     device.onPublishError = (err) => this.fail(err); // a failed publish is an "error" event (when listened to), never a rejected send()
     this.devices.push(device);
-    return device;
   }
 
   /** Forget a device (its listeners with it). Returns false when there was none. */

src/AlexaStatusMessage.ts

@@ -1,12 +1,8 @@
 import { randomUUID } from "crypto";
-import { AlexaInterfaceType } from "./AlexaInterface.js";
+import { AlexaInterfaceType } from "./compat/enums.js";
+import type { EndpointHealth, PowerController } from "./compat/enums.js";
 import type { MqttClient } from "mqtt";
 
-export enum EndpointHealth {
-  OK = "OK",
-  UNREACHABLE = "UNREACHABLE",
-}
-
 export enum ThermostatMode {
   OFF = "OFF",
   HEAT = "HEAT",
@@ -16,11 +12,6 @@ export enum ThermostatMode {
   CUSTOM = "CUSTOM",
 }
 
-export enum PowerController {
-  ON = "ON",
-  OFF = "OFF",
-}
-
 export enum TemperatureSensorScale {
   CELSIUS = "CELSIUS",
   FAHRENHEIT = "FAHRENHEIT",

src/Device.ts

@@ -1,182 +0,0 @@
-import { AlexaInterface } from "./AlexaInterface.js";
-import type { AlexaInterfaceType } from "./AlexaInterface.js";
-import { DisplayCategory } from "./DisplayCategory.js";
-import { EventEmitter } from "events";
-import { randomUUID } from "crypto";
-import type { MqttClient } from "mqtt";
-import { AlexaStatusMessage } from "./AlexaStatusMessage.js";
-import type { ChangeCause } from "./AlexaStatusMessage.js";
-import { AlexaErrorResponse } from "./AlexaErrorResponse.js";
-
-class Device extends EventEmitter {
-  protected softwareVersion: string = "1.0.0";
-  private capabilities: AlexaInterface[] = [];
-  /** Where a failed publish from this device or a message it built is reported; Alex2MQTT sets it (1.5.2). */
-  public onPublishError?: (err: Error) => void;
-
-  constructor(
-    private mqttClient: MqttClient,
-    private rootTopic: string,
-    public name: string,
-    public endpointId: string,
-    public displayCategory: Array<DisplayCategory> | null,
-    public description: string = "Alexa to Node.js bridge",
-    public manufacturerName: string = "Alex2Node",
-    public manufacturer: string = "Alex2Node",
-    public model: string = "Alex2Node_v1.0.0"
-  ) {
-    super();
-  }
-
-  /** Internal (1.5.2): Alex2MQTT.connect() re-binds every registered device to its new broker client after a disconnect(). */
-  setMqttClient(client: MqttClient): void {
-    this.mqttClient = client;
-  }
-
-  getName(): string {
-    return this.name;
-  }
-
-  setName(name: string): void {
-    this.name = name;
-  }
-
-  getEndpointId(): string {
-    return this.endpointId;
-  }
-
-  setDisplayCategory(category: DisplayCategory | DisplayCategory[]): void {
-    this.displayCategory = Array.isArray(category) ? category : [category];
-  }
-
-  getDisplayCategory(): Array<DisplayCategory> {
-    return this.displayCategory || [DisplayCategory.LIGHT];
-  }
-
-  setDescription(description: string): void {
-    this.description = description;
-  }
-
-  getDescription(): string {
-    return this.description;
-  }
-  getErrorMessage(correlationToken: string): AlexaErrorResponse {
-    const msg = new AlexaErrorResponse(
-      correlationToken,
-      this.rootTopic,
-      this.endpointId,
-      this.mqttClient
-    );
-    msg.onPublishError = this.onPublishError;
-    return msg;
-  }
-  getStatusMessage(
-    correlationToken: string,
-    isResponse = false,
-    isDeferred = false
-  ): AlexaStatusMessage {
-    const msg = new AlexaStatusMessage(
-      correlationToken,
-      this.rootTopic,
-      this.endpointId,
-      this.mqttClient,
-      isResponse,
-      isDeferred
-    );
-    msg.onPublishError = this.onPublishError;
-    return msg;
-  }
-  /**
-   * A proactive Alexa.ChangeReport (1.5.1): add the changed properties (the default target), optionally
-   * .unchanged() then the others, and .send() - it goes to <root>/changeReport, which Alex2MQTT forwards to the Alexa
-   * event gateway with the user's token. Alexa only accepts it for capabilities registered with proactivelyReported.
-   */
-  getChangeReport(cause: ChangeCause = "PHYSICAL_INTERACTION"): AlexaStatusMessage {
-    const msg = new AlexaStatusMessage("", this.rootTopic, this.endpointId, this.mqttClient, false, false, cause);
-    msg.onPublishError = this.onPublishError;
-    return msg;
-  }
-  /**
-   * Alexa.SceneController: answer an Activate / Deactivate directive with ActivationStarted / DeactivationStarted
-   * (1.5.1). Resolves with the topic published to, or "" when the publish failed (never rejects, 1.5.2).
-   */
-  sendSceneResponse(correlationToken: string, activated: boolean, cause: ChangeCause = "VOICE_INTERACTION", sendAsync = false): Promise<string> {
-    const payload = {
-      context: {},
-      event: {
-        header: { namespace: "Alexa.SceneController", name: activated ? "ActivationStarted" : "DeactivationStarted", messageId: randomUUID(), correlationToken, payloadVersion: "3" },
-        endpoint: { endpointId: this.endpointId },
-        payload: { cause: { type: cause }, timestamp: new Date().toISOString() },
-      },
-    };
-    const topic = `${this.rootTopic}/${this.endpointId}/${sendAsync ? "deferredResponse" : "alexaResponce"}`;
-    return new Promise((resolve) => {
-      this.mqttClient.publish(topic, JSON.stringify(payload), (err) => {
-        if (!err) return resolve(topic);
-        if (this.onPublishError) this.onPublishError(err); // -> the bridge's "error" event (when somebody listens)
-        resolve(""); // 1.5.1 rejected here, and an un-caught send() then killed the host on any broker hiccup
-      });
-    });
-  }
-  getCapabilities(): AlexaInterface[] {
-    return this.capabilities.slice();
-  }
-  setManufacturerName(name: string): void {
-    this.manufacturerName = name;
-  }
-
-  getManufacturerName(): string {
-    return this.manufacturerName;
-  }
-
-  setManufacturer(manufacturer: string): void {
-    this.manufacturer = manufacturer;
-  }
-
-  getManufacturer(): string {
-    return this.manufacturer;
-  }
-
-  setModel(model: string): void {
-    this.model = model;
-  }
-
-  getModel(): string {
-    return this.model;
-  }
-
-  getSoftwareVersion(): string {
-    return this.softwareVersion;
-  }
-
-  /** Add a capability. 1.5.1: options.retrievable / proactivelyReported / instance (a change report needs proactivelyReported). */
-  addCapability(type: AlexaInterfaceType, options: { retrievable?: boolean; proactivelyReported?: boolean; instance?: string } = {}): AlexaInterface {
-    const newCapability = new AlexaInterface(type, options.retrievable ?? true, options.proactivelyReported ?? false, options.instance ?? "");
-    this.capabilities.push(newCapability);
-
-    // console.log(
-    //   `Created new interface with type: ${newCapability.getTypeString()}`
-    // );
-    return newCapability;
-  }
-  getJSON(): Record<string, any> {
-    return {
-      endpointId: this.endpointId,
-      friendlyName: this.name,
-      description: this.description,
-      manufacturerName: this.manufacturerName,
-      displayCategories: this.getDisplayCategory(),
-      additionalAttributes: {
-        manufacturer: this.manufacturer,
-        model: this.model,
-        serialNumber: "Alex2Node",
-        firmwareVersion: "1.0.0",
-        softwareVersion: this.softwareVersion,
-        customIdentifier: "Alex2Node",
-      },
-      capabilities: this.capabilities.map((cap) => cap.getJSON()),
-    };
-  }
-}
-
-export default Device;

src/DisplayCategory.ts

@@ -1,60 +0,0 @@
-export enum DisplayCategory {
-  ACTIVITY_TRIGGER = "ACTIVITY_TRIGGER",
-  AIR_CONDITIONER = "AIR_CONDITIONER",
-  AIR_FRESHENER = "AIR_FRESHENER",
-  AIR_PURIFIER = "AIR_PURIFIER",
-  AIR_QUALITY_MONITOR = "AIR_QUALITY_MONITOR",
-  ALEXA_VOICE_ENABLED = "ALEXA_VOICE_ENABLED",
-  AUTO_ACCESSORY = "AUTO_ACCESSORY",
-  BLUETOOTH_SPEAKER = "BLUETOOTH_SPEAKER",
-  CAMERA = "CAMERA",
-  CHRISTMAS_TREE = "CHRISTMAS_TREE",
-  COFFEE_MAKER = "COFFEE_MAKER",
-  COMPUTER = "COMPUTER",
-  CONTACT_SENSOR = "CONTACT_SENSOR",
-  DISHWASHER = "DISHWASHER",
-  DOOR = "DOOR",
-  DOORBELL = "DOORBELL",
-  DRYER = "DRYER",
-  EXTERIOR_BLIND = "EXTERIOR_BLIND",
-  FAN = "FAN",
-  GAME_CONSOLE = "GAME_CONSOLE",
-  GARAGE_DOOR = "GARAGE_DOOR",
-  HEADPHONES = "HEADPHONES",
-  HUB = "HUB",
-  INTERIOR_BLIND = "INTERIOR_BLIND",
-  LAPTOP = "LAPTOP",
-  LIGHT = "LIGHT",
-  MICROWAVE = "MICROWAVE",
-  MOBILE_PHONE = "MOBILE_PHONE",
-  MOTION_SENSOR = "MOTION_SENSOR",
-  MUSIC_SYSTEM = "MUSIC_SYSTEM",
-  NETWORK_HARDWARE = "NETWORK_HARDWARE",
-  OTHER = "OTHER",
-  OVEN = "OVEN",
-  PHONE = "PHONE",
-  PRINTER = "PRINTER",
-  REMOTE = "REMOTE",
-  ROUTER = "ROUTER",
-  SCENE_TRIGGER = "SCENE_TRIGGER",
-  SCREEN = "SCREEN",
-  SECURITY_PANEL = "SECURITY_PANEL",
-  SECURITY_SYSTEM = "SECURITY_SYSTEM",
-  SLOW_COOKER = "SLOW_COOKER",
-  SMARTLOCK = "SMARTLOCK",
-  SMARTPLUG = "SMARTPLUG",
-  SPEAKER = "SPEAKER",
-  STREAMING_DEVICE = "STREAMING_DEVICE",
-  SWITCH = "SWITCH",
-  TABLET = "TABLET",
-  TEMPERATURE_SENSOR = "TEMPERATURE_SENSOR",
-  THERMOSTAT = "THERMOSTAT",
-  TV = "TV",
-  VACUUM_CLEANER = "VACUUM_CLEANER",
-  VACUUM = "VACUUM",
-  /** Not on the list of display categories any more; kept for 1.x callers. */
-  VEHICLE = "VEHICLE",
-  WASHER = "WASHER",
-  WATER_HEATER = "WATER_HEATER",
-  WEARABLE = "WEARABLE",
-}

src/compat/ActionMapping.ts

@@ -0,0 +1,52 @@
+import { DeclarationError } from "../registry/types.js";
+import type { ActionsToDirective } from "../registry/types.js";
+import type { AlexaActions } from "./enums.js";
+
+/**
+ * A semantics action mapping of 1.x: the phrases "open", "close", "raise", "lower" for one directive of the
+ * capability it is added to.
+ *
+ *   toggle.addActionMapping(new ActionMapping([AlexaActions.Close], "TurnOff"));
+ *   lift.addActionMapping(new ActionMapping([AlexaActions.Open], "SetRangeValue", { rangeValue: 100 }));
+ */
+export class ActionMapping {
+  type = "ActionsToDirective" as const;
+  actions: AlexaActions[];
+  directive: ActionsToDirective["directive"];
+  /** Set when the mapping was built in a way that 3.0 will refuse; the bridge logs it at the next discovery. */
+  readonly deprecation?: string;
+
+  /**
+   * directivePayload is the payload object of the directive (alexa-discovery-objects.html, "ActionMappings object").
+   * 1.x took a string and put it into discovery as one. A string that holds a JSON object is parsed; any other
+   * string throws a DeclarationError.
+   */
+  constructor(actions: AlexaActions[], directiveName: string, directivePayload?: Record<string, unknown> | string) {
+    this.actions = actions;
+    this.directive = { name: directiveName };
+    if (typeof directivePayload === "string") {
+      if (directivePayload === "") return;
+      this.directive.payload = objectIn(directivePayload, directiveName);
+      this.deprecation = `the payload of the action mapping for ${directiveName} is a JSON string, pass the object`;
+    } else if (directivePayload) {
+      this.directive.payload = directivePayload;
+    }
+  }
+
+  toJSON(): ActionsToDirective {
+    return { "@type": this.type, actions: this.actions, directive: this.directive };
+  }
+}
+
+function objectIn(text: string, directiveName: string): Record<string, unknown> {
+  let value: unknown;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    value = undefined;
+  }
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new DeclarationError({}, `the payload of the action mapping for ${directiveName} is an object, got the string ${JSON.stringify(text)}`);
+  }
+  return value as Record<string, unknown>;
+}

src/compat/AlexaInterface.ts

@@ -0,0 +1,82 @@
+import { Capability } from "../device/Capability.js";
+import type { CapabilityJson } from "../device/Capability.js";
+import { registry } from "../registry/index.js";
+import { text } from "../registry/resources.js";
+import type { Semantics } from "../registry/types.js";
+import type { ActionMapping } from "./ActionMapping.js";
+import type { AlexaInterfaceType } from "./enums.js";
+
+/** One ModeController mode as discovery lists it (configuration.supportedModes): the value plus its friendly names. */
+export interface SupportedMode {
+  value: string;
+  modeResources?: { friendlyNames: Array<{ "@type": string; value: { text?: string; locale?: string; assetId?: string } }> };
+}
+
+interface Options {
+  semantics?: Semantics;
+  supportedModes?: Array<string | SupportedMode>;
+}
+
+/**
+ * A capability as 1.x declares it: device.addCapability(type, options), then the add and set methods below. It is a
+ * Capability, so what the methods set reaches discovery the same way as the options of device.add(). Nothing is
+ * refused here except an interface name the registry does not have: what Alexa would reject is logged by the bridge
+ * when it answers a discovery.
+ */
+export class AlexaInterface extends Capability<any, any, Options> {
+  constructor(type: AlexaInterfaceType | string, retrievable = true, proactivelyReported = false, instance = "") {
+    super(registry.get(type), { retrievable, proactivelyReported, instance, options: {} });
+  }
+
+  /** The namespace of the interface, which is the value of its AlexaInterfaceType member. */
+  get type(): AlexaInterfaceType {
+    return this.descriptor.namespace as AlexaInterfaceType;
+  }
+
+  addActionMapping(mapping: ActionMapping): void {
+    const semantics = (this.options.semantics ??= {});
+    (semantics.actionMappings ??= []).push(mapping.toJSON());
+    if (mapping.deprecation) this.notes.push(mapping.deprecation);
+  }
+
+  addFriendlyName(name: string, locale: string): void {
+    this.friendlyNames.push(text(name, locale));
+  }
+
+  /** The modes of a ModeController, as { value, modeResources } objects. */
+  addSupportedModes(modes: Array<string | SupportedMode>): void {
+    this.options.supportedModes = modes;
+  }
+
+  setInstance(name: string): void {
+    this.instance = name;
+  }
+
+  getType(): AlexaInterfaceType {
+    return this.type;
+  }
+
+  /** @deprecated The same as getType(). */
+  getTypeString(): string {
+    return this.type;
+  }
+
+  /** @deprecated Read descriptor.version. */
+  getVersion(): string {
+    return this.descriptor.version;
+  }
+
+  /** @deprecated Read the keys of descriptor.properties. */
+  getProps(): string[] {
+    return Object.keys(this.descriptor.properties);
+  }
+
+  getJSON(): CapabilityJson {
+    return super.toJSON();
+  }
+
+  // 1.x callers corrected the discovery JSON by replacing getJSON on the object: discovery goes through it
+  toJSON(): CapabilityJson {
+    return this.getJSON();
+  }
+}

src/compat/enums.ts

@@ -1,6 +1,8 @@
-import type { ActionMapping } from "./ActionMapping.js";
-import { registry } from "./registry/index.js";
+// The enums of 1.x, under their 1.x names.
+import { EndpointHealth as EndpointHealthInterface } from "../registry/interfaces/EndpointHealth.js";
+import { PowerController as PowerControllerInterface } from "../registry/interfaces/PowerController.js";
 
+/** Every interface name of 1.x. registry.get() takes a member as it takes the namespace, which is its value. */
 export enum AlexaInterfaceType {
   APPLICATION_STATE_REPORTER = "Alexa.ApplicationStateReporter",
   AUDIO_PLAY_QUEUE = "Alexa.Audio.PlayQueue",
@@ -71,115 +73,96 @@ export enum AlexaInterfaceType {
   USER_PREFERENCE = "Alexa.UserPreference",
   VIDEO_RECORDER = "Alexa.VideoRecorder",
   WAKE_ON_LAN_CONTROLLER = "Alexa.WakeOnLANController",
+  /** Not an interface: declaring it throws a DeclarationError. Kept because 1.x had it. */
   UNKNOWN = "UNKNOWN",
 }
 
-interface FriendlyName {
-  text: string;
-  locale: string;
+export enum DisplayCategory {
+  ACTIVITY_TRIGGER = "ACTIVITY_TRIGGER",
+  AIR_CONDITIONER = "AIR_CONDITIONER",
+  AIR_FRESHENER = "AIR_FRESHENER",
+  AIR_PURIFIER = "AIR_PURIFIER",
+  AIR_QUALITY_MONITOR = "AIR_QUALITY_MONITOR",
+  ALEXA_VOICE_ENABLED = "ALEXA_VOICE_ENABLED",
+  AUTO_ACCESSORY = "AUTO_ACCESSORY",
+  BLUETOOTH_SPEAKER = "BLUETOOTH_SPEAKER",
+  CAMERA = "CAMERA",
+  CHRISTMAS_TREE = "CHRISTMAS_TREE",
+  COFFEE_MAKER = "COFFEE_MAKER",
+  COMPUTER = "COMPUTER",
+  CONTACT_SENSOR = "CONTACT_SENSOR",
+  DISHWASHER = "DISHWASHER",
+  DOOR = "DOOR",
+  DOORBELL = "DOORBELL",
+  DRYER = "DRYER",
+  EXTERIOR_BLIND = "EXTERIOR_BLIND",
+  FAN = "FAN",
+  GAME_CONSOLE = "GAME_CONSOLE",
+  GARAGE_DOOR = "GARAGE_DOOR",
+  HEADPHONES = "HEADPHONES",
+  HUB = "HUB",
+  INTERIOR_BLIND = "INTERIOR_BLIND",
+  LAPTOP = "LAPTOP",
+  LIGHT = "LIGHT",
+  MICROWAVE = "MICROWAVE",
+  MOBILE_PHONE = "MOBILE_PHONE",
+  MOTION_SENSOR = "MOTION_SENSOR",
+  MUSIC_SYSTEM = "MUSIC_SYSTEM",
+  NETWORK_HARDWARE = "NETWORK_HARDWARE",
+  OTHER = "OTHER",
+  OVEN = "OVEN",
+  PHONE = "PHONE",
+  PRINTER = "PRINTER",
+  REMOTE = "REMOTE",
+  ROUTER = "ROUTER",
+  SCENE_TRIGGER = "SCENE_TRIGGER",
+  SCREEN = "SCREEN",
+  SECURITY_PANEL = "SECURITY_PANEL",
+  SECURITY_SYSTEM = "SECURITY_SYSTEM",
+  SLOW_COOKER = "SLOW_COOKER",
+  SMARTLOCK = "SMARTLOCK",
+  SMARTPLUG = "SMARTPLUG",
+  SPEAKER = "SPEAKER",
+  STREAMING_DEVICE = "STREAMING_DEVICE",
+  SWITCH = "SWITCH",
+  TABLET = "TABLET",
+  TEMPERATURE_SENSOR = "TEMPERATURE_SENSOR",
+  THERMOSTAT = "THERMOSTAT",
+  TV = "TV",
+  VACUUM_CLEANER = "VACUUM_CLEANER",
+  VACUUM = "VACUUM",
+  /** Not on the list of display categories any more; kept for 1.x callers. */
+  VEHICLE = "VEHICLE",
+  WASHER = "WASHER",
+  WATER_HEATER = "WATER_HEATER",
+  WEARABLE = "WEARABLE",
 }
 
-/** One ModeController mode as discovery lists it (configuration.supportedModes): the value plus its friendly names. */
-export interface SupportedMode {
-  value: string;
-  modeResources?: { friendlyNames: Array<{ "@type": string; value: { text?: string; locale?: string; assetId?: string } }> };
+export enum AlexaActions {
+  Open = "Alexa.Actions.Open",
+  Close = "Alexa.Actions.Close",
+  Raise = "Alexa.Actions.Raise",
+  Lower = "Alexa.Actions.Lower",
+  SetEcoOn = "Alexa.Actions.SetEcoOn",
+  SetEcoOff = "Alexa.Actions.SetEcoOff",
 }
 
-export class AlexaInterface {
-  private friendlyNames: FriendlyName[] = [];
-  private actionMappings: ActionMapping[] = [];
-  private supportedModes: Array<string | SupportedMode> = [];
+/** The values of powerState and toggleState. */
+export const PowerState = { ON: "ON", OFF: "OFF" } as const;
+export type PowerState = (typeof PowerState)[keyof typeof PowerState];
 
-  constructor(
-    public type: AlexaInterfaceType,
-    public retrievable: boolean = true,
-    public proactivelyReported: boolean = false,
-    public instance = ""
-  ) {}
+const Connectivity = { OK: "OK", UNREACHABLE: "UNREACHABLE" } as const;
 
-  addActionMapping(mapping: ActionMapping): void {
-    this.actionMappings.push(mapping);
-  }
+// PowerController and EndpointHealth were enums in 1.x and are the names of two interfaces. One export serves both:
+// the descriptor, which also has the members of the enum, and a type of the same name for the values.
 
-  addFriendlyName(name: string, locale: string): void {
-    this.friendlyNames.push({ text: name, locale });
-  }
-  /** The modes of a ModeController: { value, modeResources } objects as Alexa wants them (plain strings pass through as given). */
-  addSupportedModes(modes: Array<string | SupportedMode>): void {
-    this.supportedModes = modes;
-  }
-  setInstance(name: string): void {
-    this.instance = name;
-  }
+/**
+ * The Alexa.PowerController interface, for device.add(). PowerController.ON and PowerController.OFF are the 1.x enum
+ * of power states and stay until 3.0: PowerState has the same two members.
+ */
+export const PowerController = Object.assign(PowerControllerInterface, PowerState);
+export type PowerController = PowerState;
 
-  getType(): AlexaInterfaceType {
-    return this.type;
-  }
-
-  getTypeString(): string {
-    return this.type;
-  }
-
-  /** The version of the interface, from its descriptor. "UNKNOWN" for a name the registry does not have. */
-  getVersion(): string {
-    return registry.has(this.type) ? registry.get(this.type).version : "UNKNOWN";
-  }
-
-  /** The names of the properties the interface reports, from its descriptor. */
-  getProps(): string[] {
-    return registry.has(this.type) ? Object.keys(registry.get(this.type).properties) : [];
-  }
-
-  getJSON(): object {
-    const doc: any = {
-      interface: this.getTypeString(),
-      version: this.getVersion(),
-      type: "AlexaInterface",
-      properties: {
-        retrievable: this.retrievable,
-        proactivelyReported: this.proactivelyReported,
-        supported: this.getProps().map(name => ({ name })),
-      },
-    };
-    if (this.type == AlexaInterfaceType.SCENE_CONTROLLER) {
-      // Alexa.SceneController v3 carries no properties block: supportsDeactivation + proactivelyReported at the top level
-      delete doc.properties;
-      doc.supportsDeactivation = true;
-      doc.proactivelyReported = this.proactivelyReported;
-    } else if(this.type==AlexaInterfaceType.THERMOSTAT_CONTROLLER){
-      doc.configuration={
-        "supportedModes": ["HEAT", "COOL", "AUTO", "OFF"],
-        "supportsScheduling": false
-      }
-    }else if (this.supportedModes.length > 0) {
-      doc["configuration"] = {
-        ordered:true,
-        supportedModes: this.supportedModes,
-      };
-    }
-    if (this.instance) {
-      doc.instance = this.instance;
-    }
-    if (this.friendlyNames.length > 0) {
-      const capabilityResources = doc["capabilityResources"] || {};
-      const friendlyNamesArray = capabilityResources["friendlyNames"] || [];
-      this.friendlyNames.forEach((fn) => {
-        const friendlyNameObj: any = { "@type": "text" };
-        friendlyNameObj["value"] = {
-          text: fn.text,
-          locale: fn.locale,
-        };
-        friendlyNamesArray.push(friendlyNameObj);
-      });
-      capabilityResources.friendlyNames=friendlyNamesArray
-      doc["capabilityResources"] = capabilityResources;
-    }
-    if (this.actionMappings.length > 0) {
-      doc.semantics = {
-        actionMappings: this.actionMappings.map((am) => am.toJSON()),
-      };
-    }
-
-    return doc;
-  }
-}
+/** The Alexa.EndpointHealth interface, for device.add(). EndpointHealth.OK and EndpointHealth.UNREACHABLE are the 1.x enum of connectivity values. */
+export const EndpointHealth = Object.assign(EndpointHealthInterface, Connectivity);
+export type EndpointHealth = (typeof Connectivity)[keyof typeof Connectivity];

src/device/Capability.ts

@@ -0,0 +1,116 @@
+import { s } from "../registry/schema.js";
+import type {
+  Declared, Directives, InterfaceDescriptor, Label, Properties, Semantics,
+} from "../registry/types.js";
+
+/** What a declaration can set for any interface. */
+export interface CommonOptions {
+  /** The name of the instance of a generic controller: "Blind.Lift", "Fan.Speed". */
+  instance?: string;
+  /** What the user calls the instance; the first name is the one the Alexa app shows. */
+  friendlyNames?: Label[];
+  /** The properties are in the answer to ReportState. Default: true. */
+  retrievable?: boolean;
+  /** A change of the properties is sent to Alexa as a ChangeReport. Default: false. */
+  proactivelyReported?: boolean;
+  /** The user can ask for the properties and cannot set them. Left out of discovery when not given. */
+  nonControllable?: boolean;
+}
+
+/** The same as a schema. The friendly names are checked with the instance, by the rules of the interface. */
+export const commonOptions = s.object({
+  instance: s.optional(s.string()),
+  friendlyNames: s.optional(s.array(s.unknown())),
+  retrievable: s.optional(s.boolean()),
+  proactivelyReported: s.optional(s.boolean()),
+  nonControllable: s.optional(s.boolean()),
+});
+
+type Naming<I extends boolean> = I extends true
+  ? { instance: string; friendlyNames: Label[] }
+  : { instance?: string; friendlyNames?: Label[] };
+
+/** The options of device.add() for one interface: its own, and the ones every interface has. */
+export type Declaration<O, I extends boolean> = O & Omit<CommonOptions, "instance" | "friendlyNames"> & Naming<I>;
+
+/** A capability object of a discovery answer (alexa-discovery-objects.html, "Capability object"). */
+export interface CapabilityJson {
+  type: "AlexaInterface";
+  interface: string;
+  instance?: string;
+  version: string;
+  properties?: {
+    supported: Array<{ name: string }>;
+    proactivelyReported: boolean;
+    retrievable: boolean;
+    nonControllable?: boolean;
+  };
+  capabilityResources?: { friendlyNames: Label[] };
+  configuration?: Record<string, unknown>;
+  configurations?: Record<string, unknown>;
+  semantics?: Semantics;
+  [field: string]: unknown;
+}
+
+/** One interface as an endpoint declares it: the descriptor, and what the declaration says about this endpoint. */
+export class Capability<P extends Properties = Properties, D extends Directives = Directives, O = {}> implements Declared<O> {
+  /** The endpoint the capability is declared on; the device sets it. */
+  endpointId = "";
+  /** "" for an interface without instances. */
+  instance: string;
+  friendlyNames: Label[];
+  retrievable: boolean;
+  proactivelyReported: boolean;
+  nonControllable?: boolean;
+  /** The options of the interface: a range, the supported modes, the semantics. */
+  options: O;
+  /** What the bridge logs about the declaration, once, when it answers a discovery. */
+  readonly notes: string[] = [];
+
+  constructor(readonly descriptor: InterfaceDescriptor<P, D, O, boolean>, declared: CommonOptions & { options: O }) {
+    this.instance = declared.instance ?? "";
+    this.friendlyNames = declared.friendlyNames ?? [];
+    this.retrievable = declared.retrievable ?? true;
+    this.proactivelyReported = declared.proactivelyReported ?? false;
+    this.nonControllable = declared.nonControllable;
+    this.options = declared.options;
+  }
+
+  get namespace(): string {
+    return this.descriptor.namespace;
+  }
+
+  /** Mappings of "open", "close", "raise", "lower" and of states, when the declaration has any. */
+  get semantics(): Semantics | undefined {
+    const { semantics } = this.options as { semantics?: Semantics };
+    const mapped = (semantics?.actionMappings?.length ?? 0) + (semantics?.stateMappings?.length ?? 0);
+    return mapped > 0 ? semantics : undefined;
+  }
+
+  /** The capability object for discovery, its fields in the order of the example on alexa-discovery-objects.html. */
+  toJSON(): CapabilityJson {
+    const { descriptor, semantics } = this;
+    const extras = descriptor.discovery ? descriptor.discovery(this) : {};
+    const json: CapabilityJson = {
+      type: "AlexaInterface",
+      interface: descriptor.namespace,
+      ...(this.instance ? { instance: this.instance } : {}),
+      version: descriptor.version,
+    };
+    if (extras.properties !== false) {
+      json.properties = {
+        supported: Object.keys(descriptor.properties).map((name) => ({ name })),
+        proactivelyReported: this.proactivelyReported,
+        retrievable: this.retrievable,
+      };
+      if (this.nonControllable !== undefined) json.properties.nonControllable = this.nonControllable;
+    }
+    if (this.friendlyNames.length > 0) json.capabilityResources = { friendlyNames: this.friendlyNames };
+    if (extras.configuration) json.configuration = extras.configuration;
+    if (extras.configurations) json.configurations = extras.configurations;
+    if (semantics) json.semantics = semantics;
+    return { ...json, ...extras.topLevel };
+  }
+}
+
+export type AnyCapability = Capability<any, any, any>;

src/device/Device.ts

@@ -0,0 +1,348 @@
+import { EventEmitter } from "events";
+import { randomUUID } from "crypto";
+import type { MqttClient } from "mqtt";
+import { AlexaErrorResponse } from "../AlexaErrorResponse.js";
+import { AlexaStatusMessage } from "../AlexaStatusMessage.js";
+import type { ChangeCause } from "../AlexaStatusMessage.js";
+import { AlexaInterface } from "../compat/AlexaInterface.js";
+import { DisplayCategory } from "../compat/enums.js";
+import type { AlexaInterfaceType } from "../compat/enums.js";
+import type { DisplayCategoryName } from "../registry/catalog.js";
+import { Alexa } from "../registry/interfaces/Alexa.js";
+import { EndpointHealth } from "../registry/interfaces/EndpointHealth.js";
+import { SchemaError } from "../registry/schema.js";
+import { DeclarationError } from "../registry/types.js";
+import type { Directives, EndpointView, InterfaceDescriptor, Label, Properties } from "../registry/types.js";
+import { Capability, commonOptions } from "./Capability.js";
+import type { AnyCapability, CapabilityJson, Declaration } from "./Capability.js";
+import { checkCapability, checkCapabilityCount, checkEndpoint } from "./validate.js";
+import type { EndpointFields } from "./validate.js";
+
+/** An endpoint as bridge.addDevice() takes it. */
+export interface EndpointDefinition {
+  /** Up to 256 letters, digits, spaces and _ - = # ; : ? @ &. The same id at every discovery. */
+  endpointId: string;
+  /** What the user calls the device: letters, digits and spaces. */
+  name: string;
+  /** The first one is the category the Alexa app shows the device under. */
+  categories: Array<DisplayCategoryName | DisplayCategory>;
+  /** Shown in the Alexa app, up to 128 characters. Default: "Alexa to Node.js bridge". */
+  description?: string;
+  /** Up to 128 characters. Default: "Alex2Node". */
+  manufacturerName?: string;
+  // additionalAttributes: Alexa tells two devices apart by them when two add-ons report the same one
+  manufacturer?: string;
+  model?: string;
+  serialNumber?: string;
+  firmwareVersion?: string;
+  softwareVersion?: string;
+  customIdentifier?: string;
+  /** Returned with every directive to the endpoint. Up to 5000 bytes; not a place for state. */
+  cookie?: Record<string, string>;
+  /** false: the device gets no Alexa.EndpointHealth unless it declares one. */
+  endpointHealth?: boolean;
+}
+
+/** An endpoint object of a discovery answer (alexa-discovery-objects.html, "Endpoint object"). */
+export interface EndpointJson extends EndpointFields {
+  capabilities: CapabilityJson[];
+}
+
+// device.add(PowerController) needs no options, device.add(RangeController) cannot do without
+type DeclarationArguments<O, I extends boolean> = {} extends Declaration<O, I>
+  ? [options?: Declaration<O, I>]
+  : [options: Declaration<O, I>];
+
+class Device extends EventEmitter {
+  public softwareVersion = "1.0.0";
+  public serialNumber = "Alex2Node";
+  public firmwareVersion = "1.0.0";
+  public customIdentifier = "Alex2Node";
+  public cookie?: Record<string, string>;
+  /**
+   * Discovery lists the Alexa interface on the endpoint (alexa-interface.html: "You must explicitly identify your
+   * support for the Alexa interface"). The bridge sets it from its alexaInterface option.
+   */
+  public alexaInterface = true;
+  /**
+   * Discovery lists Alexa.EndpointHealth when the device did not declare it and is not a scene. On for a device of
+   * bridge.addDevice(), off for one of registerDevice(), which is announced as 1.x announced it.
+   */
+  public endpointHealth = false;
+  private capabilities: AnyCapability[] = [];
+  /** Where a failed publish from this device or a message it built is reported; Alex2MQTT sets it (1.5.2). */
+  public onPublishError?: (err: Error) => void;
+
+  constructor(
+    private mqttClient: MqttClient,
+    private rootTopic: string,
+    public name: string,
+    public endpointId: string,
+    public displayCategory: Array<DisplayCategory> | null,
+    public description: string = "Alexa to Node.js bridge",
+    public manufacturerName: string = "Alex2Node",
+    public manufacturer: string = "Alex2Node",
+    public model: string = "Alex2Node_v1.0.0"
+  ) {
+    super();
+  }
+
+  /** Internal (1.5.2): Alex2MQTT.connect() re-binds every registered device to its new broker client after a disconnect(). */
+  setMqttClient(client: MqttClient): void {
+    this.mqttClient = client;
+  }
+
+  getName(): string {
+    return this.name;
+  }
+
+  setName(name: string): void {
+    this.name = name;
+  }
+
+  getEndpointId(): string {
+    return this.endpointId;
+  }
+
+  setDisplayCategory(category: DisplayCategory | DisplayCategory[]): void {
+    this.displayCategory = Array.isArray(category) ? category : [category];
+  }
+
+  getDisplayCategory(): Array<DisplayCategory> {
+    return this.displayCategory || [DisplayCategory.LIGHT];
+  }
+
+  setDescription(description: string): void {
+    this.description = description;
+  }
+
+  getDescription(): string {
+    return this.description;
+  }
+  getErrorMessage(correlationToken: string): AlexaErrorResponse {
+    const msg = new AlexaErrorResponse(
+      correlationToken,
+      this.rootTopic,
+      this.endpointId,
+      this.mqttClient
+    );
+    msg.onPublishError = this.onPublishError;
+    return msg;
+  }
+  getStatusMessage(
+    correlationToken: string,
+    isResponse = false,
+    isDeferred = false
+  ): AlexaStatusMessage {
+    const msg = new AlexaStatusMessage(
+      correlationToken,
+      this.rootTopic,
+      this.endpointId,
+      this.mqttClient,
+      isResponse,
+      isDeferred
+    );
+    msg.onPublishError = this.onPublishError;
+    return msg;
+  }
+  /**
+   * A proactive Alexa.ChangeReport (1.5.1): add the changed properties (the default target), optionally
+   * .unchanged() then the others, and .send() - it goes to <root>/changeReport, which Alex2MQTT forwards to the Alexa
+   * event gateway with the user's token. Alexa only accepts it for capabilities registered with proactivelyReported.
+   */
+  getChangeReport(cause: ChangeCause = "PHYSICAL_INTERACTION"): AlexaStatusMessage {
+    const msg = new AlexaStatusMessage("", this.rootTopic, this.endpointId, this.mqttClient, false, false, cause);
+    msg.onPublishError = this.onPublishError;
+    return msg;
+  }
+  /**
+   * Alexa.SceneController: answer an Activate / Deactivate directive with ActivationStarted / DeactivationStarted
+   * (1.5.1). Resolves with the topic published to, or "" when the publish failed (never rejects, 1.5.2).
+   */
+  sendSceneResponse(correlationToken: string, activated: boolean, cause: ChangeCause = "VOICE_INTERACTION", sendAsync = false): Promise<string> {
+    const payload = {
+      context: {},
+      event: {
+        header: { namespace: "Alexa.SceneController", name: activated ? "ActivationStarted" : "DeactivationStarted", messageId: randomUUID(), correlationToken, payloadVersion: "3" },
+        endpoint: { endpointId: this.endpointId },
+        payload: { cause: { type: cause }, timestamp: new Date().toISOString() },
+      },
+    };
+    const topic = `${this.rootTopic}/${this.endpointId}/${sendAsync ? "deferredResponse" : "alexaResponce"}`;
+    return new Promise((resolve) => {
+      this.mqttClient.publish(topic, JSON.stringify(payload), (err) => {
+        if (!err) return resolve(topic);
+        if (this.onPublishError) this.onPublishError(err); // -> the bridge's "error" event (when somebody listens)
+        resolve(""); // 1.5.1 rejected here, and an un-caught send() then killed the host on any broker hiccup
+      });
+    });
+  }
+  /** The capabilities the device declared, in the order it declared them. */
+  getCapabilities(): AnyCapability[] {
+    return this.capabilities.slice();
+  }
+  setManufacturerName(name: string): void {
+    this.manufacturerName = name;
+  }
+
+  getManufacturerName(): string {
+    return this.manufacturerName;
+  }
+
+  setManufacturer(manufacturer: string): void {
+    this.manufacturer = manufacturer;
+  }
+
+  getManufacturer(): string {
+    return this.manufacturer;
+  }
+
+  setModel(model: string): void {
+    this.model = model;
+  }
+
+  getModel(): string {
+    return this.model;
+  }
+
+  getSoftwareVersion(): string {
+    return this.softwareVersion;
+  }
+
+  /**
+   * Declare an interface of the device:
+   *
+   *   lamp.add(PowerController, { proactivelyReported: true });
+   *   blinds.add(RangeController, { instance: "Blind.Lift", friendlyNames: [asset("Alexa.Setting.Opening")],
+   *     range: { min: 0, max: 100, precision: 1 } });
+   *
+   * Throws a DeclarationError that names the endpoint, the interface and the instance when Alexa would reject the
+   * capability; the device is then as it was before the call.
+   */
+  add<P extends Properties, D extends Directives, O, I extends boolean>(
+    descriptor: InterfaceDescriptor<P, D, O, I>,
+    ...[options]: DeclarationArguments<O, I>
+  ): Capability<P, D, O> {
+    const where = { endpointId: this.endpointId, namespace: descriptor.namespace, instance: "" };
+    if (options !== undefined && (typeof options !== "object" || options === null)) {
+      throw new DeclarationError(where, "the options of a declaration are an object");
+    }
+    try {
+      const { instance, friendlyNames, retrievable, proactivelyReported, nonControllable, ...given } = commonOptions.parse(options ?? {});
+      where.instance = instance ?? "";
+      const common = { instance, friendlyNames: friendlyNames as Label[] | undefined, retrievable, proactivelyReported, nonControllable };
+      const capability = new Capability(descriptor, { ...common, options: interfaceOptions(descriptor, given) });
+      capability.endpointId = this.endpointId;
+      checkCapability(capability, descriptor, this.view(this.capabilities));
+      checkCapabilityCount(this.endpointId, this.announced([...this.capabilities, capability]).length);
+      this.capabilities.push(capability);
+      return capability;
+    } catch (err) {
+      throw err instanceof SchemaError ? new DeclarationError(where, err.message) : err;
+    }
+  }
+
+  /**
+   * Declare an interface the 1.x way, by its name: options.retrievable / proactivelyReported / instance, then the
+   * add and set methods of the capability that is returned. Throws for a name that is not an interface. Anything
+   * else Alexa would reject is not refused here: check() lists it.
+   */
+  addCapability(type: AlexaInterfaceType | string, options: { retrievable?: boolean; proactivelyReported?: boolean; instance?: string } = {}): AlexaInterface {
+    let capability: AlexaInterface;
+    try {
+      capability = new AlexaInterface(type, options.retrievable ?? true, options.proactivelyReported ?? false, options.instance ?? "");
+    } catch (err) {
+      throw err instanceof DeclarationError ? new DeclarationError({ endpointId: this.endpointId }, err.problem) : err;
+    }
+    capability.endpointId = this.endpointId;
+    this.capabilities.push(capability);
+    return capability;
+  }
+
+  /**
+   * What Alexa would reject in the device as it is declared now, one line for each: a name with punctuation, an
+   * interface declared twice. Also what a capability noted about its declaration. Empty when there is nothing.
+   * The bridge logs the lines when it answers a discovery.
+   */
+  check(): string[] {
+    const lines: string[] = [];
+    const attempt = (rule: () => void): void => {
+      try {
+        rule();
+      } catch (err) {
+        if (!(err instanceof DeclarationError)) throw err;
+        lines.push(err.message);
+      }
+    };
+    attempt(() => checkEndpoint(this.fields()));
+    this.capabilities.forEach((capability, i) => {
+      capability.endpointId = this.endpointId;
+      attempt(() => checkCapability(capability, capability.descriptor, this.view(this.capabilities.slice(0, i))));
+      const notes = [...capability.notes];
+      const { tier, properties } = capability.descriptor;
+      if (tier === 3 && Object.keys(properties).length === 0 && capability.toJSON().properties) {
+        notes.push("no property list known, discovery lists it with no supported properties");
+      }
+      for (const note of notes) lines.push(new DeclarationError(capability, note).message);
+    });
+    attempt(() => checkCapabilityCount(this.endpointId, this.announced(this.capabilities).length));
+    return lines;
+  }
+
+  /** The endpoint object for discovery. */
+  getJSON(): EndpointJson {
+    return { ...this.fields(), capabilities: this.announced(this.capabilities).map((capability) => capability.toJSON()) };
+  }
+
+  private fields(): EndpointFields {
+    return {
+      endpointId: this.endpointId,
+      friendlyName: this.name,
+      description: this.description,
+      manufacturerName: this.manufacturerName,
+      displayCategories: this.getDisplayCategory(),
+      additionalAttributes: {
+        manufacturer: this.manufacturer,
+        model: this.model,
+        serialNumber: this.serialNumber,
+        firmwareVersion: this.firmwareVersion,
+        softwareVersion: this.softwareVersion,
+        customIdentifier: this.customIdentifier,
+      },
+      ...(this.cookie ? { cookie: this.cookie } : {}),
+    };
+  }
+
+  // The endpoint as the rules of a capability see it
+  private view(declaredBefore: readonly AnyCapability[]): EndpointView {
+    return {
+      endpointId: this.endpointId,
+      friendlyName: this.name,
+      description: this.description,
+      displayCategories: this.getDisplayCategory(),
+      capabilities: declaredBefore,
+    };
+  }
+
+  // What discovery lists: the declared capabilities, then the ones the library adds
+  private announced(declared: readonly AnyCapability[]): AnyCapability[] {
+    const has = (namespace: string): boolean => declared.some((capability) => capability.namespace === namespace);
+    const added: AnyCapability[] = [];
+    // alexa-scenecontroller.html, "Discovery": a scene is not a physical device and has no Alexa.EndpointHealth
+    if (this.endpointHealth && !has(EndpointHealth.namespace) && !has("Alexa.SceneController")) {
+      added.push(new Capability(EndpointHealth, { options: {} }));
+    }
+    if (this.alexaInterface && !has(Alexa.namespace)) added.push(new Capability(Alexa, { options: {} }));
+    return [...declared, ...added];
+  }
+}
+
+// The options of the interface itself, checked by the schema of its descriptor
+function interfaceOptions<O>(descriptor: InterfaceDescriptor<any, any, O, boolean>, given: Record<string, unknown>): O {
+  if (descriptor.options) return descriptor.options.parse(given);
+  const [unknown] = Object.keys(given);
+  if (unknown !== undefined) throw new SchemaError(unknown, "not an option of the interface");
+  return {} as O;
+}
+
+export default Device;

src/device/validate.ts

@@ -0,0 +1,135 @@
+// What Alexa rejects at discovery, checked where a device is declared. Alexa gives no reason when it drops an
+// endpoint: the user hears "no new devices found". Each rule names the page it is from.
+import { DISPLAY_CATEGORIES, LIMITS } from "../registry/catalog.js";
+import { labels, shownAs } from "../registry/resources.js";
+import { SchemaError } from "../registry/schema.js";
+import { DeclarationError } from "../registry/types.js";
+import type { AnyDescriptor, Declared, EndpointView, Label, Semantics } from "../registry/types.js";
+
+/** An endpoint as discovery sends it, without its capabilities. */
+export interface EndpointFields {
+  endpointId: string;
+  friendlyName: string;
+  description: string;
+  manufacturerName: string;
+  displayCategories: readonly string[];
+  additionalAttributes: Readonly<Record<string, string>>;
+  cookie?: Readonly<Record<string, string>>;
+}
+
+// alexa-discovery-objects.html, "Endpoint object details": "letters, numbers, spaces, and the following special
+// characters: _ - = # ; : ? @ &"
+const ENDPOINT_ID = /^[A-Za-z0-9 _\-=#;:?@&]+$/;
+// Same table: "alphanumeric characters and spaces". Letters of any script: Alexa speaks Hindi and Japanese too.
+const FRIENDLY_NAME = /^[\p{L}\p{M}\p{N} ]+$/u;
+
+const isText = (value: unknown): value is string => typeof value === "string" && value.length > 0;
+
+/** Throws the first rule of the Endpoint object that the fields break. */
+export function checkEndpoint(endpoint: EndpointFields): void {
+  const where = { endpointId: isText(endpoint.endpointId) ? endpoint.endpointId : undefined };
+  function refuse(problem: string): never {
+    throw new DeclarationError(where, problem);
+  }
+  const { endpointId, friendlyName, description, manufacturerName, displayCategories, additionalAttributes, cookie } = endpoint;
+
+  if (!isText(endpointId)) refuse("an endpoint needs an endpointId");
+  if (endpointId.length > LIMITS.endpointIdLength || !ENDPOINT_ID.test(endpointId)) {
+    refuse(`the endpointId takes up to ${LIMITS.endpointIdLength} letters, digits, spaces and _ - = # ; : ? @ &`);
+  }
+  if (!isText(friendlyName)) refuse("an endpoint needs a name");
+  if (friendlyName.length > LIMITS.friendlyNameLength || !FRIENDLY_NAME.test(friendlyName)) {
+    refuse(`the name ${JSON.stringify(friendlyName)} takes up to ${LIMITS.friendlyNameLength} letters, digits and spaces, no punctuation`);
+  }
+  if (!isText(manufacturerName) || manufacturerName.length > LIMITS.manufacturerNameLength) {
+    refuse(`the manufacturerName takes 1 to ${LIMITS.manufacturerNameLength} characters`);
+  }
+  if (!isText(description) || description.length > LIMITS.descriptionLength) {
+    refuse(`the description takes 1 to ${LIMITS.descriptionLength} characters`);
+  }
+
+  if (!Array.isArray(displayCategories) || displayCategories.length === 0) refuse("an endpoint needs a display category");
+  const known: readonly string[] = DISPLAY_CATEGORIES;
+  for (const category of displayCategories) {
+    if (!known.includes(category)) refuse(`${JSON.stringify(category)} is not a display category`);
+  }
+
+  for (const [name, value] of Object.entries(additionalAttributes)) {
+    if (typeof value !== "string" || value.length > LIMITS.additionalAttributeLength) {
+      refuse(`${name} takes up to ${LIMITS.additionalAttributeLength} characters`);
+    }
+  }
+  if (cookie !== undefined) {
+    const bytes = Buffer.byteLength(JSON.stringify(cookie) ?? "");
+    if (bytes > LIMITS.cookieBytes) refuse(`the cookie is ${bytes} bytes, ${LIMITS.cookieBytes} is the most`);
+  }
+}
+
+/** alexa-discovery.html, "Interface limits". count includes the capabilities the library adds. */
+export function checkCapabilityCount(endpointId: string, count: number): void {
+  if (count > LIMITS.capabilitiesPerEndpoint) {
+    throw new DeclarationError({ endpointId }, `${count} capabilities, an endpoint takes ${LIMITS.capabilitiesPerEndpoint}`);
+  }
+}
+
+// Two names are the same name when the app would show the same: the asset, or the text in one locale.
+function nameKey(name: Label): string {
+  return name["@type"] === "asset" ? `asset ${name.value.assetId}` : `text ${name.value.locale} ${name.value.text.toLowerCase()}`;
+}
+
+function phrases(capability: Declared<unknown>): string[] {
+  const { semantics } = capability.options as { semantics?: Semantics };
+  return (semantics?.actionMappings ?? []).flatMap((mapping) => mapping.actions);
+}
+
+/**
+ * Throws the first rule that a capability breaks on its endpoint. endpoint.capabilities are the ones declared
+ * before it. A stub is checked for being declared twice and for nothing else: the library does not know its rules.
+ */
+export function checkCapability(capability: Declared<unknown>, descriptor: AnyDescriptor, endpoint: EndpointView): void {
+  function refuse(problem: string): never {
+    throw new DeclarationError(capability, problem);
+  }
+  const { namespace, instance, friendlyNames } = capability;
+
+  // generic-controllers.html, "Multiple instances": one capability of an interface, or one per instance name
+  if (endpoint.capabilities.some((other) => other.namespace === namespace && other.instance === instance)) {
+    refuse(instance ? "the instance is declared twice" : "the interface is declared twice");
+  }
+  if (descriptor.tier === 3) return;
+
+  if (descriptor.instanced) {
+    // alexa-rangecontroller.html, "Capabilities array": instance and capabilityResources are required
+    if (!isText(instance)) refuse("needs an instance name, like Blind.Lift");
+    try {
+      labels.parse(friendlyNames, "friendlyNames");
+    } catch (err) {
+      refuse(err instanceof SchemaError && err.path === "friendlyNames" ? "needs a friendly name, from text() or asset()" : (err as Error).message);
+    }
+    // resources-and-assets.html, "CapabilityResources": "The first friendly name in the array must be unique for
+    // the endpoint."
+    const first = nameKey(friendlyNames[0]);
+    const taken = endpoint.capabilities.find((other) => other.friendlyNames.length > 0 && nameKey(other.friendlyNames[0]) === first);
+    if (taken) {
+      refuse(`the first friendly name, ${shownAs(friendlyNames[0])}, is the first of ${taken.namespace} ${JSON.stringify(taken.instance)} too`);
+    }
+  } else {
+    if (instance) refuse("takes no instance name: an endpoint has the interface once");
+    if (friendlyNames.length > 0) refuse("takes no friendly names");
+  }
+
+  // generic-controllers.html, "Semantics for user utterances": "Each semantic phrase must be unique across all
+  // controller instances for each endpoint"
+  const used = new Map<string, Declared>();
+  for (const other of endpoint.capabilities) for (const phrase of phrases(other)) used.set(phrase, other);
+  for (const phrase of phrases(capability)) {
+    const owner = used.get(phrase);
+    if (owner) {
+      const place = owner === capability ? "twice" : `here and on ${owner.namespace} ${JSON.stringify(owner.instance)}`;
+      refuse(`${phrase} is mapped ${place}, an endpoint maps a phrase once`);
+    }
+    used.set(phrase, capability);
+  }
+
+  if (descriptor.validate) descriptor.validate(capability, endpoint);
+}

src/index.ts

@@ -1,23 +1,34 @@
 // Relative specifiers carry ".js": Node's ES module loader resolves no extension, and TypeScript maps it back to the .ts.
 export { default as Alex2MQTT, DEFAULT_HOST } from "./Alex2Node.js";
 export type { Alex2MQTTOptions } from "./Alex2Node.js";
-export { default as Device } from "./Device.js";
-export { AlexaInterface, AlexaInterfaceType } from "./AlexaInterface.js";
-export type { SupportedMode } from "./AlexaInterface.js";
-export { ActionMapping, AlexaActions } from "./ActionMapping.js";
-export { DisplayCategory } from "./DisplayCategory.js";
-export { AlexaStatusMessage, PowerController, EndpointHealth, TemperatureSensorScale, ThermostatMode } from "./AlexaStatusMessage.js";
-export type { ChangeCause } from "./AlexaStatusMessage.js";
-export { AlexaErrorType, AlexaErrorResponse } from "./AlexaErrorResponse.js";
+export { default as Device } from "./device/Device.js";
+export type { EndpointDefinition, EndpointJson } from "./device/Device.js";
+export { Capability } from "./device/Capability.js";
+export type { CapabilityJson, CommonOptions, Declaration } from "./device/Capability.js";
 
-// The interface registry and the vocabularies of the Smart Home API
+// The interfaces, for device.add(), and the registry that holds them by name
 export { registry, DeclarationError, SchemaError } from "./registry/index.js";
+export { Alexa, BrightnessController, TemperatureSensor } from "./registry/index.js";
+export { PowerController, EndpointHealth } from "./compat/enums.js";
+export { asset, text } from "./registry/resources.js";
+
+// The vocabularies of the Smart Home API
 export {
   ASSETS as Assets, UNITS_OF_MEASURE as Units, ACTIONS as Actions, STATES as States,
   DISPLAY_CATEGORIES as DisplayCategories,
 } from "./registry/index.js";
 export type {
   ActionId, AssetId, DisplayCategoryName, StateId, UnitOfMeasure,
-  AnyDescriptor, CapabilityExtras, Declared, DirectiveDescriptor, EndpointView, EventDescriptor, InterfaceDescriptor,
-  Label, PropertyDescriptor, Infer, Schema, Temperature, TimeInterval,
+  ActionsToDirective, AnyDescriptor, CapabilityExtras, Declared, DirectiveDescriptor, EndpointView, EventDescriptor,
+  InterfaceDescriptor, Label, PropertyDescriptor, Semantics, StatesToRange, StatesToValue,
+  Infer, Schema, Temperature, TimeInterval,
 } from "./registry/index.js";
+
+// 1.x
+export { AlexaInterface } from "./compat/AlexaInterface.js";
+export type { SupportedMode } from "./compat/AlexaInterface.js";
+export { ActionMapping } from "./compat/ActionMapping.js";
+export { AlexaActions, AlexaInterfaceType, DisplayCategory, PowerState } from "./compat/enums.js";
+export { AlexaStatusMessage, TemperatureSensorScale, ThermostatMode } from "./AlexaStatusMessage.js";
+export type { ChangeCause } from "./AlexaStatusMessage.js";
+export { AlexaErrorType, AlexaErrorResponse } from "./AlexaErrorResponse.js";

src/registry/index.ts

@@ -45,8 +45,8 @@ export const registry = {
 export { Alexa, BrightnessController, EndpointHealth, PowerController, TemperatureSensor };
 export { DeclarationError, defineInterface } from "./types.js";
 export type {
-  AnyDescriptor, CapabilityExtras, Declared, DirectiveDescriptor, EndpointView, EventDescriptor, InterfaceDescriptor,
-  Label, PropertyDescriptor,
+  ActionsToDirective, AnyDescriptor, CapabilityExtras, Declared, DirectiveDescriptor, EndpointView, EventDescriptor,
+  InterfaceDescriptor, Label, PropertyDescriptor, Semantics, StatesToRange, StatesToValue,
 } from "./types.js";
 export { s, SchemaError } from "./schema.js";
 export type { Infer, Schema, Temperature, TimeInterval } from "./schema.js";

src/registry/interfaces/stubs.ts

@@ -84,6 +84,21 @@ const TABLE: readonly Row[] = [
   ["Alexa.WakeOnLANController", "1", [], "alexa-wakeonlancontroller.html"],
 ];
 
+// What 1.5.2 added to the capability object of three of them
+const EXTRAS: Record<string, AnyDescriptor["discovery"]> = {
+  // No properties object; supportsDeactivation and proactivelyReported on the capability itself
+  "Alexa.SceneController": ({ proactivelyReported }) => ({
+    properties: false,
+    topLevel: { supportsDeactivation: true, proactivelyReported },
+  }),
+  "Alexa.ThermostatController": () => ({
+    configuration: { supportedModes: ["HEAT", "COOL", "AUTO", "OFF"], supportsScheduling: false },
+  }),
+  "Alexa.ModeController": ({ options }) => (options.supportedModes?.length > 0
+    ? { configuration: { ordered: true, supportedModes: options.supportedModes } }
+    : {}),
+};
+
 function kindOf(namespace: string): AnyDescriptor["kind"] {
   if (namespace.endsWith("Sensor")) return "sensor";
   if (namespace.endsWith("EventSource")) return "eventSource";
@@ -100,6 +115,7 @@ function stub([namespace, version, properties, page]: Row): AnyDescriptor {
     instanced: false,
     properties: Object.fromEntries(properties.map((name) => [name, { name, value: s.unknown() }])),
     directives: {},
+    discovery: EXTRAS[namespace],
   };
 }
 

src/registry/resources.ts

@@ -0,0 +1,47 @@
+// Friendly names: what the user calls an instance, a mode or a preset (resources-and-assets.html).
+import { ASSETS, RESERVED_WORDS } from "./catalog.js";
+import type { AssetId } from "./catalog.js";
+import { at, s, SchemaError } from "./schema.js";
+import type { Schema } from "./schema.js";
+import type { Label } from "./types.js";
+
+/** A friendly name as text, in one locale. */
+export function text(name: string, locale = "en-US"): Label {
+  return { "@type": "text", value: { text: name, locale } };
+}
+
+/** A friendly name from the global Alexa catalog: one id, several names, every language Alexa speaks. */
+export function asset(assetId: AssetId): Label {
+  return { "@type": "asset", value: { assetId } };
+}
+
+const LOCALE = /^[a-z]{2}-[A-Z]{2}$/;
+const textValue = s.object({
+  text: s.string({ min: 1 }),
+  locale: s.string({ pattern: LOCALE, expects: "a locale like en-US" }),
+});
+const assetValue = s.object({ assetId: s.oneOf(ASSETS, "an id of the global Alexa catalog, like Alexa.Setting.Opening") });
+const typed = s.object({ "@type": s.enum("text", "asset"), value: s.unknown() });
+const reserved: readonly string[] = RESERVED_WORDS;
+
+/** One friendly name. An asset has to be in the catalog, a text must not be a word Alexa keeps for itself. */
+export const label: Schema<Label> = {
+  expects: "a friendly name, from text() or asset()",
+  parse(input, path = "") {
+    const { "@type": type, value } = typed.parse(input, path);
+    if (type === "asset") return { "@type": type, value: assetValue.parse(value, at(path, "value")) };
+    const named = textValue.parse(value, at(path, "value"));
+    if (reserved.includes(named.text.trim().toLowerCase())) {
+      throw new SchemaError(at(path, "value.text"), `${JSON.stringify(named.text)} is a reserved word, not to be used as a friendly name`);
+    }
+    return { "@type": type, value: named };
+  },
+};
+
+/** The friendly names of an instance, a mode or a preset: at least one. */
+export const labels = s.array(label, { min: 1 });
+
+/** What the user is shown for a friendly name: the text, or the id of the asset. */
+export function shownAs(name: Label): string {
+  return name["@type"] === "text" ? name.value.text : name.value.assetId;
+}

src/registry/schema.ts

@@ -65,11 +65,13 @@ function shown(input: unknown): string {
   return text.length > 60 ? `${text.slice(0, 57)}...` : text;
 }
 
-function mismatch(path: string, expects: string, input: unknown): SchemaError {
+/** The error of a value that is not what a schema expects. */
+export function mismatch(path: string, expects: string, input: unknown): SchemaError {
   return new SchemaError(path, `expected ${expects}, got ${shown(input)}`);
 }
 
-const at = (path: string, key: string): string => (path ? `${path}.${key}` : key);
+/** The path of a key of the object at path. */
+export const at = (path: string, key: string): string => (path ? `${path}.${key}` : key);
 
 function isRecord(input: unknown): input is Record<string, unknown> {
   return typeof input === "object" && input !== null && !Array.isArray(input);
@@ -117,7 +119,12 @@ function literal<V extends string | number | boolean | null>(value: V): Schema<V
 }
 
 function enumeration<V extends readonly string[]>(...values: V): EnumSchema<V[number]> {
-  return { ...schema<V[number]>(values.join(" | "), (input) => values.includes(input as string)), values };
+  return oneOf(values, values.join(" | "));
+}
+
+/** One of a list too long to print in an error message: expects says what the list is. */
+function oneOf<V extends string>(values: readonly V[], expects: string): EnumSchema<V> {
+  return { ...schema<V>(expects, (input) => values.includes(input as V)), values };
 }
 
 function unknown(): Schema<unknown> {
@@ -229,6 +236,7 @@ export const s = {
   boolean,
   literal,
   enum: enumeration,
+  oneOf,
   unknown,
   optional,
   nullable,

src/registry/types.ts

@@ -10,6 +10,33 @@ export type Label =
   | { "@type": "text"; value: { text: string; locale: string } }
   | { "@type": "asset"; value: { assetId: string } };
 
+/** Phrases ("open", "lower") mapped to one directive (alexa-discovery-objects.html, "ActionMappings object"). */
+export interface ActionsToDirective {
+  "@type": "ActionsToDirective";
+  actions: string[];
+  directive: { name: string; payload?: Record<string, unknown> };
+}
+
+/** States ("open", "closed") mapped to a value of the property (same page, "StateMappings object"). */
+export interface StatesToValue {
+  "@type": "StatesToValue";
+  states: string[];
+  value: unknown;
+}
+
+/** States mapped to a range of values of the property. */
+export interface StatesToRange {
+  "@type": "StatesToRange";
+  states: string[];
+  range: { minimumValue: number; maximumValue: number };
+}
+
+/** The semantics object of a generic controller: at least one of the two lists. */
+export interface Semantics {
+  actionMappings?: ActionsToDirective[];
+  stateMappings?: Array<StatesToValue | StatesToRange>;
+}
+
 export interface PropertyDescriptor<V> {
   name: string;
   value: Schema<V>;
@@ -48,7 +75,7 @@ export interface CapabilityExtras {
 }
 
 /** A capability as declared on an endpoint: what discovery() and validate() of its descriptor are given. */
-export interface Declared<O = Record<string, unknown>> {
+export interface Declared<O = unknown> {
   readonly endpointId: string;
   readonly namespace: string;
   /** "" when the interface is declared without an instance. */
@@ -67,7 +94,7 @@ export interface EndpointView {
   readonly friendlyName: string;
   readonly description: string;
   readonly displayCategories: readonly string[];
-  /** The other capabilities of the endpoint. */
+  /** The capabilities declared on the endpoint before this one. */
   readonly capabilities: readonly Declared[];
 }
 

test/compat/capabilities.test.js

@@ -0,0 +1,108 @@
+"use strict";
+// The 1.x way of declaring capabilities, on the classes 2.0 generates discovery from.
+const { test } = require("node:test");
+const assert = require("node:assert/strict");
+const alex2node = require("alex2node");
+const {
+  ActionMapping, AlexaActions, AlexaInterface, AlexaInterfaceType, Capability, DeclarationError, EndpointHealth, PowerController,
+  PowerState, registry,
+} = alex2node;
+const { endpoint } = require("../helpers/endpoint.js");
+
+test("every export of 1.5.2 is there", () => {
+  const exported = [
+    "ActionMapping", "Alex2MQTT", "AlexaActions", "AlexaErrorResponse", "AlexaErrorType", "AlexaInterface", "AlexaInterfaceType",
+    "AlexaStatusMessage", "DEFAULT_HOST", "Device", "DisplayCategory", "EndpointHealth", "PowerController",
+    "TemperatureSensorScale", "ThermostatMode",
+  ];
+  assert.deepEqual(exported.filter((name) => alex2node[name] === undefined), []);
+});
+
+test("PowerController and EndpointHealth are the enums of 1.x and the descriptors of 2.0", () => {
+  assert.deepEqual([PowerController.ON, PowerController.OFF], ["ON", "OFF"]);
+  assert.deepEqual([EndpointHealth.OK, EndpointHealth.UNREACHABLE], ["OK", "UNREACHABLE"]);
+  assert.equal(PowerController, registry.get("Alexa.PowerController"));
+  assert.equal(EndpointHealth, registry.get(AlexaInterfaceType.ENDPOINT_HEALTH));
+  assert.deepEqual(PowerState, { ON: "ON", OFF: "OFF" });
+});
+
+test("AlexaInterface: the constructor and the getters of 1.x", () => {
+  const capability = new AlexaInterface(AlexaInterfaceType.THERMOSTAT_CONTROLLER, false, true);
+  assert.ok(capability instanceof Capability);
+  assert.equal(capability.type, "Alexa.ThermostatController");
+  assert.equal(capability.getType(), AlexaInterfaceType.THERMOSTAT_CONTROLLER);
+  assert.equal(capability.getTypeString(), "Alexa.ThermostatController");
+  assert.equal(capability.getVersion(), "3.2");
+  assert.deepEqual(capability.getProps(), ["targetSetpoint", "lowerSetpoint", "upperSetpoint", "thermostatMode"]);
+  assert.deepEqual([capability.retrievable, capability.proactivelyReported, capability.instance], [false, true, ""]);
+  assert.deepEqual(capability.getJSON(), capability.toJSON());
+
+  const toggle = new AlexaInterface("Alexa.ToggleController", true, false, "Fan.Oscillate");
+  toggle.setInstance("Fan.Swing");
+  toggle.addFriendlyName("Swing", "en-GB");
+  assert.equal(toggle.getJSON().instance, "Fan.Swing");
+  assert.deepEqual(toggle.getJSON().capabilityResources, { friendlyNames: [{ "@type": "text", value: { text: "Swing", locale: "en-GB" } }] });
+});
+
+test("addCapability takes the enum member or the namespace, and throws for a name that is not an interface", () => {
+  const lamp = endpoint();
+  const byMember = lamp.addCapability(AlexaInterfaceType.POWER_CONTROLLER, { proactivelyReported: true });
+  const byName = lamp.addCapability("Alexa.BrightnessController");
+  assert.ok(byMember instanceof AlexaInterface);
+  assert.equal(byMember.descriptor, PowerController);
+  assert.deepEqual(lamp.getCapabilities(), [byMember, byName]);
+
+  for (const name of ["Alexa.PowerControler", AlexaInterfaceType.UNKNOWN, undefined]) {
+    assert.throws(
+      () => lamp.addCapability(name),
+      (err) => err instanceof DeclarationError && err.message === `lamp-1: ${JSON.stringify(name)} is not an interface alex2node knows`
+    );
+  }
+  assert.equal(lamp.getCapabilities().length, 2);
+  assert.throws(() => new AlexaInterface("Alexa.PowerControler"), DeclarationError);
+});
+
+test("getJSON replaced on a capability, as 1.x callers did to correct it, is what discovery lists", () => {
+  const lock = endpoint("lock-1", "Front Door", ["SMARTLOCK"]);
+  const capability = lock.addCapability(AlexaInterfaceType.LOCK_CONTROLLER);
+  const original = capability.getJSON.bind(capability);
+  capability.getJSON = () => ({ ...original(), properties: { ...original().properties, supported: [{ name: "lockState" }] } });
+  assert.deepEqual(lock.getJSON().capabilities[0].properties.supported, [{ name: "lockState" }]);
+});
+
+test("ActionMapping: the payload is an object and reaches discovery as one", () => {
+  const open = new ActionMapping([AlexaActions.Open, AlexaActions.Raise], "SetRangeValue", { rangeValue: 100 });
+  assert.deepEqual(open.toJSON(), {
+    "@type": "ActionsToDirective",
+    actions: ["Alexa.Actions.Open", "Alexa.Actions.Raise"],
+    directive: { name: "SetRangeValue", payload: { rangeValue: 100 } },
+  });
+  assert.equal(open.deprecation, undefined);
+  // An empty payload is kept: the ToggleController examples of Amazon have "payload": {}
+  assert.deepEqual(new ActionMapping([AlexaActions.Close], "TurnOff", {}).toJSON().directive, { name: "TurnOff", payload: {} });
+  // None at all, and the "" that 1.x took for none
+  assert.deepEqual(new ActionMapping([AlexaActions.Close], "TurnOff").toJSON().directive, { name: "TurnOff" });
+  assert.deepEqual(new ActionMapping([AlexaActions.Close], "TurnOff", "").toJSON().directive, { name: "TurnOff" });
+});
+
+test("ActionMapping: a JSON string is parsed and noted as deprecated, any other string throws", () => {
+  const blinds = endpoint("blinds-1", "Blinds", ["INTERIOR_BLIND"]);
+  const lift = blinds.addCapability(AlexaInterfaceType.RANGE_CONTROLLER, { instance: "Blind.Lift" });
+  lift.addActionMapping(new ActionMapping([AlexaActions.Close], "SetRangeValue", JSON.stringify({ rangeValue: 0 })));
+  lift.addActionMapping(new ActionMapping([AlexaActions.Open], "SetRangeValue", { rangeValue: 100 }));
+
+  // 1.5.2 put the string itself into discovery: "payload": "{\"rangeValue\":0}"
+  assert.deepEqual(lift.getJSON().semantics.actionMappings.map((mapping) => mapping.directive.payload), [{ rangeValue: 0 }, { rangeValue: 100 }]);
+  assert.deepEqual(
+    blinds.check().filter((line) => line.includes("JSON string")),
+    ['blinds-1: Alexa.RangeController "Blind.Lift": the payload of the action mapping for SetRangeValue is a JSON string, pass the object']
+  );
+
+  for (const text of ["rangeValue: 0", "0", "[0]", "null", '"closed"']) {
+    assert.throws(
+      () => new ActionMapping([AlexaActions.Close], "SetRangeValue", text),
+      (err) => err instanceof DeclarationError
+        && err.message === `the payload of the action mapping for SetRangeValue is an object, got the string ${JSON.stringify(text)}`
+    );
+  }
+});

test/device/discovery.test.js

@@ -0,0 +1,253 @@
+"use strict";
+// The discovery JSON of an endpoint: generated from the descriptors of its capabilities, in the order they were
+// declared, with the capabilities the library adds at the end.
+const { test } = require("node:test");
+const assert = require("node:assert/strict");
+const {
+  Alex2MQTT, ActionMapping, Alexa, AlexaActions, AlexaInterfaceType, BrightnessController, DisplayCategory, EndpointHealth,
+  PowerController, TemperatureSensor, registry,
+} = require("alex2node");
+const interfaces = require("../fixtures/interfaces.js");
+const { endpoint } = require("../helpers/endpoint.js");
+const { capabilities, zoo } = require("../helpers/fixtures.js");
+const { setup, until } = require("../helpers/harness.js");
+
+const ALEXA = { type: "AlexaInterface", interface: "Alexa", version: "3" };
+const names = (json) => json.capabilities.map((capability) => capability.interface);
+
+// Ask as Alex2MQTT does and return the endpoints of the one answer.
+async function discover(alexa, root) {
+  const before = alexa.on(`${root}/discover_r`).length;
+  alexa.publish(`${root}/discover`, { namespace: "Alexa.Discovery", name: "Discover" });
+  await until(() => alexa.on(`${root}/discover_r`).length === before + 1, 3000, "discovery reply");
+  return alexa.on(`${root}/discover_r`)[before];
+}
+
+for (const { namespace, page, declared } of interfaces) {
+  test(`${namespace}: device.add() gives the capability object of ${page}.html`, () => {
+    for (const { options, as: [example, n = 0] } of declared) {
+      const capability = endpoint().add(registry.get(namespace), options);
+      assert.deepEqual(capability.toJSON(), capabilities(page, namespace, example)[n], `${example}[${n}]`);
+    }
+  });
+}
+
+test("the fields of a capability object are in the order of the examples: type, interface, version, properties", () => {
+  const lamp = endpoint();
+  lamp.add(PowerController, { proactivelyReported: true });
+  assert.equal(
+    JSON.stringify(lamp.getJSON().capabilities[0]),
+    '{"type":"AlexaInterface","interface":"Alexa.PowerController","version":"3",'
+      + '"properties":{"supported":[{"name":"powerState"}],"proactivelyReported":true,"retrievable":true}}'
+  );
+});
+
+test("capabilities are listed as declared, the Alexa interface after them", () => {
+  const thermostat = endpoint("thermo-1", "Thermostat", ["THERMOSTAT", "TEMPERATURE_SENSOR"]);
+  thermostat.add(TemperatureSensor);
+  thermostat.add(PowerController);
+  thermostat.add(BrightnessController);
+  assert.deepEqual(names(thermostat.getJSON()), ["Alexa.TemperatureSensor", "Alexa.PowerController", "Alexa.BrightnessController", "Alexa"]);
+  assert.deepEqual(thermostat.getJSON().capabilities.at(-1), ALEXA);
+  assert.deepEqual(thermostat.getCapabilities().map((capability) => capability.namespace), ["Alexa.TemperatureSensor", "Alexa.PowerController", "Alexa.BrightnessController"]);
+
+  // Declared by the device itself, it stays where it was declared and is listed once
+  const lamp = endpoint();
+  lamp.add(Alexa);
+  lamp.add(PowerController);
+  assert.deepEqual(names(lamp.getJSON()), ["Alexa", "Alexa.PowerController"]);
+});
+
+test("defaults of a declaration: retrievable, not proactively reported, nonControllable left out unless given", () => {
+  const lamp = endpoint();
+  assert.deepEqual(lamp.add(PowerController).toJSON().properties, { supported: [{ name: "powerState" }], proactivelyReported: false, retrievable: true });
+  assert.deepEqual(
+    lamp.add(BrightnessController, { retrievable: false, proactivelyReported: true, nonControllable: true }).toJSON().properties,
+    { supported: [{ name: "brightness" }], proactivelyReported: true, retrievable: false, nonControllable: true }
+  );
+  assert.equal(lamp.add(TemperatureSensor, { nonControllable: false }).toJSON().properties.nonControllable, false);
+});
+
+test("PowerController verificationsRequired: the directives Alexa asks the user to confirm", () => {
+  const capability = endpoint().add(PowerController, { verificationsRequired: ["TurnOff"] });
+  assert.deepEqual(capability.toJSON().verificationsRequired, [{ directive: "TurnOff", methods: [{ "@type": "Confirmation" }] }]);
+  assert.equal("verificationsRequired" in endpoint().add(PowerController).toJSON(), false);
+});
+
+test("1.x declarations are announced as 1.5.2 announced them, with the Alexa interface added", () => {
+  const T = AlexaInterfaceType;
+  // zoo.js, the devices whose discovery JSON 1.5.2 produced without corrections
+  const declarations = {
+    "zoo-dimmer": (device) => {
+      device.addCapability(T.POWER_CONTROLLER, { proactivelyReported: true });
+      device.addCapability(T.BRIGHTNESS_CONTROLLER, { proactivelyReported: true });
+    },
+    "zoo-thermostat": (device) => {
+      device.addCapability(T.THERMOSTAT_CONTROLLER, { proactivelyReported: true });
+      device.addCapability(T.TEMPERATURE_SENSOR, { proactivelyReported: true });
+    },
+    "zoo-curtain": (device) => {
+      device.addCapability(T.POWER_CONTROLLER, { proactivelyReported: true });
+      const toggle = device.addCapability(T.TOGGLE_CONTROLLER, { proactivelyReported: true, instance: "Zoo.Shade" });
+      toggle.addFriendlyName("Shade", "en-US");
+      toggle.addActionMapping(new ActionMapping([AlexaActions.Close], "TurnOn"));
+      toggle.addActionMapping(new ActionMapping([AlexaActions.Open], "TurnOff"));
+    },
+    "zoo-fan": (device) => {
+      device.addCapability(T.POWER_CONTROLLER, { proactivelyReported: true });
+      const mode = device.addCapability(T.MODE_CONTROLLER, { proactivelyReported: true });
+      mode.setInstance("Fan.Speed");
+      mode.addFriendlyName("Speed", "en-US");
+      mode.addSupportedModes(["Low", "Medium", "High"].map((text) => ({
+        value: `Speed.${text}`,
+        modeResources: { friendlyNames: [{ "@type": "text", value: { text, locale: "en-US" } }] },
+      })));
+    },
+    "zoo-scene": (device) => device.addCapability(T.SCENE_CONTROLLER),
+    "zoo-tv": (device) => {
+      device.addCapability("Alexa.PowerController", { proactivelyReported: true });
+      device.addCapability("Alexa.ChannelController", { proactivelyReported: true });
+    },
+  };
+  for (const [endpointId, declare] of Object.entries(declarations)) {
+    const accepted = zoo(endpointId);
+    const device = endpoint(endpointId, accepted.friendlyName, accepted.displayCategories);
+    device.setDescription(accepted.description);
+    device.setManufacturerName(accepted.manufacturerName);
+    device.setManufacturer(accepted.additionalAttributes.manufacturer);
+    device.setModel(accepted.additionalAttributes.model);
+    declare(device);
+    assert.deepEqual(device.getJSON(), { ...accepted, capabilities: [...accepted.capabilities, ALEXA] }, endpointId);
+    assert.deepEqual(device.check(), [], endpointId);
+  }
+});
+
+test("registerDevice: every endpoint ends with the Alexa interface; alexaInterface: false leaves it out", async () => {
+  const { alexa, bridge } = await setup(Alex2MQTT, "root");
+  const lamp = bridge.registerDevice("Lamp", "lamp-1", DisplayCategory.LIGHT);
+  lamp.addCapability(AlexaInterfaceType.POWER_CONTROLLER);
+  lamp.addCapability(AlexaInterfaceType.ENDPOINT_HEALTH);
+  const scene = bridge.registerDevice("Evening", "scene-1", DisplayCategory.SCENE_TRIGGER);
+  scene.addCapability(AlexaInterfaceType.SCENE_CONTROLLER);
+  // A registerDevice() device gets no Alexa.EndpointHealth it did not declare
+  const bare = bridge.registerDevice("Plug", "plug-1", DisplayCategory.SMARTPLUG);
+  bare.addCapability(AlexaInterfaceType.POWER_CONTROLLER);
+
+  assert.deepEqual((await discover(alexa, "root")).map(names), [
+    ["Alexa.PowerController", "Alexa.EndpointHealth", "Alexa"],
+    ["Alexa.SceneController", "Alexa"],
+    ["Alexa.PowerController", "Alexa"],
+  ]);
+
+  const without = await setup(Alex2MQTT, "root-1x", { alexaInterface: false });
+  without.bridge.registerDevice("Lamp", "lamp-1", DisplayCategory.LIGHT).addCapability(AlexaInterfaceType.POWER_CONTROLLER);
+  without.bridge.addDevice({ endpointId: "lamp-2", name: "Lamp Two", categories: ["LIGHT"], endpointHealth: false }).add(PowerController);
+  assert.deepEqual((await discover(without.alexa, "root-1x")).map(names), [["Alexa.PowerController"], ["Alexa.PowerController"]]);
+});
+
+test("addDevice: the fields of the definition reach discovery; the defaults are those of registerDevice", async () => {
+  const { alexa, bridge } = await setup(Alex2MQTT, "root");
+  bridge.addDevice({
+    endpointId: "bedroom-blinds",
+    name: "Bedroom Blinds",
+    categories: ["INTERIOR_BLIND", DisplayCategory.OTHER],
+    description: "Roller blind by Acme",
+    manufacturerName: "Acme",
+    manufacturer: "Acme Inc",
+    model: "RB-2",
+    serialNumber: "0042",
+    firmwareVersion: "2.1.0",
+    softwareVersion: "2.1.3",
+    customIdentifier: "acme-rb2-0042",
+    cookie: { room: "bedroom" },
+    endpointHealth: false,
+  });
+  bridge.addDevice({ endpointId: "lamp-1", name: "Lamp", categories: ["LIGHT"], endpointHealth: false });
+  const registered = bridge.registerDevice("Lamp", "lamp-2", DisplayCategory.LIGHT);
+
+  const [blinds, lamp] = await discover(alexa, "root");
+  assert.deepEqual(blinds, {
+    endpointId: "bedroom-blinds",
+    friendlyName: "Bedroom Blinds",
+    description: "Roller blind by Acme",
+    manufacturerName: "Acme",
+    displayCategories: ["INTERIOR_BLIND", "OTHER"],
+    additionalAttributes: {
+      manufacturer: "Acme Inc",
+      model: "RB-2",
+      serialNumber: "0042",
+      firmwareVersion: "2.1.0",
+      softwareVersion: "2.1.3",
+      customIdentifier: "acme-rb2-0042",
+    },
+    cookie: { room: "bedroom" },
+    capabilities: [ALEXA],
+  });
+  assert.deepEqual(lamp, { ...registered.getJSON(), endpointId: "lamp-1" });
+  assert.equal("cookie" in lamp, false);
+});
+
+test("addDevice: Alexa.EndpointHealth is listed for the device unless it declares one, opts out or is a scene", async () => {
+  const { alexa, bridge } = await setup(Alex2MQTT, "root");
+  bridge.addDevice({ endpointId: "lamp-1", name: "Lamp", categories: ["LIGHT"] }).add(PowerController);
+  const reporting = bridge.addDevice({ endpointId: "lamp-2", name: "Lamp Two", categories: ["LIGHT"] });
+  reporting.add(EndpointHealth, { proactivelyReported: true });
+  reporting.add(PowerController);
+  bridge.addDevice({ endpointId: "lamp-3", name: "Lamp Three", categories: ["LIGHT"], endpointHealth: false }).add(PowerController);
+  bridge.addDevice({ endpointId: "scene-1", name: "Evening", categories: ["SCENE_TRIGGER"], description: "Evening scene" })
+    .addCapability(AlexaInterfaceType.SCENE_CONTROLLER);
+
+  const [lamp, declared, optedOut, scene] = await discover(alexa, "root");
+  assert.deepEqual(names(lamp), ["Alexa.PowerController", "Alexa.EndpointHealth", "Alexa"]);
+  assert.deepEqual(lamp.capabilities[1], {
+    type: "AlexaInterface",
+    interface: "Alexa.EndpointHealth",
+    version: "3.1",
+    properties: { supported: [{ name: "connectivity" }], proactivelyReported: false, retrievable: true },
+  });
+  assert.deepEqual(names(declared), ["Alexa.EndpointHealth", "Alexa.PowerController", "Alexa"]);
+  assert.equal(declared.capabilities[0].properties.proactivelyReported, true);
+  assert.deepEqual(names(optedOut), ["Alexa.PowerController", "Alexa"]);
+  assert.deepEqual(names(scene), ["Alexa.SceneController", "Alexa"]);
+});
+
+test("discovery logs what check() says about the devices, each line once", async () => {
+  const logged = [];
+  const { alexa, bridge } = await setup(Alex2MQTT, "root", { log: (message) => logged.push(message) });
+  const warnings = () => logged.filter((message) => message.startsWith("warning: "));
+  const lamp = bridge.registerDevice("Dave's Lamp", "lamp-1", DisplayCategory.LIGHT);
+  lamp.addCapability(AlexaInterfaceType.POWER_CONTROLLER);
+  lamp.addCapability(AlexaInterfaceType.POWER_CONTROLLER);
+  lamp.addCapability(AlexaInterfaceType.LOCK_CONTROLLER);
+  bridge.registerDevice("Lamp", "lamp-2", DisplayCategory.LIGHT).addCapability(AlexaInterfaceType.POWER_CONTROLLER);
+
+  // Announced all the same: 1.x announced it, and Alexa may have taken it
+  const [first] = await discover(alexa, "root");
+  assert.deepEqual(names(first), ["Alexa.PowerController", "Alexa.PowerController", "Alexa.LockController", "Alexa"]);
+  assert.deepEqual(warnings(), [
+    'warning: lamp-1: the name "Dave\'s Lamp" takes up to 256 letters, digits and spaces, no punctuation',
+    "warning: lamp-1: Alexa.PowerController: the interface is declared twice",
+    "warning: lamp-1: Alexa.LockController: no property list known, discovery lists it with no supported properties",
+  ]);
+
+  lamp.setName("Daves Lamp");
+  bridge.registerDevice("Timer!", "lamp-3", DisplayCategory.LIGHT);
+  await discover(alexa, "root");
+  assert.deepEqual(warnings().slice(3), ['warning: lamp-3: the name "Timer!" takes up to 256 letters, digits and spaces, no punctuation']);
+});
+
+test("a device that cannot be described is left out of the answer and reported; the others are announced", async () => {
+  const { alexa, bridge } = await setup(Alex2MQTT, "root");
+  const errors = [];
+  bridge.on("error", (err) => errors.push(err.message));
+  bridge.registerDevice("Lamp", "lamp-1", DisplayCategory.LIGHT).addCapability(AlexaInterfaceType.POWER_CONTROLLER);
+  const lock = bridge.registerDevice("Front Door", "lock-1", DisplayCategory.SMARTLOCK);
+  lock.addCapability(AlexaInterfaceType.LOCK_CONTROLLER).getJSON = () => { throw new TypeError("state is not defined"); };
+
+  assert.deepEqual((await discover(alexa, "root")).map((each) => each.endpointId), ["lamp-1"]);
+  assert.deepEqual(errors, ["lock-1 is not in the discovery answer: state is not defined"]);
+
+  // Without an error listener the same discovery is answered and nothing is thrown
+  bridge.removeAllListeners("error");
+  assert.deepEqual((await discover(alexa, "root")).map((each) => each.endpointId), ["lamp-1"]);
+});

test/device/validate.test.js

@@ -0,0 +1,148 @@
+"use strict";
+// What Alexa rejects at discovery is refused where it is declared: bridge.addDevice() and device.add() throw a
+// DeclarationError that names the endpoint, the interface and the instance, and leave everything as it was.
+const { test } = require("node:test");
+const assert = require("node:assert/strict");
+const {
+  Alex2MQTT, AlexaInterfaceType, BrightnessController, DeclarationError, EndpointHealth, PowerController, TemperatureSensor, registry,
+} = require("alex2node");
+const { endpoint } = require("../helpers/endpoint.js");
+const { setup, sleep } = require("../helpers/harness.js");
+
+// The DeclarationError that declare() throws.
+function refused(declare) {
+  try {
+    declare();
+  } catch (err) {
+    assert.ok(err instanceof DeclarationError, `threw ${err && err.stack}`);
+    return err;
+  }
+  return assert.fail("the declaration was accepted");
+}
+
+test("addDevice refuses an endpoint Alexa would reject, registers nothing and publishes nothing", async () => {
+  const { alexa, bridge } = await setup(Alex2MQTT, "root");
+  const lamp = { endpointId: "lamp-1", name: "Lamp", categories: ["LIGHT"] };
+  const cases = [
+    [{ endpointId: "garage/lamp" }, "garage/lamp: the endpointId takes up to 256 letters, digits, spaces and _ - = # ; : ? @ &"],
+    [{ endpointId: "x".repeat(257) }, `${"x".repeat(61)}...: the endpointId takes up to 256 letters, digits, spaces and _ - = # ; : ? @ &`],
+    [{ endpointId: "" }, "an endpoint needs an endpointId"],
+    [{ name: "Dave's Lamp" }, 'lamp-1: the name "Dave\'s Lamp" takes up to 256 letters, digits and spaces, no punctuation'],
+    [{ name: "L".repeat(257) }, `lamp-1: the name "${"L".repeat(257)}" takes up to 256 letters, digits and spaces, no punctuation`],
+    [{ name: undefined }, "lamp-1: an endpoint needs a name"],
+    [{ description: "d".repeat(129) }, "lamp-1: the description takes 1 to 128 characters"],
+    [{ manufacturerName: "" }, "lamp-1: the manufacturerName takes 1 to 128 characters"],
+    [{ categories: undefined }, "lamp-1: an endpoint needs a display category"],
+    [{ categories: [] }, "lamp-1: an endpoint needs a display category"],
+    [{ categories: ["LAMP"] }, 'lamp-1: "LAMP" is not a display category'],
+    // In the DisplayCategory enum since 1.x, no longer on Amazon's list
+    [{ categories: ["LIGHT", "VEHICLE"] }, 'lamp-1: "VEHICLE" is not a display category'],
+    [{ model: "m".repeat(257) }, "lamp-1: model takes up to 256 characters"],
+    [{ cookie: { note: "c".repeat(5000) } }, "lamp-1: the cookie is 5011 bytes, 5000 is the most"],
+    [{ category: ["LIGHT"] }, "lamp-1: category is not a field of an endpoint"],
+  ];
+  for (const [fields, message] of cases) {
+    const err = refused(() => bridge.addDevice({ ...lamp, ...fields }));
+    assert.equal(err.message, message);
+    assert.equal(err.name, "DeclarationError");
+  }
+  assert.deepEqual(bridge.getDevices(), []);
+
+  // What the rules allow: every character of an endpointId, a name in another script, a cookie of 5000 bytes
+  bridge.addDevice({ ...lamp, endpointId: "A z0_-=#;:?@&", name: "Lampe für Küche 2", cookie: { note: "c".repeat(4989) } });
+  bridge.addDevice({ ...lamp, endpointId: "x".repeat(256), name: "寝室のライト" });
+  assert.equal(bridge.getDevices().length, 2);
+
+  const twice = refused(() => bridge.addDevice({ ...lamp, endpointId: "A z0_-=#;:?@&", name: "Another" }));
+  assert.equal(twice.message, 'A z0_-=#;:?@&: is registered already, as "Lampe für Küche 2"');
+  assert.equal(twice.endpointId, "A z0_-=#;:?@&");
+  assert.equal(bridge.getDevices().length, 2);
+
+  await sleep(50);
+  assert.deepEqual(alexa.got, []);
+});
+
+test("device.add refuses the interface declared twice, an instance or a friendly name where the interface has none", () => {
+  const lamp = endpoint();
+  lamp.add(PowerController);
+  const cases = [
+    [() => lamp.add(PowerController), "lamp-1: Alexa.PowerController: the interface is declared twice"],
+    [() => lamp.add(BrightnessController, { instance: "Lamp.Level" }), 'lamp-1: Alexa.BrightnessController "Lamp.Level": takes no instance name: an endpoint has the interface once'],
+    [
+      () => lamp.add(BrightnessController, { friendlyNames: [{ "@type": "text", value: { text: "Level", locale: "en-US" } }] }),
+      "lamp-1: Alexa.BrightnessController: takes no friendly names",
+    ],
+  ];
+  for (const [declare, message] of cases) assert.equal(refused(declare).message, message);
+  assert.deepEqual(lamp.getCapabilities().map((capability) => capability.namespace), ["Alexa.PowerController"]);
+
+  const err = refused(() => lamp.add(BrightnessController, { instance: "Lamp.Level" }));
+  assert.deepEqual(
+    { endpointId: err.endpointId, namespace: err.namespace, instance: err.instance, problem: err.problem },
+    { endpointId: "lamp-1", namespace: "Alexa.BrightnessController", instance: "Lamp.Level", problem: "takes no instance name: an endpoint has the interface once" }
+  );
+});
+
+test("device.add refuses an option the interface does not have and a value that does not fit", () => {
+  const lamp = endpoint();
+  const cases = [
+    [() => lamp.add(PowerController, { verificationRequired: ["TurnOn"] }), "lamp-1: Alexa.PowerController: verificationRequired: unknown key, the known ones are verificationsRequired"],
+    [() => lamp.add(PowerController, { verificationsRequired: ["Toggle"] }), 'lamp-1: Alexa.PowerController: verificationsRequired[0]: expected TurnOn | TurnOff, got "Toggle"'],
+    [() => lamp.add(TemperatureSensor, { scale: "CELSIUS" }), "lamp-1: Alexa.TemperatureSensor: scale: not an option of the interface"],
+    [() => lamp.add(TemperatureSensor, { retrievable: "yes" }), 'lamp-1: Alexa.TemperatureSensor: retrievable: expected true or false, got "yes"'],
+    [() => lamp.add(TemperatureSensor, { instance: 7 }), "lamp-1: Alexa.TemperatureSensor: instance: expected a string, got 7"],
+    [() => lamp.add(TemperatureSensor, "retrievable"), "lamp-1: Alexa.TemperatureSensor: the options of a declaration are an object"],
+  ];
+  for (const [declare, message] of cases) assert.equal(refused(declare).message, message);
+  assert.deepEqual(lamp.getCapabilities(), []);
+});
+
+test("an endpoint takes 100 capabilities, the ones the library adds among them", () => {
+  const panel = endpoint("panel-1", "Panel", ["OTHER"]);
+  for (let n = 1; n <= 98; n += 1) panel.addCapability(AlexaInterfaceType.TOGGLE_CONTROLLER, { instance: `Panel.Switch${n}` });
+  panel.add(PowerController);
+  assert.equal(panel.getJSON().capabilities.length, 100);
+  assert.deepEqual(panel.check(), []);
+
+  assert.equal(refused(() => panel.add(BrightnessController)).message, "panel-1: 101 capabilities, an endpoint takes 100");
+  assert.equal(panel.getCapabilities().length, 99);
+
+  // The 1.x call is not refused: check() says it
+  panel.addCapability(AlexaInterfaceType.BRIGHTNESS_CONTROLLER);
+  assert.deepEqual(panel.check(), ["panel-1: 101 capabilities, an endpoint takes 100"]);
+
+  // With Alexa.EndpointHealth added for the device there is room for 98
+  const health = endpoint("panel-2", "Panel", ["OTHER"]);
+  health.endpointHealth = true;
+  for (let n = 1; n <= 98; n += 1) health.addCapability(AlexaInterfaceType.TOGGLE_CONTROLLER, { instance: `Panel.Switch${n}` });
+  assert.equal(refused(() => health.add(PowerController)).message, "panel-2: 101 capabilities, an endpoint takes 100");
+  assert.doesNotThrow(() => health.add(EndpointHealth));
+});
+
+test("check() lists what is wrong with a device declared the 1.x way, one line for each", () => {
+  const lamp = endpoint("lamp/1", "Lamp #1", ["LIGHT"]);
+  assert.deepEqual(lamp.check(), ["lamp/1: the endpointId takes up to 256 letters, digits, spaces and _ - = # ; : ? @ &"]);
+
+  const fan = endpoint("fan-1", "Fan", ["FAN", "VEHICLE"]);
+  fan.addCapability(AlexaInterfaceType.POWER_CONTROLLER, { instance: "Fan.Power" });
+  fan.addCapability(AlexaInterfaceType.TOGGLE_CONTROLLER, { instance: "Fan.Oscillate" });
+  fan.addCapability(AlexaInterfaceType.TOGGLE_CONTROLLER, { instance: "Fan.Oscillate" });
+  assert.deepEqual(fan.check(), [
+    'fan-1: "VEHICLE" is not a display category',
+    'fan-1: Alexa.PowerController "Fan.Power": takes no instance name: an endpoint has the interface once',
+    'fan-1: Alexa.ToggleController "Fan.Oscillate": the instance is declared twice',
+  ]);
+  assert.equal(fan.getJSON().capabilities.length, 4, "announced all the same");
+});
+
+test("a stub is declared like any interface and checked for nothing but being declared twice", () => {
+  const lock = endpoint("lock-1", "Front Door", ["SMARTLOCK"]);
+  const capability = lock.add(registry.get("Alexa.LockController"), { proactivelyReported: true });
+  assert.deepEqual(capability.toJSON(), {
+    type: "AlexaInterface",
+    interface: "Alexa.LockController",
+    version: "3",
+    properties: { supported: [], proactivelyReported: true, retrievable: true },
+  });
+  assert.equal(refused(() => lock.add(registry.get("Alexa.LockController"))).message, "lock-1: Alexa.LockController: the interface is declared twice");
+});

test/fixtures/interfaces.js

@@ -1,11 +1,20 @@
 "use strict";
-// One entry per interface that is described in full: the page its examples were saved from (test/helpers/fixtures.js).
-// test/registry/descriptors.test.js holds every entry against those examples and fails for a descriptor of tier 1 or
-// 2 that has no entry here.
+// One entry per interface that is described in full: the page its examples were saved from (test/helpers/fixtures.js)
+// and declarations that give capability objects of those examples.
+//
+//   namespace   the interface
+//   page        the page of the interface; test/fixtures/alexa-docs/<page>/ has its examples
+//   declared    [{ options, as: [example, n] }]: device.add(descriptor, options) gives the n-th capability object of
+//               the interface in that discovery example (n counts from 0 and defaults to it)
+//
+// test/registry/descriptors.test.js and test/device/discovery.test.js run the entries. The first one fails for a
+// descriptor of tier 1 or 2 that has no entry.
+const reported = { retrievable: true, proactivelyReported: true };
+
 module.exports = [
-  { namespace: "Alexa", page: "alexa-interface" },
-  { namespace: "Alexa.BrightnessController", page: "alexa-brightnesscontroller" },
-  { namespace: "Alexa.EndpointHealth", page: "alexa-endpointhealth" },
-  { namespace: "Alexa.PowerController", page: "alexa-powercontroller" },
-  { namespace: "Alexa.TemperatureSensor", page: "alexa-temperaturesensor" },
+  { namespace: "Alexa", page: "alexa-interface", declared: [{ options: {}, as: ["discovery"] }] },
+  { namespace: "Alexa.BrightnessController", page: "alexa-brightnesscontroller", declared: [{ options: reported, as: ["discovery"] }] },
+  { namespace: "Alexa.EndpointHealth", page: "alexa-endpointhealth", declared: [{ options: reported, as: ["discovery"] }] },
+  { namespace: "Alexa.PowerController", page: "alexa-powercontroller", declared: [{ options: reported, as: ["discovery"] }] },
+  { namespace: "Alexa.TemperatureSensor", page: "alexa-temperaturesensor", declared: [{ options: reported, as: ["discovery"] }] },
 ];

test/fixtures/types.ts

@@ -2,12 +2,12 @@
 // dist/types, resolved through the package's "exports". A "@ts-expect-error" line fails the compile when the
 // declaration stops rejecting what follows it.
 import {
-  ActionMapping, AlexaActions, AlexaInterfaceType, Assets, DeclarationError, DisplayCategory, EndpointHealth, PowerController,
-  registry,
+  ActionMapping, AlexaActions, AlexaInterfaceType, Assets, BrightnessController, DeclarationError, DisplayCategory, EndpointHealth,
+  PowerController, PowerState, TemperatureSensor, asset, registry, text,
 } from "alex2node";
 import type {
-  Alex2MQTT, Alex2MQTTOptions, AlexaInterface, AlexaStatusMessage, AssetId, ChangeCause, Device, DisplayCategoryName, Infer,
-  InterfaceDescriptor, Schema, SupportedMode, Temperature, UnitOfMeasure,
+  Alex2MQTT, Alex2MQTTOptions, AlexaInterface, AlexaStatusMessage, AssetId, Capability, CapabilityJson, ChangeCause, Device,
+  DisplayCategoryName, EndpointJson, Infer, InterfaceDescriptor, Label, Schema, SupportedMode, Temperature, UnitOfMeasure,
 } from "alex2node";
 
 declare const bridge: Alex2MQTT;
@@ -18,9 +18,12 @@ const options: Alex2MQTTOptions = { host: "mqtt://127.0.0.1:1883", mqtt: { recon
 const device: Device = bridge.registerDevice("Lamp", "lamp-1", [DisplayCategory.LIGHT, DisplayCategory.SWITCH]);
 const added: AlexaInterface = device.addCapability(AlexaInterfaceType.POWER_CONTROLLER, { proactivelyReported: true });
 
-// ActionMapping: the payload is optional
+// ActionMapping: the payload is optional, and an object
 const close = new ActionMapping([AlexaActions.Close], "TurnOn");
 capability.addActionMapping(close);
+capability.addActionMapping(new ActionMapping([AlexaActions.Open], "SetRangeValue", { rangeValue: 100 }));
+// @ts-expect-error a payload is an object or, as in 1.x, a string
+capability.addActionMapping(new ActionMapping([AlexaActions.Open], "SetRangeValue", 100));
 
 // addHealthProp: the enum or its string values, chainable
 const chained: AlexaStatusMessage = message.addHealthProp(EndpointHealth.OK).addHealthProp("UNREACHABLE", 50);
@@ -29,6 +32,10 @@ message.addHealthProp("ASLEEP");
 // @ts-expect-error a power state is ON or OFF
 message.addPowerControllerProp("ON ");
 message.addPowerControllerProp(PowerController.ON);
+// PowerController is the descriptor of the interface as well; the enum alone is PowerState
+const on: PowerController = PowerState.ON;
+const namespace: string = PowerController.namespace;
+const reachable: EndpointHealth = EndpointHealth.OK;
 
 // addSupportedModes: Mode objects, plain strings still accepted
 const mode: SupportedMode = { value: "Fan.Auto", modeResources: { friendlyNames: [{ "@type": "text", value: { text: "Auto", locale: "en-US" } }] } };
@@ -39,6 +46,34 @@ const sent: Promise<string> = device.getChangeReport(cause).addPowerControllerPr
 // @ts-expect-error not a cause Alexa knows
 device.getChangeReport("BUTTON");
 
+// bridge.addDevice() and device.add(): the options of the interface and the ones every capability has
+const blinds: Device = bridge.addDevice({
+  endpointId: "bedroom-blinds",
+  name: "Bedroom Blinds",
+  categories: ["INTERIOR_BLIND", DisplayCategory.OTHER],
+  cookie: { room: "bedroom" },
+  endpointHealth: false,
+});
+// @ts-expect-error an endpoint has categories
+bridge.addDevice({ endpointId: "lamp-2", name: "Lamp" });
+// @ts-expect-error not a display category
+bridge.addDevice({ endpointId: "lamp-2", name: "Lamp", categories: ["LAMP"] });
+const power: Capability = blinds.add(PowerController, { proactivelyReported: true, verificationsRequired: ["TurnOff"] });
+blinds.add(BrightnessController);
+blinds.add(TemperatureSensor, { retrievable: true, nonControllable: true });
+// @ts-expect-error not a directive of the interface
+blinds.add(PowerController, { verificationsRequired: ["Toggle"] });
+// @ts-expect-error not an option of the interface
+blinds.add(BrightnessController, { range: { min: 0, max: 100 } });
+const announced: CapabilityJson = power.toJSON();
+const endpoint: EndpointJson = blinds.getJSON();
+const problems: string[] = blinds.check();
+
+// Friendly names
+const names: Label[] = [asset("Alexa.Setting.Opening"), text("Position"), text("Posición", "es-MX")];
+// @ts-expect-error not in the global Alexa catalog
+asset("Alexa.Setting.Openning");
+
 // The registry: a descriptor by its namespace or by the 1.x enum member
 const described: InterfaceDescriptor = registry.get("Alexa.PowerController");
 const version: string = registry.get(AlexaInterfaceType.ENDPOINT_HEALTH).version;
@@ -59,4 +94,7 @@ const measured: Infer<typeof temperature> = { value: 20, scale: "CELSIUS" };
 // @ts-expect-error not a temperature scale
 const rankine: Infer<typeof temperature> = { value: 20, scale: "RANKINE" };
 
-export { options, added, chained, sent, version, refused, opening, percent, vacuum, misspelt, notAUnit, measured, rankine };
+export {
+  options, added, chained, sent, on, namespace, reachable, announced, endpoint, problems, names, version, refused, opening,
+  percent, vacuum, misspelt, notAUnit, measured, rankine,
+};

test/helpers/endpoint.js

@@ -0,0 +1,10 @@
+"use strict";
+// A device that is on no bridge. What a device declares and the discovery JSON it answers with need no broker.
+const { Device } = require("alex2node");
+
+/** The arguments Device takes before the name are the broker client and the root topic of its bridge. */
+function endpoint(endpointId = "lamp-1", name = "Lamp", categories = ["LIGHT"]) {
+  return new Device(null, "root", name, endpointId, categories);
+}
+
+module.exports = { endpoint };

test/helpers/fixtures.js

@@ -6,6 +6,7 @@ const fs = require("node:fs");
 const path = require("node:path");
 
 const DOCS = path.join(__dirname, "..", "fixtures", "alexa-docs");
+const ZOO = path.join(__dirname, "..", "fixtures", "zoo", "discovery.json");
 
 /** One example: doc("alexa-powercontroller", "TurnOn.directive"). */
 function doc(page, name) {
@@ -44,4 +45,15 @@ function reported(page, namespace) {
   return found.filter(({ property }) => property.namespace === namespace);
 }
 
-module.exports = { doc, examples, capabilities, reported };
+/**
+ * An endpoint of the zoo: the 22 test devices built on alex2node 1.5.2, as their discovery answer was on 2026-09-28
+ * when Alexa accepted all of them. Six had their capability JSON corrected by hand, because 1.5.2 had no way to
+ * declare it: zoo-blinds, zoo-blower, zoo-heater, zoo-lock, zoo-motion, and zoo-health-lamp-31 for its version.
+ */
+function zoo(endpointId) {
+  const endpoint = JSON.parse(fs.readFileSync(ZOO, "utf8")).find((each) => each.endpointId === endpointId);
+  if (!endpoint) throw new Error(`${endpointId} is not in the zoo`);
+  return endpoint;
+}
+
+module.exports = { doc, examples, capabilities, reported, zoo };

test/packaging.test.mjs

@@ -23,7 +23,7 @@ test("import { Alex2MQTT } from \"alex2node\": discovery, a directive and a chan
   await until(() => alexa.on("root/discover_r").length === 1, 3000, "discovery reply");
   const [endpoints] = alexa.on("root/discover_r");
   assert.deepEqual(endpoints.map((e) => e.endpointId), ["lamp-1"]);
-  assert.deepEqual(endpoints[0].capabilities.map((c) => c.interface), ["Alexa.PowerController", "Alexa.EndpointHealth"]);
+  assert.deepEqual(endpoints[0].capabilities.map((c) => c.interface), ["Alexa.PowerController", "Alexa.EndpointHealth", "Alexa"]);
 
   alexa.send("root", directive("Alexa.PowerController", "TurnOn", "lamp-1", "ct1"));
   await until(() => alexa.on("root/lamp-1/alexaResponce").length === 1, 3000, "directive response");