messages: pure builders for every event the bridge sends

src/messages builds Response, StateReport, DeferredResponse, ErrorResponse, ChangeReport and the scene, doorbell
and simple events from plain values; messageId and times are parameters, so a test compares whole objects.
StateBuilder collects properties checked by the descriptors, AlexaError and AlexaErrors carry the payload fields
of an error type. AlexaStatusMessage and AlexaErrorResponse move to src/compat and are written on the builders.
On the wire, against 1.5.2: a DeferredResponse has no context key, a ChangeReport has no correlationToken, the
namespace of an ErrorResponse follows its type, and a ChangeReport without a changed property is not published:
send() resolves "" and the bridge reports an error that names the endpoint.
143 tests pass (108 before).

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

dist/esm/messages/StateBuilder.d.ts

@@ -0,0 +1,49 @@
+import { CONNECTIVITY_REASONS } from "../registry/interfaces/EndpointHealth.js";
+import type { Infer } from "../registry/schema.js";
+import type { InterfaceDescriptor, Properties } from "../registry/types.js";
+import type { PropertyOptions } from "./property.js";
+import type { Property } from "./types.js";
+/** Where a property goes in a ChangeReport: with the ones that changed, or with the rest in the context. */
+export type Target = "context" | "change";
+/** A capability of a device: its properties are reported under its instance. */
+interface DeclaredCapability<P extends Properties> {
+    readonly descriptor: InterfaceDescriptor<P, any, any, boolean>;
+    readonly instance: string;
+}
+export interface StateBuilderOptions {
+    /** Where the properties go until changed() or unchanged() says otherwise. Default: "context". */
+    target?: Target;
+    /** The time of a property that is given none. Default: the clock. */
+    now?: () => Date;
+}
+/**
+ * Collects the properties of one message. For a Response or a StateReport they are its context. For a ChangeReport
+ * changed() and unchanged() say which of the two lists the properties that follow belong to.
+ */
+export declare class StateBuilder {
+    private readonly lists;
+    private target;
+    private readonly now;
+    constructor(options?: StateBuilderOptions);
+    /**
+     * A property of an interface the library describes, its value checked: set(PowerController, "powerState", "ON").
+     * Given a capability of a device in place of the interface, the property carries the instance of the capability.
+     * Throws SchemaError for a value Alexa would not take.
+     */
+    set<P extends Properties, K extends keyof P & string>(source: InterfaceDescriptor<P, any, any, boolean> | DeclaredCapability<P>, name: K, value: Infer<P[K]["value"]>, options?: PropertyOptions): this;
+    /** A property as given, nothing checked: for an interface or a value the library does not describe. */
+    setRaw(namespace: string, name: string, value: unknown, options?: PropertyOptions): this;
+    /** The connectivity of Alexa.EndpointHealth, which belongs in every report of an endpoint that declares it. */
+    health(value: "OK" | "UNREACHABLE", reason?: (typeof CONNECTIVITY_REASONS)[number], options?: PropertyOptions): this;
+    /** A property built elsewhere, to the list that is filled now or to the one named. */
+    add(built: Property, target?: Target): this;
+    /** The properties that follow are the ones that changed. */
+    changed(): this;
+    /** The properties that follow did not change: a ChangeReport lists them in its context. */
+    unchanged(): this;
+    /** The properties for the context of the message, in the order they were set. */
+    get context(): Property[];
+    /** The properties for payload.change of a ChangeReport. */
+    get change(): Property[];
+}
+export {};

dist/esm/messages/StateBuilder.js

@@ -0,0 +1,66 @@
+import { EndpointHealth } from "../registry/interfaces/EndpointHealth.js";
+import { SchemaError } from "../registry/schema.js";
+import { property } from "./property.js";
+/**
+ * Collects the properties of one message. For a Response or a StateReport they are its context. For a ChangeReport
+ * changed() and unchanged() say which of the two lists the properties that follow belong to.
+ */
+export class StateBuilder {
+    constructor(options = {}) {
+        this.lists = { context: [], change: [] };
+        this.target = options.target ?? "context";
+        this.now = options.now ?? (() => new Date());
+    }
+    /**
+     * A property of an interface the library describes, its value checked: set(PowerController, "powerState", "ON").
+     * Given a capability of a device in place of the interface, the property carries the instance of the capability.
+     * Throws SchemaError for a value Alexa would not take.
+     */
+    set(source, name, value, options = {}) {
+        const descriptor = "descriptor" in source ? source.descriptor : source;
+        const instance = options.instance ?? ("descriptor" in source ? source.instance : "");
+        const where = `${descriptor.namespace}${instance ? ` "${instance}"` : ""}: ${name}`;
+        const described = descriptor.properties[name];
+        if (!described) {
+            const names = Object.keys(descriptor.properties);
+            throw new SchemaError(where, names.length > 0
+                ? `not a property of the interface, which has ${names.join(", ")}`
+                : "the library knows no property of the interface, report it with setRaw()");
+        }
+        if (descriptor.instanced && !instance) {
+            throw new SchemaError(where, "the interface has instances, pass the one that is reported: { instance: \"Blind.Lift\" }");
+        }
+        return this.setRaw(descriptor.namespace, described.name, described.value.parse(value, where), { ...options, instance });
+    }
+    /** A property as given, nothing checked: for an interface or a value the library does not describe. */
+    setRaw(namespace, name, value, options = {}) {
+        return this.add(property(namespace, name, value, { ...options, timeOfSample: options.timeOfSample ?? this.now() }));
+    }
+    /** The connectivity of Alexa.EndpointHealth, which belongs in every report of an endpoint that declares it. */
+    health(value, reason, options = {}) {
+        return this.set(EndpointHealth, "connectivity", reason ? { value, reason } : { value }, options);
+    }
+    /** A property built elsewhere, to the list that is filled now or to the one named. */
+    add(built, target = this.target) {
+        this.lists[target].push(built);
+        return this;
+    }
+    /** The properties that follow are the ones that changed. */
+    changed() {
+        this.target = "change";
+        return this;
+    }
+    /** The properties that follow did not change: a ChangeReport lists them in its context. */
+    unchanged() {
+        this.target = "context";
+        return this;
+    }
+    /** The properties for the context of the message, in the order they were set. */
+    get context() {
+        return [...this.lists.context];
+    }
+    /** The properties for payload.change of a ChangeReport. */
+    get change() {
+        return [...this.lists.change];
+    }
+}

dist/esm/messages/build.d.ts

@@ -0,0 +1,97 @@
+import type { ChangeCause, ChangeReportMessage, DeferredResponseMessage, ErrorResponseMessage, ProactiveEventMessage, Property, ResponseMessage, SceneEventMessage } from "./types.js";
+/** A message that would be dropped on its way to Alexa, refused where it is built. */
+export declare class MessageError extends Error {
+    readonly endpointId: string;
+    readonly problem: string;
+    constructor(endpointId: string, problem: string);
+}
+interface Envelope {
+    endpointId: string;
+    /** Default: a new version 4 UUID, which is what Alexa recommends (message-guide.html, "Header object"). */
+    messageId?: string;
+}
+interface Answer extends Envelope {
+    /** The correlationToken of the directive that is answered. */
+    correlationToken: string;
+}
+export interface ResponseFields extends Answer {
+    /** Default: "Response". */
+    name?: string;
+    /** Default: "Alexa". An interface with a response of its own names it: Alexa.SecurityPanelController, Arm.Response. */
+    namespace?: string;
+    payload?: Record<string, unknown>;
+    /** The state of the endpoint after the directive. */
+    context?: readonly Property[];
+}
+/**
+ * The answer to a directive (alexa-response.html, "Synchronous response"). An endpoint with nothing to report
+ * answers with an empty list of properties, not without a context (state-reporting-for-smart-home-addons.html,
+ * "Directive response example for a property that isn't retrievable").
+ */
+export declare function response(fields: ResponseFields): ResponseMessage;
+/** The answer to ReportState: every retrievable property of the endpoint. */
+export declare function stateReport(fields: Answer & {
+    context?: readonly Property[];
+}): ResponseMessage;
+/**
+ * "The directive arrived, the answer follows": no context, the state is in the Response that follows
+ * (alexa-response.html, "Deferred response example").
+ */
+export declare function deferredResponse(fields: Answer & {
+    estimatedDeferralInSeconds?: number;
+}): DeferredResponseMessage;
+export interface ErrorResponseFields extends Answer {
+    /** "ENDPOINT_UNREACHABLE" */
+    type: string;
+    /** For the log of the skill. */
+    message: string;
+    /** The fields a type adds to the payload: validRange, currentDeviceMode. */
+    extra?: Record<string, unknown>;
+    /** Default: the namespace the type is documented under, see errorNamespace(). */
+    namespace?: string;
+}
+/** The answer to a directive the endpoint could not follow (alexa-errorresponse.html). */
+export declare function errorResponse(fields: ErrorResponseFields): ErrorResponseMessage;
+export interface ChangeReportFields extends Envelope {
+    /** Default: "PHYSICAL_INTERACTION". */
+    cause?: ChangeCause;
+    /** The properties that changed, at least one. */
+    changed: readonly Property[];
+    /** The other properties of the endpoint, as they are now. */
+    context?: readonly Property[];
+}
+/**
+ * A change of state nobody asked for. The header has no correlationToken (message-guide.html, "Header object").
+ * A property that changed is left out of the context: it is reported in one of the two (same page, "Context
+ * object"). Throws MessageError when nothing changed: Alex2MQTT drops such a report without a word.
+ */
+export declare function changeReport(fields: ChangeReportFields): ChangeReportMessage;
+export interface SceneEventFields extends Answer {
+    /** true: ActivationStarted. false: DeactivationStarted. */
+    activated: boolean;
+    /** Default: "VOICE_INTERACTION", a scene is started by a directive. */
+    cause?: ChangeCause;
+    /** When the scene started. Default: now. */
+    timestamp?: string | Date;
+}
+/** The answer to Activate and Deactivate of a scene (alexa-scenecontroller.html). */
+export declare function sceneEvent(fields: SceneEventFields): SceneEventMessage;
+export interface DoorbellPressFields extends Envelope {
+    /** Default: "PHYSICAL_INTERACTION", somebody pressed the button. */
+    cause?: ChangeCause;
+    /** When the button was pressed. Default: now. */
+    timestamp?: string | Date;
+}
+/** Somebody rang (alexa-doorbelleventsource.html). */
+export declare function doorbellPress(fields: DoorbellPressFields): ProactiveEventMessage;
+export interface SimpleEventFields extends Envelope {
+    /** The instance of Alexa.SimpleEventSource that raises the event. */
+    instance: string;
+    /** The id of the event as discovery listed it: "Button.SinglePush.1". */
+    id: string;
+    /** When the event happened. Default: now. */
+    timestamp?: string | Date;
+}
+/** An event of a button or a sensor that routines start on (alexa-simpleeventsource.html). */
+export declare function simpleEvent(fields: SimpleEventFields): ProactiveEventMessage;
+export {};

dist/esm/messages/build.js

@@ -0,0 +1,124 @@
+// Every message the bridge publishes, built from plain values. Nothing here reads the clock or makes an id unless
+// the caller leaves messageId or a time out, so a test that passes both compares whole objects.
+import { randomUUID } from "crypto";
+import { errorNamespace } from "./errors.js";
+import { isoTime } from "./property.js";
+/** A message that would be dropped on its way to Alexa, refused where it is built. */
+export class MessageError extends Error {
+    constructor(endpointId, problem) {
+        super(`${endpointId}: ${problem}`);
+        this.endpointId = endpointId;
+        this.problem = problem;
+        this.name = "MessageError";
+    }
+}
+// The fields in the order of the examples
+function header(namespace, name, fields) {
+    return {
+        namespace,
+        name,
+        ...(fields.instance ? { instance: fields.instance } : {}),
+        messageId: fields.messageId ?? randomUUID(),
+        ...(fields.correlationToken !== undefined ? { correlationToken: fields.correlationToken } : {}),
+        payloadVersion: fields.payloadVersion ?? "3",
+    };
+}
+/**
+ * The answer to a directive (alexa-response.html, "Synchronous response"). An endpoint with nothing to report
+ * answers with an empty list of properties, not without a context (state-reporting-for-smart-home-addons.html,
+ * "Directive response example for a property that isn't retrievable").
+ */
+export function response(fields) {
+    return {
+        event: {
+            header: header(fields.namespace ?? "Alexa", fields.name ?? "Response", fields),
+            endpoint: { endpointId: fields.endpointId },
+            payload: fields.payload ?? {},
+        },
+        context: { properties: [...(fields.context ?? [])] },
+    };
+}
+/** The answer to ReportState: every retrievable property of the endpoint. */
+export function stateReport(fields) {
+    return response({ ...fields, name: "StateReport", namespace: "Alexa", payload: {} });
+}
+/**
+ * "The directive arrived, the answer follows": no context, the state is in the Response that follows
+ * (alexa-response.html, "Deferred response example").
+ */
+export function deferredResponse(fields) {
+    const { estimatedDeferralInSeconds } = fields;
+    return {
+        event: {
+            header: header("Alexa", "DeferredResponse", fields),
+            endpoint: { endpointId: fields.endpointId },
+            payload: estimatedDeferralInSeconds === undefined ? {} : { estimatedDeferralInSeconds },
+        },
+    };
+}
+/** The answer to a directive the endpoint could not follow (alexa-errorresponse.html). */
+export function errorResponse(fields) {
+    return {
+        event: {
+            header: header(fields.namespace ?? errorNamespace(fields.type), "ErrorResponse", fields),
+            endpoint: { endpointId: fields.endpointId },
+            payload: { type: fields.type, message: fields.message, ...fields.extra },
+        },
+    };
+}
+const sameProperty = (a, b) => a.namespace === b.namespace && a.name === b.name && (a.instance ?? "") === (b.instance ?? "");
+/**
+ * A change of state nobody asked for. The header has no correlationToken (message-guide.html, "Header object").
+ * A property that changed is left out of the context: it is reported in one of the two (same page, "Context
+ * object"). Throws MessageError when nothing changed: Alex2MQTT drops such a report without a word.
+ */
+export function changeReport(fields) {
+    const { endpointId, changed, context = [] } = fields;
+    if (changed.length === 0) {
+        throw new MessageError(endpointId, "a ChangeReport needs at least one property that changed, this one has none. "
+            + "Add the changed property before unchanged(), or send no report when nothing changed");
+    }
+    return {
+        event: {
+            header: header("Alexa", "ChangeReport", { messageId: fields.messageId }),
+            endpoint: { endpointId },
+            payload: { change: { cause: { type: fields.cause ?? "PHYSICAL_INTERACTION" }, properties: [...changed] } },
+        },
+        context: { properties: context.filter((property) => !changed.some((other) => sameProperty(property, other))) },
+    };
+}
+/** The answer to Activate and Deactivate of a scene (alexa-scenecontroller.html). */
+export function sceneEvent(fields) {
+    return {
+        event: {
+            header: header("Alexa.SceneController", fields.activated ? "ActivationStarted" : "DeactivationStarted", fields),
+            endpoint: { endpointId: fields.endpointId },
+            payload: { cause: { type: fields.cause ?? "VOICE_INTERACTION" }, timestamp: isoTime(fields.timestamp) },
+        },
+        context: {},
+    };
+}
+/** Somebody rang (alexa-doorbelleventsource.html). */
+export function doorbellPress(fields) {
+    return {
+        event: {
+            header: header("Alexa.DoorbellEventSource", "DoorbellPress", { messageId: fields.messageId }),
+            endpoint: { endpointId: fields.endpointId },
+            payload: { cause: { type: fields.cause ?? "PHYSICAL_INTERACTION" }, timestamp: isoTime(fields.timestamp) },
+        },
+    };
+}
+/** An event of a button or a sensor that routines start on (alexa-simpleeventsource.html). */
+export function simpleEvent(fields) {
+    return {
+        event: {
+            header: header("Alexa.SimpleEventSource", "Event", {
+                instance: fields.instance,
+                messageId: fields.messageId,
+                payloadVersion: "1.0",
+            }),
+            endpoint: { endpointId: fields.endpointId },
+            payload: { id: fields.id, timestamp: isoTime(fields.timestamp) },
+        },
+    };
+}

dist/esm/messages/errors.d.ts

@@ -0,0 +1,52 @@
+import type { Temperature } from "../registry/schema.js";
+/**
+ * The namespace an ErrorResponse of this type goes under: the one the table of error types lists it with
+ * (THERMOSTAT_IS_OFF: Alexa.ThermostatController, OBSTACLE_DETECTED: Alexa.Safety), Alexa for a type the table
+ * does not have.
+ */
+export declare function errorNamespace(type: string): string;
+/** Thrown by a directive handler, or built to be sent: the directive is answered with this ErrorResponse. */
+export declare class AlexaError extends Error {
+    /** "ENDPOINT_UNREACHABLE" */
+    readonly type: string;
+    /** payload.message: for the log of the skill, Alexa does not read it to the user. */
+    readonly alexaMessage: string;
+    /** The fields of the payload next to type and message. */
+    readonly extra: Record<string, unknown>;
+    /** The namespace of the header. */
+    readonly namespace: string;
+    constructor(type: string, message: string, extra?: Record<string, unknown>, namespace?: string);
+}
+export type CurrentDeviceMode = "ASLEEP" | "COLOR" | "DEMAND_RESPONSE" | "ECO" | "NOT_PROVISIONED" | "VACATION" | "OTHER";
+export type ControlUnavailableReason = "DEEP_SLEEP_MODE" | "OUT_OF_NETWORK_CONNECTIVITY" | "NO_CONNECTIVITY_PACKAGE_ENABLED" | "UNKNOWN";
+export type ChargeState = "ALREADY_CHARGED_TO_REQUIRED_LEVEL" | "CURRENTLY_CHARGING" | "FULLY_CHARGED" | "NOT_CONNECTED_TO_POWER";
+export declare const AlexaErrors: {
+    /** An error of any type. */
+    of(type: string, message: string, extra?: Record<string, unknown>): AlexaError;
+    /** The value is outside what the endpoint takes. For a temperature: temperatureOutOfRange(). */
+    valueOutOfRange(message: string, validRange: {
+        minimumValue: number;
+        maximumValue: number;
+    }): AlexaError;
+    temperatureOutOfRange(message: string, validRange: {
+        minimumValue: Temperature;
+        maximumValue: Temperature;
+    }): AlexaError;
+    /** A light showing a color asked for a color temperature: "COLOR". */
+    notSupportedInCurrentMode(message: string, currentDeviceMode: CurrentDeviceMode): AlexaError;
+    /** percentageState: what is left of the battery, 0 to 100. */
+    endpointLowPower(message: string, percentageState?: number): AlexaError;
+    endpointControlUnavailable(message: string, reason: ControlUnavailableReason): AlexaError;
+    notSupportedWithCurrentBatteryChargeState(message: string, currentChargeState: ChargeState, currentChargeLevelInPercentage?: number): AlexaError;
+    /** What has to be refilled. */
+    insufficientResource(message: string, resourceType: "WATER"): AlexaError;
+    /** What the user has to do first. */
+    maintenanceRequired(message: string, maintenanceAction?: "EMPTY_BIN"): AlexaError;
+    /** Goes under Alexa.ThermostatController. minimumTemperatureDelta: how far apart the setpoints have to be. */
+    setpointsTooClose(message: string, minimumTemperatureDelta?: Temperature): AlexaError;
+    /** Goes under Alexa.SecurityPanelController. With the endpoints listed, the user can bypass them by voice. */
+    bypassNeeded(message: string, endpointsNeedingBypass?: Array<{
+        friendlyName: string;
+        endpointId?: string;
+    }>): AlexaError;
+};

dist/esm/messages/errors.js

@@ -0,0 +1,69 @@
+// The errors a device answers a directive with (alexa-errorresponse.html). A helper for each type whose payload
+// has fields of its own, so that the fields cannot be misspelt.
+import { ERROR_TYPES } from "../registry/catalog.js";
+/**
+ * The namespace an ErrorResponse of this type goes under: the one the table of error types lists it with
+ * (THERMOSTAT_IS_OFF: Alexa.ThermostatController, OBSTACLE_DETECTED: Alexa.Safety), Alexa for a type the table
+ * does not have.
+ */
+export function errorNamespace(type) {
+    return Object.prototype.hasOwnProperty.call(ERROR_TYPES, type) ? ERROR_TYPES[type] : "Alexa";
+}
+/** Thrown by a directive handler, or built to be sent: the directive is answered with this ErrorResponse. */
+export class AlexaError extends Error {
+    constructor(type, message, extra = {}, namespace = errorNamespace(type)) {
+        super(`${type}: ${message}`);
+        this.name = "AlexaError";
+        this.type = type;
+        this.alexaMessage = message;
+        this.extra = extra;
+        this.namespace = namespace;
+    }
+}
+// A field that was not given is left out of the payload
+function given(fields) {
+    return Object.fromEntries(Object.entries(fields).filter(([, value]) => value !== undefined));
+}
+export const AlexaErrors = {
+    /** An error of any type. */
+    of(type, message, extra = {}) {
+        return new AlexaError(type, message, extra);
+    },
+    /** The value is outside what the endpoint takes. For a temperature: temperatureOutOfRange(). */
+    valueOutOfRange(message, validRange) {
+        return new AlexaError("VALUE_OUT_OF_RANGE", message, { validRange });
+    },
+    temperatureOutOfRange(message, validRange) {
+        return new AlexaError("TEMPERATURE_VALUE_OUT_OF_RANGE", message, { validRange });
+    },
+    /** A light showing a color asked for a color temperature: "COLOR". */
+    notSupportedInCurrentMode(message, currentDeviceMode) {
+        return new AlexaError("NOT_SUPPORTED_IN_CURRENT_MODE", message, { currentDeviceMode });
+    },
+    /** percentageState: what is left of the battery, 0 to 100. */
+    endpointLowPower(message, percentageState) {
+        return new AlexaError("ENDPOINT_LOW_POWER", message, given({ percentageState }));
+    },
+    endpointControlUnavailable(message, reason) {
+        return new AlexaError("ENDPOINT_CONTROL_UNAVAILABLE", message, { reason });
+    },
+    notSupportedWithCurrentBatteryChargeState(message, currentChargeState, currentChargeLevelInPercentage) {
+        return new AlexaError("NOT_SUPPORTED_WITH_CURRENT_BATTERY_CHARGE_STATE", message, given({ currentChargeState, currentChargeLevelInPercentage }));
+    },
+    /** What has to be refilled. */
+    insufficientResource(message, resourceType) {
+        return new AlexaError("INSUFFICIENT_RESOURCE", message, { resourceType });
+    },
+    /** What the user has to do first. */
+    maintenanceRequired(message, maintenanceAction) {
+        return new AlexaError("MAINTENANCE_REQUIRED", message, given({ maintenanceAction }));
+    },
+    /** Goes under Alexa.ThermostatController. minimumTemperatureDelta: how far apart the setpoints have to be. */
+    setpointsTooClose(message, minimumTemperatureDelta) {
+        return new AlexaError("REQUESTED_SETPOINTS_TOO_CLOSE", message, given({ minimumTemperatureDelta }));
+    },
+    /** Goes under Alexa.SecurityPanelController. With the endpoints listed, the user can bypass them by voice. */
+    bypassNeeded(message, endpointsNeedingBypass) {
+        return new AlexaError("BYPASS_NEEDED", message, given({ endpointsNeedingBypass }));
+    },
+};

dist/esm/messages/index.d.ts

@@ -0,0 +1,9 @@
+export { changeReport, deferredResponse, doorbellPress, errorResponse, response, sceneEvent, simpleEvent, stateReport, MessageError, } from "./build.js";
+export type { ChangeReportFields, DoorbellPressFields, ErrorResponseFields, ResponseFields, SceneEventFields, SimpleEventFields, } from "./build.js";
+export { AlexaError, AlexaErrors, errorNamespace } from "./errors.js";
+export type { ChargeState, ControlUnavailableReason, CurrentDeviceMode } from "./errors.js";
+export { property } from "./property.js";
+export type { PropertyOptions } from "./property.js";
+export { StateBuilder } from "./StateBuilder.js";
+export type { StateBuilderOptions, Target } from "./StateBuilder.js";
+export type { ChangeCause, ChangeReportMessage, Context, DeferredResponseMessage, Endpoint, ErrorResponseMessage, Event, Header, ProactiveEventMessage, Property, ResponseMessage, SceneEventMessage, } from "./types.js";

dist/esm/messages/index.js

@@ -0,0 +1,5 @@
+// The messages of the bridge without the bridge: builders, the state collector and the errors.
+export { changeReport, deferredResponse, doorbellPress, errorResponse, response, sceneEvent, simpleEvent, stateReport, MessageError, } from "./build.js";
+export { AlexaError, AlexaErrors, errorNamespace } from "./errors.js";
+export { property } from "./property.js";
+export { StateBuilder } from "./StateBuilder.js";

dist/esm/messages/property.d.ts

@@ -0,0 +1,16 @@
+import type { Property } from "./types.js";
+export interface PropertyOptions {
+    /** The instance of a generic controller: "Blind.Lift". */
+    instance?: string;
+    /**
+     * When the value last changed. Default: now. message-guide.html, "Property object": "don't set the same
+     * timeOfSample value for all properties", so a device that knows when each value changed passes it.
+     */
+    timeOfSample?: string | Date;
+    /** How old the value may be, for a device that is polled. Default: 0. */
+    uncertaintyInMilliseconds?: number;
+}
+/** A time as Alexa wants it: ISO 8601 in UTC. Text is taken as given. */
+export declare function isoTime(time?: string | Date): string;
+/** One property of a context or of a change, its fields in the order of the examples. */
+export declare function property(namespace: string, name: string, value: unknown, options?: PropertyOptions): Property;

dist/esm/messages/property.js

@@ -0,0 +1,15 @@
+/** A time as Alexa wants it: ISO 8601 in UTC. Text is taken as given. */
+export function isoTime(time = new Date()) {
+    return typeof time === "string" ? time : time.toISOString();
+}
+/** One property of a context or of a change, its fields in the order of the examples. */
+export function property(namespace, name, value, options = {}) {
+    return {
+        namespace,
+        ...(options.instance ? { instance: options.instance } : {}),
+        name,
+        value,
+        timeOfSample: isoTime(options.timeOfSample),
+        uncertaintyInMilliseconds: options.uncertaintyInMilliseconds ?? 0,
+    };
+}

dist/esm/messages/types.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Why a property changed or an event was raised (message-guide.html, "Cause object"). RULE_TRIGGER is not in that
+ * table; the ChangeReport examples of alexa-securitypanelcontroller.html and alexa-thermostatcontroller.html use it.
+ */
+export type ChangeCause = "APP_INTERACTION" | "PERIODIC_POLL" | "PHYSICAL_INTERACTION" | "RULE_TRIGGER" | "VOICE_INTERACTION";
+export interface Header {
+    namespace: string;
+    name: string;
+    /** Alexa.SimpleEventSource: the instance that raised the event. */
+    instance?: string;
+    messageId: string;
+    /** The token of the directive that is answered. An event nobody asked for has none. */
+    correlationToken?: string;
+    payloadVersion: string;
+}
+export interface Endpoint {
+    endpointId: string;
+}
+/** One reported property (message-guide.html, "Property object"). */
+export interface Property {
+    namespace: string;
+    /** The instance of a generic controller. */
+    instance?: string;
+    name: string;
+    value: unknown;
+    /** When the value was sampled or last changed, ISO 8601 in UTC. */
+    timeOfSample: string;
+    uncertaintyInMilliseconds: number;
+}
+export interface Event<P = Record<string, unknown>> {
+    header: Header;
+    endpoint: Endpoint;
+    payload: P;
+}
+export interface Context {
+    properties: Property[];
+}
+/** A Response, a StateReport or the response of an interface that has its own (Arm.Response). */
+export interface ResponseMessage {
+    event: Event;
+    context: Context;
+}
+export interface DeferredResponseMessage {
+    event: Event<{
+        estimatedDeferralInSeconds?: number;
+    }>;
+}
+export interface ErrorResponseMessage {
+    event: Event<{
+        type: string;
+        message: string;
+    } & Record<string, unknown>>;
+}
+export interface ChangeReportMessage {
+    event: Event<{
+        change: {
+            cause: {
+                type: ChangeCause;
+            };
+            properties: Property[];
+        };
+    }>;
+    context: Context;
+}
+/** ActivationStarted or DeactivationStarted of a scene. */
+export interface SceneEventMessage {
+    event: Event<{
+        cause: {
+            type: ChangeCause;
+        };
+        timestamp: string;
+    }>;
+    context: {};
+}
+/** An event a device raises by itself: DoorbellPress, the Event of Alexa.SimpleEventSource. */
+export interface ProactiveEventMessage {
+    event: Event;
+}

dist/esm/messages/types.js

@@ -0,0 +1,2 @@
+// The messages the bridge publishes, as message-guide.html and alexa-response.html draw them.
+export {};