@espressif/rainmaker-neo-base-sdk 1.0.0

package/dist/cjs/services/ESPTransport/ESPDiscovery/ESPDiscoveryManager.js

@@ -0,0 +1,62 @@
+'use strict';
+
+var ESPRMNeoBase = require('../../../ESPRMNeoBase.js');
+var discovery = require('../../../types/discovery.js');
+var constants = require('../../../utils/constants.js');
+
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Manages local node discovery through the app-supplied local discovery
+ * adapter (see {@link ESPRMNeoBase.setLocalDiscoveryAdapter}).
+ *
+ * - With no discovery config, the default local protocol is used
+ *   (mDNS service `_esp_local_ctrl._tcp.` in the `local` domain).
+ * - A custom {@link DiscoveryParamsInterface} can be supplied for other
+ *   discovery protocols.
+ */
+class ESPDiscoveryManager {
+    /** Discovery parameters (service type / domain) passed to the adapter. */
+    params;
+    /**
+     * @param discoveryConfig - Optional custom discovery parameters. Defaults to
+     *   the local mDNS protocol.
+     * @throws {Error} If no local discovery adapter is set.
+     */
+    constructor(discoveryConfig) {
+        if (!ESPRMNeoBase.ESPRMNeoBase.getLocalDiscoveryAdapter()) {
+            throw new Error("ESPLocalDiscoveryAdapter not set");
+        }
+        this.params = discoveryConfig || {
+            serviceType: constants.ServiceType.ESP_LOCAL_CTRL_TCP,
+            domain: discovery.ESPDiscoveryProtocol.local,
+        };
+    }
+    get adapter() {
+        const adapter = ESPRMNeoBase.ESPRMNeoBase.getLocalDiscoveryAdapter();
+        if (!adapter) {
+            throw new Error("ESPLocalDiscoveryAdapter not set");
+        }
+        return adapter;
+    }
+    /**
+     * Starts discovery. The callback is invoked for each discovered node.
+     *
+     * @param callback - Invoked with the adapter's per-node discovery result.
+     */
+    startDiscovery(callback) {
+        this.adapter.startDiscovery(callback, this.params);
+    }
+    /**
+     * Stops any ongoing discovery started by {@link startDiscovery}.
+     */
+    stopDiscovery() {
+        this.adapter.stopDiscovery();
+    }
+}
+
+exports.ESPDiscoveryManager = ESPDiscoveryManager;
+//# sourceMappingURL=ESPDiscoveryManager.js.map

package/dist/cjs/services/ESPTransport/ESPDiscovery/ESPDiscoveryManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ESPDiscoveryManager.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/cjs/services/ESPTransport/ESPLocalControlTransport.js

@@ -0,0 +1,157 @@
+'use strict';
+
+var ESPRMNeoBase = require('../../ESPRMNeoBase.js');
+var constants$1 = require('../../proto/constants.js');
+var esp_local_ctrl = require('../../proto/esp_local_ctrl.js');
+var constants = require('../../utils/constants.js');
+var TransformEncoding = require('../ESPRMNeoHelpers/TransformEncoding.js');
+
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/** Property index of the writable "params" property exposed by RMNeo local-control firmware. */
+const LOCAL_CONTROL_PARAMS_INDEX = 1;
+/**
+ * Built-in `local` transport. Communicates with the node over the LAN through
+ * the app-supplied {@link ESPRMNeoBase.ESPLocalControlAdapter} using the
+ * `esp_local_ctrl` protobuf protocol. Connection metadata (`baseUrl`,
+ * `securityType`, `pop`, and `username` for sec2) is supplied via the transport
+ * config by {@link delegatedTransportHandler}.
+ */
+class ESPLocalControlTransport {
+    payload;
+    metadata;
+    propertyInfo = {};
+    constructor(transportConfig) {
+        this.metadata = transportConfig.metadata ?? {};
+    }
+    get adapter() {
+        const adapter = ESPRMNeoBase.ESPRMNeoBase.getLocalControlAdapter();
+        if (!adapter) {
+            throw new Error("Local control adapter is not configured");
+        }
+        return adapter;
+    }
+    /**
+     * Connects to the node, retrying on failure. RMNeo's adapter resolves on a
+     * successful connection and rejects otherwise, so a resolved call is treated
+     * as connected.
+     */
+    async connectWithRetry(nodeId, baseUrl, securityType, pop, username, maxRetries = 3) {
+        let attempt = 0;
+        let lastError;
+        while (attempt < maxRetries) {
+            try {
+                await this.adapter.connect(nodeId, baseUrl, securityType, pop, username);
+                return;
+            }
+            catch (error) {
+                lastError = error;
+                attempt += 1;
+            }
+        }
+        const message = lastError instanceof Error ? lastError.message : String(lastError);
+        throw new Error(`Failed to connect after ${maxRetries} attempts: ${message}`);
+    }
+    async ensureConnected(nodeId) {
+        const isConnected = await this.adapter.isConnected(nodeId);
+        if (!isConnected) {
+            await this.connectWithRetry(nodeId, this.metadata.baseUrl, this.metadata.securityType ?? 0, this.metadata.pop, this.metadata.username);
+        }
+    }
+    async setParam(payload, _nodeRef) {
+        this.payload = payload;
+        await this.ensureConnected(this.payload?.node_id);
+        const success = await this.setProperty(this.payload?.payload ?? {});
+        if (!success) {
+            throw new Error("Failed to set device params over local control");
+        }
+        return { message: "Parameters updated successfully", statusCode: 200 };
+    }
+    async getParams(payload, _nodeRef) {
+        this.payload = payload;
+        await this.ensureConnected(this.payload?.node_id);
+        return this.getPropertyInfo();
+    }
+    // ── set ──────────────────────────────────────────────────────────────────
+    async setProperty(json) {
+        const request = this.buildSetPropertyRequest(json);
+        const response = await this.adapter.sendData(this.payload?.node_id, constants.Endpoint.LOCAL_CTRL, request);
+        return this.processSetPropertyResponse(response);
+    }
+    buildSetPropertyRequest(json) {
+        const message = new esp_local_ctrl.LocalCtrlMessage();
+        message.msg = esp_local_ctrl.LocalCtrlMsgType.TypeCmdSetPropertyValues;
+        const cmd = new esp_local_ctrl.CmdSetPropertyValues();
+        const prop = new esp_local_ctrl.PropertyValue();
+        prop.index = LOCAL_CONTROL_PARAMS_INDEX;
+        prop.value = new TextEncoder().encode(JSON.stringify(json ?? {}));
+        cmd.props.push(prop);
+        message.cmd_set_prop_vals = cmd;
+        return TransformEncoding.uint8ArrayToBase64(message.serialize());
+    }
+    processSetPropertyResponse(response) {
+        const deserialized = esp_local_ctrl.LocalCtrlMessage.deserialize(TransformEncoding.base64ToUint8Array(response));
+        return deserialized.resp_set_prop_vals.status === constants$1.Status.Success;
+    }
+    // ── get ──────────────────────────────────────────────────────────────────
+    /** Fetches the property count, then reads each property value into propertyInfo. */
+    async getPropertyInfo() {
+        this.propertyInfo = {};
+        const count = await this.fetchPropertyCount();
+        for (let index = 0; index < count; index++) {
+            await this.fetchPropertyValue(index);
+        }
+        return this.propertyInfo;
+    }
+    async fetchPropertyCount() {
+        const response = await this.adapter.sendData(this.payload?.node_id, constants.Endpoint.LOCAL_CTRL, this.buildGetPropertyCountRequest());
+        return this.processGetPropertyCountResponse(response);
+    }
+    buildGetPropertyCountRequest() {
+        const request = new esp_local_ctrl.LocalCtrlMessage();
+        request.msg = esp_local_ctrl.LocalCtrlMsgType.TypeCmdGetPropertyCount;
+        request.cmd_get_prop_count = new esp_local_ctrl.CmdGetPropertyCount();
+        return TransformEncoding.uint8ArrayToBase64(request.serialize());
+    }
+    processGetPropertyCountResponse(response) {
+        const deserialized = esp_local_ctrl.LocalCtrlMessage.deserialize(TransformEncoding.base64ToUint8Array(response));
+        if (deserialized.resp_get_prop_count.status !== constants$1.Status.Success) {
+            throw new Error("Failed to retrieve property count from device");
+        }
+        return deserialized.resp_get_prop_count.count;
+    }
+    async fetchPropertyValue(index) {
+        const response = await this.adapter.sendData(this.payload?.node_id, constants.Endpoint.LOCAL_CTRL, this.buildGetPropertyValueRequest(index));
+        const property = this.processGetPropertyValueResponse(response);
+        if (property) {
+            this.propertyInfo[property.name] = property.value;
+        }
+    }
+    buildGetPropertyValueRequest(index) {
+        const request = new esp_local_ctrl.LocalCtrlMessage();
+        request.msg = esp_local_ctrl.LocalCtrlMsgType.TypeCmdGetPropertyValues;
+        const cmd = new esp_local_ctrl.CmdGetPropertyValues();
+        cmd.indices.push(index);
+        request.cmd_get_prop_vals = cmd;
+        return TransformEncoding.uint8ArrayToBase64(request.serialize());
+    }
+    processGetPropertyValueResponse(response) {
+        const deserialized = esp_local_ctrl.LocalCtrlMessage.deserialize(TransformEncoding.base64ToUint8Array(response));
+        if (deserialized.resp_get_prop_vals.status !== constants$1.Status.Success) {
+            throw new Error("Failed to get property values from device response");
+        }
+        const prop = deserialized.resp_get_prop_vals.props[0];
+        if (!prop)
+            return undefined;
+        return {
+            name: prop.name || "unknown",
+            value: JSON.parse(new TextDecoder().decode(prop.value)),
+        };
+    }
+}
+
+exports.ESPLocalControlTransport = ESPLocalControlTransport;
+//# sourceMappingURL=ESPLocalControlTransport.js.map

package/dist/cjs/services/ESPTransport/ESPLocalControlTransport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ESPLocalControlTransport.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/cjs/services/ESPTransport/ESPMqttTransport.js

@@ -0,0 +1,26 @@
+'use strict';
+
+var NodeMQTTOrchestrator = require('../NodeMQTTOrchestrator.js');
+
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Built-in `mqtt` transport — the RainMaker Neo cloud channel. Drives node
+ * params over MQTT (AWS IoT shadow / RainMaker user params topic) through
+ * {@link NodeMQTTOrchestrator}.
+ */
+class ESPMqttTransport {
+    async setParam(payload, _nodeRef) {
+        await NodeMQTTOrchestrator.NodeMQTTOrchestrator.setParams(payload.node_id, payload.payload);
+        return { message: "Parameters updated successfully", statusCode: 200 };
+    }
+    async getParams(payload, _nodeRef) {
+        return NodeMQTTOrchestrator.NodeMQTTOrchestrator.getParams(payload.node_id);
+    }
+}
+
+exports.ESPMqttTransport = ESPMqttTransport;
+//# sourceMappingURL=ESPMqttTransport.js.map

package/dist/cjs/services/ESPTransport/ESPMqttTransport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ESPMqttTransport.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/cjs/services/ESPTransport/ESPTransportManager.js

@@ -0,0 +1,42 @@
+'use strict';
+
+var transport = require('../../types/transport.js');
+var ESPMqttTransport = require('./ESPMqttTransport.js');
+var ESPLocalControlTransport = require('./ESPLocalControlTransport.js');
+
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Selects and wraps a built-in transport implementation based on the transport
+ * config `type`. The {@link delegatedTransportHandler} constructs one of these
+ * per transport attempt and drives it through {@link ESPTransportInterface}.
+ */
+class ESPTransportManager {
+    transport;
+    constructor(transportConfig) {
+        if (transportConfig) {
+            switch (transportConfig.type) {
+                case transport.ESPTransportMode.mqtt:
+                    this.transport = new ESPMqttTransport.ESPMqttTransport();
+                    break;
+                case transport.ESPTransportMode.local:
+                    this.transport = new ESPLocalControlTransport.ESPLocalControlTransport(transportConfig);
+                    break;
+                default:
+                    throw new Error(`Unsupported transport type: ${transportConfig.type}. Please provide a transport manager via customTransportManagers.`);
+            }
+        }
+    }
+    setParam(payload, nodeRef) {
+        return this.transport.setParam(payload, nodeRef);
+    }
+    getParams(payload, nodeRef) {
+        return this.transport.getParams(payload, nodeRef);
+    }
+}
+
+exports.ESPTransportManager = ESPTransportManager;
+//# sourceMappingURL=ESPTransportManager.js.map

package/dist/cjs/services/ESPTransport/ESPTransportManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ESPTransportManager.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/cjs/services/MQTTSubscriptionChannel.js

@@ -0,0 +1,274 @@
+'use strict';
+
+var NodeMQTTOrchestrator = require('./NodeMQTTOrchestrator.js');
+var transformShadowToNodeUpdate = require('./ESPRMNeoHelpers/transformShadowToNodeUpdate.js');
+var shadowUtils = require('../utils/shadowUtils.js');
+var constants = require('../utils/constants.js');
+var logger$1 = require('../utils/logger.js');
+
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const logger = new logger$1.Logger("MQTTSubscriptionChannel");
+/**
+ * MQTT subscription channel for ESP RainMaker Neo.
+ *
+ * This channel is a thin adapter over {@link NodeMQTTOrchestrator}, which owns
+ * the single MQTT connection, the AWS IoT shadow topic subscriptions, and the
+ * deduplication of nodes that share a group/subgroup shadow. The channel's job
+ * is only to:
+ *  - map a node to its shadow and register it with the orchestrator,
+ *  - normalize each shadow message into the canonical {@link ESPNodeUpdateData}
+ *    envelope (so the app sees the same shape from every channel), and
+ *  - fan that envelope out to the app callbacks subscribed for the node.
+ *
+ * It deliberately does **not** open/close the MQTT connection — that lifecycle
+ * is owned by `ESPRMNeoBase.init()` / the orchestrator, so disposing one channel
+ * never tears down a connection other channels (or the node) still use.
+ *
+ * @example
+ * ```typescript
+ * const mqttChannel = new MQTTSubscriptionChannel();
+ * await ESPRMNeoBase.subscriptionManager.registerChannel(mqttChannel);
+ * await ESPRMNeoBase.subscriptionManager.subscribeToNode(node, (update) => {
+ *   console.log(`Node ${update.nodeId} updated:`, update.payload);
+ * });
+ * ```
+ */
+class MQTTSubscriptionChannel {
+    channelId = constants.SubscriptionChannelIds.MQTT;
+    /**
+     * App callbacks per node (nodeId → set of subscriber callbacks).
+     */
+    nodeCallbacks = new Map();
+    /**
+     * The single orchestrator listener installed per node (nodeId → listener).
+     * Kept so we can detach exactly that listener on unsubscribe.
+     */
+    orchestratorListeners = new Map();
+    /**
+     * nodeId → orchestrator generation at which we last attached its listener.
+     * If the orchestrator is re-initialized (logout→login), the generation
+     * changes and we re-attach instead of trusting stale cached state.
+     */
+    nodeGeneration = new Map();
+    /**
+     * nodeId → tail of the in-flight operation chain for that node. Subscribe and
+     * unsubscribe for the same node are serialized through this so they never
+     * interleave across an await boundary (see {@link runSerial}).
+     */
+    nodeOps = new Map();
+    isInitialized = false;
+    /**
+     * Initialize the channel. The MQTT engine
+     * ({@link NodeMQTTOrchestrator} over `ESPRMNeoMqtt`) is initialized by
+     * `ESPRMNeoBase.init()` when an `mqttAdapter` is configured, so there is no
+     * connection to set up here.
+     */
+    async initialize() {
+        this.isInitialized = true;
+    }
+    /**
+     * MQTT is the universal transport for RainMaker Neo nodes, so this channel
+     * supports every node.
+     *
+     * @param _node - Unused; MQTT supports all Neo nodes.
+     * @returns Always `true`.
+     */
+    supportsNode(_node) {
+        return true;
+    }
+    /**
+     * Subscribe to parameter updates for a node.
+     *
+     * Constructs the node's shadow name from its group/subgroup context, registers
+     * it with the orchestrator (deduped by shadow), and installs a single
+     * orchestrator listener per node that normalizes shadow messages and fans
+     * them out to all subscriber callbacks.
+     *
+     * @param callback - Invoked with a normalized {@link ESPNodeUpdateData} on each update.
+     * @param node - The node to subscribe to. Must carry `nodeId` (or `id`) and
+     *   `groupId`; `subgroupIds` optional. Group context is used to build the
+     *   shadow name directly — no reverse lookup from persisted state.
+     * @throws Error if the node has no id or the orchestrator subscription fails.
+     */
+    async subscribe(callback, node) {
+        const nodeId = node.nodeId ?? node.id;
+        if (!nodeId) {
+            throw new Error("MQTTSubscriptionChannel.subscribe requires a node with an id");
+        }
+        if (!this.isInitialized) {
+            await this.initialize();
+        }
+        // Serialize per node so this subscribe never interleaves with another
+        // subscribe/detach for the same node across an await. Without this, a late
+        // subscriber could attach to about-to-be-rolled-back (failed first install)
+        // or about-to-be-torn-down (concurrent detach) state and then silently
+        // never receive updates.
+        return this.runSerial(nodeId, () => this.installSubscriber(callback, node));
+    }
+    /**
+     * Installs a single subscriber for a node. Runs exclusively per node via
+     * {@link runSerial}: the first subscriber constructs the shadow name from the
+     * node's group context, registers the node and attaches one shared
+     * orchestrator listener; later subscribers join the node's existing callback
+     * set.
+     *
+     * @param callback - Subscriber to add.
+     * @param node - The node whose shadow is constructed from its group context.
+     */
+    async installSubscriber(callback, node) {
+        const nodeId = (node.nodeId ?? node.id);
+        const shadowName = shadowUtils.constructShadowName(node.groupId ?? "", node.subgroupIds ?? []);
+        // Re-bind shadow from node group context (no-op if unchanged).
+        NodeMQTTOrchestrator.NodeMQTTOrchestrator.registerNode(nodeId, shadowName);
+        // If the orchestrator was re-initialized since we last attached this node
+        // (e.g. logout→login wiped its subscription state), our cached listener is
+        // dead. Drop the stale local state so the block below re-creates the
+        // listener and re-attaches it to the new orchestrator.
+        const generation = NodeMQTTOrchestrator.NodeMQTTOrchestrator.getGeneration();
+        if (this.nodeCallbacks.has(nodeId) &&
+            this.nodeGeneration.get(nodeId) !== generation) {
+            this.nodeCallbacks.delete(nodeId);
+            this.orchestratorListeners.delete(nodeId);
+        }
+        this.nodeGeneration.set(nodeId, generation);
+        // First subscriber for this node installs the shared orchestrator listener.
+        if (!this.nodeCallbacks.has(nodeId)) {
+            const callbacks = new Set();
+            this.nodeCallbacks.set(nodeId, callbacks);
+            const listener = (params) => {
+                const update = transformShadowToNodeUpdate.transformShadowToNodeUpdate(nodeId, params, { shadowName }, this.channelId);
+                callbacks.forEach((cb) => {
+                    try {
+                        cb(update);
+                    }
+                    catch (error) {
+                        logger.error(`Subscriber threw for node ${nodeId}`, error);
+                    }
+                });
+            };
+            this.orchestratorListeners.set(nodeId, listener);
+            try {
+                await NodeMQTTOrchestrator.NodeMQTTOrchestrator.subscribeToNode(nodeId, listener);
+            }
+            catch (error) {
+                // Roll back bookkeeping so a later retry can subscribe cleanly.
+                this.nodeCallbacks.delete(nodeId);
+                this.orchestratorListeners.delete(nodeId);
+                this.nodeGeneration.delete(nodeId);
+                throw error;
+            }
+        }
+        this.nodeCallbacks.get(nodeId).add(callback);
+    }
+    /**
+     * Unsubscribe from a node.
+     *
+     * - No `nodeId`: detach every node.
+     * - `nodeId` only: detach the node and all its subscribers.
+     * - `nodeId` + `callback`: remove just that subscriber; the node stays
+     *   subscribed (and the shared orchestrator listener stays attached) until its
+     *   last subscriber is removed, so sibling subscribers are not affected.
+     *
+     * @param nodeId - Node id to detach; omit to detach all nodes.
+     * @param callback - Optional specific subscriber to remove.
+     */
+    async unsubscribe(nodeId, callback) {
+        if (!nodeId) {
+            const ids = Array.from(this.nodeCallbacks.keys());
+            for (const id of ids) {
+                await this.runSerial(id, () => this.removeSubscriber(id, undefined));
+            }
+            return;
+        }
+        return this.runSerial(nodeId, () => this.removeSubscriber(nodeId, callback));
+    }
+    /**
+     * Removes a subscriber for a node. Runs exclusively per node via
+     * {@link runSerial}. With a `callback`, only that subscriber is removed and the
+     * node stays subscribed while others remain; once the last subscriber is gone
+     * (or when `callback` is omitted) the node is fully detached.
+     *
+     * @param nodeId - Node id.
+     * @param callback - Specific subscriber to remove, or omit to detach the node.
+     */
+    async removeSubscriber(nodeId, callback) {
+        if (callback) {
+            const callbacks = this.nodeCallbacks.get(nodeId);
+            if (!callbacks)
+                return;
+            callbacks.delete(callback);
+            // Other subscribers remain → keep the node (and its orchestrator listener).
+            if (callbacks.size > 0)
+                return;
+            // Last subscriber removed → fall through to fully detach the node.
+        }
+        await this.detachNode(nodeId);
+    }
+    /**
+     * Detach all listeners. The shared MQTT connection is intentionally left
+     * intact — its lifecycle is owned by the orchestrator / `ESPRMNeoBase`.
+     */
+    async dispose() {
+        await this.unsubscribe();
+        this.isInitialized = false;
+    }
+    /**
+     * Removes this channel's orchestrator listener for a node and clears its
+     * bookkeeping. Only this channel's listener is detached — the orchestrator
+     * idle-cleans the underlying shadow topic once no listeners remain, so a
+     * node's own subscription (e.g. from `ESPRMNeoNode`) is never clobbered.
+     *
+     * @param nodeId - Node id to detach.
+     */
+    async detachNode(nodeId) {
+        const listener = this.orchestratorListeners.get(nodeId);
+        const callbacks = this.nodeCallbacks.get(nodeId);
+        // Drop local state synchronously (before the await) so nothing observes
+        // half-torn-down state, and empty the set the listener closes over so an
+        // in-flight message during the orchestrator unsubscribe cannot reach a
+        // removed subscriber.
+        this.orchestratorListeners.delete(nodeId);
+        this.nodeCallbacks.delete(nodeId);
+        this.nodeGeneration.delete(nodeId);
+        callbacks?.clear();
+        if (listener) {
+            try {
+                await NodeMQTTOrchestrator.NodeMQTTOrchestrator.unsubscribeFromNode(nodeId, listener);
+            }
+            catch (error) {
+                logger.error(`Failed to unsubscribe node ${nodeId} from MQTT`, error);
+            }
+        }
+    }
+    /**
+     * Runs `op` exclusively per node: operations for the same nodeId are chained
+     * so they never interleave across an await point, while operations for
+     * different nodes still run concurrently. The caller receives `op`'s own
+     * outcome (success or failure); a failed op does not block later ops.
+     *
+     * @param nodeId - Node whose operations are serialized.
+     * @param op - The operation to run once it reaches the front of the queue.
+     * @returns The result of `op`.
+     */
+    runSerial(nodeId, op) {
+        const prev = this.nodeOps.get(nodeId) ?? Promise.resolve();
+        // Chain after the previous op regardless of whether it resolved or rejected.
+        const result = prev.then(op, op);
+        const tail = result.then(() => undefined, () => undefined);
+        this.nodeOps.set(nodeId, tail);
+        void tail.then(() => {
+            // Drop the queue entry once this was the last queued op for the node.
+            if (this.nodeOps.get(nodeId) === tail) {
+                this.nodeOps.delete(nodeId);
+            }
+        });
+        return result;
+    }
+}
+
+exports.MQTTSubscriptionChannel = MQTTSubscriptionChannel;
+//# sourceMappingURL=MQTTSubscriptionChannel.js.map

package/dist/cjs/services/MQTTSubscriptionChannel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MQTTSubscriptionChannel.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}