@andrey4emk/npm-app-back-b24 3.8.2 → 3.9.0

package/bitrix24/b24.ts

@@ -1,411 +1,65 @@
-import { B24OAuth, AjaxError, SdkError, Logger, LogLevel, Result } from "@bitrix24/b24jssdk";
-import type {
-    B24OAuthParams,
-    B24OAuthSecret,
-    AuthData,
-    AjaxResult,
-    TypeCallParams,
-    BatchCommandsArrayUniversal,
-    BatchCommandsObjectUniversal,
-    BatchNamedCommandsUniversal,
-    Handler,
-    LogRecord,
-    Formatter,
-    RestrictionParams,
-} from "@bitrix24/b24jssdk";
-import { logs } from "../logs/logs.ts";
-import { isNetworkError, isPreConnectionError } from "../utils/fetchRetry.ts";
-import Conf from "conf";
-import path from "path";
+import type { B24OAuth } from "@bitrix24/b24jssdk";
 import type { Request, Response } from "express";
+import { logs } from "../logs/logs.ts";
 
-import dotEnv from "dotenv";
-dotEnv.config();
-
-// ==================== Типы ====================
-
-/** Результат операций с токенами */
-interface SaveResult {
-    error: boolean;
-    message: string;
-}
-
-/**
- * `B24OAuth` плюс пять методов, которые пакет реализует сам поверх `actions.v2.*`.
- *
- * SDK 2.x помечает `callMethod`/`callListMethod`/`fetchListMethod`/`callBatch`/`callBatchByChunk`
- * к удалению в следующем major. Пакет предоставляет их сам, поэтому сигнатуры для потребителя
- * не меняются, а зависимости от удаляемого API у нас больше нет.
- *
- * Тип расширяет `B24OAuth`, поэтому `$b24` по-прежнему передаётся туда, где ждут `B24OAuth`
- * (`new Smsgold(auth, $b24)`, `new Event($b24)`).
- */
-export interface B24Client extends B24OAuth {
-    callMethod<T = any>(method: string, params?: object, start?: number): Promise<AjaxResult<T>>;
-    callListMethod(method: string, params?: object, progress?: null | ((progress: number) => void), customKeyForResult?: string | null): Promise<Result>;
-    fetchListMethod(method: string, params?: any, idKey?: string, customKeyForResult?: string | null): AsyncGenerator<any[]>;
-    callBatch(calls: Array<any> | object, isHaltOnError?: boolean, returnAjaxResult?: boolean): Promise<Result>;
-    callBatchByChunk(calls: Array<any>, isHaltOnError: boolean): Promise<Result>;
-}
-
-/**
- * Минимальный контракт «умеет вызывать REST-методы B24».
- *
- * Нужен внутренним классам (`Event`, `Smsgold`), которые принимают экземпляр извне.
- * Объявляет `callMethod` сам, поэтому переживёт удаление метода из `B24OAuth`.
- *
- * Объединение `B24OAuth | B24Client` эту задачу не решает: `B24Client` расширяет
- * `B24OAuth`, union схлопывается в супертип, а вызов метода на union требует его
- * наличия в обеих ветках — то есть после удаления из SDK тайпчек сломается всё равно.
- *
- * Структурный тип шире `B24OAuth`, поэтому публичные сигнатуры конструкторов
- * не сужаются: и `B24OAuth`, и `$b24`, и любой свой объект с `callMethod` подходят.
- */
-export interface B24MethodCaller {
-    // Дженерика здесь быть не должно: у SDK метод не generic, и `B24OAuth`
-    // потребителя перестал бы подходить под этот тип. Проверено тайпчеком
-    callMethod(method: string, params?: object, start?: number): Promise<AjaxResult>;
-}
-
-/** Набор методов фасада — то, что Proxy отдаёт вместо реализаций SDK */
-type FacadeMethods = Pick<B24Client, "callMethod" | "callListMethod" | "fetchListMethod" | "callBatch" | "callBatchByChunk">;
-
-/** Формы списка команд batch, которые принимает actions.v2 */
-type BatchCalls = BatchCommandsArrayUniversal | BatchCommandsObjectUniversal | BatchNamedCommandsUniversal;
-
-// ==================== Константы ====================
-
-const CONFIG_DIR = process.env.CONFIG_DIR || "../config";
-const APP_ENV = process.env.APP_ENV || "PROD";
-const CLIENT_ID = process.env.APP_B24_CLIENT_ID;
-const CLIENT_SECRET = process.env.APP_B24_CLIENT_SECRET;
-
-/** 25 минут при TTL токена 30 минут */
-const PROACTIVE_REFRESH_INTERVAL_MS = 25 * 60 * 1000;
-/** 2 минуты — ускоренный интервал при ошибке обновления */
-const PROACTIVE_RETRY_ON_ERROR_MS = 2 * 60 * 1000;
-
-/** Количество попыток при сетевых ошибках */
-const RETRY_COUNT = 5;
-/** Задержка между попытками (мс) */
-const RETRY_DELAY_MS = 500;
-
-/** Методы фасада, оборачиваемые retry-логикой (fetchListMethod — async-генератор, его оборачивать нельзя) */
-const RETRYABLE_METHODS = new Set(["callMethod", "callListMethod", "callBatch"]);
-
-/**
- * Имена, которые Proxy резолвит в собственную реализацию пакета поверх `actions.v2.*`.
- *
- * Шире, чем RETRYABLE_METHODS: `fetchListMethod` и `callBatchByChunk` мы реализуем,
- * но не ретраим. `callBatchByChunk` в наборе обязателен — пока хоть один deprecated-метод
- * SDK достижим через `$b24`, он будет писать предупреждение об устаревании.
- */
-const FACADE_METHODS = new Set(["callMethod", "callListMethod", "fetchListMethod", "callBatch", "callBatchByChunk"]);
-
-/** Потолок числа страниц в callListMethod — страховка от бесконечной пагинации */
-const LIST_MAX_PAGES = 1000;
-
-/**
- * Коды транспортного сбоя. Один набор и для SdkError (AjaxError, RefreshTokenError),
- * и для вложенного AxiosError — списки совпадали, держать их раздельно смысла нет.
- */
-const NETWORK_ERROR_CODES = new Set(["NETWORK_ERROR", "REQUEST_TIMEOUT", "ERR_NETWORK", "ECONNABORTED"]);
-
-/**
- * REST-методы B24, повтор которых создаёт дубликат сущности или запускает
- * повторное действие: add, create, start, send, uploadfile, import, register.
- *
- * Транспортная ошибка не говорит, дошёл ли запрос до портала: NETWORK_ERROR приходит
- * и когда соединение не состоялось, и когда оно оборвалось после того, как портал уже
- * принял и выполнил запрос. Во втором случае retry создаст вторую задачу, второй файл,
- * второй экземпляр бизнес-процесса. Идемпотентные записи (update, delete, set) повторять
- * безопасно: повторное применение даёт то же состояние.
- *
- * По той же причине у SDK отключены собственные повторы транспортных сбоев
- * (SDK_RESTRICTION_PARAMS) — он этой разницы не знает вовсе.
- */
-const NON_IDEMPOTENT_METHOD_RE = /\.(add|create|start|send|uploadfile|import|register)(\.json)?(\?|$)/i;
-
-/**
- * Параметры ограничителя SDK. Передаются третьим аргументом конструктора B24OAuth
- * и сливаются там с дефолтами `ParamsFactory.getDefault()`.
- *
- * Единый инвариант: **транспортные сбои SDK не повторяет вообще, повторяет только
- * наш слой**, где работает гейт NON_IDEMPOTENT_METHOD_RE. У SDK нет понятия
- * «создающий вызов»: оборванный crm.deal.add он повторил бы трижды и создал три сделки.
- *
- * Одного `retryOnNetworkError: false` для этого мало. Он добавляет в жёсткий список
- * ровно два кода — NETWORK_ERROR и REQUEST_TIMEOUT, — а SDK конвертирует в них только
- * `ERR_NETWORK` и `ECONNABORTED`. Остальные транспортные ошибки Node доезжают до
- * лимитера под своим кодом (`ECONNRESET` при обрыве сокета, `ERR_BAD_RESPONSE` при
- * 502/504 от шлюза), не находятся ни в жёстком, ни в мягком списке и потому считаются
- * временными — то есть повторяются с backoff. Замерено на локальном сервере, рвущем
- * соединение после приёма запроса: без hardErrorCodes портал выполняет crm.deal.add
- * три раза, с ними — один. На SDK 2.0.0 был один: там транспорт маскировался в
- * JSSDK_UNKNOWN_ERROR, а тот во встроенном жёстком списке.
- *
- * `ERR_NETWORK` и `ECONNABORTED` в списке не нужны: до лимитера они не доживают.
- *
- * Плата за список: `ECONNREFUSED`/`ENOTFOUND`/`EAI_AGAIN` доказывают, что запрос не ушёл,
- * и SDK мог бы повторить их безопасно даже для создающих вызовов. Отказываемся сознательно —
- * ровно так вёл себя 2.0.0, а один понятный инвариант дороже трёх сэкономленных попыток.
- */
-const SDK_RESTRICTION_PARAMS = {
-    retryOnNetworkError: false,
-    hardErrorCodes: [
-        "ECONNRESET",
-        "ECONNREFUSED",
-        "ENOTFOUND",
-        "ETIMEDOUT",
-        "EHOSTUNREACH",
-        "ENETUNREACH",
-        "EAI_AGAIN",
-        "EPIPE",
-        "EPROTO",
-        "ERR_BAD_RESPONSE",
-    ],
-} as const satisfies RestrictionParams;
-
-const confAuthB24 = new Conf({
-    cwd: path.resolve(CONFIG_DIR),
-    configName: "authB24",
-});
-
-// ==================== Утилиты ====================
-
-/** Убирает протокол из домена (https://example.bitrix24.ru → example.bitrix24.ru) */
-function cleanDomain(domain: string): string {
-    return domain.replace(/^https?:\/\//, "");
-}
-
-/** Задержка на указанное количество миллисекунд */
-const delay = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
-
-/**
- * Достаёт result из ответа SDK.
- *
- * SDK при «мягких» ошибках (ERROR_ENTITY_NOT_FOUND, BITRIX_REST_V3_EXCEPTION_*)
- * не бросает исключение, а возвращает AjaxResult с ошибкой.
- * Функция превращает такой ответ в понятную ошибку вместо падения на undefined.
- * Также отсекает случай, когда запрос успешен, но result пустой (null/undefined).
- *
- * @param response — результат $b24.callMethod()
- * @param methodName — имя метода B24, попадёт в текст ошибки
- */
-export function getResultData<T = any>(response: AjaxResult, methodName: string): T {
-    if (!response.isSuccess) {
-        const messages = response.getErrorMessages().join("; ") || "неизвестная ошибка";
-        throw new Error(`${methodName}: Bitrix24 вернул ошибку — ${messages}`);
-    }
-
-    const data = response.getData();
-    if (data?.result == null) {
-        throw new Error(`${methodName}: Bitrix24 вернул пустой ответ`);
-    }
-
-    return data.result as T;
-}
-
-/** Конверт ответа restApi:v2 — то, что прислал портал, до того как AjaxResult его урезал */
-interface V2Envelope {
-    result?: unknown;
-    next?: unknown;
-    total?: unknown;
-}
-
-/**
- * Читает сырой конверт ответа из AjaxResult.
- *
- * `getData()` отдаёт замороженную пару `{ result, time }` — полей `next` и `total`
- * в ней нет намеренно (в restApi:v3 их не существует). С версии 2.2.0 SDK снял
- * `isMore()`/`getTotal()`/`getNext()` с удаления и объявил их постоянными читателями
- * конверта restApi:v2, но числового смещения среди них так и нет: `isMore()` отвечает
- * только «есть ли ещё», а `getNext(http)` сам делает следующий запрос, мимо нашего
- * прогресса и retry. Поэтому конверт читаем напрямую: `_data` объявлен `protected`,
- * а не приватным полем класса, поэтому в рантайме доступен.
- *
- * Это единственная точка связи с внутренностями SDK. Если она перестанет работать,
- * она обязана упасть громко: тихо оборванная на первой странице выборка — потеря данных.
- */
-function readV2Envelope(response: AjaxResult, method: string): V2Envelope {
-    const envelope = (response as unknown as { _data?: unknown })._data;
-
-    if (!envelope || typeof envelope !== "object") {
-        throw new Error(`${method}: не удалось прочитать конверт ответа Bitrix24 (AjaxResult._data недоступен) — изменился внутренний формат SDK`);
-    }
-
-    return envelope as V2Envelope;
-}
-
-// ==================== Логгер SDK ====================
-
-/**
- * Мост из логгера SDK в `logs` пакета.
- *
- * Порог WARNING обязателен: SDK пишет `post/send` и `post/response` на уровне `info`
- * на каждый запрос и `http batch request starting/completed` на `debug` — без фильтра
- * это залило бы лог.
- *
- * `AbstractHandler` объявлен в типах SDK, но в рантайме не экспортируется,
- * поэтому реализуем интерфейс `Handler` обычным классом.
- */
-class B24SdkLogHandler implements Handler {
-    private formatter: Formatter | null = null;
-
-    isHandling(level: LogLevel): boolean {
-        return level >= LogLevel.WARNING;
-    }
-
-    shouldBubble(): boolean {
-        return true;
-    }
-
-    setFormatter(formatter: Formatter): void {
-        this.formatter = formatter;
-    }
-
-    getFormatter(): Formatter | null {
-        return this.formatter;
-    }
+import { createB24Instance } from "./b24/instance.ts";
+import { wrapB24WithRetry } from "./b24/proxy.ts";
+import { $b24, setB24Instance } from "./b24/state.ts";
+import { refreshAndSaveTokens, resetRefreshMutex, saveTokens, startProactiveRefresh, stopProactiveRefresh } from "./b24/tokens.ts";
+import type { SaveResult } from "./b24/types.ts";
 
-    async handle(record: LogRecord): Promise<boolean> {
-        // Бросать отсюда нельзя ни при каких обстоятельствах: Logger.log() делает
-        // await handle(), но лимитер зовёт логгер без await — исключение стало бы
-        // unhandled rejection и на дефолтных настройках Node убило бы процесс.
-        // Путь к броску реален: logs.add() читает conf, а тот перечитывает файл
-        // на каждом обращении и падает на битом log.json. В catch пишем через
-        // console.error, а не через logs — иначе рискуем зациклиться на той же ошибке.
-        try {
-            const status = Number(record.context?.status);
+// ==================== Реэкспорт публичного API ====================
 
-            // Лимитер SDK через error() пишет любой 4xx кроме 408/429 как
-            // «non-retryable client error». Портал отдаёт 400 на штатные «мягкие»
-            // ошибки (несуществующая сущность), которые README описывает как
-            // нормальный путь через getResultData(): проверка существования в цикле
-            // дала бы строку на итерацию. Такие сообщения — уровень debug.
-            //
-            // 408 и 429 из правила исключены на будущее, сегодня эта ветка недостижима:
-            // status попадает в контекст записи уровня WARNING и выше ровно в одном месте
-            // SDK — #logNonRetryableClientError, а он вызывается из-под условия, которое
-            // 408 и 429 уже исключает. Сообщения лимитера про 429/503 идут другим путём,
-            // без status в контексте, и маппятся в warn независимо от этой строки.
-            // Условие оставлено потому, что фейлит в безопасную сторону: начни SDK класть
-            // status в такие записи — таймаут и упор в лимит будут видны, а не утонут в debug.
-            //
-            // Остальное: уровень ERROR у SDK — это диагностика отдельной неуспешной
-            // попытки. На транспортном сбое их пять — по числу наших попыток, повторы SDK
-            // выключены (см. SDK_RESTRICTION_PARAMS). На 429/503 и неизвестных 5xx SDK
-            // повторяет по-прежнему, там до пятнадцати: три внутри каждой из наших пяти.
-            // Уровень error пакета уходит в чат B24, поэтому маппим SDK-ERROR в warn:
-            // окончательный провал вызова логирует retry-слой, ровно один раз.
-            const isQuietClientError = status >= 400 && status < 500 && status !== 408 && status !== 429;
-            const level = isQuietClientError ? "debug" : record.level >= LogLevel.CRITICAL ? "error" : "warn";
+// Явные списки, а не `export *`: тот вытащил бы наружу внутренние имена
+// (`SaveResult`, `createFacade`, `getRetryBlockReason`, `setB24Instance`)
+// и расширил публичный API пакета
+export { $b24 } from "./b24/state.ts";
+export { getResultData } from "./b24/facade.ts";
+export { callProtected } from "./b24/retry.ts";
+export { saveTokens, refreshAndSaveTokens, stopProactiveRefresh } from "./b24/tokens.ts";
+export type { B24Client, B24MethodCaller } from "./b24/types.ts";
 
-            // Контекст SDK (requestId, method, code, wait, status) уже прогнан
-            // через redactSensitiveParams — токены в него не попадают
-            const context = record.context && Object.keys(record.context).length > 0 ? record.context : undefined;
+// ==================== Инициализация ====================
 
-            logs.add(`SDK B24: ${record.message}`, level, context);
-        } catch (error: unknown) {
-            const msg = error instanceof Error ? error.message : String(error);
-            console.error(`B24SdkLogHandler: не удалось записать сообщение SDK — ${msg}`);
+/** Настраивает колбэк автосохранения токенов на экземпляре B24OAuth */
+function setupRefreshCallback(raw: B24OAuth): void {
+    raw.setCallbackRefreshAuth(async ({ authData }) => {
+        const result = saveTokens(authData);
+        if (result.error) {
+            logs.add(`Ошибка при автосохранении токенов: ${result.message}`, "error");
+        } else {
+            logs.add("Токены автоматически обновлены и сохранены в authB24.json", "debug");
         }
-
-        return true;
-    }
+    });
 }
 
-// ==================== Создание экземпляра B24OAuth ====================
-
-function createB24Instance(): B24OAuth | null {
-    // Проект вообще не использует OAuth: ходит в B24 по входящему вебхуку либо берёт
-    // из пакета только logs/fetchRetry. Отсутствие авторизации для него — норма, а не
-    // ошибка, поэтому уровень debug: иначе ложная строка попадает в мониторинг.
-    // Признак «OAuth задуман» — наличие credentials приложения в .env.
-    if (!CLIENT_ID && !CLIENT_SECRET) {
-        logs.add("OAuth Bitrix24 не настроен (APP_B24_CLIENT_ID и APP_B24_CLIENT_SECRET не заданы), $b24 = null", "debug");
-        return null;
-    }
+/** Пересоздаёт $b24 из актуального authB24.json без перезапуска сервера */
+export async function reinitializeB24(): Promise<SaveResult> {
+    stopProactiveRefresh();
 
-    if (!CLIENT_ID || !CLIENT_SECRET) {
-        logs.add("Не заданы APP_B24_CLIENT_ID или APP_B24_CLIENT_SECRET в .env", "error");
-        return null;
-    }
+    // Мьютекс общий на модуль: без сброса новый экземпляр приклеился бы к обмену
+    // старого, то есть к запросу со старым refresh-токеном, а при залипании обмена
+    // сохранение токенов с фронта висело бы до срабатывания сторожа.
+    // Компромисс: зависший старый обмен, завершившись позже, перезапишет authB24.json
+    // своими токенами поверх только что сохранённых — оба комплекта валидны для одного
+    // портала, побеждает последняя запись; гонка предсуществующая, сбросом не создаётся
+    resetRefreshMutex();
 
-    const store = confAuthB24.store as Record<string, AuthData>;
-    const authConfig = store[APP_ENV];
+    // Оба слоя пишутся одним вызовом: держать их согласованными — забота state.ts
+    const raw = createB24Instance();
+    setB24Instance(raw, raw ? wrapB24WithRetry(raw) : null);
 
-    if (!authConfig?.domain || !authConfig?.access_token || !authConfig?.refresh_token) {
-        logs.add("В конфиге authB24 не хватает данных для авторизации. Сохрани токены через клиент и перезагрузи докер", "error");
-        return null;
+    if (!raw || !$b24) {
+        return { error: true, message: "Не удалось пересоздать $b24 — проверь authB24.json и APP_B24_CLIENT_ID/APP_B24_CLIENT_SECRET" };
     }
 
-    const domain = cleanDomain(authConfig.domain);
-
-    const authParams: B24OAuthParams = {
-        applicationToken: "",
-        userId: 0,
-        memberId: authConfig.member_id,
-        accessToken: authConfig.access_token,
-        refreshToken: authConfig.refresh_token,
-        expires: authConfig.expires,
-        expiresIn: authConfig.expires_in || 1800,
-        scope: "",
-        domain,
-        clientEndpoint: `https://${domain}/rest/`,
-        serverEndpoint: "https://oauth.bitrix.info/rest/",
-        status: "L",
-        issuer: "store",
-    };
-
-    const secret: B24OAuthSecret = { clientId: CLIENT_ID, clientSecret: CLIENT_SECRET };
-
-    // Параметры ограничителя задаём третьим аргументом конструктора: SDK сливает их
-    // с дефолтами (`{ ...ParamsFactory.getDefault(), ...restrictionParams }` в AbstractHttp)
-    // и передаёт обоим http-клиентам, v2 и v3, ещё до того как экземпляр можно использовать.
-    // Через setRestrictionManagerParams() было бы окно между созданием и настройкой,
-    // а результат вызова к тому же непроверяем: он завершается Promise.allSettled и
-    // не отклоняется никогда.
-    const b24 = new B24OAuth(authParams, secret, { restrictionParams: SDK_RESTRICTION_PARAMS });
-
-    // Диагностика SDK от WARNING и выше уходит в logs пакета: предупреждения
-    // callList/fetchList про игнорируемый order и остановку пагинации, сообщения лимитера.
-    // Дефолтный NullLogger не годится — LoggerFactory.forcedLog пишет мимо логгера
-    // прямо в console.warn, но после перехода на фасад этот путь у нас недостижим.
-    b24.setLogger(Logger.create("npm-app-back-b24").pushHandler(new B24SdkLogHandler()));
-
-    return b24;
-}
+    setupRefreshCallback(raw);
 
-// ==================== Работа с токенами ====================
-
-/** Проверяет, что authData содержит все обязательные непустые поля */
-function isValidAuthData(data: AuthData): boolean {
-    return !!(
-        data &&
-        typeof data.access_token === "string" && data.access_token.length > 0 &&
-        typeof data.refresh_token === "string" && data.refresh_token.length > 0 &&
-        typeof data.domain === "string" && data.domain.length > 0 &&
-        data.expires
-    );
-}
-
-/** Сохраняет токены в authB24.json, нормализуя домен без протокола */
-export function saveTokens(authData: AuthData): SaveResult {
-    try {
-        if (!isValidAuthData(authData)) {
-            const msg = "Попытка сохранить невалидные токены — операция отклонена";
-            logs.add(msg, "error");
-            return { error: true, message: msg };
-        }
+    const refreshResult = await refreshAndSaveTokens();
+    startProactiveRefresh();
 
-        confAuthB24.set(APP_ENV, { ...authData, domain: cleanDomain(authData.domain) });
-        logs.add("Токены Bitrix24 сохранены", "debug");
-        return { error: false, message: "Токены сохранены." };
-    } catch (error: any) {
-        logs.add(`Ошибка сохранения токенов: ${error.message}`, "error");
-        return { error: true, message: error.message };
-    }
+    logs.add("$b24 переинициализирован с новыми токенами", "debug");
+    return refreshResult;
 }
 
 /** HTTP-обработчик для сохранения токенов с фронта */
@@ -434,7 +88,15 @@ export async function saveAuthB24Handler(req: Request, res: Response): Promise<v
 
         const reinitResult = await reinitializeB24();
         if (reinitResult.error) {
-            res.status(201).json({ status: "ok", message: `Токены сохранены, но $b24 не переинициализирован: ${reinitResult.message}` });
+            // Два разных исхода под одним флагом ошибки: экземпляр не создан вовсе
+            // или создан, а не удалось лишь первое обновление токена. Во втором случае
+            // $b24 работает, колбэк навешен, таймер запущен — сообщать «не переинициализирован»
+            // значит уводить разбор в сторону
+            const message = $b24
+                ? `Токены сохранены, $b24 пересоздан, первое обновление токена не удалось: ${reinitResult.message}`
+                : `Токены сохранены, но $b24 не переинициализирован: ${reinitResult.message}`;
+
+            res.status(201).json({ status: "ok", message });
         } else {
             res.status(201).json({ status: "ok", message: "Токены сохранены и применены." });
         }
@@ -444,564 +106,13 @@ export async function saveAuthB24Handler(req: Request, res: Response): Promise<v
     }
 }
 
-// ==================== Мьютекс для refresh токена ====================
-
-/**
- * Дедупликация refresh-запросов.
- * Пока промис не завершён, все новые вызовы ждут его результат
- * вместо параллельных запросов к oauth.bitrix.info.
- */
-let refreshInProgress: Promise<AuthData> | null = null;
-
-async function refreshAuthWithMutex(): Promise<AuthData> {
-    if (refreshInProgress) {
-        logs.add("refreshAuth: ожидаем завершения текущего refresh", "debug");
-        return refreshInProgress;
-    }
-
-    refreshInProgress = (async () => {
-        try {
-            if (!$b24) throw new Error("$b24 не инициализирован");
-
-            let lastError: unknown;
-            for (let attempt = 1; attempt <= RETRY_COUNT; attempt++) {
-                try {
-                    return await $b24.auth.refreshAuth();
-                } catch (error) {
-                    lastError = error;
-
-                    // Повторяем только когда соединение заведомо не состоялось.
-                    // При таймауте или обрыве сервер мог уже провести ротацию: тогда
-                    // локальный refresh-токен мёртв независимо от наших действий, и повтор
-                    // не помогает, а лишь маскирует проблему серией одинаковых отказов.
-                    // Следующая попытка всё равно будет — проактивный таймер повторит
-                    // через 2 минуты при времени жизни токена около часа
-                    if (!isPreConnectionError(error) || attempt === RETRY_COUNT) throw error;
-
-                    const msg = error instanceof Error ? error.message : String(error);
-                    const code = error instanceof SdkError ? ` [${error.code}]` : "";
-                    const delayMs = RETRY_DELAY_MS * attempt;
-                    logs.add(`refreshAuth${code}: попытка ${attempt}/${RETRY_COUNT} не удалась (${msg}), повтор через ${delayMs}мс`, "warn");
-                    await delay(delayMs);
-                }
-            }
-            throw lastError;
-        } finally {
-            refreshInProgress = null;
-        }
-    })();
-
-    return refreshInProgress;
-}
-
-/**
- * Обновляет токены через мьютекс и сохраняет в файл.
- * Используется проактивным таймером и может вызываться вручную.
- */
-export async function refreshAndSaveTokens(): Promise<SaveResult> {
-    if (!$b24) {
-        return { error: true, message: "$b24 не инициализирован." };
-    }
-
-    try {
-        const authData = await refreshAuthWithMutex();
-        return saveTokens(authData);
-    } catch (error: any) {
-        logs.add(`Ошибка обновления токенов: ${error.message}`, "error");
-        return { error: true, message: error.message };
-    }
-}
-
-// ==================== Проактивное обновление токена ====================
-
-let proactiveRefreshTimer: ReturnType<typeof setTimeout> | null = null;
-
-/** Запускает проактивное обновление токена. При ошибке — повтор через 2 мин, при успехе — через 25 мин */
-function startProactiveRefresh(): void {
-    if (proactiveRefreshTimer) {
-        clearTimeout(proactiveRefreshTimer);
-        proactiveRefreshTimer = null;
-    }
-
-    const scheduleNext = (delayMs: number) => {
-        proactiveRefreshTimer = setTimeout(async () => {
-            logs.add("Проактивное обновление токена Bitrix24", "debug");
-            const result = await refreshAndSaveTokens();
-
-            if (result.error) {
-                logs.add(`Ошибка проактивного обновления токена, повтор через ${PROACTIVE_RETRY_ON_ERROR_MS / 60000} мин`, "error");
-                scheduleNext(PROACTIVE_RETRY_ON_ERROR_MS);
-            } else {
-                scheduleNext(PROACTIVE_REFRESH_INTERVAL_MS);
-            }
-        }, delayMs);
-    };
-
-    scheduleNext(PROACTIVE_REFRESH_INTERVAL_MS);
-    logs.add(`Проактивное обновление токена запущено (каждые ${PROACTIVE_REFRESH_INTERVAL_MS / 60000} мин)`, "debug");
-}
-
-/** Останавливает проактивное обновление токена */
-export function stopProactiveRefresh(): void {
-    if (!proactiveRefreshTimer) return;
-    clearTimeout(proactiveRefreshTimer);
-    proactiveRefreshTimer = null;
-    logs.add("Проактивное обновление токена остановлено", "debug");
-}
-
-// ==================== Retry-обёртка ====================
-
-/**
- * Проверяет, является ли ошибка из SDK сетевой.
- *
- * С версии 2.2.0 SDK отдаёт транспортный сбой честным кодом: NETWORK_ERROR (status 0)
- * или REQUEST_TIMEOUT (status 408). До 2.2.0 он их маскировал — в логирующей ветке падал
- * собственный TypeError, и наружу приходил AjaxError с кодом JSSDK_UNKNOWN_ERROR и status 0.
- * Проверку по status 0 оставляем: она ловит всё, что SDK отдаёт без внятного кода.
- * Сюда же попадает провал обновления токена внутри callMethod: SDK перезаворачивает
- * SdkError в AjaxError с кодом JSSDK_UNKNOWN_ERROR и status 0, и исходный код теряется.
- * RefreshTokenError приходит как SdkError с кодом вроде ENOTFOUND и без originalError.
- */
-function isB24NetworkError(error: unknown): boolean {
-    if (error instanceof AjaxError) {
-        // Практически недостижимо (SDK бросает реальную ошибку раньше),
-        // но если код всё же пришёл — SDK уже исчерпал свои попытки
-        if (error.code === "JSSDK_CALL_ALL_ATTEMPTS_EXHAUSTED") return false;
-    }
-
-    if (error instanceof SdkError) {
-        const { code, originalError, status } = error;
-        const originalCode = (originalError as { code?: string } | undefined)?.code;
-
-        if (NETWORK_ERROR_CODES.has(code)) return true;
-        if (originalError && isNetworkError(originalError)) return true;
-        if (originalCode && NETWORK_ERROR_CODES.has(originalCode)) return true;
-        if (status === 0) return true;
-
-        // 502 Bad Gateway: шлюз перед порталом не смог получить ответ от upstream —
-        // запрос почти наверняка не выполнялся, повтор осмыслен. Мы держим этот код
-        // в SDK_RESTRICTION_PARAMS.hardErrorCodes, чтобы SDK его не повторял, но
-        // повторить его должен наш слой: там создающие вызовы отсекает гейт.
-        //
-        // 504 сюда намеренно не входит, хотя приходит тем же кодом ERR_BAD_RESPONSE:
-        // это «портал взял запрос и считает прямо сейчас, шлюз устал ждать». Повтор
-        // создающего вызова дал бы дубликат, а читающего — ничего: за таймаут шлюза
-        // запрос не уложился один раз, не уложится и на второй, зато пять тяжёлых
-        // повторов добавят нагрузки порталу ровно тогда, когда ему и так плохо.
-        if (status === 502) return true;
-    }
-
-    return isNetworkError(error);
-}
-
-/**
- * Достаёт имя REST-метода из одной команды batch.
- * Возвращает null, если форма команды не распознана.
- */
-function extractBatchCommandMethod(cmd: unknown): string | null {
-    // Кортеж ["crm.deal.add", { ... }] — основная форма в SDK 2.x
-    if (Array.isArray(cmd)) {
-        return typeof cmd[0] === "string" ? cmd[0] : null;
-    }
-
-    // Объект { method, params }
-    if (cmd && typeof cmd === "object") {
-        const method = (cmd as { method?: unknown }).method;
-        return typeof method === "string" ? method : null;
-    }
-
-    // Строка "crm.deal.add?ID=1" — в SDK 2.x эта форма уже не поддерживается
-    // (ParseRow бросает JSSDK_INTERACTION_BATCH_ROW_FAIL), разбираем на случай,
-    // если потребитель остался на ней со старой версии
-    if (typeof cmd === "string") {
-        return cmd;
-    }
-
-    return null;
-}
-
-/**
- * Возвращает причину, по которой вызов запрещено повторять, либо null.
- *
- * Для callBatch действует правило fail-closed: если хоть одну команду разобрать
- * не удалось, вызов считается создающим. Ошибиться в сторону лишней осторожности
- * дешевле — потребитель получит ошибку вместо тихого дубликата.
- */
-function getRetryBlockReason(sdkMethod: string, args: any[]): string | null {
-    const first = args[0];
-
-    // callMethod(method, params) и callListMethod(method, params, ...)
-    if (sdkMethod === "callMethod" || sdkMethod === "callListMethod") {
-        if (typeof first !== "string") return null;
-        const method = first.trim();
-        return NON_IDEMPOTENT_METHOD_RE.test(method) ? method : null;
-    }
-
-    if (sdkMethod !== "callBatch") return null;
-
-    // callBatch(calls, ...) — команды приходят массивом либо объектом-словарём
-    if (!first || typeof first !== "object") {
-        return "аргументы batch не разобраны";
-    }
-
-    const commands: unknown[] = Array.isArray(first) ? first : Object.values(first);
-    const blocking: string[] = [];
-
-    for (const cmd of commands) {
-        const method = extractBatchCommandMethod(cmd);
-
-        if (method === null) return "команда batch не разобрана";
-        if (NON_IDEMPOTENT_METHOD_RE.test(method.trim())) blocking.push(method.trim());
-    }
-
-    return blocking.length > 0 ? blocking.join(", ") : null;
-}
-
-/**
- * Общий цикл повторов при сетевых ошибках.
- *
- * @param fn — вызов без аргументов, уже замкнутый на нужные параметры
- * @param label — префикс лог-строк, по нему в логе видно источник повтора
- * @param blockReason — причина, по которой повтор запрещён (создающий вызов), либо null
- */
-async function runWithRetry<T>(fn: () => Promise<T>, label: string, blockReason: string | null): Promise<T> {
-    let lastError: unknown;
-
-    for (let attempt = 1; attempt <= RETRY_COUNT; attempt++) {
-        try {
-            return await fn();
-        } catch (error: unknown) {
-            lastError = error;
-
-            // Ошибка не сетевая (бизнес-логика B24, неверные параметры) — отдаём
-            // вызывающему коду как есть, он решает, что с ней делать
-            if (!isB24NetworkError(error)) throw error;
-
-            const msg = error instanceof Error ? error.message : String(error);
-            const code = error instanceof SdkError ? ` [${error.code}]` : "";
-
-            // Окончательные отказы логируем на error: собственные модули пакета
-            // (errorB24, Event, Smsgold) ошибку только возвращают вызывающему коду,
-            // но не пишут в лог — без этих строк сбой $b24 не виден нигде
-
-            if (attempt === RETRY_COUNT) {
-                logs.add(`${label}${code}: исчерпаны все ${RETRY_COUNT} попыток — ${msg}`, "error");
-                throw error;
-            }
-
-            // Ошибка со status 0 может означать и «запрос не ушёл», и «запрос выполнен,
-            // а ответ не разобрался»: различить их нельзя, поэтому создающие вызовы
-            // не повторяем — лучше вернуть ошибку, чем создать дубликат
-            if (blockReason) {
-                logs.add(`${label}${code}: повтор отменён, вызов создаёт сущности (${blockReason}) — ${msg}`, "error");
-                throw error;
-            }
-
-            // Промежуточные попытки — warn: в чат B24 уходит только уровень error,
-            // иначе один упавший вызов дал бы пять сообщений
-            logs.add(`${label}${code}: попытка ${attempt}/${RETRY_COUNT} не удалась (${msg}), повтор через ${RETRY_DELAY_MS}мс`, "warn");
-
-            await delay(RETRY_DELAY_MS);
-        }
-    }
-
-    // Недостижимо при RETRY_COUNT >= 1, нужно для TypeScript
-    throw lastError;
-}
-
-/** Оборачивает async-функцию retry-логикой при сетевых ошибках */
-function withRetry<T extends (...args: any[]) => Promise<any>>(fn: T, context: any, methodName: string): T {
-    return (async (...args: any[]) => {
-        // Состав вызова между попытками не меняется — разбираем один раз
-        const blockReason = getRetryBlockReason(methodName, args);
-        return runWithRetry(() => fn.apply(context, args), `$b24.${methodName}`, blockReason);
-    }) as T;
-}
-
-/**
- * Прогоняет произвольный вызов `actions.*` через тот же retry и гейт идемпотентности,
- * что и методы фасада. Прямой `$b24.actions.v3.call.make()` идёт мимо защиты — если она
- * нужна (например, ради `FilterV3` или keyset-пагинации), вызов оборачивают этой функцией.
- *
- * @param run — сам вызов, например `() => $b24.actions.v3.call.make({ method, params })`
- * @param methodName — имя REST-метода B24 (не метода SDK) либо список имён, если внутри
- *                     batch: по ним гейт решает, создаёт ли вызов сущность
- *
- * @example
- * const response = await callProtected(
- *     () => $b24!.actions.v3.call.make({ method: "crm.item.list", params }),
- *     "crm.item.list"
- * );
- *
- * @example
- * const response = await callProtected(
- *     () => $b24!.actions.v3.batch.make({ calls }),
- *     ["crm.item.get", "crm.item.add"]
- * );
- */
-export async function callProtected<T>(run: () => Promise<T>, methodName: string | string[]): Promise<T> {
-    const names = (Array.isArray(methodName) ? methodName : [methodName]).map((name) => String(name).trim()).filter((name) => name.length > 0);
-
-    // Fail-closed, как в гейте callBatch: список пуст или имя не похоже на REST-метод
-    // (легальные имена всегда с точкой — crm.deal.add, disk.folder.uploadfile) — считаем
-    // вызов создающим. Иначе callProtected(() => batch.make({ calls }), "batch") прошёл бы
-    // мимо гейта, и батч с crm.deal.add внутри повторился бы до пяти раз при status 0.
-    const isUnparsed = names.length === 0 || names.some((name) => !name.includes("."));
-    const blocking = names.filter((name) => NON_IDEMPOTENT_METHOD_RE.test(name));
-
-    const blockReason = isUnparsed ? "имя метода не разобрано" : blocking.length > 0 ? blocking.join(", ") : null;
-
-    return runWithRetry(run, `actions:${names.join(", ") || "имя не указано"}`, blockReason);
-}
-
-// ==================== Фасад поверх actions.v2.* ====================
-
-/**
- * Собственные реализации пяти методов, которые SDK 2.x помечает к удалению.
- * Повторяют `AbstractB24` дословно, включая дефолты и порядок аргументов.
- *
- * Позиционные сигнатуры сохранены один в один: на этом держится то, что гейт
- * идемпотентности (`getRetryBlockReason`) видит те же аргументы, что и раньше,
- * — retry оборачивает фасад снаружи, а преобразование в объект опций
- * происходит уже внутри.
- */
-function createFacade(target: B24OAuth): Record<string, (...args: any[]) => any> {
-    // Геттер actions при каждом обращении проверяет инициализацию экземпляра —
-    // читаем его в момент вызова, а не один раз при создании фасада
-    const v2 = () => target.actions.v2;
-
-    const callMethod = async <T = any>(method: string, params?: object, start?: number): Promise<AjaxResult<T>> => {
-        const merged: TypeCallParams = { ...params };
-
-        // Явный params.start приоритетнее аргумента start — как в AbstractB24.callMethod.
-        // typeof, а не только Number.isInteger: последний ничего не сужает, и при
-        // exactOptionalPropertyTypes у потребителя присваивание number | undefined не проходит
-        if (!("start" in merged && Number.isInteger(merged.start)) && typeof start === "number" && Number.isInteger(start)) {
-            merged.start = start;
-        }
-
-        return v2().call.make<T>({ method, params: merged });
-    };
-
-    /**
-     * Собственный офсетный цикл, а не `actions.v2.callList.make`.
-     *
-     * У `callList.make` keyset-пагинация: он шлёт `start: -1`, навязывает
-     * `order: { ID: 'ASC' }` и добавляет в фильтр `>ID`. Пользовательский `order`
-     * при этом молча игнорируется, а колбэка `progress` там нет вовсе. Делегирование
-     * туда изменило бы поведение постраничных выборок у потребителей.
-     */
-    const callListMethod = async (
-        method: string,
-        params?: object,
-        progress?: null | ((progress: number) => void),
-        customKeyForResult?: string | null
-    ): Promise<Result> => {
-        const result = new Result();
-        const onProgress = typeof progress === "function" ? progress : null;
-
-        onProgress?.(0);
-
-        const list: unknown[] = [];
-        let start = 0;
-        let completed = false;
-
-        for (let page = 1; page <= LIST_MAX_PAGES; page++) {
-            const response = await v2().call.make({ method, params: { ...params, start } });
-
-            // SDK в своём callListMethod этой проверки не делает и падает TypeError
-            // на getData().result, когда портал вернул «мягкую» ошибку
-            if (!response.isSuccess) {
-                throw new Error(`${method}: Bitrix24 вернул ошибку — ${response.getErrorMessages().join("; ")}`);
-            }
-
-            // Читаем конверт целиком: getData() режет ответ до { result, time },
-            // а пагинация держится на next, которого там нет
-            const envelope = readV2Envelope(response, method);
-            const payload = envelope.result;
-            const chunk = customKeyForResult ? (payload as Record<string, unknown> | undefined)?.[customKeyForResult] : payload;
-
-            if (!Array.isArray(chunk)) {
-                throw new Error(`${method}: ответ не является списком`);
-            }
-
-            for (const item of chunk) {
-                list.push(item);
-            }
-
-            // Единственное правило остановки — отсутствие next в конверте. Считать
-            // смещение самим (start += chunk.length) нельзя: портал ставит next = start + 50
-            // независимо от того, сколько строк реально отдал, и на странице, укороченной
-            // правами доступа или фильтром, собственный счётчик отстаёт — перекрытие
-            // читается второй раз и записи дублируются. Метод, который игнорирует start
-            // и отдаёт весь список одной страницей, next не присылает и останавливается здесь же.
-            if (!Number.isInteger(envelope.next)) {
-                completed = true;
-                break;
-            }
-
-            const nextStart = Number(envelope.next);
-
-            // next обязан расти. Портал, вернувший прежнее или меньшее смещение,
-            // иначе гонял бы одну и ту же страницу до потолка, раздувая список
-            if (nextStart <= start) {
-                throw new Error(`${method}: портал вернул непродвигающийся next (${nextStart}) при start ${start} — пагинация зациклилась`);
-            }
-
-            start = nextStart;
-
-            if (onProgress) {
-                const total = Number(envelope.total) || 0;
-                onProgress(total > 0 ? Math.round((100 * list.length) / total) : 100);
-            }
-        }
-
-        // Обрезанный список, отданный как успешный, — худший исход: потребитель
-        // примет неполную выборку за полную. Поэтому бросаем, а не логируем:
-        // addError() на базовом Result бесполезен — getData() отдаёт данные
-        // независимо от наличия ошибок, и существующие потребители её не увидят
-        if (!completed) {
-            throw new Error(`${method}: достигнут потолок в ${LIST_MAX_PAGES} страниц, портал продолжает отдавать next — выборка прервана как неполная`);
-        }
-
-        onProgress?.(100);
-        result.setData(list);
-        return result;
-    };
-
-    async function* fetchListMethod(method: string, params?: any, idKey?: string, customKeyForResult?: string | null): AsyncGenerator<any[]> {
-        // Ключи со значением undefined не подставляем вовсе: при exactOptionalPropertyTypes
-        // у потребителя явный undefined не подходит опциональному полю опций SDK.
-        // Поведение прежнее — null и undefined одинаково означают «ключ не передан»
-        yield* v2().fetchList.make<any>({
-            method,
-            params,
-            ...(idKey === undefined ? {} : { idKey }),
-            ...(customKeyForResult === null || customKeyForResult === undefined ? {} : { customKeyForResult }),
-        });
-    }
-
-    const callBatch = async (calls: Array<any> | object, isHaltOnError?: boolean, returnAjaxResult?: boolean): Promise<Result> => {
-        // Дефолты подставляем мы: batch.make своих не имеет, он просто
-        // расширяет переданный объект опций версией API
-        return v2().batch.make({
-            calls: calls as BatchCalls,
-            options: {
-                isHaltOnError: isHaltOnError ?? true,
-                returnAjaxResult: returnAjaxResult ?? false,
-            },
-        });
-    };
-
-    const callBatchByChunk = async (calls: Array<any>, isHaltOnError: boolean): Promise<Result> => {
-        // isHaltOnError передаём как есть, без ?? true — дословно по AbstractB24.
-        // returnAjaxResult не передаём: batchByChunk.make жёстко ставит false сам,
-        // а его тип опций этот ключ не принимает
-        return v2().batchByChunk.make({ calls, options: { isHaltOnError } });
-    };
-
-    return { callMethod, callListMethod, fetchListMethod, callBatch, callBatchByChunk } satisfies FacadeMethods;
-}
-
-/**
- * Proxy-обёртка вокруг B24OAuth.
- *
- * Имена из FACADE_METHODS резолвятся в собственные реализации пакета поверх
- * `actions.v2.*`; из них методы RETRYABLE_METHODS дополнительно оборачиваются
- * retry-логикой. Все остальные методы привязываются к оригинальному объекту
- * через bind: класс B24OAuth использует приватные поля (#authOAuthManager),
- * и при вызове метода с this === Proxy движок бросает "Cannot read private member".
- *
- * Обёртки кешируются — по одной на метод, чтобы не ломать сравнение по ссылке.
- */
-function wrapB24WithRetry(b24: B24OAuth): B24Client {
-    const methodCache = new Map<string, Function>();
-    // Фасад создаётся один раз на экземпляр: он замкнут на конкретный target,
-    // а пересоздание на каждом обращении ломало бы кеш и сравнение по ссылке
-    const facade = createFacade(b24);
-
-    return new Proxy(b24, {
-        get(target, prop) {
-            // Имена фасада проверяем до Reflect.get: пока SDK ещё объявляет свои
-            // deprecated-методы, иначе мы отдавали бы их, а не свои
-            if (typeof prop === "string" && FACADE_METHODS.has(prop)) {
-                if (!methodCache.has(prop)) {
-                    const impl = facade[prop]!;
-                    methodCache.set(prop, RETRYABLE_METHODS.has(prop) ? withRetry(impl, target, prop) : impl);
-                }
-
-                return methodCache.get(prop);
-            }
-
-            // Передаём target третьим аргументом: геттеры (например, auth)
-            // тоже должны исполняться с this === target
-            const value = Reflect.get(target, prop, target);
-
-            if (typeof prop !== "string" || typeof value !== "function") {
-                return value;
-            }
-
-            if (!methodCache.has(prop)) {
-                const wrapped = RETRYABLE_METHODS.has(prop)
-                    ? withRetry(value as (...args: any[]) => Promise<any>, target, prop)
-                    : value.bind(target);
-                methodCache.set(prop, wrapped);
-            }
-
-            return methodCache.get(prop);
-        },
-
-        // Страховка на будущее: когда SDK уберёт методы из прототипа,
-        // "callMethod" in $b24 обязано остаться истинным (eventB24.ts проверяет
-        // наличие метода перед работой). Цель расширяема, лишние true законны
-        has(target, prop) {
-            if (typeof prop === "string" && FACADE_METHODS.has(prop)) return true;
-            return Reflect.has(target, prop);
-        },
-    }) as B24Client;
-}
-
-// ==================== Инициализация ====================
-
-let _b24Raw = createB24Instance();
-export let $b24: B24Client | null = _b24Raw ? wrapB24WithRetry(_b24Raw) : null;
-
-/** Настраивает колбэк автосохранения токенов на экземпляре B24OAuth */
-function setupRefreshCallback(raw: B24OAuth): void {
-    raw.setCallbackRefreshAuth(async ({ authData }) => {
-        const result = saveTokens(authData);
-        if (result.error) {
-            logs.add(`Ошибка при автосохранении токенов: ${result.message}`, "error");
-        } else {
-            logs.add("Токены автоматически обновлены и сохранены в authB24.json", "debug");
-        }
-    });
-}
-
-/** Пересоздаёт $b24 из актуального authB24.json без перезапуска сервера */
-export async function reinitializeB24(): Promise<SaveResult> {
-    stopProactiveRefresh();
-
-    _b24Raw = createB24Instance();
-    $b24 = _b24Raw ? wrapB24WithRetry(_b24Raw) : null;
-
-    if (!_b24Raw || !$b24) {
-        return { error: true, message: "Не удалось пересоздать $b24 — проверь authB24.json и APP_B24_CLIENT_ID/APP_B24_CLIENT_SECRET" };
-    }
-
-    setupRefreshCallback(_b24Raw);
-
-    const refreshResult = await refreshAndSaveTokens();
-    startProactiveRefresh();
-
-    logs.add("$b24 переинициализирован с новыми токенами", "debug");
-    return refreshResult;
-}
-
 // ==================== Начальная инициализация ====================
 
-if (_b24Raw) {
-    setupRefreshCallback(_b24Raw);
+const initialRaw = createB24Instance();
+setB24Instance(initialRaw, initialRaw ? wrapB24WithRetry(initialRaw) : null);
+
+if (initialRaw) {
+    setupRefreshCallback(initialRaw);
 
     // Намеренно не ждём результат: импорт модуля не должен блокироваться сетевым
     // запросом к oauth.bitrix.info. try/finally обязателен — если обновление всё же