@bitrix24/b24jssdk 1.1.2 → 1.3.0

package/dist/esm/index.d.mts

@@ -1006,6 +1006,7 @@ interface IResult<T = any> {
      * Retrieves an iterator for the errors collected in the result.
      *
      * @returns {IterableIterator<Error>} An iterator over the stored Error objects.
+     * @see {@link IResult.getErrorsByKey} — keeps the request keys.
      */
     getErrors: () => IterableIterator<Error>;
     /**
@@ -1014,6 +1015,21 @@ interface IResult<T = any> {
      * @returns {string[]} An array of strings representing the error messages.
      */
     getErrorMessages: () => string[];
+    /**
+     * Retrieves all errors keyed by their identifier (e.g. the batch request key),
+     * preserving which request produced each error. Unlike {@link getErrors}, the
+     * keys are not discarded — useful for batch calls with `isHaltOnError: false`.
+     *
+     * @returns {Record<string, Error>} A map of error key to Error object.
+     */
+    getErrorsByKey: () => Record<string, Error>;
+    /**
+     * Retrieves all error messages keyed by their identifier (e.g. the batch
+     * request key). Unlike {@link getErrorMessages}, the keys are preserved.
+     *
+     * @returns {Record<string, string>} A map of error key to error message.
+     */
+    getErrorMessagesByKey: () => Record<string, string>;
     /**
      * Checks for an error in a collection by key
      * @param key - Error key
@@ -1050,6 +1066,27 @@ declare class Result<T = any> implements IResult<T> {
      *          contains the message of a corresponding error object.
      */
     getErrorMessages(): string[];
+    /**
+     * Retrieves all errors as a plain object (a snapshot copy) keyed by their
+     * identifier, preserving which request produced each error. Unlike
+     * {@link Result.getErrors}, the keys are not discarded — useful for batch
+     * calls with `isHaltOnError: false`.
+     *
+     * Keys are meaningful only when the error was added with an explicit key
+     * (e.g. an object / named-command batch). Array-mode batches and
+     * {@link Result.addErrors} fall back to generated UUID keys.
+     *
+     * @returns {Record<string, Error>} A map of error key to Error object.
+     */
+    getErrorsByKey(): Record<string, Error>;
+    /**
+     * Retrieves all error messages as a plain object (a snapshot copy) keyed by
+     * their identifier. Unlike {@link Result.getErrorMessages}, the keys are
+     * preserved. See {@link Result.getErrorsByKey} for when keys are meaningful.
+     *
+     * @returns {Record<string, string>} A map of error key to error message.
+     */
+    getErrorMessagesByKey(): Record<string, string>;
     /**
      * Converts the Result object to a string.
      *
@@ -1465,6 +1502,7 @@ type ActionCallListV2 = ActionOptions & {
     method: string;
     params?: Omit<TypeCallParams, 'start' | 'order'>;
     idKey?: string;
+    cursorIdKey?: string;
     customKeyForResult?: string;
     requestId?: string;
 };
@@ -1481,12 +1519,16 @@ declare class CallListV2 extends AbstractAction {
      *
      * @param {ActionCallListV2} options - parameters for executing the request.
      *     - `method: string` - The name of the REST API method that returns a list of data (for example: `crm.item.list`, `tasks.task.list`)
-     *     - `params?: Omit<TypeCallParams, 'start'>` - Request parameters, excluding the `start` parameter,
+     *     - `params?: Omit<TypeCallParams, 'start' | 'order'>` - Request parameters, excluding the `start` and `order` parameters,
      *         since the method is designed to obtain all data in one call.
      *         Note: Use `filter`, `order`, and `select` to control the selection.
-     *     - `idKey?: string` - The name of the field containing the unique identifier of the element.
-     *         Default is 'ID' (uppercase). Alternatively, it can be 'id' (lowercase).
-     *         or another field, depending on the REST API data structure.
+     *     - `idKey?: string` - The name of the id field as it appears in each RESPONSE item; its value
+     *         drives the cursor. Default is 'ID' (uppercase). For methods that return a lowercase /
+     *         camelCase id (for example `tasks.task.list` returns `id`), set `idKey: 'id'`.
+     *     - `cursorIdKey?: string` - The field name used in the REQUEST for `order` and the `>` page
+     *         filter. Defaults to `idKey`. Set it only when the sortable / filterable field name differs
+     *         from the response field name — e.g. `tasks.task.list` sorts and filters by `ID` (uppercase)
+     *         but returns `id` (lowercase): pass `idKey: 'id', cursorIdKey: 'ID'`.
      *     - `customKeyForResult?: string` - A custom key indicating that the response REST API will be
      *        grouped by this field.
      *        Example: `items` to group a list of CRM items.
@@ -1528,6 +1570,7 @@ type ActionFetchListV2 = ActionOptions & {
     method: string;
     params?: Omit<TypeCallParams, 'start' | 'order'>;
     idKey?: string;
+    cursorIdKey?: string;
     customKeyForResult?: string;
     requestId?: string;
 };
@@ -1545,12 +1588,16 @@ declare class FetchListV2 extends AbstractAction {
      *
      * @param {ActionFetchListV2} options - parameters for executing the request.
      *     - `method: string` - The name of the REST API method that returns a list of data (for example: `crm.item.list`, `tasks.task.list`)
-     *     - `params?: Omit<TypeCallParams, 'start'>` - Request parameters, excluding the `start` parameter,
+     *     - `params?: Omit<TypeCallParams, 'start' | 'order'>` - Request parameters, excluding the `start` and `order` parameters,
      *         since the method is designed to obtain all data in one call.
      *         Note: Use `filter`, `order`, and `select` to control the selection.
-     *     - `idKey?: string` - The name of the field containing the unique identifier of the element.
-     *         Default is 'ID' (uppercase). Alternatively, it can be 'id' (lowercase).
-     *         or another field, depending on the REST API data structure.
+     *     - `idKey?: string` - The name of the id field as it appears in each RESPONSE item; its value
+     *         drives the cursor. Default is 'ID' (uppercase). For methods that return a lowercase /
+     *         camelCase id (for example `tasks.task.list` returns `id`), set `idKey: 'id'`.
+     *     - `cursorIdKey?: string` - The field name used in the REQUEST for `order` and the `>` page
+     *         filter. Defaults to `idKey`. Set it only when the sortable / filterable field name differs
+     *         from the response field name — e.g. `tasks.task.list` sorts and filters by `ID` (uppercase)
+     *         but returns `id` (lowercase): pass `idKey: 'id', cursorIdKey: 'ID'`.
      *     - `customKeyForResult?: string` - A custom key indicating that the response REST API will be
      *        grouped by this field.
      *        Example: `items` to group a list of CRM items.
@@ -1659,7 +1706,7 @@ declare class BatchV2 extends AbstractBatch {
      * const resultData = (response as Result<AjaxResult<{ item: Contact }>[]>).getData()
      * resultData.forEach((resultRow, index) => {
      *   if (resultRow.isSuccess) {
-     *    console.log(`Item ${index + 1}:`, resultRow.getData().result.item)
+     *    console.log(`Item ${index + 1}:`, resultRow.getData()!.result.item)
      *   }
      * })
      *
@@ -1702,8 +1749,8 @@ declare class BatchV2 extends AbstractBatch {
      * }
      *
      * const results = response.getData() as Record<string, AjaxResult<{ item: Contact } | { item: Deal }>>
-     * console.log('Contact:', results.Contact.getData().result.item as Contact)
-     * console.log('Deal:', results.Deal.getData().result.item as Deal)
+     * console.log('Contact:', results.Contact.getData()?.result.item as Contact)
+     * console.log('Deal:', results.Deal.getData()?.result.item as Deal)
      *
      * @warning The maximum number of commands in one batch request is 50.
      * @note A batch request executes faster than sequential single calls,
@@ -1833,6 +1880,7 @@ type ActionCallListV3 = ActionOptions & {
     method: string;
     params?: Omit<TypeCallParams, 'pagination' | 'order'>;
     idKey?: string;
+    cursorIdKey?: string;
     customKeyForResult: string;
     requestId?: string;
     limit?: number;
@@ -1850,11 +1898,15 @@ declare class CallListV3 extends AbstractAction {
      *
      * @param {ActionCallListV3} options - parameters for executing the request.
      *     - `method: string` - The name of the REST API method that returns a list of data (for example: `crm.item.list`, `tasks.task.list`)
-     *     - `params?: Omit<TypeCallParams, 'pagination'>` - Request parameters, excluding the `pagination` parameter,
+     *     - `params?: Omit<TypeCallParams, 'pagination' | 'order'>` - Request parameters, excluding the `pagination` and `order` parameters,
      *         since the method is designed to obtain all data in one call.
      *         Note: Use `filter`, `order`, and `select` to control the selection.
-     *     - `idKey?: string` - The name of the field containing the unique identifier of the element.
-     *         Default is 'id'. Alternatively, it can be another field, depending on the REST API data structure.
+     *     - `idKey?: string` - The name of the id field as it appears in each RESPONSE item; its value
+     *         drives the cursor. Default is 'id'. Set it to match the id field the method returns.
+     *     - `cursorIdKey?: string` - The field name used in the REQUEST for `order` and the
+     *         `[field, '>', n]` page filter. Defaults to `idKey`. Set it only when the sortable /
+     *         filterable field name differs from the response field name (e.g. an uppercase request
+     *         field but a lowercase response id): pass `idKey: 'id', cursorIdKey: 'ID'`.
      *     - `customKeyForResult: string` - A custom key indicating that the response REST API will be
      *        grouped by this field.
      *        Example: `items` to group a list of CRM items.
@@ -1896,6 +1948,7 @@ type ActionFetchListV3 = ActionOptions & {
     method: string;
     params?: Omit<TypeCallParams, 'pagination' | 'order'>;
     idKey?: string;
+    cursorIdKey?: string;
     customKeyForResult: string;
     requestId?: string;
     limit?: number;
@@ -1914,11 +1967,15 @@ declare class FetchListV3 extends AbstractAction {
      *
      * @param {ActionFetchListV3} options - parameters for executing the request.
      *     - `method: string` - The name of the REST API method that returns a list of data (for example: `crm.item.list`, `tasks.task.list`)
-     *     - `params?: Omit<TypeCallParams, 'pagination'>` - Request parameters, excluding the `pagination` parameter,
+     *     - `params?: Omit<TypeCallParams, 'pagination' | 'order'>` - Request parameters, excluding the `pagination` and `order` parameters,
      *         since the method is designed to obtain all data in one call.
      *         Note: Use `filter`, `order`, and `select` to control the selection.
-     *     - `idKey?: string` - The name of the field containing the unique identifier of the element.
-     *         Default is 'id'. Alternatively, it can be another field, depending on the REST API data structure.
+     *     - `idKey?: string` - The name of the id field as it appears in each RESPONSE item; its value
+     *         drives the cursor. Default is 'id'. Set it to match the id field the method returns.
+     *     - `cursorIdKey?: string` - The field name used in the REQUEST for `order` and the
+     *         `[field, '>', n]` page filter. Defaults to `idKey`. Set it only when the sortable /
+     *         filterable field name differs from the response field name (e.g. an uppercase request
+     *         field but a lowercase response id): pass `idKey: 'id', cursorIdKey: 'ID'`.
      *     - `customKeyForResult: string` - A custom key indicating that the response REST API will be
      *        grouped by this field.
      *        Example: `items` to group a list of CRM items.
@@ -2012,7 +2069,7 @@ declare class BatchV3 extends AbstractBatch {
      * const resultData = (response as Result<AjaxResult<{ item: TaskItem }>[]>).getData()
      * resultData.forEach((resultRow, index) => {
      *   if (resultRow.isSuccess) {
-     *    console.log(`Item ${index + 1}:`, resultRow.getData().result.item)
+     *    console.log(`Item ${index + 1}:`, resultRow.getData()!.result.item)
      *   }
      * })
      *
@@ -2051,8 +2108,8 @@ declare class BatchV3 extends AbstractBatch {
      * }
      *
      * const results = response.getData() as Record<string, AjaxResult<{ item: TaskItem } | { items: MainEventLogItem[] }>>
-     * console.log('Task:', results.Task.getData().result.item as TaskItem)
-     * console.log('MainEventLog:', results.MainEventLog.getData().result.items as MainEventLogItem[])
+     * console.log('Task:', results.Task.getData()?.result.item as TaskItem)
+     * console.log('MainEventLog:', results.MainEventLog.getData()?.result.items as MainEventLogItem[])
      *
      * @warning The maximum number of commands in one batch request is 50.
      * @note A batch request executes faster than sequential single calls,
@@ -4053,7 +4110,9 @@ declare class RestrictionManager {
 }
 
 /**
- * @todo add docs ??
+ * Decides which REST API version (v2 or v3) a method is routed through:
+ * v3 only for methods on the published allowlist (`#supportMethods`); everything
+ * else falls back to v2.
  */
 declare class VersionManager {
     #private;
@@ -4226,6 +4285,12 @@ declare abstract class AbstractHttp implements TypeHttp {
     protected _authActions: AuthActions;
     protected _requestIdGenerator: RequestIdGenerator;
     protected _restrictionManager: RestrictionManager;
+    /**
+     * In-flight token refresh, shared so concurrent 401s coalesce into a single
+     * `refreshAuth()` round-trip — avoids OAuth refresh-token reuse errors when a
+     * burst of requests expires together. (#182)
+     */
+    protected _pendingRefresh: Promise<AuthData> | null;
     protected _logger: LoggerInterface;
     protected _isClientSideWarning: boolean;
     protected _clientSideWarningMessage: string;
@@ -4298,6 +4363,12 @@ declare abstract class AbstractHttp implements TypeHttp {
      */
     protected _executeSingleCall<T = unknown>(requestId: string, method: string, params: TypeCallParams): Promise<AjaxResult<T>>;
     protected _ensureAuth(requestId: string): Promise<AuthData>;
+    /**
+     * Refresh the auth token, coalescing concurrent callers onto a single
+     * in-flight `refreshAuth()` so a burst of 401s triggers exactly one refresh
+     * round-trip. The slot clears once the refresh settles. (#182)
+     */
+    protected _refreshAuth(): Promise<AuthData>;
     protected _makeRequestWithAuthRetry<T>(requestId: string, method: string, params: TypeCallParams, authData: AuthData): Promise<AjaxResponse<T>>;
     protected _makeAxiosRequest<T>(requestId: string, method: string, params: TypeCallParams, authData: AuthData): Promise<AjaxResponse<T>>;
     protected _isAuthError(error: unknown): boolean;
@@ -4785,7 +4856,11 @@ declare class ParentManager {
      */
     reloadWindow(): Promise<void>;
     /**
-     * Set Page Title
+     * Sets the in-layout page title (the `#pagetitle` element the portal renders around the app).
+     *
+     * Does NOT change the browser tab title (`document.title`): the portal applies this command to
+     * `#pagetitle`, never to the tab. To set the browser tab title, open the view as a slider via
+     * `SliderManager.openSliderAppPage` with a `bx24_title` option.
      *
      * @param {string} title
      *
@@ -5060,6 +5135,10 @@ declare class SliderManager {
     /**
      * When the method is called, a pop-up window with the application frame will be opened.
      *
+     * Settings are passed via `bx24_`-prefixed keys (e.g. `bx24_title`, `bx24_width`).
+     * `bx24_title` sets the slider title; the portal also reflects it to the browser tab title
+     * (`document.title`) — unlike `ParentManager.setTitle`, which only updates the in-layout `#pagetitle`.
+     *
      * @link https://apidocs.bitrix24.com/sdk/bx24-js-sdk/additional-functions/bx24-open-application.html
      */
     openSliderAppPage(params?: any): Promise<any>;

package/dist/esm/index.d.ts

@@ -1006,6 +1006,7 @@ interface IResult<T = any> {
      * Retrieves an iterator for the errors collected in the result.
      *
      * @returns {IterableIterator<Error>} An iterator over the stored Error objects.
+     * @see {@link IResult.getErrorsByKey} — keeps the request keys.
      */
     getErrors: () => IterableIterator<Error>;
     /**
@@ -1014,6 +1015,21 @@ interface IResult<T = any> {
      * @returns {string[]} An array of strings representing the error messages.
      */
     getErrorMessages: () => string[];
+    /**
+     * Retrieves all errors keyed by their identifier (e.g. the batch request key),
+     * preserving which request produced each error. Unlike {@link getErrors}, the
+     * keys are not discarded — useful for batch calls with `isHaltOnError: false`.
+     *
+     * @returns {Record<string, Error>} A map of error key to Error object.
+     */
+    getErrorsByKey: () => Record<string, Error>;
+    /**
+     * Retrieves all error messages keyed by their identifier (e.g. the batch
+     * request key). Unlike {@link getErrorMessages}, the keys are preserved.
+     *
+     * @returns {Record<string, string>} A map of error key to error message.
+     */
+    getErrorMessagesByKey: () => Record<string, string>;
     /**
      * Checks for an error in a collection by key
      * @param key - Error key
@@ -1050,6 +1066,27 @@ declare class Result<T = any> implements IResult<T> {
      *          contains the message of a corresponding error object.
      */
     getErrorMessages(): string[];
+    /**
+     * Retrieves all errors as a plain object (a snapshot copy) keyed by their
+     * identifier, preserving which request produced each error. Unlike
+     * {@link Result.getErrors}, the keys are not discarded — useful for batch
+     * calls with `isHaltOnError: false`.
+     *
+     * Keys are meaningful only when the error was added with an explicit key
+     * (e.g. an object / named-command batch). Array-mode batches and
+     * {@link Result.addErrors} fall back to generated UUID keys.
+     *
+     * @returns {Record<string, Error>} A map of error key to Error object.
+     */
+    getErrorsByKey(): Record<string, Error>;
+    /**
+     * Retrieves all error messages as a plain object (a snapshot copy) keyed by
+     * their identifier. Unlike {@link Result.getErrorMessages}, the keys are
+     * preserved. See {@link Result.getErrorsByKey} for when keys are meaningful.
+     *
+     * @returns {Record<string, string>} A map of error key to error message.
+     */
+    getErrorMessagesByKey(): Record<string, string>;
     /**
      * Converts the Result object to a string.
      *
@@ -1465,6 +1502,7 @@ type ActionCallListV2 = ActionOptions & {
     method: string;
     params?: Omit<TypeCallParams, 'start' | 'order'>;
     idKey?: string;
+    cursorIdKey?: string;
     customKeyForResult?: string;
     requestId?: string;
 };
@@ -1481,12 +1519,16 @@ declare class CallListV2 extends AbstractAction {
      *
      * @param {ActionCallListV2} options - parameters for executing the request.
      *     - `method: string` - The name of the REST API method that returns a list of data (for example: `crm.item.list`, `tasks.task.list`)
-     *     - `params?: Omit<TypeCallParams, 'start'>` - Request parameters, excluding the `start` parameter,
+     *     - `params?: Omit<TypeCallParams, 'start' | 'order'>` - Request parameters, excluding the `start` and `order` parameters,
      *         since the method is designed to obtain all data in one call.
      *         Note: Use `filter`, `order`, and `select` to control the selection.
-     *     - `idKey?: string` - The name of the field containing the unique identifier of the element.
-     *         Default is 'ID' (uppercase). Alternatively, it can be 'id' (lowercase).
-     *         or another field, depending on the REST API data structure.
+     *     - `idKey?: string` - The name of the id field as it appears in each RESPONSE item; its value
+     *         drives the cursor. Default is 'ID' (uppercase). For methods that return a lowercase /
+     *         camelCase id (for example `tasks.task.list` returns `id`), set `idKey: 'id'`.
+     *     - `cursorIdKey?: string` - The field name used in the REQUEST for `order` and the `>` page
+     *         filter. Defaults to `idKey`. Set it only when the sortable / filterable field name differs
+     *         from the response field name — e.g. `tasks.task.list` sorts and filters by `ID` (uppercase)
+     *         but returns `id` (lowercase): pass `idKey: 'id', cursorIdKey: 'ID'`.
      *     - `customKeyForResult?: string` - A custom key indicating that the response REST API will be
      *        grouped by this field.
      *        Example: `items` to group a list of CRM items.
@@ -1528,6 +1570,7 @@ type ActionFetchListV2 = ActionOptions & {
     method: string;
     params?: Omit<TypeCallParams, 'start' | 'order'>;
     idKey?: string;
+    cursorIdKey?: string;
     customKeyForResult?: string;
     requestId?: string;
 };
@@ -1545,12 +1588,16 @@ declare class FetchListV2 extends AbstractAction {
      *
      * @param {ActionFetchListV2} options - parameters for executing the request.
      *     - `method: string` - The name of the REST API method that returns a list of data (for example: `crm.item.list`, `tasks.task.list`)
-     *     - `params?: Omit<TypeCallParams, 'start'>` - Request parameters, excluding the `start` parameter,
+     *     - `params?: Omit<TypeCallParams, 'start' | 'order'>` - Request parameters, excluding the `start` and `order` parameters,
      *         since the method is designed to obtain all data in one call.
      *         Note: Use `filter`, `order`, and `select` to control the selection.
-     *     - `idKey?: string` - The name of the field containing the unique identifier of the element.
-     *         Default is 'ID' (uppercase). Alternatively, it can be 'id' (lowercase).
-     *         or another field, depending on the REST API data structure.
+     *     - `idKey?: string` - The name of the id field as it appears in each RESPONSE item; its value
+     *         drives the cursor. Default is 'ID' (uppercase). For methods that return a lowercase /
+     *         camelCase id (for example `tasks.task.list` returns `id`), set `idKey: 'id'`.
+     *     - `cursorIdKey?: string` - The field name used in the REQUEST for `order` and the `>` page
+     *         filter. Defaults to `idKey`. Set it only when the sortable / filterable field name differs
+     *         from the response field name — e.g. `tasks.task.list` sorts and filters by `ID` (uppercase)
+     *         but returns `id` (lowercase): pass `idKey: 'id', cursorIdKey: 'ID'`.
      *     - `customKeyForResult?: string` - A custom key indicating that the response REST API will be
      *        grouped by this field.
      *        Example: `items` to group a list of CRM items.
@@ -1659,7 +1706,7 @@ declare class BatchV2 extends AbstractBatch {
      * const resultData = (response as Result<AjaxResult<{ item: Contact }>[]>).getData()
      * resultData.forEach((resultRow, index) => {
      *   if (resultRow.isSuccess) {
-     *    console.log(`Item ${index + 1}:`, resultRow.getData().result.item)
+     *    console.log(`Item ${index + 1}:`, resultRow.getData()!.result.item)
      *   }
      * })
      *
@@ -1702,8 +1749,8 @@ declare class BatchV2 extends AbstractBatch {
      * }
      *
      * const results = response.getData() as Record<string, AjaxResult<{ item: Contact } | { item: Deal }>>
-     * console.log('Contact:', results.Contact.getData().result.item as Contact)
-     * console.log('Deal:', results.Deal.getData().result.item as Deal)
+     * console.log('Contact:', results.Contact.getData()?.result.item as Contact)
+     * console.log('Deal:', results.Deal.getData()?.result.item as Deal)
      *
      * @warning The maximum number of commands in one batch request is 50.
      * @note A batch request executes faster than sequential single calls,
@@ -1833,6 +1880,7 @@ type ActionCallListV3 = ActionOptions & {
     method: string;
     params?: Omit<TypeCallParams, 'pagination' | 'order'>;
     idKey?: string;
+    cursorIdKey?: string;
     customKeyForResult: string;
     requestId?: string;
     limit?: number;
@@ -1850,11 +1898,15 @@ declare class CallListV3 extends AbstractAction {
      *
      * @param {ActionCallListV3} options - parameters for executing the request.
      *     - `method: string` - The name of the REST API method that returns a list of data (for example: `crm.item.list`, `tasks.task.list`)
-     *     - `params?: Omit<TypeCallParams, 'pagination'>` - Request parameters, excluding the `pagination` parameter,
+     *     - `params?: Omit<TypeCallParams, 'pagination' | 'order'>` - Request parameters, excluding the `pagination` and `order` parameters,
      *         since the method is designed to obtain all data in one call.
      *         Note: Use `filter`, `order`, and `select` to control the selection.
-     *     - `idKey?: string` - The name of the field containing the unique identifier of the element.
-     *         Default is 'id'. Alternatively, it can be another field, depending on the REST API data structure.
+     *     - `idKey?: string` - The name of the id field as it appears in each RESPONSE item; its value
+     *         drives the cursor. Default is 'id'. Set it to match the id field the method returns.
+     *     - `cursorIdKey?: string` - The field name used in the REQUEST for `order` and the
+     *         `[field, '>', n]` page filter. Defaults to `idKey`. Set it only when the sortable /
+     *         filterable field name differs from the response field name (e.g. an uppercase request
+     *         field but a lowercase response id): pass `idKey: 'id', cursorIdKey: 'ID'`.
      *     - `customKeyForResult: string` - A custom key indicating that the response REST API will be
      *        grouped by this field.
      *        Example: `items` to group a list of CRM items.
@@ -1896,6 +1948,7 @@ type ActionFetchListV3 = ActionOptions & {
     method: string;
     params?: Omit<TypeCallParams, 'pagination' | 'order'>;
     idKey?: string;
+    cursorIdKey?: string;
     customKeyForResult: string;
     requestId?: string;
     limit?: number;
@@ -1914,11 +1967,15 @@ declare class FetchListV3 extends AbstractAction {
      *
      * @param {ActionFetchListV3} options - parameters for executing the request.
      *     - `method: string` - The name of the REST API method that returns a list of data (for example: `crm.item.list`, `tasks.task.list`)
-     *     - `params?: Omit<TypeCallParams, 'pagination'>` - Request parameters, excluding the `pagination` parameter,
+     *     - `params?: Omit<TypeCallParams, 'pagination' | 'order'>` - Request parameters, excluding the `pagination` and `order` parameters,
      *         since the method is designed to obtain all data in one call.
      *         Note: Use `filter`, `order`, and `select` to control the selection.
-     *     - `idKey?: string` - The name of the field containing the unique identifier of the element.
-     *         Default is 'id'. Alternatively, it can be another field, depending on the REST API data structure.
+     *     - `idKey?: string` - The name of the id field as it appears in each RESPONSE item; its value
+     *         drives the cursor. Default is 'id'. Set it to match the id field the method returns.
+     *     - `cursorIdKey?: string` - The field name used in the REQUEST for `order` and the
+     *         `[field, '>', n]` page filter. Defaults to `idKey`. Set it only when the sortable /
+     *         filterable field name differs from the response field name (e.g. an uppercase request
+     *         field but a lowercase response id): pass `idKey: 'id', cursorIdKey: 'ID'`.
      *     - `customKeyForResult: string` - A custom key indicating that the response REST API will be
      *        grouped by this field.
      *        Example: `items` to group a list of CRM items.
@@ -2012,7 +2069,7 @@ declare class BatchV3 extends AbstractBatch {
      * const resultData = (response as Result<AjaxResult<{ item: TaskItem }>[]>).getData()
      * resultData.forEach((resultRow, index) => {
      *   if (resultRow.isSuccess) {
-     *    console.log(`Item ${index + 1}:`, resultRow.getData().result.item)
+     *    console.log(`Item ${index + 1}:`, resultRow.getData()!.result.item)
      *   }
      * })
      *
@@ -2051,8 +2108,8 @@ declare class BatchV3 extends AbstractBatch {
      * }
      *
      * const results = response.getData() as Record<string, AjaxResult<{ item: TaskItem } | { items: MainEventLogItem[] }>>
-     * console.log('Task:', results.Task.getData().result.item as TaskItem)
-     * console.log('MainEventLog:', results.MainEventLog.getData().result.items as MainEventLogItem[])
+     * console.log('Task:', results.Task.getData()?.result.item as TaskItem)
+     * console.log('MainEventLog:', results.MainEventLog.getData()?.result.items as MainEventLogItem[])
      *
      * @warning The maximum number of commands in one batch request is 50.
      * @note A batch request executes faster than sequential single calls,
@@ -4053,7 +4110,9 @@ declare class RestrictionManager {
 }
 
 /**
- * @todo add docs ??
+ * Decides which REST API version (v2 or v3) a method is routed through:
+ * v3 only for methods on the published allowlist (`#supportMethods`); everything
+ * else falls back to v2.
  */
 declare class VersionManager {
     #private;
@@ -4226,6 +4285,12 @@ declare abstract class AbstractHttp implements TypeHttp {
     protected _authActions: AuthActions;
     protected _requestIdGenerator: RequestIdGenerator;
     protected _restrictionManager: RestrictionManager;
+    /**
+     * In-flight token refresh, shared so concurrent 401s coalesce into a single
+     * `refreshAuth()` round-trip — avoids OAuth refresh-token reuse errors when a
+     * burst of requests expires together. (#182)
+     */
+    protected _pendingRefresh: Promise<AuthData> | null;
     protected _logger: LoggerInterface;
     protected _isClientSideWarning: boolean;
     protected _clientSideWarningMessage: string;
@@ -4298,6 +4363,12 @@ declare abstract class AbstractHttp implements TypeHttp {
      */
     protected _executeSingleCall<T = unknown>(requestId: string, method: string, params: TypeCallParams): Promise<AjaxResult<T>>;
     protected _ensureAuth(requestId: string): Promise<AuthData>;
+    /**
+     * Refresh the auth token, coalescing concurrent callers onto a single
+     * in-flight `refreshAuth()` so a burst of 401s triggers exactly one refresh
+     * round-trip. The slot clears once the refresh settles. (#182)
+     */
+    protected _refreshAuth(): Promise<AuthData>;
     protected _makeRequestWithAuthRetry<T>(requestId: string, method: string, params: TypeCallParams, authData: AuthData): Promise<AjaxResponse<T>>;
     protected _makeAxiosRequest<T>(requestId: string, method: string, params: TypeCallParams, authData: AuthData): Promise<AjaxResponse<T>>;
     protected _isAuthError(error: unknown): boolean;
@@ -4785,7 +4856,11 @@ declare class ParentManager {
      */
     reloadWindow(): Promise<void>;
     /**
-     * Set Page Title
+     * Sets the in-layout page title (the `#pagetitle` element the portal renders around the app).
+     *
+     * Does NOT change the browser tab title (`document.title`): the portal applies this command to
+     * `#pagetitle`, never to the tab. To set the browser tab title, open the view as a slider via
+     * `SliderManager.openSliderAppPage` with a `bx24_title` option.
      *
      * @param {string} title
      *
@@ -5060,6 +5135,10 @@ declare class SliderManager {
     /**
      * When the method is called, a pop-up window with the application frame will be opened.
      *
+     * Settings are passed via `bx24_`-prefixed keys (e.g. `bx24_title`, `bx24_width`).
+     * `bx24_title` sets the slider title; the portal also reflects it to the browser tab title
+     * (`document.title`) — unlike `ParentManager.setTitle`, which only updates the in-layout `#pagetitle`.
+     *
      * @link https://apidocs.bitrix24.com/sdk/bx24-js-sdk/additional-functions/bx24-open-application.html
      */
     openSliderAppPage(params?: any): Promise<any>;

package/dist/esm/index.mjs

@@ -1,6 +1,6 @@
 /**
  * @package @bitrix24/b24jssdk
- * @version 1.1.2
+ * @version 1.3.0
  * @copyright (c) 2026 Bitrix24
  * @license MIT
  * @see https://github.com/bitrix24/b24jssdk

package/dist/esm/loader-b24frame.mjs

@@ -1,6 +1,6 @@
 /**
  * @package @bitrix24/b24jssdk
- * @version 1.1.2
+ * @version 1.3.0
  * @copyright (c) 2026 Bitrix24
  * @license MIT
  * @see https://github.com/bitrix24/b24jssdk

package/dist/esm/logger/abstract-logger.mjs

@@ -1,6 +1,6 @@
 /**
  * @package @bitrix24/b24jssdk
- * @version 1.1.2
+ * @version 1.3.0
  * @copyright (c) 2026 Bitrix24
  * @license MIT
  * @see https://github.com/bitrix24/b24jssdk

package/dist/esm/logger/browser.mjs

@@ -1,6 +1,6 @@
 /**
  * @package @bitrix24/b24jssdk
- * @version 1.1.2
+ * @version 1.3.0
  * @copyright (c) 2026 Bitrix24
  * @license MIT
  * @see https://github.com/bitrix24/b24jssdk

package/dist/esm/logger/formatter/abstract-formatter.mjs

@@ -1,6 +1,6 @@
 /**
  * @package @bitrix24/b24jssdk
- * @version 1.1.2
+ * @version 1.3.0
  * @copyright (c) 2026 Bitrix24
  * @license MIT
  * @see https://github.com/bitrix24/b24jssdk

package/dist/esm/logger/formatter/json-formatter.mjs

@@ -1,6 +1,6 @@
 /**
  * @package @bitrix24/b24jssdk
- * @version 1.1.2
+ * @version 1.3.0
  * @copyright (c) 2026 Bitrix24
  * @license MIT
  * @see https://github.com/bitrix24/b24jssdk

package/dist/esm/logger/formatter/line-formatter.mjs

@@ -1,6 +1,6 @@
 /**
  * @package @bitrix24/b24jssdk
- * @version 1.1.2
+ * @version 1.3.0
  * @copyright (c) 2026 Bitrix24
  * @license MIT
  * @see https://github.com/bitrix24/b24jssdk

package/dist/esm/logger/formatter/telegram-formatter.mjs

@@ -1,6 +1,6 @@
 /**
  * @package @bitrix24/b24jssdk
- * @version 1.1.2
+ * @version 1.3.0
  * @copyright (c) 2026 Bitrix24
  * @license MIT
  * @see https://github.com/bitrix24/b24jssdk

package/dist/esm/logger/handler/abstract-handler.mjs

@@ -1,6 +1,6 @@
 /**
  * @package @bitrix24/b24jssdk
- * @version 1.1.2
+ * @version 1.3.0
  * @copyright (c) 2026 Bitrix24
  * @license MIT
  * @see https://github.com/bitrix24/b24jssdk

package/dist/esm/logger/handler/consola-adapter.mjs

@@ -1,6 +1,6 @@
 /**
  * @package @bitrix24/b24jssdk
- * @version 1.1.2
+ * @version 1.3.0
  * @copyright (c) 2026 Bitrix24
  * @license MIT
  * @see https://github.com/bitrix24/b24jssdk

package/dist/esm/logger/handler/console-handler.mjs

@@ -1,6 +1,6 @@
 /**
  * @package @bitrix24/b24jssdk
- * @version 1.1.2
+ * @version 1.3.0
  * @copyright (c) 2026 Bitrix24
  * @license MIT
  * @see https://github.com/bitrix24/b24jssdk

package/dist/esm/logger/handler/console-v2-handler.mjs

@@ -1,6 +1,6 @@
 /**
  * @package @bitrix24/b24jssdk
- * @version 1.1.2
+ * @version 1.3.0
  * @copyright (c) 2026 Bitrix24
  * @license MIT
  * @see https://github.com/bitrix24/b24jssdk