The interface registry, generated and checked discovery, typed dispatch with
automatic error answers, message builders, proactive events and typed
helpers for every error type; the 1.x API is kept and the examples of 1.5.2
run unchanged. docs/wire-changes.md lists what a 1.x caller can observe.
On 2026-09-28 a real Alexa account drove 33 test devices on this API through
the public Alex2MQTT service: Alexa accepted the discovery of all of them,
50 of 58 cases passed, 4 had no action in the control call and 4 failed on
what the check could see, none on an answer of the library. The readme table
names the interfaces that run covered. Voice commands were not tested yet.
307 tests.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
The readme is rewritten for 2.0: what the library needs, install, the lamp
as quick start, concepts, the table of interfaces, recipes, the bridge
contract, errors, testing without Alexa, migration from 1.x and limits.
scripts/capability-table.js (npm run docs) writes the table from the
registry and the text of three example files into their code blocks;
"Through Alexa" names only the runs of 2026-09-28, made with 1.5.2.
test/readme.test.js fails on a stale table or file, runs
examples/testing/lamp.test.js (MemoryPublisher, no broker) and compiles the
other code blocks. package.json: description, keywords, CHANGELOG.md in files.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
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>
An ES module TypeScript consumer was given the CommonJS declarations in dist/types. With those,
`import alex2node from "alex2node"` compiled (module Node16) and then failed when Node loaded it: "The requested
module 'alex2node' does not provide an export named 'default'". The ES module build has named exports only.
tsconfig.esm.json now emits declarations next to dist/esm/*.js, under that directory's {"type": "module"}, and
"exports" selects per condition: import -> dist/esm/index.d.ts, require -> dist/types/index.d.ts. The default
import is now refused with TS1192; named imports are unchanged. "main", "module" and "types" are as before.
test/fixtures/types.mts holds the default import under @ts-expect-error, and a new test requires "types" before
"default" and a declaration for every built file. dist/: 25 files, 132,291 B -> 33 files, 155,647 B; the npm
tarball 25,125 B -> 25,837 B. npm test: 25 pass in 5.6 s.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@types/node was not declared. It was installed only because mqtt's @types/readable-stream and @types/ws depend on
"@types/node": "*", and it resolved to 26.6.2, so an API newer than the "engines" floor passed the type check and
the build depended on another package's dependency list.
@types/node ^18.19.130 is now a devDependency (undici-types follows, 8.9.0 -> 5.26.5). A call to
process.loadEnvFile() (Node 20.12) in src/ now fails with TS2339. npm run check passes, the fixture compile with
skipLibCheck off included, so mqtt's declarations hold against the Node 18 types.
First run on the floor: npm test passes 24/24 on Node 18.20.8 and 20.20.2 as well as 24.21.0. No change to src/ or
dist/.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
"exports" gains "import" and "types" next to "require": import "alex2node" failed with
ERR_PACKAGE_PATH_NOT_EXPORTED. scripts/build.mjs compiles src/ to dist/cjs, dist/esm and dist/types in a staging
directory and swaps them in only when both compiler runs passed. "main" and "types" follow for resolvers that do
not read "exports". Target ES6 -> ES2020, "engines": node >= 18, relative imports carry ".js" for Node's ESM loader.
uuid gives way to crypto.randomUUID(); mqtt is the only runtime dependency left.
Tests load the package by name. New: both entry points, the modules the builds import, dist/ equal to a fresh
build, a round trip on the ES module build, and two compiled type fixtures in place of the .d.ts regexes.
22 tests pass in 5.7 s. dist/: 16 files, 79,711 B -> 25 files, 132,291 B; the npm tarball is 25,125 B.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
