179 lines
4.3 KiB
Markdown
179 lines
4.3 KiB
Markdown
# 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.
|