homebridge-plugin-utils 1.4.0 → 1.6.0

package/build/eslint-rules.mjs

@@ -213,9 +213,10 @@ const commonRules = {
   "eqeqeq": "warn",
   "no-await-in-loop": "warn",
   "no-console": "warn",
+  "no-restricted-syntax": ["warn", "TemplateLiteral"],
   "prefer-arrow-callback": "warn",
   "prefer-const": "warn",
-  "quotes": ["warn", "double", { "avoidEscape": true }],
+  "quotes": ["warn", "double", { "allowTemplateLiterals": false, "avoidEscape": false }],
   "sort-imports": "warn",
   "sort-keys": "warn",
   "sort-vars": "warn"

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./featureoptions.js";
 export * from "./mqttclient.js";
 export * from "./rtp.js";
-export * from "./utils.js";
+export * from "./service.js";
+export * from "./util.js";

package/dist/index.js

@@ -5,5 +5,6 @@
 export * from "./featureoptions.js";
 export * from "./mqttclient.js";
 export * from "./rtp.js";
-export * from "./utils.js";
+export * from "./service.js";
+export * from "./util.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC"}

package/dist/mqttclient.d.ts

@@ -1,5 +1,4 @@
-/// <reference types="node" />
-import { HomebridgePluginLogging } from "./utils.js";
+import { HomebridgePluginLogging } from "./util.js";
 export declare class MqttClient {
     private brokerUrl;
     private isConnected;

package/dist/rtp.d.ts

@@ -1,7 +1,14 @@
-/// <reference types="node" />
-/// <reference types="node" />
 import { EventEmitter } from "node:events";
-import { HomebridgePluginLogging } from "./utils.js";
+import { HomebridgePluginLogging } from "./util.js";
+/**
+ * Here's the problem this class solves: FFmpeg doesn't support multiplexing RTP and RTCP data on a single UDP port (RFC 5761). If it did, we wouldn't need this
+ * workaround for HomeKit compatibility, which does multiplex RTP and RTCP over a single UDP port.
+ *
+ * This class inspects all packets coming in from inputPort and demultiplexes RTP and RTCP traffic to rtpPort and rtcpPort, respectively.
+ *
+ * Credit to @dgreif and @brandawg93 who graciously shared their code as a starting point, and their collaboration in answering the questions needed to bring all this
+ * together. A special thank you to @Sunoo for the many hours of discussion and brainstorming on this and other topics.
+ */
 export declare class RtpDemuxer extends EventEmitter {
     private heartbeatTimer;
     private heartbeatMsg;

package/dist/rtp.js

@@ -8,7 +8,7 @@ import { EventEmitter, once } from "node:events";
 import { createSocket } from "node:dgram";
 // How often, in seconds, should we heartbeat FFmpeg in two-way audio sessions. This should be less than 5 seconds, which is FFmpeg's input timeout interval.
 const TWOWAY_HEARTBEAT_INTERVAL = 3;
-/*
+/**
  * Here's the problem this class solves: FFmpeg doesn't support multiplexing RTP and RTCP data on a single UDP port (RFC 5761). If it did, we wouldn't need this
  * workaround for HomeKit compatibility, which does multiplex RTP and RTCP over a single UDP port.
  *

package/dist/service.d.ts

@@ -0,0 +1,31 @@
+import { HAP, PlatformAccessory, Service, WithUUID } from "homebridge";
+/**
+ * Utility method that either creates a new service on an accessory, if needed, or returns an existing one. It optionally executes a callback to initialize a new
+ * instance of a service, if needed. Additionally, the various name characteristics of the service will be set to the specified name, optionally adding them as needed.
+ * @param hap             - HAP instance associated with the Homebridge plugin.
+ * @param accessory       - Homebridge accessory to check.
+ * @param serviceType     - Service type that is being instantiated or retrieved.
+ * @param subtype         - Service subtype, if needed.
+ * @param onServiceCreate - Callback to be used when a new service is created. It is not called when an existing service is found.
+ *
+ * @returns Returns the created or retrieved service, `null` otherwise.
+ *
+ * @remarks `onServiceCreate` is called with the newly created service as an argument to allow the caller to optionally configure it.
+ *
+ * @category Accessory
+ */
+export declare function acquireService(hap: HAP, accessory: PlatformAccessory, serviceType: WithUUID<typeof Service>, name: string, subtype?: string, onServiceCreate?: (svc: Service) => void): Service | null;
+/**
+ * Validate whether a service should exist, removing it if needed.
+ * @param accessory       - Homebridge accessory to check.
+ * @param serviceType     - Service type that is being instantiated or retrieved.
+ * @param validate        - Function to be used to test whether a service should exist or not.
+ * @param subtype         - Service subtype, if needed.
+ *
+ * @returns Returns `true` if the service is valid, will remove the service and return `false` otherwise.
+ *
+ * @remarks `validate` is called with an argument of `true` if the service currently exists on the accessory and `false` otherwise.
+ *
+ * @category Accessory
+ */
+export declare function validService(accessory: PlatformAccessory, serviceType: WithUUID<typeof Service>, validate: (hasService: boolean) => boolean, subtype?: string): boolean;

package/dist/service.js

@@ -0,0 +1,80 @@
+/**
+ * Utility method that either creates a new service on an accessory, if needed, or returns an existing one. It optionally executes a callback to initialize a new
+ * instance of a service, if needed. Additionally, the various name characteristics of the service will be set to the specified name, optionally adding them as needed.
+ * @param hap             - HAP instance associated with the Homebridge plugin.
+ * @param accessory       - Homebridge accessory to check.
+ * @param serviceType     - Service type that is being instantiated or retrieved.
+ * @param subtype         - Service subtype, if needed.
+ * @param onServiceCreate - Callback to be used when a new service is created. It is not called when an existing service is found.
+ *
+ * @returns Returns the created or retrieved service, `null` otherwise.
+ *
+ * @remarks `onServiceCreate` is called with the newly created service as an argument to allow the caller to optionally configure it.
+ *
+ * @category Accessory
+ */
+export function acquireService(hap, accessory, serviceType, name, subtype, onServiceCreate) {
+    // Services that need the ConfiguredName characteristic added and maintained.
+    const configuredNameServices = [hap.Service.ContactSensor, hap.Service.Lightbulb, hap.Service.MotionSensor, hap.Service.OccupancySensor, hap.Service.Switch];
+    // Services that need the Name characteristic maintained.
+    const nameServices = [hap.Service.Battery, hap.Service.ContactSensor, hap.Service.HumiditySensor, hap.Service.LeakSensor, hap.Service.Lightbulb,
+        hap.Service.LightSensor, hap.Service.MotionSensor, hap.Service.TemperatureSensor];
+    // Find the service, if it exists.
+    let service = subtype ? accessory.getServiceById(serviceType, subtype) : accessory.getService(serviceType);
+    // Add the service to the accessory, if needed.
+    if (!service) {
+        // @ts-expect-error TypeScript tries to associate this with an overloaded version of the addService method. However, Homebridge/HAP-NodeJS isn't exporting
+        // a version of the method that implements the unexposed interface that's been defined for each service class (e.g. Lightbulb). The constructor on the
+        // service-type-specific version of the service takes the following arguments: constructor(displayName?: string, subtype?: string). We're safe, but because
+        // the type definitions are missing, we need to override it here.
+        service = new serviceType(name, subtype);
+        if (!service) {
+            return null;
+        }
+        accessory.addService(service);
+        if (onServiceCreate) {
+            onServiceCreate(service);
+        }
+    }
+    // Update our name.
+    service.displayName = name;
+    if (configuredNameServices.includes(serviceType)) {
+        // Add the characteristic if we don't already have it. We do this here instead of at service creation to ensure we catch legacy situations where we may have
+        // already created the service previously without adding the optional characteristics we want.
+        if (!service.optionalCharacteristics.some(x => (x.UUID === hap.Characteristic.ConfiguredName.UUID))) {
+            service.addOptionalCharacteristic(hap.Characteristic.ConfiguredName);
+        }
+        service.updateCharacteristic(hap.Characteristic.ConfiguredName, name);
+    }
+    if (nameServices.includes(serviceType)) {
+        service.updateCharacteristic(hap.Characteristic.Name, name);
+    }
+    return service;
+}
+/**
+ * Validate whether a service should exist, removing it if needed.
+ * @param accessory       - Homebridge accessory to check.
+ * @param serviceType     - Service type that is being instantiated or retrieved.
+ * @param validate        - Function to be used to test whether a service should exist or not.
+ * @param subtype         - Service subtype, if needed.
+ *
+ * @returns Returns `true` if the service is valid, will remove the service and return `false` otherwise.
+ *
+ * @remarks `validate` is called with an argument of `true` if the service currently exists on the accessory and `false` otherwise.
+ *
+ * @category Accessory
+ */
+export function validService(accessory, serviceType, validate, subtype) {
+    // Find the switch service, if it exists.
+    const service = subtype ? accessory.getServiceById(serviceType, subtype) : accessory.getService(serviceType);
+    // Validate whether we should have the service. If not, remove it.
+    if (!validate(!!service)) {
+        if (service) {
+            accessory.removeService(service);
+        }
+        return false;
+    }
+    // We have a valid service.
+    return true;
+}
+//# sourceMappingURL=service.js.map

package/dist/service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,cAAc,CAAC,GAAQ,EAAE,SAA4B,EAAE,WAAqC,EAAE,IAAY,EAAE,OAAgB,EAC1I,eAAwC;IAExC,6EAA6E;IAC7E,MAAM,sBAAsB,GAAG,CAAE,GAAG,CAAC,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC,OAAO,CAAC,YAAY,EAAE,GAAG,CAAC,OAAO,CAAC,eAAe,EAAE,GAAG,CAAC,OAAO,CAAC,MAAM,CAAE,CAAC;IAE/J,yDAAyD;IACzD,MAAM,YAAY,GAAG,CAAE,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC,OAAO,CAAC,cAAc,EAAE,GAAG,CAAC,OAAO,CAAC,UAAU,EAAE,GAAG,CAAC,OAAO,CAAC,SAAS;QAC9I,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,GAAG,CAAC,OAAO,CAAC,YAAY,EAAE,GAAG,CAAC,OAAO,CAAC,iBAAiB,CAAE,CAAC;IAErF,kCAAkC;IAClC,IAAI,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,cAAc,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;IAE3G,+CAA+C;IAC/C,IAAG,CAAC,OAAO,EAAE,CAAC;QAEZ,0JAA0J;QAC1J,sJAAsJ;QACtJ,2JAA2J;QAC3J,iEAAiE;QACjE,OAAO,GAAG,IAAI,WAAW,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAEzC,IAAG,CAAC,OAAO,EAAE,CAAC;YAEZ,OAAO,IAAI,CAAC;QACd,CAAC;QAED,SAAS,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;QAE9B,IAAG,eAAe,EAAE,CAAC;YAEnB,eAAe,CAAC,OAAO,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;IAED,mBAAmB;IACnB,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAE3B,IAAG,sBAAsB,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;QAEhD,4JAA4J;QAC5J,8FAA8F;QAC9F,IAAG,CAAC,OAAO,CAAC,uBAAuB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,GAAG,CAAC,cAAc,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;YAEnG,OAAO,CAAC,yBAAyB,CAAC,GAAG,CAAC,cAAc,CAAC,cAAc,CAAC,CAAC;QACvE,CAAC;QAED,OAAO,CAAC,oBAAoB,CAAC,GAAG,CAAC,cAAc,CAAC,cAAc,EAAE,IAAI,CAAC,CAAC;IACxE,CAAC;IAED,IAAG,YAAY,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;QAEtC,OAAO,CAAC,oBAAoB,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC9D,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY,CAAC,SAA4B,EAAE,WAAqC,EAAE,QAA0C,EAAE,OAAgB;IAE5J,yCAAyC;IACzC,MAAM,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,cAAc,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;IAE7G,kEAAkE;IAClE,IAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;QAExB,IAAG,OAAO,EAAE,CAAC;YAEX,SAAS,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;QACnC,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC;IAED,2BAA2B;IAC3B,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/{utils.d.ts → util.d.ts}

@@ -1,4 +1,3 @@
-/// <reference types="node" />
 /**
  * @internal
  *
@@ -27,5 +26,6 @@ export interface HomebridgePluginLogging {
     info: (message: string, ...parameters: unknown[]) => void;
     warn: (message: string, ...parameters: unknown[]) => void;
 }
-export declare function sleep(sleepTimer: number): Promise<NodeJS.Timeout>;
 export declare function retry(operation: () => Promise<boolean>, retryInterval: number, totalRetries?: number): Promise<boolean>;
+export declare function runWithTimeout<T>(promise: Promise<T>, timeout: number): Promise<T | null>;
+export declare function sleep(sleepTimer: number): Promise<NodeJS.Timeout>;

package/dist/{utils.js → util.js}

@@ -1,11 +1,7 @@
 /* Copyright(C) 2017-2024, HJD (https://github.com/hjdhjd). All rights reserved.
  *
- * utils.ts: Useful utility functions when writing TypeScript.
+ * util.ts: Useful utility functions when writing TypeScript.
  */
-// Emulate a sleep function.
-export async function sleep(sleepTimer) {
-    return new Promise(resolve => setTimeout(resolve, sleepTimer));
-}
 // Retry an operation until we're successful.
 export async function retry(operation, retryInterval, totalRetries) {
     if ((totalRetries !== undefined) && (totalRetries < 0)) {
@@ -20,4 +16,13 @@ export async function retry(operation, retryInterval, totalRetries) {
     // We were successful - we're done.
     return true;
 }
-//# sourceMappingURL=utils.js.map
+// Run a promise with a guaranteed timeout to complete.
+export async function runWithTimeout(promise, timeout) {
+    const timeoutPromise = new Promise((resolve) => setTimeout(() => resolve(null), timeout));
+    return Promise.race([promise, timeoutPromise]);
+}
+// Emulate a sleep function.
+export async function sleep(sleepTimer) {
+    return new Promise(resolve => setTimeout(resolve, sleepTimer));
+}
+//# sourceMappingURL=util.js.map

package/dist/util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.js","sourceRoot":"","sources":["../src/util.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAqCH,6CAA6C;AAC7C,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,SAAiC,EAAE,aAAqB,EAAE,YAAqB;IAEzG,IAAG,CAAC,YAAY,KAAK,SAAS,CAAC,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC,EAAE,CAAC;QAEtD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,wCAAwC;IACxC,IAAG,CAAC,CAAC,MAAM,SAAS,EAAE,CAAC,EAAE,CAAC;QAExB,4FAA4F;QAC5F,MAAM,KAAK,CAAC,aAAa,CAAC,CAAC;QAE3B,OAAO,KAAK,CAAC,SAAS,EAAE,aAAa,EAAE,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,YAAY,EAAE,CAAC,CAAC;IACpG,CAAC;IAED,mCAAmC;IACnC,OAAO,IAAI,CAAC;AACd,CAAC;AAED,uDAAuD;AACvD,MAAM,CAAC,KAAK,UAAU,cAAc,CAAI,OAAmB,EAAE,OAAe;IAE1E,MAAM,cAAc,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;IAEhG,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC;AACjD,CAAC;AAED,4BAA4B;AAC5B,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,UAAkB;IAE5C,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC;AACjE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homebridge-plugin-utils",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "displayName": "Homebridge Plugin Utilities",
   "description": "Opinionated utilities to provide common capabilities and create rich configuration webUI experiences for Homebridge plugins.",
   "author": {
@@ -33,20 +33,21 @@
     "build": "npm run clean && tsc && shx cp dist/featureoptions.js{,.map} dist/ui",
     "build-ui": "shx mkdir -p dist/ui && shx cp ui/**.mjs dist/ui",
     "clean": "shx rm -rf dist && npm run build-ui",
-    "lint": "eslint eslint.config.mjs build/**.mjs src/**.ts \"ui/**/*.@(js|mjs)\"",
+    "lint": "eslint --max-warnings=${ESLINT_MAX_WARNINGS:-\"-1\"} eslint.config.mjs build/**.mjs src/**.ts \"ui/**/*.@(js|mjs)\"",
     "postpublish": "npm run clean",
     "prepublishOnly": "npm run lint && npm run build"
   },
   "main": "dist/index.js",
   "devDependencies": {
-    "@stylistic/eslint-plugin": "2.1.0",
-    "@types/node": "20.14.2",
+    "@stylistic/eslint-plugin": "2.3.0",
+    "@types/node": "20.14.11",
     "eslint": "8.57.0",
     "shx": "^0.3.4",
-    "typescript": "5.4.5",
-    "typescript-eslint": "^7.12.0"
+    "typescript": "5.5.3",
+    "typescript-eslint": "^7.16.1"
   },
   "dependencies": {
-    "mqtt": "^5.7.0"
+    "homebridge": "^1.8.4",
+    "mqtt": "^5.8.1"
   }
 }

package/dist/utils.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA4CH,4BAA4B;AAC5B,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,UAAkB;IAE5C,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC;AACjE,CAAC;AAED,6CAA6C;AAC7C,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,SAAiC,EAAE,aAAqB,EAAE,YAAqB;IAEzG,IAAG,CAAC,YAAY,KAAK,SAAS,CAAC,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC,EAAE,CAAC;QAEtD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,wCAAwC;IACxC,IAAG,CAAC,CAAC,MAAM,SAAS,EAAE,CAAC,EAAE,CAAC;QAExB,4FAA4F;QAC5F,MAAM,KAAK,CAAC,aAAa,CAAC,CAAC;QAE3B,OAAO,KAAK,CAAC,SAAS,EAAE,aAAa,EAAE,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,YAAY,EAAE,CAAC,CAAC;IACpG,CAAC;IAED,mCAAmC;IACnC,OAAO,IAAI,CAAC;AACd,CAAC"}