@flusys/nestjs-email 4.1.1 → 5.0.0

package/README.md

@@ -1,72 +1,9 @@
 # @flusys/nestjs-email
 
-> Production-grade email management for NestJS — multi-provider (SMTP, SendGrid, Mailgun), database-driven template engine with `{{variable}}` interpolation, company scoping, and multi-tenant support.
+Database-driven email system for NestJS — multi-provider (SMTP, SendGrid, Mailgun), template engine with `{{variable}}` interpolation, and company scoping.
 
 [![npm version](https://img.shields.io/npm/v/@flusys/nestjs-email.svg)](https://www.npmjs.com/package/@flusys/nestjs-email)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![NestJS](https://img.shields.io/badge/NestJS-11.x-red.svg)](https://nestjs.com/)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org/)
-[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18.x-green.svg)](https://nodejs.org/)
-
----
-
-## Table of Contents
-
-- [Overview](#overview)
-- [Features](#features)
-- [Compatibility](#compatibility)
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [Module Registration](#module-registration)
-  - [forRoot (Sync)](#forroot-sync)
-  - [forRootAsync (Factory)](#forrootasync-factory)
-  - [forRootAsync (Class)](#forrootasync-class)
-- [Configuration Reference](#configuration-reference)
-- [Feature Toggles](#feature-toggles)
-- [API Endpoints](#api-endpoints)
-- [Entities](#entities)
-- [Email Providers](#email-providers)
-  - [SMTP (Default)](#smtp-default)
-  - [SendGrid](#sendgrid)
-  - [Mailgun](#mailgun)
-  - [Custom Provider](#custom-provider)
-- [Template Engine](#template-engine)
-- [Exported Services](#exported-services)
-- [Sending Emails Programmatically](#sending-emails-programmatically)
-- [Troubleshooting](#troubleshooting)
-- [License](#license)
-
----
-
-## Overview
-
-`@flusys/nestjs-email` provides a complete email management system. Email provider configurations and templates are stored in the database — no code changes are needed to add new email templates or switch providers. Providers are loaded dynamically, so you only install the SDK for the providers you use.
-
----
-
-## Features
-
-- **Multi-provider** — SMTP (nodemailer), SendGrid, Mailgun with a pluggable custom provider interface
-- **Database-driven templates** — Templates stored in PostgreSQL with `{{variable}}` interpolation
-- **HTML XSS protection** — All variable values are HTML-escaped before interpolation
-- **Provider caching** — SHA-256 config hash prevents duplicate provider instances
-- **Test email** — Verify a provider configuration before using it in production
-- **Company scoping** — Optional `companyId` on configs and templates for multi-company setups
-- **Multi-tenant** — Per-tenant DataSource isolation via the DataSource Provider pattern
-- **Attachments** — Base64-encoded file attachments supported
-
----
-
-## Compatibility
-
-| Package | Version |
-|---------|---------|
-| `@flusys/nestjs-core` | `^4.0.0` |
-| `@flusys/nestjs-shared` | `^4.0.0` |
-| `nodemailer` | `^6.0.0` |
-| `@sendgrid/mail` | `^8.0.0` *(optional)* |
-| `mailgun.js` | `^10.0.0` *(optional)* |
-| Node.js | `>= 18.x` |
 
 ---
 
@@ -75,20 +12,19 @@
 ```bash
 npm install @flusys/nestjs-email @flusys/nestjs-shared @flusys/nestjs-core
 
-# Provider-specific SDKs (install only what you use)
-npm install nodemailer                   # SMTP (recommended default)
-npm install @sendgrid/mail               # SendGrid
-npm install mailgun.js form-data         # Mailgun
+# Provider SDKs — install only what you use
+npm install nodemailer           # SMTP (default, always safe to install)
+npm install @sendgrid/mail       # SendGrid
+npm install mailgun.js form-data # Mailgun
 ```
 
----
+## 1. Module Registration
 
-## Quick Start
+### forRoot (sync)
 
-### Minimal Setup (SMTP, Single Database)
+#### Mode 1: Single Database
 
 ```typescript
-import { Module } from '@nestjs/common';
 import { EmailModule } from '@flusys/nestjs-email';
 
 @Module({
@@ -102,9 +38,9 @@ import { EmailModule } from '@flusys/nestjs-email';
       },
       config: {
         defaultDatabaseConfig: {
-          type: 'postgres',
+          type: 'mysql',
           host: process.env.DB_HOST,
-          port: Number(process.env.DB_PORT ?? 5432),
+          port: Number(process.env.DB_PORT ?? 3306),
           username: process.env.DB_USER,
           password: process.env.DB_PASSWORD,
           database: process.env.DB_NAME,
@@ -116,36 +52,40 @@ import { EmailModule } from '@flusys/nestjs-email';
 export class AppModule {}
 ```
 
-After startup, create an email config via the API and then send emails using `EmailSendService`.
-
----
-
-## Module Registration
-
-### forRoot (Sync)
+#### Mode 2: Multi-Tenant
 
 ```typescript
 EmailModule.forRoot({
   global: true,
   includeController: true,
   bootstrapAppConfig: {
-    databaseMode: 'single',          // 'single' | 'multi-tenant'
-    enableCompanyFeature: false,     // true = company-scoped templates & configs
+    databaseMode: 'multi-tenant',
+    enableCompanyFeature: true,
   },
   config: {
-    defaultDatabaseConfig: { /* TypeORM DataSourceOptions */ },
-    defaultProvider: 'smtp',         // Optional: default provider type
-    rateLimitPerMinute: 100,         // Optional: rate limit on send endpoint
-    enableLogging: false,            // Optional: debug logging
+    tenantDefaultDatabaseConfig: {
+      type: 'mysql',
+      host: process.env.TENANT_DB_HOST,
+      port: Number(process.env.TENANT_DB_PORT ?? 3306),
+      username: process.env.TENANT_DB_USER,
+      password: process.env.TENANT_DB_PASSWORD,
+      database: process.env.TENANT_DB_NAME,
+    },
+    tenants: [
+      { id: 'tenant-a', database: 'tenant_a_db' },
+      { id: 'tenant-b', database: 'tenant_b_db' },
+    ],
   },
-})
+});
 ```
 
-### forRootAsync (Factory)
+### forRootAsync (factory)
 
 ```typescript
-import { ConfigService } from '@nestjs/config';
+import { ConfigModule, ConfigService } from '@nestjs/config';
+import { EmailModule, ITenantDatabaseConfig } from '@flusys/nestjs-email';
 
+// Single database
 EmailModule.forRootAsync({
   global: true,
   includeController: true,
@@ -154,346 +94,115 @@ EmailModule.forRootAsync({
     enableCompanyFeature: true,
   },
   imports: [ConfigModule],
-  useFactory: (configService: ConfigService) => ({
+  useFactory: (config: ConfigService) => ({
     defaultDatabaseConfig: {
-      type: 'postgres',
-      host: configService.get('DB_HOST'),
-      port: configService.get<number>('DB_PORT'),
-      username: configService.get('DB_USER'),
-      password: configService.get('DB_PASSWORD'),
-      database: configService.get('DB_NAME'),
+      type: 'mysql',
+      host: config.get('DB_HOST'),
+      port: config.get<number>('DB_PORT'),
+      username: config.get('DB_USER'),
+      password: config.get('DB_PASSWORD'),
+      database: config.get('DB_NAME'),
     },
   }),
   inject: [ConfigService],
-})
-```
-
-### forRootAsync (Class)
-
-```typescript
-import { EmailOptionsFactory, IEmailModuleConfig } from '@flusys/nestjs-email';
-
-@Injectable()
-export class MyEmailConfigFactory implements EmailOptionsFactory {
-  createEmailOptions(): IEmailModuleConfig {
-    return { defaultDatabaseConfig: { /* ... */ } };
-  }
-  createOptions() { return this.createEmailOptions(); }
-}
+});
 
+// Multi-tenant
 EmailModule.forRootAsync({
-  bootstrapAppConfig: { databaseMode: 'single', enableCompanyFeature: false },
-  useClass: MyEmailConfigFactory,
-})
-```
-
----
-
-## Configuration Reference
-
-```typescript
-interface IEmailModuleConfig extends IDataSourceServiceOptions {
-  /** Optional: default provider type when no config is specified */
-  defaultProvider?: 'smtp' | 'sendgrid' | 'mailgun';
-
-  /** Optional: max emails per minute (default: unlimited) */
-  rateLimitPerMinute?: number;
-
-  /** Optional: enable debug logging for send operations */
-  enableLogging?: boolean;
-}
+  global: true,
+  includeController: true,
+  bootstrapAppConfig: {
+    databaseMode: 'multi-tenant',
+    enableCompanyFeature: true,
+  },
+  imports: [ConfigModule],
+  useFactory: (config: ConfigService) => ({
+    tenantDefaultDatabaseConfig: {
+      type: 'mysql',
+      host: config.get('TENANT_DB_HOST'),
+      port: config.get<number>('TENANT_DB_PORT'),
+      username: config.get('TENANT_DB_USER'),
+      password: config.get('TENANT_DB_PASSWORD'),
+      database: config.get('TENANT_DB_NAME'),
+    },
+    tenants: config.get<ITenantDatabaseConfig[]>('TENANTS'),
+  }),
+  inject: [ConfigService],
+});
 ```
 
----
-
-## Feature Toggles
-
-| Feature | Config Key | Default | Effect |
-|---------|-----------|---------|--------|
-| Company scoping | `enableCompanyFeature: true` | `false` | Uses `EmailConfigWithCompany` and `EmailTemplateWithCompany` entities; filters all queries by `companyId` |
-| Multi-tenant | `databaseMode: 'multi-tenant'` | `'single'` | Creates per-tenant DataSource connections |
-
----
-
-## API Endpoints
-
-All endpoints use **POST**. All require JWT authentication unless noted.
-
-### Email Config — `POST /email/email-config/*`
-
-| Endpoint | Permission | Description |
-|----------|-----------|-------------|
-| `POST /email/email-config/insert` | `email-config.create` | Create a provider configuration |
-| `POST /email/email-config/get-all` | `email-config.read` | List all configs |
-| `POST /email/email-config/get/:id` | `email-config.read` | Get config by ID |
-| `POST /email/email-config/update` | `email-config.update` | Update config |
-| `POST /email/email-config/delete` | `email-config.delete` | Delete config |
-| `POST /email/email-config/test` | `email-config.create` | Send a test email to verify config |
-| `POST /email/email-config/set-default` | `email-config.update` | Set as default provider |
-
-### Email Templates — `POST /email/email-template/*`
-
-| Endpoint | Permission | Description |
-|----------|-----------|-------------|
-| `POST /email/email-template/insert` | `email-template.create` | Create a template |
-| `POST /email/email-template/get-all` | `email-template.read` | List all templates |
-| `POST /email/email-template/get/:id` | `email-template.read` | Get template by ID |
-| `POST /email/email-template/update` | `email-template.update` | Update template |
-| `POST /email/email-template/delete` | `email-template.delete` | Delete template |
-
-### Email Send — `POST /email/send/*`
-
-| Endpoint | Permission | Description |
-|----------|-----------|-------------|
-| `POST /email/send/template` | `email-config.create` | Send using a stored template |
-| `POST /email/send/raw` | `email-config.create` | Send raw HTML email |
-
----
-
-## Entities
-
-### Core Entities (always registered)
-
-| Entity | Table | Description |
-|--------|-------|-------------|
-| `EmailConfig` | `email_config` | Provider configuration (SMTP credentials, SendGrid API key, etc.) |
-| `EmailTemplate` | `email_template` | Email templates with `{{variable}}` placeholders |
-
-### Company Feature Entities (`enableCompanyFeature: true`)
-
-| Entity | Table | Description |
-|--------|-------|-------------|
-| `EmailConfigWithCompany` | `email_config` | Same as EmailConfig + `companyId` and `branchId` columns |
-| `EmailTemplateWithCompany` | `email_template` | Same as EmailTemplate + `companyId` column |
-
-#### Register Entities in TypeORM
+## 2. Register Entities
 
 ```typescript
-import { EmailModule } from '@flusys/nestjs-email';
+import { getEmailEntitiesByConfig } from '@flusys/nestjs-email/entities';
 
 TypeOrmModule.forRoot({
   entities: [
-    ...EmailModule.getEntities({ enableCompanyFeature: true }),
-    // other entities
+    ...getEmailEntitiesByConfig(false), // match enableCompanyFeature in bootstrapAppConfig
   ],
-})
+});
 ```
 
----
+| `enableCompanyFeature` | Entities registered                                  |
+| ---------------------- | ---------------------------------------------------- |
+| `false`                | `EmailConfig`, `EmailTemplate`                       |
+| `true`                 | `EmailConfigWithCompany`, `EmailTemplateWithCompany` |
 
-## Email Providers
+## 3. Send Emails
 
-### SMTP (Default)
+### Via template
 
-Create an `EmailConfig` record with provider `smtp`:
+Create a template first:
 
-```json
-POST /email/email-config/insert
-{
-  "name": "Company SMTP",
-  "provider": "smtp",
-  "config": {
-    "host": "smtp.gmail.com",
-    "port": 587,
-    "secure": false,
-    "user": "noreply@example.com",
-    "password": "app-password"
-  },
-  "fromEmail": "noreply@example.com",
-  "fromName": "My App",
-  "isDefault": true
-}
-```
-
-### SendGrid
-
-Install `@sendgrid/mail` first, then create a config:
-
-```json
-POST /email/email-config/insert
-{
-  "name": "SendGrid Production",
-  "provider": "sendgrid",
-  "config": { "apiKey": "SG.xxxxxxxxxxxx" },
-  "fromEmail": "noreply@example.com",
-  "fromName": "My App",
-  "isDefault": true
-}
-```
-
-### Mailgun
-
-Install `mailgun.js form-data` first, then create a config:
-
-```json
-POST /email/email-config/insert
-{
-  "name": "Mailgun",
-  "provider": "mailgun",
-  "config": {
-    "apiKey": "key-xxxxxxxxxxxx",
-    "domain": "mg.example.com",
-    "region": "us"
-  },
-  "fromEmail": "noreply@example.com",
-  "fromName": "My App",
-  "isDefault": true
-}
-```
-
-### Custom Provider
-
-Implement `IEmailProvider` and register it with `StorageProviderRegistry`:
-
-```typescript
-import { IEmailProvider, EmailProviderRegistry } from '@flusys/nestjs-email';
-
-class MyCustomProvider implements IEmailProvider {
-  async send(options: IEmailSendOptions): Promise<void> {
-    // custom sending logic
-  }
-  async testConnection(): Promise<boolean> {
-    return true;
-  }
-}
-
-// Register before module initialization
-EmailProviderRegistry.register('custom', MyCustomProvider);
-```
-
----
-
-## Template Engine
-
-Templates use `{{variableName}}` syntax. All values are HTML-escaped automatically.
-
-**Create a template:**
 ```json
 POST /email/email-template/insert
 {
-  "name": "Welcome Email",
+  "name": "Welcome",
   "slug": "welcome",
-  "subject": "Welcome to {{appName}}, {{userName}}!",
-  "html": "<h1>Hello {{userName}}</h1><p>Welcome to <strong>{{appName}}</strong>.</p><p><a href=\"{{loginUrl}}\">Login here</a></p>",
-  "variables": ["appName", "userName", "loginUrl"]
+  "subject": "Welcome, {{userName}}!",
+  "htmlContent": "<h1>Hello {{userName}}</h1><p>Welcome to {{appName}}.</p>",
+  "isHtml": true
 }
 ```
 
-**Send using the template:**
-```json
-POST /email/send/template
-{
-  "templateSlug": "welcome",
-  "to": "user@example.com",
-  "variables": {
-    "appName": "My App",
-    "userName": "John Doe",
-    "loginUrl": "https://app.example.com/login"
-  }
-}
-```
-
----
-
-## Exported Services
-
-These services are exported by `EmailModule` and injectable in your application:
-
-| Service | Description |
-|---------|-------------|
-| `EmailSendService` | Send emails via template slug or raw HTML |
-| `EmailTemplateService` | CRUD for email templates |
-| `EmailProviderConfigService` | CRUD for provider configurations |
-| `EmailConfigService` | Exposes runtime config (provider defaults, rate limits) |
-| `EmailDataSourceProvider` | Dynamic TypeORM DataSource resolution per request |
-
-> **Note:** Always use `@Inject(ServiceClass)` explicitly — esbuild bundling loses TypeScript metadata.
-
----
-
-## Sending Emails Programmatically
-
-Inject `EmailSendService` to send emails from other services:
+Then send it from your service:
 
 ```typescript
 import { EmailSendService } from '@flusys/nestjs-email';
 
 @Injectable()
 export class UserService {
-  constructor(
-    @Inject(EmailSendService) private readonly emailSendService: EmailSendService,
-  ) {}
+  constructor(@Inject(EmailSendService) private readonly emailSend: EmailSendService) {}
 
-  async sendWelcomeEmail(user: { email: string; name: string }): Promise<void> {
-    await this.emailSendService.sendTemplateEmail({
-      templateSlug: 'welcome',
+  async sendWelcome(user: { email: string; name: string }): Promise<void> {
+    await this.emailSend.sendTemplateEmail({
+      templateSlug: 'welcome', // or templateId: 'uuid'
       to: user.email,
       variables: { userName: user.name, appName: 'My App' },
     });
   }
-
-  async sendRawEmail(): Promise<void> {
-    await this.emailSendService.sendRawEmail({
-      to: 'recipient@example.com',
-      subject: 'Hello',
-      html: '<p>Hello world</p>',
-      attachments: [
-        {
-          filename: 'report.pdf',
-          content: base64EncodedPdfString,
-          contentType: 'application/pdf',
-        },
-      ],
-    });
-  }
 }
 ```
 
----
-
-## Troubleshooting
-
-**`No default email config found`**
-
-Create at least one `EmailConfig` record and mark it as default:
-```json
-POST /email/email-config/set-default
-{ "id": "your-config-id" }
-```
-
----
-
-**`Template not found`**
-
-Check the `templateSlug` matches exactly (case-sensitive). Use `POST /email/email-template/get-all` to list available templates.
-
----
+All `{{variable}}` values in HTML are HTML-escaped automatically.
 
-**SMTP connection refused**
+### Raw email with attachments
 
-Use the test endpoint first:
-```json
-POST /email/email-config/test
-{ "id": "your-config-id", "to": "test@example.com" }
-```
-
-For Gmail, enable "App Passwords" and use the app password, not your account password.
-
----
-
-**`No metadata for entity`**
-
-Call `EmailModule.getEntities()` with the correct flags when registering `TypeOrmModule`:
 ```typescript
-entities: [...EmailModule.getEntities({ enableCompanyFeature: true })]
+await this.emailSend.sendEmail({
+  to: 'recipient@example.com',
+  subject: 'Your Report',
+  html: '<p>See attached.</p>',
+  attachments: [
+    {
+      filename: 'report.pdf',
+      content: base64String, // base64-encoded file content
+      contentType: 'application/pdf',
+    },
+  ],
+});
 ```
 
----
-
 ## License
 
 MIT © FLUSYS
-
----
-
-> Part of the **FLUSYS** framework — a full-stack monorepo powering Angular 21 + NestJS 11 applications.

package/cjs/config/message-keys.js

@@ -10,12 +10,6 @@ function _export(target, all) {
     });
 }
 _export(exports, {
-    get EMAIL_CONFIG_MESSAGES () {
-        return EMAIL_CONFIG_MESSAGES;
-    },
-    get EMAIL_MODULE_MESSAGES () {
-        return EMAIL_MODULE_MESSAGES;
-    },
     get EMAIL_SEND_MESSAGES () {
         return EMAIL_SEND_MESSAGES;
     },
@@ -23,39 +17,13 @@ _export(exports, {
         return EMAIL_TEMPLATE_MESSAGES;
     }
 });
-const EMAIL_CONFIG_MESSAGES = {
-    CREATE_SUCCESS: 'email.config.create.success',
-    CREATE_MANY_SUCCESS: 'email.config.create.many.success',
-    GET_SUCCESS: 'email.config.get.success',
-    GET_ALL_SUCCESS: 'email.config.get.all.success',
-    UPDATE_SUCCESS: 'email.config.update.success',
-    UPDATE_MANY_SUCCESS: 'email.config.update.many.success',
-    DELETE_SUCCESS: 'email.config.delete.success',
-    RESTORE_SUCCESS: 'email.config.restore.success',
-    NOT_FOUND: 'email.config.not.found',
-    ACTIVE_SUCCESS: 'email.config.active.success',
-    TEST_SUCCESS: 'email.config.test.success',
-    TEST_FAILED: 'email.config.test.failed'
-};
 const EMAIL_TEMPLATE_MESSAGES = {
-    CREATE_SUCCESS: 'email.template.create.success',
-    CREATE_MANY_SUCCESS: 'email.template.create.many.success',
     GET_SUCCESS: 'email.template.get.success',
-    GET_ALL_SUCCESS: 'email.template.get.all.success',
-    UPDATE_SUCCESS: 'email.template.update.success',
-    UPDATE_MANY_SUCCESS: 'email.template.update.many.success',
-    DELETE_SUCCESS: 'email.template.delete.success',
-    RESTORE_SUCCESS: 'email.template.restore.success',
-    NOT_FOUND: 'email.template.not.found',
-    PREVIEW_SUCCESS: 'email.template.preview.success'
+    NOT_FOUND: 'email.template.not.found'
 };
 const EMAIL_SEND_MESSAGES = {
     SUCCESS: 'email.send.success',
     FAILED: 'email.send.failed',
-    QUEUED: 'email.send.queued',
-    TEMPLATE_SUCCESS: 'email.send.template.success',
-    BULK_SUCCESS: 'email.send.bulk.success',
-    TEST_SUCCESS: 'email.send.test.success',
     CONFIG_NOT_FOUND: 'email.send.config.not.found',
     CONFIG_INACTIVE: 'email.send.config.inactive',
     CONFIG_DEFAULT_NOT_FOUND: 'email.send.config.default.not.found',
@@ -63,8 +31,3 @@ const EMAIL_SEND_MESSAGES = {
     TEMPLATE_INACTIVE: 'email.send.template.inactive',
     TEMPLATE_ID_OR_SLUG_REQUIRED: 'email.send.template.id.or.slug.required'
 };
-const EMAIL_MODULE_MESSAGES = {
-    EMAIL_CONFIG: EMAIL_CONFIG_MESSAGES,
-    EMAIL_TEMPLATE: EMAIL_TEMPLATE_MESSAGES,
-    EMAIL_SEND: EMAIL_SEND_MESSAGES
-};

package/cjs/controllers/email-template.controller.js

@@ -9,12 +9,12 @@ Object.defineProperty(exports, "EmailTemplateController", {
     }
 });
 const _classes = require("@flusys/nestjs-shared/classes");
-const _config = require("../config");
 const _decorators = require("@flusys/nestjs-shared/decorators");
 const _guards = require("@flusys/nestjs-shared/guards");
 const _interfaces = require("@flusys/nestjs-shared/interfaces");
 const _common = require("@nestjs/common");
 const _swagger = require("@nestjs/swagger");
+const _config = require("../config");
 const _dtos = require("../dtos");
 const _services = require("../services");
 function _define_property(obj, key, value) {
@@ -45,7 +45,7 @@ function _ts_param(paramIndex, decorator) {
     };
 }
 let EmailTemplateController = class EmailTemplateController extends (0, _classes.createApiController)(_dtos.CreateEmailTemplateDto, _dtos.UpdateEmailTemplateDto, _dtos.EmailTemplateResponseDto, {
-    entityName: 'emailTemplate',
+    entityName: 'email.template',
     security: {
         insert: {
             level: 'permission',
@@ -93,11 +93,17 @@ let EmailTemplateController = class EmailTemplateController extends (0, _classes
 }) {
     async getBySlug(body, user) {
         const data = await this.emailTemplateService.findBySlug(body.slug, user);
+        if (!data) {
+            throw new _common.NotFoundException({
+                message: 'Email template not found',
+                messageKey: _config.EMAIL_TEMPLATE_MESSAGES.NOT_FOUND
+            });
+        }
         return {
             success: true,
             message: 'Template retrieved',
             messageKey: _config.EMAIL_TEMPLATE_MESSAGES.GET_SUCCESS,
-            data: data ?? undefined
+            data
         };
     }
     constructor(emailTemplateService){