ocean-cleanup/QUICK_START_EMAIL_OPTIONAL.md

Quick Start: Email-Optional Authentication

What Was Done

✅ Backend is fully configured to support users without email addresses ✅ Database schema updated (email is now optional) ✅ Notification system handles missing emails gracefully ✅ All code changes committed and pushed to git

What You Need To Do

1. Configure Clerk Dashboard (5 minutes)

Go to Clerk Dashboard and configure:

User & Authentication → Email, Phone, Username:

• ✅ Username: ON and Required
• ✅ Email: ON but Optional (not required)

User & Authentication → Sign-up:

• Required fields: ✅ Username only
• Optional fields: ✅ Email, First name, Last name

User & Authentication → Sign-in:

• Identifiers: ✅ Username (primary), ✅ Email (optional)

📖 Detailed guide: See CLERK_EMAIL_OPTIONAL_SETUP.md

2. Test It Works

Test 1: Sign up without email

1. Go to your sign-up page
2. Enter username: testuser123
3. Enter password: SecurePass123!
4. Leave email blank
5. Should succeed ✅

Test 2: Notifications work

1. Sign in as user without email
2. Create a report or event
3. Check in-app notifications → Should work ✅
4. Check email → Should not be sent (no errors) ✅

Test 3: Run automated test

cd server
npx ts-node src/scripts/testEmailOptional.ts

3. Optional: Update Frontend UI

Add to profile settings to show email status:

// Show prompt to add email
{!user.email && (
  <div className="bg-yellow-50 border border-yellow-200 rounded-lg p-4">
    <p className="text-sm text-yellow-800">
      📧 Add an email address to receive email notifications
    </p>
  </div>
)}

// Disable email notification toggle if no email
<label>
  <input
    type="checkbox"
    checked={notificationEmail}
    disabled={!user.email}
  />
  Email notifications
  {!user.email && <span className="text-sm text-gray-500 ml-2">(Add email first)</span>}
</label>

How It Works

Users Without Email

• ✅ Sign up with username + password only
• ✅ Sign in with username
• ✅ Receive in-app notifications
• ❌ Cannot receive email notifications (gracefully skipped)

Users With Email

• ✅ Sign up with username + email + password
• ✅ Sign in with username or email
• ✅ Receive both in-app and email notifications

Notification Logic

// Backend automatically filters users
const users = await prisma.user.findMany({
  where: {
    notificationEmail: true,
    email: { not: null }, // Only users with email
  },
});

// Email service validates before sending
if (!to || to.trim() === '') {
  console.log('Skipping - no email address');
  return false;
}

Files Changed

Backend:

• server/prisma/schema.prisma - Email now optional
• server/src/services/userService.ts - Handle null email
• server/src/services/notificationService.ts - Filter by email
• server/src/services/emailService.ts - Validate email
• server/src/controllers/eventController.ts - Handle null email
• server/src/controllers/reportController.ts - Handle null email

Documentation:

• EMAIL_OPTIONAL_IMPLEMENTATION.md - Technical details
• CLERK_EMAIL_OPTIONAL_SETUP.md - Clerk configuration guide
• TASK_EMAIL_OPTIONAL_COMPLETE.md - Complete summary
• QUICK_START_EMAIL_OPTIONAL.md - This file

Testing:

• server/src/scripts/testEmailOptional.ts - Test script

Troubleshooting

Issue: Users still required to enter email

• Fix: Check Clerk Dashboard → Sign-up → Email should be in "Optional fields", not "Required fields"

Issue: Email notifications failing

• Fix: Check user has email in database: SELECT email FROM users WHERE id = 'user_id'

Issue: Errors when sending notifications

• Fix: Check logs - should see "Skipping email for user X (no email address)" - this is normal

Support

• 📖 Full documentation: CLERK_EMAIL_OPTIONAL_SETUP.md
• 🧪 Test script: server/src/scripts/testEmailOptional.ts
• 📝 Implementation details: EMAIL_OPTIONAL_IMPLEMENTATION.md
• ✅ Task summary: TASK_EMAIL_OPTIONAL_COMPLETE.md

Next Steps

1. ✅ Configure Clerk Dashboard (see above)
2. ✅ Test sign-up without email
3. ✅ Test notifications work
4. ⏳ Optional: Update frontend UI
5. ⏳ Monitor user adoption

---

Status: ✅ Backend complete | ⏳ Clerk configuration needed (manual step)