@espressif/rainmaker-neo-base-sdk 1.0.0

package/dist/types/services/ESPRMNeoHelpers/DecodeToken.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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.
+ */
+declare const decodeToken: (token: string) => Record<string, unknown>;
+export { decodeToken };

package/dist/types/services/ESPRMNeoHelpers/DelegatedTransportHandler.d.ts

@@ -0,0 +1,25 @@
+import { ESPRMNeoNode } from "../../ESPRMNeoNode";
+import { ESPTransportInterface } from "../../types/transport";
+/**
+ * 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.
+ */
+declare const delegatedTransportHandler: <T>(this: ESPRMNeoNode, operation: (manager: ESPTransportInterface) => Promise<T>) => Promise<T>;
+export { delegatedTransportHandler };

package/dist/types/services/ESPRMNeoHelpers/FetchTSData.d.ts

@@ -0,0 +1,37 @@
+import type { ESPRMNeoTSDataOptions, ESPRMNeoTSDataResult } from "../../types/tsData";
+/**
+ * Everything needed to query the timeseries endpoints for one param.
+ * Shared by the node-level (`getCustomParam*TSData`) and param-level
+ * (`get*TSData`) method APIs.
+ */
+export interface FetchTSDataConfig {
+    groupId: string;
+    nodeId: string;
+    /** Backend param key, `"<device_id>.<param_id>"`. */
+    key: string;
+    /** Backend data type (`bool` | `int` | `float` | `string`). */
+    dataType: string;
+    options?: ESPRMNeoTSDataOptions;
+}
+/**
+ * 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.
+ */
+export declare const fetchRawTSData: (config: FetchTSDataConfig, startKeyParam?: string) => Promise<ESPRMNeoTSDataResult>;
+/**
+ * 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).
+ */
+export declare const fetchLatestTSData: (config: FetchTSDataConfig) => Promise<ESPRMNeoTSDataResult>;
+/**
+ * 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).
+ */
+export declare const fetchAggregatedTSData: (config: FetchTSDataConfig, startKeyParam?: string) => Promise<ESPRMNeoTSDataResult>;

package/dist/types/services/ESPRMNeoHelpers/GenerateUUID.d.ts

@@ -0,0 +1 @@
+export declare function generateUUIDv4(): string;

package/dist/types/services/ESPRMNeoHelpers/GetCurrentTimestamp.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Gets the current timestamp in seconds since the Unix epoch.
+ *
+ * @returns The current timestamp in seconds.
+ */
+declare const getCurrentTimestamp: () => number;
+export { getCurrentTimestamp };

package/dist/types/services/ESPRMNeoHelpers/NodeMappingHelper.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Helper module for managing node mapping-related operations.
+ */
+export declare class NodeMappingHelper {
+    /**
+     * Initiates a user node mapping request.
+     *
+     * @param groupId - The ID of the group to associate the node with.
+     * @param requestBody - The request body for the user node mapping.
+     * @returns A promise that resolves to the response from the API.
+     */
+    static initiateUserNodeMapping(groupId: string, requestBody?: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Verifies the mapping between a user and a node.
+     *
+     * @param groupId - The ID of the group.
+     * @param requestId - The node association request ID.
+     * @param requestBody - The request body for the user node mapping verification.
+     * @returns A promise that resolves to the response from the API.
+     */
+    static verifyUserNodeMapping(groupId: string, requestId: string, requestBody?: Record<string, unknown>): Promise<{
+        message?: string;
+        node_id?: string;
+        challenge_response?: string;
+    }>;
+}

package/dist/types/services/ESPRMNeoHelpers/TransformEncoding.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Converts a base64 string to a Uint8Array.
+ * @param b64 The base64 string to convert
+ * @returns A Uint8Array containing the decoded bytes
+ * @throws {Error} If the input is not a valid base64 string
+ */
+export declare function base64ToUint8Array(b64: string): Uint8Array;
+/**
+ * Converts a Uint8Array to a base64 string.
+ * @param arr The Uint8Array to convert
+ * @returns A base64-encoded string
+ */
+export declare function uint8ArrayToBase64(arr: Uint8Array): string;

package/dist/types/services/ESPRMNeoHelpers/transformShadowToNodeUpdate.d.ts

@@ -0,0 +1,25 @@
+import { ESPNodeUpdateData } from "../../types/subscription";
+/**
+ * Canonical event type emitted when a node's parameters change.
+ */
+export declare const NODE_PARAMS_CHANGED_EVENT = "rmneo.event.node_params_changed";
+/**
+ * Normalizes a parsed AWS IoT shadow document into the canonical
+ * {@link ESPNodeUpdateData} envelope used by every subscription channel.
+ *
+ * The `payload` is reduced to the device→param map
+ * (`{ <deviceName>: { <paramName>: value } }`) by preferring
+ * `state.reported.params` and falling back to `state.reported`, so all channels
+ * agree on the same payload shape regardless of transport.
+ *
+ * The full parsed shadow is also attached as `metadata.shadow` so consumers that
+ * need fields outside the param map (e.g. `online`, `ncfg_ver`) can read them
+ * without changing the normalized `payload` contract.
+ *
+ * @param nodeId - The node the update belongs to.
+ * @param parsedShadow - The parsed shadow document (full live message or get/accepted document).
+ * @param meta - Channel-specific metadata to merge into `metadata` (e.g. `{ shadowName, topic }`).
+ * @param source - The originating channel id (defaults to the MQTT channel).
+ * @returns A normalized `ESPNodeUpdateData`.
+ */
+export declare function transformShadowToNodeUpdate(nodeId: string, parsedShadow: unknown, meta?: Record<string, unknown>, source?: string): ESPNodeUpdateData;

package/dist/types/services/ESPRMNeoMqtt/ESPMQTTConfig.d.ts

@@ -0,0 +1,15 @@
+/** Credentials and endpoint for MQTT connect (SigV4 / temporary creds). */
+export interface ESPMQTTConfig {
+    clientId: string;
+    endpoint: string;
+    accessKey: string;
+    secretKey: string;
+    sessionToken: string;
+    region: string;
+    /**
+     * Optional expiry hint for the credentials. Not needed to open the MQTT
+     * connection. An adapter may use it to schedule a proactive reconnect
+     * before AWS drops the socket when the creds expire.
+     */
+    expiration?: string;
+}

package/dist/types/services/ESPRMNeoMqtt/ESPRMNeoMqtt.d.ts

@@ -0,0 +1,83 @@
+import type { MQTTTransport } from "../interfaces/MQTTTransport";
+import type { ESPMQTTConfig } from "./ESPMQTTConfig";
+/**
+ * Singleton `MQTTTransport` that forwards calls to the transport passed to
+ * {@link ESPRMNeoMqtt.initialize}. Use with `NodeMQTTOrchestrator` as in the
+ * example below.
+ *
+ * @example
+ * ```ts
+ * ESPRMNeoMqtt.initialize(mqttTransport);
+ * NodeMQTTOrchestrator.initialize(ESPRMNeoMqtt.getInstance());
+ * ```
+ */
+export declare class ESPRMNeoMqtt implements MQTTTransport {
+    #private;
+    /**
+     * @param adapter - Transport to wrap (typically a concrete MQTT client adapter).
+     */
+    private constructor();
+    /**
+     * Initializes the singleton with an MQTT transport.
+     * Must be called before {@link ESPRMNeoMqtt.getInstance}.
+     *
+     * @param adapter - `MQTTTransport` implementation to delegate to.
+     * @throws {Error} If already initialized. Call {@link ESPRMNeoMqtt.clear}
+     *   first if you genuinely need to re-init (e.g. between test cases). A
+     *   silent replacement is refused because in-flight subscriptions on the
+     *   old adapter would be orphaned and messages would split between the
+     *   two live transports.
+     */
+    static initialize(adapter: MQTTTransport): void;
+    /**
+     * Returns the singleton instance.
+     *
+     * @throws {Error} If {@link ESPRMNeoMqtt.initialize} was not called.
+     */
+    static getInstance(): ESPRMNeoMqtt;
+    /**
+     * Clears the singleton.
+     */
+    static clear(): void;
+    /**
+     * Returns true when {@link ESPRMNeoMqtt.initialize} has been called.
+     * Safe to call before init (does not throw).
+     */
+    static hasInstance(): boolean;
+    /**
+     * Connect to MQTT using the provided configuration.
+     *
+     * @param config - MQTT configuration
+     */
+    connect(config: ESPMQTTConfig): Promise<void>;
+    /**
+     * Disconnect from MQTT.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Returns whether the underlying MQTT client is connected.
+     */
+    isConnected(): Promise<boolean>;
+    /**
+     * Publish a message to a topic.
+     *
+     * @param topic - MQTT topic to publish to
+     * @param payload - Message payload to publish
+     */
+    publish(topic: string, payload: string | Buffer): Promise<void>;
+    /**
+     * Subscribe to a topic with a message handler.
+     *
+     * @param topic - MQTT topic to subscribe to
+     * @param handler - Callback invoked when a message is received on the topic
+     */
+    subscribe(topic: string, handler: (topic: string, payload: Buffer) => void): Promise<void>;
+    /**
+     * Unsubscribe from a topic, optionally removing a specific handler.
+     *
+     * @param topic - MQTT topic to unsubscribe from
+     * @param handler - Callback that was used with {@link ESPRMNeoMqtt.subscribe}
+     */
+    unsubscribe(topic: string, handler?: (topic: string, payload: Buffer) => void): Promise<void>;
+}
+export type { ESPMQTTConfig } from "./ESPMQTTConfig";

package/dist/types/services/ESPRMNeoStorage/DefaultStorageAdapter.d.ts

@@ -0,0 +1,17 @@
+import { ESPStorageAdapter } from "../../types/storage";
+/**
+ * Default storage adapter backed by the runtime's `localStorage`.
+ *
+ * Only useful on browser-like environments. On React Native and Node.js
+ * (which have no `localStorage`), pass a custom adapter to
+ * {@link ESPRMNeoStorage.initialize} — for example one backed by
+ * `@react-native-async-storage/async-storage`.
+ */
+export declare class DefaultStorageAdapter implements ESPStorageAdapter {
+    private readonly storage;
+    constructor();
+    setItem(name: string, value: string): Promise<void>;
+    getItem(name: string): Promise<string | null>;
+    removeItem(name: string): Promise<void>;
+    clear(): Promise<void>;
+}

package/dist/types/services/ESPRMNeoStorage/ESPRMNeoStorage.d.ts

@@ -0,0 +1,65 @@
+import { ESPStorageAdapter } from "../../types/storage";
+import { ESPAWSCredentials } from "../../types/input";
+import { NodeConfigAPI } from "../../types/output";
+/**
+ * Manages storage operations using a configurable storage adapter.
+ */
+export declare class ESPRMNeoStorage {
+    #private;
+    /**
+     * Instantiated only via {@link ESPRMNeoStorage.initialize}; external callers
+     * should never `new` this class directly.
+     */
+    private constructor();
+    /**
+     * Initializes the singleton instance of ESPRMNeoStorage.
+     */
+    static initialize(customStorageAdapter?: ESPStorageAdapter): void;
+    /**
+     * Sets an item in the storage.
+     *
+     * @param name - The name of the item.
+     * @param value - The value to store.
+     */
+    static setItem(name: string, value: string): Promise<void>;
+    /**
+     * Retrieves an item from the storage.
+     *
+     * @param name - The name of the item.
+     * @returns A promise that resolves with the value of the item or null if not found.
+     */
+    static getItem(name: string): Promise<string | null>;
+    /**
+     * Removes an item from the storage.
+     *
+     * @param name - The name of the item.
+     */
+    static removeItem(name: string): Promise<void>;
+    /**
+     * Clears all items from the storage.
+     */
+    static clear(): Promise<void>;
+    /**
+     * Temporary AWS Credentials Management
+     */
+    static saveTemporaryCredentials(credentials: ESPAWSCredentials): Promise<void>;
+    static getTemporaryCredentials(): Promise<ESPAWSCredentials>;
+    static clearTemporaryCredentials(): Promise<void>;
+    /**
+     * Node Config Management
+     *
+     * Node configs are stored as JSON under `NODE_CONFIG_PREFIX + nodeId`. All
+     * three methods below encapsulate that layout so no other file needs to
+     * know how a node config is serialized.
+     */
+    static getNodeConfig(nodeId: string): Promise<NodeConfigAPI | null>;
+    static setNodeConfig(nodeId: string, config: NodeConfigAPI): Promise<void>;
+    static deleteNodeConfig(nodeId: string): Promise<void>;
+}
+/**
+ * Clears the storage singleton so {@link ESPRMNeoStorage.initialize} can run
+ * again after SDK dispose. Test / teardown only; not re-exported.
+ *
+ * @internal
+ */
+export declare function _resetESPRMNeoStorageForTests(): void;

package/dist/types/services/ESPRMNeoSubscriptionManager.d.ts

@@ -0,0 +1,211 @@
+import { ESPNodeUpdateData, ESPSubscriptionChannelInterface, NodeLike } from "../types/subscription";
+/**
+ * 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}`);
+ * });
+ * ```
+ */
+export declare class ESPRMNeoSubscriptionManager {
+    /**
+     * Registered subscription channels (channelId -> channel instance)
+     */
+    private channels;
+    /**
+     * Global default channel order (used when node doesn't have custom order)
+     * Channels are tried in this order until one succeeds
+     */
+    private globalChannelOrder;
+    /**
+     * Whether the manager has been initialized
+     */
+    private initialized;
+    /**
+     * Initialize the subscription manager.
+     * This initializes all registered channels.
+     * Should be called during SDK initialization.
+     *
+     * @returns Promise that resolves when initialization is complete
+     */
+    initialize(): Promise<void>;
+    /**
+     * 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);
+     * ```
+     */
+    registerChannel(channel: ESPSubscriptionChannelInterface, autoInitialize?: boolean): Promise<void>;
+    /**
+     * 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");
+     * ```
+     */
+    unregisterChannel(channelId: string): Promise<void>;
+    /**
+     * 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: string[]): void;
+    /**
+     * 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: NodeLike): string[];
+    /**
+     * 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: NodeLike): ESPSubscriptionChannelInterface[];
+    /**
+     * 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.
+     */
+    private buildNoChannelsError;
+    /**
+     * 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);
+     * });
+     * ```
+     */
+    subscribeToNode(node: NodeLike, callback: (update: ESPNodeUpdateData) => void): Promise<void>;
+    /**
+     * 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`);
+     * });
+     * ```
+     */
+    subscribeToAllNodes(nodes: NodeLike[], callback: (update: ESPNodeUpdateData) => void): Promise<void>;
+    /**
+     * 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");
+     * ```
+     */
+    unsubscribeFromNode(nodeId: string, callback?: (update: ESPNodeUpdateData) => void): Promise<void>;
+    /**
+     * Get all registered channel IDs.
+     *
+     * @returns Array of channel IDs
+     *
+     * @example
+     * ```typescript
+     * const channels = ESPRMNeoBase.subscriptionManager.getRegisteredChannels();
+     * console.log(`Registered channels: ${channels.join(", ")}`);
+     * ```
+     */
+    getRegisteredChannels(): string[];
+    /**
+     * Get the global channel order.
+     *
+     * @returns Array of channel IDs in priority order
+     */
+    getGlobalChannelOrder(): string[];
+    /**
+     * 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();
+     * ```
+     */
+    dispose(): Promise<void>;
+}

package/dist/types/services/ESPSigV4APIManager.d.ts

@@ -0,0 +1,99 @@
+import { ESPRMNeoAPIManager } from "./ESPRMNeoAPIManager";
+/**
+ * Dependencies required to construct the signed API manager. Passed explicitly
+ * at init time instead of reaching back into {@link ESPRMNeoBase} — that keeps
+ * the class testable in isolation and removes the need for a require-cycle
+ * workaround.
+ */
+export interface ESPSigV4APIManagerInit {
+    /**
+     * Full API base URL including stage if any
+     * (e.g. "https://api.rainmaker.espressif.com/prod").
+     */
+    baseUrl: string;
+    /** AWS region (e.g. "us-east-1"). */
+    awsRegion: string;
+}
+export declare class ESPSigV4APIManager extends ESPRMNeoAPIManager {
+    #private;
+    private constructor();
+    /**
+     * 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: ESPSigV4APIManagerInit): ESPSigV4APIManager;
+    /**
+     * 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(): ESPSigV4APIManager;
+    private areCredentialsExpired;
+    /**
+     * 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.
+     */
+    private withCredentialsRetry;
+    /**
+     * Performs a SigV4-signed request to the given URL. Used by {@link request}.
+     */
+    private _signedRequest;
+    request<T>(method: string, path: string, data?: any, headers?: {
+        [key: string]: string;
+    }): Promise<T>;
+    get<T>(path: string, headers?: {
+        [key: string]: string;
+    }): Promise<T>;
+    post<T>(path: string, data: any, headers?: {
+        [key: string]: string;
+    }): Promise<T>;
+    put<T>(path: string, data: any, headers?: {
+        [key: string]: string;
+    }): Promise<T>;
+    patch<T>(path: string, data: any, headers?: {
+        [key: string]: string;
+    }): Promise<T>;
+    delete<T>(path: string, headers?: {
+        [key: string]: string;
+    }): Promise<T>;
+    /**
+     * 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: {
+        accessKey: string;
+        secretKey: string;
+        sessionToken?: string;
+    }, iotEndpointOrHost: string, awsRegion: string, options?: {
+        expiresSeconds?: number;
+    }): string;
+}
+/**
+ * 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.
+ */
+export declare function initializeSigV4APIManager(init: ESPSigV4APIManagerInit): void;
+/**
+ * Test-only hook to reset the singleton and any in-flight refresh promise
+ * between test cases. Not re-exported.
+ *
+ * @internal
+ */
+export declare function _resetSigV4APIManagerForTests(): void;