@fufulog/brevomorphic-cms-sdk 1.0.0

package/src/controller.ts

@@ -0,0 +1,186 @@
+import { Request, Response, Router } from 'express';
+import { EmailTemplateService } from './service.js';
+
+export class EmailTemplateController {
+  private service: EmailTemplateService;
+
+  constructor(service: EmailTemplateService) {
+    this.service = service;
+  }
+
+  /**
+   * Generates a fully configured Express Router.
+   * Can be directly mounted into any Express app: `app.use('/api/cms', controller.getRouter())`
+   */
+  getRouter(): Router {
+    const router = Router();
+
+    // Standard express mapping
+    router.get('/templates', this.listTemplates.bind(this));
+    router.get('/templates/:id', this.getTemplate.bind(this));
+    router.post('/templates', this.createTemplate.bind(this));
+    router.put('/templates/:id', this.updateTemplate.bind(this));
+    router.post('/templates/:id/toggle', this.toggleTemplate.bind(this));
+    router.get('/senders', this.listSenders.bind(this));
+    router.post('/send', this.sendEventEmail.bind(this));
+
+    return router;
+  }
+
+  /**
+   * GET /templates
+   * Lists all templates synchronized from Brevo and mapped locally.
+   */
+  async listTemplates(req: Request, res: Response): Promise<void> {
+    try {
+      const templates = await this.service.listTemplates();
+      res.status(200).json({ success: true, data: templates });
+    } catch (error: any) {
+      res.status(500).json({ success: false, error: error.message });
+    }
+  }
+
+  /**
+   * GET /templates/:id
+   * Fetches a detailed template (including HTML body content) by Brevo ID.
+   */
+  async getTemplate(req: Request, res: Response): Promise<void> {
+    try {
+      const id = parseInt(req.params.id, 10);
+      if (isNaN(id)) {
+        res.status(400).json({ success: false, error: 'Invalid template ID parameter' });
+        return;
+      }
+      const template = await this.service.getTemplate(id);
+      res.status(200).json({ success: true, data: template });
+    } catch (error: any) {
+      if (error.message.includes('not found') || error.message.includes('404')) {
+        res.status(404).json({ success: false, error: error.message });
+      } else {
+        res.status(500).json({ success: false, error: error.message });
+      }
+    }
+  }
+
+  /**
+   * POST /templates
+   * Instantiates a new draft template on Brevo and registers local mapping.
+   */
+  async createTemplate(req: Request, res: Response): Promise<void> {
+    try {
+      const { name, subject, senderEmail, senderName } = req.body;
+      const newTemplate = await this.service.createTemplate({
+        name,
+        subject,
+        senderEmail,
+        senderName,
+      });
+      res.status(201).json({ success: true, data: newTemplate });
+    } catch (error: any) {
+      res.status(500).json({ success: false, error: error.message });
+    }
+  }
+
+  /**
+   * PUT /templates/:id
+   * Validates and updates a template configuration both on Brevo and the local DB.
+   */
+  async updateTemplate(req: Request, res: Response): Promise<void> {
+    try {
+      const id = parseInt(req.params.id, 10);
+      if (isNaN(id)) {
+        res.status(400).json({ success: false, error: 'Invalid template ID parameter' });
+        return;
+      }
+
+      const { templateName, subject, sender, htmlContent, eventName, isActive } = req.body;
+      
+      const updated = await this.service.updateTemplate(id, {
+        templateName,
+        subject,
+        sender,
+        htmlContent,
+        eventName,
+        isActive: !!isActive,
+      });
+
+      res.status(200).json({ success: true, data: updated });
+    } catch (error: any) {
+      if (
+        error.message.includes('cannot be blank') ||
+        error.message.includes('must exceed') ||
+        error.message.includes('greater than 10')
+      ) {
+        res.status(400).json({ success: false, error: error.message });
+      } else {
+        res.status(500).json({ success: false, error: error.message });
+      }
+    }
+  }
+
+  /**
+   * POST /templates/:id/toggle
+   * Flips active/inactive status across Brevo and DB.
+   */
+  async toggleTemplate(req: Request, res: Response): Promise<void> {
+    try {
+      const id = parseInt(req.params.id, 10);
+      if (isNaN(id)) {
+        res.status(400).json({ success: false, error: 'Invalid template ID parameter' });
+        return;
+      }
+
+      const { isActive } = req.body;
+      if (isActive === undefined) {
+        res.status(400).json({ success: false, error: "Field 'isActive' boolean is required in request body" });
+        return;
+      }
+
+      await this.service.toggleTemplateActive(id, !!isActive);
+      res.status(200).json({ success: true, message: `Template status flipped to ${!!isActive}` });
+    } catch (error: any) {
+      res.status(500).json({ success: false, error: error.message });
+    }
+  }
+
+  /**
+   * GET /senders
+   * Lists verified sender profiles from Brevo.
+   */
+  async listSenders(req: Request, res: Response): Promise<void> {
+    try {
+      const senders = await this.service.getSenders();
+      res.status(200).json({ success: true, data: senders });
+    } catch (error: any) {
+      res.status(500).json({ success: false, error: error.message });
+    }
+  }
+
+  /**
+   * POST /send
+   * Triggers an email send for a given backend event.
+   */
+  async sendEventEmail(req: Request, res: Response): Promise<void> {
+    try {
+      const { eventName, recipientEmail, variables } = req.body;
+
+      if (!eventName || !recipientEmail) {
+        res.status(400).json({
+          success: false,
+          error: "Fields 'eventName' and 'recipientEmail' are required in request body",
+        });
+        return;
+      }
+
+      const outcome = await this.service.sendEventEmail(eventName, recipientEmail, variables);
+      
+      if (!outcome.sent) {
+        res.status(200).json({ success: true, sent: false, message: outcome.message });
+      } else {
+        res.status(200).json({ success: true, sent: true, message: outcome.message });
+      }
+    } catch (error: any) {
+      res.status(500).json({ success: false, error: error.message });
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export { BrevoClient } from './brevoClient.js';
+export { EmailTemplateRepository } from './repository.js';
+export { EmailTemplateService } from './service.js';
+export { EmailTemplateController } from './controller.js';
+export * from './types.js';

package/src/repository.ts

@@ -0,0 +1,229 @@
+import { SDKConfig, LocalMapping } from './types.js';
+
+export class EmailTemplateRepository {
+  private dbType: 'postgres' | 'mysql' | 'firestore';
+  private dbClient: any;
+  private tableName: string;
+
+  constructor(config: SDKConfig) {
+    this.dbType = config.dbType;
+    this.dbClient = config.dbClient;
+    this.tableName = config.tableNameOrCollection || 'email_event_templates';
+
+    if (!this.dbClient) {
+      throw new Error(`Database client is required for database type: ${this.dbType}`);
+    }
+  }
+
+  /**
+   * Helper to parse SQL queries results.
+   * Handles PostgreSQL result format (res.rows) and MySQL format ([rows, fields]).
+   */
+  private parseSQLResult(res: any): any[] {
+    if (!res) return [];
+    if (res.rows && Array.isArray(res.rows)) {
+      return res.rows;
+    }
+    if (Array.isArray(res)) {
+      if (res.length > 0 && Array.isArray(res[0])) {
+        // MySQL connection.query returns [rows, fields]
+        return res[0];
+      }
+      return res; // Flat rows array
+    }
+    return [];
+  }
+
+  /**
+   * Fetch all event-to-template mappings from the local database
+   */
+  async getAllMappings(): Promise<LocalMapping[]> {
+    if (this.dbType === 'firestore') {
+      const snapshot = await this.dbClient.collection(this.tableName).get();
+      const mappings: LocalMapping[] = [];
+      snapshot.forEach((doc: any) => {
+        const data = doc.data();
+        mappings.push({
+          template_id: Number(data.template_id),
+          event_name: data.event_name || '',
+          is_active: !!data.is_active,
+          updated_at: data.updated_at?.toDate ? data.updated_at.toDate() : data.updated_at,
+        });
+      });
+      return mappings;
+    } else {
+      const sql = `SELECT id, template_id, event_name, is_active, updated_at FROM ${this.tableName}`;
+      const res = await this.dbClient.query(sql, []);
+      const rows = this.parseSQLResult(res);
+      return rows.map((r: any) => ({
+        id: r.id,
+        template_id: Number(r.template_id),
+        event_name: r.event_name || '',
+        is_active: Boolean(r.is_active),
+        updated_at: r.updated_at,
+      }));
+    }
+  }
+
+  /**
+   * Fetch mapping for a specific template ID
+   */
+  async getMappingByTemplateId(templateId: number): Promise<LocalMapping | null> {
+    if (this.dbType === 'firestore') {
+      const doc = await this.dbClient.collection(this.tableName).doc(templateId.toString()).get();
+      if (!doc.exists) return null;
+      const data = doc.data();
+      return {
+        template_id: Number(data.template_id),
+        event_name: data.event_name || '',
+        is_active: !!data.is_active,
+        updated_at: data.updated_at?.toDate ? data.updated_at.toDate() : data.updated_at,
+      };
+    } else {
+      const paramChar = this.dbType === 'postgres' ? '$1' : '?';
+      const sql = `SELECT id, template_id, event_name, is_active, updated_at FROM ${this.tableName} WHERE template_id = ${paramChar}`;
+      const res = await this.dbClient.query(sql, [templateId]);
+      const rows = this.parseSQLResult(res);
+      if (rows.length === 0) return null;
+      
+      const r = rows[0];
+      return {
+        id: r.id,
+        template_id: Number(r.template_id),
+        event_name: r.event_name || '',
+        is_active: Boolean(r.is_active),
+        updated_at: r.updated_at,
+      };
+    }
+  }
+
+  /**
+   * Fetch mapping for a specific event name.
+   * Assumes we want the active template linked to this event.
+   */
+  async getActiveMappingByEvent(eventName: string): Promise<LocalMapping | null> {
+    if (this.dbType === 'firestore') {
+      const snapshot = await this.dbClient
+        .collection(this.tableName)
+        .where('event_name', '==', eventName)
+        .where('is_active', '==', true)
+        .limit(1)
+        .get();
+      
+      if (snapshot.empty) return null;
+      const doc = snapshot.docs[0];
+      const data = doc.data();
+      return {
+        template_id: Number(data.template_id),
+        event_name: data.event_name || '',
+        is_active: !!data.is_active,
+        updated_at: data.updated_at?.toDate ? data.updated_at.toDate() : data.updated_at,
+      };
+    } else {
+      const param1 = this.dbType === 'postgres' ? '$1' : '?';
+      const param2 = this.dbType === 'postgres' ? '$2' : '?';
+      // Wait, is_active could be 1/0 or true/false, standard database handles boolean conversion, but is_active = true or is_active = 1
+      const sql = `SELECT id, template_id, event_name, is_active, updated_at FROM ${this.tableName} WHERE event_name = ${param1} AND is_active = ${param2} LIMIT 1`;
+      
+      // Pass both parameters for portability
+      const res = await this.dbClient.query(sql, [eventName, true]);
+      const rows = this.parseSQLResult(res);
+      if (rows.length === 0) return null;
+
+      const r = rows[0];
+      return {
+        id: r.id,
+        template_id: Number(r.template_id),
+        event_name: r.event_name || '',
+        is_active: Boolean(r.is_active),
+        updated_at: r.updated_at,
+      };
+    }
+  }
+
+  /**
+   * Upsert a mapping (insert or update template config)
+   */
+  async upsertMapping(templateId: number, eventName: string, isActive: boolean): Promise<void> {
+    if (this.dbType === 'firestore') {
+      await this.dbClient
+        .collection(this.tableName)
+        .doc(templateId.toString())
+        .set(
+          {
+            template_id: templateId,
+            event_name: eventName,
+            is_active: isActive,
+            updated_at: new Date(),
+          },
+          { merge: true }
+        );
+    } else {
+      let sql = '';
+      let params: any[] = [];
+      if (this.dbType === 'postgres') {
+        sql = `
+          INSERT INTO ${this.tableName} (template_id, event_name, is_active, updated_at)
+          VALUES ($1, $2, $3, CURRENT_TIMESTAMP)
+          ON CONFLICT (template_id)
+          DO UPDATE SET 
+            event_name = EXCLUDED.event_name,
+            is_active = EXCLUDED.is_active,
+            updated_at = CURRENT_TIMESTAMP
+        `;
+        params = [templateId, eventName, isActive];
+      } else {
+        // MySQL ON DUPLICATE KEY UPDATE
+        sql = `
+          INSERT INTO ${this.tableName} (template_id, event_name, is_active, updated_at)
+          VALUES (?, ?, ?, CURRENT_TIMESTAMP)
+          ON DUPLICATE KEY UPDATE 
+            event_name = VALUES(event_name),
+            is_active = VALUES(is_active),
+            updated_at = CURRENT_TIMESTAMP
+        `;
+        params = [templateId, eventName, isActive];
+      }
+      await this.dbClient.query(sql, params);
+    }
+  }
+
+  /**
+   * Just-In-Time (JIT) Local Mapping Generation.
+   * If mapping does not exist, insert blank inactive mapping.
+   */
+  async insertJITMapping(templateId: number): Promise<void> {
+    if (this.dbType === 'firestore') {
+      const docRef = this.dbClient.collection(this.tableName).doc(templateId.toString());
+      const doc = await docRef.get();
+      if (!doc.exists) {
+        await docRef.set({
+          template_id: templateId,
+          event_name: '',
+          is_active: false,
+          updated_at: new Date(),
+        });
+      }
+    } else {
+      let sql = '';
+      let params: any[] = [];
+      if (this.dbType === 'postgres') {
+        sql = `
+          INSERT INTO ${this.tableName} (template_id, event_name, is_active, updated_at)
+          VALUES ($1, $2, $3, CURRENT_TIMESTAMP)
+          ON CONFLICT (template_id)
+          DO NOTHING
+        `;
+        params = [templateId, '', false];
+      } else {
+        // MySQL INSERT IGNORE
+        sql = `
+          INSERT IGNORE INTO ${this.tableName} (template_id, event_name, is_active, updated_at)
+          VALUES (?, ?, ?, CURRENT_TIMESTAMP)
+        `;
+        params = [templateId, '', false];
+      }
+      await this.dbClient.query(sql, params);
+    }
+  }
+}

package/src/service.ts

@@ -0,0 +1,221 @@
+import { BrevoClient } from './brevoClient.js';
+import { EmailTemplateRepository } from './repository.js';
+import { SDKConfig, CombinedTemplate, CreateTemplateInput, UpdateTemplateInput, BrevoSender } from './types.js';
+
+export class EmailTemplateService {
+  private brevoClient: BrevoClient;
+  private repository: EmailTemplateRepository;
+  private defaultSender: { name?: string; email: string };
+
+  constructor(config: SDKConfig) {
+    this.brevoClient = new BrevoClient(config.brevoApiKey);
+    this.repository = new EmailTemplateRepository(config);
+    this.defaultSender = config.defaultSender;
+  }
+
+  /**
+   * Syncs and returns all templates with their event mappings.
+   * Performs Just-In-Time (JIT) mapping creation for any templates missing in local DB.
+   */
+  async listTemplates(): Promise<CombinedTemplate[]> {
+    // 1. Fetch remote templates from Brevo
+    const brevoTemplates = await this.brevoClient.getTemplates();
+    
+    // 2. Fetch local mappings
+    const localMappings = await this.repository.getAllMappings();
+    const mappingMap = new Map(localMappings.map((m) => [m.template_id, m]));
+
+    const combined: CombinedTemplate[] = [];
+
+    for (const bt of brevoTemplates) {
+      let mapping = mappingMap.get(bt.id);
+
+      // 3. JIT Mapping Creation: If template exists on Brevo but not locally
+      if (!mapping) {
+        await this.repository.insertJITMapping(bt.id);
+        mapping = {
+          template_id: bt.id,
+          event_name: '',
+          is_active: false,
+        };
+      }
+
+      combined.push({
+        templateId: bt.id,
+        templateName: bt.name,
+        subject: bt.subject,
+        eventName: mapping.event_name,
+        isActive: bt.isActive && mapping.is_active, // Sync state
+        sender: bt.sender,
+      });
+    }
+
+    return combined;
+  }
+
+  /**
+   * Fetch a single combined template by ID.
+   * Creates JIT mapping if it is not in local DB.
+   */
+  async getTemplate(id: number): Promise<CombinedTemplate> {
+    const bt = await this.brevoClient.getTemplate(id);
+    let mapping = await this.repository.getMappingByTemplateId(id);
+
+    if (!mapping) {
+      await this.repository.insertJITMapping(id);
+      mapping = {
+        template_id: id,
+        event_name: '',
+        is_active: false,
+      };
+    }
+
+    return {
+      templateId: bt.id,
+      templateName: bt.name,
+      subject: bt.subject,
+      eventName: mapping.event_name,
+      isActive: bt.isActive && mapping.is_active,
+      sender: bt.sender,
+      htmlContent: bt.htmlContent,
+    };
+  }
+
+  /**
+   * Create a new Brevo Template and its corresponding local DB mapping
+   */
+  async createTemplate(input: CreateTemplateInput): Promise<CombinedTemplate> {
+    const name = input.name || 'New Untitled Template';
+    const subject = input.subject || 'Drafting Layout';
+    const senderEmail = input.senderEmail || this.defaultSender.email;
+    const senderName = input.senderName || this.defaultSender.name;
+
+    const htmlContent = '<html><body><p>Drafting...</p></body></html>';
+
+    // 1. Create on Brevo
+    const templateId = await this.brevoClient.createTemplate({
+      templateName: name,
+      subject: subject,
+      sender: { name: senderName, email: senderEmail },
+      htmlContent: htmlContent,
+      isActive: false,
+    });
+
+    // 2. Insert mapping in local DB
+    await this.repository.upsertMapping(templateId, '', false);
+
+    return {
+      templateId: templateId,
+      templateName: name,
+      subject: subject,
+      eventName: '',
+      isActive: false,
+      sender: { name: senderName || '', email: senderEmail },
+      htmlContent: htmlContent,
+    };
+  }
+
+  /**
+   * Update an existing template in Brevo and the local mapping DB
+   */
+  async updateTemplate(id: number, input: UpdateTemplateInput): Promise<CombinedTemplate> {
+    // Constraint: Template name cannot be blank
+    if (!input.templateName || input.templateName.trim() === '') {
+      throw new Error('Template name cannot be blank');
+    }
+
+    // Constraint: HTML content must exceed 10 characters
+    if (!input.htmlContent || input.htmlContent.length <= 10) {
+      throw new Error('HTML content must be greater than 10 characters');
+    }
+
+    const sender: BrevoSender = {
+      email: input.sender?.email || this.defaultSender.email,
+      name: input.sender?.name || this.defaultSender.name || '',
+    };
+
+    // 1. Update Brevo template configuration
+    await this.brevoClient.updateTemplate(id, {
+      templateName: input.templateName,
+      subject: input.subject,
+      sender: sender,
+      htmlContent: input.htmlContent,
+      isActive: input.isActive,
+    });
+
+    // 2. Update local mapping DB
+    await this.repository.upsertMapping(id, input.eventName || '', input.isActive);
+
+    return {
+      templateId: id,
+      templateName: input.templateName,
+      subject: input.subject,
+      eventName: input.eventName || '',
+      isActive: input.isActive,
+      sender: sender,
+      htmlContent: input.htmlContent,
+    };
+  }
+
+  /**
+   * Sync template active status across remote Brevo and local DB
+   */
+  async toggleTemplateActive(id: number, isActive: boolean): Promise<void> {
+    // 1. Retrieve the existing Brevo template details so we can re-submit them securely
+    const bt = await this.brevoClient.getTemplate(id);
+    
+    // 2. Flip remote status
+    await this.brevoClient.updateTemplate(id, {
+      templateName: bt.name,
+      subject: bt.subject,
+      sender: bt.sender || this.defaultSender,
+      htmlContent: bt.htmlContent || '',
+      isActive: isActive,
+    });
+
+    // 3. Update local DB mapping status
+    const mapping = await this.repository.getMappingByTemplateId(id);
+    const eventName = mapping ? mapping.event_name : '';
+    await this.repository.upsertMapping(id, eventName, isActive);
+  }
+
+  /**
+   * Retrieve list of verified sender profiles
+   */
+  async getSenders(): Promise<BrevoSender[]> {
+    return this.brevoClient.getSenders();
+  }
+
+  /**
+   * Application-facing transactional sender logic:
+   * Event triggers query mapping database, checks status, and routes transactional send to Brevo
+   */
+  async sendEventEmail(
+    eventName: string,
+    recipientEmail: string,
+    variables?: Record<string, any>
+  ): Promise<{ sent: boolean; message: string }> {
+    // 1. Find mapped template configuration
+    const mapping = await this.repository.getActiveMappingByEvent(eventName);
+
+    // 2. Guardrail: If template is disabled (isActive = false), event engine completely ignores it
+    if (!mapping || !mapping.is_active) {
+      return {
+        sent: false,
+        message: `Event '${eventName}' skipped: No active template mapped to this event.`,
+      };
+    }
+
+    // 3. Push transactional template send to Brevo API
+    await this.brevoClient.sendEmail({
+      templateId: mapping.template_id,
+      to: recipientEmail,
+      variables: variables,
+    });
+
+    return {
+      sent: true,
+      message: `Successfully sent email for event '${eventName}' using template #${mapping.template_id}.`,
+    };
+  }
+}