discovery: generate capability JSON from the registry
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>
This commit is contained in:
parent
aa0ffd64ea
commit
c492ef74d1
90 changed files with 5539 additions and 1760 deletions
135
dist/esm/device/Device.d.ts
vendored
Normal file
135
dist/esm/device/Device.d.ts
vendored
Normal file
|
|
@ -0,0 +1,135 @@
|
|||
import { EventEmitter } from "events";
|
||||
import type { MqttClient } from "mqtt";
|
||||
import { AlexaErrorResponse } from "../AlexaErrorResponse.js";
|
||||
import { AlexaStatusMessage } from "../AlexaStatusMessage.js";
|
||||
import type { ChangeCause } from "../AlexaStatusMessage.js";
|
||||
import { AlexaInterface } from "../compat/AlexaInterface.js";
|
||||
import { DisplayCategory } from "../compat/enums.js";
|
||||
import type { AlexaInterfaceType } from "../compat/enums.js";
|
||||
import type { DisplayCategoryName } from "../registry/catalog.js";
|
||||
import type { Directives, InterfaceDescriptor, Properties } from "../registry/types.js";
|
||||
import { Capability } from "./Capability.js";
|
||||
import type { AnyCapability, CapabilityJson, Declaration } from "./Capability.js";
|
||||
import type { EndpointFields } from "./validate.js";
|
||||
/** An endpoint as bridge.addDevice() takes it. */
|
||||
export interface EndpointDefinition {
|
||||
/** Up to 256 letters, digits, spaces and _ - = # ; : ? @ &. The same id at every discovery. */
|
||||
endpointId: string;
|
||||
/** What the user calls the device: letters, digits and spaces. */
|
||||
name: string;
|
||||
/** The first one is the category the Alexa app shows the device under. */
|
||||
categories: Array<DisplayCategoryName | DisplayCategory>;
|
||||
/** Shown in the Alexa app, up to 128 characters. Default: "Alexa to Node.js bridge". */
|
||||
description?: string;
|
||||
/** Up to 128 characters. Default: "Alex2Node". */
|
||||
manufacturerName?: string;
|
||||
manufacturer?: string;
|
||||
model?: string;
|
||||
serialNumber?: string;
|
||||
firmwareVersion?: string;
|
||||
softwareVersion?: string;
|
||||
customIdentifier?: string;
|
||||
/** Returned with every directive to the endpoint. Up to 5000 bytes; not a place for state. */
|
||||
cookie?: Record<string, string>;
|
||||
/** false: the device gets no Alexa.EndpointHealth unless it declares one. */
|
||||
endpointHealth?: boolean;
|
||||
}
|
||||
/** An endpoint object of a discovery answer (alexa-discovery-objects.html, "Endpoint object"). */
|
||||
export interface EndpointJson extends EndpointFields {
|
||||
capabilities: CapabilityJson[];
|
||||
}
|
||||
type DeclarationArguments<O, I extends boolean> = {} extends Declaration<O, I> ? [options?: Declaration<O, I>] : [options: Declaration<O, I>];
|
||||
declare class Device extends EventEmitter {
|
||||
private mqttClient;
|
||||
private rootTopic;
|
||||
name: string;
|
||||
endpointId: string;
|
||||
displayCategory: Array<DisplayCategory> | null;
|
||||
description: string;
|
||||
manufacturerName: string;
|
||||
manufacturer: string;
|
||||
model: string;
|
||||
softwareVersion: string;
|
||||
serialNumber: string;
|
||||
firmwareVersion: string;
|
||||
customIdentifier: string;
|
||||
cookie?: Record<string, string>;
|
||||
/**
|
||||
* Discovery lists the Alexa interface on the endpoint (alexa-interface.html: "You must explicitly identify your
|
||||
* support for the Alexa interface"). The bridge sets it from its alexaInterface option.
|
||||
*/
|
||||
alexaInterface: boolean;
|
||||
/**
|
||||
* Discovery lists Alexa.EndpointHealth when the device did not declare it and is not a scene. On for a device of
|
||||
* bridge.addDevice(), off for one of registerDevice(), which is announced as 1.x announced it.
|
||||
*/
|
||||
endpointHealth: boolean;
|
||||
private capabilities;
|
||||
/** Where a failed publish from this device or a message it built is reported; Alex2MQTT sets it (1.5.2). */
|
||||
onPublishError?: (err: Error) => void;
|
||||
constructor(mqttClient: MqttClient, rootTopic: string, name: string, endpointId: string, displayCategory: Array<DisplayCategory> | null, description?: string, manufacturerName?: string, manufacturer?: string, model?: string);
|
||||
/** Internal (1.5.2): Alex2MQTT.connect() re-binds every registered device to its new broker client after a disconnect(). */
|
||||
setMqttClient(client: MqttClient): void;
|
||||
getName(): string;
|
||||
setName(name: string): void;
|
||||
getEndpointId(): string;
|
||||
setDisplayCategory(category: DisplayCategory | DisplayCategory[]): void;
|
||||
getDisplayCategory(): Array<DisplayCategory>;
|
||||
setDescription(description: string): void;
|
||||
getDescription(): string;
|
||||
getErrorMessage(correlationToken: string): AlexaErrorResponse;
|
||||
getStatusMessage(correlationToken: string, isResponse?: boolean, isDeferred?: boolean): AlexaStatusMessage;
|
||||
/**
|
||||
* A proactive Alexa.ChangeReport (1.5.1): add the changed properties (the default target), optionally
|
||||
* .unchanged() then the others, and .send() - it goes to <root>/changeReport, which Alex2MQTT forwards to the Alexa
|
||||
* event gateway with the user's token. Alexa only accepts it for capabilities registered with proactivelyReported.
|
||||
*/
|
||||
getChangeReport(cause?: ChangeCause): AlexaStatusMessage;
|
||||
/**
|
||||
* Alexa.SceneController: answer an Activate / Deactivate directive with ActivationStarted / DeactivationStarted
|
||||
* (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>;
|
||||
/** The capabilities the device declared, in the order it declared them. */
|
||||
getCapabilities(): AnyCapability[];
|
||||
setManufacturerName(name: string): void;
|
||||
getManufacturerName(): string;
|
||||
setManufacturer(manufacturer: string): void;
|
||||
getManufacturer(): string;
|
||||
setModel(model: string): void;
|
||||
getModel(): string;
|
||||
getSoftwareVersion(): string;
|
||||
/**
|
||||
* Declare an interface of the device:
|
||||
*
|
||||
* lamp.add(PowerController, { proactivelyReported: true });
|
||||
* blinds.add(RangeController, { instance: "Blind.Lift", friendlyNames: [asset("Alexa.Setting.Opening")],
|
||||
* range: { min: 0, max: 100, precision: 1 } });
|
||||
*
|
||||
* Throws a DeclarationError that names the endpoint, the interface and the instance when Alexa would reject the
|
||||
* capability; the device is then as it was before the call.
|
||||
*/
|
||||
add<P extends Properties, D extends Directives, O, I extends boolean>(descriptor: InterfaceDescriptor<P, D, O, I>, ...[options]: DeclarationArguments<O, I>): Capability<P, D, O>;
|
||||
/**
|
||||
* Declare an interface the 1.x way, by its name: options.retrievable / proactivelyReported / instance, then the
|
||||
* add and set methods of the capability that is returned. Throws for a name that is not an interface. Anything
|
||||
* else Alexa would reject is not refused here: check() lists it.
|
||||
*/
|
||||
addCapability(type: AlexaInterfaceType | string, options?: {
|
||||
retrievable?: boolean;
|
||||
proactivelyReported?: boolean;
|
||||
instance?: string;
|
||||
}): AlexaInterface;
|
||||
/**
|
||||
* What Alexa would reject in the device as it is declared now, one line for each: a name with punctuation, an
|
||||
* interface declared twice. Also what a capability noted about its declaration. Empty when there is nothing.
|
||||
* The bridge logs the lines when it answers a discovery.
|
||||
*/
|
||||
check(): string[];
|
||||
/** The endpoint object for discovery. */
|
||||
getJSON(): EndpointJson;
|
||||
private fields;
|
||||
private view;
|
||||
private announced;
|
||||
}
|
||||
export default Device;
|
||||
Loading…
Add table
Add a link
Reference in a new issue