mailer-advance 4.0.1 โ†’ 6.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +46 -51
  2. package/package.json +1 -1
  3. package/src/repositories/mongo.repository.js +4 -3
  4. package/src/repositories/sql.repository.js +4 -3
package/README.md CHANGED
@@ -1,22 +1,20 @@
1
- # ๐Ÿš€ mailer-advance v4.0
1
+ # ๐Ÿš€ mailer-advance v6.0
2
2
 
3
3
  [![npm version](https://img.shields.io/npm/v/mailer-advance.svg?style=flat-square)](https://www.npmjs.com/package/mailer-advance)
4
4
  [![license](https://img.shields.io/npm/l/mailer-advance.svg?style=flat-square)](https://www.npmjs.com/package/mailer-advance)
5
5
  [![Node version](https://img.shields.io/badge/node-%3E%3D20-brightgreen?style=flat-square)](https://nodejs.org)
6
6
 
7
- **mailer-advance** is a high-performance, production-ready Node.js email engine. It provides dynamic SMTP management (hot-swapping), multi-database persistence (MongoDB, PostgreSQL, MySQL), and a premium, glassmorphic built-in UI for system administration.
7
+ **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.
8
8
 
9
9
  ---
10
10
 
11
- ## โœจ Key Features
11
+ ## โœจ v6.0 Highlights
12
12
 
13
- - ๐Ÿ—„๏ธ **Multi-DB Support**: Store SMTP configurations in MongoDB, Postgres, or MySQL.
14
- - ๐Ÿ”„ **Hot-Swapping**: Switch SMTP servers at runtime via API or Dashboard without restarts.
15
- - ๐ŸŽจ **Premium UI**: Built-in dark-mode dashboard for sending tests and managing profiles.
16
- - ๐Ÿ›ก๏ธ **Robust Security**: Full STARTTLS/SSL/TLS support with certificate pinning/validation.
17
- - ๐Ÿ“Ž **Rich Emails**: Native support for attachments and CID-mapped inline images.
18
- - ๐Ÿ“ฆ **Zero Overhead**: Optimized ESM-only package (~12KB) designed for high scale.
19
- - ๐Ÿ“– **Swagger Ready**: Auto-generated OpenApi documentation served at `/api-docs`.
13
+ - โšก **Smart Connection**: `connect()` automatically falls back to `process.env.DB_URI`.
14
+ - ๐Ÿ“– **Interactive Swagger UI**: Explore and test all APIs at `/api-docs`.
15
+ - ๐Ÿ—„๏ธ **Multi-DB Persistence**: Support for MongoDB, Postgres, and MySQL.
16
+ - ๐Ÿ”„ **Hot-Swapping**: Switch SMTP credentials at runtime via the Dashboard.
17
+ - ๐Ÿ›ก๏ธ **Production Ready**: Full STARTTLS support and descriptive error guards.
20
18
 
21
19
  ---
22
20
 
@@ -26,15 +24,10 @@
26
24
  npm install mailer-advance
27
25
  ```
28
26
 
29
- > [!IMPORTANT]
30
- > **ESM Only**: This package requires `"type": "module"` in your `package.json`.
31
-
32
27
  ---
33
28
 
34
29
  ## ๐Ÿš€ Quick Start (Library Mode)
35
30
 
36
- Integrate the engine into your Express app.
37
-
38
31
  ```javascript
39
32
  import express from 'express';
40
33
  import {
@@ -47,63 +40,65 @@ import {
47
40
  const app = express();
48
41
  app.use(express.json());
49
42
 
50
- // 1. Initialize Persistence (Required for UI/Storage)
43
+ // 1. Initialize Persistence (Smart Fallback to process.env.DB_URI)
51
44
  const repository = DatabaseFactory.createRepository(process.env.DB_TYPE || 'mongodb');
52
- await repository.connect(process.env.DB_URI); // throws Error if URI is missing
45
+ await repository.connect();
53
46
  dbService.setRepository(repository);
54
47
 
55
- // 2. Mount API & UI Routes
48
+ // 2. Mount API Routes
56
49
  app.use('/api/mail', contactRoutes);
57
50
  app.use('/api/config', configRoutes);
58
51
 
59
52
  app.listen(3000, () => {
60
- console.log('๐Ÿš€ Mailer engine ready at http://localhost:3000');
53
+ console.log('๐Ÿš€ Engine active at http://localhost:3000');
54
+ console.log('๐Ÿ“– API Docs: http://localhost:3000/api-docs');
61
55
  });
62
56
  ```
63
57
 
64
58
  ---
65
59
 
66
- ## โš™๏ธ Environment Configuration (.env)
60
+ ## ๐Ÿ“š Interactive API Documentation (Swagger)
67
61
 
68
- | Variable | Requirement | Description |
69
- |----------|-------------|-------------|
70
- | `DB_TYPE` | Optional | `mongodb`, `postgres`, or `mysql` (Default: `mongodb`) |
71
- | `DB_URI` | **Required** | Connection string for your chosen database. |
72
- | `PORT` | Optional | Port for the standalone server (Default: `3000`). |
73
- | `MAIL_HOST` | Optional | Fallback SMTP Host if no dynamic config is found. |
74
- | `MAIL_PORT` | Optional | Fallback SMTP Port (Default: `587`). |
75
- | `MAIL_SECURE` | Optional | `true` for Port 465, `false` for 587/STARTTLS. |
76
- | `MAIL_USER` | Optional | Fallback SMTP Username. |
77
- | `MAIL_PASS` | Optional | Fallback SMTP Password. |
78
-
79
- ### ๐Ÿ’ก Configuration Hierarchy
80
- 1. If a `configId` is passed in an API call, it uses the **Database Stored SMTP**.
81
- 2. If no `configId` exists, it falls back to **Environment Variables** (`MAIL_HOST`, etc.).
82
- 3. If neither exists, the request will fail.
62
+ V6.0.0 introduces a fully integrated **Swagger UI** for easier development and testing. Once your server is running, navigate to:
83
63
 
84
- ---
64
+ ๐Ÿ‘‰ **`http://localhost:3000/api-docs`**
85
65
 
86
- ## ๐Ÿ”’ Security Checklist
66
+ From there, you can:
67
+ - ๐Ÿ” **Explore**: See all available endpoints and their data structures.
68
+ - ๐Ÿงช **Test**: Send live requests to your mailer engine directly from the browser.
69
+ - ๐Ÿ“œ **Spec**: Download the OpenApi spec for use in other tools.
87
70
 
88
- To ensure your email service is secure in production, verify the following:
71
+ ---
89
72
 
90
- - [ ] **Database URI**: Ensure `DB_URI` is stored in a secure `.env` file and never committed to version control.
91
- - [ ] **TLS Validation**: By default, `rejectUnauthorized` is `true`. For development with self-signed certs, set `MAIL_TLS_REJECT_UNAUTHORIZED=false`.
92
- - [ ] **App Privacy**: If you mount the UI (`/contact.html`, etc.), ensure it is behind your own authentication middleware.
93
- - [ ] **Secrets**: Use [Dotenvx](https://dotenvx.com) or similar tools to encrypt your production secrets.
73
+ ## โš™๏ธ Environment Configuration (.env)
94
74
 
95
- ---
75
+ | Variable | Requirement | Description |
76
+ |----------|-------------|-------------|
77
+ | `DB_TYPE` | Optional | `mongodb`, `postgres`, or `mysql` (Default: `mongodb`) |
78
+ | `DB_URI` | **Required** | Your database connection string. |
79
+ | `MAIL_HOST` | Optional | Default SMTP Host (Fallback). |
80
+ | `MAIL_PORT` | Optional | Default SMTP Port (Default: `587`). |
81
+
82
+ ### ๐Ÿ’ก The .env Setup Guide
83
+ ```env
84
+ # Database
85
+ DB_TYPE=mongodb
86
+ DB_URI=mongodb://127.0.0.1:27017/my_mailer_db
87
+
88
+ # Fallback SMTP
89
+ MAIL_HOST=smtp.your-provider.com
90
+ MAIL_PORT=587
91
+ MAIL_USER=admin@example.com
92
+ MAIL_PASS=your-secure-password
93
+ ```
96
94
 
97
- ## ๐Ÿ›  Troubleshooting
95
+ ---
98
96
 
99
- ### `Error: Database connection URI is required`
100
- This error occurs in **v4.0.0+** if you attempt to connect a repository without a valid `DB_URI`.
101
- - **Fix**: Add `DB_URI=mongodb://your-ip:27017/dbname` (or equivalent) to your `.env` file.
102
- - **Why?**: Persistence is mandatory for the management UI and dynamic context swapping.
97
+ ## ๐Ÿ”’ Security & Best Practices
103
98
 
104
- ### SMTP Connection Failures
105
- - Verify `MAIL_PORT` (usually `587` for STARTTLS or `465` for SSL).
106
- - Ensure `MAIL_SECURE` is `true` ONLY for port `465`.
99
+ - **App Privacy**: Always wrap the mailer routes/UI with your own authentication middleware.
100
+ - **TLS validation**: Ensure `rejectUnauthorized` is `true` for production SMTP.
101
+ - **Secrets**: Encrypt your `.env` files using [Dotenvx](https://dotenvx.com).
107
102
 
108
103
  ---
109
104
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mailer-advance",
3
- "version": "4.0.1",
3
+ "version": "6.0.0",
4
4
  "description": "Advanced Node.js email service with dynamic SMTP configuration, multi-database support (MongoDB/SQL), and a built-in UI.",
5
5
  "main": "index.js",
6
6
  "type": "module",
package/src/repositories/mongo.repository.js CHANGED
@@ -4,10 +4,11 @@ import { BaseRepository } from './base.repository.js';
4
4
 
5
5
  export class MongoRepository extends BaseRepository {
6
6
  async connect(uri) {
7
- if (!uri || typeof uri !== 'string') {
8
- throw new Error('Database connection URI is required for MongoDB repository');
7
+ const connectionUri = uri || process.env.DB_URI;
8
+ if (!connectionUri || typeof connectionUri !== 'string') {
9
+ throw new Error('Database connection URI is required. Please provide it as a parameter to connect() or set the DB_URI environment variable.');
9
10
  }
10
- await mongoose.connect(uri);
11
+ await mongoose.connect(connectionUri);
11
12
  console.log('Connected to MongoDB');
12
13
  }
13
14
 
package/src/repositories/sql.repository.js CHANGED
@@ -8,10 +8,11 @@ export class SqlRepository extends BaseRepository {
8
8
  }
9
9
 
10
10
  async connect(uri) {
11
- if (!uri || typeof uri !== 'string') {
12
- throw new Error(`Database connection URI is required for SQL repository (${this.dialect})`);
11
+ const connectionUri = uri || process.env.DB_URI;
12
+ if (!connectionUri || typeof connectionUri !== 'string') {
13
+ 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.`);
13
14
  }
14
- this.sequelize = new Sequelize(uri, {
15
+ this.sequelize = new Sequelize(connectionUri, {
15
16
  dialect: this.dialect,
16
17
  logging: false
17
18
  });