David
c492ef74d1
A capability is a descriptor plus what the endpoint declares (device/Capability.ts), and its discovery object is
generated from the two. The new API is bridge.addDevice({ endpointId, name, categories, ... }) and
device.add(PowerController, options): both throw a DeclarationError that names the endpoint, the interface and
the instance (device/validate.ts), and leave the bridge and the device as they were. AlexaInterface is the same
Capability with the 1.x methods on it; it, ActionMapping and the enums moved to src/compat/, Device to src/device/.
What a 1.x caller can observe:
- every endpoint ends with { type: "AlexaInterface", interface: "Alexa", version: "3" } (alexa-interface.html);
new Alex2MQTT(..., { alexaInterface: false }) leaves it out
- the fields of a capability object come in the order of Amazon's examples; their content is unchanged
- addCapability() with a name that is not an interface throws (1.5.2 announced it with the version "UNKNOWN")
- ActionMapping takes the payload as an object; a JSON string is parsed (1.5.2 sent the string), any other throws
- what Alexa would reject in a 1.x declaration is not refused: device.check() lists it and the bridge logs each
line once, as "warning: ..." through the log hook, when it answers a discovery
- a device whose JSON cannot be built is left out of the answer and reported as an error event
- PowerController and EndpointHealth are the descriptors and keep ON/OFF and OK/UNREACHABLE; PowerState is new
Tests: six zoo devices declared the 1.x way give the JSON that Alexa accepted from 1.5.2 on 2026-09-28, plus the
Alexa capability. npm test: 85 pass (was 57) in 10-12 s, also on Node 18.20.8 and 20.20.2.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
74 lines
3.6 KiB
TypeScript
74 lines
3.6 KiB
TypeScript
import type { EndpointHealth, PowerController } from "./compat/enums.js";
|
|
import type { MqttClient } from "mqtt";
|
|
export declare enum ThermostatMode {
|
|
OFF = "OFF",
|
|
HEAT = "HEAT",
|
|
COOL = "COOL",
|
|
AUTO = "AUTO",
|
|
ECO = "ECO",
|
|
CUSTOM = "CUSTOM"
|
|
}
|
|
export declare enum TemperatureSensorScale {
|
|
CELSIUS = "CELSIUS",
|
|
FAHRENHEIT = "FAHRENHEIT"
|
|
}
|
|
interface ContextProperty {
|
|
namespace: string;
|
|
name: string;
|
|
value: any;
|
|
timeOfSample: string;
|
|
uncertaintyInMilliseconds: number;
|
|
instance?: string;
|
|
}
|
|
/** Why a ChangeReport is sent (Alexa.ChangeReport payload.change.cause.type). */
|
|
export type ChangeCause = "APP_INTERACTION" | "PHYSICAL_INTERACTION" | "PERIODIC_POLL" | "RULE_TRIGGER" | "VOICE_INTERACTION";
|
|
export declare class AlexaStatusMessage {
|
|
private context;
|
|
/** ChangeReport only: the properties that changed (payload.change.properties); the rest go to context. */
|
|
private changeProps;
|
|
private changeCause;
|
|
private target;
|
|
private event;
|
|
private rootTopic;
|
|
private endpointId;
|
|
private mqttClient;
|
|
private isDeferred;
|
|
/** Where a failed publish is reported (set by the Device that built this message, 1.5.2): send() never rejects. */
|
|
onPublishError?: (err: Error) => void;
|
|
constructor(correlationToken: string, rootTopic: string, endpointId: string, mqttClient: MqttClient, isResponse?: boolean, isDeferred?: boolean, changeCause?: ChangeCause | null);
|
|
private getTimestamp;
|
|
private addProperty;
|
|
/** ChangeReport: the add*Prop calls that follow describe what CHANGED (the default for a change report). */
|
|
changed(): this;
|
|
/** ChangeReport: the add*Prop calls that follow describe the other, unchanged properties (context). */
|
|
unchanged(): this;
|
|
/** True for a ChangeReport (Device.getChangeReport). */
|
|
isChangeReport(): boolean;
|
|
/** The message as it will be published (for tests and logging). */
|
|
toJSON(): {
|
|
event: any;
|
|
context: {
|
|
properties: ContextProperty[];
|
|
} | null;
|
|
};
|
|
addModeControllerProp(instance: string, value: string, uncertaintyInMs?: number): this;
|
|
addThermostatModeProp(mode: string, uncertaintyInMs?: number): this;
|
|
addEstimatedDeferralTime(seconds: number): this;
|
|
addThermostatControllerProp(name: "lowerSetpoint" | "upperSetpoint" | "targetSetpoint", scale: TemperatureSensorScale, value: number, uncertaintyInMs?: number): this;
|
|
/** Alexa.EndpointHealth connectivity: EndpointHealth.OK / UNREACHABLE (the plain strings "OK" / "UNREACHABLE" are accepted too). */
|
|
addHealthProp(health: EndpointHealth | `${EndpointHealth}`, uncertaintyInMs?: number): this;
|
|
addPowerControllerProp(power: PowerController, uncertaintyInMs?: number): this;
|
|
addTemperatureSensorProp(scale: TemperatureSensorScale, value: number, uncertaintyInMs?: number): this;
|
|
addBrightnessControllerProp(brightness: number, uncertaintyInMs?: number): this;
|
|
addColorTemperatureControllerProp(colorTemp: number, uncertaintyInMs?: number): this;
|
|
addToggleControllerProp(state: PowerController, instance: string, uncertaintyInMs?: number): this;
|
|
addContextProp(prop: ContextProperty): this;
|
|
/**
|
|
* Publish: a Response/StateReport to <root>/<endpoint>/alexaResponce (sendAsync: deferredResponse), a ChangeReport
|
|
* to <root>/changeReport (Alex2MQTT adds the user's token and posts it to the Alexa event gateway). Resolves with
|
|
* the topic, or "" when the publish failed - the error then goes to the bridge's "error" event (when listened to).
|
|
* Never rejects (1.5.1 did, so an un-caught send() could kill the host).
|
|
*/
|
|
send(sendAsync?: boolean): Promise<string>;
|
|
}
|
|
export {};
|