parreq-client 1.0.0 → 1.4.0

package/README.md

@@ -1,16 +1,16 @@
 # parreq
 
-Клиент [ParReq](https://req.akuraq.dev) — поисковая выдача Google и Яндекса в
+Клиент [Parreq](https://parreq.com) — поисковая выдача Google и Яндекса в
 JSON. Без зависимостей, на встроенном `fetch` (нужен Node 18+). Типы в комплекте.
 
 ```bash
-npm i parreq
+npm i parreq-client
 ```
 
 ```js
-import { ParReq } from "parreq";
+import { Parreq } from "parreq-client";
 
-const client = new ParReq({ apiKey: "pr_ВАШКЛЮЧ" });
+const client = new Parreq({ apiKey: "pr_ВАШКЛЮЧ" });
 
 const res = await client.yandex({ q: "кофемашина", gl: "by", hl: "ru",
                                   include: ["ads", "shopping"] });
@@ -49,14 +49,14 @@ res.ads; res.shopping; res.videos; res.related;
 ## Ошибки
 
 ```js
-import { ParReq, ParReqError, NoWorkers, RateLimited } from "parreq";
+import { Parreq, ParreqError, NoWorkers, RateLimited } from "parreq-client";
 
 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 if (err instanceof ParreqError) console.log(err.status, err.code, err.requestId);
   else throw err;
 }
 ```
@@ -65,8 +65,8 @@ try {
 столько, сколько просит сервер в `Retry-After`. По умолчанию три попытки:
 
 ```js
-new ParReq({ apiKey: "pr_…", retries: 0 });        // выключить повторы
-new ParReq({ apiKey: "pr_…", timeoutMs: 240_000 }); // запрос с капчей бывает долгим
+new Parreq({ apiKey: "pr_…", retries: 0 });        // выключить повторы
+new Parreq({ apiKey: "pr_…", timeoutMs: 240_000 }); // запрос с капчей бывает долгим
 ```
 
 ## Свой расход

package/index.d.ts

@@ -16,6 +16,48 @@ export interface SearchOptions {
 
 export type EngineOptions = Omit<SearchOptions, "engine">;
 
+/** Платные надстройки Fetch, заказываемые через include. */
+export type FetchExtra = "js" | "css" | "network" | "screenshot" | "iframe";
+
+export interface FetchOptions {
+  /** Адрес страницы; схема http или https. */
+  url: string;
+  device?: "desktop" | "desktop_mac" | "mobile" | "mobile_ios" | "tablet";
+  gl?: string;
+  hl?: string;
+  /** Платные надстройки: ["js","network"] либо "all". */
+  include?: FetchExtra[] | string;
+  /** false — сбор браузером с окном, платно. */
+  headless?: boolean;
+  waitMs?: number;
+  /** Ждать появления блока: CSS, XPath или название блока. */
+  waitFor?: string;
+  /** Окно наблюдения за сетью после загрузки, мс. По умолчанию 1000. */
+  networkMs?: number;
+  scroll?: boolean;
+  /** Начать разметку с этого блока. */
+  startAt?: string;
+  /** Отдать только этот блок. */
+  select?: string;
+  selectAll?: boolean;
+  /** Вырезать блоки. */
+  exclude?: string[] | string;
+  /** Убрать script, style, noscript и комментарии. */
+  strip?: boolean;
+  /** Добавить текст страницы отдельным полем. */
+  text?: boolean;
+  /**
+   * Разбор страницы в поля, описанные словами: имя поля → что в нём должно
+   * оказаться. Результат приходит в `parsed`, причина неудачи — в
+   * `fetch_metadata.extract_note`. Три кредита, и они не списываются, если
+   * разбор не состоялся.
+   */
+  extract?: ExtractSpec;
+}
+
+/** Что вынуть со страницы: имя поля → описание словами. */
+export type ExtractSpec = Record<string, string>;
+
 export interface ClientOptions {
   apiKey: string;
   baseUrl?: string;
@@ -56,7 +98,165 @@ export declare class SearchResult {
   readonly totalResults: number | null;
 }
 
-export declare class ParReqError extends Error {
+export interface FetchMetadata {
+  id: string;
+  status: string;
+  requested_url: string;
+  final_url: string;
+  http_status: number;
+  title: string;
+  fetch_ms: number;
+  total_ms: number;
+  html_size: number;
+  page_size: number;
+  matched: number;
+  note: string;
+  credits: number;
+  credits_breakdown: Record<string, number>;
+  credits_left: number;
+  created_at: number;
+  /** Почему не вышел разбор по `extract`. Пусто, если его не заказывали. */
+  extract_note?: string;
+}
+
+/** Один скрипт или один файл стилей. */
+export interface Asset {
+  url: string;
+  inline: boolean;
+  bytes: number;
+  content: string;
+}
+
+/** Один сетевой запрос страницы. */
+export interface NetworkEntry {
+  id: string;
+  url: string;
+  method: string;
+  type: string;
+  status: number;
+  mime: string;
+  bytes: number;
+  started_ms: number;
+  finished_ms: number | null;
+  error: string;
+  redirected_from: string | null;
+}
+
+export declare class FetchResult {
+  raw: Record<string, any>;
+  readonly metadata: FetchMetadata;
+  readonly parameters: Record<string, any>;
+  readonly id: string;
+  readonly html: string;
+  readonly text: string | null;
+  /** Разбор по `extract`; null и когда не заказывали, и когда не удался. */
+  readonly parsed: Record<string, any> | null;
+  readonly title: string;
+  readonly finalUrl: string;
+  readonly httpStatus: number;
+  readonly credits: number;
+  readonly creditsLeft: number;
+  readonly js: Asset[] | null;
+  readonly css: Asset[] | null;
+  readonly network: NetworkEntry[] | null;
+  readonly screenshotUrl: string | null;
+  readonly iframeUrl: string | null;
+}
+
+/** Состояние задания обхода. Последние четыре — завершённые. */
+export type CrawlStatus = "queued" | "running" | "done" | "partial" | "failed" | "canceled";
+
+export interface CrawlOptions {
+  /** Адрес, с которого начинается обход. */
+  url: string;
+  /** Сколько страниц обойти, 1..200. Обязателен: это и есть потолок расхода. */
+  pages: number;
+  /** Селектор ссылок на карточки: CSS или XPath. */
+  follow?: string;
+  /** Селектор кнопки следующей страницы. */
+  next?: string;
+  /** Насколько глубоко заходить по ссылкам, 0..5 (по умолчанию 1). */
+  depth?: number;
+  /** Не выпускать обход на чужие домены (по умолчанию true). */
+  sameSite?: boolean;
+  /** Регулярные выражения: адрес берётся, только если подходит хотя бы одному. */
+  allow?: string[] | string;
+  /** Регулярные выражения: подходящий адрес не берётся. */
+  deny?: string[] | string;
+  /** Что вынуть с каждой страницы. */
+  extract?: ExtractSpec;
+  /** Обычные параметры Fetch для каждой страницы, именами API. */
+  fetch?: Record<string, any>;
+  /** Не ждать результат: ответ придёт одним `crawl_metadata`. */
+  async?: boolean;
+}
+
+/** Правило обхода плюс то, как его ждать. Вместо него можно дать id задания. */
+export interface CrawlWaitOptions extends Omit<CrawlOptions, "async"> {
+  /** Как часто спрашивать состояние, мс (по умолчанию 3000). */
+  pollMs?: number;
+  /** Сколько всего ждать, мс (по умолчанию 1800000). */
+  timeoutMs?: number;
+  /** По сколько страниц забирать результат (по умолчанию 50). */
+  pageSize?: number;
+}
+
+export interface CrawlMetadata {
+  id: string;
+  status: CrawlStatus;
+  code: string;
+  note: string;
+  pages_planned: number;
+  pages_done: number;
+  pages_failed: number;
+  credits: number;
+  credits_max: number;
+  created_at: number;
+  started_at: number | null;
+  finished_at: number | null;
+  solution: string;
+}
+
+/** Одна страница обхода — в той же форме, что ответ Fetch. */
+export interface CrawlPage {
+  fetch_metadata: {
+    n: number;
+    status: string;
+    code: string;
+    requested_url: string;
+    final_url: string;
+    http_status: number;
+    title: string;
+    depth: number;
+    fetch_ms: number;
+    credits: number;
+    extract_note: string;
+  };
+  parsed: Record<string, any> | null;
+}
+
+export declare class CrawlResult {
+  raw: Record<string, any>;
+  readonly metadata: CrawlMetadata;
+  readonly parameters: Record<string, any>;
+  readonly id: string;
+  readonly status: CrawlStatus | "";
+  /** Дошло ли задание до конца — любого, включая неудачный. */
+  readonly finished: boolean;
+  readonly note: string;
+  readonly pages: CrawlPage[];
+  /** Только удавшийся разбор, без страниц, где его нет. */
+  readonly parsed: Record<string, any>[];
+  readonly pagesPlanned: number;
+  readonly pagesDone: number;
+  readonly pagesFailed: number;
+  readonly credits: number;
+  readonly creditsMax: number;
+  /** Смещение следующего среза или null, если это был последний. */
+  readonly nextOffset: number | null;
+}
+
+export declare class ParreqError extends Error {
   status: number;
   code: string;
   detail: string;
@@ -65,22 +265,49 @@ export declare class ParReqError extends Error {
   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 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 {}
+/** 403 feature_not_enabled — надстройка Fetch не подключена ключу. */
+export declare class FeatureNotEnabled extends ParreqError {}
+/** 402 — кредитов на ключе не хватает на этот запрос. */
+export declare class OutOfCredits extends ParreqError {}
+/** `crawlWait` перестал ждать, а задание продолжается: id в `details.job_id`. */
+export declare class CrawlTimeout extends ParreqError {}
 
-export declare class ParReq {
+export declare class Parreq {
   constructor(options: ClientOptions | string);
   search(options: SearchOptions): Promise<SearchResult>;
   google(options: EngineOptions): Promise<SearchResult>;
   yandex(options: EngineOptions): Promise<SearchResult>;
+  fetch(options: FetchOptions): Promise<FetchResult>;
+  crawl(options: CrawlOptions): Promise<CrawlResult>;
+  crawlStatus(jobId: string, options?: { offset?: number; limit?: number }): Promise<CrawlResult>;
+  crawlPages(jobId: string, options?: { offset?: number; limit?: number }): Promise<CrawlResult>;
+  crawlCancel(jobId: string): Promise<CrawlResult>;
+  crawlJobs(options?: { limit?: number }): Promise<CrawlMetadata[]>;
+  /**
+   * Ждёт задание и возвращает все страницы сразу: правилом — поставит своё,
+   * строкой — дождётся уже поставленного.
+   */
+  crawlWait(options: CrawlWaitOptions | string): Promise<CrawlResult>;
+  screenshot(fetchId: string): Promise<Uint8Array>;
+  iframeHtml(fetchId: string): Promise<string>;
+  requestInfo(fetchId: string): Promise<Record<string, any>>;
   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;
+export declare const DEFAULT_CRAWL_POLL_MS: number;
+export declare const DEFAULT_CRAWL_TIMEOUT_MS: number;
+/** Состояния, после которых задание больше не меняется. */
+export declare const CRAWL_FINAL: Set<string>;
+export default Parreq;
+
+/** Имена из 1.0.0, оставлены псевдонимами. */
+export { Parreq as ParReq, ParreqError as ParReqError };

package/index.js

@@ -1,24 +1,37 @@
 /**
- * ParReq — клиент поисковой выдачи Google и Яндекса.
+ * Parreq — клиент поисковой выдачи Google и Яндекса.
  *
  * Зависимостей нет: используется встроенный fetch, поэтому нужен Node 18+.
  * Тянуть axios ради одного запроса значит навязывать чужому проекту лишнее.
  */
 
-export const DEFAULT_BASE_URL = "https://req.akuraq.dev";
+export const DEFAULT_BASE_URL = "https://api.parreq.com";
 // Запрос идёт в настоящий браузер: 3–10 секунд на прогретом профиле и до двух
 // минут, если пришлось решать капчу. Таймаут меньше рвёт нормальные запросы.
 export const DEFAULT_TIMEOUT_MS = 180_000;
 // Коды, которые лечатся повтором. Остальные повторять бессмысленно: неверный
 // параметр и отозванный ключ от этого не исправятся.
 const RETRIABLE = new Set([429, 502, 503, 504]);
-const USER_AGENT = "parreq-node/1.0";
+const USER_AGENT = "parreq-node/1.4";
+// Обход живёт дольше HTTP-запроса, поэтому у него свои умолчания ожидания.
+// Три секунды между опросами — чтобы задание на десяток страниц не пришлось
+// ждать лишнюю минуту, и чтобы задание на две сотни не превратилось в тысячу
+// лишних запросов.
+export const DEFAULT_CRAWL_POLL_MS = 3_000;
+// Полчаса. Обход на двести страниц столько и идёт; истёкшее ожидание не
+// отменяет задание — оно доходит на сервере, и его забирают по идентификатору.
+export const DEFAULT_CRAWL_TIMEOUT_MS = 1_800_000;
+// Сколько страниц забираем за один заход, когда собираем результат целиком.
+// Потолок ручки — 200, но полсотни страниц с разбором это уже мегабайты.
+const CRAWL_PAGE_SIZE = 50;
+/** Состояния, после которых задание больше не меняется. */
+export const CRAWL_FINAL = new Set(["done", "partial", "failed", "canceled"]);
 
 /** Ошибка API. Разбирайте `code`, а не текст: текст переписывается. */
-export class ParReqError extends Error {
+export class ParreqError extends Error {
   constructor(status, code, message, { requestId = "", retryAfter = null, details = {} } = {}) {
     super(`${code}: ${message}`);
-    this.name = "ParReqError";
+    this.name = "ParreqError";
     this.status = status;
     this.code = code;
     this.detail = message;
@@ -33,12 +46,24 @@ export class ParReqError extends Error {
   }
 }
 
-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 {}
+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 {}
+/** 403 feature_not_enabled — надстройка Fetch не подключена ключу. */
+export class FeatureNotEnabled extends ParreqError {}
+/** 402 — кредитов на ключе не хватает на этот запрос. */
+export class OutOfCredits extends ParreqError {}
+/**
+ * `crawlWait` перестал ждать, а задание ещё идёт.
+ *
+ * Не отказ сервиса, а решение клиента: обход продолжается на сервере и деньги
+ * за него спишутся. Идентификатор лежит в `details.job_id` — по нему задание
+ * забирают через `crawlStatus` или останавливают через `crawlCancel`.
+ */
+export class CrawlTimeout extends ParreqError {}
 
 const BY_CODE = {
   invalid_request: BadRequest,
@@ -51,6 +76,8 @@ const BY_CODE = {
   concurrency_limit: RateLimited,
   no_workers_available: NoWorkers,
   search_blocked: SearchBlocked,
+  feature_not_enabled: FeatureNotEnabled,
+  out_of_credits: OutOfCredits,
 };
 
 function errorFrom(status, body, retryAfter) {
@@ -92,7 +119,76 @@ export class SearchResult {
   get totalResults() { return this.raw.total_results ?? null; }
 }
 
-export class ParReq {
+/**
+ * Ответ Fetch. Надстройки приходят только заказанные: `js`, `css` и `network`
+ * равны null, если их не просили, и пустому массиву, если просили, а на
+ * странице их нет. Разница важна — иначе «не заказывал» неотличимо от «нет».
+ */
+export class FetchResult {
+  constructor(raw) {
+    this.raw = raw;
+  }
+  get metadata() { return this.raw.fetch_metadata || {}; }
+  get parameters() { return this.raw.fetch_parameters || {}; }
+  get id() { return this.metadata.id || ""; }
+  get html() { return this.raw.html || ""; }
+  get text() { return this.raw.text ?? null; }
+  /**
+   * Разбор страницы в поля, заказанный через `extract`. null и когда разбор не
+   * заказывали, и когда он не удался: отличить одно от другого можно по
+   * `metadata.extract_note` — у неудачи там причина, у незаказанного пусто.
+   */
+  get parsed() { return this.raw.parsed ?? null; }
+  get title() { return this.metadata.title || ""; }
+  get finalUrl() { return this.metadata.final_url || ""; }
+  get httpStatus() { return this.metadata.http_status || 0; }
+  get credits() { return this.metadata.credits || 0; }
+  get creditsLeft() { return this.metadata.credits_left || 0; }
+  get js() { return this.raw.js ?? null; }
+  get css() { return this.raw.css ?? null; }
+  get network() { return this.raw.network ?? null; }
+  get screenshotUrl() { return this.raw.screenshot_url ?? null; }
+  get iframeUrl() { return this.raw.iframe_url ?? null; }
+}
+
+/**
+ * Ответ обхода: состояние задания и срез его страниц.
+ *
+ * Одна форма на все ручки обхода — постановку, состояние, остановку, — потому
+ * что задание одно и то же в разные моменты жизни. У свежепоставленного
+ * большого задания `pages` пуст: сервис ответил 202 и одним `crawl_metadata`,
+ * страницы появятся по мере обхода.
+ */
+export class CrawlResult {
+  constructor(raw) {
+    this.raw = raw;
+  }
+  get metadata() { return this.raw.crawl_metadata || {}; }
+  get parameters() { return this.raw.crawl_parameters || {}; }
+  get id() { return this.metadata.id || ""; }
+  get status() { return this.metadata.status || ""; }
+  /** Дошло ли задание до конца — любого, включая неудачный. */
+  get finished() { return CRAWL_FINAL.has(this.status); }
+  get note() { return this.metadata.note || ""; }
+  /** Страницы этого среза: у каждой `fetch_metadata` и `parsed`. */
+  get pages() { return this.raw.pages || []; }
+  /**
+   * Только удавшийся разбор, без страниц, где его нет. Сахар для главного
+   * случая: когда обход заказывали ради `extract`, нужен список товаров, а не
+   * список страниц, часть которых пустая.
+   */
+  get parsed() { return this.pages.filter((p) => p.parsed).map((p) => p.parsed); }
+  get pagesPlanned() { return this.metadata.pages_planned || 0; }
+  get pagesDone() { return this.metadata.pages_done || 0; }
+  get pagesFailed() { return this.metadata.pages_failed || 0; }
+  get credits() { return this.metadata.credits || 0; }
+  /** Потолок расхода: столько задание займёт, если пройдёт целиком. */
+  get creditsMax() { return this.metadata.credits_max || 0; }
+  /** Смещение следующего среза или null, если это был последний. */
+  get nextOffset() { return this.raw.next_offset ?? null; }
+}
+
+export class Parreq {
   /**
    * @param {object|string} options ключ строкой либо объект настроек
    * @param {string} options.apiKey ключ вида `pr_…`
@@ -102,7 +198,7 @@ export class ParReq {
    */
   constructor(options) {
     const opts = typeof options === "string" ? { apiKey: options } : options || {};
-    if (!opts.apiKey) throw new Error("нужен ключ ParReq");
+    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;
@@ -131,22 +227,223 @@ export class ParReq {
   /** Сахар: `client.yandex({ q: "кофемашина", gl: "by", hl: "ru" })`. */
   async yandex(options) { return this.search({ ...options, engine: "yandex" }); }
 
+  /**
+   * Страница по адресу глазами браузера.
+   *
+   * Бесплатно приходит разметка. Платные надстройки — через `include`:
+   * ["js", "css", "network", "screenshot", "iframe"] либо "all".
+   * `headless: false` — сбор браузером с окном, тоже платно.
+   *
+   * Разметку можно подрезать: `select` отдаёт один блок, `startAt` отрезает
+   * всё до блока, `exclude` вырезает лишнее, `strip` убирает скрипты, стили и
+   * комментарии. Селектор — CSS, XPath или просто название блока.
+   *
+   * `extract` — разбор страницы в поля, описанные словами:
+   * `{ name: "Название товара", price: "Цена числом, без валюты" }`. Результат
+   * приходит в `parsed`, причина неудачи — в `metadata.extract_note`. Стоит три
+   * кредита, и они не списываются, если разбор не состоялся.
+   */
+  async fetch({ url, device = "desktop", gl = "us", hl = "en", include,
+                headless = true, waitMs, waitFor, networkMs, scroll = false,
+                startAt, select, selectAll = false, exclude, strip = false,
+                text = false, extract } = {}) {
+    if (!url) throw new Error("нужен адрес url");
+    const body = { url, device, gl, hl, headless, scroll, select_all: selectAll, strip, text };
+    if (include) body.include = Array.isArray(include) ? include.join(",") : include;
+    if (waitMs != null) body.wait_ms = waitMs;
+    if (waitFor) body.wait_for = waitFor;
+    if (networkMs != null) body.network_ms = networkMs;
+    if (startAt) body.start_at = startAt;
+    if (select) body.select = select;
+    if (exclude) body.exclude = Array.isArray(exclude) ? exclude.join(",") : exclude;
+    if (extract) body.extract = { ...extract };
+    return new FetchResult(await this.#request("POST", "/v1/fetch", null, body));
+  }
+
+  /**
+   * Скачать скриншот выполненного запроса как Uint8Array.
+   *
+   * Отдельным вызовом, а не полем ответа: картинка весит сотни килобайт, и
+   * загонять её в json значит утроить размер и заставить платить за трафик
+   * даже тех, кому нужна была только ссылка.
+   */
+  async screenshot(fetchId) {
+    return this.#binary(`/v1/fetch/${fetchId}/screenshot`);
+  }
+
+  /** Копия страницы, пригодная для вставки в iframe, строкой. */
+  async iframeHtml(fetchId) {
+    const bytes = await this.#binary(`/v1/fetch/${fetchId}/iframe`);
+    return new TextDecoder().decode(bytes);
+  }
+
+  /** Что известно о выполненном запросе: статус, расход, артефакты. */
+  async requestInfo(fetchId) { return this.#request("GET", `/v1/fetch/${fetchId}`); }
+
+  /**
+   * Поставить обход: пройти страницы по правилу и разобрать их.
+   *
+   * Идти дальше можно двумя способами, и хотя бы один обязателен: `follow` —
+   * селектор ссылок на карточки, `next` — селектор кнопки следующей страницы.
+   * Их можно сочетать: `next` листает список, `follow` заходит в каждую
+   * карточку. `depth` ограничивает, насколько глубоко заходить, `sameSite` не
+   * выпускает обход на чужие домены, `allow` и `deny` — списки регулярных
+   * выражений по адресу.
+   *
+   * `fetch` — обычные параметры Fetch для каждой страницы одним объектом:
+   * `{ device: "mobile", wait_for: ".price", strip: true }`.
+   *
+   * Маленький обход — до десяти страниц и без `async` — возвращается целиком:
+   * сервис дожидается его сам. Всё, что больше, приходит одним `crawl_metadata`
+   * со статусом `queued`, а страницы забираются потом через `crawlStatus` и
+   * `crawlPages`. Проще всего не разбирать этот случай руками, а взять
+   * `crawlWait`.
+   */
+  async crawl({ url, pages, follow, next, depth = 1, sameSite = true, allow, deny,
+                extract, fetch: fetchOptions, async: background = false } = {}) {
+    if (!url) throw new Error("нужен адрес url");
+    if (!pages) throw new Error("нужен pages: сколько страниц обходим");
+    if (!follow && !next) {
+      throw new Error("нужен follow или next: без них обходу некуда идти");
+    }
+    const body = { url, pages, depth, same_site: sameSite };
+    if (follow) body.follow = follow;
+    if (next) body.next = next;
+    if (allow) body.allow = Array.isArray(allow) ? allow : [allow];
+    if (deny) body.deny = Array.isArray(deny) ? deny : [deny];
+    if (extract) body.extract = { ...extract };
+    if (fetchOptions) body.fetch = { ...fetchOptions };
+    if (background) body.async = true;
+    return new CrawlResult(await this.#request("POST", "/v1/crawl", null, body));
+  }
+
+  /** Состояние задания и срез его страниц с `offset`. */
+  async crawlStatus(jobId, { offset = 0, limit = 50 } = {}) {
+    return new CrawlResult(await this.#request("GET", `/v1/crawl/${jobId}`, { offset, limit }));
+  }
+
+  /**
+   * Только страницы задания, без его состояния.
+   *
+   * Тем же типом, что и `crawlStatus`: у ответа нет `crawl_metadata`, зато есть
+   * `pages` и `nextOffset` — а разбирать их полезно одним кодом.
+   */
+  async crawlPages(jobId, { offset = 0, limit = 50 } = {}) {
+    return new CrawlResult(
+      await this.#request("GET", `/v1/crawl/${jobId}/pages`, { offset, limit }));
+  }
+
+  /** Остановить обход. Пройденные страницы остаются и остаются платными. */
+  async crawlCancel(jobId) {
+    return new CrawlResult(await this.#request("POST", `/v1/crawl/${jobId}/cancel`));
+  }
+
+  /** Свои задания обхода, свежие сверху. */
+  /**
+   * Свои задания обхода, свежие сверху.
+   *
+   * Отдаём массив, а не конверт `{ jobs: [...] }`, которым отвечает ручка: по
+   * нему хочется пройтись циклом, а не разворачивать его на каждом вызове.
+   */
+  async crawlJobs({ limit = 20 } = {}) {
+    const got = await this.#request("GET", "/v1/crawl", { limit });
+    return (got && got.jobs) || [];
+  }
+
+  /**
+   * Дождаться обхода целиком. Один вызов вместо цикла.
+   *
+   * Принимает и правило, и уже поставленное задание — по тому, что дали:
+   *
+   *     await client.crawlWait({ url, pages: 30, next: "a.next", follow: "a.card" });
+   *     await client.crawlWait(job.id);   // то же для чужого задания
+   *
+   * Разбираемся по типу: строка — это идентификатор уже поставленного задания,
+   * объект — правило, которое надо поставить. Два имени для одного и того же
+   * ожидания были бы хуже: у человека всё равно один вопрос — «разбуди меня,
+   * когда обход закончится».
+   *
+   * Своё задание ставим в фоне намеренно, даже когда страниц мало: держать
+   * соединение открытым полчаса нечестно по отношению к сети между вами и
+   * сервисом — прокси и балансировщики рвут такие соединения без объяснений.
+   * Поэтому HTTP остаётся коротким, а ожидание — здесь: раз в `pollMs` клиент
+   * спрашивает состояние, а по завершении забирает все страницы срезами по
+   * `pageSize`.
+   *
+   * Остальные параметры — те же, что у `crawl`.
+   *
+   * Если за `timeoutMs` задание не закончилось, бросается `CrawlTimeout`. Обход
+   * при этом продолжается: остановить его — это `crawlCancel`, забрать позже —
+   * `crawlStatus` по `details.job_id`.
+   */
+  async crawlWait(options) {
+    const isJobId = typeof options === "string";
+    const { pollMs = DEFAULT_CRAWL_POLL_MS, timeoutMs = DEFAULT_CRAWL_TIMEOUT_MS,
+            pageSize = CRAWL_PAGE_SIZE, ...rule } = isJobId ? {} : options || {};
+    const jobId = isJobId ? options : (await this.crawl({ ...rule, async: true })).id;
+    const deadline = Date.now() + timeoutMs;
+
+    // Опрашиваем с limit=1: пока задание идёт, страницы нужны не нам, а только
+    // его состояние. Тянуть на каждом опросе полсотни страниц — это тот же
+    // результат, переданный по сети столько раз, сколько было опросов.
+    let state;
+    for (;;) {
+      state = await this.crawlStatus(jobId, { limit: 1 });
+      if (state.finished) break;
+      if (Date.now() >= deadline) {
+        throw new CrawlTimeout(0, "crawl_timeout",
+          `задание ${jobId} не уложилось в ${Math.round(timeoutMs / 1000)} с ` +
+          `(пройдено ${state.pagesDone} из ${state.pagesPlanned}); ` +
+          "обход продолжается, заберите его позже",
+          { details: { job_id: jobId, status: state.status, pages_done: state.pagesDone } });
+      }
+      await sleep(pollMs);
+    }
+
+    // Страницы забираем отдельно и постранично: у обхода на две сотни страниц
+    // с разбором один ответ целиком весит десятки мегабайт, и ручка его не
+    // отдаст.
+    const all = [];
+    let offset = 0;
+    for (;;) {
+      const chunk = await this.crawlPages(jobId, { offset, limit: pageSize });
+      all.push(...chunk.pages);
+      const next = chunk.nextOffset;
+      // Страховка от бесконечного круга: сервис отдаёт null на последнем срезе,
+      // но пустой срез без null означал бы вечный цикл.
+      if (next == null || chunk.pages.length === 0 || next <= offset) break;
+      offset = next;
+    }
+
+    return new CrawlResult({ ...state.raw, pages: all, next_offset: null });
+  }
+
   /** Остаток лимитов по своему ключу. */
   async usage() { return this.#request("GET", "/v1/usage"); }
 
   /** Справочники: движки, устройства, страны, языки, секции. */
   async meta() { return this.#request("GET", "/v1/meta"); }
 
-  async #request(method, path, params) {
+  async #request(method, path, params, body) {
+    const raw = await this.#retrying(method, path, params, body);
+    return raw.length ? JSON.parse(new TextDecoder().decode(raw)) : {};
+  }
+
+  /** Артефакт как есть: скриншот — это jpeg, а не json. */
+  async #binary(path) {
+    return this.#retrying("GET", path, null, null);
+  }
+
+  async #retrying(method, path, params, body) {
     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);
+        return await this.#once(method, url, body);
       } catch (err) {
-        if (!(err instanceof ParReqError) || !err.retriable || attempt === this.retries) throw err;
+        if (!(err instanceof ParreqError) || !err.retriable || attempt === this.retries) throw err;
         last = err;
         // ждём столько, сколько попросил сервер: у суточной квоты это время до
         // полуночи, и «подождать 5 секунд» там ничего не изменит
@@ -156,19 +453,22 @@ export class ParReq {
     throw last;
   }
 
-  async #once(method, url) {
+  async #once(method, url, body) {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    const headers = {
+      Authorization: `Bearer ${this.apiKey}`,
+      Accept: "application/json",
+      "User-Agent": USER_AGENT,
+    };
+    if (body != null) headers["Content-Type"] = "application/json";
     let resp;
     try {
       resp = await fetch(url, {
         method,
         signal: controller.signal,
-        headers: {
-          Authorization: `Bearer ${this.apiKey}`,
-          Accept: "application/json",
-          "User-Agent": USER_AGENT,
-        },
+        body: body == null ? undefined : JSON.stringify(body),
+        headers,
       });
     } catch (err) {
       const reason = err.name === "AbortError" ? `превышен таймаут ${this.timeoutMs} мс` : String(err);
@@ -177,19 +477,27 @@ export class ParReq {
       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) } };
-    }
+    // Читаем байтами: этой же дорогой ходят скриншоты, а jpeg через строку не
+    // проходит без потерь. Разбор в json остаётся выше, где он уместен.
+    const bytes = new Uint8Array(await resp.arrayBuffer());
     if (!resp.ok) {
+      const text = new TextDecoder().decode(bytes);
+      let failure;
+      try {
+        failure = text ? JSON.parse(text) : {};
+      } catch {
+        failure = { error: { code: `http_${resp.status}`, message: text.slice(0, 200) } };
+      }
       const ra = resp.headers.get("retry-after");
-      throw errorFrom(resp.status, body, ra ? Number(ra) : null);
+      throw errorFrom(resp.status, failure, ra ? Number(ra) : null);
     }
-    return body;
+    return bytes;
   }
 }
 
-export default ParReq;
+export default Parreq;
+
+// --- совместимость с 1.0.0 -------------------------------------------------
+// Тогда класс назывался ParReq — с заглавной R. Написание бренда изменилось на
+// Parreq, но ломать чужой импорт из-за этого нельзя.
+export { Parreq as ParReq, ParreqError as ParReqError };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "parreq-client",
-  "version": "1.0.0",
-  "description": "Клиент ParReq: поисковая выдача Google и Яндекса в JSON",
+  "version": "1.4.0",
+  "description": "Клиент Parreq: поисковая выдача Google и Яндекса и загрузка страниц браузером",
   "type": "module",
   "main": "./index.js",
   "types": "./index.d.ts",
@@ -25,10 +25,12 @@
     "google",
     "yandex",
     "search-api",
-    "scraping"
+    "scraping",
+    "headless-browser",
+    "screenshot"
   ],
   "license": "MIT",
-  "homepage": "https://req.akuraq.dev",
+  "homepage": "https://parreq.com",
   "scripts": {
     "smoke": "node smoke.mjs"
   }