oneentry 1.0.160 → 1.0.162

package/esm/pages/pagesApi.js

@@ -0,0 +1,397 @@
+/* eslint-disable jsdoc/reject-any-type */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import AsyncModules from '../base/asyncModules.js';
+import createSchemaLoader from '../base/lazySchema.js';
+import templatesApi from '../templates/templatesApi.js';
+const schema = createSchemaLoader(() => import('./pagesSchemas.js'));
+/**
+ * Controllers for working with page objects, including catalog pages
+ * @handle /api/content/pages
+ * @description Controllers for working with page objects, including catalog pages
+ */
+export default class PagesApi extends AsyncModules {
+    /**
+     * Constructor
+     * @param {StateModule} state - The state module.
+     * @description Constructor initializes the PageApi with a given state.
+     */
+    constructor(state) {
+        super(state);
+        this._url = state.url + '/api/content/pages';
+    }
+    /**
+     * Get all top-level page objects.
+     * @handleName getRootPages
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @returns {Promise<IPagesEntity[] | IError>} Returns all created pages without parents as an array of PageEntity objects or an empty array [] (if there is no data)
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description Get all top-level page objects.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/pages/getRootPages getRootPages} documentation.
+     */
+    async getRootPages(langCode = this.state.lang) {
+        // Fetch data from the server using a GET request to retrieve root pages for the specified language code
+        const data = await this._fetchGet(`/root?langCode=${langCode}`);
+        // Validate response if validation is enabled
+        const validated = await this._validateResponse(data, schema('PagesResponseSchema'));
+        // Add template information to each page in the fetched root pages data
+        const withTemplate = await this.addTemplateToPages(validated);
+        // Normalize the data and return it; ensures consistent structure or handles errors
+        return this._normalizeData(withTemplate, langCode);
+    }
+    /**
+     * Get all page objects with product information as an array.
+     * @handleName getPages
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @returns {Promise<IPagesEntity[] | IError>} Returns all created pages as an array of PageEntity objects or an empty array [] (if there is no data).
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description Get all page objects with product information as an array.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/pages/getPages getPages} documentation.
+     */
+    async getPages(langCode = this.state.lang) {
+        // Fetch data from the server using a GET request to retrieve all pages for the specified language code
+        const data = await this._fetchGet(`?langCode=${langCode}`);
+        // Validate response if validation is enabled
+        const validated = await this._validateResponse(data, schema('PagesResponseSchema'));
+        // Add template information to each page in the fetched data
+        const withTemplate = await this.addTemplateToPages(validated);
+        // Normalize the data and return it; ensures consistent structure or handles errors
+        return this._normalizeData(withTemplate, langCode);
+    }
+    /**
+     * Get page object with information about forms, blocks, menus, linked to the page.
+     * @handleName getPageById
+     * @param {number} id - The unique identifier of the page to be fetched. Example: 1.
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @returns {Promise<IPagesEntity | IError>} Returns PageEntity object
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description Get page object with information about forms, blocks, menus, linked to the page.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/pages/getPageById getPageById} documentation.
+     */
+    async getPageById(id, langCode = this.state.lang) {
+        // Fetch data from the server using a GET request to retrieve page details by ID and language code
+        const data = await this._fetchGet(`/${id}?langCode=${langCode}`);
+        // Validate response if validation is enabled
+        const validated = await this._validateResponse(data, schema('PageEntitySchema'));
+        // Add template information to the fetched page data
+        const withTemplate = await this.addTemplateToPage(validated);
+        // Normalize the data and return it; ensures consistent structure or handles errors
+        return this._normalizeData(withTemplate, langCode);
+    }
+    /**
+     * Get page object with information about forms, blocks, menus, linked to the page by URL.
+     * @handleName getPageByUrl
+     * @param {string} url - Page URL. Example: "about".
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @returns {Promise<IPagesEntity | IError>} Returns PageEntity object
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description Get page object with information about forms, blocks, menus, linked to the page by URL.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/pages/getPageByUrl getPageByUrl} documentation.
+     */
+    async getPageByUrl(url, langCode = this.state.lang) {
+        // Fetch data from the server using a GET request with the specified URL and language code
+        const data = await this._fetchGet(`/url/${url}?langCode=${langCode}`);
+        // Validate response if validation is enabled
+        const validated = await this._validateResponse(data, schema('PageEntitySchema'));
+        // Add template information to the fetched page data
+        const withTemplate = await this.addTemplateToPage(validated);
+        // Normalize the result data and return it; ensures consistent structure or handles errors
+        return this._normalizeData(withTemplate, langCode);
+    }
+    /**
+     * Get child pages object with information as an array.
+     * @handleName getChildPagesByParentUrl
+     * @param {string} url - The URL of the parent page for which child pages are to be fetched. Example: "about/our-team".
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @returns {Promise<IPagesEntity | IError>} Returns all created pages as an array of PageEntity objects or an empty array [] (if there is no data) for the selected parent
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description Get child pages object with information as an array.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/pages/getChildPagesByParentUrl getChildPagesByParentUrl} documentation.
+     */
+    async getChildPagesByParentUrl(url, langCode = this.state.lang) {
+        // Fetch data from the server using a GET request to retrieve child pages for the specified parent URL and language code
+        const data = await this._fetchGet(`/${url}/children?langCode=${langCode}`);
+        // Validate response if validation is enabled
+        const validated = await this._validateResponse(data, schema('PagesResponseSchema'));
+        // Add template information to each of the fetched child pages
+        const withTemplate = await this.addTemplateToPages(validated);
+        // Normalize the result data and return it; ensures consistent structure or handles errors
+        return this._normalizeData(withTemplate, langCode);
+    }
+    /**
+     * Get all blocks by page url.
+     * @handleName getBlocksByPageUrl
+     * @param {string} url - Page URL. Example: "about".
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @returns {Promise<IPositionBlock[] | IError>} Returns all blocks as an array of PositionBlock objects or an empty array [] (if there is no data) for the selected parent
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description Get all blocks by page url.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/pages/getBlocksByPageUrl getBlocksByPageUrl} documentation.
+     */
+    async getBlocksByPageUrl(url, langCode = this.state.lang) {
+        const response = await this._fetchGet(`/${url}/blocks?langCode=${langCode}`);
+        // Normalize the fetched response data
+        const normalizeResponse = this._normalizeData(response);
+        if (!Array.isArray(normalizeResponse)) {
+            return normalizeResponse;
+        }
+        // Helper module wrapping the block product endpoints (similar / products).
+        const staffModule = new StaffModule(this.state);
+        // Enrich every block in parallel: product / similar blocks
+        await Promise.all(normalizeResponse.map(async (item) => {
+            const customSettings = item.customSettings;
+            // Lift product display settings (stored as strings) to numeric top-level fields.
+            if (customSettings &&
+                Object.prototype.hasOwnProperty.call(customSettings, 'productConfig')) {
+                if (customSettings.productConfig.countElementsPerRow)
+                    item.countElementsPerRow =
+                        +customSettings.productConfig.countElementsPerRow;
+                if (customSettings.productConfig.quantity)
+                    item.quantity = +customSettings.productConfig.quantity;
+            }
+            // Remove internal-only properties from the result.
+            delete item.customSettings;
+            delete item.attributesSetIdentifier;
+            // In traffic-saving mode skip the extra product requests.
+            if (this.state.traficLimit)
+                return;
+            // Attach related products by block type. StaffModule already normalizes its results.
+            if (item.type === 'similar_products_block') {
+                try {
+                    item.similarProducts = await staffModule.getSimilarProducts(item.identifier, langCode);
+                }
+                catch {
+                    item.similarProducts = [];
+                }
+            }
+            else if (item.type === 'product_block') {
+                try {
+                    item.products = await staffModule.getProductsByBlockMarker(item.identifier, langCode);
+                }
+                catch {
+                    item.products = [];
+                }
+            }
+        }));
+        return normalizeResponse;
+    }
+    /**
+     * Quick search for page objects with limited output.
+     * @handleName searchPage
+     * @param {string} name - Text for searching page objects (search is performed on the title field of the localizeInfos object with the language taken into account). Example: "About Us".
+     * @param {string} [url] - Page URL. Example: "catalog".
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @returns {Promise<IPagesEntity[] | IPageSearchResult[] | IError>} Returns found pages as an array of PageEntity objects, an array of short PageSearchResult cards when the traficLimit config option is enabled, or an empty array [] (if there is no data)
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description Quick search for page objects with limited output. The quick search endpoint returns short cards ({ id, title }); with traficLimit enabled they are returned as is, otherwise full page entities are fetched for the found ids.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/pages/searchPage searchPage} documentation.
+     */
+    async searchPage(name, url, langCode = this.state.lang) {
+        // Fetch data from the server using a GET request to perform a quick search by page name and language code
+        const urlPart = url ? `url=${encodeURIComponent(url)}&` : '';
+        const searchPages = await this._fetchGet(`/quick/search?${urlPart}lang=${encodeURIComponent(langCode)}&name=${encodeURIComponent(name)}`);
+        // /quick/search?url=catalog&langCode=en_US&name=cat
+        // Validate response if validation is enabled
+        const data = (await this._validateResponse(searchPages, schema('PageSearchResponseSchema')));
+        // Check if there is no traffic limit set in the state
+        if (!this.state.traficLimit && Array.isArray(data)) {
+            // Initialize an empty array to store detailed page information
+            const pageList = [];
+            // Use Promise.all to fetch detailed information for each page concurrently
+            await Promise.all(data.map(async (page) => {
+                // Fetch detailed page information by page ID and push it to pageList
+                await this.getPageById(page.id, langCode).then((result) => {
+                    pageList.push(result);
+                });
+            }));
+            // Add templates to the fetched pages
+            const withTemplate = await this.addTemplateToPages(pageList);
+            // Normalize the data and return it; ensures consistent structure or handles errors
+            return this._normalizeData(withTemplate, langCode);
+        }
+        // With a traffic limit (or on an API error) return the quick search response as is:
+        // short cards carry no templateIdentifier, so there is nothing to attach a template to
+        return this._normalizeData(data, langCode);
+    }
+    /**
+     * Semantic (vector) search for pages.
+     * @handleName getPagesByVectorSearch
+     * @param {IPagesVectorSearch} body - Vector search body. Example: `{ queryText: "winter sale" }`.
+     * @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<IPagesResponse | IError>} Returns an object with an array of found pages and total count.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description This method performs a semantic (vector) search for pages.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/pages/getPagesByVectorSearch getPagesByVectorSearch} documentation.
+     */
+    async getPagesByVectorSearch(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);
+    }
+    /**
+     * Add template data to pages
+     * @handleName addTemplateToPages
+     * @param {IPagesEntity[]} data - An array of page objects (IPagesEntity[]) to which template data will be added.
+     * @example
+        [
+          {
+            "id": 8,
+            "parentId": null,
+            "moduleFormConfigs": [],
+            "pageUrl": "blog",
+            "depth": 0,
+            "localizeInfos": {
+              "title": "Blog",
+              "menuTitle": "Blog",
+              "htmlContent": "",
+              "plainContent": "",
+            },
+            "isVisible": true,
+            "forms": [],
+            "blocks": [],
+            "type": "common_page",
+            "templateIdentifier": "template",
+            "attributeSetIdentifier": "page",
+            "attributeValues": {},
+            "isSync": true,
+            "template": {
+              "id": 4,
+              "attributeSetIdentifier": null,
+              "title": "Template",
+              "generalTypeId": 4,
+              "identifier": "template",
+              "version": 0,
+              "generalTypeName": "catalog_page",
+              "attributeValues": {},
+              "position": 1,
+            }
+          }
+        ]
+     * @returns {Promise<any | IError>} An array of page objects with template data added
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description Add template data to pages. Optimized to avoid N+1 query problem by fetching only unique templates in parallel.
+     * For example, if 100 pages use 3 different templates, this method makes 3 requests instead of 100.
+     */
+    async addTemplateToPages(data) {
+        // On API error responses (e.g. 403 without list permission, 422) the value
+        // is an IError, not an array — return it as-is instead of calling array
+        // methods (.filter/.map) on it and throwing a TypeError.
+        if (!Array.isArray(data)) {
+            return data;
+        }
+        // Step 1: Collect unique templateIdentifiers from all pages
+        const uniqueIdentifiers = [
+            ...new Set(data
+                .filter((page) => 'templateIdentifier' in page &&
+                page.templateIdentifier !== null &&
+                page.templateIdentifier !== '')
+                .map((page) => page.templateIdentifier)),
+        ];
+        // Step 2: If no templates needed, return pages as-is
+        if (uniqueIdentifiers.length === 0) {
+            return data;
+        }
+        // Step 3: Fetch unique templates in parallel (not N queries, but unique count queries)
+        const Templates = new templatesApi(this.state);
+        const templatePromises = uniqueIdentifiers.map((identifier) => Templates.getTemplateByMarker(identifier).catch((error) => {
+            // eslint-disable-next-line no-undef, no-console
+            console.error(`Template fetch error for ${identifier}: `, error);
+            return null; // Return null for failed templates
+        }));
+        const templates = await Promise.all(templatePromises);
+        // Step 4: Create a Map for O(1) template lookup
+        const templateMap = new Map();
+        templates.forEach((template, index) => {
+            if (template !== null) {
+                templateMap.set(uniqueIdentifiers[index], template);
+            }
+        });
+        // Step 5: Apply templates to pages (no additional API calls)
+        return data.map((page) => {
+            if ('templateIdentifier' in page &&
+                page.templateIdentifier !== null &&
+                page.templateIdentifier !== '') {
+                const template = templateMap.get(page.templateIdentifier);
+                if (template) {
+                    return {
+                        ...page,
+                        template,
+                    };
+                }
+            }
+            // Return page without template if identifier is missing or template not found
+            return page;
+        });
+    }
+    /**
+     * Add template data to page by page templateIdentifier
+     * @handleName addTemplateToPage
+     * @param {IPagesEntity} data - Page object (IPagesEntity) to which template data will be added.
+     * @returns {Promise<any | IError>} An array of page objects with template data added
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description Add template data to page by page templateIdentifier
+     * @see {@link https://js-sdk.oneentry.cloud/docs/pages/addTemplateToPage addTemplateToPage} documentation.
+     */
+    async addTemplateToPage(data) {
+        // Check if 'templateIdentifier' exists in 'data' and is not null or an empty string
+        if ('templateIdentifier' in data &&
+            data.templateIdentifier !== null &&
+            data.templateIdentifier !== '') {
+            // Destructure 'templateIdentifier' from 'data'
+            const { templateIdentifier } = data;
+            try {
+                // Create a new instance of templatesApi with the current state
+                const Templates = new templatesApi(this.state);
+                // Fetch the template using the 'templateIdentifier'
+                const result = await Templates.getTemplateByMarker(templateIdentifier);
+                // Return the original data object with the fetched template added
+                return {
+                    ...data,
+                    template: result,
+                };
+            }
+            catch (error) {
+                // eslint-disable-next-line no-undef, no-console
+                console.error('Template fetch error: ', error);
+                return data;
+            }
+        }
+        else {
+            // If 'templateIdentifier' doesn't exist or is invalid, return the original data
+            return data;
+        }
+    }
+}
+/**
+ * Helper module for working with blocks, similar products and product blocks
+ * @description Internal module for fetching products and similar products for blocks
+ */
+class StaffModule extends AsyncModules {
+    constructor(state) {
+        super(state); // Call parent constructor
+        this._url = state.url + '/api/content/blocks'; // Set URL for content blocks
+    }
+    // Method to fetch similar products by marker. Returns the full response
+    // ({ total, items }) to match BlocksApi's similarProducts contract.
+    async getSimilarProducts(marker, langCode = this.state.lang, offset = 0, limit = 30) {
+        // Fetch similar products from the server
+        const result = await this._fetchGet(`/${marker}/similar-products?langCode=${langCode}&offset=${offset}&limit=${limit}`);
+        return this._normalizeData(result);
+    }
+    // Method to fetch products by block marker
+    async getProductsByBlockMarker(marker, langCode = this.state.lang, offset = 0, limit = 30) {
+        // Fetch products from the server
+        const result = await this._fetchGet(`/${marker}/products?langCode=${langCode}&offset=${offset}&limit=${limit}`);
+        // On API error responses there is no `items` array — return the (normalized)
+        // error as-is instead of producing `undefined` from `result.items`.
+        if (!Array.isArray(result === null || result === void 0 ? void 0 : result.items)) {
+            return this._normalizeData(result);
+        }
+        return this._normalizeData(result.items);
+    }
+}