ocean-cleanup/CLERK_EMAIL_OPTIONAL_SETUP.md

# Clerk Configuration: Email Optional Setup

## Overview

This guide explains how to configure Clerk to allow users to sign up and sign in without requiring an email address, while still supporting email as an optional field.

## Step-by-Step Configuration

### 1. Access Clerk Dashboard

1. Go to [Clerk Dashboard](https://dashboard.clerk.com)
2. Select your application
3. Navigate to **User & Authentication** in the left sidebar

### 2. Configure Authentication Methods

#### A. Username Configuration

1. Click on **Email, Phone, Username** in the left menu
2. Find the **Username** section
3. Toggle **Username** to **ON**
4. Set **Username** as **Required**
5. Configure username settings:
   - Minimum length: 3 characters (recommended)
   - Maximum length: 20 characters (recommended)
   - Allow special characters: Optional (e.g., underscores, hyphens)

#### B. Email Configuration

1. In the same **Email, Phone, Username** section
2. Find the **Email address** section
3. Toggle **Email address** to **ON**
4. Set **Email address** as **Optional** (NOT required)
5. Configure email settings:
   - Email verification: Recommended (when email is provided)
   - Allow disposable emails: Your choice

#### C. Phone Configuration (Optional)

1. If you want to support phone authentication:
2. Toggle **Phone number** to **ON**
3. Set as **Optional**
4. Configure SMS provider if needed

### 3. Configure Sign-Up Options

1. Navigate to **User & Authentication** → **Sign-up**
2. Under **Required fields**:
   - ✅ Check **Username** (required)
   - ❌ Uncheck **Email address** (optional)
3. Under **Optional fields**:
   - ✅ Check **Email address**
   - ✅ Check **First name** (recommended)
   - ✅ Check **Last name** (recommended)

### 4. Configure Sign-In Options

1. Navigate to **User & Authentication** → **Sign-in**
2. Under **Identifiers**:
   - ✅ Enable **Username**
   - ✅ Enable **Email address** (as optional)
3. Set **Username** as the primary identifier
4. Users can sign in with either username or email (if they provided one)

### 5. Configure Social Connections (Optional)

If you want to support social login:

1. Navigate to **User & Authentication** → **Social connections**
2. Enable providers (Google, Facebook, etc.)
3. Note: Social providers typically provide email, but you can configure them to not require it

### 6. Session & Security Settings

1. Navigate to **User & Authentication** → **Sessions**
2. Configure session duration as needed
3. Enable multi-session if desired

### 7. Customize Sign-Up/Sign-In UI

1. Navigate to **Customization** → **Components**
2. Customize the appearance of sign-up/sign-in forms
3. Add custom text to explain that email is optional:
   - "Email is optional but recommended for notifications"
   - "You can add your email later in profile settings"

## Testing the Configuration

### Test Sign-Up Without Email

1. Go to your application's sign-up page
2. Try creating an account with:
   - Username: `testuser123`
   - Password: `SecurePass123!`
   - Leave email blank
3. Sign-up should succeed

### Test Sign-In With Username

1. Go to your application's sign-in page
2. Sign in with:
   - Username: `testuser123`
   - Password: `SecurePass123!`
3. Sign-in should succeed

### Test Adding Email Later

1. Sign in to your application
2. Navigate to user profile settings
3. Add an email address
4. Verify the email (if verification is enabled)
5. Email notifications should now work

## Backend Configuration

The backend has been updated to handle optional emails:

### Database Schema

```prisma
model User {
  email String? @unique(map: "email") @db.VarChar(255)
  // email is now nullable
}
```

### User Creation

```typescript
// Backend automatically handles missing email
email: clerkUser.emailAddresses[0]?.emailAddress || null
```

### Notification Logic

```typescript
// Email notifications are only sent to users with:
// 1. notificationEmail = true
// 2. email IS NOT NULL
// Users without email only receive in-app notifications
```

## User Experience

### For Users Without Email

- ✅ Can sign up with just username and password
- ✅ Can sign in with username
- ✅ Receive in-app notifications
- ❌ Cannot receive email notifications
- 💡 Prompted to add email for full notification support

### For Users With Email

- ✅ Can sign up with username and email
- ✅ Can sign in with username or email
- ✅ Receive both in-app and email notifications
- ✅ Full feature access

## Notification Behavior

### In-App Notifications

- **Always work** for all users (with or without email)
- Stored in database
- Displayed in notification center
- Real-time updates

### Email Notifications

- **Only sent** to users who:
  1. Have an email address in their profile
  2. Have `notificationEmail` preference enabled
- **Gracefully skipped** for users without email
- No errors or warnings for users without email

## Profile Settings UI Recommendations

Add to your profile settings page:

```typescript
// Show email status
{!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>
)}

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

## Security Considerations

### Account Recovery

Without email, users cannot:
- Reset password via email
- Receive account security alerts via email

**Recommendations:**
1. Encourage users to add email for account security
2. Consider adding phone number as backup
3. Implement security questions as alternative
4. Show warning during sign-up about account recovery

### Rate Limiting

Without email verification:
- Implement stricter rate limiting on username sign-ups
- Monitor for abuse (multiple accounts from same IP)
- Consider CAPTCHA for sign-up

### Username Validation

Enforce strong username rules:
- Minimum 3 characters
- No offensive words (use profanity filter)
- Unique across platform
- Cannot impersonate system accounts

## Monitoring

Track these metrics:
- % of users signing up without email
- % of users adding email later
- Email notification delivery rate
- In-app notification engagement

## Troubleshooting

### Issue: Users can't sign up without email

**Solution**: Check Clerk Dashboard → Sign-up → Ensure email is NOT in "Required fields"

### Issue: Email notifications failing

**Solution**: Check that:
1. User has email in database
2. User has `notificationEmail = true`
3. Email service is configured correctly

### Issue: Clerk components still require email

**Solution**: 
1. Clear browser cache
2. Update `@clerk/clerk-react` to latest version
3. Verify Clerk Dashboard settings saved correctly

## Migration for Existing Users

If you have existing users with temporary emails (`@temp.com`):

```sql
-- Find users with temporary emails
SELECT id, email, username FROM users WHERE email LIKE '%@temp.com';

-- Option 1: Set to NULL
UPDATE users SET email = NULL WHERE email LIKE '%@temp.com';

-- Option 2: Keep as-is (they can update in profile)
```

## Support

For issues with Clerk configuration:
- [Clerk Documentation](https://clerk.com/docs)
- [Clerk Support](https://clerk.com/support)
- [Clerk Discord Community](https://clerk.com/discord)