matterbridge/dist/matterbridgePlatform.d.ts

Matterbridge plugin manager for Matter

/**
 * This file contains the class MatterbridgePlatform.
 *
 * @file matterbridgePlatform.ts
 * @author Luca Liguori
 * @created 2024-03-21
 * @version 1.2.1
 * @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, LogLevel } from 'node-ansi-logger';
import { NodeStorage, NodeStorageManager } from 'node-persist-manager';
import { Matterbridge } from './matterbridge.js';
import { MatterbridgeEndpoint } from './matterbridgeEndpoint.js';
export type PlatformConfigValue = string | number | boolean | bigint | object | undefined | null;
export type PlatformConfig = Record<string, PlatformConfigValue>;
export interface DefaultPlatformConfig {
    name: string;
    type: string;
    version: string;
    whiteList?: string[];
    blackList?: string[];
    debug: boolean;
    unregisterOnShutdown: boolean;
}
export type PlatformSchemaValue = string | number | boolean | bigint | object | undefined | null;
export type PlatformSchema = Record<string, PlatformSchemaValue>;
/**
 * Represents the base Matterbridge platform. It is extended by the MatterbridgeAccessoryPlatform and MatterbridgeServicePlatform classes.
 *
 */
export declare class MatterbridgePlatform {
    /** The Matterbridge instance of this Platform. */
    matterbridge: Matterbridge;
    /** The logger instance for this platform. */
    log: AnsiLogger;
    /** The configuration for this platform. */
    config: PlatformConfig;
    /** The name of the platform. Will be set by the loadPlugin() method using the package.json value. */
    name: string;
    /** The type of the platform. Will be set by the extending classes. */
    type: string;
    /** The version of the platform. Will be set by the loadPlugin() method using the package.json value */
    version: string;
    /** Platform node storage manager. */
    storage: NodeStorageManager;
    /** Platform context storage. */
    context?: NodeStorage;
    readonly selectDevice: Map<string, {
        serial: string;
        name: string;
        configUrl?: string;
        icon?: string;
        entities?: {
            name: string;
            description: string;
            icon?: string;
        }[];
    }>;
    readonly selectEntity: Map<string, {
        name: string;
        description: string;
        icon?: string;
    }>;
    private _contextReady;
    private _selectDeviceContextReady;
    private _selectEntityContextReady;
    /** The ready promise for the platform, which resolves when the platform is fully initialized. */
    ready: Promise<void>;
    /** Registered MatterbridgeEndpoint Map by uniqueId */
    private readonly _registeredEndpoints;
    /** Registered MatterbridgeEndpoint Map by deviceName */
    private readonly _registeredEndpointsByName;
    /**
     * Creates an instance of the base MatterbridgePlatform.
     * It is extended by the MatterbridgeAccessoryPlatform and MatterbridgeServicePlatform classes.
     * Each plugin must extend the MatterbridgeAccessoryPlatform and MatterbridgeServicePlatform classes.
     *
     * @param {Matterbridge} matterbridge - The Matterbridge instance.
     * @param {AnsiLogger} log - The logger instance.
     * @param {PlatformConfig} config - The platform configuration.
     */
    constructor(matterbridge: Matterbridge, log: AnsiLogger, config: PlatformConfig);
    /**
     * This method must be overridden in the extended class.
     * It is called when the platform is started.
     * Use this method to create the MatterbridgeEndpoints and call this.registerDevice().
     *
     * @param {string} [reason] - The reason for starting.
     * @throws {Error} - Throws an error if the method is not overridden.
     */
    onStart(reason?: string): Promise<void>;
    /**
     * This method can be overridden in the extended class. In this case always call super.onConfigure() to save the select and run checkEndpointNumbers().
     * It is called after the platform has started.
     * Use this method to perform any configuration of your devices and to override the value of the attributes that are persistent and stored in the
     * matter storage (i.e. the onOff attribute of the OnOff cluster).
     */
    onConfigure(): Promise<void>;
    /**
     * This method can be overridden in the extended class. In this case always call super.onShutdown() to save the selects, run checkEndpointNumbers() and cleanup memory.
     * It is called when the platform is shutting down.
     * Use this method to clean up any resources you used in the constructor or onStart.
     *
     * @param {string} [reason] - The reason for shutting down.
     */
    onShutdown(reason?: string): Promise<void>;
    /**
     * Called when the logger level is changed.
     *
     * @param {LogLevel} logLevel The new logger level.
     */
    onChangeLoggerLevel(logLevel: LogLevel): Promise<void>;
    /**
     * Called when a plugin config includes an action button or an action button with text field.
     *
     * @param {string} action The action triggered by the button in plugin config.
     * @param {string} value The value of the field of the action button.
     * @param {string} id The id of the schema associated with the action.
     * @param {PlatformConfig} formData The changed form data of the plugin.
     *
     * @remarks
     * This method can be overridden in the extended class.
     *
     * Use this method to handle the action defined in the plugin schema:
     * ```json
     *  "addDevice": {
     *      "description": "Manually add a device that has not been discovered with mdns:",
     *      "type": "boolean",
     *      "buttonText": "ADD",      // The text on the button. This is used when the action doesn't include a text field.
     *      "buttonField": "ADD",     // The text on the button. This is used when the action includes a text field.
     *      "buttonClose": false,     // optional, default is false. When true, the dialog will close after the action is sent.
     *      "buttonSave": false,      // optional, default is false. When true, the dialog will close and trigger the restart required after the action is sent.
     *      "textPlaceholder": "Enter the device IP address",   // optional: the placeholder text for the text field.
     *      "default": false
     *  },
     * ```
     */
    onAction(action: string, value?: string, id?: string, formData?: PlatformConfig): Promise<void>;
    /**
     * Called when the plugin config has been updated.
     *
     * @param {PlatformConfig} config The new plugin config.
     */
    onConfigChanged(config: PlatformConfig): Promise<void>;
    /**
     * Retrieves the devices registered with the platform.
     *
     * @returns {MatterbridgeEndpoint[]} The registered devices.
     */
    getDevices(): MatterbridgeEndpoint[];
    /**
     * Checks if a device with this name is already registered in the platform.
     *
     * @param {string} deviceName - The device name to check.
     * @returns {boolean} True if the device is already registered, false otherwise.
     */
    hasDeviceName(deviceName: string): boolean;
    /**
     * Registers a device with the Matterbridge platform.
     *
     * @param {MatterbridgeEndpoint} device - The device to register.
     */
    registerDevice(device: MatterbridgeEndpoint): Promise<void>;
    /**
     * Unregisters a device registered with the Matterbridge platform.
     *
     * @param {MatterbridgeEndpoint} device - The device to unregister.
     */
    unregisterDevice(device: MatterbridgeEndpoint): Promise<void>;
    /**
     * Unregisters all devices registered with the Matterbridge platform.
     *
     * @param {number} [delay] - The delay in milliseconds between removing each bridged endpoint (default: 0).
     */
    unregisterAllDevices(delay?: number): Promise<void>;
    /**
     * Saves the select devices and entities to storage.
     *
     * This method saves the current state of `selectDevice` and `selectEntity` maps to their respective storage.
     * It logs the number of items being saved and ensures that the storage is properly closed after saving.
     *
     * @returns {Promise<void>} A promise that resolves when the save operation is complete.
     */
    private saveSelects;
    /**
     * Clears all the select device and entity maps.
     *
     * @returns {void}
     */
    clearSelect(): Promise<void>;
    /**
     * Clears the select for a single device.
     *
     * @param {string} serial - The serial of the device to clear.
     * @returns {void}
     */
    clearDeviceSelect(serial: string): Promise<void>;
    /**
     * Set the select device in the platform map.
     *
     * @param {string} serial - The serial number of the device.
     * @param {string} name - The name of the device.
     * @param {string} [configUrl] - The configuration URL of the device.
     * @param {string} [icon] - The icon of the device: 'wifi', 'ble', 'hub'
     * @param {Array<{ name: string; description: string; icon?: string }>} [entities] - The entities associated with the device.
     * @returns {void}
     */
    setSelectDevice(serial: string, name: string, configUrl?: string, icon?: string, entities?: {
        name: string;
        description: string;
        icon?: string;
    }[]): void;
    /**
     * Set the select device entity in the platform map.
     *
     * @param {string} serial - The serial number of the device.
     * @param {string} entityName - The name of the entity.
     * @param {string} entityDescription - The description of the entity.
     * @param {string} [entityIcon] - The icon of the entity: 'wifi', 'ble', 'hub', 'component', 'matter'
     * @returns {void}
     */
    setSelectDeviceEntity(serial: string, entityName: string, entityDescription: string, entityIcon?: string): void;
    /**
     * Retrieves the select devices from the platform map.
     *
     * @returns {{ pluginName: string; serial: string; name: string; configUrl?: string; icon?: string; entities?: { name: string; description: string; icon?: string }[] }[]} The selected devices array.
     */
    getSelectDevices(): {
        pluginName: string;
        serial: string;
        name: string;
        configUrl?: string;
        icon?: string;
        entities?: {
            name: string;
            description: string;
            icon?: string;
        }[];
    }[];
    /**
     * Set the select entity in the platform map.
     *
     * @param {string} name - The entity name.
     * @param {string} description - The entity description.
     * @param {string} [icon] - The entity icon: 'wifi', 'ble', 'hub', 'component', 'matter'
     * @returns {void}
     */
    setSelectEntity(name: string, description: string, icon?: string): void;
    /**
     * Retrieve the select entities.
     *
     * @returns {{ pluginName: string; name: string; description: string; icon?: string }[]} The select entities array.
     */
    getSelectEntities(): {
        pluginName: string;
        name: string;
        description: string;
        icon?: string;
    }[];
    /**
     * Verifies if the Matterbridge version meets the required version.
     *
     * @param {string} requiredVersion - The required version to compare against.
     * @returns {boolean} True if the Matterbridge version meets or exceeds the required version, false otherwise.
     */
    verifyMatterbridgeVersion(requiredVersion: string): boolean;
    /**
     * Validates if a device is allowed based on the whitelist and blacklist configurations.
     * The blacklist has priority over the whitelist.
     *
     * @param {string | string[]} device - The device name(s) to validate.
     * @param {boolean} [log] - Whether to log the validation result.
     * @returns {boolean} - Returns true if the device is allowed, false otherwise.
     */
    validateDevice(device: string | string[], log?: boolean): boolean;
    /**
     * Validates if an entity is allowed based on the entity blacklist and device-entity blacklist configurations.
     *
     * @param {string} device - The device to which the entity belongs.
     * @param {string} entity - The entity to validate.
     * @param {boolean} [log] - Whether to log the validation result.
     * @returns {boolean} - Returns true if the entity is allowed, false otherwise.
     */
    validateEntity(device: string, entity: string, log?: boolean): boolean;
    /**
     * Checks and updates the endpoint numbers for Matterbridge devices.
     *
     * This method retrieves the list of Matterbridge devices and their child endpoints,
     * compares their current endpoint numbers with the stored ones, and updates the storage
     * if there are any changes. It logs the changes and updates the endpoint numbers accordingly.
     *
     * @returns {Promise<number>} The size of the updated endpoint map, or -1 if storage is not available.
     */
    checkEndpointNumbers(): Promise<number>;
}
//# sourceMappingURL=matterbridgePlatform.d.ts.map