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/types/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/types/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;