smart-home-engine 0.13.0 → 0.15.18

package/src/matter/controller.js

@@ -9,7 +9,7 @@
  * All nodeIds are exposed as decimal strings (BigInt serialization boundary).
  */
 
-const { Environment, ServerNode } = require('@matter/main');
+const { Environment, ServerNode, ControllerBehavior } = require('@matter/main');
 
 /** @type {import('@matter/main').ServerNode | null} */
 let _server = null;
@@ -32,13 +32,37 @@ function _nodeIdStr(nodeId) {
     return nodeId.toString();
 }
 
-function _findClientNode(nodeIdStr) {
+function _findClientNode(nodeIdOrName) {
+    nodeIdOrName = String(nodeIdOrName);
     if (!_server) throw new Error('Matter controller not started');
+    // Try exact numeric nodeId match first
     for (const node of _server.peers) {
         const addr = node.peerAddress;
-        if (addr && _nodeIdStr(addr.nodeId) === nodeIdStr) return node;
+        if (addr && _nodeIdStr(addr.nodeId) === nodeIdOrName) return node;
     }
-    throw new Error(`Matter node not found: ${nodeIdStr}`);
+    // Fall back to name match (basicInformation.nodeLabel / productName)
+    for (const node of _server.peers) {
+        if (!node.peerAddress) continue;
+        if (_getDeviceName(node) === nodeIdOrName) return node;
+    }
+    throw new Error(`Matter node not found: ${nodeIdOrName}`);
+}
+
+/**
+ * Resolve an endpoint by numeric id or by name.
+ * @param {object} node ClientNode
+ * @param {number|string} endpointIdOrName
+ * @returns endpoint object
+ */
+function _resolveEndpoint(node, endpointIdOrName) {
+    const asNum = Number(endpointIdOrName);
+    if (Number.isFinite(asNum)) return node.endpoints.for(asNum);
+    // Name-based lookup
+    const name = String(endpointIdOrName);
+    for (const ep of node.endpoints) {
+        if (_getEndpointName(ep) === name) return ep;
+    }
+    throw new Error(`Endpoint not found: ${endpointIdOrName}`);
 }
 
 /** Resolve a cluster name (camelCase) from a cluster ID number or string. */
@@ -69,7 +93,13 @@ async function init(storagePath, log, broadcastFn) {
 
     // Disable matter.js built-in CLI arg and env-var parsing so it doesn't
     // interfere with the daemon's own yargs config.
-    Environment.default.vars.set('environment.disableInteraction', true);
+    // Wrapped in try/catch because the internal variable layout changed in some
+    // @matter/main versions and throws when 'environment' is not a map segment.
+    try {
+        Environment.default.vars.set('environment.disableInteraction', true);
+    } catch {
+        // Non-fatal: the daemon has no interactive terminal anyway.
+    }
 
     _server = await ServerNode.create({
         id: 'she-matter-controller',
@@ -92,9 +122,67 @@ async function close() {
 
 // ── Device management ─────────────────────────────────────────────────────────
 
+/**
+ * Extract a human-readable name for a node from its root endpoint's basicInformation cluster.
+ * Returns null when the cluster is unavailable or the node is offline.
+ * @param {object} node ClientNode
+ * @returns {string|null}
+ */
+function _getDeviceName(node) {
+    try {
+        for (const ep of node.endpoints) {
+            if ((ep.number ?? 0) !== 0) continue;
+            const bi = ep.state?.basicInformation;
+            if (bi?.nodeLabel) return bi.nodeLabel;
+            if (bi?.productName) return bi.productName;
+        }
+    } catch { /* node may be offline */ }
+    return null;
+}
+
+/**
+ * Extract a human-readable name for a single endpoint.
+ * Prefers bridgedDeviceBasicInformation.nodeLabel for bridged devices,
+ * falls back to basicInformation for the root endpoint.
+ * @param {object} endpoint
+ * @returns {string|null}
+ */
+function _getEndpointName(endpoint) {
+    try {
+        const state = endpoint.state;
+        if (!state) return null;
+        const bridgedBi = state.bridgedDeviceBasicInformation;
+        if (bridgedBi?.nodeLabel) return bridgedBi.nodeLabel;
+        const bi = state.basicInformation;
+        if (bi?.nodeLabel) return bi.nodeLabel;
+        if (bi?.productName) return bi.productName;
+    } catch { /* best-effort */ }
+    return null;
+}
+
+/**
+ * Extract vendor + product subtitle for the root endpoint (endpoint 0).
+ * Returns null when unavailable.
+ * @param {object} node
+ * @returns {string|null}
+ */
+function _getDeviceSubtitle(node) {
+    try {
+        for (const ep of node.endpoints) {
+            if ((ep.number ?? 0) !== 0) continue;
+            const bi = ep.state?.basicInformation;
+            const parts = [];
+            if (bi?.vendorName) parts.push(bi.vendorName);
+            if (bi?.productName && bi.productName !== _getDeviceName(node)) parts.push(bi.productName);
+            return parts.length ? parts.join(' · ') : null;
+        }
+    } catch { /* offline */ }
+    return null;
+}
+
 /**
  * List all paired nodes.
- * @returns {{ nodeId: string, online: boolean }[]}
+ * @returns {{ nodeId: string, online: boolean, name: string|null }[]}
  */
 function listPaired() {
     if (!_server) return [];
@@ -105,6 +193,7 @@ function listPaired() {
         result.push({
             nodeId: _nodeIdStr(addr.nodeId),
             online: node.lifecycle?.isOnline ?? false,
+            name: _getDeviceName(node),
         });
     }
     return result;
@@ -113,12 +202,41 @@ function listPaired() {
 /**
  * Commission a new device.
  *
- * @param {{ passcode: number, discriminator?: number } | { pairingCode: string }} options
+ * @param {{ passcode: number, discriminator?: number, discoveryAddress?: string } | { pairingCode: string, discoveryAddress?: string }} options
+ *   discoveryAddress: optional "ip" or "ip:port" to bypass mDNS discovery and connect directly.
  * @returns {Promise<string>}  nodeId of the newly commissioned device
  */
 async function commission(options) {
     if (!_server) throw new Error('Matter controller not started');
-    const clientNode = await _server.peers.commission(options);
+    const { discoveryAddress, ...commissionOpts } = options;
+    let clientNode;
+    if (discoveryAddress) {
+        const colonIdx = discoveryAddress.lastIndexOf(':');
+        let ip, port;
+        if (colonIdx > 0 && !discoveryAddress.startsWith('[') && colonIdx !== discoveryAddress.indexOf(':')) {
+            // IPv6 without brackets — treat whole string as IP, use default port
+            ip = discoveryAddress;
+            port = 5540;
+        } else if (colonIdx > 0) {
+            const maybePort = parseInt(discoveryAddress.slice(colonIdx + 1), 10);
+            if (Number.isFinite(maybePort)) {
+                ip = discoveryAddress.slice(0, colonIdx).replace(/^\[|\]$/g, '');
+                port = maybePort;
+            } else {
+                ip = discoveryAddress;
+                port = 5540;
+            }
+        } else {
+            ip = discoveryAddress;
+            port = 5540;
+        }
+        _log.info(`matter: using direct discovery address ${ip}:${port} (bypassing mDNS)`);
+        _server.behaviors.require(ControllerBehavior);
+        clientNode = await _server.peers.forDescriptor({ addresses: [{ type: 'udp', ip, port }] });
+        await clientNode.commission(commissionOpts);
+    } else {
+        clientNode = await _server.peers.commission(commissionOpts);
+    }
     const addr = clientNode.peerAddress;
     if (!addr) throw new Error('Commission succeeded but node has no peerAddress');
     const nodeId = _nodeIdStr(addr.nodeId);
@@ -149,14 +267,14 @@ async function unpair(nodeId) {
  * Each endpoint entry carries the list of available cluster names.
  *
  * @param {string} nodeId
- * @returns {{ endpointId: number, clusters: string[] }[]}
+ * @returns {{ endpointId: number, clusters: string[], name: string|null }[]}
  */
 function getEndpoints(nodeId) {
     const node = _findClientNode(nodeId);
     const result = [];
     for (const endpoint of node.endpoints) {
         const clusters = endpoint.state ? Object.keys(endpoint.state) : [];
-        result.push({ endpointId: endpoint.number ?? 0, clusters });
+        result.push({ endpointId: endpoint.number ?? 0, clusters, name: _getEndpointName(endpoint) });
     }
     return result;
 }
@@ -174,7 +292,7 @@ function getEndpoints(nodeId) {
  */
 async function getAttribute(nodeId, endpointId, clusterName, attrName) {
     const node = _findClientNode(nodeId);
-    const endpoint = node.endpoints.for(endpointId);
+    const endpoint = _resolveEndpoint(node, endpointId);
     const clusterState = endpoint.state?.[_clusterName(clusterName)];
     if (!clusterState) throw new Error(`Cluster "${clusterName}" not found on endpoint ${endpointId}`);
     return clusterState[attrName];
@@ -194,17 +312,22 @@ async function getAttribute(nodeId, endpointId, clusterName, attrName) {
  */
 async function sendCommand(nodeId, endpointId, clusterName, commandName, args) {
     const node = _findClientNode(nodeId);
-    return node.act(`she.matter.send(${nodeId}, ${endpointId}, ${clusterName}.${commandName})`, async (agent) => {
-        const rootParts = agent.parts;
-        // Navigate to the target endpoint
-        const ep = rootParts ? rootParts.get(endpointId) : null;
-        if (!ep) throw new Error(`Endpoint ${endpointId} not found on node ${nodeId}`);
-        const clusterAgent = ep[_clusterName(clusterName)];
-        if (!clusterAgent) throw new Error(`Cluster "${clusterName}" not found`);
-        const cmd = clusterAgent[commandName];
-        if (typeof cmd !== 'function') throw new Error(`Command "${commandName}" not found in cluster "${clusterName}"`);
-        return cmd.call(clusterAgent, args ?? {});
-    });
+    // Use the target endpoint's own act() instead of navigating via agent.parts,
+    // because Parts in @matter/node is a set-like iterable, not a Map (.get doesn't exist).
+    const endpoint = _resolveEndpoint(node, endpointId);
+    return endpoint.act(
+        `she.matter.send(${nodeId}, ${endpointId}, ${clusterName}.${commandName})`,
+        async (agent) => {
+            const clusterAgent = agent[_clusterName(clusterName)];
+            if (!clusterAgent) throw new Error(`Cluster "${clusterName}" not found on endpoint ${endpointId}`);
+            const cmd = clusterAgent[commandName];
+            if (typeof cmd !== 'function') throw new Error(`Command "${commandName}" not found in cluster "${clusterName}"`);
+            // Only pass args when the caller actually provided non-empty args.
+            // Void commands (e.g. onOff.off) fail TLV validation if passed an empty object.
+            const hasArgs = args !== undefined && args !== null && Object.keys(args).length > 0;
+            return hasArgs ? cmd.call(clusterAgent, args) : cmd.call(clusterAgent);
+        }
+    );
 }
 
 // ── Node lifecycle events (online / offline) ────────────────────────────────
@@ -241,7 +364,7 @@ function _subscribeNodeLifecycle(node, nodeId) {
  */
 function subscribeAttribute(scriptFile, nodeId, endpointId, clusterName, attrName, callback) {
     const node = _findClientNode(nodeId);
-    const endpoint = node.endpoints.for(endpointId);
+    const endpoint = _resolveEndpoint(node, endpointId);
     const events = endpoint.events?.[_clusterName(clusterName)];
     if (!events) throw new Error(`Cluster "${clusterName}" not found on endpoint ${endpointId}`);
     const changeEvent = events[`${attrName}$Changed`];
@@ -292,6 +415,20 @@ function cleanup(scriptFile) {
     _listeners.delete(scriptFile);
 }
 
+/**
+ * Get vendor · product subtitle for a node by nodeId string.
+ * @param {string} nodeId
+ * @returns {string|null}
+ */
+function getDeviceSubtitle(nodeId) {
+    try {
+        const node = _findClientNode(nodeId);
+        return _getDeviceSubtitle(node);
+    } catch {
+        return null;
+    }
+}
+
 module.exports = {
     init,
     close,
@@ -299,6 +436,7 @@ module.exports = {
     commission,
     unpair,
     getEndpoints,
+    getDeviceSubtitle,
     getAttribute,
     sendCommand,
     subscribeAttribute,

package/src/sandbox/matter-sandbox.js

@@ -15,6 +15,11 @@
  *   she.matter.send(nodeId, endpointId, clusterName, command, args?)
  *       → Promise<result>
  *
+ * nodeId   — decimal NodeId string (e.g. '4') OR device name (e.g. 'Matterbridge')
+ * endpointId — numeric endpoint id (e.g. 43) OR endpoint name (e.g. 'Licht Werkstatt')
+ * Name matching uses basicInformation.nodeLabel / productName for devices and
+ * bridgedDeviceBasicInformation.nodeLabel / basicInformation.nodeLabel for endpoints.
+ *
  * All subscriptions registered by a script are automatically cancelled on
  * hot-reload (cleanup() is called from unloadScript() in index.js).
  */
@@ -26,11 +31,11 @@ module.exports = function (she, { scriptDomain, scriptName }) {
         /**
          * Subscribe to an attribute change on a paired Matter device.
          *
-         * @param {string}   nodeId       Decimal NodeId string
-         * @param {number}   endpointId
-         * @param {string}   clusterName  camelCase cluster name, e.g. "onOff"
-         * @param {string}   attrName     camelCase attribute name, e.g. "onOff"
-         * @param {Function} callback     (value, oldValue) => void
+         * @param {string|number} nodeId       Decimal NodeId string/number OR device name
+         * @param {number|string} endpointId   Numeric endpoint id OR endpoint name
+         * @param {string}        clusterName  camelCase cluster name, e.g. "onOff"
+         * @param {string}        attrName     camelCase attribute name, e.g. "onOff"
+         * @param {Function}      callback     (value, oldValue) => void
          * @returns {number}  listenerId
          */
         sub(nodeId, endpointId, clusterName, attrName, callback) {
@@ -53,10 +58,10 @@ module.exports = function (she, { scriptDomain, scriptName }) {
         /**
          * Read a single attribute value from a paired Matter device.
          *
-         * @param {string} nodeId
-         * @param {number} endpointId
-         * @param {string} clusterName  camelCase cluster name
-         * @param {string} attrName     camelCase attribute name
+         * @param {string|number} nodeId       Decimal NodeId string/number OR device name
+         * @param {number|string} endpointId   Numeric endpoint id OR endpoint name
+         * @param {string}        clusterName  camelCase cluster name
+         * @param {string}        attrName     camelCase attribute name
          * @returns {Promise<unknown>}
          */
         get(nodeId, endpointId, clusterName, attrName) {
@@ -66,15 +71,15 @@ module.exports = function (she, { scriptDomain, scriptName }) {
         /**
          * Invoke a cluster command on a paired Matter device.
          *
-         * @param {string}  nodeId
-         * @param {number}  endpointId
-         * @param {string}  clusterName  camelCase cluster name
-         * @param {string}  command      camelCase command name
-         * @param {object}  [args={}]
+         * @param {string|number} nodeId       Decimal NodeId string/number OR device name
+         * @param {number|string} endpointId   Numeric endpoint id OR endpoint name
+         * @param {string}        clusterName  camelCase cluster name
+         * @param {string}        command      camelCase command name
+         * @param {object}        [args]       Command arguments (omit for void commands)
          * @returns {Promise<unknown>}
          */
         send(nodeId, endpointId, clusterName, command, args) {
-            return controller.sendCommand(nodeId, endpointId, clusterName, command, args ?? {});
+            return controller.sendCommand(nodeId, endpointId, clusterName, command, args);
         },
     };
 };

package/src/sandbox/stdlib.js

@@ -129,4 +129,21 @@ module.exports = function (she) {
         /** Register a callback for MQTT connection lifecycle events ('connect' or 'disconnect'). */
         on: (event, cb) => she._registerMqttEvent(event, cb),
     };
+
+    /**
+     * Fetch a URL and return a Promise that resolves to the response body.
+     * Resolves to parsed JSON when the Content-Type is application/json, plain text otherwise.
+     * Rejects on non-2xx responses.
+     * @method fetch
+     * @param {string} url
+     * @param {RequestInit} [options]
+     * @returns {Promise<string|object>}
+     */
+    she.fetch = function Sandbox_fetch(url, options) {
+        return fetch(url, options).then((r) => {
+            if (!r.ok) throw new Error(`HTTP ${r.status} ${r.statusText}`);
+            const ct = r.headers.get('content-type') || '';
+            return ct.includes('json') ? r.json() : r.text();
+        });
+    };
 };