@flusys/nestjs-email 1.0.0-rc

package/README.md

@@ -0,0 +1,552 @@
+# 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)
+- [Module Setup](#module-setup)
+- [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
+```
+
+---
+
+## 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],
+});
+```
+
+---
+
+## 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-18

package/cjs/config/email-config.service.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "EmailConfigService", {
+    enumerable: true,
+    get: function() {
+        return EmailConfigService;
+    }
+});
+const _common = require("@nestjs/common");
+const _interfaces = require("../interfaces");
+const _emailconstants = require("./email.constants");
+function _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+function _ts_decorate(decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+function _ts_metadata(k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+function _ts_param(paramIndex, decorator) {
+    return function(target, key) {
+        decorator(target, key, paramIndex);
+    };
+}
+let EmailConfigService = class EmailConfigService {
+    isCompanyFeatureEnabled() {
+        return this.options.bootstrapAppConfig?.enableCompanyFeature ?? false;
+    }
+    getDatabaseMode() {
+        return this.options.bootstrapAppConfig?.databaseMode ?? 'single';
+    }
+    isMultiTenant() {
+        return this.getDatabaseMode() === 'multi-tenant';
+    }
+    getRateLimitPerMinute() {
+        return this.options.config?.rateLimitPerMinute ?? 60;
+    }
+    isLoggingEnabled() {
+        return this.options.config?.enableLogging ?? false;
+    }
+    getDefaultProvider() {
+        return this.options.config?.defaultProvider;
+    }
+    getDefaultFromName() {
+        return _emailconstants.DEFAULT_FROM_NAME;
+    }
+    getDefaultDatabaseConfig() {
+        return this.options.config?.defaultDatabaseConfig;
+    }
+    getOptions() {
+        return this.options;
+    }
+    constructor(options){
+        _define_property(this, "options", void 0);
+        this.options = options;
+    }
+};
+EmailConfigService = _ts_decorate([
+    (0, _common.Injectable)(),
+    _ts_param(0, (0, _common.Inject)(_emailconstants.EMAIL_MODULE_OPTIONS)),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof _interfaces.EmailModuleOptions === "undefined" ? Object : _interfaces.EmailModuleOptions
+    ])
+], EmailConfigService);

package/cjs/config/email.constants.js

@@ -0,0 +1,22 @@
+/**
+ * Email Module Constants
+ */ "use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get DEFAULT_FROM_NAME () {
+        return DEFAULT_FROM_NAME;
+    },
+    get EMAIL_MODULE_OPTIONS () {
+        return EMAIL_MODULE_OPTIONS;
+    }
+});
+const EMAIL_MODULE_OPTIONS = 'EMAIL_MODULE_OPTIONS';
+const DEFAULT_FROM_NAME = 'FLUSYS';

package/cjs/config/index.js

@@ -0,0 +1,19 @@
+"use strict";
+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)) {
+            Object.defineProperty(to, k, {
+                enumerable: true,
+                get: function() {
+                    return from[k];
+                }
+            });
+        }
+    });
+    return from;
+}