apps/Alex2Node
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

device: changeReport(cause, fill) sends a ChangeReport on the 2.0 API

Browse source 
The design has it (section 5) and 2.0 lacked it: a ChangeReport could only be
sent with getChangeReport() of 1.x, which has no helper for a contact or a
motion sensor. fill sets what changed, and after unchanged() what did not;
the rest of the context is the state of device.state(). The report goes to
<root>/changeReport. It throws MessageError without a changed property and
resolves with the failure when the device is on no bridge, as raise() does.
Four tests in test/device/raise.test.js.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
David 2026-09-28 21:37:37 +00:00
parent f0ca4c1fa4
commit 2cbcde563e
6 changed files with 165 additions and 6 deletions
Download patch file Download diff file Expand all files Collapse all files

29
src/device/Device.ts
View file

@ -4,7 +4,8 @@ import { AlexaInterface } from "../compat/AlexaInterface.js";
import { AlexaStatusMessage } from "../compat/AlexaStatusMessage.js";
import { DisplayCategory } from "../compat/enums.js";
import type { AlexaInterfaceType } from "../compat/enums.js";
import { MessageError, proactiveEvent, sceneEvent } from "../messages/build.js";
import { changeReport, MessageError, proactiveEvent, sameProperty, sceneEvent } from "../messages/build.js";
import { StateBuilder } from "../messages/StateBuilder.js";
import type { ChangeCause } from "../messages/types.js";
import type { DirectiveHandler, Fill } from "../dispatcher.js";
import type { DisplayCategoryName } from "../registry/catalog.js";
@ -273,7 +274,31 @@ class Device extends EventEmitter {
const bytes = Buffer.byteLength(JSON.stringify(message));
if (bytes > topics.EVENT_BYTES) return refuse(`it is ${bytes} bytes as JSON, Alex2MQTT takes ${topics.EVENT_BYTES}`);
const topic = topics.event(this.rootTopic);
return this.publish(topics.event(this.rootTopic), message);
}
/**
* Say that the state of the device changed, without a directive that asked for it:
*
* door.changeReport("PHYSICAL_INTERACTION", (s) => s.set(contact, "detectionState", "DETECTED"));
*
* fill sets what changed; after unchanged() it sets what did not. The rest of the context is the state of
* device.state(). The report goes to <root>/changeReport, which Alex2MQTT posts to Alexa; Alexa takes it for a
* capability declared with proactivelyReported. Resolves with what became of the publish and does not reject.
*
* Throws a MessageError when fill sets no property that changed, and a SchemaError for a value Alexa would not take.
*/
changeReport(cause: ChangeCause, fill: Fill): Promise<PublishResult> {
const { endpointId } = this;
const own = new StateBuilder({ target: "change" });
fill(own);
const whole = new StateBuilder();
this.stateProvider?.(whole);
const context = [...whole.context.filter((property) => !own.context.some((other) => sameProperty(property, other))), ...own.context];
const message = changeReport({ endpointId, cause, changed: own.change, context });
return this.publish(topics.changeReport(this.rootTopic), message);
}
// A message nobody asked for: a failed publish is reported to the bridge and is the result
private publish(topic: string, message: object): Promise<PublishResult> {
const unpublished = new Error(`nothing was published to ${topic}: the device is on no bridge, register it with addDevice() or registerDevice()`);
const published: Promise<PublishResult> = this.publisher
? this.publisher.publish(topic, message)