sightings

sightings es una librería ligera de análisis de vistas de página sin cookies, escrita en TypeScript. Rastrea visitas sin escribir nada en el dispositivo del usuario —sin cookies, localStorage ni fingerprinting— y almacena todas las filas directamente en tu propia base de datos. El diseño trata cada visita como un «avistamiento»: una observación de que ocurrió una visita, no un registro vinculado a ninguna identidad. La identificación de visitantes utiliza un hash SHA-256 con sal derivedo de IP, user agent, clave secreta y día UTC, truncado a 128 bits y rotado diariamente. La librería aplica límites estrictos de datos: los parámetros de consulta fuera de la lista permitida son rechazados, el referrer solo almacena nombres de host, y no existen payloads de eventos personalizados: añadir cualquier campo al cuerpo del beacon devuelve un error 400 en lugar de registrar una nueva métrica. Distingue entre dos mitades del tráfico que la mayoría de herramientas confunden. Los visitantes humanos envían una sola solicitud `sendBeacon` por navegación, contabilizada del lado del servidor. Los crawlers y agentes de IA (como gptbot, claudebot, perplexitybot, telegram-preview) nunca ejecutan JavaScript del lado del cliente, por lo que se detectan y cuentan en middleware usando clasificación por nombre de familia en lugar de cadenas de user-agent en crudo. Esto hace viable medir si los modelos de IA realmente han rastreado tu contenido. El paquete principal funciona en cualquier entorno que soporte un par Request/Response estándar y Web Crypto: Node, Deno, Bun, Vercel Edge, Cloudflare Workers. Las integraciones oficiales incluyen `@sightings/next` (handler para App Router de Next.js y middleware) y `@sightings/prisma` (adaptador Prisma con modelo de esquema). Los adaptadores de almacenamiento personalizados pueden implementarse proporcionando un único método `record()` y opcionalmente un método `summary()`. Las opciones clave de configuración controlan la ruta base de la API, la redacción a nivel de ruta (por ejemplo, descartar subtítulos `/admin` y `/invite`), lista blanca de parámetros de consulta (por defecto `utm_*` y `ref`), detección de familias de crawlers, ventana de hash de visitante (diario por defecto, o horario), precedencia de encabezados de IP y país, y manejo de errores. Una interfaz de consulta `api.summary()` integrada proporciona vistas agregadas sobre rangos de fecha con filtrado de bots/humanos. También se exponen métodos de grabación directa para contextos SSR, frameworks no HTTP o tareas de backfill. El repositorio utiliza changesets para versionado sincronizado entre sus tres paquetes y publica tarballs vinculados a procedencia a través de CI. Categoría: data | Subcategoría: analytics-bi