matterbridge 3.3.2-dev-20251012-0a89052 → 3.3.2

package/dist/utils/jestHelpers.js

@@ -1,21 +1,68 @@
+/**
+ * @description This file contains the Jest helpers.
+ * @file src/helpers.test.ts
+ * @author Luca Liguori
+ * @created 2025-09-03
+ * @version 1.0.5
+ * @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';
 import path from 'node:path';
+// Imports from Matterbridge
 import { jest } from '@jest/globals';
 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';
 import { AnsiLogger } from 'node-ansi-logger';
+// Imports from a plugin
+/*
+import { jest } from '@jest/globals';
+import { DeviceTypeId, Endpoint, Environment, MdnsService, ServerNode, ServerNodeStore, VendorId, LogFormat as MatterLogFormat, LogLevel as MatterLogLevel, Lifecycle } from 'matterbridge/matter';
+import { RootEndpoint, AggregatorEndpoint } from 'matterbridge/matter/endpoints';
+import { AnsiLogger } from 'matterbridge/logger';
+*/
 export let loggerLogSpy;
 export let consoleLogSpy;
 export let consoleDebugSpy;
 export let consoleInfoSpy;
 export let consoleWarnSpy;
 export let consoleErrorSpy;
+/**
+ * Setup the Jest environment:
+ * - it will remove any existing home directory
+ * - setup the spies for logging
+ *
+ * @param {string} name The name of the test suite.
+ * @param {boolean} debug If true, the logging is not mocked.
+ *
+ * ```typescript
+ * import { consoleDebugSpy, consoleErrorSpy, consoleInfoSpy, consoleLogSpy, consoleWarnSpy, loggerLogSpy, setDebug, setupTest } from './jestHelpers.js';
+ *
+ * // Setup the test environment
+ * setupTest(NAME, false);
+ *
+ * ```
+ */
 export function setupTest(name, debug = false) {
     expect(name).toBeDefined();
     expect(typeof name).toBe('string');
-    expect(name.length).toBeGreaterThanOrEqual(4);
+    expect(name.length).toBeGreaterThanOrEqual(4); // avoid accidental deletion of short paths like "/" or "C:\"
+    // Cleanup any existing home directory
     rmSync(path.join('jest', name), { recursive: true, force: true });
     if (debug) {
         loggerLogSpy = jest.spyOn(AnsiLogger.prototype, 'log');
@@ -34,6 +81,11 @@ export function setupTest(name, debug = false) {
         consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(() => { });
     }
 }
+/**
+ * Set or unset the debug mode.
+ *
+ * @param {boolean} debug If true, the logging is not mocked.
+ */
 export function setDebug(debug) {
     if (debug) {
         loggerLogSpy.mockRestore();
@@ -58,11 +110,21 @@ export function setDebug(debug) {
         consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(() => { });
     }
 }
+/**
+ * Create a matter Environment for testing:
+ * - it will remove any existing home directory
+ * - setup the matter environment with homeDir, debug logging and ANSI format
+ *
+ * @param {string} homeDir Home directory for the environment.
+ * @returns {Environment}  The default matter environment.
+ */
 export function createTestEnvironment(homeDir) {
     expect(homeDir).toBeDefined();
     expect(typeof homeDir).toBe('string');
-    expect(homeDir.length).toBeGreaterThanOrEqual(4);
+    expect(homeDir.length).toBeGreaterThanOrEqual(4); // avoid accidental deletion of short paths like "/" or "C:\"
+    // Cleanup any existing home directory
     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);
@@ -71,6 +133,18 @@ export function createTestEnvironment(homeDir) {
     environment.vars.set('runtime.exitcode', false);
     return environment;
 }
+/**
+ * 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));
@@ -79,6 +153,19 @@ 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++) {
@@ -86,6 +173,12 @@ 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) => {
@@ -99,14 +192,26 @@ 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);
+            expect(store.number ?? 0).toBe(0); // root
         }
         else {
             expect(store.number).toBeGreaterThan(0);
@@ -114,7 +219,15 @@ export async function assertAllEndpointNumbersPersisted(targetServer) {
     }
     return all.length;
 }
+/**
+ * Start a matter server node 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: {
@@ -123,6 +236,7 @@ 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',
@@ -139,21 +253,26 @@ 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();
@@ -165,21 +284,41 @@ export async function startServerNode(name, port) {
     expect(aggregator.lifecycle.isPartsReady).toBeTruthy();
     expect(aggregator.lifecycle.hasId).toBeTruthy();
     expect(aggregator.lifecycle.hasNumber).toBeTruthy();
+    // Ensure the queue is empty and pause 100ms
     await flushAsync();
     return [server, aggregator];
 }
+/**
+ * Stop a matter server node.
+ *
+ * @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 matter server node or an aggregator.
+ *
+ * @param {ServerNode<ServerNode.RootEndpoint> | Endpoint<AggregatorEndpoint>} owner The server or aggregator to add the device to.
+ * @param {Endpoint} device The device to add.
+ * @param {number} pause The pause time in milliseconds after addition (default 10ms).
+ * @returns {Promise<void>} Resolves when the device has been added and is ready.
+ */
 export async function addDevice(owner, device, pause = 10) {
     expect(owner).toBeDefined();
     expect(device).toBeDefined();
@@ -192,6 +331,7 @@ export async function addDevice(owner, device, pause = 10) {
     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;
     }
@@ -205,6 +345,14 @@ export async function addDevice(owner, device, pause = 10) {
     await flushAsync(1, 1, pause);
     return true;
 }
+/**
+ * Delete a device (endpoint) from a matter server node or an aggregator.
+ *
+ * @param {ServerNode<ServerNode.RootEndpoint> | Endpoint<AggregatorEndpoint>} owner The server or aggregator to remove the device from.
+ * @param {Endpoint} device The device to remove.
+ * @param {number} pause The pause time in milliseconds after deletion (default 10ms).
+ * @returns {Promise<void>} Resolves when the device has been removed and is no longer ready.
+ */
 export async function deleteDevice(owner, device, pause = 10) {
     expect(owner).toBeDefined();
     expect(device).toBeDefined();
@@ -217,6 +365,7 @@ export async function deleteDevice(owner, device, pause = 10) {
     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;
     }
@@ -230,3 +379,4 @@ export async function deleteDevice(owner, device, pause = 10) {
     await flushAsync(1, 1, pause);
     return true;
 }
+//# sourceMappingURL=jestHelpers.js.map

package/dist/utils/jestHelpers.js.map

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

package/dist/utils/network.d.ts

@@ -0,0 +1,115 @@
+/**
+ * @description This file contains the network functions.
+ * @file network.ts
+ * @author Luca Liguori
+ * @created 2024-02-17
+ * @version 1.0.1
+ * @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.
+ */
+/**
+ * Retrieves the first non-internal network interface details.
+ *
+ * @returns {os.NetworkInterfaceInfo | undefined} The details of the selected network interface, or undefined if not found.
+ */
+export declare function getInterfaceDetails(): {
+    interfaceName: string;
+    ipv4Address: string | undefined;
+    ipv6Address: string | undefined;
+    macAddress: string | undefined;
+} | undefined;
+/**
+ * Retrieves the first non-internal network interface name.
+ *
+ * @returns {string | undefined} The name of the selected network interface, or undefined if not found.
+ */
+export declare function getInterfaceName(): string | undefined;
+/**
+ * Retrieves the IPv4 address of the first non-internal network interface.
+ *
+ * @returns {string | undefined} The IPv4 address of the selected network interface, or undefined if not found.
+ */
+export declare function getIpv4InterfaceAddress(): string | undefined;
+/**
+ * Retrieves the IPv6 address of the first non-internal network interface.
+ *
+ * @returns {string | undefined} The IPv4 address of the selected network interface, or undefined if not found.
+ */
+export declare function getIpv6InterfaceAddress(): string | undefined;
+/**
+ * Retrieves the mac address of the first non-internal network interface.
+ *
+ * @returns {string | undefined} The mac address, or undefined if not found.
+ */
+export declare function getMacAddress(): string | undefined;
+/**
+ * Logs the available network interfaces and their details.
+ *
+ * @returns {void}
+ */
+export declare function logInterfaces(): void;
+/**
+ * Resolves the given hostname to an IP address.
+ *
+ * @param {string} hostname - The hostname to resolve.
+ * @param {0 | 4 | 6} [family] - The address family to use (0 for any, 4 for IPv4, 6 for IPv6). Default is 4.
+ * @returns {Promise<string | null>} - A promise that resolves to the IP address or null if not found.
+ *
+ * @remarks
+ * This function uses DNS lookup to resolve the hostname, which can take some time to complete.
+ */
+export declare function resolveHostname(hostname: string, family?: 0 | 4 | 6): Promise<string | null>;
+/**
+ * Retrieves the version of an npm package from the npm registry.
+ *
+ * @param {string} packageName - The name of the npm package.
+ * @param {string} [tag] - The tag of the package version to retrieve (default is 'latest').
+ * @param {number} [timeout] - The timeout duration in milliseconds (default is 10000ms).
+ * @returns {Promise<string>} A promise that resolves to the version string of the package.
+ * @throws {Error} If the request fails or the tag is not found.
+ */
+export declare function getNpmPackageVersion(packageName: string, tag?: string, timeout?: number): Promise<string>;
+/**
+ * Retrieves a file from the public directory of the Matterbridge GitHub repository.
+ *
+ * @param {string} branch - The branch from which to fetch the file.
+ * @param {string} file - The file path to fetch.
+ * @param {number} [timeout] - The timeout duration in milliseconds (default is 10000ms).
+ * @returns {Promise<Record<string, boolean | string | number>>} A promise that resolves to the parsed JSON object from the file.
+ * @throws {Error} If the request fails or the JSON parsing fails.
+ */
+export declare function getGitHubUpdate(branch: 'main' | 'dev', file: string, timeout?: number): Promise<Record<string, boolean | string | number>>;
+/**
+ * Retrieves the path to the global Node.js modules directory.
+ *
+ * @returns {Promise<string>} A promise that resolves to the path of the global Node.js modules directory.
+ */
+export declare function getGlobalNodeModules(): Promise<string>;
+/**
+ * Function to format bytes to KB, MB, or GB
+ *
+ * @param {number} bytes - The number of bytes to format
+ * @returns {string} The formatted memory usage string
+ */
+export declare function formatMemoryUsage(bytes: number): string;
+/**
+ * Function to format system uptime with only the most significant unit
+ *
+ * @param {number} seconds - The number of seconds to format
+ * @returns {string} The formatted uptime string
+ */
+export declare function formatOsUpTime(seconds: number): string;
+//# sourceMappingURL=network.d.ts.map

package/dist/utils/network.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"network.d.ts","sourceRoot":"","sources":["../../src/utils/network.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAUH;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI;IAAE,aAAa,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GAAG,SAAS,CAa7K;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,SAAS,CAOrD;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,GAAG,SAAS,CAO5D;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,GAAG,SAAS,CAO5D;AAED;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,MAAM,GAAG,SAAS,CAOlD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,IAAI,CAmBpC;AAED;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAE,CAAC,GAAG,CAAC,GAAG,CAAK,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CASrG;AAED;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,GAAE,MAAiB,EAAE,OAAO,GAAE,MAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA8ChI;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,MAAc,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC,CAAC,CAyCvJ;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,MAAM,CAAC,CAW5D;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQvD;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CActD"}

package/dist/utils/network.js

@@ -1,5 +1,34 @@
+/**
+ * @description This file contains the network functions.
+ * @file network.ts
+ * @author Luca Liguori
+ * @created 2024-02-17
+ * @version 1.0.1
+ * @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.
+ */
+// Node.js modules
 import os from 'node:os';
+// AnsiLogger module
 import { AnsiLogger, BLUE, CYAN, nf } from 'node-ansi-logger';
+/**
+ * Retrieves the first non-internal network interface details.
+ *
+ * @returns {os.NetworkInterfaceInfo | undefined} The details of the selected network interface, or undefined if not found.
+ */
 export function getInterfaceDetails() {
     const result = { interfaceName: '', ipv4Address: undefined, ipv6Address: undefined, macAddress: undefined };
     for (const [interfaceName, interfaceDetails] of Object.entries(os.networkInterfaces())) {
@@ -21,6 +50,11 @@ export function getInterfaceDetails() {
     if (result.interfaceName)
         return result;
 }
+/**
+ * Retrieves the first non-internal network interface name.
+ *
+ * @returns {string | undefined} The name of the selected network interface, or undefined if not found.
+ */
 export function getInterfaceName() {
     for (const [interfaceName, interfaceDetails] of Object.entries(os.networkInterfaces())) {
         if (!interfaceName || !interfaceDetails || interfaceDetails.length === 0)
@@ -31,6 +65,11 @@ export function getInterfaceName() {
         }
     }
 }
+/**
+ * Retrieves the IPv4 address of the first non-internal network interface.
+ *
+ * @returns {string | undefined} The IPv4 address of the selected network interface, or undefined if not found.
+ */
 export function getIpv4InterfaceAddress() {
     for (const [interfaceName, interfaceDetails] of Object.entries(os.networkInterfaces())) {
         if (!interfaceName || !interfaceDetails || interfaceDetails.length === 0)
@@ -41,6 +80,11 @@ export function getIpv4InterfaceAddress() {
         }
     }
 }
+/**
+ * Retrieves the IPv6 address of the first non-internal network interface.
+ *
+ * @returns {string | undefined} The IPv4 address of the selected network interface, or undefined if not found.
+ */
 export function getIpv6InterfaceAddress() {
     for (const [interfaceName, interfaceDetails] of Object.entries(os.networkInterfaces())) {
         if (!interfaceName || !interfaceDetails || interfaceDetails.length === 0)
@@ -51,6 +95,11 @@ export function getIpv6InterfaceAddress() {
         }
     }
 }
+/**
+ * Retrieves the mac address of the first non-internal network interface.
+ *
+ * @returns {string | undefined} The mac address, or undefined if not found.
+ */
 export function getMacAddress() {
     for (const [interfaceName, interfaceDetails] of Object.entries(os.networkInterfaces())) {
         if (!interfaceName || !interfaceDetails || interfaceDetails.length === 0)
@@ -61,9 +110,14 @@ export function getMacAddress() {
         }
     }
 }
+/**
+ * Logs the available network interfaces and their details.
+ *
+ * @returns {void}
+ */
 export function logInterfaces() {
-    const log = new AnsiLogger({ logName: 'MatterbridgeUtils', logTimestampFormat: 4, logLevel: "info" });
-    log.logLevel = "info";
+    const log = new AnsiLogger({ logName: 'MatterbridgeUtils', logTimestampFormat: 4 /* TimestampFormat.TIME_MILLIS */, logLevel: "info" /* LogLevel.INFO */ });
+    log.logLevel = "info" /* LogLevel.INFO */;
     log.logName = 'LogInterfaces';
     log.info('Available Network Interfaces:');
     const availableAddresses = Object.entries(os.networkInterfaces());
@@ -77,16 +131,36 @@ export function logInterfaces() {
         }
     }
 }
+/**
+ * Resolves the given hostname to an IP address.
+ *
+ * @param {string} hostname - The hostname to resolve.
+ * @param {0 | 4 | 6} [family] - The address family to use (0 for any, 4 for IPv4, 6 for IPv6). Default is 4.
+ * @returns {Promise<string | null>} - A promise that resolves to the IP address or null if not found.
+ *
+ * @remarks
+ * This function uses DNS lookup to resolve the hostname, which can take some time to complete.
+ */
 export async function resolveHostname(hostname, family = 4) {
     const dns = await import('node:dns');
     try {
-        const addresses = await dns.promises.lookup(hostname.toLowerCase(), { family });
+        const addresses = await dns.promises.lookup(hostname.toLowerCase() /* + '.local'*/, { family });
         return addresses.address;
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
     }
     catch (error) {
         return null;
     }
 }
+/**
+ * Retrieves the version of an npm package from the npm registry.
+ *
+ * @param {string} packageName - The name of the npm package.
+ * @param {string} [tag] - The tag of the package version to retrieve (default is 'latest').
+ * @param {number} [timeout] - The timeout duration in milliseconds (default is 10000ms).
+ * @returns {Promise<string>} A promise that resolves to the version string of the package.
+ * @throws {Error} If the request fails or the tag is not found.
+ */
 export async function getNpmPackageVersion(packageName, tag = 'latest', timeout = 10000) {
     const https = await import('node:https');
     return new Promise((resolve, reject) => {
@@ -100,7 +174,7 @@ export async function getNpmPackageVersion(packageName, tag = 'latest', timeout
             let data = '';
             if (res.statusCode !== 200) {
                 clearTimeout(timeoutId);
-                res.resume();
+                res.resume(); // Discard response data to close the socket properly
                 reject(new Error(`Failed to fetch data. Status code: ${res.statusCode}`));
                 return;
             }
@@ -111,6 +185,7 @@ export async function getNpmPackageVersion(packageName, tag = 'latest', timeout
                 clearTimeout(timeoutId);
                 try {
                     const jsonData = JSON.parse(data);
+                    // console.log(`Package ${packageName} tag ${tag}`, jsonData);
                     const version = jsonData['dist-tags']?.[tag];
                     if (version) {
                         resolve(version);
@@ -130,6 +205,15 @@ export async function getNpmPackageVersion(packageName, tag = 'latest', timeout
         });
     });
 }
+/**
+ * Retrieves a file from the public directory of the Matterbridge GitHub repository.
+ *
+ * @param {string} branch - The branch from which to fetch the file.
+ * @param {string} file - The file path to fetch.
+ * @param {number} [timeout] - The timeout duration in milliseconds (default is 10000ms).
+ * @returns {Promise<Record<string, boolean | string | number>>} A promise that resolves to the parsed JSON object from the file.
+ * @throws {Error} If the request fails or the JSON parsing fails.
+ */
 export async function getGitHubUpdate(branch, file, timeout = 10000) {
     const https = await import('node:https');
     return new Promise((resolve, reject) => {
@@ -143,7 +227,7 @@ export async function getGitHubUpdate(branch, file, timeout = 10000) {
             let data = '';
             if (res.statusCode !== 200) {
                 clearTimeout(timeoutId);
-                res.resume();
+                res.resume(); // Discard response data to close the socket properly
                 reject(new Error(`Failed to fetch data. Status code: ${res.statusCode}`));
                 return;
             }
@@ -161,12 +245,18 @@ export async function getGitHubUpdate(branch, file, timeout = 10000) {
                 }
             });
         });
+        // istanbul ignore next
         req.on('error', (error) => {
             clearTimeout(timeoutId);
             reject(new Error(`Request failed: ${error instanceof Error ? error.message : error}`));
         });
     });
 }
+/**
+ * Retrieves the path to the global Node.js modules directory.
+ *
+ * @returns {Promise<string>} A promise that resolves to the path of the global Node.js modules directory.
+ */
 export async function getGlobalNodeModules() {
     const { exec } = await import('node:child_process');
     return new Promise((resolve, reject) => {
@@ -180,6 +270,12 @@ export async function getGlobalNodeModules() {
         });
     });
 }
+/**
+ * Function to format bytes to KB, MB, or GB
+ *
+ * @param {number} bytes - The number of bytes to format
+ * @returns {string} The formatted memory usage string
+ */
 export function formatMemoryUsage(bytes) {
     if (bytes >= 1024 ** 3) {
         return `${(bytes / 1024 ** 3).toFixed(2)} GB`;
@@ -191,6 +287,12 @@ export function formatMemoryUsage(bytes) {
         return `${(bytes / 1024).toFixed(2)} KB`;
     }
 }
+/**
+ * Function to format system uptime with only the most significant unit
+ *
+ * @param {number} seconds - The number of seconds to format
+ * @returns {string} The formatted uptime string
+ */
 export function formatOsUpTime(seconds) {
     if (seconds >= 86400) {
         const days = Math.floor(seconds / 86400);
@@ -206,3 +308,4 @@ export function formatOsUpTime(seconds) {
     }
     return `${seconds} second${seconds !== 1 ? 's' : ''}`;
 }
+//# sourceMappingURL=network.js.map