@matter-server/ws-client 0.2.7-alpha.0-20260118-993a1c7 → 0.2.7-alpha.0-20260119-49e7237

package/README.md

@@ -85,6 +85,7 @@ new MatterClient(url: string, wsFactory?: WebSocketFactory)
 - `serverInfo`: Server information (fabric ID, SDK version, etc.)
 - `serverBaseAddress`: The base address extracted from the URL
 - `isProduction`: Whether connected to a production server (for UI purposes)
+- `commandTimeout`: Default timeout for commands in milliseconds (default: 5 minutes). Set to `0` to disable timeouts.
 
 #### Methods
 
@@ -114,6 +115,90 @@ new MatterClient(url: string, wsFactory?: WebSocketFactory)
 - `server_info_updated`: Fired when server info changes
 - `connection_lost`: Fired when connection is lost
 
+### Server Info
+
+The `serverInfo` property contains information about the connected Matter server:
+
+```typescript
+interface ServerInfoMessage {
+    fabric_id: bigint;              // The fabric ID
+    compressed_fabric_id: bigint;   // Compressed fabric ID (global ID)
+    fabric_index?: number;          // The fabric index (OHF Matter Server only)
+    schema_version: number;         // API schema version
+    min_supported_schema_version: number;
+    sdk_version: string;            // Server SDK version string
+    wifi_credentials_set: boolean;  // Whether WiFi credentials are configured
+    thread_credentials_set: boolean; // Whether Thread dataset is configured
+    bluetooth_enabled: boolean;     // Whether BLE commissioning is available
+}
+```
+
+**Note:** The `fabric_index` field is specific to OHF Matter Server and is not available in Python Matter Server. When connecting to Python Matter Server, this field will be undefined.
+
+### Command Timeouts
+
+All commands have a default timeout of 5 minutes (300,000ms) to prevent promises from hanging indefinitely if the server doesn't respond. You can configure this behavior globally or per-call:
+
+```typescript
+import { MatterClient, CommandTimeoutError, DEFAULT_COMMAND_TIMEOUT } from "@matter-server/ws-client";
+
+const client = new MatterClient("ws://localhost:5580/ws");
+
+// Check the default timeout (5 minutes)
+console.log(DEFAULT_COMMAND_TIMEOUT); // 300000
+
+// Change the default timeout for all commands (e.g., 1 minute)
+client.commandTimeout = 60000;
+
+// Disable timeouts entirely (not recommended)
+client.commandTimeout = 0;
+
+// Override timeout for a specific call (e.g., 30 seconds for a quick command)
+await client.deviceCommand(nodeId, 1, 6, "toggle", {}, 30000);
+
+// Use a longer timeout for operations that take time (e.g., 10 minutes for commissioning)
+await client.commissionWithCode("MT:Y3.5UNQO100KA0648G00", false, 600000);
+
+// Handle timeout errors
+try {
+    await client.deviceCommand(nodeId, 1, 6, "toggle");
+} catch (err) {
+    if (err instanceof CommandTimeoutError) {
+        console.log(`Command '${err.command}' timed out after ${err.timeoutMs}ms`);
+    }
+}
+```
+
+All client methods accept an optional `timeout` parameter as their last argument to override the default timeout for that specific call.
+
+### Connection Handling
+
+When the WebSocket connection is closed (either by calling `disconnect()` or due to connection loss), all pending commands are automatically rejected with a `ConnectionClosedError`:
+
+```typescript
+import { MatterClient, ConnectionClosedError } from "@matter-server/ws-client";
+
+const client = new MatterClient("ws://localhost:5580/ws");
+await client.connect();
+
+// Start a long-running command
+const commandPromise = client.commissionWithCode("MT:Y3.5UNQO100KA0648G00", false);
+
+// If the connection is lost or disconnected while the command is pending:
+try {
+    await commandPromise;
+} catch (err) {
+    if (err instanceof ConnectionClosedError) {
+        console.log("Connection was closed while command was pending");
+    }
+}
+
+// Listen for connection loss events
+client.addEventListener("connection_lost", () => {
+    console.log("Connection to server was lost");
+});
+```
+
 ### Other Exports
 
 ```typescript
@@ -126,6 +211,11 @@ import {
     // Exceptions
     MatterError,
     InvalidServerVersion,
+    CommandTimeoutError,
+    ConnectionClosedError,
+
+    // Constants
+    DEFAULT_COMMAND_TIMEOUT,
 
     // Types
     ServerInfoMessage,

package/dist/esm/client.d.ts

@@ -4,8 +4,10 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { Connection, WebSocketFactory } from "./connection.js";
-import { AccessControlEntry, APICommands, BindingTarget, CommissionableNodeData, CommissioningParameters, EventMessage, MatterFabricData, MatterSoftwareVersion, NodePingResult } from "./models/model.js";
+import { AccessControlEntry, APICommands, BindingTarget, CommissionableNodeData, CommissioningParameters, EventMessage, LogLevelResponse, LogLevelString, MatterFabricData, MatterSoftwareVersion, NodePingResult } from "./models/model.js";
 import { MatterNode } from "./models/node.js";
+/** Default timeout for WebSocket commands in milliseconds (5 minutes) */
+export declare const DEFAULT_COMMAND_TIMEOUT: number;
 export declare class MatterClient {
     url: string;
     connection: Connection;
@@ -13,6 +15,8 @@ export declare class MatterClient {
     serverBaseAddress: string;
     /** Whether this client is connected to a production server (optional, for UI purposes) */
     isProduction: boolean;
+    /** Default timeout for commands in milliseconds. Set to 0 to disable timeouts. */
+    commandTimeout: number;
     private result_futures;
     private msgId;
     private eventListeners;
@@ -26,31 +30,70 @@ export declare class MatterClient {
     constructor(url: string, wsFactory?: WebSocketFactory);
     get serverInfo(): import("./models/model.js").ServerInfoMessage;
     addEventListener(event: string, listener: () => void): () => void;
-    commissionWithCode(code: string, networkOnly?: boolean): Promise<MatterNode>;
-    setWifiCredentials(ssid: string, credentials: string): Promise<void>;
-    setThreadOperationalDataset(dataset: string): Promise<void>;
-    openCommissioningWindow(nodeId: number | bigint, timeout?: number, iteration?: number, option?: number, discriminator?: number): Promise<CommissioningParameters>;
-    discoverCommissionableNodes(): Promise<CommissionableNodeData[]>;
-    getMatterFabrics(nodeId: number | bigint): Promise<MatterFabricData[]>;
-    removeMatterFabric(nodeId: number | bigint, fabricIndex: number): Promise<void>;
-    pingNode(nodeId: number | bigint, attempts?: number): Promise<NodePingResult>;
-    getNodeIPAddresses(nodeId: number | bigint, preferCache?: boolean, scoped?: boolean): Promise<string[]>;
-    removeNode(nodeId: number | bigint): Promise<void>;
-    interviewNode(nodeId: number | bigint): Promise<void>;
-    importTestNode(dump: string): Promise<void>;
-    readAttribute(nodeId: number | bigint, attributePath: string | string[]): Promise<Record<string, unknown>>;
-    writeAttribute(nodeId: number | bigint, attributePath: string, value: unknown): Promise<unknown>;
-    checkNodeUpdate(nodeId: number | bigint): Promise<MatterSoftwareVersion | null>;
-    updateNode(nodeId: number | bigint, softwareVersion: number | string): Promise<void>;
-    setACLEntry(nodeId: number | bigint, entry: AccessControlEntry[]): Promise<import("./models/model.js").AttributeWriteResult[] | null>;
-    setNodeBinding(nodeId: number | bigint, endpoint: number, bindings: BindingTarget[]): Promise<import("./models/model.js").AttributeWriteResult[] | null>;
-    deviceCommand(nodeId: number | bigint, endpointId: number, clusterId: number, commandName: string, payload?: Record<string, unknown>): Promise<unknown>;
-    getNodes(onlyAvailable?: boolean): Promise<MatterNode[]>;
-    getNode(nodeId: number | bigint): Promise<MatterNode>;
-    getVendorNames(filterVendors?: number[]): Promise<Record<string, string>>;
-    fetchServerInfo(): Promise<import("./models/model.js").ServerInfoMessage>;
-    setDefaultFabricLabel(label: string | null): Promise<void>;
-    sendCommand<T extends keyof APICommands>(command: T, require_schema: number | undefined, args: APICommands[T]["requestArgs"]): Promise<APICommands[T]["response"]>;
+    commissionWithCode(code: string, networkOnly?: boolean, timeout?: number): Promise<MatterNode>;
+    setWifiCredentials(ssid: string, credentials: string, timeout?: number): Promise<void>;
+    setThreadOperationalDataset(dataset: string, timeout?: number): Promise<void>;
+    openCommissioningWindow(nodeId: number | bigint, windowTimeout?: number, iteration?: number, option?: number, discriminator?: number, timeout?: number): Promise<CommissioningParameters>;
+    discoverCommissionableNodes(timeout?: number): Promise<CommissionableNodeData[]>;
+    getMatterFabrics(nodeId: number | bigint, timeout?: number): Promise<MatterFabricData[]>;
+    removeMatterFabric(nodeId: number | bigint, fabricIndex: number, timeout?: number): Promise<void>;
+    pingNode(nodeId: number | bigint, attempts?: number, timeout?: number): Promise<NodePingResult>;
+    getNodeIPAddresses(nodeId: number | bigint, preferCache?: boolean, scoped?: boolean, timeout?: number): Promise<string[]>;
+    removeNode(nodeId: number | bigint, timeout?: number): Promise<void>;
+    interviewNode(nodeId: number | bigint, timeout?: number): Promise<void>;
+    importTestNode(dump: string, timeout?: number): Promise<void>;
+    readAttribute(nodeId: number | bigint, attributePath: string | string[], timeout?: number): Promise<Record<string, unknown>>;
+    writeAttribute(nodeId: number | bigint, attributePath: string, value: unknown, timeout?: number): Promise<unknown>;
+    checkNodeUpdate(nodeId: number | bigint, timeout?: number): Promise<MatterSoftwareVersion | null>;
+    updateNode(nodeId: number | bigint, softwareVersion: number | string, timeout?: number): Promise<void>;
+    setACLEntry(nodeId: number | bigint, entry: AccessControlEntry[], timeout?: number): Promise<import("./models/model.js").AttributeWriteResult[] | null>;
+    setNodeBinding(nodeId: number | bigint, endpoint: number, bindings: BindingTarget[], timeout?: number): Promise<import("./models/model.js").AttributeWriteResult[] | null>;
+    deviceCommand(nodeId: number | bigint, endpointId: number, clusterId: number, commandName: string, payload?: Record<string, unknown>, timeout?: number): Promise<unknown>;
+    getNodes(onlyAvailable?: boolean, timeout?: number): Promise<MatterNode[]>;
+    getNode(nodeId: number | bigint, timeout?: number): Promise<MatterNode>;
+    getVendorNames(filterVendors?: number[], timeout?: number): Promise<Record<string, string>>;
+    fetchServerInfo(timeout?: number): Promise<import("./models/model.js").ServerInfoMessage>;
+    setDefaultFabricLabel(label: string | null, timeout?: number): Promise<void>;
+    /**
+     * Get the current log levels for console and file logging.
+     * @param timeout Optional command timeout in milliseconds
+     * @returns The current log level configuration
+     */
+    getLogLevel(timeout?: number): Promise<LogLevelResponse>;
+    /**
+     * Set the log level for console and/or file logging.
+     * Changes are temporary and will be reset when the server restarts.
+     * @param consoleLoglevel Console log level to set (optional)
+     * @param fileLoglevel File log level to set, only applied if file logging is enabled (optional)
+     * @param timeout Optional command timeout in milliseconds
+     * @returns The log level configuration after the change
+     */
+    setLogLevel(consoleLoglevel?: LogLevelString, fileLoglevel?: LogLevelString, timeout?: number): Promise<LogLevelResponse>;
+    /**
+     * Send a command to the Matter server.
+     * @param command The command name
+     * @param require_schema Minimum schema version required (0 for any version)
+     * @param args Command arguments
+     * @param timeout Optional timeout in milliseconds. Defaults to `commandTimeout`. Set to 0 to disable.
+     * @returns Promise that resolves with the command result
+     * @throws Error if the command times out or fails
+     */
+    sendCommand<T extends keyof APICommands>(command: T, require_schema: number | undefined, args: APICommands[T]["requestArgs"], timeout?: number): Promise<APICommands[T]["response"]>;
+    /**
+     * Safely resolve a pending command, ensuring it's only resolved once.
+     * Clears timeout and removes from pending futures before resolving.
+     */
+    private _resolvePendingCommand;
+    /**
+     * Safely reject a pending command, ensuring it's only rejected once.
+     * Clears timeout and removes from pending futures before rejecting.
+     */
+    private _rejectPendingCommand;
+    /**
+     * Reject all pending commands with a ConnectionClosedError.
+     * Called when the connection is closed or lost.
+     */
+    private _rejectAllPendingCommands;
     connect(): Promise<void>;
     disconnect(clearStorage?: boolean): void;
     startListening(): Promise<void>;

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

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"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"}

package/dist/esm/client.js

@@ -4,11 +4,12 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { Connection } from "./connection.js";
-import { InvalidServerVersion } from "./exceptions.js";
+import { CommandTimeoutError, ConnectionClosedError, InvalidServerVersion } from "./exceptions.js";
 import { MatterNode } from "./models/node.js";
 function toNodeKey(nodeId) {
   return String(nodeId);
 }
+const DEFAULT_COMMAND_TIMEOUT = 5 * 60 * 1e3;
 class MatterClient {
   /**
    * Create a new MatterClient.
@@ -28,9 +29,12 @@ class MatterClient {
   serverBaseAddress;
   /** Whether this client is connected to a production server (optional, for UI purposes) */
   isProduction = false;
+  /** Default timeout for commands in milliseconds. Set to 0 to disable timeouts. */
+  commandTimeout = DEFAULT_COMMAND_TIMEOUT;
   // Using 'unknown' for resolve since the actual types vary by command
   result_futures = {};
-  msgId = 0;
+  // Start with random offset for defense-in-depth and easier debugging across sessions
+  msgId = Math.floor(Math.random() * 2147483647);
   eventListeners = {};
   get serverInfo() {
     return this.connection.serverInfo;
@@ -44,131 +48,255 @@ class MatterClient {
       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 commissionWithCode(code, networkOnly = true, timeout) {
+    return await this.sendCommand(
+      "commission_with_code",
+      0,
+      {
+        code,
+        network_only: networkOnly
+      },
+      timeout
+    );
   }
-  async openCommissioningWindow(nodeId, timeout, iteration, option, discriminator) {
-    return await this.sendCommand("open_commissioning_window", 0, {
-      node_id: nodeId,
-      timeout,
-      iteration,
-      option,
-      discriminator
-    });
+  async setWifiCredentials(ssid, credentials, timeout) {
+    await this.sendCommand("set_wifi_credentials", 0, { ssid, credentials }, timeout);
+  }
+  async setThreadOperationalDataset(dataset, timeout) {
+    await this.sendCommand("set_thread_dataset", 0, { dataset }, timeout);
+  }
+  async openCommissioningWindow(nodeId, windowTimeout, iteration, option, discriminator, timeout) {
+    return await this.sendCommand(
+      "open_commissioning_window",
+      0,
+      {
+        node_id: nodeId,
+        timeout: windowTimeout,
+        iteration,
+        option,
+        discriminator
+      },
+      timeout
+    );
   }
-  async discoverCommissionableNodes() {
-    return await this.sendCommand("discover_commissionable_nodes", 0, {});
+  async discoverCommissionableNodes(timeout) {
+    return await this.sendCommand("discover_commissionable_nodes", 0, {}, timeout);
   }
-  async getMatterFabrics(nodeId) {
-    return await this.sendCommand("get_matter_fabrics", 3, { node_id: nodeId });
+  async getMatterFabrics(nodeId, timeout) {
+    return await this.sendCommand("get_matter_fabrics", 3, { node_id: nodeId }, timeout);
   }
-  async removeMatterFabric(nodeId, fabricIndex) {
-    await this.sendCommand("remove_matter_fabric", 3, { node_id: nodeId, fabric_index: fabricIndex });
+  async removeMatterFabric(nodeId, fabricIndex, timeout) {
+    await this.sendCommand("remove_matter_fabric", 3, { node_id: nodeId, fabric_index: fabricIndex }, timeout);
   }
-  async pingNode(nodeId, attempts = 1) {
-    return await this.sendCommand("ping_node", 0, { node_id: nodeId, attempts });
+  async pingNode(nodeId, attempts = 1, timeout) {
+    return await this.sendCommand("ping_node", 0, { node_id: nodeId, attempts }, timeout);
   }
-  async getNodeIPAddresses(nodeId, preferCache, scoped) {
-    return await this.sendCommand("get_node_ip_addresses", 8, {
-      node_id: nodeId,
-      prefer_cache: preferCache,
-      scoped
-    });
+  async getNodeIPAddresses(nodeId, preferCache, scoped, timeout) {
+    return await this.sendCommand(
+      "get_node_ip_addresses",
+      8,
+      {
+        node_id: nodeId,
+        prefer_cache: preferCache,
+        scoped
+      },
+      timeout
+    );
   }
-  async removeNode(nodeId) {
-    await this.sendCommand("remove_node", 0, { node_id: nodeId });
+  async removeNode(nodeId, timeout) {
+    await this.sendCommand("remove_node", 0, { node_id: nodeId }, timeout);
   }
-  async interviewNode(nodeId) {
-    await this.sendCommand("interview_node", 0, { node_id: nodeId });
+  async interviewNode(nodeId, timeout) {
+    await this.sendCommand("interview_node", 0, { node_id: nodeId }, timeout);
   }
-  async importTestNode(dump) {
-    await this.sendCommand("import_test_node", 0, { dump });
+  async importTestNode(dump, timeout) {
+    await this.sendCommand("import_test_node", 0, { dump }, timeout);
   }
-  async readAttribute(nodeId, attributePath) {
-    return await this.sendCommand("read_attribute", 0, { node_id: nodeId, attribute_path: attributePath });
+  async readAttribute(nodeId, attributePath, timeout) {
+    return await this.sendCommand("read_attribute", 0, { node_id: nodeId, attribute_path: attributePath }, timeout);
   }
-  async writeAttribute(nodeId, attributePath, value) {
-    return await this.sendCommand("write_attribute", 0, {
-      node_id: nodeId,
-      attribute_path: attributePath,
-      value
-    });
+  async writeAttribute(nodeId, attributePath, value, timeout) {
+    return await this.sendCommand(
+      "write_attribute",
+      0,
+      {
+        node_id: nodeId,
+        attribute_path: attributePath,
+        value
+      },
+      timeout
+    );
   }
-  async checkNodeUpdate(nodeId) {
-    return await this.sendCommand("check_node_update", 10, { node_id: nodeId });
+  async checkNodeUpdate(nodeId, timeout) {
+    return await this.sendCommand("check_node_update", 10, { node_id: nodeId }, timeout);
+  }
+  async updateNode(nodeId, softwareVersion, timeout) {
+    await this.sendCommand("update_node", 10, { node_id: nodeId, software_version: softwareVersion }, timeout);
+  }
+  async setACLEntry(nodeId, entry, timeout) {
+    return await this.sendCommand(
+      "set_acl_entry",
+      0,
+      {
+        node_id: nodeId,
+        entry
+      },
+      timeout
+    );
   }
-  async updateNode(nodeId, softwareVersion) {
-    await this.sendCommand("update_node", 10, { node_id: nodeId, software_version: softwareVersion });
+  async setNodeBinding(nodeId, endpoint, bindings, timeout) {
+    return await this.sendCommand(
+      "set_node_binding",
+      0,
+      {
+        node_id: nodeId,
+        endpoint,
+        bindings
+      },
+      timeout
+    );
   }
-  async setACLEntry(nodeId, entry) {
-    return await this.sendCommand("set_acl_entry", 0, {
-      node_id: nodeId,
-      entry
-    });
+  async deviceCommand(nodeId, endpointId, clusterId, commandName, payload = {}, timeout) {
+    return await this.sendCommand(
+      "device_command",
+      0,
+      {
+        node_id: nodeId,
+        endpoint_id: endpointId,
+        cluster_id: clusterId,
+        command_name: commandName,
+        payload,
+        response_type: null
+      },
+      timeout
+    );
   }
-  async setNodeBinding(nodeId, endpoint, bindings) {
-    return await this.sendCommand("set_node_binding", 0, {
-      node_id: nodeId,
-      endpoint,
-      bindings
-    });
+  async getNodes(onlyAvailable = false, timeout) {
+    return await this.sendCommand("get_nodes", 0, { only_available: onlyAvailable }, timeout);
   }
-  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 getNode(nodeId, timeout) {
+    return await this.sendCommand("get_node", 0, { node_id: nodeId }, timeout);
   }
-  async getNodes(onlyAvailable = false) {
-    return await this.sendCommand("get_nodes", 0, { only_available: onlyAvailable });
+  async getVendorNames(filterVendors, timeout) {
+    return await this.sendCommand("get_vendor_names", 0, { filter_vendors: filterVendors }, timeout);
   }
-  async getNode(nodeId) {
-    return await this.sendCommand("get_node", 0, { node_id: nodeId });
+  async fetchServerInfo(timeout) {
+    return await this.sendCommand("server_info", 0, {}, timeout);
   }
-  async getVendorNames(filterVendors) {
-    return await this.sendCommand("get_vendor_names", 0, { filter_vendors: filterVendors });
+  async setDefaultFabricLabel(label, timeout) {
+    await this.sendCommand("set_default_fabric_label", 0, { label }, timeout);
   }
-  async fetchServerInfo() {
-    return await this.sendCommand("server_info", 0, {});
+  /**
+   * Get the current log levels for console and file logging.
+   * @param timeout Optional command timeout in milliseconds
+   * @returns The current log level configuration
+   */
+  async getLogLevel(timeout) {
+    return await this.sendCommand("get_loglevel", 0, {}, timeout);
   }
-  async setDefaultFabricLabel(label) {
-    await this.sendCommand("set_default_fabric_label", 0, { label });
+  /**
+   * Set the log level for console and/or file logging.
+   * Changes are temporary and will be reset when the server restarts.
+   * @param consoleLoglevel Console log level to set (optional)
+   * @param fileLoglevel File log level to set, only applied if file logging is enabled (optional)
+   * @param timeout Optional command timeout in milliseconds
+   * @returns The log level configuration after the change
+   */
+  async setLogLevel(consoleLoglevel, fileLoglevel, timeout) {
+    return await this.sendCommand(
+      "set_loglevel",
+      0,
+      {
+        console_loglevel: consoleLoglevel,
+        file_loglevel: fileLoglevel
+      },
+      timeout
+    );
   }
-  sendCommand(command, require_schema = void 0, args) {
+  /**
+   * Send a command to the Matter server.
+   * @param command The command name
+   * @param require_schema Minimum schema version required (0 for any version)
+   * @param args Command arguments
+   * @param timeout Optional timeout in milliseconds. Defaults to `commandTimeout`. Set to 0 to disable.
+   * @returns Promise that resolves with the command result
+   * @throws Error if the command times out or fails
+   */
+  sendCommand(command, require_schema = void 0, args, timeout = this.commandTimeout) {
     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;
+    if (this.msgId >= Number.MAX_SAFE_INTEGER) {
+      this.msgId = 0;
+    }
+    const messageId = String(++this.msgId);
     const message = {
-      message_id: messageId.toString(),
+      message_id: messageId,
       command,
       args
     };
-    const messagePromise = new Promise((resolve, reject) => {
+    return new Promise((resolve, reject) => {
+      let timeoutId;
+      if (timeout > 0) {
+        timeoutId = setTimeout(() => {
+          const pending = this.result_futures[messageId];
+          if (pending) {
+            if (pending.timeoutId) {
+              clearTimeout(pending.timeoutId);
+            }
+            delete this.result_futures[messageId];
+            reject(new CommandTimeoutError(command, timeout));
+          }
+        }, timeout);
+      }
       this.result_futures[messageId] = {
         resolve,
-        reject
+        reject,
+        timeoutId
       };
       this.connection.sendMessage(message);
     });
-    return messagePromise.finally(() => {
+  }
+  /**
+   * Safely resolve a pending command, ensuring it's only resolved once.
+   * Clears timeout and removes from pending futures before resolving.
+   */
+  _resolvePendingCommand(messageId, result) {
+    const pending = this.result_futures[messageId];
+    if (pending) {
+      if (pending.timeoutId) {
+        clearTimeout(pending.timeoutId);
+      }
       delete this.result_futures[messageId];
-    });
+      pending.resolve(result);
+    }
+  }
+  /**
+   * Safely reject a pending command, ensuring it's only rejected once.
+   * Clears timeout and removes from pending futures before rejecting.
+   */
+  _rejectPendingCommand(messageId, error) {
+    const pending = this.result_futures[messageId];
+    if (pending) {
+      if (pending.timeoutId) {
+        clearTimeout(pending.timeoutId);
+      }
+      delete this.result_futures[messageId];
+      pending.reject(error);
+    }
+  }
+  /**
+   * Reject all pending commands with a ConnectionClosedError.
+   * Called when the connection is closed or lost.
+   */
+  _rejectAllPendingCommands() {
+    const error = new ConnectionClosedError();
+    const pendingIds = Object.keys(this.result_futures);
+    for (const messageId of pendingIds) {
+      this._rejectPendingCommand(messageId, error);
+    }
   }
   async connect() {
     if (this.connection.connected) {
@@ -176,10 +304,14 @@ class MatterClient {
     }
     await this.connection.connect(
       (msg) => this._handleIncomingMessage(msg),
-      () => this.fireEvent("connection_lost")
+      () => {
+        this._rejectAllPendingCommands();
+        this.fireEvent("connection_lost");
+      }
     );
   }
   disconnect(clearStorage = false) {
+    this._rejectAllPendingCommands();
     if (this.connection && this.connection.connected) {
       this.connection.disconnect();
     }
@@ -203,19 +335,11 @@ class MatterClient {
       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];
-      }
+      this._rejectPendingCommand(msg.message_id, new Error(msg.details));
       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];
-      }
+      this._resolvePendingCommand(msg.message_id, msg.result);
       return;
     }
     console.warn("Received message with unknown format", msg);
@@ -281,6 +405,7 @@ class MatterClient {
   }
 }
 export {
+  DEFAULT_COMMAND_TIMEOUT,
   MatterClient
 };
 //# sourceMappingURL=client.js.map