@espressif/rainmaker-neo-base-sdk 1.0.0 → 1.2.0

package/dist/esm/utils/eventSubscriptionUtils.js

@@ -1,26 +1,70 @@
 import { ESPDiscoveryManager } from '../services/ESPTransport/ESPDiscovery/ESPDiscoveryManager.js';
 import { subscribeNodeUpdates } from '../services/NodeUpdatesBus.js';
-import { ESPTransportMode } from '../types/transport.js';
+import { ESPLocalControlProtocol, ESPTransportMode } from '../types/transport.js';
+import { RMakerLocalCtrlCapability, RMakerLocalCtrlTxtKey } from './constants.js';
 
 /*
  * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
-/** Maps a default local-discovery hit into the client-facing payload shape. */
+/**
+ * Splits the mDNS `cap` TXT record (`"local_ctrl,ch_resp"`) into tokens.
+ * Returns `undefined` when the record is absent, which older firmware omits.
+ */
+function parseCapabilities(txt) {
+    const raw = txt?.[RMakerLocalCtrlTxtKey.CAP];
+    if (typeof raw !== "string")
+        return undefined;
+    const capabilities = raw
+        .split(",")
+        .map((capability) => capability.trim())
+        .filter(Boolean);
+    return capabilities.length ? capabilities : undefined;
+}
+/**
+ * Maps a default local-discovery hit into the client-facing payload shape.
+ *
+ * The `_esp_rmaker_ctrl._tcp` instance is also advertised by nodes that
+ * only serve challenge-response (on-network user-node association). Those are
+ * not reachable for param control, so a hit whose `cap` TXT record excludes
+ * `local_ctrl` maps to `undefined` and is dropped rather than registered as a
+ * local transport. A hit with no `cap` record is treated as control-capable.
+ *
+ * @param info - Raw adapter result (`nodeId`, `baseUrl`, and `txt` when the
+ *   platform resolved TXT records).
+ * @returns The payload to deliver, or `undefined` to skip this hit.
+ */
 function toDiscoveredNodeData(info) {
+    const capabilities = parseCapabilities(info.txt);
+    if (capabilities &&
+        !capabilities.includes(RMakerLocalCtrlCapability.LOCAL_CTRL)) {
+        return undefined;
+    }
     return {
         nodeId: info.nodeId,
         transportDetails: {
             type: ESPTransportMode.local,
-            metadata: { baseUrl: info.baseUrl },
+            metadata: {
+                baseUrl: info.baseUrl,
+                protocol: ESPLocalControlProtocol.rmakerLocalCtrl,
+                ...(capabilities && { capabilities }),
+            },
         },
     };
 }
-/** Starts LAN discovery; each hit is mapped then passed to `onDiscovered`. */
+/**
+ * Starts LAN discovery; each hit is mapped then passed to `onDiscovered`.
+ * Hits that are not control-capable (see {@link toDiscoveredNodeData}) are
+ * skipped.
+ */
 function startLocalDiscovery(onDiscovered) {
     const manager = new ESPDiscoveryManager();
-    manager.startDiscovery((info) => onDiscovered(toDiscoveredNodeData(info)));
+    manager.startDiscovery((info) => {
+        const data = toDiscoveredNodeData(info);
+        if (data)
+            onDiscovered(data);
+    });
     return { stop: () => manager.stopDiscovery() };
 }
 /** Forwards process-wide node param updates to `onUpdate`. */

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

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

package/dist/esm/utils/nodeUtils.js

@@ -26,7 +26,18 @@ async function readLocalNodeConfig(nodeId) {
 /** Best-effort persist of node config to local storage. */
 async function writeLocalNodeConfig(nodeId, config) {
     try {
-        await ESPRMNeoStorage.setNodeConfig(nodeId, config);
+        let toStore = config;
+        // Cloud config omits connectivity — keep the last cached status when writing.
+        if (!config.connectivity_status) {
+            const prev = await ESPRMNeoStorage.getNodeConfig(nodeId);
+            if (prev?.connectivity_status) {
+                toStore = {
+                    ...config,
+                    connectivity_status: prev.connectivity_status,
+                };
+            }
+        }
+        await ESPRMNeoStorage.setNodeConfig(nodeId, toStore);
     }
     catch (error) {
         logger.warn(`Cache write failed for ${nodeId}`, error);

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

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

package/dist/esm/utils/waitForNodeOnline.js

@@ -63,11 +63,12 @@ function isNodeOnlineFromShadowPayload(payload) {
  * @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);
+async function waitForNodeOnline({ nodeId, groupId, subgroupIds, user, timeoutMs = DEFAULT_NODE_ONLINE_TIMEOUT_MS, pollIntervalMs = DEFAULT_NODE_ONLINE_POLL_INTERVAL_MS, }) {
+    const shadowName = constructShadowName(groupId, subgroupIds ?? []);
     logger.info("Waiting for node to come online", {
         nodeId,
         groupId,
+        subgroupIds: subgroupIds ?? [],
         shadowName,
         timeoutMs,
         pollIntervalMs,
@@ -147,10 +148,10 @@ async function waitForNodeOnline({ nodeId, groupId, user, timeoutMs = DEFAULT_NO
             });
             await user.connectMQTT();
         }
-        // 2. Register (if needed) and subscribe before the shadow may exist
-        if (!alreadyRegistered) {
-            NodeMQTTOrchestrator.registerNode(nodeId, shadowName);
-        }
+        // 2. Bind to the membership shadow and subscribe before the shadow may exist.
+        // Always registerNode so a leftover longer/stale binding for the same nodeId
+        // is rebound to constructShadowName(groupId, subgroupIds).
+        NodeMQTTOrchestrator.registerNode(nodeId, shadowName);
         await NodeMQTTOrchestrator.subscribeToNode(nodeId, onUpdate);
         logger.debug("Subscribed to node shadow for online wait", {
             nodeId,

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

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

package/dist/types/ESPDevice.d.ts

@@ -9,5 +9,15 @@ export declare class ESPDevice implements ESPDeviceInterface {
     name: string;
     transport: string;
     security: number;
+    /**
+     * What a completed association produced, kept so `retryNetworkCredentials`
+     * can resume the flow instead of repeating it. Set once verification
+     * succeeds; `undefined` until then.
+     */
+    provisionResumeState?: {
+        nodeId: string;
+        groupId: string;
+        options?: Record<string, any>;
+    };
     constructor(deviceConfig: ESPDeviceInterface);
 }

package/dist/types/ESPRMNeoBase.d.ts

@@ -115,7 +115,7 @@ export declare class ESPRMNeoBase {
     static getProvisionAdapter(): ESPProvisionAdapterInterface | undefined;
     /**
      * Sets the local control adapter used to talk to nodes over the LAN via
-     * the `esp_local_ctrl` protocol.
+     * the `rmaker_local_ctrl` protocol.
      *
      * @param adapter - Adapter implementing {@link ESPLocalControlAdapterInterface}.
      * @throws {Error} If the SDK is not initialized or the adapter is invalid.

package/dist/types/ESPRMNeoNode.d.ts

@@ -22,11 +22,16 @@ export declare class ESPRMNeoNode {
     subgroupIds: string[];
     devices: ESPRMNeoDevice[];
     services: ESPRMNeoService[];
+    /**
+     * Last-known connectivity. Seeded from cached `connectivity_status` when
+     * present (cloud config does not provide it); otherwise starts offline until
+     * an MQTT shadow `online` update arrives.
+     */
     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`).
+     * - `mqtt` (cloud) is added when the node is connected and removed when it
+     *   goes offline (from cached `connectivity_status` or shadow updates).
      * - `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
@@ -132,11 +137,18 @@ export declare class ESPRMNeoNode {
      */
     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.
+     * Updates {@link connectivityStatus} when the shadow reports `online`, then
+     * syncs MQTT transport availability. Partial updates without `online` are
+     * ignored so an existing status is not cleared.
      */
     private applyConnectivityStatus;
+    /**
+     * Registers the MQTT transport only while {@link connectivityStatus} reports
+     * the node as connected; removes it when offline.
+     */
+    private syncMqttTransportAvailability;
+    /** Persists {@link wireConfig} (including last-known connectivity) to storage. */
+    private persistWireConfig;
     /** When cloud `ncfg_ver` changes, refetch config and persist the new marker. */
     private refreshConfigIfNcfgChanged;
 }

package/dist/types/methods/ESPDevice/ResetWifiStatus.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Augments the ESPDevice class with the `resetWifiStatus` method.
+ */
+declare module "../../ESPDevice" {
+    interface ESPDevice {
+        /**
+         * Asks the device to clear its Wi-Fi state over the open provisioning session.
+         *
+         * Sent on the network-control endpoint, so it needs an established session and
+         * leaves the user-node association intact — only Wi-Fi credentials are cleared.
+         * That is what makes `retryNetworkCredentials` possible after a wrong password,
+         * instead of making the user factory reset the board.
+         * @returns A promise resolving to `true` when the device acknowledged the reset.
+         */
+        resetWifiStatus(): Promise<boolean>;
+    }
+}
+export {};

package/dist/types/methods/ESPDevice/RetryNetworkCredentials.d.ts

@@ -0,0 +1,22 @@
+import { ESPProvResponse } from "../../types/provision";
+/**
+ * Augments the ESPDevice class with the `retryNetworkCredentials` method.
+ */
+declare module "../../ESPDevice" {
+    interface ESPDevice {
+        /**
+         * Re-sends Wi-Fi credentials after `resetWifiStatus`, resuming the flow the
+         * first attempt started rather than repeating its association.
+         *
+         * Sending credentials alone is not enough: the online wait and the success
+         * report follow them and need the node id the association produced, which
+         * only this SDK holds.
+         * @param ssid - The SSID, unchanged from the first attempt.
+         * @param passphrase - The corrected Wi-Fi password.
+         * @param onProgress - Progress callback; emits the same messages as `provision`.
+         * @returns A promise resolving to the node id.
+         * @throws {ESPProvError} When no association has completed on this device yet.
+         */
+        retryNetworkCredentials(ssid: string, passphrase: string, onProgress: (message: ESPProvResponse) => void): Promise<string>;
+    }
+}

package/dist/types/methods/ESPDevice/index.d.ts

@@ -8,6 +8,8 @@ import "./SetProofOfPossession";
 import "./SendData";
 import "./InitializeSession";
 import "./SetNetworkCredentials";
+import "./ResetWifiStatus";
+import "./RetryNetworkCredentials";
 import "./InitiateUserNodeMapping";
 import "./VerifyUserNodeMapping";
 import "./StartAssistedClaiming";

package/dist/types/methods/ESPRMNeoUser/MQTT/AssumeRole.d.ts

@@ -5,29 +5,39 @@ import { AWSCredentials } from "../../../types/input";
 declare module "../../../ESPRMNeoUser" {
     interface ESPRMNeoUser {
         /**
-         * Exchanges identity (temporary) credentials for role-based IoT/MQTT credentials.
+         * Exchanges identity (temporary) credentials for role-based credentials.
          *
-         * This is not session extension. The backend uses the provided temporary credentials
-         * (from getTemporaryAWSCredentials, which are identity-pool–style credentials) to assume
-         * an IAM role that has IoT/MQTT permissions. It returns a different set of credentials
-         * (assume-role credentials) used for MQTT connection and device shadows.
+         * Two modes — chosen by whether `options.services` is set:
+         *   1. Default (no `options.services`): POST /v1/assumed-roles. Returns
+         *      IoT/MQTT credentials scoped to the user's group/subgroup membership.
+         *      Used for MQTT WebSocket auth.
+         *   2. Per-node services (`options.services` with `nodeId`):
+         *      Same route, with `services` and `node_id` in the body. Returns
+         *      credentials scoped to that single node for the listed services
+         *      (currently `s3` and/or `kvs`). The response contains only the
+         *      requested service permissions — no IoT/MQTT statements.
          *
-         * Flow: temporary credentials (auth) → POST /v1/assumed-roles → assume-role credentials (IoT).
-         *
-         * @param accessKey - AWS access key from getTemporaryAWSCredentials (identity credentials).
+         * @param accessKey - AWS access key from getTemporaryAWSCredentials.
          * @param secretKey - AWS secret key from getTemporaryAWSCredentials.
          * @param sessionToken - AWS session token from getTemporaryAWSCredentials.
-         * @param options - Optional parameters merged into the request body.
-         * @param options.include - Services to include in the session policy (e.g., ["s3"], ["kvs"], ["s3", "kvs"]).
-         *                          When omitted, only IoT/MQTT permissions are granted.
-         * @returns A promise that resolves to AWSCredentials (role-based; used for MQTT).
-         * @throws Error if the API call fails or if the response is invalid.
+         * @param options - Optional. To request per-node service credentials, pass
+         *                  `services` and `nodeId`.
+         * @returns A promise that resolves to AWSCredentials.
+         * @throws Error if `services` is set without `nodeId`, or if the API call fails.
          */
         assumeRole(accessKey: string, secretKey: string, sessionToken: string, options?: AssumeRoleOptions): Promise<AWSCredentials>;
     }
 }
+/** Per-node service credentials supported by the backend. */
+export type AssumeRoleService = "s3" | "kvs";
 /** Options for the assumeRole method. */
 export interface AssumeRoleOptions {
-    /** Services to include in the session policy (e.g., ["s3"], ["kvs"]). */
-    include?: string[];
+    /**
+     * Services to scope credentials to (e.g., `["s3"]`, `["kvs"]`, `["s3", "kvs"]`).
+     * When set, `nodeId` is required and the returned credentials contain only the
+     * listed service permissions for that single node.
+     */
+    services?: AssumeRoleService[];
+    /** Required when `services` is set. The node these credentials apply to. */
+    nodeId?: string;
 }

package/dist/types/proto/rmaker_local_ctrl.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Codec for the `rmaker_local_ctrl` endpoint protocol, mirroring the firmware's
+ * `local_ctrl.proto` schema.
+ *
+ * Hand-rolled like {@link ClaimingProtoHelper} rather than generated: the
+ * schema is small, and generated `google-protobuf` modules cannot be pulled
+ * into a downstream Metro/RN bundle (see the note in `utils/export.ts`).
+ *
+ * Field numbers are the wire contract with deployed firmware — treat them as
+ * frozen:
+ * - `RMakerLocalCtrlPayload`: 1 = msg (varint), 10 = cmdGetData, 11 = respGetData
+ * - `CmdGetData`:  1 = DataType (varint), 2 = Offset (varint),
+ *                  3 = Timestamp (varint), 4 = HasTimestamp (varint)
+ * - `RespGetData`: 1 = Status (varint), 2 = Buf
+ * - `PayloadBuf`:  1 = Offset (varint), 2 = Payload (bytes), 3 = TotalLen (varint)
+ *
+ * `Timestamp` / `HasTimestamp` are reserved for a future signed-response
+ * extension and are ignored by current firmware, so the encoder omits them.
+ *
+ * Only `get_params` / `get_config` use this schema; `set_params` carries raw
+ * JSON on the wire.
+ */
+/**
+ * Status returned by the device for a data read.
+ */
+export declare enum RMakerLocalCtrlStatus {
+    Success = 0,
+    Fail = 1,
+    InvalidParam = 2,
+    NoMemory = 3
+}
+/**
+ * Selects which document a read targets.
+ */
+export declare enum RMakerLocalCtrlDataType {
+    /** The node's params JSON, as served by `get_params`. */
+    TypeParams = 0,
+    /** The node's config JSON, as served by `get_config`. */
+    TypeConfig = 1
+}
+/**
+ * Message type discriminator carried on `RMakerLocalCtrlPayload.msg`.
+ */
+export declare enum RMakerLocalCtrlMsgType {
+    TypeCmdGetData = 0,
+    TypeRespGetData = 1
+}
+/**
+ * One fragment of a larger document.
+ */
+export interface PayloadBuf {
+    /** Byte offset of this fragment within the document. */
+    offset: number;
+    /** Fragment bytes (up to 200 per response). */
+    payload: Uint8Array;
+    /** Full document length in bytes. */
+    totalLen: number;
+}
+/**
+ * Device response to a data read.
+ */
+export interface RespGetData {
+    /** Read status. */
+    status: RMakerLocalCtrlStatus;
+    /** Fragment carried by this response. */
+    buf?: PayloadBuf;
+}
+/**
+ * Envelope exchanged on the `get_params` / `get_config` endpoints.
+ */
+export interface RMakerLocalCtrlPayload {
+    /** Message type. */
+    msg: RMakerLocalCtrlMsgType;
+    /** Response payload (device → app). */
+    respGetData?: RespGetData;
+}
+/**
+ * Encoder/decoder for `rmaker_local_ctrl` frames.
+ */
+export declare class RMakerLocalCtrlProtoHelper {
+    /**
+     * Builds a `CmdGetData` request for one fragment.
+     *
+     * An `offset` of 0 makes the device (re)generate and cache the document;
+     * subsequent offsets are served from that cache.
+     *
+     * @param dataType - Document to read.
+     * @param offset - Byte offset to read from.
+     * @returns The serialized request.
+     */
+    static createGetDataRequest(dataType: RMakerLocalCtrlDataType, offset: number): Uint8Array;
+    /**
+     * Parses a `RespGetData` frame from the device.
+     *
+     * @param data - Raw response bytes.
+     * @returns The parsed payload. Absent fields keep their proto3 defaults.
+     */
+    static parseGetDataResponse(data: Uint8Array): RMakerLocalCtrlPayload;
+    /**
+     * Whether the device reported a successful read.
+     *
+     * @param response - Parsed response.
+     */
+    static isSuccess(response: RMakerLocalCtrlPayload): boolean;
+    /**
+     * Returns the device's status as its enum name, for diagnostics.
+     *
+     * @param response - Parsed response.
+     * @returns The status name, or `"Unknown"` when absent.
+     */
+    static getStatus(response: RMakerLocalCtrlPayload): string;
+    /**
+     * Offset the device answered with, which must match the requested offset.
+     *
+     * @param response - Parsed response.
+     */
+    static getOffset(response: RMakerLocalCtrlPayload): number;
+    /**
+     * Full document length reported by the device.
+     *
+     * @param response - Parsed response.
+     */
+    static getTotalLen(response: RMakerLocalCtrlPayload): number;
+    /**
+     * Fragment bytes carried by the response.
+     *
+     * @param response - Parsed response.
+     */
+    static getPayload(response: RMakerLocalCtrlPayload): Uint8Array;
+    private static concat;
+    private static encodeVarint;
+    private static readVarint;
+    /** Advances past a field this codec does not read. */
+    private static skipField;
+    private static parseRespGetData;
+    private static parsePayloadBuf;
+}

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

@@ -58,6 +58,16 @@ export declare class ESPRMNeoMqtt implements MQTTTransport {
      * Returns whether the underlying MQTT client is connected.
      */
     isConnected(): Promise<boolean>;
+    /**
+     * Registers a transport connection-status listener when the underlying
+     * adapter supports it; otherwise returns a no-op unsubscribe.
+     *
+     * @param callback - Invoked with `{ connected }` on status changes
+     * @returns Unsubscribe function
+     */
+    onConnectionStatusChange(callback: (status: {
+        connected: boolean;
+    }) => void): () => void;
     /**
      * Publish a message to a topic.
      *

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

@@ -4,9 +4,10 @@ import { DiscoveryParamsInterface, ESPDiscoveryCallback } from "../../../types/d
  * 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.
+ *   (mDNS service `_esp_rmaker_ctrl._tcp.` in the `local` domain — the
+ *   service advertised by RainMaker Neo firmware).
+ * - A custom {@link DiscoveryParamsInterface} can be supplied to browse any
+ *   other service type.
  */
 declare class ESPDiscoveryManager {
     /** Discovery parameters (service type / domain) passed to the adapter. */

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

@@ -2,37 +2,84 @@ 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}.
+ * The built-in `local` transport, speaking the `rmaker_local_ctrl` endpoint
+ * protocol over the app-supplied {@link ESPRMNeoBase.ESPLocalControlAdapter}:
+ *
+ * - `set_params` carries the same raw JSON body as a cloud set-params call and
+ *   answers `{"status":"success"}` / `{"status":"fail","description":…}`.
+ * - `get_params` / `get_config` exchange protobuf `CmdGetData`/`RespGetData` and
+ *   are fragmented — the client pulls fixed-size chunks by offset until
+ *   `TotalLen` is covered.
+ *
+ * Connection metadata (`baseUrl`, `securityType`, `pop`, and `username` for
+ * sec2) is supplied via the transport config by {@link
+ * delegatedTransportHandler}; security 0 is not offered by this protocol.
  */
 declare class ESPLocalControlTransport implements ESPTransportInterface {
-    private payload;
     metadata: Record<string, any>;
-    propertyInfo: Record<string, any>;
     constructor(transportConfig: ESPTransportConfig);
     private get adapter();
+    private ensureConnected;
     /**
-     * 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.
+     * Applies params over `set_params`.
+     *
+     * @param payload - `{ node_id, payload }`, where `payload` is the
+     *   `{ <deviceOrServiceName>: { <paramName>: value } }` map to write.
+     * @throws {Error} When the device reports a non-success status.
      */
-    private connectWithRetry;
-    private ensureConnected;
     setParam(payload: Record<string, any>, _nodeRef?: ESPRMNeoNode): Promise<ESPAPIResponse>;
+    /**
+     * Reads the node's full params document over `get_params`.
+     *
+     * @param payload - `{ node_id }` identifying the node to read.
+     * @returns The params JSON, keyed by device/service name.
+     */
     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;
+    /**
+     * Reads the node's config document over `get_config`. Not part of
+     * {@link ESPTransportInterface} — the node config normally comes from the
+     * cloud; this serves LAN-only flows.
+     *
+     * @param nodeId - Node to read from.
+     * @returns The node config JSON.
+     */
+    getConfig(nodeId: string): Promise<Record<string, any>>;
+    /**
+     * Validates a `set_params` raw-JSON response.
+     *
+     * @throws {Error} When the body is unparseable or reports a failure.
+     */
+    private assertSetParamsAccepted;
+    /**
+     * Pulls a fragmented document and parses it as JSON, serialized against every
+     * other fragmented read of the same node.
+     *
+     * The device holds **one global transfer cache**, not one per session: an
+     * offset-0 request regenerates it and it is freed after the last fragment. So
+     * a `getParams()` racing a `getConfig()` on the same node would clobber the
+     * other — the second offset-0 regenerates the cache mid-transfer, and the
+     * first read's next fragment comes back `Fail` (or, worse, carries bytes from
+     * the wrong document). The queue makes that interleaving impossible rather
+     * than detecting it after the fact.
+     *
+     * @param nodeId - Node to read from.
+     * @param dataType - Which document to read (params or config).
+     * @param endpoint - Endpoint serving that document.
+     * @throws {Error} When the device reports a failure, the response is
+     *   malformed, or a fragment makes no forward progress.
+     */
+    private readJsonDocument;
+    /** The client-pull loop itself; always reached via {@link readJsonDocument}. */
+    private pullJsonDocument;
+    private buildGetDataRequest;
+    /**
+     * Parses one `RespGetData` and checks it answers the requested offset.
+     *
+     * @param response - Base64 protobuf response from the adapter.
+     * @param requestedOffset - Offset asked for, used to detect a desynced pull.
+     */
+    private processGetDataResponse;
+    /** Joins the pulled fragments and parses the result as JSON. */
+    private parseJsonFragments;
 }
 export { ESPLocalControlTransport };

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

@@ -0,0 +1,24 @@
+import type { ESPLocalControlAdapterInterface, ESPLocalControlSessionOptions } from "../../types/localControl";
+/**
+ * Returns the app-supplied local control adapter.
+ *
+ * @throws {Error} When no adapter was registered on {@link ESPRMNeoBase}.
+ */
+export declare function getLocalControlAdapter(): ESPLocalControlAdapterInterface;
+/**
+ * Ensures a usable local-control session for `nodeId`, connecting (with
+ * retries) when the adapter reports none.
+ *
+ * The adapter resolves on a successful handshake and rejects otherwise, so a
+ * resolved `connect` is treated as connected.
+ *
+ * @param adapter - Adapter to drive.
+ * @param nodeId - Node to connect to.
+ * @param metadata - Local transport metadata (`baseUrl`, `securityType`, `pop`,
+ *   `username`).
+ * @param options - Session endpoints for the protocol in use; omitted for the
+ *   adapter's built-in default paths.
+ * @param maxRetries - Connection attempts before failing.
+ * @throws {Error} When every connection attempt fails.
+ */
+export declare function ensureLocalControlSession(adapter: ESPLocalControlAdapterInterface, nodeId: string, metadata: Record<string, any>, options?: ESPLocalControlSessionOptions, maxRetries?: number): Promise<void>;

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

@@ -76,8 +76,8 @@ export declare class NodeMQTTOrchestrator {
     /**
      * 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.
+     * On shadow rename: clears the old binding, then installs the new name
+     * (including shrinks to a shorter membership shadow).
      *
      * @param nodeId - The device/node identifier.
      * @param shadowName - The named shadow (e.g. `params-groupId-subgroupId`).