lybrus / amocrm-connector

Node.js package for amocrm api.

Node.js AmoCRM api connector

Изначально библиотека создавалась для внутреннего использования. Периодически, с внесением изменений в amocrm api, в интеграции появляются ошибки. Цель данного проекта помочь создать надежный, протестированный инструмент для работы с amocrm. 👌 Поддерживать его актуальным с помощью автотестов и сообщества. Автоматические тесты запускаются каждый день с использованием github actions.

Описание

Основная идея. Взаимодействие с api происходит с помощью двух объектов:

• Integration - объект создается на весь срок жизни приложения. Отвечает за методы интеграции в целом, а также обработку запросов со стороны amocrm.
• Client - объект для взаимодействия с конкретной установкой интеграции для аккаунта. Например, для http сервера объект создается на каждый входящий запрос.

Api чатов

По аналогии с основным api, api чатов разделено на 2 части:

• Channel - отвечает за обработку вебхуков, а также установку чата для аккаунта.
• Chat - экземпляр чата, установленный для аккаунта.

Начало работы

Установка

yarn add amocrm-connector

Пример использования

import { Integration, Client, Channel, Chat, MessageType } from 'amocrm-connector'
import token from './token.json'

;(async () => {
    const integration = new Integration({
        integrationId: 'integration id',
        secretKey: 'secret key',
        redirectUri: 'redirect uri'
    })

    const client = new Client({
        integration,
        subdomain: 'your_subdomain',
        token
    })

    const channel = new Channel({
        chatId: 'chat id',
        chatSecret: 'chat secret',
        title: 'channel title'
    })

    const chat = await channel.connect(client)

    const result = await chat.addMessage({
            date: new Date(),
            // id беседы из вашей системы
            conversationId: 'conversation-id',
            sender: {
                id: 'sender-id',
                name: 'Имя клиента',
                profile: {
                    phone: '0123456789'
                }
            },
            id: 'message-id',
            message: {
                type: MessageType.Text,
                text: 'Тест сообщения'
            }
        }
    )
})()

Другие примеры смотрите в папке examples

Документация

Integration

• new Integration(options)

Объект является экземпляром EventEmitter, события описаны здесь

Методы

• getOAuthLink
• processOAuthRedirect
• on
• addListener
• removeListener

Client

• new Client(options)

Объект является экземпляром EventEmitter, события описаны здесь

Методы

• tokenIsActual
• getToken
• request
• get
• post
• patch
• delete
• on
• addListener
• removeListener

Подсистемы

Аккаунт

Методы

• account.getAccountInfo
• account.getAmojoId

Звонки

Методы

• calls.add

Channel

• new Channel(options)

Объект является экземпляром EventEmitter, события описаны здесь

Методы

• checkSignature
• request
• post
• delete
• connect
• disconnect
• processWebhook
• on
• removeListener

Chat

• new Chat(options)

Методы

• addMessage
• deliveryStatus
• typing

Авторизация

Подробно про AmoCRM реализацию OAuth2 авторизации в официальной документации Также можете посмотреть видео от создателей другой библиотеки https://github.com/UsefulWeb/AmoCRM.

Коротко, шаги:

1. Регистрация вашей интеграции
2. Переход пользователя по ссылке выдачи доступа пользователем вашему приложению. Ссылку получить можно методом integration.getOAuthLink
3. Обработка запроса на redirect uri, для этого должен быть запущен ваш сервер. Необходимо вызвать (пример для express) integration.processOAuthRedirect(req.query).
4. integration отправит в событие setup объект client. Процедура авторизации завершена (токен уже получен) и можно пользоваться интеграцией.

Ошибки и пожелания

Если в процессе использования вы обнаружили ошибку, расскажите о ней, откройте issue с подробным описанием. Спасибо за помощь в тестировании! 👍 Если у вас есть пожелания, также открывайте issue! 👀

Планы

• Покрыть все методы api
• Реализовать унифицированный механизм работы с сущностями (Leads, Contacts, Pipelines, Companies, Catalogs, ...)
  • create(data: DTOWithId | DTOWithId[])
  • find(type: typeof DTOWithId, findOptions)
  • findOne(type: typeof DTOWithId, findOptionsOrId)
  • update(data: DTOWithId | DTOWithId[])
  • delete(data: DTOWithId | DTOWithId[])
• Валидация DTO

Разработка

Команды

• yarn build сборка проекта
• yarn serve запуск сервера для обработки запросов от amocrm. Необходима настройка окружения.
• yarn tunnel создает туннель с использованием утилиты localtunnel. Необходима настройка окружения.
• yarn cypress запуск cypress тестов, используется для проверки работы OAuth и автоматического получения токена. Необходимо:
  • Настроить окружение. Токен сохраняется в testing/token.json. Про настройку окружения ниже.
  • Запустить сервер для обработки запросов от amocrm.
  • Создать туннель с публичного адреса на ваш локальный сервер.
• yarn cypress:open запуск cypress тестов в интерактивном режиме. Необходима настройка окружения.
• yarn jest запуск jest тестов. Для работы необходимо настроить окружение, а также токен в testing/token.json. Поэтому полезно сначала запустить cypress тест. [Пока тестов нет]
• yarn test запуск cypress и jest тестов

Настройка окружения

Необходимо создать файл .evn.test с переменными окружения в корне проекта. Для удобства можно воспользоваться шаблоном .env.test.example (здесь также описано для чего нужны переменные)

cp .env.test.example .env.test

Если у вас есть вопросы касательно разработки - пишите мне в телеграм @lybrus. 👈

Любая помощь в разработке и тестировании данного проекта приветствуется! 👍