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

package/bitrix24/b24/proxy.ts

@@ -0,0 +1,120 @@
+import type { B24OAuth } from "@bitrix24/b24jssdk";
+import { createFacade } from "./facade.ts";
+import { withRetry } from "./retry.ts";
+import type { AsyncFn } from "./retry.ts";
+import type { B24Client, FacadeMethods } from "./types.ts";
+
+// ==================== Константы и типы ====================
+
+/** Имя метода, который Proxy резолвит в реализацию пакета */
+type FacadeMethodName = keyof FacadeMethods;
+
+/** Методы фасада, оборачиваемые retry-логикой (fetchListMethod — async-генератор, его оборачивать нельзя) */
+const RETRYABLE_METHOD_NAMES = ["callMethod", "callListMethod", "callBatch"] as const;
+
+/**
+ * Имена, которые Proxy резолвит в собственную реализацию пакета поверх `actions.v2.*`.
+ *
+ * Шире, чем RETRYABLE_METHOD_NAMES: `fetchListMethod` и `callBatchByChunk` мы реализуем,
+ * но не ретраим. `callBatchByChunk` в наборе обязателен — пока хоть один deprecated-метод
+ * SDK достижим через `$b24`, он будет писать предупреждение об устаревании.
+ *
+ * `satisfies` ловит опечатку и переименование: имя, которого нет среди методов фасада,
+ * уронит тайпчек здесь, а не молча уедет мимо Proxy в SDK.
+ */
+const FACADE_METHOD_NAMES = ["callMethod", "callListMethod", "fetchListMethod", "callBatch", "callBatchByChunk"] as const satisfies readonly FacadeMethodName[];
+
+/**
+ * Обратная страховка к `satisfies` выше: ловит НЕдостачу.
+ * Забыли имя — `Exclude` перестанет быть `never`, и тип станет `never`,
+ * а `true` в него не присвоится. Значение нигде не используется
+ */
+const _facadeNamesAreExhaustive: Exclude<FacadeMethodName, (typeof FACADE_METHOD_NAMES)[number]> extends never ? true : never = true;
+void _facadeNamesAreExhaustive;
+
+/**
+ * Имя метода фасада, который дополнительно оборачивается retry.
+ *
+ * Уже, чем `FacadeMethodName`: `fetchListMethod` — async-генератор, он возвращает
+ * не `Promise`, под `AsyncFn` не подходит и в `withRetry` не попадает даже по типу.
+ * Тип выведен из самого списка, поэтому список и тип разойтись не могут
+ */
+type RetryableMethodName = (typeof RETRYABLE_METHOD_NAMES)[number];
+
+/** Тип `ReadonlySet<string>`, а не `Set<RetryableMethodName>`: `has()` вызывается с произвольным ключом Proxy */
+export const RETRYABLE_METHODS: ReadonlySet<string> = new Set<string>(RETRYABLE_METHOD_NAMES);
+
+/** См. FACADE_METHOD_NAMES */
+export const FACADE_METHODS: ReadonlySet<string> = new Set<string>(FACADE_METHOD_NAMES);
+
+/** Метод резолвится в реализацию пакета, а не SDK */
+function isFacadeMethod(prop: string): prop is FacadeMethodName {
+    return FACADE_METHODS.has(prop);
+}
+
+/** Метод фасада оборачивается retry-логикой */
+function isRetryableMethod(prop: string): prop is RetryableMethodName {
+    return RETRYABLE_METHODS.has(prop);
+}
+
+// ==================== Proxy-обёртка ====================
+
+/**
+ * Proxy-обёртка вокруг B24OAuth.
+ *
+ * Имена из FACADE_METHODS резолвятся в собственные реализации пакета поверх
+ * `actions.v2.*`; из них методы RETRYABLE_METHODS дополнительно оборачиваются
+ * retry-логикой. Все остальные методы привязываются к оригинальному объекту
+ * через bind: класс B24OAuth использует приватные поля (#authOAuthManager),
+ * и при вызове метода с this === Proxy движок бросает "Cannot read private member".
+ *
+ * Обёртки кешируются — по одной на метод, чтобы не ломать сравнение по ссылке.
+ */
+export 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" && isFacadeMethod(prop)) {
+                if (!methodCache.has(prop)) {
+                    // Индексируем внутри ветки: после сужения prop до RetryableMethodName
+                    // из типа facade[prop] уходит fetchListMethod, и withRetry принимает
+                    // остаток без приведения
+                    methodCache.set(prop, isRetryableMethod(prop) ? withRetry(facade[prop], target, prop) : facade[prop]);
+                }
+
+                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 AsyncFn, 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;
+}

package/bitrix24/b24/retry.ts

@@ -0,0 +1,490 @@
+import { AjaxError, RefreshTokenError, SdkError } from "@bitrix24/b24jssdk";
+import { logs } from "../../logs/logs.ts";
+import { isNetworkError, isPreConnectionError } from "../../utils/fetchRetry.ts";
+
+// ==================== Типы ====================
+
+/**
+ * Любая асинхронная функция.
+ *
+ * `never[]` в параметрах делает тип надмножеством всех сигнатур: `never`
+ * присваивается чему угодно, поэтому под ограничение подходит и `callMethod`,
+ * и `callBatch`. Возврат `Promise<unknown>` отсекает `fetchListMethod` —
+ * это async-генератор, и оборачивать его retry-обёрткой нельзя (`for await` ломается).
+ */
+export type AsyncFn = (...args: never[]) => Promise<unknown>;
+
+// ==================== Константы ====================
+
+/** Количество попыток при сетевых ошибках */
+export const RETRY_COUNT = 5;
+/** Задержка между попытками (мс) */
+export const RETRY_DELAY_MS = 500;
+
+/**
+ * Коды транспортного сбоя. Один набор и для SdkError (AjaxError, RefreshTokenError),
+ * и для вложенного AxiosError — списки совпадали, держать их раздельно смысла нет.
+ */
+export const NETWORK_ERROR_CODES = new Set(["NETWORK_ERROR", "REQUEST_TIMEOUT", "ERR_NETWORK", "ECONNABORTED"]);
+
+/**
+ * REST-методы B24, повтор которых создаёт дубликат сущности или запускает
+ * повторное действие: add, create, start, send, uploadfile, import, register.
+ *
+ * Транспортная ошибка не говорит, дошёл ли запрос до портала: обрыв приходит
+ * и когда соединение не состоялось, и когда оно оборвалось после того, как портал уже
+ * принял и выполнил запрос. Во втором случае retry создаст вторую задачу, второй файл,
+ * второй экземпляр бизнес-процесса. Идемпотентные записи (update, delete, set) повторять
+ * безопасно: повторное применение даёт то же состояние. При доказанном pre-connection
+ * (isPreConnectionError) ограничение снимается: соединение с целевым хостом не состоялось,
+ * портал запроса не видел, и дубликата повтор дать не может.
+ *
+ * По той же причине у SDK отключены собственные повторы транспортных сбоев
+ * (SDK_RESTRICTION_PARAMS) — он этой разницы не знает вовсе.
+ *
+ * Ключевое слово ловится **в любой позиции** имени, а не только в конце. Иначе мимо
+ * гейта проходил `imconnector.send.messages` (дефект T-48) — метод создаёт в открытой
+ * линии сообщение внешней системы. Дедупликация по `message.id` в документации портала
+ * не описана, поэтому повтор считаем задваивающим переписку у оператора — fail-closed.
+ * После ключевого слова обязателен разделитель (`.`, `?` или конец строки), поэтому
+ * `crm.deal.addcustom`, `landing.landing.addbytemplate` и `tasks.task.result.addresult`
+ * по-прежнему повторяются. Отдельная группа `(\.json)?` больше не нужна: хвост `.json`
+ * покрывается общей веткой `\.`.
+ *
+ * Побочный улов расширения — `imconnector.send.status.delivery`: он лишь помечает уже
+ * отправленное сообщение доставленным и, скорее всего, идемпотентен. Повторяться он
+ * перестанет, и это осознанная плата за правило без списка исключений: потеря отметки
+ * о доставке косметическая, переписку она не ломает, а ручной список молча устаревал бы
+ * при появлении нового метода портала — ровно тот дефект, которым T-48 и был.
+ */
+export const NON_IDEMPOTENT_METHOD_RE = /\.(add|create|start|send|uploadfile|import|register)(\.|\?|$)/i;
+
+/**
+ * Методы, повтор которых теряет данные, хотя сущностей не создаёт.
+ * Совпадение точное, по имени целиком (после нормализации), а не по префиксу.
+ *
+ * `event.offline.get` резервирует пакет очереди офлайн-событий и прячет его от следующих
+ * запросов. Если ответ первой попытки потерян по дороге, `process_id` пакета не узнает
+ * никто: записи висят зарезервированными до автоудаления через 30 дней и повторно
+ * не выдаются.
+ *
+ * Ограничение действует независимо от параметра `clear`, и вот почему:
+ *
+ * 1. при `clear: 0` первый вызов резервирует пакет и прячет его от следующих запросов —
+ *    потерянный ответ уносит `process_id` с собой;
+ * 2. при `clear: 1` портал отдаёт записи и тут же удаляет их — потерянный ответ уносит
+ *    их безвозвратно, то есть повтор так же теряет пакет, только иначе;
+ * 3. разбор по параметрам означал бы чтение `args[1]` в гейте, который смотрит только
+ *    на имя, — лишняя сложность ради ветки, где обе стороны одинаково плохи;
+ * 4. fail-closed дешевле: единственный потребитель опрашивает очередь по таймеру,
+ *    следующий опрос всё равно будет.
+ *
+ * Чего правка **не** делает: она не спасает первый потерянный пакет — он уже
+ * зарезервирован. Она предотвращает вторую потерю, то есть повтор, который зарезервировал
+ * бы ещё один пакет поверх первого. Ограничение действует только на слой пакета:
+ * собственный цикл повторов SDK (429, 503, неизвестные 5xx) под него не попадает —
+ * при 503 лимитер считает ответ временным отказом раньше, чем смотрит на hardErrorCodes,
+ * и делает свои три запроса, см. T-44.
+ *
+ * При доказанном pre-connection (соединение не состоялось) ограничение снимается вместе
+ * с гейтом идемпотентности: портал запроса не видел, резервировать было нечего.
+ */
+export const NON_RETRYABLE_METHODS = new Set(["event.offline.get"]);
+
+/** Префикс кодов, которыми SDK помечает собственные отказы обмена refresh-токена */
+const OAUTH_REFRESH_CODE_PREFIX = "JSSDK_OAUTH_TOKEN_REFRESH";
+
+// ==================== Утилиты ====================
+
+/** Задержка на указанное количество миллисекунд */
+export const delay = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Приводит имя REST-метода к виду, пригодному для точного сравнения:
+ * без пробелов по краям, без регистра, без хвоста `?query` и без расширения `.json`.
+ *
+ * Нужна списку NON_RETRYABLE_METHODS: он сравнивает имя целиком, а до него имя доезжает
+ * в любой из форм — `event.offline.get`, `Event.Offline.Get`, `event.offline.get.json`,
+ * `event.offline.get?clear=0`.
+ */
+function normalizeMethodName(raw: string): string {
+    // noUncheckedIndexedAccess: индексация массива даёт string | undefined
+    const head = raw.trim().toLowerCase().split("?")[0] ?? "";
+    return head.replace(/\.json$/, "");
+}
+
+/** Фраза для лога: повтор отменён, потому что вызов создаёт сущности */
+const creatingReason = (what: string): string => `вызов создаёт сущности (${what})`;
+
+/** Фраза для лога: повтор отменён, потому что вызов резервирует данные на портале */
+const reservingReason = (what: string): string => `вызов резервирует данные на портале (${what})`;
+
+// ==================== Retry-обёртка ====================
+
+/**
+ * Проверяет, является ли ошибка из SDK сетевой.
+ *
+ * Форма транспортного сбоя в Node: до нас доезжает **сырой errno** — ENOTFOUND,
+ * ECONNREFUSED, ECONNRESET со status 0. Ветки NETWORK_ERROR и REQUEST_TIMEOUT в SDK
+ * рассчитаны на другое: первая подставляется только при axios-коде ERR_NETWORK
+ * (браузерный адаптер), вторая — при ECONNABORTED. Node-адаптер зовёт
+ * `AxiosError.from(err, null, ...)`, и код остаётся исходным errno. Держим оба набора:
+ * сырые коды ловит последняя строка через isNetworkError(), а именованные — набор
+ * NETWORK_ERROR_CODES.
+ *
+ * Проверку по status 0 оставляем: она ловит всё, что SDK отдаёт без внятного кода.
+ * Сюда же попадает провал обновления токена внутри callMethod: SDK перезаворачивает
+ * SdkError в AjaxError с кодом JSSDK_UNKNOWN_ERROR и status 0, а исходную ошибку кладёт
+ * в originalError. RefreshTokenError приходит как SdkError с кодом вроде ENOTFOUND;
+ * при status 500 такая ошибка признаётся сетевой не веткой status === 0, а последней
+ * строкой — код есть в списке utils/fetchRetry.ts.
+ *
+ * Сетевой провал обмена токена остаётся, а повторяться перестаёт: решение принимает
+ * runWithRetry через isTokenRefreshFailure(). Классификация «сетевая ли ошибка»
+ * и решение «повторять ли её» — разные вопросы, и смешивать их здесь нельзя: иначе
+ * ошибка ушла бы наружу первой веткой цикла, без единой строки в логе.
+ */
+export 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);
+}
+
+/**
+ * Провалился ли внутри вызова обмен refresh-токена.
+ *
+ * SDK перезаворачивает такую ошибку в `_convertUnknownErrorToAjaxError`
+ * (`core/http/abstract-http.mjs`): RefreshTokenError наследует SdkError, а не AjaxError
+ * и не AxiosError, поэтому попадает в ветку «неизвестная ошибка» и **кладётся целиком
+ * в originalError**. Снаружи всегда одно и то же — AjaxError JSSDK_UNKNOWN_ERROR
+ * со status 0, а исходная причина различима внутри:
+ *
+ * | Что случилось при обмене | originalError |
+ * |---|---|
+ * | oauth-хост не резолвится | RefreshTokenError ENOTFOUND, status 0 |
+ * | oauth-хост отверг соединение | RefreshTokenError ECONNREFUSED, status 0 |
+ * | 400 invalid_grant (мёртвый токен) | RefreshTokenError invalid_grant, status 400 |
+ * | 500 от oauth-хоста | RefreshTokenError ERR_BAD_RESPONSE, status 500 |
+ * | 200 с полем error в теле | SdkError JSSDK_OAUTH_TOKEN_REFRESH_FAILED, status 0 |
+ *
+ * Форма одна и та же независимо от того, откуда запустился обмен: после 401 от портала
+ * (`_makeRequestWithAuthRetry`) или заранее, из-за протухшего `expires` (`_ensureAuth`).
+ * Обе ветки зовут `_refreshAuth()` и бросают в один catch метода `call()`.
+ *
+ * Две ловушки, из-за которых разбор выглядит именно так:
+ *
+ * - RefreshTokenError **не переопределяет `name`** — у экземпляра `name === "SdkError"`,
+ *   и проверка по имени не работает. Работают instanceof и constructor.name;
+ * - последняя строка таблицы даёт не RefreshTokenError, а голый SdkError с кодом
+ *   из семейства JSSDK_OAUTH_TOKEN_REFRESH_* — её ловим отдельно.
+ *
+ * Запасная проверка по constructor.name нужна на случай двух копий SDK в node_modules
+ * у потребителя: instanceof тогда промахнётся. Промах дешёвый — поведение откатится
+ * к прежнему (пять попыток и шум в логе), данные не пострадают.
+ *
+ * @param error — пойманная ошибка
+ * @returns true, если внутри лежит отказ обмена refresh-токена
+ */
+export function isTokenRefreshFailure(error: unknown): boolean {
+    if (!(error instanceof SdkError)) return false;
+
+    const { originalError } = error;
+    if (!originalError || typeof originalError !== "object") return false;
+
+    if (originalError instanceof RefreshTokenError) return true;
+    if (originalError.constructor?.name === "RefreshTokenError") return true;
+
+    return originalError instanceof SdkError && originalError.code.startsWith(OAUTH_REFRESH_CODE_PREFIX);
+}
+
+/**
+ * Код исходной ошибки обмена токена со статусом ответа oauth-хоста, если он известен:
+ * `invalid_grant/400`, `ERR_BAD_RESPONSE/503`, `ENOTFOUND`,
+ * `JSSDK_OAUTH_TOKEN_REFRESH_FAILED`.
+ *
+ * Нужен лог-строке: код внешней ошибки всегда JSSDK_UNKNOWN_ERROR и для разбора
+ * инцидента бесполезен.
+ *
+ * Статус дописывается потому, что без него один код накрывает разные инциденты:
+ * `ERR_BAD_RESPONSE` одинаков для 500 и 503, `ERR_BAD_REQUEST` — для 429 и прочих 4xx.
+ * По логу нельзя отличить «токен мёртв, нужна переавторизация» от «oauth-хост занят,
+ * пройдёт само», а это первый вопрос дежурного. Доступ законный: `status` у `SdkError` —
+ * публичный геттер. При status 0, отсутствующем или нечисловом хвоста нет: ноль SDK
+ * ставит транспортному сбою, где статуса ответа не существует.
+ */
+export function refreshFailureCode(error: unknown): string {
+    const originalError = error instanceof SdkError ? error.originalError : undefined;
+    const code = (originalError as { code?: unknown } | undefined)?.code;
+
+    if (typeof code !== "string" || code.length === 0) return "код неизвестен";
+
+    const status = (originalError as { status?: unknown } | undefined)?.status;
+
+    return typeof status === "number" && Number.isFinite(status) && status > 0 ? `${code}/${status}` : code;
+}
+
+/**
+ * Достаёт имя REST-метода из одной команды batch.
+ * Возвращает null, если форма команды не распознана.
+ */
+export 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;
+}
+
+/** К какому виду ограничения относится имя метода */
+type MethodRestriction = "creating" | "reserving" | null;
+
+/** Классифицирует одно имя REST-метода: создаёт, резервирует либо повторяется свободно */
+function classifyMethod(name: string): MethodRestriction {
+    if (NON_RETRYABLE_METHODS.has(normalizeMethodName(name))) return "reserving";
+    if (NON_IDEMPOTENT_METHOD_RE.test(name)) return "creating";
+
+    return null;
+}
+
+/**
+ * Собирает итоговую фразу причины из двух списков имён.
+ *
+ * Порядок фиксирован — сначала создающие, потом резервирующие: лог-строка должна быть
+ * одинаковой при одинаковом составе вызова.
+ */
+function joinReasons(creating: string[], reserving: string[]): string | null {
+    const phrases: string[] = [];
+
+    if (creating.length > 0) phrases.push(creatingReason(creating.join(", ")));
+    if (reserving.length > 0) phrases.push(reservingReason(reserving.join(", ")));
+
+    return phrases.length > 0 ? phrases.join("; ") : null;
+}
+
+/**
+ * Возвращает готовую фразу причины, по которой вызов запрещено повторять, либо null.
+ *
+ * Функция отдаёт именно фразу, а не имя метода: причин теперь две (вызов создаёт
+ * сущности либо резервирует данные на портале), и шаблон в лог-строке соврал бы про
+ * `event.offline.get` — он ничего не создаёт. runWithRetry дописывает вокруг только
+ * «повтор отменён, ...», поэтому строки для создающих вызовов остались прежними
+ * до последнего байта: по ним грепают в логах и на них настроены триггеры задач.
+ *
+ * Для callBatch действует правило fail-closed: если хоть одну команду разобрать
+ * не удалось, вызов считается создающим. Ошибиться в сторону лишней осторожности
+ * дешевле — потребитель получит ошибку вместо тихого дубликата.
+ */
+export function getRetryBlockReason(sdkMethod: string, args: readonly unknown[]): string | null {
+    const first = args[0];
+
+    // callMethod(method, params) и callListMethod(method, params, ...)
+    if (sdkMethod === "callMethod" || sdkMethod === "callListMethod") {
+        if (typeof first !== "string") return null;
+
+        // В фразу идёт имя, которое реально передали (без пробелов по краям),
+        // а не нормализованное: в логе полезнее видеть исходную форму
+        const name = first.trim();
+        const restriction = classifyMethod(name);
+
+        if (restriction === "creating") return creatingReason(name);
+        if (restriction === "reserving") return reservingReason(name);
+
+        return null;
+    }
+
+    if (sdkMethod !== "callBatch") return null;
+
+    // callBatch(calls, ...) — команды приходят массивом либо объектом-словарём
+    if (!first || typeof first !== "object") {
+        return creatingReason("аргументы batch не разобраны");
+    }
+
+    const commands: unknown[] = Array.isArray(first) ? first : Object.values(first);
+    const creating: string[] = [];
+    const reserving: string[] = [];
+
+    for (const cmd of commands) {
+        const method = extractBatchCommandMethod(cmd);
+
+        if (method === null) return creatingReason("команда batch не разобрана");
+
+        const name = method.trim();
+        const restriction = classifyMethod(name);
+
+        if (restriction === "creating") creating.push(name);
+        if (restriction === "reserving") reserving.push(name);
+    }
+
+    return joinReasons(creating, reserving);
+}
+
+/**
+ * Общий цикл повторов при сетевых ошибках.
+ *
+ * Из цикла есть три выхода без повтора:
+ *
+ * 1. ошибка не сетевая — уходит наружу как есть, без записи в лог;
+ * 2. провал обмена refresh-токена, не доказанный pre-connection — строка error и бросок:
+ *    повтор небезопасен, потому что соединение состоялось, сервер мог провести ротацию,
+ *    и тогда локальный refresh-токен мёртв независимо от повтора. Транзиентные отказы
+ *    oauth-хоста (429, 503) под правило попадают тоже — различить их от ротации
+ *    по ответу нельзя;
+ * 3. действует ограничение (blockReason) и pre-connection не доказан — строка error
+ *    и бросок.
+ *
+ * Доказанный pre-connection (`isPreConnectionError`) снимает ограничение: DNS не
+ * разрешился или хост отверг соединение, значит соединение с целевым хостом не состоялось
+ * и повтор дубликата создать не может. Это единственное основание повторить то, что
+ * повторять вообще-то нельзя, — то же правило действует и в обмене refresh-токена.
+ *
+ * @param fn — вызов без аргументов, уже замкнутый на нужные параметры
+ * @param label — префикс лог-строк, по нему в логе видно источник повтора
+ * @param blockReason — готовая фраза причины, по которой повтор запрещён, либо null
+ */
+export 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}]` : "";
+
+            // Соединение с целевым хостом не состоялось: повторять безопасно
+            // даже создающий вызов
+            const proven = isPreConnectionError(error);
+
+            // Окончательные отказы логируем на error: собственные модули пакета
+            // (errorB24, Event, Smsgold) ошибку только возвращают вызывающему коду,
+            // но не пишут в лог — без этих строк сбой $b24 не виден нигде
+
+            // Ветка обмена токена стоит до проверки исчерпания попыток: иначе она
+            // сработала бы только на пятой попытке, ради чего всё и затевалось
+            if (!proven && isTokenRefreshFailure(error)) {
+                logs.add(`${label}${code}: обновление токена не удалось (${refreshFailureCode(error)}), повтор небезопасен: сервер мог провести ротацию — ${msg}`, "error");
+                throw error;
+            }
+
+            if (attempt === RETRY_COUNT) {
+                logs.add(`${label}${code}: исчерпаны все ${RETRY_COUNT} попыток — ${msg}`, "error");
+                throw error;
+            }
+
+            // Обрыв и таймаут не говорят, дошёл ли запрос до портала: ответ мог
+            // потеряться уже после того, как портал его выполнил. Различить нельзя,
+            // поэтому вызовы под ограничением не повторяем — лучше вернуть ошибку,
+            // чем создать дубликат или потерять зарезервированный пакет
+            if (blockReason && !proven) {
+                logs.add(`${label}${code}: повтор отменён, ${blockReason} — ${msg}`, "error");
+                throw error;
+            }
+
+            // Начало строки менять нельзя: по «попытка N/5 не удалась» грепают в логах
+            const lifted = blockReason ? ` — соединение не состоялось, ограничение (${blockReason}) снято` : "";
+
+            // Промежуточные попытки — warn: в чат B24 уходит только уровень error,
+            // иначе один упавший вызов дал бы пять сообщений
+            logs.add(`${label}${code}: попытка ${attempt}/${RETRY_COUNT} не удалась (${msg}), повтор через ${RETRY_DELAY_MS}мс${lifted}`, "warn");
+
+            await delay(RETRY_DELAY_MS);
+        }
+    }
+
+    // Недостижимо при RETRY_COUNT >= 1, нужно для TypeScript
+    throw lastError;
+}
+
+/** Оборачивает async-функцию retry-логикой при сетевых ошибках */
+export function withRetry<T extends AsyncFn>(fn: T, context: object, methodName: string): T {
+    return (async (...args: Parameters<T>) => {
+        // Состав вызова между попытками не меняется — разбираем один раз
+        const blockReason = getRetryBlockReason(methodName, args as readonly unknown[]);
+        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 creating = names.filter((name) => classifyMethod(name) === "creating");
+    const reserving = names.filter((name) => classifyMethod(name) === "reserving");
+
+    const blockReason = isUnparsed ? creatingReason("имя метода не разобрано") : joinReasons(creating, reserving);
+
+    return runWithRetry(run, `actions:${names.join(", ") || "имя не указано"}`, blockReason);
+}

package/bitrix24/b24/state.ts

@@ -0,0 +1,39 @@
+import type { B24OAuth } from "@bitrix24/b24jssdk";
+import type { B24Client } from "./types.ts";
+
+// ==================== Состояние экземпляра ====================
+
+/**
+ * @module
+ * Владелец обоих слоёв экземпляра B24.
+ *
+ * Модуль-лист: не импортирует ничего, кроме типов. Так решается цикл, который иначе
+ * возник бы между `tokens.ts` и `b24.ts` — первый читает `$b24` в `refreshAuthWithMutex`,
+ * второй переприсваивает его в `reinitializeB24()`.
+ *
+ * ESM отдаёт живые связывания, и они переживают два реэкспорта подряд
+ * (`state.ts` → `b24.ts` → `index.ts`), поэтому переприсваивание видно потребителю
+ * без единой правки на его стороне.
+ */
+
+/** Обёрнутый Proxy экземпляр — то, с чем работает потребитель */
+export let $b24: B24Client | null = null;
+
+/** Оригинальный B24OAuth без Proxy: на него вешается setCallbackRefreshAuth */
+export let b24Raw: B24OAuth | null = null;
+
+/**
+ * Единственная точка записи обоих слоёв.
+ *
+ * Сегодня `b24Raw` в коде пакета не читает никто: `b24.ts` вешает
+ * `setCallbackRefreshAuth` на локальную `raw` / `initialRaw` — тот же объект, но своя
+ * переменная. Поле держит ссылку на неупакованный экземпляр и читается тестом
+ * (`tests/state-binding.test.ts`).
+ *
+ * Единый сеттер нужен на будущее: с раздельными сеттерами читатель `b24Raw` мог бы
+ * получить слои от разных экземпляров — `$b24` от прежнего рядом с новым `b24Raw`.
+ */
+export function setB24Instance(raw: B24OAuth | null, client: B24Client | null): void {
+    b24Raw = raw;
+    $b24 = client;
+}