@mikitasazan/analytics

Общее ядро аналитики для всех проектов: тянет данные из GA4, Google Search Console, Яндекс.Метрики и Яндекс.Вебмастера, складывает дневной снимок и строит дайджест/недельный отчёт. Даёт CLI analytics. Всё, что различается по сайту, живёт в консюмер-репо (analytics.config.ts + .env), а не в пакете.

Статус: публикуется в публичный npm. Потребители: playhub, game-publisher, one-q — список не ведётся вручную, propagate находит их поиском по репозиториям.

Установка

npm install -D @mikitasazan/analytics

Релиз

release patch|minor|major     # из корня пакета

Публикация и раскатка по потребителям — одной командой; канон — скилл package-ops. Своего scripts/release.sh у пакета больше нет.

Пакет ставит бинарь analytics. Ядро поставляется как TypeScript и исполняется через tsx (как это уже делают playhub/one-q) — отдельного шага сборки нет, ровно как у @mikitasazan/config.

Настройка сайта (per-site)

1. analytics.config.ts в корне репо — какие сервисы включены + карта целей Метрики:

   import { defineConfig } from '@mikitasazan/analytics';
   
   export default defineConfig({
     services: ['ga4', 'gsc', 'metrica', 'webmaster'], // game-publisher: ['ga4', 'gsc']
     metricaGoals: { playhub_click: 'Переход в PlayHub', search: 'Поиск по сайту' }
   });

   Образец — examples/analytics.config.ts.

2. .env в корне репо — id и токены сайта. Канон имён — examples/.env.example.

Команды

analytics fetch [YYYY-MM-DD]    # тянет включённые сервисы → data/analytics/raw/<день>.json;
                                # без даты — свежайший финализированный день (сегодня − лаг);
                                # с датой — бэкфилл конкретного дня
analytics digest [YYYY-MM-DD]   # дайджест в терминал + отчёт docs/analytics/<день>.md
analytics weekly [YYYY-MM-DD]   # недельный отчёт → data/analytics/weekly/<ISO-неделя>.md
                                # (каталог переопределяется env ANALYTICS_WEEKLY_DIR)
analytics audit [start] [end]   # прямой опрос всех источников за диапазон — проверка «живо ли»
analytics auth                  # разовое получение GSC refresh token (get-tokens.ts)

Пути резолвятся от корня консюмера (process.cwd()), .env подхватывается автоматически (dotenv). Рекомендуемый крон: ежедневный analytics fetch + цикл «сегодня−4…сегодня−1» для догрузки дней, пропущенных упавшим краном.

Канон env-переменных

| Переменная | Для чего | | --- | --- | | GOOGLE_SERVICE_ACCOUNT_JSON / GOOGLE_APPLICATION_CREDENTIALS | сервис-аккаунт для GA4 (inline JSON или путь). Email аккаунта — Viewer в GA4 Admin | | GOOGLE_OAUTH_CLIENT_ID / _SECRET / _REFRESH_TOKEN | пользовательский OAuth — ТОЛЬКО GSC (analytics-scope Google заблокировал) | | GOOGLE_CLOUD_PROJECT | опц.: проект для квоты GSC (x-goog-user-project). Каноничное имя; GP-шный GOOGLE_QUOTA_PROJECT сведён сюда | | GA4_PROPERTY_ID | GA4 property | | SC_SITE_URL | GSC property (URL-prefix с / или sc-domain:...) | | YANDEX_OAUTH_TOKEN | общий для Метрики и Вебмастера | | YANDEX_METRICA_ID | счётчик Метрики | | YANDEX_WEBMASTER_USER_ID | опц.: иначе тянется из /v4/user | | YANDEX_WEBMASTER_HOST_ID | URL-кодированный хост: https%3A<host>%3A443 | | METRICA_GOAL_PLAY_ID / _SEARCH_ID | опц., только для analytics audit |

Дубли METRIKA_COUNTER_ID / GSC_SITE / WEBMASTER_USER_ID (были в one-q setup.ts) сведены к рантайм-именам выше.

Грабли внешних API

Факты о чужих API, которые не ловятся ни типами, ни тестами. Живут здесь, а не в доках потребителей: код, который на них наступает, — в этом пакете, а потребителей три.

• Метрика ym:s:goalID отдаёт числовой id цели СТРОКОЙ в поле .name; поля .id в ответе нет. Читаешь .id — получаешь undefined, цель не сопоставляется, и цифры по всем целям молча становятся нулями. Держится в src/metrica.ts → mapGoalEvents().
• Вебмастер search-queries/popular игнорирует date_from/date_to и всегда отдаёт своё скользящее окно в 7 дней (границы честно возвращает в полях ответа). Штамповать его сумму датой снимка — значит выдавать недельные числа за дневные. Дневные клики и показы берутся из search-queries/all/history, popular оставлен для списка запросов и средней позиции. Признак, что наступил: два соседних дня дают идентичные числа.
• search-queries/last-week у Вебмастера не существует — 404, не заглушка.
• GSC требует x-goog-user-project, когда токен подписан общим client id gcloud (gcloud auth application-default login). Без него — 403 SERVICE_DISABLED с текстом про Application Default Credentials, хотя токен валиден. Лечится переменной GOOGLE_CLOUD_PROJECT (см. канон env выше), а не перевыпуском OAuth-клиента.

Per-site: запись в БД (persistence)

fetch-all пишет ТОЛЬКО JSON-снимок. Запись в PostgreSQL (была в one-q через @one-q/db) — забота консюмера: прочитай записанный JSON, либо импортируй фетчеры программно:

import { fetchGa4, fetchGsc } from '@mikitasazan/analytics';