matterbridge 3.2.6 → 3.2.7-dev-20250908-3bb699e

package/dist/globalMatterbridge.js

@@ -1,70 +1,23 @@
-/**
- * This file contains functions to set and get global instances of Matterbridge, Frontend, and Logger.
- *
- * @file globalMatterbridge.ts
- * @author Luca Liguori
- * @created 2025-06-01
- * @version 1.0.0
- * @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.
- */
-/**
- * Store the Matterbridge instance globally for later retrieval.
- *
- * @param {Matterbridge} matterbridge An initialized Matterbridge instance
- */
 export function setGlobalMatterbridge(matterbridge) {
     globalThis.__matterbridge__ = matterbridge;
     globalThis.__frontend__ = matterbridge.frontend;
     globalThis.__log__ = matterbridge.log;
 }
-/**
- * Retrieve the globally stored Matterbridge instance.
- *
- * @returns {Matterbridge} The Matterbridge instance.
- * @throws {Error} If the Matterbridge instance is not set.
- */
 export function getGlobalMatterbridge() {
     if (!globalThis.__matterbridge__) {
         throw new Error('Global Matterbridge instance is not set.');
     }
     return globalThis.__matterbridge__;
 }
-/**
- * Retrieve the globally stored Frontend instance.
- *
- * @returns {Frontend} The Frontend instance.
- * @throws {Error} If the Frontend instance is not set.
- */
 export function getGlobalFrontend() {
     if (!globalThis.__frontend__) {
         throw new Error('Global Frontend instance is not set.');
     }
     return globalThis.__frontend__;
 }
-/**
- * Retrieve the globally stored Logger instance.
- *
- * @returns {AnsiLogger} The AnsiLogger instance.
- * @throws {Error} If the Logger instance is not set.
- */
 export function getGlobalLog() {
     if (!globalThis.__log__) {
         throw new Error('Global Logger instance is not set.');
     }
     return globalThis.__log__;
 }
-//# sourceMappingURL=globalMatterbridge.js.map

package/dist/helpers.js

@@ -1,27 +1,3 @@
-/**
- * This file contains the helpers functions of Matterbridge.
- *
- * @file helpers.ts
- * @author Luca Liguori
- * @created 2025-05-12
- * @version 1.0.0
- * @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.
- */
-// @matter module
 import { OnOff } from '@matter/main/clusters/on-off';
 import { Endpoint } from '@matter/node';
 import { BridgedDeviceBasicInformationServer } from '@matter/node/behaviors/bridged-device-basic-information';
@@ -30,24 +6,8 @@ import { OnOffPlugInUnitDevice } from '@matter/node/devices/on-off-plug-in-unit'
 import { MountedOnOffControlDevice } from '@matter/node/devices/mounted-on-off-control';
 import { OnOffLightDevice } from '@matter/node/devices/on-off-light';
 import { OnOffLightSwitchDevice } from '@matter/node/devices/on-off-light-switch';
-// Matterbridge
 import { hasParameter } from './utils/commandLine.js';
-/**
- * Adds a virtual device to the provided endpoint, sets up an event listener for device state changes,
- * and ensures the device is initialized in the off state.
- *
- * @param {Endpoint<AggregatorEndpoint>} aggregatorEndpoint - The aggragator endpoint to which the virtual device will be added.
- * @param {string} name - The name of the virtual device. Spaces in the name are removed to form the device ID.
- * @param {'light' | 'outlet' | 'switch' | 'mounted_switch'} type - The type of the virtual device. Can be 'light', 'outlet', 'switch', or 'mounted_switch'.
- * @param {() => Promise<void>} callback - A callback function that gets executed when the device's on/off state changes to true.
- * @returns {Promise<Endpoint>} A promise that resolves with the created virtual device.
- * @remarks The virtual device is created as an instance of `Endpoint` with the `OnOffPlugInUnitDevice` device type.
- * The onOff state always reverts to false when the device is turned on.
- */
 export async function addVirtualDevice(aggregatorEndpoint, name, type, callback) {
-    // Create a new virtual device by instantiating `Endpoint` with device information.
-    // The device ID is created by replacing all spaces in the name with an empty string.
-    // The node label of the bridged device basic information is set to the given name.
     let deviceType;
     switch (type) {
         case 'light':
@@ -68,9 +28,7 @@ export async function addVirtualDevice(aggregatorEndpoint, name, type, callback)
         bridgedDeviceBasicInformation: { nodeLabel: name.slice(0, 32) },
         onOff: { onOff: false, startUpOnOff: OnOff.StartUpOnOff.Off },
     });
-    // Set up an event listener for when the `onOff` state changes.
     device.events.onOff.onOff$Changed.on((value) => {
-        // If the `onOff` state becomes true, turn off the virtual device and execute the callback.
         if (value) {
             callback();
             process.nextTick(async () => {
@@ -78,24 +36,14 @@ export async function addVirtualDevice(aggregatorEndpoint, name, type, callback)
                     await device.setStateOf(OnOffBaseServer, { onOff: false });
                 }
                 catch (_error) {
-                    // Not necessary to handle the error
                 }
             });
         }
     });
-    // Add the created device to the given endpoint.
     await aggregatorEndpoint.add(device);
-    // Initially set the state of the virtual device's `OnOffBaseServer` to false (off).
     await device.setStateOf(OnOffBaseServer, { onOff: false });
     return device;
 }
-/**
- * Creates and add the virtual devices to the aggregator.
- *
- * @param {Matterbridge} matterbridge - The Matterbridge instance.
- * @param {Endpoint<AggregatorEndpoint>} aggregatorEndpoint - The aggregator node to add the virtual devices to.
- * @returns {Promise<void>} A promise that resolves when the virtual devices are added.
- */
 export async function addVirtualDevices(matterbridge, aggregatorEndpoint) {
     if (matterbridge.matterbridgeInformation.virtualMode !== 'disabled' && matterbridge.bridgeMode === 'bridge' && aggregatorEndpoint) {
         matterbridge.log.notice(`Creating virtual devices for Matterbridge server node...`);
@@ -144,4 +92,3 @@ export async function addVirtualDevices(matterbridge, aggregatorEndpoint) {
         }
     }
 }
-//# sourceMappingURL=helpers.js.map

package/dist/index.js

@@ -1,31 +1,6 @@
-/**
- * @description This file contains the entry point of Matterbridge.
- * @file index.ts
- * @author Luca Liguori
- * @created 2023-12-29
- * @version 1.0.7
- * @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.
- */
-// AnsiLogger module
 import { AnsiLogger } from 'node-ansi-logger';
-// Matterbridge
 import { Matterbridge } from './matterbridge.js';
 import { hasParameter } from './utils/export.js';
-// Matterbridge
 export * from './matterbridge.js';
 export * from './matterbridgeTypes.js';
 export * from './matterbridgeEndpoint.js';
@@ -36,10 +11,7 @@ export * from './matterbridgePlatform.js';
 export * from './matterbridgeAccessoryPlatform.js';
 export * from './matterbridgeDynamicPlatform.js';
 export { addVirtualDevice } from './helpers.js';
-const log = new AnsiLogger({ logName: 'Main', logTimestampFormat: 4 /* TimestampFormat.TIME_MILLIS */, logLevel: hasParameter('debug') ? "debug" /* LogLevel.DEBUG */ : "info" /* LogLevel.INFO */ });
-/**
- * Main function to load the Matterbridge instance.
- */
+const log = new AnsiLogger({ logName: 'Main', logTimestampFormat: 4, logLevel: hasParameter('debug') ? "debug" : "info" });
 async function main() {
     log.debug('***Matterbridge.loadInstance() called');
     await Matterbridge.loadInstance();
@@ -48,4 +20,3 @@ async function main() {
 main().catch((error) => {
     log.error(`Matterbridge.loadInstance() failed with error: ${error instanceof Error ? error.message : error}`);
 });
-//# sourceMappingURL=index.js.map

package/dist/jest-utils/jestHelpers.js

@@ -1,48 +1,8 @@
-/**
- * @description This file contains the Jest helpers.
- * @file src/jest/helpers.test.ts
- * @author Luca Liguori
- * @created 2025-09-03
- * @version 1.0.1
- * @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 { rmSync } from 'node:fs';
 import { inspect } from 'node:util';
-// Matterbridge imports
 import { DeviceTypeId, Endpoint, Environment, ServerNode, ServerNodeStore, VendorId, LogFormat as MatterLogFormat, LogLevel as MatterLogLevel, Lifecycle } from '@matter/main';
 import { AggregatorEndpoint, RootEndpoint } from '@matter/main/endpoints';
 import { MdnsService } from '@matter/main/protocol';
-// Plugins imports
-/*
-import { DeviceTypeId, Endpoint, Environment, MdnsService, ServerNode, ServerNodeStore, VendorId, LogFormat as MatterLogFormat, LogLevel as MatterLogLevel } from 'matterbridge/matter';
-import { RootEndpoint, AggregatorEndpoint } from 'matterbridge/matter/endpoints';
-*/
-/**
- * Advance the Node.js event loop deterministically to allow chained asynchronous work (Promises scheduled in
- * microtasks and follow‑up macrotasks) to complete inside tests without adding arbitrary long timeouts.
- *
- * NOTE: This does not guarantee OS level network IO completion—only JavaScript task queue progression inside the
- *       current process.
- *
- * @param {number} ticks       Number of macrotask (setImmediate) turns to yield (default 3).
- * @param {number} microTurns  Number of microtask drains (Promise.resolve chains) after macrotask yielding (default 10).
- * @param {number} pause       Final timer delay in ms; set 0 to disable (default 100ms).
- * @returns {Promise<void>}        Resolves after the requested event loop advancement has completed.
- */
 export async function flushAsync(ticks = 3, microTurns = 10, pause = 100) {
     for (let i = 0; i < ticks; i++)
         await new Promise((resolve) => setImmediate(resolve));
@@ -51,19 +11,6 @@ export async function flushAsync(ticks = 3, microTurns = 10, pause = 100) {
     if (pause)
         await new Promise((resolve) => setTimeout(resolve, pause));
 }
-/**
- * Flush (await) the lazy endpoint number persistence mechanism used by matter.js.
- *
- * Background:
- *  assignNumber() batches persistence (store.saveNumber + updating __nextNumber__) via an internal promise (#numbersPersisted).
- *  Calling endpointStores.close() waits for the current batch only. If new endpoints were added in the same macrotask
- *  cycle additional micro/macro turns might be needed to ensure the batch started. We defensively yield macrotasks
- *  (setImmediate) and then await close() multiple rounds.
- *
- * @param {ServerNode} targetServer  The server whose endpoint numbering persistence should be flushed.
- * @param {number} rounds Number of macrotask + close cycles to run (2 is usually sufficient; 1 often works).
- * @returns {Promise<void>}          Resolves when pending number persistence batches have completed.
- */
 export async function flushAllEndpointNumberPersistence(targetServer, rounds = 2) {
     const nodeStore = targetServer.env.get(ServerNodeStore);
     for (let i = 0; i < rounds; i++) {
@@ -71,12 +18,6 @@ export async function flushAllEndpointNumberPersistence(targetServer, rounds = 2
         await nodeStore.endpointStores.close();
     }
 }
-/**
- * Collect all endpoints in the server endpoint tree (root -> descendants).
- *
- * @param {Endpoint} root  Root endpoint (typically the ServerNode root endpoint cast as Endpoint).
- * @returns {Endpoint[]}   Flat array including the root and every descendant once.
- */
 function collectAllEndpoints(root) {
     const list = [];
     const walk = (ep) => {
@@ -90,26 +31,14 @@ function collectAllEndpoints(root) {
     walk(root);
     return list;
 }
-/**
- * Assert that every endpoint attached to the server has an assigned and (batch-)persisted endpoint number.
- *
- * This waits for any outstanding number persistence batch (endpointStores.close()), then traverses the endpoint
- * graph and asserts:
- *  - Root endpoint: number is 0 (allowing undefined to coerce to 0 via nullish coalescing check).
- *  - All other endpoints: number > 0.
- *
- * @param {ServerNode} targetServer The server whose endpoint numbers are verified.
- * @returns {Promise<void>}         Resolves when assertions complete.
- */
 export async function assertAllEndpointNumbersPersisted(targetServer) {
     const nodeStore = targetServer.env.get(ServerNodeStore);
-    // Ensure any pending persistence finished (flush any in-flight batch promise)
     await nodeStore.endpointStores.close();
     const all = collectAllEndpoints(targetServer);
     for (const ep of all) {
         const store = nodeStore.storeForEndpoint(ep);
         if (ep.maybeNumber === 0) {
-            expect(store.number ?? 0).toBe(0); // root
+            expect(store.number ?? 0).toBe(0);
         }
         else {
             expect(store.number).toBeGreaterThan(0);
@@ -117,20 +46,11 @@ export async function assertAllEndpointNumbersPersisted(targetServer) {
     }
     return all.length;
 }
-/**
- * Create a Matterbridge Environment for testing.
- * It will remove any existing home directory.
- *
- * @param {string} homeDir Home directory for the environment.
- * @returns {Environment}  The created environment.
- */
 export function createTestEnvironment(homeDir) {
     expect(homeDir).toBeDefined();
     expect(typeof homeDir).toBe('string');
-    expect(homeDir.length).toBeGreaterThan(5); // avoid accidental deletion of short paths like "/" or "C:\"
-    // Cleanup any existing home directory
+    expect(homeDir.length).toBeGreaterThan(5);
     rmSync(homeDir, { recursive: true, force: true });
-    // Setup the matter environment
     const environment = Environment.default;
     environment.vars.set('log.level', MatterLogLevel.DEBUG);
     environment.vars.set('log.format', MatterLogFormat.ANSI);
@@ -139,15 +59,7 @@ export function createTestEnvironment(homeDir) {
     environment.vars.set('runtime.exitcode', false);
     return environment;
 }
-/**
- * Start a Matterbridge ServerNode for testing.
- *
- * @param {string} name Name of the server (used for logging and product description).
- * @param {number} port TCP port to listen on.
- * @returns {Promise<[ServerNode<ServerNode.RootEndpoint>, Endpoint<AggregatorEndpoint>]>} Resolves to an array containing the created ServerNode and its AggregatorNode.
- */
 export async function startServerNode(name, port) {
-    // Create the server node
     const server = await ServerNode.create({
         id: name + 'ServerNode',
         productDescription: {
@@ -156,7 +68,6 @@ export async function startServerNode(name, port) {
             vendorId: VendorId(0xfff1),
             productId: 0x8000,
         },
-        // Provide defaults for the BasicInformation cluster on the Root endpoint
         basicInformation: {
             vendorId: VendorId(0xfff1),
             vendorName: 'Matterbridge',
@@ -173,26 +84,21 @@ export async function startServerNode(name, port) {
     });
     expect(server).toBeDefined();
     expect(server.lifecycle.isReady).toBeTruthy();
-    // Create the aggregator node
     const aggregator = new Endpoint(AggregatorEndpoint, {
         id: name + 'AggregatorNode',
     });
     expect(aggregator).toBeDefined();
-    // Add the aggregator to the server
     await server.add(aggregator);
     expect(server.parts.has(aggregator.id)).toBeTruthy();
     expect(server.parts.has(aggregator)).toBeTruthy();
     expect(aggregator.lifecycle.isReady).toBeTruthy();
-    // Run the server
     expect(server.lifecycle.isOnline).toBeFalsy();
-    // Wait for the server to be online
     await new Promise((resolve) => {
         server.lifecycle.online.on(async () => {
             resolve();
         });
         server.start();
     });
-    // Check if the server is online
     expect(server.lifecycle.isReady).toBeTruthy();
     expect(server.lifecycle.isOnline).toBeTruthy();
     expect(server.lifecycle.isCommissioned).toBeFalsy();
@@ -206,36 +112,18 @@ export async function startServerNode(name, port) {
     expect(aggregator.lifecycle.hasNumber).toBeTruthy();
     return [server, aggregator];
 }
-/**
- * Stop a Matterbridge ServerNode.
- *
- * @param {ServerNode<ServerNode.RootEndpoint>} server The server to stop.
- * @returns {Promise<void>} Resolves when the server has stopped.
- */
 export async function stopServerNode(server) {
-    // Flush any pending endpoint number persistence
     await flushAllEndpointNumberPersistence(server);
-    // Ensure all endpoint numbers are persisted
     await assertAllEndpointNumbersPersisted(server);
-    // Stop the server
     expect(server).toBeDefined();
     expect(server.lifecycle.isReady).toBeTruthy();
     expect(server.lifecycle.isOnline).toBeTruthy();
     await server.close();
     expect(server.lifecycle.isReady).toBeTruthy();
     expect(server.lifecycle.isOnline).toBeFalsy();
-    // stop the mDNS service
     await server.env.get(MdnsService)[Symbol.asyncDispose]();
-    // Ensure the queue is empty and pause 100ms
     await flushAsync();
 }
-/**
- * Add a device (endpoint) to a server or aggregator.
- *
- * @param {ServerNode<ServerNode.RootEndpoint> | Endpoint<AggregatorEndpoint>} owner The server or aggregator to add the device to.
- * @param {Endpoint} device The device to add.
- * @returns {Promise<void>} Resolves when the device has been added and is ready.
- */
 export async function addDevice(owner, device) {
     expect(owner).toBeDefined();
     expect(device).toBeDefined();
@@ -248,7 +136,6 @@ export async function addDevice(owner, device) {
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : error;
         const errorInspect = inspect(error, { depth: 10 });
-        // eslint-disable-next-line no-console
         console.error(`Error adding device ${device.maybeId}.${device.maybeNumber}: ${errorMessage}\nstack: ${errorInspect}`);
         return false;
     }
@@ -261,13 +148,6 @@ export async function addDevice(owner, device) {
     expect(device.construction.status).toBe(Lifecycle.Status.Active);
     return true;
 }
-/**
- * Add a device (endpoint) to a server or aggregator.
- *
- * @param {ServerNode<ServerNode.RootEndpoint> | Endpoint<AggregatorEndpoint>} owner The server or aggregator to add the device to.
- * @param {Endpoint} device The device to add.
- * @returns {Promise<void>} Resolves when the device has been added and is ready.
- */
 export async function deleteDevice(owner, device) {
     expect(owner).toBeDefined();
     expect(device).toBeDefined();
@@ -280,7 +160,6 @@ export async function deleteDevice(owner, device) {
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : error;
         const errorInspect = inspect(error, { depth: 10 });
-        // eslint-disable-next-line no-console
         console.error(`Error deleting device ${device.maybeId}.${device.maybeNumber}: ${errorMessage}\nstack: ${errorInspect}`);
         return false;
     }
@@ -293,4 +172,3 @@ export async function deleteDevice(owner, device) {
     expect(device.construction.status).toBe(Lifecycle.Status.Destroyed);
     return true;
 }
-//# sourceMappingURL=jestHelpers.js.map

package/dist/logger/export.js

@@ -1,2 +1 @@
 export * from 'node-ansi-logger';
-//# sourceMappingURL=export.js.map

package/dist/matter/behaviors.js

@@ -1,3 +1 @@
-// @matter
 export * from '@matter/node/behaviors';
-//# sourceMappingURL=behaviors.js.map

package/dist/matter/clusters.js

@@ -1,3 +1 @@
-// @matter
 export * from '@matter/types/clusters';
-//# sourceMappingURL=clusters.js.map

package/dist/matter/devices.js

@@ -1,3 +1 @@
-// @matter
 export * from '@matter/node/devices';
-//# sourceMappingURL=devices.js.map

package/dist/matter/endpoints.js

@@ -1,3 +1 @@
-// @matter
 export { AggregatorEndpoint, ElectricalSensorEndpoint, PowerSourceEndpoint, BridgedNodeEndpoint, RootEndpoint, DeviceEnergyManagementEndpoint, OtaProviderEndpoint, OtaRequestorEndpoint } from '@matter/node/endpoints';
-//# sourceMappingURL=endpoints.js.map

package/dist/matter/export.js

@@ -1,7 +1,4 @@
-/* eslint-disable import/export */
-// @matter
 export * from '@matter/main';
 export { SemanticNamespace, ClosureTag, CompassDirectionTag, CompassLocationTag, DirectionTag, ElectricalMeasurementTag, LaundryTag, LevelTag, LocationTag, NumberTag, PositionTag, PowerSourceTag, RefrigeratorTag, RoomAirConditionerTag, SwitchesTag, } from '@matter/main';
 export { AttributeElement, ClusterElement, ClusterModel, CommandElement, EventElement, FieldElement } from '@matter/main/model';
 export { MdnsService, Val } from '@matter/main/protocol';
-//# sourceMappingURL=export.js.map

package/dist/matter/types.js

@@ -1,5 +1,2 @@
-/* eslint-disable import/export */
-// @matter
 export * from '@matter/types';
 export { ClusterRegistry } from '@matter/types';
-//# sourceMappingURL=types.js.map