matterbridge 3.4.3-dev-20251209-e6cb85f → 3.4.3

package/dist/frontend.d.ts

@@ -0,0 +1,238 @@
+/**
+ * This file contains the class Frontend.
+ *
+ * @file frontend.ts
+ * @author Luca Liguori
+ * @created 2025-01-13
+ * @version 1.3.2
+ * @license Apache-2.0
+ *
+ * Copyright 2025, 2026, 2027 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 { EndpointNumber } from '@matter/types/datatype';
+import type { ApiMatter } from './matterbridgeTypes.js';
+import type { Matterbridge } from './matterbridge.js';
+import type { RefreshRequiredChanged, WsMessageBroadcast } from './frontendTypes.js';
+/**
+ * Represents the Frontend events.
+ */
+interface FrontendEvents {
+    server_listening: [protocol: string, port: number, address?: string];
+    server_error: [error: Error];
+    server_stopped: [];
+    websocket_server_listening: [protocol: string];
+    websocket_server_stopped: [];
+}
+export declare class Frontend extends EventEmitter<FrontendEvents> {
+    private matterbridge;
+    private log;
+    private port;
+    private listening;
+    private storedPassword;
+    private expressApp;
+    private httpServer;
+    private httpsServer;
+    private webSocketServer;
+    private readonly server;
+    private readonly debug;
+    private readonly verbose;
+    constructor(matterbridge: Matterbridge);
+    destroy(): void;
+    private msgHandler;
+    set logLevel(logLevel: LogLevel);
+    start(port?: number): Promise<void>;
+    stop(): Promise<void>;
+    /**
+     * Retrieves the api settings data.
+     *
+     * @returns {Promise<{ matterbridgeInformation: MatterbridgeInformation, systemInformation: SystemInformation }>} A promise that resolve in the api settings object.
+     */
+    private getApiSettings;
+    /**
+     * Retrieves the reachable attribute.
+     *
+     * @param {MatterbridgeEndpoint} device - The MatterbridgeEndpoint object.
+     * @returns {boolean} The reachable attribute.
+     */
+    private getReachability;
+    /**
+     * Retrieves the power source attribute.
+     *
+     * @param {MatterbridgeEndpoint} endpoint - The MatterbridgeDevice to retrieve the power source from.
+     * @returns {'ac' | 'dc' | 'ok' | 'warning' | 'critical' | undefined} The power source attribute.
+     */
+    private getPowerSource;
+    /**
+     * Retrieves the cluster text description from a given device.
+     * The output is a string with the attributes description of the cluster servers in the device to show in the frontend.
+     *
+     * @param {MatterbridgeEndpoint} device - The MatterbridgeEndpoint to retrieve the cluster text from.
+     * @returns {string} The attributes description of the cluster servers in the device.
+     */
+    private getClusterTextFromDevice;
+    /**
+     * Retrieves the registered plugins sanitized for res.json().
+     *
+     * @returns {ApiPlugin[]} An array of BaseRegisteredPlugin.
+     */
+    private getPlugins;
+    /**
+     * Retrieves the devices from Matterbridge.
+     *
+     * @param {string} [pluginName] - The name of the plugin to filter devices by.
+     * @returns {ApiDevice[]} An array of ApiDevices for the frontend.
+     */
+    private getDevices;
+    /**
+     * Retrieves the clusters from a given plugin and endpoint number.
+     *
+     * Response for /api/clusters
+     *
+     * @param {string} pluginName - The name of the plugin.
+     * @param {number} endpointNumber - The endpoint number.
+     * @returns {ApiClusters | undefined} A promise that resolves to the clusters or undefined if not found.
+     */
+    private getClusters;
+    private generateDiagnostic;
+    /**
+     * Handles incoming websocket api request messages from the Matterbridge frontend.
+     *
+     * @param {WebSocket} client - The websocket client that sent the message.
+     * @param {WebSocket.RawData} message - The raw data of the message received from the client.
+     * @returns {Promise<void>} A promise that resolves when the message has been handled.
+     */
+    private wsMessageHandler;
+    /**
+     * Sends a WebSocket log message to all connected clients. The function is called by AnsiLogger.setGlobalCallback.
+     *
+     * @param {string} level - The logger level of the message: debug info notice warn error fatal...
+     * @param {string} time - The time string of the message
+     * @param {string} name - The logger name of the message
+     * @param {string} message - The content of the message.
+     *
+     * @remarks
+     * The function removes ANSI escape codes, leading asterisks, non-printable characters, and replaces all occurrences of \t and \n.
+     * It also replaces all occurrences of \" with " and angle-brackets with &lt; and &gt;.
+     * The function sends the message to all connected clients.
+     */
+    wssSendLogMessage(level: string, time: string, name: string, message: string): void;
+    /**
+     * Sends a need to refresh WebSocket message to all connected clients.
+     *
+     * @param {string} changed - The changed value.
+     * @param {Record<string, unknown>} params - Additional parameters to send with the message.
+     * possible values for changed:
+     * - 'settings' (when the bridge has started in bridge mode or childbridge mode and when update finds a new version)
+     * - 'plugins'
+     * - 'devices'
+     * - 'matter' with param 'matter' (QRDiv component)
+     * @param {ApiMatter} params.matter - The matter device that has changed. Required if changed is 'matter'.
+     */
+    wssSendRefreshRequired(changed: RefreshRequiredChanged, params?: {
+        matter: ApiMatter;
+    }): void;
+    /**
+     * Sends a need to restart WebSocket message to all connected clients.
+     *
+     * @param {boolean} snackbar - If true, a snackbar message will be sent to all connected clients. Default is true.
+     * @param {boolean} fixed - If true, the restart is fixed and will not be reset by plugin restarts. Default is false.
+     */
+    wssSendRestartRequired(snackbar?: boolean, fixed?: boolean): void;
+    /**
+     * Sends a no need to restart WebSocket message to all connected clients.
+     *
+     * @param {boolean} snackbar - If true, the snackbar message will be cleared from all connected clients. Default is true.
+     */
+    wssSendRestartNotRequired(snackbar?: boolean): void;
+    /**
+     * Sends a need to update WebSocket message to all connected clients.
+     *
+     * @param {boolean} devVersion - If true, the update is for a development version. Default is false.
+     */
+    wssSendUpdateRequired(devVersion?: boolean): void;
+    /**
+     * Sends a cpu update message to all connected clients.
+     *
+     * @param {number} cpuUsage - The CPU usage percentage to send.
+     * @param {number} processCpuUsage - The CPU usage percentage of the process to send.
+     */
+    wssSendCpuUpdate(cpuUsage: number, processCpuUsage: number): void;
+    /**
+     * Sends a memory update message to all connected clients.
+     *
+     * @param {string} totalMemory - The total memory in bytes.
+     * @param {string} freeMemory - The free memory in bytes.
+     * @param {string} rss - The resident set size in bytes.
+     * @param {string} heapTotal - The total heap memory in bytes.
+     * @param {string} heapUsed - The used heap memory in bytes.
+     * @param {string} external - The external memory in bytes.
+     * @param {string} arrayBuffers - The array buffers memory in bytes.
+     */
+    wssSendMemoryUpdate(totalMemory: string, freeMemory: string, rss: string, heapTotal: string, heapUsed: string, external: string, arrayBuffers: string): void;
+    /**
+     * Sends an uptime update message to all connected clients.
+     *
+     * @param {string} systemUptime - The system uptime in a human-readable format.
+     * @param {string} processUptime - The process uptime in a human-readable format.
+     */
+    wssSendUptimeUpdate(systemUptime: string, processUptime: string): void;
+    /**
+     * Sends an open snackbar message to all connected clients.
+     *
+     * @param {string} message - The message to send.
+     * @param {number} timeout - The timeout in seconds for the snackbar message. Default is 5 seconds.
+     * @param {'info' | 'warning' | 'error' | 'success'} severity - The severity of the message.
+     * possible values are: 'info', 'warning', 'error', 'success'. Default is 'info'.
+     *
+     * @remarks
+     * If timeout is 0, the snackbar message will be displayed until closed by the user.
+     */
+    wssSendSnackbarMessage(message: string, timeout?: number, severity?: 'info' | 'warning' | 'error' | 'success'): void;
+    /**
+     * Sends a close snackbar message to all connected clients.
+     * It will close the snackbar message with the same message and timeout = 0.
+     *
+     * @param {string} message - The message to send.
+     */
+    wssSendCloseSnackbarMessage(message: string): void;
+    /**
+     * Sends an attribute update message to all connected WebSocket clients.
+     *
+     * @param {string | undefined} plugin - The name of the plugin.
+     * @param {string | undefined} serialNumber - The serial number of the device.
+     * @param {string | undefined} uniqueId - The unique identifier of the device.
+     * @param {EndpointNumber} number - The endpoint number where the attribute belongs.
+     * @param {string} id - The endpoint id where the attribute belongs.
+     * @param {string} cluster - The cluster name where the attribute belongs.
+     * @param {string} attribute - The name of the attribute that changed.
+     * @param {number | string | boolean} value - The new value of the attribute.
+     *
+     * @remarks
+     * This method logs a debug message and sends a JSON-formatted message to all connected WebSocket clients
+     * with the updated attribute information.
+     */
+    wssSendAttributeChangedMessage(plugin: string, serialNumber: string, uniqueId: string, number: EndpointNumber, id: string, cluster: string, attribute: string, value: number | string | boolean | null): void;
+    /**
+     * Sends a message to all connected clients.
+     * This is an helper function to send a broadcast message to all connected clients.
+     *
+     * @param {WsMessageBroadcast} msg - The message to send.
+     */
+    wssBroadcastMessage(msg: WsMessageBroadcast): void;
+}
+export {};
+//# sourceMappingURL=frontend.d.ts.map

package/dist/frontend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontend.d.ts","sourceRoot":"","sources":["../src/frontend.ts"],"names":[],"mappings":"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"}