@bernierllc/email 1.0.1 → 1.1.0

package/PACKAGE_USAGE.md

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