@espressif/rainmaker-admin-sdk 1.2.0 → 1.3.1

package/CHANGELOG.md

@@ -3,6 +3,139 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html) and follows the [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format.
 
+## [1.3.1] - 2026-10-07
+
+Patch release that corrects the OTA job list types in `ESPRMAdminOTAJob.getJob`
+to match what the backend accepts and returns. No runtime behaviour changes:
+the SDK already forwarded every query parameter and returned the backend's
+response as-is. Only the types were wrong.
+
+### Added
+
+- `GetOTAJobParams` now declares the filters the backend accepts:
+  `ota_job_name` (case-sensitive "contains" search), `ota_image_id`,
+  `archived` and `all`. Callers no longer need a cast to search.
+- `GetOTAJobsResponse.otaJobs`, the key the backend actually returns the job
+  list under.
+- `GetOTAJobByIdParams` and a `getJob({ ota_job_id })` overload that returns
+  `OTAJobInfo`. The backend answers an ID lookup with the job itself, not a
+  list.
+
+### Deprecated
+
+- `GetOTAJobsResponse.ota_update_jobs` and `GetOTAJobsResponse.total`. The
+  backend has never returned either; read `otaJobs` instead. Both will be
+  removed in the next minor release.
+- `GetOTAJobParams.ota_job_id`. Pass `GetOTAJobByIdParams` to get the
+  correctly typed single-job response.
+
+## [1.3.0] - 2026-10-06
+
+Minor release that adds node deletion, node claiming through the standalone
+claiming service (new `ESPRMClaim` module) and a delete helper for common
+custom data. It also folds in the fixes prepared for 1.2.1, which was never
+published: corrected webhook integration, event filter and common custom data
+types, and a fix for `activateDeactivateNodes`, which could not have worked
+before.
+
+Some request and response types change shape to match the backend. In every
+case the old shape was never accepted or returned by the backend, so no
+working caller breaks at runtime, but code built on the old types will no
+longer type-check.
+
+### Added
+
+- **Node deletion** (`ESPRMAdminNode`)
+  - `deleteNode(nodeId)` → `DELETE admin/nodes?node_id=<id>&delete_node=true`.
+    Permanently deletes one node (certificates, IoT thing, data, user and
+    group mappings). Public deployments only; the backend rejects it on
+    customer deployments with error 105059.
+  - `MAX_NODE_ACTIVATION_BATCH_SIZE` constant (25), plus validation error
+    codes `MISSING_NODE_IDS` and `TOO_MANY_NODE_IDS`.
+  - `ActivateDeactivateNodesResponse`, `NodeActivationMultiStatusResponse`,
+    `NodeActivationSuccessResult` and `NodeActivationFailureResult` types.
+
+- **Node claiming** (`ESPRMClaim`, new module)
+  - `initiateClaim({ mac_addr, platform })` → `POST claim/initiate`, returns
+    `{ node_id }`.
+  - `verifyClaim({ csr, send_mqtt_host?, node_policies? }, { matter?, test? })`
+    → `POST claim/verify`, returns `{ certificate, mqtt_host?, mqtt_cred_host? }`.
+    `test` is only sent when `matter` is true.
+  - Both call the standalone claiming service (public deployments only), not
+    the RainMaker API. Configure it with the new optional
+    `ESPRMBase.configure({ claimingBaseUrl })`; calls without it throw
+    `ESPConfigError` `CLAIMING_NOT_CONFIGURED`. An invalid URL throws
+    `INVALID_CLAIMING_BASE_URL` at configure time.
+  - Validation error codes `MISSING_MAC_ADDRESS`, `MISSING_CLAIM_PLATFORM`
+    and `MISSING_CSR`.
+  - Only authenticated claiming is supported; the unauthenticated
+    challenge/response variant is not exposed.
+  - Available from the package root and the new
+    `@espressif/rainmaker-admin-sdk/ESPRMClaim` sub-path.
+
+- **Common custom data** (`ESPRMAdminCommonCustomData`)
+  - `deleteCommonCustomData({ name })`. The backend has no DELETE method for
+    this resource; it deletes an entry when `PUT admin/common_custom_data`
+    receives `value: null`. Callers no longer need to know that.
+  - `CommonCustomDataItem` (`{ name, value, perms? }`) and
+    `DeleteCommonCustomDataRequest` types.
+  - Validation error codes `MISSING_COMMON_CUSTOM_DATA_NAME` and
+    `MISSING_COMMON_CUSTOM_DATA_VALUE`.
+
+### Fixed
+
+- **Node activation** (`ESPRMAdminNode`) — **breaking**
+  - `activateDeactivateNodes` sent `node_id` and `activate` as a JSON body,
+    but `PUT admin/nodes` reads them from the query string only (the body is
+    parsed as tags), so every call failed with error 105018. They are now
+    sent as query parameters.
+  - `ActivateDeactivateNodesParams` is now `{ node_ids: string[]; activate }`
+    (was `{ node_id: string; activate }`), matching the backend's batch
+    support of up to 25 comma-separated IDs. The method throws
+    `ESPAPICallValidationError` for an empty list or more than 25 IDs.
+    The endpoint is supported on private (customer) deployments only.
+  - The return type is `ActivateDeactivateNodesResponse`: a single success,
+    or a 207 `{ responses }` list with per-node results when outcomes differ.
+    Since the old call never succeeded, no working caller breaks at runtime.
+
+- **Common custom data** (`ESPRMAdminCommonCustomData`)
+  - `GetCommonCustomDataResponse` is now `CommonCustomDataItem[]` instead of
+    a `{ [key: string]: unknown }` map. `GET admin/common_custom_data` has
+    always returned an array, including a single-element array when `name`
+    is given. Code that indexed the old map type will no longer type-check.
+  - `setCommonCustomData` now throws `ESPAPICallValidationError` when `name`
+    is empty or `value` is `null`/`undefined`. The backend treats a null or
+    missing value as a delete, and `JSON.stringify` drops `undefined`, so an
+    accidental `undefined` used to wipe the entry.
+  - Documented the PUT merge semantics on `SetCommonCustomDataRequest`:
+    object values are deep merged (omitted keys are kept, nested `null`
+    deletes a key); other value types replace the stored value.
+
+- **Webhook integrations** (`ESPRMAdminWebhook`)
+  - `GetWebhookIntegrationsResponse` now declares `integration_info_list`
+    (`WebhookIntegrationInfo[] | null`) instead of `webhooks_endpoints`.
+    `GET admin/webhook_integration` has always returned
+    `integration_info_list`, and returns `null` when no integrations are
+    configured. The backend never sent `webhooks_endpoints`, so no working
+    caller can break at runtime, but code that read that field will no
+    longer type-check.
+
+- **Event filters** (`ESPRMAdminEventFilter`)
+  - `UpdateEventFilterRequest.enabled_for_integrations` is now optional.
+    `PUT admin/event_filter` keeps the stored integration list when the
+    field is omitted, so callers can change only `enabled`. Existing
+    callers that pass the field are unaffected.
+  - Documented the update semantics: the list adds (`enabled: true`) or
+    removes (`enabled: false`) integrations rather than replacing the
+    stored list, and a non-empty list makes the backend derive `enabled`.
+    The call fails with error `113109` when the mapping does not exist; it
+    never creates one.
+
+### Security
+
+- `claimingBaseUrl` receives the user's access token on every `ESPRMClaim`
+  call. Set it only to a trusted Espressif claiming endpoint.
+
 ## [1.2.0] - 2026-09-25
 
 Minor release that adds typed access to node certificate registration, so

package/README.md

@@ -121,9 +121,10 @@ const adminNode = new ESPRMAdminNode();
 
 const nodes = await adminNode.getNodes({ num_records: "50" });
 await adminNode.activateDeactivateNodes({
-  node_id: "<NODE_ID>",
+  node_ids: ["<NODE_ID_1>", "<NODE_ID_2>"], // up to 25 per call
   activate: true,
 });
+await adminNode.deleteNode("<NODE_ID>"); // public deployments only
 ```
 
 ### OTA

package/dist/cjs/ESPRMBase.cjs

@@ -38,6 +38,7 @@ class ESPRMBase {
             baseUrl: config.baseUrl,
             version,
             timeoutMs: config.timeoutMs,
+            claimingBaseUrl: config.claimingBaseUrl,
         });
         ESPRMStorage.ESPRMStorage.initialize(config.customStorageAdapter);
     }

package/dist/cjs/ESPRMClaim.cjs

@@ -0,0 +1,16 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+'use strict';
+
+/**
+ * Shell class for the standalone ESP RainMaker claiming service.
+ * Requires `claimingBaseUrl` in {@link ESPRMBase.configure}.
+ * Methods are added via prototype augmentation in methods/ESPRMClaim/*.
+ */
+class ESPRMClaim {
+}
+
+exports.ESPRMClaim = ESPRMClaim;

package/dist/cjs/entries/ESPRMAdminCommonCustomData.cjs

@@ -7,6 +7,7 @@
 
 require('../methods/ESPRMAdminCommonCustomData/SetCommonCustomData.cjs');
 require('../methods/ESPRMAdminCommonCustomData/GetCommonCustomData.cjs');
+require('../methods/ESPRMAdminCommonCustomData/DeleteCommonCustomData.cjs');
 var ESPRMAdminCommonCustomData = require('../ESPRMAdminCommonCustomData.cjs');
 
 

package/dist/cjs/entries/ESPRMAdminNode.cjs

@@ -9,6 +9,7 @@ require('../methods/ESPRMAdminNode/GetNodes.cjs');
 require('../methods/ESPRMAdminNode/ActivateDeactivateNodes.cjs');
 require('../methods/ESPRMAdminNode/AttachNodeTags.cjs');
 require('../methods/ESPRMAdminNode/RemoveNodeTags.cjs');
+require('../methods/ESPRMAdminNode/DeleteNode.cjs');
 require('../methods/ESPRMAdminNode/GetNodeTags.cjs');
 require('../methods/ESPRMAdminNode/GetCommandRequests.cjs');
 require('../methods/ESPRMAdminNode/AddCommandRequest.cjs');

package/dist/cjs/entries/ESPRMClaim.cjs

@@ -0,0 +1,14 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+'use strict';
+
+require('../methods/ESPRMClaim/InitiateClaim.cjs');
+require('../methods/ESPRMClaim/VerifyClaim.cjs');
+var ESPRMClaim = require('../ESPRMClaim.cjs');
+
+
+
+exports.ESPRMClaim = ESPRMClaim.ESPRMClaim;

package/dist/cjs/index.cjs

@@ -56,6 +56,7 @@ var ESPRMAdminAPIStatistics = require('./ESPRMAdminAPIStatistics.cjs');
 var ESPRMAdminMQTTStatistics = require('./ESPRMAdminMQTTStatistics.cjs');
 var ESPRMAdminMatter = require('./ESPRMAdminMatter.cjs');
 var ESPRMAdminNodeParams = require('./ESPRMAdminNodeParams.cjs');
+var ESPRMClaim = require('./ESPRMClaim.cjs');
 require('./methods/ESPRMAuth/Login.cjs');
 require('./methods/ESPRMAuth/Logout.cjs');
 require('./methods/ESPRMAuth/ForgotPassword.cjs');
@@ -77,6 +78,7 @@ require('./methods/ESPRMAdminNode/GetNodes.cjs');
 require('./methods/ESPRMAdminNode/ActivateDeactivateNodes.cjs');
 require('./methods/ESPRMAdminNode/AttachNodeTags.cjs');
 require('./methods/ESPRMAdminNode/RemoveNodeTags.cjs');
+require('./methods/ESPRMAdminNode/DeleteNode.cjs');
 require('./methods/ESPRMAdminNode/GetNodeTags.cjs');
 require('./methods/ESPRMAdminNode/GetCommandRequests.cjs');
 require('./methods/ESPRMAdminNode/AddCommandRequest.cjs');
@@ -170,6 +172,7 @@ require('./methods/ESPRMAdminSuperAdmin/ChangeSuperAdmin.cjs');
 require('./methods/ESPRMAdminSenderEmail/ChangeSenderEmail.cjs');
 require('./methods/ESPRMAdminCommonCustomData/SetCommonCustomData.cjs');
 require('./methods/ESPRMAdminCommonCustomData/GetCommonCustomData.cjs');
+require('./methods/ESPRMAdminCommonCustomData/DeleteCommonCustomData.cjs');
 require('./methods/ESPRMAdminDeploymentSetting/GetDeploymentSettings.cjs');
 require('./methods/ESPRMAdminDeploymentSetting/UpdateDeploymentConfig.cjs');
 require('./methods/ESPRMAdminConfiguration/GetNotifications.cjs');
@@ -192,6 +195,8 @@ require('./methods/ESPRMAdminPassthrough/CreatePassthroughConfig.cjs');
 require('./methods/ESPRMAdminPassthrough/UpdatePassthroughConfig.cjs');
 require('./methods/ESPRMAdminNodeCertificateCA/UpdateNodeCACertificate.cjs');
 require('./methods/ESPRMAdminNodeCertificateCA/GetNodeCACertificate.cjs');
+require('./methods/ESPRMClaim/InitiateClaim.cjs');
+require('./methods/ESPRMClaim/VerifyClaim.cjs');
 require('./methods/ESPRMAdminWebhook/CreateWebhookIntegration.cjs');
 require('./methods/ESPRMAdminWebhook/UpdateWebhookIntegration.cjs');
 require('./methods/ESPRMAdminWebhook/GetWebhookIntegrations.cjs');
@@ -283,6 +288,7 @@ exports.ESPRMAdminAPIStatistics = ESPRMAdminAPIStatistics.ESPRMAdminAPIStatistic
 exports.ESPRMAdminMQTTStatistics = ESPRMAdminMQTTStatistics.ESPRMAdminMQTTStatistics;
 exports.ESPRMAdminMatter = ESPRMAdminMatter.ESPRMAdminMatter;
 exports.ESPRMAdminNodeParams = ESPRMAdminNodeParams.ESPRMAdminNodeParams;
+exports.ESPRMClaim = ESPRMClaim.ESPRMClaim;
 exports.APICallValidationErrorCodes = constants.APICallValidationErrorCodes;
 exports.APIEndpoints = constants.APIEndpoints;
 exports.APIErrorCodes = constants.APIErrorCodes;
@@ -293,6 +299,7 @@ exports.DEFAULT_REST_API_VERSION = constants.DEFAULT_REST_API_VERSION;
 exports.ErrorLabels = constants.ErrorLabels;
 exports.HTTPMethods = constants.HTTPMethods;
 exports.HTTPStatusCodes = constants.HTTPStatusCodes;
+exports.MAX_NODE_ACTIVATION_BATCH_SIZE = constants.MAX_NODE_ACTIVATION_BATCH_SIZE;
 exports.StorageAdapterErrorCodes = constants.StorageAdapterErrorCodes;
 exports.StorageKeys = constants.StorageKeys;
 exports.TOKEN_EXPIRY_MARGIN_SECONDS = constants.TOKEN_EXPIRY_MARGIN_SECONDS;

package/dist/cjs/methods/ESPRMAdminCommonCustomData/DeleteCommonCustomData.cjs

@@ -0,0 +1,24 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+'use strict';
+
+var ESPRMAdminCommonCustomData = require('../../ESPRMAdminCommonCustomData.cjs');
+var ESPRMAPIManager = require('../../services/ESPRMAPIManager.cjs');
+var constants = require('../../utils/constants.cjs');
+var ESPAPICallValidationError = require('../../utils/error/ESPAPICallValidationError.cjs');
+
+ESPRMAdminCommonCustomData.ESPRMAdminCommonCustomData.prototype.deleteCommonCustomData = async function (params) {
+    if (!params.name) {
+        throw new ESPAPICallValidationError.ESPAPICallValidationError(constants.APICallValidationErrorCodes.MISSING_COMMON_CUSTOM_DATA_NAME);
+    }
+    const requestConfig = {
+        url: constants.APIEndpoints.ADMIN_COMMON_CUSTOM_DATA,
+        method: constants.HTTPMethods.PUT,
+        data: { name: params.name, value: null },
+    };
+    const response = await ESPRMAPIManager.ESPRMAPIManager.authorizeRequest(requestConfig);
+    return response;
+};

package/dist/cjs/methods/ESPRMAdminCommonCustomData/SetCommonCustomData.cjs

@@ -8,8 +8,15 @@
 var ESPRMAdminCommonCustomData = require('../../ESPRMAdminCommonCustomData.cjs');
 var ESPRMAPIManager = require('../../services/ESPRMAPIManager.cjs');
 var constants = require('../../utils/constants.cjs');
+var ESPAPICallValidationError = require('../../utils/error/ESPAPICallValidationError.cjs');
 
 ESPRMAdminCommonCustomData.ESPRMAdminCommonCustomData.prototype.setCommonCustomData = async function (params) {
+    if (!params.name) {
+        throw new ESPAPICallValidationError.ESPAPICallValidationError(constants.APICallValidationErrorCodes.MISSING_COMMON_CUSTOM_DATA_NAME);
+    }
+    if (params.value === null || params.value === undefined) {
+        throw new ESPAPICallValidationError.ESPAPICallValidationError(constants.APICallValidationErrorCodes.MISSING_COMMON_CUSTOM_DATA_VALUE);
+    }
     const requestConfig = {
         url: constants.APIEndpoints.ADMIN_COMMON_CUSTOM_DATA,
         method: constants.HTTPMethods.PUT,

package/dist/cjs/methods/ESPRMAdminNode/ActivateDeactivateNodes.cjs

@@ -8,12 +8,22 @@
 var ESPRMAdminNode = require('../../ESPRMAdminNode.cjs');
 var ESPRMAPIManager = require('../../services/ESPRMAPIManager.cjs');
 var constants = require('../../utils/constants.cjs');
+var ESPAPICallValidationError = require('../../utils/error/ESPAPICallValidationError.cjs');
 
 ESPRMAdminNode.ESPRMAdminNode.prototype.activateDeactivateNodes = async function (params) {
+    const nodeIds = params.node_ids?.filter(Boolean) ?? [];
+    if (nodeIds.length === 0) {
+        throw new ESPAPICallValidationError.ESPAPICallValidationError(constants.APICallValidationErrorCodes.MISSING_NODE_IDS);
+    }
+    if (nodeIds.length > constants.MAX_NODE_ACTIVATION_BATCH_SIZE) {
+        throw new ESPAPICallValidationError.ESPAPICallValidationError(constants.APICallValidationErrorCodes.TOO_MANY_NODE_IDS);
+    }
+    // The backend reads both values from the query string only; a JSON body
+    // on this endpoint is parsed as node tags.
     const requestConfig = {
         url: constants.APIEndpoints.ADMIN_NODES,
         method: constants.HTTPMethods.PUT,
-        data: params,
+        params: { node_id: nodeIds.join(","), activate: params.activate },
     };
     const response = await ESPRMAPIManager.ESPRMAPIManager.authorizeRequest(requestConfig);
     return response;

package/dist/cjs/methods/ESPRMAdminNode/DeleteNode.cjs

@@ -0,0 +1,24 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+'use strict';
+
+var ESPRMAdminNode = require('../../ESPRMAdminNode.cjs');
+var ESPRMAPIManager = require('../../services/ESPRMAPIManager.cjs');
+var constants = require('../../utils/constants.cjs');
+var ESPAPICallValidationError = require('../../utils/error/ESPAPICallValidationError.cjs');
+
+ESPRMAdminNode.ESPRMAdminNode.prototype.deleteNode = async function (nodeId) {
+    if (!nodeId) {
+        throw new ESPAPICallValidationError.ESPAPICallValidationError(constants.APICallValidationErrorCodes.MISSING_NODE_ID);
+    }
+    const requestConfig = {
+        url: constants.APIEndpoints.ADMIN_NODES,
+        method: constants.HTTPMethods.DELETE,
+        params: { node_id: nodeId, delete_node: true },
+    };
+    const response = await ESPRMAPIManager.ESPRMAPIManager.authorizeRequest(requestConfig);
+    return response;
+};

package/dist/cjs/methods/ESPRMClaim/InitiateClaim.cjs

@@ -0,0 +1,28 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+'use strict';
+
+var ESPRMClaim = require('../../ESPRMClaim.cjs');
+var ESPRMAPIManager = require('../../services/ESPRMAPIManager.cjs');
+var constants = require('../../utils/constants.cjs');
+var ESPAPICallValidationError = require('../../utils/error/ESPAPICallValidationError.cjs');
+
+ESPRMClaim.ESPRMClaim.prototype.initiateClaim = async function (params) {
+    if (!params.mac_addr) {
+        throw new ESPAPICallValidationError.ESPAPICallValidationError(constants.APICallValidationErrorCodes.MISSING_MAC_ADDRESS);
+    }
+    if (!params.platform) {
+        throw new ESPAPICallValidationError.ESPAPICallValidationError(constants.APICallValidationErrorCodes.MISSING_CLAIM_PLATFORM);
+    }
+    const requestConfig = {
+        baseURL: ESPRMAPIManager.ESPRMAPIManager.getClaimingBaseUrl(),
+        url: constants.APIEndpoints.CLAIM_INITIATE,
+        method: constants.HTTPMethods.POST,
+        data: params,
+    };
+    const response = await ESPRMAPIManager.ESPRMAPIManager.authorizeRequest(requestConfig);
+    return response;
+};

package/dist/cjs/methods/ESPRMClaim/VerifyClaim.cjs

@@ -0,0 +1,28 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+'use strict';
+
+var ESPRMClaim = require('../../ESPRMClaim.cjs');
+var ESPRMAPIManager = require('../../services/ESPRMAPIManager.cjs');
+var constants = require('../../utils/constants.cjs');
+var ESPAPICallValidationError = require('../../utils/error/ESPAPICallValidationError.cjs');
+
+ESPRMClaim.ESPRMClaim.prototype.verifyClaim = async function (params, options = {}) {
+    if (!params.csr) {
+        throw new ESPAPICallValidationError.ESPAPICallValidationError(constants.APICallValidationErrorCodes.MISSING_CSR);
+    }
+    const matter = options.matter ?? false;
+    const requestConfig = {
+        baseURL: ESPRMAPIManager.ESPRMAPIManager.getClaimingBaseUrl(),
+        url: constants.APIEndpoints.CLAIM_VERIFY,
+        method: constants.HTTPMethods.POST,
+        data: params,
+        // The service ignores `test` unless `matter` is true.
+        params: matter ? { matter, test: options.test ?? false } : { matter },
+    };
+    const response = await ESPRMAPIManager.ESPRMAPIManager.authorizeRequest(requestConfig);
+    return response;
+};

package/dist/cjs/services/ESPRMAPIManager.cjs

@@ -21,10 +21,12 @@ class ESPRMAPIManager {
     static #instance;
     #baseUrl;
     #timeoutMs;
+    #claimingBaseUrl;
     constructor(config) {
-        const { baseUrl, version, timeoutMs } = config;
+        const { baseUrl, version, timeoutMs, claimingBaseUrl } = config;
         this.#baseUrl = `${baseUrl}/${version}`;
         this.#timeoutMs = timeoutMs ?? constants.DEFAULT_REQUEST_TIMEOUT_MS;
+        this.#claimingBaseUrl = claimingBaseUrl?.replace(/\/+$/, "");
     }
     static initialize(config) {
         ESPRMAPIManager.#instance = new ESPRMAPIManager(config);
@@ -35,6 +37,18 @@ class ESPRMAPIManager {
         }
         return ESPRMAPIManager.#instance;
     }
+    /**
+     * Base URL of the claiming service set through `claimingBaseUrl`.
+     *
+     * @throws ESPConfigError `CLAIMING_NOT_CONFIGURED` when it was not configured.
+     */
+    static getClaimingBaseUrl() {
+        const claimingBaseUrl = ESPRMAPIManager.#getInstance().#claimingBaseUrl;
+        if (!claimingBaseUrl) {
+            throw new ESPConfigError.ESPConfigError(constants.ConfigErrorCodes.CLAIMING_NOT_CONFIGURED);
+        }
+        return claimingBaseUrl;
+    }
     /**
      * Send a request with the current user's access token in the
      * `Authorization` header, refreshing the token first if it has expired.

package/dist/cjs/utils/constants.cjs

@@ -96,6 +96,8 @@ const APIEndpoints = {
     ADMIN_MATTER_BATCH: "admin/matter/batch",
     ADMIN_MATTER_BATCH_NODES: "admin/matter/batch/nodes",
     ADMIN_MAIL_FAILURES: "admin/mail_failures",
+    CLAIM_INITIATE: "claim/initiate",
+    CLAIM_VERIFY: "claim/verify",
 };
 const StorageKeys = {
     ACCESSTOKEN: "com.esprmbase.accessToken",
@@ -106,6 +108,8 @@ const ConfigErrorCodes = {
     SDK_NOT_CONFIGURED: "SDK_NOT_CONFIGURED",
     INVALID_CONFIG_OBJECT: "INVALID_CONFIG_OBJECT",
     INVALID_BASE_URL: "INVALID_BASE_URL",
+    INVALID_CLAIMING_BASE_URL: "INVALID_CLAIMING_BASE_URL",
+    CLAIMING_NOT_CONFIGURED: "CLAIMING_NOT_CONFIGURED",
 };
 const ValidationErrorCodes = {
     MISSING_LOGIN_PASSWORD: "MISSING_LOGIN_PASSWORD",
@@ -153,6 +157,13 @@ const APICallValidationErrorCodes = {
     MISSING_BATCH_ID: "MISSING_BATCH_ID",
     MISSING_CANCEL_COMMAND_SCOPE: "MISSING_CANCEL_COMMAND_SCOPE",
     CMD_ID_REQUIRES_NODE_ID: "CMD_ID_REQUIRES_NODE_ID",
+    MISSING_COMMON_CUSTOM_DATA_NAME: "MISSING_COMMON_CUSTOM_DATA_NAME",
+    MISSING_COMMON_CUSTOM_DATA_VALUE: "MISSING_COMMON_CUSTOM_DATA_VALUE",
+    MISSING_MAC_ADDRESS: "MISSING_MAC_ADDRESS",
+    MISSING_CLAIM_PLATFORM: "MISSING_CLAIM_PLATFORM",
+    MISSING_CSR: "MISSING_CSR",
+    MISSING_NODE_IDS: "MISSING_NODE_IDS",
+    TOO_MANY_NODE_IDS: "TOO_MANY_NODE_IDS",
 };
 const TokenErrorCodes = {
     MISSING_ACCESS_TOKEN: "MISSING_ACCESS_TOKEN",
@@ -178,6 +189,8 @@ const DEFAULT_REST_API_VERSION = "v1";
 const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
 /** Tokens expiring within this many seconds are refreshed proactively. */
 const TOKEN_EXPIRY_MARGIN_SECONDS = 30;
+/** Backend limit on node IDs per `PUT admin/nodes` activation request. */
+const MAX_NODE_ACTIVATION_BATCH_SIZE = 25;
 /** errorCode values the SDK itself sets on ESPAPIError for non-HTTP failures. */
 const APIErrorCodes = {
     REQUEST_TIMEOUT: "REQUEST_TIMEOUT",
@@ -194,6 +207,7 @@ exports.DEFAULT_REST_API_VERSION = DEFAULT_REST_API_VERSION;
 exports.ErrorLabels = ErrorLabels;
 exports.HTTPMethods = HTTPMethods;
 exports.HTTPStatusCodes = HTTPStatusCodes;
+exports.MAX_NODE_ACTIVATION_BATCH_SIZE = MAX_NODE_ACTIVATION_BATCH_SIZE;
 exports.StorageAdapterErrorCodes = StorageAdapterErrorCodes;
 exports.StorageKeys = StorageKeys;
 exports.TOKEN_EXPIRY_MARGIN_SECONDS = TOKEN_EXPIRY_MARGIN_SECONDS;

package/dist/cjs/utils/error/errorMessages.cjs

@@ -9,6 +9,8 @@ const configErrorMessages = {
     SDK_NOT_CONFIGURED: "ESPRMBase is not configured yet",
     INVALID_CONFIG_OBJECT: "Configuration Error: Config must be a non-null object.",
     INVALID_BASE_URL: "Configuration Error: BaseUrl must be a non-empty valid URL string.",
+    INVALID_CLAIMING_BASE_URL: "Configuration Error: claimingBaseUrl must be a non-empty valid URL string.",
+    CLAIMING_NOT_CONFIGURED: "Configuration Error: claimingBaseUrl is not configured. Pass it to ESPRMBase.configure to use ESPRMClaim.",
 };
 const validationErrorMessages = {
     MISSING_LOGIN_PASSWORD: "Validation Error: Password is required.",
@@ -20,6 +22,8 @@ const storageAdapterErrorMessages = {
 };
 const apiCallValidationErrorMessages = {
     MISSING_NODE_ID: "ESPAPICallValidationError: Node ID is required.",
+    MISSING_NODE_IDS: "ESPAPICallValidationError: At least one node ID is required.",
+    TOO_MANY_NODE_IDS: "ESPAPICallValidationError: Too many node IDs; at most 25 are allowed per request.",
     MISSING_OTA_IMAGE_ID: "ESPAPICallValidationError: OTA image ID is required.",
     MISSING_ARCHIVE_FLAG: "ESPAPICallValidationError: Archive flag is required and must be a boolean.",
     MISSING_OTA_JOB_ID: "ESPAPICallValidationError: OTA job ID is required.",
@@ -56,6 +60,11 @@ const apiCallValidationErrorMessages = {
     MISSING_BATCH_ID: "ESPAPICallValidationError: Batch ID is required.",
     MISSING_CANCEL_COMMAND_SCOPE: "ESPAPICallValidationError: Request ID or node ID is required.",
     CMD_ID_REQUIRES_NODE_ID: "ESPAPICallValidationError: Command ID can only be used together with a node ID.",
+    MISSING_COMMON_CUSTOM_DATA_NAME: "ESPAPICallValidationError: Common custom data name is required.",
+    MISSING_COMMON_CUSTOM_DATA_VALUE: "ESPAPICallValidationError: Common custom data value is required. Use deleteCommonCustomData to delete an entry.",
+    MISSING_MAC_ADDRESS: "ESPAPICallValidationError: MAC address is required (12 uppercase hex characters, no separators).",
+    MISSING_CLAIM_PLATFORM: "ESPAPICallValidationError: Claim platform is required.",
+    MISSING_CSR: "ESPAPICallValidationError: Certificate signing request (CSR) is required.",
 };
 const tokenErrorMessages = {
     MISSING_ACCESS_TOKEN: "ESPTokenError: Access token is missing. User needs to authenticate.",

package/dist/cjs/utils/validator/ConfigValidator.cjs

@@ -13,12 +13,21 @@ class ConfigValidator {
     static validateConfig(config) {
         ConfigValidator.validateConfigObject(config);
         ConfigValidator.validateBaseUrl(config.baseUrl);
+        ConfigValidator.validateClaimingBaseUrl(config.claimingBaseUrl);
     }
     static validateConfigObject(config) {
         if (!validators.isValidObject(config)) {
             throw new ESPConfigError.ESPConfigError(constants.ConfigErrorCodes.INVALID_CONFIG_OBJECT);
         }
     }
+    static validateClaimingBaseUrl(claimingBaseUrl) {
+        if (claimingBaseUrl === undefined) {
+            return;
+        }
+        if (!validators.isNonEmptyString(claimingBaseUrl) || !validators.isValidUrl(claimingBaseUrl)) {
+            throw new ESPConfigError.ESPConfigError(constants.ConfigErrorCodes.INVALID_CLAIMING_BASE_URL);
+        }
+    }
     static validateBaseUrl(baseUrl) {
         if (!validators.isNonEmptyString(baseUrl) || !validators.isValidUrl(baseUrl)) {
             throw new ESPConfigError.ESPConfigError(constants.ConfigErrorCodes.INVALID_BASE_URL);

package/dist/esm/ESPRMBase.js

@@ -36,6 +36,7 @@ class ESPRMBase {
             baseUrl: config.baseUrl,
             version,
             timeoutMs: config.timeoutMs,
+            claimingBaseUrl: config.claimingBaseUrl,
         });
         ESPRMStorage.initialize(config.customStorageAdapter);
     }

package/dist/esm/ESPRMClaim.js

@@ -0,0 +1,14 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Shell class for the standalone ESP RainMaker claiming service.
+ * Requires `claimingBaseUrl` in {@link ESPRMBase.configure}.
+ * Methods are added via prototype augmentation in methods/ESPRMClaim/*.
+ */
+class ESPRMClaim {
+}
+
+export { ESPRMClaim };

package/dist/esm/entries/ESPRMAdminCommonCustomData.js

@@ -5,4 +5,5 @@
  */
 import '../methods/ESPRMAdminCommonCustomData/SetCommonCustomData.js';
 import '../methods/ESPRMAdminCommonCustomData/GetCommonCustomData.js';
+import '../methods/ESPRMAdminCommonCustomData/DeleteCommonCustomData.js';
 export { ESPRMAdminCommonCustomData } from '../ESPRMAdminCommonCustomData.js';

package/dist/esm/entries/ESPRMAdminNode.js

@@ -7,6 +7,7 @@ import '../methods/ESPRMAdminNode/GetNodes.js';
 import '../methods/ESPRMAdminNode/ActivateDeactivateNodes.js';
 import '../methods/ESPRMAdminNode/AttachNodeTags.js';
 import '../methods/ESPRMAdminNode/RemoveNodeTags.js';
+import '../methods/ESPRMAdminNode/DeleteNode.js';
 import '../methods/ESPRMAdminNode/GetNodeTags.js';
 import '../methods/ESPRMAdminNode/GetCommandRequests.js';
 import '../methods/ESPRMAdminNode/AddCommandRequest.js';

package/dist/esm/entries/ESPRMClaim.js

@@ -0,0 +1,8 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import '../methods/ESPRMClaim/InitiateClaim.js';
+import '../methods/ESPRMClaim/VerifyClaim.js';
+export { ESPRMClaim } from '../ESPRMClaim.js';

package/dist/esm/index.js

@@ -54,6 +54,7 @@ export { ESPRMAdminAPIStatistics } from './ESPRMAdminAPIStatistics.js';
 export { ESPRMAdminMQTTStatistics } from './ESPRMAdminMQTTStatistics.js';
 export { ESPRMAdminMatter } from './ESPRMAdminMatter.js';
 export { ESPRMAdminNodeParams } from './ESPRMAdminNodeParams.js';
+export { ESPRMClaim } from './ESPRMClaim.js';
 import './methods/ESPRMAuth/Login.js';
 import './methods/ESPRMAuth/Logout.js';
 import './methods/ESPRMAuth/ForgotPassword.js';
@@ -75,6 +76,7 @@ import './methods/ESPRMAdminNode/GetNodes.js';
 import './methods/ESPRMAdminNode/ActivateDeactivateNodes.js';
 import './methods/ESPRMAdminNode/AttachNodeTags.js';
 import './methods/ESPRMAdminNode/RemoveNodeTags.js';
+import './methods/ESPRMAdminNode/DeleteNode.js';
 import './methods/ESPRMAdminNode/GetNodeTags.js';
 import './methods/ESPRMAdminNode/GetCommandRequests.js';
 import './methods/ESPRMAdminNode/AddCommandRequest.js';
@@ -168,6 +170,7 @@ import './methods/ESPRMAdminSuperAdmin/ChangeSuperAdmin.js';
 import './methods/ESPRMAdminSenderEmail/ChangeSenderEmail.js';
 import './methods/ESPRMAdminCommonCustomData/SetCommonCustomData.js';
 import './methods/ESPRMAdminCommonCustomData/GetCommonCustomData.js';
+import './methods/ESPRMAdminCommonCustomData/DeleteCommonCustomData.js';
 import './methods/ESPRMAdminDeploymentSetting/GetDeploymentSettings.js';
 import './methods/ESPRMAdminDeploymentSetting/UpdateDeploymentConfig.js';
 import './methods/ESPRMAdminConfiguration/GetNotifications.js';
@@ -190,6 +193,8 @@ import './methods/ESPRMAdminPassthrough/CreatePassthroughConfig.js';
 import './methods/ESPRMAdminPassthrough/UpdatePassthroughConfig.js';
 import './methods/ESPRMAdminNodeCertificateCA/UpdateNodeCACertificate.js';
 import './methods/ESPRMAdminNodeCertificateCA/GetNodeCACertificate.js';
+import './methods/ESPRMClaim/InitiateClaim.js';
+import './methods/ESPRMClaim/VerifyClaim.js';
 import './methods/ESPRMAdminWebhook/CreateWebhookIntegration.js';
 import './methods/ESPRMAdminWebhook/UpdateWebhookIntegration.js';
 import './methods/ESPRMAdminWebhook/GetWebhookIntegrations.js';
@@ -219,7 +224,7 @@ import './methods/ESPRMAdminMatter/GetMatterBatch.js';
 import './methods/ESPRMAdminMatter/GetMatterBatchNodes.js';
 import './methods/ESPRMAdminNodeParams/UpdateNodeParams.js';
 import './methods/ESPRMAdminNodeParams/GetNodeParams.js';
-export { APICallValidationErrorCodes, APIEndpoints, APIErrorCodes, AdditionalInfo, ConfigErrorCodes, DEFAULT_REQUEST_TIMEOUT_MS, DEFAULT_REST_API_VERSION, ErrorLabels, HTTPMethods, HTTPStatusCodes, StorageAdapterErrorCodes, StorageKeys, TOKEN_EXPIRY_MARGIN_SECONDS, TokenErrorCodes, ValidationErrorCodes } from './utils/constants.js';
+export { APICallValidationErrorCodes, APIEndpoints, APIErrorCodes, AdditionalInfo, ConfigErrorCodes, DEFAULT_REQUEST_TIMEOUT_MS, DEFAULT_REST_API_VERSION, ErrorLabels, HTTPMethods, HTTPStatusCodes, MAX_NODE_ACTIVATION_BATCH_SIZE, StorageAdapterErrorCodes, StorageKeys, TOKEN_EXPIRY_MARGIN_SECONDS, TokenErrorCodes, ValidationErrorCodes } from './utils/constants.js';
 export { isNonEmptyString, isValidObject, isValidUrl } from './utils/validator/validators.js';
 export { ESPBaseError } from './utils/error/ESPBaseError.js';
 export { ESPRMAPIManager } from './services/ESPRMAPIManager.js';