oneentry 1.0.175 → 1.0.177

package/esm/forms-data/formsDataInterfaces.d.ts

@@ -85,9 +85,9 @@ interface IFormsData {
 /**
  * Body for semantic (vector) form data search.
  * @interface IFormsDataVectorSearch
- * @property {string} queryText - Natural-language search query. Example: "order confirmation".
- * @property {number} [vectorDistanceThreshold] - Override of the cosine distance threshold (0..2). Example: 0.3.
- * @property {number} [maxHits] - Number of top candidates fetched before pagination. Default: 100. Maximum: 500. Example: 10.
+ * @property {string} queryText - Natural-language search query, 1 to 512 characters: an empty one answers `400 queryText should not be empty`, a longer one `400 queryText must be shorter than or equal to 512 characters`. Example: "order confirmation".
+ * @property {number} [vectorDistanceThreshold] - Override of the cosine distance threshold (0..2); a negative value answers `400`. Example: 0.3.
+ * @property {number} [maxHits] - Number of top candidates fetched before pagination, from 1. Default: 100. Maximum: 500. Example: 10.
  * @property {boolean} [debug] - When `true`, each returned item gets a `distance` field. Example: false.
  * @description Body for the form-data vector/search endpoint.
  */
@@ -113,14 +113,14 @@ type FormDataStatus = 'sent' | 'moderation' | 'approved' | 'banned' | 'deleted';
  * @property {number} [parentId] - Identifier of the parent record — the way to fetch replies to one comment. Example: 10.
  * @property {string} [userIdentifier] - Text identifier of the sender; an empty string means "no filter". Example: "admin".
  * @property {FormDataStatus[]} [status] - Moderation statuses to keep. Must be an array — a bare string is rejected with `400`. An empty array means "no filter". Example: ["approved"].
- * @property {string} [dateFrom] - Lower bound of the submission date, `YYYY-MM-DD`; an empty string means "no bound" — `getFormsDataByMarker` strips it from the body, since the endpoint rejects an empty date with a `400`. A non-empty value the API cannot parse still fails the request. Example: "2025-01-01".
- * @property {string} [dateTo] - Upper bound of the submission date, `YYYY-MM-DD`; an empty string means "no bound", handled like `dateFrom`. Example: "2025-12-31".
+ * @property {string} [dateFrom] - Lower bound of the submission date, `YYYY-MM-DD` or `YYYY-MM-DD HH:MM:SS`; an empty string means "no bound" — `getFormsDataByMarker` strips it from the body, since the endpoint rejects an empty date with a `400`. A non-empty value the API cannot parse still fails the request. Example: "2025-01-01".
+ * @property {string} [dateTo] - Upper bound of the submission date, `YYYY-MM-DD` or `YYYY-MM-DD HH:MM:SS`; an empty string means "no bound", handled like `dateFrom`. Example: "2025-12-31".
  * @description Filter for reading form submissions. Every field is optional and an omitted one is simply not applied.
  *
- * Typed rather than left as `object` on purpose: the API **ignores** a field it
- * does not know, so `statuses: ['approved']` (note the "s") is not an error —
- * it returns every record, unmoderated ones included. That is premoderation
- * leaking onto a public page, from one typo the compiler used to accept.
+ * Typed rather than left as `object` on purpose: the API **refuses** a field it
+ * does not know, so `statuses: ['approved']` (note the "s") answers
+ * `400 property statuses should not exist` — the compiler catches the typo
+ * before the request does.
  */
 interface IFormsDataFilter {
     /**
@@ -225,9 +225,14 @@ interface IFormDataEntity {
         "id": 1,
         "formIdentifier": "form",
         "time": "2025-06-06T19:07:45.993Z",
-        "formData": {},
-        "attributeSetIdentifier": "form",
-        "actionMessage": "Action message string"
+        "formData": [
+          {
+            "marker": "name",
+            "type": "string",
+            "value": "Test"
+          }
+        ],
+        "attributeSetIdentifier": "form"
       }
     ]
  * @property {number} total - Total number of found records. Example: 100.
@@ -241,13 +246,13 @@ interface IFormsDataEntity {
  * Represents the structure of a form data entity.
  * @interface IFormByMarkerDataEntity
  * @property {number} id - ID of the form data record. Example: 12345.
- * @property {null | number} parentId - ID of the parent form data record; `null` for a top-level record. Example: 123.
+ * @property {null | number} [parentId] - ID of the parent form data record; `null` for a top-level record. Returned only with `isExtended` = 1. Example: 123.
  * @property {string} formIdentifier - Marker of the form. Example: "contact_form".
- * @property {number} depth - Example: 1.
- * @property {string | null} ip - IP address the form was submitted from. Example: '127.0.0.1'.
- * @property {string | null} fingerprint - Device fingerprint of the sender. Example: 'fingerprint'.
- * @property {string | null} status - Moderation status of the record: "sent", "moderation", "approved", "banned" or "deleted"; `null` when the form does not moderate. Example: 'approved'.
- * @property {string | null} userIdentifier - Text identifier (marker) of the user. Example: "admin".
+ * @property {number} [depth] - Nesting depth of the record. Returned only with `isExtended` = 1. Example: 1.
+ * @property {string | null} [ip] - IP address the form was submitted from. Not returned by the by-marker list. Example: '127.0.0.1'.
+ * @property {string | null} [fingerprint] - Device fingerprint of the sender. Not returned by the by-marker list. Example: 'fingerprint'.
+ * @property {string | null} [status] - Moderation status of the record: "sent", "moderation", "approved", "banned" or "deleted"; `null` when the form does not moderate. Returned only with `isExtended` = 1. Example: 'approved'.
+ * @property {string | null} [userIdentifier] - Text identifier (marker) of the user. Returned only with `isExtended` = 1. Example: "admin".
  * @property {FormDataType[]} formData - Submitted fields, **already unwrapped from the locale**: the API returns `{ "en_US": [ … ] }` and the SDK hands over the array for the requested `langCode`. Read `formData` directly — `formData[langCode]` is `undefined`.
  * @example
     [
@@ -260,7 +265,7 @@ interface IFormsDataEntity {
  * @property {string | null} attributeSetIdentifier - Marker of the attribute set used by the form. Example: "product_attributes".
  * @property {Date | string} time - Date and time the form data was last changed. Example: "2023-10-01T12:00:00Z".
  * @property {string} entityIdentifier - Marker of the entity the record belongs to. Example: "test".
- * @property {boolean} isUserAdmin - Whether the record was submitted by an admin. Example: true.
+ * @property {boolean} [isUserAdmin] - Whether the record was submitted by an admin. Returned only with `isExtended` = 1. Example: true.
  * @property {number} formModuleConfigId - ID of the form module configuration. Example: 2.
  * @property {string} [moduleIdentifier] - Marker of the module. Example: "blog".
  * @property {number} entityId - ID of the entity the record belongs to. Example: 2.
@@ -287,7 +292,7 @@ interface IFormByMarkerDataEntity {
 /**
  * Represents a collection of form data entities.
  * @interface IFormsByMarkerDataEntity
- * @property {IFormByMarkerDataEntity[]} items - Form data records.
+ * @property {IFormByMarkerDataEntity[]} items - Form data records. The example shows a record with `isExtended` = 1; without it `parentId`, `depth`, `status`, `userIdentifier` and `isUserAdmin` are not returned.
  * @example
     [
       {
@@ -295,7 +300,6 @@ interface IFormByMarkerDataEntity {
         "parentId": null,
         "formIdentifier": "test-form",
         "depth": 0,
-        "ip": null,
         "status": null,
         "userIdentifier": null,
         "formData": [
@@ -419,7 +423,7 @@ interface IUpdateFormsData {
 /**
  * Contains an array of data form objects with the following values
  */
-type FormDataType = IBodyTypeStringNumberFloat | IBodyTypeTimeDate | IBodyTypeText | IBodyTypeTextWithHeader | IBodyTypeImageGroupOfImages | IBodyTypeFile | IBodyTypeRadioButtonList | Record<string, unknown>;
+type FormDataType = IBodyTypeStringNumberFloat | IBodyTypeTimeDate | IBodyTypeText | IBodyTypeTextWithHeader | IBodyTypeImageGroupOfImages | IBodyTypeFile | IBodyTypeRadioButtonList | IBodyTypeEntity | IBodyTypeTimeInterval | Record<string, unknown>;
 /**
  * Value shapes accepted by a SUBMISSION (`POST /form-data`).
  *
@@ -588,13 +592,13 @@ interface IBodyPostFormData {
  * Represents a form data entity with a simple value.
  * @interface IBodyTypeStringNumberFloat
  * @property {string} marker - marker name. Example: "some_marker".
- * @property {string} type - Type value. "string" | "number" | "float". Example: "string".
- * @property {string | number | null} value - Value of the form data entity. Send it as a string; in responses numeric fields come back normalized to `number`, or `null` when the field is empty. Example: "string".
+ * @property {string} type - Type value. "string" | "integer" | "number" | "float". Example: "string".
+ * @property {string | number | null} value - Value of the form data entity. A submission may send a number or a string; responses return numeric fields **as strings** — `3` comes back as `"3"`, `2.565` as `"2.565"` — or `null` when the field is empty. Convert with `Number(value)` before arithmetic. Example: "string".
  * @description Represents a form data entity with a marker, type, and value.
  */
 interface IBodyTypeStringNumberFloat {
     marker: string;
-    type: 'string' | 'number' | 'float';
+    type: 'string' | 'integer' | 'number' | 'float';
     value: string | number | null;
 }
 /**
@@ -633,43 +637,46 @@ interface ITimeDateValue {
  * @interface IBodyTypeText
  * @property {string} marker - marker name. Example: "some_marker".
  * @property {string} type - Type value. Example: "text".
- * @property {object} value - Text Object. Contains html as string, plain text and params.
+ * @property {ITextValue | ITextValue[]} value - Text value. A read returns a one-element **array**, without `plainValue` and with `params.editorMode`; older records may hold a single object.
  * @example
-    {
-      "htmlValue": "<p>Hello world</p>",
-      "plainValue": "",
-      "params": {
-        "isEditorDisabled": false,
-        "isImageCompressed": true
+    [
+      {
+        "htmlValue": "<p>Hello world</p>",
+        "params": {
+          "isImageCompressed": true,
+          "editorMode": "html"
+        }
       }
-    }
- * @description Represents a text value with HTML and plain text representations, along with parameters for editor and image compression settings.
+    ]
+ * @description Represents a text value with HTML and plain text representations, along with parameters for editor and image compression settings. To submit a text field use {@link IBodyPostTypeText}.
  */
 interface IBodyTypeText {
     marker: string;
     type: 'text';
-    value: ITextValue;
+    value: ITextValue | ITextValue[];
 }
 /**
  * @interface ITextEditorParams
- * @property {boolean} isEditorDisabled - Whether the rich-text editor is disabled. Example: false.
+ * @property {boolean} [isEditorDisabled] - Whether the rich-text editor is disabled. Older records only; current reads carry `editorMode` instead. Example: false.
  * @property {boolean} isImageCompressed - Whether embedded images are compressed. Example: true.
+ * @property {string} [editorMode] - Editor the value was written in. Example: "html".
  * @description Editor parameters attached to text-type form values.
  */
 interface ITextEditorParams {
-    isEditorDisabled: boolean;
+    isEditorDisabled?: boolean;
     isImageCompressed: boolean;
+    editorMode?: string;
 }
 /**
  * @interface ITextValue
  * @property {string} htmlValue - HTML representation of the text. Example: "<p>Hello world</p>".
- * @property {string} plainValue - Plain-text representation.
+ * @property {string} [plainValue] - Plain-text representation. Absent from current reads. Example: "Hello world".
  * @property {ITextEditorParams} params - Editor configuration applied to this value.
  * @description Value payload for `text` form fields.
  */
 interface ITextValue {
     htmlValue: string;
-    plainValue: string;
+    plainValue?: string;
     params: ITextEditorParams;
 }
 /**
@@ -677,36 +684,37 @@ interface ITextValue {
  * @interface IBodyTypeTextWithHeader
  * @property {string} marker - marker name. Example: "about".
  * @property {string} type - Type value. Example: "textWithHeader".
- * @property {object} value - Text Object. Contains html as string, header and params.
+ * @property {ITextWithHeaderValue | ITextWithHeaderValue[]} value - Text with a header. A read returns a one-element **array**, without `plainValue` and with `params.editorMode`; older records may hold a single object.
  * @example
-    {
-      "header": "Headline",
-      "htmlValue": "<p>Hello World</p>",
-      "plainValue": "",
-      "params": {
-        "isEditorDisabled": false,
-        "isImageCompressed": true
+    [
+      {
+        "header": "Headline",
+        "htmlValue": "<p>Hello World</p>",
+        "params": {
+          "isImageCompressed": true,
+          "editorMode": "html"
+        }
       }
-    }
+    ]
  * @description Represents a text value with a header, HTML and plain text representations, along with parameters for editor and image compression settings.
  */
 interface IBodyTypeTextWithHeader {
     marker: string;
     type: 'textWithHeader';
-    value: ITextWithHeaderValue;
+    value: ITextWithHeaderValue | ITextWithHeaderValue[];
 }
 /**
  * @interface ITextWithHeaderValue
  * @property {string} header - Headline text. Example: "Headline".
  * @property {string} htmlValue - HTML body. Example: "<p>Hello world</p>".
- * @property {string} plainValue - Plain-text body.
+ * @property {string} [plainValue] - Plain-text body. Absent from current reads. Example: "Hello world".
  * @property {ITextEditorParams} params - Editor configuration applied to this value.
  * @description Value payload for `textWithHeader` form fields.
  */
 interface ITextWithHeaderValue {
     header: string;
     htmlValue: string;
-    plainValue: string;
+    plainValue?: string;
     params: ITextEditorParams;
 }
 /**
@@ -765,7 +773,7 @@ interface IImageValue {
  * @interface IBodyTypeFile
  * @property {string} marker - marker name. Example: "picture".
  * @property {'file'} type - Type value. Example: "file".
- * @property {object} value - The attached file. Three shapes are accepted and may be mixed in one array: a `File`/`Blob` (also a `FileList`), which the SDK uploads first; the descriptor `FileUploading.upload` returns for a file **already in storage**, which is passed through as it is; or a hand-built {@link IFileValue}. In a SUBMISSION the value must be an **array** — a lone descriptor or {@link IFileValue} answers `400 formData's marker '<marker>' value must be an array`, while a lone `File`/`Blob` is fine because the SDK wraps the upload result. A READ returns a single attached file as the object itself.
+ * @property {object} value - The attached file. Three shapes are accepted and may be mixed in one array: a `File`/`Blob` (also a `FileList`), which the SDK uploads first; the descriptor `FileUploading.upload` returns for a file **already in storage**, which is passed through as it is; or a hand-built {@link IFileValue}. In a SUBMISSION the value must be an **array** — a lone descriptor or {@link IFileValue} answers `400 formData's marker '<marker>' value must be an array`, while a lone `File`/`Blob` is fine because the SDK wraps the upload result. A READ returns the files as an array too — a single attached file is a one-element array.
  * @example
     [
       {
@@ -800,24 +808,41 @@ interface IFileValue {
  * @interface IBodyTypeRadioButtonList
  * @property {string} marker - marker name. Example: "selector".
  * @property {string} type - Type value. Example: 'list'.
- * @property {Array} value - Array of list or radioButton bojects.
+ * @property {IListOptionValue[] | string[] | string} value - Chosen option(s). A read of a submission returns the option **values as stored**: `list` — an array of strings (`["1"]`), `radioButton` — one string (`"1"`). The `[{ title, value, extended }]` form is the shape of a page attribute.
  * @example
-    [
-      {
-        "title": "red",
-        "value": "1",
-        "extended": {
-          "value": "red",
-          "type": "string"
-        }
-      }
-    ]
- * @description Represents a list or radio button selection with multiple options, each containing a title, value, and extended information.
+    ["1"]
+ * @description Represents a list or radio button selection. Look the titles up in the form's attribute (`Forms.getFormByMarker`) by the stored value.
  */
 interface IBodyTypeRadioButtonList {
     marker: string;
     type: 'list' | 'radioButton';
-    value: IListOptionValue[];
+    value: IListOptionValue[] | string[] | string;
+}
+/**
+ * Represents an `entity` form data field — links to other entities.
+ * @interface IBodyTypeEntity
+ * @property {string} marker - marker name. Example: "related".
+ * @property {'entity'} type - Type value. Example: "entity".
+ * @property {number[]} value - Identifiers of the linked entities. Example: [2954, 2957].
+ * @description A form field that stores links to other entities (for example products) by id.
+ */
+interface IBodyTypeEntity {
+    marker: string;
+    type: 'entity';
+    value: number[];
+}
+/**
+ * Represents a `timeInterval` form data field.
+ * @interface IBodyTypeTimeInterval
+ * @property {string} marker - marker name. Example: "booking".
+ * @property {'timeInterval'} type - Type value. Example: "timeInterval".
+ * @property {string[][]} value - Intervals as `[start, end]` pairs of ISO dates. Example: [["2025-02-11T16:00:00.000Z", "2025-02-13T16:00:00.000Z"]].
+ * @description A form field that stores one or more time intervals.
+ */
+interface IBodyTypeTimeInterval {
+    marker: string;
+    type: 'timeInterval';
+    value: string[][];
 }
 /**
  * @interface IListOptionExtended
@@ -841,4 +866,4 @@ interface IListOptionValue {
     value: string;
     extended: IListOptionExtended;
 }
-export type { FormDataPostType, FormDataStatus, FormDataType, IBodyPostFormData, IBodyPostTypeList, IBodyPostTypeSpam, IBodyPostTypeText, IBodyTypeFile, IBodyTypeImageGroupOfImages, IBodyTypeRadioButtonList, IBodyTypeStringNumberFloat, IBodyTypeText, IBodyTypeTextWithHeader, IBodyTypeTimeDate, ICaptchaEvent, ICaptchaValue, IFileValue, IFormByMarkerDataEntity, IFormDataEntity, IFormDataSearchEntity, IFormsByMarkerDataEntity, IFormsData, IFormsDataEntity, IFormsDataFilter, IFormsDataSearchResponse, IFormsDataVectorSearch, IImageValue, IImageValueParams, IListOptionExtended, IListOptionValue, IPostFormResponse, IPostFormResponseData, ITextEditorParams, ITextSubmissionValue, ITextValue, ITextWithHeaderValue, ITimeDateValue, IUpdateFormsData, };
+export type { FormDataPostType, FormDataStatus, FormDataType, IBodyPostFormData, IBodyPostTypeList, IBodyPostTypeSpam, IBodyPostTypeText, IBodyTypeEntity, IBodyTypeFile, IBodyTypeImageGroupOfImages, IBodyTypeRadioButtonList, IBodyTypeStringNumberFloat, IBodyTypeText, IBodyTypeTextWithHeader, IBodyTypeTimeDate, IBodyTypeTimeInterval, ICaptchaEvent, ICaptchaValue, IFileValue, IFormByMarkerDataEntity, IFormDataEntity, IFormDataSearchEntity, IFormsByMarkerDataEntity, IFormsData, IFormsDataEntity, IFormsDataFilter, IFormsDataSearchResponse, IFormsDataVectorSearch, IImageValue, IImageValueParams, IListOptionExtended, IListOptionValue, IPostFormResponse, IPostFormResponseData, ITextEditorParams, ITextSubmissionValue, ITextSubmissionValueHtml, ITextSubmissionValueMd, ITextSubmissionValuePlain, ITextValue, ITextWithHeaderValue, ITimeDateValue, IUpdateFormsData, };

package/esm/general-types/generalTypesInterfaces.d.ts

@@ -19,7 +19,7 @@ interface IGeneralTypes {
  * Represents a general type entity.
  * @interface IGeneralTypesEntity
  * @property {number} id - ID of the type. Example: 1.
- * @property {BlockType} type - Type name: a `BlockType` value such as `"product"` or `"service"`. Example: "product", "category", "etc".
+ * @property {BlockType} type - Type name: a `BlockType` value such as `"product"`, `"catalog_page"`, `"product_block"` or `"service"`. Example: "product".
  * @description Represents a general type entity with an identifier and a type.
  */
 interface IGeneralTypesEntity {

package/esm/index.d.ts

@@ -34,6 +34,7 @@ import WsApi from './web-socket/wsApi.js';
 export { getAdditionalFields, getAttributeFile, getAttributeFiles, isFileAttribute, isListAttribute, isNumberAttribute, isStringAttribute, } from './base/attributes.js';
 export { expandAttributeTimeIntervals, expandTimeIntervals, isTimeIntervalAttribute, } from './base/timeIntervals.js';
 export type * from './types.js';
+export type { IDefineApi };
 /**
  * IDefineApi interface
  * @interface IDefineApi
@@ -132,17 +133,17 @@ interface IDefineApi {
  * @function defineOneEntry
  * @param {string} url - URl of your project.
  * @param {IConfig} config - Custom configuration settings
- * @param {string} [config.token] - Optional token parameter
+ * @param {string} config.token - App token of the project. Required: `defineOneEntry` throws without it.
  * @param {string} [config.guestId] - Optional guest identifier sent as the `x-guest-id` header for guest cart/wishlist/activity flows (only while unauthenticated). In the browser, if omitted, a stable per-device id is generated and persisted in localStorage. On the server you MUST pass a per-visitor `guestId` (or call `setGuestId`): the SDK never auto-generates a server id, to avoid sharing one guest across visitors.
  * @param {string} [config.deviceMetadata] - Optional device-metadata string sent as the `x-device-metadata` header instead of the environment-derived fingerprint. Refresh tokens are bound to this header, so a server issuing tokens for a browser (OAuth code exchange) must pass the browser's string (from `getDeviceMetadata()`), or the token will not be refreshable from that browser.
- * @param {string} [config.langCode] - Optional langCode parameter
+ * @param {string} [config.langCode] - Optional default language. Default: 'en_US'.
  * @param {boolean} [config.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, and some results change shape (e.g. `searchPage` returns short `{ id, title }` cards). Default: false.
- * @param {string} [config.auth] - An object with authorization settings.
+ * @param {object} [config.auth] - An object with authorization settings.
  * @param {boolean} [config.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.
- * @param {string} [config.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.
+ * @param {string} [config.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. On the server, also pass the `deviceMetadata` saved with the token: the API binds refresh tokens to it.
  * @param {string} [config.auth.providerMarker] - The marker of the authorization provider.
- * @param {string} [config.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.
+ * @param {function(string): void} [config.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.
  * @returns {IDefineApi} List of methods set.
- * @description Define API.
+ * @description Define API. The returned client holds one session (tokens, guest id) shared by all its modules: on a server, create a client per request for user calls — a client shared between requests serves the signed-in user's data to every visitor. `logout` does not change the guest id.
  */
 export declare function defineOneEntry(url: string, config: IConfig): IDefineApi;

package/esm/index.js

@@ -33,23 +33,55 @@ import UsersApi from './users/usersApi.js';
 import WsApi from './web-socket/wsApi.js';
 export { getAdditionalFields, getAttributeFile, getAttributeFiles, isFileAttribute, isListAttribute, isNumberAttribute, isStringAttribute, } from './base/attributes.js';
 export { expandAttributeTimeIntervals, expandTimeIntervals, isTimeIntervalAttribute, } from './base/timeIntervals.js';
+/**
+ * Checks the project URL every request path is appended to.
+ * @param {string} raw - The URL as passed, trimmed.
+ * @param {string} base - The URL with trailing `/` and `/api/content` removed.
+ * @returns {boolean} True for an http(s) origin (optionally with a path) or a same-origin proxy path.
+ * @description A backslash is read as `/` by browsers: `/\\evil.example` was a "path" that sent
+ * every request — and the app token — to another host. A query or fragment swallowed every
+ * path appended to it, and credentials in the URL make `fetch` throw on each call.
+ */
+function _isProjectUrl(raw, base) {
+    if (/[\\?#\s]/.test(base)) {
+        return false;
+    }
+    if (raw.startsWith('/')) {
+        // `/` and `/api/content` leave an empty base: the site's own origin
+        return !raw.startsWith('//') && (base === '' || base.startsWith('/'));
+    }
+    // `https:evil.example` parses with that host, but a browser resolves it as a path
+    if (!/^https?:\/\//i.test(base)) {
+        return false;
+    }
+    try {
+        const parsed = new URL(base);
+        return ((parsed.protocol === 'http:' || parsed.protocol === 'https:') &&
+            !!parsed.hostname &&
+            !parsed.username &&
+            !parsed.password);
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Define API.
  * @function defineOneEntry
  * @param {string} url - URl of your project.
  * @param {IConfig} config - Custom configuration settings
- * @param {string} [config.token] - Optional token parameter
+ * @param {string} config.token - App token of the project. Required: `defineOneEntry` throws without it.
  * @param {string} [config.guestId] - Optional guest identifier sent as the `x-guest-id` header for guest cart/wishlist/activity flows (only while unauthenticated). In the browser, if omitted, a stable per-device id is generated and persisted in localStorage. On the server you MUST pass a per-visitor `guestId` (or call `setGuestId`): the SDK never auto-generates a server id, to avoid sharing one guest across visitors.
  * @param {string} [config.deviceMetadata] - Optional device-metadata string sent as the `x-device-metadata` header instead of the environment-derived fingerprint. Refresh tokens are bound to this header, so a server issuing tokens for a browser (OAuth code exchange) must pass the browser's string (from `getDeviceMetadata()`), or the token will not be refreshable from that browser.
- * @param {string} [config.langCode] - Optional langCode parameter
+ * @param {string} [config.langCode] - Optional default language. Default: 'en_US'.
  * @param {boolean} [config.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, and some results change shape (e.g. `searchPage` returns short `{ id, title }` cards). Default: false.
- * @param {string} [config.auth] - An object with authorization settings.
+ * @param {object} [config.auth] - An object with authorization settings.
  * @param {boolean} [config.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.
- * @param {string} [config.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.
+ * @param {string} [config.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. On the server, also pass the `deviceMetadata` saved with the token: the API binds refresh tokens to it.
  * @param {string} [config.auth.providerMarker] - The marker of the authorization provider.
- * @param {string} [config.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.
+ * @param {function(string): void} [config.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.
  * @returns {IDefineApi} List of methods set.
- * @description Define API.
+ * @description Define API. The returned client holds one session (tokens, guest id) shared by all its modules: on a server, create a client per request for user calls — a client shared between requests serves the signed-in user's data to every visitor. `logout` does not change the guest id.
  */
 export function defineOneEntry(url, config) {
     if (typeof url !== 'string' || url.trim() === '') {
@@ -64,7 +96,18 @@ export function defineOneEntry(url, config) {
             'Pass it via config, e.g. ' +
             'defineOneEntry("https://your-project.oneentry.cloud", { token: "your-app-token" }).');
     }
-    const stateModule = new StateModule(url.endsWith('/') ? url.slice(0, -1) : url, config);
+    // Trailing slashes and a copied `/api/content` suffix used to double up in every path
+    // (`//api/content/…`, `/api/content/api/content/…`) and fail each call with a 404
+    const baseUrl = url
+        .trim()
+        .replace(/\/+$/, '')
+        .replace(/\/api\/content$/i, '');
+    if (!_isProjectUrl(url.trim(), baseUrl)) {
+        throw new Error('OneEntry SDK: project URL must be an http(s) URL without credentials, query or fragment, ' +
+            'or a same-origin proxy path starting with "/", e.g. ' +
+            'defineOneEntry("https://your-project.oneentry.cloud", { token: "your-app-token" }).');
+    }
+    const stateModule = new StateModule(baseUrl, config);
     const Admins = new AdminsApi(stateModule);
     const AttributesSets = new AttributesSetsApi(stateModule);
     const AuthProvider = new AuthProviderApi(stateModule);

package/esm/integration-collections/integrationCollectionsApi.d.ts

@@ -86,11 +86,13 @@ export default class IntegrationCollectionsApi extends AsyncModules implements I
      * @handleName getICollectionRowsByMarker
      * @param {string} marker - Marker of the collection. Example: "collection1".
      * @param {string} [langCode] - Language code. Default: "en_US".
+     * @param {ICollectionQuery} [userQuery] - Pagination and entity filter, as in `getICollectionRowsById`. Without it the API returns the first 30 records only. Example: `{ limit: 100, offset: 0 }`.
      * @returns {Promise<ICollectionRowsResponce | IError>} Returns CollectionRowEntity object.
      * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description Records of the collection, one page at a time: `limit` defaults to 30 and `total` holds the full count.
      * @see {@link https://js-sdk.oneentry.cloud/docs/integration-collections/getICollectionRowsByMarker getICollectionRowsByMarker} documentation.
      */
-    getICollectionRowsByMarker(marker: string, langCode?: string): Promise<ICollectionRowsResponce | IError>;
+    getICollectionRowsByMarker(marker: string, langCode?: string, userQuery?: ICollectionQuery): Promise<ICollectionRowsResponce | IError>;
     /**
      * Getting one record from the collection.
      * @handleName getICollectionRowByMarkerAndId
@@ -121,7 +123,7 @@ export default class IntegrationCollectionsApi extends AsyncModules implements I
      * @param {string} [langCode] - Language code. Default: "en_US".
      * @returns {Promise<ICollectionRow | IError>} Returns object of type ICollectionRow.
      * @throws {IError} When isShell=false and an error occurs during the fetch
-     * @description Create a record in the collection.
+     * @description Create a record in the collection. The row is stored under the language key of `formData` when it is wrapped (`{ "en_US": [...] }`), not under `langCode` of the call; the returned `formData` is an array either way.
      * @see {@link https://js-sdk.oneentry.cloud/docs/integration-collections/createICollectionRow createICollectionRow} documentation.
      */
     createICollectionRow(marker: string, body: ICollectionFormObject, langCode?: string): Promise<ICollectionRow | IError>;
@@ -147,7 +149,7 @@ export default class IntegrationCollectionsApi extends AsyncModules implements I
      * @param {string} [langCode] - Language code. Default: "en_US".
      * @returns {Promise<ICollectionRow | IError>} Returns object of type ICollectionRow.
      * @throws {IError} When isShell=false and an error occurs during the fetch
-     * @description Edit a record in the collection.
+     * @description Edit a record in the collection. `formData` **replaces** every field of the row: fields left out of the body are removed, not kept.
      * @see {@link https://js-sdk.oneentry.cloud/docs/integration-collections/updateICollectionRow updateICollectionRow} documentation.
      */
     updateICollectionRow(marker: string, id: number, body: {
@@ -159,10 +161,19 @@ export default class IntegrationCollectionsApi extends AsyncModules implements I
      * @handleName deleteICollectionRowByMarkerAndId
      * @param {string} marker - Marker of the collection. Example: "collection1".
      * @param {number} id - ID of the collection row. Example: 12.
-     * @returns {Promise<boolean | IError>} Returns true (in case of successful deletion) or false (in case of unsuccessful deletion) (permission "collections.row.delete" required for access)
+     * @returns {Promise<boolean | IError>} Returns `true` once the row is deleted; a row that is not there (or already deleted) answers IError `404 Row not found`, not `false`. Permission "collections.row.delete" is required.
      * @throws {IError} When isShell=false and an error occurs during the fetch
      * @description Deletion of collection record object
      * @see {@link https://js-sdk.oneentry.cloud/docs/integration-collections/deleteICollectionRowByMarkerAndId deleteICollectionRowByMarkerAndId} documentation.
      */
     deleteICollectionRowByMarkerAndId(marker: string, id: number): Promise<boolean | IError>;
+    /**
+     * Unwraps `formData` of a created or updated row that is still keyed by a language.
+     * @param {any} row - The normalized row.
+     * @returns {any} The row with `formData` as an array.
+     * @description The row is stored under the language key of the body, and the answer
+     * keeps that key: `createICollectionRow(…, 'ru_RU')` with `{ en_US: [...] }` returned
+     * `formData` as an object, while `ICollectionRow.formData` is an array.
+     */
+    private _rowFormDataAsArray;
 }

package/esm/integration-collections/integrationCollectionsApi.js

@@ -56,7 +56,8 @@ export default class IntegrationCollectionsApi extends AsyncModules {
      * @see {@link https://js-sdk.oneentry.cloud/docs/integration-collections/getICollectionById getICollectionById} documentation.
      */
     async getICollectionById(id, langCode = this.state.lang) {
-        const result = await this._fetchGet(`/${id}?` + this._queryParamsToString({ langCode }));
+        const result = await this._fetchGet(`/${this._pathSegment(String(id))}?` +
+            this._queryParamsToString({ langCode }));
         // Validate response if validation is enabled
         const validated = await this._validateResponse(result, schema('CollectionEntitySchema'));
         return this._normalizeData(validated, langCode);
@@ -84,7 +85,7 @@ export default class IntegrationCollectionsApi extends AsyncModules {
      * @see {@link https://js-sdk.oneentry.cloud/docs/integration-collections/getICollectionRowsById getICollectionRowsById} documentation.
      */
     async getICollectionRowsById(id, langCode = this.state.lang, userQuery) {
-        const result = await this._fetchGet(`/${id}/rows?` +
+        const result = await this._fetchGet(`/${this._pathSegment(String(id))}/rows?` +
             this._queryParamsToString({
                 ...this._defaultQuery,
                 ...userQuery,
@@ -108,7 +109,7 @@ export default class IntegrationCollectionsApi extends AsyncModules {
      * @see {@link https://js-sdk.oneentry.cloud/docs/integration-collections/validateICollectionMarker validateICollectionMarker} documentation.
      */
     async validateICollectionMarker(marker) {
-        const result = await this._fetchGet(`/marker-validation/${marker}`);
+        const result = await this._fetchGet(`/marker-validation/${this._pathSegment(marker)}`);
         // Validate response if validation is enabled
         const validated = await this._validateResponse(result, schema('CollectionIsValidSchema'));
         return this._normalizeData(validated);
@@ -118,12 +119,19 @@ export default class IntegrationCollectionsApi extends AsyncModules {
      * @handleName getICollectionRowsByMarker
      * @param {string} marker - Marker of the collection. Example: "collection1".
      * @param {string} [langCode] - Language code. Default: "en_US".
+     * @param {ICollectionQuery} [userQuery] - Pagination and entity filter, as in `getICollectionRowsById`. Without it the API returns the first 30 records only. Example: `{ limit: 100, offset: 0 }`.
      * @returns {Promise<ICollectionRowsResponce | IError>} Returns CollectionRowEntity object.
      * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description Records of the collection, one page at a time: `limit` defaults to 30 and `total` holds the full count.
      * @see {@link https://js-sdk.oneentry.cloud/docs/integration-collections/getICollectionRowsByMarker getICollectionRowsByMarker} documentation.
      */
-    async getICollectionRowsByMarker(marker, langCode = this.state.lang) {
-        const result = await this._fetchGet(`/marker/${marker}/rows?langCode=${langCode}`);
+    async getICollectionRowsByMarker(marker, langCode = this.state.lang, userQuery) {
+        const result = await this._fetchGet(`/marker/${this._pathSegment(marker)}/rows?` +
+            this._queryParamsToString({
+                ...this._defaultQuery,
+                ...userQuery,
+                langCode,
+            }));
         // Validate response if validation is enabled
         const validated = await this._validateResponse(result, schema('CollectionRowsResponseSchema'));
         return this._normalizeData(validated, langCode);
@@ -139,7 +147,7 @@ export default class IntegrationCollectionsApi extends AsyncModules {
      * @see {@link https://js-sdk.oneentry.cloud/docs/integration-collections/getICollectionRowByMarkerAndId getICollectionRowByMarkerAndId} documentation.
      */
     async getICollectionRowByMarkerAndId(marker, id, langCode = this.state.lang) {
-        const result = await this._fetchGet(`/marker/${marker}/rows/${id}?langCode=${langCode}`);
+        const result = await this._fetchGet(`/marker/${this._pathSegment(marker)}/rows/${this._pathSegment(String(id))}?langCode=${encodeURIComponent(langCode)}`);
         // Validate response if validation is enabled
         const validated = await this._validateResponse(result, schema('CollectionRowSchema'));
         return this._normalizeData(validated, langCode);
@@ -163,14 +171,14 @@ export default class IntegrationCollectionsApi extends AsyncModules {
      * @param {string} [langCode] - Language code. Default: "en_US".
      * @returns {Promise<ICollectionRow | IError>} Returns object of type ICollectionRow.
      * @throws {IError} When isShell=false and an error occurs during the fetch
-     * @description Create a record in the collection.
+     * @description Create a record in the collection. The row is stored under the language key of `formData` when it is wrapped (`{ "en_US": [...] }`), not under `langCode` of the call; the returned `formData` is an array either way.
      * @see {@link https://js-sdk.oneentry.cloud/docs/integration-collections/createICollectionRow createICollectionRow} documentation.
      */
     async createICollectionRow(marker, body, langCode = this.state.lang) {
-        const response = await this._fetchPost(`/marker/${marker}/rows?langCode=${langCode}`, body);
+        const response = await this._fetchPost(`/marker/${this._pathSegment(marker)}/rows?langCode=${encodeURIComponent(langCode)}`, body);
         // Validate response if validation is enabled
         const validated = await this._validateResponse(response, schema('CollectionRowSchema'));
-        return this._normalizeData(validated, langCode);
+        return this._rowFormDataAsArray(this._normalizeData(validated, langCode));
     }
     /**
      * Edit a record in the collection.
@@ -194,27 +202,47 @@ export default class IntegrationCollectionsApi extends AsyncModules {
      * @param {string} [langCode] - Language code. Default: "en_US".
      * @returns {Promise<ICollectionRow | IError>} Returns object of type ICollectionRow.
      * @throws {IError} When isShell=false and an error occurs during the fetch
-     * @description Edit a record in the collection.
+     * @description Edit a record in the collection. `formData` **replaces** every field of the row: fields left out of the body are removed, not kept.
      * @see {@link https://js-sdk.oneentry.cloud/docs/integration-collections/updateICollectionRow updateICollectionRow} documentation.
      */
     async updateICollectionRow(marker, id, body, langCode = this.state.lang) {
-        const response = await this._fetchPut(`/marker/${marker}/rows/${id}?` + `langCode=${langCode}`, body);
+        const response = await this._fetchPut(`/marker/${this._pathSegment(marker)}/rows/${this._pathSegment(String(id))}?` +
+            `langCode=${encodeURIComponent(langCode)}`, body);
         // Validate response if validation is enabled
         const validated = await this._validateResponse(response, schema('CollectionRowSchema'));
-        return this._normalizeData(validated, langCode);
+        return this._rowFormDataAsArray(this._normalizeData(validated, langCode));
     }
     /**
      * Deletion of collection record object
      * @handleName deleteICollectionRowByMarkerAndId
      * @param {string} marker - Marker of the collection. Example: "collection1".
      * @param {number} id - ID of the collection row. Example: 12.
-     * @returns {Promise<boolean | IError>} Returns true (in case of successful deletion) or false (in case of unsuccessful deletion) (permission "collections.row.delete" required for access)
+     * @returns {Promise<boolean | IError>} Returns `true` once the row is deleted; a row that is not there (or already deleted) answers IError `404 Row not found`, not `false`. Permission "collections.row.delete" is required.
      * @throws {IError} When isShell=false and an error occurs during the fetch
      * @description Deletion of collection record object
      * @see {@link https://js-sdk.oneentry.cloud/docs/integration-collections/deleteICollectionRowByMarkerAndId deleteICollectionRowByMarkerAndId} documentation.
      */
     async deleteICollectionRowByMarkerAndId(marker, id) {
-        const result = await this._fetchDelete(`/marker/${marker}/rows/${id}`);
+        const result = await this._fetchDelete(`/marker/${this._pathSegment(marker)}/rows/${this._pathSegment(String(id))}`);
         return result;
     }
+    /**
+     * Unwraps `formData` of a created or updated row that is still keyed by a language.
+     * @param {any} row - The normalized row.
+     * @returns {any} The row with `formData` as an array.
+     * @description The row is stored under the language key of the body, and the answer
+     * keeps that key: `createICollectionRow(…, 'ru_RU')` with `{ en_US: [...] }` returned
+     * `formData` as an object, while `ICollectionRow.formData` is an array.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    _rowFormDataAsArray(row) {
+        const formData = row === null || row === void 0 ? void 0 : row.formData;
+        if (formData && typeof formData === 'object' && !Array.isArray(formData)) {
+            const keys = Object.keys(formData);
+            if (keys.length === 1 && Array.isArray(formData[keys[0]])) {
+                return { ...row, formData: formData[keys[0]] };
+            }
+        }
+        return row;
+    }
 }