@ezmar/yandex-metric-parser-lib 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VRomazanov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,213 @@
+# yandex-metric-parser-lib
+
+Типизированная обёртка над API отчётов Яндекс Метрики для сбора ключевых слов:
+по каким словам сайт находят в поиске и сколько кликов из Яндекс Директа пришло по каждому слову.
+
+Библиотека делает две вещи: аккуратно достаёт данные (квоты, пагинация, ретраи, валидация запроса
+до его отправки) и приводит органику и Директ к единому реестру ключевых слов. Кластеризация,
+поиск корреляций и генерация текстов — задача следующего слоя, поверх этого реестра.
+
+## Установка
+
+```bash
+npm install @ezmar/yandex-metric-parser-lib
+```
+
+Нужен OAuth-токен Яндекса — см. раздел [Получение токена](#получение-токена) ниже.
+
+## Быстрый старт
+
+```ts
+import { YandexMetrika } from '@ezmar/yandex-metric-parser-lib';
+
+const metrika = new YandexMetrika({ token: process.env.YANDEX_METRIKA_TOKEN! });
+
+const registry = await metrika.buildKeywordRegistry({ counterId: 44147844 });
+
+for (const keyword of registry.keywords.slice(0, 20)) {
+  console.log(keyword.displayPhrase, keyword.totalVisits, keyword.direct?.clicks ?? 0);
+}
+```
+
+`buildKeywordRegistry` выгружает органику, посадочные страницы и Директ и склеивает их
+в единый реестр. Логины клиентов Директа подставляются автоматически; если доступа к кампаниям нет,
+Директ выгружается по визитам (без кликов и расходов) с предупреждением.
+
+## Получение токена
+
+Токен выдаётся OAuth-сервером Яндекса. Два пути:
+
+**Быстрый — только ClientId.** Создайте приложение на
+[oauth.yandex.ru](https://oauth.yandex.ru/?dialog=create-client-entry) с доступом
+**`metrika:read`**, затем откройте в браузере:
+
+```
+https://oauth.yandex.ru/authorize?response_type=token&client_id=<ваш ClientId>
+```
+
+Токен придёт во фрагменте адреса: `#access_token=…`. Refresh-токена в этом потоке нет.
+
+**Для автоматизации — ClientId + ClientSecret.** Добавьте в настройках приложения
+Redirect URI `https://oauth.yandex.ru/verification_code` (Платформы → Веб-сервисы),
+затем:
+
+```bash
+YANDEX_CLIENT_ID=… YANDEX_CLIENT_SECRET=… npm run get-token -- --code --save
+```
+
+Скрипт напечатает ссылку, спросит код с экрана (он живёт 10 минут), обменяет его на токен
+и запишет `access_token` с `refresh_token` в `.env.local`. Продление без браузера:
+`npm run get-token -- --refresh --save`.
+
+> **Владельцем токена становится аккаунт, под которым вы авторизовались в браузере**,
+> а не владелец приложения. У этого аккаунта должен быть доступ к счётчику,
+> иначе API ответит `403`.
+
+Проверить токен, не запуская библиотеку:
+
+```bash
+curl -s -o /dev/null -w "%{http_code}\n" \
+  -H "Authorization: OAuth <token>" \
+  https://api-metrika.yandex.net/management/v1/counters
+```
+
+Ожидается `200`.
+
+## Что можно достать
+
+| Метод | Что отдаёт | Требует доступ к Директу |
+|---|---|---|
+| `getOrganicSearchPhrases` | Поисковые фразы органики: визиты, посетители, отказы, глубина, время на сайте | нет |
+| `getPhraseLandingMap` | Связку «фраза → страница входа» | нет |
+| `getDirectSearchPhraseCost` | Реальные запросы Директа, купленные ключевые слова, **клики и расходы** | да |
+| `getDirectKeywordsByVisits` | Ключевые слова и запросы Директа по визитам, с конверсией | нет |
+| `getPhraseTimeline` | Динамику фраз по дням/неделям с оценкой тренда | нет |
+
+Под капотом — группировки `ym:s:<attribution>SearchPhrase`, `ym:s:<attribution>DirectSearchPhrase`,
+`ym:ad:<attribution>DirectSearchPhrase`, `ym:ad:<attribution>DirectPhraseOrCond` и метрики
+`ym:ad:clicks`, `ym:ad:<currency>ConvertedAdCost`.
+
+```ts
+import { aggregateDirectKeywords, settledRange } from '@ezmar/yandex-metric-parser-lib';
+
+// Только органика, за 90 дней, без роботов, топ по визитам
+const organic = await metrika.getOrganicSearchPhrases({
+  counterId: 44147844,
+  ...settledRange(90),
+  searchEngines: ['yandex'],
+});
+
+// Клики и расходы Директа
+const direct = await metrika.getDirectSearchPhraseCost({ counterId: 44147844 });
+
+// Сводка по купленным ключевым словам, а не по запросам
+const byKeyword = aggregateDirectKeywords(direct);
+
+// Что растёт
+const timeline = await metrika.getPhraseTimeline({ counterId: 44147844, topPhrases: 20 });
+const growing = timeline.filter((series) => (series.trend ?? 0) > 1.2);
+```
+
+Идентификатор счётчика можно не искать руками — он находится по адресу сайта:
+
+```ts
+const counter = await metrika.management.findCounterBySite('example.ru');
+const registry = await metrika.buildKeywordRegistry({ counterId: counter.id });
+```
+
+`findCounterBySite` бросает `CounterLookupError`, если совпадений нет или их несколько:
+выгружать наугад выбранный счётчик хуже, чем остановиться.
+
+## Ограничения API, о которых нужно знать
+
+Это не мелочи реализации — они меняют то, как читать выгрузку.
+
+- **Поисковых фраз нет в Logs API.** Из «фразовых» полей там доступно только
+  `ym:s:<attribution>DirectPhraseOrCond`. Сырой выгрузки фраз не существует: только агрегаты
+  из API отчётов.
+- **Порог раскрытия.** Фразы — конфиденциальные данные: если в выборке меньше 10 посетителей,
+  строка не отдаётся. Это режет ровно длинный хвост запросов. Библиотека прокидывает
+  `contains_sensitive_data` в `meta.containsSensitiveData` и помечает пограничные записи
+  флагом `quality.belowPrivacyThreshold`.
+- **Семплирование.** По умолчанию API считает по неполной выборке. Библиотека всегда шлёт
+  `accuracy=full` и предупреждает, если ответ всё равно пришёл семплированным.
+- **Лаг дозаполнения.** 99 % визитов завершаются в течение 3 дней. Период по умолчанию —
+  30 дней, заканчивающихся на `T-3` (`settledRange`).
+- **Квоты.** 30 запросов/с на IP, 3 параллельных, 5000 в сутки, **200 за 5 минут** к `/stat/v1/data`.
+  Встроенный лимитер ждёт локально вместо того, чтобы ловить 429.
+- **Нельзя смешивать** `ym:s:` и `ym:ad:` в `dimensions`/`metrics` одного запроса —
+  библиотека ловит это до отправки.
+- **Атрибуция.** По умолчанию `last`. Модели `first`, `last_significant`
+  и `last_yandex_direct_click` с 25 июня 2026 схлопываются в аналоги — на них выдаётся предупреждение.
+
+## Предупреждения
+
+Ничего не проглатывается молча. Все оговорки приходят в `report.meta.warnings`
+и в колбэк `onWarning`:
+
+```ts
+const metrika = new YandexMetrika({
+  token,
+  onWarning: (warning) => logger.warn({ code: warning.code, ...warning.details }, warning.message),
+});
+```
+
+Коды: `sampling`, `sensitive_data_hidden`, `data_lag`, `deprecated_attribution`,
+`unknown_field`, `truncated`, `direct_access_missing`.
+
+## Проверка актуальности
+
+API Метрики меняется, и молча разошедшаяся с ним библиотека хуже упавшей. Источник истины —
+машиночитаемая документация [`llms-full.txt`](https://yandex.ru/dev/metrika/ru/llms-full.txt).
+
+```bash
+npm run fetch-docs      # скачать свежую документацию в docs/full-docs.txt
+npm run parse-contract  # разобрать её в снапшот + рантайм-реестр
+npm run check-contract  # сравнить снапшот с документацией
+```
+
+`check-contract` падает (exit 1), только если сломалось то, на чём держатся рецепты — список
+в [`src/contract/used.ts`](src/contract/used.ts). Появление новых группировок и метрик печатается
+отчётом, но сборку не роняет: API растёт постоянно.
+
+В CI ([`.github/workflows/contract.yml`](.github/workflows/contract.yml)) проверка идёт на каждом PR
+против закоммиченной документации и раз в неделю — против свежескачанной (`--fetch`).
+
+Дополнительно:
+
+- каждый запрос уходит с `User-Agent: yandex-metric-parser-lib (contract <version>)`,
+  а `report.meta.contractVersion` попадает в результат — по логам видно, на какой версии
+  контракта получены данные;
+- запрос с неизвестной группировкой или метрикой не отправляется вовсе
+  (`RequestValidationError`; опция `allowUnknownFields: true` понижает это до предупреждения);
+- если API вернул поле, которого нет в снапшоте, приходит предупреждение `unknown_field`.
+
+## Структура
+
+```
+src/
+  client/      HTTP, лимитер квот, ошибки, предупреждения
+  reports/     /stat/v1/data и /stat/v1/data/bytime, валидация, пагинация, даты
+  management/  логины клиентов Директа
+  contract/    снапшот контракта, сгенерированный реестр, список используемых полей
+  keywords/    рецепты выгрузки и слой нормализации
+scripts/       fetch-docs, parse-contract, check-contract
+examples/      сквозной сценарий выгрузки реестра в NDJSON
+```
+
+## Разработка
+
+```bash
+npm install
+npm run typecheck
+npm test
+npm run build
+
+# Сквозная выгрузка: счётчик по адресу сайта или по идентификатору
+node --env-file=.env.local --import tsx examples/build-registry.ts --site=example.ru
+YANDEX_METRIKA_TOKEN=… npx tsx examples/build-registry.ts --counter=44147844 --days=30
+```
+
+## Лицензия
+
+MIT