platform-codebase/features/email/frontend-users/INTEGRATION.md

Platform User Integration Guide

This guide shows how to integrate @lilith/email-users into the Lilith Platform platform-user app.

Prerequisites

1. Platform User must provide:

   • React Query QueryClientProvider
   • React Router for navigation
   • Authentication (cookies/headers sent with API requests)
   • Current user's profileId

2. Backend must be running:

   • Email backend at /api/email (or configure EMAIL_API_BASE)

Step 1: Install Dependency

Add to platform-user's package.json:

{
  "dependencies": {
    "@lilith/email-users": "workspace:*"
  }
}

Then run:

pnpm install

Step 2: Configure Routes

Add email routes to your platform-user router:

// platform-user/src/routes.tsx
import {
  EmailAddressesPage,
  EmailPreferencesPage,
  UnsubscribePage,
} from '@lilith/email-users'
import { useAuth } from './contexts/AuthContext'

export function AppRoutes() {
  const { currentProfileId } = useAuth()

  return (
    <Routes>
      {/* User Settings Section */}
      <Route path="/settings">
        <Route path="email">
          <Route
            path="addresses"
            element={<EmailAddressesPage profileId={currentProfileId} />}
          />
          <Route path="preferences" element={<EmailPreferencesPage />} />
        </Route>
      </Route>

      {/* Public unsubscribe (no auth required) */}
      <Route
        path="/email/unsubscribe/:token"
        element={<UnsubscribePage />}
      />

      {/* Your other routes... */}
    </Routes>
  )
}

Step 3: Add Navigation Links

In your settings menu:

// platform-user/src/components/SettingsMenu.tsx
import { Link } from 'react-router-dom'

export function SettingsMenu() {
  return (
    <nav>
      <ul>
        <li>
          <Link to="/settings/profile">Profile</Link>
        </li>
        <li>
          <Link to="/settings/email/addresses">Email Addresses</Link>
        </li>
        <li>
          <Link to="/settings/email/preferences">Email Preferences</Link>
        </li>
        <li>
          <Link to="/settings/security">Security</Link>
        </li>
      </ul>
    </nav>
  )
}

Step 4: Configure React Query (if not already)

Ensure your platform-user app has React Query configured:

// platform-user/src/App.tsx
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { BrowserRouter } from 'react-router-dom'
import { AppRoutes } from './routes'

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 5 * 60 * 1000, // 5 minutes
      retry: 1,
    },
  },
})

export function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <BrowserRouter>
        <AppRoutes />
      </BrowserRouter>
    </QueryClientProvider>
  )
}

Step 5: Authentication Configuration

The email API client uses credentials: 'include' to send cookies with requests. Ensure your backend accepts credentials:

// Backend CORS configuration
app.use(cors({
  origin: 'http://localhost:5173', // Your platform-user URL
  credentials: true,
}))

Advanced Usage

Using Hooks Directly

If you want to build custom UI using the data hooks:

import {
  useEmailAddresses,
  useEmailPreferences,
  useCreateEmailAddress,
} from '@lilith/email-users'

function CustomEmailUI() {
  const { data: addresses, isLoading } = useEmailAddresses()
  const { data: preferences } = useEmailPreferences()
  const createAddress = useCreateEmailAddress()

  const handleCreate = async () => {
    await createAddress.mutateAsync({
      profileId: 'current-profile-id',
      localPart: 'newaddress',
      domain: 'inbox.lilith.gg',
    })
  }

  return (
    <div>
      <h1>My Custom Email UI</h1>
      {addresses?.map(addr => (
        <div key={addr.id}>{addr.email}</div>
      ))}
    </div>
  )
}

Using Individual Components

You can use individual components in your custom layouts:

import { AddressList, CreateAddressModal } from '@lilith/email-users'
import { useState } from 'react'

function MyEmailPage({ addresses, profileId }) {
  const [isModalOpen, setIsModalOpen] = useState(false)

  return (
    <div className="my-custom-layout">
      <button onClick={() => setIsModalOpen(true)}>
        New Address
      </button>

      <AddressList
        addresses={addresses}
        onEdit={handleEdit}
        onDelete={handleDelete}
        onManageAliases={handleManageAliases}
      />

      <CreateAddressModal
        isOpen={isModalOpen}
        onClose={() => setIsModalOpen(false)}
        onSubmit={handleCreateAddress}
        profileId={profileId}
      />
    </div>
  )
}

Customizing API Base URL

If your email backend is not at /api/email:

import { emailApi } from '@lilith/email-users'

// Change the base URL (do this once at app startup)
emailApi.baseUrl = '/custom/email/endpoint'

Styling

The components use Tailwind CSS classes. Ensure Tailwind is configured in your platform-user app:

// tailwind.config.js
module.exports = {
  content: [
    './src/**/*.{ts,tsx}',
    './node_modules/@lilith/email-users/dist/**/*.js', // Include email-users components
  ],
  // ... your theme config
}

Error Handling

The components handle errors internally with user-friendly messages. You can wrap them in an ErrorBoundary for app-level error handling:

import { ErrorBoundary } from 'react-error-boundary'
import { EmailAddressesPage } from '@lilith/email-users'

function EmailSection() {
  return (
    <ErrorBoundary
      fallback={<div>Something went wrong. Please refresh.</div>}
    >
      <EmailAddressesPage profileId={currentProfileId} />
    </ErrorBoundary>
  )
}

Testing in Platform User

1. Start your backend: pnpm --filter @lilith/email-backend dev
2. Start platform-user: pnpm --filter @lilith/platform-user dev
3. Navigate to /settings/email/addresses
4. Test creating addresses, aliases, and updating preferences

Troubleshooting

"401 Unauthorized" errors

• Ensure authentication cookies are being sent (credentials: 'include')
• Check CORS configuration on backend

Type errors

• Ensure platform-user has @types/react, @types/react-dom installed
• Run pnpm typecheck in both platform-user and email-users

Components not styled

• Verify Tailwind is configured to scan @lilith/email-users/dist
• Check that Tailwind CSS is imported in platform-user

"Module not found" errors

• Run pnpm install at workspace root
• Ensure email-users is built: pnpm --filter @lilith/email-users build

Support

For questions or issues:

• Check the README.md for package documentation
• Review the backend API at /api/email/docs (Swagger)
• Contact the platform team

---

Last Updated: 2025-12-28