@fufulog/brevomorphic-cms-sdk 1.0.0

package/dist/controller.js

@@ -0,0 +1,173 @@
+import { Router } from 'express';
+export class EmailTemplateController {
+    service;
+    constructor(service) {
+        this.service = service;
+    }
+    /**
+     * Generates a fully configured Express Router.
+     * Can be directly mounted into any Express app: `app.use('/api/cms', controller.getRouter())`
+     */
+    getRouter() {
+        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, res) {
+        try {
+            const templates = await this.service.listTemplates();
+            res.status(200).json({ success: true, data: templates });
+        }
+        catch (error) {
+            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, res) {
+        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) {
+            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, res) {
+        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) {
+            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, res) {
+        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) {
+            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, res) {
+        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) {
+            res.status(500).json({ success: false, error: error.message });
+        }
+    }
+    /**
+     * GET /senders
+     * Lists verified sender profiles from Brevo.
+     */
+    async listSenders(req, res) {
+        try {
+            const senders = await this.service.getSenders();
+            res.status(200).json({ success: true, data: senders });
+        }
+        catch (error) {
+            res.status(500).json({ success: false, error: error.message });
+        }
+    }
+    /**
+     * POST /send
+     * Triggers an email send for a given backend event.
+     */
+    async sendEventEmail(req, res) {
+        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) {
+            res.status(500).json({ success: false, error: error.message });
+        }
+    }
+}

package/dist/index.d.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/dist/index.js

@@ -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/dist/repository.d.ts

@@ -0,0 +1,34 @@
+import { SDKConfig, LocalMapping } from './types.js';
+export declare class EmailTemplateRepository {
+    private dbType;
+    private dbClient;
+    private tableName;
+    constructor(config: SDKConfig);
+    /**
+     * Helper to parse SQL queries results.
+     * Handles PostgreSQL result format (res.rows) and MySQL format ([rows, fields]).
+     */
+    private parseSQLResult;
+    /**
+     * Fetch all event-to-template mappings from the local database
+     */
+    getAllMappings(): Promise<LocalMapping[]>;
+    /**
+     * Fetch mapping for a specific template ID
+     */
+    getMappingByTemplateId(templateId: number): Promise<LocalMapping | null>;
+    /**
+     * Fetch mapping for a specific event name.
+     * Assumes we want the active template linked to this event.
+     */
+    getActiveMappingByEvent(eventName: string): Promise<LocalMapping | null>;
+    /**
+     * Upsert a mapping (insert or update template config)
+     */
+    upsertMapping(templateId: number, eventName: string, isActive: boolean): Promise<void>;
+    /**
+     * Just-In-Time (JIT) Local Mapping Generation.
+     * If mapping does not exist, insert blank inactive mapping.
+     */
+    insertJITMapping(templateId: number): Promise<void>;
+}

package/dist/repository.js

@@ -0,0 +1,224 @@
+export class EmailTemplateRepository {
+    dbType;
+    dbClient;
+    tableName;
+    constructor(config) {
+        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]).
+     */
+    parseSQLResult(res) {
+        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() {
+        if (this.dbType === 'firestore') {
+            const snapshot = await this.dbClient.collection(this.tableName).get();
+            const mappings = [];
+            snapshot.forEach((doc) => {
+                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) => ({
+                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) {
+        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) {
+        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, eventName, isActive) {
+        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 = [];
+            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) {
+        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 = [];
+            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/dist/service.d.ts

@@ -0,0 +1,41 @@
+import { SDKConfig, CombinedTemplate, CreateTemplateInput, UpdateTemplateInput, BrevoSender } from './types.js';
+export declare class EmailTemplateService {
+    private brevoClient;
+    private repository;
+    private defaultSender;
+    constructor(config: SDKConfig);
+    /**
+     * Syncs and returns all templates with their event mappings.
+     * Performs Just-In-Time (JIT) mapping creation for any templates missing in local DB.
+     */
+    listTemplates(): Promise<CombinedTemplate[]>;
+    /**
+     * Fetch a single combined template by ID.
+     * Creates JIT mapping if it is not in local DB.
+     */
+    getTemplate(id: number): Promise<CombinedTemplate>;
+    /**
+     * Create a new Brevo Template and its corresponding local DB mapping
+     */
+    createTemplate(input: CreateTemplateInput): Promise<CombinedTemplate>;
+    /**
+     * Update an existing template in Brevo and the local mapping DB
+     */
+    updateTemplate(id: number, input: UpdateTemplateInput): Promise<CombinedTemplate>;
+    /**
+     * Sync template active status across remote Brevo and local DB
+     */
+    toggleTemplateActive(id: number, isActive: boolean): Promise<void>;
+    /**
+     * Retrieve list of verified sender profiles
+     */
+    getSenders(): Promise<BrevoSender[]>;
+    /**
+     * Application-facing transactional sender logic:
+     * Event triggers query mapping database, checks status, and routes transactional send to Brevo
+     */
+    sendEventEmail(eventName: string, recipientEmail: string, variables?: Record<string, any>): Promise<{
+        sent: boolean;
+        message: string;
+    }>;
+}

package/dist/service.js

@@ -0,0 +1,185 @@
+import { BrevoClient } from './brevoClient.js';
+import { EmailTemplateRepository } from './repository.js';
+export class EmailTemplateService {
+    brevoClient;
+    repository;
+    defaultSender;
+    constructor(config) {
+        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() {
+        // 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 = [];
+        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) {
+        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) {
+        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, input) {
+        // 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 = {
+            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, isActive) {
+        // 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() {
+        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, recipientEmail, variables) {
+        // 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}.`,
+        };
+    }
+}