@espressif/rainmaker-neo-base-sdk 1.0.0

package/dist/cjs/services/ESPRMNeoHelpers/ChannelRegistration.js

@@ -0,0 +1,49 @@
+'use strict';
+
+var MQTTSubscriptionChannel = require('../MQTTSubscriptionChannel.js');
+var constants = require('../../utils/constants.js');
+var logger$1 = require('../../utils/logger.js');
+
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const logger = new logger$1.Logger("ChannelRegistration");
+/**
+ * Registers the MQTT subscription channel with the manager (idempotent) and,
+ * if no global order has been set yet, makes MQTT the default channel.
+ *
+ * This runs **synchronously** on purpose: `registerChannel` adds the channel to
+ * the manager's map before its first `await`, so by the time this function sets
+ * the global order the channel is already present. Doing it synchronously avoids
+ * the order-clobber race that consumer apps had to defend against (where an
+ * async registration reset the channel order after the app had configured it).
+ *
+ * @param manager - The subscription manager to register the MQTT channel on.
+ */
+function registerMqttChannelIfNeeded(manager) {
+    if (!manager.getRegisteredChannels().includes(constants.SubscriptionChannelIds.MQTT)) {
+        // registerChannel() updates the channel map synchronously; the returned
+        // promise only awaits channel.initialize() when the manager is already
+        // initialized. We don't await it here so the order can be set synchronously.
+        manager
+            .registerChannel(new MQTTSubscriptionChannel.MQTTSubscriptionChannel())
+            .catch((error) => logger.error("Failed to register MQTT subscription channel", error));
+    }
+    if (manager.getGlobalChannelOrder().length === 0) {
+        manager.setGlobalChannelOrder([constants.SubscriptionChannelIds.MQTT]);
+    }
+    // Drive the manager lifecycle: initialize the registered channel(s) and flip
+    // the manager's `initialized` flag. Without this, `registerChannel`'s
+    // `autoInitialize` gate never fires, so a channel registered later by a
+    // satellite SDK (Matter/BLE) would be left un-initialized (its connection /
+    // cache warmup silently skipped). The MQTT channel's own lazy-init in
+    // subscribe() is kept as a defensive fallback.
+    void manager
+        .initialize()
+        .catch((error) => logger.error("Failed to initialize subscription manager", error));
+}
+
+exports.registerMqttChannelIfNeeded = registerMqttChannelIfNeeded;
+//# sourceMappingURL=ChannelRegistration.js.map

package/dist/cjs/services/ESPRMNeoHelpers/ChannelRegistration.js.map

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

package/dist/cjs/services/ESPRMNeoHelpers/CheckTokenExpiry.js

@@ -0,0 +1,25 @@
+'use strict';
+
+var DecodeToken = require('./DecodeToken.js');
+var GetCurrentTimestamp = require('./GetCurrentTimestamp.js');
+
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Checks if the given token has expired.
+ *
+ * @param token - The token to check.
+ * @returns True if the token has expired, false otherwise.
+ */
+const isTokenExpired = (token) => {
+    const tokenPayload = DecodeToken.decodeToken(token);
+    const tokenExpiryTimestamp = tokenPayload.exp;
+    const currentTimestamp = GetCurrentTimestamp.getCurrentTimestamp();
+    return currentTimestamp >= tokenExpiryTimestamp;
+};
+
+exports.isTokenExpired = isTokenExpired;
+//# sourceMappingURL=CheckTokenExpiry.js.map

package/dist/cjs/services/ESPRMNeoHelpers/CheckTokenExpiry.js.map

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

package/dist/cjs/services/ESPRMNeoHelpers/ClaimingHelper.js

@@ -0,0 +1,221 @@
+'use strict';
+
+var ESPRMNeoBase = require('../../ESPRMNeoBase.js');
+var ESPSigV4APIManager = require('../ESPSigV4APIManager.js');
+var constants = require('../../utils/constants.js');
+var ESPClaimError = require('../../utils/error/ESPClaimError.js');
+var logger$1 = require('../../utils/logger.js');
+
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const logger = new logger$1.Logger("ClaimingHelper");
+/**
+ * Assisted-claiming cloud calls.
+ *
+ * Both routes live on the deployment's main API and are IAM-authorized like their
+ * neighbours, so they go through {@link ESPSigV4APIManager} and are SigV4-signed
+ * against `baseUrl`. A Cognito JWT is rejected there with
+ * `403 Invalid key=value pair (missing equal-sign) in Authorization header`.
+ *
+ * Both calls are independently retryable: initiate is idempotent per device and
+ * caller, and verify replaces the device's certificate rather than duplicating
+ * the node.
+ */
+class ClaimingHelper {
+    /**
+     * Normalizes a device MAC: separators stripped and upper-cased, so every
+     * spelling of one address resolves to the same reservation.
+     *
+     * @param raw - MAC as reported by the device
+     * @returns Normalized MAC
+     * @throws ESPClaimError when the value is not 12 or 16 hex characters
+     */
+    static normalizeMacAddress(raw) {
+        const mac = raw.trim().replace(constants.CLAIM_MAC_SEPARATORS, "").toUpperCase();
+        const isHex = /^[0-9A-F]+$/.test(mac);
+        const hasValidLength = constants.CLAIM_MAC_HEX_LENGTHS.includes(mac.length);
+        if (!isHex || !hasValidLength) {
+            logger.error("device MAC is not a valid claiming MAC", {
+                length: mac.length,
+                isHex,
+            });
+            throw new ESPClaimError.ESPClaimError(constants.ClaimErrorCodes.DEVICE_MAC_UNAVAILABLE);
+        }
+        return mac;
+    }
+    /**
+     * Reduces a broker endpoint to the bare host the device stores. The device
+     * keeps host and port separately, so a scheme, path or `:port` would be
+     * persisted verbatim into the factory partition and fail to resolve.
+     *
+     * @param raw - Broker endpoint in any form
+     * @returns Host only, or "" when nothing usable remains
+     */
+    static normalizeMqttHost(raw) {
+        return raw
+            .trim()
+            .replace(/^[a-z][a-z0-9+.-]*:\/\//i, "") // scheme
+            .replace(/\/.*$/, "") // path
+            .replace(/:\d+$/, "") // port
+            .trim();
+    }
+    /**
+     * Issues a SigV4-signed claiming POST. Signing, credential refresh and retry
+     * come from {@link ESPSigV4APIManager}, which also attaches a failed call's
+     * `{ message }` body to the thrown error as `responseData`.
+     *
+     * @param path - Claiming path, e.g. `/v1/claim/initiate`
+     * @param body - JSON request body
+     * @param claimId - Correlation id for this claim attempt
+     * @returns Parsed JSON response
+     * @throws ESPClaimError when the SDK is unconfigured or the call fails
+     */
+    static async postClaim(path, body, claimId) {
+        let api;
+        try {
+            api = ESPSigV4APIManager.ESPSigV4APIManager.getInstance();
+        }
+        catch {
+            logger.error("claiming unavailable: SDK is not configured", { claimId });
+            throw new ESPClaimError.ESPClaimError(constants.ClaimErrorCodes.CLAIM_API_NOT_CONFIGURED);
+        }
+        try {
+            return await api.post(path, body);
+        }
+        catch (error) {
+            const failure = error;
+            const message = failure.responseData?.message;
+            const reason = typeof message === "string" && message.trim()
+                ? message.trim()
+                : error instanceof Error
+                    ? error.message
+                    : String(error);
+            logger.error("claim request failed", {
+                claimId,
+                path,
+                httpStatus: failure.status,
+                reason,
+            });
+            throw new ESPClaimError.ESPClaimError(constants.ClaimErrorCodes.CLAIM_API_FAILED, failure.status ? `HTTP ${failure.status}: ${reason}` : reason);
+        }
+    }
+    /**
+     * Assigns a node ID to the device's MAC address.
+     *
+     * `POST /v1/claim/initiate` — 201 for a new reservation, 200 when one already
+     * existed, returning the same node ID either way. That idempotency is what lets
+     * a factory-erased device come back as the same node.
+     *
+     * @param macAddress - Device MAC, normalized before sending
+     * @param devicePayload - The device's claim-start payload, forwarded whole
+     * @param claimId - Correlation id for this claim attempt
+     * @returns The assigned node ID and any attestation challenge
+     * @throws ESPClaimError when the MAC is invalid or the call fails
+     */
+    static async initiateClaim(macAddress, devicePayload = {}, claimId = "") {
+        const request = {
+            ...devicePayload,
+            // Last, so a raw MAC in the device payload cannot shadow the normalized one.
+            mac_addr: this.normalizeMacAddress(macAddress),
+        };
+        const response = await this.postClaim(constants.ClaimEndpoints.CLAIM_INITIATE, request, claimId);
+        if (!response?.node_id) {
+            logger.error("claim initiate returned no node_id", { claimId });
+            throw new ESPClaimError.ESPClaimError(constants.ClaimErrorCodes.CLAIM_API_FAILED, "response contained no node_id");
+        }
+        return response;
+    }
+    /**
+     * Exchanges the device's CSR for a signed certificate.
+     *
+     * `POST /v1/claim/verify` — the CSR's subject is ignored; the certificate's
+     * Common Name comes from the reservation. Called again after a factory erase, it
+     * issues a new certificate and deactivates the previous one, node ID unchanged.
+     *
+     * @param macAddress - Same device MAC as initiate
+     * @param devicePayload - The device's claim payload, forwarded whole
+     * @param claimCapability - Optional capability, mapped to extra IoT policies
+     * @param claimId - Correlation id for this claim attempt
+     * @returns The claim response, with `mqtt_host` resolved for the device
+     * @throws ESPClaimError when the call fails or no certificate is returned
+     */
+    static async verifyClaim(macAddress, devicePayload, claimCapability, claimId = "") {
+        const request = {
+            ...devicePayload,
+            // Last, so a raw MAC in the device payload cannot shadow the normalized one.
+            mac_addr: this.normalizeMacAddress(macAddress),
+        };
+        const policies = claimCapability
+            ? constants.ClaimCapabilityPolicies[claimCapability]
+            : undefined;
+        if (policies?.length) {
+            request.capabilities = [...policies];
+        }
+        else if (claimCapability) {
+            // Omitted rather than guessed — see ClaimCapabilityPolicies.
+            logger.warn("claim capability has no mapped IoT policies; sending none", {
+                claimId,
+                claimCapability,
+            });
+        }
+        const response = await this.postClaim(constants.ClaimEndpoints.CLAIM_VERIFY, request, claimId);
+        if (!response?.certificate) {
+            logger.error("claim verify returned no certificate", {
+                claimId,
+                received: response ? Object.keys(response) : null,
+            });
+            throw new ESPClaimError.ESPClaimError(constants.ClaimErrorCodes.CLAIM_API_FAILED, "response is missing certificate");
+        }
+        return {
+            ...response,
+            mqtt_host: this.resolveDeviceMqttHost(response, claimId),
+        };
+    }
+    /**
+     * Resolves the broker host to hand the device, normalized to a bare host.
+     *
+     * The app owns this value: the claiming service omits it because the app
+     * already learned the deployment's broker from its config, so the configured
+     * `iotEndpoint` is the normal source and is correct by construction — it is the
+     * broker of the deployment that just issued this certificate. A `mqtt_host` in
+     * the response still wins if one is ever sent.
+     *
+     * Resolved before streaming because the device validates the reassembled
+     * payload only on its final fragment: an absent host surfaces there as a
+     * rejected certificate fragment, with nothing pointing at MQTT.
+     *
+     * @param response - Parsed claim/verify response
+     * @param claimId - Correlation id for this claim attempt
+     * @returns Bare broker host
+     * @throws ESPClaimError when neither source yields a usable host
+     */
+    static resolveDeviceMqttHost(response, claimId) {
+        const fromService = this.normalizeMqttHost(response.mqtt_host ?? "");
+        if (fromService) {
+            return fromService;
+        }
+        let configured;
+        try {
+            configured = ESPRMNeoBase.ESPRMNeoBase.getConfig().iotEndpoint;
+        }
+        catch {
+            configured = undefined;
+        }
+        const fromConfig = this.normalizeMqttHost(configured ?? "");
+        if (!fromConfig) {
+            logger.error("no mqtt_host for the device", {
+                claimId,
+                fromResponse: response.mqtt_host ?? null,
+                configuredIotEndpoint: configured ?? null,
+            });
+            throw new ESPClaimError.ESPClaimError(constants.ClaimErrorCodes.CLAIM_API_FAILED, "no mqtt_host available: the claim response omitted it and no iotEndpoint is configured");
+        }
+        return fromConfig;
+    }
+}
+
+exports.ClaimingHelper = ClaimingHelper;
+//# sourceMappingURL=ClaimingHelper.js.map

package/dist/cjs/services/ESPRMNeoHelpers/ClaimingHelper.js.map

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

package/dist/cjs/services/ESPRMNeoHelpers/DecodeToken.js

@@ -0,0 +1,52 @@
+'use strict';
+
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Converts a base64url string to standard base64 (adds padding and replaces
+ * URL-safe characters). JWT segments use base64url per RFC 7519.
+ */
+function base64UrlToBase64(s) {
+    const swapped = s.replace(/-/g, "+").replace(/_/g, "/");
+    const padding = (4 - (swapped.length % 4)) % 4;
+    return swapped + "=".repeat(padding);
+}
+/**
+ * Decodes a JWT and returns the payload (middle segment) as a parsed object.
+ * Uses base64url decoding per RFC 7519 and UTF-8 decoding so non-ASCII fields
+ * (e.g. unicode usernames) round-trip correctly.
+ *
+ * @param token - The JWT to decode.
+ * @returns The decoded payload object.
+ * @throws Error with a clear message if the token is malformed, non-base64url,
+ *   or the payload is not valid JSON.
+ */
+const decodeToken = (token) => {
+    if (typeof token !== "string" || token.length === 0) {
+        throw new Error("decodeToken: token must be a non-empty string");
+    }
+    const parts = token.split(".");
+    if (parts.length < 2) {
+        throw new Error("decodeToken: token is not a valid JWT (expected three '.'-separated segments)");
+    }
+    try {
+        const base64 = base64UrlToBase64(parts[1]);
+        const binary = atob(base64);
+        const bytes = new Uint8Array(binary.length);
+        for (let i = 0; i < binary.length; i++) {
+            bytes[i] = binary.charCodeAt(i);
+        }
+        const json = new TextDecoder().decode(bytes);
+        return JSON.parse(json);
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new Error(`decodeToken: failed to decode payload — ${detail}`);
+    }
+};
+
+exports.decodeToken = decodeToken;
+//# sourceMappingURL=DecodeToken.js.map

package/dist/cjs/services/ESPRMNeoHelpers/DecodeToken.js.map

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

package/dist/cjs/services/ESPRMNeoHelpers/DelegatedTransportHandler.js

@@ -0,0 +1,132 @@
+'use strict';
+
+var ESPTransportManager = require('../ESPTransport/ESPTransportManager.js');
+var transport = require('../../types/transport.js');
+var constants = require('../../utils/constants.js');
+var coerce = require('../../utils/coerce.js');
+var ESPAPICallValidationError = require('../../utils/error/ESPAPICallValidationError.js');
+
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Resolves the param ID for a given param type within a service's param list.
+ * Returns `undefined` when no param with that type is registered.
+ */
+function resolveParamId(serviceParams, paramType) {
+    return serviceParams.find((p) => p.type === paramType)?.id;
+}
+/**
+ * Reads the local-control credentials directly from the node's
+ * local-control service param values.
+ */
+function readLocalControlCreds(node) {
+    const service = node.services.find((s) => s.type === constants.ESPServiceType.LOCAL_CONTROL);
+    if (!service)
+        return {};
+    const readCred = (paramType) => {
+        const paramId = resolveParamId(service.params, paramType);
+        return paramId !== undefined
+            ? service.params.find((p) => p.id === paramId)?.value
+            : undefined;
+    };
+    const securityType = coerce.coerceToFiniteNumber(readCred(constants.ESPServiceParamType.LOCAL_CONTROL.TYPE));
+    const pop = coerce.coerceToNonEmptyString(readCred(constants.ESPServiceParamType.LOCAL_CONTROL.POP));
+    const username = coerce.coerceToNonEmptyString(readCred(constants.ESPServiceParamType.LOCAL_CONTROL.USERNAME));
+    return {
+        ...(securityType !== undefined && { securityType }),
+        ...(pop !== undefined && { pop }),
+        ...(username !== undefined && { username }),
+    };
+}
+/**
+ * Builds the transport config for the `local` control transport: validates that
+ * a `baseUrl` is known and enriches the metadata with the node's on-demand
+ * credentials — `securityType` for all schemes, `pop` for sec1/sec2, and
+ * additionally `username` for sec2. Returns a new config (does not mutate the
+ * node's stored `availableTransports`).
+ *
+ * @throws {ESPAPICallValidationError} `MISSING_BASE_URL` when no baseUrl is set;
+ *   the caller treats this like any transport failure and tries the next mode.
+ */
+function buildLocalControlConfig(node, config) {
+    if (!config.metadata?.baseUrl) {
+        throw new ESPAPICallValidationError.ESPAPICallValidationError(constants.APICallValidationErrorCodes.MISSING_BASE_URL);
+    }
+    const creds = readLocalControlCreds(node);
+    const metadata = {
+        ...config.metadata,
+        securityType: creds.securityType ?? 0,
+    };
+    if (creds.securityType === 1 || creds.securityType === 2) {
+        metadata.pop = creds.pop;
+    }
+    // sec2 additionally authenticates with a username (SRP6a salt/verifier).
+    if (creds.securityType === 2) {
+        metadata.username = creds.username;
+    }
+    return { ...config, metadata };
+}
+/**
+ * Drives a transport operation over the best available transport for a node.
+ *
+ * Iterates the node's {@link ESPRMNeoNode.transportOrder} and, for each mode
+ * present in {@link ESPRMNeoNode.availableTransports}:
+ *  1. For the `local` mode, validates a `baseUrl` is known and enriches the
+ *     transport config metadata with the node's `securityType`/`pop`/`username`.
+ *  2. Uses a registered custom transport manager for that mode if one exists;
+ *     otherwise constructs the built-in {@link ESPTransportManager}.
+ *  3. Runs the supplied `operation` against the transport. The first success
+ *     wins; failures fall through to the next mode in the order.
+ *
+ * Must be invoked bound to a node, e.g.
+ * `delegatedTransportHandler.call(node, (m) => m.setParam(payload, node))`.
+ *
+ * @typeParam T - Result type of the transport operation.
+ * @param operation - Callback receiving the selected transport.
+ * @returns The operation result from the first successful transport.
+ * @throws {ESPAPICallValidationError} `NODE_UNREACHABLE` if no transport is
+ *   configured/available, or the last transport error if all attempts fail.
+ */
+const delegatedTransportHandler = async function (operation) {
+    const order = this.transportOrder?.length
+        ? this.transportOrder
+        : [transport.ESPTransportMode.local, transport.ESPTransportMode.mqtt];
+    const available = this.availableTransports ?? {};
+    if (order.length === 0 || Object.keys(available).length === 0) {
+        throw new ESPAPICallValidationError.ESPAPICallValidationError(constants.APICallValidationErrorCodes.NODE_UNREACHABLE);
+    }
+    let errorInstance;
+    let success = false;
+    let result;
+    for (const transportMode of order) {
+        const config = available[transportMode];
+        if (!config)
+            continue;
+        const customManager = this.customTransportManagers?.[transportMode];
+        try {
+            // The local transport needs connection metadata (baseUrl from mDNS;
+            // securityType/pop read on-demand from the node) before it can be used.
+            const transportConfig = transportMode === transport.ESPTransportMode.local
+                ? buildLocalControlConfig(this, config)
+                : config;
+            const manager = customManager ?? new ESPTransportManager.ESPTransportManager(transportConfig);
+            result = await operation(manager);
+            success = true;
+            break;
+        }
+        catch (error) {
+            errorInstance = error;
+        }
+    }
+    if (!success) {
+        throw (errorInstance ??
+            new ESPAPICallValidationError.ESPAPICallValidationError(constants.APICallValidationErrorCodes.NODE_UNREACHABLE));
+    }
+    return result;
+};
+
+exports.delegatedTransportHandler = delegatedTransportHandler;
+//# sourceMappingURL=DelegatedTransportHandler.js.map

package/dist/cjs/services/ESPRMNeoHelpers/DelegatedTransportHandler.js.map

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

package/dist/cjs/services/ESPRMNeoHelpers/FetchTSData.js

@@ -0,0 +1,137 @@
+'use strict';
+
+var ESPSigV4APIManager = require('../ESPSigV4APIManager.js');
+var constants = require('../../utils/constants.js');
+var ESPAPICallValidationError = require('../../utils/error/ESPAPICallValidationError.js');
+var logger$1 = require('../../utils/logger.js');
+var tsDataUtils = require('../../utils/tsDataUtils.js');
+
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const logger = new logger$1.Logger("FetchTSData");
+/**
+ * Fetches raw time-series samples (newest first) from
+ * `GET /v1/groups/{groupId}/nodes/{nodeId}/timeseries/raw`.
+ * `options.startTs` (Unix ms) is required; `endTs` defaults to now.
+ * When more pages exist the result carries `hasNext: true` and a
+ * `fetchNext()` closure that resolves the next page.
+ */
+const fetchRawTSData = async (config, startKeyParam) => {
+    const { options } = config;
+    if (options?.startTs === undefined) {
+        throw new ESPAPICallValidationError.ESPAPICallValidationError(constants.APICallValidationErrorCodes.MISSING_TS_START_TIME);
+    }
+    const query = tsDataUtils.buildTSQueryString({
+        key: config.key,
+        data_type: config.dataType,
+        start_time: options.startTs,
+        end_time: options.endTs,
+        page_size: options.pageSize,
+        start_key: startKeyParam ?? options.startKey,
+    });
+    const endpoint = `${constants.APIPathV1.groupNodeTimeseriesRaw(config.groupId, config.nodeId)}?${query}`;
+    try {
+        const response = await ESPSigV4APIManager.ESPSigV4APIManager.getInstance().get(endpoint);
+        const nextKey = response?.next_key;
+        const result = {
+            data: (response?.data ?? []).map(tsDataUtils.transformTSDataPoint),
+            nextKey,
+            pageTotal: response?.page_total,
+            hasNext: !!nextKey,
+        };
+        if (nextKey) {
+            result.fetchNext = () => fetchRawTSData(config, nextKey);
+        }
+        return result;
+    }
+    catch (error) {
+        logger.error("Failed to get raw time-series data", {
+            nodeId: config.nodeId,
+            key: config.key,
+            error,
+        });
+        throw error;
+    }
+};
+/**
+ * Fetches the most recent time-series sample from
+ * `GET /v1/groups/{groupId}/nodes/{nodeId}/timeseries/latest`.
+ * Returns at most one point in `data` (empty when the param has no samples).
+ */
+const fetchLatestTSData = async (config) => {
+    const query = tsDataUtils.buildTSQueryString({
+        key: config.key,
+        data_type: config.dataType,
+    });
+    const endpoint = `${constants.APIPathV1.groupNodeTimeseriesLatest(config.groupId, config.nodeId)}?${query}`;
+    try {
+        const response = await ESPSigV4APIManager.ESPSigV4APIManager.getInstance().get(endpoint);
+        // Unlike /raw, the /latest endpoint returns `data` as a single object.
+        return {
+            data: response?.data ? [tsDataUtils.transformTSDataPoint(response.data)] : [],
+            hasNext: false,
+        };
+    }
+    catch (error) {
+        logger.error("Failed to get latest time-series data", {
+            nodeId: config.nodeId,
+            key: config.key,
+            error,
+        });
+        throw error;
+    }
+};
+/**
+ * Fetches windowed aggregates from
+ * `GET /v1/groups/{groupId}/nodes/{nodeId}/timeseries/aggregates`.
+ * `options.window` is required. Provide no date (current live window),
+ * `date` (one completed window), or `startDate`/`endDate` (paginated range —
+ * `hasNext`/`fetchNext()` cover the following pages).
+ */
+const fetchAggregatedTSData = async (config, startKeyParam) => {
+    const { options } = config;
+    const window = tsDataUtils.resolveTSWindow(options);
+    const query = tsDataUtils.buildTSQueryString({
+        key: config.key,
+        data_type: config.dataType,
+        window,
+        date: options?.date,
+        start_date: options?.startDate,
+        end_date: options?.endDate,
+        page_size: options?.pageSize,
+        start_key: startKeyParam ?? options?.startKey,
+    });
+    const endpoint = `${constants.APIPathV1.groupNodeTimeseriesAggregates(config.groupId, config.nodeId)}?${query}`;
+    try {
+        const response = await ESPSigV4APIManager.ESPSigV4APIManager.getInstance().get(endpoint);
+        const nextKey = response?.next_key;
+        const result = {
+            data: [],
+            aggregates: (response?.aggregates ?? []).map((entry) => tsDataUtils.transformTSAggregateEntry(entry, window)),
+            nextKey,
+            pageTotal: response?.page_total,
+            hasNext: !!nextKey,
+        };
+        if (nextKey) {
+            result.fetchNext = () => fetchAggregatedTSData(config, nextKey);
+        }
+        return result;
+    }
+    catch (error) {
+        logger.error("Failed to get aggregated time-series data", {
+            nodeId: config.nodeId,
+            key: config.key,
+            window,
+            error,
+        });
+        throw error;
+    }
+};
+
+exports.fetchAggregatedTSData = fetchAggregatedTSData;
+exports.fetchLatestTSData = fetchLatestTSData;
+exports.fetchRawTSData = fetchRawTSData;
+//# sourceMappingURL=FetchTSData.js.map

package/dist/cjs/services/ESPRMNeoHelpers/FetchTSData.js.map

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

package/dist/cjs/services/ESPRMNeoHelpers/GetCurrentTimestamp.js

@@ -0,0 +1,18 @@
+'use strict';
+
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Gets the current timestamp in seconds since the Unix epoch.
+ *
+ * @returns The current timestamp in seconds.
+ */
+const getCurrentTimestamp = () => {
+    return Math.floor(new Date().getTime() / 1000);
+};
+
+exports.getCurrentTimestamp = getCurrentTimestamp;
+//# sourceMappingURL=GetCurrentTimestamp.js.map

package/dist/cjs/services/ESPRMNeoHelpers/GetCurrentTimestamp.js.map

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