Gerador de SKILL.md, AGENTS.md e Servidor MCP

Diagnóstico de Ativação (Skill Trigger Audit)

• Identificador "meta-app-whatsapp-capi" segue o padrão kebab-case oficial.
• Descrição com densidade ideal (384 caracteres) para o índice de contexto do agente.
• Começa com verbos de ação claros sobre o que a skill resolve.
• Contém gatilho explícito de ativação ("Use SEMPRE que o usuário mencionar...").
• Possui guardrails inegociáveis e passo a passo determinístico no corpo.

---
name: meta-app-whatsapp-capi
description: "Implementa e depura integrações com o App da Meta (Meta Developers): WhatsApp Cloud API (webhooks, templates Utility, janelas de 24h), Instagram Graph API (vínculo ig.me?ref= e métricas) e Meta Conversions API (CAPI) com deduplicação event_id. Use SEMPRE que o usuário mencionar Meta Developers, API Oficial do WhatsApp, webhook da Meta, Pixel da Meta, CAPI ou automação de Instagram."
---

# meta-app-whatsapp-capi

## Contexto de Arquitetura e Stack

Cloudflare Workers (Hono) + Cloudflare Queues (retentativa assíncrona CAPI e webhooks) + SurrealDB + Meta Graph API v25.0.

## Exemplos de Solicitações que Ativam esta Skill

- "configurar webhook da API oficial do WhatsApp"
- "enviar evento Purchase para Meta CAPI com deduplicação"
- "validar assinatura X-Hub-Signature-256 da Meta no Cloudflare Workers"
- "criar template Utility do WhatsApp sem cair em Marketing"

## Guardrails Inegociáveis (Regras de Produção)

- **Regra:** Sempre valide o header X-Hub-Signature-256 usando Web Crypto API (crypto.subtle.verify) com o META_APP_SECRET antes de processar qualquer payload de webhook.
- **Regra:** Responda 200 OK ao webhook da Meta em menos de 3 segundos e enfileire o processamento pesado no Cloudflare Queues (ex.: Q_CONVERSIONS ou Q_MESSAGING_REPLIES).
- **Regra:** Use sempre o mesmo event_id no navegador (Meta Pixel fbq) e no servidor (Conversions API) para garantir deduplicação sem perda de atribuição.
- **Regra:** Em templates Utility do WhatsApp, nunca inclua gatilhos promocionais, cupons ou chamadas de venda para evitar reclassificação automática para Marketing pela Meta.

## Fluxo de Execução Passo a Passo

1. Verificar o desafio GET do webhook (hub.mode === "subscribe" e hub.verify_token) retornando hub.challenge em texto puro.
2. Validar o HMAC SHA-256 do corpo bruto (rawBody) no POST do webhook antes do parse JSON.
3. Persistir idempotência do evento por message.id ou event_id antes de disparar efeitos colaterais.
4. Enfileirar envios de CAPI e respostas de WhatsApp com backoff exponencial e Dead Letter Queue (DLQ).

## Padrão de Referência (Golden Pattern)

```typescript
// Validação HMAC SHA-256 de Webhook da Meta no Cloudflare Workers
export async function verifyMetaWebhookSignature(
  rawBody: string,
  signatureHeader: string | undefined,
  appSecret: string
): Promise<boolean> {
  if (!signatureHeader?.startsWith('sha256=')) return false
  const expectedHex = signatureHeader.slice('sha256='.length)
  const encoder = new TextEncoder()
  const key = await crypto.subtle.importKey(
    'raw',
    encoder.encode(appSecret),
    { name: 'HMAC', hash: 'SHA-256' },
    false,
    ['sign']
  )
  const sigBuffer = await crypto.subtle.sign('HMAC', key, encoder.encode(rawBody))
  const computedHex = Array.from(new Uint8Array(sigBuffer))
    .map(b => b.toString(16).padStart(2, '0'))
    .join('')
  return computedHex === expectedHex
}
```