Docs eksp

Prompt pronto: gere um provedor EKSP com IA

Para quem: o time da plataforma que vai se integrar à Encantra (BaaS, SaaS, e-commerce, ERP…).
Como usar: copie tudo entre as linhas ===== abaixo, preencha os campos <<…>> e cole no seu assistente de código (Claude Code, Cursor, Copilot etc.) dentro do repositório do seu produto. Anexe também spec-v1.md, a pasta schemas/ e examples/ deste diretório.

=====================================================================
VOCÊ É um engenheiro sênior. Implemente, NESTE repositório, um PROVEDOR EKSP v1.0
(Encantra Knowledge & Signals Protocol) para que a plataforma de atendimento Encantra
leia o conhecimento do nosso produto e os sinais dos nossos clientes.

## Contexto do nosso produto
- Nome do produto: <<NOME>>
- Stack/framework do backend: <<ex.: Laravel 11 / NestJS / Django / Rails / Supabase Edge Functions>>
- Onde está a documentação/FAQ hoje: <<ex.: tabela help_articles, pasta /docs em Markdown, CMS Strapi, Notion exportado>>
- Onde estão planos e preços: <<ex.: tabela plans, Stripe Products, arquivo pricing.json>>
- Onde estão clientes (contas) e usuários: <<ex.: tabelas organizations e users>>
- Fonte de eventos de uso: <<ex.: tabela audit_events, PostHog, logs>>
- Fonte de status/incidentes: <<ex.: Statuspage API, tabela incidents, nenhuma>>
- Ações que agentes de suporte poderão executar (com confirmação humana): <<ex.: reenviar fatura, estender trial, reenviar convite>>
- URL base pública desejada: <<ex.: https://api.nossoproduto.com/eksp>>

## Contrato (leia os anexos spec-v1.md, schemas/*.json e examples/*.json — eles são a fonte da verdade)
Implemente sob a URL base:
1. GET /.well-known/encantra.json  (público) — manifesto com eksp_version "1.0", provider{name,…},
   capabilities (somente as que implementar), auth {type:"bearer"}, limits {max_page_size:100,…},
   push {events:[…], signature:"hmac-sha256"}.
2. GET /content?updated_since&cursor&limit — envelope {data, next_cursor, has_more}.
   Documentos: id estável, type, title, body_markdown (Markdown completo), url, summary, locale,
   tags, product_area, audience (public|customer|internal), updated_at, deleted.
   Sem updated_since → carga completa. Com updated_since → criados/alterados/EXCLUÍDOS depois
   (exclusões como {id, deleted:true, updated_at} por 30 dias).
3. GET /catalog → {data:{products:[{id,name,description,url,plans:[{id,name,price_cents,currency,interval,features[],limits{}}]}]}}.
4. GET /customers?updated_since&cursor&limit → contas {external_id,name,domain,plan,mrr_cents,status,
   customer_since,renewal_date,updated_at,contacts:[{external_id,name,email,role}]}.
5. GET /customers/{external_id}/context → {data:{customer_external_id, generated_at, summary,
   subscription, fields:[{key,label,value,severity(ok|info|warning|critical),url}], invoices, feature_flags,
   usage_summary, incidents, links}}. Responder em < 1,5 s; 404 se não existir. 3–12 fields úteis ao suporte.
6. GET /usage?since&cursor&limit → eventos {id único, customer_external_id, user_external_id, event (snake_case),
   quantity, properties, occurred_at}, ordenados por occurred_at. Somente eventos de VALOR (não cliques).
7. GET /status → {data:{status, updated_at, components[], incidents[]}} (incidentes das últimas 72 h).
8. GET /actions → {data:[{name,title,description,danger,requires_confirmation:true,input_schema}]}
   POST /actions/{name} com header Idempotency-Key obrigatório e corpo {customer_external_id, input, requested_by}
   → 200 {data:{ok,message,reference}} | 404 | 422 validation_failed. Valide input contra input_schema,
   registre auditoria com requested_by e trate a mesma Idempotency-Key como a mesma operação por 24 h.
9. PUSH (cliente HTTP de saída): ao criar/alterar/excluir conteúdo, alterar cliente, registrar uso relevante
   ou abrir/resolver incidente, envie POST para ENCANTRA_PUSH_URL com corpo {id,type,created_at,data}
   (ou lote {events:[…]}), header X-EKSP-Signature: t=<unix>,v1=<hex(hmac_sha256(ENCANTRA_PUSH_SECRET, t + "." + corpo))>.
   Faça isso de forma assíncrona (fila/job) com retry exponencial até 24 h. Nunca bloqueie a requisição do usuário.

## Regras transversais
- Autenticação: Authorization: Bearer <token> comparado em tempo constante com ENCANTRA_EKSP_TOKEN
  (aceite também ENCANTRA_EKSP_TOKEN_NEXT para rotação). Sem token/errado → 401
  {"error":{"code":"unauthorized","message":"…"}}. O manifesto é público.
- Erros SEMPRE em {"error":{"code","message","details?"}} com os códigos da spec (§14).
- Cursores opacos (ex.: base64 de "updated_at|id"), ordenação determinística, sem repetição entre páginas,
  cursor inválido → 400 invalid_cursor. limit entre 1 e 100 (padrão 50).
- Datas ISO 8601 com fuso; dinheiro em centavos inteiros.
- Rate limit ≥ 120 req/min para o token da Encantra; 429 com Retry-After.
- LGPD: não exponha senhas, tokens, cartões, CPF ou dados sensíveis. Conteúdo interno marcado audience:"internal".
- Configuração por variáveis de ambiente: ENCANTRA_EKSP_TOKEN, ENCANTRA_EKSP_TOKEN_NEXT,
  ENCANTRA_PUSH_URL, ENCANTRA_PUSH_SECRET. Nada de segredos no código.
- Siga o estilo, a arquitetura e as convenções já existentes NESTE repositório.

## Entregáveis
1. Código dos endpoints (rotas, controladores/handlers, mapeadores de dados → objetos EKSP).
2. Publicador de push assíncrono com assinatura HMAC e retry.
3. Testes automatizados que:
   - validam cada resposta contra os JSON Schemas anexos;
   - cobrem 401 sem token, paginação (2 páginas sem repetição), cursor inválido (400),
     updated_since futuro (lista vazia), exclusões (deleted:true), context 404, ação com input inválido (422),
     idempotência de ação e assinatura de push (verificação com o mesmo algoritmo).
4. README curto: como configurar as variáveis, como gerar/rotacionar o token e como registrar o conector
   na Encantra (Integrações › Conectores › Novo conector › Protocolo EKSP).
5. Ao final, liste o que ficou fora do escopo e qualquer decisão de mapeamento que precise de validação humana.

## Checklist de aceite (o Testador de conformidade da Encantra verificará)
[ ] Manifesto válido  [ ] 401 no formato padrão  [ ] Envelope de lista + cursor  [ ] Sem repetição entre páginas
[ ] updated_since correto  [ ] Exclusões  [ ] Objetos válidos pelos schemas  [ ] Contexto < 1,5 s e 404
[ ] Ações com Idempotency-Key e 422  [ ] Push assinado  [ ] HTTPS
=====================================================================

Depois de gerar

  1. Rode os testes gerados e suba em homologação.
  2. Na Encantra: Integrações › Conectores › Novo conector › Protocolo EKSP, informe a URL base e o token.
  3. Abra o conector e rode Conformidade até atingir nota ≥ 80 sem falhas obrigatórias.
  4. Copie a URL de push e o segredo do conector para ENCANTRA_PUSH_URL / ENCANTRA_PUSH_SECRET.
  5. Faça uma alteração num artigo e confira, em segundos, a execução "Push" no histórico do conector.

Dúvidas: master@inspire4u.com.br

Encontrou algo para melhorar? Escreva para master@inspire4u.com.br.