registry: SecurityPanelController with Arm.Response and its errors

Alexa.SecurityPanelController is described from its page: version 3 (the stub of 1.5.2 said 1), armState and the
four alarms, Arm and Disarm. ctx.respond() answers Arm with Arm.Response under the namespace of the interface,
its payload checked (exitDelayInSeconds 0 to 255, bypassedEndpoints), and Disarm with a Response. A Disarm
carries the PIN the user said when the panel is declared with supportedAuthorizationTypes; the handler checks
it and answers UNAUTHORIZED, which goes under Alexa.SecurityPanelController like the five other error types.

A panel declared without options lists armState, where 1.5.2 listed no property; alarms are declared.
17 examples of the two pages are saved as fixtures. 215 tests pass, 207 before.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

src/index.ts

@@ -10,8 +10,8 @@ export type { CapabilityJson, CommonOptions, Declaration } from "./device/Capabi
 export { registry, DeclarationError, SchemaError } from "./registry/index.js";
 export {
   Alexa, BrightnessController, ColorController, ColorTemperatureController, ContactSensor, HumiditySensor, LockController,
-  ModeController, MotionSensor, PercentageController, PowerLevelController, RangeController, TemperatureSensor,
-  ThermostatController, ThermostatControllerSchedule, ToggleController,
+  ModeController, MotionSensor, PercentageController, PowerLevelController, RangeController, SecurityPanelController,
+  TemperatureSensor, ThermostatController, ThermostatControllerSchedule, ToggleController,
 } from "./registry/index.js";
 export { PowerController, EndpointHealth } from "./compat/enums.js";
 export { asset, text, semantics, SemanticsBuilder } from "./registry/index.js";

src/registry/index.ts

@@ -13,6 +13,7 @@ import { PercentageController } from "./interfaces/PercentageController.js";
 import { PowerController } from "./interfaces/PowerController.js";
 import { PowerLevelController } from "./interfaces/PowerLevelController.js";
 import { RangeController } from "./interfaces/RangeController.js";
+import { SecurityPanelController } from "./interfaces/SecurityPanelController.js";
 import { TemperatureSensor } from "./interfaces/TemperatureSensor.js";
 import { ThermostatController } from "./interfaces/ThermostatController.js";
 import { ThermostatControllerSchedule } from "./interfaces/ThermostatControllerSchedule.js";
@@ -36,6 +37,7 @@ const described: readonly AnyDescriptor[] = [
   PowerController,
   PowerLevelController,
   RangeController,
+  SecurityPanelController,
   TemperatureSensor,
   ThermostatController,
   ThermostatControllerSchedule,
@@ -71,7 +73,7 @@ export const registry = {
 export {
   Alexa, BrightnessController, ColorController, ColorTemperatureController, ContactSensor, EndpointHealth, HumiditySensor,
   LockController, ModeController, MotionSensor, PercentageController, PowerController, PowerLevelController, RangeController,
-  TemperatureSensor, ThermostatController, ThermostatControllerSchedule, ToggleController,
+  SecurityPanelController, TemperatureSensor, ThermostatController, ThermostatControllerSchedule, ToggleController,
 };
 export type { Mode } from "./interfaces/ModeController.js";
 export { THERMOSTAT_MODES } from "./interfaces/ThermostatController.js";

src/registry/interfaces/SecurityPanelController.ts

@@ -0,0 +1,91 @@
+import { s } from "../schema.js";
+import { DeclarationError, defineInterface } from "../types.js";
+
+const ARM_STATES = ["ARMED_AWAY", "ARMED_STAY", "ARMED_NIGHT", "DISARMED"] as const;
+const ALARMS = ["burglaryAlarm", "fireAlarm", "carbonMonoxideAlarm", "waterAlarm"] as const;
+
+const alarm = s.object({ value: s.enum("OK", "ALARM") });
+// A sensor that is left out when the panel arms. The endpointId is for a sensor that is an endpoint of its own.
+const bypassed = s.object({ friendlyName: s.optional(s.string({ min: 1 })), endpointId: s.optional(s.string({ min: 1 })) });
+
+const armResponse = s.object({
+  /** How long the occupants have to leave before the panel arms. 0: it arms at once. */
+  exitDelayInSeconds: s.optional(s.number({ min: 0, max: 255, integer: true })),
+  /** For an Arm that came with bypassType only. */
+  bypassedEndpoints: s.optional(s.array(bypassed)),
+});
+
+/**
+ * A security panel. Arm is answered with Arm.Response, Disarm with a Response, an error of errorTypes under the
+ * namespace of the interface (alexa-securitypanelcontroller-errorresponse.html).
+ *
+ * Alexa sends Disarm only when the user switched on disarming by voice in the Alexa app. A panel declared with
+ * supportedAuthorizationTypes gets the PIN the user said in payload.authorization and has to check it: a wrong PIN
+ * is answered with UNAUTHORIZED. Without authorization in the payload Alexa checked a voice code of its own.
+ *
+ * A panel that is ARMED_AWAY is disarmed before it is armed another way: Arm to ARMED_STAY or ARMED_NIGHT is
+ * then answered with AUTHORIZATION_REQUIRED. Arm to the state the panel is in is answered with Arm.Response.
+ */
+export const SecurityPanelController = defineInterface({
+  namespace: "Alexa.SecurityPanelController",
+  version: "3",
+  doc: "https://developer.amazon.com/docs/alexaplus/device-apis/alexa-securitypanelcontroller.html",
+  kind: "controller",
+  tier: 2,
+  instanced: false,
+  properties: {
+    armState: { name: "armState", value: s.enum(...ARM_STATES) },
+    burglaryAlarm: { name: "burglaryAlarm", value: alarm },
+    fireAlarm: { name: "fireAlarm", value: alarm },
+    carbonMonoxideAlarm: { name: "carbonMonoxideAlarm", value: alarm },
+    waterAlarm: { name: "waterAlarm", value: alarm },
+  },
+  directives: {
+    Arm: {
+      name: "Arm",
+      payload: s.object({ armState: s.enum(...ARM_STATES), bypassType: s.optional(s.enum("BYPASS_ALL")) }),
+      note: "bypassType: the user said to arm with the open sensors left out, which BYPASS_NEEDED listed",
+    },
+    Disarm: {
+      name: "Disarm",
+      payload: s.object({
+        authorization: s.optional(s.object({
+          type: s.enum("FOUR_DIGIT_PIN"),
+          value: s.string({ pattern: /^\d{4}$/, expects: "a PIN of four digits" }),
+        })),
+      }),
+      note: "authorization: the PIN the user said, for the panel to check",
+    },
+  },
+  options: s.object({
+    /** Default: Alexa takes the panel to have all four. */
+    supportedArmStates: s.optional(s.array(s.enum(...ARM_STATES), { min: 1 })),
+    /** For a panel that has four digit PINs and checks the PIN of a Disarm itself. */
+    supportedAuthorizationTypes: s.optional(s.array(s.enum("FOUR_DIGIT_PIN"), { min: 1 })),
+    /** The alarms the panel reports. Default: none. */
+    alarms: s.optional(s.array(s.enum(...ALARMS))),
+  }, { unknownKeys: "reject" }),
+  discovery({ options: { supportedArmStates, supportedAuthorizationTypes, alarms = [] } }) {
+    const configuration = {
+      ...(supportedArmStates && { supportedArmStates: supportedArmStates.map((value) => ({ value })) }),
+      ...(supportedAuthorizationTypes && { supportedAuthorizationTypes: supportedAuthorizationTypes.map((type) => ({ type })) }),
+    };
+    return {
+      supported: ["armState", ...alarms],
+      ...(Object.keys(configuration).length > 0 && { configuration }),
+    };
+  },
+  validate(capability) {
+    const { supportedArmStates = [], supportedAuthorizationTypes = [], alarms = [] } = capability.options;
+    const lists: ReadonlyArray<readonly string[]> = [supportedArmStates, supportedAuthorizationTypes, alarms];
+    for (const list of lists) {
+      const twice = list.find((entry, i) => list.indexOf(entry) !== i);
+      if (twice) throw new DeclarationError(capability, `${twice} is listed twice`);
+    }
+  },
+  responseFor: (directive) => (directive === "Arm"
+    ? { namespace: "Alexa.SecurityPanelController", name: "Arm.Response", payload: armResponse }
+    : undefined),
+  errorNamespace: "Alexa.SecurityPanelController",
+  errorTypes: ["AUTHORIZATION_REQUIRED", "BYPASS_NEEDED", "NOT_READY", "UNAUTHORIZED", "UNCLEARED_ALARM", "UNCLEARED_TROUBLE"],
+});

src/registry/interfaces/stubs.ts

@@ -54,7 +54,6 @@ const TABLE: readonly Row[] = [
   ["Alexa.RecordController", "3", [], "alexa-recordcontroller.html"],
   ["Alexa.RemoteVideoPlayer", "1", [], "alexa-remotevideoplayer.html"],
   ["Alexa.SceneController", "3", [], "alexa-scenecontroller.html"],
-  ["Alexa.SecurityPanelController", "1", [], "alexa-securitypanelcontroller.html"],
   ["Alexa.SecurityPanelController.Alert", "1", [], "alexa-securitypanelcontroller-alert.html"],
   ["Alexa.SeekController", "3", [], "alexa-seekcontroller.html"],
   ["Alexa.SimpleEventSource", "1", [], "alexa-simpleeventsource.html"],