@itd-api/captcha 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,380 @@
+//#region src/driver.d.ts
+/**
+ * Минимальные структурные типы драйвера браузера.
+ *
+ * Ни один драйвер не импортируется даже как тип: пакет собирается и проверяется без них,
+ * а подойдёт любой совместимый по API — `patchright`, `playwright`, `playwright-core`,
+ * Camoufox. Форма взята у Playwright, потому что её повторяют остальные. Описаны только
+ * те методы, которыми пользуется солвер.
+ */
+/** Перехваченный запрос. Нужен, чтобы отдать свою страницу вместо настоящей. */
+interface Route {
+  fulfill(options: {
+    status?: number;
+    contentType?: string;
+    body?: string;
+  }): Promise<void>;
+}
+/** Прямоугольник элемента в координатах страницы. */
+interface BoundingBox {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+interface ElementHandle {
+  boundingBox(): Promise<BoundingBox | null>;
+}
+/** Мышь уровня страницы: события идут через CDP, а не через DOM. */
+interface Mouse {
+  move(x: number, y: number, options?: {
+    steps?: number;
+  }): Promise<void>;
+  click(x: number, y: number, options?: {
+    delay?: number;
+  }): Promise<void>;
+}
+interface Page {
+  route(url: string, handler: (route: Route) => void | Promise<void>): Promise<void>;
+  goto(url: string, options?: {
+    waitUntil?: 'domcontentloaded' | 'load';
+  }): Promise<unknown>;
+  evaluate<R>(fn: () => R): Promise<R>;
+  waitForSelector(selector: string, options?: {
+    timeout?: number;
+    state?: 'attached' | 'visible';
+  }): Promise<unknown>;
+  $(selector: string): Promise<ElementHandle | null>;
+  readonly mouse: Mouse;
+  close(): Promise<void>;
+}
+interface BrowserContext {
+  newPage(): Promise<Page>;
+  close(): Promise<void>;
+}
+/**
+ * Настройки контекста. Совпадают по форме с `browser.newContext` в Playwright.
+ *
+ * Кроме перечисленных полей принимается что угодно ещё: драйверы вроде Camoufox понимают
+ * свои настройки, и перечислять их здесь пакет не берётся.
+ */
+interface NewContextOptions {
+  locale?: string;
+  viewport?: {
+    width: number;
+    height: number;
+  } | null;
+  userAgent?: string;
+  [option: string]: unknown;
+}
+interface Browser {
+  newContext(options?: NewContextOptions): Promise<BrowserContext>;
+  /** Версия браузера, например `149.0.7827.55`. Есть не у всякого драйвера. */
+  version?(): string;
+  close(): Promise<void>;
+}
+//#endregion
+//#region src/types.d.ts
+/**
+ * Открытый строковый enum.
+ *
+ * Даёт автодополнение известных значений, но не ломается, если появится новое.
+ */
+type Loose<T extends string> = T | (string & {});
+/** Провайдер капчи — теми же именами, какими его называет сервер итд.com. */
+declare const CaptchaType: Readonly<{
+  /** Собственная капча ИТД: карточка «Я не робот» в iframe с `captcha.итд.com`. */
+  readonly Itd: "itd";
+  /** Cloudflare Turnstile. */
+  readonly Cloudflare: "cloudflare";
+}>;
+type CaptchaType = Loose<(typeof CaptchaType)[keyof typeof CaptchaType]>;
+/** Оформление виджета. */
+type Theme = 'auto' | 'light' | 'dark';
+/** Результат виджета, снятый со страницы через `page.evaluate`. */
+interface WidgetState {
+  token: string | null;
+  error: string | null;
+}
+//#endregion
+//#region src/errors.d.ts
+/** Почему не удалось получить токен. */
+declare const CaptchaFailure: Readonly<{
+  /** Драйвер браузера не установлен. */
+  readonly DriverMissing: "driver-missing";
+  /** Браузер не запустился: нет исполняемого файла, нет дисплея, отказ песочницы. */
+  readonly LaunchFailed: "launch-failed";
+  /** Браузер или страница закрылись, пока решался виджет. */
+  readonly BrowserClosed: "browser-closed";
+  /** Виджет не отдал токен за отведённое время. */
+  readonly Timeout: "timeout";
+  /** Сам виджет сообщил об ошибке — код лежит в `widgetCode`. */
+  readonly WidgetError: "widget-error";
+}>;
+type CaptchaFailure = (typeof CaptchaFailure)[keyof typeof CaptchaFailure];
+/**
+ * Ошибка получения токена капчи.
+ *
+ * Причина в {@link CaptchaError.reason} определяет, что с ошибкой делать: отсутствие драйвера
+ * чинится установкой, таймаут — повтором, а ошибка виджета повтором не лечится. Поле
+ * {@link CaptchaError.type} говорит, чей именно виджет решался, — оно есть не у всех ошибок
+ * (запуск браузера происходит до выбора виджета).
+ */
+declare class CaptchaError extends Error {
+  readonly reason: CaptchaFailure;
+  /** Какой провайдер решался в момент ошибки. */
+  readonly type: CaptchaType | undefined;
+  /**
+   * Код ошибки виджета, если он его сообщил.
+   *
+   * Для Cloudflare самые частые: `110200` — домен не разрешён для этого ключа, `300***`
+   * и `600***` — внутренние сбои виджета, лечатся повтором.
+   */
+  readonly widgetCode: string | undefined;
+  constructor(reason: CaptchaFailure, message: string, options?: {
+    type?: CaptchaType;
+    widgetCode?: string;
+  });
+}
+//#endregion
+//#region src/handler.d.ts
+/**
+ * Контракт одного провайдера капчи: всё, чем один виджет отличается от другого.
+ *
+ * Перехват навигации, ожидание, клик и повторы одинаковы для всех виджетов и в реализацию
+ * не входят. Свой провайдер достаточно описать этим интерфейсом и передать в `solveCaptcha`.
+ *
+ * @example
+ * ```ts
+ * const myCaptcha: CaptchaHandler = {
+ *   type: 'my-captcha',
+ *   label: 'моей капчи',
+ *   buildPage: ({ theme }) => `<!doctype html>…`,
+ *   widgetReadySelector: '#widget',
+ *   checkboxOffsetX: 30,
+ *   readState: (page) => page.evaluate(() => ({ token: null, error: null })),
+ *   isPermanentWidgetError: () => false,
+ * };
+ *
+ * const token = await solveCaptcha(myCaptcha);
+ * ```
+ */
+interface CaptchaHandler {
+  /** Имя провайдера. */
+  readonly type: CaptchaType;
+  /** Как назвать виджет в сообщении об ошибке. */
+  readonly label: string;
+  /** Собирает страницу с одним виджетом. Ключ и адрес виджета обработчик хранит сам. */
+  buildPage(input: {
+    theme: Theme;
+  }): string;
+  /** Селектор, по которому видно, что виджет отрисовался. */
+  readonly widgetReadySelector: string;
+  /** Насколько правее левого края контейнера находится чекбокс, px. */
+  readonly checkboxOffsetX: number;
+  /** Читает результат виджета со страницы. */
+  readState(page: Page): Promise<WidgetState>;
+  /** Постоянна ли ошибка виджета с таким кодом: повтор её не исправит. */
+  isPermanentWidgetError(code: string): boolean;
+}
+//#endregion
+//#region src/launch.d.ts
+/** Настройки запуска браузера. */
+interface BrowserOptions {
+  /**
+   * Запускать ли браузер без окна. По умолчанию `false`.
+   *
+   * В безоконном режиме виджет проходится заметно хуже: признаки такого режима видны
+   * странице. На сервере поднимите виртуальный дисплей (`xvfb-run -a node bot.js`).
+   */
+  headless?: boolean | undefined;
+  /**
+   * Какой драйвер брать вместо перебора `patchright` → `playwright` → `playwright-core`.
+   *
+   * Нужен, когда установлено несколько и важно, какой именно поднимется. Названный
+   * драйвер берётся один: не найден — ошибка, а не молчаливая подмена соседним.
+   */
+  driver?: string | undefined;
+  /** Путь к исполняемому файлу браузера, если он лежит не там, где его ищет драйвер. */
+  executablePath?: string | undefined;
+  /** Канал браузера, например `chrome` или `msedge`, — вместо сборки из комплекта драйвера. */
+  channel?: string | undefined;
+  /** Дополнительные аргументы командной строки — добавляются к стандартным. */
+  args?: readonly string[] | undefined;
+  /**
+   * Отключить sandbox Chromium. По умолчанию `false`.
+   *
+   * Используйте только внутри изолированного контейнера, где sandbox невозможно настроить:
+   * страница исполняет удалённый код виджета, и без изоляции браузера его компрометация
+   * получает больше доступа к процессу и системе.
+   */
+  disableSandbox?: boolean | undefined;
+  /** Прокси для браузера. */
+  proxy?: {
+    server: string;
+    username?: string;
+    password?: string;
+  } | undefined;
+  /**
+   * Свой запуск браузера. Заменяет все остальные параметры запуска.
+   *
+   * Нужен, чтобы подставить другой драйвер или подключиться к уже работающему браузеру.
+   *
+   * @example
+   * ```ts
+   * launch: async () => {
+   *   const { chromium } = await import('patchright');
+   *   return chromium.launch({ headless: false });
+   * };
+   * ```
+   */
+  launch?: (() => Promise<Browser>) | undefined;
+}
+/**
+ * Поднимает браузер по настройкам.
+ *
+ * Тем же путём, что и солверы: те же флаги, тот же порядок драйверов. Пригодится, чтобы
+ * поднять браузер один раз на несколько токенов и передать его в `browser`, — и чтобы
+ * проверять связки драйвера и сборки ровно в том виде, в каком их поднимает пакет.
+ */
+declare function launchBrowser(options: BrowserOptions): Promise<Browser>;
+//#endregion
+//#region src/options.d.ts
+/** Базовый URL сайта итд.com. Домен записан в punycode: `итд.com`. */
+declare const DEFAULT_ORIGIN = "https://xn--d1ah4a.com";
+/**
+ * Настройки получения токена, общие для любого виджета.
+ *
+ * Ключ, назначение токена и адрес виджета задаются при создании провайдера:
+ * `solveCaptcha(itdCaptcha({ action: 'register' }))`.
+ */
+interface SolveOptions extends BrowserOptions {
+  /** Сайт, чей виджет решается. По умолчанию {@link DEFAULT_ORIGIN}. */
+  origin?: string | undefined;
+  /** Оформление виджета. По умолчанию `auto`. */
+  theme?: Theme | undefined;
+  /** Сколько ждать токен, мс. По умолчанию 60000. */
+  timeout?: number | undefined;
+  /** Сколько попыток делать при неудаче. По умолчанию 2. */
+  attempts?: number | undefined;
+  /**
+   * Готовый браузер. Тогда пакет его не запускает и не закрывает.
+   *
+   * Пригодится, если браузер уже поднят для чего-то ещё.
+   */
+  browser?: Browser | undefined;
+  /**
+   * Настройки контекста. Заменяют стандартные целиком, а не дополняют их.
+   *
+   * По умолчанию `{ locale: 'ru-RU', viewport: { width: 1280, height: 800 } }`. Драйверам,
+   * которые собирают отпечаток браузера сами, навязанный `locale` мешает — им передайте `{}`.
+   */
+  contextOptions?: NewContextOptions | undefined;
+  /** Куда писать ход решения. Например `console.debug`. */
+  logger?: ((message: string) => void) | undefined;
+}
+//#endregion
+//#region src/providers/itd.d.ts
+/** Базовый адрес виджета собственной капчи ИТД. Домен в punycode: `captcha.итд.com`. */
+declare const DEFAULT_CAPTCHA_ORIGIN = "https://captcha.xn--d1ah4a.com";
+/**
+ * Публичный ключ виджета собственной капчи ИТД.
+ *
+ * Как и ключ Turnstile, он публичный и привязан к домену итд.com: виджет отдаёт его браузеру
+ * каждому посетителю.
+ */
+declare const ITD_CAPTCHA_SITE_KEY = "sk_44d64cf7bf8bc8377f5b";
+/** Настройки виджета собственной капчи ИТД. */
+interface ItdCaptchaOptions {
+  /** Публичный ключ виджета. По умолчанию {@link ITD_CAPTCHA_SITE_KEY} — ключ итд.com. */
+  sitekey?: string | undefined;
+  /**
+   * Назначение токена: `login`, `register`, `password_reset`. По умолчанию `login`.
+   *
+   * Сервер сверяет назначение с операцией, поэтому для регистрации или сброса пароля нужен
+   * токен с соответствующим `action`.
+   */
+  action?: string | undefined;
+  /** Базовый адрес виджета. По умолчанию {@link DEFAULT_CAPTCHA_ORIGIN}. */
+  captchaOrigin?: string | undefined;
+}
+/**
+ * Создаёт обработчик собственной капчи ИТД.
+ *
+ * @throws {TypeError} при некорректных настройках
+ */
+declare function itdCaptcha(options?: ItdCaptchaOptions): CaptchaHandler;
+//#endregion
+//#region src/providers/registry.d.ts
+/** Что решать: имя известного провайдера либо свой обработчик. */
+type CaptchaTarget = CaptchaType | CaptchaHandler;
+//#endregion
+//#region src/providers/turnstile.d.ts
+/**
+ * Публичный ключ виджета Cloudflare Turnstile на итд.com.
+ *
+ * Ключ публичный — виджет отдаёт его браузеру каждому посетителю — и привязан к домену
+ * итд.com, поэтому больше ни для чего не годится. Держим его прямо в пакете: это его данные,
+ * а не пользовательская настройка. Тот же ключ экспортирует `itd-api`.
+ */
+declare const TURNSTILE_SITE_KEY = "0x4AAAAAACHhxczw6fJGwPBg";
+/** Настройки виджета Cloudflare Turnstile. */
+interface TurnstileOptions {
+  /** Публичный ключ виджета. По умолчанию {@link TURNSTILE_SITE_KEY} — ключ итд.com. */
+  sitekey?: string | undefined;
+}
+/**
+ * Создаёт обработчик Cloudflare Turnstile.
+ *
+ * @throws {TypeError} при некорректных настройках
+ */
+declare function turnstile(options?: TurnstileOptions): CaptchaHandler;
+//#endregion
+//#region src/solve.d.ts
+/**
+ * Получает один токен капчи указанного типа.
+ *
+ * Поднимает браузер, решает виджет и закрывает браузер за собой.
+ *
+ * @example
+ * ```ts
+ * await solveCaptcha(CaptchaType.Itd);
+ * await solveCaptcha(itdCaptcha({ action: 'register' }), { headless: true });
+ * await solveCaptcha(myOwnHandler);
+ * ```
+ *
+ * @throws {CaptchaError} если токен получить не удалось
+ * @throws {TypeError} при некорректных настройках или незнакомом типе
+ */
+declare function solveCaptcha(target: CaptchaTarget, options?: SolveOptions): Promise<string>;
+/** Источник токена капчи для `auth.captcha` клиента `itd-api`. */
+interface CaptchaSolver {
+  /** Решает капчу названного типа и отдаёт токен. */
+  getToken(type: CaptchaType): Promise<string>;
+}
+/**
+ * Собирает источник токена для клиента `itd-api`.
+ *
+ * Токен одноразовый и живёт несколько минут, поэтому клиент спрашивает его заново перед
+ * каждым входом. Браузер поднимается на время одного вызова и сразу закрывается.
+ *
+ * @example
+ * ```ts
+ * import { ItdClient } from 'itd-api';
+ * import { FileTokenStorage } from 'itd-api/node';
+ * import { createCaptchaSolver } from '@itd-api/captcha';
+ *
+ * const itd = new ItdClient({
+ *   storage: new FileTokenStorage('./.itd-session.json'),
+ *   auth: {
+ *     email: process.env.ITD_EMAIL!,
+ *     password: process.env.ITD_PASSWORD!,
+ *     captcha: createCaptchaSolver(),
+ *   },
+ * });
+ * ```
+ */
+declare function createCaptchaSolver(options?: SolveOptions): CaptchaSolver;
+//#endregion
+export { type Browser, type BrowserContext, type BrowserOptions, CaptchaError, CaptchaFailure, type CaptchaHandler, type CaptchaSolver, type CaptchaTarget, CaptchaType, DEFAULT_CAPTCHA_ORIGIN, DEFAULT_ORIGIN, ITD_CAPTCHA_SITE_KEY, type ItdCaptchaOptions, type Loose, type NewContextOptions, type Page, type SolveOptions, TURNSTILE_SITE_KEY, type Theme, type TurnstileOptions, type WidgetState, createCaptchaSolver, itdCaptcha, launchBrowser, solveCaptcha, turnstile };
+//# sourceMappingURL=index.d.ts.map