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

package/bitrix24/eventB24.ts

@@ -1,4 +1,5 @@
 import { $b24, getResultData, type B24MethodCaller } from "./b24.ts";
+import { logs } from "../logs/logs.ts";
 
 // ==================== Типы ====================
 
@@ -74,32 +75,140 @@ interface OfflineEventsResponse {
 /**
  * Пользователь, чьи события класс отбрасывает и сразу очищает из очереди.
  *
- * Это защита от петли, а не случайность: 138 — владелец OAuth-токенов приложений
- * на портале, и всё, что приложения пишут в B24 (обновление сделки, комментарий,
- * задача), приходит офлайн-событием с `user_id: "138"`. Без фильтра правка сделки
- * кодом возвращалась бы событием в тот же код и обрабатывалась бы второй раз.
+ * Это защита от петли, а не случайность: 138 — владелец OAuth-токенов всех приложений
+ * на портале, и всё, что приложения и роботы пишут в B24 (обновление сделки,
+ * комментарий, задача), приходит офлайн-событием с `user_id: "138"`. Собственные
+ * правки платформа приложению не отдаёт, но правки соседнего приложения под тем же
+ * владельцем — отдаёт; без фильтра правка сделки одним приложением обрабатывалась бы
+ * другим как внешнее изменение, и дальше по кругу.
  *
  * Оборотная сторона: ручные правки под этой же учёткой (это администратор портала)
  * тоже пропадают. Поэтому класс не годится для задач полной выгрузки или витрин,
  * где нужны все изменения без исключения — там читать `event.offline.get` напрямую
+ *
+ * Сравнение идёт по нормализованному значению (`readId`), поэтому системным считается
+ * и строка `"138"`, и число `138`. Портал сегодня отдаёт `user_id` строкой, то есть
+ * в бою это ничего не меняет; форма поля на защиту от петли влиять не должна
  */
 const SYSTEM_USER_ID = "138";
 
 // ==================== Утилиты ====================
 
 /**
- * Приводит MESSAGES из события к массиву.
+ * Приводит коллекцию из ответа портала к массиву.
  *
  * B24 отдаёт коллекции то массивом, то словарём с числовыми ключами (так PHP
  * сериализует разреженный массив), поэтому опираться на одну форму нельзя.
  * Неизвестная форма даёт пустой массив, а не исключение.
+ *
+ * Применяется к обеим коллекциям одного ответа — к списку записей и к сообщениям
+ * внутри записи: защита только одной из них читалась бы как решение «здесь
+ * нормализация не нужна», а словарь на месте списка ронял бы весь вызов.
  */
-function normalizeMessages(messages: unknown): any[] {
-    if (Array.isArray(messages)) return messages;
-    if (messages && typeof messages === "object") return Object.values(messages);
+function normalizeCollection(value: unknown): any[] {
+    if (Array.isArray(value)) return value;
+    if (value && typeof value === "object") return Object.values(value);
     return [];
 }
 
+/**
+ * Возвращает значение как словарь или null.
+ *
+ * Массив словарём не считается намеренно: PHP сериализует пустую коллекцию в `[]`,
+ * и такая форма на месте `EVENT_DATA` или `EVENT_ADDITIONAL` — признак битой записи,
+ * а не словаря с полями.
+ */
+function asRecord(value: unknown): Record<string, unknown> | null {
+    if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+    return value as Record<string, unknown>;
+}
+
+/**
+ * Приводит идентификатор B24 к непустой строке.
+ *
+ * Портал отдаёт идентификаторы то строкой, то числом. Всё остальное (null, undefined,
+ * объект, пустая строка, нечисловое число) считается отсутствием значения.
+ */
+function readId(value: unknown): string | null {
+    if (typeof value === "number") return Number.isFinite(value) ? String(value) : null;
+    if (typeof value !== "string") return null;
+
+    const trimmed = value.trim();
+    return trimmed === "" ? null : trimmed;
+}
+
+/** Что делать с записью очереди в ветке сущностей */
+type EntityVerdict =
+    | { kind: "system"; messageId: string | null }
+    | { kind: "broken"; messageId: string | null; eventName: string; reason: string }
+    | { kind: "active"; messageId: string; entityId: string; note?: string };
+
+/** Вердикт `active` — вынесен отдельно, чтобы фильтр давал строгие `string` без утверждений типа */
+type ActiveEntityVerdict = Extract<EntityVerdict, { kind: "active" }>;
+
+/** Вердикт `broken` — вынесен отдельно ради типизированного фильтра при логировании */
+type BrokenEntityVerdict = Extract<EntityVerdict, { kind: "broken" }>;
+
+/**
+ * Классифицирует запись очереди офлайн-событий в ветке сущностей.
+ *
+ * Чистая функция без побочных эффектов: решает только «системная / битая / рабочая»,
+ * а логирование и очистку делает вызывающий.
+ *
+ * Битой считается только та запись, которую обработать нечем: нет идентификатора
+ * сущности (`EVENT_DATA.FIELDS.ID`) или нет ключа очистки (`MESSAGE_ID`). Отсутствие
+ * `EVENT_ADDITIONAL.user_id` битой запись не делает — идентификатор сущности на месте,
+ * значит потребитель её обработает. Признать такую запись битой значило бы поменять
+ * громкое падение на тихое безвозвратное удаление: `event.offline.clear` снимает
+ * запись с резерва навсегда, и восстановить её нечем.
+ *
+ * Обратная сторона учтена: если у записи не читается `user_id`, а на самом деле она
+ * от системного пользователя, она пройдёт как рабочая и теоретически даст петлю между
+ * приложениями. Это приемлемо — петля шумная и видимая, а тихая потеря нет; вдобавок
+ * на такую запись вызывающий пишет строку `warn` (поле `note`).
+ *
+ * Порядок проверок важен. Системная запись определяется до разбора `EVENT_DATA`:
+ * её данные не нужны, а битая системная запись должна уходить в очистку как системная —
+ * иначе лог шумел бы про записи, которые мы и так выбрасываем по замыслу.
+ *
+ * @param raw — запись, как её прислал портал
+ * @param requestedEventName — имя события из запроса, подставляется, если в записи его нет
+ */
+function classifyEntityEvent(raw: unknown, requestedEventName: string): EntityVerdict {
+    const record = asRecord(raw);
+    if (!record) {
+        return { kind: "broken", messageId: null, eventName: requestedEventName, reason: "запись не является объектом" };
+    }
+
+    const messageId = readId(record.MESSAGE_ID);
+    const eventName = readId(record.EVENT_NAME) ?? requestedEventName;
+
+    const additional = asRecord(record.EVENT_ADDITIONAL);
+    const userId = readId(additional?.user_id);
+
+    if (userId === SYSTEM_USER_ID) {
+        return { kind: "system", messageId };
+    }
+
+    const fields = asRecord(asRecord(record.EVENT_DATA)?.FIELDS);
+    const entityId = readId(fields?.ID);
+    if (entityId === null) {
+        return { kind: "broken", messageId, eventName, reason: "нет EVENT_DATA.FIELDS.ID" };
+    }
+
+    // Без ключа очистки запись обработать нельзя: потребитель обработал бы сущность
+    // и не смог закрыть запись, и та пришла бы снова следующим опросом
+    if (messageId === null) {
+        return { kind: "broken", messageId, eventName, reason: "нет MESSAGE_ID" };
+    }
+
+    if (userId === null) {
+        return { kind: "active", messageId, entityId, note: "нет EVENT_ADDITIONAL.user_id, запись считается не системной" };
+    }
+
+    return { kind: "active", messageId, entityId };
+}
+
 // ==================== Класс ====================
 
 /**
@@ -187,9 +296,27 @@ export class Event {
      * под тем же `process_id`. Безопасный режим — `clear(processId)` целиком.
      *
      * События пользователя `SYSTEM_USER_ID` (138, владелец токенов приложений)
-     * отбрасываются и очищаются здесь же — защита от петли «приложение записало →
-     * событие → приложение обработало свою же запись». Для полной выгрузки всех
-     * изменений класс не подходит, см. комментарий у константы.
+     * отбрасываются и очищаются здесь же — защита от петли между приложениями
+     * и роботами под одной учёткой. Для полной выгрузки всех изменений класс
+     * не подходит, см. комментарий у константы.
+     *
+     * В ветке сущностей битая запись больше не роняет весь вызов. Битой считается
+     * та, у которой не читается идентификатор сущности (`EVENT_DATA.FIELDS.ID`)
+     * или ключ очистки (`MESSAGE_ID`): она отбрасывается, её `MESSAGE_ID` уходит
+     * в очистку вместе с системными, а в лог пишется одна строка `warn`. Запись,
+     * у которой не читается сам `MESSAGE_ID`, только логируется — снять её с резерва
+     * может лишь `clear(processId)` целиком.
+     *
+     * Отсутствие `EVENT_ADDITIONAL.user_id` битой записью не является: обработать её
+     * можно, поэтому она уходит потребителю как рабочая, а в лог пишется строка `warn`
+     * о том, что системной её признать нечем.
+     *
+     * Retry-слой этот вызов **не повторяет**: `event.offline.get` входит в
+     * `NON_RETRYABLE_METHODS` (`bitrix24/b24/retry.ts`). Повтор при сетевом сбое
+     * зарезервировал бы второй пакет поверх первого, ответ которого уже потерян.
+     * Исключение — доказанный pre-connection: соединение не состоялось, резервировать
+     * порталу было нечего. На практике это значит, что сбой сети даёт одну попытку
+     * и метод возвращает `{ error: true }` — очередь заберёт следующий опрос по таймеру.
      */
     async get(eventName: string): Promise<StandardResult> {
         try {
@@ -199,8 +326,10 @@ export class Event {
             });
 
             const arrOfflineEvents = getResultData<OfflineEventsResponse["result"]>(response, "event.offline.get");
-            // B24 для пустой коллекции может вернуть result: [] — тогда events отсутствует
-            const allEvents = arrOfflineEvents?.events ?? [];
+            // B24 для пустой коллекции может вернуть result: [] — тогда events отсутствует.
+            // Форму самой коллекции тоже не угадываем: словарь с числовыми ключами
+            // не должен ронять разбор, как не роняет он MESSAGES внутри записи
+            const allEvents = normalizeCollection(arrOfflineEvents?.events);
 
             // Обработка событий коннектора
             if (eventName === "ONIMCONNECTORMESSAGEADD") {
@@ -222,7 +351,7 @@ export class Event {
                     data.message = allEvents.flatMap((event) => {
                         const eventData = event.EVENT_DATA ?? {};
 
-                        return normalizeMessages(eventData.MESSAGES)
+                        return normalizeCollection(eventData.MESSAGES)
                             .filter((messageData) => messageData?.chat && messageData?.message)
                             .map((messageData) => ({
                                 // Портал отдаёт идентификаторы то строкой, то числом —
@@ -250,29 +379,102 @@ export class Event {
                 arrMessageIdAndEntityId: [],
             };
 
-            // Очищаем события от системного пользователя
-            const arrEventsToClear = allEvents.filter((event) => event.EVENT_ADDITIONAL.user_id === SYSTEM_USER_ID);
+            // Тип OfflineEvent описывает то, что портал обещает, а не то, что присылает:
+            // EVENT_ADDITIONAL и EVENT_DATA приходили и без обязательных полей (T-50).
+            // Параметр колбэка объявлен unknown намеренно — так классификация видит запись
+            // такой, какая она есть. Глобальная зачистка `any` в этом файле — отдельная задача T-53
+            const verdicts = allEvents.map((raw: unknown) => classifyEntityEvent(raw, eventName));
+
+            // Битую запись обработать нечем, и о её пропаже иначе не узнает никто:
+            // ошибку вызова логирует retry-слой, а отброшенные данные — только мы
+            const brokenVerdicts = verdicts.filter((verdict): verdict is BrokenEntityVerdict => verdict.kind === "broken");
+
+            for (const verdict of brokenVerdicts) {
+                logs.add(
+                    `[${verdict.messageId ?? "без MESSAGE_ID"}] event.offline.get: запись пропущена, ${verdict.reason} (событие ${verdict.eventName})`,
+                    "warn"
+                );
+            }
+
+            // Запись без user_id уходит потребителю как рабочая — предупреждаем:
+            // системной её признать нечем, и петля между приложениями на такой записи
+            // иначе прошла бы незамеченной
+            for (const verdict of verdicts) {
+                if (verdict.kind !== "active" || !verdict.note) continue;
+
+                logs.add(`[${verdict.messageId}] event.offline.get: ${verdict.note}`, "warn");
+            }
+
+            // Битой оказалась вся выборка целиком — это уже не одна кривая запись,
+            // а похоже на смену формы ответа портала (переименованное поле). Уровень
+            // error, потому что строка обязана дойти до чата B24: очередь при этом
+            // продолжает вычищаться пакет за пакетом, и локальный лог никто не увидит
+            if (verdicts.length > 1 && brokenVerdicts.length === verdicts.length) {
+                const firstReason = brokenVerdicts.at(0)?.reason ?? "причина не определена";
+
+                logs.add(
+                    `event.offline.get: битыми оказались все записи выборки, их ${verdicts.length}, причина первой — ${firstReason}. Похоже на смену формы ответа портала`,
+                    "error"
+                );
+            }
+
+            // process_id читаем защищённо: при пустой коллекции портал отдаёт result: []
+            const processId = readId(arrOfflineEvents?.process_id);
+
+            // Без process_id снять с резерва нельзя ни битые записи, ни обработанные:
+            // потребитель не получит ключ для clear(). Предупреждаем один раз на вызов
+            // и независимо от корзины — последствие у всей выборки одно: записи придут
+            // следующим опросом и будут обработаны повторно
+            if (processId === null && verdicts.length > 0) {
+                logs.add(
+                    "event.offline.get: в ответе нет process_id — снять записи с резерва нечем, они придут следующим опросом и будут обработаны повторно",
+                    "warn"
+                );
+            }
 
-            if (arrEventsToClear.length > 0) {
-                const arrMessageIdToClear = arrEventsToClear.map((event) => event.MESSAGE_ID);
+            // Снимаем с резерва и системные записи (выброшены по замыслу), и битые:
+            // иначе они провисят зарезервированными до автоудаления через 30 дней.
+            // Битая запись без читаемого MESSAGE_ID сюда попасть не может — передавать нечего,
+            // забрать её может только clear(processId) целиком
+            const messageIdsToClear = verdicts
+                .filter((verdict) => verdict.kind !== "active")
+                .map((verdict) => verdict.messageId)
+                .filter((messageId): messageId is string => messageId !== null);
+
+            // Без process_id вызов пропускаем молча: строка warn о его отсутствии
+            // уже написана выше, на всю выборку разом
+            if (messageIdsToClear.length > 0 && processId !== null) {
                 // Результат намеренно не проверяется: отказ здесь не фатален — те же
-                // записи придут следующим опросом, а бросок лишил бы потребителя всей
-                // выборки активных событий
-                await this.b24.callMethod("event.offline.clear", {
-                    process_id: arrOfflineEvents.process_id,
-                    message_id: arrMessageIdToClear,
-                });
+                // записи придут следующим опросом. Исключение ловим здесь же и наружу
+                // не пускаем: бросок после исчерпания повторов Proxy унёс бы всю выборку
+                // активных записей, а пакет к этому моменту уже зарезервирован под
+                // process_id — снять его с резерва потребителю было бы нечем
+                try {
+                    await this.b24.callMethod("event.offline.clear", {
+                        process_id: processId,
+                        message_id: messageIdsToClear,
+                    });
+                } catch (error: unknown) {
+                    const message = error instanceof Error ? error.message : String(error);
+
+                    // Уровень warn, а не error: окончательный отказ вызова уже написал
+                    // строку error retry-слой Proxy, дубль ушёл бы в чат B24 второй раз
+                    logs.add(
+                        `event.offline.clear: не удалось снять с резерва записи, их ${messageIdsToClear.length} — ${message}. Записи придут следующим опросом`,
+                        "warn"
+                    );
+                }
             }
 
-            // Работаем только с событиями, не относящимися к системному пользователю
-            const activeEvents = allEvents.filter((event) => event.EVENT_ADDITIONAL.user_id !== SYSTEM_USER_ID);
+            // Работаем только с рабочими записями: не системными и не битыми
+            const activeEvents = verdicts.filter((verdict): verdict is ActiveEntityVerdict => verdict.kind === "active");
 
             if (activeEvents.length > 0) {
-                data.processId = arrOfflineEvents.process_id;
-                data.entitysId = activeEvents.map((event) => event.EVENT_DATA.FIELDS.ID);
-                data.arrMessageIdAndEntityId = activeEvents.map((event) => ({
-                    messageId: event.MESSAGE_ID,
-                    entityId: event.EVENT_DATA.FIELDS.ID,
+                data.processId = processId;
+                data.entitysId = activeEvents.map((verdict) => verdict.entityId);
+                data.arrMessageIdAndEntityId = activeEvents.map((verdict) => ({
+                    messageId: verdict.messageId,
+                    entityId: verdict.entityId,
                 }));
             }
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@andrey4emk/npm-app-back-b24",
-    "version": "3.8.2",
+    "version": "3.9.0",
     "description": "Bitrix24 OAuth helpers for Node.js projects",
     "main": "index.ts",
     "type": "module",
@@ -10,7 +10,7 @@
         "./fetchRetry": "./utils/fetchRetry.ts"
     },
     "scripts": {
-        "test": "echo \"No tests\" && exit 0",
+        "test": "DOTENV_CONFIG_QUIET=true node --test --test-timeout=30000 \"tests/**/*.test.ts\"",
         "pack:dry": "npm pack --dry-run"
     },
     "repository": {
@@ -30,6 +30,14 @@
     "files": [
         "index.ts",
         "bitrix24/b24.ts",
+        "bitrix24/b24/types.ts",
+        "bitrix24/b24/config.ts",
+        "bitrix24/b24/state.ts",
+        "bitrix24/b24/retry.ts",
+        "bitrix24/b24/facade.ts",
+        "bitrix24/b24/proxy.ts",
+        "bitrix24/b24/instance.ts",
+        "bitrix24/b24/tokens.ts",
         "bitrix24/errTaskB24.ts",
         "bitrix24/eventB24.ts",
         "sendMessage/chatApp.ts",