Node.js Turnstile solver: clearing Cloudflare Turnstile from Node

// solve.mjs — Node 18+, zero dependencies.
// Run: SOLVEGATE_KEY=sk_test_... node solve.mjs
import { randomUUID } from "node:crypto";

const API = "https://api.solvegate.io";
const KEY = process.env.SOLVEGATE_KEY;
if (!KEY) throw new Error("set SOLVEGATE_KEY");

export async function solveTurnstile({ sitekey, url, timeoutMs = 60_000 }) {
  const res = await fetch(`${API}/v1/solve`, {
    method: "POST",
    headers: {
      authorization: `Bearer ${KEY}`,
      "content-type": "application/json",
      // Retrying the same request with this header cannot double-charge you.
      "idempotency-key": randomUUID(),
    },
    body: JSON.stringify({ gate: "turnstile", sitekey, url }),
    signal: AbortSignal.timeout(timeoutMs),
  });

  const body = await res.json().catch(() => ({}));

  if (res.status === 429) {
    // Retry-After is sent on every 429, in whole seconds. Honour it.
    const err = new Error("rate_limited");
    err.retryAfter = Number(res.headers.get("retry-after")) || 1;
    throw err;
  }

  if (!res.ok) {
    // Documented envelope: { error: { code, message, billed } }
    const { code = "error", message = res.statusText, billed = false } = body.error ?? {};
    throw Object.assign(new Error(`${code}: ${message}`), { status: res.status, code, billed });
  }

  if (body.mode === "sandbox") {
    console.warn("sandbox key: deterministic response, never cleared a real gate");
  }

  return body; // { id, status, token, solve_ms, expires_at, mode, meter, billed }
}

const solve = await solveTurnstile({
  sitekey: "0x4AAAAAAAAA_target",
  url: "https://staging.example.com/login",
});

console.log(solve.status, `${solve.solve_ms}ms`, solve.token);

npm install solvegate   # Node 18+, zero dependencies, ships its own .d.ts

// solve.ts — TypeScript, or drop the annotations for plain .mjs
import { SolveGate, SolveGateError, type Solve } from "solvegate";

const sg = new SolveGate(process.env.SOLVEGATE_KEY!, {
  timeoutMs: 45_000, // per-request cap
  maxRetries: 3,     // 429s and network errors; Retry-After wins over backoff
});

export async function turnstileToken(sitekey: string, url: string): Promise<string> {
  try {
    const solve: Solve = await sg.solve({ gate: "turnstile", sitekey, url });

    if (solve.status !== "solved" || solve.token === null) {
      throw new Error(`solve ${solve.id} ended as ${solve.status}`);
    }
    if (solve.meter === "sandbox") {
      throw new Error("sandbox key — swap in a live key before trusting this token");
    }
    return solve.token;
  } catch (err) {
    if (err instanceof SolveGateError) {
      // .code / .status / .billed come straight off the error envelope.
      switch (err.code) {
        case "balance_empty":
        case "spend_cap_reached":
          throw new Error(`out of credit (${err.code}) — top up, then retry`);
        case "solve_timeout":
          throw new Error("gate did not clear; not billed, safe to retry");
        case "unknown_sitekey":
          throw new Error(`sitekey ${sitekey} rejected — re-read it off the page`);
      }
    }
    throw err;
  }
}

// Fire-and-poll, for jobs you do not want to block on.
export async function turnstileTokenAsync(sitekey: string, url: string): Promise<Solve> {
  const pending = await sg.solve({ gate: "turnstile", sitekey, url, async: true });
  return sg.wait(pending.id, { intervalMs: 750, timeoutMs: 30_000 });
}

// solvegate-types.ts
export type Gate = "turnstile" | "waf";
export type SolveStatus = "pending" | "solved" | "failed";

export interface Solve {
  id: string;
  status: SolveStatus;
  gate: Gate;
  token: string | null;        // null until status === "solved"
  solve_ms: number | null;
  expires_at: number | null;   // unix seconds
  mode: "live" | "sandbox";    // sandbox = sk_test_ key, no real gate cleared
  meter: "credits" | "pass" | "sandbox";
  billed: boolean;
  error_code: string | null;   // set only when status === "failed"
  error_message: string | null;
}

export interface ApiErrorBody {
  error: { code: string; message: string; billed: boolean };
}

export function isSolved(s: Solve): s is Solve & { token: string } {
  return s.status === "solved" && s.token !== null;
}

// test.mjs — npm install playwright
import { chromium } from "playwright";
import { solveTurnstile } from "./solve.mjs";

const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto("https://staging.example.com/login");

// Implicit rendering puts the sitekey on the container. Explicit rendering
// does not — read it from your own config in that case.
const sitekey = await page.locator("[data-sitekey]").first().getAttribute("data-sitekey");

const { token } = await solveTurnstile({ sitekey, url: page.url() });

await page.evaluate((t) => {
  const field = document.querySelector('input[name="cf-turnstile-response"]');
  if (!field) throw new Error("no cf-turnstile-response input — widget not rendered yet");
  field.value = t;
}, token);

await page.fill("#email", "qa@example.com");
await page.fill("#password", process.env.TEST_PASSWORD);
await page.click('button[type="submit"]');
await page.waitForURL("**/dashboard");

await browser.close();