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

package/README.md

@@ -26,6 +26,24 @@
 npm install @andrey4emk/npm-app-back-b24
 ```
 
+### Точки входа
+
+| Импорт                                        | Что отдаёт                    | Поднимает OAuth-модуль |
+| --------------------------------------------- | ----------------------------- | ---------------------- |
+| `@andrey4emk/npm-app-back-b24`                | всё                           | да                     |
+| `@andrey4emk/npm-app-back-b24/logs`           | `logs`                        | нет                    |
+| `@andrey4emk/npm-app-back-b24/fetchRetry`     | `fetchRetry`, `isNetworkError`, `isPreConnectionError`, `maskUrl` | нет |
+
+Корневой импорт — barrel: он тянет модуль OAuth, который при загрузке читает `authB24.json` и, если приложение авторизовано, запускает таймер проактивного обновления токена. Проектам, которые ходят в B24 по **входящему вебхуку** или берут из пакета только логгер и `fetchRetry`, удобнее импортировать по подпутям — тогда OAuth-модуль не загружается вообще.
+
+```js
+// Проект без OAuth: ничего лишнего не поднимается
+import { logs } from "@andrey4emk/npm-app-back-b24/logs";
+import { fetchRetry, maskUrl } from "@andrey4emk/npm-app-back-b24/fetchRetry";
+```
+
+Корневой импорт при этом остаётся безопасным: если `APP_B24_CLIENT_ID` и `APP_B24_CLIENT_SECRET` не заданы, пакет считает, что OAuth в проекте не используется, молча выставляет `$b24 = null` и пишет об этом только в `debug`.
+
 ## Использование
 
 ```js
@@ -46,6 +64,7 @@ import {
     logs,
     fetchRetry,
     isNetworkError,
+    maskUrl,
 } from "@andrey4emk/npm-app-back-b24";
 
 // $b24 — готовый экземпляр B24OAuth (или null, если токены не настроены)
@@ -116,6 +135,7 @@ const response = await fetchRetry("https://api.example.com/data", { method: "GET
     **Особенности:**
     -   При обновлении токенов SDK автоматически сохраняет их в файл через callback `setCallbackRefreshAuth`.
     -   Окружение (`DEV`/`PROD`) определяется переменной `APP_ENV` — используется как ключ секции в конфиге авторизации.
+    -   Признак того, что проект использует OAuth, — заданные `APP_B24_CLIENT_ID` и `APP_B24_CLIENT_SECRET`. Если их нет, `$b24` молча становится `null` (уровень `debug`). Если они заданы, но токенов в `authB24.json` не хватает, пишется `error` — это уже настоящая проблема конфигурации.
 
     **Retry при сетевых ошибках:**
 
@@ -126,7 +146,11 @@ 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()` с уровнем `error` — в сообщение попадает код ошибки SDK.
+    Retry срабатывает только при сетевых проблемах (`ECONNRESET`, `ETIMEDOUT`, `ERR_NETWORK` и т.д.). HTTP-ошибки (400, 500) и ошибки бизнес-логики Bitrix24 **не** вызывают повторных попыток. Каждая неудачная попытка логируется через `logs.add()` с уровнем `warn` — в сообщение попадает код ошибки SDK. Уровень `warn` выбран намеренно: `error` уходит в чат B24, и пять попыток одного упавшего вызова превращались в пять сообщений. Финальный провал приходит вызывающему коду исключением и логируется им один раз.
+
+    **Создающие вызовы не повторяются.** Если в вызове есть метод, создающий сущность (`*.add`, `*.uploadfile`, `*.import`, `*.register` — в том числе внутри `callBatch`), retry отменяется, а в лог идёт `повтор отменён`. Причина: при ответе портала «200 без поля `result`» (заглушка прокси или WAF) SDK падает в собственной ветке логирования и отдаёт ошибку со `status: 0`, неотличимую от транспортного сбоя — хотя запрос уже выполнен. Повтор в такой ситуации создавал до пяти дубликатов задачи или файла. Идемпотентные записи (`*.update`, `*.delete`, `*.set`) повторяются как прежде: повторное применение даёт то же состояние.
+
+    **Обмен refresh-токена** повторяется по более строгому правилу — только если соединение заведомо не состоялось (`ENOTFOUND`, `ECONNREFUSED`, `EAI_AGAIN`, `ENETUNREACH`, см. `isPreConnectionError()`). При таймауте или обрыве сервер мог уже провести ротацию, а ответ потеряться: повтор вернул бы `invalid_grant` и оставил в конфиге мёртвый `refresh_token`.
 
     У самого SDK есть собственный слой ретраев (`maxRetries: 3`), но он работает только при rate limit (HTTP 429, 503) и при распознанных `NETWORK_ERROR` / `REQUEST_TIMEOUT`. Замаскированные транспортные сбои приходят с кодом `JSSDK_UNKNOWN_ERROR`, который входит в `BUILT_IN_HARD_ERROR_CODES` — на таких ошибках SDK делает одну попытку, и повторяет только Proxy.
 
@@ -633,6 +657,29 @@ const response = await fetchRetry("https://api.example.com/data", { method: "GET
 
 -   **`fetchRetry(url, options?, retries?, delay?)`** — обёртка над `fetch` с повторными попытками при сетевых ошибках. HTTP-ошибки (4xx, 5xx) **не** вызывают повторных попыток — повторяются только сетевые сбои (TypeError, ECONNRESET, ETIMEDOUT и т.д.).
 
+-   **`maskUrl(url)`** — маскирует секреты в адресе перед записью в лог. URL входящего вебхука B24 содержит секрет прямо в пути (`/rest/1/<секрет>/method.json`), а токен авторизации может приходить в query-параметрах (`auth`, `access_token`, `refresh_token`, `token`). Хост и имя метода сохраняются, тело секрета заменяется на `***`. Используется внутри `fetchRetry`; применяйте в своём коде везде, где логируете адреса запросов к B24.
+
+    ```js
+    import { maskUrl } from "@andrey4emk/npm-app-back-b24";
+
+    logs.add(`Запрос не прошёл — ${maskUrl(url)}`, "warn");
+    // https://portal.bitrix24.ru/rest/1/***/crm.deal.get.json
+    ```
+
+-   **`isPreConnectionError(error)`** — строгая проверка: соединение не состоялось, значит запрос **точно** не был выполнен сервером (`ENOTFOUND`, `ECONNREFUSED`, `EAI_AGAIN`, `ENETUNREACH`; код ищется и во вложенных `originalError` / `cause`). Отличие от `isNetworkError()` в том, что таймаут и обрыв соединения тоже сетевые, но при них ответ мог потеряться уже после обработки запроса. Используйте эту проверку там, где повтор небезопасен сам по себе: создание сущностей, отправка сообщений, обмен токена.
+
+    ```js
+    import { isPreConnectionError } from "@andrey4emk/npm-app-back-b24";
+
+    try {
+        await sendSms(phone, text);
+    } catch (error) {
+        // Повторяем только если сообщение заведомо не ушло
+        if (isPreConnectionError(error)) await sendSms(phone, text);
+        else throw error;
+    }
+    ```
+
 -   **`isNetworkError(error)`** — проверяет, является ли ошибка сетевой (стоит повторить запрос). Используется внутри `fetchRetry` и retry-обёртки `$b24`. Можно использовать в своём коде для аналогичных проверок.
 
     ```js
@@ -661,7 +708,7 @@ const response = await fetchRetry("https://api.example.com/data", { method: "GET
     -   **Обрабатываемые сетевые ошибки:**
         `ECONNRESET`, `ECONNREFUSED`, `ETIMEDOUT`, `ENOTFOUND`, `ENETUNREACH`, `EAI_AGAIN`, `UND_ERR_CONNECT_TIMEOUT`, `UND_ERR_SOCKET`, `TypeError`, а также ошибки с сообщениями `fetch failed`, `network`, `socket`.
 
-    -   **Логирование:** при каждой неудачной попытке записывает сообщение через `logs.add()` с уровнем `error`.
+    -   **Логирование:** при каждой неудачной попытке записывает сообщение через `logs.add()` с уровнем `warn`. Адрес запроса перед записью пропускается через `maskUrl()`, поэтому секрет вебхука в лог не попадает.
 
     ```js
     import { fetchRetry } from "@andrey4emk/npm-app-back-b24";

package/bitrix24/b24.ts

@@ -1,7 +1,7 @@
 import { B24OAuth, AjaxError, SdkError, Logger } from "@bitrix24/b24jssdk";
 import type { B24OAuthParams, B24OAuthSecret, AuthData, AjaxResult } from "@bitrix24/b24jssdk";
 import { logs } from "../logs/logs.ts";
-import { isNetworkError } from "../utils/fetchRetry.ts";
+import { isNetworkError, isPreConnectionError } from "../utils/fetchRetry.ts";
 import Conf from "conf";
 import path from "path";
 import type { Request, Response } from "express";
@@ -37,11 +37,22 @@ const RETRY_DELAY_MS = 500;
 /** Методы B24OAuth, оборачиваемые retry-логикой (fetchListMethod — async-генератор, его оборачивать нельзя) */
 const RETRYABLE_METHODS = new Set(["callMethod", "callListMethod", "callBatch"]);
 
-/** Коды AxiosError, означающие проблему с сетью */
-const AXIOS_NETWORK_CODES = new Set(["ERR_NETWORK", "ECONNABORTED"]);
+/**
+ * Коды транспортного сбоя. Один набор и для SdkError (AjaxError, RefreshTokenError),
+ * и для вложенного AxiosError — списки совпадали, держать их раздельно смысла нет.
+ */
+const NETWORK_ERROR_CODES = new Set(["NETWORK_ERROR", "REQUEST_TIMEOUT", "ERR_NETWORK", "ECONNABORTED"]);
 
-/** Коды ошибок SDK (AjaxError / RefreshTokenError), означающие транспортный сбой */
-const SDK_NETWORK_CODES = new Set(["NETWORK_ERROR", "REQUEST_TIMEOUT", "ERR_NETWORK", "ECONNABORTED"]);
+/**
+ * REST-методы B24, повтор которых создаёт дубликат сущности.
+ *
+ * SDK 2.x при ответе портала «200 без поля result» (заглушка прокси или WAF) падает
+ * внутри собственной логирующей ветки и отдаёт ошибку со status 0 — неотличимую от
+ * транспортного сбоя. Запрос при этом уже выполнен, поэтому retry создаст вторую
+ * задачу, второй файл и т.д. Идемпотентные записи (update, delete, set) повторять
+ * безопасно: повторное применение даёт то же состояние.
+ */
+const NON_IDEMPOTENT_METHOD_RE = /\.(add|uploadfile|import|register)(\?|$)/i;
 
 const confAuthB24 = new Conf({
     cwd: path.resolve(CONFIG_DIR),
@@ -86,11 +97,12 @@ export function getResultData<T = any>(response: AjaxResult, methodName: string)
 // ==================== Создание экземпляра B24OAuth ====================
 
 function createB24Instance(): B24OAuth | null {
-    const store = confAuthB24.store as Record<string, AuthData>;
-    const authConfig = store[APP_ENV];
-
-    if (!authConfig?.domain || !authConfig?.access_token || !authConfig?.refresh_token) {
-        logs.add("В конфиге authB24 не хватает данных для авторизации. Сохрани токены через клиент и перезагрузи докер", "error");
+    // Проект вообще не использует OAuth: ходит в B24 по входящему вебхуку либо берёт
+    // из пакета только logs/fetchRetry. Отсутствие авторизации для него — норма, а не
+    // ошибка, поэтому уровень debug: иначе ложная строка попадает в мониторинг.
+    // Признак «OAuth задуман» — наличие credentials приложения в .env.
+    if (!CLIENT_ID && !CLIENT_SECRET) {
+        logs.add("OAuth Bitrix24 не настроен (APP_B24_CLIENT_ID и APP_B24_CLIENT_SECRET не заданы), $b24 = null", "debug");
         return null;
     }
 
@@ -99,6 +111,14 @@ function createB24Instance(): B24OAuth | null {
         return null;
     }
 
+    const store = confAuthB24.store as Record<string, AuthData>;
+    const authConfig = store[APP_ENV];
+
+    if (!authConfig?.domain || !authConfig?.access_token || !authConfig?.refresh_token) {
+        logs.add("В конфиге authB24 не хватает данных для авторизации. Сохрани токены через клиент и перезагрузи докер", "error");
+        return null;
+    }
+
     const domain = cleanDomain(authConfig.domain);
 
     const authParams: B24OAuthParams = {
@@ -221,11 +241,17 @@ async function refreshAuthWithMutex(): Promise<AuthData> {
                     return await $b24.auth.refreshAuth();
                 } catch (error) {
                     lastError = error;
-                    if (!isB24NetworkError(error) || attempt === RETRY_COUNT) throw error;
+
+                    // Повторяем только когда соединение заведомо не состоялось: при таймауте
+                    // или обрыве сервер мог уже провести ротацию, ответ потеряться, и повтор
+                    // вернёт invalid_grant — refresh-токен окажется сожжён, потребуется
+                    // ручная переавторизация
+                    if (!isPreConnectionError(error) || attempt === RETRY_COUNT) throw error;
+
                     const msg = error instanceof Error ? error.message : String(error);
                     const code = error instanceof SdkError ? ` [${error.code}]` : "";
                     const delayMs = RETRY_DELAY_MS * attempt;
-                    logs.add(`refreshAuth${code}: попытка ${attempt}/${RETRY_COUNT} не удалась (${msg}), повтор через ${delayMs}мс`, "error");
+                    logs.add(`refreshAuth${code}: попытка ${attempt}/${RETRY_COUNT} не удалась (${msg}), повтор через ${delayMs}мс`, "warn");
                     await delay(delayMs);
                 }
             }
@@ -312,19 +338,48 @@ function isB24NetworkError(error: unknown): boolean {
 
     if (error instanceof SdkError) {
         const { code, originalError, status } = error;
+        const originalCode = (originalError as { code?: string } | undefined)?.code;
 
-        if (SDK_NETWORK_CODES.has(code)) return true;
+        if (NETWORK_ERROR_CODES.has(code)) return true;
         if (originalError && isNetworkError(originalError)) return true;
-        if (AXIOS_NETWORK_CODES.has((originalError as any)?.code)) return true;
+        if (originalCode && NETWORK_ERROR_CODES.has(originalCode)) return true;
         if (status === 0) return true;
     }
 
     return isNetworkError(error);
 }
 
+/** Достаёт имена REST-методов B24 из аргументов вызова SDK */
+function extractB24Methods(sdkMethod: string, args: any[]): string[] {
+    const first = args[0];
+
+    // callMethod(method, params) и callListMethod(method, params, ...)
+    if (sdkMethod === "callMethod" || sdkMethod === "callListMethod") {
+        return typeof first === "string" ? [first] : [];
+    }
+
+    // callBatch(calls, ...) — команды приходят массивом либо объектом-словарём
+    if (sdkMethod === "callBatch") {
+        const commands: unknown[] = Array.isArray(first) ? first : first && typeof first === "object" ? Object.values(first) : [];
+
+        return commands
+            .map((cmd) => (typeof cmd === "string" ? cmd : (cmd as { method?: unknown })?.method))
+            .filter((method): method is string => typeof method === "string");
+    }
+
+    return [];
+}
+
+/** Возвращает методы вызова, повтор которых создал бы дубликаты сущностей */
+function getNonIdempotentMethods(sdkMethod: string, args: any[]): string[] {
+    return extractB24Methods(sdkMethod, args).filter((method) => NON_IDEMPOTENT_METHOD_RE.test(method));
+}
+
 /** Оборачивает 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);
         let lastError: unknown;
 
         for (let attempt = 1; attempt <= RETRY_COUNT; attempt++) {
@@ -339,7 +394,21 @@ function withRetry<T extends (...args: any[]) => Promise<any>>(fn: T, context: a
 
                 const msg = error instanceof Error ? error.message : String(error);
                 const code = error instanceof SdkError ? ` [${error.code}]` : "";
-                logs.add(`$b24.${methodName}${code}: попытка ${attempt}/${RETRY_COUNT} не удалась (${msg}), повтор через ${RETRY_DELAY_MS}мс`, "error");
+
+                // Ошибка со status 0 может означать и «запрос не ушёл», и «запрос выполнен,
+                // а ответ не разобрался»: различить их нельзя, поэтому создающие вызовы
+                // не повторяем — лучше вернуть ошибку, чем создать дубликат
+                if (nonIdempotent.length > 0) {
+                    logs.add(
+                        `$b24.${methodName}${code}: повтор отменён, вызов создаёт сущности (${nonIdempotent.join(", ")}) — ${msg}`,
+                        "warn"
+                    );
+                    throw error;
+                }
+
+                // Уровень warn: промежуточные попытки не должны улетать в чат B24,
+                // финальный провал прилетит вызывающему коду исключением
+                logs.add(`$b24.${methodName}${code}: попытка ${attempt}/${RETRY_COUNT} не удалась (${msg}), повтор через ${RETRY_DELAY_MS}мс`, "warn");
 
                 await delay(RETRY_DELAY_MS);
             }
@@ -410,7 +479,7 @@ export async function reinitializeB24(): Promise<SaveResult> {
     $b24 = _b24Raw ? wrapB24WithRetry(_b24Raw) : null;
 
     if (!_b24Raw || !$b24) {
-        return { error: true, message: "Не удалось пересоздать $b24 — проверь authB24.json" };
+        return { error: true, message: "Не удалось пересоздать $b24 — проверь authB24.json и APP_B24_CLIENT_ID/APP_B24_CLIENT_SECRET" };
     }
 
     setupRefreshCallback(_b24Raw);
@@ -426,5 +495,12 @@ export async function reinitializeB24(): Promise<SaveResult> {
 
 if (_b24Raw) {
     setupRefreshCallback(_b24Raw);
-    refreshAndSaveTokens().then(() => startProactiveRefresh());
+
+    // Намеренно не ждём результат: импорт модуля не должен блокироваться сетевым
+    // запросом к oauth.bitrix.info. refreshAndSaveTokens() исключений не бросает —
+    // ошибку возвращает в SaveResult и пишет в лог сам
+    void (async () => {
+        await refreshAndSaveTokens();
+        startProactiveRefresh();
+    })();
 }

package/bitrix24/eventB24.ts

@@ -154,10 +154,13 @@ export class Event {
 
                 if (allEvents.length > 0) {
                     data.processId = arrOfflineEvents.process_id;
-                    data.message = allEvents.map((event) => {
-                        const messageData = event.EVENT_DATA.MESSAGES[0];
+                    // Событие может принести несколько сообщений. Раньше бралось только
+                    // первое, а остальные терялись безвозвратно — событие после обработки
+                    // удаляется из очереди B24
+                    data.message = allEvents.flatMap((event) => {
+                        const messages = event.EVENT_DATA.MESSAGES ?? [];
 
-                        return {
+                        return messages.map((messageData: any) => ({
                             connectorId: event.EVENT_DATA.CONNECTOR,
                             lineId: event.EVENT_DATA.LINE,
                             chatId: messageData.chat.id,
@@ -165,7 +168,7 @@ export class Event {
                             file: this.convertB24FilesToTelegramFormat(messageData.message.files),
                             attachments: messageData.message.attachments || null,
                             im: messageData.im || null,
-                        };
+                        }));
                     });
                 }
 

package/package.json

@@ -1,11 +1,13 @@
 {
     "name": "@andrey4emk/npm-app-back-b24",
-    "version": "3.4.0",
+    "version": "3.6.0",
     "description": "Bitrix24 OAuth helpers for Node.js projects",
     "main": "index.ts",
     "type": "module",
     "exports": {
-        ".": "./index.ts"
+        ".": "./index.ts",
+        "./logs": "./logs/logs.ts",
+        "./fetchRetry": "./utils/fetchRetry.ts"
     },
     "scripts": {
         "test": "echo \"No tests\" && exit 0",

package/sendMessage/smsgold.ts

@@ -1,5 +1,6 @@
 import type { B24OAuth } from "@bitrix24/b24jssdk";
 import { getResultData } from "../bitrix24/b24.ts";
+import { fetchRetry } from "../utils/fetchRetry.ts";
 
 // ==================== Типы ====================
 
@@ -150,7 +151,10 @@ export class Smsgold {
 
     private async downloadFileToUrl(fileUrl: string): Promise<{ error: boolean; message?: string; buffer?: Buffer }> {
         try {
-            const response = await fetch(fileUrl);
+            // Скачивание файла идемпотентно — повтор при сетевом сбое безопасен.
+            // Отправка SMS (fetch выше по коду) намеренно остаётся без retry:
+            // при потерянном ответе повтор отправил бы сообщение второй раз
+            const response = await fetchRetry(fileUrl);
             if (!response.ok) {
                 throw new Error(`HTTP error! status: ${response.status}`);
             }

package/utils/fetchRetry.ts

@@ -32,6 +32,58 @@ export function isNetworkError(error: unknown): boolean {
     return false;
 }
 
+/**
+ * Коды, доказывающие, что соединение не было установлено: DNS не разрешился либо
+ * хост отверг подключение. Запрос при таких ошибках гарантированно не дошёл до сервера.
+ */
+const PRE_CONNECTION_ERROR_CODES = ["ENOTFOUND", "EAI_AGAIN", "ECONNREFUSED", "ENETUNREACH"];
+
+/**
+ * Проверяет, что соединение не состоялось — запрос точно не был выполнен сервером.
+ *
+ * Отличается от `isNetworkError()` строгостью: таймаут и обрыв соединения тоже сетевые,
+ * но при них ответ мог потеряться уже после того, как сервер обработал запрос.
+ * Используйте эту проверку вместо `isNetworkError()` там, где повтор небезопасен сам
+ * по себе: обмен refresh-токена, создание сущностей, отправка сообщений.
+ *
+ * @param error — пойманная ошибка
+ * @returns true, если повторить запрос заведомо безопасно
+ */
+export function isPreConnectionError(error: unknown): boolean {
+    if (!error || typeof error !== "object") return false;
+
+    const codes: unknown[] = [
+        (error as { code?: unknown }).code,
+        (error as { originalError?: { code?: unknown } }).originalError?.code,
+        (error as { cause?: { code?: unknown } }).cause?.code,
+    ];
+
+    return codes.some((code) => typeof code === "string" && PRE_CONNECTION_ERROR_CODES.includes(code));
+}
+
+/**
+ * Маскирует секреты в URL перед записью в лог.
+ *
+ * URL входящего вебхука B24 содержит секрет прямо в пути
+ * (`https://портал.bitrix24.ru/rest/1/<секрет>/method.json`), а токен авторизации
+ * может приходить в query-параметрах. Хост и имя метода сохраняются — они нужны
+ * для диагностики, тело секрета заменяется на `***`.
+ *
+ * @param url — адрес запроса в любом виде, принимаемом fetch
+ * @returns строка URL, пригодная для логирования
+ */
+export function maskUrl(url: string | URL | Request): string {
+    const raw = typeof url === "string" ? url : url instanceof URL ? url.href : url.url;
+
+    return (
+        raw
+            // Секрет входящего вебхука: /rest/<id пользователя>/<секрет>/
+            .replace(/(\/rest\/\d+\/)[^/?#]+/gi, "$1***")
+            // Токены в query-параметрах
+            .replace(/([?&](?:auth|access_token|refresh_token|token)=)[^&#]+/gi, "$1***")
+    );
+}
+
 /**
  * Обёртка над fetch с повторными попытками при сетевых ошибках.
  * Повторяет запрос только при проблемах с сетью (TypeError, ECONNRESET и т.д.),
@@ -63,7 +115,7 @@ export async function fetchRetry(
             }
 
             logs.add(
-                `fetchRetry: попытка ${attempt}/${retries} не удалась (${lastError.message}), повтор через ${delay}мс — ${String(url)}`,
+                `fetchRetry: попытка ${attempt}/${retries} не удалась (${lastError.message}), повтор через ${delay}мс — ${maskUrl(url)}`,
                 "warn"
             );