mailer-advance 3.0.0 → 4.0.1
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,22 @@
|
|
|
1
|
-
# 🚀 mailer-advance
|
|
1
|
+
# 🚀 mailer-advance v4.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, 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.
|
|
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.
|
|
8
8
|
|
|
9
9
|
---
|
|
10
10
|
|
|
11
|
-
## ✨ Features
|
|
11
|
+
## ✨ Key Features
|
|
12
12
|
|
|
13
|
-
- 🗄️ **
|
|
14
|
-
- 🔄 **Hot-Swapping**: Switch SMTP servers at runtime via API or
|
|
15
|
-
- 🎨 **Premium UI**: Built-in dark-mode dashboard for sending tests and managing
|
|
16
|
-
-
|
|
17
|
-
- 📎 **Rich
|
|
18
|
-
- 📦 **Zero Overhead**:
|
|
19
|
-
- 📖 **Swagger
|
|
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`.
|
|
20
20
|
|
|
21
21
|
---
|
|
22
22
|
|
|
@@ -31,16 +31,15 @@ npm install mailer-advance
|
|
|
31
31
|
|
|
32
32
|
---
|
|
33
33
|
|
|
34
|
-
##
|
|
34
|
+
## 🚀 Quick Start (Library Mode)
|
|
35
35
|
|
|
36
|
-
Integrate the
|
|
36
|
+
Integrate the engine into your Express app.
|
|
37
37
|
|
|
38
38
|
```javascript
|
|
39
39
|
import express from 'express';
|
|
40
40
|
import {
|
|
41
41
|
contactRoutes,
|
|
42
42
|
configRoutes,
|
|
43
|
-
mailService,
|
|
44
43
|
dbService,
|
|
45
44
|
DatabaseFactory
|
|
46
45
|
} from 'mailer-advance';
|
|
@@ -48,54 +47,63 @@ import {
|
|
|
48
47
|
const app = express();
|
|
49
48
|
app.use(express.json());
|
|
50
49
|
|
|
51
|
-
// 1. Initialize
|
|
52
|
-
const repository = DatabaseFactory.createRepository('mongodb');
|
|
53
|
-
await repository.connect(process.env.DB_URI);
|
|
50
|
+
// 1. Initialize Persistence (Required for UI/Storage)
|
|
51
|
+
const repository = DatabaseFactory.createRepository(process.env.DB_TYPE || 'mongodb');
|
|
52
|
+
await repository.connect(process.env.DB_URI); // throws Error if URI is missing
|
|
54
53
|
dbService.setRepository(repository);
|
|
55
54
|
|
|
56
|
-
// 2. Mount Routes
|
|
57
|
-
app.use('/api/mail', contactRoutes);
|
|
58
|
-
app.use('/api/config', configRoutes);
|
|
55
|
+
// 2. Mount API & UI Routes
|
|
56
|
+
app.use('/api/mail', contactRoutes);
|
|
57
|
+
app.use('/api/config', configRoutes);
|
|
59
58
|
|
|
60
|
-
// 3. Access Admin UI (Optional)
|
|
61
|
-
// The UI is served relative to your static assets if configured
|
|
62
59
|
app.listen(3000, () => {
|
|
63
60
|
console.log('🚀 Mailer engine ready at http://localhost:3000');
|
|
64
|
-
console.log('📖 Documentation: http://localhost:3000/api-docs');
|
|
65
61
|
});
|
|
66
62
|
```
|
|
67
63
|
|
|
68
64
|
---
|
|
69
65
|
|
|
70
|
-
##
|
|
66
|
+
## ⚙️ Environment Configuration (.env)
|
|
71
67
|
|
|
72
|
-
|
|
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. |
|
|
73
78
|
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
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.
|
|
78
83
|
|
|
79
84
|
---
|
|
80
85
|
|
|
81
|
-
##
|
|
86
|
+
## 🔒 Security Checklist
|
|
82
87
|
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
| `MAIL_PORT` | Fallback SMTP Port | `587` |
|
|
88
|
+
To ensure your email service is secure in production, verify the following:
|
|
89
|
+
|
|
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.
|
|
90
94
|
|
|
91
95
|
---
|
|
92
96
|
|
|
93
|
-
##
|
|
97
|
+
## 🛠 Troubleshooting
|
|
98
|
+
|
|
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.
|
|
94
103
|
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
3. **Safety Guards**: `DbService` now throws descriptive errors if used before initialization.
|
|
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
107
|
|
|
100
108
|
---
|
|
101
109
|
|
package/package.json
CHANGED
|
@@ -4,6 +4,9 @@ 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');
|
|
9
|
+
}
|
|
7
10
|
await mongoose.connect(uri);
|
|
8
11
|
console.log('Connected to MongoDB');
|
|
9
12
|
}
|
|
@@ -8,6 +8,9 @@ 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})`);
|
|
13
|
+
}
|
|
11
14
|
this.sequelize = new Sequelize(uri, {
|
|
12
15
|
dialect: this.dialect,
|
|
13
16
|
logging: false
|