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
23
dist/types/compat/ActionMapping.d.ts
vendored
Normal file
23
dist/types/compat/ActionMapping.d.ts
vendored
Normal file
|
|
@ -0,0 +1,23 @@
|
|||
import type { ActionsToDirective } from "../registry/types.js";
|
||||
import type { AlexaActions } from "./enums.js";
|
||||
/**
|
||||
* A semantics action mapping of 1.x: the phrases "open", "close", "raise", "lower" for one directive of the
|
||||
* capability it is added to.
|
||||
*
|
||||
* toggle.addActionMapping(new ActionMapping([AlexaActions.Close], "TurnOff"));
|
||||
* lift.addActionMapping(new ActionMapping([AlexaActions.Open], "SetRangeValue", { rangeValue: 100 }));
|
||||
*/
|
||||
export declare class ActionMapping {
|
||||
type: "ActionsToDirective";
|
||||
actions: AlexaActions[];
|
||||
directive: ActionsToDirective["directive"];
|
||||
/** Set when the mapping was built in a way that 3.0 will refuse; the bridge logs it at the next discovery. */
|
||||
readonly deprecation?: string;
|
||||
/**
|
||||
* directivePayload is the payload object of the directive (alexa-discovery-objects.html, "ActionMappings object").
|
||||
* 1.x took a string and put it into discovery as one. A string that holds a JSON object is parsed; any other
|
||||
* string throws a DeclarationError.
|
||||
*/
|
||||
constructor(actions: AlexaActions[], directiveName: string, directivePayload?: Record<string, unknown> | string);
|
||||
toJSON(): ActionsToDirective;
|
||||
}
|
||||
49
dist/types/compat/AlexaInterface.d.ts
vendored
Normal file
49
dist/types/compat/AlexaInterface.d.ts
vendored
Normal file
|
|
@ -0,0 +1,49 @@
|
|||
import { Capability } from "../device/Capability.js";
|
||||
import type { CapabilityJson } from "../device/Capability.js";
|
||||
import type { Semantics } from "../registry/types.js";
|
||||
import type { ActionMapping } from "./ActionMapping.js";
|
||||
import type { AlexaInterfaceType } from "./enums.js";
|
||||
/** One ModeController mode as discovery lists it (configuration.supportedModes): the value plus its friendly names. */
|
||||
export interface SupportedMode {
|
||||
value: string;
|
||||
modeResources?: {
|
||||
friendlyNames: Array<{
|
||||
"@type": string;
|
||||
value: {
|
||||
text?: string;
|
||||
locale?: string;
|
||||
assetId?: string;
|
||||
};
|
||||
}>;
|
||||
};
|
||||
}
|
||||
interface Options {
|
||||
semantics?: Semantics;
|
||||
supportedModes?: Array<string | SupportedMode>;
|
||||
}
|
||||
/**
|
||||
* A capability as 1.x declares it: device.addCapability(type, options), then the add and set methods below. It is a
|
||||
* Capability, so what the methods set reaches discovery the same way as the options of device.add(). Nothing is
|
||||
* refused here except an interface name the registry does not have: what Alexa would reject is logged by the bridge
|
||||
* when it answers a discovery.
|
||||
*/
|
||||
export declare class AlexaInterface extends Capability<any, any, Options> {
|
||||
constructor(type: AlexaInterfaceType | string, retrievable?: boolean, proactivelyReported?: boolean, instance?: string);
|
||||
/** The namespace of the interface, which is the value of its AlexaInterfaceType member. */
|
||||
get type(): AlexaInterfaceType;
|
||||
addActionMapping(mapping: ActionMapping): void;
|
||||
addFriendlyName(name: string, locale: string): void;
|
||||
/** The modes of a ModeController, as { value, modeResources } objects. */
|
||||
addSupportedModes(modes: Array<string | SupportedMode>): void;
|
||||
setInstance(name: string): void;
|
||||
getType(): AlexaInterfaceType;
|
||||
/** @deprecated The same as getType(). */
|
||||
getTypeString(): string;
|
||||
/** @deprecated Read descriptor.version. */
|
||||
getVersion(): string;
|
||||
/** @deprecated Read the keys of descriptor.properties. */
|
||||
getProps(): string[];
|
||||
getJSON(): CapabilityJson;
|
||||
toJSON(): CapabilityJson;
|
||||
}
|
||||
export {};
|
||||
193
dist/types/compat/enums.d.ts
vendored
Normal file
193
dist/types/compat/enums.d.ts
vendored
Normal file
|
|
@ -0,0 +1,193 @@
|
|||
/** Every interface name of 1.x. registry.get() takes a member as it takes the namespace, which is its value. */
|
||||
export declare enum AlexaInterfaceType {
|
||||
APPLICATION_STATE_REPORTER = "Alexa.ApplicationStateReporter",
|
||||
AUDIO_PLAY_QUEUE = "Alexa.Audio.PlayQueue",
|
||||
AUTHORIZATION_CONTROLLER = "Alexa.AuthorizationController",
|
||||
AUTOMATION_MANAGEMENT = "Alexa.AutomationManagement",
|
||||
AUTOMOTIVE_VEHICLE_DATA = "Alexa.Automotive.VehicleData",
|
||||
BRIGHTNESS_CONTROLLER = "Alexa.BrightnessController",
|
||||
CAMERA_LIVE_VIEW_CONTROLLER = "Alexa.Camera.LiveViewController",
|
||||
CAMERA_STREAM_CONTROLLER = "Alexa.CameraStreamController",
|
||||
CHANNEL_CONTROLLER = "Alexa.ChannelController",
|
||||
COLOR_CONTROLLER = "Alexa.ColorController",
|
||||
COLOR_TEMPERATURE_CONTROLLER = "Alexa.ColorTemperatureController",
|
||||
COMMISSIONABLE = "Alexa.Commissionable",
|
||||
CONSENT_MANAGEMENT_CONSENT_REQUIRED_REPORTER = "Alexa.ConsentManagement.ConsentRequiredReporter",
|
||||
CONTACT_SENSOR = "Alexa.ContactSensor",
|
||||
COOKING = "Alexa.Cooking",
|
||||
COOKING_FOOD_TEMPERATURE_CONTROLLER = "Alexa.Cooking.FoodTemperatureController",
|
||||
COOKING_FOOD_TEMPERATURE_SENSOR = "Alexa.Cooking.FoodTemperatureSensor",
|
||||
COOKING_PRESET_CONTROLLER = "Alexa.Cooking.PresetController",
|
||||
COOKING_TEMPERATURE_CONTROLLER = "Alexa.Cooking.TemperatureController",
|
||||
COOKING_TEMPERATURE_SENSOR = "Alexa.Cooking.TemperatureSensor",
|
||||
COOKING_TIME_CONTROLLER = "Alexa.Cooking.TimeController",
|
||||
DATA_CONTROLLER = "Alexa.DataController",
|
||||
DEVICE_USAGE_ESTIMATION = "Alexa.DeviceUsage.Estimation",
|
||||
DEVICE_USAGE_METER = "Alexa.DeviceUsage.Meter",
|
||||
DOORBELL_EVENT_SOURCE = "Alexa.DoorbellEventSource",
|
||||
ENDPOINT_HEALTH = "Alexa.EndpointHealth",
|
||||
EQUALIZER_CONTROLLER = "Alexa.EqualizerController",
|
||||
INPUT_CONTROLLER = "Alexa.InputController",
|
||||
INVENTORY_LEVEL_SENSOR = "Alexa.InventoryLevelSensor",
|
||||
INVENTORY_LEVEL_USAGE_SENSOR = "Alexa.InventoryLevelUsageSensor",
|
||||
INVENTORY_USAGE_SENSOR = "Alexa.InventoryUsageSensor",
|
||||
KEYPAD_CONTROLLER = "Alexa.KeypadController",
|
||||
LAUNCHER = "Alexa.Launcher",
|
||||
LOCK_CONTROLLER = "Alexa.LockController",
|
||||
MEDIA_PLAYBACK = "Alexa.Media.Playback",
|
||||
MEDIA_PLAY_QUEUE = "Alexa.Media.PlayQueue",
|
||||
MEDIA_SEARCH = "Alexa.Media.Search",
|
||||
MODE_CONTROLLER = "Alexa.ModeController",
|
||||
MOTION_SENSOR = "Alexa.MotionSensor",
|
||||
PERCENTAGE_CONTROLLER = "Alexa.PercentageController",
|
||||
PLAYBACK_CONTROLLER = "Alexa.PlaybackController",
|
||||
PLAYBACK_STATE_REPORTER = "Alexa.PlaybackStateReporter",
|
||||
POWER_CONTROLLER = "Alexa.PowerController",
|
||||
POWER_LEVEL_CONTROLLER = "Alexa.PowerLevelController",
|
||||
PROACTIVE_NOTIFICATION_SOURCE = "Alexa.ProactiveNotificationSource",
|
||||
RANGE_CONTROLLER = "Alexa.RangeController",
|
||||
RECORD_CONTROLLER = "Alexa.RecordController",
|
||||
REMOTE_VIDEO_PLAYER = "Alexa.RemoteVideoPlayer",
|
||||
RTC_SESSION_CONTROLLER = "Alexa.RTCSessionController",
|
||||
SCENE_CONTROLLER = "Alexa.SceneController",
|
||||
SECURITY_PANEL_CONTROLLER = "Alexa.SecurityPanelController",
|
||||
SECURITY_PANEL_CONTROLLER_ALERT = "Alexa.SecurityPanelController.Alert",
|
||||
SEEK_CONTROLLER = "Alexa.SeekController",
|
||||
SIMPLE_EVENT_SOURCE = "Alexa.SimpleEventSource",
|
||||
SMART_VISION_OBJECT_DETECTION_SENSOR = "Alexa.SmartVision.ObjectDetectionSensor",
|
||||
SMART_VISION_SNAPSHOT_PROVIDER = "Alexa.SmartVision.SnapshotProvider",
|
||||
SPEAKER = "Alexa.Speaker",
|
||||
STEP_SPEAKER = "Alexa.StepSpeaker",
|
||||
TEMPERATURE_SENSOR = "Alexa.TemperatureSensor",
|
||||
THERMOSTAT_CONTROLLER = "Alexa.ThermostatController",
|
||||
THERMOSTAT_CONTROLLER_CONFIGURATION = "Alexa.ThermostatController.Configuration",
|
||||
THERMOSTAT_CONTROLLER_HVAC_COMPONENTS = "Alexa.ThermostatController.HVAC.Components",
|
||||
THERMOSTAT_CONTROLLER_SCHEDULE = "Alexa.ThermostatController.Schedule",
|
||||
TIME_HOLD_CONTROLLER = "Alexa.TimeHoldController",
|
||||
TOGGLE_CONTROLLER = "Alexa.ToggleController",
|
||||
UI_CONTROLLER = "Alexa.UIController",
|
||||
USER_PREFERENCE = "Alexa.UserPreference",
|
||||
VIDEO_RECORDER = "Alexa.VideoRecorder",
|
||||
WAKE_ON_LAN_CONTROLLER = "Alexa.WakeOnLANController",
|
||||
/** Not an interface: declaring it throws a DeclarationError. Kept because 1.x had it. */
|
||||
UNKNOWN = "UNKNOWN"
|
||||
}
|
||||
export declare enum DisplayCategory {
|
||||
ACTIVITY_TRIGGER = "ACTIVITY_TRIGGER",
|
||||
AIR_CONDITIONER = "AIR_CONDITIONER",
|
||||
AIR_FRESHENER = "AIR_FRESHENER",
|
||||
AIR_PURIFIER = "AIR_PURIFIER",
|
||||
AIR_QUALITY_MONITOR = "AIR_QUALITY_MONITOR",
|
||||
ALEXA_VOICE_ENABLED = "ALEXA_VOICE_ENABLED",
|
||||
AUTO_ACCESSORY = "AUTO_ACCESSORY",
|
||||
BLUETOOTH_SPEAKER = "BLUETOOTH_SPEAKER",
|
||||
CAMERA = "CAMERA",
|
||||
CHRISTMAS_TREE = "CHRISTMAS_TREE",
|
||||
COFFEE_MAKER = "COFFEE_MAKER",
|
||||
COMPUTER = "COMPUTER",
|
||||
CONTACT_SENSOR = "CONTACT_SENSOR",
|
||||
DISHWASHER = "DISHWASHER",
|
||||
DOOR = "DOOR",
|
||||
DOORBELL = "DOORBELL",
|
||||
DRYER = "DRYER",
|
||||
EXTERIOR_BLIND = "EXTERIOR_BLIND",
|
||||
FAN = "FAN",
|
||||
GAME_CONSOLE = "GAME_CONSOLE",
|
||||
GARAGE_DOOR = "GARAGE_DOOR",
|
||||
HEADPHONES = "HEADPHONES",
|
||||
HUB = "HUB",
|
||||
INTERIOR_BLIND = "INTERIOR_BLIND",
|
||||
LAPTOP = "LAPTOP",
|
||||
LIGHT = "LIGHT",
|
||||
MICROWAVE = "MICROWAVE",
|
||||
MOBILE_PHONE = "MOBILE_PHONE",
|
||||
MOTION_SENSOR = "MOTION_SENSOR",
|
||||
MUSIC_SYSTEM = "MUSIC_SYSTEM",
|
||||
NETWORK_HARDWARE = "NETWORK_HARDWARE",
|
||||
OTHER = "OTHER",
|
||||
OVEN = "OVEN",
|
||||
PHONE = "PHONE",
|
||||
PRINTER = "PRINTER",
|
||||
REMOTE = "REMOTE",
|
||||
ROUTER = "ROUTER",
|
||||
SCENE_TRIGGER = "SCENE_TRIGGER",
|
||||
SCREEN = "SCREEN",
|
||||
SECURITY_PANEL = "SECURITY_PANEL",
|
||||
SECURITY_SYSTEM = "SECURITY_SYSTEM",
|
||||
SLOW_COOKER = "SLOW_COOKER",
|
||||
SMARTLOCK = "SMARTLOCK",
|
||||
SMARTPLUG = "SMARTPLUG",
|
||||
SPEAKER = "SPEAKER",
|
||||
STREAMING_DEVICE = "STREAMING_DEVICE",
|
||||
SWITCH = "SWITCH",
|
||||
TABLET = "TABLET",
|
||||
TEMPERATURE_SENSOR = "TEMPERATURE_SENSOR",
|
||||
THERMOSTAT = "THERMOSTAT",
|
||||
TV = "TV",
|
||||
VACUUM_CLEANER = "VACUUM_CLEANER",
|
||||
VACUUM = "VACUUM",
|
||||
/** Not on the list of display categories any more; kept for 1.x callers. */
|
||||
VEHICLE = "VEHICLE",
|
||||
WASHER = "WASHER",
|
||||
WATER_HEATER = "WATER_HEATER",
|
||||
WEARABLE = "WEARABLE"
|
||||
}
|
||||
export declare enum AlexaActions {
|
||||
Open = "Alexa.Actions.Open",
|
||||
Close = "Alexa.Actions.Close",
|
||||
Raise = "Alexa.Actions.Raise",
|
||||
Lower = "Alexa.Actions.Lower",
|
||||
SetEcoOn = "Alexa.Actions.SetEcoOn",
|
||||
SetEcoOff = "Alexa.Actions.SetEcoOff"
|
||||
}
|
||||
/** The values of powerState and toggleState. */
|
||||
export declare const PowerState: {
|
||||
readonly ON: "ON";
|
||||
readonly OFF: "OFF";
|
||||
};
|
||||
export type PowerState = (typeof PowerState)[keyof typeof PowerState];
|
||||
declare const Connectivity: {
|
||||
readonly OK: "OK";
|
||||
readonly UNREACHABLE: "UNREACHABLE";
|
||||
};
|
||||
/**
|
||||
* The Alexa.PowerController interface, for device.add(). PowerController.ON and PowerController.OFF are the 1.x enum
|
||||
* of power states and stay until 3.0: PowerState has the same two members.
|
||||
*/
|
||||
export declare const PowerController: import("../index.js").InterfaceDescriptor<{
|
||||
powerState: {
|
||||
name: string;
|
||||
value: import("../registry/schema.js").EnumSchema<"ON" | "OFF">;
|
||||
};
|
||||
}, {
|
||||
TurnOn: {
|
||||
name: string;
|
||||
payload: import("../index.js").Schema<import("../registry/schema.js").InferShape<{}>>;
|
||||
};
|
||||
TurnOff: {
|
||||
name: string;
|
||||
payload: import("../index.js").Schema<import("../registry/schema.js").InferShape<{}>>;
|
||||
};
|
||||
}, import("../registry/schema.js").InferShape<{
|
||||
verificationsRequired: import("../registry/schema.js").OptionalSchema<("TurnOn" | "TurnOff")[]>;
|
||||
}>, false> & {
|
||||
readonly ON: "ON";
|
||||
readonly OFF: "OFF";
|
||||
};
|
||||
export type PowerController = PowerState;
|
||||
/** The Alexa.EndpointHealth interface, for device.add(). EndpointHealth.OK and EndpointHealth.UNREACHABLE are the 1.x enum of connectivity values. */
|
||||
export declare const EndpointHealth: import("../index.js").InterfaceDescriptor<{
|
||||
connectivity: {
|
||||
name: string;
|
||||
value: import("../index.js").Schema<import("../registry/schema.js").InferShape<{
|
||||
value: import("../registry/schema.js").EnumSchema<"OK" | "UNREACHABLE">;
|
||||
reason: import("../registry/schema.js").OptionalSchema<"WIFI_BAD_PASSWORD" | "WIFI_AP_NOT_FOUND" | "WIFI_ROUTER_UNREACHABLE" | "WIFI_AP_CHANNEL_QUALITY_LOW" | "INTERNET_UNREACHABLE" | "CAPTIVE_PORTAL_CHECK_FAILED" | "UNKNOWN">;
|
||||
}>>;
|
||||
note: string;
|
||||
};
|
||||
}, {}, {}, false> & {
|
||||
readonly OK: "OK";
|
||||
readonly UNREACHABLE: "UNREACHABLE";
|
||||
};
|
||||
export type EndpointHealth = (typeof Connectivity)[keyof typeof Connectivity];
|
||||
export {};
|
||||
Loading…
Add table
Add a link
Reference in a new issue