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

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/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/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`).

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/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/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).
  */
@@ -800,7 +809,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, 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/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.1.0",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/cjs/index.js",