@espressif/rainmaker-admin-sdk

TypeScript SDK for building admin applications on the ESP RainMaker platform. Provides typed, modular APIs for fleet-wide node management, OTA updates, user administration, role-based access control, deployment configuration, and more.

📖 SDK Documentation — Getting started guides, configuration reference, and full API docs.

Table of Contents

• Features
• Requirements
• Installation
• Quick Start
• Authentication
• Usage
• Available Modules
• Error Handling
• Storage Adapters
• Updating the Library
• Versioning
• Security
• License

Features

• Framework-agnostic — works with React, Vue, Angular, Svelte, Node.js, or plain JavaScript
• Admin APIs for nodes, groups, users, OTA images and jobs, tags, custom data, files
• Role-based access control: roles, policies, and user-role assignment
• Super-admin APIs: identity providers, Cognito, message templates, push notifications, webhooks, deployment settings, statistics, licensing
• Automatic session handling: tokens are stored, refreshed before expiry, and cleared on sign-out
• Full TypeScript types for every request and response
• Self-contained sub-path exports for each module, ESM and CommonJS output
• Zero runtime dependencies

Requirements

• A browser with the Fetch API, or Node.js 20.17 or later
• An ESP RainMaker deployment and an admin (or super-admin) account

Installation

npm install @espressif/rainmaker-admin-sdk

The package is published to public npm under the @espressif scope. It ships prebuilt ESM and CommonJS bundles with type declarations, so no registry configuration or build step is needed.

Quick Start

Configure the SDK once, before using any module:

import { ESPRMBase } from "@espressif/rainmaker-admin-sdk";

ESPRMBase.configure({
  baseUrl: "https://api.rainmaker.espressif.com",
  version: "v1",
});

| Option | Type | Required | Description | | ---------------------- | ------------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------- | | baseUrl | string | Yes | ESP RainMaker API base URL (without the version segment) | | version | string | No | API version path segment. Default v1 | | customStorageAdapter | ESPRMStorageAdapterInterface | No | Token storage. Default window.localStorage; required outside the browser (see Storage Adapters) | | timeoutMs | number | No | Per-request timeout in milliseconds. Default 30000; 0 disables |

Authentication

const auth = ESPRMBase.getAuthInstance();

// Sign in. Tokens are persisted in the configured storage.
const user = await auth.login("<USERNAME>", "<PASSWORD>");

// Restore a previous session on app start (returns null if none is valid).
const existing = await auth.getLoggedInUser();

// Sign out and clear stored tokens.
await auth.logout();

After sign-in, every admin call attaches the access token automatically and refreshes it when it is about to expire. If the server rejects the token (HTTP 401), stored tokens are cleared and the error carries additionalInfo asking the user to sign in again.

Usage

// Import from the root entry point
import {
  ESPRMBase,
  ESPRMAdminNode,
  ESPRMAdminOTAJob,
} from "@espressif/rainmaker-admin-sdk";

// Or import individual modules for smaller bundles. Each sub-path is
// self-contained: it registers the module's methods on import.
import { ESPRMBase } from "@espressif/rainmaker-admin-sdk/ESPRMBase";
import { ESPRMAdminNode } from "@espressif/rainmaker-admin-sdk/ESPRMAdminNode";

Node management

const adminNode = new ESPRMAdminNode();

const nodes = await adminNode.getNodes({ num_records: "50" });
await adminNode.activateDeactivateNodes({
  node_id: "<NODE_ID>",
  activate: true,
});

OTA

import {
  ESPRMAdminOTAImage,
  ESPRMAdminOTAJob,
} from "@espressif/rainmaker-admin-sdk";

const images = await new ESPRMAdminOTAImage().getImages();
const job = await new ESPRMAdminOTAJob().createJob({
  ota_job_name: "fleet-rollout-1",
  ota_image_id: "<OTA_IMAGE_ID>",
});
const status = await new ESPRMAdminOTAJob().getJobStatus({
  ota_job_id: job.ota_job_id,
});

Groups and users

import {
  ESPRMAdminGroup,
  ESPRMAdminUser,
} from "@espressif/rainmaker-admin-sdk";

const groups = await new ESPRMAdminGroup().getGroups();
const users = await new ESPRMAdminUser().getUsers();

Every method's parameters and return type are documented in the API reference.

Available Modules

Core

| Module | Sub-path | Description | | ----------- | ------------- | -------------------------------------------------------------- | | ESPRMBase | ./ESPRMBase | SDK configuration and access to the auth instance | | ESPRMAuth | ./ESPRMAuth | Sign-in, sign-out, sign-up, password recovery, session restore | | ESPRMUser | ./ESPRMUser | Signed-in user profile and token helpers |

Admin modules

| Module | Sub-path | Description | | --------------------------------- | ----------------------------------- | ------------------------------------------------ | | ESPRMAdminAPIGateway | ./ESPRMAdminAPIGateway | API gateway | | ESPRMAdminAPIInfo | ./ESPRMAdminAPIInfo | API info | | ESPRMAdminAPIRateLimit | ./ESPRMAdminAPIRateLimit | API rate limit configuration | | ESPRMAdminAPIStatistics | ./ESPRMAdminAPIStatistics | API statistics | | ESPRMAdminCloudwatchLog | ./ESPRMAdminCloudwatchLog | Cloudwatch log IAM user | | ESPRMAdminCognitoAppClient | ./ESPRMAdminCognitoAppClient | Cognito app client | | ESPRMAdminCognitoDomain | ./ESPRMAdminCognitoDomain | Cognito domain | | ESPRMAdminCommonCustomData | ./ESPRMAdminCommonCustomData | Common custom data | | ESPRMAdminConfiguration | ./ESPRMAdminConfiguration | Configuration | | ESPRMAdminCustomData | ./ESPRMAdminCustomData | Custom user data management | | ESPRMAdminCustomMessageTemplate | ./ESPRMAdminCustomMessageTemplate | Custom mobile push notification message template | | ESPRMAdminDashboard | ./ESPRMAdminDashboard | Dashboard | | ESPRMAdminDeploymentCapability | ./ESPRMAdminDeploymentCapability | Deployment capability | | ESPRMAdminDeploymentDetails | ./ESPRMAdminDeploymentDetails | Deployment details | | ESPRMAdminDeploymentSetting | ./ESPRMAdminDeploymentSetting | Deployment setting | | ESPRMAdminEventFilter | ./ESPRMAdminEventFilter | Event filter management | | ESPRMAdminFile | ./ESPRMAdminFile | File upload management | | ESPRMAdminGroup | ./ESPRMAdminGroup | Group management | | ESPRMAdminIdentityProvider | ./ESPRMAdminIdentityProvider | Identity provider | | ESPRMAdminIoTDeviceRateLimit | ./ESPRMAdminIoTDeviceRateLimit | IoT device rate limit configuration | | ESPRMAdminKey | ./ESPRMAdminKey | Key management | | ESPRMAdminLicense | ./ESPRMAdminLicense | License | | ESPRMAdminLogConfig | ./ESPRMAdminLogConfig | Log configuration | | ESPRMAdminMQTTStatistics | ./ESPRMAdminMQTTStatistics | MQTT statistics | | ESPRMAdminMailFailure | ./ESPRMAdminMailFailure | Mail delivery failure log | | ESPRMAdminMatter | ./ESPRMAdminMatter | Matter setup | | ESPRMAdminMessageTemplate | ./ESPRMAdminMessageTemplate | Message template | | ESPRMAdminMobilePlatform | ./ESPRMAdminMobilePlatform | Mobile platform application | | ESPRMAdminNode | ./ESPRMAdminNode | Node management | | ESPRMAdminNodeCertificateCA | ./ESPRMAdminNodeCertificateCA | Node certificate CA | | ESPRMAdminNodeParams | ./ESPRMAdminNodeParams | Node parameter | | ESPRMAdminNodeRegistration | ./ESPRMAdminNodeRegistration | Node registration | | ESPRMAdminOTAImage | ./ESPRMAdminOTAImage | OTA image management | | ESPRMAdminOTAJob | ./ESPRMAdminOTAJob | OTA job management | | ESPRMAdminPassthrough | ./ESPRMAdminPassthrough | External API passthrough | | ESPRMAdminPolicy | ./ESPRMAdminPolicy | RBAC policy management | | ESPRMAdminPublishMessage | ./ESPRMAdminPublishMessage | Publish message | | ESPRMAdminRole | ./ESPRMAdminRole | RBAC role management | | ESPRMAdminSecureSign | ./ESPRMAdminSecureSign | Secure signing | | ESPRMAdminSenderEmail | ./ESPRMAdminSenderEmail | Sender email | | ESPRMAdminStatisticalService | ./ESPRMAdminStatisticalService | Statistical service | | ESPRMAdminSuperAdmin | ./ESPRMAdminSuperAdmin | Super admin management | | ESPRMAdminTag | ./ESPRMAdminTag | Tag management | | ESPRMAdminTermsPolicy | ./ESPRMAdminTermsPolicy | Terms and policy | | ESPRMAdminUser | ./ESPRMAdminUser | User management | | ESPRMAdminUserRole | ./ESPRMAdminUserRole | User-role mapping | | ESPRMAdminWebhook | ./ESPRMAdminWebhook | Webhook integration |

Error Handling

API failures reject with an ESPAPIError object:

import type { ESPAPIError } from "@espressif/rainmaker-admin-sdk";

try {
  await new ESPRMAdminNode().getNodes();
} catch (e) {
  const err = e as ESPAPIError;
  err.statusCode; // HTTP status (0 for timeouts and network failures)
  err.errorCode; // RainMaker error code, or REQUEST_TIMEOUT / NETWORK_ERROR
  err.description; // Human-readable message
  err.additionalInfo; // Set on 401: the user must sign in again
}

Problems detected before a request is sent (missing configuration, invalid arguments, missing or malformed tokens, unsupported storage) throw subclasses of ESPBaseError, which extends Error and exposes code and label.

Storage Adapters

Tokens are stored through a small async interface. The default uses window.localStorage; in Node.js, React Native, or web workers provide your own:

import {
  ESPRMBase,
  type ESPRMStorageAdapterInterface,
} from "@espressif/rainmaker-admin-sdk";

class MemoryStorage implements ESPRMStorageAdapterInterface {
  #store = new Map<string, string>();
  async setItem(name: string, value: string) {
    this.#store.set(name, value);
  }
  async getItem(name: string) {
    return this.#store.get(name) ?? null;
  }
  async removeItem(name: string) {
    this.#store.delete(name);
  }
  async clear() {
    this.#store.clear();
  }
}

ESPRMBase.configure({
  baseUrl: "https://api.rainmaker.espressif.com",
  customStorageAdapter: new MemoryStorage(),
});

Store tokens as securely as your platform allows; they grant admin access to your deployment.

Security note. The default window.localStorage adapter stores the access, ID and refresh tokens unencrypted, readable by any script running on your origin (including a compromised third-party script or a browser extension). For an admin application, prefer a hardened adapter where the platform offers one, keep third-party scripts off the admin origin, and always use an https:// baseUrl. See SECURITY.md.

Updating the Library

Patch updates within the current range

If package.json pins "^0.5.0" and a newer patch is available:

npm update @espressif/rainmaker-admin-sdk

package.json is unchanged; package-lock.json records the new patch. Commit the lockfile.

Plain npm install (no arguments) respects the existing lockfile and does not pick up newer patches.

Minor or major bumps

npm install @espressif/rainmaker-admin-sdk@^0.6.0

Both package.json and package-lock.json change. Commit both.

Check the installed version

npm ls @espressif/rainmaker-admin-sdk

See all releases on the package's versions page and the CHANGELOG.

Versioning

This project follows Semantic Versioning. While the major version is 0, minor releases may contain breaking changes; consult the CHANGELOG before widening a range.

Security

Please report vulnerabilities privately as described in SECURITY.md.

License

Licensed under the Apache License 2.0. See NOTICE for trademark information.

© 2026 Espressif Systems (Shanghai) CO LTD