bx-rest 1.5.1 → 1.7.0

package/CHANGELOG.md

@@ -7,6 +7,169 @@
 История до версии 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
+
+- Клиент со своими настройками: `new BXRestNavvy(settings)`. Все запросы
+  такого клиента идут на его портал с его токеном, продление авторизации у
+  него своё, а `BXRestSettings` на него не влияют. Так в одном процессе можно
+  работать с несколькими порталами. `new BXRestNavvy()` без аргумента
+  работает с глобальными `BXRestSettings`, как раньше. Подробнее — в разделе
+  README «Несколько порталов».
+- Настройки `retryOnQueryLimit`, `timeout` и `throttle` — в `BXRestSettings`
+  или у клиента `new BXRestNavvy(settings)`. `retryOnQueryLimit` повторяет
+  запрос при `QUERY_LIMIT_EXCEEDED` с растущей паузой, `timeout` отменяет
+  запрос, который идёт дольше заданного времени, с ошибкой
+  `BXRestTimeoutError`, `throttle` пропускает не больше N запросов в секунду.
+  `true` включает значения по умолчанию: 3 попытки с паузой от 1000 мс,
+  60 000 мс и 2 запроса в секунду. Пока настройки не заданы, запросы идут как
+  раньше. Подробнее — в разделе README «Повтор, таймаут и очередь запросов».
+- Настройка `middleware` — свои функции, через которые проходит каждый
+  запрос: логирование, подмена заголовков, свой транспорт вместо axios. Типы
+  `BXRestMiddleware`, `BXRestRequestConfig` и `BXRestSend` экспортируются из
+  `bx-rest`. Подробнее — в разделе README «Свои middleware».
+
+### Changed
+
+- Отписка до ответа теперь отменяет HTTP-запрос, как у `HttpClient` в
+  Angular. Раньше запрос доходил до конца, а ответ отбрасывался. На
+  `firstValueFrom` и обычную подписку это не влияет: они отписываются после
+  ответа. Отменяются запросы, которые обрывают `switchMap`, `takeUntil`,
+  `timeout` из RxJS или явный `unsubscribe()`. Отмена не откатывает то, что
+  портал уже успел сделать.
+- Один экземпляр axios на клиента: он создаётся только при первом запросе. 
+  Создание объекта запроса стало примерно в 100 раз быстрее (10,7 → 0,15 мкс), 
+  при `new BXRestNavvy()` — вдвое.
+- Ошибки HTTP библиотека узнаёт по полю `response: { status, data }`, а не
+  через `axios.isAxiosError`. Для ошибок axios ничего не меняется, а
+  `isBXRestAuthError` и `BXRestApiError` теперь работают и с ошибками своего
+  транспорта такой же формы.
+- `bizProc.startProcFormNewsFeed()`: если портал вернул ошибку Bitrix при
+  создании элемента списка в ответе 2xx, вызов завершается ошибкой
+  `BXRestApiError` с кодом и описанием ошибки. Раньше в этом случае приходила
+  общая ошибка `Не удалось запустить бизнес процесс`. Ошибки со статусом не 2xx
+  и раньше приходили как `BXRestApiError`.
+- Ошибки, которые библиотека создаёт сама, теперь на английском, как и
+  остальные её сообщения (`SessionKeyError`, `BXRestTimeoutError`, ошибки
+  разбора значений). Это ошибки `bizProc.startProcFormNewsFeed()`,
+  `disk.operation.*` и `task.elapsedItem.operation.*`. Код, который
+  сравнивает `err.message` с русским текстом, нужно обновить. Ошибки Bitrix
+  (`BXRestApiError`) приходят с текстом портала, как и раньше.
+
+### Removed
+
+- У `BXRestRequest` удалены публичные члены, которые библиотека не
+  использовала: `defSettings`, `getHttpParamsPost()`, `sliceArrayIntoChunks()`
+  и `removingMultipleSlashes()`. Они достались от внутреннего базового класса
+  и запросы не отправляли. `post()`, `get()`, `httpPost()` и `httpGet()` не
+  изменились. Код, который обращался к удалённым членам, перестанет
+  компилироваться.
+- Из `bx-rest/services/navvy` удалён абстрактный класс `NavvySupport`:
+  библиотека его не использовала. Тип `ReturnTypeNavvy` остался.
+- Из `bx-rest` удалён класс `HttpNavvyServices` вместе с его типами
+  `iBXRestParams` и `iBXRestAnswers`. Он отправлял запросы с типами для
+  небольшого набора методов, сама библиотека его не использовала, а в README
+  он не описан. Вместо него используйте `BXRestNavvy` или
+  `BXRestRequest.post()`.
+- Из исходников удалены 63 модуля, недостижимых из точек входа пакета (старый
+  слой `request/*`, `rest/base`, `functions/errorHandler`, `isDate`, `isEqual`,
+  `isValidDate`, `serializeJavascript`, `services/permission` и другие), и
+  закомментированный код. Файлы 52 из них (`.d.ts` и `esm2022/*.mjs`) лежали в
+  пакете, но ни основной бандл, ни `exports` их не подключали, поэтому через
+  `import` из `bx-rest` и его подпутей они были недоступны. Из пакета удалено
+  104 файла. Затронуть это может только код, который импортировал типы по
+  внутреннему пути вроде `bx-rest/request/...` при `moduleResolution: "node"`.
+
+### Fixed
+
+- Проверка типов под `moduleResolution: "nodenext"` или `"node16"` с
+  `skipLibCheck: false` больше не падает с ошибкой TS1479 в
+  `typification/rest/calendar/event/get.d.ts`. Типы `countries-and-timezones`
+  теперь подключаются через `resolution-mode: 'import'`: ветка `require` этого
+  пакета указывает на несуществующий файл типов. Сами типы не изменились, код
+  пакета тоже. В режиме `bundler` (Angular, Vite, webpack) ошибки не было.
+- `bizProc.startProcFormNewsFeed()` создаёт `ELEMENT_CODE` из префикса
+  `bx_rest_` и 128 случайных бит (`crypto.getRandomValues`). Раньше код
+  собирался из префикса другого приложения `trace_studio_`, времени и
+  `Math.random()`. Если портал отвечает, что такой код уже занят
+  (`ERROR_ELEMENT_ALREADY_EXISTS`), вызов создаёт новый код и повторяет
+  запрос, всего до трёх попыток.
+- `disk.operation.getOfCreateRootFolderApp()` и
+  `getOfCreateRootContentFolderApp()`: если не удалось получить хранилище
+  приложения, ошибка теперь так и называется — `Could not get the app
+  storage`. Раньше в ней был чужой текст про учёт времени: `Отсутствуют права
+  добавление записи затраченного времени`.
+
 ## [1.5.1] - 2026-11-05
 
 ### Added

package/README.en.md

@@ -24,6 +24,11 @@ Also known as: Bitrix24 REST client, BX24 REST SDK, Bitrix24 API client, Bitrix
   - [A token from the portal without BX24.js](#a-token-from-the-portal-without-bx24js)
   - [Recipe: straight to the portal](#recipe-straight-to-the-portal)
   - [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)
 - [SessionKeyServices](#sessionkeyservices)
@@ -36,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)
@@ -93,12 +99,12 @@ Do not hardcode or commit a production access token. Pass it from your applicati
 
 ### Result modes
 
-REST calls are lazy: the request starts when the returned `Observable` is subscribed to or passed to `firstValueFrom`.
+REST calls are lazy: the request starts when the returned `Observable` is subscribed to or passed to `firstValueFrom`. Unsubscribing before the response aborts the HTTP request — this is what `switchMap`, `takeUntil` and the RxJS `timeout` operator rely on. Aborting does not undo what the portal has already done: if `crm.deal.add` reached the server, the deal may be created.
 
 | 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`. |
 
@@ -108,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.
@@ -196,7 +209,9 @@ For cross-origin requests, the server — the portal or your proxy — must allo
 | --- | --- |
 | Bitrix API error with a non-2xx HTTP status — this is how Bitrix sends most errors: `expired_token` (401), `ERROR_METHOD_NOT_FOUND` (404), `QUERY_LIMIT_EXCEEDED` (503), `Not found` from `crm.*.get` (400) | The returned `Observable` errors with a `BXRestApiError`, with or without `throwOnApiError`. |
 | Bitrix API error in the body of a 2xx response | By default, `.res()` resolves normally with `undefined` — **it does not throw**. Pass `{ throwOnApiError: true }` to make it throw a `BXRestApiError` instead. |
-| Transport / configuration errors — network failure, missing auth, missing base URL, a response that is not from Bitrix (e.g. a proxy's HTML error page) | The returned `Observable` errors with a plain `Error`. The original error is in its `cause`: for a response that is not from Bitrix it is the axios error, with the HTTP status in `cause.response.status`. |
+| Transport / configuration errors — network failure, [`timeout`](#retry-timeout-and-request-queue) exceeded, missing auth, an empty base address (see below), a response that is not from Bitrix (e.g. a proxy's HTML error page) | The returned `Observable` errors with a plain `Error`. The original error is in its `cause`: for a response that is not from Bitrix it is the axios error, with the HTTP status in `cause.response.status`; for `timeout` it is `BXRestTimeoutError`. |
+
+**Base address.** The request address is built from two parts: the portal address and `urls.additional_part`. The portal address is `urls.key`, or, with `urls.source: 'localStorage'`, the value stored in `localStorage` under the `urls.key` key. The `Base URL was not resolved` error happens only when both parts are empty. If only the portal address is empty and `additional_part` is `'rest'` (as in the default settings), the request goes to `rest/<method>` relative to the current page. This is meant for pages opened on the portal's own domain. But a request also goes there when nothing was found in `localStorage` under the key, so check the value beforehand.
 
 `BXRestApiError` fields:
 
@@ -210,6 +225,8 @@ For cross-origin requests, the server — the portal or your proxy — must allo
 
 For REST v3 methods, `error` holds the error `code` and `error_description` its `message`.
 
+**The token in errors.** An axios error keeps the whole request that was sent: `config.url` holds the address, and with it the webhook secret, and `config.data` holds the body with the token. The library passes this error on as is — in `err.cause` for `.res()` and as the error itself for `.resVanilla()`. So `console.error(err)` or sending the error to an error tracker passes the token along too. If errors go to logs, pick the fields you need, for example `err.status`, `err.error` and `err.cause?.response?.data`.
+
 **Recommended — `.res({ throwOnApiError: true })`.** Every Bitrix error then arrives as a `BXRestApiError` whatever the HTTP status, and can be handled alongside transport errors in a single `catchError`/`error` callback:
 
 ```typescript
@@ -404,6 +421,140 @@ BXRestSettings.update({
 
 Errors of the refresh function end up in `authRefreshError` of the original error, and your app may print that error to the console or send it to an error tracker — so keep tokens out of the error messages of the refresh function.
 
+## Several portals
+
+`BXRestSettings` are shared by the whole app. To work with several portals in one process, for example on a server that serves different customers, pass the settings to the `BXRestNavvy` constructor. Such a client has its own settings: all its requests go to its portal with its token, and `BXRestSettings` do not affect it.
+
+```typescript
+import { BXRestNavvy } from 'bx-rest'
+import { firstValueFrom } from 'rxjs'
+
+const portalA = new BXRestNavvy({
+  auth: { source: () => tokenA, key: 'auth' },
+  urls: { source: 'string', key: 'https://a.bitrix24.com', additional_part: 'rest' }
+})
+const portalB = new BXRestNavvy({
+  auth: { source: () => tokenB, key: 'auth' },
+  urls: { source: 'string', key: 'https://b.bitrix24.com', additional_part: 'rest' }
+})
+
+const deals = await firstValueFrom(
+  portalA.crm.deal.list({ select: ['ID'], filter: {}, start: 0 }).resAll()
+)
+```
+
+- **Without an argument** `new BXRestNavvy()` uses the global `BXRestSettings`, as before.
+- **The format** is the same as for `BXRestSettings.update()`, but the settings are passed in full: `auth` and `urls` are required and are not merged with the global settings.
+- **Changing the token of an existing client.** The library calls `auth.source` before every request, at subscribe time. To change the token, change the value the function returns. Requests created earlier but not started yet get the new token too:
+
+  ```typescript
+  let token = await getToken()
+  const portal = new BXRestNavvy({
+    auth: {
+      source: () => token,
+      key: 'auth',
+      refresh: async () => { token = await getNewToken() } // optional
+    },
+    urls: { source: 'string', key: 'https://a.bitrix24.com', additional_part: 'rest' }
+  })
+
+  token = newToken // the next request goes out with the new token
+  ```
+
+- **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()` 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
+
+Three optional settings protect against the Bitrix24 request rate limit and against hanging requests. Set them in `BXRestSettings.update()` for the whole app or in the settings of a `new BXRestNavvy(settings)` client. `true` turns on the defaults, a number or an object sets your own values. While a setting is not set, requests go as before.
+
+```typescript
+BXRestSettings.update({
+  retryOnQueryLimit: true,      // 3 attempts, pause from 1000 ms
+  timeout: 30_000,              // ms
+  throttle: { perSecond: 2 },
+})
+```
+
+| Setting | `true` means | What it does |
+| --- | --- | --- |
+| `retryOnQueryLimit` | `{ attempts: 3, delay: 1000 }` | Retries the request when the portal answers `QUERY_LIMIT_EXCEEDED` (HTTP 503, request rate limit exceeded). `attempts` is the total number of attempts including the first one, `delay` is the pause before the second attempt in ms, then it doubles: 1000, 2000, 4000... Other errors are not retried. When the attempts run out, the error of the last one goes out; in `.res()` it is a `BXRestApiError` with `error: 'QUERY_LIMIT_EXCEEDED'`. |
+| `timeout` | `60000` | Time limit for one HTTP request in ms. A request that takes longer is aborted with `BXRestTimeoutError` (its `timeout` field is the limit). In `.res()` it is in `cause`; `.resVanilla()`, `.mapForVanilla()` and `.resAll()` error with it directly. |
+| `throttle` | `{ perSecond: 2 }` | At most `perSecond` requests per second, the rest wait in a queue. 2 requests per second is the Bitrix24 limit on regular plans. |
+
+An object may set only some fields: `retryOnQueryLimit: { attempts: 5 }` keeps `delay: 1000`.
+
+- **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:
+
+```typescript
+import { BXRestMiddleware, BXRestSettings } from 'bx-rest'
+
+const logDuration: BXRestMiddleware = async (config, next) => {
+  const started = Date.now()
+  try {
+    return await next(config)
+  } finally {
+    console.debug(config.method, Date.now() - started, 'ms')
+  }
+}
+
+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`, `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`.
+- **`config.url` and `config.data`** contain the token and the webhook secret — do not log them as they are.
+
 ## Working in an iframe without BX24.js
 
 `BXRestFrame` is the commands an application in an iframe sends to the portal: the frame size, the selection dialogs, sliders, the messenger, placements, options, installation. The same commands and the same names as in BX24.js, but with promises instead of callbacks, and with no need to load BX24.js. bx-rest itself makes the REST requests, and `getAuth()`/`refreshAuth()` give the token for them (see [Authorization refresh](#authorization-refresh)).
@@ -665,6 +816,12 @@ npm run demo:bootstrap
 Then, in any of `projects/demo-angular|demo-vue|demo-react`: `npm run dev`
 (for Angular, `npm start`). See each demo's own README for details.
 
+`projects/demo-node` is a Node.js demo without a UI. It shows two portals in
+one process, `retryOnQueryLimit`, `throttle`, `timeout`, your own `middleware`
+for logging and handling `BXRestApiError`. `npm run mock` runs it against a
+built-in mock portal, `npm start` against a real portal using the incoming
+webhook address from `BX_WEBHOOK_A`. On a portal the demo only reads data.
+
 ## Custom REST methods
 
 `Navvy` is exported from `bx-rest`. In Angular, register the `NavvyProvider` shown above and inject `Navvy` into your custom API service. A method URL is represented as an array and is joined with dots before the request is sent.
@@ -777,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`
@@ -828,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: