Source maps: a pilha do erro no seu código-fonte

01O que é monitorado

Nada novo: o source map só traduz a pilha dos erros que já chegam. Ele não é enviado para a IA, e o código em volta da linha nunca vai ao modelo.

02Como funciona

• No deploy, você manda **um pedido por arquivo .map, dizendo a versão e o nome do arquivo gerado** (o nome que aparece na pilha, só o nome, sem pasta: index-DNNrolCp.js, servidor.js).
• O evobits guarda o mapa por empresa, serviço e versão, e resolve a pilha na hora em que a página do erro abre. Por isso o mapa enviado depois do erro também vale para os erros daquela versão que já estavam lá.
• A versão tem de ser a mesma que o serviço manda em service.version (no @evobits/node, a do package.json ou EVOBITS_VERSAO).
• Sem mapa, a pilha aparece crua, como chegou, e o agrupamento do erro continua igual (o grupo não depende do mapa).

O token público do navegador (evn_...) nunca manda source map. A chave da API vale para qualquer serviço da empresa (ou só os do grupo dela, se a chave tiver recorte), por isso ela pede o servico.

03Onde aparece

Página do erro (Aplicações > Erros > um erro): quadros com função, arquivo e linha do fonte, o trecho do código em volta da linha (quando o mapa traz sourcesContent) e o quadro gerado ao lado. Na lista de erros, o "onde" do grupo passa a mostrar o arquivo do fonte.

04Alertas

Não muda nenhum alerta.

05Limites e privacidade

• Até 32 MB por arquivo, 256 MB por versão, as 10 versões mais recentes por serviço (a mais antiga sai quando chega a 11ª) e 2 GB por empresa. Acima disso, 413.
• Até 120 envios por minuto.
• Source map v3 em JSON, com mappings e sources. Mapa indexado (sections) não é aceito.
• Nome do arquivo: letras, números, ponto, hífen e sublinhado; o .map no fim é tirado sozinho.
• O mapa pode conter o seu código-fonte (sourcesContent). Ele fica guardado na nossa infraestrutura, separado por empresa, não entra nas cópias de segurança (reenvie a cada deploy) e é apagado com o serviço ou com a conta.
• Você não precisa publicar os .map junto com o site: gere os mapas sem a referência no arquivo (no Vite, build.sourcemap: 'hidden'), mande ao evobits e tire do pacote publicado.

06Como enviar

Node.js compilado (no passo de deploy, com o mesmo EVOBITS_TOKEN do serviço):

VERSAO=$(node -p "require('./package.json').version")
for mapa in dist/*.js.map; do
  curl -fsS -X POST "https://app.evobits.com.br/api/aplicacoes/source-maps?versao=$VERSAO&arquivo=$(basename "$mapa" .map)" \
    -H "authorization: Bearer $EVOBITS_TOKEN" -H "content-type: application/json" \
    --data-binary @"$mapa"
done

Se o serviço roda com node --enable-source-maps, a pilha já sai resolvida e este envio é dispensável.

Página (Vite e afins), no CI, com a chave da API em EVOBITS_CHAVE e a mesma versão do build (VITE_VERSAO):

for mapa in dist/assets/*.js.map; do
  curl -fsS -X POST "https://app.evobits.com.br/api/aplicacoes/source-maps?servico=<id-do-servico>&versao=$VITE_VERSAO&arquivo=$(basename "$mapa" .map)" \
    -H "authorization: Bearer $EVOBITS_CHAVE" -H "content-type: application/json" \
    --data-binary @"$mapa"
done

O nome do arquivo gerado tem o hash do build (index-DNNrolCp.js); o laço acima tira o nome de cada .map.

Respostas: 201 com { versao, arquivo, bytes }; 400 corpo que não é source map, nome inválido, ou chave da API sem servico; 401 token ausente, revogado ou do navegador; 403 chave da API sem o escopo sourcemaps.enviar; 404 serviço de outra empresa ou fora do recorte da chave; 413 acima dos limites.

07Como conferir

1. 1O curl responde 201 para cada arquivo.
2. 2Abra um erro da mesma versão em Aplicações > Erros: os quadros mostram src/... com a linha do fonte e o código em volta. Erros antigos da mesma versão passam a aparecer resolvidos também.

08Problemas comuns

09Texto para IA

Para pedir a um assistente de código (Claude Code ou afins) que acrescente o envio ao deploy do projeto. Troque os marcadores entre < >; o token fica só na variável EVOBITS_TOKEN.

# Tarefa: enviar os source maps do serviço <nome do serviço> ao evobits em cada deploy

## Objetivo
Acrescentar ao deploy deste projeto o envio dos source maps, para a página do erro do evobits mostrar o arquivo e a
linha do código-fonte.

## Contexto
- Rota: POST https://app.evobits.com.br/api/aplicacoes/source-maps?versao=<versão>&arquivo=<nome do arquivo gerado>
  com o source map v3 no corpo (`content-type: application/json`, `--data-binary @arquivo.map`). Um pedido por mapa.
- `arquivo` é só o nome do arquivo gerado como aparece na pilha (por exemplo `index-DNNrolCp.js` ou `servidor.js`),
  sem pasta e sem `.map`.
- `versao` é a mesma que o serviço manda em `service.version` no momento do erro.
- Backend (Node compilado): credencial = token do serviço, na variável EVOBITS_TOKEN.
- Página (serviço navegador): credencial = chave da API com o escopo `sourcemaps.enviar`, na variável EVOBITS_CHAVE,
  e o parâmetro `servico=<id do serviço>`. O token público do navegador (`evn_`) é recusado.
- Limites: 32 MB por arquivo, 256 MB por versão, 10 versões por serviço. Respostas: 201 ok; 400 inválido; 401
  credencial; 403 sem escopo; 404 serviço; 413 tamanho.

## Passos
1. Descubra como o projeto compila (tsc, Vite, webpack, esbuild, Next.js) e onde fica o passo de deploy (CI, script).
2. Ligue a geração de source maps no build, se ainda não estiver ligada (no Vite, `build.sourcemap: 'hidden'` gera os
   mapas sem expor a referência na página).
3. No passo de deploy, depois do build, acrescente um laço que manda cada `*.js.map` com `curl -fsS`, usando
   `arquivo=$(basename "$mapa" .map)` e a versão do deploy (a mesma de `service.version`).
4. Use a credencial por variável de ambiente do CI (EVOBITS_TOKEN para backend, EVOBITS_CHAVE para página).
5. Se os `.map` não devem ser publicados, remova-os do pacote publicado DEPOIS do envio.

## Regras
- Nunca escreva token ou chave em arquivo versionado, no log do CI ou na resposta; use os segredos do CI.
- Falha no envio do mapa não deve derrubar o deploy: registre e siga.
- Não mude nada além do pedido.

## Como saber que deu certo
1. No log do deploy, cada mapa respondeu HTTP 201 com `{"versao": ..., "arquivo": ..., "bytes": ...}`.
2. No painel do evobits, um erro dessa versão mostra `src/...` com a linha do código-fonte.