@andrey4emk/npm-app-back-b24 4.0.0 → 4.0.1

package/README.md

@@ -442,7 +442,7 @@ const sent = await fetchWithTimeout("https://api.example.com/send", { method: "P
     | `createdBy`      | number           | `138`                     | ID создателя                                   |
     | `responsibleId`  | number           | `1`                       | ID ответственного                              |
     | `deadline`       | ISO string       | `DateTime.now() + 1 день` | Дедлайн в ISO формате                          |
-    | `groupId`        | number\|null     | `null`                    | ID группы (опционально)                        |
+    | `groupId`        | number\|null     | `B24_ERROR_TASK_GROUP_ID` или `null` | ID группы; не передан — берётся переменная окружения |
     | `accomplices`    | number[]         | `[]`                      | Массив ID соисполнителей                       |
     | `maxTasks`       | number           | `100`                     | Максимум существующих задач с таким названием  |
     | `ufCrmTask`      | string\|string[] | `""`                      | Значение для `UF_CRM_TASK` (массив или строка) |
@@ -459,6 +459,10 @@ const sent = await fetchWithTimeout("https://api.example.com/send", { method: "P
     });
     ```
 
+    **Отказ портала виден в логе.** Если портал отказал в создании задачи (нет прав, указанной группы не существует), пишется одна строка уровня `error` с заголовком задачи, номером группы и текстом ошибки. Сетевые сбои этой строки не дают: их уже записал слой повторов, и вторая ушла бы дублем в чат B24.
+
+    **Группа задачи по умолчанию.** Если `groupId` не передан, группа берётся из переменной окружения `B24_ERROR_TASK_GROUP_ID`. Явно переданное значение всегда важнее переменной: `null` и `0` означают осознанное «без группы» и дефолт не подхватывают. Переменная читается один раз при загрузке модуля — правка `process.env` в рантайме дефолт не двигает, нужен перезапуск процесса. Если переменная не задана или непригодна (не целое больше нуля), поведение прежнее — задача создаётся без группы, плюс одна строка уровня `warn` за процесс. Строка пишется при первом вызове, которому дефолт реально понадобился: у потребителя, который всегда передаёт группу сам, в логе не появится ничего.
+
 -   **`checkB24Scope()`** — проверяет и логирует права (скоупы) приложения Bitrix24. Вызывается автоматически при старте, если `$b24` инициализирован.
 
 ### События
@@ -989,6 +993,7 @@ const sent = await fetchWithTimeout("https://api.example.com/send", { method: "P
 | `APP_B24_CLIENT_SECRET`     | Client Secret приложения Bitrix24                               |
 | `APP_ENV`                   | Определяет окружение, используется как ключ секции авторизации   |
 | `APP_NAME`                  | Название приложения (используется в описании задач)           |
+| `B24_ERROR_TASK_GROUP_ID`   | ID группы по умолчанию для задач `errorB24()` (не задана — задача без группы) |
 | `CONFIG_DIR`                | Путь к директории с конфигами (по умолчанию `../config`)      |
 | `FETCH_TIMEOUT_MS`          | Бюджет одной попытки `fetchRetry`/`fetchWithTimeout`, мс (по умолчанию `60000`; `0` — без таймаута) |
 | `FETCH_TIMEOUT_QUICK_MS`    | Бюджет `FETCH_TIMEOUTS.quick` — токены, мс (по умолчанию `10000`)               |
@@ -1010,6 +1015,10 @@ APP_NAME=MyApp
 CONFIG_DIR=../config
 FETCH_TIMEOUT_MS=60000
 
+# Группа по умолчанию для задач об ошибках. ID свой у каждого портала —
+# посмотреть в адресе группы на портале. Не задана — задачи создаются без группы
+B24_ERROR_TASK_GROUP_ID=196
+
 # Именованные бюджеты пакета — задавать только при необходимости, иначе действуют дефолты
 # FETCH_TIMEOUT_QUICK_MS=10000
 # FETCH_TIMEOUT_API_MS=20000

package/bitrix24/b24/retry.ts

@@ -402,8 +402,9 @@ export async function runWithRetry<T>(fn: () => Promise<T>, label: string, block
             const proven = isPreConnectionError(error);
 
             // Окончательные отказы логируем на error: собственные модули пакета
-            // (errorB24, Event, Smsgold) ошибку только возвращают вызывающему коду,
-            // но не пишут в лог — без этих строк сбой $b24 не виден нигде
+            // (Event, Smsgold) ошибку только возвращают вызывающему коду,
+            // но не пишут в лог — без этих строк сбой $b24 не виден нигде.
+            // errorB24 пишет сама только несетевой отказ, сетевой ждёт от нас
 
             // Ветка обмена токена стоит до проверки исчерпания попыток: иначе она
             // сработала бы только на пятой попытке, ради чего всё и затевалось

package/bitrix24/errTaskB24.ts

@@ -1,5 +1,6 @@
 import { DateTime } from "luxon";
 import { $b24, getResultData } from "./b24.ts";
+import { isB24NetworkError } from "./b24/retry.ts";
 import { logs } from "../logs/logs.ts";
 import dotEnv from "dotenv";
 
@@ -14,6 +15,10 @@ export interface ErrorTaskData {
     createdBy?: number;
     responsibleId?: number;
     deadline?: string;
+    /**
+     * ID группы задачи. Поле не передано — берётся `B24_ERROR_TASK_GROUP_ID`;
+     * явные `null` и `0` означают «без группы» и дефолт не подхватывают
+     */
     groupId?: number | null;
     accomplices?: number[];
     maxTasks?: number;
@@ -41,6 +46,76 @@ interface TaskItem {
 
 const appName: string = process.env.APP_NAME || "Задай название приложения в .env";
 
+/** Имя переменной окружения с группой по умолчанию для задач об ошибках */
+const ERROR_TASK_GROUP_ENV = "B24_ERROR_TASK_GROUP_ID";
+
+/** Разобранная группа по умолчанию плюс текст претензии к значению, если она есть */
+interface DefaultGroup {
+    /** ID группы либо `null` — «без группы» */
+    id: number | null;
+    /** Текст строки `warn`; `null` — предупреждать не о чем */
+    warning: string | null;
+}
+
+/**
+ * Разбирает значение `B24_ERROR_TASK_GROUP_ID`.
+ *
+ * `Number`, а не `parseInt`: последний молча съел бы «196abc» и вернул 196.
+ * Непригодное значение группой не становится — задача создаётся без группы,
+ * как до 4.0.1.
+ */
+function parseDefaultGroupId(raw: string | undefined): DefaultGroup {
+    const value = (raw ?? "").trim();
+
+    if (value === "") {
+        return {
+            id: null,
+            warning: `${ERROR_TASK_GROUP_ENV} не задана — задачи об ошибках создаются без группы`,
+        };
+    }
+
+    const parsed = Number(value);
+
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        return {
+            id: null,
+            warning: `${ERROR_TASK_GROUP_ENV}: значение '${value}' непригодно (нужно целое больше нуля) — задачи об ошибках создаются без группы`,
+        };
+    }
+
+    return { id: parsed, warning: null };
+}
+
+/**
+ * Значение читается один раз при загрузке модуля — тем же правилом, что и бюджеты
+ * таймаутов в `utils/fetchRetry.ts`. Правка `process.env` в рантайме дефолт не двигает.
+ */
+const defaultGroup: DefaultGroup = parseDefaultGroupId(process.env[ERROR_TASK_GROUP_ENV]);
+
+/** Строка `warn` о непригодном дефолте пишется один раз за процесс, а не на каждый вызов */
+let defaultGroupWarned = false;
+
+/**
+ * Выбирает группу задачи.
+ *
+ * Явно переданное значение приоритетнее дефолта: `null` и `0` означают осознанное
+ * «без группы» (так же вёл себя прежний `dataTask.groupId || null`), а отсутствие поля
+ * и `undefined` — «решай сам», то есть дефолт из окружения.
+ *
+ * Предупреждение пишется только когда дефолт реально понадобился: у потребителя,
+ * который всегда передаёт группу сам, в логе не появится ни строки.
+ */
+function resolveGroupId(explicit: number | null | undefined): number | null {
+    if (explicit !== undefined) return explicit || null;
+
+    if (defaultGroup.warning !== null && !defaultGroupWarned) {
+        defaultGroupWarned = true;
+        logs.add(defaultGroup.warning, "warn");
+    }
+
+    return defaultGroup.id;
+}
+
 // ==================== Функция ====================
 
 /**
@@ -85,13 +160,16 @@ export async function errorB24(dataTask: ErrorTaskData): Promise<ErrorB24Result>
         };
     }
 
+    // Резолв группы стоит до `try`: сама функция не бросает, а номер группы нужен
+    // в `catch` — без него по строке отказа не понять, куда задача не попала
+    const groupId = resolveGroupId(dataTask.groupId);
+
     try {
         const title = dataTask.title;
         const description = dataTask.description || "";
         const createdBy = dataTask.createdBy || 138;
         const responsibleId = dataTask.responsibleId || 1;
         const deadline = dataTask.deadline || DateTime.now().plus({ days: 1 }).toISO();
-        const groupId = dataTask.groupId || null;
         const accomplices = dataTask.accomplices || [];
         const maxTasks = dataTask.maxTasks || 100;
         const ufCrmTask = dataTask.ufCrmTask ?? dataTask.entityTypeAbbr ?? "";
@@ -137,6 +215,19 @@ export async function errorB24(dataTask: ErrorTaskData): Promise<ErrorB24Result>
         };
     } catch (error: unknown) {
         const message = error instanceof Error ? error.message : String(error);
+
+        // Отказ портала иначе не виден нигде: несетевую ошибку retry-слой отдаёт
+        // наружу как есть, без единой строки в логе, а `errorB24()` зовут последним
+        // средством и её результат обычно не читают — отказ прав или неверный номер
+        // группы уходил бы в тишину.
+        //
+        // Условие обязательно: сетевой отказ retry-слой уже записал сам — строкой
+        // про исчерпание попыток либо про отменённый повтор. Без проверки вторая
+        // строка ушла бы дублем в чат B24, куда уходит уровень `error`
+        if (!isB24NetworkError(error)) {
+            logs.add(`errorB24: задача «${dataTask.title}» не создана (группа ${groupId ?? "не задана"}) — ${message}`, "error");
+        }
+
         return {
             error: true,
             message: `Не удалось создать задачу в Битрикс24: ${message}`,

package/package.json

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