email-mailtrap

Imported from JoyanLabs/template-nestjs-dashboard-better_auth (skills/email-mailtrap/SKILL.md). Install upstream with npx skills add JoyanLabs/template-nestjs-dashboard-better_auth --skill email-mailtrap. Copyright stays with the author (MIT).

Arquitectura: Ports & Adapters

El servicio de notificaciones sigue el patrón Ports & Adapters:

┌─────────────────────────────────────┐
│  CAPA DE APLICACIÓN                 │
│  - Handlers usan INotificationService│
│  - No conocen Mailtrap              │
└──────────────┬──────────────────────┘
               │ Inyección de dependencias
┌──────────────▼──────────────────────┐
│  PUERTO: INotificationService       │
│  - Interfaz (contrato)              │
│  - Define sendEmail()               │
└──────────────┬──────────────────────┘
               │ Implementación
┌──────────────▼──────────────────────┐
│  ADAPTADOR: MailtrapAdapter         │
│  - Implementa INotificationService  │
│  - Usa Mailtrap SDK                 │
└─────────────────────────────────────┘

Ubicación de archivos:

src/shared/
├── application/ports/
│   └── notification-service.port.ts   # Puerto (interfaz)
└── infrastructure/adapters/
    └── mailtrap.adapter.ts            # Adaptador (Mailtrap)

Critical Patterns

1. Puerto (Interfaz)

// shared/application/ports/notification-service.port.ts
export interface INotificationService {
  sendEmail(params: SendEmailParams): Promise<EmailResult>;
}

export const NOTIFICATION_SERVICE = Symbol('NOTIFICATION_SERVICE');

export interface SendEmailParams {
  to: string;
  subject: string;
  html: string;
  text?: string;
}

2. Adaptador (Implementación)

// shared/infrastructure/adapters/mailtrap.adapter.ts
@Injectable()
export class MailtrapAdapter implements INotificationService {
  private client: MailtrapClient;

  constructor(config: { apiToken: string; senderEmail: string }) {
    this.client = new MailtrapClient({ token: config.apiToken });
  }

  async sendEmail(params: SendEmailParams): Promise<EmailResult> {
    const response = await this.client.send({
      from: { email: this.senderEmail },
      to: [{ email: params.to }],
      subject: params.subject,
      html: params.html,
    });

    return {
      success: true,
      messageId: String(response.message_ids?.[0]),
      provider: 'mailtrap',
    };
  }
}

3. Uso en Handlers (Inyección)

// En un handler CQRS
import { Inject } from '@nestjs/common';
import { CommandHandler, ICommandHandler } from '@nestjs/cqrs';
import {
  NOTIFICATION_SERVICE,
  INotificationService,
} from '@/shared/application/ports/notification-service.port.js';

@CommandHandler(CreateUserCommand)
export class CreateUserHandler implements ICommandHandler<CreateUserCommand> {
  constructor(
    @Inject(NOTIFICATION_SERVICE)
    private readonly notificationService: INotificationService,
  ) {}

  async execute(command: CreateUserCommand) {
    // Crear usuario...
    
    // Enviar email usando el puerto (no Mailtrap directamente)
    await this.notificationService.sendEmail({
      to: command.email,
      subject: 'Bienvenido a nuestra plataforma',
      html: welcomeTemplate({ name: command.name }),
    });
  }
}

4. Configuración en Módulo

// shared/shared.module.ts o app.module.ts
import { Module } from '@nestjs/common';
import { NOTIFICATION_SERVICE } from './application/ports/notification-service.port.js';
import { MailtrapAdapter } from './infrastructure/adapters/mailtrap.adapter.js';

@Module({
  providers: [
    {
      provide: NOTIFICATION_SERVICE,
      useFactory: () => {
        return new MailtrapAdapter({
          apiToken: process.env.MAILTRAP_API_TOKEN!,
          senderEmail: process.env.MAILTRAP_SENDER_EMAIL || 'hello@example.com',
        });
      },
    },
  ],
  exports: [NOTIFICATION_SERVICE],
})
export class SharedModule {}

5. Templates de Email

Los templates se mantienen en shared/infrastructure/email/email.templates.ts:

// email.templates.ts
export interface WelcomeData {
  name: string;
  resetUrl: string;
  appName?: string;
}

export function welcomeTemplate(data: WelcomeData): string {
  const { name, resetUrl, appName = 'Tu Aplicación' } = data;
  
  return `
    <!DOCTYPE html>
    <html>
      <head>
        <meta charset="utf-8">
        <title>Bienvenido</title>
      </head>
      <body style="font-family: Arial, sans-serif; max-width: 600px; margin: 0 auto;">
        <h1>Hola ${name},</h1>
        <p>Bienvenido a ${appName}.</p>
        <p>
          <a href="${resetUrl}" style="background: #007bff; color: white; padding: 10px 20px; text-decoration: none; border-radius: 5px;">
            Configurar cuenta
          </a>
        </p>
      </body>
    </html>
  `;
}

Agregar Nuevo Template

1. Crear interfaz y función en email.templates.ts:

interface PasswordResetData {
  name: string;
  resetUrl: string;
  expiresIn: string;
}

export function passwordResetTemplate(data: PasswordResetData): string {
  return `
    <!DOCTYPE html>
    <html>
      <body>
        <h1>Hola ${data.name}</h1>
        <p>Has solicitado restablecer tu contraseña.</p>
        <a href="${data.resetUrl}">Restablecer contraseña</a>
        <p>Este enlace expira en ${data.expiresIn}.</p>
      </body>
    </html>
  `;
}

2. Exportar en index.ts:

export { welcomeTemplate, passwordResetTemplate } from './email.templates.js';

3. Usar en handler:

await this.notificationService.sendEmail({
  to: user.email,
  subject: 'Restablecer contraseña',
  html: passwordResetTemplate({
    name: user.name,
    resetUrl: generateResetUrl(user.email),
    expiresIn: '24 horas',
  }),
});

Envío Asíncrono con Inngest

Recomendado: Usar Inngest para envío de emails en background:

// Función Inngest
export const createUserOnboardingFn = ({
  notificationService,
  logger,
}: Deps) =>
  inngest.createFunction(
    { id: 'user-onboarding' },
    { event: 'user/created' },
    async ({ event, step }) => {
      const { email, name } = event.data;

      // Step con reintentos automáticos
      await step.run('send-welcome-email', async () => {
        return notificationService.sendEmail({
          to: email,
          subject: 'Bienvenido a nuestra plataforma',
          html: welcomeTemplate({ name, resetUrl: generateUrl(email) }),
        });
      });
    },
  );

Ventajas:

• ✅ Reintentos automáticos si falla Mailtrap
• ✅ No bloquea la respuesta HTTP
• ✅ Observabilidad en dashboard de Inngest
• ✅ Desacoplamiento completo

Modos de Operación

Sandbox (Desarrollo)

Los emails NO se envían realmente, se capturan en Mailtrap:

MAILTRAP_SANDBOX=true

Ver emails en: https://mailtrap.io/inboxes

Producción

Los emails se envían realmente:

MAILTRAP_SANDBOX=false
MAILTRAP_SENDER_EMAIL=noreply@tudominio.com

Requisitos:

• Dominio verificado en Mailtrap
• Email de remitente del dominio verificado

Variables de Entorno

# Requerido
MAILTRAP_API_TOKEN=tu-api-token

# Remitente
MAILTRAP_SENDER_EMAIL=hello@demomailtrap.com
MAILTRAP_SENDER_NAME=Tu Aplicación

# Modo
MAILTRAP_SANDBOX=true

# Opcional (para sandbox)
MAILTRAP_INBOX_ID=tu-inbox-id

Decision Tree

¿Necesitas enviar emails?
│
├─ ¿Es parte de un flujo de negocio (ej: onboarding)?
│  ├─ SÍ: ¿Puede fallar sin afectar la operación principal?
│  │  ├─ SÍ: Usar Inngest (recomendado)
│  │  │        → Inyectar notificationService
│  │  │        → Usar step.run() para reintentos
│  │  └─ NO: Usar puerto directamente en handler
│  │
│  └─ NO: Usar puerto directamente (respuesta inmediata)
│
└─ ¿Es un template nuevo?
   ├─ SÍ: Crear en email.templates.ts
   │        → Exportar en index.ts
   │        → Usar en handler
   └─ NO: Usar template existente

¿Qué template usar?
├── Usuario nuevo (admin crea)     → welcomeTemplate
├── Restablecer contraseña         → passwordResetTemplate
├── Notificación genérica          → Crear nuevo template

Testing con Mocks

El patrón Ports & Adapters facilita testing:

// Test unitario
import { Test } from '@nestjs/testing';
import { CreateUserHandler } from './create-user.handler';
import {
  NOTIFICATION_SERVICE,
  INotificationService,
} from '@/shared/application/ports/notification-service.port.js';

describe('CreateUserHandler', () => {
  let handler: CreateUserHandler;
  let mockNotificationService: jest.Mocked<INotificationService>;

  beforeEach(async () => {
    mockNotificationService = {
      sendEmail: jest.fn().mockResolvedValue({
        success: true,
        messageId: 'test-123',
        provider: 'mock',
      }),
    } as unknown as jest.Mocked<INotificationService>;

    const module = await Test.createTestingModule({
      providers: [
        CreateUserHandler,
        {
          provide: NOTIFICATION_SERVICE,
          useValue: mockNotificationService,
        },
      ],
    }).compile();

    handler = module.get<CreateUserHandler>(CreateUserHandler);
  });

  it('should send welcome email', async () => {
    await handler.execute(command);

    expect(mockNotificationService.sendEmail).toHaveBeenCalledWith({
      to: command.email,
      subject: expect.any(String),
      html: expect.any(String),
    });
  });
});

Troubleshooting

Cambiar de Proveedor

El patrón Ports & Adapters permite cambiar fácilmente de Mailtrap a otro proveedor:

// Crear nuevo adaptador
@Injectable()
export class SESAdapter implements INotificationService {
  async sendEmail(params: SendEmailParams): Promise<EmailResult> {
    // Implementación con AWS SES
    return { success: true, provider: 'ses' };
  }
}

// Cambiar en configuración
{
  provide: NOTIFICATION_SERVICE,
  useClass: process.env.NODE_ENV === 'production' 
    ? SESAdapter 
    : MailtrapAdapter,
}

No es necesario modificar handlers - solo cambiar el adaptador en el módulo.

Resources

Documentación Relacionada

• NestJS: Ver guía de arquitectura hexagonal y CQRS
• Inngest Integration: Tareas asíncronas y eventos
• Arquitectura Hexagonal: Visión general del patrón

Dependencias

La skill requiere que mailtrap esté instalado:

npm install mailtrap

Skills Relacionados

• nestjs - CQRS y arquitectura hexagonal
• documentation - Crear documentación