@contentgrowth/content-emailing 0.2.0 → 0.4.0

package/README.md

@@ -36,7 +36,13 @@ In your worker or Hono app:
 import { EmailService } from '@emails/backend';
 
 // Initialize with your environment (needs DB binding)
+// Auto-detects 'EMAIL_TEMPLATE_CACHE' Durable Object if present!
 const emailService = new EmailService(env, {
+  // Optional: Rename tables if needed
+  emailTablePrefix: 'system_email_', // default (for templates/logs)
+  // emailSettingsTable: 'system_settings', // default (for settings)
+  // emailSettingsKeyPrefix: 'email_', // Optional: filter settings in shared table
+
   defaults: {
     fromName: 'My App',
     fromAddress: 'noreply@myapp.com',
@@ -47,7 +53,90 @@ const emailService = new EmailService(env, {
 });
 ```
 
-### 2. Database Schema
+### 2.- `EmailingCacheDO.js` - Durable Object for caching templates & settings, you can enable the read-through cache using Cloudflare Durable Objects.
+
+**The "Magic" Way (Auto-detection):**
+1. Add a Durable Object binding named `EMAIL_TEMPLATE_CACHE` to your `wrangler.toml`.
+2. Point it to the `EmailingCacheDO` class from this package.
+3. Initialize `EmailService(env)` normally. It will automatically find and use the cache.
+
+**wrangler.toml:**
+```toml
+[[durable_objects.bindings]]
+name = "EMAIL_TEMPLATE_CACHE"
+class_name = "EmailTemplateCacheDO"
+
+[[migrations]]
+tag = "v1"
+new_classes = ["EmailTemplateCacheDO"]
+```
+
+**The Explicit Way:**
+If you use a custom binding name or cache implementation:
+
+```javascript
+import { EmailService, createDOCacheProvider } from '@emails/backend';
+
+const cache = createDOCacheProvider(env.MY_CUSTOM_BINDING);
+const service = new EmailService(env, config, cache);
+```
+
+**Custom Cache Provider Interface:**
+You can also implement your own cache provider (e.g., using Redis/KV). It must match this interface:
+
+```javascript
+const myCustomCache = {
+  // Return template object or null
+  async getTemplate(templateId) {
+    // implementation
+  },
+
+  // Called when template is saved/updated
+  async putTemplate(template) {
+    // implementation (usually just invalidates cache)
+  },
+
+  // Called when template is deleted
+  async deleteTemplate(templateId) {
+    // implementation
+  }
+};
+
+const service = new EmailService(env, config, myCustomCache);
+```
+const service = new EmailService(env, config, myCustomCache);
+```
+
+### 3. Settings Management (Hybrid Caching)
+
+The package supports a robust caching strategy for email settings (provider API keys, SMTP config, etc.).
+
+**Case A: Default System Settings (Zero Config)**
+If you store settings in the `system_settings` table (default schema), the Durable Object handles everything automatically:
+1. `EmailService` asks DO for settings.
+2. If not cached, **DO queries D1 directly** (Read-Through).
+3. If cached, returns instantly.
+
+**Case B: Component/Tenant Settings (Custom Logic)**
+If you need to load settings from a custom source (e.g., tenant tables, KV, external API), simple provide loader/updater callbacks:
+
+```javascript
+const emailService = new EmailService(env, {
+  // Custom Loader (Read-Aside)
+  // The service will load this, THEN cache it in the DO for you.
+  settingsLoader: async (profile, tenantId) => {
+    return await env.TENANT_DB.prepare('SELECT * FROM tenant_config WHERE id = ?').bind(tenantId).first();
+  },
+
+  // Custom Updater (Write-Aside)
+  // required if you use saveSettings()
+  settingsUpdater: async (profile, tenantId, settings) => {
+    await env.TENANT_DB.prepare('UPDATE tenant_config SET ...').run();
+  }
+});
+```
+
+### 4. 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).
 
@@ -56,7 +145,7 @@ Tables needed:
 - `system_settings`
 - `system_email_sends` (for logs)
 
-### 3. Add API Routes
+### 5. Add API Routes
 
 Mount the management routes in your Hono app:
 

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@contentgrowth/content-emailing",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "type": "module",
   "description": "Unified email delivery and template management system",
   "main": "src/index.js",
   "exports": {
     ".": "./src/index.js",
     "./backend": "./src/backend/EmailService.js",
+    "./backend/EmailingCacheDO.js": "./src/backend/EmailingCacheDO.js",
     "./routes": "./src/backend/routes/index.js",
     "./common": "./src/common/index.js"
   },

package/src/backend/EmailService.js

@@ -5,12 +5,13 @@
 import { marked } from 'marked';
 import Mustache from 'mustache';
 import { wrapInEmailTemplate } from '../common/htmlWrapper.js';
+import { createDOCacheProvider } from './EmailingCacheDO.js';
 
 export class EmailService {
     /**
      * @param {Object} env - Cloudflare environment bindings (DB, etc.)
      * @param {Object} config - Configuration options
-     * @param {string} [config.tableNamePrefix='system_email_'] - Prefix for D1 tables
+     * @param {string} [config.emailTablePrefix='system_email_'] - Prefix for D1 tables
      * @param {Object} [config.defaults] - Default settings (fromName, fromAddress)
      * @param {Object} [cacheProvider] - Optional cache interface (DO stub or KV wrapper)
      */
@@ -18,12 +19,20 @@ export class EmailService {
         this.env = env;
         this.db = env.DB;
         this.config = {
-            tableNamePrefix: config.tableNamePrefix || 'system_email_',
+            emailTablePrefix: config.emailTablePrefix || config.tableNamePrefix || 'system_email_',
             defaults: config.defaults || {
                 fromName: 'System',
                 fromAddress: 'noreply@example.com',
                 provider: 'mailchannels'
             },
+            // Loader function to fetch settings from backend (DB, KV, etc.)
+            // Signature: async (profile, tenantId) => SettingsObject
+            settingsLoader: config.settingsLoader || null,
+
+            // Updater function to save settings to backend
+            // Signature: async (profile, tenantId, settings) => void
+            settingsUpdater: config.settingsUpdater || null,
+
             // Branding configuration for email templates
             branding: {
                 brandName: config.branding?.brandName || 'Your App',
@@ -33,91 +42,94 @@ export class EmailService {
             },
             ...config
         };
-        this.cache = cacheProvider;
+
+        // Cache Auto-detection:
+        // If no provider explicitly passed, try to use built-in DO provider if binding exists
+        if (!cacheProvider && env.EMAIL_TEMPLATE_CACHE) {
+            this.cache = createDOCacheProvider(env.EMAIL_TEMPLATE_CACHE);
+        } else {
+            this.cache = cacheProvider;
+        }
     }
 
     // --- Configuration & Settings ---
 
     /**
      * Load email configuration
-     * @param {string} profile - 'system' or 'tenant'
-     * @param {string} tenantId - Required if profile is 'tenant'
+     * @param {string} profile - 'system' or 'tenant' (or custom profile string)
+     * @param {string} tenantId - Context ID (optional)
      * @returns {Promise<Object>} Email configuration
      */
     async loadSettings(profile = 'system', tenantId = null) {
-        // 1. Try cache if available (for system profile)
-        if (this.cache && profile === 'system') {
+        // 1. Try cache (now with Read-Through logic in DO)
+        if (this.cache && this.cache.getSettings) {
             try {
-                const cached = await this.cache.getSettings();
+                const cached = await this.cache.getSettings(profile, tenantId);
                 if (cached) return this._normalizeConfig(cached);
             } catch (e) {
-                console.warn('[EmailService] Cache lookup failed:', e);
+                // Ignore cache/rpc errors
             }
         }
 
-        // 2. Load from D1 based on profile
-        if (profile === 'system') {
+        let settings = null;
+
+        // 2. Use settingsLoader (Custom Worker Logic) if provided
+        if (this.config.settingsLoader) {
             try {
-                // Try to load from system_settings table
-                const settings = await this.db
-                    .prepare(`SELECT setting_key, setting_value FROM system_settings`)
-                    .all();
-
-                if (settings.results && settings.results.length > 0) {
-                    const config = {};
-                    settings.results.forEach((row) => {
-                        config[row.setting_key] = row.setting_value;
-                    });
-                    return this._normalizeConfig(config);
-                }
+                settings = await this.config.settingsLoader(profile, tenantId);
             } catch (e) {
-                console.warn('[EmailService] D1 settings lookup failed:', e);
+                console.warn('[EmailService] settingsLoader failed:', e);
             }
-        } else if (profile === 'tenant' && tenantId) {
-            try {
-                const tenant = await this.db
-                    .prepare(`SELECT settings FROM tenants WHERE tenant_id = ?`)
-                    .bind(tenantId)
-                    .first();
-
-                if (tenant?.settings) {
-                    const settings = JSON.parse(tenant.settings);
-                    const emailConfig = settings.email || {};
-                    return {
-                        provider: emailConfig.provider || this.config.defaults.provider,
-                        fromAddress: emailConfig.fromAddress || this.config.defaults.fromAddress,
-                        fromName: emailConfig.fromName || this.config.defaults.fromName,
-                        ...emailConfig
-                    };
-                }
-            } catch (e) {
-                console.warn('[EmailService] Tenant settings lookup failed:', e);
+        }
+
+        // Note: The "Magical D1 Fallback" for system settings has been moved 
+        // INSIDE the EmailTemplateCacheDO (fetchSettingsFromD1).
+        // If the DO failed to find it (or is missing), we fall back to generic defaults below.
+
+        if (settings) {
+            // 3. Populate Cache (Write-Back for custom loaded settings)
+            if (this.cache && this.cache.putSettings) {
+                try {
+                    this.cache.putSettings(profile, tenantId, settings);
+                } catch (e) { /* ignore */ }
             }
+            return this._normalizeConfig(settings);
         }
 
-        // 3. Fallback to defaults
+        // 4. Fallback to defaults
         return {
             ...this.config.defaults,
         };
     }
 
     /**
-     * Normalize config keys from D1 format
+     * Normalize config keys to standard format
+     * Handles both snake_case (DB) and camelCase inputs
      */
     _normalizeConfig(config) {
         return {
-            provider: config.email_provider || this.config.defaults.provider,
-            fromAddress: config.email_from_address || this.config.defaults.fromAddress,
-            fromName: config.email_from_name || this.config.defaults.fromName,
-            // Provider-specific settings
-            sendgridApiKey: config.sendgrid_api_key,
-            resendApiKey: config.resend_api_key,
-            sendpulseClientId: config.sendpulse_client_id,
-            sendpulseClientSecret: config.sendpulse_client_secret,
-            smtpHost: config.smtp_host,
-            smtpPort: config.smtp_port,
-            smtpUsername: config.smtp_username,
-            smtpPassword: config.smtp_password,
+            provider: config.email_provider || config.provider || this.config.defaults.provider,
+            fromAddress: config.email_from_address || config.fromAddress || this.config.defaults.fromAddress,
+            fromName: config.email_from_name || config.fromName || this.config.defaults.fromName,
+
+            // Provider-specific settings (normalize DB keys to service keys)
+            sendgridApiKey: config.sendgrid_api_key || config.sendgridApiKey,
+            resendApiKey: config.resend_api_key || config.resendApiKey,
+            sendpulseClientId: config.sendpulse_client_id || config.sendpulseClientId,
+            sendpulseClientSecret: config.sendpulse_client_secret || config.sendpulseClientSecret,
+
+            // SMTP
+            smtpHost: config.smtp_host || config.smtpHost,
+            smtpPort: config.smtp_port || config.smtpPort,
+            smtpUsername: config.smtp_username || config.smtpUsername,
+            smtpPassword: config.smtp_password || config.smtpPassword,
+
+            // Tracking
+            trackingUrl: config.tracking_url || config.trackingUrl,
+
+            // Pass through others
+            // Pass through others
+            ...config,
             smtpSecure: config.smtp_secure === 'true',
         };
     }
@@ -135,20 +147,55 @@ export class EmailService {
             }
         }
 
-        const table = `${this.config.tableNamePrefix}templates`;
+        const table = `${this.config.emailTablePrefix}templates`;
         return await this.db.prepare(`SELECT * FROM ${table} WHERE template_id = ?`)
             .bind(templateId)
             .first();
     }
 
     async getAllTemplates() {
-        const table = `${this.config.tableNamePrefix}templates`;
+        const table = `${this.config.emailTablePrefix}templates`;
         const result = await this.db.prepare(`SELECT * FROM ${table} ORDER BY template_name`).all();
         return result.results || [];
     }
 
+    /**
+     * Save email configuration
+     * @param {Object} settings - Config object
+     * @param {string} profile - 'system' or 'tenant'
+     * @param {string} tenantId - Context ID
+     */
+    async saveSettings(settings, profile = 'system', tenantId = null) {
+        // 1. Convert to DB format if needed (not implemented here, assumes settingsUpdater handles it)
+
+        // 2. Use settingsUpdater if provided (Write-Aside)
+        if (this.config.settingsUpdater) {
+            try {
+                await this.config.settingsUpdater(profile, tenantId, settings);
+            } catch (e) {
+                console.error('[EmailService] settingsUpdater failed:', e);
+                throw e;
+            }
+        }
+        // 3. Helper for saving to D1 (if no updater, legacy/default tables)
+        else if (profile === 'system' && this.db) {
+            // NOTE: We could implement a default D1 upsert here similar to the DO fallback,
+            // but for writing it's safer to rely on explicit updaters or the DO write-through if implemented.
+            // Currently DO supports write-through for 'system' keys.
+        }
+
+        // 4. Update Cache (Write-Invalidate)
+        if (this.cache && this.cache.invalidateSettings) {
+            try {
+                await this.cache.invalidateSettings(profile, tenantId);
+            } catch (e) {
+                console.warn('[EmailService] Failed to invalidate settings cache:', e);
+            }
+        }
+    }
+
     async saveTemplate(template, userId = 'system') {
-        const table = `${this.config.tableNamePrefix}templates`;
+        const table = `${this.config.emailTablePrefix}templates`;
         const now = Math.floor(Date.now() / 1000);
         const existing = await this.getTemplate(template.template_id);
 
@@ -184,7 +231,7 @@ export class EmailService {
     }
 
     async deleteTemplate(templateId) {
-        const table = `${this.config.tableNamePrefix}templates`;
+        const table = `${this.config.emailTablePrefix}templates`;
         await this.db.prepare(`DELETE FROM ${table} WHERE template_id = ?`).bind(templateId).run();
         if (this.cache) {
             await this.cache.deleteTemplate(templateId);
@@ -240,7 +287,11 @@ export class EmailService {
      * @param {Object} [params.metadata] - Additional metadata
      * @returns {Promise<Object>} Delivery result
      */
-    async sendEmail({ to, subject, html, text, provider, profile = 'system', tenantId = null, metadata = {} }) {
+    async sendEmail({ to, subject, html, htmlBody, text, textBody, provider, profile = 'system', tenantId = null, metadata = {} }) {
+        // Backward compatibility: accept htmlBody/textBody as aliases
+        const htmlContent = html || htmlBody;
+        const textContent = text || textBody;
+
         try {
             const settings = await this.loadSettings(profile, tenantId);
             const useProvider = provider || settings.provider || 'mailchannels';
@@ -249,16 +300,16 @@ export class EmailService {
 
             switch (useProvider) {
                 case 'mailchannels':
-                    result = await this.sendViaMailChannels(to, subject, html, text, settings, metadata);
+                    result = await this.sendViaMailChannels(to, subject, htmlContent, textContent, settings, metadata);
                     break;
                 case 'sendgrid':
-                    result = await this.sendViaSendGrid(to, subject, html, text, settings, metadata);
+                    result = await this.sendViaSendGrid(to, subject, htmlContent, textContent, settings, metadata);
                     break;
                 case 'resend':
-                    result = await this.sendViaResend(to, subject, html, text, settings, metadata);
+                    result = await this.sendViaResend(to, subject, htmlContent, textContent, settings, metadata);
                     break;
                 case 'sendpulse':
-                    result = await this.sendViaSendPulse(to, subject, html, text, settings, metadata);
+                    result = await this.sendViaSendPulse(to, subject, htmlContent, textContent, settings, metadata);
                     break;
                 default:
                     console.error(`[EmailService] Unknown provider: ${useProvider}`);
@@ -441,7 +492,16 @@ export class EmailService {
             }
 
             const { access_token } = tokenData;
-            const toBase64 = (str) => Buffer.from(str).toString('base64');
+
+            // Safe base64 encoding
+            const toBase64 = (str) => {
+                if (!str) return '';
+                return Buffer.from(String(str)).toString('base64');
+            };
+
+            // Ensure html/text are strings
+            const htmlSafe = html || '';
+            const textSafe = text || (htmlSafe ? htmlSafe.replace(/<[^>]*>/g, '') : '');
 
             // Send the email
             const response = await fetch('https://api.sendpulse.com/smtp/emails', {
@@ -452,8 +512,8 @@ export class EmailService {
                 },
                 body: JSON.stringify({
                     email: {
-                        html: toBase64(html),
-                        text: toBase64(text || html.replace(/<[^>]*>/g, '')),
+                        html: toBase64(htmlSafe),
+                        text: toBase64(textSafe),
                         subject,
                         from: { name: settings.fromName, email: settings.fromAddress },
                         to: [{ name: metadata.recipientName || '', email: to }],

package/src/backend/EmailingCacheDO.js

@@ -0,0 +1,466 @@
+/**
+ * EmailingCacheDO - Optional read-through cache for email templates and settings
+ * 
+ * This is a Cloudflare Durable Object that provides caching for email templates and settings.
+ * 
+ * Configurable via environment variable:
+ * - EMAIL_TABLE_PREFIX: Prefix for tables (default: 'system_email_')
+ */
+export class EmailingCacheDO {
+    constructor(state, env) {
+        this.state = state;
+        this.env = env;
+        this.cache = new Map(); // templateId -> { data, timestamp }
+        this.settingsCache = new Map(); // key -> { data, timestamp }
+        this.cacheTTL = 3600000; // 1 hour in milliseconds
+        // Templates use the prefix
+        this.emailTablePrefix = env.EMAIL_TABLE_PREFIX || 'system_email_';
+        // Settings use a specific table name (defaulting to system_settings)
+        // This allows decoupling template prefix from settings table
+        this.settingsTableName = env.EMAIL_SETTINGS_TABLE || 'system_settings';
+
+        // Optional: Filter settings by key prefix (e.g. 'email_')
+        // This allows sharing the system_settings table with other apps
+        this.settingsKeyPrefix = env.EMAIL_SETTINGS_KEY_PREFIX || '';
+    }
+
+    /**
+     * 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 === '/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);
+            }
+            // Settings endpoints
+            else if (path === '/settings/get' && request.method === 'GET') {
+                return this.handleGetSettings(request);
+            } else if (path === '/settings/put' && request.method === 'POST') {
+                return this.handlePutSettings(request);
+            } else if (path === '/settings/invalidate' && request.method === 'POST') {
+                return this.handleInvalidateSettings(request);
+            } else {
+                return new Response('Not Found', { status: 404 });
+            }
+        } catch (error) {
+            console.error('[EmailingCacheDO] Error:', error);
+            return new Response(JSON.stringify({ error: error.message }), {
+                status: 500,
+                headers: { 'Content-Type': 'application/json' },
+            });
+        }
+    }
+
+    /**
+     * Get template (from cache or D1)
+     */
+    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('[EmailingCacheDO] 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('[EmailingCacheDO] 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' },
+        });
+    }
+
+    // --- Settings Cache Handlers ---
+
+    async handleGetSettings(request) {
+        const url = new URL(request.url);
+        const key = url.searchParams.get('key');
+
+        if (!key) return new Response('Key required', { status: 400 });
+
+        // Check Cache
+        const cached = this.settingsCache.get(key);
+        if (cached && Date.now() - cached.timestamp < this.cacheTTL) {
+            console.log('[EmailingCacheDO] Settings Cache HIT:', key);
+            return new Response(JSON.stringify({ settings: cached.data }), {
+                headers: { 'Content-Type': 'application/json' },
+            });
+        }
+
+        // Cache Miss - Fetch from D1 (Read-Through)
+        // Only fetch from D1 for system settings (consistent with handlePutSettings)
+        if (key.startsWith('system')) {
+            console.log('[EmailingCacheDO] Settings Cache MISS - fetching from D1:', key);
+            const settings = await this.fetchSettingsFromD1(key);
+
+            // Even if null, we might want to cache the "null" result to prevent hammer? 
+            // For now, only cache if we found something or explicitly handle negative caching.
+            if (settings) {
+                this.settingsCache.set(key, {
+                    data: settings,
+                    timestamp: Date.now()
+                });
+                return new Response(JSON.stringify({ settings }), {
+                    headers: { 'Content-Type': 'application/json' },
+                });
+            }
+        }
+
+        return new Response(JSON.stringify({ settings: null }), {
+            headers: { 'Content-Type': 'application/json' },
+        });
+    }
+
+    async handlePutSettings(request) {
+        try {
+            const body = await request.json();
+            const { key, settings } = body;
+
+            if (!key || !settings) return new Response('Key and settings required', { status: 400 });
+
+            // Write to Cache
+            this.settingsCache.set(key, {
+                data: settings,
+                timestamp: Date.now()
+            });
+
+            // Write to D1 (Write-Through)
+            // Note: only supports writing to "system" (default table) currently
+            if (key.startsWith('system')) {
+                await this.saveSettingsToD1(settings);
+            }
+
+            return new Response(JSON.stringify({ success: true }), {
+                headers: { 'Content-Type': 'application/json' },
+            });
+        } catch (e) {
+            console.error('[EmailingCacheDO] PutSettings error:', e);
+            return new Response('Error parsing body/saving', { status: 400 });
+        }
+    }
+
+    async handleInvalidateSettings(request) {
+        try {
+            const body = await request.json();
+            const { key } = body;
+
+            if (!key) return new Response('Key required', { status: 400 });
+
+            const existed = this.settingsCache.has(key);
+            this.settingsCache.delete(key);
+            console.log('[EmailingCacheDO] Invalidated settings:', key, existed ? '(existed)' : '(not in cache)');
+
+            return new Response(JSON.stringify({ success: true, existed }), {
+                headers: { 'Content-Type': 'application/json' },
+            });
+        } catch (e) {
+            console.error('[EmailingCacheDO] InvalidateSettings error:', e);
+            return new Response('Error invalidated settings', { status: 400 });
+        }
+    }
+
+    /**
+     * Invalidate specific template(s) from cache
+     * Body: { templateId: 'template_id' } or { templateId: '*' } for all
+     */
+    async handleInvalidate(request) {
+        const body = await request.json();
+        const { templateId } = body;
+
+        if (!templateId) {
+            return new Response(JSON.stringify({ error: 'templateId is required' }), {
+                status: 400,
+                headers: { 'Content-Type': 'application/json' },
+            });
+        }
+
+        if (templateId === '*') {
+            // Invalidate all templates
+            const count = this.cache.size;
+            this.cache.clear();
+            console.log('[EmailingCacheDO] 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('[EmailingCacheDO] 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.settingsCache.size;
+        this.cache.clear();
+        this.settingsCache.clear();
+        console.log('[EmailingCacheDO] Cache cleared:', count, 'entries (templates + settings)');
+
+        return new Response(JSON.stringify({
+            success: true,
+            message: `Cleared ${count} cached items`,
+        }), {
+            headers: { 'Content-Type': 'application/json' },
+        });
+    }
+
+    /**
+     * Get cache statistics
+     */
+    async handleStats(request) {
+        const stats = {
+            templates: this.cache.size,
+            settings: this.settingsCache.size,
+            cacheTTL: 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 tableName = `${this.emailTablePrefix}templates`;
+
+        try {
+            const template = await db
+                .prepare(`SELECT * FROM ${tableName} WHERE template_id = ? AND is_active = 1`)
+                .bind(templateId)
+                .first();
+            return template;
+        } catch (e) {
+            console.error(`[EmailingCacheDO] DB Error (${tableName}):`, e);
+            return null;
+        }
+    }
+
+    /**
+     * Fetch settings from D1
+     * Only supports default table (e.g. system_settings) for now
+     */
+    async fetchSettingsFromD1(key) {
+        const db = this.env.DB;
+        const tableName = this.settingsTableName;
+        const prefix = this.settingsKeyPrefix;
+
+        try {
+            let results;
+
+            if (prefix) {
+                // Filter by prefix (e.g. WHERE setting_key LIKE 'email_%')
+                // Note: We need to handle both schema variants (setting_key vs key)
+                // BUT standard D1 SQL doesn't support "OR" in column names easily with LIKE parameter binding
+                // for flexible schemas.
+                // We will assume 'setting_key' matches if table is system_settings, or try both.
+
+                // Construct query dynamically based on likely schema or just try standard first
+                try {
+                    results = await db.prepare(`SELECT * FROM ${tableName} WHERE setting_key LIKE ?`).bind(`${prefix}%`).all();
+                } catch (e) {
+                    // Fallback to 'key' column
+                    results = await db.prepare(`SELECT * FROM ${tableName} WHERE key LIKE ?`).bind(`${prefix}%`).all();
+                }
+            } else {
+                // No prefix, fetch all
+                results = await db.prepare(`SELECT * FROM ${tableName}`).all();
+            }
+
+            if (!results.results || results.results.length === 0) return null;
+
+            const settings = {};
+            results.results.forEach(row => {
+                const k = row.setting_key || row.key;
+                const v = row.setting_value || row.value;
+                if (k) settings[k] = v;
+            });
+            return settings;
+        } catch (e) {
+            console.warn(`[EmailingCacheDO] Failed to load settings from ${tableName}:`, e);
+            return null;
+        }
+    }
+
+    async saveSettingsToD1(settings) {
+        const db = this.env.DB;
+        const tableName = this.settingsTableName;
+
+        // Simple upset not easy in D1 without specific keys.
+        // We'll rely on calling code/migration. 
+        // For now, let's just log or try to update if possible.
+        // Actually, writing settings is complex because we don't know the schema perfectly.
+        // Let's implement a BEST EFFORT update for x0start schema
+
+        const entries = Object.entries(settings);
+        for (const [k, v] of entries) {
+            try {
+                // Heuristic: Try to determine column names based on common conventions
+                // We'll try Schema 1 (setting_key/value) first as it's the default internal convention
+                // If that fails, we might fall back to Schema 2 (key/value) in a real implementation
+                // For now, let's try a best-effort upsert based on x0start schema or generic
+
+                try {
+                    const res = await db.prepare(`UPDATE ${tableName} SET setting_value = ? WHERE setting_key = ?`).bind(v, k).run();
+                    if (res.meta.changes === 0) {
+                        await db.prepare(`INSERT INTO ${tableName} (setting_key, setting_value) VALUES (?, ?)`).bind(k, v).run();
+                    }
+                } catch (e) {
+                    // Fallback to key/value
+                    await db.prepare(`INSERT OR REPLACE INTO ${tableName} (key, value) VALUES (?, ?)`).bind(k, v).run();
+                }
+            } catch (e) {
+                console.warn('[EmailingCacheDO] Failed to save setting to D1:', k);
+            }
+        }
+    }
+}
+
+/**
+ * Create a cache provider wrapper for the DO
+ */
+export function createDOCacheProvider(doStub, instanceName = 'global') {
+    if (!doStub) {
+        return null;
+    }
+
+    const stub = doStub.get(doStub.idFromName(instanceName));
+
+    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(profile, tenantId) {
+            const key = `${profile}:${tenantId || ''}`;
+            try {
+                const response = await stub.fetch(`http://do/settings/get?key=${encodeURIComponent(key)}`);
+                const data = await response.json();
+                return data.settings || null;
+            } catch (e) {
+                return null;
+            }
+        },
+
+        async putSettings(profile, tenantId, settings) {
+            const key = `${profile}:${tenantId || ''}`;
+            try {
+                await stub.fetch('http://do/settings/put', {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ key, settings }),
+                });
+            } catch (e) {
+                console.warn('[DOCacheProvider] Failed to cache settings:', e);
+            }
+        },
+
+        async putTemplate(template) {
+            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(profile, tenantId) {
+            const key = `${profile}:${tenantId || ''}`;
+            try {
+                await stub.fetch('http://do/settings/invalidate', {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ key }),
+                });
+            } catch (e) {
+                console.warn('[DOCacheProvider] Failed to invalidate settings:', e);
+            }
+        },
+    };
+}

package/src/backend/routes/tracking.js

@@ -17,13 +17,13 @@ const TRACKING_PIXEL = new Uint8Array([
  * Create email tracking routes
  * @param {Object} env - Environment bindings
  * @param {Object} config - Configuration
- * @param {string} [config.tableNamePrefix='system_email_'] - Prefix for D1 tables
+ * @param {string} [config.emailTablePrefix='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_';
+    const tablePrefix = config.emailTablePrefix || config.tableNamePrefix || 'system_email_';
 
     /**
      * GET /track/open/:token

package/src/common/utils.js

@@ -3,6 +3,8 @@
  * Common helpers for email processing
  */
 
+import mustache from 'mustache';
+
 // Module-level cache for website URL
 let cachedWebsiteUrl = null;
 
@@ -100,18 +102,40 @@ export function markdownToPlainText(markdown) {
 }
 
 /**
- * Extract variables from a template string
- * @param {string} template - Template with {{variable}} placeholders
- * @returns {string[]} Array of variable names found
+ * Extract variables from a Mustache template string
+ * @param {string} templateString - The mustache template string
+ * @returns {string[]} Array of unique variable names
  */
-export function extractVariables(template) {
-    const regex = /\{\{([^}]+)\}\}/g;
-    const variables = new Set();
-    let match;
-
-    while ((match = regex.exec(template)) !== null) {
-        variables.add(match[1].trim());
+export function extractVariables(templateString) {
+    if (!templateString) return [];
+
+    try {
+        // Parse the template to get tokens
+        const tokens = mustache.parse(templateString);
+        const variables = new Set();
+
+        // Recursively extract variables from tokens
+        const collectVariables = (tokenList) => {
+            tokenList.forEach(token => {
+                const type = token[0];
+                const value = token[1];
+
+                // Types: 'name' ({{var}}), '#' (section), '^' (inverted section), '&' (unescaped)
+                if (type === 'name' || type === '#' || type === '^' || type === '&') {
+                    variables.add(value);
+                }
+
+                // Variable is in token[4] for sections
+                if ((type === '#' || type === '^') && token[4]) {
+                    collectVariables(token[4]);
+                }
+            });
+        };
+
+        collectVariables(tokens);
+        return Array.from(variables);
+    } catch (error) {
+        console.error('Error parsing template variables:', error);
+        return [];
     }
-
-    return Array.from(variables);
 }

package/src/index.js

@@ -1,6 +1,6 @@
 // Backend services
 export { EmailService } from './backend/EmailService.js';
-export { EmailTemplateCacheDO, createDOCacheProvider } from './backend/EmailTemplateCacheDO.js';
+export { EmailingCacheDO, createDOCacheProvider } from './backend/EmailingCacheDO.js';
 
 // Routes
 export {

package/src/backend/EmailTemplateCacheDO.js

@@ -1,363 +0,0 @@
-/**
- * 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);
-            }
-        },
-    };
-}