bx-rest 1.3.0 → 1.4.0

package/fesm2022/bx-rest.mjs

@@ -1,5 +1,5 @@
-import { switchMap, map, catchError, take, mergeMap as mergeMap$1 } from 'rxjs/operators';
-import { Subscription, of, throwError, from, forkJoin, defer, last, shareReplay, mergeMap, concatMap, toArray, map as map$1, tap } from 'rxjs';
+import { switchMap, catchError, map, take, mergeMap as mergeMap$1 } from 'rxjs/operators';
+import { Subscription, of, throwError, from, defer, forkJoin, last, shareReplay, mergeMap, concatMap, toArray, map as map$1, tap } from 'rxjs';
 import clone from 'just-clone';
 import axios from 'axios';
 import flatten from 'just-flatten-it';
@@ -930,6 +930,178 @@ function serializeBitrixParams(params) {
     return stringify(params, BITRIX_STRINGIFY_OPTIONS);
 }
 
+/**
+ * Why `BXRestSettings.auth.refresh` failed. When a request fails with an
+ * authorization error and the refresh fails too, the library rethrows the
+ * original request error and puts the refresh failure into its
+ * `authRefreshError` field — on the `AxiosError` of `.resVanilla()` and the
+ * like, and on the `BXRestApiError` / `Error` of `.res()`.
+ *
+ * Returns `undefined` when there was no refresh or it succeeded.
+ */
+function getAuthRefreshError(error) {
+    return (error && typeof error === 'object')
+        ? error.authRefreshError
+        : undefined;
+}
+/**
+ * A Bitrix-level API error, e.g. `INSUFFICIENT_SCOPE` or `expired_token`.
+ *
+ * `.res()` fails with it whenever the portal answers with a Bitrix error and
+ * a non-2xx HTTP status — which is how Bitrix sends most of its errors. When
+ * the error comes in the body of a 2xx response, `.res()` resolves as
+ * `undefined` by default and fails with it only with
+ * `{ throwOnApiError: true }` — see the "Error handling" section of the README.
+ */
+class BXRestApiError extends Error {
+    constructor(error, error_description, details) {
+        super(error_description || error || 'Bitrix API error', details?.cause !== undefined ? { cause: details.cause } : undefined);
+        this.error = error;
+        this.error_description = error_description;
+        this.name = 'BXRestApiError';
+        this.status = details?.status;
+        this.method = details?.method;
+        this.authRefreshError = details?.authRefreshError;
+    }
+}
+/**
+ * Recognises a Bitrix error body: REST v2 `{ error, error_description }` and
+ * REST v3 `{ error: { code, message } }`. Returns `undefined` for anything
+ * else — a success payload, an HTML page from a proxy, an empty body.
+ *
+ * An empty `error` still counts: Bitrix answers e.g. `crm.deal.get` for a
+ * missing ID with `{ error: '', error_description: 'Not found' }`.
+ */
+function parseBXRestErrorBody(body) {
+    if (!body || typeof body !== 'object' || !('error' in body)) {
+        return undefined;
+    }
+    const { error, error_description } = body;
+    if (typeof error === 'string') {
+        return {
+            error,
+            error_description: typeof error_description === 'string' ? error_description : undefined
+        };
+    }
+    if (error && typeof error === 'object' && 'code' in error) {
+        const { code, message } = error;
+        return {
+            error: String(code),
+            error_description: typeof message === 'string' ? message : undefined
+        };
+    }
+    return undefined;
+}
+/**
+ * Turns an HTTP failure into a `BXRestApiError` when the portal answered with
+ * a Bitrix error body. Bitrix sends most errors with a non-2xx status
+ * (401 `expired_token`, 404 `ERROR_METHOD_NOT_FOUND`, 503
+ * `QUERY_LIMIT_EXCEEDED`, 400 "Not found" from `crm.*.get`, ...), and axios
+ * rejects on those.
+ *
+ * Returns `undefined` for network errors and for responses that are not a
+ * Bitrix error body, so the caller can keep its own handling for them.
+ */
+function bxRestApiErrorFromHttp(err, method) {
+    if (!axios.isAxiosError(err) || !err.response) {
+        return undefined;
+    }
+    const parsed = parseBXRestErrorBody(err.response.data);
+    if (!parsed) {
+        return undefined;
+    }
+    return new BXRestApiError(parsed.error, parsed.error_description, {
+        status: err.response.status,
+        method,
+        cause: err,
+        authRefreshError: getAuthRefreshError(err)
+    });
+}
+
+/**
+ * Коды ошибок Bitrix, которые лечатся продлением токена. `expired_token` —
+ * единственный системный код, для которого документация Bitrix24 советует
+ * "обновить токены и повторить вызов". `invalid_token` в списке системных
+ * ошибок документации нет, но так же считает официальный `@bitrix24/b24jssdk`.
+ *
+ * Остальные системные ошибки тоже приходят со статусом 401
+ * (`insufficient_scope`, `NO_AUTH_FOUND`, `ACCESS_DENIED`,
+ * `INVALID_CREDENTIALS`, `user_access_error`, ...), но новый токен их
+ * не исправит — поэтому смотрим на код, а не только на статус.
+ */
+const AUTH_ERROR_CODES = ['expired_token', 'invalid_token'];
+/**
+ * Условие продления по умолчанию (`BXRestSettings.auth.isAuthError`):
+ * - ответ с ошибкой Bitrix `expired_token` или `invalid_token` — при любом статусе;
+ * - ответ 401 без тела ошибки Bitrix — например, пустой ответ своего
+ *   бэкенд-прокси, у которого нет действующего токена.
+ *
+ * Ответ 401 с другим кодом Bitrix ошибкой авторизации не считается.
+ */
+function isBXRestAuthError(error) {
+    if (!axios.isAxiosError(error) || !error.response) {
+        return false;
+    }
+    const parsed = parseBXRestErrorBody(error.response.data);
+    if (parsed) {
+        return AUTH_ERROR_CODES.includes(parsed.error);
+    }
+    return error.response.status === 401;
+}
+// Общее на всю библиотеку состояние продления — как и сами BXRestSettings.
+// pendingRefresh — идущее сейчас продление, его ждут все упавшие запросы;
+// refreshCount — сколько продлений уже завершилось успешно.
+let pendingRefresh;
+let refreshCount = 0;
+function sharedRefresh(refresh) {
+    if (!pendingRefresh) {
+        pendingRefresh = Promise.resolve()
+            // Через then, чтобы синхронное исключение в refresh() тоже стало
+            // отклонённым промисом, а не вылетело из catchError
+            .then(() => refresh())
+            .then(() => {
+            refreshCount++;
+        })
+            .finally(() => {
+            pendingRefresh = undefined;
+        });
+    }
+    return pendingRefresh;
+}
+/**
+ * Повтор запроса после продления авторизации (`BXRestSettings.auth.refresh`).
+ *
+ * `request$` должен быть "холодным" и читать настройки при подписке (как
+ * `defer()` в HttpBXServices): повтор — это повторная подписка, поэтому
+ * токен, адрес и заголовки берутся уже новые. На второй попытке ошибка не
+ * перехватывается — запрос повторяется не больше одного раза.
+ */
+function withAuthRefresh(request$) {
+    return defer(() => {
+        const { refresh, isAuthError = isBXRestAuthError } = BXRestSettings.value.auth;
+        if (!refresh) {
+            return request$;
+        }
+        const refreshCountAtStart = refreshCount;
+        return request$.pipe(catchError((error) => {
+            if (!isAuthError(error)) {
+                return throwError(() => error);
+            }
+            // Пока этот запрос был в пути, токен уже продлили по ошибке другого
+            // запроса — повторяем без нового продления
+            const refreshed = (refreshCount !== refreshCountAtStart)
+                ? Promise.resolve()
+                : sharedRefresh(refresh);
+            return from(refreshed).pipe(catchError((refreshError) => {
+                if (error && typeof error === 'object') {
+                    error.authRefreshError = refreshError;
+                }
+                return throwError(() => error);
+            }), switchMap(() => request$));
+        }));
+    });
+}
+
 class HttpBXServices extends HttpServices {
     /**
      * Не считайте этот метод образцом/финальным API.
@@ -1002,7 +1174,13 @@ class HttpBXServices extends HttpServices {
         // геттером в SessionKeyServices настройки читались бы в момент вызова
         // .res(), а не в момент subscribe()/firstValueFrom(), что и обещано
         // в README как поведение "ленивого" REST-вызова.
-        return defer(() => {
+        //
+        // withAuthRefresh() повторяет запрос после BXRestSettings.auth.refresh —
+        // повторной подпиской на этот же defer(), поэтому повтор заново читает
+        // токен, адрес и заголовки. Через httpPost/httpGet идут все запросы
+        // библиотеки (post/get, batch, все виды Navvy-запросов), так что повтор
+        // встроен только здесь.
+        return withAuthRefresh(defer(() => {
             const paramsClone = clone(params);
             const key = this.session.getKeyAuth();
             const auth = this.session.getAuthParams();
@@ -1032,14 +1210,15 @@ class HttpBXServices extends HttpServices {
                     headers: this.buildHeaders(headers, { 'Content-Type': 'application/json' }),
                 }).then((response) => response.data));
             }));
-        });
+        }));
     }
     httpGet(url, params = {}, settings, headers) {
         // Та же причина, что и у httpPost выше: откладываем чтение BXRestSettings
         // до подписки, чтобы `get()` вёл себя так же "лениво", как и `post()`
         // (симметрия, которой не было до этого — GET резолвил настройки в момент
-        // вызова, а не в момент subscribe()).
-        return defer(() => {
+        // вызова, а не в момент subscribe()). Повтор после продления
+        // авторизации — как в httpPost.
+        return withAuthRefresh(defer(() => {
             const paramsClone = clone(params);
             const auth = this.session.getAuthParams();
             const checkIsOn = this.session.getCheckAuthParamsIsOn();
@@ -1060,7 +1239,7 @@ class HttpBXServices extends HttpServices {
                     headers: this.buildHeaders(headers),
                 }).then((response) => response.data));
             }));
-        });
+        }));
     }
     /**
      * Заголовки запроса: `BXRestSettings.headers`, поверх них — заголовки
@@ -1079,78 +1258,6 @@ class HttpBXServices extends HttpServices {
     }
 }
 
-/**
- * A Bitrix-level API error, e.g. `INSUFFICIENT_SCOPE` or `expired_token`.
- *
- * `.res()` fails with it whenever the portal answers with a Bitrix error and
- * a non-2xx HTTP status — which is how Bitrix sends most of its errors. When
- * the error comes in the body of a 2xx response, `.res()` resolves as
- * `undefined` by default and fails with it only with
- * `{ throwOnApiError: true }` — see the "Error handling" section of the README.
- */
-class BXRestApiError extends Error {
-    constructor(error, error_description, details) {
-        super(error_description || error || 'Bitrix API error', details?.cause !== undefined ? { cause: details.cause } : undefined);
-        this.error = error;
-        this.error_description = error_description;
-        this.name = 'BXRestApiError';
-        this.status = details?.status;
-        this.method = details?.method;
-    }
-}
-/**
- * Recognises a Bitrix error body: REST v2 `{ error, error_description }` and
- * REST v3 `{ error: { code, message } }`. Returns `undefined` for anything
- * else — a success payload, an HTML page from a proxy, an empty body.
- *
- * An empty `error` still counts: Bitrix answers e.g. `crm.deal.get` for a
- * missing ID with `{ error: '', error_description: 'Not found' }`.
- */
-function parseBXRestErrorBody(body) {
-    if (!body || typeof body !== 'object' || !('error' in body)) {
-        return undefined;
-    }
-    const { error, error_description } = body;
-    if (typeof error === 'string') {
-        return {
-            error,
-            error_description: typeof error_description === 'string' ? error_description : undefined
-        };
-    }
-    if (error && typeof error === 'object' && 'code' in error) {
-        const { code, message } = error;
-        return {
-            error: String(code),
-            error_description: typeof message === 'string' ? message : undefined
-        };
-    }
-    return undefined;
-}
-/**
- * Turns an HTTP failure into a `BXRestApiError` when the portal answered with
- * a Bitrix error body. Bitrix sends most errors with a non-2xx status
- * (401 `expired_token`, 404 `ERROR_METHOD_NOT_FOUND`, 503
- * `QUERY_LIMIT_EXCEEDED`, 400 "Not found" from `crm.*.get`, ...), and axios
- * rejects on those.
- *
- * Returns `undefined` for network errors and for responses that are not a
- * Bitrix error body, so the caller can keep its own handling for them.
- */
-function bxRestApiErrorFromHttp(err, method) {
-    if (!axios.isAxiosError(err) || !err.response) {
-        return undefined;
-    }
-    const parsed = parseBXRestErrorBody(err.response.data);
-    if (!parsed) {
-        return undefined;
-    }
-    return new BXRestApiError(parsed.error, parsed.error_description, {
-        status: err.response.status,
-        method,
-        cause: err
-    });
-}
-
 class NavvyPagBase {
     constructor(url, param, map = undefined, restApi = false) {
         this.url = url;
@@ -1212,7 +1319,15 @@ class NavvyPagBase {
             if (apiError) {
                 throw apiError;
             }
-            throw new Error((err.error) ? err.error : err);
+            // Сообщение прежнее, но исходная ошибка остаётся в cause — без неё
+            // терялся HTTP-статус ответа не от Bitrix (например, пустого 401 от
+            // бэкенд-прокси): он был только в тексте сообщения.
+            const error = new Error((err.error) ? err.error : err, { cause: err });
+            const authRefreshError = getAuthRefreshError(err);
+            if (authRefreshError !== undefined) {
+                Object.assign(error, { authRefreshError });
+            }
+            throw error;
         }));
     }
 }
@@ -20231,6 +20346,576 @@ class BXRestMap {
     }
 }
 
+/**
+ * Обмен сообщениями между iframe приложения и порталом Bitrix24 — тот
+ * транспорт, на котором построены команды BX24.js: страница приложения шлёт
+ * команду родительскому окну портала через postMessage, портал отвечает
+ * сообщением с тем же callbackId.
+ *
+ * ВНИМАНИЕ: протокол внутренний и недокументированный — Bitrix24 может
+ * изменить его без предупреждения. Транспорт повторяет BX24.js
+ * (https://api.bitrix24.com/api/v1/, скачан 2026-10-29, Last-Modified
+ * 2022-03-17, sha256 945ad491df8ffb7490b89f4914a439b5a3f575c950c3480562815716a3e07f23)
+ * и сверен с ответной стороной портала — `/bitrix/js/rest/applayout.js`
+ * (Last-Modified 2024-05-15, sha256 3efd6ab57a4778493a26d10ae0987a82e19fc012ed9935f5c6afa78c4052fcb5).
+ * Всё знание о протоколе — только в этом модуле (`services/frame`).
+ */
+/**
+ * Ошибка обращения к порталу из iframe. `code`:
+ * - `NOT_IN_FRAME` — страница открыта не в iframe приложения Bitrix24;
+ * - `TIMEOUT` — портал не ответил за отведённое время;
+ * - `NO_AUTH` — портал ответил без токена;
+ * - `BAD_RESPONSE` — ответ портала не удалось разобрать;
+ * - `CANCELLED` — ожидание отменено через `signal` или новым вызовом того же диалога;
+ * - `ACCESS_DENIED` — команда доступна только администратору портала.
+ */
+class BXRestFrameError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'BXRestFrameError';
+    }
+}
+/**
+ * Параметры портала (DOMAIN, PROTOCOL, APP_SID) читаются в конструкторе —
+ * так же, как это делает BX24.js, из `window.name`: портал задаёт имя
+ * iframe приложения в виде `DOMAIN|PROTOCOL|APP_SID`. Если там их нет —
+ * из query страницы (`?DOMAIN=…&PROTOCOL=…&APP_SID=…`), с которым портал
+ * открывает обработчик приложения. Конструктор не бросает исключений:
+ * вне iframe ошибку вернут сами команды.
+ */
+class FrameTransport {
+    constructor() {
+        this.frame = readPortalFrame();
+    }
+    /** Домен портала из параметров фрейма — как `BX24.getDomain()`. */
+    get domain() {
+        return this.frame?.domain ?? '';
+    }
+    /**
+     * Команда, на которую портал не отвечает (`reloadWindow`, `imCallTo`, ...).
+     * Вне iframe бросает `BXRestFrameError` с кодом `NOT_IN_FRAME`.
+     */
+    post(command, params) {
+        this.send(this.requireFrame(), command, params, '');
+    }
+    /** Команда с одним ответом портала. */
+    request(command, params, options) {
+        return new Promise((resolve, reject) => {
+            let frame;
+            try {
+                frame = this.requireFrame();
+            }
+            catch (error) {
+                reject(error);
+                return;
+            }
+            const { timeout, onTimeout = 'reject', signal } = options;
+            if (signal?.aborted) {
+                reject(cancelled(command));
+                return;
+            }
+            const callbackId = uniqId();
+            let timer;
+            const finish = () => {
+                clearTimeout(timer);
+                stopListening();
+                signal?.removeEventListener('abort', onAbort);
+            };
+            const onAbort = () => {
+                finish();
+                reject(cancelled(command));
+            };
+            const stopListening = this.listen(frame, callbackId, payload => {
+                finish();
+                const answer = parsePayload(payload);
+                if (answer.ok) {
+                    resolve(answer.value);
+                }
+                else {
+                    // В тексте ошибки — только команда, без тела ответа: в нём бывают токены
+                    reject(new BXRestFrameError('BAD_RESPONSE', `Bitrix24 answered ${command} with a payload that is not JSON.`));
+                }
+            });
+            if (timeout !== false) {
+                timer = setTimeout(() => {
+                    finish();
+                    if (onTimeout === 'resolve') {
+                        resolve(undefined);
+                    }
+                    else {
+                        reject(new BXRestFrameError('TIMEOUT', [
+                            `Bitrix24 did not answer ${command} within ${timeout} ms:`,
+                            'the page is not opened inside a Bitrix24 portal iframe, or the portal could not process the command.'
+                        ].join(' ')));
+                    }
+                }, timeout);
+            }
+            signal?.addEventListener('abort', onAbort, { once: true });
+            this.send(frame, command, params, callbackId);
+        });
+    }
+    /**
+     * Команда, на которую портал отвечает многократно (`placementBindEvent`):
+     * `handler` вызывается на каждый ответ. Возвращает функцию отписки —
+     * она только перестаёт слушать: отменить подписку на стороне портала
+     * протокол не позволяет. Вне iframe бросает `BXRestFrameError`.
+     */
+    subscribe(command, params, handler) {
+        const frame = this.requireFrame();
+        const callbackId = uniqId();
+        const stopListening = this.listen(frame, callbackId, payload => {
+            const answer = parsePayload(payload);
+            if (answer.ok) {
+                handler(answer.value);
+            }
+        });
+        this.send(frame, command, params, callbackId);
+        return stopListening;
+    }
+    requireFrame() {
+        if (!this.frame) {
+            throw new BXRestFrameError('NOT_IN_FRAME', 'Bitrix24 frame parameters (DOMAIN, APP_SID) were not found in window.name or in the URL query: '
+                + 'the page is not opened as a Bitrix24 application.');
+        }
+        if (window.parent === window) {
+            throw new BXRestFrameError('NOT_IN_FRAME', 'The page is not opened inside an iframe, so there is no Bitrix24 portal to send commands to.');
+        }
+        return this.frame;
+    }
+    /**
+     * Формат — как у BX24.js. Обычно строка `команда:параметры:callbackId:APP_SID`
+     * (портал разбирает её с конца, поэтому параметры и callbackId могут быть
+     * пустыми); для команд с `:` в имени — объект.
+     */
+    send(frame, command, params, callbackId) {
+        const message = command.includes(':')
+            ? { method: command, params: params ? params : '', callback: callbackId, appSid: frame.appSid }
+            : `${command}:${params ? JSON.stringify(params) : ''}:${callbackId}:${frame.appSid}`;
+        window.parent.postMessage(message, frame.origin);
+    }
+    /** Ответ портала — строка `callbackId:JSON` (или `callbackId:`, если ответ пустой). */
+    listen(frame, callbackId, onAnswer) {
+        const portalWindow = window.parent;
+        const onMessage = (event) => {
+            // Ответ принимаем только от родительского окна и только с origin
+            // портала — BX24.js проверяет лишь origin
+            if (event.source !== portalWindow || event.origin !== frame.origin || typeof event.data !== 'string') {
+                return;
+            }
+            const separator = event.data.indexOf(':');
+            const id = separator < 0 ? event.data : event.data.slice(0, separator);
+            if (id === callbackId) {
+                onAnswer(separator < 0 ? '' : event.data.slice(separator + 1));
+            }
+        };
+        window.addEventListener('message', onMessage);
+        return () => window.removeEventListener('message', onMessage);
+    }
+}
+function parsePayload(payload) {
+    if (payload === '') {
+        return { ok: true, value: undefined };
+    }
+    try {
+        return { ok: true, value: JSON.parse(payload) };
+    }
+    catch {
+        return { ok: false };
+    }
+}
+function cancelled(command) {
+    return new BXRestFrameError('CANCELLED', `Waiting for the Bitrix24 answer to ${command} was cancelled.`);
+}
+function readPortalFrame() {
+    if (typeof window === 'undefined') {
+        return undefined;
+    }
+    // BX24.js: window.name = 'DOMAIN|PROTOCOL|APP_SID'
+    const [nameDomain, nameProtocol, nameAppSid] = (typeof window.name === 'string' ? window.name : '').split('|');
+    const fromName = toPortalFrame(nameDomain, nameProtocol, nameAppSid);
+    if (fromName) {
+        return fromName;
+    }
+    try {
+        const query = new URLSearchParams(window.location?.search ?? '');
+        return toPortalFrame(query.get('DOMAIN'), query.get('PROTOCOL'), query.get('APP_SID'));
+    }
+    catch {
+        return undefined;
+    }
+}
+function toPortalFrame(rawDomain, rawProtocol, appSid) {
+    // Как BX24.js: порт по умолчанию отрезается, PROTOCOL 1 — https
+    const domain = (rawDomain ?? '').replace(/:(80|443)$/, '');
+    if (!domain || !appSid) {
+        return undefined;
+    }
+    const protocol = (Number.parseInt(rawProtocol ?? '', 10) || 0) ? 'https' : 'http';
+    try {
+        const url = new URL(`${protocol}://${domain}`);
+        // В DOMAIN должен быть только хост (и порт) — никаких путей и логинов
+        if (url.host !== domain.toLowerCase() || url.username || url.password) {
+            return undefined;
+        }
+        return { domain, origin: url.origin, appSid };
+    }
+    catch {
+        return undefined;
+    }
+}
+function uniqId() {
+    const bytes = new Uint8Array(16);
+    globalThis.crypto.getRandomValues(bytes);
+    return Array.from(bytes, byte => byte.toString(16).padStart(2, '0')).join('');
+}
+
+const DEFAULT_TIMEOUT = 10000;
+/**
+ * Команды порталу Bitrix24 из iframe приложения — без подключения BX24.js.
+ * Те же команды и те же имена, что у BX24.js, но вместо колбэков —
+ * промисы. Протокол внутренний и недокументированный, см. `transport.ts`.
+ *
+ * Создавайте один экземпляр на страницу и при старте приложения: параметры
+ * портала читаются в конструкторе (до того, как роутер перепишет адрес), а
+ * `firstRun` портал сообщает только в первом ответе на `getInitData`.
+ *
+ * Токены класс не логирует и никуда не сохраняет: `getAuth()` и
+ * `refreshAuth()` каждый раз спрашивают портал, а в `init()` токенов нет.
+ *
+ * @example
+ * const frame = new BXRestFrame()
+ * const { lang, placement } = await frame.init()
+ * await frame.fitWindow()
+ * const user = await frame.selectUser()
+ */
+class BXRestFrame {
+    constructor(options = {}) {
+        this.transport = new FrameTransport();
+        // Открытый диалог каждого вида — новый вызов того же диалога отменяет прошлый
+        this.dialogs = new Map();
+        /** Мессенджер — как `BX24.im`. Портал на эти команды не отвечает. */
+        this.im = {
+            /** Позвонить сотруднику — `BX24.im.callTo()`. */
+            callTo: async (userId, video) => {
+                this.transport.post('imCallTo', { userId, video });
+            },
+            /** Позвонить на телефон — `BX24.im.phoneTo()`. */
+            phoneTo: async (phone) => {
+                this.transport.post('imPhoneTo', { phone });
+            },
+            /** Открыть чат — `BX24.im.openMessenger()`. */
+            openMessenger: async (dialogId) => {
+                this.transport.post('imOpenMessenger', { dialogId });
+            },
+            /** Открыть историю чата — `BX24.im.openHistory()`. */
+            openHistory: async (dialogId) => {
+                this.transport.post('imOpenHistory', { dialogId });
+            },
+        };
+        /** Встраивание — как `BX24.placement`. */
+        this.placement = {
+            /** Код и параметры встраивания — `BX24.placement.info()`. */
+            info: async () => {
+                const { placement, placementOptions } = await this.init();
+                return { placement, options: placementOptions };
+            },
+            /** Команды и события текущего встраивания — `BX24.placement.getInterface()`. */
+            getInterface: async () => {
+                return await this.transport.request('getInterface', null, { timeout: this.timeout });
+            },
+            /**
+             * Команда встраивания — `BX24.placement.call()`. Набор команд зависит от
+             * встраивания (см. `getInterface()`). Не на все команды портал отвечает:
+             * без ответа за `timeout` промис завершается с `undefined`.
+             */
+            call: async (command, params, options = {}) => {
+                return this.transport.request(command, params, {
+                    timeout: options.timeout ?? this.timeout,
+                    onTimeout: 'resolve',
+                });
+            },
+            /**
+             * Подписка на событие встраивания — `BX24.placement.bindEvent()`.
+             * `handler` вызывается при каждом событии. Возвращает функцию отписки:
+             * она только перестаёт вызывать `handler` — отменить подписку на
+             * стороне портала протокол не позволяет. Вне iframe бросает
+             * `BXRestFrameError` с кодом `NOT_IN_FRAME`.
+             */
+            bindEvent: (event, handler) => {
+                return this.transport.subscribe('placementBindEvent', { event }, handler);
+            },
+        };
+        /** Настройки приложения для текущего пользователя — как `BX24.userOption`. */
+        this.userOption = {
+            get: async (name) => (await this.init()).userOptions[name],
+            set: async (name, value) => {
+                const init = await this.init();
+                init.userOptions[name] = value;
+                await this.ack('setUserOption', { name, value });
+            },
+        };
+        /** Настройки приложения для всего портала — как `BX24.appOption`. */
+        this.appOption = {
+            get: async (name) => (await this.init()).appOptions[name],
+            /**
+             * Менять их может только администратор портала: остальным — ошибка
+             * `ACCESS_DENIED` (BX24.js в этом случае молча ничего не делает).
+             * Возвращает настройки приложения после сохранения.
+             */
+            set: async (name, value) => {
+                const init = await this.init();
+                if (!init.isAdmin) {
+                    throw new BXRestFrameError('ACCESS_DENIED', 'Only a Bitrix24 administrator can change application options.');
+                }
+                init.appOptions[name] = value;
+                return await this.transport.request('setAppOption', { name, value }, { timeout: this.timeout });
+            },
+        };
+        this.timeout = options.timeout ?? DEFAULT_TIMEOUT;
+    }
+    /**
+     * Данные запуска приложения — аналог `BX24.init()`: язык, домен, права,
+     * встраивание, настройки, признаки установки. Запрашиваются у портала
+     * один раз, дальше берутся из памяти. Токенов здесь нет — см. `getAuth()`.
+     */
+    init() {
+        if (this.initValue) {
+            return Promise.resolve(this.initValue);
+        }
+        if (!this.initRequest) {
+            this.initRequest = this.getInitData()
+                .then(() => this.initValue)
+                .finally(() => {
+                this.initRequest = undefined;
+            });
+        }
+        return this.initRequest;
+    }
+    /**
+     * Текущая авторизация приложения — аналог `BX24.getAuth()`. Каждый вызов —
+     * новый запрос `getInitData` к порталу.
+     *
+     * `expires_in` портал считает от срока жизни токена в момент выдачи, а не
+     * от остатка: если страница открыта давно, значение будет завышено (так
+     * же и у BX24.js). Для свежего токена используйте `refreshAuth()`.
+     */
+    async getAuth() {
+        const data = await this.getInitData();
+        return this.toAuth('getInitData', data, String(data['MEMBER_ID'] || ''));
+    }
+    /**
+     * Новая авторизация приложения — аналог `BX24.refreshAuth()`: портал
+     * выпускает новую пару `access_token`/`refresh_token`. Если портал не может
+     * выдать токен, он показывает `alert` «Unable to get new token!» и не
+     * отвечает — тогда ошибка `TIMEOUT`.
+     */
+    async refreshAuth() {
+        // member_id приходит только в getInitData — refreshAuth его не возвращает
+        const { memberId } = await this.init();
+        const data = asObject('refreshAuth', await this.transport.request('refreshAuth', {}, { timeout: this.timeout }));
+        return this.toAuth('refreshAuth', data, memberId);
+    }
+    /**
+     * Завершить установку — аналог `BX24.installFinish()`: портал отмечает
+     * приложение установленным и перезагружает страницу. Делает что-то только
+     * на странице установщика (`init().install`), иначе — ничего, как и BX24.js.
+     */
+    async installFinish() {
+        if ((await this.init()).install) {
+            this.transport.post('setInstallFinish', {});
+        }
+    }
+    /**
+     * Отметить, что первый запуск у этого пользователя пройден, — то, что
+     * BX24.js делает после последнего обработчика `BX24.install()`. Без этого
+     * `init().firstRun` останется `true` и при следующих запусках. Делает
+     * что-то только при первом запуске.
+     */
+    async firstRunFinish() {
+        const init = await this.init();
+        if (init.firstRun) {
+            await this.ack('setInstall', { install: true });
+            init.firstRun = false;
+        }
+    }
+    /** Задать размер фрейма — `BX24.resizeWindow()`. Возвращает размер, который выставил портал. */
+    async resizeWindow(width, height) {
+        const w = Number.parseInt(String(width), 10);
+        const h = Number.parseInt(String(height), 10);
+        if (!(w > 0 && h > 0)) {
+            throw new TypeError('resizeWindow: width and height must be positive numbers.');
+        }
+        return await this.ack('resizeWindow', { width: w, height: h });
+    }
+    /** Подогнать высоту фрейма под содержимое — `BX24.fitWindow()`. */
+    async fitWindow() {
+        const root = document.documentElement;
+        const height = Math.max(root.scrollHeight, root.offsetHeight);
+        return await this.ack('resizeWindow', { width: '100%', height });
+    }
+    /**
+     * Перезагрузить страницу портала с приложением — `BX24.reloadWindow()`.
+     * Портал на эту команду не отвечает.
+     */
+    async reloadWindow() {
+        this.transport.post('reloadWindow', {});
+    }
+    /** Заголовок страницы портала — `BX24.setTitle()`. */
+    async setTitle(title) {
+        return await this.ack('setTitle', { title: String(title) });
+    }
+    /** Прокрутить страницу портала — `BX24.scrollParentWindow()`. */
+    async scrollParentWindow(scroll) {
+        const value = Number.parseInt(String(scroll), 10);
+        if (Number.isNaN(value)) {
+            throw new TypeError('scrollParentWindow: scroll must be a number.');
+        }
+        return await this.ack('setScroll', { scroll: value });
+    }
+    /**
+     * Диалог выбора одного сотрудника — `BX24.selectUser()`. Ждёт выбора без
+     * ограничения по времени: если пользователь закрыл диалог, портал не
+     * отвечает вовсе. Отменить ожидание — `signal` или новый вызов
+     * `selectUser()`/`selectUsers()` (ошибка `CANCELLED`).
+     */
+    selectUser(options = {}) {
+        return this.dialog('user', 'selectUser', { title: options.title ?? '', mult: false }, options.signal);
+    }
+    /** Диалог выбора нескольких сотрудников — `BX24.selectUsers()`. Ожидание — как у `selectUser()`. */
+    selectUsers(options = {}) {
+        return this.dialog('user', 'selectUser', { title: options.title ?? '', mult: true }, options.signal);
+    }
+    /**
+     * Диалог выбора прав доступа — `BX24.selectAccess()`. `value` — коды,
+     * которые нельзя выбрать. Ожидание — как у `selectUser()`.
+     */
+    selectAccess(options = {}) {
+        return this.dialog('access', 'selectAccess', { value: options.value ?? [] }, options.signal);
+    }
+    /** Диалог выбора объектов CRM — `BX24.selectCRM()`. Ожидание — как у `selectUser()`. */
+    selectCRM(options = {}) {
+        const { entityType, multiple, value, signal } = options;
+        return this.dialog('crm', 'selectCRM', { entityType, multiple, value }, signal);
+    }
+    /**
+     * Открыть приложение в слайдере — `BX24.openApplication()`. Промис
+     * завершается, когда слайдер закрыли. `settings` — настройки слайдера
+     * (уходят как `bx24_<ключ>`, как в BX24.js).
+     */
+    async openApplication(params = {}, settings = {}, options = {}) {
+        const message = { ...params };
+        for (const [key, value] of Object.entries(settings)) {
+            message[`bx24_${key}`] = value;
+        }
+        await this.transport.request('openApplication', message, { timeout: false, signal: options.signal });
+    }
+    /**
+     * Открыть страницу портала в слайдере — `BX24.openPath()`. Промис
+     * завершается, когда слайдер закрыли (`{ result: 'close' }`), или сразу,
+     * если путь не открылся (`{ result: 'error', errorCode }`).
+     */
+    async openPath(path, options = {}) {
+        return await this.transport.request('openPath', { path }, { timeout: false, signal: options.signal });
+    }
+    /**
+     * Закрыть слайдер с приложением — `BX24.closeApplication()`. Если
+     * приложение открыто не в слайдере, ничего не происходит. Узнать о
+     * закрытии может открывший слайдер — через `openApplication()`.
+     */
+    async closeApplication() {
+        this.transport.post('closeApplication', null);
+    }
+    /**
+     * Команда, на которую портал отвечает подтверждением. В некоторых
+     * встраиваниях портал на такие команды не отвечает (так считает и
+     * b24jssdk) — тогда промис завершается с `undefined`, а не ошибкой.
+     */
+    ack(command, params) {
+        return this.transport.request(command, params, { timeout: this.timeout, onTimeout: 'resolve' });
+    }
+    /**
+     * Диалоги ждут пользователя без таймаута. Портал держит один обработчик
+     * на диалог (у выбора сотрудников он общий для `selectUser` и
+     * `selectUsers`) и на прошлый вызов уже не ответит — поэтому новый вызов
+     * отменяет ожидание прошлого.
+     */
+    dialog(kind, command, params, signal) {
+        this.dialogs.get(kind)?.abort();
+        const controller = new AbortController();
+        this.dialogs.set(kind, controller);
+        const onAbort = () => controller.abort();
+        if (signal?.aborted) {
+            controller.abort();
+        }
+        signal?.addEventListener('abort', onAbort, { once: true });
+        return this.transport.request(command, params, { timeout: false, signal: controller.signal })
+            .finally(() => {
+            signal?.removeEventListener('abort', onAbort);
+            if (this.dialogs.get(kind) === controller) {
+                this.dialogs.delete(kind);
+            }
+        });
+    }
+    async getInitData() {
+        const data = asObject('getInitData', await this.transport.request('getInitData', null, { timeout: this.timeout }));
+        // firstRun портал отдаёт только в первом ответе за загрузку страницы —
+        // поэтому запоминаем данные первого ответа, кто бы его ни запросил
+        if (!this.initValue) {
+            this.initValue = this.toInit(data);
+        }
+        return data;
+    }
+    toInit(data) {
+        return {
+            // Как BX24.js: домен — из параметров фрейма, DOMAIN ответа — запасной
+            domain: this.transport.domain || String(data['DOMAIN'] || ''),
+            lang: String(data['LANG'] || ''),
+            path: String(data['PATH'] || ''),
+            https: Number.parseInt(String(data['PROTOCOL']), 10) === 1,
+            memberId: String(data['MEMBER_ID'] || ''),
+            isAdmin: !!data['IS_ADMIN'],
+            install: !!data['INSTALL'],
+            firstRun: !!data['FIRST_RUN'],
+            placement: String(data['PLACEMENT'] || 'DEFAULT'),
+            placementOptions: data['PLACEMENT_OPTIONS'],
+            userOptions: toRecord(data['USER_OPTIONS']),
+            appOptions: toRecord(data['APP_OPTIONS']),
+        };
+    }
+    toAuth(command, data, memberId) {
+        const { AUTH_ID, REFRESH_ID, AUTH_EXPIRES } = data;
+        if (!AUTH_ID || typeof AUTH_ID !== 'string') {
+            throw new BXRestFrameError('NO_AUTH', `Bitrix24 answered ${command} without an access token.`);
+        }
+        // AUTH_EXPIRES — срок жизни токена в секундах. BX24.js переводит его в
+        // момент истечения в миллисекундах — так же, как здесь.
+        const expiresIn = Number.parseInt(String(AUTH_EXPIRES), 10);
+        if (!Number.isFinite(expiresIn) || expiresIn <= 0) {
+            throw new BXRestFrameError('BAD_RESPONSE', `Bitrix24 answered ${command} without a usable AUTH_EXPIRES.`);
+        }
+        return {
+            access_token: AUTH_ID,
+            refresh_token: typeof REFRESH_ID === 'string' ? REFRESH_ID : '',
+            expires_in: Date.now() + expiresIn * 1000,
+            domain: this.transport.domain,
+            member_id: memberId,
+        };
+    }
+}
+function asObject(command, data) {
+    if (!data || typeof data !== 'object' || Array.isArray(data)) {
+        throw new BXRestFrameError('BAD_RESPONSE', `Bitrix24 answered ${command} with a payload that is not an object.`);
+    }
+    return data;
+}
+// Пустые настройки PHP отдаёт массивом `[]`
+function toRecord(value) {
+    return (value && typeof value === 'object' && !Array.isArray(value))
+        ? { ...value }
+        : {};
+}
+
 /**
  * Public API Surface of bx-rest
  */
@@ -20239,5 +20924,5 @@ class BXRestMap {
  * Generated bundle index. Do not edit.
  */
 
-export { base as BXBaseServices, BXRestApiError, BXRestMap, BXRestMapResult, BXRestNavvy, HttpBXServices as BXRestRequest, BXRestSettings, HttpNavvyServices, Navvy, SessionKeyError, SessionKeyServices, instanceOfiBXRestAnswerSuccess as isBXRestAnswerSuccess, partNameMethods$1 as partNameMethods };
+export { base as BXBaseServices, BXRestApiError, BXRestFrame, BXRestFrameError, BXRestMap, BXRestMapResult, BXRestNavvy, HttpBXServices as BXRestRequest, BXRestSettings, HttpNavvyServices, Navvy, SessionKeyError, SessionKeyServices, getAuthRefreshError, instanceOfiBXRestAnswerSuccess as isBXRestAnswerSuccess, isBXRestAuthError, partNameMethods$1 as partNameMethods };
 //# sourceMappingURL=bx-rest.mjs.map