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

package/bitrix24/b24/facade.ts

@@ -0,0 +1,371 @@
+import { Result } from "@bitrix24/b24jssdk";
+import type { AjaxResult, TypeCallParams, B24OAuth } from "@bitrix24/b24jssdk";
+import { logs } from "../../logs/logs.ts";
+import { getRetryBlockReason, runWithRetry } from "./retry.ts";
+import type { FacadeMethods, BatchCalls, V2Envelope } from "./types.ts";
+
+// ==================== Константы ====================
+
+/** Потолок числа страниц в callListMethod — страховка от бесконечной пагинации */
+export const LIST_MAX_PAGES = 1000;
+
+/**
+ * Потолок числа страниц keyset-цикла в fetchListMethod — страховка от зацикливания,
+ * а не лимит выборки.
+ *
+ * Своя константа, не общая LIST_MAX_PAGES: у callListMethod потолок продиктован ростом
+ * массива в памяти, он копит весь список. fetchListMethod — генератор, он существует
+ * ровно для выборок, которые в память не помещаются, и потолок в 1000 страниц оборвал бы
+ * законную выборку на крупном портале. Миллион записей недостижим для законного вызова
+ * и достижим для зацикленного за секунды.
+ */
+export const FETCH_LIST_MAX_PAGES = 20000;
+
+// ==================== Разбор ответа SDK ====================
+
+/**
+ * Достаёт result из ответа SDK.
+ *
+ * SDK при «мягких» ошибках (ERROR_ENTITY_NOT_FOUND, BITRIX_REST_V3_EXCEPTION_*)
+ * не бросает исключение, а возвращает AjaxResult с ошибкой.
+ * Функция превращает такой ответ в понятную ошибку вместо падения на undefined.
+ * Также отсекает случай, когда запрос успешен, но result пустой (null/undefined).
+ *
+ * Дефолт дженерика — `any`, и это осознанно: потребители пишут
+ * `getResultData(response, "tasks.task.add").task.id` без параметра типа.
+ * Замена дефолта на `unknown` сломала бы каждое такое обращение, ничего не дав
+ * взамен: узкий тип задаётся на месте вызова — `getResultData<Deal>(response, method)`.
+ *
+ * @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;
+}
+
+/**
+ * Читает сырой конверт ответа из AjaxResult.
+ *
+ * `getData()` отдаёт замороженную пару `{ result, time }` — полей `next` и `total`
+ * в ней нет намеренно (в restApi:v3 их не существует). С версии 2.2.0 SDK снял
+ * `isMore()`/`getTotal()`/`getNext()` с удаления и объявил их постоянными читателями
+ * конверта restApi:v2, но числового смещения среди них так и нет: `isMore()` отвечает
+ * только «есть ли ещё», а `getNext(http)` сам делает следующий запрос, мимо нашего
+ * прогресса и retry. Поэтому конверт читаем напрямую: `_data` объявлен `protected`,
+ * а не приватным полем класса, поэтому в рантайме доступен.
+ *
+ * Это единственная точка связи с внутренностями SDK. Если она перестанет работать,
+ * она обязана упасть громко: тихо оборванная на первой странице выборка — потеря данных.
+ */
+export 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;
+}
+
+// ==================== Фасад поверх actions.v2.* ====================
+
+/**
+ * Собственные реализации пяти методов, которые SDK 2.x помечает к удалению.
+ * Повторяют `AbstractB24` дословно, включая дефолты и порядок аргументов.
+ *
+ * Позиционные сигнатуры сохранены один в один: на этом держится то, что гейт
+ * идемпотентности (`getRetryBlockReason`) видит те же аргументы, что и раньше,
+ * — retry оборачивает фасад снаружи, а преобразование в объект опций
+ * происходит уже внутри.
+ *
+ * `any` в сигнатурах ниже (`callMethod<T = any>`, `params?: any`, `AsyncGenerator<any[]>`,
+ * `Array<any>`, а также `call.make<any>` внутри `fetchListMethod` — тип страницы
+ * задаёт вызывающий) оставлен НАМЕРЕННО и снятию по T-53 не подлежит. Это дефолты дженериков
+ * публичной поверхности, дословно повторяющие `AbstractB24`: на них стоит код потребителей
+ * (`for await (const chunk of $b24.fetchListMethod(...)) chunk.forEach((x) => x.ID)`).
+ * `unknown` в дефолте уронил бы каждое такое место, не дав взамен ничего — узкий тип
+ * задаётся параметром типа на месте вызова (`callMethod<Deal>(...)`).
+ */
+export function createFacade(target: B24OAuth): FacadeMethods {
+    // Геттер 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;
+    };
+
+    /**
+     * Собственный keyset-цикл, а не `actions.v2.fetchList.make`.
+     *
+     * Делегирование не давало повторить страницу: генератор нельзя обернуть
+     * `withRetry` снаружи (обёртка в async-функцию ломает `for await`), поэтому
+     * одиночный сетевой сбой на двенадцатой странице обрывал всю выборку, а уже
+     * прочитанные одиннадцать потребитель либо терял, либо принимал за полную.
+     * Здесь повторяется страница: курсор двигается только после успешной страницы,
+     * поэтому отданные страницы не теряются и не дублируются.
+     *
+     * Форма запроса взята из `fetch-list.mjs`: `start: -1`, навязанный
+     * `order: { <курсор>: "ASC" }`, фильтр `>курсор`. Отступления от SDK — пять,
+     * все намеренные:
+     *   1. остановка только на пустой странице, а не на короткой: страница, укороченная
+     *      правами доступа, у портала штатна, и правило SDK молча обрезало бы выборку;
+     *   2. нечитаемый курсор — бросок, а не предупреждение и тихая остановка:
+     *      после пункта 1 он означает гарантированно неполную выборку;
+     *   3. потолок страниц (`FETCH_LIST_MAX_PAGES`) — у SDK цикл ничем не ограничен;
+     *   4. проверка роста курсора — портал, отбросивший неизвестный ключ фильтра,
+     *      иначе отдавал бы одну и ту же страницу вечно;
+     *   5. пустая строка в `customKeyForResult` трактуется как «ключ не передан».
+     *
+     * Плюс диагностика: ошибки называют метод B24 вместо `TypeError` из недр SDK
+     * и `SdkError` с кодом SDK.
+     *
+     * Ограничение: один и тот же ключ идёт и на чтение курсора, и в `order`/`filter`.
+     * Методы, у которых имя поля в ответе отличается от сортируемого (`tasks.task.list`:
+     * ответ `id`, фильтр `ID`), этим методом не выбираются — для них `callListMethod`
+     * или `actions.v2.fetchList.make` с `cursorIdKey`.
+     */
+    async function* fetchListMethod(method: string, params?: any, idKey?: string, customKeyForResult?: string | null): AsyncGenerator<any[]> {
+        // Отдельного cursorIdKey, как в опциях SDK, у нас нет и не будет: позиционная
+        // сигнатура deprecated-метода его не содержала, а добавление пятого аргумента —
+        // расширение публичного API. У SDK он по умолчанию тоже равен idKey
+        const cursorKey = idKey ?? "ID";
+        const moreKey = `>${cursorKey}`;
+        const source: Record<string, unknown> = { ...(params ?? {}) };
+
+        // Раньше это предупреждение приходило от логгера SDK, теперь пишем сами
+        if ("order" in source && source["order"]) {
+            logs.add(`${method}: параметр order игнорируется — keyset-пагинация сортирует по «${cursorKey}» ASC, сужать выборку следует через filter`, "warn");
+        }
+
+        const { order: _ignoredOrder, filter: userFilter, ...restParams } = source;
+
+        // Ключ курсора в пользовательском фильтре перетирается на каждой странице.
+        // Молчать здесь нельзя: рядом про order предупреждение есть, и асимметрия
+        // читалась бы как «фильтр по курсору пользователю оставлен»
+        if (userFilter && typeof userFilter === "object" && moreKey in (userFilter as Record<string, unknown>)) {
+            logs.add(`${method}: ключ «${moreKey}» в фильтре перетирается курсором пагинации — сузить выборку по нему нельзя`, "warn");
+        }
+
+        // Курсор: значение, от которого идёт следующая страница. Оно же лежит в фильтре
+        // запроса, отдельная переменная нужна для проверки роста
+        let cursor = 0;
+
+        // Фильтр — новый объект: мутировать переданный вызывающим нельзя, SDK этого тоже
+        // не делает, а курсор в этом объекте переписывается на каждой странице
+        const requestParams: Record<string, unknown> & { filter: Record<string, unknown> } = {
+            ...restParams,
+            order: { [cursorKey]: "ASC" },
+            filter: { ...((userFilter as Record<string, unknown> | undefined) ?? {}), [moreKey]: cursor },
+            start: -1,
+        };
+
+        // Список — чтение и дубликатов не создаёт, но гейт пусть стоит: если потребитель
+        // передаст создающий метод, повтор должен блокироваться, как везде.
+        // Состав вызова между страницами не меняется, поэтому считаем один раз
+        const blockReason = getRetryBlockReason("callMethod", [method]);
+
+        // Страховка от вечного цикла: портал, отбросивший неизвестный ключ фильтра,
+        // отдаёт одну и ту же страницу без ошибки и без строки в логе
+        let completed = false;
+
+        for (let page = 1; page <= FETCH_LIST_MAX_PAGES; page++) {
+            // Замыкание читает requestParams в момент вызова: объект один и тот же,
+            // курсор в нём двигается только после успешной страницы — поэтому повтор
+            // попадает ровно в ту же страницу, а не в следующую
+            const response = await runWithRetry(
+                () => v2().call.make<any>({ method, params: requestParams as TypeCallParams }),
+                "$b24.fetchListMethod",
+                blockReason
+            );
+
+            // Формулировка дословно как в callListMethod — один стиль ошибок на оба
+            // списочных метода. Сетевой такая ошибка не считается, повтора не будет:
+            // «мягкая» ошибка портала от повтора не исправится
+            if (!response.isSuccess) {
+                throw new Error(`${method}: Bitrix24 вернул ошибку — ${response.getErrorMessages().join("; ")}`);
+            }
+
+            const data = response.getData();
+            if (!data) {
+                completed = true;
+                break;
+            }
+
+            const payload = data.result;
+            const chunk = customKeyForResult ? (payload as Record<string, unknown> | undefined)?.[customKeyForResult] : payload;
+
+            // Отступление от SDK намеренное и такое же, как в callListMethod:
+            // там на этом месте падал TypeError из недр библиотеки
+            if (!Array.isArray(chunk)) {
+                throw new Error(`${method}: ответ не является списком`);
+            }
+
+            // Единственное правило остановки — пустая страница. SDK на этом месте
+            // останавливается ещё и на короткой (меньше 50 строк), но у портала
+            // страница, укороченная правами доступа, штатна — из-за неё в callListMethod
+            // запрещено считать смещение самим. Цена нового правила — один лишний
+            // запрос на всю выборку, всегда пустой; цена старого — молча отданные
+            // сорок семь записей вместо нескольких тысяч
+            if (chunk.length === 0) {
+                completed = true;
+                break;
+            }
+
+            yield chunk;
+
+            // noUncheckedIndexedAccess: индексация массива даёт T | undefined
+            const lastItem = chunk[chunk.length - 1] as Record<string, unknown> | undefined;
+            const cursorValue = Number.parseInt(String(lastItem?.[cursorKey]), 10);
+
+            // Страница непустая, а продолжить её нечем: остановиться тихо — значит
+            // отдать неполную выборку как полную. Бросаем по тому же правилу,
+            // что и callListMethod
+            if (!Number.isFinite(cursorValue)) {
+                throw new Error(`${method}: в строках ответа нет числового идентификатора по ключу «${cursorKey}» — выборка прервана как неполная`);
+            }
+
+            // Курсор обязан расти. Портал, отбросивший неизвестный ключ фильтра,
+            // иначе гонял бы одну и ту же страницу до потолка
+            if (cursorValue <= cursor) {
+                throw new Error(`${method}: портал вернул непродвигающийся курсор (${cursorValue}) при предыдущем ${cursor} — пагинация зациклилась`);
+            }
+
+            cursor = cursorValue;
+            requestParams.filter[moreKey] = cursor;
+        }
+
+        // Обоснование броска то же, что у потолка в callListMethod: обрезанная выборка,
+        // отданная как полная, — худший исход. Тихая остановка здесь неотличима
+        // от нормального завершения `for await`
+        if (!completed) {
+            throw new Error(`${method}: достигнут потолок в ${FETCH_LIST_MAX_PAGES} страниц, портал продолжает отдавать данные — выборка прервана как неполная`);
+        }
+    }
+
+    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;
+}

package/bitrix24/b24/instance.ts

@@ -0,0 +1,186 @@
+import { B24OAuth, Logger, LogLevel } from "@bitrix24/b24jssdk";
+import type { B24OAuthParams, B24OAuthSecret, AuthData, Handler, LogRecord, Formatter, RestrictionParams } from "@bitrix24/b24jssdk";
+import { logs } from "../../logs/logs.ts";
+import { APP_ENV, CLIENT_ID, CLIENT_SECRET, confAuthB24, cleanDomain } from "./config.ts";
+
+// ==================== Константы ====================
+
+/**
+ * Параметры ограничителя 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, а один понятный инвариант дороже трёх сэкономленных попыток.
+ */
+export const SDK_RESTRICTION_PARAMS = {
+    retryOnNetworkError: false,
+    hardErrorCodes: [
+        "ECONNRESET",
+        "ECONNREFUSED",
+        "ENOTFOUND",
+        "ETIMEDOUT",
+        "EHOSTUNREACH",
+        "ENETUNREACH",
+        "EAI_AGAIN",
+        "EPIPE",
+        "EPROTO",
+        "ERR_BAD_RESPONSE",
+    ],
+} as const satisfies RestrictionParams;
+
+// ==================== Логгер SDK ====================
+
+/**
+ * Мост из логгера SDK в `logs` пакета.
+ *
+ * Порог WARNING обязателен: SDK пишет `post/send` и `post/response` на уровне `info`
+ * на каждый запрос и `http batch request starting/completed` на `debug` — без фильтра
+ * это залило бы лог.
+ *
+ * `AbstractHandler` объявлен в типах SDK, но в рантайме не экспортируется,
+ * поэтому реализуем интерфейс `Handler` обычным классом.
+ */
+export 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;
+    }
+
+    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);
+
+            // Лимитер 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";
+
+            // Контекст 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}`);
+        }
+
+        return true;
+    }
+}
+
+// ==================== Создание экземпляра B24OAuth ====================
+
+export 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;
+    }
+
+    if (!CLIENT_ID || !CLIENT_SECRET) {
+        logs.add("Не заданы APP_B24_CLIENT_ID или APP_B24_CLIENT_SECRET в .env", "error");
+        return null;
+    }
+
+    const store = confAuthB24.store as Record<string, AuthData>;
+    const authConfig = store[APP_ENV];
+
+    if (!authConfig?.domain || !authConfig?.access_token || !authConfig?.refresh_token) {
+        logs.add("В конфиге authB24 не хватает данных для авторизации. Сохрани токены через клиент и перезагрузи докер", "error");
+        return null;
+    }
+
+    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;
+}