oneentry 1.0.159 → 1.0.161

package/esm/products/productsApi.js

@@ -0,0 +1,468 @@
+/* eslint-disable jsdoc/reject-any-type */
+import AsyncModules from '../base/asyncModules.js';
+import createSchemaLoader from '../base/lazySchema.js';
+const schema = createSchemaLoader(() => import('./productsSchemas.js'));
+/**
+ * Controllers for working with product pages
+ * @handle /api/content/products
+ * @description Controllers for working with product pages
+ */
+export default class ProductsApi extends AsyncModules {
+    /**
+     * Constructor
+     * @param {StateModule} state - StateModule instance
+     * @description Constructor initializes the ProductsApi with a given state.
+     */
+    constructor(state) {
+        super(state);
+        this._url = state.url + '/api/content/products';
+    }
+    /**
+     * Search for all products with pagination and filter.
+     * @handleName getProducts
+     * @param {IFilterParams[]} [body] - Request body. Default: [].
+     * @example
+        [
+          {
+            "attributeMarker": "price",
+            "conditionMarker": "mth",
+            "statusMarker": "waiting",
+            "conditionValue": 1,
+            "pageUrls": [
+              "23-laminat-floorwood-maxima"
+            ],
+            "isNested": false,
+            "title": ""
+          },
+          {
+            "attributeMarker": "price",
+            "conditionMarker": "lth",
+            "conditionValue": 3,
+            "pageUrls": [
+              "23-laminat-floorwood-maxima"
+            ],
+            "isNested": false,
+            "title": ""
+          }
+        ]
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @param {IProductsQueryBase} [userQuery] - Optional set query parameters.
+     * @example
+        {
+          "limit": 30,
+          "offset": 0,
+          "sortOrder": "DESC",
+          "sortKey": "id",
+          "signPrice": "orders"
+        }
+     * @param {string} [userQuery.signPrice] - Order storage marker for price fixing. If the parameter is set, the price is fixed for a certain time. Example: "orders_storage".
+     * @see {@link https://js-sdk.oneentry.cloud/docs/products/#Fixing-the-price-signPrice Fixing the price} documentation.
+     * @param {string} [userQuery.sortOrder] - Sorting order parameter.
+     * @returns {Promise<IProductsResponse | IError>} Products response, or IError when isShell=true
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description Fetch products with optional filters and pagination.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/products/getProducts getProducts} documentation.
+     */
+    async getProducts(body = [], langCode = this.state.lang, userQuery) {
+        const query = {
+            ...userQuery,
+            langCode,
+        };
+        const result = await this._fetchPost(`/all?` + this._queryParamsToString(query), { filter: body });
+        // Validate response if validation is enabled
+        const validated = await this._validateResponse(result, schema('ProductsResponseSchema'));
+        return this._normalizeData(validated, langCode);
+    }
+    /**
+     * Search for all product page objects with pagination (and aggregation) that do not have a category.
+     * @handleName getProductsEmptyPage
+     * @param {object} [body] - Request body. Default: {}.
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @param {IProductsQueryBase} [userQuery] - Optional set query parameters.
+     * @example
+        {
+          "limit": 30,
+          "offset": 0,
+          "sortOrder": "DESC",
+          "sortKey": "id",
+          "signPrice": "orders"
+        }
+     * @returns {Promise<IAggregatedProductGroup[] | IError>} Array with AggregatedProductGroup objects.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description Search for all product page objects with pagination (and aggregation) that do not have a category.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/products/getProductsEmptyPage getProductsEmptyPage} documentation.
+     */
+    async getProductsEmptyPage(body = {}, langCode = this.state.lang, userQuery) {
+        const query = { ...userQuery, langCode };
+        const result = await this._fetchPost(`/empty-page?` + this._queryParamsToString(query), body);
+        return this._normalizeData(result);
+    }
+    /**
+     * Search for all products with pagination for the selected category.
+     * @handleName getProductsByPageId
+     * @param {number} id - Page id. Example: 2492.
+     * @param {IFilterParams[]} [body] - Request body. Default: [].
+     * @example
+        [
+          {
+            "attributeMarker": "price",
+            "conditionMarker": "mth",
+            "statusMarker": "waiting",
+            "conditionValue": 1,
+            "pageUrls": [
+              "23-laminat-floorwood-maxima"
+            ],
+            "isNested": false,
+            "title": ""
+          },
+          {
+            "attributeMarker": "price",
+            "conditionMarker": "lth",
+            "conditionValue": 3,
+            "pageUrls": [
+              "23-laminat-floorwood-maxima"
+            ],
+            "isNested": false,
+            "title": ""
+          }
+        ]
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @param {IProductsQueryBase} [userQuery] - Optional set query parameters.
+     * @example
+        {
+          "limit": 30,
+          "offset": 0,
+          "sortOrder": "DESC",
+          "sortKey": "id",
+          "signPrice": "orders"
+        }
+     * @returns {Promise<IProductsResponse | IError>} Array with ProductEntity objects
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description Fetch products by page ID with optional filters and pagination.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/products/getProductsByPageId getProductsByPageId} documentation.
+     */
+    async getProductsByPageId(id, body = [], langCode = this.state.lang, userQuery) {
+        const query = { ...userQuery };
+        const result = await this._fetchPost(`/page/${id}?langCode=${langCode}&` + this._queryParamsToString(query), { filter: body });
+        // Validate response if validation is enabled
+        const validated = await this._validateResponse(result, schema('ProductsResponseSchema'));
+        return this._normalizeData(validated, langCode);
+    }
+    /**
+     * Search for information about products and prices for the selected category.
+     * @handleName getProductsPriceByPageUrl
+     * @param {string} [url] - Page url. Example: "23-laminat-floorwood-maxima".
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @param {IProductsPriceQuery} [userQuery] - Optional set query parameters.
+     * @example
+        {
+          "limit": 30,
+          "offset": 0,
+          "sortOrder": "DESC",
+          "signPrice": "orders",
+          "statusMarker": "in_stock"
+        }
+     * @returns {Promise<IProductsInfo | IError>} Array with ProductInformation objects.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description Search for information about products and prices for the selected category.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/products/getProductsPriceByPageUrl getProductsPriceByPageUrl} documentation.
+     */
+    async getProductsPriceByPageUrl(url, langCode = this.state.lang, userQuery) {
+        const query = {
+            ...userQuery,
+            langCode,
+        };
+        const result = await this._fetchGet(`/page/${url}/prices?` + this._queryParamsToString(query));
+        return result;
+    }
+    /**
+     * Search for all products with pagination for the selected category.
+     * @handleName getProductsByPageUrl
+     * @param {string} url - Page url. Example: "catalog".
+     * @param {IFilterParams[]} [body] - Request body. Default: [].
+     * @example
+        [
+          {
+            "attributeMarker": "price",
+            "conditionMarker": "mth",
+            "statusMarker": "waiting",
+            "conditionValue": 1,
+            "pageUrls": [
+            "23-laminat-floorwood-maxima"
+            ],
+            "isNested": false,
+            "title": ""
+          },
+          {
+            "attributeMarker": "price",
+            "conditionMarker": "lth",
+            "conditionValue": 3,
+            "pageUrls": [
+            "23-laminat-floorwood-maxima"
+            ],
+            "isNested": false,
+            "title": ""
+          }
+        ]
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @param {IProductsQueryBase} [userQuery] - Optional set query parameters.
+     * @example
+        {
+          "limit": 30,
+          "offset": 0,
+          "sortOrder": "DESC",
+          "sortKey": "id",
+          "signPrice": "orders"
+        }
+     * @returns {Promise<IProductsResponse | IError>} Array with ProductEntity objects.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description Search for all products with pagination for the selected category.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/products/getProductsByPageUrl getProductsByPageUrl} documentation.
+     */
+    async getProductsByPageUrl(url, body = [], langCode = this.state.lang, userQuery) {
+        const query = { ...userQuery };
+        const result = await this._fetchPost(`/page/url/${url}?langCode=${langCode}&` +
+            this._queryParamsToString(query), { filter: body });
+        // Validate response if validation is enabled
+        const validated = await this._validateResponse(result, schema('ProductsResponseSchema'));
+        return this._normalizeData(validated, langCode);
+    }
+    /**
+     * Find all related product page objects.
+     * @handleName getRelatedProductsById
+     * @param {number} [id] - Product page identifier for which to find relationship. Example: 12345.
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @param {IProductsRelatedQuery} [userQuery] - Optional set query parameters.
+     * @example
+        {
+          "limit": 30,
+          "offset": 0,
+          "sortOrder": "DESC",
+          "sortKey": "id",
+          "signPrice": "orders",
+          "statusMarker": "in_stock",
+          "templateMarker": "template_12345"
+        }
+     * @param {number} [userQuery.limit] - Optional parameter for pagination. Default: 30.
+     * @param {number} [userQuery.offset] - Optional parameter for pagination. Default: 0.
+     * @param {string} [userQuery.sortOrder] - Optional sorting order "DESC" | "ASC". Example: "DESC".
+     * @param {string} [userQuery.sortKey] - Optional field to sort by ("id", "title", "date", "price", "position", "status"). Example: "id".
+     * @returns {Promise<IProductsResponse | IError>} Array with ProductEntity objects
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description Find all related product page objects.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/products/getRelatedProductsById getRelatedProductsById} documentation.
+     */
+    async getRelatedProductsById(id, langCode = this.state.lang, userQuery) {
+        const query = { ...userQuery };
+        const result = await this._fetchGet(`/${id}/related?langCode=${langCode}&` + this._queryParamsToString(query));
+        // Validate response if validation is enabled
+        const validated = await this._validateResponse(result, schema('ProductsResponseSchema'));
+        return this._normalizeData(validated, langCode);
+    }
+    /**
+     * Find products by its ids.
+     * @handleName getProductsByIds
+     * @param {string} ids - Product page identifiers for which to find relationships. Example: "12345,67890".
+     * @param {string} [langCode] - Language code. Default "en_US".
+     * @param {IProductsByIdsQuery} [userQuery] - Optional set query parameters.
+     * @example
+        {
+          "limit": 30,
+          "offset": 0,
+          "signPrice": "orders"
+        }
+     * @param {number} [userQuery.limit] - Optional parameter for pagination. Default: 30.
+     * @param {number} [userQuery.offset] - Optional parameter for pagination. Default: 0.
+     * @param {string} [userQuery.signPrice] - Order storage marker for price fixing.
+     * @returns {Promise<IProductsEntity[] | IError>} Array with ProductEntity objects
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description Find products by its ids.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/products/getProductsByIds getProductsByIds} documentation.
+     */
+    async getProductsByIds(ids, langCode = this.state.lang, userQuery) {
+        const query = {
+            ids,
+            langCode,
+            ...userQuery,
+        };
+        const result = await this._fetchGet(`/ids?` + this._queryParamsToString(query));
+        return this._normalizeData(result, langCode);
+    }
+    /**
+     * Retrieve one product object.
+     * @handleName getProductById
+     * @param {number} id - Product id. Example: 12345.
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @param {boolean} [isNormalized] - If true, the product object will be normalized.
+     * @returns {Promise<IProductsEntity | IError>} ProductEntity object.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description Retrieve one product object.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/products/getProductById getProductById} documentation.
+     */
+    async getProductById(id, langCode = this.state.lang, isNormalized) {
+        const query = { langCode };
+        if (isNormalized !== undefined)
+            query.isNormalized = isNormalized;
+        const result = await this._fetchGet(`/${id}?` + this._queryParamsToString(query));
+        // Validate response if validation is enabled
+        const validated = await this._validateResponse(result, schema('ProductEntitySchema'));
+        return this._normalizeData(validated, langCode);
+    }
+    /**
+     * Getting a product block object by product id.
+     * @handleName getProductBlockById
+     * @param {number} id - Product id. Example: 12345.
+     * @returns {Promise<IProductBlock | IError>} - Product block object.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description Getting a product block object by product id.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/products/getProductBlockById getProductBlockById} documentation.
+     */
+    async getProductBlockById(id) {
+        const response = await this._fetchGet(`/${id}/blocks`);
+        return this._normalizeData(response);
+    }
+    /**
+     * Quick search for product page objects with limited output.
+     * @handleName searchProduct
+     * @param {string} name - Text to search product page objects (search is based on the title field of the localizeInfos object with language consideration). Example: "laminat".
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @returns {Promise<IProductsEntity[] | IProductSearchResult[] | IError>} Array with ProductEntity objects, or an array with short ProductSearchResult cards when the traficLimit config option is enabled
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description Quick search for product page objects with limited output. The quick search endpoint returns short cards ({ id, title, pageId }); with traficLimit enabled they are returned as is, otherwise full product entities are fetched for the found ids.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/products/searchProduct searchProduct} documentation.
+     */
+    async searchProduct(name, langCode = this.state.lang) {
+        const result = await this._fetchGet(`/quick/search?langCode=${encodeURIComponent(langCode)}&name=${encodeURIComponent(name)}`);
+        // Validate response if validation is enabled
+        const searchProducts = (await this._validateResponse(result, schema('ProductSearchResponseSchema')));
+        if (!this.state.traficLimit && Array.isArray(searchProducts)) {
+            if (searchProducts.length === 0)
+                return searchProducts;
+            const ids = searchProducts.map((product) => product.id);
+            // One /ids request instead of one getProductById per result.
+            const products = await this.getProductsByIds(ids.join(','), langCode);
+            if (!Array.isArray(products))
+                return products;
+            // /ids re-sorts by id (DESC) by default, so restore the original
+            // search relevance order from the quick search response.
+            const byId = new Map(products.map((product) => [product.id, product]));
+            return ids
+                .map((id) => byId.get(id))
+                .filter((product) => product !== undefined);
+        }
+        return searchProducts;
+    }
+    /**
+     * Getting the number of products for the entire catalog.
+     * @handleName getProductsCount
+     * @param {any[]} body - Body parameters for filter. Deault: [].
+     * @example
+        [
+          {
+            "attributeMarker": "price",
+            "conditionMarker": "in",
+            "statusMarker": "status_1",
+            "conditionValue": {},
+            "pageUrls": [
+              "23-laminat-floorwood-maxima"
+            ],
+            "title": "Iphone 17 Pro"
+          }
+        ]
+     * @returns {Promise<IProductsCount | IError>} Object with product items count.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description This method calculates and returns the total number of products present across the entire catalog, optionally applying specified filters.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/products/getProductsCount getProductsCount} documentation.
+     */
+    async getProductsCount(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    body = []) {
+        const result = await this._fetchPost(`/all/counts`, body);
+        return result;
+    }
+    /**
+     * Getting the number of products on a catalog page by page ID.
+     * @handleName getProductsCountByPageId
+     * @param {string} id - Page ID.
+     * @param {any[]} body - Body parameters for filter. Deault: [].
+     * @example
+        [
+          {
+            "attributeMarker": "price",
+            "conditionMarker": "in",
+            "statusMarker": "status_1",
+            "conditionValue": {},
+            "pageUrls": [
+              "23-laminat-floorwood-maxima"
+            ],
+            "title": "Iphone 17 Pro"
+          }
+        ]
+     * @returns {Promise<IProductsCount | IError>} Object with product items count.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description This method calculates and returns the number of products available on a given catalog page, identified by its page ID, with optional filtering.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/products/getProductsCountByPageId getProductsCountByPageId} documentation.
+     */
+    async getProductsCountByPageId(id, 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    body = []) {
+        const result = await this._fetchPost(`/page/${id}/counts`, body);
+        return result;
+    }
+    /**
+     * Getting the number of products for the catalog page by page url.
+     * @handleName getProductsCountByPageUrl
+     * @param {string} url - Page url.
+     * @param {any[]} body - Body parameters for filter. Deault: [].
+     * @example
+        [
+          {
+            "attributeMarker": "price",
+            "conditionMarker": "in",
+            "statusMarker": "status_1",
+            "conditionValue": {},
+            "pageUrls": [
+              "23-laminat-floorwood-maxima"
+            ],
+            "title": "Iphone 17 Pro"
+          }
+        ]
+     * @returns {Promise<IProductsCount | IError>} Object with product items count.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description This method calculates and returns the number of products available on a given catalog page, identified by its URL, with optional filtering.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/products/getProductsCountByPageUrl getProductsCountByPageUrl} documentation.
+     */
+    /**
+     * Semantic (vector) search for products.
+     * @handleName getProductsByVectorSearch
+     * @param {IVectorSearchProducts} body - Vector search body. Example: `{ queryText: "red running shoes" }`.
+     * @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<IProductsResponse | IError>} Returns an object with an array of found products and total count.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description This method performs a semantic (vector) search for products.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/products/getProductsByVectorSearch getProductsByVectorSearch} documentation.
+     */
+    async getProductsByVectorSearch(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);
+    }
+    /**
+     * Get products by page url.
+     * @param {string} url - Page url.
+     * @param {any[]} body - Request body.
+     * @returns {IProductsEntity[] | IError} Returns an array of products or an error object.
+     */
+    async getProductsCountByPageUrl(url, 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    body = []) {
+        const result = await this._fetchPost(`/page/url/${url}/counts`, body);
+        return result;
+    }
+}