@matterbridge/core 3.5.3 → 3.5.4-dev-20260211-520e349

package/dist/matterbridge.d.ts

@@ -1,26 +1,3 @@
-/**
- * This file contains the class Matterbridge.
- *
- * @file matterbridge.ts
- * @author Luca Liguori
- * @created 2023-12-29
- * @version 1.6.2
- * @license Apache-2.0
- *
- * Copyright 2023, 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 EventEmitter from 'node:events';
 import { AnsiLogger, LogLevel } from 'node-ansi-logger';
 import { NodeStorageManager, NodeStorage } from 'node-persist-manager';
@@ -35,9 +12,6 @@ import { PluginManager } from './pluginManager.js';
 import { DeviceManager } from './deviceManager.js';
 import { MatterbridgeEndpoint } from './matterbridgeEndpoint.js';
 import { Frontend } from './frontend.js';
-/**
- * Represents the Matterbridge events.
- */
 interface MatterbridgeEvents {
     shutdown: [];
     restart: [];
@@ -57,66 +31,40 @@ interface MatterbridgeEvents {
     takeheapsnapshot: [];
     triggergarbagecollection: [];
 }
-/**
- * Represents the Matterbridge application.
- */
 export declare class Matterbridge extends EventEmitter<MatterbridgeEvents> {
-    /** Matterbridge system information */
     systemInformation: SystemInformation;
-    /** It indicates the home directory of the Matterbridge application. The home directory is the base directory where Matterbridge creates the matterbridge directories (os.homedir() if not overridden). */
     homeDirectory: string;
-    /** It indicates the root directory of the Matterbridge application. The root directory is the directory where Matterbridge is executed. */
     rootDirectory: string;
-    /** It indicates where the directory .matterbridge is located. */
     matterbridgeDirectory: string;
-    /** It indicates where the directory Matterbridge is located. */
     matterbridgePluginDirectory: string;
-    /** It indicates where the directory .mattercert is located. */
     matterbridgeCertDirectory: string;
-    /** It indicates the global modules directory for npm. */
     globalModulesDirectory: string;
     matterbridgeVersion: string;
     matterbridgeLatestVersion: string;
     matterbridgeDevVersion: string;
     frontendVersion: string;
-    /** It indicates the mode of the Matterbridge instance. It can be 'bridge', 'childbridge', 'controller' or ''. */
     bridgeMode: 'bridge' | 'childbridge' | 'controller' | '';
-    /** It indicates the restart mode of the Matterbridge instance. It can be 'service', 'docker' or ''. */
     restartMode: 'service' | 'docker' | '';
-    /** It indicates whether virtual mode is enabled and its type. The virtual mode control the creation of "Update matterbridge" and "Restart matterbridge" endpoints. */
     virtualMode: 'disabled' | 'outlet' | 'light' | 'switch' | 'mounted_switch';
-    /** It indicates the Matterbridge profile in use. */
     readonly profile: string | undefined;
-    /** Matterbridge logger */
     readonly log: AnsiLogger;
-    /** Matterbridge logger level */
     logLevel: LogLevel;
-    /** Whether to log to a file */
     fileLogger: boolean;
-    /** Matter logger */
     readonly matterLog: AnsiLogger;
-    /** Matter logger level */
     matterLogLevel: LogLevel;
-    /** Whether to log Matter to a file */
     matterFileLogger: boolean;
     readonly readOnly: boolean;
     readonly shellyBoard: boolean;
     shellySysUpdate: boolean;
     shellyMainUpdate: boolean;
-    /** It indicates whether a restart is required. It can be unset in childbridge mode by restarting the plugin that triggered the restart. */
     restartRequired: boolean;
-    /** It indicates whether a fixed restart is required. It cannot be unset once set. */
     fixedRestartRequired: boolean;
-    /** It indicates whether an update is available. */
     updateRequired: boolean;
     readonly plugins: PluginManager;
     readonly devices: DeviceManager;
     readonly frontend: Frontend;
-    /** Matterbridge node storage manager created in the directory 'storage' in matterbridgeDirectory */
     nodeStorage: NodeStorageManager | undefined;
-    /** Matterbridge node context created with name 'matterbridge' */
     nodeContext: NodeStorage | undefined;
-    /** The main instance of the Matterbridge class (singleton) */
     protected static instance: Matterbridge | undefined;
     shutdown: boolean;
     private readonly failCountLimit;
@@ -132,32 +80,19 @@ export declare class Matterbridge extends EventEmitter<MatterbridgeEvents> {
     private sigtermHandler;
     private exceptionHandler;
     private rejectionHandler;
-    /** Matter environment default */
     private readonly environment;
-    /** Matter storage service from environment default */
     matterStorageService: StorageService | undefined;
-    /** Matter storage manager created with name 'Matterbridge' */
     matterStorageManager: StorageManager | undefined;
-    /** Matter matterbridge storage context created in the storage manager with name 'persist' */
     matterbridgeContext: StorageContext | undefined;
     controllerContext: StorageContext | undefined;
-    /** Matter mdns interface e.g. 'eth0' or 'wlan0' or 'Wi-Fi' */
     mdnsInterface: string | undefined;
-    /** Matter listeningAddressIpv4 address */
     ipv4Address: string | undefined;
-    /** Matter listeningAddressIpv6 address */
     ipv6Address: string | undefined;
-    /** Matter commissioning port */
     port: number | undefined;
-    /** Matter commissioning passcode */
     passcode: number | undefined;
-    /** Matter commissioning discriminator */
     discriminator: number | undefined;
-    /** Matter device certification */
     certification: DeviceCertification.Configuration | undefined;
-    /** Matter server node in bridge mode */
     serverNode: ServerNode<ServerNode.RootEndpoint> | undefined;
-    /** Matter aggregator node in bridge mode */
     aggregatorNode: Endpoint<AggregatorEndpoint> | undefined;
     aggregatorVendorId: VendorId;
     aggregatorVendorName: string;
@@ -166,379 +101,55 @@ export declare class Matterbridge extends EventEmitter<MatterbridgeEvents> {
     aggregatorDeviceType: DeviceTypeId;
     aggregatorSerialNumber: string | undefined;
     aggregatorUniqueId: string | undefined;
-    /** Advertising nodes map: time advertising started keyed by storeId */
     advertisingNodes: Map<string, number>;
-    /** Broadcast server */
     private readonly server;
     private readonly verbose;
-    /** We load asyncronously so is private */
     private constructor();
-    /** Close the broadcast server */
     destroy(): void;
-    /**
-     * Get a platform matterbridge object
-     *
-     * @returns {PlatformMatterbridge} The platform matterbridge object.
-     */
     getPlatformMatterbridge(): PlatformMatterbridge;
-    /**
-     *  Get a shared matterbridge object
-     *
-     * @returns {SharedMatterbridge} The shared matterbridge object.
-     */
     getSharedMatterbridge(): SharedMatterbridge;
     private msgHandler;
-    /**
-     * Loads an instance of the Matterbridge class.
-     * If an instance already exists, return that instance.
-     *
-     * @param {boolean} initialize - Whether to initialize the Matterbridge instance after loading. Defaults to false.
-     * @returns {Matterbridge} A promise that resolves to the Matterbridge instance.
-     */
     static loadInstance(initialize?: boolean): Promise<Matterbridge>;
-    /**
-     * Initializes the Matterbridge application.
-     *
-     * @remarks
-     * This method performs the necessary setup and initialization steps for the Matterbridge application.
-     * It displays the help information if the 'help' parameter is provided, sets up the logger, checks the
-     * node version, registers signal handlers, initializes storage, and parses the command line.
-     *
-     * @returns {Promise<void>} A Promise that resolves when the initialization is complete.
-     */
     private initialize;
-    /**
-     * Resolve a file path located in the `@matterbridge/core` distribution directory.
-     *
-     * @remarks
-     * Matterbridge spawns ESM workers from built JavaScript files (e.g. `workerCheckUpdates.js`).
-     * Depending on how the code is executed:
-     * - **Production**: `import.meta.url` points inside `.../node_modules/@matterbridge/core/dist/...`
-     *   and the worker file is usually alongside the current module.
-     * - **Development / tests**: `import.meta.url` may point inside `.../packages/core/src/...`
-     *   while the worker file exists in `.../packages/core/dist/...`.
-     *
-     * This helper tries both locations and returns the first existing candidate.
-     *
-     * @param {string} fileName - Worker/build artifact file name, e.g. `workerGlobalPrefix.js`.
-     * @returns {string} Absolute path to the resolved file. If none exists, returns the first candidate (best effort).
-     */
     resolveWorkerDistFilePath(fileName: string): string;
-    /**
-     * Parses the command line arguments and performs the corresponding actions.
-     *
-     * @private
-     * @returns {Promise<void>} A promise that resolves when the command line arguments have been processed, or the process exits.
-     */
     private parseCommandLine;
-    /**
-     * Asynchronously loads and starts the registered plugins.
-     *
-     * This method is responsible for initializing and starting all enabled plugins.
-     * It ensures that each plugin is properly loaded and started before the bridge starts.
-     *
-     * @param {boolean} [wait] - If true, the method will wait for all plugins to be fully loaded and started before resolving. Defaults to false.
-     * @param {boolean} [start] - If true, the method will start the plugins after loading them. Defaults to true.
-     * @returns {Promise<void>} A promise that resolves when all plugins have been loaded and started.
-     */
     private startPlugins;
-    /**
-     * Registers the process handlers for uncaughtException, unhandledRejection, SIGINT and SIGTERM.
-     * - When an uncaught exception occurs, the exceptionHandler logs the error message and stack trace.
-     * - When an unhandled promise rejection occurs, the rejectionHandler logs the reason and stack trace.
-     * - When either of SIGINT and SIGTERM signals are received, the cleanup method is called with an appropriate message.
-     */
     private registerProcessHandlers;
-    /**
-     * Deregisters the process uncaughtException, unhandledRejection, SIGINT and SIGTERM signal handlers.
-     */
     private deregisterProcessHandlers;
-    /**
-     * Logs the node and system information.
-     *
-     * @remarks
-     * This method retrieves and logs various details about the host system, including:
-     * - IP address information (IPv4, IPv6, MAC address)
-     * - Node.js version
-     * - Hostname and user information
-     * - Operating system details (type, release, platform, architecture)
-     * - Memory usage statistics
-     * - Uptime information for both the system and the process
-     */
     private logNodeAndSystemInfo;
-    /**
-     * Set the logger logLevel for the Matterbridge classes and call onChangeLoggerLevel() for each plugin.
-     *
-     * @param {LogLevel} logLevel The logger logLevel to set.
-     * @returns {Promise<LogLevel>} A promise that resolves when the logLevel has been set.
-     */
     setLogLevel(logLevel: LogLevel): Promise<LogLevel>;
-    /**
-     * Get the current logger logLevel.
-     *
-     * @returns {LogLevel} The current logger logLevel.
-     */
     getLogLevel(): MaybePromise<LogLevel>;
-    /**
-     * Creates a MatterLogger function to show the matter.js log messages in AnsiLogger (for the frontend).
-     * It also logs to file (matter.log) if fileLogger is true.
-     *
-     * @param {boolean} fileLogger - Whether to log to file or not.
-     * @returns {(text: string, message: Diagnostic.Message) => void} The MatterLogger function. \x1b[35m for violet \x1b[34m is blue
-     */
     private createDestinationMatterLogger;
-    /**
-     * Restarts the process by exiting the current instance and loading a new instance (/api/restart).
-     *
-     * @returns {Promise<void>} A promise that resolves when the restart is completed.
-     */
     restartProcess(): Promise<void>;
-    /**
-     * Shut down the process (/api/shutdown).
-     *
-     * @returns {Promise<void>} A promise that resolves when the shutdown is completed.
-     */
     shutdownProcess(): Promise<void>;
-    /**
-     * Update matterbridge and shut down the process (virtual device 'Update Matterbridge').
-     *
-     * @returns {Promise<void>} A promise that resolves when the update is completed.
-     */
     updateProcess(): Promise<void>;
-    /**
-     * Unregister all devices and shut down the process (/api/unregister).
-     *
-     * @param {number} [timeout] - The timeout duration to wait for the message exchange to complete in milliseconds. Default is 1000.
-     *
-     * @returns {Promise<void>} A promise that resolves when the cleanup is completed.
-     */
     unregisterAndShutdownProcess(timeout?: number): Promise<void>;
-    /**
-     * Reset commissioning and shut down the process (/api/reset).
-     *
-     * @returns {Promise<void>} A promise that resolves when the cleanup is completed.
-     */
     shutdownProcessAndReset(): Promise<void>;
-    /**
-     * Factory reset and shut down the process (/api/factory-reset).
-     *
-     * @returns {Promise<void>} A promise that resolves when the cleanup is completed.
-     */
     shutdownProcessAndFactoryReset(): Promise<void>;
-    /**
-     * Cleans up the Matterbridge instance.
-     *
-     * @param {string} message - The cleanup message.
-     * @param {boolean} [restart] - Indicates whether to restart the instance after cleanup. Default is `false`.
-     * @param {number} [pause] - The pause in ms to wait for the message exchange to complete in milliseconds. Default is 1000.
-     *
-     * @returns {Promise<void>} A promise that resolves when the cleanup is completed.
-     */
     private cleanup;
-    /**
-     * Starts the Matterbridge in bridge mode.
-     *
-     * @private
-     * @returns {Promise<void>} A promise that resolves when the Matterbridge is started.
-     */
     private startBridge;
-    /**
-     * Starts the Matterbridge in childbridge mode.
-     *
-     * @param {number} [delay] - The delay before starting the childbridge. Default is 1000 milliseconds.
-     *
-     * @returns {Promise<void>} A promise that resolves when the Matterbridge is started.
-     */
     private startChildbridge;
-    /**
-     * Starts the Matterbridge controller.
-     *
-     * @private
-     * @returns {Promise<void>} A promise that resolves when the Matterbridge is started.
-     */
     private startController;
-    /**                                                                                                                                   */
-    /**                                                     Matter.js methods                                                             */
-    /**                                                                                                                                   */
-    /**
-     * Starts the matter storage with name Matterbridge, create the matterbridge context and performs a backup.
-     *
-     * @returns {Promise<void>} - A promise that resolves when the storage is started.
-     */
     private startMatterStorage;
-    /**
-     * Makes a backup copy of the specified matter storage directory.
-     *
-     * @param {string} storageName - The name of the storage directory to be backed up.
-     * @param {string} backupName - The name of the backup directory to be created.
-     * @private
-     * @returns {Promise<void>} A promise that resolves when the has been done.
-     */
     private backupMatterStorage;
-    /**
-     * Stops the matter storage.
-     *
-     * @returns {Promise<void>} A promise that resolves when the storage is stopped.
-     */
     private stopMatterStorage;
-    /**
-     * Creates a server node storage context.
-     *
-     * @param {string} storeId - The storeId.
-     * @param {string} deviceName - The name of the device.
-     * @param {DeviceTypeId} deviceType - The device type of the device.
-     * @param {number} vendorId - The vendor ID.
-     * @param {string} vendorName - The vendor name.
-     * @param {number} productId - The product ID.
-     * @param {string} productName - The product name.
-     * @param {string} [serialNumber] - The serial number of the device (optional).
-     * @param {string} [uniqueId] - The unique ID of the device (optional).
-     * @returns {Promise<StorageContext>} The storage context for the commissioning server.
-     */
     private createServerNodeContext;
-    /**
-     * Creates a server node.
-     *
-     * @param {StorageContext} storageContext - The storage context for the server node.
-     * @param {number} [port] - The port number for the server node. Defaults to 5540.
-     * @param {number} [passcode] - The passcode for the server node. Defaults to 20242025.
-     * @param {number} [discriminator] - The discriminator for the server node. Defaults to 3850.
-     * @returns {Promise<ServerNode<ServerNode.RootEndpoint>>} A promise that resolves to the created server node.
-     */
     private createServerNode;
-    /**
-     * Gets the matter sanitized data of the specified server node.
-     *
-     * @param {ServerNode} [serverNode] - The server node to start.
-     * @returns {ApiMatter} The sanitized data of the server node.
-     */
     getServerNodeData(serverNode: ServerNode<ServerNode.RootEndpoint>): ApiMatter;
-    /**
-     * Starts the specified server node.
-     *
-     * @param {ServerNode} [matterServerNode] - The server node to start.
-     * @returns {Promise<void>} A promise that resolves when the server node has started.
-     */
     private startServerNode;
-    /**
-     * Stops the specified server node.
-     *
-     * @param {ServerNode} matterServerNode - The server node to stop.
-     * @param {number} [timeout] - The timeout in milliseconds for stopping the server node. Defaults to 10 seconds.
-     * @returns {Promise<void>} A promise that resolves when the server node has stopped.
-     */
     private stopServerNode;
-    /**
-     * Creates an aggregator node with the specified storage context.
-     *
-     * @param {StorageContext} storageContext - The storage context for the aggregator node.
-     * @returns {Promise<Endpoint<AggregatorEndpoint>>} A promise that resolves to the created aggregator node.
-     */
     private createAggregatorNode;
-    /**
-     * Creates and configures the server node for an accessory plugin for a given device.
-     *
-     * @param {Plugin} plugin - The plugin to configure.
-     * @param {MatterbridgeEndpoint} device - The device to associate with the plugin.
-     * @returns {Promise<void>} A promise that resolves when the server node for the accessory plugin is created and configured.
-     */
     private createAccessoryPlugin;
-    /**
-     * Creates and configures the server node and the aggregator node for a dynamic plugin.
-     *
-     * @param {Plugin} plugin - The plugin to configure.
-     * @returns {Promise<void>} A promise that resolves when the server node and the aggregator node for the dynamic plugin is created and configured.
-     */
     private createDynamicPlugin;
-    /**
-     * Creates and configures the server node for a single not bridged device.
-     *
-     * @param {Plugin} plugin - The plugin to configure.
-     * @param {MatterbridgeEndpoint} device - The device to associate with the plugin.
-     * @returns {Promise<void>} A promise that resolves when the server node for the accessory plugin is created and configured.
-     */
     private createDeviceServerNode;
-    /**
-     * Adds a MatterbridgeEndpoint to the specified plugin.
-     *
-     * @param {string} pluginName - The name of the plugin.
-     * @param {MatterbridgeEndpoint} device - The device to add as a bridged endpoint.
-     * @returns {Promise<void>} A promise that resolves when the bridged endpoint has been added.
-     */
     addBridgedEndpoint(pluginName: string, device: MatterbridgeEndpoint): Promise<void>;
-    /**
-     * Removes a MatterbridgeEndpoint from the specified plugin.
-     *
-     * @param {string} pluginName - The name of the plugin.
-     * @param {MatterbridgeEndpoint} device - The device to remove as a bridged endpoint.
-     * @returns {Promise<void>} A promise that resolves when the bridged endpoint has been removed.
-     */
     removeBridgedEndpoint(pluginName: string, device: MatterbridgeEndpoint): Promise<void>;
-    /**
-     * Removes all bridged endpoints from the specified plugin.
-     *
-     * @param {string} pluginName - The name of the plugin.
-     * @param {number} [delay] - The delay in milliseconds between removing each bridged endpoint (default: 0).
-     * @returns {Promise<void>} A promise that resolves when all bridged endpoints have been removed.
-     *
-     * @remarks
-     * This method iterates through all devices in the DeviceManager and removes each bridged endpoint associated with the specified plugin.
-     * It also applies a delay between each removal if specified.
-     * The delay is useful to allow the controllers to receive a single subscription for each device removed.
-     */
     removeAllBridgedEndpoints(pluginName: string, delay?: number): Promise<void>;
-    /**
-     * Registers a virtual device.
-     * Virtual devices are only supported in bridge mode and childbridge mode with a DynamicPlatform.
-     *
-     * The virtual device is created as an instance of `Endpoint` with the provided device type.
-     * When the virtual device is turned on, the provided callback function is executed.
-     * The onOff state of the virtual device always reverts to false when the device is turned on.
-     *
-     * @param { string } pluginName - The name of the plugin to register the virtual device under.
-     * @param { string } name - The name of the virtual device.
-     * @param { 'light' | 'outlet' | 'switch' | 'mounted_switch' } type - The type of the virtual device.
-     * @param { () => Promise<void> } callback - The callback to call when the virtual device is turned on.
-     *
-     * @returns {Promise<boolean>} A promise that resolves to true if the virtual device was successfully registered, false otherwise.
-     *
-     * @remarks
-     * The virtual devices don't show up in the device list of the frontend.
-     * Type 'switch' is not supported by Alexa and 'mounted_switch' is not supported by Apple Home.
-     */
     addVirtualEndpoint(pluginName: string, name: string, type: 'light' | 'outlet' | 'switch' | 'mounted_switch', callback: () => Promise<void>): Promise<boolean>;
-    /**
-     * Subscribes to the attribute change event for the given device and plugin.
-     * Specifically, it listens for changes in the 'reachable' attribute of the
-     * BridgedDeviceBasicInformationServer cluster server of the bridged device or BasicInformationServer cluster server of server node.
-     *
-     * @param {Plugin} plugin - The plugin associated with the device.
-     * @param {MatterbridgeEndpoint} device - The device to subscribe to attribute changes for.
-     * @returns {Promise<void>} A promise that resolves when the subscription is set up.
-     */
     private subscribeAttributeChanged;
-    /**
-     * Sanitizes the fabric information by converting bigint properties to strings because `res.json` doesn't support bigint.
-     *
-     * @param {ExposedFabricInformation[]} fabricInfo - The array of exposed fabric information objects.
-     * @returns {SanitizedExposedFabricInformation[]} An array of sanitized exposed fabric information objects.
-     */
     private sanitizeFabricInformations;
-    /**
-     * Sanitizes the session information by converting bigint properties to strings because `res.json` doesn't support bigint.
-     *
-     * @param {SessionsBehavior.Session[]} sessions - The array of session information objects.
-     * @returns {SanitizedSession[]} An array of sanitized session information objects.
-     */
     private sanitizeSessionInformation;
-    /**
-     * Sets the reachability of the specified aggregator node bridged devices and trigger.
-     *
-     * @param {Endpoint<AggregatorEndpoint>} aggregatorNode - The aggregator node to set the reachability for.
-     * @param {boolean} reachable - A boolean indicating the reachability status to set.
-     */
     private setAggregatorReachability;
     private getVendorIdName;
 }
 export {};
-//# sourceMappingURL=matterbridge.d.ts.map