matterbridge 3.4.7 → 3.5.0-dev-20260113-29ad318

package/dist/matterbridgeTypes.d.ts

@@ -1,26 +1,3 @@
-/**
- * This file contains the types for Matterbridge.
- *
- * @file matterbridgeTypes.ts
- * @author Luca Liguori
- * @created 2024-07-12
- * @version 1.0.3
- * @license Apache-2.0
- *
- * Copyright 2023, 2024, 2025 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 type { NodeStorage } from 'node-persist-manager';
 import type { LogLevel } from 'node-ansi-logger';
 import type { ServerNode, Endpoint as EndpointNode } from '@matter/node';
@@ -41,14 +18,9 @@ export declare const MATTER_STORAGE_NAME = "matterstorage";
 export declare const MATTERBRIDGE_DIAGNOSTIC_FILE = "diagnostic.log";
 export declare const MATTERBRIDGE_HISTORY_FILE = "history.html";
 export type MaybePromise<T> = T | Promise<T>;
-/**
- * A type representing a read-only subset of the Matterbridge properties.
- */
 export type SharedMatterbridge = Readonly<Pick<Matterbridge, 'systemInformation' | 'rootDirectory' | 'homeDirectory' | 'matterbridgeDirectory' | 'matterbridgePluginDirectory' | 'matterbridgeCertDirectory' | 'globalModulesDirectory' | 'matterbridgeVersion' | 'matterbridgeLatestVersion' | 'matterbridgeDevVersion' | 'frontendVersion' | 'bridgeMode' | 'restartMode' | 'virtualMode' | 'profile' | 'logLevel' | 'fileLogger' | 'matterLogLevel' | 'matterFileLogger' | 'mdnsInterface' | 'ipv4Address' | 'ipv6Address' | 'port' | 'discriminator' | 'passcode' | 'shellySysUpdate' | 'shellyMainUpdate'>>;
 export type PluginName = string;
-/** Define an interface for matterbridge */
 export interface Plugin extends ApiPlugin {
-    /** Node storage context created in the directory 'storage' in matterbridgeDirectory with the plugin name */
     nodeContext?: NodeStorage;
     storageContext?: StorageContext;
     serverNode?: ServerNode<ServerNode.RootEndpoint>;
@@ -57,7 +29,6 @@ export interface Plugin extends ApiPlugin {
     platform?: MatterbridgePlatform;
     reachabilityTimeout?: NodeJS.Timeout;
 }
-/** Define an interface for the frontend */
 export interface ApiPlugin extends StoragePlugin {
     latestVersion?: string;
     devVersion?: string;
@@ -70,7 +41,6 @@ export interface ApiPlugin extends StoragePlugin {
     loaded?: boolean;
     started?: boolean;
     configured?: boolean;
-    /** Signal that the config has changed and a restart is required */
     restartRequired?: boolean;
     registeredDevices?: number;
     configJson?: PlatformConfig;
@@ -79,7 +49,6 @@ export interface ApiPlugin extends StoragePlugin {
     hasBlackList?: boolean;
     matter?: ApiMatter;
 }
-/** Define an interface for storing the plugin information */
 export interface StoragePlugin {
     name: string;
     path: string;
@@ -89,7 +58,6 @@ export interface StoragePlugin {
     author: string;
     enabled: boolean;
 }
-/** Define an interface for the system information */
 export interface SystemInformation {
     interfaceName: string;
     macAddress: string;
@@ -112,7 +80,6 @@ export interface SystemInformation {
     heapTotal: string;
     heapUsed: string;
 }
-/** Define an interface for the matterbridge information */
 export interface MatterbridgeInformation {
     rootDirectory: string;
     homeDirectory: string;
@@ -146,7 +113,6 @@ export interface MatterbridgeInformation {
     fixedRestartRequired: boolean;
     updateRequired: boolean;
 }
-/** Define an interface for sanitized exposed fabric information suitable for API responses */
 export interface SanitizedExposedFabricInformation {
     fabricIndex: FabricIndex;
     fabricId: string;
@@ -156,7 +122,6 @@ export interface SanitizedExposedFabricInformation {
     rootVendorName: string;
     label: string;
 }
-/** Define an interface for sanitized session information suitable for API responses */
 export interface SanitizedSession {
     name: string;
     nodeId: string;
@@ -167,7 +132,6 @@ export interface SanitizedSession {
     lastActiveTimestamp: string;
     numberOfActiveSubscriptions: number;
 }
-/** Define an interface for API device information */
 export interface ApiDevice {
     pluginName: string;
     type: string;
@@ -183,7 +147,6 @@ export interface ApiDevice {
     cluster: string;
     matter?: ApiMatter;
 }
-/** Define an interface for base device information */
 export interface BaseDevice {
     mode: 'server' | 'matter' | undefined;
     plugin: string | undefined;
@@ -207,7 +170,6 @@ export interface BaseDevice {
     number: EndpointNumber | undefined;
     id: string | undefined;
 }
-/** Define an interface for API matter information */
 export interface ApiMatter {
     id: string;
     online: boolean;
@@ -221,25 +183,18 @@ export interface ApiMatter {
     manualPairingCode: string;
     serialNumber: string | undefined;
 }
-/** Define an interface for API clusters information */
 export interface ApiClusters {
     plugin: string;
     deviceName: string;
     serialNumber: string;
-    /** Endpoint number */
     number: EndpointNumber;
-    /** Endpoint id */
     id: string;
     deviceTypes: number[];
     clusters: Cluster[];
 }
-/** Define an interface for Cluster information in ApiClusters */
 export interface Cluster {
-    /** Endpoint number > string */
     endpoint: string;
-    /** Endpoint number */
     number: EndpointNumber;
-    /** Endpoint id or main for the device root endpoint */
     id: string;
     deviceTypes: number[];
     clusterName: string;
@@ -249,4 +204,3 @@ export interface Cluster {
     attributeValue: string;
     attributeLocalValue: unknown;
 }
-//# sourceMappingURL=matterbridgeTypes.d.ts.map

package/dist/matterbridgeTypes.js

@@ -1,35 +1,9 @@
-/**
- * This file contains the types for Matterbridge.
- *
- * @file matterbridgeTypes.ts
- * @author Luca Liguori
- * @created 2024-07-12
- * @version 1.0.3
- * @license Apache-2.0
- *
- * Copyright 2023, 2024, 2025 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.
- */
-// Default colors
 export const plg = '\u001B[38;5;33m';
 export const dev = '\u001B[38;5;79m';
 export const typ = '\u001B[38;5;207m';
-// Default names
 export const MATTERBRIDGE_LOGGER_FILE = 'matterbridge.log';
 export const MATTER_LOGGER_FILE = 'matter.log';
 export const NODE_STORAGE_DIR = 'storage';
 export const MATTER_STORAGE_NAME = 'matterstorage';
 export const MATTERBRIDGE_DIAGNOSTIC_FILE = 'diagnostic.log';
 export const MATTERBRIDGE_HISTORY_FILE = 'history.html';
-//# sourceMappingURL=matterbridgeTypes.js.map

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