David
c492ef74d1
A capability is a descriptor plus what the endpoint declares (device/Capability.ts), and its discovery object is
generated from the two. The new API is bridge.addDevice({ endpointId, name, categories, ... }) and
device.add(PowerController, options): both throw a DeclarationError that names the endpoint, the interface and
the instance (device/validate.ts), and leave the bridge and the device as they were. AlexaInterface is the same
Capability with the 1.x methods on it; it, ActionMapping and the enums moved to src/compat/, Device to src/device/.
What a 1.x caller can observe:
- every endpoint ends with { type: "AlexaInterface", interface: "Alexa", version: "3" } (alexa-interface.html);
new Alex2MQTT(..., { alexaInterface: false }) leaves it out
- the fields of a capability object come in the order of Amazon's examples; their content is unchanged
- addCapability() with a name that is not an interface throws (1.5.2 announced it with the version "UNKNOWN")
- ActionMapping takes the payload as an object; a JSON string is parsed (1.5.2 sent the string), any other throws
- what Alexa would reject in a 1.x declaration is not refused: device.check() lists it and the bridge logs each
line once, as "warning: ..." through the log hook, when it answers a discovery
- a device whose JSON cannot be built is left out of the answer and reported as an error event
- PowerController and EndpointHealth are the descriptors and keep ON/OFF and OK/UNREACHABLE; PowerState is new
Tests: six zoo devices declared the 1.x way give the JSON that Alexa accepted from 1.5.2 on 2026-09-28, plus the
Alexa capability. npm test: 85 pass (was 57) in 10-12 s, also on Node 18.20.8 and 20.20.2.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
98 lines
3.7 KiB
TypeScript
98 lines
3.7 KiB
TypeScript
/** A value that does not fit its schema: path is where ("payload.targetSetpoint.scale"), problem is what. */
|
|
export declare class SchemaError extends Error {
|
|
readonly path: string;
|
|
readonly problem: string;
|
|
constructor(path: string, problem: string);
|
|
}
|
|
export interface Schema<T> {
|
|
/** What the schema accepts, in the words of an error message: "an integer from 0 to 100", "ON | OFF". */
|
|
readonly expects: string;
|
|
/** The checked value. path names it in the error message. */
|
|
parse(input: unknown, path?: string): T;
|
|
}
|
|
/** A schema that accepts a missing value; s.object() makes its key optional in the inferred type. */
|
|
export interface OptionalSchema<T> extends Schema<T | undefined> {
|
|
readonly optional: true;
|
|
}
|
|
export interface EnumSchema<V> extends Schema<V> {
|
|
readonly values: readonly V[];
|
|
}
|
|
/** The type a schema produces. */
|
|
export type Infer<S> = S extends Schema<infer T> ? T : never;
|
|
export type Shape = Record<string, Schema<any>>;
|
|
type OptionalKeys<S extends Shape> = {
|
|
[K in keyof S]: S[K] extends OptionalSchema<any> ? K : never;
|
|
}[keyof S];
|
|
export type InferShape<S extends Shape> = {
|
|
[K in Exclude<keyof S, OptionalKeys<S>>]: Infer<S[K]>;
|
|
} & {
|
|
[K in OptionalKeys<S>]?: Infer<S[K]>;
|
|
};
|
|
export interface NumberRules {
|
|
min?: number;
|
|
max?: number;
|
|
/** Greater than, the bound itself excluded. */
|
|
gt?: number;
|
|
integer?: boolean;
|
|
}
|
|
export interface Temperature {
|
|
value: number;
|
|
scale: "CELSIUS" | "FAHRENHEIT" | "KELVIN";
|
|
}
|
|
export interface TimeInterval {
|
|
start?: string;
|
|
end?: string;
|
|
duration?: string;
|
|
}
|
|
/** The error of a value that is not what a schema expects. */
|
|
export declare function mismatch(path: string, expects: string, input: unknown): SchemaError;
|
|
/** The path of a key of the object at path. */
|
|
export declare const at: (path: string, key: string) => string;
|
|
declare function number(rules?: NumberRules): Schema<number>;
|
|
declare function string(rules?: {
|
|
min?: number;
|
|
max?: number;
|
|
pattern?: RegExp;
|
|
expects?: string;
|
|
}): Schema<string>;
|
|
declare function boolean(): Schema<boolean>;
|
|
declare function literal<V extends string | number | boolean | null>(value: V): Schema<V>;
|
|
declare function enumeration<V extends readonly string[]>(...values: V): EnumSchema<V[number]>;
|
|
/** One of a list too long to print in an error message: expects says what the list is. */
|
|
declare function oneOf<V extends string>(values: readonly V[], expects: string): EnumSchema<V>;
|
|
declare function unknown(): Schema<unknown>;
|
|
declare function optional<T>(inner: Schema<T>): OptionalSchema<T>;
|
|
declare function nullable<T>(inner: Schema<T>): Schema<T | null>;
|
|
declare function array<T>(item: Schema<T>, rules?: {
|
|
min?: number;
|
|
max?: number;
|
|
}): Schema<T[]>;
|
|
/**
|
|
* An object with the keys of shape. Keys the shape does not name are kept as they are: a field Alexa adds to a
|
|
* directive reaches the handler. unknownKeys "reject" is for what a developer writes, where such a key is a typo.
|
|
*/
|
|
declare function object<S extends Shape>(shape: S, rules?: {
|
|
unknownKeys?: "keep" | "reject";
|
|
}): Schema<InferShape<S>>;
|
|
declare function temperature(): Schema<Temperature>;
|
|
declare function dateTime(): Schema<string>;
|
|
declare function duration(): Schema<string>;
|
|
declare function timeInterval(): Schema<TimeInterval>;
|
|
export declare const s: {
|
|
string: typeof string;
|
|
number: typeof number;
|
|
boolean: typeof boolean;
|
|
literal: typeof literal;
|
|
enum: typeof enumeration;
|
|
oneOf: typeof oneOf;
|
|
unknown: typeof unknown;
|
|
optional: typeof optional;
|
|
nullable: typeof nullable;
|
|
array: typeof array;
|
|
object: typeof object;
|
|
temperature: typeof temperature;
|
|
dateTime: typeof dateTime;
|
|
duration: typeof duration;
|
|
timeInterval: typeof timeInterval;
|
|
};
|
|
export {};
|