sightings

sightings是一款用TypeScript编写的轻量级无Cookie页面浏览量分析库。它无需向用户设备写入任何内容即可追踪访问——不使用Cookie、localStorage或指纹识别——并将所有数据行直接存储在您自己的数据库中。 设计将每次访问视为一次"目击(sighting)"：仅作为访问发生的观测记录，不与任何身份绑定。访客识别采用基于IP、用户代理、密钥和UTC日期的带盐SHA-256哈希，截断为128位并每日轮换。该库严格执行数据边界：允许列表外的查询参数会被拒绝，引荐来源仅存储主机名，且无自定义事件负载——向信标正文添加任何字段会返回400错误而非记录新指标。 它将多数工具混淆的两类流量分开处理。人类访客每次导航发送单个sendBeacon请求，在服务端计数。爬虫和AI代理（如gptbot、claudebot、perplexitybot、telegram-preview）不执行客户端JavaScript，因此通过家族名称分类（而非原始用户代理字符串）在中间件层检测并计数。这使得实际衡量AI模型是否真正抓取过您的内容成为可能。 核心包可在任何具备标准Request/Response和Web Crypto的环境运行——Node、Deno、Bun、Vercel Edge、Cloudflare Workers。官方集成包括@sightings/next（Next.js App Router处理器和中间件）和@sightings/prisma（带schema模型的Prisma适配器）。可通过提供单个record()方法及可选的summary()方法实现自定义存储适配器。 关键配置项控制基础API路径、路径级脱敏（如删除/admin和/invite子树）、查询参数白名单（默认为utm_*和ref）、爬虫家族检测、访客哈希窗口（默认每日，或每小时）、IP和国家头部优先级及错误处理。 内置的api.summary()查询接口提供按日期范围聚合的视图，并支持机器人/人类过滤。直接记录方法同样暴露，适用于SSR上下文、非HTTP框架或数据回填。仓库使用changesets对三个包进行同步版本管理，并通过CI发布带有来源链接的tarballs。 Category: data | Subcategory: analytics-bi