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

package/README.md

@@ -191,11 +191,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 +218,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 +242,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 +340,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 +362,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 +524,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)` целиком.
@@ -694,8 +723,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,6 +739,10 @@ const sent = await fetchWithTimeout("https://api.example.com/send", { method: "P
     -   **Особенности:**
         -   SMTP-сервер: `smtp.yandex.ru:465` (SMTPS).
         -   Копия письма автоматически отправляется на адрес отправителя.
+        -   **Адрес получателя проверяется до вызова транспорта.** Пустая строка, строка с пробелом, адрес без собаки или с пустой частью слева либо справа дают `{ 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; без него класс поднимает транспорт Яндекса сам.
         -   Транспорт — `nodemailer` `^9` (диапазон, а не точная версия: иначе патч безопасности нельзя было бы применить на стороне потребителя).
         -   Вложения передаются готовым `Buffer` — файл по `fileUrl` пакет скачивает сам. Поля `path` и `href` намеренно не поддерживаются: nodemailer не должен ходить по URL. Скачивание идёт через `fetchWithTimeout` с бюджетом 60 секунд.
         -   Таймауты SMTP-транспорта переопределены: соединение 15 с, приветствие 10 с, сокет 120 с. Дефолты nodemailer (2 мин / 30 с / 10 мин) слишком щедры — письмо на Яндекс уходит за секунды, а 10 минут молчания сокета блокируют вызывающую очередь.
@@ -880,7 +914,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 +929,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 +969,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,6 +988,12 @@ 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
@@ -944,7 +1001,7 @@ CHATAPP_APP_ID=your-app-id
 
 ## Скрипты
 
--   `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?:\/\//, "");
+}

package/bitrix24/b24/facade.ts

@@ -0,0 +1,358 @@
+import { Result } from "@bitrix24/b24jssdk";
+import type { AjaxResult, TypeCallParams, B24OAuth } from "@bitrix24/b24jssdk";
+import { logs } from "../../logs/logs.ts";
+import { getRetryBlockReason, runWithRetry } from "./retry.ts";
+import type { FacadeMethods, BatchCalls, V2Envelope } from "./types.ts";
+
+// ==================== Константы ====================
+
+/** Потолок числа страниц в callListMethod — страховка от бесконечной пагинации */
+export const LIST_MAX_PAGES = 1000;
+
+/**
+ * Потолок числа страниц keyset-цикла в fetchListMethod — страховка от зацикливания,
+ * а не лимит выборки.
+ *
+ * Своя константа, не общая LIST_MAX_PAGES: у callListMethod потолок продиктован ростом
+ * массива в памяти, он копит весь список. fetchListMethod — генератор, он существует
+ * ровно для выборок, которые в память не помещаются, и потолок в 1000 страниц оборвал бы
+ * законную выборку на крупном портале. Миллион записей недостижим для законного вызова
+ * и достижим для зацикленного за секунды.
+ */
+export const FETCH_LIST_MAX_PAGES = 20000;
+
+// ==================== Разбор ответа SDK ====================
+
+/**
+ * Достаёт result из ответа SDK.
+ *
+ * SDK при «мягких» ошибках (ERROR_ENTITY_NOT_FOUND, BITRIX_REST_V3_EXCEPTION_*)
+ * не бросает исключение, а возвращает AjaxResult с ошибкой.
+ * Функция превращает такой ответ в понятную ошибку вместо падения на undefined.
+ * Также отсекает случай, когда запрос успешен, но result пустой (null/undefined).
+ *
+ * @param response — результат $b24.callMethod()
+ * @param methodName — имя метода B24, попадёт в текст ошибки
+ */
+export function getResultData<T = any>(response: AjaxResult, methodName: string): T {
+    if (!response.isSuccess) {
+        const messages = response.getErrorMessages().join("; ") || "неизвестная ошибка";
+        throw new Error(`${methodName}: Bitrix24 вернул ошибку — ${messages}`);
+    }
+
+    const data = response.getData();
+    if (data?.result == null) {
+        throw new Error(`${methodName}: Bitrix24 вернул пустой ответ`);
+    }
+
+    return data.result as T;
+}
+
+/**
+ * Читает сырой конверт ответа из AjaxResult.
+ *
+ * `getData()` отдаёт замороженную пару `{ result, time }` — полей `next` и `total`
+ * в ней нет намеренно (в restApi:v3 их не существует). С версии 2.2.0 SDK снял
+ * `isMore()`/`getTotal()`/`getNext()` с удаления и объявил их постоянными читателями
+ * конверта restApi:v2, но числового смещения среди них так и нет: `isMore()` отвечает
+ * только «есть ли ещё», а `getNext(http)` сам делает следующий запрос, мимо нашего
+ * прогресса и retry. Поэтому конверт читаем напрямую: `_data` объявлен `protected`,
+ * а не приватным полем класса, поэтому в рантайме доступен.
+ *
+ * Это единственная точка связи с внутренностями SDK. Если она перестанет работать,
+ * она обязана упасть громко: тихо оборванная на первой странице выборка — потеря данных.
+ */
+export function readV2Envelope(response: AjaxResult, method: string): V2Envelope {
+    const envelope = (response as unknown as { _data?: unknown })._data;
+
+    if (!envelope || typeof envelope !== "object") {
+        throw new Error(`${method}: не удалось прочитать конверт ответа Bitrix24 (AjaxResult._data недоступен) — изменился внутренний формат SDK`);
+    }
+
+    return envelope as V2Envelope;
+}
+
+// ==================== Фасад поверх actions.v2.* ====================
+
+/**
+ * Собственные реализации пяти методов, которые SDK 2.x помечает к удалению.
+ * Повторяют `AbstractB24` дословно, включая дефолты и порядок аргументов.
+ *
+ * Позиционные сигнатуры сохранены один в один: на этом держится то, что гейт
+ * идемпотентности (`getRetryBlockReason`) видит те же аргументы, что и раньше,
+ * — retry оборачивает фасад снаружи, а преобразование в объект опций
+ * происходит уже внутри.
+ */
+export function createFacade(target: B24OAuth): Record<string, (...args: any[]) => any> {
+    // Геттер actions при каждом обращении проверяет инициализацию экземпляра —
+    // читаем его в момент вызова, а не один раз при создании фасада
+    const v2 = () => target.actions.v2;
+
+    const callMethod = async <T = any>(method: string, params?: object, start?: number): Promise<AjaxResult<T>> => {
+        const merged: TypeCallParams = { ...params };
+
+        // Явный 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;
+        }
+
+        return v2().call.make<T>({ method, params: merged });
+    };
+
+    /**
+     * Собственный офсетный цикл, а не `actions.v2.callList.make`.
+     *
+     * У `callList.make` keyset-пагинация: он шлёт `start: -1`, навязывает
+     * `order: { ID: 'ASC' }` и добавляет в фильтр `>ID`. Пользовательский `order`
+     * при этом молча игнорируется, а колбэка `progress` там нет вовсе. Делегирование
+     * туда изменило бы поведение постраничных выборок у потребителей.
+     */
+    const callListMethod = async (
+        method: string,
+        params?: object,
+        progress?: null | ((progress: number) => void),
+        customKeyForResult?: string | null
+    ): Promise<Result> => {
+        const result = new Result();
+        const onProgress = typeof progress === "function" ? progress : null;
+
+        onProgress?.(0);
+
+        const list: unknown[] = [];
+        let start = 0;
+        let completed = false;
+
+        for (let page = 1; page <= LIST_MAX_PAGES; page++) {
+            const response = await v2().call.make({ method, params: { ...params, start } });
+
+            // SDK в своём callListMethod этой проверки не делает и падает TypeError
+            // на getData().result, когда портал вернул «мягкую» ошибку
+            if (!response.isSuccess) {
+                throw new Error(`${method}: Bitrix24 вернул ошибку — ${response.getErrorMessages().join("; ")}`);
+            }
+
+            // Читаем конверт целиком: getData() режет ответ до { result, time },
+            // а пагинация держится на next, которого там нет
+            const envelope = readV2Envelope(response, method);
+            const payload = envelope.result;
+            const chunk = customKeyForResult ? (payload as Record<string, unknown> | undefined)?.[customKeyForResult] : payload;
+
+            if (!Array.isArray(chunk)) {
+                throw new Error(`${method}: ответ не является списком`);
+            }
+
+            for (const item of chunk) {
+                list.push(item);
+            }
+
+            // Единственное правило остановки — отсутствие next в конверте. Считать
+            // смещение самим (start += chunk.length) нельзя: портал ставит next = start + 50
+            // независимо от того, сколько строк реально отдал, и на странице, укороченной
+            // правами доступа или фильтром, собственный счётчик отстаёт — перекрытие
+            // читается второй раз и записи дублируются. Метод, который игнорирует start
+            // и отдаёт весь список одной страницей, next не присылает и останавливается здесь же.
+            if (!Number.isInteger(envelope.next)) {
+                completed = true;
+                break;
+            }
+
+            const nextStart = Number(envelope.next);
+
+            // next обязан расти. Портал, вернувший прежнее или меньшее смещение,
+            // иначе гонял бы одну и ту же страницу до потолка, раздувая список
+            if (nextStart <= start) {
+                throw new Error(`${method}: портал вернул непродвигающийся next (${nextStart}) при start ${start} — пагинация зациклилась`);
+            }
+
+            start = nextStart;
+
+            if (onProgress) {
+                const total = Number(envelope.total) || 0;
+                onProgress(total > 0 ? Math.round((100 * list.length) / total) : 100);
+            }
+        }
+
+        // Обрезанный список, отданный как успешный, — худший исход: потребитель
+        // примет неполную выборку за полную. Поэтому бросаем, а не логируем:
+        // addError() на базовом Result бесполезен — getData() отдаёт данные
+        // независимо от наличия ошибок, и существующие потребители её не увидят
+        if (!completed) {
+            throw new Error(`${method}: достигнут потолок в ${LIST_MAX_PAGES} страниц, портал продолжает отдавать next — выборка прервана как неполная`);
+        }
+
+        onProgress?.(100);
+        result.setData(list);
+        return result;
+    };
+
+    /**
+     * Собственный keyset-цикл, а не `actions.v2.fetchList.make`.
+     *
+     * Делегирование не давало повторить страницу: генератор нельзя обернуть
+     * `withRetry` снаружи (обёртка в async-функцию ломает `for await`), поэтому
+     * одиночный сетевой сбой на двенадцатой странице обрывал всю выборку, а уже
+     * прочитанные одиннадцать потребитель либо терял, либо принимал за полную.
+     * Здесь повторяется страница: курсор двигается только после успешной страницы,
+     * поэтому отданные страницы не теряются и не дублируются.
+     *
+     * Форма запроса взята из `fetch-list.mjs`: `start: -1`, навязанный
+     * `order: { <курсор>: "ASC" }`, фильтр `>курсор`. Отступления от SDK — пять,
+     * все намеренные:
+     *   1. остановка только на пустой странице, а не на короткой: страница, укороченная
+     *      правами доступа, у портала штатна, и правило SDK молча обрезало бы выборку;
+     *   2. нечитаемый курсор — бросок, а не предупреждение и тихая остановка:
+     *      после пункта 1 он означает гарантированно неполную выборку;
+     *   3. потолок страниц (`FETCH_LIST_MAX_PAGES`) — у SDK цикл ничем не ограничен;
+     *   4. проверка роста курсора — портал, отбросивший неизвестный ключ фильтра,
+     *      иначе отдавал бы одну и ту же страницу вечно;
+     *   5. пустая строка в `customKeyForResult` трактуется как «ключ не передан».
+     *
+     * Плюс диагностика: ошибки называют метод B24 вместо `TypeError` из недр SDK
+     * и `SdkError` с кодом SDK.
+     *
+     * Ограничение: один и тот же ключ идёт и на чтение курсора, и в `order`/`filter`.
+     * Методы, у которых имя поля в ответе отличается от сортируемого (`tasks.task.list`:
+     * ответ `id`, фильтр `ID`), этим методом не выбираются — для них `callListMethod`
+     * или `actions.v2.fetchList.make` с `cursorIdKey`.
+     */
+    async function* fetchListMethod(method: string, params?: any, idKey?: string, customKeyForResult?: string | null): AsyncGenerator<any[]> {
+        // Отдельного cursorIdKey, как в опциях SDK, у нас нет и не будет: позиционная
+        // сигнатура deprecated-метода его не содержала, а добавление пятого аргумента —
+        // расширение публичного API. У SDK он по умолчанию тоже равен idKey
+        const cursorKey = idKey ?? "ID";
+        const moreKey = `>${cursorKey}`;
+        const source: Record<string, unknown> = { ...(params ?? {}) };
+
+        // Раньше это предупреждение приходило от логгера SDK, теперь пишем сами
+        if ("order" in source && source["order"]) {
+            logs.add(`${method}: параметр order игнорируется — keyset-пагинация сортирует по «${cursorKey}» ASC, сужать выборку следует через filter`, "warn");
+        }
+
+        const { order: _ignoredOrder, filter: userFilter, ...restParams } = source;
+
+        // Ключ курсора в пользовательском фильтре перетирается на каждой странице.
+        // Молчать здесь нельзя: рядом про order предупреждение есть, и асимметрия
+        // читалась бы как «фильтр по курсору пользователю оставлен»
+        if (userFilter && typeof userFilter === "object" && moreKey in (userFilter as Record<string, unknown>)) {
+            logs.add(`${method}: ключ «${moreKey}» в фильтре перетирается курсором пагинации — сузить выборку по нему нельзя`, "warn");
+        }
+
+        // Курсор: значение, от которого идёт следующая страница. Оно же лежит в фильтре
+        // запроса, отдельная переменная нужна для проверки роста
+        let cursor = 0;
+
+        // Фильтр — новый объект: мутировать переданный вызывающим нельзя, SDK этого тоже
+        // не делает, а курсор в этом объекте переписывается на каждой странице
+        const requestParams: Record<string, unknown> & { filter: Record<string, unknown> } = {
+            ...restParams,
+            order: { [cursorKey]: "ASC" },
+            filter: { ...((userFilter as Record<string, unknown> | undefined) ?? {}), [moreKey]: cursor },
+            start: -1,
+        };
+
+        // Список — чтение и дубликатов не создаёт, но гейт пусть стоит: если потребитель
+        // передаст создающий метод, повтор должен блокироваться, как везде.
+        // Состав вызова между страницами не меняется, поэтому считаем один раз
+        const blockReason = getRetryBlockReason("callMethod", [method]);
+
+        // Страховка от вечного цикла: портал, отбросивший неизвестный ключ фильтра,
+        // отдаёт одну и ту же страницу без ошибки и без строки в логе
+        let completed = false;
+
+        for (let page = 1; page <= FETCH_LIST_MAX_PAGES; page++) {
+            // Замыкание читает requestParams в момент вызова: объект один и тот же,
+            // курсор в нём двигается только после успешной страницы — поэтому повтор
+            // попадает ровно в ту же страницу, а не в следующую
+            const response = await runWithRetry(
+                () => v2().call.make<any>({ method, params: requestParams as TypeCallParams }),
+                "$b24.fetchListMethod",
+                blockReason
+            );
+
+            // Формулировка дословно как в callListMethod — один стиль ошибок на оба
+            // списочных метода. Сетевой такая ошибка не считается, повтора не будет:
+            // «мягкая» ошибка портала от повтора не исправится
+            if (!response.isSuccess) {
+                throw new Error(`${method}: Bitrix24 вернул ошибку — ${response.getErrorMessages().join("; ")}`);
+            }
+
+            const data = response.getData();
+            if (!data) {
+                completed = true;
+                break;
+            }
+
+            const payload = data.result;
+            const chunk = customKeyForResult ? (payload as Record<string, unknown> | undefined)?.[customKeyForResult] : payload;
+
+            // Отступление от SDK намеренное и такое же, как в callListMethod:
+            // там на этом месте падал TypeError из недр библиотеки
+            if (!Array.isArray(chunk)) {
+                throw new Error(`${method}: ответ не является списком`);
+            }
+
+            // Единственное правило остановки — пустая страница. SDK на этом месте
+            // останавливается ещё и на короткой (меньше 50 строк), но у портала
+            // страница, укороченная правами доступа, штатна — из-за неё в callListMethod
+            // запрещено считать смещение самим. Цена нового правила — один лишний
+            // запрос на всю выборку, всегда пустой; цена старого — молча отданные
+            // сорок семь записей вместо нескольких тысяч
+            if (chunk.length === 0) {
+                completed = true;
+                break;
+            }
+
+            yield chunk;
+
+            // noUncheckedIndexedAccess: индексация массива даёт T | undefined
+            const lastItem = chunk[chunk.length - 1] as Record<string, unknown> | undefined;
+            const cursorValue = Number.parseInt(String(lastItem?.[cursorKey]), 10);
+
+            // Страница непустая, а продолжить её нечем: остановиться тихо — значит
+            // отдать неполную выборку как полную. Бросаем по тому же правилу,
+            // что и callListMethod
+            if (!Number.isFinite(cursorValue)) {
+                throw new Error(`${method}: в строках ответа нет числового идентификатора по ключу «${cursorKey}» — выборка прервана как неполная`);
+            }
+
+            // Курсор обязан расти. Портал, отбросивший неизвестный ключ фильтра,
+            // иначе гонял бы одну и ту же страницу до потолка
+            if (cursorValue <= cursor) {
+                throw new Error(`${method}: портал вернул непродвигающийся курсор (${cursorValue}) при предыдущем ${cursor} — пагинация зациклилась`);
+            }
+
+            cursor = cursorValue;
+            requestParams.filter[moreKey] = cursor;
+        }
+
+        // Обоснование броска то же, что у потолка в callListMethod: обрезанная выборка,
+        // отданная как полная, — худший исход. Тихая остановка здесь неотличима
+        // от нормального завершения `for await`
+        if (!completed) {
+            throw new Error(`${method}: достигнут потолок в ${FETCH_LIST_MAX_PAGES} страниц, портал продолжает отдавать данные — выборка прервана как неполная`);
+        }
+    }
+
+    const callBatch = async (calls: Array<any> | object, isHaltOnError?: boolean, returnAjaxResult?: boolean): Promise<Result> => {
+        // Дефолты подставляем мы: batch.make своих не имеет, он просто
+        // расширяет переданный объект опций версией API
+        return v2().batch.make({
+            calls: calls as BatchCalls,
+            options: {
+                isHaltOnError: isHaltOnError ?? true,
+                returnAjaxResult: returnAjaxResult ?? false,
+            },
+        });
+    };
+
+    const callBatchByChunk = async (calls: Array<any>, isHaltOnError: boolean): Promise<Result> => {
+        // isHaltOnError передаём как есть, без ?? true — дословно по AbstractB24.
+        // returnAjaxResult не передаём: batchByChunk.make жёстко ставит false сам,
+        // а его тип опций этот ключ не принимает
+        return v2().batchByChunk.make({ calls, options: { isHaltOnError } });
+    };
+
+    return { callMethod, callListMethod, fetchListMethod, callBatch, callBatchByChunk } satisfies FacadeMethods;
+}