@espressif/rainmaker-neo-base-sdk 1.0.0

package/dist/esm/services/ESPRMNeoHelpers/NodeMappingHelper.js

@@ -0,0 +1,43 @@
+import { ESPSigV4APIManager } from '../ESPSigV4APIManager.js';
+import { APIPathV1 } from '../../utils/constants.js';
+import { normalizeApiResponse } from '../../utils/normalizeApiResponse.js';
+
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Helper module for managing node mapping-related operations.
+ */
+class NodeMappingHelper {
+    /**
+     * Initiates a user node mapping request.
+     *
+     * @param groupId - The ID of the group to associate the node with.
+     * @param requestBody - The request body for the user node mapping.
+     * @returns A promise that resolves to the response from the API.
+     */
+    static async initiateUserNodeMapping(groupId, requestBody = {}) {
+        const api = ESPSigV4APIManager.getInstance();
+        const endpoint = APIPathV1.USER_NODE_MAPPING_INITIATE(groupId);
+        return api.post(endpoint, requestBody);
+    }
+    /**
+     * Verifies the mapping between a user and a node.
+     *
+     * @param groupId - The ID of the group.
+     * @param requestId - The node association request ID.
+     * @param requestBody - The request body for the user node mapping verification.
+     * @returns A promise that resolves to the response from the API.
+     */
+    static async verifyUserNodeMapping(groupId, requestId, requestBody = {}) {
+        const api = ESPSigV4APIManager.getInstance();
+        const endpoint = APIPathV1.USER_NODE_MAPPING_VERIFY(groupId, requestId);
+        const response = await api.post(endpoint, requestBody);
+        return normalizeApiResponse(response, { message: "User node mapping verified successfully" });
+    }
+}
+
+export { NodeMappingHelper };
+//# sourceMappingURL=NodeMappingHelper.js.map

package/dist/esm/services/ESPRMNeoHelpers/NodeMappingHelper.js.map

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

package/dist/esm/services/ESPRMNeoHelpers/TransformEncoding.js

@@ -0,0 +1,63 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Converts a base64 string to a Uint8Array.
+ * @param b64 The base64 string to convert
+ * @returns A Uint8Array containing the decoded bytes
+ * @throws {Error} If the input is not a valid base64 string
+ */
+function base64ToUint8Array(b64) {
+    // Validate base64 string format
+    const base64Regex = /^[A-Za-z0-9+/]*={0,2}$/;
+    if (!base64Regex.test(b64)) {
+        throw new Error(`Invalid base64 string: contains invalid characters`);
+    }
+    try {
+        if (globalThis.Buffer) {
+            const buf = globalThis.Buffer.from(b64, "base64");
+            // Buffer.from doesn't throw for invalid base64, so we need to validate by encoding back
+            const reencoded = buf.toString("base64");
+            // Remove padding for comparison
+            const normalizedInput = b64.replace(/=+$/, "");
+            const normalizedOutput = reencoded.replace(/=+$/, "");
+            if (normalizedInput !== normalizedOutput) {
+                throw new Error(`Invalid base64 string: decoding failed`);
+            }
+            return Uint8Array.from(buf);
+        }
+        else {
+            const bin = globalThis.atob(b64);
+            const arr = new Uint8Array(bin.length);
+            for (let i = 0; i < bin.length; ++i) {
+                arr[i] = bin.charCodeAt(i);
+            }
+            return arr;
+        }
+    }
+    catch (error) {
+        throw new Error(`Invalid base64 string: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Converts a Uint8Array to a base64 string.
+ * @param arr The Uint8Array to convert
+ * @returns A base64-encoded string
+ */
+function uint8ArrayToBase64(arr) {
+    if (globalThis.Buffer) {
+        return globalThis.Buffer.from(arr).toString("base64");
+    }
+    else {
+        const bin = [];
+        arr.forEach((byte) => {
+            bin.push(String.fromCharCode(byte));
+        });
+        return globalThis.btoa(bin.join(""));
+    }
+}
+
+export { base64ToUint8Array, uint8ArrayToBase64 };
+//# sourceMappingURL=TransformEncoding.js.map

package/dist/esm/services/ESPRMNeoHelpers/TransformEncoding.js.map

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

package/dist/esm/services/ESPRMNeoHelpers/transformShadowToNodeUpdate.js

@@ -0,0 +1,52 @@
+import { getReportedParamsFromShadowDocument } from '../../utils/awsShadowTopics.js';
+import { SubscriptionChannelIds } from '../../utils/constants.js';
+
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Canonical event type emitted when a node's parameters change.
+ */
+const NODE_PARAMS_CHANGED_EVENT = "rmneo.event.node_params_changed";
+/**
+ * Normalizes a parsed AWS IoT shadow document into the canonical
+ * {@link ESPNodeUpdateData} envelope used by every subscription channel.
+ *
+ * The `payload` is reduced to the device→param map
+ * (`{ <deviceName>: { <paramName>: value } }`) by preferring
+ * `state.reported.params` and falling back to `state.reported`, so all channels
+ * agree on the same payload shape regardless of transport.
+ *
+ * The full parsed shadow is also attached as `metadata.shadow` so consumers that
+ * need fields outside the param map (e.g. `online`, `ncfg_ver`) can read them
+ * without changing the normalized `payload` contract.
+ *
+ * @param nodeId - The node the update belongs to.
+ * @param parsedShadow - The parsed shadow document (full live message or get/accepted document).
+ * @param meta - Channel-specific metadata to merge into `metadata` (e.g. `{ shadowName, topic }`).
+ * @param source - The originating channel id (defaults to the MQTT channel).
+ * @returns A normalized `ESPNodeUpdateData`.
+ */
+function transformShadowToNodeUpdate(nodeId, parsedShadow, meta = {}, source = SubscriptionChannelIds.MQTT) {
+    const payload = getReportedParamsFromShadowDocument(parsedShadow);
+    const shadow = (parsedShadow ?? {});
+    return {
+        nodeId,
+        source,
+        eventType: NODE_PARAMS_CHANGED_EVENT,
+        payload,
+        metadata: {
+            ...meta,
+            version: shadow.version,
+            timestamp: shadow.timestamp,
+            // Full parsed shadow, for consumers (e.g. ESPRMNeoNode) that need fields
+            // beyond the param map such as `online` / `ncfg_ver`.
+            shadow: parsedShadow,
+        },
+    };
+}
+
+export { NODE_PARAMS_CHANGED_EVENT, transformShadowToNodeUpdate };
+//# sourceMappingURL=transformShadowToNodeUpdate.js.map

package/dist/esm/services/ESPRMNeoHelpers/transformShadowToNodeUpdate.js.map

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

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

@@ -0,0 +1,118 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Singleton `MQTTTransport` that forwards calls to the transport passed to
+ * {@link ESPRMNeoMqtt.initialize}. Use with `NodeMQTTOrchestrator` as in the
+ * example below.
+ *
+ * @example
+ * ```ts
+ * ESPRMNeoMqtt.initialize(mqttTransport);
+ * NodeMQTTOrchestrator.initialize(ESPRMNeoMqtt.getInstance());
+ * ```
+ */
+class ESPRMNeoMqtt {
+    static #instance;
+    #adapter;
+    /**
+     * @param adapter - Transport to wrap (typically a concrete MQTT client adapter).
+     */
+    constructor(adapter) {
+        this.#adapter = adapter;
+    }
+    /**
+     * Initializes the singleton with an MQTT transport.
+     * Must be called before {@link ESPRMNeoMqtt.getInstance}.
+     *
+     * @param adapter - `MQTTTransport` implementation to delegate to.
+     * @throws {Error} If already initialized. Call {@link ESPRMNeoMqtt.clear}
+     *   first if you genuinely need to re-init (e.g. between test cases). A
+     *   silent replacement is refused because in-flight subscriptions on the
+     *   old adapter would be orphaned and messages would split between the
+     *   two live transports.
+     */
+    static initialize(adapter) {
+        if (this.#instance) {
+            throw new Error("ESPRMNeoMqtt already initialized. Call clear() first if you truly need to re-init.");
+        }
+        this.#instance = new ESPRMNeoMqtt(adapter);
+    }
+    /**
+     * Returns the singleton instance.
+     *
+     * @throws {Error} If {@link ESPRMNeoMqtt.initialize} was not called.
+     */
+    static getInstance() {
+        const instance = this.#instance;
+        if (!instance) {
+            throw new Error("ESPRMNeoMqtt not initialized. Call initialize(adapter) first.");
+        }
+        return instance;
+    }
+    /**
+     * Clears the singleton.
+     */
+    static clear() {
+        this.#instance = undefined;
+    }
+    /**
+     * Returns true when {@link ESPRMNeoMqtt.initialize} has been called.
+     * Safe to call before init (does not throw).
+     */
+    static hasInstance() {
+        return this.#instance !== undefined;
+    }
+    /**
+     * Connect to MQTT using the provided configuration.
+     *
+     * @param config - MQTT configuration
+     */
+    async connect(config) {
+        await this.#adapter.connect(config);
+    }
+    /**
+     * Disconnect from MQTT.
+     */
+    async disconnect() {
+        await this.#adapter.disconnect();
+    }
+    /**
+     * Returns whether the underlying MQTT client is connected.
+     */
+    isConnected() {
+        return this.#adapter.isConnected();
+    }
+    /**
+     * Publish a message to a topic.
+     *
+     * @param topic - MQTT topic to publish to
+     * @param payload - Message payload to publish
+     */
+    async publish(topic, payload) {
+        await this.#adapter.publish(topic, payload);
+    }
+    /**
+     * Subscribe to a topic with a message handler.
+     *
+     * @param topic - MQTT topic to subscribe to
+     * @param handler - Callback invoked when a message is received on the topic
+     */
+    async subscribe(topic, handler) {
+        await this.#adapter.subscribe(topic, handler);
+    }
+    /**
+     * Unsubscribe from a topic, optionally removing a specific handler.
+     *
+     * @param topic - MQTT topic to unsubscribe from
+     * @param handler - Callback that was used with {@link ESPRMNeoMqtt.subscribe}
+     */
+    async unsubscribe(topic, handler) {
+        await this.#adapter.unsubscribe(topic, handler);
+    }
+}
+
+export { ESPRMNeoMqtt };
+//# sourceMappingURL=ESPRMNeoMqtt.js.map

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

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

package/dist/esm/services/ESPRMNeoStorage/DefaultStorageAdapter.js

@@ -0,0 +1,50 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Detects a usable `localStorage` at construction time — present on browsers
+ * but missing on React Native and most Node.js runtimes.
+ */
+function detectLocalStorage() {
+    if (typeof globalThis === "undefined")
+        return null;
+    const storage = globalThis.localStorage;
+    return storage ?? null;
+}
+/**
+ * Default storage adapter backed by the runtime's `localStorage`.
+ *
+ * Only useful on browser-like environments. On React Native and Node.js
+ * (which have no `localStorage`), pass a custom adapter to
+ * {@link ESPRMNeoStorage.initialize} — for example one backed by
+ * `@react-native-async-storage/async-storage`.
+ */
+class DefaultStorageAdapter {
+    storage;
+    constructor() {
+        const storage = detectLocalStorage();
+        if (!storage) {
+            throw new Error("DefaultStorageAdapter: no localStorage available on this runtime. " +
+                "Pass a custom storage adapter to ESPRMNeoBase.configure() " +
+                "(e.g. AsyncStorage on React Native).");
+        }
+        this.storage = storage;
+    }
+    async setItem(name, value) {
+        this.storage.setItem(name, value);
+    }
+    async getItem(name) {
+        return this.storage.getItem(name);
+    }
+    async removeItem(name) {
+        this.storage.removeItem(name);
+    }
+    async clear() {
+        this.storage.clear();
+    }
+}
+
+export { DefaultStorageAdapter };
+//# sourceMappingURL=DefaultStorageAdapter.js.map

package/dist/esm/services/ESPRMNeoStorage/DefaultStorageAdapter.js.map

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

package/dist/esm/services/ESPRMNeoStorage/ESPRMNeoStorage.js

@@ -0,0 +1,139 @@
+import { StorageKeys } from '../../utils/constants.js';
+import { DefaultStorageAdapter } from './DefaultStorageAdapter.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("ESPRMNeoStorage");
+/**
+ * Module-scoped singleton. Constructed only via {@link ESPRMNeoStorage.initialize};
+ * cleared by {@link _resetESPRMNeoStorageForTests}.
+ */
+let instance;
+/**
+ * Manages storage operations using a configurable storage adapter.
+ */
+class ESPRMNeoStorage {
+    /** Storage adapter used for storage operations */
+    #storageAdapter;
+    /**
+     * Instantiated only via {@link ESPRMNeoStorage.initialize}; external callers
+     * should never `new` this class directly.
+     */
+    constructor(customStorageAdapter) {
+        this.#storageAdapter = customStorageAdapter || new DefaultStorageAdapter();
+    }
+    /**
+     * Initializes the singleton instance of ESPRMNeoStorage.
+     */
+    static initialize(customStorageAdapter) {
+        instance = new ESPRMNeoStorage(customStorageAdapter);
+    }
+    /**
+     * Gets the singleton instance of ESPRMNeoStorage.
+     *
+     * @returns The singleton instance of ESPRMNeoStorage.
+     */
+    static #getInstance() {
+        return instance;
+    }
+    /**
+     * Sets an item in the storage.
+     *
+     * @param name - The name of the item.
+     * @param value - The value to store.
+     */
+    static async setItem(name, value) {
+        const storage = this.#getInstance();
+        await storage.#storageAdapter.setItem(name, value);
+    }
+    /**
+     * Retrieves an item from the storage.
+     *
+     * @param name - The name of the item.
+     * @returns A promise that resolves with the value of the item or null if not found.
+     */
+    static getItem(name) {
+        const storage = this.#getInstance();
+        return storage.#storageAdapter.getItem(name);
+    }
+    /**
+     * Removes an item from the storage.
+     *
+     * @param name - The name of the item.
+     */
+    static async removeItem(name) {
+        const storage = this.#getInstance();
+        await storage.#storageAdapter.removeItem(name);
+    }
+    /**
+     * Clears all items from the storage.
+     */
+    static async clear() {
+        const storage = this.#getInstance();
+        await storage.#storageAdapter.clear();
+    }
+    /**
+     * Temporary AWS Credentials Management
+     */
+    static async saveTemporaryCredentials(credentials) {
+        await this.setItem(StorageKeys.TEMPORARY_AWS_CREDENTIALS, JSON.stringify(credentials));
+    }
+    static async getTemporaryCredentials() {
+        const credentialsString = await this.getItem(StorageKeys.TEMPORARY_AWS_CREDENTIALS);
+        if (!credentialsString) {
+            throw new Error("No AWS credentials found");
+        }
+        return JSON.parse(credentialsString);
+    }
+    static async clearTemporaryCredentials() {
+        await this.removeItem(StorageKeys.TEMPORARY_AWS_CREDENTIALS);
+    }
+    /**
+     * Node Config Management
+     *
+     * Node configs are stored as JSON under `NODE_CONFIG_PREFIX + nodeId`. All
+     * three methods below encapsulate that layout so no other file needs to
+     * know how a node config is serialized.
+     */
+    static async getNodeConfig(nodeId) {
+        const raw = await this.getItem(StorageKeys.NODE_CONFIG_PREFIX + nodeId);
+        if (!raw)
+            return null;
+        try {
+            return JSON.parse(raw);
+        }
+        catch (parseError) {
+            // A bad blob would otherwise poison every subsequent read; treat it as
+            // a cache miss and let the caller repopulate on the next cloud fetch.
+            logger.warn("Corrupted cached node config; treating as missing", {
+                nodeId,
+                error: parseError instanceof Error
+                    ? parseError.message
+                    : String(parseError),
+            });
+            return null;
+        }
+    }
+    static async setNodeConfig(nodeId, config) {
+        await this.setItem(StorageKeys.NODE_CONFIG_PREFIX + nodeId, JSON.stringify(config));
+    }
+    static async deleteNodeConfig(nodeId) {
+        await this.removeItem(StorageKeys.NODE_CONFIG_PREFIX + nodeId);
+    }
+}
+/**
+ * Clears the storage singleton so {@link ESPRMNeoStorage.initialize} can run
+ * again after SDK dispose. Test / teardown only; not re-exported.
+ *
+ * @internal
+ */
+function _resetESPRMNeoStorageForTests() {
+    instance = undefined;
+}
+
+export { ESPRMNeoStorage, _resetESPRMNeoStorageForTests };
+//# sourceMappingURL=ESPRMNeoStorage.js.map

package/dist/esm/services/ESPRMNeoStorage/ESPRMNeoStorage.js.map

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