From 2558e217879e84b17504b2b5554a8c22f9343668 Mon Sep 17 00:00:00 2001 From: David Date: Mon, 28 Sep 2026 15:50:25 +0000 Subject: [PATCH] registry: RangeController, ModeController, ToggleController with resources, presets and semantics 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 --- dist/cjs/compat/AlexaInterface.js | 16 +- dist/cjs/device/validate.js | 9 + dist/cjs/index.js | 25 +- dist/cjs/registry/index.js | 17 +- .../cjs/registry/interfaces/ModeController.js | 87 ++++++ .../registry/interfaces/RangeController.js | 76 ++++++ .../registry/interfaces/ToggleController.js | 31 +++ dist/cjs/registry/interfaces/stubs.js | 8 +- dist/cjs/registry/resources.js | 2 + dist/cjs/registry/semantics.js | 112 ++++++++ dist/esm/compat/AlexaInterface.d.ts | 18 +- dist/esm/compat/AlexaInterface.js | 16 +- dist/esm/device/validate.js | 9 + dist/esm/index.d.ts | 6 +- dist/esm/index.js | 4 +- dist/esm/registry/index.d.ts | 9 +- dist/esm/registry/index.js | 10 +- .../registry/interfaces/ModeController.d.ts | 43 +++ .../esm/registry/interfaces/ModeController.js | 84 ++++++ .../registry/interfaces/RangeController.d.ts | 39 +++ .../registry/interfaces/RangeController.js | 73 ++++++ .../registry/interfaces/ToggleController.d.ts | 21 ++ .../registry/interfaces/ToggleController.js | 28 ++ dist/esm/registry/interfaces/stubs.js | 8 +- dist/esm/registry/resources.js | 4 +- dist/esm/registry/semantics.d.ts | 47 ++++ dist/esm/registry/semantics.js | 106 ++++++++ dist/esm/registry/types.d.ts | 8 +- dist/types/compat/AlexaInterface.d.ts | 18 +- dist/types/index.d.ts | 6 +- dist/types/registry/index.d.ts | 9 +- .../registry/interfaces/ModeController.d.ts | 43 +++ .../registry/interfaces/RangeController.d.ts | 39 +++ .../registry/interfaces/ToggleController.d.ts | 21 ++ dist/types/registry/semantics.d.ts | 47 ++++ dist/types/registry/types.d.ts | 8 +- src/compat/AlexaInterface.ts | 20 +- src/device/validate.ts | 9 + src/index.ts | 8 +- src/registry/index.ts | 15 +- src/registry/interfaces/ModeController.ts | 95 +++++++ src/registry/interfaces/RangeController.ts | 75 ++++++ src/registry/interfaces/ToggleController.ts | 30 +++ src/registry/interfaces/stubs.ts | 8 +- src/registry/resources.ts | 3 +- src/registry/semantics.ts | 135 ++++++++++ src/registry/types.ts | 8 +- test/device/discovery.test.js | 137 +++++++++- test/device/validate.test.js | 166 +++++++++++- .../actionMapping.json | 13 + .../alexa-discovery-objects/semantics.json | 51 ++++ .../alexa-discovery-objects/stateMapping.json | 10 + .../AdjustMode.directive.json | 23 ++ .../AdjustMode.response.json | 31 +++ .../alexa-modecontroller/ChangeReport.json | 43 +++ .../SetMode.directive.json | 23 ++ .../SetMode.response.json | 31 +++ .../alexa-modecontroller/StateReport.json | 31 +++ .../alexa-modecontroller/mode.property.json | 6 + .../AdjustRangeValue.directive.json | 24 ++ .../AdjustRangeValue.response.json | 31 +++ .../alexa-rangecontroller/ChangeReport.json | 50 ++++ .../SetRangeValue.directive.json | 23 ++ .../SetRangeValue.response.json | 31 +++ .../alexa-rangecontroller/StateReport.json | 38 +++ .../rangeValue.property.json | 6 + .../alexa-togglecontroller/ChangeReport.json | 51 ++++ .../alexa-togglecontroller/StateReport.json | 39 +++ .../TurnOff.directive.json | 21 ++ .../TurnOff.response.json | 31 +++ .../TurnOn.directive.json | 21 ++ .../TurnOn.response.json | 31 +++ .../discovery-oven.json | 127 +++++++++ .../discovery-range-and-toggle.json | 247 ++++++++++++++++++ .../discovery-semantics.json | 111 ++++++++ .../toggleState.property.json | 6 + test/fixtures/interfaces.js | 97 ++++++- test/fixtures/types.ts | 44 +++- test/registry/descriptors.test.js | 27 +- test/registry/semantics.test.js | 104 ++++++++ 80 files changed, 3131 insertions(+), 107 deletions(-) create mode 100644 dist/cjs/registry/interfaces/ModeController.js create mode 100644 dist/cjs/registry/interfaces/RangeController.js create mode 100644 dist/cjs/registry/interfaces/ToggleController.js create mode 100644 dist/cjs/registry/semantics.js create mode 100644 dist/esm/registry/interfaces/ModeController.d.ts create mode 100644 dist/esm/registry/interfaces/ModeController.js create mode 100644 dist/esm/registry/interfaces/RangeController.d.ts create mode 100644 dist/esm/registry/interfaces/RangeController.js create mode 100644 dist/esm/registry/interfaces/ToggleController.d.ts create mode 100644 dist/esm/registry/interfaces/ToggleController.js create mode 100644 dist/esm/registry/semantics.d.ts create mode 100644 dist/esm/registry/semantics.js create mode 100644 dist/types/registry/interfaces/ModeController.d.ts create mode 100644 dist/types/registry/interfaces/RangeController.d.ts create mode 100644 dist/types/registry/interfaces/ToggleController.d.ts create mode 100644 dist/types/registry/semantics.d.ts create mode 100644 src/registry/interfaces/ModeController.ts create mode 100644 src/registry/interfaces/RangeController.ts create mode 100644 src/registry/interfaces/ToggleController.ts create mode 100644 src/registry/semantics.ts create mode 100644 test/fixtures/alexa-docs/alexa-discovery-objects/actionMapping.json create mode 100644 test/fixtures/alexa-docs/alexa-discovery-objects/semantics.json create mode 100644 test/fixtures/alexa-docs/alexa-discovery-objects/stateMapping.json create mode 100644 test/fixtures/alexa-docs/alexa-modecontroller/AdjustMode.directive.json create mode 100644 test/fixtures/alexa-docs/alexa-modecontroller/AdjustMode.response.json create mode 100644 test/fixtures/alexa-docs/alexa-modecontroller/ChangeReport.json create mode 100644 test/fixtures/alexa-docs/alexa-modecontroller/SetMode.directive.json create mode 100644 test/fixtures/alexa-docs/alexa-modecontroller/SetMode.response.json create mode 100644 test/fixtures/alexa-docs/alexa-modecontroller/StateReport.json create mode 100644 test/fixtures/alexa-docs/alexa-modecontroller/mode.property.json create mode 100644 test/fixtures/alexa-docs/alexa-rangecontroller/AdjustRangeValue.directive.json create mode 100644 test/fixtures/alexa-docs/alexa-rangecontroller/AdjustRangeValue.response.json create mode 100644 test/fixtures/alexa-docs/alexa-rangecontroller/ChangeReport.json create mode 100644 test/fixtures/alexa-docs/alexa-rangecontroller/SetRangeValue.directive.json create mode 100644 test/fixtures/alexa-docs/alexa-rangecontroller/SetRangeValue.response.json create mode 100644 test/fixtures/alexa-docs/alexa-rangecontroller/StateReport.json create mode 100644 test/fixtures/alexa-docs/alexa-rangecontroller/rangeValue.property.json create mode 100644 test/fixtures/alexa-docs/alexa-togglecontroller/ChangeReport.json create mode 100644 test/fixtures/alexa-docs/alexa-togglecontroller/StateReport.json create mode 100644 test/fixtures/alexa-docs/alexa-togglecontroller/TurnOff.directive.json create mode 100644 test/fixtures/alexa-docs/alexa-togglecontroller/TurnOff.response.json create mode 100644 test/fixtures/alexa-docs/alexa-togglecontroller/TurnOn.directive.json create mode 100644 test/fixtures/alexa-docs/alexa-togglecontroller/TurnOn.response.json create mode 100644 test/fixtures/alexa-docs/alexa-togglecontroller/discovery-oven.json create mode 100644 test/fixtures/alexa-docs/alexa-togglecontroller/discovery-range-and-toggle.json create mode 100644 test/fixtures/alexa-docs/alexa-togglecontroller/discovery-semantics.json create mode 100644 test/fixtures/alexa-docs/alexa-togglecontroller/toggleState.property.json create mode 100644 test/registry/semantics.test.js diff --git a/dist/cjs/compat/AlexaInterface.js b/dist/cjs/compat/AlexaInterface.js index d02d6a4..6abe5c2 100644 --- a/dist/cjs/compat/AlexaInterface.js +++ b/dist/cjs/compat/AlexaInterface.js @@ -28,9 +28,19 @@ class AlexaInterface extends Capability_js_1.Capability { addFriendlyName(name, locale) { this.friendlyNames.push((0, resources_js_1.text)(name, locale)); } - /** The modes of a ModeController, as { value, modeResources } objects. */ - addSupportedModes(modes) { - this.options.supportedModes = modes; + /** + * The modes of a ModeController, as { value, modeResources } objects. A mode given as a string is announced as + * { value } and noted: Alexa wants friendly names for it. ordered is true unless options.ordered says otherwise, + * as 1.x announced every mode list; with device.add() the default is false. + */ + addSupportedModes(modes, options = {}) { + this.options.ordered = options.ordered ?? true; + this.options.supportedModes = modes.map((mode) => { + if (typeof mode !== "string") + return { value: mode.value, friendlyNames: (mode.modeResources?.friendlyNames ?? []) }; + this.notes.push(`the mode ${mode} was given as a string, pass { value, modeResources }`); + return { value: mode, friendlyNames: [] }; + }); } setInstance(name) { this.instance = name; diff --git a/dist/cjs/device/validate.js b/dist/cjs/device/validate.js index 0c0bc65..f817cec 100644 --- a/dist/cjs/device/validate.js +++ b/dist/cjs/device/validate.js @@ -109,6 +109,15 @@ function checkCapability(capability, descriptor, endpoint) { if (friendlyNames.length > 0) refuse("takes no friendly names"); } + // A capability of device.add() passed the schema when it was declared; one declared the 1.x way did not + if (descriptor.options) { + try { + descriptor.options.parse(capability.options); + } + catch (err) { + refuse(err instanceof schema_js_1.SchemaError ? err.message : String(err)); + } + } // generic-controllers.html, "Semantics for user utterances": "Each semantic phrase must be unique across all // controller instances for each endpoint" const used = new Map(); diff --git a/dist/cjs/index.js b/dist/cjs/index.js index d152ab4..8e0e781 100644 --- a/dist/cjs/index.js +++ b/dist/cjs/index.js @@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) { return (mod && mod.__esModule) ? mod : { "default": mod }; }; Object.defineProperty(exports, "__esModule", { value: true }); -exports.AlexaErrorResponse = exports.AlexaErrorType = exports.ThermostatMode = exports.TemperatureSensorScale = exports.AlexaStatusMessage = exports.PowerState = exports.DisplayCategory = exports.AlexaInterfaceType = exports.AlexaActions = exports.ActionMapping = exports.AlexaInterface = exports.DisplayCategories = exports.States = exports.Actions = exports.Units = exports.Assets = exports.text = exports.asset = exports.EndpointHealth = exports.PowerController = exports.TemperatureSensor = exports.BrightnessController = exports.Alexa = exports.SchemaError = exports.DeclarationError = exports.registry = exports.Capability = exports.Device = exports.DEFAULT_HOST = exports.Alex2MQTT = void 0; +exports.AlexaErrorResponse = exports.AlexaErrorType = exports.ThermostatMode = exports.TemperatureSensorScale = exports.AlexaStatusMessage = exports.PowerState = exports.DisplayCategory = exports.AlexaInterfaceType = exports.AlexaActions = exports.ActionMapping = exports.AlexaInterface = exports.DisplayCategories = exports.States = exports.Actions = exports.Units = exports.Assets = exports.SemanticsBuilder = exports.semantics = exports.text = exports.asset = exports.EndpointHealth = exports.PowerController = exports.ToggleController = exports.TemperatureSensor = exports.RangeController = exports.ModeController = exports.BrightnessController = exports.Alexa = exports.SchemaError = exports.DeclarationError = exports.registry = exports.Capability = exports.Device = exports.DEFAULT_HOST = exports.Alex2MQTT = void 0; // Relative specifiers carry ".js": Node's ES module loader resolves no extension, and TypeScript maps it back to the .ts. var Alex2Node_js_1 = require("./Alex2Node.js"); Object.defineProperty(exports, "Alex2MQTT", { enumerable: true, get: function () { return __importDefault(Alex2Node_js_1).default; } }); @@ -20,20 +20,25 @@ Object.defineProperty(exports, "SchemaError", { enumerable: true, get: function var index_js_2 = require("./registry/index.js"); Object.defineProperty(exports, "Alexa", { enumerable: true, get: function () { return index_js_2.Alexa; } }); Object.defineProperty(exports, "BrightnessController", { enumerable: true, get: function () { return index_js_2.BrightnessController; } }); +Object.defineProperty(exports, "ModeController", { enumerable: true, get: function () { return index_js_2.ModeController; } }); +Object.defineProperty(exports, "RangeController", { enumerable: true, get: function () { return index_js_2.RangeController; } }); Object.defineProperty(exports, "TemperatureSensor", { enumerable: true, get: function () { return index_js_2.TemperatureSensor; } }); +Object.defineProperty(exports, "ToggleController", { enumerable: true, get: function () { return index_js_2.ToggleController; } }); var enums_js_1 = require("./compat/enums.js"); Object.defineProperty(exports, "PowerController", { enumerable: true, get: function () { return enums_js_1.PowerController; } }); Object.defineProperty(exports, "EndpointHealth", { enumerable: true, get: function () { return enums_js_1.EndpointHealth; } }); -var resources_js_1 = require("./registry/resources.js"); -Object.defineProperty(exports, "asset", { enumerable: true, get: function () { return resources_js_1.asset; } }); -Object.defineProperty(exports, "text", { enumerable: true, get: function () { return resources_js_1.text; } }); -// The vocabularies of the Smart Home API var index_js_3 = require("./registry/index.js"); -Object.defineProperty(exports, "Assets", { enumerable: true, get: function () { return index_js_3.ASSETS; } }); -Object.defineProperty(exports, "Units", { enumerable: true, get: function () { return index_js_3.UNITS_OF_MEASURE; } }); -Object.defineProperty(exports, "Actions", { enumerable: true, get: function () { return index_js_3.ACTIONS; } }); -Object.defineProperty(exports, "States", { enumerable: true, get: function () { return index_js_3.STATES; } }); -Object.defineProperty(exports, "DisplayCategories", { enumerable: true, get: function () { return index_js_3.DISPLAY_CATEGORIES; } }); +Object.defineProperty(exports, "asset", { enumerable: true, get: function () { return index_js_3.asset; } }); +Object.defineProperty(exports, "text", { enumerable: true, get: function () { return index_js_3.text; } }); +Object.defineProperty(exports, "semantics", { enumerable: true, get: function () { return index_js_3.semantics; } }); +Object.defineProperty(exports, "SemanticsBuilder", { enumerable: true, get: function () { return index_js_3.SemanticsBuilder; } }); +// The vocabularies of the Smart Home API +var index_js_4 = require("./registry/index.js"); +Object.defineProperty(exports, "Assets", { enumerable: true, get: function () { return index_js_4.ASSETS; } }); +Object.defineProperty(exports, "Units", { enumerable: true, get: function () { return index_js_4.UNITS_OF_MEASURE; } }); +Object.defineProperty(exports, "Actions", { enumerable: true, get: function () { return index_js_4.ACTIONS; } }); +Object.defineProperty(exports, "States", { enumerable: true, get: function () { return index_js_4.STATES; } }); +Object.defineProperty(exports, "DisplayCategories", { enumerable: true, get: function () { return index_js_4.DISPLAY_CATEGORIES; } }); // 1.x var AlexaInterface_js_1 = require("./compat/AlexaInterface.js"); Object.defineProperty(exports, "AlexaInterface", { enumerable: true, get: function () { return AlexaInterface_js_1.AlexaInterface; } }); diff --git a/dist/cjs/registry/index.js b/dist/cjs/registry/index.js index 1222c88..fd7eba4 100644 --- a/dist/cjs/registry/index.js +++ b/dist/cjs/registry/index.js @@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) { for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p); }; Object.defineProperty(exports, "__esModule", { value: true }); -exports.SchemaError = exports.s = exports.defineInterface = exports.DeclarationError = exports.TemperatureSensor = exports.PowerController = exports.EndpointHealth = exports.BrightnessController = exports.Alexa = exports.registry = void 0; +exports.SchemaError = exports.s = exports.defineInterface = exports.DeclarationError = exports.SemanticsBuilder = exports.semantics = exports.text = exports.asset = exports.ToggleController = exports.TemperatureSensor = exports.RangeController = exports.PowerController = exports.ModeController = exports.EndpointHealth = exports.BrightnessController = exports.Alexa = exports.registry = void 0; // The interfaces the library knows, by namespace. const Alexa_js_1 = require("./interfaces/Alexa.js"); Object.defineProperty(exports, "Alexa", { enumerable: true, get: function () { return Alexa_js_1.Alexa; } }); @@ -22,18 +22,27 @@ const BrightnessController_js_1 = require("./interfaces/BrightnessController.js" Object.defineProperty(exports, "BrightnessController", { enumerable: true, get: function () { return BrightnessController_js_1.BrightnessController; } }); const EndpointHealth_js_1 = require("./interfaces/EndpointHealth.js"); Object.defineProperty(exports, "EndpointHealth", { enumerable: true, get: function () { return EndpointHealth_js_1.EndpointHealth; } }); +const ModeController_js_1 = require("./interfaces/ModeController.js"); +Object.defineProperty(exports, "ModeController", { enumerable: true, get: function () { return ModeController_js_1.ModeController; } }); const PowerController_js_1 = require("./interfaces/PowerController.js"); Object.defineProperty(exports, "PowerController", { enumerable: true, get: function () { return PowerController_js_1.PowerController; } }); +const RangeController_js_1 = require("./interfaces/RangeController.js"); +Object.defineProperty(exports, "RangeController", { enumerable: true, get: function () { return RangeController_js_1.RangeController; } }); const TemperatureSensor_js_1 = require("./interfaces/TemperatureSensor.js"); Object.defineProperty(exports, "TemperatureSensor", { enumerable: true, get: function () { return TemperatureSensor_js_1.TemperatureSensor; } }); +const ToggleController_js_1 = require("./interfaces/ToggleController.js"); +Object.defineProperty(exports, "ToggleController", { enumerable: true, get: function () { return ToggleController_js_1.ToggleController; } }); const stubs_js_1 = require("./interfaces/stubs.js"); const types_js_1 = require("./types.js"); const described = [ Alexa_js_1.Alexa, BrightnessController_js_1.BrightnessController, EndpointHealth_js_1.EndpointHealth, + ModeController_js_1.ModeController, PowerController_js_1.PowerController, + RangeController_js_1.RangeController, TemperatureSensor_js_1.TemperatureSensor, + ToggleController_js_1.ToggleController, ]; const descriptors = new Map(); for (const descriptor of [...described, ...stubs_js_1.STUBS]) { @@ -59,6 +68,12 @@ exports.registry = { return [...descriptors.values()].sort((a, b) => (a.namespace < b.namespace ? -1 : 1)); }, }; +var resources_js_1 = require("./resources.js"); +Object.defineProperty(exports, "asset", { enumerable: true, get: function () { return resources_js_1.asset; } }); +Object.defineProperty(exports, "text", { enumerable: true, get: function () { return resources_js_1.text; } }); +var semantics_js_1 = require("./semantics.js"); +Object.defineProperty(exports, "semantics", { enumerable: true, get: function () { return semantics_js_1.semantics; } }); +Object.defineProperty(exports, "SemanticsBuilder", { enumerable: true, get: function () { return semantics_js_1.SemanticsBuilder; } }); var types_js_2 = require("./types.js"); Object.defineProperty(exports, "DeclarationError", { enumerable: true, get: function () { return types_js_2.DeclarationError; } }); Object.defineProperty(exports, "defineInterface", { enumerable: true, get: function () { return types_js_2.defineInterface; } }); diff --git a/dist/cjs/registry/interfaces/ModeController.js b/dist/cjs/registry/interfaces/ModeController.js new file mode 100644 index 0000000..e7b56fe --- /dev/null +++ b/dist/cjs/registry/interfaces/ModeController.js @@ -0,0 +1,87 @@ +"use strict"; +Object.defineProperty(exports, "__esModule", { value: true }); +exports.ModeController = void 0; +const resources_js_1 = require("../resources.js"); +const schema_js_1 = require("../schema.js"); +const semantics_js_1 = require("../semantics.js"); +const types_js_1 = require("../types.js"); +const directives = { + SetMode: { name: "SetMode", payload: schema_js_1.s.object({ mode: schema_js_1.s.string({ min: 1 }) }) }, + AdjustMode: { + name: "AdjustMode", + payload: schema_js_1.s.object({ modeDelta: schema_js_1.s.optional(schema_js_1.s.number({ integer: true })) }), + // alexa-modecontroller.html, "Capabilities object": "Modes that have an order support the AdjustMode directive." + when: ({ options }) => options.ordered === true, + note: "modeDelta is the number of modes to move by, 1 when it is left out", + }, +}; +// A mode is declared as { value, friendlyNames }. The object of discovery and of 1.x, { value, modeResources: +// { friendlyNames } }, is taken as well. +const eitherForm = schema_js_1.s.object({ + value: schema_js_1.s.string({ min: 1 }), + friendlyNames: schema_js_1.s.optional(schema_js_1.s.unknown()), + modeResources: schema_js_1.s.optional(schema_js_1.s.object({ friendlyNames: schema_js_1.s.unknown() })), +}, { unknownKeys: "reject" }); +const mode = { + expects: "a mode { value, friendlyNames }", + parse(input, path = "") { + if (typeof input !== "object" || input === null) + throw (0, schema_js_1.mismatch)(path, mode.expects, input); + const { value, friendlyNames, modeResources } = eitherForm.parse(input, path); + const named = friendlyNames === undefined && modeResources ? "modeResources.friendlyNames" : "friendlyNames"; + return { value, friendlyNames: resources_js_1.labels.parse(friendlyNames ?? modeResources?.friendlyNames, (0, schema_js_1.at)(path, named)) }; + }, +}; +/** + * One of a list of values, under an instance name: the wash cycle of a washer, the position of a garage door. Amazon + * certifies a garage door only with this interface and the display category GARAGE_DOOR. + */ +exports.ModeController = (0, types_js_1.defineInterface)({ + namespace: "Alexa.ModeController", + version: "3", + doc: "https://developer.amazon.com/docs/alexaplus/device-apis/alexa-modecontroller.html", + kind: "controller", + tier: 1, + instanced: true, + properties: { + mode: { name: "mode", value: schema_js_1.s.nullable(schema_js_1.s.string({ min: 1 })), note: "null when no mode is set, as when the device is off" }, + }, + directives, + options: schema_js_1.s.object({ + /** At least two. When the modes have an order, in increasing order. */ + supportedModes: schema_js_1.s.array(mode, { min: 2 }), + /** The modes have an order, cold to hot, and the user can say "increase": Alexa sends AdjustMode. Default: false. */ + ordered: schema_js_1.s.optional(schema_js_1.s.boolean()), + semantics: schema_js_1.s.optional((0, semantics_js_1.semanticsOf)({ directives, stateValue: schema_js_1.s.string({ min: 1 }) })), + }, { unknownKeys: "reject" }), + // A capability declared the 1.x way may be without modes, or have modes without names + discovery({ options: { supportedModes = [], ordered = false } }) { + if (supportedModes.length === 0) + return {}; + const modes = supportedModes.map(({ value, friendlyNames = [] }) => (friendlyNames.length > 0 ? { value, modeResources: { friendlyNames } } : { value })); + return { configuration: { ordered, supportedModes: modes } }; + }, + validate(capability) { + const { supportedModes, ordered = false, semantics } = capability.options; + const values = supportedModes.map(({ value }) => value); + const twice = values.find((value, i) => values.indexOf(value) !== i); + if (twice !== undefined) + throw new types_js_1.DeclarationError(capability, `the mode ${twice} is listed twice`); + const isMode = (value) => values.includes(value); + for (const { directive } of semantics?.actionMappings ?? []) { + if (directive.name === "AdjustMode" && !ordered) { + throw new types_js_1.DeclarationError(capability, "an action is mapped to AdjustMode, which needs ordered: true"); + } + if (directive.name === "SetMode" && !isMode(directive.payload?.mode)) { + throw new types_js_1.DeclarationError(capability, `an action is mapped to SetMode ${directive.payload?.mode}, the modes are ${values.join(", ")}`); + } + } + for (const mapping of semantics?.stateMappings ?? []) { + if (mapping["@type"] === "StatesToValue" && !isMode(mapping.value)) { + throw new types_js_1.DeclarationError(capability, `a state is mapped to ${mapping.value}, the modes are ${values.join(", ")}`); + } + } + }, + errorNamespace: "Alexa.Safety", + errorTypes: ["OBSTACLE_DETECTED", "SAFETY_BEAM_BREACHED"], +}); diff --git a/dist/cjs/registry/interfaces/RangeController.js b/dist/cjs/registry/interfaces/RangeController.js new file mode 100644 index 0000000..7fabae0 --- /dev/null +++ b/dist/cjs/registry/interfaces/RangeController.js @@ -0,0 +1,76 @@ +"use strict"; +Object.defineProperty(exports, "__esModule", { value: true }); +exports.RangeController = void 0; +const catalog_js_1 = require("../catalog.js"); +const resources_js_1 = require("../resources.js"); +const schema_js_1 = require("../schema.js"); +const semantics_js_1 = require("../semantics.js"); +const types_js_1 = require("../types.js"); +const directives = { + SetRangeValue: { name: "SetRangeValue", payload: schema_js_1.s.object({ rangeValue: schema_js_1.s.number() }) }, + AdjustRangeValue: { + name: "AdjustRangeValue", + payload: schema_js_1.s.object({ rangeValueDelta: schema_js_1.s.number(), rangeValueDeltaDefault: schema_js_1.s.boolean() }), + note: "rangeValueDeltaDefault is true when the user named no amount; rangeValueDelta is then the precision", + }, +}; +// 0.1 + 0.2 is not 0.3: a value is on the grid when it is within a millionth of a step of it +function onGrid(value, origin, step) { + const steps = (value - origin) / step; + return Math.abs(steps - Math.round(steps)) < 1e-6; +} +/** + * A number in a range, under an instance name: the position of a blind, the speed of a fan. With nonControllable it + * is a reading the user can ask for, like an air quality index. + */ +exports.RangeController = (0, types_js_1.defineInterface)({ + namespace: "Alexa.RangeController", + version: "3", + doc: "https://developer.amazon.com/docs/alexaplus/device-apis/alexa-rangecontroller.html", + kind: "controller", + tier: 1, + instanced: true, + properties: { + rangeValue: { name: "rangeValue", value: schema_js_1.s.number() }, + }, + directives, + options: schema_js_1.s.object({ + /** precision is the step of the range and what "turn up the fan speed" changes it by. */ + range: schema_js_1.s.object({ min: schema_js_1.s.number(), max: schema_js_1.s.number(), precision: schema_js_1.s.number({ gt: 0 }) }, { unknownKeys: "reject" }), + unit: schema_js_1.s.optional(schema_js_1.s.oneOf(catalog_js_1.UNITS_OF_MEASURE, "a unit of measure like Alexa.Unit.Percent")), + /** Names for values: "set the fan speed to maximum". */ + presets: schema_js_1.s.optional(schema_js_1.s.array(schema_js_1.s.object({ value: schema_js_1.s.number(), friendlyNames: resources_js_1.labels }, { unknownKeys: "reject" }))), + semantics: schema_js_1.s.optional((0, semantics_js_1.semanticsOf)({ directives, stateValue: schema_js_1.s.number(), ranges: true })), + }, { unknownKeys: "reject" }), + // A capability declared the 1.x way may be without a range; check() says so, discovery lists what there is + discovery({ options: { range, unit, presets } }) { + const configuration = { + ...(range && { supportedRange: { minimumValue: range.min, maximumValue: range.max, precision: range.precision } }), + ...(unit && { unitOfMeasure: unit }), + ...(presets && { presets: presets.map(({ value, friendlyNames }) => ({ rangeValue: value, presetResources: { friendlyNames } })) }), + }; + return Object.keys(configuration).length > 0 ? { configuration } : {}; + }, + validate(capability) { + const { range: { min, max, precision }, presets = [], semantics } = capability.options; + const inRange = (value) => value >= min && value <= max; + if (max <= min) + throw new types_js_1.DeclarationError(capability, `range.max ${max} is not above range.min ${min}`); + for (const { value } of presets) { + // alexa-rangecontroller.html, "Preset object": "minimum range value + (n x precision) where n is an integer" + if (!inRange(value) || !onGrid(value, min, precision)) { + throw new types_js_1.DeclarationError(capability, `the preset ${value} is not ${min} + n x ${precision}, up to ${max}`); + } + } + for (const { directive } of semantics?.actionMappings ?? []) { + const { rangeValue } = directive.payload ?? {}; + if (directive.name === "SetRangeValue" && !inRange(rangeValue)) { + throw new types_js_1.DeclarationError(capability, `an action is mapped to SetRangeValue ${rangeValue}, the range is ${min} to ${max}`); + } + } + }, + // alexa-rangecontroller.html, "SetRangeValue directive error handling": "If your error is safety related, respond + // with an Alexa.Safety.ErrorResponse" + errorNamespace: "Alexa.Safety", + errorTypes: ["OBSTACLE_DETECTED", "SAFETY_BEAM_BREACHED"], +}); diff --git a/dist/cjs/registry/interfaces/ToggleController.js b/dist/cjs/registry/interfaces/ToggleController.js new file mode 100644 index 0000000..78b0b22 --- /dev/null +++ b/dist/cjs/registry/interfaces/ToggleController.js @@ -0,0 +1,31 @@ +"use strict"; +Object.defineProperty(exports, "__esModule", { value: true }); +exports.ToggleController = void 0; +const schema_js_1 = require("../schema.js"); +const semantics_js_1 = require("../semantics.js"); +const types_js_1 = require("../types.js"); +const directives = { + TurnOn: { name: "TurnOn", payload: schema_js_1.s.object({}) }, + TurnOff: { name: "TurnOff", payload: schema_js_1.s.object({}) }, +}; +/** + * Something that is on or off, under an instance name: the oscillation of a fan, the light of an oven. The one + * generic controller that Alexa hunches work with (SetEcoOn, SetEcoOff, EcoOn, EcoOff). + */ +exports.ToggleController = (0, types_js_1.defineInterface)({ + namespace: "Alexa.ToggleController", + version: "3", + doc: "https://developer.amazon.com/docs/alexaplus/device-apis/alexa-togglecontroller.html", + kind: "controller", + tier: 1, + instanced: true, + properties: { + toggleState: { name: "toggleState", value: schema_js_1.s.enum("ON", "OFF") }, + }, + directives, + options: schema_js_1.s.object({ + semantics: schema_js_1.s.optional((0, semantics_js_1.semanticsOf)({ directives, stateValue: schema_js_1.s.enum("ON", "OFF"), hunches: true })), + }, { unknownKeys: "reject" }), + errorNamespace: "Alexa.Safety", + errorTypes: ["OBSTACLE_DETECTED", "SAFETY_BEAM_BREACHED"], +}); diff --git a/dist/cjs/registry/interfaces/stubs.js b/dist/cjs/registry/interfaces/stubs.js index f33495e..07ebcb2 100644 --- a/dist/cjs/registry/interfaces/stubs.js +++ b/dist/cjs/registry/interfaces/stubs.js @@ -48,7 +48,6 @@ const TABLE = [ ["Alexa.Media.PlayQueue", "1", [], "alexa-media-playqueue.html"], ["Alexa.Media.Playback", "1", [], "alexa-media-playback.html"], ["Alexa.Media.Search", "1", [], "alexa-media-search.html"], - ["Alexa.ModeController", "3", ["mode"], "alexa-modecontroller.html"], ["Alexa.MotionSensor", "3", [], "alexa-motionsensor.html"], ["Alexa.PercentageController", "3", [], "alexa-percentagecontroller.html"], ["Alexa.PlaybackController", "3", [], "alexa-playbackcontroller.html"], @@ -56,7 +55,6 @@ const TABLE = [ ["Alexa.PowerLevelController", "3", [], "alexa-powerlevelcontroller.html"], ["Alexa.ProactiveNotificationSource", "1", [], "alexa-proactivenotificationsource.html"], ["Alexa.RTCSessionController", "1", [], "alexa-rtcsessioncontroller.html"], - ["Alexa.RangeController", "3", [], "alexa-rangecontroller.html"], ["Alexa.RecordController", "3", [], "alexa-recordcontroller.html"], ["Alexa.RemoteVideoPlayer", "1", [], "alexa-remotevideoplayer.html"], ["Alexa.SceneController", "3", [], "alexa-scenecontroller.html"], @@ -74,13 +72,12 @@ const TABLE = [ ["Alexa.ThermostatController.Schedule", "1", [], "alexa-thermostatcontroller-schedule.html"], // "UNKNOWN" in 1.5.2 as well; the page is titled "Interface 3" ["Alexa.TimeHoldController", "3", [], "alexa-timeholdcontroller.html"], - ["Alexa.ToggleController", "3", ["toggleState"], "alexa-togglecontroller.html"], ["Alexa.UIController", "1", [], "alexa-uicontroller.html"], ["Alexa.UserPreference", "1", [], "alexa-userpreference.html"], ["Alexa.VideoRecorder", "1", [], "alexa-videorecorder.html"], ["Alexa.WakeOnLANController", "1", [], "alexa-wakeonlancontroller.html"], ]; -// What 1.5.2 added to the capability object of three of them +// What 1.5.2 added to the capability object of two of them const EXTRAS = { // No properties object; supportsDeactivation and proactivelyReported on the capability itself "Alexa.SceneController": ({ proactivelyReported }) => ({ @@ -90,9 +87,6 @@ const EXTRAS = { "Alexa.ThermostatController": () => ({ configuration: { supportedModes: ["HEAT", "COOL", "AUTO", "OFF"], supportsScheduling: false }, }), - "Alexa.ModeController": ({ options }) => (options.supportedModes?.length > 0 - ? { configuration: { ordered: true, supportedModes: options.supportedModes } } - : {}), }; function kindOf(namespace) { if (namespace.endsWith("Sensor")) diff --git a/dist/cjs/registry/resources.js b/dist/cjs/registry/resources.js index e8ddefb..290da18 100644 --- a/dist/cjs/registry/resources.js +++ b/dist/cjs/registry/resources.js @@ -27,6 +27,8 @@ const reserved = catalog_js_1.RESERVED_WORDS; exports.label = { expects: "a friendly name, from text() or asset()", parse(input, path = "") { + if (typeof input !== "object" || input === null) + throw (0, schema_js_1.mismatch)(path, exports.label.expects, input); const { "@type": type, value } = typed.parse(input, path); if (type === "asset") return { "@type": type, value: assetValue.parse(value, (0, schema_js_1.at)(path, "value")) }; diff --git a/dist/cjs/registry/semantics.js b/dist/cjs/registry/semantics.js new file mode 100644 index 0000000..3082bab --- /dev/null +++ b/dist/cjs/registry/semantics.js @@ -0,0 +1,112 @@ +"use strict"; +Object.defineProperty(exports, "__esModule", { value: true }); +exports.SemanticsBuilder = void 0; +exports.semantics = semantics; +exports.semanticsOf = semanticsOf; +// Semantics of a generic controller: the phrases "open", "close", "raise", "lower" mapped to directives, and states +// like "open" and "closed" mapped to values of the property (alexa-discovery-objects.html, "Semantics object"). +const catalog_js_1 = require("./catalog.js"); +const schema_js_1 = require("./schema.js"); +const listed = (given) => (Array.isArray(given) ? [...given] : [given]); +const withPrefix = (prefix, name) => (name.startsWith(prefix) ? name : `${prefix}${name}`); +/** + * 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. + */ +class SemanticsBuilder { + constructor() { + this.actionMappings = []; + this.stateMappings = []; + } + /** The phrases send the directive. payload is its payload; leave it out for a directive that has none. */ + action(actions, directive, payload) { + this.actionMappings.push({ + "@type": "ActionsToDirective", + actions: listed(actions).map((name) => withPrefix("Alexa.Actions.", name)), + directive: payload === undefined ? { name: directive } : { name: directive, payload }, + }); + return this; + } + /** The property at this value is in these states: "is the garage door open?" */ + state(states, value) { + this.stateMappings.push({ "@type": "StatesToValue", states: listed(states).map((name) => withPrefix("Alexa.States.", name)), value }); + return this; + } + /** The property between the two values, both included, is in these states. For an interface with a numeric property. */ + stateRange(states, minimumValue, maximumValue) { + this.stateMappings.push({ + "@type": "StatesToRange", + states: listed(states).map((name) => withPrefix("Alexa.States.", name)), + range: { minimumValue, maximumValue }, + }); + return this; + } +} +exports.SemanticsBuilder = SemanticsBuilder; +function semantics() { + return new SemanticsBuilder(); +} +const isHunch = (id) => /\.(SetEcoOn|SetEcoOff|EcoOn|EcoOff)$/.test(id); +/** The schema of the semantics option of one interface. It takes a semantics() builder or the object as discovery has it. */ +function semanticsOf({ directives, stateValue, ranges = false, hunches = false }) { + const allowed = (ids, what) => { + const choice = ids.filter((id) => hunches || !isHunch(id)); + return schema_js_1.s.array(schema_js_1.s.oneOf(choice, `${what}: ${choice.map((id) => id.split(".")[2]).join(", ")}`), { min: 1 }); + }; + const names = Object.keys(directives); + const lists = schema_js_1.s.object({ actionMappings: schema_js_1.s.optional(schema_js_1.s.array(schema_js_1.s.unknown())), stateMappings: schema_js_1.s.optional(schema_js_1.s.array(schema_js_1.s.unknown())) }); + const action = schema_js_1.s.object({ + "@type": schema_js_1.s.literal("ActionsToDirective"), + actions: allowed(catalog_js_1.ACTIONS, "a phrase of Alexa.Actions"), + directive: schema_js_1.s.object({ name: schema_js_1.s.oneOf(names, `a directive of the interface: ${names.join(", ")}`) }), + }); + const state = schema_js_1.s.object({ + "@type": ranges ? schema_js_1.s.enum("StatesToValue", "StatesToRange") : schema_js_1.s.enum("StatesToValue"), + states: allowed(catalog_js_1.STATES, "a state of Alexa.States"), + }); + const range = schema_js_1.s.object({ minimumValue: schema_js_1.s.number(), maximumValue: schema_js_1.s.number() }, { unknownKeys: "reject" }); + function actionMapping(input, path) { + const mapping = action.parse(input, path); + const { name, payload } = mapping.directive; + // Checked as the directive will arrive; a mapping without a payload stays without one in discovery + const checked = directives[name].payload.parse(payload ?? {}, (0, schema_js_1.at)(path, "directive.payload")); + return { "@type": mapping["@type"], actions: mapping.actions, directive: payload === undefined ? { name } : { name, payload: checked } }; + } + function stateMapping(input, path) { + const mapping = state.parse(input, path); + if (mapping["@type"] === "StatesToValue") { + return { "@type": mapping["@type"], states: mapping.states, value: stateValue.parse(mapping.value, (0, schema_js_1.at)(path, "value")) }; + } + const { minimumValue, maximumValue } = range.parse(mapping.range, (0, schema_js_1.at)(path, "range")); + if (minimumValue > maximumValue) + throw new schema_js_1.SchemaError((0, schema_js_1.at)(path, "range"), `the minimumValue ${minimumValue} is above the maximumValue ${maximumValue}`); + return { "@type": mapping["@type"], states: mapping.states, range: { minimumValue, maximumValue } }; + } + const expects = "semantics() with at least one action or state"; + return { + expects, + parse(input, path = "") { + if (typeof input !== "object" || input === null) + throw (0, schema_js_1.mismatch)(path, expects, input); + const { actionMappings = [], stateMappings = [] } = lists.parse(input, path); + if (actionMappings.length + stateMappings.length === 0) + throw (0, schema_js_1.mismatch)(path, expects, {}); + const parsed = {}; + if (actionMappings.length > 0) { + parsed.actionMappings = actionMappings.map((mapping, i) => actionMapping(mapping, `${(0, schema_js_1.at)(path, "actionMappings")}[${i}]`)); + } + if (stateMappings.length > 0) { + parsed.stateMappings = stateMappings.map((mapping, i) => stateMapping(mapping, `${(0, schema_js_1.at)(path, "stateMappings")}[${i}]`)); + } + return parsed; + }, + }; +} diff --git a/dist/esm/compat/AlexaInterface.d.ts b/dist/esm/compat/AlexaInterface.d.ts index f24a410..8e6eb0b 100644 --- a/dist/esm/compat/AlexaInterface.d.ts +++ b/dist/esm/compat/AlexaInterface.d.ts @@ -1,6 +1,6 @@ import { Capability } from "../device/Capability.js"; import type { CapabilityJson } from "../device/Capability.js"; -import type { Semantics } from "../registry/types.js"; +import type { Label, 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. */ @@ -19,7 +19,11 @@ export interface SupportedMode { } interface Options { semantics?: Semantics; - supportedModes?: Array; + supportedModes?: Array<{ + value: string; + friendlyNames: Label[]; + }>; + ordered?: boolean; } /** * A capability as 1.x declares it: device.addCapability(type, options), then the add and set methods below. It is a @@ -33,8 +37,14 @@ export declare class AlexaInterface extends Capability { 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): void; + /** + * The modes of a ModeController, as { value, modeResources } objects. A mode given as a string is announced as + * { value } and noted: Alexa wants friendly names for it. ordered is true unless options.ordered says otherwise, + * as 1.x announced every mode list; with device.add() the default is false. + */ + addSupportedModes(modes: Array, options?: { + ordered?: boolean; + }): void; setInstance(name: string): void; getType(): AlexaInterfaceType; /** @deprecated The same as getType(). */ diff --git a/dist/esm/compat/AlexaInterface.js b/dist/esm/compat/AlexaInterface.js index ef02b39..4e104de 100644 --- a/dist/esm/compat/AlexaInterface.js +++ b/dist/esm/compat/AlexaInterface.js @@ -25,9 +25,19 @@ export class AlexaInterface extends Capability { addFriendlyName(name, locale) { this.friendlyNames.push(text(name, locale)); } - /** The modes of a ModeController, as { value, modeResources } objects. */ - addSupportedModes(modes) { - this.options.supportedModes = modes; + /** + * The modes of a ModeController, as { value, modeResources } objects. A mode given as a string is announced as + * { value } and noted: Alexa wants friendly names for it. ordered is true unless options.ordered says otherwise, + * as 1.x announced every mode list; with device.add() the default is false. + */ + addSupportedModes(modes, options = {}) { + this.options.ordered = options.ordered ?? true; + this.options.supportedModes = modes.map((mode) => { + if (typeof mode !== "string") + return { value: mode.value, friendlyNames: (mode.modeResources?.friendlyNames ?? []) }; + this.notes.push(`the mode ${mode} was given as a string, pass { value, modeResources }`); + return { value: mode, friendlyNames: [] }; + }); } setInstance(name) { this.instance = name; diff --git a/dist/esm/device/validate.js b/dist/esm/device/validate.js index b5d9e01..1a1d74c 100644 --- a/dist/esm/device/validate.js +++ b/dist/esm/device/validate.js @@ -104,6 +104,15 @@ export function checkCapability(capability, descriptor, endpoint) { if (friendlyNames.length > 0) refuse("takes no friendly names"); } + // A capability of device.add() passed the schema when it was declared; one declared the 1.x way did not + if (descriptor.options) { + try { + descriptor.options.parse(capability.options); + } + catch (err) { + refuse(err instanceof SchemaError ? err.message : String(err)); + } + } // generic-controllers.html, "Semantics for user utterances": "Each semantic phrase must be unique across all // controller instances for each endpoint" const used = new Map(); diff --git a/dist/esm/index.d.ts b/dist/esm/index.d.ts index 303df58..89506d4 100644 --- a/dist/esm/index.d.ts +++ b/dist/esm/index.d.ts @@ -5,11 +5,11 @@ export type { EndpointDefinition, EndpointJson } from "./device/Device.js"; export { Capability } from "./device/Capability.js"; export type { CapabilityJson, CommonOptions, Declaration } from "./device/Capability.js"; export { registry, DeclarationError, SchemaError } from "./registry/index.js"; -export { Alexa, BrightnessController, TemperatureSensor } from "./registry/index.js"; +export { Alexa, BrightnessController, ModeController, RangeController, TemperatureSensor, ToggleController, } from "./registry/index.js"; export { PowerController, EndpointHealth } from "./compat/enums.js"; -export { asset, text } from "./registry/resources.js"; +export { asset, text, semantics, SemanticsBuilder } from "./registry/index.js"; export { ASSETS as Assets, UNITS_OF_MEASURE as Units, ACTIONS as Actions, STATES as States, DISPLAY_CATEGORIES as DisplayCategories, } from "./registry/index.js"; -export type { ActionId, AssetId, DisplayCategoryName, StateId, UnitOfMeasure, ActionsToDirective, AnyDescriptor, CapabilityExtras, Declared, DirectiveDescriptor, EndpointView, EventDescriptor, InterfaceDescriptor, Label, PropertyDescriptor, Semantics, StatesToRange, StatesToValue, Infer, Schema, Temperature, TimeInterval, } from "./registry/index.js"; +export type { ActionId, AssetId, DisplayCategoryName, StateId, UnitOfMeasure, ActionsToDirective, AnyDescriptor, CapabilityExtras, Declared, DirectiveDescriptor, EndpointView, EventDescriptor, InterfaceDescriptor, Label, PropertyDescriptor, Semantics, StatesToRange, StatesToValue, ActionName, StateName, Mode, Infer, Schema, Temperature, TimeInterval, } from "./registry/index.js"; export { AlexaInterface } from "./compat/AlexaInterface.js"; export type { SupportedMode } from "./compat/AlexaInterface.js"; export { ActionMapping } from "./compat/ActionMapping.js"; diff --git a/dist/esm/index.js b/dist/esm/index.js index 9e8ab0c..d9342f0 100644 --- a/dist/esm/index.js +++ b/dist/esm/index.js @@ -4,9 +4,9 @@ export { default as Device } from "./device/Device.js"; export { Capability } from "./device/Capability.js"; // The interfaces, for device.add(), and the registry that holds them by name export { registry, DeclarationError, SchemaError } from "./registry/index.js"; -export { Alexa, BrightnessController, TemperatureSensor } from "./registry/index.js"; +export { Alexa, BrightnessController, ModeController, RangeController, TemperatureSensor, ToggleController, } from "./registry/index.js"; export { PowerController, EndpointHealth } from "./compat/enums.js"; -export { asset, text } from "./registry/resources.js"; +export { asset, text, semantics, SemanticsBuilder } from "./registry/index.js"; // The vocabularies of the Smart Home API export { ASSETS as Assets, UNITS_OF_MEASURE as Units, ACTIONS as Actions, STATES as States, DISPLAY_CATEGORIES as DisplayCategories, } from "./registry/index.js"; // 1.x diff --git a/dist/esm/registry/index.d.ts b/dist/esm/registry/index.d.ts index 316e8d2..701579b 100644 --- a/dist/esm/registry/index.d.ts +++ b/dist/esm/registry/index.d.ts @@ -1,8 +1,11 @@ import { Alexa } from "./interfaces/Alexa.js"; import { BrightnessController } from "./interfaces/BrightnessController.js"; import { EndpointHealth } from "./interfaces/EndpointHealth.js"; +import { ModeController } from "./interfaces/ModeController.js"; import { PowerController } from "./interfaces/PowerController.js"; +import { RangeController } from "./interfaces/RangeController.js"; import { TemperatureSensor } from "./interfaces/TemperatureSensor.js"; +import { ToggleController } from "./interfaces/ToggleController.js"; import type { AnyDescriptor } from "./types.js"; export declare const registry: { /** Whether an interface of this name is known. */ @@ -12,7 +15,11 @@ export declare const registry: { /** Every descriptor, ordered by namespace. */ list(): AnyDescriptor[]; }; -export { Alexa, BrightnessController, EndpointHealth, PowerController, TemperatureSensor }; +export { Alexa, BrightnessController, EndpointHealth, ModeController, PowerController, RangeController, TemperatureSensor, ToggleController, }; +export type { Mode } from "./interfaces/ModeController.js"; +export { asset, text } from "./resources.js"; +export { semantics, SemanticsBuilder } from "./semantics.js"; +export type { ActionName, StateName } from "./semantics.js"; export { DeclarationError, defineInterface } from "./types.js"; export type { ActionsToDirective, AnyDescriptor, CapabilityExtras, Declared, DirectiveDescriptor, EndpointView, EventDescriptor, InterfaceDescriptor, Label, PropertyDescriptor, Semantics, StatesToRange, StatesToValue, } from "./types.js"; export { s, SchemaError } from "./schema.js"; diff --git a/dist/esm/registry/index.js b/dist/esm/registry/index.js index 91dc8ba..d8a80e2 100644 --- a/dist/esm/registry/index.js +++ b/dist/esm/registry/index.js @@ -2,16 +2,22 @@ import { Alexa } from "./interfaces/Alexa.js"; import { BrightnessController } from "./interfaces/BrightnessController.js"; import { EndpointHealth } from "./interfaces/EndpointHealth.js"; +import { ModeController } from "./interfaces/ModeController.js"; import { PowerController } from "./interfaces/PowerController.js"; +import { RangeController } from "./interfaces/RangeController.js"; import { TemperatureSensor } from "./interfaces/TemperatureSensor.js"; +import { ToggleController } from "./interfaces/ToggleController.js"; import { STUBS } from "./interfaces/stubs.js"; import { DeclarationError } from "./types.js"; const described = [ Alexa, BrightnessController, EndpointHealth, + ModeController, PowerController, + RangeController, TemperatureSensor, + ToggleController, ]; const descriptors = new Map(); for (const descriptor of [...described, ...STUBS]) { @@ -37,7 +43,9 @@ export const registry = { return [...descriptors.values()].sort((a, b) => (a.namespace < b.namespace ? -1 : 1)); }, }; -export { Alexa, BrightnessController, EndpointHealth, PowerController, TemperatureSensor }; +export { Alexa, BrightnessController, EndpointHealth, ModeController, PowerController, RangeController, TemperatureSensor, ToggleController, }; +export { asset, text } from "./resources.js"; +export { semantics, SemanticsBuilder } from "./semantics.js"; export { DeclarationError, defineInterface } from "./types.js"; export { s, SchemaError } from "./schema.js"; export * from "./catalog.js"; diff --git a/dist/esm/registry/interfaces/ModeController.d.ts b/dist/esm/registry/interfaces/ModeController.d.ts new file mode 100644 index 0000000..f8bba4d --- /dev/null +++ b/dist/esm/registry/interfaces/ModeController.d.ts @@ -0,0 +1,43 @@ +import type { Schema } from "../schema.js"; +import type { Label } from "../types.js"; +/** One mode: its value and what the user calls it. */ +export interface Mode { + value: string; + friendlyNames: Label[]; +} +/** + * One of a list of values, under an instance name: the wash cycle of a washer, the position of a garage door. Amazon + * certifies a garage door only with this interface and the display category GARAGE_DOOR. + */ +export declare const ModeController: import("../types.js").InterfaceDescriptor<{ + mode: { + name: string; + value: Schema; + note: string; + }; +}, { + SetMode: { + name: string; + payload: Schema; + }>>; + }; + AdjustMode: { + name: string; + payload: Schema; + }>>; + when: ({ options }: { + options: { + ordered?: boolean; + }; + }) => boolean; + note: string; + }; +}, import("../schema.js").InferShape<{ + /** At least two. When the modes have an order, in increasing order. */ + supportedModes: Schema; + /** The modes have an order, cold to hot, and the user can say "increase": Alexa sends AdjustMode. Default: false. */ + ordered: import("../schema.js").OptionalSchema; + semantics: import("../schema.js").OptionalSchema; +}>, true>; diff --git a/dist/esm/registry/interfaces/ModeController.js b/dist/esm/registry/interfaces/ModeController.js new file mode 100644 index 0000000..84d08f4 --- /dev/null +++ b/dist/esm/registry/interfaces/ModeController.js @@ -0,0 +1,84 @@ +import { labels } from "../resources.js"; +import { at, mismatch, s } from "../schema.js"; +import { semanticsOf } from "../semantics.js"; +import { DeclarationError, defineInterface } from "../types.js"; +const directives = { + SetMode: { name: "SetMode", payload: s.object({ mode: s.string({ min: 1 }) }) }, + AdjustMode: { + name: "AdjustMode", + payload: s.object({ modeDelta: s.optional(s.number({ integer: true })) }), + // alexa-modecontroller.html, "Capabilities object": "Modes that have an order support the AdjustMode directive." + when: ({ options }) => options.ordered === true, + note: "modeDelta is the number of modes to move by, 1 when it is left out", + }, +}; +// A mode is declared as { value, friendlyNames }. The object of discovery and of 1.x, { value, modeResources: +// { friendlyNames } }, is taken as well. +const eitherForm = s.object({ + value: s.string({ min: 1 }), + friendlyNames: s.optional(s.unknown()), + modeResources: s.optional(s.object({ friendlyNames: s.unknown() })), +}, { unknownKeys: "reject" }); +const mode = { + expects: "a mode { value, friendlyNames }", + parse(input, path = "") { + if (typeof input !== "object" || input === null) + throw mismatch(path, mode.expects, input); + const { value, friendlyNames, modeResources } = eitherForm.parse(input, path); + const named = friendlyNames === undefined && modeResources ? "modeResources.friendlyNames" : "friendlyNames"; + return { value, friendlyNames: labels.parse(friendlyNames ?? modeResources?.friendlyNames, at(path, named)) }; + }, +}; +/** + * One of a list of values, under an instance name: the wash cycle of a washer, the position of a garage door. Amazon + * certifies a garage door only with this interface and the display category GARAGE_DOOR. + */ +export const ModeController = defineInterface({ + namespace: "Alexa.ModeController", + version: "3", + doc: "https://developer.amazon.com/docs/alexaplus/device-apis/alexa-modecontroller.html", + kind: "controller", + tier: 1, + instanced: true, + properties: { + mode: { name: "mode", value: s.nullable(s.string({ min: 1 })), note: "null when no mode is set, as when the device is off" }, + }, + directives, + options: s.object({ + /** At least two. When the modes have an order, in increasing order. */ + supportedModes: s.array(mode, { min: 2 }), + /** The modes have an order, cold to hot, and the user can say "increase": Alexa sends AdjustMode. Default: false. */ + ordered: s.optional(s.boolean()), + semantics: s.optional(semanticsOf({ directives, stateValue: s.string({ min: 1 }) })), + }, { unknownKeys: "reject" }), + // A capability declared the 1.x way may be without modes, or have modes without names + discovery({ options: { supportedModes = [], ordered = false } }) { + if (supportedModes.length === 0) + return {}; + const modes = supportedModes.map(({ value, friendlyNames = [] }) => (friendlyNames.length > 0 ? { value, modeResources: { friendlyNames } } : { value })); + return { configuration: { ordered, supportedModes: modes } }; + }, + validate(capability) { + const { supportedModes, ordered = false, semantics } = capability.options; + const values = supportedModes.map(({ value }) => value); + const twice = values.find((value, i) => values.indexOf(value) !== i); + if (twice !== undefined) + throw new DeclarationError(capability, `the mode ${twice} is listed twice`); + const isMode = (value) => values.includes(value); + for (const { directive } of semantics?.actionMappings ?? []) { + if (directive.name === "AdjustMode" && !ordered) { + throw new DeclarationError(capability, "an action is mapped to AdjustMode, which needs ordered: true"); + } + if (directive.name === "SetMode" && !isMode(directive.payload?.mode)) { + throw new DeclarationError(capability, `an action is mapped to SetMode ${directive.payload?.mode}, the modes are ${values.join(", ")}`); + } + } + for (const mapping of semantics?.stateMappings ?? []) { + if (mapping["@type"] === "StatesToValue" && !isMode(mapping.value)) { + throw new DeclarationError(capability, `a state is mapped to ${mapping.value}, the modes are ${values.join(", ")}`); + } + } + }, + errorNamespace: "Alexa.Safety", + errorTypes: ["OBSTACLE_DETECTED", "SAFETY_BEAM_BREACHED"], +}); diff --git a/dist/esm/registry/interfaces/RangeController.d.ts b/dist/esm/registry/interfaces/RangeController.d.ts new file mode 100644 index 0000000..e7f7417 --- /dev/null +++ b/dist/esm/registry/interfaces/RangeController.d.ts @@ -0,0 +1,39 @@ +/** + * A number in a range, under an instance name: the position of a blind, the speed of a fan. With nonControllable it + * is a reading the user can ask for, like an air quality index. + */ +export declare const RangeController: import("../types.js").InterfaceDescriptor<{ + rangeValue: { + name: string; + value: import("../schema.js").Schema; + }; +}, { + SetRangeValue: { + name: string; + payload: import("../schema.js").Schema; + }>>; + }; + AdjustRangeValue: { + name: string; + payload: import("../schema.js").Schema; + rangeValueDeltaDefault: import("../schema.js").Schema; + }>>; + note: string; + }; +}, import("../schema.js").InferShape<{ + /** precision is the step of the range and what "turn up the fan speed" changes it by. */ + range: import("../schema.js").Schema; + max: import("../schema.js").Schema; + precision: import("../schema.js").Schema; + }>>; + unit: import("../schema.js").OptionalSchema; + /** Names for values: "set the fan speed to maximum". */ + presets: import("../schema.js").OptionalSchema; + friendlyNames: import("../schema.js").Schema; + }>[]>; + semantics: import("../schema.js").OptionalSchema; +}>, true>; diff --git a/dist/esm/registry/interfaces/RangeController.js b/dist/esm/registry/interfaces/RangeController.js new file mode 100644 index 0000000..0189b31 --- /dev/null +++ b/dist/esm/registry/interfaces/RangeController.js @@ -0,0 +1,73 @@ +import { UNITS_OF_MEASURE } from "../catalog.js"; +import { labels } from "../resources.js"; +import { s } from "../schema.js"; +import { semanticsOf } from "../semantics.js"; +import { DeclarationError, defineInterface } from "../types.js"; +const directives = { + SetRangeValue: { name: "SetRangeValue", payload: s.object({ rangeValue: s.number() }) }, + AdjustRangeValue: { + name: "AdjustRangeValue", + payload: s.object({ rangeValueDelta: s.number(), rangeValueDeltaDefault: s.boolean() }), + note: "rangeValueDeltaDefault is true when the user named no amount; rangeValueDelta is then the precision", + }, +}; +// 0.1 + 0.2 is not 0.3: a value is on the grid when it is within a millionth of a step of it +function onGrid(value, origin, step) { + const steps = (value - origin) / step; + return Math.abs(steps - Math.round(steps)) < 1e-6; +} +/** + * A number in a range, under an instance name: the position of a blind, the speed of a fan. With nonControllable it + * is a reading the user can ask for, like an air quality index. + */ +export const RangeController = defineInterface({ + namespace: "Alexa.RangeController", + version: "3", + doc: "https://developer.amazon.com/docs/alexaplus/device-apis/alexa-rangecontroller.html", + kind: "controller", + tier: 1, + instanced: true, + properties: { + rangeValue: { name: "rangeValue", value: s.number() }, + }, + directives, + options: s.object({ + /** precision is the step of the range and what "turn up the fan speed" changes it by. */ + range: s.object({ min: s.number(), max: s.number(), precision: s.number({ gt: 0 }) }, { unknownKeys: "reject" }), + unit: s.optional(s.oneOf(UNITS_OF_MEASURE, "a unit of measure like Alexa.Unit.Percent")), + /** Names for values: "set the fan speed to maximum". */ + presets: s.optional(s.array(s.object({ value: s.number(), friendlyNames: labels }, { unknownKeys: "reject" }))), + semantics: s.optional(semanticsOf({ directives, stateValue: s.number(), ranges: true })), + }, { unknownKeys: "reject" }), + // A capability declared the 1.x way may be without a range; check() says so, discovery lists what there is + discovery({ options: { range, unit, presets } }) { + const configuration = { + ...(range && { supportedRange: { minimumValue: range.min, maximumValue: range.max, precision: range.precision } }), + ...(unit && { unitOfMeasure: unit }), + ...(presets && { presets: presets.map(({ value, friendlyNames }) => ({ rangeValue: value, presetResources: { friendlyNames } })) }), + }; + return Object.keys(configuration).length > 0 ? { configuration } : {}; + }, + validate(capability) { + const { range: { min, max, precision }, presets = [], semantics } = capability.options; + const inRange = (value) => value >= min && value <= max; + if (max <= min) + throw new DeclarationError(capability, `range.max ${max} is not above range.min ${min}`); + for (const { value } of presets) { + // alexa-rangecontroller.html, "Preset object": "minimum range value + (n x precision) where n is an integer" + if (!inRange(value) || !onGrid(value, min, precision)) { + throw new DeclarationError(capability, `the preset ${value} is not ${min} + n x ${precision}, up to ${max}`); + } + } + for (const { directive } of semantics?.actionMappings ?? []) { + const { rangeValue } = directive.payload ?? {}; + if (directive.name === "SetRangeValue" && !inRange(rangeValue)) { + throw new DeclarationError(capability, `an action is mapped to SetRangeValue ${rangeValue}, the range is ${min} to ${max}`); + } + } + }, + // alexa-rangecontroller.html, "SetRangeValue directive error handling": "If your error is safety related, respond + // with an Alexa.Safety.ErrorResponse" + errorNamespace: "Alexa.Safety", + errorTypes: ["OBSTACLE_DETECTED", "SAFETY_BEAM_BREACHED"], +}); diff --git a/dist/esm/registry/interfaces/ToggleController.d.ts b/dist/esm/registry/interfaces/ToggleController.d.ts new file mode 100644 index 0000000..7d610d4 --- /dev/null +++ b/dist/esm/registry/interfaces/ToggleController.d.ts @@ -0,0 +1,21 @@ +/** + * Something that is on or off, under an instance name: the oscillation of a fan, the light of an oven. The one + * generic controller that Alexa hunches work with (SetEcoOn, SetEcoOff, EcoOn, EcoOff). + */ +export declare const ToggleController: import("../types.js").InterfaceDescriptor<{ + toggleState: { + name: string; + value: import("../schema.js").EnumSchema<"ON" | "OFF">; + }; +}, { + TurnOn: { + name: string; + payload: import("../schema.js").Schema>; + }; + TurnOff: { + name: string; + payload: import("../schema.js").Schema>; + }; +}, import("../schema.js").InferShape<{ + semantics: import("../schema.js").OptionalSchema; +}>, true>; diff --git a/dist/esm/registry/interfaces/ToggleController.js b/dist/esm/registry/interfaces/ToggleController.js new file mode 100644 index 0000000..4657019 --- /dev/null +++ b/dist/esm/registry/interfaces/ToggleController.js @@ -0,0 +1,28 @@ +import { s } from "../schema.js"; +import { semanticsOf } from "../semantics.js"; +import { defineInterface } from "../types.js"; +const directives = { + TurnOn: { name: "TurnOn", payload: s.object({}) }, + TurnOff: { name: "TurnOff", payload: s.object({}) }, +}; +/** + * Something that is on or off, under an instance name: the oscillation of a fan, the light of an oven. The one + * generic controller that Alexa hunches work with (SetEcoOn, SetEcoOff, EcoOn, EcoOff). + */ +export const ToggleController = defineInterface({ + namespace: "Alexa.ToggleController", + version: "3", + doc: "https://developer.amazon.com/docs/alexaplus/device-apis/alexa-togglecontroller.html", + kind: "controller", + tier: 1, + instanced: true, + properties: { + toggleState: { name: "toggleState", value: s.enum("ON", "OFF") }, + }, + directives, + options: s.object({ + semantics: s.optional(semanticsOf({ directives, stateValue: s.enum("ON", "OFF"), hunches: true })), + }, { unknownKeys: "reject" }), + errorNamespace: "Alexa.Safety", + errorTypes: ["OBSTACLE_DETECTED", "SAFETY_BEAM_BREACHED"], +}); diff --git a/dist/esm/registry/interfaces/stubs.js b/dist/esm/registry/interfaces/stubs.js index f5f05df..afb289b 100644 --- a/dist/esm/registry/interfaces/stubs.js +++ b/dist/esm/registry/interfaces/stubs.js @@ -45,7 +45,6 @@ const TABLE = [ ["Alexa.Media.PlayQueue", "1", [], "alexa-media-playqueue.html"], ["Alexa.Media.Playback", "1", [], "alexa-media-playback.html"], ["Alexa.Media.Search", "1", [], "alexa-media-search.html"], - ["Alexa.ModeController", "3", ["mode"], "alexa-modecontroller.html"], ["Alexa.MotionSensor", "3", [], "alexa-motionsensor.html"], ["Alexa.PercentageController", "3", [], "alexa-percentagecontroller.html"], ["Alexa.PlaybackController", "3", [], "alexa-playbackcontroller.html"], @@ -53,7 +52,6 @@ const TABLE = [ ["Alexa.PowerLevelController", "3", [], "alexa-powerlevelcontroller.html"], ["Alexa.ProactiveNotificationSource", "1", [], "alexa-proactivenotificationsource.html"], ["Alexa.RTCSessionController", "1", [], "alexa-rtcsessioncontroller.html"], - ["Alexa.RangeController", "3", [], "alexa-rangecontroller.html"], ["Alexa.RecordController", "3", [], "alexa-recordcontroller.html"], ["Alexa.RemoteVideoPlayer", "1", [], "alexa-remotevideoplayer.html"], ["Alexa.SceneController", "3", [], "alexa-scenecontroller.html"], @@ -71,13 +69,12 @@ const TABLE = [ ["Alexa.ThermostatController.Schedule", "1", [], "alexa-thermostatcontroller-schedule.html"], // "UNKNOWN" in 1.5.2 as well; the page is titled "Interface 3" ["Alexa.TimeHoldController", "3", [], "alexa-timeholdcontroller.html"], - ["Alexa.ToggleController", "3", ["toggleState"], "alexa-togglecontroller.html"], ["Alexa.UIController", "1", [], "alexa-uicontroller.html"], ["Alexa.UserPreference", "1", [], "alexa-userpreference.html"], ["Alexa.VideoRecorder", "1", [], "alexa-videorecorder.html"], ["Alexa.WakeOnLANController", "1", [], "alexa-wakeonlancontroller.html"], ]; -// What 1.5.2 added to the capability object of three of them +// What 1.5.2 added to the capability object of two of them const EXTRAS = { // No properties object; supportsDeactivation and proactivelyReported on the capability itself "Alexa.SceneController": ({ proactivelyReported }) => ({ @@ -87,9 +84,6 @@ const EXTRAS = { "Alexa.ThermostatController": () => ({ configuration: { supportedModes: ["HEAT", "COOL", "AUTO", "OFF"], supportsScheduling: false }, }), - "Alexa.ModeController": ({ options }) => (options.supportedModes?.length > 0 - ? { configuration: { ordered: true, supportedModes: options.supportedModes } } - : {}), }; function kindOf(namespace) { if (namespace.endsWith("Sensor")) diff --git a/dist/esm/registry/resources.js b/dist/esm/registry/resources.js index 4b832ff..b4cdbab 100644 --- a/dist/esm/registry/resources.js +++ b/dist/esm/registry/resources.js @@ -1,6 +1,6 @@ // 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, s, SchemaError } from "./schema.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 } }; @@ -21,6 +21,8 @@ const reserved = RESERVED_WORDS; 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")) }; diff --git a/dist/esm/registry/semantics.d.ts b/dist/esm/registry/semantics.d.ts new file mode 100644 index 0000000..da2f381 --- /dev/null +++ b/dist/esm/registry/semantics.d.ts @@ -0,0 +1,47 @@ +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 `${Prefix}${infer Name}` ? Name : never; +/** A phrase by its id or by its name: "Alexa.Actions.Open" or "Open". */ +export type ActionName = ActionId | Short; +/** A state by its id or by its name: "Alexa.States.Closed" or "Closed". */ +export type StateName = StateId | Short; +/** + * 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; + /** 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): 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; + /** 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; +export {}; diff --git a/dist/esm/registry/semantics.js b/dist/esm/registry/semantics.js new file mode 100644 index 0000000..0b653f3 --- /dev/null +++ b/dist/esm/registry/semantics.js @@ -0,0 +1,106 @@ +// Semantics of a generic controller: the phrases "open", "close", "raise", "lower" mapped to directives, and states +// like "open" and "closed" mapped to values of the property (alexa-discovery-objects.html, "Semantics object"). +import { ACTIONS, STATES } from "./catalog.js"; +import { at, mismatch, s, SchemaError } from "./schema.js"; +const listed = (given) => (Array.isArray(given) ? [...given] : [given]); +const withPrefix = (prefix, name) => (name.startsWith(prefix) ? name : `${prefix}${name}`); +/** + * 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 class SemanticsBuilder { + constructor() { + this.actionMappings = []; + this.stateMappings = []; + } + /** The phrases send the directive. payload is its payload; leave it out for a directive that has none. */ + action(actions, directive, payload) { + this.actionMappings.push({ + "@type": "ActionsToDirective", + actions: listed(actions).map((name) => withPrefix("Alexa.Actions.", name)), + directive: payload === undefined ? { name: directive } : { name: directive, payload }, + }); + return this; + } + /** The property at this value is in these states: "is the garage door open?" */ + state(states, value) { + this.stateMappings.push({ "@type": "StatesToValue", states: listed(states).map((name) => withPrefix("Alexa.States.", name)), value }); + return this; + } + /** The property between the two values, both included, is in these states. For an interface with a numeric property. */ + stateRange(states, minimumValue, maximumValue) { + this.stateMappings.push({ + "@type": "StatesToRange", + states: listed(states).map((name) => withPrefix("Alexa.States.", name)), + range: { minimumValue, maximumValue }, + }); + return this; + } +} +export function semantics() { + return new SemanticsBuilder(); +} +const isHunch = (id) => /\.(SetEcoOn|SetEcoOff|EcoOn|EcoOff)$/.test(id); +/** The schema of the semantics option of one interface. It takes a semantics() builder or the object as discovery has it. */ +export function semanticsOf({ directives, stateValue, ranges = false, hunches = false }) { + const allowed = (ids, what) => { + const choice = ids.filter((id) => hunches || !isHunch(id)); + return s.array(s.oneOf(choice, `${what}: ${choice.map((id) => id.split(".")[2]).join(", ")}`), { min: 1 }); + }; + const names = Object.keys(directives); + const lists = s.object({ actionMappings: s.optional(s.array(s.unknown())), stateMappings: s.optional(s.array(s.unknown())) }); + const action = s.object({ + "@type": s.literal("ActionsToDirective"), + actions: allowed(ACTIONS, "a phrase of Alexa.Actions"), + directive: s.object({ name: s.oneOf(names, `a directive of the interface: ${names.join(", ")}`) }), + }); + const state = s.object({ + "@type": ranges ? s.enum("StatesToValue", "StatesToRange") : s.enum("StatesToValue"), + states: allowed(STATES, "a state of Alexa.States"), + }); + const range = s.object({ minimumValue: s.number(), maximumValue: s.number() }, { unknownKeys: "reject" }); + function actionMapping(input, path) { + const mapping = action.parse(input, path); + const { name, payload } = mapping.directive; + // Checked as the directive will arrive; a mapping without a payload stays without one in discovery + const checked = directives[name].payload.parse(payload ?? {}, at(path, "directive.payload")); + return { "@type": mapping["@type"], actions: mapping.actions, directive: payload === undefined ? { name } : { name, payload: checked } }; + } + function stateMapping(input, path) { + const mapping = state.parse(input, path); + if (mapping["@type"] === "StatesToValue") { + return { "@type": mapping["@type"], states: mapping.states, value: stateValue.parse(mapping.value, at(path, "value")) }; + } + const { minimumValue, maximumValue } = range.parse(mapping.range, at(path, "range")); + if (minimumValue > maximumValue) + throw new SchemaError(at(path, "range"), `the minimumValue ${minimumValue} is above the maximumValue ${maximumValue}`); + return { "@type": mapping["@type"], states: mapping.states, range: { minimumValue, maximumValue } }; + } + const expects = "semantics() with at least one action or state"; + return { + expects, + parse(input, path = "") { + if (typeof input !== "object" || input === null) + throw mismatch(path, expects, input); + const { actionMappings = [], stateMappings = [] } = lists.parse(input, path); + if (actionMappings.length + stateMappings.length === 0) + throw mismatch(path, expects, {}); + const parsed = {}; + if (actionMappings.length > 0) { + parsed.actionMappings = actionMappings.map((mapping, i) => actionMapping(mapping, `${at(path, "actionMappings")}[${i}]`)); + } + if (stateMappings.length > 0) { + parsed.stateMappings = stateMappings.map((mapping, i) => stateMapping(mapping, `${at(path, "stateMappings")}[${i}]`)); + } + return parsed; + }, + }; +} diff --git a/dist/esm/registry/types.d.ts b/dist/esm/registry/types.d.ts index c01b242..d6e882e 100644 --- a/dist/esm/registry/types.d.ts +++ b/dist/esm/registry/types.d.ts @@ -120,7 +120,11 @@ export interface InterfaceDescriptor

; /** What a declaration can set beyond the fields every capability has: a range, the supported modes. */ options?: Schema; - discovery?: (capability: Declared) => CapabilityExtras; + /** + * What the interface adds to the capability object. The options may be incomplete: a capability declared the + * 1.x way is announced with what it has, and check() of its device says what is missing. + */ + discovery?: (capability: Declared>) => CapabilityExtras; /** The event that answers a directive when it is not Alexa / Response (Arm -> Arm.Response). */ responseFor?: (directive: string) => { namespace: string; @@ -132,7 +136,7 @@ export interface InterfaceDescriptor

, endpoint: EndpointView) => void; } export type AnyDescriptor = InterfaceDescriptor; diff --git a/dist/types/compat/AlexaInterface.d.ts b/dist/types/compat/AlexaInterface.d.ts index f24a410..8e6eb0b 100644 --- a/dist/types/compat/AlexaInterface.d.ts +++ b/dist/types/compat/AlexaInterface.d.ts @@ -1,6 +1,6 @@ import { Capability } from "../device/Capability.js"; import type { CapabilityJson } from "../device/Capability.js"; -import type { Semantics } from "../registry/types.js"; +import type { Label, 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. */ @@ -19,7 +19,11 @@ export interface SupportedMode { } interface Options { semantics?: Semantics; - supportedModes?: Array; + supportedModes?: Array<{ + value: string; + friendlyNames: Label[]; + }>; + ordered?: boolean; } /** * A capability as 1.x declares it: device.addCapability(type, options), then the add and set methods below. It is a @@ -33,8 +37,14 @@ export declare class AlexaInterface extends Capability { 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): void; + /** + * The modes of a ModeController, as { value, modeResources } objects. A mode given as a string is announced as + * { value } and noted: Alexa wants friendly names for it. ordered is true unless options.ordered says otherwise, + * as 1.x announced every mode list; with device.add() the default is false. + */ + addSupportedModes(modes: Array, options?: { + ordered?: boolean; + }): void; setInstance(name: string): void; getType(): AlexaInterfaceType; /** @deprecated The same as getType(). */ diff --git a/dist/types/index.d.ts b/dist/types/index.d.ts index 303df58..89506d4 100644 --- a/dist/types/index.d.ts +++ b/dist/types/index.d.ts @@ -5,11 +5,11 @@ export type { EndpointDefinition, EndpointJson } from "./device/Device.js"; export { Capability } from "./device/Capability.js"; export type { CapabilityJson, CommonOptions, Declaration } from "./device/Capability.js"; export { registry, DeclarationError, SchemaError } from "./registry/index.js"; -export { Alexa, BrightnessController, TemperatureSensor } from "./registry/index.js"; +export { Alexa, BrightnessController, ModeController, RangeController, TemperatureSensor, ToggleController, } from "./registry/index.js"; export { PowerController, EndpointHealth } from "./compat/enums.js"; -export { asset, text } from "./registry/resources.js"; +export { asset, text, semantics, SemanticsBuilder } from "./registry/index.js"; export { ASSETS as Assets, UNITS_OF_MEASURE as Units, ACTIONS as Actions, STATES as States, DISPLAY_CATEGORIES as DisplayCategories, } from "./registry/index.js"; -export type { ActionId, AssetId, DisplayCategoryName, StateId, UnitOfMeasure, ActionsToDirective, AnyDescriptor, CapabilityExtras, Declared, DirectiveDescriptor, EndpointView, EventDescriptor, InterfaceDescriptor, Label, PropertyDescriptor, Semantics, StatesToRange, StatesToValue, Infer, Schema, Temperature, TimeInterval, } from "./registry/index.js"; +export type { ActionId, AssetId, DisplayCategoryName, StateId, UnitOfMeasure, ActionsToDirective, AnyDescriptor, CapabilityExtras, Declared, DirectiveDescriptor, EndpointView, EventDescriptor, InterfaceDescriptor, Label, PropertyDescriptor, Semantics, StatesToRange, StatesToValue, ActionName, StateName, Mode, Infer, Schema, Temperature, TimeInterval, } from "./registry/index.js"; export { AlexaInterface } from "./compat/AlexaInterface.js"; export type { SupportedMode } from "./compat/AlexaInterface.js"; export { ActionMapping } from "./compat/ActionMapping.js"; diff --git a/dist/types/registry/index.d.ts b/dist/types/registry/index.d.ts index 316e8d2..701579b 100644 --- a/dist/types/registry/index.d.ts +++ b/dist/types/registry/index.d.ts @@ -1,8 +1,11 @@ import { Alexa } from "./interfaces/Alexa.js"; import { BrightnessController } from "./interfaces/BrightnessController.js"; import { EndpointHealth } from "./interfaces/EndpointHealth.js"; +import { ModeController } from "./interfaces/ModeController.js"; import { PowerController } from "./interfaces/PowerController.js"; +import { RangeController } from "./interfaces/RangeController.js"; import { TemperatureSensor } from "./interfaces/TemperatureSensor.js"; +import { ToggleController } from "./interfaces/ToggleController.js"; import type { AnyDescriptor } from "./types.js"; export declare const registry: { /** Whether an interface of this name is known. */ @@ -12,7 +15,11 @@ export declare const registry: { /** Every descriptor, ordered by namespace. */ list(): AnyDescriptor[]; }; -export { Alexa, BrightnessController, EndpointHealth, PowerController, TemperatureSensor }; +export { Alexa, BrightnessController, EndpointHealth, ModeController, PowerController, RangeController, TemperatureSensor, ToggleController, }; +export type { Mode } from "./interfaces/ModeController.js"; +export { asset, text } from "./resources.js"; +export { semantics, SemanticsBuilder } from "./semantics.js"; +export type { ActionName, StateName } from "./semantics.js"; export { DeclarationError, defineInterface } from "./types.js"; export type { ActionsToDirective, AnyDescriptor, CapabilityExtras, Declared, DirectiveDescriptor, EndpointView, EventDescriptor, InterfaceDescriptor, Label, PropertyDescriptor, Semantics, StatesToRange, StatesToValue, } from "./types.js"; export { s, SchemaError } from "./schema.js"; diff --git a/dist/types/registry/interfaces/ModeController.d.ts b/dist/types/registry/interfaces/ModeController.d.ts new file mode 100644 index 0000000..f8bba4d --- /dev/null +++ b/dist/types/registry/interfaces/ModeController.d.ts @@ -0,0 +1,43 @@ +import type { Schema } from "../schema.js"; +import type { Label } from "../types.js"; +/** One mode: its value and what the user calls it. */ +export interface Mode { + value: string; + friendlyNames: Label[]; +} +/** + * One of a list of values, under an instance name: the wash cycle of a washer, the position of a garage door. Amazon + * certifies a garage door only with this interface and the display category GARAGE_DOOR. + */ +export declare const ModeController: import("../types.js").InterfaceDescriptor<{ + mode: { + name: string; + value: Schema; + note: string; + }; +}, { + SetMode: { + name: string; + payload: Schema; + }>>; + }; + AdjustMode: { + name: string; + payload: Schema; + }>>; + when: ({ options }: { + options: { + ordered?: boolean; + }; + }) => boolean; + note: string; + }; +}, import("../schema.js").InferShape<{ + /** At least two. When the modes have an order, in increasing order. */ + supportedModes: Schema; + /** The modes have an order, cold to hot, and the user can say "increase": Alexa sends AdjustMode. Default: false. */ + ordered: import("../schema.js").OptionalSchema; + semantics: import("../schema.js").OptionalSchema; +}>, true>; diff --git a/dist/types/registry/interfaces/RangeController.d.ts b/dist/types/registry/interfaces/RangeController.d.ts new file mode 100644 index 0000000..e7f7417 --- /dev/null +++ b/dist/types/registry/interfaces/RangeController.d.ts @@ -0,0 +1,39 @@ +/** + * A number in a range, under an instance name: the position of a blind, the speed of a fan. With nonControllable it + * is a reading the user can ask for, like an air quality index. + */ +export declare const RangeController: import("../types.js").InterfaceDescriptor<{ + rangeValue: { + name: string; + value: import("../schema.js").Schema; + }; +}, { + SetRangeValue: { + name: string; + payload: import("../schema.js").Schema; + }>>; + }; + AdjustRangeValue: { + name: string; + payload: import("../schema.js").Schema; + rangeValueDeltaDefault: import("../schema.js").Schema; + }>>; + note: string; + }; +}, import("../schema.js").InferShape<{ + /** precision is the step of the range and what "turn up the fan speed" changes it by. */ + range: import("../schema.js").Schema; + max: import("../schema.js").Schema; + precision: import("../schema.js").Schema; + }>>; + unit: import("../schema.js").OptionalSchema; + /** Names for values: "set the fan speed to maximum". */ + presets: import("../schema.js").OptionalSchema; + friendlyNames: import("../schema.js").Schema; + }>[]>; + semantics: import("../schema.js").OptionalSchema; +}>, true>; diff --git a/dist/types/registry/interfaces/ToggleController.d.ts b/dist/types/registry/interfaces/ToggleController.d.ts new file mode 100644 index 0000000..7d610d4 --- /dev/null +++ b/dist/types/registry/interfaces/ToggleController.d.ts @@ -0,0 +1,21 @@ +/** + * Something that is on or off, under an instance name: the oscillation of a fan, the light of an oven. The one + * generic controller that Alexa hunches work with (SetEcoOn, SetEcoOff, EcoOn, EcoOff). + */ +export declare const ToggleController: import("../types.js").InterfaceDescriptor<{ + toggleState: { + name: string; + value: import("../schema.js").EnumSchema<"ON" | "OFF">; + }; +}, { + TurnOn: { + name: string; + payload: import("../schema.js").Schema>; + }; + TurnOff: { + name: string; + payload: import("../schema.js").Schema>; + }; +}, import("../schema.js").InferShape<{ + semantics: import("../schema.js").OptionalSchema; +}>, true>; diff --git a/dist/types/registry/semantics.d.ts b/dist/types/registry/semantics.d.ts new file mode 100644 index 0000000..da2f381 --- /dev/null +++ b/dist/types/registry/semantics.d.ts @@ -0,0 +1,47 @@ +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 `${Prefix}${infer Name}` ? Name : never; +/** A phrase by its id or by its name: "Alexa.Actions.Open" or "Open". */ +export type ActionName = ActionId | Short; +/** A state by its id or by its name: "Alexa.States.Closed" or "Closed". */ +export type StateName = StateId | Short; +/** + * 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; + /** 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): 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; + /** 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; +export {}; diff --git a/dist/types/registry/types.d.ts b/dist/types/registry/types.d.ts index c01b242..d6e882e 100644 --- a/dist/types/registry/types.d.ts +++ b/dist/types/registry/types.d.ts @@ -120,7 +120,11 @@ export interface InterfaceDescriptor

; /** What a declaration can set beyond the fields every capability has: a range, the supported modes. */ options?: Schema; - discovery?: (capability: Declared) => CapabilityExtras; + /** + * What the interface adds to the capability object. The options may be incomplete: a capability declared the + * 1.x way is announced with what it has, and check() of its device says what is missing. + */ + discovery?: (capability: Declared>) => CapabilityExtras; /** The event that answers a directive when it is not Alexa / Response (Arm -> Arm.Response). */ responseFor?: (directive: string) => { namespace: string; @@ -132,7 +136,7 @@ export interface InterfaceDescriptor

, endpoint: EndpointView) => void; } export type AnyDescriptor = InterfaceDescriptor; diff --git a/src/compat/AlexaInterface.ts b/src/compat/AlexaInterface.ts index 381c1ab..031b09c 100644 --- a/src/compat/AlexaInterface.ts +++ b/src/compat/AlexaInterface.ts @@ -2,7 +2,7 @@ import { Capability } from "../device/Capability.js"; import type { CapabilityJson } from "../device/Capability.js"; import { registry } from "../registry/index.js"; import { text } from "../registry/resources.js"; -import type { Semantics } from "../registry/types.js"; +import type { Label, Semantics } from "../registry/types.js"; import type { ActionMapping } from "./ActionMapping.js"; import type { AlexaInterfaceType } from "./enums.js"; @@ -14,7 +14,8 @@ export interface SupportedMode { interface Options { semantics?: Semantics; - supportedModes?: Array; + supportedModes?: Array<{ value: string; friendlyNames: Label[] }>; + ordered?: boolean; } /** @@ -43,9 +44,18 @@ export class AlexaInterface extends Capability { this.friendlyNames.push(text(name, locale)); } - /** The modes of a ModeController, as { value, modeResources } objects. */ - addSupportedModes(modes: Array): void { - this.options.supportedModes = modes; + /** + * The modes of a ModeController, as { value, modeResources } objects. A mode given as a string is announced as + * { value } and noted: Alexa wants friendly names for it. ordered is true unless options.ordered says otherwise, + * as 1.x announced every mode list; with device.add() the default is false. + */ + addSupportedModes(modes: Array, options: { ordered?: boolean } = {}): void { + this.options.ordered = options.ordered ?? true; + this.options.supportedModes = modes.map((mode) => { + if (typeof mode !== "string") return { value: mode.value, friendlyNames: (mode.modeResources?.friendlyNames ?? []) as Label[] }; + this.notes.push(`the mode ${mode} was given as a string, pass { value, modeResources }`); + return { value: mode, friendlyNames: [] }; + }); } setInstance(name: string): void { diff --git a/src/device/validate.ts b/src/device/validate.ts index 9771bd7..eedecf9 100644 --- a/src/device/validate.ts +++ b/src/device/validate.ts @@ -118,6 +118,15 @@ export function checkCapability(capability: Declared, descriptor: AnyDe if (friendlyNames.length > 0) refuse("takes no friendly names"); } + // A capability of device.add() passed the schema when it was declared; one declared the 1.x way did not + if (descriptor.options) { + try { + descriptor.options.parse(capability.options); + } catch (err) { + refuse(err instanceof SchemaError ? err.message : String(err)); + } + } + // generic-controllers.html, "Semantics for user utterances": "Each semantic phrase must be unique across all // controller instances for each endpoint" const used = new Map(); diff --git a/src/index.ts b/src/index.ts index 3e91dfc..f090e3e 100644 --- a/src/index.ts +++ b/src/index.ts @@ -8,9 +8,11 @@ export type { CapabilityJson, CommonOptions, Declaration } from "./device/Capabi // The interfaces, for device.add(), and the registry that holds them by name export { registry, DeclarationError, SchemaError } from "./registry/index.js"; -export { Alexa, BrightnessController, TemperatureSensor } from "./registry/index.js"; +export { + Alexa, BrightnessController, ModeController, RangeController, TemperatureSensor, ToggleController, +} from "./registry/index.js"; export { PowerController, EndpointHealth } from "./compat/enums.js"; -export { asset, text } from "./registry/resources.js"; +export { asset, text, semantics, SemanticsBuilder } from "./registry/index.js"; // The vocabularies of the Smart Home API export { @@ -21,7 +23,7 @@ export type { ActionId, AssetId, DisplayCategoryName, StateId, UnitOfMeasure, ActionsToDirective, AnyDescriptor, CapabilityExtras, Declared, DirectiveDescriptor, EndpointView, EventDescriptor, InterfaceDescriptor, Label, PropertyDescriptor, Semantics, StatesToRange, StatesToValue, - Infer, Schema, Temperature, TimeInterval, + ActionName, StateName, Mode, Infer, Schema, Temperature, TimeInterval, } from "./registry/index.js"; // 1.x diff --git a/src/registry/index.ts b/src/registry/index.ts index 3c1cac1..e7532e6 100644 --- a/src/registry/index.ts +++ b/src/registry/index.ts @@ -2,8 +2,11 @@ import { Alexa } from "./interfaces/Alexa.js"; import { BrightnessController } from "./interfaces/BrightnessController.js"; import { EndpointHealth } from "./interfaces/EndpointHealth.js"; +import { ModeController } from "./interfaces/ModeController.js"; import { PowerController } from "./interfaces/PowerController.js"; +import { RangeController } from "./interfaces/RangeController.js"; import { TemperatureSensor } from "./interfaces/TemperatureSensor.js"; +import { ToggleController } from "./interfaces/ToggleController.js"; import { STUBS } from "./interfaces/stubs.js"; import { DeclarationError } from "./types.js"; import type { AnyDescriptor } from "./types.js"; @@ -12,8 +15,11 @@ const described: readonly AnyDescriptor[] = [ Alexa, BrightnessController, EndpointHealth, + ModeController, PowerController, + RangeController, TemperatureSensor, + ToggleController, ]; const descriptors = new Map(); @@ -42,7 +48,14 @@ export const registry = { }, }; -export { Alexa, BrightnessController, EndpointHealth, PowerController, TemperatureSensor }; +export { + Alexa, BrightnessController, EndpointHealth, ModeController, PowerController, RangeController, TemperatureSensor, + ToggleController, +}; +export type { Mode } from "./interfaces/ModeController.js"; +export { asset, text } from "./resources.js"; +export { semantics, SemanticsBuilder } from "./semantics.js"; +export type { ActionName, StateName } from "./semantics.js"; export { DeclarationError, defineInterface } from "./types.js"; export type { ActionsToDirective, AnyDescriptor, CapabilityExtras, Declared, DirectiveDescriptor, EndpointView, EventDescriptor, diff --git a/src/registry/interfaces/ModeController.ts b/src/registry/interfaces/ModeController.ts new file mode 100644 index 0000000..a050928 --- /dev/null +++ b/src/registry/interfaces/ModeController.ts @@ -0,0 +1,95 @@ +import { labels } from "../resources.js"; +import { at, mismatch, s } from "../schema.js"; +import type { Schema } from "../schema.js"; +import { semanticsOf } from "../semantics.js"; +import { DeclarationError, defineInterface } from "../types.js"; +import type { Label } from "../types.js"; + +const directives = { + SetMode: { name: "SetMode", payload: s.object({ mode: s.string({ min: 1 }) }) }, + AdjustMode: { + name: "AdjustMode", + payload: s.object({ modeDelta: s.optional(s.number({ integer: true })) }), + // alexa-modecontroller.html, "Capabilities object": "Modes that have an order support the AdjustMode directive." + when: ({ options }: { options: { ordered?: boolean } }) => options.ordered === true, + note: "modeDelta is the number of modes to move by, 1 when it is left out", + }, +}; + +/** One mode: its value and what the user calls it. */ +export interface Mode { + value: string; + friendlyNames: Label[]; +} + +// A mode is declared as { value, friendlyNames }. The object of discovery and of 1.x, { value, modeResources: +// { friendlyNames } }, is taken as well. +const eitherForm = s.object({ + value: s.string({ min: 1 }), + friendlyNames: s.optional(s.unknown()), + modeResources: s.optional(s.object({ friendlyNames: s.unknown() })), +}, { unknownKeys: "reject" }); +const mode: Schema = { + expects: "a mode { value, friendlyNames }", + parse(input, path = "") { + if (typeof input !== "object" || input === null) throw mismatch(path, mode.expects, input); + const { value, friendlyNames, modeResources } = eitherForm.parse(input, path); + const named = friendlyNames === undefined && modeResources ? "modeResources.friendlyNames" : "friendlyNames"; + return { value, friendlyNames: labels.parse(friendlyNames ?? modeResources?.friendlyNames, at(path, named)) }; + }, +}; + +/** + * One of a list of values, under an instance name: the wash cycle of a washer, the position of a garage door. Amazon + * certifies a garage door only with this interface and the display category GARAGE_DOOR. + */ +export const ModeController = defineInterface({ + namespace: "Alexa.ModeController", + version: "3", + doc: "https://developer.amazon.com/docs/alexaplus/device-apis/alexa-modecontroller.html", + kind: "controller", + tier: 1, + instanced: true, + properties: { + mode: { name: "mode", value: s.nullable(s.string({ min: 1 })), note: "null when no mode is set, as when the device is off" }, + }, + directives, + options: s.object({ + /** At least two. When the modes have an order, in increasing order. */ + supportedModes: s.array(mode, { min: 2 }), + /** The modes have an order, cold to hot, and the user can say "increase": Alexa sends AdjustMode. Default: false. */ + ordered: s.optional(s.boolean()), + semantics: s.optional(semanticsOf({ directives, stateValue: s.string({ min: 1 }) })), + }, { unknownKeys: "reject" }), + // A capability declared the 1.x way may be without modes, or have modes without names + discovery({ options: { supportedModes = [], ordered = false } }) { + if (supportedModes.length === 0) return {}; + const modes = supportedModes.map(({ value, friendlyNames = [] }) => ( + friendlyNames.length > 0 ? { value, modeResources: { friendlyNames } } : { value } + )); + return { configuration: { ordered, supportedModes: modes } }; + }, + validate(capability) { + const { supportedModes, ordered = false, semantics } = capability.options; + const values = supportedModes.map(({ value }) => value); + const twice = values.find((value, i) => values.indexOf(value) !== i); + if (twice !== undefined) throw new DeclarationError(capability, `the mode ${twice} is listed twice`); + const isMode = (value: unknown): boolean => values.includes(value as string); + + for (const { directive } of semantics?.actionMappings ?? []) { + if (directive.name === "AdjustMode" && !ordered) { + throw new DeclarationError(capability, "an action is mapped to AdjustMode, which needs ordered: true"); + } + if (directive.name === "SetMode" && !isMode(directive.payload?.mode)) { + throw new DeclarationError(capability, `an action is mapped to SetMode ${directive.payload?.mode}, the modes are ${values.join(", ")}`); + } + } + for (const mapping of semantics?.stateMappings ?? []) { + if (mapping["@type"] === "StatesToValue" && !isMode(mapping.value)) { + throw new DeclarationError(capability, `a state is mapped to ${mapping.value}, the modes are ${values.join(", ")}`); + } + } + }, + errorNamespace: "Alexa.Safety", + errorTypes: ["OBSTACLE_DETECTED", "SAFETY_BEAM_BREACHED"], +}); diff --git a/src/registry/interfaces/RangeController.ts b/src/registry/interfaces/RangeController.ts new file mode 100644 index 0000000..53266ca --- /dev/null +++ b/src/registry/interfaces/RangeController.ts @@ -0,0 +1,75 @@ +import { UNITS_OF_MEASURE } from "../catalog.js"; +import { labels } from "../resources.js"; +import { s } from "../schema.js"; +import { semanticsOf } from "../semantics.js"; +import { DeclarationError, defineInterface } from "../types.js"; + +const directives = { + SetRangeValue: { name: "SetRangeValue", payload: s.object({ rangeValue: s.number() }) }, + AdjustRangeValue: { + name: "AdjustRangeValue", + payload: s.object({ rangeValueDelta: s.number(), rangeValueDeltaDefault: s.boolean() }), + note: "rangeValueDeltaDefault is true when the user named no amount; rangeValueDelta is then the precision", + }, +}; + +// 0.1 + 0.2 is not 0.3: a value is on the grid when it is within a millionth of a step of it +function onGrid(value: number, origin: number, step: number): boolean { + const steps = (value - origin) / step; + return Math.abs(steps - Math.round(steps)) < 1e-6; +} + +/** + * A number in a range, under an instance name: the position of a blind, the speed of a fan. With nonControllable it + * is a reading the user can ask for, like an air quality index. + */ +export const RangeController = defineInterface({ + namespace: "Alexa.RangeController", + version: "3", + doc: "https://developer.amazon.com/docs/alexaplus/device-apis/alexa-rangecontroller.html", + kind: "controller", + tier: 1, + instanced: true, + properties: { + rangeValue: { name: "rangeValue", value: s.number() }, + }, + directives, + options: s.object({ + /** precision is the step of the range and what "turn up the fan speed" changes it by. */ + range: s.object({ min: s.number(), max: s.number(), precision: s.number({ gt: 0 }) }, { unknownKeys: "reject" }), + unit: s.optional(s.oneOf(UNITS_OF_MEASURE, "a unit of measure like Alexa.Unit.Percent")), + /** Names for values: "set the fan speed to maximum". */ + presets: s.optional(s.array(s.object({ value: s.number(), friendlyNames: labels }, { unknownKeys: "reject" }))), + semantics: s.optional(semanticsOf({ directives, stateValue: s.number(), ranges: true })), + }, { unknownKeys: "reject" }), + // A capability declared the 1.x way may be without a range; check() says so, discovery lists what there is + discovery({ options: { range, unit, presets } }) { + const configuration = { + ...(range && { supportedRange: { minimumValue: range.min, maximumValue: range.max, precision: range.precision } }), + ...(unit && { unitOfMeasure: unit }), + ...(presets && { presets: presets.map(({ value, friendlyNames }) => ({ rangeValue: value, presetResources: { friendlyNames } })) }), + }; + return Object.keys(configuration).length > 0 ? { configuration } : {}; + }, + validate(capability) { + const { range: { min, max, precision }, presets = [], semantics } = capability.options; + const inRange = (value: number): boolean => value >= min && value <= max; + if (max <= min) throw new DeclarationError(capability, `range.max ${max} is not above range.min ${min}`); + for (const { value } of presets) { + // alexa-rangecontroller.html, "Preset object": "minimum range value + (n x precision) where n is an integer" + if (!inRange(value) || !onGrid(value, min, precision)) { + throw new DeclarationError(capability, `the preset ${value} is not ${min} + n x ${precision}, up to ${max}`); + } + } + for (const { directive } of semantics?.actionMappings ?? []) { + const { rangeValue } = directive.payload ?? {}; + if (directive.name === "SetRangeValue" && !inRange(rangeValue as number)) { + throw new DeclarationError(capability, `an action is mapped to SetRangeValue ${rangeValue}, the range is ${min} to ${max}`); + } + } + }, + // alexa-rangecontroller.html, "SetRangeValue directive error handling": "If your error is safety related, respond + // with an Alexa.Safety.ErrorResponse" + errorNamespace: "Alexa.Safety", + errorTypes: ["OBSTACLE_DETECTED", "SAFETY_BEAM_BREACHED"], +}); diff --git a/src/registry/interfaces/ToggleController.ts b/src/registry/interfaces/ToggleController.ts new file mode 100644 index 0000000..01bc0b1 --- /dev/null +++ b/src/registry/interfaces/ToggleController.ts @@ -0,0 +1,30 @@ +import { s } from "../schema.js"; +import { semanticsOf } from "../semantics.js"; +import { defineInterface } from "../types.js"; + +const directives = { + TurnOn: { name: "TurnOn", payload: s.object({}) }, + TurnOff: { name: "TurnOff", payload: s.object({}) }, +}; + +/** + * Something that is on or off, under an instance name: the oscillation of a fan, the light of an oven. The one + * generic controller that Alexa hunches work with (SetEcoOn, SetEcoOff, EcoOn, EcoOff). + */ +export const ToggleController = defineInterface({ + namespace: "Alexa.ToggleController", + version: "3", + doc: "https://developer.amazon.com/docs/alexaplus/device-apis/alexa-togglecontroller.html", + kind: "controller", + tier: 1, + instanced: true, + properties: { + toggleState: { name: "toggleState", value: s.enum("ON", "OFF") }, + }, + directives, + options: s.object({ + semantics: s.optional(semanticsOf({ directives, stateValue: s.enum("ON", "OFF"), hunches: true })), + }, { unknownKeys: "reject" }), + errorNamespace: "Alexa.Safety", + errorTypes: ["OBSTACLE_DETECTED", "SAFETY_BEAM_BREACHED"], +}); diff --git a/src/registry/interfaces/stubs.ts b/src/registry/interfaces/stubs.ts index 1c45487..09266fa 100644 --- a/src/registry/interfaces/stubs.ts +++ b/src/registry/interfaces/stubs.ts @@ -51,7 +51,6 @@ const TABLE: readonly Row[] = [ ["Alexa.Media.PlayQueue", "1", [], "alexa-media-playqueue.html"], ["Alexa.Media.Playback", "1", [], "alexa-media-playback.html"], ["Alexa.Media.Search", "1", [], "alexa-media-search.html"], - ["Alexa.ModeController", "3", ["mode"], "alexa-modecontroller.html"], ["Alexa.MotionSensor", "3", [], "alexa-motionsensor.html"], ["Alexa.PercentageController", "3", [], "alexa-percentagecontroller.html"], ["Alexa.PlaybackController", "3", [], "alexa-playbackcontroller.html"], @@ -59,7 +58,6 @@ const TABLE: readonly Row[] = [ ["Alexa.PowerLevelController", "3", [], "alexa-powerlevelcontroller.html"], ["Alexa.ProactiveNotificationSource", "1", [], "alexa-proactivenotificationsource.html"], ["Alexa.RTCSessionController", "1", [], "alexa-rtcsessioncontroller.html"], - ["Alexa.RangeController", "3", [], "alexa-rangecontroller.html"], ["Alexa.RecordController", "3", [], "alexa-recordcontroller.html"], ["Alexa.RemoteVideoPlayer", "1", [], "alexa-remotevideoplayer.html"], ["Alexa.SceneController", "3", [], "alexa-scenecontroller.html"], @@ -77,14 +75,13 @@ const TABLE: readonly Row[] = [ ["Alexa.ThermostatController.Schedule", "1", [], "alexa-thermostatcontroller-schedule.html"], // "UNKNOWN" in 1.5.2 as well; the page is titled "Interface 3" ["Alexa.TimeHoldController", "3", [], "alexa-timeholdcontroller.html"], - ["Alexa.ToggleController", "3", ["toggleState"], "alexa-togglecontroller.html"], ["Alexa.UIController", "1", [], "alexa-uicontroller.html"], ["Alexa.UserPreference", "1", [], "alexa-userpreference.html"], ["Alexa.VideoRecorder", "1", [], "alexa-videorecorder.html"], ["Alexa.WakeOnLANController", "1", [], "alexa-wakeonlancontroller.html"], ]; -// What 1.5.2 added to the capability object of three of them +// What 1.5.2 added to the capability object of two of them const EXTRAS: Record = { // No properties object; supportsDeactivation and proactivelyReported on the capability itself "Alexa.SceneController": ({ proactivelyReported }) => ({ @@ -94,9 +91,6 @@ const EXTRAS: Record = { "Alexa.ThermostatController": () => ({ configuration: { supportedModes: ["HEAT", "COOL", "AUTO", "OFF"], supportsScheduling: false }, }), - "Alexa.ModeController": ({ options }) => (options.supportedModes?.length > 0 - ? { configuration: { ordered: true, supportedModes: options.supportedModes } } - : {}), }; function kindOf(namespace: string): AnyDescriptor["kind"] { diff --git a/src/registry/resources.ts b/src/registry/resources.ts index 2e61875..6d578a4 100644 --- a/src/registry/resources.ts +++ b/src/registry/resources.ts @@ -1,7 +1,7 @@ // 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 type { AssetId } from "./catalog.js"; -import { at, s, SchemaError } from "./schema.js"; +import { at, mismatch, s, SchemaError } from "./schema.js"; import type { Schema } from "./schema.js"; import type { Label } from "./types.js"; @@ -28,6 +28,7 @@ const reserved: readonly string[] = RESERVED_WORDS; export const label: Schema