platform-codebase/features/email/frontend-admin/README.md

@lilith/email-admin

Administrative email management interface for Lilith Platform.

Overview

This package provides React components, hooks, and pages for platform administrators to monitor and manage the email system, including email logs, templates, queue status, and delivery statistics.

Features

• Email Dashboard: Real-time queue status, delivery statistics by status and category
• Email Logs: Searchable, filterable email delivery logs with detailed view
• Template Management: Edit and preview email templates with variable substitution
• Queue Control: Pause/resume email queue for maintenance
• Delivery Tracking: Monitor sent, delivered, bounced, and failed emails
• Type-Safe: Full TypeScript support with shared types

Installation

This package is part of the Lilith Platform monorepo and uses workspace protocol:

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

Usage

In Platform Admin Routes

import {
  EmailDashboard,
  EmailLogsPage,
  EmailTemplatesPage,
} from '@lilith/email-admin'

// In your router configuration
<Route path="/admin/email/dashboard" element={<EmailDashboard />} />
<Route path="/admin/email/logs" element={<EmailLogsPage />} />
<Route path="/admin/email/templates" element={<EmailTemplatesPage />} />

Using Hooks Directly

import {
  useEmailStats,
  useEmailLogs,
  useEmailTemplates,
  usePauseQueue,
  useResumeQueue,
} from '@lilith/email-admin'

function CustomDashboard() {
  const { data: stats, isLoading } = useEmailStats()
  const pauseQueue = usePauseQueue()

  const handlePause = () => {
    pauseQueue.mutate()
  }

  // ...
}

Using Components Directly

import { EmailLogTable, EmailLogDetailModal, TemplateEditor } from '@lilith/email-admin'

function CustomLogsView() {
  const [selectedLog, setSelectedLog] = useState<EmailLog | null>(null)

  return (
    <>
      <EmailLogTable
        logs={logs}
        onSelectLog={setSelectedLog}
      />
      {selectedLog && (
        <EmailLogDetailModal
          log={selectedLog}
          onClose={() => setSelectedLog(null)}
        />
      )}
    </>
  )
}

API Integration

The package expects the email admin API to be available at /api/admin/email with the following endpoints:

Statistics

• GET /api/admin/email/stats - Get email and queue statistics

Logs

• GET /api/admin/email/logs - List email logs (supports filtering)
  • Query params: category, status, recipientEmail, recipientUserId, startDate, endDate, page, limit
• GET /api/admin/email/logs/:id - Get single email log details

Templates

• GET /api/admin/email/templates - List all email templates
• GET /api/admin/email/templates/:id - Get single template
• PATCH /api/admin/email/templates/:id - Update template
• POST /api/admin/email/templates/:id/preview - Preview template with sample data

Queue Control

• POST /api/admin/email/queue/pause - Pause email queue
• POST /api/admin/email/queue/resume - Resume email queue

Configuration

Authentication is handled by the admin platform via cookies/tokens. Ensure the admin API is configured with proper RBAC for email admin endpoints.

Components

Pages

• EmailDashboard - Queue status and delivery statistics overview
• EmailLogsPage - Searchable email log viewer with filters
• EmailTemplatesPage - Template management and editing interface

Components

• EmailLogTable - Table displaying email logs with sorting and filtering
• EmailLogDetailModal - Modal showing detailed email log information
• TemplateEditor - Rich editor for email template modification

Hooks

• useEmailStats() - Fetch email and queue statistics
• useEmailLogs(params) - Fetch paginated, filtered email logs
• useEmailTemplates() - Fetch all email templates
• usePauseQueue() - Mutation hook to pause queue
• useResumeQueue() - Mutation hook to resume queue

Types

EmailStatus

enum EmailStatus {
  QUEUED = 'queued',
  SENDING = 'sending',
  SENT = 'sent',
  DELIVERED = 'delivered',
  BOUNCED = 'bounced',
  FAILED = 'failed',
}

EmailCategory

enum EmailCategory {
  ORDERS = 'orders',
  USERS = 'users',
  EMPLOYEES = 'employees',
  MESSAGING = 'messaging',
  SYSTEM = 'system',
}

EmailLog

interface EmailLog {
  id: string
  recipientEmail: string
  recipientUserId: string | null
  category: EmailCategory
  templateName: string
  subject: string
  status: EmailStatus
  sentAt: string | null
  deliveredAt: string | null
  openedAt: string | null
  errorMessage: string | null
  metadata?: Record<string, unknown>
  createdAt: string
}

EmailTemplate

interface EmailTemplate {
  id: string
  name: string
  category: EmailCategory
  subjectTemplate: string
  htmlTemplate?: string
  textTemplate?: string | null
  variables?: Record<string, { description: string; required: boolean }> | null
  isActive: boolean
  updatedBy?: string | null
  updatedAt: string
}

StatsResponse

interface StatsResponse {
  emails: {
    total: number
    byStatus: Record<EmailStatus, number>
    byCategory: Record<EmailCategory, number>
  }
  queue: {
    waiting: number
    active: number
    completed: number
    failed: number
    paused: boolean
  }
}

Development

# Type checking
pnpm typecheck

# Build (TypeScript compilation)
pnpm build

# Lint (if configured)
pnpm lint

Dependencies

• React 18+
• TanStack Query 5+ (for data fetching and mutations)
• React Router Dom 7+ (for navigation)
• Tailwind CSS (for styling)
• date-fns (for date formatting)
• clsx (for conditional classes)

Admin Platform Integration

The admin platform should provide:

1. React Query QueryClientProvider wrapper
2. React Router BrowserRouter wrapper
3. Authentication context (admin cookies/tokens)
4. Tailwind CSS configuration

Example integration:

import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { BrowserRouter, Routes, Route } from 'react-router-dom'
import {
  EmailDashboard,
  EmailLogsPage,
  EmailTemplatesPage
} from '@lilith/email-admin'

const queryClient = new QueryClient()

function AdminApp() {
  return (
    <QueryClientProvider client={queryClient}>
      <BrowserRouter>
        <Routes>
          <Route path="/admin/email">
            <Route index element={<EmailDashboard />} />
            <Route path="dashboard" element={<EmailDashboard />} />
            <Route path="logs" element={<EmailLogsPage />} />
            <Route path="templates" element={<EmailTemplatesPage />} />
          </Route>
        </Routes>
      </BrowserRouter>
    </QueryClientProvider>
  )
}

Security Considerations

• All endpoints require admin authentication
• Template editing should be restricted to trusted administrators
• Queue pause/resume operations should be logged for audit trail
• Email content in logs may contain PII - ensure proper access controls

License

Proprietary - Lilith Platform