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

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

@@ -0,0 +1,44 @@
+import { ESPDevice } from '../../ESPDevice.js';
+import { ESPProvResponseStatus } from '../../types/provision.js';
+import { ESPProvProgressMessages } from '../../utils/constants.js';
+import { ESPProvError } from '../../utils/error/ESPProvError.js';
+import { waitForNodeOnline, DEFAULT_NODE_ONLINE_TIMEOUT_MS } from '../../utils/waitForNodeOnline.js';
+import { Logger } from '../../utils/logger.js';
+
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const logger = new Logger("RetryNetworkCredentials");
+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("FAILED_PROV");
+    }
+    onProgress({
+        status: ESPProvResponseStatus.onProgress,
+        description: ESPProvProgressMessages.SETTING_NETWORK_CREDENTIALS,
+    });
+    await this.setNetworkCredentials(ssid, passphrase);
+    const options = resumeState.options;
+    if (options?.waitForOnline && options.user) {
+        onProgress({
+            status: ESPProvResponseStatus.onProgress,
+            description: ESPProvProgressMessages.WAITING_FOR_ONLINE,
+        });
+        await waitForNodeOnline({
+            nodeId: resumeState.nodeId,
+            groupId: resumeState.groupId,
+            user: options.user,
+            timeoutMs: options.onlineTimeoutMs ?? DEFAULT_NODE_ONLINE_TIMEOUT_MS,
+        });
+    }
+    onProgress({
+        status: ESPProvResponseStatus.succeed,
+        description: resumeState.nodeId ?? ESPProvProgressMessages.DEVICE_PROVISIONED,
+    });
+    return resumeState.nodeId;
+};
+//# sourceMappingURL=RetryNetworkCredentials.js.map

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

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

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

@@ -14,7 +14,10 @@ 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 writeLocalNodeConfig(this.nodeId, config);
+        await writeLocalNodeConfig(this.nodeId, {
+            ...config,
+            connectivity_status: this.connectivityStatus,
+        });
         return this;
     }
     catch (error) {

package/dist/esm/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/esm/methods/ESPRMNeoUser/MQTT/AssumeRole.js

@@ -1,5 +1,5 @@
 import { ESPRMNeoUser } from '../../../ESPRMNeoUser.js';
-import { APIPathV1 } from '../../../utils/constants.js';
+import { AssumeRoleErrorMessages, APIPathV1 } from '../../../utils/constants.js';
 import { ESPSigV4APIManager } from '../../../services/ESPSigV4APIManager.js';
 
 /*
@@ -9,27 +9,26 @@ import { ESPSigV4APIManager } from '../../../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.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(AssumeRoleErrorMessages.NODE_ID_REQUIRED);
+        }
+        requestBody.services = options.services;
+        requestBody.node_id = options.nodeId;
     }
     const api = ESPSigV4APIManager.getInstance();
     const response = await api.post(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(AssumeRoleErrorMessages.INVALID_RESPONSE);
     }
     return response;
 };

package/dist/esm/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/esm/proto/esp_rmaker_chal_resp.js

@@ -1,5 +1,10 @@
 import * as pb_1 from 'google-protobuf';
 
+/*
+ * 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/esm/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/esm/proto/rmaker_local_ctrl.js

@@ -0,0 +1,271 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Codec for the `rmaker_local_ctrl` endpoint protocol, mirroring the firmware's
+ * `local_ctrl.proto` schema.
+ *
+ * Hand-rolled like {@link ClaimingProtoHelper} rather than generated: the
+ * schema is small, and generated `google-protobuf` modules cannot be pulled
+ * into a downstream Metro/RN bundle (see the note in `utils/export.ts`).
+ *
+ * Field numbers are the wire contract with deployed firmware — treat them as
+ * frozen:
+ * - `RMakerLocalCtrlPayload`: 1 = msg (varint), 10 = cmdGetData, 11 = respGetData
+ * - `CmdGetData`:  1 = DataType (varint), 2 = Offset (varint),
+ *                  3 = Timestamp (varint), 4 = HasTimestamp (varint)
+ * - `RespGetData`: 1 = Status (varint), 2 = Buf
+ * - `PayloadBuf`:  1 = Offset (varint), 2 = Payload (bytes), 3 = TotalLen (varint)
+ *
+ * `Timestamp` / `HasTimestamp` are reserved for a future signed-response
+ * extension and are ignored by current firmware, so the encoder omits them.
+ *
+ * Only `get_params` / `get_config` use this schema; `set_params` carries raw
+ * JSON on the wire.
+ */
+/**
+ * Status returned by the device for a data read.
+ */
+var RMakerLocalCtrlStatus;
+(function (RMakerLocalCtrlStatus) {
+    RMakerLocalCtrlStatus[RMakerLocalCtrlStatus["Success"] = 0] = "Success";
+    RMakerLocalCtrlStatus[RMakerLocalCtrlStatus["Fail"] = 1] = "Fail";
+    RMakerLocalCtrlStatus[RMakerLocalCtrlStatus["InvalidParam"] = 2] = "InvalidParam";
+    RMakerLocalCtrlStatus[RMakerLocalCtrlStatus["NoMemory"] = 3] = "NoMemory";
+})(RMakerLocalCtrlStatus || (RMakerLocalCtrlStatus = {}));
+/**
+ * Selects which document a read targets.
+ */
+var RMakerLocalCtrlDataType;
+(function (RMakerLocalCtrlDataType) {
+    /** The node's params JSON, as served by `get_params`. */
+    RMakerLocalCtrlDataType[RMakerLocalCtrlDataType["TypeParams"] = 0] = "TypeParams";
+    /** The node's config JSON, as served by `get_config`. */
+    RMakerLocalCtrlDataType[RMakerLocalCtrlDataType["TypeConfig"] = 1] = "TypeConfig";
+})(RMakerLocalCtrlDataType || (RMakerLocalCtrlDataType = {}));
+/**
+ * Message type discriminator carried on `RMakerLocalCtrlPayload.msg`.
+ */
+var RMakerLocalCtrlMsgType;
+(function (RMakerLocalCtrlMsgType) {
+    RMakerLocalCtrlMsgType[RMakerLocalCtrlMsgType["TypeCmdGetData"] = 0] = "TypeCmdGetData";
+    RMakerLocalCtrlMsgType[RMakerLocalCtrlMsgType["TypeRespGetData"] = 1] = "TypeRespGetData";
+})(RMakerLocalCtrlMsgType || (RMakerLocalCtrlMsgType = {}));
+/** Tag bytes written by the request encoder: `(fieldNumber << 3) | wireType`. */
+const TAG_FIELD_1_VARINT = 0x08;
+const TAG_FIELD_2_VARINT = 0x10;
+const TAG_FIELD_10_BYTES = 0x52;
+const WIRE_TYPE_VARINT = 0;
+const WIRE_TYPE_BYTES = 2;
+/**
+ * Encoder/decoder for `rmaker_local_ctrl` frames.
+ */
+class RMakerLocalCtrlProtoHelper {
+    /**
+     * Builds a `CmdGetData` request for one fragment.
+     *
+     * An `offset` of 0 makes the device (re)generate and cache the document;
+     * subsequent offsets are served from that cache.
+     *
+     * @param dataType - Document to read.
+     * @param offset - Byte offset to read from.
+     * @returns The serialized request.
+     */
+    static createGetDataRequest(dataType, offset) {
+        const cmdGetData = this.concat([
+            // Both fields are written explicitly, including their proto3 zero values,
+            // matching how the reference clients frame this command.
+            new Uint8Array([TAG_FIELD_1_VARINT]),
+            this.encodeVarint(dataType),
+            new Uint8Array([TAG_FIELD_2_VARINT]),
+            this.encodeVarint(offset),
+        ]);
+        return this.concat([
+            new Uint8Array([TAG_FIELD_1_VARINT]),
+            this.encodeVarint(RMakerLocalCtrlMsgType.TypeCmdGetData),
+            new Uint8Array([TAG_FIELD_10_BYTES]),
+            this.encodeVarint(cmdGetData.length),
+            cmdGetData,
+        ]);
+    }
+    /**
+     * Parses a `RespGetData` frame from the device.
+     *
+     * @param data - Raw response bytes.
+     * @returns The parsed payload. Absent fields keep their proto3 defaults.
+     */
+    static parseGetDataResponse(data) {
+        const result = {
+            msg: RMakerLocalCtrlMsgType.TypeCmdGetData,
+        };
+        let index = 0;
+        while (index < data.length) {
+            const tag = data[index++];
+            const fieldNumber = tag >> 3;
+            const wireType = tag & 0x07;
+            if (fieldNumber === 1 && wireType === WIRE_TYPE_VARINT) {
+                const { value, newIndex } = this.readVarint(data, index);
+                result.msg = value;
+                index = newIndex;
+                continue;
+            }
+            if (fieldNumber === 11 && wireType === WIRE_TYPE_BYTES) {
+                const { value: length, newIndex } = this.readVarint(data, index);
+                result.respGetData = this.parseRespGetData(data.slice(newIndex, newIndex + length));
+                index = newIndex + length;
+                continue;
+            }
+            index = this.skipField(data, index, wireType);
+        }
+        return result;
+    }
+    /**
+     * Whether the device reported a successful read.
+     *
+     * @param response - Parsed response.
+     */
+    static isSuccess(response) {
+        return response.respGetData?.status === RMakerLocalCtrlStatus.Success;
+    }
+    /**
+     * Returns the device's status as its enum name, for diagnostics.
+     *
+     * @param response - Parsed response.
+     * @returns The status name, or `"Unknown"` when absent.
+     */
+    static getStatus(response) {
+        const status = response.respGetData?.status;
+        return status === undefined
+            ? "Unknown"
+            : (RMakerLocalCtrlStatus[status] ?? `Unknown(${status})`);
+    }
+    /**
+     * Offset the device answered with, which must match the requested offset.
+     *
+     * @param response - Parsed response.
+     */
+    static getOffset(response) {
+        return response.respGetData?.buf?.offset ?? 0;
+    }
+    /**
+     * Full document length reported by the device.
+     *
+     * @param response - Parsed response.
+     */
+    static getTotalLen(response) {
+        return response.respGetData?.buf?.totalLen ?? 0;
+    }
+    /**
+     * Fragment bytes carried by the response.
+     *
+     * @param response - Parsed response.
+     */
+    static getPayload(response) {
+        return response.respGetData?.buf?.payload ?? new Uint8Array(0);
+    }
+    // Private helper methods
+    static concat(parts) {
+        const totalLength = parts.reduce((sum, part) => sum + part.length, 0);
+        const result = new Uint8Array(totalLength);
+        let pos = 0;
+        for (const part of parts) {
+            result.set(part, pos);
+            pos += part.length;
+        }
+        return result;
+    }
+    static encodeVarint(value) {
+        const bytes = [];
+        let remaining = value;
+        while (remaining > 127) {
+            bytes.push((remaining & 0x7f) | 0x80);
+            remaining >>>= 7;
+        }
+        bytes.push(remaining & 0x7f);
+        return new Uint8Array(bytes);
+    }
+    static readVarint(data, index) {
+        let value = 0;
+        let shift = 0;
+        let byte;
+        do {
+            byte = data[index++];
+            value |= (byte & 0x7f) << shift;
+            shift += 7;
+        } while (byte & 0x80);
+        return { value, newIndex: index };
+    }
+    /** Advances past a field this codec does not read. */
+    static skipField(data, index, wireType) {
+        if (wireType === WIRE_TYPE_VARINT) {
+            return this.readVarint(data, index).newIndex;
+        }
+        if (wireType === WIRE_TYPE_BYTES) {
+            const { value: length, newIndex } = this.readVarint(data, index);
+            return newIndex + length;
+        }
+        return index + 1;
+    }
+    static parseRespGetData(data) {
+        // In proto3 an absent status defaults to 0, i.e. Success.
+        const result = { status: RMakerLocalCtrlStatus.Success };
+        let index = 0;
+        while (index < data.length) {
+            const tag = data[index++];
+            const fieldNumber = tag >> 3;
+            const wireType = tag & 0x07;
+            if (fieldNumber === 1 && wireType === WIRE_TYPE_VARINT) {
+                const { value, newIndex } = this.readVarint(data, index);
+                result.status = value;
+                index = newIndex;
+                continue;
+            }
+            if (fieldNumber === 2 && wireType === WIRE_TYPE_BYTES) {
+                const { value: length, newIndex } = this.readVarint(data, index);
+                result.buf = this.parsePayloadBuf(data.slice(newIndex, newIndex + length));
+                index = newIndex + length;
+                continue;
+            }
+            index = this.skipField(data, index, wireType);
+        }
+        return result;
+    }
+    static parsePayloadBuf(data) {
+        const result = {
+            offset: 0,
+            payload: new Uint8Array(0),
+            totalLen: 0,
+        };
+        let index = 0;
+        while (index < data.length) {
+            const tag = data[index++];
+            const fieldNumber = tag >> 3;
+            const wireType = tag & 0x07;
+            if (fieldNumber === 1 && wireType === WIRE_TYPE_VARINT) {
+                const { value, newIndex } = this.readVarint(data, index);
+                result.offset = value;
+                index = newIndex;
+                continue;
+            }
+            if (fieldNumber === 2 && wireType === WIRE_TYPE_BYTES) {
+                const { value: length, newIndex } = this.readVarint(data, index);
+                result.payload = data.slice(newIndex, newIndex + length);
+                index = newIndex + length;
+                continue;
+            }
+            if (fieldNumber === 3 && wireType === WIRE_TYPE_VARINT) {
+                const { value, newIndex } = this.readVarint(data, index);
+                result.totalLen = value;
+                index = newIndex;
+                continue;
+            }
+            index = this.skipField(data, index, wireType);
+        }
+        return result;
+    }
+}
+
+export { RMakerLocalCtrlDataType, RMakerLocalCtrlMsgType, RMakerLocalCtrlProtoHelper, RMakerLocalCtrlStatus };
+//# sourceMappingURL=rmaker_local_ctrl.js.map

package/dist/esm/proto/rmaker_local_ctrl.js.map

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

package/dist/esm/services/ESPRMNeoMqtt/ESPRMNeoMqtt.js

@@ -85,6 +85,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/esm/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/esm/services/ESPTransport/ESPDiscovery/ESPDiscoveryManager.js

@@ -12,9 +12,10 @@ import { ServiceType } from '../../../utils/constants.js';
  * 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.
+ *   (mDNS service `_esp_rmaker_ctrl._tcp.` in the `local` domain — the
+ *   service advertised by RainMaker Neo firmware).
+ * - A custom {@link DiscoveryParamsInterface} can be supplied to browse any
+ *   other service type.
  */
 class ESPDiscoveryManager {
     /** Discovery parameters (service type / domain) passed to the adapter. */
@@ -29,7 +30,7 @@ class ESPDiscoveryManager {
             throw new Error("ESPLocalDiscoveryAdapter not set");
         }
         this.params = discoveryConfig || {
-            serviceType: ServiceType.ESP_LOCAL_CTRL_TCP,
+            serviceType: ServiceType.ESP_RMAKER_LOCAL_CTRL_TCP,
             domain: ESPDiscoveryProtocol.local,
         };
     }

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

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