@andrey4emk/npm-app-back-b24 3.9.0 → 4.0.1

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 });
@@ -422,7 +442,7 @@ const sent = await fetchWithTimeout("https://api.example.com/send", { method: "P
     | `createdBy`      | number           | `138`                     | ID создателя                                   |
     | `responsibleId`  | number           | `1`                       | ID ответственного                              |
     | `deadline`       | ISO string       | `DateTime.now() + 1 день` | Дедлайн в ISO формате                          |
-    | `groupId`        | number\|null     | `null`                    | ID группы (опционально)                        |
+    | `groupId`        | number\|null     | `B24_ERROR_TASK_GROUP_ID` или `null` | ID группы; не передан — берётся переменная окружения |
     | `accomplices`    | number[]         | `[]`                      | Массив ID соисполнителей                       |
     | `maxTasks`       | number           | `100`                     | Максимум существующих задач с таким названием  |
     | `ufCrmTask`      | string\|string[] | `""`                      | Значение для `UF_CRM_TASK` (массив или строка) |
@@ -439,6 +459,10 @@ const sent = await fetchWithTimeout("https://api.example.com/send", { method: "P
     });
     ```
 
+    **Отказ портала виден в логе.** Если портал отказал в создании задачи (нет прав, указанной группы не существует), пишется одна строка уровня `error` с заголовком задачи, номером группы и текстом ошибки. Сетевые сбои этой строки не дают: их уже записал слой повторов, и вторая ушла бы дублем в чат B24.
+
+    **Группа задачи по умолчанию.** Если `groupId` не передан, группа берётся из переменной окружения `B24_ERROR_TASK_GROUP_ID`. Явно переданное значение всегда важнее переменной: `null` и `0` означают осознанное «без группы» и дефолт не подхватывают. Переменная читается один раз при загрузке модуля — правка `process.env` в рантайме дефолт не двигает, нужен перезапуск процесса. Если переменная не задана или непригодна (не целое больше нуля), поведение прежнее — задача создаётся без группы, плюс одна строка уровня `warn` за процесс. Строка пишется при первом вызове, которому дефолт реально понадобился: у потребителя, который всегда передаёт группу сам, в логе не появится ничего.
+
 -   **`checkB24Scope()`** — проверяет и логирует права (скоупы) приложения Bitrix24. Вызывается автоматически при старте, если `$b24` инициализирован.
 
 ### События
@@ -704,7 +728,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",
@@ -743,7 +767,9 @@ const sent = await fetchWithTimeout("https://api.example.com/send", { method: "P
         -   **Отвергнутый получатель — это ошибка.** Ответ транспорта разбирается: адрес ищется в `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; без него класс поднимает транспорт Яндекса сам.
-        -   Транспорт — `nodemailer` `^9` (диапазон, а не точная версия: иначе патч безопасности нельзя было бы применить на стороне потребителя).
+        -   **Класс живёт в подпути `@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 минут молчания сокета блокируют вызывающую очередь.
 
@@ -967,6 +993,7 @@ const sent = await fetchWithTimeout("https://api.example.com/send", { method: "P
 | `APP_B24_CLIENT_SECRET`     | Client Secret приложения Bitrix24                               |
 | `APP_ENV`                   | Определяет окружение, используется как ключ секции авторизации   |
 | `APP_NAME`                  | Название приложения (используется в описании задач)           |
+| `B24_ERROR_TASK_GROUP_ID`   | ID группы по умолчанию для задач `errorB24()` (не задана — задача без группы) |
 | `CONFIG_DIR`                | Путь к директории с конфигами (по умолчанию `../config`)      |
 | `FETCH_TIMEOUT_MS`          | Бюджет одной попытки `fetchRetry`/`fetchWithTimeout`, мс (по умолчанию `60000`; `0` — без таймаута) |
 | `FETCH_TIMEOUT_QUICK_MS`    | Бюджет `FETCH_TIMEOUTS.quick` — токены, мс (по умолчанию `10000`)               |
@@ -988,6 +1015,10 @@ APP_NAME=MyApp
 CONFIG_DIR=../config
 FETCH_TIMEOUT_MS=60000
 
+# Группа по умолчанию для задач об ошибках. ID свой у каждого портала —
+# посмотреть в адресе группы на портале. Не задана — задачи создаются без группы
+B24_ERROR_TASK_GROUP_ID=196
+
 # Именованные бюджеты пакета — задавать только при необходимости, иначе действуют дефолты
 # FETCH_TIMEOUT_QUICK_MS=10000
 # FETCH_TIMEOUT_API_MS=20000
@@ -999,6 +1030,79 @@ 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` — прогон юнит-тестов из `tests/` через встроенный `node --test`. Дополнительных зависимостей не нужно: `.ts` запускаются на нативном стирании типов Node, поэтому прогону нужен Node 22.6+ (`engines: ">=20.3.0"` — это требование к потребителю пакета, а не к разработке). Сети тесты не касаются, в тарбол папка не попадает.

package/bitrix24/b24/facade.ts

@@ -31,6 +31,11 @@ export const FETCH_LIST_MAX_PAGES = 20000;
  * Функция превращает такой ответ в понятную ошибку вместо падения на undefined.
  * Также отсекает случай, когда запрос успешен, но result пустой (null/undefined).
  *
+ * Дефолт дженерика — `any`, и это осознанно: потребители пишут
+ * `getResultData(response, "tasks.task.add").task.id` без параметра типа.
+ * Замена дефолта на `unknown` сломала бы каждое такое обращение, ничего не дав
+ * взамен: узкий тип задаётся на месте вызова — `getResultData<Deal>(response, method)`.
+ *
  * @param response — результат $b24.callMethod()
  * @param methodName — имя метода B24, попадёт в текст ошибки
  */
@@ -82,8 +87,16 @@ export function readV2Envelope(response: AjaxResult, method: string): V2Envelope
  * идемпотентности (`getRetryBlockReason`) видит те же аргументы, что и раньше,
  * — retry оборачивает фасад снаружи, а преобразование в объект опций
  * происходит уже внутри.
+ *
+ * `any` в сигнатурах ниже (`callMethod<T = any>`, `params?: any`, `AsyncGenerator<any[]>`,
+ * `Array<any>`, а также `call.make<any>` внутри `fetchListMethod` — тип страницы
+ * задаёт вызывающий) оставлен НАМЕРЕННО и снятию по T-53 не подлежит. Это дефолты дженериков
+ * публичной поверхности, дословно повторяющие `AbstractB24`: на них стоит код потребителей
+ * (`for await (const chunk of $b24.fetchListMethod(...)) chunk.forEach((x) => x.ID)`).
+ * `unknown` в дефолте уронил бы каждое такое место, не дав взамен ничего — узкий тип
+ * задаётся параметром типа на месте вызова (`callMethod<Deal>(...)`).
  */
-export function createFacade(target: B24OAuth): Record<string, (...args: any[]) => any> {
+export function createFacade(target: B24OAuth): FacadeMethods {
     // Геттер actions при каждом обращении проверяет инициализацию экземпляра —
     // читаем его в момент вызова, а не один раз при создании фасада
     const v2 = () => target.actions.v2;

package/bitrix24/b24/proxy.ts

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

package/bitrix24/b24/retry.ts

@@ -2,6 +2,18 @@ import { AjaxError, RefreshTokenError, SdkError } from "@bitrix24/b24jssdk";
 import { logs } from "../../logs/logs.ts";
 import { isNetworkError, isPreConnectionError } from "../../utils/fetchRetry.ts";
 
+// ==================== Типы ====================
+
+/**
+ * Любая асинхронная функция.
+ *
+ * `never[]` в параметрах делает тип надмножеством всех сигнатур: `never`
+ * присваивается чему угодно, поэтому под ограничение подходит и `callMethod`,
+ * и `callBatch`. Возврат `Promise<unknown>` отсекает `fetchListMethod` —
+ * это async-генератор, и оборачивать его retry-обёрткой нельзя (`for await` ломается).
+ */
+export type AsyncFn = (...args: never[]) => Promise<unknown>;
+
 // ==================== Константы ====================
 
 /** Количество попыток при сетевых ошибках */
@@ -302,7 +314,7 @@ function joinReasons(creating: string[], reserving: string[]): string | null {
  * не удалось, вызов считается создающим. Ошибиться в сторону лишней осторожности
  * дешевле — потребитель получит ошибку вместо тихого дубликата.
  */
-export function getRetryBlockReason(sdkMethod: string, args: any[]): string | null {
+export function getRetryBlockReason(sdkMethod: string, args: readonly unknown[]): string | null {
     const first = args[0];
 
     // callMethod(method, params) и callListMethod(method, params, ...)
@@ -390,8 +402,9 @@ export async function runWithRetry<T>(fn: () => Promise<T>, label: string, block
             const proven = isPreConnectionError(error);
 
             // Окончательные отказы логируем на error: собственные модули пакета
-            // (errorB24, Event, Smsgold) ошибку только возвращают вызывающему коду,
-            // но не пишут в лог — без этих строк сбой $b24 не виден нигде
+            // (Event, Smsgold) ошибку только возвращают вызывающему коду,
+            // но не пишут в лог — без этих строк сбой $b24 не виден нигде.
+            // errorB24 пишет сама только несетевой отказ, сетевой ждёт от нас
 
             // Ветка обмена токена стоит до проверки исчерпания попыток: иначе она
             // сработала бы только на пятой попытке, ради чего всё и затевалось
@@ -430,10 +443,10 @@ export async function runWithRetry<T>(fn: () => Promise<T>, label: string, block
 }
 
 /** Оборачивает async-функцию retry-логикой при сетевых ошибках */
-export function withRetry<T extends (...args: any[]) => Promise<any>>(fn: T, context: any, methodName: string): T {
-    return (async (...args: any[]) => {
+export function withRetry<T extends AsyncFn>(fn: T, context: object, methodName: string): T {
+    return (async (...args: Parameters<T>) => {
         // Состав вызова между попытками не меняется — разбираем один раз
-        const blockReason = getRetryBlockReason(methodName, args);
+        const blockReason = getRetryBlockReason(methodName, args as readonly unknown[]);
         return runWithRetry(() => fn.apply(context, args), `$b24.${methodName}`, blockReason);
     }) as T;
 }

package/bitrix24/b24/tokens.ts

@@ -64,9 +64,10 @@ export function saveTokens(authData: AuthData): SaveResult {
         confAuthB24.set(APP_ENV, { ...authData, domain: cleanDomain(authData.domain) });
         logs.add("Токены Bitrix24 сохранены", "debug");
         return { error: false, message: "Токены сохранены." };
-    } catch (error: any) {
-        logs.add(`Ошибка сохранения токенов: ${error.message}`, "error");
-        return { error: true, message: error.message };
+    } catch (error: unknown) {
+        const message = error instanceof Error ? error.message : String(error);
+        logs.add(`Ошибка сохранения токенов: ${message}`, "error");
+        return { error: true, message };
     }
 }
 
@@ -234,9 +235,10 @@ export async function refreshAndSaveTokens(): Promise<SaveResult> {
     try {
         const authData = await refreshAuthWithMutex();
         return saveTokens(authData);
-    } catch (error: any) {
-        logs.add(`Ошибка обновления токенов: ${error.message}`, "error");
-        return { error: true, message: error.message };
+    } catch (error: unknown) {
+        const message = error instanceof Error ? error.message : String(error);
+        logs.add(`Ошибка обновления токенов: ${message}`, "error");
+        return { error: true, message };
     }
 }
 

package/bitrix24/b24/types.ts

@@ -8,6 +8,26 @@ export interface SaveResult {
     message: string;
 }
 
+/**
+ * Минимальный контракт HTTP-запроса, который читает `saveAuthB24Handler`.
+ *
+ * Своя структура вместо `Request` из `@types/express`: три потребителя
+ * (`b24_rnp`, `b24_ai`, `marketing_vk_ads`) `express` не ставят вовсе и жили
+ * на нашей копии типов, приезжавшей транзитивно. С 4.0.0 `@types/*` в
+ * `devDependencies`, поэтому такой копии больше нет.
+ *
+ * Express подставляет сюда свой `Request` без правок у потребителя:
+ * параметры контравариантны, и `Request.body: any` подходит под `body: unknown`.
+ */
+export interface AuthSaveRequest {
+    body: unknown;
+}
+
+/** Минимальный контракт HTTP-ответа, который пишет `saveAuthB24Handler` */
+export interface AuthSaveResponse {
+    status(code: number): { json(body: unknown): unknown };
+}
+
 /**
  * `B24OAuth` плюс пять методов, которые пакет реализует сам поверх `actions.v2.*`.
  *
@@ -24,6 +44,13 @@ export interface SaveResult {
  * SDK 2.2.0 останется зелёным, то есть пропажа обнаружится только у потребителя.
  * Страховка от «уборки дублей» — `tests/client-type.test.ts`: он читает текст этого
  * файла и падает, если хоть одно объявление отсюда исчезло.
+ *
+ * `any` в сигнатурах оставлен НАМЕРЕННО и снятию по T-53 не подлежит: это дефолты
+ * дженериков публичной поверхности, дословно повторяющие `AbstractB24`. На них стоит
+ * код потребителей — `for await (const chunk of $b24.fetchListMethod(...))
+ * chunk.forEach((x) => x.ID)` и `callBatch([["crm.deal.get", { id }]])`. `unknown`
+ * в дефолте уронил бы каждое такое место, ничего не дав взамен: узкий тип задаётся
+ * параметром типа на месте вызова (`callMethod<Deal>(...)`).
  */
 export interface B24Client extends B24OAuth {
     callMethod<T = any>(method: string, params?: object, start?: number): Promise<AjaxResult<T>>;

package/bitrix24/b24.ts

@@ -1,12 +1,11 @@
 import type { B24OAuth } from "@bitrix24/b24jssdk";
-import type { Request, Response } from "express";
 import { logs } from "../logs/logs.ts";
 
 import { createB24Instance } from "./b24/instance.ts";
 import { wrapB24WithRetry } from "./b24/proxy.ts";
 import { $b24, setB24Instance } from "./b24/state.ts";
 import { refreshAndSaveTokens, resetRefreshMutex, saveTokens, startProactiveRefresh, stopProactiveRefresh } from "./b24/tokens.ts";
-import type { SaveResult } from "./b24/types.ts";
+import type { AuthSaveRequest, AuthSaveResponse, SaveResult } from "./b24/types.ts";
 
 // ==================== Реэкспорт публичного API ====================
 
@@ -62,12 +61,43 @@ export async function reinitializeB24(): Promise<SaveResult> {
     return refreshResult;
 }
 
-/** HTTP-обработчик для сохранения токенов с фронта */
-export async function saveAuthB24Handler(req: Request, res: Response): Promise<void> {
-    try {
-        const { access_token, refresh_token, domain, expires_in, member_id } = req.body;
+/** Непустая строка — единственная форма, пригодная для поля токена */
+function isFilledString(value: unknown): value is string {
+    return typeof value === "string" && value.length > 0;
+}
 
-        if (!access_token || !refresh_token || !domain || !expires_in || !member_id) {
+/**
+ * HTTP-обработчик для сохранения токенов с фронта.
+ *
+ * Типы запроса и ответа — собственные структурные (`AuthSaveRequest`/`AuthSaveResponse`),
+ * а не `Request`/`Response` из `@types/express`: пакет больше не тянет типы express
+ * потребителю. Express подставляет свои объекты сюда без правок на его стороне
+ */
+export async function saveAuthB24Handler(req: AuthSaveRequest, res: AuthSaveResponse): Promise<void> {
+    try {
+        // req.body теперь unknown — разбираем явно, деструктуризация по нему не пройдёт
+        const body = (req.body ?? {}) as Record<string, unknown>;
+        const access_token = body["access_token"];
+        const refresh_token = body["refresh_token"];
+        const domain = body["domain"];
+        const expires_in = body["expires_in"];
+        const member_id = body["member_id"];
+
+        // expires_in участвует и в самом объекте токенов, и в расчёте expires —
+        // приводим один раз в отдельную переменную
+        const expiresIn = Number(expires_in);
+
+        // Проверяем именно тип, а не «истинность» после String(): приведение объекта
+        // дало бы непустую строку "[object Object]", она прошла бы валидацию
+        // в saveTokens и затёрла рабочие токены в authB24.json
+        if (
+            !isFilledString(access_token) ||
+            !isFilledString(refresh_token) ||
+            !isFilledString(domain) ||
+            !isFilledString(member_id) ||
+            !Number.isFinite(expiresIn) ||
+            expiresIn <= 0
+        ) {
             res.status(400).json({ status: "error", message: "Не заполнены обязательные поля." });
             return;
         }
@@ -76,9 +106,9 @@ export async function saveAuthB24Handler(req: Request, res: Response): Promise<v
             access_token,
             refresh_token,
             domain,
-            expires_in,
+            expires_in: expiresIn,
             member_id,
-            expires: Math.floor(Date.now() / 1000) + expires_in,
+            expires: Math.floor(Date.now() / 1000) + expiresIn,
         });
 
         if (result.error) {
@@ -100,9 +130,10 @@ export async function saveAuthB24Handler(req: Request, res: Response): Promise<v
         } else {
             res.status(201).json({ status: "ok", message: "Токены сохранены и применены." });
         }
-    } catch (error: any) {
-        logs.add(`Ошибка в saveAuthB24Handler: ${error.message}`, "error");
-        res.status(500).json({ status: "error", message: error.message });
+    } catch (error: unknown) {
+        const message = error instanceof Error ? error.message : String(error);
+        logs.add(`Ошибка в saveAuthB24Handler: ${message}`, "error");
+        res.status(500).json({ status: "error", message });
     }
 }