Cursor, Windsurf e Copilot

Nos editores com IA, combine três coisas:

1. Documentação — para a IA escrever código certo (@Docs com o llms-full.txt).
2. Regras do projeto — para ela nunca expor a chave nem duplicar mensagens.
3. MCP (opcional) — para ela consultar dados reais da sua conta enquanto programa.

1. Adicione a documentação

Cursor

1. Abra as configurações do Cursor, na seção de Docs (indexação de documentação).
2. Adicione uma nova documentação com a URL https://platform.toptalking.com.br/llms-full.txt e o nome TopTalking.
3. No chat, digite @TopTalking (ou @Docs → TopTalking) para incluir a documentação no contexto.

Windsurf e Copilot

Inclua o link direto no pedido — o agente consegue ler a página:

Leia https://platform.toptalking.com.br/llms-full.txt antes de começar.

Ou baixe o arquivo para dentro do projeto (ex.: docs/toptalking-llms-full.txt) e referencie-o no chat.

2. Adicione as regras do projeto

O conteúdo é o mesmo nos três editores; muda só o arquivo.

Cursor

.cursor/rules/toptalking.mdc

---
description: Regras para integrar com a API da TopTalking (WhatsApp, contatos, Kanban, mensagens agendadas e webhooks)
alwaysApply: true
---

# TopTalking

- Documentação: https://platform.toptalking.com.br/llms-full.txt (use @TopTalking). OpenAPI: https://platform.toptalking.com.br/openapi.yaml
- Não invente endpoints, campos ou eventos: use só o que está na documentação.
- API REST: https://platform.toptalking.com.br/v1, JSON, cabeçalho `Authorization: Bearer <chave>`.
- A chave vem SEMPRE de `process.env.TOPTALKING_API_KEY` (ou equivalente). Nunca no código-fonte, testes, logs ou commits.
- Nunca chame a API a partir de código de navegador (componentes React/Vue client-side, `"use client"`, HTML).
  A API não tem CORS. Use rotas de API/Server Actions/Edge Functions.
- Envios (`POST /messages`, `POST /scheduled-messages`) sempre com `Idempotency-Key` derivada do ID da operação.
- Erros: `{ "error": { "type", "code", "message", "param", "request_id" } }`. Trate pelo `code`; em 429 respeite `Retry-After`.
- Listas: cursor (`has_more`, `next_cursor` → `?cursor=`), `limit` até 100.
- Telefones: DDI + DDD, só dígitos (ex.: `5511999998888`).
- Webhooks: validar `X-TopTalking-Signature` (`t=<unix>,v1=<hex>`, HMAC-SHA256 hex de `<t>.<corpo cru>` com
  `TOPTALKING_WEBHOOK_SECRET`), tolerância 300 s, comparação em tempo constante, 2xx em até 10 s, deduplicar pelo `id`.
- Testes nunca enviam mensagens reais: use mocks.
- Nada de envio em massa pelo WhatsApp.

Windsurf

Crie um arquivo de regra do workspace em .windsurf/rules/ (ex.: .windsurf/rules/toptalking.md) com o mesmo conteúdo da aba Cursor (sem o bloco --- do topo) e configure a ativação como sempre ativa (Always On) nas regras do Cascade.

GitHub Copilot

.github/copilot-instructions.md

# TopTalking

- Documentação: https://platform.toptalking.com.br/llms-full.txt. OpenAPI: https://platform.toptalking.com.br/openapi.yaml
- Não invente endpoints, campos ou eventos.
- API REST: https://platform.toptalking.com.br/v1, cabeçalho `Authorization: Bearer <chave>`.
- Chave só em `TOPTALKING_API_KEY` (variável de ambiente). Nunca no código nem no navegador (a API não tem CORS).
- `Idempotency-Key` em `POST /messages` e `POST /scheduled-messages`.
- Erros pelo `code`; 429 → `Retry-After`.
- Paginação por cursor (`next_cursor`).
- Webhooks: validar `X-TopTalking-Signature` (HMAC-SHA256 de `<t>.<corpo cru>` com `TOPTALKING_WEBHOOK_SECRET`).
- Testes com mocks; nada de envio em massa.

3. Conecte o MCP (opcional)

Com o MCP, o agente pode, por exemplo, buscar os IDs reais das etapas do seu Kanban enquanto escreve o código.

• Cursor: MCP no Cursor
• VS Code (Copilot) e Windsurf: MCP no VS Code e Windsurf

Use uma chave Somente leitura para o MCP no editor, a menos que você queira que o agente envie mensagens.

4. Peça a integração

@TopTalking Leia a documentação da TopTalking e siga as regras do projeto (.cursor/rules/toptalking.mdc).

Neste projeto Next.js (App Router), crie a integração com a API da TopTalking:

1. lib/toptalking.ts (só servidor: adicione import "server-only"):
   - função request(method, path, { body, query, idempotencyKey }) com base https://platform.toptalking.com.br/v1,
     Authorization: Bearer process.env.TOPTALKING_API_KEY, Content-Type: application/json.
   - erro tipado TopTalkingError { status, code, message, requestId } a partir de { error: { type, code, message, request_id } }.
   - em 429, esperar Retry-After e tentar de novo até 3 vezes.
   - funções: sendMessage({ to?, contactId?, text?, media?, idempotencyKey }), upsertContact({ phone, name?, email?, stageId? }),
     listStages(), moveContact(contactId, stageId | null), listContacts({ search?, stageId?, cursor?, limit? }).
2. app/api/whatsapp/send/route.ts (POST): exige usuário logado, valida { phone, text } com zod e chama sendMessage
   com Idempotency-Key recebida do cliente (crypto.randomUUID() gerado uma vez por envio no front).
3. app/api/webhooks/toptalking/route.ts (POST): lê o corpo cru com await req.text(), valida X-TopTalking-Signature
   (TOPTALKING_WEBHOOK_SECRET, 300 s, comparação em tempo constante), responde 200 e trata message.received e
   contact.stage_changed; ignora duplicados pelo id do evento. Garanta runtime "nodejs".
4. Testes com fetch mockado e o vetor de teste da assinatura da documentação.
5. .env.example com TOPTALKING_API_KEY= e TOPTALKING_WEBHOOK_SECRET=.

Nenhum componente client-side pode importar lib/toptalking.ts.