@hed-hog/core 0.0.399 → 0.0.401

package/src/document-kit/document-kit.service.ts

@@ -0,0 +1,173 @@
+import {
+  BadGatewayException,
+  HttpException,
+  Inject,
+  Injectable,
+  Logger,
+  NotFoundException,
+  forwardRef,
+} from '@nestjs/common';
+
+import { AiService } from '../ai/ai.service';
+import { AiPromptResolverService } from '../ai-instruction/ai-prompt-resolver.service';
+import { TemplateVars } from '../ai-instruction/ai-prompt-template.util';
+import { DocumentKitDefinition, getDocumentKit, pickLocale } from './document-kit.registry';
+
+export type DocumentKitDraftSection = {
+  key: string;
+  eyebrow: string;
+  title: string;
+  /** Straight from the model: the caller sanitizes before storing or printing. */
+  html: string;
+};
+
+export type DocumentKitDraft = {
+  kit: string;
+  /** Opening text of the document (executive summary), when the model wrote one. */
+  summaryHtml: string | null;
+  sections: DocumentKitDraftSection[];
+  provider: string;
+  model: string;
+  executionId: number | null;
+};
+
+/**
+ * Pulls the JSON object out of a model answer. Providers without a JSON mode
+ * (Claude) wrap it in a code fence or add a sentence before it.
+ */
+export function extractJsonObject(content: string): Record<string, any> | null {
+  const text = String(content ?? '')
+    .replace(/```(?:json)?/gi, '')
+    .trim();
+  const start = text.indexOf('{');
+  const end = text.lastIndexOf('}');
+  if (start < 0 || end <= start) return null;
+
+  try {
+    const parsed = JSON.parse(text.slice(start, end + 1));
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function asText(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+/** Only keys the kit declares survive, in the kit's order, and empty ones drop. */
+export function readDraftAnswer(
+  kit: DocumentKitDefinition,
+  answer: Record<string, any>,
+  locale?: string,
+): { summaryHtml: string | null; sections: DocumentKitDraftSection[] } {
+  const raw = answer.sections && typeof answer.sections === 'object' ? answer.sections : {};
+
+  const sections = kit.sections
+    .map((section) => {
+      const value = raw[section.key];
+      const html = typeof value === 'string' ? value.trim() : asText(value?.html);
+      if (!html) return null;
+      return {
+        key: section.key,
+        eyebrow: pickLocale(section.eyebrow, locale),
+        title: asText(value?.title) || pickLocale(section.title, locale),
+        html,
+      };
+    })
+    .filter((section): section is DocumentKitDraftSection => section !== null);
+
+  return { summaryHtml: asText(answer.summary_html) || null, sections };
+}
+
+/** The section list as the prompts receive it, in `{{sectionsSpec}}`. */
+export function buildSectionsSpec(kit: DocumentKitDefinition, locale?: string): string {
+  return kit.sections
+    .map(
+      (section) =>
+        `- ${section.key} — "${pickLocale(section.title, locale)}": ${section.guidance}`,
+    )
+    .join('\n');
+}
+
+@Injectable()
+export class DocumentKitService {
+  private readonly logger = new Logger(DocumentKitService.name);
+
+  constructor(
+    @Inject(forwardRef(() => AiService))
+    private readonly aiService: AiService,
+    @Inject(forwardRef(() => AiPromptResolverService))
+    private readonly prompts: AiPromptResolverService,
+  ) {}
+
+  /**
+   * Drafts a document with the kit's prompts. The references are resolved first
+   * and reach the prompts as variables, next to `sectionsSpec` and whatever the
+   * caller passes (client, items, values already computed by the system).
+   */
+  async draft(
+    slug: string,
+    input: { variables?: TemplateVars; locale?: string; contextSlug?: string },
+  ): Promise<DocumentKitDraft> {
+    const kit = getDocumentKit(slug);
+    if (!kit) {
+      throw new NotFoundException(`Document kit "${slug}" is not registered.`);
+    }
+
+    const referenceEntries = Object.entries(kit.references ?? {});
+    const resolvedReferences = referenceEntries.length
+      ? await this.prompts.resolveMany(referenceEntries.map(([, referenceSlug]) => ({ slug: referenceSlug })))
+      : {};
+    const references = Object.fromEntries(
+      referenceEntries.map(([variable, referenceSlug]) => [
+        variable,
+        resolvedReferences[referenceSlug]?.content?.trim() ?? '',
+      ]),
+    );
+
+    let result: Awaited<ReturnType<AiService['chatWithPrompt']>>;
+    try {
+      result = await this.aiService.chatWithPrompt({
+        systemPromptSlug: kit.prompts.system,
+        userPromptSlug: kit.prompts.user,
+        variables: {
+          ...references,
+          ...(input.variables ?? {}),
+          sectionsSpec: buildSectionsSpec(kit, input.locale),
+        },
+        params: { responseFormat: 'json_object' },
+        contextSlug: input.contextSlug ?? `document-kit.${kit.slug}`,
+      });
+    } catch (error) {
+      // Erro com mensagem propria (setting faltando, perfil invalido) passa como
+      // veio; o resto e falha do provedor (chave recusada, timeout) e chegaria
+      // na tela como "erro interno".
+      if (error instanceof HttpException) throw error;
+      this.logger.error(
+        `Document kit "${kit.slug}": the AI provider call failed. ${error instanceof Error ? error.message : String(error)}`,
+      );
+      throw new BadGatewayException(
+        'The AI provider did not answer. Check the AI integration profile and try again.',
+      );
+    }
+
+    const answer = extractJsonObject(result.content);
+    if (!answer) {
+      this.logger.warn(
+        `Document kit "${kit.slug}": the model answer is not a JSON object (${result.provider}/${result.model}).`,
+      );
+      throw new BadGatewayException(
+        'The AI answer could not be read. Try again, or review the prompts in AI Instructions.',
+      );
+    }
+
+    return {
+      kit: kit.slug,
+      ...readDraftAnswer(kit, answer, input.locale),
+      provider: result.provider,
+      model: result.model,
+      executionId: result.executionId,
+    };
+  }
+}

package/src/file/file-upload-ticket.service.spec.ts

@@ -0,0 +1,422 @@
+import { beforeEach, describe, expect, it, jest } from '@jest/globals';
+
+jest.mock('@hed-hog/api-prisma', () => ({
+  __esModule: true,
+  PrismaService: class {},
+  Prisma: {},
+}));
+
+import { FileUploadTicketService } from './file-upload-ticket.service';
+
+const PDF_BYTES = Buffer.concat([Buffer.from('%PDF-1.7'), Buffer.alloc(56)]);
+const PNG_BYTES = Buffer.concat([
+  Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+  Buffer.alloc(56),
+]);
+const CALLER = 7;
+
+const baseTicket = (overrides: Partial<any> = {}) => ({
+  id: 1,
+  user_id: CALLER,
+  filename: 'nota.pdf',
+  mimetype: 'application/pdf',
+  size_bytes: PDF_BYTES.length,
+  destination: 'mcp/uploads',
+  is_private: false,
+  sha256: null,
+  mode: 'chunked',
+  status: 'pending',
+  file_id: null,
+  idempotency_key: null,
+  expires_at: new Date(Date.now() + 600_000),
+  consumed_at: null,
+  ...overrides,
+});
+
+const makeService = (options: { ticket?: any; chunks?: any[] } = {}) => {
+  const state = {
+    ticket: options.ticket ?? baseTicket(),
+    chunks: options.chunks ?? [],
+  };
+
+  const prisma: any = {
+    file_upload_ticket: {
+      create: jest.fn(async ({ data }: any) => {
+        state.ticket = { ...baseTicket(), ...data, id: 1 };
+        return state.ticket;
+      }),
+      findFirst: jest.fn(async () =>
+        state.ticket?.idempotency_key ? state.ticket : null,
+      ),
+      findUnique: jest.fn(async () => state.ticket),
+      update: jest.fn(async ({ data }: any) => {
+        state.ticket = { ...state.ticket, ...data };
+        return state.ticket;
+      }),
+      // Espelha o update condicional: só vence quem encontra status pending e não expirado.
+      updateMany: jest.fn(async ({ where, data }: any) => {
+        const t = state.ticket;
+        const eligible =
+          t.id === where.id &&
+          t.status === where.status &&
+          t.expires_at.getTime() > where.expires_at.gt.getTime();
+
+        if (!eligible) {
+          return { count: 0 };
+        }
+
+        state.ticket = { ...t, ...data };
+        return { count: 1 };
+      }),
+    },
+    file_upload_chunk: {
+      upsert: jest.fn(async ({ where, create, update }: any) => {
+        const key = where.ticket_id_index;
+        const found = state.chunks.find(
+          (c) => c.ticket_id === key.ticket_id && c.index === key.index,
+        );
+        if (found) {
+          found.data = update.data;
+        } else {
+          state.chunks.push({ ...create });
+        }
+      }),
+      count: jest.fn(async () => state.chunks.length),
+      findMany: jest.fn(async () =>
+        [...state.chunks].sort((a, b) => a.index - b.index),
+      ),
+      deleteMany: jest.fn(async () => {
+        state.chunks = [];
+      }),
+    },
+  };
+
+  const jwtService: any = {
+    sign: jest.fn(() => 'token-assinado'),
+    verify: jest.fn(() => ({ t: 'file-upload', ticketId: 1 })),
+  };
+
+  const settingService: any = {
+    getSettingValues: jest.fn(async (keys: string[]) => {
+      const values: Record<string, any> = {
+        'storage-max-size': 10485760,
+        'storage-upload-url-ttl': 900,
+        'mcp-upload-chunk-bytes': 32,
+      };
+      return Object.fromEntries(keys.map((k) => [k, values[k]]));
+    }),
+  };
+
+  const fileService: any = {
+    acceptMimetypes: jest.fn(async () => true),
+    resolvePublicBaseUrl: jest.fn(async () => 'https://hub-api.hcode.com.br'),
+    get: jest.fn(async (id: number) => ({ id, filename: 'nota.pdf', size: 64, mimetype_id: 1 })),
+    upload: jest.fn(async (_d: string, file: any, _r: any, opts: any) => ({
+      id: 555,
+      filename: file.originalname,
+      size: file.size,
+      mimetype_id: 1,
+      created_by_user_id: opts?.createdByUserId ?? null,
+    })),
+  };
+
+  const service = new FileUploadTicketService(
+    prisma,
+    jwtService,
+    settingService,
+    fileService,
+  );
+
+  return { service, prisma, fileService, jwtService, state };
+};
+
+const chunksOf = (buffer: Buffer, size: number) => {
+  const out: Buffer[] = [];
+  for (let i = 0; i < buffer.length; i += size) {
+    out.push(buffer.subarray(i, i + size));
+  }
+  return out;
+};
+
+describe('create', () => {
+  it('recusa tamanho acima do storage-max-size antes de qualquer byte subir', async () => {
+    const { service } = makeService();
+    await expect(
+      service.create({
+        userId: CALLER,
+        fileName: 'grande.pdf',
+        mimeType: 'application/pdf',
+        sizeBytes: 99_000_000,
+        mode: 'signed_url',
+      }),
+    ).rejects.toThrow(/File too large/);
+  });
+
+  it('recusa mimetype fora da allowlist já na abertura', async () => {
+    // Deixar para o fim faria o cliente subir o arquivo inteiro para só então saber.
+    const { service, fileService } = makeService();
+    fileService.acceptMimetypes.mockResolvedValue(false);
+
+    await expect(
+      service.create({
+        userId: CALLER,
+        fileName: 'x.exe',
+        mimeType: 'application/x-msdownload',
+        sizeBytes: 100,
+        mode: 'signed_url',
+      }),
+    ).rejects.toThrow(/Invalid file type/);
+  });
+
+  it('recusa sha256 malformado', async () => {
+    const { service } = makeService();
+    await expect(
+      service.create({
+        userId: CALLER,
+        fileName: 'n.pdf',
+        mimeType: 'application/pdf',
+        sizeBytes: 100,
+        sha256: 'curto',
+        mode: 'signed_url',
+      }),
+    ).rejects.toThrow(/64 hexadecimal/);
+  });
+
+  it('devolve o mesmo ticket quando a idempotencyKey se repete', async () => {
+    const { service, prisma } = makeService({
+      ticket: baseTicket({ idempotency_key: 'k1' }),
+    });
+
+    const result = await service.create({
+      userId: CALLER,
+      fileName: 'n.pdf',
+      mimeType: 'application/pdf',
+      sizeBytes: 100,
+      idempotencyKey: 'k1',
+      mode: 'signed_url',
+    });
+
+    expect(result.reused).toBe(true);
+    expect(prisma.file_upload_ticket.create).not.toHaveBeenCalled();
+  });
+
+  it('reencontra o ticket quando o P2002 do índice parcial vence a corrida', async () => {
+    // O índice (user_id, idempotency_key) é PARCIAL, e o Prisma não modela índice
+    // parcial — a violação chega como P2002 cru em vez de ser evitada pelo findFirst.
+    const { service, prisma, state } = makeService();
+    state.ticket = baseTicket({ idempotency_key: 'k1' });
+    prisma.file_upload_ticket.create.mockRejectedValue(
+      Object.assign(new Error('unique'), { code: 'P2002' }),
+    );
+
+    const result = await service.create({
+      userId: CALLER,
+      fileName: 'n.pdf',
+      mimeType: 'application/pdf',
+      sizeBytes: 100,
+      idempotencyKey: 'k1',
+      mode: 'signed_url',
+    });
+
+    expect(result.reused).toBe(true);
+  });
+});
+
+describe('claim: uso único', () => {
+  it('só o primeiro vence', async () => {
+    const { service } = makeService();
+
+    await expect(service.claim(1)).resolves.toBe(true);
+    // O segundo encontra status != pending e sai de mãos vazias.
+    await expect(service.claim(1)).resolves.toBe(false);
+  });
+
+  it('não deixa reivindicar ticket expirado', async () => {
+    const { service } = makeService({
+      ticket: baseTicket({ expires_at: new Date(Date.now() - 1000) }),
+    });
+
+    await expect(service.claim(1)).resolves.toBe(false);
+  });
+});
+
+describe('appendChunk', () => {
+  it('recusa ticket de outro usuário como se não existisse', async () => {
+    const { service } = makeService();
+    await expect(service.appendChunk(1, 0, 'AAAA', 999)).rejects.toThrow(
+      /Upload ticket not found/,
+    );
+  });
+
+  it('recusa ticket expirado', async () => {
+    const { service } = makeService({
+      ticket: baseTicket({ expires_at: new Date(Date.now() - 1000) }),
+    });
+    await expect(service.appendChunk(1, 0, 'AAAA', CALLER)).rejects.toThrow(/expired/);
+  });
+
+  it('recusa append num upload aberto para PUT direto', async () => {
+    const { service } = makeService({ ticket: baseTicket({ mode: 'signed_url' }) });
+    await expect(service.appendChunk(1, 0, 'AAAA', CALLER)).rejects.toThrow(
+      /use the signed URL/,
+    );
+  });
+
+  it('recusa parte acima do chunkBytes configurado', async () => {
+    const { service } = makeService();
+    const tooBig = Buffer.alloc(64).toString('base64');
+    await expect(service.appendChunk(1, 0, tooBig, CALLER)).rejects.toThrow(
+      /above the 32 allowed/,
+    );
+  });
+
+  it('recusa índice negativo', async () => {
+    const { service } = makeService();
+    await expect(service.appendChunk(1, -1, 'AAAA', CALLER)).rejects.toThrow(
+      /non-negative integer/,
+    );
+  });
+
+  it('sobrescreve ao reenviar o mesmo índice, em vez de duplicar', async () => {
+    const { service, state } = makeService();
+
+    await service.appendChunk(1, 0, Buffer.from('abc').toString('base64'), CALLER);
+    await service.appendChunk(1, 0, Buffer.from('xyz').toString('base64'), CALLER);
+
+    expect(state.chunks).toHaveLength(1);
+    expect(Buffer.from(state.chunks[0].data).toString()).toBe('xyz');
+  });
+});
+
+describe('complete', () => {
+  const sendAll = async (service: any, buffer: Buffer) => {
+    const parts = chunksOf(buffer, 32);
+    for (let i = 0; i < parts.length; i += 1) {
+      await service.appendChunk(1, i, parts[i].toString('base64'), CALLER);
+    }
+  };
+
+  it('monta as partes na ordem e grava com o dono registrado', async () => {
+    const { service, fileService } = makeService();
+    await sendAll(service, PDF_BYTES);
+
+    const file = await service.complete(1, CALLER);
+
+    expect(file.id).toBe(555);
+    expect(fileService.upload).toHaveBeenCalledWith(
+      'mcp/uploads',
+      expect.objectContaining({ size: PDF_BYTES.length }),
+      undefined,
+      expect.objectContaining({ createdByUserId: CALLER }),
+    );
+    expect(fileService.upload.mock.calls[0][1].buffer).toEqual(PDF_BYTES);
+  });
+
+  it('recusa quando falta uma parte, em vez de montar um arquivo corrompido', async () => {
+    const { service } = makeService();
+    const parts = chunksOf(PDF_BYTES, 32);
+    // Manda 0 e 2, pulando o 1.
+    await service.appendChunk(1, 0, parts[0].toString('base64'), CALLER);
+    await service.appendChunk(1, 2, (parts[1] ?? parts[0]).toString('base64'), CALLER);
+
+    await expect(service.complete(1, CALLER)).rejects.toThrow(/missing chunk 1/);
+  });
+
+  it('recusa quando nenhuma parte chegou', async () => {
+    const { service } = makeService();
+    await expect(service.complete(1, CALLER)).rejects.toThrow(/has no chunks/);
+  });
+
+  it('recusa quando o conteúdo contradiz o mimetype declarado', async () => {
+    const { service } = makeService({
+      ticket: baseTicket({ size_bytes: PNG_BYTES.length }),
+    });
+    await sendAll(service, PNG_BYTES);
+
+    await expect(service.complete(1, CALLER)).rejects.toThrow(
+      /but the content is image\/png/,
+    );
+  });
+
+  it('recusa quando o sha256 declarado não bate', async () => {
+    const { service } = makeService({ ticket: baseTicket({ sha256: 'f'.repeat(64) }) });
+    await sendAll(service, PDF_BYTES);
+
+    await expect(service.complete(1, CALLER)).rejects.toThrow(/sha256 mismatch/);
+  });
+
+  it('recusa quando o tamanho entregue difere do declarado', async () => {
+    const { service } = makeService({ ticket: baseTicket({ size_bytes: 9999 }) });
+    await sendAll(service, PDF_BYTES);
+
+    await expect(service.complete(1, CALLER)).rejects.toThrow(
+      /but the ticket declared 9999/,
+    );
+  });
+
+  it('é idempotente: um ticket já finalizado devolve o mesmo fileId', async () => {
+    const { service, fileService } = makeService({
+      ticket: baseTicket({ status: 'completed', file_id: 555 }),
+    });
+
+    const file = await service.complete(1, CALLER);
+
+    expect(file.id).toBe(555);
+    // O ponto: não gera um segundo arquivo.
+    expect(fileService.upload).not.toHaveBeenCalled();
+  });
+
+  it('diz o que falta quando o PUT direto ainda não aconteceu', async () => {
+    const { service } = makeService({ ticket: baseTicket({ mode: 'signed_url' }) });
+    await expect(service.complete(1, CALLER)).rejects.toThrow(
+      /PUT the file to the signed URL first/,
+    );
+  });
+
+  it('recusa ticket de outro usuário', async () => {
+    const { service } = makeService();
+    await expect(service.complete(1, 999)).rejects.toThrow(/not found/);
+  });
+
+  it('marca como failed quando a montagem falha', async () => {
+    const { service, state } = makeService({ ticket: baseTicket({ sha256: 'f'.repeat(64) }) });
+    await sendAll(service, PDF_BYTES);
+
+    await expect(service.complete(1, CALLER)).rejects.toThrow();
+    expect(state.ticket.status).toBe('failed');
+  });
+});
+
+describe('resolveTicketFromToken', () => {
+  it('recusa token que não é de upload', async () => {
+    const { service, jwtService } = makeService();
+    jwtService.verify.mockReturnValue({ t: 'download', filepath: 'x' });
+
+    await expect(service.resolveTicketFromToken('t')).rejects.toThrow(
+      /not an upload token/,
+    );
+  });
+
+  it('recusa token inválido ou expirado', async () => {
+    const { service, jwtService } = makeService();
+    jwtService.verify.mockImplementation(() => {
+      throw new Error('jwt expired');
+    });
+
+    await expect(service.resolveTicketFromToken('t')).rejects.toThrow(
+      /Invalid or expired upload token/,
+    );
+  });
+});
+
+describe('describeUploadedBuffer', () => {
+  it('produz tamanho, hash e cabeçalho numa passada', () => {
+    const digest = FileUploadTicketService.describeUploadedBuffer(PDF_BYTES);
+
+    expect(digest.bytes).toBe(PDF_BYTES.length);
+    expect(digest.sha256).toBe(
+      require('crypto').createHash('sha256').update(PDF_BYTES).digest('hex'),
+    );
+    expect(digest.header.subarray(0, 5).toString()).toBe('%PDF-');
+  });
+});