@espressif/rainmaker-admin-sdk 1.3.1 → 1.4.0

package/CHANGELOG.md

@@ -3,6 +3,36 @@
 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.4.0] - 2026-10-07
+
+Minor release that adds OAuth 2.0 authorization-code login, so dashboards can
+complete social sign-in that uses `response_type=code` (WeChat on China
+deployments) through the SDK instead of calling `/token` themselves. Existing
+methods keep their signatures; the two behaviour changes below are fixes.
+
+### Added
+
+- `ESPRMAuth.loginWithAuthorizationCode({ code, redirectUri, clientId })`
+  completes an OAuth 2.0 authorization-code login (`response_type=code`, used
+  by WeChat sign-in on China deployments). It sends a form-encoded
+  `POST {baseUrl}/token` and stores the returned tokens like `login()`. When
+  no refresh token is issued, an empty one is stored.
+- `ESPRMRequestConfig.formData` sends a request body as
+  `application/x-www-form-urlencoded`.
+- `ESPRMAPIManager.getRootUrl()` returns the configured `baseUrl` without the
+  API version segment.
+- Types `AuthorizationCodeLoginParams`, `AuthorizationCodeTokenRequest` and
+  `OAuthTokenResponse`, and validation codes `MISSING_AUTHORIZATION_CODE`,
+  `MISSING_REDIRECT_URI` and `MISSING_OAUTH_CLIENT_ID`.
+
+### Changed
+
+- `ESPAPIError` now reads RFC 6749 error bodies too. `errorCode` falls back to
+  `error`, and `description` falls back to `error_description`, when the
+  RainMaker `error_code` / `description` fields are absent.
+- A trailing slash on `baseUrl` is now removed before the version segment is
+  appended. Before, it produced a double slash such as `https://host//v1`.
+
 ## [1.3.1] - 2026-10-07
 
 Patch release that corrects the OTA job list types in `ESPRMAdminOTAJob.getJob`

package/dist/cjs/entries/ESPRMAuth.cjs

@@ -6,6 +6,7 @@
 'use strict';
 
 require('../methods/ESPRMAuth/Login.cjs');
+require('../methods/ESPRMAuth/LoginWithAuthorizationCode.cjs');
 require('../methods/ESPRMAuth/Logout.cjs');
 require('../methods/ESPRMAuth/ForgotPassword.cjs');
 require('../methods/ESPRMAuth/ChangePassword.cjs');

package/dist/cjs/entries/ESPRMBase.cjs

@@ -6,6 +6,7 @@
 'use strict';
 
 require('../methods/ESPRMAuth/Login.cjs');
+require('../methods/ESPRMAuth/LoginWithAuthorizationCode.cjs');
 require('../methods/ESPRMAuth/Logout.cjs');
 require('../methods/ESPRMAuth/ForgotPassword.cjs');
 require('../methods/ESPRMAuth/ChangePassword.cjs');

package/dist/cjs/index.cjs

@@ -58,6 +58,7 @@ var ESPRMAdminMatter = require('./ESPRMAdminMatter.cjs');
 var ESPRMAdminNodeParams = require('./ESPRMAdminNodeParams.cjs');
 var ESPRMClaim = require('./ESPRMClaim.cjs');
 require('./methods/ESPRMAuth/Login.cjs');
+require('./methods/ESPRMAuth/LoginWithAuthorizationCode.cjs');
 require('./methods/ESPRMAuth/Logout.cjs');
 require('./methods/ESPRMAuth/ForgotPassword.cjs');
 require('./methods/ESPRMAuth/ChangePassword.cjs');

package/dist/cjs/methods/ESPRMAuth/LoginWithAuthorizationCode.cjs

@@ -0,0 +1,54 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+'use strict';
+
+var ESPRMAuth = require('../../ESPRMAuth.cjs');
+var ESPRMUser = require('../../ESPRMUser.cjs');
+var ESPRMAPIManager = require('../../services/ESPRMAPIManager.cjs');
+var constants = require('../../utils/constants.cjs');
+var ESPValidationError = require('../../utils/error/ESPValidationError.cjs');
+var parser = require('../../utils/error/parser.cjs');
+
+function validateParams({ code, redirectUri, clientId, }) {
+    if (!code) {
+        throw new ESPValidationError.ESPValidationError(constants.ValidationErrorCodes.MISSING_AUTHORIZATION_CODE);
+    }
+    if (!redirectUri) {
+        throw new ESPValidationError.ESPValidationError(constants.ValidationErrorCodes.MISSING_REDIRECT_URI);
+    }
+    if (!clientId) {
+        throw new ESPValidationError.ESPValidationError(constants.ValidationErrorCodes.MISSING_OAUTH_CLIENT_ID);
+    }
+}
+ESPRMAuth.ESPRMAuth.prototype.loginWithAuthorizationCode = async function (params) {
+    validateParams(params);
+    const tokenRequest = {
+        grant_type: "authorization_code",
+        code: params.code,
+        redirect_uri: params.redirectUri,
+        client_id: params.clientId,
+    };
+    const requestConfig = {
+        baseURL: ESPRMAPIManager.ESPRMAPIManager.getRootUrl(),
+        url: constants.APIEndpoints.OAUTH_TOKEN,
+        method: constants.HTTPMethods.POST,
+        formData: tokenRequest,
+    };
+    const responseData = await ESPRMAPIManager.ESPRMAPIManager.request(requestConfig);
+    if (!responseData?.access_token || !responseData?.id_token) {
+        throw parser.parseAPIErrorResponse({
+            status: "failure",
+            description: "Token response is missing access_token or id_token",
+        }, 200);
+    }
+    const userTokens = {
+        accessToken: responseData.access_token,
+        idToken: responseData.id_token,
+        refreshToken: responseData.refresh_token ?? "",
+    };
+    await ESPRMUser.ESPRMUser.storeTokens(userTokens);
+    return new ESPRMUser.ESPRMUser(userTokens);
+};

package/dist/cjs/services/ESPRMAPIManager.cjs

@@ -20,11 +20,13 @@ var common = require('../types/common.cjs');
 class ESPRMAPIManager {
     static #instance;
     #baseUrl;
+    #rootUrl;
     #timeoutMs;
     #claimingBaseUrl;
     constructor(config) {
         const { baseUrl, version, timeoutMs, claimingBaseUrl } = config;
-        this.#baseUrl = `${baseUrl}/${version}`;
+        this.#rootUrl = baseUrl.replace(/\/+$/, "");
+        this.#baseUrl = `${this.#rootUrl}/${version}`;
         this.#timeoutMs = timeoutMs ?? constants.DEFAULT_REQUEST_TIMEOUT_MS;
         this.#claimingBaseUrl = claimingBaseUrl?.replace(/\/+$/, "");
     }
@@ -37,6 +39,13 @@ class ESPRMAPIManager {
         }
         return ESPRMAPIManager.#instance;
     }
+    /**
+     * Configured `baseUrl` without the API version segment, for the endpoints
+     * served outside `/{version}`, such as the OAuth `/token` endpoint.
+     */
+    static getRootUrl() {
+        return ESPRMAPIManager.#getInstance().#rootUrl;
+    }
     /**
      * Base URL of the claiming service set through `claimingBaseUrl`.
      *
@@ -82,6 +91,21 @@ class ESPRMAPIManager {
             throw error;
         }
     }
+    static #serializeBody(requestConfig) {
+        if (requestConfig.formData) {
+            return {
+                contentType: "application/x-www-form-urlencoded",
+                body: new URLSearchParams(requestConfig.formData).toString(),
+            };
+        }
+        if (requestConfig.data) {
+            return {
+                contentType: "application/json",
+                body: JSON.stringify(requestConfig.data),
+            };
+        }
+        return {};
+    }
     /**
      * Send an unauthenticated request. Non-2xx responses and network/timeout
      * failures reject with an {@link ESPAPIError}.
@@ -102,18 +126,19 @@ class ESPRMAPIManager {
                 requestUrl += `?${new URLSearchParams(queryEntries).toString()}`;
             }
         }
+        const { contentType, body } = ESPRMAPIManager.#serializeBody(requestConfig);
         const fetchOptions = {
             method: requestConfig.method,
             // The API never redirects. Following one would re-send the body (login
             // password, refresh token) to whatever host the redirect names.
             redirect: "error",
             headers: {
-                ...(requestConfig.data ? { "Content-Type": "application/json" } : {}),
+                ...(contentType ? { "Content-Type": contentType } : {}),
                 ...requestConfig.headers,
             },
         };
-        if (requestConfig.data) {
-            fetchOptions.body = JSON.stringify(requestConfig.data);
+        if (body !== undefined) {
+            fetchOptions.body = body;
         }
         const timeoutMs = requestConfig.timeoutMs ?? instance.#timeoutMs;
         let timer;

package/dist/cjs/utils/constants.cjs

@@ -17,6 +17,7 @@ const APIEndpoints = {
     LOGIN: "login2",
     PASSWORD: "password2",
     LOGOUT: "logout2",
+    OAUTH_TOKEN: "token",
     ADMIN_USER: "admin/user2",
     ADMIN_USER_SUMMARY: "admin/user2/summary",
     ADMIN_NODES: "admin/nodes",
@@ -115,6 +116,9 @@ const ValidationErrorCodes = {
     MISSING_LOGIN_PASSWORD: "MISSING_LOGIN_PASSWORD",
     MISSING_USERNAME: "MISSING_USERNAME",
     MISSING_VERIFICATION_CODE: "MISSING_VERIFICATION_CODE",
+    MISSING_AUTHORIZATION_CODE: "MISSING_AUTHORIZATION_CODE",
+    MISSING_REDIRECT_URI: "MISSING_REDIRECT_URI",
+    MISSING_OAUTH_CLIENT_ID: "MISSING_OAUTH_CLIENT_ID",
 };
 const StorageAdapterErrorCodes = {
     UNSUPPORTED_DEFAULT_STORAGE_ADAPTER_API: "UNSUPPORTED_DEFAULT_STORAGE_ADAPTER_API",

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

@@ -16,6 +16,9 @@ const validationErrorMessages = {
     MISSING_LOGIN_PASSWORD: "Validation Error: Password is required.",
     MISSING_USERNAME: "Validation Error: Username is required.",
     MISSING_VERIFICATION_CODE: "Validation Error: Verification code is required.",
+    MISSING_AUTHORIZATION_CODE: "Validation Error: Authorization code is required.",
+    MISSING_REDIRECT_URI: "Validation Error: Redirect URI is required.",
+    MISSING_OAUTH_CLIENT_ID: "Validation Error: OAuth client ID is required.",
 };
 const storageAdapterErrorMessages = {
     UNSUPPORTED_DEFAULT_STORAGE_ADAPTER_API: "ESPStorageAdapterError: It seems like your environment doesn't support window.localstorage, you can define your own storage adapter while configuring the ESPRMBase instance. Please refer docs for more information.",

package/dist/cjs/utils/error/parser.cjs

@@ -11,8 +11,9 @@ const parseAPIErrorResponse = (error, statusCode) => {
     let description = "An error has occurred";
     if (error) {
         status = error.status ?? "";
-        errorCode = error.error_code ?? "";
-        description = error.description ?? "An error has occurred";
+        errorCode = error.error_code ?? error.error ?? "";
+        description =
+            error.description ?? error.error_description ?? "An error has occurred";
     }
     else {
         throw error;

package/dist/esm/entries/ESPRMAuth.js

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import '../methods/ESPRMAuth/Login.js';
+import '../methods/ESPRMAuth/LoginWithAuthorizationCode.js';
 import '../methods/ESPRMAuth/Logout.js';
 import '../methods/ESPRMAuth/ForgotPassword.js';
 import '../methods/ESPRMAuth/ChangePassword.js';

package/dist/esm/entries/ESPRMBase.js

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import '../methods/ESPRMAuth/Login.js';
+import '../methods/ESPRMAuth/LoginWithAuthorizationCode.js';
 import '../methods/ESPRMAuth/Logout.js';
 import '../methods/ESPRMAuth/ForgotPassword.js';
 import '../methods/ESPRMAuth/ChangePassword.js';

package/dist/esm/index.js

@@ -56,6 +56,7 @@ export { ESPRMAdminMatter } from './ESPRMAdminMatter.js';
 export { ESPRMAdminNodeParams } from './ESPRMAdminNodeParams.js';
 export { ESPRMClaim } from './ESPRMClaim.js';
 import './methods/ESPRMAuth/Login.js';
+import './methods/ESPRMAuth/LoginWithAuthorizationCode.js';
 import './methods/ESPRMAuth/Logout.js';
 import './methods/ESPRMAuth/ForgotPassword.js';
 import './methods/ESPRMAuth/ChangePassword.js';

package/dist/esm/methods/ESPRMAuth/LoginWithAuthorizationCode.js

@@ -0,0 +1,52 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ESPRMAuth } from '../../ESPRMAuth.js';
+import { ESPRMUser } from '../../ESPRMUser.js';
+import { ESPRMAPIManager } from '../../services/ESPRMAPIManager.js';
+import { HTTPMethods, APIEndpoints, ValidationErrorCodes } from '../../utils/constants.js';
+import { ESPValidationError } from '../../utils/error/ESPValidationError.js';
+import { parseAPIErrorResponse } from '../../utils/error/parser.js';
+
+function validateParams({ code, redirectUri, clientId, }) {
+    if (!code) {
+        throw new ESPValidationError(ValidationErrorCodes.MISSING_AUTHORIZATION_CODE);
+    }
+    if (!redirectUri) {
+        throw new ESPValidationError(ValidationErrorCodes.MISSING_REDIRECT_URI);
+    }
+    if (!clientId) {
+        throw new ESPValidationError(ValidationErrorCodes.MISSING_OAUTH_CLIENT_ID);
+    }
+}
+ESPRMAuth.prototype.loginWithAuthorizationCode = async function (params) {
+    validateParams(params);
+    const tokenRequest = {
+        grant_type: "authorization_code",
+        code: params.code,
+        redirect_uri: params.redirectUri,
+        client_id: params.clientId,
+    };
+    const requestConfig = {
+        baseURL: ESPRMAPIManager.getRootUrl(),
+        url: APIEndpoints.OAUTH_TOKEN,
+        method: HTTPMethods.POST,
+        formData: tokenRequest,
+    };
+    const responseData = await ESPRMAPIManager.request(requestConfig);
+    if (!responseData?.access_token || !responseData?.id_token) {
+        throw parseAPIErrorResponse({
+            status: "failure",
+            description: "Token response is missing access_token or id_token",
+        }, 200);
+    }
+    const userTokens = {
+        accessToken: responseData.access_token,
+        idToken: responseData.id_token,
+        refreshToken: responseData.refresh_token ?? "",
+    };
+    await ESPRMUser.storeTokens(userTokens);
+    return new ESPRMUser(userTokens);
+};

package/dist/esm/services/ESPRMAPIManager.js

@@ -18,11 +18,13 @@ import { PropertyCheckMode } from '../types/common.js';
 class ESPRMAPIManager {
     static #instance;
     #baseUrl;
+    #rootUrl;
     #timeoutMs;
     #claimingBaseUrl;
     constructor(config) {
         const { baseUrl, version, timeoutMs, claimingBaseUrl } = config;
-        this.#baseUrl = `${baseUrl}/${version}`;
+        this.#rootUrl = baseUrl.replace(/\/+$/, "");
+        this.#baseUrl = `${this.#rootUrl}/${version}`;
         this.#timeoutMs = timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
         this.#claimingBaseUrl = claimingBaseUrl?.replace(/\/+$/, "");
     }
@@ -35,6 +37,13 @@ class ESPRMAPIManager {
         }
         return ESPRMAPIManager.#instance;
     }
+    /**
+     * Configured `baseUrl` without the API version segment, for the endpoints
+     * served outside `/{version}`, such as the OAuth `/token` endpoint.
+     */
+    static getRootUrl() {
+        return ESPRMAPIManager.#getInstance().#rootUrl;
+    }
     /**
      * Base URL of the claiming service set through `claimingBaseUrl`.
      *
@@ -80,6 +89,21 @@ class ESPRMAPIManager {
             throw error;
         }
     }
+    static #serializeBody(requestConfig) {
+        if (requestConfig.formData) {
+            return {
+                contentType: "application/x-www-form-urlencoded",
+                body: new URLSearchParams(requestConfig.formData).toString(),
+            };
+        }
+        if (requestConfig.data) {
+            return {
+                contentType: "application/json",
+                body: JSON.stringify(requestConfig.data),
+            };
+        }
+        return {};
+    }
     /**
      * Send an unauthenticated request. Non-2xx responses and network/timeout
      * failures reject with an {@link ESPAPIError}.
@@ -100,18 +124,19 @@ class ESPRMAPIManager {
                 requestUrl += `?${new URLSearchParams(queryEntries).toString()}`;
             }
         }
+        const { contentType, body } = ESPRMAPIManager.#serializeBody(requestConfig);
         const fetchOptions = {
             method: requestConfig.method,
             // The API never redirects. Following one would re-send the body (login
             // password, refresh token) to whatever host the redirect names.
             redirect: "error",
             headers: {
-                ...(requestConfig.data ? { "Content-Type": "application/json" } : {}),
+                ...(contentType ? { "Content-Type": contentType } : {}),
                 ...requestConfig.headers,
             },
         };
-        if (requestConfig.data) {
-            fetchOptions.body = JSON.stringify(requestConfig.data);
+        if (body !== undefined) {
+            fetchOptions.body = body;
         }
         const timeoutMs = requestConfig.timeoutMs ?? instance.#timeoutMs;
         let timer;

package/dist/esm/utils/constants.js

@@ -15,6 +15,7 @@ const APIEndpoints = {
     LOGIN: "login2",
     PASSWORD: "password2",
     LOGOUT: "logout2",
+    OAUTH_TOKEN: "token",
     ADMIN_USER: "admin/user2",
     ADMIN_USER_SUMMARY: "admin/user2/summary",
     ADMIN_NODES: "admin/nodes",
@@ -113,6 +114,9 @@ const ValidationErrorCodes = {
     MISSING_LOGIN_PASSWORD: "MISSING_LOGIN_PASSWORD",
     MISSING_USERNAME: "MISSING_USERNAME",
     MISSING_VERIFICATION_CODE: "MISSING_VERIFICATION_CODE",
+    MISSING_AUTHORIZATION_CODE: "MISSING_AUTHORIZATION_CODE",
+    MISSING_REDIRECT_URI: "MISSING_REDIRECT_URI",
+    MISSING_OAUTH_CLIENT_ID: "MISSING_OAUTH_CLIENT_ID",
 };
 const StorageAdapterErrorCodes = {
     UNSUPPORTED_DEFAULT_STORAGE_ADAPTER_API: "UNSUPPORTED_DEFAULT_STORAGE_ADAPTER_API",

package/dist/esm/utils/error/errorMessages.js

@@ -14,6 +14,9 @@ const validationErrorMessages = {
     MISSING_LOGIN_PASSWORD: "Validation Error: Password is required.",
     MISSING_USERNAME: "Validation Error: Username is required.",
     MISSING_VERIFICATION_CODE: "Validation Error: Verification code is required.",
+    MISSING_AUTHORIZATION_CODE: "Validation Error: Authorization code is required.",
+    MISSING_REDIRECT_URI: "Validation Error: Redirect URI is required.",
+    MISSING_OAUTH_CLIENT_ID: "Validation Error: OAuth client ID is required.",
 };
 const storageAdapterErrorMessages = {
     UNSUPPORTED_DEFAULT_STORAGE_ADAPTER_API: "ESPStorageAdapterError: It seems like your environment doesn't support window.localstorage, you can define your own storage adapter while configuring the ESPRMBase instance. Please refer docs for more information.",

package/dist/esm/utils/error/parser.js

@@ -9,8 +9,9 @@ const parseAPIErrorResponse = (error, statusCode) => {
     let description = "An error has occurred";
     if (error) {
         status = error.status ?? "";
-        errorCode = error.error_code ?? "";
-        description = error.description ?? "An error has occurred";
+        errorCode = error.error_code ?? error.error ?? "";
+        description =
+            error.description ?? error.error_description ?? "An error has occurred";
     }
     else {
         throw error;

package/dist/types/methods/ESPRMAuth/LoginWithAuthorizationCode.d.ts

@@ -0,0 +1,40 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ESPRMUser } from "../../ESPRMUser.js";
+import { AuthorizationCodeLoginParams } from "../../types/auth.js";
+declare module "../../ESPRMAuth.js" {
+    interface ESPRMAuth {
+        /**
+         * Complete an OAuth 2.0 authorization-code login (`response_type=code`)
+         * by exchanging the code returned on the redirect URI for tokens.
+         *
+         * Sends `POST {baseUrl}/token` (outside the API version path) as
+         * `application/x-www-form-urlencoded`, without an `Authorization` header.
+         * Stores the returned tokens like {@link ESPRMAuth.login}. When the server
+         * issues no refresh token, an empty one is stored, so the session ends
+         * when the access token expires.
+         *
+         * @param params - Authorization code plus the `redirect_uri` and
+         * `client_id` sent in the authorize request
+         * @returns A new {@link ESPRMUser} instance with active session tokens
+         * @throws ESPValidationError when `code`, `redirectUri` or `clientId` is empty
+         * @throws ESPAPIError on a non-2xx response, where `errorCode` carries the
+         * RFC 6749 `error` value (for example `invalid_grant`), or when a 2xx
+         * response lacks `access_token` or `id_token`
+         *
+         * @example
+         * ```typescript
+         * const code = new URLSearchParams(window.location.search).get("code");
+         * const user = await ESPRMBase.getAuthInstance().loginWithAuthorizationCode({
+         *   code,
+         *   redirectUri: "https://dashboard.example.com/socialauth",
+         *   clientId: "<OAUTH_CLIENT_ID>",
+         * });
+         * ```
+         */
+        loginWithAuthorizationCode(params: AuthorizationCodeLoginParams): Promise<ESPRMUser>;
+    }
+}

package/dist/types/methods/ESPRMAuth/index.d.ts

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import "./Login.js";
+import "./LoginWithAuthorizationCode.js";
 import "./Logout.js";
 import "./ForgotPassword.js";
 import "./ChangePassword.js";

package/dist/types/services/ESPRMAPIManager.d.ts

@@ -13,6 +13,11 @@ export declare class ESPRMAPIManager {
     #private;
     private constructor();
     static initialize(config: ESPRMAPIManagerConfig): void;
+    /**
+     * Configured `baseUrl` without the API version segment, for the endpoints
+     * served outside `/{version}`, such as the OAuth `/token` endpoint.
+     */
+    static getRootUrl(): string;
     /**
      * Base URL of the claiming service set through `claimingBaseUrl`.
      *

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

@@ -84,3 +84,33 @@ export interface GetUserInfoResponse {
     locale?: string;
     tags?: string[];
 }
+/** Parameters for {@link ESPRMAuth.loginWithAuthorizationCode}. */
+export interface AuthorizationCodeLoginParams {
+    /** Authorization code from the `code` query parameter of the OAuth callback. */
+    code: string;
+    /** Redirect URI sent in the authorize request. Must match it exactly. */
+    redirectUri: string;
+    /** OAuth client ID sent in the authorize request. */
+    clientId: string;
+}
+/**
+ * Form body for `POST /token` with `grant_type=authorization_code`.
+ * A type alias, not an interface, so it is assignable to the
+ * `Record<string, string>` that `formData` takes.
+ */
+export type AuthorizationCodeTokenRequest = {
+    grant_type: "authorization_code";
+    code: string;
+    redirect_uri: string;
+    client_id: string;
+};
+/** Successful `POST /token` response (RFC 6749 section 5.1). */
+export interface OAuthTokenResponse {
+    access_token: string;
+    id_token: string;
+    /** Omitted or empty when the grant issues no refresh token. */
+    refresh_token?: string;
+    token_type?: string;
+    /** Access-token lifetime in seconds. */
+    expires_in?: number;
+}

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

@@ -45,6 +45,11 @@ export interface ESPRMRequestConfig {
     method: string;
     /** Request body data (will be JSON-stringified). */
     data?: Record<string, unknown> | object;
+    /**
+     * Request body sent as `application/x-www-form-urlencoded`, for the OAuth
+     * endpoints. Takes precedence over `data` when both are set.
+     */
+    formData?: Record<string, string>;
     /** URL query parameters. */
     params?: Record<string, string> | object;
     /** Additional HTTP headers. */

package/dist/types/utils/constants.d.ts

@@ -15,6 +15,7 @@ declare const APIEndpoints: {
     readonly LOGIN: "login2";
     readonly PASSWORD: "password2";
     readonly LOGOUT: "logout2";
+    readonly OAUTH_TOKEN: "token";
     readonly ADMIN_USER: "admin/user2";
     readonly ADMIN_USER_SUMMARY: "admin/user2/summary";
     readonly ADMIN_NODES: "admin/nodes";
@@ -113,6 +114,9 @@ declare const ValidationErrorCodes: {
     readonly MISSING_LOGIN_PASSWORD: "MISSING_LOGIN_PASSWORD";
     readonly MISSING_USERNAME: "MISSING_USERNAME";
     readonly MISSING_VERIFICATION_CODE: "MISSING_VERIFICATION_CODE";
+    readonly MISSING_AUTHORIZATION_CODE: "MISSING_AUTHORIZATION_CODE";
+    readonly MISSING_REDIRECT_URI: "MISSING_REDIRECT_URI";
+    readonly MISSING_OAUTH_CLIENT_ID: "MISSING_OAUTH_CLIENT_ID";
 };
 declare const StorageAdapterErrorCodes: {
     readonly UNSUPPORTED_DEFAULT_STORAGE_ADAPTER_API: "UNSUPPORTED_DEFAULT_STORAGE_ADAPTER_API";

package/dist/types/utils/error/errorMessages.d.ts

@@ -14,6 +14,9 @@ declare const validationErrorMessages: {
     MISSING_LOGIN_PASSWORD: string;
     MISSING_USERNAME: string;
     MISSING_VERIFICATION_CODE: string;
+    MISSING_AUTHORIZATION_CODE: string;
+    MISSING_REDIRECT_URI: string;
+    MISSING_OAUTH_CLIENT_ID: string;
 };
 declare const storageAdapterErrorMessages: {
     UNSUPPORTED_DEFAULT_STORAGE_ADAPTER_API: string;

package/dist/types/utils/error/parser.d.ts

@@ -8,6 +8,10 @@ interface RawAPIErrorBody {
     status?: string;
     error_code?: string;
     description?: string;
+    /** RFC 6749 error code, returned by the OAuth endpoints instead of `error_code`. */
+    error?: string;
+    /** RFC 6749 error text, returned by the OAuth endpoints instead of `description`. */
+    error_description?: string;
 }
 declare const parseAPIErrorResponse: (error: RawAPIErrorBody, statusCode: number) => ESPAPIError;
 export { parseAPIErrorResponse };

package/dist/types-cjs/methods/ESPRMAuth/LoginWithAuthorizationCode.d.cts

@@ -0,0 +1,40 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ESPRMUser } from "../../ESPRMUser.cjs";
+import { AuthorizationCodeLoginParams } from "../../types/auth.cjs";
+declare module "../../ESPRMAuth.cjs" {
+    interface ESPRMAuth {
+        /**
+         * Complete an OAuth 2.0 authorization-code login (`response_type=code`)
+         * by exchanging the code returned on the redirect URI for tokens.
+         *
+         * Sends `POST {baseUrl}/token` (outside the API version path) as
+         * `application/x-www-form-urlencoded`, without an `Authorization` header.
+         * Stores the returned tokens like {@link ESPRMAuth.login}. When the server
+         * issues no refresh token, an empty one is stored, so the session ends
+         * when the access token expires.
+         *
+         * @param params - Authorization code plus the `redirect_uri` and
+         * `client_id` sent in the authorize request
+         * @returns A new {@link ESPRMUser} instance with active session tokens
+         * @throws ESPValidationError when `code`, `redirectUri` or `clientId` is empty
+         * @throws ESPAPIError on a non-2xx response, where `errorCode` carries the
+         * RFC 6749 `error` value (for example `invalid_grant`), or when a 2xx
+         * response lacks `access_token` or `id_token`
+         *
+         * @example
+         * ```typescript
+         * const code = new URLSearchParams(window.location.search).get("code");
+         * const user = await ESPRMBase.getAuthInstance().loginWithAuthorizationCode({
+         *   code,
+         *   redirectUri: "https://dashboard.example.com/socialauth",
+         *   clientId: "<OAUTH_CLIENT_ID>",
+         * });
+         * ```
+         */
+        loginWithAuthorizationCode(params: AuthorizationCodeLoginParams): Promise<ESPRMUser>;
+    }
+}

package/dist/types-cjs/methods/ESPRMAuth/index.d.cts

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import "./Login.cjs";
+import "./LoginWithAuthorizationCode.cjs";
 import "./Logout.cjs";
 import "./ForgotPassword.cjs";
 import "./ChangePassword.cjs";

package/dist/types-cjs/services/ESPRMAPIManager.d.cts

@@ -13,6 +13,11 @@ export declare class ESPRMAPIManager {
     #private;
     private constructor();
     static initialize(config: ESPRMAPIManagerConfig): void;
+    /**
+     * Configured `baseUrl` without the API version segment, for the endpoints
+     * served outside `/{version}`, such as the OAuth `/token` endpoint.
+     */
+    static getRootUrl(): string;
     /**
      * Base URL of the claiming service set through `claimingBaseUrl`.
      *

package/dist/types-cjs/types/auth.d.cts

@@ -84,3 +84,33 @@ export interface GetUserInfoResponse {
     locale?: string;
     tags?: string[];
 }
+/** Parameters for {@link ESPRMAuth.loginWithAuthorizationCode}. */
+export interface AuthorizationCodeLoginParams {
+    /** Authorization code from the `code` query parameter of the OAuth callback. */
+    code: string;
+    /** Redirect URI sent in the authorize request. Must match it exactly. */
+    redirectUri: string;
+    /** OAuth client ID sent in the authorize request. */
+    clientId: string;
+}
+/**
+ * Form body for `POST /token` with `grant_type=authorization_code`.
+ * A type alias, not an interface, so it is assignable to the
+ * `Record<string, string>` that `formData` takes.
+ */
+export type AuthorizationCodeTokenRequest = {
+    grant_type: "authorization_code";
+    code: string;
+    redirect_uri: string;
+    client_id: string;
+};
+/** Successful `POST /token` response (RFC 6749 section 5.1). */
+export interface OAuthTokenResponse {
+    access_token: string;
+    id_token: string;
+    /** Omitted or empty when the grant issues no refresh token. */
+    refresh_token?: string;
+    token_type?: string;
+    /** Access-token lifetime in seconds. */
+    expires_in?: number;
+}

package/dist/types-cjs/types/config.d.cts

@@ -45,6 +45,11 @@ export interface ESPRMRequestConfig {
     method: string;
     /** Request body data (will be JSON-stringified). */
     data?: Record<string, unknown> | object;
+    /**
+     * Request body sent as `application/x-www-form-urlencoded`, for the OAuth
+     * endpoints. Takes precedence over `data` when both are set.
+     */
+    formData?: Record<string, string>;
     /** URL query parameters. */
     params?: Record<string, string> | object;
     /** Additional HTTP headers. */

package/dist/types-cjs/utils/constants.d.cts

@@ -15,6 +15,7 @@ declare const APIEndpoints: {
     readonly LOGIN: "login2";
     readonly PASSWORD: "password2";
     readonly LOGOUT: "logout2";
+    readonly OAUTH_TOKEN: "token";
     readonly ADMIN_USER: "admin/user2";
     readonly ADMIN_USER_SUMMARY: "admin/user2/summary";
     readonly ADMIN_NODES: "admin/nodes";
@@ -113,6 +114,9 @@ declare const ValidationErrorCodes: {
     readonly MISSING_LOGIN_PASSWORD: "MISSING_LOGIN_PASSWORD";
     readonly MISSING_USERNAME: "MISSING_USERNAME";
     readonly MISSING_VERIFICATION_CODE: "MISSING_VERIFICATION_CODE";
+    readonly MISSING_AUTHORIZATION_CODE: "MISSING_AUTHORIZATION_CODE";
+    readonly MISSING_REDIRECT_URI: "MISSING_REDIRECT_URI";
+    readonly MISSING_OAUTH_CLIENT_ID: "MISSING_OAUTH_CLIENT_ID";
 };
 declare const StorageAdapterErrorCodes: {
     readonly UNSUPPORTED_DEFAULT_STORAGE_ADAPTER_API: "UNSUPPORTED_DEFAULT_STORAGE_ADAPTER_API";

package/dist/types-cjs/utils/error/errorMessages.d.cts

@@ -14,6 +14,9 @@ declare const validationErrorMessages: {
     MISSING_LOGIN_PASSWORD: string;
     MISSING_USERNAME: string;
     MISSING_VERIFICATION_CODE: string;
+    MISSING_AUTHORIZATION_CODE: string;
+    MISSING_REDIRECT_URI: string;
+    MISSING_OAUTH_CLIENT_ID: string;
 };
 declare const storageAdapterErrorMessages: {
     UNSUPPORTED_DEFAULT_STORAGE_ADAPTER_API: string;

package/dist/types-cjs/utils/error/parser.d.cts

@@ -8,6 +8,10 @@ interface RawAPIErrorBody {
     status?: string;
     error_code?: string;
     description?: string;
+    /** RFC 6749 error code, returned by the OAuth endpoints instead of `error_code`. */
+    error?: string;
+    /** RFC 6749 error text, returned by the OAuth endpoints instead of `description`. */
+    error_description?: string;
 }
 declare const parseAPIErrorResponse: (error: RawAPIErrorBody, statusCode: number) => ESPAPIError;
 export { parseAPIErrorResponse };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@espressif/rainmaker-admin-sdk",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "Espressif's Rainmaker Admin SDK enables seamless integration of admin applications with the ESP Rainmaker ecosystem.",
   "license": "Apache-2.0",
   "author": "Espressif Systems (Shanghai) CO LTD",