@contentgrowth/content-emailing 0.1.0

package/src/backend/routes.js

@@ -0,0 +1,98 @@
+/**
+ * Email Routes Factory
+ * Creates a Hono router with admin endpoints for the email system.
+ */
+import { Hono } from 'hono';
+import { EmailService } from './EmailService';
+
+/**
+ * Create email admin routes
+ * @param {Object} env - Environment bindings
+ * @param {Object} config - Configuration
+ * @param {Object} cacheProvider - Optional cache provider
+ * @returns {Hono} Hono router
+ */
+export function createEmailRoutes(env, config = {}, cacheProvider = null) {
+    const app = new Hono();
+    const emailService = new EmailService(env, config, cacheProvider);
+
+    // List all templates
+    app.get('/templates', async (c) => {
+        try {
+            const templates = await emailService.getAllTemplates();
+            return c.json({ success: true, templates });
+        } catch (err) {
+            return c.json({ success: false, error: err.message }, 500);
+        }
+    });
+
+    // Get single template
+    app.get('/templates/:id', async (c) => {
+        try {
+            const template = await emailService.getTemplate(c.req.param('id'));
+            if (!template) return c.json({ success: false, error: 'Template not found' }, 404);
+            return c.json({ success: true, template });
+        } catch (err) {
+            return c.json({ success: false, error: err.message }, 500);
+        }
+    });
+
+    // Create/Update template
+    app.post('/templates', async (c) => {
+        try {
+            const data = await c.req.json();
+            await emailService.saveTemplate(data, 'admin'); // TODO: Pass real user ID
+            return c.json({ success: true, message: 'Template saved' });
+        } catch (err) {
+            return c.json({ success: false, error: err.message }, 500);
+        }
+    });
+
+    // Delete template
+    app.delete('/templates/:id', async (c) => {
+        try {
+            await emailService.deleteTemplate(c.req.param('id'));
+            return c.json({ success: true, message: 'Template deleted' });
+        } catch (err) {
+            return c.json({ success: false, error: err.message }, 500);
+        }
+    });
+
+    // Preview template
+    app.post('/templates/:id/preview', async (c) => {
+        try {
+            const id = c.req.param('id');
+            const data = await c.req.json(); // Variables
+            const result = await emailService.renderTemplate(id, data);
+            return c.json({ success: true, preview: result });
+        } catch (err) {
+            return c.json({ success: false, error: err.message }, 500);
+        }
+    });
+
+    // Send test email
+    app.post('/templates/:id/test', async (c) => {
+        try {
+            const id = c.req.param('id');
+            const { to, data } = await c.req.json();
+
+            const { subject, html, plainText } = await emailService.renderTemplate(id, data);
+            const result = await emailService.sendEmail({
+                to,
+                subject: `[TEST] ${subject}`,
+                html,
+                text: plainText
+            });
+
+            if (result.success) {
+                return c.json({ success: true, message: 'Test email sent' });
+            } else {
+                return c.json({ success: false, error: result.error }, 500);
+            }
+        } catch (err) {
+            return c.json({ success: false, error: err.message }, 500);
+        }
+    });
+
+    return app;
+}

package/src/common/htmlWrapper.js

@@ -0,0 +1,169 @@
+/**
+ * HTML Email Wrapper
+ * Full styled HTML template for wrapping email content
+ */
+
+/**
+ * Wrap content HTML in email template with styling
+ * @param {string} contentHtml - The HTML content to wrap
+ * @param {string} subject - Email subject for the title
+ * @param {Object} data - Template data (portalUrl, unsubscribeUrl, etc.)
+ * @returns {string} Complete HTML email
+ */
+export function wrapInEmailTemplate(contentHtml, subject, data = {}) {
+    const portalUrl = data.portalUrl || 'https://app.x0start.com';
+    const unsubscribeUrl = data.unsubscribeUrl || '{{unsubscribe_url}}';
+    const brandName = data.brandName || 'X0 Start';
+
+    return `
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${subject}</title>
+  <style>
+    body {
+      margin: 0;
+      padding: 0;
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
+      background-color: #f5f5f5;
+      line-height: 1.6;
+    }
+    .email-wrapper {
+      background-color: #f5f5f5;
+      padding: 40px 20px;
+    }
+    .email-container {
+      max-width: 600px;
+      margin: 0 auto;
+      background-color: #ffffff;
+      border-radius: 8px;
+      overflow: hidden;
+      box-shadow: 0 2px 8px rgba(0,0,0,0.1);
+    }
+    .email-header {
+      padding: 40px 40px 20px;
+      text-align: center;
+      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+      color: #ffffff;
+    }
+    .email-header h1 {
+      margin: 0;
+      font-size: 28px;
+      font-weight: 600;
+    }
+    .email-content {
+      padding: 30px 40px;
+      color: #333333;
+    }
+    .email-content h1 {
+      font-size: 24px;
+      margin-top: 0;
+      margin-bottom: 20px;
+      color: #333333;
+    }
+    .email-content h2 {
+      font-size: 20px;
+      margin-top: 30px;
+      margin-bottom: 15px;
+      color: #333333;
+    }
+    .email-content h3 {
+      font-size: 16px;
+      margin-top: 20px;
+      margin-bottom: 10px;
+      color: #333333;
+    }
+    .email-content p {
+      margin: 0 0 15px;
+      color: #666666;
+    }
+    .email-content a {
+      color: #667eea;
+      text-decoration: none;
+    }
+    .email-content ul, .email-content ol {
+      margin: 0 0 15px;
+      padding-left: 25px;
+    }
+    .email-content li {
+      margin-bottom: 8px;
+      color: #666666;
+    }
+    .email-content blockquote {
+      margin: 20px 0;
+      padding: 15px 20px;
+      background-color: #f8f9fa;
+      border-left: 4px solid #667eea;
+      color: #666666;
+    }
+    .email-content code {
+      padding: 2px 6px;
+      background-color: #f8f9fa;
+      border-radius: 3px;
+      font-family: 'Courier New', monospace;
+      font-size: 14px;
+    }
+    .email-content pre {
+      padding: 15px;
+      background-color: #f8f9fa;
+      border-radius: 6px;
+      overflow-x: auto;
+    }
+    .email-content pre code {
+      padding: 0;
+      background: none;
+    }
+    .btn {
+      display: inline-block;
+      padding: 12px 24px;
+      background-color: #667eea;
+      color: #ffffff !important;
+      text-decoration: none;
+      border-radius: 6px;
+      font-weight: 600;
+      margin: 10px 0;
+    }
+    .btn:hover {
+      background-color: #5568d3;
+    }
+    .email-footer {
+      padding: 20px 40px;
+      background-color: #f8f9fa;
+      text-align: center;
+      font-size: 12px;
+      color: #666666;
+    }
+    .email-footer a {
+      color: #667eea;
+      text-decoration: none;
+    }
+    hr {
+      border: none;
+      border-top: 1px solid #e0e0e0;
+      margin: 30px 0;
+    }
+  </style>
+</head>
+<body>
+  <div class="email-wrapper">
+    <div class="email-container">
+      <div class="email-content">
+        ${contentHtml}
+      </div>
+      <div class="email-footer">
+        <p style="margin: 0 0 10px;">
+          You're receiving this email from ${brandName}.
+        </p>
+        <p style="margin: 0;">
+          <a href="${unsubscribeUrl}">Unsubscribe</a> | 
+          <a href="${portalUrl}/settings/notifications">Manage Preferences</a>
+        </p>
+      </div>
+    </div>
+  </div>
+</body>
+</html>
+  `.trim();
+}

package/src/common/index.js

@@ -0,0 +1,11 @@
+/**
+ * Common exports
+ */
+export { wrapInEmailTemplate } from './htmlWrapper.js';
+export {
+    getWebsiteUrl,
+    resetWebsiteUrlCache,
+    encodeTrackingLinks,
+    markdownToPlainText,
+    extractVariables
+} from './utils.js';

package/src/common/utils.js

@@ -0,0 +1,117 @@
+/**
+ * Email Utility Functions
+ * Common helpers for email processing
+ */
+
+// Module-level cache for website URL
+let cachedWebsiteUrl = null;
+
+/**
+ * Build website URL based on environment configuration (with caching)
+ * @param {Object} env - Environment bindings
+ * @returns {string} Website URL (e.g., 'https://www.x0start.com')
+ */
+export function getWebsiteUrl(env) {
+    if (cachedWebsiteUrl) {
+        return cachedWebsiteUrl;
+    }
+
+    const domain = env.DOMAIN || 'x0start.com';
+    const isDev = env.ENVIRONMENT === 'development' || !env.ENVIRONMENT;
+    const protocol = isDev ? 'http' : 'https';
+
+    cachedWebsiteUrl = `${protocol}://www.${domain}`;
+
+    return cachedWebsiteUrl;
+}
+
+/**
+ * Reset the cached website URL (for testing or config changes)
+ */
+export function resetWebsiteUrlCache() {
+    cachedWebsiteUrl = null;
+}
+
+/**
+ * Encode all links in HTML to go through tracking redirect
+ * @param {string} html - HTML content with links
+ * @param {string} sendId - Unique send ID for tracking
+ * @param {Object} env - Environment bindings (optional, for auto-detecting URL)
+ * @param {string} websiteUrl - Base website URL (optional, overrides env detection)
+ * @returns {string} HTML with encoded tracking links
+ */
+export function encodeTrackingLinks(html, sendId, env = null, websiteUrl = null) {
+    const baseUrl = websiteUrl || (env ? getWebsiteUrl(env) : 'https://www.x0start.com');
+
+    // Helper to decode HTML entities
+    const decodeHtmlEntities = (text) => {
+        return text
+            .replace(///g, '/')
+            .replace(/:/g, ':')
+            .replace(/&/g, '&')
+            .replace(/&lt;/g, '<')
+            .replace(/&gt;/g, '>')
+            .replace(/&quot;/g, '"')
+            .replace(/&#39;/g, "'");
+    };
+
+    // Replace all href attributes with tracking URLs
+    return html.replace(/href="([^"]+)"/g, (match, url) => {
+        // Skip certain URLs that shouldn't be tracked
+        if (
+            url.startsWith('mailto:') ||
+            url.startsWith('tel:') ||
+            url.startsWith('#') ||
+            url.includes('{{') || // Skip template variables
+            url.includes('/email/unsubscribe/') ||
+            url.includes('/email/track/')
+        ) {
+            return match;
+        }
+
+        // Decode HTML entities first (marked encodes URLs with HTML entities)
+        const decodedUrl = decodeHtmlEntities(url);
+
+        // Encode the decoded URL in base64
+        const encodedUrl = Buffer.from(decodedUrl).toString('base64');
+
+        // Create tracking redirect URL
+        const trackingUrl = `${baseUrl}/r/${sendId}?url=${encodedUrl}`;
+
+        return `href="${trackingUrl}"`;
+    });
+}
+
+/**
+ * Convert markdown to plain text
+ * @param {string} markdown - Markdown content
+ * @returns {string} Plain text version
+ */
+export function markdownToPlainText(markdown) {
+    return markdown
+        .replace(/#{1,6}\s+/g, '') // Remove headers
+        .replace(/\*\*(.+?)\*\*/g, '$1') // Remove bold
+        .replace(/\*(.+?)\*/g, '$1') // Remove italic
+        .replace(/\[(.+?)\]\((.+?)\)/g, '$1: $2') // Keep both link text and URL
+        .replace(/`(.+?)`/g, '$1') // Remove code
+        .replace(/>\s+/g, '') // Remove blockquotes
+        .replace(/\n{3,}/g, '\n\n') // Normalize line breaks
+        .trim();
+}
+
+/**
+ * Extract variables from a template string
+ * @param {string} template - Template with {{variable}} placeholders
+ * @returns {string[]} Array of variable names found
+ */
+export function extractVariables(template) {
+    const regex = /\{\{([^}]+)\}\}/g;
+    const variables = new Set();
+    let match;
+
+    while ((match = regex.exec(template)) !== null) {
+        variables.add(match[1].trim());
+    }
+
+    return Array.from(variables);
+}

package/src/frontend/TemplateEditor.jsx

@@ -0,0 +1,117 @@
+import React, { useState, useEffect } from 'react';
+import { Save, X, Eye, AlertCircle } from 'lucide-react';
+
+export const TemplateEditor = ({
+    initialData,
+    onSave,
+    onCancel,
+    onPreview,
+    variablesHelpText = 'Supports {{variable}}'
+}) => {
+    const [formData, setFormData] = useState({
+        template_id: '',
+        template_name: '',
+        template_type: 'daily_reminder',
+        subject_template: '',
+        body_markdown: '',
+        variables: '[]',
+        description: '',
+        is_active: 1,
+        ...initialData
+    });
+
+    const handleSubmit = (e) => {
+        e.preventDefault();
+        onSave(formData);
+    };
+
+    return (
+        <div className="fixed inset-0 bg-black bg-opacity-50 flex items-center justify-center z-50 p-4">
+            <div className="bg-white rounded-lg shadow-xl max-w-4xl w-full max-h-[90vh] overflow-hidden flex flex-col">
+                <div className="p-6 border-b border-gray-200 flex justify-between items-center">
+                    <h2 className="text-xl font-bold text-gray-900">
+                        {initialData ? 'Edit Template' : 'New Template'}
+                    </h2>
+                    <button onClick={onCancel} className="p-2 hover:bg-gray-100 rounded-lg">
+                        <X className="h-5 w-5" />
+                    </button>
+                </div>
+
+                <form onSubmit={handleSubmit} className="flex-1 overflow-y-auto p-6 space-y-4">
+                    <div className="grid grid-cols-2 gap-4">
+                        <div>
+                            <label className="block text-sm font-medium text-gray-700 mb-1">Template ID *</label>
+                            <input
+                                type="text"
+                                required
+                                disabled={!!initialData}
+                                value={formData.template_id}
+                                onChange={e => setFormData({ ...formData, template_id: e.target.value })}
+                                className="w-full px-3 py-2 border border-gray-300 rounded-lg focus:ring-2 focus:ring-blue-500 disabled:bg-gray-100"
+                            />
+                        </div>
+                        <div>
+                            <label className="block text-sm font-medium text-gray-700 mb-1">Name *</label>
+                            <input
+                                type="text"
+                                required
+                                value={formData.template_name}
+                                onChange={e => setFormData({ ...formData, template_name: e.target.value })}
+                                className="w-full px-3 py-2 border border-gray-300 rounded-lg focus:ring-2 focus:ring-blue-500"
+                            />
+                        </div>
+                    </div>
+
+                    <div>
+                        <label className="block text-sm font-medium text-gray-700 mb-1">Subject *</label>
+                        <input
+                            type="text"
+                            required
+                            value={formData.subject_template}
+                            onChange={e => setFormData({ ...formData, subject_template: e.target.value })}
+                            className="w-full px-3 py-2 border border-gray-300 rounded-lg focus:ring-2 focus:ring-blue-500"
+                        />
+                        <p className="text-xs text-gray-500 mt-1">{variablesHelpText}</p>
+                    </div>
+
+                    <div>
+                        <label className="block text-sm font-medium text-gray-700 mb-1">Body (Markdown) *</label>
+                        <textarea
+                            required
+                            rows={12}
+                            value={formData.body_markdown}
+                            onChange={e => setFormData({ ...formData, body_markdown: e.target.value })}
+                            className="w-full px-3 py-2 border border-gray-300 rounded-lg focus:ring-2 focus:ring-blue-500 font-mono text-sm"
+                        />
+                    </div>
+
+                    <div className="flex justify-between pt-4">
+                        <button
+                            type="button"
+                            onClick={() => onPreview && onPreview(formData)}
+                            className="flex items-center gap-2 px-4 py-2 bg-gray-100 text-gray-700 rounded-lg hover:bg-gray-200"
+                        >
+                            <Eye className="h-4 w-4" /> Preview
+                        </button>
+
+                        <div className="flex gap-2">
+                            <button
+                                type="button"
+                                onClick={onCancel}
+                                className="px-4 py-2 border border-gray-300 text-gray-700 rounded-lg hover:bg-gray-50"
+                            >
+                                Cancel
+                            </button>
+                            <button
+                                type="submit"
+                                className="flex items-center gap-2 px-4 py-2 bg-blue-600 text-white rounded-lg hover:bg-blue-700"
+                            >
+                                <Save className="h-4 w-4" /> Save
+                            </button>
+                        </div>
+                    </div>
+                </form>
+            </div>
+        </div>
+    );
+};

package/src/frontend/TemplateManager.jsx

@@ -0,0 +1,117 @@
+import React, { useState, useEffect } from 'react';
+import { Plus, Edit2, Trash2, Mail, Loader } from 'lucide-react';
+import { TemplateEditor } from './TemplateEditor';
+
+export const TemplateManager = ({
+    apiClient,
+    title = 'Email Templates',
+    description = 'Manage your email templates'
+}) => {
+    const [templates, setTemplates] = useState([]);
+    const [loading, setLoading] = useState(true);
+    const [showEditor, setShowEditor] = useState(false);
+    const [editingTemplate, setEditingTemplate] = useState(null);
+
+    useEffect(() => {
+        loadTemplates();
+    }, []);
+
+    const loadTemplates = async () => {
+        try {
+            setLoading(true);
+            const res = await apiClient.get('/templates');
+            if (res.data.success) {
+                setTemplates(res.data.templates);
+            }
+        } catch (err) {
+            console.error('Failed to load templates:', err);
+        } finally {
+            setLoading(false);
+        }
+    };
+
+    const handleSave = async (formData) => {
+        try {
+            await apiClient.post('/templates', formData);
+            setShowEditor(false);
+            loadTemplates();
+        } catch (err) {
+            console.error('Failed to save template:', err);
+            alert('Failed to save template');
+        }
+    };
+
+    const handleDelete = async (id) => {
+        if (!confirm('Delete this template?')) return;
+        try {
+            await apiClient.delete(`/templates/${id}`);
+            loadTemplates();
+        } catch (err) {
+            console.error('Failed to delete:', err);
+            alert('Failed to delete template');
+        }
+    };
+
+    return (
+        <div className="email-template-manager">
+            <div className="flex justify-between items-center mb-6">
+                <div>
+                    <h1 className="text-2xl font-bold text-gray-900">{title}</h1>
+                    <p className="text-gray-600 mt-1">{description}</p>
+                </div>
+                <button
+                    onClick={() => { setEditingTemplate(null); setShowEditor(true); }}
+                    className="flex items-center gap-2 px-4 py-2 bg-blue-600 text-white rounded-lg hover:bg-blue-700"
+                >
+                    <Plus className="h-4 w-4" /> New Template
+                </button>
+            </div>
+
+            {loading ? (
+                <div className="flex justify-center p-12"><Loader className="animate-spin text-gray-500" /></div>
+            ) : (
+                <div className="grid gap-4">
+                    {templates.map(t => (
+                        <div key={t.template_id} className="bg-white border rounded-lg p-6 flex justify-between items-start hover:shadow-md transition">
+                            <div>
+                                <div className="flex items-center gap-3 mb-2">
+                                    <Mail className="h-5 w-5 text-blue-600" />
+                                    <h3 className="text-lg font-semibold">{t.template_name}</h3>
+                                    <span className="px-2 py-1 text-xs bg-gray-100 rounded">{t.template_type}</span>
+                                </div>
+                                <p className="text-sm text-gray-600">{t.description}</p>
+                            </div>
+                            <div className="flex gap-2">
+                                <button
+                                    onClick={() => { setEditingTemplate(t); setShowEditor(true); }}
+                                    className="p-2 text-blue-600 hover:bg-blue-50 rounded"
+                                >
+                                    <Edit2 className="h-4 w-4" />
+                                </button>
+                                <button
+                                    onClick={() => handleDelete(t.template_id)}
+                                    className="p-2 text-red-600 hover:bg-red-50 rounded"
+                                >
+                                    <Trash2 className="h-4 w-4" />
+                                </button>
+                            </div>
+                        </div>
+                    ))}
+                    {templates.length === 0 && (
+                        <div className="text-center py-12 text-gray-500 bg-gray-50 rounded border-dashed border-2">
+                            No templates found. Create one to get started.
+                        </div>
+                    )}
+                </div>
+            )}
+
+            {showEditor && (
+                <TemplateEditor
+                    initialData={editingTemplate}
+                    onSave={handleSave}
+                    onCancel={() => setShowEditor(false)}
+                />
+            )}
+        </div>
+    );
+};

package/src/index.js

@@ -0,0 +1,24 @@
+// Backend services
+export { EmailService } from './backend/EmailService.js';
+export { EmailTemplateCacheDO, createDOCacheProvider } from './backend/EmailTemplateCacheDO.js';
+
+// Routes
+export {
+    createEmailRoutes,
+    createTemplateRoutes,
+    createTrackingRoutes
+} from './backend/routes/index.js';
+
+// Common utilities
+export {
+    wrapInEmailTemplate,
+    getWebsiteUrl,
+    resetWebsiteUrlCache,
+    encodeTrackingLinks,
+    markdownToPlainText,
+    extractVariables
+} from './common/index.js';
+
+// Frontend components
+export { TemplateManager } from './frontend/TemplateManager.jsx';
+export { TemplateEditor } from './frontend/TemplateEditor.jsx';