Puppeteer (Node.js) модуль

Используется Puppeteer для автоматического решения капчи.
Поддерживает клики по изображениям, перетягивание ползунка и другие типы.
Умеет сам определять тип капчи на странице.

Актуальная версия:

Версия модуля	Скачать	Изменения
0.4	npm · 0.4	Автоопределение капчи auto(), добавлен AWS WAF

Установка

Модуль опубликован на npm:

npm install capguru puppeteer

const { CaptchaSolver, CapGuruFatalError } = require('capguru');

Обновление до последней версии:

npm install capguru@latest

Установка без npm

Скачайте архив из таблицы версий, скопируйте папку capguru в свой проект и установите Puppeteer:

npm install puppeteer

Подключайте модуль по относительному пути: require('./capguru').

Как использовать

Импортируйте CaptchaSolver из пакета.
Создайте солвер до перехода на страницу с капчей и вызовите await solver.setup().
Затем откройте страницу и вызовите await solver.auto() — модуль сам найдёт капчу и решит её.
Если тип капчи известен заранее, можно вызвать нужный метод напрямую.

const puppeteer = require('puppeteer');
const { CaptchaSolver, CapGuruFatalError } = require('capguru');

(async () => {
  const browser = await puppeteer.launch({ headless: false });
  const page = await browser.newPage();

  const solver = new CaptchaSolver({
    page,
    apiKey: 'YOUR_CAPGURU_API_KEY',
    debug: true,
    attempts: 5,
  });
  await solver.setup();

  await page.goto('https://example.com/with-captcha');

  try {
    const kind = await solver.auto(30);
    console.log('Captcha:', kind || 'not found');
  } catch (e) {
    if (e instanceof CapGuruFatalError) console.log('API key or balance problem:', e.message);
    else console.log('Not solved:', e.message);
  } finally {
    await browser.close();
  }
})();

Почему солвер создаётся до перехода на страницу

При создании солвер начинает запоминать картинки капчи, которые загружает браузер, и переключает hCaptcha на английский язык. Если создать его после page.goto(), картинки первой загрузки будут пропущены, а hCaptcha может остаться на языке сайта.

Методы:

Автоматически:

  await solver.auto(30);      // найти капчу и решить, вернёт тип или null
  await solver.detect();      // только определить тип, не решая
  await solver.setup();       // подготовка, вызывать до page.goto()

Для конкретного типа:

  await solver.solveRecaptcha2();
  await solver.solveHcaptcha();
  await solver.solveOther();
  await solver.solveGeetest();
  await solver.solveFuncaptcha();
  await solver.solveTiktok();
  await solver.solveAws();

auto() и detect() возвращают тип капчи:

Значение	Капча
recaptcha2	reCAPTCHA v2
hcaptcha	hCaptcha
yandex	Other
geetest	GeeTest v3 / v4
funcaptcha	FunCaptcha (Arkose Labs)
tiktok	TikTok
aws	AWS WAF
null	Капча не найдена за отведённое время

Параметры auto():

Параметр	Тип	По умолчанию	Описание
timeout	number	30	Сколько секунд ждать появления капчи
poll	number	0.5	Как часто проверять страницу, в секундах

Поддержка капч:

reCaptcha2	FunCaptcha	TikTok	GeeTest	hCaptcha	AWS WAF	Other
Да	Да	Да	Да	Да	Да	Да

Параметры конструктора:

Параметр	Тип	По умолчанию	Описание
page	Page	—	Экземпляр Puppeteer page
apiKey	string	—	API-ключ Cap.Guru
server	string	'https://api.cap.guru'	URL сервера API
attempts	number	5	Макс. количество попыток
debug	boolean	false	Вывод отладочных сообщений
selector	string	''	CSS-селектор контейнера капчи

Требования

• Puppeteer 24 или 25
• Node.js 18+ (для Puppeteer 25 нужен Node.js 22.12+)

Обработка ошибок

При неверном API-ключе или нулевом балансе выбрасывается CapGuruFatalError — модуль сразу прекращает попытки.
Если капчу не удалось решить за все попытки, выбрасывается Error.
CapGuruFatalError — наследник Error, поэтому проверяйте его первым:

const { CapGuruFatalError } = require('capguru');

try {
  const kind = await solver.auto(30);
  console.log('Captcha:', kind || 'not found');
} catch (e) {
  if (e instanceof CapGuruFatalError) {
    console.log('Проблема с API-ключом или балансом:', e.message);
  } else if (e.message.includes('ERROR_CAPTCHA_UNSOLVABLE')) {
    console.log('Капча не решена за все попытки');
  }
}