oneentry 1.0.166 → 1.0.168

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,51 @@
 # SDK Change Log
 
+## v.1.0.168
+
+### What's Fixed
+
+- **`Search.globalSearch` could not ask for a language, so a second-locale word found nothing.** The search index is per language, and the method sent no `langCode` — not even the one given to `defineOneEntry`. On a bilingual project the Spanish word "agua" came back with an empty group while the same request with `langCode=es_ES` returned a full page. The method now takes `langCode` as its last parameter, defaulting to the client's own language, so an existing call needs no edit and starts asking in the right language by itself. Measured on a bilingual stand: "agua" 0 → 30+, the English control unchanged (CMS-912).
+
+- **Methods that post a body no longer modify the object they are given.** `_normalizePostBody` wrapped `formData` and dropped an empty `phoneSMS` in place, and `signUp` and `updateUser` wrote `langCode` onto the caller's object. A body that is reused — a retry wrapper, two parallel calls, a shared default — came back already wrapped, was wrapped a second time, and the platform answered `400 "formData.en_US[0].marker" is required`: a validation error about a field the caller never sent. The normalizer now works on a copy, `notificationData` included, and the caller's object is identical after the call (CMS-909).
+
+- **A dropped connection returned `{}`, which reads exactly like an empty answer.** With `isShell` on — the default — a network failure was handed back as the thrown `TypeError`, whose `message` and `stack` are not enumerable, so it serialized to an empty object. There was no way to tell "no connection" from "no data": on one site such a value entered the page cache and was served for minutes after the link came back, and a static build baked a site of 404s while reporting success. A failure that never reached the platform now returns `{ statusCode: 0, message, pageData: null, timestamp }` — `statusCode: 0` is a value no HTTP answer uses. An error the platform itself sent is passed through untouched (CMS-780).
+
+- **`Discounts.getBonusHistory` was declared to return an array; it returns a container.** The endpoint answers `{ items, total }` — an account with no transactions gives `{"items":[],"total":0}` — while the method and the `IDiscounts` interface both promised `IBonusTransactionEntity[]`. Code written from the type read `.length` off an object and found `undefined`. The return type is now `IBonusHistoryResponse`, exported alongside the rest. Found while covering the module with tests (CMS-531); types only, the wire format did not change.
+
+- **The declared value shapes of a form submission were the ones the platform refuses.** A body written from the types got three `400`s in a row: a `list` field typed as `[{ title, value }]` (a page attribute's shape) answers `value[0] must be a string`, a `text` field typed as an object answers `value must be an array`, and `params` inside it answers `is not allowed`; a `spam` field had no type at all and a bare token is refused with the same sentence as a wrong one. `IBodyPostFormData.formData` now uses submission-specific types — `IBodyPostTypeList` (a list of strings), `IBodyPostTypeText` (a one-element array holding exactly one of `plainValue`, `htmlValue` or `mdValue`, no `params`) and `IBodyPostTypeSpam` (`{ event: { token, siteKey } }`) — with the read types left as they were. Types and documentation only; the wire format did not change (CMS-888).
+
+### Tests
+
+- **`discounts` and `oauth` now have tests that run.** The discounts suite covered four of six methods; `getBonusBalance` and `getBonusHistory` were untested, and it was the new coverage that found the wrong return type above. The suite went from 5 cases to 8, and the bonus ones authenticate first — the balance belongs to the signed-in user and answers `401` under the app token alone. The `oauth` case was an empty shell: its body was commented out and the expectation rule disabled, so it passed while testing nothing. The happy path still cannot be covered from the test stand — it needs a provider of type `oauth` and a one-time code from that provider's consent screen, and the stand has neither — so what is pinned instead is the SDK's own half of the contract: a refusal comes back as an error value rather than an exception, and the caller's body is not modified. The limitation is written into the test rather than left as a silent pass (CMS-531, CMS-532).
+
+## 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

package/dist/auth-provider/authProviderApi.js

@@ -124,8 +124,9 @@ class AuthProviderApi extends asyncModules_1.default {
      * @see {@link https://js-sdk.oneentry.cloud/docs/auth-provider/signUp signUp} documentation.
      */
     async signUp(marker, body, langCode = this.state.lang) {
-        body['langCode'] = langCode;
-        const result = await this._fetchPost(`/marker/${marker}/users/sign-up`, this._normalizePostBody(body, langCode));
+        // `langCode` goes onto our own copy — the caller's body stays as it was
+        // given, so a retry or a second parallel call sends the same thing (CMS-909).
+        const result = await this._fetchPost(`/marker/${marker}/users/sign-up`, this._normalizePostBody({ ...body, langCode }, langCode));
         // Validate response if validation is enabled
         const validated = await this._validateResponse(result, schema('SignUpResponseSchema'));
         return this._normalizeData(validated);

package/dist/base/asyncModules.d.ts

@@ -120,4 +120,22 @@ export default abstract class AsyncModules extends SyncModules {
      * @description Define an asynchronous method 'browserResponse' that takes a path and options as parameters
      */
     private browserResponse;
+    /**
+     * Turns whatever was thrown into the error shape the SDK already returns.
+     *
+     * With `isShell` on, a failure is returned rather than thrown — and a dropped
+     * connection throws a `TypeError`, whose `message` and `stack` are not
+     * enumerable. Returned as it was, it serializes to `{}` and reads exactly
+     * like an empty answer: on the sanbenitocog pilot such a value entered the
+     * page cache and was served for minutes after the link came back, and
+     * `next build` baked a site of 404s while reporting success (CMS-780).
+     *
+     * An object that already carries a `statusCode` is the platform's own error
+     * and is passed through untouched. Everything else becomes
+     * `{ statusCode: 0, message, pageData: null, timestamp }` — `statusCode: 0`
+     * says "the request never reached the platform", which no HTTP answer uses.
+     * @param {unknown} e - Whatever the try block threw.
+     * @returns {IError} The error in the shape the SDK returns for platform errors.
+     */
+    private _toShellError;
 }

package/dist/base/asyncModules.js

@@ -410,12 +410,45 @@ class AsyncModules extends syncModules_1.default {
             // Handle any errors that occur during the fetch process
             // Determine whether to return or throw the error based on 'isShell' state
             if (this.state.isShell) {
-                return e;
+                return this._toShellError(e);
             }
             else {
                 throw e;
             }
         }
     }
+    /**
+     * Turns whatever was thrown into the error shape the SDK already returns.
+     *
+     * With `isShell` on, a failure is returned rather than thrown — and a dropped
+     * connection throws a `TypeError`, whose `message` and `stack` are not
+     * enumerable. Returned as it was, it serializes to `{}` and reads exactly
+     * like an empty answer: on the sanbenitocog pilot such a value entered the
+     * page cache and was served for minutes after the link came back, and
+     * `next build` baked a site of 404s while reporting success (CMS-780).
+     *
+     * An object that already carries a `statusCode` is the platform's own error
+     * and is passed through untouched. Everything else becomes
+     * `{ statusCode: 0, message, pageData: null, timestamp }` — `statusCode: 0`
+     * says "the request never reached the platform", which no HTTP answer uses.
+     * @param {unknown} e - Whatever the try block threw.
+     * @returns {IError} The error in the shape the SDK returns for platform errors.
+     */
+    _toShellError(e) {
+        if (e && typeof e === 'object' && 'statusCode' in e) {
+            return e;
+        }
+        const message = e instanceof Error
+            ? `${e.name}: ${e.message}`
+            : typeof e === 'string'
+                ? e
+                : 'Request failed before a response was received';
+        return {
+            statusCode: 0,
+            message,
+            pageData: null,
+            timestamp: new Date().toISOString(),
+        };
+    }
 }
 exports.default = AsyncModules;

package/dist/base/syncModules.d.ts

@@ -81,10 +81,17 @@ export default abstract class SyncModules {
      * 2. **formData localization**: the API expects formData as
      * `{ "<langCode>": [...fields] }`, but callers pass a flat array or a single object.
      * The method wraps the data into the required structure.
-     * If `formData` is absent from the body — return the body as-is (only phoneSMS cleanup applied).
-     * @param {any} body - The body to normalize.
+     * If `formData` is absent from the body — return a copy with only the phoneSMS cleanup applied.
+     *
+     * **The caller's object is never touched.** Methods that post a body are
+     * routinely called with one that is reused — a retry wrapper, two parallel
+     * calls, a shared default. Normalizing in place sends the already-wrapped
+     * value the second time, it is wrapped again, and the platform answers
+     * `400 "formData.en_US[0].marker" is required` about a field the caller
+     * never sent (CMS-909).
+     * @param {any} body - The body to normalize. Left unchanged.
      * @param {string} [langCode] - The language code for normalization.
-     * @returns {any} Normalized body.
+     * @returns {any} A normalized copy of the body.
      */
     protected _normalizePostBody(body: any, langCode?: string): any;
     /**

package/dist/base/syncModules.js

@@ -220,27 +220,38 @@ class SyncModules {
      * 2. **formData localization**: the API expects formData as
      * `{ "<langCode>": [...fields] }`, but callers pass a flat array or a single object.
      * The method wraps the data into the required structure.
-     * If `formData` is absent from the body — return the body as-is (only phoneSMS cleanup applied).
-     * @param {any} body - The body to normalize.
+     * If `formData` is absent from the body — return a copy with only the phoneSMS cleanup applied.
+     *
+     * **The caller's object is never touched.** Methods that post a body are
+     * routinely called with one that is reused — a retry wrapper, two parallel
+     * calls, a shared default. Normalizing in place sends the already-wrapped
+     * value the second time, it is wrapped again, and the platform answers
+     * `400 "formData.en_US[0].marker" is required` about a field the caller
+     * never sent (CMS-909).
+     * @param {any} body - The body to normalize. Left unchanged.
      * @param {string} [langCode] - The language code for normalization.
-     * @returns {any} Normalized body.
+     * @returns {any} A normalized copy of the body.
      */
     _normalizePostBody(body, langCode = this.state.lang) {
-        // API does not accept phoneSMS = '' — delete the field if empty.
-        if (body.notificationData && body.notificationData.phoneSMS === '') {
-            delete body.notificationData.phoneSMS;
+        const next = { ...body };
+        // API does not accept phoneSMS = '' — drop the field if empty. `notificationData`
+        // is copied too: deleting the key on the original would reach the caller.
+        if (next.notificationData && next.notificationData.phoneSMS === '') {
+            next.notificationData = { ...next.notificationData };
+            delete next.notificationData.phoneSMS;
         }
         // If formData is not provided — no further normalization needed.
-        if (!body.formData)
-            return body;
+        if (!next.formData)
+            return next;
         // Wrap form fields in an object keyed by locale:
         // [{ marker, value }]  →  { "en_US": [{ marker, value }] }
-        const formData = {};
-        formData[langCode] = Array.isArray(body.formData)
-            ? body.formData
-            : [body.formData];
-        body.formData = formData;
-        return body;
+        // The fields themselves are reused by reference — they are not modified.
+        next.formData = {
+            [langCode]: Array.isArray(next.formData)
+                ? next.formData
+                : [next.formData],
+        };
+        return next;
     }
     /**
      * Normalizes the value of a single attribute in place.

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/discounts/discountsApi.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 { IBonusBalanceEntity, IBonusTransactionEntity, IBonusTransactionType, ICouponValidationResult, IDiscountsApi, IDiscountsEntity, IDiscountsResponse, IDiscountsVectorSearch, IDiscountType } from './discountsInterfaces';
+import type { IBonusBalanceEntity, IBonusHistoryResponse, IBonusTransactionType, ICouponValidationResult, IDiscountsApi, IDiscountsEntity, IDiscountsResponse, IDiscountsVectorSearch, IDiscountType } from './discountsInterfaces';
 /**
  * Controllers for working with events
  * @handle /api/content/events
@@ -63,11 +63,11 @@ export default class DiscountsApi extends AsyncModules implements IDiscountsApi
      * @param {number} [discountId] - Discount id filter.
      * @param {number} [moduleId] - Module id filter.
      * @param {boolean} [isAdmin] - Admin filter.
-     * @returns {Promise<IBonusTransactionEntity[] | IError>} Returns array of bonus transactions or an error object.
+     * @returns {Promise<IBonusHistoryResponse | IError>} Returns the container with the transactions and their total, or an error object.
      * @throws {IError} When isShell=false and an error occurs during the fetch
      * @see {@link https://js-sdk.oneentry.cloud/docs/discounts/getBonusHistory getBonusHistory} documentation.
      */
-    getBonusHistory(type?: IBonusTransactionType, dateFrom?: string, dateTo?: string, discountId?: number, moduleId?: number, isAdmin?: boolean): Promise<IBonusTransactionEntity[] | IError>;
+    getBonusHistory(type?: IBonusTransactionType, dateFrom?: string, dateTo?: string, discountId?: number, moduleId?: number, isAdmin?: boolean): Promise<IBonusHistoryResponse | IError>;
     /**
      * Validate discounts coupon
      * @handleName validateDiscountsCoupon

package/dist/discounts/discountsApi.js

@@ -85,7 +85,7 @@ class DiscountsApi extends asyncModules_1.default {
      * @param {number} [discountId] - Discount id filter.
      * @param {number} [moduleId] - Module id filter.
      * @param {boolean} [isAdmin] - Admin filter.
-     * @returns {Promise<IBonusTransactionEntity[] | IError>} Returns array of bonus transactions or an error object.
+     * @returns {Promise<IBonusHistoryResponse | IError>} Returns the container with the transactions and their total, or an error object.
      * @throws {IError} When isShell=false and an error occurs during the fetch
      * @see {@link https://js-sdk.oneentry.cloud/docs/discounts/getBonusHistory getBonusHistory} documentation.
      */

package/dist/discounts/discountsInterfaces.d.ts

@@ -55,10 +55,10 @@ interface IDiscountsApi {
      * @param {number} [discountId] - Discount id filter.
      * @param {number} [moduleId] - Module id filter.
      * @param {boolean} [isAdmin] - Admin filter.
-     * @returns {Promise<IBonusTransactionEntity[] | IError>} Returns array of bonus transactions or an error object.
+     * @returns {Promise<IBonusHistoryResponse | IError>} Returns the container with the transactions and their total, or an error object.
      * @throws {IError} When isShell=false and an error occurs during the fetch
      */
-    getBonusHistory(type?: IBonusTransactionType, dateFrom?: string, dateTo?: string, discountId?: number, moduleId?: number, isAdmin?: boolean): Promise<IBonusTransactionEntity[] | IError>;
+    getBonusHistory(type?: IBonusTransactionType, dateFrom?: string, dateTo?: string, discountId?: number, moduleId?: number, isAdmin?: boolean): Promise<IBonusHistoryResponse | IError>;
     /**
      * Semantic (vector) search for discounts.
      * @handleName getDiscountsByVectorSearch
@@ -284,6 +284,18 @@ interface IBonusTransactionEntity {
     expiresAt?: string;
     createdAt?: string;
 }
+/**
+ * @interface IBonusHistoryResponse
+ * @property {IBonusTransactionEntity[]} items - The transactions of the current page.
+ * @property {number} total - How many transactions the filter matches in total.
+ * @description Container the bonus history arrives in. The endpoint answers
+ * `{ items, total }`, not a bare array — measured on the SDK test stand,
+ * 2026-09-28: an account with no transactions answers `{"items":[],"total":0}`.
+ */
+interface IBonusHistoryResponse {
+    items: IBonusTransactionEntity[];
+    total: number;
+}
 /**
  * @interface IBonusBalanceEntity
  * @description Represents the balance of bonus points.
@@ -292,4 +304,4 @@ interface IBonusTransactionEntity {
 interface IBonusBalanceEntity {
     balance: number;
 }
-export type { IBonusBalanceEntity, IBonusHistoryQuery, IBonusTransactionEntity, IBonusTransactionType, ICouponEntity, ICouponValidationResult, IDiscountByMarkerQuery, IDiscountCondition, IDiscountsApi, IDiscountsEntity, IDiscountsQuery, IDiscountsResponse, IDiscountsValidateCoupon, IDiscountsVectorSearch, IDiscountType, IDiscountValue, };
+export type { IBonusBalanceEntity, IBonusHistoryQuery, IBonusHistoryResponse, IBonusTransactionEntity, IBonusTransactionType, ICouponEntity, ICouponValidationResult, IDiscountByMarkerQuery, IDiscountCondition, IDiscountsApi, IDiscountsEntity, IDiscountsQuery, IDiscountsResponse, IDiscountsValidateCoupon, IDiscountsVectorSearch, IDiscountType, IDiscountValue, };

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, };