matterbridge/dist/pluginManager.d.ts

Matterbridge plugin manager for Matter

/**
 * This file contains the Plugins class.
 *
 * @file plugins.ts
 * @author Luca Liguori
 * @created 2024-07-14
 * @version 1.2.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 EventEmitter from 'node:events';
import { LogLevel } from 'node-ansi-logger';
import type { Matterbridge } from './matterbridge.js';
import type { MatterbridgePlatform, PlatformConfig, PlatformSchema } from './matterbridgePlatform.js';
import { RegisteredPlugin } from './matterbridgeTypes.js';
interface PluginManagerEvents {
    added: [name: string];
    removed: [name: string];
    loaded: [name: string];
    enabled: [name: string];
    disabled: [name: string];
    installed: [name: string, version: string | undefined];
    uninstalled: [name: string];
    started: [name: string];
    configured: [name: string];
    shutdown: [name: string];
}
export declare class PluginManager extends EventEmitter<PluginManagerEvents> {
    private _plugins;
    private matterbridge;
    private log;
    constructor(matterbridge: Matterbridge);
    get length(): number;
    get size(): number;
    has(name: string): boolean;
    get(name: string): RegisteredPlugin | undefined;
    set(plugin: RegisteredPlugin): RegisteredPlugin;
    clear(): void;
    array(): RegisteredPlugin[];
    [Symbol.iterator](): MapIterator<RegisteredPlugin>;
    forEach(callback: (plugin: RegisteredPlugin) => Promise<void>): Promise<void>;
    set logLevel(logLevel: LogLevel);
    /**
     * Loads registered plugins from storage.
     *
     * This method retrieves an array of registered plugins from the storage and converts it
     * into a map where the plugin names are the keys and the plugin objects are the values.
     *
     * @returns {Promise<RegisteredPlugin[]>} A promise that resolves to an array of registered plugins.
     */
    loadFromStorage(): Promise<RegisteredPlugin[]>;
    /**
     * Loads registered plugins from storage.
     *
     * This method retrieves an array of registered plugins from the storage and converts it
     * into a map where the plugin names are the keys and the plugin objects are the values.
     *
     * @returns {Promise<RegisteredPlugin[]>} A promise that resolves to an array of registered plugins.
     */
    saveToStorage(): Promise<number>;
    /**
     * Resolves the name of a plugin by loading and parsing its package.json file.
     *
     * @param {string} pluginPath - The path to the plugin or the path to the plugin's package.json file.
     * @returns {Promise<string | null>} A promise that resolves to the path of the plugin's package.json file or null if it could not be resolved.
     */
    resolve(pluginPath: string): Promise<string | null>;
    /**
     * Get the author of a plugin from its package.json.
     *
     * @param {Record<string, string | number | Record<string, string | number | object>>} packageJson - The package.json object of the plugin.
     * @returns {string} The author of the plugin, or 'Unknown author' if not found.
     */
    getAuthor(packageJson: Record<string, string | number | Record<string, string | number | object>>): string;
    /**
     * Get the homepage of a plugin from its package.json.
     *
     * @param {Record<string, string | number | Record<string, string | number | object>>} packageJson - The package.json object of the plugin.
     * @returns {string | undefined} The homepage of the plugin, or undefined if not found.
     */
    getHomepage(packageJson: Record<string, string | number | Record<string, string | number | object>>): string | undefined;
    /**
     * Get the help URL of a plugin from its package.json.
     *
     * @param {Record<string, string | number | Record<string, string | number | object>>} packageJson - The package.json object of the plugin.
     * @returns {string | undefined} The URL to the help page or to the README file, or undefined if not found.
     */
    getHelp(packageJson: Record<string, string | number | Record<string, string | number | object>>): string | undefined;
    /**
     * Get the changelog URL of a plugin from its package.json.
     *
     * @param {Record<string, string | number | Record<string, string | number | object>>} packageJson - The package.json object of the plugin.
     * @returns {string | undefined} The URL to the CHANGELOG file, or undefined if not found.
     */
    getChangelog(packageJson: Record<string, string | number | Record<string, string | number | object>>): string | undefined;
    /**
     * Get the first funding URL(s) of a plugin from its package.json.
     *
     * @param {Record<string, any>} packageJson - The package.json object of the plugin.
     * @returns {string | undefined} The first funding URLs, or undefined if not found.
     */
    getFunding(packageJson: Record<string, any>): string | undefined;
    /**
     * Loads and parse the plugin package.json and returns it.
     *
     * @param {RegisteredPlugin} plugin - The plugin to load the package from.
     * @returns {Promise<Record<string, string | number | object> | null>} A promise that resolves to the parsed package.json object or null if it could not be parsed.
     */
    parse(plugin: RegisteredPlugin): Promise<Record<string, string | number | object> | null>;
    /**
     * Enables a plugin by its name or path.
     *
     * This method enables a plugin by setting its `enabled` property to `true` and saving the updated
     * plugin information to storage. It first checks if the plugin is already registered in the `_plugins` map.
     * If not, it attempts to resolve the plugin's `package.json` file to retrieve its name and enable it.
     *
     * @param {string} nameOrPath - The name or path of the plugin to enable.
     * @returns {Promise<RegisteredPlugin | null>} A promise that resolves to the enabled plugin object, or null if the plugin could not be enabled.
     */
    enable(nameOrPath: string): Promise<RegisteredPlugin | null>;
    /**
     * Enables a plugin by its name or path.
     *
     * This method enables a plugin by setting its `enabled` property to `true` and saving the updated
     * plugin information to storage. It first checks if the plugin is already registered in the `_plugins` map.
     * If not, it attempts to resolve the plugin's `package.json` file to retrieve its name and enable it.
     *
     * @param {string} nameOrPath - The name or path of the plugin to enable.
     * @returns {Promise<RegisteredPlugin | null>} A promise that resolves to the enabled plugin object, or null if the plugin could not be enabled.
     */
    disable(nameOrPath: string): Promise<RegisteredPlugin | null>;
    /**
     * Removes a plugin by its name or path.
     *
     * This method removes a plugin from the `_plugins` map and saves the updated plugin information to storage.
     * It first checks if the plugin is already registered in the `_plugins` map. If not, it attempts to resolve
     * the plugin's `package.json` file to retrieve its name and remove it.
     *
     * @param {string} nameOrPath - The name or path of the plugin to remove.
     * @returns {Promise<RegisteredPlugin | null>} A promise that resolves to the removed plugin object, or null if the plugin could not be removed.
     */
    remove(nameOrPath: string): Promise<RegisteredPlugin | null>;
    /**
     * Adds a plugin by its name or path.
     *
     * This method adds a plugin to the plugins map and saves the updated plugin information to storage.
     * It first resolves the plugin's `package.json` file to retrieve its details. If the plugin is already
     * registered, it logs an info message and returns null. Otherwise, it registers the plugin, enables it,
     * and saves the updated plugin information to storage.
     *
     * @param {string} nameOrPath - The name or path of the plugin to add.
     * @returns {Promise<RegisteredPlugin | null>} A promise that resolves to the added plugin object, or null if the plugin could not be added.
     */
    add(nameOrPath: string): Promise<RegisteredPlugin | null>;
    /**
     * Loads a plugin and returns the corresponding MatterbridgePlatform instance.
     *
     * @param {RegisteredPlugin} plugin - The plugin to load.
     * @param {boolean} start - Optional flag indicating whether to start the plugin after loading. Default is false.
     * @param {string} message - Optional message to pass to the plugin when starting.
     * @param {boolean} configure - Optional flag indicating whether to configure the plugin after loading. Default is false.
     * @returns {Promise<MatterbridgePlatform | undefined>} A Promise that resolves to the loaded MatterbridgePlatform instance or undefined.
     */
    load(plugin: RegisteredPlugin, start?: boolean, message?: string, configure?: boolean): Promise<MatterbridgePlatform | undefined>;
    /**
     * Starts a plugin.
     *
     * @param {RegisteredPlugin} plugin - The plugin to start.
     * @param {string} [message] - Optional message to pass to the plugin's onStart method.
     * @param {boolean} [configure] - Indicates whether to configure the plugin after starting (default false).
     * @returns {Promise<RegisteredPlugin | undefined>} A promise that resolves when the plugin is started successfully, or rejects with an error if starting the plugin fails.
     */
    start(plugin: RegisteredPlugin, message?: string, configure?: boolean): Promise<RegisteredPlugin | undefined>;
    /**
     * Configures a plugin.
     *
     * @param {RegisteredPlugin} plugin - The plugin to configure.
     * @returns {Promise<RegisteredPlugin | undefined>} A promise that resolves when the plugin is configured successfully, or rejects with an error if configuration fails.
     */
    configure(plugin: RegisteredPlugin): Promise<RegisteredPlugin | undefined>;
    /**
     * Shuts down a plugin.
     *
     * This method shuts down a plugin by calling its `onShutdown` method and resetting its state.
     * It logs the shutdown process and optionally removes all devices associated with the plugin.
     *
     * @param {RegisteredPlugin} plugin - The plugin to shut down.
     * @param {string} [reason] - The reason for shutting down the plugin.
     * @param {boolean} [removeAllDevices] - Whether to remove all devices associated with the plugin.
     * @param {boolean} [force] - Whether to force the shutdown even if the plugin is not loaded or started.
     * @returns {Promise<RegisteredPlugin | undefined>} A promise that resolves to the shut down plugin object, or undefined if the shutdown failed.
     */
    shutdown(plugin: RegisteredPlugin, reason?: string, removeAllDevices?: boolean, force?: boolean): Promise<RegisteredPlugin | undefined>;
    /**
     * Loads the configuration for a plugin.
     * If the configuration file exists, it reads the file and returns the parsed JSON data.
     * If the configuration file does not exist, it creates a new file with default configuration and returns it.
     * If any error occurs during file access or creation, it logs an error and return un empty config.
     *
     * @param {RegisteredPlugin} plugin - The plugin for which to load the configuration.
     * @returns {Promise<PlatformConfig>} A promise that resolves to the loaded or created configuration.
     */
    loadConfig(plugin: RegisteredPlugin): Promise<PlatformConfig>;
    /**
     * Saves the configuration of a plugin to a file.
     *
     * This method saves the configuration of the specified plugin to a JSON file in the matterbridge directory.
     * If the plugin's configuration is not found, it logs an error and rejects the promise. If the configuration
     * is successfully saved, it logs a debug message. If an error occurs during the file write operation, it logs
     * the error and rejects the promise.
     *
     * @param {RegisteredPlugin} plugin - The plugin whose configuration is to be saved.
     * @param {boolean} [restartRequired] - Indicates whether a restart is required after saving the configuration.
     * @returns {Promise<void>} A promise that resolves when the configuration is successfully saved, or rejects if an error occurs.
     * @throws {Error} If the plugin's configuration is not found.
     */
    saveConfigFromPlugin(plugin: RegisteredPlugin, restartRequired?: boolean): Promise<void>;
    /**
     * Saves the configuration of a plugin from a JSON object to a file.
     *
     * This method saves the provided configuration of the specified plugin to a JSON file in the matterbridge directory.
     * It first checks if the configuration data is valid by ensuring it contains the correct name and type, and matches
     * the plugin's name. If the configuration data is invalid, it logs an error and returns. If the configuration is
     * successfully saved, it updates the plugin's `configJson` property and logs a debug message. If an error occurs
     * during the file write operation, it logs the error and returns.
     *
     * @param {RegisteredPlugin} plugin - The plugin whose configuration is to be saved.
     * @param {PlatformConfig} config - The configuration data to be saved.
     * @param {boolean} [restartRequired] - Indicates whether a restart is required after saving the configuration.
     * @returns {Promise<void>} A promise that resolves when the configuration is successfully saved, or returns if an error occurs.
     */
    saveConfigFromJson(plugin: RegisteredPlugin, config: PlatformConfig, restartRequired?: boolean): Promise<void>;
    /**
     * Loads the schema for a plugin.
     *
     * This method attempts to load the schema file for the specified plugin. If the schema file is found,
     * it reads and parses the file, updates the schema's title and description, and logs the process.
     * If the schema file is not found, it logs the event and loads a default schema for the plugin.
     *
     * @param {RegisteredPlugin} plugin - The plugin whose schema is to be loaded.
     * @returns {Promise<PlatformSchema>} A promise that resolves to the loaded schema object, or the default schema if the schema file is not found.
     */
    loadSchema(plugin: RegisteredPlugin): Promise<PlatformSchema>;
    /**
     * Returns the default schema for a plugin.
     *
     * This method generates a default schema object for the specified plugin. The schema includes
     * metadata such as the plugin's title, description, version, and author. It also defines the
     * properties of the schema, including the plugin's name, type, debug flag, and unregisterOnShutdown flag.
     *
     * @param {RegisteredPlugin} plugin - The plugin for which the default schema is to be generated.
     * @returns {PlatformSchema} The default schema object for the plugin.
     */
    getDefaultSchema(plugin: RegisteredPlugin): PlatformSchema;
}
export {};
//# sourceMappingURL=pluginManager.d.ts.map