@andrey4emk/npm-app-back-b24 3.4.0 → 3.5.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`, `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 при сетевых ошибках:**
 
@@ -633,6 +653,15 @@ 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
+    ```
+
 -   **`isNetworkError(error)`** — проверяет, является ли ошибка сетевой (стоит повторить запрос). Используется внутри `fetchRetry` и retry-обёртки `$b24`. Можно использовать в своём коде для аналогичных проверок.
 
     ```js
@@ -661,7 +690,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

@@ -86,11 +86,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 +100,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 = {
@@ -410,7 +419,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);

package/package.json

@@ -1,11 +1,13 @@
 {
     "name": "@andrey4emk/npm-app-back-b24",
-    "version": "3.4.0",
+    "version": "3.5.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/utils/fetchRetry.ts

@@ -32,6 +32,29 @@ export function isNetworkError(error: unknown): boolean {
     return false;
 }
 
+/**
+ * Маскирует секреты в 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 +86,7 @@ export async function fetchRetry(
             }
 
             logs.add(
-                `fetchRetry: попытка ${attempt}/${retries} не удалась (${lastError.message}), повтор через ${delay}мс — ${String(url)}`,
+                `fetchRetry: попытка ${attempt}/${retries} не удалась (${lastError.message}), повтор через ${delay}мс — ${maskUrl(url)}`,
                 "warn"
             );