sightings

sightings — это лёгкая библиотека аналитики просмотров страниц без cookie, написанная на TypeScript. Она отслеживает посещения без записи чего‑либо на устройство пользователя — без cookies, localStorage или отпечатков пальцев — и сохраняет все строки непосредственно в вашей собственной базе данных. Дизайн рассматривает каждое посещение как «sighting»: наблюдение о том, что посещение произошло, а не запись, привязанную к какой‑либо идентичности. Идентификация посетителя использует солёный хеш SHA‑256, полученный из IP, user agent, секретного ключа и текущего дня в UTC, усечённый до 128 бит и вращающийся ежедневно. Библиотека обеспечивает строгие границы данных: параметры запроса, не входящие в allowlist, отклоняются, referrer хранит только имена хостов, а пользовательские полезные нагрузки событий отсутствуют — добавление любого поля в тело beacon возвращает ошибку 400 вместо записи новой метрики. Она различает две половины трафика, которые большинство инструментов смешивают. Человеческие посетители посылают один запрос `sendBeacon` на навигацию, считаемый сервер‑сайд. Краулеры и AI‑агенты (например, gptbot, claudebot, perplexitybot, telegram‑preview) никогда не выполняют клиент‑сайд JavaScript, поэтому они обнаруживаются и учитываются в middleware через классификацию по семейству, а не через raw user‑agent строки. Это делает практичным измерение того, действительно ли модели AI просканировали ваш контент. Основной пакет работает везде, где существует стандартная пара Request/Response и Web Crypto — Node, Deno, Bun, Vercel Edge, Cloudflare Workers. Официальные интеграции включают `@sightings/next` (обработчик и middleware для Next.js App Router) и `@sightings/prisma` (адаптер Prisma со схемой модели). Пользовательские адаптеры хранилища можно реализовать, предоставив единственный метод `record()` и опционально метод `summary()`. Ключевые параметры конфигурации управляют базовым путём API, редакцией на уровне пути (например, удалением поддеревьев `/admin` и `/invite`), allowlist‑ом query‑параметров (по умолчанию `utm_*` и `ref`), обнаружением семейства краулеров, окном хеша посетителя (по умолчанию ежедневно, либо ежечасно), приоритетом заголовков IP и страны, а также обработкой ошибок. Встроенный интерфейс запроса `api.summary()` предоставляет агрегированные представления за диапазоны дат с фильтрацией бот/человек. Прямые методы записи также доступны для контекстов SSR, не‑HTTP фреймворков или backfill‑ов. Репозиторий использует changesets для синхронного версионирования своих трёх пакетов и публикует tarball‑ы с подтверждением происхождения через CI. Category: data | Subcategory: analytics-bi