jsonseo 1.0.0

package/dist/cjs/client.js

@@ -0,0 +1,135 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JsonSeoClient = void 0;
+const errors_js_1 = require("./errors.js");
+const http_js_1 = require("./http.js");
+/**
+ * Клиент JSON SEO API.
+ *
+ * ```ts
+ * const client = new JsonSeoClient('ВАШ_КЛЮЧ');
+ * const serp = await client.yandex({ text: 'купить ноутбук', region: 213 });
+ * ```
+ */
+class JsonSeoClient {
+    constructor(first, second = {}) {
+        this.http = new http_js_1.HttpClient(typeof first === 'string' ? { ...second, apiKey: first } : first);
+    }
+    // Яндекс
+    /** Органическая выдача Яндекса: мобильная, регион 213. 0.01 ₽ за страницу. */
+    async yandex(params, options) {
+        return this.http.json('yandex', primary(params, 'text'), options);
+    }
+    /** Подсказки Яндекса: до 50 фраз с учётом региона. 0.01 ₽ за запрос. */
+    async yandexSuggest(params, options) {
+        return this.http.json('yandex/suggest', primary(params, 'text'), options);
+    }
+    /** Код региона (lr) по названию города или области. Бесплатно, нужен ключ. */
+    async yandexRegions(params, options) {
+        return this.http.json('yandex/regions', primary(params, 'name'), options);
+    }
+    /** Картинки Яндекса: 20 карточек на страницу, 0.01 ₽ за страницу. */
+    async yandexImages(params, options) {
+        return this.http.json('yandex/images', primary(params, 'q'), options);
+    }
+    /** Видео Яндекса: 20 карточек на страницу, 0.01 ₽ за страницу. */
+    async yandexVideo(params, options) {
+        return this.http.json('yandex/video', primary(params, 'q'), options);
+    }
+    // Google
+    /** Органическая выдача google.com: мобильная, 0.01 ₽ за страницу. */
+    async google(params, options) {
+        return this.http.json('google', primary(params, 'q'), options);
+    }
+    /** Подсказки Google: до ~15 фраз. 0.01 ₽ за запрос. */
+    async googleSuggest(params, options) {
+        return this.http.json('google/suggest', primary(params, 'q'), options);
+    }
+    /** ID региона Google по названию и готовый `uule`. Бесплатно, нужен ключ. */
+    async googleRegions(params, options) {
+        return this.http.json('google/regions', primary(params, 'name'), options);
+    }
+    /** Картинки Google: 100 карточек на страницу, 0.01 ₽ за страницу. */
+    async googleImages(params, options) {
+        return this.http.json('google/images', primary(params, 'q'), options);
+    }
+    /** Видео Google: 10 карточек на страницу, 0.01 ₽ за страницу. */
+    async googleVideo(params, options) {
+        return this.http.json('google/video', primary(params, 'q'), options);
+    }
+    // Bing
+    /** Органическая выдача bing.com: без локации — Россия, 0.01 ₽ за страницу. */
+    async bing(params, options) {
+        return this.http.json('bing', primary(params, 'q'), options);
+    }
+    /** Подсказки Bing. 0.01 ₽ за запрос. */
+    async bingSuggest(params, options) {
+        return this.http.json('bing/suggest', primary(params, 'q'), options);
+    }
+    /** Картинки Bing: `count` карточек (по умолчанию 35), дальше 700-й не листает. */
+    async bingImages(params, options) {
+        return this.http.json('bing/images', primary(params, 'q'), options);
+    }
+    /** Видео Bing: `count` карточек на страницу, по умолчанию 105. */
+    async bingVideo(params, options) {
+        return this.http.json('bing/video', primary(params, 'q'), options);
+    }
+    // Вордстат
+    /** Популярные и похожие запросы. 0.01 ₽ за запрос. */
+    async wordstat(params, options) {
+        return this.http.json('wordstat', primary(params, 'text'), options);
+    }
+    /** Частота запроса одним числом — `results.totalValue`. 0.01 ₽ за запрос. */
+    async wordstatFrequency(params, options) {
+        return this.http.json('wordstat/frequency', primary(params, 'text'), options);
+    }
+    /** Динамика показов по месяцам, неделям или дням. 0.01 ₽ за запрос. */
+    async wordstatGraph(params, options) {
+        return this.http.json('wordstat/graph', primary(params, 'text'), options);
+    }
+    /**
+     * Показы по регионам и городам. `popularity` — affinity-индекс: 100 —
+     * средний интерес. 0.01 ₽ за запрос.
+     */
+    async wordstatMap(params, options) {
+        return this.http.json('wordstat/map', primary(params, 'text'), options);
+    }
+    // Директ и служебные методы
+    /**
+     * Прогноз показов Директа со ставками и бюджетом. Кабинет не нужен.
+     *
+     * 0.01 ₽ за пачку до 4000 символов (около 150 фраз). До 1000 фраз за
+     * запрос, 100 запросов в час.
+     */
+    async direct(params, options) {
+        return this.http.json('direct', primary(params, 'phrases'), options);
+    }
+    /** Страна, регион и координаты по IPv4. Бесплатно, нужен ключ. */
+    async geoip(params, options) {
+        return this.http.json('geoip', primary(params, 'ip'), options);
+    }
+    /** Текущий баланс. Бесплатно, нужен ключ. */
+    async balance(options) {
+        return this.http.json('balance', {}, options);
+    }
+    // Запасной выход
+    /** Произвольный метод API — если в сервисе появился новый. */
+    async call(path, params = {}, options) {
+        return this.http.json(path, params, options);
+    }
+    /** То же, но ответ возвращается строкой без разбора. */
+    async callRaw(path, params = {}, options) {
+        return this.http.text(path, params, options);
+    }
+}
+exports.JsonSeoClient = JsonSeoClient;
+/** Даёт вызывать метод строкой или, для `direct()`, списком фраз. */
+function primary(params, key) {
+    if (typeof params === 'string' || Array.isArray(params)) {
+        return { [key]: params };
+    }
+    if (params === null || typeof params !== 'object') {
+        throw new errors_js_1.InvalidArgumentError('Параметры метода передаются строкой, массивом или объектом.');
+    }
+    return params;
+}

package/dist/cjs/common.d.ts

@@ -0,0 +1,40 @@
+/** Значение параметра: массив склеивается, флаг даёт 1/0, null не уедет. */
+export type ParamValue = string | number | boolean | ReadonlyArray<string | number> | null | undefined;
+/** Переключатель: API принимает и 1/0, и true/false. */
+export type Flag = boolean | 0 | 1;
+/** Устройство, с которого снимается выдача. */
+export type Device = 'mobile' | 'desktop' | 'tablet';
+/** У Google и Bing планшетной выдачи нет. */
+export type MobileDevice = 'mobile' | 'desktop';
+/** Фильтрация взрослого контента у Яндекса. */
+export type AdultFilter = 'none' | 'moderate' | 'strict';
+/** Она же у Bing — значения называются иначе. */
+export type BingSafeSearch = 'off' | 'moderate' | 'strict';
+/** SafeSearch Google. */
+export type GoogleSafeSearch = 'active' | 'off';
+/** Доменная зона Яндекса. */
+export type YandexZone = 'ru' | 'tr' | 'com' | 'kz' | 'by' | 'be' | 'kk' | 'uz' | 'com.tr';
+/** Язык названий в справочниках регионов. */
+export type RegionLanguage = 'ru' | 'en';
+/** Размер картинки. У Google меньшая ступень — это значки ровно 256 px. */
+export type ImageSize = 'large' | 'medium' | 'small';
+/** Ориентация картинки. Есть у всех трёх поисковиков. */
+export type ImageOrientation = 'horizontal' | 'vertical' | 'square';
+/** Цвет: color — полноцветные, mono — чёрно-белые, остальное — основной. */
+export type ImageColor = 'color' | 'mono' | 'red' | 'orange' | 'yellow' | 'green' | 'teal' | 'blue' | 'purple' | 'white' | 'black' | 'pink' | 'brown';
+/** Тип изображения: transparent нет у Яндекса, demotivator есть только у него. */
+export type ImageType = 'photo' | 'clipart' | 'lineart' | 'face' | 'animated' | 'transparent' | 'demotivator';
+/** Формат файла. У Bing поддерживается только gif. */
+export type ImageFormat = 'jpg' | 'png' | 'gif';
+/** Насколько свежий результат. Окна у поисковиков свои. */
+export type Freshness = 'day' | 'week' | 'month' | 'year';
+/** Длительность ролика. Границы ступеней у каждого поисковика свои. */
+export type VideoDuration = 'short' | 'medium' | 'long';
+/** Вид частотности: операторы расставит сервис, кавычки не нужны. */
+export type WordstatKind = 'base' | 'phrase' | 'exact' | 'superexact';
+/** Шаг динамики: month и week — история с 2018 года, day — последние 60 дней. */
+export type WordstatGraphType = 'day' | 'week' | 'month';
+/** Разрез географии показов. */
+export type WordstatMapType = 'all' | 'regions' | 'cities';
+/** Период прогноза Яндекс Директа. */
+export type DirectPeriod = 'week' | 'month' | 'quarter' | 'year';

package/dist/cjs/common.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/errors.d.ts

@@ -0,0 +1,71 @@
+/** Общий предок всех ошибок SDK. */
+export declare class JsonSeoError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Сервис ответил отказом. Тело сохраняется целиком. */
+export declare class JsonSeoApiError extends JsonSeoError {
+    /** HTTP-статус ответа. */
+    readonly status: number;
+    /** Тело ответа как есть. */
+    readonly body: string;
+    /** Разобранный JSON ответа. Пустой объект, если тело не разобралось. */
+    readonly payload: Record<string, unknown>;
+    /** Через сколько секунд вернуться. null, если срок не назван. */
+    readonly retryAfter: number | null;
+    constructor(message: string, status: number, body: string, payload: Record<string, unknown>, retryAfter?: number | null);
+}
+/** 402: на счёте не хватает средств. */
+export declare class PaymentRequiredError extends JsonSeoApiError {
+}
+/** 403 или 401: ключ не передан или недействителен. */
+export declare class UnauthorizedError extends JsonSeoApiError {
+}
+/** 503: выдачу получить не вышло. Деньги не списаны, повтор обычно проходит. */
+export declare class ServiceUnavailableError extends JsonSeoApiError {
+}
+/** 422: параметры запроса не приняты. Деньги не списываются. */
+export declare class ValidationError extends JsonSeoApiError {
+    /** Ошибки по именам параметров: `{ text: ['Введите запрос'] }`. */
+    get errors(): Record<string, string[]>;
+    /** Забракованные параметры. */
+    get fields(): string[];
+}
+/** 429: превышен лимит частоты. Срок повтора — в `retryAfter`. */
+export declare class RateLimitError extends JsonSeoApiError {
+}
+/** До сервиса не достучались: сеть, DNS, TLS. Статуса нет. */
+export declare class NetworkError extends JsonSeoError {
+    constructor(message: string, cause?: unknown);
+}
+/** Запрос не уложился в отведённое время и был прерван на стороне клиента. */
+export declare class TimeoutError extends NetworkError {
+}
+/**
+ * Заголовки пришли, а тело дочитать не вышло. Автоматически не повторяется:
+ * выдача уже собрана и оплачена, обрыв случился на отдаче.
+ */
+export declare class IncompleteResponseError extends NetworkError {
+}
+/** Запрос прерван переданным в него AbortSignal. */
+export declare class AbortError extends JsonSeoError {
+}
+/** Запрос не отправлен: SDK забраковал аргументы ещё до обращения к сети. */
+export declare class InvalidArgumentError extends JsonSeoError {
+}
+/**
+ * Успех, но тело не разобралось как JSON. Тело сохраняется: страница уже
+ * оплачена, и достать из неё данные руками лучше, чем не иметь ничего.
+ */
+export declare class ParseError extends JsonSeoError {
+    /** Тело ответа как есть. */
+    readonly body: string;
+    constructor(message: string, body: string);
+}
+/**
+ * Собирает ошибку под этот HTTP-статус.
+ *
+ * @internal
+ */
+export declare function apiErrorFor(status: number, body: string, payload: Record<string, unknown>, retryAfter: number | null): JsonSeoApiError;

package/dist/cjs/errors.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ParseError = exports.InvalidArgumentError = exports.AbortError = exports.IncompleteResponseError = exports.TimeoutError = exports.NetworkError = exports.RateLimitError = exports.ValidationError = exports.ServiceUnavailableError = exports.UnauthorizedError = exports.PaymentRequiredError = exports.JsonSeoApiError = exports.JsonSeoError = void 0;
+exports.apiErrorFor = apiErrorFor;
+/** Общий предок всех ошибок SDK. */
+class JsonSeoError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = new.target.name;
+        // Иначе instanceof ломается в сборках под ES5.
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.JsonSeoError = JsonSeoError;
+/** Сервис ответил отказом. Тело сохраняется целиком. */
+class JsonSeoApiError extends JsonSeoError {
+    constructor(message, status, body, payload, retryAfter = null) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.payload = payload;
+        this.retryAfter = retryAfter;
+    }
+}
+exports.JsonSeoApiError = JsonSeoApiError;
+/** 402: на счёте не хватает средств. */
+class PaymentRequiredError extends JsonSeoApiError {
+}
+exports.PaymentRequiredError = PaymentRequiredError;
+/** 403 или 401: ключ не передан или недействителен. */
+class UnauthorizedError extends JsonSeoApiError {
+}
+exports.UnauthorizedError = UnauthorizedError;
+/** 503: выдачу получить не вышло. Деньги не списаны, повтор обычно проходит. */
+class ServiceUnavailableError extends JsonSeoApiError {
+}
+exports.ServiceUnavailableError = ServiceUnavailableError;
+/** 422: параметры запроса не приняты. Деньги не списываются. */
+class ValidationError extends JsonSeoApiError {
+    /** Ошибки по именам параметров: `{ text: ['Введите запрос'] }`. */
+    get errors() {
+        const raw = this.payload.errors;
+        if (raw === null || typeof raw !== 'object') {
+            return {};
+        }
+        const errors = {};
+        for (const [field, messages] of Object.entries(raw)) {
+            errors[field] = Array.isArray(messages) ? messages.map(String) : [String(messages)];
+        }
+        return errors;
+    }
+    /** Забракованные параметры. */
+    get fields() {
+        return Object.keys(this.errors);
+    }
+}
+exports.ValidationError = ValidationError;
+/** 429: превышен лимит частоты. Срок повтора — в `retryAfter`. */
+class RateLimitError extends JsonSeoApiError {
+}
+exports.RateLimitError = RateLimitError;
+/** До сервиса не достучались: сеть, DNS, TLS. Статуса нет. */
+class NetworkError extends JsonSeoError {
+    constructor(message, cause) {
+        super(message, { cause });
+    }
+}
+exports.NetworkError = NetworkError;
+/** Запрос не уложился в отведённое время и был прерван на стороне клиента. */
+class TimeoutError extends NetworkError {
+}
+exports.TimeoutError = TimeoutError;
+/**
+ * Заголовки пришли, а тело дочитать не вышло. Автоматически не повторяется:
+ * выдача уже собрана и оплачена, обрыв случился на отдаче.
+ */
+class IncompleteResponseError extends NetworkError {
+}
+exports.IncompleteResponseError = IncompleteResponseError;
+/** Запрос прерван переданным в него AbortSignal. */
+class AbortError extends JsonSeoError {
+}
+exports.AbortError = AbortError;
+/** Запрос не отправлен: SDK забраковал аргументы ещё до обращения к сети. */
+class InvalidArgumentError extends JsonSeoError {
+}
+exports.InvalidArgumentError = InvalidArgumentError;
+/**
+ * Успех, но тело не разобралось как JSON. Тело сохраняется: страница уже
+ * оплачена, и достать из неё данные руками лучше, чем не иметь ничего.
+ */
+class ParseError extends JsonSeoError {
+    constructor(message, body) {
+        super(message);
+        this.body = body;
+    }
+}
+exports.ParseError = ParseError;
+/**
+ * Собирает ошибку под этот HTTP-статус.
+ *
+ * @internal
+ */
+function apiErrorFor(status, body, payload, retryAfter) {
+    const message = typeof payload.message === 'string' && payload.message !== ''
+        ? payload.message
+        : `JSON SEO API вернул ошибку ${status}.`;
+    switch (status) {
+        case 401:
+        case 403:
+            return new UnauthorizedError(message, status, body, payload, retryAfter);
+        case 402:
+            return new PaymentRequiredError(message, status, body, payload, retryAfter);
+        case 422:
+            return new ValidationError(message, status, body, payload, retryAfter);
+        case 429:
+            return new RateLimitError(message, status, body, payload, retryAfter);
+        case 503:
+            return new ServiceUnavailableError(message, status, body, payload, retryAfter);
+        default:
+            return new JsonSeoApiError(message, status, body, payload, retryAfter);
+    }
+}

package/dist/cjs/http.d.ts

@@ -0,0 +1,77 @@
+import type { ParamValue } from './common.js';
+/** Глобальный `fetch` или любая его замена. */
+export type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
+/** Куда класть ключ: в заголовок Authorization или в параметр key. */
+export type AuthMode = 'header' | 'query';
+/** Настройки клиента. */
+export interface ClientOptions {
+    /** Ключ из личного кабинета на jsonseo.ru. */
+    apiKey: string;
+    /** Адрес API. По умолчанию https://jsonseo.ru/api */
+    baseUrl?: string;
+    /** Сколько ждать ответа на одну попытку. По умолчанию 300 000 мс. */
+    timeoutMs?: number;
+    /** Сколько всего попыток у запроса, включая первую. По умолчанию 3. */
+    attempts?: number;
+    /** Стартовая пауза между попытками, миллисекунд. По умолчанию 1000. */
+    retryDelayMs?: number;
+    /**
+     * Потолок паузы между попытками, миллисекунд. По умолчанию 30 000. Если
+     * сервис просит ждать дольше, повторов не будет вовсе.
+     */
+    maxRetryDelayMs?: number;
+    /** Где передавать ключ. В заголовке — чтобы не оседал в логах прокси. */
+    auth?: AuthMode;
+    /** Своя подпись клиента. */
+    userAgent?: string;
+    /** Своя реализация fetch — для тестов или прокси. */
+    fetch?: FetchLike;
+}
+/** Настройки одного запроса. */
+export interface RequestOptions {
+    /** Отмена запроса снаружи. */
+    signal?: AbortSignal;
+    /** Таймаут именно этого запроса, миллисекунд. */
+    timeoutMs?: number;
+}
+/**
+ * Транспорт: собирает запрос, разбирает ответ и решает, повторять ли отказ.
+ *
+ * @internal
+ */
+export declare class HttpClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly attempts;
+    private readonly retryDelayMs;
+    private readonly maxRetryDelayMs;
+    private readonly auth;
+    private readonly userAgent;
+    private readonly fetchImpl;
+    constructor(options: ClientOptions);
+    /** Запрос, ответ которого разбирается как JSON. */
+    json<T>(path: string, params: Record<string, ParamValue>, options?: RequestOptions): Promise<T>;
+    /** Запрос, ответ которого возвращается строкой без разбора. */
+    text(path: string, params: Record<string, ParamValue>, options?: RequestOptions): Promise<string>;
+    /**
+     * Выполняет запрос, повторяя те отказы, за которые сервис не берёт денег:
+     * 429, 5xx и обрывы связи до того, как ответ начал приходить.
+     */
+    private send;
+    /**
+     * Один заход в сеть: таймаут и внешняя отмена сводятся в один сигнал.
+     * Тело читается здесь же — fetch отдаёт ответ сразу по заголовкам, и
+     * снаружи застрявшая передача висела бы без ограничения по времени.
+     */
+    private fetchOnce;
+    /** Попытки нумеруются с нуля: при attempts = 3 последняя — вторая. */
+    private isLastAttempt;
+    /**
+     * Пауза удваивается с каждой попыткой; случайная добавка разводит
+     * параллельные запросы, чтобы они не вернулись разом.
+     */
+    private backoff;
+}
+/** Приводит параметры к тому виду, в каком их ждёт форма запроса. */
+export declare function encodeParams(params: Record<string, ParamValue>): URLSearchParams;