@matter/protocol 0.12.4-alpha.0-20250211-56b2c53a0 → 0.12.4-alpha.0-20250212-b2729c9eb

package/src/action/request/Read.ts

@@ -0,0 +1,356 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { FALLBACK_INTERACTIONMODEL_REVISION } from "#session/Session.js";
+import type {
+    AttributePath,
+    ClusterType,
+    DataVersionFilter,
+    EventFilter,
+    EventPath,
+    GlobalAttributes,
+    ReadRequest,
+} from "#types";
+import { camelize } from "@matter/general";
+import { MalformedRequestError } from "./MalformedRequestError.js";
+import { Specifier } from "./Specifier.js";
+
+/**
+ * A read request formulated using Matter protocol semantics.
+ */
+export interface Read extends ReadRequest {}
+
+/**
+ * Formulate a read request using Matter numeric IDs.
+ */
+export function Read(options: Read.Options): Read;
+
+/**
+ * Formulate a read request with extended options and name-based IDs.
+ */
+export function Read(options: Read.Options, ...selectors: Read.Selector[]): Read;
+
+/**
+ * Formulate a read request with name-based IDs.
+ */
+export function Read(...selectors: Read.Selector[]): Read;
+
+export function Read(optionsOrSelector: Read.Options | Read.Selector, ...selectors: Read.Selector[]): Read {
+    let options;
+    if ("kind" in optionsOrSelector) {
+        selectors = [optionsOrSelector, ...selectors];
+        options = {};
+    } else {
+        options = optionsOrSelector;
+    }
+    let { attributes: attributeRequests, versionFilters, events: eventRequests, eventFilters } = options;
+
+    const result: Read = {
+        isFabricFiltered: options.fabricFilter ?? true,
+        interactionModelRevision: options.interactionModelRevision ?? FALLBACK_INTERACTIONMODEL_REVISION,
+    };
+
+    for (const selector of selectors) {
+        reifySelector(selector);
+    }
+
+    if (!attributeRequests?.length && !eventRequests?.length) {
+        throw new MalformedRequestError(`Read action designates no attributes or events`);
+    }
+
+    if (attributeRequests) {
+        result.attributeRequests = attributeRequests;
+    }
+
+    if (versionFilters) {
+        result.dataVersionFilters = versionFilters;
+    }
+
+    if (eventRequests) {
+        result.eventRequests = eventRequests;
+    }
+
+    if (eventFilters !== undefined) {
+        result.eventFilters = eventFilters;
+    }
+
+    return result;
+
+    function reifySelector(selector: Read.Selector) {
+        switch (selector.kind) {
+            case "attribute":
+                reifyAttributeSelector(selector);
+                break;
+
+            case "event":
+                reifyEventSelector(selector);
+                break;
+
+            default:
+                throw new MalformedRequestError(`Invalid selector kind "${(selector as Read.Selector).kind}"`);
+        }
+    }
+
+    /**
+     * Update "real" ReadRequest fields from our convenience attribute "selector".
+     */
+    function reifyAttributeSelector(selector: Read.AttributeSelector) {
+        const cluster = Specifier.clusterOf(selector);
+        const { endpoint } = selector;
+
+        // Install data version filter if the endpoint reports it has complete version information
+        if (typeof endpoint === "object" && endpoint?.versions && typeof cluster === "object" && cluster !== null) {
+            const version = endpoint.versions?.[camelize(cluster.name)];
+            if (version !== undefined) {
+                const filter = {
+                    path: { endpointId: endpoint.number, clusterId: cluster.id },
+                    dataVersion: version,
+                };
+                if (versionFilters === undefined) {
+                    versionFilters = [filter];
+                } else if (
+                    versionFilters.find(
+                        ({ path: { endpointId, clusterId } }) =>
+                            endpointId === endpoint.number && clusterId === cluster.id,
+                    ) === undefined
+                ) {
+                    versionFilters.push(filter);
+                }
+            }
+        }
+
+        // Configure base AttributePath
+        if (attributeRequests === undefined) {
+            attributeRequests = [];
+        }
+        const prototype: AttributePath = {};
+        if (endpoint !== undefined) {
+            prototype.endpointId = Specifier.endpointIdOf(selector);
+        }
+        if (cluster !== undefined) {
+            prototype.clusterId = cluster.id;
+        }
+
+        // If the attribute is a wildcard we are done
+        let { attributes } = selector;
+        if (attributes === undefined) {
+            attributeRequests.push(prototype);
+            return;
+        }
+
+        // Add concrete attribute requests
+        if (!Array.isArray(attributes)) {
+            attributes = [attributes];
+        }
+        for (const specifier of attributes) {
+            attributeRequests.push({ ...prototype, attributeId: Specifier.attributeFor(cluster, specifier).id });
+        }
+    }
+
+    /**
+     * Update "real" ReadRequest fields from our convenience event "selector"
+     */
+    function reifyEventSelector(selector: Read.EventSelector) {
+        const cluster = Specifier.clusterOf(selector);
+        const { endpoint } = selector;
+
+        // Install event minimum if the endpoint reports ingested events
+        if (typeof endpoint === "object" && endpoint.minEvent !== undefined) {
+            if (eventFilters === undefined) {
+                eventFilters = [{ eventMin: endpoint.minEvent }];
+            }
+        }
+
+        // Configure base EventPath
+        if (eventRequests === undefined) {
+            eventRequests = [];
+        }
+        const prototype: EventPath = {};
+        if (endpoint !== undefined) {
+            prototype.endpointId = Specifier.endpointIdOf(selector);
+        }
+        if (cluster !== undefined) {
+            prototype.clusterId = cluster.id;
+        }
+
+        // If the event is a wildcard we are done
+        let { events } = selector;
+        if (events === undefined) {
+            eventRequests.push(prototype);
+            return;
+        }
+
+        // Add concrete event requests
+        if (!Array.isArray(events)) {
+            events = [events];
+        }
+        for (const specifier of events) {
+            eventRequests.push({ ...prototype, eventId: Specifier.eventFor(cluster, specifier).id });
+        }
+    }
+}
+
+export namespace Read {
+    export interface Options {
+        attributes?: AttributePath[];
+        versionFilters?: DataVersionFilter[];
+        events?: EventPath[];
+        eventFilters?: EventFilter[];
+        fabricFilter?: boolean;
+        interactionModelRevision?: number;
+    }
+
+    export interface Attributes extends Read {
+        attributeRequests: Exclude<Read["attributeRequests"], undefined>;
+    }
+
+    export function isAttribute(request: Read): request is Attributes {
+        return !!request.attributeRequests?.length;
+    }
+
+    export interface Events extends Read {
+        eventRequests: Exclude<Read["eventRequests"], undefined>;
+    }
+
+    export function isEvent(request: Read): request is Events {
+        return !!request.eventRequests?.length;
+    }
+
+    /**
+     * Selects attributes or events to read.
+     */
+    export type Selector<C extends Specifier.Cluster = Specifier.Cluster> =
+        | ({ kind: "attribute" } & AttributeSelector<C>)
+        | ({ kind: "event" } & EventSelector<C>);
+
+    /**
+     * Selects attributes to read.  Limits fields to legal permutations per the Matter specification.
+     */
+    export type AttributeSelector<C extends Specifier.Cluster = Specifier.Cluster> =
+        | AttributeSelector.Concrete<C>
+        | AttributeSelector.FullWildcard
+        | AttributeSelector.Global
+        | AttributeSelector.WildcardEndpoint<C>
+        | AttributeSelector.WildcardAttribute
+        | AttributeSelector.Endpoint;
+
+    /**
+     * Selects events to read.  Limits fields to legal permutations per the Matter specification.
+     */
+    export type EventSelector<C extends Specifier.Cluster = Specifier.Cluster> =
+        | EventSelector.Concrete<C>
+        | EventSelector.FullWildcard
+        | EventSelector.WildcardEndpoint<C>
+        | EventSelector.WildcardEvent
+        | EventSelector.Endpoint;
+
+    export function Attribute<const C extends ClusterType>(
+        selector?: AttributeSelector<C>,
+    ): { kind: "attribute" } & AttributeSelector<C> {
+        return {
+            kind: "attribute",
+            ...selector,
+        };
+    }
+
+    export function Event<const T extends EventSelector>(selector: T): { kind: "event" } & T {
+        return {
+            kind: "event",
+            ...selector,
+        };
+    }
+
+    export interface WildcardFlags {
+        skipRoot?: boolean;
+        skipCustom?: boolean;
+        skipDiagnostics?: boolean;
+        skipGlobals?: boolean;
+        skipAttributeList?: boolean;
+        skipCommandList?: boolean;
+        skipFixed?: boolean;
+        skipChangesOmitted?: boolean;
+    }
+
+    export type GlobalAttributeSpecifier = ClusterType.Attribute | keyof GlobalAttributes<any>;
+
+    export namespace AttributeSelector {
+        export interface Concrete<C extends Specifier.Cluster> {
+            endpoint: Specifier.Endpoint;
+            cluster: C;
+            attributes: Specifier.Attribute<Specifier.ClusterFor<C>> | Specifier.Attribute<Specifier.ClusterFor<C>>[];
+        }
+
+        export interface Wildcard {
+            flags?: WildcardFlags;
+        }
+
+        export interface FullWildcard extends Wildcard {
+            endpoint?: undefined;
+            cluster?: undefined;
+            attributes?: undefined;
+        }
+
+        export interface Global extends Wildcard {
+            endpoint?: Specifier.Endpoint;
+            cluster?: undefined;
+            attributes: GlobalAttributeSpecifier | GlobalAttributeSpecifier[];
+        }
+
+        export interface WildcardEndpoint<C extends Specifier.Cluster> extends Wildcard {
+            endpoint?: undefined;
+            cluster: C;
+            attributes: Specifier.Attribute<Specifier.ClusterFor<C>> | Specifier.Attribute<Specifier.ClusterFor<C>>[];
+        }
+
+        export interface WildcardAttribute extends Wildcard {
+            endpoint?: Specifier.Endpoint;
+            cluster: Specifier.Cluster;
+            attributes?: undefined;
+        }
+
+        export interface Endpoint extends Wildcard {
+            endpoint: Specifier.Endpoint;
+            cluster?: undefined;
+            attributes?: undefined;
+        }
+    }
+
+    export namespace EventSelector {
+        export interface Concrete<C extends Specifier.Cluster> {
+            endpoint: Specifier.Endpoint;
+            cluster: Specifier.Cluster;
+            events: Specifier.Event<Specifier.ClusterFor<C>> | Specifier.Event<Specifier.ClusterFor<C>>[];
+        }
+
+        export interface Wildcard {
+            flags?: WildcardFlags;
+        }
+
+        export interface FullWildcard extends Wildcard {
+            endpoint?: undefined;
+            cluster?: undefined;
+            events?: undefined;
+        }
+
+        export interface WildcardEndpoint<C extends Specifier.Cluster> extends Wildcard {
+            endpoint?: undefined;
+            cluster: Specifier.Cluster;
+            events: Specifier.Event<Specifier.ClusterFor<C>> | Specifier.Event<Specifier.ClusterFor<C>>[];
+        }
+
+        export interface WildcardEvent extends Wildcard {
+            endpoint: Specifier.Endpoint;
+            cluster: Specifier.Cluster;
+            events?: undefined;
+        }
+
+        export interface Endpoint extends Wildcard {
+            endpoint: Specifier.Endpoint;
+            cluster?: undefined;
+            events?: undefined;
+        }
+    }
+}

package/src/action/request/Specifier.ts

@@ -0,0 +1,146 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ClusterType, EndpointNumber, GlobalAttributeNames, GlobalAttributes } from "#types";
+import { MalformedRequestError } from "./MalformedRequestError.js";
+
+const GlobalAttrMap = GlobalAttributes({}) as Record<string, ClusterType.Attribute>;
+
+/**
+ * A "specifier" addresses a specific element of the Matter data model in the context of a request.
+ */
+export namespace Specifier {
+    /**
+     * Clusters we designate with an object to convey structural and type information.  The second form of this union
+     * allows for specification with a host object (such as a ClusterBehavior instance or class).
+     */
+    export type Cluster = ClusterType | { cluster: ClusterType };
+
+    /**
+     * You may address endpoints with a bare ID but the object form allows an "endpoint object" as input and optionally
+     * conveys additional metadata.
+     */
+    export type Endpoint =
+        | EndpointNumber
+        | { number: EndpointNumber; versions?: Record<string, number>; minEvent?: number };
+
+    /**
+     * An attribute specifier may be the name of a cluster attribute or the name of a cluster or global attribute.
+     */
+    export type Attribute<C extends ClusterType = ClusterType> =
+        | ClusterType.Attribute
+        | (string & keyof C["attributes"])
+        | GlobalAttributeNames<any>;
+
+    /**
+     * A command specifier may be the name of a cluster attribute or the name of a cluster command.
+     */
+    export type Command<C extends ClusterType = ClusterType> = ClusterType.Command | (string & keyof C["commands"]);
+
+    /**
+     * An event specifier may be the name of a cluser event or an event object.
+     */
+    export type Event<C extends ClusterType = ClusterType> = ClusterType.Event | (string & keyof C["events"]);
+
+    /**
+     * Extract a cluster type from a cluster specifier type.
+     */
+    export type ClusterFor<T extends Cluster> = T extends ClusterType
+        ? T
+        : T extends { cluster: ClusterType }
+          ? T["cluster"]
+          : never;
+
+    /**
+     * Extract a cluster type from a cluster specifier.
+     */
+    export function clusterFor<const T extends Cluster>(specifier: T) {
+        if ("cluster" in specifier) {
+            return specifier["cluster"] as ClusterFor<T>;
+        }
+        return specifier as ClusterFor<T>;
+    }
+
+    /**
+     * Extract an attribute object from a cluster and attribute specifier.
+     */
+    export function attributeFor(cluster: ClusterType | undefined, specifier: Specifier.Attribute) {
+        if (typeof specifier === "object") {
+            return specifier;
+        }
+
+        if (cluster === undefined) {
+            const attr = GlobalAttrMap[specifier];
+            if (attr === undefined) {
+                throw new MalformedRequestError(`Cannot designate event "${specifier}" without a cluster`);
+            }
+            return attr;
+        }
+
+        const attr = cluster.attributes?.[specifier];
+        if (attr === undefined) {
+            throw new MalformedRequestError(`Cluster ${cluster.name} does not define attribute ${specifier}`);
+        }
+
+        return attr;
+    }
+
+    /**
+     * Extract a command type from a cluster type and command specifier.
+     */
+    export type CommandFor<C extends ClusterType, CMD extends Specifier.Command<C>> = CMD extends string
+        ? C["commands"][CMD]
+        : CMD extends ClusterType.Command
+          ? CMD
+          : never;
+
+    /**
+     * Extract an event object from a cluster and event specifier.
+     */
+    export function eventFor(cluster: ClusterType | undefined, specifier: Specifier.Event) {
+        if (typeof specifier === "object") {
+            return specifier;
+        }
+
+        if (cluster === undefined) {
+            throw new MalformedRequestError(`Cannot designate event "${specifier}" without a cluster`);
+        }
+
+        const event = cluster.events?.[specifier];
+        if (event === undefined) {
+            throw new MalformedRequestError(`Cluster ${cluster.name} does not define event ${specifier}`);
+        }
+
+        return event;
+    }
+
+    /**
+     * Extract the cluster type from a cluster request type.
+     */
+    export type ClusterOf<T extends { cluster?: Cluster }> = T extends { cluster: Specifier.Cluster }
+        ? Specifier.ClusterFor<T["cluster"]>
+        : undefined;
+
+    /**
+     * Extract the cluster type from an element request.
+     */
+    export function clusterOf<const T extends { cluster?: Cluster }>(request: T): ClusterOf<T> {
+        if (request.cluster) {
+            return Specifier.clusterFor(request.cluster) as ClusterOf<T>;
+        }
+        return undefined as ClusterOf<T>;
+    }
+
+    /**
+     * Determine endpoint number for an object with an endpoint specifier.
+     */
+    export function endpointIdOf<const T extends { endpoint?: Endpoint }>(request: T): EndpointNumber | undefined {
+        if (typeof request.endpoint === "number") {
+            return request.endpoint;
+        }
+        return request.endpoint?.number;
+    }
+}

package/src/action/request/Subscribe.ts

@@ -0,0 +1,54 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { UINT16_MAX } from "#general";
+import { MalformedRequestError } from "./MalformedRequestError.js";
+import { Read } from "./Read.js";
+
+/**
+ * Defines a subscription.
+ *
+ * The subscription interval fields are optional as matter.js will set them to appropriate defaults based on physical
+ * attributes of the target device.  If you are unsure of appropriate values do not set them.
+ */
+export interface Subscribe extends Read {
+    keepSubscriptions: boolean;
+    minIntervalFloorSeconds?: number;
+    maxIntervalCeilingSeconds?: number;
+}
+
+export function Subscribe(options: Subscribe.Options): Subscribe {
+    const subscribe = Read(options) as unknown as Subscribe;
+
+    const { keepSubscriptions, minIntervalFloorSeconds, maxIntervalCeilingSeconds } = options;
+    subscribe.keepSubscriptions = keepSubscriptions ?? true;
+
+    if (minIntervalFloorSeconds !== undefined) {
+        if (minIntervalFloorSeconds < 0 || minIntervalFloorSeconds > UINT16_MAX) {
+            throw new MalformedRequestError(`Minimum interval floor ${minIntervalFloorSeconds} is out of range`);
+        }
+        subscribe.minIntervalFloorSeconds = minIntervalFloorSeconds;
+    }
+
+    if (maxIntervalCeilingSeconds !== undefined) {
+        if (maxIntervalCeilingSeconds < 0 || maxIntervalCeilingSeconds > UINT16_MAX) {
+            throw new MalformedRequestError(`Maximum interval ceiling ${maxIntervalCeilingSeconds} is out of range`);
+        }
+        subscribe.maxIntervalCeilingSeconds = maxIntervalCeilingSeconds;
+    }
+
+    return subscribe;
+}
+
+export namespace Subscribe {
+    export interface Options extends Read.Options {
+        keepSubscriptions?: boolean;
+        minIntervalFloorSeconds?: number;
+        maxIntervalCeilingSeconds?: number;
+    }
+}
+
+// TODO - subscribe DSL extending read DSL

package/src/action/request/Write.ts

@@ -0,0 +1,13 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { WriteRequest } from "#types";
+
+export interface Write extends WriteRequest {
+    timeout?: number;
+}
+
+// TODO - write DSL

package/src/action/request/index.ts

@@ -0,0 +1,11 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from "./Invoke.js";
+export * from "./Read.js";
+export * from "./Specifier.js";
+export * from "./Subscribe.js";
+export * from "./Write.js";

package/src/action/response/InvokeResult.ts

@@ -0,0 +1,17 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { Invoke } from "#action/request/Invoke.js";
+import type { CommandData } from "#types";
+import { CancelablePromise } from "@matter/general";
+
+export type InvokeResult<T extends Invoke> = T extends { suppressResponse: true }
+    ? CancelablePromise<void>
+    : AsyncIterable<InvokeResult.Chunk>;
+
+export namespace InvokeResult {
+    export type Chunk = CommandData[];
+}

package/src/action/response/ReadResult.ts

@@ -0,0 +1,89 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type {
+    AttributeId,
+    AttributePath,
+    ClusterId,
+    EndpointNumber,
+    EventId,
+    EventPath,
+    NodeId,
+    Status,
+    StatusCode,
+} from "#types";
+
+/**
+ * Streaming result for a Matter protocol-level read.
+ *
+ * These structures contain data for AttributeReportIB and EventReportIB.  We don't use the deeply-nested native TLV
+ * structure directly for reasons of performance and developer convenience.
+ *
+ * Iteration occurs in chunks for performance reasons.  A chunk is an iterable of reports, one per output attribute or
+ * event.
+ */
+export interface ReadResult<Chunk = ReadResult.Chunk> extends AsyncIterable<ReadResult.Chunk> {}
+
+export namespace ReadResult {
+    export type Chunk = Iterable<Report>;
+
+    export type Report =
+        | AttributeValue
+        | GlobalAttributeStatus
+        | ClusterAttributeStatus
+        | EventValue
+        | GlobalEventStatus
+        | ClusterEventStatus;
+
+    export interface ConcreteAttributePath extends AttributePath {
+        nodeId?: NodeId;
+        endpointId: EndpointNumber;
+        clusterId: ClusterId;
+        attributeId: AttributeId;
+    }
+
+    export interface AttributeValue {
+        kind: "attr-value";
+        path: ConcreteAttributePath;
+        value: unknown;
+    }
+
+    export interface GlobalAttributeStatus {
+        kind: "attr-status";
+        path: ConcreteAttributePath;
+        status: StatusCode;
+    }
+
+    export interface ClusterAttributeStatus {
+        kind: "attr-cluster-status";
+        path: ConcreteAttributePath;
+        clusterStatus: number;
+    }
+
+    export interface ConcreteEventPath extends EventPath {
+        nodeId?: NodeId;
+        endpointId: EndpointNumber;
+        clusterId: ClusterId;
+        eventId: EventId;
+    }
+
+    export interface EventValue {
+        kind: "event-value";
+        path: ConcreteEventPath;
+    }
+
+    export interface GlobalEventStatus {
+        kind: "event-status";
+        path: ConcreteEventPath;
+        status: Status;
+    }
+
+    export interface ClusterEventStatus {
+        kind: "event-cluster-status";
+        path: ConcreteEventPath;
+        clusterStatus: number;
+    }
+}

package/src/action/response/SubscribeResult.ts

@@ -0,0 +1,14 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { SubscribeResponse } from "#types";
+import { ReadResult } from "./ReadResult.js";
+
+export interface SubscribeResult extends AsyncIterator<SubscribeResult.Chunk> {}
+
+export namespace SubscribeResult {
+    export type Chunk = ReadResult.Chunk | SubscribeResponse;
+}