Alex2Node/src/registry/interfaces/ModeController.ts

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<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: 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"],
});