oneentry 1.0.159 → 1.0.161

package/esm/users/usersApi.js

@@ -0,0 +1,312 @@
+import AsyncModules from '../base/asyncModules.js';
+import createSchemaLoader from '../base/lazySchema.js';
+const schema = createSchemaLoader(() => import('./usersSchemas.js'));
+/**
+ * Controllers for working with users
+ * @handle /api/content/users
+ * @description This module provides various methods to manage users, including creating, retrieving, updating, and deleting user data. It requires proper authorization to access these endpoints.
+ */
+export default class UsersApi extends AsyncModules {
+    /**
+     * Constructor for UsersApi class.
+     * @param {StateModule} state - The state module containing necessary information for API calls.
+     * @description Initializes the UsersApi class with the provided state module.
+     */
+    constructor(state) {
+        super(state);
+        this._url = state.url + '/api/content/users';
+    }
+    /**
+     * Getting the data of an authorized user.
+     * @handleName getUser
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @returns {Promise<IUserEntity | IError>} Returns a promise that resolves to the user entity object if successful; otherwise, returns an error object.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description This method requires user authorization.
+     * @see For more information about configuring the {@link https://js-sdk.oneentry.cloud/docs/category/authprovider authorization module}, see the documentation in the  {@link https://js-sdk.oneentry.cloud/docs/category/authprovider configuration settings section of the SDK}.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/users/getUser getUser} documentation.
+     */
+    async getUser(langCode = this.state.lang) {
+        const result = await this._fetchGet(`/me?langCode=${langCode}`);
+        // Validate response if validation is enabled
+        const validated = await this._validateResponse(result, schema('UserResponseSchema'));
+        return this._normalizeData(validated);
+    }
+    /**
+     * Updating a single user object.
+     * @handleName updateUser
+     * @param {IUserBody} body - Request body.
+     * @example
+        {
+          "formIdentifier": "reg",
+          "authData": [
+            {
+              "marker": "email_reg",
+              "value": "your-email@oneentery.cloud"
+            },
+            {
+              "marker": "password_reg",
+              "value": "12345"
+            }
+          ],
+          "formData": [
+            {
+              "marker": "last_name",
+              "type": "string",
+              "value": "Username"
+            }
+          ],
+          "notificationData": {
+            "email": "example@oneentry.cloud",
+            "phonePush": ["+99999999999"],
+            "phoneSMS": "+99999999999"
+          },
+          "state": {}
+        }
+     * @param {string} body.formIdentifier - Identifies the registration form being used. Example: "reg_form".
+     * @param {string} body.authData - Contains authentication credentials for the user. Example:
+     * @example
+        [
+          {
+            "marker": "email_reg",
+            "value": "example@oneentry.cloud"
+          },
+          {
+            "marker": "password_reg",
+            "value": "password"
+          }
+        ]
+     * @param {string} body.authData[].marker - Identifies the field being used. Example: "email_reg".
+     * @param {string} body.authData[].value - Contains the value of the field. Example: "example@oneentry.cloud".
+     * @param {string} body.formData - Contains additional data for the user.
+     * @example
+        [
+          {
+            "marker": "last_name",
+            "type": "string",
+            "value": "Username"
+          }
+        ]
+     * @param {string} body.formData[].marker - The marker of the field. Example: "last_name".
+     * @param {string} body.formData[].type - The type of the field. Example: "string".
+     * @param {string} body.formData[].value - The value of the field. Example: "Username".
+     * @param {string} body.notificationData - The notification data.
+     * @example
+        {
+          "email": "example@oneentry.cloud",
+          "phonePush": ["+99999999999"],
+          "phoneSMS": "+99999999999"
+        }
+     * @param {string} body.notificationData.email - The email address of the user. Example: "example@oneentry.cloud".
+     * @param {string} body.notificationData.phonePush - An array of phone numbers for push notifications. Example: ["+99999999999"].
+     * @param {string} body.notificationData.phoneSMS - The phone number for SMS notifications. Example: "+99999999999".
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @returns {Promise<boolean | IError>} Returns `true` if the user object was successfully updated; otherwise, returns an error object.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description This method updates the user's data. This method requires user authorization.
+     * @see For more information about configuring the {@link https://js-sdk.oneentry.cloud/docs/category/authprovider authorization module}, see the documentation in the  {@link https://js-sdk.oneentry.cloud/docs/category/authprovider configuration settings section of the SDK}.
+     * @see For more information about {@link https://doc.oneentry.cloud/docs/forms/create-form registration forms}, see the documentation in the  {@link https://doc.oneentry.cloud/docs/forms/create-form forms configuration section}.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/users/updateUser updateUser} documentation.
+     */
+    async updateUser(body, langCode = this.state.lang) {
+        if (!('langCode' in body))
+            body['langCode'] = langCode;
+        const result = await this._fetchPut('/me', this._normalizePostBody(body, langCode));
+        const validated = await this._validateResponse(result, schema('UpdateUserResponseSchema'));
+        return validated;
+    }
+    /**
+     * Archiving one user object (marked for deletion).
+     * @handleName archiveUser
+     * @returns {Promise<boolean | IError>} Returns `true` if the user was successfully deleted; otherwise, returns an error object.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description This method archives a user object (marks it for deletion). This method requires user authorization.
+     * @see For more information about configuring the {@link https://js-sdk.oneentry.cloud/docs/auth-provider/authprovider authorization module}, see the documentation in the  {@link https://js-sdk.oneentry.cloud/docs/category/authprovider configuration settings section of the SDK}.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/users/archiveUser archiveUser} documentation.
+     */
+    async archiveUser() {
+        const result = await this._fetchDelete('/me');
+        return result;
+    }
+    /**
+     * Delete a single user.
+     * @handleName deleteUser
+     * @returns {Promise<boolean | IError>} Returns `true` if the user was successfully deleted; otherwise, returns an error object.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description This method deletes the user from the system. This method requires user authorization.
+     * @see For more information about configuring the {@link https://js-sdk.oneentry.cloud/docs/category/authprovider authorization module}, see the documentation in the  {@link https://js-sdk.oneentry.cloud/docs/category/authprovider configuration settings section of the SDK}.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/users/deleteUser deleteUser} documentation.
+     */
+    async deleteUser() {
+        const result = await this._fetchDelete('/me/account');
+        return result;
+    }
+    /**
+     * Adds an FCM (Firebase Cloud Messaging) token for sending push notifications.
+     * @handleName addFCMToken
+     * @param {string} token - The cloud messaging token to be added. This token is used to identify the user's device for push notifications. Example: "fcm_token_1234567890abcdefg".
+     * @returns {Promise<boolean | IError>} Returns `true` if the token was successfully added; otherwise, returns an error object.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description This method adds an FCM token for sending push notifications. This method requires user authorization.
+     * @see For more information about configuring the {@link https://js-sdk.oneentry.cloud/docs/category/authprovider authorization module}, see the documentation in the  {@link https://js-sdk.oneentry.cloud/docs/category/authprovider configuration settings section of the SDK}.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/users/addFCMToken addFCMToken} documentation.
+     */
+    async addFCMToken(token) {
+        const result = await this._fetchPost(`/me/fcm-token/${token}`);
+        return result;
+    }
+    /**
+     * Deletes an FCM (Firebase Cloud Messaging) token.
+     * @handleName deleteFCMToken
+     * @param {string} token - The cloud messaging token to be deleted. This token is used to identify the user's device for push notifications and will be removed. Example: "fcm_token_1234567890abcdefg".
+     * @returns {Promise<boolean | IError>} Returns `true` if the token was successfully deleted; otherwise, returns an error object.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description This method deletes an existing FCM token. This method requires user authorization.
+     * @see For more information about configuring the {@link https://js-sdk.oneentry.cloud/docs/category/authprovider authorization module}, see the documentation in the  {@link https://js-sdk.oneentry.cloud/docs/category/authprovider configuration settings section of the SDK}.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/users/deleteFCMToken deleteFCMToken} documentation.
+     */
+    async deleteFCMToken(token) {
+        const result = await this._fetchDelete(`/me/fcm-token/${token}`);
+        return result;
+    }
+    /**
+     * Get the current user's or guest's cart.
+     * @handleName getCart
+     * @returns {Promise<ICartResponse | IError>} Returns the cart with its items and total.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description This method requires user authorization (or a guest context).
+     * @see For more information about configuring the {@link https://js-sdk.oneentry.cloud/docs/category/authprovider authorization module}, see the documentation in the  {@link https://js-sdk.oneentry.cloud/docs/category/authprovider configuration settings section of the SDK}.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/users/getCart getCart} documentation.
+     */
+    async getCart() {
+        const result = await this._fetchGet('/me/cart');
+        const validated = await this._validateResponse(result, schema('CartResponseSchema'));
+        return this._normalizeData(validated);
+    }
+    /**
+     * Replace the current user's or guest's cart.
+     * @handleName setCart
+     * @param {ICartSet} body - New cart contents. Example: `{ items: [{ productId: 1, qty: 2 }] }`.
+     * @returns {Promise<ICartResponse | IError>} Returns the updated cart.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description This method requires user authorization (or a guest context).
+     * @see For more information about configuring the {@link https://js-sdk.oneentry.cloud/docs/category/authprovider authorization module}, see the documentation in the  {@link https://js-sdk.oneentry.cloud/docs/category/authprovider configuration settings section of the SDK}.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/users/setCart setCart} documentation.
+     */
+    async setCart(body) {
+        const result = await this._fetchPut('/me/cart', body);
+        const validated = await this._validateResponse(result, schema('CartResponseSchema'));
+        return this._normalizeData(validated);
+    }
+    /**
+     * Add an item to the cart (or update qty of an existing one).
+     * @handleName addCartItem
+     * @param {ICartAddItem} body - Item to add. Example: `{ productId: 1, qty: 2 }`.
+     * @returns {Promise<ICartResponse | IError>} Returns the updated cart.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description This method requires user authorization (or a guest context).
+     * @see For more information about configuring the {@link https://js-sdk.oneentry.cloud/docs/category/authprovider authorization module}, see the documentation in the  {@link https://js-sdk.oneentry.cloud/docs/category/authprovider configuration settings section of the SDK}.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/users/addCartItem addCartItem} documentation.
+     */
+    async addCartItem(body) {
+        const result = await this._fetchPost('/me/cart/items', body);
+        const validated = await this._validateResponse(result, schema('CartResponseSchema'));
+        return this._normalizeData(validated);
+    }
+    /**
+     * Remove an item from the cart.
+     * @handleName removeCartItem
+     * @param {number} productId - Product identifier. Example: 12345.
+     * @returns {Promise<ICartResponse | IError>} Returns the updated cart.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description This method requires user authorization (or a guest context).
+     * @see For more information about configuring the {@link https://js-sdk.oneentry.cloud/docs/category/authprovider authorization module}, see the documentation in the  {@link https://js-sdk.oneentry.cloud/docs/category/authprovider configuration settings section of the SDK}.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/users/removeCartItem removeCartItem} documentation.
+     */
+    async removeCartItem(productId) {
+        const result = await this._fetchDelete(`/me/cart/items/${productId}`);
+        const validated = await this._validateResponse(result, schema('CartResponseSchema'));
+        return this._normalizeData(validated);
+    }
+    /**
+     * Get the current user's or guest's wishlist.
+     * @handleName getWishlist
+     * @returns {Promise<IWishlistResponse | IError>} Returns the wishlist with its items and total.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description This method requires user authorization (or a guest context).
+     * @see For more information about configuring the {@link https://js-sdk.oneentry.cloud/docs/category/authprovider authorization module}, see the documentation in the  {@link https://js-sdk.oneentry.cloud/docs/category/authprovider configuration settings section of the SDK}.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/users/getWishlist getWishlist} documentation.
+     */
+    async getWishlist() {
+        const result = await this._fetchGet('/me/wishlist');
+        const validated = await this._validateResponse(result, schema('WishlistResponseSchema'));
+        return this._normalizeData(validated);
+    }
+    /**
+     * Replace the current user's or guest's wishlist.
+     * @handleName setWishlist
+     * @param {IWishlistSet} body - New wishlist contents. Example: `{ items: [{ productId: 1 }] }`.
+     * @returns {Promise<IWishlistResponse | IError>} Returns the updated wishlist.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description This method requires user authorization (or a guest context).
+     * @see For more information about configuring the {@link https://js-sdk.oneentry.cloud/docs/category/authprovider authorization module}, see the documentation in the  {@link https://js-sdk.oneentry.cloud/docs/category/authprovider configuration settings section of the SDK}.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/users/setWishlist setWishlist} documentation.
+     */
+    async setWishlist(body) {
+        const result = await this._fetchPut('/me/wishlist', body);
+        const validated = await this._validateResponse(result, schema('WishlistResponseSchema'));
+        return this._normalizeData(validated);
+    }
+    /**
+     * Add an item to the wishlist.
+     * @handleName addWishlistItem
+     * @param {IWishlistAddItem} body - Item to add. Example: `{ productId: 1 }`.
+     * @returns {Promise<IWishlistResponse | IError>} Returns the updated wishlist.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description This method requires user authorization (or a guest context).
+     * @see For more information about configuring the {@link https://js-sdk.oneentry.cloud/docs/category/authprovider authorization module}, see the documentation in the  {@link https://js-sdk.oneentry.cloud/docs/category/authprovider configuration settings section of the SDK}.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/users/addWishlistItem addWishlistItem} documentation.
+     */
+    async addWishlistItem(body) {
+        const result = await this._fetchPost('/me/wishlist/items', body);
+        const validated = await this._validateResponse(result, schema('WishlistResponseSchema'));
+        return this._normalizeData(validated);
+    }
+    /**
+     * Remove an item from the wishlist.
+     * @handleName removeWishlistItem
+     * @param {number} productId - Product identifier. Example: 12345.
+     * @returns {Promise<IWishlistResponse | IError>} Returns the updated wishlist.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description This method requires user authorization (or a guest context).
+     * @see For more information about configuring the {@link https://js-sdk.oneentry.cloud/docs/category/authprovider authorization module}, see the documentation in the  {@link https://js-sdk.oneentry.cloud/docs/category/authprovider configuration settings section of the SDK}.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/users/removeWishlistItem removeWishlistItem} documentation.
+     */
+    async removeWishlistItem(productId) {
+        const result = await this._fetchDelete(`/me/wishlist/items/${productId}`);
+        const validated = await this._validateResponse(result, schema('WishlistResponseSchema'));
+        return this._normalizeData(validated);
+    }
+    /**
+     * Semantic (vector) search for users.
+     * @handleName getUsersByVectorSearch
+     * @param {IUsersVectorSearch} body - Vector search body. Example: `{ queryText: "john" }`.
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @param {number} [offset] - Parameter for pagination. Default: 0.
+     * @param {number} [limit] - Parameter for pagination. Default: 30.
+     * @returns {Promise<IUsersResponse | IError>} Returns an object with an array of found users and total count.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description This method performs a semantic (vector) search for users. It requires user authorization.
+     * @see For more information about configuring the {@link https://js-sdk.oneentry.cloud/docs/category/authprovider authorization module}, see the documentation in the  {@link https://js-sdk.oneentry.cloud/docs/category/authprovider configuration settings section of the SDK}.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/users/getUsersByVectorSearch getUsersByVectorSearch} documentation.
+     */
+    async getUsersByVectorSearch(body, langCode = this.state.lang, offset = 0, limit = 30) {
+        const query = {
+            langCode,
+            offset,
+            limit,
+        };
+        const result = await this._fetchPost(`/vector/search?` + this._queryParamsToString(query), body);
+        return this._normalizeData(result, langCode);
+    }
+}