@hed-hog/core 0.0.387 → 0.0.393

package/src/mail-layout/dto/update.dto.ts

@@ -0,0 +1,19 @@
+import { IsObject, IsOptional, IsString } from 'class-validator';
+
+export class UpdateDTO {
+  @IsString()
+  @IsOptional()
+  wrapper?: string;
+
+  /**
+   * Traducoes indexadas pelo CODIGO do locale (`{ pt: { name, header, footer } }`).
+   *
+   * Codigo e nao id de proposito: o `useApp().locales` do admin so expoe
+   * `{ code, name }`, entao qualquer payload baseado em id acabaria adivinhando o
+   * id a partir do indice do array. `LocaleService.updateModelWithLocale` resolve
+   * o codigo via `getByCode`.
+   */
+  @IsObject()
+  @IsOptional()
+  locale?: Record<string, { name?: string; header?: string; footer?: string }>;
+}

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

@@ -0,0 +1,47 @@
+import { Role } from '@hed-hog/api';
+import { Locale } from '@hed-hog/api-locale';
+import { Pagination } from '@hed-hog/api-pagination';
+import {
+  Body,
+  Controller,
+  Get,
+  Inject,
+  Param,
+  ParseIntPipe,
+  Patch,
+  forwardRef,
+} from '@nestjs/common';
+import { UpdateDTO } from './dto/update.dto';
+import { MailLayoutService } from './mail-layout.service';
+
+/**
+ * Controller proprio (e nao `@Get('layout')` dentro de MailController) porque o
+ * MailController ja declara `@Get(':id')` com ParseIntPipe: uma rota
+ * `/mail/layout` seria capturada por ele e responderia 400.
+ */
+@Role()
+@Controller('mail-layout')
+export class MailLayoutController {
+  constructor(
+    @Inject(forwardRef(() => MailLayoutService))
+    private readonly mailLayoutService: MailLayoutService,
+  ) {}
+
+  @Get()
+  async list(@Locale() locale, @Pagination() paginationParams) {
+    return this.mailLayoutService.list(locale, paginationParams);
+  }
+
+  @Get(':id')
+  async get(@Param('id', ParseIntPipe) id: number) {
+    return this.mailLayoutService.get(id);
+  }
+
+  @Patch(':id')
+  async update(
+    @Param('id', ParseIntPipe) id: number,
+    @Body() data: UpdateDTO,
+  ) {
+    return this.mailLayoutService.update(id, data);
+  }
+}

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

@@ -0,0 +1,22 @@
+import { LocaleModule } from '@hed-hog/api-locale';
+import { PaginationModule } from '@hed-hog/api-pagination';
+import { PrismaModule } from '@hed-hog/api-prisma';
+import { forwardRef, Module } from '@nestjs/common';
+import { MailModule } from '../mail/mail.module';
+import { MailLayoutController } from './mail-layout.controller';
+import { MailLayoutService } from './mail-layout.service';
+
+@Module({
+  imports: [
+    // MailModule registra o MailModule global do api-mail, de onde vem o
+    // MailService usado para invalidar o cache do layout.
+    forwardRef(() => MailModule),
+    forwardRef(() => PrismaModule),
+    forwardRef(() => PaginationModule),
+    forwardRef(() => LocaleModule),
+  ],
+  controllers: [MailLayoutController],
+  providers: [MailLayoutService],
+  exports: [MailLayoutService],
+})
+export class MailLayoutModule {}

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

@@ -0,0 +1,94 @@
+import { LocaleService } from '@hed-hog/api-locale';
+import { MailService as MailMainService } from '@hed-hog/api-mail';
+import { PaginationDTO } from '@hed-hog/api-pagination';
+import { PrismaService } from '@hed-hog/api-prisma';
+import {
+  BadRequestException,
+  forwardRef,
+  Inject,
+  Injectable,
+  NotFoundException,
+} from '@nestjs/common';
+import { UpdateDTO } from './dto/update.dto';
+
+/**
+ * Layout base aplicado a todo e-mail transacional do sistema.
+ *
+ * Modelo de registro unico na pratica (um `is_default`), mas a tabela ja tem
+ * `slug` + `is_default` para permitir varios layouts depois sem migration
+ * destrutiva.
+ */
+@Injectable()
+export class MailLayoutService {
+  private readonly modelName = 'mail_layout';
+  private readonly foreignKeyName = 'mail_layout_id';
+
+  constructor(
+    @Inject(forwardRef(() => PrismaService))
+    private readonly prismaService: PrismaService,
+    @Inject(forwardRef(() => LocaleService))
+    private readonly localeService: LocaleService,
+    @Inject(forwardRef(() => MailMainService))
+    private readonly mailMainService: MailMainService,
+  ) {}
+
+  async list(locale: string, paginationParams: PaginationDTO): Promise<any> {
+    return this.localeService.listModelWithLocale(
+      locale,
+      this.modelName,
+      paginationParams,
+    );
+  }
+
+  async get(id: number): Promise<any> {
+    const layout = await this.localeService.getModelWithLocale(
+      this.modelName,
+      id,
+    );
+
+    if (!layout) {
+      throw new NotFoundException(`Mail layout with id ${id} not found.`);
+    }
+
+    return layout;
+  }
+
+  /** Retorna o layout marcado como padrao, que e o que a tela do admin edita. */
+  async getDefault(): Promise<any> {
+    const row = await this.prismaService.mail_layout.findFirst({
+      where: { is_default: true },
+      select: { id: true },
+    });
+
+    if (!row) {
+      throw new NotFoundException('No default mail layout configured.');
+    }
+
+    return this.get(row.id);
+  }
+
+  async update(id: number, data: UpdateDTO): Promise<any> {
+    if (data.wrapper !== undefined && !this.hasContentToken(data.wrapper)) {
+      // Um wrapper sem slot de conteudo enviaria e-mails vazios para todo mundo,
+      // e a falha so apareceria na caixa do destinatario.
+      throw new BadRequestException(
+        'The wrapper must contain a {{{content}}} token.',
+      );
+    }
+
+    const updated = await this.localeService.updateModelWithLocale(
+      this.modelName,
+      this.foreignKeyName,
+      id,
+      data,
+    );
+
+    this.mailMainService.invalidateLayoutCache();
+
+    return updated;
+  }
+
+  private hasContentToken(wrapper: string): boolean {
+    return wrapper.includes('{{{content}}}') || wrapper.includes('{{content}}');
+  }
+}

package/src/mail-sent/dto/query-mail-sent-list.dto.ts

@@ -13,6 +13,21 @@ export class QueryMailSentListDTO extends PaginationDTO {
   @IsString()
   hasError?: string;
 
+  /**
+   * Desfecho reportado pelo provedor. `pending` e a ausencia de desfecho: ele
+   * aceitou a mensagem e nao disse mais nada.
+   */
+  @IsOptional()
+  @Transform(({ value }) => String(value ?? '').trim().toLowerCase())
+  @IsIn(['all', 'pending', 'delivered', 'bounced', 'complained', 'rejected'])
+  deliveryStatus?:
+    | 'all'
+    | 'pending'
+    | 'delivered'
+    | 'bounced'
+    | 'complained'
+    | 'rejected';
+
   @IsOptional()
   @Transform(({ value }) => String(value ?? '').trim())
   @IsString()

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

@@ -42,7 +42,18 @@ export class MailSentService {
   ) { }
 
   async list(paginationParams: QueryMailSentListDTO) {
-    const fields = ['subject', 'from', 'to', 'cc', 'bcc', 'body'];
+    // `provider_message_id` entra na busca porque e o unico identificador que o
+    // evento do provedor traz: sem ele, ler um bounce no console da AWS e achar
+    // o envio correspondente aqui exigia adivinhacao.
+    const fields = [
+      'subject',
+      'from',
+      'to',
+      'cc',
+      'bcc',
+      'body',
+      'provider_message_id',
+    ];
     const OR: any[] = this.prismaService.createInsensitiveSearch(
       fields,
       paginationParams,
@@ -99,6 +110,17 @@ export class MailSentService {
       });
     }
 
+    const deliveryStatus = paginationParams.deliveryStatus?.trim();
+    if (deliveryStatus && deliveryStatus !== 'all') {
+      // `pending` e a ausencia de desfecho: o provedor aceitou e nao disse mais
+      // nada. E o estado em que ficam os envios que ninguem sabe se chegaram.
+      AND.push(
+        deliveryStatus === 'pending'
+          ? { delivery_status: null }
+          : { delivery_status: deliveryStatus },
+      );
+    }
+
     const createdAt: { gte?: Date; lte?: Date } = {};
     const createdAtFrom = paginationParams.createdAtFrom?.trim();
     const createdAtTo = paginationParams.createdAtTo?.trim();
@@ -146,6 +168,22 @@ export class MailSentService {
               updated_at: true,
             },
           },
+          // O que o provedor disse depois de aceitar. `mail_sent_user` so cobre
+          // destinatario que e usuario da plataforma; um solicitante externo nao
+          // deixava rastro nenhum de entrega.
+          mail_delivery_event: {
+            select: {
+              id: true,
+              recipient_email: true,
+              event_type: true,
+              bounce_type: true,
+              bounce_subtype: true,
+              diagnostic_code: true,
+              reporting_mta: true,
+              occurred_at: true,
+            },
+            orderBy: { occurred_at: 'desc' },
+          },
         },
       },
     );
@@ -198,9 +236,15 @@ export class MailSentService {
     };
   }
 
-  async get(locale:string, id: number) {
+  async get(locale: string, id: number) {
     const mailSent = await this.prismaService.mail_sent.findUnique({
       where: { id: id },
+      // Sem os relacionamentos, abrir um envio direto pelo id devolvia um
+      // registro sem nenhuma informacao de entrega - so a listagem trazia.
+      include: {
+        mail_sent_user: true,
+        mail_delivery_event: { orderBy: { occurred_at: 'desc' } },
+      },
     });
 
     if (!mailSent) {

package/src/mailbox/mailbox-fetcher.registry.ts

@@ -0,0 +1,132 @@
+import { Injectable, Logger } from '@nestjs/common';
+
+/**
+ * Uma mensagem recebida, ainda crua.
+ *
+ * O fetcher devolve o MIME e nada mais. Interpretar (parsear cabeçalhos, cortar
+ * citação, decidir se é autoresposta) é do consumidor — assim os dois provedores
+ * compartilham exatamente o mesmo caminho de leitura, e o core não precisa
+ * conhecer mailparser nem as regras de atendimento.
+ */
+export interface RawInboundMessage {
+  /**
+   * Identidade da mensagem no provedor (Message-Id, id do Graph).
+   * É a chave de idempotência de quem consome.
+   */
+  externalId: string;
+  /** Mensagem RFC 822 completa. */
+  source: Buffer;
+  receivedAt: Date;
+}
+
+export interface MailboxFetchTarget {
+  /** Perfil de integração com as credenciais. */
+  integrationProfileId: number;
+  /** Endereço monitorado. No Graph, é também o alvo do acesso app-only. */
+  address: string;
+  folder: string;
+  /**
+   * Cursor OPACO, como o fetcher o gravou da última vez.
+   *
+   * Cada provedor escolhe o formato — UID + UIDVALIDITY no IMAP, deltaLink no
+   * Graph. Manter isso opaco é o que permite um campo só no banco servir aos
+   * dois sem o consumidor entender nenhum dos dois.
+   */
+  cursor: string | null;
+  markAsRead: boolean;
+  /** Teto por ciclo, para uma caixa esquecida não virar um poll infinito. */
+  maxMessages: number;
+}
+
+export interface MailboxFetchResult {
+  messages: RawInboundMessage[];
+  /** Cursor a gravar DEPOIS que as mensagens forem persistidas. */
+  cursor: string | null;
+  /**
+   * O provedor invalidou o cursor anterior (UIDVALIDITY novo, delta expirado).
+   * Serve para o consumidor registrar o fato — a releitura em si já vem
+   * resolvida no resultado.
+   */
+  cursorReset: boolean;
+}
+
+/** Resultado de um teste de leitura, no mesmo formato do `MailVerifyResult`. */
+export interface MailboxVerifyResult {
+  ok: boolean;
+  /** Evidência legível do sucesso. Nunca contém credencial. */
+  info?: string;
+  /** Motivo legível da falha. Nunca contém credencial. */
+  error?: string;
+}
+
+/**
+ * Lê uma caixa de correio.
+ *
+ * Implementações vivem nas libraries donas do protocolo (IMAP no `sac`,
+ * Microsoft Graph no `microsoft`) e se registram aqui no boot.
+ */
+export interface IMailboxFetcher {
+  /** Falso quando o provedor está desligado ou mal configurado nesta instalação. */
+  isAvailable(): Promise<boolean>;
+  fetch(target: MailboxFetchTarget): Promise<MailboxFetchResult>;
+  /**
+   * Confere se ESTA caixa pode ser lida agora, exercitando o caminho real.
+   *
+   * Existe porque testar o perfil de integração não é a mesma coisa que testar a
+   * caixa: para o Entra, o teste do perfil só pede um token e passa mesmo sem
+   * permissão de e-mail, sem acesso àquele endereço e sem a pasta existir — ou
+   * seja, aprovaria uma caixa que nunca vai receber nada.
+   *
+   * Opcional: sem ela, o chamador cai no testador do perfil (o que basta para o
+   * IMAP, onde autenticar já prova o acesso).
+   */
+  verify?(target: MailboxFetchTarget): Promise<MailboxVerifyResult>;
+}
+
+/**
+ * Registro dos leitores de caixa, no mesmo padrão do MeetingProviderRegistry.
+ *
+ * Existe pelo mesmo motivo daquele: permitir que um módulo de negócio leia uma
+ * caixa do Microsoft 365 sem depender de `@hed-hog-pro/microsoft` — o que
+ * arrastaria as tabelas, as rotas e os crons daquela library para toda
+ * instalação, só para obter um token.
+ *
+ * A chave é o SLUG DO PROVIDER DE INTEGRAÇÃO (`imap`,
+ * `microsoft-entra-id-oauth`), então o caminho perfil → fetcher se resolve sem
+ * nenhuma tabela de-para.
+ */
+@Injectable()
+export class MailboxFetcherRegistry {
+  private readonly logger = new Logger(MailboxFetcherRegistry.name);
+  private readonly fetchers = new Map<string, IMailboxFetcher>();
+
+  register(providerSlug: string, implementation: IMailboxFetcher): void {
+    const key = normalizeProvider(providerSlug);
+    if (!key) throw new Error('Mailbox fetcher provider key is required.');
+
+    if (this.fetchers.has(key)) {
+      this.logger.warn(`Mailbox fetcher "${key}" was overwritten.`);
+    }
+
+    this.fetchers.set(key, implementation);
+    this.logger.log(`Registered mailbox fetcher "${key}"`);
+  }
+
+  get(providerSlug: string | null | undefined): IMailboxFetcher | null {
+    const key = normalizeProvider(providerSlug);
+    return key ? (this.fetchers.get(key) ?? null) : null;
+  }
+
+  has(providerSlug: string | null | undefined): boolean {
+    return this.get(providerSlug) !== null;
+  }
+
+  /** Providers que sabem ler caixa nesta instalação (a UI filtra por isto). */
+  list(): string[] {
+    return [...this.fetchers.keys()].sort();
+  }
+}
+
+function normalizeProvider(providerSlug: string | null | undefined): string {
+  return String(providerSlug ?? '').trim().toLowerCase();
+}

package/src/mailbox/mailbox.module.ts

@@ -0,0 +1,14 @@
+import { Global, Module } from '@nestjs/common';
+import { MailboxFetcherRegistry } from './mailbox-fetcher.registry';
+
+/**
+ * Porta genérica de leitura de caixa de correio. Só carrega o registro — as
+ * implementações vêm de quem se registrar no boot (a library `sac` com a chave
+ * `imap`, a library `microsoft` com `microsoft-entra-id-oauth`).
+ */
+@Global()
+@Module({
+  providers: [MailboxFetcherRegistry],
+  exports: [MailboxFetcherRegistry],
+})
+export class MailboxModule {}

package/src/mcp-chat/mcp-chat.service.spec.ts

@@ -0,0 +1,236 @@
+import axios from 'axios';
+import { McpChatService } from './mcp-chat.service';
+
+jest.mock('axios');
+
+const mockedAxios = axios as jest.Mocked<typeof axios>;
+
+type ProfileConfig = Record<string, unknown>;
+
+/**
+ * O serviço é instanciado à mão em vez de por `Test.createTestingModule` para
+ * não arrastar os `forwardRef` do módulo — o que está sob teste é a resolução
+ * do modelo, não a injeção.
+ */
+function buildService(params: {
+  providerSlug: string;
+  config: ProfileConfig;
+  clarification?: string;
+}) {
+  const recordStep = jest.fn();
+  const finish = jest.fn();
+
+  const prisma = {
+    mcp_conversation: {
+      findUnique: jest.fn().mockResolvedValue({ user_id: 1, title: 'conversa' }),
+      update: jest.fn().mockResolvedValue({}),
+    },
+    mcp_conversation_message: {
+      create: jest.fn().mockResolvedValue({}),
+      findMany: jest.fn().mockResolvedValue([]),
+    },
+    integration_profile: {
+      findUnique: jest.fn().mockResolvedValue({
+        config: { api_key: 'chave-secreta', ...params.config },
+        integration_provider: { slug: params.providerSlug },
+      }),
+    },
+    route: { findMany: jest.fn().mockResolvedValue([]) },
+  };
+
+  const setting = {
+    getSettingValues: jest.fn(async (keys: string[]) => {
+      const values: Record<string, unknown> = {
+        'mcp-enabled': true,
+        'mcp-ai-profile-id': 'perfil-mcp',
+      };
+      return Object.fromEntries(keys.map((key) => [key, values[key]]));
+    }),
+  };
+
+  // Sem ferramentas registradas o loop encerra na primeira resposta, e
+  // `tools`/`tool_choice` continuam `undefined` no corpo enviado.
+  const registry = { getAll: jest.fn().mockReturnValue([]) };
+
+  const promptBuilder = {
+    build: jest.fn().mockResolvedValue({
+      systemPrompt: 'prompt de sistema',
+      layers: [],
+      layerNames: [],
+    }),
+  };
+
+  const aiExecution = {
+    start: jest.fn().mockResolvedValue(7),
+    recordStep,
+    finish,
+  };
+
+  const service = new McpChatService(
+    prisma as any,
+    setting as any,
+    registry as any,
+    promptBuilder as any,
+    aiExecution as any,
+  );
+
+  if (params.clarification) {
+    jest
+      .spyOn(service as any, 'selectOpenAiTools')
+      .mockResolvedValue({ tools: [], clarification: params.clarification });
+  }
+
+  return { service, recordStep, finish, prisma };
+}
+
+function mockOpenAiReply() {
+  mockedAxios.post.mockResolvedValue({
+    data: {
+      choices: [{ message: { content: 'resposta' } }],
+      usage: { prompt_tokens: 10, completion_tokens: 5, total_tokens: 15 },
+    },
+  } as any);
+}
+
+function mockGeminiReply() {
+  mockedAxios.post.mockResolvedValue({
+    data: {
+      candidates: [{ content: { parts: [{ text: 'resposta' }] } }],
+      usageMetadata: {
+        promptTokenCount: 10,
+        candidatesTokenCount: 5,
+        totalTokenCount: 15,
+      },
+    },
+  } as any);
+}
+
+const send = (service: McpChatService) =>
+  service.sendMessage(1, 1, 'pt-BR', 'olá');
+
+describe('McpChatService — modelo vindo do integration_profile', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe('OpenAI', () => {
+    it('sem model no perfil, envia o corpo histórico intacto', async () => {
+      const { service, recordStep } = buildService({
+        providerSlug: 'openai',
+        config: {},
+      });
+      mockOpenAiReply();
+
+      await send(service);
+
+      const [url, body, options] = mockedAxios.post.mock.calls[0];
+      expect(url).toBe('https://api.openai.com/v1/chat/completions');
+      expect(body).toEqual({
+        model: 'gpt-4o-mini',
+        messages: [
+          { role: 'system', content: 'prompt de sistema' },
+        ],
+        tools: undefined,
+        tool_choice: undefined,
+      });
+      expect(options).toEqual({
+        headers: {
+          Authorization: 'Bearer chave-secreta',
+          'Content-Type': 'application/json',
+        },
+      });
+      expect(recordStep).toHaveBeenCalledWith(
+        expect.objectContaining({ provider: 'openai', model: 'gpt-4o-mini' }),
+      );
+    });
+
+    it('usa o model do perfil no corpo e no registro de custo', async () => {
+      const { service, recordStep } = buildService({
+        providerSlug: 'openai',
+        config: { model: 'gpt-4o' },
+      });
+      mockOpenAiReply();
+
+      await send(service);
+
+      expect(mockedAxios.post.mock.calls[0][1]).toEqual(
+        expect.objectContaining({ model: 'gpt-4o' }),
+      );
+      expect(recordStep).toHaveBeenCalledWith(
+        expect.objectContaining({ provider: 'openai', model: 'gpt-4o' }),
+      );
+    });
+  });
+
+  describe('Gemini', () => {
+    it('sem model no perfil, mantém a URL e o custo históricos', async () => {
+      const { service, recordStep } = buildService({
+        providerSlug: 'gemini',
+        config: {},
+      });
+      mockGeminiReply();
+
+      await send(service);
+
+      expect(mockedAxios.post.mock.calls[0][0]).toBe(
+        'https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key=chave-secreta',
+      );
+      expect(recordStep).toHaveBeenCalledWith(
+        expect.objectContaining({
+          provider: 'gemini',
+          model: 'gemini-2.0-flash',
+        }),
+      );
+    });
+
+    it('usa o model do perfil na URL e no registro de custo', async () => {
+      const { service, recordStep } = buildService({
+        providerSlug: 'gemini',
+        config: { model: 'gemini-2.5-flash' },
+      });
+      mockGeminiReply();
+
+      await send(service);
+
+      expect(mockedAxios.post.mock.calls[0][0]).toContain(
+        '/models/gemini-2.5-flash:generateContent',
+      );
+      expect(recordStep).toHaveBeenCalledWith(
+        expect.objectContaining({
+          provider: 'gemini',
+          model: 'gemini-2.5-flash',
+        }),
+      );
+    });
+
+    it('aceita o model no formato "models/<id>" sem duplicar o segmento', async () => {
+      const { service, recordStep } = buildService({
+        providerSlug: 'gemini',
+        config: { model: 'models/gemini-2.5-flash' },
+      });
+      mockGeminiReply();
+
+      await send(service);
+
+      const url = mockedAxios.post.mock.calls[0][0];
+      expect(url).toContain('/v1beta/models/gemini-2.5-flash:generateContent');
+      expect(url).not.toContain('models/models/');
+      expect(recordStep).toHaveBeenCalledWith(
+        expect.objectContaining({ model: 'gemini-2.5-flash' }),
+      );
+    });
+  });
+
+  it('fecha a execução quando o caminho OpenAI devolve pedido de esclarecimento', async () => {
+    const { service, finish } = buildService({
+      providerSlug: 'openai',
+      config: {},
+      clarification: 'Qual conta você quer consultar?',
+    });
+
+    await send(service);
+
+    expect(mockedAxios.post).not.toHaveBeenCalled();
+    expect(finish).toHaveBeenCalledWith(7, 'completed');
+  });
+});