@andrey4emk/npm-app-back-b24 3.7.1 → 3.8.1

package/README.md

@@ -15,7 +15,7 @@
     -   [Email](#email)
     -   [Wappi](#wappi)
     -   [Логирование](#логирование)
-    -   [fetchRetry](#fetchretry)
+    -   [fetchRetry и таймауты](#fetchretry-и-таймауты)
 -   [Переменные окружения](#переменные-окружения)
 -   [Скрипты](#скрипты)
 -   [Лицензия](#лицензия)
@@ -32,7 +32,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`, `isNetworkError`, `isPreConnectionError`, `maskUrl` | нет |
+| `@andrey4emk/npm-app-back-b24/fetchRetry`     | `fetchRetry`, `fetchWithTimeout`, `isNetworkError`, `isPreConnectionError`, `isTimeoutError`, `isAbortError`, `maskUrl`, `FETCH_TIMEOUTS`, `DEFAULT_FETCH_TIMEOUT_MS` | нет |
 
 Корневой импорт — barrel: он тянет модуль OAuth, который при загрузке читает `authB24.json` и, если приложение авторизовано, запускает таймер проактивного обновления токена. Проектам, которые ходят в B24 по **входящему вебхуку** или берут из пакета только логгер и `fetchRetry`, удобнее импортировать по подпутям — тогда OAuth-модуль не загружается вообще.
 
@@ -50,6 +50,41 @@ import { fetchRetry, maskUrl } from "@andrey4emk/npm-app-back-b24/fetchRetry";
 
 Практическое следствие: индексация массива внутри пакета всегда сопровождается проверкой на `undefined`. Если в своём проекте эти флаги включены — ошибок из `node_modules/@andrey4emk/npm-app-back-b24` быть не должно.
 
+### Nuxt: сборка в Nitro и импорт `$b24`
+
+Пакет публикуется исходниками на TypeScript, а Nitro по умолчанию не транспилирует ничего из `node_modules`. Двух ловушек здесь достаточно, чтобы потерять полдня, — обе проверены на Nuxt 4.5.
+
+**Сборка.** Одного `nitro.externals.inline` мало: Nuxt жёстко ставит `esbuild.options.exclude = [/node_modules/]`, а `defu` при слиянии конфигов массивы **склеивает**, а не заменяет — переопределить это из `nuxt.config` нельзя. Rollup получает сырой TypeScript и падает на `Expected '{', got 'interface'`. Рабочая комбинация — inline плюс хук `nitro:config`, который присваивает `exclude` заново:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+    nitro: { externals: { inline: ["@andrey4emk/npm-app-back-b24"] } },
+    hooks: {
+        "nitro:config"(nitroConfig) {
+            // ЗАМЕНЯЕТ exclude, а не дополняет — иначе /node_modules/ из дефолта победит
+            nitroConfig.esbuild.options.exclude = [/node_modules\/(?!@andrey4emk\/)/];
+        },
+    },
+});
+```
+
+**Импорт `$b24`.** Это `export let`, а не `const`: `reinitializeB24()` переприсваивает биндинг. Захват значения в момент импорта (`const b24 = $b24` на уровне модуля) навсегда оставит то, что было при загрузке, — как правило `null`, потому что токены к этому моменту ещё не прочитаны. Читать свойство нужно в момент вызова:
+
+```ts
+// server/utils/b24.ts
+import { $b24 } from "@andrey4emk/npm-app-back-b24";
+
+// Геттер, а не const: биндинг $b24 меняется после reinitializeB24()
+export const getB24 = () => $b24;
+
+// Использование
+const b24 = getB24();
+if (b24) {
+    const res = await b24.callMethod("crm.deal.get", { id: 123 });
+}
+```
+
 ## Использование
 
 ```js
@@ -70,8 +105,11 @@ import {
     Wappi,
     logs,
     fetchRetry,
+    fetchWithTimeout,
     isNetworkError,
+    isTimeoutError,
     maskUrl,
+    FETCH_TIMEOUTS,
 } from "@andrey4emk/npm-app-back-b24";
 
 // $b24 — готовый экземпляр B24OAuth (или null, если токены не настроены)
@@ -119,8 +157,11 @@ await wappi.sendMessageWappi("whatsApp", { phone: "+1234567890", message: "Пр
 // Логирование
 logs.add("Сообщение", "info");
 
-// fetch с повторными попытками при сетевых ошибках
+// fetch с повторными попытками при сетевых ошибках (бюджет попытки — 60с)
 const response = await fetchRetry("https://api.example.com/data", { method: "GET" });
+
+// Один запрос без повторов — для неидемпотентных операций
+const sent = await fetchWithTimeout("https://api.example.com/send", { method: "POST" }, FETCH_TIMEOUTS.send);
 ```
 
 ## API
@@ -167,15 +208,21 @@ const response = await fetchRetry("https://api.example.com/data", { method: "GET
 
     **Уровни логов.** Промежуточные попытки пишутся на `warn`, окончательный отказ — на `error`: исчерпание всех попыток и отмена повтора гейтом. Так один упавший вызов даёт одно сообщение в чат B24 вместо пяти, но при этом не теряется совсем. Логировать провал обязан сам Proxy: `errorB24()`, `Event` и `Smsgold` ошибку только возвращают вызывающему коду и в лог не пишут.
 
-    **Создающие вызовы не повторяются Proxy-слоем.** Если в вызове есть метод, создающий сущность или запускающий действие (`*.add`, `*.create`, `*.start`, `*.send`, `*.uploadfile`, `*.import`, `*.register` — в том числе среди команд `callBatch`), retry отменяется, а в лог идёт `повтор отменён`. Причина: при ответе портала «200 без поля `result`» (заглушка прокси или WAF) SDK падает в собственной ветке логирования и отдаёт ошибку со `status: 0`, неотличимую от транспортного сбоя — хотя запрос уже выполнен. Повтор в такой ситуации создавал до пяти дубликатов задачи или файла. Идемпотентные записи (`*.update`, `*.delete`, `*.set`) повторяются как прежде: повторное применение даёт то же состояние.
+    **Создающие вызовы не повторяются Proxy-слоем.** Если в вызове есть метод, создающий сущность или запускающий действие (`*.add`, `*.create`, `*.start`, `*.send`, `*.uploadfile`, `*.import`, `*.register` — в том числе среди команд `callBatch`), retry отменяется, а в лог идёт `повтор отменён`. Причина: транспортная ошибка не говорит, дошёл ли запрос до портала. `NETWORK_ERROR` приходит и когда соединение не состоялось, и когда оно оборвалось после того, как портал уже принял и выполнил запрос — а повтор во втором случае создаёт вторую задачу, второй файл, второй экземпляр бизнес-процесса. Идемпотентные записи (`*.update`, `*.delete`, `*.set`) повторяются как прежде: повторное применение даёт то же состояние.
 
     Команды `callBatch` разбираются в обеих формах — кортеж `["crm.deal.add", {...}]` (основная в SDK 2.x) и объект `{ method, params }`. Если форму команды разобрать не удалось, вызов считается создающим и не повторяется: для защиты от дубликатов безопаснее ошибиться в сторону осторожности.
 
-    Важно: **у SDK есть собственный слой ретраев**, который гейт не отменяет. При настоящем разрыве соединения (`ECONNRESET` и подобные) SDK сходит на портал до 3 раз независимо от нашей защиты. Гейт закрывает конкретный случай — `JSSDK_UNKNOWN_ERROR`, который входит в `BUILT_IN_HARD_ERROR_CODES` и самим SDK не повторяется.
+    Важно: **транспортные сбои SDK не повторяет вообще** — пакет задаёт параметры ограничителя при создании клиента. Иначе гейт был бы дырявым: SDK не различает идемпотентные и создающие вызовы и повторил бы оборванный `crm.deal.add` до трёх раз внутри себя, куда наша защита не дотягивается. Измерено: без этих параметров обрыв соединения, 502 и 504 дают по три выполнения на портале, с ними — по одному.
+
+    Повторы SDK при 429 и 503 сохранены: портал отвечает отказом, не выполнив запрос.
+
+    Отсюда следствие для вашего кода: **не вызывайте `setRestrictionManagerParams()` и не поднимайте `initB24Helper()` / `B24HelperManager` на `$b24`** — они перезаписывают настройки ограничителя целиком, не сливая, и молча вернут повторы SDK вместе с риском дубликатов.
 
     **Обмен refresh-токена** повторяется по более строгому правилу — только если соединение заведомо не состоялось (см. `isPreConnectionError()`). При таймауте или обрыве сервер мог уже провести ротацию; тогда локальный `refresh_token` мёртв независимо от наших действий, и повтор не помогает, а лишь маскирует проблему серией одинаковых отказов. Следующая попытка всё равно будет: проактивный таймер повторяет через 2 минуты при времени жизни токена около часа.
 
-    У самого SDK есть собственный слой ретраев (`maxRetries: 3`), но он работает только при rate limit (HTTP 429, 503) и при распознанных `NETWORK_ERROR` / `REQUEST_TIMEOUT`. Замаскированные транспортные сбои приходят с кодом `JSSDK_UNKNOWN_ERROR`, который входит в `BUILT_IN_HARD_ERROR_CODES` — на таких ошибках SDK делает одну попытку, и повторяет только Proxy.
+    У самого SDK есть собственный слой ретраев (`maxRetries: 3`), но на транспортных ошибках он выключен — там одна попытка, повторяет только Proxy. При 429, 503 и неизвестных 5xx SDK повторяет по-прежнему.
+
+    Отдельно про ответы шлюза перед порталом. **502** повторяет наш слой: шлюз не смог получить ответ от upstream, запрос почти наверняка не выполнялся. **504** не повторяет никто — это «портал взял запрос и считает прямо сейчас»; повтор создающего вызова дал бы дубликат, а читающего — ничего, кроме нагрузки на портал в худший для него момент.
 
     **Диагностика SDK.** Начиная с 3.7.0 собственные сообщения SDK от уровня `WARNING` и выше попадают в лог пакета с префиксом `SDK B24:` вместе с контекстом (`requestId`, `method`, `status`, код ошибки) — например предупреждение `fetchList` про игнорируемый `order` или про остановку пагинации, когда `idKey` не совпал с полем ответа. Порог нужен: на уровне `info` SDK пишет две строки на каждый запрос. Ошибки SDK приходят как `warn`, а не `error` — это диагностика отдельной неуспешной попытки, а окончательный провал вызова один раз пишет retry-слой.
 
@@ -427,6 +474,8 @@ const response = await fetchRetry("https://api.example.com/data", { method: "GET
                     processId: "12345",
                     message: [
                         {
+                            messageId: "7cf5d29bee90cc37382a9fff07fc2a43", // MESSAGE_ID записи очереди — ключ для clear()
+                            eventId: "4821",                             // ID записи очереди, информационное; в clear() не передавать
                             connectorId: "...",
                             lineId: "...",
                             chatId: "...",
@@ -454,6 +503,8 @@ const response = await fetchRetry("https://api.example.com/data", { method: "GET
             -   Автоматически фильтрует и удаляет события от системного пользователя (`user_id: '138'`).
             -   Для коннекторных событий конвертирует файлы в формат с типами `image`, `video`, `document`.
             -   Если событий нет, возвращает `data` с пустыми массивами.
+            -   **Гранулярность очистки — запись очереди, а не сообщение.** Одна запись коннектора (один `MESSAGE_ID`) может нести несколько сообщений, и они приходят отдельными элементами `message` с одинаковым `messageId`. Очистка по этому ключу удаляет запись целиком: если из двух сообщений одной записи ушло одно, `clear()` заберёт и неотправленное. Строить поэлементную очистку с точностью до сообщения на `messageId` нельзя. Для дедупликации отдельных сообщений он не годится по той же причине — у сообщений одной записи он общий, для этого есть `im.id`. Обратная сторона: запись, из которой не разобрано ни одного сообщения, в `data.message` не попадёт вовсе, и очистка по собранным `messageId` её не заберёт. Безопасный режим — `clear(processId)` целиком.
+            -   Типы `ConnectorMessage`, `ConnectorEvents` и `EntityEvents` экспортируются из пакета.
 
         ```js
         const { error, data } = await event.get("ONCRMDYNAMICITEMUPDATE_149");
@@ -467,7 +518,7 @@ const response = await fetchRetry("https://api.example.com/data", { method: "GET
         -   **Параметры:**
 
             -   `processId` (string) — ID процесса (получен из `get()`).
-            -   `messageId` (string|string[]) — опциональный ID или массив ID сообщений для очистки.
+            -   `messageId` (string|string[]) — опциональный `MESSAGE_ID` или массив `MESSAGE_ID` записей очереди для очистки. Без него очищается весь пакет `processId`. Пустой массив означает «очищать нечего»: вызов до API не доходит и возвращает `error: false` (раньше уезжало `message_id: []`). «Мягкая» ошибка портала, например `ERROR_ENTITY_NOT_FOUND` на протухшем `processId`, возвращается как `error: true`.
 
         -   **Возвращает:** промис с объектом `{ error, message, data }`.
 
@@ -501,6 +552,8 @@ const response = await fetchRetry("https://api.example.com/data", { method: "GET
 
     Конструктор сразу разрешает тип мессенджера для `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) — решение о повторе принимает человек. Раньше зависание долетало до вызывающего кода исключением через пять минут; теперь оно возвращается объектом через тридцать секунд, поэтому запись в лог обязательна: без неё отказ стал бы тише, чем был.
+
     Отказ локальный: пустой `whatsApp` не мешает `telegram`. Но конфиг всё равно нужен для **обоих** мессенджеров, даже если проект пользуется одним — иначе второй канал молча перестанет работать, и узнать об этом можно будет только по `res.error` в логе.
 
     **Методы:**
@@ -564,6 +617,7 @@ const response = await fetchRetry("https://api.example.com/data", { method: "GET
             -   `messengerType` (string) — `"whatsApp"` или `"telegram"`.
             -   `phone` (string) — номер телефона.
         -   **Возвращает:** промис с объектом `{ error, message, data }`, где `data.check` — результат проверки.
+        -   **Особенности:** если API ответил `success: true`, но без объекта `data`, метод возвращает `{ error: true, message: "Ответ ChatApp без поля data ...", data }` с сырым ответом. Раньше в этом случае наружу летел `TypeError` — метод не обёрнут в `try/catch`. Подставлять `check: undefined` было бы хуже: вызывающий принял бы непонятный ответ за «телефон не найден».
 
 ### Smsgold
 
@@ -574,10 +628,13 @@ const response = await fetchRetry("https://api.example.com/data", { method: "GET
 
     const smsClient = new Smsgold(
         { user: "smsgold_login", pass: "smsgold_password" },
-        b24Instance // опционально — экземпляр B24OAuth для загрузки файлов на диск
+        b24Instance, // опционально — экземпляр B24OAuth для загрузки файлов на диск
+        123456 // опционально — ID папки на диске B24 для вложений, по умолчанию 2792881
     );
     ```
 
+    Третий параметр — папка, куда кладётся файл из `fileUrl` перед отправкой SMS. Дефолт `2792881` — папка «contract_company» портала `repacheb.bitrix24.ru`; на другом портале такого ID нет, и его нужно передать своим. Параметр нужен только при отправке файлов.
+
     **Методы:**
 
     -   **`sendSms(messageData)`** — отправить SMS.
@@ -588,7 +645,7 @@ const response = await fetchRetry("https://api.example.com/data", { method: "GET
                 -   `message` (string) — текст сообщения.
                 -   `fileUrl` (string) — опционально, ссылка на файл (будет загружен на диск Bitrix24 и публичная ссылка добавлена в SMS).
                 -   `fileName` (string) — опционально, имя файла.
-        -   **Возвращает:** промис с объектом `{ error, message, result }`.
+        -   **Возвращает:** промис с объектом `{ error, message, result }`, а при таймауте — ещё и `unknownDelivery: true`.
 
         ```js
         const result = await smsClient.sendSms({
@@ -600,6 +657,19 @@ const response = await fetchRetry("https://api.example.com/data", { method: "GET
         }
         ```
 
+    -   **Таймаут и неизвестный статус доставки.** Отправка идёт без повторов с бюджетом 30 секунд. Если SMSGold не ответил, запрос уже ушёл — сообщение **могло быть доставлено**, и повторять отправку нельзя. Такой результат отличается от обычной ошибки: `unknownDelivery: true` и текст «SMSGold не ответил за 30с — статус отправки неизвестен». Дополнительно пакет пишет строку уровня `error` (она уходит в чат B24), потому что решение о повторе должен принимать человек, а не код. Это единственное место, где `Smsgold` пишет в лог сам.
+
+        ```js
+        const result = await smsClient.sendSms({ phone, message });
+        if (result.unknownDelivery) {
+            // Не отправлять повторно: возможен дубль у клиента. Ставим задачу на ручную проверку
+        } else if (result.error) {
+            // Обычная ошибка — отправка не состоялась, повтор безопасен
+        }
+        ```
+
+    -   **Скачивание файла** по `fileUrl` идёт через `fetchRetry` с 3 попытками и бюджетом 60 секунд на попытку (раньше было 5 попыток без таймаута): пять попыток по минуте задерживали бы саму отправку SMS до пяти минут.
+
 ### Email
 
 -   **`Email`** — класс для отправки email через SMTP Яндекса. Экземпляр нужно создать самостоятельно.
@@ -640,12 +710,15 @@ const response = await fetchRetry("https://api.example.com/data", { method: "GET
         -   SMTP-сервер: `smtp.yandex.ru:465` (SMTPS).
         -   Копия письма автоматически отправляется на адрес отправителя.
         -   Транспорт — `nodemailer` `^9` (диапазон, а не точная версия: иначе патч безопасности нельзя было бы применить на стороне потребителя).
-        -   Вложения передаются готовым `Buffer` — файл по `fileUrl` пакет скачивает сам. Поля `path` и `href` намеренно не поддерживаются: nodemailer не должен ходить по URL.
+        -   Вложения передаются готовым `Buffer` — файл по `fileUrl` пакет скачивает сам. Поля `path` и `href` намеренно не поддерживаются: nodemailer не должен ходить по URL. Скачивание идёт через `fetchWithTimeout` с бюджетом 60 секунд.
+        -   Таймауты SMTP-транспорта переопределены: соединение 15 с, приветствие 10 с, сокет 120 с. Дефолты nodemailer (2 мин / 30 с / 10 мин) слишком щедры — письмо на Яндекс уходит за секунды, а 10 минут молчания сокета блокируют вызывающую очередь.
 
 ### Wappi
 
 -   **`Wappi`** — класс для отправки сообщений через Wappi API (WhatsApp, Telegram, Max). Экземпляр нужно создать самостоятельно.
 
+    **Таймаут отправки — статус неизвестен.** Как и у `ChatApp`: бюджет 20 секунд на проверку номера, 30 на сообщение, 60 на файл. При таймауте отправки метод возвращает `{ error: true, message: "Wappi: таймаут ... — статус неизвестен", data: null }` и пишет строку уровня `error` в чат B24 — сообщение могло уйти, повторять нельзя. Отдельно про Telegram: `phoneCheckWappi` при таймауте проверки контакта **не создаёт контакт**, а возвращает ошибку. Иначе не дождавшись ответа мы бы завели контакт на номер, который мог уже быть в адресной книге, и объявили номер проверенным без проверки.
+
     ```js
     import { Wappi } from "@andrey4emk/npm-app-back-b24";
 
@@ -720,9 +793,9 @@ const response = await fetchRetry("https://api.example.com/data", { method: "GET
     -   Конфигурация хранится в файле `log.json` (через `conf`).
     -   Каждый уровень можно включить/выключить, изменить цвет.
 
-### fetchRetry
+### fetchRetry и таймауты
 
--   **`fetchRetry(url, options?, retries?, delay?)`** — обёртка над `fetch` с повторными попытками при сетевых ошибках. HTTP-ошибки (4xx, 5xx) **не** вызывают повторных попыток — повторяются только сетевые сбои (TypeError, ECONNRESET, ETIMEDOUT и т.д.).
+-   **`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.
 
@@ -769,6 +842,7 @@ const response = await fetchRetry("https://api.example.com/data", { method: "GET
     | `options` | RequestInit                  | `undefined`     | Параметры fetch (метод, заголовки, body и т.д.) |
     | `retries` | number                       | `5`             | Количество попыток                              |
     | `delay`   | number                       | `500`           | Задержка между попытками (мс)                   |
+    | `timeoutMs` | number                     | `60000` (или `FETCH_TIMEOUT_MS`) | Бюджет на одну попытку; `0` — без таймаута |
 
     -   **Возвращает:** `Promise<Response>` — ответ от fetch.
 
@@ -797,6 +871,46 @@ const response = await fetchRetry("https://api.example.com/data", { method: "GET
     );
     ```
 
+#### Таймауты
+
+С версии 3.8.0 каждый запрос пакета имеет бюджет времени: зависшее соединение больше не держится до таймаутов undici (5 минут на попытку, а при медленной «капле» данных — бесконечно).
+
+-   **Бюджет считается на попытку, а не на весь вызов.** Каждой попытке `fetchRetry` выдаётся свой `AbortSignal.timeout(timeoutMs)`. Бюджет покрывает и чтение тела ответа: сигнал живёт до конца запроса, поэтому `res.text()` / `res.arrayBuffer()` могут упасть с `TimeoutError` уже **после** возврата из `fetchRetry`. Для крупных файлов передавайте больший `timeoutMs` или `0`.
+-   **Худший случай по времени** — `retries × (timeoutMs + delay)`. При дефолтах это 5 × (60 000 + 500) ≈ 5 минут.
+-   **Свой `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 — непригодное отбрасывается с записью в лог, а не выключает защиту молча.
+-   **Ограничение при вызове с объектом `Request`:** тело такого запроса читается первой попыткой, и повтор упадёт с `body used already`. Существовало и до таймаутов; для повторяемых запросов передавайте строку URL и `options`.
+
+-   **`fetchWithTimeout(url, options?, timeoutMs?)`** — один запрос с бюджетом времени, **без повторов и без логирования**. Для неидемпотентных операций: отправка сообщения, создание сущности — там, где повтор мог бы продублировать действие, но защита от зависшего соединения нужна. Правила про чужой сигнал те же, что у `fetchRetry`. Внутри пакета через неё идут все отправки ChatApp, Wappi и SMSGold.
+
+    ```js
+    import { fetchWithTimeout, FETCH_TIMEOUTS } from "@andrey4emk/npm-app-back-b24/fetchRetry";
+
+    const res = await fetchWithTimeout(
+        "https://api.example.com/orders",
+        { method: "POST", body: JSON.stringify(order) },
+        FETCH_TIMEOUTS.send // 30 000 мс
+    );
+    ```
+
+-   **`FETCH_TIMEOUTS`** — именованные бюджеты, которыми пакет пользуется сам: `quick` 10 000 (токены), `api` 20 000 (короткое чтение), `send` 30 000 (отправка), `transfer` 60 000 (файлы). **`DEFAULT_FETCH_TIMEOUT_MS`** — действующий дефолт `fetchRetry` (60 000 либо значение `FETCH_TIMEOUT_MS`).
+
+-   **`isTimeoutError(error)` / `isAbortError(error)`** — различают «не дождались» и «отменили». Ошибка таймаута не оборачивается в свою: наружу идёт исходный `DOMException` с `name: "TimeoutError"` (отмена без причины — `"AbortError"`), проверки читают именно `name`.
+
+    ```js
+    import { fetchRetry, isTimeoutError, isAbortError } from "@andrey4emk/npm-app-back-b24/fetchRetry";
+
+    try {
+        await fetchRetry(url, { signal: ac.signal }, 3, 500, 20_000);
+    } catch (error) {
+        if (isTimeoutError(error)) logs.add("не дождались ответа", "warn");
+        else if (isAbortError(error)) logs.add("запрос отменили", "debug");
+        else throw error;
+    }
+    ```
+
 ## Переменные окружения
 
 | Переменная                  | Назначение                                                    |
@@ -807,6 +921,7 @@ const response = await fetchRetry("https://api.example.com/data", { method: "GET
 | `APP_ENV`                   | Определяет окружение, используется как ключ секции авторизации   |
 | `APP_NAME`                  | Название приложения (используется в описании задач)           |
 | `CONFIG_DIR`                | Путь к директории с конфигами (по умолчанию `../config`)      |
+| `FETCH_TIMEOUT_MS`          | Бюджет одной попытки `fetchRetry`/`fetchWithTimeout`, мс (по умолчанию `60000`; `0` — без таймаута) |
 | `CHATAPP_EMAIL`             | Email аккаунта ChatApp                                        |
 | `CHATAPP_PASS`              | Пароль аккаунта ChatApp                                       |
 | `CHATAPP_APP_ID`            | ID приложения в ChatApp                                       |
@@ -820,6 +935,7 @@ APP_B24_CLIENT_ID=xxx
 APP_B24_CLIENT_SECRET=yyy
 APP_NAME=MyApp
 CONFIG_DIR=../config
+FETCH_TIMEOUT_MS=60000
 
 CHATAPP_EMAIL=your-email@example.com
 CHATAPP_PASS=your-password

package/bitrix24/b24.ts

@@ -11,6 +11,7 @@ import type {
     Handler,
     LogRecord,
     Formatter,
+    RestrictionParams,
 } from "@bitrix24/b24jssdk";
 import { logs } from "../logs/logs.ts";
 import { isNetworkError, isPreConnectionError } from "../utils/fetchRetry.ts";
@@ -114,14 +115,57 @@ const NETWORK_ERROR_CODES = new Set(["NETWORK_ERROR", "REQUEST_TIMEOUT", "ERR_NE
  * REST-методы B24, повтор которых создаёт дубликат сущности или запускает
  * повторное действие: add, create, start, send, uploadfile, import, register.
  *
- * SDK 2.x при ответе портала «200 без поля result» (заглушка прокси или WAF) падает
- * внутри собственной логирующей ветки и отдаёт ошибку со status 0 — неотличимую от
- * транспортного сбоя. Запрос при этом уже выполнен, поэтому retry создаст вторую
- * задачу, второй файл, второй экземпляр бизнес-процесса. Идемпотентные записи
- * (update, delete, set) повторять безопасно: повторное применение даёт то же состояние.
+ * Транспортная ошибка не говорит, дошёл ли запрос до портала: NETWORK_ERROR приходит
+ * и когда соединение не состоялось, и когда оно оборвалось после того, как портал уже
+ * принял и выполнил запрос. Во втором случае retry создаст вторую задачу, второй файл,
+ * второй экземпляр бизнес-процесса. Идемпотентные записи (update, delete, set) повторять
+ * безопасно: повторное применение даёт то же состояние.
+ *
+ * По той же причине у SDK отключены собственные повторы транспортных сбоев
+ * (SDK_RESTRICTION_PARAMS) — он этой разницы не знает вовсе.
  */
 const NON_IDEMPOTENT_METHOD_RE = /\.(add|create|start|send|uploadfile|import|register)(\.json)?(\?|$)/i;
 
+/**
+ * Параметры ограничителя SDK. Передаются третьим аргументом конструктора B24OAuth
+ * и сливаются там с дефолтами `ParamsFactory.getDefault()`.
+ *
+ * Единый инвариант: **транспортные сбои SDK не повторяет вообще, повторяет только
+ * наш слой**, где работает гейт NON_IDEMPOTENT_METHOD_RE. У SDK нет понятия
+ * «создающий вызов»: оборванный crm.deal.add он повторил бы трижды и создал три сделки.
+ *
+ * Одного `retryOnNetworkError: false` для этого мало. Он добавляет в жёсткий список
+ * ровно два кода — NETWORK_ERROR и REQUEST_TIMEOUT, — а SDK конвертирует в них только
+ * `ERR_NETWORK` и `ECONNABORTED`. Остальные транспортные ошибки Node доезжают до
+ * лимитера под своим кодом (`ECONNRESET` при обрыве сокета, `ERR_BAD_RESPONSE` при
+ * 502/504 от шлюза), не находятся ни в жёстком, ни в мягком списке и потому считаются
+ * временными — то есть повторяются с backoff. Замерено на локальном сервере, рвущем
+ * соединение после приёма запроса: без hardErrorCodes портал выполняет crm.deal.add
+ * три раза, с ними — один. На SDK 2.0.0 был один: там транспорт маскировался в
+ * JSSDK_UNKNOWN_ERROR, а тот во встроенном жёстком списке.
+ *
+ * `ERR_NETWORK` и `ECONNABORTED` в списке не нужны: до лимитера они не доживают.
+ *
+ * Плата за список: `ECONNREFUSED`/`ENOTFOUND`/`EAI_AGAIN` доказывают, что запрос не ушёл,
+ * и SDK мог бы повторить их безопасно даже для создающих вызовов. Отказываемся сознательно —
+ * ровно так вёл себя 2.0.0, а один понятный инвариант дороже трёх сэкономленных попыток.
+ */
+const SDK_RESTRICTION_PARAMS = {
+    retryOnNetworkError: false,
+    hardErrorCodes: [
+        "ECONNRESET",
+        "ECONNREFUSED",
+        "ENOTFOUND",
+        "ETIMEDOUT",
+        "EHOSTUNREACH",
+        "ENETUNREACH",
+        "EAI_AGAIN",
+        "EPIPE",
+        "EPROTO",
+        "ERR_BAD_RESPONSE",
+    ],
+} as const satisfies RestrictionParams;
+
 const confAuthB24 = new Conf({
     cwd: path.resolve(CONFIG_DIR),
     configName: "authB24",
@@ -173,10 +217,12 @@ interface V2Envelope {
  * Читает сырой конверт ответа из AjaxResult.
  *
  * `getData()` отдаёт замороженную пару `{ result, time }` — полей `next` и `total`
- * в ней нет намеренно (в restApi:v3 их не существует), а `isMore()`/`getTotal()`/`getNext()`
- * помечены `@removed 2.0.0` и читают тот же приватный конверт. Единственный способ узнать
- * смещение следующей страницы, не опираясь на удаляемое API, — прочитать конверт напрямую:
- * `_data` объявлен `protected`, а не приватным полем класса, поэтому в рантайме доступен.
+ * в ней нет намеренно (в restApi:v3 их не существует). С версии 2.2.0 SDK снял
+ * `isMore()`/`getTotal()`/`getNext()` с удаления и объявил их постоянными читателями
+ * конверта restApi:v2, но числового смещения среди них так и нет: `isMore()` отвечает
+ * только «есть ли ещё», а `getNext(http)` сам делает следующий запрос, мимо нашего
+ * прогресса и retry. Поэтому конверт читаем напрямую: `_data` объявлен `protected`,
+ * а не приватным полем класса, поэтому в рантайме доступен.
  *
  * Это единственная точка связи с внутренностями SDK. Если она перестанет работать,
  * она обязана упасть громко: тихо оборванная на первой странице выборка — потеря данных.
@@ -238,11 +284,22 @@ class B24SdkLogHandler implements Handler {
             // нормальный путь через getResultData(): проверка существования в цикле
             // дала бы строку на итерацию. Такие сообщения — уровень debug.
             //
+            // 408 и 429 из правила исключены на будущее, сегодня эта ветка недостижима:
+            // status попадает в контекст записи уровня WARNING и выше ровно в одном месте
+            // SDK — #logNonRetryableClientError, а он вызывается из-под условия, которое
+            // 408 и 429 уже исключает. Сообщения лимитера про 429/503 идут другим путём,
+            // без status в контексте, и маппятся в warn независимо от этой строки.
+            // Условие оставлено потому, что фейлит в безопасную сторону: начни SDK класть
+            // status в такие записи — таймаут и упор в лимит будут видны, а не утонут в debug.
+            //
             // Остальное: уровень ERROR у SDK — это диагностика отдельной неуспешной
-            // попытки, а таких попыток на один вызов до пятнадцати (3 внутри SDK × 5 наших).
+            // попытки. На транспортном сбое их пять — по числу наших попыток, повторы SDK
+            // выключены (см. SDK_RESTRICTION_PARAMS). На 429/503 и неизвестных 5xx SDK
+            // повторяет по-прежнему, там до пятнадцати: три внутри каждой из наших пяти.
             // Уровень error пакета уходит в чат B24, поэтому маппим SDK-ERROR в warn:
-            // окончательный провал вызова логирует retry-слой, и он туда попадёт ровно один раз.
-            const level = status >= 400 && status < 500 ? "debug" : record.level >= LogLevel.CRITICAL ? "error" : "warn";
+            // окончательный провал вызова логирует retry-слой, ровно один раз.
+            const isQuietClientError = status >= 400 && status < 500 && status !== 408 && status !== 429;
+            const level = isQuietClientError ? "debug" : record.level >= LogLevel.CRITICAL ? "error" : "warn";
 
             // Контекст SDK (requestId, method, code, wait, status) уже прогнан
             // через redactSensitiveParams — токены в него не попадают
@@ -303,7 +360,13 @@ function createB24Instance(): B24OAuth | null {
 
     const secret: B24OAuthSecret = { clientId: CLIENT_ID, clientSecret: CLIENT_SECRET };
 
-    const b24 = new B24OAuth(authParams, secret);
+    // Параметры ограничителя задаём третьим аргументом конструктора: SDK сливает их
+    // с дефолтами (`{ ...ParamsFactory.getDefault(), ...restrictionParams }` в AbstractHttp)
+    // и передаёт обоим http-клиентам, v2 и v3, ещё до того как экземпляр можно использовать.
+    // Через setRestrictionManagerParams() было бы окно между созданием и настройкой,
+    // а результат вызова к тому же непроверяем: он завершается Promise.allSettled и
+    // не отклоняется никогда.
+    const b24 = new B24OAuth(authParams, secret, { restrictionParams: SDK_RESTRICTION_PARAMS });
 
     // Диагностика SDK от WARNING и выше уходит в logs пакета: предупреждения
     // callList/fetchList про игнорируемый order и остановку пагинации, сообщения лимитера.
@@ -491,9 +554,12 @@ export function stopProactiveRefresh(): void {
 /**
  * Проверяет, является ли ошибка из SDK сетевой.
  *
- * SDK 2.x маскирует транспортные сбои: в логирующей ветке падает собственный
- * TypeError, и наружу приходит AjaxError с кодом JSSDK_UNKNOWN_ERROR и status 0.
- * Поэтому проверяем и код, и originalError, и status.
+ * С версии 2.2.0 SDK отдаёт транспортный сбой честным кодом: NETWORK_ERROR (status 0)
+ * или REQUEST_TIMEOUT (status 408). До 2.2.0 он их маскировал — в логирующей ветке падал
+ * собственный TypeError, и наружу приходил AjaxError с кодом JSSDK_UNKNOWN_ERROR и status 0.
+ * Проверку по status 0 оставляем: она ловит всё, что SDK отдаёт без внятного кода.
+ * Сюда же попадает провал обновления токена внутри callMethod: SDK перезаворачивает
+ * SdkError в AjaxError с кодом JSSDK_UNKNOWN_ERROR и status 0, и исходный код теряется.
  * RefreshTokenError приходит как SdkError с кодом вроде ENOTFOUND и без originalError.
  */
 function isB24NetworkError(error: unknown): boolean {
@@ -511,6 +577,18 @@ function isB24NetworkError(error: unknown): boolean {
         if (originalError && isNetworkError(originalError)) return true;
         if (originalCode && NETWORK_ERROR_CODES.has(originalCode)) return true;
         if (status === 0) return true;
+
+        // 502 Bad Gateway: шлюз перед порталом не смог получить ответ от upstream —
+        // запрос почти наверняка не выполнялся, повтор осмыслен. Мы держим этот код
+        // в SDK_RESTRICTION_PARAMS.hardErrorCodes, чтобы SDK его не повторял, но
+        // повторить его должен наш слой: там создающие вызовы отсекает гейт.
+        //
+        // 504 сюда намеренно не входит, хотя приходит тем же кодом ERR_BAD_RESPONSE:
+        // это «портал взял запрос и считает прямо сейчас, шлюз устал ждать». Повтор
+        // создающего вызова дал бы дубликат, а читающего — ничего: за таймаут шлюза
+        // запрос не уложился один раз, не уложится и на второй, зато пять тяжёлых
+        // повторов добавят нагрузки порталу ровно тогда, когда ему и так плохо.
+        if (status === 502) return true;
     }
 
     return isNetworkError(error);
@@ -695,8 +773,10 @@ function createFacade(target: B24OAuth): Record<string, (...args: any[]) => any>
     const callMethod = async <T = any>(method: string, params?: object, start?: number): Promise<AjaxResult<T>> => {
         const merged: TypeCallParams = { ...params };
 
-        // Явный params.start приоритетнее аргумента start — как в AbstractB24.callMethod
-        if (!("start" in merged && Number.isInteger(merged.start)) && Number.isInteger(start)) {
+        // Явный params.start приоритетнее аргумента start — как в AbstractB24.callMethod.
+        // typeof, а не только Number.isInteger: последний ничего не сужает, и при
+        // exactOptionalPropertyTypes у потребителя присваивание number | undefined не проходит
+        if (!("start" in merged && Number.isInteger(merged.start)) && typeof start === "number" && Number.isInteger(start)) {
             merged.start = start;
         }
 
@@ -790,11 +870,14 @@ function createFacade(target: B24OAuth): Record<string, (...args: any[]) => any>
     };
 
     async function* fetchListMethod(method: string, params?: any, idKey?: string, customKeyForResult?: string | null): AsyncGenerator<any[]> {
+        // Ключи со значением undefined не подставляем вовсе: при exactOptionalPropertyTypes
+        // у потребителя явный undefined не подходит опциональному полю опций SDK.
+        // Поведение прежнее — null и undefined одинаково означают «ключ не передан»
         yield* v2().fetchList.make<any>({
             method,
             params,
-            idKey,
-            customKeyForResult: customKeyForResult === null ? undefined : customKeyForResult,
+            ...(idKey === undefined ? {} : { idKey }),
+            ...(customKeyForResult === null || customKeyForResult === undefined ? {} : { customKeyForResult }),
         });
     }