@espressif/rainmaker-neo-base-sdk 1.0.0

package/dist/esm/utils/eventSubscriptionUtils.js

@@ -0,0 +1,42 @@
+import { ESPDiscoveryManager } from '../services/ESPTransport/ESPDiscovery/ESPDiscoveryManager.js';
+import { subscribeNodeUpdates } from '../services/NodeUpdatesBus.js';
+import { ESPTransportMode } from '../types/transport.js';
+
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/** Maps a default local-discovery hit into the client-facing payload shape. */
+function toDiscoveredNodeData(info) {
+    return {
+        nodeId: info.nodeId,
+        transportDetails: {
+            type: ESPTransportMode.local,
+            metadata: { baseUrl: info.baseUrl },
+        },
+    };
+}
+/** Starts LAN discovery; each hit is mapped then passed to `onDiscovered`. */
+function startLocalDiscovery(onDiscovered) {
+    const manager = new ESPDiscoveryManager();
+    manager.startDiscovery((info) => onDiscovered(toDiscoveredNodeData(info)));
+    return { stop: () => manager.stopDiscovery() };
+}
+/** Forwards process-wide node param updates to `onUpdate`. */
+function startNodeUpdates(onUpdate) {
+    const unsubscribe = subscribeNodeUpdates(onUpdate);
+    return { stop: unsubscribe };
+}
+/**
+ * Starts discovery with a custom config; raw adapter results are forwarded
+ * unchanged (caller interprets them).
+ */
+function startCustomDiscovery(config, onInfo) {
+    const manager = new ESPDiscoveryManager(config);
+    manager.startDiscovery(onInfo);
+    return { stop: () => manager.stopDiscovery() };
+}
+
+export { startCustomDiscovery, startLocalDiscovery, startNodeUpdates, toDiscoveredNodeData };
+//# sourceMappingURL=eventSubscriptionUtils.js.map

package/dist/esm/utils/eventSubscriptionUtils.js.map

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

package/dist/esm/utils/groupUtils.js

@@ -0,0 +1,30 @@
+import { isChildGroup } from '../ESPRMNeoGroup.js';
+
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Resolves a group API path for a root group vs nested subgroup.
+ *
+ * - Root: `root(group.groupId, ...args)`
+ * - Child: `subgroup(group.parentId, group.groupId, ...args)`
+ */
+function resolveGroupPath(group, root, subgroup, ...args) {
+    return isChildGroup(group)
+        ? subgroup(group.parentId, group.groupId, ...args)
+        : root(group.groupId, ...args);
+}
+/**
+ * PATCH body for renaming a root group (`group_name`) or nested subgroup
+ * (`subgroup_name`).
+ */
+function buildGroupNameBody(group, name) {
+    return isChildGroup(group)
+        ? { subgroup_name: name }
+        : { group_name: name };
+}
+
+export { buildGroupNameBody, resolveGroupPath };
+//# sourceMappingURL=groupUtils.js.map

package/dist/esm/utils/groupUtils.js.map

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

package/dist/esm/utils/logger.js

@@ -0,0 +1,45 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+var LogLevel;
+(function (LogLevel) {
+    LogLevel[LogLevel["ERROR"] = 0] = "ERROR";
+    LogLevel[LogLevel["WARN"] = 1] = "WARN";
+    LogLevel[LogLevel["INFO"] = 2] = "INFO";
+    LogLevel[LogLevel["DEBUG"] = 3] = "DEBUG";
+})(LogLevel || (LogLevel = {}));
+class Logger {
+    context;
+    static level = LogLevel.INFO; // Default level
+    constructor(context) {
+        this.context = context;
+    }
+    static setLogLevel(level) {
+        Logger.level = level;
+    }
+    error(message, error) {
+        if (Logger.level >= LogLevel.ERROR) {
+            console.error(`[ERROR][${this.context}] ${message}`, error || "");
+        }
+    }
+    warn(message, data) {
+        if (Logger.level >= LogLevel.WARN) {
+            console.warn(`[WARN][${this.context}] ${message}`, data || "");
+        }
+    }
+    info(message, data) {
+        if (Logger.level >= LogLevel.INFO) {
+            console.info(`[INFO][${this.context}] ${message}`, data || "");
+        }
+    }
+    debug(message, data) {
+        if (Logger.level >= LogLevel.DEBUG) {
+            console.debug(`[DEBUG][${this.context}] ${message}`, data || "");
+        }
+    }
+}
+
+export { LogLevel, Logger };
+//# sourceMappingURL=logger.js.map

package/dist/esm/utils/logger.js.map

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

package/dist/esm/utils/mapLimit.js

@@ -0,0 +1,41 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Runs one promise per item immediately, keeping at most `poolLimit` in flight
+ * (classic async pool: schedule parallel work, throttle with {@link Promise.race}).
+ * Results match the order of `items`.
+ *
+ * @param poolLimit - Max concurrent `iteratorFn` executions (must be ≥ 1)
+ * @param items - Input values
+ * @param iteratorFn - Async work per item
+ */
+async function concurrentFetchPool(poolLimit, items, iteratorFn) {
+    if (poolLimit < 1) {
+        throw new RangeError("concurrentFetchPool: poolLimit must be >= 1");
+    }
+    if (items.length === 0) {
+        return [];
+    }
+    const executing = new Set();
+    const results = [];
+    for (const [index, item] of items.entries()) {
+        const p = Promise.resolve().then(() => iteratorFn(item, index));
+        results.push(p);
+        const slot = p.then(() => {
+            executing.delete(slot);
+        }, () => {
+            executing.delete(slot);
+        });
+        executing.add(slot);
+        if (executing.size >= poolLimit) {
+            await Promise.race(executing);
+        }
+    }
+    return Promise.all(results);
+}
+
+export { concurrentFetchPool };
+//# sourceMappingURL=mapLimit.js.map

package/dist/esm/utils/mapLimit.js.map

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

package/dist/esm/utils/mqtt.js

@@ -0,0 +1,27 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Resolves an MQTT endpoint to a WebSocket MQTT URL (wss://host/mqtt).
+ * Strips any existing protocol or /mqtt path from the input and returns a normalized URL.
+ *
+ * @param mqttEndpoint - Raw MQTT endpoint (e.g. "xxxxx-ats.iot.region.amazonaws.com" or "wss://.../mqtt").
+ * @returns Normalized URL "wss://{host}/mqtt" for use with MQTT over WebSocket.
+ * @throws Error if endpoint is empty.
+ */
+function resolveMqttWebSocketEndpoint(mqttEndpoint) {
+    if (!mqttEndpoint || typeof mqttEndpoint !== "string") {
+        throw new Error("Invalid MQTT endpoint: endpoint is required");
+    }
+    const trimmed = mqttEndpoint.trim();
+    const cleanEndpoint = trimmed
+        .replace(/^https?:\/\//, "")
+        .replace(/^wss?:\/\//, "")
+        .replace(/\/mqtt\/?$/, "");
+    return `wss://${cleanEndpoint}/mqtt`;
+}
+
+export { resolveMqttWebSocketEndpoint };
+//# sourceMappingURL=mqtt.js.map

package/dist/esm/utils/mqtt.js.map

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

package/dist/esm/utils/nodeNcfgVersionHandler.js

@@ -0,0 +1,123 @@
+import { ESPRMNeoStorage } from '../services/ESPRMNeoStorage/ESPRMNeoStorage.js';
+import { coerceToString } from './coerce.js';
+import { asObject } from './common.js';
+import { StorageKeys } from './constants.js';
+import { Logger } from './logger.js';
+
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const logger = new Logger("nodeNcfgVersionHandler");
+/** Reads the cached ncfg_ver map from storage; returns `{}` if none or unparseable. */
+async function getNcfgCachedVersion() {
+    try {
+        const raw = await ESPRMNeoStorage.getItem(StorageKeys.NCFG_VERSIONS);
+        if (!raw)
+            return {};
+        return asObject(JSON.parse(raw));
+    }
+    catch {
+        return {};
+    }
+}
+/** Persists the cached ncfg_ver map. */
+async function saveNcfgCachedVersion(cachedVersions) {
+    await ESPRMNeoStorage.setItem(StorageKeys.NCFG_VERSIONS, JSON.stringify(cachedVersions));
+}
+/**
+ * Reads `ncfg_ver` from an IoT shadow document's `state.reported`.
+ *
+ * Legacy integer timestamps from older firmware are normalized to strings.
+ */
+function getNcfgVersion(shadow) {
+    return coerceToString(shadow.state?.reported?.ncfg_ver) ?? null;
+}
+/**
+ * Returns true when the shadow's `ncfg_ver` differs from the last cached
+ * version for this node. On first sighting, persists a baseline and returns
+ * false (no refresh needed).
+ */
+async function hasNcfgVersionChanged(nodeId, shadow) {
+    const current = getNcfgVersion(shadow);
+    if (current == null)
+        return false;
+    const cachedVersions = await getNcfgCachedVersion();
+    const prev = cachedVersions[nodeId];
+    // First sighting → baseline only.
+    if (prev === undefined) {
+        cachedVersions[nodeId] = current;
+        try {
+            await saveNcfgCachedVersion(cachedVersions);
+        }
+        catch {
+            /* ignore */
+        }
+        return false;
+    }
+    return prev !== current;
+}
+/**
+ * Persists the shadow's `ncfg_ver` as the last-seen cached version for this node.
+ * Call after a successful config refresh when {@link hasNcfgVersionChanged}
+ * returned true.
+ */
+async function persistNcfgVersionMarker(nodeId, shadow) {
+    const current = getNcfgVersion(shadow);
+    if (current == null)
+        return;
+    const cachedVersions = await getNcfgCachedVersion();
+    cachedVersions[nodeId] = current;
+    try {
+        await saveNcfgCachedVersion(cachedVersions);
+    }
+    catch {
+        /* ignore */
+    }
+}
+/**
+ * Removes the cached ncfg_ver for a single node. Call after
+ * `group.removeNode()` so the entry doesn't outlive the node in storage.
+ */
+async function clearNcfgVersionMarker(nodeId) {
+    const cachedVersions = await getNcfgCachedVersion();
+    if (!(nodeId in cachedVersions))
+        return;
+    delete cachedVersions[nodeId];
+    try {
+        await saveNcfgCachedVersion(cachedVersions);
+    }
+    catch {
+        /* ignore */
+    }
+}
+/**
+ * Removes every cached ncfg_ver. Call on logout / session reset.
+ * Returns the list of node ids whose entries were cleared, so callers can
+ * follow up (e.g. delete the corresponding node-config cache entries).
+ */
+async function clearAllNcfgVersionMarkers() {
+    const cachedVersions = await getNcfgCachedVersion();
+    const ids = Object.keys(cachedVersions);
+    if (ids.length === 0)
+        return [];
+    try {
+        await ESPRMNeoStorage.removeItem(StorageKeys.NCFG_VERSIONS);
+    }
+    catch (error) {
+        logger.debug("Failed to clear cached ncfg versions", error);
+    }
+    return ids;
+}
+/**
+ * Returns the list of node ids the SDK is currently tracking cached versions for.
+ * Callers can use it to enumerate related caches at logout time without
+ * needing the storage adapter to support key listing.
+ */
+async function listTrackedNodeIds() {
+    return Object.keys(await getNcfgCachedVersion());
+}
+
+export { clearAllNcfgVersionMarkers, clearNcfgVersionMarker, getNcfgVersion, hasNcfgVersionChanged, listTrackedNodeIds, persistNcfgVersionMarker };
+//# sourceMappingURL=nodeNcfgVersionHandler.js.map

package/dist/esm/utils/nodeNcfgVersionHandler.js.map

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

package/dist/esm/utils/nodeTransform.js

@@ -0,0 +1,109 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Transforms a raw API attribute to the shape used by {@link ESPRMNeoDevice}.
+ */
+function transformApiAttributeForNodeDevice(attr) {
+    return {
+        name: attr.name ?? "",
+        value: attr.value,
+    };
+}
+/**
+ * Transforms a raw API param to device param input for {@link ESPRMNeoDevice}.
+ * Tolerates both the API shape (snake_case) and the legacy cached runtime
+ * shape (camelCase, see {@link ESPRMNeoCachedParamShape}).
+ */
+function transformApiParamForNodeDevice(p) {
+    const cached = p;
+    return {
+        id: p.id,
+        type: p.type ?? p.id,
+        properties: p.properties ?? [],
+        dataType: p.data_type ?? cached.dataType,
+        uiType: p.ui_type ?? cached.uiType,
+        bounds: p.bounds,
+        validStrings: p.valid_strings ?? cached.validStrings,
+    };
+}
+/**
+ * Transforms a raw API param to service param input for {@link ESPRMNeoService}.
+ * Tolerates both the API shape (snake_case) and the legacy cached runtime
+ * shape (camelCase, see {@link ESPRMNeoCachedParamShape}).
+ */
+function transformApiParamForNodeService(p) {
+    const cached = p;
+    return {
+        id: p.id,
+        type: p.type ?? p.id,
+        properties: p.properties ?? [],
+        dataType: p.data_type ?? cached.dataType,
+        bounds: p.bounds,
+        validStrings: p.valid_strings ?? cached.validStrings,
+    };
+}
+/**
+ * Builds the first constructor argument for {@link ESPRMNeoDevice} from API data.
+ * Trusts the wire/API shape (`id`, `type`, …) — callers pass cloud or cache
+ * config already resolved before {@link ESPRMNeoNode} construction.
+ */
+function transformNodeDevice(d) {
+    const name = d.id;
+    return {
+        name,
+        displayName: name,
+        type: d.type ?? "esp.device.generic",
+        primary: d.primary,
+        attributes: d.attributes?.map(transformApiAttributeForNodeDevice),
+        params: (d.params ?? []).map(transformApiParamForNodeDevice),
+    };
+}
+/**
+ * Builds the first constructor argument for {@link ESPRMNeoService} from API data.
+ * Trusts the wire/API shape (`id`, `type`, …) — same as {@link transformNodeDevice}.
+ */
+function transformNodeService(s) {
+    return {
+        name: s.id,
+        type: s.type ?? "",
+        params: (s.params ?? []).map(transformApiParamForNodeService),
+    };
+}
+/**
+ * Transforms a raw node config `info` block ({@link ESPRMNeoNodeInfoAPI}) to
+ * {@link ESPRMNeoNodeInfoInterface}. The mapped `firmwareVersion` is added
+ * alongside the raw wire keys (`fw_version` is kept via the spread), so
+ * re-transforming an already-transformed object is a no-op.
+ * Returns `undefined` when `raw` is missing or not an object.
+ */
+function transformNodeInfo(raw) {
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    return {
+        ...raw,
+        type: raw.type ?? "",
+        model: raw.model ?? "",
+        firmwareVersion: raw.fw_version,
+        readme: raw.readme,
+    };
+}
+/**
+ * Params and connectivity from a shadow / reported-state JSON payload.
+ */
+function extract(json) {
+    const reported = json?.state?.reported;
+    return {
+        params: reported?.params || {},
+        connectivityStatus: {
+            isConnected: reported?.online || false,
+            lastConnectionTimestamp: reported?.disconnect_info?.last_disconnect_ts || 0,
+        },
+        configVersion: String(reported?.ncfg_ver ?? "") || "",
+    };
+}
+
+export { extract, transformApiAttributeForNodeDevice, transformApiParamForNodeDevice, transformApiParamForNodeService, transformNodeDevice, transformNodeInfo, transformNodeService };
+//# sourceMappingURL=nodeTransform.js.map

package/dist/esm/utils/nodeTransform.js.map

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

package/dist/esm/utils/nodeUtils.js

@@ -0,0 +1,104 @@
+import { isChildGroup } from '../ESPRMNeoGroup.js';
+import { ESPRMNeoNode } from '../ESPRMNeoNode.js';
+import { ESPSigV4APIManager } from '../services/ESPSigV4APIManager.js';
+import { ESPRMNeoStorage } from '../services/ESPRMNeoStorage/ESPRMNeoStorage.js';
+import { NodeWarnMessages, APIPathV1 } from './constants.js';
+import { Logger } from './logger.js';
+import { clearNcfgVersionMarker } from './nodeNcfgVersionHandler.js';
+
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const logger = new Logger("nodeUtils");
+/** Sorted subgroup IDs under this group that contain `nodeId`. */
+function collectSubgroupIdsForNode(group, nodeId) {
+    return group.subgroups
+        .filter((sg) => sg.nodeIds.includes(nodeId))
+        .map((sg) => sg.groupId)
+        .sort();
+}
+/** Read node config from local storage. Returns null on miss or corrupt data. */
+async function readLocalNodeConfig(nodeId) {
+    return ESPRMNeoStorage.getNodeConfig(nodeId);
+}
+/** Best-effort persist of node config to local storage. */
+async function writeLocalNodeConfig(nodeId, config) {
+    try {
+        await ESPRMNeoStorage.setNodeConfig(nodeId, config);
+    }
+    catch (error) {
+        logger.warn(`Cache write failed for ${nodeId}`, error);
+    }
+}
+/** Best-effort removal of node config from local storage. */
+async function removeLocalNodeConfig(nodeId) {
+    try {
+        await ESPRMNeoStorage.deleteNodeConfig(nodeId);
+    }
+    catch (error) {
+        logger.warn(NodeWarnMessages.NODE_CONFIG_CACHE_REMOVE_FAILED, {
+            nodeId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+/**
+ * Best-effort clear of the ncfg version marker.
+ * Safe even when the node remains associated to another group — the marker
+ * will re-baseline on the next shadow update.
+ */
+async function clearLocalNcfgVersionMarker(nodeId) {
+    try {
+        await clearNcfgVersionMarker(nodeId);
+    }
+    catch (error) {
+        logger.warn(NodeWarnMessages.NCFG_VERSION_MARKER_CLEAR_FAILED, {
+            nodeId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+/**
+ * Best-effort cleanup of local node config cache + ncfg version marker.
+ * Safe even when the node remains associated to another group.
+ */
+async function clearLocalNodeCache(nodeId) {
+    await removeLocalNodeConfig(nodeId);
+    await clearLocalNcfgVersionMarker(nodeId);
+}
+/**
+ * Fetch node config from the cloud.
+ *
+ * Config is always served on the root-group route — the subgroup variant
+ * (`…/subgroups/{sgid}/nodes/{nid}/config`) does not exist in the backend
+ * (verified against the backend source: the gateway defines only PUT/DELETE on
+ * subgroup nodes). Subgroup-scoped users still pass the access check here
+ * because the user↔group mapping is keyed on the root group id.
+ */
+async function fetchCloudNodeConfigForNode(groupId, nodeId) {
+    const path = APIPathV1.groupNodeConfig(groupId, nodeId);
+    return ESPSigV4APIManager.getInstance().get(path);
+}
+/** Fetch node config from the cloud and best-effort write it to local storage. */
+async function fetchCloudNodeConfig(group, nodeId) {
+    // Root-group id even for child groups — see fetchCloudNodeConfigForNode.
+    const rootGroupId = isChildGroup(group) ? group.parentId : group.groupId;
+    const config = await fetchCloudNodeConfigForNode(rootGroupId, nodeId);
+    await writeLocalNodeConfig(nodeId, config);
+    return config;
+}
+/** Wrap a resolved config in an ESPRMNeoNode for this group context. */
+function toNeoNode(group, config, nodeId) {
+    if (!config.node_id) {
+        config.node_id = nodeId;
+    }
+    if (isChildGroup(group)) {
+        return new ESPRMNeoNode(config, group.parentId, group.groupId);
+    }
+    return new ESPRMNeoNode(config, group.groupId, collectSubgroupIdsForNode(group, nodeId));
+}
+
+export { clearLocalNcfgVersionMarker, clearLocalNodeCache, collectSubgroupIdsForNode, fetchCloudNodeConfig, fetchCloudNodeConfigForNode, readLocalNodeConfig, removeLocalNodeConfig, toNeoNode, writeLocalNodeConfig };
+//# sourceMappingURL=nodeUtils.js.map

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

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

package/dist/esm/utils/normalizeApiResponse.js

@@ -0,0 +1,28 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+function asRecord(value) {
+    if (value === null || value === undefined || typeof value !== "object") {
+        return null;
+    }
+    return value;
+}
+/**
+ * Normalizes API success payloads to {@link SuccessResponse}.
+ * Expects `{ message }` from the backend or an empty body on success.
+ */
+function normalizeApiResponse(response, fallback = {}) {
+    const record = asRecord(response);
+    if (!record) {
+        return fallback;
+    }
+    if (typeof record.message === "string" && record.message.length > 0) {
+        return { message: record.message };
+    }
+    return fallback;
+}
+
+export { normalizeApiResponse };
+//# sourceMappingURL=normalizeApiResponse.js.map

package/dist/esm/utils/normalizeApiResponse.js.map

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

package/dist/esm/utils/paramValues.js

@@ -0,0 +1,54 @@
+import { asObject } from './common.js';
+
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Writes values from a map onto matching param instances.
+ * Params whose id is absent from the map are left unchanged.
+ */
+function applyValuesToParams(params, values) {
+    const map = asObject(values);
+    for (const p of params) {
+        if (Object.prototype.hasOwnProperty.call(map, p.id)) {
+            p.value = map[p.id];
+        }
+    }
+}
+/**
+ * Writes a params snapshot (`entityName → { paramId → value }`) onto matching
+ * device/service param instances.
+ */
+function applyParamValues(node, values) {
+    for (const [name, raw] of Object.entries(values)) {
+        const device = node.devices.find((d) => d.name === name);
+        if (device) {
+            applyValuesToParams(device.params, raw);
+            continue;
+        }
+        const service = node.services.find((s) => s.name === name);
+        if (service) {
+            applyValuesToParams(service.params, raw);
+        }
+    }
+}
+/**
+ * Deep-merges an incoming params map onto a previous one (per entity name).
+ * Partial updates (e.g. only `Switch.Power`) keep sibling entities/params.
+ */
+function mergeParamMaps(previous, incoming) {
+    const prev = asObject(previous);
+    const next = { ...prev };
+    for (const [name, raw] of Object.entries(incoming)) {
+        next[name] = {
+            ...asObject(prev[name]),
+            ...asObject(raw),
+        };
+    }
+    return next;
+}
+
+export { applyParamValues, applyValuesToParams, mergeParamMaps };
+//# sourceMappingURL=paramValues.js.map

package/dist/esm/utils/paramValues.js.map

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

package/dist/esm/utils/scheduleUtils.js

@@ -0,0 +1,38 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Fetches the current schedule list for a node as ScheduleItem[].
+ * Always hits the cloud — the schedules API is replace-all and has no
+ * version marker, so the SDK does not cache to avoid silent overwrites
+ * when another session edits the same list.
+ */
+async function getScheduleItemsForNode(node) {
+    const schedules = await node.getSchedules();
+    return schedules.map((s) => ({
+        id: s.id,
+        name: s.name,
+        enabled: s.enabled,
+        triggers: s.triggers,
+        action: s.action,
+        validity: s.validity,
+    }));
+}
+/**
+ * Converts an ESPRMNeoSchedule instance to ScheduleItem (for building payloads).
+ */
+function scheduleToItem(s) {
+    return {
+        id: s.id,
+        name: s.name,
+        enabled: s.enabled,
+        triggers: s.triggers,
+        action: s.action,
+        validity: s.validity,
+    };
+}
+
+export { getScheduleItemsForNode, scheduleToItem };
+//# sourceMappingURL=scheduleUtils.js.map