@flusys/ng-email 1.1.0-beta

package/README.md

@@ -0,0 +1,660 @@
+# Email Package Guide
+
+> **Package:** `@flusys/ng-email`
+> **Type:** Email management with configurations, templates, and sending
+
+---
+
+## Overview
+
+`@flusys/ng-email` provides complete email management:
+
+- **Email Configurations** - CRUD for SMTP, SendGrid, Mailgun providers
+- **Email Templates** - Visual template management with variable interpolation
+- **HTML/Plain Text** - Toggle between content types via `isHtml` field
+- **Test Sending** - Test configurations and templates with dynamic variables
+- **Company Scoping** - Automatic company-scoped queries (when enabled)
+- **Lazy Loading** - All page components are lazy-loaded via routes
+
+### Package Hierarchy
+
+```
+@flusys/ng-core           <- Foundation (BaseApiService, APP_CONFIG)
+        |
+@flusys/ng-shared         <- Shared utilities (ApiResourceService, IBaseEntity)
+        |
+@flusys/ng-layout         <- Layout (LAYOUT_AUTH_STATE for company context)
+        |
+@flusys/ng-email          <- Email management (THIS PACKAGE)
+```
+
+### Company Context
+
+Email components use `LAYOUT_AUTH_STATE` from `@flusys/ng-layout` for company context. This follows the Provider Interface Pattern - ng-email depends on ng-layout's abstraction, not ng-auth directly.
+
+```typescript
+import { LAYOUT_AUTH_STATE } from '@flusys/ng-layout';
+
+private readonly companyContext = inject(LAYOUT_AUTH_STATE);
+
+readonly currentCompanyName = computed(
+  () => this.companyContext.currentCompanyInfo()?.name ?? DEFAULT_APP_NAME,
+);
+```
+
+---
+
+## Package Architecture
+
+```
+ng-email/
+├── interfaces/
+│   ├── email-config.interface.ts     # IEmailConfig, ICreateEmailConfigDto
+│   ├── email-template.interface.ts   # IEmailTemplate, ICreateEmailTemplateDto
+│   ├── email-send.interface.ts       # ISendEmailDto, ISendTemplateEmailDto
+│   └── public-api.ts
+├── services/
+│   ├── email-config-api.service.ts   # Config CRUD
+│   ├── email-template-api.service.ts # Template CRUD
+│   ├── email-send.service.ts         # Email sending operations
+│   └── public-api.ts
+├── pages/
+│   ├── config/
+│   │   ├── email-config-list.component.ts
+│   │   └── email-config-form.component.ts
+│   └── template/
+│       ├── template-list.component.ts
+│       └── template-form.component.ts
+├── routes/
+│   └── email.routes.ts
+└── public-api.ts
+```
+
+---
+
+## Route Integration
+
+### Adding Email Routes
+
+```typescript
+// app.routes.ts
+import { EMAIL_ROUTES } from '@flusys/ng-email';
+
+export const routes: Routes = [
+  {
+    path: 'email',
+    children: EMAIL_ROUTES,
+  },
+];
+```
+
+### Route Structure
+
+| Path | Component | Description |
+|------|-----------|-------------|
+| `/email/configs` | EmailConfigListComponent | List email configurations |
+| `/email/configs/new` | EmailConfigFormComponent | Create new config |
+| `/email/configs/:id` | EmailConfigFormComponent | Edit config |
+| `/email/templates` | TemplateListComponent | List email templates |
+| `/email/templates/new` | TemplateFormComponent | Create new template |
+| `/email/templates/:id` | TemplateFormComponent | Edit template |
+
+---
+
+## Interfaces
+
+### Email Configuration
+
+```typescript
+interface IEmailConfig extends IBaseEntity {
+  name: string;
+  provider: 'smtp' | 'sendgrid' | 'mailgun';
+  config: Record<string, any>;    // Provider-specific config
+  fromEmail: string;
+  fromName: string | null;
+  replyTo: string | null;
+  isActive: boolean;
+  isDefault: boolean;             // Set as default configuration
+  companyId?: string | null;
+}
+
+interface ICreateEmailConfigDto {
+  name: string;
+  provider: 'smtp' | 'sendgrid' | 'mailgun';
+  config: Record<string, any>;
+  fromEmail: string;
+  fromName?: string;
+  replyTo?: string;
+  isActive?: boolean;
+  isDefault?: boolean;
+}
+
+interface IUpdateEmailConfigDto {
+  id: string;
+  name?: string;
+  provider?: 'smtp' | 'sendgrid' | 'mailgun';
+  config?: Record<string, any>;
+  fromEmail?: string;
+  fromName?: string;
+  replyTo?: string;
+  isActive?: boolean;
+  isDefault?: boolean;
+}
+```
+
+### Provider-Specific Configs
+
+```typescript
+// SMTP
+interface ISmtpConfig {
+  host: string;
+  port: number;
+  secure: boolean;
+  auth: {
+    user: string;
+    pass: string;
+  };
+}
+
+// SendGrid
+interface ISendGridConfig {
+  apiKey: string;
+}
+
+// Mailgun
+interface IMailgunConfig {
+  apiKey: string;
+  domain: string;
+  region?: 'us' | 'eu';
+}
+```
+
+### Email Template
+
+```typescript
+interface IEmailTemplate extends IBaseEntity {
+  name: string;
+  slug: string;
+  description: string | null;
+  subject: string;
+  schema: Record<string, unknown>;
+  htmlContent: string;
+  textContent: string | null;
+  schemaVersion: number;
+  isActive: boolean;
+  isHtml: boolean;                 // true=HTML mode, false=plain text
+  metadata: Record<string, unknown> | null;
+  companyId?: string | null;
+}
+
+interface ICreateEmailTemplateDto {
+  name: string;
+  slug: string;
+  description?: string;
+  subject: string;
+  schema?: Record<string, unknown>;
+  htmlContent: string;
+  textContent?: string;
+  isActive?: boolean;
+  isHtml?: boolean;
+}
+
+interface IUpdateEmailTemplateDto {
+  id: string;
+  name?: string;
+  slug?: string;
+  description?: string;
+  subject?: string;
+  schema?: Record<string, unknown>;
+  htmlContent?: string;
+  textContent?: string;
+  isActive?: boolean;
+  isHtml?: boolean;
+}
+```
+
+### Email Sending
+
+```typescript
+// Direct email
+interface ISendEmailDto {
+  to: string | string[];
+  cc?: string | string[];
+  bcc?: string | string[];
+  subject: string;
+  html: string;
+  text?: string;
+  from?: string;
+  fromName?: string;
+  replyTo?: string;
+  emailConfigId?: string;
+  attachments?: IEmailAttachmentDto[];
+}
+
+// Template email
+interface ISendTemplateEmailDto {
+  templateId?: string;
+  templateSlug?: string;
+  to: string | string[];
+  cc?: string | string[];
+  bcc?: string | string[];
+  variables?: Record<string, any>;
+  from?: string;
+  fromName?: string;
+  replyTo?: string;
+  emailConfigId?: string;
+  attachments?: IEmailAttachmentDto[];
+}
+
+// Test email
+interface ITestEmailDto {
+  emailConfigId: string;
+  recipient: string;
+}
+
+// Attachment
+interface IEmailAttachmentDto {
+  filename: string;
+  content: string;               // Base64 encoded
+  contentType?: string;
+}
+
+// Result
+interface IEmailSendResult {
+  success: boolean;
+  messageId?: string;
+  error?: string;
+}
+```
+
+---
+
+## Services
+
+All services are `providedIn: 'root'`. Company scoping is automatic when the company feature is enabled.
+
+### EmailConfigApiService
+
+Email configuration CRUD. Extends `ApiResourceService<IUpdateEmailConfigDto, IEmailConfig>`.
+
+**Inherited CRUD methods** (from ApiResourceService): `insert`, `update`, `findById`, `getAll`, `delete` and their `*Async` variants.
+
+### EmailTemplateApiService
+
+Email template CRUD. Extends `ApiResourceService<IUpdateEmailTemplateDto, IEmailTemplate>`.
+
+**Inherited CRUD methods** (from ApiResourceService): `insert`, `update`, `findById`, `getAll`, `delete` and their `*Async` variants.
+
+### EmailSendService
+
+Handles email sending operations. Extends `BaseApiService`.
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `sendDirect(dto)` | `POST /email/send/direct` | Send email directly |
+| `sendTemplate(dto)` | `POST /email/send/template` | Send using template |
+| `testConfiguration(dto)` | `POST /email/send/test` | Test email configuration |
+
+---
+
+## Components
+
+All components are standalone, use Angular 21 signals, and lazy-load via routes.
+
+### EmailConfigListComponent
+
+Lists email configurations with actions.
+
+**Features:**
+- Lazy pagination via `p-datatable`
+- Provider type tags (SMTP, SendGrid, Mailgun)
+- Active/Inactive status badges
+- Test button with dialog for recipient input
+- Edit and delete actions
+- Company info display when enabled
+
+**Test Dialog:**
+Opens a PrimeNG dialog to enter test recipient email instead of browser `prompt()`.
+
+```typescript
+readonly showTestDialog = signal(false);
+readonly selectedConfig = signal<IEmailConfig | null>(null);
+testRecipient = '';
+
+onTest(config: IEmailConfig): void {
+  this.selectedConfig.set(config);
+  this.testRecipient = '';
+  this.showTestDialog.set(true);
+}
+
+async sendTestEmail(): Promise<void> {
+  const config = this.selectedConfig();
+  if (!config || !this.testRecipient) return;
+
+  const response = await firstValueFrom(
+    this.emailSendService.testConfiguration({
+      emailConfigId: config.id,
+      recipient: this.testRecipient,
+    })
+  );
+
+  if (response.data?.success) {
+    this.messageService.add({
+      severity: 'success',
+      summary: 'Success',
+      detail: `Test email sent! Message ID: ${response.data.messageId}`,
+    });
+    this.showTestDialog.set(false);
+  }
+}
+```
+
+### EmailConfigFormComponent
+
+Create/edit email configuration with dynamic provider fields.
+
+**Features:**
+- Dynamic form fields based on selected provider
+- SMTP: host, port, secure, username, password
+- SendGrid: apiKey
+- Mailgun: apiKey, domain, region
+- Active toggle
+- **Set as Default toggle** - marks configuration as the default for sending emails
+- Create/Edit mode auto-detection
+
+**Default Configuration:**
+When `isDefault: true`, this configuration will be used automatically when no `emailConfigId` is provided in send requests.
+
+### TemplateListComponent
+
+Lists email templates with test send functionality.
+
+**Features:**
+- Lazy pagination via `p-datatable`
+- HTML/Text type badges (based on `isHtml`)
+- Active/Inactive status badges
+- Test send button with dialog
+- Edit and delete actions
+
+**Test Send Dialog:**
+- Select email configuration
+- Enter recipient email
+- **Dynamic variable inputs** extracted from template content
+
+```typescript
+/** Extract variables from template content */
+readonly templateVariables = computed(() => {
+  const template = this.selectedTemplate();
+  if (!template) return [];
+
+  // Combine all content sources to extract variables
+  const content = [
+    template.subject,
+    template.htmlContent,
+    template.textContent || '',
+  ].join(' ');
+
+  // Find all {{variableName}} patterns
+  const matches = content.matchAll(/\{\{(\w+)\}\}/g);
+  const variables = new Set<string>();
+
+  for (const match of matches) {
+    variables.add(match[1]);
+  }
+
+  return Array.from(variables).sort();
+});
+
+// Variable values bound to form inputs
+variableValues: Record<string, string> = {};
+```
+
+### TemplateFormComponent
+
+Create/edit email template with HTML/Plain Text toggle.
+
+**Features:**
+- Name, slug, description fields
+- Subject line with variable support
+- **Editor Mode Toggle** (HTML/Plain Text)
+- HTML content editor (when `isHtml: true`)
+- Plain text content editor (editable, not read-only)
+- Content sync between modes when switching
+- Preview with variable highlighting
+- Active toggle
+
+**Editor Mode Switching:**
+
+```typescript
+setEditorMode(mode: 'html' | 'text'): void {
+  const currentMode = this.editorMode();
+
+  // Sync content when switching modes
+  if (currentMode === 'text' && mode === 'html') {
+    if (!this.formModel.htmlContent && this.formModel.textContent) {
+      this.formModel.htmlContent = this.textToHtml(this.formModel.textContent);
+    }
+  } else if (currentMode === 'html' && mode === 'text') {
+    if (!this.formModel.textContent && this.formModel.htmlContent) {
+      this.formModel.textContent = this.htmlToPlainText(this.formModel.htmlContent);
+    }
+  }
+
+  this.editorMode.set(mode);
+  this.formModel.isHtml = mode === 'html';
+}
+```
+
+---
+
+## Usage Examples
+
+### Send Direct Email
+
+```typescript
+import { EmailSendService } from '@flusys/ng-email';
+
+private readonly emailSendService = inject(EmailSendService);
+
+async sendEmail(): Promise<void> {
+  const response = await firstValueFrom(
+    this.emailSendService.sendDirect({
+      to: 'user@example.com',
+      subject: 'Hello!',
+      html: '<h1>Hello World</h1>',
+      text: 'Hello World',
+      emailConfigId: 'config-id',
+    })
+  );
+
+  if (response.data?.success) {
+    console.log('Sent! Message ID:', response.data.messageId);
+  }
+}
+```
+
+### Send Template Email
+
+```typescript
+async sendTemplateEmail(): Promise<void> {
+  const response = await firstValueFrom(
+    this.emailSendService.sendTemplate({
+      templateId: 'template-id',
+      to: 'user@example.com',
+      emailConfigId: 'config-id',
+      variables: {
+        userName: 'John',
+        appName: 'My App',
+        verificationLink: 'https://example.com/verify/abc123',
+      },
+    })
+  );
+
+  if (response.data?.success) {
+    console.log('Sent! Message ID:', response.data.messageId);
+  }
+}
+```
+
+### Test Configuration
+
+```typescript
+async testConfig(configId: string, recipient: string): Promise<boolean> {
+  const response = await firstValueFrom(
+    this.emailSendService.testConfiguration({
+      emailConfigId: configId,
+      recipient: recipient,
+    })
+  );
+
+  return response.data?.success ?? false;
+}
+```
+
+### Create Email Template
+
+```typescript
+import { EmailTemplateApiService } from '@flusys/ng-email';
+
+private readonly templateService = inject(EmailTemplateApiService);
+
+async createTemplate(): Promise<void> {
+  const response = await firstValueFrom(
+    this.templateService.insert({
+      name: 'Welcome Email',
+      slug: 'welcome-email',
+      description: 'Sent to new users',
+      subject: 'Welcome {{userName}}!',
+      isHtml: true,
+      htmlContent: '<h1>Welcome, {{userName}}!</h1><p>Thank you for joining.</p>',
+      textContent: 'Welcome, {{userName}}! Thank you for joining.',
+      isActive: true,
+    })
+  );
+
+  if (response.success) {
+    console.log('Template created:', response.data?.id);
+  }
+}
+```
+
+---
+
+## Backend Integration
+
+All endpoints use **POST-only RPC** style (not REST).
+
+| Service | Endpoint | Description |
+|---------|----------|-------------|
+| Config | `POST /email/config/insert` | Create config |
+| Config | `POST /email/config/get/:id` | Get config by ID |
+| Config | `POST /email/config/get-all` | List configs (paginated) |
+| Config | `POST /email/config/update` | Update config |
+| Config | `POST /email/config/delete` | Delete config |
+| Template | `POST /email/template/insert` | Create template |
+| Template | `POST /email/template/get/:id` | Get template by ID |
+| Template | `POST /email/template/get-all` | List templates (paginated) |
+| Template | `POST /email/template/update` | Update template |
+| Template | `POST /email/template/delete` | Delete template |
+| Send | `POST /email/send/direct` | Send email directly |
+| Send | `POST /email/send/template` | Send using template |
+| Send | `POST /email/send/test` | Test configuration |
+
+---
+
+## Best Practices
+
+### 1. Use Template Slugs for Code References
+
+```typescript
+// ✅ Use slug for programmatic access
+await this.emailSendService.sendTemplate({
+  templateSlug: 'welcome-email',  // Stable identifier
+  ...
+});
+
+// ❌ Don't hardcode template IDs
+await this.emailSendService.sendTemplate({
+  templateId: 'f47ac10b-58cc-4372-a567-0e02b2c3d479',  // May change
+  ...
+});
+```
+
+### 2. Provide Both HTML and Text Content
+
+```typescript
+// ✅ Provide both for maximum compatibility
+{
+  isHtml: true,
+  htmlContent: '<h1>Hello!</h1>',
+  textContent: 'Hello!',  // Fallback for text-only clients
+}
+```
+
+### 3. Test Configurations Before Production
+
+Always use the test send feature to verify configurations work before using them in production.
+
+### 4. Use Meaningful Variable Names
+
+```typescript
+// ✅ Clear, descriptive variable names
+"Hello {{userName}}, your order #{{orderNumber}} shipped on {{shipDate}}."
+
+// ❌ Vague or abbreviated names
+"Hello {{u}}, order {{o}} shipped {{d}}."
+```
+
+### 5. Handle Send Failures Gracefully
+
+```typescript
+async sendEmail(): Promise<void> {
+  const response = await firstValueFrom(
+    this.emailSendService.sendTemplate({ ... })
+  );
+
+  if (response.data?.success) {
+    this.messageService.add({
+      severity: 'success',
+      summary: 'Email Sent',
+      detail: `Message ID: ${response.data.messageId}`,
+    });
+  } else {
+    this.messageService.add({
+      severity: 'error',
+      summary: 'Send Failed',
+      detail: response.data?.error || 'Unknown error occurred',
+    });
+  }
+}
+```
+
+---
+
+## Public API Exports
+
+```typescript
+// Interfaces
+export {
+  IEmailConfig, ICreateEmailConfigDto, IUpdateEmailConfigDto,
+  ISmtpConfig, ISendGridConfig, IMailgunConfig,
+  IEmailTemplate, ICreateEmailTemplateDto, IUpdateEmailTemplateDto,
+  ISendEmailDto, ISendTemplateEmailDto, ITestEmailDto,
+  IEmailAttachmentDto, IEmailSendResult,
+} from '@flusys/ng-email';
+
+// Services
+export {
+  EmailConfigApiService,
+  EmailTemplateApiService,
+  EmailSendService,
+} from '@flusys/ng-email';
+
+// Routes
+export { EMAIL_ROUTES } from '@flusys/ng-email';
+```
+
+---
+
+**Last Updated:** 2026-02-17
+**Angular Version:** 21