@matter-server/ws-controller 0.5.7 → 0.5.8

package/src/controller/MatterController.ts

@@ -122,9 +122,10 @@ export class MatterController {
 
             // Check if the nextNodeId needs to be updated based on legacy data
             const lastNodeId = legacyData.nodeData?.last_node_id;
-            if (typeof lastNodeId === "number") {
-                if (config.nextNodeId <= lastNodeId) {
-                    const newNextNodeId = lastNodeId + 10;
+            if (typeof lastNodeId === "number" || typeof lastNodeId === "bigint") {
+                // Compare as BigInt to safely handle both number and bigint types
+                if (BigInt(config.nextNodeId) <= BigInt(lastNodeId)) {
+                    const newNextNodeId = BigInt(lastNodeId) + 10n;
                     logger.info(
                         `Updating nextNodeId from ${config.nextNodeId} to ${newNextNodeId} (legacy last_node_id: ${lastNodeId})`,
                     );

package/src/model/ModelMapper.ts

@@ -15,7 +15,7 @@ import {
     EventModel,
     FeatureMap,
     GeneratedCommandList,
-    MatterModel,
+    Matter,
 } from "@matter/main/model";
 
 type AttributeDetails = { readonly [key: string]: AttributeModel | undefined };
@@ -53,7 +53,7 @@ export type ClusterMapType = {
 // Build the cluster map at module load time
 const clusterMapBuilder: { [key: string]: ClusterMapEntry | undefined } = {};
 
-MatterModel.standard.clusters.forEach(cluster => {
+Matter.clusters.forEach(cluster => {
     if (cluster.id === undefined) {
         return;
     } // Skip clusters without an ID

package/src/server/ConfigStorage.ts

@@ -20,7 +20,7 @@ function sanitizeForLog(key: string, value: unknown): string {
 
 interface ConfigData {
     fabricLabel: string;
-    nextNodeId: number; // formally wrong, should be bigint
+    nextNodeId: number | bigint;
     wifiSsid?: string;
     wifiCredentials?: string;
     threadDataset?: string;
@@ -68,7 +68,7 @@ export class ConfigStorage {
         const fabricLabel = (await this.#configStore.has("fabricLabel"))
             ? await this.#configStore.get<string>("fabricLabel")
             : (this.#env.vars.string("fabricLabel") ?? this.#data.fabricLabel);
-        const nextNodeId = await this.#configStore.get<number>("nextNodeId", this.#data.nextNodeId);
+        const nextNodeId = await this.#configStore.get<number | bigint>("nextNodeId", this.#data.nextNodeId);
 
         const wifiSsid = (await this.#configStore.has("wifiSsid"))
             ? await this.#configStore.get<string>("wifiSsid", "")

package/src/server/Converters.ts

@@ -90,7 +90,7 @@ export function convertWebSocketTagBasedToMatter(
 
     // Handle lists
     if (Array.isArray(value) && model.type === "list") {
-        return value.map(v => convertWebSocketTagBasedToMatter(v, model.members[0], clusterModel));
+        return value.map(v => convertWebSocketTagBasedToMatter(v, model.members.at(0), clusterModel));
     }
 
     // Handle structs - convert numeric keys to camelCased member names
@@ -136,7 +136,7 @@ export function convertCommandDataToMatter(
 
     // Handle lists
     if (Array.isArray(value) && model.type === "list") {
-        return value.map(v => convertCommandDataToMatter(v, model.members[0], clusterModel));
+        return value.map(v => convertCommandDataToMatter(v, model.members.at(0), clusterModel));
     }
 
     // Handle structs - convert numeric keys to camelCased member names
@@ -303,7 +303,7 @@ function convertMatterToWebSocket(
 
         case ConvKind.List:
             return Array.isArray(value)
-                ? value.map(v => convertMatterToWebSocket(v, model.members[0], clusterModel, tagBased))
+                ? value.map(v => convertMatterToWebSocket(v, model.members.at(0), clusterModel, tagBased))
                 : value;
 
         case ConvKind.Struct: {
@@ -527,7 +527,7 @@ export function convertWebsocketDataToMatter(value: any, model: ValueModel): any
             value = parseChipJSON(value);
         }
         if (Array.isArray(value)) {
-            return value.map(v => convertWebsocketDataToMatter(v, model.members[0]));
+            return value.map(v => convertWebsocketDataToMatter(v, model.members.at(0)!));
         }
     }
 

package/src/server/WebSocketControllerHandler.ts

@@ -361,7 +361,6 @@ export class WebSocketControllerHandler implements WebServerHandler {
                 }
             }
         });
-        console.log("send close to clients");
 
         const wss = this.#wss;
         // Wait for the WebSocket server to close properly
@@ -379,7 +378,7 @@ export class WebSocketControllerHandler implements WebServerHandler {
     async #handleWebSocketRequest(
         connId: string,
         data: string,
-    ): Promise<{ response: ErrorResultMessage | SuccessResultMessage<any>; enableListeners?: boolean }> {
+    ): Promise<{ response: ErrorResultMessage | SuccessResultMessage; enableListeners?: boolean }> {
         let messageId: string | undefined;
         try {
             logger.debug(`[${connId}] WebSocket request`, () => data);
@@ -603,7 +602,9 @@ export class WebSocketControllerHandler implements WebServerHandler {
             }
         }
 
-        await this.#config.set({ nextNodeId: nextNodeId + 1 });
+        await this.#config.set({
+            nextNodeId: typeof nextNodeId === "bigint" ? nextNodeId + 1n : nextNodeId + 1,
+        });
 
         const { nodeId } = await this.#commandHandler.commissionNode({
             nodeId: NodeId(nextNodeId),
@@ -657,7 +658,9 @@ export class WebSocketControllerHandler implements WebServerHandler {
                 break;
         }
 
-        await this.#config.set({ nextNodeId: nextNodeId + 1 });
+        await this.#config.set({
+            nextNodeId: typeof nextNodeId === "bigint" ? nextNodeId + 1n : nextNodeId + 1,
+        });
 
         const { nodeId } = await this.#commandHandler.commissionNode(commissionRequest);
 

package/src/tsconfig.json

@@ -1,7 +1,13 @@
 {
     "extends": "../../tools/tsc/tsconfig.lib.json",
     "compilerOptions": {
-        "types": ["globals"]
+        "types": [
+            "globals"
+        ]
     },
-    "references": []
-}
+    "references": [
+        {
+            "path": "../../ws-client/src"
+        }
+    ]
+}

package/src/types/CommandHandler.ts

@@ -211,11 +211,9 @@ export type OpenCommissioningWindowResponse = {
     qrCode: string;
 };
 
-import { AttributesData, MatterNode } from "./WebSocketMessageTypes.js";
+import type { AttributesData, MatterNodeData } from "@matter-server/ws-client";
 
-/** MatterNode details for WebSocket API - re-export from WebSocketMessageTypes */
-export type { AttributesData };
-export type MatterNodeData = MatterNode;
+export type { AttributesData, MatterNodeData };
 
 /**
  * Interface for node command handlers.

package/src/types/WebSocketMessageTypes.ts

@@ -4,465 +4,47 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-export type AttributesData = { [key: string]: unknown };
-
-export interface MatterNode {
-    node_id: number | bigint;
-    date_commissioned: string;
-    last_interview: string;
-    interview_version: number;
-    available: boolean;
-    is_bridge: boolean;
-    attributes: AttributesData;
-    attribute_subscriptions: []; // ???
-    /**
-     * Matter specification version of the node (e.g., "1.2.0", "1.3.0", "1.4.0").
-     * Determined from the SpecificationVersion attribute (0x15) if available,
-     * otherwise estimated from DataModelRevision (0x0) on BasicInformation cluster.
-     * Optional - not available in Python Matter Server.
-     */
-    matter_version?: string;
-}
-
-export interface APICommands {
-    start_listening: {
-        requestArgs: void;
-        response: Array<MatterNode>;
-    };
-    set_default_fabric_label: {
-        requestArgs: {
-            /** Fabric label (null to clear) */
-            label: string | null;
-        };
-        response: null;
-    };
-    diagnostics: {
-        requestArgs: {};
-        response: {
-            info: ServerInfoMessage;
-            nodes: Array<MatterNode>;
-            /** Last 25 node events */
-            events: Array<MatterNodeEvent>;
-        };
-    };
-    server_info: {
-        requestArgs: {};
-        response: ServerInfoMessage;
-    };
-    get_nodes: {
-        requestArgs: {
-            only_available?: boolean;
-        };
-        response: Array<MatterNode>;
-    };
-    get_node: {
-        requestArgs: {
-            node_id: number | bigint; // ????
-        };
-        response: MatterNode; // ????
-    };
-    commission_with_code: {
-        requestArgs: {
-            code: string;
-            network_only?: boolean;
-        };
-        response: MatterNode;
-    };
-    commission_on_network: {
-        requestArgs: {
-            setup_pin_code: number;
-            /** Discovery filter type: 0=None, 1=ShortDiscriminator, 2=LongDiscriminator, 3=VendorId, 4=DeviceType */
-            filter_type?: number;
-            /** Filter value (discriminator, vendor ID, or device type depending on filter_type) */
-            filter?: number;
-            /** Direct IP address for commissioning */
-            ip_addr?: string;
-        };
-        response: MatterNode;
-    };
-    set_wifi_credentials: {
-        requestArgs: {
-            ssid: string;
-            credentials: string;
-        };
-        response: {};
-    };
-    set_thread_dataset: {
-        requestArgs: {
-            dataset: string;
-        };
-        response: {};
-    };
-    open_commissioning_window: {
-        requestArgs: {
-            node_id: number | bigint; //????
-            timeout: number; // seconds
-            iteration?: number; // 1000
-            option?: number; // 1??
-            discriminator?: number | null; // ???
-        };
-        response: {
-            setup_pin_code: number;
-            setup_manual_code: string;
-            setup_qr_code: string;
-        };
-    };
-    discover: {
-        requestArgs: {};
-        response: CommissionableNodeData[];
-    };
-    interview_node: {
-        requestArgs: {
-            node_id: number | bigint; // ???
-        };
-        response: null;
-    };
-    device_command: {
-        requestArgs: {
-            node_id: number | bigint; // ??
-            endpoint_id: number;
-            cluster_id: number;
-            command_name: string;
-            payload: unknown;
-            response_type: unknown; // ????
-            timed_request_timeout_ms?: number | null;
-            interaction_timeout_ms?: number | null;
-        };
-        response: unknown;
-    };
-    remove_node: {
-        requestArgs: {
-            node_id: number | bigint; // ???
-        };
-        response: null;
-    };
-    get_vendor_names: {
-        requestArgs: {
-            filter_vendors?: Array<number>;
-        };
-        response: { [key: string]: string };
-    };
-    subscribe_attribute: {
-        requestArgs: {};
-        response: {};
-    };
-    read_attribute: {
-        requestArgs: {
-            node_id: number | bigint;
-            /** Single attribute path or array of paths. Supports wildcards (*) for cluster and attribute IDs. */
-            attribute_path: string | string[];
-            /** Filter by fabric (default: false) */
-            fabric_filtered?: boolean;
-        };
-        response: AttributesData;
-    };
-    write_attribute: {
-        requestArgs: {
-            node_id: number | bigint; //???,
-            attribute_path: string;
-            value: unknown;
-        };
-        response: Array<{
-            Path: {
-                EndpointId: number;
-                ClusterId: number;
-                AttributeId: number;
-            };
-            Status: number;
-        }>;
-    };
-    ping_node: {
-        requestArgs: {
-            node_id: number | bigint;
-            /** Number of ping attempts per IP address (default: 1) */
-            attempts?: number;
-        };
-        response: { [key: string]: boolean };
-    };
-    import_test_node: {
-        requestArgs: {
-            dump: string;
-        };
-        response: null;
-    };
-    get_node_ip_addresses: {
-        requestArgs: {
-            node_id: number | bigint; // ????
-            prefer_cache: boolean;
-            scoped: boolean;
-        };
-        response: Array<string>;
-    };
-    check_node_update: {
-        requestArgs: { node_id: number | bigint };
-        response: MatterSoftwareVersion | null;
-    };
-    update_node: {
-        requestArgs: { node_id: number | bigint; software_version: number | string };
-        response: MatterSoftwareVersion | null;
-    };
-    discover_commissionable_nodes: {
-        requestArgs: {};
-        response: CommissionableNodeData[];
-    };
-    get_matter_fabrics: {
-        requestArgs: { node_id: number | bigint };
-        response: MatterFabricData[];
-    };
-    remove_matter_fabric: {
-        requestArgs: {
-            node_id: number | bigint;
-            fabric_index: number;
-        };
-        response: {};
-    };
-    set_acl_entry: {
-        requestArgs: {
-            node_id: number | bigint;
-            entry: AccessControlEntry[];
-        };
-        response: AttributeWriteResult[] | null;
-    };
-    set_node_binding: {
-        requestArgs: {
-            node_id: number | bigint;
-            endpoint: number;
-            bindings: BindingTarget[];
-        };
-        response: AttributeWriteResult[] | null;
-    };
-    get_loglevel: {
-        requestArgs: {};
-        response: {
-            /** Console log level */
-            console_loglevel: LogLevelString;
-            /** File log level (null if file logging not enabled) */
-            file_loglevel: LogLevelString | null;
-        };
-    };
-    set_loglevel: {
-        requestArgs: {
-            /** Console log level to set */
-            console_loglevel?: LogLevelString;
-            /** File log level to set (only applied if file logging is enabled) */
-            file_loglevel?: LogLevelString;
-        };
-        response: {
-            /** Console log level after change */
-            console_loglevel: LogLevelString;
-            /** File log level after change (null if file logging not enabled) */
-            file_loglevel: LogLevelString | null;
-        };
-    };
-}
-
-/** Log level string values matching CLI options */
-export type LogLevelString = "critical" | "error" | "warning" | "info" | "debug";
-
-/**
- * Access Control Entry structure for set_acl_entry command.
- * Uses snake_case field names matching our API convention.
- */
-export interface AccessControlEntry {
-    /** 1=View, 3=Operate, 4=Manage, 5=Administer */
-    privilege: number;
-    /** 1=PASE, 2=CASE, 3=Group */
-    auth_mode: number;
-    /** List of subject NodeIds or GroupIds */
-    subjects: Array<number | bigint> | null;
-    /** Optional target restrictions */
-    targets: AccessControlTarget[] | null;
-}
-
-export interface AccessControlTarget {
-    cluster: number | null;
-    endpoint: number | null;
-    device_type: number | null;
-}
-
-/**
- * Binding target structure for set_node_binding command.
- * Matches Python Matter Server's TargetStruct.
- */
-export interface BindingTarget {
-    /** Target node ID */
-    node: number | bigint | null;
-    /** Target group ID */
-    group: number | null;
-    /** Target endpoint */
-    endpoint: number | null;
-    /** Target cluster */
-    cluster: number | null;
-}
-
-/** Attribute write result for set_acl_entry and set_node_binding responses */
-export interface AttributeWriteResult {
-    path: {
-        endpoint_id: number;
-        cluster_id: number;
-        attribute_id: number;
-    };
-    status: number;
-}
-
-export interface ServerInfoMessage {
-    fabric_id: bigint; // not number
-    compressed_fabric_id: bigint; // not number
-    fabric_index: number;
-    schema_version: number;
-    min_supported_schema_version: number;
-    sdk_version: string;
-    wifi_credentials_set: boolean;
-    thread_credentials_set: boolean;
-    bluetooth_enabled: boolean;
-}
-
-/**
- * Matter node event structure for node_event WebSocket event.
- * Matches Python Matter Server's MatterNodeEvent.
- */
-export interface MatterNodeEvent {
-    node_id: number | bigint;
-    endpoint_id: number;
-    cluster_id: number;
-    event_id: number;
-    event_number: number | bigint;
-    priority: number; // 0=Debug, 1=Info, 2=Critical
-    timestamp: number | bigint;
-    timestamp_type: number; // 0=System, 1=Epoch, 2=POSIX
-    data: unknown | null;
-}
-
-interface APIEvents {
-    node_added: {
-        data: MatterNode;
-    };
-    node_updated: {
-        data: MatterNode;
-    };
-    node_removed: {
-        data: number | bigint;
-    };
-    node_event: {
-        data: MatterNodeEvent;
-    };
-    attribute_updated: {
-        data: [node_id: number | bigint, attribute_path: string, value: unknown];
-    };
-    server_shutdown: {
-        data: Record<string, never>;
-    };
-    endpoint_added: {
-        data: { node_id: number | bigint; endpoint_id: number };
-    };
-    endpoint_removed: {
-        data: { node_id: number | bigint; endpoint_id: number };
-    };
-    server_info_updated: {
-        data: ServerInfoMessage;
-    };
-}
-
-export type EventMessage<E extends keyof APIEvents> = {
-    event: E;
-    data: APIEvents[E]["data"];
-};
-export type EventTypes = keyof APIEvents;
-
-export interface WebSocketConfig {
-    host: string;
-    port: string;
-    scheme: string;
-    path: string;
-}
-
-export enum UpdateSource {
-    MAIN_NET_DCL = "main-net-dcl",
-    TEST_NET_DCL = "test-net-dcl",
-    LOCAL = "local",
-}
-
-export interface MatterSoftwareVersion {
-    vid: number;
-    pid: number;
-    software_version: number;
-    software_version_string: string;
-    firmware_information?: string;
-    min_applicable_software_version: number;
-    max_applicable_software_version: number;
-    release_notes_url?: string;
-    update_source: UpdateSource;
-}
-
-export interface CommissioningParameters {
-    setup_pin_code: number;
-    setup_manual_code: string;
-    setup_qr_code: string;
-}
-
-export interface CommissionableNodeData {
-    instance_name?: string;
-    host_name?: string;
-    port?: number;
-    long_discriminator?: number;
-    vendor_id?: number;
-    product_id?: number;
-    commissioning_mode?: number;
-    device_type?: number;
-    device_name?: string;
-    pairing_instruction?: string;
-    pairing_hint?: number;
-    mrp_retry_interval_idle?: number;
-    mrp_retry_interval_active?: number;
-    supports_tcp?: boolean;
-    addresses?: string[];
-    rotating_id?: string;
-}
-
-export interface MatterFabricData {
-    fabric_id?: number | bigint;
-    vendor_id?: number;
-    fabric_index?: number;
-    fabric_label?: string;
-    vendor_name?: string;
-}
-
-export type NotificationType = "success" | "info" | "warning" | "error";
-export type NodePingResult = Record<string, boolean>;
-
 /**
- * WebSocket Command Message generic type.
+ * WebSocket protocol types.
+ *
+ * Canonical type definitions live in @matter-server/ws-client.
+ * This module re-exports them for backward compatibility and adds server-only types.
  */
-export interface CommandMessage {
-    message_id: string;
-    command: keyof APICommands;
-    args?: APICommands[keyof APICommands]["requestArgs"];
-}
-
-/** WebSocket Result Message base fields type */
-interface ResultMessageBase {
-    message_id: string;
-}
-
-/** WebSocket Error Result Message type */
-export interface ErrorResultMessage extends ResultMessageBase {
-    error_code: number;
-    details?: string;
-}
-
-/** WebSocket Success Result Message type */
-export interface SuccessResultMessage<T extends keyof APICommands> extends ResultMessageBase {
-    result: APICommands[T]["response"];
-}
 
-export type ArgsOf<R extends keyof APICommands> = APICommands[R]["requestArgs"];
-export type ResponseOf<R extends keyof APICommands> = APICommands[R]["response"];
-
-/**
- * Minimum test node ID. Node IDs >= this value are reserved for test nodes.
- * Uses high 64-bit range (0xFFFF_FFFE_0000_0000) to avoid collision with real node IDs.
- */
-export const TEST_NODE_START = 0xffff_fffe_0000_0000n;
+// Re-export all shared protocol types from ws-client
+export {
+    type AccessControlEntry,
+    type AccessControlTarget,
+    type APICommands,
+    type APIEvents,
+    type ArgsOf,
+    type AttributesData,
+    type AttributeWriteResult,
+    type BindingTarget,
+    type CommandMessage,
+    type CommissionableNodeData,
+    type CommissioningParameters,
+    type ErrorResultMessage,
+    type EventMessage,
+    type EventTypes,
+    type LogLevelResponse,
+    type LogLevelString,
+    type MatterFabricData,
+    type MatterNodeEvent,
+    type NodePingResult,
+    type NotificationType,
+    type ResponseOf,
+    type ResultMessageBase,
+    type ServerInfoMessage,
+    type SuccessResultMessage,
+    type MatterSoftwareVersion,
+    type WebSocketConfig,
+    TEST_NODE_START,
+    UpdateSource,
+} from "@matter-server/ws-client";
+
+// Re-export MatterNodeData as MatterNode for backward compatibility within ws-controller
+export type { MatterNodeData as MatterNode } from "@matter-server/ws-client";
 
 /**
  * Error codes matching Python Matter Server for API compatibility.