@bitrix24/b24jssdk 1.3.0 → 2.0.0

package/dist/esm/index.d.mts

@@ -1072,9 +1072,16 @@ declare class Result<T = any> implements IResult<T> {
      * {@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.
+     * For batch calls the key tells you *which* command failed:
+     * - an **object / named-command batch** keys each error by the command label;
+     * - an **array-mode batch** keys each per-command error by its **numeric
+     *   position** (`'0'`, `'1'`, … as a string), matching the command order you
+     *   passed in. (#255 — previously these fell back to a random UUID.)
+     *
+     * An envelope-level soft error (not tied to one command) lands under the
+     * internal `'base-error'` key, and {@link Result.addErrors} (no explicit key)
+     * still uses generated UUIDs — for those, prefer {@link Result.getErrors} /
+     * {@link Result.getErrorMessages}. (#230)
      *
      * @returns {Record<string, Error>} A map of error key to Error object.
      */
@@ -2014,6 +2021,178 @@ declare class FetchListV3 extends AbstractAction {
     make<T = unknown>(options: ActionFetchListV3): AsyncGenerator<T[]>;
 }
 
+type ActionCallTailV3 = ActionOptions & {
+    method: string;
+    params?: Omit<TypeCallParams, 'pagination' | 'order' | 'cursor'>;
+    cursorField?: string;
+    order?: 'ASC' | 'DESC' | 'asc' | 'desc' | string;
+    customKeyForResult?: string;
+    requestId?: string;
+    limit?: number;
+    initialValue?: number | string;
+};
+/**
+ * Fast data retrieval via the native `tail` (keyset cursor) action, without
+ * counting the total number of records. `restApi:v3`
+ *
+ * The eager counterpart of `fetchTail`: it walks the same native
+ * `cursor: { field, value, order, limit }` pagination and returns every record
+ * as a single array. See the v3 reference §6.2. The cursor field MUST NOT appear
+ * in `filter`.
+ */
+declare class CallTailV3 extends AbstractAction {
+    /**
+     * Returns every record of a `tail` method as one array.
+     *
+     * @template T - The type of the elements of the returned array (default is `unknown`).
+     *
+     * @param {ActionCallTailV3} options - parameters for executing the request.
+     *     - `method: string` - A REST API `tail` method name (for example: `main.eventlog.tail`).
+     *     - `params?: Omit<TypeCallParams, 'pagination' | 'order' | 'cursor'>` - Request parameters
+     *         (`filter`, `select`). `pagination`, `order` and `cursor` are managed by this helper.
+     *         The cursor field must NOT be used in `filter`.
+     *     - `cursorField?: string` - The DTO field that drives the cursor. Default is `id`.
+     *     - `order?: 'ASC' | 'DESC'` - Cursor direction. Default is `ASC`. For `DESC` you MUST pass
+     *         `initialValue` (the server pages by `field < value`, so the default `0` returns nothing).
+     *     - `customKeyForResult?: string` - The key the response groups rows under. Default is `items`.
+     *     - `requestId?: string` - Unique request identifier for tracking.
+     *     - `limit?: number` - How many records to retrieve at a time. Default is `50`. Maximum is `1000`.
+     *     - `initialValue?: number | string` - Cursor start value for the first page. Default is `0`
+     *         (valid for ascending numeric fields); required for `DESC` and for non-numeric fields.
+     *
+     * @returns {Promise<Result<T[]>>} A promise that resolves to the result of an REST API call.
+     *
+     * @example
+     * const response = await b24.actions.v3.callTail.make<{ id: string }>({
+     *   method: 'main.eventlog.tail',
+     *   params: { select: ['id', 'auditType'] },
+     *   cursorField: 'id',
+     *   customKeyForResult: 'items'
+     * })
+     * if (!response.isSuccess) {
+     *   throw new Error(`Problem: ${response.getErrorMessages().join('; ')}`)
+     * }
+     * console.log(`Result: ${response.getData()?.length}`)
+     */
+    make<T = unknown>(options: ActionCallTailV3): Promise<Result<T[]>>;
+}
+
+type ActionFetchTailV3 = ActionOptions & {
+    method: string;
+    params?: Omit<TypeCallParams, 'pagination' | 'order' | 'cursor'>;
+    cursorField?: string;
+    order?: 'ASC' | 'DESC' | 'asc' | 'desc' | string;
+    customKeyForResult?: string;
+    requestId?: string;
+    limit?: number;
+    initialValue?: number | string;
+};
+/**
+ * Calls a REST API `tail` method (native keyset cursor) and returns an async
+ * generator for efficient large data retrieval. `restApi:v3`
+ *
+ * Unlike `fetchList`, which emulates keyset pagination on top of the `list`
+ * action by injecting a `[field, '>', n]` filter, this helper drives the server
+ * `tail` action with its native `cursor: { field, value, order, limit }`
+ * parameter (see the v3 reference §6.2). The server itself adds `field > value`
+ * (asc) / `field < value` (desc) and sorts by `field`, so the cursor field
+ * MUST NOT appear in `filter` (the server rejects it with
+ * `INVALIDFILTEREXCEPTION`).
+ */
+declare class FetchTailV3 extends AbstractAction {
+    /**
+     * Streams every record of a `tail` method as chunks, advancing the keyset
+     * cursor between requests.
+     *
+     * @template T - The type of items in the returned arrays (default is `unknown`).
+     *
+     * @param {ActionFetchTailV3} options - parameters for executing the request.
+     *     - `method: string` - A REST API `tail` method name (for example: `main.eventlog.tail`).
+     *     - `params?: Omit<TypeCallParams, 'pagination' | 'order' | 'cursor'>` - Request parameters.
+     *         Use `filter` and `select` to control the selection. `pagination`, `order` and `cursor`
+     *         are managed by this helper and must not be passed. The cursor field must NOT be used in `filter`.
+     *     - `cursorField?: string` - The DTO field that drives the cursor. Must be monotonic and
+     *         preferably unique, and present in `select`. Default is `id`.
+     *     - `order?: 'ASC' | 'DESC'` - Cursor direction. Default is `ASC`. For `DESC` you MUST pass
+     *         `initialValue` (the server pages by `field < value`, so the default `0` returns nothing).
+     *     - `customKeyForResult?: string` - The key the response groups rows under. Default is `items`.
+     *     - `requestId?: string` - Unique request identifier for tracking.
+     *     - `limit?: number` - How many records to retrieve at a time. Default is `50`. Maximum is `1000`.
+     *     - `initialValue?: number | string` - Cursor start value for the first page. Default is `0`
+     *         (valid for ascending numeric fields); required for `DESC` and for non-numeric fields.
+     *
+     * @returns {AsyncGenerator<T[]>} An async generator that yields chunks of data as arrays of type `T`.
+     *
+     * @example
+     * const generator = b24.actions.v3.fetchTail.make<{ id: string }>({
+     *   method: 'main.eventlog.tail',
+     *   params: { select: ['id', 'auditType'] },
+     *   cursorField: 'id',
+     *   customKeyForResult: 'items'
+     * })
+     * for await (const chunk of generator) {
+     *   console.log(`Processing ${chunk.length} items`)
+     * }
+     */
+    make<T = unknown>(options: ActionFetchTailV3): AsyncGenerator<T[]>;
+}
+
+/**
+ * The six aggregate functions the v3 `aggregate` action accepts (reference §7).
+ * Anything else is rejected server-side with `UNKNOWNAGGREGATEFUNCTIONEXCEPTION`.
+ */
+type AggregateFunctionV3 = 'sum' | 'avg' | 'min' | 'max' | 'count' | 'countDistinct';
+/**
+ * Per-function field selection. Two forms (reference §7):
+ *   - list: `['amount', 'qty']` — default alias `<func>_<field>`;
+ *   - map:  `{ amount: 'totalAmount' }` — custom alias.
+ * Note: the response keys buckets by the **field name**, not the alias.
+ */
+type AggregateSelectV3 = Partial<Record<AggregateFunctionV3, string[] | Record<string, string>>>;
+/**
+ * Aggregate response buckets: `{ sum: { amount: 12345 }, count: { id: 87 } }`.
+ * Keyed by function, then by field name.
+ */
+type AggregateResultV3 = Partial<Record<AggregateFunctionV3, Record<string, number>>>;
+/** @experimental options for the v3 `aggregate` action — unverified live (see {@link AggregateV3}). */
+type ActionAggregateV3 = ActionOptions & {
+    method: string;
+    select: AggregateSelectV3;
+    params?: Pick<TypeCallParams, 'filter'>;
+    requestId?: string;
+};
+/**
+ * Runs the v3 `aggregate` action for modules that support it (reference §7).
+ * `restApi:v3`
+ *
+ * @experimental NOT verified against a live portal — no module on the SDK's
+ * reference test portal currently exposes an `*.aggregate` endpoint. The
+ * request/response shapes follow the published v3 reference and may change once
+ * verified live; pin to a version if you depend on the exact shape.
+ */
+declare class AggregateV3 extends AbstractAction {
+    /**
+     * @param {ActionAggregateV3} options
+     *     - `method: string` - an `*.aggregate` method name.
+     *     - `select: AggregateSelectV3` - per-function field selection (`sum`/`avg`/`min`/`max`/`count`/`countDistinct`).
+     *     - `params?: { filter }` - optional v3 filter (array-of-triples; use `FilterV3` to build it).
+     *     - `requestId?: string` - tracking id.
+     *
+     * @returns {Promise<Result<AggregateResultV3>>} buckets keyed by function then field name.
+     *
+     * @example
+     * const response = await b24.actions.v3.aggregate.make({
+     *   method: 'some.entity.aggregate',
+     *   select: { sum: { amount: 'totalAmount' }, count: ['id'] },
+     *   params: { filter: FilterV3.build(FilterV3.eq('status', 'NEW')) }
+     * })
+     * if (response.isSuccess) {
+     *   const total = response.getData()?.sum?.amount
+     * }
+     */
+    make(options: ActionAggregateV3): Promise<Result<AggregateResultV3>>;
+}
+
 type ActionBatchV3 = ActionOptions & {
     calls: BatchCommandsArrayUniversal | BatchCommandsObjectUniversal | BatchNamedCommandsUniversal;
     options?: IB24BatchOptions;
@@ -2191,6 +2370,9 @@ declare class ActionsManagerV3 {
     get call(): CallV3;
     get callList(): CallListV3;
     get fetchList(): FetchListV3;
+    get callTail(): CallTailV3;
+    get fetchTail(): FetchTailV3;
+    get aggregate(): AggregateV3;
     get batch(): BatchV3;
     get batchByChunk(): BatchByChunkV3;
 }
@@ -2699,10 +2881,10 @@ declare class AjaxResult<T = unknown> extends Result<Payload<T>> implements IRes
     isMore(): boolean;
     /**
      * @deprecated Will be removed in `2.0.0`. Tied to the `restApi:v2` envelope
-     *   field `total`, which `restApi:v3` does not return. For `restApi:v3` the
-     *   SDK exposes element counts via the `aggregate` action (`count` /
-     *   `countDistinct`); for `restApi:v2` use the list helpers, which iterate
-     *   without exposing `total`.
+     *   field `total`, which `restApi:v3` does not return. `restApi:v3` has no
+     *   element-count replacement yet — an `aggregate` action (`count` /
+     *   `countDistinct`) is planned but not exposed in the SDK; for `restApi:v2`
+     *   use the list helpers, which iterate without exposing `total`.
      *
      * @removed 2.0.0
      */
@@ -2763,12 +2945,16 @@ type TypeCallParams = {
         offset?: number;
     };
     /**
-     * Used only in Api:V3
+     * Used only in Api:V3 — keyset (`tail`) pagination cursor.
+     * `value` is the last seen value of `field`; `0` (or the type minimum) on the
+     * first page. `order` defaults to `asc`; `limit` shares the 50/1000 rule of
+     * `pagination`.
      */
     cursor?: {
         field: string;
-        value: number;
-        order: 'ASC' | 'DESC' | 'asc' | 'desc' | string;
+        value: number | string;
+        order?: 'ASC' | 'DESC' | 'asc' | 'desc' | string;
+        limit?: number;
     };
     [key: string]: any;
 };
@@ -4110,33 +4296,46 @@ declare class RestrictionManager {
 }
 
 /**
- * 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.
+ * Decides which REST API version a method is routed through.
+ *
+ * The SDK no longer maintains a hardcoded v3 method allowlist. A portal's set of
+ * v3 methods is large and version/edition-dependent (the authoritative list is
+ * the portal's own OpenAPI document, `rest.documentation.openapi`), so gating on
+ * a static list both lagged behind the server and blocked valid methods. The
+ * server is now the single source of truth: an unknown v3 method simply comes
+ * back as `METHODNOTFOUNDEXCEPTION`.
+ *
+ * Consequences:
+ * - `actions.v3.*` no longer pre-flight-rejects a method — it is sent to the v3
+ *   endpoint and the server validates it.
+ * - v3 is opt-in only via the explicit `actions.v3.*` surface; version
+ *   auto-detection therefore defaults to v2 (the universal endpoint).
  */
 declare class VersionManager {
-    #private;
-    constructor();
     static create(): VersionManager;
     /**
-     * List of supported API versions
-     * The highest version must be first
+     * List of supported API versions.
+     * The highest version must be first.
      */
     getAllApiVersions(): ApiVersion[];
-    isSupport(version: ApiVersion, method: string): boolean;
     /**
-     * Automatically obtain the API version
+     * Retained for backward compatibility. The SDK no longer keeps a v3 method
+     * allowlist, so support is not decided client-side any more — always returns
+     * `true`. Method existence is validated by the server.
      */
-    automaticallyObtainApiVersion(method: string): ApiVersion;
+    isSupport(_version: ApiVersion, _method: string): boolean;
     /**
-     * Automatically obtain the API version for Batch
-     *
-     * @todo test methods
-     *   `[['crm.item.get', { entityTypeId: 3, id: 1 }]]`
-     *   `[{ method: 'crm.item.get', params: { entityTypeId: 3, id: 1 } }]`
-     *   `{ cmd1: { method: 'crm.item.get', params: { entityTypeId: 3, id: 1 } }, cmd2: ['crm.item.get', { entityTypeId: 2, id: 2 }] }`
+     * Returns the API version to use when the caller did not specify one. With the
+     * allowlist removed there is no client-side signal that a method is a v3
+     * method, so this defaults to v2 (the universal endpoint). Use the explicit
+     * `actions.v3.*` surface to call a method on v3.
+     */
+    automaticallyObtainApiVersion(_method: string): ApiVersion;
+    /**
+     * Batch counterpart of {@link automaticallyObtainApiVersion}. Defaults to v2;
+     * call `actions.v3.batch.make` explicitly to run a batch on v3.
      */
-    automaticallyObtainApiVersionForBatch(calls: BatchCommandsArrayUniversal | BatchCommandsObjectUniversal | BatchNamedCommandsUniversal): ApiVersion;
+    automaticallyObtainApiVersionForBatch(_calls: BatchCommandsArrayUniversal | BatchCommandsObjectUniversal | BatchNamedCommandsUniversal): ApiVersion;
 }
 declare const versionManager: VersionManager;
 
@@ -4378,9 +4577,35 @@ declare abstract class AbstractHttp implements TypeHttp {
      */
     protected _createAjaxResultWithErrorFromResponse<T>(ajaxError: AjaxError, requestId: string, method: string, params: TypeCallParams): AjaxResult<T>;
     /**
-     * Makes the function name safe and adds JSON format
+     * Builds the request URL: the method path plus the SDK telemetry query params
+     * (`bx24_request_id` / `bx24_sdk_ver` / `bx24_sdk_type` — request tracing and
+     * SDK identification, not auth material).
+     *
+     * Carve-out for the legacy positional `task.*` methods (`task.commentitem.*`,
+     * `task.checklistitem.*`, `task.elapseditem.*`, …): these read the request
+     * **query string positionally**, so appending the telemetry params shifts
+     * `Param #0` and the server rejects the call —
+     * `WRONG_ARGUMENTS: Param #0 (taskId) ... expected integer, but given
+     * something else`. Verified live against a portal: the same
+     * `task.commentitem.getlist` / `task.checklistitem.getlist` call succeeds
+     * without the telemetry params and fails with them; modern `tasks.task.*`
+     * (named params) is unaffected. So telemetry is omitted for any method whose
+     * name contains `task.`.
+     *
+     * Shared by v2 and v3 (rather than per-transport): once the v3 method
+     * allowlist was dropped (#259) a positional `task.*` method can be routed via
+     * `actions.v3.*` too, so v3 needs the same suppression — keeping the rule in
+     * one place stops the two transports drifting apart again (#207).
+     *
+     * `includes('task.')` is a deliberate over-approximation: it also drops the
+     * (optional, telemetry-safe) params for modern `tasks.task.*` / `bizproc.task.*`.
+     * Narrowing to an anchored `^task\.` is possible but unverified across the
+     * whole task surface, so the broad, safe match is kept. Bitrix24 method names
+     * are lowercase by convention, so the case-sensitive match is sufficient.
+     *
+     * @see https://apidocs.bitrix24.com/settings/how-to-call-rest-api/data-encoding.html#order-of-parameters
      */
-    protected abstract _prepareMethod(requestId: string, method: string, baseUrl: string): string;
+    protected _prepareMethod(requestId: string, method: string, baseUrl: string): string;
     /**
      * Processes function parameters and adds authorization
      */
@@ -4423,10 +4648,6 @@ declare abstract class AbstractHttp implements TypeHttp {
 declare class HttpV2 extends AbstractHttp implements TypeHttp {
     constructor(authActions: AuthActions, options?: null | object, restrictionParams?: Partial<RestrictionParams>);
     batch<T = unknown>(calls: BatchCommandsArrayUniversal | BatchCommandsObjectUniversal | BatchNamedCommandsUniversal, options?: ICallBatchOptions): Promise<Result<ICallBatchResult<T>>>;
-    /**
-     * @inheritDoc
-     */
-    protected _prepareMethod(requestId: string, method: string, baseUrl: string): string;
 }
 
 /**
@@ -4440,10 +4661,6 @@ declare class HttpV2 extends AbstractHttp implements TypeHttp {
 declare class HttpV3 extends AbstractHttp implements TypeHttp {
     constructor(authActions: AuthActions, options?: null | object, restrictionParams?: Partial<RestrictionParams>);
     batch<T = unknown>(calls: BatchCommandsArrayUniversal | BatchCommandsObjectUniversal | BatchNamedCommandsUniversal, options?: ICallBatchOptions): Promise<Result<ICallBatchResult<T>>>;
-    /**
-     * @inheritDoc
-     */
-    protected _prepareMethod(requestId: string, method: string, baseUrl: string): string;
 }
 
 declare class FormatterNumbers {
@@ -4594,6 +4811,146 @@ declare const useFormatter: () => {
     formatterIban: FormatterIban;
 };
 
+/**
+ * The eight — and only eight — comparison operators the Bitrix24 REST API v3
+ * filter grammar accepts. Anything else is rejected server-side with
+ * `UNKNOWNFILTEROPERATOREXCEPTION`.
+ */
+type FilterV3Operator = '=' | '!=' | '>' | '>=' | '<' | '<=' | 'in' | 'between';
+/**
+ * A single condition in short-form: `[field, operator, value]`.
+ */
+type FilterV3Condition = [string, FilterV3Operator, unknown];
+/**
+ * A logical group of conditions / nested groups. `logic` defaults to `'and'`;
+ * `negative: true` wraps the whole group in a NOT.
+ */
+interface FilterV3Group {
+    logic?: 'and' | 'or';
+    negative?: boolean;
+    conditions: FilterV3Node[];
+}
+type FilterV3Node = FilterV3Condition | FilterV3Group;
+/**
+ * Typed builder for Bitrix24 REST API **v3** filters (the array-of-triples
+ * dialect with AND/OR/NOT groups — see the v3 reference §3). Produces exactly
+ * the structures the server accepts, so a bad operator or a malformed
+ * `in` / `between` value fails fast on the client instead of as a server 400.
+ *
+ * @example
+ * import { FilterV3 as F } from '@bitrix24/b24jssdk'
+ *
+ * // status = NEW  AND  (id in [1,2]  OR  id > 100)
+ * const filter = F.build(
+ *   F.eq('status', 'NEW'),
+ *   F.or(
+ *     F.in('id', [1, 2]),
+ *     F.gt('id', 100)
+ *   )
+ * )
+ * await b24.actions.v3.call.make({ method: 'tasks.task.list', params: { filter } })
+ */
+declare const FilterV3: Readonly<{
+    /** `field = value` */
+    eq(field: string, value: unknown): FilterV3Condition;
+    /** `field != value` */
+    ne(field: string, value: unknown): FilterV3Condition;
+    /** `field > value` */
+    gt(field: string, value: unknown): FilterV3Condition;
+    /** `field >= value` */
+    ge(field: string, value: unknown): FilterV3Condition;
+    /** `field < value` */
+    lt(field: string, value: unknown): FilterV3Condition;
+    /** `field <= value` */
+    le(field: string, value: unknown): FilterV3Condition;
+    /** `field in [values]` — `values` must be a non-empty array. */
+    in(field: string, values: unknown[]): FilterV3Condition;
+    /** `field between [from, to]` — inclusive range of exactly two defined operands. */
+    between(field: string, from: unknown, to: unknown): FilterV3Condition;
+    /** Combine nodes with AND (for nesting inside an OR; the top level is already AND). */
+    and(...conditions: FilterV3Node[]): FilterV3Group;
+    /** Combine nodes with OR. */
+    or(...conditions: FilterV3Node[]): FilterV3Group;
+    /**
+     * Negate a condition or group (wraps it in a NOT). A bare condition is wrapped
+     * in a single-item AND group so the `negative` flag has somewhere to live.
+     * Returns a fresh group (the input's `conditions` array is copied, not shared).
+     */
+    not(node: FilterV3Node): FilterV3Group;
+    /**
+     * Assemble the top-level filter array (its elements are AND-joined) ready to
+     * pass as `params.filter`. Falsy nodes are skipped, so you can inline
+     * conditionals: `F.build(F.eq('a', 1), flag && F.gt('b', 2))`.
+     *
+     * Always wrap with `build` (or an array) even for a single condition —
+     * `params.filter` must be an array, so pass `build(F.eq('a', 1))`, not the bare
+     * `F.eq('a', 1)`. Each surviving node is shape-checked, so a forgotten spread
+     * (`build([F.eq(...)])`) or a hand-rolled malformed triple fails fast here
+     * instead of as an opaque server error.
+     */
+    build(...nodes: Array<FilterV3Node | false | null | undefined>): FilterV3Node[];
+}>;
+
+/**
+ * A `$ref` substitution marker: pulls a single value from an earlier batch
+ * command's context by dotted path (reference §8).
+ */
+interface BatchRef {
+    $ref: string;
+}
+/**
+ * A `$refArray` substitution marker: collects one field across the `items[]` of
+ * an earlier list/tail command into an array (reference §8).
+ */
+interface BatchRefArray {
+    $refArray: string;
+}
+/**
+ * Helpers for the v3 batch `$ref` / `$refArray` substitution markers (reference
+ * §8). The **server** performs the substitution: these helpers just build the
+ * marker objects you drop into a later command's `params` (the SDK forwards
+ * `params` to the wire `query`), with a little client-side validation. Reference
+ * an earlier command by its `as` alias — or by its numeric index if you omit `as`.
+ * Only `item` (get) and `items` (list/tail) results land in context; `add` → id
+ * and `update` → bool results do not.
+ *
+ * **v3 only.** Substitution is a v3 batch feature. Dropped into a v2 batch
+ * (`actions.v2.batch.make`) the markers are NOT substituted — they are encoded
+ * as literal filter values and silently yield wrong/empty results.
+ *
+ * **Security:** the `path` selects from the batch's own response context, but do
+ * not build it from untrusted end-user input — a crafted path could read context
+ * the caller did not intend to expose to the next command.
+ *
+ * @example
+ * import { BatchRefV3 as R } from '@bitrix24/b24jssdk'
+ *
+ * const response = await b24.actions.v3.batch.make({
+ *   calls: [
+ *     { method: 'tasks.task.list', as: 'tasks', params: { select: ['id'] } },
+ *     {
+ *       method: 'tasks.task.comment.list',
+ *       // server substitutes the array of ids collected from the first command's items[]
+ *       params: { filter: [['taskId', 'in', R.refArray('tasks.id')]] }
+ *     }
+ *   ]
+ * })
+ */
+declare const BatchRefV3: Readonly<{
+    /**
+     * `{ $ref: path }` — substitute a single value from context, e.g.
+     * `ref('newTask.item.id')`. `add` → id / `update` → bool results are NOT in
+     * context (reference §8); only `item` (get) and `items` (list/tail) are.
+     */
+    ref(path: string): BatchRef;
+    /**
+     * `{ $refArray: path }` — collect one field across the `items[]` of an earlier
+     * list/tail command, e.g. `refArray('tasks.id')`. The path MUST contain a dot
+     * (`alias.field`); the server rejects a dot-less path with INVALIDSELECTEXCEPTION.
+     */
+    refArray(path: string): BatchRefArray;
+}>;
+
 /**
  * B24.Hook Manager.
  *
@@ -5683,8 +6040,12 @@ declare class PullClient implements ConnectorParent {
     private _watchUpdateTimeout;
     private _pingWaitTimeout;
     private _isManualDisconnect;
+    private _disposed;
     private _loggingEnabled;
     private _onPingTimeoutHandler;
+    private _onBeforeUnloadHandler;
+    private _onOfflineHandler;
+    private _onOnlineHandler;
     private _userStatusCallbacks;
     private _connectPromise;
     private _startingPromise;
@@ -5694,6 +6055,12 @@ declare class PullClient implements ConnectorParent {
     constructor(params: TypePullClientParams);
     setLogger(logger: LoggerInterface): void;
     getLogger(): LoggerInterface;
+    /**
+     * Terminal teardown: removes the window listeners, cancels every pending timer,
+     * persists the session for a quick re-init, and disconnects. Irreversible — a
+     * destroyed client schedules no further work and `start()` rejects with
+     * `PULL_DISPOSED`; create a new instance to reconnect.
+     */
     destroy(): void;
     private init;
     get connector(): null | TypeConnector;
@@ -5716,7 +6083,11 @@ declare class PullClient implements ConnectorParent {
      */
     private attachCommandHandler;
     /**
+     * Connects the client and begins receiving events.
+     *
      * @param config
+     * @throws Rejects with `{ ex: { error: 'PULL_DISPOSED' } }` when called after
+     *   `destroy()` — a destroyed client cannot be restarted; create a new instance.
      */
     start(config?: null | (TypePullClientConfig & {
         skipReconnectToLastSession?: boolean;
@@ -5727,6 +6098,7 @@ declare class PullClient implements ConnectorParent {
      */
     restart(disconnectCode?: number | CloseReasons, disconnectReason?: string): void;
     stop(disconnectCode?: number | CloseReasons, disconnectReason?: string): void;
+    private clearAllTimers;
     reconnect(disconnectCode: number | CloseReasons, disconnectReason: string, delay?: number): void;
     /**
      * @param lastMessageId
@@ -5970,6 +6342,7 @@ declare class PullClient implements ConnectorParent {
     private onOffline;
     private onOnline;
     private onBeforeUnload;
+    private persistSession;
     /**
      * @param status
      * @param delay
@@ -6038,5 +6411,5 @@ declare function initializeB24Frame(options?: {
     restrictionParams?: Partial<RestrictionParams>;
 }): Promise<B24Frame>;
 
-export { AbstractB24, AbstractLogger, AdaptiveDelayer, AjaxError, AjaxResult, ApiVersion, AppFrame, AuthHookManager, AuthManager, AuthOAuthManager, B24Frame, B24Hook, B24LangList, B24LocaleMap, B24OAuth, PullClient as B24PullClientManager, Browser, CatalogProductImageType, CatalogProductType, CatalogRoundingRuleType, CloseReasons, ConnectionType, ConsolaAdapter, ConsoleHandler, ConsoleV2Handler, DataType, DialogManager, EnumAppStatus, EnumBitrix24Edition, EnumBizprocBaseType, EnumBizprocDocumentType, EnumCrmEntityType, EnumCrmEntityTypeId, EnumCrmEntityTypeShort, Environment, HttpV2, HttpV3, JsonFormatter, LineFormatter, ListRpcError, LoadDataType, LogLevel, Logger, LoggerBrowser, LoggerFactory, LoggerType, LsKeys, MemoryHandler, MessageCommands, MessageManager, NullLogger, OperatingLimiter, OptionsManager$1 as OptionsManager, ParamsFactory, ParentManager, PlacementManager, ProductRowDiscountTypeId, PullStatus, RateLimiter, RefreshTokenError, RestrictionManager, Result, RpcMethod, SdkError, SenderType, ServerMode, SliderManager, StatusDescriptions, StreamHandler, SubscriptionType, SystemCommands, TelegramFormatter, TelegramHandler, Text$1 as Text, Type, TypeOption, TypeSpecificUrl, WinstonAdapter, convertBizprocDocumentTypeToCrmEntityTypeId, getDocumentId, getDocumentType, getDocumentTypeForFilter, getEnumCrmEntityTypeShort, getEnumValue, getEnvironment, initializeB24Frame, isArrayOfArray, memoryUsageProcessor, omit, pick, pidProcessor, useB24Helper, useFormatter, versionManager };
-export type { ActivityConfig, ActivityHandlerParams, ActivityOrRobotConfig, ActivityProperty, ActivityPropertyType, AdaptiveConfig, AjaxErrorParams, AjaxQuery, AnswerError, AuthActions, AuthData, B24FrameQueryParams, B24HookParams, B24OAuthParams, B24OAuthSecret, BatchCommandV3, BatchCommandsArrayUniversal, BatchCommandsObjectUniversal, BatchCommandsUniversal, BatchNamedCommandsUniversal, BatchPayload, BatchPayloadResult, BoolString, CallBatchResult, CallbackRefreshAuth, CatalogCatalog, CatalogExtra, CatalogLanguage, CatalogMeasure, CatalogPriceType, CatalogPriceTypeLang, CatalogProduct, CatalogProductImage, CatalogProductOffer, CatalogProductService, CatalogProductSku, CatalogRatio, CatalogRoundingRule, CatalogSection, CatalogStore, CatalogVat, CommandHandlerFunctionV1, CommandHandlerFunctionV2, CommandObject, CommandTuple, CommandUniversal, ConnectorCallbacks, ConnectorConfig, ConnectorParent, ConsolaAdapterOptions, ConsoleHandlerOptions, CrmItemDelivery, CrmItemPayment, CrmItemProductRow, Currency, CurrencyFormat, CustomRefreshAuth, EventHandlerParams, EventOnAppInstallHandlerParams, EventOnAppUnInstallHandlerParams, Fields, Formatter, GenderString, GetPayload, Handler, HandlerAuthParams, HandlerOptions, HandlerRefreshAuth, IB24BatchOptions, ICallBatchOptions, ICallBatchResult, ILimiter, IPlacementUF, IRequestIdGenerator, IResult, ISODate, JsonRpcRequest, ListPayload, LogLevelName, LogRecord, LoggerInterface, MemoryHandlerOptions, MessageInitData, MultiField, MultiFieldArray, NumberString, OperatingLimitConfig, Payload, PayloadOAuthToken, PayloadTime, PlacementViewMode, Processor, RateLimitConfig, RefreshAuthData, RestrictionManagerStats, RestrictionParams, RpcCommand, RpcCommandResult, RpcError, RpcRequest, SdkErrorDetails, SelectCRMParams, SelectCRMParamsEntityType, SelectCRMParamsValue, SelectedAccess, SelectedCRM, SelectedCRMEntity, SelectedUser, SendParams, SharedConfigCallbacks, SharedConfigParams, StatusClose, StorageManagerParams, StreamHandlerOptions, SuccessPayload, TelegramHandlerOptions, TextType, TypeApp, TypeB24, TypeB24Form, TypeCallParams, TypeChanel, TypeChannelManagerParams, TypeConnector, TypeDescriptionError, TypeDescriptionErrorV3, TypeEnumAppStatus, TypeHttp, TypeJsonRpcConfig, TypeLicense, TypePayment, TypePublicIdDescriptor, TypePullClientConfig, TypePullClientEmitConfig, TypePullClientMessageBatch, TypePullClientMessageBody, TypePullClientParams, TypePullClientSession, TypePullMessage, TypeRpcResponseAwaiters, TypeSessionEvent, TypeStorageManager, TypeSubscriptionCommandHandler, TypeSubscriptionOptions, TypeUser, UserBasic, UserBrief, UserFieldType, UserStatusCallback, WinstonAdapterOptions };
+export { AbstractB24, AbstractLogger, AdaptiveDelayer, AjaxError, AjaxResult, ApiVersion, AppFrame, AuthHookManager, AuthManager, AuthOAuthManager, B24Frame, B24Hook, B24LangList, B24LocaleMap, B24OAuth, PullClient as B24PullClientManager, BatchRefV3, Browser, CatalogProductImageType, CatalogProductType, CatalogRoundingRuleType, CloseReasons, ConnectionType, ConsolaAdapter, ConsoleHandler, ConsoleV2Handler, DataType, DialogManager, EnumAppStatus, EnumBitrix24Edition, EnumBizprocBaseType, EnumBizprocDocumentType, EnumCrmEntityType, EnumCrmEntityTypeId, EnumCrmEntityTypeShort, Environment, FilterV3, HttpV2, HttpV3, JsonFormatter, LineFormatter, ListRpcError, LoadDataType, LogLevel, Logger, LoggerBrowser, LoggerFactory, LoggerType, LsKeys, MemoryHandler, MessageCommands, MessageManager, NullLogger, OperatingLimiter, OptionsManager$1 as OptionsManager, ParamsFactory, ParentManager, PlacementManager, ProductRowDiscountTypeId, PullStatus, RateLimiter, RefreshTokenError, RestrictionManager, Result, RpcMethod, SdkError, SenderType, ServerMode, SliderManager, StatusDescriptions, StreamHandler, SubscriptionType, SystemCommands, TelegramFormatter, TelegramHandler, Text$1 as Text, Type, TypeOption, TypeSpecificUrl, WinstonAdapter, convertBizprocDocumentTypeToCrmEntityTypeId, getDocumentId, getDocumentType, getDocumentTypeForFilter, getEnumCrmEntityTypeShort, getEnumValue, getEnvironment, initializeB24Frame, isArrayOfArray, memoryUsageProcessor, omit, pick, pidProcessor, useB24Helper, useFormatter, versionManager };
+export type { ActivityConfig, ActivityHandlerParams, ActivityOrRobotConfig, ActivityProperty, ActivityPropertyType, AdaptiveConfig, AjaxErrorParams, AjaxQuery, AnswerError, AuthActions, AuthData, B24FrameQueryParams, B24HookParams, B24OAuthParams, B24OAuthSecret, BatchCommandV3, BatchCommandsArrayUniversal, BatchCommandsObjectUniversal, BatchCommandsUniversal, BatchNamedCommandsUniversal, BatchPayload, BatchPayloadResult, BatchRef, BatchRefArray, BoolString, CallBatchResult, CallbackRefreshAuth, CatalogCatalog, CatalogExtra, CatalogLanguage, CatalogMeasure, CatalogPriceType, CatalogPriceTypeLang, CatalogProduct, CatalogProductImage, CatalogProductOffer, CatalogProductService, CatalogProductSku, CatalogRatio, CatalogRoundingRule, CatalogSection, CatalogStore, CatalogVat, CommandHandlerFunctionV1, CommandHandlerFunctionV2, CommandObject, CommandTuple, CommandUniversal, ConnectorCallbacks, ConnectorConfig, ConnectorParent, ConsolaAdapterOptions, ConsoleHandlerOptions, CrmItemDelivery, CrmItemPayment, CrmItemProductRow, Currency, CurrencyFormat, CustomRefreshAuth, EventHandlerParams, EventOnAppInstallHandlerParams, EventOnAppUnInstallHandlerParams, Fields, FilterV3Condition, FilterV3Group, FilterV3Node, FilterV3Operator, Formatter, GenderString, GetPayload, Handler, HandlerAuthParams, HandlerOptions, HandlerRefreshAuth, IB24BatchOptions, ICallBatchOptions, ICallBatchResult, ILimiter, IPlacementUF, IRequestIdGenerator, IResult, ISODate, JsonRpcRequest, ListPayload, LogLevelName, LogRecord, LoggerInterface, MemoryHandlerOptions, MessageInitData, MultiField, MultiFieldArray, NumberString, OperatingLimitConfig, Payload, PayloadOAuthToken, PayloadTime, PlacementViewMode, Processor, RateLimitConfig, RefreshAuthData, RestrictionManagerStats, RestrictionParams, RpcCommand, RpcCommandResult, RpcError, RpcRequest, SdkErrorDetails, SelectCRMParams, SelectCRMParamsEntityType, SelectCRMParamsValue, SelectedAccess, SelectedCRM, SelectedCRMEntity, SelectedUser, SendParams, SharedConfigCallbacks, SharedConfigParams, StatusClose, StorageManagerParams, StreamHandlerOptions, SuccessPayload, TelegramHandlerOptions, TextType, TypeApp, TypeB24, TypeB24Form, TypeCallParams, TypeChanel, TypeChannelManagerParams, TypeConnector, TypeDescriptionError, TypeDescriptionErrorV3, TypeEnumAppStatus, TypeHttp, TypeJsonRpcConfig, TypeLicense, TypePayment, TypePublicIdDescriptor, TypePullClientConfig, TypePullClientEmitConfig, TypePullClientMessageBatch, TypePullClientMessageBody, TypePullClientParams, TypePullClientSession, TypePullMessage, TypeRpcResponseAwaiters, TypeSessionEvent, TypeStorageManager, TypeSubscriptionCommandHandler, TypeSubscriptionOptions, TypeUser, UserBasic, UserBrief, UserFieldType, UserStatusCallback, WinstonAdapterOptions };