@fufulog/brevomorphic-cms-sdk 1.0.0

package/dist/types.d.ts

@@ -0,0 +1,69 @@
+export interface BrevoSender {
+    id?: number;
+    name: string;
+    email: string;
+    active?: boolean;
+}
+export interface BrevoTemplate {
+    id: number;
+    name: string;
+    subject: string;
+    isActive: boolean;
+    htmlContent?: string;
+    sender?: BrevoSender;
+}
+export interface LocalMapping {
+    id?: number | string;
+    template_id: number;
+    event_name: string;
+    is_active: boolean;
+    updated_at?: Date | string;
+}
+export interface CombinedTemplate {
+    templateId: number;
+    templateName: string;
+    subject: string;
+    eventName: string;
+    isActive: boolean;
+    sender?: BrevoSender;
+    htmlContent?: string;
+}
+export interface SQLClient {
+    query: (sql: string, params: any[]) => Promise<any>;
+}
+export interface FirestoreClient {
+    collection: (collectionPath: string) => any;
+}
+export interface SDKConfig {
+    brevoApiKey: string;
+    defaultSender: {
+        name?: string;
+        email: string;
+    };
+    dbType: 'postgres' | 'mysql' | 'firestore';
+    /**
+     * For 'postgres': an object satisfying { query: (sql, params) => Promise<{ rows: any[] }> } or equivalent
+     * For 'mysql': an object satisfying { query: (sql, params) => Promise<[any[], any]> } or equivalent
+     * For 'firestore': an instance of Firebase Firestore DB
+     */
+    dbClient: any;
+    /**
+     * Table name for postgres/mysql, or Collection path for Firestore.
+     * Defaults to 'email_event_templates'
+     */
+    tableNameOrCollection?: string;
+}
+export interface CreateTemplateInput {
+    name?: string;
+    subject?: string;
+    senderEmail?: string;
+    senderName?: string;
+}
+export interface UpdateTemplateInput {
+    templateName: string;
+    subject: string;
+    sender: BrevoSender;
+    htmlContent: string;
+    eventName: string;
+    isActive: boolean;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/env.example

@@ -0,0 +1,25 @@
+# Brevo API Settings
+BREVO_API_KEY=xkeysib-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-xxxxxxxx
+DEFAULT_SENDER_EMAIL=noreply@example.com
+DEFAULT_SENDER_NAME="Brevo CMS Engine"
+
+# Database Configuration Strategy
+# Options: postgres | mysql | firestore
+DB_TYPE=postgres
+
+# --- SQL Database Connection (For bootstrapping host project) ---
+DB_HOST=localhost
+DB_PORT=5432
+DB_USER=joseph
+DB_PASSWORD=your_secure_password
+DB_NAME=brevo_cms_db
+DATABASE_URL=postgresql://joseph:your_secure_password@localhost:5432/brevo_cms_db
+SQL_TABLE_NAME=email_event_templates
+
+# --- NoSQL Firestore Connection Settings ---
+# If DB_TYPE=firestore, supply these OR rely on default Firebase credentials (e.g. Service Account)
+FIREBASE_PROJECT_ID=brevocms-prod
+FIREBASE_CLIENT_EMAIL=firebase-adminsdk-xxxxx@brevocms-prod.iam.gserviceaccount.com
+# Use literal \n inside string or place service account credentials JSON in a local configuration file
+FIREBASE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nMIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQC7...\n-----END PRIVATE KEY-----\n"
+FIRESTORE_COLLECTION_NAME=email_event_templates

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@fufulog/brevomorphic-cms-sdk",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "SDK library to bootstrap Brevo email templates and manage local mappings in Postgres, MySQL, or Firestore",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "tsx tests/sdk.test.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "brevo",
+    "cms",
+    "email",
+    "sdk",
+    "firestore",
+    "postgres",
+    "mysql"
+  ],
+  "author": "Joseph",
+  "license": "MIT",
+  "dependencies": {
+    "axios": "^1.6.8",
+    "dotenv": "^16.4.5"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.30",
+    "@types/express": "^4.17.21",
+    "typescript": "^5.4.3",
+    "tsx": "^4.7.1",
+    "express": "^4.19.2"
+  }
+}

package/prd.md

@@ -0,0 +1,135 @@
+# Product Requirement Document (PRD)
+
+## Project Overview
+
+This project aims to build a centralized, internal **Email Template Manager & Event Linker Dashboard**. The application will serve as a gateway dashboard that allows teams to manage, edit, and link Brevo email layouts directly to our application-specific backend events (e.g., `ticket.preapproved`, `user.welcome`).
+
+By maintaining a dedicated mapping database locally, the platform isolates core app logic from Brevo's internal identifiers while providing a clean, rich-text editing experience wrapper around Brevo’s API.
+
+---
+
+## 1. System Architecture & Objectives
+
+* **Decoupled Sync:** The system operates a two-way synchronization layer—pulling core presentation data from Brevo's API while using a local database as the absolute source of truth for routing events to templates.
+* **Zero Orphaned States:** New templates created via the dashboard will seamlessly spawn required local mapping definitions in an inactive state until configured.
+* **One-Way Outbound Sends:** Application event providers will query the local database map to find the correct active `template_id` and push a flat transaction to Brevo.
+
+---
+
+## 2. Core Functional Requirements
+
+### 2.1 Template List Screen (The Main Ledger)
+
+Upon accessing the dashboard, the system must render a comprehensive ledger combining Brevo template properties with local event configurations.
+
+* **Data Aggregation Engine:** The backend must fetch all templates from Brevo (`GET /v3/smtp/templates`) and cross-reference them against the local database table (`email_event_templates`).
+* **Just-In-Time (JIT) Local Mapping Generation:** If a template exists on Brevo but does not have a corresponding record in our local mapping database, the application must automatically generate a new mapping object in the local database with a blank `event_name` string and `is_active = false`.
+* **UI Columns Required:**
+* **Internal Template Name** (Read from Brevo metadata)
+* **Subject Line** (Read from Brevo metadata)
+* **Mapped Target Event** (Read from Local DB mapping)
+* **Status Toggle** (Reflects `isActive` state from Brevo / Local DB syncing)
+* **Actions:** Edit Button
+
+
+
+### 2.2 Template Activation / Deactivation Flow
+
+* The Template List screen must display a clear toggle switch or button indicating whether a template is active or disabled.
+* Clicking the button will execute an explicit toggle event that hits both systems:
+1. Update Brevo remotely (`PUT /v3/smtp/templates/{id}`) setting `isActive` to the new state.
+2. Update the local database mapping record (`is_active` boolean column).
+
+
+* **Guardrail:** If a template is marked disabled (`isActive = false`), the event engine must completely ignore it, ensuring it does not process or execute the associated target event if fired by an application.
+
+### 2.3 Creation Workflow ("New Template")
+
+When an authorized user clicks the **"New Template"** button, the system must automate the initialization sequence without leaving the current view:
+
+1. **Brevo Initialization:** The backend calls Brevo (`POST /v3/smtp/templates`) passing an initial structural setup name ("New Untitled Template"), placeholder subject line, verified default sender email, and a minimum valid HTML string skeleton (`<html><body><p>Drafting...</p></body></html>`).
+2. **ID Extraction:** Brevo returns a unique numerical `templateId`.
+3. **Local Mapping Insertion:** The backend immediately saves a new mapping row in our database linking the new `templateId` with an empty `event_name` and `is_active = false`.
+4. **Automatic Redirect:** The dashboard must automatically fetch the fresh payload properties and instantly open the **Edit Email Template** view for that specific ID.
+
+### 2.4 Edit Template View (The Screen Layout)
+
+This view provides an explicit interface for updating visual parameters and application routing logic, matching our verified structural wireframe design:
+
+* **Internal Template Name:** A required input field allowing the user to rename the template file identifier (`templateName` in Brevo).
+* **Subject:** A required input text field mapping to the email subject.
+* **Sender Selection:** A dropdown menu populated by valid sender profiles pulled down directly from Brevo's API (`GET /v3/senders`).
+* **Target Event Field:** A dropdown menu populated by our application’s known structural system events. Modifying this field directly updates the local database mapping row upon submission.
+* **Variable Injector ("Constants"):** A dropdown interface filled with system keys (e.g., `Customer Name`, `Ticket Code`). Clicking **"Insert Variable"** drops the appropriate Brevo Twig expression (e.g., `{{ params.name }}`) directly into the current cursor location inside the editor.
+* **Email Body WYSIWYG Editor:** A rich text editor component.
+* Must support full HTML markup layout architecture.
+* Must feature a **"Source"** toggle view button to allow advanced layout engineering and direct copy/pasting of raw template code blocks.
+* Must possess string rule protections to prevent the WYSIWYG parser from corrupting or encoding raw Twig brackets (`{{ ... }}` or `{% ... %}`).
+
+
+
+---
+
+## 3. Data Dictionary & Contract Mapping
+
+### 3.1 Local Database Contract (`email_event_templates`)
+
+```sql
+CREATE TABLE email_event_templates (
+    id SERIAL PRIMARY KEY,
+    event_name VARCHAR(255) UNIQUE, -- Stores user assigned target event string
+    template_id INT NOT NULL UNIQUE, -- Bridges directly to Brevo's Template ID
+    is_active BOOLEAN DEFAULT false,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+```
+
+### 3.2 Main Dashboard Fields to Brevo API Structural Alignment
+
+| Dashboard Form Element | Local DB Target | Brevo API Target Parameter | API Type |
+| --- | --- | --- | --- |
+| **Internal Name Input** | N/A | `templateName` | String |
+| **Subject Input** | N/A | `subject` | String |
+| **Sender Dropdown** | N/A | `sender.email` / `sender.id` | Object |
+| **Target Event Selection** | `event_name` | N/A (Stored locally in DB) | String |
+| **Status Toggle** | `is_active` | `isActive` | Boolean |
+| **WYSIWYG Workspace** | N/A | `htmlContent` | String (Full HTML) |
+
+---
+
+## 4. User Interaction Flows (User Journeys)
+
+### 4.1 Editing and Assigning an Existing Event
+
+```
+[User logs into Dashboard] 
+       │
+       ▼
+[List screen performs concurrent lookups: Local DB mappings + Brevo templates list]
+       │
+       ▼
+[System matches rows; auto-creates a fallback mapping block in local DB if anomalies exist]
+       │
+       ▼
+[User clicks "Edit" on a template row]
+       │
+       ▼
+[Router opens Editor UI populated with current Brevo details and the Local DB Target Event]
+       │
+       ▼
+[User rewrites HTML body, inputs an internal name, and changes Target Event to 'ticket.preapproved']
+       │
+       ▼
+[User clicks "Submit"] ───► 1. PUT Payload streams directly to Brevo API
+                          2. SQL Upsert saves 'ticket.preapproved' to Local DB Map
+
+```
+
+---
+
+## 5. Non-Functional & Security Requirements
+
+* **Content Sanitization Exception:** The rich text editor engine must be strictly configured **not** to escape or scrub symbols like `{`, `%`, or `}`. Doing so breaks Brevo’s templating system processor.
+* **API Network Fault Isolation:** If Brevo's API experiences downstream lag or outages, the local dashboard list should gracefully fail via a readable UI banner message while protecting database integrity.
+* **Payload Boundary Constraint:** The editor form must enforce standard text character validations before sending to Brevo: a template name cannot be blank, and the final extracted HTML content must exceed 10 characters to clear Brevo's server validations.

package/react/BrevoWysiwyg.css

@@ -0,0 +1,233 @@
+/* BrevoWysiwyg.css — Styles for the React WYSIWYG editor component */
+
+/* ── Container ── */
+.brevo-wysiwyg {
+  --brevo-bg: #1a1a2e;
+  --brevo-surface: #16213e;
+  --brevo-border: #2a2a4a;
+  --brevo-border-focus: #6366f1;
+  --brevo-text: #e2e8f0;
+  --brevo-text-muted: #94a3b8;
+  --brevo-accent: #6366f1;
+  --brevo-accent-hover: #818cf8;
+  --brevo-toolbar-bg: #0f1629;
+  --brevo-btn-hover: #2a2a4a;
+  --brevo-btn-active: #3730a3;
+  --brevo-radius: 8px;
+  --brevo-font: 'Inter', 'Segoe UI', system-ui, -apple-system, sans-serif;
+
+  font-family: var(--brevo-font);
+  border: 1.5px solid var(--brevo-border);
+  border-radius: var(--brevo-radius);
+  overflow: hidden;
+  background: var(--brevo-bg);
+  transition: border-color 0.2s ease;
+}
+
+.brevo-wysiwyg--focused {
+  border-color: var(--brevo-border-focus);
+  box-shadow: 0 0 0 3px rgba(99, 102, 241, 0.15);
+}
+
+.brevo-wysiwyg--disabled {
+  opacity: 0.55;
+  pointer-events: none;
+}
+
+/* ── Toolbar ── */
+.brevo-toolbar {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: 2px;
+  padding: 6px 8px;
+  background: var(--brevo-toolbar-bg);
+  border-bottom: 1px solid var(--brevo-border);
+}
+
+.brevo-toolbar__group {
+  display: flex;
+  gap: 2px;
+}
+
+.brevo-toolbar__divider {
+  width: 1px;
+  height: 22px;
+  background: var(--brevo-border);
+  margin: 0 4px;
+}
+
+.brevo-toolbar__spacer {
+  flex: 1;
+}
+
+/* ── Buttons ── */
+.brevo-btn {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  padding: 5px 10px;
+  border: none;
+  border-radius: 5px;
+  background: transparent;
+  color: var(--brevo-text-muted);
+  font-family: var(--brevo-font);
+  font-size: 13px;
+  cursor: pointer;
+  transition: all 0.15s ease;
+  white-space: nowrap;
+  line-height: 1.4;
+}
+
+.brevo-btn:hover {
+  background: var(--brevo-btn-hover);
+  color: var(--brevo-text);
+}
+
+.brevo-btn--active {
+  background: var(--brevo-btn-active);
+  color: #fff;
+}
+
+.brevo-btn--accent {
+  color: var(--brevo-accent);
+  font-weight: 500;
+}
+
+.brevo-btn--accent:hover {
+  color: var(--brevo-accent-hover);
+  background: rgba(99, 102, 241, 0.12);
+}
+
+.brevo-btn--source {
+  font-size: 12px;
+  font-weight: 600;
+  letter-spacing: 0.02em;
+}
+
+.brevo-btn:disabled {
+  opacity: 0.4;
+  cursor: not-allowed;
+}
+
+/* ── Dropdowns ── */
+.brevo-dropdown {
+  position: relative;
+}
+
+.brevo-dropdown__menu {
+  position: absolute;
+  top: calc(100% + 4px);
+  left: 0;
+  min-width: 160px;
+  padding: 4px;
+  background: var(--brevo-surface);
+  border: 1px solid var(--brevo-border);
+  border-radius: 6px;
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.4);
+  z-index: 100;
+  animation: brevo-dropdown-in 0.12s ease-out;
+}
+
+.brevo-dropdown__menu--variables {
+  min-width: 260px;
+}
+
+@keyframes brevo-dropdown-in {
+  from {
+    opacity: 0;
+    transform: translateY(-4px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+.brevo-dropdown__menu button {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  width: 100%;
+  padding: 7px 10px;
+  border: none;
+  border-radius: 4px;
+  background: transparent;
+  color: var(--brevo-text);
+  font-family: var(--brevo-font);
+  font-size: 13px;
+  cursor: pointer;
+  text-align: left;
+  gap: 8px;
+}
+
+.brevo-dropdown__menu button:hover {
+  background: var(--brevo-btn-hover);
+}
+
+.brevo-var-label {
+  flex: 1;
+}
+
+.brevo-var-key {
+  font-size: 11px;
+  color: var(--brevo-accent);
+  background: rgba(99, 102, 241, 0.1);
+  padding: 2px 6px;
+  border-radius: 3px;
+  font-family: 'JetBrains Mono', 'Fira Code', monospace;
+}
+
+/* ── Editor ── */
+.brevo-editor-wrapper {
+  background: var(--brevo-bg);
+}
+
+.brevo-editor {
+  min-height: 320px;
+  max-height: 600px;
+  overflow-y: auto;
+  padding: 20px 24px;
+  color: var(--brevo-text);
+  font-size: 15px;
+  line-height: 1.7;
+  outline: none;
+  word-wrap: break-word;
+  overflow-wrap: break-word;
+}
+
+.brevo-editor:empty::before {
+  content: attr(data-placeholder);
+  color: var(--brevo-text-muted);
+  opacity: 0.5;
+  pointer-events: none;
+}
+
+.brevo-editor h1 { font-size: 1.8em; font-weight: 700; margin: 0.4em 0; }
+.brevo-editor h2 { font-size: 1.4em; font-weight: 600; margin: 0.4em 0; }
+.brevo-editor h3 { font-size: 1.15em; font-weight: 600; margin: 0.4em 0; }
+.brevo-editor a { color: var(--brevo-accent-hover); text-decoration: underline; }
+.brevo-editor ul,
+.brevo-editor ol { padding-left: 1.6em; }
+
+/* ── Source ── */
+.brevo-source {
+  width: 100%;
+  min-height: 320px;
+  max-height: 600px;
+  padding: 16px 20px;
+  border: none;
+  background: #0d1117;
+  color: #c9d1d9;
+  font-family: 'JetBrains Mono', 'Fira Code', 'Cascadia Code', monospace;
+  font-size: 13px;
+  line-height: 1.65;
+  resize: vertical;
+  outline: none;
+  tab-size: 2;
+  box-sizing: border-box;
+}
+
+.brevo-source::placeholder {
+  color: #484f58;
+}