@matter/protocol 0.14.1-alpha.0-20250605-9fc134af0 → 0.14.1-alpha.0-20250607-a93593303

package/src/cluster/client/ClusterClient.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { capitalize, Diagnostic, Logger, Merge } from "#general";
+import { capitalize, Diagnostic, ImplementationError, Logger, Merge } from "#general";
 import {
     Attribute,
     AttributeId,
@@ -31,18 +31,37 @@ import {
     AttributeClientValues,
     ClusterClientObj,
     EventClients,
+    GroupClusterClientObj,
     SignatureFromCommandSpec,
+    SignatureFromCommandSpecWithoutResponse,
 } from "./ClusterClientTypes.js";
 import { createEventClient } from "./EventClient.js";
 
 const logger = Logger.get("ClusterClient");
 
+export function GroupClusterClient<const T extends ClusterType>(
+    clusterDef: T,
+    interactionClient: InteractionClient,
+    globalAttributeValues: Partial<AttributeClientValues<GlobalAttributes<T["features"]>>> = {},
+): GroupClusterClientObj<T> {
+    if (!interactionClient.isGroupAddress) {
+        throw new Error("GroupClusterClient must be used with a GroupAddress InteractionClient");
+    }
+
+    return ClusterClient(clusterDef, undefined, interactionClient, globalAttributeValues);
+}
+
 export function ClusterClient<const T extends ClusterType>(
     clusterDef: T,
-    endpointId: EndpointNumber,
+    endpointId: EndpointNumber | undefined,
     interactionClient: InteractionClient,
     globalAttributeValues: Partial<AttributeClientValues<GlobalAttributes<T["features"]>>> = {},
 ): ClusterClientObj<T> {
+    const isGroupAddress = interactionClient.isGroupAddress;
+    if (isGroupAddress !== (endpointId === undefined)) {
+        throw new Error("Endpoint ID must be defined for a Non-Group ClusterClient");
+    }
+
     function addAttributeToResult(attribute: Attribute<any, any>, attributeName: string) {
         (attributes as any)[attributeName] = createAttributeClient(
             attribute,
@@ -59,6 +78,10 @@ export function ClusterClient<const T extends ClusterType>(
             requestFromRemote?: boolean,
             isFabricFiltered = true,
         ) => {
+            if (isGroupAddress) {
+                throw new ImplementationError("Group cluster clients do not support reading attributes");
+            }
+
             try {
                 return await (attributes as any)[attributeName].get(requestFromRemote, isFabricFiltered);
             } catch (e) {
@@ -68,6 +91,13 @@ export function ClusterClient<const T extends ClusterType>(
                 throw e;
             }
         };
+        result[`get${capitalizedAttributeName}AttributeFromCache`] = () => {
+            if (isGroupAddress) {
+                throw new ImplementationError("Group cluster clients do not support reading attributes");
+            }
+
+            return (attributes as any)[attributeName].getLocal();
+        };
         result[`set${capitalizedAttributeName}Attribute`] = async <T>(value: T, dataVersion?: number) =>
             (attributes as any)[attributeName].set(value, dataVersion);
         result[`subscribe${capitalizedAttributeName}Attribute`] = async <T>(
@@ -77,6 +107,10 @@ export function ClusterClient<const T extends ClusterType>(
             knownDataVersion?: number,
             isFabricFiltered?: boolean,
         ) => {
+            if (isGroupAddress) {
+                throw new ImplementationError("Group cluster clients do not support subscribing attributes");
+            }
+
             (attributes as any)[attributeName].addListener(listener);
             return (attributes as any)[attributeName].subscribe(
                 minIntervalS,
@@ -86,9 +120,17 @@ export function ClusterClient<const T extends ClusterType>(
             );
         };
         result[`add${capitalizedAttributeName}AttributeListener`] = <T>(listener: (value: T) => void) => {
+            if (isGroupAddress) {
+                throw new ImplementationError("Group cluster clients do not support subscribing attributes");
+            }
+
             (attributes as any)[attributeName].addListener(listener);
         };
         result[`remove${capitalizedAttributeName}AttributeListener`] = <T>(listener: (value: T) => void) => {
+            if (isGroupAddress) {
+                throw new ImplementationError("Group cluster clients do not support subscribing attributes");
+            }
+
             (attributes as any)[attributeName].removeListener(listener);
         };
     }
@@ -102,6 +144,10 @@ export function ClusterClient<const T extends ClusterType>(
             minimumEventNumber?: number | bigint,
             isFabricFiltered?: boolean,
         ) => {
+            if (isGroupAddress) {
+                throw new ImplementationError("Group cluster clients do not support reading events");
+            }
+
             try {
                 return await (events as any)[eventName].get(minimumEventNumber, isFabricFiltered);
             } catch (e) {
@@ -119,6 +165,10 @@ export function ClusterClient<const T extends ClusterType>(
             minimumEventNumber?: number | bigint,
             isFabricFiltered?: boolean,
         ) => {
+            if (isGroupAddress) {
+                throw new ImplementationError("Group cluster clients do not support subscribing to events");
+            }
+
             (events as any)[eventName].addListener(listener);
             return (events as any)[eventName].subscribe(
                 minIntervalS,
@@ -129,9 +179,17 @@ export function ClusterClient<const T extends ClusterType>(
             );
         };
         result[`add${capitalizedEventName}EventListener`] = <T>(listener: (value: DecodedEventData<T>) => void) => {
+            if (isGroupAddress) {
+                throw new ImplementationError("Group cluster clients do not support subscribing events");
+            }
+
             (events as any)[eventName].addListener(listener);
         };
         result[`remove${capitalizedEventName}EventListener`] = <T>(listener: (value: DecodedEventData<T>) => void) => {
+            if (isGroupAddress) {
+                throw new ImplementationError("Group cluster clients do not support subscribing events");
+            }
+
             (events as any)[eventName].removeListener(listener);
         };
     }
@@ -149,7 +207,13 @@ export function ClusterClient<const T extends ClusterType>(
     } = clusterDef;
     const attributes = <AttributeClients<T["features"], T["attributes"]>>{};
     const events = <EventClients<T["events"]>>{};
-    const commands = <{ [P in keyof T["commands"]]: SignatureFromCommandSpec<T["commands"][P]> }>{};
+    const commands = <
+        {
+            [P in keyof T["commands"]]:
+                | SignatureFromCommandSpec<T["commands"][P]>
+                | SignatureFromCommandSpecWithoutResponse<T["commands"][P]>;
+        }
+    >{};
 
     let reportedFeatures: TypeFromPartialBitSchema<T["features"]> | undefined = undefined;
     // If we have global attribute values we use them to modify
@@ -178,6 +242,10 @@ export function ClusterClient<const T extends ClusterType>(
             eventFilters?: TypeFromSchema<typeof TlvEventFilter>[];
             dataVersionFilters?: { endpointId: EndpointNumber; clusterId: ClusterId; dataVersion: number }[];
         }) => {
+            if (isGroupAddress) {
+                throw new ImplementationError("Group cluster clients do not support subscribing attributes");
+            }
+
             const {
                 minIntervalFloorSeconds,
                 maxIntervalCeilingSeconds,
@@ -237,10 +305,18 @@ export function ClusterClient<const T extends ClusterType>(
         },
 
         isAttributeSupported: (attributeId: AttributeId) => {
+            if (isGroupAddress) {
+                throw new ImplementationError("Group cluster clients do not allow to determine attribute existence.");
+            }
+
             return !!globalAttributeValues?.attributeList?.includes(attributeId);
         },
 
         isAttributeSupportedByName: (attributeName: string) => {
+            if (isGroupAddress) {
+                throw new ImplementationError("Group cluster clients do not allow to determine attribute existence.");
+            }
+
             const attribute = (attributes as any)[attributeName];
             if (attribute === undefined) {
                 return false;
@@ -249,10 +325,18 @@ export function ClusterClient<const T extends ClusterType>(
         },
 
         isCommandSupported: (commandId: CommandId) => {
+            if (isGroupAddress) {
+                throw new ImplementationError("Group cluster clients do not allow to determine command existence.");
+            }
+
             return !!globalAttributeValues?.acceptedCommandList?.includes(commandId);
         },
 
         isCommandSupportedByName: (commandName: string) => {
+            if (isGroupAddress) {
+                throw new ImplementationError("Group cluster clients do not allow to determine attribute existence.");
+            }
+
             const command = commandDef[commandName];
             if (command === undefined) {
                 return false;
@@ -308,8 +392,17 @@ export function ClusterClient<const T extends ClusterType>(
             } = {},
         ) => {
             const { asTimedRequest, timedRequestTimeoutMs, useExtendedFailSafeMessageResponseTimeout } = options;
+            if (isGroupAddress) {
+                return interactionClient.invokeWithSuppressedResponse<Command<RequestT, ResponseT, any>>({
+                    clusterId,
+                    command: commandDef[commandName],
+                    request,
+                    asTimedRequest,
+                    timedRequestTimeoutMs,
+                });
+            }
             return interactionClient.invoke<Command<RequestT, ResponseT, any>>({
-                endpointId,
+                endpointId: endpointId!,
                 clusterId,
                 command: commandDef[commandName],
                 request,

package/src/cluster/client/ClusterClientTypes.ts

@@ -72,6 +72,23 @@ export type SignatureFromCommandSpec<C extends Command<any, any, any>> = (
         useExtendedFailSafeMessageResponseTimeout?: boolean;
     },
 ) => Promise<ResponseType<C>>;
+
+export type SignatureFromCommandSpecWithoutResponse<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<void>;
 type GetterTypeFromSpec<A extends Attribute<any, any>> =
     A extends OptionalAttribute<infer T, any> ? T | undefined : AttributeJsType<A>;
 type ClientAttributeGetters<A extends Attributes> = Omit<
@@ -83,6 +100,12 @@ type ClientAttributeGetters<A extends Attributes> = Omit<
     },
     keyof GlobalAttributes<any>
 >;
+type ClientLocalAttributeGetters<A extends Attributes> = Omit<
+    {
+        [P in keyof A as `get${Capitalize<string & P>}AttributeFromCache`]: () => GetterTypeFromSpec<A[P]> | undefined;
+    },
+    keyof GlobalAttributes<any>
+>;
 type ClientGlobalAttributeGetters<F extends BitSchema> = {
     [P in GlobalAttributeNames<F> as `get${Capitalize<string & P>}Attribute`]: () => Promise<
         GetterTypeFromSpec<GlobalAttributes<F>[P]>
@@ -116,6 +139,7 @@ type ClientAttributeListeners<A extends Attributes> = {
 };
 
 type CommandServers<C extends Commands> = { [P in keyof C]: SignatureFromCommandSpec<C[P]> };
+type NoResponseCommandServers<C extends Commands> = { [P in keyof C]: SignatureFromCommandSpecWithoutResponse<C[P]> };
 
 type ClientEventGetters<E extends Events> = {
     [P in keyof E as `get${Capitalize<string & P>}Event`]: (
@@ -143,8 +167,8 @@ type ClientEventListeners<E extends Events> = {
     ) => void;
 };
 
-/** Strongly typed interface of a cluster client */
-export type ClusterClientObj<T extends ClusterType = ClusterType> = {
+/** Strongly typed interface of a group cluster client (limited functionalities) */
+export type BaseClusterClientObj<T extends ClusterType = ClusterType> = {
     /**
      * Cluster ID
      * @readonly
@@ -177,12 +201,6 @@ export type ClusterClientObj<T extends ClusterType = ClusterType> = {
      */
     readonly isUnknown: boolean;
 
-    /**
-     * Endpoint ID the cluster is on.
-     * @readonly
-     */
-    readonly endpointId: number;
-
     /**
      * Supported Features of the cluster
      * @readonly
@@ -195,6 +213,24 @@ export type ClusterClientObj<T extends ClusterType = ClusterType> = {
      * @readonly
      */
     readonly attributes: AttributeClients<T["features"], T["attributes"]>;
+} & ClientAttributeSetters<T["attributes"]>;
+
+export type GroupClusterClientObj<T extends ClusterType = ClusterType> = BaseClusterClientObj<T> & {
+    /**
+     * Commands of the cluster as object with named keys. This can be used to discover the commands of the cluster
+     * programmatically.
+     * @readonly
+     */
+    readonly commands: NoResponseCommandServers<T["commands"]>;
+} & NoResponseCommandServers<T["commands"]>;
+
+/** Strongly typed interface of a cluster client */
+export type ClusterClientObj<T extends ClusterType = ClusterType> = BaseClusterClientObj<T> & {
+    /**
+     * Endpoint ID the cluster is on.
+     * @readonly
+     */
+    readonly endpointId: number;
 
     /**
      * Events of the cluster as object with named keys. This can be used to discover the events of the cluster
@@ -235,8 +271,8 @@ export type ClusterClientObj<T extends ClusterType = ClusterType> = {
     /** Returns if a given Command with provided name is present and supported at the connected cluster server. */
     isCommandSupportedByName: (commandName: string) => boolean;
 } & ClientAttributeGetters<T["attributes"]> &
+    ClientLocalAttributeGetters<T["attributes"]> &
     ClientGlobalAttributeGetters<T["features"]> &
-    ClientAttributeSetters<T["attributes"]> &
     ClientAttributeSubscribers<T["attributes"]> &
     ClientAttributeListeners<T["attributes"]> &
     CommandServers<T["commands"]> &

package/src/cluster/client/EventClient.ts

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { ImplementationError } from "#general";
 import { ClusterId, EndpointNumber, Event, EventId, EventNumber } from "#types";
 import { DecodedEventData } from "../../interaction/EventDataDecoder.js";
 import { InteractionClient } from "../../interaction/InteractionClient.js";
@@ -14,7 +15,7 @@ import { InteractionClient } from "../../interaction/InteractionClient.js";
 export function createEventClient<T>(
     event: Event<T, any>,
     name: string,
-    endpointId: EndpointNumber,
+    endpointId: EndpointNumber | undefined,
     clusterId: ClusterId,
     interactionClient: InteractionClient,
 ): EventClient<T> {
@@ -32,7 +33,7 @@ export class EventClient<T> {
     constructor(
         readonly event: Event<T, any>,
         readonly name: string,
-        readonly endpointId: EndpointNumber,
+        readonly endpointId: EndpointNumber | undefined,
         readonly clusterId: ClusterId,
         interactionClient: InteractionClient,
     ) {
@@ -44,6 +45,9 @@ export class EventClient<T> {
         minimumEventNumber?: EventNumber,
         isFabricFiltered?: boolean,
     ): Promise<DecodedEventData<T>[] | undefined> {
+        if (this.endpointId === undefined) {
+            throw new ImplementationError("Cannot read event without endpointId");
+        }
         return await this.#interactionClient.getEvent({
             endpointId: this.endpointId,
             clusterId: this.clusterId,
@@ -60,6 +64,9 @@ export class EventClient<T> {
         minimumEventNumber?: EventNumber,
         isFabricFiltered?: boolean,
     ) {
+        if (this.endpointId === undefined) {
+            throw new ImplementationError("Cannot read event without endpointId");
+        }
         return await this.#interactionClient.subscribeEvent({
             endpointId: this.endpointId,
             clusterId: this.clusterId,

package/src/codec/MessageCodec.ts

@@ -4,7 +4,16 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { Bytes, DataReader, DataWriter, Diagnostic, Endian, NotImplementedError, UnexpectedDataError } from "#general";
+import {
+    Bytes,
+    DataReader,
+    DataWriter,
+    Diagnostic,
+    Endian,
+    InternalError,
+    NotImplementedError,
+    UnexpectedDataError,
+} from "#general";
 import { ExchangeLogContext } from "#protocol/index.js";
 import { GroupId, INTERACTION_PROTOCOL_ID, NodeId, SECURE_CHANNEL_PROTOCOL_ID, SecureMessageType } from "#types";
 import { MessageType } from "../interaction/InteractionMessenger.js";
@@ -84,6 +93,7 @@ const enum SecurityFlag {
     HasPrivacyEnhancements = 0b10000000,
     IsControlMessage = 0b01000000,
     HasMessageExtension = 0b00100000,
+    SessionTypeMask = 0b00000011,
 }
 
 function mapProtocolAndMessageType(protocolId: number, messageType: number): { type: string; for?: string } {
@@ -129,6 +139,13 @@ export class MessageCodec {
             const extensionLength = reader.readUInt16();
             securityExtension = reader.readByteArray(extensionLength);
         }
+
+        if (header.sessionType === SessionType.Group && !header.isControlMessage) {
+            if (payloadHeader.requiresAck || payloadHeader.ackedMessageId) {
+                throw new UnexpectedDataError(`Group data messages cannot have requiresAck or ackedMessageId set.`);
+            }
+        }
+
         return {
             packetHeader: header,
             payloadHeader,
@@ -176,13 +193,31 @@ export class MessageCodec {
         const destNodeId = hasDestNodeId ? NodeId(reader.readUInt64()) : undefined;
         const destGroupId = hasDestGroupId ? GroupId(reader.readUInt16()) : undefined;
 
-        const sessionType = securityFlags & 0b00000011;
-        if (sessionType !== SessionType.Group && sessionType !== SessionType.Unicast)
-            throw new UnexpectedDataError(`Unsupported session type ${sessionType}`);
+        const sessionType = securityFlags & SecurityFlag.SessionTypeMask;
+
+        if (sessionType !== SessionType.Group && sessionType !== SessionType.Unicast) {
+            throw new UnexpectedDataError(`Unsupported session type ${sessionType}.`);
+        }
+        if (sessionType === SessionType.Unicast && hasDestGroupId) {
+            throw new UnexpectedDataError(`Unicast session cannot have destination group id.`);
+        }
+        if (sessionType === SessionType.Group) {
+            if (!hasDestGroupId && !hasDestNodeId) {
+                throw new UnexpectedDataError(`Group session must have destination group id or destination node id.`);
+            }
+            if (!hasSourceNodeId) {
+                throw new UnexpectedDataError(`Group session must have source node id.`);
+            }
+        }
         const hasPrivacyEnhancements = (securityFlags & SecurityFlag.HasPrivacyEnhancements) !== 0;
-        if (hasPrivacyEnhancements) throw new NotImplementedError(`Privacy enhancements not supported`);
+        if (hasPrivacyEnhancements) {
+            throw new NotImplementedError(`Privacy enhancements not supported.`);
+        }
         const isControlMessage = (securityFlags & SecurityFlag.IsControlMessage) !== 0;
-        if (isControlMessage) throw new NotImplementedError(`Control Messages not supported`);
+        if (isControlMessage) {
+            // And also currently not needed because MCP is not relevant
+            throw new NotImplementedError(`Control Messages not supported.`);
+        }
         const hasMessageExtensions = (securityFlags & SecurityFlag.HasMessageExtension) !== 0;
 
         return {
@@ -207,7 +242,7 @@ export class MessageCodec {
         const hasSecuredExtension = (exchangeFlags & PayloadHeaderFlag.HasSecureExtension) !== 0;
         const hasVendorId = (exchangeFlags & PayloadHeaderFlag.HasVendorId) !== 0;
 
-        const messageType = reader.readUInt8();
+        const messageType = reader.readUInt8(); // Protocol Opcode
         const exchangeId = reader.readUInt16();
         const vendorId = hasVendorId ? reader.readUInt16() : COMMON_VENDOR_ID;
         const protocolId = (vendorId << 16) | reader.readUInt16();
@@ -232,6 +267,12 @@ export class MessageCodec {
         sourceNodeId,
         sessionType,
     }: PacketHeader) {
+        if (
+            sessionType === SessionType.Group &&
+            (destGroupId === undefined || sourceNodeId === undefined || destNodeId !== undefined)
+        ) {
+            throw new InternalError(`Group session must have destination group id or source node id.`);
+        }
         const writer = new DataWriter(Endian.Little);
         const flags =
             (HEADER_VERSION << 4) |
@@ -246,7 +287,7 @@ export class MessageCodec {
         writer.writeUInt32(messageCounter);
         if (sourceNodeId !== undefined) writer.writeUInt64(sourceNodeId);
         if (destNodeId !== undefined) writer.writeUInt64(destNodeId);
-        if (destGroupId !== undefined) writer.writeUInt32(destGroupId);
+        if (destGroupId !== undefined) writer.writeUInt16(destGroupId);
         return writer.toByteArray();
     }