npm_appBackB24

Утилиты для работы с Bitrix24 OAuth на основе @bitrix24/b24jssdk.

Содержание

• Установка
• Использование
• API
  • OAuth функции
  • Утилиты
  • События
  • ChatApp
  • Smsgold
• Переменные окружения
• Скрипты
• Лицензия

Установка

npm install @andrey4emk/npm-app-back-b24

Использование

import { create, refresh, save, errTask, Event } from "@andrey4emk/npm-app-back-b24";
import { chatApp, smsgold } from "@andrey4emk/npm-app-back-b24";
import { AuthB24Model } from "./models/AuthB24.js"; // пример модели

// OAuth функции
const b24Client = await create(AuthB24Model);
const refreshResult = await refresh(AuthB24Model);

app.post("/b24/auth", (req, res) => save(req, res, AuthB24Model));

// Создание служебной задачи при ошибке
await errTask(b24Client, {
    title: "Ошибка синхронизации",
    description: "Детали ошибки здесь",
});

// Работа с событиями
const eventHandler = new Event(b24Client);
const { error, events } = await eventHandler.get("ONCRMDYNAMICITEMUPDATE_149");

// Работа с ChatApp
await chatApp.makeTokenChatApp();
const result = await chatApp.sendMessageChatApp("whatsApp", {
    phone: "+1234567890",
    message: "Привет!",
});

// Работа с SMSGold
await smsgold.sendSms("+1234567890", "Привет из SMSGold!");

API

OAuth функции

• create(AuthB24Model) — создаёт клиента B24OAuth с использованием сохранённых в БД токенов.

  • Параметры:
    • AuthB24Model (Sequelize Model) — модель для получения данных авторизации из БД.
  • Возвращает: промис с экземпляром B24OAuth, готовым к вызовам REST API.
  • Ошибки: выбрасывает Error если запись авторизации не найдена в БД.

  const b24 = await create(AuthB24Model);
  const result = await b24.callMethod("crm.contact.list", { limit: 5 });

• refresh(AuthB24Model) — продлевает токены через Bitrix24 и обновляет запись в БД.

  • Параметры:
    • AuthB24Model (Sequelize Model) — модель для обновления токенов.
  • Возвращает: промис с объектом { error: boolean, message: string }.

  const result = await refresh(AuthB24Model);
  if (!result.error) {
      console.log("Токены обновлены:", result.message);
  }

• save(req, res, AuthB24Model) — HTTP-обработчик для сохранения набора токенов из req.body.

  • Параметры:
    • req (Express Request) — объект запроса с полем body.
    • res (Express Response) — объект ответа.
    • AuthB24Model (Sequelize Model) — модель для сохранения.
  • Тело запроса (req.body):

    {
        "access_token": "string",
        "refresh_token": "string",
        "domain": "string",
        "expires_in": "number",
        "member_id": "number"
    }

  • Возвращает: HTTP-ответ с JSON { status, message } (код 201 при успехе, 400/500 при ошибках).

  app.post("/b24/auth", (req, res) => save(req, res, AuthB24Model));

Утилиты

• errTask(b24, dataTask) — создаёт служебную задачу в Bitrix24 при ошибках/событиях.

  • Алгоритм:

    1. Сначала проверяет, сколько задач с таким TITLE уже создано (через tasks.task.list).
    2. Если их меньше чем maxTasks, создаёт новую задачу (tasks.task.add).

  • Параметры:

    • b24 (B24OAuth) — экземпляр клиента Bitrix24.
    • dataTask (object) — объект с параметрами задачи (см. ниже).

  • Возвращает: промис с объектом:

    {
        error: false,
        message: "Задача создана в Битрикс24.",
        result: { /* API response */ }
    }

    или при превышении лимита:

    {
        error: false,
        message: "Превышено максимальное количество задач с таким названием (100). Новая задача не создана."
    }

    или при ошибке:

    {
        error: true,
        message: "Не удалось создать задачу в Битрикс24: <текст ошибки>"
    }

  Параметры dataTask:

  | Параметр | Тип | По умолчанию | Описание | | ---------------- | ------------ | ------------------------- | --------------------------------------------- | | title | string | обязательно | Заголовок задачи | | description | string | "" | Описание задачи | | createdBy | number | 138 | ID создателя | | responsibleId | number | 1 | ID ответственного | | deadline | ISO string | DateTime.now() + 1 день | Дедлайн в ISO формате | | groupId | number|null | null | ID группы (опционально) | | accomplices | array | [] | Массив ID соисполнителей | | maxTasks | number | 100 | Максимум существующих задач с таким названием | | entityTypeAbbr | string | "" | Код CRM сущности для UF_CRM_TASK |

  await errTask(b24, {
      title: "Ошибка синхронизации",
      description: "Не удалось подключиться к API",
      responsibleId: 42,
      deadline: new Date(Date.now() + 2 * 24 * 60 * 60 * 1000).toISOString(),
      maxTasks: 50,
  });

События

• Event — класс для работы с офлайн-событиями Bitrix24.

  import { Event } from "@andrey4emk/npm-app-back-b24";
  
  const eventHandler = new Event(b24);

  Методы:

  • get(eventName) — получить события по названию.

    • Параметры:

      • eventName (string) — название события (например, 'ONCRMDYNAMICITEMUPDATE_149').

    • Возвращает: промис с объектом:

      {
          error: false,
          events: {
              processId: "12345",
              entitysId: [101, 102, 103],
              arrMessageIdAndEntityId: [
                  { messageId: "msg_1", entityId: 101 },
                  { messageId: "msg_2", entityId: 102 },
                  { messageId: "msg_3", entityId: 103 }
              ]
          }
      }

      или при ошибке:

      {
          error: true,
          status: "error",
          message: "Не удалось получить события. <текст ошибки>"
      }

    • Особенности:

      • Автоматически фильтрует и удаляет события от пользователя с user_id: '138'.
      • Если событий нет, возвращает events с пустыми массивами.

    const { error, events } = await eventHandler.get("ONCRMDYNAMICITEMUPDATE_149");
    if (!error && events.entitysId.length > 0) {
        console.log("Обработанные ID сущностей:", events.entitysId);
        // events.processId — идентификатор процесса для очистки
        // events.arrMessageIdAndEntityId — данные для методов clear() и deleteMessageId()
    }

  • clear(processId, messageId) — очистить события в Bitrix24.

    • Параметры:

      • processId (string|number) — ID процесса (получен из get()).
      • messageId (array|string) — ID или массив ID сообщений для очистки.

    • Возвращает: промис с объектом:

      {
          error: false;
      }

      или при ошибке:

      {
          error: true,
          status: "error",
          message: "Не удалось очистить события. <текст ошибки>"
      }

    const { events } = await eventHandler.get("ONCRMDYNAMICITEMUPDATE_149");
    if (events.processId) {
        const messageIds = events.arrMessageIdAndEntityId.map((item) => item.messageId);
        await eventHandler.clear(events.processId, messageIds);
    }

  • deleteMessageId(entityId, arrMessageIdAndEntityId) — удалить запись события из массива (локально).

    • Параметры:

      • entityId (number) — ID сущности для удаления.
      • arrMessageIdAndEntityId (array) — исходный массив событий.

    • Возвращает: обновлённый массив без записей с указанным entityId.

    const { events } = await eventHandler.get("ONCRMDYNAMICITEMUPDATE_149");
    const updated = eventHandler.deleteMessageId(101, events.arrMessageIdAndEntityId);
    // updated содержит все события, кроме entityId: 101

ChatApp

• chatApp — готовый экземпляр класса ChatApp для работы с мессенджерами через платформу ChatApp Online.

  import { chatApp } from "@andrey4emk/npm-app-back-b24";

  Методы:

  • makeTokenChatApp() — получить токены доступа для ChatApp API.

    • Возвращает: промис с объектом:

      {
          error: false;
      }

      или при ошибке:

      {
          error: true,
          message: "Не удалось получить токен ChatApp",
          data: { /* API response */ }
      }

    • Особенности:

      • Сохраняет полученные токены в свойствах экземпляра (accessToken, refreshToken и т.д.).
      • Требует переменные окружения: CHATAPP_EMAIL, CHATAPP_PASS, CHATAPP_APP_ID.

    const result = await chatApp.makeTokenChatApp();
    if (!result.error) {
        console.log("Токены успешно получены");
    }

  • refreshTokenChatApp() — обновить токены доступа.

    • Возвращает: промис с объектом:

      {
          error: false;
      }

      или при ошибке:

      {
          error: true,
          message: "Не удалось обновить токен ChatApp",
          data: { /* API response */ }
      }

    • Алгоритм:

      1. Пытается обновить токены через API.
      2. Если обновление не удалось, автоматически получает новые токены через makeTokenChatApp().

    const result = await chatApp.refreshTokenChatApp();
    if (!result.error) {
        console.log("Токены обновлены");
    }

  • checkTokenChatApp() — проверить валидность текущего токена.

    • Возвращает: промис с объектом:

      {
          error: false,
          message: "Токен действителен" // или "Токен обновлен"
      }

      или при ошибке:

      {
          error: true,
          message: "<текст ошибки>",
          data: null
      }

    • Особенности:

      • Если токен невалидный, автоматически вызывает refreshTokenChatApp().

    const result = await chatApp.checkTokenChatApp();
    console.log(result.message);

  • getLicensesChatApp() — получить список лицензий для текущего аккаунта.

    • Возвращает: промис с объектом:

      {
          error: false,
          message: "Лицензии успешно получены",
          data: [ /* массив лицензий */ ]
      }

      или при ошибке:

      {
          error: true,
          message: "Не удалось получить лицензии ChatApp",
          data: null
      }

    • Структура лицензии в массиве:

      {
          id: 15779,
          licenseName: "*5787",
          messengers: [
              { type: "grWhatsApp", name: "[WEB] WhatsApp" }
          ]
      }

    const result = await chatApp.getLicensesChatApp();
    if (!result.error) {
        console.log("Доступные лицензии:", result.data);
    }

  • sendMessageChatApp(messengerType, messageData) — отправить сообщение через мессенджер.

    • Параметры:

      • messengerType (string) — тип мессенджера: "whatsApp" или "telegram".
      • messageData (object) — объект с данными сообщения:
        • phone (string) — номер телефона или ID чата получателя.
        • message (string) — текст сообщения.

    • Возвращает: промис с объектом:

      {
          error: false,
          message: "Сообщение успешно отправлено в ChatApp через whatsApp",
          data: null
      }

      или при ошибке:

      {
          error: true,
          message: "Ошибка при отправке сообщения в ChatApp через whatsApp",
          data: null
      }

    • Особенности:

      • Перед отправкой автоматически проверяет токен через checkTokenChatApp().
      • Использует конфигурацию из config.js для получения ID лицензий и типов мессенджеров.
      • Поддерживает отправку сообщений в WhatsApp и Telegram.

    const result = await chatApp.sendMessageChatApp("whatsApp", {
        phone: "+1234567890",
        message: "Это тестовое сообщение",
    });
    
    if (!result.error) {
        console.log(result.message);
    } else {
        console.error(result.message);
    }

    Пример отправки в Telegram:

    const result = await chatApp.sendMessageChatApp("telegram", {
        phone: "123456789", // ID чата в Telegram
        message: "Привет из приложения!",
    });

Smsgold

• smsgold.sendSms(phone, message) — отправляет SMS через сервис SMSGold.

  import { smsgold } from "@andrey4emk/npm-app-back-b24";
  
  const result = await smsgold.sendSms("+79990000000", "Готово!");
  if (!result.error) {
      console.log(result.message);
  } else {
      console.error(result.result);
  }

  Требуемые переменные окружения:

  | Переменная | Назначение | | -------------- | ---------------- | | SMSGOLD_USER | Логин в SMSGold | | SMSGOLD_PASS | Пароль в SMSGold |

  Метод возвращает объект { error, message, result }, где в result содержатся статус-код HTTP и тело ответа сервиса.

Переменные окружения

| Переменная | Назначение | | --------------------------- | ------------------------------------------------------------- | | APP_B24_DOMEN | Домен Bitrix24, для которого хранится запись авторизации в БД | | APP_B24_CLIENT_ID | Client ID для production | | APP_B24_CLIENT_SECRET | Client Secret для production | | APP_B24_CLIENT_ID_DEV | Client ID для DEV окружения | | APP_B24_CLIENT_SECRET_DEV | Client Secret для DEV окружения | | APP_ENV | Определяет окружение (DEV или production) | | APP_NAME | Название приложения (используется в описании задач) | | CHATAPP_EMAIL | Email аккаунта ChatApp | | CHATAPP_PASS | Пароль аккаунта ChatApp | | CHATAPP_APP_ID | ID приложения в ChatApp |

Пример .env:

APP_B24_DOMEN=mycompany.bitrix24.ru
APP_ENV=DEV
APP_B24_CLIENT_ID_DEV=xxx
APP_B24_CLIENT_SECRET_DEV=yyy
APP_B24_CLIENT_ID=aaa
APP_B24_CLIENT_SECRET=bbb
APP_NAME=MyApp

[email protected]
CHATAPP_PASS=your-password
CHATAPP_APP_ID=your-app-id

Скрипты

• npm run test — запуск тестов (заглушка).
• npm run pack:dry — предпросмотр содержимого пакета перед публикацией.

Лицензия

MIT © 2025 andrey4emk