Added email monitoring

docs/EMAIL_MONITORING_QUICKSTART.md

@@ -0,0 +1,172 @@
+# Email Monitoring Quick Start
+
+Get email notifications for errors and daily reports in 5 minutes.
+
+## 1. Configure SMTP Settings
+
+Edit `config/config.yaml` and add:
+
+```yaml
+email:
+  smtp:
+    host: "smtp.gmail.com"
+    port: 587
+    username: !secret EMAIL_USERNAME
+    password: !secret EMAIL_PASSWORD
+    use_tls: true
+  from_address: "noreply@yourdomain.com"
+  from_name: "AlpineBits Monitor"
+```
+
+## 2. Set Environment Variables
+
+Create a `.env` file in the project root:
+
+```bash
+EMAIL_USERNAME=your-email@gmail.com
+EMAIL_PASSWORD=your-app-password
+```
+
+> **Note:** For Gmail, use an [App Password](https://support.google.com/accounts/answer/185833), not your regular password.
+
+## 3. Enable Error Alerts
+
+In `config/config.yaml`:
+
+```yaml
+email:
+  monitoring:
+    error_alerts:
+      enabled: true
+      recipients:
+        - "alerts@yourdomain.com"
+      error_threshold: 5
+      buffer_minutes: 15
+      cooldown_minutes: 15
+```
+
+**How it works:**
+- Sends immediate alert after 5 errors
+- Otherwise sends after 15 minutes
+- Waits 15 minutes between alerts (cooldown)
+
+## 4. Enable Daily Reports (Optional)
+
+In `config/config.yaml`:
+
+```yaml
+email:
+  monitoring:
+    daily_report:
+      enabled: true
+      recipients:
+        - "admin@yourdomain.com"
+      send_time: "08:00"
+      include_stats: true
+      include_errors: true
+```
+
+## 5. Test Your Configuration
+
+Run the test script:
+
+```bash
+uv run python examples/test_email_monitoring.py
+```
+
+This will:
+- ✅ Send a test email
+- ✅ Trigger an error alert
+- ✅ Send a test daily report
+
+## What You Get
+
+### Error Alert Email
+
+When errors occur, you'll receive:
+
+```
+🚨 AlpineBits Error Alert: 5 errors (threshold exceeded)
+
+Error Count: 5
+Time Range: 14:25:00 to 14:30:00
+
+Errors:
+----------------------------------------------------------------------
+[2025-10-15 14:25:12] ERROR: Database connection timeout
+  Module: db:245
+
+[2025-10-15 14:26:34] ERROR: Failed to process reservation
+  Module: api:567
+  Exception: ValueError: Invalid hotel code
+```
+
+### Daily Report Email
+
+Every day at 8 AM, you'll receive:
+
+```
+📊 AlpineBits Daily Report - 2025-10-15
+
+Statistics:
+  total_reservations: 42
+  new_customers: 15
+  active_hotels: 4
+
+Errors (3):
+  [08:15:23] ERROR: Connection timeout
+  [12:45:10] ERROR: Invalid form data
+  [18:30:00] CRITICAL: Database unavailable
+```
+
+## Troubleshooting
+
+### No emails received?
+
+1. Check your SMTP credentials:
+   ```bash
+   echo $EMAIL_USERNAME
+   echo $EMAIL_PASSWORD
+   ```
+
+2. Check application logs for errors:
+   ```bash
+   tail -f alpinebits.log | grep -i email
+   ```
+
+3. Test SMTP connection manually:
+   ```bash
+   uv run python -c "
+   import smtplib
+   with smtplib.SMTP('smtp.gmail.com', 587) as smtp:
+       smtp.starttls()
+       smtp.login('$EMAIL_USERNAME', '$EMAIL_PASSWORD')
+       print('✅ SMTP connection successful')
+   "
+   ```
+
+### Gmail authentication failed?
+
+- Enable 2-factor authentication on your Google account
+- Generate an App Password at https://myaccount.google.com/apppasswords
+- Use the App Password (not your regular password)
+
+### Too many emails?
+
+- Increase `error_threshold` to only alert on serious issues
+- Increase `buffer_minutes` to batch more errors together
+- Increase `cooldown_minutes` to reduce alert frequency
+
+## Next Steps
+
+- Read the full [Email Monitoring Documentation](./EMAIL_MONITORING.md)
+- Configure custom statistics for daily reports
+- Set up multiple recipient groups
+- Integrate with Slack or PagerDuty (coming soon)
+
+## Support
+
+For issues or questions:
+- Check the [documentation](./EMAIL_MONITORING.md)
+- Review [test examples](../examples/test_email_monitoring.py)
+- Open an issue on GitHub