@djust-b2b/djust-front-sdk 1.15.0 → 1.16.0

package/lib/services/auth/index.js

@@ -1,8 +1,17 @@
 "use strict";
 /**
- * @packageDocumentation
+ * # Auth Service
  *
- * @document documents/auth.md
+ * This module provides all functionalities related to user authentication and authorization.
+ *
+ * ## Features:
+ * - Validate tokens
+ * - Refresh tokens
+ * - Reset user passwords
+ * - Manage user login and logout
+ * - Send password reset emails
+ *
+ * Each function is described with its input parameters, output responses, and example usages.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isTokenValid = isTokenValid;
@@ -14,28 +23,30 @@ exports.logout = logout;
 const parameters_validation_1 = require("../../helpers/parameters-validation");
 const fetch_instance_1 = require("../../settings/fetch-instance");
 /**
- * CART ENDPOINT
- */
-/**
- * ##R eturns true if the token is valid and not expired, false otherwise
- * ### APICODE(TOK-200)
- * @param {IsTokenValidParameters} params - The parameters for the function
- * #### token - `string` | <strong style={{ color: 'red' }}>required</strong>
- * The token to validate.
- *
- * @returns {Promise<boolean>} - A promise that resolves to a boolean indicating whether the token is valid or not
- *
- * @example
- * #### input
- * ```typescript
- * const isValidToken = await isTokenValid({
- *  token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
+ * 🔐 Validates if a token is still active and unexpired.
+ *
+ * This function checks whether the provided token is valid, ensuring it has not expired or been invalidated.
+ *
+ * 🛠 **Endpoint**: `GET /auth/is-token-valid [TOK-200]`
+ *
+ * | Parameter | Type     | Required | Description                         |
+ * |-----------|----------|----------|-------------------------------------|
+ * | `token`   | `string` | ✅       | The token to validate.              |
+ *
+ * 📤 **Returns**:
+ * A `Promise<boolean>` resolving to `true` if the token is valid and active, or `false` otherwise.
+ *
+ * 🛠 **Example usage**:
+ * ```ts
+ * const isValid = await isTokenValid({
+ *   token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  * });
+ * console.log(isValid); // true
  * ```
- * #### output
- * ```json
- * true
- * ```
+ *
+ * @param {IsTokenValidParameters} params - The parameters for validating the token.
+ * @throws {Error} If the required `token` parameter is missing.
+ * @returns {Promise<boolean>} A promise that resolves to a boolean indicating whether the token is valid.
  */
 async function isTokenValid({ token, }) {
     (0, parameters_validation_1.required)({ token });
@@ -49,32 +60,29 @@ async function isTokenValid({ token, }) {
     return response === null || response === void 0 ? void 0 : response.data;
 }
 /**
- * ## Ask for a new token from a refresh token
- * ### APICODE(AUTH-102)
- * @param {RefreshTokenParameters} params - The parameters for the function, including:
- * #### refreshToken - `string` | <strong style={{ color: 'red' }}>required</strong>
- * The refresh token to request a new access token (required)
- *
- * @returns {Promise<RefreshTokenResponse>} - A promise that resolves to the response containing the new token
- *
- * @example
- * #### input
- * ```typescript
- * const response = await refreshToken({ refreshToken: 'string' });
- * ```
- * #### output
- * ```json
- *   {
- *     "token": {
- *       "accessToken": "string",
- *       "expireAt": 0,
- *       "refreshToken": "string"
- *     },
- *     "user": {
- *       "id": "userID"
- *     }
- *   }
+ * 🔄 Requests a new access token using a refresh token.
+ *
+ * This function allows you to obtain a new access token by providing a valid refresh token.
+ *
+ * 🛠 **Endpoint**: `POST /auth/refresh-token [AUTH-102]`
+ *
+ * | Parameter       | Type     | Required | Description                                      |
+ * |-----------------|----------|----------|--------------------------------------------------|
+ * | `refreshToken`  | `string` | ✅       | The refresh token used to request a new access token. |
+ *
+ * 📤 **Returns**:
+ * A `Promise<RefreshTokenResponse>` containing the new access token, its expiry time, and a refreshed token.
+ *
+ * 🛠 **Example usage**:
+ * ```ts
+ * const response = await refreshToken({
+ *   refreshToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+ * });
  * ```
+ *
+ * @param {RefreshTokenParameters} params - The parameters for requesting a new token.
+ * @throws {Error} If the required `refreshToken` parameter is missing.
+ * @returns {Promise<RefreshTokenResponse>} A promise that resolves to the response containing the new token and user details.
  */
 async function refreshToken({ refreshToken, }) {
     (0, parameters_validation_1.required)({ refreshToken });
@@ -88,25 +96,31 @@ async function refreshToken({ refreshToken, }) {
     return data;
 }
 /**
- * ## Reset the password of a user
- * ### APICODE(PWD-102)
- * @param {ResetPasswordParameters} params - The parameters for the function
- * #### newPassword - `string` | <strong style={{ color: 'red' }}>required</strong>
- * The new password to set for the user.
- * #### resetPasswordToken - `string` | <strong style={{ color: 'red' }}>required</strong>
- * The token required to authenticate the password reset process.
- *
- * @returns {Promise<void>} - Resolves to a success message `"OK"` when the password is successfully reset
- *
- * @example
- * #### input
- * ```typescript
- *    await resetPassword({ newPassword: 'string', resetPasswordToken: 'string' });
- * ```
- * #### output
- * ```json
- *    "OK" (No output, resolves on success)
+ * 🔑 Resets the password of a user.
+ *
+ * This function allows a user to reset their password by providing a new password along with a valid reset token.
+ *
+ * 🛠 **Endpoint**: `POST /auth/reset-password [PWD-102]`
+ *
+ * | Parameter             | Type     | Required | Description                                                  |
+ * |-----------------------|----------|----------|--------------------------------------------------------------|
+ * | `newPassword`         | `string` | ✅       | The new password to set for the user.                        |
+ * | `resetPasswordToken`  | `string` | ✅       | The token required to authenticate the password reset process. |
+ *
+ * 📤 **Returns**:
+ * A `Promise<void>` that resolves with a success message `"OK"` if the password is successfully reset.
+ *
+ * 🛠 **Example usage**:
+ * ```ts
+ * await resetPassword({
+ *   newPassword: "mySecurePassword2025!",
+ *   resetPasswordToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+ * });
  * ```
+ *
+ * @param {ResetPasswordParameters} params - The parameters required for resetting the password.
+ * @throws {Error} If the required parameters `newPassword` or `resetPasswordToken` are missing.
+ * @returns {Promise<void>} Resolves to `"OK"` if the password reset is successful.
  */
 async function resetPassword({ newPassword, resetPasswordToken, }) {
     (0, parameters_validation_1.required)({ newPassword, resetPasswordToken });
@@ -120,23 +134,29 @@ async function resetPassword({ newPassword, resetPasswordToken, }) {
     });
 }
 /**
- * ## Send an email to the user with a reset password link
- * ### APICODE(PWD-101)
- * @param {SendResetPasswordEmailParameters} params - The parameters for the function, including:
- * #### email - `string` | <strong style={{ color: 'red' }}>required</strong>
- * The email address to send the reset link to.
- *
- * @returns {Promise<void>} - A promise that resolves when the email is sent
- *
- * @example
- * #### input
- * ```typescript
- *    await sendResetPasswordEmail({ email: 'user@example.com' });
- * ```
- * #### output
- * ```json
- *    "OK" (No output, resolves on success)
+ * 📧 Sends a reset password email to a user.
+ *
+ * This function sends an email containing a reset password link to the specified email address.
+ *
+ * 🛠 **Endpoint**: `POST /auth/send-reset-password-email [PWD-101]`
+ *
+ * | Parameter  | Type     | Required | Description                                        |
+ * |------------|----------|----------|----------------------------------------------------|
+ * | `email`    | `string` | ✅       | The email address to which the reset link will be sent. |
+ *
+ * 📤 **Returns**:
+ * A `Promise<void>` that resolves when the reset password email is successfully sent.
+ *
+ * 🛠 **Example usage**:
+ * ```ts
+ * await sendResetPasswordEmail({
+ *   email: "user@example.com",
+ * });
  * ```
+ *
+ * @param {SendResetPasswordEmailParameters} params - The parameters required to send the reset password email.
+ * @throws {Error} If the required parameter `email` is missing.
+ * @returns {Promise<void>} Resolves when the reset email is successfully sent.
  */
 async function sendResetPasswordEmail({ email, }) {
     (0, parameters_validation_1.required)({ email });
@@ -149,34 +169,33 @@ async function sendResetPasswordEmail({ email, }) {
     });
 }
 /**
- * ##Login a user
- * ### APICODE(AUTH-101)
- * @param {LoginParameters} params - The parameters for the function, including:
- * #### username - `string` | <strong style={{ color: 'red' }}>required</strong>
- * The username of the user to log in.
- * #### password - `string` | <strong style={{ color: 'red' }}>required</strong>
- * The password of the user to log in.
- *
- * @returns {Promise<LoginResponse>} - A promise that resolves to the response containing the user's login information
- *
- * @example
- * #### input
- * ```typescript
- *    const loginResponse = await login({ username: 'user@example.com', password: 'password123' });
- * ```
- * #### output
- * ```json
- *    {
- *      "token": {
- *        "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
- *        "expireAt": 1679022000,
- *        "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
- *      },
- *      "user": {
- *        "id": "userID"
- *      }
- *    }
+ * 🔐 Logs in a user.
+ *
+ * This function allows a user to log in by providing their username and password, and returns their login information, including an access token and user details.
+ *
+ * 🛠 **Endpoint**: `POST /auth/token?withUser=true [AUTH-101]`
+ *
+ * | Parameter   | Type     | Required | Description                          |
+ * |-------------|----------|----------|--------------------------------------|
+ * | `username`  | `string` | ✅       | The username of the user to log in.  |
+ * | `password`  | `string` | ✅       | The password of the user to log in.  |
+ *
+ * 📤 **Returns**:
+ * A `Promise<LoginResponse>` that resolves to the user's login information, including:
+ * - `token` (object): Contains the `accessToken`, `refreshToken`, and `expireAt` timestamp.
+ * - `user` (object): Contains the user's `id`.
+ *
+ * 🛠 **Example usage**:
+ * ```ts
+ * const loginResponse = await login({
+ *   username: "user@example.com",
+ *   password: "password123",
+ * });
  * ```
+ *
+ * @param {LoginParameters} params - The parameters required for logging in the user.
+ * @throws {Error} If the required parameters `username` or `password` are missing.
+ * @returns {Promise<LoginResponse>} Resolves to an object containing the user's login information.
  */
 async function login({ username, password, }) {
     (0, parameters_validation_1.required)({ username, password });
@@ -191,20 +210,26 @@ async function login({ username, password, }) {
     return data;
 }
 /**
- * ### Logout the user
- * ### APICODE(AUTH-103)
+ * 🚪 Logs out the user.
  *
- * @returns {Promise<void>} - A promise that resolves when the user is logged out
+ * This function logs out the user by revoking their authentication token.
  *
- * @example
- * #### input
- * ```typescript
- *    await logout();
- * ```
- * #### output
- * ```json
- *    "OK" (No output, resolves on success)
+ * 🛠 **Endpoint**: `POST /auth/revoke-token [AUTH-103]`
+ *
+ * | Parameter | Type | Required | Description |
+ * |-----------|------|----------|-------------|
+ * | *(none)*  | -    | -        | This function does not require any parameters. |
+ *
+ * 📤 **Returns**:
+ * A `Promise<void>` that resolves when the user is successfully logged out. No additional data is returned.
+ *
+ * 🛠 **Example usage**:
+ * ```ts
+ * await logout();
  * ```
+ *
+ * @throws {Error} If there is an issue with the logout process (e.g., network error).
+ * @returns {Promise<void>} Resolves when the logout is successful.
  */
 async function logout() {
     await (0, fetch_instance_1.enhancedFetch)({