feat: add email templates and email OTP login flow

[koistya]

This PR introduces a comprehensive email template system powered by React Email and significantly enhances the authentication experience with modern login methods including passkeys, social auth, and OTP verification. Also, fixes outdated docs mentioned in #2108.

Key Features

🎨 React Email Template System

A new @repo/email package provides beautiful, responsive transactional email templates:

• Email Verification - Welcome users with a clean verification flow
• Password Reset - Secure password recovery with time-limited links
• OTP Emails - One-time passcodes for sign-in, verification, and password reset
• BaseTemplate Component - Consistent branding across all email communications

🔐 Modern Authentication Methods

Enhanced login experience with multiple authentication options:

• Passkey Authentication - WebAuthn support with automatic conditional UI for seamless biometric login
• Social Login - Google OAuth integration with proper session management
• OTP Verification - Email-based one-time passwords for passwordless authentication
• Improved UX - Modular auth components with loading states, error handling, and graceful fallbacks

📧 Email Service Integration

Complete email sending infrastructure via Resend API:

• Type-safe email service with HTML/text rendering
• Environment-based configuration (dev/staging/prod)
• Automatic text fallback generation
• Comprehensive error handling and validation

Getting Started

Email Development

# Start email preview server (http://localhost:3001)
bun email:dev

# Build email templates for production
bun email:build

# Export static HTML templates
bun email:export

Environment Setup

Add these variables to your .env:

# Resend API Configuration
RESEND_API_KEY=re_xxxxxxxxxx
RESEND_EMAIL_FROM="Your App <noreply@example.com>"

# OAuth Providers
GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret

Using Email Templates

import { EmailVerification, renderEmailToHtml } from "@repo/email";

// Create email component
const component = EmailVerification({
  userName: "John Doe",
  verificationUrl: "https://example.com/verify?token=abc123",
  appName: "My App",
  appUrl: "https://example.com",
});

// Render to HTML
const html = await renderEmailToHtml(component);

Architecture Changes

Modular Authentication Components

The login system is now split into focused, reusable components:

• PasskeyLogin - Handles WebAuthn authentication with autofill support
• SocialLogin - Manages OAuth provider flows
• OtpVerification - Processes email OTP codes
• useLoginForm - Centralized hook for form logic and state management

Email Service Architecture

apps/email/
├── templates/         # React Email components
├── components/        # Shared UI (BaseTemplate)
├── utils/             # Rendering utilities
└── emails/            # Development preview files

API Integration

The API layer now includes:

• Full email sending capability via lib/email.ts
• Better Auth plugins for OTP and passkey support
• Environment-aware configuration
• Proper error handling and retry logic

Testing Instructions

1. Email Templates

   • Run bun email:dev to preview all templates
   • Test responsive design at different breakpoints
   • Verify dark mode compatibility

2. Authentication Flows

   • Test passkey registration and login
   • Verify Google OAuth flow
   • Test OTP email delivery and verification
   • Ensure proper session management after login

3. Error Scenarios

   • Invalid OTP codes (3 attempt limit)
   • Expired verification links (5 minute timeout)
   • Network failures during OAuth
   • Missing environment variables

Breaking Changes

None - all changes are backwards compatible. Existing password-based authentication continues to work alongside new methods.

Performance Considerations

• Email templates are pre-built at compile time
• Passkey conditional UI loads asynchronously without blocking
• OAuth redirects preserve intended destination URLs
• Session queries cached for 30 seconds with automatic refresh

Security Enhancements

• OTP codes expire after 5 minutes
• Maximum 3 failed OTP attempts before lockout
• Secure session management with httpOnly cookies
• Proper CORS and origin validation for OAuth flows

Documentation Updates

• Added comprehensive README for email package
• Updated main README with new authentication commands
• Added inline documentation for all new components
• Included usage examples and best practices

Dependencies

• @react-email/components - Email component library
• resend - Email delivery service
• better-auth/plugins/email-otp - OTP authentication
• better-auth/plugins/passkey - WebAuthn support

Deployment Notes

Before deploying:

1. Ensure Resend API key is configured in production
2. Build email templates: bun email:build
3. Update OAuth redirect URLs in Google Console
4. Configure proper CORS origins for production domain

Future Enhancements

• Add more OAuth providers (GitHub, Microsoft)
• Implement magic link authentication
• Add email template customization UI
• Support for multiple email providers
• A/B testing for email templates