@matterbridge/core 3.8.0-dev-20260530-1971f9d → 3.8.0-dev-20260531-fafe993

package/dist/behaviors/bindingServer.d.ts

@@ -1,13 +1,18 @@
-import { BindingBehavior } from '@matter/node/behaviors/binding';
+import { Endpoint } from '@matter/main/node';
+import { BindingBehavior, BindingServer } from '@matter/node/behaviors/binding';
 import { ClusterId } from '@matter/types';
-export declare class MatterbridgeBindingServer extends BindingBehavior {
+import { Binding } from '@matter/types/clusters/binding';
+export declare class MatterbridgeBindingServer extends BindingServer {
     protected internal: MatterbridgeBindingServer.Internal;
     state: MatterbridgeBindingServer.State;
     initialize(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+    getEndpoint(clusterId: ClusterId): Endpoint | undefined;
 }
 export declare namespace MatterbridgeBindingServer {
     class Internal {
         bound: boolean;
+        boundEndpoints: Map<Binding.Target, Endpoint>;
     }
     class State extends BindingBehavior.State {
         clientList: ClusterId[];

package/dist/behaviors/bindingServer.js

@@ -1,19 +1,53 @@
-import { BindingBehavior } from '@matter/node/behaviors/binding';
+import { BindingBehavior, BindingServer } from '@matter/node/behaviors/binding';
+import { DescriptorServer } from '@matter/node/behaviors/descriptor';
+import { debugStringify, nt } from 'node-ansi-logger';
 import { MatterbridgeServer } from './matterbridgeServer.js';
-export class MatterbridgeBindingServer extends BindingBehavior {
+export class MatterbridgeBindingServer extends BindingServer {
     async initialize() {
+        super.initialize();
         const device = this.endpoint.stateOf(MatterbridgeServer);
         device.log.info(`Initializing MatterbridgeBindingServer (endpoint ${this.endpoint.maybeId}.${this.endpoint.maybeNumber}) with clientList: ${this.state.clientList.join(', ')}`);
+        const clientList = this.state.clientList;
+        this.endpoint.construction.onSuccess(async () => {
+            const currentClientList = this.endpoint.stateOf(DescriptorServer).clientList;
+            const toAddClientList = clientList.filter((id) => !currentClientList.includes(id));
+            if (toAddClientList.length > 0) {
+                await this.endpoint.setStateOf(DescriptorServer, { clientList: [...currentClientList, ...toAddClientList] });
+                device.log.info(`Adding client clusters to endpoint ${this.endpoint.maybeId}.${this.endpoint.maybeNumber}: ${toAddClientList.join(', ')}`);
+            }
+        });
         this.reactTo(this.events.binding$Changed, (value) => {
             this.internal.bound = value.length > 0;
-            device.log.notice(`MatterbridgeBindingServer (endpoint ${this.endpoint.maybeId}.${this.endpoint.maybeNumber}) binding changed: ${value}, bound: ${this.internal.bound}`);
+            device.log.notice(`MatterbridgeBindingServer (endpoint ${this.endpoint.maybeId}.${this.endpoint.maybeNumber}) binding changed: ${debugStringify(value)}${nt}, bound: ${this.internal.bound}`);
+        });
+        this.reactTo(this.events.established, async (resolution) => {
+            device.log.notice(`MatterbridgeBindingServer (endpoint ${this.endpoint.maybeId}.${this.endpoint.maybeNumber}) binding established: kind ${resolution.kind} entry ${debugStringify(resolution.entry)}${nt}`);
+            this.internal.boundEndpoints.set(resolution.entry, resolution.endpoint);
+            if (resolution.kind !== 'client')
+                return;
+            await resolution.node.set({ network: { autoSubscribe: true } });
+        });
+        this.reactTo(this.events.removed, async (resolution) => {
+            device.log.notice(`MatterbridgeBindingServer (endpoint ${this.endpoint.maybeId}.${this.endpoint.maybeNumber}) binding removed: kind ${resolution.kind} entry ${debugStringify(resolution.entry)}${nt}`);
+            this.internal.boundEndpoints.delete(resolution.entry);
         });
-        await super.initialize();
+    }
+    async [Symbol.asyncDispose]() {
+        this.internal.boundEndpoints.clear();
+        await super[Symbol.asyncDispose]();
+    }
+    getEndpoint(clusterId) {
+        for (const [target, endpoint] of this.internal.boundEndpoints) {
+            if (target.cluster === clusterId)
+                return endpoint;
+        }
+        return undefined;
     }
 }
 (function (MatterbridgeBindingServer) {
     class Internal {
         bound = false;
+        boundEndpoints = new Map();
     }
     MatterbridgeBindingServer.Internal = Internal;
     class State extends BindingBehavior.State {

package/dist/frontend.js

@@ -14,10 +14,11 @@ import { inspectError } from '@matterbridge/utils/error';
 import { formatBytes, formatPercent, formatUptime } from '@matterbridge/utils/format';
 import { isValidArray, isValidBoolean, isValidNumber, isValidObject, isValidString } from '@matterbridge/utils/validate';
 import { fireAndForget, wait, withTimeout } from '@matterbridge/utils/wait';
-import { AnsiLogger, CYAN, db, debugStringify, er, nf, nt, rs, stringify, UNDERLINE, UNDERLINEOFF, YELLOW } from 'node-ansi-logger';
+import { AnsiLogger, bgHex, CYAN, db, debugStringify, er, GREEN, nf, nt, rs, stringify, UNDERLINE, UNDERLINEOFF, wr, YELLOW } from 'node-ansi-logger';
 import { cliEmitter, lastOsCpuUsage, lastProcessCpuUsage } from './cliEmitter.js';
 import { generateHistoryPage } from './cliHistory.js';
 import { capitalizeFirstLetter, getAttribute } from './matterbridgeEndpointHelpers.js';
+import { logError } from './utils/export.js';
 if (hasParameter('loader'))
     console.log('\u001B[32mFrontend loaded.\u001B[40;0m');
 export class Frontend extends EventEmitter {
@@ -801,6 +802,50 @@ export class Frontend extends EventEmitter {
                 res.status(500).send(`Error uploading or installing plugin package ${filename}`);
             }
         });
+        for (const plugin of this.matterbridge.plugins.array().filter((p) => p.enabled && !p.error)) {
+            const { existsSync } = await import('node:fs');
+            if (plugin.frontendPath && existsSync(plugin.frontendPath)) {
+                this.log.debug(`Registering frontend route for plugin ${plg}${plugin.name}${db} at ${GREEN}/plugins/${plugin.name}${db} with path ${CYAN}${plugin.frontendPath}${db}`);
+                this.expressApp.use(`/plugins/${plugin.name}`, express.static(path.dirname(plugin.frontendPath)));
+                const apiHandler = async (req, res) => {
+                    const method = req.method.toUpperCase();
+                    const path = Array.isArray(req.params.path) ? req.params.path[0] : req.params.path;
+                    const query = req.query;
+                    const body = req.body;
+                    this.log.debug(`The frontend sent ${bgHex('#0ba7bc').bold.white ` ${method} `} ${bgHex('#0b6a2b').bold.italic.white ` /plugins/${plugin.name}/api/${path ?? ''} `}`);
+                    if (!plugin.platform) {
+                        this.log.error(`The platform for plugin ${plg}${plugin.name}${er} is not running`);
+                        res.status(503).json({ error: `Plugin ${plugin.name} platform is not running` });
+                        return;
+                    }
+                    try {
+                        const value = await plugin.platform.onFetch(method, path, query, body);
+                        if (value === undefined) {
+                            this.log.warn(`MatterbridgePlatform.onFetch returned undefined for plugin ${plg}${plugin.name}${wr} method ${method} path ${path}`);
+                            res.status(404).json({ error: `Not found in plugin ${plugin.name}` });
+                            return;
+                        }
+                        if (method === 'DELETE')
+                            res.status(204).send();
+                        else
+                            res.json(value);
+                    }
+                    catch (error) {
+                        logError(this.log, `MatterbridgePlatform.onFetch threw an error for plugin ${plg}${plugin.name}${er}`, error);
+                        res.status(500).json({ error: `Internal error in plugin ${plugin.name}` });
+                    }
+                };
+                this.expressApp.get(`/plugins/${plugin.name}/api/:path`, apiHandler);
+                this.expressApp.post(`/plugins/${plugin.name}/api/:path`, apiHandler);
+                this.expressApp.put(`/plugins/${plugin.name}/api/:path`, apiHandler);
+                this.expressApp.patch(`/plugins/${plugin.name}/api/:path`, apiHandler);
+                this.expressApp.delete(`/plugins/${plugin.name}/api/:path`, apiHandler);
+                this.expressApp.get(`/plugins/${plugin.name}/{*splat}`, (_req, res) => {
+                    this.log.warn(`The plugin frontend sent /plugins/${plugin.name}/index.html (plugin SPA fallback)`);
+                    res.sendFile('index.html', { root: path.dirname(plugin.frontendPath) });
+                });
+            }
+        }
         this.expressApp.use((req, res) => {
             const filePath = path.resolve(this.matterbridge.rootDirectory, 'apps', 'frontend', 'build');
             this.log.debug(`The frontend sent ${req.url} method ${req.method}: sending index.html in ${filePath} as fallback`);

package/dist/matterbridgeEndpoint.d.ts

@@ -119,6 +119,9 @@ export declare class MatterbridgeEndpoint extends Endpoint {
     invokeBehaviorCommand(cluster: ClusterId | string, command: CommandHandlers, params?: Record<string, boolean | number | bigint | string | object | null>): Promise<void>;
     addRequiredClusterServers(): MatterbridgeEndpoint;
     addOptionalClusterServers(): MatterbridgeEndpoint;
+    addRequiredClusterClients(): MatterbridgeEndpoint;
+    addOptionalClusterClients(): MatterbridgeEndpoint;
+    addClusterClients(clientList: ClusterId[]): MatterbridgeEndpoint;
     getAllClusterServers(): Behavior.Type[];
     getAllClusterServerNames(): string[];
     forEachAttribute(callback: (clusterName: string, clusterId: number, attributeName: string, attributeId: number, attributeValue: boolean | number | bigint | string | object | null | undefined) => void): void;
@@ -143,6 +146,7 @@ export declare class MatterbridgeEndpoint extends Endpoint {
     createApparentElectricalPowerMeasurementClusterServer(voltage?: number | bigint | null, apparentCurrent?: number | bigint | null, apparentPower?: number | bigint | null, frequency?: number | bigint | null): this;
     createDefaultDeviceEnergyManagementClusterServer(esaType?: DeviceEnergyManagement.EsaType, esaCanGenerate?: boolean, esaState?: DeviceEnergyManagement.EsaState, absMinPower?: number, absMaxPower?: number): this;
     createDefaultDeviceEnergyManagementModeClusterServer(currentMode?: number, supportedModes?: DeviceEnergyManagementMode.ModeOption[]): this;
+    createDefaultBindingClusterServer(clientList?: ClusterId[]): this;
     createDefaultIdentifyClusterServer(identifyTime?: number, identifyType?: Identify.IdentifyType): this;
     createDefaultGroupsClusterServer(): this;
     createDefaultScenesManagementClusterServer(): this;

package/dist/matterbridgeEndpoint.js

@@ -83,7 +83,7 @@ import { MatterbridgeThermostatServer } from './behaviors/thermostatServer.js';
 import { MatterbridgeValveConfigurationAndControlServer } from './behaviors/valveConfigurationAndControlServer.js';
 import { MatterbridgeWindowCoveringServer } from './behaviors/windowCoveringServer.js';
 import { CommandHandler } from './matterbridgeEndpointCommandHandler.js';
-import { addClusterServers, addFixedLabel, addOptionalClusterServers, addRequiredClusterServers, addUserLabel, checkNotLatinCharacters, createUniqueId, defaultFor, featuresFor, generateUniqueId, getApparentElectricalPowerMeasurementClusterServer, getAttribute, getAttributeId, getBehavior, getBehaviourTypesFromClusterClientIds, getBehaviourTypesFromClusterServerIds, getCluster, getClusterId, getDefaultDeviceEnergyManagementClusterServer, getDefaultDeviceEnergyManagementModeClusterServer, getDefaultElectricalEnergyMeasurementClusterServer, getDefaultElectricalPowerMeasurementClusterServer, getDefaultFlowMeasurementClusterServer, getDefaultIlluminanceMeasurementClusterServer, getDefaultOccupancySensingClusterServer, getDefaultOperationalStateClusterServer, getDefaultPowerSourceBatteryClusterServer, getDefaultPowerSourceRechargeableBatteryClusterServer, getDefaultPowerSourceReplaceableBatteryClusterServer, getDefaultPowerSourceWiredClusterServer, getDefaultPressureMeasurementClusterServer, getDefaultRelativeHumidityMeasurementClusterServer, getDefaultTemperatureMeasurementClusterServer, invokeBehaviorCommand, lowercaseFirstLetter, setAttribute, setCluster, subscribeAttribute, triggerEvent, updateAttribute, } from './matterbridgeEndpointHelpers.js';
+import { addClusterClients, addClusterServers, addFixedLabel, addOptionalClusterClients, addOptionalClusterServers, addRequiredClusterClients, addRequiredClusterServers, addUserLabel, checkNotLatinCharacters, createUniqueId, defaultFor, featuresFor, generateUniqueId, getApparentElectricalPowerMeasurementClusterServer, getAttribute, getAttributeId, getBehavior, getBehaviourTypesFromClusterClientIds, getBehaviourTypesFromClusterServerIds, getCluster, getClusterId, getDefaultDeviceEnergyManagementClusterServer, getDefaultDeviceEnergyManagementModeClusterServer, getDefaultElectricalEnergyMeasurementClusterServer, getDefaultElectricalPowerMeasurementClusterServer, getDefaultFlowMeasurementClusterServer, getDefaultIlluminanceMeasurementClusterServer, getDefaultOccupancySensingClusterServer, getDefaultOperationalStateClusterServer, getDefaultPowerSourceBatteryClusterServer, getDefaultPowerSourceRechargeableBatteryClusterServer, getDefaultPowerSourceReplaceableBatteryClusterServer, getDefaultPowerSourceWiredClusterServer, getDefaultPressureMeasurementClusterServer, getDefaultRelativeHumidityMeasurementClusterServer, getDefaultTemperatureMeasurementClusterServer, invokeBehaviorCommand, lowercaseFirstLetter, setAttribute, setCluster, subscribeAttribute, triggerEvent, updateAttribute, } from './matterbridgeEndpointHelpers.js';
 const MATTERBRIDGE_ENDPOINT_BRAND = Symbol('MatterbridgeEndpoint.brand');
 export function isMatterbridgeEndpoint(value) {
     if (!value || typeof value !== 'object')
@@ -276,6 +276,18 @@ export class MatterbridgeEndpoint extends Endpoint {
         addOptionalClusterServers(this);
         return this;
     }
+    addRequiredClusterClients() {
+        addRequiredClusterClients(this);
+        return this;
+    }
+    addOptionalClusterClients() {
+        addOptionalClusterClients(this);
+        return this;
+    }
+    addClusterClients(clientList) {
+        addClusterClients(this, clientList);
+        return this;
+    }
     getAllClusterServers() {
         return Object.values(this.behaviors.supported);
     }
@@ -560,6 +572,10 @@ export class MatterbridgeEndpoint extends Endpoint {
         this.behaviors.require(MatterbridgeDeviceEnergyManagementModeServer, getDefaultDeviceEnergyManagementModeClusterServer(currentMode, supportedModes));
         return this;
     }
+    createDefaultBindingClusterServer(clientList = []) {
+        addClusterClients(this, clientList);
+        return this;
+    }
     createDefaultIdentifyClusterServer(identifyTime = 0, identifyType = Identify.IdentifyType.None) {
         this.behaviors.require(MatterbridgeIdentifyServer, {
             identifyTime,

package/dist/matterbridgeEndpointHelpers.d.ts

@@ -46,6 +46,9 @@ export declare function invokeSubscribeHandler(endpoint: MatterbridgeEndpoint, c
 export declare function addRequiredClusterServers(endpoint: MatterbridgeEndpoint): void;
 export declare function addOptionalClusterServers(endpoint: MatterbridgeEndpoint): void;
 export declare function addClusterServers(endpoint: MatterbridgeEndpoint, serverList: ClusterId[]): void;
+export declare function addClusterClients(endpoint: MatterbridgeEndpoint, clientList: ClusterId[]): void;
+export declare function addRequiredClusterClients(endpoint: MatterbridgeEndpoint): void;
+export declare function addOptionalClusterClients(endpoint: MatterbridgeEndpoint): void;
 export declare function addFixedLabel(endpoint: MatterbridgeEndpoint, label: string, value: string): Promise<void>;
 export declare function addUserLabel(endpoint: MatterbridgeEndpoint, label: string, value: string): Promise<void>;
 export declare function getClusterId(endpoint: Endpoint, cluster: string): number | undefined;

package/dist/matterbridgeEndpointHelpers.js

@@ -84,6 +84,7 @@ import { MeasurementType } from '@matter/types/globals';
 import { deepEqual } from '@matterbridge/utils/deep-equal';
 import { isValidArray } from '@matterbridge/utils/validate';
 import { BLUE, CYAN, db, debugStringify, er, hk, or, YELLOW, zb } from 'node-ansi-logger';
+import { MatterbridgeBindingServer } from './behaviors/bindingServer.js';
 import { MatterbridgeBooleanStateConfigurationServer } from './behaviors/booleanStateConfigurationServer.js';
 import { MatterbridgeColorControlServer } from './behaviors/colorControlServer.js';
 import { MatterbridgeDeviceEnergyManagementModeServer } from './behaviors/deviceEnergyManagementModeServer.js';
@@ -491,6 +492,44 @@ export function addClusterServers(endpoint, serverList) {
     if (serverList.includes(DeviceEnergyManagementMode.Cluster.id))
         endpoint.createDefaultDeviceEnergyManagementModeClusterServer();
 }
+export function addClusterClients(endpoint, clientList) {
+    if (clientList.length === 0)
+        return;
+    if (!endpoint.behaviors.has(MatterbridgeBindingServer)) {
+        endpoint.behaviors.require(MatterbridgeBindingServer, { clientList });
+        return;
+    }
+    const existing = endpoint.behaviors.optionsFor(MatterbridgeBindingServer)?.clientList ?? [];
+    endpoint.behaviors.inject(MatterbridgeBindingServer, { clientList: [...new Set([...existing, ...clientList])] });
+}
+export function addRequiredClusterClients(endpoint) {
+    const requiredClientList = [];
+    endpoint.log.debug(`addRequiredClusterClients for ${CYAN}${endpoint.maybeId}${db}`);
+    Array.from(endpoint.deviceTypes.values()).forEach((deviceType) => {
+        endpoint.log.debug(`- for deviceType: ${zb}${'0x' + deviceType.code.toString(16).padStart(4, '0')}${db}-${zb}${deviceType.name}${db}`);
+        deviceType.requiredClientClusters.forEach((clusterId) => {
+            if (!requiredClientList.includes(clusterId)) {
+                requiredClientList.push(clusterId);
+                endpoint.log.debug(`- cluster: ${hk}${'0x' + clusterId.toString(16).padStart(4, '0')}${db}-${hk}${getClusterNameById(clusterId)}${db}`);
+            }
+        });
+    });
+    addClusterClients(endpoint, requiredClientList);
+}
+export function addOptionalClusterClients(endpoint) {
+    const optionalClientList = [];
+    endpoint.log.debug(`addOptionalClusterClients for ${CYAN}${endpoint.maybeId}${db}`);
+    Array.from(endpoint.deviceTypes.values()).forEach((deviceType) => {
+        endpoint.log.debug(`- for deviceType: ${zb}${'0x' + deviceType.code.toString(16).padStart(4, '0')}${db}-${zb}${deviceType.name}${db}`);
+        deviceType.optionalClientClusters.forEach((clusterId) => {
+            if (!optionalClientList.includes(clusterId)) {
+                optionalClientList.push(clusterId);
+                endpoint.log.debug(`- cluster: ${hk}${'0x' + clusterId.toString(16).padStart(4, '0')}${db}-${hk}${getClusterNameById(clusterId)}${db}`);
+            }
+        });
+    });
+    addClusterClients(endpoint, optionalClientList);
+}
 export async function addFixedLabel(endpoint, label, value) {
     if (!endpoint.hasClusterServer(FixedLabel.Cluster.id)) {
         endpoint.log.debug(`addFixedLabel: add cluster ${hk}FixedLabel${db}:${hk}fixedLabel${db} with label ${CYAN}${label}${db} value ${CYAN}${value}${db}`);

package/dist/matterbridgePlatform.d.ts

@@ -29,6 +29,7 @@ export declare class MatterbridgePlatform {
     onShutdown(reason?: string): Promise<void>;
     onChangeLoggerLevel(logLevel: LogLevel): Promise<void>;
     onAction(action: string, value?: string, id?: string, formData?: PlatformConfig): Promise<void>;
+    onFetch(method: string, path?: string, query?: Record<string, unknown>, body?: unknown): Promise<unknown>;
     onConfigChanged(config: PlatformConfig): Promise<void>;
     saveConfig(config: PlatformConfig): void;
     getSchema(): Promise<PlatformSchema | undefined>;

package/dist/matterbridgePlatform.js

@@ -156,6 +156,10 @@ export class MatterbridgePlatform {
     async onAction(action, value, id, formData) {
         this.log.debug(`The plugin ${CYAN}${this.name}${db} doesn't override onAction. Received action ${CYAN}${action}${db}${value ? ' with ' + CYAN + value + db : ''} ${id ? ' for schema ' + CYAN + id + db : ''}`, formData);
     }
+    async onFetch(method, path, query, body) {
+        this.log.debug(`onFetch called: method=${method} path=${path ?? 'none'} query=${query ? JSON.stringify(query) : 'none'} body=${body ? JSON.stringify(body) : 'none'}`);
+        return undefined;
+    }
     async onConfigChanged(config) {
         this.log.debug(`The plugin ${CYAN}${config.name}${db} doesn't override onConfigChanged. Received new config.`);
     }

package/dist/pluginManager.js

@@ -1,6 +1,7 @@
 if (process.argv.includes('--loader') || process.argv.includes('-loader'))
     console.log('\u001B[32mPlugin Manager loaded.\u001B[40;0m');
 import EventEmitter from 'node:events';
+import path from 'node:path';
 import { BroadcastServer } from '@matterbridge/thread/server';
 import { plg, typ } from '@matterbridge/types';
 import { hasParameter } from '@matterbridge/utils/cli';
@@ -657,6 +658,10 @@ export class PluginManager extends EventEmitter {
             plugin.funding = this.getFunding(packageJson);
             if (!plugin.type)
                 this.log.warn(`Plugin ${plg}${plugin.name}${wr} has no type`);
+            const frontendPath = path.join(plugin.path.replace('package.json', ''), 'apps', 'frontend', 'build', 'index.html');
+            const { existsSync } = await import('node:fs');
+            if (existsSync(frontendPath))
+                plugin.frontendPath = frontendPath;
             const invalidDependencies = this.findInvalidDependencies(packageJson);
             if (invalidDependencies) {
                 this.logInvalidDependencies(packageJson, invalidDependencies, plugin.name);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matterbridge/core",
-  "version": "3.8.0-dev-20260530-1971f9d",
+  "version": "3.8.0-dev-20260531-fafe993",
   "description": "Matterbridge core library",
   "author": "https://github.com/Luligu",
   "homepage": "https://matterbridge.io/",
@@ -130,16 +130,16 @@
   ],
   "dependencies": {
     "@matter/main": "0.17.0",
-    "@matterbridge/dgram": "3.8.0-dev-20260530-1971f9d",
-    "@matterbridge/thread": "3.8.0-dev-20260530-1971f9d",
-    "@matterbridge/types": "3.8.0-dev-20260530-1971f9d",
-    "@matterbridge/utils": "3.8.0-dev-20260530-1971f9d",
+    "@matterbridge/dgram": "3.8.0-dev-20260531-fafe993",
+    "@matterbridge/thread": "3.8.0-dev-20260531-fafe993",
+    "@matterbridge/types": "3.8.0-dev-20260531-fafe993",
+    "@matterbridge/utils": "3.8.0-dev-20260531-fafe993",
     "escape-html": "1.0.3",
     "express": "5.2.1",
     "express-rate-limit": "8.5.2",
     "multer": "2.1.1",
     "node-ansi-logger": "3.3.0-dev-20260524-cac9dd5",
     "node-persist-manager": "2.1.0-dev-20260524-6a6019a",
-    "ws": "8.20.1"
+    "ws": "8.21.0"
   }
 }