@bernierllc/email 1.0.0

package/PACKAGE_USAGE.md

@@ -0,0 +1,471 @@
+# Email Template Manager - Package Usage Guide
+
+This guide shows how to use the Email Template Manager as importable packages in your Python, React, and Next.js applications.
+
+## Python Package Usage
+
+### Installation
+
+```bash
+# Basic installation
+pip install email-template-manager
+
+# With SendGrid support
+pip install email-template-manager[sendgrid]
+
+# With FastAPI integration
+pip install email-template-manager[fastapi,sendgrid]
+
+# With all providers and frameworks
+pip install email-template-manager[all]
+```
+
+### Basic Python Usage
+
+```python
+from email_template_manager import (
+    EmailTemplateManager,
+    EmailScheduler,
+    SendGridProvider,
+    EmailTemplate,
+    ScheduledEmail
+)
+
+# Initialize the email provider
+email_provider = SendGridProvider({
+    'api_key': 'your-sendgrid-api-key',
+    'from_email': 'noreply@yourapp.com',
+    'from_name': 'Your App'
+})
+
+# Initialize the template manager
+template_manager = EmailTemplateManager(
+    database_url='postgresql://user:pass@localhost/db'
+)
+
+# Initialize the scheduler
+scheduler = EmailScheduler(template_manager, email_provider)
+
+# Create an email template
+template = EmailTemplate(
+    name='Welcome Email',
+    subject='Welcome to {{app_name}}!',
+    html_body='<h1>Hello {{name}}!</h1><p>Welcome to {{app_name}}.</p>',
+    text_body='Hello {{name}}! Welcome to {{app_name}}.',
+    variables=[
+        {'name': 'name', 'type': 'text', 'required': True},
+        {'name': 'app_name', 'type': 'text', 'required': True}
+    ]
+)
+
+# Save the template
+saved_template = await template_manager.create_template(template)
+
+# Schedule an email
+scheduled_email = ScheduledEmail(
+    template_id=saved_template.id,
+    recipient_email='user@example.com',
+    recipient_name='John Doe',
+    variables={
+        'name': 'John Doe',
+        'app_name': 'My Amazing App'
+    },
+    trigger_type='immediate'
+)
+
+result = await scheduler.schedule_email(scheduled_email)
+```
+
+### FastAPI Integration
+
+```python
+from fastapi import FastAPI, BackgroundTasks
+from email_template_manager import EmailTemplateManager, EmailScheduler, SendGridProvider
+from email_template_manager.integrations.fastapi import create_email_router
+
+app = FastAPI()
+
+# Initialize components
+template_manager = EmailTemplateManager('postgresql://user:pass@localhost/db')
+email_provider = SendGridProvider({
+    'api_key': 'your-sendgrid-api-key',
+    'from_email': 'noreply@yourapp.com'
+})
+scheduler = EmailScheduler(template_manager, email_provider)
+
+# Add the email management router
+email_router = create_email_router(
+    get_template_manager=lambda: template_manager,
+    get_scheduler=lambda: scheduler
+)
+app.include_router(email_router, prefix='/api/email', tags=['email'])
+
+# Custom endpoint using the email system
+@app.post('/send-welcome-email')
+async def send_welcome_email(
+    user_email: str,
+    user_name: str,
+    background_tasks: BackgroundTasks
+):
+    # Find welcome template
+    templates = await template_manager.list_templates(
+        filters={'name': 'Welcome Email'}
+    )
+    
+    if templates:
+        scheduled_email = ScheduledEmail(
+            template_id=templates[0].id,
+            recipient_email=user_email,
+            recipient_name=user_name,
+            variables={'name': user_name, 'app_name': 'My App'},
+            trigger_type='immediate'
+        )
+        
+        await scheduler.schedule_email(scheduled_email)
+        background_tasks.add_task(scheduler.process_pending_emails)
+        
+        return {'status': 'success', 'message': 'Welcome email scheduled'}
+    
+    return {'status': 'error', 'message': 'Welcome template not found'}
+```
+
+## NPM/TypeScript Package Usage
+
+### Installation
+
+```bash
+# For React/Next.js projects
+npm install @email-template-manager/core @email-template-manager/react
+
+# For vanilla JavaScript/TypeScript
+npm install @email-template-manager/core
+```
+
+### Basic TypeScript Usage
+
+```typescript
+import {
+  EmailTemplateManager,
+  EmailScheduler,
+  SendGridProvider,
+  EmailTemplate,
+  ScheduledEmail
+} from '@email-template-manager/core';
+
+// Initialize the email provider
+const emailProvider = new SendGridProvider({
+  apiKey: 'your-sendgrid-api-key',
+  fromEmail: 'noreply@yourapp.com',
+  fromName: 'Your App'
+});
+
+// Initialize the template manager
+const templateManager = new EmailTemplateManager({
+  database: {
+    type: 'postgresql',
+    connectionString: 'postgresql://user:pass@localhost/db'
+  }
+});
+
+// Initialize the scheduler
+const scheduler = new EmailScheduler(templateManager, emailProvider);
+
+// Create an email template
+const template: EmailTemplate = {
+  name: 'Welcome Email',
+  subject: 'Welcome to {{app_name}}!',
+  htmlBody: '<h1>Hello {{name}}!</h1><p>Welcome to {{app_name}}.</p>',
+  textBody: 'Hello {{name}}! Welcome to {{app_name}}.',
+  variables: [
+    { name: 'name', type: 'text', required: true },
+    { name: 'app_name', type: 'text', required: true }
+  ],
+  tags: ['welcome'],
+  isActive: true,
+  version: 1
+};
+
+// Save the template
+const savedTemplate = await templateManager.createTemplate(template);
+
+// Schedule an email
+const scheduledEmail: ScheduledEmail = {
+  templateId: savedTemplate.id!,
+  recipientEmail: 'user@example.com',
+  recipientName: 'John Doe',
+  variables: {
+    name: 'John Doe',
+    app_name: 'My Amazing App'
+  },
+  triggerType: 'immediate',
+  status: 'pending',
+  retryCount: 0,
+  maxRetries: 3,
+  metadata: {}
+};
+
+const result = await scheduler.scheduleEmail(scheduledEmail);
+```
+
+### React Component Usage
+
+```tsx
+import React from 'react';
+import {
+  EmailTemplateProvider,
+  EmailTemplateList,
+  EmailTemplateEditor,
+  useEmailTemplates
+} from '@email-template-manager/react';
+import { EmailManagerConfig } from '@email-template-manager/core';
+
+const config: EmailManagerConfig = {
+  database: {
+    type: 'postgresql',
+    connectionString: process.env.DATABASE_URL!
+  },
+  emailProvider: {
+    provider: 'sendgrid',
+    apiKey: process.env.SENDGRID_API_KEY!,
+    fromEmail: 'noreply@yourapp.com',
+    fromName: 'Your App'
+  }
+};
+
+function TemplateManager() {
+  const { 
+    templates, 
+    createTemplate, 
+    updateTemplate, 
+    deleteTemplate,
+    loading 
+  } = useEmailTemplates();
+
+  const handleCreateTemplate = async (templateData: any) => {
+    await createTemplate(templateData);
+  };
+
+  return (
+    <div className="p-6">
+      <h1 className="text-2xl font-bold mb-4">Email Templates</h1>
+      
+      <EmailTemplateList
+        templates={templates}
+        onEdit={(template) => console.log('Edit:', template)}
+        onDelete={(templateId) => deleteTemplate(templateId)}
+        loading={loading}
+      />
+      
+      <EmailTemplateEditor
+        onSave={handleCreateTemplate}
+        onCancel={() => console.log('Cancel')}
+        variables={[
+          { name: 'name', type: 'text', required: true },
+          { name: 'email', type: 'email', required: true }
+        ]}
+        previewData={{
+          name: 'John Doe',
+          email: 'john@example.com'
+        }}
+      />
+    </div>
+  );
+}
+
+export default function App() {
+  return (
+    <EmailTemplateProvider config={config}>
+      <TemplateManager />
+    </EmailTemplateProvider>
+  );
+}
+```
+
+### Next.js API Route Usage
+
+```typescript
+// pages/api/email/send-welcome.ts
+import { NextApiRequest, NextApiResponse } from 'next';
+import {
+  EmailTemplateManager,
+  EmailScheduler,
+  SendGridProvider
+} from '@email-template-manager/core';
+
+const templateManager = new EmailTemplateManager({
+  database: {
+    type: 'postgresql',
+    connectionString: process.env.DATABASE_URL!
+  }
+});
+
+const emailProvider = new SendGridProvider({
+  apiKey: process.env.SENDGRID_API_KEY!,
+  fromEmail: 'noreply@yourapp.com',
+  fromName: 'Your App'
+});
+
+const scheduler = new EmailScheduler(templateManager, emailProvider);
+
+export default async function handler(
+  req: NextApiRequest,
+  res: NextApiResponse
+) {
+  if (req.method !== 'POST') {
+    return res.status(405).json({ error: 'Method not allowed' });
+  }
+
+  const { userEmail, userName } = req.body;
+
+  try {
+    // Find the welcome email template
+    const templates = await templateManager.listTemplates({
+      search: 'Welcome Email'
+    });
+
+    if (templates.length === 0) {
+      return res.status(404).json({ error: 'Welcome template not found' });
+    }
+
+    // Schedule the welcome email
+    const scheduledEmail = {
+      templateId: templates[0].id!,
+      recipientEmail: userEmail,
+      recipientName: userName,
+      variables: {
+        name: userName,
+        app_name: 'My Next.js App'
+      },
+      triggerType: 'immediate' as const,
+      status: 'pending' as const,
+      retryCount: 0,
+      maxRetries: 3,
+      metadata: { source: 'api' }
+    };
+
+    const result = await scheduler.scheduleEmail(scheduledEmail);
+    
+    // Process emails immediately in the background
+    scheduler.processPendingEmails().catch(console.error);
+
+    res.status(200).json({
+      success: true,
+      scheduledEmailId: result.id,
+      message: 'Welcome email scheduled successfully'
+    });
+
+  } catch (error) {
+    console.error('Failed to send welcome email:', error);
+    res.status(500).json({
+      error: 'Failed to schedule welcome email',
+      details: error instanceof Error ? error.message : 'Unknown error'
+    });
+  }
+}
+```
+
+## Environment Configuration
+
+### Python Environment Variables
+
+```bash
+# Database
+DATABASE_URL=postgresql://user:pass@localhost/email_templates
+
+# SendGrid
+SENDGRID_API_KEY=your-sendgrid-api-key
+
+# Security
+ENCRYPTION_KEY=your-secret-encryption-key-32-chars
+
+# Optional: Other providers
+AWS_ACCESS_KEY_ID=your-aws-key
+AWS_SECRET_ACCESS_KEY=your-aws-secret
+AWS_REGION=us-east-1
+```
+
+### Node.js Environment Variables
+
+```bash
+# Database
+DATABASE_URL=postgresql://user:pass@localhost/email_templates
+
+# SendGrid
+SENDGRID_API_KEY=your-sendgrid-api-key
+
+# Security
+ENCRYPTION_KEY=your-secret-encryption-key-32-chars
+
+# Next.js specific
+NEXTAUTH_SECRET=your-nextauth-secret
+```
+
+## Package Development Setup
+
+### Python Development
+
+```bash
+# Clone the repository
+git clone https://github.com/mattbernier/email-template-manager.git
+cd email-template-manager
+
+# Set up Python virtual environment
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install in development mode
+cd packages/python
+pip install -e .[dev]
+
+# Run tests
+pytest
+
+# Run linting
+black .
+isort .
+mypy .
+```
+
+### NPM Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build all packages
+npm run build
+
+# Run tests
+npm test
+
+# Start development mode
+npm run dev
+
+# Lint and format
+npm run lint:fix
+```
+
+## Publishing Packages
+
+### Python Package Publishing
+
+```bash
+# Build the package
+cd packages/python
+python -m build
+
+# Upload to PyPI
+twine upload dist/*
+```
+
+### NPM Package Publishing
+
+```bash
+# Build packages
+npm run build
+
+# Publish with changesets
+npm run release
+```
+
+This setup provides you with fully importable, production-ready packages that you can use across your Python, React, and Next.js applications with comprehensive SendGrid support for all your email template needs! 

package/README.md

@@ -0,0 +1,232 @@
+# Email Template Manager - Universal Email Management Component
+
+## Overview
+
+A framework-agnostic email management library that provides template creation, scheduling, and delivery capabilities with support for React, Next.js, and Python applications. Extracted from the Event Venue Platform project to serve as a reusable component for any application requiring sophisticated email automation.
+
+## Core Features
+
+### 🎨 Template Management
+
+- **Visual Template Editor** - Rich HTML/text editor with live preview
+- **Liquid Template Engine** - Dynamic content with `{{variable}}` syntax
+- **Multi-format Support** - HTML and plain text versions
+- **Template Versioning** - Track changes and rollback capabilities
+- **Theme Support** - Customizable styling per application/tenant
+
+### 📅 Email Scheduling
+
+- **Event-based Triggers** - Schedule emails relative to dates/events
+- **Batch Processing** - Queue and send multiple emails efficiently
+- **Retry Logic** - Automatic retry with exponential backoff
+- **Pause/Resume** - Admin control over scheduled campaigns
+- **Delivery Tracking** - Monitor sent, opened, clicked, bounced
+
+### 🔐 Authentication & Security
+
+- **Magic Link Generation** - Secure token-based authentication
+- **Token Expiration** - Configurable expiry times
+- **One-time Use** - Prevent token reuse
+- **Rate Limiting** - Protect against abuse
+- **Encryption** - Secure token storage and transmission
+
+### 🚀 Multi-platform Support
+
+- **React Components** - Pre-built UI components for template management
+- **Python SDK** - FastAPI/Django integration with ORM models
+- **REST API** - Framework-agnostic HTTP interface
+- **TypeScript Support** - Full type definitions included
+- **Database Agnostic** - Supports PostgreSQL, MySQL, SQLite
+
+## Project Structure
+
+```
+email-template-manager/
+├── packages/
+│   ├── core/              # Core TypeScript/JavaScript library
+│   ├── react/             # React components and hooks
+│   ├── python/            # Python SDK and FastAPI integration
+│   └── api/               # Standalone REST API server
+├── examples/
+│   ├── nextjs-example/    # Next.js integration example
+│   ├── react-example/     # React app example
+│   ├── fastapi-example/   # FastAPI backend example
+│   └── django-example/    # Django integration example
+├── docs/                  # Documentation website
+├── scripts/               # Build and deployment scripts
+└── tests/                 # End-to-end test suites
+```
+
+## Quick Start
+
+### npm/yarn Installation
+
+```bash
+# For React/Next.js projects
+npm install @email-template-manager/react
+npm install @email-template-manager/core
+
+# For Node.js backends
+npm install @email-template-manager/api
+```
+
+### pip Installation
+
+```bash
+# For Python projects
+pip install email-template-manager[fastapi]
+pip install email-template-manager[django]
+```
+
+### CDN Usage
+
+```html
+<!-- For vanilla JavaScript -->
+<script src="https://unpkg.com/@email-template-manager/core@latest/dist/index.js"></script>
+```
+
+## Package Management & Distribution
+
+### NPM Packages
+
+- `@email-template-manager/core` - Core functionality
+- `@email-template-manager/react` - React components
+- `@email-template-manager/api` - Node.js API server
+
+### Python Packages
+
+- `email-template-manager` - Main Python package
+- `email-template-manager[fastapi]` - FastAPI extras
+- `email-template-manager[django]` - Django extras
+
+### Docker Images
+
+- `email-template-manager/api` - Standalone API server
+- `email-template-manager/worker` - Background job processor
+
+## Open Source Setup
+
+### Repository Structure
+
+- **Monorepo** - All packages in single repository with Lerna/Nx
+- **MIT License** - Permissive open source license
+- **Contributing Guidelines** - Clear contribution process
+- **Code of Conduct** - Community standards
+- **Issue Templates** - Bug reports and feature requests
+
+### Development Tools
+
+- **TypeScript** - Type safety across all packages
+- **Jest** - Unit and integration testing
+- **ESLint/Prettier** - Code formatting and linting
+- **Husky** - Git hooks for quality control
+- **Semantic Release** - Automated versioning and publishing
+
+### CI/CD Pipeline
+
+- **GitHub Actions** - Automated testing and deployment
+- **Test Coverage** - Minimum 80% coverage requirement
+- **Security Scanning** - Automated vulnerability detection
+- **Performance Testing** - Load testing for API endpoints
+
+## Supported Integrations
+
+### Email Providers
+
+- **SendGrid** - Primary provider with full feature support
+- **AWS SES** - Cost-effective option for high volume
+- **Mailgun** - Developer-friendly API
+- **Postmark** - Transactional email specialist
+- **SMTP** - Generic SMTP server support
+
+### Databases
+
+- **PostgreSQL** - Recommended for production
+- **MySQL** - Wide compatibility
+- **SQLite** - Development and testing
+- **MongoDB** - Document-based storage option
+
+### Frontend Frameworks
+
+- **React** - Full component library
+- **Next.js** - SSR and API routes integration
+- **Vue.js** - Vue 3 composition API support
+- **Angular** - Angular 12+ compatibility
+- **Svelte** - Lightweight integration
+
+### Backend Frameworks
+
+- **FastAPI** - Python async framework
+- **Django** - Django 3.2+ with admin integration
+- **Express.js** - Node.js middleware
+- **NestJS** - TypeScript decorators support
+- **Spring Boot** - Java integration (community)
+
+## Getting Started Checklist
+
+### For Package Publishing
+
+- [ ] Set up NPM organization (`@email-template-manager`)
+- [ ] Configure automated publishing with semantic-release
+- [ ] Set up PyPI account and package publishing
+- [ ] Create Docker Hub organization for container images
+- [ ] Set up CDN distribution for browser packages
+
+### For Open Source
+
+- [ ] Create GitHub organization
+- [ ] Set up repository with proper README and documentation
+- [ ] Configure issue and PR templates
+- [ ] Set up community health files (CONTRIBUTING.md, CODE_OF_CONDUCT.md)
+- [ ] Enable GitHub Discussions for community support
+- [ ] Set up GitHub Sponsors for project sustainability
+
+### For Documentation
+
+- [ ] Create documentation website (Docusaurus/GitBook)
+- [ ] Write comprehensive API documentation
+- [ ] Create integration guides for each framework
+- [ ] Record video tutorials for common use cases
+- [ ] Set up interactive playground/demo
+
+## License and Legal
+
+- **MIT License** - Permissive open source license allowing commercial use
+- **Contributor License Agreement** - Ensure proper IP assignment
+- **Trademark Guidelines** - Protect project name and logo
+- **Privacy Policy** - For any hosted services or telemetry
+
+## Community and Support
+
+### Communication Channels
+
+- **GitHub Discussions** - Community Q&A and feature requests
+- **Discord Server** - Real-time chat and support
+- **Twitter Account** - Updates and announcements
+- **Blog/Newsletter** - Technical articles and release notes
+
+### Contribution Types
+
+- **Code Contributions** - Bug fixes and new features
+- **Documentation** - Tutorials, guides, and API docs
+- **Testing** - Test cases and bug reports
+- **Translations** - Internationalization support
+- **Design** - UI/UX improvements and assets
+
+## Monorepo Workspaces & Dependency Management
+
+This package is part of a monorepo using npm workspaces. All dependencies are hoisted to the root. Always run `npm install` from the root directory.
+
+## React 19 and Testing Library Compatibility
+
+This package uses React 19.1.0. If you see peer dependency warnings with Testing Library, use:
+
+```bash
+npm install --legacy-peer-deps
+```
+
+This is a temporary workaround until official support is released.
+
+---
+
+This specification provides the foundation for creating a world-class, open source email management solution that can be adopted by developers across multiple platforms and use cases.