@matter/node 0.16.0-alpha.0-20251006-3fe1e7c57 → 0.16.0-alpha.0-20251013-89bb7099d

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

@@ -0,0 +1,137 @@
+/**
+ * @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 { RemoteResponse } from "./RemoteResponse.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", RemoteResponse.describe(response));
+    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": []
+}

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

@@ -0,0 +1,53 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { ValueSupervisor } from "#behavior/supervision/ValueSupervisor.js";
+import { Bytes } from "#general";
+import { DataModelPath } from "#model";
+/**
+ * Api data envelope packages used for request and response.
+ *
+ * This allows for transparent conversion between our three "native" formats -- JS values, serialized JSON and
+ * serialized TLV.
+ */
+export declare class Envelope<T = unknown> {
+    #private;
+    constructor({ supervisor, js, json, tlv }: Envelope.Definition<T>);
+    /**
+     * Validate against the schema.  Casts to appropriate types if necessary.
+     */
+    validate(path?: DataModelPath): void;
+    /**
+     * Convert a {@link js} value to {@link JSON}.
+     *
+     * This acts as a deep copy and optimizes JSON access.  If TLV becomes a priority then we can make this conversion
+     * configurable.
+     */
+    convertToJson(): void;
+    /**
+     * Native JS format.
+     */
+    get js(): T;
+    /**
+     * JSON format.
+     */
+    get json(): string;
+    /**
+     * Serialized TLV format.
+     */
+    get tlv(): AllowSharedBufferSource;
+}
+export declare namespace Envelope {
+    interface Data<T = unknown> {
+        id?: string;
+        js?: T;
+        json?: string;
+        tlv?: Bytes;
+    }
+    interface Definition<T = unknown> extends Data<T> {
+        supervisor: ValueSupervisor;
+    }
+}
+//# sourceMappingURL=Envelope.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Envelope.d.ts","sourceRoot":"","sources":["../../../../../../src/behavior/system/remote/api/Envelope.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0CAA0C,CAAC;AAChF,OAAO,EAAU,KAAK,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAGvC;;;;;GAKG;AACH,qBAAa,QAAQ,CAAC,CAAC,GAAG,OAAO;;gBAMjB,EAAE,UAAU,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC;IAOjE;;OAEG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,aAAa;IAS7B;;;;;OAKG;IACH,aAAa;IAOb;;OAEG;IACH,IAAI,EAAE,MAkBL;IAED;;OAEG;IACH,IAAI,IAAI,WAKP;IAED;;OAEG;IACH,IAAI,GAAG,4BAKN;CACJ;AAED,yBAAiB,QAAQ,CAAC;IACtB,UAAiB,IAAI,CAAC,CAAC,GAAG,OAAO;QAC7B,EAAE,CAAC,EAAE,MAAM,CAAC;QACZ,EAAE,CAAC,EAAE,CAAC,CAAC;QACP,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,GAAG,CAAC,EAAE,KAAK,CAAC;KACf;IAED,UAAiB,UAAU,CAAC,CAAC,GAAG,OAAO,CAAE,SAAQ,IAAI,CAAC,CAAC,CAAC;QACpD,UAAU,EAAE,eAAe,CAAC;KAC/B;CACJ"}

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

@@ -0,0 +1,87 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { LocalActorContext } from "#behavior/context/index.js";
+import { asJson } from "#general";
+import { DataModelPath } from "#model";
+import { StatusResponse, TlvOfModel } from "#types";
+class Envelope {
+  #supervisor;
+  #js;
+  #json;
+  #tlv;
+  constructor({ supervisor, js, json, tlv }) {
+    this.#supervisor = supervisor;
+    this.#js = js;
+    this.#json = json;
+    this.#tlv = tlv;
+  }
+  /**
+   * Validate against the schema.  Casts to appropriate types if necessary.
+   */
+  validate(path) {
+    if (!path) {
+      path = DataModelPath(this.#supervisor.schema.path);
+    }
+    this.#js = this.#supervisor.cast(this.#js);
+    this.#supervisor.validate?.(this.js, LocalActorContext.ReadOnly, { path });
+  }
+  /**
+   * Convert a {@link js} value to {@link JSON}.
+   *
+   * This acts as a deep copy and optimizes JSON access.  If TLV becomes a priority then we can make this conversion
+   * configurable.
+   */
+  convertToJson() {
+    if (this.#js !== void 0) {
+      void this.json;
+    }
+    this.#js = void 0;
+  }
+  /**
+   * Native JS format.
+   */
+  get js() {
+    if (this.#js === void 0) {
+      if (this.#json) {
+        try {
+          this.#js = JSON.parse(this.#json);
+        } catch (e) {
+          if (e instanceof SyntaxError) {
+            throw new StatusResponse.FailureError(`Unparseable JSON: ${e.message}`);
+          }
+          throw e;
+        }
+      } else if (this.#tlv) {
+        this.#js = TlvOfModel(this.#supervisor.schema).decode(this.#tlv);
+      } else {
+        this.#js = null;
+      }
+    }
+    return this.#js;
+  }
+  /**
+   * JSON format.
+   */
+  get json() {
+    if (this.#json === void 0) {
+      this.#json = asJson(this.js);
+    }
+    return this.#json;
+  }
+  /**
+   * Serialized TLV format.
+   */
+  get tlv() {
+    if (this.#tlv === void 0) {
+      this.#tlv = TlvOfModel(this.#supervisor.schema).encode(this.#js);
+    }
+    return this.#tlv;
+  }
+}
+export {
+  Envelope
+};
+//# sourceMappingURL=Envelope.js.map

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

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../../../../../src/behavior/system/remote/api/Envelope.ts"],
+  "mappings": "AAAA;AAAA;AAAA;AAAA;AAAA;AAMA,SAAS,yBAAyB;AAElC,SAAS,cAAqB;AAC9B,SAAS,qBAAqB;AAC9B,SAAS,gBAAgB,kBAAkB;AAQpC,MAAM,SAAsB;AAAA,EAC/B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAEA,YAAY,EAAE,YAAY,IAAI,MAAM,IAAI,GAA2B;AAC/D,SAAK,cAAc;AACnB,SAAK,MAAM;AACX,SAAK,QAAQ;AACb,SAAK,OAAO;AAAA,EAChB;AAAA;AAAA;AAAA;AAAA,EAKA,SAAS,MAAsB;AAC3B,QAAI,CAAC,MAAM;AACP,aAAO,cAAc,KAAK,YAAY,OAAO,IAAI;AAAA,IACrD;AAEA,SAAK,MAAM,KAAK,YAAY,KAAK,KAAK,GAAG;AACzC,SAAK,YAAY,WAAW,KAAK,IAAI,kBAAkB,UAAU,EAAE,KAAK,CAAC;AAAA,EAC7E;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,gBAAgB;AACZ,QAAI,KAAK,QAAQ,QAAW;AACxB,WAAK,KAAK;AAAA,IACd;AACA,SAAK,MAAM;AAAA,EACf;AAAA;AAAA;AAAA;AAAA,EAKA,IAAI,KAAK;AACL,QAAI,KAAK,QAAQ,QAAW;AACxB,UAAI,KAAK,OAAO;AACZ,YAAI;AACA,eAAK,MAAM,KAAK,MAAM,KAAK,KAAK;AAAA,QACpC,SAAS,GAAG;AACR,cAAI,aAAa,aAAa;AAC1B,kBAAM,IAAI,eAAe,aAAa,qBAAqB,EAAE,OAAO,EAAE;AAAA,UAC1E;AACA,gBAAM;AAAA,QACV;AAAA,MACJ,WAAW,KAAK,MAAM;AAClB,aAAK,MAAM,WAAW,KAAK,YAAY,MAAM,EAAE,OAAO,KAAK,IAAI;AAAA,MACnE,OAAO;AACH,aAAK,MAAM;AAAA,MACf;AAAA,IACJ;AACA,WAAO,KAAK;AAAA,EAChB;AAAA;AAAA;AAAA;AAAA,EAKA,IAAI,OAAO;AACP,QAAI,KAAK,UAAU,QAAW;AAC1B,WAAK,QAAQ,OAAO,KAAK,EAAE;AAAA,IAC/B;AACA,WAAO,KAAK;AAAA,EAChB;AAAA;AAAA;AAAA;AAAA,EAKA,IAAI,MAAM;AACN,QAAI,KAAK,SAAS,QAAW;AACzB,WAAK,OAAO,WAAW,KAAK,YAAY,MAAM,EAAE,OAAO,KAAK,GAAG;AAAA,IACnE;AACA,WAAO,KAAK;AAAA,EAChB;AACJ;",
+  "names": []
+}

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

@@ -0,0 +1,28 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Envelope } from "./Envelope.js";
+import { RemoteResponse } from "./RemoteResponse.js";
+/**
+ * The intermediate version of a {@link RemoteResponse}, transformed before transmission.
+ */
+export type LocalResponse = RemoteResponse.OK | RemoteResponse.Change | LocalResponse.Value | LocalResponse.Subscription | LocalResponse.Error;
+export declare namespace LocalResponse {
+    interface Value extends RemoteResponse.Base {
+        kind: "value";
+        value: Envelope;
+    }
+    interface Subscription extends RemoteResponse.Base {
+        kind: "subscription";
+        stream: Stream;
+    }
+    interface Error extends RemoteResponse.Base {
+        kind: "error";
+        error: globalThis.Error;
+    }
+    interface Stream extends AsyncIterableIterator<Envelope<LocalResponse>, void, void> {
+    }
+}
+//# sourceMappingURL=LocalResponse.d.ts.map