matterbridge 3.5.0 → 3.5.1-dev-20260121-22e98b4

package/dist/pluginManager.d.ts

@@ -1,26 +1,3 @@
-/**
- * This file contains the Plugins class.
- *
- * @file plugins.ts
- * @author Luca Liguori
- * @created 2024-07-14
- * @version 1.3.5
- * @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';
@@ -38,9 +15,6 @@ interface PluginManagerEvents {
     configured: [name: string];
     shutdown: [name: string];
 }
-/**
- * Manages Matterbridge plugins.
- */
 export declare class PluginManager extends EventEmitter<PluginManagerEvents> {
     private readonly matterbridge;
     private readonly _plugins;
@@ -48,325 +22,46 @@ export declare class PluginManager extends EventEmitter<PluginManagerEvents> {
     private readonly server;
     private readonly debug;
     private readonly verbose;
-    /**
-     * Creates an instance of PluginManager.
-     *
-     * @param {Matterbridge} matterbridge - The Matterbridge instance.
-     */
     constructor(matterbridge: Matterbridge);
     destroy(): void;
     private msgHandler;
-    /**
-     * Gets the number of plugins.
-     *
-     * @returns {number} The number of plugins.
-     */
     get length(): number;
-    /**
-     * Gets the number of plugins.
-     *
-     * @returns {number} The number of plugins.
-     */
     get size(): number;
-    /**
-     * Checks if a plugin with the specified name exists.
-     *
-     * @param {string} name - The name of the plugin.
-     * @returns {boolean} True if the plugin exists, false otherwise.
-     */
     has(name: string): boolean;
-    /**
-     * Gets a plugin by its name.
-     *
-     * @param {string} name - The name of the plugin.
-     * @returns {Plugin | undefined} The plugin, or undefined if not found.
-     */
     get(name: string): Plugin | undefined;
-    /**
-     * Adds a plugin to the manager.
-     *
-     * @param {Plugin} plugin - The plugin to add.
-     * @returns {Plugin} The added plugin.
-     */
     set(plugin: Plugin): Plugin;
-    /**
-     * Clears all plugins from the manager.
-     */
     clear(): void;
-    /**
-     * Converts a plugin or API plugin to a storage plugin.
-     *
-     * @param {Plugin | ApiPlugin} plugin - The plugin or API plugin to convert.
-     * @returns {StoragePlugin} The converted storage plugin.
-     */
     private toStoragePlugin;
-    /**
-     * Converts a plugin to an API plugin.
-     *
-     * @param {Plugin} plugin - The plugin to convert.
-     * @returns {ApiPlugin} The converted API plugin.
-     */
     private toApiPlugin;
-    /**
-     * Gets an array of all plugins.
-     *
-     * @returns {Plugin[]} An array of all plugins.
-     */
     array(): Plugin[];
-    /**
-     * Gets a StoragePlugin array of all plugins suitable for serialization.
-     *
-     * @returns {StoragePlugin[]} An array of all plugins.
-     */
     storagePluginArray(): StoragePlugin[];
-    /**
-     * Gets an ApiPlugin array of all plugins suitable for serialization.
-     *
-     * @returns {ApiPlugin[]} An array of all plugins.
-     */
     apiPluginArray(): ApiPlugin[];
-    /**
-     * Gets an iterator for the plugins.
-     *
-     * @returns {IterableIterator<Plugin>} An iterator for the plugins.
-     */
     [Symbol.iterator](): MapIterator<Plugin>;
-    /**
-     * Executes a provided function once for each plugin.
-     *
-     * @param {Function} callback - The function to execute for each plugin.
-     * @returns {Promise<void>}
-     */
     forEach(callback: (plugin: Plugin) => Promise<void>): Promise<void>;
-    /**
-     * Sets the log level for the plugin manager.
-     *
-     * @param {LogLevel} logLevel - The log level to set.
-     */
     set logLevel(logLevel: LogLevel);
-    /**
-     * Loads registered plugins from storage.
-     *
-     * @returns {Promise<StoragePlugin[]>} A promise that resolves to an array of registered plugins.
-     */
     loadFromStorage(): Promise<StoragePlugin[]>;
-    /**
-     * Saves registered plugins to storage.
-     *
-     * @returns {Promise<number>} A promise that resolves to the number of registered plugins.
-     */
     saveToStorage(): Promise<number>;
-    /**
-     * Resolves the name of a plugin by loading and parsing its package.json file.
-     * It will first try to resolve the path as is, then in the global modules directory, and finally in the matterbridge plugin directory.
-     *
-     * @param {string} nameOrPath - The name of 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(nameOrPath: string): Promise<string | null>;
-    /**
-     * Installs a package globally using npm.
-     *
-     * @param {string} packageName - The name of the package to install.
-     * @returns {Promise<boolean>} A promise that resolves to true if the installation was successful, false otherwise.
-     */
     install(packageName: string): Promise<boolean>;
-    /**
-     * Uninstalls a package globally using npm.
-     *
-     * @param {string} packageName - The name of the package to uninstall.
-     * @returns {Promise<boolean>} A promise that resolves to true if the uninstallation was successful, false otherwise.
-     */
     uninstall(packageName: string): Promise<boolean>;
-    /**
-     * 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;
-    /**
-     * Parses the plugin package.json and returns it.
-     * It will also log warnings and errors for missing or invalid fields.
-     * It will return null if critical errors are found.
-     *
-     * @param {Plugin | PluginName} 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: Plugin | PluginName): 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<Plugin | null>} A promise that resolves to the enabled plugin object, or null if the plugin could not be enabled.
-     */
     enable(nameOrPath: string): Promise<Plugin | null>;
-    /**
-     * Disables a plugin by its name or path.
-     *
-     * This method disables a plugin by setting its `enabled` property to `false` 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 disable it.
-     *
-     * @param {string} nameOrPath - The name or path of the plugin to enable.
-     * @returns {Promise<Plugin | null>} A promise that resolves to the disabled plugin object, or null if the plugin could not be disabled.
-     */
     disable(nameOrPath: string): Promise<Plugin | 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<Plugin | null>} A promise that resolves to the removed plugin object, or null if the plugin could not be removed.
-     */
     remove(nameOrPath: string): Promise<Plugin | 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<Plugin | null>} A promise that resolves to the added plugin object, or null if the plugin could not be added.
-     */
     add(nameOrPath: string): Promise<Plugin | null>;
-    /**
-     * Loads a plugin and returns the corresponding MatterbridgePlatform instance.
-     *
-     * @param {Plugin | PluginName} 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: Plugin | PluginName, start?: boolean, message?: string, configure?: boolean): Promise<MatterbridgePlatform | undefined>;
-    /**
-     * Starts a plugin.
-     *
-     * @param {Plugin | PluginName} 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<Plugin | undefined>} A promise that resolves when the plugin is started successfully, or rejects with an error if starting the plugin fails.
-     */
     start(plugin: Plugin | PluginName, message?: string, configure?: boolean): Promise<Plugin | undefined>;
-    /**
-     * Configures a plugin.
-     *
-     * @param {Plugin | PluginName} plugin - The plugin to configure.
-     * @returns {Promise<Plugin | undefined>} A promise that resolves when the plugin is configured successfully, or rejects with an error if configuration fails.
-     */
     configure(plugin: Plugin | PluginName): Promise<Plugin | 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 {Plugin | PluginName} 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<Plugin | undefined>} A promise that resolves to the shut down plugin object, or undefined if the shutdown failed.
-     */
     shutdown(plugin: Plugin | PluginName, reason?: string, removeAllDevices?: boolean, force?: boolean): Promise<Plugin | 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 {Plugin} plugin - The plugin for which to load the configuration.
-     * @returns {Promise<PlatformConfig>} A promise that resolves to the loaded or created configuration.
-     */
     loadConfig(plugin: Plugin): 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 {Plugin} 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: Plugin, 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 {Plugin} 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: Plugin, 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 {Plugin} 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: Plugin): 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 {Plugin} plugin - The plugin for which the default schema is to be generated.
-     * @returns {PlatformSchema} The default schema object for the plugin.
-     */
     getDefaultSchema(plugin: Plugin): PlatformSchema;
 }
 export {};
-//# sourceMappingURL=pluginManager.d.ts.map