219 lines
5.0 KiB
Markdown
219 lines
5.0 KiB
Markdown
# 🏠 Yaltopia Telegram Bot
|
|
|
|
A comprehensive Telegram bot for property management with advanced monitoring and security features.
|
|
|
|
## 🚀 Features
|
|
|
|
- **User Authentication** - Phone-based registration and login
|
|
- **Property Management** - Browse, add, and manage property listings
|
|
- **Role-Based Access** - AGENT role restrictions
|
|
- **Advanced Monitoring** - Topic-based alerts and health checks
|
|
- **Configurable Logging** - Flexible log retention and cleanup
|
|
- **Security Features** - Rate limiting, input validation, invalid login tracking
|
|
|
|
## 📋 Prerequisites
|
|
|
|
- Node.js 16+
|
|
- npm or yarn
|
|
- Telegram Bot Token
|
|
- API Backend Service
|
|
|
|
## 🛠️ Installation
|
|
|
|
1. **Clone the repository**
|
|
```bash
|
|
git clone <repository-url>
|
|
cd yaltopia-telegram-bot
|
|
```
|
|
|
|
2. **Install dependencies**
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
3. **Configure environment variables**
|
|
```bash
|
|
cp .env.example .env
|
|
# Edit .env with your actual values
|
|
```
|
|
|
|
4. **Build the project**
|
|
```bash
|
|
npm run build
|
|
```
|
|
|
|
5. **Start the bot**
|
|
```bash
|
|
npm start
|
|
```
|
|
|
|
## ⚙️ Configuration
|
|
|
|
### Required Environment Variables
|
|
|
|
```bash
|
|
# Bot Configuration
|
|
TELEGRAM_BOT_TOKEN=your_bot_token_here
|
|
API_BASE_URL=http://localhost:3000/api
|
|
|
|
# Monitoring (Optional but Recommended)
|
|
MONITORING_SUPERGROUP_ID=your_supergroup_id
|
|
TOPIC_ALL_MONITORING=your_main_topic_id
|
|
ADMIN_CHAT_IDS=admin_chat_id1,admin_chat_id2
|
|
```
|
|
|
|
### Optional Configuration
|
|
|
|
```bash
|
|
# Schedule Configuration
|
|
DAILY_REPORT_TIME=09:00 # UTC time for daily reports
|
|
HEALTH_CHECK_INTERVAL=5 # Minutes between health checks
|
|
LOG_CLEANUP_INTERVAL=24 # Hours between log cleanup
|
|
LOG_RETENTION_DAYS=30 # Days to keep logs
|
|
|
|
# Alert Thresholds
|
|
MEMORY_ALERT_THRESHOLD=90 # Memory usage percentage
|
|
API_FAILURE_ALERT_THRESHOLD=5 # API failure rate percentage
|
|
INVALID_LOGIN_THRESHOLD=50 # Invalid logins per hour
|
|
```
|
|
|
|
## 🔧 Development
|
|
|
|
### Available Scripts
|
|
|
|
```bash
|
|
npm run dev # Start in development mode
|
|
npm run build # Build for production
|
|
npm run watch # Watch mode for development
|
|
npm run test-config # Test configuration
|
|
npm run test-monitoring # Test monitoring system
|
|
```
|
|
|
|
### Setting Up Monitoring
|
|
|
|
1. **Create a Telegram supergroup**
|
|
2. **Add your bot as admin**
|
|
3. **Enable topics in group settings**
|
|
4. **Get group and topic IDs:**
|
|
```bash
|
|
npm run get-group-info
|
|
```
|
|
5. **Update your .env file with the IDs**
|
|
6. **Test the monitoring:**
|
|
```bash
|
|
npm run test-monitoring
|
|
```
|
|
|
|
## 📊 Monitoring Features
|
|
|
|
### Topic-Based Alerts
|
|
- **Main Monitoring Topic** - Receives all alerts
|
|
- **Specific Topics** - Optional categorized alerts
|
|
- **Health Checks** - Automated system monitoring
|
|
- **Daily Reports** - Scheduled system summaries
|
|
|
|
### Alert Types
|
|
- 🚀 **Startup Alerts** - Bot initialization
|
|
- 💥 **Error Alerts** - System errors and exceptions
|
|
- 🔥 **Backend Failures** - API and service issues
|
|
- 🏥 **Health Alerts** - Memory, performance issues
|
|
- 🔐 **Security Alerts** - Invalid login attempts
|
|
- 📊 **Daily Reports** - System statistics
|
|
|
|
## 🔒 Security Features
|
|
|
|
- **Environment Variable Protection** - No hardcoded secrets
|
|
- **Role-Based Access Control** - AGENT-only access
|
|
- **Rate Limiting** - Prevent abuse
|
|
- **Input Validation** - Secure data handling
|
|
- **Login Attempt Monitoring** - Brute force detection
|
|
- **Secure Logging** - No sensitive data in logs
|
|
|
|
## 🚀 Deployment
|
|
|
|
### Production Checklist
|
|
|
|
1. **Set production environment variables**
|
|
```bash
|
|
NODE_ENV=production
|
|
BOT_VERSION=1.0.0
|
|
```
|
|
|
|
2. **Configure monitoring thresholds**
|
|
```bash
|
|
MEMORY_ALERT_THRESHOLD=80
|
|
API_FAILURE_ALERT_THRESHOLD=2
|
|
INVALID_LOGIN_THRESHOLD=20
|
|
```
|
|
|
|
3. **Set up log management**
|
|
```bash
|
|
LOG_RETENTION_DAYS=90
|
|
LOG_CLEANUP_INTERVAL=24
|
|
```
|
|
|
|
4. **Test all systems**
|
|
```bash
|
|
npm run test-config
|
|
npm run test-monitoring
|
|
```
|
|
|
|
### Docker Deployment (Optional)
|
|
|
|
```dockerfile
|
|
FROM node:16-alpine
|
|
WORKDIR /app
|
|
COPY package*.json ./
|
|
RUN npm ci --only=production
|
|
COPY dist ./dist
|
|
CMD ["npm", "start"]
|
|
```
|
|
|
|
## 📚 API Integration
|
|
|
|
The bot integrates with a backend API for:
|
|
- User authentication
|
|
- Property management
|
|
- Data persistence
|
|
|
|
Ensure your API backend is running and accessible at the configured `API_BASE_URL`.
|
|
|
|
## 🐛 Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
1. **Bot not responding**
|
|
- Check bot token validity
|
|
- Verify API backend is running
|
|
- Check network connectivity
|
|
|
|
2. **Monitoring not working**
|
|
- Verify supergroup configuration
|
|
- Check topic IDs are correct
|
|
- Ensure bot has admin permissions
|
|
|
|
3. **Authentication failures**
|
|
- Check API backend connectivity
|
|
- Verify user roles in backend
|
|
- Check input validation rules
|
|
|
|
### Debug Mode
|
|
|
|
Enable debug logging:
|
|
```bash
|
|
NODE_ENV=development
|
|
```
|
|
|
|
Check logs in `./logs/` directory for detailed information.
|
|
|
|
## 📄 License
|
|
|
|
[Add your license information here]
|
|
|
|
## 🤝 Contributing
|
|
|
|
[Add contribution guidelines here]
|
|
|
|
## 📞 Support
|
|
|
|
[Add support contact information here] |