@hed-hog/core 0.0.390 → 0.0.394

package/src/mail-delivery/mail-delivery.service.spec.ts

@@ -0,0 +1,136 @@
+import { MailDeliveryService } from './mail-delivery.service';
+
+describe('MailDeliveryService', () => {
+  let prisma: any;
+  let service: MailDeliveryService;
+
+  const messageId = '010001a0152e404c-d20f2613-b278-4738-bb2c-a5901a8e1a94-000000';
+  const mail = { timestamp: '2026-08-18T14:02:27.000Z', messageId };
+
+  beforeEach(() => {
+    prisma = {
+      mail_sent: {
+        findFirst: jest.fn().mockResolvedValue({ id: 767 }),
+        updateMany: jest.fn().mockResolvedValue({ count: 1 }),
+      },
+      mail_delivery_event: { create: jest.fn().mockResolvedValue({ id: 1 }) },
+    };
+    service = new MailDeliveryService(prisma);
+  });
+
+  it('liga o evento ao envio pelo provider_message_id', async () => {
+    const result = await service.ingestSesNotification({
+      notificationType: 'Delivery',
+      mail,
+      delivery: { recipients: ['joao@hcode.com.br'], smtpResponse: '250 ok' },
+    });
+
+    expect(prisma.mail_sent.findFirst).toHaveBeenCalledWith(
+      expect.objectContaining({ where: { provider_message_id: messageId } }),
+    );
+    expect(prisma.mail_delivery_event.create).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({
+          mail_sent_id: 767,
+          provider_message_id: messageId,
+          recipient_email: 'joao@hcode.com.br',
+          event_type: 'delivery',
+        }),
+      }),
+    );
+    expect(result).toEqual({ events: 1, stored: 1, matched: 1 });
+  });
+
+  it('grava o evento mesmo sem envio correspondente', async () => {
+    // E justamente a evidencia de que algo saiu por fora do Hub; descartar seria
+    // apagar o unico rastro.
+    prisma.mail_sent.findFirst.mockResolvedValue(null);
+
+    const result = await service.ingestSesNotification({
+      notificationType: 'Bounce',
+      mail,
+      bounce: { bouncedRecipients: [{ emailAddress: 'x@y.com' }] },
+    });
+
+    expect(prisma.mail_delivery_event.create).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({ mail_sent_id: null }),
+      }),
+    );
+    expect(result).toEqual({ events: 1, stored: 1, matched: 0 });
+  });
+
+  it('trata a reentrega do SNS como caminho normal, nao como erro', async () => {
+    prisma.mail_delivery_event.create.mockRejectedValue({ code: 'P2002' });
+
+    const result = await service.ingestSesNotification({
+      notificationType: 'Delivery',
+      mail,
+      delivery: { recipients: ['joao@hcode.com.br'] },
+    });
+
+    expect(result).toEqual({ events: 1, stored: 0, matched: 1 });
+  });
+
+  it('marca o envio como bounced', async () => {
+    await service.ingestSesNotification({
+      notificationType: 'Bounce',
+      mail,
+      bounce: {
+        bounceType: 'Permanent',
+        bouncedRecipients: [{ emailAddress: 'joao@hcode.com.br' }],
+      },
+    });
+
+    expect(prisma.mail_sent.updateMany).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({ delivery_status: 'bounced' }),
+      }),
+    );
+  });
+
+  it('so sobrescreve status mais fracos que o novo', async () => {
+    // Um Delivery atrasado nao pode apagar um Complaint: marcar como spam depois
+    // de receber e o caso comum, nao a excecao.
+    await service.ingestSesNotification({
+      notificationType: 'Delivery',
+      mail,
+      delivery: { recipients: ['joao@hcode.com.br'] },
+    });
+
+    const where = prisma.mail_sent.updateMany.mock.calls[0][0].where;
+    expect(where.OR).toEqual([
+      { delivery_status: null },
+      { delivery_status: { in: [] } },
+    ]);
+  });
+
+  it('complaint sobrescreve qualquer desfecho anterior', async () => {
+    await service.ingestSesNotification({
+      notificationType: 'Complaint',
+      mail,
+      complaint: { complainedRecipients: [{ emailAddress: 'joao@hcode.com.br' }] },
+    });
+
+    const call = prisma.mail_sent.updateMany.mock.calls[0][0];
+    expect(call.data.delivery_status).toBe('complained');
+    expect(call.where.OR[1].delivery_status.in).toEqual(
+      expect.arrayContaining(['delivered', 'bounced', 'rejected']),
+    );
+  });
+
+  it('evento que nao decide entrega nao mexe no status', async () => {
+    // Send, Open e Click dizem o que aconteceu com a mensagem, nao se ela chegou.
+    await service.ingestSesNotification({ eventType: 'Open', mail });
+
+    expect(prisma.mail_delivery_event.create).toHaveBeenCalled();
+    expect(prisma.mail_sent.updateMany).not.toHaveBeenCalled();
+  });
+
+  it('ignora notificacao irreconhecivel sem estourar', async () => {
+    const result = await service.ingestSesNotification({ foo: 'bar' });
+
+    expect(result).toEqual({ events: 0, stored: 0, matched: 0 });
+    expect(prisma.mail_delivery_event.create).not.toHaveBeenCalled();
+  });
+});

package/src/mail-delivery/mail-delivery.service.ts

@@ -0,0 +1,152 @@
+import { PrismaService } from '@hed-hog/api-prisma';
+import { Inject, Injectable, Logger, forwardRef } from '@nestjs/common';
+import {
+  MAIL_DELIVERY_EVENT_STATUS,
+  MAIL_DELIVERY_STATUS_RANK,
+} from './mail-delivery.constants';
+import { SesDeliveryEvent, parseSesNotification } from './ses-event.parser';
+
+export type MailDeliveryIngestResult = {
+  events: number;
+  stored: number;
+  matched: number;
+};
+
+/**
+ * Grava o que o provedor diz depois de aceitar a mensagem.
+ *
+ * Ate existir isto, "enviado" no log de e-mails significava apenas "o provedor
+ * aceitou". Tres mensagens do chamado 202608-000020 sairam com MessageId de
+ * sucesso do SES e nenhuma chegou a caixa alguma - e nao havia nada no Hub que
+ * pudesse mostrar isso.
+ */
+@Injectable()
+export class MailDeliveryService {
+  private readonly logger = new Logger(MailDeliveryService.name);
+
+  constructor(
+    @Inject(forwardRef(() => PrismaService))
+    private readonly prisma: PrismaService,
+  ) {}
+
+  /** Processa uma notificacao ja desembrulhada do envelope do SNS. */
+  async ingestSesNotification(payload: any): Promise<MailDeliveryIngestResult> {
+    const events = parseSesNotification(payload);
+    if (!events.length) {
+      this.logger.warn(
+        `Ignoring SES notification without a recognizable event type or messageId.`,
+      );
+      return { events: 0, stored: 0, matched: 0 };
+    }
+
+    let stored = 0;
+    let matched = 0;
+
+    for (const event of events) {
+      const mailSentId = await this.findMailSentId(event.providerMessageId);
+      if (mailSentId) matched += 1;
+
+      const created = await this.storeEvent(event, mailSentId, payload);
+      if (created) stored += 1;
+    }
+
+    // O status consolidado e por mensagem, nao por destinatario: e o que a
+    // listagem mostra numa linha so.
+    await this.applyStatus(events[0].providerMessageId, events);
+
+    return { events: events.length, stored, matched };
+  }
+
+  private async findMailSentId(providerMessageId: string): Promise<number | null> {
+    const row = await this.prisma.mail_sent.findFirst({
+      where: { provider_message_id: providerMessageId },
+      select: { id: true },
+      orderBy: { id: 'desc' },
+    });
+    return row?.id ?? null;
+  }
+
+  /**
+   * Devolve `false` quando o evento ja existia.
+   *
+   * O SNS reentrega quando a resposta demora, entao a colisao no indice de
+   * dedupe e o caminho normal - nao um erro a ser propagado.
+   */
+  private async storeEvent(
+    event: SesDeliveryEvent,
+    mailSentId: number | null,
+    payload: any,
+  ): Promise<boolean> {
+    try {
+      await this.prisma.mail_delivery_event.create({
+        data: {
+          mail_sent_id: mailSentId,
+          provider_message_id: event.providerMessageId,
+          recipient_email: event.recipientEmail,
+          event_type: event.eventType,
+          bounce_type: event.bounceType,
+          bounce_subtype: event.bounceSubtype,
+          diagnostic_code: event.diagnosticCode,
+          reporting_mta: event.reportingMta,
+          payload: payload ?? undefined,
+          occurred_at: event.occurredAt,
+        },
+      });
+
+      if (!mailSentId) {
+        // Evento de um envio que nao esta no mail_sent: guardado de proposito,
+        // porque e justamente a evidencia de que algo saiu por fora.
+        this.logger.warn(
+          `Delivery event "${event.eventType}" for unknown messageId ${event.providerMessageId}`,
+        );
+      }
+
+      return true;
+    } catch (error) {
+      if ((error as any)?.code === 'P2002') return false;
+      this.logger.error(
+        `Failed to store delivery event for ${event.providerMessageId}: ${
+          (error as Error)?.message
+        }`,
+      );
+      return false;
+    }
+  }
+
+  /**
+   * Consolida o desfecho em `mail_sent.delivery_status`.
+   *
+   * So sobe na escala: uma reclamacao que chega depois da entrega nao pode ser
+   * apagada por um `Delivery` atrasado - e o destinatario marcar como spam
+   * depois de receber e exatamente o caso comum.
+   */
+  private async applyStatus(
+    providerMessageId: string,
+    events: SesDeliveryEvent[],
+  ): Promise<void> {
+    let best: string | null = null;
+    for (const event of events) {
+      const status = MAIL_DELIVERY_EVENT_STATUS[event.eventType];
+      if (!status) continue;
+      if (!best || MAIL_DELIVERY_STATUS_RANK[status] > MAIL_DELIVERY_STATUS_RANK[best]) {
+        best = status;
+      }
+    }
+
+    // Send, Open, Click e afins nao mudam o desfecho da entrega.
+    if (!best) return;
+
+    const rank = MAIL_DELIVERY_STATUS_RANK[best];
+    const weaker = Object.entries(MAIL_DELIVERY_STATUS_RANK)
+      .filter(([, value]) => value < rank)
+      .map(([key]) => key);
+
+    await this.prisma.mail_sent.updateMany({
+      where: {
+        provider_message_id: providerMessageId,
+        OR: [{ delivery_status: null }, { delivery_status: { in: weaker } }],
+      },
+      data: { delivery_status: best, delivery_updated_at: new Date() },
+    });
+  }
+}

package/src/mail-delivery/ses-event.parser.spec.ts

@@ -0,0 +1,140 @@
+import { parseSesNotification } from './ses-event.parser';
+
+describe('parseSesNotification', () => {
+  const mail = {
+    timestamp: '2026-08-18T14:02:27.000Z',
+    messageId: '010001a0152e404c-d20f2613-b278-4738-bb2c-a5901a8e1a94-000000',
+    source: 'hcode@hcode.com.br',
+    destination: ['joao@hcode.com.br'],
+  };
+
+  it('extrai o diagnostic code de cada destinatario que voltou', () => {
+    // O diagnosticCode e a resposta literal do servidor destinatario: e ele que
+    // responde "por que nao chegou".
+    const events = parseSesNotification({
+      notificationType: 'Bounce',
+      mail,
+      bounce: {
+        bounceType: 'Permanent',
+        bounceSubType: 'General',
+        timestamp: '2026-08-18T14:02:30.000Z',
+        reportingMTA: 'dns; a8-70.smtp-out.amazonses.com',
+        bouncedRecipients: [
+          {
+            emailAddress: 'joao@hcode.com.br',
+            status: '5.1.1',
+            diagnosticCode: 'smtp; 550 5.1.1 User unknown',
+          },
+          { emailAddress: 'ronaldo@hcode.com.br', status: '5.2.2' },
+        ],
+      },
+    });
+
+    expect(events).toHaveLength(2);
+    expect(events[0]).toMatchObject({
+      providerMessageId: mail.messageId,
+      recipientEmail: 'joao@hcode.com.br',
+      eventType: 'bounce',
+      bounceType: 'Permanent',
+      bounceSubtype: 'General',
+      diagnosticCode: 'smtp; 550 5.1.1 User unknown',
+      reportingMta: 'dns; a8-70.smtp-out.amazonses.com',
+    });
+    expect(events[0].occurredAt.toISOString()).toBe('2026-08-18T14:02:30.000Z');
+    // Sem diagnosticCode, o status ainda diz alguma coisa.
+    expect(events[1].diagnosticCode).toBe('5.2.2');
+  });
+
+  it('registra o bounce mesmo sem destinatario listado', () => {
+    const events = parseSesNotification({
+      notificationType: 'Bounce',
+      mail,
+      bounce: { bounceType: 'Transient', bouncedRecipients: [] },
+    });
+
+    expect(events).toHaveLength(1);
+    expect(events[0].recipientEmail).toBeNull();
+    expect(events[0].eventType).toBe('bounce');
+  });
+
+  it('expande a entrega por destinatario e guarda a resposta SMTP', () => {
+    const events = parseSesNotification({
+      notificationType: 'Delivery',
+      mail,
+      delivery: {
+        timestamp: '2026-08-18T14:02:29.000Z',
+        recipients: ['joao@hcode.com.br', 'ronaldo@hcode.com.br'],
+        smtpResponse: '250 2.6.0 Message received',
+        reportingMTA: 'a8-70.smtp-out.amazonses.com',
+      },
+    });
+
+    expect(events.map((e) => e.recipientEmail)).toEqual([
+      'joao@hcode.com.br',
+      'ronaldo@hcode.com.br',
+    ]);
+    expect(events[0].eventType).toBe('delivery');
+    expect(events[0].diagnosticCode).toBe('250 2.6.0 Message received');
+  });
+
+  it('le a reclamacao e o tipo de feedback', () => {
+    const events = parseSesNotification({
+      notificationType: 'Complaint',
+      mail,
+      complaint: {
+        complainedRecipients: [{ emailAddress: 'joao@hcode.com.br' }],
+        complaintFeedbackType: 'abuse',
+        timestamp: '2026-08-18T15:00:00.000Z',
+      },
+    });
+
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({
+      eventType: 'complaint',
+      recipientEmail: 'joao@hcode.com.br',
+      diagnosticCode: 'abuse',
+    });
+  });
+
+  it('aceita o formato de configuration set (eventType)', () => {
+    // Qual formato chega depende de como as notificacoes foram ligadas no
+    // console da AWS - uma escolha que nem sempre e nossa.
+    const events = parseSesNotification({
+      eventType: 'Reject',
+      mail,
+      reject: { reason: 'Bad content' },
+    });
+
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({
+      eventType: 'reject',
+      recipientEmail: 'joao@hcode.com.br',
+      diagnosticCode: 'Bad content',
+    });
+  });
+
+  it('guarda um tipo desconhecido em vez de descartar', () => {
+    const events = parseSesNotification({ eventType: 'DeliveryDelay', mail });
+
+    expect(events).toHaveLength(1);
+    expect(events[0].eventType).toBe('deliverydelay');
+  });
+
+  it('ignora payload sem tipo ou sem messageId', () => {
+    expect(parseSesNotification({ mail })).toEqual([]);
+    expect(parseSesNotification({ notificationType: 'Bounce', mail: {} })).toEqual([]);
+    expect(parseSesNotification(null)).toEqual([]);
+  });
+
+  it('nao produz Invalid Date quando o timestamp vem quebrado', () => {
+    // occurred_at e NOT NULL e entra na chave de dedupe: um Invalid Date
+    // derrubaria a ingestao do lote inteiro.
+    const events = parseSesNotification({
+      notificationType: 'Delivery',
+      mail: { ...mail, timestamp: 'nao e data' },
+      delivery: { recipients: ['joao@hcode.com.br'] },
+    });
+
+    expect(Number.isNaN(events[0].occurredAt.getTime())).toBe(false);
+  });
+});

package/src/mail-delivery/ses-event.parser.ts

@@ -0,0 +1,191 @@
+/**
+ * Um evento de entrega ja normalizado, independente do formato em que o SES o
+ * enviou.
+ */
+export type SesDeliveryEvent = {
+  providerMessageId: string;
+  recipientEmail: string | null;
+  /** minusculo: delivery | bounce | complaint | reject | send | open | click | ... */
+  eventType: string;
+  bounceType: string | null;
+  bounceSubtype: string | null;
+  diagnosticCode: string | null;
+  reportingMta: string | null;
+  occurredAt: Date;
+};
+
+/**
+ * O SES publica o mesmo fato em dois formatos, e qual deles chega depende de
+ * como as notificacoes foram ligadas:
+ *
+ *   - notificacoes por identidade (o caminho simples): `notificationType`
+ *   - configuration set com event destination: `eventType`
+ *
+ * Suportar os dois e barato e evita que a escolha feita no console da AWS - que
+ * nem sempre e nossa - quebre a ingestao.
+ */
+export function parseSesNotification(payload: any): SesDeliveryEvent[] {
+  const rawType = String(payload?.notificationType ?? payload?.eventType ?? '').trim();
+  if (!rawType) return [];
+
+  const providerMessageId = String(payload?.mail?.messageId ?? '').trim();
+  if (!providerMessageId) return [];
+
+  const type = rawType.toLowerCase();
+  const mailTimestamp = payload?.mail?.timestamp;
+
+  switch (type) {
+    case 'bounce': {
+      const bounce = payload.bounce ?? {};
+      const recipients = Array.isArray(bounce.bouncedRecipients)
+        ? bounce.bouncedRecipients
+        : [];
+      const occurredAt = toDate(bounce.timestamp ?? mailTimestamp);
+
+      // Um bounce sem destinatario listado ainda e um bounce: registrar sem
+      // e-mail e melhor que descartar a unica evidencia de que a mensagem voltou.
+      if (!recipients.length) {
+        return [
+          {
+            providerMessageId,
+            recipientEmail: null,
+            eventType: type,
+            bounceType: str(bounce.bounceType),
+            bounceSubtype: str(bounce.bounceSubType),
+            diagnosticCode: null,
+            reportingMta: str(bounce.reportingMTA),
+            occurredAt,
+          },
+        ];
+      }
+
+      return recipients.map((recipient: any) => ({
+        providerMessageId,
+        recipientEmail: str(recipient?.emailAddress),
+        eventType: type,
+        bounceType: str(bounce.bounceType),
+        bounceSubtype: str(bounce.bounceSubType),
+        // A resposta literal do servidor destinatario - o campo que responde
+        // "por que nao chegou".
+        diagnosticCode: str(recipient?.diagnosticCode) ?? str(recipient?.status),
+        reportingMta: str(bounce.reportingMTA),
+        occurredAt,
+      }));
+    }
+
+    case 'complaint': {
+      const complaint = payload.complaint ?? {};
+      const recipients = Array.isArray(complaint.complainedRecipients)
+        ? complaint.complainedRecipients
+        : [];
+      const occurredAt = toDate(complaint.timestamp ?? mailTimestamp);
+      const feedback = str(complaint.complaintFeedbackType);
+
+      if (!recipients.length) {
+        return [
+          buildSimple(providerMessageId, null, type, occurredAt, feedback, null),
+        ];
+      }
+
+      return recipients.map((recipient: any) =>
+        buildSimple(
+          providerMessageId,
+          str(recipient?.emailAddress),
+          type,
+          occurredAt,
+          feedback,
+          null,
+        ),
+      );
+    }
+
+    case 'delivery': {
+      const delivery = payload.delivery ?? {};
+      const recipients = Array.isArray(delivery.recipients) ? delivery.recipients : [];
+      const occurredAt = toDate(delivery.timestamp ?? mailTimestamp);
+
+      if (!recipients.length) {
+        return [
+          buildSimple(
+            providerMessageId,
+            null,
+            type,
+            occurredAt,
+            str(delivery.smtpResponse),
+            str(delivery.reportingMTA),
+          ),
+        ];
+      }
+
+      return recipients.map((recipient: any) =>
+        buildSimple(
+          providerMessageId,
+          str(recipient),
+          type,
+          occurredAt,
+          str(delivery.smtpResponse),
+          str(delivery.reportingMTA),
+        ),
+      );
+    }
+
+    default: {
+      // Send, Reject, Open, Click, DeliveryDelay, RenderingFailure e o que a AWS
+      // acrescentar depois. Guardar o desconhecido e o que faz um tipo novo
+      // aparecer no log em vez de sumir.
+      const destinations = Array.isArray(payload?.mail?.destination)
+        ? payload.mail.destination
+        : [];
+      const occurredAt = toDate(mailTimestamp);
+      const detail =
+        str(payload?.reject?.reason) ??
+        str(payload?.failure?.errorMessage) ??
+        str(payload?.deliveryDelay?.delayType);
+
+      if (!destinations.length) {
+        return [
+          buildSimple(providerMessageId, null, type, occurredAt, detail, null),
+        ];
+      }
+
+      return destinations.map((address: any) =>
+        buildSimple(providerMessageId, str(address), type, occurredAt, detail, null),
+      );
+    }
+  }
+}
+
+function buildSimple(
+  providerMessageId: string,
+  recipientEmail: string | null,
+  eventType: string,
+  occurredAt: Date,
+  diagnosticCode: string | null,
+  reportingMta: string | null,
+): SesDeliveryEvent {
+  return {
+    providerMessageId,
+    recipientEmail,
+    eventType,
+    bounceType: null,
+    bounceSubtype: null,
+    diagnosticCode,
+    reportingMta,
+    occurredAt,
+  };
+}
+
+function str(value: unknown): string | null {
+  const text = String(value ?? '').trim();
+  return text || null;
+}
+
+/**
+ * Data do provedor. Cai para agora quando o timestamp vem ausente ou invalido -
+ * a coluna e NOT NULL e faz parte da chave de dedupe, entao um `Invalid Date`
+ * derrubaria a ingestao inteira do lote.
+ */
+function toDate(value: unknown): Date {
+  const parsed = new Date(String(value ?? ''));
+  return Number.isNaN(parsed.getTime()) ? new Date() : parsed;
+}