@flusys/nestjs-email 1.1.0-beta → 2.0.0

package/README.md

@@ -0,0 +1,589 @@
+# Email Package Guide
+
+> **Package:** `@flusys/nestjs-email`
+> **Type:** Email sending with templates, multiple providers, and multi-tenant support
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Installation](#installation)
+- [Constants](#constants)
+- [Module Setup](#module-setup)
+- [Entities](#entities)
+- [Email Providers](#email-providers)
+- [Email Configuration](#email-configuration)
+- [Email Templates](#email-templates)
+- [Email Sending](#email-sending)
+- [API Endpoints](#api-endpoints)
+- [Multi-Tenant Support](#multi-tenant-support)
+- [Best Practices](#best-practices)
+
+---
+
+## Overview
+
+`@flusys/nestjs-email` provides:
+
+- **Multiple Providers** - SMTP, SendGrid, Mailgun with dynamic registration
+- **Email Templates** - Variable interpolation with `{{variableName}}` syntax
+- **HTML/Plain Text** - Support via `isHtml` toggle
+- **Multi-Tenant Support** - Company-scoped configurations and templates
+- **Attachments** - File attachment support
+
+### Package Hierarchy
+
+```
+@flusys/nestjs-core     ← Foundation
+     ↓
+@flusys/nestjs-shared   ← Shared utilities
+     ↓
+@flusys/nestjs-email    ← Email system (THIS PACKAGE)
+```
+
+---
+
+## Installation
+
+```bash
+npm install @flusys/nestjs-email
+
+# Provider-specific packages (install as needed)
+npm install nodemailer                  # For SMTP
+npm install @sendgrid/mail              # For SendGrid
+npm install mailgun.js form-data        # For Mailgun
+```
+
+---
+
+## Constants
+
+```typescript
+// Injection Token
+export const EMAIL_MODULE_OPTIONS = 'EMAIL_MODULE_OPTIONS';
+
+// Default Configuration
+export const DEFAULT_FROM_NAME = 'FLUSYS';
+```
+
+---
+
+## Module Setup
+
+### Basic Setup
+
+```typescript
+import { EmailModule } from '@flusys/nestjs-email';
+
+@Module({
+  imports: [
+    EmailModule.forRoot({
+      global: true,
+      includeController: true,
+      bootstrapAppConfig: {
+        databaseMode: 'single',
+        enableCompanyFeature: false,
+      },
+      config: {
+        defaultDatabaseConfig: {
+          type: 'postgres',
+          host: 'localhost',
+          port: 5432,
+          username: 'user',
+          password: 'password',
+          database: 'myapp',
+        },
+      },
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### With Company Feature
+
+```typescript
+EmailModule.forRoot({
+  global: true,
+  includeController: true,
+  bootstrapAppConfig: {
+    databaseMode: 'single',
+    enableCompanyFeature: true,
+  },
+  config: {
+    defaultDatabaseConfig: { ... },
+  },
+});
+```
+
+### Async Configuration
+
+```typescript
+EmailModule.forRootAsync({
+  global: true,
+  includeController: true,
+  bootstrapAppConfig: {
+    databaseMode: 'single',
+    enableCompanyFeature: true,
+  },
+  imports: [ConfigModule],
+  useFactory: async (configService: ConfigService) => ({
+    defaultDatabaseConfig: configService.getDatabaseConfig(),
+  }),
+  inject: [ConfigService],
+});
+```
+
+---
+
+## Entities
+
+### Entity Groups
+
+```typescript
+// Core entities (no company feature)
+export const EmailCoreEntities = [EmailConfig, EmailTemplate];
+
+// Company-specific entities
+export const EmailCompanyEntities = [EmailConfigWithCompany, EmailTemplateWithCompany];
+
+// Helper function
+export function getEmailEntitiesByConfig(enableCompanyFeature: boolean): any[] {
+  return enableCompanyFeature ? EmailCompanyEntities : EmailCoreEntities;
+}
+
+// Base type aliases for backwards compatibility
+export { EmailConfig as EmailConfigBase } from './email-config.entity';
+export { EmailTemplate as EmailTemplateBase } from './email-template.entity';
+```
+
+---
+
+## Email Providers
+
+### Provider Types
+
+```typescript
+enum EmailProviderTypeEnum {
+  SMTP = 'smtp',
+  SENDGRID = 'sendgrid',
+  MAILGUN = 'mailgun',
+}
+```
+
+Providers are auto-registered at module load via `EmailProviderRegistry`.
+
+### SMTP Configuration
+
+```typescript
+{
+  provider: 'smtp',
+  config: {
+    host: 'smtp.gmail.com',
+    port: 587,
+    secure: false,
+    auth: { user: 'your@gmail.com', pass: 'app-password' },
+  }
+}
+```
+
+### SendGrid Configuration
+
+```typescript
+// Requires: npm install @sendgrid/mail
+{
+  provider: 'sendgrid',
+  config: { apiKey: 'SG.xxxxxxxxxxxx' }
+}
+```
+
+### Mailgun Configuration
+
+```typescript
+// Requires: npm install mailgun.js form-data
+{
+  provider: 'mailgun',
+  config: {
+    apiKey: 'key-xxxxxxxx',
+    domain: 'mail.yourdomain.com',
+    region: 'us',  // 'us' or 'eu'
+  }
+}
+```
+
+### Provider Interface
+
+```typescript
+interface IEmailProvider {
+  sendEmail(options: IEmailSendOptions): Promise<IEmailSendResult>;
+  sendBulkEmails(options: IEmailSendOptions[]): Promise<IEmailSendResult[]>;
+  healthCheck(): Promise<boolean>;
+  initialize?(config: any): Promise<void>;
+  close?(): Promise<void>;
+}
+
+interface IEmailSendOptions {
+  to: string | string[];
+  cc?: string | string[];
+  bcc?: string | string[];
+  subject: string;
+  html?: string;
+  text?: string;
+  from?: string;
+  fromName?: string;
+  replyTo?: string;
+  attachments?: IEmailAttachment[];
+}
+
+interface IEmailSendResult {
+  success: boolean;
+  messageId?: string;
+  error?: string;
+}
+```
+
+---
+
+## Email Configuration
+
+### EmailConfig Entity
+
+```typescript
+interface IEmailConfig {
+  id: string;
+  name: string;                // e.g., 'default', 'marketing'
+  provider: EmailProviderTypeEnum;
+  config: Record<string, any>; // Provider-specific config
+  fromEmail: string | null;
+  fromName: string | null;
+  isActive: boolean;
+  isDefault: boolean;          // Auto-selected when emailConfigId not provided
+  companyId?: string | null;   // When company feature enabled
+}
+```
+
+### Default Configuration Resolution
+
+When `emailConfigId` is not provided:
+1. Find config with `isDefault: true` and `isActive: true`
+2. Fall back to oldest active config
+
+### Creating Configurations
+
+```typescript
+import { EmailProviderConfigService } from '@flusys/nestjs-email';
+
+await emailConfigService.insert({
+  name: 'default',
+  provider: 'smtp',
+  fromEmail: 'noreply@example.com',
+  fromName: 'My App',
+  config: {
+    host: 'smtp.gmail.com',
+    port: 587,
+    auth: { user: '...', pass: '...' },
+  },
+  isActive: true,
+  isDefault: true,
+}, user);
+```
+
+---
+
+## Email Templates
+
+### EmailTemplate Entity
+
+```typescript
+interface IEmailTemplate {
+  id: string;
+  name: string;
+  slug: string;              // URL-friendly identifier
+  description: string | null;
+  subject: string;           // Supports {{variables}}
+  schema: Record<string, unknown>;
+  htmlContent: string;
+  textContent: string | null;
+  schemaVersion: number;     // Auto-incremented on schema change
+  isActive: boolean;
+  isHtml: boolean;           // true=HTML, false=plain text
+  metadata: Record<string, unknown> | null;
+  companyId?: string | null;
+}
+```
+
+### Creating Templates
+
+```typescript
+import { EmailTemplateService } from '@flusys/nestjs-email';
+
+await templateService.insert({
+  name: 'Welcome Email',
+  slug: 'welcome-email',
+  subject: 'Welcome to {{appName}}, {{userName}}!',
+  isHtml: true,
+  htmlContent: `
+    <h1>Welcome, {{userName}}!</h1>
+    <p>Thank you for joining {{appName}}.</p>
+    <a href="{{verificationLink}}">Verify Email</a>
+  `,
+  textContent: 'Welcome! Verify: {{verificationLink}}',
+  schema: {},
+  isActive: true,
+}, user);
+```
+
+### Variable Interpolation
+
+```typescript
+// Template: "Hello {{userName}}, your order #{{orderId}} is {{status}}."
+// Variables: { userName: "John", orderId: "12345", status: "shipped" }
+// Result: "Hello John, your order #12345 is shipped."
+```
+
+### isHtml Toggle
+
+- **`isHtml: true`** - Sends `htmlContent` as HTML, `textContent` as fallback
+- **`isHtml: false`** - Sends `textContent` only (no HTML)
+
+---
+
+## Email Sending
+
+### EmailSendService
+
+```typescript
+import { EmailSendService } from '@flusys/nestjs-email';
+
+// Send direct email
+const result = await emailSendService.sendEmail({
+  to: 'user@example.com',
+  subject: 'Hello!',
+  html: '<h1>Hello World</h1>',
+  text: 'Hello World',
+  emailConfigId: 'config-uuid', // Optional - uses default
+}, user);
+
+// Send using template
+const result = await emailSendService.sendTemplateEmail({
+  templateSlug: 'welcome-email',
+  to: 'user@example.com',
+  variables: {
+    userName: 'John',
+    appName: 'My App',
+  },
+}, user);
+
+// Send with attachments
+const result = await emailSendService.sendEmail({
+  to: 'user@example.com',
+  subject: 'Your Invoice',
+  html: '<p>Invoice attached.</p>',
+  attachments: [{
+    filename: 'invoice.pdf',
+    content: base64Content,
+    contentType: 'application/pdf',
+  }],
+}, user);
+```
+
+---
+
+## API Endpoints
+
+All endpoints use POST (RPC pattern) and require JWT authentication.
+
+### Email Configuration
+
+| Endpoint | Description |
+|----------|-------------|
+| `POST /email/email-config/insert` | Create configuration |
+| `POST /email/email-config/get/:id` | Get by ID |
+| `POST /email/email-config/get-all` | Get all (paginated) |
+| `POST /email/email-config/update` | Update |
+| `POST /email/email-config/delete` | Delete |
+
+### Email Templates
+
+| Endpoint | Description |
+|----------|-------------|
+| `POST /email/email-template/insert` | Create template |
+| `POST /email/email-template/get/:id` | Get by ID |
+| `POST /email/email-template/get-all` | Get all (paginated) |
+| `POST /email/email-template/get-by-slug` | Get by slug |
+| `POST /email/email-template/update` | Update |
+| `POST /email/email-template/delete` | Delete |
+
+### Email Sending
+
+| Endpoint | Description |
+|----------|-------------|
+| `POST /email/send/direct` | Send direct email |
+| `POST /email/send/template` | Send using template |
+| `POST /email/send/test` | Test configuration |
+
+### Example Requests
+
+```bash
+# Send template email
+curl -X POST http://localhost:3000/email/send/template \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "templateSlug": "welcome-email",
+    "to": "user@example.com",
+    "variables": { "userName": "John" }
+  }'
+
+# Test configuration
+curl -X POST http://localhost:3000/email/send/test \
+  -H "Authorization: Bearer <token>" \
+  -d '{ "emailConfigId": "uuid", "recipient": "test@example.com" }'
+```
+
+---
+
+## Multi-Tenant Support
+
+### Company Isolation
+
+When `enableCompanyFeature: true`:
+- Email configs are company-scoped
+- Templates are company-scoped
+- Users can only access their company's resources
+
+### Company Filtering
+
+Services automatically filter by `companyId`:
+
+```typescript
+// In EmailTemplateService
+if (this.emailConfig.isCompanyFeatureEnabled() && user?.companyId) {
+  query.andWhere('emailTemplate.companyId = :companyId', {
+    companyId: user.companyId,
+  });
+}
+```
+
+### Dynamic Entity Selection
+
+```typescript
+protected resolveEntity(): EntityTarget<EmailTemplateBase> {
+  return this.emailConfig.isCompanyFeatureEnabled()
+    ? EmailTemplateWithCompany
+    : EmailTemplate;
+}
+```
+
+---
+
+## Best Practices
+
+### 1. Use Template Slugs
+
+```typescript
+// Use slug for stable references
+await emailSendService.sendTemplateEmail({
+  templateSlug: 'welcome-email',  // Stable
+  ...
+});
+
+// Avoid hardcoded IDs
+templateId: 'f47ac10b-58cc-4372-a567-...'  // May change
+```
+
+### 2. Provide Both HTML and Text
+
+```typescript
+await templateService.insert({
+  isHtml: true,
+  htmlContent: '<h1>Thank you!</h1>',
+  textContent: 'Thank you!',  // For clients that don't render HTML
+});
+```
+
+### 3. Test Before Production
+
+```typescript
+const result = await emailSendService.sendTestEmail(
+  configId,
+  'admin@example.com',
+  user,
+);
+if (!result.success) throw new Error(result.error);
+```
+
+### 4. Use Variables for Personalization
+
+```typescript
+// Template
+subject: 'Hello {{userName}}!'
+
+// Sending
+variables: { userName: 'John' }
+```
+
+---
+
+## API Reference
+
+### Main Exports
+
+```typescript
+// Module
+import { EmailModule } from '@flusys/nestjs-email';
+
+// Services
+import {
+  EmailProviderConfigService,
+  EmailTemplateService,
+  EmailSendService,
+  EmailDataSourceProvider,
+} from '@flusys/nestjs-email/services';
+
+// Entities
+import {
+  EmailConfig,
+  EmailConfigBase,
+  EmailConfigWithCompany,
+  EmailTemplate,
+  EmailTemplateBase,
+  EmailTemplateWithCompany,
+} from '@flusys/nestjs-email/entities';
+
+// DTOs
+import {
+  CreateEmailConfigDto,
+  UpdateEmailConfigDto,
+  EmailConfigResponseDto,
+  CreateEmailTemplateDto,
+  UpdateEmailTemplateDto,
+  EmailTemplateResponseDto,
+  SendEmailDto,
+  SendTemplateEmailDto,
+  TestEmailDto,
+  EmailSendResultDto,
+} from '@flusys/nestjs-email/dtos';
+
+// Interfaces
+import {
+  IEmailProvider,
+  IEmailSendOptions,
+  IEmailSendResult,
+  IEmailConfig,
+  IEmailTemplate,
+  EmailModuleOptions,
+} from '@flusys/nestjs-email/interfaces';
+
+// Providers
+import {
+  EmailProviderRegistry,
+  EmailFactoryService,
+  SmtpProvider,
+  SendGridProvider,
+  MailgunProvider,
+} from '@flusys/nestjs-email/providers';
+```
+
+---
+
+**Last Updated:** 2026-02-21

package/cjs/config/email.constants.js

@@ -14,27 +14,9 @@ _export(exports, {
     get DEFAULT_FROM_NAME () {
         return DEFAULT_FROM_NAME;
     },
-    get EMAIL_CONFIG_SERVICE () {
-        return EMAIL_CONFIG_SERVICE;
-    },
-    get EMAIL_DATA_SOURCE_PROVIDER () {
-        return EMAIL_DATA_SOURCE_PROVIDER;
-    },
     get EMAIL_MODULE_OPTIONS () {
         return EMAIL_MODULE_OPTIONS;
-    },
-    get EMAIL_VALIDATION_MESSAGES () {
-        return EMAIL_VALIDATION_MESSAGES;
     }
 });
 const EMAIL_MODULE_OPTIONS = 'EMAIL_MODULE_OPTIONS';
-const EMAIL_CONFIG_SERVICE = 'EMAIL_CONFIG_SERVICE';
-const EMAIL_DATA_SOURCE_PROVIDER = 'EMAIL_DATA_SOURCE_PROVIDER';
 const DEFAULT_FROM_NAME = 'FLUSYS';
-const EMAIL_VALIDATION_MESSAGES = {
-    INVALID_RECIPIENT: 'Invalid email recipient',
-    TEMPLATE_NOT_FOUND: 'Email template not found',
-    CONFIG_NOT_FOUND: 'Email configuration not found',
-    PROVIDER_NOT_AVAILABLE: 'Email provider not available',
-    SEND_FAILED: 'Failed to send email'
-};

package/cjs/config/index.js

@@ -3,7 +3,6 @@ Object.defineProperty(exports, "__esModule", {
     value: true
 });
 _export_star(require("./email.constants"), exports);
-_export_star(require("./email-config.service"), exports);
 function _export_star(from, to) {
     Object.keys(from).forEach(function(k) {
         if (k !== "default" && !Object.prototype.hasOwnProperty.call(to, k)) {

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

@@ -8,7 +8,6 @@ Object.defineProperty(exports, "EmailConfigController", {
         return EmailConfigController;
     }
 });
-const _guards = require("@flusys/nestjs-shared/guards");
 const _classes = require("@flusys/nestjs-shared/classes");
 const _common = require("@nestjs/common");
 const _swagger = require("@nestjs/swagger");
@@ -41,16 +40,59 @@ function _ts_param(paramIndex, decorator) {
         decorator(target, key, paramIndex);
     };
 }
-let EmailConfigController = class EmailConfigController extends (0, _classes.createApiController)(_dtos.CreateEmailConfigDto, _dtos.UpdateEmailConfigDto, _dtos.EmailConfigResponseDto) {
+let EmailConfigController = class EmailConfigController extends (0, _classes.createApiController)(_dtos.CreateEmailConfigDto, _dtos.UpdateEmailConfigDto, _dtos.EmailConfigResponseDto, {
+    security: {
+        insert: {
+            level: 'permission',
+            permissions: [
+                _classes.EMAIL_CONFIG_PERMISSIONS.CREATE
+            ]
+        },
+        insertMany: {
+            level: 'permission',
+            permissions: [
+                _classes.EMAIL_CONFIG_PERMISSIONS.CREATE
+            ]
+        },
+        getById: {
+            level: 'permission',
+            permissions: [
+                _classes.EMAIL_CONFIG_PERMISSIONS.READ
+            ]
+        },
+        getAll: {
+            level: 'permission',
+            permissions: [
+                _classes.EMAIL_CONFIG_PERMISSIONS.READ
+            ]
+        },
+        update: {
+            level: 'permission',
+            permissions: [
+                _classes.EMAIL_CONFIG_PERMISSIONS.UPDATE
+            ]
+        },
+        updateMany: {
+            level: 'permission',
+            permissions: [
+                _classes.EMAIL_CONFIG_PERMISSIONS.UPDATE
+            ]
+        },
+        delete: {
+            level: 'permission',
+            permissions: [
+                _classes.EMAIL_CONFIG_PERMISSIONS.DELETE
+            ]
+        }
+    }
+}) {
     constructor(emailConfigService){
         super(emailConfigService), _define_property(this, "emailConfigService", void 0), this.emailConfigService = emailConfigService;
     }
 };
 EmailConfigController = _ts_decorate([
     (0, _swagger.ApiTags)('Email Config'),
-    (0, _swagger.ApiBearerAuth)(),
     (0, _common.Controller)('email/email-config'),
-    (0, _common.UseGuards)(_guards.JwtAuthGuard),
     _ts_param(0, (0, _common.Inject)(_services.EmailProviderConfigService)),
     _ts_metadata("design:type", Function),
     _ts_metadata("design:paramtypes", [