@contentgrowth/content-emailing 0.1.0

package/src/backend/EmailTemplateCacheDO.js

@@ -0,0 +1,363 @@
+/**
+ * EmailTemplateCacheDO - Optional read-through cache for email templates
+ * 
+ * This is a Cloudflare Durable Object that provides caching for email templates.
+ * It is OPTIONAL - to use it, add to your wrangler.toml/wrangler.json:
+ * 
+ * [[durable_objects.bindings]]
+ * name = "EMAIL_TEMPLATE_CACHE"
+ * class_name = "EmailTemplateCacheDO"
+ * 
+ * [[migrations]]
+ * tag = "v1"
+ * new_classes = ["EmailTemplateCacheDO"]
+ * 
+ * Then pass the DO stub as cacheProvider to EmailService:
+ * 
+ * const cacheProvider = createDOCacheProvider(env.EMAIL_TEMPLATE_CACHE);
+ * const emailService = new EmailService(env, config, cacheProvider);
+ * 
+ * Caching strategy:
+ * - READ: Check cache → if miss, load from D1 and cache
+ * - WRITE: Update D1 directly → invalidate cache → next read refreshes
+ * 
+ * Cache key: template_id
+ * TTL: 1 hour (templates rarely change)
+ */
+export class EmailTemplateCacheDO {
+    constructor(state, env) {
+        this.state = state;
+        this.env = env;
+        this.cache = new Map(); // templateId -> { data, timestamp }
+        this.settingsCache = null; // { data, timestamp }
+        this.cacheTTL = 3600000; // 1 hour in milliseconds
+    }
+
+    /**
+     * Handle HTTP requests to this Durable Object
+     */
+    async fetch(request) {
+        const url = new URL(request.url);
+        const path = url.pathname;
+
+        try {
+            if (path === '/get' && request.method === 'GET') {
+                return this.handleGet(request);
+            } else if (path === '/getSettings' && request.method === 'GET') {
+                return this.handleGetSettings(request);
+            } else if (path === '/invalidate' && request.method === 'POST') {
+                return this.handleInvalidate(request);
+            } else if (path === '/clear' && request.method === 'POST') {
+                return this.handleClear(request);
+            } else if (path === '/stats' && request.method === 'GET') {
+                return this.handleStats(request);
+            } else {
+                return new Response('Not Found', { status: 404 });
+            }
+        } catch (error) {
+            console.error('[EmailTemplateCacheDO] Error:', error);
+            return new Response(JSON.stringify({ error: error.message }), {
+                status: 500,
+                headers: { 'Content-Type': 'application/json' },
+            });
+        }
+    }
+
+    /**
+     * Get template (from cache or D1)
+     * Query params:
+     * - templateId: Template ID to fetch
+     * - refresh: Force refresh from D1 (optional)
+     */
+    async handleGet(request) {
+        const url = new URL(request.url);
+        const templateId = url.searchParams.get('templateId');
+        const forceRefresh = url.searchParams.get('refresh') === 'true';
+
+        if (!templateId) {
+            return new Response(JSON.stringify({ error: 'templateId is required' }), {
+                status: 400,
+                headers: { 'Content-Type': 'application/json' },
+            });
+        }
+
+        // Check cache (unless force refresh)
+        if (!forceRefresh) {
+            const cached = this.cache.get(templateId);
+            if (cached && Date.now() - cached.timestamp < this.cacheTTL) {
+                console.log('[EmailTemplateCacheDO] Cache HIT:', templateId);
+                return new Response(JSON.stringify({
+                    template: cached.data,
+                    cached: true,
+                    age: Date.now() - cached.timestamp,
+                }), {
+                    headers: { 'Content-Type': 'application/json' },
+                });
+            }
+        }
+
+        // Cache miss or expired - fetch from D1
+        console.log('[EmailTemplateCacheDO] Cache MISS - fetching from D1:', templateId);
+        const template = await this.fetchTemplateFromD1(templateId);
+
+        if (!template) {
+            return new Response(JSON.stringify({
+                error: 'Template not found',
+                templateId
+            }), {
+                status: 404,
+                headers: { 'Content-Type': 'application/json' },
+            });
+        }
+
+        // Cache the result
+        this.cache.set(templateId, {
+            data: template,
+            timestamp: Date.now(),
+        });
+
+        return new Response(JSON.stringify({
+            template,
+            cached: false,
+        }), {
+            headers: { 'Content-Type': 'application/json' },
+        });
+    }
+
+    /**
+     * Get system settings from cache
+     */
+    async handleGetSettings(request) {
+        const url = new URL(request.url);
+        const forceRefresh = url.searchParams.get('refresh') === 'true';
+
+        // Check cache
+        if (!forceRefresh && this.settingsCache && Date.now() - this.settingsCache.timestamp < this.cacheTTL) {
+            return new Response(JSON.stringify({
+                settings: this.settingsCache.data,
+                cached: true,
+                age: Date.now() - this.settingsCache.timestamp,
+            }), {
+                headers: { 'Content-Type': 'application/json' },
+            });
+        }
+
+        // Fetch from D1
+        const settings = await this.fetchSettingsFromD1();
+
+        this.settingsCache = {
+            data: settings,
+            timestamp: Date.now(),
+        };
+
+        return new Response(JSON.stringify({
+            settings,
+            cached: false,
+        }), {
+            headers: { 'Content-Type': 'application/json' },
+        });
+    }
+
+    /**
+     * Invalidate specific template(s) from cache
+     * Body: { templateId: 'template_id' } or { templateId: '*' } for all
+     */
+    async handleInvalidate(request) {
+        const body = await request.json();
+        const { templateId, settings } = body;
+
+        if (settings) {
+            this.settingsCache = null;
+            console.log('[EmailTemplateCacheDO] Invalidated settings cache');
+            return new Response(JSON.stringify({
+                success: true,
+                message: 'Settings cache invalidated',
+            }), {
+                headers: { 'Content-Type': 'application/json' },
+            });
+        }
+
+        if (!templateId) {
+            return new Response(JSON.stringify({ error: 'templateId or settings flag is required' }), {
+                status: 400,
+                headers: { 'Content-Type': 'application/json' },
+            });
+        }
+
+        if (templateId === '*') {
+            // Invalidate all templates
+            const count = this.cache.size;
+            this.cache.clear();
+            console.log('[EmailTemplateCacheDO] Invalidated ALL templates:', count);
+            return new Response(JSON.stringify({
+                success: true,
+                message: `Invalidated ${count} templates`,
+            }), {
+                headers: { 'Content-Type': 'application/json' },
+            });
+        }
+
+        // Invalidate specific template
+        const existed = this.cache.has(templateId);
+        this.cache.delete(templateId);
+        console.log('[EmailTemplateCacheDO] Invalidated template:', templateId, existed ? '(existed)' : '(not in cache)');
+
+        return new Response(JSON.stringify({
+            success: true,
+            message: existed ? 'Template invalidated' : 'Template was not in cache',
+            templateId,
+        }), {
+            headers: { 'Content-Type': 'application/json' },
+        });
+    }
+
+    /**
+     * Clear entire cache (admin operation)
+     */
+    async handleClear(request) {
+        const count = this.cache.size;
+        this.cache.clear();
+        this.settingsCache = null;
+        console.log('[EmailTemplateCacheDO] Cache cleared:', count, 'entries');
+
+        return new Response(JSON.stringify({
+            success: true,
+            message: `Cleared ${count} cached templates and settings`,
+        }), {
+            headers: { 'Content-Type': 'application/json' },
+        });
+    }
+
+    /**
+     * Get cache statistics
+     */
+    async handleStats(request) {
+        const stats = {
+            cacheSize: this.cache.size,
+            cacheTTL: this.cacheTTL,
+            hasSettingsCache: !!this.settingsCache,
+            templates: [],
+        };
+
+        const now = Date.now();
+        for (const [templateId, entry] of this.cache.entries()) {
+            stats.templates.push({
+                templateId,
+                age: now - entry.timestamp,
+                expired: now - entry.timestamp > this.cacheTTL,
+            });
+        }
+
+        return new Response(JSON.stringify(stats), {
+            headers: { 'Content-Type': 'application/json' },
+        });
+    }
+
+    /**
+     * Fetch template from D1
+     */
+    async fetchTemplateFromD1(templateId) {
+        const db = this.env.DB;
+        const template = await db
+            .prepare(`SELECT * FROM system_email_templates WHERE template_id = ? AND is_active = 1`)
+            .bind(templateId)
+            .first();
+
+        return template;
+    }
+
+    /**
+     * Fetch settings from D1
+     */
+    async fetchSettingsFromD1() {
+        const db = this.env.DB;
+        const settings = await db
+            .prepare(`SELECT setting_key, setting_value FROM system_settings`)
+            .all();
+
+        const config = {};
+        if (settings.results) {
+            settings.results.forEach((row) => {
+                config[row.setting_key] = row.setting_value;
+            });
+        }
+        return config;
+    }
+}
+
+/**
+ * Create a cache provider wrapper for the DO
+ * This adapts the DO interface to the simpler interface expected by EmailService
+ * 
+ * @param {DurableObjectStub} doStub - The DO stub from env.EMAIL_TEMPLATE_CACHE
+ * @returns {Object} Cache provider interface
+ */
+export function createDOCacheProvider(doStub) {
+    if (!doStub) {
+        return null;
+    }
+
+    const stub = doStub.get(doStub.idFromName('global'));
+
+    return {
+        async getTemplate(templateId) {
+            try {
+                const response = await stub.fetch(`http://do/get?templateId=${templateId}`);
+                const data = await response.json();
+                return data.template || null;
+            } catch (e) {
+                console.warn('[DOCacheProvider] Failed to get template:', e);
+                return null;
+            }
+        },
+
+        async getSettings() {
+            try {
+                const response = await stub.fetch('http://do/getSettings');
+                const data = await response.json();
+                return data.settings || null;
+            } catch (e) {
+                console.warn('[DOCacheProvider] Failed to get settings:', e);
+                return null;
+            }
+        },
+
+        async putTemplate(template) {
+            // DO uses invalidation, not direct puts
+            // Invalidate so next read refreshes from D1
+            try {
+                await stub.fetch('http://do/invalidate', {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ templateId: template.template_id }),
+                });
+            } catch (e) {
+                console.warn('[DOCacheProvider] Failed to invalidate template:', e);
+            }
+        },
+
+        async deleteTemplate(templateId) {
+            try {
+                await stub.fetch('http://do/invalidate', {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ templateId }),
+                });
+            } catch (e) {
+                console.warn('[DOCacheProvider] Failed to invalidate template:', e);
+            }
+        },
+
+        async invalidateSettings() {
+            try {
+                await stub.fetch('http://do/invalidate', {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ settings: true }),
+                });
+            } catch (e) {
+                console.warn('[DOCacheProvider] Failed to invalidate settings:', e);
+            }
+        },
+    };
+}

package/src/backend/routes/index.js

@@ -0,0 +1,30 @@
+/**
+ * Email Routes Index
+ * Aggregates and exports all route factories
+ */
+import { Hono } from 'hono';
+import { createTemplateRoutes } from './templates.js';
+import { createTrackingRoutes } from './tracking.js';
+
+// Re-export individual route factories
+export { createTemplateRoutes } from './templates.js';
+export { createTrackingRoutes } from './tracking.js';
+
+/**
+ * Create combined email routes
+ * @param {Object} env - Environment bindings
+ * @param {Object} config - Configuration
+ * @param {Object} cacheProvider - Optional cache provider
+ * @returns {Hono} Combined Hono router
+ */
+export function createEmailRoutes(env, config = {}, cacheProvider = null) {
+    const app = new Hono();
+
+    // Mount template routes at /api/email
+    app.route('/api/email', createTemplateRoutes(env, config, cacheProvider));
+
+    // Mount tracking routes at /email
+    app.route('/email', createTrackingRoutes(env, config));
+
+    return app;
+}

package/src/backend/routes/templates.js

@@ -0,0 +1,98 @@
+/**
+ * Email Template Routes Factory
+ * Creates a Hono router with admin endpoints for template management.
+ */
+import { Hono } from 'hono';
+import { EmailService } from '../EmailService.js';
+
+/**
+ * Create email template routes
+ * @param {Object} env - Environment bindings
+ * @param {Object} config - Configuration
+ * @param {Object} cacheProvider - Optional cache provider
+ * @returns {Hono} Hono router
+ */
+export function createTemplateRoutes(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/backend/routes/tracking.js

@@ -0,0 +1,215 @@
+/**
+ * Email Tracking Routes Factory
+ * Creates a Hono router with tracking endpoints for the email system.
+ */
+import { Hono } from 'hono';
+
+// 1x1 transparent GIF pixel
+const TRACKING_PIXEL = new Uint8Array([
+    0x47, 0x49, 0x46, 0x38, 0x39, 0x61, 0x01, 0x00, 0x01, 0x00,
+    0x80, 0x00, 0x00, 0x00, 0x00, 0x00, 0xFF, 0xFF, 0xFF, 0x21,
+    0xF9, 0x04, 0x01, 0x00, 0x00, 0x00, 0x00, 0x2C, 0x00, 0x00,
+    0x00, 0x00, 0x01, 0x00, 0x01, 0x00, 0x00, 0x02, 0x01, 0x44,
+    0x00, 0x3B
+]);
+
+/**
+ * Create email tracking routes
+ * @param {Object} env - Environment bindings
+ * @param {Object} config - Configuration
+ * @param {string} [config.tableNamePrefix='system_email_'] - Prefix for D1 tables
+ * @returns {Hono} Hono router
+ */
+export function createTrackingRoutes(env, config = {}) {
+    const app = new Hono();
+    const db = env.DB;
+    const tablePrefix = config.tableNamePrefix || 'system_email_';
+
+    /**
+     * GET /track/open/:token
+     * Track email opens via a 1x1 pixel
+     */
+    app.get('/track/open/:token', async (c) => {
+        const token = c.req.param('token');
+
+        try {
+            const sendId = token;
+
+            // Look up the send record
+            const send = await db
+                .prepare(`SELECT * FROM ${tablePrefix}sends WHERE send_id = ?`)
+                .bind(sendId)
+                .first();
+
+            if (send) {
+                // Log the open event
+                const eventId = crypto.randomUUID();
+                const now = Math.floor(Date.now() / 1000);
+
+                await db
+                    .prepare(
+                        `INSERT INTO ${tablePrefix}events (
+              event_id, send_id, user_id, tenant_id, email_kind, event_type, metadata, created_at
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`
+                    )
+                    .bind(
+                        eventId,
+                        sendId,
+                        send.user_id,
+                        send.tenant_id,
+                        send.email_kind,
+                        'opened',
+                        JSON.stringify({
+                            user_agent: c.req.header('user-agent'),
+                            referer: c.req.header('referer'),
+                        }),
+                        now
+                    )
+                    .run();
+            }
+        } catch (error) {
+            console.error('[EmailTracking] Error tracking email open:', error);
+            // Don't fail the request - just serve the pixel
+        }
+
+        // Always return the tracking pixel
+        return new Response(TRACKING_PIXEL, {
+            headers: {
+                'Content-Type': 'image/gif',
+                'Cache-Control': 'no-cache, no-store, must-revalidate',
+                'Pragma': 'no-cache',
+                'Expires': '0',
+            },
+        });
+    });
+
+    /**
+     * POST /track/click/:token
+     * Track email clicks
+     */
+    app.post('/track/click/:token', async (c) => {
+        const token = c.req.param('token');
+
+        let url;
+        try {
+            const body = await c.req.json();
+            url = body.url;
+        } catch {
+            return c.json({ success: false, error: 'Invalid request body' }, 400);
+        }
+
+        if (!url) {
+            return c.json({ success: false, error: 'Missing URL' }, 400);
+        }
+
+        try {
+            const sendId = token;
+
+            // Look up the send record
+            const send = await db
+                .prepare(`SELECT * FROM ${tablePrefix}sends WHERE send_id = ?`)
+                .bind(sendId)
+                .first();
+
+            if (send) {
+                // Log the click event
+                const eventId = crypto.randomUUID();
+                const now = Math.floor(Date.now() / 1000);
+
+                await db
+                    .prepare(
+                        `INSERT INTO ${tablePrefix}events (
+              event_id, send_id, user_id, tenant_id, email_kind, event_type, metadata, created_at
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`
+                    )
+                    .bind(
+                        eventId,
+                        sendId,
+                        send.user_id,
+                        send.tenant_id,
+                        send.email_kind,
+                        'clicked',
+                        JSON.stringify({
+                            url: url,
+                            user_agent: c.req.header('user-agent'),
+                            referer: c.req.header('referer'),
+                        }),
+                        now
+                    )
+                    .run();
+            }
+
+            return c.json({ success: true, tracked: !!send });
+        } catch (error) {
+            console.error('[EmailTracking] Error tracking email click:', error);
+            return c.json({ success: false, error: 'Failed to track click' }, 500);
+        }
+    });
+
+    /**
+     * GET /unsubscribe/:token
+     * Unsubscribe a user from all email notifications
+     */
+    app.get('/unsubscribe/:token', async (c) => {
+        const unsubToken = c.req.param('token');
+
+        try {
+            // Find the user by their unsubscribe token
+            const prefs = await db
+                .prepare(`SELECT * FROM ${tablePrefix}preferences WHERE unsub_token = ?`)
+                .bind(unsubToken)
+                .first();
+
+            if (!prefs) {
+                return c.json({ success: false, error: 'Invalid unsubscribe link' }, 404);
+            }
+
+            // Check if already unsubscribed
+            const currentSettings = JSON.parse(prefs.email_settings || '{}');
+            const alreadyUnsubscribed = Object.keys(currentSettings).length === 0;
+
+            if (!alreadyUnsubscribed) {
+                // Disable all email types by setting email_settings to empty object
+                const now = Math.floor(Date.now() / 1000);
+                await db
+                    .prepare(
+                        `UPDATE ${tablePrefix}preferences 
+             SET email_settings = '{}',
+                 updated_at = ?
+             WHERE unsub_token = ?`
+                    )
+                    .bind(now, unsubToken)
+                    .run();
+
+                // Log the unsubscribe event
+                const eventId = crypto.randomUUID();
+                await db
+                    .prepare(
+                        `INSERT INTO ${tablePrefix}events (
+              event_id, send_id, user_id, tenant_id, email_kind, event_type, metadata, created_at
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`
+                    )
+                    .bind(
+                        eventId,
+                        'unsubscribe',
+                        prefs.user_id,
+                        prefs.tenant_id,
+                        'all',
+                        'unsubscribed',
+                        JSON.stringify({
+                            user_agent: c.req.header('user-agent'),
+                        }),
+                        now
+                    )
+                    .run();
+            }
+
+            return c.json({ success: true, alreadyUnsubscribed });
+        } catch (error) {
+            console.error('[EmailTracking] Error processing unsubscribe:', error);
+            return c.json({ success: false, error: 'An error occurred' }, 500);
+        }
+    });
+
+    return app;
+}