David
2558e21787
The three generic controllers are described in full and leave the stub table (62 stubs remain). A declaration
takes an instance name, friendly names from text() and asset(), and the options of the interface: range, unit and
presets for a range; supportedModes and ordered for a mode; semantics() for all three, with actions mapped to
directives and states mapped to a value or a range of values.
Refused at device.add(), each with the endpoint, interface and instance in the message: no instance name or no
friendly name; an instance declared twice; a first friendly name or a phrase used by another capability of the
endpoint; a reserved word, an asset id that is not in the catalog; range.max not above range.min; a preset off the
precision grid or outside the range; fewer than two modes or a mode listed twice; a mapping to a directive the
interface does not have, to a payload that does not fit, to a mode that is not listed, to AdjustMode on modes
that are not ordered; SetEcoOn, SetEcoOff, EcoOn and EcoOff on anything but a toggle.
For 1.x callers: Alexa.RangeController lists rangeValue (1.5.2 sent supported: []); addSupportedModes() announces
a mode given as a string as { value } and notes it, and takes { ordered: false } as a second argument, the default
stays true as 1.5.2 sent it (device.add() defaults to false). Declared the 1.x way, the zoo fan and curtain give
the same JSON as before.
Tests: the zoo blind, whose range, unit and semantics were written by hand into the JSON of 1.5.2, is declared
with device.add() and equals that JSON plus the Alexa capability; five capability objects of Amazon's examples
are reproduced the same way. 27 examples of four pages added. npm test: 108 pass (was 85) in 10.5-11.3 s, also on
Node 18.20.8 and 20.20.2.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
47 lines
2.6 KiB
TypeScript
47 lines
2.6 KiB
TypeScript
import type { ActionId, StateId } from "./catalog.js";
|
|
import type { Schema } from "./schema.js";
|
|
import type { ActionsToDirective, Directives, Semantics, StatesToRange, StatesToValue } from "./types.js";
|
|
type Short<Id extends string, Prefix extends string> = Id extends `${Prefix}${infer Name}` ? Name : never;
|
|
/** A phrase by its id or by its name: "Alexa.Actions.Open" or "Open". */
|
|
export type ActionName = ActionId | Short<ActionId, "Alexa.Actions.">;
|
|
/** A state by its id or by its name: "Alexa.States.Closed" or "Closed". */
|
|
export type StateName = StateId | Short<StateId, "Alexa.States.">;
|
|
/**
|
|
* Collects the mappings of one capability:
|
|
*
|
|
* semantics()
|
|
* .action("Close", "SetRangeValue", { rangeValue: 0 })
|
|
* .action(["Open", "Raise"], "SetRangeValue", { rangeValue: 100 })
|
|
* .state("Closed", 0)
|
|
* .stateRange("Open", 1, 100)
|
|
*
|
|
* What is collected is checked when the capability is declared, against the directives and the property of its
|
|
* interface.
|
|
*/
|
|
export declare class SemanticsBuilder implements Semantics {
|
|
readonly actionMappings: ActionsToDirective[];
|
|
readonly stateMappings: Array<StatesToValue | StatesToRange>;
|
|
/** The phrases send the directive. payload is its payload; leave it out for a directive that has none. */
|
|
action(actions: ActionName | readonly ActionName[], directive: string, payload?: Record<string, unknown>): this;
|
|
/** The property at this value is in these states: "is the garage door open?" */
|
|
state(states: StateName | readonly StateName[], value: unknown): this;
|
|
/** The property between the two values, both included, is in these states. For an interface with a numeric property. */
|
|
stateRange(states: StateName | readonly StateName[], minimumValue: number, maximumValue: number): this;
|
|
}
|
|
export declare function semantics(): SemanticsBuilder;
|
|
export interface SemanticsRules {
|
|
/** The directives of the interface: a mapping names one of them and gives its payload. */
|
|
directives: Directives;
|
|
/** The value of the property a state stands for. */
|
|
stateValue: Schema<unknown>;
|
|
/** States can be mapped to a range of values: the property is a number. */
|
|
ranges?: boolean;
|
|
/**
|
|
* SetEcoOn, SetEcoOff, EcoOn and EcoOff can be mapped. "Semantics for Alexa hunches is supported only for
|
|
* Alexa.ToggleController" (generic-controllers.html).
|
|
*/
|
|
hunches?: boolean;
|
|
}
|
|
/** The schema of the semantics option of one interface. It takes a semantics() builder or the object as discovery has it. */
|
|
export declare function semanticsOf({ directives, stateValue, ranges, hunches }: SemanticsRules): Schema<Semantics>;
|
|
export {};
|