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

package/README.md

@@ -17,6 +17,7 @@
     -   [Логирование](#логирование)
     -   [fetchRetry и таймауты](#fetchretry-и-таймауты)
 -   [Переменные окружения](#переменные-окружения)
+-   [Миграция на 5.1.0](#миграция-на-510)
 -   [Миграция на 5.0.0](#миграция-на-500)
 -   [Миграция на 4.0.0](#миграция-на-400)
 -   [Скрипты](#скрипты)
@@ -239,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`) повторяются как прежде: повторное применение даёт то же состояние.
 
@@ -475,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` за процесс. Строка пишется при первом вызове, которому дефолт реально понадобился: у потребителя, который всегда передаёт группу сам, в логе не появится ничего.
 
@@ -621,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` в логе.
 
@@ -726,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 });
@@ -793,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";
@@ -869,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";
@@ -1011,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`)        |
@@ -1031,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
@@ -1046,6 +1061,17 @@ 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`) не меняются.

package/bitrix24/b24/instance.ts

@@ -105,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";

package/bitrix24/b24/retry.ts

@@ -456,7 +456,7 @@ export async function runWithRetry<T>(fn: () => Promise<T>, label: string, block
             const lifted = blockReason ? ` — соединение не состоялось, ограничение (${blockReason}) снято` : "";
             const pause = retryDelayFor(error, attempt);
 
-            // Промежуточные попытки — warn: в чат B24 уходит только уровень error,
+            // Промежуточные попытки — warn: в Телеграм через ретранслятор уходит только уровень error,
             // иначе один упавший вызов дал бы пять сообщений
             logs.add(`${label}${code}: попытка ${attempt}/${RETRY_COUNT} не удалась (${msg}), повтор через ${pause}мс${lifted}`, "warn");
 

package/bitrix24/b24/tokens.ts

@@ -190,7 +190,7 @@ function refreshAuthWithMutex(): Promise<AuthData> {
 
             // Уровень warn, а не error, намеренно: брошенную ниже ошибку поймает
             // refreshAndSaveTokens и напишет свою строку уровня error, а error уходит
-            // в чат B24 — иначе на одно залипание пришло бы два сообщения
+            // в Телеграм через ретранслятор — иначе на одно залипание пришло бы два сообщения
             logs.add(
                 `refreshAuth: обмен токена не завершился за ${REFRESH_STUCK_TIMEOUT_MS / 60000} мин — ${mutexPart}, зависший запрос продолжает работу и сохранит токены сам, если ответ придёт`,
                 "warn"

package/bitrix24/errTaskB24.ts

@@ -223,7 +223,7 @@ export async function errorB24(dataTask: ErrorTaskData): Promise<ErrorB24Result>
         //
         // Условие обязательно: сетевой отказ retry-слой уже записал сам — строкой
         // про исчерпание попыток либо про отменённый повтор. Без проверки вторая
-        // строка ушла бы дублем в чат B24, куда уходит уровень `error`
+        // строка ушла бы дублем в Телеграм через ретранслятор, куда уходит уровень `error`
         if (!isB24NetworkError(error)) {
             logs.add(`errorB24: задача «${dataTask.title}» не создана (группа ${groupId ?? "не задана"}) — ${message}`, "error");
         }

package/bitrix24/eventB24.ts

@@ -441,7 +441,7 @@ export class Event {
 
             // Битой оказалась вся выборка целиком — это уже не одна кривая запись,
             // а похоже на смену формы ответа портала (переименованное поле). Уровень
-            // error, потому что строка обязана дойти до чата B24: очередь при этом
+            // error, потому что строка обязана дойти до Телеграма: очередь при этом
             // продолжает вычищаться пакет за пакетом, и локальный лог никто не увидит
             if (verdicts.length > 1 && brokenVerdicts.length === verdicts.length) {
                 const firstReason = brokenVerdicts.at(0)?.reason ?? "причина не определена";
@@ -492,7 +492,7 @@ export class Event {
                     const message = error instanceof Error ? error.message : String(error);
 
                     // Уровень warn, а не error: окончательный отказ вызова уже написал
-                    // строку error retry-слой Proxy, дубль ушёл бы в чат B24 второй раз
+                    // строку error retry-слой Proxy, дубль ушёл бы в Телеграм через ретранслятор второй раз
                     logs.add(
                         `event.offline.clear: не удалось снять с резерва записи, их ${messageIdsToClear.length} — ${message}. Записи придут следующим опросом`,
                         "warn"

package/logs/logs.ts

@@ -1,6 +1,7 @@
 import path from "path";
 import Conf from "conf";
 import dotEnv from "dotenv";
+import { maskPhones } from "./maskPhones.ts";
 
 dotEnv.config();
 
@@ -19,28 +20,33 @@ interface LogLevelConfig {
 /** Полная конфигурация логирования */
 type LogConfig = Record<LogLevel, LogLevelConfig>;
 
-// ==================== Константы B24 Chat ====================
+// ==================== Константы канала в Телеграм ====================
 
-/** ID бота в B24 для отправки error-логов */
-const B24_BOT_ID = 66600;
-
-/** CLIENT_ID бота в B24 */
-const B24_CLIENT_ID = "6rf74zyu842h6op1z186b08k7aavqq7z";
-
-/** Лимит длины сообщения для B24 чата (безопасный, с запасом на BB-обёртку) */
-const B24_TEXT_LIMIT = 4000;
+/**
+ * Предел длины текста, отправляемого в ретранслятор. Совпадает с `ENTRY_TEXT_LIMIT`
+ * ретранслятора (`tg_relay/src/format.ts`): длиннее он обрезал бы запись сам, уже после
+ * нашей маскировки и без нашей пометки. Сообщение Телеграма — 4096 символов, остаток
+ * ретранслятор оставляет под заголовок записи и строку «пропущено N»
+ */
+const RELAY_TEXT_LIMIT = 3800;
 
 /**
- * Бюджет времени на отправку error-лога в чат B24, мс.
+ * Бюджет времени на отправку одного error-лога в ретранслятор, мс.
  *
  * Своя константа, а не `FETCH_TIMEOUTS` из `utils/fetchRetry.ts`: тот модуль импортирует
  * `logs` первой строкой, и обратный импорт дал бы цикл. Дублирование одного числа
  * дешевле цикла зависимостей.
  */
-const B24_CHAT_TIMEOUT_MS = 5_000;
+const RELAY_TIMEOUT_MS = 5_000;
+
+/** Сколько символов тела неуспешного ответа ретранслятора показывать в `console.error` */
+const RELAY_BODY_PREVIEW = 300;
 
-/** Сколько символов тела неуспешного ответа чата показывать в `console.error` */
-const B24_CHAT_BODY_PREVIEW = 300;
+/** Пояснения к статусам ответа ретранслятора, которые чаще всего придётся разбирать */
+const RELAY_STATUS_HINTS: Readonly<Record<number, string>> = {
+    401: "ключ LOG_RELAY_KEY не принят",
+    503: "ретранслятор останавливается и не принимает",
+};
 
 /**
  * Ошибка — обрыв по бюджету `AbortSignal.timeout`. Проверка локальная, без импорта
@@ -50,6 +56,41 @@ function isTimeout(error: unknown): boolean {
     return (error as { name?: unknown } | null)?.name === "TimeoutError";
 }
 
+/**
+ * Короткое описание ошибки отправки без текста сообщения: `name` и код или имя причины.
+ * Текст сообщения сетевой ошибки может содержать адрес запроса, а адрес и ключ канала
+ * в консоль не печатаются
+ */
+function describeSendError(error: unknown): string {
+    const name = error instanceof Error ? error.name : typeof error;
+    const cause = error instanceof Error ? (error.cause as { code?: unknown; name?: unknown } | null | undefined) : undefined;
+    const causeLabel = cause && typeof cause === "object" ? (cause.code ?? cause.name) : undefined;
+    return typeof causeLabel === "string" && causeLabel ? `${name} (${causeLabel})` : name;
+}
+
+/** Ключ ретранслятора — только видимые символы ASCII, без пробелов и управляющих */
+const RELAY_KEY_RE = /^[\x21-\x7e]+$/;
+
+/**
+ * Проверяет адрес ретранслятора: только `http`/`https` и без логина и пароля в адресе.
+ * Возвращает причину отказа или `null`. Значение адреса в причину не попадает
+ */
+function relayUrlProblem(raw: string): string | null {
+    let parsed: URL;
+    try {
+        parsed = new URL(raw);
+    } catch {
+        return "LOG_RELAY_URL не разбирается как адрес";
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        return "LOG_RELAY_URL должен начинаться с http:// или https://";
+    }
+    if (parsed.username || parsed.password) {
+        return "LOG_RELAY_URL не должен содержать логин и пароль";
+    }
+    return null;
+}
+
 // ==================== Настройки ====================
 
 const configDir: string = process.env.CONFIG_DIR || "../config";
@@ -93,20 +134,43 @@ class LogsAPI {
 
     private readonly resetColor = "\x1b[0m";
 
-    /** Webhook URL для отправки error-логов в B24 чат */
-    private readonly b24WebhookUrl: string | undefined;
+    /** Адрес `POST /send` ретранслятора (`LOG_RELAY_URL`); `undefined` — канал выключен */
+    private readonly relayUrl: string | undefined;
 
-    /** ID чата B24 для отправки error-логов (формат: chatXXXXXX) */
-    private readonly b24ChatId: string | undefined;
-
-    /** Имя приложения для заголовка сообщения */
-    private readonly appName: string;
+    /** Ключ клиента ретранслятора (`LOG_RELAY_KEY`); `undefined` — канал выключен */
+    private readonly relayKey: string | undefined;
 
     constructor() {
         this.initConfig();
-        this.b24WebhookUrl = process.env.LOG_B24_WEBHOOK_URL;
-        this.b24ChatId = process.env.LOG_B24_CHAT_ID;
-        this.appName = process.env.APP_NAME || "Unknown App";
+        const url = process.env.LOG_RELAY_URL?.trim() || undefined;
+        const key = process.env.LOG_RELAY_KEY?.trim() || undefined;
+
+        // Канал включается только парой. Половина пары — ошибка настройки: одна строка
+        // предупреждения и канал выключен, а не запрос без ключа или в никуда
+        // Непригодные значения тоже выключают канал одной строкой. Сами значения в строку
+        // не попадают: адрес с паролем или ключ ушли бы в журнал контейнера
+        let enabled = false;
+        if (Boolean(url) !== Boolean(key)) {
+            console.warn("Logs: задан только один из LOG_RELAY_URL/LOG_RELAY_KEY — отправка error-логов в Телеграм выключена");
+        } else if (url && key) {
+            const problem = relayUrlProblem(url) ?? (RELAY_KEY_RE.test(key) ? null : "LOG_RELAY_KEY содержит пробелы или управляющие символы");
+            if (problem) {
+                console.warn(`Logs: ${problem} — отправка error-логов в Телеграм выключена`);
+            } else {
+                enabled = true;
+            }
+        }
+        this.relayUrl = enabled ? url : undefined;
+        this.relayKey = enabled ? key : undefined;
+
+        // Старый канал в чат Bitrix24 снят. Строка ровно одна за процесс: конструктор
+        // singleton'а вызывается один раз. Без неё обновление пакета молча оставило бы
+        // проект без канала error-логов
+        if (process.env.LOG_B24_WEBHOOK_URL || process.env.LOG_B24_CHAT_ID) {
+            console.warn(
+                "Logs: канал Bitrix24 снят в 5.1.0 — LOG_B24_WEBHOOK_URL и LOG_B24_CHAT_ID больше не читаются, error-логи идут через LOG_RELAY_URL/LOG_RELAY_KEY",
+            );
+        }
     }
 
     /** Проверяем и заполняем конфиг дефолтными значениями если данных нет */
@@ -121,7 +185,7 @@ class LogsAPI {
     /**
      * Добавляет сообщение в лог
      *
-     * Важно: при уровне `error` сообщение отправляется в B24 чат (через webhook)
+     * Важно: при уровне `error` сообщение отправляется в Телеграм через ретранслятор
      * независимо от настройки `error.enabled` в `log.json`. Настройка `enabled`
      * управляет только выводом в консоль. Это сделано намеренно, чтобы критические
      * ошибки всегда доходили до команды даже при отключённом консольном логировании.
@@ -132,11 +196,15 @@ class LogsAPI {
      */
     add(message: string | object, level?: LogLevel, jsonData?: unknown): void {
         const levelStr: LogLevel = level || "info";
-        const messageText = typeof message === "string" ? message : JSON.stringify(message);
+        // JSON.stringify отдаёт undefined для undefined, функции и объекта с toJSON → undefined;
+        // тогда берём String(), иначе дальше по коду шёл бы не текст
+        const messageText = typeof message === "string" ? message : (JSON.stringify(message) ?? String(message));
 
-        // Отправляем error-логи в B24 чат независимо от настроек консольного вывода
+        // Отправляем error-логи в Телеграм независимо от настроек консольного вывода.
+        // В консоль ниже уходят исходные message и jsonData — маскировка телефонов
+        // касается только текста для Телеграма
         if (levelStr === "error") {
-            this.sendToB24Chat(messageText, jsonData);
+            this.sendToRelay(messageText, jsonData);
         }
 
         // Проверяем конфиг, и если логирование отключено, то выходим
@@ -161,117 +229,87 @@ class LogsAPI {
     }
 
     /**
-     * Убирает BB-теги для plain text отправки (при обрезке текста)
+     * Готовит текст error-лога и отправляет его в ретранслятор (fire-and-forget).
+     *
+     * Телефоны маскируются ДО обрезки по длине: после обрезки хвост номера на границе
+     * уже не узнать шаблоном, и он ушёл бы в Телеграм открытым.
      */
-    private stripBbCodes(text: string): string {
-        return text.replace(/\[\/?(b|code)\]/g, "");
-    }
+    private sendToRelay(message: string, jsonData?: unknown): void {
+        if (!this.relayUrl || !this.relayKey) return;
 
-    /**
-     * Отправляет error-сообщение в чат B24 через webhook (fire-and-forget)
-     * Использует нативный fetch, а не fetchRetry/fetchWithTimeout — во избежание
-     * циклической зависимости, поэтому и таймаут выставляется здесь вручную через
-     * `AbortSignal.timeout`: без него зависшее соединение никого бы не разбудило,
-     * вызов идёт без await
-     * Ошибки не пробрасываются, только console.error
-     */
-    private sendToB24Chat(message: string, jsonData?: unknown): void {
-        if (!this.b24WebhookUrl || !this.b24ChatId) return;
-
-        // Нормализуем URL — гарантируем trailing slash
-        const baseUrl = this.b24WebhookUrl.endsWith("/") ? this.b24WebhookUrl : `${this.b24WebhookUrl}/`;
-        const url = `${baseUrl}imbot.message.add.json`;
-
-        let text = `[b]ERROR[/b] | ${this.appName}\n${message}`;
-
-        // Добавляем jsonData если есть
-        if (jsonData !== undefined) {
-            // Безопасная сериализация — логгер не должен бросать исключения
-            let jsonStr: string;
-            try {
-                jsonStr = JSON.stringify(jsonData, null, 2);
-            } catch {
-                jsonStr = "[Не удалось сериализовать jsonData]";
+        // Логгер не должен бросать синхронно: его зовут из catch-блоков потребителей,
+        // и бросок отсюда подменил бы исходную ошибку. Отказ — только console.error
+        try {
+            let text = message.trim() ? message : "(пустое сообщение)";
+
+            // null и undefined не дописываем: строка «null» в Телеграме ничего не говорит
+            if (jsonData != null) {
+                // Безопасная сериализация: циклы бросают, функция и undefined дают undefined
+                try {
+                    const serialized = JSON.stringify(jsonData, null, 2) as string | undefined;
+                    text += `\n${serialized ?? String(jsonData)}`;
+                } catch {
+                    text += "\n[Не удалось сериализовать jsonData]";
+                }
             }
-            text += `\n[code]${jsonStr}[/code]`;
-        }
 
-        // Обрезаем до лимита B24
-        let isTruncated = false;
-        if (text.length > B24_TEXT_LIMIT) {
-            const truncatedSuffix = "\n...(обрезано)";
-            text = text.slice(0, B24_TEXT_LIMIT - truncatedSuffix.length) + truncatedSuffix;
-            isTruncated = true;
-        }
+            text = maskPhones(text);
 
-        // Если текст обрезан — отправляем без BB-тегов, чтобы не разорвать [code]...[/code]
-        if (isTruncated) {
-            text = this.stripBbCodes(text);
-        }
+            if (text.length > RELAY_TEXT_LIMIT) {
+                const truncatedSuffix = "\n...(обрезано)";
+                text = text.slice(0, RELAY_TEXT_LIMIT - truncatedSuffix.length) + truncatedSuffix;
+            }
 
-        void this.postToB24Chat(url, text);
+            void this.postToRelay(this.relayUrl, this.relayKey, text);
+        } catch (error: unknown) {
+            console.error(`Logs Relay: не удалось подготовить сообщение — ${describeSendError(error)}`);
+        }
     }
 
     /**
-     * Сам запрос в чат и разбор ответа. Никогда не бросает: все ошибки — в `console.error`,
-     * не через `logs`, иначе отказ канала порождал бы новый error и зацикливался.
+     * Сам запрос к ретранслятору и разбор ответа. Никогда не бросает: все ошибки — в
+     * `console.error`, не через `logs`, иначе отказ канала порождал бы новый error и зацикливался.
+     *
+     * Нативный `fetch`, а не `fetchRetry`/`fetchWithTimeout` — во избежание циклической
+     * зависимости, поэтому таймаут выставляется здесь через `AbortSignal.timeout`: вызов идёт
+     * без `await`, и без бюджета зависшее соединение никого бы не разбудило. Сигнал действует
+     * и на чтение тела ответа — зависшее тело обрывается тем же бюджетом.
      *
-     * Сигнал `AbortSignal.timeout` отдан в `fetch`, а он действует и на чтение тела
-     * ответа: зависшее тело обрывается тем же бюджетом с `TimeoutError`. До общего `catch`
-     * такая ошибка не доходит — у каждого чтения тела свой `.catch`, поэтому таймаут
-     * разбирается прямо там: при `!ok` к статусу дописывается пометка «тело не дочитано»,
-     * при 200 пишется отдельная строка «доставка не подтверждена».
+     * Ни адрес, ни ключ в строки ошибок не попадают: вместо текста сетевой ошибки
+     * (он может содержать адрес) печатается только её имя и код причины.
      */
-    private async postToB24Chat(url: string, text: string): Promise<void> {
+    private async postToRelay(url: string, key: string, text: string): Promise<void> {
         try {
             const response = await fetch(url, {
                 method: "POST",
-                headers: { "Content-Type": "application/json" },
-                body: JSON.stringify({
-                    BOT_ID: B24_BOT_ID,
-                    CLIENT_ID: B24_CLIENT_ID,
-                    DIALOG_ID: this.b24ChatId,
-                    MESSAGE: text,
-                }),
-                signal: AbortSignal.timeout(B24_CHAT_TIMEOUT_MS),
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${key}`,
+                },
+                body: JSON.stringify({ level: "error", text }),
+                signal: AbortSignal.timeout(RELAY_TIMEOUT_MS),
             });
 
-            if (!response.ok) {
-                // Тело — подсказка к причине отказа, его чтение отправку уронить не должно
-                const body = await response.text().catch((error: unknown) =>
-                    isTimeout(error) ? `[тело не дочитано за ${B24_CHAT_TIMEOUT_MS / 1000}с]` : "",
-                );
-                const bodyPart = body ? ` — ${body.slice(0, B24_CHAT_BODY_PREVIEW)}` : "";
-                console.error(`Logs B24 Chat: HTTP ${response.status}, сообщение не доставлено${bodyPart}`);
+            // 202 — принято в очередь ретранслятора; тело не нужно, соединение освобождаем
+            if (response.status === 202) {
+                await response.body?.cancel().catch(() => {});
                 return;
             }
 
-            // B24 умеет отвечать 200 с телом {error, error_description} — сообщения при этом нет.
-            // Нечитаемый JSON — молча null (портал ответил 200, ошибки в теле не видно),
-            // а вот зависшее тело — отказ канала: доставку подтвердить нечем, молчать нельзя
-            let bodyTimedOut = false;
-            const data: unknown = await response.json().catch((error: unknown) => {
-                bodyTimedOut = isTimeout(error);
-                return null;
-            });
-            if (bodyTimedOut) {
-                console.error(
-                    `Logs B24 Chat: HTTP ${response.status}, но ответ не дочитан за ${B24_CHAT_TIMEOUT_MS / 1000}с — доставка не подтверждена`,
-                );
-                return;
-            }
-            if (data && typeof data === "object" && "error" in data) {
-                const { error, error_description: description } = data as { error?: unknown; error_description?: unknown };
-                const reason = description ? String(description) : String(error);
-                console.error(`Logs B24 Chat: портал отклонил сообщение — ${reason}`);
-            }
+            // Тело — подсказка к причине отказа, его чтение отправку уронить не должно
+            const body = await response.text().catch((error: unknown) =>
+                isTimeout(error) ? `[тело не дочитано за ${RELAY_TIMEOUT_MS / 1000}с]` : "",
+            );
+            const bodyPart = body ? ` — ${body.slice(0, RELAY_BODY_PREVIEW)}` : "";
+            const hint = RELAY_STATUS_HINTS[response.status];
+            const hintPart = hint ? ` (${hint})` : "";
+            console.error(`Logs Relay: HTTP ${response.status}, сообщение не доставлено${hintPart}${bodyPart}`);
         } catch (error: unknown) {
             if (isTimeout(error)) {
-                console.error(`Logs B24 Chat: не ответил за ${B24_CHAT_TIMEOUT_MS / 1000}с, сообщение не доставлено`);
+                console.error(`Logs Relay: не ответил за ${RELAY_TIMEOUT_MS / 1000}с, сообщение не доставлено`);
                 return;
             }
-            const errMsg = error instanceof Error ? error.message : String(error);
-            console.error(`Logs B24 Chat: ошибка отправки — ${errMsg}`);
+            console.error(`Logs Relay: ошибка отправки — ${describeSendError(error)}`);
         }
     }
 }

package/logs/maskPhones.ts

@@ -0,0 +1,63 @@
+/**
+ * Маскировка российских телефонных номеров в тексте error-лога перед отправкой
+ * в Телеграм через ретранслятор. Внутренний модуль: из `logs.ts` не реэкспортируется
+ * и подпути в `exports` не имеет. Побочных эффектов нет.
+ *
+ * Номер ищется по цифрам, а не по рисунку групп: между любыми двумя цифрами может
+ * стоять сколько угодно разделителей — пробел, табуляция, неразрывные и узкие пробелы,
+ * дефис и тире всех видов (U+2010–U+2015), точка, косая черта, скобки. Так ловятся
+ * `+7 916 123-45-67`, `8.916.123.45.67`, `+7 916 12 34 567`, `8 9161 234567`,
+ * `8–916–123–45–67`, а не только «правильная» запись 3-3-2-2.
+ *
+ * Что ловит:
+ * - префикс `+7`, `7`, `8` или `+8` и ещё десять цифр;
+ * - мобильный без префикса — десять цифр, первая `9`, можно с открывающей скобкой.
+ *
+ * Границы:
+ * - слева от номера не может стоять цифра, латинская буква, `_` или `+` — поэтому
+ *   не трогаются куски длинных чисел, `DEAL_9161234567`, `v8.9.16.123.45`.
+ *   Точка и кириллица слева допустимы: `тел.89161234567` маскируется;
+ * - справа от номера не может стоять цифра — 12+ цифр подряд (метки времени в мс,
+ *   длинные идентификаторы) не трогаются;
+ * - перевод строки разделителем не считается: соседние числа отформатированного
+ *   JSON (`JSON.stringify(..., 2)`) не склеиваются в номер.
+ *
+ * Известные границы (сознательно):
+ * - 10-значный городской номер без префикса (`4951234567`) не маскируется — иначе под
+ *   маску попали бы метки времени Unix в секундах (10 цифр, первая `1`);
+ * - 10-значное число на `9` (например, ИНН `9701234567`) маскируется. Это ошибка
+ *   в безопасную сторону: лог теряет число, но номер телефона не утекает;
+ * - цепочка мелких чисел через точки или пробелы, где после `7`/`8`/`9` набирается
+ *   нужное число цифр, тоже может попасть под маску.
+ *
+ * Скорость: разделители и цифры не пересекаются, поэтому каждый повтор однозначен
+ * и катастрофического перебора нет (строки в 30–50 тыс. символов — миллисекунды).
+ */
+
+/** Разделитель между цифрами номера (без перевода строки) */
+const SEP = "[ \\t\\u00a0\\u2007\\u202f\\-\\u2010-\\u2015./()]*";
+
+/**
+ * Шаблон номера. Группы: 1–2 — две последние цифры номера с префиксом,
+ * 3–4 — две последние цифры мобильного без префикса.
+ */
+const PHONE_RE = new RegExp(
+    "(?<![\\dA-Za-z_+])(?:" +
+        `(?:\\+7|\\+?8|7)(?:${SEP}\\d){8}${SEP}(\\d)${SEP}(\\d)` +
+        "|" +
+        `\\(?9(?:${SEP}\\d){7}${SEP}(\\d)${SEP}(\\d)` +
+        ")(?!\\d)",
+    "g",
+);
+
+/**
+ * Заменяет каждый найденный номер на `+7 ••• •••-••-NN`, где NN — две последние цифры.
+ * Хвост оставлен, чтобы по логу можно было отличить один номер от другого.
+ */
+export function maskPhones(text: string): string {
+    return text.replace(PHONE_RE, (...args: unknown[]) => {
+        // args: совпадение, группы 1–4, смещение, исходная строка
+        const tail = typeof args[1] === "string" ? `${args[1]}${String(args[2])}` : `${String(args[3])}${String(args[4])}`;
+        return `+7 ••• •••-••-${tail}`;
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@andrey4emk/npm-app-back-b24",
-    "version": "5.0.0",
+    "version": "5.1.0",
     "description": "Bitrix24 OAuth helpers for Node.js projects",
     "main": "index.ts",
     "type": "module",
@@ -47,6 +47,7 @@
         "sendMessage/email.ts",
         "sendMessage/wappi.ts",
         "logs/logs.ts",
+        "logs/maskPhones.ts",
         "utils/fetchRetry.ts"
     ],
     "dependencies": {

package/sendMessage/chatApp.ts

@@ -215,7 +215,7 @@ export class ChatApp {
             // и вводим. Остальные ошибки летят наружу как раньше
             if (!isTimeoutError(error)) throw error;
 
-            // Уровень error — единственный, который уходит в чат B24. До появления
+            // Уровень error — единственный, который уходит в Телеграм через ретранслятор. До появления
             // таймаута зависание долетало исключением до потребителя и там порождало
             // задачу через errorB24(); перехватив ошибку здесь, мы обязаны сами оставить
             // след, иначе правка сделала бы отказ отправки тише, чем он был

package/sendMessage/email.ts

@@ -255,7 +255,7 @@ export class Email {
      * возвращался вызывающему как `error: false`.
      *
      * Отказ логируется не здесь: результат уходит вызывающему, а уровень `error`
-     * дублировался бы в чат B24. От таймаутов отправки в `Smsgold`/`Wappi` случай
+     * дублировался бы в Телеграм через ретранслятор. От таймаутов отправки в `Smsgold`/`Wappi` случай
      * отличается тем, что статус известен — сервер прямо сказал «не принял».
      */
     private checkDelivery(to: string, info: SendMailInfo): EmailResult {

package/sendMessage/smsgold.ts

@@ -163,7 +163,7 @@ export class Smsgold {
         } catch (error: unknown) {
             // Ответа не дождались: запрос уже ушёл, сообщение могло быть доставлено.
             // Это не «ошибка отправки» — статус неизвестен, и решить это кодом нельзя.
-            // Единственное место в классе, где пишем в лог: уровень error уходит в чат B24,
+            // Единственное место в классе, где пишем в лог: уровень error уходит в Телеграм через ретранслятор,
             // потому что разбираться должен человек
             if (isTimeoutError(error)) {
                 logs.add(

package/sendMessage/wappi.ts

@@ -137,7 +137,7 @@ export class Wappi {
             // Остальные ошибки летят наружу как раньше
             if (!isTimeoutError(error)) throw error;
 
-            // Уровень error — единственный, который уходит в чат B24. До появления
+            // Уровень error — единственный, который уходит в Телеграм через ретранслятор. До появления
             // таймаута зависание долетало исключением до потребителя и там порождало
             // задачу через errorB24(); перехватив ошибку здесь, мы обязаны сами оставить
             // след, иначе правка сделала бы отказ отправки тише, чем он был

package/utils/fetchRetry.ts

@@ -52,7 +52,7 @@ const SUSPICIOUS_TIMEOUT_MAX_MS = 999;
  * Значение от 1 до 999 применяется как есть, но с записью `warn`: столько миллисекунд
  * не хватит ни одному живому запросу, и это типовая путаница секунд с миллисекундами.
  * Молча такое значение пропускать нельзя — на бюджетах отправки оно превращается
- * в массовую недоставку с «неизвестным статусом» и потоком `error` в чат портала.
+ * в массовую недоставку с «неизвестным статусом» и потоком `error` в Телеграм через ретранслятор.
  *
  * Экспортируется по двум причинам: одинаковая семантика для всех бюджетов пакета
  * (дефолт `fetchRetry` и каждый из `FETCH_TIMEOUTS` читаются одной и той же функцией)
@@ -228,8 +228,10 @@ export function isPreConnectionError(error: unknown): boolean {
  *
  * URL входящего вебхука B24 содержит секрет прямо в пути
  * (`https://портал.bitrix24.ru/rest/1/<секрет>/method.json`), а токен авторизации
- * может приходить в query-параметрах. Хост и имя метода сохраняются — они нужны
- * для диагностики, тело секрета заменяется на `***`.
+ * может приходить в query-параметрах. Bot API Телеграма тоже держит токен в пути:
+ * `https://api.telegram.org/bot<id>:<токен>/<метод>` и `/file/bot<id>:<токен>/<путь>`.
+ * Хост, id бота и имя метода сохраняются — они нужны для диагностики, тело секрета
+ * заменяется на `***`.
  *
  * @param url — адрес запроса в любом виде, принимаемом fetch
  * @returns строка URL, пригодная для логирования
@@ -241,6 +243,9 @@ export function maskUrl(url: string | URL | Request): string {
         raw
             // Секрет входящего вебхука: /rest/<id пользователя>/<секрет>/
             .replace(/(\/rest\/\d+\/)[^/?#]+/gi, "$1***")
+            // Токен бота Телеграма: /bot<id>:<токен>/ и /file/bot<id>:<токен>/.
+            // Двоеточие бывает закодировано как %3A — адрес мог пройти через кодирование
+            .replace(/(\/bot\d+(?::|%3A))[^/?#]+/gi, "$1***")
             // Токены и подписи в query-параметрах. signature и sessid нужны отдельно:
             // ссылка на файл B24-диска несёт секрет именно в signature
             .replace(/([?&](?:auth|access_token|refresh_token|token|signature|sessid)=)[^&#]+/gi, "$1***")