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>

test/registry/catalog.test.js

@@ -0,0 +1,72 @@
+"use strict";
+// The vocabularies copied from Amazon's pages: their sizes as counted on the pages on 2026-09-28, and how they
+// relate to the 1.x enums.
+const { test } = require("node:test");
+const assert = require("node:assert/strict");
+const {
+  Actions, AlexaActions, AlexaErrorType, Assets, DisplayCategories, DisplayCategory, States, Units,
+} = require("alex2node");
+const { ERROR_TYPES, RESERVED_WORDS, LIMITS } = require("../../dist/cjs/registry/catalog.js");
+
+const unique = (list) => new Set(list).size === list.length;
+
+test("assets: the 103 ids of the global Alexa catalog, 23 of them units of measure", () => {
+  assert.equal(Assets.length, 103);
+  assert.ok(unique(Assets));
+  for (const id of Assets) assert.match(id, /^Alexa\.(Actions|Button|DeviceName|Gestures?|Setting|Shower|Unit|Value)\.[A-Za-z0-9.]+$/);
+  assert.equal(Units.length, 23);
+  assert.deepEqual(Units, Assets.filter((id) => id.startsWith("Alexa.Unit.")));
+  assert.ok(Units.includes("Alexa.Unit.Percent"));
+  // The page has "Gesture" seven times and "Gestures" once
+  assert.deepEqual(Assets.filter((id) => id.startsWith("Alexa.Gestures.")), ["Alexa.Gestures.DoubleTap"]);
+});
+
+test("semantics: six actions, the ones the AlexaActions enum of 1.x has, and nine states", () => {
+  assert.deepEqual([...Actions].sort(), Object.values(AlexaActions).sort());
+  assert.deepEqual(States.map((id) => id.replace("Alexa.States.", "")), ["Open", "Closed", "EcoOn", "EcoOff", "Low", "Empty", "Full", "Done", "Stuck"]);
+});
+
+test("display categories: the 56 of the page; the enum has them all and keeps VEHICLE", () => {
+  assert.equal(DisplayCategories.length, 56);
+  assert.ok(unique(DisplayCategories));
+  const inEnum = Object.values(DisplayCategory);
+  assert.deepEqual(DisplayCategories.filter((category) => !inEnum.includes(category)), []);
+  assert.deepEqual(inEnum.filter((category) => !DisplayCategories.includes(category)), ["VEHICLE"]);
+  assert.equal(DisplayCategory.VACUUM, "VACUUM");
+  for (const [key, value] of Object.entries(DisplayCategory)) assert.equal(key, value);
+});
+
+test("error types: the 73 of the error type table, each under the namespace of its interface", () => {
+  assert.equal(Object.keys(ERROR_TYPES).length, 73);
+  assert.equal(ERROR_TYPES.ENDPOINT_UNREACHABLE, "Alexa");
+  assert.equal(ERROR_TYPES.INVALID_VALUE, "Alexa");
+  assert.equal(ERROR_TYPES.THERMOSTAT_IS_OFF, "Alexa.ThermostatController");
+  assert.equal(ERROR_TYPES.UNAUTHORIZED, "Alexa.SecurityPanelController");
+  assert.equal(ERROR_TYPES.OBSTACLE_DETECTED, "Alexa.Safety");
+  assert.equal(ERROR_TYPES.TEMPERATURE_VALUE_OUT_OF_RANGE, "Alexa", "the generic one, not a thermostat error");
+  const namespaces = [...new Set(Object.values(ERROR_TYPES))].sort();
+  assert.equal(namespaces.length, 11);
+  for (const namespace of namespaces) assert.match(namespace, /^Alexa(\.[A-Za-z]+)*$/);
+
+  // AlexaErrorType of 1.x has every type of the table and two that the table does not list
+  const inEnum = Object.values(AlexaErrorType);
+  assert.deepEqual(Object.keys(ERROR_TYPES).filter((type) => !inEnum.includes(type)), []);
+  assert.deepEqual(inEnum.filter((type) => !(type in ERROR_TYPES)).sort(), ["EXCEEDED_PIN_ATTEMPTS", "PIN_SETUP_REQUIRED"]);
+});
+
+test("reserved words and limits", () => {
+  assert.equal(RESERVED_WORDS.length, 22);
+  assert.ok(unique(RESERVED_WORDS));
+  for (const word of RESERVED_WORDS) assert.equal(word, word.toLowerCase());
+  assert.deepEqual(LIMITS, {
+    endpointsPerCustomer: 300,
+    capabilitiesPerEndpoint: 100,
+    endpointIdLength: 256,
+    friendlyNameLength: 256,
+    sceneFriendlyNameLength: 128,
+    manufacturerNameLength: 128,
+    descriptionLength: 128,
+    additionalAttributeLength: 256,
+    cookieBytes: 5000,
+  });
+});

test/registry/descriptors.test.js

@@ -0,0 +1,127 @@
+"use strict";
+// The registry: every descriptor is well formed, the ones described in full agree with the examples of their page,
+// and every interface name of 1.x resolves.
+const { test } = require("node:test");
+const assert = require("node:assert/strict");
+const { registry, AlexaInterface, AlexaInterfaceType, DeclarationError } = require("alex2node");
+const interfaces = require("../fixtures/interfaces.js");
+const { doc, examples, capabilities, reported } = require("../helpers/fixtures.js");
+
+const described = registry.list().filter((descriptor) => descriptor.tier !== 3);
+const stubs = registry.list().filter((descriptor) => descriptor.tier === 3);
+
+test("every descriptor has a namespace, a version, a kind and the page it was written from", () => {
+  const namespaces = registry.list().map((descriptor) => descriptor.namespace);
+  assert.deepEqual(namespaces, [...namespaces].sort(), "list() is ordered by namespace");
+  for (const descriptor of registry.list()) {
+    const { namespace } = descriptor;
+    assert.match(namespace, /^Alexa(\.[A-Za-z]+)*$/);
+    assert.match(descriptor.version, /^\d+(\.\d+)?$/, namespace);
+    assert.match(descriptor.doc, /^https:\/\/developer\.amazon\.com\/[\w\-./]+\.html$/, namespace);
+    assert.ok(["base", "controller", "sensor", "eventSource"].includes(descriptor.kind), namespace);
+    assert.ok([1, 2, 3].includes(descriptor.tier), namespace);
+    assert.equal(typeof descriptor.instanced, "boolean", namespace);
+    for (const [key, property] of Object.entries(descriptor.properties)) assert.equal(property.name, key, namespace);
+    for (const [key, directive] of Object.entries(descriptor.directives)) assert.equal(directive.name, key, namespace);
+  }
+});
+
+test("a descriptor of tier 1 or 2 has an entry in test/fixtures/interfaces.js, and every entry a descriptor", () => {
+  assert.deepEqual(described.map((descriptor) => descriptor.namespace), interfaces.map((entry) => entry.namespace).sort());
+});
+
+for (const { namespace, page } of interfaces) {
+  test(`${namespace}: version, properties, directive payloads and property values of ${page}.html`, () => {
+    const descriptor = registry.get(namespace);
+    assert.ok(descriptor.doc.endsWith(`/${page}.html`), descriptor.doc);
+
+    for (const name of examples(page).filter((example) => example.startsWith("discovery"))) {
+      for (const capability of capabilities(page, namespace, name)) {
+        assert.equal(capability.version, descriptor.version, `${name}: version`);
+        const supported = capability.properties ? capability.properties.supported.map((property) => property.name) : [];
+        for (const property of supported) assert.ok(property in descriptor.properties, `${name}: ${property}`);
+      }
+    }
+
+    const directives = examples(page, ".directive").map((name) => doc(page, name).directive);
+    assert.deepEqual(
+      directives.map((directive) => directive.header.name).sort(),
+      Object.keys(descriptor.directives).filter((name) => name !== "ReportState").sort(),
+      "the page has an example of every directive"
+    );
+    for (const { header, payload } of directives) {
+      assert.equal(header.namespace, namespace);
+      assert.deepEqual(descriptor.directives[header.name].payload.parse(payload, "payload"), payload);
+    }
+
+    const values = reported(page, namespace);
+    for (const { example, property } of values) {
+      const known = descriptor.properties[property.name];
+      assert.ok(known, `${example}: ${property.name} is not a property of the descriptor`);
+      assert.deepEqual(known.value.parse(property.value, property.name), property.value, example);
+    }
+    if (Object.keys(descriptor.properties).length > 0) assert.ok(values.length > 0, "the page reports no property of the interface");
+  });
+}
+
+test("Alexa.EndpointHealth is version 3.1 and reports connectivity, with a reason when it has one", () => {
+  const { version, properties } = registry.get("Alexa.EndpointHealth");
+  assert.equal(version, "3.1");
+  assert.deepEqual(Object.keys(properties), ["connectivity"]);
+  const unreachable = doc("alexa-endpointhealth", "connectivity.property").value;
+  assert.deepEqual(properties.connectivity.value.parse(unreachable), { value: "UNREACHABLE", reason: "WIFI_BAD_PASSWORD" });
+  assert.deepEqual(properties.connectivity.value.parse({ value: "OK" }), { value: "OK" });
+  assert.throws(
+    () => properties.connectivity.value.parse({ value: "UNREACHABLE", reason: "UNPLUGGED" }, "connectivity"),
+    /^SchemaError: connectivity\.reason: expected WIFI_BAD_PASSWORD \| .* \| UNKNOWN, got "UNPLUGGED"$/
+  );
+});
+
+test("a payload or a value that does not fit is refused with its path", () => {
+  const { directives, properties } = registry.get("Alexa.BrightnessController");
+  assert.throws(
+    () => directives.SetBrightness.payload.parse({ brightness: "lots" }, "payload"),
+    /^SchemaError: payload\.brightness: expected an integer from 0 to 100, got "lots"$/
+  );
+  assert.throws(() => directives.AdjustBrightness.payload.parse({ brightnessDelta: 101 }, "payload"), /from -100 to 100/);
+  assert.throws(() => properties.brightness.value.parse(-1, "brightness"), /^SchemaError: brightness: expected an integer/);
+  assert.throws(() => registry.get("Alexa.PowerController").properties.powerState.value.parse("on", "powerState"), /expected ON \| OFF/);
+});
+
+test("registry.get: the namespace and the AlexaInterfaceType member give the same descriptor; an unknown name throws", () => {
+  assert.equal(registry.get(AlexaInterfaceType.POWER_CONTROLLER), registry.get("Alexa.PowerController"));
+  assert.equal(registry.has("Alexa.PowerController"), true);
+  assert.equal(registry.has("Alexa.TeleportController"), false);
+  assert.throws(
+    () => registry.get("Alexa.TeleportController"),
+    (err) => err instanceof DeclarationError && err.message === '"Alexa.TeleportController" is not an interface alex2node knows'
+  );
+  assert.throws(() => registry.get(AlexaInterfaceType.UNKNOWN), DeclarationError);
+});
+
+test("every AlexaInterfaceType of 1.x is in the registry: described, or a stub with the version and properties of 1.5.2", () => {
+  const names = Object.values(AlexaInterfaceType).filter((name) => name !== AlexaInterfaceType.UNKNOWN);
+  assert.equal(names.length, 69);
+  assert.deepEqual(names.filter((name) => !registry.has(name)), []);
+  // "Alexa" is the one interface that was never in the enum
+  assert.deepEqual(registry.list().map((descriptor) => descriptor.namespace).filter((name) => !names.includes(name)), ["Alexa"]);
+
+  for (const stub of stubs) {
+    assert.deepEqual(stub.directives, {}, stub.namespace);
+    assert.equal(stub.instanced, false, stub.namespace);
+  }
+  const thermostat = registry.get("Alexa.ThermostatController");
+  assert.equal(thermostat.version, "3.2");
+  assert.deepEqual(Object.keys(thermostat.properties), ["targetSetpoint", "lowerSetpoint", "upperSetpoint", "thermostatMode"]);
+});
+
+test("AlexaInterface.getVersion() and getProps() read the registry", () => {
+  for (const descriptor of registry.list().filter(({ namespace }) => namespace !== "Alexa")) {
+    const capability = new AlexaInterface(descriptor.namespace);
+    assert.equal(capability.getVersion(), descriptor.version, descriptor.namespace);
+    assert.deepEqual(capability.getProps(), Object.keys(descriptor.properties), descriptor.namespace);
+  }
+  // 1.5.2 had no version for these two and put "UNKNOWN" in discovery
+  assert.equal(new AlexaInterface(AlexaInterfaceType.TIME_HOLD_CONTROLLER).getVersion(), "3");
+  assert.equal(new AlexaInterface(AlexaInterfaceType.CAMERA_LIVE_VIEW_CONTROLLER).getVersion(), "1.7");
+});

test/registry/schema.test.js

@@ -0,0 +1,111 @@
+"use strict";
+// The schema helper of the registry: what parse() returns, and what the error says when the value does not fit.
+const { test } = require("node:test");
+const assert = require("node:assert/strict");
+const { SchemaError } = require("alex2node");
+// The helper is not part of the public surface; the descriptors are built with it.
+const { s } = require("../../dist/cjs/registry/schema.js");
+
+// The message of the SchemaError that parse() throws.
+function refusal(schema, input, path) {
+  try {
+    schema.parse(input, path);
+  } catch (err) {
+    assert.ok(err instanceof SchemaError, `threw ${err}`);
+    return err.message;
+  }
+  return assert.fail(`${JSON.stringify(input)} was accepted`);
+}
+
+test("number: bounds, integers, and no NaN or text", () => {
+  const percent = s.number({ min: 0, max: 100, integer: true });
+  assert.equal(percent.parse(0), 0);
+  assert.equal(percent.parse(100), 100);
+  assert.equal(refusal(percent, 101, "payload.brightness"), "payload.brightness: expected an integer from 0 to 100, got 101");
+  assert.equal(refusal(percent, 50.5, "payload.brightness"), "payload.brightness: expected an integer from 0 to 100, got 50.5");
+  assert.equal(refusal(percent, "lots", "payload.brightness"), 'payload.brightness: expected an integer from 0 to 100, got "lots"');
+  assert.equal(refusal(s.number(), NaN, "value"), "value: expected a number, got null");
+  assert.equal(refusal(s.number({ gt: 0 }), 0, "range.precision"), "range.precision: expected a number greater than 0, got 0");
+  assert.equal(s.number({ gt: 0 }).parse(0.5), 0.5);
+});
+
+test("enum and literal: the value itself, the choices in the message", () => {
+  const power = s.enum("ON", "OFF");
+  assert.equal(power.parse("ON"), "ON");
+  assert.deepEqual(power.values, ["ON", "OFF"]);
+  assert.equal(refusal(power, "on", "powerState"), 'powerState: expected ON | OFF, got "on"');
+  assert.equal(s.literal("FOUR_DIGIT_PIN").parse("FOUR_DIGIT_PIN"), "FOUR_DIGIT_PIN");
+  assert.equal(refusal(s.literal(3), "3", "version"), 'version: expected 3, got "3"');
+});
+
+test("object: the path of the key that is wrong; a key that is not in the shape is kept", () => {
+  const payload = s.object({ rangeValueDelta: s.number(), rangeValueDeltaDefault: s.boolean() });
+  assert.deepEqual(payload.parse({ rangeValueDelta: -5, rangeValueDeltaDefault: false }), { rangeValueDelta: -5, rangeValueDeltaDefault: false });
+  assert.equal(
+    refusal(payload, { rangeValueDelta: -5 }, "payload"),
+    "payload.rangeValueDeltaDefault: expected true or false, got nothing"
+  );
+  assert.equal(refusal(payload, [1, 2], "payload"), "payload: expected an object with rangeValueDelta, rangeValueDeltaDefault, got [1,2]");
+  assert.equal(refusal(payload, null, "payload"), "payload: expected an object with rangeValueDelta, rangeValueDeltaDefault, got null");
+  // A field Alexa adds to a directive later reaches the handler
+  assert.deepEqual(s.object({}).parse({ added: 1 }), { added: 1 });
+});
+
+test("object with unknownKeys \"reject\": a misspelt option is named, with the ones that exist", () => {
+  const options = s.object({ range: s.unknown(), presets: s.optional(s.unknown()) }, { unknownKeys: "reject" });
+  assert.equal(refusal(options, { range: {}, preset: [] }), "preset: unknown key, the known ones are range, presets");
+  assert.deepEqual(options.parse({ range: {} }), { range: {} });
+});
+
+test("optional, nullable, array", () => {
+  assert.equal(s.optional(s.number()).parse(undefined), undefined);
+  assert.equal(refusal(s.optional(s.number()), null, "delta"), "delta: expected a number, got null");
+  assert.equal(s.nullable(s.string()).parse(null), null);
+  assert.equal(refusal(s.nullable(s.string()), 5, "mode"), "mode: expected a string or null, got 5");
+  const modes = s.array(s.object({ value: s.string() }), { min: 2 });
+  assert.deepEqual(modes.parse([{ value: "a" }, { value: "b" }]), [{ value: "a" }, { value: "b" }]);
+  assert.equal(refusal(modes, [{ value: "a" }], "supportedModes"), 'supportedModes: expected a list with 2 or more entries, got [{"value":"a"}]');
+  assert.equal(refusal(modes, [{ value: "a" }, { value: 2 }], "supportedModes"), "supportedModes[1].value: expected a string, got 2");
+});
+
+test("temperature: the three scales of alexa-property-schemas.html, the scale named when it is wrong", () => {
+  const temperature = s.temperature();
+  assert.deepEqual(temperature.parse({ value: 68.0, scale: "FAHRENHEIT" }), { value: 68, scale: "FAHRENHEIT" });
+  assert.deepEqual(temperature.parse({ value: 293.15, scale: "KELVIN" }), { value: 293.15, scale: "KELVIN" });
+  assert.equal(
+    refusal(temperature, { value: 20, scale: "Celsius" }, "payload.targetSetpoint"),
+    'payload.targetSetpoint.scale: expected CELSIUS | FAHRENHEIT | KELVIN, got "Celsius"'
+  );
+  assert.equal(refusal(temperature, 20, "temperature"), "temperature: expected an object with value, scale, got 20");
+});
+
+test("dateTime and duration: the examples of alexa-property-schemas.html", () => {
+  for (const time of ["2017-08-30T01:18:21Z", "2017-08-30T01:18:21.123Z", "2017-10-04T14:00Z"]) assert.equal(s.dateTime().parse(time), time);
+  for (const time of ["2017-08-30T01:18:21+02:00", "2017-08-30 01:18:21Z", "2017-13-40T01:18:21Z", 1504055901]) {
+    assert.match(refusal(s.dateTime(), time, "start"), /^start: expected a UTC time like 2017-08-30T01:18:21Z, got /);
+  }
+  for (const length of ["PT3M15S", "PT-30S", "PT30M", "PT1H"]) assert.equal(s.duration().parse(length), length);
+  for (const length of ["PT", "3M", "P1D", "PT3M15"]) {
+    assert.match(refusal(s.duration(), length, "duration"), /^duration: expected a duration like PT3M15S, got /);
+  }
+});
+
+test("timeInterval: one or two of start, end and duration", () => {
+  const interval = s.timeInterval();
+  for (const example of [
+    { start: "2017-10-04T14:00Z", end: "2017-10-04T14:15Z" },
+    { start: "2017-10-04T14:00Z", duration: "PT30M" },
+    { duration: "PT30M" },
+  ]) assert.deepEqual(interval.parse(example), example);
+  const all = { start: "2017-10-04T14:00Z", end: "2017-10-04T14:15Z", duration: "PT15M" };
+  assert.match(refusal(interval, all, "holdUntil"), /^holdUntil: expected a time interval with one or two of start, end, duration, got /);
+  assert.match(refusal(interval, {}, "holdUntil"), /^holdUntil: expected a time interval with one or two of start, end, duration, got \{\}$/);
+  assert.equal(refusal(interval, { end: "tomorrow" }, "holdUntil"), 'holdUntil.end: expected a UTC time like 2017-08-30T01:18:21Z, got "tomorrow"');
+});
+
+test("an error without a path is the problem alone, and a long value is cut short", () => {
+  assert.equal(refusal(s.boolean(), "yes"), 'expected true or false, got "yes"');
+  const message = refusal(s.number(), "x".repeat(200), "value");
+  assert.equal(message.length, "value: expected a number, got ".length + 60);
+  assert.ok(message.endsWith("..."));
+});