# Notifications Feature Capsule

## Quick Summary

Email and toast notification system for maintenance due/overdue items and expiring documents. Uses Resend for email delivery and provides admin-editable email templates. User-scoped data with per-entry email notification toggles.

## API Endpoints

### User Endpoints
- `GET /api/notifications/summary` - Get notification summary (counts for login toast)
- `GET /api/notifications/maintenance` - Get due/overdue maintenance items
- `GET /api/notifications/documents` - Get expiring/expired documents

### Admin Endpoints
- `GET /api/admin/email-templates` - List all email templates
- `GET /api/admin/email-templates/:key` - Get single email template
- `PUT /api/admin/email-templates/:key` - Update email template
- `POST /api/admin/email-templates/:key/preview` - Preview template with sample variables

## Structure

- **api/** - HTTP endpoints, routes, validators
- **domain/** - Business logic, services, types
- **data/** - Repository, database queries
- **migrations/** - Feature-specific schema
- **tests/** - All feature tests

## Email Templates

### Predefined Templates (4 total)
1. **maintenance_due_soon** - Sent when maintenance is due within 30 days or 500 miles
2. **maintenance_overdue** - Sent when maintenance is past due
3. **document_expiring** - Sent when document expires within 30 days
4. **document_expired** - Sent when document has expired

### Template Variables
Templates use `{{variableName}}` syntax for variable substitution.

**Maintenance templates:**
- userName, vehicleName, category, subtypes, dueDate, dueMileage

**Document templates:**
- userName, vehicleName, documentType, documentTitle, expirationDate

## Dependencies

### Internal
- `core/auth` - Authentication plugin
- `core/logging` - Structured logging
- `core/config` - Database pool and secrets

### External
- `resend` - Email delivery service

### Database
- Tables: `email_templates`, `notification_logs`
- FK: `maintenance_schedules(email_notifications)`, `documents(email_notifications)`

## Business Rules

### Notification Triggers

**Maintenance Due Soon:**
- Next due date within 30 days OR
- Next due mileage within 500 miles of current odometer

**Maintenance Overdue:**
- Next due date in the past OR
- Current odometer exceeds next due mileage

**Document Expiring Soon:**
- Expiration date within 30 days

**Document Expired:**
- Expiration date in the past

### Email Notification Toggle
- Per-entry toggle on `maintenance_schedules.email_notifications`
- Per-entry toggle on `documents.email_notifications`
- Default: `false` (opt-in)

### Login Toast Summary
- Shows count of maintenance items requiring attention
- Shows count of documents requiring attention
- Displayed once per session on successful login

## Security Requirements

1. All queries user-scoped (filter by user_id)
2. Prepared statements (never concatenate SQL)
3. User endpoints require JWT authentication
4. Admin endpoints require admin role
5. Template editing restricted to admins
6. Email logs track all sent notifications

## Email Service Configuration

### Environment Variables
- `RESEND_API_KEY` - Resend API key (required, stored in secrets)
- `FROM_EMAIL` - Sender email address (default: noreply@motovaultpro.com)

### Email Delivery
- Uses Resend API for transactional emails
- Converts plain text templates to HTML with line breaks
- Tracks all sent emails in `notification_logs` table
- Logs failures with error messages for debugging

## Testing

```bash
# Run feature tests
npm test -- features/notifications
```

## Future Enhancements

- Batch notification processing (scheduled job)
- Notification frequency controls (daily digest, etc.)
- User preference for notification types
- SMS notifications (via Twilio or similar)
- Push notifications (via FCM or similar)