@espressif/rainmaker-neo-base-sdk 1.0.0

package/dist/esm/ESPRMNeoBase.js

@@ -0,0 +1,248 @@
+import { ConfigValidator } from './utils/validator/ConfigValidator.js';
+import { Logger } from './utils/logger.js';
+import { ESPRMNeoStorage } from './services/ESPRMNeoStorage/ESPRMNeoStorage.js';
+import { createDefaultTransportOrder, logConfigSummary, extractAdaptersFromConfig, initializeMqttIfConfigured, createAuthInstance, initializeApiStack, createSubscriptionManager, disposePeerSingletons, assertSdkInitialized, assertAdapterProvided, copyTransportOrder } from './utils/baseUtils.js';
+import { ConfigErrorCodes } from './utils/constants.js';
+
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const logger = new Logger("ESPRMNeoBase");
+/**
+ * Configures and manages the ESP RainMaker Neo SDK.
+ *
+ * Holds process-wide configuration, adapters, and auth state. Call
+ * {@link ESPRMNeoBase.configure} once before using other SDK APIs.
+ * Low-level initialization helpers live in `utils/baseUtils`.
+ */
+class ESPRMNeoBase {
+    /** Active SDK configuration, or `null` before {@link configure} / after {@link dispose}. */
+    static #config = null;
+    /** Auth instance created during {@link configure}. */
+    static authInstance = null;
+    /** Subscription manager created during {@link configure}. */
+    static _subscriptionManager = null;
+    static _storageAdapter;
+    static _provisionAdapter;
+    static _localControlAdapter;
+    /**
+     * App-supplied adapter for local (LAN / mDNS) discovery.
+     * Used when an app subscribes to `localDiscovery` via {@link ESPRMNeoUser.subscribe}.
+     * Access via {@link getLocalDiscoveryAdapter}.
+     */
+    static _localDiscoveryAdapter;
+    /**
+     * Global default transport priority order.
+     * Each node copies this at construction; apps may override globally via
+     * {@link setTransportOrder} or per-node via `ESPRMNeoNode.setTransportOrder`.
+     */
+    static globalTransportOrder = createDefaultTransportOrder();
+    /**
+     * Configures the ESP RainMaker Neo SDK with the given options.
+     * Must be called before using any other SDK functionality.
+     *
+     * If the SDK is already configured, previous state is disposed first so
+     * re-configure is safe.
+     *
+     * @param config - Base URL (include API Gateway stage if any), Cognito/IoT
+     *   settings, and optional adapters.
+     * @throws {Error} If the configuration is invalid or initialization fails.
+     */
+    static configure(config) {
+        logger.debug("Starting SDK configuration");
+        ConfigValidator.validateConfig(config);
+        logConfigSummary(config);
+        try {
+            if (ESPRMNeoBase.#config) {
+                ESPRMNeoBase.dispose();
+            }
+            const adapters = extractAdaptersFromConfig(config);
+            ESPRMNeoBase._storageAdapter = adapters.storage;
+            ESPRMNeoBase._provisionAdapter = adapters.provision;
+            ESPRMNeoBase._localControlAdapter = adapters.localControl;
+            ESPRMNeoBase._localDiscoveryAdapter = adapters.localDiscovery;
+            initializeMqttIfConfigured(config);
+            ESPRMNeoBase.authInstance = createAuthInstance(config);
+            ESPRMNeoBase.#config = config;
+            initializeApiStack(config, ESPRMNeoBase._storageAdapter);
+            ESPRMNeoBase._subscriptionManager = createSubscriptionManager(config);
+        }
+        catch (error) {
+            logger.error("SDK initialization failed", error instanceof Error ? error.message : error);
+            throw error;
+        }
+    }
+    /**
+     * Initializes the ESP RainMaker Neo SDK with the given configuration.
+     * Back-compat alias for {@link configure}.
+     *
+     * @param config - Same options as {@link configure}.
+     */
+    static init(config) {
+        ESPRMNeoBase.configure(config);
+    }
+    /**
+     * Disposes SDK state and resets peer singletons so {@link configure} can run again.
+     * Prefer this over `jest.resetModules()` when tearing down in tests.
+     */
+    static dispose() {
+        disposePeerSingletons(ESPRMNeoBase._subscriptionManager);
+        ESPRMNeoBase._subscriptionManager = null;
+        ESPRMNeoBase.#config = null;
+        ESPRMNeoBase.authInstance = null;
+        ESPRMNeoBase._storageAdapter = undefined;
+        ESPRMNeoBase._provisionAdapter = undefined;
+        ESPRMNeoBase._localControlAdapter = undefined;
+        ESPRMNeoBase._localDiscoveryAdapter = undefined;
+        ESPRMNeoBase.globalTransportOrder = createDefaultTransportOrder();
+    }
+    /**
+     * Returns a readonly copy of the current SDK configuration.
+     *
+     * @returns Frozen shallow copy of the active config.
+     * @throws {Error} If the SDK has not been initialized.
+     */
+    static getConfig() {
+        assertSdkInitialized(!!ESPRMNeoBase.#config);
+        return Object.freeze({ ...ESPRMNeoBase.#config });
+    }
+    /**
+     * Returns the authentication instance for the SDK.
+     *
+     * @returns The {@link ESPRMNeoAuth} instance used for auth operations.
+     * @throws {Error} If the SDK has not been initialized.
+     */
+    static getAuthInstance() {
+        assertSdkInitialized(!!ESPRMNeoBase.authInstance);
+        return ESPRMNeoBase.authInstance;
+    }
+    /**
+     * Returns the subscription manager instance.
+     *
+     * @returns The {@link ESPRMNeoSubscriptionManager} for managing subscriptions.
+     * @throws {Error} If the SDK has not been initialized.
+     */
+    static get subscriptionManager() {
+        assertSdkInitialized(!!ESPRMNeoBase._subscriptionManager);
+        return ESPRMNeoBase._subscriptionManager;
+    }
+    /**
+     * Sets the storage adapter for the SDK and re-initializes persistent storage.
+     *
+     * @param adapter - Adapter implementing {@link ESPStorageAdapter}.
+     * @throws {Error} If the SDK is not initialized or the adapter is invalid.
+     */
+    static setStorageAdapter(adapter) {
+        logger.debug("Setting storage adapter via method");
+        assertSdkInitialized(!!ESPRMNeoBase.#config);
+        assertAdapterProvided(adapter, ConfigErrorCodes.INVALID_STORAGE_ADAPTER);
+        ESPRMNeoBase._storageAdapter = adapter;
+        ESPRMNeoStorage.initialize(adapter);
+    }
+    /**
+     * Gets the current storage adapter, if any.
+     *
+     * @returns The configured {@link ESPStorageAdapter}, or `undefined`.
+     */
+    static get storageAdapter() {
+        logger.debug("Getting storage adapter");
+        return ESPRMNeoBase._storageAdapter;
+    }
+    /**
+     * Sets the storage adapter for the SDK.
+     *
+     * Prefer {@link setStorageAdapter} for clearer call sites.
+     *
+     * @param adapter - Adapter implementing {@link ESPStorageAdapter}.
+     */
+    static set storageAdapter(adapter) {
+        logger.debug("Setting storage adapter via property setter");
+        ESPRMNeoBase._storageAdapter = adapter;
+        ESPRMNeoStorage.initialize(adapter);
+    }
+    /**
+     * Sets the provisioning adapter for the SDK.
+     *
+     * @param adapter - Adapter implementing {@link ESPProvisionAdapterInterface}.
+     * @throws {Error} If the SDK is not initialized or the adapter is invalid.
+     */
+    static setProvisioningAdapter(adapter) {
+        assertSdkInitialized(!!ESPRMNeoBase.#config);
+        assertAdapterProvided(adapter, ConfigErrorCodes.INVALID_PROVISION_ADAPTER);
+        ESPRMNeoBase._provisionAdapter = adapter;
+    }
+    /**
+     * Gets the provisioning adapter.
+     *
+     * @returns The provisioning adapter, or `undefined` if not configured.
+     */
+    static getProvisionAdapter() {
+        return ESPRMNeoBase._provisionAdapter;
+    }
+    /**
+     * Sets the local control adapter used to talk to nodes over the LAN via
+     * the `esp_local_ctrl` protocol.
+     *
+     * @param adapter - Adapter implementing {@link ESPLocalControlAdapterInterface}.
+     * @throws {Error} If the SDK is not initialized or the adapter is invalid.
+     */
+    static setLocalControlAdapter(adapter) {
+        assertSdkInitialized(!!ESPRMNeoBase.#config);
+        assertAdapterProvided(adapter, ConfigErrorCodes.INVALID_LOCAL_CONTROL_ADAPTER);
+        ESPRMNeoBase._localControlAdapter = adapter;
+    }
+    /**
+     * Gets the local control adapter.
+     *
+     * @returns The local control adapter, or `undefined` if not configured.
+     */
+    static getLocalControlAdapter() {
+        return ESPRMNeoBase._localControlAdapter;
+    }
+    /**
+     * Sets the local discovery adapter used to browse for nodes on the LAN
+     * (mDNS). Required before subscribing to `localDiscovery` via
+     * {@link ESPRMNeoUser.subscribe}.
+     *
+     * @param adapter - Adapter implementing {@link ESPLocalDiscoveryAdapterInterface}.
+     * @throws {Error} If the SDK is not initialized or the adapter is invalid.
+     */
+    static setLocalDiscoveryAdapter(adapter) {
+        assertSdkInitialized(!!ESPRMNeoBase.#config);
+        assertAdapterProvided(adapter, ConfigErrorCodes.INVALID_LOCAL_DISCOVERY_ADAPTER);
+        ESPRMNeoBase._localDiscoveryAdapter = adapter;
+    }
+    /**
+     * Gets the local discovery adapter.
+     *
+     * @returns The local discovery adapter, or `undefined` if not configured.
+     */
+    static getLocalDiscoveryAdapter() {
+        return ESPRMNeoBase._localDiscoveryAdapter;
+    }
+    /**
+     * Sets the global default transport priority order.
+     * New nodes adopt this order at construction; existing nodes keep their
+     * current order unless updated per-node via `ESPRMNeoNode.setTransportOrder`.
+     *
+     * @param order - Non-empty ordered list of transport modes (built-in
+     *   {@link ESPTransportMode} values or custom string keys).
+     * @throws {ESPConfigError} If the order is empty or not an array.
+     */
+    static setTransportOrder(order) {
+        ESPRMNeoBase.globalTransportOrder = copyTransportOrder(order);
+    }
+    /**
+     * Returns a copy of the global default transport priority order.
+     *
+     * @returns Shallow copy of the current transport order.
+     */
+    static getTransportOrder() {
+        return [...ESPRMNeoBase.globalTransportOrder];
+    }
+}
+
+export { ESPRMNeoBase };
+//# sourceMappingURL=ESPRMNeoBase.js.map

package/dist/esm/ESPRMNeoBase.js.map

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

package/dist/esm/ESPRMNeoDevice.js

@@ -0,0 +1,49 @@
+import { ESPRMNeoDeviceParam } from './ESPRMNeoDeviceParam.js';
+
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Logical device inside a node (e.g. switch, light, thermostat).
+ * Holds a WeakRef to the parent node for delegating getParams/setParams.
+ */
+class ESPRMNeoDevice {
+    name;
+    displayName;
+    type;
+    attributes;
+    params;
+    primaryParam;
+    _nodeRef;
+    constructor(data, nodeRef) {
+        this.name = data.name;
+        this.displayName = data.displayName ?? data.name;
+        this.type = data.type ?? "esp.device.generic";
+        this.attributes = data.attributes;
+        this._nodeRef = nodeRef;
+        const paramInstances = (data.params ?? []).map((p) => new ESPRMNeoDeviceParam({
+            id: p.id,
+            type: p.type ?? p.id,
+            properties: p.properties ?? [],
+            dataType: p.dataType,
+            deviceName: data.name,
+            uiType: p.uiType,
+            bounds: p.bounds,
+            validStrings: p.validStrings,
+        }, nodeRef));
+        this.params = paramInstances;
+        const primaryName = data.primary ?? data.primary;
+        this.primaryParam = primaryName
+            ? paramInstances.find((p) => p.id === primaryName)
+            : paramInstances[0];
+    }
+    /** Parent node, if the weak reference is still alive. */
+    getNode() {
+        return this._nodeRef.deref();
+    }
+}
+
+export { ESPRMNeoDevice };
+//# sourceMappingURL=ESPRMNeoDevice.js.map

package/dist/esm/ESPRMNeoDevice.js.map

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

package/dist/esm/ESPRMNeoDeviceParam.js

@@ -0,0 +1,52 @@
+import { delegatedTransportHandler } from './services/ESPRMNeoHelpers/DelegatedTransportHandler.js';
+import { APICallValidationErrorCodes } from './utils/constants.js';
+import { ESPAPICallValidationError } from './utils/error/ESPAPICallValidationError.js';
+
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Device parameter – one controllable parameter of a device (e.g. Power, Brightness).
+ * Holds a WeakRef to the parent node so writes can be dispatched via the best
+ * available transport (see {@link delegatedTransportHandler}).
+ */
+class ESPRMNeoDeviceParam {
+    id;
+    type;
+    properties;
+    dataType;
+    deviceName;
+    uiType;
+    bounds;
+    validStrings;
+    value;
+    _nodeRef;
+    constructor(data, nodeRef) {
+        this.id = data.id;
+        this.type = data.type ?? data.id;
+        this.properties = data.properties ?? [];
+        this.dataType = data.dataType;
+        this.deviceName = data.deviceName;
+        this.uiType = data.uiType;
+        this.bounds = data.bounds;
+        this.validStrings = data.validStrings;
+        this.value = data.value;
+        this._nodeRef = nodeRef;
+    }
+    setValue(value) {
+        const node = this._nodeRef.deref();
+        if (!node) {
+            throw new ESPAPICallValidationError(APICallValidationErrorCodes.MISSING_NODE_REF);
+        }
+        const payload = {
+            node_id: node.nodeId,
+            payload: { [this.deviceName]: { [this.id]: value } },
+        };
+        return (delegatedTransportHandler).call(node, (manager) => manager.setParam(payload, node));
+    }
+}
+
+export { ESPRMNeoDeviceParam };
+//# sourceMappingURL=ESPRMNeoDeviceParam.js.map

package/dist/esm/ESPRMNeoDeviceParam.js.map

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

package/dist/esm/ESPRMNeoGroup.js

@@ -0,0 +1,47 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/** True when this instance is a nested group (child of another group). */
+function isChildGroup(g) {
+    return g.parentId != null && g.parentId !== "";
+}
+/**
+ * Represents a group in the ESP Rainmaker Neo SDK.
+ * Nested groups are also `ESPRMNeoGroup` instances with `parentId` set.
+ *
+ * Instance methods (attached via prototype in `methods/ESPRMNeoGroup/`):
+ *   - Membership: `addNode`, `removeNode`, `getNode`, `getNodes`
+ *   - Lifecycle:  `updateName`, `delete`, `leave`, `createSubGroup`
+ *   - Sharing:    `share`, `getSharingInfo`, `removeMember`
+ *   - Params:     `setParams`
+ *   - Schedules:  `getSchedules`, `createSchedule`, `deleteAllSchedules`
+ *   - Automation: `createAutomation`, `getAutomation`, `getAutomations`
+ */
+class ESPRMNeoGroup {
+    groupId;
+    groupName;
+    accessType;
+    /** Present only when this instance is a nested group (see {@link isChildGroup}). */
+    parentId;
+    nodeIds;
+    subgroups;
+    nodeDetails;
+    constructor(data) {
+        this.groupId = data.groupId;
+        this.groupName = data.groupName;
+        this.accessType = data.accessType;
+        this.parentId = data.parentId;
+        this.nodeIds = data.nodeIds ?? [];
+        this.nodeDetails = data.nodeDetails ?? {};
+        this.subgroups =
+            data.subgroups?.map((sg) => new ESPRMNeoGroup({
+                ...sg,
+                parentId: sg.parentId ?? this.groupId,
+            })) ?? [];
+    }
+}
+
+export { ESPRMNeoGroup, isChildGroup };
+//# sourceMappingURL=ESPRMNeoGroup.js.map

package/dist/esm/ESPRMNeoGroup.js.map

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

package/dist/esm/ESPRMNeoNode.js

@@ -0,0 +1,281 @@
+import { emitNodeUpdate } from './services/NodeUpdatesBus.js';
+import { Logger } from './utils/logger.js';
+import { NodeMQTTOrchestrator } from './services/NodeMQTTOrchestrator.js';
+import { ESPRMNeoService } from './ESPRMNeoService.js';
+import { ESPRMNeoDevice } from './ESPRMNeoDevice.js';
+import { constructShadowName, constructDeviceParamsTopic } from './utils/shadowUtils.js';
+import { transformNodeInfo, transformNodeDevice, transformNodeService, extract } from './utils/nodeTransform.js';
+import { ESPRMNeoStorage } from './services/ESPRMNeoStorage/ESPRMNeoStorage.js';
+import { ConfigErrorCodes, StorageKeys } from './utils/constants.js';
+import { hasNcfgVersionChanged, persistNcfgVersionMarker } from './utils/nodeNcfgVersionHandler.js';
+import { applyParamValues, mergeParamMaps } from './utils/paramValues.js';
+import { ESPRMNeoBase } from './ESPRMNeoBase.js';
+import { ESPTransportMode } from './types/transport.js';
+import { asStringArray } from './utils/common.js';
+import { ESPConfigError } from './utils/error/ESPConfigError.js';
+
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const logger = new Logger("ESPRMNeoNode");
+/**
+ * Represents a node in the ESP Rainmaker Neo SDK.
+ * Provides access to node configuration and metadata.
+ *
+ * Live updates arrive via the subscription manager
+ * (`subscribeToNode` → {@link handleNodeUpdate}) and are re-broadcast on the
+ * process-wide node-updates bus for `user.subscribe(nodeUpdates)`.
+ */
+class ESPRMNeoNode {
+    nodeId;
+    config;
+    /** API/cache snapshot (snake_case devices/services) used for local persistence. */
+    wireConfig;
+    groupId;
+    /** All subgroup IDs this node belongs to under {@link groupId} (shadow segment order from {@link constructShadowName}). Empty when the node lives only at the root group. */
+    subgroupIds = [];
+    devices = [];
+    services = [];
+    connectivityStatus = {
+        isConnected: false,
+        lastConnectionTimestamp: 0,
+    };
+    /**
+     * Transports currently usable for this node, keyed by mode.
+     * - `mqtt` (cloud) is added when the node reports online and removed when
+     *   it goes offline (via shadow updates or seeded `connectivity_status`).
+     * - `local` is added/removed at runtime by a `localDiscovery` subscriber as the
+     *   node appears/disappears on the LAN (via {@link addTransport}/{@link removeTransport}).
+     * Apps may also add custom string-keyed entries (pair with
+     * {@link customTransportManagers}).
+     */
+    availableTransports = {};
+    /**
+     * Transport priority order for this node. Initialized from the global default
+     * ({@link ESPRMNeoBase.getTransportOrder}); override per-node via
+     * {@link setTransportOrder}.
+     */
+    transportOrder = [];
+    /**
+     * Optional per-node custom transport implementations keyed by mode. When a
+     * mode in {@link transportOrder} has an entry here, the transport handler uses
+     * it in preference to the built-in local/MQTT backends. Enables BLE, WebSocket
+     * or proprietary transports without modifying the SDK.
+     */
+    customTransportManagers;
+    /**
+     * Optional per-node subscription channel order, overriding the global order
+     * on {@link ESPRMNeoBase.subscriptionManager}. Set and read via the
+     * `setSubscriptionChannelOrder` / `getSubscriptionChannelOrder` methods
+     * added by module augmentation in
+     * `src/methods/ESPRMNeoNode/SubscriptionConfig.ts`.
+     */
+    subscriptionConfig;
+    constructor(config, groupId, subgroupIdOrIds) {
+        this.groupId = groupId;
+        this.subgroupIds = asStringArray(subgroupIdOrIds);
+        this.transportOrder = ESPRMNeoBase.getTransportOrder();
+        this.availableTransports = {};
+        this.applyNodeConfig(config);
+        if (config.connectivity_status) {
+            this.connectivityStatus = config.connectivity_status;
+        }
+        if (this.connectivityStatus.isConnected) {
+            this.addTransport(ESPTransportMode.mqtt, {
+                type: ESPTransportMode.mqtt,
+                metadata: {},
+            });
+        }
+        this.subscribeToMqttUpdates();
+    }
+    /**
+     * Adds (or replaces) an available transport for this node, keyed by mode.
+     * Works for built-in modes ({@link ESPTransportMode}) and custom string modes.
+     * For a custom transport, also register its implementation via
+     * {@link addCustomTransportManager}.
+     *
+     * @param mode - Transport mode key (e.g. `local`, `mqtt`, or a custom string).
+     * @param config - The transport config (`{ type, metadata }`).
+     */
+    addTransport(mode, config) {
+        if (!mode || !config)
+            return;
+        this.availableTransports[mode] = config;
+    }
+    /**
+     * Removes an available transport for this node by mode.
+     *
+     * @param mode - Transport mode key to remove.
+     */
+    removeTransport(mode) {
+        delete this.availableTransports[mode];
+    }
+    /**
+     * Registers (or replaces) a custom transport manager for a mode. The transport
+     * handler prefers it over the built-in backend for that mode. Pair with
+     * {@link addTransport} so the mode also appears in {@link availableTransports}
+     * and participates in {@link transportOrder}.
+     *
+     * @param mode - Transport mode key the manager handles.
+     * @param manager - Implementation of {@link ESPTransportInterface}.
+     */
+    addCustomTransportManager(mode, manager) {
+        if (!mode || !manager)
+            return;
+        if (!this.customTransportManagers) {
+            this.customTransportManagers = {};
+        }
+        this.customTransportManagers[mode] = manager;
+    }
+    /**
+     * Removes the custom transport manager registered for a mode (if any).
+     *
+     * @param mode - Transport mode key to clear.
+     */
+    removeCustomTransportManager(mode) {
+        if (this.customTransportManagers) {
+            delete this.customTransportManagers[mode];
+        }
+    }
+    /**
+     * Overrides the transport priority order for this node only.
+     *
+     * @param order - Non-empty ordered list of transport modes.
+     * @throws {ESPConfigError} If the order is empty or not an array.
+     */
+    setTransportOrder(order) {
+        if (!Array.isArray(order) || order.length === 0) {
+            throw new ESPConfigError(ConfigErrorCodes.INVALID_TRANSPORT_ORDER);
+        }
+        this.transportOrder = [...order];
+    }
+    /**
+     * Replaces config and rebuilds devices/services (used after cloud sync).
+     *
+     * Sets {@link config} so `config.devices` / `config.services` are the same
+     * live {@link ESPRMNeoDevice} / {@link ESPRMNeoService} instances as
+     * {@link devices} / {@link services}.
+     */
+    applyNodeConfig(config) {
+        this.nodeId = config.node_id ?? this.nodeId ?? "";
+        const info = transformNodeInfo(config.info);
+        const nodeRef = new WeakRef(this);
+        const deviceRecords = Array.isArray(config.devices) ? config.devices : [];
+        const serviceRecords = Array.isArray(config.services) ? config.services : [];
+        this.devices = deviceRecords.map((d) => new ESPRMNeoDevice(transformNodeDevice(d), nodeRef));
+        this.services = serviceRecords.map((s) => new ESPRMNeoService(transformNodeService(s), nodeRef));
+        // Keep wire records for cache writes (never persist live class instances).
+        this.wireConfig = {
+            ...config,
+            info,
+            devices: deviceRecords,
+            services: serviceRecords,
+        };
+        this.config = {
+            ...config,
+            info,
+            devices: this.devices,
+            services: this.services,
+        };
+        applyParamValues(this, config.params ?? {});
+    }
+    getShadowName() {
+        return constructShadowName(this.groupId, this.subgroupIds);
+    }
+    /**
+     * RainMaker params channel: rainmaker/nodes/{nodeId}/user/{shadowName}/params
+     */
+    getParamsTopic() {
+        return constructDeviceParamsTopic(this.nodeId, this.groupId, this.subgroupIds);
+    }
+    /**
+     * Registers this node with the MQTT orchestrator and subscribes via the
+     * subscription manager so the highest-priority available channel serves it
+     * (MQTT today; Matter/BLE when a satellite SDK registers one). Fire-and-forget
+     * from the constructor — failures are logged, not thrown.
+     */
+    async subscribeToMqttUpdates() {
+        const shadowName = this.getShadowName();
+        try {
+            // The MQTT channel reuses this registration rather than re-resolving
+            // the shadow.
+            NodeMQTTOrchestrator.registerNode(this.nodeId, shadowName);
+            await ESPRMNeoBase.subscriptionManager.subscribeToNode(this, (update) => this.handleNodeUpdate(update));
+            // Warm read: the shadow GET response also arrives on the live
+            // subscription, delivering the node's current params right after subscribe.
+            await NodeMQTTOrchestrator.getParams(this.nodeId);
+        }
+        catch (error) {
+            logger.error("Failed to subscribe to MQTT updates", error);
+        }
+    }
+    /**
+     * Handles a normalized update from the subscription manager: applies it to the
+     * node's internal state (via {@link processNodeUpdate}) and re-broadcasts it on
+     * the process-wide node-updates bus for `user.subscribe(nodeUpdates)`.
+     *
+     * For MQTT the full shadow is carried in `metadata.shadow`, so internal
+     * bookkeeping (params + connectivity + config version) is unchanged. For a
+     * channel that only provides a param map, a minimal shadow is reconstructed.
+     *
+     * @param update - The normalized node update.
+     */
+    handleNodeUpdate(update) {
+        const shadow = update.metadata?.shadow ?? {
+            state: { reported: { params: update.payload } },
+        };
+        this.processNodeUpdate(shadow);
+        emitNodeUpdate(update);
+    }
+    /**
+     * Applies a shadow update: devices/services params, connectivity, cache.
+     * If `ncfg_ver` changed, {@link ESPRMNeoNode#sync} → {@link applyNodeConfig}.
+     */
+    processNodeUpdate(shadow) {
+        const { params, connectivityStatus } = extract(shadow);
+        if (Object.keys(params).length > 0) {
+            applyParamValues(this, params);
+            this.config.params = mergeParamMaps(this.config.params, params);
+            this.wireConfig.params = this.config.params;
+        }
+        this.applyConnectivityStatus(shadow, connectivityStatus);
+        ESPRMNeoStorage.setItem(StorageKeys.NODE_CONFIG_PREFIX + this.nodeId, JSON.stringify({ ...this.wireConfig, node_id: this.nodeId }));
+        this.refreshConfigIfNcfgChanged(shadow);
+    }
+    /**
+     * Updates {@link connectivityStatus} and MQTT transport availability when the
+     * shadow reports `online`. Partial updates without `online` are ignored so
+     * an existing status is not cleared.
+     */
+    applyConnectivityStatus(shadow, connectivityStatus) {
+        if (shadow.state?.reported?.online === undefined)
+            return;
+        this.connectivityStatus = connectivityStatus;
+        if (connectivityStatus.isConnected) {
+            this.addTransport(ESPTransportMode.mqtt, {
+                type: ESPTransportMode.mqtt,
+                metadata: {},
+            });
+        }
+        else {
+            this.removeTransport(ESPTransportMode.mqtt);
+        }
+    }
+    /** When cloud `ncfg_ver` changes, refetch config and persist the new marker. */
+    async refreshConfigIfNcfgChanged(shadow) {
+        try {
+            if (!(await hasNcfgVersionChanged(this.nodeId, shadow)))
+                return;
+            await this.sync();
+            await persistNcfgVersionMarker(this.nodeId, shadow);
+        }
+        catch (error) {
+            logger.error("Failed to refresh config on ncfg_ver change", error);
+        }
+    }
+}
+
+export { ESPRMNeoNode };
+//# sourceMappingURL=ESPRMNeoNode.js.map