homebridge-plugin-utils 1.34.0 → 2.0.0

package/dist/mqttclient.js

@@ -1,310 +0,0 @@
-/* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
- *
- * mqttclient.ts: MQTT connectivity class for Homebridge plugins.
- */
-import { connect } from "mqtt";
-import util from "node:util";
-const MQTT_DEFAULT_RECONNECT_INTERVAL = 60;
-/**
- * MQTT connectivity and topic management class for Homebridge plugins.
- *
- * This class manages connection, publishing, subscription, and message handling for an MQTT broker, and provides convenience methods for Homebridge accessories to
- * interact with MQTT topics using a standard topic prefix.
- *
- * @example
- *
- * ```ts
- * const mqtt = new MqttClient("mqtt://localhost:1883", "homebridge", log);
- *
- * // Publish a message to a topic.
- * mqtt.publish("device1", "status", "on");
- *
- * // Subscribe to a topic.
- * mqtt.subscribe("device1", "status", (msg) => {
- *
- *   console.log(msg.toString());
- * });
- *
- * // Subscribe to a 'get' topic and automatically publish a value in response.
- * mqtt.subscribeGet("device1", "temperature", "Temperature", () => "21.5");
- *
- * // Subscribe to a 'set' topic and handle value changes.
- * mqtt.subscribeSet("device1", "switch", "Switch", (value) => {
- *
- *   console.log("Switch set to", value);
- * });
- *
- * // Unsubscribe from a topic.
- * mqtt.unsubscribe("device1", "status");
- * ```
- */
-export class MqttClient {
-    brokerUrl;
-    isConnected;
-    reconnectInterval;
-    log;
-    mqtt;
-    subscriptions;
-    topicPrefix;
-    /**
-     * Creates a new MQTT client for connecting to a broker and managing topics with a given prefix.
-     *
-     * @param brokerUrl          - The MQTT broker URL (e.g., "mqtt://localhost:1883").
-     * @param topicPrefix        - Prefix to use for all MQTT topics (e.g., "homebridge").
-     * @param log                - Logger for debug and info messages.
-     * @param reconnectInterval  - Optional. Interval (in seconds) to wait between reconnection attempts. Defaults to 60 seconds.
-     *
-     * @example
-     *
-     * ```ts
-     * const mqtt = new MqttClient("mqtt://localhost", "homebridge", log);
-     * ```
-     *
-     * @remarks URL must conform to formats supported by {@link https://github.com/mqttjs/MQTT.js | MQTT.js}.
-     */
-    constructor(brokerUrl, topicPrefix, log, reconnectInterval = MQTT_DEFAULT_RECONNECT_INTERVAL) {
-        this.brokerUrl = brokerUrl;
-        this.isConnected = false;
-        this.log = log;
-        this.mqtt = null;
-        this.reconnectInterval = reconnectInterval;
-        this.subscriptions = new Map();
-        this.topicPrefix = topicPrefix;
-        this.configure();
-    }
-    /**
-     * Initializes and connects the MQTT client to the broker, setting up event handlers for connection, messages, and errors.
-     *
-     * Catches invalid broker URLs and logs errors. Handles all major MQTT client events internally.
-     */
-    configure() {
-        // Try to connect to the MQTT broker and make sure we catch any URL errors.
-        try {
-            this.mqtt = connect(this.brokerUrl, { reconnectPeriod: this.reconnectInterval * 1000, rejectUnauthorized: false });
-        }
-        catch (error) {
-            if (error instanceof Error) {
-                switch (error.message) {
-                    case "Missing protocol":
-                        this.log.error("MQTT Broker: Invalid URL provided: %s.", this.brokerUrl);
-                        break;
-                    default:
-                        this.log.error("MQTT Broker: Error: %s.", error.message);
-                        break;
-                }
-            }
-        }
-        // We've been unable to even attempt to connect. It's likely we have a configuration issue - we're done here.
-        if (!this.mqtt) {
-            return;
-        }
-        // Notify the user when we connect to the broker.
-        this.mqtt.on("connect", () => {
-            this.isConnected = true;
-            // Inform users, while redacting authentication credentials.
-            this.log.info("MQTT Broker: Connected to %s (topic: %s).", this.brokerUrl.replace(/^(.*:\/\/.*:)(.*)(@.*)$/, "$1REDACTED$3"), this.topicPrefix);
-        });
-        // Notify the user when we've disconnected.
-        this.mqtt.on("close", () => {
-            // We only inform users if we're already connected. Otherwise, we're likely in an error state and that's logged elsewhere.
-            if (!this.isConnected) {
-                return;
-            }
-            this.isConnected = false;
-            // Inform users.
-            this.log.info("MQTT Broker: Connection closed.");
-        });
-        // Process inbound messages and pass it to the right message handler.
-        this.mqtt.on("message", (topic, message) => {
-            void this.subscriptions.get(topic)?.(message);
-        });
-        // Notify the user when there's a connectivity error.
-        this.mqtt.on("error", (error) => {
-            const logError = (message) => {
-                this.log.error("MQTT Broker: %s. Will retry again in %s second%s.", message, this.reconnectInterval, this.reconnectInterval !== 1 ? "s" : "");
-            };
-            switch (error.code) {
-                case "ECONNREFUSED":
-                    logError("Connection refused");
-                    break;
-                case "ECONNRESET":
-                    logError("Connection reset");
-                    break;
-                case "ENOTFOUND":
-                    this.mqtt?.end(true);
-                    this.log.error("MQTT Broker: Hostname or IP address not found.");
-                    break;
-                default:
-                    logError(util.inspect(error, { sorted: true }));
-                    break;
-            }
-        });
-    }
-    /**
-     * Publishes a message to a topic for a specific device.
-     *
-     * Expands the topic using the topic prefix and device ID, then publishes the provided message string.
-     *
-     * @param id      - The device or accessory identifier.
-     * @param topic   - The topic name to publish to.
-     * @param message - The message payload to publish.
-     *
-     * @example
-     *
-     * ```ts
-     * mqtt.publish("device1", "status", "on");
-     * ```
-     */
-    publish(id, topic, message) {
-        const expandedTopic = this.expandTopic(id, topic);
-        // No valid topic returned, we're done.
-        if (!expandedTopic) {
-            return;
-        }
-        this.log.debug("MQTT publish: %s Message: %s.", expandedTopic, message);
-        // By default, we publish as: pluginTopicPrefix/id/topic
-        this.mqtt?.publish(expandedTopic, message);
-    }
-    /**
-     * Subscribes to a topic for a specific device and registers a handler for incoming messages.
-     *
-     * The topic is expanded using the prefix and device ID, and the callback will be called for each message received.
-     *
-     * @param id       - The device or accessory identifier.
-     * @param topic    - The topic name to subscribe to.
-     * @param callback - Handler function called with the message buffer.
-     *
-     * @example
-     *
-     * ```ts
-     * mqtt.subscribe("device1", "status", (msg) => {
-     *
-     *   console.log(msg.toString());
-     * });
-     * ```
-     */
-    subscribe(id, topic, callback) {
-        const expandedTopic = this.expandTopic(id, topic);
-        // No valid topic returned, we're done.
-        if (!expandedTopic) {
-            return;
-        }
-        this.log.debug("MQTT subscribe: %s.", expandedTopic);
-        // Add to our callback list.
-        this.subscriptions.set(expandedTopic, callback);
-        // Tell MQTT we're subscribing to this event.
-        // By default, we subscribe as: pluginTopicPrefix/id/topic
-        this.mqtt?.subscribe(expandedTopic);
-    }
-    /**
-     * Subscribes to a '<topic>/get' topic and publishes a value in response to "true" messages.
-     *
-     * When a message "true" is received on the '<topic>/get' topic, this method will publish the result of `getValue()` on the main topic. The log will record each status
-     * publication event.
-     *
-     * @param id       - The device or accessory identifier.
-     * @param topic    - The topic name to use.
-     * @param type     - A human-readable label for log messages (e.g., "Temperature").
-     * @param getValue - Function to get the value to publish as a string.
-     * @param log      - Optional logger for status output. Defaults to the class logger.
-     *
-     * @example
-     *
-     * ```ts
-     * mqtt.subscribeGet("device1", "temperature", "Temperature", () => "21.5");
-     * ```
-     */
-    subscribeGet(id, topic, type, getValue, log = this.log) {
-        // Subscribe to the get topic and publish the current value when requested.
-        this.subscribe(id, topic + "/get", (message) => {
-            const value = message.toString().toLowerCase();
-            // We only respond to "true" messages on the get topic.
-            if (value !== "true") {
-                return;
-            }
-            this.publish(id, topic, getValue());
-            log.info("MQTT: %s status published.", type);
-        });
-    }
-    /**
-     * Subscribes to a '<topic>/set' topic and calls a setter when a message is received.
-     *
-     * The `setValue` function is called with both a normalized value and the raw string. Handles both synchronous and promise-based setters. Logs when set messages are
-     * received and when errors occur.
-     *
-     * @param id        - The device or accessory identifier.
-     * @param topic     - The topic name to use.
-     * @param type      - A human-readable label for log messages (e.g., "Switch").
-     * @param setValue  - Function to call when a value is set. Can be synchronous or return a Promise.
-     * @param log       - Optional logger for status output. Defaults to the class logger.
-     *
-     * @example
-     *
-     * ```ts
-     * mqtt.subscribeSet("device1", "switch", "Switch", (value) => {
-     *
-     *   console.log("Switch set to", value);
-     * });
-     * ```
-     */
-    subscribeSet(id, topic, type, setValue, log = this.log) {
-        // Subscribe to the set topic and invoke the setter callback when a value is received.
-        this.subscribe(id, topic + "/set", async (message) => {
-            const value = message.toString().toLowerCase();
-            // Set our value and inform the user.
-            try {
-                await setValue(value, message.toString());
-                log.info("MQTT: set message received for %s: %s.", type, value);
-            }
-            catch (error) {
-                log.error("MQTT: error setting message received for %s: %s. %s", type, value, error);
-            }
-        });
-    }
-    /**
-     * Unsubscribes from a topic for a specific device, removing its message handler.
-     *
-     * @param id    - The device or accessory identifier.
-     * @param topic - The topic name to unsubscribe from.
-     *
-     * @example
-     *
-     * ```ts
-     * mqtt.unsubscribe("device1", "status");
-     * ```
-     */
-    unsubscribe(id, topic) {
-        const expandedTopic = this.expandTopic(id, topic);
-        // No valid topic returned, we're done.
-        if (!expandedTopic) {
-            return;
-        }
-        this.subscriptions.delete(expandedTopic);
-        this.mqtt?.unsubscribe(expandedTopic);
-    }
-    /**
-     * Expands a topic string into a fully-formed topic path including the prefix and device ID.
-     *
-     * Returns `null` if the device ID is missing or empty.
-     *
-     * @param id    - The device or accessory identifier.
-     * @param topic - The topic name to expand.
-     *
-     * @returns The expanded topic string, or `null` if the ID is missing.
-     *
-     * @example
-     *
-     * ```ts
-     * const topic = mqtt['expandTopic']("device1", "status");
-     * // topic = "homebridge/device1/status"
-     * ```
-     */
-    expandTopic(id, topic) {
-        // No id, we're done.
-        if (!id) {
-            return null;
-        }
-        return this.topicPrefix + "/" + id + "/" + topic;
-    }
-}
-//# sourceMappingURL=mqttclient.js.map

package/dist/mqttclient.js.map

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