@hed-hog/core 0.0.400 → 0.0.402

package/src/ai-instruction/ai-prompt-resolver.service.ts

@@ -255,6 +255,35 @@ export function applyOpenAiModelParams(
   return result;
 }
 
+/**
+ * Same as `applyOpenAiModelParams`, but for `POST /v1/responses`.
+ *
+ * That endpoint renames three things, and this is the single place the rename
+ * lives: the messages array is `input`, `max_tokens` is `max_output_tokens`,
+ * and `response_format` moved under `text.format`. The system prompt is not a
+ * message either — it is the top-level `instructions`, handled by the caller.
+ *
+ * Same contract as the sibling: a key is only written when there is a value, so
+ * a body built with no params stays exactly `{ model, input }`.
+ */
+export function applyOpenAiResponsesParams(
+  body: Record<string, unknown>,
+  params: ModelParams,
+  defaults: OpenAiParamDefaults,
+): Record<string, unknown> {
+  const model = params.model || defaults.model;
+  const temperature = params.temperature ?? defaults.temperature;
+  const maxTokens = params.maxTokens ?? defaults.maxTokens;
+
+  const result: Record<string, unknown> = { model, ...body };
+
+  if (temperature != null) result.temperature = temperature;
+  if (maxTokens != null) result.max_output_tokens = maxTokens;
+  if (defaults.jsonObject) result.text = { format: { type: 'json_object' } };
+
+  return result;
+}
+
 export function applyGeminiModelParams(
   payload: Record<string, unknown>,
   params: ModelParams,

package/src/core.module.ts

@@ -26,6 +26,7 @@ import { LeakedPasswordService } from './leaked-password/leaked-password.service
 import { MailLayoutModule } from './mail-layout/mail-layout.module';
 import { MailModule } from './mail/mail.module';
 import { MessageTemplateModule } from './message-template/message-template.module';
+import { DocumentKitModule } from './document-kit/document-kit.module';
 import { McpChatModule } from './mcp-chat/mcp-chat.module';
 import { McpModule } from './mcp/mcp.module';
 import { MenuModule } from './menu/menu.module';
@@ -90,6 +91,7 @@ import { WhatsappSenderModule } from './whatsapp-sender/whatsapp-sender.module';
     forwardRef(() => LeakedPasswordModule),
     forwardRef(() => MailModule),
     forwardRef(() => MessageTemplateModule),
+    forwardRef(() => DocumentKitModule),
     forwardRef(() => MailLayoutModule),
     forwardRef(() => IntegrationProfileModule),
     forwardRef(() => WhatsappSenderModule),
@@ -125,6 +127,7 @@ import { WhatsappSenderModule } from './whatsapp-sender/whatsapp-sender.module';
     LeakedPasswordModule,
     MailModule,
     MessageTemplateModule,
+    DocumentKitModule,
     MailLayoutModule,
     IntegrationProfileModule,
     WhatsappSenderModule,

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

@@ -0,0 +1,12 @@
+import { forwardRef, Module } from '@nestjs/common';
+
+import { AiInstructionModule } from '../ai-instruction/ai-instruction.module';
+import { AiModule } from '../ai/ai.module';
+import { DocumentKitService } from './document-kit.service';
+
+@Module({
+  imports: [forwardRef(() => AiModule), forwardRef(() => AiInstructionModule)],
+  providers: [DocumentKitService],
+  exports: [DocumentKitService],
+})
+export class DocumentKitModule {}

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

@@ -0,0 +1,125 @@
+/**
+ * Document kits: what a library needs to have a document drafted by AI and
+ * printed with a core template — the prompts, the reference texts the prompts
+ * lean on (catalog, price table, writing rules) and the sections the document
+ * is made of.
+ *
+ * Only code, like the message templates: the editable parts are the prompts and
+ * references, which are `ai_instruction` rows and already have their own screen
+ * (Core › AI Instructions), with versions and "restore default". A kit only ties
+ * them together.
+ *
+ * Libraries register at import time, from their `*.prompts.ts`:
+ *
+ *   registerDocumentKits([{ slug: 'crm.commercial-proposal', ... }]);
+ */
+
+export type DocumentKitTemplate = 'commercial-proposal';
+
+export type DocumentKitSection = {
+  /** Stable id: the key the model answers with and the one stored with the document. */
+  key: string;
+  /** Short label next to the section number (`02 · ESCOPO`). */
+  eyebrow: Record<string, string>;
+  /** Default title, a short sentence; the model may propose a better one. */
+  title: Record<string, string>;
+  /** What goes in the section, as told to the model. */
+  guidance: string;
+};
+
+export type DocumentKitDefinition = {
+  /** `<module>.<name>`, e.g. `crm.commercial-proposal`. */
+  slug: string;
+  /** Must equal the first slug segment. */
+  moduleSlug: string;
+  /** 'pt' required. */
+  name: Record<string, string>;
+  template: DocumentKitTemplate;
+  /** `ai_instruction` slugs of the drafting call. */
+  prompts: { system: string; user: string };
+  /**
+   * Prompt variable → `ai_instruction` slug (`.raw`) whose content is handed to
+   * the prompts under that name. Lets the business content be edited apart from
+   * the instructions.
+   */
+  references: Record<string, string>;
+  sections: DocumentKitSection[];
+};
+
+const SLUG_RE = /^([a-z0-9-]+)\.([a-z0-9-]+)$/;
+const KEY_RE = /^[a-z][a-z0-9_]*$/;
+
+const registry = new Map<string, DocumentKitDefinition>();
+
+function assertDefinition(definition: DocumentKitDefinition) {
+  const match = SLUG_RE.exec(definition.slug);
+  if (!match) {
+    throw new Error(`Invalid document kit slug "${definition.slug}". Expected "<module>.<name>".`);
+  }
+  if (match[1] !== definition.moduleSlug) {
+    throw new Error(
+      `Document kit "${definition.slug}" declares moduleSlug "${definition.moduleSlug}" but its slug says "${match[1]}".`,
+    );
+  }
+  if (!definition.name?.pt) {
+    throw new Error(`Document kit "${definition.slug}" needs a 'pt' name.`);
+  }
+  if (!definition.prompts?.system || !definition.prompts?.user) {
+    throw new Error(`Document kit "${definition.slug}" needs a system and a user prompt.`);
+  }
+  if (!definition.sections?.length) {
+    throw new Error(`Document kit "${definition.slug}" has no sections.`);
+  }
+
+  const keys = new Set<string>();
+  for (const section of definition.sections) {
+    if (!KEY_RE.test(section.key)) {
+      throw new Error(`Document kit "${definition.slug}" has an invalid section key "${section.key}".`);
+    }
+    if (keys.has(section.key)) {
+      throw new Error(`Document kit "${definition.slug}" repeats the section key "${section.key}".`);
+    }
+    if (!section.eyebrow?.pt || !section.title?.pt) {
+      throw new Error(`Section "${section.key}" of "${definition.slug}" needs a 'pt' eyebrow and title.`);
+    }
+    keys.add(section.key);
+  }
+
+  for (const variable of Object.keys(definition.references ?? {})) {
+    if (variable === 'sectionsSpec') {
+      throw new Error(`Document kit "${definition.slug}" cannot name a reference "sectionsSpec".`);
+    }
+  }
+}
+
+export function registerDocumentKits(definitions: DocumentKitDefinition[]): void {
+  for (const definition of definitions) {
+    assertDefinition(definition);
+    const existing = registry.get(definition.slug);
+    if (existing && existing !== definition) {
+      throw new Error(`Document kit "${definition.slug}" is already registered.`);
+    }
+    registry.set(definition.slug, definition);
+  }
+}
+
+export function getDocumentKit(slug: string): DocumentKitDefinition | undefined {
+  return registry.get(slug);
+}
+
+export function listDocumentKits(moduleSlug?: string): DocumentKitDefinition[] {
+  const all = [...registry.values()];
+  const filtered = moduleSlug ? all.filter((kit) => kit.moduleSlug === moduleSlug) : all;
+  return filtered.sort((a, b) => a.slug.localeCompare(b.slug));
+}
+
+/** Test helper. */
+export function clearDocumentKitRegistry(): void {
+  registry.clear();
+}
+
+/** Text of a localized label, falling back to 'pt'. */
+export function pickLocale(value: Record<string, string>, locale?: string): string {
+  const short = String(locale || 'pt').toLowerCase().split('-')[0];
+  return value[short] ?? value.pt ?? Object.values(value)[0] ?? '';
+}

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

@@ -0,0 +1,156 @@
+import { BadGatewayException, NotFoundException } from '@nestjs/common';
+import { afterEach, beforeEach, describe, expect, it, jest } from '@jest/globals';
+
+import {
+  DocumentKitDefinition,
+  clearDocumentKitRegistry,
+  getDocumentKit,
+  registerDocumentKits,
+} from './document-kit.registry';
+import { DocumentKitService, extractJsonObject } from './document-kit.service';
+
+const kit = (overrides: Partial<DocumentKitDefinition> = {}): DocumentKitDefinition => ({
+  slug: 'crm.commercial-proposal',
+  moduleSlug: 'crm',
+  name: { pt: 'Proposta comercial' },
+  template: 'commercial-proposal',
+  prompts: { system: 'task.crm.proposal-draft.compose.system', user: 'task.crm.proposal-draft.compose.user' },
+  references: { catalog: 'task.crm.proposal-draft.catalog.raw' },
+  sections: [
+    { key: 'scope', eyebrow: { pt: 'Escopo', en: 'Scope' }, title: { pt: 'O que entra.', en: 'What is in.' }, guidance: 'O que está incluído.' },
+    { key: 'program', eyebrow: { pt: 'Programa' }, title: { pt: 'Como é o dia.' }, guidance: 'Blocos do programa.' },
+  ],
+  ...overrides,
+});
+
+describe('registerDocumentKits', () => {
+  afterEach(() => clearDocumentKitRegistry());
+
+  it('registra e devolve o kit pelo slug', () => {
+    registerDocumentKits([kit()]);
+    expect(getDocumentKit('crm.commercial-proposal')?.sections).toHaveLength(2);
+  });
+
+  it('recusa slug fora do formato e módulo divergente', () => {
+    expect(() => registerDocumentKits([kit({ slug: 'proposal' })])).toThrow(/Invalid document kit slug/);
+    expect(() => registerDocumentKits([kit({ moduleSlug: 'lms' })])).toThrow(/declares moduleSlug/);
+  });
+
+  it('recusa seção repetida, chave inválida e kit sem seção', () => {
+    const section = kit().sections[0];
+    expect(() => registerDocumentKits([kit({ sections: [section, section] })])).toThrow(/repeats/);
+    expect(() => registerDocumentKits([kit({ sections: [{ ...section, key: 'Escopo' }] })])).toThrow(/invalid section key/);
+    expect(() => registerDocumentKits([kit({ sections: [] })])).toThrow(/no sections/);
+  });
+
+  it('recusa outro kit com o mesmo slug', () => {
+    registerDocumentKits([kit()]);
+    expect(() => registerDocumentKits([kit()])).toThrow(/already registered/);
+  });
+});
+
+describe('extractJsonObject', () => {
+  it('lê JSON puro, com cerca de código e com texto em volta', () => {
+    expect(extractJsonObject('{"a":1}')).toEqual({ a: 1 });
+    expect(extractJsonObject('```json\n{"a":1}\n```')).toEqual({ a: 1 });
+    expect(extractJsonObject('Segue a proposta:\n{"a":{"b":2}}\nBoa sorte.')).toEqual({ a: { b: 2 } });
+  });
+
+  it('devolve null para texto sem objeto ou JSON quebrado', () => {
+    expect(extractJsonObject('não consegui')).toBeNull();
+    expect(extractJsonObject('{"a":')).toBeNull();
+    expect(extractJsonObject('[1,2]')).toBeNull();
+  });
+});
+
+describe('DocumentKitService.draft', () => {
+  let chatWithPrompt: jest.Mock<(...args: any[]) => Promise<any>>;
+  let resolveMany: jest.Mock<(...args: any[]) => Promise<any>>;
+  let service: DocumentKitService;
+
+  beforeEach(() => {
+    registerDocumentKits([kit()]);
+    chatWithPrompt = jest.fn();
+    resolveMany = jest.fn(async () => ({
+      'task.crm.proposal-draft.catalog.raw': { content: '  Workshop 4h  ' },
+    }));
+    service = new DocumentKitService({ chatWithPrompt } as any, { resolveMany } as any);
+  });
+
+  afterEach(() => clearDocumentKitRegistry());
+
+  const answer = (content: string) =>
+    chatWithPrompt.mockResolvedValue({ provider: 'claude', model: 'claude-sonnet-4-5', content, executionId: 9 });
+
+  it('passa referências, seções e variáveis do chamador aos prompts, pedindo JSON', async () => {
+    answer('{"summary_html":"<p>Oi</p>","sections":{}}');
+
+    await service.draft('crm.commercial-proposal', { variables: { clientName: 'ArcelorMittal' }, locale: 'pt-BR' });
+
+    const call = chatWithPrompt.mock.calls[0][0];
+    expect(call).toMatchObject({
+      systemPromptSlug: 'task.crm.proposal-draft.compose.system',
+      userPromptSlug: 'task.crm.proposal-draft.compose.user',
+      params: { responseFormat: 'json_object' },
+      contextSlug: 'document-kit.crm.commercial-proposal',
+    });
+    expect(call.variables.catalog).toBe('Workshop 4h');
+    expect(call.variables.clientName).toBe('ArcelorMittal');
+    expect(call.variables.sectionsSpec).toContain('- scope — "O que entra.": O que está incluído.');
+  });
+
+  it('devolve as seções na ordem do kit, sem chave desconhecida nem seção vazia', async () => {
+    answer(
+      '```json\n' +
+        JSON.stringify({
+          summary_html: '<p>Resumo</p>',
+          sections: {
+            program: { title: 'Um dia de prática.', html: '<p>Blocos</p>' },
+            invented: { html: '<p>fora do kit</p>' },
+            scope: { html: '<p>Tudo</p>' },
+          },
+        }) +
+        '\n```',
+    );
+
+    const draft = await service.draft('crm.commercial-proposal', { locale: 'en' });
+
+    expect(draft.summaryHtml).toBe('<p>Resumo</p>');
+    expect(draft.sections).toEqual([
+      { key: 'scope', eyebrow: 'Scope', title: 'What is in.', html: '<p>Tudo</p>' },
+      { key: 'program', eyebrow: 'Programa', title: 'Um dia de prática.', html: '<p>Blocos</p>' },
+    ]);
+    expect(draft.executionId).toBe(9);
+  });
+
+  it('aceita a seção como string e omite a que veio vazia', async () => {
+    answer('{"sections":{"scope":"<p>Tudo</p>","program":{"html":"   "}}}');
+
+    const draft = await service.draft('crm.commercial-proposal', {});
+
+    expect(draft.summaryHtml).toBeNull();
+    expect(draft.sections.map((section) => section.key)).toEqual(['scope']);
+  });
+
+  it('responde 502 quando a IA não devolve JSON', async () => {
+    answer('Desculpe, não consigo ajudar.');
+
+    await expect(service.draft('crm.commercial-proposal', {})).rejects.toBeInstanceOf(BadGatewayException);
+  });
+
+  it('troca a falha do provedor por 502 e deixa passar erro HTTP com mensagem própria', async () => {
+    chatWithPrompt.mockRejectedValueOnce(new Error('Request failed with status code 401'));
+    await expect(service.draft('crm.commercial-proposal', {})).rejects.toThrow(
+      'The AI provider did not answer',
+    );
+
+    chatWithPrompt.mockRejectedValueOnce(new NotFoundException('Integration profile not found'));
+    await expect(service.draft('crm.commercial-proposal', {})).rejects.toThrow(
+      'Integration profile not found',
+    );
+  });
+
+  it('responde 404 para kit não registrado', async () => {
+    await expect(service.draft('crm.nao-existe', {})).rejects.toBeInstanceOf(NotFoundException);
+  });
+});

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,
+    };
+  }
+}