bx-rest 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -7,6 +7,183 @@
 История до версии 1.0.0 здесь не восстанавливалась — смотрите `git log` для
 более ранних изменений.
 
+## [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
+
+- Типы `iBXRestSettings` и `BXRestApiErrorDetails` экспортируются из `bx-rest`,
+  а `iBXRestSettings` — ещё и из `bx-rest/typification/settings`, где его раньше
+  не было. Новый подпуть `bx-rest/typification/batch` — типы `batch`.
+
+### Changed
+
+- `.resAll()` теперь завершается ошибкой `BXRestApiError`, если любая страница
+  внутри batch-запроса вернула ошибку (`result_error`) или сам batch-запрос
+  вернул ошибку в теле ответа 2xx. Раньше такие страницы молча пропускались, и
+  вызывающий код получал неполный список как полный. Код, который рассчитывал
+  на частичный результат, должен обрабатывать ошибку.
+- `iBXRestUser.DATE_REGISTER` и `iBXRestUser.PERSONAL_BIRTHDAY` стали
+  необязательными: см. исправление `user.get` ниже. Код, который обращается к
+  этим полям без проверки, перестанет компилироваться в режиме `strict`.
+- Отписка от `.resAll()` останавливает запрос оставшихся страниц. Уже
+  отправленный HTTP-запрос не отменяется. `.resAll()` по-прежнему кэширует
+  завершённый результат там, где делал это раньше.
+- `.resAll()` у всех видов пагинации отправляет batch-запросы по 50 команд.
+  Раньше `pagNavResultKeyObject` отправлял отдельный batch на каждую страницу.
+
+### Fixed
+
+- `.resAll()` у `pagNavWithUselessKey` (`lists.field.get`) складывал страницы
+  после первой под числовые ключи вместо объединения полей, а без своего `map`
+  накапливал результат между запусками одного и того же объекта запроса.
+- `.resAll()` падал с `RangeError: Maximum call stack size exceeded` на списках
+  примерно от 124 тысяч записей.
+- `.resAll()` у `pagNav` при нескольких одновременных подписчиках мог отдавать
+  записи по два раза: подписчики делили один массив результата.
+- `.resAll()` учитывает параметры запроса: при заданном `start` страница больше
+  не запрашивается повторно, а `alterPagNav` при `nPageSize` меньше 50 загружает
+  все страницы — раньше он отдавал только часть записей.
+- `.resAll()` у `pagNavTasks`, `pagNavWithUselessKey` и `alterPagNav` не
+  запрашивает лишнюю пустую страницу, если число записей кратно размеру страницы.
+- Ответ 2xx не от Bitrix (например, HTML-страница входа от прокси) больше не даёт
+  `TypeError: Cannot use 'in' operator...`: `.res()` и `.resAll()` завершаются
+  обычным `Error` с названием метода. Пустое тело `.res()` по-прежнему отдаёт как
+  `undefined`, а `.resAll()` завершается той же ошибкой.
+- `isBXRestAnswerSuccess()` и `BXRestMapResult()` падали с `TypeError`, если им
+  передавали не объект.
+- `BXRestRequest.get()`:
+  - вложенные параметры уходили как `filter=[object Object]`, а массивы — как
+    `select=ID,TITLE`. Теперь они сериализуются так же, как в POST;
+  - при `auth.key: 'OAuth2'` токен попадал в адрес запроса как `OAuth2=...`.
+    Теперь он не отправляется, как и в POST.
+- `BXRestSettings.withCredentials` не действовал на запросы `.get()` и на
+  POST-запросы при `auth.key: 'sessid'`.
+- `toDate()` превращал несуществующие даты в соседние (`31.02.2026` — в 3 марта).
+  Теперь это ошибка `Wrong date format`, как и у других неверных дат.
+- `user.get`, `user.current` и другие методы с тем же маппером: пустой
+  `PERSONAL_BIRTHDAY` давал `Invalid Date`, а ответ без `DATE_REGISTER` или
+  `PERSONAL_BIRTHDAY` завершал весь запрос ошибкой. Теперь в этих случаях поле
+  равно `undefined`.
+- `bizProc.startProcFormNewsFeed()` заменял текущей датой любую переданную строку
+  `DATE_CREATE` и падал с `TypeError`, если передать `Date`.
+- `task.elapsedItem.operation.getListByIDTask([])` завершался без значения, и
+  `firstValueFrom` падал с `EmptyError`. Теперь пустой список задач даёт `[]` без
+  запроса. В ошибке `operation.add()` исправлен текст: «Отсутствуют права на
+  добавление записи затраченного времени».
+- `new BXRestMap().disk` возвращал класс запросов вместо маппера, а
+  `.task.commentItem`, `.task.elapsedItem`, `.task.stages`, `.tasks.task` и
+  `.tasks.task.result` были недоступны.
+- Импорт одного класса больше не тянет в бандл всю библиотеку: `BXRestFrame` без
+  остальной библиотеки весит около 8 КБ вместо 117 КБ. Мешали статический
+  инициализатор и декораторы, которые выполнялись при загрузке модуля. В
+  результате убрано статическое поле `BXRestNavvyPullConfig.public` — оно нигде не
+  использовалось, а сам класс не экспортируется.
+
+### Security
+
+- `.res()` и `.resAll()` больше не пишут ошибки запроса в `console.error`:
+  в `AxiosError` лежит конфигурация запроса с токеном авторизации, и он мог
+  попасть в журналы браузера и системы сбора ошибок. Ошибка по-прежнему приходит
+  подписчику. Токен остаётся в `cause.config` у `BXRestApiError` — не логируйте
+  и не отправляйте `cause` целиком.
+- Минимальная версия `axios` поднята до 1.21.0: в версиях до 1.19.0 включительно
+  есть уязвимости высокой степени. В `package-lock.json` также обновлён
+  `follow-redirects` до 1.16.2.
+
 ## [1.5.0] - 2026-11-02
 
 ### Added

package/README.en.md

@@ -24,6 +24,9 @@ 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)
+  - [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)
@@ -93,7 +96,7 @@ 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 |
 | --- | --- |
@@ -196,7 +199,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 +215,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
@@ -238,7 +245,7 @@ bxRest.crm.deal.list({
 
 Without `throwOnApiError`, plain `.res()` can't tell "no records" apart from "an error in a 2xx response" — both resolve as `undefined`.
 
-**Alternative — check the raw response.** `.resVanilla()` returns the raw Bitrix body for 2xx responses; check it with the exported `isBXRestAnswerSuccess()` type guard. Note that `.resVanilla()`, `.mapForVanilla()` and `.resAll()` don't convert errors: on a Bitrix error with a non-2xx status they fail with the original axios error, with the response body in `err.response.data`. An error in the body of a 2xx response comes back as is from `.resVanilla()` and `.mapForVanilla()`, while `.resAll()` fails with a `BXRestApiError` — it has no `throwOnApiError` option.
+**Alternative — check the raw response.** `.resVanilla()` returns the raw Bitrix body for 2xx responses; check it with the exported `isBXRestAnswerSuccess()` type guard. Note that `.resVanilla()`, `.mapForVanilla()` and `.resAll()` don't convert errors: on a Bitrix error with a non-2xx status they fail with the original axios error, with the response body in `err.response.data`. An error in the body of a 2xx response comes back as is from `.resVanilla()` and `.mapForVanilla()`, while `.resAll()` fails with a `BXRestApiError` — it has no `throwOnApiError` option. It fails the same way when any page inside a batch request returns an error (`result_error`): `.resAll()` never gives a partial list.
 
 ```typescript
 import { firstValueFrom } from 'rxjs'
@@ -305,7 +312,7 @@ How the retry works:
   })
   ```
 
-- **Where it works.** In every library request: `.res()`, `.resAll()` (the first page and every batch request), `.resVanilla()`, `.mapForVanilla()`, `BXRestRequest.post()`/`.get()`, `BXRest.batch()`. The retry lives in the HTTP layer, so `.res()` already gets the result of the retry.
+- **Where it works.** In every library request: `.res()`, `.resAll()` (the first page and every batch request), `.resVanilla()`, `.mapForVanilla()`, `BXRestRequest.post()`/`.get()`. The retry lives in the HTTP layer, so `.res()` already gets the result of the retry.
 - **What is not retried:** errors in the body of a 2xx response (Bitrix sends `expired_token` with status 401) and errors of single commands inside a successful batch response (`result_error`) — the whole HTTP request is what gets retried.
 
 ### A token from the portal without BX24.js
@@ -402,7 +409,105 @@ BXRestSettings.update({
 })
 ```
 
-Errors of the refresh function end up in `authRefreshError` of the original error, and `.res()` may print the original error to the console — so keep tokens out of the error messages of the refresh function.
+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()`, `new BXRestRequest()`, `new SessionKeyServices()` — use the global `BXRestSettings`. Only `BXRestNavvy` and everything created through it get the client's own 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, [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`.
+- **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.
+
+### 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` 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.
+- **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
 
@@ -665,6 +770,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.

package/README.md

@@ -24,6 +24,9 @@
   - [Токен от портала без BX24.js](#токен-от-портала-без-bx24js)
   - [Рецепт: напрямую в портал](#рецепт-напрямую-в-портал)
   - [Рецепт: через бэкенд-прокси](#рецепт-через-бэкенд-прокси)
+- [Несколько порталов](#несколько-порталов)
+- [Повтор, таймаут и очередь запросов](#повтор-таймаут-и-очередь-запросов)
+  - [Свои middleware](#свои-middleware)
 - [Работа в iframe без BX24.js](#работа-в-iframe-без-bx24js)
 - [Использование в Angular](#использование-в-angular)
 - [SessionKeyServices](#sessionkeyservices)
@@ -103,7 +106,7 @@ console.log(deals)
 
 ### Режимы результата
 
-REST-вызовы ленивые: запрос начинается, когда на возвращённый `Observable` подписываются или передают его в `firstValueFrom`.
+REST-вызовы ленивые: запрос начинается, когда на возвращённый `Observable` подписываются или передают его в `firstValueFrom`. Отписка до ответа отменяет HTTP-запрос — так работают `switchMap`, `takeUntil` и оператор `timeout` из RxJS. Отмена не откатывает то, что портал уже успел сделать: если `crm.deal.add` дошёл до сервера, сделка может быть создана.
 
 | Метод | Результат |
 | --- | --- |
@@ -206,7 +209,9 @@ const deals = await firstValueFrom(
 | --- | --- |
 | Ошибка API Bitrix с HTTP-статусом не 2xx — так Bitrix отдаёт большинство ошибок: `expired_token` (401), `ERROR_METHOD_NOT_FOUND` (404), `QUERY_LIMIT_EXCEEDED` (503), `Not found` у `crm.*.get` (400) | Возвращённый `Observable` завершается ошибкой `BXRestApiError` — с `throwOnApiError` и без него. |
 | Ошибка API Bitrix в теле ответа со статусом 2xx | По умолчанию `.res()` резолвится обычным образом со значением `undefined` — **исключение не выбрасывается**. Передайте `{ throwOnApiError: true }`, чтобы вместо этого выбрасывалось `BXRestApiError`. |
-| Ошибки транспорта / конфигурации — сбой сети, отсутствие авторизации, отсутствие базового URL, ответ не от Bitrix (например, HTML-страница ошибки прокси) | Возвращённый `Observable` завершается обычной ошибкой `Error`. Исходная ошибка — в её `cause`: для ответа не от Bitrix это ошибка axios, HTTP-статус — в `cause.response.status`. |
+| Ошибки транспорта / конфигурации — сбой сети, превышен [`timeout`](#повтор-таймаут-и-очередь-запросов), отсутствие авторизации, пустой базовый адрес (см. ниже), ответ не от Bitrix (например, HTML-страница ошибки прокси) | Возвращённый `Observable` завершается обычной ошибкой `Error`. Исходная ошибка — в её `cause`: для ответа не от Bitrix это ошибка axios, HTTP-статус — в `cause.response.status`; для `timeout` — `BXRestTimeoutError`. |
+
+**Базовый адрес.** Адрес запроса собирается из двух частей: адреса портала и `urls.additional_part`. Адрес портала — это `urls.key`, а при `urls.source: 'localStorage'` — значение в `localStorage` под ключом `urls.key`. Ошибка `Base URL was not resolved` возникает, только если пусты обе части. Если пуст только адрес портала, а `additional_part` равен `'rest'` (так в настройках по умолчанию), запрос уходит на `rest/<метод>` относительно текущей страницы. Это нужно страницам, открытым на домене самого портала. Но так же уйдёт запрос, если в `localStorage` под ключом ничего не оказалось, — проверяйте значение заранее.
 
 Поля `BXRestApiError`:
 
@@ -220,6 +225,8 @@ const deals = await firstValueFrom(
 
 Для методов REST v3 в `error` попадает `code` ошибки, а в `error_description` — её `message`.
 
+**Токен в ошибках.** Ошибка axios хранит весь отправленный запрос: в `config.url` — адрес, а с ним и секрет вебхука, в `config.data` — тело с токеном. Библиотека отдаёт эту ошибку как есть — в `err.cause` у `.res()` и саму ошибку у `.resVanilla()`. Поэтому `console.error(err)` или отправка ошибки в систему сбора ошибок передаёт и токен. Если ошибки уходят в логи, выбирайте из них нужные поля, например `err.status`, `err.error` и `err.cause?.response?.data`.
+
 **Рекомендуемый вариант — `.res({ throwOnApiError: true })`.** Тогда любая ошибка Bitrix приходит как `BXRestApiError` независимо от HTTP-статуса, и её можно обработать вместе с транспортными ошибками в одном колбэке `catchError`/`error`:
 
 ```typescript
@@ -248,7 +255,7 @@ bxRest.crm.deal.list({
 
 Без `throwOnApiError` по голому `.res()` нельзя отличить «нет записей» от «ошибки в ответе 2xx» — оба случая резолвятся как `undefined`.
 
-**Альтернатива — проверять сырой ответ.** `.resVanilla()` возвращает сырое тело ответа Bitrix для ответов 2xx; проверяйте его экспортируемым type guard `isBXRestAnswerSuccess()`. Учтите, что `.resVanilla()`, `.mapForVanilla()` и `.resAll()` ошибки не преобразуют: на ошибку Bitrix со статусом не 2xx они завершаются исходной ошибкой axios, тело ответа — в `err.response.data`. Ошибку в теле ответа 2xx `.resVanilla()` и `.mapForVanilla()` отдают как есть, а `.resAll()` завершается ошибкой `BXRestApiError`: опции `throwOnApiError` у него нет.
+**Альтернатива — проверять сырой ответ.** `.resVanilla()` возвращает сырое тело ответа Bitrix для ответов 2xx; проверяйте его экспортируемым type guard `isBXRestAnswerSuccess()`. Учтите, что `.resVanilla()`, `.mapForVanilla()` и `.resAll()` ошибки не преобразуют: на ошибку Bitrix со статусом не 2xx они завершаются исходной ошибкой axios, тело ответа — в `err.response.data`. Ошибку в теле ответа 2xx `.resVanilla()` и `.mapForVanilla()` отдают как есть, а `.resAll()` завершается ошибкой `BXRestApiError`: опции `throwOnApiError` у него нет. Так же он завершается, если ошибку вернула любая из страниц внутри batch-запроса (`result_error`): неполный список `.resAll()` не отдаёт.
 
 ```typescript
 import { firstValueFrom } from 'rxjs'
@@ -315,7 +322,7 @@ BXRestSettings.update({
   })
   ```
 
-- **Где работает.** Во всех запросах библиотеки: `.res()`, `.resAll()` (и первая страница, и каждый batch-запрос), `.resVanilla()`, `.mapForVanilla()`, `BXRestRequest.post()`/`.get()`, `BXRest.batch()`. Повтор встроен в HTTP-слой, поэтому `.res()` получает уже результат повтора.
+- **Где работает.** Во всех запросах библиотеки: `.res()`, `.resAll()` (и первая страница, и каждый batch-запрос), `.resVanilla()`, `.mapForVanilla()`, `BXRestRequest.post()`/`.get()`. Повтор встроен в HTTP-слой, поэтому `.res()` получает уже результат повтора.
 - **Что не повторяется:** ошибки в теле ответа со статусом 2xx (Bitrix отдаёт `expired_token` со статусом 401) и ошибки отдельных команд внутри успешного batch-ответа (`result_error`) — повторяется HTTP-запрос целиком.
 
 ### Токен от портала без BX24.js
@@ -412,7 +419,105 @@ BXRestSettings.update({
 })
 ```
 
-Ошибки функции продления попадают в `authRefreshError` исходной ошибки, а `.res()` может вывести исходную ошибку в консоль — поэтому не кладите токены в текст ошибок функции продления.
+Ошибки функции продления попадают в `authRefreshError` исходной ошибки, а приложение может вывести эту ошибку в консоль или отправить в систему сбора ошибок — поэтому не кладите токены в текст ошибок функции продления.
+
+## Несколько порталов
+
+`BXRestSettings` — общие настройки на всё приложение. Если в одном процессе нужно работать с несколькими порталами, например на сервере, который обслуживает разных клиентов, передайте настройки в конструктор `BXRestNavvy`. У такого клиента настройки свои: все его запросы идут на его портал с его токеном, а `BXRestSettings` на него не влияют.
+
+```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.ru', additional_part: 'rest' }
+})
+const portalB = new BXRestNavvy({
+  auth: { source: () => tokenB, key: 'auth' },
+  urls: { source: 'string', key: 'https://b.bitrix24.ru', additional_part: 'rest' }
+})
+
+const deals = await firstValueFrom(
+  portalA.crm.deal.list({ select: ['ID'], filter: {}, start: 0 }).resAll()
+)
+```
+
+- **Без аргумента** `new BXRestNavvy()` работает с глобальными `BXRestSettings`, как и раньше.
+- **Формат** тот же, что у `BXRestSettings.update()`, но настройки передаются целиком: `auth` и `urls` обязательны, с глобальными настройками они не смешиваются.
+- **Смена токена у готового клиента.** Функцию `auth.source` библиотека вызывает перед каждым запросом, в момент подписки. Чтобы сменить токен, поменяйте значение, которое она возвращает. Новый токен получат и запросы, созданные раньше, но ещё не запущенные:
+
+  ```typescript
+  let token = await getToken()
+  const portal = new BXRestNavvy({
+    auth: {
+      source: () => token,
+      key: 'auth',
+      refresh: async () => { token = await getNewToken() } // необязательно
+    },
+    urls: { source: 'string', key: 'https://a.bitrix24.ru', additional_part: 'rest' }
+  })
+
+  token = newToken // следующий запрос уйдёт с новым токеном
+  ```
+
+- **Другой портал или другие заголовки** — создайте новый клиент, это занимает доли миллисекунды.
+- **Продление авторизации** у каждого клиента своё: `auth.refresh` клиента вызывается только для его запросов.
+- **`auth.source: 'cookies'` и `'localStorage'`** читают общее хранилище браузера, поэтому два клиента с одним ключом получат один и тот же токен. Для нескольких порталов задавайте `source` функцией.
+- **Объекты, созданные напрямую**, — `new Navvy()`, `new BXRestRequest()`, `new SessionKeyServices()` — работают с глобальными `BXRestSettings`. Свои настройки получает только `BXRestNavvy` и всё, что создаётся через него.
+
+## Повтор, таймаут и очередь запросов
+
+Три необязательные настройки защищают от лимита частоты запросов Bitrix24 и от зависших запросов. Задайте их в `BXRestSettings.update()` для всего приложения или в настройках клиента `new BXRestNavvy(settings)`. `true` включает значения по умолчанию, число или объект задают свои. Пока настройка не задана, запросы идут как раньше.
+
+```typescript
+BXRestSettings.update({
+  retryOnQueryLimit: true,      // 3 попытки, пауза от 1000 мс
+  timeout: 30_000,              // мс
+  throttle: { perSecond: 2 },
+})
+```
+
+| Настройка | `true` означает | Что делает |
+| --- | --- | --- |
+| `retryOnQueryLimit` | `{ attempts: 3, delay: 1000 }` | Повторяет запрос, если портал ответил `QUERY_LIMIT_EXCEEDED` (HTTP 503, превышен лимит частоты запросов). `attempts` — сколько всего попыток вместе с первой, `delay` — пауза перед второй попыткой в мс, дальше она растёт вдвое: 1000, 2000, 4000... Другие ошибки не повторяются. Попытки кончились — наружу уходит ошибка последней, в `.res()` это `BXRestApiError` с `error: 'QUERY_LIMIT_EXCEEDED'`. |
+| `timeout` | `60000` | Предельное время одного HTTP-запроса в мс. Не уложился — запрос отменяется с ошибкой `BXRestTimeoutError` (поле `timeout` — заданное время). В `.res()` она лежит в `cause`, `.resVanilla()`, `.mapForVanilla()` и `.resAll()` завершаются ей самой. |
+| `throttle` | `{ perSecond: 2 }` | Не больше `perSecond` запросов в секунду, остальные ждут своей очереди. 2 запроса в секунду — лимит Bitrix24 на обычных тарифах. |
+
+В объекте можно задать только часть полей: `retryOnQueryLimit: { attempts: 5 }` оставит `delay: 1000`.
+
+- **Порядок:** повтор, очередь, таймаут, [свои middleware](#свои-middleware), axios. Каждая попытка повтора заново встаёт в очередь и получает своё время `timeout`. Ожидание в очереди и паузы перед повтором в `timeout` не входят.
+- **Очередь** своя у каждого клиента `new BXRestNavvy(settings)` и общая у всех, кто работает с глобальными `BXRestSettings`. Через неё проходит каждый запрос, в том числе каждый batch-запрос `.resAll()`.
+- **`throttle` строже портала.** Bitrix24 пропускает короткие всплески сверх лимита, а `throttle` равномерно распределяет все запросы. Если важна скорость коротких пачек запросов, хватит одного `retryOnQueryLimit`.
+- **Отписка** прерывает и ожидание в очереди, и паузу перед повтором: такой запрос уже не уйдёт.
+- **Настройки читаются в момент подписки**, как и остальные.
+- **Неверное значение** — например, `throttle: { perSecond: 0 }` или отрицательный `timeout` — завершает запрос ошибкой `TypeError` с описанием, на портал ничего не уходит.
+
+### Свои middleware
+
+Middleware — функция, через которую проходит каждый запрос перед отправкой: логирование, метрики, подмена заголовков, свой транспорт вместо axios. Задаётся в `middleware` — так же глобально или у клиента:
+
+```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`** — запрос: `method` (`'GET'` или `'POST'`), `url` (у GET вместе с параметрами), `data` (тело POST), `headers`, `withCredentials`, `signal`. `next(config)` отправляет его дальше и возвращает тело ответа.
+- **Порядок:** первый в списке — внешний, он первым видит запрос и последним — ответ. Все свои middleware идут после `retryOnQueryLimit`, `throttle` и `timeout`, поэтому видят каждую попытку повтора. Повтор после `auth.refresh` идёт снаружи всех шагов: при продлении авторизации запрос пройдёт через них ещё раз.
+- **Изменить запрос** — передать дальше новый объект: `next({ ...config, headers: { ...config.headers, 'X-Trace': id } })`.
+- **Свой транспорт** — middleware, который не зовёт `next`: он сам отправляет запрос и возвращает тело ответа. На ответ не 2xx он должен отклонить промис ошибкой с полем `response: { status, data }`, как это делает axios. По этому полю библиотека узнаёт ошибки Bitrix (`BXRestApiError`) и ошибки авторизации (`auth.refresh`).
+- **`config.signal`** передавайте в свой транспорт: по нему запрос отменяется при отписке и по `timeout`.
+- **`config.url` и `config.data`** содержат токен и секрет вебхука — не логируйте их как есть.
 
 ## Работа в iframe без BX24.js
 
@@ -675,6 +780,13 @@ npm run demo:bootstrap
 Дальше в любой из `projects/demo-angular|demo-vue|demo-react`: `npm run dev`
 (для Angular — `npm start`). Подробности — в README каждого демо.
 
+`projects/demo-node` — демо для Node.js, без интерфейса. Показывает два
+портала в одном процессе, `retryOnQueryLimit`, `throttle`, `timeout`, свой
+`middleware` для логирования и обработку `BXRestApiError`. `npm run mock`
+запускает его со встроенной заглушкой портала, `npm start` — с настоящим
+порталом по адресу входящего вебхука из `BX_WEBHOOK_A`. На портале демо только
+читает данные.
+
 ## Кастомные REST-методы
 
 `Navvy` экспортируется из `bx-rest`. В Angular зарегистрируйте показанный выше `NavvyProvider` и внедрите `Navvy` в ваш кастомный API-сервис. URL метода представлен массивом и перед отправкой запроса соединяется точками.