@hed-hog/core 0.0.400 → 0.0.402

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hed-hog/core",
-  "version": "0.0.400",
+  "version": "0.0.402",
   "license": "MIT",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -48,12 +48,12 @@
     "ua-parser-js": "^2.0.10",
     "uuid": "^11.1.0",
     "@hed-hog/api-prisma": "0.0.7",
-    "@hed-hog/api-locale": "0.0.15",
-    "@hed-hog/api-mail": "0.0.11",
     "@hed-hog/vault-crypto": "0.0.1",
+    "@hed-hog/api-mail": "0.0.11",
+    "@hed-hog/api-locale": "0.0.15",
+    "@hed-hog/api-types": "0.0.2",
     "@hed-hog/api": "0.0.9",
-    "@hed-hog/api-pagination": "0.0.8",
-    "@hed-hog/api-types": "0.0.2"
+    "@hed-hog/api-pagination": "0.0.8"
   },
   "exports": {
     ".": {

package/src/access-log/access-log.interceptor.spec.ts

@@ -0,0 +1,50 @@
+import 'reflect-metadata';
+import { SetMetadata } from '@nestjs/common';
+import { lastValueFrom, of } from 'rxjs';
+import { AccessLogInterceptor, SKIP_ACCESS_LOG_KEY } from './access-log.interceptor';
+
+class PlainController {
+  handler() {}
+}
+
+@SetMetadata(SKIP_ACCESS_LOG_KEY, true)
+class AnonymousController {
+  handler() {}
+}
+
+function contextFor(controller: any) {
+  const request = {
+    url: '/x',
+    ip: '203.0.113.7',
+    method: 'POST',
+    headers: { 'user-agent': 'UA' },
+  };
+  return {
+    getType: () => 'http',
+    switchToHttp: () => ({ getRequest: () => request }),
+    getHandler: () => controller.prototype.handler,
+    getClass: () => controller,
+  } as any;
+}
+
+describe('AccessLogInterceptor', () => {
+  it('records ordinary requests', async () => {
+    const recordHttp = jest.fn();
+    const interceptor = new AccessLogInterceptor({ recordHttp } as any);
+    await lastValueFrom(
+      interceptor.intercept(contextFor(PlainController), { handle: () => of(1) }),
+    );
+    expect(recordHttp).toHaveBeenCalledWith(
+      expect.objectContaining({ ip: '203.0.113.7', userAgent: 'UA' }),
+    );
+  });
+
+  it('skips routes marked with skipAccessLog (anonymous whistleblower channel)', async () => {
+    const recordHttp = jest.fn();
+    const interceptor = new AccessLogInterceptor({ recordHttp } as any);
+    await lastValueFrom(
+      interceptor.intercept(contextFor(AnonymousController), { handle: () => of(1) }),
+    );
+    expect(recordHttp).not.toHaveBeenCalled();
+  });
+});

package/src/access-log/access-log.interceptor.ts

@@ -7,6 +7,17 @@ import {
 import { Observable, tap } from 'rxjs';
 import { AccessLogService } from './access-log.service';
 
+/**
+ * Metadado (handler ou classe) que tira a rota do access log.
+ *
+ * Existe para superficies cujo valor depende de NAO saber quem chamou — o canal
+ * de denuncias da library integrity: uma linha com IP, user agent e horario de
+ * `POST /integrity/public/reports` identificaria o denunciante. Quem usa aplica
+ * `SetMetadata('skipAccessLog', true)` direto, sem importar daqui, para uma
+ * library nao exigir esta versao do core (um core antigo apenas continua logando).
+ */
+export const SKIP_ACCESS_LOG_KEY = 'skipAccessLog';
+
 @Injectable()
 export class AccessLogInterceptor implements NestInterceptor {
   constructor(private readonly accessLogService: AccessLogService) {}
@@ -23,6 +34,13 @@ export class AccessLogInterceptor implements NestInterceptor {
       return next.handle();
     }
 
+    if (
+      Reflect.getMetadata(SKIP_ACCESS_LOG_KEY, context.getHandler()) === true ||
+      Reflect.getMetadata(SKIP_ACCESS_LOG_KEY, context.getClass()) === true
+    ) {
+      return next.handle();
+    }
+
     return next.handle().pipe(
       tap(() => {
         const userId: number | undefined = request.auth?.sub;

package/src/ai/ai-attachment.fragments.spec.ts

@@ -179,6 +179,10 @@ describe('AiService — anexos no fio', () => {
     return mockedAxios.post.mock.calls.at(-1)?.[1] as Record<string, any>;
   }
 
+  function lastUrl(): string {
+    return mockedAxios.post.mock.calls.at(-1)?.[0] as string;
+  }
+
   describe('Gemini', () => {
     it('embrulha anexo de texto exatamente como o código original', async () => {
       useAttachment(TEXT_ATTACHMENT);
@@ -248,23 +252,72 @@ describe('AiService — anexos no fio', () => {
       );
     });
 
-    it('embrulha PDF com texto extraído exatamente como o código original', async () => {
+    // Num modelo com visão o PDF deixou de ser achatado em texto: ele vai
+    // inteiro para a Responses API, que renderiza as páginas. Era isso que
+    // faltava para uma nota fiscal escaneada — sem camada de texto, o caminho
+    // antigo mandava ao modelo a frase dizendo que o PDF é ilegível.
+    it('PDF vai como documento para a Responses API, não achatado em texto', async () => {
       const pdfText = 'Cláusula 1ª — objeto do contrato.';
       useAttachment(PDF_ATTACHMENT);
       jest.spyOn(service as any, 'extractPdfText').mockResolvedValue(pdfText);
+      jest.spyOn(service as any, 'countPdfPages').mockResolvedValue(1);
 
       await service.chat({ message: 'Resuma.', provider: 'openai' } as any);
 
+      expect(lastUrl()).toBe('https://api.openai.com/v1/responses');
+      expect(lastBody().messages).toBeUndefined();
+
+      const [file, text] = lastBody().input[0].content;
+      expect(file.type).toBe('input_file');
+      expect(file.filename).toBe(PDF_ATTACHMENT.filename);
+      expect(file.file_data).toBe(
+        `data:application/pdf;base64,${PDF_ATTACHMENT.buffer.toString('base64')}`,
+      );
+      expect(text).toEqual({ type: 'input_text', text: 'Resuma.' });
+    });
+
+    it('PDF ilegível também vai como documento, sem marcador nenhum', async () => {
+      useAttachment(PDF_ATTACHMENT);
+      jest.spyOn(service as any, 'extractPdfText').mockResolvedValue('');
+      jest.spyOn(service as any, 'countPdfPages').mockResolvedValue(1);
+
+      await service.chat({ message: 'Resuma.', provider: 'openai' } as any);
+
+      expect(lastUrl()).toBe('https://api.openai.com/v1/responses');
+      expect(JSON.stringify(lastBody())).not.toContain(
+        legacyUnreadablePdf(PDF_ATTACHMENT),
+      );
+    });
+
+    // O marcador continua valendo onde a Responses API não ajuda: modelo sem
+    // visão só receberia a camada de texto de volta, o mesmo nada num endpoint
+    // diferente. Então esses dois casos guardam a fidelidade byte a byte.
+    it('em modelo sem visão, PDF com texto continua no bloco de arquivo legado', async () => {
+      const pdfText = 'Cláusula 1ª — objeto do contrato.';
+      useAttachment(PDF_ATTACHMENT);
+      jest.spyOn(service as any, 'extractPdfText').mockResolvedValue(pdfText);
+
+      await service.chat({
+        message: 'Resuma.',
+        provider: 'openai',
+        model: 'gpt-3.5-turbo',
+      } as any);
+
+      expect(lastUrl()).toBe('https://api.openai.com/v1/chat/completions');
       expect(lastBody().messages[0].content).toBe(
         legacyOpenAiReturn('Resuma.', PDF_ATTACHMENT, pdfText),
       );
     });
 
-    it('PDF ilegível cai no marcador de PDF, dentro do bloco de arquivo', async () => {
+    it('em modelo sem visão, PDF ilegível cai no marcador de PDF', async () => {
       useAttachment(PDF_ATTACHMENT);
       jest.spyOn(service as any, 'extractPdfText').mockResolvedValue('');
 
-      await service.chat({ message: 'Resuma.', provider: 'openai' } as any);
+      await service.chat({
+        message: 'Resuma.',
+        provider: 'openai',
+        model: 'gpt-3.5-turbo',
+      } as any);
 
       expect(lastBody().messages[0].content).toBe(
         legacyOpenAiReturn('Resuma.', PDF_ATTACHMENT, legacyUnreadablePdf(PDF_ATTACHMENT)),

package/src/ai/ai.service.responses.spec.ts

@@ -0,0 +1,429 @@
+import axios from 'axios';
+import { AiService } from './ai.service';
+
+jest.mock('axios');
+
+const mockedAxios = axios as jest.Mocked<typeof axios>;
+
+/**
+ * PDF como documento.
+ *
+ * O caminho antigo achatava todo PDF em texto: sem camada de texto, o modelo
+ * recebia o marcador `[PDF attachment with unreadable text: ...]` e não tinha
+ * como extrair coisa alguma — era esse o motivo de uma nota fiscal escaneada
+ * voltar com todos os campos vazios. Estes testes fixam o caminho que entrega
+ * o documento ao modelo, e os limites em que ele não se aplica.
+ */
+describe('AiService — PDF como documento (Responses API)', () => {
+  let service: AiService;
+
+  const aiProfile = {
+    apiKey: 'sk-test',
+    model: undefined as string | undefined,
+    timeoutMs: undefined as number | undefined,
+    baseUrl: undefined as string | undefined,
+  };
+
+  const PDF = {
+    filename: 'nf.pdf',
+    mimeType: 'application/pdf',
+    buffer: Buffer.from('%PDF-1.7 conteudo'),
+  };
+
+  const IMAGE = {
+    filename: 'nf.png',
+    mimeType: 'image/png',
+    buffer: Buffer.from('png-bytes'),
+  };
+
+  beforeEach(() => {
+    const aiExecution = {
+      start: jest.fn().mockResolvedValue(1),
+      recordStep: jest.fn().mockResolvedValue(undefined),
+      finish: jest.fn().mockResolvedValue(undefined),
+    } as any;
+
+    service = new AiService(
+      {} as any,
+      { getSettingValues: jest.fn().mockResolvedValue({}) } as any,
+      {} as any,
+      aiExecution,
+      { resolveMany: jest.fn() } as any,
+    );
+
+    jest.spyOn(service as any, 'getAiProfile').mockResolvedValue(aiProfile);
+    jest.spyOn(service as any, 'getDefaultProvider').mockResolvedValue('openai');
+    jest.spyOn(service as any, 'resolveAttachment').mockResolvedValue(PDF);
+    jest.spyOn(service as any, 'countPdfPages').mockResolvedValue(3);
+    jest.spyOn(service as any, 'extractPdfText').mockResolvedValue('');
+
+    mockedAxios.post.mockResolvedValue({
+      data: {
+        status: 'completed',
+        output: [
+          { type: 'message', content: [{ type: 'output_text', text: 'ok' }] },
+        ],
+        choices: [{ message: { content: 'ok' } }],
+      },
+    } as any);
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+    mockedAxios.post.mockReset();
+  });
+
+  const lastBody = () =>
+    mockedAxios.post.mock.calls.at(-1)?.[1] as Record<string, any>;
+  const lastUrl = () => mockedAxios.post.mock.calls.at(-1)?.[0] as string;
+  const lastConfig = () =>
+    mockedAxios.post.mock.calls.at(-1)?.[2] as Record<string, any>;
+
+  it('manda o PDF em input_file, com a instrução depois do arquivo', async () => {
+    await service.chat({ message: 'Extraia.', provider: 'openai' } as any);
+
+    expect(lastUrl()).toBe('https://api.openai.com/v1/responses');
+
+    const [file, text] = lastBody().input[0].content;
+    expect(file).toEqual({
+      type: 'input_file',
+      filename: 'nf.pdf',
+      file_data: `data:application/pdf;base64,${PDF.buffer.toString('base64')}`,
+    });
+    expect(text).toEqual({ type: 'input_text', text: 'Extraia.' });
+  });
+
+  it('sem parâmetros, o corpo é exatamente { input, model }', async () => {
+    await service.chat({ message: 'Extraia.', provider: 'openai' } as any);
+
+    expect(Object.keys(lastBody()).sort()).toEqual(['input', 'model']);
+  });
+
+  it('o system prompt vira instructions de topo, não uma mensagem', async () => {
+    await service.chat({
+      message: 'Extraia.',
+      provider: 'openai',
+      systemPrompt: 'Você é um extrator.',
+    } as any);
+
+    expect(lastBody().instructions).toBe('Você é um extrator.');
+    expect(lastBody().input.some((item: any) => item.role === 'system')).toBe(
+      false,
+    );
+  });
+
+  it('renomeia max_tokens e response_format para os nomes da Responses API', async () => {
+    await service.chat({
+      message: 'Extraia.',
+      provider: 'openai',
+      max_tokens: 500,
+      response_format: 'json_object',
+    } as any);
+
+    expect(lastBody().max_output_tokens).toBe(500);
+    expect(lastBody()).not.toHaveProperty('max_tokens');
+    expect(lastBody().text).toEqual({ format: { type: 'json_object' } });
+    expect(lastBody()).not.toHaveProperty('response_format');
+  });
+
+  it('não trunca nem trava num corpo de megabytes', async () => {
+    await service.chat({ message: 'Extraia.', provider: 'openai' } as any);
+
+    expect(lastConfig().maxBodyLength).toBe(Infinity);
+    expect(lastConfig().maxContentLength).toBe(Infinity);
+    expect(lastConfig().timeout).toBe(120_000);
+  });
+
+  // `output_text` é conveniência do SDK e costuma faltar no JSON cru; ler só
+  // ele é a forma mais provável de entregar isto quebrado.
+  it('lê o texto do array output, ignorando o reasoning sem content', async () => {
+    mockedAxios.post.mockResolvedValue({
+      data: {
+        output: [
+          { type: 'reasoning', summary: [] },
+          {
+            type: 'message',
+            content: [{ type: 'output_text', text: '{"valor":9500}' }],
+          },
+        ],
+      },
+    } as any);
+
+    const result = await service.chat({
+      message: 'Extraia.',
+      provider: 'openai',
+    } as any);
+
+    expect(result.content).toBe('{"valor":9500}');
+  });
+
+  it('usa output_text quando ele vem preenchido', async () => {
+    mockedAxios.post.mockResolvedValue({
+      data: { output_text: '{"valor":1}', output: [] },
+    } as any);
+
+    const result = await service.chat({
+      message: 'Extraia.',
+      provider: 'openai',
+    } as any);
+
+    expect(result.content).toBe('{"valor":1}');
+  });
+
+  it('mapeia o usage da Responses API, inclusive os tokens em cache', async () => {
+    mockedAxios.post.mockResolvedValue({
+      data: {
+        output: [
+          { type: 'message', content: [{ type: 'output_text', text: 'ok' }] },
+        ],
+        usage: {
+          input_tokens: 1200,
+          output_tokens: 80,
+          total_tokens: 1280,
+          input_tokens_details: { cached_tokens: 400 },
+        },
+      },
+    } as any);
+
+    const recordStep = jest.fn().mockResolvedValue(undefined);
+    (service as any).aiExecution.recordStep = recordStep;
+
+    await service.chat({ message: 'Extraia.', provider: 'openai' } as any);
+
+    expect(recordStep.mock.calls[0][0].usage).toEqual({
+      input: 1200,
+      output: 80,
+      total: 1280,
+      cached: 400,
+    });
+  });
+
+  it('reporta que o documento chegou ao modelo', async () => {
+    const result = await service.chat({
+      message: 'Extraia.',
+      provider: 'openai',
+    } as any);
+
+    expect(result.attachmentDelivery).toBe('pdf-document');
+  });
+
+  it('degrada para chat/completions quando a Responses API devolve 400', async () => {
+    mockedAxios.post
+      .mockRejectedValueOnce({
+        response: { status: 400, data: { error: { message: 'unsupported' } } },
+      })
+      .mockResolvedValue({
+        data: { choices: [{ message: { content: 'ok' } }] },
+      } as any);
+
+    const result = await service.chat({
+      message: 'Extraia.',
+      provider: 'openai',
+    } as any);
+
+    expect(mockedAxios.post).toHaveBeenCalledTimes(2);
+    expect(lastUrl()).toBe('https://api.openai.com/v1/chat/completions');
+    expect(result.content).toBe('ok');
+  });
+
+  // Degradar aqui só reproduziria o marcador de PDF ilegível e devolveria
+  // "não achei nada" — escondendo uma credencial inválida.
+  it('não mascara um 401 com uma segunda chamada mais fraca', async () => {
+    mockedAxios.post.mockRejectedValue({
+      response: { status: 401, data: { error: { message: 'bad key' } } },
+    });
+
+    await expect(
+      service.chat({ message: 'Extraia.', provider: 'openai' } as any),
+    ).rejects.toMatchObject({ response: { status: 401 } });
+
+    expect(mockedAxios.post).toHaveBeenCalledTimes(1);
+  });
+
+  it('PDF acima do teto de páginas volta para o chat/completions', async () => {
+    jest.spyOn(service as any, 'countPdfPages').mockResolvedValue(50);
+
+    await service.chat({ message: 'Extraia.', provider: 'openai' } as any);
+
+    expect(lastUrl()).toBe('https://api.openai.com/v1/chat/completions');
+  });
+
+  it('imagem continua pelo bloco de visão do chat/completions', async () => {
+    jest.spyOn(service as any, 'resolveAttachment').mockResolvedValue(IMAGE);
+
+    const result = await service.chat({
+      message: 'Extraia.',
+      provider: 'openai',
+    } as any);
+
+    expect(lastUrl()).toBe('https://api.openai.com/v1/chat/completions');
+    expect(lastBody().messages[0].content[1].type).toBe('image_url');
+    expect(result.attachmentDelivery).toBe('image');
+  });
+
+  // O guarda dos ~25 pontos do repo que chamam IA sem anexo nenhum.
+  it('sem anexo, nada muda: chat/completions com o corpo de sempre', async () => {
+    jest.spyOn(service as any, 'resolveAttachment').mockResolvedValue(null);
+
+    const result = await service.chat({
+      message: 'oi',
+      provider: 'openai',
+    } as any);
+
+    expect(lastUrl()).toBe('https://api.openai.com/v1/chat/completions');
+    expect(Object.keys(lastBody()).sort()).toEqual(['messages', 'model']);
+    expect(result.attachmentDelivery).toBe('none');
+  });
+
+  it('o DeepSeek não tem /v1/responses: PDF segue no chat/completions', async () => {
+    await service.chat({ message: 'Extraia.', provider: 'deepseek' } as any);
+
+    expect(lastUrl()).toContain('/chat/completions');
+    expect(lastUrl()).not.toContain('api.openai.com');
+  });
+
+  it('uma base URL de gateway não recebe /v1/responses', async () => {
+    jest
+      .spyOn(service as any, 'getAiProfile')
+      .mockResolvedValue({ ...aiProfile, baseUrl: 'https://gateway.interno/v1' });
+
+    await service.chat({ message: 'Extraia.', provider: 'openai' } as any);
+
+    expect(lastUrl()).toBe('https://gateway.interno/v1/chat/completions');
+  });
+
+  it('modelo sem visão não usa a Responses API', async () => {
+    await service.chat({
+      message: 'Extraia.',
+      provider: 'openai',
+      model: 'gpt-3.5-turbo',
+    } as any);
+
+    expect(lastUrl()).toBe('https://api.openai.com/v1/chat/completions');
+  });
+});
+
+/**
+ * Provider x perfil.
+ *
+ * O setting `ai-gemini-profile-id` apontando para um perfil OpenAI fazia o
+ * serviço postar a chave da OpenAI no endpoint do Google e engolir o erro de
+ * cada modelo tentado. A trava já existia para o perfil explícito; faltava no
+ * caminho que vem do setting global.
+ */
+describe('AiService — perfil do provider', () => {
+  let service: AiService;
+  let integrationProfile: { findUnique: jest.Mock };
+  let settingService: { getSettingValues: jest.Mock };
+
+  const geminiProfile = {
+    slug: 'gemini',
+    config: { api_key: 'AIza-test' },
+    integration_provider: { slug: 'gemini' },
+  };
+
+  const openaiProfile = {
+    slug: 'openia-hub',
+    config: { api_key: 'sk-test' },
+    integration_provider: { slug: 'openai' },
+  };
+
+  beforeEach(() => {
+    integrationProfile = { findUnique: jest.fn() };
+    settingService = { getSettingValues: jest.fn() };
+
+    service = new AiService(
+      { integration_profile: integrationProfile } as any,
+      settingService as any,
+      {} as any,
+      {
+        start: jest.fn().mockResolvedValue(1),
+        recordStep: jest.fn().mockResolvedValue(undefined),
+        finish: jest.fn().mockResolvedValue(undefined),
+      } as any,
+      { resolveMany: jest.fn() } as any,
+    );
+
+    mockedAxios.post.mockResolvedValue({
+      data: { candidates: [{ content: { parts: [{ text: 'ok' }] } }] },
+    } as any);
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+    mockedAxios.post.mockReset();
+  });
+
+  it('recusa quando o setting do Gemini aponta para um perfil OpenAI', async () => {
+    settingService.getSettingValues.mockResolvedValue({
+      'ai-gemini-profile-id': 'openia-hub',
+    });
+    integrationProfile.findUnique.mockResolvedValue(openaiProfile);
+
+    await expect(
+      (service as any).getAiProfile('gemini'),
+    ).rejects.toThrow(/ai-gemini-profile-id/);
+
+    // O ponto todo: nenhuma requisição condenada sai.
+    expect(mockedAxios.post).not.toHaveBeenCalled();
+  });
+
+  it('aceita quando o provider do perfil bate com o pedido', async () => {
+    settingService.getSettingValues.mockResolvedValue({
+      'ai-gemini-profile-id': 'gemini',
+    });
+    integrationProfile.findUnique.mockResolvedValue(geminiProfile);
+
+    await expect((service as any).getAiProfile('gemini')).resolves.toMatchObject(
+      { apiKey: 'AIza-test' },
+    );
+  });
+
+  it('isProviderConfigured responde sem lançar', async () => {
+    settingService.getSettingValues.mockResolvedValue({
+      'ai-gemini-profile-id': 'openia-hub',
+    });
+    integrationProfile.findUnique.mockResolvedValue(openaiProfile);
+
+    const result = await service.isProviderConfigured('gemini' as any);
+
+    expect(result.ok).toBe(false);
+    expect(result.reason).toMatch(/ai-gemini-profile-id/);
+  });
+
+  it('isProviderConfigured devolve ok quando o perfil está correto', async () => {
+    settingService.getSettingValues.mockResolvedValue({
+      'ai-gemini-profile-id': 'gemini',
+    });
+    integrationProfile.findUnique.mockResolvedValue(geminiProfile);
+
+    await expect(service.isProviderConfigured('gemini' as any)).resolves.toEqual(
+      { ok: true },
+    );
+  });
+
+  it('setting vazio continua sendo "não configurado", não incompatibilidade', async () => {
+    settingService.getSettingValues.mockResolvedValue({
+      'ai-gemini-profile-id': '',
+    });
+
+    const result = await service.isProviderConfigured('gemini' as any);
+
+    expect(result.ok).toBe(false);
+    expect(result.reason).toMatch(/No gemini AI profile configured/);
+  });
+
+  // O caminho do perfil explícito deriva o provider DO perfil, então nunca cai
+  // na trava nova — é o que o SAC, o CMS e o campaign usam.
+  it('perfil explícito segue derivando o provider do próprio perfil', async () => {
+    integrationProfile.findUnique.mockResolvedValue(openaiProfile);
+
+    const resolved = await (service as any).resolveProviderAndProfile(
+      undefined,
+      'openia-hub',
+    );
+
+    expect(resolved.provider).toBe('openai');
+    expect(resolved.profile.apiKey).toBe('sk-test');
+  });
+});