@hed-hog/core 0.0.399 → 0.0.401

package/hedhog/table/user_session.yaml

@@ -7,6 +7,17 @@ columns:
       column: id
       onDelete: CASCADE
   - name: hash
+  # Hash do refresh token IMEDIATAMENTE anterior, aceito ate
+  # `previous_hash_expires_at`. Sem essa janela, a rotacao e um handoff sem
+  # tolerancia: se a resposta do /auth/refresh se perde (rede caindo, aba
+  # suspensa, pod reciclado) o servidor ja girou e o cliente fica com um token
+  # morto — sessao de 30 dias destruida por um soluco de rede. Serve tambem para
+  # duas abas que renovam ao mesmo tempo.
+  - name: previous_hash
+    isNullable: true
+  - name: previous_hash_expires_at
+    type: datetime
+    isNullable: true
   - name: browser_id
     isNullable: true
   - name: ip_address
@@ -28,6 +39,25 @@ columns:
     type: varchar
     length: 255
     isNullable: true
+  # Recurso para o qual o access token desta sessao foi emitido (o `aud` do JWT).
+  # NULL e a sessao de login normal, que vale na API inteira; preenchida, o token
+  # so serve naquele recurso — e o TokenService recusa o caminho contrario, um
+  # token COM `aud` chegando numa rota que nao espera audiencia nenhuma.
+  #
+  # Mora na sessao, e nao so no JWT, porque o refresh token e opaco: na rotacao a
+  # unica coisa que sobrevive e esta linha. Sem a coluna, o primeiro
+  # POST /auth/refresh de um cliente externo devolveria um token sem `aud` e
+  # desfaria a restricao.
+  - name: audience
+    type: varchar
+    length: 255
+    isNullable: true
+  # Qual client OAuth abriu a sessao (oauth_app_client.client_id). Serve para a
+  # tela de sessoes dizer "Claude" em vez de repetir o user agent.
+  - name: oauth_client_id
+    type: varchar
+    length: 100
+    isNullable: true
   - type: created_at
   - type: updated_at
 
@@ -36,4 +66,9 @@ columns:
 # composto ja cobre esses casos.
 indices:
   - columns: [user_id, browser_id]
-  - columns: [impersonator_user_id]
+  - columns: [impersonator_user_id]
+  # Todo /auth/refresh e todo /auth/logout procuram a sessao pelo hash. Sem
+  # indice sao seq scans na tabela inteira, e a latencia do refresh entra na
+  # janela de corrida da rotacao.
+  - columns: [hash]
+  - columns: [previous_hash]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hed-hog/core",
-  "version": "0.0.399",
+  "version": "0.0.401",
   "license": "MIT",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -27,6 +27,8 @@
     "@simplewebauthn/server": "^13.2.2",
     "argon2": "^0.44.0",
     "axios": "^1.9.0",
+    "class-transformer": "*",
+    "class-validator": "*",
     "cookie-parser": "^1.4.7",
     "geoip-lite": "^2.0.2",
     "handlebars": "^4.7.8",
@@ -45,11 +47,11 @@
     "speakeasy": "^2.0.0",
     "ua-parser-js": "^2.0.10",
     "uuid": "^11.1.0",
-    "@hed-hog/vault-crypto": "0.0.1",
     "@hed-hog/api-prisma": "0.0.7",
-    "@hed-hog/api-types": "0.0.2",
     "@hed-hog/api-mail": "0.0.11",
     "@hed-hog/api-locale": "0.0.15",
+    "@hed-hog/vault-crypto": "0.0.1",
+    "@hed-hog/api-types": "0.0.2",
     "@hed-hog/api-pagination": "0.0.8",
     "@hed-hog/api": "0.0.9"
   },

package/src/ai/ai-agent.sort.ts

@@ -0,0 +1,21 @@
+import { defineSortable } from '@hed-hog/api-pagination';
+
+/**
+ * Campos ordenáveis de `ai_agent` (`AiService.listAgents`). Todas as colunas
+ * exibidas na tela são planas — sem relação envolvida.
+ */
+export const AI_AGENT_SORT = defineSortable(
+  {
+    slug: true,
+    provider: true,
+    model: true,
+    external_agent_id: true,
+    created_at: { initialOrder: 'desc' },
+    id: { initialOrder: 'desc' },
+  },
+  {
+    // Mesma ordem que estava fixa no `$queryRaw` (`ORDER BY id DESC`).
+    default: 'id',
+    defaultOrder: 'desc',
+  },
+);

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');
+  });
+});