@hed-hog/core 0.0.399 → 0.0.401

package/src/utils/abbreviate-name.ts

@@ -0,0 +1,44 @@
+/**
+ * Partículas ignoradas ao escolher o "último sobrenome" — sem isso, "Maria de
+ * Souza" viraria "Maria de" em vez de "Maria Souza".
+ */
+const NAME_PARTICLES = new Set(['de', 'da', 'do', 'das', 'dos', 'e']);
+
+/**
+ * Abrevia um nome completo para "primeiro nome + último sobrenome", o formato
+ * usado nos templates de e-mail transacional (ex.: `operations-task-assigned`)
+ * pra não estampar o nome completo do colaborador — "João Henrique Cunha
+ * Rangel" vira "João Rangel".
+ *
+ * Partículas (de/da/do/das/dos/e) são ignoradas na escolha do último
+ * sobrenome, não removidas do nome inteiro — só afetam qual token conta como
+ * "o último". Nome com uma palavra só, vazio ou nulo passa como está (nada a
+ * abreviar).
+ */
+export function abbreviateName(fullName?: string | null): string {
+  const trimmed = (fullName ?? '').trim();
+  if (!trimmed) {
+    return trimmed;
+  }
+
+  const words = trimmed.split(/\s+/);
+  if (words.length === 1) {
+    return words[0];
+  }
+
+  const firstName = words[0];
+
+  // Anda de trás pra frente até achar um token que não seja partícula. Se
+  // todos os tokens depois do primeiro forem partícula (dado maltratado),
+  // cai no primeiro nome sozinho em vez de repetir "João de" ou "João João".
+  let lastIndex = words.length - 1;
+  while (lastIndex > 0 && NAME_PARTICLES.has(words[lastIndex].toLowerCase())) {
+    lastIndex--;
+  }
+
+  if (lastIndex === 0) {
+    return firstName;
+  }
+
+  return `${firstName} ${words[lastIndex]}`;
+}

package/src/utils/date-range-query.dto.ts

@@ -0,0 +1,56 @@
+import { Transform } from 'class-transformer';
+import { IsDateString, IsOptional } from 'class-validator';
+
+/**
+ * `?from=yyyy-MM-dd&to=yyyy-MM-dd` — o par padrão de recorte por período de
+ * toda listagem nova. Endpoint que já tem nome próprio (`dateFrom`/`dateTo` da
+ * fila, `createdAtFrom`/`createdAtTo` do mail-sent, `date_from`/`date_to` do
+ * sac) mantém o nome dele: só o que nasce daqui em diante usa `from`/`to`.
+ *
+ * Composto, e não herdado de `PaginationDTO`, porque quase todo adotante é o
+ * **segundo** argumento `@Query()` do controller, ao lado do `@Pagination()` —
+ * que descarta tudo que não é paginação. Carregar `page`/`pageSize` junto
+ * duplicaria campo que o DTO de filtro não é dono. Onde o DTO de filtro já
+ * estende `PaginationDTO`, o jeito de juntar os dois é o `IntersectionType`:
+ *
+ * ```ts
+ * export class ListContractsDto extends IntersectionType(
+ *   PaginationDTO,
+ *   DateRangeQueryDTO,
+ * ) {}
+ * ```
+ *
+ * Quem traduz este par para o `where` do banco é o `resolveDateRange` /
+ * `dateRangeWhere` (`./date-range`).
+ */
+
+/**
+ * O admin manda `?from=` quando o usuário **limpa** o campo. O `@IsOptional()`
+ * só pula `null`/`undefined`, então sem isto o campo limpo viraria 400 — uma
+ * regressão de tela causada por um parâmetro que nem deveria existir. O
+ * `@Transform` roda no `plainToInstance` do `ValidationPipe`, antes do
+ * `validate`, então a string vazia nunca chega ao validador.
+ */
+const blankToUndefined = ({ value }: { value: unknown }) => {
+  const raw = typeof value === 'string' ? value.trim() : value;
+
+  return raw === '' || raw === null ? undefined : raw;
+};
+
+export class DateRangeQueryDTO {
+  /** Primeiro dia do recorte, inclusive. `yyyy-MM-dd`. */
+  @IsOptional()
+  @Transform(blankToUndefined)
+  @IsDateString({}, { message: 'from must be a date in the yyyy-MM-dd format' })
+  from?: string;
+
+  /**
+   * Último dia do recorte, **inclusive** — é assim que o usuário lê o
+   * calendário. Quem converte para o `< to+1d` que o banco precisa é o
+   * `resolveDateRange`.
+   */
+  @IsOptional()
+  @Transform(blankToUndefined)
+  @IsDateString({}, { message: 'to must be a date in the yyyy-MM-dd format' })
+  to?: string;
+}

package/src/utils/date-range.spec.ts

@@ -0,0 +1,175 @@
+import { addIsoDays, dateRangeWhere, resolveDateRange } from './date-range';
+
+describe('resolveDateRange', () => {
+  it('devolve null quando não há período', () => {
+    expect(resolveDateRange()).toBeNull();
+    expect(resolveDateRange('', '')).toBeNull();
+    expect(resolveDateRange(null, null)).toBeNull();
+  });
+
+  it('só com `from`, limita apenas o início', () => {
+    const range = resolveDateRange('2026-08-01')!;
+
+    expect(range.gte).toEqual(new Date('2026-08-01T00:00:00.000Z'));
+    expect(range.lt).toBeUndefined();
+  });
+
+  it('só com `to`, limita apenas o fim', () => {
+    const range = resolveDateRange(undefined, '2026-08-31')!;
+
+    expect(range.lt).toEqual(new Date('2026-09-01T00:00:00.000Z'));
+    expect(range.gte).toBeUndefined();
+  });
+
+  /**
+   * O caso que os três serviços erravam: com `lte` + `new Date(to)` o dia 31
+   * inteiro ficava de fora, porque `'2026-08-31'` vira o INSTANTE
+   * `2026-08-31T00:00:00Z`.
+   */
+  it('inclui o dia final inteiro', () => {
+    const { lt } = resolveDateRange('2026-08-01', '2026-08-31')!;
+
+    expect(lt).toEqual(new Date('2026-09-01T00:00:00.000Z'));
+    expect(new Date('2026-08-31T23:59:59.999Z') < lt!).toBe(true);
+    expect(new Date('2026-09-01T00:00:00.000Z') < lt!).toBe(false);
+  });
+
+  it('atravessa a virada do mês e do ano', () => {
+    expect(resolveDateRange('2026-12-31', '2026-12-31')!.lt).toEqual(
+      new Date('2027-01-01T00:00:00.000Z'),
+    );
+  });
+
+  it('cobre o 29 de fevereiro em ano bissexto', () => {
+    expect(resolveDateRange('2028-02-28', '2028-02-29')!.lt).toEqual(
+      new Date('2028-03-01T00:00:00.000Z'),
+    );
+  });
+
+  it('inverte o período digitado de trás pra frente', () => {
+    expect(resolveDateRange('2026-08-31', '2026-08-01')).toEqual(
+      resolveDateRange('2026-08-01', '2026-08-31'),
+    );
+  });
+
+  it('trata data inválida como ausente, sem estourar', () => {
+    expect(resolveDateRange('31/08/2026', '2026-08-31')!.gte).toBeUndefined();
+    expect(resolveDateRange('2026-13-01')).toBeNull();
+    expect(resolveDateRange('2026-02-31')).toBeNull();
+    expect(resolveDateRange('ontem')).toBeNull();
+  });
+
+  it('aceita ISO completo e ignora a hora', () => {
+    expect(
+      resolveDateRange('2026-08-01T13:45:00.000Z', '2026-08-31T09:00:00Z'),
+    ).toEqual(resolveDateRange('2026-08-01', '2026-08-31'));
+  });
+
+  it('não limita o fim a agora — período no futuro continua aberto', () => {
+    // Contrato vigente, reunião agendada e assinatura a vencer dependem disso.
+    const { lt } = resolveDateRange('2099-01-01', '2099-12-31')!;
+
+    expect(lt).toEqual(new Date('2100-01-01T00:00:00.000Z'));
+    expect(lt!.getTime()).toBeGreaterThan(Date.now());
+  });
+
+  it('expõe as strings que o SQL cru precisa', () => {
+    const range = resolveDateRange('2026-08-01', '2026-08-31')!;
+
+    expect(range.fromIso).toBe('2026-08-01');
+    expect(range.toExclusiveIso).toBe('2026-09-01');
+  });
+});
+
+describe('resolveDateRange — fuso', () => {
+  it('desloca as bordas para o fuso pedido', () => {
+    // Em São Paulo (UTC-3) o dia civil começa às 03:00 UTC.
+    const range = resolveDateRange('2026-08-01', '2026-08-31', {
+      timezone: 'America/Sao_Paulo',
+    })!;
+
+    expect(range.gte).toEqual(new Date('2026-08-01T03:00:00.000Z'));
+    expect(range.lt).toEqual(new Date('2026-09-01T03:00:00.000Z'));
+  });
+
+  /**
+   * A armadilha da coluna `@db.Date`: o Prisma manda o parâmetro como `DATE` e
+   * o trunca pela leitura UTC. Meia-noite de 01/08 em Tóquio é
+   * `2026-07-31T15:00Z`, que truncaria para 31/07 e derrubaria um dia inteiro
+   * da consulta, sem erro nenhum. Por isso `dateOnly` ignora o fuso.
+   */
+  it('mantém `dateOnly` em UTC puro, mesmo com fuso a leste', () => {
+    const range = resolveDateRange('2026-08-01', '2026-08-31', {
+      timezone: 'Asia/Tokyo',
+    })!;
+
+    expect(range.gte).toEqual(new Date('2026-07-31T15:00:00.000Z'));
+    expect(range.dateOnly.gte).toEqual(new Date('2026-08-01T00:00:00.000Z'));
+    expect(range.dateOnly.lt).toEqual(new Date('2026-09-01T00:00:00.000Z'));
+  });
+
+  it('acerta a borda na virada do horário de verão', () => {
+    // Lisboa entra no horário de verão em 29/03/2026: antes UTC+0, depois +1.
+    const range = resolveDateRange('2026-03-28', '2026-03-30', {
+      timezone: 'Europe/Lisbon',
+    })!;
+
+    expect(range.gte).toEqual(new Date('2026-03-28T00:00:00.000Z'));
+    expect(range.lt).toEqual(new Date('2026-03-30T23:00:00.000Z'));
+  });
+
+  it('cai no UTC quando o fuso é desconhecido', () => {
+    expect(
+      resolveDateRange('2026-08-01', '2026-08-31', { timezone: 'Nao/Existe' }),
+    ).toEqual(resolveDateRange('2026-08-01', '2026-08-31'));
+  });
+});
+
+describe('addIsoDays', () => {
+  it('soma dias de calendário', () => {
+    expect(addIsoDays('2026-08-31', 1)).toBe('2026-09-01');
+    expect(addIsoDays('2026-12-31', 1)).toBe('2027-01-01');
+    expect(addIsoDays('2028-02-28', 1)).toBe('2028-02-29');
+    expect(addIsoDays('2026-09-01', -1)).toBe('2026-08-31');
+  });
+});
+
+describe('dateRangeWhere', () => {
+  it('devolve {} sem período, pra espalhar ser sempre seguro', () => {
+    expect(dateRangeWhere('created_at')).toEqual({});
+    expect(dateRangeWhere('created_at', '', '')).toEqual({});
+    expect({ deleted_at: null, ...dateRangeWhere('created_at') }).toEqual({
+      deleted_at: null,
+    });
+  });
+
+  it('monta o fragmento do Prisma', () => {
+    expect(dateRangeWhere('created_at', '2026-08-01', '2026-08-31')).toEqual({
+      created_at: {
+        gte: new Date('2026-08-01T00:00:00.000Z'),
+        lt: new Date('2026-09-01T00:00:00.000Z'),
+      },
+    });
+  });
+
+  it('usa as bordas UTC puras para coluna de data', () => {
+    expect(
+      dateRangeWhere('meeting_date', '2026-08-01', '2026-08-31', {
+        dateOnly: true,
+        timezone: 'America/Sao_Paulo',
+      }),
+    ).toEqual({
+      meeting_date: {
+        gte: new Date('2026-08-01T00:00:00.000Z'),
+        lt: new Date('2026-09-01T00:00:00.000Z'),
+      },
+    });
+  });
+
+  it('omite a chave ausente em vez de pô-la como undefined', () => {
+    const where = dateRangeWhere('created_at', '2026-08-01');
+
+    expect(Object.keys(where.created_at)).toEqual(['gte']);
+    expect('lt' in where.created_at).toBe(false);
+  });
+});

package/src/utils/date-range.ts

@@ -0,0 +1,246 @@
+/**
+ * Tradução única de `?from=yyyy-MM-dd&to=yyyy-MM-dd` para limites comparáveis
+ * no banco.
+ *
+ * A janela é **meio-aberta** — `[from 00:00, to+1d 00:00)` — e nunca inclusiva.
+ * `lte new Date('2026-08-31')` compara contra o *instante* `T00:00:00Z` e
+ * derruba o dia 31 inteiro; `lte 23:59:59.999` perde o último milissegundo e
+ * mente sobre o modelo de dados. A forma meio-aberta é a única que vale igual
+ * para coluna `@db.Date` e para coluna `@db.Timestamptz(6)`, sem flag nenhum.
+ *
+ * Diferenças de propósito para o `resolveRangeWindow` do operations
+ * (`libraries/operations/src/services/shared/operations-activity-window.helper.ts`),
+ * que serve relatório e não listagem:
+ *
+ * - sem `from` e sem `to` devolve `null` (= sem recorte), e não o dia de hoje:
+ *   listagem sem filtro tem de devolver tudo;
+ * - **não limita o fim em agora**: reunião de amanhã, contrato que vence em
+ *   2027 e assinatura com período à frente são justamente o que essas telas
+ *   procuram;
+ * - aceita janela aberta de um lado só.
+ *
+ * Os dois hão de convergir, mas depois: aquele alimenta o e-mail do relatório
+ * diário e depende do clamp.
+ */
+
+export interface DateRangeBounds {
+  gte?: Date;
+  lt?: Date;
+}
+
+export interface DateRange {
+  /** Início inclusivo, no fuso pedido. Ausente quando só veio `to`. */
+  gte?: Date;
+  /** Fim EXCLUSIVO (`to` + 1 dia), no fuso pedido. Ausente quando só veio `from`. */
+  lt?: Date;
+  /**
+   * As mesmas bordas em UTC puro — o que uma coluna `@db.Date` entende.
+   *
+   * O Prisma manda o parâmetro como `DATE` e o trunca pela leitura **UTC** do
+   * `Date`. Uma borda deslocada para fuso a leste derruba um dia inteiro sem
+   * erro nenhum: meia-noite de 01/09 em `Asia/Tokyo` é `2026-08-31T15:00Z`,
+   * que trunca para `2026-08-31`. Coluna de data pura não tem fuso, então
+   * converter fuso nela é sempre errado.
+   */
+  dateOnly: DateRangeBounds;
+  /** `yyyy-MM-dd` normalizado, já desinvertido. */
+  fromIso?: string;
+  /** `to + 1 dia`, para o `< $n::date` do SQL cru. */
+  toExclusiveIso?: string;
+}
+
+export interface DateRangeOptions {
+  /**
+   * Fuso IANA das bordas civis; o padrão é UTC, que é o fuso dos pods da API.
+   * Só afeta coluna com hora — veja `dateOnly`.
+   */
+  timezone?: string;
+}
+
+/** Tolera ISO completo: só o prefixo `yyyy-MM-dd` interessa. */
+const ISO_DATE_PREFIX = /^(\d{4})-(\d{2})-(\d{2})/;
+
+function normalizeTimezone(timezone?: string): string {
+  const candidate = String(timezone ?? '').trim();
+  if (!candidate) return 'UTC';
+
+  try {
+    new Intl.DateTimeFormat('en-US', { timeZone: candidate });
+    return candidate;
+  } catch {
+    // Fuso inventado não pode derrubar uma listagem: cai no fuso dos pods.
+    return 'UTC';
+  }
+}
+
+function toIsoDate(value?: string | null): string | null {
+  const match = ISO_DATE_PREFIX.exec(String(value ?? '').trim());
+  if (!match) return null;
+
+  const [, yearText, monthText, dayText] = match;
+  const year = Number(yearText);
+  const month = Number(monthText);
+  const day = Number(dayText);
+
+  // `2026-02-31` casa com o regex e o `Date.UTC` o aceita virando 03/03.
+  // Só a volta denuncia.
+  const probe = new Date(Date.UTC(year, month - 1, day));
+  if (
+    probe.getUTCFullYear() !== year ||
+    probe.getUTCMonth() !== month - 1 ||
+    probe.getUTCDate() !== day
+  ) {
+    return null;
+  }
+
+  return `${yearText}-${monthText}-${dayText}`;
+}
+
+/**
+ * Soma dias de **calendário**. Somar 86400000 ms a um instante zonado erra o
+ * dia em toda virada de horário de verão.
+ */
+export function addIsoDays(isoDate: string, days: number): string {
+  const [year, month, day] = isoDate.split('-').map(Number);
+
+  return new Date(Date.UTC(year, month - 1, day + days))
+    .toISOString()
+    .slice(0, 10);
+}
+
+function utcMidnight(isoDate: string): Date {
+  return new Date(`${isoDate}T00:00:00.000Z`);
+}
+
+/**
+ * Deslocamento do fuso, em ms, no instante informado. Formatar a data no fuso
+ * e reinterpretar as partes como UTC devolve o offset vigente — inclusive em
+ * fuso com horário de verão.
+ */
+function timezoneOffsetMs(at: Date, timezone: string): number {
+  const parts = new Intl.DateTimeFormat('en-US', {
+    timeZone: timezone,
+    hour12: false,
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+    hour: '2-digit',
+    minute: '2-digit',
+    second: '2-digit',
+  }).formatToParts(at);
+
+  const part = (type: string) =>
+    Number(parts.find((item) => item.type === type)?.value ?? 0);
+
+  const asUtc = Date.UTC(
+    part('year'),
+    part('month') - 1,
+    part('day'),
+    // Algumas engines devolvem "24" para a meia-noite em hour12:false.
+    part('hour') % 24,
+    part('minute'),
+    part('second'),
+  );
+
+  return asUtc - at.getTime();
+}
+
+/** Meia-noite civil de `isoDate` naquele fuso, como instante UTC. */
+function zonedMidnight(isoDate: string, timezone: string): Date {
+  if (timezone === 'UTC') return utcMidnight(isoDate);
+
+  const naive = Date.parse(`${isoDate}T00:00:00.000Z`);
+
+  // Duas passadas: a primeira usa o offset do palpite, a segunda o do instante
+  // já corrigido — é o que resolve a virada de horário de verão.
+  let utc = naive;
+  for (let pass = 0; pass < 2; pass += 1) {
+    utc = naive - timezoneOffsetMs(new Date(utc), timezone);
+  }
+
+  return new Date(utc);
+}
+
+/**
+ * Resolve o par `from`/`to` da query.
+ *
+ * Devolve `null` quando nenhuma das pontas é data utilizável — o que cobre de
+ * uma vez "o cliente não filtrou", "o cliente limpou o campo e mandou
+ * `?from=`" e "o cliente mandou `31/08/2026`". Filtro ilegível vira "sem
+ * filtro", não 500: o `ValidationPipe` barra o que dá para barrar na borda, e
+ * aqui dentro a listagem não pode cair.
+ *
+ * Intervalo invertido é desinvertido: arrastar o calendário de trás para
+ * frente não deve devolver lista vazia.
+ */
+export function resolveDateRange(
+  from?: string | null,
+  to?: string | null,
+  options: DateRangeOptions = {},
+): DateRange | null {
+  const timezone = normalizeTimezone(options.timezone);
+
+  let fromIso = toIsoDate(from);
+  let toIso = toIsoDate(to);
+
+  if (!fromIso && !toIso) return null;
+
+  if (fromIso && toIso && toIso < fromIso) {
+    [fromIso, toIso] = [toIso, fromIso];
+  }
+
+  const toExclusiveIso = toIso ? addIsoDays(toIso, 1) : undefined;
+
+  return {
+    gte: fromIso ? zonedMidnight(fromIso, timezone) : undefined,
+    lt: toExclusiveIso ? zonedMidnight(toExclusiveIso, timezone) : undefined,
+    dateOnly: {
+      gte: fromIso ? utcMidnight(fromIso) : undefined,
+      lt: toExclusiveIso ? utcMidnight(toExclusiveIso) : undefined,
+    },
+    fromIso: fromIso ?? undefined,
+    toExclusiveIso,
+  };
+}
+
+export interface DateRangeWhereOptions extends DateRangeOptions {
+  /**
+   * `true` para coluna `@db.Date`. Usa as bordas UTC puras, que são as únicas
+   * que o `DATE` do Postgres trunca para o dia certo.
+   */
+  dateOnly?: boolean;
+}
+
+/**
+ * Fragmento pronto para espalhar dentro de um `where` do Prisma:
+ *
+ * ```ts
+ * const where = {
+ *   deleted_at: null,
+ *   ...dateRangeWhere('created_at', filters?.from, filters?.to),
+ * };
+ * ```
+ *
+ * Devolve `{}` quando não há recorte, então espalhar é sempre seguro e não
+ * existe o caminho "montei um `created_at: {}` vazio". As chaves ausentes são
+ * omitidas de verdade, não postas como `undefined`.
+ */
+export function dateRangeWhere(
+  field: string,
+  from?: string | null,
+  to?: string | null,
+  options: DateRangeWhereOptions = {},
+): Record<string, DateRangeBounds> {
+  const range = resolveDateRange(from, to, options);
+  if (!range) return {};
+
+  const source = options.dateOnly
+    ? range.dateOnly
+    : { gte: range.gte, lt: range.lt };
+
+  const bounds: DateRangeBounds = {};
+  if (source.gte) bounds.gte = source.gte;
+  if (source.lt) bounds.lt = source.lt;
+
+  return Object.keys(bounds).length > 0 ? { [field]: bounds } : {};
+}

package/src/webhook-integration/webhook-utils.spec.ts

@@ -0,0 +1,67 @@
+import { describe, it, expect } from '@jest/globals';
+import { renderTemplate } from './webhook-utils';
+
+describe('renderTemplate', () => {
+  it('interpola valores simples e aninhados', () => {
+    expect(renderTemplate('olá {{name}}', { name: 'João' })).toBe('olá João');
+    expect(
+      renderTemplate('{{alerts.0.labels.severity}}', {
+        alerts: [{ labels: { severity: 'warning' } }],
+      }),
+    ).toBe('warning');
+  });
+
+  it('percorre listas com each', () => {
+    const out = renderTemplate('{{#each alerts}}[{{name}}]{{/each}}', {
+      alerts: [{ name: 'a' }, { name: 'b' }],
+    });
+    expect(out).toBe('[a][b]');
+  });
+
+  // O motivo dos helpers: o payload do Alertmanager traz status "firing" ou
+  // "resolved" e a mensagem tem de ser diferente em cada caso.
+  it('escolhe o ramo pelo status com o helper eq', () => {
+    const tpl = '{{#if (eq status "firing")}}ALERTA{{else}}NORMALIZOU{{/if}}';
+    expect(renderTemplate(tpl, { status: 'firing' })).toBe('ALERTA');
+    expect(renderTemplate(tpl, { status: 'resolved' })).toBe('NORMALIZOU');
+  });
+
+  it('compara número e string como equivalentes', () => {
+    // O payload vem de JSON externo: quem escreve o template não deve precisar
+    // saber se o produtor mandou 200 ou "200".
+    expect(renderTemplate('{{#if (eq code 200)}}ok{{/if}}', { code: '200' })).toBe('ok');
+    expect(renderTemplate('{{#if (eq code "200")}}ok{{/if}}', { code: 200 })).toBe('ok');
+  });
+
+  it('oferece ne, gt e lt', () => {
+    expect(renderTemplate('{{#if (ne a "x")}}dif{{/if}}', { a: 'y' })).toBe('dif');
+    expect(renderTemplate('{{#if (gt n 5)}}maior{{/if}}', { n: 6 })).toBe('maior');
+    expect(renderTemplate('{{#if (lt n 5)}}menor{{/if}}', { n: 4 })).toBe('menor');
+  });
+
+  it('normaliza caixa com upper e lower', () => {
+    expect(renderTemplate('{{upper s}}', { s: 'firing' })).toBe('FIRING');
+    expect(renderTemplate('{{lower s}}', { s: 'FIRING' })).toBe('firing');
+    // Ausente não pode virar "undefined" no meio da mensagem.
+    expect(renderTemplate('{{upper ausente}}', {})).toBe('');
+  });
+
+  it('mantém acentos e símbolos quando usa triple stash', () => {
+    // O destino é WhatsApp, não HTML: escapar viraria ' na tela do usuário.
+    const ctx = { texto: "capacidade 78% — 'atenção'" };
+    expect(renderTemplate('{{{texto}}}', ctx)).toBe("capacidade 78% — 'atenção'");
+  });
+
+  it('atravessa objetos e listas preservando os tipos que não são string', () => {
+    const out = renderTemplate(
+      { titulo: '{{name}}', ativo: true, tentativas: 3, tags: ['{{name}}'] },
+      { name: 'x' },
+    );
+    expect(out).toEqual({ titulo: 'x', ativo: true, tentativas: 3, tags: ['x'] });
+  });
+
+  it('devolve null e undefined sem tentar compilar', () => {
+    expect(renderTemplate(null, {})).toBeNull();
+    expect(renderTemplate(undefined, {})).toBeUndefined();
+  });
+});

package/src/webhook-integration/webhook-utils.ts

@@ -13,6 +13,32 @@ export function hashToken(token: string) {
   return createHash('sha256').update(token).digest('hex');
 }
 
+/**
+ * Handlebars puro não compara valores: `{{#if}}` só testa se algo é vazio. Sem
+ * isto um template não consegue reagir ao conteúdo do payload — o caso que
+ * motivou os helpers foi o webhook do Alertmanager, onde `status` chega como
+ * "firing" ou "resolved" e a mensagem precisa ser diferente em cada caso (mandar
+ * o texto de alerta quando o problema acabou é pior do que não mandar nada).
+ *
+ * Registrados uma vez, no import do módulo: `Handlebars.registerHelper` é global
+ * e chamá-lo a cada render só repetiria trabalho.
+ */
+const HELPERS: Record<string, (...args: any[]) => any> = {
+  // `{{#if (eq status "firing")}}`. A comparação é frouxa de propósito: o payload
+  // vem de JSON externo, onde 200 e "200" são a mesma coisa para quem escreve o
+  // template.
+  eq: (a: unknown, b: unknown) => String(a) === String(b),
+  ne: (a: unknown, b: unknown) => String(a) !== String(b),
+  gt: (a: unknown, b: unknown) => Number(a) > Number(b),
+  lt: (a: unknown, b: unknown) => Number(a) < Number(b),
+  upper: (value: unknown) => String(value ?? '').toUpperCase(),
+  lower: (value: unknown) => String(value ?? '').toLowerCase(),
+};
+
+for (const [name, fn] of Object.entries(HELPERS)) {
+  Handlebars.registerHelper(name, fn);
+}
+
 export function renderTemplate(source: unknown, context: Record<string, any>) {
   if (source === undefined || source === null) {
     return source;