@hed-hog/core 0.0.386 → 0.0.390

package/src/incident/incident-notifier.service.ts

@@ -0,0 +1,241 @@
+import { PrismaService } from '@hed-hog/api-prisma';
+import { forwardRef, Inject, Injectable, Logger } from '@nestjs/common';
+import { buildWhatsappOfficialConfigFromIntegration } from '../integration-profile/integration-profile.utils';
+import { MailService } from '../mail/mail.service';
+import { SettingService } from '../setting/setting.service';
+
+export type IncidentSeverity = 'warning' | 'error' | 'critical';
+
+export interface NotifiableIncident {
+  id: number;
+  source: string;
+  code: string;
+  severity: IncidentSeverity;
+  message: string;
+  occurrences: number;
+  context?: Record<string, unknown> | null;
+  notifiedAt?: Date | null;
+  reason: 'created' | 'reopened';
+}
+
+const SEVERITY_ORDER: Record<IncidentSeverity, number> = {
+  warning: 0,
+  error: 1,
+  critical: 2,
+};
+
+/**
+ * Fonte reservada às falhas do próprio aviso. Nunca notifica — senão um SMTP
+ * fora do ar geraria aviso, que falharia, que geraria outro aviso, em laço.
+ */
+export const INCIDENT_NOTIFY_SOURCE = 'core.incident-notify';
+
+const SETTING_KEYS = [
+  'incident.notify-enabled',
+  'incident.notify-min-severity',
+  'incident.notify-cooldown-minutes',
+  'incident.notify-email-to',
+  'incident.notify-whatsapp-profile',
+  'incident.notify-whatsapp-phone-number-id',
+  'incident.notify-whatsapp-to',
+  'incident.notify-whatsapp-template',
+  'incident.notify-whatsapp-template-language',
+];
+
+@Injectable()
+export class IncidentNotifierService {
+  private readonly logger = new Logger(IncidentNotifierService.name);
+
+  constructor(
+    @Inject(forwardRef(() => PrismaService)) private readonly prisma: PrismaService,
+    @Inject(forwardRef(() => SettingService)) private readonly setting: SettingService,
+    @Inject(forwardRef(() => MailService)) private readonly mail: MailService,
+  ) {}
+
+  /** Nunca lança: o aviso é o último elo, não pode derrubar nada acima dele. */
+  async notify(incident: NotifiableIncident): Promise<void> {
+    try {
+      if (incident.source === INCIDENT_NOTIFY_SOURCE) return;
+
+      const settings = await this.setting.getSettingValues(SETTING_KEYS);
+
+      if (!this.isTrue(settings['incident.notify-enabled'])) return;
+
+      const minSeverity = this.parseSeverity(settings['incident.notify-min-severity']);
+      if (SEVERITY_ORDER[incident.severity] < SEVERITY_ORDER[minSeverity]) return;
+
+      if (this.isWithinCooldown(incident, settings['incident.notify-cooldown-minutes'])) return;
+
+      const subject = `[${incident.severity.toUpperCase()}] ${incident.source} — ${incident.code}`;
+      const sent: string[] = [];
+
+      if (await this.sendEmail(settings['incident.notify-email-to'], subject, incident)) {
+        sent.push('email');
+      }
+
+      if (await this.sendWhatsapp(settings, subject, incident)) {
+        sent.push('whatsapp');
+      }
+
+      if (!sent.length) return;
+
+      await (this.prisma as any).system_incident.update({
+        where: { id: incident.id },
+        data: { notified_at: new Date() },
+      });
+
+      this.logger.log(`Incidente ${incident.id} avisado via ${sent.join(', ')}`);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      this.logger.warn(`Falha ao avisar sobre o incidente ${incident.id}: ${message}`);
+    }
+  }
+
+  private isWithinCooldown(incident: NotifiableIncident, raw: unknown): boolean {
+    // Reabertura sempre avisa: o incidente foi dado como resolvido e voltou.
+    if (incident.reason === 'reopened') return false;
+    if (!incident.notifiedAt) return false;
+
+    const minutes = Number(raw);
+    const cooldown = Number.isFinite(minutes) && minutes > 0 ? minutes : 60;
+
+    return Date.now() - new Date(incident.notifiedAt).getTime() < cooldown * 60_000;
+  }
+
+  private async sendEmail(
+    raw: unknown,
+    subject: string,
+    incident: NotifiableIncident,
+  ): Promise<boolean> {
+    const recipients = String(raw ?? '')
+      .split(',')
+      .map((item) => item.trim())
+      .filter(Boolean);
+
+    if (!recipients.length) return false;
+
+    const html = [
+      `<p><strong>${this.escape(incident.message)}</strong></p>`,
+      `<p>Origem: ${this.escape(incident.source)}<br>`,
+      `Código: ${this.escape(incident.code)}<br>`,
+      `Severidade: ${this.escape(incident.severity)}<br>`,
+      `Ocorrências: ${incident.occurrences}</p>`,
+      incident.context
+        ? `<pre>${this.escape(JSON.stringify(incident.context, null, 2))}</pre>`
+        : '',
+    ].join('');
+
+    // sendRawMail não depende de template cadastrado: um alerta de infra não
+    // pode depender de seed de banco para sair.
+    for (const to of recipients) {
+      await this.mail.sendRawMail({ to, subject, html });
+    }
+
+    return true;
+  }
+
+  private async sendWhatsapp(
+    settings: Record<string, unknown>,
+    subject: string,
+    incident: NotifiableIncident,
+  ): Promise<boolean> {
+    const profileSlug = String(settings['incident.notify-whatsapp-profile'] ?? '').trim();
+    const phoneNumberId = String(settings['incident.notify-whatsapp-phone-number-id'] ?? '').trim();
+    const to = String(settings['incident.notify-whatsapp-to'] ?? '').replace(/\D/g, '');
+
+    if (!profileSlug || !phoneNumberId || !to) return false;
+
+    const profile = await this.prisma.integration_profile.findUnique({
+      where: { slug: profileSlug },
+      select: { config: true },
+    });
+
+    if (!profile) {
+      this.logger.warn(`Perfil de integração "${profileSlug}" não encontrado para aviso.`);
+      return false;
+    }
+
+    const cfg = buildWhatsappOfficialConfigFromIntegration(profile.config);
+
+    if (!cfg.accessToken) {
+      this.logger.warn(`Perfil "${profileSlug}" sem access token.`);
+      return false;
+    }
+
+    const template = String(settings['incident.notify-whatsapp-template'] ?? '').trim();
+    const language =
+      String(settings['incident.notify-whatsapp-template-language'] ?? '').trim() || 'pt_BR';
+
+    // A Meta só aceita mensagem iniciada pela empresa através de template
+    // aprovado. Sem template, o texto livre só é entregue se o destinatário
+    // tiver falado com o número nas últimas 24h.
+    const body = template
+      ? {
+          messaging_product: 'whatsapp',
+          to,
+          type: 'template',
+          template: {
+            name: template,
+            language: { code: language },
+            components: [
+              {
+                type: 'body',
+                parameters: [
+                  { type: 'text', text: subject },
+                  { type: 'text', text: incident.message.slice(0, 400) },
+                ],
+              },
+            ],
+          },
+        }
+      : {
+          messaging_product: 'whatsapp',
+          to,
+          type: 'text',
+          text: { body: `${subject}\n\n${incident.message}`.slice(0, 4000) },
+        };
+
+    const url = `https://graph.facebook.com/${cfg.graphApiVersion}/${encodeURIComponent(
+      phoneNumberId,
+    )}/messages`;
+
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${cfg.accessToken}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(body),
+    });
+
+    if (!response.ok) {
+      const payload = (await response.json().catch(() => ({}))) as {
+        error?: { message?: string };
+      };
+      this.logger.warn(
+        `WhatsApp recusou o aviso (HTTP ${response.status}): ${
+          payload?.error?.message ?? 'sem detalhe'
+        }${template ? '' : ' — sem template configurado, a entrega só funciona na janela de 24h'}`,
+      );
+      return false;
+    }
+
+    return true;
+  }
+
+  private parseSeverity(raw: unknown): IncidentSeverity {
+    const value = String(raw ?? '').trim().toLowerCase();
+    return value === 'warning' || value === 'error' || value === 'critical' ? value : 'critical';
+  }
+
+  private isTrue(value: unknown): boolean {
+    return value === true || value === 'true';
+  }
+
+  private escape(value: string): string {
+    return String(value ?? '')
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;');
+  }
+}

package/src/incident/incident.controller.ts

@@ -0,0 +1,38 @@
+import { Role, User } from '@hed-hog/api';
+import { Pagination } from '@hed-hog/api-pagination';
+import { Controller, Get, Inject, Param, Patch, Query, forwardRef } from '@nestjs/common';
+import { IncidentService, type IncidentSeverity } from './incident.service';
+
+@Role()
+@Controller('incident')
+export class IncidentController {
+  constructor(
+    @Inject(forwardRef(() => IncidentService))
+    private readonly incidentService: IncidentService,
+  ) {}
+
+  @Get()
+  async list(
+    @Pagination() paginationParams,
+    @Query('source') source?: string,
+    @Query('severity') severity?: IncidentSeverity,
+    @Query('status') status?: 'open' | 'resolved' | 'all',
+  ) {
+    return this.incidentService.list({ ...paginationParams, source, severity, status });
+  }
+
+  @Get('summary')
+  async summary() {
+    return this.incidentService.summary();
+  }
+
+  @Patch(':id/resolve')
+  async resolve(@Param('id') id: string, @User() user) {
+    return this.incidentService.resolve(Number(id), user?.id);
+  }
+
+  @Patch(':id/reopen')
+  async reopen(@Param('id') id: string) {
+    return this.incidentService.reopen(Number(id));
+  }
+}

package/src/incident/incident.module.ts

@@ -0,0 +1,19 @@
+import { PaginationModule } from '@hed-hog/api-pagination';
+import { PrismaModule } from '@hed-hog/api-prisma';
+import { forwardRef, Global, Module } from '@nestjs/common';
+import { IncidentNotifierService } from './incident-notifier.service';
+import { IncidentController } from './incident.controller';
+import { IncidentService } from './incident.service';
+
+/**
+ * `@Global()` de propósito: qualquer módulo que engula uma falha deve conseguir
+ * registrá-la sem precisar importar mais nada.
+ */
+@Global()
+@Module({
+  imports: [forwardRef(() => PrismaModule), forwardRef(() => PaginationModule)],
+  controllers: [IncidentController],
+  providers: [IncidentService, IncidentNotifierService],
+  exports: [IncidentService, IncidentNotifierService],
+})
+export class IncidentModule {}

package/src/incident/incident.service.spec.ts

@@ -0,0 +1,150 @@
+import { beforeEach, describe, expect, it, jest } from '@jest/globals';
+import { IncidentService } from './incident.service';
+
+const makeDeps = () => ({
+  prisma: {
+    system_incident: {
+      findUnique: jest.fn(async () => null),
+      upsert: jest.fn(async () => ({ id: 1, occurrences: 1 })),
+      count: jest.fn(async () => 0),
+      groupBy: jest.fn(async () => []),
+      update: jest.fn(async () => ({ id: 1 })),
+    },
+  },
+  pagination: { paginate: jest.fn(async () => ({ data: [], total: 0 })) },
+  notifier: { notify: jest.fn(async () => undefined) },
+});
+
+const makeService = (deps: any) => new IncidentService(deps.prisma as any, deps.pagination as any, deps.notifier as any);
+
+describe('IncidentService.persist', () => {
+  beforeEach(() => jest.clearAllMocks());
+
+  it('agrupa por fingerprint em vez de criar uma linha por ocorrência', async () => {
+    const deps = makeDeps();
+    await makeService(deps).persist({
+      source: 'core.mail',
+      code: 'mail_send_failed',
+      message: 'SMTP timeout',
+      key: 'auth-login-new-device',
+    });
+
+    const [args] = deps.prisma.system_incident.upsert.mock.calls[0] as [any];
+    expect(args.where.fingerprint).toMatch(/^[0-9a-f]{64}$/);
+    expect(args.update.occurrences).toEqual({ increment: 1 });
+    expect(args.create.occurrences).toBe(1);
+  });
+
+  it('o mesmo (source, code, key) gera o mesmo fingerprint', async () => {
+    const deps = makeDeps();
+    const service = makeService(deps);
+    const input = { source: 'core.mail', code: 'x', message: 'm', key: 'slug-a' };
+
+    await service.persist(input);
+    await service.persist({ ...input, message: 'outra mensagem' });
+
+    const [a] = deps.prisma.system_incident.upsert.mock.calls[0] as [any];
+    const [b] = deps.prisma.system_incident.upsert.mock.calls[1] as [any];
+    expect(a.where.fingerprint).toBe(b.where.fingerprint);
+  });
+
+  it('key diferente gera incidente diferente', async () => {
+    const deps = makeDeps();
+    const service = makeService(deps);
+
+    await service.persist({ source: 'core.mail', code: 'x', message: 'm', key: 'slug-a' });
+    await service.persist({ source: 'core.mail', code: 'x', message: 'm', key: 'slug-b' });
+
+    const [a] = deps.prisma.system_incident.upsert.mock.calls[0] as [any];
+    const [b] = deps.prisma.system_incident.upsert.mock.calls[1] as [any];
+    expect(a.where.fingerprint).not.toBe(b.where.fingerprint);
+  });
+
+  it('reabre um incidente que voltou a acontecer', async () => {
+    const deps = makeDeps();
+    await makeService(deps).persist({ source: 's', code: 'c', message: 'm' });
+
+    const [args] = deps.prisma.system_incident.upsert.mock.calls[0] as [any];
+    expect(args.update.resolved_at).toBeNull();
+    expect(args.update.resolved_by).toBeNull();
+  });
+
+  it('ignora registro sem source ou code', async () => {
+    const deps = makeDeps();
+    const service = makeService(deps);
+
+    await service.persist({ source: '', code: 'c', message: 'm' });
+    await service.persist({ source: 's', code: '  ', message: 'm' });
+
+    expect(deps.prisma.system_incident.upsert).not.toHaveBeenCalled();
+  });
+
+  it('trunca mensagem gigante para não inchar a tabela', async () => {
+    const deps = makeDeps();
+    await makeService(deps).persist({ source: 's', code: 'c', message: 'x'.repeat(5000) });
+
+    const [args] = deps.prisma.system_incident.upsert.mock.calls[0] as [any];
+    expect(args.create.message.length).toBe(2000);
+  });
+});
+
+describe('IncidentService.record', () => {
+  beforeEach(() => jest.clearAllMocks());
+
+  it('nunca lança — o remédio não pode virar a doença', async () => {
+    const deps = makeDeps();
+    deps.prisma.system_incident.upsert = jest.fn(async () => {
+      throw new Error('banco fora do ar');
+    });
+
+    expect(() => makeService(deps).record({ source: 's', code: 'c', message: 'm' })).not.toThrow();
+    // Deixa o rejection assíncrono resolver antes do teste terminar.
+    await new Promise((resolve) => setImmediate(resolve));
+  });
+});
+
+describe('IncidentService.list', () => {
+  beforeEach(() => jest.clearAllMocks());
+
+  it('mostra só os abertos por padrão — a tela existe para o que pede ação', async () => {
+    const deps = makeDeps();
+    await makeService(deps).list({});
+
+    const [, , options] = deps.pagination.paginate.mock.calls[0] as [any, any, any];
+    expect(options.where.resolved_at).toBeNull();
+    expect(options.orderBy).toEqual({ last_seen_at: 'desc' });
+  });
+
+  it('filtra por resolvidos e por todos', async () => {
+    const deps = makeDeps();
+    const service = makeService(deps);
+
+    await service.list({ status: 'resolved' });
+    await service.list({ status: 'all' });
+
+    const [, , resolvidos] = deps.pagination.paginate.mock.calls[0] as [any, any, any];
+    const [, , todos] = deps.pagination.paginate.mock.calls[1] as [any, any, any];
+    expect(resolvidos.where.resolved_at).toEqual({ not: null });
+    expect(todos.where.resolved_at).toBeUndefined();
+  });
+
+  it('busca por mensagem, código e origem', async () => {
+    const deps = makeDeps();
+    await makeService(deps).list({ search: 'smtp' });
+
+    const [, , options] = deps.pagination.paginate.mock.calls[0] as [any, any, any];
+    expect(options.where.OR).toHaveLength(3);
+  });
+});
+
+describe('IncidentService.resolve', () => {
+  it('registra quem resolveu', async () => {
+    const deps = makeDeps();
+    await makeService(deps).resolve(7, 42);
+
+    const [args] = deps.prisma.system_incident.update.mock.calls[0] as [any];
+    expect(args.where).toEqual({ id: 7 });
+    expect(args.data.resolved_by).toBe(42);
+    expect(args.data.resolved_at).toBeInstanceOf(Date);
+  });
+});

package/src/incident/incident.service.ts

@@ -0,0 +1,209 @@
+import { PageOrderDirection, PaginationService } from '@hed-hog/api-pagination';
+import { PrismaService } from '@hed-hog/api-prisma';
+import { forwardRef, Inject, Injectable, Logger } from '@nestjs/common';
+import { createHash } from 'crypto';
+import { IncidentNotifierService } from './incident-notifier.service';
+
+export type IncidentSeverity = 'warning' | 'error' | 'critical';
+
+export interface RecordIncidentInput {
+  /** `<modulo>.<area>`, ex.: `core.mail`, `legacy.reconcile`. */
+  source: string;
+  /** Identificador estável da falha, ex.: `mail_send_failed`. */
+  code: string;
+  message: string;
+  severity?: IncidentSeverity;
+  /**
+   * Torna o incidente distinto dentro de `(source, code)`. Use algo estável e
+   * de baixa cardinalidade — o slug do template, o id do provider. **Nunca** um
+   * id de usuário ou timestamp: viraria uma linha por ocorrência, que é
+   * exatamente o que esta tabela existe para evitar.
+   */
+  key?: string;
+  context?: Record<string, unknown>;
+}
+
+export interface IncidentListParams {
+  page?: number;
+  pageSize?: number;
+  search?: string;
+  sortField?: string;
+  sortOrder?: PageOrderDirection;
+  fields?: string;
+  source?: string;
+  severity?: IncidentSeverity;
+  status?: 'open' | 'resolved' | 'all';
+}
+
+const MAX_MESSAGE_LENGTH = 2000;
+
+/**
+ * Registro central das falhas que hoje somem em `.catch(() => null)` e
+ * `logger.error`.
+ *
+ * Não substitui a fila: job que falha já tem `queue_job_event` com timeline. O
+ * alvo aqui são os caminhos fire-and-forget, onde ninguém fica sabendo.
+ */
+@Injectable()
+export class IncidentService {
+  private readonly logger = new Logger(IncidentService.name);
+
+  constructor(
+    @Inject(forwardRef(() => PrismaService))
+    private readonly prisma: PrismaService,
+    @Inject(forwardRef(() => PaginationService))
+    private readonly pagination: PaginationService,
+    @Inject(forwardRef(() => IncidentNotifierService))
+    private readonly notifier: IncidentNotifierService,
+  ) {}
+
+  /**
+   * Nunca lança e nunca bloqueia quem chamou — o remédio não pode virar a
+   * doença. Registrar um incidente jamais pode derrubar o fluxo que já estava
+   * degradado.
+   */
+  record(input: RecordIncidentInput): void {
+    void this.persist(input).catch((error) => {
+      const message = error instanceof Error ? error.message : String(error);
+      this.logger.warn(`Falha ao registrar incidente ${input.source}/${input.code}: ${message}`);
+    });
+  }
+
+  /** Versão aguardável, para quem precisa garantir a gravação (testes, jobs). */
+  async persist(input: RecordIncidentInput): Promise<void> {
+    const source = String(input.source ?? '').trim().slice(0, 120);
+    const code = String(input.code ?? '').trim().slice(0, 120);
+
+    if (!source || !code) return;
+
+    const fingerprint = createHash('sha256')
+      .update(`${source}|${code}|${input.key ?? ''}`)
+      .digest('hex');
+
+    const now = new Date();
+    const message = String(input.message ?? '').slice(0, MAX_MESSAGE_LENGTH);
+
+    // Lido antes do upsert só para saber se é novo ou reabertura — é o que
+    // decide se vale um aviso. Repetição pura não avisa.
+    const existing = await (this.prisma as any).system_incident.findUnique({
+      where: { fingerprint },
+      select: { id: true, resolved_at: true, notified_at: true },
+    });
+
+    const incident = await (this.prisma as any).system_incident.upsert({
+      where: { fingerprint },
+      // Repetição vira contador, não linha nova. `resolved_at: null` reabre um
+      // incidente que alguém já tinha dado como resolvido e voltou a acontecer.
+      update: {
+        occurrences: { increment: 1 },
+        last_seen_at: now,
+        message,
+        context: (input.context ?? undefined) as any,
+        severity: input.severity ?? 'error',
+        resolved_at: null,
+        resolved_by: null,
+        updated_at: now,
+      },
+      create: {
+        source,
+        code,
+        severity: input.severity ?? 'error',
+        message,
+        context: (input.context ?? undefined) as any,
+        fingerprint,
+        occurrences: 1,
+        first_seen_at: now,
+        last_seen_at: now,
+      },
+      select: { id: true, occurrences: true },
+    });
+
+    const reason = !existing ? 'created' : existing.resolved_at ? 'reopened' : null;
+
+    if (!reason) return;
+
+    await this.notifier.notify({
+      id: incident.id,
+      source,
+      code,
+      severity: input.severity ?? 'error',
+      message,
+      occurrences: incident.occurrences,
+      context: input.context ?? null,
+      notifiedAt: existing?.notified_at ?? null,
+      reason,
+    });
+  }
+
+  async list(params: IncidentListParams) {
+    const where: Record<string, unknown> = {};
+
+    if (params.source) where.source = params.source;
+    if (params.severity) where.severity = params.severity;
+
+    // Aberto é o default: a tela existe para mostrar o que precisa de ação.
+    if (params.status !== 'all') {
+      where.resolved_at = params.status === 'resolved' ? { not: null } : null;
+    }
+
+    if (params.search) {
+      where.OR = [
+        { message: { contains: params.search, mode: 'insensitive' } },
+        { code: { contains: params.search, mode: 'insensitive' } },
+        { source: { contains: params.search, mode: 'insensitive' } },
+      ];
+    }
+
+    return this.pagination.paginate(
+      (this.prisma as any).system_incident,
+      { ...params, fields: params.fields ?? '' },
+      { where, orderBy: { last_seen_at: 'desc' } },
+    );
+  }
+
+  /** Contadores da barra de KPI e das abas de filtro. */
+  async summary() {
+    const [open, resolved, bySeverity, bySource] = await Promise.all([
+      (this.prisma as any).system_incident.count({ where: { resolved_at: null } }),
+      (this.prisma as any).system_incident.count({ where: { resolved_at: { not: null } } }),
+      (this.prisma as any).system_incident.groupBy({
+        by: ['severity'],
+        where: { resolved_at: null },
+        _count: { _all: true },
+        _sum: { occurrences: true },
+      }),
+      (this.prisma as any).system_incident.groupBy({
+        by: ['source'],
+        where: { resolved_at: null },
+        _count: { _all: true },
+        orderBy: { _count: { source: 'desc' } },
+        take: 20,
+      }),
+    ]);
+
+    return {
+      open,
+      resolved,
+      bySeverity: bySeverity.map((row: any) => ({
+        severity: row.severity,
+        incidents: row._count._all,
+        occurrences: Number(row._sum?.occurrences ?? 0),
+      })),
+      bySource: bySource.map((row: any) => ({ source: row.source, incidents: row._count._all })),
+    };
+  }
+
+  async resolve(id: number, userId?: number) {
+    return (this.prisma as any).system_incident.update({
+      where: { id },
+      data: { resolved_at: new Date(), resolved_by: userId ?? null, updated_at: new Date() },
+    });
+  }
+
+  async reopen(id: number) {
+    return (this.prisma as any).system_incident.update({
+      where: { id },
+      data: { resolved_at: null, resolved_by: null, updated_at: new Date() },
+    });
+  }
+}