@andrey4emk/npm-app-back-b24 3.6.1 → 3.7.0

package/README.md

@@ -54,6 +54,7 @@ import {
     reinitializeB24,
     stopProactiveRefresh,
     getResultData,
+    callProtected,
     errorB24,
     event,
     Event,
@@ -122,7 +123,7 @@ const response = await fetchRetry("https://api.example.com/data", { method: "GET
 
 Модуль работает с токенами через файл `authB24.json` (используется библиотека `conf`). Модель БД не требуется.
 
--   **`$b24`** — готовый экземпляр `B24OAuth`, создаётся автоматически при импорте на основе сохранённых токенов. Если данные авторизации отсутствуют — `null`.
+-   **`$b24`** — готовый экземпляр `B24Client` (`B24OAuth` плюс методы фасада, см. ниже), создаётся автоматически при импорте на основе сохранённых токенов. Если данные авторизации отсутствуют — `null`.
 
     ```js
     import { $b24 } from "@andrey4emk/npm-app-back-b24";
@@ -137,9 +138,19 @@ const response = await fetchRetry("https://api.example.com/data", { method: "GET
     -   Окружение (`DEV`/`PROD`) определяется переменной `APP_ENV` — используется как ключ секции в конфиге авторизации.
     -   Признак того, что проект использует OAuth, — заданные `APP_B24_CLIENT_ID` и `APP_B24_CLIENT_SECRET`. Если их нет, `$b24` молча становится `null` (уровень `debug`). Если они заданы, но токенов в `authB24.json` не хватает, пишется `error` — это уже настоящая проблема конфигурации.
 
+    **Методы `callMethod`, `callListMethod`, `fetchListMethod`, `callBatch`, `callBatchByChunk` — фасад пакета.**
+
+    SDK 2.x помечает эти пять методов к удалению в следующем major и на каждый вызов пишет предупреждение об устаревании. Пакет реализует их сам поверх `actions.v2.*`, поэтому вызовы у потребителей не меняются, а зависимости от удаляемого API у пакета больше нет. Сигнатуры и типы возврата прежние — правок в проектах не требуется.
+
+    Поведение прежнее у четырёх методов из пяти. **`callListMethod` отличается в двух местах:** он бросает внятную ошибку с именем метода там, где SDK падал `TypeError` из своих недр (портал вернул «мягкую» ошибку, ответ не список, конверт нечитаем, `next` не растёт), и у него есть потолок в 1000 страниц — при упоре в него вызов тоже бросает, а не отдаёт молча обрезанный список. Если у вас есть `try`/`catch` вокруг постраничных выборок, текст ошибки изменится; если его нет — падение станет заметнее, но не появится там, где раньше всё работало.
+
+    Прямой доступ к `$b24.actions.*` остаётся: это сырой SDK **без** retry и гейта идемпотентности. Если защита нужна, оборачивайте вызов в `callProtected()`.
+
     **Retry при сетевых ошибках:**
 
-    Экземпляр `$b24` обёрнут Proxy, который автоматически повторяет запросы при сетевых ошибках. Повторные попытки применяются к методам `callMethod`, `callListMethod`, `callBatch`, а также к обновлению токена (`refreshAuth`). Метод `fetchListMethod` из ретраев исключён — это async-генератор, оборачивать его в async-функцию нельзя; постраничные запросы SDK ретраит сам.
+    Экземпляр `$b24` обёрнут Proxy, который автоматически повторяет запросы при сетевых ошибках. Повторные попытки применяются к методам `callMethod`, `callListMethod`, `callBatch`, а также к обновлению токена (`refreshAuth`). Метод `fetchListMethod` из ретраев исключён — это async-генератор, оборачивать его в async-функцию нельзя. `callBatchByChunk` пакет реализует, но не ретраит.
+
+    `callListMethod` повторяется целиком: при сетевом сбое пагинация начинается с нулевой страницы заново. Постраничный retry был бы сменой семантики, поэтому поведение оставлено прежним.
 
     | Параметр       | Значение                                  |
     | -------------- | ----------------------------------------- |
@@ -160,6 +171,10 @@ const response = await fetchRetry("https://api.example.com/data", { method: "GET
 
     У самого SDK есть собственный слой ретраев (`maxRetries: 3`), но он работает только при rate limit (HTTP 429, 503) и при распознанных `NETWORK_ERROR` / `REQUEST_TIMEOUT`. Замаскированные транспортные сбои приходят с кодом `JSSDK_UNKNOWN_ERROR`, который входит в `BUILT_IN_HARD_ERROR_CODES` — на таких ошибках SDK делает одну попытку, и повторяет только Proxy.
 
+    **Диагностика SDK.** Начиная с 3.7.0 собственные сообщения SDK от уровня `WARNING` и выше попадают в лог пакета с префиксом `SDK B24:` вместе с контекстом (`requestId`, `method`, `status`, код ошибки) — например предупреждение `fetchList` про игнорируемый `order` или про остановку пагинации, когда `idKey` не совпал с полем ответа. Порог нужен: на уровне `info` SDK пишет две строки на каждый запрос. Ошибки SDK приходят как `warn`, а не `error` — это диагностика отдельной неуспешной попытки, а окончательный провал вызова один раз пишет retry-слой.
+
+    Ответы со статусом 4xx уходят на `debug`: лимитер SDK пишет через свой `error()` любой 4xx кроме 408 и 429, а Bitrix24 отдаёт 400 на штатные «мягкие» ошибки вроде несуществующей сущности. Без этого проверка существования в цикле давала бы строку на каждой итерации. Разбирайте такие ответы через `getResultData()` — это нормальный путь, а не сбой.
+
     **«Мягкие» ошибки Bitrix24:**
 
     Часть ошибок (`ERROR_ENTITY_NOT_FOUND`, `BITRIX_REST_V3_EXCEPTION_*`) SDK не бросает исключением, а возвращает как `AjaxResult` с ошибкой: `isSuccess === false`, и тогда `response.getData()` вернёт `undefined`. Отдельный случай — успешный ответ, у которого сам `result` пустой (`null`/`undefined`). Чтобы не падать на `undefined`, разбирайте ответы через `getResultData()` — он покрывает обе ситуации и бросает понятную ошибку с именем метода.
@@ -244,6 +259,40 @@ const response = await fetchRetry("https://api.example.com/data", { method: "GET
     const deal = getResultData(response, "crm.deal.get");
     ```
 
+-   **`callProtected(run, methodName)`** — прогоняет произвольный вызов `$b24.actions.*` через тот же retry и гейт идемпотентности, что и методы фасада. Нужен, когда требуется API, которого у фасада нет: `FilterV3`, keyset-пагинация (`callTail`/`fetchTail`), `aggregate`.
+
+    -   **Параметры:**
+        -   `run` (`() => Promise<T>`) — сам вызов.
+        -   `methodName` (`string | string[]`) — имя REST-метода B24 (**не** метода SDK) либо список имён, если внутри batch: по ним гейт решает, создаёт ли вызов сущность.
+    -   **Возвращает:** промис с результатом `run`.
+
+    ```js
+    import { $b24, callProtected } from "@andrey4emk/npm-app-back-b24";
+
+    const response = await callProtected(
+        () => $b24.actions.v3.call.make({ method: "crm.item.list", params }),
+        "crm.item.list"
+    );
+
+    // Для batch перечисляйте методы команд, а не "batch"
+    const batchResponse = await callProtected(
+        () => $b24.actions.v3.batch.make({ calls }),
+        ["crm.item.get", "crm.item.add"]
+    );
+    ```
+
+    **Гейт работает fail-closed.** Если список имён пуст или хоть одно имя не похоже на REST-метод (легальные всегда с точкой — `crm.deal.add`, `disk.folder.uploadfile`), вызов считается создающим и не повторяется. Поэтому `callProtected(() => batch.make({ calls }), "batch")` защиту не обойдёт: имя `batch` не разбирается, и батч с `crm.deal.add` внутри не будет повторён пять раз при `status: 0`. Цена ошибки в эту сторону — лишняя необработанная сетевая ошибка; в обратную — дубликаты сущностей.
+
+    Без обёртки вызов `$b24.actions.*` идёт мимо защиты: ни повторов при сетевых сбоях, ни блокировки повтора для создающих методов.
+
+-   **`B24Client`** — экспортируемый тип: `B24OAuth` плюс пять методов, которые пакет реализует сам. Объявлен как `interface B24Client extends B24OAuth`, поэтому `$b24` по-прежнему принимается везде, где ожидается `B24OAuth` — например в `new Smsgold(auth, $b24)`.
+
+    ```ts
+    import type { B24Client } from "@andrey4emk/npm-app-back-b24";
+
+    function sync(client: B24Client) { /* ... */ }
+    ```
+
 ### Задачи ошибок
 
 -   **`errorB24(dataTask)`** — создаёт служебную задачу в Bitrix24 при ошибках/событиях. Использует глобальный `$b24`.

package/bitrix24/b24.ts

@@ -1,5 +1,17 @@
-import { B24OAuth, AjaxError, SdkError, Logger } from "@bitrix24/b24jssdk";
-import type { B24OAuthParams, B24OAuthSecret, AuthData, AjaxResult } from "@bitrix24/b24jssdk";
+import { B24OAuth, AjaxError, SdkError, Logger, LogLevel, Result } from "@bitrix24/b24jssdk";
+import type {
+    B24OAuthParams,
+    B24OAuthSecret,
+    AuthData,
+    AjaxResult,
+    TypeCallParams,
+    BatchCommandsArrayUniversal,
+    BatchCommandsObjectUniversal,
+    BatchNamedCommandsUniversal,
+    Handler,
+    LogRecord,
+    Formatter,
+} from "@bitrix24/b24jssdk";
 import { logs } from "../logs/logs.ts";
 import { isNetworkError, isPreConnectionError } from "../utils/fetchRetry.ts";
 import Conf from "conf";
@@ -17,6 +29,49 @@ interface SaveResult {
     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";
@@ -34,9 +89,21 @@ const RETRY_COUNT = 5;
 /** Задержка между попытками (мс) */
 const RETRY_DELAY_MS = 500;
 
-/** Методы B24OAuth, оборачиваемые retry-логикой (fetchListMethod — async-генератор, его оборачивать нельзя) */
+/** Методы фасада, оборачиваемые 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 — списки совпадали, держать их раздельно смысла нет.
@@ -95,6 +162,102 @@ export function getResultData<T = any>(response: AjaxResult, methodName: string)
     return data.result as T;
 }
 
+/** Конверт ответа restApi:v2 — то, что прислал портал, до того как AjaxResult его урезал */
+interface V2Envelope {
+    result?: unknown;
+    next?: unknown;
+    total?: unknown;
+}
+
+/**
+ * Читает сырой конверт ответа из AjaxResult.
+ *
+ * `getData()` отдаёт замороженную пару `{ result, time }` — полей `next` и `total`
+ * в ней нет намеренно (в restApi:v3 их не существует), а `isMore()`/`getTotal()`/`getNext()`
+ * помечены `@removed 2.0.0` и читают тот же приватный конверт. Единственный способ узнать
+ * смещение следующей страницы, не опираясь на удаляемое API, — прочитать конверт напрямую:
+ * `_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;
+    }
+
+    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.
+            //
+            // Остальное: уровень ERROR у SDK — это диагностика отдельной неуспешной
+            // попытки, а таких попыток на один вызов до пятнадцати (3 внутри SDK × 5 наших).
+            // Уровень error пакета уходит в чат B24, поэтому маппим SDK-ERROR в warn:
+            // окончательный провал вызова логирует retry-слой, и он туда попадёт ровно один раз.
+            const level = status >= 400 && status < 500 ? "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 ====================
 
 function createB24Instance(): B24OAuth | null {
@@ -142,10 +305,11 @@ function createB24Instance(): B24OAuth | null {
 
     const b24 = new B24OAuth(authParams, secret);
 
-    // Логгер без хендлеров: SDK 2.x на каждый вызов callMethod/callBatch пишет
-    // предупреждение об устаревании напрямую в console.warn, если логгер — NullLogger.
-    // Любой другой логгер получает запись через свой интерфейс, поэтому консоль остаётся чистой.
-    b24.setLogger(Logger.create("npm-app-back-b24"));
+    // Диагностика SDK от WARNING и выше уходит в logs пакета: предупреждения
+    // callList/fetchList про игнорируемый order и остановку пагинации, сообщения лимитера.
+    // Дефолтный NullLogger не годится — LoggerFactory.forcedLog пишет мимо логгера
+    // прямо в console.warn, но после перехода на фасад этот путь у нас недостижим.
+    b24.setLogger(Logger.create("npm-app-back-b24").pushHandler(new B24SdkLogHandler()));
 
     return b24;
 }
@@ -415,71 +579,277 @@ function getRetryBlockReason(sdkMethod: string, args: any[]): string | null {
     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);
-        let lastError: unknown;
+        return runWithRetry(() => fn.apply(context, args), `$b24.${methodName}`, blockReason);
+    }) as T;
+}
 
-        for (let attempt = 1; attempt <= RETRY_COUNT; attempt++) {
-            try {
-                return await fn.apply(context, args);
-            } catch (error: unknown) {
-                lastError = error;
+/**
+ * Прогоняет произвольный вызов `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);
 
-                // Ошибка не сетевая (бизнес-логика B24, неверные параметры) — отдаём
-                // вызывающему коду как есть, он решает, что с ней делать
-                if (!isB24NetworkError(error)) throw error;
+    // 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 msg = error instanceof Error ? error.message : String(error);
-                const code = error instanceof SdkError ? ` [${error.code}]` : "";
+    const blockReason = isUnparsed ? "имя метода не разобрано" : blocking.length > 0 ? blocking.join(", ") : null;
 
-                // Окончательные отказы логируем на error: собственные модули пакета
-                // (errorB24, Event, Smsgold) ошибку только возвращают вызывающему коду,
-                // но не пишут в лог — без этих строк сбой $b24 не виден нигде
+    return runWithRetry(run, `actions:${names.join(", ") || "имя не указано"}`, blockReason);
+}
 
-                if (attempt === RETRY_COUNT) {
-                    logs.add(`$b24.${methodName}${code}: исчерпаны все ${RETRY_COUNT} попыток — ${msg}`, "error");
-                    throw error;
-                }
+// ==================== Фасад поверх actions.v2.* ====================
 
-                // Ошибка со status 0 может означать и «запрос не ушёл», и «запрос выполнен,
-                // а ответ не разобрался»: различить их нельзя, поэтому создающие вызовы
-                // не повторяем — лучше вернуть ошибку, чем создать дубликат
-                if (blockReason) {
-                    logs.add(`$b24.${methodName}${code}: повтор отменён, вызов создаёт сущности (${blockReason}) — ${msg}`, "error");
-                    throw error;
-                }
+/**
+ * Собственные реализации пяти методов, которые 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
+        if (!("start" in merged && Number.isInteger(merged.start)) && 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;
+            }
 
-                // Промежуточные попытки — warn: в чат B24 уходит только уровень error,
-                // иначе один упавший вызов дал бы пять сообщений
-                logs.add(`$b24.${methodName}${code}: попытка ${attempt}/${RETRY_COUNT} не удалась (${msg}), повтор через ${RETRY_DELAY_MS}мс`, "warn");
+            const nextStart = Number(envelope.next);
 
-                await delay(RETRY_DELAY_MS);
+            // 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);
             }
         }
 
-        // Недостижимо при RETRY_COUNT >= 1, нужно для TypeScript
-        throw lastError;
-    }) as T;
+        // Обрезанный список, отданный как успешный, — худший исход: потребитель
+        // примет неполную выборку за полную. Поэтому бросаем, а не логируем:
+        // 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[]> {
+        yield* v2().fetchList.make<any>({
+            method,
+            params,
+            idKey,
+            customKeyForResult: customKeyForResult === null ? 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.
  *
- * Методы из RETRYABLE_METHODS оборачиваются retry-логикой, все остальные
- * привязываются к оригинальному объекту через bind: класс B24OAuth использует
- * приватные поля (#authOAuthManager), и при вызове метода с this === Proxy
- * движок бросает "Cannot read private member".
+ * Имена из FACADE_METHODS резолвятся в собственные реализации пакета поверх
+ * `actions.v2.*`; из них методы RETRYABLE_METHODS дополнительно оборачиваются
+ * retry-логикой. Все остальные методы привязываются к оригинальному объекту
+ * через bind: класс B24OAuth использует приватные поля (#authOAuthManager),
+ * и при вызове метода с this === Proxy движок бросает "Cannot read private member".
  *
  * Обёртки кешируются — по одной на метод, чтобы не ломать сравнение по ссылке.
  */
-function wrapB24WithRetry(b24: B24OAuth): B24OAuth {
+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);
@@ -497,13 +867,21 @@ function wrapB24WithRetry(b24: B24OAuth): B24OAuth {
 
             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 = _b24Raw ? wrapB24WithRetry(_b24Raw) : null;
+export let $b24: B24Client | null = _b24Raw ? wrapB24WithRetry(_b24Raw) : null;
 
 /** Настраивает колбэк автосохранения токенов на экземпляре B24OAuth */
 function setupRefreshCallback(raw: B24OAuth): void {

package/bitrix24/eventB24.ts

@@ -1,5 +1,4 @@
-import type { B24OAuth } from "@bitrix24/b24jssdk";
-import { $b24, getResultData } from "./b24.ts";
+import { $b24, getResultData, type B24MethodCaller } from "./b24.ts";
 
 // ==================== Типы ====================
 
@@ -83,14 +82,16 @@ function normalizeMessages(messages: unknown): any[] {
  * Класс для работы с офлайн-событиями Bitrix24
  */
 export class Event {
-    private b24: B24OAuth;
+    // Структурный тип, а не B24OAuth: объявляет callMethod сам, поэтому переживёт
+    // удаление метода из SDK. Сигнатуру конструктора не сужает — она стала шире
+    private b24: B24MethodCaller;
 
     /** Расширения видео-файлов */
     private static readonly VIDEO_EXTENSIONS = ["mp4", "mov", "avi", "mkv", "webm", "3gp", "m4v"];
     /** Расширения изображений */
     private static readonly IMAGE_EXTENSIONS = ["jpg", "jpeg", "png", "gif", "webp", "bmp"];
 
-    constructor(b24: B24OAuth) {
+    constructor(b24: B24MethodCaller) {
         if (!b24 || typeof b24.callMethod !== "function") {
             throw new Error("Event: передали некорректный b24 или не передали вообще");
         }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@andrey4emk/npm-app-back-b24",
-    "version": "3.6.1",
+    "version": "3.7.0",
     "description": "Bitrix24 OAuth helpers for Node.js projects",
     "main": "index.ts",
     "type": "module",

package/sendMessage/smsgold.ts

@@ -1,5 +1,4 @@
-import type { B24OAuth } from "@bitrix24/b24jssdk";
-import { getResultData } from "../bitrix24/b24.ts";
+import { getResultData, type B24MethodCaller } from "../bitrix24/b24.ts";
 import { fetchRetry } from "../utils/fetchRetry.ts";
 
 // ==================== Типы ====================
@@ -35,9 +34,11 @@ interface SmsResult {
 export class Smsgold {
     private user: string;
     private pass: string;
-    private b24: B24OAuth | null;
+    // Структурный тип, а не B24OAuth: объявляет callMethod сам, поэтому переживёт
+    // удаление метода из SDK. Сигнатуру конструктора не сужает — она стала шире
+    private b24: B24MethodCaller | null;
 
-    constructor(authParam: SmsgoldAuthParam, b24: B24OAuth | null = null) {
+    constructor(authParam: SmsgoldAuthParam, b24: B24MethodCaller | null = null) {
         this.user = authParam.user;
         this.pass = authParam.pass;
         this.b24 = b24;