matterbridge/dist/matterbridgeEndpointHelpers.d.ts

Matterbridge plugin manager for Matter

/**
 * This file contains the helpers for the class MatterbridgeEndpoint.
 *
 * @file matterbridgeEndpointHelpers.ts
 * @author Luca Liguori
 * @created 2024-10-01
 * @version 2.1.0
 * @license Apache-2.0
 *
 * Copyright 2024, 2025, 2026 Luca Liguori.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
import { AnsiLogger } from 'node-ansi-logger';
import { ActionContext, Behavior, ClusterId, Endpoint } from '@matter/main';
import { ClusterType } from '@matter/main/types';
import { OperationalState } from '@matter/main/clusters/operational-state';
import { MatterbridgeEndpoint, MatterbridgeEndpointCommands } from './matterbridgeEndpoint.js';
/**
 *  Capitalizes the first letter of a string.
 *
 * @param {string} name - The string to capitalize.
 * @returns {string} The string with the first letter capitalized.
 */
export declare function capitalizeFirstLetter(name: string): string;
/**
 * Lowercases the first letter of a string.
 *
 * @param {string} name - The string to lowercase the first letter of.
 * @returns {string} The string with the first letter lowercased.
 */
export declare function lowercaseFirstLetter(name: string): string;
/**
 * Checks if the device name contains non-Latin characters.
 *
 * @param {string} deviceName - The name of the device to check.
 * @returns {boolean} Returns true if the device name contains non-Latin characters, false otherwise.
 */
export declare function checkNotLatinCharacters(deviceName: string): boolean;
/**
 * Generates a unique ID based on the device name.
 *
 * @param {string} deviceName - The name of the device to generate a unique ID for.
 * @returns {string} A unique ID generated from the device name using MD5 hashing.
 */
export declare function generateUniqueId(deviceName: string): string;
/**
 * Generates a unique ID based on four parameters.
 *
 * @param {string} param1 - The first parameter.
 * @param {string} param2 - The second parameter.
 * @param {string} param3 - The third parameter.
 * @param {string} param4 - The fourth parameter.
 * @returns {string} A unique ID generated from the concatenation of the parameters using MD5 hashing.
 */
export declare function createUniqueId(param1: string, param2: string, param3: string, param4: string): string;
/**
 * Retrieves the features for a specific behavior.
 *
 * @param {Endpoint} endpoint - The endpoint to retrieve the features from.
 * @param {string} behavior - The behavior to retrieve the features for.
 *
 * @returns {Record<string, boolean | undefined>} The features for the specified behavior.
 *
 * @remarks Use with:
 * ```typescript
 *     expect(featuresFor(device, 'powerSource').wired).toBe(true);
 * ```
 */
export declare function featuresFor(endpoint: Endpoint, behavior: string): Record<string, boolean | undefined>;
/**
 * Maps a list of ClusterId to Behavior.Type for server clusters.
 *
 * @param {ClusterId[]} clusterServerList - The list of ClusterId to map.
 * @returns {Behavior.Type[]} An array of Behavior.Type corresponding to the ClusterId in the server list.
 */
export declare function getBehaviourTypesFromClusterServerIds(clusterServerList: ClusterId[]): Behavior.Type[];
/**
 * Maps a list of ClusterId to Behavior.Type for client clusters.
 *
 * @param {ClusterId[]} clusterClientList - The list of ClusterId to map.
 * @returns {Behavior.Type[]} An array of Behavior.Type corresponding to the ClusterId in the client list.
 */
export declare function getBehaviourTypesFromClusterClientIds(clusterClientList: ClusterId[]): Behavior.Type[];
/**
 * Maps a ClusterId to a Behavior.Type for server clusters.
 *
 * @param {ClusterId} clusterId - The ClusterId to map.
 * @returns {Behavior.Type} The corresponding Behavior.Type for the given ClusterId.
 */
export declare function getBehaviourTypeFromClusterServerId(clusterId: ClusterId): Behavior.Type;
/**
 *  Maps a ClusterId to a Behavior.Type for client clusters.
 *
 * @param {ClusterId} _clusterId - The ClusterId to map.
 */
export declare function getBehaviourTypeFromClusterClientId(_clusterId: ClusterId): void;
/**
 *  Retrieves the Behavior.Type for a given cluster from the endpoint's supported behaviors.
 *
 * @param {MatterbridgeEndpoint} endpoint - The endpoint to retrieve the behavior from.
 * @param {Behavior.Type | ClusterType | ClusterId | string} cluster - The cluster to retrieve the behavior for.
 * @returns {Behavior.Type | undefined} The Behavior.Type for the given cluster, or undefined if not found.
 */
export declare function getBehavior(endpoint: MatterbridgeEndpoint, cluster: Behavior.Type | ClusterType | ClusterId | string): Behavior.Type | undefined;
/**
 * Invokes a command on the specified behavior of the endpoint. Used ONLY in Jest tests.
 *
 * @param {MatterbridgeEndpoint} endpoint - The endpoint to invoke the command on.
 * @param {Behavior.Type | ClusterType | ClusterId | string} cluster - The cluster to invoke the command on.
 * @param {keyof MatterbridgeEndpointCommands} command - The command to invoke.
 * @param {Record<string, boolean | number | bigint | string | object | null>} [params] - The parameters to pass to the command.
 *
 * @returns {Promise<boolean>} A promise that resolves to true if the command was invoked successfully, false otherwise.
 *
 * @deprecated Used ONLY in Jest tests.
 */
export declare function invokeBehaviorCommand(endpoint: MatterbridgeEndpoint, cluster: Behavior.Type | ClusterType | ClusterId | string, command: keyof MatterbridgeEndpointCommands, params?: Record<string, boolean | number | bigint | string | object | null>): Promise<boolean>;
/**
 * Invokes the subscription handler on the specified cluster and attribute of the endpoint. Used ONLY in Jest tests.
 *
 * @param {MatterbridgeEndpoint} endpoint - The endpoint to invoke the subscription handler on.
 * @param {Behavior.Type | ClusterType | ClusterId | string} cluster - The cluster to invoke the subscription handler on.
 * @param {string} attribute - The attribute to invoke the subscription handler on.
 * @param {unknown} newValue - The new value of the attribute.
 * @param {unknown} oldValue - The old value of the attribute.
 *
 * @returns {Promise<boolean>} A promise that resolves to true if the subscription handler was invoked successfully, false otherwise.
 * @deprecated Used ONLY in Jest tests.
 */
export declare function invokeSubscribeHandler(endpoint: MatterbridgeEndpoint, cluster: Behavior.Type | ClusterType | ClusterId | string, attribute: string, newValue: unknown, oldValue: unknown): Promise<boolean>;
/**
 * Adds required cluster servers to the specified endpoint based on the device types.
 *
 * @param {MatterbridgeEndpoint} endpoint - The endpoint to add the required cluster servers to.
 * @returns {void}
 */
export declare function addRequiredClusterServers(endpoint: MatterbridgeEndpoint): void;
/**
 * Adds optional cluster servers to the specified endpoint based on the device types.
 *
 * @param {MatterbridgeEndpoint} endpoint - The endpoint to add the optional cluster servers to.
 * @returns {void}
 */
export declare function addOptionalClusterServers(endpoint: MatterbridgeEndpoint): void;
/**
 * 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.
 */
export declare function addClusterServers(endpoint: MatterbridgeEndpoint, serverList: ClusterId[]): void;
/**
 * 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. Max 16 characters.
 * @param {string} value - The value of the label. Max 16 characters.
 */
export declare function addFixedLabel(endpoint: MatterbridgeEndpoint, label: string, value: string): Promise<void>;
/**
 * 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. Max 16 characters.
 * @param {string} value - The value of the label. Max 16 characters.
 */
export declare function addUserLabel(endpoint: MatterbridgeEndpoint, label: string, value: string): Promise<void>;
/**
 * Returns the options for a given behavior type.
 *
 * @param {T} type - The behavior type.
 * @param {Behavior.Options<T>} options - The options for the behavior type.
 * @returns {Behavior.Options<T>} The options for the behavior type.
 */
export declare function optionsFor<T extends Behavior.Type>(type: T, options: Behavior.Options<T>): Behavior.Options<T>;
/**
 * Retrieves the cluster name by its ID.
 *
 * @param {Endpoint} endpoint - The endpoint to retrieve the cluster name from.
 * @param {ClusterId} cluster - The ID of the cluster.
 * @returns {string} The name of the cluster.
 */
export declare function getClusterId(endpoint: Endpoint, cluster: string): number | undefined;
/**
 * Retrieves the ID of an attribute from a cluster behavior.
 *
 * @param {Endpoint} endpoint - The endpoint to retrieve the attribute ID from.
 * @param {string} cluster - The name of the cluster.
 * @param {string} attribute - The name of the attribute.
 * @returns {number | undefined} The ID of the attribute, or undefined if not found.
 */
export declare function getAttributeId(endpoint: Endpoint, cluster: string, attribute: string): import("@matter/main").AttributeId | undefined;
/**
 * 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.
 */
export declare function getAttribute(endpoint: MatterbridgeEndpoint, cluster: Behavior.Type | ClusterType | ClusterId | string, attribute: string, log?: AnsiLogger): any;
/**
 * 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 declare function setAttribute(endpoint: MatterbridgeEndpoint, cluster: Behavior.Type | ClusterType | ClusterId | string, attribute: string, value: boolean | number | bigint | string | object | null, log?: AnsiLogger): Promise<boolean>;
/**
 * 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 declare function updateAttribute(endpoint: MatterbridgeEndpoint, cluster: Behavior.Type | ClusterType | ClusterId | string, attribute: string, value: boolean | number | bigint | string | object | null, log?: AnsiLogger): Promise<boolean>;
/**
 * 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, context: ActionContext) => void} listener - A callback function that will be called when the attribute value changes. When context.offline === true then the change is locally generated and not from the controller.
 * @param {AnsiLogger} [log] - Optional logger for logging errors and information.
 * @returns {boolean} - A boolean indicating whether the subscription was successful.
 *
 * @remarks The listener function (cannot be async) will receive three parameters:
 * - `newValue`: The new value of the attribute.
 * - `oldValue`: The old value of the attribute.
 * - `context`: The action context, which includes information about the action that triggered the change. When context.offline === true then the change is locally generated and not from the controller.
 */
export declare function subscribeAttribute(endpoint: MatterbridgeEndpoint, cluster: Behavior.Type | ClusterType | ClusterId | string, attribute: string, listener: (newValue: any, oldValue: any, context: ActionContext) => void, log?: AnsiLogger): Promise<boolean>;
/**
 * Triggers an event on the specified cluster.
 *
 * @param {MatterbridgeEndpoint} endpoint - The endpoint to trigger the event on.
 * @param {Behavior.Type | ClusterType | ClusterId | string} cluster - The ID of the cluster.
 * @param {string} event - The name of the event to trigger.
 * @param {Record<string, boolean | number | bigint | string | object | undefined | null>} payload - The payload to pass to the event.
 * @param {AnsiLogger} [log] - Optional logger for logging information.
 *
 * @returns {Promise<boolean>} - A promise that resolves to a boolean indicating whether the event was successfully triggered.
 */
export declare function triggerEvent(endpoint: MatterbridgeEndpoint, cluster: Behavior.Type | ClusterType | ClusterId | string, event: string, payload: Record<string, boolean | number | bigint | string | object | undefined | null>, log?: AnsiLogger): Promise<boolean>;
/**
 * Get the default OperationalState Cluster Server.
 *
 * @param {OperationalState.OperationalStateEnum} operationalState - The initial operational state id.
 *
 * @returns {Behavior.Options<MatterbridgeOperationalStateServer>} - The default options for the OperationalState cluster server.
 *
 * @remarks
 * This method adds a cluster server with a default operational state configuration:
 * - { operationalStateId: OperationalState.OperationalStateEnum.Stopped, operationalStateLabel: 'Stopped' },
 * - { operationalStateId: OperationalState.OperationalStateEnum.Running, operationalStateLabel: 'Running' },
 * - { operationalStateId: OperationalState.OperationalStateEnum.Paused, operationalStateLabel: 'Paused' },
 * - { operationalStateId: OperationalState.OperationalStateEnum.Error, operationalStateLabel: 'Error' },
 */
export declare function getDefaultOperationalStateClusterServer(operationalState?: OperationalState.OperationalStateEnum): Partial<{
    phaseList: string[] | null;
    currentPhase: number | null;
    operationalStateList: {
        operationalStateId: number;
        operationalStateLabel?: string | undefined;
    }[];
    operationalState: number;
    operationalError: {
        errorStateId: number;
        errorStateLabel?: string | undefined;
        errorStateDetails?: string | undefined;
    };
    countdownTime?: number | null | undefined;
}>;
/**
 * 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.
 * @returns {Behavior.Options<MatterbridgeTemperatureMeasurementServer>} - The default options for the TemperatureMeasurement cluster server.
 */
export declare function getDefaultTemperatureMeasurementClusterServer(measuredValue?: number | null, minMeasuredValue?: number | null, maxMeasuredValue?: number | null): Partial<{
    measuredValue: number | null;
    minMeasuredValue: number | null;
    maxMeasuredValue: number | null;
    tolerance?: number | undefined;
}>;
/**
 * 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.
 * @returns {Behavior.Options<MatterbridgeRelativeHumidityMeasurementServer>} - The default options for the RelativeHumidityMeasurement cluster server.
 */
export declare function getDefaultRelativeHumidityMeasurementClusterServer(measuredValue?: number | null, minMeasuredValue?: number | null, maxMeasuredValue?: number | null): Partial<{
    measuredValue: number | null;
    minMeasuredValue: number | null;
    maxMeasuredValue: number | null;
    tolerance?: number | undefined;
}>;
/**
 * Get the default PressureMeasurement cluster server options.
 *
 * @param {number | null} measuredValue - The measured value for the pressure in kPa x 10.
 * @param {number | null} minMeasuredValue - The minimum measured value for the pressure in kPa x 10.
 * @param {number | null} maxMeasuredValue - The maximum measured value for the pressure in kPa x 10.
 * @returns {Behavior.Options<MatterbridgePressureMeasurementServer>} - The default options for the PressureMeasurement cluster server.
 */
export declare function getDefaultPressureMeasurementClusterServer(measuredValue?: number | null, minMeasuredValue?: number | null, maxMeasuredValue?: number | null): Partial<{
    measuredValue: number | null;
    minMeasuredValue: number | null;
    maxMeasuredValue: number | null;
    tolerance?: number | undefined;
}>;
/**
 * 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.
 *
 * @returns {Behavior.Options<MatterbridgeIlluminanceMeasurementServer>} - The default options for the IlluminanceMeasurement cluster server.
 *
 * @remarks 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 declare function getDefaultIlluminanceMeasurementClusterServer(measuredValue?: number | null, minMeasuredValue?: number | null, maxMeasuredValue?: number | null): Partial<{
    measuredValue: number | null;
    minMeasuredValue: number | null;
    maxMeasuredValue: number | null;
    tolerance?: number | undefined;
    lightSensorType?: number | null | undefined;
}>;
/**
 * 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.
 * @returns {Behavior.Options<MatterbridgeFlowMeasurementServer>} - The default options for the FlowMeasurement cluster server.
 */
export declare function getDefaultFlowMeasurementClusterServer(measuredValue?: number | null, minMeasuredValue?: number | null, maxMeasuredValue?: number | null): Partial<{
    measuredValue: number | null;
    minMeasuredValue: number | null;
    maxMeasuredValue: number | null;
    tolerance?: number | undefined;
}>;
/**
 * 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.
 * @returns {Behavior.Options<MatterbridgeOccupancySensingServer>} - The default options for the OccupancySensing cluster server.
 *
 * @remarks 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 declare function getDefaultOccupancySensingClusterServer(occupied?: boolean, holdTime?: number, holdTimeMin?: number, holdTimeMax?: number): Partial<{
    occupancy: {
        occupied?: boolean | undefined;
    };
    holdTime?: number | undefined;
    pirOccupiedToUnoccupiedDelay?: number | undefined;
    pirUnoccupiedToOccupiedDelay?: number | undefined;
    pirUnoccupiedToOccupiedThreshold?: number | undefined;
    occupancySensorType: number;
    occupancySensorTypeBitmap: {
        pir?: boolean | undefined;
        ultrasonic?: boolean | undefined;
        physicalContact?: boolean | undefined;
    };
    holdTimeLimits?: {
        holdTimeMin: number;
        holdTimeMax: number;
        holdTimeDefault: number;
    } | undefined;
}>;
//# sourceMappingURL=matterbridgeEndpointHelpers.d.ts.map