jsonseo 1.0.0

package/dist/esm/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/esm/errors.js

@@ -0,0 +1,106 @@
+/** Общий предок всех ошибок SDK. */
+export class JsonSeoError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = new.target.name;
+        // Иначе instanceof ломается в сборках под ES5.
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/** Сервис ответил отказом. Тело сохраняется целиком. */
+export 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;
+    }
+}
+/** 402: на счёте не хватает средств. */
+export class PaymentRequiredError extends JsonSeoApiError {
+}
+/** 403 или 401: ключ не передан или недействителен. */
+export class UnauthorizedError extends JsonSeoApiError {
+}
+/** 503: выдачу получить не вышло. Деньги не списаны, повтор обычно проходит. */
+export class ServiceUnavailableError extends JsonSeoApiError {
+}
+/** 422: параметры запроса не приняты. Деньги не списываются. */
+export 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);
+    }
+}
+/** 429: превышен лимит частоты. Срок повтора — в `retryAfter`. */
+export class RateLimitError extends JsonSeoApiError {
+}
+/** До сервиса не достучались: сеть, DNS, TLS. Статуса нет. */
+export class NetworkError extends JsonSeoError {
+    constructor(message, cause) {
+        super(message, { cause });
+    }
+}
+/** Запрос не уложился в отведённое время и был прерван на стороне клиента. */
+export class TimeoutError extends NetworkError {
+}
+/**
+ * Заголовки пришли, а тело дочитать не вышло. Автоматически не повторяется:
+ * выдача уже собрана и оплачена, обрыв случился на отдаче.
+ */
+export class IncompleteResponseError extends NetworkError {
+}
+/** Запрос прерван переданным в него AbortSignal. */
+export class AbortError extends JsonSeoError {
+}
+/** Запрос не отправлен: SDK забраковал аргументы ещё до обращения к сети. */
+export class InvalidArgumentError extends JsonSeoError {
+}
+/**
+ * Успех, но тело не разобралось как JSON. Тело сохраняется: страница уже
+ * оплачена, и достать из неё данные руками лучше, чем не иметь ничего.
+ */
+export class ParseError extends JsonSeoError {
+    constructor(message, body) {
+        super(message);
+        this.body = body;
+    }
+}
+/**
+ * Собирает ошибку под этот HTTP-статус.
+ *
+ * @internal
+ */
+export 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/esm/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;

package/dist/esm/http.js

@@ -0,0 +1,302 @@
+import { AbortError, apiErrorFor, IncompleteResponseError, InvalidArgumentError, JsonSeoError, NetworkError, ParseError, TimeoutError, } from './errors.js';
+const DEFAULT_BASE_URL = 'https://jsonseo.ru/api';
+/**
+ * Ключи проверяются типом: забытая здесь настройка из ClientOptions
+ * отвергалась бы у пользователя как незнакомая.
+ */
+const KNOWN_OPTIONS = {
+    apiKey: true,
+    baseUrl: true,
+    timeoutMs: true,
+    attempts: true,
+    retryDelayMs: true,
+    maxRetryDelayMs: true,
+    auth: true,
+    userAgent: true,
+    fetch: true,
+};
+const KNOWN_OPTION_NAMES = Object.keys(KNOWN_OPTIONS);
+const VERSION = '1.0.0';
+/**
+ * Транспорт: собирает запрос, разбирает ответ и решает, повторять ли отказ.
+ *
+ * @internal
+ */
+export class HttpClient {
+    constructor(options) {
+        if (typeof options.apiKey !== 'string' || options.apiKey.trim() === '') {
+            throw new InvalidArgumentError('Нужен API-ключ: возьмите его в личном кабинете на https://jsonseo.ru.');
+        }
+        // undefined из спреда частичного конфига — не настройка, а её отсутствие.
+        const unknown = Object.keys(options).filter((name) => !KNOWN_OPTION_NAMES.includes(name) && options[name] !== undefined);
+        if (unknown.length > 0) {
+            throw new InvalidArgumentError(`Неизвестные настройки клиента: ${unknown.join(', ')}. Доступны: ${KNOWN_OPTION_NAMES.join(', ')}.`);
+        }
+        // NaN сюда приезжает из Number(process.env.ЧЕГО_НЕТ), и без проверки
+        // сравнение с ним всегда ложно — повторы платного запроса не кончались бы.
+        if (options.attempts !== undefined && (!Number.isInteger(options.attempts) || options.attempts < 1)) {
+            throw new InvalidArgumentError(`Настройка attempts ожидает целое число не меньше 1, получено: ${String(options.attempts)}.`);
+        }
+        if (options.auth !== undefined && options.auth !== 'header' && options.auth !== 'query') {
+            throw new InvalidArgumentError(`Настройка auth принимает "header" или "query", получено: ${String(options.auth)}.`);
+        }
+        const fetchImpl = options.fetch ?? (typeof fetch === 'function' ? fetch : undefined);
+        if (!fetchImpl) {
+            throw new InvalidArgumentError('В этой среде нет глобального fetch. Нужен Node 18+, Bun или Deno — либо передайте свою реализацию настройкой fetch.');
+        }
+        this.apiKey = options.apiKey.trim();
+        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+        this.timeoutMs = options.timeoutMs ?? 300000;
+        this.attempts = options.attempts ?? 3;
+        this.retryDelayMs = options.retryDelayMs ?? 1000;
+        this.maxRetryDelayMs = options.maxRetryDelayMs ?? 30000;
+        this.auth = options.auth ?? 'header';
+        this.userAgent = options.userAgent ?? `jsonseo-node/${VERSION}`;
+        this.fetchImpl = fetchImpl;
+    }
+    /** Запрос, ответ которого разбирается как JSON. */
+    async json(path, params, options) {
+        const body = await this.send(path, params, 'application/json', options);
+        try {
+            return JSON.parse(body);
+        }
+        catch (error) {
+            // Тело кладём в ошибку: страница выдачи уже оплачена.
+            throw new ParseError(`Ответ JSON SEO API не разобрался как JSON: ${error.message}.`, body);
+        }
+    }
+    /** Запрос, ответ которого возвращается строкой без разбора. */
+    text(path, params, options) {
+        return this.send(path, params, 'application/xml, text/xml', options);
+    }
+    /**
+     * Выполняет запрос, повторяя те отказы, за которые сервис не берёт денег:
+     * 429, 5xx и обрывы связи до того, как ответ начал приходить.
+     */
+    async send(path, params, accept, options) {
+        const query = encodeParams(params);
+        if (this.auth === 'query') {
+            query.set('key', this.apiKey);
+        }
+        const headers = {
+            Accept: accept,
+            'Content-Type': 'application/x-www-form-urlencoded',
+            'User-Agent': this.userAgent,
+        };
+        if (this.auth === 'header') {
+            headers.Authorization = `Bearer ${this.apiKey}`;
+        }
+        // Всегда POST: длинные списки фраз в GET не помещаются.
+        const url = `${this.baseUrl}/${path.replace(/^\/+/, '')}`;
+        const body = query.toString();
+        for (let attempt = 0;; attempt++) {
+            let response;
+            try {
+                response = await this.fetchOnce(url, headers, body, options);
+            }
+            catch (error) {
+                // Таймаут и обрыв на середине тела не повторяем: выдача уже
+                // собрана и оплачена.
+                if (error instanceof NetworkError &&
+                    !(error instanceof TimeoutError) &&
+                    !(error instanceof IncompleteResponseError) &&
+                    !this.isLastAttempt(attempt)) {
+                    try {
+                        await sleep(this.backoff(attempt), options?.signal);
+                    }
+                    catch (aborted) {
+                        // Отменили во время паузы: причину ожидания не теряем.
+                        aborted.cause = error;
+                        throw aborted;
+                    }
+                    continue;
+                }
+                throw error;
+            }
+            if (response.ok) {
+                return response.body;
+            }
+            const { retryAfter } = response;
+            const error = apiErrorFor(response.status, response.body, parseQuietly(response.body), retryAfter);
+            // Проснуться раньше названного срока — снова получить тот же отказ.
+            // Ждать дольше потолка не станем: отдаём ошибку.
+            if (this.isLastAttempt(attempt) ||
+                !isRetryable(response.status) ||
+                (retryAfter !== null && retryAfter * 1000 > this.maxRetryDelayMs)) {
+                throw error;
+            }
+            // Не раньше, чем просит сервис, и не чаще своего бэкоффа:
+            // Retry-After прошедшей датой даёт ноль.
+            const pause = retryAfter === null ? this.backoff(attempt) : Math.max(retryAfter * 1000, this.backoff(attempt));
+            await sleep(pause, options?.signal);
+        }
+    }
+    /**
+     * Один заход в сеть: таймаут и внешняя отмена сводятся в один сигнал.
+     * Тело читается здесь же — fetch отдаёт ответ сразу по заголовкам, и
+     * снаружи застрявшая передача висела бы без ограничения по времени.
+     */
+    async fetchOnce(url, headers, body, options) {
+        const external = options?.signal;
+        if (external?.aborted) {
+            throw new AbortError('Запрос отменён до отправки.');
+        }
+        const controller = new AbortController();
+        const timeoutMs = options?.timeoutMs ?? this.timeoutMs;
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+        }, timeoutMs);
+        const forward = () => controller.abort();
+        external?.addEventListener('abort', forward);
+        try {
+            const response = await this.fetchImpl(url, {
+                method: 'POST',
+                headers,
+                body,
+                signal: controller.signal,
+                redirect: 'follow',
+            });
+            let text;
+            try {
+                text = await response.text();
+            }
+            catch (error) {
+                if (timedOut) {
+                    throw new TimeoutError(`Ответа от JSON SEO API не дождались за ${timeoutMs} мс.`, error);
+                }
+                if (external?.aborted) {
+                    throw new AbortError('Запрос отменён.');
+                }
+                // Тело дочитать не вышло, а выдача уже оплачена — отдельный
+                // класс ошибки, повторять такое нельзя.
+                throw new IncompleteResponseError(`Ответ от JSON SEO API пришёл не целиком: ${error.message}.`, error);
+            }
+            return {
+                status: response.status,
+                ok: response.ok,
+                retryAfter: parseRetryAfter(response.headers.get('retry-after')),
+                body: text,
+            };
+        }
+        catch (error) {
+            if (error instanceof JsonSeoError) {
+                throw error;
+            }
+            if (timedOut) {
+                throw new TimeoutError(`Ответа от JSON SEO API не дождались за ${timeoutMs} мс.`, error);
+            }
+            if (external?.aborted) {
+                throw new AbortError('Запрос отменён.');
+            }
+            throw new NetworkError(`Запрос к JSON SEO API не удался: ${error.message}.`, error);
+        }
+        finally {
+            clearTimeout(timer);
+            external?.removeEventListener('abort', forward);
+        }
+    }
+    /** Попытки нумеруются с нуля: при attempts = 3 последняя — вторая. */
+    isLastAttempt(attempt) {
+        return attempt + 1 >= this.attempts;
+    }
+    /**
+     * Пауза удваивается с каждой попыткой; случайная добавка разводит
+     * параллельные запросы, чтобы они не вернулись разом.
+     */
+    backoff(attempt) {
+        const delay = this.retryDelayMs * 2 ** attempt;
+        // Потолок накладывается после добавки, иначе она бы его превышала.
+        return Math.min(delay + delay * 0.25 * Math.random(), this.maxRetryDelayMs);
+    }
+}
+/** Приводит параметры к тому виду, в каком их ждёт форма запроса. */
+export function encodeParams(params) {
+    const query = new URLSearchParams();
+    for (const [name, value] of Object.entries(params)) {
+        if (value === null || value === undefined) {
+            continue;
+        }
+        if (Array.isArray(value)) {
+            // Пустой список — «параметр не задан»: от region= сервис откажет.
+            if (value.length === 0) {
+                continue;
+            }
+            // Фразы — переводом строки: запятая в них встречается.
+            query.set(name, value.map((item, index) => scalar(`${name}[${index}]`, item)).join(name === 'phrases' ? '\n' : ','));
+            continue;
+        }
+        query.set(name, scalar(name, value));
+    }
+    return query;
+}
+function scalar(name, value) {
+    if (typeof value === 'boolean') {
+        return value ? '1' : '0';
+    }
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value)) {
+            throw new InvalidArgumentError(`Параметр ${name} получил не число: ${String(value)}.`);
+        }
+        return String(value);
+    }
+    if (typeof value === 'string') {
+        return value;
+    }
+    throw new InvalidArgumentError(`Параметр ${name} должен быть строкой, числом, флагом или массивом таких значений.`);
+}
+function isRetryable(status) {
+    return status === 429 || status >= 500;
+}
+/**
+ * Сколько секунд просит подождать сервис. RFC 9110 разрешает число секунд
+ * и HTTP-дату, разбираются обе.
+ */
+function parseRetryAfter(header) {
+    if (header === null) {
+        return null;
+    }
+    const value = header.trim();
+    if (/^\d+$/.test(value)) {
+        return Number(value);
+    }
+    const timestamp = Date.parse(value);
+    if (Number.isNaN(timestamp)) {
+        return null;
+    }
+    return Math.max(0, Math.round((timestamp - Date.now()) / 1000));
+}
+/** Тело ошибки может быть и не JSON — тогда подробностей просто нет. */
+function parseQuietly(body) {
+    try {
+        const parsed = JSON.parse(body);
+        return parsed !== null && typeof parsed === 'object' ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Прерываемая пауза: без учёта сигнала отмена замечалась бы только через
+ * всю паузу целиком, до 30 секунд при значениях по умолчанию.
+ */
+function sleep(ms, signal) {
+    if (!signal) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    if (signal.aborted) {
+        return Promise.reject(new AbortError('Запрос отменён.'));
+    }
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            signal.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        function onAbort() {
+            clearTimeout(timer);
+            reject(new AbortError('Запрос отменён.'));
+        }
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+}

package/dist/esm/index.d.ts

@@ -0,0 +1,9 @@
+export { JsonSeoClient } from './client.js';
+export { encodeParams } from './http.js';
+export type { AuthMode, ClientOptions, FetchLike, RequestOptions } from './http.js';
+export { AbortError, IncompleteResponseError, InvalidArgumentError, JsonSeoApiError, JsonSeoError, NetworkError, ParseError, PaymentRequiredError, RateLimitError, ServiceUnavailableError, TimeoutError, UnauthorizedError, ValidationError, } from './errors.js';
+export type * from './common.js';
+export type * from './params.js';
+export type * from './responses.js';
+import { JsonSeoClient } from './client.js';
+export default JsonSeoClient;

package/dist/esm/index.js

@@ -0,0 +1,5 @@
+export { JsonSeoClient } from './client.js';
+export { encodeParams } from './http.js';
+export { AbortError, IncompleteResponseError, InvalidArgumentError, JsonSeoApiError, JsonSeoError, NetworkError, ParseError, PaymentRequiredError, RateLimitError, ServiceUnavailableError, TimeoutError, UnauthorizedError, ValidationError, } from './errors.js';
+import { JsonSeoClient } from './client.js';
+export default JsonSeoClient;

package/dist/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}