@matter/protocol 0.11.0-alpha.0-20241005-e3e4e4a7a

package/src/cluster/client/ClusterClient.ts

@@ -0,0 +1,354 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { capitalize, Diagnostic, Logger, Merge } from "#general";
+import {
+    Attribute,
+    AttributeId,
+    ClusterId,
+    ClusterType,
+    Command,
+    CommandId,
+    EndpointNumber,
+    Event,
+    EventId,
+    GlobalAttributes,
+    StatusCode,
+    StatusResponseError,
+    TlvEventFilter,
+    TypeFromPartialBitSchema,
+    TypeFromSchema,
+    UnknownAttribute,
+    UnknownEvent,
+} from "#types";
+import { DecodedEventData } from "../../interaction/EventDataDecoder.js";
+import { InteractionClient } from "../../interaction/InteractionClient.js";
+import { createAttributeClient } from "./AttributeClient.js";
+import {
+    AttributeClients,
+    AttributeClientValues,
+    ClusterClientObj,
+    EventClients,
+    SignatureFromCommandSpec,
+} from "./ClusterClientTypes.js";
+import { createEventClient } from "./EventClient.js";
+
+const logger = Logger.get("ClusterClient");
+
+export function ClusterClient<const T extends ClusterType>(
+    clusterDef: T,
+    endpointId: EndpointNumber,
+    interactionClient: InteractionClient,
+    globalAttributeValues: Partial<AttributeClientValues<GlobalAttributes<T["features"]>>> = {},
+): ClusterClientObj<T> {
+    function addAttributeToResult(attribute: Attribute<any, any>, attributeName: string) {
+        (attributes as any)[attributeName] = createAttributeClient(
+            attribute,
+            attributeName,
+            endpointId,
+            clusterId,
+            interactionClient,
+            !!globalAttributeValues?.attributeList?.includes(attribute.id),
+        );
+        attributeToId[attribute.id] = attributeName;
+        const capitalizedAttributeName = capitalize(attributeName);
+        result[`get${capitalizedAttributeName}Attribute`] = async (
+            alwaysRequestFromRemote?: boolean,
+            isFabricFiltered = true,
+        ) => {
+            try {
+                return await (attributes as any)[attributeName].get(alwaysRequestFromRemote, isFabricFiltered);
+            } catch (e) {
+                if (StatusResponseError.is(e, StatusCode.UnsupportedAttribute)) {
+                    return undefined;
+                }
+                throw e;
+            }
+        };
+        result[`set${capitalizedAttributeName}Attribute`] = async <T>(value: T, dataVersion?: number) =>
+            (attributes as any)[attributeName].set(value, dataVersion);
+        result[`subscribe${capitalizedAttributeName}Attribute`] = async <T>(
+            listener: (value: T) => void,
+            minIntervalS: number,
+            maxIntervalS: number,
+            knownDataVersion?: number,
+            isFabricFiltered?: boolean,
+        ) => {
+            (attributes as any)[attributeName].addListener(listener);
+            return (attributes as any)[attributeName].subscribe(
+                minIntervalS,
+                maxIntervalS,
+                knownDataVersion,
+                isFabricFiltered,
+            );
+        };
+        result[`add${capitalizedAttributeName}AttributeListener`] = <T>(listener: (value: T) => void) => {
+            (attributes as any)[attributeName].addListener(listener);
+        };
+    }
+
+    function addEventToResult(event: Event<any, any>, eventName: string) {
+        (events as any)[eventName] = createEventClient(
+            event,
+            eventName,
+            endpointId,
+            clusterId,
+            interactionClient,
+            !!globalAttributeValues?.eventList?.includes(event.id),
+        );
+        eventToId[event.id] = eventName;
+        const capitalizedEventName = capitalize(eventName);
+        result[`get${capitalizedEventName}Event`] = async (
+            minimumEventNumber?: number | bigint,
+            isFabricFiltered?: boolean,
+        ) => {
+            try {
+                return await (events as any)[eventName].get(minimumEventNumber, isFabricFiltered);
+            } catch (e) {
+                if (StatusResponseError.is(e, StatusCode.UnsupportedEvent)) {
+                    return undefined;
+                }
+                throw e;
+            }
+        };
+        result[`subscribe${capitalizedEventName}Event`] = async <T>(
+            listener: (value: DecodedEventData<T>) => void,
+            minIntervalS: number,
+            maxIntervalS: number,
+            isUrgent?: boolean,
+            minimumEventNumber?: number | bigint,
+            isFabricFiltered?: boolean,
+        ) => {
+            (events as any)[eventName].addListener(listener);
+            return (events as any)[eventName].subscribe(
+                minIntervalS,
+                maxIntervalS,
+                isUrgent,
+                minimumEventNumber,
+                isFabricFiltered,
+            );
+        };
+        result[`add${capitalizedEventName}EventListener`] = <T>(listener: (value: DecodedEventData<T>) => void) => {
+            (events as any)[eventName].addListener(listener);
+        };
+    }
+
+    const {
+        id: clusterId,
+        name,
+        commands: commandDef,
+        attributes: attributeDef,
+        events: eventDef,
+        features,
+        supportedFeatures,
+        revision,
+        unknown,
+    } = clusterDef;
+    const attributes = <AttributeClients<T["features"], T["attributes"]>>{};
+    const events = <EventClients<T["events"]>>{};
+    const commands = <{ [P in keyof T["commands"]]: SignatureFromCommandSpec<T["commands"][P]> }>{};
+
+    let reportedFeatures: TypeFromPartialBitSchema<T["features"]> | undefined = undefined;
+    // If we have global attribute values we use them to modify
+    if (globalAttributeValues !== undefined) {
+        if (globalAttributeValues.featureMap !== undefined) {
+            reportedFeatures = globalAttributeValues.featureMap;
+        }
+    }
+
+    const result: any = {
+        id: clusterId,
+        name,
+        revision: globalAttributeValues?.clusterRevision ?? revision,
+        _type: "ClusterClient",
+        supportedFeatures: reportedFeatures ?? supportedFeatures ?? {},
+        isUnknown: unknown,
+        endpointId,
+        attributes,
+        events,
+        commands,
+        subscribeAllAttributes: async (options: {
+            minIntervalFloorSeconds: number;
+            maxIntervalCeilingSeconds: number;
+            keepSubscriptions?: boolean;
+            isFabricFiltered?: boolean;
+            eventFilters?: TypeFromSchema<typeof TlvEventFilter>[];
+            dataVersionFilters?: { endpointId: EndpointNumber; clusterId: ClusterId; dataVersion: number }[];
+        }) => {
+            const {
+                minIntervalFloorSeconds,
+                maxIntervalCeilingSeconds,
+                keepSubscriptions,
+                isFabricFiltered,
+                eventFilters,
+                dataVersionFilters,
+            } = options;
+
+            return interactionClient.subscribeMultipleAttributesAndEvents({
+                attributes: [{ endpointId: endpointId, clusterId: clusterId }],
+                events: [{ endpointId: endpointId, clusterId: clusterId }],
+                minIntervalFloorSeconds,
+                maxIntervalCeilingSeconds,
+                keepSubscriptions,
+                isFabricFiltered,
+                eventFilters,
+                dataVersionFilters,
+                attributeListener: attributeData => {
+                    const { path, value } = attributeData;
+                    result._triggerAttributeUpdate(path.attributeId, value);
+                },
+                eventListener: eventData => {
+                    const { path, events: newEvents } = eventData;
+                    result._triggerEventUpdate(path.eventId, newEvents);
+                },
+            });
+        },
+
+        /** Trigger a value change for an Attributed, used by subscriptions. */
+        _triggerAttributeUpdate(attributeId: AttributeId, value: any) {
+            const attributeName = attributeToId[attributeId];
+            if (attributeName === undefined) {
+                logger.warn("Unknown attribute id", attributeId);
+                return;
+            }
+            if ((attributes as any)[attributeName] !== undefined) {
+                (attributes as any)[attributeName].update(value);
+            } else {
+                logger.warn("Attribute not found", attributeName, "in list", Object.keys(attributes));
+            }
+        },
+
+        /** Trigger a value change for an Event, used by subscriptions. */
+        _triggerEventUpdate(eventId: EventId, eventData: DecodedEventData<any>[]) {
+            const eventName = eventToId[eventId];
+            if (eventName === undefined) {
+                logger.warn("Unknown event id", eventId);
+                return;
+            }
+            if ((events as any)[eventName] !== undefined) {
+                const event = (events as any)[eventName];
+                eventData.forEach(data => event.update(data));
+            } else {
+                logger.warn("Event not found", eventName, "in list", Object.keys(events));
+            }
+        },
+
+        isAttributeSupported: (attributeId: AttributeId) => {
+            return !!globalAttributeValues?.attributeList?.includes(attributeId);
+        },
+
+        isAttributeSupportedByName: (attributeName: string) => {
+            const attribute = (attributes as any)[attributeName];
+            if (attribute === undefined) {
+                return false;
+            }
+            return !!globalAttributeValues?.attributeList?.includes(attribute.id);
+        },
+
+        isEventSupported: (eventId: EventId) => {
+            return !!globalAttributeValues?.eventList?.includes(eventId);
+        },
+
+        isEventSupportedByName: (eventName: string) => {
+            const event = (events as any)[eventName];
+            if (event === undefined) {
+                return false;
+            }
+            return !!globalAttributeValues?.eventList?.includes(event.id);
+        },
+
+        isCommandSupported: (commandId: CommandId) => {
+            return !!globalAttributeValues?.acceptedCommandList?.includes(commandId);
+        },
+
+        isCommandSupportedByName: (commandName: string) => {
+            const command = commandDef[commandName];
+            if (command === undefined) {
+                return false;
+            }
+            return !!globalAttributeValues?.acceptedCommandList?.includes(command.requestId);
+        },
+    };
+
+    const attributeToId = <{ [key: AttributeId]: string }>{};
+
+    const allAttributeDefs = Merge<T["attributes"], GlobalAttributes<T["features"]>>(
+        attributeDef,
+        GlobalAttributes(features),
+    );
+
+    // Add accessors from definition
+    for (const attributeName in allAttributeDefs) {
+        addAttributeToResult(allAttributeDefs[attributeName], attributeName);
+    }
+    if (globalAttributeValues?.attributeList !== undefined) {
+        // Add accessors for potential unknown data
+        for (const attributeId of globalAttributeValues.attributeList) {
+            if (attributeToId[attributeId] === undefined) {
+                const attribute = UnknownAttribute(attributeId);
+                addAttributeToResult(attribute, `unknownAttribute_${Diagnostic.hex(attributeId)}`);
+                logger.info(
+                    `Added unknown attribute ${Diagnostic.hex(attributeId)} to cluster ${Diagnostic.hex(clusterId)}`,
+                );
+            }
+        }
+    }
+
+    const eventToId = <{ [key: EventId]: string }>{};
+
+    // add events
+    for (const eventName in eventDef) {
+        addEventToResult(eventDef[eventName], eventName);
+    }
+    if (globalAttributeValues?.eventList !== undefined) {
+        // Add accessors for potential unknown data
+        for (const eventId of globalAttributeValues.eventList) {
+            if (eventToId[eventId] === undefined) {
+                const event = UnknownEvent(eventId);
+                addEventToResult(event, `unknownEvent_${Diagnostic.hex(eventId)}`);
+                logger.info(`Added unknown event ${Diagnostic.hex(eventId)} to cluster ${Diagnostic.hex(clusterId)}.`);
+            }
+        }
+    }
+
+    const commandToId = <{ [key: CommandId]: string }>{};
+
+    // Add command calls
+    for (const commandName in commandDef) {
+        const { requestId } = commandDef[commandName];
+
+        commandToId[requestId] = commandName;
+        commands[commandName as keyof T["commands"]] = async <RequestT, ResponseT>(
+            request: RequestT,
+            options: {
+                asTimedRequest?: boolean;
+                timedRequestTimeoutMs?: number;
+                useExtendedFailSafeMessageResponseTimeout?: boolean;
+            } = {},
+        ) => {
+            const { asTimedRequest, timedRequestTimeoutMs, useExtendedFailSafeMessageResponseTimeout } = options;
+            return interactionClient.invoke<Command<RequestT, ResponseT, any>>({
+                endpointId,
+                clusterId,
+                command: commandDef[commandName],
+                request,
+                asTimedRequest,
+                timedRequestTimeoutMs,
+                useExtendedFailSafeMessageResponseTimeout,
+            });
+        };
+        result[commandName] = result.commands[commandName];
+    }
+    if (globalAttributeValues?.acceptedCommandList !== undefined) {
+        for (const requestId of globalAttributeValues.acceptedCommandList) {
+            if (commandToId[requestId] === undefined) {
+                logger.info(`Ignoring unknown command ${requestId} at cluster ${Diagnostic.hex(clusterId)}`);
+            }
+        }
+    }
+
+    return result as ClusterClientObj<T>;
+}

package/src/cluster/client/ClusterClientTypes.ts

@@ -0,0 +1,257 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Merge } from "#general";
+import {
+    Attribute,
+    AttributeId,
+    AttributeJsType,
+    Attributes,
+    BitSchema,
+    ClusterId,
+    ClusterType,
+    Command,
+    CommandId,
+    Commands,
+    EndpointNumber,
+    EventId,
+    EventType,
+    Events,
+    GlobalAttributeNames,
+    GlobalAttributes,
+    MandatoryAttributeNames,
+    MandatoryEventNames,
+    OptionalAttribute,
+    OptionalAttributeNames,
+    OptionalEventNames,
+    OptionalWritableAttribute,
+    RequestType,
+    ResponseType,
+    TlvEventFilter,
+    TypeFromPartialBitSchema,
+    TypeFromSchema,
+    WritableAttribute,
+} from "#types";
+import { DecodedEventData } from "../../interaction/EventDataDecoder.js";
+import { AttributeClient } from "./AttributeClient.js";
+import { EventClient } from "./EventClient.js";
+
+export type AttributeClients<F extends BitSchema, A extends Attributes> = Merge<
+    Merge<
+        { [P in MandatoryAttributeNames<A>]: AttributeClient<AttributeJsType<A[P]>> },
+        { [P in OptionalAttributeNames<A>]: AttributeClient<AttributeJsType<A[P]> | undefined> }
+    >,
+    { [P in GlobalAttributeNames<F>]: AttributeClient<AttributeJsType<GlobalAttributes<F>[P]>> }
+>;
+
+export type AttributeClientValues<A extends Attributes> = Merge<
+    { [P in MandatoryAttributeNames<A>]: AttributeJsType<A[P]> },
+    { [P in OptionalAttributeNames<A>]?: AttributeJsType<A[P]> }
+>;
+
+export type EventClients<E extends Events> = Merge<
+    { [P in MandatoryEventNames<E>]: EventClient<EventType<E[P]>> },
+    { [P in OptionalEventNames<E>]: EventClient<EventType<E[P]> | undefined> }
+>;
+
+export type SignatureFromCommandSpec<C extends Command<any, any, any>> = (
+    request: RequestType<C>,
+    options?: {
+        /** Send this command as a timed request also when not required. Default timeout are 10 seconds. */
+        asTimedRequest?: boolean;
+
+        /** Override the request timeout when the command is sent as times request. Default are 10s. */
+        timedRequestTimeoutMs?: number;
+
+        /**
+         * Use the extended fail-safe message response timeout of 30 seconds. Use this for all commands
+         * executed during an activated FailSafe context!
+         */
+        useExtendedFailSafeMessageResponseTimeout?: boolean;
+    },
+) => Promise<ResponseType<C>>;
+type GetterTypeFromSpec<A extends Attribute<any, any>> =
+    A extends OptionalAttribute<infer T, any> ? T | undefined : AttributeJsType<A>;
+type ClientAttributeGetters<A extends Attributes> = Omit<
+    {
+        [P in keyof A as `get${Capitalize<string & P>}Attribute`]: (
+            alwaysRequestFromRemote?: boolean,
+            isFabricFiltered?: boolean,
+        ) => Promise<GetterTypeFromSpec<A[P]>>;
+    },
+    keyof GlobalAttributes<any>
+>;
+type ClientGlobalAttributeGetters<F extends BitSchema> = {
+    [P in GlobalAttributeNames<F> as `get${Capitalize<string & P>}Attribute`]: () => Promise<
+        GetterTypeFromSpec<GlobalAttributes<F>[P]>
+    >;
+};
+type WritableAttributeNames<A extends Attributes> =
+    | { [K in keyof A]: A[K] extends WritableAttribute<any, any> ? K : never }[keyof A]
+    | { [K in keyof A]: A[K] extends OptionalWritableAttribute<any, any> ? K : never }[keyof A];
+type ClientAttributeSetters<A extends Attributes> = {
+    [P in WritableAttributeNames<A> as `set${Capitalize<string & P>}Attribute`]: (
+        value: AttributeJsType<A[P]>,
+    ) => Promise<void>;
+};
+type ClientAttributeSubscribers<A extends Attributes> = {
+    [P in keyof A as `subscribe${Capitalize<string & P>}Attribute`]: (
+        listener: (value: AttributeJsType<A[P]>) => void,
+        minIntervalS: number,
+        maxIntervalS: number,
+        knownDataVersion?: number,
+        isFabricFiltered?: boolean,
+    ) => Promise<void>;
+};
+type ClientAttributeListeners<A extends Attributes> = {
+    [P in keyof A as `add${Capitalize<string & P>}AttributeListener`]: (
+        listener: (value: AttributeJsType<A[P]>) => void,
+    ) => void;
+};
+
+type CommandServers<C extends Commands> = { [P in keyof C]: SignatureFromCommandSpec<C[P]> };
+
+type ClientEventGetters<E extends Events> = {
+    [P in keyof E as `get${Capitalize<string & P>}Event`]: (
+        minimumEventNumber?: number | bigint,
+        isFabricFiltered?: boolean,
+    ) => Promise<DecodedEventData<EventType<E[P]>>>;
+};
+type ClientEventSubscribers<E extends Events> = {
+    [P in keyof E as `subscribe${Capitalize<string & P>}Event`]: (
+        listener: (value: DecodedEventData<EventType<E[P]>>) => void,
+        minIntervalS: number,
+        maxIntervalS: number,
+        isUrgent?: boolean,
+        minimumEventNumber?: number | bigint,
+        isFabricFiltered?: boolean,
+    ) => Promise<void>;
+};
+type ClientEventListeners<E extends Events> = {
+    [P in keyof E as `add${Capitalize<string & P>}EventListener`]: (
+        listener: (value: DecodedEventData<EventType<E[P]>>) => void,
+    ) => void;
+};
+
+/** Strongly typed interface of a cluster client */
+export type ClusterClientObj<T extends ClusterType = ClusterType> = {
+    /**
+     * Cluster ID
+     * @readonly
+     */
+    id: ClusterId;
+
+    /**
+     * Cluster type
+     * @private
+     * @readonly
+     */
+    _type: "ClusterClient";
+
+    /**
+     * Cluster revision
+     * @readonly
+     */
+    readonly revision: number;
+
+    /**
+     * Cluster name
+     * @readonly
+     */
+    readonly name: string;
+
+    /**
+     * Whether the cluster is unknown, means that we do not have types and schema information for it. Most likely no
+     * official cluster.
+     * @readonly
+     */
+    readonly isUnknown: boolean;
+
+    /**
+     * Endpoint ID the cluster is on.
+     * @readonly
+     */
+    readonly endpointId: number;
+
+    /**
+     * Supported Features of the cluster
+     * @readonly
+     */
+    readonly supportedFeatures: TypeFromPartialBitSchema<T["features"]>;
+
+    /**
+     * Attributes of the cluster as object with named keys. This can be used to discover the attributes of the cluster
+     * programmatically.
+     * @readonly
+     */
+    readonly attributes: AttributeClients<T["features"], T["attributes"]>;
+
+    /**
+     * Events of the cluster as object with named keys. This can be used to discover the events of the cluster
+     * programmatically.
+     * @readonly
+     */
+    readonly events: EventClients<T["events"]>;
+
+    /**
+     * Commands of the cluster as object with named keys. This can be used to discover the commands of the cluster
+     * programmatically.
+     * @readonly
+     */
+    readonly commands: CommandServers<T["commands"]>;
+
+    /**
+     * Subscribe to all attributes of the cluster. This will subscribe to all attributes of the cluster. Add listeners
+     * to the relevant attributes you want to get updates for.
+     */
+    readonly subscribeAllAttributes: (options: {
+        minIntervalFloorSeconds: number;
+        maxIntervalCeilingSeconds: number;
+        keepSubscriptions?: boolean;
+        isFabricFiltered?: boolean;
+        eventFilters?: TypeFromSchema<typeof TlvEventFilter>[];
+        dataVersionFilters?: { endpointId: EndpointNumber; clusterId: ClusterId; dataVersion: number }[];
+    }) => Promise<void>;
+
+    /** Returns if a given Attribute Id is present and supported at the connected cluster server. */
+    isAttributeSupported: (attributeId: AttributeId) => boolean;
+
+    /** Returns if a given Attribute with provided name is present and supported at the connected cluster server. */
+    isAttributeSupportedByName: (attributeName: string) => boolean;
+
+    /** Returns if a given Event Id is present and supported at the connected cluster server. */
+    isEventSupported: (eventId: EventId) => boolean;
+
+    /** Returns if a given Event with provided name is present and supported at the connected cluster server. */
+    isEventSupportedByName: (eventName: string) => boolean;
+
+    /** Returns if a given Command Id is present and supported at the connected cluster server. */
+    isCommandSupported: (commandId: CommandId) => boolean;
+
+    /** Returns if a given Command with provided name is present and supported at the connected cluster server. */
+    isCommandSupportedByName: (commandName: string) => boolean;
+} & ClientAttributeGetters<T["attributes"]> &
+    ClientGlobalAttributeGetters<T["features"]> &
+    ClientAttributeSetters<T["attributes"]> &
+    ClientAttributeSubscribers<T["attributes"]> &
+    ClientAttributeListeners<T["attributes"]> &
+    CommandServers<T["commands"]> &
+    ClientEventGetters<T["events"]> &
+    ClientEventSubscribers<T["events"]> &
+    ClientEventListeners<T["events"]>;
+
+export type ClusterClientObjInternal<T extends ClusterType = ClusterType> = ClusterClientObj<T> & {
+    /**
+     * Trigger an attribute update. This is mainly used internally and not needed to be called by the user.
+     * @private
+     */
+    readonly _triggerAttributeUpdate: (attributeId: AttributeId, value: any) => void;
+
+    /**
+     * Trigger an event update. This is mainly used internally and not needed to be called by the user.
+     * @private
+     */
+    readonly _triggerEventUpdate: (eventId: EventId, events: DecodedEventData<any>[]) => void;
+};