@itd-api/captcha 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @itd-api/captcha
 
-Получает токены собственной капчи ИТД и Cloudflare Turnstile для входа через [`itd-api`](https://github.com/KiowDev/itd-api). Активного провайдера выбирает сервер.
+Получает токены собственной капчи ИТД и Cloudflare Turnstile для входа через [`itd-api`](https://github.com/KiowDev/itd-api). Сервер принимает обе: виджет выбираете вы либо он сам.
 
 [Руководство](https://kiowdev.github.io/itd-api/packages/captcha) ·
 [API из TSDoc](https://kiowdev.github.io/itd-api/api/generated/captcha/)
@@ -9,18 +9,19 @@
 
 ## Когда пакет не нужен
 
-Капча участвует только в самом входе по паролю — ни продление сессии, ни обычные запросы,
-ни событийные соединения её не требуют. Пакет незачем ставить, если:
+Капча участвует во входе по паролю, регистрации, сбросе пароля и подтверждении QR-входа —
+ни продление сессии, ни обычные запросы, ни событийные соединения её не требуют. Пакет
+незачем ставить, если:
 
 - сессия уже сохранена в `FileTokenStorage` — клиент продлевает её сам;
 - токены можно [скопировать из браузера](https://kiowdev.github.io/itd-api/authentication/#токены-из-браузера), где вы уже вошли: DevTools отдают и access token, и cookie `refresh_token`;
 - access token выдаёт серверное приложение или хранилище секретов — тогда подойдёт `auth: { getToken }`;
-- токен капчи приходит из своего источника — `auth.captcha.getToken` принимает любую функцию.
+- токен капчи приходит из своего источника — опция клиента `captcha` принимает любую функцию.
 
 ## Установка
 
 ```sh
-npm i @itd-api/captcha patchright
+npm i @itd-api/captcha patchright@1.61.1
 npx patchright install chromium
 ```
 
@@ -38,68 +39,42 @@ 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(),
-  },
+  auth: { email: process.env.ITD_EMAIL!, password: process.env.ITD_PASSWORD! },
+  captcha: createCaptchaSolver(),
 });
 ```
 
-`createCaptchaSolver()` отдаёт `getToken(type)`. Перед каждым входом клиент читает активного
-провайдера и просит решить именно его виджет, поэтому переключение провайдера сервером
-переживается без правок кода. Передаётся функция, а не готовый токен: токен одноразовый и
-живёт несколько минут. Браузер поднимается на время одного вызова и сразу закрывается.
+Клиент спрашивает токен каждый раз, когда сервер требует капчу; браузер поднимается на
+время одного вызова и сразу закрывается. Тот же источник, заданный контейнеру
+`ItdAccounts`, достаётся каждому аккаунту.
 
-Решить капчу без клиента — тип называется явно:
+### Какую капчу проходить
 
-```ts
-import { solveCaptcha, CaptchaType } from '@itd-api/captcha';
-
-const token = await solveCaptcha(CaptchaType.Itd);
-```
+Сервер принимает обе. Без настройки источник следует за сервером: клиент спрашивает
+активного провайдера и просит пройти именно его виджет, так что переключение провайдера
+переживается без правок кода.
 
-Провайдера с другими настройками собирает его фабрика:
+Нужен конкретный виджет — назовите его, и лишнего запроса к серверу не будет:
 
 ```ts
-import { solveCaptcha, itdCaptcha, turnstile } from '@itd-api/captcha';
+import { createCaptchaSolver, CaptchaType } from '@itd-api/captcha';
 
-const forRegistration = await solveCaptcha(itdCaptcha({ action: 'register' }));
-const withOwnKey = await solveCaptcha(turnstile({ sitekey: '0x…' }), { headless: true });
+createCaptchaSolver({ type: CaptchaType.Cloudflare }); // всегда Turnstile
+createCaptchaSolver({ type: CaptchaType.Itd }); // всегда капча ИТД
 ```
 
-## Свой провайдер
+Незнакомый тип отвергается при создании, а не в момент входа.
+
+Имя поля, в котором сервер ждёт токен, клиент при закреплённом типе берёт из своей таблицы.
+Если сервер его переименовал, назовите поле сами: `createCaptchaSolver({ type, field: 'c7f2' })`.
 
-Новый виджет добавляется реализацией `CaptchaHandler` — менять пакет не нужно. Перехват
-навигации, ожидание, клик по чекбоксу и повторы одинаковы для всех виджетов и уже сделаны;
-описать нужно только то, чем виджет отличается:
+### Один токен без клиента
 
 ```ts
-import { solveCaptcha, type CaptchaHandler } from '@itd-api/captcha';
-
-const myCaptcha: CaptchaHandler = {
-  type: 'my-captcha',
-  label: 'моей капчи',
-  // Страница отдаётся вместо настоящей по адресу из `origin`, поэтому виджет видит верный домен.
-  buildPage: ({ theme }) => `<!doctype html>…<div id="widget" data-theme="${theme}"></div>…`,
-  // По этому селектору видно, что виджет отрисовался.
-  widgetReadySelector: '#widget',
-  // Насколько правее левого края контейнера чекбокс: клик идёт по координатам.
-  checkboxOffsetX: 30,
-  readState: (page) =>
-    page.evaluate(() => {
-      const field = document.querySelector('#my-token') as { value?: string } | null;
-      return { token: field?.value || null, error: null };
-    }),
-  // Повтор не поможет — например, ключ не разрешён для домена.
-  isPermanentWidgetError: (code) => code === 'domain-mismatch',
-};
-
-const token = await solveCaptcha(myCaptcha);
-```
+import { solveCaptcha, CaptchaType } from '@itd-api/captcha';
 
-Такой обработчик подставляется и в клиент: `captcha: { type: 'my-captcha', getToken: () =>
-solveCaptcha(myCaptcha), field: 'myToken' }`.
+const token = await solveCaptcha(CaptchaType.Itd);
+```
 
 ## Запуск на сервере
 
@@ -155,20 +130,12 @@ CDP), а не программной установкой значения, —
 | `browser` | — | Готовый браузер. Тогда пакет его не запускает и не закрывает. |
 | `launch` | — | Свой запуск браузера. Заменяет все параметры запуска. |
 | `contextOptions` | `locale: 'ru-RU'`, окно 1280×800 | Настройки контекста. Заменяют стандартные целиком. |
-| `logger` | — | Функция для вывода хода решения, например `console.debug`. |
-
-Ключ, назначение токена и адрес виджета — настройки конкретного провайдера, поэтому задаются
-в его фабрике:
-
-| Фабрика | Параметр | По умолчанию | Что делает |
-| --- | --- | --- | --- |
-| `itdCaptcha` | `sitekey` | ключ итд.com | Публичный ключ виджета. |
-| `itdCaptcha` | `action` | `'login'` | Назначение токена: `login`, `register`, `password_reset`. |
-| `itdCaptcha` | `captchaOrigin` | `https://captcha.xn--d1ah4a.com` | Базовый адрес виджета. |
-| `turnstile` | `sitekey` | ключ итд.com | Публичный ключ виджета. |
+| `logger` | логгер клиента | Куда писать ход решения: объект вида `console`. `createCaptchaSolver` без него пишет в логгер `itd-api`. |
+| `type` | — | Какую капчу проходить всегда. Только для `createCaptchaSolver`. |
+| `field` | — | Поле тела запроса для закреплённого типа. Только вместе с `type`. |
 
 ```ts
-await solveCaptcha(itdCaptcha({ action: 'password_reset' }), { timeout: 90_000 });
+createCaptchaSolver({ type: CaptchaType.Itd, timeout: 90_000, headless: true });
 ```
 
 Свой драйвер:
@@ -212,19 +179,52 @@ createCaptchaSolver({
 
 ## Совместимость
 
-Виджет пропускает не всякий браузер. Таблица пересобирается скриптом `scripts/drivers.mjs`
-из исходников пакета:
+Ниже — связки, на которых Cloudflare Turnstile выдал токен. Проверено 19.09.2026
+с окном, если не указано иное.
+
+| Драйвер | Версия и конфигурация | Браузер |
+|---|---|---|
+| `patchright` | 1.59.4 · 1.60.2 · 1.61.1, штатные сборки | Chromium 147 · 148 · 149 соответственно |
+| | 1.62.3 · 1.63.0, `executablePath` | Chromium 149 |
+| | 1.63.0, `executablePath` | Chromium 148 |
+| `playwright` | 1.60.0 · 1.61.0, штатные сборки | Chromium 148 · 149 соответственно |
+| | 1.62.1 · 1.63.0, `executablePath` | Chromium 149 |
+| `playwright-core` | 1.62.1 · 1.63.0, `executablePath` | Chromium 149 |
+| `camoufox-js` | 0.11.5 с окном · 0.12.0 с окном и headless, `contextOptions: {}` | Camoufox 152.0.4-beta.29 |
+| `rebrowser-playwright` | 1.48.2 · 1.49.1, `executablePath` | Chromium 149 |
+
+<details>
+<summary>Комбинации, не прошедшие проверку</summary>
+
+| Драйвер | Версия и конфигурация | Браузер | Результат |
+|---|---|---|---|
+| `patchright` | 1.62.3, штатная сборка | Chromium 151 | таймаут |
+| | 1.63.0, штатная сборка | Chrome for Testing 153 | таймаут |
+| | 1.63.0, `executablePath` | Google Chrome 152 | таймаут |
+| `playwright` | 1.62.1, штатная сборка | Chromium 151 | `600010`, таймаут |
+| | 1.63.0, штатная сборка | Chrome for Testing 153 | `600010`, таймаут |
+| | 1.63.0, `executablePath` | Google Chrome 152 | `600010`, таймаут |
+| `rebrowser-playwright` | 1.52.0, `executablePath` | Chromium 149 | `600010`, таймаут |
+| `playwright-extra` + `puppeteer-extra-plugin-stealth` | 4.3.6 + 2.11.2, `playwright` 1.62.1 · 1.63.0, `executablePath` | Chromium 149 | `600010`, таймаут |
+
+</details>
+
+Собственная капча ИТД менее требовательна: ее можно получить любым подходящим драйвером и версией браузера.
+
+Таблица проверяется скриптом `scripts/drivers.mjs` из исходников пакета:
 
 ```sh
-npm i --no-save patchright playwright camoufox-js
+npm i --no-save patchright playwright camoufox-js rebrowser-playwright \
+  playwright-extra puppeteer-extra-plugin-stealth
 node scripts/drivers.mjs            # Turnstile
 node scripts/drivers.mjs --itd      # капча ИТД
 ```
 
-Всё, что удаётся получить с окном; `headless: true` токена почти нигде не даёт. Сборка
-приезжает вместе с версией драйвера, ею и выбирается — `npm i playwright@1.61`. Поставленная
-отдельно тоже годится: `npx @puppeteer/browsers install chrome@149.0.7827.55` и путь
-в `executablePath`. Версию запущенного браузера пакет называет в сообщении о таймауте.
+Штатная сборка приезжает вместе с версией драйвера. Другую можно поставить командой
+`npx @puppeteer/browsers install chrome@149.0.7827.55` и передать путь в `executablePath`.
+Версия драйвера сама по себе не гарантирует результат: например, `patchright` и
+`playwright` 1.63.0 не проходят Turnstile на штатном Chrome for Testing 153, но проходят
+на Chromium 149 через `executablePath`.
 
 ## Лицензия
 

package/dist/index.cjs

@@ -54,9 +54,8 @@ const DEFAULT_ARGS = ["--disable-dev-shm-usage", "--disable-blink-features=Autom
 /**
 * Драйверы в порядке предпочтения.
 *
-* `patchright` впереди намеренно: он ставит собственную сборку Chromium, и та проходит
-* виджет там, где сборка из свежего Playwright уже нет. Если стоит только `playwright`,
-* ничего не меняется — берётся он.
+* `patchright` впереди намеренно: проверенная связка `patchright@1.61.1` со штатным
+* Chromium 149 проходит виджет. Если стоит только `playwright`, берётся он.
 */
 const DRIVERS = [
 	"patchright",
@@ -101,7 +100,7 @@ async function loadDriver(requested) {
 	} catch (error) {
 		if (!isModuleNotFound(error)) throw error;
 	}
-	throw new CaptchaError(CaptchaFailure.DriverMissing, requested ? `Драйвер ${requested} не установлен.` : "Не найден драйвер браузера. Установите его командой: npm i patchright && npx patchright install chromium. Либо передайте свой запуск браузера через параметр launch.");
+	throw new CaptchaError(CaptchaFailure.DriverMissing, requested ? `Драйвер ${requested} не установлен.` : "Не найден драйвер браузера. Установите проверенную связку командой: npm i patchright@1.61.1 && npx patchright install chromium. Либо передайте свой запуск браузера через параметр launch.");
 }
 /** Собирает параметры запуска, не поднимая браузер. @internal */
 function resolveLaunchOptions(options, driver = "") {
@@ -140,6 +139,12 @@ async function launchBrowser(options) {
 //#region src/options.ts
 /** Базовый URL сайта итд.com. Домен записан в punycode: `итд.com`. */
 const DEFAULT_ORIGIN = "https://xn--d1ah4a.com";
+const LOGGER_METHODS = [
+	"debug",
+	"info",
+	"warn",
+	"error"
+];
 /**
 * Приводит адрес к корню и проверяет его пригодность.
 *
@@ -172,7 +177,10 @@ function resolveOptions(options) {
 	if (theme !== "auto" && theme !== "light" && theme !== "dark") throw new TypeError("theme должен быть 'auto', 'light' или 'dark'");
 	for (const [name, value] of [["headless", options.headless], ["disableSandbox", options.disableSandbox]]) if (value !== void 0 && typeof value !== "boolean") throw new TypeError(`${name} должен быть boolean`);
 	for (const [name, value] of [["driver", options.driver], ["channel", options.channel]]) if (value !== void 0 && (typeof value !== "string" || value.trim() === "")) throw new TypeError(`${name} должен быть непустой строкой`);
-	if (options.logger !== void 0 && typeof options.logger !== "function") throw new TypeError("logger должен быть функцией");
+	if (options.logger !== void 0) {
+		if (typeof options.logger !== "object" || options.logger === null) throw new TypeError("logger должен быть объектом с методами debug, info, warn и error");
+		for (const method of LOGGER_METHODS) if (typeof options.logger[method] !== "function") throw new TypeError(`logger.${method} должен быть функцией`);
+	}
 	if (options.contextOptions !== void 0 && (typeof options.contextOptions !== "object" || options.contextOptions === null || Array.isArray(options.contextOptions))) throw new TypeError("contextOptions должен быть объектом");
 	if (options.launch !== void 0 && typeof options.launch !== "function") throw new TypeError("launch должен быть функцией");
 	if (options.args !== void 0 && (!Array.isArray(options.args) || options.args.some((argument) => typeof argument !== "string"))) throw new TypeError("args должен быть массивом строк");
@@ -521,7 +529,8 @@ async function clickCheckbox(page, offsetX) {
 }
 /** Ждёт токен, периодически подталкивая виджет кликом. */
 async function waitForToken(page, handler, options, browser) {
-	const deadline = Date.now() + options.timeout;
+	const startedAt = Date.now();
+	const deadline = startedAt + options.timeout;
 	await page.waitForSelector(handler.widgetReadySelector, {
 		timeout: Math.min(WIDGET_APPEAR_TIMEOUT, options.timeout),
 		state: "attached"
@@ -531,7 +540,7 @@ async function waitForToken(page, handler, options, browser) {
 	while (Date.now() < deadline) {
 		const state = await handler.readState(page);
 		if (state.token) {
-			options.logger?.("токен получен");
+			options.logger?.info(`токен ${handler.label} получен за ${Date.now() - startedAt} мс`);
 			return state.token;
 		}
 		if (state.error && state.error !== lastError) {
@@ -540,10 +549,10 @@ async function waitForToken(page, handler, options, browser) {
 				widgetCode: state.error
 			});
 			lastError = state.error;
-			options.logger?.(`виджет сообщил об ошибке ${state.error}, ждём повтора`);
+			options.logger?.debug(`виджет ${handler.label} сообщил об ошибке ${state.error}, ждём повтора`);
 		}
 		if (Date.now() >= nextClickAt && await clickCheckbox(page, handler.checkboxOffsetX)) {
-			options.logger?.("клик по чекбоксу");
+			options.logger?.debug(`клик по чекбоксу ${handler.label}`);
 			nextClickAt = Date.now() + CLICK_INTERVAL;
 		}
 		await sleep(POLL_INTERVAL);
@@ -609,16 +618,17 @@ function toCaptchaError(error, handler) {
 * @throws {CaptchaError} если токен получить не удалось
 */
 async function runSolver(handler, options) {
-	const browser = options.browser ?? await launchBrowser(options);
 	const owned = options.browser === void 0;
+	if (owned) options.logger?.info(`запуск браузера для ${handler.label}`);
+	const browser = options.browser ?? await launchBrowser(options);
 	try {
 		for (let attempt = 1; attempt <= options.attempts; attempt++) try {
-			options.logger?.(`попытка ${attempt} из ${options.attempts}`);
+			options.logger?.debug(`попытка ${attempt} из ${options.attempts} для ${handler.label}`);
 			return await solveOnce(browser, handler, options);
 		} catch (raw) {
 			const error = toCaptchaError(raw, handler);
 			if (isPermanent(error) || attempt === options.attempts) throw error;
-			options.logger?.(`попытка ${attempt} не удалась: ${error instanceof Error ? error.message : String(error)}`);
+			options.logger?.warn(`попытка ${attempt} из ${options.attempts} для ${handler.label} не удалась (${error instanceof Error ? error.message : String(error)}), повтор`);
 		}
 		throw new CaptchaError(CaptchaFailure.Timeout, `Токен ${handler.label} получить не удалось`, { type: handler.type });
 	} finally {
@@ -645,30 +655,46 @@ async function runSolver(handler, options) {
 async function solveCaptcha(target, options = {}) {
 	return runSolver(resolveHandler(target), resolveOptions(options));
 }
+/** Без своего логгера источник пишет ход решения в логгер клиента. */
+function withClientLogger(options, context) {
+	if (options.logger || !context?.logger) return options;
+	return {
+		...options,
+		logger: context.logger
+	};
+}
 /**
-* Собирает источник токена для клиента `itd-api`.
+* Собирает источник токена капчи для клиента `itd-api`.
 *
 * Токен одноразовый и живёт несколько минут, поэтому клиент спрашивает его заново перед
-* каждым входом. Браузер поднимается на время одного вызова и сразу закрывается.
+* каждым запросом, которому нужна капча. Браузер поднимается на время одного вызова
+* и сразу закрывается.
+*
+* @throws {TypeError} если тип капчи незнаком или `field` задан без него
 *
 * @example
 * ```ts
 * import { ItdClient } from 'itd-api';
 * import { FileTokenStorage } from 'itd-api/node';
-* import { createCaptchaSolver } from '@itd-api/captcha';
+* import { createCaptchaSolver, CaptchaType } 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(),
-*   },
+*   auth: { email: process.env.ITD_EMAIL!, password: process.env.ITD_PASSWORD! },
+*   captcha: createCaptchaSolver({ type: CaptchaType.Cloudflare }),
 * });
 * ```
 */
 function createCaptchaSolver(options = {}) {
-	return { getToken: (type) => solveCaptcha(type, options) };
+	const { type, field, ...solveOptions } = options;
+	if (type === void 0) return { getToken: (requested, context) => solveCaptcha(requested, withClientLogger(solveOptions, context)) };
+	const handler = resolveHandler(type);
+	const resolved = resolveOptions(solveOptions);
+	return {
+		type: handler.type,
+		...field === void 0 ? {} : { field },
+		getToken: (_requested, context) => runSolver(handler, withClientLogger(resolved, context))
+	};
 }
 //#endregion
 exports.CaptchaError = CaptchaError;