diff --git a/server/NOTIFICATION_QUICK_START.md b/server/NOTIFICATION_QUICK_START.md new file mode 100644 index 0000000..3a5cdf1 --- /dev/null +++ b/server/NOTIFICATION_QUICK_START.md @@ -0,0 +1,178 @@ +# 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 " +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.