158 lines
4.3 KiB
Markdown
158 lines
4.3 KiB
Markdown
# 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](https://dashboard.clerk.com) 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**
|
|
```bash
|
|
cd server
|
|
npx ts-node src/scripts/testEmailOptional.ts
|
|
```
|
|
|
|
### 3. Optional: Update Frontend UI
|
|
|
|
Add to profile settings to show email status:
|
|
|
|
```typescript
|
|
// 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
|
|
```typescript
|
|
// 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)
|