@ezmar/yandex-metric-parser-lib 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,999 @@
+/**
+ * Ошибки API Метрики.
+ *
+ * Тело ошибки: `{ errors: [{ error_type, message, location }], code, message }`.
+ * Типы ошибок описаны в разделе «Описание ошибок в API».
+ */
+/** Один элемент массива `errors` в ответе API. */
+interface ApiErrorDetail {
+    error_type: string;
+    message?: string;
+    location?: string;
+}
+/** Тело ошибочного ответа API Метрики. */
+interface ApiErrorBody {
+    errors?: ApiErrorDetail[];
+    code?: number;
+    message?: string;
+}
+/** Базовая ошибка API Метрики. */
+declare class MetrikaError extends Error {
+    readonly status: number;
+    readonly errorType: string;
+    readonly details: ApiErrorDetail[];
+    readonly requestUrl: string;
+    constructor(message: string, options: {
+        status: number;
+        errorType: string;
+        details: ApiErrorDetail[];
+        requestUrl: string;
+    });
+}
+/** 429: превышена одна из квот. Запрос имеет смысл повторить позже. */
+declare class QuotaError extends MetrikaError {
+    /** Через сколько миллисекунд разумно повторить попытку. */
+    readonly retryAfterMs: number;
+    constructor(message: string, options: ConstructorParameters<typeof MetrikaError>[1] & {
+        retryAfterMs: number;
+    });
+}
+/** 401/403: нет токена, токен недействителен или нет доступа к счётчику. */
+declare class AuthError extends MetrikaError {
+}
+/** 400: неверный параметр запроса — обычно исчезнувшая или опечатанная группировка. */
+declare class InvalidRequestError extends MetrikaError {
+}
+/** 404: объект не найден. */
+declare class NotFoundError extends MetrikaError {
+}
+/** 5xx и 504: временная проблема на стороне сервиса. */
+declare class ServerError extends MetrikaError {
+}
+/** Ошибка валидации запроса на стороне библиотеки — до обращения к API. */
+declare class RequestValidationError extends Error {
+    constructor(message: string);
+}
+/** Строит типизированную ошибку по HTTP-статусу и телу ответа. */
+declare function toMetrikaError(status: number, body: ApiErrorBody | undefined, requestUrl: string): MetrikaError;
+/** Стоит ли повторять запрос после этой ошибки. */
+declare function isRetryable(error: unknown): boolean;
+
+/**
+ * Локальный лимитер под квоты Яндекс Метрики.
+ *
+ * Квоты из раздела «Квотирование»:
+ *   - 30 запросов в секунду с одного IP;
+ *   - 3 параллельных запроса на пользователя;
+ *   - 5000 запросов в сутки на пользователя (сброс в 00:00 GMT);
+ *   - 200 запросов за 5 минут к `/stat/v1/data`.
+ *
+ * Дешевле подождать локально, чем словить 429 и потерять запрос.
+ */
+/** Группа методов: отчёты считаются отдельной пятиминутной квотой. */
+type QuotaScope = 'report' | 'management';
+interface RateLimitOptions {
+    /** Одновременных запросов. По умолчанию 3 — квота на пользователя. */
+    maxConcurrent?: number;
+    /** Запросов в секунду. По умолчанию 30 — квота на IP. */
+    perSecond?: number;
+    /** Запросов к `/stat/v1/data` за 5 минут. По умолчанию 200. */
+    reportsPer5Min?: number;
+    /** Запросов в сутки. По умолчанию 5000, сброс в 00:00 GMT. */
+    perDay?: number;
+    /** Подменяемый источник времени и сна — для тестов. */
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}
+declare class RateLimiter {
+    private readonly maxConcurrent;
+    private readonly perSecond;
+    private readonly reportsPer5Min;
+    private readonly perDay;
+    private readonly now;
+    private readonly sleep;
+    private inFlight;
+    private readonly secondWindow;
+    private readonly reportWindow;
+    private dayKey;
+    private dayCount;
+    /** Очередь ожидающих: разбуженные проверяют условия заново. */
+    private readonly waiters;
+    constructor(options?: RateLimitOptions);
+    /** Выполняет `fn`, не нарушая квот. Возвращает результат `fn`. */
+    schedule<T>(scope: QuotaScope, fn: () => Promise<T>): Promise<T>;
+    /** Сколько запросов уже израсходовано в текущих окнах — для диагностики. */
+    usage(): {
+        inFlight: number;
+        lastSecond: number;
+        reportsLast5Min: number;
+        today: number;
+    };
+    private rollDay;
+    private acquire;
+    /** 0 — можно выполнять; Infinity — ждать освобождения слота параллелизма. */
+    private waitMs;
+    private release;
+}
+
+/**
+ * Предупреждения, которые библиотека выдаёт вместо тихого проглатывания проблемы.
+ *
+ * Ни одно из них не является ошибкой запроса: данные пришли, но их нужно читать с оговоркой.
+ */
+type WarningCode = 
+/** Ответ построен по неполной выборке — редкие фразы могли не попасть в отчёт. */
+'sampling'
+/** Часть строк скрыта порогом приватности: фразы не отдаются при выборке < 10 посетителей. */
+ | 'sensitive_data_hidden'
+/** Данные за хвост периода ещё дозаполняются. */
+ | 'data_lag'
+/** Запрошена модель атрибуции, которая с 25.06.2026 схлопывается в аналог. */
+ | 'deprecated_attribution'
+/** API вернул группировку или метрику, которой нет в снапшоте контракта. */
+ | 'unknown_field'
+/** Достигнут предел выдачи — часть строк осталась за пределами выгрузки. */
+ | 'truncated'
+/** Нет доступа к кампаниям Директа: клики и расходы недоступны. */
+ | 'direct_access_missing';
+interface Warning {
+    code: WarningCode;
+    message: string;
+    details?: Record<string, unknown>;
+}
+type WarningHandler = (warning: Warning) => void;
+/** Печатает предупреждение в `console.warn` — поведение по умолчанию. */
+declare const consoleWarningHandler: WarningHandler;
+
+/** Базовый адрес API Метрики. */
+declare const DEFAULT_BASE_URL = "https://api-metrika.yandex.net";
+/** Значение параметра запроса: массивы сериализуются через запятую, как требует API. */
+type QueryValue = string | number | boolean | readonly (string | number)[] | undefined;
+interface MetrikaClientOptions {
+    /** OAuth-токен Яндекса. Передаётся в заголовке `Authorization: OAuth <token>`. */
+    token: string;
+    /** Базовый URL. Переопределяется в тестах. */
+    baseUrl?: string;
+    /** Настройки лимитера или готовый лимитер (чтобы делить квоту между клиентами). */
+    rateLimit?: RateLimitOptions | RateLimiter;
+    /** Подменяемый `fetch` — для тестов и прокси. */
+    fetch?: typeof globalThis.fetch;
+    /** Сколько раз повторять запрос при 429 и 5xx. По умолчанию 3. */
+    maxRetries?: number;
+    /** Верхняя граница паузы перед повтором. По умолчанию 30 секунд. */
+    maxRetryDelayMs?: number;
+    /** Таймаут одного запроса. По умолчанию 60 секунд. */
+    timeoutMs?: number;
+    /** Язык расшифровок и значений фильтров. По умолчанию `ru`. */
+    lang?: 'ru' | 'en';
+    /** Куда отдавать предупреждения. По умолчанию `console.warn`. */
+    onWarning?: WarningHandler;
+}
+interface RequestOptions {
+    /** Путь без базового URL, например `/stat/v1/data`. */
+    path: string;
+    query?: Record<string, QueryValue>;
+    /** Группа квот: у отчётов отдельный пятиминутный лимит. */
+    scope: QuotaScope;
+    signal?: AbortSignal;
+}
+declare function buildUrl(baseUrl: string, path: string, query?: Record<string, QueryValue>): string;
+/** Низкоуровневый клиент API Метрики. */
+declare class MetrikaHttpClient {
+    readonly lang: 'ru' | 'en';
+    readonly warn: WarningHandler;
+    readonly limiter: RateLimiter;
+    private readonly token;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly maxRetries;
+    private readonly maxRetryDelayMs;
+    private readonly timeoutMs;
+    constructor(options: MetrikaClientOptions);
+    /** Выполняет GET-запрос и разбирает JSON-ответ. */
+    get<T>(options: RequestOptions): Promise<T>;
+    /**
+     * Пауза перед повтором. `undefined` — ждать пришлось бы дольше `maxRetryDelayMs`,
+     * повтор бессмыслен и ошибку надо отдать вызывающему коду.
+     */
+    private retryDelay;
+    private send;
+}
+
+/**
+ * API управления: счётчики и клиенты Яндекс Директа.
+ *
+ * Отсюда берутся две вещи, без которых не построить отчёт по ключевым словам:
+ * идентификатор счётчика (по адресу сайта) и логины клиентов Директа
+ * для параметра `direct_client_logins`.
+ */
+
+/** Клиент Яндекс Директа, доступный счётчику. */
+interface DirectClient {
+    id: number;
+    name?: string;
+    /** Логин главного представителя — то, что передаётся в `direct_client_logins`. */
+    chief_login: string;
+}
+/** Счётчик Метрики в плоском виде: адрес сайта поднят из вложенного `site2`. */
+interface CounterBrief {
+    id: number;
+    name: string;
+    /** Адрес сайта. В ответе API лежит в `site2.site`. */
+    site: string;
+    /** Дополнительные адреса (зеркала). */
+    mirrors: string[];
+    status?: string;
+    /** Уровень доступа: `own`, `view`, `edit`. */
+    permission?: string;
+    ownerLogin?: string;
+}
+/** Уровень доступа к счётчику. */
+type CounterPermission = 'own' | 'view' | 'edit';
+interface GetCountersOptions {
+    /**
+     * Фильтр по подстроке: идентификатор, название, адрес сайта или зеркало.
+     * Идентификатор указывается целиком.
+     */
+    searchString?: string;
+    /** Ограничить уровнем доступа. */
+    permission?: CounterPermission[];
+    /** Счётчиков за запрос. Максимум 10 000, по умолчанию 1000. */
+    perPage?: number;
+    /** Номер первого счётчика в выдаче, начиная с 1. */
+    offset?: number;
+    signal?: AbortSignal;
+}
+/** Счётчик по адресу сайта не найден или найден не один. */
+declare class CounterLookupError extends Error {
+    readonly candidates: CounterBrief[];
+    constructor(message: string, candidates: CounterBrief[]);
+}
+declare class ManagementApi {
+    private readonly http;
+    constructor(http: MetrikaHttpClient);
+    /** Счётчики, доступные владельцу токена. */
+    getCounters(options?: GetCountersOptions): Promise<CounterBrief[]>;
+    /**
+     * Находит единственный счётчик по адресу сайта.
+     * Бросает `CounterLookupError` со списком кандидатов, если совпадений нет или их несколько:
+     * запускать выгрузку по наугад выбранному счётчику хуже, чем остановиться.
+     */
+    findCounterBySite(site: string, signal?: AbortSignal): Promise<CounterBrief>;
+    /** Клиенты Директа, доступные указанным счётчикам. */
+    getDirectClients(counterIds: number | number[], signal?: AbortSignal): Promise<DirectClient[]>;
+    /** Логины для параметра `direct_client_logins`. */
+    getDirectClientLogins(counterIds: number | number[], signal?: AbortSignal): Promise<string[]>;
+}
+
+/** Версия контракта: первые 12 символов sha256 документации, по которой собран реестр. */
+declare const contractVersion = "5695d8903f6d";
+/** Полный sha256 документации-источника. */
+declare const contractSourceSha256 = "5695d8903f6d252cdd95f058ed3b5984815fe96a215bbd6c23db3e349d4eb784";
+/** Когда снапшот был разобран. */
+declare const contractParsedAt = "2026-09-05T13:29:26.759Z";
+/** Все известные группировки (684). */
+declare const DIMENSION_IDS: ReadonlySet<string>;
+/** Все известные метрики (538). */
+declare const METRIC_IDS: ReadonlySet<string>;
+/** Все известные шаблоны отчётов (93). */
+declare const PRESET_IDS: ReadonlySet<string>;
+
+/**
+ * Реестр известных группировок, метрик и шаблонов — извлечён из документации Метрики.
+ *
+ * Используется для валидации запросов до отправки: неизвестное имя ловится локально,
+ * а не превращается в `400 invalid_parameter` после расхода квоты.
+ */
+
+/** Пространства имён API отчётов: визиты, просмотры, реклама, расходы, события, загрузки, параметры. */
+type Namespace = 's' | 'pv' | 'ad' | 'ev' | 'ep' | 'dl' | 'up';
+/** Возвращает пространство имён идентификатора: `ym:s:visits` → `s`. */
+declare function namespaceOf(id: string): string | undefined;
+/**
+ * Приводит конкретный идентификатор к форме из документации, заменяя подставленные
+ * значения параметров обратно на плейсхолдеры: `ym:s:lastSearchPhrase` → `ym:s:<attribution>SearchPhrase`.
+ */
+declare const ATTRIBUTIONS: readonly ["cross_device_first", "cross_device_last_significant", "last_significant", "last_yandex_direct_click", "automatic", "first", "last"];
+/** Модели атрибуции, поддерживаемые API отчётов. */
+type Attribution = (typeof ATTRIBUTIONS)[number];
+/**
+ * Модели, которые с 25 июня 2026 года схлопываются в ближайшие аналоги.
+ * Библиотека их принимает, но предупреждает.
+ */
+declare const DEPRECATED_ATTRIBUTIONS: Readonly<Record<string, Attribution>>;
+/** Валюты, доступные в параметре `<currency>`. */
+type Currency = 'RUB' | 'USD' | 'EUR' | 'YND';
+/** Известна ли группировка (идентификатор в форме документации, с плейсхолдерами). */
+declare function hasDimension(id: string): boolean;
+/** Известна ли метрика (идентификатор в форме документации, с плейсхолдерами). */
+declare function hasMetric(id: string): boolean;
+/** Известен ли шаблон отчёта. */
+declare function hasPreset(id: string): boolean;
+
+/** Типы API отчётов (`/stat/v1/data`, `/stat/v1/data/bytime`). */
+
+/**
+ * Значение группировки. Для группировок с расшифровкой приходит `{id, name}`,
+ * для остальных — только `name`; география добавляет `iso_name` и иконки.
+ */
+interface DimensionValue {
+    id?: string | null;
+    name?: string | null;
+    icon_id?: string | null;
+    icon_type?: string | null;
+    iso_name?: string | null;
+    [key: string]: unknown;
+}
+/** Строка отчёта: значения группировок и соответствующие им метрики. */
+interface StatRow {
+    dimensions: DimensionValue[];
+    metrics: (number | null)[];
+}
+/** Ответ `/stat/v1/data`. */
+interface StatDataResponse {
+    query: {
+        ids: number[];
+        dimensions: string[];
+        metrics: string[];
+        sort?: string[];
+        date1: string;
+        date2: string;
+        filters?: string;
+        limit: number;
+        offset: number;
+        [key: string]: unknown;
+    };
+    data: StatRow[];
+    total_rows: number;
+    total_rows_rounded?: boolean;
+    sampled: boolean;
+    sample_share?: number;
+    sample_size?: number;
+    sample_space?: number;
+    /** `true` — часть строк скрыта порогом приватности (выборка меньше 10 посетителей). */
+    contains_sensitive_data?: boolean;
+    /** Задержка данных в секундах. */
+    data_lag?: number;
+    totals?: (number | null)[];
+    min?: (number | null)[];
+    max?: (number | null)[];
+}
+/** Строка отчёта по времени: серия значений по точкам временной шкалы. */
+interface BytimeRow {
+    dimensions: DimensionValue[];
+    metrics: (number | null)[][];
+}
+/** Ответ `/stat/v1/data/bytime`. */
+interface BytimeResponse extends Omit<StatDataResponse, 'data'> {
+    data: BytimeRow[];
+    /** Метки времени точек графика. */
+    time_intervals: [string, string][];
+}
+/** Группировка по времени для `/stat/v1/data/bytime`. */
+type TimeGroup = 'all' | 'auto' | 'minute' | 'dekaminute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+/** Управление семплированием. */
+type Accuracy = 'low' | 'medium' | 'high' | 'full' | number;
+/** Параметры запроса к API отчётов. */
+interface StatQuery {
+    /** Идентификаторы счётчиков. */
+    ids: number | number[];
+    metrics: string[];
+    dimensions?: string[];
+    /** Шаблон отчёта. Явные `metrics`/`dimensions` имеют приоритет над шаблоном. */
+    preset?: string;
+    /** Дата начала: `YYYY-MM-DD`, `today`, `yesterday`, `NdaysAgo`. */
+    date1?: string;
+    date2?: string;
+    filters?: string;
+    sort?: string[];
+    /** По умолчанию `full` — иначе редкие фразы выпадают из выборки. */
+    accuracy?: Accuracy;
+    /** Разрешить API поднять `accuracy` до рекомендованного значения. */
+    proposedAccuracy?: boolean;
+    limit?: number;
+    offset?: number;
+    /** Модель атрибуции для группировок с `<attribution>`. */
+    attribution?: Attribution;
+    /** Валюта для метрик с `<currency>`. */
+    currency?: Currency;
+    /** Идентификатор цели для метрик с `<goal_id>`. */
+    goalId?: number;
+    /** Логины клиентов Директа — обязательны для отчётов в пространстве `ym:ad:`. */
+    directClientLogins?: string[];
+    /** Включить строки с неопределённым значением первой группировки. */
+    includeUndefined?: boolean;
+    timezone?: string;
+    lang?: 'ru' | 'en';
+}
+/** Диагностика выгрузки: качество данных и предупреждения. */
+interface ReportMeta {
+    /** Версия контракта, по которой собран запрос. */
+    contractVersion: string;
+    sampled: boolean;
+    sampleShare?: number;
+    sampleSize?: number;
+    sampleSpace?: number;
+    /** Часть строк скрыта порогом приватности. */
+    containsSensitiveData: boolean;
+    dataLagSeconds?: number;
+    totalRows: number;
+    /** Сколько строк реально выгружено. */
+    fetchedRows: number;
+    requests: number;
+    warnings: Warning[];
+}
+/** Результат выгрузки: строки плюс диагностика. */
+interface Report<TRow> {
+    rows: TRow[];
+    meta: ReportMeta;
+}
+
+/**
+ * API отчётов: `/stat/v1/data` (таблица) и `/stat/v1/data/bytime` (по времени).
+ */
+
+interface ReportsApiOptions {
+    /** Не бросать исключение на группировку, которой нет в снапшоте, а предупреждать. */
+    allowUnknownFields?: boolean;
+}
+interface FetchAllOptions {
+    /** Верхняя граница выгрузки. Без неё выгружаются все `total_rows`. */
+    maxRows?: number;
+    /** Строк за запрос. По умолчанию 100 000 — максимум API. */
+    pageSize?: number;
+    signal?: AbortSignal;
+}
+interface BytimeQuery extends StatQuery {
+    /** Разбиение шкалы времени. По умолчанию `day`. */
+    group?: TimeGroup;
+    /** Сколько строк строить, если не заданы `rowIds`. Максимум 30. */
+    topKeys?: number;
+    /** Явный выбор строк по ключам группировок. */
+    rowIds?: string[][];
+}
+/** Преобразует запрос библиотеки в query-параметры API. */
+declare function toQueryParams(query: StatQuery, lang: 'ru' | 'en'): Record<string, QueryValue>;
+/** Собирает предупреждения о качестве данных из ответа API. */
+declare function inspectResponse(response: StatDataResponse): Warning[];
+/** Типизированный доступ к API отчётов. */
+declare class ReportsApi {
+    private readonly http;
+    private readonly options;
+    constructor(http: MetrikaHttpClient, options?: ReportsApiOptions);
+    /** Одна страница отчёта. Сырой ответ API без постобработки. */
+    fetchPage(query: StatQuery, signal?: AbortSignal): Promise<StatDataResponse>;
+    /**
+     * Выгружает отчёт целиком, постранично по `total_rows`.
+     * Период по умолчанию — 30 дней, заканчивающихся на T-3 (данные визитов дозаполняются ~3 дня).
+     */
+    fetchAll(query: StatQuery, options?: FetchAllOptions): Promise<Report<StatRow>>;
+    /** Ленивая постраничная выгрузка — когда весь отчёт не нужно держать в памяти. */
+    stream(query: StatQuery, options?: FetchAllOptions): AsyncGenerator<StatRow>;
+    /** Отчёт с разбивкой по времени — для динамики фраз. */
+    bytime(query: BytimeQuery, signal?: AbortSignal): Promise<BytimeResponse>;
+}
+
+/**
+ * Общее для рецептов выгрузки ключевых слов: идентификаторы группировок и метрик,
+ * сборка фильтров и безопасное чтение ячеек ответа.
+ */
+
+/** Группировки, на которых держатся рецепты. Форма — как в документации, с плейсхолдерами. */
+declare const DIM: {
+    readonly searchPhrase: "ym:s:<attribution>SearchPhrase";
+    readonly searchEngineRoot: "ym:s:<attribution>SearchEngineRoot";
+    readonly trafficSource: "ym:s:<attribution>TrafficSource";
+    readonly isRobot: "ym:s:isRobot";
+    readonly startUrl: "ym:s:startURL";
+    readonly visitDirectSearchPhrase: "ym:s:<attribution>DirectSearchPhrase";
+    readonly visitDirectPhraseOrCond: "ym:s:<attribution>DirectPhraseOrCond";
+    readonly adDirectSearchPhrase: "ym:ad:<attribution>DirectSearchPhrase";
+    readonly adDirectPhraseOrCond: "ym:ad:<attribution>DirectPhraseOrCond";
+    readonly adDirectOrder: "ym:ad:<attribution>DirectOrder";
+    readonly adDirectConditionType: "ym:ad:<attribution>DirectConditionType";
+};
+/** Метрики, на которых держатся рецепты. */
+declare const METRIC: {
+    readonly visits: "ym:s:visits";
+    readonly users: "ym:s:users";
+    readonly bounceRate: "ym:s:bounceRate";
+    readonly pageDepth: "ym:s:pageDepth";
+    readonly avgVisitDuration: "ym:s:avgVisitDurationSeconds";
+    readonly anyGoalConversionRate: "ym:s:anyGoalConversionRate";
+    readonly adClicks: "ym:ad:clicks";
+    readonly adVisits: "ym:ad:visits";
+    readonly adUsers: "ym:ad:users";
+    readonly adBounceRate: "ym:ad:bounceRate";
+    readonly adCost: "ym:ad:<currency>ConvertedAdCost";
+    readonly adCostPerVisit: "ym:ad:<currency>ConvertedAdCostPerVisit";
+};
+/** Общие параметры всех рецептов. */
+interface KeywordQueryOptions {
+    /** Счётчик или счётчики Метрики. */
+    counterId: number | number[];
+    /** Начало периода. По умолчанию 30 дней, заканчивающихся на T-3. */
+    date1?: string;
+    date2?: string;
+    /** Модель атрибуции. По умолчанию `last`. */
+    attribution?: Attribution;
+    /** Дополнительный фильтр сегментации — приклеивается к фильтру рецепта через `AND`. */
+    filters?: string;
+    /** Верхняя граница выгрузки. Без неё выгружается весь отчёт. */
+    maxRows?: number;
+    signal?: AbortSignal;
+}
+/** Склеивает условия фильтра через `AND`, отбрасывая пустые. */
+declare function andFilters(...parts: (string | undefined)[]): string | undefined;
+/**
+ * Нормализует поисковую фразу для склейки источников: обрезает края,
+ * схлопывает пробелы, приводит к нижнему регистру и унифицирует `ё`.
+ * Метрика отдаёт одну и ту же фразу с разным регистром из органики и Директа.
+ */
+declare function normalizePhrase(phrase: string): string;
+
+/**
+ * Рецепт C — Яндекс Директ: реальные запросы, клики и расходы.
+ *
+ * Работает в пространстве `ym:ad:`, поэтому требует `direct_client_logins` —
+ * логины клиентов Директа, к кампаниям которых есть доступ у владельца счётчика.
+ * Эквивалент шаблона `preset=sources_direct_clicks`, дополненный метрикой `ym:ad:clicks`.
+ */
+
+/** Строка отчёта по расходам Директа в разрезе запроса и ключевого слова. */
+interface DirectCostRow {
+    /** Реальный поисковый запрос, по которому показалось объявление. */
+    query: string;
+    /** Условие показа: ключевое слово или условие ретаргетинга. */
+    keyword: string;
+    /** Тип условия показа — позволяет отделить ключевики от ретаргетинга. */
+    conditionType?: string;
+    campaignId?: string;
+    campaignName: string;
+    /** Клики по рекламе. */
+    clicks: number;
+    visits: number;
+    users: number;
+    /** Расходы в валюте отчёта. */
+    cost: number;
+    /** Средняя стоимость визита. */
+    costPerVisit: number;
+    bounceRate: number;
+}
+interface DirectCostOptions extends KeywordQueryOptions {
+    /**
+     * Логины клиентов Директа. Обязательны: без них API отчётов не строит `ym:ad:`.
+     * Получить: `ManagementApi.getDirectClientLogins(counterId)`.
+     */
+    directClientLogins: string[];
+    /** Валюта расходов. По умолчанию — валюта счётчика. */
+    currency?: Currency;
+    /**
+     * Оставить только указанные типы условия показа — так отсекаются условия ретаргетинга.
+     * Документация не перечисляет допустимые значения, поэтому список передаётся явно:
+     * сначала выгрузите отчёт без фильтра и посмотрите, какие `conditionType` встречаются.
+     */
+    conditionTypes?: string[];
+}
+/** Выгружает запросы Директа с кликами и расходами по каждому ключевому слову. */
+declare function getDirectSearchPhraseCost(reports: ReportsApi, options: DirectCostOptions): Promise<Report<DirectCostRow>>;
+
+/**
+ * Рецепт D — ключевые слова Директа по визитам, без доступа к кампаниям.
+ *
+ * Работает в пространстве `ym:s:`, поэтому не требует `direct_client_logins`.
+ * Отдаёт слова и запросы с качеством визита и конверсией, но без кликов и расходов —
+ * их можно получить только рецептом C.
+ * Эквивалент шаблона `preset=sources_direct_summary`.
+ */
+
+/** Строка отчёта по ключевым словам Директа в разрезе визитов. */
+interface DirectVisitRow {
+    /** Условие показа: ключевое слово или условие ретаргетинга. */
+    keyword: string;
+    /** Реальный поисковый запрос, по которому показалось объявление. */
+    query: string;
+    visits: number;
+    users: number;
+    bounceRate: number;
+    /** Конверсия по любой цели, %. */
+    anyGoalConversionRate: number;
+}
+/** Выгружает ключевые слова и запросы Директа без доступа к рекламным кампаниям. */
+declare function getDirectKeywordsByVisits(reports: ReportsApi, options: KeywordQueryOptions & {
+    excludeRobots?: boolean;
+}): Promise<Report<DirectVisitRow>>;
+
+/**
+ * Рецепт A — поисковые фразы органики: по каким словам сайт находят в поиске.
+ *
+ * Эквивалент шаблона `preset=sources_search_phrases`, но с отсечкой роботов
+ * и `accuracy=full`, иначе длинный хвост фраз выпадает из выборки.
+ */
+
+/** Строка отчёта по органическим поисковым фразам. */
+interface OrganicPhraseRow {
+    /** Поисковая фраза как её отдал API. */
+    phrase: string;
+    /** Название поисковой системы (Яндекс, Google, …). */
+    searchEngine: string;
+    /** Идентификатор поисковой системы. */
+    searchEngineId?: string;
+    visits: number;
+    users: number;
+    /** Доля отказов, %. */
+    bounceRate: number;
+    /** Средняя глубина просмотра. */
+    pageDepth: number;
+    /** Среднее время на сайте, секунды. */
+    avgVisitDurationSeconds: number;
+}
+interface OrganicPhrasesOptions extends KeywordQueryOptions {
+    /** Исключить визиты роботов. По умолчанию `true`. */
+    excludeRobots?: boolean;
+    /** Ограничить конкретными поисковыми системами, например `['yandex']`. */
+    searchEngines?: string[];
+}
+/** Фильтр рецепта: только переходы из поисковых систем, по умолчанию без роботов. */
+declare function organicFilters(options: OrganicPhrasesOptions): string | undefined;
+/** Выгружает поисковые фразы органики со статистикой качества визита. */
+declare function getOrganicSearchPhrases(reports: ReportsApi, options: OrganicPhrasesOptions): Promise<Report<OrganicPhraseRow>>;
+
+/**
+ * Рецепт B — фраза × посадочная страница.
+ *
+ * Связывает ключевое слово с конкретным материалом сайта: основа для того,
+ * чтобы понять, какой контент уже отвечает на запрос, а какой ещё нужно написать.
+ */
+
+/** Строка отчёта «фраза → страница входа». */
+interface PhraseLandingRow {
+    phrase: string;
+    /** Адрес страницы входа. */
+    url: string;
+    visits: number;
+    users: number;
+    bounceRate: number;
+    avgVisitDurationSeconds: number;
+}
+/** Выгружает связку «поисковая фраза → посадочная страница» для органики. */
+declare function getPhraseLandingMap(reports: ReportsApi, options: OrganicPhrasesOptions): Promise<Report<PhraseLandingRow>>;
+
+/**
+ * Рецепт E — динамика фраз во времени.
+ *
+ * Отвечает на вопрос «какие слова сейчас растут»: именно растущие фразы стоит брать
+ * в работу, а не те, что просто набрали много визитов за весь период.
+ * Ограничение API: не более 30 строк на график (`top_keys`).
+ */
+
+/** Максимум строк, который API отдаёт для отчёта по времени. */
+declare const MAX_TIMELINE_ROWS = 30;
+/** Точка временного ряда. */
+interface TimelinePoint {
+    /** Начало интервала. */
+    from: string;
+    /** Конец интервала. */
+    to: string;
+    visits: number;
+}
+/** Временной ряд одной фразы. */
+interface PhraseTimeline {
+    phrase: string;
+    points: TimelinePoint[];
+    /** Суммарные визиты за период. */
+    totalVisits: number;
+    /**
+     * Отношение визитов второй половины периода к первой.
+     * Больше 1 — фраза растёт, меньше 1 — затухает; `null`, если первая половина пуста.
+     */
+    trend: number | null;
+}
+interface PhraseTimelineOptions extends OrganicPhrasesOptions {
+    /** Разбиение шкалы. По умолчанию `day`. */
+    group?: TimeGroup;
+    /** Сколько top-фраз строить. По умолчанию 10, максимум 30. */
+    topPhrases?: number;
+    /** Явный список фраз вместо топа. */
+    phrases?: string[];
+}
+/** Выгружает динамику визитов по органическим поисковым фразам. */
+declare function getPhraseTimeline(reports: ReportsApi, options: PhraseTimelineOptions): Promise<PhraseTimeline[]>;
+
+/**
+ * Метки качества данных.
+ *
+ * Метрика скрывает конфиденциальные данные — в том числе поисковые фразы — если
+ * в выборке меньше 10 посетителей. Это ровно тот диапазон, где живёт длинный хвост
+ * запросов, поэтому строку рядом с порогом нельзя молча считать полной.
+ */
+
+/** Порог раскрытия конфиденциальных данных в отчётах Метрики. */
+declare const PRIVACY_THRESHOLD_USERS = 10;
+/** Оговорки, с которыми нужно читать конкретную запись реестра. */
+interface KeywordQuality {
+    /** Отчёт построен по неполной выборке. */
+    sampled: boolean;
+    /** В отчёте могли быть скрыты строки с малой выборкой. */
+    sensitiveDataHidden: boolean;
+    /**
+     * Суммарно посетителей меньше порога раскрытия: рядом с этой записью в отчёте
+     * почти наверняка не хватает соседних, отсечённых порогом.
+     */
+    belowPrivacyThreshold: boolean;
+}
+/** Диагностика склеенного реестра. */
+interface MergedMeta {
+    contractVersion: string;
+    /** Хотя бы один из отчётов был семплирован. */
+    sampled: boolean;
+    /** Минимальная доля выборки среди отчётов — худший случай. */
+    minSampleShare?: number;
+    containsSensitiveData: boolean;
+    /** Сколько записей попало под порог раскрытия. */
+    belowPrivacyThreshold: number;
+    /** Суммарно запросов к API. */
+    requests: number;
+    warnings: Warning[];
+    /** Из каких отчётов собран реестр. */
+    sources: string[];
+}
+/**
+ * Оговорки уровня отчёта. `belowPrivacyThreshold` здесь всегда `false`:
+ * он зависит от суммарного числа посетителей ключевого слова и проставляется
+ * в конце склейки — см. `isBelowPrivacyThreshold`.
+ */
+declare function qualityOf(meta: ReportMeta): KeywordQuality;
+/**
+ * Попадает ли ключевое слово под порог раскрытия.
+ *
+ * Считать это построчно нельзя: одна фраза приходит несколькими строками —
+ * разный регистр написания, разные поисковые системы. Редкий вариант с четырьмя
+ * посетителями пометил бы всё слово, у которого суммарно их пятьсот.
+ * Поэтому флаг считается один раз по итоговой сумме.
+ */
+declare function isBelowPrivacyThreshold(users: number): boolean;
+/** Объединяет метки уровня отчёта: запись видна в нескольких выгрузках. */
+declare function mergeQuality(a: KeywordQuality, b: KeywordQuality): KeywordQuality;
+/** Сводит метаданные нескольких отчётов в одну диагностику. */
+declare function mergeMeta(entries: {
+    source: string;
+    meta: ReportMeta;
+}[], belowPrivacyThreshold: number): MergedMeta;
+
+/**
+ * Слой нормализации: сводит выгрузки органики и Директа в единый реестр ключевых слов.
+ *
+ * Ключ склейки — нормализованная фраза реального пользовательского запроса
+ * (`SearchPhrase` из органики, `DirectSearchPhrase` из Директа). Купленные ключевые
+ * слова Директа (`DirectPhraseOrCond`) — другой уровень агрегации, поэтому они не
+ * смешиваются с запросами, а складываются в `direct.keywords` и в отдельную сводку
+ * `aggregateDirectKeywords`.
+ */
+
+/** Откуда в реестре взялась фраза. */
+type KeywordSource = 'organic' | 'direct_query';
+/** Показатели фразы в органическом поиске. */
+interface OrganicStats {
+    visits: number;
+    users: number;
+    bounceRate: number;
+    pageDepth: number;
+    avgVisitDurationSeconds: number;
+    /** Поисковые системы, из которых приходили по этой фразе. */
+    searchEngines: string[];
+}
+/** Показатели фразы в Яндекс Директе. */
+interface DirectStats {
+    clicks: number;
+    visits: number;
+    users: number;
+    cost: number;
+    costPerVisit: number;
+    bounceRate: number;
+    /** Купленные ключевые слова (условия показа), по которым показывалось объявление. */
+    keywords: string[];
+    campaigns: string[];
+    /** Конверсия по любой цели, если данные пришли из рецепта по визитам. */
+    anyGoalConversionRate?: number;
+}
+/** Посадочная страница, на которую приходили по фразе. */
+interface KeywordLanding {
+    url: string;
+    visits: number;
+}
+/** Запись реестра ключевых слов. */
+interface Keyword {
+    /** Нормализованная фраза — ключ склейки. */
+    phrase: string;
+    /** Написание, как его отдал API (первое встреченное). */
+    displayPhrase: string;
+    sources: KeywordSource[];
+    organic?: OrganicStats;
+    direct?: DirectStats;
+    landings: KeywordLanding[];
+    /** Визиты из всех источников — основная величина для сортировки. */
+    totalVisits: number;
+    /** Посетители из всех источников. По ним считается порог раскрытия. */
+    totalUsers: number;
+    quality: KeywordQuality;
+}
+/** Реестр ключевых слов и диагностика его сборки. */
+interface KeywordRegistry {
+    keywords: Keyword[];
+    meta: MergedMeta;
+}
+/** Выгрузки, из которых собирается реестр. Все части необязательны. */
+interface MergeInput {
+    organic?: Report<OrganicPhraseRow>;
+    landings?: Report<PhraseLandingRow>;
+    directCost?: Report<DirectCostRow>;
+    directVisits?: Report<DirectVisitRow>;
+}
+/** Сводка по купленному ключевому слову Директа. */
+interface DirectKeywordSummary {
+    keyword: string;
+    clicks: number;
+    visits: number;
+    users: number;
+    cost: number;
+    /** Реальные запросы, приведшие к показу по этому слову. */
+    queries: string[];
+    campaigns: string[];
+}
+/** Склеивает выгрузки в единый реестр, отсортированный по суммарным визитам. */
+declare function mergeKeywords(input: MergeInput): KeywordRegistry;
+/** Сводит расходы Директа по купленным ключевым словам, а не по запросам. */
+declare function aggregateDirectKeywords(report: Report<DirectCostRow>): DirectKeywordSummary[];
+
+/**
+ * Фасад библиотеки: клиент, отчёты и рецепты выгрузки ключевых слов в одном объекте.
+ */
+
+type MetrikaOptions = MetrikaClientOptions & ReportsApiOptions;
+/** Что именно собирать в реестр ключевых слов. */
+interface KeywordRegistryOptions extends OrganicPhrasesOptions {
+    /** Добавить связку «фраза → посадочная страница». По умолчанию `true`. */
+    withLandings?: boolean;
+    /**
+     * Добавить клики и расходы Директа. По умолчанию `true`.
+     * Логины клиентов подставляются автоматически; если доступа к Директу нет,
+     * блок пропускается с предупреждением.
+     */
+    withDirect?: boolean;
+    /** Готовые логины клиентов Директа — чтобы не тратить запрос на их получение. */
+    directClientLogins?: string[];
+}
+/** Точка входа: `new YandexMetrika({ token })`. */
+declare class YandexMetrika {
+    readonly http: MetrikaHttpClient;
+    readonly reports: ReportsApi;
+    readonly management: ManagementApi;
+    constructor(options: MetrikaOptions);
+    /** Версия контракта, по которой собрана библиотека. */
+    contract(): {
+        version: string;
+        sourceSha256: string;
+        parsedAt: string;
+    };
+    /** Рецепт A: поисковые фразы органики. */
+    getOrganicSearchPhrases(options: OrganicPhrasesOptions): Promise<Report<OrganicPhraseRow>>;
+    /** Рецепт B: фраза × посадочная страница. */
+    getPhraseLandingMap(options: OrganicPhrasesOptions): Promise<Report<PhraseLandingRow>>;
+    /**
+     * Рецепт C: запросы Директа с кликами и расходами.
+     * Если `directClientLogins` не передан, логины запрашиваются автоматически.
+     */
+    getDirectSearchPhraseCost(options: Omit<DirectCostOptions, 'directClientLogins'> & {
+        directClientLogins?: string[];
+    }): Promise<Report<DirectCostRow>>;
+    /** Рецепт D: ключевые слова Директа по визитам, без доступа к кампаниям. */
+    getDirectKeywordsByVisits(options: KeywordQueryOptions & {
+        excludeRobots?: boolean;
+    }): Promise<Report<DirectVisitRow>>;
+    /** Рецепт E: динамика фраз во времени. */
+    getPhraseTimeline(options: PhraseTimelineOptions): Promise<PhraseTimeline[]>;
+    /**
+     * Сквозной сценарий: выгружает органику, посадочные страницы и Директ,
+     * склеивает в единый реестр ключевых слов.
+     */
+    buildKeywordRegistry(options: KeywordRegistryOptions): Promise<KeywordRegistry>;
+}
+
+/** Документированные лимиты запроса к API отчётов. */
+declare const LIMITS: {
+    readonly maxDimensions: 10;
+    readonly maxMetrics: 20;
+    readonly maxRowsPerRequest: 100000;
+    readonly maxFilterLength: 10000;
+    readonly maxFilterValues: 100;
+};
+/**
+ * Приводит идентификатор к форме документации, подставляя обратно плейсхолдеры:
+ * `ym:s:lastSearchPhrase` → `ym:s:<attribution>SearchPhrase`,
+ * `ym:ad:RUBConvertedAdCost` → `ym:ad:<currency>ConvertedAdCost`,
+ * `ym:s:goal123visits` → `ym:s:goal<goal_id>visits`.
+ */
+declare function toContractForm(id: string): string;
+interface ValidationResult {
+    warnings: Warning[];
+}
+/** Проверяет запрос и возвращает предупреждения; на грубых ошибках бросает исключение. */
+declare function validateQuery(query: StatQuery, options?: {
+    allowUnknownFields?: boolean;
+}): ValidationResult;
+
+/**
+ * Даты отчётного периода.
+ *
+ * Визиты дозаполняются по мере поступления данных: в среднем 99 % визитов завершаются
+ * в течение 3 дней после начала. Поэтому окно по умолчанию заканчивается на T-3,
+ * иначе последние дни выглядят «просевшими» и портят сравнение периодов.
+ */
+/** Сколько последних дней считаются недозаполненными. */
+declare const SETTLED_LAG_DAYS = 3;
+/** Отчётный период: значения в формате API (`YYYY-MM-DD` или `NdaysAgo`). */
+interface DateRange {
+    date1: string;
+    date2: string;
+}
+/**
+ * Окно из `days` дней, заканчивающееся за `lagDays` дней до сегодня.
+ * `settledRange(30)` → `{ date1: '32daysAgo', date2: '3daysAgo' }`.
+ */
+declare function settledRange(days?: number, lagDays?: number): DateRange;
+
+/**
+ * Идентификаторы, на которых держатся рецепты библиотеки.
+ *
+ * `check-contract` падает, если что-то отсюда исчезло или изменилось в документации:
+ * это ровно тот набор, поломка которого ломает библиотеку, а не просто расширяет API.
+ * Записи в `<attribution>`/`<currency>`-форме — как в документации, до подстановки параметров.
+ */
+/** Группировки, используемые рецептами. Ключ — идентификатор, значение — где он нужен. */
+declare const USED_DIMENSIONS: Readonly<Record<string, string>>;
+/** Метрики, используемые рецептами. */
+declare const USED_METRICS: Readonly<Record<string, string>>;
+/** Шаблоны, на которые библиотека ссылается в документации и тестах. */
+declare const USED_PRESETS: Readonly<Record<string, string>>;
+
+/** Типы машиночитаемого контракта API Метрики, извлекаемого из `llms-full.txt`. */
+interface DimensionEntry {
+    /** Полный идентификатор, например `ym:s:<attribution>SearchPhrase`. */
+    id: string;
+    /** Человекочитаемое название из документации. */
+    title?: string;
+    /** Операторы фильтрации, разрешённые для этой группировки. */
+    operators?: string[];
+    /** Группировка-расшифровка, отдающая `{id, name}` вместо голого идентификатора. */
+    decoder?: string;
+    /** Минимальная дата, за которую можно построить отчёт (YYYY-MM-DD). */
+    since?: string;
+}
+interface MetricEntry {
+    id: string;
+    title?: string;
+    /** `int`, `double`, `percents`, `currency`, `second`, `affinity` … */
+    type?: string;
+    /** Можно ли использовать метрику в `filters`. */
+    filterable?: boolean;
+    since?: string;
+}
+interface PresetEntry {
+    id: string;
+    title?: string;
+    dimensions: string[];
+    metrics: string[];
+}
+interface Contract {
+    /** ISO-время разбора. */
+    parsedAt: string;
+    /** sha256 исходного документа. */
+    sourceSha256: string;
+    /** Число строк в исходном документе — грубая проверка, что скачали документ целиком. */
+    sourceLines: number;
+    dimensions: Record<string, DimensionEntry>;
+    metrics: Record<string, MetricEntry>;
+    presets: Record<string, PresetEntry>;
+}
+
+export { type Accuracy, type ApiErrorBody, type ApiErrorDetail, type Attribution, AuthError, type BytimeQuery, type BytimeResponse, type BytimeRow, type Contract, type CounterBrief, CounterLookupError, type CounterPermission, type Currency, DEFAULT_BASE_URL, DEPRECATED_ATTRIBUTIONS, DIM, DIMENSION_IDS, type DateRange, type DimensionEntry, type DimensionValue, type DirectClient, type DirectCostOptions, type DirectCostRow, type DirectKeywordSummary, type DirectStats, type DirectVisitRow, type FetchAllOptions, type GetCountersOptions, InvalidRequestError, type Keyword, type KeywordLanding, type KeywordQuality, type KeywordQueryOptions, type KeywordRegistry, type KeywordRegistryOptions, type KeywordSource, LIMITS, MAX_TIMELINE_ROWS, METRIC, METRIC_IDS, ManagementApi, type MergeInput, type MergedMeta, type MetricEntry, type MetrikaClientOptions, MetrikaError, MetrikaHttpClient, type MetrikaOptions, type Namespace, NotFoundError, type OrganicPhraseRow, type OrganicPhrasesOptions, type OrganicStats, PRESET_IDS, PRIVACY_THRESHOLD_USERS, type PhraseLandingRow, type PhraseTimeline, type PhraseTimelineOptions, type PresetEntry, type QueryValue, QuotaError, type QuotaScope, type RateLimitOptions, RateLimiter, type Report, type ReportMeta, ReportsApi, type ReportsApiOptions, type RequestOptions, RequestValidationError, SETTLED_LAG_DAYS, ServerError, type StatDataResponse, type StatQuery, type StatRow, type TimeGroup, type TimelinePoint, USED_DIMENSIONS, USED_METRICS, USED_PRESETS, type Warning, type WarningCode, type WarningHandler, YandexMetrika, aggregateDirectKeywords, andFilters, buildUrl, consoleWarningHandler, contractParsedAt, contractSourceSha256, contractVersion, getDirectKeywordsByVisits, getDirectSearchPhraseCost, getOrganicSearchPhrases, getPhraseLandingMap, getPhraseTimeline, hasDimension, hasMetric, hasPreset, inspectResponse, isBelowPrivacyThreshold, isRetryable, mergeKeywords, mergeMeta, mergeQuality, namespaceOf, normalizePhrase, organicFilters, qualityOf, settledRange, toContractForm, toMetrikaError, toQueryParams, validateQuery };