@matter-server/ws-client 0.2.0-alpha.0-00000000-000000000

package/dist/esm/client.js

@@ -0,0 +1,286 @@
+/**
+ * @license
+ * Copyright 2025-2026 Open Home Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Connection } from "./connection.js";
+import { InvalidServerVersion } from "./exceptions.js";
+import { MatterNode } from "./models/node.js";
+function toNodeKey(nodeId) {
+  return String(nodeId);
+}
+class MatterClient {
+  /**
+   * Create a new MatterClient.
+   * @param url WebSocket URL to connect to
+   * @param wsFactory Optional factory function to create WebSocket instances.
+   *                  For Node.js, pass: (url) => new WebSocket(url) from the 'ws' package.
+   *                  For browser, leave undefined to use native WebSocket.
+   */
+  constructor(url, wsFactory) {
+    this.url = url;
+    this.url = url;
+    this.connection = new Connection(this.url, wsFactory);
+    this.serverBaseAddress = this.url.split("://")[1].split(":")[0] || "";
+  }
+  connection;
+  nodes = {};
+  serverBaseAddress;
+  /** Whether this client is connected to a production server (optional, for UI purposes) */
+  isProduction = false;
+  // Using 'unknown' for resolve since the actual types vary by command
+  result_futures = {};
+  msgId = 0;
+  eventListeners = {};
+  get serverInfo() {
+    return this.connection.serverInfo;
+  }
+  addEventListener(event, listener) {
+    if (!this.eventListeners[event]) {
+      this.eventListeners[event] = [];
+    }
+    this.eventListeners[event].push(listener);
+    return () => {
+      this.eventListeners[event] = this.eventListeners[event].filter((l) => l !== listener);
+    };
+  }
+  async commissionWithCode(code, networkOnly = true) {
+    return await this.sendCommand("commission_with_code", 0, {
+      code,
+      network_only: networkOnly
+    });
+  }
+  async setWifiCredentials(ssid, credentials) {
+    await this.sendCommand("set_wifi_credentials", 0, { ssid, credentials });
+  }
+  async setThreadOperationalDataset(dataset) {
+    await this.sendCommand("set_thread_dataset", 0, { dataset });
+  }
+  async openCommissioningWindow(nodeId, timeout, iteration, option, discriminator) {
+    return await this.sendCommand("open_commissioning_window", 0, {
+      node_id: nodeId,
+      timeout,
+      iteration,
+      option,
+      discriminator
+    });
+  }
+  async discoverCommissionableNodes() {
+    return await this.sendCommand("discover_commissionable_nodes", 0, {});
+  }
+  async getMatterFabrics(nodeId) {
+    return await this.sendCommand("get_matter_fabrics", 3, { node_id: nodeId });
+  }
+  async removeMatterFabric(nodeId, fabricIndex) {
+    await this.sendCommand("remove_matter_fabric", 3, { node_id: nodeId, fabric_index: fabricIndex });
+  }
+  async pingNode(nodeId, attempts = 1) {
+    return await this.sendCommand("ping_node", 0, { node_id: nodeId, attempts });
+  }
+  async getNodeIPAddresses(nodeId, preferCache, scoped) {
+    return await this.sendCommand("get_node_ip_addresses", 8, {
+      node_id: nodeId,
+      prefer_cache: preferCache,
+      scoped
+    });
+  }
+  async removeNode(nodeId) {
+    await this.sendCommand("remove_node", 0, { node_id: nodeId });
+  }
+  async interviewNode(nodeId) {
+    await this.sendCommand("interview_node", 0, { node_id: nodeId });
+  }
+  async importTestNode(dump) {
+    await this.sendCommand("import_test_node", 0, { dump });
+  }
+  async readAttribute(nodeId, attributePath) {
+    return await this.sendCommand("read_attribute", 0, { node_id: nodeId, attribute_path: attributePath });
+  }
+  async writeAttribute(nodeId, attributePath, value) {
+    return await this.sendCommand("write_attribute", 0, {
+      node_id: nodeId,
+      attribute_path: attributePath,
+      value
+    });
+  }
+  async checkNodeUpdate(nodeId) {
+    return await this.sendCommand("check_node_update", 10, { node_id: nodeId });
+  }
+  async updateNode(nodeId, softwareVersion) {
+    await this.sendCommand("update_node", 10, { node_id: nodeId, software_version: softwareVersion });
+  }
+  async setACLEntry(nodeId, entry) {
+    return await this.sendCommand("set_acl_entry", 0, {
+      node_id: nodeId,
+      entry
+    });
+  }
+  async setNodeBinding(nodeId, endpoint, bindings) {
+    return await this.sendCommand("set_node_binding", 0, {
+      node_id: nodeId,
+      endpoint,
+      bindings
+    });
+  }
+  async deviceCommand(nodeId, endpointId, clusterId, commandName, payload = {}) {
+    return await this.sendCommand("device_command", 0, {
+      node_id: nodeId,
+      endpoint_id: endpointId,
+      cluster_id: clusterId,
+      command_name: commandName,
+      payload,
+      response_type: null
+    });
+  }
+  async getNodes(onlyAvailable = false) {
+    return await this.sendCommand("get_nodes", 0, { only_available: onlyAvailable });
+  }
+  async getNode(nodeId) {
+    return await this.sendCommand("get_node", 0, { node_id: nodeId });
+  }
+  async getVendorNames(filterVendors) {
+    return await this.sendCommand("get_vendor_names", 0, { filter_vendors: filterVendors });
+  }
+  async fetchServerInfo() {
+    return await this.sendCommand("server_info", 0, {});
+  }
+  async setDefaultFabricLabel(label) {
+    await this.sendCommand("set_default_fabric_label", 0, { label });
+  }
+  sendCommand(command, require_schema = void 0, args) {
+    if (require_schema && this.serverInfo.schema_version < require_schema) {
+      throw new InvalidServerVersion(
+        `Command not available due to incompatible server version. Update the Matter Server to a version that supports at least api schema ${require_schema}.`
+      );
+    }
+    const messageId = ++this.msgId;
+    const message = {
+      message_id: messageId.toString(),
+      command,
+      args
+    };
+    const messagePromise = new Promise((resolve, reject) => {
+      this.result_futures[messageId] = {
+        resolve,
+        reject
+      };
+      this.connection.sendMessage(message);
+    });
+    return messagePromise.finally(() => {
+      delete this.result_futures[messageId];
+    });
+  }
+  async connect() {
+    if (this.connection.connected) {
+      return;
+    }
+    await this.connection.connect(
+      (msg) => this._handleIncomingMessage(msg),
+      () => this.fireEvent("connection_lost")
+    );
+  }
+  disconnect(clearStorage = false) {
+    if (this.connection && this.connection.connected) {
+      this.connection.disconnect();
+    }
+    if (clearStorage && typeof localStorage !== "undefined") {
+      localStorage.removeItem("matterURL");
+      location.reload();
+    }
+  }
+  async startListening() {
+    await this.connect();
+    const nodesArray = await this.sendCommand("start_listening", 0, {});
+    const nodes = {};
+    for (const node of nodesArray) {
+      nodes[toNodeKey(node.node_id)] = new MatterNode(node);
+    }
+    this.nodes = nodes;
+  }
+  _handleIncomingMessage(msg) {
+    if ("event" in msg) {
+      this._handleEventMessage(msg);
+      return;
+    }
+    if ("error_code" in msg) {
+      const promise = this.result_futures[msg.message_id];
+      if (promise) {
+        promise.reject(new Error(msg.details));
+        delete this.result_futures[msg.message_id];
+      }
+      return;
+    }
+    if ("result" in msg) {
+      const promise = this.result_futures[msg.message_id];
+      if (promise) {
+        promise.resolve(msg.result);
+        delete this.result_futures[msg.message_id];
+      }
+      return;
+    }
+    console.warn("Received message with unknown format", msg);
+  }
+  _handleEventMessage(event) {
+    console.log("Incoming event", event);
+    this.onRawEvent(event);
+    if (event.event === "node_added") {
+      const node = new MatterNode(event.data);
+      this.nodes = { ...this.nodes, [toNodeKey(node.node_id)]: node };
+      this.fireEvent("nodes_changed");
+      return;
+    }
+    if (event.event === "node_removed") {
+      delete this.nodes[toNodeKey(event.data)];
+      this.nodes = { ...this.nodes };
+      this.fireEvent("nodes_changed");
+      return;
+    }
+    if (event.event === "node_updated") {
+      const node = new MatterNode(event.data);
+      this.nodes = { ...this.nodes, [toNodeKey(node.node_id)]: node };
+      this.fireEvent("nodes_changed");
+      return;
+    }
+    if (event.event === "attribute_updated") {
+      const [nodeId, attributeKey, attributeValue] = event.data;
+      const nodeKey = toNodeKey(nodeId);
+      const existingNode = this.nodes[nodeKey];
+      if (existingNode) {
+        const node = new MatterNode(existingNode.data);
+        node.attributes[attributeKey] = attributeValue;
+        this.nodes = { ...this.nodes, [nodeKey]: node };
+        this.fireEvent("nodes_changed");
+      }
+      return;
+    }
+    if (event.event === "server_info_updated") {
+      this.connection.serverInfo = event.data;
+      this.fireEvent("server_info_updated");
+      return;
+    }
+    if (event.event === "server_shutdown") {
+      this.fireEvent("server_shutdown");
+      this.disconnect();
+      return;
+    }
+  }
+  fireEvent(event) {
+    const listeners = this.eventListeners[event];
+    if (listeners) {
+      for (const listener of listeners) {
+        listener();
+      }
+    }
+  }
+  /**
+   * Hook for subclasses to receive raw events.
+   * Override this method to intercept all incoming events.
+   * @param event The raw event message
+   */
+  onRawEvent(_event) {
+  }
+}
+export {
+  MatterClient
+};
+//# sourceMappingURL=client.js.map

package/dist/esm/client.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../src/client.ts"],
+  "mappings": "AAAA;AAAA;AAAA;AAAA;AAAA;AAMA,SAAS,kBAAoC;AAC7C,SAAS,4BAA4B;AAcrC,SAAS,kBAAkB;AAM3B,SAAS,UAAU,QAAiC;AAChD,SAAO,OAAO,MAAM;AACxB;AAEO,MAAM,aAAa;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAmBtB,YACW,KACP,WACF;AAFS;AAGP,SAAK,MAAM;AACX,SAAK,aAAa,IAAI,WAAW,KAAK,KAAK,SAAS;AACpD,SAAK,oBAAoB,KAAK,IAAI,MAAM,KAAK,EAAE,CAAC,EAAE,MAAM,GAAG,EAAE,CAAC,KAAK;AAAA,EACvE;AAAA,EAzBO;AAAA,EACA,QAAoC,CAAC;AAAA,EACrC;AAAA;AAAA,EAEA,eAAwB;AAAA;AAAA,EAEvB,iBACJ,CAAC;AAAA,EACG,QAAQ;AAAA,EACR,iBAAoD,CAAC;AAAA,EAkB7D,IAAI,aAAa;AACb,WAAO,KAAK,WAAW;AAAA,EAC3B;AAAA,EAEA,iBAAiB,OAAe,UAAsB;AAClD,QAAI,CAAC,KAAK,eAAe,KAAK,GAAG;AAC7B,WAAK,eAAe,KAAK,IAAI,CAAC;AAAA,IAClC;AACA,SAAK,eAAe,KAAK,EAAE,KAAK,QAAQ;AACxC,WAAO,MAAM;AACT,WAAK,eAAe,KAAK,IAAI,KAAK,eAAe,KAAK,EAAE,OAAO,OAAK,MAAM,QAAQ;AAAA,IACtF;AAAA,EACJ;AAAA,EAEA,MAAM,mBAAmB,MAAc,cAAc,MAA2B;AAK5E,WAAO,MAAM,KAAK,YAAY,wBAAwB,GAAG;AAAA,MACrD;AAAA,MACA,cAAc;AAAA,IAClB,CAAC;AAAA,EACL;AAAA,EAEA,MAAM,mBAAmB,MAAc,aAAqB;AAExD,UAAM,KAAK,YAAY,wBAAwB,GAAG,EAAE,MAAM,YAAY,CAAC;AAAA,EAC3E;AAAA,EAEA,MAAM,4BAA4B,SAAiB;AAE/C,UAAM,KAAK,YAAY,sBAAsB,GAAG,EAAE,QAAQ,CAAC;AAAA,EAC/D;AAAA,EAEA,MAAM,wBACF,QACA,SACA,WACA,QACA,eACgC;AAGhC,WAAO,MAAM,KAAK,YAAY,6BAA6B,GAAG;AAAA,MAC1D,SAAS;AAAA,MACT;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACJ,CAAC;AAAA,EACL;AAAA,EAEA,MAAM,8BAAiE;AAEnE,WAAO,MAAM,KAAK,YAAY,iCAAiC,GAAG,CAAC,CAAC;AAAA,EACxE;AAAA,EAEA,MAAM,iBAAiB,QAAsD;AAGzE,WAAO,MAAM,KAAK,YAAY,sBAAsB,GAAG,EAAE,SAAS,OAAO,CAAC;AAAA,EAC9E;AAAA,EAEA,MAAM,mBAAmB,QAAyB,aAAqB;AAEnE,UAAM,KAAK,YAAY,wBAAwB,GAAG,EAAE,SAAS,QAAQ,cAAc,YAAY,CAAC;AAAA,EACpG;AAAA,EAEA,MAAM,SAAS,QAAyB,WAAW,GAA4B;AAE3E,WAAO,MAAM,KAAK,YAAY,aAAa,GAAG,EAAE,SAAS,QAAQ,SAAS,CAAC;AAAA,EAC/E;AAAA,EAEA,MAAM,mBAAmB,QAAyB,aAAuB,QAAqC;AAE1G,WAAO,MAAM,KAAK,YAAY,yBAAyB,GAAG;AAAA,MACtD,SAAS;AAAA,MACT,cAAc;AAAA,MACd;AAAA,IACJ,CAAC;AAAA,EACL;AAAA,EAEA,MAAM,WAAW,QAAyB;AAEtC,UAAM,KAAK,YAAY,eAAe,GAAG,EAAE,SAAS,OAAO,CAAC;AAAA,EAChE;AAAA,EAEA,MAAM,cAAc,QAAyB;AAEzC,UAAM,KAAK,YAAY,kBAAkB,GAAG,EAAE,SAAS,OAAO,CAAC;AAAA,EACnE;AAAA,EAEA,MAAM,eAAe,MAAc;AAE/B,UAAM,KAAK,YAAY,oBAAoB,GAAG,EAAE,KAAK,CAAC;AAAA,EAC1D;AAAA,EAEA,MAAM,cAAc,QAAyB,eAAoE;AAE7G,WAAO,MAAM,KAAK,YAAY,kBAAkB,GAAG,EAAE,SAAS,QAAQ,gBAAgB,cAAc,CAAC;AAAA,EACzG;AAAA,EAEA,MAAM,eAAe,QAAyB,eAAuB,OAAkC;AAEnG,WAAO,MAAM,KAAK,YAAY,mBAAmB,GAAG;AAAA,MAChD,SAAS;AAAA,MACT,gBAAgB;AAAA,MAChB;AAAA,IACJ,CAAC;AAAA,EACL;AAAA,EAEA,MAAM,gBAAgB,QAAgE;AAKlF,WAAO,MAAM,KAAK,YAAY,qBAAqB,IAAI,EAAE,SAAS,OAAO,CAAC;AAAA,EAC9E;AAAA,EAEA,MAAM,WAAW,QAAyB,iBAAkC;AAMxE,UAAM,KAAK,YAAY,eAAe,IAAI,EAAE,SAAS,QAAQ,kBAAkB,gBAAgB,CAAC;AAAA,EACpG;AAAA,EAEA,MAAM,YAAY,QAAyB,OAA6B;AACpE,WAAO,MAAM,KAAK,YAAY,iBAAiB,GAAG;AAAA,MAC9C,SAAS;AAAA,MACT;AAAA,IACJ,CAAC;AAAA,EACL;AAAA,EAEA,MAAM,eAAe,QAAyB,UAAkB,UAA2B;AACvF,WAAO,MAAM,KAAK,YAAY,oBAAoB,GAAG;AAAA,MACjD,SAAS;AAAA,MACT;AAAA,MACA;AAAA,IACJ,CAAC;AAAA,EACL;AAAA,EAEA,MAAM,cACF,QACA,YACA,WACA,aACA,UAAmC,CAAC,GACpB;AAChB,WAAO,MAAM,KAAK,YAAY,kBAAkB,GAAG;AAAA,MAC/C,SAAS;AAAA,MACT,aAAa;AAAA,MACb,YAAY;AAAA,MACZ,cAAc;AAAA,MACd;AAAA,MACA,eAAe;AAAA,IACnB,CAAC;AAAA,EACL;AAAA,EAEA,MAAM,SAAS,gBAAgB,OAA8B;AACzD,WAAO,MAAM,KAAK,YAAY,aAAa,GAAG,EAAE,gBAAgB,cAAc,CAAC;AAAA,EACnF;AAAA,EAEA,MAAM,QAAQ,QAA8C;AACxD,WAAO,MAAM,KAAK,YAAY,YAAY,GAAG,EAAE,SAAS,OAAO,CAAC;AAAA,EACpE;AAAA,EAEA,MAAM,eAAe,eAA2D;AAC5E,WAAO,MAAM,KAAK,YAAY,oBAAoB,GAAG,EAAE,gBAAgB,cAAc,CAAC;AAAA,EAC1F;AAAA,EAEA,MAAM,kBAAkB;AACpB,WAAO,MAAM,KAAK,YAAY,eAAe,GAAG,CAAC,CAAC;AAAA,EACtD;AAAA,EAEA,MAAM,sBAAsB,OAAsB;AAC9C,UAAM,KAAK,YAAY,4BAA4B,GAAG,EAAE,MAAM,CAAC;AAAA,EACnE;AAAA,EAEA,YACI,SACA,iBAAqC,QACrC,MACmC;AACnC,QAAI,kBAAkB,KAAK,WAAW,iBAAiB,gBAAgB;AACnE,YAAM,IAAI;AAAA,QACN,qIAC6D,cAAc;AAAA,MAC/E;AAAA,IACJ;AAEA,UAAM,YAAY,EAAE,KAAK;AAEzB,UAAM,UAAU;AAAA,MACZ,YAAY,UAAU,SAAS;AAAA,MAC/B;AAAA,MACA;AAAA,IACJ;AAEA,UAAM,iBAAiB,IAAI,QAAoC,CAAC,SAAS,WAAW;AAEhF,WAAK,eAAe,SAAS,IAAI;AAAA,QAC7B;AAAA,QACA;AAAA,MACJ;AACA,WAAK,WAAW,YAAY,OAAO;AAAA,IACvC,CAAC;AAED,WAAO,eAAe,QAAQ,MAAM;AAChC,aAAO,KAAK,eAAe,SAAS;AAAA,IACxC,CAAC;AAAA,EACL;AAAA,EAEA,MAAM,UAAU;AACZ,QAAI,KAAK,WAAW,WAAW;AAC3B;AAAA,IACJ;AACA,UAAM,KAAK,WAAW;AAAA,MAClB,SAAO,KAAK,uBAAuB,GAAsB;AAAA,MACzD,MAAM,KAAK,UAAU,iBAAiB;AAAA,IAC1C;AAAA,EACJ;AAAA,EAEA,WAAW,eAAe,OAAO;AAE7B,QAAI,KAAK,cAAc,KAAK,WAAW,WAAW;AAC9C,WAAK,WAAW,WAAW;AAAA,IAC/B;AACA,QAAI,gBAAgB,OAAO,iBAAiB,aAAa;AACrD,mBAAa,WAAW,WAAW;AACnC,eAAS,OAAO;AAAA,IACpB;AAAA,EACJ;AAAA,EAEA,MAAM,iBAAiB;AACnB,UAAM,KAAK,QAAQ;AAEnB,UAAM,aAAa,MAAM,KAAK,YAAY,mBAAmB,GAAG,CAAC,CAAC;AAElE,UAAM,QAAoC,CAAC;AAC3C,eAAW,QAAQ,YAAY;AAC3B,YAAM,UAAU,KAAK,OAAO,CAAC,IAAI,IAAI,WAAW,IAAI;AAAA,IACxD;AACA,SAAK,QAAQ;AAAA,EACjB;AAAA,EAEQ,uBAAuB,KAAsB;AACjD,QAAI,WAAW,KAAK;AAChB,WAAK,oBAAoB,GAAG;AAC5B;AAAA,IACJ;AAEA,QAAI,gBAAgB,KAAK;AACrB,YAAM,UAAU,KAAK,eAAe,IAAI,UAAU;AAClD,UAAI,SAAS;AACT,gBAAQ,OAAO,IAAI,MAAM,IAAI,OAAO,CAAC;AACrC,eAAO,KAAK,eAAe,IAAI,UAAU;AAAA,MAC7C;AACA;AAAA,IACJ;AAEA,QAAI,YAAY,KAAK;AACjB,YAAM,UAAU,KAAK,eAAe,IAAI,UAAU;AAClD,UAAI,SAAS;AACT,gBAAQ,QAAQ,IAAI,MAAM;AAC1B,eAAO,KAAK,eAAe,IAAI,UAAU;AAAA,MAC7C;AACA;AAAA,IACJ;AAEA,YAAQ,KAAK,wCAAwC,GAAG;AAAA,EAC5D;AAAA,EAEQ,oBAAoB,OAAqB;AAC7C,YAAQ,IAAI,kBAAkB,KAAK;AAGnC,SAAK,WAAW,KAAK;AAErB,QAAI,MAAM,UAAU,cAAc;AAC9B,YAAM,OAAO,IAAI,WAAW,MAAM,IAAI;AACtC,WAAK,QAAQ,EAAE,GAAG,KAAK,OAAO,CAAC,UAAU,KAAK,OAAO,CAAC,GAAG,KAAK;AAC9D,WAAK,UAAU,eAAe;AAC9B;AAAA,IACJ;AACA,QAAI,MAAM,UAAU,gBAAgB;AAChC,aAAO,KAAK,MAAM,UAAU,MAAM,IAAI,CAAC;AACvC,WAAK,QAAQ,EAAE,GAAG,KAAK,MAAM;AAC7B,WAAK,UAAU,eAAe;AAC9B;AAAA,IACJ;AAEA,QAAI,MAAM,UAAU,gBAAgB;AAChC,YAAM,OAAO,IAAI,WAAW,MAAM,IAAI;AACtC,WAAK,QAAQ,EAAE,GAAG,KAAK,OAAO,CAAC,UAAU,KAAK,OAAO,CAAC,GAAG,KAAK;AAC9D,WAAK,UAAU,eAAe;AAC9B;AAAA,IACJ;AAEA,QAAI,MAAM,UAAU,qBAAqB;AACrC,YAAM,CAAC,QAAQ,cAAc,cAAc,IAAI,MAAM;AACrD,YAAM,UAAU,UAAU,MAAM;AAChC,YAAM,eAAe,KAAK,MAAM,OAAO;AACvC,UAAI,cAAc;AACd,cAAM,OAAO,IAAI,WAAW,aAAa,IAAI;AAC7C,aAAK,WAAW,YAAY,IAAI;AAChC,aAAK,QAAQ,EAAE,GAAG,KAAK,OAAO,CAAC,OAAO,GAAG,KAAK;AAC9C,aAAK,UAAU,eAAe;AAAA,MAClC;AACA;AAAA,IACJ;AAEA,QAAI,MAAM,UAAU,uBAAuB;AACvC,WAAK,WAAW,aAAa,MAAM;AACnC,WAAK,UAAU,qBAAqB;AACpC;AAAA,IACJ;AAEA,QAAI,MAAM,UAAU,mBAAmB;AACnC,WAAK,UAAU,iBAAiB;AAChC,WAAK,WAAW;AAChB;AAAA,IACJ;AAAA,EACJ;AAAA,EAEQ,UAAU,OAAe;AAC7B,UAAM,YAAY,KAAK,eAAe,KAAK;AAC3C,QAAI,WAAW;AACX,iBAAW,YAAY,WAAW;AAC9B,iBAAS;AAAA,MACb;AAAA,IACJ;AAAA,EACJ;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOU,WAAW,QAA4B;AAAA,EAGjD;AACJ;",
+  "names": []
+}

package/dist/esm/connection.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @license
+ * Copyright 2025-2026 Open Home Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { CommandMessage, ServerInfoMessage } from "./models/model.js";
+/**
+ * WebSocket interface that works with both browser WebSocket and Node.js ws library.
+ */
+export interface WebSocketLike {
+    readyState: number;
+    onopen: ((event: unknown) => void) | null;
+    onclose: ((event: unknown) => void) | null;
+    onerror: ((event: unknown) => void) | null;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    send(data: string): void;
+    close(): void;
+}
+export type WebSocketFactory = (url: string) => WebSocketLike;
+export declare class Connection {
+    ws_server_url: string;
+    serverInfo?: ServerInfoMessage;
+    private socket?;
+    private wsFactory;
+    /**
+     * Create a new connection.
+     * @param ws_server_url WebSocket server URL
+     * @param wsFactory Optional factory function to create WebSocket instances.
+     *                  If not provided, uses the global WebSocket constructor.
+     */
+    constructor(ws_server_url: string, wsFactory?: WebSocketFactory);
+    get connected(): boolean;
+    connect(onMessage: (msg: unknown) => void, onConnectionLost: () => void): Promise<void>;
+    disconnect(): void;
+    sendMessage(message: CommandMessage): void;
+}
+export default Connection;
+//# sourceMappingURL=connection.d.ts.map

package/dist/esm/connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../src/connection.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,aAAa;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1C,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IAC3C,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IAC3C,SAAS,EAAE,CAAC,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IACvD,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,MAAM,gBAAgB,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,aAAa,CAAC;AAE9D,qBAAa,UAAU;IAaR,aAAa,EAAE,MAAM;IAZzB,UAAU,CAAC,EAAE,iBAAiB,CAAa;IAElD,OAAO,CAAC,MAAM,CAAC,CAAgB;IAC/B,OAAO,CAAC,SAAS,CAAmB;IAEpC;;;;;OAKG;gBAEQ,aAAa,EAAE,MAAM,EAC5B,SAAS,CAAC,EAAE,gBAAgB;IAMhC,IAAI,SAAS,YAEZ;IAEK,OAAO,CAAC,SAAS,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,EAAE,gBAAgB,EAAE,MAAM,IAAI;IAsC7E,UAAU;IAOV,WAAW,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI;CAO7C;AAED,eAAe,UAAU,CAAC"}

package/dist/esm/connection.js

@@ -0,0 +1,75 @@
+/**
+ * @license
+ * Copyright 2025-2026 Open Home Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { parseBigIntAwareJson, toBigIntAwareJson } from "./json-utils.js";
+class Connection {
+  /**
+   * Create a new connection.
+   * @param ws_server_url WebSocket server URL
+   * @param wsFactory Optional factory function to create WebSocket instances.
+   *                  If not provided, uses the global WebSocket constructor.
+   */
+  constructor(ws_server_url, wsFactory) {
+    this.ws_server_url = ws_server_url;
+    this.ws_server_url = ws_server_url;
+    this.wsFactory = wsFactory ?? ((url) => new WebSocket(url));
+  }
+  serverInfo = void 0;
+  socket;
+  wsFactory;
+  get connected() {
+    return this.socket?.readyState === 1;
+  }
+  async connect(onMessage, onConnectionLost) {
+    if (this.socket) {
+      throw new Error("Already connected");
+    }
+    console.debug("Trying to connect");
+    return new Promise((resolve, reject) => {
+      this.socket = this.wsFactory(this.ws_server_url);
+      this.socket.onopen = () => {
+        console.log("WebSocket Connected");
+      };
+      this.socket.onclose = () => {
+        console.log("WebSocket Closed");
+        onConnectionLost();
+      };
+      this.socket.onerror = (error) => {
+        console.error("WebSocket Error: ", error);
+        reject(new Error("WebSocket Error"));
+      };
+      this.socket.onmessage = (event) => {
+        const dataStr = typeof event.data === "string" ? event.data : String(event.data);
+        const data = parseBigIntAwareJson(dataStr);
+        console.log("WebSocket OnMessage", data);
+        if (!this.serverInfo) {
+          this.serverInfo = data;
+          resolve();
+          return;
+        }
+        onMessage(data);
+      };
+    });
+  }
+  disconnect() {
+    if (this.socket) {
+      this.socket.close();
+      this.socket = void 0;
+    }
+  }
+  sendMessage(message) {
+    if (!this.socket) {
+      throw new Error("Not connected");
+    }
+    console.log("WebSocket send message", message);
+    this.socket.send(toBigIntAwareJson(message));
+  }
+}
+var connection_default = Connection;
+export {
+  Connection,
+  connection_default as default
+};
+//# sourceMappingURL=connection.js.map

package/dist/esm/connection.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../src/connection.ts"],
+  "mappings": "AAAA;AAAA;AAAA;AAAA;AAAA;AAMA,SAAS,sBAAsB,yBAAyB;AAkBjD,MAAM,WAAW;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAYpB,YACW,eACP,WACF;AAFS;AAGP,SAAK,gBAAgB;AACrB,SAAK,YAAY,cAAc,SAAO,IAAI,UAAU,GAAG;AAAA,EAC3D;AAAA,EAjBO,aAAiC;AAAA,EAEhC;AAAA,EACA;AAAA,EAgBR,IAAI,YAAY;AACZ,WAAO,KAAK,QAAQ,eAAe;AAAA,EACvC;AAAA,EAEA,MAAM,QAAQ,WAAmC,kBAA8B;AAC3E,QAAI,KAAK,QAAQ;AACb,YAAM,IAAI,MAAM,mBAAmB;AAAA,IACvC;AAEA,YAAQ,MAAM,mBAAmB;AAEjC,WAAO,IAAI,QAAc,CAAC,SAAS,WAAW;AAC1C,WAAK,SAAS,KAAK,UAAU,KAAK,aAAa;AAE/C,WAAK,OAAO,SAAS,MAAM;AACvB,gBAAQ,IAAI,qBAAqB;AAAA,MACrC;AAEA,WAAK,OAAO,UAAU,MAAM;AACxB,gBAAQ,IAAI,kBAAkB;AAC9B,yBAAiB;AAAA,MACrB;AAEA,WAAK,OAAO,UAAU,WAAS;AAC3B,gBAAQ,MAAM,qBAAqB,KAAK;AACxC,eAAO,IAAI,MAAM,iBAAiB,CAAC;AAAA,MACvC;AAEA,WAAK,OAAO,YAAY,CAAC,UAA6B;AAClD,cAAM,UAAU,OAAO,MAAM,SAAS,WAAW,MAAM,OAAO,OAAO,MAAM,IAAI;AAC/E,cAAM,OAAO,qBAAqB,OAAO;AACzC,gBAAQ,IAAI,uBAAuB,IAAI;AACvC,YAAI,CAAC,KAAK,YAAY;AAClB,eAAK,aAAa;AAClB,kBAAQ;AACR;AAAA,QACJ;AACA,kBAAU,IAAI;AAAA,MAClB;AAAA,IACJ,CAAC;AAAA,EACL;AAAA,EAEA,aAAa;AACT,QAAI,KAAK,QAAQ;AACb,WAAK,OAAO,MAAM;AAClB,WAAK,SAAS;AAAA,IAClB;AAAA,EACJ;AAAA,EAEA,YAAY,SAA+B;AACvC,QAAI,CAAC,KAAK,QAAQ;AACd,YAAM,IAAI,MAAM,eAAe;AAAA,IACnC;AACA,YAAQ,IAAI,0BAA0B,OAAO;AAC7C,SAAK,OAAO,KAAK,kBAAkB,OAAO,CAAC;AAAA,EAC/C;AACJ;AAEA,IAAO,qBAAQ;",
+  "names": []
+}

package/dist/esm/exceptions.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @license
+ * Copyright 2025-2026 Open Home Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export declare class MatterError extends Error {
+}
+export declare class InvalidServerVersion extends MatterError {
+}
+//# sourceMappingURL=exceptions.d.ts.map

package/dist/esm/exceptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exceptions.d.ts","sourceRoot":"","sources":["../../src/exceptions.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,qBAAa,WAAY,SAAQ,KAAK;CAAG;AAEzC,qBAAa,oBAAqB,SAAQ,WAAW;CAAG"}

package/dist/esm/exceptions.js

@@ -0,0 +1,14 @@
+/**
+ * @license
+ * Copyright 2025-2026 Open Home Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ */
+class MatterError extends Error {
+}
+class InvalidServerVersion extends MatterError {
+}
+export {
+  InvalidServerVersion,
+  MatterError
+};
+//# sourceMappingURL=exceptions.js.map

package/dist/esm/exceptions.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../src/exceptions.ts"],
+  "mappings": "AAAA;AAAA;AAAA;AAAA;AAAA;AAMO,MAAM,oBAAoB,MAAM;AAAC;AAEjC,MAAM,6BAA6B,YAAY;AAAC;",
+  "names": []
+}

package/dist/esm/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @license
+ * Copyright 2025-2026 Open Home Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * @matter-server/ws-client - WebSocket client library for Matter server
+ */
+export * from "./client.js";
+export * from "./connection.js";
+export * from "./exceptions.js";
+export * from "./json-utils.js";
+export * from "./models/model.js";
+export * from "./models/node.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AAGH,cAAc,aAAa,CAAC;AAG5B,cAAc,iBAAiB,CAAC;AAGhC,cAAc,iBAAiB,CAAC;AAGhC,cAAc,iBAAiB,CAAC;AAGhC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC"}

package/dist/esm/index.js

@@ -0,0 +1,12 @@
+/**
+ * @license
+ * Copyright 2025-2026 Open Home Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export * from "./client.js";
+export * from "./connection.js";
+export * from "./exceptions.js";
+export * from "./json-utils.js";
+export * from "./models/model.js";
+export * from "./models/node.js";
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../src/index.ts"],
+  "mappings": "AAAA;AAAA;AAAA;AAAA;AAAA;AAWA,cAAc;AAGd,cAAc;AAGd,cAAc;AAGd,cAAc;AAGd,cAAc;AACd,cAAc;",
+  "names": []
+}

package/dist/esm/json-utils.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @license
+ * Copyright 2025-2026 Open Home Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Serialize to JSON with BigInt support.
+ * - BigInt values within safe integer range are converted to numbers
+ * - Large BigInt values are output as raw decimal numbers (not quoted strings)
+ * Use this for outgoing WebSocket messages and displaying values.
+ */
+export declare function toBigIntAwareJson(value: unknown, spaces?: number): string;
+/**
+ * Parse JSON with BigInt support for large numbers that exceed JavaScript precision.
+ * Numbers with 15+ digits that exceed MAX_SAFE_INTEGER are converted to BigInt.
+ * Use this for incoming WebSocket messages.
+ */
+export declare function parseBigIntAwareJson(json: string): unknown;
+//# sourceMappingURL=json-utils.d.ts.map

package/dist/esm/json-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-utils.d.ts","sourceRoot":"","sources":["../../src/json-utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAWH;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CA2BzE;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAmB1D"}

package/dist/esm/json-utils.js

@@ -0,0 +1,50 @@
+/**
+ * @license
+ * Copyright 2025-2026 Open Home Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const BIGINT_MARKER = "__BIGINT__";
+function toBigIntAwareJson(value, spaces) {
+  const replacements = new Array();
+  let result = JSON.stringify(
+    value,
+    (_key, val) => {
+      if (typeof val === "bigint") {
+        if (val > Number.MAX_SAFE_INTEGER) {
+          replacements.push({ from: `"0x${val.toString(16)}"`, to: val.toString() });
+          return `0x${val.toString(16)}`;
+        } else {
+          return Number(val);
+        }
+      }
+      return val;
+    },
+    spaces
+  );
+  if (replacements.length > 0) {
+    replacements.forEach(({ from, to }) => {
+      result = result.replaceAll(from, to);
+    });
+  }
+  return result;
+}
+function parseBigIntAwareJson(json) {
+  const processed = json.replace(/([:,[])\s*(\d{15,})(?=[,}\]\s])/g, (match, prefix, number) => {
+    const num = BigInt(number);
+    if (num > Number.MAX_SAFE_INTEGER) {
+      return `${prefix}"${BIGINT_MARKER}${number}"`;
+    }
+    return match;
+  });
+  return JSON.parse(processed, (_key, value) => {
+    if (typeof value === "string" && value.startsWith(BIGINT_MARKER)) {
+      return BigInt(value.slice(BIGINT_MARKER.length));
+    }
+    return value;
+  });
+}
+export {
+  parseBigIntAwareJson,
+  toBigIntAwareJson
+};
+//# sourceMappingURL=json-utils.js.map

package/dist/esm/json-utils.js.map

@@ -0,0 +1,6 @@
+{
+  "version": 3,
+  "sources": ["../../src/json-utils.ts"],
+  "mappings": "AAAA;AAAA;AAAA;AAAA;AAAA;AAaA,MAAM,gBAAgB;AAQf,SAAS,kBAAkB,OAAgB,QAAyB;AACvE,QAAM,eAAe,IAAI,MAAoC;AAC7D,MAAI,SAAS,KAAK;AAAA,IACd;AAAA,IACA,CAAC,MAAM,QAAQ;AACX,UAAI,OAAO,QAAQ,UAAU;AACzB,YAAI,MAAM,OAAO,kBAAkB;AAE/B,uBAAa,KAAK,EAAE,MAAM,MAAM,IAAI,SAAS,EAAE,CAAC,KAAK,IAAI,IAAI,SAAS,EAAE,CAAC;AACzE,iBAAO,KAAK,IAAI,SAAS,EAAE,CAAC;AAAA,QAChC,OAAO;AACH,iBAAO,OAAO,GAAG;AAAA,QACrB;AAAA,MACJ;AACA,aAAO;AAAA,IACX;AAAA,IACA;AAAA,EACJ;AAGA,MAAI,aAAa,SAAS,GAAG;AACzB,iBAAa,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM;AACnC,eAAS,OAAO,WAAW,MAAM,EAAE;AAAA,IACvC,CAAC;AAAA,EACL;AAEA,SAAO;AACX;AAOO,SAAS,qBAAqB,MAAuB;AAIxD,QAAM,YAAY,KAAK,QAAQ,oCAAoC,CAAC,OAAO,QAAQ,WAAW;AAC1F,UAAM,MAAM,OAAO,MAAM;AACzB,QAAI,MAAM,OAAO,kBAAkB;AAC/B,aAAO,GAAG,MAAM,IAAI,aAAa,GAAG,MAAM;AAAA,IAC9C;AACA,WAAO;AAAA,EACX,CAAC;AAGD,SAAO,KAAK,MAAM,WAAW,CAAC,MAAM,UAAU;AAC1C,QAAI,OAAO,UAAU,YAAY,MAAM,WAAW,aAAa,GAAG;AAC9D,aAAO,OAAO,MAAM,MAAM,cAAc,MAAM,CAAC;AAAA,IACnD;AACA,WAAO;AAAA,EACX,CAAC;AACL;",
+  "names": []
+}