Handle captchas in Puppeteer flows

npm install puppeteer

export BYPASS_API_KEY="your-api-key"

$env:BYPASS_API_KEY = "your-api-key"

bypass.mjs
page-helpers.mjs
contact.mjs

const API_URL = "https://bypass.so";
const CLIENT_KEY = process.env.BYPASS_API_KEY ?? "";

export class BypassError extends Error {
  constructor(code, description = "", taskId = null) {
    super(`${code}: ${description}`);
    this.name = "BypassError";
    this.code = code;
    this.taskId = taskId;
  }
}

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function call(path, init = {}) {
  const res = await fetch(API_URL + path, { ...init, signal: AbortSignal.timeout(30_000) });
  let data;
  try {
    data = await res.json();
  } catch {
    throw new BypassError("HTTP_ERROR", `HTTP ${res.status} without a JSON body`);
  }
  if (data.errorId) {
    throw new BypassError(data.errorCode ?? "ERROR_UNKNOWN", data.errorDescription ?? "", data.taskId);
  }
  return data;
}

export async function solve(type, params, { timeoutMs = 120_000, pollMs = 2_000 } = {}) {
  if (!CLIENT_KEY) {
    throw new BypassError("ERROR_KEY_INVALID", "set the BYPASS_API_KEY environment variable");
  }
  let data = await call("/createTask", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ clientKey: CLIENT_KEY, type, ...params }),
  });
  const taskId = data.taskId;
  const deadline = Date.now() + timeoutMs;
  while (data.status !== "ready") {
    if (Date.now() > deadline) {
      throw new BypassError("CLIENT_TIMEOUT", `task ${taskId} was not ready after ${timeoutMs / 1000}s`, taskId);
    }
    await sleep(pollMs);
    data = await call(`/getTaskResult/${taskId}?clientKey=${encodeURIComponent(CLIENT_KEY)}`);
  }
  return { ...data.solution, taskId };
}

export const tokenOf = (solution) => solution.gRecaptchaResponse ?? solution.token ?? solution.text;

export const balance = () =>
  call("/balance", { headers: { Authorization: `Bearer ${CLIENT_KEY}` } });

export const reportBad = (taskId) =>
  call(`/reportBad?task_id=${encodeURIComponent(taskId)}`, {
    method: "POST",
    headers: { Authorization: `Bearer ${CLIENT_KEY}` },
  });

export const FIELDS = {
  RecaptchaV2Task: "g-recaptcha-response",
  RecaptchaV3Task: "g-recaptcha-response",
  HCaptchaTask: "h-captcha-response",
  TurnstileTask: "cf-turnstile-response",
};

export function probeWidget() {
  const kinds = [
    ["TurnstileTask", ".cf-turnstile", "iframe[src*='challenges.cloudflare.com']"],
    ["HCaptchaTask", ".h-captcha", "iframe[src*='hcaptcha.com']"],
    ["RecaptchaV2Task", ".g-recaptcha", "iframe[src*='/recaptcha/']"],
  ];
  for (const [type, box, frame] of kinds) {
    const host = document.querySelector(box + "[data-sitekey]");
    if (host) return { type, sitekey: host.dataset.sitekey, callback: host.dataset.callback || null };
    const iframe = document.querySelector(frame);
    if (iframe) {
      const url = new URL(iframe.src, location.href);
      const hash = new URLSearchParams(url.hash.slice(1));
      const sitekey = url.searchParams.get("k") || url.searchParams.get("sitekey")
        || hash.get("sitekey") || (url.pathname.match(/0x4[\w-]+/) || [])[0];
      if (sitekey) return { type, sitekey, callback: null };
    }
  }
  const any = document.querySelector("[data-sitekey]");
  if (!any) return null;
  const key = any.dataset.sitekey;
  const type = key.startsWith("0x4") ? "TurnstileTask"
    : /^[0-9a-f-]{36}$/i.test(key) ? "HCaptchaTask" : "RecaptchaV2Task";
  return { type, sitekey: key, callback: any.dataset.callback || null };
}

export function injectToken({ field, token, callback }) {
  let targets = [...document.querySelectorAll('[name="' + field + '"]')];
  if (field === "h-captcha-response") {
    targets.push(...document.querySelectorAll('[name="g-recaptcha-response"]'));
  }
  if (!targets.length) {
    const input = document.createElement("input");
    input.type = "hidden";
    input.name = field;
    (document.querySelector("form") || document.body).appendChild(input);
    targets = [input];
  }
  for (const el of targets) {
    el.value = token;
    el.dispatchEvent(new Event("input", { bubbles: true }));
    el.dispatchEvent(new Event("change", { bubbles: true }));
  }
  const fn = callback && callback.split(".").reduce((o, k) => (o ? o[k] : undefined), window);
  if (typeof fn === "function") fn(token);
  return targets.length;
}

const handle = await page.waitForFunction(probeWidget, { timeout: 20_000 });
const widget = await handle.jsonValue();

const solution = await solve(widget.type, {
  websiteURL: page.url(),
  websiteKey: widget.sitekey,
});

const field = solution.tokenField ?? FIELDS[widget.type];
await page.evaluate(injectToken, { field, token: tokenOf(solution), callback: widget.callback });
await Promise.all([page.waitForNavigation(), page.click('form [type="submit"]')]);

import puppeteer from "puppeteer";
import { solve, tokenOf } from "./bypass.mjs";
import { FIELDS, injectToken, probeWidget } from "./page-helpers.mjs";

const PAGE_URL = "https://example.com/contact";

const browser = await puppeteer.launch();
try {
  const page = await browser.newPage();
  await page.goto(PAGE_URL, { waitUntil: "domcontentloaded" });

  const handle = await page.waitForFunction(probeWidget, { timeout: 20_000 });
  const widget = await handle.jsonValue();
  console.log("found", widget.type, widget.sitekey);

  await page.type('input[name="name"]', "Ada");
  await page.type('input[name="email"]', "[email protected]");
  await page.type('textarea[name="message"]', "Hello from my test run");

  const solution = await solve(widget.type, { websiteURL: page.url(), websiteKey: widget.sitekey });
  const field = solution.tokenField ?? FIELDS[widget.type];
  await page.evaluate(injectToken, { field, token: tokenOf(solution), callback: widget.callback });

  await Promise.all([
    page.waitForNavigation({ waitUntil: "domcontentloaded" }),
    page.click('form [type="submit"]'),
  ]);
  console.log("submitted, now at", page.url());
} finally {
  await browser.close();
}

node contact.mjs

found TurnstileTask 0x4AAAAAAA-SITE-KEY
submitted, now at https://example.com/contact/thanks

const image = await page.$("img.captcha");
const imageBase64 = await image.screenshot({ encoding: "base64" });
const { text } = await solve("ImageToTextTask", { imageBase64 });

await page.type('input[name="captcha"]', text);
await Promise.all([page.waitForNavigation(), page.click('form [type="submit"]')]);

const siteKey = await page.evaluate(() => {
  const s = document.querySelector("script[src*='recaptcha'][src*='render=']");
  return s ? new URL(s.src).searchParams.get("render") : null;
});
const solution = await solve("RecaptchaV3Task", {
  websiteURL: page.url(),
  websiteKey: siteKey,
  action: "submit",
});