oneentry 1.0.159 → 1.0.161

package/esm/base/validation.d.ts

@@ -0,0 +1,98 @@
+import { z } from 'zod';
+/**
+ * Common validation schemas for API responses
+ * @description Base schemas that can be reused across different modules
+ */
+/**
+ * Error response schema
+ */
+export declare const ErrorSchema: z.ZodObject<{
+    statusCode: z.ZodNumber;
+    message: z.ZodString;
+    localizeMessage: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Localize info schema
+ */
+export declare const LocalizeInfoSchema: z.ZodObject<{
+    title: z.ZodString;
+    content: z.ZodOptional<z.ZodString>;
+    menuTitle: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Attribute schema
+ */
+export declare const AttributeSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodNumber>;
+    marker: z.ZodString;
+    type: z.ZodString;
+    isVisible: z.ZodOptional<z.ZodBoolean>;
+    isRequired: z.ZodOptional<z.ZodBoolean>;
+    position: z.ZodOptional<z.ZodNumber>;
+    localizeInfos: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        title: z.ZodString;
+        content: z.ZodOptional<z.ZodString>;
+        menuTitle: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    value: z.ZodOptional<z.ZodAny>;
+}, z.core.$strip>;
+/**
+ * User entity schema
+ */
+export declare const UserEntitySchema: z.ZodObject<{
+    id: z.ZodNumber;
+    identifier: z.ZodString;
+    authProviderIdentifier: z.ZodString;
+    formData: z.ZodUnion<readonly [z.ZodArray<z.ZodAny>, z.ZodRecord<z.ZodString, z.ZodAny>]>;
+    formIdentifier: z.ZodString;
+    total: z.ZodString;
+    groups: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    state: z.ZodRecord<z.ZodString, z.ZodAny>;
+    moduleFormConfigs: z.ZodOptional<z.ZodArray<z.ZodAny>>;
+    rating: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+/**
+ * Auth entity schema
+ * API returns only accessToken and refreshToken
+ * userIdentifier and authProviderIdentifier are optional legacy fields
+ */
+export declare const AuthEntitySchema: z.ZodObject<{
+    userIdentifier: z.ZodString;
+    authProviderIdentifier: z.ZodString;
+    accessToken: z.ZodString;
+    refreshToken: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Paginated response schema factory
+ * @param {T} itemSchema - The schema for each item in the paginated response
+ * @returns {any} Paginated response schema
+ */
+export declare function createPaginatedSchema<T extends z.ZodTypeAny>(itemSchema: T): any;
+/**
+ * Validation helper function
+ * @param {z.ZodSchema<T>} schema - Zod schema to validate against
+ * @param {unknown} data - Data to validate
+ * @param {object} options - Validation options
+ * @param {boolean} options.strict - Whether to use strict mode
+ * @param {boolean} options.logErrors - Whether to log errors
+ * @returns {object} Validated data or error
+ */
+export declare function validateResponse<T>(schema: z.ZodSchema<T>, data: unknown, options?: {
+    strict?: boolean;
+    logErrors?: boolean;
+}): {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: z.ZodError;
+};
+/**
+ * Safe validation helper - returns data even if validation fails
+ * Used when strict mode is disabled
+ * @param {z.ZodSchema<T>} schema - Zod schema to validate against
+ * @param {unknown} data - Data to validate
+ * @param {boolean} logErrors - Whether to log errors
+ * @returns {T} Validated data or original data if validation fails in non-strict mode
+ */
+export declare function validateResponseSafe<T>(schema: z.ZodSchema<T>, data: unknown, logErrors?: boolean): T;

package/esm/base/validation.js

@@ -0,0 +1,118 @@
+/* eslint-disable jsdoc/reject-any-type */
+import { z } from 'zod';
+/**
+ * Common validation schemas for API responses
+ * @description Base schemas that can be reused across different modules
+ */
+/**
+ * Error response schema
+ */
+export const ErrorSchema = z.object({
+    statusCode: z.number(),
+    message: z.string(),
+    localizeMessage: z.string().optional(),
+});
+/**
+ * Localize info schema
+ */
+export const LocalizeInfoSchema = z.object({
+    title: z.string(),
+    content: z.string().optional(),
+    menuTitle: z.string().optional(),
+});
+/**
+ * Attribute schema
+ */
+export const AttributeSchema = z.object({
+    id: z.number().optional(),
+    marker: z.string(),
+    type: z.string(),
+    isVisible: z.boolean().optional(),
+    isRequired: z.boolean().optional(),
+    position: z.number().optional(),
+    localizeInfos: z.record(z.string(), LocalizeInfoSchema).optional(),
+    value: z.any().optional(),
+});
+/**
+ * User entity schema
+ */
+export const UserEntitySchema = z.object({
+    id: z.number(),
+    identifier: z.string(),
+    authProviderIdentifier: z.string(),
+    formData: z.union([z.array(z.any()), z.record(z.string(), z.any())]),
+    formIdentifier: z.string(),
+    total: z.string(),
+    groups: z.array(z.union([z.string(), z.number()])),
+    state: z.record(z.string(), z.any()),
+    moduleFormConfigs: z.array(z.any()).optional(),
+    rating: z.record(z.string(), z.unknown()).optional(),
+});
+/**
+ * Auth entity schema
+ * API returns only accessToken and refreshToken
+ * userIdentifier and authProviderIdentifier are optional legacy fields
+ */
+export const AuthEntitySchema = z.object({
+    userIdentifier: z.string(),
+    authProviderIdentifier: z.string(),
+    accessToken: z.string(),
+    refreshToken: z.string(),
+});
+/**
+ * Paginated response schema factory
+ * @param {T} itemSchema - The schema for each item in the paginated response
+ * @returns {any} Paginated response schema
+ */
+export function createPaginatedSchema(itemSchema) {
+    return z.object({
+        items: z.array(itemSchema),
+        total: z.number(),
+        page: z.number().optional(),
+        limit: z.number().optional(),
+    });
+}
+/**
+ * Validation helper function
+ * @param {z.ZodSchema<T>} schema - Zod schema to validate against
+ * @param {unknown} data - Data to validate
+ * @param {object} options - Validation options
+ * @param {boolean} options.strict - Whether to use strict mode
+ * @param {boolean} options.logErrors - Whether to log errors
+ * @returns {object} Validated data or error
+ */
+export function validateResponse(schema, data, options) {
+    try {
+        const validated = schema.parse(data);
+        return { success: true, data: validated };
+    }
+    catch (error) {
+        if (error instanceof z.ZodError) {
+            if (options === null || options === void 0 ? void 0 : options.logErrors) {
+                // eslint-disable-next-line no-undef, no-console
+                console.error('Validation error:', {
+                    errors: error.issues,
+                    data,
+                });
+            }
+            return { success: false, error };
+        }
+        throw error;
+    }
+}
+/**
+ * Safe validation helper - returns data even if validation fails
+ * Used when strict mode is disabled
+ * @param {z.ZodSchema<T>} schema - Zod schema to validate against
+ * @param {unknown} data - Data to validate
+ * @param {boolean} logErrors - Whether to log errors
+ * @returns {T} Validated data or original data if validation fails in non-strict mode
+ */
+export function validateResponseSafe(schema, data, logErrors = false) {
+    const result = validateResponse(schema, data, { logErrors });
+    if (result.success) {
+        return result.data;
+    }
+    // Return original data if validation fails in non-strict mode
+    return data;
+}

package/esm/blocks/blocksApi.d.ts

@@ -0,0 +1,252 @@
+import AsyncModules from '../base/asyncModules.js';
+import type StateModule from '../base/stateModule.js';
+import type { IError } from '../base/utils.js';
+import type { IProductsResponse } from '../products/productsInterfaces.js';
+import type { BlockType, IBlockEntity, IBlockProductsLookup, IBlocks, IBlockSlidesResponse, IBlocksResponse, ISearchBlock } from './blocksInterfaces.js';
+/**
+ * Controllers for working with blocks.
+ * @handle /api/content/blocks
+ * @class BlocksApi
+ * @augments AsyncModules
+ * @implements {IBlocks}
+ * @description This class provides methods to interact with blocks.
+ */
+export default class BlocksApi extends AsyncModules implements IBlocks {
+    protected state: StateModule;
+    protected _url: string;
+    /**
+     * Constructor for BlocksApi class.
+     */
+    constructor(state: StateModule);
+    /**
+     * Get blocks by parameters.
+     * @handleName getBlocks
+     * @param {BlockType} [type] - Optional block type to filter by. Available values: "product" | "error_page" | "catalog_page" | "product_preview" | "similar_products_block" | "product_block" | "form" | "common_page" | "common_block" | "order" | "service" | "none". When omitted, blocks of all types are returned. Example: 'product'.
+     * @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<IBlocksResponse | IError>} Returns BlocksEntity object.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @see {@link https://js-sdk.oneentry.cloud/docs/blocks/getBlocks getBlocks} documentation.
+     */
+    getBlocks(type?: BlockType, langCode?: string, offset?: number, limit?: number): Promise<IBlocksResponse | IError>;
+    /**
+     * Get block by marker.
+     * @handleName getBlockByMarker
+     * @param {string} marker - Marker of Block. Example: "product_block".
+     * @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<IBlockEntity | IError>} - Returns a BlockEntity object.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description This method retrieves a block by its marker and includes additional information such as similar products or products associated with the block.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/blocks/getBlockByMarker getBlockByMarker} documentation.
+     */
+    getBlockByMarker(marker: string, langCode?: string, offset?: number, limit?: number): Promise<IBlockEntity | IError>;
+    /**
+     * Enrich a single block in place.
+     *
+     * Lifts product display settings from `customSettings.productConfig` to
+     * numeric top-level fields, strips internal-only fields, and — when
+     * `loadProducts` is true — fetches the related products for
+     * `similar_products_block` / `product_block` blocks. Shared by `getBlocks`
+     * (array) and `getBlockByMarker` (single block). Mutates `block` in place.
+     * @param {any} block - Normalized block to enrich (mutated in place).
+     * @param {string} langCode - Language code passed to product sub-requests.
+     * @param {number} offset - Pagination offset for product sub-requests.
+     * @param {number} limit - Pagination limit for product sub-requests.
+     * @param {boolean} loadProducts - Whether to fetch related products.
+     * @returns {Promise<void>} Resolves when enrichment (incl. sub-requests) is done.
+     */
+    private _enrichBlock;
+    /**
+     * Get similar products by block marker.
+     * @handleName getSimilarProducts
+     * @param {string} marker - Block identifier. Example: "similar_products_block".
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @param {number} [offset] - Parameter for pagination. Default: 0.
+     * @param {number} [limit] - Parameter for pagination. Default: 30.
+     * @param {string} [signPrice] - Order storage marker for price fixing. If the parameter is set, the price is fixed for a certain time.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/blocks/#Fixing-the-price-signPrice Fixing the price} documentation.
+     * @param {number} [productId] - Optional product id to find similar products for.
+     * @returns {Promise<IProductsResponse | IError>} Returns the total count and an array of product items in object by specified block marker.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @see {@link https://js-sdk.oneentry.cloud/docs/blocks/getSimilarProducts getSimilarProducts} documentation.
+     */
+    private getSimilarProducts;
+    /**
+     * Get products by block marker.
+     * @handleName getProductsByBlockMarker
+     * @param {string} marker - Block identifier. Example: "product_block".
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @param {number} [offset] - Parameter for pagination. Default: 0.
+     * @param {number} [limit] - Parameter for pagination. Default: 30.
+     * @param {string} [signPrice] - Order storage marker for price fixing. If the parameter is set, the price is fixed for a certain time.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/blocks/#Fixing-the-price-signPrice Fixing the price} documentation.
+     * @returns {Promise<IProductsEntity[] | IError>} Return array of BlocksEntity object.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @see {@link https://js-sdk.oneentry.cloud/docs/blocks/getProductsByBlockMarker getProductsByBlockMarker} documentation.
+     */
+    private getProductsByBlockMarker;
+    /**
+     * Get frequently ordered products by block marker and product id.
+     * @handleName getFrequentlyOrderedProducts
+     * @param {number} productId - Product id. Example: 1.
+     * @param {string} marker - Block marker. Example: "frequently_ordered_block".
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @param {string} [signPrice] - Order storage marker for price fixing. If the parameter is set, the price is fixed for a certain time.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/blocks/#Fixing-the-price-signPrice Fixing the price} documentation.
+     * @returns {Promise<IProductsResponse | IError>} Returns a products response with items and total.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @see {@link https://js-sdk.oneentry.cloud/docs/blocks/getFrequentlyOrderedProducts getFrequentlyOrderedProducts} documentation.
+     */
+    getFrequentlyOrderedProducts(productId: number, marker: string, langCode?: string, signPrice?: string): Promise<IProductsResponse | IError>;
+    /**
+     * Quick search for block objects with limited output.
+     * @handleName searchBlock
+     * @param {string} name - Search string. Example: "product_block".
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @returns {Promise<ISearchBlock[] | IError>} Returns an array of ISearchBlock objects.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @see {@link https://js-sdk.oneentry.cloud/docs/blocks/searchBlock searchBlock} documentation.
+     */
+    searchBlock(name: string, langCode?: string): Promise<ISearchBlock[] | IError>;
+    /**
+     * Get "complete your cart" products by the cart from context (auth user or guest).
+     * @handleName getCartComplement
+     * @param {string} marker - Block marker. Example: "cart_complement_block".
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @param {string} [signPrice] - Order storage marker for price fixing. If the parameter is set, the price is fixed for a certain time.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/blocks/#Fixing-the-price-signPrice Fixing the price} documentation.
+     * @returns {Promise<IProductsResponse | IError>} Returns an object with an array of products, total count and totalFound.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @see {@link https://js-sdk.oneentry.cloud/docs/blocks/getCartComplement getCartComplement} documentation.
+     */
+    getCartComplement(marker: string, langCode?: string, signPrice?: string): Promise<IProductsResponse | IError>;
+    /**
+     * Get "complete your cart" products by an explicit list of productIds (POST body).
+     * @handleName getCartComplementByProductIds
+     * @param {string} marker - Block marker. Example: "cart_complement_block".
+     * @param {IBlockProductsLookup} body - Lookup body.
+     * @example
+        {
+          "productIds": [1, 2],
+          "langCode": "en_US"
+        }
+     * @returns {Promise<IProductsResponse | IError>} Returns an object with an array of products, total count and totalFound.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @see {@link https://js-sdk.oneentry.cloud/docs/blocks/getCartComplementByProductIds getCartComplementByProductIds} documentation.
+     */
+    getCartComplementByProductIds(marker: string, body: IBlockProductsLookup): Promise<IProductsResponse | IError>;
+    /**
+     * Get "similar to cart" products by the cart from context (auth user or guest).
+     * @handleName getCartSimilar
+     * @param {string} marker - Block marker. Example: "cart_similar_block".
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @param {string} [signPrice] - Order storage marker for price fixing. If the parameter is set, the price is fixed for a certain time.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/blocks/#Fixing-the-price-signPrice Fixing the price} documentation.
+     * @returns {Promise<IProductsResponse | IError>} Returns an object with an array of products, total count and totalFound.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @see {@link https://js-sdk.oneentry.cloud/docs/blocks/getCartSimilar getCartSimilar} documentation.
+     */
+    getCartSimilar(marker: string, langCode?: string, signPrice?: string): Promise<IProductsResponse | IError>;
+    /**
+     * Get "similar to cart" products by an explicit list of productIds (POST body).
+     * @handleName getCartSimilarByProductIds
+     * @param {string} marker - Block marker. Example: "cart_similar_block".
+     * @param {IBlockProductsLookup} body - Lookup body.
+     * @example
+        {
+          "productIds": [1, 2],
+          "langCode": "en_US"
+        }
+     * @returns {Promise<IProductsResponse | IError>} Returns an object with an array of products, total count and totalFound.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @see {@link https://js-sdk.oneentry.cloud/docs/blocks/getCartSimilarByProductIds getCartSimilarByProductIds} documentation.
+     */
+    getCartSimilarByProductIds(marker: string, body: IBlockProductsLookup): Promise<IProductsResponse | IError>;
+    /**
+     * Get personal recommendations for the user.
+     * @handleName getPersonalRecommendations
+     * @param {string} marker - Block marker. Example: "personal_recommendations_block".
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @param {string} [signPrice] - Order storage marker for price fixing. If the parameter is set, the price is fixed for a certain time.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/blocks/#Fixing-the-price-signPrice Fixing the price} documentation.
+     * @returns {Promise<IProductsResponse | IError>} Returns an object with an array of products, total count and totalFound.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @see {@link https://js-sdk.oneentry.cloud/docs/blocks/getPersonalRecommendations getPersonalRecommendations} documentation.
+     */
+    getPersonalRecommendations(marker: string, langCode?: string, signPrice?: string): Promise<IProductsResponse | IError>;
+    /**
+     * Get recently viewed products.
+     * @handleName getRecentlyViewed
+     * @param {string} marker - Block marker. Example: "recently_viewed_block".
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @param {string} [signPrice] - Order storage marker for price fixing. If the parameter is set, the price is fixed for a certain time.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/blocks/#Fixing-the-price-signPrice Fixing the price} documentation.
+     * @returns {Promise<IProductsResponse | IError>} Returns an object with an array of products, total count and totalFound.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @see {@link https://js-sdk.oneentry.cloud/docs/blocks/getRecentlyViewed getRecentlyViewed} documentation.
+     */
+    getRecentlyViewed(marker: string, langCode?: string, signPrice?: string): Promise<IProductsResponse | IError>;
+    /**
+     * Get products for repeat purchase.
+     * @handleName getRepeatPurchase
+     * @param {string} marker - Block marker. Example: "repeat_purchase_block".
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @param {string} [signPrice] - Order storage marker for price fixing. If the parameter is set, the price is fixed for a certain time.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/blocks/#Fixing-the-price-signPrice Fixing the price} documentation.
+     * @returns {Promise<IProductsResponse | IError>} Returns an object with an array of products, total count and totalFound.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @see {@link https://js-sdk.oneentry.cloud/docs/blocks/getRepeatPurchase getRepeatPurchase} documentation.
+     */
+    getRepeatPurchase(marker: string, langCode?: string, signPrice?: string): Promise<IProductsResponse | IError>;
+    /**
+     * Get the block's slides tree as a flat pre-order array (slider_block only).
+     * @handleName getSlides
+     * @param {string} marker - Block marker. Example: "slider_block".
+     * @returns {Promise<IBlockSlidesResponse | IError>} Returns the slides response.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @see {@link https://js-sdk.oneentry.cloud/docs/blocks/getSlides getSlides} documentation.
+     */
+    getSlides(marker: string): Promise<IBlockSlidesResponse | IError>;
+    /**
+     * Get trending products of the block.
+     * @handleName getTrending
+     * @param {string} marker - Block marker. Example: "trending_block".
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @param {string} [signPrice] - Order storage marker for price fixing. If the parameter is set, the price is fixed for a certain time.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/blocks/#Fixing-the-price-signPrice Fixing the price} documentation.
+     * @returns {Promise<IProductsResponse | IError>} Returns an object with an array of products, total count and totalFound.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @see {@link https://js-sdk.oneentry.cloud/docs/blocks/getTrending getTrending} documentation.
+     */
+    getTrending(marker: string, langCode?: string, signPrice?: string): Promise<IProductsResponse | IError>;
+    /**
+     * Get "similar to wishlist" products by the wishlist from context (auth user or guest).
+     * @handleName getWishlistSimilar
+     * @param {string} marker - Block marker. Example: "wishlist_similar_block".
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @param {string} [signPrice] - Order storage marker for price fixing. If the parameter is set, the price is fixed for a certain time.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/blocks/#Fixing-the-price-signPrice Fixing the price} documentation.
+     * @returns {Promise<IProductsResponse | IError>} Returns an object with an array of products, total count and totalFound.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @see {@link https://js-sdk.oneentry.cloud/docs/blocks/getWishlistSimilar getWishlistSimilar} documentation.
+     */
+    getWishlistSimilar(marker: string, langCode?: string, signPrice?: string): Promise<IProductsResponse | IError>;
+    /**
+     * Get "similar to wishlist" products by an explicit list of productIds (POST body).
+     * @handleName getWishlistSimilarByProductIds
+     * @param {string} marker - Block marker. Example: "wishlist_similar_block".
+     * @param {IBlockProductsLookup} body - Lookup body.
+     * @example
+        {
+          "productIds": [1, 2],
+          "langCode": "en_US"
+        }
+     * @returns {Promise<IProductsResponse | IError>} Returns an object with an array of products, total count and totalFound.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @see {@link https://js-sdk.oneentry.cloud/docs/blocks/getWishlistSimilarByProductIds getWishlistSimilarByProductIds} documentation.
+     */
+    getWishlistSimilarByProductIds(marker: string, body: IBlockProductsLookup): Promise<IProductsResponse | IError>;
+}