oneentry 1.0.156 → 1.0.157

package/changelog.md

@@ -1,5 +1,94 @@
 # SDK Change Log
 
+## v.1.0.157
+
+### What's New
+
+- Subscriptions > `ISubscriptionEntity` — new exported type describing an available subscription: `id`, `identifier`, `localizeInfos` (`ILocalizeInfo`), `productIds`, `periodInDays`, `paymentAccountId`, `isUsed`. It backs the corrected return type of `getAllSubscriptions` (see below) and has a matching Zod schema (`SubscriptionEntitySchema` / `SubscriptionsListSchema`).
+
+- Orders > `IOrderByMarkerEntity` — four fields the API already returns are now declared: `fulfillmentStatusIdentifier`, `fulfillmentStatusLocalizeInfos`, `paymentStatusIdentifier`, `paymentStatusLocalizeInfos` (each `null` until the corresponding status is assigned). Response validation drops every key its schema does not describe, so with `validation.enabled` these four were silently stripped from `getOrderByMarkerAndId` and `getAllOrdersByMarker` before reaching the consumer:
+
+  ```ts
+  const order = await Orders.getOrderByMarkerAndId('my_order', 179);
+  order.paymentStatusIdentifier; // "inProgress-payment"
+  order.paymentStatusLocalizeInfos; // { title: "In progress" }
+  ```
+
+- Orders > `IBaseOrdersEntity` — `statusLocalizeInfos` (localized name of the status assigned to the order) is now declared on the `createOrder` / `updateOrderByMarkerAndId` response, which returned it but had it stripped by validation.
+
+- IntegrationCollections > `ICollectionRow` — `langCode` and `formIdentifier` are now declared. Both are returned by the create/update row endpoints (`formIdentifier` on update) and were stripped by validation.
+
+- AuthProvider > `ISignUpEntity` — `attributeSetId` and `attributesSets` are now declared on the `signUp` response, which returned them but had them stripped by validation.
+
+- Products > `IProductSearchResult` and Pages > `IPageSearchResult` — new exported types describing the short card the quick search endpoints return: `{ id, title, pageId }` for products and `{ id, title }` for pages. Both have matching Zod schemas (`ProductSearchResultSchema` / `ProductSearchResponseSchema`, `PageSearchResultSchema` / `PageSearchResponseSchema`), so the quick search response is validated like every other response.
+
+### What's Changed
+
+- **Breaking** — single-file `image` attributes are now unwrapped in **every** module, not only in the few that ran the extra post-processing step. When an `image` attribute holds exactly one file, its `value` is the file object itself (`[img]` → `img`); values with two or more files stay an array, as before.
+
+  Previously the unwrapping lived in `_clearArray`, which ran only after `_dataPostProcess` (products, menus, forms, forms-data, attribute-sets, integration-collections and `Pages.searchPage`) and only looked at the `attributeValues` key. Everywhere else — blocks, all other pages methods, `Products.getProductsEmptyPage`, `Products.getProductBlockById`, admins, discounts, templates, orders, users — the same attribute arrived as a one-element array, so consumers had to branch on the shape. Form `attributes`, form-data fields and nested `additionalFields` were never unwrapped at all.
+
+  The logic now lives in `_normalizeAttr`, which runs on every attribute of every response:
+
+  ```ts
+  const block = await Blocks.getBlockByMarker('promo');
+  // before: block.attributeValues.img.value[0].downloadLink
+  // now:    block.attributeValues.img.value.downloadLink
+  ```
+
+  Code that reads `value[0]` from products or menus is unaffected — those modules already returned the object. Code that reads `value[0]` from blocks, pages, users or orders must drop the index.
+
+- **Breaking** — a single-file `file` attribute is unwrapped like `image`: `value` is the file object itself, and an array only when several files are attached. `groupOfImages` is a collection by definition and always stays an array. `IBodyTypeFile.value` is widened to `IFileValue | IFileValue[]` accordingly.
+
+- **Breaking** — `real` attributes are cast to a number. `integer` and `float` were already normalized, `real` was not, so the same numeric field reached the consumer as `10` or as `"10"` depending on which of the three types it was declared with:
+
+  ```ts
+  const page = await Pages.getPageByUrl('catalog');
+  // before: page.attributeValues.amount.value // "5"
+  // now:    page.attributeValues.amount.value // 5
+  ```
+
+- **Breaking** — numeric normalization now also runs on form attributes and on form-data fields, which were skipped entirely. A `rating` field of an `integer` form attribute is a `number`, not a string. `IBodyTypeStringNumberFloat.value` is widened to `string | number | null` (send a string; responses come back normalized).
+
+- **Breaking** — an attribute with no value is always `null`. The API returns an empty localization map (`{}`) for an unset value, and the SDK passed it through for text-like types while numeric types became `null` — the same "no value" state had three representations. As a side effect, an unset `integer`/`float` no longer becomes `0`: `Number(null)` is `0`, so an explicit `null` from the API used to be reported as a real zero.
+
+- **Breaking** — form `attributes` are sorted by `position`, the way `attributeValues` always were. The API returns form fields unordered (a field with `position: 10` could arrive after `position: 14`), so rendering a form in CMS order required sorting on the consumer side.
+
+- **Breaking** — Subscriptions > `getAllSubscriptions` returns `ISubscriptionEntity[]` instead of `string[]`. The signature was taken from swagger, which declares `GET /api/content/subscriptions` as an array of markers; the endpoint actually returns full subscription objects, so response validation reported `expected string, received object` on every call and the declared type never matched the data. Callers that read markers should switch from the array element to its `identifier` field:
+
+  ```ts
+  const subscriptions = await Subscriptions.getAllSubscriptions();
+  // before: subscriptions // string[]
+  // now:    subscriptions.map((s) => s.identifier)
+  ```
+
+  `getActiveSubscriptions` is unchanged (`string[]`).
+
+- **Breaking (types only)** — `Products.searchProduct` returns `IProductsEntity[] | IProductSearchResult[] | IError` and `Pages.searchPage` returns `IPagesEntity[] | IPageSearchResult[] | IError`. With `traficLimit: true` both methods return the raw quick search response — a short card without `attributeValues`, `localizeInfos`, `blocks` and the rest of the entity — while the signature promised a full entity in both modes, so a consumer reading `attributeValues` in traficLimit mode got `undefined` with no type error. Runtime behaviour is unchanged; narrow by config or by field:
+
+  ```ts
+  const found = await Products.searchProduct('cos');
+  if (Array.isArray(found) && found.length && 'attributeValues' in found[0]) {
+    // IProductsEntity[] — traficLimit is off
+  }
+  ```
+
+- `Pages.searchPage` no longer runs the template lookup over the traficLimit response. Short cards carry no `templateIdentifier`, so the step could never attach anything; the result is identical, minus the pointless pass.
+
+### Bug Fixes
+
+- Methods whose result is just success-or-failure no longer report `true` when the API rejected the request: `Subscriptions.cancelSubscription`, `Subscriptions.recoverSubscriptions`, `Events.subscribeByMarker`, `Events.unsubscribeByMarker`, `Events.subscribeToForm`, `Events.unsubscribeFromForm`.
+
+  With `errors.isShell` enabled — the default — the SDK **returns** the API error instead of throwing it. The shared helper behind these six methods only had a `try/catch`, so nothing ever reached its `catch` and every failure was reported as a success: `cancelSubscription` answered `true` while the API replied `404 "Subscription already inactive"`, and the `IError` half of the declared `Promise<boolean | IError>` was unreachable. The helper now also inspects the returned value and passes the error through:
+
+  ```ts
+  const cancelled = await Subscriptions.cancelSubscription({ marker: 'premium' });
+  // before: true — on 404 and 403 alike
+  // now:    { statusCode: 404, message: 'Subscription already inactive', ... }
+  ```
+
+  The success path is unchanged (`true`), and `isShell: false` still throws. Code that checks these results with `if (result)` must switch to `if (result === true)` — an error object is truthy.
+
 ## v.1.0.156
 
 ### What's New

package/dist/attribute-sets/attributeSetsApi.js

@@ -50,7 +50,7 @@ class AttributesSetsApi extends asyncModules_1.default {
         const result = await this._fetchGet(`?` + this._queryParamsToString(query));
         // Validate response if validation is enabled
         const validated = this._validateResponse(result, attributeSetsSchemas_1.AttributeSetsResponseSchema);
-        return this._dataPostProcess(validated, langCode);
+        return this._normalizeData(validated, langCode);
     }
     /**
      * Getting all attributes with data from the attribute set.
@@ -65,7 +65,7 @@ class AttributesSetsApi extends asyncModules_1.default {
         const result = await this._fetchGet(`/${marker}/attributes?langCode=${langCode}`);
         // Validate response if validation is enabled
         const validated = this._validateResponse(result, attributeSetsSchemas_1.AttributesArrayResponseSchema);
-        return this._dataPostProcess(validated, langCode);
+        return this._normalizeData(validated, langCode);
     }
     /**
      * Get a single attribute with data from the attribute sets.
@@ -81,7 +81,7 @@ class AttributesSetsApi extends asyncModules_1.default {
         const result = await this._fetchGet(`/${setMarker}/attributes/${attributeMarker}?langCode=${langCode}`);
         // Validate response if validation is enabled
         const validated = this._validateResponse(result, attributeSetsSchemas_1.AttributeEntitySchema);
-        return this._dataPostProcess(validated, langCode);
+        return this._normalizeData(validated, langCode);
     }
     /**
      * Getting a single object from a set of attributes by marker.
@@ -96,7 +96,7 @@ class AttributesSetsApi extends asyncModules_1.default {
         const result = await this._fetchGet(`/marker/${marker}?langCode=${langCode}`);
         // Validate response if validation is enabled
         const validated = this._validateResponse(result, attributeSetsSchemas_1.AttributeSetEntitySchema);
-        return this._dataPostProcess(validated, langCode);
+        return this._normalizeData(validated, langCode);
     }
 }
 exports.default = AttributesSetsApi;

package/dist/attribute-sets/attributeSetsInterfaces.d.ts

@@ -82,7 +82,7 @@ type AttributeType = 'string' | 'text' | 'textWithHeader' | 'integer' | 'real' |
  * Represents an attribute set entity.
  * @interface IAttributesSetsEntity
  * @property {AttributeType} type - Attribute type. Example: "string", "text", "integer", "etc".
- * @property {unknown} [value] - Value of the attribute, which can be of any type.
+ * @property {unknown} [value] - Value of the attribute, normalized the same way as an entity attribute value: `number | null` for numeric types, the file object itself for a single-file `image`/`file`, `null` when the attribute carries no value.
  * @property {unknown} initialValue - Initial value of the attribute.
  * @property {string} marker - Textual identifier of the attribute (marker). Example: "color", "size", "etc".
  * @property {number} position - Position number for sorting. Example: 1.

package/dist/auth-provider/authProviderSchemas.d.ts

@@ -26,6 +26,8 @@ export declare const SignUpResponseSchema: z.ZodObject<{
     isDeleted: z.ZodOptional<z.ZodBoolean>;
     state: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
     rating: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    attributeSetId: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    attributesSets: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strip>;
 /**
  * Auth response schema (login/refresh)

package/dist/auth-provider/authProviderSchemas.js

@@ -30,6 +30,8 @@ exports.SignUpResponseSchema = zod_1.z.object({
     isDeleted: zod_1.z.boolean().optional(),
     state: zod_1.z.record(zod_1.z.string(), zod_1.z.any()).optional(),
     rating: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
+    attributeSetId: zod_1.z.number().nullable().optional(),
+    attributesSets: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
 });
 /**
  * Auth response schema (login/refresh)

package/dist/auth-provider/authProvidersInterfaces.d.ts

@@ -268,6 +268,8 @@ interface IOauthData {
  * @property {boolean} [isDeleted] - Whether the entity is deleted. Example: false.
  * @property {Record<string, unknown>} [state] - Additional state information. Example: {}.
  * @property {IRating} [rating] - Rating data.
+ * @property {number | null} [attributeSetId] - Identifier of the attribute set attached to the user, or null when none is attached. Example: null.
+ * @property {Record<string, unknown>} [attributesSets] - Attribute sets attached to the user, keyed by marker; empty object when none. Example: {}.
  * @description This interface defines the structure of a sign-up entity.
  */
 interface ISignUpEntity {
@@ -285,6 +287,8 @@ interface ISignUpEntity {
     isDeleted?: boolean;
     state?: Record<string, unknown>;
     rating?: IRating;
+    attributeSetId?: number | null;
+    attributesSets?: Record<string, unknown>;
 }
 /**
  * Interface representing a code entity used for user registration or verification processes.

package/dist/base/asyncModules.d.ts

@@ -15,6 +15,17 @@ export default abstract class AsyncModules extends SyncModules {
      * @description Constructor initializes the AsyncModules with a given state.
      */
     protected constructor(state: StateModule);
+    /**
+     * Detects an API error returned as a value instead of being thrown.
+     *
+     * With `isShell` enabled (the default) `browserResponse` returns the error
+     * body — and a caught exception — instead of throwing, so a failed request
+     * is indistinguishable from a successful one by control flow alone.
+     * @param {unknown} value - Value returned by a request.
+     * @returns {boolean} True when the value is an API error (statusCode >= 400) or a thrown error object.
+     * @description Recognizes both the OneEntry error body and errors caught by browserResponse (e.g. a network failure).
+     */
+    protected _isErrorResponse(value: unknown): value is IError;
     /**
      * Validates API response against a Zod schema (optional)
      * @param {unknown} data - The data to validate
@@ -59,8 +70,13 @@ export default abstract class AsyncModules extends SyncModules {
      *
      * Several endpoints (cancel/recover subscription, subscribe/unsubscribe to
      * events) return no useful body — callers only care whether the request
-     * succeeded. This helper resolves to `true` on success and to the caught
-     * error (as IError) on failure, centralizing the repeated try/catch.
+     * succeeded. This helper resolves to `true` on success and to the error
+     * (as IError) on failure, centralizing the repeated try/catch.
+     *
+     * The returned value has to be inspected as well: with `isShell` enabled
+     * (the default) browserResponse returns the API error instead of throwing
+     * it, so relying on the catch alone would report every failed call — a 404
+     * from cancelSubscription, a 403 from recoverSubscriptions — as a success.
      * @param {() => Promise<unknown>} request - Thunk performing the fetch call.
      * @returns {Promise<boolean | IError>} `true` on success, IError on failure.
      */

package/dist/base/asyncModules.js

@@ -20,6 +20,26 @@ class AsyncModules extends syncModules_1.default {
         this.state = state;
         this._url = this.state.url;
     }
+    /**
+     * Detects an API error returned as a value instead of being thrown.
+     *
+     * With `isShell` enabled (the default) `browserResponse` returns the error
+     * body — and a caught exception — instead of throwing, so a failed request
+     * is indistinguishable from a successful one by control flow alone.
+     * @param {unknown} value - Value returned by a request.
+     * @returns {boolean} True when the value is an API error (statusCode >= 400) or a thrown error object.
+     * @description Recognizes both the OneEntry error body and errors caught by browserResponse (e.g. a network failure).
+     */
+    _isErrorResponse(value) {
+        if (value instanceof Error) {
+            return true;
+        }
+        return (value !== null &&
+            typeof value === 'object' &&
+            'statusCode' in value &&
+            typeof value.statusCode === 'number' &&
+            value.statusCode >= 400);
+    }
     /**
      * Validates API response against a Zod schema (optional)
      * @param {unknown} data - The data to validate
@@ -33,11 +53,7 @@ class AsyncModules extends syncModules_1.default {
             return data;
         }
         // Skip validation for error responses (statusCode indicates API error)
-        if (data !== null &&
-            typeof data === 'object' &&
-            'statusCode' in data &&
-            typeof data.statusCode === 'number' &&
-            data.statusCode >= 400) {
+        if (this._isErrorResponse(data)) {
             return data;
         }
         // Use strict or safe validation based on config
@@ -109,14 +125,22 @@ class AsyncModules extends syncModules_1.default {
      *
      * Several endpoints (cancel/recover subscription, subscribe/unsubscribe to
      * events) return no useful body — callers only care whether the request
-     * succeeded. This helper resolves to `true` on success and to the caught
-     * error (as IError) on failure, centralizing the repeated try/catch.
+     * succeeded. This helper resolves to `true` on success and to the error
+     * (as IError) on failure, centralizing the repeated try/catch.
+     *
+     * The returned value has to be inspected as well: with `isShell` enabled
+     * (the default) browserResponse returns the API error instead of throwing
+     * it, so relying on the catch alone would report every failed call — a 404
+     * from cancelSubscription, a 403 from recoverSubscriptions — as a success.
      * @param {() => Promise<unknown>} request - Thunk performing the fetch call.
      * @returns {Promise<boolean | IError>} `true` on success, IError on failure.
      */
     async _fetchBoolean(request) {
         try {
-            await request();
+            const result = await request();
+            if (this._isErrorResponse(result)) {
+                return result;
+            }
             return true;
         }
         catch (e) {

package/dist/base/syncModules.d.ts

@@ -88,27 +88,33 @@ export default abstract class SyncModules {
      */
     protected _normalizePostBody(body: any, langCode?: string): any;
     /**
-     * Clears arrays within the data structure.
+     * Normalizes the value of a single attribute in place.
      *
-     * Traverses the data and fixes a specific edge case with image attributes:
-     * when an `image` attribute has a single-element array in `value`,
-     * the API returns an array but consumers expect a plain object.
-     * In that case `value` is unwrapped: `[img]` → `img`.
+     * Applies the three type-driven fixes the API response needs, so that an
+     * attribute of a given type always reaches the consumer in the same shape,
+     * no matter which collection it arrived in:
      *
-     * For all other keys the method recursively copies the structure unchanged.
-     * @param {Record<string, any>} data - The data to clear.
-     * @returns {any} Cleared data.
+     * 1. **Single-file values** (`image`, `file`) — the API always sends an array,
+     * even for one file: `[img]` → `img`. Multi-file values and `groupOfImages`
+     * (a collection by definition) stay an array.
+     * 2. **Empty values** — an attribute with no value comes back as an empty
+     * localization map `{}`; it is replaced with `null`, the same marker the
+     * 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`.
+     * @param {any} attr - The attribute object to normalize in place.
      */
-    protected _clearArray(data: Record<string, any>): any;
+    private _normalizeAttrValue;
     /**
      * Sorts attributes by their positions.
      *
-     * The API returns attributes as an object `{ marker: AttrObject }`.
-     * Each attribute has a `position` field. The method rebuilds the object
-     * with keys sorted by ascending `position` so that the display order
-     * matches the order defined in the CMS.
-     * @param {any} data - The data containing attributes.
-     * @returns {any} Sorted attributes.
+     * Each attribute has a `position` field, and the API returns them in no
+     * particular order. The method rebuilds the collection sorted by ascending
+     * `position`, so the display order matches the order defined in the CMS.
+     * Both container shapes the API uses are handled: an object keyed by marker
+     * (`attributeValues`) and an array (form `attributes`).
+     * @param {any} data - The attributes collection to sort.
+     * @returns {any} Sorted attributes, in the same container shape.
      */
     protected _sortAttributes: (data: any) => any;
     /**
@@ -127,18 +133,23 @@ export default abstract class SyncModules {
      *
      * Handles three different attribute formats returned by the API:
      *
-     * **1. `attributeValues`** — attributes of pages, products and other entities.
-     * Contains an object `{ marker: AttrObject }`. For each attribute:
-     * - `_normalizeAdditionalFields` is called;
-     * - numeric types (`integer`, `float`) are cast to a JS number (or `null`);
-     * - the whole object is re-sorted by `position`.
+     * All three go through the same steps, so an attribute of a given type looks
+     * the same whichever collection it arrived in:
+     * - `_normalizeAdditionalFields` turns nested fields into a marker map;
+     * - `_normalizeAttrValue` unwraps single-file values, empties to `null` and
+     * casts numbers;
+     * - the collection is re-sorted by `position`.
      *
-     * **2. `attributes`** — form attributes (different API structure).
-     * Same `additionalFields` processing,
-     * but numbers are not normalized here (commented out — logic differs).
+     * **1. `attributeValues`** — attributes of pages, products and other entities,
+     * an object `{ marker: AttrObject }`.
      *
-     * **3. `type`** — a single attribute from an attribute set.
-     * Same transformations as in case 1, but without sorting.
+     * **2. `attributes`** — form attributes, an array (or a marker map on some
+     * endpoints); form-only boolean flags (`isLogin`, `isSignUp`, notifications)
+     * are additionally coerced from `null` to `false`.
+     *
+     * **3. `type`** — a standalone attribute: an attribute-set entry, a form-data
+     * field or a nested `additionalFields` entry. Same transformations, but there
+     * is no collection to sort.
      *
      * `timeInterval` attributes are left exactly as the API returned them — a
      * compact recurrence rule. Resolving one into concrete slots is the caller's
@@ -150,17 +161,6 @@ export default abstract class SyncModules {
      * @returns {any} Normalized attributes.
      */
     protected _normalizeAttr(data: any): any;
-    /**
-     * Processes data after fetching or receiving it.
-     *
-     * Final post-processing of the API response: first unwraps localized fields
-     * (`_normalizeData`), then fixes single-element image attributes
-     * (`_clearArray`). Called at the end of every fetch method.
-     * @param {any} data - The data to process.
-     * @param {any} [langCode] - The language code for processing.
-     * @returns {any} Processed data.
-     */
-    protected _dataPostProcess(data: any, langCode?: string): any;
     /**
      * Sets the access token in the state.
      * @param {string} accessToken - The access token to set.

package/dist/base/syncModules.js

@@ -91,14 +91,17 @@ class SyncModules {
         /**
          * Sorts attributes by their positions.
          *
-         * The API returns attributes as an object `{ marker: AttrObject }`.
-         * Each attribute has a `position` field. The method rebuilds the object
-         * with keys sorted by ascending `position` so that the display order
-         * matches the order defined in the CMS.
-         * @param {any} data - The data containing attributes.
-         * @returns {any} Sorted attributes.
+         * Each attribute has a `position` field, and the API returns them in no
+         * particular order. The method rebuilds the collection sorted by ascending
+         * `position`, so the display order matches the order defined in the CMS.
+         * Both container shapes the API uses are handled: an object keyed by marker
+         * (`attributeValues`) and an array (form `attributes`).
+         * @param {any} data - The attributes collection to sort.
+         * @returns {any} Sorted attributes, in the same container shape.
          */
-        this._sortAttributes = (data) => Object.fromEntries(Object.entries(data).sort(([, a], [, b]) => a.position - b.position));
+        this._sortAttributes = (data) => Array.isArray(data)
+            ? [...data].sort((a, b) => a.position - b.position)
+            : Object.fromEntries(Object.entries(data).sort(([, a], [, b]) => a.position - b.position));
         this.state = state;
         this._url = state.url;
         this._nodeDeviceId = _generateId();
@@ -240,50 +243,42 @@ class SyncModules {
         return body;
     }
     /**
-     * Clears arrays within the data structure.
+     * Normalizes the value of a single attribute in place.
      *
-     * Traverses the data and fixes a specific edge case with image attributes:
-     * when an `image` attribute has a single-element array in `value`,
-     * the API returns an array but consumers expect a plain object.
-     * In that case `value` is unwrapped: `[img]` → `img`.
+     * Applies the three type-driven fixes the API response needs, so that an
+     * attribute of a given type always reaches the consumer in the same shape,
+     * no matter which collection it arrived in:
      *
-     * For all other keys the method recursively copies the structure unchanged.
-     * @param {Record<string, any>} data - The data to clear.
-     * @returns {any} Cleared data.
+     * 1. **Single-file values** (`image`, `file`) — the API always sends an array,
+     * even for one file: `[img]` → `img`. Multi-file values and `groupOfImages`
+     * (a collection by definition) stay an array.
+     * 2. **Empty values** — an attribute with no value comes back as an empty
+     * localization map `{}`; it is replaced with `null`, the same marker the
+     * 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`.
+     * @param {any} attr - The attribute object to normalize in place.
      */
-    _clearArray(data) {
-        if (Array.isArray(data)) {
-            return data.map((item) => this._clearArray(item));
+    _normalizeAttrValue(attr) {
+        if ((attr.type === 'image' || attr.type === 'file') &&
+            Array.isArray(attr.value) &&
+            attr.value.length === 1) {
+            attr.value = attr.value[0];
         }
-        else if (typeof data === 'object' && data) {
-            const normalizeData = {};
-            Object.keys(data).forEach((key) => {
-                if (Array.isArray(data[key])) {
-                    normalizeData[key] = this._clearArray(data[key]);
-                }
-                else if (!data[key] || typeof data[key] !== 'object') {
-                    normalizeData[key] = data[key];
-                }
-                else if (key === 'attributeValues') {
-                    const attrs = data[key];
-                    Object.keys(attrs).forEach((attr) => {
-                        // If an image attribute has a single-element value array,
-                        // unwrap it to a plain object for consumer convenience.
-                        if (attrs[attr].type === 'image' &&
-                            attrs[attr].value.length === 1) {
-                            attrs[attr].value = attrs[attr].value[0];
-                        }
-                    });
-                    normalizeData[key] = data[key];
-                }
-                else {
-                    normalizeData[key] = this._clearArray(data[key]);
-                }
-            });
-            return normalizeData;
+        // An attribute with no value arrives as an empty localization map.
+        if (attr.value &&
+            typeof attr.value === 'object' &&
+            !Array.isArray(attr.value) &&
+            Object.keys(attr.value).length === 0) {
+            attr.value = null;
         }
-        else {
-            return data;
+        if (attr.type === 'integer' ||
+            attr.type === 'float' ||
+            attr.type === 'real') {
+            // 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);
+            attr.value = isNaN(numValue) ? null : numValue;
         }
     }
     /**
@@ -306,18 +301,23 @@ class SyncModules {
      *
      * Handles three different attribute formats returned by the API:
      *
-     * **1. `attributeValues`** — attributes of pages, products and other entities.
-     * Contains an object `{ marker: AttrObject }`. For each attribute:
-     * - `_normalizeAdditionalFields` is called;
-     * - numeric types (`integer`, `float`) are cast to a JS number (or `null`);
-     * - the whole object is re-sorted by `position`.
+     * All three go through the same steps, so an attribute of a given type looks
+     * the same whichever collection it arrived in:
+     * - `_normalizeAdditionalFields` turns nested fields into a marker map;
+     * - `_normalizeAttrValue` unwraps single-file values, empties to `null` and
+     * casts numbers;
+     * - the collection is re-sorted by `position`.
      *
-     * **2. `attributes`** — form attributes (different API structure).
-     * Same `additionalFields` processing,
-     * but numbers are not normalized here (commented out — logic differs).
+     * **1. `attributeValues`** — attributes of pages, products and other entities,
+     * an object `{ marker: AttrObject }`.
      *
-     * **3. `type`** — a single attribute from an attribute set.
-     * Same transformations as in case 1, but without sorting.
+     * **2. `attributes`** — form attributes, an array (or a marker map on some
+     * endpoints); form-only boolean flags (`isLogin`, `isSignUp`, notifications)
+     * are additionally coerced from `null` to `false`.
+     *
+     * **3. `type`** — a standalone attribute: an attribute-set entry, a form-data
+     * field or a nested `additionalFields` entry. Same transformations, but there
+     * is no collection to sort.
      *
      * `timeInterval` attributes are left exactly as the API returned them — a
      * compact recurrence rule. Resolving one into concrete slots is the caller's
@@ -334,11 +334,7 @@ class SyncModules {
             Object.keys(data.attributeValues).forEach((attr) => {
                 const d = data.attributeValues[attr];
                 this._normalizeAdditionalFields(d);
-                // normalize numbers
-                if (d.type === 'integer' || d.type === 'float') {
-                    const numValue = Number(d.value);
-                    d.value = isNaN(numValue) ? null : numValue;
-                }
+                this._normalizeAttrValue(d);
             });
             return {
                 ...data,
@@ -357,45 +353,27 @@ class SyncModules {
             const d = data.attributes;
             Object.keys(d).forEach((attr) => {
                 this._normalizeAdditionalFields(d[attr]);
+                this._normalizeAttrValue(d[attr]);
                 for (const field of booleanFields) {
                     if (field in d[attr] && d[attr][field] === null) {
                         d[attr][field] = false;
                     }
                 }
             });
-            return data;
+            return { ...data, attributes: this._sortAttributes(d) };
         }
         //  For single attribute - for attribute sets
         if ('type' in data) {
             this._normalizeAdditionalFields(data);
+            this._normalizeAttrValue(data);
             for (const field of booleanFields) {
                 if (field in data && data[field] === null) {
                     data[field] = false;
                 }
             }
-            // Normalize numbers
-            if (data.type === 'integer' || data.type === 'float') {
-                const numValue = Number(data.value);
-                data.value = isNaN(numValue) ? null : numValue;
-            }
         }
         return data;
     }
-    /**
-     * Processes data after fetching or receiving it.
-     *
-     * Final post-processing of the API response: first unwraps localized fields
-     * (`_normalizeData`), then fixes single-element image attributes
-     * (`_clearArray`). Called at the end of every fetch method.
-     * @param {any} data - The data to process.
-     * @param {any} [langCode] - The language code for processing.
-     * @returns {any} Processed data.
-     */
-    _dataPostProcess(data, langCode = this.state.lang) {
-        const normalize = this._normalizeData(data, langCode);
-        const result = this._clearArray(normalize);
-        return result;
-    }
     /**
      * Sets the access token in the state.
      * @param {string} accessToken - The access token to set.

package/dist/base/utils.d.ts

@@ -260,8 +260,8 @@ interface ITimeIntervalRange {
 /**
  * @interface IAttributeValue
  * @property {string} type - Attribute data type (e.g. "string", "integer", "list", "file", "image").
- * @property {unknown} value - Attribute value — actual TS type depends on `type` (string for "string"/"text", number for "integer", array for "list", etc.). Example: "Admins text".
- * @property {number} [position] - Sort position of the value inside its set. Example: 0.
+ * @property {unknown} value - Attribute value — actual TS type depends on `type`, and the SDK normalizes it to the same shape in every module: `string` for "string"/"text"; `number | null` for "integer"/"float"/"real"; the file object itself for a single-file "image"/"file" and an array of them for several; an array for "list" and "groupOfImages". An attribute with no value is always `null`. Example: "Admins text".
+ * @property {number} [position] - Sort position of the value inside its set; the containing collection is returned sorted by it. Example: 0.
  * @property {Record<string, IAttributeValue> | unknown[]} [additionalFields] - Nested attribute values keyed by marker; the API may also return an empty array when none are configured. Optional.
  * @property {boolean} [isIcon] - Block/preview attribute flag — whether the field is treated as an icon. Optional.
  * @property {boolean} [isProductPreview] - Block/preview attribute flag — whether the field is shown in product preview. Optional.

package/dist/forms/formsApi.js

@@ -38,7 +38,7 @@ class FormsApi extends asyncModules_1.default {
         const result = await this._fetchGet(`?langCode=${langCode}&offset=${offset}&limit=${limit}`);
         // Validate response if validation is enabled
         const validated = this._validateResponse(result, formsSchemas_1.FormsResponseSchema);
-        return this._dataPostProcess(validated, langCode);
+        return this._normalizeData(validated, langCode);
     }
     /**
      * Get one form by form marker.
@@ -53,7 +53,7 @@ class FormsApi extends asyncModules_1.default {
         const result = await this._fetchGet(`/marker/${marker}?langCode=${langCode}`);
         // Validate response if validation is enabled
         const validated = this._validateResponse(result, formsSchemas_1.FormEntitySchema);
-        return this._dataPostProcess(validated, langCode);
+        return this._normalizeData(validated, langCode);
     }
 }
 exports.default = FormsApi;