@gatesolve/playwright-plugin 0.1.0

package/README.md

@@ -0,0 +1,102 @@
+# @gatesolve/playwright-plugin
+
+Automatic CAPTCHA solving for Playwright. Detects Cloudflare Turnstile, reCAPTCHA, and hCaptcha challenges and solves them via [GateSolve](https://gatesolve.dev).
+
+## Install
+
+```bash
+npm install @gatesolve/playwright-plugin
+```
+
+## Quick Start
+
+### One-shot: Solve CAPTCHA on current page
+
+```typescript
+import { chromium } from 'playwright';
+import { solveOnPage } from '@gatesolve/playwright-plugin';
+
+const browser = await chromium.launch();
+const page = await browser.newPage();
+await page.goto('https://example.com/login');
+
+// Detect and solve any CAPTCHA on the page
+const result = await solveOnPage(page, {
+  apiKey: 'gs_your_key_here', // Free at gatesolve.dev
+});
+
+if (result?.success) {
+  console.log(`Solved ${result.type} in ${result.solveTimeMs}ms`);
+  // Token is already injected into the page — submit the form
+  await page.click('button[type="submit"]');
+}
+```
+
+### Auto-solve: Wrap browser context
+
+```typescript
+import { chromium } from 'playwright';
+import { withGateSolve } from '@gatesolve/playwright-plugin';
+
+const browser = await chromium.launch();
+const context = await browser.newContext();
+
+// Every page in this context will auto-solve CAPTCHAs
+withGateSolve(context, {
+  apiKey: 'gs_your_key_here',
+  debug: true,
+});
+
+const page = await context.newPage();
+await page.goto('https://example.com/protected');
+// CAPTCHA is solved automatically on page load
+```
+
+### Detect only (no solve)
+
+```typescript
+import { detectCaptcha } from '@gatesolve/playwright-plugin';
+
+const detection = await detectCaptcha(page);
+if (detection) {
+  console.log(`Found ${detection.type} with siteKey ${detection.siteKey}`);
+}
+```
+
+## API
+
+### `solveOnPage(page, options)`
+
+Detect and solve a CAPTCHA on the current page. Returns `SolveResult | null`.
+
+### `withGateSolve(context, options)`
+
+Wrap a `BrowserContext` to auto-solve CAPTCHAs on every page load. Returns the same context.
+
+### `detectCaptcha(page)`
+
+Detect CAPTCHA type and siteKey without solving. Returns `CaptchaDetection | null`.
+
+## Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiKey` | `string` | required | GateSolve API key |
+| `baseUrl` | `string` | `https://gatesolve.dev` | API base URL |
+| `timeout` | `number` | `30000` | Max solve wait (ms) |
+| `pollInterval` | `number` | `2000` | Poll frequency (ms) |
+| `debug` | `boolean` | `false` | Log debug info |
+
+## Supported CAPTCHAs
+
+- **Cloudflare Turnstile** — $0.02/solve
+- **reCAPTCHA v2/v3** — $0.03/solve
+- **hCaptcha** — $0.03/solve
+
+## Free Tier
+
+100 free solves per API key. No credit card required. Get your key at [gatesolve.dev](https://gatesolve.dev).
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @gatesolve/playwright-plugin
+ *
+ * Automatic CAPTCHA solving for Playwright.
+ * Detects Cloudflare Turnstile, reCAPTCHA, and hCaptcha on page navigation
+ * and solves them via GateSolve API.
+ *
+ * Usage:
+ *   import { solveOnPage, withGateSolve } from '@gatesolve/playwright-plugin';
+ *
+ *   // Option 1: One-shot — solve any CAPTCHA on current page
+ *   const token = await solveOnPage(page, { apiKey: 'gs_...' });
+ *
+ *   // Option 2: Auto-detect — wrap browser context, solves on every navigation
+ *   const context = await withGateSolve(browserContext, { apiKey: 'gs_...' });
+ */
+export interface GateSolveOptions {
+    /** GateSolve API key. Get one free at gatesolve.dev */
+    apiKey: string;
+    /** API base URL (default: https://gatesolve.dev) */
+    baseUrl?: string;
+    /** Max time to wait for solve in ms (default: 30000) */
+    timeout?: number;
+    /** Poll interval in ms (default: 2000) */
+    pollInterval?: number;
+    /** Log debug info (default: false) */
+    debug?: boolean;
+}
+export interface CaptchaDetection {
+    type: "turnstile" | "recaptcha" | "hcaptcha";
+    siteKey: string;
+    pageUrl: string;
+}
+export interface SolveResult {
+    success: boolean;
+    token?: string;
+    type?: string;
+    error?: string;
+    solveTimeMs?: number;
+}
+interface MinimalPage {
+    url(): string;
+    evaluate<T>(fn: string | ((...args: any[]) => T), ...args: any[]): Promise<T>;
+    waitForTimeout(ms: number): Promise<void>;
+}
+interface MinimalContext {
+    on(event: "page", handler: (page: MinimalPage) => void): void;
+    pages(): MinimalPage[];
+}
+/**
+ * Detect CAPTCHA challenges on a page.
+ */
+export declare function detectCaptcha(page: MinimalPage): Promise<CaptchaDetection | null>;
+/**
+ * Detect and solve any CAPTCHA on the current page.
+ * Returns the solve result, or null if no CAPTCHA was found.
+ */
+export declare function solveOnPage(page: MinimalPage, opts: GateSolveOptions): Promise<SolveResult | null>;
+/**
+ * Wrap a Playwright BrowserContext to automatically solve CAPTCHAs on every page load.
+ * Returns the same context (mutated with event listener).
+ */
+export declare function withGateSolve<T extends MinimalContext>(context: T, opts: GateSolveOptions): T;
+export {};

package/dist/index.js

@@ -0,0 +1,243 @@
+"use strict";
+/**
+ * @gatesolve/playwright-plugin
+ *
+ * Automatic CAPTCHA solving for Playwright.
+ * Detects Cloudflare Turnstile, reCAPTCHA, and hCaptcha on page navigation
+ * and solves them via GateSolve API.
+ *
+ * Usage:
+ *   import { solveOnPage, withGateSolve } from '@gatesolve/playwright-plugin';
+ *
+ *   // Option 1: One-shot — solve any CAPTCHA on current page
+ *   const token = await solveOnPage(page, { apiKey: 'gs_...' });
+ *
+ *   // Option 2: Auto-detect — wrap browser context, solves on every navigation
+ *   const context = await withGateSolve(browserContext, { apiKey: 'gs_...' });
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectCaptcha = detectCaptcha;
+exports.solveOnPage = solveOnPage;
+exports.withGateSolve = withGateSolve;
+const DEFAULT_BASE_URL = "https://gatesolve.dev";
+const DEFAULT_TIMEOUT = 30000;
+const DEFAULT_POLL_INTERVAL = 2000;
+function log(opts, ...args) {
+    if (opts.debug)
+        console.log("[gatesolve]", ...args);
+}
+/**
+ * Detect CAPTCHA challenges on a page.
+ */
+async function detectCaptcha(page) {
+    return page.evaluate(() => {
+        // Cloudflare Turnstile
+        const turnstileEl = document.querySelector("[data-sitekey].cf-turnstile") ||
+            document.querySelector('iframe[src*="challenges.cloudflare.com"]');
+        if (turnstileEl) {
+            const siteKey = turnstileEl.getAttribute("data-sitekey") ||
+                // Extract from iframe src
+                new URL(turnstileEl.src || "").searchParams.get("k") ||
+                "";
+            return {
+                type: "turnstile",
+                siteKey,
+                pageUrl: window.location.href,
+            };
+        }
+        // reCAPTCHA v2/v3
+        const recaptchaEl = document.querySelector(".g-recaptcha[data-sitekey]") ||
+            document.querySelector('iframe[src*="google.com/recaptcha"]');
+        if (recaptchaEl) {
+            const siteKey = recaptchaEl.getAttribute("data-sitekey") ||
+                new URL(recaptchaEl.src || "").searchParams.get("k") ||
+                "";
+            return {
+                type: "recaptcha",
+                siteKey,
+                pageUrl: window.location.href,
+            };
+        }
+        // hCaptcha
+        const hcaptchaEl = document.querySelector(".h-captcha[data-sitekey]") ||
+            document.querySelector('iframe[src*="hcaptcha.com"]');
+        if (hcaptchaEl) {
+            const siteKey = hcaptchaEl.getAttribute("data-sitekey") ||
+                new URL(hcaptchaEl.src || "").searchParams.get("sitekey") ||
+                "";
+            return {
+                type: "hcaptcha",
+                siteKey,
+                pageUrl: window.location.href,
+            };
+        }
+        return null;
+    });
+}
+/**
+ * Submit a solve request to GateSolve and poll for result.
+ */
+async function submitAndPoll(detection, opts) {
+    const baseUrl = opts.baseUrl || DEFAULT_BASE_URL;
+    const timeout = opts.timeout || DEFAULT_TIMEOUT;
+    const pollInterval = opts.pollInterval || DEFAULT_POLL_INTERVAL;
+    const startTime = Date.now();
+    log(opts, `Solving ${detection.type} for ${detection.pageUrl}`);
+    // Submit
+    const submitRes = await fetch(`${baseUrl}/api/solve`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "x-api-key": opts.apiKey,
+        },
+        body: JSON.stringify({
+            type: detection.type,
+            siteKey: detection.siteKey,
+            pageUrl: detection.pageUrl,
+        }),
+    });
+    if (!submitRes.ok) {
+        const err = await submitRes.text();
+        return { success: false, error: `Submit failed (${submitRes.status}): ${err}` };
+    }
+    const submitData = (await submitRes.json());
+    // If immediate result (unlikely but handle it)
+    if (submitData.token) {
+        return {
+            success: true,
+            token: submitData.token,
+            type: detection.type,
+            solveTimeMs: Date.now() - startTime,
+        };
+    }
+    if (!submitData.id) {
+        return { success: false, error: submitData.error || "No job ID returned" };
+    }
+    // Poll
+    const jobId = submitData.id;
+    log(opts, `Job ${jobId} submitted, polling...`);
+    while (Date.now() - startTime < timeout) {
+        await new Promise((r) => setTimeout(r, pollInterval));
+        const pollRes = await fetch(`${baseUrl}/api/solve?id=${jobId}`, {
+            headers: { "x-api-key": opts.apiKey },
+        });
+        if (!pollRes.ok)
+            continue;
+        const pollData = (await pollRes.json());
+        if (pollData.status === "completed" && pollData.token) {
+            log(opts, `Solved in ${Date.now() - startTime}ms`);
+            return {
+                success: true,
+                token: pollData.token,
+                type: detection.type,
+                solveTimeMs: Date.now() - startTime,
+            };
+        }
+        if (pollData.status === "failed") {
+            return { success: false, error: pollData.error || "Solve failed" };
+        }
+        log(opts, `Status: ${pollData.status}, waiting...`);
+    }
+    return { success: false, error: `Timeout after ${timeout}ms` };
+}
+/**
+ * Inject a solved CAPTCHA token back into the page.
+ */
+async function injectToken(page, detection, token) {
+    await page.evaluate((args) => {
+        const { type, token } = args;
+        if (type === "turnstile") {
+            // Set the hidden input
+            const input = document.querySelector('input[name="cf-turnstile-response"]') ||
+                document.querySelector(".cf-turnstile input[type=hidden]");
+            if (input)
+                input.value = token;
+            // Call the callback if it exists
+            const widget = document.querySelector(".cf-turnstile");
+            const cbName = widget?.getAttribute("data-callback");
+            if (cbName && typeof window[cbName] === "function") {
+                window[cbName](token);
+            }
+        }
+        else if (type === "recaptcha") {
+            const textarea = document.querySelector("#g-recaptcha-response");
+            if (textarea) {
+                textarea.style.display = "block";
+                textarea.value = token;
+            }
+            // Trigger callback
+            if (typeof window.___grecaptcha_cfg !== "undefined") {
+                const clients = window.___grecaptcha_cfg?.clients;
+                if (clients) {
+                    for (const client of Object.values(clients)) {
+                        for (const val of Object.values(client)) {
+                            if (val?.callback && typeof val.callback === "function") {
+                                val.callback(token);
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        else if (type === "hcaptcha") {
+            const textarea = document.querySelector('[name="h-captcha-response"]');
+            if (textarea)
+                textarea.value = token;
+            const iframe = document.querySelector('iframe[src*="hcaptcha.com"]');
+            const cbName = iframe
+                ?.closest(".h-captcha")
+                ?.getAttribute("data-callback");
+            if (cbName && typeof window[cbName] === "function") {
+                window[cbName](token);
+            }
+        }
+    }, { type: detection.type, token });
+}
+/**
+ * Detect and solve any CAPTCHA on the current page.
+ * Returns the solve result, or null if no CAPTCHA was found.
+ */
+async function solveOnPage(page, opts) {
+    const detection = await detectCaptcha(page);
+    if (!detection) {
+        log(opts, "No CAPTCHA detected");
+        return null;
+    }
+    log(opts, `Detected ${detection.type} (siteKey: ${detection.siteKey})`);
+    const result = await submitAndPoll(detection, opts);
+    if (result.success && result.token) {
+        await injectToken(page, detection, result.token);
+        log(opts, "Token injected into page");
+    }
+    return result;
+}
+/**
+ * Wrap a Playwright BrowserContext to automatically solve CAPTCHAs on every page load.
+ * Returns the same context (mutated with event listener).
+ */
+function withGateSolve(context, opts) {
+    const handlePage = (page) => {
+        // We need to listen for navigation completion. Since we use minimal types,
+        // check if the page has a 'on' method for load events
+        const pageAny = page;
+        if (typeof pageAny.on === "function") {
+            pageAny.on("load", async () => {
+                try {
+                    // Small delay to let JS render CAPTCHA widgets
+                    await page.waitForTimeout(1000);
+                    await solveOnPage(page, opts);
+                }
+                catch (err) {
+                    log(opts, "Auto-solve error:", err);
+                }
+            });
+        }
+    };
+    // Attach to existing pages
+    for (const page of context.pages()) {
+        handlePage(page);
+    }
+    // Attach to future pages
+    context.on("page", handlePage);
+    return context;
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@gatesolve/playwright-plugin",
+  "version": "0.1.0",
+  "description": "Automatic CAPTCHA solving for Playwright. Detects Cloudflare Turnstile, reCAPTCHA, and hCaptcha challenges and solves them via GateSolve.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "playwright",
+    "captcha",
+    "turnstile",
+    "cloudflare",
+    "recaptcha",
+    "hcaptcha",
+    "gatesolve",
+    "automation",
+    "ai-agent"
+  ],
+  "author": "Arson <arson@agentmail.to>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/arsonx-dev/gatesolve-playwright"
+  },
+  "peerDependencies": {
+    "playwright": ">=1.40.0",
+    "playwright-core": ">=1.40.0"
+  },
+  "peerDependenciesMeta": {
+    "playwright": {
+      "optional": true
+    },
+    "playwright-core": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ]
+}