# @mobilon-dev/amotop

[![npm version](https://badge.fury.io/js/%40mobilon-dev%2Famotop.svg)](https://badge.fury.io/js/%40mobilon-dev%2Famotop)
[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)

Полнофункциональный TypeScript клиент для работы с amoCRM API, включающий поддержку основного API, Chat API, File API и OAuth 2.0 аутентификации.

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

- [📖 Полная документация](https://mobilon-dev.github.io/amotop/)
- [💡 Примеры использования](samples/index.md)
- [🔗 Репозиторий](https://github.com/mobilon-dev/amotop)

## 🎥 Видеоуроки

- [🎬 Знакомство с @mobilon-dev/amotop](https://youtu.be/zRlO7e41bwg)
- [🔐 amoCRM OAuth 2.0](https://youtu.be/CxQcB5AsyHI)
- [💬 amoCRM Chat API](https://youtu.be/f31UVtn7EJI)
- [📁 amoCRM File API](https://youtu.be/3DLbkBt7kHw)

## ✨ Особенности

- **🚀 Простота использования** - Интуитивно понятный API с подробным логированием
- **🔧 TypeScript поддержка** - Полная типизация для лучшего DX
- **📊 Подробное логирование** - Все запросы и ответы логируются для отладки
- **💬 Chat API интеграция** - Работа с чатами amoCRM
- **📁 File API поддержка** - Загрузка и управление файлами
- **🔐 OAuth 2.0** - Безопасная аутентификация
- **📝 Webhook поддержка** - Работа с вебхуками amoCRM

## 🛠 Установка

```bash
npm install @mobilon-dev/amotop
```

## 🚀 Быстрый старт

### 1. Настройка конфигурации

Создайте файл конфигурации `config.js`:

```javascript
module.exports = {
  domain: 'your-domain.amocrm.ru',
  accessToken: 'your-access-token',
  scopeId: 'your-scope-id',
  channelSecret: 'your-channel-secret',
  debug: true
};
```

### 2. Базовое использование

```javascript
const { AmoApiClient, AmoJoScopeClient } = require('@mobilon-dev/amotop');

const config = require('./config');

// Инициализация клиентов
const amoApiClient = new AmoApiClient(config.domain, config.accessToken, { debug: config.debug });
const amoJoScopeClient = new AmoJoScopeClient({
  scopeId: config.scopeId, 
  channelSecret: config.channelSecret, 
  debug: config.debug
});

// Получение сделок
const leads = await amoApiClient.getLeads({ limit: 20 });

// Отправка сообщения в чат
const message = {
  text: 'Привет! Это тестовое сообщение.',
  source: 'bot'
};
const response = await amoJoScopeClient.sendMessage(message);
```

## 🏗 Архитектура

![Архитектура проекта](images/scheme.jpg)

### Основные компоненты

| Компонент | Назначение | Конфигурация |
|-----------|------------|--------------|
| **AmoService** | Обмен токенов OAuth 2.0 | `domain` |
| **AmoApiClient** | Основной API amoCRM | `domain`, `accessToken` |
| **AmoFileClient** | File API amoCRM | `accessToken` |
| **AmoJoChannelClient** | Управление каналами Chat API | `channelId`, `channelSecret` |
| **AmoJoScopeClient** | Работа с подключениями чатов | `scopeId`, `channelSecret` |

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

### Работа со сделками

```javascript
// Добавление сделки
const lead = {
  name: 'Продать слона',
  price: 1000,
  ...amoApiClient.getPipelineLeadPayload(7183562, 60002878)
};
const newLead = await amoApiClient.addLead(lead);

// Получение сделок с фильтрацией
const leads = await amoApiClient.getLeads({
  limit: 50,
  filter: {
    responsible_user_id: [12345]
  }
});
```

### Работа с контактами

```javascript
// Добавление контакта
const contact = {
  name: 'Иван Иванов',
  phone: '+79001234567',
  email: 'ivan@example.com'
};
const newContact = await amoApiClient.addContact(contact);

// Получение всех контактов
const contacts = await amoApiClient.getAllContacts();
```

### Работа с чатами

```javascript
// Отправка текстового сообщения
await amoJoScopeClient.sendTextMessage({
  text: 'Привет! Чем могу помочь?',
  source: 'bot'
});

// Отправка изображения
await amoJoScopeClient.sendImageMessage({
  image: 'https://example.com/image.jpg',
  caption: 'Описание изображения',
  source: 'bot'
});
```

### Работа с файлами

```javascript
const { AmoFileClient } = require('@mobilon-dev/amotop');

const fileClient = new AmoFileClient(accessToken, { debug: true });

// Загрузка файла
const uploadResult = await fileClient.uploadFile({
  file: './document.pdf',
  name: 'document.pdf'
});

// Привязка файла к сделке
await amoApiClient.attachFileToLead(leadId, uploadResult.id);
```

## 🔧 Настройка OAuth 2.0

```javascript
const { AmoService } = require('@mobilon-dev/amotop');

const amoService = new AmoService('your-domain.amocrm.ru');

// Получение URL для авторизации
const authUrl = amoService.getAuthUrl({
  clientId: 'your-client-id',
  redirectUri: 'your-redirect-uri',
  state: 'random-state'
});

// Обмен кода на токен
const tokens = await amoService.exchangeCode({
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  code: 'authorization-code',
  redirectUri: 'your-redirect-uri'
});
```

## 📊 Логирование

Библиотека автоматически логирует все запросы и ответы при включенном режиме debug:

```
[AmoApiClient][Request] GET https://domain.amocrm.ru/api/v4/leads?page=1&limit=20
[AmoApiClient][Response] GET https://domain.amocrm.ru/api/v4/leads?page=1&limit=20 200:OK
```

## 🔗 Полезные ссылки

- [📖 amoCRM API документация](https://www.amocrm.ru/developers/content/crm_platform/api-reference)
- [💬 Chat API документация](https://www.amocrm.ru/developers/content/chats/chat-api-reference)
- [📁 Files API документация](https://www.amocrm.ru/developers/content/files/files-capabilities)

## 🤝 Поддержка

Если у вас есть вопросы или предложения:

1. Создайте [Issue](https://github.com/mobilon-dev/amotop/issues) в репозитории
2. Изучите [примеры](samples/index.md) для решения типичных задач
3. Обратитесь к [документации](https://mobilon-dev.github.io/amotop/)

## 📄 Лицензия

ISC License - см. файл [LICENSE](LICENSE) для подробностей.

---

**Создано с ❤️ для упрощения работы с amoCRM API**