mailer-advance 4.0.1 → 5.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.
package/README.md
CHANGED
|
@@ -1,22 +1,20 @@
|
|
|
1
|
-
# 🚀 mailer-advance
|
|
1
|
+
# 🚀 mailer-advance v5.0
|
|
2
2
|
|
|
3
3
|
[](https://www.npmjs.com/package/mailer-advance)
|
|
4
4
|
[](https://www.npmjs.com/package/mailer-advance)
|
|
5
5
|
[](https://nodejs.org)
|
|
6
6
|
|
|
7
|
-
**mailer-advance** is a high-performance
|
|
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
|
-
## ✨
|
|
11
|
+
## ✨ v5.0 Highlights
|
|
12
12
|
|
|
13
|
-
-
|
|
14
|
-
-
|
|
15
|
-
-
|
|
16
|
-
- 🛡️ **
|
|
17
|
-
-
|
|
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**: No need to pass URIs manually. `connect()` now automatically falls back to `process.env.DB_URI`.
|
|
14
|
+
- 🗄️ **Multi-DB Persistence**: Store configurations in MongoDB, Postgres, or MySQL.
|
|
15
|
+
- 🔄 **Zero-Restart Swapping**: Switch SMTP credentials at runtime via the Dashboard.
|
|
16
|
+
- 🛡️ **Production Ready**: Full STARTTLS support and descriptive error guards.
|
|
17
|
+
- 📖 **Swagger UI**: API docs auto-served at `/api-docs`.
|
|
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,18 +40,16 @@ import {
|
|
|
47
40
|
const app = express();
|
|
48
41
|
app.use(express.json());
|
|
49
42
|
|
|
50
|
-
// 1. Initialize Persistence (
|
|
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(
|
|
45
|
+
await repository.connect(); // ✨ Automagically uses DB_URI from .env
|
|
53
46
|
dbService.setRepository(repository);
|
|
54
47
|
|
|
55
|
-
// 2. Mount API
|
|
48
|
+
// 2. Mount API Routes
|
|
56
49
|
app.use('/api/mail', contactRoutes);
|
|
57
50
|
app.use('/api/config', configRoutes);
|
|
58
51
|
|
|
59
|
-
app.listen(3000, () =>
|
|
60
|
-
console.log('🚀 Mailer engine ready at http://localhost:3000');
|
|
61
|
-
});
|
|
52
|
+
app.listen(3000, () => console.log('🚀 Engine active at http://localhost:3000'));
|
|
62
53
|
```
|
|
63
54
|
|
|
64
55
|
---
|
|
@@ -68,42 +59,41 @@ app.listen(3000, () => {
|
|
|
68
59
|
| Variable | Requirement | Description |
|
|
69
60
|
|----------|-------------|-------------|
|
|
70
61
|
| `DB_TYPE` | Optional | `mongodb`, `postgres`, or `mysql` (Default: `mongodb`) |
|
|
71
|
-
| `DB_URI` | **Required** |
|
|
72
|
-
| `
|
|
73
|
-
| `
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
1
|
|
81
|
-
|
|
82
|
-
|
|
62
|
+
| `DB_URI` | **Required** | Your database connection string. |
|
|
63
|
+
| `MAIL_HOST` | Optional | Default SMTP Host (Fallback). |
|
|
64
|
+
| `MAIL_PORT` | Optional | Default SMTP Port (Default: `587`). |
|
|
65
|
+
|
|
66
|
+
### 💡 The .env Setup Guide
|
|
67
|
+
For the engine to function correctly as a library, ensure your project's `.env` contains:
|
|
68
|
+
```env
|
|
69
|
+
# Database
|
|
70
|
+
DB_TYPE=mongodb
|
|
71
|
+
DB_URI=mongodb://127.0.0.1:27017/my_mailer_db
|
|
72
|
+
|
|
73
|
+
# Fallback SMTP (Initial Setup)
|
|
74
|
+
MAIL_HOST=smtp.your-provider.com
|
|
75
|
+
MAIL_PORT=587
|
|
76
|
+
MAIL_USER=admin@example.com
|
|
77
|
+
MAIL_PASS=your-secure-password
|
|
78
|
+
```
|
|
83
79
|
|
|
84
80
|
---
|
|
85
81
|
|
|
86
|
-
## 🔒 Security
|
|
82
|
+
## 🔒 Security & Best Practices
|
|
87
83
|
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
-
|
|
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.
|
|
84
|
+
- **App Privacy**: Always wrap the mailer routes/UI with your own authentication middleware in production.
|
|
85
|
+
- **TLS validation**: Ensure `rejectUnauthorized` is `true` for production SMTP connections.
|
|
86
|
+
- **Secrets**: Encrypt your `.env` files using tools like [Dotenvx](https://dotenvx.com).
|
|
94
87
|
|
|
95
88
|
---
|
|
96
89
|
|
|
97
90
|
## 🛠 Troubleshooting
|
|
98
91
|
|
|
99
92
|
### `Error: Database connection URI is required`
|
|
100
|
-
This
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
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`.
|
|
93
|
+
This occurs if `process.env.DB_URI` is undefined.
|
|
94
|
+
1. Ensure your `.env` file exists in the root of your project.
|
|
95
|
+
2. Verify you are using `dotenv.config()` BEFORE initializing the mailer.
|
|
96
|
+
3. Check the variable name is exactly `DB_URI`.
|
|
107
97
|
|
|
108
98
|
---
|
|
109
99
|
|
package/package.json
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
|
-
|
|
8
|
-
|
|
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(
|
|
11
|
+
await mongoose.connect(connectionUri);
|
|
11
12
|
console.log('Connected to MongoDB');
|
|
12
13
|
}
|
|
13
14
|
|
|
@@ -8,10 +8,11 @@ export class SqlRepository extends BaseRepository {
|
|
|
8
8
|
}
|
|
9
9
|
|
|
10
10
|
async connect(uri) {
|
|
11
|
-
|
|
12
|
-
|
|
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(
|
|
15
|
+
this.sequelize = new Sequelize(connectionUri, {
|
|
15
16
|
dialect: this.dialect,
|
|
16
17
|
logging: false
|
|
17
18
|
});
|