@espressif/rainmaker-neo-base-sdk 1.0.0

package/dist/types/types/auth.d.ts

@@ -0,0 +1,89 @@
+export interface ESPRMNeoUserInfo {
+    username: string;
+    userAttributes: Record<string, string | undefined>;
+    /** RainMaker `user_id` from `GET /v1/users/{userId}`. */
+    userId?: string;
+}
+/** Response shape for GET /v1/users/{userId} (snake_case from backend). */
+export interface GetUserApiResponse {
+    user_id: string;
+    email?: string;
+    phone_number?: string;
+}
+export interface ESPRMNeoAuthTokens {
+    accessToken: string;
+    idToken: string;
+    refreshToken: string;
+}
+/** Request body for POST /v1/user/auth/token/refresh. */
+export interface TokenRefreshRequest {
+    refresh_token: string;
+}
+/** Standard shape of the token/refresh API response (snake_case from backend). */
+export interface TokenRefreshApiResponse {
+    access_token: string;
+    id_token: string;
+}
+/** Request body for POST /v1/user/auth/token (Login). */
+export interface SigninRequest {
+    username: string;
+    password: string;
+}
+/** Response shape for POST /v1/user/auth/token (snake_case from backend). */
+export interface SigninApiResponse {
+    access_token: string;
+    id_token: string;
+    refresh_token: string;
+}
+/** Request body for POST /v1/user/auth/signup. */
+export interface SignupRequest {
+    password: string;
+    email?: string;
+    phone_number?: string;
+}
+/** Response shape for POST /v1/user/auth/signup (snake_case from backend). */
+export interface SignupApiResponse {
+    message?: string;
+}
+/** Request body for POST /v1/user/auth/signup/verify. */
+export interface VerifySignupRequest {
+    code: string;
+    email?: string;
+    phone_number?: string;
+}
+/** Response shape for POST /v1/user/auth/signup/verify (snake_case from backend). */
+export interface VerifySignupApiResponse {
+    message?: string;
+}
+/** Request body for POST /v1/user/auth/password-recovery. */
+export interface ForgotPasswordRequest {
+    username: string;
+}
+/** Response shape for POST /v1/user/auth/password-recovery (snake_case from backend). */
+export interface ForgotPasswordApiResponse {
+    message?: string;
+}
+/** Request body for POST /v1/user/auth/password-recovery/confirmation. */
+export interface PasswordRecoveryConfirmationRequest {
+    username: string;
+    code: string;
+    new_password: string;
+}
+/** Response shape for POST /v1/user/auth/password-recovery/confirmation. */
+export interface PasswordRecoveryConfirmationApiResponse {
+    message?: string;
+}
+/** Request body for POST /v1/user/auth/password (Change Password). */
+export interface ChangePasswordRequest {
+    /** Access token (required by backend for Cognito ChangePassword API). */
+    access_token: string;
+    old_password: string;
+    new_password: string;
+}
+/** Response shape for POST /v1/user/auth/password. */
+export interface ChangePasswordApiResponse {
+    message?: string;
+}
+export interface ESPRMNeoAuthConfig {
+    awsRegion: string;
+}

package/dist/types/types/automation.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Action target for automation actions
+ */
+export interface ActionTarget {
+    node: string;
+    path: string;
+    value: any;
+}
+/**
+ * Automation conditions (references to trigger IDs)
+ */
+export interface AutomationConditions {
+    and: string[];
+}
+/**
+ * Automation actions (targets to execute)
+ */
+export interface AutomationActions {
+    targets: ActionTarget[];
+}
+/**
+ * Automation enable/disable status as stored and returned by the backend.
+ * `enabled` defaults to `"enabled"` when the field is absent (legacy items).
+ */
+export type AutomationStatus = "enabled" | "disabled";
+/**
+ * Fields the SDK accepts when creating or updating an automation.
+ * `id` is omitted here because the server mints it on creation and it
+ * cannot be changed later.
+ */
+export interface CreateAutomationInput {
+    name: string;
+    conditions: AutomationConditions;
+    actions: AutomationActions;
+    /** Enable/disable flag stored inside the payload. Defaults to "enabled" when absent. */
+    status?: AutomationStatus;
+    retrigger?: boolean;
+}
+/**
+ * A fully-formed automation as returned by the server or held on an
+ * `ESPRMNeoAutomation` instance. Always has an id.
+ */
+export interface AutomationItem extends CreateAutomationInput {
+    id: string;
+}
+/** Response shape for create automation API (snake_case from backend). */
+export interface CreateAutomationApiResponse {
+    automation_id: string;
+    group_id: string;
+    message?: string;
+}
+/**
+ * Raw response shape for get automation / get automations API.
+ * Backend returns a flat object: {id, name, conditions, actions, ...} with no payload wrapper.
+ */
+export interface GetAutomationApiResponse {
+    id: string;
+    name: string;
+    conditions: AutomationConditions;
+    actions: AutomationActions;
+    enabled?: boolean;
+    retrigger?: boolean;
+}

package/dist/types/types/common.d.ts

@@ -0,0 +1,5 @@
+export interface ESPRMNeoConfig {
+    baseUrl: string;
+    awsRegion: string;
+    iotEndpoint: string;
+}

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

@@ -0,0 +1,71 @@
+import type { ESPTransportConfig } from "./transport";
+/**
+ * Discovery protocol / domain identifiers.
+ */
+declare enum ESPDiscoveryProtocol {
+    local = "local"
+}
+/**
+ * Events an app can subscribe to via {@link ESPRMNeoUser.subscribe}.
+ */
+declare enum ESPRMNeoEventType {
+    /** Local (mDNS / LAN) node discovery. */
+    localDiscovery = "com.espressif.event.localDiscovery",
+    /**
+     * All-node parameter updates. Subscribers receive an `ESPNodeUpdateData` for
+     * every node param change, from whichever subscription channel served the
+     * node. Backed by the process-wide node-updates bus.
+     */
+    nodeUpdates = "com.espressif.event.nodeUpdates"
+}
+/**
+ * Parameters passed to a local-discovery adapter to scope the search
+ * (e.g. mDNS service type and domain).
+ */
+interface DiscoveryParamsInterface {
+    /** Service type to browse for, e.g. `_esp_local_ctrl._tcp.` */
+    serviceType: string;
+    /** Discovery domain, e.g. `local`. */
+    domain: string;
+}
+/** Callback invoked by a discovery adapter for each discovered node. */
+type ESPDiscoveryCallback = (info: Record<string, any>) => void;
+/** Callback invoked for a subscribed event (see {@link ESPRMNeoUser.subscribe}). */
+type ESPEventCallback = (arg: any) => void;
+/**
+ * Adapter the app supplies to perform local (LAN / mDNS) discovery. The SDK
+ * starts/stops discovery through this adapter and forwards each result to the
+ * app's subscribed callback.
+ */
+interface ESPLocalDiscoveryAdapterInterface {
+    /**
+     * Starts the discovery process.
+     * @param callback - Invoked for each discovered node. Receives at least
+     *   `{ nodeId, baseUrl }` for the default local protocol.
+     * @param params - Discovery parameters (service type / domain).
+     */
+    startDiscovery(callback: ESPDiscoveryCallback, params: DiscoveryParamsInterface): void;
+    /**
+     * Stops the discovery process.
+     */
+    stopDiscovery(): void;
+}
+/**
+ * Standardized payload delivered to a `localDiscovery` subscriber. The
+ * subscriber typically applies `transportDetails` to the matching node's
+ * `availableTransports` (e.g. via
+ * `node.addTransport(transportDetails.type, transportDetails)`).
+ */
+interface ESPDiscoveredNodeData {
+    nodeId: string;
+    transportDetails: ESPTransportConfig;
+}
+/**
+ * Per-event registry of the subscriber callback held on {@link ESPRMNeoUser}.
+ * One callback per event — subscribing again for the same event replaces the
+ * previous callback rather than appending.
+ */
+type EventCallbacks = {
+    [event in ESPRMNeoEventType | string]?: ESPEventCallback;
+};
+export { ESPDiscoveryProtocol, ESPRMNeoEventType, DiscoveryParamsInterface, ESPLocalDiscoveryAdapterInterface, ESPDiscoveredNodeData, ESPDiscoveryCallback, ESPEventCallback, EventCallbacks, };

package/dist/types/types/export.d.ts

@@ -0,0 +1,17 @@
+export * from "./auth";
+export * from "./automation";
+export * from "./common";
+export * from "./discovery";
+export * from "./input";
+export * from "./output";
+export * from "./provision";
+export * from "./schedule";
+export * from "./storage";
+export * from "./subscription";
+export * from "./trigger";
+export * from "./transport";
+export * from "./group";
+export * from "./node";
+export * from "./localControl";
+export * from "./tsData";
+export * from "./mainTypes";

package/dist/types/types/group.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Options for {@link ESPRMNeoGroup.setParams} (group control / multicast).
+ */
+export interface ESPRMNeoGroupSetParamsOptions {
+    /**
+     * Primary-group scope: target only this subgroup id.
+     * Nested subgroup instances always target their own subgroup id.
+     */
+    subgroupId?: string;
+}

package/dist/types/types/input.d.ts

@@ -0,0 +1,81 @@
+import { ESPStorageAdapter } from "./storage";
+import { ESPProvisionAdapterInterface } from "./provision";
+import { MQTTTransport } from "../services/interfaces/MQTTTransport";
+import { ESPLocalControlAdapterInterface } from "./localControl";
+import { ESPLocalDiscoveryAdapterInterface } from "./discovery";
+/**
+ * Data structure for user tokens.
+ */
+export interface UserTokensData {
+    idToken: string;
+    accessToken: string;
+    refreshToken: string;
+}
+export interface ESPAWSCredentials {
+    accessKey: string;
+    secretKey: string;
+    sessionToken: string;
+    expiration: string;
+    /** Optional status text from POST /v1/user/credentials. */
+    message?: string;
+}
+export interface AWSCredentials {
+    access_key: string;
+    secret_key: string;
+    session_token: string;
+    /** Unix timestamp (int64); optional. */
+    expiration?: number;
+}
+/**
+ * SDK configuration for {@link ESPRMNeoBase.configure}.
+ * Supplies Rainmaker API base URL, Cognito/IoT identifiers, and optional adapters.
+ *
+ * Put the API Gateway stage in `baseUrl` when using the default execute-api host
+ * (e.g. `https://xxx.execute-api.region.amazonaws.com/prod`). Custom domains
+ * typically need no stage segment.
+ */
+export interface ESPRMNeoBaseConfig {
+    /**
+     * Full main API base, including stage if any.
+     * e.g. "https://xxx.execute-api.us-east-1.amazonaws.com/prod"
+     * or custom domain "https://api.example.com"
+     */
+    baseUrl: string;
+    /**
+     * Full User/auth API base, including stage if any.
+     * e.g. "https://xxx.execute-api.us-east-1.amazonaws.com/prod"
+     * or custom domain "https://api.example.com"
+     */
+    userApiBase: string;
+    awsRegion: string;
+    iotEndpoint: string;
+    customStorageAdapter?: ESPStorageAdapter;
+    provisionAdapter?: ESPProvisionAdapterInterface;
+    mqttAdapter?: MQTTTransport;
+    localControlAdapter?: ESPLocalControlAdapterInterface;
+    localDiscoveryAdapter?: ESPLocalDiscoveryAdapterInterface;
+}
+export interface AssumeRoleRequest {
+    access_key: string;
+    secret_key: string;
+    session_token: string;
+    tags?: Record<string, string>;
+    group?: string;
+    subgroup?: string;
+}
+/**
+ * Delivery credentials for registering an integration endpoint
+ * (PUT /v1/integrations/{integrationId}/endpoints). The documented field is
+ * `app_token`; different integration types may accept additional credentials.
+ */
+export interface DeliveryCredentials {
+    app_token: string;
+    [key: string]: string;
+}
+/**
+ * Request body for PUT /v1/integrations/{integrationId}/endpoints.
+ */
+export interface RegisterEndpointRequest {
+    delivery_credentials: DeliveryCredentials;
+    locale?: string;
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Local control adapter interface for node communication over LAN.
+ */
+export interface ESPLocalControlAdapterInterface {
+    /**
+     * Checks if the node is connected.
+     */
+    isConnected(nodeId: string): Promise<boolean>;
+    /**
+     * Connects to the node with local control parameters.
+     */
+    connect(nodeId: string, baseUrl: string, securtiyType: number, pop?: string, username?: string): Promise<Record<string, unknown>>;
+    /**
+     * Sends data to the specified path on the node.
+     */
+    sendData(nodeId: string, path: string, data: string): Promise<string>;
+}

package/dist/types/types/mainTypes.d.ts

@@ -0,0 +1,5 @@
+import { ESPRMNeoAuth } from "../ESPRMNeoAuth";
+import { ESPDevice } from "../ESPDevice";
+import { ESPRMNeoUser } from "../ESPRMNeoUser";
+import "../methods/export";
+export { ESPRMNeoAuth, ESPDevice, ESPRMNeoUser };

package/dist/types/types/node.d.ts

@@ -0,0 +1,202 @@
+/**
+ * ESP RainMaker Neo Node type definitions.
+ *
+ * Hierarchy:
+ * ESPRMNeoNode
+ *   ├── ESPRMNeoDevice[] (logical devices)
+ *   │     └── ESPRMNeoDeviceParam[] (device params)
+ *   └── ESPRMNeoService[] (node services, optional)
+ *         └── ESPRMNeoServiceParam[] (service params)
+ */
+/**
+ * Base attribute interface (name, value).
+ */
+export interface ESPRMNeoAttributeInterface {
+    name: string;
+    value?: unknown;
+}
+/**
+ * Base param interface for device and service params.
+ */
+export interface ESPRMNeoParamInterface {
+    id: string;
+    value?: any;
+    type: string;
+    properties: string[];
+    dataType: string;
+    bounds?: Record<string, unknown>;
+    validStrings?: string[];
+}
+/**
+ * Device parameter – one controllable parameter of a device (e.g. Power, Brightness).
+ */
+export interface ESPRMNeoDeviceParamInterface extends ESPRMNeoParamInterface {
+    deviceName: string;
+    uiType?: string;
+}
+/**
+ * Service parameter – one parameter of a node service (e.g. timezone).
+ */
+export interface ESPRMNeoServiceParamInterface extends ESPRMNeoParamInterface {
+    serviceName: string;
+}
+/**
+ * Logical device inside a node (e.g. switch, light, thermostat).
+ */
+export interface ESPRMNeoDeviceInterface {
+    name: string;
+    displayName: string;
+    type: string;
+    attributes?: ESPRMNeoAttributeInterface[];
+    params?: ESPRMNeoDeviceParamInterface[];
+    primaryParam?: ESPRMNeoDeviceParamInterface;
+}
+/**
+ * Node-level service (not tied to a single device), e.g. time, local control.
+ */
+export interface ESPRMNeoServiceInterface {
+    name: string;
+    type: string;
+    params: ESPRMNeoServiceParamInterface[];
+    value?: any;
+}
+/**
+ * Node info (model, firmware, etc.).
+ */
+export interface ESPRMNeoNodeInfoInterface {
+    name?: string;
+    type: string;
+    model: string;
+    firmwareVersion?: string;
+    readme?: string;
+    [key: string]: unknown;
+}
+/**
+ * Plain-object view of a node's devices, services, and metadata (e.g. from API transforms).
+ * For live instances, use the `ESPRMNeoNode` class.
+ */
+export interface ESPRMNeoNodeData {
+    configVersion?: string;
+    attributes?: ESPRMNeoAttributeInterface[];
+    devices: ESPRMNeoDeviceInterface[];
+    info?: ESPRMNeoNodeInfoInterface;
+    services?: ESPRMNeoServiceInterface[];
+}
+/**
+ * Connectivity status for a node.
+ */
+export interface ESPRMNeoConnectivityStatusInterface {
+    isConnected: boolean;
+    lastConnectionTimestamp: number;
+}
+/**
+ * `state.reported` fields the SDK reads from an AWS IoT device shadow.
+ * Partials are common (e.g. only `ncfg_ver` or only a param subset).
+ */
+export interface ESPRMNeoShadowReported {
+    online?: boolean;
+    params?: Record<string, unknown>;
+    ncfg_ver?: string | number;
+    disconnect_info?: {
+        last_disconnect_ts?: number;
+    };
+}
+/**
+ * Shadow `state` object (`reported` + optional `desired`).
+ */
+export interface ESPRMNeoShadowState {
+    reported?: ESPRMNeoShadowReported;
+    desired?: unknown;
+}
+/**
+ * AWS IoT shadow document shape used for live MQTT updates and GET responses.
+ */
+export interface ESPRMNeoShadowDocument {
+    state?: ESPRMNeoShadowState;
+}
+/**
+ * Params and connectivity derived from a shadow / reported-state payload.
+ */
+export interface ESPRMNeoExtractedShadow {
+    params: Record<string, unknown>;
+    connectivityStatus: ESPRMNeoConnectivityStatusInterface;
+    configVersion: string;
+}
+/**
+ * Node interface – represents a claimed RainMaker Neo node.
+ */
+export interface ESPRMNeoNodeInterface {
+    id: string;
+    nodeId: string;
+    groupId: string;
+    subgroupId?: string;
+    nodeData?: ESPRMNeoNodeData;
+    connectivityStatus?: ESPRMNeoConnectivityStatusInterface;
+    metadata?: Record<string, unknown>;
+    tags?: string[];
+}
+/**
+ * Raw API attribute (snake_case).
+ */
+export interface ESPRMNeoAttributeAPI {
+    name?: string;
+    value?: unknown;
+}
+/**
+ * Raw API param (snake_case).
+ */
+export interface ESPRMNeoParamAPI {
+    data_type: string;
+    id: string;
+    properties: string[];
+    type?: string;
+    ui_type?: string;
+    bounds?: {
+        max: number;
+        min: number;
+    };
+    valid_strings?: string[];
+}
+/**
+ * Raw API node config `info` block (snake_case). Mirrors the backend's
+ * `NodeCfgInfo` struct (rmneo `src/service/config/config.go`), where
+ * `fw_version` is the only required field on the wire. The config is stored
+ * and served verbatim by the backend, so extra keys may pass through.
+ */
+export interface ESPRMNeoNodeInfoAPI {
+    fw_version: string;
+    type?: string;
+    model?: string;
+    name?: string;
+    [key: string]: unknown;
+}
+/**
+ * Raw API device (snake_case).
+ */
+export interface ESPRMNeoDeviceAPI {
+    id: string;
+    params: ESPRMNeoParamAPI[];
+    primary: string;
+    type?: string;
+    attributes?: ESPRMNeoAttributeAPI[];
+}
+/**
+ * Raw API service (snake_case).
+ */
+export interface ESPRMNeoServiceAPI {
+    id: string;
+    type?: string;
+    params?: ESPRMNeoParamAPI[];
+}
+/**
+ * Raw API node config response (snake_case).
+ */
+export interface ESPRMNeoNodeConfigAPI {
+    node_id: string;
+    config: {
+        devices: ESPRMNeoDeviceAPI[];
+        config_version?: string;
+        info?: ESPRMNeoNodeInfoAPI;
+        services?: ESPRMNeoServiceAPI[];
+    };
+}