@flusys/nestjs-email 2.0.0 → 3.0.0

package/README.md

@@ -1,6 +1,7 @@
 # Email Package Guide
 
 > **Package:** `@flusys/nestjs-email`
+> **Version:** 3.0.0
 > **Type:** Email sending with templates, multiple providers, and multi-tenant support
 
 ## Table of Contents
@@ -10,11 +11,15 @@
 - [Constants](#constants)
 - [Module Setup](#module-setup)
 - [Entities](#entities)
+- [Interfaces](#interfaces)
 - [Email Providers](#email-providers)
 - [Email Configuration](#email-configuration)
 - [Email Templates](#email-templates)
 - [Email Sending](#email-sending)
+- [DTOs](#dtos)
+- [Utility Functions](#utility-functions)
 - [API Endpoints](#api-endpoints)
+- [Swagger Documentation](#swagger-documentation)
 - [Multi-Tenant Support](#multi-tenant-support)
 - [Best Practices](#best-practices)
 
@@ -69,6 +74,21 @@ export const DEFAULT_FROM_NAME = 'FLUSYS';
 
 ## Module Setup
 
+### Module Options Interface
+
+```typescript
+interface IEmailModuleConfig extends IDataSourceServiceOptions {
+  defaultProvider?: string;       // Default provider type
+  rateLimitPerMinute?: number;    // Rate limiting
+  enableLogging?: boolean;        // Enable debug logging
+}
+
+interface EmailModuleOptions extends IDynamicModuleConfig {
+  bootstrapAppConfig?: IBootstrapAppConfig;
+  config?: IEmailModuleConfig;
+}
+```
+
 ### Basic Setup
 
 ```typescript
@@ -158,6 +178,97 @@ export { EmailTemplate as EmailTemplateBase } from './email-template.entity';
 
 ---
 
+## Interfaces
+
+### Provider Configuration Interfaces
+
+```typescript
+interface ISmtpTlsConfig {
+  rejectUnauthorized?: boolean;          // Reject unauthorized certs (default: true)
+  minVersion?: 'TLSv1.2' | 'TLSv1.3';    // Min TLS version (default: 'TLSv1.2')
+}
+
+interface ISmtpConfig {
+  host: string;
+  port: number;
+  secure?: boolean;
+  auth?: { user: string; pass: string };
+  tls?: ISmtpTlsConfig;                  // TLS configuration
+}
+
+interface ISendGridConfig {
+  apiKey: string;
+}
+
+interface IMailgunConfig {
+  apiKey: string;
+  domain: string;
+  region?: 'us' | 'eu';
+}
+```
+
+### Email Template Schema Interfaces
+
+```typescript
+interface IEmailTemplateVariable {
+  name: string;
+  type: 'string' | 'number' | 'boolean' | 'date';
+  required?: boolean;
+  defaultValue?: string;
+  description?: string;
+}
+
+interface IEmailSection {
+  id: string;
+  type: 'header' | 'body' | 'footer';
+  name: string;
+  blocks: IEmailBlock[];
+  order: number;
+  style?: IEmailSectionStyle;
+}
+
+interface IEmailSectionStyle {
+  backgroundColor?: string;
+  padding?: string;
+  maxWidth?: string;
+}
+
+interface IEmailBlock {
+  id: string;
+  type: 'text' | 'image' | 'button' | 'divider' | 'html';
+  order: number;
+  content: Record<string, any>;
+  style?: IEmailBlockStyle;
+}
+
+interface IEmailBlockStyle {
+  textAlign?: 'left' | 'center' | 'right';
+  padding?: string;
+  margin?: string;
+  backgroundColor?: string;
+}
+
+interface IEmailSettings {
+  maxWidth?: string;
+  backgroundColor?: string;
+  fontFamily?: string;
+  baseTextColor?: string;
+}
+
+interface IEmailSchema {
+  id: string;
+  version: string;
+  name: string;
+  subject: string;
+  preheader?: string;
+  sections: IEmailSection[];
+  variables?: IEmailTemplateVariable[];
+  settings?: IEmailSettings;
+}
+```
+
+---
+
 ## Email Providers
 
 ### Provider Types
@@ -180,8 +291,12 @@ Providers are auto-registered at module load via `EmailProviderRegistry`.
   config: {
     host: 'smtp.gmail.com',
     port: 587,
-    secure: false,
+    secure: false,                         // true for port 465
     auth: { user: 'your@gmail.com', pass: 'app-password' },
+    tls: {
+      rejectUnauthorized: true,            // Certificate validation (default: true)
+      minVersion: 'TLSv1.2',               // Minimum TLS version
+    },
   }
 }
 ```
@@ -234,6 +349,13 @@ interface IEmailSendOptions {
   attachments?: IEmailAttachment[];
 }
 
+interface IEmailAttachment {
+  filename: string;
+  content: Buffer | string;
+  contentType?: string;
+  encoding?: string;
+}
+
 interface IEmailSendResult {
   success: boolean;
   messageId?: string;
@@ -241,6 +363,54 @@ interface IEmailSendResult {
 }
 ```
 
+### EmailProviderRegistry
+
+Providers are auto-registered at module load:
+
+```typescript
+// Built-in registration (happens automatically)
+EmailProviderRegistry.register(EmailProviderTypeEnum.SMTP, SmtpProvider);
+EmailProviderRegistry.register(EmailProviderTypeEnum.SENDGRID, SendGridProvider);
+EmailProviderRegistry.register(EmailProviderTypeEnum.MAILGUN, MailgunProvider);
+
+// Registry methods
+EmailProviderRegistry.register(name, ProviderClass);  // Register provider
+EmailProviderRegistry.get(name);                       // Get provider class
+EmailProviderRegistry.has(name);                       // Check if registered
+EmailProviderRegistry.getAll();                        // List all providers
+EmailProviderRegistry.clear();                         // Clear registry
+```
+
+### Custom Provider Example
+
+```typescript
+class MyCustomProvider implements IEmailProvider {
+  async initialize(config: any): Promise<void> {
+    // Initialize connection
+  }
+
+  async sendEmail(options: IEmailSendOptions): Promise<IEmailSendResult> {
+    // Send email
+    return { success: true, messageId: 'xxx' };
+  }
+
+  async sendBulkEmails(options: IEmailSendOptions[]): Promise<IEmailSendResult[]> {
+    return Promise.all(options.map(opt => this.sendEmail(opt)));
+  }
+
+  async healthCheck(): Promise<boolean> {
+    return true;
+  }
+
+  async close(): Promise<void> {
+    // Cleanup connections
+  }
+}
+
+// Register custom provider
+EmailProviderRegistry.register('custom', MyCustomProvider);
+```
+
 ---
 
 ## Email Configuration
@@ -388,6 +558,103 @@ const result = await emailSendService.sendEmail({
 
 ---
 
+## DTOs
+
+### Email Send DTOs
+
+```typescript
+// Base class for common email fields
+class BaseEmailDto {
+  to: string | string[];           // Recipient(s)
+  cc?: string | string[];          // CC recipients
+  bcc?: string | string[];         // BCC recipients
+  from?: string;                   // Sender email
+  fromName?: string;               // Sender name
+  replyTo?: string;                // Reply-to address
+  emailConfigId?: string;          // Email config to use
+  attachments?: EmailAttachmentDto[];
+}
+
+class SendEmailDto extends BaseEmailDto {
+  subject: string;
+  html: string;
+  text?: string;
+}
+
+class SendTemplateEmailDto extends BaseEmailDto {
+  templateId?: string;             // Template ID (or slug required)
+  templateSlug?: string;           // Template slug (or ID required)
+  variables?: Record<string, any>; // Template variables
+}
+
+class TestEmailDto {
+  emailConfigId: string;
+  recipient: string;
+}
+
+class EmailAttachmentDto {
+  filename: string;
+  content: string;                 // Base64 encoded
+  contentType?: string;
+}
+
+class EmailSendResultDto {
+  success: boolean;
+  messageId?: string;
+  error?: string;
+}
+```
+
+### Custom Validators
+
+The DTOs use custom validators for email fields:
+
+```typescript
+// Validates single email or array of emails
+@IsEmailOrEmailArray()
+to: string | string[];
+
+// Requires either templateId or templateSlug
+@RequireTemplateIdOrSlug()
+templateId?: string;
+```
+
+---
+
+## Utility Functions
+
+Built-in email template utilities for common use cases:
+
+```typescript
+import { getOtpEmailFormat, getResetPasswordEmailFormat } from '@flusys/nestjs-email/utils';
+
+// Generate OTP email HTML
+const otpHtml = getOtpEmailFormat(123456, 'John Doe');
+
+// Generate password reset email HTML
+const resetHtml = getResetPasswordEmailFormat('https://example.com/reset?token=xyz', 'John Doe');
+```
+
+### getOtpEmailFormat(otp, userName?)
+
+Generates styled HTML for OTP verification emails.
+
+```typescript
+const html = getOtpEmailFormat(123456, 'John');
+// Returns formatted HTML with OTP code prominently displayed
+```
+
+### getResetPasswordEmailFormat(resetLink, userName?)
+
+Generates styled HTML for password reset emails.
+
+```typescript
+const html = getResetPasswordEmailFormat('https://app.example.com/reset?token=abc123', 'John');
+// Returns formatted HTML with reset button
+```
+
+---
+
 ## API Endpoints
 
 All endpoints use POST (RPC pattern) and require JWT authentication.
@@ -440,6 +707,61 @@ curl -X POST http://localhost:3000/email/send/test \
   -d '{ "emailConfigId": "uuid", "recipient": "test@example.com" }'
 ```
 
+### Controller Permissions
+
+Controllers use permission-based security via `createApiController`:
+
+```typescript
+// Email Config permissions
+EMAIL_CONFIG_PERMISSIONS.CREATE  // 'email-config.create'
+EMAIL_CONFIG_PERMISSIONS.READ    // 'email-config.read'
+EMAIL_CONFIG_PERMISSIONS.UPDATE  // 'email-config.update'
+EMAIL_CONFIG_PERMISSIONS.DELETE  // 'email-config.delete'
+
+// Email Template permissions
+EMAIL_TEMPLATE_PERMISSIONS.CREATE  // 'email-template.create'
+EMAIL_TEMPLATE_PERMISSIONS.READ    // 'email-template.read'
+EMAIL_TEMPLATE_PERMISSIONS.UPDATE  // 'email-template.update'
+EMAIL_TEMPLATE_PERMISSIONS.DELETE  // 'email-template.delete'
+
+// Email Send permission
+'email.send'
+```
+
+---
+
+## Swagger Documentation
+
+### Setup Swagger for Email Module
+
+```typescript
+import { emailSwaggerConfig } from '@flusys/nestjs-email';
+import { setupSwaggerDocs } from '@flusys/nestjs-core/docs';
+
+// In your bootstrap function
+setupSwaggerDocs(app, emailSwaggerConfig(bootstrapAppConfig));
+```
+
+### Swagger Config Options
+
+```typescript
+function emailSwaggerConfig(bootstrapConfig?: IBootstrapAppConfig): IModuleSwaggerOptions {
+  return {
+    title: 'Email API',
+    description: '...',            // Auto-generated based on features
+    version: '1.0',
+    path: 'api/docs/email',        // Swagger UI path
+    bearerAuth: true,
+    excludeTags: [],
+    excludeSchemaProperties: [...], // Excludes companyId when company feature disabled
+  };
+}
+```
+
+The Swagger documentation automatically adapts based on `enableCompanyFeature`:
+- When enabled: Shows company isolation and multi-tenant features
+- When disabled: Hides companyId fields from schemas
+
 ---
 
 ## Multi-Tenant Support
@@ -534,7 +856,8 @@ import { EmailModule } from '@flusys/nestjs-email';
 
 // Services
 import {
-  EmailProviderConfigService,
+  EmailConfigService,           // Module configuration service
+  EmailProviderConfigService,   // CRUD for email provider configs
   EmailTemplateService,
   EmailSendService,
   EmailDataSourceProvider,
@@ -548,6 +871,9 @@ import {
   EmailTemplate,
   EmailTemplateBase,
   EmailTemplateWithCompany,
+  EmailCoreEntities,
+  EmailCompanyEntities,
+  getEmailEntitiesByConfig,
 } from '@flusys/nestjs-email/entities';
 
 // DTOs
@@ -558,6 +884,7 @@ import {
   CreateEmailTemplateDto,
   UpdateEmailTemplateDto,
   EmailTemplateResponseDto,
+  EmailAttachmentDto,
   SendEmailDto,
   SendTemplateEmailDto,
   TestEmailDto,
@@ -569,9 +896,25 @@ import {
   IEmailProvider,
   IEmailSendOptions,
   IEmailSendResult,
+  IEmailAttachment,
+  IEmailProviderConfig,
   IEmailConfig,
   IEmailTemplate,
+  IEmailTemplateVariable,
+  IEmailSection,
+  IEmailSectionStyle,
+  IEmailBlock,
+  IEmailBlockStyle,
+  IEmailSettings,
+  IEmailSchema,
+  ISmtpConfig,
+  ISmtpTlsConfig,
+  ISendGridConfig,
+  IMailgunConfig,
+  IEmailModuleConfig,
   EmailModuleOptions,
+  EmailModuleAsyncOptions,
+  EmailOptionsFactory,
 } from '@flusys/nestjs-email/interfaces';
 
 // Providers
@@ -582,8 +925,103 @@ import {
   SendGridProvider,
   MailgunProvider,
 } from '@flusys/nestjs-email/providers';
+
+// Controllers
+import {
+  EmailConfigController,
+  EmailTemplateController,
+  EmailSendController,
+} from '@flusys/nestjs-email/controllers';
+
+// Enums
+import { EmailProviderTypeEnum } from '@flusys/nestjs-email/enums';
+
+// Constants
+import {
+  EMAIL_MODULE_OPTIONS,
+  DEFAULT_FROM_NAME,
+} from '@flusys/nestjs-email/config';
+
+// Utilities
+import {
+  getOtpEmailFormat,
+  getResetPasswordEmailFormat,
+} from '@flusys/nestjs-email/utils';
+
+// Swagger Config
+import { emailSwaggerConfig } from '@flusys/nestjs-email/docs';
+```
+
+### Service Methods Reference
+
+#### EmailConfigService
+
+```typescript
+class EmailConfigService {
+  isCompanyFeatureEnabled(): boolean;
+  getDatabaseMode(): DatabaseMode;
+  isMultiTenant(): boolean;
+  getDefaultFromName(): string;
+  getOptions(): EmailModuleOptions;
+}
+```
+
+#### EmailProviderConfigService
+
+```typescript
+class EmailProviderConfigService {
+  // Standard CRUD (inherited from RequestScopedApiService)
+  insert(dto, user): Promise<EmailConfigBase>;
+  getById(id, user): Promise<EmailConfigBase | null>;
+  getAll(filterDto, user): Promise<{ list: EmailConfigBase[]; total: number }>;
+  update(dto, user): Promise<EmailConfigBase>;
+  delete(id, user): Promise<boolean>;
+
+  // Custom methods
+  findByIdDirect(id): Promise<EmailConfigBase | null>;
+  getDefaultConfig(user?): Promise<EmailConfigBase | null>;
+  getConfigByProvider(provider, user?): Promise<EmailConfigBase[]>;
+}
+```
+
+#### EmailTemplateService
+
+```typescript
+class EmailTemplateService {
+  // Standard CRUD (inherited from RequestScopedApiService)
+  insert(dto, user): Promise<EmailTemplateBase>;
+  getById(id, user): Promise<EmailTemplateBase | null>;
+  getAll(filterDto, user): Promise<{ list: EmailTemplateBase[]; total: number }>;
+  update(dto, user): Promise<EmailTemplateBase>;
+  delete(id, user): Promise<boolean>;
+
+  // Custom methods
+  findByIdDirect(id): Promise<EmailTemplateBase | null>;
+  findBySlug(slug, user?): Promise<EmailTemplateBase | null>;
+  getActiveTemplates(user?): Promise<EmailTemplateBase[]>;
+}
+```
+
+#### EmailSendService
+
+```typescript
+class EmailSendService {
+  sendEmail(dto: SendEmailDto, user?): Promise<IEmailSendResult>;
+  sendTemplateEmail(dto: SendTemplateEmailDto, user?): Promise<IEmailSendResult>;
+  sendTestEmail(emailConfigId, recipient, user?): Promise<IEmailSendResult>;
+}
+```
+
+#### EmailFactoryService
+
+```typescript
+class EmailFactoryService {
+  createProvider(config: IEmailProviderConfig): Promise<IEmailProvider>;
+  // Providers are cached by config hash for reuse
+  // Connections cleaned up on module destroy
+}
 ```
 
 ---
 
-**Last Updated:** 2026-02-21
+**Last Updated:** 2026-02-25

package/cjs/entities/email-config.entity.js

@@ -10,7 +10,6 @@ Object.defineProperty(exports, "EmailConfig", {
 });
 const _entities = require("@flusys/nestjs-shared/entities");
 const _typeorm = require("typeorm");
-const _enums = require("../enums");
 function _define_property(obj, key, value) {
     if (key in obj) {
         Object.defineProperty(obj, key, {
@@ -48,11 +47,11 @@ _ts_decorate([
 ], EmailConfig.prototype, "name", void 0);
 _ts_decorate([
     (0, _typeorm.Column)({
-        type: 'enum',
-        enum: _enums.EmailProviderTypeEnum,
+        type: 'varchar',
+        length: 50,
         nullable: false
     }),
-    _ts_metadata("design:type", typeof _enums.EmailProviderTypeEnum === "undefined" ? Object : _enums.EmailProviderTypeEnum)
+    _ts_metadata("design:type", String)
 ], EmailConfig.prototype, "provider", void 0);
 _ts_decorate([
     (0, _typeorm.Column)({

package/cjs/utils/email-templates.util.js

@@ -1,4 +1,3 @@
-// ─── Shared Styles ───────────────────────────────────────────────────────────
 "use strict";
 Object.defineProperty(exports, "__esModule", {
     value: true
@@ -17,6 +16,7 @@ _export(exports, {
         return getResetPasswordEmailFormat;
     }
 });
+// ─── Shared Styles ───────────────────────────────────────────────────────────
 const BASE_STYLES = `
   body { font-family: Arial, sans-serif; background-color: #f4f4f7; margin: 0; padding: 0; }
   .email-container { max-width: 500px; margin: 40px auto; background-color: #ffffff; padding: 30px; border-radius: 8px; box-shadow: 0 2px 6px rgba(0,0,0,0.1); text-align: center; }

package/entities/email-config.entity.d.ts

@@ -1,8 +1,7 @@
 import { Identity } from '@flusys/nestjs-shared/entities';
-import { EmailProviderTypeEnum } from '../enums';
 export declare class EmailConfig extends Identity {
     name: string;
-    provider: EmailProviderTypeEnum;
+    provider: string;
     config: Record<string, unknown>;
     fromEmail: string | null;
     fromName: string | null;

package/fesm/entities/email-config.entity.js

@@ -22,7 +22,6 @@ function _ts_metadata(k, v) {
 }
 import { Identity } from '@flusys/nestjs-shared/entities';
 import { Column, Entity, Index } from 'typeorm';
-import { EmailProviderTypeEnum } from '../enums';
 export class EmailConfig extends Identity {
     constructor(...args){
         super(...args), _define_property(this, "name", void 0), _define_property(this, "provider", void 0), _define_property(this, "config", void 0), _define_property(this, "fromEmail", void 0), _define_property(this, "fromName", void 0), _define_property(this, "isActive", void 0), _define_property(this, "isDefault", void 0);
@@ -38,11 +37,11 @@ _ts_decorate([
 ], EmailConfig.prototype, "name", void 0);
 _ts_decorate([
     Column({
-        type: 'enum',
-        enum: EmailProviderTypeEnum,
+        type: 'varchar',
+        length: 50,
         nullable: false
     }),
-    _ts_metadata("design:type", typeof EmailProviderTypeEnum === "undefined" ? Object : EmailProviderTypeEnum)
+    _ts_metadata("design:type", String)
 ], EmailConfig.prototype, "provider", void 0);
 _ts_decorate([
     Column({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flusys/nestjs-email",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "Modular email package with SMTP, SendGrid, and Mailgun providers",
   "main": "cjs/index.js",
   "module": "fesm/index.js",
@@ -32,6 +32,11 @@
       "import": "./fesm/controllers/index.js",
       "require": "./cjs/controllers/index.js"
     },
+    "./docs": {
+      "types": "./docs/index.d.ts",
+      "import": "./fesm/docs/index.js",
+      "require": "./cjs/docs/index.js"
+    },
     "./dtos": {
       "types": "./dtos/index.d.ts",
       "import": "./fesm/dtos/index.js",
@@ -99,7 +104,7 @@
     }
   },
   "dependencies": {
-    "@flusys/nestjs-core": "2.0.0",
-    "@flusys/nestjs-shared": "2.0.0"
+    "@flusys/nestjs-core": "3.0.0",
+    "@flusys/nestjs-shared": "3.0.0"
   }
 }