sightings

sightings é uma biblioteca leve de analytics de pageviews sem cookies, escrita em TypeScript. Ela rastreia visitas sem gravar nada no dispositivo do usuário—sem cookies, localStorage ou fingerprinting—e armazena todas as linhas diretamente no seu próprio banco de dados. O design trata cada visita como um "avistamento": uma observação de que uma visita ocorreu, não um registro vinculado a qualquer identidade. A identificação do visitante usa um hash SHA-256 com sal derivado de IP, user agent, chave secreta e dia UTC, truncado para 128 bits e rotacionado diariamente. A biblioteca impõe limites estritos de dados: parâmetros de query fora da allowlist são rejeitados, referrer armazena apenas hostnames, e não há payloads de eventos personalizados—adicionar qualquer campo ao corpo do beacon retorna erro 400 em vez de registrar uma nova métrica. Ela distingue entre dois tipos de tráfego que a maioria das ferramentas confunde. Visitantes humanos enviam uma única requisição `sendBeacon` por navegação, contabilizada no server-side. Crawlers e agentes de IA (como gptbot, claudebot, perplexitybot, telegram-preview) nunca executam JavaScript client-side, então são detectados e contabilizados no middleware usando classificação por family-name em vez de strings cruas de user-agent. Isso torna viável medir se modelos de IA realmente rastream o seu conteúdo. O pacote core roda em qualquer lugar onde existam pares Request/Response padrão e Web Crypto—Node, Deno, Bun, Vercel Edge, Cloudflare Workers. Integrações oficiais incluem `@sightings/next` (handler do Next.js App Router e middleware) e `@sightings/prisma` (adapter Prisma com schema model). Adaptadores de armazenamento personalizados podem ser implementados fornecendo um único método `record()` e opcionalmente um método `summary()`. As principais opções de configuração controlam o caminho base da API, redação por path (por exemplo, descartar subtrees `/admin` e `/invite`), allowlist de query parameters (default para `utm_*` e `ref`), detecção de families de crawler, janela de hash do visitante (diariamente por padrão, ou hourly), precedência de headers de IP e país, e tratamento de erros. Uma interface de query `api.summary()` integrada fornece visões agregadas sobre intervalos de datas com filtragem bot/human. Métodos de gravação direta também estão expostos para contextos SSR, frameworks não-HTTP ou backfills. O repositório usa changesets para versionamento sincronizado entre seus três pacotes e publica tarballs com provenance vinculada via CI. Categoria: data | Subcategoria: analytics-bi