# 🏠 Yaltipia Telegram Bot

A powerful, production-ready Telegram bot for real estate property notifications. Users can create custom property alerts and receive instant notifications when matching properties become available.

[![Node.js](https://img.shields.io/badge/Node.js-16%2B-green.svg)](https://nodejs.org/)
[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Production Ready](https://img.shields.io/badge/Production-Ready-brightgreen.svg)](SECURITY_DEPLOYMENT_CHECKLIST.md)

## 🚀 **Features**

### **🔔 Smart Notifications**
- **Custom Property Alerts** - Users set criteria (type, location, price range)
- **Automatic Matching** - Bot finds properties matching user preferences
- **Real-time Notifications** - Instant alerts via Telegram (with webhook support)
- **Flexible Filtering** - By property type, location, house type, and price

### **👤 User Management**
- **Secure Authentication** - Phone-based registration and login
- **Session Management** - Persistent user sessions with token-based auth
- **Notification Management** - Create, view, edit, and delete notifications
- **User-friendly Interface** - Intuitive inline keyboards and menus

### **📊 Admin Monitoring**
- **Real-time Health Monitoring** - System health checks every 30 minutes
- **Error Reporting** - Automatic error alerts to admin chat
- **Failed Login Tracking** - Security alerts for failed authentication attempts
- **Daily Reports** - Comprehensive system statistics
- **Performance Metrics** - Memory usage, uptime, and error rates

### **🔒 Security & Performance**
- **Rate Limiting** - Protection against spam and abuse
- **Input Validation** - Secure handling of user inputs
- **Error Handling** - Comprehensive error management
- **Security Headers** - Protection against common web attacks
- **Production Hardening** - Security best practices implemented

## 📋 **Quick Start**

### **Prerequisites**
- Node.js 16+ and npm
- Telegram Bot Token (from [@BotFather](https://t.me/botfather))
- Backend API for property data
- Admin Telegram chat for monitoring

### **Installation**

```bash
# Clone the repository
git clone <your-repository-url>
cd yaltipia-telegram-bot

# Install dependencies
npm install

# Create environment file
cp .env.example .env

# Configure your environment variables
nano .env
```

### **Configuration**

Edit `.env` with your settings:

```env
# Bot Configuration
TELEGRAM_BOT_TOKEN=your_bot_token_here
API_BASE_URL=https://your-api.com/api
WEBSITE_URL=https://yaltipia.com

# Notification System
NOTIFICATION_MODE=optimized
NOTIFICATION_CHECK_INTERVAL_HOURS=6
SEND_NO_MATCH_NOTIFICATIONS=false

# Admin Monitoring
ADMIN_CHAT_IDS=your_admin_chat_id
MONITORING_TOPIC_ID=your_topic_id
```

### **Start the Bot**

```bash
# Development
npm run dev

# Production
npm start

# With PM2 (recommended for production)
pm2 start src/bot.js --name "yaltipia-bot"
```

## 🏗️ **Architecture**

### **System Components**

```
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Telegram      │    │   Yaltipia Bot   │    │   Backend API   │
│   Users         │◄──►│                  │◄──►│   (Property     │
│                 │    │   • Auth         │    │    Data)        │
└─────────────────┘    │   • Notifications│    └─────────────────┘
                       │   • Monitoring   │              │
┌─────────────────┐    │   • Webhooks     │              │
│   Admin Chat    │◄───┤                  │              │
│   (Monitoring)  │    └──────────────────┘              │
└─────────────────┘             │                        │
                                │                        │
                       ┌──────────────────┐              │
                       │   Webhook Server │◄─────────────┘
                       │   (Real-time)    │
                       └──────────────────┘
```

### **Notification Modes**

| Mode | Description | Use Case |
|------|-------------|----------|
| **optimized** | Polls API every 6 hours | Current setup (no backend changes needed) |
| **full** | Real-time webhooks + polling backup | Future upgrade (requires backend integration) |

## 📖 **User Guide**

### **For End Users**

1. **Start the bot**: Send `/start` to the bot
2. **Register/Login**: Provide phone number and password
3. **Create notifications**: Use "🔔 Create Notification" button
4. **Set preferences**: Choose property type, location, price range
5. **Receive alerts**: Get notified when matching properties are found

### **Supported Property Criteria**
- **Property Type**: Rent, Sale
- **Location**: Any subcity (Bole, Kirkos, Addis Ketema, etc.)
- **House Type**: Apartment, Villa, Studio, Condominium, etc.
- **Price Range**: Minimum and maximum price limits

## 🛠️ **Development**

### **Project Structure**

```
yaltipia-telegram-bot/
├── src/
│   ├── bot.js                 # Main bot application
│   ├── api.js                 # Backend API client
│   ├── features/              # Bot features (auth, notifications, menu)
│   ├── services/              # Notification services
│   ├── utils/                 # Utilities (monitoring, error handling)
│   └── webhook/               # Webhook handlers
├── scripts/                   # Utility scripts
├── docs/                      # Documentation
├── .env.example              # Environment template
└── package.json              # Dependencies and scripts
```

### **Available Scripts**

```bash
npm run dev          # Start in development mode with nodemon
npm start            # Start in production mode
npm test             # Run tests (if available)
```

### **Environment Variables**

| Variable | Description | Default |
|----------|-------------|---------|
| `TELEGRAM_BOT_TOKEN` | Bot token from BotFather | Required |
| `API_BASE_URL` | Backend API endpoint | Required |
| `NOTIFICATION_MODE` | Notification system mode | `optimized` |
| `NOTIFICATION_CHECK_INTERVAL_HOURS` | Check frequency | `6` |
| `ADMIN_CHAT_IDS` | Admin chat IDs (comma-separated) | Required |
| `HEALTH_CHECK_INTERVAL_MINUTES` | Health check frequency | `30` |

## 🚀 **Deployment**

### **Quick Deployment**

For detailed deployment instructions, see [SECURITY_DEPLOYMENT_CHECKLIST.md](SECURITY_DEPLOYMENT_CHECKLIST.md)

```bash
# 1. Server setup
sudo npm install -g pm2

# 2. Clone and install
git clone <repo> && cd yaltipia-telegram-bot
npm ci --only=production

# 3. Configure environment
cp .env.production .env
# Edit .env with production values

# 4. Start application
pm2 start src/bot.js --name "yaltipia-bot"
pm2 save && pm2 startup
```

### **Docker Deployment**

```bash
# Build image
docker build -t yaltipia-bot .

# Run container
docker run -d \
  --name yaltipia-bot \
  --env-file .env.production \
  -p 3001:3001 \
  yaltipia-bot
```

### **Health Checks**

| Endpoint | Purpose |
|----------|---------|
| `GET /status` | Application health status |
| `GET /webhook/health` | Webhook service health |

## 📊 **Monitoring**

### **Built-in Monitoring Features**

- **System Health**: Memory usage, error rates, uptime tracking
- **User Activity**: Login attempts, notification creation, message processing
- **Error Tracking**: Automatic error reporting with stack traces
- **Performance Metrics**: Response times, API call success rates

### **Admin Notifications**

The bot automatically sends alerts to admin chat for:
- 🚨 **Critical system issues** (high error rates, memory problems)
- 🔐 **Security events** (failed login attempts, suspicious activity)
- 📊 **Daily reports** (system statistics and health summary)
- ⚠️ **Application errors** (with detailed error information)

## 🔗 **Webhook Integration**

### **Current Setup**
- **Mode**: Optimized polling (checks every 6 hours)
- **Backend Required**: No webhook integration needed

### **Future Enhancement**
- **Mode**: Real-time webhooks (instant notifications)
- **Backend Required**: Send HTTP POST to bot when properties are added/updated

For webhook integration guide, see [docs/WEBHOOK_INTEGRATION_GUIDE.md](docs/WEBHOOK_INTEGRATION_GUIDE.md)

## 🔒 **Security**

### **Security Features**
- ✅ **Rate limiting** (100 requests/minute per IP)
- ✅ **Input validation** and sanitization
- ✅ **Secure authentication** with token management
- ✅ **Error handling** without information leakage
- ✅ **Security headers** for webhook endpoints
- ✅ **Environment variable protection**

### **Security Best Practices**
- Never commit `.env` files to version control
- Use strong, unique bot tokens for production
- Regularly rotate authentication tokens
- Monitor admin chat for security alerts
- Keep dependencies updated

## 📚 **Documentation**

| Document | Description |
|----------|-------------|
| [SECURITY_DEPLOYMENT_CHECKLIST.md](SECURITY_DEPLOYMENT_CHECKLIST.md) | Complete deployment guide for DevOps teams |
| [docs/WEBHOOK_INTEGRATION_GUIDE.md](docs/WEBHOOK_INTEGRATION_GUIDE.md) | Future webhook integration instructions |
| [docs/CONFIGURATION_GUIDE.md](docs/CONFIGURATION_GUIDE.md) | Detailed configuration options |
| [docs/MONITORING_SYSTEM.md](docs/MONITORING_SYSTEM.md) | Monitoring and alerting setup |

## 🤝 **Contributing**

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

### **Development Guidelines**
- Follow existing code style and patterns
- Add appropriate error handling
- Update documentation for new features
- Test thoroughly before submitting PR

## 📝 **License**

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🆘 **Support**

### **Getting Help**
- 📖 Check the [documentation](docs/) first
- 🐛 Report bugs via GitHub Issues
- 💬 Contact the development team
- 📧 Email: [your-support-email]

### **Common Issues**
- **Bot not responding**: Check bot token and network connectivity
- **API errors**: Verify API_BASE_URL and backend availability
- **No notifications**: Ensure users are logged in and have active notifications
- **Memory issues**: Monitor system resources and restart if needed

## 🎯 **Roadmap**

### **Current Version (v1.0)**
- ✅ Basic notification system with polling
- ✅ User authentication and management
- ✅ Admin monitoring and alerts
- ✅ Security hardening

### **Future Enhancements**
- 🔄 **Real-time webhooks** (when backend supports it)
- 📱 **Mobile app integration** 
- 🔍 **Advanced search filters**
- 📊 **Analytics dashboard**
- 🌐 **Multi-language support**

---

## 🏆 **Production Ready**

This bot is **production-ready** with:
- ✅ **Comprehensive security** measures
- ✅ **Robust error handling** and monitoring
- ✅ **Scalable architecture** design
- ✅ **Complete documentation** for deployment
- ✅ **DevOps-friendly** configuration

**Deploy with confidence!** 🚀

---

<div align="center">

**Built with ❤️ for Yaltipia**

[🏠 Website](https://yaltipia.com) • [📱 Telegram Bot](https://t.me/your_bot) • [📧 Support](mailto:support@yaltipia.com)

</div>