shipd 0.1.3 → 0.2.0

package/features/email/README.md

@@ -0,0 +1,341 @@
+# Email Module - Integration Guide
+
+**Module Version:** 1.0.0  
+**Last Updated:** 2025-12-22  
+**Standalone:** ✅ Yes (can work independently)
+
+---
+
+## Overview
+
+This module adds email sending functionality using Resend and React Email. It includes pre-built email templates for common use cases like welcome emails, password resets, subscription confirmations, and payment failures.
+
+**Key Features:**
+- Resend integration for email delivery
+- React Email templates (beautiful, responsive emails)
+- Pre-built email templates:
+  - Welcome email
+  - Password reset email
+  - Subscription confirmation email
+  - Payment failed email
+- Graceful fallback (logs to console if not configured)
+- Type-safe email sending
+
+---
+
+## Files Added
+
+### Utilities/Libraries
+- `lib/email.ts` - Email sending utilities and helper functions
+
+### Email Templates
+- `emails/welcome.tsx` - Welcome email template
+- `emails/password-reset.tsx` - Password reset email template
+- `emails/subscription-confirmation.tsx` - Subscription confirmation template
+- `emails/payment-failed.tsx` - Payment failed notification template
+- `emails/components/layout.tsx` - Shared email layout component
+
+---
+
+## Dependencies
+
+### Package Dependencies
+The following packages will be added to `package.json`:
+- `resend@^6.6.0` - Resend email service SDK
+- `@react-email/components@^1.0.2` - React Email component library
+- `@react-email/render@^2.0.0` - React Email rendering utilities
+
+### Required Modules
+- None - Email module is standalone
+
+### Optional Integration
+- **Auth Module** - Uses email for password resets (works without it, but emails won't send)
+- **Payments Module** - Uses email for subscription confirmations (works without it, but emails won't send)
+
+---
+
+## Environment Variables
+
+Add these to your `.env.local`:
+
+```env
+# Email (Resend)
+RESEND_API_KEY="re_xxxxxxxxxxxxx"  # Your Resend API key
+EMAIL_FROM="Your App <noreply@yourdomain.com>"  # Sender email address
+```
+
+**Required Variables:**
+- `RESEND_API_KEY` - Your Resend API key (get from [resend.com](https://resend.com))
+
+**Optional Variables:**
+- `EMAIL_FROM` - Sender email address (defaults to "SaaS Scaffold <noreply@saas-scaffold.com>")
+
+**Where to get them:**
+- **Resend**: [resend.com](https://resend.com) - Free tier available (100 emails/day)
+- Create an account and get your API key from the dashboard
+- Verify your domain for production use
+
+---
+
+## Manual Integration Steps
+
+If you're appending this module to an existing project, follow these steps:
+
+### Step 1: Install Dependencies
+
+```bash
+npm install
+# or
+pnpm install
+# or
+yarn install
+```
+
+The append command automatically adds missing dependencies to `package.json`, but you need to install them.
+
+### Step 2: Add Environment Variables
+
+1. Copy `.env.example` to `.env.local` (if not exists)
+2. Add `RESEND_API_KEY` with your Resend API key
+3. Optionally set `EMAIL_FROM` with your sender email
+
+### Step 3: Verify Installation
+
+1. Check that `lib/email.ts` exists
+2. Check that `emails/` directory exists with all templates
+3. Start your dev server: `npm run dev`
+
+### Step 4: Test Email Sending
+
+The email module works gracefully without configuration:
+- If `RESEND_API_KEY` is not set, emails are logged to console
+- If `RESEND_API_KEY` is set, emails are sent via Resend
+
+---
+
+## Usage Examples
+
+### Sending a Welcome Email
+
+```typescript
+import { sendWelcomeEmail } from "@/lib/email";
+
+// In your sign-up handler
+await sendWelcomeEmail(user.email, user.name);
+```
+
+### Sending a Password Reset Email
+
+```typescript
+import { sendPasswordResetEmail } from "@/lib/email";
+
+// In your password reset handler
+const resetUrl = `${process.env.NEXT_PUBLIC_APP_URL}/reset-password?token=${token}`;
+await sendPasswordResetEmail(user.email, resetUrl);
+```
+
+### Sending a Custom Email
+
+```typescript
+import { sendEmail } from "@/lib/email";
+import { MyCustomEmail } from "@/emails/my-custom-email";
+
+await sendEmail({
+  to: "user@example.com",
+  subject: "Custom Email Subject",
+  react: MyCustomEmail({ customProp: "value" }),
+  from: "Custom Sender <custom@yourdomain.com>", // Optional
+});
+```
+
+### Creating a New Email Template
+
+1. Create a new file in `emails/`:
+   ```typescript
+   // emails/my-email.tsx
+   import { Text } from '@react-email/components';
+   import { EmailLayout } from './components/layout';
+
+   interface MyEmailProps {
+     userName: string;
+   }
+
+   export function MyEmail({ userName }: MyEmailProps) {
+     return (
+       <EmailLayout preview="My email preview">
+         <Text>Hello {userName}!</Text>
+       </EmailLayout>
+     );
+   }
+   ```
+
+2. Add a helper function in `lib/email.ts`:
+   ```typescript
+   export async function sendMyEmail(email: string, userName: string) {
+     const { MyEmail } = await import('@/emails/my-email');
+     return sendEmail({
+       to: email,
+       subject: 'My Email Subject',
+       react: MyEmail({ userName }),
+     });
+   }
+   ```
+
+---
+
+## Customization
+
+### Styling
+- Email templates use React Email components
+- Customize styles in individual email templates
+- Shared layout in `emails/components/layout.tsx`
+
+### Configuration
+- Email configuration is in `lib/email.ts`
+- Customize default sender in `EMAIL_FROM` env var
+- Modify email templates in `emails/` directory
+
+### Templates
+- All templates are in `emails/` directory
+- Use `EmailLayout` component for consistent styling
+- Templates are React components - fully customizable
+
+---
+
+## Integration Points
+
+### Files That May Need Manual Updates
+
+**lib/auth.ts** (if auth module installed):
+- Already imports email functions
+- Will automatically use real email sending when email module is installed
+- Falls back to console logging if email module not installed
+
+**lib/subscription.ts** (if payments module installed):
+- Subscription confirmation emails will work automatically
+- Payment failed emails will work automatically
+
+**No manual integration needed!** The email module integrates automatically with auth and payments modules.
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+**Issue:** "Email not sent (Resend not configured)" in console
+**Solution:**
+- Add `RESEND_API_KEY` to `.env.local`
+- Get API key from [resend.com](https://resend.com)
+- Restart dev server after adding env var
+
+**Issue:** Emails not being received
+**Solution:**
+- Check Resend dashboard for delivery status
+- Verify sender email is verified in Resend
+- Check spam folder
+- Verify `EMAIL_FROM` matches verified domain
+
+**Issue:** "Invalid API key" error
+**Solution:**
+- Verify `RESEND_API_KEY` is correct
+- Check for extra spaces or quotes in `.env.local`
+- Regenerate API key in Resend dashboard if needed
+
+**Issue:** Domain not verified
+**Solution:**
+- In development, you can use Resend's test domain
+- For production, verify your domain in Resend dashboard
+- Add DNS records as instructed by Resend
+
+---
+
+## Next Steps
+
+After installing this module:
+
+1. Get Resend API key from [resend.com](https://resend.com)
+2. Add `RESEND_API_KEY` to `.env.local`
+3. Test email sending (welcome email, password reset, etc.)
+4. Verify your domain for production
+5. Customize email templates to match your brand
+6. Set up custom `EMAIL_FROM` address
+
+---
+
+## Related Modules
+
+This module works well with:
+- **Auth Module** - For password reset emails
+- **Payments Module** - For subscription confirmation and payment failed emails
+
+**Note:** Email module is optional. Auth and Payments modules work without it (they log to console instead of sending emails).
+
+---
+
+## Module Status
+
+✅ **Standalone Package** - Can be installed independently  
+✅ **Graceful Fallback** - Works without configuration (logs to console)  
+✅ **Ready to Use** - Works immediately after append  
+✅ **Well Documented** - Comprehensive integration guide
+
+---
+
+## AI Integration Prompt
+
+**For AI Assistants:** Use this prompt to understand and integrate the Email module into an existing Next.js application.
+
+```
+The Email module has been appended to this Next.js project. Your task is to ensure it's properly integrated and functional.
+
+**Installed Packages:**
+- resend@^6.6.0 - Resend email service SDK
+- @react-email/components@^1.0.2 - React components for email templates
+- @react-email/render@^2.0.0 - Render React components to HTML
+
+**Files Added:**
+- lib/email.ts - Email sending utilities with Resend integration
+- emails/welcome.tsx - Welcome email template
+- emails/password-reset.tsx - Password reset email template
+- emails/subscription-confirmation.tsx - Subscription confirmation email template
+- emails/payment-failed.tsx - Payment failed email template
+- emails/components/layout.tsx - Shared email layout component
+
+**Environment Variables Required:**
+- RESEND_API_KEY - Resend API key (get from resend.com)
+- EMAIL_FROM - Sender email address (e.g., "Your App <noreply@yourdomain.com>")
+
+**Integration Steps:**
+1. Verify lib/email.ts exists and exports sendEmail, sendPasswordResetEmail, etc.
+2. Check that email templates exist in emails/ directory
+3. If auth module installed: lib/auth.ts should import email functions (auto-replaces stubs)
+4. If payments module installed: Subscription emails will work automatically
+5. Verify environment variables are set in .env.local
+6. Test email sending with a simple function call
+
+**Key Integration Points:**
+- Automatic replacement: Email module replaces auth module's email stubs automatically
+- Template system: All emails use React Email components for consistent styling
+- Email layout: emails/components/layout.tsx provides shared header/footer
+- Function exports: lib/email.ts exports all email functions used by auth/payments
+- Graceful fallback: If RESEND_API_KEY not set, emails log to console instead of failing
+
+**Dependencies:**
+- OPTIONAL: Auth module (for password reset emails)
+- OPTIONAL: Payments module (for subscription/payment emails)
+- No hard dependencies - can be installed standalone
+
+**Common Issues to Check:**
+- If emails not sending: Check RESEND_API_KEY is set and valid
+- If "Invalid API key" error: Verify API key in Resend dashboard
+- If emails not received: Check Resend dashboard for delivery status, verify sender domain
+- If template errors: Ensure @react-email/components is installed
+
+**Next Steps After Integration:**
+- Get Resend API key from resend.com
+- Add RESEND_API_KEY and EMAIL_FROM to .env.local
+- Test email sending (password reset, welcome email, etc.)
+- Customize email templates to match your brand
+- Verify sender domain in Resend dashboard for production
+```

package/features/email/emails/components/layout.tsx

@@ -0,0 +1,181 @@
+import {
+  Html,
+  Head,
+  Preview,
+  Body,
+  Container,
+  Section,
+  Text,
+  Link,
+  Hr,
+} from '@react-email/components';
+
+interface EmailLayoutProps {
+  preview: string;
+  children: React.ReactNode;
+}
+
+export function EmailLayout({ preview, children }: EmailLayoutProps) {
+  return (
+    <Html>
+      <Head />
+      <Preview>{preview}</Preview>
+      <Body style={main}>
+        <Container style={container}>
+          {/* Header */}
+          <Section style={header}>
+            <Text style={logo}>SaaS Scaffold</Text>
+          </Section>
+
+          {/* Main Content */}
+          <Section style={content}>
+            {children}
+          </Section>
+
+          {/* Footer */}
+          <Hr style={hr} />
+          <Section style={footer}>
+            <Text style={footerText}>
+              © {new Date().getFullYear()} SaaS Scaffold. All rights reserved.
+            </Text>
+            <Text style={footerLinks}>
+              <Link href="https://saas-scaffold.com" style={link}>
+                Website
+              </Link>
+              {' • '}
+              <Link href="https://saas-scaffold.com/docs" style={link}>
+                Docs
+              </Link>
+              {' • '}
+              <Link href="https://saas-scaffold.com/support" style={link}>
+                Support
+              </Link>
+            </Text>
+            <Text style={footerText}>
+              You received this email because you have an account with SaaS Scaffold.
+            </Text>
+          </Section>
+        </Container>
+      </Body>
+    </Html>
+  );
+}
+
+// Styles
+const main = {
+  backgroundColor: '#000000',
+  fontFamily:
+    '-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Ubuntu,sans-serif',
+};
+
+const container = {
+  backgroundColor: '#0a0a0a',
+  margin: '0 auto',
+  padding: '20px 0 48px',
+  marginBottom: '64px',
+  maxWidth: '600px',
+  border: '1px solid #2a2a2a',
+  borderRadius: '8px',
+};
+
+const header = {
+  padding: '32px 48px',
+  backgroundColor: '#000000',
+  borderBottom: '1px solid #2a2a2a',
+};
+
+const logo = {
+  fontSize: '24px',
+  fontWeight: 'bold',
+  color: '#ffffff',
+  margin: 0,
+  background: 'linear-gradient(135deg, #ff5722 0%, #d84315 100%)',
+  WebkitBackgroundClip: 'text',
+  WebkitTextFillColor: 'transparent',
+  backgroundClip: 'text',
+};
+
+const content = {
+  padding: '48px 48px 24px',
+};
+
+const hr = {
+  borderColor: '#2a2a2a',
+  margin: '32px 48px',
+};
+
+const footer = {
+  padding: '0 48px 32px',
+};
+
+const footerText = {
+  fontSize: '12px',
+  lineHeight: '16px',
+  color: '#666666',
+  margin: '8px 0',
+};
+
+const footerLinks = {
+  fontSize: '12px',
+  lineHeight: '16px',
+  color: '#666666',
+  margin: '16px 0 8px',
+};
+
+const link = {
+  color: '#ff5722',
+  textDecoration: 'none',
+};
+
+// Reusable component styles
+export const styles = {
+  h1: {
+    fontSize: '32px',
+    fontWeight: 'bold',
+    color: '#ffffff',
+    margin: '0 0 16px',
+  },
+  h2: {
+    fontSize: '24px',
+    fontWeight: 'bold',
+    color: '#ffffff',
+    margin: '32px 0 16px',
+  },
+  p: {
+    fontSize: '16px',
+    lineHeight: '24px',
+    color: '#cccccc',
+    margin: '16px 0',
+  },
+  button: {
+    backgroundColor: '#ff5722',
+    borderRadius: '6px',
+    color: '#ffffff',
+    fontSize: '16px',
+    fontWeight: '600',
+    textDecoration: 'none',
+    textAlign: 'center' as const,
+    display: 'inline-block',
+    padding: '12px 32px',
+    margin: '24px 0',
+  },
+  code: {
+    backgroundColor: '#1a1a1a',
+    border: '1px solid #2a2a2a',
+    borderRadius: '4px',
+    color: '#ff5722',
+    fontFamily: 'monospace',
+    fontSize: '14px',
+    padding: '2px 6px',
+  },
+  codeBlock: {
+    backgroundColor: '#1a1a1a',
+    border: '1px solid #2a2a2a',
+    borderRadius: '6px',
+    color: '#ffffff',
+    fontFamily: 'monospace',
+    fontSize: '14px',
+    padding: '16px',
+    margin: '16px 0',
+  },
+};

package/features/email/emails/password-reset.tsx

@@ -0,0 +1,67 @@
+import { Text, Link, Section } from '@react-email/components';
+import { EmailLayout, styles } from './components/layout';
+
+interface PasswordResetEmailProps {
+  resetUrl: string;
+}
+
+export function PasswordResetEmail({ resetUrl }: PasswordResetEmailProps) {
+  return (
+    <EmailLayout preview="Reset your SaaS Scaffold password">
+      <Text style={styles.h1}>Reset your password</Text>
+
+      <Text style={styles.p}>
+        We received a request to reset your password for your SaaS Scaffold account.
+      </Text>
+
+      <Text style={styles.p}>
+        Click the button below to choose a new password. This link will expire in 1 hour for security reasons.
+      </Text>
+
+      <Link href={resetUrl} style={styles.button}>
+        Reset Password
+      </Link>
+
+      <Section style={warningBox}>
+        <Text style={warningText}>
+          <strong>Security Tip:</strong> If you didn't request this password reset, you can safely ignore this email. Your password will remain unchanged.
+        </Text>
+      </Section>
+
+      <Text style={styles.p}>
+        For your security, this password reset link can only be used once and will expire in 60 minutes.
+      </Text>
+
+      <Text style={{ ...styles.p, marginTop: '32px' }}>
+        If you're having trouble clicking the button, copy and paste this URL into your browser:
+      </Text>
+
+      <Section style={styles.codeBlock}>
+        {resetUrl}
+      </Section>
+
+      <Text style={styles.p}>
+        Thanks,<br />
+        The SaaS Scaffold Team
+      </Text>
+    </EmailLayout>
+  );
+}
+
+// Additional styles
+const warningBox = {
+  backgroundColor: '#2a1a1a',
+  border: '1px solid #ff5722',
+  borderRadius: '6px',
+  padding: '16px',
+  margin: '24px 0',
+};
+
+const warningText = {
+  fontSize: '14px',
+  lineHeight: '20px',
+  color: '#ff9a80',
+  margin: 0,
+};
+
+export default PasswordResetEmail;