oneentry 1.0.172 → 1.0.174

package/changelog.md

@@ -1,5 +1,53 @@
 # SDK Change Log
 
+## v.1.0.174
+
+### What's Changed
+
+- **⚠️ Breaking (types): `IBodyPostFormData.replayTo` is `number | null`.** It was declared `string | null` and described as the email to reply to. The endpoint takes the id of the parent form data record and stores it as `parentId` — `replayTo: 9262` comes back as `parentId: 9262`, while an email answers `500 invalid input syntax for type integer`. Code that passed `null` is unaffected (CMS-1087).
+
+- **`Products.getProductsCountByPageId` takes `id: number | string`.** It was `string` only, while `getProductsByPageId` takes a `number` for the same page id, so `getProductsCountByPageId(10)` did not compile. A string id still compiles (CMS-1087).
+
+### What's Fixed
+
+- **JSDoc that the documentation site is generated from** (CMS-1087).
+  - Tracker card numbers, stand names and dates are gone from the public JSDoc and so from `.d.ts`; the history stays in code comments and in this change log.
+  - About 600 field and parameter descriptions are rewritten after the documentation site's edits, checked against the sources and the API reference: literal translations ("A sign of page visibility", "Set of attributes id", "User id of the linked template"), descriptions that did not say what a field holds, and pagination parameters described only as "Parameter for pagination". `templateIdentifier` and `attributeSetIdentifier` are described as markers, not ids.
+  - `forms-data`: `formIdentifier` is the form marker, not "The identifier of the page"; `time` is the date of the record, not "The identifier of the form"; `entityId` is the id of the record's entity, not "Form module config Id"; `ip` and `isUserAdmin` are described instead of repeated.
+  - `AttributesSets.getAttributes`: `sortBy` is the sort key (`id` or `position`); it carried the description of `typeId`.
+  - `Forms`: `isSignUp` and `isSignUpRequired` no longer share one description. `IntegrationCollections`: `valid` is described as the boolean it is.
+  - `IFilterParams.pageUrl` has a single URL as its example, not an array. `isPositionLocked` is marked optional in the JSDoc, as in the type. `IUserEntity.total` is described as the API returns it — a numeric string the API reference does not describe.
+  - Typos: "Deault: []" (six places), `Default: "en_US".=`, `Example: "Product Template"..`.
+
+### Tests
+
+- **`callercontracts.spec.ts`**: a numeric `replayTo` must compile and an email must not; `getProductsCountByPageId(10)` must compile and request `/page/10/counts`.
+
+## v.1.0.173
+
+### What's Changed
+
+- **⚠️ Breaking (types): `FileUploading.upload` and `FileUploading.delete` require `fileQuery`, and `IUploadingQuery` requires `type`, `entity` and `id`.** The signature and the JSDoc declared all of them optional, and the SDK filled the gaps with `null` — which the endpoint refuses: without any of the three both methods answer `400 type should not be empty; entity should not be empty; id should not be empty`, and a `delete` without `type` leaves the file in place. A call that compiled could never succeed. It is now a compile error instead of a `400` at run time; code that already passed a full `fileQuery` is unaffected. `width`, `height`, `compress` and `template` stay optional. The per-field `fileQuery` of `postFormsData` is unchanged — there the SDK still picks a folder when none is given (CMS-1085).
+
+- **`IntegrationCollections` types accept the calls the API accepts.** `ICollectionFormObject.formData` was declared as a map keyed by language only, so the flat array `[{ marker, type, value }]` shown in the JSDoc example of `createICollectionRow` — and stored by the platform — did not compile; it is now `ICollectionFormData[] | Record<string, ICollectionFormData[]>`. All four fields of `ICollectionQuery` were required, so `{ limit, offset }` did not compile either; they are optional now. `getICollections` takes the new `ICollectionsListQuery` (`limit`, `offset`): the collection list has no entity filter. The JSDoc of both list methods gave the pagination defaults swapped (`limit` 0, `offset` 30); the code has always used `limit` 30, `offset` 0, and so does the JSDoc now (CMS-1078, CMS-1086).
+
+- **`IFilterParams.attributeMarker` and `conditionValue` are optional.** A filter entry may select by `statusMarker` (or `pageUrls`, `title`) alone — `getProducts([{ statusMarker: 'sale' }])` is answered and filtered by the endpoint (an unknown status gives `total: 0`), but the type refused it without a cast (CMS-1086).
+
+- **`System.getApiStat` is typed.** It returned `Promise<unknown>` and its JSDoc promised "object with date and count"; the endpoint answers an array of one-key day objects, `[{ "2026-10-25": 17280 }, { "2026-10-26": 13671 }]`. The return type is now `IApiStatEntry[] | IError`, with `IApiStatEntry = Record<string, number>` exported (CMS-1077).
+
+### What's Fixed
+
+- **JSDoc that the documentation site is generated from.**
+  - `IConfig.traficLimit` and the `config.traficLimit` parameter of `defineOneEntry` said "set it to `false` to save traffic" — the opposite of the code: `true` makes the SDK skip its follow-up requests (one request instead of six for a quick page search) and shortens some results to `{ id, title }` cards (CMS-1084).
+  - `Templates.getAllTemplates`, `getTemplateByType` and `getTemplateByMarker` named `GroupedTemplatesObject` and `TemplateEntity`, which do not exist; they name `BlockType` and `ITemplateEntity` now, and `getTemplateByType` is described as the array it returns (CMS-1077).
+  - `AuthProvider.getActiveSessionsByMarker` carried the description of `getAuthProviderByMarker`; it describes the user's active sessions now (CMS-1086).
+  - `ProductStatuses.getProductsByStatusMarker` and `validateMarker` called their argument a product marker; it is a product status marker (CMS-1086).
+  - Examples carried Russian data into English documentation: `"Ivan"` in the order examples and `"ru-RU"` in `IActiveSession` are `"John"` and `"en-US"` (CMS-1086).
+
+### Tests
+
+- **`callercontracts.spec.ts` checks the types against the API.** ts-jest type-checks the file, so a type that drifts back fails the run: a flat collection `formData`, `{ limit, offset }` as a collection query, a status-only product filter and the `getApiStat` array must compile, and `upload` / `delete` without `fileQuery` must not (`@ts-expect-error`). The test client is typed now — it was `any`, which would have let such checks pass silently. Against 1.0.172 the file does not compile, with six errors naming exactly these types.
+
 ## v.1.0.172
 
 ### What's Fixed

package/dist/admins/adminsApi.d.ts

@@ -25,7 +25,7 @@ export default class AdminsApi extends AsyncModules implements IAdmins {
     /**
      * Get all admins objects with filters.
      * @handleName getAdminsInfo
-     * @param {IFilterParams[]} [body] - Array of filter objects with search conditions. Default: [].
+     * @param {IFilterParams[]} [body] - Filter objects with search conditions. Default: `[]`.
      * @example
         [
           {
@@ -39,12 +39,12 @@ export default class AdminsApi extends AsyncModules implements IAdmins {
             "conditionValue": 3
           }
         ]
-     * @param {string} [body.attributeMarker] - Text identifier (marker) of the attribute in the set. Example: "num".
+     * @param {string} [body.attributeMarker] - Marker of the attribute in the set. Example: "num".
      * @param {string} [body.conditionMarker] - Text identifier (marker) of the condition in the set. Example: "mth".
      * @param {number | string | null} [body.conditionValue] - Value of the condition. Example: "new".
      * @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 {number} [offset] - Number of records to skip. Default: 0.
+     * @param {number} [limit] - Maximum number of records to return. Default: 30.
      * @returns {Promise<IAdminEntity[] | IError>} Returns an array of admin objects.
      * @throws {IError} When isShell=false and an error occurs during the fetch
      * @see {@link https://js-sdk.oneentry.cloud/docs/admins/getAdminsInfo getAdminsInfo} documentation.
@@ -53,10 +53,10 @@ export default class AdminsApi extends AsyncModules implements IAdmins {
     /**
      * Semantic (vector) search for admins.
      * @handleName getAdminsByVectorSearch
-     * @param {IAdminsVectorSearch} body - Vector search body. Example: `{ queryText: "content manager" }`.
+     * @param {IAdminsVectorSearch} body - Vector search parameters. Example: `{ queryText: "content manager" }`.
      * @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 {number} [offset] - Number of records to skip. Default: 0.
+     * @param {number} [limit] - Maximum number of records to return. Default: 30.
      * @returns {Promise<IVectorSearchResponse<IAdminsResponse> | IError>} Returns an object with an array of found admins and total count.
      * @throws {IError} When isShell=false and an error occurs during the fetch
      * @description This method performs a semantic (vector) search for admins.

package/dist/admins/adminsApi.js

@@ -62,7 +62,7 @@ class AdminsApi extends asyncModules_1.default {
     /**
      * Get all admins objects with filters.
      * @handleName getAdminsInfo
-     * @param {IFilterParams[]} [body] - Array of filter objects with search conditions. Default: [].
+     * @param {IFilterParams[]} [body] - Filter objects with search conditions. Default: `[]`.
      * @example
         [
           {
@@ -76,12 +76,12 @@ class AdminsApi extends asyncModules_1.default {
             "conditionValue": 3
           }
         ]
-     * @param {string} [body.attributeMarker] - Text identifier (marker) of the attribute in the set. Example: "num".
+     * @param {string} [body.attributeMarker] - Marker of the attribute in the set. Example: "num".
      * @param {string} [body.conditionMarker] - Text identifier (marker) of the condition in the set. Example: "mth".
      * @param {number | string | null} [body.conditionValue] - Value of the condition. Example: "new".
      * @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 {number} [offset] - Number of records to skip. Default: 0.
+     * @param {number} [limit] - Maximum number of records to return. Default: 30.
      * @returns {Promise<IAdminEntity[] | IError>} Returns an array of admin objects.
      * @throws {IError} When isShell=false and an error occurs during the fetch
      * @see {@link https://js-sdk.oneentry.cloud/docs/admins/getAdminsInfo getAdminsInfo} documentation.
@@ -100,10 +100,10 @@ class AdminsApi extends asyncModules_1.default {
     /**
      * Semantic (vector) search for admins.
      * @handleName getAdminsByVectorSearch
-     * @param {IAdminsVectorSearch} body - Vector search body. Example: `{ queryText: "content manager" }`.
+     * @param {IAdminsVectorSearch} body - Vector search parameters. Example: `{ queryText: "content manager" }`.
      * @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 {number} [offset] - Number of records to skip. Default: 0.
+     * @param {number} [limit] - Maximum number of records to return. Default: 30.
      * @returns {Promise<IVectorSearchResponse<IAdminsResponse> | IError>} Returns an object with an array of found admins and total count.
      * @throws {IError} When isShell=false and an error occurs during the fetch
      * @description This method performs a semantic (vector) search for admins.

package/dist/admins/adminsInterfaces.d.ts

@@ -9,7 +9,7 @@ interface IAdmins {
     /**
      * Get all admins objects with filters.
      * @handleName getAdminsInfo
-     * @param {IFilterParams[]} [body] - Array of filter objects with search conditions. Default: [].
+     * @param {IFilterParams[]} [body] - Filter objects with search conditions. Default: `[]`.
      * @example
         [
           {
@@ -23,12 +23,12 @@ interface IAdmins {
             "conditionValue": 3
           }
         ]
-     * @param {string} [body.attributeMarker] - Text identifier (marker) of the attribute in the set. Example: "num".
+     * @param {string} [body.attributeMarker] - Marker of the attribute in the set. Example: "num".
      * @param {string} [body.conditionMarker] - Text identifier (marker) of the condition in the set. Example: "mth".
      * @param {number | string | null} [body.conditionValue] - Value of the condition. Example: "new".
      * @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 {number} [offset] - Number of records to skip. Default: 0.
+     * @param {number} [limit] - Maximum number of records to return. Default: 30.
      * @returns {IAdminEntity[]} Returns an array of admin objects.
      * @throws {IError} - If there is an error during the fetch operation, it will return an error object.
      */
@@ -36,10 +36,10 @@ interface IAdmins {
     /**
      * Semantic (vector) search for admins.
      * @handleName getAdminsByVectorSearch
-     * @param {IAdminsVectorSearch} body - Vector search body. Example: `{ queryText: "content manager" }`.
+     * @param {IAdminsVectorSearch} body - Vector search parameters. Example: `{ queryText: "content manager" }`.
      * @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 {number} [offset] - Number of records to skip. Default: 0.
+     * @param {number} [limit] - Maximum number of records to return. Default: 30.
      * @returns {IVectorSearchResponse<IAdminsResponse>} Returns an object with an array of found admins, total count and indexReady.
      * @throws {IError} - If there is an error during the fetch operation, it will return an error object.
      */
@@ -50,8 +50,8 @@ interface IAdmins {
  * @interface IAdminsVectorSearch
  * @property {string} queryText - Natural-language search query. Example: "content manager".
  * @property {number} [vectorDistanceThreshold] - Override of the cosine distance threshold (0..2). Example: 0.3.
- * @property {number} [maxHits] - Top-K candidates fetched before pagination. Default: 100. Max: 500. Example: 10.
- * @property {boolean} [debug] - When true, each returned item gets a `distance` field. Example: false.
+ * @property {number} [maxHits] - Number of top candidates fetched before pagination. Default: 100. Maximum: 500. Example: 10.
+ * @property {boolean} [debug] - When `true`, each returned item gets a `distance` field. Example: false.
  * @description Body for the admins vector/search endpoint.
  */
 interface IAdminsVectorSearch {
@@ -62,7 +62,7 @@ interface IAdminsVectorSearch {
 }
 /**
  * @interface IAdminsResponse
- * @property {IAdminEntity[]} items - Array of found admin objects.
+ * @property {IAdminEntity[]} items - Admins that match the query.
  * @property {number} total - Total number of found records. Example: 100.
  * @description This interface defines the structure of a response containing multiple admin entities, including the total count and an array of admin items.
  */
@@ -73,12 +73,12 @@ interface IAdminsResponse {
 /**
  * Interface representing a Position entity.
  * @interface IPosition
- * @property {number} id - The unique identifier of the position. Example: 1764.
+ * @property {number} id - ID of the object. Example: 1764.
  * @property {boolean} [isLocked] - Indicates whether the position is locked or not. Example: false.
  * @property {number} objectId - The unique identifier of the object. Example: 120.
  * @property {number} [objectCategoryId] - The unique identifier of the object's category. Example: 5.
  * @property {string} objectType - The type of the object. Example: "admin".
- * @property {number} position - The position of the object. Example: 192.
+ * @property {number} position - Position of the object, used for sorting. Example: 192.
  * @description This interface outlines the properties associated with a position within a system.
  */
 interface IPosition {
@@ -92,13 +92,13 @@ interface IPosition {
 /**
  * Interface representing an Admin Entity.
  * @interface IAdminEntity
- * @property {number} id - The identifier of the object. Example: 1764.
- * @property {number | null} attributeSetId - The identifier of the attribute set being used. Example: 120.
- * @property {string} identifier - The textual identifier for the record field. Example: "admin1".
- * @property {string | null} attributeSetIdentifier - The identifier of the attribute set. Example: "admins".
- * @property {number | null} position - Position number (for sorting). Example: 1.
- * @property {boolean} isSync - Page indexing flag (true or false). Example: true.
- * @property {IAttributeValues} attributeValues - Array of attribute values from the index (presented as a pair of user attribute identifier: attribute value).
+ * @property {number} id - Object ID. Example: 1764.
+ * @property {number | null} attributeSetId - ID of the attribute set in use. Example: 120.
+ * @property {string} identifier - Text identifier (marker) of the object. Example: "admin1".
+ * @property {string | null} attributeSetIdentifier - Marker of the attribute set. Example: "admins".
+ * @property {number | null} position - Position used for sorting. Example: 1.
+ * @property {boolean} isSync - Whether the page is indexed. Example: true.
+ * @property {IAttributeValues} attributeValues - Attribute values keyed by attribute marker.
  * @example
     [
       {
@@ -108,7 +108,7 @@ interface IPosition {
         }
       }
     ]
- * @property {IFormConfig[]} [moduleFormConfigs] - Array of module form configurations associated with the admin.
+ * @property {IFormConfig[]} [moduleFormConfigs] - Form configurations of the module associated with the admin.
  * @property {number} [distance] - Cosine distance to the query. Returned only by the semantic (vector) search endpoint when `debug: true` is passed in the search body. Example: 0.12.
  * @description This interface captures the essential details and additional attributes of an admin entity.
  */
@@ -127,8 +127,8 @@ interface IAdminEntity {
  * Interface representing a query for fetching admin data.
  * @interface IAdminQuery
  * @property {string} langCode - Language code. Default: "en_US".
- * @property {number} limit - Parameter for pagination. Default: 30.
- * @property {number} offset - Parameter for pagination. Default: 0.
+ * @property {number} limit - Maximum number of records to return. Default: 30.
+ * @property {number} offset - Number of records to skip. Default: 0.
  * @description This interface defines the parameters required for querying admin data, including optional defaults.
  */
 interface IAdminQuery {

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

@@ -24,10 +24,10 @@ export default class AttributesSetsApi extends AsyncModules implements IAttribut
      * Getting all attribute sets objects.
      * @handleName getAttributes
      * @param {string} [langCode] - Language code. Default: "en_US".
-     * @param {number} [offset] - parameter offset of record selection. Default: 0.
-     * @param {number} [limit] - parameter limiting the selection of records. Default: 30.
-     * @param {number} [typeId] - identifier of the attribute set type. Default: null.
-     * @param {string} [sortBy] - identifier of the attribute set type. Default: "id".
+     * @param {number} [offset] - Number of records to skip. Default: 0.
+     * @param {number} [limit] - Maximum number of records to return. Default: 30.
+     * @param {number} [typeId] - ID of the attribute set type to filter by. Default: null.
+     * @param {string} [sortBy] - Field to sort by: `id` or `position`. Default: "id".
      * @returns {Promise<IAttributesSetsResponse | IError>} Returns object with array of IAttributeSetsEntity and total items count.
      * @throws {IError} When isShell=false and an error occurs during the fetch
      * @see {@link https://js-sdk.oneentry.cloud/docs/attribute-sets/getAttributes getAttributes} documentation.
@@ -36,7 +36,7 @@ export default class AttributesSetsApi extends AsyncModules implements IAttribut
     /**
      * Getting all attributes with data from the attribute set.
      * @handleName getAttributesByMarker
-     * @param {string} marker - Attribute marker. Example: "productAttributes".
+     * @param {string} marker - Marker of the attribute. Example: "productAttributes".
      * @param {string} [langCode] - Language code. Default: "en_US".
      * @returns {Promise<IAttributesSetsEntity[] | IError>} Returns an array of Attributes objects.
      * @throws {IError} When isShell=false and an error occurs during the fetch
@@ -46,8 +46,8 @@ export default class AttributesSetsApi extends AsyncModules implements IAttribut
     /**
      * Get a single attribute with data from the attribute sets.
      * @handleName getSingleAttributeByMarkerSet
-     * @param {string} setMarker - Text identifier (marker) of the attribute set. Example: "productAttributes".
-     * @param {string} attributeMarker - Text identifier (marker) of the attribute in the set. Example: "color".
+     * @param {string} setMarker - Marker of the attribute set. Example: "productAttributes".
+     * @param {string} attributeMarker - Marker of the attribute in the set. Example: "color".
      * @param {string} [langCode] - Language code. Default: "en_US".
      * @returns {Promise<IAttributesSetsEntity | IError>} Returns a single attribute object from the attribute set.
      * @throws {IError} When isShell=false and an error occurs during the fetch
@@ -57,7 +57,7 @@ export default class AttributesSetsApi extends AsyncModules implements IAttribut
     /**
      * Getting a single object from a set of attributes by marker.
      * @handleName getAttributeSetByMarker
-     * @param {string} marker - marker of the attribute set object. Example: "productAttributes".
+     * @param {string} marker - Marker of the attribute set. Example: "productAttributes".
      * @param {string} [langCode] - Language code. Default: "en_US".
      * @returns {Promise<IAttributeSetsEntity | IError>} Returns one object of the attribute set.
      * @throws {IError} When isShell=false and an error occurs during the fetch

package/dist/attribute-sets/attributeSetsApi.js

@@ -62,10 +62,10 @@ class AttributesSetsApi extends asyncModules_1.default {
      * Getting all attribute sets objects.
      * @handleName getAttributes
      * @param {string} [langCode] - Language code. Default: "en_US".
-     * @param {number} [offset] - parameter offset of record selection. Default: 0.
-     * @param {number} [limit] - parameter limiting the selection of records. Default: 30.
-     * @param {number} [typeId] - identifier of the attribute set type. Default: null.
-     * @param {string} [sortBy] - identifier of the attribute set type. Default: "id".
+     * @param {number} [offset] - Number of records to skip. Default: 0.
+     * @param {number} [limit] - Maximum number of records to return. Default: 30.
+     * @param {number} [typeId] - ID of the attribute set type to filter by. Default: null.
+     * @param {string} [sortBy] - Field to sort by: `id` or `position`. Default: "id".
      * @returns {Promise<IAttributesSetsResponse | IError>} Returns object with array of IAttributeSetsEntity and total items count.
      * @throws {IError} When isShell=false and an error occurs during the fetch
      * @see {@link https://js-sdk.oneentry.cloud/docs/attribute-sets/getAttributes getAttributes} documentation.
@@ -89,7 +89,7 @@ class AttributesSetsApi extends asyncModules_1.default {
     /**
      * Getting all attributes with data from the attribute set.
      * @handleName getAttributesByMarker
-     * @param {string} marker - Attribute marker. Example: "productAttributes".
+     * @param {string} marker - Marker of the attribute. Example: "productAttributes".
      * @param {string} [langCode] - Language code. Default: "en_US".
      * @returns {Promise<IAttributesSetsEntity[] | IError>} Returns an array of Attributes objects.
      * @throws {IError} When isShell=false and an error occurs during the fetch
@@ -104,8 +104,8 @@ class AttributesSetsApi extends asyncModules_1.default {
     /**
      * Get a single attribute with data from the attribute sets.
      * @handleName getSingleAttributeByMarkerSet
-     * @param {string} setMarker - Text identifier (marker) of the attribute set. Example: "productAttributes".
-     * @param {string} attributeMarker - Text identifier (marker) of the attribute in the set. Example: "color".
+     * @param {string} setMarker - Marker of the attribute set. Example: "productAttributes".
+     * @param {string} attributeMarker - Marker of the attribute in the set. Example: "color".
      * @param {string} [langCode] - Language code. Default: "en_US".
      * @returns {Promise<IAttributesSetsEntity | IError>} Returns a single attribute object from the attribute set.
      * @throws {IError} When isShell=false and an error occurs during the fetch
@@ -120,7 +120,7 @@ class AttributesSetsApi extends asyncModules_1.default {
     /**
      * Getting a single object from a set of attributes by marker.
      * @handleName getAttributeSetByMarker
-     * @param {string} marker - marker of the attribute set object. Example: "productAttributes".
+     * @param {string} marker - Marker of the attribute set. Example: "productAttributes".
      * @param {string} [langCode] - Language code. Default: "en_US".
      * @returns {Promise<IAttributeSetsEntity | IError>} Returns one object of the attribute set.
      * @throws {IError} When isShell=false and an error occurs during the fetch

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

@@ -30,12 +30,12 @@ interface IAttributesSets {
 /**
  * Represents the structure of a list item.
  * @interface IListTitle
- * @property {string} title - The title or name associated with the list item. Example: "Item Name".
- * @property {number | string} value - The value of the list item, which can be either a number or a string depending on the context. Example: 42.
- * @property {string | number | null} position - The position of the list item, which can be represented as a string, number, or null if not applicable. Example: 1.
- * @property {object} extended - An object containing additional properties or metadata related to the list item. This could include any extra details that extend the basic information.
- * @property {string | null} extended.value - The extended value, which can be a string or null. Example: "extra_value".
- * @property {string | null} extended.type - The type of the extended value, which can be a string or null. Example: "color".
+ * @property {string} title - Title of the list item. Example: "Item Name".
+ * @property {number | string} value - Value of the list item: a number or a string. Example: 42.
+ * @property {string | number | null} position - Position of the list item: a number, a string, or `null`. Example: 1.
+ * @property {object} extended - Additional properties of the list item.
+ * @property {string | null} extended.value - Extended value, or `null`. Example: "extra_value".
+ * @property {string | null} extended.type - Type of the extended value, or `null`. Example: "color".
  * @description This interface defines the structure of a list item, which includes properties for the title, value, position, and extended information.
  */
 interface IListTitle {
@@ -84,9 +84,9 @@ type AttributeType = 'string' | 'text' | 'textWithHeader' | 'integer' | 'real' |
  * @property {AttributeType} type - Attribute type. Example: "string", "text", "integer", "etc".
  * @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.
- * @property {IListTitle[]} listTitles - Array of values (with extended data) for list and radioButton attributes; empty array for non-list types.
+ * @property {string} marker - Marker of the attribute. Example: "color", "size", "etc".
+ * @property {number} position - Position used for sorting. Example: 1.
+ * @property {IListTitle[]} listTitles - Options with extended data for `list` and `radioButton` attributes; empty array for other types.
  * @example
     [
       {
@@ -104,7 +104,7 @@ type AttributeType = 'string' | 'text' | 'textWithHeader' | 'integer' | 'real' |
         "extendedValueType": null
       }
     ]
- * @property {IAttributeValidators} validators - Set of validators for validation; empty object when no validators are configured.
+ * @property {IAttributeValidators} validators - Validators configured for the attribute; empty object when none are set.
  * @example
     {
       "requiredValidator": {
@@ -114,12 +114,12 @@ type AttributeType = 'string' | 'text' | 'textWithHeader' | 'integer' | 'real' |
         "fieldDefaultValue": 11
       }
     }
- * @property {IAttributeLocalizeInfo} localizeInfos - The name of the template, taking into account localization.
+ * @property {IAttributeLocalizeInfo} localizeInfos - Localized name of the template.
  * @example
    {
      "title": "My attribute"
    }
- * @property {Record<string, IAttributesSetsEntity>} additionalFields - Nested sub-attributes keyed by marker; empty object when none.
+ * @property {Record<string, IAttributesSetsEntity>} additionalFields - Nested sub-attributes keyed by marker; an empty object when there are none.
  * @description This interface defines the structure of an attribute set entity, including its type, marker, position, validators, localization information, list titles, additional fields, and settings.
  */
 interface IAttributesSetsEntity {
@@ -193,20 +193,20 @@ interface IAttributeSchemaItem {
  * @property {object | boolean} [trimValidator] - Leading and trailing whitespace is stripped from the value. Stored as an empty object when the toggle is on. Example: `{}`.
  * @property {object} [stringInspectionValidator] - Length constraints for string fields. Example: `{ stringLength: 0, stringMin: 2, stringMax: 60 }`.
  * @property {object | boolean} [urlInspectionValidator] - Value must look like a URL. Stored either as `true` or as an object. Example: `true`.
- * @property {object | boolean} [emailInspectionValidator] - Value must look like an e-mail address. Stored either as `true` or as an object. Example: `true`.
- * @property {object} [checkForNumberValidator] - Value must be a number, optionally an integer within bounds. `0` disables a bound. Example: `{ integerOnly: true, minValue: 1, maxValue: 10 }`.
+ * @property {object | boolean} [emailInspectionValidator] - The value must look like an email address. Stored either as `true` or as an object. Example: `true`.
+ * @property {object} [checkForNumberValidator] - The value must be a number, optionally an integer within bounds. `0` disables a bound. Example: `{ integerOnly: true, minValue: 1, maxValue: 10 }`.
  * @property {object} [roundingNumberValidator] - Rounds the number before storing it. Example: `{ integerOnly: false, numberOfDecimals: 2, direction: 'round' }`.
- * @property {object} [booleanValidator] - Value must equal one of the two declared values. Example: `{ trueValue: 1, falseValue: 0 }`.
+ * @property {object} [booleanValidator] - The value must equal one of the two declared values. Example: `{ trueValue: 1, falseValue: 0 }`.
  * @property {object} [comparisonValidator] - Compares the value with another attribute or with a constant. Example: `{ compareAttribute: 'notChoosed', compareValue: '10', type: 'number', operator: 'equality' }`.
  * @property {object} [regExpValidator] - Value must match a regular expression; `invert` refuses matches instead. Example: `{ patternValue: '^[0-9]{5}$', invert: false, flags: ['i'] }`.
  * @property {object} [fieldMaskValidator] - Value must match an input mask (`9` digit, `A` upper letter, `a` lower letter, `*` any, `$` one of `()+-`). Example: `{ maskValue: '+9 (999) 999-99-99' }`.
- * @property {object} [checkForAGivenList] - Value must be in the list, or outside it when `notValue` is true. Example: `{ rangeValue: ['red', 'green'], notValue: false }`.
- * @property {object} [defaultValueValidator] - Value substituted when the field is left empty. Example: `{ fieldDefaultValue: 'USD' }`.
+ * @property {object} [checkForAGivenList] - The value must be in the list, or outside it when `notValue` is `true`. Example: `{ rangeValue: ['red', 'green'], notValue: false }`.
+ * @property {object} [defaultValueValidator] - Value used when the field is left empty. Example: `{ fieldDefaultValue: 'USD' }`.
  * @property {object} [sizeInPixelsValidator] - Image bounds in pixels; executed by the admin panel. Example: `{ maxX: 1920, maxY: 1080 }`.
- * @property {object} [checkingFilesValidator] - File size bounds and allowed extensions; executed by the admin panel. Example: `{ minValue: 0, maxValue: 5, minUnits: 'kb', maxUnits: 'mb', extensions: ['pdf'] }`.
- * @property {object} [minMaxDateValidator] - Date bounds; executed by the admin panel. Example: `{ minDateTimeValue: '2026-01-01', maxDateTimeValue: '2026-12-31' }`.
+ * @property {object} [checkingFilesValidator] - File size bounds and allowed extensions; run by the admin panel. Example: `{ minValue: 0, maxValue: 5, minUnits: 'kb', maxUnits: 'mb', extensions: ['pdf'] }`.
+ * @property {object} [minMaxDateValidator] - Date bounds. The admin panel enforces them. Example: `{ minDateTimeValue: '2026-01-01', maxDateTimeValue: '2026-12-31' }`.
  * @property {object} [valueValidator] - The panel's "default value" control; it writes `defaultValueValidator`, and this name is kept because the API accepts and stores it. Example: `{ fieldDefaultValue: 'USD' }`.
- * @property {object} [checkForLettersValidator] - Letters-only check by pattern; executed by the admin panel. Example: `{ patternValue: '^[A-Za-z ]+$' }`.
+ * @property {object} [checkForLettersValidator] - Letters-only check by pattern; run by the admin panel. Example: `{ patternValue: '^[A-Za-z ]+$' }`.
  * @description Map of validators applied to an attribute or form field, keyed by validator name.
  *
  * These eighteen names are the full set the API accepts in
@@ -317,12 +317,12 @@ interface IAttributeValidators {
 /**
  * Represents an attribute set entity.
  * @interface IAttributeSetsEntity
- * @property {number} id - The unique identifier of the attribute set entity. Example: 123.
- * @property {string} createdDate - The date when the attribute set was created. Example: "2023-10-01T12:00:00Z".
- * @property {string} updatedDate - The date when the attribute set was last updated. Example: "2023-10-01T12:00:00Z".
- * @property {number} version - The version number of the attribute set, used for tracking changes or updates. Example: 1.
- * @property {string} identifier - A string that uniquely identifies the attribute set. Example: "attributeSet1".
- * @property {string} title - The title or name of the attribute set. Example: "Product Attributes".
+ * @property {number} id - ID of the attribute set. Example: 123.
+ * @property {string} createdDate - Creation date of the attribute set. Example: "2023-10-01T12:00:00Z".
+ * @property {string} updatedDate - Date the attribute set was last updated. Example: "2023-10-01T12:00:00Z".
+ * @property {number} version - Version number of the attribute set; changes with each update. Example: 1.
+ * @property {string} identifier - Marker of the attribute set. Example: "attributeSet1".
+ * @property {string} title - Name of the attribute set. Example: "Product Attributes".
  * @property {Record<string, IAttributeSchemaItem>} schema - Schema fields keyed by marker.
  * @example
    {
@@ -337,9 +337,9 @@ interface IAttributeValidators {
        }
      }
    }
- * @property {boolean} isVisible - Indicates whether the attribute set is visible or not. Example: true.
- * @property {string} type - The type of the attribute set, which could be a specific classification or category. Example: "product", "user", "etc".
- * @property {number} position - The position number for sorting the attribute set. Example: 1.
+ * @property {boolean} isVisible - Whether the attribute set is visible. Example: true.
+ * @property {string} type - Type of the attribute set. Example: "product", "user", "etc".
+ * @property {number} position - Position of the attribute set, used for sorting. Example: 1.
  * @description This interface defines the structure of an attribute set entity.
  */
 interface IAttributeSetsEntity {
@@ -367,8 +367,8 @@ interface IAttributeSetTypeRef {
 /**
  * Represents the response structure for attribute sets.
  * @interface IAttributesSetsResponse
- * @property {number} total - Total items. Example: 100.
- * @property {IAttributeSetsEntity[]} items - IAttributeSetsEntity array containing attribute set entities.
+ * @property {number} total - Total number of attribute sets. Example: 100.
+ * @property {IAttributeSetsEntity[]} items - Attribute sets in this response.
  * @example
     [
      {