mailer-advance 4.0.0 → 5.0.0

package/README.md

@@ -1,22 +1,20 @@
-# 🚀 mailer-advance v2.0
+# 🚀 mailer-advance v5.0
 
 [![npm version](https://img.shields.io/npm/v/mailer-advance.svg?style=flat-square)](https://www.npmjs.com/package/mailer-advance)
 [![license](https://img.shields.io/npm/l/mailer-advance.svg?style=flat-square)](https://www.npmjs.com/package/mailer-advance)
 [![Node version](https://img.shields.io/badge/node-%3E%3D20-brightgreen?style=flat-square)](https://nodejs.org)
 
-**mailer-advance** is a high-performance, production-ready Node.js email engine. It provides dynamic SMTP management, multi-database persistence (MongoDB, PostgreSQL, MySQL), and a premium, glassmorphic built-in UI for administration.
+**mailer-advance** is a high-performance Node.js email engine with absolute flexibility. It features dynamic SMTP hot-swapping, multi-DB persistence, and a premium "management-in-a-box" UI.
 
 ---
 
-## ✨ Features
+## ✨ v5.0 Highlights
 
-- 🗄️ **Persistence**: Multi-database support for storing SMTP configs (MongoDB, Postgres, MySQL).
-- 🔄 **Hot-Swapping**: Switch SMTP servers at runtime via API or the Admin Dashboard.
-- 🎨 **Premium UI**: Built-in dark-mode dashboard for sending tests and managing configs.
-- 🔒 **Secure by Design**: Full STARTTLS/SSL/TLS support with configurable certificate validation.
-- 📎 **Rich Media**: Support for attachments and inline images ($cid$ mapping).
-- 📦 **Zero Overhead**: Ultra-lightweight (~12KB) ESM-only package with minimal dependencies.
-- 📖 **Swagger Included**: Auto-generated API documentation for easy integration.
+- ⚡ **Smart Connection**: No need to pass URIs manually. `connect()` now automatically falls back to `process.env.DB_URI`.
+- 🗄️ **Multi-DB Persistence**: Store configurations in MongoDB, Postgres, or MySQL.
+- 🔄 **Zero-Restart Swapping**: Switch SMTP credentials at runtime via the Dashboard.
+- 🛡️ **Production Ready**: Full STARTTLS support and descriptive error guards.
+- 📖 **Swagger UI**: API docs auto-served at `/api-docs`.
 
 ---
 
@@ -26,21 +24,15 @@
 npm install mailer-advance
 ```
 
-> [!IMPORTANT]
-> **ESM Only**: This package requires `"type": "module"` in your `package.json`.
-
 ---
 
-## � Quick Start (Library Mode)
-
-Integrate the email engine into your existing Express app in less than 2 minutes.
+## 🚀 Quick Start (Library Mode)
 
 ```javascript
 import express from 'express';
 import { 
     contactRoutes, 
     configRoutes, 
-    mailService, 
     dbService, 
     DatabaseFactory 
 } from 'mailer-advance';
@@ -48,54 +40,60 @@ import {
 const app = express();
 app.use(express.json());
 
-// 1. Initialize Database
-const repository = DatabaseFactory.createRepository('mongodb'); // or 'postgres', 'mysql'
-await repository.connect(process.env.DB_URI);
+// 1. Initialize Persistence (Smart Fallback to process.env.DB_URI)
+const repository = DatabaseFactory.createRepository(process.env.DB_TYPE || 'mongodb');
+await repository.connect(); // ✨ Automagically uses DB_URI from .env
 dbService.setRepository(repository);
 
-// 2. Mount Routes
-app.use('/api/mail', contactRoutes);    // Form submissions
-app.use('/api/config', configRoutes);  // SMTP Management
+// 2. Mount API Routes
+app.use('/api/mail', contactRoutes);
+app.use('/api/config', configRoutes);
 
-// 3. Access Admin UI (Optional)
-// The UI is served relative to your static assets if configured
-app.listen(3000, () => {
-    console.log('🚀 Mailer engine ready at http://localhost:3000');
-    console.log('📖 Documentation: http://localhost:3000/api-docs');
-});
+app.listen(3000, () => console.log('🚀 Engine active at http://localhost:3000'));
 ```
 
 ---
 
-## 🖥 Admin Dashboard
-
-When serving the package, the following tools are available:
-
-- � **Send Test**: `http://localhost:3000/contact.html`
-- 📑 **Manage Configs**: `http://localhost:3000/list-configs.html`
-- ➕ **Add New**: `http://localhost:3000/config.html`
-- 📚 **Swagger Docs**: `http://localhost:3000/api-docs`
+## ⚙️ Environment Configuration (.env)
+
+| Variable | Requirement | Description |
+|----------|-------------|-------------|
+| `DB_TYPE` | Optional | `mongodb`, `postgres`, or `mysql` (Default: `mongodb`) |
+| `DB_URI` | **Required** | Your database connection string. |
+| `MAIL_HOST` | Optional | Default SMTP Host (Fallback). |
+| `MAIL_PORT` | Optional | Default SMTP Port (Default: `587`). |
+
+### 💡 The .env Setup Guide
+For the engine to function correctly as a library, ensure your project's `.env` contains:
+```env
+# Database
+DB_TYPE=mongodb
+DB_URI=mongodb://127.0.0.1:27017/my_mailer_db
+
+# Fallback SMTP (Initial Setup)
+MAIL_HOST=smtp.your-provider.com
+MAIL_PORT=587
+MAIL_USER=admin@example.com
+MAIL_PASS=your-secure-password
+```
 
 ---
 
-## ⚙️ Configuration (.env)
+## 🔒 Security & Best Practices
 
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `PORT` | Server port | `3000` |
-| `DB_TYPE` | `mongodb`, `postgres`, `mysql` | `mongodb` |
-| `DB_URI` | Connection string | - |
-| `MAIL_HOST` | Fallback SMTP Host | - |
-| `MAIL_PORT` | Fallback SMTP Port | `587` |
+- **App Privacy**: Always wrap the mailer routes/UI with your own authentication middleware in production.
+- **TLS validation**: Ensure `rejectUnauthorized` is `true` for production SMTP connections.
+- **Secrets**: Encrypt your `.env` files using tools like [Dotenvx](https://dotenvx.com).
 
 ---
 
-## 🔄 Migration to v2.0.0
+## 🛠 Troubleshooting
 
-V2 introduces breaking changes to improve library integration:
-1. **Named Exports**: All modules now use named exports instead of a single default export.
-2. **Relative UI Paths**: The built-in dashboard now uses relative API paths, allowing it to be mounted on any sub-path (e.g., `/admin/mailer/`).
-3. **Safety Guards**: `DbService` now throws descriptive errors if used before initialization.
+### `Error: Database connection URI is required`
+This occurs if `process.env.DB_URI` is undefined.
+1. Ensure your `.env` file exists in the root of your project.
+2. Verify you are using `dotenv.config()` BEFORE initializing the mailer.
+3. Check the variable name is exactly `DB_URI`.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mailer-advance",
-  "version": "4.0.0",
+  "version": "5.0.0",
   "description": "Advanced Node.js email service with dynamic SMTP configuration, multi-database support (MongoDB/SQL), and a built-in UI.",
   "main": "index.js",
   "type": "module",

package/src/repositories/mongo.repository.js

@@ -4,10 +4,11 @@ import { BaseRepository } from './base.repository.js';
 
 export class MongoRepository extends BaseRepository {
     async connect(uri) {
-        if (!uri || typeof uri !== 'string') {
-            throw new Error('Database connection URI is required for MongoDB repository');
+        const connectionUri = uri || process.env.DB_URI;
+        if (!connectionUri || typeof connectionUri !== 'string') {
+            throw new Error('Database connection URI is required. Please provide it as a parameter to connect() or set the DB_URI environment variable.');
         }
-        await mongoose.connect(uri);
+        await mongoose.connect(connectionUri);
         console.log('Connected to MongoDB');
     }
 

package/src/repositories/sql.repository.js

@@ -8,10 +8,11 @@ export class SqlRepository extends BaseRepository {
     }
 
     async connect(uri) {
-        if (!uri || typeof uri !== 'string') {
-            throw new Error(`Database connection URI is required for SQL repository (${this.dialect})`);
+        const connectionUri = uri || process.env.DB_URI;
+        if (!connectionUri || typeof connectionUri !== 'string') {
+            throw new Error(`Database connection URI is required for SQL repository (${this.dialect}). Please provide it as a parameter to connect() or set the DB_URI environment variable.`);
         }
-        this.sequelize = new Sequelize(uri, {
+        this.sequelize = new Sequelize(connectionUri, {
             dialect: this.dialect,
             logging: false
         });