@matter/protocol 0.13.1-alpha.0-20250520-d699cd56d → 0.14.0-alpha.0-20250524-51a7e1721

package/src/action/protocols.ts

@@ -8,15 +8,24 @@ import { InteractionSession } from "#action/Interactable.js";
 import { OccurrenceManager } from "#events/OccurrenceManager.js";
 import { MaybePromise, Observable } from "#general";
 import { DataModelPath, MatterModel } from "#model";
-import type { AttributeId, ClusterId, DeviceTypeId, EndpointNumber, FabricIndex, NodeId, TlvSchema } from "#types";
-import { AttributePath, EventId, EventPath } from "#types";
+import type {
+    AttributeId,
+    ClusterId,
+    CommandId,
+    DeviceTypeId,
+    EndpointNumber,
+    FabricIndex,
+    NodeId,
+    TlvSchema,
+} from "#types";
+import { AttributePath, CommandPath, EventId, EventPath } from "#types";
 import { AccessControl } from "./server/AccessControl.js";
 import { Val } from "./Val.js";
 
-export interface AvailableElementIds {
-    attributes: Set<AttributeId>;
-    events: Set<EventId>;
-}
+export type CommandInvokeHandler = (
+    args: Val.Struct | undefined,
+    session: InteractionSession,
+) => MaybePromise<Val.Struct | void>;
 
 /**
  * Optimized Matter protocol<->JS object interface
@@ -65,7 +74,7 @@ export interface NodeProtocol extends CollectionProtocol<EndpointProtocol> {
     /**
      * Inspects an Attribute- or Event path and log in human-readable form if possible
      */
-    inspectPath(path: AttributePath | EventPath): string;
+    inspectPath(path: AttributePath | EventPath | CommandPath): string;
 }
 
 /**
@@ -74,6 +83,11 @@ export interface NodeProtocol extends CollectionProtocol<EndpointProtocol> {
 export interface EndpointProtocol
     extends CollectionProtocol<ClusterProtocol>,
         AddressableElementProtocol<EndpointNumber> {
+    /**
+     * Bitmap with each wildcard path flag bit set where this value should be skipped.
+     */
+    wildcardPathFlags: number;
+
     /**
      * Path to the endpoint within the data model.
      */
@@ -118,6 +132,11 @@ export interface ClusterProtocol {
      * session.  So doing is the responsibility of the node implementation.
      */
     openForWrite(session: InteractionSession): Promise<Val.ProtocolStruct>;
+
+    /**
+     * Invoke handler for the commands of the cluster
+     */
+    commands: Record<CommandId, CommandInvokeHandler>;
 }
 
 /**
@@ -126,6 +145,11 @@ export interface ClusterProtocol {
  * TODO - commands
  */
 export interface ClusterTypeProtocol extends AddressableElementProtocol<ClusterId> {
+    /**
+     * Bitmap with each wildcard path flag bit set where this value should be skipped.
+     */
+    wildcardPathFlags: number;
+
     /**
      * Attribute metadata.
      */
@@ -135,12 +159,22 @@ export interface ClusterTypeProtocol extends AddressableElementProtocol<ClusterI
      * Event metadata.
      */
     events: CollectionProtocol<EventTypeProtocol>;
+
+    /**
+     * Command metadata.
+     */
+    commands: CollectionProtocol<CommandTypeProtocol>;
 }
 
 /**
- * Descriptor for a specific property type.
+ * Descriptor for a specific attribute property type.
  */
 export interface AttributeTypeProtocol extends AddressableElementProtocol<AttributeId> {
+    /**
+     * Bitmap with each wildcard path flag bit set where this value should be skipped.
+     */
+    wildcardPathFlags: number;
+
     /**
      * The TLV schema for this property.
      */
@@ -163,16 +197,41 @@ export interface AttributeTypeProtocol extends AddressableElementProtocol<Attrib
 }
 
 /**
- * Descriptor for a specific property type.
+ * Descriptor for a specific event property type.
  */
-export interface EventTypeProtocol extends Omit<AddressableElementProtocol<EventId>, "wildcardPathFlags"> {
+export interface EventTypeProtocol extends AddressableElementProtocol<EventId> {
     /**
      * The TLV schema for this property.
      */
     tlv: TlvSchema<unknown>;
 
     /**
-     * Access control information for the attribute.
+     * Access control information for the event.
+     */
+    limits: AccessControl.Limits;
+}
+
+/**
+ * Descriptor for a specific command property type.
+ */
+export interface CommandTypeProtocol extends AddressableElementProtocol<CommandId> {
+    /**
+     * The TLV schema for the command request.
+     */
+    requestTlv: TlvSchema<unknown>;
+
+    /**
+     * The TLV schema for the command response.
+     */
+    responseTlv: TlvSchema<unknown>;
+
+    /**
+     * The Response command Id
+     */
+    responseId: CommandId;
+
+    /**
+     * Access control information for the command.
      */
     limits: AccessControl.Limits;
 }
@@ -190,11 +249,6 @@ export interface AddressableElementProtocol<N extends number> {
      * Human readable name of the element.
      */
     name: string;
-
-    /**
-     * Bitmap with each wildcard path flag bit set where this value should be skipped.
-     */
-    wildcardPathFlags: number;
 }
 
 /**

package/src/action/request/Invoke.ts

@@ -10,26 +10,53 @@ import { MalformedRequestError } from "./MalformedRequestError.js";
 import { Specifier } from "./Specifier.js";
 
 export interface Invoke extends InvokeRequest {
+    /** Timeout only relevant for Client Interactions */
     timeout?: number;
 }
 
 /**
  * Request invocation of one or more commands.
  */
-export function Invoke(definition: Invoke.Definition): Invoke {
+export function Invoke(options: Invoke.Definition): Invoke;
+
+/**
+ * Request invocation multiple commands with defined options
+ */
+export function Invoke(options: Invoke.Definition, ...commands: CommandData[]): Invoke;
+
+/**
+ * Request invocation multiple commands as list of Commands with default options.
+ */
+export function Invoke(...commands: CommandData[]): Invoke;
+
+export function Invoke(optionsOrData: Invoke.Definition | CommandData, ...commands: CommandData[]): Invoke {
+    let options;
+    if ("commands" in optionsOrData) {
+        options = optionsOrData;
+    } else {
+        commands = [optionsOrData, ...commands];
+        options = {};
+    }
+
     const {
-        commands,
+        commands: invokeRequests = [],
         interactionModelRevision = FALLBACK_INTERACTIONMODEL_REVISION,
         suppressResponse = false,
         timed: timedRequest = false,
-    } = definition;
+    } = options;
+
+    if (commands.length) {
+        for (const entry of commands) {
+            invokeRequests.push(entry);
+        }
+    }
 
-    if (!commands?.length) {
+    if (!invokeRequests?.length) {
         throw new MalformedRequestError(`Invocation requires at least one command`);
     }
 
     return {
-        invokeRequests: commands,
+        invokeRequests,
         interactionModelRevision,
         suppressResponse,
         timedRequest,

package/src/action/request/Read.ts

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { camelize } from "#general";
 import { FALLBACK_INTERACTIONMODEL_REVISION } from "#session/Session.js";
 import type {
     AttributePath,
@@ -14,7 +15,6 @@ import type {
     GlobalAttributes,
     ReadRequest,
 } from "#types";
-import { camelize } from "@matter/general";
 import { MalformedRequestError } from "./MalformedRequestError.js";
 import { Specifier } from "./Specifier.js";
 

package/src/action/request/Write.ts

@@ -9,7 +9,10 @@ import { AttributeData, ClusterType, WriteRequest } from "#types";
 import { MalformedRequestError } from "./MalformedRequestError.js";
 import { Specifier } from "./Specifier.js";
 
-export interface Write extends WriteRequest {}
+export interface Write extends WriteRequest {
+    /** Timeout only relevant for Client Interactions */
+    timeout?: number;
+}
 
 /**
  * Formulate a write-request using Matter numeric IDs.

package/src/action/response/InvokeResult.ts

@@ -4,13 +4,33 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import type { Invoke } from "#action/request/Invoke.js";
-import type { CommandData } from "#types";
+import type { ClusterId, CommandId, CommandPath, EndpointNumber, StatusCode, TlvStream } from "#types";
 
-export type InvokeResult<T extends Invoke> = T extends { suppressResponse: true }
-    ? Promise<void>
-    : AsyncIterable<InvokeResult.Chunk>;
+export type InvokeResult = AsyncIterable<InvokeResult.Chunk>;
 
 export namespace InvokeResult {
-    export type Chunk = CommandData[];
+    export type Chunk = Iterable<Data>;
+
+    export type Data = CommandStatus | CommandResponse;
+
+    export interface ConcreteCommandPath extends CommandPath {
+        endpointId: EndpointNumber;
+        clusterId: ClusterId;
+        commandId: CommandId;
+    }
+
+    export interface CommandStatus {
+        kind: "cmd-status";
+        path: ConcreteCommandPath;
+        commandRef?: number;
+        status: StatusCode;
+        clusterStatus?: number;
+    }
+
+    export interface CommandResponse {
+        kind: "cmd-response";
+        path: ConcreteCommandPath;
+        commandRef?: number;
+        data: TlvStream;
+    }
 }

package/src/action/response/ReadResult.ts

@@ -47,7 +47,7 @@ export namespace ReadResult {
         path: ConcreteAttributePath;
         value: unknown;
         version: number;
-        tlv: TlvSchema<unknown>;
+        tlv: TlvSchema<unknown>; // TODO: Remove when we also move encoding to the new format
     }
 
     export interface AttributeStatus {

package/src/action/server/AttributeReadResponse.ts

@@ -20,10 +20,10 @@ import {
     GlobalAttributes,
     NodeId,
     Status,
+    StatusCode,
     StatusResponseError,
     TlvSchema,
 } from "#types";
-import { StatusCode } from "@matter/types";
 
 const logger = Logger.get("AttributeReadResponse");
 

package/src/action/server/AttributeWriteResponse.ts

@@ -9,7 +9,7 @@ import { AttributeTypeProtocol, ClusterProtocol, EndpointProtocol, NodeProtocol
 import { Write } from "#action/request/Write.js";
 import { WriteResult } from "#action/response/WriteResult.js";
 import { AccessControl } from "#action/server/AccessControl.js";
-import { DataResponse, FallbackLimits, WildcardPathFlagsCodec } from "#action/server/DataResponse.js";
+import { DataResponse, FallbackLimits } from "#action/server/DataResponse.js";
 import { Diagnostic, InternalError, Logger } from "#general";
 import { AttributeModel, DataModelPath, ElementTag, FabricIndex as FabricIndexField } from "#model";
 import {
@@ -39,7 +39,6 @@ export class AttributeWriteResponse<
     #currentEndpoint?: EndpointProtocol;
     #currentCluster?: ClusterProtocol;
     #previousProcessedAttributePath?: WriteResult.ConcreteAttributePath;
-    #wildcardPathFlags = 0;
 
     // Count how many attribute status (on error) and attribute values (on success) we have emitted
     #statusCount = 0;
@@ -101,15 +100,12 @@ export class AttributeWriteResponse<
      * Validate a wildcard path and update internal state.
      */
     async #processWildcard(path: AttributePath, value: TlvStream) {
-        const { nodeId, endpointId, wildcardPathFlags } = path;
+        const { nodeId, endpointId } = path;
 
         if (nodeId !== undefined && nodeId !== this.nodeId) {
             return;
         }
 
-        // TODO clarify isf that's needed or not
-        this.#wildcardPathFlags = wildcardPathFlags ? WildcardPathFlagsCodec.encode(wildcardPathFlags) : 0;
-
         // TODO: Add Group handling and validation
         /*
         if (isGroupSession && endpointId !== undefined) {
@@ -248,8 +244,6 @@ export class AttributeWriteResponse<
      * Emits previous chunk if it exists and was not for this endpoint.  This means that our chunk size is one endpoint
      * worth of data, except for the initial error chunk if there are path errors.
      *
-     * {@link this.#wildcardPathFlags} to numeric bitmap must be set prior to invocation.
-     *
      * TODO - skip endpoints for which subject is unauthorized as optimization
      */
     #writeEndpointForWildcard(endpoint: EndpointProtocol, path: AttributePath, value: TlvStream) {
@@ -261,10 +255,6 @@ export class AttributeWriteResponse<
             );
         }
 
-        if (endpoint.wildcardPathFlags & this.#wildcardPathFlags) {
-            return; // TODO ???
-        }
-
         if (this.#currentEndpoint !== endpoint) {
             this.#currentEndpoint = endpoint;
             this.#currentCluster = undefined;
@@ -284,10 +274,6 @@ export class AttributeWriteResponse<
      * TODO - skip clusters for which subject is unauthorized
      */
     #writeClusterForWildcard(cluster: ClusterProtocol, path: AttributePath, value: TlvStream) {
-        if (cluster.type.wildcardPathFlags & this.#wildcardPathFlags) {
-            return; // TODO ???
-        }
-
         if (this.#currentCluster !== cluster) {
             this.#currentCluster = cluster;
         }
@@ -313,10 +299,6 @@ export class AttributeWriteResponse<
             return;
         }
 
-        if (attribute.wildcardPathFlags & this.#wildcardPathFlags) {
-            return; // TODO ????
-        }
-
         if (
             !attribute.limits.writable ||
             this.session.authorityAt(attribute.limits.readLevel, this.#guardedCurrentCluster.location) !==