# 📚 Telegram UserBot - Полная документация

## 🚀 Описание
Модульный Telegram UserBot на JavaScript с использованием библиотеки GramJS. Работает от имени вашего аккаунта и поддерживает динамическую загрузку команд.

## 📁 Структура проекта
\`\`\`
scripts/
├── telegram-userbot.js      # Основной файл бота
├── modules/                 # Папка с модулями команд
│   ├── help.js             # Справка по командам
│   ├── info.js             # Системная информация
│   ├── ping.js             # Пинг до Telegram DC2
│   ├── calc.js             # Калькулятор
│   ├── time.js             # Текущее время
│   ├── loadmod.js          # Динамическая загрузка модулей
│   └── docs.js             # Документация
├── package.json            # Зависимости проекта
└── USERBOT_DOCS.md         # Эта документация
\`\`\`

## 🛠️ Установка и настройка

### 1. Установка зависимостей
\`\`\`bash
npm install
\`\`\`

### 2. Получение API ключей
1. Перейдите на https://my.telegram.org
2. Войдите в свой аккаунт Telegram
3. Создайте новое приложение
4. Скопируйте API ID и API Hash

### 3. Настройка бота
Откройте файл `telegram-userbot.js` и замените:
- `YOUR_API_ID` на ваш API ID
- `YOUR_API_HASH` на ваш API Hash  
- `YOUR_PHONE_NUMBER` на ваш номер телефона

### 4. Запуск
\`\`\`bash
node telegram-userbot.js
\`\`\`

## 📋 Встроенные команды

| Команда | Описание | Пример использования |
|---------|----------|---------------------|
| `!help` | Показать все доступные команды | `!help` |
| `!info` | Системная информация и статистика | `!info` |
| `!ping` | Пинг до Telegram DC2 | `!ping` |
| `!calc` | Калькулятор с поддержкой скобок | `!calc 2+2*3` |
| `!time` | Текущее время и дата | `!time` |
| `!docs` | Показать документацию | `!docs` |
| `.lm` | Загрузить новый модуль | `.lm mymodule` |

## 🔧 Создание собственных модулей

### Структура модуля
\`\`\`javascript
export default {
    name: 'commandname',           // Имя команды (обязательно)
    description: 'Описание команды', // Описание (опционально)
    usage: '!commandname <args>',   // Пример использования (опционально)
    
    async execute(client, message, args, commands) {
        try {
            // Ваш код здесь
            await client.sendMessage(message.chatId, {
                message: 'Ответ команды'
            });
        } catch (error) {
            console.error('Ошибка:', error);
            await client.sendMessage(message.chatId, {
                message: '❌ Произошла ошибка'
            });
        }
    }
};
\`\`\`

### Параметры функции execute

- **client** - Экземпляр GramJS клиента для взаимодействия с Telegram API
- **message** - Объект сообщения с полями:
  - `chatId` - ID чата
  - `text` - Полный текст сообщения
  - `fromId` - ID отправителя
- **args** - Массив аргументов команды (без имени команды)
- **commands** - Map всех загруженных команд

### Полезные методы client

\`\`\`javascript
// Отправка сообщения
await client.sendMessage(chatId, { message: 'Текст' });

// Получение информации о себе
const me = await client.getMe();

// Получение списка чатов
const dialogs = await client.getDialogs();
\`\`\`

### Пример простого модуля
\`\`\`javascript
// modules/hello.js
export default {
    name: 'hello',
    description: 'Приветствие пользователя',
    usage: '!hello [имя]',
    
    async execute(client, message, args) {
        const name = args.length > 0 ? args.join(' ') : 'Мир';
        await client.sendMessage(message.chatId, {
            message: `👋 Привет, ${name}!`
        });
    }
};
\`\`\`

## ⚡ Динамическая загрузка модулей

### Загрузка нового модуля
1. Создайте файл модуля в папке `modules/`
2. Используйте команду `.lm имя_файла` для загрузки
3. Модуль будет доступен сразу без перезапуска бота

### Перезагрузка существующего модуля
Используйте `.lm имя_модуля` для перезагрузки уже существующего модуля с обновлениями.

## 🔒 Безопасность

- Userbot работает только с сообщениями от вашего аккаунта
- Не передавайте API ключи третьим лицам
- Будьте осторожны с модулями от неизвестных источников
- Регулярно проверяйте код загружаемых модулей

## 🐛 Отладка

### Логирование
Бот выводит подробные логи в консоль:
- Загрузка модулей
- Выполнение команд
- Ошибки и исключения

### Частые проблемы

1. **"require is not defined"**
   - Убедитесь, что используете `export default` вместо `module.exports`
   - Проверьте наличие `"type": "module"` в package.json

2. **"Could not find the input entity"**
   - Проблема с параметрами sendMessage
   - Убедитесь, что передаете правильный chatId

3. **Модуль не загружается**
   - Проверьте синтаксис модуля
   - Убедитесь, что файл находится в папке modules/

## 📈 Расширенные возможности

### Работа с базами данных
\`\`\`javascript
// Пример работы с JSON файлом как БД
import fs from 'fs';

const data = JSON.parse(fs.readFileSync('data.json', 'utf8'));
data.users.push(newUser);
fs.writeFileSync('data.json', JSON.stringify(data, null, 2));
\`\`\`

### HTTP запросы
\`\`\`javascript
// Пример HTTP запроса
const response = await fetch('https://api.example.com/data');
const data = await response.json();
\`\`\`

### Работа с файлами
\`\`\`javascript
import fs from 'fs';
import path from 'path';

// Чтение файла
const content = fs.readFileSync('file.txt', 'utf8');

// Запись файла
fs.writeFileSync('output.txt', 'content');
\`\`\`

## 🤝 Вклад в проект

1. Создавайте полезные модули
2. Документируйте свой код
3. Тестируйте перед публикацией
4. Следуйте стилю кодирования проекта

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

При возникновении проблем:
1. Проверьте логи в консоли
2. Убедитесь в правильности API ключей
3. Проверьте синтаксис модулей
4. Обратитесь к документации GramJS