@contentgrowth/content-emailing 0.1.0

package/README.md

@@ -0,0 +1,96 @@
+# @emails/backend
+
+A comprehensive email management and delivery package designed for **Cloudflare Workers**.
+
+This package provides a complete solution for handling transactional emails, managing templates (with Markdown and variable substitution), and tracking email events (opens, clicks). It relies on **Cloudflare D1** for storage and supports optional **Durable Objects** for high-performance caching.
+
+## Features
+
+- **Multi-Provider Support**: Switch between MailChannels, SendGrid, Resend, SendPulse, or Mock (for testing) via configuration.
+- **Template Management**: Create and edit email templates using Markdown.
+- **Dynamic Variables**: Mustache-style variable substitution (`{{ user_name }}`) in subjects and bodies.
+- **Email Tracking**: Built-in support for tracking email opens (pixel) and link clicks.
+- **Cloudflare D1**: Stores templates, settings, and logs in D1 SQL database.
+- **Durable Objects Cache**: Optional caching layer for high-speed template retrieval.
+- **React Components**: Ready-to-use UI components for managing templates (`TemplateManager`, `TemplateEditor`).
+
+## Requirements
+
+- **Runtime**: Cloudflare Workers (or compatible environment like Hono on Node.js with D1 bindings).
+- **Framework**: built with [Hono](https://hono.dev).
+- **Database**: Cloudflare D1.
+
+## Installation
+
+```bash
+npm install @emails/backend
+```
+
+## Setup & Usage
+
+### 1. Initialize Email Service
+
+In your worker or Hono app:
+
+```javascript
+import { EmailService } from '@emails/backend';
+
+// Initialize with your environment (needs DB binding)
+const emailService = new EmailService(env, {
+  defaults: {
+    fromName: 'My App',
+    fromAddress: 'noreply@myapp.com',
+    provider: 'resend' // or 'mailchannels', 'sendgrid', 'mock'
+  },
+  // API keys from env
+  resend_api_key: env.RESEND_API_KEY
+});
+```
+
+### 2. Database Schema
+
+Ensure your D1 database has the required tables. See `examples/mocks/MockD1.js` for the schema structure, or refer to the provided SQL migration files (if available).
+
+Tables needed:
+- `system_email_templates`
+- `system_settings`
+- `system_email_sends` (for logs)
+
+### 3. Add API Routes
+
+Mount the management routes in your Hono app:
+
+```javascript
+import { createTemplateRoutes, createTrackingRoutes } from '@emails/backend';
+
+// Template management (protected routes recommended)
+app.route('/api/templates', createTemplateRoutes(emailService));
+
+// Public tracking routes (opens/clicks)
+app.route('/email', createTrackingRoutes(emailService));
+```
+
+## Running the Example
+
+A fully functional example server is included in `examples/`. It uses a **Mock D1** implementation so you can run it locally without deploying to Cloudflare.
+
+```bash
+cd examples
+npm install
+npm start
+```
+
+Visit `http://localhost:3456/portal/` to try the Template Manager UI.
+
+## Environment Variables
+
+Configure your provider using standard environment variables or pass them in the config object:
+
+- `EMAIL_PROVIDER`: `resend`, `sendgrid`, `mailchannels`, `sendpulse`, or `mock`
+- `RESEND_API_KEY`
+- `SENDGRID_API_KEY`
+- `SENDPULSE_CLIENT_ID` / `SENDPULSE_CLIENT_SECRET`
+
+## Architecture Note
+
+This package is "Cloudflare-native". It expects `env.DB` to be a D1 binding. If running outside Cloudflare (e.g. Node.js), you must provide a D1-compatible mock or adapter, as demonstrated in the `examples/` folder.

package/examples/.env.example

@@ -0,0 +1,16 @@
+# Server Configuration
+PORT=3456
+
+# Email Configuration
+# Options: mock, mailchannels, sendgrid, resend, sendpulse
+EMAIL_PROVIDER=mock
+
+# Provider Credentials (if using real provider)
+SENDGRID_API_KEY=
+RESEND_API_KEY=
+SENDPULSE_CLIENT_ID=
+SENDPULSE_CLIENT_SECRET=
+
+# Sender Info
+FROM_NAME="Example App"
+FROM_ADDRESS="noreply@example.com"

package/examples/README.md

@@ -0,0 +1,55 @@
+# Email Package Examples
+
+This folder contains a working example server and portal UI for testing the email package.
+
+## Quick Start
+
+```bash
+cd examples
+npm install
+npm start
+```
+
+Then open http://localhost:3456/portal/ in your browser.
+
+## What's Included
+
+### Mocks (`mocks/`)
+
+- **MockD1.js** - In-memory D1 database implementation with sample templates
+- **MockEmailSender.js** - Simulates email sending (logs to console, stores in memory)
+
+### Server (`server.js`)
+
+A Hono server that exposes:
+- `GET /api/templates` - List all templates
+- `GET /api/templates/:id` - Get single template
+- `POST /api/templates` - Create/update template
+- `DELETE /api/templates/:id` - Delete template
+- `POST /api/templates/:id/preview` - Render template with variables
+- `POST /api/templates/:id/test` - Send test email (mocked)
+- `GET /api/sent-emails` - View "sent" emails
+- `GET /email/track/open/:token` - Open tracking pixel
+- `GET /r/:token` - Click tracking redirect
+
+### Portal (`portal/`)
+
+A standalone HTML portal for:
+- Browsing and editing templates
+- Live preview with variable substitution
+- Sending test emails
+- Viewing sent email history
+
+## No Real Dependencies
+
+This example uses **no real external services**:
+- D1 is mocked with in-memory storage
+- Emails are logged to console, not actually sent
+- All data is ephemeral (resets on server restart)
+
+## Sample Templates
+
+The mock D1 comes pre-loaded with sample templates:
+- `welcome` - Onboarding welcome email
+- `password_reset` - Password reset request
+- `weekly_digest` - Weekly activity summary

package/examples/mocks/MockD1.js

@@ -0,0 +1,311 @@
+/**
+ * MockD1 - In-memory D1 database mock for testing
+ * 
+ * This provides a simple in-memory implementation of the D1 interface
+ * for testing the email package without a real database.
+ */
+
+export class MockD1 {
+    constructor(options = {}) {
+        this.seedSettings = options.seedSettings !== false;
+
+        // In-memory storage
+        this.tables = {
+            system_email_templates: [],
+            system_email_preferences: [],
+            system_email_sends: [],
+            system_email_events: [],
+            system_settings: [],
+            tenants: []
+        };
+
+        // Seed with sample data
+        this._seedData();
+    }
+
+    _seedData() {
+        // Add sample templates
+        this.tables.system_email_templates = [
+            {
+                template_id: 'welcome',
+                template_name: 'Welcome Email',
+                template_type: 'onboarding',
+                subject_template: 'Welcome to {{company_name}}, {{user_name}}!',
+                body_markdown: `# Welcome, {{user_name}}!
+
+We're thrilled to have you join **{{company_name}}**!
+
+## Getting Started
+
+Here are a few things you can do:
+
+1. **Complete your profile** - Add your photo and bio
+2. **Explore features** - Check out our [documentation]({{docs_url}})
+3. **Join the community** - Connect with other users
+
+If you have any questions, just reply to this email.
+
+Best regards,
+The {{company_name}} Team`,
+                variables: JSON.stringify(['user_name', 'company_name', 'docs_url']),
+                description: 'Sent to new users after signup',
+                is_active: 1,
+                created_at: Math.floor(Date.now() / 1000),
+                updated_at: Math.floor(Date.now() / 1000),
+                updated_by: 'system'
+            },
+            {
+                template_id: 'password_reset',
+                template_name: 'Password Reset',
+                template_type: 'transactional',
+                subject_template: 'Reset your password for {{company_name}}',
+                body_markdown: `# Password Reset Request
+
+Hi {{user_name}},
+
+We received a request to reset your password. Click the button below to create a new password:
+
+[Reset Password]({{reset_url}})
+
+This link will expire in **1 hour**.
+
+If you didn't request this, you can safely ignore this email.
+
+---
+*This is an automated message from {{company_name}}*`,
+                variables: JSON.stringify(['user_name', 'company_name', 'reset_url']),
+                description: 'Sent when user requests password reset',
+                is_active: 1,
+                created_at: Math.floor(Date.now() / 1000),
+                updated_at: Math.floor(Date.now() / 1000),
+                updated_by: 'system'
+            },
+            {
+                template_id: 'weekly_digest',
+                template_name: 'Weekly Digest',
+                template_type: 'marketing',
+                subject_template: 'Your weekly update from {{company_name}}',
+                body_markdown: `# Weekly Digest
+
+Hi {{user_name}},
+
+Here's what happened this week:
+
+{{#highlights}}
+- {{.}}
+{{/highlights}}
+
+## Stats
+
+| Metric | Value |
+|--------|-------|
+| Views | {{views}} |
+| Clicks | {{clicks}} |
+
+[View Full Report]({{report_url}})
+
+See you next week!`,
+                variables: JSON.stringify(['user_name', 'company_name', 'highlights', 'views', 'clicks', 'report_url']),
+                description: 'Weekly activity summary',
+                is_active: 1,
+                created_at: Math.floor(Date.now() / 1000),
+                updated_at: Math.floor(Date.now() / 1000),
+                updated_by: 'system'
+            }
+        ];
+
+        // Add sample settings only if seedSettings is true
+        if (this.seedSettings) {
+            const env = (typeof process !== 'undefined' && process.env) || {};
+
+            this.tables.system_settings = [
+                { setting_key: 'email_provider', setting_value: env.EMAIL_PROVIDER || 'mock' },
+                { setting_key: 'email_from_address', setting_value: env.FROM_ADDRESS || 'noreply@example.com' },
+                { setting_key: 'email_from_name', setting_value: env.FROM_NAME || 'Example App' }
+            ];
+        }
+    }
+
+    /**
+     * Prepare a SQL statement
+     */
+    prepare(sql) {
+        return new MockStatement(this, sql);
+    }
+
+    /**
+     * Execute a batch of statements
+     */
+    async batch(statements) {
+        const results = [];
+        for (const stmt of statements) {
+            results.push(await stmt.run());
+        }
+        return results;
+    }
+}
+
+class MockStatement {
+    constructor(db, sql) {
+        this.db = db;
+        this.sql = sql;
+        this.bindings = [];
+    }
+
+    bind(...values) {
+        this.bindings = values;
+        return this;
+    }
+
+    async first() {
+        const results = await this.all();
+        return results.results?.[0] || null;
+    }
+
+    async all() {
+        const { operation, table, data } = this._parseSql();
+
+        switch (operation) {
+            case 'SELECT':
+                return { results: this._executeSelect(table) };
+            case 'INSERT':
+                return { results: this._executeInsert(table, data) };
+            case 'UPDATE':
+                return { results: this._executeUpdate(table, data) };
+            case 'DELETE':
+                return { results: this._executeDelete(table) };
+            default:
+                return { results: [] };
+        }
+    }
+
+    async run() {
+        return this.all();
+    }
+
+    _parseSql() {
+        const sql = this.sql.trim().toUpperCase();
+
+        if (sql.startsWith('SELECT')) {
+            const match = this.sql.match(/FROM\s+(\w+)/i);
+            return { operation: 'SELECT', table: match?.[1] };
+        }
+        if (sql.startsWith('INSERT')) {
+            const match = this.sql.match(/INTO\s+(\w+)/i);
+            return { operation: 'INSERT', table: match?.[1] };
+        }
+        if (sql.startsWith('UPDATE')) {
+            const match = this.sql.match(/UPDATE\s+(\w+)/i);
+            return { operation: 'UPDATE', table: match?.[1] };
+        }
+        if (sql.startsWith('DELETE')) {
+            const match = this.sql.match(/FROM\s+(\w+)/i);
+            return { operation: 'DELETE', table: match?.[1] };
+        }
+
+        return { operation: 'UNKNOWN' };
+    }
+
+    _executeSelect(tableName) {
+        const table = this.db.tables[tableName] || [];
+
+        // Handle WHERE clause with bindings
+        if (this.sql.includes('WHERE') && this.bindings.length > 0) {
+            // Simple WHERE clause parsing
+            if (this.sql.includes('template_id = ?')) {
+                return table.filter(row => row.template_id === this.bindings[0]);
+            }
+            if (this.sql.includes('send_id = ?')) {
+                return table.filter(row => row.send_id === this.bindings[0]);
+            }
+            if (this.sql.includes('unsub_token = ?')) {
+                return table.filter(row => row.unsub_token === this.bindings[0]);
+            }
+            if (this.sql.includes('tenant_id = ?')) {
+                return table.filter(row => row.tenant_id === this.bindings[0]);
+            }
+            if (this.sql.includes('setting_key = ?')) {
+                return table.filter(row => row.setting_key === this.bindings[0]);
+            }
+        }
+
+        return table;
+    }
+
+    _executeInsert(tableName) {
+        const table = this.db.tables[tableName];
+        if (!table) return [];
+
+        // Parse column names from SQL
+        const colMatch = this.sql.match(/\(([^)]+)\)\s*VALUES/i);
+        if (!colMatch) return [];
+
+        const columns = colMatch[1].split(',').map(c => c.trim());
+        const newRow = {};
+
+        columns.forEach((col, i) => {
+            newRow[col] = this.bindings[i];
+        });
+
+        // Handle ON CONFLICT for upserts
+        if (this.sql.includes('ON CONFLICT')) {
+            const existingIndex = table.findIndex(row => row.template_id === newRow.template_id);
+            if (existingIndex >= 0) {
+                table[existingIndex] = { ...table[existingIndex], ...newRow };
+                return [table[existingIndex]];
+            }
+        }
+
+        table.push(newRow);
+        return [newRow];
+    }
+
+    _executeUpdate(tableName) {
+        const table = this.db.tables[tableName];
+        if (!table) return [];
+
+        // Find the row to update using the last binding (usually the WHERE value)
+        const whereValue = this.bindings[this.bindings.length - 1];
+
+        const updated = [];
+        for (const row of table) {
+            if (row.template_id === whereValue || row.unsub_token === whereValue || row.setting_key === whereValue) {
+                // Apply updates (simplified - just takes values from bindings assuming simple SET col=?)
+                // NOTE: This Mock is very simple and assumes bindings order matches SET order
+                // For: UPDATE system_settings SET setting_value = ? WHERE setting_key = ?
+                // Binding 0 is value, Binding 1 is key
+                if (tableName === 'system_settings') {
+                    row.setting_value = this.bindings[0];
+                }
+
+                row.updated_at = Math.floor(Date.now() / 1000);
+                updated.push(row);
+            }
+        }
+
+        return updated;
+    }
+
+    _executeDelete(tableName) {
+        const table = this.db.tables[tableName];
+        if (!table) return [];
+
+        const deleteValue = this.bindings[0];
+        const initialLength = table.length;
+
+        this.db.tables[tableName] = table.filter(row => row.template_id !== deleteValue);
+
+        return [{ changes: initialLength - this.db.tables[tableName].length }];
+    }
+}
+
+/**
+ * Create a mock environment object
+ */
+export function createMockEnv(options = {}) {
+    return {
+        DB: new MockD1(options),
+        DOMAIN: 'example.com',
+        ENVIRONMENT: 'development'
+    };
+}

package/examples/mocks/MockEmailSender.js

@@ -0,0 +1,64 @@
+/**
+ * MockEmailSender - Simulates email sending for testing
+ * 
+ * Instead of actually sending emails, this logs them and stores
+ * them in memory so you can view what would have been sent.
+ */
+
+export class MockEmailSender {
+    constructor() {
+        this.sentEmails = [];
+        this.failNextSend = false;
+    }
+
+    /**
+     * Simulate sending an email
+     */
+    async send({ to, subject, html, text, from }) {
+        const email = {
+            id: crypto.randomUUID(),
+            to,
+            from,
+            subject,
+            html,
+            text,
+            sentAt: new Date().toISOString(),
+            status: this.failNextSend ? 'failed' : 'sent'
+        };
+
+        this.sentEmails.push(email);
+
+        console.log(`[MockEmailSender] ${email.status.toUpperCase()}: "${subject}" to ${to}`);
+
+        if (this.failNextSend) {
+            this.failNextSend = false;
+            return { success: false, error: 'Simulated failure' };
+        }
+
+        return { success: true, messageId: email.id };
+    }
+
+    /**
+     * Get all sent emails
+     */
+    getSentEmails() {
+        return this.sentEmails;
+    }
+
+    /**
+     * Clear sent emails history
+     */
+    clear() {
+        this.sentEmails = [];
+    }
+
+    /**
+     * Make the next send fail (for testing error handling)
+     */
+    simulateFailure() {
+        this.failNextSend = true;
+    }
+}
+
+// Global instance for the example server
+export const mockEmailSender = new MockEmailSender();

package/examples/mocks/index.js

@@ -0,0 +1,5 @@
+/**
+ * Mocks index - exports all mock implementations
+ */
+export { MockD1, createMockEnv } from './MockD1.js';
+export { MockEmailSender, mockEmailSender } from './MockEmailSender.js';

package/examples/package-lock.json

@@ -0,0 +1,73 @@
+{
+    "name": "@content-growth/content-emailing-examples",
+    "version": "0.1.0",
+    "lockfileVersion": 3,
+    "requires": true,
+    "packages": {
+        "": {
+            "name": "@content-growth/content-emailing-examples",
+            "version": "0.1.0",
+            "dependencies": {
+                "@hono/node-server": "^1.3.0",
+                "dotenv": "^16.4.5",
+                "hono": "^4.0.0",
+                "marked": "^9.1.2",
+                "mustache": "^4.2.0"
+            }
+        },
+        "node_modules/@hono/node-server": {
+            "version": "1.19.7",
+            "resolved": "https://registry.npmjs.org/@hono/node-server/-/node-server-1.19.7.tgz",
+            "integrity": "sha512-vUcD0uauS7EU2caukW8z5lJKtoGMokxNbJtBiwHgpqxEXokaHCBkQUmCHhjFB1VUTWdqj25QoMkMKzgjq+uhrw==",
+            "license": "MIT",
+            "engines": {
+                "node": ">=18.14.1"
+            },
+            "peerDependencies": {
+                "hono": "^4"
+            }
+        },
+        "node_modules/dotenv": {
+            "version": "16.6.1",
+            "resolved": "https://registry.npmjs.org/dotenv/-/dotenv-16.6.1.tgz",
+            "integrity": "sha512-uBq4egWHTcTt33a72vpSG0z3HnPuIl6NqYcTrKEg2azoEyl2hpW0zqlxysq2pK9HlDIHyHyakeYaYnSAwd8bow==",
+            "license": "BSD-2-Clause",
+            "engines": {
+                "node": ">=12"
+            },
+            "funding": {
+                "url": "https://dotenvx.com"
+            }
+        },
+        "node_modules/hono": {
+            "version": "4.11.1",
+            "resolved": "https://registry.npmjs.org/hono/-/hono-4.11.1.tgz",
+            "integrity": "sha512-KsFcH0xxHes0J4zaQgWbYwmz3UPOOskdqZmItstUG93+Wk1ePBLkLGwbP9zlmh1BFUiL8Qp+Xfu9P7feJWpGNg==",
+            "license": "MIT",
+            "engines": {
+                "node": ">=16.9.0"
+            }
+        },
+        "node_modules/marked": {
+            "version": "9.1.6",
+            "resolved": "https://registry.npmjs.org/marked/-/marked-9.1.6.tgz",
+            "integrity": "sha512-jcByLnIFkd5gSXZmjNvS1TlmRhCXZjIzHYlaGkPlLIekG55JDR2Z4va9tZwCiP+/RDERiNhMOFu01xd6O5ct1Q==",
+            "license": "MIT",
+            "bin": {
+                "marked": "bin/marked.js"
+            },
+            "engines": {
+                "node": ">= 16"
+            }
+        },
+        "node_modules/mustache": {
+            "version": "4.2.0",
+            "resolved": "https://registry.npmjs.org/mustache/-/mustache-4.2.0.tgz",
+            "integrity": "sha512-71ippSywq5Yb7/tVYyGbkBggbU8H3u5Rz56fH60jGFgr8uHwxs+aSKeqmluIVzM0m0kB7xQjKS6qPfd0b2ZoqQ==",
+            "license": "MIT",
+            "bin": {
+                "mustache": "bin/mustache"
+            }
+        }
+    }
+}

package/examples/package.json

@@ -0,0 +1,18 @@
+{
+    "name": "@content-growth/content-emailing-examples",
+    "version": "0.1.0",
+    "private": true,
+    "type": "module",
+    "description": "Example server for testing the email package",
+    "scripts": {
+        "start": "node server.js",
+        "dev": "node --watch server.js"
+    },
+    "dependencies": {
+        "hono": "^4.0.0",
+        "@hono/node-server": "^1.3.0",
+        "marked": "^9.1.2",
+        "mustache": "^4.2.0",
+        "dotenv": "^16.4.5"
+    }
+}