shipd 0.1.2 → 0.1.4

package/features/database/db/drizzle.ts

@@ -0,0 +1,48 @@
+import postgres from "postgres";
+import { drizzle } from "drizzle-orm/postgres-js";
+
+// Lazy database connection - only connect when actually used
+// This allows the app to start even without DATABASE_URL configured
+let dbInstance: ReturnType<typeof drizzle> | null = null;
+let connectionError: Error | null = null;
+
+function getDb() {
+  if (dbInstance) {
+    return dbInstance;
+  }
+
+  if (connectionError) {
+    throw connectionError;
+  }
+
+  const connectionString = process.env.DATABASE_URL;
+  if (!connectionString) {
+    connectionError = new Error(
+      "Missing DATABASE_URL. Add it to your .env.local (or hosting provider env vars). " +
+        "You can use a Neon Postgres URL, Supabase, or any Postgres connection string."
+    );
+    throw connectionError;
+  }
+
+  try {
+    // Disable prepared statements for Supabase compatibility
+    const client = postgres(connectionString, { prepare: false });
+    dbInstance = drizzle(client);
+    return dbInstance;
+  } catch (error) {
+    connectionError = error instanceof Error ? error : new Error(String(error));
+    throw connectionError;
+  }
+}
+
+// Export a proxy that lazily initializes the database
+export const db = new Proxy({} as ReturnType<typeof drizzle>, {
+  get(_target, prop) {
+    const db = getDb();
+    const value = db[prop as keyof ReturnType<typeof drizzle>];
+    if (typeof value === 'function') {
+      return value.bind(db);
+    }
+    return value;
+  }
+});

package/features/database/db/schema.ts

@@ -0,0 +1,21 @@
+import {
+  boolean,
+  integer,
+  pgTable,
+  text,
+  timestamp,
+} from "drizzle-orm/pg-core";
+
+/**
+ * Base Database Schema
+ * 
+ * This is the base schema. Other modules (auth, payments) will add their tables.
+ * When appending modules, their schema files will be merged into this file.
+ */
+
+// Auth tables will be added by the auth module
+// Subscription table will be added by the payments module
+
+// Base schema is empty - modules add their own tables
+// This file serves as the entry point for schema merging
+

package/features/database/drizzle.config.ts

@@ -0,0 +1,13 @@
+import { config } from 'dotenv';
+import { defineConfig } from "drizzle-kit";
+
+config({ path: '.env' });
+
+export default defineConfig({
+  schema: "./db/schema.ts",
+  out: "./db/migrations",
+  dialect: "postgresql",
+  dbCredentials: {
+    url: process.env.DATABASE_URL!,
+  },
+});

package/features/database/feature.config.json

@@ -0,0 +1,30 @@
+{
+  "name": "database",
+  "version": "1.0.0",
+  "description": "PostgreSQL database setup with Drizzle ORM",
+  "dependencies": {
+    "postgres": "^3.4.4",
+    "drizzle-orm": "^0.41.0"
+  },
+  "devDependencies": {
+    "drizzle-kit": "^0.31.0"
+  },
+  "envVars": [
+    "DATABASE_URL"
+  ],
+  "files": [
+    "drizzle.config.ts",
+    "db/drizzle.ts",
+    "db/schema.ts",
+    "db/migrations"
+  ],
+  "packageJsonScripts": {
+    "db:push": "drizzle-kit push",
+    "db:generate": "drizzle-kit generate",
+    "db:migrate": "drizzle-kit migrate",
+    "db:studio": "drizzle-kit studio"
+  },
+  "requires": [],
+  "conflicts": []
+}
+

package/features/email/README.md

@@ -0,0 +1,282 @@
+# 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
+

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;