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

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

@@ -18,6 +18,16 @@ export interface MQTTTransport {
      * Check if the MQTT client is connected.
      */
     isConnected(): Promise<boolean>;
+    /**
+     * Optional push notification when the transport connects or drops.
+     * Returns an unsubscribe function. Not required by NodeMQTTOrchestrator;
+     * adapters that omit it simply do not surface async status changes.
+     *
+     * @param callback - Invoked with `{ connected }` on status changes
+     */
+    onConnectionStatusChange?(callback: (status: {
+        connected: boolean;
+    }) => void): () => void;
     /**
      * Publish a message to a topic.
      *

package/dist/types/types/discovery.d.ts

@@ -23,7 +23,7 @@ declare enum ESPRMNeoEventType {
  * (e.g. mDNS service type and domain).
  */
 interface DiscoveryParamsInterface {
-    /** Service type to browse for, e.g. `_esp_local_ctrl._tcp.` */
+    /** Service type to browse for, e.g. `_esp_rmaker_ctrl._tcp.` */
     serviceType: string;
     /** Discovery domain, e.g. `local`. */
     domain: string;

package/dist/types/types/localControl.d.ts

@@ -1,3 +1,25 @@
+/**
+ * Per-connection session details passed to {@link
+ * ESPLocalControlAdapterInterface.connect}. The protocomm handshake endpoint
+ * differs per local-control protocol, so the transport tells the native layer
+ * which paths to use instead of the adapter hardcoding them.
+ *
+ * Adapters built against an earlier SDK simply ignore the extra argument and
+ * keep using their built-in default paths.
+ */
+export interface ESPLocalControlSessionOptions {
+    /** Protocol tag, one of {@link ESPLocalControlProtocol}. */
+    protocol: string;
+    /** Protocomm session-security endpoint, e.g. `rmaker_local_ctrl/session`. */
+    sessionPath: string;
+    /** Version/service-info endpoint, e.g. `rmaker_local_ctrl/version`. */
+    versionPath: string;
+    /**
+     * Root key to read in the version response when probing the security scheme
+     * version, e.g. `rmaker_local_ctrl` for `{"rmaker_local_ctrl": {…}}`.
+     */
+    versionKey: string;
+}
 /**
  * Local control adapter interface for node communication over LAN.
  */
@@ -8,8 +30,11 @@ export interface ESPLocalControlAdapterInterface {
     isConnected(nodeId: string): Promise<boolean>;
     /**
      * Connects to the node with local control parameters.
+     *
+     * @param options - Session endpoints for the protocol in use. Omitted only by
+     *   callers that want the adapter's built-in default paths.
      */
-    connect(nodeId: string, baseUrl: string, securtiyType: number, pop?: string, username?: string): Promise<Record<string, unknown>>;
+    connect(nodeId: string, baseUrl: string, securtiyType: number, pop?: string, username?: string, options?: ESPLocalControlSessionOptions): Promise<Record<string, unknown>>;
     /**
      * Sends data to the specified path on the node.
      */

package/dist/types/types/provision.d.ts

@@ -73,6 +73,16 @@ interface ESPProvisionAdapterInterface {
     scanWifiList(deviceName: string): Promise<ESPWifiList[]>;
     sendData(deviceName: string, endPoint: string, data: string): Promise<string>;
     provision(deviceName: string, ssid: string, passphrase: string): Promise<ESPProvisionStatus>;
+    /**
+     * Clears the device's Wi-Fi state over the open provisioning session.
+     * Requires an established session; the user-node association is left intact.
+     *
+     * Optional so that adapters written against an earlier SDK keep compiling;
+     * `ESPDevice.resetWifiStatus` resolves `false` when it is absent.
+     * @param deviceName - Name of the connected provisioning device.
+     * @returns Promise resolving to `true` when the device acknowledged the reset.
+     */
+    resetWifiStatus?(deviceName: string): Promise<boolean>;
     disconnect(deviceName: string): Promise<void>;
 }
 /**

package/dist/types/types/transport.d.ts

@@ -13,11 +13,33 @@ declare enum ESPTransportMode {
     /** Communication is routed through MQTT (RainMaker Neo cloud: AWS shadow). */
     mqtt = "mqtt"
 }
+/**
+ * Wire protocol spoken by the `local` transport. Both protocols run over a
+ * protocomm session on the node's LAN HTTP server; they differ in endpoint
+ * names and message encoding.
+ *
+ * Carried on the local transport config's `metadata.protocol`, set by local
+ * discovery from the mDNS service type that produced the hit.
+ */
+declare enum ESPLocalControlProtocol {
+    /**
+     * RainMaker Neo protocol (`rmaker_local_ctrl/*` session plus
+     * `get_params`/`set_params`/`get_config`), advertised as
+     * `_esp_rmaker_ctrl._tcp`. Default for this SDK.
+     */
+    rmakerLocalCtrl = "rmaker_local_ctrl"
+}
+/**
+ * Protocol assumed when a local transport config carries no explicit
+ * `metadata.protocol` — for example a LAN transport restored from a client-side
+ * registry rather than a fresh discovery hit.
+ */
+declare const DEFAULT_LOCAL_CONTROL_PROTOCOL = ESPLocalControlProtocol.rmakerLocalCtrl;
 /**
  * Configuration options for the transport mechanism for ESP communication.
  *
  * Includes the transport type and any additional metadata for the chosen mode
- * (e.g. `baseUrl`, `securityType`, `pop` for the local transport).
+ * (e.g. `baseUrl`, `securityType`, `pop`, `protocol` for the local transport).
  */
 interface ESPTransportConfig {
     /**
@@ -62,4 +84,4 @@ interface ESPTransportInterface {
  * has an explicit order configured: local control first, MQTT (cloud) fallback.
  */
 declare const DEFAULT_TRANSPORT_ORDER: (ESPTransportMode | string)[];
-export { ESPTransportMode, ESPTransportConfig, ESPTransportInterface, DEFAULT_TRANSPORT_ORDER, };
+export { ESPTransportMode, ESPLocalControlProtocol, ESPTransportConfig, ESPTransportInterface, DEFAULT_TRANSPORT_ORDER, DEFAULT_LOCAL_CONTROL_PROTOCOL, };

package/dist/types/utils/baseUtils.d.ts

@@ -25,7 +25,7 @@ export interface ESPRMNeoBaseAdapters {
     storage?: ESPStorageAdapter;
     /** SoftAP / BLE provisioning implementation supplied by the host app. */
     provision?: ESPProvisionAdapterInterface;
-    /** LAN `esp_local_ctrl` transport implementation. */
+    /** LAN local-control transport implementation. */
     localControl?: ESPLocalControlAdapterInterface;
     /** LAN / mDNS discovery implementation. */
     localDiscovery?: ESPLocalDiscoveryAdapterInterface;

package/dist/types/utils/constants.d.ts

@@ -386,6 +386,15 @@ declare const TriggerErrorMessages: {
     /** Logged when retrieving triggers for a node fails. */
     readonly GET_FAILED: "getTriggers failed";
 };
+/**
+ * Error messages for assumeRole (POST /v1/assumed-roles).
+ */
+declare const AssumeRoleErrorMessages: {
+    /** Thrown when `services` is provided without a `nodeId`. */
+    readonly NODE_ID_REQUIRED: "assumeRole: nodeId is required when services is provided";
+    /** Thrown when the assume-role response is missing required credential fields. */
+    readonly INVALID_RESPONSE: "Invalid assume role response: missing required credential fields";
+};
 /**
  * Error / log messages for temporary AWS credentials (POST /v1/user/credentials).
  */
@@ -459,8 +468,6 @@ declare const ProvisionType: {
  * An object containing endpoint paths.
  */
 declare const Endpoint: {
-    /** The endpoint for local control. */
-    LOCAL_CTRL: string;
     /** The endpoint for cloud user association. */
     CLOUD_USER_ASSOCIATION: string;
     /** The endpoint for challenge-response and get-node-id protocol with the device. */
@@ -468,6 +475,64 @@ declare const Endpoint: {
     /** The endpoint for assisted claiming. */
     RM_CLAIM: string;
 };
+/**
+ * Endpoint paths of the `rmaker_local_ctrl` protocol served by RainMaker Neo
+ * firmware (see the firmware's local-control endpoint protocol spec).
+ *
+ * All data endpoints inherit the security of the session established on
+ * {@link RMakerLocalCtrlEndpoint.SESSION}.
+ */
+declare const RMakerLocalCtrlEndpoint: {
+    /** Protocomm session-security endpoint (SEC1 with/without PoP, or SEC2). */
+    readonly SESSION: "rmaker_local_ctrl/session";
+    /** POST any payload; responds with the service info JSON (`sec_ver`, `cap`, …). */
+    readonly VERSION: "rmaker_local_ctrl/version";
+    /** Reads the params JSON — protobuf `CmdGetData`, fragmented response. */
+    readonly GET_PARAMS: "get_params";
+    /** Reads the node config JSON — protobuf `CmdGetData`, fragmented response. */
+    readonly GET_CONFIG: "get_config";
+    /** Writes params — raw JSON request and response (no protobuf). */
+    readonly SET_PARAMS: "set_params";
+};
+/**
+ * Root key of the JSON served by {@link RMakerLocalCtrlEndpoint.VERSION}, i.e.
+ * `{"rmaker_local_ctrl": {"ver": …, "sec_ver": …, "cap": [...]}}`. Passed to the
+ * local-control adapter so the native layer probes the right scheme version.
+ */
+declare const RMAKER_LOCAL_CTRL_VERSION_KEY = "rmaker_local_ctrl";
+/**
+ * Maximum fragment size (bytes) the firmware serves per `RespGetData`. Reads
+ * loop with `Offset += Payload.length` until `TotalLen` is reached; this value
+ * is informational (the device dictates the actual fragment length).
+ */
+declare const RMAKER_LOCAL_CTRL_FRAGMENT_SIZE = 200;
+/**
+ * `status` values in a `set_params` raw-JSON response.
+ */
+declare const RMakerLocalCtrlSetParamsStatus: {
+    readonly SUCCESS: "success";
+    readonly FAIL: "fail";
+};
+/**
+ * mDNS TXT record keys advertised by the `_esp_rmaker_ctrl._tcp` service.
+ */
+declare const RMakerLocalCtrlTxtKey: {
+    /** Node ID (also the service instance name and hostname). */
+    readonly NODE_ID: "node_id";
+    /** Comma-separated active capabilities — see {@link RMakerLocalCtrlCapability}. */
+    readonly CAP: "cap";
+};
+/**
+ * Capability tokens found in the `cap` TXT record. A node advertising only
+ * `ch_resp` is reachable for on-network user-node association but *not* for
+ * param control, so it must not be registered as a local control transport.
+ */
+declare const RMakerLocalCtrlCapability: {
+    /** Params/config endpoints are registered. */
+    readonly LOCAL_CTRL: "local_ctrl";
+    /** Challenge-response (on-network user-node association) is registered. */
+    readonly CH_RESP: "ch_resp";
+};
 /**
  * Assisted-claiming REST paths, on the deployment's main API and SigV4-signed
  * like every other `/v1/*` route.
@@ -618,8 +683,12 @@ declare const ProvErrorCodes: {
  * @enum {string}
  */
 declare const ServiceType: {
-    /** Represents the ESP local control TCP service type. */
-    ESP_LOCAL_CTRL_TCP: string;
+    /**
+     * Service type advertised by RainMaker Neo firmware. A single instance serves
+     * the `rmaker_local_ctrl` endpoints; the `cap` TXT record says which endpoint
+     * sets are active. This is the default for local discovery in this SDK.
+     */
+    ESP_RMAKER_LOCAL_CTRL_TCP: string;
 };
 /**
  * An object containing protocol types.
@@ -800,7 +869,7 @@ declare const APIPathV1: {
     /** POST /v1/groups/{groupId}/node-assoc-requests/{requestId}/verify - Verifies user node mapping */
     readonly USER_NODE_MAPPING_VERIFY: (groupId: string, requestId: string) => string;
 };
-export { HTTPMethods, APIEndpoints, APIPathV1, StorageKeys, ValidationErrorCodes, StorageAdapterErrorCodes, ConfigErrorCodes, APICallValidationErrorCodes, APIOperations, TokenErrorCodes, AuthErrorCodes, AuthSuccessMessages, AutomationSuccessMessages, AutomationStatusValues, GroupSuccessMessages, NodeSuccessMessages, NodeWarnMessages, ScheduleSuccessMessages, ScheduleErrorMessages, TriggerErrorMessages, TriggerSuccessMessages, SharingSuccessMessages, IntegrationSuccessMessages, AWSCredentialsErrorMessages, GroupUserAliases, Endpoint, ProvisionType, ProvErrorCodes, ServiceType, ProtocolType, StatusMessage, DEFAULT_REST_API_VERSION, ESPServiceType, ESPServiceParamType, ESPProvProgressMessages, ErrorLabels, SDK_VERSION, ClaimEndpoints, ClaimCapabilities, ClaimCapabilityPolicies, ClaimErrorCodes, ClaimProgressMessages, CLAIM_CSR_MAX_CHUNKS, CLAIM_MAX_FRAGMENT_SIZE, CLAIM_MAC_SEPARATORS, CLAIM_MAC_HEX_LENGTHS, CLAIM_DEVICE_MAC_KEYS, CLAIM_DEVICE_CSR_KEYS, };
+export { HTTPMethods, APIEndpoints, APIPathV1, StorageKeys, ValidationErrorCodes, StorageAdapterErrorCodes, ConfigErrorCodes, APICallValidationErrorCodes, APIOperations, TokenErrorCodes, AuthErrorCodes, AuthSuccessMessages, AutomationSuccessMessages, AutomationStatusValues, GroupSuccessMessages, NodeSuccessMessages, NodeWarnMessages, ScheduleSuccessMessages, ScheduleErrorMessages, TriggerErrorMessages, TriggerSuccessMessages, SharingSuccessMessages, IntegrationSuccessMessages, AssumeRoleErrorMessages, AWSCredentialsErrorMessages, GroupUserAliases, Endpoint, RMakerLocalCtrlEndpoint, RMAKER_LOCAL_CTRL_VERSION_KEY, RMAKER_LOCAL_CTRL_FRAGMENT_SIZE, RMakerLocalCtrlSetParamsStatus, RMakerLocalCtrlTxtKey, RMakerLocalCtrlCapability, ProvisionType, ProvErrorCodes, ServiceType, ProtocolType, StatusMessage, DEFAULT_REST_API_VERSION, ESPServiceType, ESPServiceParamType, ESPProvProgressMessages, ErrorLabels, SDK_VERSION, ClaimEndpoints, ClaimCapabilities, ClaimCapabilityPolicies, ClaimErrorCodes, ClaimProgressMessages, CLAIM_CSR_MAX_CHUNKS, CLAIM_MAX_FRAGMENT_SIZE, CLAIM_MAC_SEPARATORS, CLAIM_MAC_HEX_LENGTHS, CLAIM_DEVICE_MAC_KEYS, CLAIM_DEVICE_CSR_KEYS, };
 export declare enum ESPRMNeoErrorCodes {
     SDK_NOT_CONFIGURED = "SDK_NOT_CONFIGURED",
     INVALID_CREDENTIALS = "INVALID_CREDENTIALS",

package/dist/types/utils/eventSubscriptionUtils.d.ts

@@ -4,9 +4,25 @@ import { ESPNodeUpdateData } from "../types/subscription";
 export type EventTeardown = {
     stop(): void;
 };
-/** Maps a default local-discovery hit into the client-facing payload shape. */
-export declare function toDiscoveredNodeData(info: Record<string, any>): ESPDiscoveredNodeData;
-/** Starts LAN discovery; each hit is mapped then passed to `onDiscovered`. */
+/**
+ * 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.
+ */
+export declare function toDiscoveredNodeData(info: Record<string, any>): ESPDiscoveredNodeData | undefined;
+/**
+ * Starts LAN discovery; each hit is mapped then passed to `onDiscovered`.
+ * Hits that are not control-capable (see {@link toDiscoveredNodeData}) are
+ * skipped.
+ */
 export declare function startLocalDiscovery(onDiscovered: (data: ESPDiscoveredNodeData) => void): EventTeardown;
 /** Forwards process-wide node param updates to `onUpdate`. */
 export declare function startNodeUpdates(onUpdate: (update: ESPNodeUpdateData) => void): EventTeardown;

package/dist/types/utils/waitForNodeOnline.d.ts

@@ -4,8 +4,8 @@
  * Typical use: after provisioning WiFi credentials, the device joins the network and
  * connects to the cloud. There is no dedicated "online" MQTT topic — connectivity is
  * published as `state.reported.online` inside shadow update messages on the named
- * shadow `params-{groupId}` (firmware writes this after getGroupInfo; cloud presence
- * only clears online on disconnect).
+ * shadow `params-{groupId}` or `params-{groupId}-{subgroupIds}` (firmware writes this
+ * after getGroupInfo; cloud presence only clears online on disconnect).
  *
  * Matches app_sim `_wait_node_online`: subscribe first, then poll shadow GET on an
  * interval until `reported.online === true` (or a live MQTT update arrives). GET may
@@ -24,6 +24,12 @@ export interface WaitForNodeOnlineParams {
     nodeId: string;
     /** Group the node was associated with during provisioning (drives shadow name). */
     groupId: string;
+    /**
+     * Subgroup (room/CG) ids that currently contain the node.
+     * Omitted or empty ⇒ home-only shadow `params-{groupId}` (legacy callers).
+     * When set, shadow is `params-{groupId}-{sortedSubgroupIds}`.
+     */
+    subgroupIds?: string[];
     /** Logged-in user; used to connect MQTT if not already connected. */
     user: ESPRMNeoUser;
     timeoutMs?: number;
@@ -45,4 +51,4 @@ export declare function isNodeOnlineFromShadowPayload(payload: unknown): boolean
  * @throws {ESPProvError} If `timeoutMs` elapses without the node reporting online.
  * @throws {Error} If MQTT connection or subscription fails.
  */
-export declare function waitForNodeOnline({ nodeId, groupId, user, timeoutMs, pollIntervalMs, }: WaitForNodeOnlineParams): Promise<void>;
+export declare function waitForNodeOnline({ nodeId, groupId, subgroupIds, user, timeoutMs, pollIntervalMs, }: WaitForNodeOnlineParams): Promise<void>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@espressif/rainmaker-neo-base-sdk",
   "description": "ESP RainMaker Neo TypeScript SDK for JS-based apps — Cognito auth, MQTT control, device provisioning, groups, and real-time node updates.",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/cjs/index.js",

package/dist/cjs/proto/constants.js

@@ -1,24 +0,0 @@
-'use strict';
-
-/*
- * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
- *
- * SPDX-License-Identifier: Apache-2.0
- */
-/**
- * Generated by the protoc-gen-ts.  DO NOT EDIT!
- * compiler version: 5.28.2
- * source: constants.proto
- * git: https://github.com/thesayyn/protoc-gen-ts */
-exports.Status = void 0;
-(function (Status) {
-    Status[Status["Success"] = 0] = "Success";
-    Status[Status["InvalidSecScheme"] = 1] = "InvalidSecScheme";
-    Status[Status["InvalidProto"] = 2] = "InvalidProto";
-    Status[Status["TooManySessions"] = 3] = "TooManySessions";
-    Status[Status["InvalidArgument"] = 4] = "InvalidArgument";
-    Status[Status["InternalError"] = 5] = "InternalError";
-    Status[Status["CryptoError"] = 6] = "CryptoError";
-    Status[Status["InvalidSession"] = 7] = "InvalidSession";
-})(exports.Status || (exports.Status = {}));
-//# sourceMappingURL=constants.js.map

package/dist/cjs/proto/constants.js.map

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