registry: describe an Alexa interface as data

src/registry/ holds what the library knows about an interface: namespace, version, the page it was read from,
properties with their value schemas and directives with their payload schemas. Five interfaces are described
(Alexa, PowerController, BrightnessController, TemperatureSensor, EndpointHealth); the other 65 names of
AlexaInterfaceType are stubs with the version and property names of 1.5.2. schema.ts is the run-time check behind
it (241 lines, no new dependency), catalog.ts the vocabularies of the pages: 103 assets (23 units), 6 actions,
9 states, 56 display categories, 22 reserved words, 73 error types under 11 namespaces.

AlexaInterface.getVersion() and getProps() read the registry; the two switch statements are gone (-167 lines).
On the wire: Alexa.EndpointHealth is announced at 3.1 (was 3.3; the page is titled 3.1 and no page mentions 3.3),
and TimeHoldController and Camera.LiveViewController at 3 and 1.7 (1.5.2 sent the string "UNKNOWN").
DisplayCategory gains VACUUM. New exports: registry, DeclarationError, SchemaError, Assets, Units, Actions,
States, DisplayCategories and the descriptor types.

Tests: 20 JSON examples of the five pages under test/fixtures/alexa-docs; every directive payload and property
value in them parses with its descriptor. npm test: 57 pass (was 30) in 10.8 s, also on Node 18.20.8 and 20.20.2.

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

src/registry/interfaces/Alexa.ts

@@ -0,0 +1,21 @@
+import { s } from "../schema.js";
+import { defineInterface } from "../types.js";
+
+/**
+ * The base interface: every endpoint lists it (alexa-interface.html, "Support the Alexa interface in all add-ons").
+ * Its one directive to a device is ReportState, answered with a StateReport.
+ */
+export const Alexa = defineInterface({
+  namespace: "Alexa",
+  version: "3",
+  doc: "https://developer.amazon.com/docs/alexaplus/device-apis/alexa-interface.html",
+  kind: "base",
+  tier: 1,
+  instanced: false,
+  properties: {},
+  directives: {
+    ReportState: { name: "ReportState", payload: s.object({}) },
+  },
+  // { type, interface, version } and nothing else, as in the discovery example of the page
+  discovery: () => ({ properties: false }),
+});

src/registry/interfaces/BrightnessController.ts

@@ -0,0 +1,25 @@
+import { s } from "../schema.js";
+import { defineInterface } from "../types.js";
+
+/** Both directives turn a light that is off on, at the brightness asked for (alexa-brightnesscontroller.html). */
+export const BrightnessController = defineInterface({
+  namespace: "Alexa.BrightnessController",
+  version: "3",
+  doc: "https://developer.amazon.com/docs/alexaplus/device-apis/alexa-brightnesscontroller.html",
+  kind: "controller",
+  tier: 1,
+  instanced: false,
+  properties: {
+    brightness: { name: "brightness", value: s.number({ min: 0, max: 100, integer: true }) },
+  },
+  directives: {
+    SetBrightness: {
+      name: "SetBrightness",
+      payload: s.object({ brightness: s.number({ min: 0, max: 100, integer: true }) }),
+    },
+    AdjustBrightness: {
+      name: "AdjustBrightness",
+      payload: s.object({ brightnessDelta: s.number({ min: -100, max: 100, integer: true }) }),
+    },
+  },
+});

src/registry/interfaces/EndpointHealth.ts

@@ -0,0 +1,31 @@
+import { s } from "../schema.js";
+import { defineInterface } from "../types.js";
+
+export const CONNECTIVITY_REASONS = [
+  "WIFI_BAD_PASSWORD", "WIFI_AP_NOT_FOUND", "WIFI_ROUTER_UNREACHABLE", "WIFI_AP_CHANNEL_QUALITY_LOW",
+  "INTERNET_UNREACHABLE", "CAPTIVE_PORTAL_CHECK_FAILED", "UNKNOWN",
+] as const;
+
+/**
+ * Version 3.1, as the page is titled. It defines connectivity only. Examples on other pages declare 3 and 3.2;
+ * alex2node 1.x declared 3.3, which no page mentions.
+ */
+export const EndpointHealth = defineInterface({
+  namespace: "Alexa.EndpointHealth",
+  version: "3.1",
+  doc: "https://developer.amazon.com/docs/alexaplus/device-apis/alexa-endpointhealth.html",
+  kind: "sensor",
+  tier: 1,
+  instanced: false,
+  properties: {
+    connectivity: {
+      name: "connectivity",
+      value: s.object({
+        value: s.enum("OK", "UNREACHABLE"),
+        reason: s.optional(s.enum(...CONNECTIVITY_REASONS)),
+      }),
+      note: "in every Response, StateReport and ChangeReport; a change of it reported within three seconds",
+    },
+  },
+  directives: {},
+});

src/registry/interfaces/PowerController.ts

@@ -0,0 +1,28 @@
+import { s } from "../schema.js";
+import { defineInterface } from "../types.js";
+
+export const PowerController = defineInterface({
+  namespace: "Alexa.PowerController",
+  version: "3",
+  doc: "https://developer.amazon.com/docs/alexaplus/device-apis/alexa-powercontroller.html",
+  kind: "controller",
+  tier: 1,
+  instanced: false,
+  properties: {
+    powerState: { name: "powerState", value: s.enum("ON", "OFF") },
+  },
+  directives: {
+    TurnOn: { name: "TurnOn", payload: s.object({}) },
+    TurnOff: { name: "TurnOff", payload: s.object({}) },
+  },
+  options: s.object({
+    // The directives Alexa asks the user to confirm before it sends them. Amazon supports this for devices in Japan
+    // only (alexa-discovery-objects.html, "VerificationsRequired object").
+    verificationsRequired: s.optional(s.array(s.enum("TurnOn", "TurnOff"), { min: 1 })),
+  }, { unknownKeys: "reject" }),
+  discovery({ options }) {
+    if (!options.verificationsRequired) return {};
+    const confirmed = options.verificationsRequired.map((directive) => ({ directive, methods: [{ "@type": "Confirmation" }] }));
+    return { topLevel: { verificationsRequired: confirmed } };
+  },
+});

src/registry/interfaces/TemperatureSensor.ts

@@ -0,0 +1,16 @@
+import { s } from "../schema.js";
+import { defineInterface } from "../types.js";
+
+/** A sensor: an endpoint that has it declares Alexa.EndpointHealth as well (alexa-temperaturesensor.html). */
+export const TemperatureSensor = defineInterface({
+  namespace: "Alexa.TemperatureSensor",
+  version: "3",
+  doc: "https://developer.amazon.com/docs/alexaplus/device-apis/alexa-temperaturesensor.html",
+  kind: "sensor",
+  tier: 1,
+  instanced: false,
+  properties: {
+    temperature: { name: "temperature", value: s.temperature() },
+  },
+  directives: {},
+});

src/registry/interfaces/stubs.ts

@@ -0,0 +1,106 @@
+// Interfaces without a descriptor of their own. A stub names the interface with the version and the properties
+// alex2node 1.5.2 put in discovery, so an endpoint that declares one is announced as before. Nothing about it is
+// checked, and the version is the one 1.5.2 sent, which is not always the one on the page of the interface
+// (Alexa.Speaker is "3" there). A row leaves this table when a descriptor is written from that page.
+import { s } from "../schema.js";
+import type { AnyDescriptor } from "../types.js";
+
+const DEVICE_APIS = "https://developer.amazon.com/docs/alexaplus/device-apis";
+const LIST_OF_INTERFACES = `${DEVICE_APIS}/list-of-interfaces.html`;
+// "As of August 7, 2026, Automotive skills and the associated Alexa.AuthorizationController and
+// Alexa.Automotive.VehicleData APIs are no longer available."
+const DEPRECATED_FEATURES = "https://developer.amazon.com/en-US/docs/alexa/ask-overviews/deprecated-features.html";
+
+// namespace, version, properties, page (a name under device-apis/, or a URL)
+type Row = readonly [string, string, readonly string[], string];
+
+const TABLE: readonly Row[] = [
+  ["Alexa.ApplicationStateReporter", "1", [], "https://developer.amazon.com/docs/alexaplus/alexa-voice-service/alexa-applicationstatereporter.html"],
+  ["Alexa.Audio.PlayQueue", "1", [], "alexa-audio-playqueue.html"],
+  ["Alexa.AuthorizationController", "1", [], DEPRECATED_FEATURES],
+  ["Alexa.AutomationManagement", "1", ["automationStatuses"], "alexa-automationmanagement.html"],
+  ["Alexa.Automotive.VehicleData", "1", [], DEPRECATED_FEATURES],
+  // 1.5.2 announced the version "UNKNOWN"; 1.7 is what the list of interfaces gives
+  ["Alexa.Camera.LiveViewController", "1.7", [], LIST_OF_INTERFACES],
+  ["Alexa.CameraStreamController", "3", [], "alexa-camerastreamcontroller.html"],
+  ["Alexa.ChannelController", "3", ["channel"], "alexa-channelcontroller.html"],
+  ["Alexa.ColorController", "3", ["color"], "alexa-colorcontroller.html"],
+  ["Alexa.ColorTemperatureController", "3", ["colorTemperatureInKelvin"], "alexa-colortemperaturecontroller.html"],
+  ["Alexa.Commissionable", "1", [], "alexa-commissionable.html"],
+  ["Alexa.ConsentManagement.ConsentRequiredReporter", "1", [], "alexa-consentrequiredreporter.html"],
+  ["Alexa.ContactSensor", "3", ["detectionState"], "alexa-contactsensor.html"],
+  ["Alexa.Cooking", "1", [], "alexa-cooking.html"],
+  ["Alexa.Cooking.FoodTemperatureController", "1", [], "alexa-cooking-foodtemperaturecontroller.html"],
+  ["Alexa.Cooking.FoodTemperatureSensor", "1", [], "alexa-cooking-foodtemperaturesensor.html"],
+  ["Alexa.Cooking.PresetController", "1", [], "alexa-cooking-presetcontroller.html"],
+  ["Alexa.Cooking.TemperatureController", "1", [], "alexa-cooking-temperaturecontroller.html"],
+  ["Alexa.Cooking.TemperatureSensor", "1", [], "alexa-cooking-temperaturesensor.html"],
+  ["Alexa.Cooking.TimeController", "1", [], "alexa-cooking-timecontroller.html"],
+  ["Alexa.DataController", "1", [], "alexa-datacontroller.html"],
+  ["Alexa.DeviceUsage.Estimation", "1", [], "alexa-deviceusage-estimation.html"],
+  ["Alexa.DeviceUsage.Meter", "1", [], "alexa-deviceusage-meter.html"],
+  ["Alexa.DoorbellEventSource", "3", [], "alexa-doorbelleventsource.html"],
+  ["Alexa.EqualizerController", "1", [], "alexa-equalizercontroller.html"],
+  ["Alexa.InputController", "3", [], "alexa-inputcontroller.html"],
+  ["Alexa.InventoryLevelSensor", "1", [], "alexa-inventorylevelsensor.html"],
+  ["Alexa.InventoryLevelUsageSensor", "1", [], "alexa-inventorylevelusagesensor.html"],
+  ["Alexa.InventoryUsageSensor", "1", [], "alexa-inventoryusagesensor.html"],
+  ["Alexa.KeypadController", "1", [], "alexa-keypadcontroller.html"],
+  ["Alexa.Launcher", "1.1", [], "alexa-launcher.html"],
+  ["Alexa.LockController", "3", [], "alexa-lockcontroller.html"],
+  ["Alexa.Media.PlayQueue", "1", [], "alexa-media-playqueue.html"],
+  ["Alexa.Media.Playback", "1", [], "alexa-media-playback.html"],
+  ["Alexa.Media.Search", "1", [], "alexa-media-search.html"],
+  ["Alexa.ModeController", "3", ["mode"], "alexa-modecontroller.html"],
+  ["Alexa.MotionSensor", "3", [], "alexa-motionsensor.html"],
+  ["Alexa.PercentageController", "3", [], "alexa-percentagecontroller.html"],
+  ["Alexa.PlaybackController", "3", [], "alexa-playbackcontroller.html"],
+  ["Alexa.PlaybackStateReporter", "1", [], "alexa-playbackcontroller.html"],
+  ["Alexa.PowerLevelController", "3", [], "alexa-powerlevelcontroller.html"],
+  ["Alexa.ProactiveNotificationSource", "1", [], "alexa-proactivenotificationsource.html"],
+  ["Alexa.RTCSessionController", "1", [], "alexa-rtcsessioncontroller.html"],
+  ["Alexa.RangeController", "3", [], "alexa-rangecontroller.html"],
+  ["Alexa.RecordController", "3", [], "alexa-recordcontroller.html"],
+  ["Alexa.RemoteVideoPlayer", "1", [], "alexa-remotevideoplayer.html"],
+  ["Alexa.SceneController", "3", [], "alexa-scenecontroller.html"],
+  ["Alexa.SecurityPanelController", "1", [], "alexa-securitypanelcontroller.html"],
+  ["Alexa.SecurityPanelController.Alert", "1", [], "alexa-securitypanelcontroller-alert.html"],
+  ["Alexa.SeekController", "3", [], "alexa-seekcontroller.html"],
+  ["Alexa.SimpleEventSource", "1", [], "alexa-simpleeventsource.html"],
+  ["Alexa.SmartVision.ObjectDetectionSensor", "1", [], "alexa-smartvision-objectdetectionsensor.html"],
+  ["Alexa.SmartVision.SnapshotProvider", "1", [], "alexa-smartvision-snapshotprovider.html"],
+  ["Alexa.Speaker", "1", [], "alexa-speaker.html"],
+  ["Alexa.StepSpeaker", "1", [], "alexa-stepspeaker.html"],
+  ["Alexa.ThermostatController", "3.2", ["targetSetpoint", "lowerSetpoint", "upperSetpoint", "thermostatMode"], "alexa-thermostatcontroller.html"],
+  ["Alexa.ThermostatController.Configuration", "1", [], "alexa-thermostatcontroller-configuration.html"],
+  ["Alexa.ThermostatController.HVAC.Components", "1", [], "alexa-thermostatcontroller-hvac-components.html"],
+  ["Alexa.ThermostatController.Schedule", "1", [], "alexa-thermostatcontroller-schedule.html"],
+  // "UNKNOWN" in 1.5.2 as well; the page is titled "Interface 3"
+  ["Alexa.TimeHoldController", "3", [], "alexa-timeholdcontroller.html"],
+  ["Alexa.ToggleController", "3", ["toggleState"], "alexa-togglecontroller.html"],
+  ["Alexa.UIController", "1", [], "alexa-uicontroller.html"],
+  ["Alexa.UserPreference", "1", [], "alexa-userpreference.html"],
+  ["Alexa.VideoRecorder", "1", [], "alexa-videorecorder.html"],
+  ["Alexa.WakeOnLANController", "1", [], "alexa-wakeonlancontroller.html"],
+];
+
+function kindOf(namespace: string): AnyDescriptor["kind"] {
+  if (namespace.endsWith("Sensor")) return "sensor";
+  if (namespace.endsWith("EventSource")) return "eventSource";
+  return "controller";
+}
+
+function stub([namespace, version, properties, page]: Row): AnyDescriptor {
+  return {
+    namespace,
+    version,
+    doc: page.startsWith("https://") ? page : `${DEVICE_APIS}/${page}`,
+    kind: kindOf(namespace),
+    tier: 3,
+    instanced: false,
+    properties: Object.fromEntries(properties.map((name) => [name, { name, value: s.unknown() }])),
+    directives: {},
+  };
+}
+
+export const STUBS: readonly AnyDescriptor[] = TABLE.map(stub);