@espressif/rainmaker-neo-base-sdk 1.0.0

package/dist/cjs/services/ESPRMNeoSubscriptionManager.js

@@ -0,0 +1,357 @@
+'use strict';
+
+var subscription = require('../types/subscription.js');
+var NodeMQTTOrchestrator = require('./NodeMQTTOrchestrator.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("ESPRMNeoSubscriptionManager");
+/**
+ * Manages subscription channels and coordinates node update subscriptions.
+ * This is the central hub for all parameter update subscriptions from various sources
+ * (custom channels)
+ *
+ * The manager uses a priority-based approach:
+ * 1. For each node, it determines the effective channel order (node-specific or global)
+ * 2. It filters channels based on availability and node support
+ * 3. It tries channels in order until one succeeds
+ *
+ * Subscription pattern: register one or more channels, set global channel order,
+ * then subscribeToNode(node, callback). Node must have .id; for channel selection it may
+ * have .type, .metadata, .subscriptionConfig.channelOrder. Callback receives ESPNodeUpdateData.
+ *
+ * @example
+ * ```typescript
+ * // Register channels
+ * await ESPRMNeoBase.subscriptionManager.registerChannel(new MQTTSubscriptionChannel());
+ *
+ * // Set global channel order (applies to nodes without their own override)
+ * ESPRMNeoBase.subscriptionManager.setGlobalChannelOrder(["mqtt"]);
+ *
+ * // Subscribe to node updates (node can be an SDK node or a proxy with { id, nodeId, type, config, metadata })
+ * await ESPRMNeoBase.subscriptionManager.subscribeToNode(node, (update) => {
+ *   console.log(`Node ${update.nodeId} updated via ${update.source}`);
+ * });
+ * ```
+ */
+class ESPRMNeoSubscriptionManager {
+    /**
+     * Registered subscription channels (channelId -> channel instance)
+     */
+    channels = new Map();
+    /**
+     * Global default channel order (used when node doesn't have custom order)
+     * Channels are tried in this order until one succeeds
+     */
+    globalChannelOrder = [];
+    /**
+     * Whether the manager has been initialized
+     */
+    initialized = false;
+    /**
+     * Initialize the subscription manager.
+     * This initializes all registered channels.
+     * Should be called during SDK initialization.
+     *
+     * @returns Promise that resolves when initialization is complete
+     */
+    async initialize() {
+        if (this.initialized) {
+            return;
+        }
+        for (const channel of this.channels.values()) {
+            try {
+                await channel.initialize();
+            }
+            catch (error) {
+                logger.error(`Failed to initialize channel ${channel.channelId}:`, error);
+            }
+        }
+        this.initialized = true;
+    }
+    /**
+     * Register a new subscription channel.
+     *
+     * @param channel - The channel to register
+     * @param autoInitialize - Whether to initialize the channel immediately (default: true)
+     * @throws Error if a channel with the same ID is already registered
+     *
+     * @example
+     * ```typescript
+     * const mqttChannel = new MQTTSubscriptionChannel();
+     * await ESPRMNeoBase.subscriptionManager.registerChannel(mqttChannel);
+     * ```
+     */
+    async registerChannel(channel, autoInitialize = true) {
+        if (this.channels.has(channel.channelId)) {
+            throw new Error(`Channel ${channel.channelId} is already registered`);
+        }
+        this.channels.set(channel.channelId, channel);
+        if (autoInitialize && this.initialized) {
+            await channel.initialize();
+        }
+    }
+    /**
+     * Unregister a subscription channel.
+     * This will dispose the channel and remove it from the manager.
+     *
+     * @param channelId - ID of the channel to unregister
+     *
+     * @example
+     * ```typescript
+     * await ESPRMNeoBase.subscriptionManager.unregisterChannel("mqtt");
+     * ```
+     */
+    async unregisterChannel(channelId) {
+        const channel = this.channels.get(channelId);
+        if (!channel)
+            return;
+        await channel.dispose();
+        this.channels.delete(channelId);
+    }
+    /**
+     * Set the global default channel order.
+     * This order is used for all nodes unless they have a custom order in subscriptionConfig.
+     *
+     * @param channelIds - Array of channel IDs in priority order (first = highest priority)
+     *
+     * @example
+     * ```typescript
+     * // Try Matter first, then MQTT
+     * ESPRMNeoBase.subscriptionManager.setGlobalChannelOrder([
+     *   "matter",
+     *   "mqtt"
+     * ]);
+     * ```
+     */
+    setGlobalChannelOrder(channelIds) {
+        const invalidChannels = channelIds.filter((id) => !this.channels.has(id));
+        if (invalidChannels.length > 0) {
+            logger.warn(`Unknown channels in order: ${invalidChannels.join(", ")}`);
+        }
+        this.globalChannelOrder = channelIds;
+    }
+    /**
+     * Get the effective channel order for a node.
+     * Priority: node.subscriptionConfig.channelOrder > global channel order
+     *
+     * @param node - The node to get channel order for
+     * @returns Array of channel IDs in priority order
+     */
+    getEffectiveChannelOrder(node) {
+        // Use the per-node override only when it is non-empty. An empty array is
+        // treated the same as "not set" so a stray/rehydrated `channelOrder: []`
+        // falls back to the global order instead of trapping the node with no
+        // available channels (which only clearSubscriptionChannelOrder() could undo).
+        if (node.subscriptionConfig?.channelOrder?.length) {
+            return node.subscriptionConfig.channelOrder;
+        }
+        return this.globalChannelOrder;
+    }
+    /**
+     * Get available channels for a node.
+     * Filters channels based on:
+     * - Channel is registered
+     * - Channel supports the node (via supportsNode())
+     * - Channel is in the effective order
+     *
+     * @param node - The node to get channels for
+     * @returns Array of available channels in priority order
+     *
+     * @example
+     * ```typescript
+     * const channels = ESPRMNeoBase.subscriptionManager.getAvailableChannelsForNode(node);
+     * console.log(`Available channels: ${channels.map(c => c.channelId).join(", ")}`);
+     * ```
+     */
+    getAvailableChannelsForNode(node) {
+        const effectiveOrder = this.getEffectiveChannelOrder(node);
+        return effectiveOrder
+            .map((channelId) => this.channels.get(channelId))
+            .filter((channel) => channel && channel.supportsNode(node));
+    }
+    /**
+     * Builds a diagnostic message for the "no available channels" case. Lists the
+     * effective order, the registered channels, and which ids in the order are
+     * unregistered vs. registered-but-unsupported — so an order typo or a missing
+     * channel is easy to spot. Used in place of set-time validation, which would
+     * false-positive when an order references a not-yet-registered channel
+     * (e.g. an order set before its target channel registers).
+     *
+     * @param node - The node being subscribed.
+     * @param nodeId - The resolved node id (for the message).
+     * @returns A human-readable diagnostic error message.
+     */
+    buildNoChannelsError(node, nodeId) {
+        const effectiveOrder = this.getEffectiveChannelOrder(node);
+        const registered = this.getRegisteredChannels();
+        const unregistered = effectiveOrder.filter((id) => !this.channels.has(id));
+        const unsupported = effectiveOrder.filter((id) => {
+            const channel = this.channels.get(id);
+            return channel ? !channel.supportsNode(node) : false;
+        });
+        let message = `No available subscription channels for node ${nodeId}. ` +
+            `Effective order: [${effectiveOrder.join(", ") || "(empty)"}]. ` +
+            `Registered channels: [${registered.join(", ") || "(none)"}].`;
+        if (unregistered.length) {
+            message += ` Unregistered ids in order: [${unregistered.join(", ")}].`;
+        }
+        if (unsupported.length) {
+            message += ` Registered but unsupported for this node: [${unsupported.join(", ")}].`;
+        }
+        return message;
+    }
+    /**
+     * Subscribe to updates for a specific node using priority-based channel selection.
+     * Tries channels in order until one succeeds.
+     *
+     * @param node - The node to subscribe to
+     * @param callback - Function to call when updates are received
+     * @throws Error if no channels are available or all channels fail
+     *
+     * @example
+     * ```typescript
+     * await ESPRMNeoBase.subscriptionManager.subscribeToNode(node, (update) => {
+     *   console.log(`Update from ${update.source}:`, update.payload);
+     * });
+     * ```
+     */
+    async subscribeToNode(node, callback) {
+        const nodeId = subscription.resolveNodeId(node);
+        if (!nodeId) {
+            throw new Error("Cannot subscribe: node has no id or nodeId");
+        }
+        const availableChannels = this.getAvailableChannelsForNode(node);
+        if (availableChannels.length === 0) {
+            throw new Error(this.buildNoChannelsError(node, nodeId));
+        }
+        let lastError;
+        for (const channel of availableChannels) {
+            try {
+                await channel.subscribe(callback, node);
+                return;
+            }
+            catch (error) {
+                lastError = error;
+            }
+        }
+        throw new Error(`All subscription channels failed for node ${nodeId}. Last error: ${lastError?.message}`);
+    }
+    /**
+     * Subscribe to updates for all nodes.
+     *
+     * @param nodes - Array of nodes to subscribe to
+     * @param callback - Function to call when any node is updated
+     *
+     * @example
+     * ```typescript
+     * const nodes = group.getNodes();
+     * await ESPRMNeoBase.subscriptionManager.subscribeToAllNodes(nodes, (update) => {
+     *   console.log(`Node ${update.nodeId} updated`);
+     * });
+     * ```
+     */
+    async subscribeToAllNodes(nodes, callback) {
+        const errors = [];
+        for (const node of nodes) {
+            try {
+                await this.subscribeToNode(node, callback);
+            }
+            catch (error) {
+                errors.push({
+                    nodeId: subscription.resolveNodeId(node) ?? "unknown",
+                    error: error,
+                });
+            }
+        }
+        if (errors.length > 0) {
+            logger.warn(`Failed to subscribe to ${errors.length} nodes:`, errors);
+        }
+    }
+    /**
+     * Unsubscribe from updates for a specific node across all channels.
+     *
+     * @param nodeId - ID of the node to unsubscribe from.
+     * @param callback - Optional specific subscriber to remove. When provided,
+     *   only that callback is detached (the node's other subscribers keep
+     *   receiving updates); when omitted, all subscribers for the node are
+     *   removed AND the node's MQTT shadow binding on {@link NodeMQTTOrchestrator}
+     *   is cleared — so the next subscribe re-registers a fresh shadow name
+     *   (needed when app-side membership changes the node's shadow topic).
+     *
+     * @example
+     * ```typescript
+     * // Remove one subscriber (siblings keep receiving updates):
+     * await ESPRMNeoBase.subscriptionManager.unsubscribeFromNode("node-123", myCallback);
+     * // Remove every subscriber for the node + clear MQTT shadow binding:
+     * await ESPRMNeoBase.subscriptionManager.unsubscribeFromNode("node-123");
+     * ```
+     */
+    async unsubscribeFromNode(nodeId, callback) {
+        for (const channel of this.channels.values()) {
+            try {
+                await channel.unsubscribe(nodeId, callback);
+            }
+            catch (error) {
+                logger.warn(`Failed to unsubscribe from ${channel.channelId} for node ${nodeId}:`, error);
+            }
+        }
+        // Full purge (no specific callback): also drop the orchestrator's
+        // nodeId → shadowName binding so a later subscribe re-registers the node
+        // against its current shadow. Consumers that just detach one callback
+        // keep the binding intact for other subscribers.
+        if (!callback) {
+            try {
+                NodeMQTTOrchestrator.NodeMQTTOrchestrator.unregisterNode(nodeId);
+            }
+            catch (error) {
+                logger.warn(`Failed to unregister node ${nodeId} from NodeMQTTOrchestrator:`, error);
+            }
+        }
+    }
+    /**
+     * Get all registered channel IDs.
+     *
+     * @returns Array of channel IDs
+     *
+     * @example
+     * ```typescript
+     * const channels = ESPRMNeoBase.subscriptionManager.getRegisteredChannels();
+     * console.log(`Registered channels: ${channels.join(", ")}`);
+     * ```
+     */
+    getRegisteredChannels() {
+        return Array.from(this.channels.keys());
+    }
+    /**
+     * Get the global channel order.
+     *
+     * @returns Array of channel IDs in priority order
+     */
+    getGlobalChannelOrder() {
+        return [...this.globalChannelOrder];
+    }
+    /**
+     * Cleanup all subscriptions and dispose channels.
+     * Should be called when app is closing or SDK is being torn down.
+     *
+     * @example
+     * ```typescript
+     * await ESPRMNeoBase.subscriptionManager.dispose();
+     * ```
+     */
+    async dispose() {
+        for (const channel of this.channels.values()) {
+            await channel.dispose();
+        }
+        this.channels.clear();
+        this.initialized = false;
+    }
+}
+
+exports.ESPRMNeoSubscriptionManager = ESPRMNeoSubscriptionManager;
+//# sourceMappingURL=ESPRMNeoSubscriptionManager.js.map

package/dist/cjs/services/ESPRMNeoSubscriptionManager.js.map

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

package/dist/cjs/services/ESPSigV4APIManager.js

@@ -0,0 +1,328 @@
+'use strict';
+
+var awsSigv4Utils = require('../utils/awsSigv4Utils.js');
+var logger$1 = require('../utils/logger.js');
+var ESPRMNeoStorage = require('./ESPRMNeoStorage/ESPRMNeoStorage.js');
+var ESPRMNeoAPIManager = require('./ESPRMNeoAPIManager.js');
+
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const logger = new logger$1.Logger("ESPSigV4APIManager");
+// ═════════════════════════════════════════════════════════════════════
+// Module-scoped state
+// ═════════════════════════════════════════════════════════════════════
+/**
+ * Module-scoped singleton. Cannot be constructed by external code because the
+ * class constructor is private; the only construction path is
+ * {@link initializeSigV4APIManager}, which lives in this module and is not
+ * re-exported through the public SDK barrel.
+ */
+let instance = null;
+/**
+ * In-flight refresh promise for concurrent-call coalescing. When multiple
+ * signed requests notice expired credentials at the same time, they all share
+ * one Cognito round-trip instead of stampeding.
+ */
+let refreshInFlight = null;
+// ═════════════════════════════════════════════════════════════════════
+// Module-scoped helpers
+// ═════════════════════════════════════════════════════════════════════
+/** Late-bound to avoid a circular import through `../methods/ESPRMNeoUser`. */
+function fetchTemporaryAWSCredentials() {
+    return require("../methods/ESPRMNeoUser/GetTemporaryAWSCredentials")
+        .fetchTemporaryAWSCredentials();
+}
+/**
+ * Fetches fresh temporary AWS credentials and persists them, coalescing
+ * concurrent callers onto a single in-flight promise.
+ */
+async function refreshTemporaryCredentialsOnce() {
+    if (refreshInFlight)
+        return refreshInFlight;
+    refreshInFlight = (async () => {
+        try {
+            const fresh = await fetchTemporaryAWSCredentials();
+            await ESPRMNeoStorage.ESPRMNeoStorage.saveTemporaryCredentials(fresh);
+            return fresh;
+        }
+        finally {
+            refreshInFlight = null;
+        }
+    })();
+    return refreshInFlight;
+}
+/**
+ * Produces the two UTC timestamps required by every SigV4-signed request:
+ *
+ * - `timestamp` – ISO 8601 basic (`YYYYMMDDTHHMMSSZ`), used in the
+ *   `X-Amz-Date` header and in the string-to-sign.
+ * - `dateStamp` – date-only (`YYYYMMDD`), used in the credential scope
+ *   (`{dateStamp}/{region}/{service}/aws4_request`).
+ *
+ * Computed once per request; both values share the same underlying `Date`.
+ */
+function formatSigV4Timestamps(date) {
+    // toISOString → "2026-07-18T14:30:22.123Z"; SigV4 needs no separators or ms.
+    const timestamp = date.toISOString().replace(/[-:]|\.\d{3}/g, "");
+    return { timestamp, dateStamp: timestamp.slice(0, 8) };
+}
+class ESPSigV4APIManager extends ESPRMNeoAPIManager.ESPRMNeoAPIManager {
+    // ─── Fields ─────────────────────────────────────────────────────────
+    #baseUrl;
+    #awsRegion;
+    #service = "execute-api";
+    // ═════════════════════════════════════════════════════════════════════
+    // Lifecycle
+    // ═════════════════════════════════════════════════════════════════════
+    constructor(init) {
+        super();
+        this.#baseUrl = init.baseUrl.replace(/\/$/, "");
+        this.#awsRegion = init.awsRegion;
+    }
+    /**
+     * Friend-access hook used only by {@link initializeSigV4APIManager} in this
+     * module. TypeScript allows a same-class static method to reach the private
+     * constructor; free functions cannot. Not part of the public API surface.
+     *
+     * @internal
+     */
+    static _constructSigV4(init) {
+        return new ESPSigV4APIManager(init);
+    }
+    /**
+     * Returns the singleton constructed by SDK bootstrap.
+     *
+     * @throws {Error} If the SDK has not been configured — usually because
+     *   `ESPRMNeoBase.configure()` did not run first.
+     */
+    static getInstance() {
+        if (!instance) {
+            throw new Error("ESPSigV4APIManager not initialized. Ensure ESPRMNeoBase.configure() ran first.");
+        }
+        return instance;
+    }
+    // ═════════════════════════════════════════════════════════════════════
+    // Credential + retry helpers
+    // ═════════════════════════════════════════════════════════════════════
+    areCredentialsExpired(credentials) {
+        // If no expiration field or invalid, treat as expired
+        if (!credentials.expiration) {
+            return true;
+        }
+        const expirationDate = new Date(credentials.expiration);
+        // If invalid date, treat as expired
+        if (isNaN(expirationDate.getTime())) {
+            return true;
+        }
+        // Add buffer time (5 minutes) before actual expiration
+        const bufferTime = 5 * 60 * 1000;
+        const now = Date.now();
+        const isExpired = now + bufferTime >= expirationDate.getTime();
+        return isExpired;
+    }
+    /**
+     * Runs `fn` and, on a 403, clears stored credentials and retries once.
+     * Any 403 is treated as retryable — AWS uses 403 uniformly for expired /
+     * invalid credentials, and a single retry is bounded regardless of the
+     * response wording. `retriesLeft` is per-call, so concurrent requests
+     * never block each other's retry.
+     */
+    async withCredentialsRetry(fn, retriesLeft = 1) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            if (retriesLeft > 0 && err?.status === 403) {
+                await ESPRMNeoStorage.ESPRMNeoStorage.clearTemporaryCredentials();
+                return this.withCredentialsRetry(fn, retriesLeft - 1);
+            }
+            throw err;
+        }
+    }
+    // ═════════════════════════════════════════════════════════════════════
+    // Signed HTTP core
+    // ═════════════════════════════════════════════════════════════════════
+    /**
+     * Performs a SigV4-signed request to the given URL. Used by {@link request}.
+     */
+    async _signedRequest(method, url, data, headers = {}) {
+        const canonicalURI = url.pathname;
+        let credentials;
+        try {
+            credentials = await ESPRMNeoStorage.ESPRMNeoStorage.getTemporaryCredentials();
+            if (this.areCredentialsExpired(credentials)) {
+                credentials = await refreshTemporaryCredentialsOnce();
+            }
+        }
+        catch {
+            // No stored credentials, or storage read failed — refresh from Cognito.
+            credentials = await refreshTemporaryCredentialsOnce();
+        }
+        const { timestamp, dateStamp } = formatSigV4Timestamps(new Date());
+        const payload = data ? JSON.stringify(data) : "";
+        const payloadHash = crypto
+            .createHash("sha256")
+            .update(payload)
+            .digest("hex");
+        const requestHeaders = {
+            host: url.host,
+            "x-amz-date": timestamp,
+            "x-amz-security-token": credentials.sessionToken,
+            ...headers,
+        };
+        const signedHeaderKeys = Object.keys(requestHeaders).sort();
+        const signedHeaders = signedHeaderKeys.join(";");
+        // SigV4 requires the canonical query string sorted and re-encoded; signing
+        // url.search verbatim breaks any request whose params aren't already
+        // in sorted order (API Gateway sorts before verifying).
+        const canonicalQueryString = awsSigv4Utils.buildCanonicalQueryString(url.searchParams);
+        const authHeader = awsSigv4Utils.generateSigV4AuthHeader({
+            accessKey: credentials.accessKey,
+            secretKey: credentials.secretKey,
+            timestamp,
+            dateStamp,
+            region: this.#awsRegion,
+            service: this.#service,
+            method,
+            canonicalURI,
+            canonicalQueryString,
+            requestHeaders,
+            signedHeaders,
+            payloadHash,
+        });
+        const response = await fetch(url.toString(), {
+            method,
+            headers: {
+                ...requestHeaders,
+                Authorization: authHeader,
+                "Content-Type": "application/json",
+            },
+            body: data ? JSON.stringify(data) : undefined,
+        });
+        const text = await response.text();
+        const responseData = (() => {
+            try {
+                return text ? JSON.parse(text) : null;
+            }
+            catch (parseErr) {
+                logger.debug("SigV4 API: Failed to parse response as JSON", parseErr);
+                throw new Error("Failed to parse response as JSON", parseErr instanceof Error ? { cause: parseErr } : undefined);
+            }
+        })();
+        if (!response.ok) {
+            logger.error("HTTP request failed:", {
+                method,
+                url: url.toString(),
+                status: response.status,
+                message: responseData?.message,
+            });
+            const errorMessage = `HTTP error! status: ${response.status}` +
+                (responseData?.message ? ` - ${responseData.message}` : "") +
+                (responseData?.error ? ` - ${responseData.error}` : "");
+            const err = new Error(errorMessage);
+            err.status = response.status;
+            err.responseData = responseData;
+            throw err;
+        }
+        return { data: responseData, status: response.status, responseData };
+    }
+    // ═════════════════════════════════════════════════════════════════════
+    // Public HTTP API
+    // ═════════════════════════════════════════════════════════════════════
+    async request(method, path, data, headers = {}) {
+        const pathWithSlash = path.startsWith("/") ? path : `/${path}`;
+        const url = new URL(this.#baseUrl + pathWithSlash);
+        return this.withCredentialsRetry(async () => {
+            const result = await this._signedRequest(method, url, data, headers);
+            return result.data;
+        });
+    }
+    async get(path, headers = {}) {
+        return this.request("GET", path, undefined, headers);
+    }
+    async post(path, data, headers = {}) {
+        return this.request("POST", path, data, headers);
+    }
+    async put(path, data, headers = {}) {
+        return this.request("PUT", path, data, headers);
+    }
+    async patch(path, data, headers = {}) {
+        return this.request("PATCH", path, data, headers);
+    }
+    async delete(path, headers = {}) {
+        return this.request("DELETE", path, undefined, headers);
+    }
+    // ═════════════════════════════════════════════════════════════════════
+    // IoT MQTT URL signing (static utility)
+    // ═════════════════════════════════════════════════════════════════════
+    /**
+     * Normalizes a config IoT endpoint to a hostname (strips protocol and path).
+     */
+    static #normalizeIotEndpointHost(endpoint) {
+        const trimmed = endpoint.trim();
+        const withoutProto = trimmed
+            .replace(/^https?:\/\//, "")
+            .replace(/^wss?:\/\//, "");
+        const hostOnly = withoutProto.split("/")[0];
+        if (!hostOnly) {
+            throw new Error("Invalid IoT endpoint: empty host");
+        }
+        return hostOnly;
+    }
+    /**
+     * Presigned `wss://…/mqtt?…` URL for AWS IoT Core MQTT over WebSocket (SigV4 query signing,
+     * service `iotdevicegateway`). Uses the same signing primitives as {@link ESPSigV4APIManager._signedRequest}.
+     *
+     * @param credentials - Temporary AWS credentials (e.g. from `ESPRMNeoUser.getTemporaryAWSCredentials`).
+     * @param iotEndpointOrHost - Raw `config.iotEndpoint`, a full `wss://…/mqtt` URL, or hostname only.
+     * @param awsRegion - AWS region for signing (e.g. "us-east-1"). Required; passed explicitly so
+     *   this helper stays pure and doesn't reach back to global SDK config.
+     * @param options - Optional URL expiry (default 86400s).
+     */
+    static getIotMqttWebSocketSignedUrl(credentials, iotEndpointOrHost, awsRegion, options) {
+        const host = ESPSigV4APIManager.#normalizeIotEndpointHost(iotEndpointOrHost);
+        return awsSigv4Utils.generateIotDeviceGatewayMqttSignedUrl({
+            accessKey: credentials.accessKey,
+            secretKey: credentials.secretKey,
+            sessionToken: credentials.sessionToken,
+            host,
+            awsRegion,
+            expiresSeconds: options?.expiresSeconds,
+        });
+    }
+}
+// ═════════════════════════════════════════════════════════════════════
+// SDK bootstrap hooks (not re-exported publicly)
+// ═════════════════════════════════════════════════════════════════════
+/**
+ * SDK bootstrap hook. Called by {@link ESPRMNeoBase.configure}. Not re-exported
+ * through the public SDK barrel — external consumers cannot reach this function
+ * and cannot construct an {@link ESPSigV4APIManager} instance.
+ *
+ * @internal
+ * @throws {Error} If already initialized.
+ */
+function initializeSigV4APIManager(init) {
+    if (instance) {
+        throw new Error("ESPSigV4APIManager already initialized. Re-configuring the SDK is not supported.");
+    }
+    instance = ESPSigV4APIManager._constructSigV4(init);
+}
+/**
+ * Test-only hook to reset the singleton and any in-flight refresh promise
+ * between test cases. Not re-exported.
+ *
+ * @internal
+ */
+function _resetSigV4APIManagerForTests() {
+    instance = null;
+    refreshInFlight = null;
+}
+
+exports.ESPSigV4APIManager = ESPSigV4APIManager;
+exports._resetSigV4APIManagerForTests = _resetSigV4APIManagerForTests;
+exports.initializeSigV4APIManager = initializeSigV4APIManager;
+//# sourceMappingURL=ESPSigV4APIManager.js.map

package/dist/cjs/services/ESPSigV4APIManager.js.map

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