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>
41 lines
2.1 KiB
JavaScript
41 lines
2.1 KiB
JavaScript
// Friendly names: what the user calls an instance, a mode or a preset (resources-and-assets.html).
|
|
import { ASSETS, RESERVED_WORDS } from "./catalog.js";
|
|
import { at, mismatch, s, SchemaError } from "./schema.js";
|
|
/** A friendly name as text, in one locale. */
|
|
export function text(name, locale = "en-US") {
|
|
return { "@type": "text", value: { text: name, locale } };
|
|
}
|
|
/** A friendly name from the global Alexa catalog: one id, several names, every language Alexa speaks. */
|
|
export function asset(assetId) {
|
|
return { "@type": "asset", value: { assetId } };
|
|
}
|
|
const LOCALE = /^[a-z]{2}-[A-Z]{2}$/;
|
|
const textValue = s.object({
|
|
text: s.string({ min: 1 }),
|
|
locale: s.string({ pattern: LOCALE, expects: "a locale like en-US" }),
|
|
});
|
|
const assetValue = s.object({ assetId: s.oneOf(ASSETS, "an id of the global Alexa catalog, like Alexa.Setting.Opening") });
|
|
const typed = s.object({ "@type": s.enum("text", "asset"), value: s.unknown() });
|
|
const reserved = RESERVED_WORDS;
|
|
/** One friendly name. An asset has to be in the catalog, a text must not be a word Alexa keeps for itself. */
|
|
export const label = {
|
|
expects: "a friendly name, from text() or asset()",
|
|
parse(input, path = "") {
|
|
if (typeof input !== "object" || input === null)
|
|
throw mismatch(path, label.expects, input);
|
|
const { "@type": type, value } = typed.parse(input, path);
|
|
if (type === "asset")
|
|
return { "@type": type, value: assetValue.parse(value, at(path, "value")) };
|
|
const named = textValue.parse(value, at(path, "value"));
|
|
if (reserved.includes(named.text.trim().toLowerCase())) {
|
|
throw new SchemaError(at(path, "value.text"), `${JSON.stringify(named.text)} is a reserved word, not to be used as a friendly name`);
|
|
}
|
|
return { "@type": type, value: named };
|
|
},
|
|
};
|
|
/** The friendly names of an instance, a mode or a preset: at least one. */
|
|
export const labels = s.array(label, { min: 1 });
|
|
/** What the user is shown for a friendly name: the text, or the id of the asset. */
|
|
export function shownAs(name) {
|
|
return name["@type"] === "text" ? name.value.text : name.value.assetId;
|
|
}
|