@espressif/rainmaker-neo-base-sdk 1.0.0

package/dist/esm/utils/waitForNodeOnline.js

@@ -0,0 +1,182 @@
+import { ESPRMNeoMqtt } from '../services/ESPRMNeoMqtt/ESPRMNeoMqtt.js';
+import { NodeMQTTOrchestrator } from '../services/NodeMQTTOrchestrator.js';
+import { ProvErrorCodes } from './constants.js';
+import { ESPProvError } from './error/ESPProvError.js';
+import { constructShadowName } from './shadowUtils.js';
+import { Logger } from './logger.js';
+
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const logger = new Logger("waitForNodeOnline");
+/** Default max wait after WiFi provisioning before rejecting (2 minutes). */
+const DEFAULT_NODE_ONLINE_TIMEOUT_MS = 120_000;
+/** Interval between shadow GET polls while waiting (matches app_sim). */
+const DEFAULT_NODE_ONLINE_POLL_INTERVAL_MS = 5_000;
+/**
+ * Creates a promise with externally accessible `resolve` / `reject` handles.
+ * Used so MQTT callbacks and the timeout timer can settle the same wait.
+ */
+function createDeferred() {
+    let resolve;
+    let reject;
+    const promise = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+    return { promise, resolve, reject };
+}
+/**
+ * Schedules a one-shot timeout that rejects the online wait with {@link ESPProvError}.
+ * No-ops if the wait already settled (MQTT success, GET poll, or duplicate event).
+ */
+function createOnlineTimeout(nodeId, timeoutMs, reject, isSettled, markSettled) {
+    return setTimeout(() => {
+        if (isSettled()) {
+            return;
+        }
+        markSettled();
+        logger.error("Timed out waiting for node to come online", {
+            nodeId,
+            timeoutMs,
+        });
+        reject(new ESPProvError(ProvErrorCodes.NODE_ONLINE_TIMEOUT));
+    }, timeoutMs);
+}
+/**
+ * Detects online status from a shadow MQTT payload or getShadow state slice.
+ *
+ * Live MQTT messages use `{ state: { reported: { online: true } } }`.
+ * {@link NodeMQTTOrchestrator.getShadow} returns `{ reported: { online: true } }`.
+ */
+function isNodeOnlineFromShadowPayload(payload) {
+    const data = payload;
+    return (data?.state?.reported?.online === true || data?.reported?.online === true);
+}
+/**
+ * Subscribes to shadow MQTT for `nodeId`, polls getShadow on an interval, resolves
+ * when `online: true`, then unsubscribes and unregisters the temporary node binding
+ * (if owned).
+ *
+ * @throws {ESPProvError} If `timeoutMs` elapses without the node reporting online.
+ * @throws {Error} If MQTT connection or subscription fails.
+ */
+async function waitForNodeOnline({ nodeId, groupId, user, timeoutMs = DEFAULT_NODE_ONLINE_TIMEOUT_MS, pollIntervalMs = DEFAULT_NODE_ONLINE_POLL_INTERVAL_MS, }) {
+    const shadowName = constructShadowName(groupId);
+    logger.info("Waiting for node to come online", {
+        nodeId,
+        groupId,
+        shadowName,
+        timeoutMs,
+        pollIntervalMs,
+    });
+    // Guards against resolving/rejecting more than once (MQTT vs poll vs timeout race).
+    let settled = false;
+    const isSettled = () => settled;
+    const markSettled = () => {
+        settled = true;
+    };
+    const online = createDeferred();
+    const settleOnline = (source) => {
+        if (isSettled()) {
+            return;
+        }
+        markSettled();
+        logger.info("Node reported online", { nodeId, source });
+        online.resolve();
+    };
+    /** MQTT shadow callback — resolves the wait when `state.reported.online` becomes true. */
+    const onUpdate = (payload) => {
+        if (!isNodeOnlineFromShadowPayload(payload)) {
+            return;
+        }
+        settleOnline("mqtt");
+    };
+    /** Polls getShadow; ignores missing-shadow errors (expected right after provision). */
+    const pollShadowOnce = async () => {
+        if (isSettled()) {
+            return;
+        }
+        try {
+            const shadow = await NodeMQTTOrchestrator.getShadow(nodeId);
+            if (isNodeOnlineFromShadowPayload(shadow)) {
+                settleOnline("shadow_get");
+            }
+        }
+        catch (error) {
+            logger.debug("Shadow get while waiting for online failed; will retry", {
+                nodeId,
+                error,
+            });
+        }
+    };
+    // Avoid wiping a registration owned by ESPRMNeoNode / subscription channel.
+    const alreadyRegistered = NodeMQTTOrchestrator.isNodeRegistered(nodeId);
+    let timer;
+    let pollTimer;
+    /** Clears timers, unsubscribes our callback; unregisters only if we created the binding. */
+    const cleanup = async () => {
+        if (timer !== undefined) {
+            clearTimeout(timer);
+        }
+        if (pollTimer !== undefined) {
+            clearInterval(pollTimer);
+        }
+        try {
+            await NodeMQTTOrchestrator.unsubscribeFromNode(nodeId, onUpdate);
+            if (!alreadyRegistered) {
+                NodeMQTTOrchestrator.unregisterNode(nodeId);
+            }
+            logger.debug("Cleaned up temporary MQTT subscription", { nodeId });
+        }
+        catch (error) {
+            logger.warn("Failed to clean up temporary MQTT subscription", {
+                nodeId,
+                error,
+            });
+        }
+    };
+    try {
+        // 1. Ensure MQTT connectivity
+        const mqttConnected = ESPRMNeoMqtt.hasInstance() && (await ESPRMNeoMqtt.getInstance().isConnected());
+        if (!mqttConnected) {
+            logger.debug("MQTT not connected; connecting before online wait", {
+                nodeId,
+            });
+            await user.connectMQTT();
+        }
+        // 2. Register (if needed) and subscribe before the shadow may exist
+        if (!alreadyRegistered) {
+            NodeMQTTOrchestrator.registerNode(nodeId, shadowName);
+        }
+        await NodeMQTTOrchestrator.subscribeToNode(nodeId, onUpdate);
+        logger.debug("Subscribed to node shadow for online wait", {
+            nodeId,
+            shadowName,
+        });
+        // 3. Start timeout only after we are listening
+        timer = createOnlineTimeout(nodeId, timeoutMs, online.reject, isSettled, markSettled);
+        // 4. Immediate GET + interval poll (app_sim pattern); MQTT updates also settle
+        await pollShadowOnce();
+        if (!isSettled()) {
+            pollTimer = setInterval(() => {
+                void pollShadowOnce();
+            }, pollIntervalMs);
+        }
+        // 5. Wait until MQTT update, successful GET, or timeout
+        await online.promise;
+    }
+    catch (error) {
+        markSettled();
+        logger.error("Error while waiting for node to come online", error);
+        throw error;
+    }
+    finally {
+        await cleanup();
+    }
+}
+
+export { DEFAULT_NODE_ONLINE_POLL_INTERVAL_MS, DEFAULT_NODE_ONLINE_TIMEOUT_MS, isNodeOnlineFromShadowPayload, waitForNodeOnline };
+//# sourceMappingURL=waitForNodeOnline.js.map

package/dist/esm/utils/waitForNodeOnline.js.map

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

package/dist/types/ESPDevice.d.ts

@@ -0,0 +1,13 @@
+import { ESPDeviceInterface, ESPProvisionAdapterInterface } from "./types/provision";
+/**
+ * Represents an ESP device for provisioning and local communication.
+ * Provides methods for device discovery and WiFi provisioning.
+ */
+export declare class ESPDevice implements ESPDeviceInterface {
+    private _espProvisionAdapter?;
+    get ESPProvisionAdapter(): ESPProvisionAdapterInterface;
+    name: string;
+    transport: string;
+    security: number;
+    constructor(deviceConfig: ESPDeviceInterface);
+}

package/dist/types/ESPRMNeoAuth.d.ts

@@ -0,0 +1,26 @@
+import { ESPRMNeoBaseConfig, UserTokensData } from "./types/input";
+export { ESPAuthError } from "./utils/error/ESPAuthError";
+/**
+ * The `ESPRMNeoAuth` class provides authentication functionality via the
+ * RainMaker User Auth API. Key features include:
+ *
+ * - **Sign-Up Process**: Methods to send sign-up codes and confirm user registration.
+ * - **Password Management**: Support for password recovery, setting new passwords, and login with credentials.
+ * - **Session Management**: Provides functionality to fetch details of the currently logged-in user.
+ */
+export declare class ESPRMNeoAuth {
+    private _config;
+    constructor(config: ESPRMNeoBaseConfig);
+    /**
+     * Returns the SDK config this auth instance was constructed with.
+     * Prefer this over {@link ESPRMNeoBase.getConfig} in auth method implementations.
+     */
+    getConfig(): Readonly<ESPRMNeoBaseConfig>;
+    /**
+     * Gets refreshed tokens using a refresh token without persisting them.
+     *
+     * Calls `POST /v1/user/auth/token/refresh` (unauthenticated; the backend
+     * validates `refresh_token` in the body only).
+     */
+    static getRefreshedTokens(refreshToken: string): Promise<UserTokensData>;
+}

package/dist/types/ESPRMNeoAutomation.d.ts

@@ -0,0 +1,17 @@
+import { AutomationItem, AutomationConditions, AutomationActions, AutomationStatus } from "./types/automation";
+import { ESPRMNeoGroup } from "./ESPRMNeoGroup";
+/**
+ * Represents an automation in the ESP Rainmaker Neo SDK.
+ * Provides instance methods for automation operations.
+ */
+export declare class ESPRMNeoAutomation {
+    id: string;
+    groupId: string;
+    name: string;
+    conditions: AutomationConditions;
+    actions: AutomationActions;
+    /** Enable/disable flag. Defaults to "enabled" when absent (backend default). */
+    status?: AutomationStatus;
+    retrigger?: boolean;
+    constructor(data: AutomationItem, group: ESPRMNeoGroup);
+}

package/dist/types/ESPRMNeoBase.d.ts

@@ -0,0 +1,169 @@
+import { ESPRMNeoAuth } from "./ESPRMNeoAuth";
+import { ESPRMNeoBaseConfig } from "./types/input";
+import { ESPStorageAdapter } from "./types/storage";
+import { ESPProvisionAdapterInterface } from "./types/provision";
+import { ESPRMNeoSubscriptionManager } from "./services/ESPRMNeoSubscriptionManager";
+import type { ESPLocalControlAdapterInterface } from "./types/localControl";
+import type { ESPLocalDiscoveryAdapterInterface } from "./types/discovery";
+import { ESPTransportMode } from "./types/transport";
+/**
+ * Configures and manages the ESP RainMaker Neo SDK.
+ *
+ * Holds process-wide configuration, adapters, and auth state. Call
+ * {@link ESPRMNeoBase.configure} once before using other SDK APIs.
+ * Low-level initialization helpers live in `utils/baseUtils`.
+ */
+export declare class ESPRMNeoBase {
+    #private;
+    /** Auth instance created during {@link configure}. */
+    private static authInstance;
+    /** Subscription manager created during {@link configure}. */
+    private static _subscriptionManager;
+    private static _storageAdapter?;
+    private static _provisionAdapter?;
+    private static _localControlAdapter?;
+    /**
+     * App-supplied adapter for local (LAN / mDNS) discovery.
+     * Used when an app subscribes to `localDiscovery` via {@link ESPRMNeoUser.subscribe}.
+     * Access via {@link getLocalDiscoveryAdapter}.
+     */
+    private static _localDiscoveryAdapter?;
+    /**
+     * Global default transport priority order.
+     * Each node copies this at construction; apps may override globally via
+     * {@link setTransportOrder} or per-node via `ESPRMNeoNode.setTransportOrder`.
+     */
+    private static globalTransportOrder;
+    /**
+     * Configures the ESP RainMaker Neo SDK with the given options.
+     * Must be called before using any other SDK functionality.
+     *
+     * If the SDK is already configured, previous state is disposed first so
+     * re-configure is safe.
+     *
+     * @param config - Base URL (include API Gateway stage if any), Cognito/IoT
+     *   settings, and optional adapters.
+     * @throws {Error} If the configuration is invalid or initialization fails.
+     */
+    static configure(config: ESPRMNeoBaseConfig): void;
+    /**
+     * Initializes the ESP RainMaker Neo SDK with the given configuration.
+     * Back-compat alias for {@link configure}.
+     *
+     * @param config - Same options as {@link configure}.
+     */
+    static init(config: ESPRMNeoBaseConfig): void;
+    /**
+     * Disposes SDK state and resets peer singletons so {@link configure} can run again.
+     * Prefer this over `jest.resetModules()` when tearing down in tests.
+     */
+    static dispose(): void;
+    /**
+     * Returns a readonly copy of the current SDK configuration.
+     *
+     * @returns Frozen shallow copy of the active config.
+     * @throws {Error} If the SDK has not been initialized.
+     */
+    static getConfig(): Readonly<ESPRMNeoBaseConfig>;
+    /**
+     * Returns the authentication instance for the SDK.
+     *
+     * @returns The {@link ESPRMNeoAuth} instance used for auth operations.
+     * @throws {Error} If the SDK has not been initialized.
+     */
+    static getAuthInstance(): ESPRMNeoAuth;
+    /**
+     * Returns the subscription manager instance.
+     *
+     * @returns The {@link ESPRMNeoSubscriptionManager} for managing subscriptions.
+     * @throws {Error} If the SDK has not been initialized.
+     */
+    static get subscriptionManager(): ESPRMNeoSubscriptionManager;
+    /**
+     * Sets the storage adapter for the SDK and re-initializes persistent storage.
+     *
+     * @param adapter - Adapter implementing {@link ESPStorageAdapter}.
+     * @throws {Error} If the SDK is not initialized or the adapter is invalid.
+     */
+    static setStorageAdapter(adapter: ESPStorageAdapter): void;
+    /**
+     * Gets the current storage adapter, if any.
+     *
+     * @returns The configured {@link ESPStorageAdapter}, or `undefined`.
+     */
+    static get storageAdapter(): ESPStorageAdapter | undefined;
+    /**
+     * Sets the storage adapter for the SDK.
+     *
+     * Prefer {@link setStorageAdapter} for clearer call sites.
+     *
+     * @param adapter - Adapter implementing {@link ESPStorageAdapter}.
+     */
+    static set storageAdapter(adapter: ESPStorageAdapter);
+    /**
+     * Sets the provisioning adapter for the SDK.
+     *
+     * @param adapter - Adapter implementing {@link ESPProvisionAdapterInterface}.
+     * @throws {Error} If the SDK is not initialized or the adapter is invalid.
+     */
+    static setProvisioningAdapter(adapter: ESPProvisionAdapterInterface): void;
+    /**
+     * Gets the provisioning adapter.
+     *
+     * @returns The provisioning adapter, or `undefined` if not configured.
+     */
+    static getProvisionAdapter(): ESPProvisionAdapterInterface | undefined;
+    /**
+     * Sets the local control adapter used to talk to nodes over the LAN via
+     * the `esp_local_ctrl` protocol.
+     *
+     * @param adapter - Adapter implementing {@link ESPLocalControlAdapterInterface}.
+     * @throws {Error} If the SDK is not initialized or the adapter is invalid.
+     */
+    static setLocalControlAdapter(adapter: ESPLocalControlAdapterInterface): void;
+    /**
+     * Gets the local control adapter.
+     *
+     * @returns The local control adapter, or `undefined` if not configured.
+     */
+    static getLocalControlAdapter(): ESPLocalControlAdapterInterface | undefined;
+    /**
+     * Sets the local discovery adapter used to browse for nodes on the LAN
+     * (mDNS). Required before subscribing to `localDiscovery` via
+     * {@link ESPRMNeoUser.subscribe}.
+     *
+     * @param adapter - Adapter implementing {@link ESPLocalDiscoveryAdapterInterface}.
+     * @throws {Error} If the SDK is not initialized or the adapter is invalid.
+     */
+    static setLocalDiscoveryAdapter(adapter: ESPLocalDiscoveryAdapterInterface): void;
+    /**
+     * Gets the local discovery adapter.
+     *
+     * @returns The local discovery adapter, or `undefined` if not configured.
+     */
+    static getLocalDiscoveryAdapter(): ESPLocalDiscoveryAdapterInterface | undefined;
+    /**
+     * Sets the global default transport priority order.
+     * New nodes adopt this order at construction; existing nodes keep their
+     * current order unless updated per-node via `ESPRMNeoNode.setTransportOrder`.
+     *
+     * @param order - Non-empty ordered list of transport modes (built-in
+     *   {@link ESPTransportMode} values or custom string keys).
+     * @throws {ESPConfigError} If the order is empty or not an array.
+     */
+    static setTransportOrder(order: (ESPTransportMode | string)[]): void;
+    /**
+     * Returns a copy of the global default transport priority order.
+     *
+     * @returns Shallow copy of the current transport order.
+     */
+    static getTransportOrder(): (ESPTransportMode | string)[];
+}
+/**
+ * Test / teardown helper: clears Base state and peer singletons so
+ * {@link ESPRMNeoBase.configure} can run again. Prefer this over
+ * `jest.resetModules()`. Not re-exported from the public SDK barrel.
+ *
+ * @internal
+ */
+export declare function resetForTests(): void;

package/dist/types/ESPRMNeoDevice.d.ts

@@ -0,0 +1,31 @@
+import type { ESPRMNeoNode } from "./ESPRMNeoNode";
+import { ESPRMNeoDeviceParam } from "./ESPRMNeoDeviceParam";
+import type { ESPRMNeoDeviceInterface, ESPRMNeoAttributeInterface } from "./types/node";
+/**
+ * Logical device inside a node (e.g. switch, light, thermostat).
+ * Holds a WeakRef to the parent node for delegating getParams/setParams.
+ */
+export declare class ESPRMNeoDevice implements ESPRMNeoDeviceInterface {
+    readonly name: string;
+    readonly displayName: string;
+    readonly type: string;
+    readonly attributes?: ESPRMNeoAttributeInterface[];
+    readonly params: ESPRMNeoDeviceParam[];
+    readonly primaryParam?: ESPRMNeoDeviceParam;
+    readonly _nodeRef: WeakRef<ESPRMNeoNode>;
+    constructor(data: Omit<ESPRMNeoDeviceInterface, "params" | "primaryParam"> & {
+        params?: Array<{
+            id: string;
+            type?: string;
+            properties?: string[];
+            dataType: string;
+            deviceName?: string;
+            uiType?: string;
+            bounds?: Record<string, unknown>;
+            validStrings?: string[];
+        }>;
+        primary?: string;
+    }, nodeRef: WeakRef<ESPRMNeoNode>);
+    /** Parent node, if the weak reference is still alive. */
+    getNode(): ESPRMNeoNode | undefined;
+}

package/dist/types/ESPRMNeoDeviceParam.d.ts

@@ -0,0 +1,25 @@
+import type { ESPRMNeoNode } from "./ESPRMNeoNode";
+import type { ESPAPIResponse } from "./types/output";
+import type { ESPRMNeoDeviceParamInterface, ESPRMNeoParamInterface } from "./types/node";
+/**
+ * Device parameter – one controllable parameter of a device (e.g. Power, Brightness).
+ * Holds a WeakRef to the parent node so writes can be dispatched via the best
+ * available transport (see {@link delegatedTransportHandler}).
+ */
+export declare class ESPRMNeoDeviceParam implements ESPRMNeoDeviceParamInterface {
+    readonly id: string;
+    readonly type: string;
+    readonly properties: string[];
+    readonly dataType: string;
+    readonly deviceName: string;
+    readonly uiType?: string;
+    readonly bounds?: Record<string, unknown>;
+    readonly validStrings?: string[];
+    value?: any;
+    readonly _nodeRef: WeakRef<ESPRMNeoNode>;
+    constructor(data: ESPRMNeoParamInterface & {
+        deviceName: string;
+        uiType?: string;
+    }, nodeRef: WeakRef<ESPRMNeoNode>);
+    setValue(value: any): Promise<ESPAPIResponse>;
+}

package/dist/types/ESPRMNeoGroup.d.ts

@@ -0,0 +1,26 @@
+import { ESPRMNeoGroup as ESPRMNeoGroupData, GroupUserAccessType, NodeCapabilityInfo } from "./types/output";
+/** True when this instance is a nested group (child of another group). */
+export declare function isChildGroup(g: ESPRMNeoGroup): boolean;
+/**
+ * Represents a group in the ESP Rainmaker Neo SDK.
+ * Nested groups are also `ESPRMNeoGroup` instances with `parentId` set.
+ *
+ * Instance methods (attached via prototype in `methods/ESPRMNeoGroup/`):
+ *   - Membership: `addNode`, `removeNode`, `getNode`, `getNodes`
+ *   - Lifecycle:  `updateName`, `delete`, `leave`, `createSubGroup`
+ *   - Sharing:    `share`, `getSharingInfo`, `removeMember`
+ *   - Params:     `setParams`
+ *   - Schedules:  `getSchedules`, `createSchedule`, `deleteAllSchedules`
+ *   - Automation: `createAutomation`, `getAutomation`, `getAutomations`
+ */
+export declare class ESPRMNeoGroup implements ESPRMNeoGroupData {
+    groupId: string;
+    groupName: string;
+    accessType?: GroupUserAccessType;
+    /** Present only when this instance is a nested group (see {@link isChildGroup}). */
+    parentId?: string;
+    nodeIds: string[];
+    subgroups: ESPRMNeoGroup[];
+    nodeDetails: Record<string, NodeCapabilityInfo>;
+    constructor(data: ESPRMNeoGroupData);
+}

package/dist/types/ESPRMNeoNode.d.ts

@@ -0,0 +1,142 @@
+import { NodeConfig, NodeConfigAPI } from "./types/output";
+import type { ESPRMNeoConnectivityStatusInterface } from "./types/node";
+import type { ESPNodeSubscriptionConfig } from "./types/subscription";
+import { ESPRMNeoService } from "./ESPRMNeoService";
+import { ESPRMNeoDevice } from "./ESPRMNeoDevice";
+import { ESPTransportMode, ESPTransportConfig, ESPTransportInterface } from "./types/transport";
+/**
+ * Represents a node in the ESP Rainmaker Neo SDK.
+ * Provides access to node configuration and metadata.
+ *
+ * Live updates arrive via the subscription manager
+ * (`subscribeToNode` → {@link handleNodeUpdate}) and are re-broadcast on the
+ * process-wide node-updates bus for `user.subscribe(nodeUpdates)`.
+ */
+export declare class ESPRMNeoNode {
+    nodeId: string;
+    config: NodeConfig;
+    /** API/cache snapshot (snake_case devices/services) used for local persistence. */
+    private wireConfig;
+    groupId: string;
+    /** All subgroup IDs this node belongs to under {@link groupId} (shadow segment order from {@link constructShadowName}). Empty when the node lives only at the root group. */
+    subgroupIds: string[];
+    devices: ESPRMNeoDevice[];
+    services: ESPRMNeoService[];
+    connectivityStatus: ESPRMNeoConnectivityStatusInterface;
+    /**
+     * Transports currently usable for this node, keyed by mode.
+     * - `mqtt` (cloud) is added when the node reports online and removed when
+     *   it goes offline (via shadow updates or seeded `connectivity_status`).
+     * - `local` is added/removed at runtime by a `localDiscovery` subscriber as the
+     *   node appears/disappears on the LAN (via {@link addTransport}/{@link removeTransport}).
+     * Apps may also add custom string-keyed entries (pair with
+     * {@link customTransportManagers}).
+     */
+    availableTransports: Record<ESPTransportMode | string, ESPTransportConfig>;
+    /**
+     * Transport priority order for this node. Initialized from the global default
+     * ({@link ESPRMNeoBase.getTransportOrder}); override per-node via
+     * {@link setTransportOrder}.
+     */
+    transportOrder: (ESPTransportMode | string)[];
+    /**
+     * Optional per-node custom transport implementations keyed by mode. When a
+     * mode in {@link transportOrder} has an entry here, the transport handler uses
+     * it in preference to the built-in local/MQTT backends. Enables BLE, WebSocket
+     * or proprietary transports without modifying the SDK.
+     */
+    customTransportManagers?: Record<ESPTransportMode | string, ESPTransportInterface>;
+    /**
+     * Optional per-node subscription channel order, overriding the global order
+     * on {@link ESPRMNeoBase.subscriptionManager}. Set and read via the
+     * `setSubscriptionChannelOrder` / `getSubscriptionChannelOrder` methods
+     * added by module augmentation in
+     * `src/methods/ESPRMNeoNode/SubscriptionConfig.ts`.
+     */
+    subscriptionConfig?: ESPNodeSubscriptionConfig;
+    constructor(config: NodeConfigAPI, groupId: string, subgroupIdOrIds?: string | string[]);
+    /**
+     * Adds (or replaces) an available transport for this node, keyed by mode.
+     * Works for built-in modes ({@link ESPTransportMode}) and custom string modes.
+     * For a custom transport, also register its implementation via
+     * {@link addCustomTransportManager}.
+     *
+     * @param mode - Transport mode key (e.g. `local`, `mqtt`, or a custom string).
+     * @param config - The transport config (`{ type, metadata }`).
+     */
+    addTransport(mode: ESPTransportMode | string, config: ESPTransportConfig): void;
+    /**
+     * Removes an available transport for this node by mode.
+     *
+     * @param mode - Transport mode key to remove.
+     */
+    removeTransport(mode: ESPTransportMode | string): void;
+    /**
+     * Registers (or replaces) a custom transport manager for a mode. The transport
+     * handler prefers it over the built-in backend for that mode. Pair with
+     * {@link addTransport} so the mode also appears in {@link availableTransports}
+     * and participates in {@link transportOrder}.
+     *
+     * @param mode - Transport mode key the manager handles.
+     * @param manager - Implementation of {@link ESPTransportInterface}.
+     */
+    addCustomTransportManager(mode: ESPTransportMode | string, manager: ESPTransportInterface): void;
+    /**
+     * Removes the custom transport manager registered for a mode (if any).
+     *
+     * @param mode - Transport mode key to clear.
+     */
+    removeCustomTransportManager(mode: ESPTransportMode | string): void;
+    /**
+     * Overrides the transport priority order for this node only.
+     *
+     * @param order - Non-empty ordered list of transport modes.
+     * @throws {ESPConfigError} If the order is empty or not an array.
+     */
+    setTransportOrder(order: (ESPTransportMode | string)[]): void;
+    /**
+     * Replaces config and rebuilds devices/services (used after cloud sync).
+     *
+     * Sets {@link config} so `config.devices` / `config.services` are the same
+     * live {@link ESPRMNeoDevice} / {@link ESPRMNeoService} instances as
+     * {@link devices} / {@link services}.
+     */
+    applyNodeConfig(config: NodeConfigAPI): void;
+    getShadowName(): string;
+    /**
+     * RainMaker params channel: rainmaker/nodes/{nodeId}/user/{shadowName}/params
+     */
+    getParamsTopic(): string;
+    /**
+     * Registers this node with the MQTT orchestrator and subscribes via the
+     * subscription manager so the highest-priority available channel serves it
+     * (MQTT today; Matter/BLE when a satellite SDK registers one). Fire-and-forget
+     * from the constructor — failures are logged, not thrown.
+     */
+    private subscribeToMqttUpdates;
+    /**
+     * Handles a normalized update from the subscription manager: applies it to the
+     * node's internal state (via {@link processNodeUpdate}) and re-broadcasts it on
+     * the process-wide node-updates bus for `user.subscribe(nodeUpdates)`.
+     *
+     * For MQTT the full shadow is carried in `metadata.shadow`, so internal
+     * bookkeeping (params + connectivity + config version) is unchanged. For a
+     * channel that only provides a param map, a minimal shadow is reconstructed.
+     *
+     * @param update - The normalized node update.
+     */
+    private handleNodeUpdate;
+    /**
+     * Applies a shadow update: devices/services params, connectivity, cache.
+     * If `ncfg_ver` changed, {@link ESPRMNeoNode#sync} → {@link applyNodeConfig}.
+     */
+    private processNodeUpdate;
+    /**
+     * Updates {@link connectivityStatus} and MQTT transport availability when the
+     * shadow reports `online`. Partial updates without `online` are ignored so
+     * an existing status is not cleared.
+     */
+    private applyConnectivityStatus;
+    /** When cloud `ncfg_ver` changes, refetch config and persist the new marker. */
+    private refreshConfigIfNcfgChanged;
+}

package/dist/types/ESPRMNeoSchedule.d.ts

@@ -0,0 +1,36 @@
+import { ScheduleItem, ScheduleTrigger, ScheduleActionMap } from "./types/schedule";
+import { ESPRMNeoNode } from "./ESPRMNeoNode";
+import { ESPRMNeoGroup } from "./ESPRMNeoGroup";
+/**
+ * Represents a schedule in the ESP Rainmaker Neo SDK.
+ * Provides instance methods for schedule operations.
+ */
+export declare class ESPRMNeoSchedule {
+    id: string;
+    name?: string;
+    nodeId: string;
+    groupId: string;
+    enabled: boolean;
+    triggers: ScheduleTrigger[];
+    action: ScheduleActionMap;
+    validity?: {
+        start?: number;
+        end?: number;
+    };
+    private node?;
+    private group?;
+    constructor(schedule: ScheduleItem, nodeId: string, groupId: string, id?: string, node?: ESPRMNeoNode, group?: ESPRMNeoGroup);
+    /**
+     * Gets the node instance for this schedule.
+     * Returns the direct node reference when set, otherwise resolves it via the
+     * group. Returns `null` when neither path yields a node.
+     */
+    getNode(): Promise<ESPRMNeoNode | null>;
+    /**
+     * Generates a schedule id when the caller doesn't provide one.
+     * 4-char base36 tail (a-z, 0-9) — ~1.6M values per node. Duplicate ids
+     * inside a single node's list are still guarded against at create-time by
+     * {@link ESPRMNeoNode.createSchedule}.
+     */
+    private static generateId;
+}