@andrey4emk/npm-app-back-b24 3.6.0 → 3.6.1

package/README.md

@@ -146,11 +146,17 @@ const response = await fetchRetry("https://api.example.com/data", { method: "GET
     | Попыток        | 5                                         |
     | Задержка       | 500 мс (линейно растущая для refreshAuth) |
 
-    Retry срабатывает только при сетевых проблемах (`ECONNRESET`, `ETIMEDOUT`, `ERR_NETWORK` и т.д.). HTTP-ошибки (400, 500) и ошибки бизнес-логики Bitrix24 **не** вызывают повторных попыток. Каждая неудачная попытка логируется через `logs.add()` с уровнем `warn` — в сообщение попадает код ошибки SDK. Уровень `warn` выбран намеренно: `error` уходит в чат B24, и пять попыток одного упавшего вызова превращались в пять сообщений. Финальный провал приходит вызывающему коду исключением и логируется им один раз.
+    Retry срабатывает только при сетевых проблемах (`ECONNRESET`, `ETIMEDOUT`, `ERR_NETWORK` и т.д.). HTTP-ошибки (400, 500) и ошибки бизнес-логики Bitrix24 **не** вызывают повторных попыток.
 
-    **Создающие вызовы не повторяются.** Если в вызове есть метод, создающий сущность (`*.add`, `*.uploadfile`, `*.import`, `*.register` — в том числе внутри `callBatch`), retry отменяется, а в лог идёт `повтор отменён`. Причина: при ответе портала «200 без поля `result`» (заглушка прокси или WAF) SDK падает в собственной ветке логирования и отдаёт ошибку со `status: 0`, неотличимую от транспортного сбоя — хотя запрос уже выполнен. Повтор в такой ситуации создавал до пяти дубликатов задачи или файла. Идемпотентные записи (`*.update`, `*.delete`, `*.set`) повторяются как прежде: повторное применение даёт то же состояние.
+    **Уровни логов.** Промежуточные попытки пишутся на `warn`, окончательный отказ — на `error`: исчерпание всех попыток и отмена повтора гейтом. Так один упавший вызов даёт одно сообщение в чат B24 вместо пяти, но при этом не теряется совсем. Логировать провал обязан сам Proxy: `errorB24()`, `Event` и `Smsgold` ошибку только возвращают вызывающему коду и в лог не пишут.
 
-    **Обмен refresh-токена** повторяется по более строгому правилу — только если соединение заведомо не состоялось (`ENOTFOUND`, `ECONNREFUSED`, `EAI_AGAIN`, `ENETUNREACH`, см. `isPreConnectionError()`). При таймауте или обрыве сервер мог уже провести ротацию, а ответ потеряться: повтор вернул бы `invalid_grant` и оставил в конфиге мёртвый `refresh_token`.
+    **Создающие вызовы не повторяются Proxy-слоем.** Если в вызове есть метод, создающий сущность или запускающий действие (`*.add`, `*.create`, `*.start`, `*.send`, `*.uploadfile`, `*.import`, `*.register` — в том числе среди команд `callBatch`), retry отменяется, а в лог идёт `повтор отменён`. Причина: при ответе портала «200 без поля `result`» (заглушка прокси или WAF) SDK падает в собственной ветке логирования и отдаёт ошибку со `status: 0`, неотличимую от транспортного сбоя — хотя запрос уже выполнен. Повтор в такой ситуации создавал до пяти дубликатов задачи или файла. Идемпотентные записи (`*.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 не повторяется.
+
+    **Обмен 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.
 

package/bitrix24/b24.ts

@@ -44,15 +44,16 @@ const RETRYABLE_METHODS = new Set(["callMethod", "callListMethod", "callBatch"])
 const NETWORK_ERROR_CODES = new Set(["NETWORK_ERROR", "REQUEST_TIMEOUT", "ERR_NETWORK", "ECONNABORTED"]);
 
 /**
- * REST-методы B24, повтор которых создаёт дубликат сущности.
+ * REST-методы B24, повтор которых создаёт дубликат сущности или запускает
+ * повторное действие: add, create, start, send, uploadfile, import, register.
  *
  * SDK 2.x при ответе портала «200 без поля result» (заглушка прокси или WAF) падает
  * внутри собственной логирующей ветки и отдаёт ошибку со status 0 — неотличимую от
  * транспортного сбоя. Запрос при этом уже выполнен, поэтому retry создаст вторую
- * задачу, второй файл и т.д. Идемпотентные записи (update, delete, set) повторять
- * безопасно: повторное применение даёт то же состояние.
+ * задачу, второй файл, второй экземпляр бизнес-процесса. Идемпотентные записи
+ * (update, delete, set) повторять безопасно: повторное применение даёт то же состояние.
  */
-const NON_IDEMPOTENT_METHOD_RE = /\.(add|uploadfile|import|register)(\?|$)/i;
+const NON_IDEMPOTENT_METHOD_RE = /\.(add|create|start|send|uploadfile|import|register)(\.json)?(\?|$)/i;
 
 const confAuthB24 = new Conf({
     cwd: path.resolve(CONFIG_DIR),
@@ -242,10 +243,12 @@ async function refreshAuthWithMutex(): Promise<AuthData> {
                 } catch (error) {
                     lastError = error;
 
-                    // Повторяем только когда соединение заведомо не состоялось: при таймауте
-                    // или обрыве сервер мог уже провести ротацию, ответ потеряться, и повтор
-                    // вернёт invalid_grant — refresh-токен окажется сожжён, потребуется
-                    // ручная переавторизация
+                    // Повторяем только когда соединение заведомо не состоялось.
+                    // При таймауте или обрыве сервер мог уже провести ротацию: тогда
+                    // локальный refresh-токен мёртв независимо от наших действий, и повтор
+                    // не помогает, а лишь маскирует проблему серией одинаковых отказов.
+                    // Следующая попытка всё равно будет — проактивный таймер повторит
+                    // через 2 минуты при времени жизни токена около часа
                     if (!isPreConnectionError(error) || attempt === RETRY_COUNT) throw error;
 
                     const msg = error instanceof Error ? error.message : String(error);
@@ -349,37 +352,74 @@ function isB24NetworkError(error: unknown): boolean {
     return isNetworkError(error);
 }
 
-/** Достаёт имена REST-методов B24 из аргументов вызова SDK */
-function extractB24Methods(sdkMethod: string, args: any[]): string[] {
+/**
+ * Достаёт имя REST-метода из одной команды batch.
+ * Возвращает null, если форма команды не распознана.
+ */
+function extractBatchCommandMethod(cmd: unknown): string | null {
+    // Кортеж ["crm.deal.add", { ... }] — основная форма в SDK 2.x
+    if (Array.isArray(cmd)) {
+        return typeof cmd[0] === "string" ? cmd[0] : null;
+    }
+
+    // Объект { method, params }
+    if (cmd && typeof cmd === "object") {
+        const method = (cmd as { method?: unknown }).method;
+        return typeof method === "string" ? method : null;
+    }
+
+    // Строка "crm.deal.add?ID=1" — в SDK 2.x эта форма уже не поддерживается
+    // (ParseRow бросает JSSDK_INTERACTION_BATCH_ROW_FAIL), разбираем на случай,
+    // если потребитель остался на ней со старой версии
+    if (typeof cmd === "string") {
+        return cmd;
+    }
+
+    return null;
+}
+
+/**
+ * Возвращает причину, по которой вызов запрещено повторять, либо null.
+ *
+ * Для callBatch действует правило fail-closed: если хоть одну команду разобрать
+ * не удалось, вызов считается создающим. Ошибиться в сторону лишней осторожности
+ * дешевле — потребитель получит ошибку вместо тихого дубликата.
+ */
+function getRetryBlockReason(sdkMethod: string, args: any[]): string | null {
     const first = args[0];
 
     // callMethod(method, params) и callListMethod(method, params, ...)
     if (sdkMethod === "callMethod" || sdkMethod === "callListMethod") {
-        return typeof first === "string" ? [first] : [];
+        if (typeof first !== "string") return null;
+        const method = first.trim();
+        return NON_IDEMPOTENT_METHOD_RE.test(method) ? method : null;
     }
 
-    // callBatch(calls, ...) — команды приходят массивом либо объектом-словарём
-    if (sdkMethod === "callBatch") {
-        const commands: unknown[] = Array.isArray(first) ? first : first && typeof first === "object" ? Object.values(first) : [];
+    if (sdkMethod !== "callBatch") return null;
 
-        return commands
-            .map((cmd) => (typeof cmd === "string" ? cmd : (cmd as { method?: unknown })?.method))
-            .filter((method): method is string => typeof method === "string");
+    // callBatch(calls, ...) — команды приходят массивом либо объектом-словарём
+    if (!first || typeof first !== "object") {
+        return "аргументы batch не разобраны";
     }
 
-    return [];
-}
+    const commands: unknown[] = Array.isArray(first) ? first : Object.values(first);
+    const blocking: string[] = [];
 
-/** Возвращает методы вызова, повтор которых создал бы дубликаты сущностей */
-function getNonIdempotentMethods(sdkMethod: string, args: any[]): string[] {
-    return extractB24Methods(sdkMethod, args).filter((method) => NON_IDEMPOTENT_METHOD_RE.test(method));
+    for (const cmd of commands) {
+        const method = extractBatchCommandMethod(cmd);
+
+        if (method === null) return "команда batch не разобрана";
+        if (NON_IDEMPOTENT_METHOD_RE.test(method.trim())) blocking.push(method.trim());
+    }
+
+    return blocking.length > 0 ? blocking.join(", ") : null;
 }
 
 /** Оборачивает async-функцию retry-логикой при сетевых ошибках */
 function withRetry<T extends (...args: any[]) => Promise<any>>(fn: T, context: any, methodName: string): T {
     return (async (...args: any[]) => {
         // Состав вызова между попытками не меняется — разбираем один раз
-        const nonIdempotent = getNonIdempotentMethods(methodName, args);
+        const blockReason = getRetryBlockReason(methodName, args);
         let lastError: unknown;
 
         for (let attempt = 1; attempt <= RETRY_COUNT; attempt++) {
@@ -388,26 +428,32 @@ function withRetry<T extends (...args: any[]) => Promise<any>>(fn: T, context: a
             } catch (error: unknown) {
                 lastError = error;
 
-                if (!isB24NetworkError(error) || attempt === RETRY_COUNT) {
-                    throw error;
-                }
+                // Ошибка не сетевая (бизнес-логика B24, неверные параметры) — отдаём
+                // вызывающему коду как есть, он решает, что с ней делать
+                if (!isB24NetworkError(error)) throw error;
 
                 const msg = error instanceof Error ? error.message : String(error);
                 const code = error instanceof SdkError ? ` [${error.code}]` : "";
 
+                // Окончательные отказы логируем на error: собственные модули пакета
+                // (errorB24, Event, Smsgold) ошибку только возвращают вызывающему коду,
+                // но не пишут в лог — без этих строк сбой $b24 не виден нигде
+
+                if (attempt === RETRY_COUNT) {
+                    logs.add(`$b24.${methodName}${code}: исчерпаны все ${RETRY_COUNT} попыток — ${msg}`, "error");
+                    throw error;
+                }
+
                 // Ошибка со status 0 может означать и «запрос не ушёл», и «запрос выполнен,
                 // а ответ не разобрался»: различить их нельзя, поэтому создающие вызовы
                 // не повторяем — лучше вернуть ошибку, чем создать дубликат
-                if (nonIdempotent.length > 0) {
-                    logs.add(
-                        `$b24.${methodName}${code}: повтор отменён, вызов создаёт сущности (${nonIdempotent.join(", ")}) — ${msg}`,
-                        "warn"
-                    );
+                if (blockReason) {
+                    logs.add(`$b24.${methodName}${code}: повтор отменён, вызов создаёт сущности (${blockReason}) — ${msg}`, "error");
                     throw error;
                 }
 
-                // Уровень warn: промежуточные попытки не должны улетать в чат B24,
-                // финальный провал прилетит вызывающему коду исключением
+                // Промежуточные попытки — warn: в чат B24 уходит только уровень error,
+                // иначе один упавший вызов дал бы пять сообщений
                 logs.add(`$b24.${methodName}${code}: попытка ${attempt}/${RETRY_COUNT} не удалась (${msg}), повтор через ${RETRY_DELAY_MS}мс`, "warn");
 
                 await delay(RETRY_DELAY_MS);
@@ -497,10 +543,17 @@ if (_b24Raw) {
     setupRefreshCallback(_b24Raw);
 
     // Намеренно не ждём результат: импорт модуля не должен блокироваться сетевым
-    // запросом к oauth.bitrix.info. refreshAndSaveTokens() исключений не бросает —
-    // ошибку возвращает в SaveResult и пишет в лог сам
+    // запросом к oauth.bitrix.info. try/finally обязателен — если обновление всё же
+    // бросит (например, битый log.json уронит логгер), без него таймер не стартует
+    // никогда и процесс проживёт без обновления токена до перезапуска
     void (async () => {
-        await refreshAndSaveTokens();
-        startProactiveRefresh();
+        try {
+            await refreshAndSaveTokens();
+        } catch (error: unknown) {
+            const msg = error instanceof Error ? error.message : String(error);
+            logs.add(`Начальное обновление токенов упало: ${msg}`, "error");
+        } finally {
+            startProactiveRefresh();
+        }
     })();
 }

package/bitrix24/eventB24.ts

@@ -62,6 +62,21 @@ interface OfflineEventsResponse {
 
 const SYSTEM_USER_ID = "138"; // ID системного пользователя для фильтрации
 
+// ==================== Утилиты ====================
+
+/**
+ * Приводит MESSAGES из события к массиву.
+ *
+ * B24 отдаёт коллекции то массивом, то словарём с числовыми ключами (так PHP
+ * сериализует разреженный массив), поэтому опираться на одну форму нельзя.
+ * Неизвестная форма даёт пустой массив, а не исключение.
+ */
+function normalizeMessages(messages: unknown): any[] {
+    if (Array.isArray(messages)) return messages;
+    if (messages && typeof messages === "object") return Object.values(messages);
+    return [];
+}
+
 // ==================== Класс ====================
 
 /**
@@ -156,19 +171,26 @@ export class Event {
                     data.processId = arrOfflineEvents.process_id;
                     // Событие может принести несколько сообщений. Раньше бралось только
                     // первое, а остальные терялись безвозвратно — событие после обработки
-                    // удаляется из очереди B24
+                    // удаляется из очереди B24.
+                    //
+                    // Разбор намеренно устойчив к форме и к битым элементам: исключение
+                    // здесь означало бы, что get() вернёт ошибку, потребитель не вызовет
+                    // clear(), и те же события придут следующим опросом — очередь встала бы
+                    // навсегда на одном кривом сообщении
                     data.message = allEvents.flatMap((event) => {
-                        const messages = event.EVENT_DATA.MESSAGES ?? [];
-
-                        return messages.map((messageData: any) => ({
-                            connectorId: event.EVENT_DATA.CONNECTOR,
-                            lineId: event.EVENT_DATA.LINE,
-                            chatId: messageData.chat.id,
-                            text: messageData.message.text || null,
-                            file: this.convertB24FilesToTelegramFormat(messageData.message.files),
-                            attachments: messageData.message.attachments || null,
-                            im: messageData.im || null,
-                        }));
+                        const eventData = event.EVENT_DATA ?? {};
+
+                        return normalizeMessages(eventData.MESSAGES)
+                            .filter((messageData) => messageData?.chat && messageData?.message)
+                            .map((messageData) => ({
+                                connectorId: eventData.CONNECTOR,
+                                lineId: eventData.LINE,
+                                chatId: messageData.chat.id,
+                                text: messageData.message.text || null,
+                                file: this.convertB24FilesToTelegramFormat(messageData.message.files),
+                                attachments: messageData.message.attachments || null,
+                                im: messageData.im || null,
+                            }));
                     });
                 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@andrey4emk/npm-app-back-b24",
-    "version": "3.6.0",
+    "version": "3.6.1",
     "description": "Bitrix24 OAuth helpers for Node.js projects",
     "main": "index.ts",
     "type": "module",

package/utils/fetchRetry.ts

@@ -36,7 +36,7 @@ export function isNetworkError(error: unknown): boolean {
  * Коды, доказывающие, что соединение не было установлено: DNS не разрешился либо
  * хост отверг подключение. Запрос при таких ошибках гарантированно не дошёл до сервера.
  */
-const PRE_CONNECTION_ERROR_CODES = ["ENOTFOUND", "EAI_AGAIN", "ECONNREFUSED", "ENETUNREACH"];
+const PRE_CONNECTION_ERROR_CODES = ["ENOTFOUND", "EAI_AGAIN", "EAI_NODATA", "ECONNREFUSED", "ENETUNREACH", "EHOSTUNREACH", "ENETDOWN"];
 
 /**
  * Проверяет, что соединение не состоялось — запрос точно не был выполнен сервером.
@@ -79,8 +79,9 @@ export function maskUrl(url: string | URL | Request): string {
         raw
             // Секрет входящего вебхука: /rest/<id пользователя>/<секрет>/
             .replace(/(\/rest\/\d+\/)[^/?#]+/gi, "$1***")
-            // Токены в query-параметрах
-            .replace(/([?&](?:auth|access_token|refresh_token|token)=)[^&#]+/gi, "$1***")
+            // Токены и подписи в query-параметрах. signature и sessid нужны отдельно:
+            // ссылка на файл B24-диска несёт секрет именно в signature
+            .replace(/([?&](?:auth|access_token|refresh_token|token|signature|sessid)=)[^&#]+/gi, "$1***")
     );
 }