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

package/README.md

@@ -17,6 +17,7 @@
     -   [Логирование](#логирование)
     -   [fetchRetry и таймауты](#fetchretry-и-таймауты)
 -   [Переменные окружения](#переменные-окружения)
+-   [Миграция на 4.0.0](#миграция-на-400)
 -   [Скрипты](#скрипты)
 -   [Лицензия](#лицензия)
 
@@ -26,6 +27,15 @@
 npm install @andrey4emk/npm-app-back-b24
 ```
 
+`nodemailer` — **опциональная peer-зависимость**: её ставит потребитель, и только если пользуется классом `Email`. Всем остальным она не нужна и не приезжает.
+
+```bash
+# Только тем, кто шлёт почту
+npm install nodemailer@9.0.5
+```
+
+Типы (`@types/node`, `@types/luxon` и прочие) пакет **не транслирует** — с 4.0.0 они лежат в его `devDependencies`. Потребителю, который гоняет `tsc`, нужны свои: подробности в разделе [Миграция на 4.0.0](#миграция-на-400).
+
 ### Точки входа
 
 | Импорт                                        | Что отдаёт                    | Поднимает OAuth-модуль |
@@ -33,6 +43,7 @@ npm install @andrey4emk/npm-app-back-b24
 | `@andrey4emk/npm-app-back-b24`                | всё                           | да                     |
 | `@andrey4emk/npm-app-back-b24/logs`           | `logs`                        | нет                    |
 | `@andrey4emk/npm-app-back-b24/fetchRetry`     | `fetchRetry`, `fetchWithTimeout`, `isNetworkError`, `isPreConnectionError`, `isTimeoutError`, `isAbortError`, `maskUrl`, `FETCH_TIMEOUTS`, `DEFAULT_FETCH_TIMEOUT_MS` | нет |
+| `@andrey4emk/npm-app-back-b24/email`          | `Email`                       | нет                    |
 
 Корневой импорт — barrel: он тянет модуль OAuth, который при загрузке читает `authB24.json` и, если приложение авторизовано, запускает таймер проактивного обновления токена. Проектам, которые ходят в B24 по **входящему вебхуку** или берут из пакета только логгер и `fetchRetry`, удобнее импортировать по подпутям — тогда OAuth-модуль не загружается вообще.
 
@@ -42,6 +53,13 @@ import { logs } from "@andrey4emk/npm-app-back-b24/logs";
 import { fetchRetry, maskUrl } from "@andrey4emk/npm-app-back-b24/fetchRetry";
 ```
 
+Подпуть `./email` стоит особняком: `Email` вынесен из barrel'а не ради экономии импорта, а ради зависимости. Он единственный тянет `nodemailer`, и пока класс лежал в barrel'е, почтовая библиотека приезжала во все восемь проектов — включая те шесть, что почту не шлют.
+
+```js
+// Почту шлём — ставим nodemailer и берём Email из подпути
+import { Email } from "@andrey4emk/npm-app-back-b24/email";
+```
+
 Корневой импорт при этом остаётся безопасным: если `APP_B24_CLIENT_ID` и `APP_B24_CLIENT_SECRET` не заданы, пакет считает, что OAuth в проекте не используется, молча выставляет `$b24 = null` и пишет об этом только в `debug`.
 
 ### Строгость типов
@@ -101,7 +119,6 @@ import {
     Event,
     ChatApp,
     Smsgold,
-    Email,
     Wappi,
     logs,
     fetchRetry,
@@ -112,6 +129,9 @@ import {
     FETCH_TIMEOUTS,
 } from "@andrey4emk/npm-app-back-b24";
 
+// Email живёт в подпути: он единственный тянет optional peer nodemailer
+import { Email } from "@andrey4emk/npm-app-back-b24/email";
+
 // $b24 — готовый экземпляр B24OAuth (или null, если токены не настроены)
 if ($b24) {
     const result = await $b24.callMethod("crm.contact.list", { limit: 5 });
@@ -191,11 +211,21 @@ const sent = await fetchWithTimeout("https://api.example.com/send", { method: "P
 
     Поведение прежнее у четырёх методов из пяти. **`callListMethod` отличается в двух местах:** он бросает внятную ошибку с именем метода там, где SDK падал `TypeError` из своих недр (портал вернул «мягкую» ошибку, ответ не список, конверт нечитаем, `next` не растёт), и у него есть потолок в 1000 страниц — при упоре в него вызов тоже бросает, а не отдаёт молча обрезанный список. Если у вас есть `try`/`catch` вокруг постраничных выборок, текст ошибки изменится; если его нет — падение станет заметнее, но не появится там, где раньше всё работало.
 
+    **`fetchListMethod` теперь тоже свой:** keyset-цикл пакета вместо `actions.v2.fetchList.make`. Форма запроса прежняя — тот же курсор по `idKey`, тот же навязанный порядок сортировки. Появился постраничный повтор (см. ниже), стали внятными ошибки (имя метода B24 в тексте вместо `TypeError` из недр SDK и `SdkError` с внутренним кодом библиотеки; если вы разбирали `error.code` у этого метода, разбор придётся заменить на чтение сообщения) и изменились правила остановки:
+
+    -   **выборку завершает только пустая страница.** Раньше, как в SDK, цикл останавливался ещё и на короткой — меньше 50 строк. У портала страница, укороченная правами доступа, штатна, поэтому старое правило могло молча отдать полсотни записей вместо нескольких тысяч. Цена нового — один лишний запрос на всю выборку, всегда пустой;
+    -   **нечитаемый курсор бросает.** Если в строках ответа нет числового идентификатора по ключу курсора, продолжить пагинацию нечем — вместо тихой остановки (SDK пишет предупреждение и выходит) выборка прерывается ошибкой «выборка прервана как неполная». Неполный список, отданный как полный, хуже громкого отказа;
+    -   **есть потолок в 20 000 страниц** и **проверка роста курсора** — обе бросают. Портал, отбросивший неизвестный ключ фильтра, отдаёт одну и ту же страницу бесконечно, без ошибки и без строки в логе; у SDK от этого нет никакой страховки.
+
+    **Ограничение по ключу курсора.** Один и тот же ключ идёт и на чтение идентификатора из строки ответа, и в `order`/`filter`. Методы, у которых имя поля в ответе отличается от сортируемого — например `tasks.task.list`, где в ответе `id`, а в фильтре `ID`, — этим методом не выбираются: передача `idKey: "id"` уберёт ошибку, но запрос уйдёт с параметрами, которых метод не понимает. Для таких выборок берите `callListMethod` или `actions.v2.fetchList.make` с опцией `cursorIdKey`. Ключ `>ID` в вашем фильтре пагинация перетирает своим курсором — об этом теперь пишется предупреждение уровня `warn`, как и про игнорируемый `order`.
+
     Прямой доступ к `$b24.actions.*` остаётся: это сырой SDK **без** retry и гейта идемпотентности. Если защита нужна, оборачивайте вызов в `callProtected()`.
 
     **Retry при сетевых ошибках:**
 
-    Экземпляр `$b24` обёрнут Proxy, который автоматически повторяет запросы при сетевых ошибках. Повторные попытки применяются к методам `callMethod`, `callListMethod`, `callBatch`, а также к обновлению токена (`refreshAuth`). Метод `fetchListMethod` из ретраев исключён — это async-генератор, оборачивать его в async-функцию нельзя. `callBatchByChunk` пакет реализует, но не ретраит.
+    Экземпляр `$b24` обёрнут Proxy, который автоматически повторяет запросы при сетевых ошибках. Повторные попытки применяются к методам `callMethod`, `callListMethod`, `callBatch`, а также к обновлению токена (`refreshAuth`). `callBatchByChunk` пакет реализует, но не ретраит.
+
+    Метод `fetchListMethod` Proxy снаружи не оборачивает — это async-генератор, обёртка в async-функцию сломала бы `for await`. Повтор у него внутренний и **постраничный**: обрыв на двенадцатой странице повторяет двенадцатую страницу, а не всю выборку. Уже отданные страницы не теряются и не дублируются, потому что курсор двигается только после успешной страницы. Раньше одиночный сбой обрывал выборку целиком, и прочитанное потребитель либо терял, либо принимал за полный результат.
 
     `callListMethod` повторяется целиком: при сетевом сбое пагинация начинается с нулевой страницы заново. Постраничный retry был бы сменой семантики, поэтому поведение оставлено прежним.
 
@@ -208,7 +238,19 @@ const sent = await fetchWithTimeout("https://api.example.com/send", { method: "P
 
     **Уровни логов.** Промежуточные попытки пишутся на `warn`, окончательный отказ — на `error`: исчерпание всех попыток и отмена повтора гейтом. Так один упавший вызов даёт одно сообщение в чат B24 вместо пяти, но при этом не теряется совсем. Логировать провал обязан сам Proxy: `errorB24()`, `Event` и `Smsgold` ошибку только возвращают вызывающему коду и в лог не пишут.
 
-    **Создающие вызовы не повторяются Proxy-слоем.** Если в вызове есть метод, создающий сущность или запускающий действие (`*.add`, `*.create`, `*.start`, `*.send`, `*.uploadfile`, `*.import`, `*.register` — в том числе среди команд `callBatch`), retry отменяется, а в лог идёт `повтор отменён`. Причина: транспортная ошибка не говорит, дошёл ли запрос до портала. `NETWORK_ERROR` приходит и когда соединение не состоялось, и когда оно оборвалось после того, как портал уже принял и выполнил запрос — а повтор во втором случае создаёт вторую задачу, второй файл, второй экземпляр бизнес-процесса. Идемпотентные записи (`*.update`, `*.delete`, `*.set`) повторяются как прежде: повторное применение даёт то же состояние.
+    **Создающие вызовы не повторяются Proxy-слоем.** Если в вызове есть метод, создающий сущность или запускающий действие (`*.add`, `*.create`, `*.start`, `*.send`, `*.uploadfile`, `*.import`, `*.register` — в том числе среди команд `callBatch`), retry отменяется, а в лог идёт `повтор отменён`. Причина: транспортная ошибка не говорит, дошёл ли запрос до портала. Обрыв приходит и когда соединение не состоялось, и когда оно случилось после того, как портал уже принял и выполнил запрос — а повтор во втором случае создаёт вторую задачу, второй файл, второй экземпляр бизнес-процесса. Идемпотентные записи (`*.update`, `*.delete`, `*.set`) повторяются как прежде: повторное применение даёт то же состояние.
+
+    Ключевое слово ищется **в любой позиции** имени, а не только в конце: `imconnector.send.messages` и `imconnector.send.status.delivery` тоже под гейтом. После ключевого слова обязателен разделитель (`.`, `?` или конец строки), поэтому `crm.deal.addcustom` и `landing.landing.addbytemplate` повторяются как прежде.
+
+    Попадание `imconnector.send.status.delivery` под гейт — осознанная плата за правило без списка исключений. Метод лишь фиксирует доставку и отмечает сообщение прочитанным, повтор его безвреден, а отказ от повтора стоит только потерянной отметки о доставке: переписку это не ломает. Ручной же список исключений молча устаревал бы при появлении нового метода портала — ровно тот дефект, которым и был пропуск `imconnector.send.messages` мимо гейта.
+
+    **Отдельный список методов, теряющих данные при повторе.** Пока в нём один `event.offline.get`: вызов резервирует пакет очереди офлайн-событий и прячет его от следующих запросов, поэтому потерянный ответ уносит `process_id` с собой, а повтор зарезервировал бы ещё один пакет поверх первого. Сущностей метод не создаёт, и в логе это видно по фразе: `повтор отменён, вызов резервирует данные на портале (event.offline.get)`.
+
+    **Исключение для обоих ограничений — доказанный pre-connection.** Коды `ENOTFOUND`, `EAI_AGAIN`, `ECONNREFUSED`, `ENETUNREACH`, `EHOSTUNREACH`, `ENETDOWN` означают, что соединение с целевым хостом не состоялось: дубликата повтор дать не может. Такие вызовы повторяются все пять раз, а в warn-строке появляется хвост `— соединение не состоялось, ограничение (...) снято`.
+
+    Следствие для вашего кода: после снятия гейта отказ вызова больше не означает, что на портале ничего не произошло — первая попытка могла упасть на `ECONNREFUSED`, а вторая дойти и оборваться уже на ответе. Дубликата пакет при этом не создаёт, но потребитель с собственным повтором поверх пакета создаст.
+
+    **Провал обмена refresh-токена повторов не получает.** Когда обмен падает внутри вызова, попытка ровно одна, а в лог идёт строка уровня `error` с исходным кодом и статусом ответа oauth-хоста: `обновление токена не удалось (invalid_grant/400), повтор небезопасен: сервер мог провести ротацию`. Под правило попадает **любой** отказ обмена, кроме доказанного pre-connection, — и мёртвый токен после ротации, и транзиентные 429/503 от oauth-хоста: различить их по ответу нельзя. Если ротация прошла, локальный `refresh_token` мёртв независимо от повтора и нужна переавторизация приложения на портале. DNS-сбой на oauth-хосте под это правило не попадает: соединение не состоялось, значит повторяем.
 
     Команды `callBatch` разбираются в обеих формах — кортеж `["crm.deal.add", {...}]` (основная в SDK 2.x) и объект `{ method, params }`. Если форму команды разобрать не удалось, вызов считается создающим и не повторяется: для защиты от дубликатов безопаснее ошибиться в сторону осторожности.
 
@@ -220,6 +262,8 @@ const sent = await fetchWithTimeout("https://api.example.com/send", { method: "P
 
     **Обмен refresh-токена** повторяется по более строгому правилу — только если соединение заведомо не состоялось (см. `isPreConnectionError()`). При таймауте или обрыве сервер мог уже провести ротацию; тогда локальный `refresh_token` мёртв независимо от наших действий, и повтор не помогает, а лишь маскирует проблему серией одинаковых отказов. Следующая попытка всё равно будет: проактивный таймер повторяет через 2 минуты при времени жизни токена около часа.
 
+    Над обменом стоит **сторожевой таймер** с бюджетом 2 минуты. Он нужен потому, что сам обмен идёт внутри SDK отдельным HTTP-клиентом без таймаута: зависшее соединение раньше занимало мьютекс навсегда, все следующие обновления приклеивались к мёртвому запросу, и через час процесс начинал получать 401 на каждый вызов. Сторож освобождает **только** мьютекс — сам запрос не отменяется, и если ответ всё же придёт, токены сохранятся: колбэк сохранения SDK зовёт сам. Ждущий получает ошибку «обмен refresh-токена завис», повтор делает проактивный таймер. `reinitializeB24()` (а значит и сохранение токенов с фронта через `saveAuthB24Handler`) сбрасывает мьютекс принудительно и не ждёт зависший обмен.
+
     У самого SDK есть собственный слой ретраев (`maxRetries: 3`), но на транспортных ошибках он выключен — там одна попытка, повторяет только Proxy. При 429, 503 и неизвестных 5xx SDK повторяет по-прежнему.
 
     Отдельно про ответы шлюза перед порталом. **502** повторяет наш слой: шлюз не смог получить ответ от upstream, запрос почти наверняка не выполнялся. **504** не повторяет никто — это «портал взял запрос и считает прямо сейчас»; повтор создающего вызова дал бы дубликат, а читающего — ничего, кроме нагрузки на портал в худший для него момент.
@@ -316,7 +360,7 @@ const sent = await fetchWithTimeout("https://api.example.com/send", { method: "P
 
     -   **Параметры:**
         -   `run` (`() => Promise<T>`) — сам вызов.
-        -   `methodName` (`string | string[]`) — имя REST-метода B24 (**не** метода SDK) либо список имён, если внутри batch: по ним гейт решает, создаёт ли вызов сущность.
+        -   `methodName` (`string | string[]`) — имя REST-метода B24 (**не** метода SDK) либо список имён, если внутри batch. По ним гейт решает не только «создаёт ли вызов сущность», но и «не входит ли он в список методов, повтор которых теряет данные» (`event.offline.get`).
     -   **Возвращает:** промис с результатом `run`.
 
     ```js
@@ -338,7 +382,7 @@ 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)`.
+-   **`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`.
 
     ```ts
     import type { B24Client } from "@andrey4emk/npm-app-back-b24";
@@ -500,7 +544,12 @@ const sent = await fetchWithTimeout("https://api.example.com/send", { method: "P
             ```
 
         -   **Особенности:**
-            -   **Автоматически отбрасывает и очищает события пользователя 138** — владельца OAuth-токенов приложений. Это защита от петли: всё, что приложения сами пишут в B24, приходит событием с `user_id: '138'`, и без фильтра код обрабатывал бы собственные записи повторно. Оборотная сторона: ручные правки под этой же учёткой (администратор портала) тоже не возвращаются. **Для полной выгрузки всех изменений класс не подходит** — там читать `event.offline.get` напрямую.
+            -   **Автоматически отбрасывает и очищает события пользователя 138** — владельца OAuth-токенов приложений. Это защита от петли: всё, что приложения и роботы пишут в B24 под этой учёткой, приходит событием с `user_id: '138'`. Собственные правки платформа приложению не отдаёт, а правки соседнего приложения под тем же владельцем — отдаёт, и без фильтра они обрабатывались бы как внешние изменения по кругу. Оборотная сторона: ручные правки под этой же учёткой (администратор портала) тоже не возвращаются. **Для полной выгрузки всех изменений класс не подходит** — там читать `event.offline.get` напрямую.
+            -   **Битая запись в ветке сущностей не роняет весь вызов.** Битой считается запись, которую обработать нечем: не читается идентификатор сущности `EVENT_DATA.FIELDS.ID` (в том числе когда на его месте пришёл пустой массив — так PHP сериализует пустую коллекцию) или не читается ключ очистки `MESSAGE_ID`. Такая запись отбрасывается, её `MESSAGE_ID` уходит в очистку вместе с системными, а в лог пишется одна строка `warn` с причиной. Раньше такая запись валила `get()` исключением: пакет к тому моменту уже зарезервирован порталом, `processId` наружу не ушёл, и очистить его было нечем. Запись, у которой не читается сам `MESSAGE_ID`, только логируется — передавать в `clear()` нечего, снять её с резерва может лишь `clear(processId)` целиком.
+            -   **Отсутствие `EVENT_ADDITIONAL.user_id` битой записью не является.** Идентификатор сущности на месте, значит запись обработать можно: она уходит потребителю как рабочая, а в лог пишется строка `warn` о том, что системной её признать нечем. Удалять такую запись нельзя — `event.offline.clear` снимает её с резерва безвозвратно.
+            -   **Если битой оказалась вся выборка целиком** (больше одной записи и ни одной рабочей), в лог уходит строка уровня `error` с числом записей и причиной первой: так выглядит не одна кривая запись, а смена формы ответа портала. Очистку это не меняет — записи по-прежнему снимаются с резерва.
+            -   **Сбой `event.offline.clear` не уносит выборку.** Исключение перехватывается, пишется строка `warn`, активные записи возвращаются потребителю. Иначе он остался бы и без `processId`, и без событий, а пакет уже зарезервирован порталом. Если в ответе нет `process_id`, очистка пропускается, а в лог уходит одна строка `warn` на весь вызов: записи придут следующим опросом и будут обработаны повторно.
+            -   Значение `user_id` сравнивается после нормализации, поэтому системным считается и строка `'138'`, и число `138`. Портал сегодня отдаёт это поле строкой; форма поля на защиту от петли влиять не должна.
             -   Для коннекторных событий конвертирует файлы в формат с типами `image`, `video`, `document`.
             -   Если событий нет, возвращает `data` с пустыми массивами.
             -   **Гранулярность очистки — запись очереди, а не сообщение.** Одна запись коннектора (один `MESSAGE_ID`) может нести несколько сообщений, и они приходят отдельными элементами `message` с одинаковым `messageId`. Очистка по этому ключу удаляет запись целиком: если из двух сообщений одной записи ушло одно, `clear()` заберёт и неотправленное. Строить поэлементную очистку с точностью до сообщения на `messageId` нельзя. Для дедупликации отдельных сообщений он не годится по той же причине — у сообщений одной записи он общий, для этого есть `im.id`. Обратная сторона: запись, из которой не разобрано ни одного сообщения, в `data.message` не попадёт вовсе, и очистка по собранным `messageId` её не заберёт. Безопасный режим — `clear(processId)` целиком.
@@ -675,7 +724,7 @@ const sent = await fetchWithTimeout("https://api.example.com/send", { method: "P
 -   **`Email`** — класс для отправки email через SMTP Яндекса. Экземпляр нужно создать самостоятельно.
 
     ```js
-    import { Email } from "@andrey4emk/npm-app-back-b24";
+    import { Email } from "@andrey4emk/npm-app-back-b24/email";
 
     const emailClient = new Email({
         user: "your-email@yandex.ru",
@@ -694,8 +743,9 @@ const sent = await fetchWithTimeout("https://api.example.com/send", { method: "P
                 -   `text` (string) — текстовая версия.
                 -   `html` (string) — опционально, HTML-версия.
                 -   `fileUrl` (string) — опционально, ссылка на файл (будет скачан и прикреплён).
-                -   `fileName` (string) — опционально, имя файла для вложения.
-        -   **Возвращает:** промис с объектом `{ error, info }` при успехе или `{ error, message }` при ошибке.
+                -   `fileName` (string) — опционально, имя файла для вложения. Не задано — имя выводится из последнего сегмента пути в `fileUrl`, а если и оттуда не выходит, вложение называется `attachment`.
+                -   `attachments` (array) — опционально, готовые вложения вида `{ filename, content }`, где `content` — `Buffer`. Скачанное по `fileUrl` **добавляется** к ним, а не заменяет: оба поля независимы, и заполнивший оба получает оба вложения. Порядок — сначала переданные, затем скачанное.
+        -   **Возвращает:** промис с объектом `{ error, info }` при успехе или `{ error, message }` при ошибке. `error: true` приходит и тогда, когда SMTP принял копию отправителю, но **отверг получателя**: в `to` всегда уходит пара «получатель + отправитель», а `sendMail` резолвится, если принят хотя бы один адрес.
 
         ```js
         const result = await emailClient.send({
@@ -709,7 +759,13 @@ const sent = await fetchWithTimeout("https://api.example.com/send", { method: "P
     -   **Особенности:**
         -   SMTP-сервер: `smtp.yandex.ru:465` (SMTPS).
         -   Копия письма автоматически отправляется на адрес отправителя.
-        -   Транспорт — `nodemailer` `^9` (диапазон, а не точная версия: иначе патч безопасности нельзя было бы применить на стороне потребителя).
+        -   **Адрес получателя проверяется до вызова транспорта.** Пустая строка, строка с пробелом, адрес без собаки или с пустой частью слева либо справа дают `{ error: true }`, и письмо не отправляется вовсе — раньше такой `to` давал «успешную» отправку копии себе. Проверка намеренно грубая: точка в домене не требуется, полную валидацию адреса делает почтовый сервер. Поле `to` принимает **ровно один адрес**: формы `Имя <адрес>` и перечисление через запятую не поддерживаются и дают `{ error: true }`.
+        -   **Отвергнутый получатель — это ошибка.** Ответ транспорта разбирается: адрес ищется в `accepted` и `rejected`, элементы принимаются и строкой, и объектом `{ name, address }`. Текст ошибки несёт адрес и ответ сервера. Сверка идёт по **нормализованному** адресу: снимается регистр, снимаются угловые скобки, домен приводится к punycode. Иначе живой адрес объявлялся бы недоставленным — почтовый сервер возвращает адреса из конверта, а не в том виде, как их передали: `ivan@пример.рф` приходит обратно как `ivan@xn--e1afmkfd.xn--p1ai`, а `<a@b.ru>` — как `a@b.ru`. Если транспорт не сообщил ни `accepted`, ни `rejected`, результат считается успешным и в лог уходит одна строка `warn`: объявить доставленное письмо ошибкой было бы хуже исходного дефекта.
+        -   **Входной объект не мутируется.** Прежняя реализация записывала вложения обратно в переданный `dataMail`, затирая `attachments` вызывающего.
+        -   **Второй аргумент конструктора — подмена транспорта.** `new Email(auth, transport)` принимает любой объект с методом `sendMail(options)` (тип `MailTransport`). Нужен тестам и потребителю со своим SMTP; без него класс поднимает транспорт Яндекса сам.
+        -   **Класс живёт в подпути `@andrey4emk/npm-app-back-b24/email`, а не в корне.** Из barrel'а он убран в 4.0.0.
+        -   Транспорт — `nodemailer`, **опциональная peer-зависимость** с диапазоном `^9.0.5 || ^10.0.0`. Ставит его потребитель. Нижняя граница — CVE (GHSA-p6gq-j5cr-w38f, уязвимы версии `<= 9.0.0`), верхняя — проверенная совместимость с десяткой.
+        -   `@types/nodemailer` нужен **только на девятке**. У `nodemailer` 10 типы свои, и TypeScript предпочтёт их; отдельный пакет типов там лишний.
         -   Вложения передаются готовым `Buffer` — файл по `fileUrl` пакет скачивает сам. Поля `path` и `href` намеренно не поддерживаются: nodemailer не должен ходить по URL. Скачивание идёт через `fetchWithTimeout` с бюджетом 60 секунд.
         -   Таймауты SMTP-транспорта переопределены: соединение 15 с, приветствие 10 с, сокет 120 с. Дефолты nodemailer (2 мин / 30 с / 10 мин) слишком щедры — письмо на Яндекс уходит за секунды, а 10 минут молчания сокета блокируют вызывающую очередь.
 
@@ -880,7 +936,7 @@ const sent = await fetchWithTimeout("https://api.example.com/send", { method: "P
 -   **Свой `options.signal` отключает наш дефолт.** Если вызывающий передал сигнал именно в `options`, а `timeoutMs` не задан, пакет своего таймаута не добавляет — чужой осознанный бюджет не обрезается. Явно переданный `timeoutMs` применяется всегда, тогда побеждает тот сигнал, который сработал раньше. Отмена по чужому сигналу **никогда не повторяется**; различаем её по объекту сигнала, а не по типу ошибки: причиной отмены может быть любой объект, включая `TypeError`.
 -   **Сигнал у объекта `Request` на дефолт не влияет.** Он участвует в отмене — сигналы склеиваются через `AbortSignal.any`, иначе `fetch(request, init)` затёр бы его, — но признаком «вызывающий сам управляет временем» не считается: у любого `Request` сигнал есть всегда, даже когда его никто не задавал. Учитывать его значило бы молча снять таймаут со всех вызовов такой формы. Нужен свой бюджет при вызове с `Request` — передавайте `timeoutMs` пятым аргументом.
 -   **Таймаут при чтении тела не повторяется и не логируется.** Бюджет действует до конца запроса, поэтому `res.text()` / `res.arrayBuffer()` после возврата из `fetchRetry` могут упасть с `TimeoutError` уже у вас. Функция об этом не знает: повторов там нет, записи в лог тоже. Читаете большое тело — задавайте `timeoutMs` с запасом на скачивание.
--   **Переменная `FETCH_TIMEOUT_MS`** меняет дефолт без правки кода (читается один раз при загрузке модуля), `FETCH_TIMEOUT_MS=0` выключает таймаут. Это аварийный рычаг на случай, когда дефолт обрывает живой долгий запрос — отчёт Seatable, Google Sheets, МойСклад. Действует только на вызовы **без явного** `timeoutMs`: внутренние вызовы пакета (ChatApp, Wappi, SMS, скачивание файлов) передают свои значения из `FETCH_TIMEOUTS` и переменную игнорируют. Значение должно быть целым от 0 до 2 147 483 647 — непригодное отбрасывается с записью в лог, а не выключает защиту молча.
+-   **Переменная `FETCH_TIMEOUT_MS`** меняет дефолт без правки кода (читается один раз при загрузке модуля), `FETCH_TIMEOUT_MS=0` выключает таймаут. Это аварийный рычаг на случай, когда дефолт обрывает живой долгий запрос — отчёт Seatable, Google Sheets, МойСклад. Действует только на вызовы **без явного** `timeoutMs`: внутренние вызовы пакета (ChatApp, Wappi, SMS, скачивание файлов) берут свои значения из `FETCH_TIMEOUTS`, и каждое из них переопределяется отдельной переменной (см. ниже). Значение должно быть целым от 0 до 2 147 483 647 — непригодное отбрасывается с записью в лог, а не выключает защиту молча. Значение от 1 до 999 применяется **как есть**, но с записью `warn`: столько миллисекунд не хватит ни одному живому запросу, и это типовая путаница секунд с миллисекундами. Ноль под правило не попадает — это задокументированное выключение таймаута.
 -   **Ограничение при вызове с объектом `Request`:** тело такого запроса читается первой попыткой, и повтор упадёт с `body used already`. Существовало и до таймаутов; для повторяемых запросов передавайте строку URL и `options`.
 
 -   **`fetchWithTimeout(url, options?, timeoutMs?)`** — один запрос с бюджетом времени, **без повторов и без логирования**. Для неидемпотентных операций: отправка сообщения, создание сущности — там, где повтор мог бы продублировать действие, но защита от зависшего соединения нужна. Правила про чужой сигнал те же, что у `fetchRetry`. Внутри пакета через неё идут все отправки ChatApp, Wappi и SMSGold.
@@ -895,7 +951,20 @@ const sent = await fetchWithTimeout("https://api.example.com/send", { method: "P
     );
     ```
 
--   **`FETCH_TIMEOUTS`** — именованные бюджеты, которыми пакет пользуется сам: `quick` 10 000 (токены), `api` 20 000 (короткое чтение), `send` 30 000 (отправка), `transfer` 60 000 (файлы). **`DEFAULT_FETCH_TIMEOUT_MS`** — действующий дефолт `fetchRetry` (60 000 либо значение `FETCH_TIMEOUT_MS`).
+-   **`FETCH_TIMEOUTS`** — именованные бюджеты, которыми пакет пользуется сам. Каждый переопределяется своей переменной окружения:
+
+    | Ключ       | Переменная                 | Дефолт, мс | Где применяется          |
+    | ---------- | -------------------------- | ---------- | ------------------------ |
+    | `quick`    | `FETCH_TIMEOUT_QUICK_MS`   | 10 000     | токены                   |
+    | `api`      | `FETCH_TIMEOUT_API_MS`     | 20 000     | короткое чтение          |
+    | `send`     | `FETCH_TIMEOUT_SEND_MS`    | 30 000     | отправка                 |
+    | `transfer` | `FETCH_TIMEOUT_TRANSFER_MS`| 60 000     | файлы и вложения         |
+
+    Значения читаются **один раз при загрузке модуля**, поэтому менять их нужно до старта процесса. Проверка та же, что у `FETCH_TIMEOUT_MS`: целое от 0 до 2 147 483 647, непригодное значение даёт строку `warn` и дефолт.
+
+    **`0` выключает таймаут для этого бюджета целиком.** У `send` и `transfer` это снимает заодно защиту «неизвестный статус доставки»: зависшая отправка снова держится до таймаутов undici, а `unknownDelivery` в `Smsgold` не выставится никогда. Пользоваться нулём только как аварийным рычагом.
+
+    **`DEFAULT_FETCH_TIMEOUT_MS`** — действующий дефолт `fetchRetry` (60 000 либо значение `FETCH_TIMEOUT_MS`).
 
 -   **`isTimeoutError(error)` / `isAbortError(error)`** — различают «не дождались» и «отменили». Ошибка таймаута не оборачивается в свою: наружу идёт исходный `DOMException` с `name: "TimeoutError"` (отмена без причины — `"AbortError"`), проверки читают именно `name`.
 
@@ -922,6 +991,10 @@ const sent = await fetchWithTimeout("https://api.example.com/send", { method: "P
 | `APP_NAME`                  | Название приложения (используется в описании задач)           |
 | `CONFIG_DIR`                | Путь к директории с конфигами (по умолчанию `../config`)      |
 | `FETCH_TIMEOUT_MS`          | Бюджет одной попытки `fetchRetry`/`fetchWithTimeout`, мс (по умолчанию `60000`; `0` — без таймаута) |
+| `FETCH_TIMEOUT_QUICK_MS`    | Бюджет `FETCH_TIMEOUTS.quick` — токены, мс (по умолчанию `10000`)               |
+| `FETCH_TIMEOUT_API_MS`      | Бюджет `FETCH_TIMEOUTS.api` — короткое чтение, мс (по умолчанию `20000`)        |
+| `FETCH_TIMEOUT_SEND_MS`     | Бюджет `FETCH_TIMEOUTS.send` — отправка, мс (по умолчанию `30000`)              |
+| `FETCH_TIMEOUT_TRANSFER_MS` | Бюджет `FETCH_TIMEOUTS.transfer` — файлы и вложения, мс (по умолчанию `60000`)  |
 | `CHATAPP_EMAIL`             | Email аккаунта ChatApp                                        |
 | `CHATAPP_PASS`              | Пароль аккаунта ChatApp                                       |
 | `CHATAPP_APP_ID`            | ID приложения в ChatApp                                       |
@@ -937,14 +1010,93 @@ APP_NAME=MyApp
 CONFIG_DIR=../config
 FETCH_TIMEOUT_MS=60000
 
+# Именованные бюджеты пакета — задавать только при необходимости, иначе действуют дефолты
+# FETCH_TIMEOUT_QUICK_MS=10000
+# FETCH_TIMEOUT_API_MS=20000
+# FETCH_TIMEOUT_SEND_MS=30000
+# FETCH_TIMEOUT_TRANSFER_MS=60000
+
 CHATAPP_EMAIL=your-email@example.com
 CHATAPP_PASS=your-password
 CHATAPP_APP_ID=your-app-id
 ```
 
+## Миграция на 4.0.0
+
+Выпуск ломающий. Правок у потребителя четыре, все механические.
+
+### 1. `Email` переехал в подпуть
+
+Из общего импорта его убрать, добавить отдельной строкой:
+
+```diff
+-import { $b24, logs, Email } from "@andrey4emk/npm-app-back-b24";
++import { $b24, logs } from "@andrey4emk/npm-app-back-b24";
++import { Email } from "@andrey4emk/npm-app-back-b24/email";
+```
+
+Затрагивает два проекта: `b24_conector/server/api/sendMessage.ts` и `b24_desktop/server/api/sendMessage.js` (первая строка в обоих). Больше `Email` из пакета никто не импортирует.
+
+### 2. `nodemailer` — теперь зависимость потребителя
+
+Кто пользуется `Email`, ставит его себе: `pnpm add nodemailer@9.0.5` (оба проекта на pnpm). Диапазон peer — `^9.0.5 || ^10.0.0`. Тем же двум проектам `@types/nodemailer` в `devDependencies`, если остаются на девятке; на десятке типы приходят с самим пакетом.
+
+Шаг обязателен обоим, но по разным причинам:
+
+-   **`b24_conector`** — `nodemailer` в его `package.json` отсутствует вовсе, библиотека приезжала транзитивно из наших `dependencies`. После 4.0.0 не приедет, и первый же импорт `server/api/sendMessage.ts` упадёт с `ERR_MODULE_NOT_FOUND`. Вместе с почтой встанут `ChatApp`, `Wappi` и SemySMS — они живут в том же модуле. Пропустить шаг нельзя;
+-   **`b24_desktop`** — зависимость уже прописана в его `package.json`, поставленная версия `9.0.5` подходит под диапазон. Здесь достаточно сверки.
+
+Под pnpm несовпадение опционального peer не блокирует установку: менеджер пишет `WARN` и завершает работу с нулевым кодом. Кому нужен жёсткий блок — `strict-peer-dependencies=true` в своём `.npmrc`.
+
+Остальным шести проектам делать нечего — почтовая библиотека к ним больше не приезжает.
+
+### 3. `@types/*` больше не приезжают из пакета
+
+Они переехали в `devDependencies` и потребителю не транслируются. Кто гоняет `tsc`, держит свои:
+
+-   `@types/node` — всем;
+-   `@types/luxon` — всем, кто импортирует корень (`errTaskB24.ts` тянет `luxon` в рантайме);
+-   `@types/express` — **больше не нужен из-за нас никому**: пакет типы `express` не импортирует вовсе.
+
+Без `@types/luxon` тайпчек упадёт с `TS7016` на `bitrix24/errTaskB24.ts`. Семь из восьми живых потребителей его уже держат.
+
+### 4. Изменённые публичные типы
+
+`any` в поверхности пакета заменён на `unknown` — читающий поле напрямую добавляет приведение.
+
+| Что                                            | Было    | Стало                       |
+| ---------------------------------------------- | ------- | --------------------------- |
+| `data` у `event.get()` и `event.clear()`       | `any`   | `unknown`                   |
+| `ConnectorMessage.file`                        | `any[] \| null` | `TelegramFile[] \| null`          |
+| `ConnectorMessage.attachments`                 | `any[] \| null` | `unknown[] \| null`               |
+| `ConnectorMessage.im`                          | `any \| null`   | `Record<string, unknown> \| null` |
+| `data` у методов `Wappi`                       | `any`   | `unknown`                   |
+| `data` у `errorB24()`                          | `any`   | `unknown`                   |
+
+```diff
+-const { data } = await event.get("ONCRMDEALUPDATE");
+-for (const id of data.entitysId) { /* ... */ }
++const { data } = await event.get("ONCRMDEALUPDATE");
++const events = data as EntityEvents;
++for (const id of events.entitysId) { /* ... */ }
+```
+
+Тип `TelegramFile` экспортируется из пакета — своё объявление в `b24_conector` можно убрать, но замена не drop-in: у них поле объявлено `name?: string`, в пакете оно `name: string`. Разбор пакета всегда отдаёт строку (на битом элементе — пустую), поэтому чтение вида `fileInfo.name || fallback` продолжит работать. Сверки потребуют их собственные места, где `TelegramFile` создаётся, — в том числе очередь ретраев `confB24Outbox.ts`: объект без `name` в наш тип не ляжет и упадёт тайпчеком.
+
+`saveAuthB24Handler` больше не типизирован типами `express`, но по-прежнему принимает `Request`/`Response` без правок: `app.post("/saveAuthB24", saveAuthB24Handler)` работает как раньше.
+
+Дефолты дженериков `callMethod`, `callBatch`, `fetchListMethod` и `getResultData` остались `any` намеренно — код вида `chunk.forEach((x) => x.ID)` продолжает компилироваться.
+
+### Что изменилось само, правок не требует
+
+-   Вместе с `Email` из барреля уехали и его типы — `MailTransport` и `SendMailInfo`. Теперь они в подпути `@andrey4emk/npm-app-back-b24/email`. Из потребителей их никто не импортирует.
+-   `saveAuthB24Handler` на запрос **без тела** отвечает `400 Не заполнены обязательные поля.` вместо прежних `500`. Раньше разбор пустого тела падал и уходил в общий `catch`.
+-   Он же отвечает `400` на **нестроковые поля** тела: объект в `access_token`, число в `member_id`, нечисловой `expires_in`. Раньше такой запрос давал `500` — а в 4.0.0 до этой правки успевал затереть рабочий `config/authB24.json` строкой `"[object Object]"` и ответить `201`. Файл токенов в этом случае не трогается.
+-   `expires_in`, пришедший строкой (`"3600"`), считается правильно. Раньше склейка строк в расчёте `expires` давала абсурдную дату.
+
 ## Скрипты
 
--   `npm run test` — запуск тестов (заглушка).
+-   `npm run test` — прогон юнит-тестов из `tests/` через встроенный `node --test`. Дополнительных зависимостей не нужно: `.ts` запускаются на нативном стирании типов Node, поэтому прогону нужен Node 22.6+ (`engines: ">=20.3.0"` — это требование к потребителю пакета, а не к разработке). Сети тесты не касаются, в тарбол папка не попадает.
 -   `npm run pack:dry` — предпросмотр содержимого пакета перед публикацией.
 
 ## Лицензия

package/bitrix24/b24/config.ts

@@ -0,0 +1,24 @@
+import Conf from "conf";
+import path from "path";
+
+import dotEnv from "dotenv";
+dotEnv.config();
+
+// ==================== Константы ====================
+
+export const CONFIG_DIR = process.env.CONFIG_DIR || "../config";
+export const APP_ENV = process.env.APP_ENV || "PROD";
+export const CLIENT_ID = process.env.APP_B24_CLIENT_ID;
+export const CLIENT_SECRET = process.env.APP_B24_CLIENT_SECRET;
+
+export const confAuthB24 = new Conf({
+    cwd: path.resolve(CONFIG_DIR),
+    configName: "authB24",
+});
+
+// ==================== Утилиты ====================
+
+/** Убирает протокол из домена (https://example.bitrix24.ru → example.bitrix24.ru) */
+export function cleanDomain(domain: string): string {
+    return domain.replace(/^https?:\/\//, "");
+}