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

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

@@ -468,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. */
@@ -477,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.
@@ -627,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.
@@ -809,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, AssumeRoleErrorMessages, 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/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.1.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":";;;;;;;;;;;;;;;;;;;;;;;;"}