matterbridge 3.0.1 → 3.0.2-dev-20250509-ae61aa7

package/dist/matterbridgeEndpointHelpers.js

@@ -1,15 +1,5 @@
-/* eslint-disable @typescript-eslint/no-unused-vars */
-// Node.js modules
-import { createHash } from 'node:crypto';
-// AnsiLogger module
-import { BLUE, CYAN, db, debugStringify, er, hk, or, YELLOW, zb } from './logger/export.js';
-// Matterbridge
-import { deepCopy, deepEqual, isValidArray } from './utils/export.js';
-import { MatterbridgeIdentifyServer, MatterbridgeOnOffServer, MatterbridgeLevelControlServer, MatterbridgeColorControlServer, MatterbridgeWindowCoveringServer, MatterbridgeThermostatServer, MatterbridgeFanControlServer, MatterbridgeDoorLockServer, MatterbridgeModeSelectServer, MatterbridgeValveConfigurationAndControlServer, MatterbridgeSmokeCoAlarmServer, MatterbridgeBooleanStateConfigurationServer, MatterbridgeOperationalStateServer, } from './matterbridgeBehaviors.js';
-// @matter
 import { Lifecycle } from '@matter/main';
 import { getClusterNameById } from '@matter/main/types';
-// @matter clusters
 import { PowerSource } from '@matter/main/clusters/power-source';
 import { UserLabel } from '@matter/main/clusters/user-label';
 import { FixedLabel } from '@matter/main/clusters/fixed-label';
@@ -52,7 +42,6 @@ import { Pm10ConcentrationMeasurement } from '@matter/main/clusters/pm10-concent
 import { RadonConcentrationMeasurement } from '@matter/main/clusters/radon-concentration-measurement';
 import { TotalVolatileOrganicCompoundsConcentrationMeasurement } from '@matter/main/clusters/total-volatile-organic-compounds-concentration-measurement';
 import { OperationalState } from '@matter/main/clusters/operational-state';
-// @matter behaviors
 import { PowerSourceServer } from '@matter/main/behaviors/power-source';
 import { UserLabelServer } from '@matter/main/behaviors/user-label';
 import { FixedLabelServer } from '@matter/main/behaviors/fixed-label';
@@ -82,6 +71,10 @@ import { Pm25ConcentrationMeasurementServer } from '@matter/main/behaviors/pm25-
 import { Pm10ConcentrationMeasurementServer } from '@matter/main/behaviors/pm10-concentration-measurement';
 import { RadonConcentrationMeasurementServer } from '@matter/main/behaviors/radon-concentration-measurement';
 import { TotalVolatileOrganicCompoundsConcentrationMeasurementServer } from '@matter/main/behaviors/total-volatile-organic-compounds-concentration-measurement';
+import { createHash } from 'node:crypto';
+import { BLUE, CYAN, db, debugStringify, er, hk, or, YELLOW, zb } from 'node-ansi-logger';
+import { deepCopy, deepEqual, isValidArray } from './utils/export.js';
+import { MatterbridgeIdentifyServer, MatterbridgeOnOffServer, MatterbridgeLevelControlServer, MatterbridgeColorControlServer, MatterbridgeWindowCoveringServer, MatterbridgeThermostatServer, MatterbridgeFanControlServer, MatterbridgeDoorLockServer, MatterbridgeModeSelectServer, MatterbridgeValveConfigurationAndControlServer, MatterbridgeSmokeCoAlarmServer, MatterbridgeBooleanStateConfigurationServer, MatterbridgeOperationalStateServer, } from './matterbridgeBehaviors.js';
 export function capitalizeFirstLetter(name) {
     if (!name)
         return name;
@@ -94,19 +87,19 @@ export function lowercaseFirstLetter(name) {
 }
 export function checkNotLatinCharacters(deviceName) {
     const nonLatinRegexList = [
-        /[\u0400-\u04FF\u0500-\u052F]/, // Cyrillic
-        /[\u2E80-\u9FFF]/, // CJK (Chinese, Japanese, Korean)
-        /[\uAC00-\uD7AF]/, // Korean Hangul
-        /[\u0600-\u06FF\u0750-\u077F]/, // Arabic, Persian
-        /[\u0590-\u05FF]/, // Hebrew
-        /[\u0900-\u097F]/, // Devanagari (Hindi, Sanskrit)
-        /[\u0E00-\u0E7F]/, // Thai
-        /[\u1200-\u137F]/, // Ethiopic (Amharic, Tigrinya)
+        /[\u0400-\u04FF\u0500-\u052F]/,
+        /[\u2E80-\u9FFF]/,
+        /[\uAC00-\uD7AF]/,
+        /[\u0600-\u06FF\u0750-\u077F]/,
+        /[\u0590-\u05FF]/,
+        /[\u0900-\u097F]/,
+        /[\u0E00-\u0E7F]/,
+        /[\u1200-\u137F]/,
     ];
     return nonLatinRegexList.some((regex) => regex.test(deviceName));
 }
 export function generateUniqueId(deviceName) {
-    return createHash('md5').update(deviceName).digest('hex'); // MD5 hash of the device name
+    return createHash('md5').update(deviceName).digest('hex');
 }
 export function createUniqueId(param1, param2, param3, param4) {
     const hash = createHash('md5');
@@ -114,7 +107,6 @@ export function createUniqueId(param1, param2, param3, param4) {
     return hash.digest('hex');
 }
 export function getBehaviourTypesFromClusterServerIds(clusterServerList) {
-    // Map Server ClusterId to Behavior.Type
     const behaviorTypes = [];
     clusterServerList.forEach((clusterId) => {
         behaviorTypes.push(getBehaviourTypeFromClusterServerId(clusterId));
@@ -122,15 +114,12 @@ export function getBehaviourTypesFromClusterServerIds(clusterServerList) {
     return behaviorTypes;
 }
 export function getBehaviourTypesFromClusterClientIds(clusterClientList) {
-    // Map Client ClusterId to Behavior.Type
     const behaviorTypes = [];
-    clusterClientList.forEach((clusterId) => {
-        // behaviorTypes.push(getBehaviourTypeFromClusterClientId(clusterId));
+    clusterClientList.forEach((_clusterId) => {
     });
     return behaviorTypes;
 }
 export function getBehaviourTypeFromClusterServerId(clusterId) {
-    // Map ClusterId to Server Behavior.Type
     if (clusterId === PowerSource.Cluster.id)
         return PowerSourceServer.with(PowerSource.Feature.Wired);
     if (clusterId === UserLabel.Cluster.id)
@@ -217,9 +206,7 @@ export function getBehaviourTypeFromClusterServerId(clusterId) {
         return TotalVolatileOrganicCompoundsConcentrationMeasurementServer.with('NumericMeasurement');
     return MatterbridgeIdentifyServer;
 }
-export function getBehaviourTypeFromClusterClientId(clusterId) {
-    // Map ClusterId to Client Behavior.Type
-    // return IdentifyClient;
+export function getBehaviourTypeFromClusterClientId(_clusterId) {
 }
 export function getBehavior(endpoint, cluster) {
     let behavior;
@@ -237,6 +224,21 @@ export function getBehavior(endpoint, cluster) {
     }
     return behavior;
 }
+export async function invokeBehaviorCommand(endpoint, cluster, command, params) {
+    const behaviorId = getBehavior(endpoint, cluster)?.id;
+    if (!behaviorId) {
+        endpoint.log.error(`invokeBehaviorCommand error: command ${hk}${command}${er} not found on endpoint ${or}${endpoint.maybeId}${er}:${or}${endpoint.maybeNumber}${er}`);
+        return;
+    }
+    await endpoint.act((agent) => {
+        const behavior = agent[behaviorId];
+        if (!(command in behavior) || typeof behavior[command] !== 'function') {
+            endpoint.log.error(`invokeBehaviorCommand error: command ${hk}${command}${er} not found on agent for endpoint ${or}${endpoint.maybeId}${er}:${or}${endpoint.maybeNumber}${er}`);
+            return;
+        }
+        behavior[command](params);
+    });
+}
 export function addRequiredClusterServers(endpoint) {
     const requiredServerList = [];
     endpoint.log.debug(`addRequiredClusterServers for ${CYAN}${endpoint.maybeId}${db}`);
@@ -265,13 +267,6 @@ export function addOptionalClusterServers(endpoint) {
     });
     addClusterServers(endpoint, optionalServerList);
 }
-/**
- * Adds cluster servers to the specified endpoint based on the provided server list.
- *
- * @param {MatterbridgeEndpoint} endpoint - The endpoint to add the cluster servers to.
- * @param {ClusterId[]} serverList - The list of cluster IDs to add.
- * @returns void
- */
 export function addClusterServers(endpoint, serverList) {
     if (serverList.includes(PowerSource.Cluster.id))
         endpoint.createDefaultPowerSourceWiredClusterServer();
@@ -347,16 +342,7 @@ export function addClusterServers(endpoint, serverList) {
         endpoint.createDefaultRadonConcentrationMeasurementClusterServer();
     if (serverList.includes(TotalVolatileOrganicCompoundsConcentrationMeasurement.Cluster.id))
         endpoint.createDefaultTvocMeasurementClusterServer();
-    // if (serverList.includes(DeviceEnergyManagement.Cluster.id)) endpoint.createDefaultDeviceEnergyManagementClusterServer();
-    // if (serverList.includes(DeviceEnergyManagementMode.Cluster.id)) endpoint.createDefaultDeviceEnergyManagementModeClusterServer();
 }
-/**
- * Adds a fixed label to the FixedLabel cluster. The FixedLabel cluster is created if it does not exist.
- *
- * @param {MatterbridgeEndpoint} endpoint - The endpoint to add the cluster servers to.
- * @param {string} label - The label to add.
- * @param {string} value - The value of the label.
- */
 export async function addFixedLabel(endpoint, label, value) {
     if (!endpoint.hasClusterServer(FixedLabel.Cluster.id)) {
         endpoint.log.debug(`addFixedLabel: add cluster ${hk}FixedLabel${db}:${hk}fixedLabel${db} with label ${CYAN}${label}${db} value ${CYAN}${value}${db}`);
@@ -373,13 +359,6 @@ export async function addFixedLabel(endpoint, label, value) {
         await endpoint.setAttribute(FixedLabel.Cluster.id, 'labelList', labelList, endpoint.log);
     }
 }
-/**
- * Adds a user label to the UserLabel cluster. The UserLabel cluster is created if it does not exist.
- *
- * @param {MatterbridgeEndpoint} endpoint - The endpoint to add the cluster servers to.
- * @param {string} label - The label to add.
- * @param {string} value - The value of the label.
- */
 export async function addUserLabel(endpoint, label, value) {
     if (!endpoint.hasClusterServer(UserLabel.Cluster.id)) {
         endpoint.log.debug(`addUserLabel: add cluster ${hk}UserLabel${db}:${hk}userLabel${db} with label ${CYAN}${label}${db} value ${CYAN}${value}${db}`);
@@ -457,16 +436,6 @@ export function getAttributeId(endpoint, cluster, attribute) {
         return endpoint.behaviors.supported[lowercaseFirstLetter(cluster)]?.schema?.children?.find((child) => child.name === capitalizeFirstLetter(attribute))?.id;
     }
 }
-/**
- * Retrieves the value of the provided attribute from the given cluster.
- *
- * @param {MatterbridgeEndpoint} endpoint - The endpoint to retrieve the attribute from.
- * @param {Behavior.Type | ClusterType | ClusterId | string} cluster - The cluster to retrieve the attribute from.
- * @param {string} attribute - The name of the attribute to retrieve.
- * @param {AnsiLogger} [log] - (Optional) The logger to use for logging the retrieve. Errors are logged to the endpoint logger.
- * @returns {any} The value of the attribute, or undefined if the attribute is not found.
- */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function getAttribute(endpoint, cluster, attribute, log) {
     const clusterName = getBehavior(endpoint, cluster)?.id;
     if (!clusterName) {
@@ -489,16 +458,6 @@ export function getAttribute(endpoint, cluster, attribute, log) {
     log?.info(`${db}Get endpoint ${or}${endpoint.id}${db}:${or}${endpoint.number}${db} attribute ${hk}${capitalizeFirstLetter(clusterName)}${db}.${hk}${attribute}${db} value ${YELLOW}${value !== null && typeof value === 'object' ? debugStringify(value) : value}${db}`);
     return value;
 }
-/**
- * Sets the value of an attribute on a cluster server.
- *
- * @param {MatterbridgeEndpoint} endpoint - The endpoint to set the attribute on.
- * @param {Behavior.Type | ClusterType | ClusterId | string} cluster - The cluster to set the attribute on.
- * @param {string} attribute - The name of the attribute.
- * @param {boolean | number | bigint | string | object | null} value - The value to set for the attribute.
- * @param {AnsiLogger} [log] - (Optional) The logger to use for logging the set. Errors are logged to the endpoint logger.
- * @returns {Promise<boolean>} - A promise that resolves to a boolean indicating whether the attribute was successfully set.
- */
 export async function setAttribute(endpoint, cluster, attribute, value, log) {
     const clusterName = getBehavior(endpoint, cluster)?.id;
     if (!clusterName) {
@@ -524,16 +483,6 @@ export async function setAttribute(endpoint, cluster, attribute, value, log) {
         `to ${YELLOW}${value !== null && typeof value === 'object' ? debugStringify(value) : value}${db}`);
     return true;
 }
-/**
- * Sets the value of an attribute on a cluster server.
- *
- * @param {MatterbridgeEndpoint} endpoint - The endpoint to update the attribute on.
- * @param {Behavior.Type | ClusterType | ClusterId | string} cluster - The cluster to update the attribute on.
- * @param {string} attribute - The name of the attribute.
- * @param {boolean | number | bigint | string | object | null} value - The value to set for the attribute.
- * @param {AnsiLogger} [log] - (Optional) The logger to use for logging the update. Errors are logged to the endpoint logger.
- * @returns {Promise<boolean>} - A promise that resolves to a boolean indicating whether the attribute was successfully set.
- */
 export async function updateAttribute(endpoint, cluster, attribute, value, log) {
     const clusterName = getBehavior(endpoint, cluster)?.id;
     if (!clusterName) {
@@ -564,17 +513,6 @@ export async function updateAttribute(endpoint, cluster, attribute, value, log)
         `to ${YELLOW}${value !== null && typeof value === 'object' ? debugStringify(value) : value}${db}`);
     return true;
 }
-/**
- * Subscribes to the provided attribute on a cluster.
- *
- * @param {MatterbridgeEndpoint} endpoint - The endpoint to subscribe the attribute to.
- * @param {Behavior.Type | ClusterType | ClusterId | string} cluster - The cluster to subscribe the attribute to.
- * @param {string} attribute - The name of the attribute to subscribe to.
- * @param {(newValue: any, oldValue: any) => void} listener - A callback function that will be called when the attribute value changes.
- * @param {AnsiLogger} [log] - Optional logger for logging errors and information.
- * @returns {boolean} - A boolean indicating whether the subscription was successful.
- */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
 export async function subscribeAttribute(endpoint, cluster, attribute, listener, log) {
     const clusterName = getBehavior(endpoint, cluster)?.id;
     if (!clusterName) {
@@ -585,7 +523,6 @@ export async function subscribeAttribute(endpoint, cluster, attribute, listener,
         endpoint.log.debug(`subscribeAttribute ${hk}${clusterName}.${attribute}${db}: Endpoint ${or}${endpoint.maybeId}${db}:${or}${endpoint.maybeNumber}${db} is in the ${BLUE}${endpoint.construction.status}${db} state`);
         await endpoint.construction.ready;
     }
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const events = endpoint.events;
     attribute = lowercaseFirstLetter(attribute) + '$Changed';
     if (!(clusterName in events) || !(attribute in events[clusterName])) {
@@ -596,13 +533,20 @@ export async function subscribeAttribute(endpoint, cluster, attribute, listener,
     log?.info(`${db}Subscribed endpoint ${or}${endpoint.id}${db}:${or}${endpoint.number}${db} attribute ${hk}${capitalizeFirstLetter(clusterName)}${db}.${hk}${attribute}${db}`);
     return true;
 }
-/**
- * Get the default TemperatureMeasurement cluster server options.
- *
- * @param {number | null} measuredValue - The measured value of the temperature x 100.
- * @param {number | null} minMeasuredValue - The minimum measured value of the temperature x 100.
- * @param {number | null} maxMeasuredValue - The maximum measured value of the temperature x 100.
- */
+export function getDefaultOperationalStateClusterServer(operationalState = OperationalState.OperationalStateEnum.Stopped) {
+    return optionsFor(MatterbridgeOperationalStateServer, {
+        phaseList: [],
+        currentPhase: null,
+        operationalStateList: [
+            { operationalStateId: OperationalState.OperationalStateEnum.Stopped, operationalStateLabel: 'Stopped' },
+            { operationalStateId: OperationalState.OperationalStateEnum.Running, operationalStateLabel: 'Running' },
+            { operationalStateId: OperationalState.OperationalStateEnum.Paused, operationalStateLabel: 'Paused' },
+            { operationalStateId: OperationalState.OperationalStateEnum.Error, operationalStateLabel: 'Error' },
+        ],
+        operationalState,
+        operationalError: { errorStateId: OperationalState.ErrorState.NoError, errorStateLabel: 'No error', errorStateDetails: 'Fully operational' },
+    });
+}
 export function getDefaultTemperatureMeasurementClusterServer(measuredValue = null, minMeasuredValue = null, maxMeasuredValue = null) {
     return optionsFor(TemperatureMeasurementServer, {
         measuredValue,
@@ -611,13 +555,6 @@ export function getDefaultTemperatureMeasurementClusterServer(measuredValue = nu
         tolerance: 0,
     });
 }
-/**
- * Get the default RelativeHumidityMeasurement cluster server options.
- *
- * @param {number | null} measuredValue - The measured value of the relative humidity x 100.
- * @param {number | null} minMeasuredValue - The minimum measured value of the relative humidity x 100.
- * @param {number | null} maxMeasuredValue - The maximum measured value of the relative humidity x 100.
- */
 export function getDefaultRelativeHumidityMeasurementClusterServer(measuredValue = null, minMeasuredValue = null, maxMeasuredValue = null) {
     return optionsFor(RelativeHumidityMeasurementServer, {
         measuredValue,
@@ -626,13 +563,6 @@ export function getDefaultRelativeHumidityMeasurementClusterServer(measuredValue
         tolerance: 0,
     });
 }
-/**
- * Get the default PressureMeasurement cluster server options.
- *
- * @param {number | null} measuredValue - The measured value for the pressure.
- * @param {number | null} minMeasuredValue - The minimum measured value for the pressure.
- * @param {number | null} maxMeasuredValue - The maximum measured value for the pressure.
- */
 export function getDefaultPressureMeasurementClusterServer(measuredValue = null, minMeasuredValue = null, maxMeasuredValue = null) {
     return optionsFor(PressureMeasurementServer, {
         measuredValue,
@@ -641,19 +571,6 @@ export function getDefaultPressureMeasurementClusterServer(measuredValue = null,
         tolerance: 0,
     });
 }
-/**
- * Get the default IlluminanceMeasurement cluster server options.
- *
- * @param {number | null} measuredValue - The measured value of illuminance.
- * @param {number | null} minMeasuredValue - The minimum measured value of illuminance.
- * @param {number | null} maxMeasuredValue - The maximum measured value of illuminance.
- * @remark The default value for the illuminance measurement is null.
- * This attribute SHALL indicate the illuminance in Lux (symbol lx) as follows:
- * •  MeasuredValue = 10,000 x log10(illuminance) + 1,
- *    where 1 lx <= illuminance <= 3.576 Mlx, corresponding to a MeasuredValue in the range 1 to 0xFFFE.
- * • 0 indicates a value of illuminance that is too low to be measured
- * • null indicates that the illuminance measurement is invalid.
- */
 export function getDefaultIlluminanceMeasurementClusterServer(measuredValue = null, minMeasuredValue = null, maxMeasuredValue = null) {
     return optionsFor(IlluminanceMeasurementServer, {
         measuredValue,
@@ -662,13 +579,6 @@ export function getDefaultIlluminanceMeasurementClusterServer(measuredValue = nu
         tolerance: 0,
     });
 }
-/**
- * Get the default FlowMeasurement cluster server options.
- *
- * @param {number | null} measuredValue - The measured value of the flow in 10 x m3/h.
- * @param {number | null} minMeasuredValue - The minimum measured value of the flow in 10 x m3/h.
- * @param {number | null} maxMeasuredValue - The maximum measured value of the flow in 10 x m3/h.
- */
 export function getDefaultFlowMeasurementClusterServer(measuredValue = null, minMeasuredValue = null, maxMeasuredValue = null) {
     return optionsFor(FlowMeasurementServer, {
         measuredValue,
@@ -677,19 +587,6 @@ export function getDefaultFlowMeasurementClusterServer(measuredValue = null, min
         tolerance: 0,
     });
 }
-/**
- * Get the default OccupancySensing cluster server options.
- *
- * @param {boolean} occupied - A boolean indicating whether the occupancy is occupied or not. Default is false.
- * @param {number} holdTime - The hold time in seconds. Default is 30.
- * @param {number} holdTimeMin - The minimum hold time in seconds. Default is 1.
- * @param {number} holdTimeMax - The maximum hold time in seconds. Default is 300.
- *
- * @remark The default value for the occupancy sensor type is PIR.
- * Servers SHALL set these attributes for backward compatibility with clients implementing a cluster revision <= 4 as
- * described in OccupancySensorType and OccupancySensorTypeBitmap Attributes.
- * This replaces the 9 legacy attributes PIROccupiedToUnoccupiedDelay through PhysicalContactUnoccupiedToOccupiedThreshold.
- */
 export function getDefaultOccupancySensingClusterServer(occupied = false, holdTime = 30, holdTimeMin = 1, holdTimeMax = 300) {
     return optionsFor(OccupancySensingServer.with(OccupancySensing.Feature.PassiveInfrared), {
         occupancy: { occupied },
@@ -701,4 +598,3 @@ export function getDefaultOccupancySensingClusterServer(occupied = false, holdTi
         holdTimeLimits: { holdTimeMin, holdTimeMax, holdTimeDefault: holdTime },
     });
 }
-//# sourceMappingURL=matterbridgeEndpointHelpers.js.map