@zyther/tzmail 0.1.4 → 0.5.0

package/src/core/interfaces/template.interface.ts

@@ -0,0 +1,71 @@
+import { ThemeType } from "../enums/theme.enum";
+
+export interface ITemplate {
+  name: string;
+  theme: ThemeType;
+  variant: 'light' | 'dark';
+  config: ITemplateConfig;
+  render(data: any): Promise<string>;
+}
+
+export interface ITemplateConfig {
+  /** BCP 47 language tag written to the generated document; defaults to en. */
+  language?: string;
+  /** Text direction for right-to-left or automatic-script content; defaults to ltr. */
+  direction?: 'ltr' | 'rtl' | 'auto';
+  /** Hidden inbox preview text shown beside the subject; limited to 500 characters. */
+  preheader?: string;
+  /** Decoration for generated footer links; defaults to none. Set to underline when desired. */
+  linkDecoration?: 'none' | 'underline';
+  header?: IHeaderConfig;
+  body?: IBodyConfig;
+  footer?: IFooterConfig;
+  layout?: 'full' | 'minimal';
+  spacing?: 'compact' | 'normal' | 'relaxed';
+  borderRadius?: 'none' | 'small' | 'medium' | 'large';
+}
+
+export interface IBodyConfig {
+  title?: string;
+  message?: string;
+  /** HTML intencionalmente confiável; os demais campos textuais são escapados pelo renderer. */
+  content?: string;
+  buttonText?: string;
+  buttonUrl?: string;
+  buttonVariant?: 'primary' | 'secondary' | 'success' | 'danger';
+  alignment?: 'left' | 'center' | 'right';
+  backgroundColor?: string;
+  textColor?: string;
+  fontSize?: number;
+}
+
+export interface IHeaderConfig {
+  show: boolean;
+  logo?: {
+    type: 'text' | 'image';
+    text?: string;
+    imageUrl?: string;
+    alt?: string;
+    size?: 'small' | 'medium' | 'large';
+  };
+  backgroundColor?: string;
+  textColor?: string;
+}
+
+export interface IFooterConfig {
+  show: boolean;
+  links?: Array<{
+    text: string;
+    url: string;
+  }>;
+  socialLinks?: Array<{
+    platform: 'facebook' | 'twitter' | 'linkedin' | 'github' | 'instagram' | 'youtube' | 'tiktok' | 'pinterest' | 'reddit' | 'gitlab' | 'stackoverflow' | 'medium' | 'dribbble' | 'behance' | 'telegram';
+    url: string;
+  }>;
+  copyrightText?: string;
+  unsubscribeText?: string;
+  /** URL opcional do link de cancelamento; sem ela, o texto é exibido sem href fictício. */
+  unsubscribeUrl?: string;
+  backgroundColor?: string;
+  textColor?: string;
+}

package/src/factories/email-factory.ts

@@ -0,0 +1,208 @@
+import { createHash } from 'crypto';
+import { createRequire } from 'module';
+import nodemailer from 'nodemailer';
+import {
+  IAmazonSesConfig,
+  IEmailConfig,
+  IEmailOptions,
+  IEmailSendResult,
+  IMailgunConfig,
+  ISendGridConfig
+} from '../core/interfaces/email.interface';
+import { EmailService } from '../services/email.service';
+import { ITemplateServiceOptions, TemplateService } from '../services/template.service';
+import { AttachmentService, IAttachmentServiceOptions } from '../services/attachment.service';
+import { ThemeType } from '../core/enums/theme.enum';
+import { ITemplateConfig } from '../core/interfaces/template.interface';
+import { IEmailTransport } from '../providers/provider.interface';
+import { NodemailerTransport } from '../providers/nodemailer.transport';
+import { SendGridTransport } from '../providers/sendgrid.transport';
+import { MailgunTransport } from '../providers/mailgun.transport';
+import { BullMQEmailQueue, IBullMQEmailQueueConfig } from '../queues/bullmq-email-queue';
+
+const loadOptionalModule = createRequire(__filename);
+
+export class EmailFactory {
+  private static instance?: EmailFactory;
+  private static singletonFingerprint?: string;
+  private emailService: EmailService;
+  private templateService: TemplateService;
+  private attachmentService: AttachmentService;
+
+  private constructor(
+    transport: IEmailTransport,
+    defaultFrom?: string,
+    templateOptions?: ITemplateServiceOptions,
+    attachmentOptions?: IAttachmentServiceOptions,
+    errorStage: 'smtp' | 'provider' = 'smtp'
+  ) {
+    this.emailService = new EmailService(transport, defaultFrom, errorStage);
+    this.templateService = new TemplateService(templateOptions);
+    this.attachmentService = new AttachmentService(attachmentOptions);
+  }
+
+  /**
+   * Returns the process singleton. A later call with different settings fails
+   * explicitly rather than silently continuing with the first configuration.
+   */
+  static initialize(config: IEmailConfig, templateOptions?: ITemplateServiceOptions, attachmentOptions?: IAttachmentServiceOptions): EmailFactory {
+    const fingerprint = this.fingerprint(config, templateOptions, attachmentOptions);
+    if (!this.instance) {
+      this.instance = new EmailFactory(
+        new NodemailerTransport(nodemailer.createTransport(config)),
+        config.defaultFrom,
+        templateOptions,
+        attachmentOptions
+      );
+      this.singletonFingerprint = fingerprint;
+    } else if (this.singletonFingerprint !== fingerprint) {
+      throw new Error('EmailFactory is already initialized with a different configuration; use EmailFactory.create() for an independent instance.');
+    }
+    return this.instance;
+  }
+
+  /** Creates an independent factory instance without changing the singleton. */
+  static create(config: IEmailConfig, templateOptions?: ITemplateServiceOptions, attachmentOptions?: IAttachmentServiceOptions): EmailFactory {
+    return new EmailFactory(
+      new NodemailerTransport(nodemailer.createTransport(config)),
+      config.defaultFrom,
+      templateOptions,
+      attachmentOptions
+    );
+  }
+
+  /** Creates an independent SendGrid Web API v3 client; no provider state is shared between instances. */
+  static createSendGrid(config: ISendGridConfig, templateOptions?: ITemplateServiceOptions, attachmentOptions?: IAttachmentServiceOptions): EmailFactory {
+    return new EmailFactory(new SendGridTransport(config), config.defaultFrom, templateOptions, attachmentOptions, 'provider');
+  }
+
+  /** Creates an independent Mailgun Messages API client. */
+  static createMailgun(config: IMailgunConfig, templateOptions?: ITemplateServiceOptions, attachmentOptions?: IAttachmentServiceOptions): EmailFactory {
+    return new EmailFactory(new MailgunTransport(config), config.defaultFrom, templateOptions, attachmentOptions, 'provider');
+  }
+
+  /** Creates an Amazon SES v2 transport using the AWS SDK credential provider chain unless credentials are supplied. */
+  static createSES(config: IAmazonSesConfig, templateOptions?: ITemplateServiceOptions, attachmentOptions?: IAttachmentServiceOptions): EmailFactory {
+    if (!config.region.trim()) throw new Error('Amazon SES region is required');
+    let awsSes: {
+      SESv2Client: new (options: Record<string, unknown>) => unknown;
+      SendEmailCommand: unknown;
+    };
+    try {
+      awsSes = loadOptionalModule('@aws-sdk/client-sesv2') as typeof awsSes;
+    } catch (error) {
+      throw new Error('Amazon SES support requires optional package @aws-sdk/client-sesv2. Install it with: npm install @aws-sdk/client-sesv2', { cause: error });
+    }
+    const sesClient = new awsSes.SESv2Client({
+      region: config.region,
+      ...(config.credentials ? { credentials: config.credentials } : {})
+    });
+    const transporter = nodemailer.createTransport({
+      SES: { sesClient, SendEmailCommand: awsSes.SendEmailCommand }
+    } as never);
+    return new EmailFactory(
+      new NodemailerTransport(transporter, () => (sesClient as { destroy?: () => void }).destroy?.()),
+      config.defaultFrom,
+      templateOptions,
+      attachmentOptions,
+      'provider'
+    );
+  }
+
+  /** Creates an instance around a user-supplied transport adapter. */
+  static createWithTransport(
+    transport: IEmailTransport,
+    defaultFrom?: string,
+    templateOptions?: ITemplateServiceOptions,
+    attachmentOptions?: IAttachmentServiceOptions
+  ): EmailFactory {
+    return new EmailFactory(transport, defaultFrom, templateOptions, attachmentOptions, 'provider');
+  }
+
+  /** Creates an optional Redis-backed BullMQ producer/worker integration. */
+  static createBullMQQueue(config: IBullMQEmailQueueConfig): BullMQEmailQueue {
+    return new BullMQEmailQueue(config);
+  }
+
+  static getInstance(): EmailFactory {
+    if (!this.instance) {
+      throw new Error('EmailFactory not initialized. Call initialize() first.');
+    }
+    return this.instance;
+  }
+
+  async sendEmail(options: IEmailOptions): Promise<IEmailSendResult> {
+    return this.emailService.send(options);
+  }
+
+  getTemplateService(): TemplateService {
+    return this.templateService;
+  }
+
+  getAttachmentService(): AttachmentService {
+    return this.attachmentService;
+  }
+
+  /** Verify connectivity when supported by the selected transport; API transports may not provide a safe check. */
+  async verifyTransport(): Promise<true> {
+    return this.emailService.verify();
+  }
+
+  /** Release pooled SMTP connections and the template cache cleanup timer. */
+  close(): void {
+    this.emailService.close();
+    this.templateService.dispose();
+    if (EmailFactory.instance === this) {
+      EmailFactory.instance = undefined;
+      EmailFactory.singletonFingerprint = undefined;
+    }
+  }
+
+  async previewTemplate(
+    themeType: ThemeType,
+    variant: 'light' | 'dark',
+    config: ITemplateConfig,
+    data: any
+  ): Promise<string> {
+    return this.templateService.previewTemplate(themeType, variant, config, data);
+  }
+
+  getThemeInfo(themeType: ThemeType) {
+    return this.templateService.getThemeInfo(themeType);
+  }
+
+  listThemes() {
+    return this.templateService.listThemes();
+  }
+
+  getTemplateStats() {
+    return this.templateService.getTemplateStats();
+  }
+
+  /** Hashes canonicalized settings so credentials are never exposed in errors/logs. */
+  private static fingerprint(config: IEmailConfig, templateOptions?: ITemplateServiceOptions, attachmentOptions?: IAttachmentServiceOptions): string {
+    const canonicalize = (value: any, ancestors = new Set<object>()): string => {
+      if (value === undefined) return 'undefined';
+      if (value === null || typeof value !== 'object') {
+        if (typeof value === 'function') return `function:${value.toString()}`;
+        if (typeof value === 'bigint') return `bigint:${value.toString()}`;
+        return JSON.stringify(value) ?? String(value);
+      }
+      if (ancestors.has(value)) return '[Circular]';
+      ancestors.add(value);
+      let result: string;
+      if (Array.isArray(value)) {
+        result = `[${value.map((item) => canonicalize(item, ancestors)).join(',')}]`;
+      } else if (value instanceof Date) {
+        result = `date:${value.toISOString()}`;
+      } else {
+        result = `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalize(value[key], ancestors)}`).join(',')}}`;
+      }
+      ancestors.delete(value);
+      return result;
+    };
+
+    const serialized = `${canonicalize(config)}|${canonicalize(templateOptions)}|${canonicalize(attachmentOptions)}`;
+    return createHash('sha256').update(serialized).digest('hex');
+  }
+}

package/src/factories/template-factory.ts

@@ -0,0 +1,201 @@
+import { ThemeType } from '../core/enums/theme.enum';
+import { ITemplate, ITemplateConfig } from '../core/interfaces/template.interface';
+import { ITheme } from '../templates/themes/theme.interface';
+import { SystemTheme } from '../templates/themes/system.theme';
+import { MonokaiTheme } from '../templates/themes/monokai.theme';
+import { ModernTheme } from '../templates/themes/modern.theme';
+import { CorporateTheme } from '../templates/themes/corporate.theme';
+import { MinimalTheme } from '../templates/themes/minimal.theme';
+import { AuroraTheme } from '../templates/themes/aurora.theme';
+import { OceanTheme } from '../templates/themes/ocean.theme';
+import { SunsetTheme } from '../templates/themes/sunset.theme';
+import { LavenderTheme } from '../templates/themes/lavender.theme';
+import { ForestTheme } from '../templates/themes/forest.theme';
+import { EditorialTheme } from '../templates/themes/editorial.theme';
+import { PastelTheme } from '../templates/themes/pastel.theme';
+import { NeoBrutalTheme } from '../templates/themes/neobrutal.theme';
+import { GlassTheme } from '../templates/themes/glass.theme';
+import { MidnightTheme } from '../templates/themes/midnight.theme';
+import { TemplateBuilder } from '../templates/base/template-builder';
+import { readableTextColor } from '../templates/base/color-accessibility';
+
+const SAFE_COLOR = /^(#[\da-f]{3,8}|[a-z]{1,24}|(?:rgb|rgba|hsl|hsla)\([\d.%\s,+/-]+\))$/i;
+const SAFE_LANGUAGE_TAG = /^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$/;
+const SAFE_NAMED_COLORS = new Set(('transparent inherit currentcolor aliceblue antiquewhite aqua aquamarine azure beige bisque black blanchedalmond blue blueviolet brown burlywood cadetblue chartreuse chocolate coral cornflowerblue cornsilk crimson cyan darkblue darkcyan darkgoldenrod darkgray darkgrey darkgreen darkkhaki darkmagenta darkolivegreen darkorange darkorchid darkred darksalmon darkseagreen darkslateblue darkslategray darkslategrey darkturquoise darkviolet deeppink deepskyblue dimgray dimgrey dodgerblue firebrick floralwhite forestgreen fuchsia gainsboro ghostwhite gold goldenrod gray grey green greenyellow honeydew hotpink indianred indigo ivory khaki lavender lavenderblush lawngreen lemonchiffon lightblue lightcoral lightcyan lightgoldenrodyellow lightgray lightgrey lightgreen lightpink lightsalmon lightseagreen lightskyblue lightslategray lightslategrey lightsteelblue lightyellow lime limegreen linen magenta maroon mediumaquamarine mediumblue mediumorchid mediumpurple mediumseagreen mediumslateblue mediumspringgreen mediumturquoise mediumvioletred midnightblue mintcream mistyrose moccasin navajowhite navy oldlace olive olivedrab orange orangered orchid palegoldenrod palegreen paleturquoise palevioletred papayawhip peachpuff peru pink plum powderblue purple rebeccapurple red rosybrown royalblue saddlebrown salmon sandybrown seagreen seashell sienna silver skyblue slateblue slategray slategrey snow springgreen steelblue tan teal thistle tomato turquoise violet wheat white whitesmoke yellow yellowgreen').split(' '));
+function cssColor(value: string | undefined, fallback: string): string {
+  if (value === undefined) return fallback;
+  const trimmed = value.trim();
+  if (!SAFE_COLOR.test(trimmed) || (!trimmed.startsWith('#') && !/^(rgb|rgba|hsl|hsla)\(/i.test(trimmed) && !SAFE_NAMED_COLORS.has(trimmed.toLowerCase()))) {
+    throw new Error('Invalid template color value');
+  }
+  return trimmed;
+}
+function escapeHtml(value: unknown): string {
+  return String(value ?? '').replace(/[&<>"']/g, character => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[character]!));
+}
+
+function interpolate(value: string | undefined, variables: Record<string, unknown>, escapeValues = false): string | undefined {
+  if (value === undefined) return undefined;
+  return value.replace(/\{\{\s*([A-Za-z0-9_.-]+)\s*\}\}/g, (_placeholder, path: string) => {
+    let resolved: unknown = variables;
+    for (const segment of path.split('.')) {
+      if (resolved === null || typeof resolved !== 'object') throw new Error(`Missing template variable: ${path}`);
+      resolved = (resolved as Record<string, unknown>)[segment];
+    }
+    if (resolved === undefined) throw new Error(`Missing template variable: ${path}`);
+    if (resolved !== null && !['string', 'number', 'boolean'].includes(typeof resolved)) {
+      throw new Error(`Template variable ${path} must be a string, number, boolean, or null`);
+    }
+    const text = resolved === null ? '' : String(resolved);
+    return escapeValues ? escapeHtml(text) : text;
+  });
+}
+
+function resolveTemplateConfig(config: ITemplateConfig, variables: Record<string, unknown>): ITemplateConfig {
+  return {
+    ...config,
+    preheader: interpolate(config.preheader, variables),
+    header: config.header ? {
+      ...config.header,
+      logo: config.header.logo ? {
+        ...config.header.logo,
+        text: interpolate(config.header.logo.text, variables),
+        imageUrl: interpolate(config.header.logo.imageUrl, variables),
+        alt: interpolate(config.header.logo.alt, variables)
+      } : undefined
+    } : undefined,
+    body: config.body ? {
+      ...config.body,
+      title: interpolate(config.body.title, variables),
+      message: interpolate(config.body.message, variables),
+      // Substitutions inside trusted HTML are escaped before insertion.
+      content: interpolate(config.body.content, variables, true),
+      buttonText: interpolate(config.body.buttonText, variables),
+      buttonUrl: interpolate(config.body.buttonUrl, variables)
+    } : undefined,
+    footer: config.footer ? {
+      ...config.footer,
+      links: config.footer.links?.map(link => ({
+        text: interpolate(link.text, variables)!,
+        url: interpolate(link.url, variables)!
+      })),
+      socialLinks: config.footer.socialLinks?.map(link => ({
+        ...link,
+        url: interpolate(link.url, variables)!
+      })),
+      copyrightText: interpolate(config.footer.copyrightText, variables),
+      unsubscribeText: interpolate(config.footer.unsubscribeText, variables),
+      unsubscribeUrl: interpolate(config.footer.unsubscribeUrl, variables)
+    } : undefined
+  };
+}
+
+export class TemplateFactory {
+  private static themes: Map<ThemeType, ITheme> = new Map([
+    [ThemeType.SYSTEM, new SystemTheme()],
+    [ThemeType.MONOKAI, new MonokaiTheme()],
+    [ThemeType.MODERN, new ModernTheme()],
+    [ThemeType.CORPORATE, new CorporateTheme()],
+    [ThemeType.MINIMAL, new MinimalTheme()],
+    [ThemeType.AURORA, new AuroraTheme()],
+    [ThemeType.OCEAN, new OceanTheme()],
+    [ThemeType.SUNSET, new SunsetTheme()],
+    [ThemeType.LAVENDER, new LavenderTheme()],
+    [ThemeType.FOREST, new ForestTheme()],
+    [ThemeType.EDITORIAL, new EditorialTheme()],
+    [ThemeType.PASTEL, new PastelTheme()],
+    [ThemeType.NEOBRUTAL, new NeoBrutalTheme()],
+    [ThemeType.GLASS, new GlassTheme()],
+    [ThemeType.MIDNIGHT, new MidnightTheme()]
+  ]);
+
+  static createTemplate(themeType: ThemeType, variant: 'light' | 'dark', config: ITemplateConfig): ITemplate {
+    const theme = this.themes.get(themeType);
+    if (!theme) throw new Error(`Theme ${themeType} not found`);
+    if (variant !== 'light' && variant !== 'dark') throw new Error(`Invalid template variant: ${variant}`);
+    if (!config || typeof config !== 'object') throw new Error('Template config must be an object');
+    if (config.language !== undefined && (typeof config.language !== 'string' || config.language.length > 63 || !SAFE_LANGUAGE_TAG.test(config.language))) {
+      throw new Error('Invalid template language tag');
+    }
+    if (config.direction !== undefined && !['ltr', 'rtl', 'auto'].includes(config.direction)) throw new Error('Invalid template text direction');
+    if (config.linkDecoration !== undefined && !['none', 'underline'].includes(config.linkDecoration)) throw new Error('Invalid template linkDecoration');
+    if (config.preheader !== undefined && (typeof config.preheader !== 'string' || config.preheader.length > 500 || /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/.test(config.preheader))) {
+      throw new Error('preheader must be a string of at most 500 printable characters');
+    }
+
+    return {
+      name: `${themeType}_${variant}`,
+      theme: themeType,
+      variant,
+      config,
+      render: async (data: any) => {
+        const templateData = data?.templateData && typeof data.templateData === 'object' && !Array.isArray(data.templateData)
+          ? data.templateData as Record<string, unknown>
+          : {};
+        const renderConfig = resolveTemplateConfig(config, templateData);
+        const builder = new TemplateBuilder(theme, renderConfig, variant);
+        // Renderer usa sempre a configuração capturada. `data` é somente conteúdo variável,
+        // nunca uma fonte alternativa de configuração/template.
+        const body = renderConfig.body || {};
+        const alignment = body.alignment || 'left';
+        if (!['left', 'center', 'right'].includes(alignment)) throw new Error('Invalid body alignment');
+        const fontSize = body.fontSize ?? 14;
+        if (!Number.isFinite(fontSize) || fontSize < 8 || fontSize > 72) throw new Error('Invalid body font size');
+        const background = cssColor(body.backgroundColor, theme[variant].background);
+        const requestedTextColor = cssColor(body.textColor, theme[variant].text);
+        const textColor = readableTextColor(requestedTextColor, background, theme[variant].text);
+        cssColor(renderConfig.header?.backgroundColor, 'transparent');
+        cssColor(renderConfig.header?.textColor, 'inherit');
+        cssColor(renderConfig.footer?.backgroundColor, 'transparent');
+        cssColor(renderConfig.footer?.textColor, 'inherit');
+        const titleFontSize = fontSize + 7;
+        const bodyCellStyle = `padding: 0; text-align: ${alignment}; background-color: ${background}; color: ${textColor}; font-size: ${fontSize}px; font-family: ${theme.typography.fontFamily};`;
+        const titleStyle = `margin: 0 0 16px 0; color: ${textColor}; font-family: ${theme.typography.fontFamily}; font-size: ${titleFontSize}px; font-weight: ${theme.typography.fontWeights.bold}; line-height: 1.3; text-align: ${alignment};`;
+        const messageStyle = `margin: 0; color: ${textColor}; font-family: ${theme.typography.fontFamily}; font-size: ${fontSize}px; line-height: 1.6; text-align: ${alignment};`;
+        // body.content é o único campo da configuração intencionalmente tratado como HTML confiável.
+        // Título, mensagem e valores de estilo são sempre escapados/validados e não viram HTML.
+        const bodyContent = body.content ?? `
+          <table width="100%" cellpadding="0" cellspacing="0" role="presentation">
+            <tr>
+              <td align="${alignment}" style="${escapeHtml(bodyCellStyle)}">
+                <h2 style="${escapeHtml(titleStyle)}">${escapeHtml(body.title ?? 'Hello!')}</h2>
+                <p style="${escapeHtml(messageStyle)}">${escapeHtml(body.message ?? 'This is an email generated with tzMail.')}</p>
+              </td>
+            </tr>
+          </table>`;
+
+        builder.buildPreheader().buildHeader(typeof data?.headerContent === 'string' ? data.headerContent : '').buildBody(bodyContent);
+        if (body.buttonText && body.buttonUrl) {
+          builder.buildButton(body.buttonText, body.buttonUrl, body.buttonVariant || 'primary');
+        }
+        return builder.buildFooter().build();
+      }
+    };
+  }
+
+  static getTheme(themeType: ThemeType): ITheme | undefined { return this.themes.get(themeType); }
+  static listThemes(): ThemeType[] { return Array.from(this.themes.keys()); }
+
+  static getThemeInfo(themeType: ThemeType): { name: string; description: string; features: string[] } {
+    const themeInfo: Record<ThemeType, { name: string; description: string; features: string[] }> = {
+      [ThemeType.SYSTEM]: { name: 'System', description: 'Clean, professional palette with adaptive light and dark variants', features: ['Minimal design', 'Accessible contrast', 'Email-client friendly'] },
+      [ThemeType.MONOKAI]: { name: 'Monokai', description: 'Vibrant, code-inspired colors for technical content', features: ['Vivid accents', 'Developer aesthetic', 'Dark-mode variant'] },
+      [ThemeType.MODERN]: { name: 'Modern', description: 'Contemporary layout with refined colors and typography', features: ['Modern palette', 'Clean hierarchy', 'Responsive structure'] },
+      [ThemeType.CORPORATE]: { name: 'Corporate', description: 'Professional, structured styling for business communication', features: ['Serif typography', 'Gold details', 'Formal hierarchy'] },
+      [ThemeType.MINIMAL]: { name: 'Minimal', description: 'Content-first design with generous whitespace', features: ['Low visual noise', 'Generous spacing', 'Clean typography'] },
+      [ThemeType.AURORA]: { name: 'Aurora', description: 'Cool northern-lights colors with teal and violet accents', features: ['Teal and violet palette', 'Balanced light and dark modes', 'System-font typography'] },
+      [ThemeType.OCEAN]: { name: 'Ocean', description: 'Calm marine blues and cyan for clear, trustworthy messages', features: ['Navy and cyan palette', 'Readable contrast', 'Email-safe fonts'] },
+      [ThemeType.SUNSET]: { name: 'Sunset', description: 'Warm coral, terracotta, and amber for an energetic impression', features: ['Warm accents', 'Polished surfaces', 'Light and dark modes'] },
+      [ThemeType.LAVENDER]: { name: 'Lavender', description: 'Elegant violet and rose accents on soft, readable surfaces', features: ['Lavender palette', 'Soft visual tone', 'Accessible contrast'] },
+      [ThemeType.FOREST]: { name: 'Forest', description: 'Natural evergreen, moss, sage, and warm cream colors', features: ['Nature-inspired palette', 'Calm serif typography', 'Light and dark modes'] },
+      [ThemeType.EDITORIAL]: { name: 'Editorial', description: 'Magazine-inspired typography with warm paper and ink tones', features: ['Serif hierarchy', 'Brick-red accent', 'Content-led layout'] },
+      [ThemeType.PASTEL]: { name: 'Pastel', description: 'Soft peach, mint, and lavender accents with readable contrast', features: ['Gentle pastel palette', 'Bright, friendly tone', 'Accessible text colors'] },
+      [ThemeType.NEOBRUTAL]: { name: 'Neo Brutal', description: 'Bold black-and-white styling with electric color accents', features: ['High contrast', 'Strong typography', 'Distinctive cobalt and yellow'] },
+      [ThemeType.GLASS]: { name: 'Glass', description: 'Cool, glass-inspired colors implemented with solid email-safe surfaces', features: ['Cool blue-gray palette', 'Solid client-compatible colors', 'Clean typography'] },
+      [ThemeType.MIDNIGHT]: { name: 'Midnight', description: 'Premium midnight navy and champagne-gold accents', features: ['Luxe dark palette', 'Warm paper light mode', 'Serif typography'] }
+    };
+    const info = themeInfo[themeType];
+    if (!info) throw new Error(`Theme ${themeType} not found`);
+    return info;
+  }
+}

package/src/index.ts

@@ -0,0 +1,53 @@
+
+export { EmailFactory } from './factories/email-factory';
+export { TemplateFactory } from './factories/template-factory';
+export { ITemplate, ITemplateConfig } from './core/interfaces/template.interface';
+export { ThemeType } from './core/enums/theme.enum';
+export { ITheme, IThemeColorToken, IThemeEmailStyles, IThemeTextTransform } from './templates/themes/theme.interface';
+export { TemplateService, ITemplateServiceOptions } from './services/template.service';
+export { EmailService } from './services/email.service';
+export { AttachmentService, IAttachmentServiceOptions } from './services/attachment.service';
+export {
+  IAmazonSesConfig,
+  IAttachment,
+  IEmailAuth,
+  IEmailConfig,
+  IEmailOptions,
+  IEmailSendResult,
+  IMailgunConfig,
+  ISendGridConfig
+} from './core/interfaces/email.interface';
+export { IEmailTransport, ITransportMessage, ITransportSendInfo } from './providers/provider.interface';
+export {
+  BullMQEmailQueue,
+  IBullMQBackoffOptions,
+  IBullMQEmailQueueConfig,
+  IBullMQJobLike,
+  IBullMQQueueEventPayload,
+  IBullMQQueueEventsLike,
+  IBullMQQueueMetrics,
+  IBullMQRateLimiterOptions,
+  IBullMQRuntime,
+  IBullMQWorkerMetricsOptions,
+  IEmailQueueJobData,
+  IEmailQueueJobOptions,
+  IEmailQueueSender,
+  ISerializedEmailAttachment,
+  IQueuedEmailJob
+} from './queues/bullmq-email-queue';
+export { TemplateBuilder } from './templates/base/template-builder';
+export { CorporateTheme } from './templates/themes/corporate.theme';
+export { MinimalTheme } from './templates/themes/minimal.theme';
+export { ModernTheme } from './templates/themes/modern.theme';
+export { MonokaiTheme } from './templates/themes/monokai.theme';
+export { SystemTheme } from './templates/themes/system.theme';
+export { AuroraTheme } from './templates/themes/aurora.theme';
+export { OceanTheme } from './templates/themes/ocean.theme';
+export { SunsetTheme } from './templates/themes/sunset.theme';
+export { LavenderTheme } from './templates/themes/lavender.theme';
+export { ForestTheme } from './templates/themes/forest.theme';
+export { EditorialTheme } from './templates/themes/editorial.theme';
+export { PastelTheme } from './templates/themes/pastel.theme';
+export { NeoBrutalTheme } from './templates/themes/neobrutal.theme';
+export { GlassTheme } from './templates/themes/glass.theme';
+export { MidnightTheme } from './templates/themes/midnight.theme';

package/src/providers/mailgun.transport.ts

@@ -0,0 +1,80 @@
+import { IMailgunConfig } from '../core/interfaces/email.interface';
+import { ITransportMessage, ITransportSendInfo, IEmailTransport } from './provider.interface';
+import { attachmentToBuffer, splitAddresses, validateApiConfig } from './provider-utils';
+
+export class MailgunTransport implements IEmailTransport {
+  private readonly apiUrl: string;
+  private readonly fetchImpl: typeof fetch;
+
+  constructor(private readonly config: IMailgunConfig, fetchImpl: typeof fetch = fetch) {
+    validateApiConfig(config);
+    if (!config.domain.trim() || /[\u0000-\u001f\u007f]/.test(config.domain)) {
+      throw new Error('Mailgun domain is required and must not contain control characters');
+    }
+    const defaultApiUrl = config.region === 'eu' ? 'https://api.eu.mailgun.net' : 'https://api.mailgun.net';
+    this.apiUrl = (config.apiUrl ?? defaultApiUrl).replace(/\/+$/, '');
+    const parsedUrl = new URL(this.apiUrl);
+    if (parsedUrl.protocol !== 'https:' && parsedUrl.hostname !== 'localhost' && parsedUrl.hostname !== '127.0.0.1') {
+      throw new Error('Mailgun apiUrl must use HTTPS');
+    }
+    this.fetchImpl = fetchImpl;
+  }
+
+  async sendMail(message: ITransportMessage): Promise<ITransportSendInfo> {
+    const recipients = splitAddresses(message.to);
+    if (recipients.length === 0) throw new Error('Mailgun requires at least one recipient');
+    const from = message.from ?? this.config.defaultFrom;
+    const body = new FormData();
+    body.set('from', from);
+    for (const recipient of recipients) body.append('to', recipient);
+    for (const recipient of splitAddresses(message.cc)) body.append('cc', recipient);
+    for (const recipient of splitAddresses(message.bcc)) body.append('bcc', recipient);
+    body.set('subject', message.subject);
+    if (message.text !== undefined) body.set('text', message.text);
+    if (message.text === undefined && message.html === undefined) {
+      throw new Error('Mailgun requires a text or HTML body');
+    }
+
+    let html = message.html;
+    for (const attachment of message.attachments ?? []) {
+      const data = await attachmentToBuffer(attachment, this.config.maxAttachmentBytes);
+      const file = new Blob([new Uint8Array(data)], { type: attachment.contentType ?? 'application/octet-stream' });
+      body.append(attachment.cid ? 'inline' : 'attachment', file, attachment.filename);
+      if (attachment.cid && html !== undefined) {
+        html = html.split(`cid:${attachment.cid}`).join(`cid:${attachment.filename}`);
+      }
+    }
+    if (html !== undefined) body.set('html', html);
+
+    const url = `${this.apiUrl}/v3/${encodeURIComponent(this.config.domain)}/messages`;
+    const response = await this.fetchImpl(url, {
+      method: 'POST',
+      headers: {
+        authorization: `Basic ${Buffer.from(`api:${this.config.apiKey}`).toString('base64')}`
+      },
+      body,
+      redirect: 'error',
+      signal: AbortSignal.timeout(this.config.requestTimeoutMs ?? 30_000)
+    });
+    const responseBody = await response.text();
+    if (response.status !== 200) {
+      const error = new Error(`Mailgun API returned HTTP ${response.status}${responseBody ? `: ${responseBody}` : ''}`);
+      Object.assign(error, { statusCode: response.status, responseBody });
+      throw error;
+    }
+
+    let result: { id?: string; message?: string };
+    try {
+      result = responseBody ? JSON.parse(responseBody) as { id?: string; message?: string } : {};
+    } catch {
+      throw new Error('Mailgun API returned an invalid JSON response');
+    }
+    const accepted = [...recipients, ...splitAddresses(message.cc), ...splitAddresses(message.bcc)];
+    return {
+      ...(result.id ? { messageId: result.id } : {}),
+      response: result.message ?? '200 Accepted',
+      accepted,
+      rejected: []
+    };
+  }
+}

package/src/providers/nodemailer.transport.ts

@@ -0,0 +1,20 @@
+import { Transporter } from 'nodemailer';
+import { IEmailTransport, ITransportMessage, ITransportSendInfo } from './provider.interface';
+
+export class NodemailerTransport implements IEmailTransport {
+  constructor(private readonly transporter: Transporter, private readonly closeExtra?: () => void) {}
+
+  async sendMail(message: ITransportMessage): Promise<ITransportSendInfo> {
+    const info = await this.transporter.sendMail(message as never);
+    return info as ITransportSendInfo;
+  }
+
+  verify(): Promise<true> {
+    return this.transporter.verify();
+  }
+
+  close(): void {
+    this.transporter.close();
+    this.closeExtra?.();
+  }
+}