Yaltopia-Homes-TGAgent/README.md

🏠 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

   git clone <repository-url>
   cd yaltopia-telegram-bot
   

2. Install dependencies

   npm install
   

3. Configure environment variables

   cp .env.example .env
   # Edit .env with your actual values
   

4. Build the project

   npm run build
   

5. Start the bot

   npm start
   

⚙️ Configuration

Required Environment Variables

# 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

# 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

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:

   npm run get-group-info
   

5. Update your .env file with the IDs
6. Test the monitoring:

   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

   NODE_ENV=production
   BOT_VERSION=1.0.0
   

2. Configure monitoring thresholds

   MEMORY_ALERT_THRESHOLD=80
   API_FAILURE_ALERT_THRESHOLD=2
   INVALID_LOGIN_THRESHOLD=20
   

3. Set up log management

   LOG_RETENTION_DAYS=90
   LOG_CLEANUP_INTERVAL=24
   

4. Test all systems

   npm run test-config
   npm run test-monitoring
   

Docker Deployment (Optional)

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:

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]