@espressif/rainmaker-neo-base-sdk 1.0.0 → 1.1.0

package/LICENSE

@@ -187,7 +187,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2026 Espressif Systems \(Shanghai\) CO LTD
+   Copyright 2026 Espressif Systems (Shanghai) CO LTD
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/README.md

@@ -1,3 +1,40 @@
+# ESP RainMaker Neo - IoT Cloud
+
+**Tools**
+
+[![Try With Launchpad](https://img.shields.io/badge/Try_With-ESP_Launchpad-0066CC?logo=espressif)](https://espressif.github.io/esp-launchpad/?flashConfigURL=https://espressif.github.io/esp-rainmaker-neo-firmware/launchpad.toml)
+ 
+[![Download iOS App](https://img.shields.io/badge/Download-iOS_App-0066CC?logo=appstore)](https://apps.apple.com/us/app/esp-rainmaker-home/id1563728960)
+ 
+[![Download Android App](https://img.shields.io/badge/Download-Android_App-0066CC?logo=googleplay)](https://play.google.com/store/apps/details?id=com.espressif.novahome)
+
+**Documentation**
+
+[![ESP RainMaker Neo Website](https://img.shields.io/badge/ESP_RainMaker_Neo-Website-6F42C1?logo=espressif)](https://neo.rainmaker.espressif.com)
+ 
+[![Documentation](https://img.shields.io/badge/ESP_RainMaker_Neo-Docs-6F42C1?logo=readthedocs)](https://docs.neo.rainmaker.espressif.com/)
+
+---
+
+## Introduction
+
+ESP RainMaker Neo is a serverless, open-source IoT cloud for ESP devices that you deploy into your own AWS account. It scales with your fleet and is pay-as-you-go. Devices connect over MQTT through AWS IoT. Phone apps, the admin dashboard and voice assistants reach the same backend over REST APIs and MQTT.
+
+<p align="center">
+  <img src="assets/images/architecture.svg" alt="ESP RainMaker Neo Architecture" width="800">
+</p>
+
+### Repositories
+
+| Repository                                                                            | Holds                                            |
+| ------------------------------------------------------------------------------------- | ------------------------------------------------ |
+| [esp-rainmaker-neo](https://github.com/espressif/esp-rainmaker-neo)                   | Cloud backend, admin dashboard |
+| [esp-rainmaker-neo-firmware](https://github.com/espressif/esp-rainmaker-neo-firmware) | Device firmware SDK                              |
+| [esp-rainmaker-home](https://github.com/espressif/esp-rainmaker-home)<br>[esp-rainmaker-neo-app-sdk-ts](https://github.com/espressif/esp-rainmaker-neo-app-sdk-ts) | ESP RainMaker Home phone app (iOS and Android)<br>(this repository) ESP RainMaker Neo App SDK (TypeScript) |
+
+
+---
+
 # ESP RainMaker Neo TypeScript SDK
 
 **RainMaker Neo** (short: **RMNeo**) is Espressif’s AIoT stack. `@espressif/rainmaker-neo-base-sdk` is the TypeScript SDK that powers JavaScript-based apps integrating with RainMaker Neo — authentication, groups/nodes, device provisioning, real-time MQTT control, and group sharing.
@@ -63,10 +100,7 @@ import { ESPRMNeoBase } from "@espressif/rainmaker-neo-base-sdk";
 ESPRMNeoBase.init({
   baseUrl: "https://your-api-gateway.amazonaws.com/prod",
   userApiBase: "https://your-user-api-gateway.amazonaws.com/prod",
-  identityId: "your-identity-pool-id",
   awsRegion: "us-east-1",
-  userPoolId: "your-user-pool-id",
-  clientId: "your-cognito-client-id",
   iotEndpoint: "xxxxxxxx-ats.iot.us-east-1.amazonaws.com",
   // Optional adapters (provided by your app):
   // mqttAdapter, customStorageAdapter, provisionAdapter, ...
@@ -184,7 +218,9 @@ await device.disconnect();
 
 ## API Documentation
 
-Generate local docs from JSDoc:
+Browse the hosted API reference at [https://espressif.github.io/esp-rainmaker-neo-app-sdk-ts/](https://espressif.github.io/esp-rainmaker-neo-app-sdk-ts/).
+
+To generate local docs from JSDoc:
 
 ```bash
 npm run genDocs

package/dist/cjs/ESPDevice.js

@@ -24,6 +24,12 @@ class ESPDevice {
     name;
     transport;
     security;
+    /**
+     * What a completed association produced, kept so `retryNetworkCredentials`
+     * can resume the flow instead of repeating it. Set once verification
+     * succeeds; `undefined` until then.
+     */
+    provisionResumeState;
     constructor(deviceConfig) {
         this.name = deviceConfig.name;
         this.transport = deviceConfig.transport;

package/dist/cjs/ESPDevice.js.map

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

package/dist/cjs/ESPRMNeoNode.js

@@ -40,14 +40,19 @@ class ESPRMNeoNode {
     subgroupIds = [];
     devices = [];
     services = [];
+    /**
+     * Last-known connectivity. Seeded from cached `connectivity_status` when
+     * present (cloud config does not provide it); otherwise starts offline until
+     * an MQTT shadow `online` update arrives.
+     */
     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`).
+     * - `mqtt` (cloud) is added when the node is connected and removed when it
+     *   goes offline (from cached `connectivity_status` or shadow updates).
      * - `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
@@ -80,16 +85,11 @@ class ESPRMNeoNode {
         this.subgroupIds = common.asStringArray(subgroupIdOrIds);
         this.transportOrder = ESPRMNeoBase.ESPRMNeoBase.getTransportOrder();
         this.availableTransports = {};
-        this.applyNodeConfig(config);
         if (config.connectivity_status) {
             this.connectivityStatus = config.connectivity_status;
         }
-        if (this.connectivityStatus.isConnected) {
-            this.addTransport(transport.ESPTransportMode.mqtt, {
-                type: transport.ESPTransportMode.mqtt,
-                metadata: {},
-            });
-        }
+        this.applyNodeConfig(config);
+        this.syncMqttTransportAvailability();
         this.subscribeToMqttUpdates();
     }
     /**
@@ -169,11 +169,14 @@ class ESPRMNeoNode {
         this.devices = deviceRecords.map((d) => new ESPRMNeoDevice.ESPRMNeoDevice(nodeTransform.transformNodeDevice(d), nodeRef));
         this.services = serviceRecords.map((s) => new ESPRMNeoService.ESPRMNeoService(nodeTransform.transformNodeService(s), nodeRef));
         // Keep wire records for cache writes (never persist live class instances).
+        // Preserve last-known connectivity when the incoming config omits it
+        // (cloud node config does not include connectivity_status).
         this.wireConfig = {
             ...config,
             info,
             devices: deviceRecords,
             services: serviceRecords,
+            connectivity_status: config.connectivity_status ?? this.connectivityStatus,
         };
         this.config = {
             ...config,
@@ -243,19 +246,27 @@ class ESPRMNeoNode {
             this.wireConfig.params = this.config.params;
         }
         this.applyConnectivityStatus(shadow, connectivityStatus);
-        ESPRMNeoStorage.ESPRMNeoStorage.setItem(constants.StorageKeys.NODE_CONFIG_PREFIX + this.nodeId, JSON.stringify({ ...this.wireConfig, node_id: this.nodeId }));
+        this.persistWireConfig();
         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.
+     * Updates {@link connectivityStatus} when the shadow reports `online`, then
+     * syncs MQTT transport availability. 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.wireConfig.connectivity_status = connectivityStatus;
+        this.syncMqttTransportAvailability();
+    }
+    /**
+     * Registers the MQTT transport only while {@link connectivityStatus} reports
+     * the node as connected; removes it when offline.
+     */
+    syncMqttTransportAvailability() {
+        if (this.connectivityStatus.isConnected) {
             this.addTransport(transport.ESPTransportMode.mqtt, {
                 type: transport.ESPTransportMode.mqtt,
                 metadata: {},
@@ -265,6 +276,14 @@ class ESPRMNeoNode {
             this.removeTransport(transport.ESPTransportMode.mqtt);
         }
     }
+    /** Persists {@link wireConfig} (including last-known connectivity) to storage. */
+    persistWireConfig() {
+        ESPRMNeoStorage.ESPRMNeoStorage.setItem(constants.StorageKeys.NODE_CONFIG_PREFIX + this.nodeId, JSON.stringify({
+            ...this.wireConfig,
+            node_id: this.nodeId,
+            connectivity_status: this.connectivityStatus,
+        }));
+    }
     /** When cloud `ncfg_ver` changes, refetch config and persist the new marker. */
     async refreshConfigIfNcfgChanged(shadow) {
         try {

package/dist/cjs/ESPRMNeoNode.js.map

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

package/dist/cjs/index.js

@@ -104,6 +104,8 @@ require('./methods/ESPDevice/SetProofOfPossession.js');
 require('./methods/ESPDevice/SendData.js');
 require('./methods/ESPDevice/InitializeSession.js');
 require('./methods/ESPDevice/SetNetworkCredentials.js');
+require('./methods/ESPDevice/ResetWifiStatus.js');
+require('./methods/ESPDevice/RetryNetworkCredentials.js');
 require('./methods/ESPDevice/InitiateUserNodeMapping.js');
 require('./methods/ESPDevice/VerifyUserNodeMapping.js');
 require('./methods/ESPDevice/StartAssistedClaiming.js');
@@ -224,6 +226,7 @@ exports.APIEndpoints = constants.APIEndpoints;
 exports.APIOperations = constants.APIOperations;
 exports.APIPathV1 = constants.APIPathV1;
 exports.AWSCredentialsErrorMessages = constants.AWSCredentialsErrorMessages;
+exports.AssumeRoleErrorMessages = constants.AssumeRoleErrorMessages;
 exports.AuthErrorCodes = constants.AuthErrorCodes;
 exports.AuthSuccessMessages = constants.AuthSuccessMessages;
 exports.AutomationStatusValues = constants.AutomationStatusValues;

package/dist/cjs/index.js.map

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

package/dist/cjs/methods/ESPDevice/Provision.js

@@ -67,6 +67,13 @@ async function runChallengeResponseFlow(device, ssid, passphrase, groupId, onPro
         challenge_response: signedChallenge,
         node_id: nodeId,
     });
+    // Association is verified and cannot be repeated; remember what step 6 needs
+    // so `retryNetworkCredentials` can resume from the Wi-Fi step.
+    device.provisionResumeState = {
+        nodeId: nodeId,
+        groupId,
+        options: options,
+    };
     // 5. SET NETWORK CREDENTIALS
     reportProgress(onProgress, provision.ESPProvResponseStatus.onProgress, constants.ESPProvProgressMessages.SETTING_NETWORK_CREDENTIALS);
     await device.setNetworkCredentials(ssid, passphrase);

package/dist/cjs/methods/ESPDevice/Provision.js.map

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

package/dist/cjs/methods/ESPDevice/ResetWifiStatus.js

@@ -0,0 +1,26 @@
+'use strict';
+
+var ESPDevice = require('../../ESPDevice.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("ResetWifiStatus");
+ESPDevice.ESPDevice.prototype.resetWifiStatus = async function () {
+    if (!this.ESPProvisionAdapter.resetWifiStatus) {
+        logger.warn(`Adapter has no resetWifiStatus; treating as not acknowledged for "${this.name}"`);
+        return false;
+    }
+    try {
+        const acknowledged = await this.ESPProvisionAdapter.resetWifiStatus(this.name);
+        return acknowledged;
+    }
+    catch (error) {
+        logger.error(`<- device "${this.name}": reset failed`, error);
+        throw error;
+    }
+};
+//# sourceMappingURL=ResetWifiStatus.js.map

package/dist/cjs/methods/ESPDevice/ResetWifiStatus.js.map

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

package/dist/cjs/methods/ESPDevice/RetryNetworkCredentials.js

@@ -0,0 +1,46 @@
+'use strict';
+
+var ESPDevice = require('../../ESPDevice.js');
+var provision = require('../../types/provision.js');
+var constants = require('../../utils/constants.js');
+var ESPProvError = require('../../utils/error/ESPProvError.js');
+var waitForNodeOnline = require('../../utils/waitForNodeOnline.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("RetryNetworkCredentials");
+ESPDevice.ESPDevice.prototype.retryNetworkCredentials = async function (ssid, passphrase, onProgress) {
+    const resumeState = this.provisionResumeState;
+    if (!resumeState) {
+        logger.error(`Retry refused for "${this.name}": no association recorded, nothing to resume`);
+        throw new ESPProvError.ESPProvError("FAILED_PROV");
+    }
+    onProgress({
+        status: provision.ESPProvResponseStatus.onProgress,
+        description: constants.ESPProvProgressMessages.SETTING_NETWORK_CREDENTIALS,
+    });
+    await this.setNetworkCredentials(ssid, passphrase);
+    const options = resumeState.options;
+    if (options?.waitForOnline && options.user) {
+        onProgress({
+            status: provision.ESPProvResponseStatus.onProgress,
+            description: constants.ESPProvProgressMessages.WAITING_FOR_ONLINE,
+        });
+        await waitForNodeOnline.waitForNodeOnline({
+            nodeId: resumeState.nodeId,
+            groupId: resumeState.groupId,
+            user: options.user,
+            timeoutMs: options.onlineTimeoutMs ?? waitForNodeOnline.DEFAULT_NODE_ONLINE_TIMEOUT_MS,
+        });
+    }
+    onProgress({
+        status: provision.ESPProvResponseStatus.succeed,
+        description: resumeState.nodeId ?? constants.ESPProvProgressMessages.DEVICE_PROVISIONED,
+    });
+    return resumeState.nodeId;
+};
+//# sourceMappingURL=RetryNetworkCredentials.js.map

package/dist/cjs/methods/ESPDevice/RetryNetworkCredentials.js.map

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

package/dist/cjs/methods/ESPRMNeoNode/Sync.js

@@ -16,7 +16,10 @@ ESPRMNeoNode.ESPRMNeoNode.prototype.sync = async function () {
         // Apply first so a schema issue surfaces to the caller instead of
         // poisoning the storage cache for the next cold start.
         this.applyNodeConfig(config);
-        await nodeUtils.writeLocalNodeConfig(this.nodeId, config);
+        await nodeUtils.writeLocalNodeConfig(this.nodeId, {
+            ...config,
+            connectivity_status: this.connectivityStatus,
+        });
         return this;
     }
     catch (error) {

package/dist/cjs/methods/ESPRMNeoNode/Sync.js.map

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

package/dist/cjs/methods/ESPRMNeoUser/MQTT/AssumeRole.js

@@ -11,27 +11,26 @@ var ESPSigV4APIManager = require('../../../services/ESPSigV4APIManager.js');
  */
 /**
  * Implementation of the `assumeRole` method for the `ESPRMNeoUser` class.
- *
- * Exchanges identity (temporary) credentials for assume-role credentials with IoT/MQTT
- * permissions. The backend signs the user in with the provided credentials and returns
- * a new credential set for MQTT; this is not refreshing or extending the same credentials.
  */
 ESPRMNeoUser.ESPRMNeoUser.prototype.assumeRole = async function (accessKey, secretKey, sessionToken, options) {
-    // Request body: identity (temporary) credentials so backend can assume the IoT role
     const requestBody = {
         access_key: accessKey,
         secret_key: secretKey,
         session_token: sessionToken,
     };
-    // Merge optional fields (e.g., include: ["s3", "kvs"])
-    if (options?.include && options.include.length > 0) {
-        requestBody.include = options.include;
+    const servicesMode = !!(options?.services && options.services.length > 0);
+    if (servicesMode) {
+        if (!options.nodeId) {
+            throw new Error(constants.AssumeRoleErrorMessages.NODE_ID_REQUIRED);
+        }
+        requestBody.services = options.services;
+        requestBody.node_id = options.nodeId;
     }
     const api = ESPSigV4APIManager.ESPSigV4APIManager.getInstance();
     const response = await api.post(constants.APIPathV1.ASSUME_ROLE, requestBody);
     // Validate response contains required fields
     if (!response.access_key || !response.secret_key || !response.session_token) {
-        throw new Error("Invalid assume role response: missing required credential fields");
+        throw new Error(constants.AssumeRoleErrorMessages.INVALID_RESPONSE);
     }
     return response;
 };

package/dist/cjs/methods/ESPRMNeoUser/MQTT/AssumeRole.js.map

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

package/dist/cjs/proto/esp_rmaker_chal_resp.js

@@ -21,6 +21,11 @@ function _interopNamespaceDefault(e) {
 
 var pb_1__namespace = /*#__PURE__*/_interopNamespaceDefault(pb_1);
 
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
 /**
  * Generated by the protoc-gen-ts.  DO NOT EDIT!
  * compiler version: 5.29.3

package/dist/cjs/proto/esp_rmaker_chal_resp.js.map

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

package/dist/cjs/services/ESPRMNeoMqtt/ESPRMNeoMqtt.js

@@ -87,6 +87,19 @@ class ESPRMNeoMqtt {
     isConnected() {
         return this.#adapter.isConnected();
     }
+    /**
+     * Registers a transport connection-status listener when the underlying
+     * adapter supports it; otherwise returns a no-op unsubscribe.
+     *
+     * @param callback - Invoked with `{ connected }` on status changes
+     * @returns Unsubscribe function
+     */
+    onConnectionStatusChange(callback) {
+        if (typeof this.#adapter.onConnectionStatusChange === "function") {
+            return this.#adapter.onConnectionStatusChange(callback);
+        }
+        return () => { };
+    }
     /**
      * Publish a message to a topic.
      *

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

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

package/dist/cjs/services/NodeMQTTOrchestrator.js

@@ -141,8 +141,8 @@ class NodeMQTTOrchestrator {
     /**
      * Registers a node with the orchestrator.
      * Must be called before subscribeToNode, getParams, getShadow, etc.
-     * On shadow rename: clears the old binding; ignores shorter/incomplete names.
-     * Shrink membership via {@link unregisterNode} first.
+     * On shadow rename: clears the old binding, then installs the new name
+     * (including shrinks to a shorter membership shadow).
      *
      * @param nodeId - The device/node identifier.
      * @param shadowName - The named shadow (e.g. `params-groupId-subgroupId`).
@@ -151,9 +151,6 @@ class NodeMQTTOrchestrator {
         const instance = NodeMQTTOrchestrator.getInstance();
         const existing = instance.nodeMap.get(nodeId);
         if (existing && existing.shadowName !== shadowName) {
-            if (shadowName.split("-").length < existing.shadowName.split("-").length) {
-                return;
-            }
             NodeMQTTOrchestrator.unregisterNode(nodeId);
         }
         instance.nodeMap.set(nodeId, { shadowName });

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

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

package/dist/cjs/utils/constants.js

@@ -393,6 +393,15 @@ const TriggerErrorMessages = {
     /** Logged when retrieving triggers for a node fails. */
     GET_FAILED: "getTriggers failed",
 };
+/**
+ * Error messages for assumeRole (POST /v1/assumed-roles).
+ */
+const AssumeRoleErrorMessages = {
+    /** Thrown when `services` is provided without a `nodeId`. */
+    NODE_ID_REQUIRED: "assumeRole: nodeId is required when services is provided",
+    /** Thrown when the assume-role response is missing required credential fields. */
+    INVALID_RESPONSE: "Invalid assume role response: missing required credential fields",
+};
 /**
  * Error / log messages for temporary AWS credentials (POST /v1/user/credentials).
  */
@@ -847,6 +856,7 @@ exports.APIEndpoints = APIEndpoints;
 exports.APIOperations = APIOperations;
 exports.APIPathV1 = APIPathV1;
 exports.AWSCredentialsErrorMessages = AWSCredentialsErrorMessages;
+exports.AssumeRoleErrorMessages = AssumeRoleErrorMessages;
 exports.AuthErrorCodes = AuthErrorCodes;
 exports.AuthSuccessMessages = AuthSuccessMessages;
 exports.AutomationStatusValues = AutomationStatusValues;

package/dist/cjs/utils/constants.js.map

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

package/dist/cjs/utils/nodeUtils.js

@@ -28,7 +28,18 @@ async function readLocalNodeConfig(nodeId) {
 /** Best-effort persist of node config to local storage. */
 async function writeLocalNodeConfig(nodeId, config) {
     try {
-        await ESPRMNeoStorage.ESPRMNeoStorage.setNodeConfig(nodeId, config);
+        let toStore = config;
+        // Cloud config omits connectivity — keep the last cached status when writing.
+        if (!config.connectivity_status) {
+            const prev = await ESPRMNeoStorage.ESPRMNeoStorage.getNodeConfig(nodeId);
+            if (prev?.connectivity_status) {
+                toStore = {
+                    ...config,
+                    connectivity_status: prev.connectivity_status,
+                };
+            }
+        }
+        await ESPRMNeoStorage.ESPRMNeoStorage.setNodeConfig(nodeId, toStore);
     }
     catch (error) {
         logger.warn(`Cache write failed for ${nodeId}`, error);

package/dist/cjs/utils/nodeUtils.js.map

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

package/dist/cjs/utils/waitForNodeOnline.js

@@ -65,11 +65,12 @@ function isNodeOnlineFromShadowPayload(payload) {
  * @throws {ESPProvError} If `timeoutMs` elapses without the node reporting online.
  * @throws {Error} If MQTT connection or subscription fails.
  */
-async function waitForNodeOnline({ nodeId, groupId, user, timeoutMs = DEFAULT_NODE_ONLINE_TIMEOUT_MS, pollIntervalMs = DEFAULT_NODE_ONLINE_POLL_INTERVAL_MS, }) {
-    const shadowName = shadowUtils.constructShadowName(groupId);
+async function waitForNodeOnline({ nodeId, groupId, subgroupIds, user, timeoutMs = DEFAULT_NODE_ONLINE_TIMEOUT_MS, pollIntervalMs = DEFAULT_NODE_ONLINE_POLL_INTERVAL_MS, }) {
+    const shadowName = shadowUtils.constructShadowName(groupId, subgroupIds ?? []);
     logger.info("Waiting for node to come online", {
         nodeId,
         groupId,
+        subgroupIds: subgroupIds ?? [],
         shadowName,
         timeoutMs,
         pollIntervalMs,
@@ -149,10 +150,10 @@ async function waitForNodeOnline({ nodeId, groupId, user, timeoutMs = DEFAULT_NO
             });
             await user.connectMQTT();
         }
-        // 2. Register (if needed) and subscribe before the shadow may exist
-        if (!alreadyRegistered) {
-            NodeMQTTOrchestrator.NodeMQTTOrchestrator.registerNode(nodeId, shadowName);
-        }
+        // 2. Bind to the membership shadow and subscribe before the shadow may exist.
+        // Always registerNode so a leftover longer/stale binding for the same nodeId
+        // is rebound to constructShadowName(groupId, subgroupIds).
+        NodeMQTTOrchestrator.NodeMQTTOrchestrator.registerNode(nodeId, shadowName);
         await NodeMQTTOrchestrator.NodeMQTTOrchestrator.subscribeToNode(nodeId, onUpdate);
         logger.debug("Subscribed to node shadow for online wait", {
             nodeId,

package/dist/cjs/utils/waitForNodeOnline.js.map

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

package/dist/esm/ESPDevice.js

@@ -22,6 +22,12 @@ class ESPDevice {
     name;
     transport;
     security;
+    /**
+     * What a completed association produced, kept so `retryNetworkCredentials`
+     * can resume the flow instead of repeating it. Set once verification
+     * succeeds; `undefined` until then.
+     */
+    provisionResumeState;
     constructor(deviceConfig) {
         this.name = deviceConfig.name;
         this.transport = deviceConfig.transport;

package/dist/esm/ESPDevice.js.map

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