@matter/node 0.16.0-alpha.0-20251004-92135c7df → 0.16.0-alpha.0-20251011-d8942d7d5

package/dist/esm/behavior/system/remote/RemoteServer.js

@@ -0,0 +1,98 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Behavior } from "#behavior/Behavior.js";
+import { EndpointInitializer } from "#endpoint/index.js";
+import { AppAddress, ImplementationError, InternalError } from "#general";
+import { DatatypeModel, FieldElement } from "#model";
+import { ServerEndpointInitializer } from "#node/index.js";
+class RemoteServer extends Behavior {
+  static early = true;
+  static interfaceType;
+  async initialize() {
+    if (!(this.env.get(EndpointInitializer) instanceof ServerEndpointInitializer)) {
+      throw new ImplementationError("Remote server is not installed in a ServerNode");
+    }
+    this.reactTo(this.endpoint.lifecycle.online, this.#start);
+    this.reactTo(this.endpoint.lifecycle.offline, this.#onOffline);
+    this.reactTo(this.endpoint.lifecycle.destroying, this.#stop);
+    if (this.state.allowOfflineUse) {
+      await this.#start();
+    }
+  }
+  [Symbol.asyncDispose]() {
+    return this.#stop();
+  }
+  async #start() {
+    if (!this.state.enabled || this.internal.interface) {
+      return;
+    }
+    const interfaceType = this.constructor.interfaceType;
+    if (typeof interfaceType !== "function") {
+      throw new InternalError(`Remote server ${this.constructor.name} does not define a remote interface`);
+    }
+    const address = new AppAddress(this.state.address);
+    const intf = await interfaceType.create(this.endpoint, address);
+    this.internal.interface = intf;
+  }
+  async #stop() {
+    const { interface: intf } = this.internal;
+    if (!intf) {
+      return;
+    }
+    this.internal.interface = void 0;
+    await intf.close();
+  }
+  async #onOffline() {
+    if (!this.state.allowOfflineUse) {
+      await this.#stop();
+    }
+  }
+  static schema = new DatatypeModel(
+    {
+      name: "ApiState",
+      type: "struct"
+    },
+    FieldElement({ name: "address", type: "string" }),
+    FieldElement({ name: "enabled", type: "bool" }),
+    FieldElement({ name: "allowOfflineUse", type: "bool" })
+  );
+}
+((RemoteServer2) => {
+  class Internal {
+    interface;
+  }
+  RemoteServer2.Internal = Internal;
+  class State {
+    /**
+     * The public address at which the service endpoint is accessible.
+     *
+     * The address is a URL.  See subclasses for supported protocols.  An "s" suffix indicates standard TLS support.
+     * The "+unix" suffix indicates that the hostname is a URL encoded path to a UNIX socket.  The socket path may
+     * be absolute or relative to the node's storage root.
+     *
+     * The path portion of the URL generally acts as a namespace prefix for the relevant protocol implementation.
+     * Matter.js replaces the special token `{node}` in the URL with the {@link ServerNode.id}.  This allows for
+     * multiple nodes to participate in a protocol in separate namespaces.
+     */
+    address = "";
+    /**
+     * Set to false to disable this service.
+     */
+    enabled = true;
+    /**
+     * By default the HTTP endpoint is available as soon as the {@link Node} initializes.
+     *
+     * If you set this to false, the HTTP endpoint is only available when the {@link Node}'s Matter networking is
+     * also online.
+     */
+    allowOfflineUse = true;
+  }
+  RemoteServer2.State = State;
+})(RemoteServer || (RemoteServer = {}));
+export {
+  RemoteServer
+};
+//# sourceMappingURL=RemoteServer.js.map

package/dist/esm/behavior/system/remote/RemoteServer.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/behavior/system/remote/RemoteServer.ts"],
+  "mappings": "AAAA;AAAA;AAAA;AAAA;AAAA;AAMA,SAAS,gBAAgB;AACzB,SAAS,2BAA2B;AACpC,SAAS,YAAY,qBAAqB,qBAAqB;AAC/D,SAAS,eAAe,oBAAoB;AAE5C,SAAS,iCAAiC;AAenC,MAAe,qBAAqB,SAAS;AAAA,EAChD,OAAyB,QAAQ;AAAA,EAEjC,OAAO;AAAA,EAKP,MAAe,aAAa;AACxB,QAAI,EAAE,KAAK,IAAI,IAAI,mBAAmB,aAAa,4BAA4B;AAC3E,YAAM,IAAI,oBAAoB,gDAAgD;AAAA,IAClF;AAEA,SAAK,QAAS,KAAK,SAAwB,UAAU,QAAQ,KAAK,MAAM;AACxE,SAAK,QAAS,KAAK,SAAwB,UAAU,SAAS,KAAK,UAAU;AAI7E,SAAK,QAAS,KAAK,SAAwB,UAAU,YAAY,KAAK,KAAK;AAE3E,QAAI,KAAK,MAAM,iBAAiB;AAC5B,YAAM,KAAK,OAAO;AAAA,IACtB;AAAA,EACJ;AAAA,EAEA,CAAU,OAAO,YAAY,IAAI;AAC7B,WAAO,KAAK,MAAM;AAAA,EACtB;AAAA,EAEA,MAAM,SAAS;AACX,QAAI,CAAC,KAAK,MAAM,WAAW,KAAK,SAAS,WAAW;AAChD;AAAA,IACJ;AAEA,UAAM,gBAAiB,KAAK,YAAoC;AAChE,QAAI,OAAQ,kBAA0B,YAAY;AAC9C,YAAM,IAAI,cAAc,iBAAiB,KAAK,YAAY,IAAI,qCAAqC;AAAA,IACvG;AAEA,UAAM,UAAU,IAAI,WAAW,KAAK,MAAM,OAAO;AACjD,UAAM,OAAO,MAAM,cAAc,OAAO,KAAK,UAAwB,OAAO;AAE5E,SAAK,SAAS,YAAY;AAAA,EAC9B;AAAA,EAEA,MAAM,QAAQ;AACV,UAAM,EAAE,WAAW,KAAK,IAAI,KAAK;AACjC,QAAI,CAAC,MAAM;AACP;AAAA,IACJ;AAEA,SAAK,SAAS,YAAY;AAC1B,UAAM,KAAK,MAAM;AAAA,EACrB;AAAA,EAEA,MAAM,aAAa;AACf,QAAI,CAAC,KAAK,MAAM,iBAAiB;AAC7B,YAAM,KAAK,MAAM;AAAA,IACrB;AAAA,EACJ;AAAA,EAEA,OAAyB,SAAS,IAAI;AAAA,IAClC;AAAA,MACI,MAAM;AAAA,MACN,MAAM;AAAA,IACV;AAAA,IAEA,aAAa,EAAE,MAAM,WAAW,MAAM,SAAS,CAAC;AAAA,IAChD,aAAa,EAAE,MAAM,WAAW,MAAM,OAAO,CAAC;AAAA,IAC9C,aAAa,EAAE,MAAM,mBAAmB,MAAM,OAAO,CAAC;AAAA,EAC1D;AACJ;AAAA,CAEO,CAAUA,kBAAV;AAAA,EACI,MAAM,SAAS;AAAA,IAClB;AAAA,EACJ;AAFO,EAAAA,cAAM;AAAA,EAIN,MAAM,MAAM;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAYf,UAAU;AAAA;AAAA;AAAA;AAAA,IAKV,UAAU;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAQV,kBAAkB;AAAA,EACtB;AA1BO,EAAAA,cAAM;AAAA,GALA;",
+  "names": ["RemoteServer"]
+}

package/dist/esm/behavior/system/remote/api/Api.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Agent } from "#endpoint/Agent.js";
+import { Abort } from "#general";
+import { ServerNode } from "#node/ServerNode.js";
+import { ApiPath } from "./ApiPath.js";
+import { ApiResource } from "./ApiResource.js";
+import { LocalResponse } from "./LocalResponse.js";
+import { RemoteRequest } from "./RemoteRequest.js";
+import { RemoteResponse } from "./RemoteResponse.js";
+/**
+ * Common substrate for the network APIs.
+ *
+ * The logical API covers RPC and read/write semantics.  These involve a "/"-separated path and a logical operation
+ * (read, write, invoke, etc.)
+ *
+ * This namespace provides utilities for mapping paths to resources and taking action on the resource.
+ */
+export declare namespace Api {
+    /**
+     * Retrieve the {@link ApiResource} for a path.
+     */
+    function resourceFor(agent: Agent, path: ApiPath): Promise<ApiResource | void>;
+    function log(level: "error" | "info", facility: string, id: string | undefined, ...message: unknown[]): void;
+    function logRequest(facility: string, id: string | undefined, method: string, target: string): void;
+    function logResponse(facility: string, response: RemoteResponse): void;
+    /**
+     * Execute a {@link RemoteRequest}.
+     */
+    function execute(facility: string, node: ServerNode, request: RemoteRequest, signal: Abort.Signal): Promise<LocalResponse>;
+    function errorResponseOf(facility: string, id: string | undefined, error: unknown): LocalResponse;
+}
+//# sourceMappingURL=Api.d.ts.map

package/dist/esm/behavior/system/remote/api/Api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Api.d.ts","sourceRoot":"","sources":["../../../../../../src/behavior/system/remote/api/Api.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAE,KAAK,EAA8C,MAAM,UAAU,CAAC;AAE7E,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEjD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAOrD;;;;;;;GAOG;AACH,yBAAiB,GAAG,CAAC;IACjB;;OAEG;IACH,SAAsB,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAwB1F;IAED,SAAgB,GAAG,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,OAAO,EAAE,OAAO,EAAE,QAM3G;IAED,SAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAElG;IAED,SAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,QAerE;IAED;;OAEG;IACH,SAAsB,OAAO,CACzB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,UAAU,EAChB,OAAO,EAAE,aAAa,EACtB,MAAM,EAAE,KAAK,CAAC,MAAM,GACrB,OAAO,CAAC,aAAa,CAAC,CAmExB;IAED,SAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,EAAE,OAAO,GAAG,aAAa,CAWvG;CACJ"}

package/dist/esm/behavior/system/remote/api/Api.js

@@ -0,0 +1,136 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { asError, Diagnostic, InternalError, Logger } from "#general";
+import { Node } from "#node/Node.js";
+import { StatusResponse, StatusResponseError } from "#types";
+import { ApiPath } from "./ApiPath.js";
+import { EndpointResource } from "./resources/EndpointResource.js";
+import { NodeResource } from "./resources/NodeResource.js";
+import { ServerNodeResource } from "./resources/ServerNodeResource.js";
+const loggers = /* @__PURE__ */ new Map();
+var Api;
+((Api2) => {
+  async function resourceFor(agent, path) {
+    let item;
+    if ("peers" in agent.endpoint) {
+      item = new ServerNodeResource(agent, void 0);
+    } else if (agent.endpoint instanceof Node) {
+      item = new NodeResource(agent, void 0);
+    } else {
+      item = new EndpointResource(agent, void 0);
+    }
+    const breadcrumb = [item];
+    for (const segment of path) {
+      const parent = breadcrumb[breadcrumb.length - 1];
+      const item2 = await parent.childFor(segment);
+      if (!item2) {
+        return;
+      }
+      breadcrumb.push(item2);
+    }
+    return breadcrumb[breadcrumb.length - 1];
+  }
+  Api2.resourceFor = resourceFor;
+  function log(level, facility, id, ...message) {
+    let logger = loggers.get(facility);
+    if (!logger) {
+      loggers.set(facility, logger = Logger.get(facility));
+    }
+    logger[level](Diagnostic.via(id ?? "(anon)"), message);
+  }
+  Api2.log = log;
+  function logRequest(facility, id, method, target) {
+    log("info", facility, id, "\xAB", Diagnostic.strong(method), target);
+  }
+  Api2.logRequest = logRequest;
+  function logResponse(facility, response) {
+    const message = Array("\xBB", response.kind);
+    let level;
+    switch (response.kind) {
+      case "error":
+        message.push(Diagnostic.squash("[", Diagnostic.strong(response.code), "]"));
+        message.push(response.message);
+        level = "error";
+        break;
+      default:
+        level = "info";
+        break;
+    }
+    log(level, facility, response.id, message);
+  }
+  Api2.logResponse = logResponse;
+  async function execute(facility, node, request, signal) {
+    const { target, method, id } = request;
+    logRequest(facility, id, method, target);
+    try {
+      const message = await node.act("remote", async (agent) => {
+        const item = await resourceFor(agent, new ApiPath(target));
+        if (item === void 0) {
+          throw new StatusResponse.NotFoundError(`Target "${target}" not found`);
+        }
+        switch (method) {
+          case "read":
+            const value = item.read();
+            if (value === void 0) {
+              throw new StatusResponse.UnsupportedReadError(`Target "${target}" is not readable`);
+            }
+            value.convertToJson();
+            return {
+              kind: "value",
+              id,
+              // TODO - consider handling serialization here (in agent context) so copy is unnecessary
+              value
+            };
+          case "write":
+            item.write({ js: request.value });
+            return { kind: "ok", id };
+          case "add":
+            item.add({ js: item.value });
+            return { kind: "ok", id };
+          case "delete":
+            item.delete();
+            return { kind: "ok", id };
+          case "invoke": {
+            const value2 = await item.invoke({ js: request.parameters });
+            if (value2?.js === void 0 || value2?.js === null) {
+              return { kind: "ok", id };
+            }
+            value2.convertToJson();
+            return { id, kind: "value", value: value2 };
+          }
+          case "subscribe": {
+            const options = { ...request };
+            for (const field of ["target", "id", "method"]) {
+              delete options[field];
+            }
+            const stream = item.subscribe(signal, {
+              id,
+              js: options
+            });
+            return { kind: "subscription", id, stream };
+          }
+        }
+      });
+      return message;
+    } catch (error) {
+      return errorResponseOf(facility, id, error);
+    }
+  }
+  Api2.execute = execute;
+  function errorResponseOf(facility, id, error) {
+    error = asError(error);
+    if (error instanceof StatusResponseError) {
+      return { kind: "error", id, error };
+    }
+    log("error", facility, id, "Internal error:", error);
+    return { kind: "error", id, error: new InternalError() };
+  }
+  Api2.errorResponseOf = errorResponseOf;
+})(Api || (Api = {}));
+export {
+  Api
+};
+//# sourceMappingURL=Api.js.map

package/dist/esm/behavior/system/remote/api/Api.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../../../../../src/behavior/system/remote/api/Api.ts"],
+  "mappings": "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",
+  "names": ["Api", "item", "value"]
+}

package/dist/esm/behavior/system/remote/api/ApiPath.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { AppAddress } from "#general";
+/**
+ * A logical path in the API.
+ */
+export declare class ApiPath {
+    #private;
+    /**
+     * Create a new path from:
+     *
+     * * An {@link AppAddress#pathname}
+     * * A text path, delimited with "/" with URL encoded segments
+     * * An array of decoded segments
+     *
+     * Ignores path segments that are empty or ".".  ".." resolves up one level.
+     *
+     * So generally normal UNIX/URL semantics.
+     */
+    constructor(path: AppAddress | string | string[]);
+    get isEmpty(): boolean;
+    [Symbol.iterator](): ArrayIterator<string>;
+    slice(start?: number, end?: number): ApiPath;
+    at(path: AppAddress | string | string[]): ApiPath;
+    toString(): string;
+    includes(other: ApiPath): boolean;
+    subpathFor(other: ApiPath): ApiPath | undefined;
+}
+//# sourceMappingURL=ApiPath.d.ts.map

package/dist/esm/behavior/system/remote/api/ApiPath.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ApiPath.d.ts","sourceRoot":"","sources":["../../../../../../src/behavior/system/remote/api/ApiPath.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAe,MAAM,UAAU,CAAC;AAEnD;;GAEG;AACH,qBAAa,OAAO;;IAGhB;;;;;;;;;;OAUG;gBACS,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,MAAM,EAAE;IAuBhD,IAAI,OAAO,YAEV;IAED,CAAC,MAAM,CAAC,QAAQ,CAAC;IAIjB,KAAK,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM;IAIlC,EAAE,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,MAAM,EAAE;IAqBvC,QAAQ;IAIR,QAAQ,CAAC,KAAK,EAAE,OAAO;IAIvB,UAAU,CAAC,KAAK,EAAE,OAAO;CAW5B"}

package/dist/esm/behavior/system/remote/api/ApiPath.js

@@ -0,0 +1,81 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { isDeepEqual } from "#general";
+class ApiPath {
+  #segments = Array();
+  /**
+   * Create a new path from:
+   *
+   * * An {@link AppAddress#pathname}
+   * * A text path, delimited with "/" with URL encoded segments
+   * * An array of decoded segments
+   *
+   * Ignores path segments that are empty or ".".  ".." resolves up one level.
+   *
+   * So generally normal UNIX/URL semantics.
+   */
+  constructor(path) {
+    if (path instanceof URL) {
+      path = path.pathname;
+    }
+    if (!Array.isArray(path)) {
+      path = path.split("/").map(decodeURIComponent);
+    }
+    for (const segment of path) {
+      if (segment === "" || segment === ".") {
+        continue;
+      }
+      if (segment === "..") {
+        this.#segments.pop();
+        continue;
+      }
+      this.#segments.push(segment);
+    }
+  }
+  get isEmpty() {
+    return !this.#segments.length;
+  }
+  [Symbol.iterator]() {
+    return this.#segments[Symbol.iterator]();
+  }
+  slice(start, end) {
+    return new ApiPath(this.#segments.slice(start, end));
+  }
+  at(path) {
+    if (this.isEmpty) {
+      return new ApiPath(path);
+    }
+    if (path instanceof URL) {
+      path = path.pathname;
+    }
+    if (Array.isArray(path)) {
+      path = path.map(encodeURIComponent).join("/");
+    }
+    if (path.startsWith("/")) {
+      return new ApiPath(path);
+    }
+    return new ApiPath(`${this.toString()}/${path}`);
+  }
+  toString() {
+    return `${this.#segments.map(encodeURIComponent).join("/")}`;
+  }
+  includes(other) {
+    return isDeepEqual(this.#segments, other.slice(0, this.#segments.length).#segments);
+  }
+  subpathFor(other) {
+    if (!this.#segments.length) {
+      return other;
+    }
+    if (!this.includes(other)) {
+      return void 0;
+    }
+    return other.slice(this.#segments.length);
+  }
+}
+export {
+  ApiPath
+};
+//# sourceMappingURL=ApiPath.js.map

package/dist/esm/behavior/system/remote/api/ApiPath.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../../../../../src/behavior/system/remote/api/ApiPath.ts"],
+  "mappings": "AAAA;AAAA;AAAA;AAAA;AAAA;AAMA,SAAqB,mBAAmB;AAKjC,MAAM,QAAQ;AAAA,EACjB,YAAY,MAAc;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAa1B,YAAY,MAAsC;AAC9C,QAAI,gBAAgB,KAAK;AACrB,aAAO,KAAK;AAAA,IAChB;AAEA,QAAI,CAAC,MAAM,QAAQ,IAAI,GAAG;AACtB,aAAO,KAAK,MAAM,GAAG,EAAE,IAAI,kBAAkB;AAAA,IACjD;AAEA,eAAW,WAAW,MAAM;AACxB,UAAI,YAAY,MAAM,YAAY,KAAK;AACnC;AAAA,MACJ;AAEA,UAAI,YAAY,MAAM;AAClB,aAAK,UAAU,IAAI;AACnB;AAAA,MACJ;AAEA,WAAK,UAAU,KAAK,OAAO;AAAA,IAC/B;AAAA,EACJ;AAAA,EAEA,IAAI,UAAU;AACV,WAAO,CAAC,KAAK,UAAU;AAAA,EAC3B;AAAA,EAEA,CAAC,OAAO,QAAQ,IAAI;AAChB,WAAO,KAAK,UAAU,OAAO,QAAQ,EAAE;AAAA,EAC3C;AAAA,EAEA,MAAM,OAAgB,KAAc;AAChC,WAAO,IAAI,QAAQ,KAAK,UAAU,MAAM,OAAO,GAAG,CAAC;AAAA,EACvD;AAAA,EAEA,GAAG,MAAsC;AACrC,QAAI,KAAK,SAAS;AACd,aAAO,IAAI,QAAQ,IAAI;AAAA,IAC3B;AAEA,QAAI,gBAAgB,KAAK;AACrB,aAAO,KAAK;AAAA,IAChB;AAEA,QAAI,MAAM,QAAQ,IAAI,GAAG;AACrB,aAAO,KAAK,IAAI,kBAAkB,EAAE,KAAK,GAAG;AAAA,IAChD;AAEA,QAAI,KAAK,WAAW,GAAG,GAAG;AACtB,aAAO,IAAI,QAAQ,IAAI;AAAA,IAC3B;AAGA,WAAO,IAAI,QAAQ,GAAG,KAAK,SAAS,CAAC,IAAI,IAAI,EAAE;AAAA,EACnD;AAAA,EAEA,WAAW;AACP,WAAO,GAAG,KAAK,UAAU,IAAI,kBAAkB,EAAE,KAAK,GAAG,CAAC;AAAA,EAC9D;AAAA,EAEA,SAAS,OAAgB;AACrB,WAAO,YAAY,KAAK,WAAW,MAAM,MAAM,GAAG,KAAK,UAAU,MAAM,EAAE,SAAS;AAAA,EACtF;AAAA,EAEA,WAAW,OAAgB;AACvB,QAAI,CAAC,KAAK,UAAU,QAAQ;AACxB,aAAO;AAAA,IACX;AAEA,QAAI,CAAC,KAAK,SAAS,KAAK,GAAG;AACvB,aAAO;AAAA,IACX;AAEA,WAAO,MAAM,MAAM,KAAK,UAAU,MAAM;AAAA,EAC5C;AACJ;",
+  "names": []
+}

package/dist/esm/behavior/system/remote/api/ApiResource.d.ts

@@ -0,0 +1,102 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { RootSupervisor } from "#behavior/supervision/RootSupervisor.js";
+import type { ValueSupervisor } from "#behavior/supervision/ValueSupervisor.js";
+import { Abort, MaybePromise } from "#general";
+import { DataModelPath, Schema } from "#model";
+import { Envelope } from "./Envelope.js";
+import { LocalResponse } from "./LocalResponse.js";
+/**
+ * A node in the logical API tree structure.
+ *
+ * {@link ApiResource}s are ephemeral objects created on-demand as the server navigates paths.
+ */
+export declare abstract class ApiResource {
+    /**
+     * The item's identifier in the logical model path.
+     */
+    abstract readonly id: string;
+    /**
+     * The item's owner, if any.
+     */
+    readonly parent?: ApiResource;
+    /**
+     * Data model path used for diagnostics.
+     */
+    abstract readonly dataModelPath: DataModelPath;
+    /**
+     * Value supervisor, if any.
+     */
+    abstract readonly supervisor?: ValueSupervisor;
+    /**
+     * Data value.
+     */
+    abstract readonly value: unknown;
+    /**
+     * Indicates whether this is an RPC endpoint.
+     */
+    readonly isInvocable: boolean;
+    /**
+     * Indicates whether this is an event endpoint.
+     */
+    readonly isSubscribable: boolean;
+    /**
+     * The {@link ApiResource.Kind} for {@link value}.
+     */
+    abstract readonly valueKind: ApiResource.Kind;
+    constructor(parent: undefined | ApiResource);
+    /**
+     * Retrieve the body of the item.
+     */
+    read(): Envelope<{} | null> | undefined;
+    /**
+     * Create or replace item.
+     */
+    write(_request: Envelope.Data): void;
+    /**
+     * Update item using matter.js patch semantics.
+     */
+    patch(_request: Envelope.Data): MaybePromise<void>;
+    /**
+     * Add a child item of this item.
+     */
+    add(_request: Envelope.Data): MaybePromise<void>;
+    /**
+     * Remove this item.
+     */
+    delete(): MaybePromise<void>;
+    /**
+     * The {@link Schema} for this resource subtree.
+     */
+    get schema(): Schema | undefined;
+    /**
+     * Obtain the appropriate {@link ValueSupervisor} for a {@link Schema} in this subtree.
+     */
+    supervisorFor(schema: Schema): ValueSupervisor;
+    /**
+     * The {@link RootSupervisor} for this resource subtree.
+     */
+    get rootSupervisor(): RootSupervisor | undefined;
+    /**
+     * Execute a procedure.
+     */
+    invoke(_request?: Envelope.Data): Promise<undefined | Envelope>;
+    /**
+     * Subscribe to events.
+     */
+    subscribe(_abort: Abort.Signal, _request?: Envelope.Data): AsyncGenerator<Envelope<LocalResponse>, void, void>;
+    /**
+     * Retrieve a child with the specified ID.
+     */
+    childFor(_id: string): Promise<ApiResource | void>;
+}
+export declare namespace ApiResource {
+    /**
+     * "Kind" values provided in response JSON payloads.
+     */
+    type Kind = "ok" | "node" | "endpoint" | "index" | "cluster" | "attribute" | "field" | "error" | "command" | "response" | "changes";
+}
+//# sourceMappingURL=ApiResource.d.ts.map

package/dist/esm/behavior/system/remote/api/ApiResource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ApiResource.d.ts","sourceRoot":"","sources":["../../../../../../src/behavior/system/remote/api/ApiResource.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0CAA0C,CAAC;AAChF,OAAO,EAAE,KAAK,EAAE,YAAY,EAAuB,MAAM,UAAU,CAAC;AACpE,OAAO,EAAO,aAAa,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACpD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD;;;;GAIG;AACH,8BAAsB,WAAW;IAC7B;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAE7B;;OAEG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAE9B;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IAE/C;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,eAAe,CAAC;IAE/C;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IAEjC;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAS;IAEtC;;OAEG;IACH,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAS;IAEzC;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,IAAI,CAAC;gBAElC,MAAM,EAAE,SAAS,GAAG,WAAW;IAI3C;;OAEG;IACH,IAAI;IAWJ;;OAEG;IACH,KAAK,CAAC,QAAQ,EAAE,QAAQ,CAAC,IAAI,GAAG,IAAI;IAIpC;;OAEG;IACH,KAAK,CAAC,QAAQ,EAAE,QAAQ,CAAC,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC;IAIlD;;OAEG;IACH,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAC,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC;IAIhD;;OAEG;IACH,MAAM,IAAI,YAAY,CAAC,IAAI,CAAC;IAI5B;;OAEG;IACH,IAAI,MAAM,uBAET;IAED;;OAEG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM;IAI5B;;OAEG;IACH,IAAI,cAAc,IAAI,cAAc,GAAG,SAAS,CAE/C;IAED;;OAEG;IACG,MAAM,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,IAAI,GAAG,OAAO,CAAC,SAAS,GAAG,QAAQ,CAAC;IAIrE;;OAEG;IAEI,SAAS,CACZ,MAAM,EAAE,KAAK,CAAC,MAAM,EACpB,QAAQ,CAAC,EAAE,QAAQ,CAAC,IAAI,GACzB,cAAc,CAAC,QAAQ,CAAC,aAAa,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC;IAItD;;OAEG;IACG,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;CAG3D;AAED,yBAAiB,WAAW,CAAC;IACzB;;OAEG;IACH,KAAY,IAAI,GACV,IAAI,GACJ,MAAM,GACN,UAAU,GACV,OAAO,GACP,SAAS,GACT,WAAW,GACX,OAAO,GACP,OAAO,GACP,SAAS,GACT,UAAU,GACV,SAAS,CAAC;CACnB"}

package/dist/esm/behavior/system/remote/api/ApiResource.js

@@ -0,0 +1,103 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { RootSupervisor } from "#behavior/supervision/RootSupervisor.js";
+import { NotImplementedError } from "#general";
+import { any } from "#model";
+import { Envelope } from "./Envelope.js";
+class ApiResource {
+  /**
+   * The item's owner, if any.
+   */
+  parent;
+  /**
+   * Indicates whether this is an RPC endpoint.
+   */
+  isInvocable = false;
+  /**
+   * Indicates whether this is an event endpoint.
+   */
+  isSubscribable = false;
+  constructor(parent) {
+    this.parent = parent;
+  }
+  /**
+   * Retrieve the body of the item.
+   */
+  read() {
+    if (this.value === void 0) {
+      return;
+    }
+    return new Envelope({
+      supervisor: this.supervisor ?? RootSupervisor.for(any),
+      js: this.value
+    });
+  }
+  /**
+   * Create or replace item.
+   */
+  write(_request) {
+    throw new NotImplementedError();
+  }
+  /**
+   * Update item using matter.js patch semantics.
+   */
+  patch(_request) {
+    throw new NotImplementedError();
+  }
+  /**
+   * Add a child item of this item.
+   */
+  add(_request) {
+    throw new NotImplementedError();
+  }
+  /**
+   * Remove this item.
+   */
+  delete() {
+    throw new NotImplementedError();
+  }
+  /**
+   * The {@link Schema} for this resource subtree.
+   */
+  get schema() {
+    return this.supervisor?.schema;
+  }
+  /**
+   * Obtain the appropriate {@link ValueSupervisor} for a {@link Schema} in this subtree.
+   */
+  supervisorFor(schema) {
+    return this.rootSupervisor?.get(schema) ?? RootSupervisor.for(schema);
+  }
+  /**
+   * The {@link RootSupervisor} for this resource subtree.
+   */
+  get rootSupervisor() {
+    return this.parent?.rootSupervisor;
+  }
+  /**
+   * Execute a procedure.
+   */
+  async invoke(_request) {
+    throw new NotImplementedError();
+  }
+  /**
+   * Subscribe to events.
+   */
+  // eslint-disable-next-line require-yield
+  async *subscribe(_abort, _request) {
+    throw new NotImplementedError();
+  }
+  /**
+   * Retrieve a child with the specified ID.
+   */
+  async childFor(_id) {
+    return void 0;
+  }
+}
+export {
+  ApiResource
+};
+//# sourceMappingURL=ApiResource.js.map

package/dist/esm/behavior/system/remote/api/ApiResource.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../../../../../src/behavior/system/remote/api/ApiResource.ts"],
+  "mappings": "AAAA;AAAA;AAAA;AAAA;AAAA;AAMA,SAAS,sBAAsB;AAE/B,SAA8B,2BAA2B;AACzD,SAAS,WAAkC;AAC3C,SAAS,gBAAgB;AAQlB,MAAe,YAAY;AAAA;AAAA;AAAA;AAAA,EASrB;AAAA;AAAA;AAAA;AAAA,EAoBA,cAAuB;AAAA;AAAA;AAAA;AAAA,EAKvB,iBAA0B;AAAA,EAOnC,YAAY,QAAiC;AACzC,SAAK,SAAS;AAAA,EAClB;AAAA;AAAA;AAAA;AAAA,EAKA,OAAO;AACH,QAAI,KAAK,UAAU,QAAW;AAC1B;AAAA,IACJ;AAEA,WAAO,IAAI,SAAS;AAAA,MAChB,YAAY,KAAK,cAAc,eAAe,IAAI,GAAG;AAAA,MACrD,IAAI,KAAK;AAAA,IACb,CAAC;AAAA,EACL;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,UAA+B;AACjC,UAAM,IAAI,oBAAoB;AAAA,EAClC;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,UAA6C;AAC/C,UAAM,IAAI,oBAAoB;AAAA,EAClC;AAAA;AAAA;AAAA;AAAA,EAKA,IAAI,UAA6C;AAC7C,UAAM,IAAI,oBAAoB;AAAA,EAClC;AAAA;AAAA;AAAA;AAAA,EAKA,SAA6B;AACzB,UAAM,IAAI,oBAAoB;AAAA,EAClC;AAAA;AAAA;AAAA;AAAA,EAKA,IAAI,SAAS;AACT,WAAO,KAAK,YAAY;AAAA,EAC5B;AAAA;AAAA;AAAA;AAAA,EAKA,cAAc,QAAgB;AAC1B,WAAO,KAAK,gBAAgB,IAAI,MAAM,KAAK,eAAe,IAAI,MAAM;AAAA,EACxE;AAAA;AAAA;AAAA;AAAA,EAKA,IAAI,iBAA6C;AAC7C,WAAO,KAAK,QAAQ;AAAA,EACxB;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,OAAO,UAAyD;AAClE,UAAM,IAAI,oBAAoB;AAAA,EAClC;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,OAAO,UACH,QACA,UACmD;AACnD,UAAM,IAAI,oBAAoB;AAAA,EAClC;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,SAAS,KAA0C;AACrD,WAAO;AAAA,EACX;AACJ;",
+  "names": []
+}