@espressif/rainmaker-neo-base-sdk 1.0.0

package/dist/cjs/utils/paramValues.js

@@ -0,0 +1,58 @@
+'use strict';
+
+var common = require('./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 = common.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 = common.asObject(previous);
+    const next = { ...prev };
+    for (const [name, raw] of Object.entries(incoming)) {
+        next[name] = {
+            ...common.asObject(prev[name]),
+            ...common.asObject(raw),
+        };
+    }
+    return next;
+}
+
+exports.applyParamValues = applyParamValues;
+exports.applyValuesToParams = applyValuesToParams;
+exports.mergeParamMaps = mergeParamMaps;
+//# sourceMappingURL=paramValues.js.map

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

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

package/dist/cjs/utils/scheduleUtils.js

@@ -0,0 +1,41 @@
+'use strict';
+
+/*
+ * 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,
+    };
+}
+
+exports.getScheduleItemsForNode = getScheduleItemsForNode;
+exports.scheduleToItem = scheduleToItem;
+//# sourceMappingURL=scheduleUtils.js.map

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

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

package/dist/cjs/utils/shadowUtils.js

@@ -0,0 +1,72 @@
+'use strict';
+
+var logger$1 = require('./logger.js');
+
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const logger = new logger$1.Logger("ShadowUtils");
+/**
+ * Constructs a shadow name based on group ID and subgroups
+ * @param groupId The group ID
+ * @param subgroups Array of subgroup IDs
+ * @returns The constructed shadow name
+ */
+function constructShadowName(groupId, subgroups = []) {
+    let shadowName = `params-${groupId}`;
+    if (subgroups.length > 0) {
+        const sortedSubgroups = [...subgroups].sort();
+        shadowName += `-${sortedSubgroups.join("-")}`;
+    }
+    return shadowName;
+}
+/**
+ * Constructs a shadow topic for a device
+ * @param nodeId The node ID
+ * @param groupId The group ID
+ * @param subgroups Array of subgroup IDs
+ * @returns The constructed shadow topic
+ */
+function constructShadowTopic(nodeId, groupId, subgroups) {
+    const shadowName = constructShadowName(groupId, subgroups);
+    return `$aws/things/${nodeId}/shadow/name/${shadowName}`;
+}
+/**
+ * Constructs a device parameters topic
+ * @param nodeId The node ID
+ * @param groupId The group ID
+ * @param subgroups Array of subgroup IDs
+ * @returns The constructed parameters topic
+ */
+function constructDeviceParamsTopic(nodeId, groupId, subgroups) {
+    const shadowName = constructShadowName(groupId, subgroups);
+    return `rainmaker/nodes/${nodeId}/user/${shadowName}/params`;
+}
+/**
+ * Generates a digest for parameters to detect changes
+ * @param params The parameters object
+ * @returns A digest string representing the parameters
+ */
+function generateParamsDigest(params) {
+    try {
+        const sortedParams = Object.keys(params)
+            .sort()
+            .reduce((result, key) => {
+            result[key] = params[key];
+            return result;
+        }, {});
+        return JSON.stringify(sortedParams);
+    }
+    catch (error) {
+        logger.error("Error generating params digest:", error);
+        return "";
+    }
+}
+
+exports.constructDeviceParamsTopic = constructDeviceParamsTopic;
+exports.constructShadowName = constructShadowName;
+exports.constructShadowTopic = constructShadowTopic;
+exports.generateParamsDigest = generateParamsDigest;
+//# sourceMappingURL=shadowUtils.js.map

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

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

package/dist/cjs/utils/triggerUtils.js

@@ -0,0 +1,60 @@
+'use strict';
+
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Converts a trigger-like object to TriggerItem (for building payloads).
+ */
+function triggerToItem(t) {
+    return {
+        id: t.id,
+        type: t.type,
+        enabled: t.enabled,
+        path: t.path,
+        operator: t.operator,
+        value: t.value,
+    };
+}
+/**
+ * Fetches the current trigger list for a node as TriggerItem[].
+ * Always hits the cloud — the triggers API is replace-all.
+ */
+async function getTriggerItemsForNode(node) {
+    const triggers = await node.getTriggers();
+    return triggers.map((t) => triggerToItem(t));
+}
+/**
+ * Merges defined update fields onto a base TriggerItem without writing
+ * `undefined` over existing values.
+ */
+function mergeTriggerItem(base, updates) {
+    return {
+        ...base,
+        ...(updates.path !== undefined ? { path: updates.path } : {}),
+        ...(updates.enabled !== undefined ? { enabled: updates.enabled } : {}),
+        ...(updates.operator !== undefined ? { operator: updates.operator } : {}),
+        ...(updates.value !== undefined ? { value: updates.value } : {}),
+    };
+}
+/**
+ * Copies defined update fields onto a live trigger instance.
+ */
+function applyTriggerUpdates(target, updates) {
+    if (updates.path !== undefined)
+        target.path = updates.path;
+    if (updates.enabled !== undefined)
+        target.enabled = updates.enabled;
+    if (updates.operator !== undefined)
+        target.operator = updates.operator;
+    if (updates.value !== undefined)
+        target.value = updates.value;
+}
+
+exports.applyTriggerUpdates = applyTriggerUpdates;
+exports.getTriggerItemsForNode = getTriggerItemsForNode;
+exports.mergeTriggerItem = mergeTriggerItem;
+exports.triggerToItem = triggerToItem;
+//# sourceMappingURL=triggerUtils.js.map

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

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

package/dist/cjs/utils/tsDataUtils.js

@@ -0,0 +1,165 @@
+'use strict';
+
+var constants = require('./constants.js');
+var ESPAPICallValidationError = require('./error/ESPAPICallValidationError.js');
+var logger$1 = require('./logger.js');
+
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const logger = new logger$1.Logger("TSDataUtils");
+/** Param property flag marking a param as time-series capable (node config). */
+const TIME_SERIES_PROPERTY = "time_series";
+const AGGREGATION_WINDOWS = [
+    "hourly",
+    "daily",
+    "weekly",
+    "monthly",
+];
+/**
+ * Returns the explicit query identity from options when the caller provided
+ * one, bypassing any node-config lookup. This is the escape hatch for data
+ * models the default lookup cannot resolve (e.g. Matter attributes).
+ *
+ * @throws {ESPAPICallValidationError} If `options.key` is set without `options.dataType`.
+ */
+function tsParamIdentityFromOptions(options) {
+    if (!options?.key)
+        return undefined;
+    if (!options.dataType) {
+        throw new ESPAPICallValidationError.ESPAPICallValidationError(constants.APICallValidationErrorCodes.MISSING_TS_CUSTOM_KEY_DATA_TYPE);
+    }
+    return { key: options.key, dataType: options.dataType };
+}
+/**
+ * Builds the backend query identity from a device param's own metadata
+ * (used by the param-level methods, where `this` IS the param).
+ *
+ * @throws {ESPAPICallValidationError} If no data type can be determined.
+ */
+function tsParamIdentityFromParam(param, options) {
+    const explicit = tsParamIdentityFromOptions(options);
+    if (explicit)
+        return explicit;
+    const key = `${param.deviceName}.${param.id}`;
+    if (!param.properties?.includes(TIME_SERIES_PROPERTY)) {
+        logger.warn(`Param "${key}" does not declare the "${TIME_SERIES_PROPERTY}" property; the backend may have no data for it`);
+    }
+    const dataType = options?.dataType ?? param.dataType;
+    if (!dataType) {
+        logger.error(`Param "${key}" has no data_type`);
+        throw new ESPAPICallValidationError.ESPAPICallValidationError(constants.APICallValidationErrorCodes.MISSING_TS_DATA_TYPE);
+    }
+    return { key, dataType };
+}
+/**
+ * Resolves the backend query identity for a device param by looking it up in
+ * the node's config (used by the node-level methods).
+ *
+ * @throws {ESPAPICallValidationError} If the param is not found on the node's config.
+ */
+function resolveTSParamIdentity(node, deviceName, paramId, options) {
+    const explicit = tsParamIdentityFromOptions(options);
+    if (explicit)
+        return explicit;
+    const device = node.devices?.find((d) => d.name === deviceName);
+    const param = device?.params?.find((p) => p.id === paramId);
+    if (!param) {
+        logger.error(`Param "${paramId}" not found on device "${deviceName}" of node "${node.nodeId}"`);
+        throw new ESPAPICallValidationError.ESPAPICallValidationError(constants.APICallValidationErrorCodes.TS_PARAM_NOT_FOUND);
+    }
+    return tsParamIdentityFromParam(param, options);
+}
+/**
+ * Resolves the aggregation window from options.
+ *
+ * @throws {ESPAPICallValidationError} If no valid window is provided.
+ */
+function resolveTSWindow(options) {
+    const candidate = options?.window;
+    if (typeof candidate === "string" &&
+        AGGREGATION_WINDOWS.includes(candidate)) {
+        return candidate;
+    }
+    throw new ESPAPICallValidationError.ESPAPICallValidationError(constants.APICallValidationErrorCodes.INVALID_TS_WINDOW);
+}
+/**
+ * Builds a URL query string from the given params, skipping undefined values.
+ */
+function buildTSQueryString(params) {
+    const parts = [];
+    for (const [name, value] of Object.entries(params)) {
+        if (value === undefined)
+            continue;
+        parts.push(`${encodeURIComponent(name)}=${encodeURIComponent(String(value))}`);
+    }
+    return parts.join("&");
+}
+/**
+ * Maps a raw API sample into an {@link ESPRMNeoTSDataPoint}.
+ * The backend emits `key`; older swagger examples show `name` — both accepted.
+ */
+function transformTSDataPoint(point) {
+    return {
+        timestamp: point.ts,
+        value: point.value,
+        dataType: point.dt,
+        timezone: point.tz,
+        cumulative: point.cumulative,
+    };
+}
+function transformTSWindowAggregate(aggregate) {
+    const { first_value: firstValue, last_value: lastValue, cumulative_value: cumulativeValue, window_start: windowStart, window_end: windowEnd, ...rest } = aggregate;
+    return {
+        ...rest,
+        firstValue,
+        lastValue,
+        cumulativeValue,
+        windowStart,
+        windowEnd,
+    };
+}
+/**
+ * Maps a raw API aggregate entry into an {@link ESPRMNeoTSAggregateEntry}.
+ *
+ * The backend emits two entry shapes:
+ * - **Nested** (`windows: {hourly: {...}, ...}`) — only the current-aggregates
+ *   query with no `window` param (all windows at once).
+ * - **Flat** — historical `date`/`start_date`+`end_date` queries and the
+ *   current-single-window query put the stats directly on the entry
+ *   (`{date, window_start, count, average, ...}`), with no `windows` map.
+ *
+ * Flat entries are nested under `requestedWindow` so consumers always read
+ * `entry.windows[window]` regardless of query mode.
+ */
+function transformTSAggregateEntry(entry, requestedWindow) {
+    const { is_cumulative: isCumulative, windows: rawWindows, ...rest } = entry;
+    const windows = {};
+    if (rawWindows && Object.keys(rawWindows).length > 0) {
+        for (const [windowName, aggregate] of Object.entries(rawWindows)) {
+            windows[windowName] =
+                transformTSWindowAggregate(aggregate);
+        }
+        return { ...rest, isCumulative, windows };
+    }
+    if (requestedWindow) {
+        // Flat entry: everything except the entry-level identity fields is the
+        // window's stat set.
+        const { date, parameter, ...flatStats } = rest;
+        windows[requestedWindow] = transformTSWindowAggregate(flatStats);
+        return { date, parameter, isCumulative, windows };
+    }
+    return { ...rest, isCumulative, windows };
+}
+
+exports.TIME_SERIES_PROPERTY = TIME_SERIES_PROPERTY;
+exports.buildTSQueryString = buildTSQueryString;
+exports.resolveTSParamIdentity = resolveTSParamIdentity;
+exports.resolveTSWindow = resolveTSWindow;
+exports.transformTSAggregateEntry = transformTSAggregateEntry;
+exports.transformTSDataPoint = transformTSDataPoint;
+exports.tsParamIdentityFromOptions = tsParamIdentityFromOptions;
+exports.tsParamIdentityFromParam = tsParamIdentityFromParam;
+//# sourceMappingURL=tsDataUtils.js.map

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

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

package/dist/cjs/utils/userUtils.js

@@ -0,0 +1,60 @@
+'use strict';
+
+var ESPRMNeoStorage = require('../services/ESPRMNeoStorage/ESPRMNeoStorage.js');
+var ESPRMNeoAPIManager = require('../services/ESPRMNeoAPIManager.js');
+var constants = require('./constants.js');
+var nodeNcfgVersionHandler = require('./nodeNcfgVersionHandler.js');
+var logger$1 = require('./logger.js');
+
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const logger = new logger$1.Logger("userUtils");
+function errorDetail(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** Runs an action without letting failures abort the caller. */
+async function failSafe(step, action) {
+    try {
+        await action();
+        logger.debug(`${step} succeeded`);
+    }
+    catch (error) {
+        logger.warn(`${step} failed`, { error: errorDetail(error) });
+    }
+}
+/** Best-effort `POST /v1/user/auth/signout` when an access token is present. */
+async function invalidateServerSession() {
+    const accessToken = (await ESPRMNeoStorage.ESPRMNeoStorage.getItem(constants.StorageKeys.ACCESSTOKEN)) || undefined;
+    if (!accessToken) {
+        logger.debug("Skipping server signout: no access token");
+        return;
+    }
+    const refreshToken = (await ESPRMNeoStorage.ESPRMNeoStorage.getItem(constants.StorageKeys.REFRESHTOKEN)) || undefined;
+    const requestBody = refreshToken
+        ? { refresh_token: refreshToken }
+        : undefined;
+    await ESPRMNeoAPIManager.ESPRMNeoAPIManager.getInstance().postUserApiWithBearer(constants.APIPathV1.USER_AUTH_SIGNOUT, requestBody, accessToken);
+}
+/** Removes access, id, and refresh tokens from storage. */
+async function clearTokens() {
+    await ESPRMNeoStorage.ESPRMNeoStorage.removeItem(constants.StorageKeys.ACCESSTOKEN);
+    await ESPRMNeoStorage.ESPRMNeoStorage.removeItem(constants.StorageKeys.IDTOKEN);
+    await ESPRMNeoStorage.ESPRMNeoStorage.removeItem(constants.StorageKeys.REFRESHTOKEN);
+}
+/**
+ * Clears ncfg version markers and every cached node config they referenced.
+ */
+async function clearNodeConfigCache() {
+    const trackedNodeIds = await nodeNcfgVersionHandler.clearAllNcfgVersionMarkers();
+    await Promise.all(trackedNodeIds.map((nodeId) => ESPRMNeoStorage.ESPRMNeoStorage.removeItem(constants.StorageKeys.NODE_CONFIG_PREFIX + nodeId).catch(() => undefined)));
+}
+
+exports.clearNodeConfigCache = clearNodeConfigCache;
+exports.clearTokens = clearTokens;
+exports.errorDetail = errorDetail;
+exports.failSafe = failSafe;
+exports.invalidateServerSession = invalidateServerSession;
+//# sourceMappingURL=userUtils.js.map

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

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