@espressif/rainmaker-admin-sdk 1.0.0

package/dist/types/types/api_statistics.d.ts

@@ -0,0 +1,70 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/** Single time-bucket value in API usage statistics. */
+export interface APIStatisticsValuePoint {
+    /** Unix timestamp (seconds) for the bucket start. */
+    ts: number;
+    val: number;
+    /** Present when the request used `group_by: "api_path"`. */
+    api_path?: string;
+    /**
+     * Present when the request used `group_by: "user"`.
+     * @deprecated Prefer `user_id`; some backends historically returned `user`.
+     */
+    user?: string;
+    /** User identifier when the request used `group_by: "user"`. */
+    user_id?: string;
+}
+/** One stats payload block (typically one row of aggregated series). */
+export interface APIStatisticsSeries {
+    values: APIStatisticsValuePoint[];
+    num_records: number;
+}
+/** Aggregated slice returned for one query (possibly paginated). */
+export interface APIStatisticsBucket {
+    stats: APIStatisticsSeries[];
+    aggregate: string;
+    aggregation_interval: string;
+    /** Set when the request used `group_by` (e.g. `api_path`, `user`). */
+    group_by?: string;
+    /** Pagination cursor for the next request (`start_id`). */
+    next_id?: string;
+}
+/** Query parameters for retrieving API usage statistics. */
+export interface GetAPIStatisticsParams {
+    /**
+     * Filter by API path for `GET /admin/api_stats` (query key `api_path`).
+     */
+    api_path?: string;
+    /**
+     * @deprecated Prefer `api_path` for `/admin/api_stats` path filtering.
+     */
+    api?: string;
+    /** Filter by HTTP method. */
+    method?: string;
+    /** Filter by node firmware version. */
+    fw_version?: string;
+    /** Aggregation measure (e.g. `count`). */
+    aggregate?: string;
+    /** Aggregation interval aligned with dashboard stats (e.g. `day`, `week`). */
+    aggregation_interval?: string;
+    /** Maximum number of records to return per page. */
+    num_records?: string | number;
+    /** Pagination cursor from the previous response (`next_id`). */
+    start_id?: string;
+    /** Start of the time range as a Unix timestamp (seconds). */
+    start_time?: number;
+    /** End of the time range as a Unix timestamp (seconds). */
+    end_time?: number;
+    /** Timezone for the statistics data. */
+    timezone?: string;
+    /** Group results (e.g. `api_path`, `user`). */
+    group_by?: string;
+}
+/** Response from GET /admin/api_stats. */
+export interface GetAPIStatisticsResponse {
+    api_stats: APIStatisticsBucket[];
+}

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

@@ -0,0 +1,86 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/** Request body for user sign-up / login with password. */
+export interface SignUpRequest {
+    user_name: string;
+    password: string;
+}
+/** Request body for confirming a user. */
+export interface ConfirmUserRequest {
+    user_name: string;
+    verification_code: string;
+    tags?: string[];
+}
+/** Request body for changing password. */
+export interface ChangePasswordRequest {
+    password: string;
+    newpassword: string;
+}
+/** Request body for forgot password (request phase). */
+export interface ForgotPasswordRequest {
+    user_name: string;
+}
+/** Request body for forgot password (confirm phase). */
+export interface ForgotPasswordConfirmRequest {
+    user_name: string;
+    password: string;
+    verification_code: string;
+}
+/** Request body for logout. */
+export interface LogoutRequest {
+    refreshtoken?: string;
+}
+/** Request body for updating user profile. */
+export interface UpdateUserProfileRequest {
+    name?: string;
+    phone_number?: string;
+    verification_code?: string;
+    mfa?: boolean;
+    locale?: string;
+    operation?: "add" | "remove";
+    tags?: string[];
+    tags_verification_code?: string;
+}
+/** Parameters for deleting user account. */
+export interface DeleteAccountParams {
+    request?: boolean;
+    verification_code?: string;
+    locale?: string;
+}
+/** Login response containing tokens. */
+export interface LoginWithPasswordResponse {
+    status: string;
+    description: string;
+    idtoken: string;
+    accesstoken: string;
+    refreshtoken: string;
+}
+/** Response when extending a session via refresh token. */
+export interface ExtendSessionResponse {
+    status: string;
+    description: string;
+    idtoken: string;
+    accesstoken: string;
+}
+/** Response for login without password (OTP flow). */
+export interface LoginWithoutPasswordResponse {
+    status: string;
+    description: string;
+    session: string;
+}
+/** Response for GET /user2. */
+export interface GetUserInfoResponse {
+    user_id: string;
+    user_name: string;
+    super_admin?: boolean;
+    admin?: boolean;
+    picture_url?: string;
+    name?: string;
+    mfa?: boolean;
+    phone_number?: string;
+    locale?: string;
+    tags?: string[];
+}

package/dist/types/types/cloudwatch_log.d.ts

@@ -0,0 +1,10 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/** Request body for adding a user to CloudWatch log access. */
+export interface AddCloudwatchLogUserRequest {
+    /** The email address of the user to grant CloudWatch log access. */
+    email: string;
+}

package/dist/types/types/cognito_app_client.d.ts

@@ -0,0 +1,45 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/** Request body for creating a new Cognito app client. */
+export interface CreateCognitoAppClientRequest {
+    /** Name of the app client to create. */
+    client_name: string;
+    /** Whether to generate a client secret for the app client. */
+    generate_secret?: boolean;
+}
+/** Request body for updating an existing Cognito app client. */
+export interface UpdateCognitoAppClientRequest {
+    /** ID of the app client to update. */
+    client_id: string;
+    /** Identity providers to associate with the app client. */
+    providers?: string[];
+    /** Allowed OAuth callback URLs for the app client. */
+    callback_urls?: string[];
+}
+/** Parameters for listing Cognito app clients. */
+export interface GetCognitoAppClientsParams {
+    /** Whether to query the email/mobile user pool instead of the default. */
+    email_mobile_userpool?: boolean;
+}
+/** Optional query parameters for updating Cognito app clients. */
+export interface UpdateCognitoAppClientParams {
+    /** Whether to update the email/mobile user pool instead of the default. */
+    email_mobile_userpool?: boolean;
+}
+/** Information about a Cognito app client. */
+export interface CognitoAppClientInfo {
+    /** ID of the Cognito user pool. */
+    user_poolid?: string;
+    /** Unique identifier of the app client. */
+    client_id?: string;
+    /** Display name of the app client. */
+    client_name?: string;
+    /** Identity providers associated with the app client. */
+    identity_providers?: string[];
+    /** Configured OAuth callback URLs. */
+    callback_urls?: string[];
+}
+export type GetCognitoAppClientsResponse = CognitoAppClientInfo[];

package/dist/types/types/cognito_domain.d.ts

@@ -0,0 +1,26 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/** Request body for creating a Cognito custom domain. */
+export interface CreateCognitoDomainRequest {
+    /** Custom domain name to assign to the Cognito user pool. */
+    domain_name: string;
+}
+/** Parameters for retrieving the Cognito domain configuration. */
+export interface GetCognitoDomainParams {
+    /** Whether to query the email/mobile user pool instead of the default. */
+    email_mobile_userpool?: boolean;
+}
+/** Parameters for deleting a Cognito custom domain. */
+export interface DeleteCognitoDomainParams {
+    /** Whether to target the email/mobile user pool instead of the default. */
+    email_mobile_userpool?: boolean;
+}
+/** Response containing the Cognito domain configuration. */
+export interface GetCognitoDomainResponse {
+    /** The configured custom domain name. */
+    domain?: string;
+    [key: string]: unknown;
+}

package/dist/types/types/command_response.d.ts

@@ -0,0 +1,82 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/** Parameters for listing command requests. */
+export interface GetCommandRequestsParams {
+    /** Filter by specific request ID. */
+    request_id?: string;
+    /** Filter by node ID. */
+    node_id?: string;
+    /** Filter by request status. */
+    status?: string;
+    /** Filter requests created after this timestamp. */
+    start_time?: number;
+    /** Filter requests created before this timestamp. */
+    end_time?: number;
+    /** Filter by command ID. */
+    cmd_id?: number;
+    /** Whether to return results in descending order. */
+    desc_order?: boolean;
+    /** Request ID to start pagination from. */
+    start_id?: string;
+    /** Maximum number of records to return. */
+    num_records?: number;
+}
+/** Request body for sending a command to nodes. */
+export interface AddCommandRequestBody {
+    /** List of node IDs to send the command to. */
+    node_ids: string[];
+    /** Command identifier. */
+    cmd: number;
+    /** Payload data for the command. */
+    data: unknown;
+    /** Whether the data is base64-encoded. */
+    is_base64?: boolean;
+    /** Timeout in seconds for the command. */
+    timeout?: number;
+    /** Whether to override a pending command. */
+    override?: boolean;
+}
+/** Information about a command request and its response. */
+export interface CommandRequestInfo {
+    /** Unique identifier of the command request. */
+    request_id: string;
+    /** Current status of the request. */
+    status: string;
+    /** Device-reported status code. */
+    device_status?: number;
+    /** Human-readable description of the status. */
+    status_description?: string;
+    /** Data sent in the request. */
+    request_data?: unknown;
+    /** Data received in the response. */
+    response_data?: unknown;
+    /** Node ID the command was sent to. */
+    node_id: string;
+    /** Timestamp when the request was created. */
+    request_timestamp?: number;
+    /** Timestamp when the response was received. */
+    response_timestamp?: number;
+    /** Timestamp when the request expires. */
+    expiration_timestamp?: number;
+    /** Command identifier. */
+    cmd?: number;
+}
+/** Paginated response containing a list of command requests. */
+export interface GetCommandRequestsResponse {
+    /** List of command request objects. */
+    requests?: CommandRequestInfo[];
+    /** Total number of requests matching the query. */
+    total?: number;
+    /** ID to use for fetching the next page. */
+    next_id?: string;
+}
+/** Response returned after adding a command request. */
+export interface AddCommandRequestResponse {
+    /** ID assigned to the new command request. */
+    request_id: string;
+    /** Status of the command submission. */
+    status: string;
+}

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

@@ -0,0 +1,17 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/** Common pagination fields shared across paginated API responses. */
+export interface PaginationFields {
+    /** Cursor token for fetching the next page of results. */
+    next_id?: string;
+    /** Total number of records available. */
+    total?: number;
+}
+/** Mode for property checking. */
+export declare enum PropertyCheckMode {
+    OwnPropertyOnly = "OwnPropertyOnly",
+    PrototypeChain = "PrototypeChain"
+}

package/dist/types/types/common_custom_data.d.ts

@@ -0,0 +1,21 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/** Request body for setting a common custom data entry. */
+export interface SetCommonCustomDataRequest {
+    /** Name of the custom data entry. */
+    name: string;
+    /** Value to assign to the custom data entry. */
+    value: unknown;
+}
+/** Parameters for retrieving common custom data. */
+export interface GetCommonCustomDataParams {
+    /** Name of the custom data entry to retrieve. */
+    name?: string;
+}
+/** Response containing common custom data as dynamic key-value pairs. */
+export interface GetCommonCustomDataResponse {
+    [key: string]: unknown;
+}

package/dist/types/types/config.d.ts

@@ -0,0 +1,59 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ESPRMStorageAdapterInterface } from "./storage.js";
+/** Configuration for the ESPRMBase SDK. */
+export interface ESPRMBaseConfig {
+    /** ESP RainMaker API base URL, e.g. `https://api.rainmaker.espressif.com`. */
+    baseUrl: string;
+    /** API version path segment. Defaults to `v1`. */
+    version?: string;
+    /**
+     * Storage used to persist session tokens. Defaults to `window.localStorage`;
+     * required in environments without it (Node.js, React Native, workers).
+     */
+    customStorageAdapter?: ESPRMStorageAdapterInterface;
+    /**
+     * Per-request timeout in milliseconds applied to every API call. Requests
+     * exceeding it are aborted and rejected with an `ESPAPIError` whose
+     * `errorCode` is `REQUEST_TIMEOUT`. Defaults to 30000. Set to `0` to disable.
+     */
+    timeoutMs?: number;
+}
+/** Configuration for the ESPRMAPIManager. */
+export interface ESPRMAPIManagerConfig {
+    baseUrl: string;
+    version: string;
+    timeoutMs?: number;
+}
+/** Configuration for an API request made through ESPRMAPIManager. */
+export interface ESPRMRequestConfig {
+    /** The API endpoint path (appended to the base URL). */
+    url: string;
+    /** The HTTP method to use. */
+    method: string;
+    /** Request body data (will be JSON-stringified). */
+    data?: Record<string, unknown> | object;
+    /** URL query parameters. */
+    params?: Record<string, string> | object;
+    /** Additional HTTP headers. */
+    headers?: Record<string, string>;
+    /**
+     * Override the base URL for this request.
+     *
+     * **Security note:** when used with `ESPRMAPIManager.authorizeRequest`, the
+     * user's access token is sent to this host. Only point it at the trusted
+     * ESP RainMaker deployment; never at a URL derived from untrusted input.
+     */
+    baseURL?: string;
+    /** Per-request timeout in milliseconds; overrides the configured default. */
+    timeoutMs?: number;
+}
+/** Data required to create an ESPRMUser instance. */
+export interface UserTokensData {
+    accessToken: string;
+    idToken: string;
+    refreshToken: string;
+}

package/dist/types/types/configuration.d.ts

@@ -0,0 +1,20 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/** Parameters for retrieving notification configurations. */
+export interface GetNotificationsParams {
+    /** The service name to filter by. */
+    service_name?: string;
+}
+/** Request body for updating notification configuration. */
+export interface UpdateNotificationsRequest {
+    /** The service name to update. */
+    service_name: string;
+    [key: string]: unknown;
+}
+/** Response containing notification configuration data. */
+export interface GetNotificationsResponse {
+    [key: string]: unknown;
+}

package/dist/types/types/custom_data.d.ts

@@ -0,0 +1,23 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/** Parameters for retrieving admin-level custom data. */
+export interface GetAdminCustomDataParams {
+    /** User ID to filter custom data by. */
+    user_id?: string;
+    /** Username to filter custom data by. */
+    user_name?: string;
+}
+/** Parameters for setting admin-level custom data. */
+export interface SetAdminCustomDataParams {
+    /** User ID to set custom data for. */
+    user_id?: string;
+    /** Username to set custom data for. */
+    user_name?: string;
+}
+/** Response containing custom data as dynamic key-value pairs. */
+export interface CustomDataResponse {
+    [key: string]: unknown;
+}

package/dist/types/types/custom_message_template.d.ts

@@ -0,0 +1,86 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/** Request body for creating a custom message template. */
+export interface CreateCustomMessageTemplateRequest {
+    /** The event type for the template (SNS topic name). */
+    event_type?: string;
+    /** Common custom message title (max 50 characters). */
+    message_title?: string;
+    /** The message body content (max 1500 characters). */
+    message_body?: string;
+    /** Optional event data associated with the template (`enable` or `disable`). */
+    event_data?: string;
+    /** Priority settings per platform. */
+    priority?: {
+        /** Android notification priority level (`high` or `normal`). */
+        android?: string;
+        /** iOS notification priority level (1, 5, or 10). */
+        ios?: number;
+    };
+}
+/** Request body for updating a custom message template (sent in PUT body). */
+export interface UpdateCustomMessageTemplateBody {
+    /** Common custom message title (max 50 characters). */
+    message_title?: string;
+    /** The updated message body content (max 1500 characters). */
+    message_body?: string;
+    /** Updated event data for the template (`enable` or `disable`). */
+    event_data?: string;
+    /** Updated priority settings per platform. */
+    priority?: {
+        /** Android notification priority level. */
+        android?: string;
+        /** iOS notification priority level. */
+        ios?: number;
+    };
+}
+/** Parameters for updating a custom message template. */
+export interface UpdateCustomMessageTemplateRequest extends UpdateCustomMessageTemplateBody {
+    /**
+     * Event type query parameter. Omit when updating only the common message title.
+     */
+    event_type?: string;
+}
+/** Parameters for retrieving custom message templates. */
+export interface GetCustomMessageTemplatesParams {
+    /** The event type to filter by. */
+    event_type?: string;
+}
+/** Parameters for deleting a custom message template. */
+export interface DeleteCustomMessageTemplateParams {
+    /** The event type of the template to delete, or `all` for all supported types. */
+    event_type: string;
+    /**
+     * When true, completely deletes the template including event_data.
+     * When false (default), only clears the message body.
+     */
+    reset_to_default?: boolean;
+    /**
+     * When true, clears only the priority field. Cannot be used with reset_to_default.
+     */
+    reset_priority?: boolean;
+}
+/** Information about a custom message template. */
+export interface CustomMessageTemplateInfo {
+    /** The event type of the template. */
+    event_type?: string;
+    /** The message body content. */
+    message_body?: string;
+    /** Event data associated with the template. */
+    event_data?: string;
+    /** Priority settings per platform. */
+    priority?: {
+        android?: string;
+        ios?: number;
+    };
+}
+/** Response containing custom message templates. */
+export interface GetCustomMessageTemplatesResponse {
+    /** The common custom title for templates. */
+    common_custom_title?: string;
+    /** List of custom message templates. */
+    custom_message_templates?: CustomMessageTemplateInfo[];
+}

package/dist/types/types/dashboard.d.ts

@@ -0,0 +1,23 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/** Request body for updating the dashboard version. */
+export interface UpdateDashboardRequest {
+    /** The target dashboard version. */
+    version: string;
+}
+/** Response containing dashboard update status. */
+export interface GetDashboardUpdateStatusResponse {
+    /** The current or target dashboard version. */
+    version?: string;
+    [key: string]: unknown;
+}
+/** Response containing dashboard version compatibility mappings. */
+export interface GetDashboardVersionMappingResponse {
+    /** Backend version compatibility mapping. */
+    backend?: Record<string, string[]>;
+    /** Frontend version compatibility mapping. */
+    frontend?: Record<string, string[]>;
+}

package/dist/types/types/deployment_capability.d.ts

@@ -0,0 +1,25 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/** Request body for updating a deployment capability. */
+export interface UpdateDeploymentCapabilityRequest {
+    /** The capability name. */
+    name: string;
+    /** The capability value. */
+    value: string;
+}
+/** Information about a deployment capability. */
+export interface DeploymentCapabilityInfo {
+    /** The capability name. */
+    name?: string;
+    /** The capability value. */
+    value?: string;
+}
+/** Response containing deployment capabilities. */
+export interface GetDeploymentCapabilitiesResponse {
+    /** List of deployment capabilities. */
+    capabilities?: DeploymentCapabilityInfo[];
+    [key: string]: unknown;
+}

package/dist/types/types/deployment_details.d.ts

@@ -0,0 +1,54 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/** Query parameters for `admin/rainmaker_deployment_details`. */
+export interface GetDeploymentDetailsParams {
+    /** When true, response includes expanded `pre_requisite_details`. */
+    pre_requisite?: boolean;
+    /** Used by some admin flows when querying pool-related deployment data. */
+    email_mobile_userpool?: boolean;
+}
+/** Single stack row under `pre_requisite_details.stack_deployment_details`. */
+export interface RainmakerStackDeploymentDetail {
+    stack_name: string;
+    created_time_stamp: string;
+    last_updated_time_stamp: string;
+    /** Present when the stack reports a semver (e.g. addons / core stacks). */
+    version?: string;
+}
+/** SNS limits block under `pre_requisite_details`. */
+export interface RainmakerSnsConfiguration {
+    sns_monthly_spending_limit?: string;
+    is_sns_in_production?: boolean;
+}
+/** Nested object returned when `pre_requisite=true` is passed. */
+export interface RainmakerPreRequisiteDetails {
+    is_ses_in_production?: boolean;
+    is_super_admin_ses_verified?: boolean;
+    is_current_user_ses_verified?: boolean;
+    stack_deployment_details?: RainmakerStackDeploymentDetail[];
+    sns_configuration?: RainmakerSnsConfiguration;
+}
+/** Response body for `GET admin/rainmaker_deployment_details` (snake_case per API). */
+export interface GetDeploymentDetailsResponse {
+    base_url?: string;
+    http_base_url?: string;
+    region?: string;
+    account_id?: string;
+    build_info?: string;
+    mqtt_endpoint?: string;
+    mqtt_credentials_endpoint?: string;
+    user_pool_id?: string;
+    app_client_id?: string;
+    oauth_issuer?: string;
+    oauth_url?: string;
+    pre_requisite_details?: RainmakerPreRequisiteDetails;
+    oauth_deployment?: boolean;
+    super_admin_user_name?: string;
+    dashboard_url?: string;
+    deployment_type?: string;
+}
+/** Alias for consumer apps that prefer the product name over the RPC-style type. */
+export type RainmakerDeploymentDetails = GetDeploymentDetailsResponse;