oneentry 1.0.165 → 1.0.167

package/README.md

@@ -65,6 +65,7 @@ const {
     Templates,
     TemplatePreviews,
     UserActivity,
+    UserGroups,
     Users,
     WS,
 } = defineOneEntry('your-url', config)
@@ -95,6 +96,8 @@ The second parameter of the constructor takes the 'config'. It contains the foll
 
 - 'traficLimit' - Some methods use more than one request to the CMS so that the data you receive is complete and easy to work with. Pass the value "true" for this parameter to save traffic and decide for yourself what data you need. The default value "false".
 
+- 'rawData' - Pass "true" to keep an attribute's nested "additionalFields" exactly as the API sends them — an array of field objects, each carrying its own "marker" — instead of the marker-keyed map the SDK builds by default. This is the only transformation the flag turns off: locale unwrapping, sorting by "position", single-file unwrapping and number casting still apply. The "getAdditionalFields" helper returns the same marker map in both modes, so reading fields through it is unaffected. The default value "false".
+
 - 'auth' - An object with authorization settings. By default, the SDK is configured to work with tokens inside the user's session and does not require any additional work from you. At the same time, the SDK does not store the session state between sessions. If you are satisfied with such settings, do not pass the variable 'auth' at all.
 
 The 'auth' contains the following settings:
@@ -169,7 +172,7 @@ const api = defineOneEntry('your-url', {
     langCode: 'my-langCode',
     auth: {
         customAuth: false,
-        userToken: 'rerfesh.token',
+        refreshToken: 'user.refresh.token',
         providerMarker: 'email',
         saveFunction: saveTokenFromLocalStorage,
     },
@@ -302,6 +305,7 @@ Now you can use the following links to jump to specific entries documentation:
 - [Templates](https://js-sdk.oneentry.cloud/docs/category/templates)
 - [TemplatePreviews](https://js-sdk.oneentry.cloud/docs/category/templatepreviews)
 - [UserActivity](https://js-sdk.oneentry.cloud/docs/category/useractivity)
+- [UserGroups](https://js-sdk.oneentry.cloud/docs/category/usergroups)
 - [Users](https://js-sdk.oneentry.cloud/docs/category/users-1)
 - [WS](https://js-sdk.oneentry.cloud/docs/category/web-socket)
 - [Advanced examples](https://js-sdk.oneentry.cloud/docs/category/usage-examples)

package/changelog.md

@@ -1,5 +1,41 @@
 # SDK Change Log
 
+## v.1.0.167
+
+### What's New
+
+- **`UserGroups` — a whole section of the Content API that the SDK did not reach.** Five read methods over the user-group tree: `getUserGroups` (flat list), `getRootUserGroups` (top level, `parentId: null`), `getUserGroupById`, `getUserGroupByMarker` and `getChildUserGroupsByMarker`. Nesting is walked with the last one rather than through `parentId`, which is the same shape the menus API already taught: the parent link is there, but the children are what you read.
+
+  One field is worth knowing before you type it: **`childrenCount` arrives as a string** (`"0"`), not a number. The platform DTO declares it a number, the API sends a string, and the interface follows the API — so `Number(group.childrenCount)` is on you. `version` is not sent by every stand and is optional.
+
+- **`FileUploading.searchFileContent` — public search across the content of files attached to records.** Takes a query of at least 3 characters plus optional filters by extension, owner section and link locale, and `onlyTruncated` for files whose extracted text hit the size ceiling. Pagination is `offset` and `limit`, the latter capped at 50 — a larger value is rejected with `400 "limit must not be greater than 50"`.
+
+  Two things decide how you render the result. The unit is a **file, not a fragment**: one `snippet` per file, even when the document matches on twenty pages, and `snippet.pageFrom` says where it starts. And the match inside the snippet is wrapped in the control characters `U+0002` / `U+0003`, not in HTML — paste it into markup unchanged and the reader sees nothing, so replace them with your own highlighting. The result is narrowed by access: only files of visible records in sections enabled in project settings, personal sections only down to the caller's own records, and the admins section never. A separate `403` means the feature is not in the project tariff.
+
+- **`Orders.getOrderById` — an order by its own id, without the storage marker.** `getOrderByMarkerAndId` needs both, and the marker is exactly what is missing when the id arrives from outside: a payment provider's return URL, a link in a notification, an order number a customer read out. The route is the same one the storage method ends at, so the returned entity is `IOrderByMarkerEntity` as before — no new type.
+
+- **`Payments.getPaymentStagesByOrderId` — the payment progress of an order.** An order can be paid in parts rather than in one payment; `partial` says which case it is, `completed` says whether anything is left, and each stage in `stages` carries its own `marker`, `sessionId`, `productId`, `title`, `value` and a `status` of `planned` or `completed`.
+
+### What's Fixed
+
+- **`IConfig.rawData` was documented as something it is not.** Both the README and the JSDoc said it returns "raw API responses without any transformation", which reads as an off switch for normalization. It is not: the flag is read in exactly one place and decides only whether an attribute's nested `additionalFields` stays the array the API sends or becomes the marker-keyed map the SDK builds. Locale unwrapping, sorting by `position`, single-file unwrapping and number casting apply either way, and `getAdditionalFields` returns the same map in both modes. Anyone who set it expecting untouched payloads got normalized data and a puzzle. Documentation only.
+
+- **Two config examples named fields that do not exist.** The README's `auth` example passed `userToken` — the field is `refreshToken`, and the value was misspelled `'rerfesh.token'` on top of it. The `IConfig` JSDoc example passed `multipleRequests`, which is `traficLimit`. Both were copy-paste targets, so the error propagated: `userToken` reached nine locales of the documentation site. Documentation only.
+
+- **`docs/VALIDATION.md` described a validation layer the SDK no longer has.** It listed 5 validated modules and 6 schema files; there are 22 of each, covering 71 methods, and the auth-provider list named six methods that are not validated at all. Worse, its "Contributing" section told you to import the schema statically and call `this._validateResponse(result, Schema)` — a static `*Schemas` import anywhere in the graph puts Zod back into every consumer's bundle, which is the one thing `createSchemaLoader` exists to prevent, and the method has been async and loader-taking for several releases. The page now matches the code, and the performance section says schemas are loaded on demand rather than tree-shaken.
+
+### What's Deleted
+
+- **The dead `strict` option of `validateResponse`.** The options object declared `strict?: boolean` and the JSDoc described it as "Whether to use strict mode", but the implementation never read it — strictness is decided by which of the two helpers runs, and `_validateResponse` picks between them by `config.validation.strictMode`. No caller passed it and the function is not exported from the package root, so the field is gone rather than wired up.
+
+## v.1.0.166
+
+### What's Fixed
+
+- **FormData > `IFormsDataFilter.entityIdentifier` accepts a number.** The field was typed `string`, but an entity is not always addressed by a text marker: product-scoped records — reviews and ratings — are filtered by the **numeric product id**, and that is what the endpoint expects. So the one filter every storefront writes, `{ entityIdentifier: product.id, status: ['approved'] }`, did not compile: `TS2322: Type 'number' is not assignable to type 'string'`. The call worked perfectly at runtime, which made the error read as a mistake in the caller rather than in the type — the usual fix was a cast, and a cast on a field whose real contract nobody had written down. The declaration is now `string | number`, documented with the full contract: a text marker for content entities (`"blog"`), the numeric id for products (`2954`), the login for users and admins.
+
+  Only the **request** is widened. The API normalizes the value and sends it back as a string — the SDK's own fixture stores a product id as `entityIdentifier: "2954"` — so `IFormByMarkerDataEntity`, `IFormDataSearchEntity`, `IPostFormResponseData` and `IUpdateFormsData` keep `entityIdentifier: string`, and reading code needs no narrowing. Types only; no runtime change, and `_stripEmptyDates` never touched this field.
+
 ## v.1.0.165
 
 ### What's New

package/dist/base/utils.d.ts

@@ -5,7 +5,10 @@
  * @property {string} [deviceMetadata] - Device-metadata string sent as the `x-device-metadata` header on POST requests and token refresh, overriding the environment-derived fingerprint. The API binds refresh tokens to this header, so server-side flows that issue tokens on behalf of a browser (e.g. an OAuth code exchange) must pass the browser's string here — otherwise the token is bound to the server's fingerprint and cannot be refreshed from the browser. Obtain the string in the browser via `getDeviceMetadata()`. Can also be set later via `setDeviceMetadata`.
  * @property {string} [langCode] - specify the default language to avoid specifying it in every request.
  * @property {boolean} [traficLimit] - Some methods use multiple queries to make it easier to work with the API. Set this parameter to "false" to save traffic and decide for yourself what data you need.
- * @property {boolean} [rawData] - Set to true to receive raw API responses without any transformation.
+ * @property {boolean} [rawData] - Set to true to keep an attribute's nested `additionalFields` as the
+ * array the API sends, instead of the marker-keyed map the SDK builds by default. It turns off only that
+ * transformation — locale unwrapping, sorting by `position`, single-file unwrapping and number casting
+ * still apply. `getAdditionalFields` returns the same marker map in either mode.
  * @property {object} [validation] - Validation settings for API responses.
  * @property {boolean} [auth] - An object with authorization settings.
  * @property {boolean} [auth.customAuth] - Set this flag to true if you want to configure the authorization process yourself. Set the flag to false, or do not pass it at all to have automatic authorization and token renewal.
@@ -22,7 +25,7 @@
  * const config = {
  *     token: 'project.token.here',
  *     langCode: 'en_US',
- *     multipleRequests: true,
+ *     traficLimit: true,
  *     auth: {
  *         customAuth: false,
  *         refreshToken: 'user.refresh.token',

package/dist/base/validation.d.ts

@@ -99,16 +99,18 @@ export declare const AuthEntitySchema: z.ZodObject<{
  */
 export declare function createPaginatedSchema<T extends z.ZodTypeAny>(itemSchema: T): any;
 /**
- * Validation helper function
+ * Validation helper function.
+ *
+ * This is the strict half of the pair: it reports a failure instead of hiding it.
+ * Strictness is the choice of function, not an option — `validateResponseSafe` is the
+ * lenient one, and `_validateResponse` picks between them by `config.validation.strictMode`.
  * @param {z.ZodSchema<T>} schema - Zod schema to validate against
  * @param {unknown} data - Data to validate
- * @param {object} options - Validation options
- * @param {boolean} options.strict - Whether to use strict mode
- * @param {boolean} options.logErrors - Whether to log errors
+ * @param {object} [options] - Validation options
+ * @param {boolean} [options.logErrors] - Whether to log errors
  * @returns {object} Validated data or error
  */
 export declare function validateResponse<T>(schema: z.ZodSchema<T>, data: unknown, options?: {
-    strict?: boolean;
     logErrors?: boolean;
 }): {
     success: true;

package/dist/base/validation.js

@@ -175,12 +175,15 @@ function createPaginatedSchema(itemSchema) {
     });
 }
 /**
- * Validation helper function
+ * Validation helper function.
+ *
+ * This is the strict half of the pair: it reports a failure instead of hiding it.
+ * Strictness is the choice of function, not an option — `validateResponseSafe` is the
+ * lenient one, and `_validateResponse` picks between them by `config.validation.strictMode`.
  * @param {z.ZodSchema<T>} schema - Zod schema to validate against
  * @param {unknown} data - Data to validate
- * @param {object} options - Validation options
- * @param {boolean} options.strict - Whether to use strict mode
- * @param {boolean} options.logErrors - Whether to log errors
+ * @param {object} [options] - Validation options
+ * @param {boolean} [options.logErrors] - Whether to log errors
  * @returns {object} Validated data or error
  */
 function validateResponse(schema, data, options) {

package/dist/file-uploading/fileUploadingApi.d.ts

@@ -1,7 +1,7 @@
 import AsyncModules from '../base/asyncModules';
 import type StateModule from '../base/stateModule';
 import type { IError } from '../base/utils';
-import type { IFileUploading, IUploadingQuery, IUploadingReturn } from './fileUploadingInterfaces';
+import type { IFileSearchResponse, IFileUploading, IUploadingQuery, IUploadingReturn } from './fileUploadingInterfaces';
 /**
  * Controllers for working with file uploading
  * @handle /api/content/files
@@ -67,6 +67,32 @@ export default class FileUploadingApi extends AsyncModules implements IFileUploa
      * @see {@link https://js-sdk.oneentry.cloud/docs/file-uploading/delete delete} documentation.
      */
     delete(filename: string, fileQuery?: IUploadingQuery): Promise<boolean | IError>;
+    /**
+     * Public search across the content of files attached to records.
+     * @handleName searchFileContent
+     * @param {string} query - Search query, at least 3 characters — shorter is rejected with 400. Example: "transportation".
+     * @param {string} [langCode] - Language of the query. Example: "en_US".
+     * @param {string[]} [extensions] - Filter by file extension, sent comma-separated. Example: ["pdf", "docx"].
+     * @param {string[]} [ownerTables] - Filter by the section the attached record belongs to, sent comma-separated. Example: ["products", "pages"].
+     * @param {string[]} [localeCodes] - Filter by the locale of the link, not of the file content. Example: ["en_US"].
+     * @param {boolean} [onlyTruncated] - Return only files whose extracted text was cut at the size ceiling.
+     * @param {number} [offset] - Parameter for pagination. Default: 0.
+     * @param {number} [limit] - Parameter for pagination. Default: 10, maximum 50 — a larger value is rejected with 400 "limit must not be greater than 50".
+     * @returns {Promise<IFileSearchResponse | IError>} Returns the found files with their matching fragments.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description The unit of the result is a **file, not a fragment**: one `snippet` per file,
+     * even when the document matches on many pages. Matches inside the snippet are wrapped in the
+     * control characters `U+0002` and `U+0003` rather than HTML, so replace them before rendering.
+     * The result is narrowed by access: only files of visible records of the sections enabled in the
+     * project settings, personal sections only down to the caller's own records, and the admins
+     * section is never returned. A separate 403 means the feature is not part of the project tariff.
+     * @example
+     * ```ts
+     * const found = await api.FileUploading.searchFileContent('transportation', 'en_US', ['pdf']);
+     * ```
+     * @see {@link https://js-sdk.oneentry.cloud/docs/file-uploading/searchFileContent searchFileContent} documentation.
+     */
+    searchFileContent(query: string, langCode?: string, extensions?: string[], ownerTables?: string[], localeCodes?: string[], onlyTruncated?: boolean, offset?: number, limit?: number): Promise<IFileSearchResponse | IError>;
     /**
      * Create a File object from a URL.
      * @param {string} url - The URL to fetch the file from.

package/dist/file-uploading/fileUploadingApi.js

@@ -125,6 +125,48 @@ class FileUploadingApi extends asyncModules_1.default {
         const result = await this._fetchDelete(`?filename=${filename}&` + this._queryParamsToString(query));
         return result;
     }
+    /**
+     * Public search across the content of files attached to records.
+     * @handleName searchFileContent
+     * @param {string} query - Search query, at least 3 characters — shorter is rejected with 400. Example: "transportation".
+     * @param {string} [langCode] - Language of the query. Example: "en_US".
+     * @param {string[]} [extensions] - Filter by file extension, sent comma-separated. Example: ["pdf", "docx"].
+     * @param {string[]} [ownerTables] - Filter by the section the attached record belongs to, sent comma-separated. Example: ["products", "pages"].
+     * @param {string[]} [localeCodes] - Filter by the locale of the link, not of the file content. Example: ["en_US"].
+     * @param {boolean} [onlyTruncated] - Return only files whose extracted text was cut at the size ceiling.
+     * @param {number} [offset] - Parameter for pagination. Default: 0.
+     * @param {number} [limit] - Parameter for pagination. Default: 10, maximum 50 — a larger value is rejected with 400 "limit must not be greater than 50".
+     * @returns {Promise<IFileSearchResponse | IError>} Returns the found files with their matching fragments.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description The unit of the result is a **file, not a fragment**: one `snippet` per file,
+     * even when the document matches on many pages. Matches inside the snippet are wrapped in the
+     * control characters `U+0002` and `U+0003` rather than HTML, so replace them before rendering.
+     * The result is narrowed by access: only files of visible records of the sections enabled in the
+     * project settings, personal sections only down to the caller's own records, and the admins
+     * section is never returned. A separate 403 means the feature is not part of the project tariff.
+     * @example
+     * ```ts
+     * const found = await api.FileUploading.searchFileContent('transportation', 'en_US', ['pdf']);
+     * ```
+     * @see {@link https://js-sdk.oneentry.cloud/docs/file-uploading/searchFileContent searchFileContent} documentation.
+     */
+    async searchFileContent(query, langCode = this.state.lang, extensions, ownerTables, localeCodes, onlyTruncated, offset, limit) {
+        // Array filters are sent comma-separated — an array stringifies to exactly that.
+        const params = {
+            q: query,
+            langCode,
+            extensions,
+            ownerTables,
+            localeCodes,
+            onlyTruncated,
+            offset,
+            limit,
+        };
+        const result = await this._fetchGet(`/search?` + this._queryParamsToString(params));
+        // Validate response if validation is enabled
+        const validated = await this._validateResponse(result, schema('FileSearchResponseSchema'));
+        return this._normalizeData(validated);
+    }
     /**
      * Create a File object from a URL.
      * @param {string} url - The URL to fetch the file from.

package/dist/file-uploading/fileUploadingInterfaces.d.ts

@@ -71,6 +71,22 @@ interface IFileUploading {
      * @throws {IError} - If there is an error during the fetch operation, it will return an error object.
      */
     getFile(id: number, type: string, entity: string, filename: string, template?: string): Promise<Response | IError>;
+    /**
+     * Public search across the content of files attached to records.
+     * @handleName searchFileContent
+     * @param {string} query - Search query, at least 3 characters. Example: "transportation".
+     * @param {string} [langCode] - Language of the query. Example: "en_US".
+     * @param {string[]} [extensions] - Filter by file extension, sent comma-separated. Example: ["pdf", "docx"].
+     * @param {string[]} [ownerTables] - Filter by the section the attached record belongs to. Example: ["products", "pages"].
+     * @param {string[]} [localeCodes] - Filter by the locale of the link, not of the file content. Example: ["en_US"].
+     * @param {boolean} [onlyTruncated] - Return only files whose extracted text was cut at the size ceiling.
+     * @param {number} [offset] - Parameter for pagination. Default: 0.
+     * @param {number} [limit] - Parameter for pagination, 1 to 50. Default: 10.
+     * @returns {IFileSearchResponse} Returns the found files with their matching fragments.
+     * @throws {IError} - If there is an error during the fetch operation, it will return an error object.
+     * @description This method searches the content of files attached to records.
+     */
+    searchFileContent(query: string, langCode?: string, extensions?: string[], ownerTables?: string[], localeCodes?: string[], onlyTruncated?: boolean, offset?: number, limit?: number): Promise<IFileSearchResponse | IError>;
 }
 /**
  * Represents a file entity that may contain a file object or a path as a string.
@@ -113,4 +129,89 @@ interface IUploadingReturn {
     size: number;
     contentType: string;
 }
-export type { IFileEntity, IFileUploading, IUploadingQuery, IUploadingReturn };
+/**
+ * The `IFileSearchOwner` interface describes one record a found file is attached to.
+ * @interface IFileSearchOwner
+ * @property {string} tableName - Section the record belongs to. Example: "products".
+ * @property {number} dataId - Identifier of the record. Example: 644.
+ * @property {string} title - Title of the record. Example: "COG — March 17, 2016".
+ * @property {string} langCode - Locale of the link, not of the file content. Example: "en_US".
+ * @description One record a found file is attached to. The same file can be attached to several records, and a record contributes one entry per locale.
+ */
+interface IFileSearchOwner {
+    tableName: string;
+    dataId: number;
+    title: string;
+    langCode: string;
+}
+/**
+ * The `IFileSearchSnippet` interface describes the matching fragment of a file.
+ * @interface IFileSearchSnippet
+ * @property {string} text - The fragment itself. Every match inside it is wrapped in the control characters U+0002 and U+0003 — not HTML, so replace them before rendering. Example: "… Active \u0002Transportation\u0003 2…".
+ * @property {number | null} pageFrom - Page the fragment starts on, for paged formats. Example: 86.
+ * @description The matching fragment of a file. One fragment per file, even when the document matches on many pages.
+ */
+interface IFileSearchSnippet {
+    text: string;
+    pageFrom: number | null;
+}
+/**
+ * The `IFileSearchItem` interface describes one found file.
+ * @interface IFileSearchItem
+ * @property {number} id - Identifier of the indexed file. Example: 1077.
+ * @property {string} storageKey - Key of the object in the storage; the file link is built from it. Example: "files/project/file/644/product/db1918c4.pdf".
+ * @property {string} extension - File extension. Example: "pdf".
+ * @property {string | null} title - Title from the document metadata, `null` when the document carries none. Example: "Microsoft Word - COG Agenda.docx".
+ * @property {string | null} langCode - Language of the file content, detected on indexing. Example: "en".
+ * @property {number | null} pageCount - Number of pages, for paged formats. Example: 244.
+ * @property {number} rank - Relevance of the match; the API sorts by it descending. Example: 0.0971.
+ * @property {IFileSearchSnippet | null} snippet - The matching fragment.
+ * @property {IFileSearchOwner[]} owners - Records the file is attached to, limited to those the caller may see.
+ * @property {number} ownersTotal - How many records visible to the caller reference the file. Example: 2.
+ * @description One found file. The unit of the result is a file, not a fragment.
+ */
+interface IFileSearchItem {
+    id: number;
+    storageKey: string;
+    extension: string;
+    title: string | null;
+    langCode: string | null;
+    pageCount: number | null;
+    rank: number;
+    snippet: IFileSearchSnippet | null;
+    owners: IFileSearchOwner[];
+    ownersTotal: number;
+}
+/**
+ * The `IFileSearchQueryLanguage` interface describes how the query language was resolved.
+ * @interface IFileSearchQueryLanguage
+ * @property {string[]} resolved - Languages the query was actually run in. Example: ["english"].
+ * @property {string} source - How they were chosen: "explicit" when taken from `langCode`, otherwise detected. Example: "explicit".
+ * @property {string[]} candidates - Languages considered. Example: ["english"].
+ * @description How the query language was resolved for the search.
+ */
+interface IFileSearchQueryLanguage {
+    resolved: string[];
+    source: string;
+    candidates: string[];
+}
+/**
+ * The `IFileSearchResponse` interface describes the result of a file content search.
+ * @interface IFileSearchResponse
+ * @property {number} total - Total number of matching files. Example: 166.
+ * @property {number} offset - Offset the page starts at. Example: 0.
+ * @property {number} limit - Page size. Example: 10.
+ * @property {IFileSearchQueryLanguage} queryLanguage - How the query language was resolved.
+ * @property {string[]} warnings - Warnings about the search, empty when there are none.
+ * @property {IFileSearchItem[]} items - The found files.
+ * @description The result of a file content search.
+ */
+interface IFileSearchResponse {
+    total: number;
+    offset: number;
+    limit: number;
+    queryLanguage: IFileSearchQueryLanguage;
+    warnings: string[];
+    items: IFileSearchItem[];
+}
+export type { IFileEntity, IFileSearchItem, IFileSearchOwner, IFileSearchQueryLanguage, IFileSearchResponse, IFileSearchSnippet, IFileUploading, IUploadingQuery, IUploadingReturn, };

package/dist/file-uploading/fileUploadingSchemas.d.ts

@@ -22,3 +22,76 @@ export declare const UploadResponseSchema: z.ZodArray<z.ZodObject<{
     size: z.ZodNumber;
     contentType: z.ZodString;
 }, z.core.$strip>>;
+/**
+ * One record a found file is attached to
+ */
+export declare const FileSearchOwnerSchema: z.ZodObject<{
+    tableName: z.ZodString;
+    dataId: z.ZodNumber;
+    title: z.ZodString;
+    langCode: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Matching fragment of a found file
+ */
+export declare const FileSearchSnippetSchema: z.ZodObject<{
+    text: z.ZodString;
+    pageFrom: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * One found file
+ */
+export declare const FileSearchItemSchema: z.ZodObject<{
+    id: z.ZodNumber;
+    storageKey: z.ZodString;
+    extension: z.ZodString;
+    title: z.ZodNullable<z.ZodString>;
+    langCode: z.ZodNullable<z.ZodString>;
+    pageCount: z.ZodNullable<z.ZodNumber>;
+    rank: z.ZodNumber;
+    snippet: z.ZodNullable<z.ZodObject<{
+        text: z.ZodString;
+        pageFrom: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>>;
+    owners: z.ZodArray<z.ZodObject<{
+        tableName: z.ZodString;
+        dataId: z.ZodNumber;
+        title: z.ZodString;
+        langCode: z.ZodString;
+    }, z.core.$strip>>;
+    ownersTotal: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * File content search response
+ */
+export declare const FileSearchResponseSchema: z.ZodObject<{
+    total: z.ZodNumber;
+    offset: z.ZodNumber;
+    limit: z.ZodNumber;
+    queryLanguage: z.ZodObject<{
+        resolved: z.ZodArray<z.ZodString>;
+        source: z.ZodString;
+        candidates: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+    warnings: z.ZodArray<z.ZodString>;
+    items: z.ZodArray<z.ZodObject<{
+        id: z.ZodNumber;
+        storageKey: z.ZodString;
+        extension: z.ZodString;
+        title: z.ZodNullable<z.ZodString>;
+        langCode: z.ZodNullable<z.ZodString>;
+        pageCount: z.ZodNullable<z.ZodNumber>;
+        rank: z.ZodNumber;
+        snippet: z.ZodNullable<z.ZodObject<{
+            text: z.ZodString;
+            pageFrom: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strip>>;
+        owners: z.ZodArray<z.ZodObject<{
+            tableName: z.ZodString;
+            dataId: z.ZodNumber;
+            title: z.ZodString;
+            langCode: z.ZodString;
+        }, z.core.$strip>>;
+        ownersTotal: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;

package/dist/file-uploading/fileUploadingSchemas.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.UploadResponseSchema = exports.UploadingReturnSchema = void 0;
+exports.FileSearchResponseSchema = exports.FileSearchItemSchema = exports.FileSearchSnippetSchema = exports.FileSearchOwnerSchema = exports.UploadResponseSchema = exports.UploadingReturnSchema = void 0;
 /**
  * Validation schemas for FileUploading module
  * @description Zod schemas for validating file uploading-related API responses
@@ -20,3 +20,49 @@ exports.UploadingReturnSchema = zod_1.z.object({
  * Upload response schema (array of upload results)
  */
 exports.UploadResponseSchema = zod_1.z.array(exports.UploadingReturnSchema);
+/**
+ * One record a found file is attached to
+ */
+exports.FileSearchOwnerSchema = zod_1.z.object({
+    tableName: zod_1.z.string(),
+    dataId: zod_1.z.number(),
+    title: zod_1.z.string(),
+    langCode: zod_1.z.string(),
+});
+/**
+ * Matching fragment of a found file
+ */
+exports.FileSearchSnippetSchema = zod_1.z.object({
+    text: zod_1.z.string(),
+    pageFrom: zod_1.z.number().nullable(),
+});
+/**
+ * One found file
+ */
+exports.FileSearchItemSchema = zod_1.z.object({
+    id: zod_1.z.number(),
+    storageKey: zod_1.z.string(),
+    extension: zod_1.z.string(),
+    title: zod_1.z.string().nullable(),
+    langCode: zod_1.z.string().nullable(),
+    pageCount: zod_1.z.number().nullable(),
+    rank: zod_1.z.number(),
+    snippet: exports.FileSearchSnippetSchema.nullable(),
+    owners: zod_1.z.array(exports.FileSearchOwnerSchema),
+    ownersTotal: zod_1.z.number(),
+});
+/**
+ * File content search response
+ */
+exports.FileSearchResponseSchema = zod_1.z.object({
+    total: zod_1.z.number(),
+    offset: zod_1.z.number(),
+    limit: zod_1.z.number(),
+    queryLanguage: zod_1.z.object({
+        resolved: zod_1.z.array(zod_1.z.string()),
+        source: zod_1.z.string(),
+        candidates: zod_1.z.array(zod_1.z.string()),
+    }),
+    warnings: zod_1.z.array(zod_1.z.string()),
+    items: zod_1.z.array(exports.FileSearchItemSchema),
+});

package/dist/forms-data/formsDataApi.d.ts

@@ -90,7 +90,7 @@ export default class FormsDataApi extends AsyncModules implements IFormsData {
           "dateFrom": "2025-01-01",
           "dateTo": ""
         }
-     * @param {string} [body.entityIdentifier] - Text identifier (marker) of the entity the records belong to. Example: "blog".
+     * @param {string | number} [body.entityIdentifier] - Identifier of the entity the records belong to: a text marker for content entities ("blog"), the **numeric id for products** (2954), the login for users and admins. Example: "blog".
      * @param {number} [body.parentId] - Identifier of the parent record, to fetch replies to one submission. Example: 10.
      * @param {string} [body.userIdentifier] - Text identifier of the sender. Example: "admin".
      * @param {FormDataStatus[]} [body.status] - Moderation statuses to keep: "sent", "moderation", "approved", "banned", "deleted". Must be an array; anything outside the set is rejected with `400 each value in status must be a valid enum value`. Example: ["approved"].

package/dist/forms-data/formsDataApi.js

@@ -197,7 +197,7 @@ class FormsDataApi extends asyncModules_1.default {
           "dateFrom": "2025-01-01",
           "dateTo": ""
         }
-     * @param {string} [body.entityIdentifier] - Text identifier (marker) of the entity the records belong to. Example: "blog".
+     * @param {string | number} [body.entityIdentifier] - Identifier of the entity the records belong to: a text marker for content entities ("blog"), the **numeric id for products** (2954), the login for users and admins. Example: "blog".
      * @param {number} [body.parentId] - Identifier of the parent record, to fetch replies to one submission. Example: 10.
      * @param {string} [body.userIdentifier] - Text identifier of the sender. Example: "admin".
      * @param {FormDataStatus[]} [body.status] - Moderation statuses to keep: "sent", "moderation", "approved", "banned", "deleted". Must be an array; anything outside the set is rejected with `400 each value in status must be a valid enum value`. Example: ["approved"].

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

@@ -109,7 +109,7 @@ type FormDataStatus = 'sent' | 'moderation' | 'approved' | 'banned' | 'deleted';
 /**
  * Represents the filter body of `getFormsDataByMarker`.
  * @interface IFormsDataFilter
- * @property {string} [entityIdentifier] - Text identifier (marker) of the entity the records belong to; an empty string means "no filter". Example: "blog".
+ * @property {string | number} [entityIdentifier] - Identifier of the entity the records belong to; an empty string means "no filter". Text marker for content entities ("blog"), the **numeric id for products** (2954), the login for users and admins. Example: "blog".
  * @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"].
@@ -123,7 +123,14 @@ type FormDataStatus = 'sent' | 'moderation' | 'approved' | 'banned' | 'deleted';
  * leaking onto a public page, from one typo the compiler used to accept.
  */
 interface IFormsDataFilter {
-    entityIdentifier?: string;
+    /**
+     * `string | number` because the entity is not always addressed by a marker:
+     * product-scoped records (reviews, ratings) are filtered by the **numeric
+     * product id**, which is what the API expects and what every storefront
+     * passes. The response normalizes it back to a string, so the read-side
+     * interfaces keep `entityIdentifier: string` — only the request is widened.
+     */
+    entityIdentifier?: string | number;
     parentId?: number;
     userIdentifier?: string;
     status?: FormDataStatus[];

package/dist/index.d.ts

@@ -28,6 +28,7 @@ import SystemApi from './system/systemApi';
 import TemplatesApi from './templates/templatesApi';
 import TemplatePreviewsApi from './templates-preview/templatesPreviewApi';
 import UserActivityApi from './user-activity/userActivityApi';
+import UserGroupsApi from './user-groups/userGroupsApi';
 import UsersApi from './users/usersApi';
 import WsApi from './web-socket/wsApi';
 export { getAdditionalFields, getAttributeFile, getAttributeFiles, isFileAttribute, isListAttribute, isNumberAttribute, isStringAttribute, } from './base/attributes';
@@ -62,6 +63,7 @@ export type * from './types';
  * @property {TemplatesApi} Templates - Templates API module.
  * @property {TemplatePreviewsApi} TemplatePreviews - Template previews API module.
  * @property {UserActivityApi} UserActivity - User activity API module.
+ * @property {UserGroupsApi} UserGroups - User groups API module.
  * @property {UsersApi} Users - Users API module.
  * @property {WsApi} WS - WebSocket API module.
  */
@@ -118,6 +120,8 @@ interface IDefineApi {
     TemplatePreviews: TemplatePreviewsApi;
     /** User/guest activity tracking: trackUserActivity */
     UserActivity: UserActivityApi;
+    /** User groups tree: getUserGroups, getRootUserGroups, getUserGroupByMarker, getChildUserGroupsByMarker */
+    UserGroups: UserGroupsApi;
     /** Current authenticated user: getUser, updateUser */
     Users: UsersApi;
     /** WebSocket real-time updates */

package/dist/index.js

@@ -35,6 +35,7 @@ const systemApi_1 = __importDefault(require("./system/systemApi"));
 const templatesApi_1 = __importDefault(require("./templates/templatesApi"));
 const templatesPreviewApi_1 = __importDefault(require("./templates-preview/templatesPreviewApi"));
 const userActivityApi_1 = __importDefault(require("./user-activity/userActivityApi"));
+const userGroupsApi_1 = __importDefault(require("./user-groups/userGroupsApi"));
 const usersApi_1 = __importDefault(require("./users/usersApi"));
 const wsApi_1 = __importDefault(require("./web-socket/wsApi"));
 var attributes_1 = require("./base/attributes");
@@ -107,6 +108,7 @@ function defineOneEntry(url, config) {
     const Templates = new templatesApi_1.default(stateModule);
     const TemplatePreviews = new templatesPreviewApi_1.default(stateModule);
     const UserActivity = new userActivityApi_1.default(stateModule);
+    const UserGroups = new userGroupsApi_1.default(stateModule);
     const Users = new usersApi_1.default(stateModule);
     const WS = new wsApi_1.default(stateModule);
     return {
@@ -136,6 +138,7 @@ function defineOneEntry(url, config) {
         Templates,
         TemplatePreviews,
         UserActivity,
+        UserGroups,
         Users,
         WS,
     };

package/dist/orders/ordersApi.d.ts

@@ -70,6 +70,20 @@ export default class OrdersApi extends AsyncModules implements IOrdersApi {
      * @see {@link https://js-sdk.oneentry.cloud/docs/orders/getOrderByMarkerAndId getOrderByMarkerAndId} documentation.
      */
     getOrderByMarkerAndId(marker: string, id: number, langCode?: string): Promise<IOrderByMarkerEntity | IError>;
+    /**
+     * Getting a single order created by the user, by its own id.
+     * @handleName getOrderById
+     * @param {number} id - ID of the order object. Example: 12345.
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @returns {Promise<IOrderByMarkerEntity | IError>} Returns an object with the order.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description This method requires user authorization. Unlike `getOrderByMarkerAndId`,
+     * it does not need the storage marker — use it when only the order id is at hand, for
+     * example on the return URL of a payment provider or in a link from a notification.
+     * @see For more information about configuring the {@link https://js-sdk.oneentry.cloud/docs/category/authprovider authorization module}, see the documentation in the  {@link https://js-sdk.oneentry.cloud/docs/category/authprovider configuration settings section of the SDK}.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/orders/getOrderById getOrderById} documentation.
+     */
+    getOrderById(id: number, langCode?: string): Promise<IOrderByMarkerEntity | IError>;
     /**
      * Preview order calculation with discounts and coupons (without saving).
      * @handleName previewOrder

package/dist/orders/ordersApi.js

@@ -124,6 +124,25 @@ class OrdersApi extends asyncModules_1.default {
         const validated = await this._validateResponse(result, schema('OrderEntitySchema'));
         return this._normalizeData(validated);
     }
+    /**
+     * Getting a single order created by the user, by its own id.
+     * @handleName getOrderById
+     * @param {number} id - ID of the order object. Example: 12345.
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @returns {Promise<IOrderByMarkerEntity | IError>} Returns an object with the order.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description This method requires user authorization. Unlike `getOrderByMarkerAndId`,
+     * it does not need the storage marker — use it when only the order id is at hand, for
+     * example on the return URL of a payment provider or in a link from a notification.
+     * @see For more information about configuring the {@link https://js-sdk.oneentry.cloud/docs/category/authprovider authorization module}, see the documentation in the  {@link https://js-sdk.oneentry.cloud/docs/category/authprovider configuration settings section of the SDK}.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/orders/getOrderById getOrderById} documentation.
+     */
+    async getOrderById(id, langCode = this.state.lang) {
+        const result = await this._withOrdersUrl(() => this._fetchGet(`/${id}?langCode=${langCode}`));
+        // Validate response if validation is enabled
+        const validated = await this._validateResponse(result, schema('OrderEntitySchema'));
+        return this._normalizeData(validated);
+    }
     /**
      * Preview order calculation with discounts and coupons (without saving).
      * @handleName previewOrder