oneentry 1.0.176 → 1.0.177

package/dist/base/syncModules.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports._warnGuestId = _warnGuestId;
 // localStorage keys for the persistent browser-side identifiers.
 const _DEVICE_ID_STORAGE_KEY = 'oneentry_device_id';
 const _GUEST_ID_STORAGE_KEY = 'oneentry_guest_id';
@@ -11,31 +12,46 @@ const _persistentIds = {};
  *
  * Prefers a cryptographically secure source (Web Crypto, exposed as
  * `globalThis.crypto` in browsers and Node.js >= 18): `randomUUID()` when
- * available, otherwise random bytes rendered as a base-36 string. Falls back to
- * a timestamp + `Math.random()` only when no CSPRNG exists (e.g. very old Node).
- *
- * The result contains no special characters, so it is safe to use both in
- * localStorage and in HTTP headers.
- * @returns {string} A freshly generated identifier.
+ * available, otherwise a UUID v4 built from `getRandomValues`, and from
+ * `Math.random()` only when no CSPRNG exists (e.g. very old Node).
+ * @returns {string} A freshly generated UUID v4.
  */
 function _generateId() {
     const cryptoObj = typeof globalThis !== 'undefined' ? globalThis.crypto : undefined;
     if (cryptoObj === null || cryptoObj === void 0 ? void 0 : cryptoObj.randomUUID) {
         return cryptoObj.randomUUID();
     }
+    // `randomUUID` is missing on pages served over plain http (not a secure context): the id
+    // must still be a UUID v4 — the platform silently replaces any other guest id on every
+    // request, and the guest cart was lost
+    const bytes = new Uint8Array(16);
     if (cryptoObj === null || cryptoObj === void 0 ? void 0 : cryptoObj.getRandomValues) {
-        const bytes = cryptoObj.getRandomValues(new Uint8Array(18));
-        let result = '';
+        cryptoObj.getRandomValues(bytes);
+    }
+    else {
+        // Last-resort fallback for environments without Web Crypto: non-cryptographic.
         for (let i = 0; i < bytes.length; i++) {
-            result += bytes[i].toString(36).padStart(2, '0');
+            bytes[i] = Math.floor(Math.random() * 256);
         }
-        return result;
     }
-    // Last-resort fallback for environments without Web Crypto.
-    // Non-cryptographic, but adequate when nothing better is available.
-    return (Date.now().toString(36) +
-        Math.random().toString(36).substring(2, 15) +
-        Math.random().toString(36).substring(2, 15));
+    bytes[6] = (bytes[6] & 0x0f) | 0x40;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+/**
+ * The UUID v4 shape the platform requires of a guest id (it replaces any other value).
+ */
+const _UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+/**
+ * Warns about a caller's guest id the platform will not keep.
+ * @param {string | undefined} guestId - The id passed in config or to `setGuestId`.
+ */
+function _warnGuestId(guestId) {
+    if (guestId && !_UUID.test(guestId)) {
+        // eslint-disable-next-line no-undef, no-console
+        console.warn('OneEntry SDK: guestId must be a UUID v4 — the platform replaces any other value on every request, and the guest cart is lost');
+    }
 }
 /**
  * Returns a stable identifier for the browser environment, persisted in localStorage.
@@ -59,7 +75,9 @@ function _getPersistentBrowserId(storageKey) {
         return _persistentIds[storageKey];
     try {
         const stored = win.localStorage.getItem(storageKey);
-        if (stored) {
+        // A guest id stored by an older SDK may not be a UUID: replace it, the platform ignores it
+        if (stored &&
+            (storageKey !== _GUEST_ID_STORAGE_KEY || _UUID.test(stored))) {
             _persistentIds[storageKey] = stored;
             return _persistentIds[storageKey];
         }
@@ -79,6 +97,21 @@ function _getPersistentBrowserId(storageKey) {
     }
     return _persistentIds[storageKey];
 }
+/**
+ * Attribute types for which the API's `""` means "not set": none of them has an empty-string value.
+ */
+const EMPTY_STRING_UNSET_TYPES = new Set([
+    'image',
+    'groupOfImages',
+    'file',
+    'timeInterval',
+    'date',
+    'dateTime',
+    'time',
+    'list',
+    'radioButton',
+    'entity',
+]);
 /**
  * Abstract class representing synchronization modules.
  */
@@ -104,7 +137,12 @@ class SyncModules {
             : Object.fromEntries(Object.entries(data).sort(([, a], [, b]) => a.position - b.position));
         this.state = state;
         this._url = state.url;
-        this._nodeDeviceId = _generateId();
+        // Fallback device ID for Node.js and cases where localStorage is unavailable.
+        // Kept on the shared state, so every module of one client sends the same one:
+        // generated per module, the token issued by AuthProvider was refreshed from
+        // another module with another fingerprint and answered `400 Provided token is incorrect`.
+        if (!state.nodeDeviceId)
+            state.nodeDeviceId = _generateId();
     }
     /**
      * Resolves the guest identifier for the current request, or `undefined`.
@@ -268,9 +306,26 @@ class SyncModules {
      * numeric branch already produced.
      * 3. **Numbers** (`integer`, `float`, `real`) — cast to a JS number; anything
      * that is not a number (including an empty value) becomes `null`.
+     * 4. **Empty strings** of non-text types (`image`, `groupOfImages`, `file`,
+     * `timeInterval`, `date`, `dateTime`, `time`) — the API sends an unset value as
+     * `""`; it is replaced with `null`. For text types `""` is a real value and stays.
      * @param {any} attr - The attribute object to normalize in place.
+     * @param {boolean} [isEntityValue] - The attribute is a value of an entity (`attributeValues`): one without a `value` key is unset and gets `null`. Form fields and attribute-set schemas describe a field and get no key.
      */
-    _normalizeAttrValue(attr) {
+    _normalizeAttrValue(attr, isEntityValue = false) {
+        // A non-object entry is not an attribute: leave it as it is instead of throwing
+        if (!attr || typeof attr !== 'object')
+            return;
+        // Only an attribute (it has a `type`): a locale map left by a missing translation is not one
+        if (isEntityValue && 'type' in attr && !('value' in attr)) {
+            attr.value = null;
+        }
+        // Only for entity values: form data of orders and users types these fields without `null`
+        if (isEntityValue &&
+            attr.value === '' &&
+            EMPTY_STRING_UNSET_TYPES.has(attr.type)) {
+            attr.value = null;
+        }
         if ((attr.type === 'image' || attr.type === 'file') &&
             Array.isArray(attr.value) &&
             attr.value.length === 1) {
@@ -283,9 +338,11 @@ class SyncModules {
             Object.keys(attr.value).length === 0) {
             attr.value = null;
         }
-        if (attr.type === 'integer' ||
+        if ((attr.type === 'integer' ||
             attr.type === 'float' ||
-            attr.type === 'real') {
+            attr.type === 'real') &&
+            // A form attribute describes a field and carries no `value` key — don't add one
+            'value' in attr) {
             // Number(null) is 0 and Number('') is 0 — an empty value must stay empty.
             const isEmpty = attr.value === null || attr.value === undefined || attr.value === '';
             const numValue = isEmpty ? NaN : Number(attr.value);
@@ -303,7 +360,7 @@ class SyncModules {
      * @param {any} attr - The attribute object that may contain additionalFields.
      */
     _normalizeAdditionalFields(attr) {
-        if (!this.state.rawData && Array.isArray(attr.additionalFields)) {
+        if (attr && !this.state.rawData && Array.isArray(attr.additionalFields)) {
             attr.additionalFields = Object.fromEntries(attr.additionalFields.map((field) => [field.marker, field]));
         }
     }
@@ -343,10 +400,17 @@ class SyncModules {
     _normalizeAttr(data) {
         // For regular attributes collections - pages, products, etc.
         if ('attributeValues' in data) {
+            // `null` (or any non-object) is not a collection: `Object.keys(null)` threw past
+            // isShell and took a whole list down with one record
+            if (!data.attributeValues ||
+                typeof data.attributeValues !== 'object' ||
+                Array.isArray(data.attributeValues)) {
+                return data;
+            }
             Object.keys(data.attributeValues).forEach((attr) => {
                 const d = data.attributeValues[attr];
                 this._normalizeAdditionalFields(d);
-                this._normalizeAttrValue(d);
+                this._normalizeAttrValue(d, true);
             });
             return {
                 ...data,
@@ -363,6 +427,9 @@ class SyncModules {
         // for forms attributes - forms attributes collections
         if ('attributes' in data) {
             const d = data.attributes;
+            if (!d || typeof d !== 'object') {
+                return data;
+            }
             // A form with no attributes arrives as an empty object `{}` — normalize
             // it to an empty array, the container every non-empty form uses.
             if (d &&
@@ -375,7 +442,10 @@ class SyncModules {
                 this._normalizeAdditionalFields(d[attr]);
                 this._normalizeAttrValue(d[attr]);
                 for (const field of booleanFields) {
-                    if (field in d[attr] && d[attr][field] === null) {
+                    if (d[attr] &&
+                        typeof d[attr] === 'object' &&
+                        field in d[attr] &&
+                        d[attr][field] === null) {
                         d[attr][field] = false;
                     }
                 }
@@ -397,7 +467,7 @@ class SyncModules {
     /**
      * Sets the access token in the state.
      * @param {string} accessToken - The access token to set.
-     * @returns {any} The instance of SyncModules for chaining.
+     * @returns {this} The same module, for chaining.
      */
     setAccessToken(accessToken) {
         this.state.accessToken = accessToken;
@@ -406,7 +476,7 @@ class SyncModules {
     /**
      * Sets the refresh token in the state.
      * @param {string} refreshToken - The refresh token to set.
-     * @returns {any} The instance of SyncModules for chaining.
+     * @returns {this} The same module, for chaining.
      */
     setRefreshToken(refreshToken) {
         this.state.refreshToken = refreshToken;
@@ -420,9 +490,10 @@ class SyncModules {
      * (the SDK then falls back to the localStorage-backed id in the browser, or to
      * no guest id at all on the server).
      * @param {string} guestId - The guest identifier to set (empty string clears it).
-     * @returns {any} The instance of SyncModules for chaining.
+     * @returns {this} The same module, for chaining.
      */
     setGuestId(guestId) {
+        _warnGuestId(guestId);
         this.state.guestId = guestId || undefined;
         return this;
     }
@@ -436,7 +507,7 @@ class SyncModules {
      * browser's string (obtained there via `getDeviceMetadata`). Pass an empty
      * string to clear the override and fall back to the computed fingerprint.
      * @param {string} deviceMetadata - The metadata string to send (empty string clears the override).
-     * @returns {any} The instance of SyncModules for chaining.
+     * @returns {this} The same module, for chaining.
      */
     setDeviceMetadata(deviceMetadata) {
         this.state.deviceMetadata = deviceMetadata || undefined;
@@ -477,7 +548,7 @@ class SyncModules {
      *
      * **instanceId strategy:**
      * - Browser: `_getPersistentBrowserId('oneentry_device_id')` — read from localStorage, stable across sessions.
-     * - Node.js / no localStorage: `_nodeDeviceId` — generated at instance creation,
+     * - Node.js / no localStorage: `state.nodeDeviceId` — generated once per client (shared by its modules),
      * lives until the process restarts.
      *
      * In a Node.js environment (no `window`) returns a simplified object without screen/navigator.
@@ -499,7 +570,7 @@ class SyncModules {
         }
         // Access navigator through globalThis.window object to avoid direct reference
         const win = globalThis.window;
-        const instanceId = (_a = _getPersistentBrowserId(_DEVICE_ID_STORAGE_KEY)) !== null && _a !== void 0 ? _a : this._nodeDeviceId;
+        const instanceId = (_a = _getPersistentBrowserId(_DEVICE_ID_STORAGE_KEY)) !== null && _a !== void 0 ? _a : this.state.nodeDeviceId;
         // Node.js environment
         if (!win) {
             return JSON.stringify({

package/dist/base/utils.d.ts

@@ -1,21 +1,26 @@
 /**
  * @interface IConfig
- * @property {string} [token] - If your project is protected by a token, specify this token in this parameter.
- * @property {string} [guestId] - Guest identifier sent as the `x-guest-id` header on unauthenticated requests. Lets cart/wishlist/activity endpoints work for a guest. In the browser a stable id is auto-generated (localStorage) when omitted; on the server pass a per-visitor id. Can also be set later via `setGuestId`.
+ * @property {string} token - App token of the project. Required: `defineOneEntry` throws without it.
+ * @property {string} [guestId] - Guest identifier sent as the `x-guest-id` header on unauthenticated requests. Must be a UUID v4 — the platform replaces any other value with a new id on every request, so a guest cart is silently lost. Lets cart/wishlist/activity endpoints work for a guest. In the browser a stable id is auto-generated (localStorage) when omitted; on the server pass a per-visitor id. Can also be set later via `setGuestId`.
  * @property {string} [deviceMetadata] - Device-metadata string sent as the `x-device-metadata` header on POST requests and token refresh, overriding the environment-derived fingerprint. The API binds refresh tokens to this header, so server-side flows that issue tokens on behalf of a browser (e.g. an OAuth code exchange) must pass the browser's string here — otherwise the token is bound to the server's fingerprint and cannot be refreshed from the browser. Obtain the string in the browser via `getDeviceMetadata()`. Can also be set later via `setDeviceMetadata`.
- * @property {string} [langCode] - specify the default language to avoid specifying it in every request.
+ * @property {string} [langCode] - specify the default language to avoid specifying it in every request. Default: 'en_US' (an empty string counts as not set).
  * @property {boolean} [traficLimit] - Some methods use multiple queries to make it easier to work with the API. Set it to `true` to save traffic and decide for yourself what data you need: the SDK then skips its follow-up requests (full pages behind quick search results, products of page blocks), and some results change shape — e.g. `searchPage` returns short `{ id, title }` cards. Default: false.
  * @property {boolean} [rawData] - Set to true to keep an attribute's nested `additionalFields` as the
  * array the API sends, instead of the marker-keyed map the SDK builds by default. It turns off only that
  * transformation — locale unwrapping, sorting by `position`, single-file unwrapping and number casting
  * still apply. `getAdditionalFields` returns the same marker map in either mode.
- * @property {object} [validation] - Validation settings for API responses.
- * @property {boolean} [auth] - An object with authorization settings.
+ * @property {object} [validation] - Validation of API responses against the SDK's Zod schemas. Off by default; Zod is loaded only when it is on.
+ * @property {boolean} [validation.enabled] - Turns validation on. Default: false. `strictMode` and `logErrors` take effect only together with it.
+ * @property {boolean} [validation.strictMode] - With validation enabled, a response that does not match its schema is returned as an `IError` with `statusCode: 422` instead of the data. Default: false (mismatches are only logged). The data itself is never altered by validation.
+ * @property {boolean} [validation.logErrors] - With validation enabled, logs schema mismatches to the console. Default: true.
+ * @property {object} [auth] - An object with authorization settings.
  * @property {boolean} [auth.customAuth] - Set this flag to true if you want to configure the authorization process yourself. Set the flag to false, or do not pass it at all to have automatic authorization and token renewal.
- * @property {boolean} [auth.refreshToken] - Transfer the refresh token here, for example from the local storage, to resume the user's session. Otherwise, the user will need to log in every time a new session is created.
- * @property {boolean} [auth.providerMarker] - The marker of the provider, for example, email, google, facebook, etc. Default 'email';
- * @property {boolean} [auth.saveFunction] - If you want to store the token between sessions, for example in local storage, create a custom function that takes refreshToken as a parameter and executes the necessary instructions. This function will be called every time the tokens are updated.
+ * @property {string | null} [auth.refreshToken] - Transfer the refresh token here, for example from the local storage, to resume the user's session. Otherwise, the user will need to log in every time a new session is created. The API binds a refresh token to the device fingerprint sent in `x-device-metadata`: on the server (Node.js, SSR) every `defineOneEntry` call gets a new random fingerprint, so store `getDeviceMetadata()` next to the refresh token and pass it back as `deviceMetadata`, or the refresh is rejected with `400 Provided token is incorrect`.
+ * @property {string} [auth.providerMarker] - The marker of the provider used to refresh a restored session, for example, email, google, facebook, etc. Default 'email'. After `AuthProvider.auth`/`oauth`/`refresh` the marker of that call is used.
+ * @property {function(string): void} [auth.saveFunction] - If you want to store the token between sessions, for example in local storage, create a custom function that takes refreshToken as a parameter and executes the necessary instructions. This function will be called every time the tokens are updated.
  * @property {object} [errors] - Error handling settings.
+ * @property {boolean} [errors.isShell] - `true` (default): a failed request resolves to an `IError` object instead of throwing. `false`: the `IError` is thrown (a request that got no answer throws an `IError` with `statusCode: 0` and the original error in `cause`).
+ * @property {object} [errors.customErrors] - Handlers called with the `IError` of a failed request, keyed by HTTP status. Supported codes: 400, 401, 403, 404, 429, 500, 502, 503, 504. A handler may be async (it is awaited); an exception it throws (e.g. Next.js `redirect()`/`notFound()`) reaches the caller.
  * @example
  * ```ts
  * const saveToken = (token) => {
@@ -46,7 +51,7 @@
  * ```
  */
 interface IConfig {
-    token?: string;
+    token: string;
     guestId?: string;
     deviceMetadata?: string;
     langCode?: string;
@@ -59,22 +64,22 @@ interface IConfig {
     };
     auth?: {
         customAuth?: boolean;
-        refreshToken?: string;
+        refreshToken?: string | null;
         providerMarker?: string;
         saveFunction?: (refreshToken: string) => void;
     };
     errors?: {
         isShell?: boolean;
         customErrors?: {
-            400?: (data?: IError) => unknown;
-            401?: (data?: IError) => unknown;
-            403?: (data?: IError) => unknown;
-            404?: (data?: IError) => unknown;
-            429?: (data?: IError) => unknown;
-            500?: (data?: IError) => unknown;
-            502?: (data?: IError) => unknown;
-            503?: (data?: IError) => unknown;
-            504?: (data?: IError) => unknown;
+            400?: (data: IError) => unknown;
+            401?: (data: IError) => unknown;
+            403?: (data: IError) => unknown;
+            404?: (data: IError) => unknown;
+            429?: (data: IError) => unknown;
+            500?: (data: IError) => unknown;
+            502?: (data: IError) => unknown;
+            503?: (data: IError) => unknown;
+            504?: (data: IError) => unknown;
         };
     };
 }
@@ -399,7 +404,7 @@ interface IRating {
 /**
  * @interface IError
  * @property {string} message - Error message.
- * @property {unknown} pageData - Page data.
+ * @property {unknown} [pageData] - Page data; `null` on most errors. Absent on the errors of the subscriptions module and of `/files/search` (CMS-1177).
  * @property {number} statusCode - Status code.
  * @property {string} timestamp - Timestamp.
  * @property {string} [localizeMessage] - Human-readable localized error message; populated by the SDK when response validation fails. Optional.
@@ -408,7 +413,7 @@ interface IRating {
  */
 interface IError {
     message: string;
-    pageData: unknown;
+    pageData?: unknown;
     statusCode: number;
     timestamp: string;
     localizeMessage?: string;

package/dist/base/validation.d.ts

@@ -17,7 +17,7 @@ export declare const ErrorSchema: z.ZodObject<{
 export declare const LocalizeInfoSchema: z.ZodObject<{
     title: z.ZodString;
     content: z.ZodOptional<z.ZodString>;
-    menuTitle: z.ZodOptional<z.ZodString>;
+    menuTitle: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
 /**
  * Attribute schema
@@ -32,7 +32,7 @@ export declare const AttributeSchema: z.ZodObject<{
     localizeInfos: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         title: z.ZodString;
         content: z.ZodOptional<z.ZodString>;
-        menuTitle: z.ZodOptional<z.ZodString>;
+        menuTitle: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     }, z.core.$strip>>>;
     value: z.ZodOptional<z.ZodAny>;
 }, z.core.$strip>;
@@ -125,6 +125,6 @@ export declare function validateResponse<T>(schema: z.ZodSchema<T>, data: unknow
  * @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
+ * @returns {T} The original data, whether or not it passed validation
  */
 export declare function validateResponseSafe<T>(schema: z.ZodSchema<T>, data: unknown, logErrors?: boolean): T;

package/dist/base/validation.js

@@ -24,7 +24,8 @@ exports.ErrorSchema = zod_1.z.object({
 exports.LocalizeInfoSchema = zod_1.z.object({
     title: zod_1.z.string(),
     content: zod_1.z.string().optional(),
-    menuTitle: zod_1.z.string().optional(),
+    // `string | null` as in ILocalizeInfo
+    menuTitle: zod_1.z.string().nullable().optional(),
 });
 /**
  * Attribute schema
@@ -211,13 +212,11 @@ function validateResponse(schema, data, options) {
  * @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
+ * @returns {T} The original data, whether or not it passed validation
  */
 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
+    validateResponse(schema, data, { logErrors });
+    // Always return the original data: Zod objects strip keys the schema does
+    // not describe, and the result must not depend on whether validation is on
     return data;
 }

package/dist/blocks/blocksApi.d.ts

@@ -21,7 +21,7 @@ export default class BlocksApi extends AsyncModules implements IBlocks {
     /**
      * 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" | "frequently_ordered_block" | "trending_block" | "recently_viewed_block" | "repeat_purchase_block" | "slider_block" | "personal_recommendations_block" | "cart_complement_block" | "cart_similar_block" | "wishlist_similar_block" | "form" | "common_page" | "common_block" | "order" | "service" | "external_page" | "discount" (see BlockType). When omitted, blocks of all types are returned. Example: 'product'.
+     * @param {BlockType} [type] - Optional block type to filter by. Available values: "product" | "error_page" | "catalog_page" | "product_preview" | "similar_products_block" | "product_block" | "frequently_ordered_block" | "trending_block" | "recently_viewed_block" | "repeat_purchase_block" | "slider_block" | "personal_recommendations_block" | "cart_complement_block" | "cart_similar_block" | "wishlist_similar_block" | "form" | "common_page" | "common_block" | "order" | "service" | "external_page" | "discount" (see BlockType). When omitted, blocks of all types are returned. A type no block has (e.g. "product", which is a product type, not a block type) gives an empty list, not an error. Example: 'product_block'.
      * @param {string} [langCode] - Language code. Default: "en_US".
      * @param {number} [offset] - Number of records to skip. Default: 0.
      * @param {number} [limit] - Maximum number of records to return. Default: 30.
@@ -44,21 +44,26 @@ export default class BlocksApi extends AsyncModules implements IBlocks {
      */
     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.
+     * Lifts the product display settings of a block to top-level fields and drops internal ones.
+     * @param {any} block - A block as the API sent it.
+     * @description `customSettings.productConfig` holds `countElementsPerRow` and `quantity`
+     * as strings; they become numbers on the block. `customSettings`, `attributeSetIdentifier`
+     * and `productPageUrls` are internal and removed — in traffic-saving mode as well, which
+     * used to return them as they came; the set marker was misspelt (`attributesSetIdentifier`)
+     * and stayed in every block.
      */
-    private _enrichBlock;
+    private _liftBlockSettings;
+    /**
+     * Attaches the products of a product or similar-products block.
+     * @param {any} block - A normalized block.
+     * @param {string} langCode - Language of the products.
+     * @param {number} [offset] - Products to skip.
+     * @param {number} [limit] - Products to return.
+     * @description A failed sub-request leaves an empty value of the declared type —
+     * `{ items: [], total: 0 }` for `similarProducts`, `[]` for `products` — instead of
+     * the error object or an array where a container is declared.
+     */
+    private _loadBlockProducts;
     /**
      * Get similar products by block marker.
      * @handleName getSimilarProducts
@@ -71,7 +76,6 @@ export default class BlocksApi extends AsyncModules implements IBlocks {
      * @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;
     /**
@@ -85,7 +89,6 @@ export default class BlocksApi extends AsyncModules implements IBlocks {
      * @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;
     /**