@hed-hog/core 0.0.385 → 0.0.387

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