@espressif/rainmaker-neo-base-sdk 1.0.0

package/dist/types/services/ESPTransport/ESPDiscovery/ESPDiscoveryManager.d.ts

@@ -0,0 +1,32 @@
+import { DiscoveryParamsInterface, ESPDiscoveryCallback } from "../../../types/discovery";
+/**
+ * Manages local node discovery through the app-supplied local discovery
+ * adapter (see {@link ESPRMNeoBase.setLocalDiscoveryAdapter}).
+ *
+ * - With no discovery config, the default local protocol is used
+ *   (mDNS service `_esp_local_ctrl._tcp.` in the `local` domain).
+ * - A custom {@link DiscoveryParamsInterface} can be supplied for other
+ *   discovery protocols.
+ */
+declare class ESPDiscoveryManager {
+    /** Discovery parameters (service type / domain) passed to the adapter. */
+    params: DiscoveryParamsInterface;
+    /**
+     * @param discoveryConfig - Optional custom discovery parameters. Defaults to
+     *   the local mDNS protocol.
+     * @throws {Error} If no local discovery adapter is set.
+     */
+    constructor(discoveryConfig?: DiscoveryParamsInterface);
+    private get adapter();
+    /**
+     * Starts discovery. The callback is invoked for each discovered node.
+     *
+     * @param callback - Invoked with the adapter's per-node discovery result.
+     */
+    startDiscovery(callback: ESPDiscoveryCallback): void;
+    /**
+     * Stops any ongoing discovery started by {@link startDiscovery}.
+     */
+    stopDiscovery(): void;
+}
+export { ESPDiscoveryManager };

package/dist/types/services/ESPTransport/ESPLocalControlTransport.d.ts

@@ -0,0 +1,38 @@
+import type { ESPRMNeoNode } from "../../ESPRMNeoNode";
+import { ESPAPIResponse } from "../../types/output";
+import { ESPTransportConfig, ESPTransportInterface } from "../../types/transport";
+/**
+ * Built-in `local` transport. Communicates with the node over the LAN through
+ * the app-supplied {@link ESPRMNeoBase.ESPLocalControlAdapter} using the
+ * `esp_local_ctrl` protobuf protocol. Connection metadata (`baseUrl`,
+ * `securityType`, `pop`, and `username` for sec2) is supplied via the transport
+ * config by {@link delegatedTransportHandler}.
+ */
+declare class ESPLocalControlTransport implements ESPTransportInterface {
+    private payload;
+    metadata: Record<string, any>;
+    propertyInfo: Record<string, any>;
+    constructor(transportConfig: ESPTransportConfig);
+    private get adapter();
+    /**
+     * Connects to the node, retrying on failure. RMNeo's adapter resolves on a
+     * successful connection and rejects otherwise, so a resolved call is treated
+     * as connected.
+     */
+    private connectWithRetry;
+    private ensureConnected;
+    setParam(payload: Record<string, any>, _nodeRef?: ESPRMNeoNode): Promise<ESPAPIResponse>;
+    getParams(payload: Record<string, any>, _nodeRef?: ESPRMNeoNode): Promise<Record<string, any>>;
+    private setProperty;
+    private buildSetPropertyRequest;
+    private processSetPropertyResponse;
+    /** Fetches the property count, then reads each property value into propertyInfo. */
+    private getPropertyInfo;
+    private fetchPropertyCount;
+    private buildGetPropertyCountRequest;
+    private processGetPropertyCountResponse;
+    private fetchPropertyValue;
+    private buildGetPropertyValueRequest;
+    private processGetPropertyValueResponse;
+}
+export { ESPLocalControlTransport };

package/dist/types/services/ESPTransport/ESPMqttTransport.d.ts

@@ -0,0 +1,13 @@
+import type { ESPRMNeoNode } from "../../ESPRMNeoNode";
+import { ESPAPIResponse } from "../../types/output";
+import { ESPTransportInterface } from "../../types/transport";
+/**
+ * Built-in `mqtt` transport — the RainMaker Neo cloud channel. Drives node
+ * params over MQTT (AWS IoT shadow / RainMaker user params topic) through
+ * {@link NodeMQTTOrchestrator}.
+ */
+declare class ESPMqttTransport implements ESPTransportInterface {
+    setParam(payload: Record<string, any>, _nodeRef?: ESPRMNeoNode): Promise<ESPAPIResponse>;
+    getParams(payload: Record<string, any>, _nodeRef?: ESPRMNeoNode): Promise<Record<string, any>>;
+}
+export { ESPMqttTransport };

package/dist/types/services/ESPTransport/ESPTransportManager.d.ts

@@ -0,0 +1,15 @@
+import type { ESPRMNeoNode } from "../../ESPRMNeoNode";
+import { ESPAPIResponse } from "../../types/output";
+import { ESPTransportConfig, ESPTransportInterface } from "../../types/transport";
+/**
+ * Selects and wraps a built-in transport implementation based on the transport
+ * config `type`. The {@link delegatedTransportHandler} constructs one of these
+ * per transport attempt and drives it through {@link ESPTransportInterface}.
+ */
+declare class ESPTransportManager implements ESPTransportInterface {
+    private transport;
+    constructor(transportConfig: ESPTransportConfig);
+    setParam(payload: Record<string, any>, nodeRef?: ESPRMNeoNode): Promise<ESPAPIResponse>;
+    getParams(payload: Record<string, any>, nodeRef?: ESPRMNeoNode): Promise<Record<string, any>>;
+}
+export { ESPTransportManager };

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

@@ -0,0 +1,140 @@
+import { ESPNodeUpdateData, ESPSubscriptionChannelInterface, NodeLike } from "../types/subscription";
+/**
+ * MQTT subscription channel for ESP RainMaker Neo.
+ *
+ * This channel is a thin adapter over {@link NodeMQTTOrchestrator}, which owns
+ * the single MQTT connection, the AWS IoT shadow topic subscriptions, and the
+ * deduplication of nodes that share a group/subgroup shadow. The channel's job
+ * is only to:
+ *  - map a node to its shadow and register it with the orchestrator,
+ *  - normalize each shadow message into the canonical {@link ESPNodeUpdateData}
+ *    envelope (so the app sees the same shape from every channel), and
+ *  - fan that envelope out to the app callbacks subscribed for the node.
+ *
+ * It deliberately does **not** open/close the MQTT connection — that lifecycle
+ * is owned by `ESPRMNeoBase.init()` / the orchestrator, so disposing one channel
+ * never tears down a connection other channels (or the node) still use.
+ *
+ * @example
+ * ```typescript
+ * const mqttChannel = new MQTTSubscriptionChannel();
+ * await ESPRMNeoBase.subscriptionManager.registerChannel(mqttChannel);
+ * await ESPRMNeoBase.subscriptionManager.subscribeToNode(node, (update) => {
+ *   console.log(`Node ${update.nodeId} updated:`, update.payload);
+ * });
+ * ```
+ */
+export declare class MQTTSubscriptionChannel implements ESPSubscriptionChannelInterface {
+    readonly channelId: "mqtt";
+    /**
+     * App callbacks per node (nodeId → set of subscriber callbacks).
+     */
+    private nodeCallbacks;
+    /**
+     * The single orchestrator listener installed per node (nodeId → listener).
+     * Kept so we can detach exactly that listener on unsubscribe.
+     */
+    private orchestratorListeners;
+    /**
+     * nodeId → orchestrator generation at which we last attached its listener.
+     * If the orchestrator is re-initialized (logout→login), the generation
+     * changes and we re-attach instead of trusting stale cached state.
+     */
+    private nodeGeneration;
+    /**
+     * nodeId → tail of the in-flight operation chain for that node. Subscribe and
+     * unsubscribe for the same node are serialized through this so they never
+     * interleave across an await boundary (see {@link runSerial}).
+     */
+    private nodeOps;
+    private isInitialized;
+    /**
+     * Initialize the channel. The MQTT engine
+     * ({@link NodeMQTTOrchestrator} over `ESPRMNeoMqtt`) is initialized by
+     * `ESPRMNeoBase.init()` when an `mqttAdapter` is configured, so there is no
+     * connection to set up here.
+     */
+    initialize(): Promise<void>;
+    /**
+     * MQTT is the universal transport for RainMaker Neo nodes, so this channel
+     * supports every node.
+     *
+     * @param _node - Unused; MQTT supports all Neo nodes.
+     * @returns Always `true`.
+     */
+    supportsNode(_node: NodeLike): boolean;
+    /**
+     * Subscribe to parameter updates for a node.
+     *
+     * Constructs the node's shadow name from its group/subgroup context, registers
+     * it with the orchestrator (deduped by shadow), and installs a single
+     * orchestrator listener per node that normalizes shadow messages and fans
+     * them out to all subscriber callbacks.
+     *
+     * @param callback - Invoked with a normalized {@link ESPNodeUpdateData} on each update.
+     * @param node - The node to subscribe to. Must carry `nodeId` (or `id`) and
+     *   `groupId`; `subgroupIds` optional. Group context is used to build the
+     *   shadow name directly — no reverse lookup from persisted state.
+     * @throws Error if the node has no id or the orchestrator subscription fails.
+     */
+    subscribe(callback: (update: ESPNodeUpdateData) => void, node: NodeLike): Promise<void>;
+    /**
+     * Installs a single subscriber for a node. Runs exclusively per node via
+     * {@link runSerial}: the first subscriber constructs the shadow name from the
+     * node's group context, registers the node and attaches one shared
+     * orchestrator listener; later subscribers join the node's existing callback
+     * set.
+     *
+     * @param callback - Subscriber to add.
+     * @param node - The node whose shadow is constructed from its group context.
+     */
+    private installSubscriber;
+    /**
+     * Unsubscribe from a node.
+     *
+     * - No `nodeId`: detach every node.
+     * - `nodeId` only: detach the node and all its subscribers.
+     * - `nodeId` + `callback`: remove just that subscriber; the node stays
+     *   subscribed (and the shared orchestrator listener stays attached) until its
+     *   last subscriber is removed, so sibling subscribers are not affected.
+     *
+     * @param nodeId - Node id to detach; omit to detach all nodes.
+     * @param callback - Optional specific subscriber to remove.
+     */
+    unsubscribe(nodeId?: string, callback?: (update: ESPNodeUpdateData) => void): Promise<void>;
+    /**
+     * Removes a subscriber for a node. Runs exclusively per node via
+     * {@link runSerial}. With a `callback`, only that subscriber is removed and the
+     * node stays subscribed while others remain; once the last subscriber is gone
+     * (or when `callback` is omitted) the node is fully detached.
+     *
+     * @param nodeId - Node id.
+     * @param callback - Specific subscriber to remove, or omit to detach the node.
+     */
+    private removeSubscriber;
+    /**
+     * Detach all listeners. The shared MQTT connection is intentionally left
+     * intact — its lifecycle is owned by the orchestrator / `ESPRMNeoBase`.
+     */
+    dispose(): Promise<void>;
+    /**
+     * Removes this channel's orchestrator listener for a node and clears its
+     * bookkeeping. Only this channel's listener is detached — the orchestrator
+     * idle-cleans the underlying shadow topic once no listeners remain, so a
+     * node's own subscription (e.g. from `ESPRMNeoNode`) is never clobbered.
+     *
+     * @param nodeId - Node id to detach.
+     */
+    private detachNode;
+    /**
+     * Runs `op` exclusively per node: operations for the same nodeId are chained
+     * so they never interleave across an await point, while operations for
+     * different nodes still run concurrently. The caller receives `op`'s own
+     * outcome (success or failure); a failed op does not block later ops.
+     *
+     * @param nodeId - Node whose operations are serialized.
+     * @param op - The operation to run once it reaches the front of the queue.
+     * @returns The result of `op`.
+     */
+    private runSerial;
+}

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

@@ -0,0 +1,213 @@
+import type { MQTTTransport } from "./interfaces/MQTTTransport";
+/**
+ * NodeMQTTOrchestrator - Central MQTT orchestration layer for AWS IoT Device Shadow.
+ *
+ * Design principles:
+ * - Node-agnostic: does not depend on the Node class.
+ * - Single connection: one MQTT client, one message router.
+ * - Deduplicated subscriptions: 30 nodes → maybe 3 shadows → only 3 MQTT subscriptions.
+ * - Nodes = dumb consumers, Orchestrator = brain.
+ */
+export declare class NodeMQTTOrchestrator {
+    private static _instance;
+    /**
+     * Increments every time the orchestrator is (re)initialized — e.g. on a
+     * logout→login cycle, where {@link clear} wipes all subscription state and a
+     * fresh {@link initialize} follows. Subscribers (the MQTT channel) compare
+     * this to detect that their cached listener/topic state is stale and must
+     * be re-attached to the new orchestrator.
+     */
+    private static _generation;
+    private transport;
+    private initialized;
+    /** nodeId → NodeRegistration */
+    private nodeMap;
+    /** shadowName → subscription state */
+    private shadowSubs;
+    /** responseTopic → pending request (for getShadow, getParams) */
+    private pendingRequests;
+    /**
+     * Per-shadow serial op queue. Subscribe / unsubscribe for the same shadow are
+     * chained through this so they never interleave across `await` — otherwise
+     * two concurrent subscribes for the same shadow could both call
+     * `transport.subscribe(...)` and produce duplicate delivery of every message.
+     */
+    private shadowOps;
+    private constructor();
+    /**
+     * Returns the singleton instance.
+     *
+     * @throws {Error} If orchestrator is not initialized.
+     */
+    private static getInstance;
+    /**
+     * Initializes the orchestrator with an MQTT transport. Must be called before
+     * any other method.
+     *
+     * @param transport - MQTT transport for publish/subscribe.
+     * @throws {Error} If already initialized. Call {@link clear} first if you
+     *   truly need to re-init — a silent swap would leave stale in-memory
+     *   subscriptions pointing at topics that were never subscribed on the new
+     *   transport.
+     */
+    static initialize(transport: MQTTTransport): void;
+    /**
+     * Returns the current initialization generation. Increments on each
+     * {@link initialize}. Used by subscription channels to detect a
+     * logout→login reset and re-attach stale listeners.
+     */
+    static getGeneration(): number;
+    /**
+     * Clears the singleton and resets it for re-initialization.
+     * Rejects all pending requests, unsubscribes shadow wildcard topics and
+     * request-response topics, then drops transport and in-memory state.
+     */
+    static clear(): void;
+    /**
+     * Soft-resets session-scoped state without dropping the singleton. Called
+     * from {@link ESPRMNeoUser.logout} so the orchestrator is ready for the
+     * next login without a public re-initialize step. Rejects pending requests,
+     * clears shadow listeners, drops node registrations, and bumps
+     * {@link _generation} so subscription channels detect the reset and
+     * re-attach on next login. Keeps `transport`, `initialized`, and
+     * `_instance` intact so `getInstance()` continues to work.
+     */
+    static resetSession(): void;
+    /**
+     * Registers a node with the orchestrator.
+     * Must be called before subscribeToNode, getParams, getShadow, etc.
+     * On shadow rename: clears the old binding; ignores shorter/incomplete names.
+     * Shrink membership via {@link unregisterNode} first.
+     *
+     * @param nodeId - The device/node identifier.
+     * @param shadowName - The named shadow (e.g. `params-groupId-subgroupId`).
+     */
+    static registerNode(nodeId: string, shadowName: string): void;
+    /**
+     * Unregisters a node. Removes from nodeMap and cleans up listeners.
+     * Unsubscribes from shadow topic if no other nodes use it.
+     *
+     * @param nodeId - The device/node identifier.
+     */
+    static unregisterNode(nodeId: string): void;
+    /**
+     * Checks if a node is registered. Returns `false` if the orchestrator has
+     * not been initialized at all (safe read-only check, matches
+     * {@link getRegisteredNodeCount} — the mutating methods throw instead).
+     *
+     * @param nodeId - The device/node identifier.
+     */
+    static isNodeRegistered(nodeId: string): boolean;
+    /**
+     * Number of registered nodes (for debugging). Returns 0 if not initialized.
+     */
+    static getRegisteredNodeCount(): number;
+    /**
+     * Subscribes to node param updates. Deduplicates MQTT subscriptions by
+     * shadow.
+     *
+     * @param nodeId - The device/node identifier.
+     * @param callback - Callback invoked when shadow update/accepted is received.
+     * @throws {Error} If node is not registered, MQTT is not connected, or the
+     *   underlying transport subscribe fails. On failure no listener is added.
+     */
+    static subscribeToNode(nodeId: string, callback: (params: unknown) => void): Promise<void>;
+    /**
+     * Unsubscribes a callback from a node.
+     *
+     * In-memory listener removal happens even if MQTT is disconnected —
+     * otherwise on reconnect the orchestrator would fan messages out to a stale
+     * listener (per-disconnect leak). The network topic-unsubscribe inside
+     * `cleanupSubscriptionIfIdle` is best-effort and tolerates a missing
+     * connection.
+     *
+     * @param nodeId - The device/node identifier.
+     * @param callback - The callback to remove.
+     */
+    static unsubscribeFromNode(nodeId: string, callback: (params: unknown) => void): Promise<void>;
+    /**
+     * Routes live shadow messages (update/get accepted/rejected, delta) to
+     * listeners. Drops malformed messages at debug level so they're visible in
+     * logs during investigation but don't disrupt healthy traffic.
+     */
+    private handleShadowLiveMessage;
+    /**
+     * Runs `op` exclusively per shadow: operations for the same shadowName are
+     * chained so they never interleave across an await. Ops for different
+     * shadows still run concurrently. Failure of one op does not block later
+     * ops (each op sees its own outcome; the queue only tracks completion).
+     */
+    private runSerial;
+    /**
+     * Request-response helper. Subscribes to accepted + rejected, publishes,
+     * resolves on first message.
+     *
+     * @param publishTopic - Topic to publish the request to.
+     * @param acceptedTopic - Successful response topic.
+     * @param rejectedTopic - Error response topic.
+     * @param payload - Request payload.
+     * @param timeoutMs - Timeout in milliseconds.
+     * @returns Parsed response or rejects on timeout / invalid response / rejected.
+     */
+    private static executeRequestResponse;
+    /**
+     * Fetches the shadow document and extracts a portion via `extractor`.
+     *
+     * @param nodeId - The device/node identifier.
+     * @param extractor - Function to extract desired part from parsed response.
+     * @returns The extracted value.
+     * @throws {Error} If node is not registered.
+     */
+    private static fetchShadowDocument;
+    /**
+     * Wraps `transport.publish` so publish failures throw with an actionable
+     * message. Without this wrapper, callers get whatever the adapter throws
+     * (often a generic `TypeError` from a broken pipe) with no topic context.
+     */
+    private static publishOrThrow;
+    /**
+     * Gets params (`state.reported.params`) for a node.
+     *
+     * @param nodeId - The device/node identifier.
+     * @returns The reported params map, or `{}` when absent.
+     * @throws {Error} If node is not registered.
+     */
+    static getParams(nodeId: string): Promise<Record<string, unknown>>;
+    /**
+     * Gets the full shadow document (`state.reported` + `state.desired`).
+     *
+     * @param nodeId - The device/node identifier.
+     * @returns The full state object.
+     * @throws {Error} If node is not registered.
+     */
+    static getShadow(nodeId: string): Promise<unknown>;
+    /**
+     * Sets params via the RainMaker user params topic (unicast: single node).
+     *
+     * @param nodeId - The device/node identifier.
+     * @param params - Parameter payload (often `{ <deviceId>: { <paramId>: value } }`).
+     * @throws {Error} If node is not registered, MQTT is not connected, or the
+     *   publish fails.
+     */
+    static setParams(nodeId: string, params: unknown): Promise<void>;
+    /**
+     * Publishes parameters to the group control MQTT topic (fan-out to all
+     * devices in the group or in one subgroup). Does not require a registered
+     * node; only a connected MQTT transport (same credentials as unicast
+     * `setParams`).
+     *
+     * @param groupId - Primary group id.
+     * @param params - Same payload shape as {@link NodeMQTTOrchestrator.setParams}.
+     * @param subgroupId - Omit for group-wide broadcast; set to target one
+     *   subgroup.
+     */
+    static setGroupParams(groupId: string, params: unknown, subgroupId?: string): Promise<void>;
+    /**
+     * Updates shadow `state.desired`.
+     *
+     * @param nodeId - The device/node identifier.
+     * @param params - The desired state parameters.
+     * @throws {Error} If node is not registered or transport unavailable.
+     */
+    static updateShadow(nodeId: string, params: unknown): Promise<void>;
+}

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

@@ -0,0 +1,45 @@
+import type { MQTTTransport } from "./interfaces/MQTTTransport";
+/** Pending request for cleanup on clear() */
+export interface PendingRequest {
+    timer: ReturnType<typeof setTimeout>;
+    handler: (topic: string, payload: Buffer) => void;
+    reject: (err: Error) => void;
+    /** MQTT topics this handler was subscribed to (for unsubscribe) */
+    topicsToUnsubscribe: string[];
+}
+/** Shadow subscription state */
+export interface ShadowSubscriptionState {
+    /** All wildcard topics for this shadow (documents/delta/accepted/rejected, get) */
+    topics: string[];
+    listeners: Map<string, Set<(params: unknown) => void>>;
+    subscribed: boolean;
+    handler?: (topic: string, payload: Buffer) => void;
+}
+/**
+ * Clears all pending request-response operations.
+ * Rejects each with the given error and unsubscribes from response topics.
+ *
+ * @param pendingRequests - Map of responseTopic → pending request
+ * @param transport - MQTT transport for unsubscribe
+ * @param rejectError - Error to reject pending promises with
+ */
+export declare function clearAllPendingRequests(pendingRequests: Map<string, PendingRequest>, transport: MQTTTransport | null, rejectError: Error): void;
+/**
+ * Unsubscribes from shadow topic when no listeners remain.
+ * Cleans up subscription state to avoid orphaned MQTT subscriptions.
+ *
+ * @param subscription - The shadow subscription state
+ * @param transport - MQTT transport for unsubscribe
+ * @returns true if unsubscribed, false otherwise
+ */
+export declare function cleanupSubscriptionIfIdle(subscription: ShadowSubscriptionState, transport: MQTTTransport | null): boolean;
+/**
+ * Invokes all listeners with the given params.
+ * Isolates errors from individual listeners so one failure cannot block the
+ * others. Logs the actual error (and the params for context) so investigators
+ * can see WHY a listener failed, not just THAT one did.
+ *
+ * @param listeners - Set of callback functions
+ * @param params - The params to pass to each listener
+ */
+export declare function notifyListenersSafely(listeners: Set<(params: unknown) => void>, params: unknown): void;

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

@@ -0,0 +1,21 @@
+import { ESPNodeUpdateData } from "../types/subscription";
+type NodeUpdateListener = (update: ESPNodeUpdateData) => void;
+/**
+ * Registers a listener for all node updates.
+ *
+ * @param listener - Invoked with each {@link ESPNodeUpdateData}.
+ * @returns An unsubscribe function that removes the listener.
+ */
+export declare function subscribeNodeUpdates(listener: NodeUpdateListener): () => void;
+/**
+ * Emits a node update to every registered listener. Listener errors are isolated
+ * so one bad subscriber cannot break delivery to the others.
+ *
+ * @param update - The normalized update to broadcast.
+ */
+export declare function emitNodeUpdate(update: ESPNodeUpdateData): void;
+/**
+ * Removes all listeners. Intended for teardown/tests.
+ */
+export declare function clearNodeUpdateListeners(): void;
+export {};

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

@@ -0,0 +1,41 @@
+/**
+ * Public SDK service surface.
+ *
+ * Two categories of "internal" code, treated differently:
+ *
+ * 1. Stateful services (API managers, storage, MQTT engines, transports,
+ *    orchestrators) — kept internal. They hold shared state or lifecycle and
+ *    exposing them lets consumers reach into private plumbing. Use the
+ *    domain classes (ESPRMNeoUser, ESPRMNeoGroup, ESPRMNeoNode, etc.) to
+ *    reach any behaviour these internals implement.
+ *
+ * 2. Pure stateless utilities (JWT decoders, capability predicates,
+ *    shadow-topic builders, ncfg-version helpers) — exposed via
+ *    `utils/export.ts`. No state, no lifecycle; hiding them just forces
+ *    consumers to reinvent them.
+ *
+ * If you want to re-export a stateful service here, ask first whether the
+ * domain classes should grow a wrapper for it instead. Stateless utilities
+ * go directly in `utils/export.ts`.
+ */
+/**
+ * Subscription manager — accessed by consumers via `ESPRMNeoBase.subscriptionManager`.
+ * The type must be public so that getter's return type is usable in app code.
+ */
+export { ESPRMNeoSubscriptionManager } from "./ESPRMNeoSubscriptionManager";
+/**
+ * MQTT transport contract that app-supplied MQTT adapters must satisfy.
+ * Consumed by apps passing an adapter via `ESPRMNeoBaseConfig.mqttAdapter`.
+ */
+export type { MQTTTransport } from "./interfaces/MQTTTransport";
+/**
+ * Canonical event type emitted by every subscription channel when a node's
+ * params change. Public so consumers can pattern-match on incoming updates.
+ */
+export { NODE_PARAMS_CHANGED_EVENT } from "./ESPRMNeoHelpers/transformShadowToNodeUpdate";
+/**
+ * Time-series fetcher entry points. Public so consumers can compose their
+ * own custom pagination flows on top of {@link ESPRMNeoDeviceParam.getRawTSData}.
+ */
+export { fetchRawTSData, fetchLatestTSData, fetchAggregatedTSData, } from "./ESPRMNeoHelpers/FetchTSData";
+export type { FetchTSDataConfig } from "./ESPRMNeoHelpers/FetchTSData";

package/dist/types/services/interfaces/MQTTTransport.d.ts

@@ -0,0 +1,62 @@
+import type { ESPMQTTConfig } from "../ESPRMNeoMqtt/ESPMQTTConfig";
+/**
+ * MQTT Transport interface - abstraction over MQTT client.
+ * Used by NodeMQTTOrchestrator for all MQTT operations.
+ */
+export interface MQTTTransport {
+    /**
+     * Connect to MQTT using the provided configuration.
+     *
+     * @param config - MQTT configuration
+     */
+    connect(config: ESPMQTTConfig): Promise<void>;
+    /**
+     * Disconnect from MQTT.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Check if the 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
+     *
+     * @remarks
+     * The handler function reference is used to manage subscriptions.
+     * The same handler must be passed to `unsubscribe` to remove it.
+     */
+    subscribe(topic: string, handler: (topic: string, payload: Buffer) => void): Promise<void>;
+    /**
+    * Unsubscribe from a topic.
+    *
+    * @param topic - MQTT topic to unsubscribe from
+    * @param handler - Optional handler to remove
+    *
+    * @remarks
+    * If a handler was provided during subscription, the same function reference
+    * must be passed to successfully unsubscribe it.
+    *
+    * Passing a different function (even if identical in implementation) will not
+    * remove the original handler.
+    *
+    * If handler is omitted, all handlers for the topic may be removed,
+    * depending on the implementation.
+    */
+    unsubscribe(topic: string, handler?: (topic: string, payload: Buffer) => void): Promise<void>;
+    /**
+    * @remarks
+    * Optional helper for request-response patterns. Invokes the handler once
+    * and auto-unsubscribes. Not required by NodeMQTTOrchestrator.
+    */
+    once?(topic: string, handler: (topic: string, payload: Buffer) => void): Promise<void>;
+}