@espressif/rainmaker-neo-base-sdk 1.0.0

package/dist/types/types/output.d.ts

@@ -0,0 +1,195 @@
+import type { ESPRMNeoAttributeAPI, ESPRMNeoConnectivityStatusInterface, ESPRMNeoDeviceAPI, ESPRMNeoNodeInfoAPI, ESPRMNeoServiceAPI } from "./node";
+import type { ESPRMNeoDevice } from "../ESPRMNeoDevice";
+import type { ESPRMNeoService } from "../ESPRMNeoService";
+/**
+ * Optional human-readable status text from the API body.
+ * Success vs failure is determined by the HTTP status code.
+ */
+interface ESPAPIResponse {
+    message?: string;
+    statusCode?: number;
+    errorCode?: string;
+}
+/**
+ * Represents an error response from the API.
+ */
+interface ESPAPIError extends ESPAPIResponse {
+}
+/**
+ * Represents a successful response from the API (optional message only).
+ */
+interface SuccessResponse {
+    message?: string;
+}
+/**
+ * Options for sharing a group or subgroup.
+ */
+export interface ShareOptions {
+    username: string;
+    accessType: "primary" | "secondary";
+}
+/**
+ * Access type for the current user on a group (GET /v1/groups, GET /v1/groups/{groupId}/users).
+ */
+export type GroupUserAccessType = "primary" | "secondary" | "subgroup";
+/**
+ * Raw API response entry for GET /v1/groups/{groupId}/users.
+ * @internal
+ */
+export interface GroupUserInGroup {
+    user_id: string;
+    email: string;
+    phone_number?: string;
+    access_type: GroupUserAccessType;
+    /** Present when access is via subgroup membership. */
+    subgroups?: string[];
+}
+/**
+ * Raw API response body for GET /v1/groups/{groupId}/users.
+ * @internal
+ */
+export interface ListGroupUsersResponse {
+    users: GroupUserInGroup[];
+}
+/**
+ * A user with access to a group, as returned by {@link ESPRMNeoGroup.getSharingInfo}.
+ */
+export interface GroupUser {
+    userId: string;
+    email: string;
+    phoneNumber?: string;
+    accessType: GroupUserAccessType;
+    /** Present when access is via subgroup membership. */
+    subgroups?: string[];
+}
+/**
+ * Result of {@link ESPRMNeoGroup.getSharingInfo}.
+ */
+export interface GroupSharingInfo {
+    users: GroupUser[];
+}
+interface ConfirmSignUpResponse {
+    message?: string;
+}
+interface ForgotPasswordResponse {
+    message?: string;
+}
+interface SetNewPasswordResponse {
+    message?: string;
+}
+interface ChangePasswordResponse {
+    message?: string;
+}
+interface ESPNodeGroupsResponse extends ESPAPIResponse {
+    groups: ESPNodeGroup[];
+}
+/**
+ * Per-node capability information returned by the groups API inside `node_details`.
+ */
+interface NodeCapabilityInfo {
+    capabilities?: Record<string, Record<string, any>>;
+}
+interface ESPNodeGroup {
+    group_id: string;
+    group_name: string;
+    /** How the user accesses this group (GET /v1/groups). */
+    access_type?: GroupUserAccessType;
+    node_ids?: string[];
+    subgroups?: Subgroup[];
+    node_details?: Record<string, NodeCapabilityInfo>;
+}
+interface Subgroup {
+    subgroup_id: string;
+    subgroup_name: string;
+    node_ids?: string[];
+}
+/**
+ * Represents a group with camelCase properties for SDK use.
+ * Nested groups use the same shape; set `parentId` to the parent group’s `groupId` (root groups omit it).
+ */
+export interface ESPRMNeoGroup {
+    groupId: string;
+    groupName: string;
+    /** How the current user accesses this group (from GET /v1/groups). */
+    accessType?: GroupUserAccessType;
+    /** Set when this group is nested under another; root groups omit this. */
+    parentId?: string;
+    nodeIds?: string[];
+    subgroups?: ESPRMNeoGroup[];
+    nodeDetails?: Record<string, NodeCapabilityInfo>;
+}
+/**
+ * Response from POST /v1/groups/{groupId}/node-assoc-requests
+ * Initiates the process of associating a node with a user's group.
+ * Generates a request ID and challenge string for the verification step.
+ */
+interface InitiateNodeAssociationResponse {
+    request_id: string;
+    challenge: string;
+    message?: string;
+}
+/**
+ * Node configuration from the User API / local cache (wire shape).
+ *
+ * `devices` / `services` are raw snake_case records. {@link ESPRMNeoNode}
+ * transforms them into live {@link ESPRMNeoDevice} / {@link ESPRMNeoService}
+ * instances on {@link NodeConfig}.
+ */
+export interface NodeConfigAPI extends ESPAPIResponse {
+    node_id?: string;
+    devices: ESPRMNeoDeviceAPI[];
+    services: ESPRMNeoServiceAPI[];
+    config_version?: string;
+    info?: ESPRMNeoNodeInfoAPI;
+    data_model?: string;
+    attributes?: ESPRMNeoAttributeAPI[];
+    group_id?: string;
+    subgroup_id?: string;
+    params?: Record<string, unknown>;
+    connectivity_status?: ESPRMNeoConnectivityStatusInterface;
+}
+/**
+ * Runtime node configuration held on {@link ESPRMNeoNode.config}.
+ *
+ * Same metadata as {@link NodeConfigAPI}, but `devices` / `services` are the
+ * live SDK instances (same objects as `node.devices` / `node.services`).
+ */
+export interface NodeConfig extends Omit<NodeConfigAPI, "devices" | "services"> {
+    devices: ESPRMNeoDevice[];
+    services: ESPRMNeoService[];
+}
+interface CreateSubgroupResponse extends ESPAPIResponse {
+    subgroup_id: string;
+}
+/**
+ * A configured integration entry from GET /v1/integrations (non-admin).
+ * Exposes only the id/type and its addressing hint — no credentials or other
+ * configuration. Push integrations carry either `bundle_id` (Apple: `apns` /
+ * `apns_sandbox`) or `project_id` (Firebase: `gcm`), which callers use to pick
+ * the integration matching the current app build.
+ */
+interface IntegrationInfo {
+    integration_id: string;
+    /** e.g. `apns`, `apns_sandbox`, `gcm`. */
+    integration_type: string;
+    /** Apple bundle id, present for `apns` / `apns_sandbox` integrations. */
+    bundle_id?: string;
+    /** Firebase project id, present for `gcm` integrations. */
+    project_id?: string;
+}
+interface ListSharingRequestsResponse extends ESPAPIResponse {
+    sharing_requests: SharingRequestInfo[];
+}
+/** Access grade the recipient will hold once a sharing request is accepted. */
+export type SharingRequestAccessType = "primary" | "secondary" | "subentity";
+interface SharingRequestInfo {
+    sharing_request_id: string;
+    group_id: string;
+    subgroup_id: string;
+    access_type: SharingRequestAccessType;
+    /** Primary user information who sent the share invitation. */
+    primary_user_id?: string;
+    primary_email?: string;
+    primary_phone_number?: string;
+}
+export { ESPAPIResponse, ESPAPIError, SuccessResponse, ESPNodeGroupsResponse, ESPNodeGroup, NodeCapabilityInfo, Subgroup, InitiateNodeAssociationResponse, CreateSubgroupResponse, IntegrationInfo, ListSharingRequestsResponse, SharingRequestInfo, ConfirmSignUpResponse, ForgotPasswordResponse, SetNewPasswordResponse, ChangePasswordResponse, };

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

@@ -0,0 +1,120 @@
+/**
+ * Represents the types of transport mechanisms available.
+ */
+declare enum ESPTransport {
+    ble = "ble",
+    softap = "softap"
+}
+/**
+ * Represents the levels of security available.
+ */
+declare enum ESPSecurity {
+    unsecure = 0,
+    secure = 1,
+    secure2 = 2
+}
+/**
+ * Represents the status of the connection.
+ */
+declare enum ESPConnectStatus {
+    connected = 0,
+    failedToConnect = 1,
+    disconnected = 2
+}
+/**
+ * Represents the status of the provisioning process.
+ */
+declare enum ESPProvisionStatus {
+    success = 0,
+    failure = 1
+}
+/**
+ * Represents a list of WiFi networks.
+ */
+interface ESPWifiList {
+    ssid: string;
+    rssi: number;
+    auth: number;
+    bssid?: string;
+    channel?: number;
+}
+/**
+ * Device descriptor returned by provisioning adapter (search/createESPDevice).
+ * Pass an object implementing this interface to the ESPDevice constructor.
+ */
+interface ESPDeviceInterface {
+    name: string;
+    security: number;
+    transport: string;
+    connected?: boolean;
+    username?: string;
+    versionInfo?: {
+        [key: string]: any;
+    }[];
+    capabilities?: string[];
+    advertisementData?: {
+        [key: string]: any;
+    }[];
+}
+/**
+ * Represents the methods available for provisioning a device.
+ */
+interface ESPProvisionAdapterInterface {
+    searchESPDevices(devicePrefix: string, transport: ESPTransport): Promise<ESPDeviceInterface[]>;
+    stopESPDevicesSearch(): Promise<void>;
+    createESPDevice(name: string, transport: string, security?: number, proofOfPossession?: string, softAPPassword?: string, username?: string): Promise<ESPDeviceInterface>;
+    connect(deviceName: string): Promise<number>;
+    getDeviceCapabilities(deviceName: string): Promise<string[]>;
+    getDeviceVersion(deviceName: string): Promise<{
+        [key: string]: any;
+    }>;
+    setProofOfPossession(deviceName: string, proofOfPossession: string): Promise<boolean>;
+    initializeSession(deviceName: string): Promise<boolean>;
+    scanWifiList(deviceName: string): Promise<ESPWifiList[]>;
+    sendData(deviceName: string, endPoint: string, data: string): Promise<string>;
+    provision(deviceName: string, ssid: string, passphrase: string): Promise<ESPProvisionStatus>;
+    disconnect(deviceName: string): Promise<void>;
+}
+/**
+ * Represents the status of the provisioning response.
+ */
+declare enum ESPProvResponseStatus {
+    onProgress = "onProgress",
+    succeed = "succeed"
+}
+/**
+ * Represents the response received after provisioning.
+ */
+interface ESPProvResponse {
+    status: ESPProvResponseStatus;
+    description?: string;
+}
+/**
+ * Represents the status of a claiming operation.
+ */
+declare enum ESPClaimStatus {
+    /** Claiming in progress */
+    inProgress = "inProgress",
+    /** Claiming succeeded */
+    success = "success",
+    /** Claiming failed */
+    failed = "failed",
+    /** Claiming was aborted */
+    aborted = "aborted"
+}
+/**
+ * Represents a claiming progress callback response.
+ */
+interface ESPClaimResponse {
+    /** Current status of the claiming operation */
+    status: ESPClaimStatus;
+    /** Progress message description */
+    message: string;
+    /** Optional error information */
+    error?: string;
+}
+/**
+ * Callback type for claiming progress updates.
+ */
+type ESPClaimProgressCallback = (response: ESPClaimResponse) => void;
+export { ESPTransport, ESPSecurity, ESPProvisionStatus, ESPConnectStatus, ESPWifiList, ESPDeviceInterface, ESPProvisionAdapterInterface, ESPProvResponse, ESPProvResponseStatus, ESPClaimStatus, ESPClaimResponse, ESPClaimProgressCallback, };

package/dist/types/types/schedule.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Schedule trigger definition (minutes/day/month/year or relative seconds)
+ */
+export interface ScheduleTrigger {
+    m?: number;
+    d?: number;
+    dd?: number;
+    mm?: number;
+    yy?: number;
+    rsec?: number;
+}
+/**
+ * Action map: device -> param -> value
+ */
+export type ScheduleActionMap = Record<string, Record<string, any>>;
+/**
+ * Single schedule item (aligns with Swagger
+ * /v1/groups/{groupId}/nodes/{nodeId}/schedules)
+ */
+export interface ScheduleItem {
+    id?: string;
+    name?: string;
+    enabled: boolean;
+    triggers: ScheduleTrigger[];
+    action: ScheduleActionMap;
+    validity?: {
+        start?: number;
+        end?: number;
+    };
+}
+/**
+ * Node schedule envelope used by backend
+ */
+export interface NodeSchedulePayload {
+    schedule: {
+        schedules: ScheduleItem[];
+    };
+}
+/**
+ * Generic status response from backend for write operations
+ */
+export interface StatusResponse {
+    status?: string;
+    [k: string]: any;
+}

package/dist/types/types/storage.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Interface for a storage adapter, allowing for various implementations
+ * such as localStorage, sessionStorage, or custom storage mechanisms.
+ */
+interface ESPStorageAdapter {
+    /**
+     * Stores a value under the specified name.
+     * @param name - The key under which the value will be stored.
+     * @param value - The value to store.
+     * @returns A promise that resolves when the value is stored.
+     */
+    setItem(name: string, value: string): Promise<void>;
+    /**
+     * Retrieves a stored value by its name.
+     * @param name - The key associated with the value to retrieve.
+     * @returns A promise that resolves with the retrieved value, or null if not found.
+     */
+    getItem(name: string): Promise<string | null>;
+    /**
+     * Removes the stored value associated with the specified name.
+     * @param name - The key of the value to remove.
+     * @returns A promise that resolves when the value is removed.
+     */
+    removeItem(name: string): Promise<void>;
+    /**
+     * Clears all stored values.
+     * @returns A promise that resolves when all values are cleared.
+     */
+    clear(): Promise<void>;
+}
+export { ESPStorageAdapter };

package/dist/types/types/subscription.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Standardized format for node parameter updates from any subscription channel.
+ * All subscription channels must transform their data into this format.
+ */
+export interface ESPNodeUpdateData {
+    /**
+     * ID of the node that was updated
+     */
+    nodeId: string;
+    /**
+     * Source channel that provided this update (e.g., "mqtt", "matter", "ble")
+     */
+    source: string;
+    /**
+     * Type of event (e.g., "rmneo.event.node_params_changed")
+     */
+    eventType: string;
+    /**
+     * The actual parameter data
+     * Format: { <deviceId>: { <paramId>: value } }
+     */
+    payload: Record<string, any>;
+    /**
+     * Optional metadata specific to the channel
+     * Examples:
+     * - MQTT: { topic: "...", shadowName: "params-groupId", qos: 1 }
+     * - Matter: { endpointId: 1, clusterId: 6, attributeId: 0 }
+     */
+    metadata?: Record<string, any>;
+}
+/**
+ * Interface for subscription channels that provide device parameter updates.
+ * Each channel represents a different communication method (MQTT, Matter, BLE, etc.)
+ *
+ * Implementation Guidelines:
+ * - channelId should be unique and descriptive (e.g., "mqtt", "matter", "ble")
+ * - supportsNode() should check if the node has the required capabilities/configuration
+ * - subscribe() should set up the subscription and call the callback when updates arrive
+ * - All updates must be transformed into ESPNodeUpdateData format
+ */
+export interface ESPSubscriptionChannelInterface {
+    /**
+     * Unique identifier for this channel (e.g., "mqtt", "matter", "ble")
+     */
+    readonly channelId: string;
+    /**
+     * Initialize the channel (setup connections, adapters, etc.)
+     * Called once when channel is registered with the subscription manager
+     *
+     * @throws Error if initialization fails
+     */
+    initialize(): Promise<void>;
+    /**
+     * Check if this channel supports a specific node.
+     * This method determines whether the channel can provide updates for the given node.
+     *
+     * Examples:
+     * - MQTT channel: returns true for all nodes (generic)
+     * - Matter channel: returns true only if node has Matter capability in its config
+     * - BLE channel: returns true only if node has BLE support in metadata
+     *
+     * @param node - The node to check support for
+     * @returns true if this channel can provide updates for the node
+     */
+    supportsNode(node: NodeLike): boolean;
+    /**
+     * Subscribe to parameter updates for a specific node.
+     *
+     * @param callback - Function to call when updates are received
+     * @param node - The node to subscribe to. Must carry the identifier and any
+     *   routing context the channel needs (e.g. `groupId`, `subgroupIds` for MQTT
+     *   shadow topic construction). Passing the full node — not just an id —
+     *   lets channels operate without reverse-looking up group membership from
+     *   persistent state.
+     * @returns Promise that resolves when subscription is active
+     * @throws Error if subscription fails (e.g., adapter not configured, connection failed)
+     */
+    subscribe(callback: (update: ESPNodeUpdateData) => void, node: NodeLike): Promise<void>;
+    /**
+     * Unsubscribe from updates.
+     *
+     * @param nodeId - Optional node ID. If omitted, unsubscribes every node.
+     * @param callback - Optional specific subscriber to remove. When provided,
+     *   only that callback is detached; the channel keeps delivering to the node's
+     *   other subscribers and fully detaches the node only once none remain. When
+     *   omitted, all subscribers for the node are removed.
+     * @returns Promise that resolves when unsubscription is complete
+     */
+    unsubscribe(nodeId?: string, callback?: (update: ESPNodeUpdateData) => void): Promise<void>;
+    /**
+     * Cleanup and dispose of all channel resources (connections, callbacks, etc.).
+     * Called when the channel is unregistered or the app is closing.
+     */
+    dispose(): Promise<void>;
+}
+/**
+ * Subscription configuration for a specific node.
+ * Allows per-node customization of subscription channel priority.
+ */
+export interface ESPNodeSubscriptionConfig {
+    /**
+     * Custom channel order for this node (overrides global order).
+     * Channels are tried in the order specified until one succeeds.
+     * If not set, uses the global channel order from ESPRMNeoSubscriptionManager.
+     *
+     * Example: ["matter", "mqtt"]
+     * - Try Matter first (if supported)
+     * - Fall back to MQTT
+     */
+    channelOrder?: string[];
+}
+/**
+ * Minimal structural shape the subscription manager needs from a node.
+ *
+ * Used instead of a hard dependency on {@link ESPRMNeoNode} so that satellite
+ * SDKs (Matter, BLE, …) and lightweight proxies can be passed to the manager.
+ * A node is identified by {@link id} or {@link nodeId}; channel selection may
+ * also read {@link subscriptionConfig}, {@link type} and {@link metadata}.
+ */
+export interface NodeLike {
+    /** Node identifier (preferred). */
+    id?: string;
+    /** Node identifier as used by {@link ESPRMNeoNode}. */
+    nodeId?: string;
+    /**
+     * Group this node belongs to. Required for channels that route by group
+     * (e.g. MQTT constructs its shadow name from `groupId` + `subgroupIds`).
+     */
+    groupId?: string;
+    /**
+     * Subgroup ids this node belongs to under {@link groupId}. Passed through to
+     * MQTT shadow-name construction. Empty/omitted → group-level shadow.
+     */
+    subgroupIds?: string[];
+    /** Per-node channel order override. */
+    subscriptionConfig?: ESPNodeSubscriptionConfig;
+    /** Optional node type hint used by capability-gated channels. */
+    type?: string;
+    /** Optional metadata used by capability-gated channels (e.g. Matter markers). */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Resolves the canonical node id from a {@link NodeLike} (`id` preferred,
+ * falling back to `nodeId`).
+ *
+ * @param node - The node-like object.
+ * @returns The node id, or `undefined` if neither field is set.
+ */
+export declare function resolveNodeId(node: NodeLike): string | undefined;

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

@@ -0,0 +1,65 @@
+import { ESPAPIResponse } from "./output";
+import type { ESPRMNeoNode } from "../ESPRMNeoNode";
+/**
+ * Defines the transport mode for ESP node communication.
+ *
+ * The transport mode specifies whether communication is done locally (LAN /
+ * local-control) or through MQTT (the RainMaker Neo cloud channel: AWS IoT
+ * shadow / RainMaker user params topic).
+ */
+declare enum ESPTransportMode {
+    /** Communication is handled locally over the LAN, without cloud intervention. */
+    local = "local",
+    /** Communication is routed through MQTT (RainMaker Neo cloud: AWS shadow). */
+    mqtt = "mqtt"
+}
+/**
+ * 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).
+ */
+interface ESPTransportConfig {
+    /**
+     * Transport mode. One of {@link ESPTransportMode} for built-in transports,
+     * or an arbitrary string key for a custom transport registered via
+     * `customTransportManagers` on the node.
+     */
+    type: ESPTransportMode | string;
+    /**
+     * Additional metadata for the transport configuration.
+     *
+     * This can include any key-value pairs relevant to the chosen transport mode.
+     */
+    metadata: Record<string, any>;
+}
+/**
+ * Contract implemented by every transport (built-in or custom). The
+ * {@link delegatedTransportHandler} drives a transport purely through this
+ * interface, so custom transports (BLE, WebSocket, proprietary) are
+ * interchangeable with the built-in local/cloud transports.
+ */
+interface ESPTransportInterface {
+    /**
+     * Sets parameters on the node.
+     * @param payload - `{ node_id, payload }` where `payload` is the
+     *   `{ <deviceOrServiceId>: { <paramId>: value } }` map to apply.
+     * @param nodeRef - Optional reference to the node instance (custom transports
+     *   may use it to read config/metadata).
+     * @returns A promise resolving to the API response.
+     */
+    setParam(payload: Record<string, any>, nodeRef?: ESPRMNeoNode): Promise<ESPAPIResponse>;
+    /**
+     * Gets parameters from the node.
+     * @param payload - `{ node_id }` identifying the node to read.
+     * @param nodeRef - Optional reference to the node instance.
+     * @returns A promise resolving to the node's parameters.
+     */
+    getParams(payload: Record<string, any>, nodeRef?: ESPRMNeoNode): Promise<Record<string, any>>;
+}
+/**
+ * Default transport priority order used when neither the node nor the SDK base
+ * 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, };

package/dist/types/types/trigger.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Trigger comparison operator, matching the wire format expected by the
+ * RainMaker firmware trigger codec (`eq`/`ne`/`gt`/`lt`/`ge`/`le`). The cloud
+ * stores triggers verbatim, so any other spelling (e.g. `"=="`) reaches the
+ * device unchanged and makes it reject the node's entire trigger list.
+ */
+export type TriggerOperator = "eq" | "ne" | "gt" | "lt" | "ge" | "le";
+/**
+ * Single trigger item.
+ */
+export interface TriggerItem {
+    /** Server-visible id (must be unique within the node's trigger list). */
+    id: string;
+    /** Trigger source category (e.g. `"param"` for a device param trigger). */
+    type: string;
+    /** Dotted path locating the value to watch, e.g. `"Light.Power"`. */
+    path: string;
+    /** Comparison operator applied to `path`'s current value against `value`. */
+    operator: TriggerOperator;
+    /** Right-hand side of the comparison. */
+    value: unknown;
+    /** Whether the trigger is armed. Defaults to `true` on the server when absent. */
+    enabled?: boolean;
+}