dispatch: typed handlers, respond/defer/error, automatic ErrorResponse, watchdog

src/dispatcher.ts routes a directive to capability.on(name | "*"), device.onDirective() or
device.onReportState(), with the payload checked by the descriptor of the interface. The
DirectiveContext answers with respond/report/defer/error; respond() and report() start from
device.state(). A handler or 1.x listener that throws or rejects is answered with INTERNAL_ERROR
(an AlexaError with itself) and reported through "error", never as an unhandled rejection.
Undeclared interface, unknown directive, AdjustMode on an unordered mode and a missing handler
get INVALID_DIRECTIVE, a bad payload INVALID_VALUE; a device with an "Event" or "ReportState"
listener keeps the answer to itself. Every answer passes the dispatcher: the first one per
correlationToken is published, a second is refused. No answer within answerWithinMs (6500,
0 = off, unref'd timer) sends INTERNAL_ERROR and emits "unanswered". A messageId that arrived
in the last 60 s is dropped. New: "unknownEndpoint", options answerUnknownEndpoints, publisher,
timers, and bridge.receive() to run a bridge without a broker. 168 tests pass (18 new).

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

dist/esm/device/Capability.d.ts

@@ -1,3 +1,5 @@
+import type { DirectiveHandler } from "../dispatcher.js";
+import type { Infer } 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 {
@@ -66,10 +68,24 @@ export declare class Capability<P extends Properties = Properties, D extends Dir
     options: O;
     /** What the bridge logs about the declaration, once, when it answers a discovery. */
     readonly notes: string[];
+    private readonly handlers;
     constructor(descriptor: InterfaceDescriptor<P, D, O, boolean>, declared: CommonOptions & {
         options: O;
     });
     get namespace(): string;
+    /**
+     * What the device does on a directive of the interface:
+     *
+     *   lift.on("SetRangeValue", async (ctx) => { await motor.moveTo(ctx.payload.rangeValue); return ctx.respond(); });
+     *
+     * "*" is the handler of every directive that has none of its own. A handler that throws answers the directive
+     * with an ErrorResponse: the AlexaError it threw, INTERNAL_ERROR for anything else. Throws a DeclarationError
+     * for a name that is not a directive of the interface.
+     */
+    on<K extends keyof D & string>(name: K, handler: DirectiveHandler<Infer<D[K]["payload"]>>): this;
+    on(name: "*", handler: DirectiveHandler): this;
+    /** The handler on(name) registered, or the one of "*". */
+    handlerFor(name: string): DirectiveHandler<any> | undefined;
     /** 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. */

dist/esm/device/Capability.js

@@ -1,4 +1,5 @@
 import { s } from "../registry/schema.js";
+import { DeclarationError } from "../registry/types.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()),
@@ -15,6 +16,7 @@ export class Capability {
         this.endpointId = "";
         /** What the bridge logs about the declaration, once, when it answers a discovery. */
         this.notes = [];
+        this.handlers = new Map();
         this.instance = declared.instance ?? "";
         this.friendlyNames = declared.friendlyNames ?? [];
         this.retrievable = declared.retrievable ?? true;
@@ -25,6 +27,21 @@ export class Capability {
     get namespace() {
         return this.descriptor.namespace;
     }
+    on(name, handler) {
+        const names = Object.keys(this.descriptor.directives);
+        // An interface the library only names (tier 3) describes no directive: any name is taken
+        if (name !== "*" && this.descriptor.tier !== 3 && !names.includes(name)) {
+            throw new DeclarationError(this, `${name} is not a directive of the interface, which has ${names.join(", ") || "none"}`);
+        }
+        if (typeof handler !== "function")
+            throw new DeclarationError(this, `the handler of ${name} is a function`);
+        this.handlers.set(name, handler);
+        return this;
+    }
+    /** The handler on(name) registered, or the one of "*". */
+    handlerFor(name) {
+        return this.handlers.get(name) ?? this.handlers.get("*");
+    }
     /** Mappings of "open", "close", "raise", "lower" and of states, when the declaration has any. */
     get semantics() {
         const { semantics } = this.options;

dist/esm/device/Device.d.ts

@@ -5,6 +5,7 @@ import { AlexaStatusMessage } from "../compat/AlexaStatusMessage.js";
 import { DisplayCategory } from "../compat/enums.js";
 import type { AlexaInterfaceType } from "../compat/enums.js";
 import type { ChangeCause } from "../messages/types.js";
+import type { DirectiveHandler, Fill } from "../dispatcher.js";
 import type { DisplayCategoryName } from "../registry/catalog.js";
 import type { Directives, InterfaceDescriptor, Properties } from "../registry/types.js";
 import type { Publisher } from "../transport.js";
@@ -72,6 +73,12 @@ declare class Device extends EventEmitter {
      * is null every send() resolves "" and reports why.
      */
     publisher: Publisher | null;
+    /** Set by state(). */
+    stateProvider?: Fill;
+    /** Set by onReportState(). */
+    reportStateHandler?: DirectiveHandler<Record<string, never>>;
+    /** Set by onDirective(). */
+    directiveHandler?: DirectiveHandler;
     /** client is ignored: in 1.x it was the broker client, and a device could only be built after connect(). */
     constructor(client: unknown, rootTopic: string, name: string, endpointId: string, displayCategory: Array<DisplayCategory> | null, description?: string, manufacturerName?: string, manufacturer?: string, model?: string);
     getName(): string;
@@ -95,6 +102,21 @@ declare class Device extends EventEmitter {
      * (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>;
+    /**
+     * How the device reports its state, every retrievable property of it:
+     *
+     *   blinds.state((s) => s.set(lift, "rangeValue", motor.position).health("OK"));
+     *
+     * ReportState is answered with it, and it is the context of every ctx.respond(), where the handler sets only what
+     * the directive changed. Alexa wants the whole state in both (alexa-response.html, "Synchronous response").
+     */
+    state(fill: Fill): this;
+    /** Answer ReportState in a handler of its own, for a state that has to be read from the device first. */
+    onReportState(handler: DirectiveHandler<Record<string, never>>): this;
+    /** The handler for the directives of declared capabilities that have no handler of their own. */
+    onDirective(handler: DirectiveHandler): this;
+    /** The capability declared for the interface, under the instance for a generic controller. */
+    capability(namespace: string, instance?: string): AnyCapability | undefined;
     /** The capabilities the device declared, in the order it declared them. */
     getCapabilities(): AnyCapability[];
     setManufacturerName(name: string): void;

dist/esm/device/Device.js

@@ -97,6 +97,32 @@ class Device extends EventEmitter {
         const build = () => sceneEvent({ endpointId: this.endpointId, correlationToken, activated, cause });
         return send(this.publisher, answer(this.rootTopic, this.endpointId), build, this.onPublishError);
     }
+    /**
+     * How the device reports its state, every retrievable property of it:
+     *
+     *   blinds.state((s) => s.set(lift, "rangeValue", motor.position).health("OK"));
+     *
+     * ReportState is answered with it, and it is the context of every ctx.respond(), where the handler sets only what
+     * the directive changed. Alexa wants the whole state in both (alexa-response.html, "Synchronous response").
+     */
+    state(fill) {
+        this.stateProvider = fill;
+        return this;
+    }
+    /** Answer ReportState in a handler of its own, for a state that has to be read from the device first. */
+    onReportState(handler) {
+        this.reportStateHandler = handler;
+        return this;
+    }
+    /** The handler for the directives of declared capabilities that have no handler of their own. */
+    onDirective(handler) {
+        this.directiveHandler = handler;
+        return this;
+    }
+    /** The capability declared for the interface, under the instance for a generic controller. */
+    capability(namespace, instance = "") {
+        return this.capabilities.find((capability) => capability.namespace === namespace && capability.instance === instance);
+    }
     /** The capabilities the device declared, in the order it declared them. */
     getCapabilities() {
         return this.capabilities.slice();