@espressif/rainmaker-neo-base-sdk 1.0.0

package/dist/cjs/ESPRMNeoBase.js

@@ -0,0 +1,250 @@
+'use strict';
+
+var ConfigValidator = require('./utils/validator/ConfigValidator.js');
+var logger$1 = require('./utils/logger.js');
+var ESPRMNeoStorage = require('./services/ESPRMNeoStorage/ESPRMNeoStorage.js');
+var baseUtils = require('./utils/baseUtils.js');
+var constants = require('./utils/constants.js');
+
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const logger = new logger$1.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 = baseUtils.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.ConfigValidator.validateConfig(config);
+        baseUtils.logConfigSummary(config);
+        try {
+            if (ESPRMNeoBase.#config) {
+                ESPRMNeoBase.dispose();
+            }
+            const adapters = baseUtils.extractAdaptersFromConfig(config);
+            ESPRMNeoBase._storageAdapter = adapters.storage;
+            ESPRMNeoBase._provisionAdapter = adapters.provision;
+            ESPRMNeoBase._localControlAdapter = adapters.localControl;
+            ESPRMNeoBase._localDiscoveryAdapter = adapters.localDiscovery;
+            baseUtils.initializeMqttIfConfigured(config);
+            ESPRMNeoBase.authInstance = baseUtils.createAuthInstance(config);
+            ESPRMNeoBase.#config = config;
+            baseUtils.initializeApiStack(config, ESPRMNeoBase._storageAdapter);
+            ESPRMNeoBase._subscriptionManager = baseUtils.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() {
+        baseUtils.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 = baseUtils.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() {
+        baseUtils.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() {
+        baseUtils.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() {
+        baseUtils.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");
+        baseUtils.assertSdkInitialized(!!ESPRMNeoBase.#config);
+        baseUtils.assertAdapterProvided(adapter, constants.ConfigErrorCodes.INVALID_STORAGE_ADAPTER);
+        ESPRMNeoBase._storageAdapter = adapter;
+        ESPRMNeoStorage.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.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) {
+        baseUtils.assertSdkInitialized(!!ESPRMNeoBase.#config);
+        baseUtils.assertAdapterProvided(adapter, constants.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) {
+        baseUtils.assertSdkInitialized(!!ESPRMNeoBase.#config);
+        baseUtils.assertAdapterProvided(adapter, constants.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) {
+        baseUtils.assertSdkInitialized(!!ESPRMNeoBase.#config);
+        baseUtils.assertAdapterProvided(adapter, constants.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 = baseUtils.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];
+    }
+}
+
+exports.ESPRMNeoBase = ESPRMNeoBase;
+//# sourceMappingURL=ESPRMNeoBase.js.map

package/dist/cjs/ESPRMNeoBase.js.map

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

package/dist/cjs/ESPRMNeoDevice.js

@@ -0,0 +1,51 @@
+'use strict';
+
+var ESPRMNeoDeviceParam = require('./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.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();
+    }
+}
+
+exports.ESPRMNeoDevice = ESPRMNeoDevice;
+//# sourceMappingURL=ESPRMNeoDevice.js.map

package/dist/cjs/ESPRMNeoDevice.js.map

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

package/dist/cjs/ESPRMNeoDeviceParam.js

@@ -0,0 +1,54 @@
+'use strict';
+
+var DelegatedTransportHandler = require('./services/ESPRMNeoHelpers/DelegatedTransportHandler.js');
+var constants = require('./utils/constants.js');
+var ESPAPICallValidationError = require('./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.ESPAPICallValidationError(constants.APICallValidationErrorCodes.MISSING_NODE_REF);
+        }
+        const payload = {
+            node_id: node.nodeId,
+            payload: { [this.deviceName]: { [this.id]: value } },
+        };
+        return (DelegatedTransportHandler.delegatedTransportHandler).call(node, (manager) => manager.setParam(payload, node));
+    }
+}
+
+exports.ESPRMNeoDeviceParam = ESPRMNeoDeviceParam;
+//# sourceMappingURL=ESPRMNeoDeviceParam.js.map

package/dist/cjs/ESPRMNeoDeviceParam.js.map

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

package/dist/cjs/ESPRMNeoGroup.js

@@ -0,0 +1,50 @@
+'use strict';
+
+/*
+ * 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,
+            })) ?? [];
+    }
+}
+
+exports.ESPRMNeoGroup = ESPRMNeoGroup;
+exports.isChildGroup = isChildGroup;
+//# sourceMappingURL=ESPRMNeoGroup.js.map

package/dist/cjs/ESPRMNeoGroup.js.map

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