# Notification System - Quick Start Guide

## 🚀 Get Started in 3 Steps

### Step 1: Authorize Your Email in Mailgun

1. Go to https://app.mailgun.com/
2. Navigate to: **Sending** → **Domains** → `sandbox1835a1917b07443f8c1ca858689c42ea.mailgun.org`
3. Scroll to **"Authorized Recipients"**
4. Add your email: `psbailey31@gmail.com`
5. Click **"Invite"**
6. Check your email and click the confirmation link

### Step 2: Test Email Delivery

```bash
cd server
npx tsx src/scripts/testEmail.ts
```

Expected output:
```
✅ Test email sent successfully to psbailey31@gmail.com
✅ Notification email sent successfully to psbailey31@gmail.com
```

Check your inbox (and spam folder)!

### Step 3: Test Full Notification System

```bash
cd server
npx tsx src/scripts/testNotifications.ts
```

This tests:
- ✅ Email service connection
- ✅ Notification creation
- ✅ Area-of-interest matching
- ✅ Mark as read functionality
- ✅ Event reminders

## 📧 Configuration

Already configured in `.env`:

```env
MAILGUN_API_KEY="dd27be7a81dd7b0980ada31fec9a9bd9-e80d8b76-fd80c63b"
MAILGUN_DOMAIN="sandbox1835a1917b07443f8c1ca858689c42ea.mailgun.org"
FROM_EMAIL="Beach Litter Platform <noreply@sandbox1835a1917b07443f8c1ca858689c42ea.mailgun.org>"
TEST_EMAIL="psbailey31@gmail.com"
```

## 🔔 How It Works

### For Users

1. **Set Areas of Interest**:
   - Go to Profile → Notification Settings
   - Add locations with radius (1-50km)
   - Enable email/in-app notifications

2. **Receive Notifications**:
   - Bell icon in header shows unread count
   - Click to see notification list
   - Click notification to view details
   - Automatically marked as read

3. **Email Notifications**:
   - Receive formatted HTML emails
   - Click links to view details
   - Manage preferences in profile

### For Developers

1. **Automatic Triggers**:
   ```typescript
   // Report created → notifications sent
   await reportService.createReport(data);
   // Automatically triggers notificationService.notifyNewReport()
   
   // Event created → notifications sent
   await eventService.createEvent(data);
   // Automatically triggers notificationService.notifyNewEvent()
   ```

2. **Manual Notifications**:
   ```typescript
   import { notificationService } from './services/notificationService';
   
   await notificationService.createNotification({
     userId: 'user-id',
     type: 'new_report',
     title: 'New Report',
     message: 'A new report was created',
     relatedId: 'report-id',
     relatedType: 'report',
     latitude: 53.3498,
     longitude: -6.2603,
   });
   ```

3. **Scheduled Jobs**:
   - Event reminders: Every 10 minutes
   - Cleanup old notifications: Daily at 2 AM

## 🎯 API Endpoints

All require authentication:

```bash
# Get notifications
GET /api/notifications?unreadOnly=true

# Get unread count
GET /api/notifications/unread-count

# Mark as read
PATCH /api/notifications/:id/read

# Mark all as read
PATCH /api/notifications/read-all
```

## 🐛 Troubleshooting

### "Forbidden" Error

**Problem**: Email not authorized in Mailgun sandbox

**Solution**: 
1. Add email to authorized recipients
2. Confirm authorization email
3. Wait 2-3 minutes
4. Try again

### Notifications Not Appearing

**Problem**: User has no areas of interest

**Solution**:
1. Go to Profile → Notification Settings
2. Add at least one area of interest
3. Create a report/event in that area
4. Check notification bell

### Emails Going to Spam

**Problem**: Sandbox domain has low reputation

**Solution**:
1. Check spam folder
2. Mark as "Not Spam"
3. For production, use custom domain

## 📚 Full Documentation

- **Implementation Guide**: `NOTIFICATION_SYSTEM_IMPLEMENTATION.md`
- **Mailgun Setup**: `MAILGUN_SETUP.md`
- **Task Summary**: `TASK_33_NOTIFICATION_SYSTEM_COMPLETE.md`

## ✅ Checklist

- [ ] Authorized email in Mailgun dashboard
- [ ] Confirmed authorization email
- [ ] Ran test email script successfully
- [ ] Ran full notification test successfully
- [ ] Checked inbox for test emails
- [ ] Tested notification bell in UI
- [ ] Set up areas of interest for test user
- [ ] Created test report/event
- [ ] Verified notification received

## 🎉 You're Done!

The notification system is ready to use. Users will now receive notifications about reports and events in their areas of interest!

For production deployment, see `MAILGUN_SETUP.md` for custom domain setup.