@hed-hog/core 0.0.390 → 0.0.393

package/src/mail/mail.service.ts

@@ -1,6 +1,13 @@
 import { DeleteDTO } from '@hed-hog/api';
-import { getLocaleText, LocaleService } from '@hed-hog/api-locale';
 import {
+  getLocaleText,
+  isLocaleDetectedFromContext,
+  LocaleService,
+  normalizeLocaleCode,
+} from '@hed-hog/api-locale';
+import {
+  DEFAULT_PRIMARY_COLOR,
+  DEFAULT_PRIMARY_FOREGROUND,
   MailLayout,
   MailService as MailMainService,
   renderMailTemplate,
@@ -20,17 +27,21 @@ import * as Handlebars from 'handlebars';
 import {
   buildMailConfigFromIntegration,
   getFromAddress,
+  getReplyToAddress,
 } from '../integration-profile/integration-profile.utils';
 import { IntegrationDeveloperApiService } from '../integration/services/integration-developer-api.service';
+import { BrandAssetService } from '../setting/brand-asset.service';
 import { SettingService } from '../setting/setting.service';
 import { CreateDTO } from './dto/create.dto';
 import { ImportDTO } from './dto/import.dto';
 import { PreviewDTO } from './dto/preview.dto';
-import { SendTemplatedMailDTO } from './dto/send.dto';
+import { SendTemplatedMailDTO, SendTemplatedMailResult } from './dto/send.dto';
 import { TestMailDTO } from './dto/test-mail.dto';
 import { UpdateDTO } from './dto/update.dto';
 import { IncidentService } from '../incident/incident.service';
 
+export type { SendTemplatedMailResult } from './dto/send.dto';
+
 @Injectable()
 export class MailService implements OnModuleInit {
   private readonly logger = new Logger(MailService.name);
@@ -51,6 +62,8 @@ export class MailService implements OnModuleInit {
     private readonly integrationApi: IntegrationDeveloperApiService,
     @Inject(forwardRef(() => IncidentService))
     private readonly incident: IncidentService,
+    @Inject(forwardRef(() => BrandAssetService))
+    private readonly brandAsset: BrandAssetService,
   ) { }
 
   onModuleInit(): void {
@@ -61,6 +74,13 @@ export class MailService implements OnModuleInit {
       handler: async (event) => {
         const slug = String(event.payload?.slug || '').trim();
 
+        // O layout resolvido (logo, cores, nome) fica ate 60s em cache no
+        // api-mail. Sem descartar aqui, "subi o logo e mandei um teste" - o
+        // fluxo natural de validacao - mostraria o valor antigo.
+        if (MailService.BRAND_SLUGS.has(slug)) {
+          this.mailMainService.invalidateLayoutCache();
+        }
+
         if (!this.isMailConfigSlug(slug)) {
           return;
         }
@@ -71,6 +91,16 @@ export class MailService implements OnModuleInit {
 
   }
 
+  /** Settings que compoem o cabecalho do e-mail resolvido em `resolveLayout`. */
+  private static readonly BRAND_SLUGS = new Set([
+    'image-url',
+    'url',
+    'api-url',
+    'system-name',
+    'theme-primary-light',
+    'theme-primary-foreground-light',
+  ]);
+
   private isMailConfigSlug(slug: string) {
     return slug === this.integrationProfileSettingSlug;
   }
@@ -79,6 +109,29 @@ export class MailService implements OnModuleInit {
     return value === true || value === 'true';
   }
 
+  /**
+   * Cor de marca (`theme-primary-light`) e seu contraste (`theme-primary-foreground-light`),
+   * disponibilizadas como `{{primaryColor}}`/`{{primaryForeground}}` no corpo Handlebars dos
+   * templates (ex.: o botao de CTA de um convite) e no layout base do e-mail.
+   */
+  private async getThemeVariables(): Promise<{
+    primaryColor: string;
+    primaryForeground: string;
+  }> {
+    const settings = await this.setting.getSettingValues([
+      'theme-primary-light',
+      'theme-primary-foreground-light',
+    ]);
+
+    return {
+      primaryColor:
+        (settings['theme-primary-light'] as string) || DEFAULT_PRIMARY_COLOR,
+      primaryForeground:
+        (settings['theme-primary-foreground-light'] as string) ||
+        DEFAULT_PRIMARY_FOREGROUND,
+    };
+  }
+
   private async syncConfiguredMailFlag() {
     try {
       const settings = await this.setting.getSettingValues([
@@ -117,7 +170,7 @@ export class MailService implements OnModuleInit {
     * Otherwise the global integration profile setting is read.
    * Returns the active from address and the built config object.
    */
-  async reloadConfig(profileSlug?: string): Promise<{ success: boolean; provider: string; from: string; config: any }> {
+  async reloadConfig(profileSlug?: string): Promise<{ success: boolean; provider: string; from: string; replyTo?: string; config: any }> {
     try {
       let resolvedProfileSlug = String(profileSlug ?? '').trim();
 
@@ -159,8 +212,9 @@ export class MailService implements OnModuleInit {
       this.logger.log(`Mail configuration reloaded from profile "${profile.name}" (${providerSlug})`);
 
       const from = getFromAddress(profile.config);
+      const replyTo = getReplyToAddress(profile.config);
 
-      return { success: true, provider: providerSlug, from, config };
+      return { success: true, provider: providerSlug, from, replyTo, config };
     } catch (error) {
       this.logger.error('Error reloading mail configuration:', error);
       throw error;
@@ -395,10 +449,17 @@ export class MailService implements OnModuleInit {
     });
   }
 
+  /**
+   * Continua sem lancar: ha dezenas de call sites que disparam e-mail sem
+   * `await`, e transformar isto em excecao derrubaria fluxos que hoje so perdem
+   * a notificacao. O que muda e o *retorno* - quem se importa (a fila do SAC,
+   * por exemplo) agora consegue distinguir enviado de engolido, em vez de
+   * assumir sucesso porque a promise resolveu.
+   */
   async sendTemplatedMail(
     locale: string,
-    { email, slug, variables, profileSlug, app }: SendTemplatedMailDTO,
-  ) {
+    { email, slug, variables, profileSlug, replyTo, app, userId }: SendTemplatedMailDTO,
+  ): Promise<SendTemplatedMailResult> {
     const settings = await this.setting.getSettingValues(['configured-mail']);
 
     if (!this.isSettingEnabled(settings['configured-mail'])) {
@@ -412,29 +473,67 @@ export class MailService implements OnModuleInit {
         message: 'Envio de e-mail abortado: a configuracao de e-mail nao esta ativa.',
         context: { slug },
       });
-      return;
+      return { sent: false, reason: 'mail-not-configured' };
     }
 
     try {
-      const { from } = await this.reloadConfig(profileSlug);
-      const localeRecord = await this.getLocaleRecord(locale);
-      const mail = await this.getMailTemplate(slug, localeRecord.id);
-      const { subject, body } = mail.mail_locale[0];
-      const brandName = await this.mailMainService.getBrandName(app, locale);
-      const mergedVariables = { brandName, ...variables };
+      // O `replyTo` do perfil de integracao entra como padrao para que a
+      // resposta de quem trata o e-mail transacional como conversa caia numa
+      // caixa monitorada, e nao no remetente. Quem passa `replyTo` no DTO
+      // continua mandando.
+      const { from, replyTo: profileReplyTo } = await this.reloadConfig(profileSlug);
+      const resolvedReplyTo = replyTo?.trim() || profileReplyTo;
+      const recipientLocale = await this.resolveRecipientLocale(email, locale, userId);
+      const mail = await this.getMailTemplate(slug);
+      const translation = this.pickTranslation(mail, recipientLocale);
+
+      if (!translation) {
+        // Antes isto era um TypeError em `mail_locale[0]`, engolido pelo catch
+        // abaixo e reportado como `send-failed` - um template sem traducao
+        // nenhuma parecia falha do provedor.
+        this.logger.error(`Template "${slug}" has no translation available.`);
+        this.incident.record({
+          source: 'core.mail',
+          code: 'mail_template_no_locale',
+          severity: 'critical',
+          message: `Template "${slug}" nao tem nenhuma traducao cadastrada.`,
+          key: slug,
+          context: { slug, locale: recipientLocale },
+        });
+
+        return { sent: false, reason: 'template-locale-missing' };
+      }
+
+      const { subject, body, code: templateLocale } = translation;
+      const brandName = await this.mailMainService.getBrandName(app, templateLocale);
+      const { primaryColor, primaryForeground } = await this.getThemeVariables();
+      const mergedVariables = { brandName, primaryColor, primaryForeground, ...variables };
       const parsedSubject = this.interpolateTemplate(subject, mergedVariables);
       const parsedBody = this.interpolateTemplate(body, mergedVariables);
 
-      await this.mailMainService.send({
+      const sendResult: any = await this.mailMainService.send({
         to: email,
         from,
+        ...(resolvedReplyTo ? { replyTo: resolvedReplyTo } : {}),
         subject: parsedSubject,
         body: parsedBody,
         mail_id: mail.id,
-        locale,
+        // O layout (header/footer) e escolhido por este locale la no api-mail,
+        // entao tem que ser o do template escolhido, nao o cru do request.
+        locale: templateLocale,
         app,
       });
 
+      const providerMessageId =
+        sendResult?.result?.MessageId ??
+        sendResult?.result?.messageId ??
+        sendResult?.result?.data?.id ??
+        null;
+
+      return {
+        sent: true,
+        providerMessageId: providerMessageId ? String(providerMessageId) : null,
+      };
     } catch (error) {
       this.logger.error('Error sending templated mail:', error);
       // Agrupado por slug: um template quebrado vira um incidente com contador,
@@ -446,28 +545,109 @@ export class MailService implements OnModuleInit {
         key: slug,
         context: { slug, locale },
       });
+
+      return {
+        sent: false,
+        reason: 'send-failed',
+        error: error instanceof Error ? error.message : String(error),
+      };
     }
   }
 
-  private async getLocaleRecord(locale: string) {
-    const localeRecord = await this.prismaService.locale.findUnique({
-      where: { code: locale },
+  /**
+   * Idioma em que ESTE destinatario deve receber o e-mail.
+   *
+   * Publico porque quem pre-formata variaveis antes de enviar (data e pais do
+   * alerta de seguranca) precisa do mesmo idioma que o corpo, senao o texto sai
+   * em portugues com a data em ingles. E idempotente: chamar aqui e passar o
+   * resultado como `locale` no envio da no mesmo lugar.
+   *
+   * Ordem:
+   *   1. preferencia gravada do destinatario  - escolha explicita sempre vence;
+   *   2. locale do chamador, se o cliente realmente declarou um idioma;
+   *   3. setting global `language`;
+   *   4. `en`.
+   */
+  async resolveRecipientLocale(
+    email: string,
+    callerLocale?: string | null,
+    userId?: number,
+  ): Promise<string> {
+    try {
+      const recipientId = userId ?? (await this.findUserIdByEmail(email));
+      const resolved = await this.setting.resolveUserLocale(recipientId);
+
+      // A cadeia do `SettingService` usa o locale do CONTEXTO da requisicao.
+      // Quase sempre e o mesmo que chegou aqui, mas ha envios fora de request
+      // (fila, cron) e chamadores que passam um locale proprio: nesses, o
+      // `callerLocale` e a unica pista que existe.
+      if (resolved !== 'en') {
+        return resolved;
+      }
+
+      return normalizeLocaleCode(callerLocale) ?? resolved;
+    } catch (error) {
+      this.logger.warn(
+        `Falling back to caller locale while resolving recipient language: ${error}`,
+      );
+
+      return normalizeLocaleCode(callerLocale) ?? 'en';
+    }
+  }
+
+  /** `user_identifier` tem unique (type, value), entao e busca por indice. */
+  private async findUserIdByEmail(email: string): Promise<number | null> {
+    const value = String(email ?? '').trim();
+
+    if (!value) {
+      return null;
+    }
+
+    const identifier = await this.prismaService.user_identifier.findFirst({
+      where: { type: 'email', value },
+      select: { user_id: true },
     });
 
-    if (!localeRecord) {
-      throw new Error(`Locale "${locale}" not found`);
+    return identifier?.user_id ?? null;
+  }
+
+  /**
+   * Escolhe a traducao do template, caindo para o que existir.
+   *
+   * O filtro por locale ficava na propria query e `mail_locale[0]` era acessado
+   * sem checagem: template sem a traducao pedida virava TypeError silencioso.
+   * Trazendo todas as traducoes numa query so, a escolha vira decisao explicita
+   * - e o `locale.findUnique` que estourava com `pt-BR` deixa de ser preciso.
+   */
+  private pickTranslation(mail: any, requested: string) {
+    const translations = (mail?.mail_locale ?? [])
+      .map((item: any) => ({
+        subject: item?.subject,
+        body: item?.body,
+        code: item?.locale?.code,
+      }))
+      .filter((item: any) => item.code && item.subject != null && item.body != null);
+
+    if (!translations.length) {
+      return null;
     }
 
-    return localeRecord;
+    const byCode = (code: string) =>
+      translations.find((item: any) => item.code === code);
+
+    return byCode(requested) ?? byCode('pt') ?? byCode('en') ?? translations[0];
   }
 
-  private async getMailTemplate(slug: string, localeId: number) {
+  private async getMailTemplate(slug: string) {
     const mail = await this.prismaService.mail.findUnique({
       where: { slug },
       include: {
         mail_locale: {
-          where: { locale_id: localeId },
-          select: { subject: true, body: true },
+          select: {
+            subject: true,
+            body: true,
+            locale: { select: { code: true } },
+          },
         },
         mail_var: {
           select: { name: true },
@@ -476,7 +656,7 @@ export class MailService implements OnModuleInit {
     });
 
     if (!mail) {
-      throw new Error(`Template "${slug}" not found for locale "${localeId}"`);
+      throw new Error(`Template "${slug}" not found`);
     }
 
     return mail;
@@ -544,9 +724,23 @@ export class MailService implements OnModuleInit {
     locale: string,
     { subject, body, variables, use_layout, layout }: PreviewDTO,
   ): Promise<{ html: string }> {
-    const settings = await this.setting.getSettingValues(['system-name']);
+    const settings = await this.setting.getSettingValues([
+      'system-name',
+      'theme-primary-light',
+      'theme-primary-foreground-light',
+      'image-url',
+    ]);
     const brandName = settings['system-name'] as string;
-    const data = { brandName, ...(variables || {}) };
+    const primaryColor =
+      (settings['theme-primary-light'] as string) || DEFAULT_PRIMARY_COLOR;
+    const primaryForeground =
+      (settings['theme-primary-foreground-light'] as string) ||
+      DEFAULT_PRIMARY_FOREGROUND;
+    const rawLogoUrl = settings['image-url'] as string;
+    const logoUrl = rawLogoUrl
+      ? (await this.brandAsset.resolveAssetUrl(rawLogoUrl)) || undefined
+      : undefined;
+    const data = { brandName, primaryColor, primaryForeground, ...(variables || {}) };
     const parsedSubject = subject ? this.interpolateTemplate(subject, data) : '';
     const parsedBody = body ? this.interpolateTemplate(body, data) : '';
 
@@ -569,6 +763,9 @@ export class MailService implements OnModuleInit {
       // devolver o corpo cru.
       layout: use_layout === false ? { wrapper: '' } : resolvedLayout,
       brandName,
+      primaryColor,
+      primaryForeground,
+      logoUrl,
       lang: locale,
     });
 
@@ -582,8 +779,7 @@ export class MailService implements OnModuleInit {
     body,
     variables,
   }: TestMailDTO) {
-    const localeRecord = await this.getLocaleRecord(locale);
-    const mail = await this.getMailTemplate(slug, localeRecord.id);
+    const mail = await this.getMailTemplate(slug);
     const settings = await this.setting.getSettingValues(['configured-mail']);
 
     if (!this.isSettingEnabled(settings['configured-mail'])) {
@@ -594,7 +790,8 @@ export class MailService implements OnModuleInit {
 
     try {
       const brandName = await this.mailMainService.getBrandName(undefined, locale);
-      const mergedVariables = { brandName, ...(variables || {}) };
+      const { primaryColor, primaryForeground } = await this.getThemeVariables();
+      const mergedVariables = { brandName, primaryColor, primaryForeground, ...(variables || {}) };
       const parsedSubject = this.interpolateTemplate(subject, mergedVariables);
       const parsedBody = this.interpolateTemplate(body, mergedVariables);
 

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

@@ -0,0 +1,66 @@
+import { PrismaService } from '@hed-hog/api-prisma';
+import {
+  BadRequestException,
+  Inject,
+  Injectable,
+  forwardRef,
+} from '@nestjs/common';
+import { WebhookIntegrationService } from '../webhook-integration/webhook-integration.service';
+import {
+  SES_DELIVERY_WEBHOOK_PROTOCOL,
+  SES_PROVIDER_SLUG,
+  SES_WEBHOOK_SLUG_PREFIX,
+} from './mail-delivery.constants';
+
+export type SesWebhookInfo = {
+  /** URL para assinar no topico SNS (subscription HTTPS). */
+  publicUrl: string | null;
+  publicUuid: string;
+  webhookIntegrationId: number;
+};
+
+/**
+ * Provisiona o webhook que recebe os eventos de entrega de um perfil SES.
+ *
+ * Idempotente: a chave e (protocol, integration_profile_id), entao chamar de
+ * novo devolve o mesmo UUID - e a URL ja assinada no topico SNS continua valida.
+ */
+@Injectable()
+export class MailDeliveryProvisionService {
+  constructor(
+    @Inject(forwardRef(() => PrismaService))
+    private readonly prisma: PrismaService,
+    private readonly webhookIntegration: WebhookIntegrationService,
+  ) {}
+
+  async provision(integrationProfileId: number): Promise<SesWebhookInfo> {
+    const profile = await this.prisma.integration_profile.findFirst({
+      where: {
+        id: integrationProfileId,
+        integration_provider: { slug: SES_PROVIDER_SLUG },
+      },
+      select: { id: true, slug: true, name: true },
+    });
+
+    if (!profile) {
+      throw new BadRequestException(
+        `Integration profile ${integrationProfileId} is not a "${SES_PROVIDER_SLUG}" profile.`,
+      );
+    }
+
+    const webhook = await this.webhookIntegration.provisionProtocolWebhook({
+      slug: `${SES_WEBHOOK_SLUG_PREFIX}-${profile.slug}`,
+      name: `SES — entrega (${profile.name})`,
+      description:
+        'Recebe bounce, complaint e delivery do Amazon SES. A URL vai numa subscription HTTPS do tópico SNS configurado nas notificações da identidade.',
+      protocol: SES_DELIVERY_WEBHOOK_PROTOCOL,
+      integrationProfileId: profile.id,
+    });
+
+    return {
+      publicUrl: webhook.public_url ?? null,
+      publicUuid: webhook.public_uuid,
+      webhookIntegrationId: webhook.id,
+    };
+  }
+}

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

@@ -0,0 +1,31 @@
+/** Protocolo do adaptador registrado no WebhookProtocolRegistry. */
+export const SES_DELIVERY_WEBHOOK_PROTOCOL = 'aws-ses';
+
+/** Prefixo do slug do webhook provisionado por perfil. */
+export const SES_WEBHOOK_SLUG_PREFIX = 'ses-delivery';
+
+export const SES_PROVIDER_SLUG = 'ses';
+
+/**
+ * Desfecho consolidado gravado em `mail_sent.delivery_status`.
+ *
+ * A ordem e a precedencia: um evento so sobrescreve o status atual se tiver
+ * rank maior ou igual. Sem isso um `Delivery` que chega depois de um
+ * `Complaint` - o que acontece, porque o destinatario marca como spam depois de
+ * receber - apagaria a reclamacao e diria que esta tudo bem.
+ */
+export const MAIL_DELIVERY_STATUS_RANK: Record<string, number> = {
+  delivered: 1,
+  rejected: 2,
+  bounced: 3,
+  complained: 4,
+};
+
+/** Tipo de evento do provedor -> desfecho que ele representa. */
+export const MAIL_DELIVERY_EVENT_STATUS: Record<string, string> = {
+  delivery: 'delivered',
+  bounce: 'bounced',
+  complaint: 'complained',
+  reject: 'rejected',
+  renderingfailure: 'rejected',
+};

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

@@ -0,0 +1,38 @@
+import { Role } from '@hed-hog/api';
+import {
+  Controller,
+  Inject,
+  Param,
+  ParseIntPipe,
+  Post,
+  forwardRef,
+} from '@nestjs/common';
+import { MailDeliveryProvisionService } from './mail-delivery-provision.service';
+
+/**
+ * Via administrativa do rastreio de entrega.
+ *
+ * O endpoint que recebe os eventos e o `/webhook/:uuid` publico do core, servido
+ * pelo adaptador do protocolo `aws-ses` - por isso ele nao aparece aqui nem no
+ * route.yaml: o RoleGuard curto-circuita em IS_PUBLIC_KEY antes de ler a tabela
+ * de rotas, e uma linha la seria peso morto.
+ */
+@Role()
+@Controller('mail-delivery')
+export class MailDeliveryController {
+  constructor(
+    @Inject(forwardRef(() => MailDeliveryProvisionService))
+    private readonly provision: MailDeliveryProvisionService,
+  ) {}
+
+  /**
+   * Devolve a URL para assinar no topico SNS. Idempotente: chamar de novo
+   * devolve o mesmo UUID, entao uma subscription ja criada continua valendo.
+   */
+  @Post('provision/:integrationProfileId')
+  async provisionWebhook(
+    @Param('integrationProfileId', ParseIntPipe) integrationProfileId: number,
+  ) {
+    return this.provision.provision(integrationProfileId);
+  }
+}

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

@@ -0,0 +1,23 @@
+import { PrismaModule } from '@hed-hog/api-prisma';
+import { Module, forwardRef } from '@nestjs/common';
+import { WebhookIntegrationModule } from '../webhook-integration/webhook-integration.module';
+import { MailDeliveryProvisionService } from './mail-delivery-provision.service';
+import { MailDeliveryController } from './mail-delivery.controller';
+import { MailDeliveryService } from './mail-delivery.service';
+import { SesWebhookService } from './ses-webhook.service';
+
+/**
+ * Rastreio de entrega do e-mail: consome o que o provedor diz depois de aceitar
+ * a mensagem e o reflete em `mail_sent`.
+ */
+@Module({
+  imports: [
+    forwardRef(() => PrismaModule),
+    // O adaptador se registra no WebhookProtocolRegistry, que mora aqui.
+    forwardRef(() => WebhookIntegrationModule),
+  ],
+  controllers: [MailDeliveryController],
+  providers: [MailDeliveryService, MailDeliveryProvisionService, SesWebhookService],
+  exports: [MailDeliveryService, MailDeliveryProvisionService],
+})
+export class MailDeliveryModule {}