@hed-hog/core 0.0.399 → 0.0.401

package/src/captcha/captcha.service.ts

@@ -21,6 +21,26 @@ export interface CaptchaPublicConfig {
   site_key: string | null;
 }
 
+/**
+ * Contexto da submissao que esta sendo verificada. Tudo opcional: uma superficie
+ * que ainda nao manda `action` continua passando, o que permite subir o backend
+ * antes do front sem derrubar quem esta com bundle antigo em cache.
+ */
+export interface CaptchaVerifyContext {
+  /** IP do visitante (X-Forwarded-For repassado pelo BFF), nao o IP do pod. */
+  remoteIp?: string | null;
+  /** `data-action` que a superficie manda no widget. */
+  expectedAction?: string | null;
+}
+
+/** Resposta do siteverify que nos interessa. Os provedores mandam mais campos. */
+interface SiteverifyResponse {
+  success?: boolean;
+  action?: string;
+  hostname?: string;
+  'error-codes'?: string[];
+}
+
 interface AltchaPayload {
   algorithm: string;
   challenge: string;
@@ -29,6 +49,12 @@ interface AltchaPayload {
   signature: string;
 }
 
+/** Teto do token aceito pelo siteverify; acima disso nem vale a viagem de rede. */
+const MAX_TOKEN_LENGTH = 2048;
+
+/** Timeout da chamada ao provedor: sem ele um provedor lento prende o request. */
+const SITEVERIFY_TIMEOUT_MS = 10_000;
+
 /**
  * Server-side CAPTCHA verification shared by every public form in the platform.
  *
@@ -45,19 +71,36 @@ export class CaptchaService {
   /**
    * Verifies a token against the provider configured in an integration profile.
    * Throws `BadRequestException` when the challenge does not check out.
+   *
+   * The profile can be addressed by numeric id or by slug. Forms and channels
+   * hold a real FK (`captcha_integration_profile_id`), but a setting picked
+   * through the admin's entity-picker stores the profile *slug* — as
+   * `commerce-back-in-stock-captcha-profile-id` does. Accepting both keeps a
+   * profile chosen on screen from silently failing the challenge shut.
    */
   async verifyForProfile(
-    integrationProfileId: number | null | undefined,
+    integrationProfileRef: number | string | null | undefined,
     token: string | null | undefined,
+    context: CaptchaVerifyContext = {},
   ): Promise<void> {
-    if (!integrationProfileId) {
+    const ref =
+      typeof integrationProfileRef === 'string'
+        ? integrationProfileRef.trim()
+        : integrationProfileRef;
+
+    // `'0'` is the legacy default of the settings named `...-profile-id`: it is
+    // nobody's id and nobody's slug.
+    if (!ref || ref === '0') {
       throw new BadRequestException(
         'CAPTCHA is enabled but no integration profile is configured.',
       );
     }
 
+    const numericId =
+      typeof ref === 'number' ? ref : /^\d+$/.test(ref) ? Number(ref) : null;
+
     const profile = await (this.prisma as any).integration_profile.findFirst({
-      where: { id: integrationProfileId },
+      where: numericId ? { id: numericId } : { slug: String(ref) },
       select: {
         config: true,
         integration_provider: { select: { slug: true } },
@@ -72,6 +115,7 @@ export class CaptchaService {
       token ?? '',
       profile.integration_provider?.slug as string,
       (profile.config ?? {}) as Record<string, string>,
+      context,
     );
   }
 
@@ -80,25 +124,32 @@ export class CaptchaService {
     token: string,
     providerSlug: string,
     config: Record<string, string>,
+    context: CaptchaVerifyContext = {},
   ): Promise<void> {
     if (!token) {
       throw new BadRequestException('CAPTCHA token is required.');
     }
 
+    if (token.length > MAX_TOKEN_LENGTH) {
+      throw new BadRequestException('CAPTCHA token is malformed.');
+    }
+
     switch (providerSlug) {
       case 'recaptcha':
         await this.verifyRemote(
           'https://www.google.com/recaptcha/api/siteverify',
-          config.secret_key,
+          config,
           token,
+          context,
         );
         break;
 
       case 'cloudflare-turnstile':
         await this.verifyRemote(
           'https://challenges.cloudflare.com/turnstile/v0/siteverify',
-          config.secret_key,
+          config,
           token,
+          context,
         );
         break;
 
@@ -148,16 +199,82 @@ export class CaptchaService {
     return value ? String(value) : null;
   }
 
+  /**
+   * Hostnames que o perfil aceita, em `config.hostnames` (separados por virgula).
+   * Vazio significa "nao confira" - todo perfil ja existente continua valendo.
+   */
+  static parseHostnames(config: Record<string, unknown> | null): Set<string> {
+    const raw = config?.hostnames ?? config?.allowed_hostnames;
+    return new Set(
+      String(raw ?? '')
+        .split(',')
+        .map((hostname) => hostname.trim().toLowerCase())
+        .filter(Boolean),
+    );
+  }
+
+  /**
+   * Chamada canonica de siteverify: manda o IP do visitante, tem timeout, e
+   * confere `action` e `hostname` alem do `success`.
+   *
+   * Toda falha - rede, HTTP nao-2xx, corpo que nao e JSON - vira falha de
+   * CAPTCHA. Deixar a excecao subir crua transformaria um solavanco do provedor em
+   * 500, e o visitante veria "erro do servidor" no lugar de "tente de novo".
+   */
   private async verifyRemote(
     url: string,
-    secret: string,
+    config: Record<string, string>,
     token: string,
+    context: CaptchaVerifyContext,
   ): Promise<void> {
-    const body = new URLSearchParams({ secret, response: token });
-    const response = await fetch(url, { method: 'POST', body });
-    const json = (await response.json()) as { success: boolean };
+    const body = new URLSearchParams({
+      secret: config.secret_key,
+      response: token,
+    });
+
+    if (context.remoteIp) {
+      body.set('remoteip', context.remoteIp);
+    }
+
+    let result: SiteverifyResponse;
+    try {
+      const response = await fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        signal: AbortSignal.timeout(SITEVERIFY_TIMEOUT_MS),
+        body,
+      });
+
+      if (!response.ok) {
+        throw new Error(`siteverify ${response.status}`);
+      }
+
+      result = (await response.json()) as SiteverifyResponse;
+    } catch {
+      throw new BadRequestException('CAPTCHA validation failed.');
+    }
+
+    if (!result?.success) {
+      throw new BadRequestException('CAPTCHA validation failed.');
+    }
+
+    // As duas checagens abaixo so valem quando os dois lados informaram o campo:
+    // o reCAPTCHA v2 nao devolve `action`, e um perfil sem `hostnames` nao pediu
+    // conferencia de origem.
+    if (
+      context.expectedAction &&
+      result.action &&
+      result.action !== context.expectedAction
+    ) {
+      throw new BadRequestException('CAPTCHA validation failed.');
+    }
 
-    if (!json.success) {
+    const hostnames = CaptchaService.parseHostnames(config);
+    if (
+      hostnames.size > 0 &&
+      result.hostname &&
+      !hostnames.has(result.hostname.toLowerCase())
+    ) {
       throw new BadRequestException('CAPTCHA validation failed.');
     }
   }

package/src/core.module.ts

@@ -25,6 +25,8 @@ import { LeakedPasswordModule } from './leaked-password/leaked-password.module';
 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';
@@ -33,6 +35,7 @@ import { NotificationModule } from './notification/notification.module';
 import { OAuthModule } from './oauth/oauth.module';
 import { PresenceModule } from './presence/presence.module';
 import { RealtimeModule } from './realtime/realtime.module';
+import { RedisModule } from './redis/redis.module';
 import { PdfModule } from './pdf/pdf.module';
 import { ProfileModule } from './profile/profile.module';
 import { RoleModule } from './role/role.module';
@@ -87,6 +90,8 @@ import { WhatsappSenderModule } from './whatsapp-sender/whatsapp-sender.module';
     forwardRef(() => IncidentModule),
     forwardRef(() => LeakedPasswordModule),
     forwardRef(() => MailModule),
+    forwardRef(() => MessageTemplateModule),
+    forwardRef(() => DocumentKitModule),
     forwardRef(() => MailLayoutModule),
     forwardRef(() => IntegrationProfileModule),
     forwardRef(() => WhatsappSenderModule),
@@ -110,6 +115,7 @@ import { WhatsappSenderModule } from './whatsapp-sender/whatsapp-sender.module';
     forwardRef(() => AccessLogModule),
     forwardRef(() => RealtimeModule),
     forwardRef(() => PresenceModule),
+    RedisModule,
     MailboxModule,
 
     MeetingModule,
@@ -120,6 +126,8 @@ import { WhatsappSenderModule } from './whatsapp-sender/whatsapp-sender.module';
     IncidentModule,
     LeakedPasswordModule,
     MailModule,
+    MessageTemplateModule,
+    DocumentKitModule,
     MailLayoutModule,
     IntegrationProfileModule,
     WhatsappSenderModule,
@@ -151,6 +159,7 @@ import { WhatsappSenderModule } from './whatsapp-sender/whatsapp-sender.module';
     AccessLogModule,
     RealtimeModule,
     PresenceModule,
+    RedisModule,
     CaptchaModule,
   ],
   providers: [

package/src/dashboard/dashboard-component-role/dashboard-component-role.service.ts

@@ -11,6 +11,7 @@ import {
     CreateDashboardComponentRoleBatchDTO,
     CreateDashboardComponentRoleDTO,
 } from './dto';
+import { DASHBOARD_COMPONENT_ROLE_SORT } from './dashboard-component-role.sort';
 
 @Injectable()
 export class DashboardComponentRoleService {
@@ -46,11 +47,9 @@ export class DashboardComponentRoleService {
             },
           },
         },
-        orderBy: {
-          id: 'desc',
-        },
       },
       'dashboardComponentRole',
+      { sort: DASHBOARD_COMPONENT_ROLE_SORT },
     );
   }
 

package/src/dashboard/dashboard-component-role/dashboard-component-role.sort.ts

@@ -0,0 +1,18 @@
+import { defineSortable } from '@hed-hog/api-pagination';
+
+/**
+ * Campos ordenáveis de `dashboard_component_role`. Nomes localizados
+ * (`dashboard_component_locale`/`role_locale`) ficam de fora — relação de
+ * locale, dois saltos. `component_slug`/`role_slug` ordenam pelo slug da
+ * relação to-one, que o Prisma já suporta direto.
+ */
+export const DASHBOARD_COMPONENT_ROLE_SORT = defineSortable(
+  {
+    id: { initialOrder: 'desc' },
+    component_slug: {
+      orderBy: (dir) => ({ dashboard_component: { slug: dir } }),
+    },
+    role_slug: { orderBy: (dir) => ({ role: { slug: dir } }) },
+  },
+  { default: 'id', defaultOrder: 'desc' },
+);

package/src/dashboard/dashboard-item/dashboard-item.service.ts

@@ -8,6 +8,7 @@ import {
   NotFoundException
 } from '@nestjs/common';
 import { CreateDashboardItemDTO } from './dto';
+import { DASHBOARD_ITEM_SORT } from './dashboard-item.sort';
 
 @Injectable()
 export class DashboardItemService {
@@ -46,11 +47,9 @@ export class DashboardItemService {
             },
           },
         },
-        orderBy: {
-          id: 'desc',
-        },
       },
       'dashboardItem',
+      { sort: DASHBOARD_ITEM_SORT },
     );
   }
 

package/src/dashboard/dashboard-item/dashboard-item.sort.ts

@@ -0,0 +1,19 @@
+import { defineSortable } from '@hed-hog/api-pagination';
+
+/**
+ * Campos ordenáveis de `dashboard_item`. Os nomes localizados exibidos na
+ * tela (`dashboard.dashboard_locale.name`, `dashboard_component.
+ * dashboard_component_locale.name`) ficam de fora — relação de locale, dois
+ * saltos a partir de `dashboard_item`. `dashboard_slug`/`component_slug`
+ * ordenam pelo slug da relação to-one, que o Prisma já suporta direto.
+ */
+export const DASHBOARD_ITEM_SORT = defineSortable(
+  {
+    id: { initialOrder: 'desc' },
+    dashboard_slug: { orderBy: (dir) => ({ dashboard: { slug: dir } }) },
+    component_slug: {
+      orderBy: (dir) => ({ dashboard_component: { slug: dir } }),
+    },
+  },
+  { default: 'id', defaultOrder: 'desc' },
+);

package/src/dashboard/dashboard-role/dashboard-role.service.ts

@@ -11,6 +11,7 @@ import {
     CreateDashboardRoleBatchDTO,
     CreateDashboardRoleDTO,
 } from './dto';
+import { DASHBOARD_ROLE_SORT } from './dashboard-role.sort';
 
 @Injectable()
 export class DashboardRoleService {
@@ -46,11 +47,9 @@ export class DashboardRoleService {
             },
           },
         },
-        orderBy: {
-          id: 'desc',
-        },
       },
       'dashboardRole',
+      { sort: DASHBOARD_ROLE_SORT },
     );
   }
 

package/src/dashboard/dashboard-role/dashboard-role.sort.ts

@@ -0,0 +1,16 @@
+import { defineSortable } from '@hed-hog/api-pagination';
+
+/**
+ * Campos ordenáveis de `dashboard_role`. Nomes localizados
+ * (`dashboard_locale`/`role_locale`) ficam de fora — relação de locale, dois
+ * saltos. `dashboard_slug`/`role_slug` ordenam pelo slug da relação to-one,
+ * que o Prisma já suporta direto.
+ */
+export const DASHBOARD_ROLE_SORT = defineSortable(
+  {
+    id: { initialOrder: 'desc' },
+    dashboard_slug: { orderBy: (dir) => ({ dashboard: { slug: dir } }) },
+    role_slug: { orderBy: (dir) => ({ role: { slug: dir } }) },
+  },
+  { default: 'id', defaultOrder: 'desc' },
+);

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