Integre pagamentos pelo Cursor: do prompt ao primeiro Pix pago no sandbox

HEROPAY_API_KEY=seu-token-do-sandbox
HEROPAY_API_URL=https://api.beta.heropay.tech
HEROPAY_WEBHOOK_SECRET=segredo-de-assinatura-do-webhook

grep -qxF '.env*' .gitignore || echo '.env*' >> .gitignore
git check-ignore -v .env   # precisa imprimir a regra; se não imprimir, o arquivo vai para o repositório

mkdir -p docs/heropay
curl -sL https://heropay.tech/llms.txt -o docs/heropay/llms.txt

---
description: Integração de pagamentos com a API HeroPay (links de pagamento, Pix, boleto, cartão, webhooks). Use sempre que o pedido envolver cobrança, checkout, pagamento, assinatura ou webhook.
globs: ["**/*heropay*", "**/payments/**", "**/checkout/**", "**/webhooks/**"]
alwaysApply: false
---

# HeroPay: regras de integração

Referências: esta regra, @docs/heropay/llms.txt e a documentação em https://docs.heropay.tech.
Nunca invente endpoint, campo ou gatilho que não esteja nesta regra ou na documentação. Se algo não estiver lá, pare e pergunte.

## Ambiente
- URL base vem de HEROPAY_API_URL (sandbox: https://api.beta.heropay.tech; produção: https://api.heropay.tech).
- Token vem de HEROPAY_API_KEY. Segredo do webhook vem de HEROPAY_WEBHOOK_SECRET.
- Essas variáveis só são lidas no servidor (route handler, API route, server action, função serverless).
- Nunca use prefixo NEXT_PUBLIC_, VITE_ ou similar nelas. Nunca escreva o valor em código, teste, fixture, log ou commit.

## Toda requisição
- Authorization: Bearer ${HEROPAY_API_KEY}
- Accept: application/vnd.herospark.com; version=1   (sempre fixe version=1)
- Content-Type: application/json

## Cobrança
- Crie cobrança com POST /payment_links e corpo { "payment_link": { ... } }.
- Campos obrigatórios: absorbs_fees (boolean) e price_cents (inteiro).
- price_cents é inteiro em centavos: R$ 197,00 = 19700. Mínimo 500. Nunca float, nunca reais.
- absorbs_fees false repassa os juros do parcelamento ao comprador; true faz o vendedor absorver (venda sem juros).
- max_installments de 1 a 12; cada parcela precisa ter pelo menos R$ 1,99.
- payment_methods aceita "pix", "bank_slip", "credit_card".
- Mande src = id do pedido interno. Ele volta em cart.src em todos os webhooks da compra.
- src aceita só letras, números e . _ - ~ (máx. 255).
- A URL do checkout é data.offer.url. O id do link é data.id.
- O preço vem do banco/servidor. Nunca aceite price_cents vindo do cliente.
- POST /payment_links não é idempotente: grave o id retornado antes de qualquer nova tentativa.

## Webhook
- Cadastro: POST /webhook com { "webhook": { "trigger", "webhook_url", "request_method": "post" } }. Um cadastro por gatilho, com a URL /api/webhooks/heropay/<gatilho>.
- Gatilhos: spark_payment_confirmed, payment_pix_created, spark_payment_boleto_created,
  payment_credit_cart_refused (grafia com "cart"), refunded, chargeback_request,
  subscription_activate, subscription_update, subscription_cancel.
- Valide o header X-HeroPay-Signature: HMAC SHA-256 do CORPO BRUTO com HEROPAY_WEBHOOK_SECRET, comparação em tempo constante. Confira na documentação o formato da assinatura (hex ou base64). Assinatura inválida: 401.
- Leia o corpo cru antes de fazer parse de JSON (no Next.js: await request.text()).
- Seja idempotente: deduplique por id do pagamento + gatilho; a retentativa automática pode entregar o mesmo evento mais de uma vez.
- Responda 2xx rápido; trabalho pesado vai para fila.
- Liberação de acesso acontece SÓ no webhook spark_payment_confirmed. Nunca pelo redirect da página de obrigado.

## Testes contra a API
- Só com a chave de sandbox. Use curl lendo $HEROPAY_API_KEY do ambiente; nunca escreva o valor no comando.
- Pergunte antes de cadastrar webhook ou de chamar qualquer endpoint que não seja de leitura.

## Proibido
- Criar formulário próprio de cartão (o checkout hospedado cuida disso e do PCI).
- Polling na API para saber se pagou. Confie no evento, não no polling.

set -a; source .env; set +a

curl -s -X POST "$HEROPAY_API_URL/payment_links" \
  -H "Authorization: Bearer $HEROPAY_API_KEY" \
  -H "Accept: application/vnd.herospark.com; version=1" \
  -H "Content-Type: application/json" \
  -d '{"payment_link":{"name":"Teste Cursor","description":"Link de teste","price_cents":500,"absorbs_fees":false,"max_installments":1,"payment_methods":["pix","credit_card","bank_slip"],"src":"teste-local"}}'

Integre pagamentos neste projeto usando a API HeroPay.
Referências: a regra @heropay, @docs/heropay/llms.txt e a documentação em https://docs.heropay.tech. Não invente endpoint nem campo fora delas; se faltar algo, pare e me pergunte.

Antes de escrever código, leia o projeto e me diga em 5 linhas: framework, onde ficam as rotas de servidor, qual banco/ORM é usado, como funciona a autenticação e onde ficam as variáveis de ambiente. Siga essa stack; não instale framework novo.

CONTEXTO DO PRODUTO
- O que vendo: [ex.: "Plano Pro anual do meu SaaS de agendamento"]
- Preço: [ex.: R$ 197,00]
- Parcelamento no cartão: até [12]x
- Métodos: Pix, cartão e boleto

1. BANCO
- Tabela/modelo "products": product_key (único), name, description, price_cents (inteiro). Cadastre o produto acima numa seed.
- Tabela/modelo "orders": id (uuid), user_id, product_key, amount_cents (inteiro), status (pending | paid | refunded | canceled, padrão pending), checkout_url, heropay_payment_link_id (inteiro), paid_at (nulo), created_at.
- Tabela "webhook_events": chave única (payment_id + trigger) para deduplicar eventos.
- Gere a migration no padrão do projeto.

2. ROTA "criar checkout" (servidor)
- Exige usuário autenticado. Recebe apenas product_key; nunca aceite preço do cliente.
- Busca o preço em products, cria o pedido pending.
- Chama POST ${HEROPAY_API_URL}/payment_links com os headers da regra e o corpo:
  { "payment_link": { "name", "description", "price_cents", "absorbs_fees": false,
    "max_installments": [12], "payment_methods": ["pix","credit_card","bank_slip"],
    "src": "<id do pedido>" } }
- Salva data.id em heropay_payment_link_id e data.offer.url em checkout_url.
- Devolve ao front só checkout_url e o id do pedido.
- Em erro da API: mensagem amigável ao usuário e o corpo do erro no log do servidor (sem o token).
- Crie um cliente HTTP pequeno em lib/heropay (ou equivalente na stack) que lê HEROPAY_API_URL e HEROPAY_API_KEY e monta os headers. Nada de chave fora dele.

3. FRONT
- Botão "Comprar" na página do produto: chama a rota acima e redireciona para checkout_url.
- Página /pedido/[id]: mostra "Aguardando pagamento" enquanto status = pending e atualiza a cada 5 segundos consultando o NOSSO backend (não a API HeroPay). Quando status = paid, mostra "Pagamento confirmado" e libera o acesso.
- Voltar do checkout não libera nada. Quem libera é o status paid gravado pelo webhook.

4. ROTA "webhook HeroPay" (servidor, pública, só POST) em /api/webhooks/heropay/[trigger]
- Leia o corpo BRUTO antes do parse. Valide X-HeroPay-Signature: HMAC SHA-256 do corpo bruto com HEROPAY_WEBHOOK_SECRET, comparação em tempo constante. Confira na documentação se a assinatura vem em hex ou base64; se não estiver claro, aceite os dois e me avise. Inválido: 401.
- Deduplique em webhook_events; evento repetido responde 200 sem efeito.
- Encontre o pedido por cart.src.
- spark_payment_confirmed: marque paid e grave paid_at, só se o valor pago bater com amount_cents (confira na documentação o campo de valor e se vem em reais ou centavos) e o pedido ainda estiver pending.
- refunded ou chargeback_request: marque refunded e revogue o acesso.
- cart.src desconhecido: registre no log e responda 200. Responda 2xx rápido.

5. TESTES
- Teste automatizado da validação de assinatura (válida, inválida, ausente) e da idempotência (mesmo evento duas vezes, uma liberação só), no framework de teste que o projeto já usa. Nenhum teste chama a API real.

6. ENTREGA
- Rode os testes e o lint do projeto.
- Me mostre a lista de arquivos criados/alterados e confirme que HEROPAY_API_KEY não aparece fora de lib/heropay e do .env.
- Não cadastre webhook sem me perguntar. Não crie nada fora do que foi pedido.

TUNEL="https://SEU-TUNEL"
for trigger in spark_payment_confirmed refunded chargeback_request; do
  curl -s -X POST "$HEROPAY_API_URL/webhook" \
    -H "Authorization: Bearer $HEROPAY_API_KEY" \
    -H "Accept: application/vnd.herospark.com; version=1" \
    -H "Content-Type: application/json" \
    -d "{\"webhook\":{\"trigger\":\"$trigger\",\"webhook_url\":\"$TUNEL/api/webhooks/heropay/$trigger\",\"request_method\":\"post\"}}"
done