@andrey4emk/npm-app-back-b24 4.0.2 → 5.1.0

package/README.md

@@ -17,6 +17,8 @@
     -   [Логирование](#логирование)
     -   [fetchRetry и таймауты](#fetchretry-и-таймауты)
 -   [Переменные окружения](#переменные-окружения)
+-   [Миграция на 5.1.0](#миграция-на-510)
+-   [Миграция на 5.0.0](#миграция-на-500)
 -   [Миграция на 4.0.0](#миграция-на-400)
 -   [Скрипты](#скрипты)
 -   [Лицензия](#лицензия)
@@ -27,6 +29,8 @@
 npm install @andrey4emk/npm-app-back-b24
 ```
 
+Нужен Node.js 22 или новее (с 5.0.0 — его требует `@bitrix24/b24jssdk` 3.0.0).
+
 `nodemailer` — **опциональная peer-зависимость**: её ставит потребитель, и только если пользуется классом `Email`. Всем остальным она не нужна и не приезжает.
 
 ```bash
@@ -207,7 +211,7 @@ const sent = await fetchWithTimeout("https://api.example.com/send", { method: "P
 
     **Методы `callMethod`, `callListMethod`, `fetchListMethod`, `callBatch`, `callBatchByChunk` — фасад пакета.**
 
-    SDK 2.x помечает эти пять методов к удалению в следующем major и на каждый вызов пишет предупреждение об устаревании. Пакет реализует их сам поверх `actions.v2.*`, поэтому вызовы у потребителей не меняются, а зависимости от удаляемого API у пакета больше нет. Сигнатуры и типы возврата прежние — правок в проектах не требуется.
+    В SDK 3.0.0 этих пяти методов нет. Пакет реализует их сам поверх `actions.v2.*`, поэтому вызовы у потребителей не меняются, а зависимости от удалённого API у пакета нет. Сигнатуры и типы возврата прежние — правок в проектах не требуется.
 
     Поведение прежнее у четырёх методов из пяти. **`callListMethod` отличается в двух местах:** он бросает внятную ошибку с именем метода там, где SDK падал `TypeError` из своих недр (портал вернул «мягкую» ошибку, ответ не список, конверт нечитаем, `next` не растёт), и у него есть потолок в 1000 страниц — при упоре в него вызов тоже бросает, а не отдаёт молча обрезанный список. Если у вас есть `try`/`catch` вокруг постраничных выборок, текст ошибки изменится; если его нет — падение станет заметнее, но не появится там, где раньше всё работало.
 
@@ -236,7 +240,7 @@ const sent = await fetchWithTimeout("https://api.example.com/send", { method: "P
 
     Retry срабатывает только при сетевых проблемах (`ECONNRESET`, `ETIMEDOUT`, `ERR_NETWORK` и т.д.). HTTP-ошибки (400, 500) и ошибки бизнес-логики Bitrix24 **не** вызывают повторных попыток.
 
-    **Уровни логов.** Промежуточные попытки пишутся на `warn`, окончательный отказ — на `error`: исчерпание всех попыток и отмена повтора гейтом. Так один упавший вызов даёт одно сообщение в чат B24 вместо пяти, но при этом не теряется совсем. Логировать провал обязан сам Proxy: `errorB24()`, `Event` и `Smsgold` ошибку только возвращают вызывающему коду и в лог не пишут.
+    **Уровни логов.** Промежуточные попытки пишутся на `warn`, окончательный отказ — на `error`: исчерпание всех попыток и отмена повтора гейтом. Так один упавший вызов даёт одно сообщение в Телеграм-группу через ретранслятор вместо пяти, но при этом не теряется совсем. Логировать провал обязан сам Proxy: `errorB24()`, `Event` и `Smsgold` ошибку только возвращают вызывающему коду и в лог не пишут.
 
     **Создающие вызовы не повторяются Proxy-слоем.** Если в вызове есть метод, создающий сущность или запускающий действие (`*.add`, `*.create`, `*.start`, `*.send`, `*.uploadfile`, `*.import`, `*.register` — в том числе среди команд `callBatch`), retry отменяется, а в лог идёт `повтор отменён`. Причина: транспортная ошибка не говорит, дошёл ли запрос до портала. Обрыв приходит и когда соединение не состоялось, и когда оно случилось после того, как портал уже принял и выполнил запрос — а повтор во втором случае создаёт вторую задачу, второй файл, второй экземпляр бизнес-процесса. Идемпотентные записи (`*.update`, `*.delete`, `*.set`) повторяются как прежде: повторное применение даёт то же состояние.
 
@@ -252,9 +256,9 @@ const sent = await fetchWithTimeout("https://api.example.com/send", { method: "P
 
     **Провал обмена refresh-токена повторов не получает.** Когда обмен падает внутри вызова, попытка ровно одна, а в лог идёт строка уровня `error` с исходным кодом и статусом ответа oauth-хоста: `обновление токена не удалось (invalid_grant/400), повтор небезопасен: сервер мог провести ротацию`. Под правило попадает **любой** отказ обмена, кроме доказанного pre-connection, — и мёртвый токен после ротации, и транзиентные 429/503 от oauth-хоста: различить их по ответу нельзя. Если ротация прошла, локальный `refresh_token` мёртв независимо от повтора и нужна переавторизация приложения на портале. DNS-сбой на oauth-хосте под это правило не попадает: соединение не состоялось, значит повторяем.
 
-    Команды `callBatch` разбираются в обеих формах — кортеж `["crm.deal.add", {...}]` (основная в SDK 2.x) и объект `{ method, params }`. Если форму команды разобрать не удалось, вызов считается создающим и не повторяется: для защиты от дубликатов безопаснее ошибиться в сторону осторожности.
+    Команды `callBatch` разбираются в обеих формах — кортеж `["crm.deal.add", {...}]` (основная в SDK 2.x и 3.0) и объект `{ method, params }`. Если форму команды разобрать не удалось, вызов считается создающим и не повторяется: для защиты от дубликатов безопаснее ошибиться в сторону осторожности.
 
-    Важно: **транспортные сбои SDK не повторяет вообще** — пакет задаёт параметры ограничителя при создании клиента. Иначе гейт был бы дырявым: SDK не различает идемпотентные и создающие вызовы и повторил бы оборванный `crm.deal.add` до трёх раз внутри себя, куда наша защита не дотягивается. Измерено: без этих параметров обрыв соединения, 502 и 504 дают по три выполнения на портале, с ними — по одному.
+    Важно: **транспортные сбои SDK не повторяет вообще** — пакет задаёт параметры ограничителя при создании клиента. Иначе гейт был бы дырявым: SDK не различает идемпотентные и создающие вызовы и повторил бы оборванный `crm.deal.add` до трёх раз внутри себя, куда наша защита не дотягивается. Измерено: без этих параметров обрыв соединения, 502 и 504 дают по три выполнения на портале, с ними — по одному. На SDK 3.0.0 замер повторён и закреплён тестом `tests/sdk-executions.test.ts`: создающий вызов выполняется ровно один раз во всех сценариях сбоя.
 
     Повторы SDK при 429 и 503 сохранены: портал отвечает отказом, не выполнив запрос.
 
@@ -274,7 +278,9 @@ const sent = await fetchWithTimeout("https://api.example.com/send", { method: "P
 
     **«Мягкие» ошибки Bitrix24:**
 
-    Часть ошибок (`ERROR_ENTITY_NOT_FOUND`, `BITRIX_REST_V3_EXCEPTION_*`) SDK не бросает исключением, а возвращает как `AjaxResult` с ошибкой: `isSuccess === false`, и тогда `response.getData()` вернёт `undefined`. Отдельный случай — успешный ответ, у которого сам `result` пустой (`null`/`undefined`). Чтобы не падать на `undefined`, разбирайте ответы через `getResultData()` — он покрывает обе ситуации и бросает понятную ошибку с именем метода.
+    Часть ошибок (`ERROR_ENTITY_NOT_FOUND`, `BITRIX_REST_V3_EXCEPTION_*`) SDK не бросает исключением, а возвращает как `AjaxResult` с ошибкой: `isSuccess === false`, и тогда `response.getData()` вернёт `undefined`. У REST v3 (`$b24.actions.v3.*`) с SDK 3.0.0 «мягкой» стала ошибка 4xx, кроме 401, 408 и 429. Так ведут себя только ответы, пришедшие в конверте v3, с кодом вне жёсткого списка SDK (нехватка scope, `ACCESS_DENIED`, `NOT_FOUND`, `INVALID_ARG_VALUE`) и вне `hardErrorCodes` пакета; коды из этих списков по-прежнему бросаются, как и плоский ответ v2 от шлюза. Поэтому нужны и `catch`, и проверка `isSuccess`. Отдельный случай — успешный ответ, у которого сам `result` пустой (`null`/`undefined`). Чтобы не падать на `undefined`, разбирайте ответы через `getResultData()` — он покрывает обе ситуации и бросает понятную ошибку с именем метода.
+
+    **Ответ портала без JSON-конверта.** Если портал или прокси перед ним отдал со статусом 200 HTML-страницу, пустое тело или JSON без `result` и `error` (`{}`, `{ time }`), вызов бросает `JSSDK_UNKNOWN_ERROR` с понятным текстом: `портал вернул не JSON: HTTP 200, text/html, «<!DOCTYPE html>…»` или `портал вернул JSON без result и error: HTTP 200, …`. Без этой проверки SDK 3.0.0 принял бы такой ответ за успех — `crm.deal.add` вернул бы `{}` вместо ID сделки. Чтение повторяется с паузами 1-2-4-8 с, создающие вызовы не повторяются. Без конверта законно отвечают `rest.documentation.openapi` (через `$b24` не вызвать) и бинарные загрузки с `responseType`, отличным от `json` (`deferredBatch.download`), — их перехватчик пропускает.
 
     **Проактивное обновление токена:**
 
@@ -382,7 +388,18 @@ const sent = await fetchWithTimeout("https://api.example.com/send", { method: "P
 
     Без обёртки вызов `$b24.actions.*` идёт мимо защиты: ни повторов при сетевых сбоях, ни блокировки повтора для создающих методов.
 
--   **`B24Client`** — экспортируемый тип: `B24OAuth` плюс пять методов, которые пакет реализует сам. Объявлен как `interface B24Client extends B24OAuth`, поэтому `$b24` по-прежнему принимается везде, где ожидается `B24OAuth` — например в `new Smsgold(auth, $b24)`. Все пять сигнатур объявлены в интерфейсе явно, а не взяты по наследству: в SDK 3.x этих методов у базового класса не будет, и без явных объявлений тип потерял бы весь фасад. Держит их тест `tests/client-type.test.ts`: он читает текст `types.ts` (пропажу объявления система типов не видит — метод пока наследуется) и сверяет кортежи параметров строгим равенством типов, поэтому потеря необязательного аргумента или расширение параметра до `any` роняют `npx tsc --noEmit`.
+    **REST v3: проверяйте `isSuccess`.** С SDK 3.0.0 ошибки 4xx у `actions.v3.*` (кроме 401/408/429) не бросаются, а приходят в `AjaxResult` с `isSuccess === false`. `catch` вокруг `callProtected` их не поймает. Так ведут себя только ответы, пришедшие в конверте v3, с кодом вне жёсткого списка SDK (нехватка scope, `ACCESS_DENIED`, `NOT_FOUND`, `INVALID_ARG_VALUE`) и вне `hardErrorCodes` пакета; коды из этих списков по-прежнему бросаются, как и плоский ответ v2 от шлюза. Поэтому нужны и `catch`, и проверка `isSuccess`:
+
+    ```ts
+    const response = await callProtected(() => $b24!.actions.v3.call.make({ method: "tasks.task.get", params }), "tasks.task.get");
+    if (!response.isSuccess) {
+        throw new Error(`tasks.task.get: ${response.getErrorMessages().join("; ")}`);
+    }
+    ```
+
+    Или разбирайте через `getResultData(response, method)` — он бросит понятную ошибку сам. `callProtected` такой результат не повторяет: это не бросок, и 4xx от повтора не исправится. `actions.v3.callList.make` при ошибке отдаёт прочитанные строки **вместе** с ошибкой — тоже проверяйте `isSuccess`. Генераторы `fetchList`/`fetchTail` в `callProtected` не оборачиваются. `idempotencyKey` у `actions.v3.call.make` пакет пока не учитывает: блокировка повтора решается по имени метода.
+
+-   **`B24Client`** — экспортируемый тип: `B24OAuth` плюс пять методов, которые пакет реализует сам. Объявлен как `interface B24Client extends B24OAuth`, поэтому `$b24` по-прежнему принимается везде, где ожидается `B24OAuth` — например в `new Smsgold(auth, $b24)`. Все пять сигнатур объявлены в интерфейсе явно: в SDK 3.0.0 у базового класса этих методов нет, и пропажу объявления ловит тайпчек. Результаты `callListMethod`, `callBatch` и `callBatchByChunk` — `Promise<Result<any>>`, как и на 4.x: у самого SDK дефолт `Result<T>` теперь `unknown`. Тест `tests/client-type.test.ts` сверяет кортежи параметров и типы результата строгим равенством типов, поэтому потеря необязательного аргумента, расширение параметра до `any` или откат результата на голый `Result` роняют `npx tsc --noEmit`.
 
     ```ts
     import type { B24Client } from "@andrey4emk/npm-app-back-b24";
@@ -459,7 +476,7 @@ const sent = await fetchWithTimeout("https://api.example.com/send", { method: "P
     });
     ```
 
-    **Отказ портала виден в логе.** Если портал отказал в создании задачи (нет прав, указанной группы не существует), пишется одна строка уровня `error` с заголовком задачи, номером группы и текстом ошибки. Сетевые сбои этой строки не дают: их уже записал слой повторов, и вторая ушла бы дублем в чат B24.
+    **Отказ портала виден в логе.** Если портал отказал в создании задачи (нет прав, указанной группы не существует), пишется одна строка уровня `error` с заголовком задачи, номером группы и текстом ошибки. Сетевые сбои этой строки не дают: их уже записал слой повторов, и вторая ушла бы дублем в Телеграм-группу через ретранслятор.
 
     **Группа задачи по умолчанию.** Если `groupId` не передан, группа берётся из переменной окружения `B24_ERROR_TASK_GROUP_ID`. Явно переданное значение всегда важнее переменной: `null` и `0` означают осознанное «без группы» и дефолт не подхватывают. Переменная читается один раз при загрузке модуля — правка `process.env` в рантайме дефолт не двигает, нужен перезапуск процесса. Если переменная не задана или непригодна (не целое больше нуля), поведение прежнее — задача создаётся без группы, плюс одна строка уровня `warn` за процесс. Строка пишется при первом вызове, которому дефолт реально понадобился: у потребителя, который всегда передаёт группу сам, в логе не появится ничего.
 
@@ -477,7 +494,7 @@ const sent = await fetchWithTimeout("https://api.example.com/send", { method: "P
     }
     ```
 
--   **`Event`** — класс для работы с офлайн-событиями Bitrix24. Можно создать свой экземпляр, передав `B24OAuth`.
+-   **`Event`** — класс для работы с офлайн-событиями Bitrix24. Можно создать свой экземпляр, передав `$b24` (голый `B24OAuth` с 5.0.0 не подходит — в нём нет `callMethod`).
 
     ```js
     import { Event } from "@andrey4emk/npm-app-back-b24";
@@ -605,7 +622,7 @@ const sent = await fetchWithTimeout("https://api.example.com/send", { method: "P
 
     Конструктор сразу разрешает тип мессенджера для `whatsApp` и `telegram` — берёт `messenger[0].type` и держит в полях, вместо того чтобы индексировать массив при каждой отправке. Если конфига нет или список `messenger` пуст, тип остаётся неразрешённым, и **методы этого мессенджера возвращают** `{ error: true, message: "ChatApp: не разрешён тип мессенджера whatsApp (нет конфига или пуст messenger)", data: null }` — вместо запроса на URL с `undefined` в пути. Конструктор при этом **не бросает**: экземпляр обычно создаётся на уровне модуля, и бросок уронил бы загрузку всего модуля отправки вместе с соседними каналами.
 
-    **Таймаут отправки — статус неизвестен.** Запросы идут с бюджетом времени (10 секунд на работу с токеном, 20 на проверку номера, 30 на отправку сообщения, 60 на отправку файла). Если ответа не дождались, отправка **могла состояться** — методы возвращают `{ error: true, message: "ChatApp: таймаут ... — статус неизвестен", data: null }`, а не бросают исключение. Повторять такую отправку нельзя: клиент получит второе сообщение. Пакет дополнительно пишет строку уровня `error` (она уходит в чат B24) — решение о повторе принимает человек. Раньше зависание долетало до вызывающего кода исключением через пять минут; теперь оно возвращается объектом через тридцать секунд, поэтому запись в лог обязательна: без неё отказ стал бы тише, чем был.
+    **Таймаут отправки — статус неизвестен.** Запросы идут с бюджетом времени (10 секунд на работу с токеном, 20 на проверку номера, 30 на отправку сообщения, 60 на отправку файла). Если ответа не дождались, отправка **могла состояться** — методы возвращают `{ error: true, message: "ChatApp: таймаут ... — статус неизвестен", data: null }`, а не бросают исключение. Повторять такую отправку нельзя: клиент получит второе сообщение. Пакет дополнительно пишет строку уровня `error` (она уходит в Телеграм-группу через ретранслятор) — решение о повторе принимает человек. Раньше зависание долетало до вызывающего кода исключением через пять минут; теперь оно возвращается объектом через тридцать секунд, поэтому запись в лог обязательна: без неё отказ стал бы тише, чем был.
 
     Отказ локальный: пустой `whatsApp` не мешает `telegram`. Но конфиг всё равно нужен для **обоих** мессенджеров, даже если проект пользуется одним — иначе второй канал молча перестанет работать, и узнать об этом можно будет только по `res.error` в логе.
 
@@ -681,7 +698,7 @@ const sent = await fetchWithTimeout("https://api.example.com/send", { method: "P
 
     const smsClient = new Smsgold(
         { user: "smsgold_login", pass: "smsgold_password" },
-        b24Instance, // опционально — экземпляр B24OAuth для загрузки файлов на диск
+        b24Instance, // опционально — $b24 для загрузки файлов на диск (голый B24OAuth с 5.0.0 не подходит)
         123456 // опционально — ID папки на диске B24 для вложений, по умолчанию 2792881
     );
     ```
@@ -710,7 +727,7 @@ const sent = await fetchWithTimeout("https://api.example.com/send", { method: "P
         }
         ```
 
-    -   **Таймаут и неизвестный статус доставки.** Отправка идёт без повторов с бюджетом 30 секунд. Если SMSGold не ответил, запрос уже ушёл — сообщение **могло быть доставлено**, и повторять отправку нельзя. Такой результат отличается от обычной ошибки: `unknownDelivery: true` и текст «SMSGold не ответил за 30с — статус отправки неизвестен». Дополнительно пакет пишет строку уровня `error` (она уходит в чат B24), потому что решение о повторе должен принимать человек, а не код. Это единственное место, где `Smsgold` пишет в лог сам.
+    -   **Таймаут и неизвестный статус доставки.** Отправка идёт без повторов с бюджетом 30 секунд. Если SMSGold не ответил, запрос уже ушёл — сообщение **могло быть доставлено**, и повторять отправку нельзя. Такой результат отличается от обычной ошибки: `unknownDelivery: true` и текст «SMSGold не ответил за 30с — статус отправки неизвестен». Дополнительно пакет пишет строку уровня `error` (она уходит в Телеграм-группу через ретранслятор), потому что решение о повторе должен принимать человек, а не код. Это единственное место, где `Smsgold` пишет в лог сам.
 
         ```js
         const result = await smsClient.sendSms({ phone, message });
@@ -777,7 +794,7 @@ const sent = await fetchWithTimeout("https://api.example.com/send", { method: "P
 
 -   **`Wappi`** — класс для отправки сообщений через Wappi API (WhatsApp, Telegram, Max). Экземпляр нужно создать самостоятельно.
 
-    **Таймаут отправки — статус неизвестен.** Как и у `ChatApp`: бюджет 20 секунд на проверку номера, 30 на сообщение, 60 на файл. При таймауте отправки метод возвращает `{ error: true, message: "Wappi: таймаут ... — статус неизвестен", data: null }` и пишет строку уровня `error` в чат B24 — сообщение могло уйти, повторять нельзя. Отдельно про Telegram: `phoneCheckWappi` при таймауте проверки контакта **не создаёт контакт**, а возвращает ошибку. Иначе не дождавшись ответа мы бы завели контакт на номер, который мог уже быть в адресной книге, и объявили номер проверенным без проверки.
+    **Таймаут отправки — статус неизвестен.** Как и у `ChatApp`: бюджет 20 секунд на проверку номера, 30 на сообщение, 60 на файл. При таймауте отправки метод возвращает `{ error: true, message: "Wappi: таймаут ... — статус неизвестен", data: null }` и пишет строку уровня `error` (она уходит в Телеграм-группу через ретранслятор) — сообщение могло уйти, повторять нельзя. Отдельно про Telegram: `phoneCheckWappi` при таймауте проверки контакта **не создаёт контакт**, а возвращает ошибку. Иначе не дождавшись ответа мы бы завели контакт на номер, который мог уже быть в адресной книге, и объявили номер проверенным без проверки.
 
     ```js
     import { Wappi } from "@andrey4emk/npm-app-back-b24";
@@ -853,11 +870,19 @@ const sent = await fetchWithTimeout("https://api.example.com/send", { method: "P
     -   Конфигурация хранится в файле `log.json` (через `conf`).
     -   Каждый уровень можно включить/выключить, изменить цвет.
 
+    **Error-логи в Телеграм.** Если заданы обе переменные `LOG_RELAY_URL` и `LOG_RELAY_KEY`, каждый `logs.add(..., "error")` дополнительно уходит в Телеграм-группу логов через ретранслятор `tg_relay` — независимо от того, включён ли `error` в `log.json`. Тема в группе определяется ключом клиента, уровень, время и имя клиента ставит ретранслятор.
+
+    -   Запрос: `POST LOG_RELAY_URL`, заголовок `Authorization: Bearer <LOG_RELAY_KEY>`, тело `{"level":"error","text":"..."}`. Успех — ответ `202`.
+    -   В текст идёт сообщение и `jsonData` (`JSON.stringify` с отступами; `null` и `undefined` не дописываются). Пустое сообщение заменяется на `(пустое сообщение)`. Длинный текст обрезается до 3800 символов с пометкой `...(обрезано)`. Логгер не бросает исключений ни на каком `message`.
+    -   **Телефоны маскируются** — только в Телеграме, в консоли данные исходные: `+7 916 123-45-67`, `89161234567`, `8.916.123.45.67`, `+7 916 12 34 567`, `9161234567` → `+7 ••• •••-••-67`. Разделителем между цифрами считаются пробелы, дефисы и тире, точки, `/` и скобки, но не перевод строки. Числа из 6–9 и 12+ цифр (id, суммы, метки времени) и идентификаторы с латинским префиксом (`DEAL_9161234567`) не трогаются. Известные границы: 10-значный городской номер без префикса (`4951234567`) не маскируется — его не отличить от метки времени в секундах; 10-значное число на `9` (например, ИНН) маскируется.
+    -   Отправка без ожидания, с бюджетом 5 секунд и без повторов. Отказ ретранслятора (не `202`, таймаут, сетевой сбой) пишется одной строкой `console.error` с префиксом `Logs Relay:`; для `401` — «ключ не принят», для `503` — «ретранслятор останавливается». Сетевой сбой печатается только именем ошибки и кодом причины (`TypeError (ECONNREFUSED)`). Адрес и ключ в строку не попадают.
+    -   Задана только одна из двух переменных, адрес не `http`/`https` или с логином и паролем, ключ с пробелами или управляющими символами — одна строка `console.warn` при старте (без самого значения) и канал выключен.
+
 ### fetchRetry и таймауты
 
 -   **`fetchRetry(url, options?, retries?, delay?, timeoutMs?)`** — обёртка над `fetch` с повторными попытками при сетевых ошибках. HTTP-ошибки (4xx, 5xx) **не** вызывают повторных попыток — повторяются только сетевые сбои (TypeError, ECONNRESET, ETIMEDOUT и т.д.) и собственный таймаут запроса.
 
--   **`maskUrl(url)`** — маскирует секреты в адресе перед записью в лог. URL входящего вебхука B24 содержит секрет прямо в пути (`/rest/1/<секрет>/method.json`), а токен авторизации может приходить в query-параметрах (`auth`, `access_token`, `refresh_token`, `token`). Хост и имя метода сохраняются, тело секрета заменяется на `***`. Используется внутри `fetchRetry`; применяйте в своём коде везде, где логируете адреса запросов к B24.
+-   **`maskUrl(url)`** — маскирует секреты в адресе перед записью в лог. URL входящего вебхука B24 содержит секрет прямо в пути (`/rest/1/<секрет>/method.json`), а токен авторизации может приходить в query-параметрах (`auth`, `access_token`, `refresh_token`, `token`, `signature`, `sessid`). Так же прячется токен бота Телеграма в пути Bot API: `https://api.telegram.org/bot<id>:<токен>/<метод>` и `/file/bot<id>:<токен>/<путь>` превращаются в `bot<id>:***`. Хост и имя метода сохраняются, тело секрета заменяется на `***`. Используется внутри `fetchRetry`; применяйте в своём коде везде, где логируете адреса запросов к B24.
 
     ```js
     import { maskUrl } from "@andrey4emk/npm-app-back-b24";
@@ -995,6 +1020,8 @@ const sent = await fetchWithTimeout("https://api.example.com/send", { method: "P
 | `APP_NAME`                  | Название приложения (используется в описании задач)           |
 | `B24_ERROR_TASK_GROUP_ID`   | ID группы по умолчанию для задач `errorB24()` (не задана — задача без группы) |
 | `CONFIG_DIR`                | Путь к директории с конфигами (по умолчанию `../config`)      |
+| `LOG_RELAY_URL`             | Адрес `POST /send` ретранслятора error-логов в Телеграм (только парой с `LOG_RELAY_KEY`) |
+| `LOG_RELAY_KEY`             | Ключ клиента ретранслятора; по нему ретранслятор выбирает тему в группе |
 | `FETCH_TIMEOUT_MS`          | Бюджет одной попытки `fetchRetry`/`fetchWithTimeout`, мс (по умолчанию `60000`; `0` — без таймаута) |
 | `FETCH_TIMEOUT_QUICK_MS`    | Бюджет `FETCH_TIMEOUTS.quick` — токены, мс (по умолчанию `10000`)               |
 | `FETCH_TIMEOUT_API_MS`      | Бюджет `FETCH_TIMEOUTS.api` — короткое чтение, мс (по умолчанию `20000`)        |
@@ -1015,6 +1042,10 @@ APP_NAME=MyApp
 CONFIG_DIR=../config
 FETCH_TIMEOUT_MS=60000
 
+# Error-логи в Телеграм через ретранслятор (только парой; не заданы — канал выключен)
+LOG_RELAY_URL=http://tg_relay:8080/send
+LOG_RELAY_KEY=ключ-клиента
+
 # Группа по умолчанию для задач об ошибках. ID свой у каждого портала —
 # посмотреть в адресе группы на портале. Не задана — задачи создаются без группы
 B24_ERROR_TASK_GROUP_ID=196
@@ -1030,6 +1061,30 @@ CHATAPP_PASS=your-password
 CHATAPP_APP_ID=your-app-id
 ```
 
+## Миграция на 5.1.0
+
+Канал error-логов переехал из чата Bitrix24 в Телеграм-группу через ретранслятор `tg_relay`. Публичный API не менялся: `logs.add(message, level?, jsonData?)` как прежде.
+
+1. **Задать `LOG_RELAY_URL` и `LOG_RELAY_KEY`** в `.env` проекта. Ключ выдаётся на ретрансляторе (`npm run issue-key -- <имя> <тема>`), тема в группе привязана к ключу. Задана одна из двух — канал выключен и при старте одна строка `warn`.
+2. **Убрать `LOG_B24_WEBHOOK_URL` и `LOG_B24_CHAT_ID`.** Они больше не читаются; пока заданы, при старте пишется одна строка `warn` «канал Bitrix24 снят в 5.1.0».
+3. **Контейнер проекта — в сеть `tg-relay`**, иначе адрес ретранслятора не резолвится и каждый error даст строку `Logs Relay: ошибка отправки`.
+4. **Глушилки тестов** — гасить `LOG_RELAY_URL`/`LOG_RELAY_KEY` пустой строкой (не `delete`: dotenv вернул бы значение из `.env`). Старые `LOG_B24_*` в глушилках можно оставить — они только убирают строку `warn`.
+5. **Телефоны в тексте error-логов маскируются** — только в Телеграме. В консоли и в журнале контейнера данные остаются исходными.
+6. **`APP_NAME` логгер больше не читает** — имя проекта в сообщении ставит ретранслятор по ключу. Для `errorB24()` переменная по-прежнему нужна.
+
+## Миграция на 5.0.0
+
+Выпуск ломающий: пакет переехал на `@bitrix24/b24jssdk` 3.0.0. Вызовы методов фасада (`callMethod`, `callListMethod`, `fetchListMethod`, `callBatch`, `callBatchByChunk`) не меняются.
+
+1. **Node.js 22 или новее** — этого требует SDK 3.0.0.
+2. **Свою копию SDK поднять одновременно с пакетом.** Проектам, которые держат `@bitrix24/b24jssdk` своей зависимостью ради типов (`b24_rnp`, `b24_money`, `b24_analytics`), — до 3.0.0. Иначе в дереве будут две копии SDK с несовместимыми типами `B24OAuth`, и разбор ошибок через `instanceof` промахнётся.
+3. **Свои вызовы `$b24.actions.v3.*` проверять на `isSuccess`**, в том числе внутри `callProtected`: ошибки 4xx, кроме 401/408/429, больше не бросаются (см. «REST v3: проверяйте `isSuccess`»). Так ведут себя только ответы, пришедшие в конверте v3, с кодом вне жёсткого списка SDK (нехватка scope, `ACCESS_DENIED`, `NOT_FOUND`, `INVALID_ARG_VALUE`) и вне `hardErrorCodes` пакета; коды из этих списков по-прежнему бросаются, как и плоский ответ v2 от шлюза. Поэтому нужны и `catch`, и проверка `isSuccess`.
+4. **Удалённое API SDK мимо `$b24`** — `callMethod` у собственного `B24OAuth`, `LoggerBrowser`, `AbstractB24.batchSize` — перевести на `actions.v2.*`, `LoggerFactory` и литерал `50` соответственно.
+5. **В `new Event(...)` и `new Smsgold(..., b24)` передавать `$b24`**, а не голый `B24OAuth`: в нём больше нет `callMethod`.
+6. **Тип `$b24` в своих обёртках (`getB24`/`ensureB24`/`b24`) — `B24Client` из пакета, а не `B24OAuth` из SDK.** После подъёма своей копии SDK до 3.0.0 у `B24OAuth` нет `callMethod`/`callListMethod`/`callBatch`, и обёртка с таким типом перестанет компилироваться.
+7. **`Result` самого SDK по умолчанию `unknown`.** У методов фасада `any` сохранён, правок не нужно; у своего кода поверх `actions.*` указывайте параметр типа (`Result<Deal[]>`).
+8. **Ответ портала «200 без `result`» — всегда ошибка с понятным текстом** («портал вернул JSON без result и error» или «портал вернул не JSON»). На 4.x это была та же ошибка с текстом про `'operating'` либо «Bitrix24 вернул пустой ответ». Если вы разбирали эти тексты — замените разбор. Без конверта законно отвечают `rest.documentation.openapi` (через `$b24` не вызвать) и бинарные загрузки с `responseType`, отличным от `json` (`deferredBatch.download`), — их перехватчик пропускает.
+
 ## Миграция на 4.0.0
 
 Выпуск ломающий. Правок у потребителя четыре, все механические.
@@ -1105,7 +1160,7 @@ CHATAPP_APP_ID=your-app-id
 
 ## Скрипты
 
--   `npm run test` — прогон юнит-тестов из `tests/` через встроенный `node --test`. Дополнительных зависимостей не нужно: `.ts` запускаются на нативном стирании типов Node, поэтому прогону нужен Node 22.6+ (`engines: ">=20.3.0"` — это требование к потребителю пакета, а не к разработке). Сети тесты не касаются, в тарбол папка не попадает.
+-   `npm run test` — прогон юнит-тестов из `tests/` через встроенный `node --test`. Дополнительных зависимостей не нужно: `.ts` запускаются на нативном стирании типов Node, поэтому прогону нужен Node 22.6+ (`engines: ">=22.0.0"` — требование к потребителю пакета, его диктует SDK 3.0.0). Сети тесты не касаются, в тарбол папка не попадает.
 -   `npm run pack:dry` — предпросмотр содержимого пакета перед публикацией.
 
 ## Лицензия

package/bitrix24/b24/facade.ts

@@ -1,5 +1,5 @@
 import { Result } from "@bitrix24/b24jssdk";
-import type { AjaxResult, TypeCallParams, B24OAuth } from "@bitrix24/b24jssdk";
+import type { AjaxResult, TypeCallParamsV2, B24OAuth } from "@bitrix24/b24jssdk";
 import { logs } from "../../logs/logs.ts";
 import { getRetryBlockReason, runWithRetry } from "./retry.ts";
 import type { FacadeMethods, BatchCalls, V2Envelope } from "./types.ts";
@@ -62,7 +62,8 @@ export function getResultData<T = any>(response: AjaxResult, methodName: string)
  * конверта restApi:v2, но числового смещения среди них так и нет: `isMore()` отвечает
  * только «есть ли ещё», а `getNext(http)` сам делает следующий запрос, мимо нашего
  * прогресса и retry. Поэтому конверт читаем напрямую: `_data` объявлен `protected`,
- * а не приватным полем класса, поэтому в рантайме доступен.
+ * а не приватным полем класса, поэтому в рантайме доступен. В 3.0.0 всё это на месте:
+ * `_data` тот же, `getData()` по-прежнему режет конверт до `{ result, time }`.
  *
  * Это единственная точка связи с внутренностями SDK. Если она перестанет работать,
  * она обязана упасть громко: тихо оборванная на первой странице выборка — потеря данных.
@@ -80,7 +81,7 @@ export function readV2Envelope(response: AjaxResult, method: string): V2Envelope
 // ==================== Фасад поверх actions.v2.* ====================
 
 /**
- * Собственные реализации пяти методов, которые SDK 2.x помечает к удалению.
+ * Собственные реализации пяти методов, удалённых в SDK 3.0.0.
  * Повторяют `AbstractB24` дословно, включая дефолты и порядок аргументов.
  *
  * Позиционные сигнатуры сохранены один в один: на этом держится то, что гейт
@@ -95,6 +96,10 @@ export function readV2Envelope(response: AjaxResult, method: string): V2Envelope
  * (`for await (const chunk of $b24.fetchListMethod(...)) chunk.forEach((x) => x.ID)`).
  * `unknown` в дефолте уронил бы каждое такое место, не дав взамен ничего — узкий тип
  * задаётся параметром типа на месте вызова (`callMethod<Deal>(...)`).
+ *
+ * По той же причине `Promise<Result<any>>` у `callListMethod`, `callBatch` и `callBatchByChunk`:
+ * с SDK 3 дефолт `Result<T>` — `unknown`, и голый `Result` уронил бы код потребителей вида
+ * `(await $b24.callListMethod(...)).getData().forEach(...)`.
  */
 export function createFacade(target: B24OAuth): FacadeMethods {
     // Геттер actions при каждом обращении проверяет инициализацию экземпляра —
@@ -102,7 +107,7 @@ export function createFacade(target: B24OAuth): FacadeMethods {
     const v2 = () => target.actions.v2;
 
     const callMethod = async <T = any>(method: string, params?: object, start?: number): Promise<AjaxResult<T>> => {
-        const merged: TypeCallParams = { ...params };
+        const merged: TypeCallParamsV2 = { ...params };
 
         // Явный params.start приоритетнее аргумента start — как в AbstractB24.callMethod.
         // typeof, а не только Number.isInteger: последний ничего не сужает, и при
@@ -127,7 +132,7 @@ export function createFacade(target: B24OAuth): FacadeMethods {
         params?: object,
         progress?: null | ((progress: number) => void),
         customKeyForResult?: string | null
-    ): Promise<Result> => {
+    ): Promise<Result<any>> => {
         const result = new Result();
         const onProgress = typeof progress === "function" ? progress : null;
 
@@ -211,16 +216,17 @@ export function createFacade(target: B24OAuth): FacadeMethods {
      * поэтому отданные страницы не теряются и не дублируются.
      *
      * Форма запроса взята из `fetch-list.mjs`: `start: -1`, навязанный
-     * `order: { <курсор>: "ASC" }`, фильтр `>курсор`. Отступления от SDK — пять,
+     * `order: { <курсор>: "ASC" }`, фильтр `>курсор`. Отступления от SDK — три,
      * все намеренные:
      *   1. остановка только на пустой странице, а не на короткой: страница, укороченная
      *      правами доступа, у портала штатна, и правило SDK молча обрезало бы выборку;
      *   2. нечитаемый курсор — бросок, а не предупреждение и тихая остановка:
      *      после пункта 1 он означает гарантированно неполную выборку;
-     *   3. потолок страниц (`FETCH_LIST_MAX_PAGES`) — у SDK цикл ничем не ограничен;
-     *   4. проверка роста курсора — портал, отбросивший неизвестный ключ фильтра,
-     *      иначе отдавал бы одну и ту же страницу вечно;
-     *   5. пустая строка в `customKeyForResult` трактуется как «ключ не передан».
+     *   3. пустая строка в `customKeyForResult` трактуется как «ключ не передан».
+     *
+     * Потолок страниц (`FETCH_LIST_MAX_PAGES`) и проверка роста курсора (портал,
+     * отбросивший неизвестный ключ фильтра, иначе отдавал бы одну и ту же страницу
+     * вечно) есть и у SDK 3.0.0, у нас свои пороги и свой текст ошибки.
      *
      * Плюс диагностика: ошибки называют метод B24 вместо `TypeError` из недр SDK
      * и `SdkError` с кодом SDK.
@@ -232,7 +238,7 @@ export function createFacade(target: B24OAuth): FacadeMethods {
      */
     async function* fetchListMethod(method: string, params?: any, idKey?: string, customKeyForResult?: string | null): AsyncGenerator<any[]> {
         // Отдельного cursorIdKey, как в опциях SDK, у нас нет и не будет: позиционная
-        // сигнатура deprecated-метода его не содержала, а добавление пятого аргумента —
+        // сигнатура удалённого метода SDK его не содержала, а добавление пятого аргумента —
         // расширение публичного API. У SDK он по умолчанию тоже равен idKey
         const cursorKey = idKey ?? "ID";
         const moreKey = `>${cursorKey}`;
@@ -279,7 +285,7 @@ export function createFacade(target: B24OAuth): FacadeMethods {
             // курсор в нём двигается только после успешной страницы — поэтому повтор
             // попадает ровно в ту же страницу, а не в следующую
             const response = await runWithRetry(
-                () => v2().call.make<any>({ method, params: requestParams as TypeCallParams }),
+                () => v2().call.make<any>({ method, params: requestParams as TypeCallParamsV2 }),
                 "$b24.fetchListMethod",
                 blockReason
             );
@@ -348,7 +354,7 @@ export function createFacade(target: B24OAuth): FacadeMethods {
         }
     }
 
-    const callBatch = async (calls: Array<any> | object, isHaltOnError?: boolean, returnAjaxResult?: boolean): Promise<Result> => {
+    const callBatch = async (calls: Array<any> | object, isHaltOnError?: boolean, returnAjaxResult?: boolean): Promise<Result<any>> => {
         // Дефолты подставляем мы: batch.make своих не имеет, он просто
         // расширяет переданный объект опций версией API
         return v2().batch.make({
@@ -360,7 +366,7 @@ export function createFacade(target: B24OAuth): FacadeMethods {
         });
     };
 
-    const callBatchByChunk = async (calls: Array<any>, isHaltOnError: boolean): Promise<Result> => {
+    const callBatchByChunk = async (calls: Array<any>, isHaltOnError: boolean): Promise<Result<any>> => {
         // isHaltOnError передаём как есть, без ?? true — дословно по AbstractB24.
         // returnAjaxResult не передаём: batchByChunk.make жёстко ставит false сам,
         // а его тип опций этот ключ не принимает

package/bitrix24/b24/instance.ts

@@ -1,6 +1,7 @@
-import { B24OAuth, Logger, LogLevel } from "@bitrix24/b24jssdk";
+import { ApiVersion, 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 { installJsonGuard } from "./nonJsonResponse.ts";
 import { APP_ENV, CLIENT_ID, CLIENT_SECRET, confAuthB24, cleanDomain } from "./config.ts";
 
 // ==================== Константы ====================
@@ -104,7 +105,7 @@ export class B24SdkLogHandler implements Handler {
             // попытки. На транспортном сбое их пять — по числу наших попыток, повторы SDK
             // выключены (см. SDK_RESTRICTION_PARAMS). На 429/503 и неизвестных 5xx SDK
             // повторяет по-прежнему, там до пятнадцати: три внутри каждой из наших пяти.
-            // Уровень error пакета уходит в чат B24, поэтому маппим SDK-ERROR в warn:
+            // Уровень error пакета уходит в Телеграм через ретранслятор, поэтому маппим SDK-ERROR в warn:
             // окончательный провал вызова логирует retry-слой, ровно один раз.
             const isQuietClientError = status >= 400 && status < 500 && status !== 408 && status !== 429;
             const level = isQuietClientError ? "debug" : record.level >= LogLevel.CRITICAL ? "error" : "warn";
@@ -182,5 +183,13 @@ export function createB24Instance(): B24OAuth | null {
     // прямо в console.warn, но после перехода на фасад этот путь у нас недостижим.
     b24.setLogger(Logger.create("npm-app-back-b24").pushHandler(new B24SdkLogHandler()));
 
+    // Ответ без JSON-конверта (HTML-страница прокси, пустое тело, JSON без result и error)
+    // превращаем в понятную ошибку со статусом и началом тела: SDK 3 принял бы такой
+    // ответ за успех (T-65, #469). Перехватчик обязателен. Ставим на оба клиента:
+    // v3 ходит через свой axios. Обмен refresh-токена идёт отдельным экземпляром
+    // axios и проверку не получает
+    installJsonGuard(b24.getHttpClient(ApiVersion.v2).ajaxClient);
+    installJsonGuard(b24.getHttpClient(ApiVersion.v3).ajaxClient);
+
     return b24;
 }

package/bitrix24/b24/nonJsonResponse.ts

@@ -0,0 +1,161 @@
+import { SdkError } from "@bitrix24/b24jssdk";
+
+/**
+ * Распознавание ответа портала, который не является JSON-конвертом REST.
+ *
+ * Сценарий из логов 29.09.2026 (T-65): портал или прокси на его пути несколько секунд
+ * отдавал HTML-страницу со статусом 200. axios с настройками по умолчанию нечитаемый
+ * JSON не бросает, а молча отдаёт строку. SDK 2.x падал на ней в лимитере с безликим
+ * «Cannot destructure property 'operating'». SDK 3.0.0 не падает вовсе: любое тело без
+ * ключа `result` он заворачивает в `result` и отдаёт как успех (#469). HTML-страница
+ * прокси приходит потребителю строкой в `getData().result`, а ответ `{}` или `{ time }`
+ * превращает `crm.deal.add` в «успешный» вызов без ID сделки.
+ *
+ * Поэтому проверка стоит раньше SDK — перехватчиком ответа на axios-клиенте самого SDK
+ * (официальная точка доступа `getHttpClient(version).ajaxClient`). Она единственное, что
+ * отделяет страницу прокси от «успешного» ответа. Пропускается только объект с ключом
+ * `result` или `error` — успех (`{ result, time }`) или ошибка (`{ error, error_description }`
+ * у v2, `{ error: { code, message } }` у v3). Всё остальное — строка, пустое тело, массив,
+ * объект без конверта — превращается в B24NonJsonResponseError со статусом, типом содержимого
+ * и началом тела. SDK заворачивает её в `JSSDK_UNKNOWN_ERROR` (он в его жёстком списке — сам
+ * SDK не повторяет) и кладёт целиком в `originalError`, а retry-слой пакета по ней узнаёт
+ * временный сбой портала и повторяет с нарастающей паузой.
+ *
+ * Без конверта законно отвечают `rest.documentation.openapi` (через `$b24` не вызвать) и
+ * бинарные загрузки с `responseType`, отличным от `json` (`deferredBatch.download`), — их
+ * перехватчик пропускает. Сами запросы REST у SDK `responseType` не задают.
+ */
+
+/** Сколько символов тела попадает в сообщение об ошибке */
+export const NON_JSON_BODY_PREVIEW = 200;
+
+/**
+ * Вид сбоя: `not-json` — тело не объект (HTML, пустое, обрезанное),
+ * `no-envelope` — разобранный JSON без ключей `result` и `error`
+ */
+export type NonJsonResponseKind = "not-json" | "no-envelope";
+
+/** Ответ портала без JSON-конверта REST: HTML-страница прокси, пустое тело, JSON без result и error */
+export class B24NonJsonResponseError extends Error {
+    /** HTTP-статус ответа */
+    readonly status: number;
+    /** Заголовок Content-Type, если пришёл */
+    readonly contentType: string;
+    /** Начало тела без лишних пробелов, не длиннее NON_JSON_BODY_PREVIEW */
+    readonly bodyPreview: string;
+    /** Вид сбоя */
+    readonly kind: NonJsonResponseKind;
+
+    constructor(status: number, contentType: string, bodyPreview: string, kind: NonJsonResponseKind = "not-json") {
+        const type = contentType || "тип не указан";
+        const body = bodyPreview ? `«${bodyPreview}»` : "пустое тело";
+        const what = kind === "no-envelope" ? "JSON без result и error" : "не JSON";
+        super(`портал вернул ${what}: HTTP ${status}, ${type}, ${body}`);
+        this.name = "B24NonJsonResponseError";
+        this.status = status;
+        this.contentType = contentType;
+        this.bodyPreview = bodyPreview;
+        this.kind = kind;
+    }
+}
+
+/** Минимальная форма ответа axios, которую читает перехватчик */
+export interface AxiosLikeResponse {
+    status: number;
+    data: unknown;
+    headers?: unknown;
+    /** Настройки запроса: `responseType` говорит, какое тело ждёт вызывающий */
+    config?: { responseType?: string };
+}
+
+/**
+ * Минимальная форма axios-клиента: только регистрация перехватчика ответа.
+ * Параметр типа — конкретный тип ответа клиента (у axios — AxiosResponse): перехватчик
+ * обязан вернуть ровно его, а не урезанную структурную форму.
+ */
+export interface AxiosLikeClient<R extends AxiosLikeResponse> {
+    interceptors: {
+        response: {
+            use: (onFulfilled: (response: R) => R) => unknown;
+        };
+    };
+}
+
+/** Читает Content-Type и из AxiosHeaders (метод get), и из обычного объекта */
+function readContentType(headers: unknown): string {
+    if (!headers || typeof headers !== "object") return "";
+
+    const getter = (headers as { get?: unknown }).get;
+    const value = typeof getter === "function" ? getter.call(headers, "content-type") : (headers as Record<string, unknown>)["content-type"];
+
+    return typeof value === "string" ? value : "";
+}
+
+/** Тело как текст: разобранный JSON без конверта показываем как JSON, а не «[object Object]» */
+function bodyToText(data: unknown): string {
+    if (typeof data === "string") return data;
+    if (typeof data !== "object") return String(data);
+
+    try {
+        return JSON.stringify(data) ?? String(data);
+    } catch {
+        return String(data);
+    }
+}
+
+/** Начало тела одной строкой: переводы строк и повторные пробелы схлопываются */
+function previewBody(data: unknown): string {
+    if (data === undefined || data === null) return "";
+
+    const flat = bodyToText(data).replace(/\s+/g, " ").trim();
+
+    return flat.length > NON_JSON_BODY_PREVIEW ? `${flat.slice(0, NON_JSON_BODY_PREVIEW)}…` : flat;
+}
+
+/**
+ * Пропускает ответ дальше, если в теле объект с ключом `result` или `error`,
+ * иначе бросает B24NonJsonResponseError.
+ *
+ * Объект с конвертом — единственная законная форма тела REST: и успех (`{result, time}`),
+ * и ошибка (`{error, error_description}` или `{error: {code, message}}`). Строка означает,
+ * что axios не смог разобрать JSON, пустое тело — что ответа по сути нет. Объект без обоих
+ * ключей (`{}`, `{ time }`) и массив SDK 3 принял бы за успех с мусором в `result`.
+ *
+ * Исключение — запрос, который сам попросил не JSON (`responseType` задан и не `json`):
+ * так SDK скачивает файл в `deferredBatch.download` (`arraybuffer`). Такой ответ
+ * пропускается без проверки.
+ */
+export function assertJsonResponse<R extends AxiosLikeResponse>(response: R): R {
+    const responseType = response.config?.responseType;
+    if (responseType && responseType !== "json") return response;
+
+    const { data } = response;
+    const status = response.status;
+    const contentType = readContentType(response.headers);
+
+    if (data === null || typeof data !== "object") {
+        throw new B24NonJsonResponseError(status, contentType, previewBody(data), "not-json");
+    }
+
+    if (!Array.isArray(data) && ("result" in data || "error" in data)) return response;
+
+    throw new B24NonJsonResponseError(status, contentType, previewBody(data), "no-envelope");
+}
+
+/** Ставит проверку тела на axios-клиент SDK */
+export function installJsonGuard<R extends AxiosLikeResponse>(client: AxiosLikeClient<R>): void {
+    client.interceptors.response.use((response) => assertJsonResponse(response));
+}
+
+/**
+ * Пришла ли ошибка от ответа портала без JSON-конверта.
+ *
+ * Смотрит и на саму ошибку, и на `originalError` — SDK кладёт нашу ошибку туда,
+ * заворачивая её в `JSSDK_UNKNOWN_ERROR`.
+ */
+export function isNonJsonResponseError(error: unknown): boolean {
+    if (error instanceof B24NonJsonResponseError) return true;
+    if (!(error instanceof SdkError)) return false;
+
+    return error.originalError instanceof B24NonJsonResponseError;
+}

package/bitrix24/b24/proxy.ts

@@ -16,8 +16,8 @@ const RETRYABLE_METHOD_NAMES = ["callMethod", "callListMethod", "callBatch"] as
  * Имена, которые Proxy резолвит в собственную реализацию пакета поверх `actions.v2.*`.
  *
  * Шире, чем RETRYABLE_METHOD_NAMES: `fetchListMethod` и `callBatchByChunk` мы реализуем,
- * но не ретраим. `callBatchByChunk` в наборе обязателен — пока хоть один deprecated-метод
- * SDK достижим через `$b24`, он будет писать предупреждение об устаревании.
+ * но не ретраим. `callBatchByChunk` в наборе обязателен: в SDK 3.0.0 метода на цели нет,
+ * и без него `Reflect.get` вернул бы `undefined`.
  *
  * `satisfies` ловит опечатку и переименование: имя, которого нет среди методов фасада,
  * уронит тайпчек здесь, а не молча уедет мимо Proxy в SDK.
@@ -78,8 +78,8 @@ export function wrapB24WithRetry(b24: B24OAuth): B24Client {
 
     return new Proxy(b24, {
         get(target, prop) {
-            // Имена фасада проверяем до Reflect.get: пока SDK ещё объявляет свои
-            // deprecated-методы, иначе мы отдавали бы их, а не свои
+            // Имена фасада проверяем до Reflect.get. SDK 3.0.0 их не объявляет, проверка
+            // остаётся на случай, если имя вернётся в SDK: отдавать надо своё, а не его
             if (typeof prop === "string" && isFacadeMethod(prop)) {
                 if (!methodCache.has(prop)) {
                     // Индексируем внутри ветки: после сужения prop до RetryableMethodName
@@ -109,8 +109,8 @@ export function wrapB24WithRetry(b24: B24OAuth): B24Client {
             return methodCache.get(prop);
         },
 
-        // Страховка на будущее: когда SDK уберёт методы из прототипа,
-        // "callMethod" in $b24 обязано остаться истинным (eventB24.ts проверяет
+        // Нужна: в SDK 3.0.0 методов фасада на цели нет, а
+        // "callMethod" in $b24 обязано быть истинным (eventB24.ts проверяет
         // наличие метода перед работой). Цель расширяема, лишние true законны
         has(target, prop) {
             if (typeof prop === "string" && FACADE_METHODS.has(prop)) return true;