@hed-hog/core 0.0.386 → 0.0.390

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

@@ -7,6 +7,7 @@ import {
     BadRequestException,
     HttpException,
     Injectable,
+    Logger,
     NotFoundException,
 } from '@nestjs/common';
 import { EventEmitter } from 'events';
@@ -25,6 +26,11 @@ import {
     UpdateWebhookActionDTO,
 } from './dto/webhook-action.dto';
 import { AppCommandRegistry } from '../app-command/app-command.registry';
+import {
+    WebhookProtocolRegistry,
+    WebhookProtocolRequest,
+    WebhookProtocolResponse,
+} from './webhook-protocol.registry';
 import {
     createPlainToken,
     createPublicUuid,
@@ -58,6 +64,7 @@ type WebhookActionPayload =
 
 @Injectable()
 export class WebhookIntegrationService {
+  private readonly logger = new Logger(WebhookIntegrationService.name);
   private readonly logEmitter = new EventEmitter();
   private readonly webhookActionSelect = {
     id: true,
@@ -105,6 +112,7 @@ export class WebhookIntegrationService {
     private readonly settingService: SettingService,
     private readonly commandRegistry: AppCommandRegistry,
     private readonly mcpApiKeyService: McpApiKeyService,
+    private readonly protocolRegistry: WebhookProtocolRegistry,
   ) {}
 
   private get integrations() {
@@ -551,6 +559,131 @@ export class WebhookIntegrationService {
     });
   }
 
+  /**
+   * Cria (ou devolve) o webhook de um perfil de integração que fala um protocolo
+   * próprio. Idempotente: a chave é (protocol, integration_profile_id), então
+   * chamar de novo devolve o mesmo UUID — e a URL já registrada no painel do
+   * provedor continua válida.
+   *
+   * Existe para que módulos não precisem montar a URL pública por conta própria:
+   * `/webhook/:uuid` e a base vinda dos settings ficam sob responsabilidade do core.
+   */
+  async provisionProtocolWebhook(input: {
+    slug: string;
+    name: string;
+    protocol: string;
+    integrationProfileId: number;
+    description?: string;
+  }) {
+    const existing = await this.integrations.findFirst({
+      where: {
+        protocol: input.protocol,
+        integration_profile_id: input.integrationProfileId,
+      },
+    });
+
+    if (existing) return this.withPublicUrl(existing);
+
+    const created = await this.integrations.create({
+      data: {
+        slug: await this.ensureProvisionSlug(input.slug),
+        name: input.name,
+        description: input.description ?? null,
+        protocol: input.protocol,
+        integration_profile_id: input.integrationProfileId,
+        public_uuid: createPublicUuid(),
+        status: 'active',
+        // Webhooks de protocolo não usam o token estático do core: o adaptador
+        // faz a própria autenticação (HMAC, no caso da Meta).
+        require_token: false,
+      },
+    });
+
+    this.logger.log(
+      `Provisioned "${input.protocol}" webhook ${created.id} for integration profile ${input.integrationProfileId}`,
+    );
+
+    return this.withPublicUrl(created);
+  }
+
+  /** Sufixa o slug até achar um livre (o slug é unique na tabela). */
+  private async ensureProvisionSlug(base: string): Promise<string> {
+    const slug = base.trim();
+    if (!(await this.integrations.findUnique({ where: { slug } }))) return slug;
+
+    for (let i = 2; ; i++) {
+      const candidate = `${slug}-${i}`;
+      if (!(await this.integrations.findUnique({ where: { slug: candidate } }))) {
+        return candidate;
+      }
+    }
+  }
+
+  /**
+   * Entrega a chamada ao adaptador de protocolo do webhook, se houver um.
+   *
+   * Devolve `null` quando o webhook é clássico (protocol nulo) ou quando nenhum
+   * módulo registrou o protocolo — nesse caso o chamador segue pelo fluxo normal
+   * de token + actions.
+   *
+   * Webhooks com protocolo NÃO passam por validateToken/validateIp/validateBodySchema:
+   * o adaptador faz a própria autenticação (a Meta, por exemplo, assina com HMAC).
+   */
+  async executeProtocol(
+    uuid: string,
+    method: 'GET' | 'POST',
+    body: any,
+    query: any,
+    headers: any,
+    req: Request,
+  ): Promise<WebhookProtocolResponse | null> {
+    const integration = await this.integrations.findUnique({
+      where: { public_uuid: uuid },
+      select: {
+        id: true,
+        slug: true,
+        status: true,
+        protocol: true,
+        integration_profile_id: true,
+      },
+    });
+
+    if (!integration?.protocol) return null;
+
+    const adapter = this.protocolRegistry.get(integration.protocol);
+    if (!adapter) {
+      // Protocolo gravado mas nenhum módulo o registrou (library desabilitada,
+      // por exemplo). Não cai no fluxo de actions: seria autenticar com o token
+      // clássico um webhook que deveria exigir a auth do provedor.
+      this.logger.error(
+        `Webhook ${integration.id} declares protocol "${integration.protocol}", but no adapter is registered.`,
+      );
+      throw new NotFoundException('Webhook not found.');
+    }
+
+    if (integration.status !== 'active') {
+      throw new NotFoundException('Webhook not found.');
+    }
+
+    const request: WebhookProtocolRequest = {
+      integration: {
+        id: integration.id,
+        slug: integration.slug,
+        integration_profile_id: integration.integration_profile_id ?? null,
+      },
+      body,
+      query: (query ?? {}) as Record<string, string>,
+      headers: (headers ?? {}) as Record<string, string | string[] | undefined>,
+      rawBody: (req as Request & { rawBody?: Buffer }).rawBody,
+      remoteIp: this.getRemoteIp(req),
+      req,
+    };
+
+    return method === 'GET'
+      ? adapter.verify(request)
+      : adapter.handle(request);
+  }
+
   async executePublic(uuid: string, body: any, headers: any, req: Request) {
     const startedAt = Date.now();
     const remoteIp = this.getRemoteIp(req);

package/src/webhook-integration/webhook-protocol.registry.spec.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it, jest } from '@jest/globals';
+import { WebhookProtocolRegistry } from './webhook-protocol.registry';
+
+const makeAdapter = () =>
+  ({
+    verify: jest.fn(),
+    handle: jest.fn(),
+  }) as any;
+
+describe('WebhookProtocolRegistry', () => {
+  it('devolve o adaptador registrado', () => {
+    const registry = new WebhookProtocolRegistry();
+    const adapter = makeAdapter();
+
+    registry.register('meta-whatsapp', adapter);
+
+    expect(registry.get('meta-whatsapp')).toBe(adapter);
+    expect(registry.has('meta-whatsapp')).toBe(true);
+  });
+
+  it('normaliza a chave (case e espaços)', () => {
+    const registry = new WebhookProtocolRegistry();
+    const adapter = makeAdapter();
+
+    registry.register('  Meta-WhatsApp ', adapter);
+
+    expect(registry.get('meta-whatsapp')).toBe(adapter);
+    expect(registry.get('META-WHATSAPP')).toBe(adapter);
+  });
+
+  it('devolve null para protocolo desconhecido, nulo ou vazio', () => {
+    const registry = new WebhookProtocolRegistry();
+
+    expect(registry.get('nao-existe')).toBeNull();
+    expect(registry.get(null)).toBeNull();
+    expect(registry.get(undefined)).toBeNull();
+    expect(registry.get('')).toBeNull();
+    expect(registry.has(null)).toBe(false);
+  });
+
+  it('recusa registrar com chave vazia', () => {
+    const registry = new WebhookProtocolRegistry();
+
+    expect(() => registry.register('   ', makeAdapter())).toThrow();
+  });
+
+  it('avisa ao sobrescrever um protocolo já registrado', () => {
+    const registry = new WebhookProtocolRegistry();
+    const warn = jest
+      .spyOn((registry as any).logger, 'warn')
+      .mockImplementation(() => undefined);
+    const first = makeAdapter();
+    const second = makeAdapter();
+
+    registry.register('dup', first);
+    registry.register('dup', second);
+
+    // Sobrescrever silenciosamente esconderia dois módulos brigando pelo protocolo.
+    expect(warn).toHaveBeenCalled();
+    expect(registry.get('dup')).toBe(second);
+  });
+
+  it('lista os protocolos registrados em ordem', () => {
+    const registry = new WebhookProtocolRegistry();
+    registry.register('zeta', makeAdapter());
+    registry.register('alpha', makeAdapter());
+
+    expect(registry.list()).toEqual(['alpha', 'zeta']);
+  });
+});

package/src/webhook-integration/webhook-protocol.registry.ts

@@ -0,0 +1,93 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { Request } from 'express';
+
+/**
+ * Resposta que um adaptador devolve ao controller público.
+ *
+ * `contentType` existe porque nem todo provedor aceita JSON: o handshake da Meta,
+ * por exemplo, compara o corpo com o challenge literalmente — um envelope JSON
+ * reprova a verificação.
+ */
+export type WebhookProtocolResponse = {
+  status: number;
+  contentType?: string;
+  body: string | object;
+};
+
+export type WebhookProtocolRequest = {
+  /** O registro de webhook_integration que casou com o uuid da URL. */
+  integration: {
+    id: number;
+    slug: string;
+    integration_profile_id: number | null;
+  };
+  /** Body já parseado (POST) ou query params (GET). */
+  body: unknown;
+  query: Record<string, string>;
+  headers: Record<string, string | string[] | undefined>;
+  /**
+   * Bytes originais da requisição. Obrigatório para validar assinaturas HMAC:
+   * reserializar o JSON reordena chaves e invalida a assinatura.
+   */
+  rawBody?: Buffer;
+  remoteIp: string;
+  req: Request;
+};
+
+/**
+ * Adaptador de um protocolo de webhook de entrada.
+ *
+ * O framework de webhooks do core é um disparador de ações genérico, autenticado
+ * por token estático. Provedores como a Meta falam um protocolo próprio (handshake
+ * de verificação + assinatura HMAC) que não cabe nesse modelo.
+ *
+ * Em vez de espalhar `if (provider === 'meta')` pelo core, um módulo registra aqui
+ * um adaptador e passa a responder pela mesma URL pública (`/webhook/:uuid`). O core
+ * continua sem conhecer nenhum provedor específico.
+ */
+export interface IWebhookProtocolAdapter {
+  /** GET na URL pública (tipicamente o handshake de verificação). */
+  verify(request: WebhookProtocolRequest): Promise<WebhookProtocolResponse>;
+  /** POST na URL pública (o evento em si). */
+  handle(request: WebhookProtocolRequest): Promise<WebhookProtocolResponse>;
+}
+
+/**
+ * Registro dos adaptadores de protocolo, no mesmo padrão do QueueHandlerRegistry
+ * e do FiscalProviderRegistry: o módulo dono do protocolo se registra no boot.
+ */
+@Injectable()
+export class WebhookProtocolRegistry {
+  private readonly logger = new Logger(WebhookProtocolRegistry.name);
+  private readonly adapters = new Map<string, IWebhookProtocolAdapter>();
+
+  register(protocol: string, adapter: IWebhookProtocolAdapter): void {
+    const key = normalizeProtocol(protocol);
+    if (!key) throw new Error('Webhook protocol key is required.');
+
+    if (this.adapters.has(key)) {
+      this.logger.warn(`Webhook protocol "${key}" was overwritten.`);
+    }
+
+    this.adapters.set(key, adapter);
+    this.logger.log(`Registered webhook protocol "${key}"`);
+  }
+
+  get(protocol: string | null | undefined): IWebhookProtocolAdapter | null {
+    const key = normalizeProtocol(protocol);
+    return key ? (this.adapters.get(key) ?? null) : null;
+  }
+
+  has(protocol: string | null | undefined): boolean {
+    return this.get(protocol) !== null;
+  }
+
+  /** Protocolos registrados (para a UI listar o que existe). */
+  list(): string[] {
+    return [...this.adapters.keys()].sort();
+  }
+}
+
+function normalizeProtocol(protocol: string | null | undefined): string {
+  return String(protocol ?? '').trim().toLowerCase();
+}

package/src/whatsapp-sender/whatsapp-sender.module.ts

@@ -0,0 +1,10 @@
+import { PrismaModule } from '@hed-hog/api-prisma';
+import { forwardRef, Module } from '@nestjs/common';
+import { WhatsappSenderService } from './whatsapp-sender.service';
+
+@Module({
+  imports: [forwardRef(() => PrismaModule)],
+  providers: [WhatsappSenderService],
+  exports: [WhatsappSenderService],
+})
+export class WhatsappSenderModule {}

package/src/whatsapp-sender/whatsapp-sender.service.ts

@@ -0,0 +1,313 @@
+import { PrismaService } from '@hed-hog/api-prisma';
+import {
+  BadRequestException,
+  forwardRef,
+  Inject,
+  Injectable,
+  Logger,
+  NotFoundException,
+} from '@nestjs/common';
+import {
+  buildWhatsappOfficialConfigFromIntegration,
+} from '../integration-profile/integration-profile.utils';
+
+export type WhatsappTargetType = 'phone' | 'group';
+
+export type WhatsappMedia = {
+  /** Bare base64 (sem prefixo data:) ou data URL — ambos aceitos. */
+  base64: string;
+  mimetype: string;
+  fileName: string;
+  caption?: string;
+};
+
+export type WhatsappSendInput = {
+  /** Slug do perfil de integração. Vazio => primeiro perfil ativo do tipo whatsapp. */
+  profileSlug?: string;
+  to: string;
+  targetType?: WhatsappTargetType;
+  text: string;
+  media?: WhatsappMedia;
+  /** Exigido pelo provider `whatsapp-official` (id do número no WABA). */
+  phoneNumberId?: string;
+  /** Template aprovado pela Meta — sem ele o envio só chega na janela de 24h. */
+  template?: { name: string; language?: string; params?: string[] };
+};
+
+type ResolvedProfile = {
+  slug: string;
+  providerSlug: string;
+  config: Record<string, unknown>;
+};
+
+/**
+ * Envio de WhatsApp usando um perfil de integração escolhido pelo usuário.
+ *
+ * O provider não é fixado em código: ele vem do próprio perfil, então quem
+ * configura o sistema decide entre Evolution API e a Cloud API oficial da Meta
+ * sem que o chamador precise saber a diferença.
+ */
+@Injectable()
+export class WhatsappSenderService {
+  private readonly logger = new Logger(WhatsappSenderService.name);
+
+  constructor(
+    @Inject(forwardRef(() => PrismaService))
+    private readonly prisma: PrismaService,
+  ) {}
+
+  async send(input: WhatsappSendInput): Promise<void> {
+    const profile = await this.resolveProfile(input.profileSlug);
+
+    switch (profile.providerSlug) {
+      case 'evolution-api':
+        return this.sendWithEvolution(profile, input);
+      case 'whatsapp-official':
+        return this.sendWithOfficial(profile, input);
+      default:
+        throw new BadRequestException(
+          `Perfil de integração "${profile.slug}" usa o provider "${profile.providerSlug}", que não envia WhatsApp. Use um perfil evolution-api ou whatsapp-official.`,
+        );
+    }
+  }
+
+  /** Diz se há perfil utilizável, para o chamador decidir por um fallback sem tentar o envio. */
+  async isConfigured(profileSlug?: string): Promise<boolean> {
+    try {
+      const profile = await this.resolveProfile(profileSlug);
+
+      if (profile.providerSlug === 'evolution-api') {
+        const { baseUrl, token, instance } = this.readEvolutionConfig(profile);
+        return Boolean(baseUrl && token && instance);
+      }
+
+      if (profile.providerSlug === 'whatsapp-official') {
+        const cfg = buildWhatsappOfficialConfigFromIntegration(profile.config);
+        return Boolean(cfg.accessToken);
+      }
+
+      return false;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Normaliza o destino: número vira só dígitos, id de grupo passa intacto
+   * (grupos do WhatsApp têm sufixo `@g.us`, que seria destruído por um strip).
+   */
+  normalizeTarget(target: string, targetType: WhatsappTargetType = 'phone'): string {
+    const raw = String(target ?? '').trim();
+
+    if (!raw) {
+      throw new BadRequestException('Destino de WhatsApp vazio.');
+    }
+
+    if (targetType === 'group') {
+      return raw;
+    }
+
+    const normalized = raw.replace(/\D+/g, '');
+
+    if (!normalized) {
+      throw new BadRequestException(
+        'O número de WhatsApp precisa conter ao menos um dígito.',
+      );
+    }
+
+    return normalized;
+  }
+
+  private async resolveProfile(profileSlug?: string): Promise<ResolvedProfile> {
+    const slug = String(profileSlug ?? '').trim();
+
+    const profile = slug
+      ? await this.prisma.integration_profile.findUnique({
+          where: { slug },
+          include: {
+            integration_provider: { select: { slug: true } },
+            integration_type: { select: { slug: true } },
+          },
+        })
+      : await this.prisma.integration_profile.findFirst({
+          where: { is_active: true, integration_type: { slug: 'whatsapp' } },
+          orderBy: { updated_at: 'desc' },
+          include: {
+            integration_provider: { select: { slug: true } },
+            integration_type: { select: { slug: true } },
+          },
+        });
+
+    if (!profile) {
+      throw new NotFoundException(
+        slug
+          ? `Perfil de integração "${slug}" não encontrado.`
+          : 'Nenhum perfil de integração de WhatsApp ativo encontrado.',
+      );
+    }
+
+    if ((profile as any).integration_type?.slug !== 'whatsapp') {
+      throw new BadRequestException(
+        `Perfil de integração "${profile.slug}" não é do tipo whatsapp.`,
+      );
+    }
+
+    return {
+      slug: profile.slug,
+      providerSlug: String((profile as any).integration_provider?.slug ?? ''),
+      config: ((profile.config ?? {}) as Record<string, unknown>),
+    };
+  }
+
+  private readEvolutionConfig(profile: ResolvedProfile) {
+    const cfg = profile.config;
+
+    return {
+      baseUrl: String(cfg.host ?? cfg.base_url ?? '').trim().replace(/\/+$/, ''),
+      token: String(cfg.token ?? cfg.api_key ?? '').trim(),
+      instance: String(cfg.instance_name ?? cfg.instance ?? '').trim(),
+    };
+  }
+
+  private async sendWithEvolution(
+    profile: ResolvedProfile,
+    input: WhatsappSendInput,
+  ): Promise<void> {
+    const { baseUrl, token, instance } = this.readEvolutionConfig(profile);
+
+    if (!baseUrl || !token || !instance) {
+      throw new BadRequestException(
+        `Perfil de WhatsApp "${profile.slug}" incompleto. Obrigatórios: host, instance_name e token.`,
+      );
+    }
+
+    const target = this.normalizeTarget(input.to, input.targetType);
+    const encodedInstance = encodeURIComponent(instance);
+
+    const url = input.media
+      ? `${baseUrl}/message/sendMedia/${encodedInstance}`
+      : `${baseUrl}/message/sendText/${encodedInstance}`;
+
+    const body = input.media
+      ? {
+          number: target,
+          mediatype: 'image',
+          mimetype: input.media.mimetype,
+          fileName: input.media.fileName,
+          media: stripDataUrlPrefix(input.media.base64),
+          caption: input.media.caption ?? input.text,
+        }
+      : { number: target, text: input.text };
+
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: { apikey: token, 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+
+    if (!response.ok) {
+      const detail = await response.text().catch(() => '');
+
+      if (response.status === 401) {
+        throw new BadRequestException(
+          `Credenciais do WhatsApp inválidas (401). Verifique o token do perfil "${profile.slug}".`,
+        );
+      }
+
+      throw new BadRequestException(
+        `Evolution API recusou o envio (HTTP ${response.status}): ${detail.slice(0, 300)}`,
+      );
+    }
+  }
+
+  private async sendWithOfficial(
+    profile: ResolvedProfile,
+    input: WhatsappSendInput,
+  ): Promise<void> {
+    const cfg = buildWhatsappOfficialConfigFromIntegration(profile.config);
+
+    if (!cfg.accessToken) {
+      throw new BadRequestException(
+        `Perfil de WhatsApp "${profile.slug}" está sem access_token.`,
+      );
+    }
+
+    // O phone_number_id não vive no perfil: um WABA pode ter vários números,
+    // então quem envia precisa dizer por qual deles a mensagem sai.
+    const phoneNumberId = String(
+      input.phoneNumberId ?? profile.config.phone_number_id ?? '',
+    ).trim();
+
+    if (!phoneNumberId) {
+      throw new BadRequestException(
+        'O provider whatsapp-official exige o phone_number_id do número remetente.',
+      );
+    }
+
+    const to = this.normalizeTarget(input.to, 'phone');
+
+    // A Meta só aceita mensagem iniciada pela empresa através de template
+    // aprovado. Sem template, o texto livre só chega se o destinatário tiver
+    // falado com o número nas últimas 24h.
+    const body = input.template?.name
+      ? {
+          messaging_product: 'whatsapp',
+          to,
+          type: 'template',
+          template: {
+            name: input.template.name,
+            language: { code: input.template.language || 'pt_BR' },
+            components: [
+              {
+                type: 'body',
+                parameters: (input.template.params ?? [input.text]).map((text) => ({
+                  type: 'text',
+                  text,
+                })),
+              },
+            ],
+          },
+        }
+      : {
+          messaging_product: 'whatsapp',
+          to,
+          type: 'text',
+          text: { body: input.text.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 };
+      };
+
+      throw new BadRequestException(
+        `WhatsApp recusou o envio (HTTP ${response.status}): ${
+          payload?.error?.message ?? 'sem detalhe'
+        }${
+          input.template?.name
+            ? ''
+            : ' — sem template configurado, a entrega só funciona na janela de 24h'
+        }`,
+      );
+    }
+  }
+}
+
+/** Evolution espera base64 puro; um data URL vindo do chamador quebraria o envio. */
+function stripDataUrlPrefix(image: string): string {
+  const match = /^data:[^;]+;base64,(.*)$/i.exec(image);
+  return match ? match[1] : image;
+}