bx-rest 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -7,6 +7,59 @@
 История до версии 1.0.0 здесь не восстанавливалась — смотрите `git log` для
 более ранних изменений.
 
+## [1.4.0] - 2026-10-29
+
+### Added
+
+- Автоматическое продление авторизации — `BXRestSettings.auth.refresh`.
+  Если запрос упал с ошибкой авторизации, библиотека вызывает эту функцию и
+  повторяет запрос один раз, заново читая токен, адрес и заголовки из
+  настроек. Работает во всех запросах: `.res()`, `.resAll()` (включая
+  batch), `.resVanilla()`, `.mapForVanilla()`, `BXRestRequest.post()`/`.get()`,
+  `BXRest.batch()`. Одновременно упавшие запросы ждут одно общее продление.
+  Если продление упало, наружу уходит исходная ошибка запроса, а причина —
+  в её поле `authRefreshError` (`getAuthRefreshError(err)`). Без
+  `auth.refresh` запросы не повторяются, как и раньше.
+- `isBXRestAuthError()` — условие продления по умолчанию: ошибка Bitrix
+  `expired_token` или `invalid_token`, либо ответ 401 без тела ошибки Bitrix
+  (например, пустой 401 от бэкенд-прокси). Другие ошибки Bitrix со статусом
+  401 (`insufficient_scope`, `ACCESS_DENIED`, ...) продлением не лечатся и не
+  повторяются. Условие переопределяется через `auth.isAuthError`.
+- `BXRestFrame` — команды порталу из iframe приложения без подключения
+  BX24.js: те же команды и имена, что у BX24.js, но с промисами вместо
+  колбэков. Данные запуска (`init()`), токен приложения (`getAuth()`,
+  `refreshAuth()`), установка (`installFinish()`, `firstRunFinish()`), размер
+  и заголовок фрейма, прокрутка и перезагрузка страницы, диалоги выбора
+  сотрудников, прав доступа и объектов CRM (с отменой через `signal`),
+  слайдеры (`openApplication()`, `openPath()`, `closeApplication()`),
+  мессенджер (`im.*`), встраивания (`placement.info/getInterface/call/bindEvent`)
+  и настройки (`userOption`, `appOption`). Ошибки — `BXRestFrameError` с
+  полем `code`. Использует внутренний недокументированный протокол
+  postMessage, который Bitrix24 может изменить; сверен с BX24.js от
+  2022-03-17 и с ответной стороной портала — подробности в README, раздел
+  «Работа в iframe без BX24.js».
+- У `BXRestApiError` появилось поле `authRefreshError`.
+
+### Changed
+
+- Обычный `Error`, которым `.res()` завершается на ответ не от Bitrix
+  (например, HTML-страницу или пустой 401 от прокси), теперь хранит исходную
+  ошибку axios в `cause` — с HTTP-статусом в `cause.response.status`. Тип и
+  текст ошибки прежние.
+
+## [1.3.0] - 2026-10-28
+
+### Added
+
+- `BXRestSettings.headers` — статичные HTTP-заголовки, которые прикладываются
+  к каждому запросу (например, `{ 'X-Bitrix-App': 'smart-process-pro' }`).
+- `.withHeaders()` у Navvy-запросов — заголовки только для одного запроса,
+  поверх `BXRestSettings.headers`. Действуют и на batch-запросы `.resAll()`.
+  `BXRestRequest.post()`/`.get()` и `BXRest.batch()` принимают те же заголовки
+  последним необязательным аргументом.
+- `Content-Type` библиотека по-прежнему выставляет сама — заголовками он не
+  перебивается.
+
 ## [1.2.0] - 2026-10-28
 
 ### Fixed

package/README.en.md

@@ -18,7 +18,13 @@ Also known as: Bitrix24 REST client, BX24 REST SDK, Bitrix24 API client, Bitrix
   - [Result modes](#result-modes)
 - [Authentication and OAuth2](#authentication-and-oauth2)
   - [`withCredentials`](#withcredentials)
+- [HTTP headers](#http-headers)
 - [Error handling](#error-handling)
+- [Authorization refresh](#authorization-refresh)
+  - [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)
+- [Working in an iframe without BX24.js](#working-in-an-iframe-without-bx24js)
 - [Usage in Angular](#usage-in-angular)
 - [SessionKeyServices](#sessionkeyservices)
 - [Usage in Vue](#usage-in-vue)
@@ -154,6 +160,34 @@ BXRestSettings.update({
 })
 ```
 
+## HTTP headers
+
+Put static headers that every request needs into `BXRestSettings.headers`:
+
+```typescript
+BXRestSettings.update({
+  headers: {
+    'X-Bitrix-App': 'smart-process-pro'
+  }
+})
+```
+
+They are attached to every request the library makes, including the `.resAll()` batch requests, and, like the other settings, are read at subscribe time. `update()` merges settings only at the top level, so `headers` is replaced as a whole — to add a header to the ones already set, pass the full set.
+
+For a single request, use `.withHeaders()`. Its headers are applied on top of `BXRestSettings.headers`; when a name matches (case-insensitively), the `.withHeaders()` value wins. It applies to `.res()`, `.resAll()`, `.resVanilla()` and `.mapForVanilla()`:
+
+```typescript
+const deals = await firstValueFrom(
+  bxRest.crm.deal.list({ select: ['ID', 'TITLE'], filter: {}, start: 0 })
+    .withHeaders({ 'X-Request-Source': 'report' })
+    .resAll()
+)
+```
+
+The library always sets `Content-Type` itself (`application/json`, or `application/x-www-form-urlencoded` for `auth.key: 'sessid'`): the server parses the request body based on it, so headers can't override it.
+
+For cross-origin requests, the server — the portal or your proxy — must allow a non-standard header in `Access-Control-Allow-Headers` of its CORS preflight (`OPTIONS`) response, or the browser will block the request. The header doesn't add an extra request: the library's JSON requests already go through a preflight because of `Content-Type: application/json`.
+
 ## Error handling
 
 `.res()` can fail in three ways — which one depends on how the portal answered.
@@ -162,7 +196,7 @@ BXRestSettings.update({
 | --- | --- |
 | 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`. |
+| 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`. |
 
 `BXRestApiError` fields:
 
@@ -193,7 +227,7 @@ bxRest.crm.deal.list({
     if (err instanceof BXRestApiError) {
       console.error('Bitrix API error:', err.status, err.error, err.error_description)
       if (err.error === 'expired_token') {
-        // refresh the token and retry the request
+        // auth.refresh is not set or did not help — see "Authorization refresh"
       }
     } else {
       console.error('Request failed:', err.message)
@@ -227,6 +261,205 @@ if (!answer || !isBXRestAnswerSuccess(answer)) {
 }
 ```
 
+## Authorization refresh
+
+With `auth.refresh` set, the library refreshes an expired authorization by itself. When a request fails with an authorization error, the library calls `auth.refresh()` and retries the request, and your code just gets the result.
+
+```typescript
+BXRestSettings.update({
+  auth: {
+    source: () => accessToken,
+    key: 'auth',
+    // get a new authorization and put it where source reads it from
+    refresh: async () => {
+      accessToken = await getNewToken()
+    }
+  },
+  // ...
+})
+```
+
+| `auth` field | Value |
+| --- | --- |
+| `refresh` | `() => Promise<unknown>`. Gets a new authorization. The promise value is not used: the retry reads the token, the URL and the headers from the settings again — so the function has to put the new token where `auth.source` reads it from (or, through a proxy, hand it to the server). |
+| `isAuthError` | `(error: unknown) => boolean`, optional. Which request error counts as an authorization error. It gets the original HTTP request error — usually an `AxiosError`. Defaults to the exported `isBXRestAuthError`, which is easy to extend: `error => isBXRestAuthError(error) \|\| myCheck(error)`. |
+
+Without `auth.refresh` the library behaves as before: requests are not retried. `update()` merges settings at the top level only, so `BXRestSettings.update({ auth: {...} })` replaces the whole `auth` — `refresh` included. When you change `auth`, pass `refresh` again.
+
+How the retry works:
+
+- **What counts as an authorization error** (`isBXRestAuthError`): a response with the Bitrix error `expired_token` or `invalid_token`, whatever the HTTP status; a 401 response without a Bitrix error body — e.g. an empty 401 from a backend proxy that has no valid token. The other Bitrix system errors come with status 401 too (`insufficient_scope`, `NO_AUTH_FOUND`, `ACCESS_DENIED`, `INVALID_CREDENTIALS`, `user_access_error`, `OVERLOAD_LIMIT`), but a new token does not fix them — they are not retried.
+- **One retry.** If the retry fails as well, its error goes out; there is no second refresh.
+- **One refresh for everybody.** When several requests fail at once, `refresh()` is called once and all of them are retried. A request that was in flight while the token was being refreshed is retried without another refresh.
+- **The refresh failed** (`refresh()` rejected or threw) — the original request error goes out, and the reason the refresh failed is in its `authRefreshError` field. `getAuthRefreshError(err)` reads it from any error:
+
+  ```typescript
+  import { BXRestApiError, getAuthRefreshError } from 'bx-rest'
+
+  bxRest.crm.deal.get({ ID: 1 }).res().subscribe({
+    error: err => {
+      if (err instanceof BXRestApiError && err.error === 'expired_token') {
+        console.error('Could not refresh the authorization:', getAuthRefreshError(err))
+      }
+    }
+  })
+  ```
+
+- **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.
+- **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
+
+A browser cannot refresh a token through OAuth — that takes the `client_secret`. But the application is open in a portal iframe, the user is logged in to the portal, and the portal itself hands the application a token over postMessage — this is how `BX24.getAuth()` and `BX24.refreshAuth()` work. `BXRestFrame` does the same without loading BX24.js (the other BX24.js commands are in [Working in an iframe without BX24.js](#working-in-an-iframe-without-bx24js)):
+
+```typescript
+import { BXRestFrame } from 'bx-rest'
+
+const frame = new BXRestFrame()         // optional: { timeout: 10000 }
+
+const auth = await frame.getAuth()      // the current authorization — like BX24.getAuth()
+const fresh = await frame.refreshAuth() // a new authorization — like BX24.refreshAuth()
+// { access_token, refresh_token, expires_in, domain, member_id }
+```
+
+| Result field | Value |
+| --- | --- |
+| `access_token`, `refresh_token` | The application tokens. |
+| `expires_in` | When the `access_token` expires — **milliseconds** since January 1, 1970, as in `BX24.getAuth()`. Not the lifetime in seconds, as in the OAuth server response. |
+| `domain` | The portal address without the protocol, e.g. `mycompany.bitrix24.com`. |
+| `member_id` | The permanent portal identifier. |
+
+- **Tokens.** `BXRestFrame` does not log tokens and does not store them anywhere: every `getAuth()` and `refreshAuth()` call asks the portal again, and your code gets the result.
+- **Errors** — `BXRestFrameError` with a `code` field: `NOT_IN_FRAME` (the page is not opened in an application iframe — fails right away), `TIMEOUT` (the portal did not answer within `timeout`, 10 seconds by default), `NO_AUTH` (the portal answered without a token), `BAD_RESPONSE` (the answer could not be parsed). When the portal cannot issue a new token (e.g. the application trial or paid period is over), it shows the "Unable to get new token!" `alert` and does not answer at all — such a refusal comes as `TIMEOUT`.
+- **`getAuth()` and the expiry.** The portal gives the token lifetime at the moment of issue, not what is left of it, so on a page that has been open for a while `expires_in` from `getAuth()` points too far ahead (the same with BX24.js). Use `refreshAuth()` for a fresh token.
+- **The portal domain.** Like BX24.js, `BXRestFrame` cannot vouch for it — it is set by whoever embedded the page in an iframe. So a server must check a token that came from the browser with the portal before trusting it.
+
+### Recipe: straight to the portal
+
+The frontend keeps the token, requests go to `https://<portal>/rest/`. The refresh function gets a new token from the portal and puts it where `auth.source` reads it from — an in-memory variable here:
+
+```typescript
+import { BXRestSettings, BXRestFrame } from 'bx-rest'
+
+const frame = new BXRestFrame()
+const auth = await frame.getAuth()
+let accessToken = auth.access_token
+
+BXRestSettings.update({
+  auth: {
+    source: () => accessToken,
+    key: 'auth',
+    refresh: async () => {
+      accessToken = (await frame.refreshAuth()).access_token
+    }
+  },
+  urls: {
+    source: 'string',
+    key: `https://${auth.domain}`,
+    additional_part: 'rest'
+  }
+})
+```
+
+With `auth.source: 'localStorage'` the refresh function writes the token to `localStorage[auth.key]` in the same way.
+
+### Recipe: through a backend proxy
+
+The server keeps the token, and the browser authorizes with the proxy through a cookie session (`auth.source: 'off'`). A proxy without a valid token answers 401 with an empty body — an authorization error by default. The refresh function gets a new token from the portal and sends it to the server:
+
+```typescript
+import { BXRestSettings, BXRestFrame } from 'bx-rest'
+
+const APP = 'smart-process-pro'
+const frame = new BXRestFrame()
+
+BXRestSettings.update({
+  auth: {
+    source: 'off',
+    key: 'auth',
+    refresh: async () => {
+      const { access_token, refresh_token, expires_in } = await frame.refreshAuth()
+      const response = await fetch(`/api/bitrix/token/${APP}`, {
+        method: 'POST',
+        credentials: 'same-origin',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ access_token, refresh_token, expires_in })
+      })
+      if (!response.ok) {
+        // no request body in the message — it holds the tokens
+        throw new Error(`Token upload failed: HTTP ${response.status}`)
+      }
+    }
+  },
+  urls: {
+    source: 'string',
+    key: '/api/bitrix/rest/',
+    additional_part: '' // otherwise one more `rest/` is appended to the URL
+  },
+  headers: {
+    'X-Bitrix-App': APP
+  }
+})
+```
+
+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.
+
+## 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)).
+
+```typescript
+import { BXRestFrame } from 'bx-rest'
+
+const frame = new BXRestFrame()
+
+const { lang, isAdmin, placement } = await frame.init()
+await frame.fitWindow()
+const user = await frame.selectUser()
+const unsubscribe = frame.placement.bindEvent('Tab:onChange', data => console.log(data))
+```
+
+Create one instance per page, when the application starts: the portal parameters are read in the constructor, and the portal reports the first run only in its first answer per page load. For the same reason, do not use `BXRestFrame` and BX24.js on one page.
+
+| BX24.js | `BXRestFrame` | Answer |
+| --- | --- | --- |
+| `BX24.init()`, `isAdmin()`, `getLang()`, `getDomain()` | `init()` — `{ domain, lang, path, https, memberId, isAdmin, install, firstRun, placement, placementOptions, userOptions, appOptions }` | Asked once, without tokens |
+| `BX24.getAuth()`, `BX24.refreshAuth()` | `getAuth()`, `refreshAuth()` | Asked from the portal every time |
+| `BX24.installFinish()` | `installFinish()` | Only on the installer page (`install`); the portal reloads the page |
+| the end of the `BX24.install()` chain | `firstRunFinish()` | Marks the first run as done; without it `firstRun` stays `true` |
+| `BX24.resizeWindow(w, h)`, `BX24.fitWindow()` | `resizeWindow(w, h)`, `fitWindow()` | `{ width, height }` or `undefined` |
+| `BX24.setTitle(title)` | `setTitle(title)` | `{ title }` or `undefined` |
+| `BX24.scrollParentWindow(scroll)` | `scrollParentWindow(scroll)` | `{ scroll }` or `undefined` |
+| `BX24.reloadWindow()` | `reloadWindow()` | No answer |
+| `BX24.selectUser()`, `BX24.selectUsers()` | `selectUser({ title?, signal? })`, `selectUsers(...)` | An employee / an array of employees |
+| `BX24.selectAccess(value)` | `selectAccess({ value?, signal? })` — `value`: codes that cannot be selected | An array of `{ provider, id, name }` |
+| `BX24.selectCRM(params)` | `selectCRM({ entityType?, multiple?, value?, signal? })` | CRM items by type |
+| `BX24.openApplication(params, cb, settings)` | `openApplication(params?, settings?, { signal? })` | When the slider is closed |
+| `BX24.openPath(path)` | `openPath(path, { signal? })` | `{ result: 'close' }` or `{ result: 'error', errorCode }` |
+| `BX24.closeApplication()` | `closeApplication()` | No answer |
+| `BX24.im.callTo/phoneTo/openMessenger/openHistory` | `im.callTo/phoneTo/openMessenger/openHistory` | No answer |
+| `BX24.placement.info()` | `placement.info()` | `{ placement, options }` from `init()` |
+| `BX24.placement.getInterface()` | `placement.getInterface()` | `{ command, event }` |
+| `BX24.placement.call(cmd, params)` | `placement.call(cmd, params?, { timeout? })` | The command answer or `undefined` |
+| `BX24.placement.bindEvent(event, cb)` | `placement.bindEvent(event, handler)` | `handler` on every event; returns an unsubscribe function |
+| `BX24.userOption.get/set` | `userOption.get/set` | A user option |
+| `BX24.appOption.get/set` | `appOption.get/set` | `set` — administrators only, otherwise `ACCESS_DENIED` |
+
+How the portal answers a command decides when the promise settles:
+
+- **With an answer** (`init()`, `getAuth()`, `refreshAuth()`, `placement.getInterface()`, `appOption.set()`) — no answer within `timeout` (10 seconds by default) is a `TIMEOUT` error.
+- **With an acknowledgement** (`resizeWindow()`, `fitWindow()`, `setTitle()`, `scrollParentWindow()`, `userOption.set()`, `firstRunFinish()`, `placement.call()`) — in some placements the portal does not answer them, so without an answer within `timeout` the promise resolves with `undefined`, not with an error.
+- **Without an answer** (`reloadWindow()`, `closeApplication()`, `installFinish()`, `im.*`) — the promise resolves right after sending.
+- **Waiting for the user** (`select*()`, `openApplication()`, `openPath()`) — with no time limit. When the user closes a dialog without selecting anything, the portal does not answer at all. Cancel the wait with `signal` (`AbortController`); calling the same dialog again cancels the previous wait, because the portal keeps one handler per dialog. A cancelled wait is a `CANCELLED` error.
+
+`placement.bindEvent()` returns an unsubscribe function, but it only stops calling `handler`: the protocol has no way to cancel the subscription on the portal side.
+
+- **Where it looks for the portal.** Like BX24.js, in `window.name`: the portal names the application iframe `DOMAIN|PROTOCOL|APP_SID`. If it is empty — in the page query (`?DOMAIN=…&PROTOCOL=…&APP_SID=…`) the portal opens the application handler with.
+- **Security.** Commands go to the portal origin only (not `'*'`), answers are accepted only from `window.parent` and only from the portal origin.
+- **Errors** — `BXRestFrameError` with a `code` field: `NOT_IN_FRAME` (the page is not opened in an application iframe — fails right away), `TIMEOUT`, `NO_AUTH`, `BAD_RESPONSE`, `CANCELLED`, `ACCESS_DENIED`. Wrong arguments of `resizeWindow()` and `scrollParentWindow()` are a `TypeError`.
+
+> **The protocol is internal and undocumented.** The messages between an application and a Bitrix24 portal are not described in the documentation and may change without notice. `BXRestFrame` follows BX24.js — `https://api.bitrix24.com/api/v1/`, downloaded 2026-10-29, `Last-Modified: 2022-03-17`, SHA-256 `945ad491df8ffb7490b89f4914a439b5a3f575c950c3480562815716a3e07f23` — and is checked against the portal side, `/bitrix/js/rest/applayout.js` (`Last-Modified: 2024-05-15`, SHA-256 `3efd6ab57a4778493a26d10ae0987a82e19fc012ed9935f5c6afa78c4052fcb5`), and against the BX24.js documentation. It is tested against a fake portal, not against a live one.
+
 ## Usage in Angular
 
 Register the public clients and `Navvy` when you want to inject them into Angular services or components:

package/README.md

@@ -18,7 +18,13 @@
   - [Режимы результата](#режимы-результата)
 - [Аутентификация и OAuth2](#аутентификация-и-oauth2)
   - [`withCredentials`](#withcredentials)
+- [HTTP-заголовки](#http-заголовки)
 - [Обработка ошибок](#обработка-ошибок)
+- [Продление авторизации](#продление-авторизации)
+  - [Токен от портала без BX24.js](#токен-от-портала-без-bx24js)
+  - [Рецепт: напрямую в портал](#рецепт-напрямую-в-портал)
+  - [Рецепт: через бэкенд-прокси](#рецепт-через-бэкенд-прокси)
+- [Работа в iframe без BX24.js](#работа-в-iframe-без-bx24js)
 - [Использование в Angular](#использование-в-angular)
 - [SessionKeyServices](#sessionkeyservices)
 - [Использование в Vue](#использование-в-vue)
@@ -164,6 +170,34 @@ BXRestSettings.update({
 })
 ```
 
+## HTTP-заголовки
+
+Статичные заголовки, которые нужны в каждом запросе, задайте в `BXRestSettings.headers`:
+
+```typescript
+BXRestSettings.update({
+  headers: {
+    'X-Bitrix-App': 'smart-process-pro'
+  }
+})
+```
+
+Они прикладываются ко всем запросам библиотеки, включая batch-запросы `.resAll()`, и, как и остальные настройки, читаются в момент подписки. `update()` сливает настройки только на верхнем уровне, поэтому `headers` заменяется целиком — чтобы добавить заголовок к уже заданным, передайте весь набор.
+
+Для одного запроса используйте `.withHeaders()`. Его заголовки добавляются поверх `BXRestSettings.headers`, при совпадении имени (без учёта регистра) побеждает значение из `.withHeaders()`. Действует на `.res()`, `.resAll()`, `.resVanilla()` и `.mapForVanilla()`:
+
+```typescript
+const deals = await firstValueFrom(
+  bxRest.crm.deal.list({ select: ['ID', 'TITLE'], filter: {}, start: 0 })
+    .withHeaders({ 'X-Request-Source': 'report' })
+    .resAll()
+)
+```
+
+`Content-Type` библиотека всегда выставляет сама (`application/json`, а для `auth.key: 'sessid'` — `application/x-www-form-urlencoded`): от него зависит, как сервер разберёт тело запроса, поэтому заголовками он не перебивается.
+
+Для запросов на другой домен сервер — портал или ваш прокси — должен разрешить нестандартный заголовок в `Access-Control-Allow-Headers` ответа на CORS preflight (`OPTIONS`), иначе браузер заблокирует запрос. Лишнего запроса заголовок не добавляет: JSON-запросы библиотеки и так проходят через preflight из-за `Content-Type: application/json`.
+
 ## Обработка ошибок
 
 `.res()` может завершиться неудачей тремя способами — какой именно, зависит от того, как ответил портал.
@@ -172,7 +206,7 @@ BXRestSettings.update({
 | --- | --- |
 | Ошибка 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`. |
+| Ошибки транспорта / конфигурации — сбой сети, отсутствие авторизации, отсутствие базового URL, ответ не от Bitrix (например, HTML-страница ошибки прокси) | Возвращённый `Observable` завершается обычной ошибкой `Error`. Исходная ошибка — в её `cause`: для ответа не от Bitrix это ошибка axios, HTTP-статус — в `cause.response.status`. |
 
 Поля `BXRestApiError`:
 
@@ -203,7 +237,7 @@ bxRest.crm.deal.list({
     if (err instanceof BXRestApiError) {
       console.error('Bitrix API error:', err.status, err.error, err.error_description)
       if (err.error === 'expired_token') {
-        // обновить токен и повторить запрос
+        // auth.refresh не задан или не помог — см. «Продление авторизации»
       }
     } else {
       console.error('Request failed:', err.message)
@@ -237,6 +271,205 @@ if (!answer || !isBXRestAnswerSuccess(answer)) {
 }
 ```
 
+## Продление авторизации
+
+Если задать `auth.refresh`, библиотека сама продлевает истёкшую авторизацию. Запрос упал с ошибкой авторизации — библиотека вызывает `auth.refresh()` и повторяет запрос, а прикладной код получает обычный результат.
+
+```typescript
+BXRestSettings.update({
+  auth: {
+    source: () => accessToken,
+    key: 'auth',
+    // получить новую авторизацию и положить её туда, откуда её читает source
+    refresh: async () => {
+      accessToken = await getNewToken()
+    }
+  },
+  // ...
+})
+```
+
+| Поле `auth` | Значение |
+| --- | --- |
+| `refresh` | `() => Promise<unknown>`. Получает новую авторизацию. Значение промиса не используется: повтор заново читает токен, адрес и заголовки из настроек — поэтому функция должна положить новый токен туда, откуда его читает `auth.source` (или, при работе через прокси, передать его на сервер). |
+| `isAuthError` | `(error: unknown) => boolean`, необязательно. Какую ошибку запроса считать ошибкой авторизации. Получает исходную ошибку HTTP-запроса — обычно `AxiosError`. По умолчанию — экспортируемая `isBXRestAuthError`, её удобно дополнять: `error => isBXRestAuthError(error) \|\| myCheck(error)`. |
+
+Без `auth.refresh` библиотека ведёт себя как раньше: запросы не повторяются. `update()` сливает настройки только на верхнем уровне, поэтому `BXRestSettings.update({ auth: {...} })` заменяет `auth` целиком — вместе с `refresh`. Если меняете `auth`, передайте `refresh` снова.
+
+Как работает повтор:
+
+- **Что считается ошибкой авторизации** (`isBXRestAuthError`): ответ с ошибкой Bitrix `expired_token` или `invalid_token` — при любом HTTP-статусе; ответ 401 без тела ошибки Bitrix — например, пустой 401 от бэкенд-прокси, у которого нет действующего токена. Остальные системные ошибки Bitrix тоже приходят со статусом 401 (`insufficient_scope`, `NO_AUTH_FOUND`, `ACCESS_DENIED`, `INVALID_CREDENTIALS`, `user_access_error`, `OVERLOAD_LIMIT`), но новый токен их не исправит — они не повторяются.
+- **Один повтор.** Если и повтор упал — наружу уходит его ошибка, второго продления не будет.
+- **Одно продление на всех.** Если одновременно упало несколько запросов, `refresh()` вызывается один раз, а повторяются все. Запрос, который был в пути, пока токен продлевали, повторяется без нового продления.
+- **Продление упало** (`refresh()` отклонил промис или бросил исключение) — наружу уходит исходная ошибка запроса, а причина сбоя продления — в её поле `authRefreshError`. Достать её из любой ошибки — `getAuthRefreshError(err)`:
+
+  ```typescript
+  import { BXRestApiError, getAuthRefreshError } from 'bx-rest'
+
+  bxRest.crm.deal.get({ ID: 1 }).res().subscribe({
+    error: err => {
+      if (err instanceof BXRestApiError && err.error === 'expired_token') {
+        console.error('Авторизацию продлить не удалось:', getAuthRefreshError(err))
+      }
+    }
+  })
+  ```
+
+- **Где работает.** Во всех запросах библиотеки: `.res()`, `.resAll()` (и первая страница, и каждый batch-запрос), `.resVanilla()`, `.mapForVanilla()`, `BXRestRequest.post()`/`.get()`, `BXRest.batch()`. Повтор встроен в HTTP-слой, поэтому `.res()` получает уже результат повтора.
+- **Что не повторяется:** ошибки в теле ответа со статусом 2xx (Bitrix отдаёт `expired_token` со статусом 401) и ошибки отдельных команд внутри успешного batch-ответа (`result_error`) — повторяется HTTP-запрос целиком.
+
+### Токен от портала без BX24.js
+
+Обновить токен по OAuth прямо в браузере нельзя — для этого нужен `client_secret`. Но приложение открыто в iframe портала, пользователь в портале залогинен, и портал сам выдаёт приложению токен по postMessage — так работают `BX24.getAuth()` и `BX24.refreshAuth()`. `BXRestFrame` делает то же самое без подключения BX24.js (остальные команды BX24.js — в разделе [Работа в iframe без BX24.js](#работа-в-iframe-без-bx24js)):
+
+```typescript
+import { BXRestFrame } from 'bx-rest'
+
+const frame = new BXRestFrame()         // необязательно: { timeout: 10000 }
+
+const auth = await frame.getAuth()      // текущая авторизация — как BX24.getAuth()
+const fresh = await frame.refreshAuth() // новая авторизация — как BX24.refreshAuth()
+// { access_token, refresh_token, expires_in, domain, member_id }
+```
+
+| Поле результата | Значение |
+| --- | --- |
+| `access_token`, `refresh_token` | Токены приложения. |
+| `expires_in` | Момент истечения `access_token` — **миллисекунды** с 1 января 1970 года, как у `BX24.getAuth()`. Не срок жизни в секундах, как в ответе OAuth-сервера. |
+| `domain` | Адрес портала без протокола, например `mycompany.bitrix24.ru`. |
+| `member_id` | Постоянный идентификатор портала. |
+
+- **Токены** `BXRestFrame` не логирует и никуда не сохраняет: каждый вызов `getAuth()` и `refreshAuth()` спрашивает портал заново, результат получает ваш код.
+- **Ошибки** — `BXRestFrameError` с полем `code`: `NOT_IN_FRAME` (страница открыта не в iframe приложения — ошибка сразу), `TIMEOUT` (портал не ответил за `timeout`, по умолчанию 10 секунд), `NO_AUTH` (портал ответил без токена), `BAD_RESPONSE` (ответ не удалось разобрать). Если портал не может выдать новый токен (например, у приложения закончился пробный или платный период), он показывает `alert` «Unable to get new token!» и не отвечает вовсе — такой отказ приходит как `TIMEOUT`.
+- **`getAuth()` и срок действия.** Портал отдаёт срок жизни токена на момент выдачи, а не остаток, поэтому `expires_in` от `getAuth()` на давно открытой странице завышен (у BX24.js так же). Для свежего токена используйте `refreshAuth()`.
+- **Домен портала** `BXRestFrame`, как и BX24.js, удостоверить не может — его задаёт тот, кто встроил страницу в iframe. Поэтому токен, пришедший из браузера, сервер должен проверить у портала, прежде чем ему доверять.
+
+### Рецепт: напрямую в портал
+
+Токен хранит фронтенд, запросы идут в `https://<портал>/rest/`. Функция продления берёт новый токен у портала и кладёт его туда, откуда его читает `auth.source` — здесь это переменная в памяти:
+
+```typescript
+import { BXRestSettings, BXRestFrame } from 'bx-rest'
+
+const frame = new BXRestFrame()
+const auth = await frame.getAuth()
+let accessToken = auth.access_token
+
+BXRestSettings.update({
+  auth: {
+    source: () => accessToken,
+    key: 'auth',
+    refresh: async () => {
+      accessToken = (await frame.refreshAuth()).access_token
+    }
+  },
+  urls: {
+    source: 'string',
+    key: `https://${auth.domain}`,
+    additional_part: 'rest'
+  }
+})
+```
+
+С `auth.source: 'localStorage'` функция продления так же записывает токен в `localStorage[auth.key]`.
+
+### Рецепт: через бэкенд-прокси
+
+Токен хранит сервер, браузер авторизуется у прокси cookie-сессией (`auth.source: 'off'`). Прокси без действующего токена отвечает 401 с пустым телом — это ошибка авторизации по умолчанию. Функция продления берёт новый токен у портала и отправляет его на сервер:
+
+```typescript
+import { BXRestSettings, BXRestFrame } from 'bx-rest'
+
+const APP = 'smart-process-pro'
+const frame = new BXRestFrame()
+
+BXRestSettings.update({
+  auth: {
+    source: 'off',
+    key: 'auth',
+    refresh: async () => {
+      const { access_token, refresh_token, expires_in } = await frame.refreshAuth()
+      const response = await fetch(`/api/bitrix/token/${APP}`, {
+        method: 'POST',
+        credentials: 'same-origin',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ access_token, refresh_token, expires_in })
+      })
+      if (!response.ok) {
+        // без тела запроса в сообщении — в нём токены
+        throw new Error(`Token upload failed: HTTP ${response.status}`)
+      }
+    }
+  },
+  urls: {
+    source: 'string',
+    key: '/api/bitrix/rest/',
+    additional_part: '' // иначе к адресу добавится ещё один `rest/`
+  },
+  headers: {
+    'X-Bitrix-App': APP
+  }
+})
+```
+
+Ошибки функции продления попадают в `authRefreshError` исходной ошибки, а `.res()` может вывести исходную ошибку в консоль — поэтому не кладите токены в текст ошибок функции продления.
+
+## Работа в iframe без BX24.js
+
+`BXRestFrame` — команды, которые приложение из iframe отправляет порталу: размер фрейма, диалоги выбора, слайдеры, мессенджер, встраивания, настройки, установка. Те же команды и те же имена, что у BX24.js, но вместо колбэков — промисы, и подключать BX24.js не нужно. REST-запросы делает сама bx-rest, токен для них — `getAuth()`/`refreshAuth()` (см. [Продление авторизации](#продление-авторизации)).
+
+```typescript
+import { BXRestFrame } from 'bx-rest'
+
+const frame = new BXRestFrame()
+
+const { lang, isAdmin, placement } = await frame.init()
+await frame.fitWindow()
+const user = await frame.selectUser()
+const unsubscribe = frame.placement.bindEvent('Tab:onChange', data => console.log(data))
+```
+
+Создавайте один экземпляр на страницу и при старте приложения: параметры портала читаются в конструкторе, а признак первого запуска портал сообщает только в первом ответе за загрузку страницы. По той же причине не используйте `BXRestFrame` и BX24.js на одной странице.
+
+| BX24.js | `BXRestFrame` | Ответ |
+| --- | --- | --- |
+| `BX24.init()`, `isAdmin()`, `getLang()`, `getDomain()` | `init()` — `{ domain, lang, path, https, memberId, isAdmin, install, firstRun, placement, placementOptions, userOptions, appOptions }` | Запрашивается один раз, без токенов |
+| `BX24.getAuth()`, `BX24.refreshAuth()` | `getAuth()`, `refreshAuth()` | Каждый раз у портала |
+| `BX24.installFinish()` | `installFinish()` | Только на странице установщика (`install`); портал перезагружает страницу |
+| конец цепочки `BX24.install()` | `firstRunFinish()` | Отмечает, что первый запуск пройден; без него `firstRun` останется `true` |
+| `BX24.resizeWindow(w, h)`, `BX24.fitWindow()` | `resizeWindow(w, h)`, `fitWindow()` | `{ width, height }` или `undefined` |
+| `BX24.setTitle(title)` | `setTitle(title)` | `{ title }` или `undefined` |
+| `BX24.scrollParentWindow(scroll)` | `scrollParentWindow(scroll)` | `{ scroll }` или `undefined` |
+| `BX24.reloadWindow()` | `reloadWindow()` | Без ответа |
+| `BX24.selectUser()`, `BX24.selectUsers()` | `selectUser({ title?, signal? })`, `selectUsers(...)` | Сотрудник / массив сотрудников |
+| `BX24.selectAccess(value)` | `selectAccess({ value?, signal? })` — `value`: коды, которые нельзя выбрать | Массив `{ provider, id, name }` |
+| `BX24.selectCRM(params)` | `selectCRM({ entityType?, multiple?, value?, signal? })` | Объекты CRM по типам |
+| `BX24.openApplication(params, cb, settings)` | `openApplication(params?, settings?, { signal? })` | Когда слайдер закрыли |
+| `BX24.openPath(path)` | `openPath(path, { signal? })` | `{ result: 'close' }` или `{ result: 'error', errorCode }` |
+| `BX24.closeApplication()` | `closeApplication()` | Без ответа |
+| `BX24.im.callTo/phoneTo/openMessenger/openHistory` | `im.callTo/phoneTo/openMessenger/openHistory` | Без ответа |
+| `BX24.placement.info()` | `placement.info()` | `{ placement, options }` из `init()` |
+| `BX24.placement.getInterface()` | `placement.getInterface()` | `{ command, event }` |
+| `BX24.placement.call(cmd, params)` | `placement.call(cmd, params?, { timeout? })` | Ответ команды или `undefined` |
+| `BX24.placement.bindEvent(event, cb)` | `placement.bindEvent(event, handler)` | `handler` на каждое событие; возвращает функцию отписки |
+| `BX24.userOption.get/set` | `userOption.get/set` | Настройка пользователя |
+| `BX24.appOption.get/set` | `appOption.get/set` | `set` — только администратору, иначе `ACCESS_DENIED` |
+
+Как портал отвечает на команды — от этого зависит, когда завершается промис:
+
+- **С ответом** (`init()`, `getAuth()`, `refreshAuth()`, `placement.getInterface()`, `appOption.set()`) — нет ответа за `timeout` (по умолчанию 10 секунд) — ошибка `TIMEOUT`.
+- **С подтверждением** (`resizeWindow()`, `fitWindow()`, `setTitle()`, `scrollParentWindow()`, `userOption.set()`, `firstRunFinish()`, `placement.call()`) — в некоторых встраиваниях портал на них не отвечает, поэтому без ответа за `timeout` промис завершается с `undefined`, а не ошибкой.
+- **Без ответа** (`reloadWindow()`, `closeApplication()`, `installFinish()`, `im.*`) — промис завершается сразу после отправки.
+- **Ждут пользователя** (`select*()`, `openApplication()`, `openPath()`) — без ограничения по времени. Если пользователь закрыл диалог, ничего не выбрав, портал не отвечает вовсе. Отменить ожидание можно через `signal` (`AbortController`), а повторный вызов того же диалога отменяет прошлый: портал держит один обработчик на диалог. Отменённое ожидание — ошибка `CANCELLED`.
+
+`placement.bindEvent()` возвращает функцию отписки, но она только перестаёт вызывать `handler`: отменить подписку на стороне портала протокол не позволяет.
+
+- **Где ищет портал.** Как BX24.js — в `window.name`: портал называет iframe приложения `DOMAIN|PROTOCOL|APP_SID`. Если там пусто — в query страницы (`?DOMAIN=…&PROTOCOL=…&APP_SID=…`), с которым портал открывает обработчик приложения.
+- **Безопасность.** Команды уходят только на origin портала (не `'*'`), ответы принимаются только от `window.parent` и только с origin портала.
+- **Ошибки** — `BXRestFrameError` с полем `code`: `NOT_IN_FRAME` (страница открыта не в iframe приложения — ошибка сразу), `TIMEOUT`, `NO_AUTH`, `BAD_RESPONSE`, `CANCELLED`, `ACCESS_DENIED`. Неверные аргументы `resizeWindow()` и `scrollParentWindow()` — `TypeError`.
+
+> **Протокол внутренний и недокументированный.** Обмен сообщениями между приложением и порталом Bitrix24 не описан в документации и может измениться без предупреждения. `BXRestFrame` повторяет BX24.js — `https://api.bitrix24.com/api/v1/`, скачан 2026-10-29, `Last-Modified: 2022-03-17`, SHA-256 `945ad491df8ffb7490b89f4914a439b5a3f575c950c3480562815716a3e07f23` — и сверен с ответной стороной портала, `/bitrix/js/rest/applayout.js` (`Last-Modified: 2024-05-15`, SHA-256 `3efd6ab57a4778493a26d10ae0987a82e19fc012ed9935f5c6afa78c4052fcb5`) и с документацией BX24.js. Проверен на поддельном портале в тестах, но не на живом портале.
+
 ## Использование в Angular
 
 Зарегистрируйте публичные клиенты и `Navvy`, когда нужно внедрять их в сервисы или компоненты Angular: