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

package/README.md

@@ -474,6 +474,8 @@ const sent = await fetchWithTimeout("https://api.example.com/send", { method: "P
                     processId: "12345",
                     message: [
                         {
+                            messageId: "7cf5d29bee90cc37382a9fff07fc2a43", // MESSAGE_ID записи очереди — ключ для clear()
+                            eventId: "4821",                             // ID записи очереди, информационное; в clear() не передавать
                             connectorId: "...",
                             lineId: "...",
                             chatId: "...",
@@ -498,9 +500,11 @@ const sent = await fetchWithTimeout("https://api.example.com/send", { method: "P
             ```
 
         -   **Особенности:**
-            -   Автоматически фильтрует и удаляет события от системного пользователя (`user_id: '138'`).
+            -   **Автоматически отбрасывает и очищает события пользователя 138** — владельца OAuth-токенов приложений. Это защита от петли: всё, что приложения сами пишут в B24, приходит событием с `user_id: '138'`, и без фильтра код обрабатывал бы собственные записи повторно. Оборотная сторона: ручные правки под этой же учёткой (администратор портала) тоже не возвращаются. **Для полной выгрузки всех изменений класс не подходит** — там читать `event.offline.get` напрямую.
             -   Для коннекторных событий конвертирует файлы в формат с типами `image`, `video`, `document`.
             -   Если событий нет, возвращает `data` с пустыми массивами.
+            -   **Гранулярность очистки — запись очереди, а не сообщение.** Одна запись коннектора (один `MESSAGE_ID`) может нести несколько сообщений, и они приходят отдельными элементами `message` с одинаковым `messageId`. Очистка по этому ключу удаляет запись целиком: если из двух сообщений одной записи ушло одно, `clear()` заберёт и неотправленное. Строить поэлементную очистку с точностью до сообщения на `messageId` нельзя. Для дедупликации отдельных сообщений он не годится по той же причине — у сообщений одной записи он общий, для этого есть `im.id`. Обратная сторона: запись, из которой не разобрано ни одного сообщения, в `data.message` не попадёт вовсе, и очистка по собранным `messageId` её не заберёт. Безопасный режим — `clear(processId)` целиком.
+            -   Типы `ConnectorMessage`, `ConnectorEvents` и `EntityEvents` экспортируются из пакета.
 
         ```js
         const { error, data } = await event.get("ONCRMDYNAMICITEMUPDATE_149");
@@ -514,7 +518,7 @@ const sent = await fetchWithTimeout("https://api.example.com/send", { method: "P
         -   **Параметры:**
 
             -   `processId` (string) — ID процесса (получен из `get()`).
-            -   `messageId` (string|string[]) — опциональный ID или массив ID сообщений для очистки.
+            -   `messageId` (string|string[]) — опциональный `MESSAGE_ID` или массив `MESSAGE_ID` записей очереди для очистки. Без него очищается весь пакет `processId`. Пустой массив означает «очищать нечего»: вызов до API не доходит и возвращает `error: false` (раньше уезжало `message_id: []`). «Мягкая» ошибка портала, например `ERROR_ENTITY_NOT_FOUND` на протухшем `processId`, возвращается как `error: true`.
 
         -   **Возвращает:** промис с объектом `{ error, message, data }`.
 

package/bitrix24/eventB24.ts

@@ -3,7 +3,18 @@ import { $b24, getResultData, type B24MethodCaller } from "./b24.ts";
 // ==================== Типы ====================
 
 /** Сообщение из коннектора */
-interface ConnectorMessage {
+export interface ConnectorMessage {
+    /**
+     * `MESSAGE_ID` записи очереди офлайн-событий — ключ для `clear()`.
+     * Идентифицирует запись, а не отдельное сообщение: у сообщений одной записи
+     * он общий, поэтому для дедупликации сообщений не годится (для этого `im.id`)
+     */
+    messageId: string;
+    /**
+     * `ID` записи очереди офлайн-событий. Поле информационное, для сверки
+     * с `event.offline.list`. В `clear()` не передавать — метод принимает `MESSAGE_ID`
+     */
+    eventId: string;
     connectorId: string;
     lineId: string;
     chatId: string;
@@ -14,7 +25,7 @@ interface ConnectorMessage {
 }
 
 /** События коннектора */
-interface ConnectorEvents {
+export interface ConnectorEvents {
     processId: string | null;
     message: ConnectorMessage[];
 }
@@ -26,7 +37,7 @@ interface MessageEntityLink {
 }
 
 /** События сущностей (сделки, смарт-процессы) */
-interface EntityEvents {
+export interface EntityEvents {
     processId: string | null;
     entitysId: string[];
     arrMessageIdAndEntityId: MessageEntityLink[];
@@ -41,6 +52,7 @@ interface StandardResult {
 
 /** Офлайн-событие Bitrix24 */
 interface OfflineEvent {
+    ID: string;
     MESSAGE_ID: string;
     EVENT_NAME: string;
     EVENT_DATA: any;
@@ -59,7 +71,19 @@ interface OfflineEventsResponse {
 
 // ==================== Константы ====================
 
-const SYSTEM_USER_ID = "138"; // ID системного пользователя для фильтрации
+/**
+ * Пользователь, чьи события класс отбрасывает и сразу очищает из очереди.
+ *
+ * Это защита от петли, а не случайность: 138 — владелец OAuth-токенов приложений
+ * на портале, и всё, что приложения пишут в B24 (обновление сделки, комментарий,
+ * задача), приходит офлайн-событием с `user_id: "138"`. Без фильтра правка сделки
+ * кодом возвращалась бы событием в тот же код и обрабатывалась бы второй раз.
+ *
+ * Оборотная сторона: ручные правки под этой же учёткой (это администратор портала)
+ * тоже пропадают. Поэтому класс не годится для задач полной выгрузки или витрин,
+ * где нужны все изменения без исключения — там читать `event.offline.get` напрямую
+ */
+const SYSTEM_USER_ID = "138";
 
 // ==================== Утилиты ====================
 
@@ -148,7 +172,24 @@ export class Event {
     }
 
     /**
-     * Получает офлайн-события по имени
+     * Получает офлайн-события по имени.
+     *
+     * Гранулярность очистки — запись очереди, а не сообщение. Для коннектора одна
+     * запись (один `MESSAGE_ID`) может нести несколько сообщений, и `get()` раскладывает
+     * их через `flatMap` — у таких сообщений `messageId` совпадает. Очистка по этому
+     * ключу удалит запись целиком: если из двух сообщений одной записи ушло одно,
+     * `clear()` заберёт и неотправленное. Поэлементную очистку с точностью до
+     * сообщения на этом ключе построить нельзя.
+     *
+     * Обратная сторона: запись, из которой не разобрано ни одного сообщения
+     * (пустой или битый `MESSAGES`), в `data.message` не попадает вовсе — очистка
+     * по собранным `messageId` её не заберёт, и она останется зарезервированной
+     * под тем же `process_id`. Безопасный режим — `clear(processId)` целиком.
+     *
+     * События пользователя `SYSTEM_USER_ID` (138, владелец токенов приложений)
+     * отбрасываются и очищаются здесь же — защита от петли «приложение записало →
+     * событие → приложение обработало свою же запись». Для полной выгрузки всех
+     * изменений класс не подходит, см. комментарий у константы.
      */
     async get(eventName: string): Promise<StandardResult> {
         try {
@@ -184,6 +225,10 @@ export class Event {
                         return normalizeMessages(eventData.MESSAGES)
                             .filter((messageData) => messageData?.chat && messageData?.message)
                             .map((messageData) => ({
+                                // Портал отдаёт идентификаторы то строкой, то числом —
+                                // приводим, чтобы тип `string` не врал
+                                messageId: String(event.MESSAGE_ID ?? ""),
+                                eventId: String(event.ID ?? ""),
                                 connectorId: eventData.CONNECTOR,
                                 lineId: eventData.LINE,
                                 chatId: messageData.chat.id,
@@ -210,6 +255,9 @@ export class Event {
 
             if (arrEventsToClear.length > 0) {
                 const arrMessageIdToClear = arrEventsToClear.map((event) => event.MESSAGE_ID);
+                // Результат намеренно не проверяется: отказ здесь не фатален — те же
+                // записи придут следующим опросом, а бросок лишил бы потребителя всей
+                // выборки активных событий
                 await this.b24.callMethod("event.offline.clear", {
                     process_id: arrOfflineEvents.process_id,
                     message_id: arrMessageIdToClear,
@@ -243,11 +291,29 @@ export class Event {
      */
     async clear(processId: string, messageId?: string | string[]): Promise<StandardResult> {
         try {
+            // Пустой массив в JavaScript истинен и уезжал в теле запроса как `message_id: []` —
+            // это не документированный режим «очистить весь пакет» (что портал делает с
+            // пустым списком, не проверялось). Считаем пустой список за «очищать нечего»
+            // и до API не доходим: молча сносить весь пакет по пустому списку опасно —
+            // зарезервированный пакет портал повторно не выдаёт
+            if (Array.isArray(messageId) && messageId.length === 0) {
+                return { error: false, message: "Список записей пуст, очищать нечего", data: null };
+            }
+
             const params: any = { process_id: processId };
             if (messageId) {
                 params.message_id = messageId;
             }
-            await this.b24.callMethod("event.offline.clear", params);
+            const response = await this.b24.callMethod("event.offline.clear", params);
+            // «Мягкую» ошибку (например, ERROR_ENTITY_NOT_FOUND на протухшем process_id)
+            // SDK не бросает, а возвращает AjaxResult с isSuccess: false. Без проверки
+            // метод рапортовал бы «События очищены» при неочищенной очереди.
+            // Именно isSuccess, а не getResultData(): та бросает ещё и на result == null,
+            // а что портал кладёт в result этого метода, не проверено
+            if (!response.isSuccess) {
+                const messages = response.getErrorMessages().join("; ") || "неизвестная ошибка";
+                throw new Error(`event.offline.clear: Bitrix24 вернул ошибку — ${messages}`);
+            }
 
             return { error: false, message: "События очищены", data: null };
         } catch (error: any) {

package/package.json

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