parreq-client 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ParReq
+
+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,77 @@
+# parreq
+
+Клиент [ParReq](https://req.akuraq.dev) — поисковая выдача Google и Яндекса в
+JSON. Без зависимостей, на встроенном `fetch` (нужен Node 18+). Типы в комплекте.
+
+```bash
+npm i parreq
+```
+
+```js
+import { ParReq } from "parreq";
+
+const client = new ParReq({ apiKey: "pr_ВАШКЛЮЧ" });
+
+const res = await client.yandex({ q: "кофемашина", gl: "by", hl: "ru",
+                                  include: ["ads", "shopping"] });
+console.log(res.organic.length, "органических,", res.ads.length, "объявлений");
+
+for (const item of res.organic) {
+  console.log(item.position, item.title, item.link);
+}
+```
+
+`engine` обязателен, поэтому у общего метода он в объекте параметров, а для двух
+движков есть сахар:
+
+```js
+await client.search({ q: "coffee machine", engine: "google", gl: "us" });
+await client.google({ q: "coffee machine", gl: "us" });
+await client.yandex({ q: "кофемашина", gl: "by", hl: "ru" });
+```
+
+## Секции
+
+По умолчанию приходит только органика. Остальное — через `include`:
+
+```js
+const res = await client.google({
+  q: "купить кофемашину", gl: "by", hl: "ru",
+  include: ["ads", "shopping", "videos", "related_searches"],
+});
+res.ads; res.shopping; res.videos; res.related;
+```
+
+Доступно: `ads`, `shopping`, `local`, `knowledge_graph`, `ai_overview`,
+`answer_box`, `people_also_ask`, `related_searches`, `images`, `videos`, `news`,
+`total_results`, либо `include: "all"`.
+
+## Ошибки
+
+```js
+import { ParReq, ParReqError, NoWorkers, RateLimited } from "parreq";
+
+try {
+  const res = await client.google({ q: "coffee", gl: "us" });
+} catch (err) {
+  if (err instanceof NoWorkers) console.log("повторить через", err.retryAfter);
+  else if (err instanceof RateLimited) console.log(err.code, err.retryAfter);
+  else if (err instanceof ParReqError) console.log(err.status, err.code, err.requestId);
+  else throw err;
+}
+```
+
+Клиент **сам повторяет** то, что лечится повтором (429, 502, 503, 504), выжидая
+столько, сколько просит сервер в `Retry-After`. По умолчанию три попытки:
+
+```js
+new ParReq({ apiKey: "pr_…", retries: 0 });        // выключить повторы
+new ParReq({ apiKey: "pr_…", timeoutMs: 240_000 }); // запрос с капчей бывает долгим
+```
+
+## Свой расход
+
+```js
+const u = await client.usage();
+console.log(u.used_today, "из", u.limits.daily);
+```

package/index.d.ts

@@ -0,0 +1,86 @@
+export interface SearchOptions {
+  /** Поисковый запрос. */
+  q: string;
+  /** Обязателен: умолчания нет намеренно. */
+  engine: "google" | "yandex";
+  device?: "desktop" | "desktop_mac" | "mobile" | "mobile_ios" | "tablet";
+  gl?: string;
+  hl?: string;
+  page?: number;
+  num?: number;
+  location?: string;
+  domain?: string;
+  /** Секции сверх органики: ["ads","shopping"] либо "all". */
+  include?: string[] | string;
+}
+
+export type EngineOptions = Omit<SearchOptions, "engine">;
+
+export interface ClientOptions {
+  apiKey: string;
+  baseUrl?: string;
+  timeoutMs?: number;
+  retries?: number;
+}
+
+export interface SearchMetadata {
+  id: string;
+  status: string;
+  engine: string;
+  requested_url: string;
+  final_url: string;
+  fetch_ms: number;
+  total_ms: number;
+  html_size: number;
+  detected_location: string | null;
+  created_at: number;
+}
+
+export declare class SearchResult {
+  raw: Record<string, any>;
+  readonly metadata: SearchMetadata;
+  readonly parameters: Record<string, any>;
+  readonly requestId: string;
+  readonly organic: Record<string, any>[];
+  readonly ads: Record<string, any>[];
+  readonly shopping: Record<string, any>[];
+  readonly local: Record<string, any>[];
+  readonly videos: Record<string, any>[];
+  readonly images: Record<string, any>[];
+  readonly news: Record<string, any>[];
+  readonly related: Record<string, any>[];
+  readonly peopleAlsoAsk: Record<string, any>[];
+  readonly knowledgeGraph: Record<string, any> | null;
+  readonly answerBox: Record<string, any> | null;
+  readonly aiOverview: Record<string, any> | null;
+  readonly totalResults: number | null;
+}
+
+export declare class ParReqError extends Error {
+  status: number;
+  code: string;
+  detail: string;
+  requestId: string;
+  retryAfter: number | null;
+  details: Record<string, any>;
+  readonly retriable: boolean;
+}
+export declare class BadRequest extends ParReqError {}
+export declare class AuthError extends ParReqError {}
+export declare class RateLimited extends ParReqError {}
+export declare class NoWorkers extends ParReqError {}
+export declare class SearchBlocked extends ParReqError {}
+export declare class ServerError extends ParReqError {}
+
+export declare class ParReq {
+  constructor(options: ClientOptions | string);
+  search(options: SearchOptions): Promise<SearchResult>;
+  google(options: EngineOptions): Promise<SearchResult>;
+  yandex(options: EngineOptions): Promise<SearchResult>;
+  usage(): Promise<Record<string, any>>;
+  meta(): Promise<Record<string, any>>;
+}
+
+export declare const DEFAULT_BASE_URL: string;
+export declare const DEFAULT_TIMEOUT_MS: number;
+export default ParReq;

package/index.js

@@ -0,0 +1,195 @@
+/**
+ * ParReq — клиент поисковой выдачи Google и Яндекса.
+ *
+ * Зависимостей нет: используется встроенный fetch, поэтому нужен Node 18+.
+ * Тянуть axios ради одного запроса значит навязывать чужому проекту лишнее.
+ */
+
+export const DEFAULT_BASE_URL = "https://req.akuraq.dev";
+// Запрос идёт в настоящий браузер: 3–10 секунд на прогретом профиле и до двух
+// минут, если пришлось решать капчу. Таймаут меньше рвёт нормальные запросы.
+export const DEFAULT_TIMEOUT_MS = 180_000;
+// Коды, которые лечатся повтором. Остальные повторять бессмысленно: неверный
+// параметр и отозванный ключ от этого не исправятся.
+const RETRIABLE = new Set([429, 502, 503, 504]);
+const USER_AGENT = "parreq-node/1.0";
+
+/** Ошибка API. Разбирайте `code`, а не текст: текст переписывается. */
+export class ParReqError extends Error {
+  constructor(status, code, message, { requestId = "", retryAfter = null, details = {} } = {}) {
+    super(`${code}: ${message}`);
+    this.name = "ParReqError";
+    this.status = status;
+    this.code = code;
+    this.detail = message;
+    this.requestId = requestId;
+    this.retryAfter = retryAfter;
+    this.details = details;
+  }
+
+  /** Имеет ли смысл повторить этот запрос. */
+  get retriable() {
+    return RETRIABLE.has(this.status);
+  }
+}
+
+export class BadRequest extends ParReqError {}
+export class AuthError extends ParReqError {}
+export class RateLimited extends ParReqError {}
+export class NoWorkers extends ParReqError {}
+export class SearchBlocked extends ParReqError {}
+export class ServerError extends ParReqError {}
+
+const BY_CODE = {
+  invalid_request: BadRequest,
+  missing_api_key: AuthError,
+  invalid_api_key: AuthError,
+  key_revoked: AuthError,
+  admin_only: AuthError,
+  rate_limited: RateLimited,
+  quota_exceeded: RateLimited,
+  concurrency_limit: RateLimited,
+  no_workers_available: NoWorkers,
+  search_blocked: SearchBlocked,
+};
+
+function errorFrom(status, body, retryAfter) {
+  const err = (body && body.error) || {};
+  const code = err.code || `http_${status}`;
+  let Cls = BY_CODE[code];
+  if (!Cls) {
+    Cls = status === 400 ? BadRequest : status === 401 || status === 403 ? AuthError : ServerError;
+  }
+  return new Cls(status, code, err.message || "без описания", {
+    requestId: err.request_id || "",
+    retryAfter,
+    details: err.details || {},
+  });
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/** Ответ поиска: секции удобными геттерами плюс исходный JSON в `raw`. */
+export class SearchResult {
+  constructor(raw) {
+    this.raw = raw;
+  }
+  get metadata() { return this.raw.search_metadata || {}; }
+  get parameters() { return this.raw.search_parameters || {}; }
+  get requestId() { return this.metadata.id || ""; }
+  get organic() { return this.raw.organic_results || []; }
+  get ads() { return this.raw.ads || []; }
+  get shopping() { return this.raw.shopping_results || []; }
+  get local() { return this.raw.local_results || []; }
+  get videos() { return this.raw.inline_videos || []; }
+  get images() { return this.raw.inline_images || []; }
+  get news() { return this.raw.top_stories || []; }
+  get related() { return this.raw.related_searches || []; }
+  get peopleAlsoAsk() { return this.raw.people_also_ask || []; }
+  get knowledgeGraph() { return this.raw.knowledge_graph ?? null; }
+  get answerBox() { return this.raw.answer_box ?? null; }
+  get aiOverview() { return this.raw.ai_overview ?? null; }
+  get totalResults() { return this.raw.total_results ?? null; }
+}
+
+export class ParReq {
+  /**
+   * @param {object|string} options ключ строкой либо объект настроек
+   * @param {string} options.apiKey ключ вида `pr_…`
+   * @param {string} [options.baseUrl]
+   * @param {number} [options.timeoutMs]
+   * @param {number} [options.retries] сколько раз повторять то, что лечится повтором
+   */
+  constructor(options) {
+    const opts = typeof options === "string" ? { apiKey: options } : options || {};
+    if (!opts.apiKey) throw new Error("нужен ключ ParReq");
+    this.apiKey = opts.apiKey;
+    this.baseUrl = (opts.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.retries = Math.max(0, opts.retries ?? 3);
+  }
+
+  /**
+   * Поиск. `engine` обязателен: "google" или "yandex".
+   * `include` — секции сверх органики: ["ads", "shopping"] либо "all".
+   */
+  async search({ q, engine, device = "desktop", gl = "us", hl = "en", page = 1,
+                 num, location, domain, include } = {}) {
+    if (!q) throw new Error("нужен запрос q");
+    if (!engine) throw new Error("нужен engine: google или yandex");
+    const params = { q, engine, device, gl, hl, page };
+    if (num != null) params.num = num;
+    if (location) params.location = location;
+    if (domain) params.domain = domain;
+    if (include) params.include = Array.isArray(include) ? include.join(",") : include;
+    return new SearchResult(await this.#request("GET", "/v1/search", params));
+  }
+
+  /** Сахар: `client.google({ q: "coffee machine", gl: "us" })`. */
+  async google(options) { return this.search({ ...options, engine: "google" }); }
+
+  /** Сахар: `client.yandex({ q: "кофемашина", gl: "by", hl: "ru" })`. */
+  async yandex(options) { return this.search({ ...options, engine: "yandex" }); }
+
+  /** Остаток лимитов по своему ключу. */
+  async usage() { return this.#request("GET", "/v1/usage"); }
+
+  /** Справочники: движки, устройства, страны, языки, секции. */
+  async meta() { return this.#request("GET", "/v1/meta"); }
+
+  async #request(method, path, params) {
+    const url = new URL(this.baseUrl + path);
+    for (const [k, v] of Object.entries(params || {})) url.searchParams.set(k, String(v));
+
+    let last;
+    for (let attempt = 0; attempt <= this.retries; attempt++) {
+      try {
+        return await this.#once(method, url);
+      } catch (err) {
+        if (!(err instanceof ParReqError) || !err.retriable || attempt === this.retries) throw err;
+        last = err;
+        // ждём столько, сколько попросил сервер: у суточной квоты это время до
+        // полуночи, и «подождать 5 секунд» там ничего не изменит
+        await sleep((err.retryAfter ?? 5) * 1000);
+      }
+    }
+    throw last;
+  }
+
+  async #once(method, url) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    let resp;
+    try {
+      resp = await fetch(url, {
+        method,
+        signal: controller.signal,
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          Accept: "application/json",
+          "User-Agent": USER_AGENT,
+        },
+      });
+    } catch (err) {
+      const reason = err.name === "AbortError" ? `превышен таймаут ${this.timeoutMs} мс` : String(err);
+      throw new ServerError(0, "connection_error", reason);
+    } finally {
+      clearTimeout(timer);
+    }
+
+    const text = await resp.text();
+    let body;
+    try {
+      body = text ? JSON.parse(text) : {};
+    } catch {
+      body = { error: { code: `http_${resp.status}`, message: text.slice(0, 200) } };
+    }
+    if (!resp.ok) {
+      const ra = resp.headers.get("retry-after");
+      throw errorFrom(resp.status, body, ra ? Number(ra) : null);
+    }
+    return body;
+  }
+}
+
+export default ParReq;

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "parreq-client",
+  "version": "1.0.0",
+  "description": "Клиент ParReq: поисковая выдача Google и Яндекса в JSON",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "serp",
+    "google",
+    "yandex",
+    "search-api",
+    "scraping"
+  ],
+  "license": "MIT",
+  "homepage": "https://req.akuraq.dev",
+  "scripts": {
+    "smoke": "node smoke.mjs"
+  }
+}