bx-rest 1.6.0 → 1.7.0

package/CHANGELOG.md

@@ -7,6 +7,75 @@
 История до версии 1.0.0 здесь не восстанавливалась — смотрите `git log` для
 более ранних изменений.
 
+## [1.7.0] - 2026-11-11
+
+### Added
+
+- `.resAll()` у 59 списочных методов, которые листаются через `start`:
+  `catalog.*.list` (25 методов), `sale.*.list` (20),
+  `documentgenerator.{document,numerator,role,template}.list`,
+  `booking.v1.resource.list`, `booking.v1.resourcetype.list`,
+  `crm.activity.list`, `crm.item.productrow.list`, `crm.orderentity.list`,
+  `crm.stagehistory.list`, `crm.timeline.bindings.list`,
+  `crm.requisite.link.list`, `crm.deal.recurring.list` и `userfieldtype.list`.
+  Список сверен с документацией Bitrix24. `.res()` у этих методов не
+  изменился. Если `result` метода — объект со списком под ключом, как у
+  `catalog.product.list` (`{ products: [...] }`), `.resAll()` отдаёт такой же
+  объект, где под ключом собраны записи всех страниц. Подробнее — в разделе
+  README «Режимы результата».
+- `Navvy.pagNavKeyed()` и класс `NavvyPagNavKeyed` — пагинация для своих
+  методов, у которых `result` — объект со списком под ключом.
+- `pull.application.event.add()` — событие в канал приложения, и
+  `pull.application.push.add()` — push-уведомление в мобильное приложение.
+  Типы параметров: `iBXRestParamPullApplicationEventAdd`,
+  `iBXRestParamPullApplicationPushAdd`.
+- `pull.application.config.get()` и `pull.config.get()` принимают
+  необязательные параметры `CACHE` и `REOPEN` (тип `iBXRestParamPullConfigGet`).
+  В типах ответа появились поля `exp`, `clientId` и `jwt`. Подробнее — в
+  разделе README «Push & Pull».
+- Настройка `logRequests` — журнал запросов: функция получает запись о каждом
+  HTTP-запросе (метод, адрес, длительность, статус, код ошибки Bitrix). Тип
+  записи `BXRestRequestLogEntry`. Адрес в записи не маскируется. Подробнее — в
+  разделе README «Журнал запросов».
+- Настройка `transport: 'fetch'` — отправка запросов через глобальный `fetch`
+  вместо axios. Ответ не 2xx приходит ошибкой `BXRestHttpError` с полем
+  `response: { status, data }`. Подробнее — в разделе README «Транспорт fetch».
+- `new Navvy(settings)` и `new BXRestRequest(settings)` — свои настройки, как у
+  `new BXRestNavvy(settings)`. Без аргумента оба работают с глобальными
+  `BXRestSettings`, как раньше.
+
+### Changed
+
+- Тип результата `.res()` у `crm.item.productrow.list`, `crm.orderentity.list`
+  и `crm.stagehistory.list` исправлен на объект: `{ productRows }`,
+  `{ orderEntity }` и `{ items }`. Раньше тип обещал массив, хотя портал
+  отдаёт объект, и само значение не изменилось. Код, который работал с
+  результатом как с массивом, перестанет компилироваться: во время выполнения
+  он и раньше не работал.
+- Тип результата `userfieldtype.list().res()` исправлен на массив: портал
+  отдаёт массив.
+- Типы параметров `crm.timeline.bindings.list` и `crm.requisite.link.list`
+  принимают `start`.
+- В сырых типах ответа `iBXRestPullConfigGetHttp` и
+  `iBXRestPullApplicationConfigGetHttp` поле `publicChannels` может быть
+  `false`: так портал отвечает при версии сервера Push & Pull ниже 4. После
+  маппера `.res()` такое значение становится пустым объектом.
+
+### Fixed
+
+- `task.elapsedItem.operation.getListByIDTask()` загружает все записи каждой
+  задачи. Раньше метод запрашивал одну страницу с `nPageSize: 99999`, а по
+  документации портал отдаёт не больше 50 записей на страницу, поэтому у
+  задачи с большим числом записей часть могла пропасть без ошибки. Теперь
+  первые страницы всех задач уходят одним batch, как раньше, а остальные
+  страницы догружаются только для задач, где записей больше 50.
+- Публичное поле `pull.channel.public.url.get` указывало на `log.blogpost.add`.
+  Теперь там `pull.channel.public.get`, сам запрос и раньше шёл на этот метод.
+- Мапперы `pull.application.config.get()` и `pull.config.get()` больше не
+  падают с `TypeError`, если в ответе нет `publicChannels` или одного из
+  каналов, и с `Wrong date format`, если в ответе `pull.config.get` нет
+  `serverTime`.
+
 ## [1.6.0] - 2026-11-10
 
 ### Added

package/README.en.md

@@ -26,6 +26,8 @@ Also known as: Bitrix24 REST client, BX24 REST SDK, Bitrix24 API client, Bitrix
   - [Recipe: through a backend proxy](#recipe-through-a-backend-proxy)
 - [Several portals](#several-portals)
 - [Retry, timeout and request queue](#retry-timeout-and-request-queue)
+  - [Request log](#request-log)
+  - [The fetch transport](#the-fetch-transport)
   - [Your own middleware](#your-own-middleware)
 - [Working in an iframe without BX24.js](#working-in-an-iframe-without-bx24js)
 - [Usage in Angular](#usage-in-angular)
@@ -39,6 +41,7 @@ Also known as: Bitrix24 REST client, BX24 REST SDK, Bitrix24 API client, Bitrix
   - [A paginated custom method with `pagNav()`](#a-paginated-custom-method-with-pagnav)
 - [Specific methods](#specific-methods)
   - [`tasks.task.list`](#taskstasklist)
+  - [Push & Pull](#push--pull)
 - [Date parsing](#date-parsing)
 - [Future features](#future-features)
 - [License](#license)
@@ -101,7 +104,7 @@ REST calls are lazy: the request starts when the returned `Observable` is subscr
 | Method | Result |
 | --- | --- |
 | `.res(options?)` | Unwraps the Bitrix response and applies the configured mapper. For paginated methods it returns the current page. |
-| `.resAll()` | Loads and combines every page. Available on paginated Navvy helpers. |
+| `.resAll()` | Loads and combines every page. Available on paged list methods, see below. |
 | `.resVanilla()` | Returns the raw Bitrix response, including fields such as `result`, `total` and `next`. |
 | `.mapForVanilla()` | Keeps the raw response envelope but applies the mapper to its `result`. |
 
@@ -111,6 +114,13 @@ REST calls are lazy: the request starts when the returned `Observable` is subscr
 | --- | --- | --- |
 | `throwOnApiError` | `false` | When `true`, a Bitrix-level API error makes the returned `Observable` error out with a `BXRestApiError` instead of resolving with `undefined`. See [Error handling](#error-handling). |
 
+`.resAll()` exists on list methods that page through `start`. It requests the first page itself and the rest in packs through `batch`. The result has the same shape as `.res()`:
+
+- if the method returns an array (`crm.deal.list`, `crm.activity.list`), `.resAll()` returns an array of all records;
+- if `result` is an object with the list under a key, as with `catalog.product.list` (`{ products: [...] }`) or `sale.order.list` (`{ orders: [...] }`), `.resAll()` returns the same object with the records of all pages under that key.
+
+Methods that return the whole list in one response or page in another way (`OFFSET`/`LIMIT`, a page number, the REST v3 `pagination` object) have no `.resAll()`. They are listed with reasons in [list-pagination.spec.ts](https://github.com/Aricatofuka/bx-rest/blob/main/projects/bx-rest/src/rest/list-pagination.spec.ts).
+
 ## Authentication and OAuth2
 
 `auth.source` controls where credentials are read from. `auth.key` controls the request parameter name, except for the special `OAuth2` cookie-credentials mode.
@@ -454,7 +464,7 @@ const deals = await firstValueFrom(
 - **Another portal or other headers** — create a new client, it takes a fraction of a millisecond.
 - **Authorization refresh** is per client: a client's `auth.refresh` is called only for its own requests.
 - **`auth.source: 'cookies'` and `'localStorage'`** read the shared browser storage, so two clients with the same key get the same token. For several portals, set `source` to a function.
-- **Objects created directly** — `new Navvy()`, `new BXRestRequest()`, `new SessionKeyServices()` — use the global `BXRestSettings`. Only `BXRestNavvy` and everything created through it get the client's own settings.
+- **Objects created directly** — `new Navvy()` and `new BXRestRequest()` — use the global `BXRestSettings` when called without an argument. They also accept their own settings: `new Navvy(settings)`, `new BXRestRequest(settings)`. Such an object has its own `throttle` queue and authorization refresh, even if a `BXRestNavvy` client has the same settings. `new SessionKeyServices()` always uses the global settings.
 
 ## Retry, timeout and request queue
 
@@ -476,13 +486,49 @@ BXRestSettings.update({
 
 An object may set only some fields: `retryOnQueryLimit: { attempts: 5 }` keeps `delay: 1000`.
 
-- **Order:** retry, queue, timeout, [your own middleware](#your-own-middleware), axios. Every retry attempt queues again and gets its own `timeout`. Waiting in the queue and pauses before a retry do not count towards `timeout`.
+- **Order:** retry, queue, timeout, [log](#request-log), [your own middleware](#your-own-middleware), [transport](#the-fetch-transport). Every retry attempt queues again and gets its own `timeout`. Waiting in the queue and pauses before a retry do not count towards `timeout`.
 - **The queue** belongs to each `new BXRestNavvy(settings)` client and is shared by everything that uses the global `BXRestSettings`. Every request goes through it, including every batch request of `.resAll()`.
 - **`throttle` is stricter than the portal.** Bitrix24 lets short bursts above the limit through, while `throttle` spreads all requests evenly. If short bursts of requests need to be fast, `retryOnQueryLimit` alone is enough.
 - **Unsubscribing** stops both the wait in the queue and the pause before a retry: such a request is never sent.
 - **Settings are read at subscribe time**, like the rest.
 - **An invalid value** — for example `throttle: { perSecond: 0 }` or a negative `timeout` — fails the request with a `TypeError` that describes it; nothing is sent to the portal.
 
+### Request log
+
+`logRequests` is a function that receives an entry for every HTTP request once it finishes. It is set the same way, globally or per client:
+
+```typescript
+BXRestSettings.update({
+  logRequests: entry => console.debug(entry.method, entry.url, `${entry.duration} ms`, entry.failed ? entry.error : 'ok'),
+})
+```
+
+| Field | What it holds |
+| --- | --- |
+| `method` | `'GET'` or `'POST'`. |
+| `url` | The full request address. |
+| `duration` | Time from sending to the response or error, ms. |
+| `failed` | `true` if the request failed: a non-2xx response, a network failure, a timeout or a cancel. |
+| `status` | The HTTP status of a failed response. The transport does not report the status of a successful one. |
+| `error` | The Bitrix error code from the response body, such as `QUERY_LIMIT_EXCEEDED`, including one from a 2xx response. If the portal sent no code, the error message. |
+
+- **One entry per HTTP request:** every `retryOnQueryLimit` attempt and every batch request of `.resAll()` is its own entry. Waiting in the `throttle` queue does not count towards `duration`.
+- **The address is as is.** The request body is not in the entry, but a webhook keeps its secret in the address, and a GET request keeps the token there. If the log goes to a third-party system, remove them yourself.
+- **An exception from the function** does not affect the request.
+
+### The fetch transport
+
+By default axios sends the requests. With `transport: 'fetch'` the global `fetch` of the browser or Node 18+ sends them:
+
+```typescript
+const portal = new BXRestNavvy({ ...settings, transport: 'fetch' })
+```
+
+The result is the same as with axios; only transport errors differ:
+
+- on a non-2xx response `.resVanilla()` fails with a `BXRestHttpError` that has `response: { status, data }`, like `AxiosError`; in `.res()` it is in the `cause` of `BXRestApiError`;
+- a network failure comes as the error of `fetch` itself (usually a `TypeError`), without the `request` field axios has.
+
 ### Your own middleware
 
 A middleware is a function every request passes through before it is sent: logging, metrics, changing headers, your own transport instead of axios. Set it in `middleware`, globally or per client in the same way:
@@ -503,7 +549,7 @@ BXRestSettings.update({ middleware: [logDuration] })
 ```
 
 - **`config`** is the request: `method` (`'GET'` or `'POST'`), `url` (with the parameters for GET), `data` (the POST body), `headers`, `withCredentials`, `signal`. `next(config)` sends it on and returns the response body.
-- **Order:** the first in the list is the outermost one: it sees the request first and the response last. All your middleware run after `retryOnQueryLimit`, `throttle` and `timeout`, so they see every retry attempt. The retry after `auth.refresh` wraps all the steps: on an authorization refresh the request passes through them again.
+- **Order:** the first in the list is the outermost one: it sees the request first and the response last. All your middleware run after `retryOnQueryLimit`, `throttle`, `timeout` and `logRequests`, so they see every retry attempt. The retry after `auth.refresh` wraps all the steps: on an authorization refresh the request passes through them again.
 - **To change the request**, pass a new object on: `next({ ...config, headers: { ...config.headers, 'X-Trace': id } })`.
 - **Your own transport** is a middleware that does not call `next`: it sends the request itself and returns the response body. For a non-2xx response it must reject with an error that has a `response: { status, data }` field, as axios does. The library uses that field to recognize Bitrix errors (`BXRestApiError`) and authorization errors (`auth.refresh`).
 - **Pass `config.signal`** to your transport: it aborts the request on unsubscribe and on `timeout`.
@@ -888,6 +934,18 @@ export class BXRestNavvyCustomApiBlogList {
 
 The returned helper additionally supports `.resAll()` for loading and combining all pages.
 
+If the method's `result` is an object with the list under a key, such as `{ items: [...] }`, use `pagNavKeyed()`: its third argument is the list key. `.res()` returns the object as is, `.resAll()` the same object with the records of all pages under the key:
+
+```typescript
+type BlogItems = { items?: iBXRestCustomBlogGetHttp[] }
+
+this.navvy.pagNavKeyed<BlogItems, BlogItems, iBXRestCustomParamBlogList>(
+  ['blog', 'item', PNM.$list],
+  param,
+  'items'
+)
+```
+
 ## Specific methods
 
 ### `tasks.task.list`
@@ -939,6 +997,40 @@ const tasks$ = bxRest.tasks.task.list<
 }).res()
 ```
 
+### Push & Pull
+
+The `pull` section returns the settings for connecting to the Push & Pull server and sends application events. The library has no websocket client: connect with your own client following the [protocol description](https://apidocs.bitrix24.com/settings/interactivity/custom-push-and-pull-client.html) or with `PullClient` from [b24jssdk](https://github.com/bitrix24/b24jssdk).
+
+```typescript
+import { firstValueFrom } from 'rxjs'
+import { BXRestNavvy } from 'bx-rest'
+
+const bxRest = new BXRestNavvy()
+
+// Server addresses and channels for the client to connect
+const config = await firstValueFrom(bxRest.pull.application.config.get().res())
+console.log(config?.server.websocket_secure, config?.channels.private.id, config?.exp)
+
+// An event in the shared channel of the application: every subscribed client gets it
+await firstValueFrom(bxRest.pull.application.event.add({
+  COMMAND: 'grid:update',
+  PARAMS: { grid_id: 15 },
+}).res())
+```
+
+| Method | What it does |
+| --- | --- |
+| `pull.application.config.get(param?)` | Connection settings for the application: server addresses, the `shared` and `private` channels, public channels, `exp`, and with the right server version `clientId` or `jwt`. Channel dates are `Date`. |
+| `pull.application.event.add(param)` | An event in the application channel: without `USER_ID` in the shared `shared` channel, with it in the users' personal channels. |
+| `pull.application.push.add(param)` | A push notification to the Bitrix24 mobile app. For portal administrators only. |
+| `pull.config.get(param?)` | Connection settings for a user. The method is not in the Bitrix24 documentation, so it is marked `@experimental`. |
+| `pull.channel.public.get()` | A public Push & Pull channel. |
+
+- **`pull.application.*` methods** work only in an application context, with its OAuth token. Through a webhook the portal answers `WRONG_AUTH_TYPE`.
+- **`true` in the response** of `event.add` and `push.add` means "accepted for sending", not "delivered".
+- **`USER_ID` for a non-administrator.** They can send an event only to themselves, and `USER_ID` must then be a string: `'577'`. The portal rejects a number or an array with `USER_ID_ACCESS_ERROR`.
+- **The settings are personal:** the `private` channel belongs to the user whose token makes the request. Request them again when `exp` or the channels' `end` expires.
+
 ## Date parsing
 
 Some Bitrix24 REST fields (notably `calendar.section.get`, `calendar.event.get` and `crm.calllist.*`) return dates as plain strings formatted according to the portal's own date/time settings (Settings → date and time format) — not a fixed ISO format. Because that format is a per-portal setting, `bx-rest` can't know it in advance, so `BXBaseServices.toDate()` (used internally by these mappers) resolves an ambiguous string in three steps, in order:

package/README.md

@@ -26,6 +26,8 @@
   - [Рецепт: через бэкенд-прокси](#рецепт-через-бэкенд-прокси)
 - [Несколько порталов](#несколько-порталов)
 - [Повтор, таймаут и очередь запросов](#повтор-таймаут-и-очередь-запросов)
+  - [Журнал запросов](#журнал-запросов)
+  - [Транспорт fetch](#транспорт-fetch)
   - [Свои middleware](#свои-middleware)
 - [Работа в iframe без BX24.js](#работа-в-iframe-без-bx24js)
 - [Использование в Angular](#использование-в-angular)
@@ -39,6 +41,7 @@
   - [Пагинированный кастомный метод с `pagNav()`](#пагинированный-кастомный-метод-с-pagnav)
 - [Специфичные методы](#специфичные-методы)
   - [`tasks.task.list`](#taskstasklist)
+  - [Push & Pull](#push--pull)
 - [Парсинг дат](#парсинг-дат)
 - [Планы на будущее](#планы-на-будущее)
 - [Лицензия](#лицензия)
@@ -111,7 +114,7 @@ REST-вызовы ленивые: запрос начинается, когда
 | Метод | Результат |
 | --- | --- |
 | `.res(options?)` | Разворачивает ответ Bitrix и применяет настроенный маппер. Для пагинированных методов возвращает текущую страницу. |
-| `.resAll()` | Загружает и объединяет все страницы. Доступен для пагинированных Navvy-хелперов. |
+| `.resAll()` | Загружает и объединяет все страницы. Доступен у списочных методов с постраничной навигацией, подробнее ниже. |
 | `.resVanilla()` | Возвращает сырой ответ Bitrix, включая такие поля, как `result`, `total` и `next`. |
 | `.mapForVanilla()` | Сохраняет исходную обёртку ответа, но применяет маппер к её `result`. |
 
@@ -121,6 +124,13 @@ REST-вызовы ленивые: запрос начинается, когда
 | --- | --- | --- |
 | `throwOnApiError` | `false` | При `true` ошибка API-уровня Bitrix приводит к тому, что возвращённый `Observable` завершается ошибкой `BXRestApiError` вместо резолва в `undefined`. См. [Обработка ошибок](#обработка-ошибок). |
 
+`.resAll()` есть у списочных методов, которые листаются через `start`. Первую страницу он запрашивает сам, остальные — пакетами через `batch`. Результат такой же формы, как у `.res()`:
+
+- если метод отдаёт массив (`crm.deal.list`, `crm.activity.list`), `.resAll()` отдаёт массив всех записей;
+- если `result` — объект со списком под ключом, как у `catalog.product.list` (`{ products: [...] }`) или `sale.order.list` (`{ orders: [...] }`), `.resAll()` отдаёт такой же объект, где под ключом собраны записи всех страниц.
+
+У методов, которые отдают весь список одним ответом или листаются иначе (`OFFSET`/`LIMIT`, номер страницы, объект `pagination` в REST v3), `.resAll()` нет. Они перечислены с причинами в [list-pagination.spec.ts](https://github.com/Aricatofuka/bx-rest/blob/main/projects/bx-rest/src/rest/list-pagination.spec.ts).
+
 ## Аутентификация и OAuth2
 
 `auth.source` определяет, откуда читаются учётные данные. `auth.key` определяет имя параметра запроса, за исключением специального режима учётных данных через куки `OAuth2`.
@@ -464,7 +474,7 @@ const deals = await firstValueFrom(
 - **Другой портал или другие заголовки** — создайте новый клиент, это занимает доли миллисекунды.
 - **Продление авторизации** у каждого клиента своё: `auth.refresh` клиента вызывается только для его запросов.
 - **`auth.source: 'cookies'` и `'localStorage'`** читают общее хранилище браузера, поэтому два клиента с одним ключом получат один и тот же токен. Для нескольких порталов задавайте `source` функцией.
-- **Объекты, созданные напрямую**, — `new Navvy()`, `new BXRestRequest()`, `new SessionKeyServices()` — работают с глобальными `BXRestSettings`. Свои настройки получает только `BXRestNavvy` и всё, что создаётся через него.
+- **Объекты, созданные напрямую**, — `new Navvy()` и `new BXRestRequest()` — без аргумента работают с глобальными `BXRestSettings`. Им тоже можно передать свои настройки: `new Navvy(settings)`, `new BXRestRequest(settings)`. Очередь `throttle` и продление авторизации у такого объекта свои, даже если у клиента `BXRestNavvy` те же настройки. `new SessionKeyServices()` всегда работает с глобальными.
 
 ## Повтор, таймаут и очередь запросов
 
@@ -486,13 +496,49 @@ BXRestSettings.update({
 
 В объекте можно задать только часть полей: `retryOnQueryLimit: { attempts: 5 }` оставит `delay: 1000`.
 
-- **Порядок:** повтор, очередь, таймаут, [свои middleware](#свои-middleware), axios. Каждая попытка повтора заново встаёт в очередь и получает своё время `timeout`. Ожидание в очереди и паузы перед повтором в `timeout` не входят.
+- **Порядок:** повтор, очередь, таймаут, [журнал](#журнал-запросов), [свои middleware](#свои-middleware), [транспорт](#транспорт-fetch). Каждая попытка повтора заново встаёт в очередь и получает своё время `timeout`. Ожидание в очереди и паузы перед повтором в `timeout` не входят.
 - **Очередь** своя у каждого клиента `new BXRestNavvy(settings)` и общая у всех, кто работает с глобальными `BXRestSettings`. Через неё проходит каждый запрос, в том числе каждый batch-запрос `.resAll()`.
 - **`throttle` строже портала.** Bitrix24 пропускает короткие всплески сверх лимита, а `throttle` равномерно распределяет все запросы. Если важна скорость коротких пачек запросов, хватит одного `retryOnQueryLimit`.
 - **Отписка** прерывает и ожидание в очереди, и паузу перед повтором: такой запрос уже не уйдёт.
 - **Настройки читаются в момент подписки**, как и остальные.
 - **Неверное значение** — например, `throttle: { perSecond: 0 }` или отрицательный `timeout` — завершает запрос ошибкой `TypeError` с описанием, на портал ничего не уходит.
 
+### Журнал запросов
+
+`logRequests` — функция, которая получает запись о каждом HTTP-запросе после его завершения. Задаётся так же, глобально или у клиента:
+
+```typescript
+BXRestSettings.update({
+  logRequests: entry => console.debug(entry.method, entry.url, `${entry.duration} ms`, entry.failed ? entry.error : 'ok'),
+})
+```
+
+| Поле | Что в нём |
+| --- | --- |
+| `method` | `'GET'` или `'POST'`. |
+| `url` | Полный адрес запроса. |
+| `duration` | Время от отправки до ответа или ошибки, мс. |
+| `failed` | `true`, если запрос завершился ошибкой: ответ не 2xx, сбой сети, таймаут или отмена. |
+| `status` | HTTP-статус ответа с ошибкой. У успешного ответа транспорт статус не сообщает. |
+| `error` | Код ошибки Bitrix из тела ответа, например `QUERY_LIMIT_EXCEEDED`, в том числе из ответа 2xx. Если портал кода не прислал — текст ошибки. |
+
+- **Запись на каждый HTTP-запрос:** каждая попытка `retryOnQueryLimit` и каждый batch-запрос `.resAll()` — отдельная запись. Ожидание в очереди `throttle` в `duration` не входит.
+- **Адрес — как есть.** Тела запроса в записи нет, но у вебхука секрет лежит в адресе, а у GET-запроса в адресе токен. Если журнал уходит в стороннюю систему, уберите их сами.
+- **Исключение из функции** на запрос не влияет.
+
+### Транспорт fetch
+
+По умолчанию запросы отправляет axios. С `transport: 'fetch'` их отправляет глобальный `fetch` браузера или Node 18+:
+
+```typescript
+const portal = new BXRestNavvy({ ...settings, transport: 'fetch' })
+```
+
+Результат тот же, что с axios, разница только в ошибках транспорта:
+
+- на ответ не 2xx `.resVanilla()` завершается ошибкой `BXRestHttpError` с полем `response: { status, data }`, как у `AxiosError`; в `.res()` она лежит в `cause` у `BXRestApiError`;
+- сбой сети приходит ошибкой самого `fetch` (обычно `TypeError`), поля `request`, как у axios, у неё нет.
+
 ### Свои middleware
 
 Middleware — функция, через которую проходит каждый запрос перед отправкой: логирование, метрики, подмена заголовков, свой транспорт вместо axios. Задаётся в `middleware` — так же глобально или у клиента:
@@ -513,7 +559,7 @@ BXRestSettings.update({ middleware: [logDuration] })
 ```
 
 - **`config`** — запрос: `method` (`'GET'` или `'POST'`), `url` (у GET вместе с параметрами), `data` (тело POST), `headers`, `withCredentials`, `signal`. `next(config)` отправляет его дальше и возвращает тело ответа.
-- **Порядок:** первый в списке — внешний, он первым видит запрос и последним — ответ. Все свои middleware идут после `retryOnQueryLimit`, `throttle` и `timeout`, поэтому видят каждую попытку повтора. Повтор после `auth.refresh` идёт снаружи всех шагов: при продлении авторизации запрос пройдёт через них ещё раз.
+- **Порядок:** первый в списке — внешний, он первым видит запрос и последним — ответ. Все свои middleware идут после `retryOnQueryLimit`, `throttle`, `timeout` и `logRequests`, поэтому видят каждую попытку повтора. Повтор после `auth.refresh` идёт снаружи всех шагов: при продлении авторизации запрос пройдёт через них ещё раз.
 - **Изменить запрос** — передать дальше новый объект: `next({ ...config, headers: { ...config.headers, 'X-Trace': id } })`.
 - **Свой транспорт** — middleware, который не зовёт `next`: он сам отправляет запрос и возвращает тело ответа. На ответ не 2xx он должен отклонить промис ошибкой с полем `response: { status, data }`, как это делает axios. По этому полю библиотека узнаёт ошибки Bitrix (`BXRestApiError`) и ошибки авторизации (`auth.refresh`).
 - **`config.signal`** передавайте в свой транспорт: по нему запрос отменяется при отписке и по `timeout`.
@@ -899,6 +945,18 @@ export class BXRestNavvyCustomApiBlogList {
 
 Возвращённый хелпер дополнительно поддерживает `.resAll()` для загрузки и объединения всех страниц.
 
+Если `result` метода — объект со списком под ключом, например `{ items: [...] }`, используйте `pagNavKeyed()`: третий аргумент — ключ списка. `.res()` отдаёт объект как есть, `.resAll()` — такой же объект с записями всех страниц под ключом:
+
+```typescript
+type BlogItems = { items?: iBXRestCustomBlogGetHttp[] }
+
+this.navvy.pagNavKeyed<BlogItems, BlogItems, iBXRestCustomParamBlogList>(
+  ['blog', 'item', PNM.$list],
+  param,
+  'items'
+)
+```
+
 ## Специфичные методы
 
 ### `tasks.task.list`
@@ -950,6 +1008,40 @@ const tasks$ = bxRest.tasks.task.list<
 }).res()
 ```
 
+### Push & Pull
+
+Раздел `pull` отдаёт настройки подключения к серверу Push & Pull и отправляет события приложения. Клиента веб-сокета в библиотеке нет: подключайтесь своим клиентом по [описанию протокола](https://apidocs.bitrix24.com/settings/interactivity/custom-push-and-pull-client.html) или клиентом `PullClient` из [b24jssdk](https://github.com/bitrix24/b24jssdk).
+
+```typescript
+import { firstValueFrom } from 'rxjs'
+import { BXRestNavvy } from 'bx-rest'
+
+const bxRest = new BXRestNavvy()
+
+// Адреса сервера и каналы для подключения клиента
+const config = await firstValueFrom(bxRest.pull.application.config.get().res())
+console.log(config?.server.websocket_secure, config?.channels.private.id, config?.exp)
+
+// Событие в общий канал приложения: его получат все подписанные клиенты
+await firstValueFrom(bxRest.pull.application.event.add({
+  COMMAND: 'grid:update',
+  PARAMS: { grid_id: 15 },
+}).res())
+```
+
+| Метод | Что делает |
+| --- | --- |
+| `pull.application.config.get(param?)` | Настройки подключения для приложения: адреса сервера, каналы `shared` и `private`, публичные каналы, `exp`, при нужной версии сервера — `clientId` или `jwt`. Даты каналов — `Date`. |
+| `pull.application.event.add(param)` | Событие в канал приложения: без `USER_ID` — в общий канал `shared`, с ним — в личные каналы пользователей. |
+| `pull.application.push.add(param)` | Push-уведомление в мобильное приложение Bitrix24. Только для администратора портала. |
+| `pull.config.get(param?)` | Настройки подключения для пользователя. Метода нет в документации Bitrix24, поэтому он помечен `@experimental`. |
+| `pull.channel.public.get()` | Публичный канал Push & Pull. |
+
+- **Методы `pull.application.*`** работают только в контексте приложения, с его OAuth-токеном. Через вебхук портал отвечает `WRONG_AUTH_TYPE`.
+- **`true` в ответе** `event.add` и `push.add` значит «принято к отправке», а не «доставлено».
+- **`USER_ID` у не администратора.** Отправить событие можно только себе, и `USER_ID` при этом — строка: `'577'`. Число или массив портал отклонит с ошибкой `USER_ID_ACCESS_ERROR`.
+- **Настройки личные:** канал `private` принадлежит пользователю, с чьим токеном идёт запрос. Запрашивайте их заново, когда истекут `exp` или `end` каналов.
+
 ## Парсинг дат
 
 Некоторые REST-поля Bitrix24 (в частности `calendar.section.get`, `calendar.event.get` и `crm.calllist.*`) возвращают даты в виде обычных строк, отформатированных согласно собственным настройкам даты/времени портала (Настройки → формат даты и времени), а не в фиксированном формате ISO. Поскольку этот формат — настройка конкретного портала, `bx-rest` не может знать его заранее, поэтому `BXBaseServices.toDate()` (используется этими мапперами внутренне) разрешает неоднозначную строку в три шага, по порядку:

package/consts/part-name-methods.d.ts

@@ -105,6 +105,7 @@ export declare const $pull = "pull";
 export declare const $channel = "channel";
 export declare const $public = "public";
 export declare const $application = "application";
+export declare const $push = "push";
 export declare const $dialog = "dialog";
 export declare const $users = "users";
 export declare const $messages = "messages";