@xbrowser/cli 1.9.2 → 1.9.3

package/dist/human-interaction-OU7LZ6OZ.js

@@ -0,0 +1,434 @@
+import {
+  getCaptchaConfig
+} from "./chunk-IIM5GOD7.js";
+import "./chunk-KFQGP6VL.js";
+
+// src/human-interaction.ts
+import { execSync } from "child_process";
+
+// src/screencast.ts
+var ScreencastCapturer = class {
+  interval;
+  quality;
+  type;
+  maxWidth;
+  maxHeight;
+  isCapturing = false;
+  frameCallback = null;
+  // CDP Cast state
+  cdpSession = null;
+  sessionId = "";
+  // Fallback polling state
+  fallbackTimer = null;
+  constructor(options = {}) {
+    this.interval = options.interval || 100;
+    this.quality = options.quality || 60;
+    this.type = options.type || "jpeg";
+    this.maxWidth = options.width || 1920;
+    this.maxHeight = options.height || 1080;
+  }
+  /**
+   * Start screencast capture using CDP Page.startScreencast.
+   *
+   * If CDP session creation fails (non-Chromium, restricted access),
+   * automatically falls back to `page.screenshot()` polling.
+   */
+  async startCapture(page, sessionId, onFrame) {
+    if (this.isCapturing) {
+      throw new Error("Screencast is already capturing");
+    }
+    this.isCapturing = true;
+    this.frameCallback = onFrame;
+    this.sessionId = sessionId;
+    try {
+      const cdp = await page.context().newCDPSession(page);
+      this.cdpSession = cdp;
+      cdp.on("Page.screencastFrame", async (params) => {
+        if (!this.frameCallback) return;
+        try {
+          await cdp.send("Page.screencastFrameAck", { sessionId: params.sessionId });
+        } catch {
+        }
+        const viewport = {
+          width: params.metadata?.deviceWidth || this.maxWidth,
+          height: params.metadata?.deviceHeight || this.maxHeight
+        };
+        this.frameCallback({
+          id: crypto.randomUUID(),
+          sessionId: this.sessionId,
+          timestamp: Date.now(),
+          data: Buffer.from(params.data, "base64"),
+          url: page.url(),
+          viewport
+        });
+      });
+      await cdp.send("Page.startScreencast", {
+        format: this.type === "png" ? "png" : "jpeg",
+        quality: this.type === "jpeg" ? this.quality : void 0,
+        maxWidth: this.maxWidth,
+        maxHeight: this.maxHeight
+      });
+    } catch {
+      this.cdpSession = null;
+      this.startFallbackPolling(page, sessionId);
+    }
+  }
+  /**
+   * Fallback: periodic page.screenshot() polling when CDP Cast is unavailable.
+   */
+  startFallbackPolling(page, sessionId) {
+    const captureLoop = async () => {
+      if (!this.frameCallback) return;
+      try {
+        const frame = await this.captureFrame(page, sessionId);
+        this.frameCallback(frame);
+      } catch {
+      }
+    };
+    captureLoop();
+    this.fallbackTimer = setInterval(captureLoop, this.interval);
+  }
+  /**
+   * Capture a single screenshot frame from the page (fallback mode).
+   */
+  async captureFrame(page, sessionId) {
+    let viewport = page.viewportSize();
+    if (!viewport) {
+      try {
+        viewport = await page.evaluate(() => ({ width: window.innerWidth, height: window.innerHeight }));
+      } catch {
+        viewport = { width: 1920, height: 1080 };
+      }
+    }
+    const screenshot = await page.screenshot({
+      type: this.type,
+      quality: this.type === "jpeg" ? this.quality : void 0
+    });
+    return {
+      id: crypto.randomUUID(),
+      sessionId,
+      timestamp: Date.now(),
+      data: screenshot,
+      url: page.url(),
+      viewport: viewport || { width: 0, height: 0 }
+    };
+  }
+  /**
+   * Stop the current screencast capture.
+   */
+  async stopCapture() {
+    if (this.cdpSession) {
+      try {
+        this.cdpSession.off("Page.screencastFrame", () => {
+        });
+        await this.cdpSession.send("Page.stopScreencast");
+      } catch {
+      }
+      try {
+        await this.cdpSession.detach();
+      } catch {
+      }
+      this.cdpSession = null;
+    }
+    if (this.fallbackTimer) {
+      clearInterval(this.fallbackTimer);
+      this.fallbackTimer = null;
+    }
+    this.isCapturing = false;
+    this.frameCallback = null;
+  }
+  isActive() {
+    return this.isCapturing;
+  }
+  setInterval(interval) {
+    this.interval = interval;
+  }
+  setQuality(quality) {
+    this.quality = quality;
+  }
+};
+
+// src/captcha-detector.ts
+var CAPTCHA_SELECTORS = [
+  { selector: 'iframe[src*="recaptcha"]', type: "recaptcha", confidence: "high" },
+  { selector: ".g-recaptcha", type: "recaptcha", confidence: "high" },
+  { selector: "#recaptcha", type: "recaptcha", confidence: "high" },
+  { selector: "[data-sitekey]", type: "recaptcha", confidence: "medium" },
+  { selector: 'iframe[src*="hcaptcha"]', type: "hcaptcha", confidence: "high" },
+  { selector: ".h-captcha", type: "hcaptcha", confidence: "high" },
+  { selector: 'iframe[src*="challenges.cloudflare.com"]', type: "turnstile", confidence: "high" },
+  { selector: ".cf-turnstile", type: "turnstile", confidence: "high" },
+  { selector: 'iframe[src*="captcha"]', type: "generic", confidence: "medium" },
+  { selector: "[data-captcha]", type: "generic", confidence: "medium" },
+  { selector: ".captcha-container", type: "generic", confidence: "medium" },
+  { selector: "#captcha", type: "generic", confidence: "medium" },
+  { selector: ".captcha-image", type: "generic", confidence: "medium" },
+  { selector: "#captcha_image", type: "generic", confidence: "medium" },
+  // 小红书滑块验证
+  { selector: ".captcha-verify-image", type: "xhs-slider", confidence: "high" },
+  { selector: ".verify-wrap", type: "xhs-slider", confidence: "medium" },
+  { selector: '[class*="slider-verify"]', type: "xhs-slider", confidence: "medium" },
+  { selector: '[class*="captcha-verify"]', type: "xhs-slider", confidence: "medium" },
+  { selector: '[class*="verify-image"]', type: "xhs-slider", confidence: "low" }
+];
+var CAPTCHA_TEXT_PATTERNS = [
+  "verify you are human",
+  "prove you are not a robot",
+  "complete the challenge",
+  "are you a robot",
+  "human verification",
+  "security check",
+  "prove you're human",
+  "not a robot",
+  // 小红书验证提示
+  /xiaohongshu.*verif/i,
+  /拖动滑块/,
+  /请完成验证/,
+  /slide.*verify/i
+];
+var CaptchaDetector = class {
+  /**
+   * Scan the page for visible CAPTCHA elements or challenge text.
+   *
+   * @param page - The Playwright page to scan.
+   * @returns Detection result with type, selector, and confidence level.
+   */
+  static async detect(page) {
+    for (const rule of CAPTCHA_SELECTORS) {
+      try {
+        const el = await page.$(rule.selector);
+        if (el) {
+          const visible = await el.isVisible().catch(() => false);
+          if (visible) {
+            return {
+              detected: true,
+              type: rule.type,
+              selector: rule.selector,
+              confidence: rule.confidence
+            };
+          }
+        }
+      } catch {
+      }
+    }
+    try {
+      const bodyText = await page.textContent("body").catch(() => "");
+      if (bodyText) {
+        for (const pattern of CAPTCHA_TEXT_PATTERNS) {
+          const matches = pattern instanceof RegExp ? pattern.test(bodyText) : bodyText.toLowerCase().includes(pattern);
+          if (matches) {
+            return {
+              detected: true,
+              type: "text-challenge",
+              confidence: "low"
+            };
+          }
+        }
+      }
+    } catch {
+    }
+    return { detected: false, confidence: "low" };
+  }
+  /**
+   * Check whether a previously detected CAPTCHA has been solved.
+   *
+   * @param page - The Playwright page to check.
+   * @param previousSelector - The selector from a previous detection result.
+   * @returns `true` if the CAPTCHA is no longer visible.
+   */
+  static async isSolved(page, previousSelector) {
+    if (previousSelector) {
+      try {
+        const el = await page.$(previousSelector);
+        if (!el) return true;
+        const visible = await el.isVisible().catch(() => false);
+        if (!visible) return true;
+      } catch {
+        return true;
+      }
+    }
+    const result = await this.detect(page);
+    return !result.detected;
+  }
+};
+
+// src/webhook.ts
+var WebhookNotifier = class {
+  url;
+  constructor(url) {
+    this.url = url || process.env.XBROWSER_NOTIFY_URL || null;
+  }
+  /**
+   * Send a webhook notification payload.
+   *
+   * @param payload - The event payload to send.
+   * @returns `true` if the request succeeded (HTTP 2xx), `false` otherwise.
+   */
+  async notify(payload) {
+    if (!this.url) return false;
+    try {
+      const response = await fetch(this.url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(payload),
+        signal: AbortSignal.timeout(5e3)
+      });
+      return response.ok;
+    } catch {
+      return false;
+    }
+  }
+};
+
+// src/utils/shell-escape.ts
+function shellEscape(value) {
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}
+
+// src/human-interaction.ts
+var HumanInteractionManager = class {
+  wsServer;
+  page;
+  capturer;
+  webhook;
+  autoOpen;
+  constructor(wsServer, page) {
+    this.wsServer = wsServer;
+    this.page = page;
+    this.capturer = new ScreencastCapturer();
+    const cfg = getCaptchaConfig();
+    this.webhook = new WebhookNotifier(cfg.notifyUrl);
+    this.autoOpen = cfg.autoOpen;
+    this.wsServer.registerSession("default", page);
+  }
+  async sendWebhook(event, overrides = {}) {
+    await this.webhook.notify({
+      event,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      url: this.page.url(),
+      previewUrl: `http://localhost:${this.wsServer.getPort()}`,
+      ...overrides
+    });
+  }
+  tryAutoOpen(previewUrl) {
+    if (!this.autoOpen) return;
+    try {
+      const cmd = process.platform === "darwin" ? "open" : process.platform === "linux" ? "xdg-open" : "start";
+      execSync(`${cmd} ${shellEscape(previewUrl)}`, { stdio: "ignore" });
+    } catch {
+    }
+  }
+  /**
+   * Wait for a human to solve a CAPTCHA or complete an interaction.
+   *
+   * Starts screencast streaming, sends webhook and broadcast notifications,
+   * then polls for CAPTCHA resolution or waits for a manual solve signal.
+   *
+   * @param options - Configuration for timeout, auto-detection, and reason text.
+   * @returns Result indicating whether the CAPTCHA was solved and by what method.
+   */
+  async waitForHuman(options = {}) {
+    const {
+      reason = "Human interaction required",
+      timeout = 120,
+      autoDetect = true,
+      detectInterval = 2e3
+    } = options;
+    const captcha = await CaptchaDetector.detect(this.page);
+    const captchaInfo = captcha.detected ? captcha : void 0;
+    await this.capturer.startCapture(this.page, "default", (frame) => {
+      this.wsServer.broadcast({
+        type: "screenshot",
+        data: {
+          sessionId: frame.sessionId,
+          id: frame.id,
+          timestamp: frame.timestamp,
+          data: frame.data,
+          url: frame.url,
+          viewport: frame.viewport
+        }
+      });
+    });
+    const previewUrl = `http://localhost:${this.wsServer.getPort()}`;
+    await this.sendWebhook("captcha-detected", {
+      reason: captchaInfo ? `${captchaInfo.type ?? "unknown"} CAPTCHA detected` : reason,
+      timeout,
+      targetUrl: this.page.url()
+    });
+    this.wsServer.broadcast({
+      type: "captcha-detected",
+      sessionId: "default",
+      url: this.page.url(),
+      reason: captchaInfo ? `${captchaInfo.type ?? "unknown"} CAPTCHA detected` : reason,
+      timeout
+    });
+    this.tryAutoOpen(previewUrl);
+    console.log("");
+    console.log("\u26A0\uFE0F  \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550");
+    console.log(`\u26A0\uFE0F  ${captchaInfo ? (captchaInfo.type ?? "UNKNOWN").toUpperCase() + " CAPTCHA" : "INTERACTION"} REQUIRED`);
+    console.log(`\u26A0\uFE0F  URL: ${this.page.url()}`);
+    console.log(`\u26A0\uFE0F  `);
+    console.log(`\u26A0\uFE0F  Solve via:`);
+    console.log(`\u26A0\uFE0F    \u{1F4FA} Preview: ${previewUrl}`);
+    console.log(`\u26A0\uFE0F    \u{1F310} Direct:  ${this.page.url()}`);
+    console.log(`\u26A0\uFE0F    \u23ED\uFE0F  Skip`);
+    console.log(`\u26A0\uFE0F    \u274C Abort`);
+    console.log(`\u26A0\uFE0F  `);
+    console.log(`\u26A0\uFE0F  \u23F3 Waiting... (${timeout}s timeout)`);
+    console.log("\u26A0\uFE0F  \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550");
+    console.log("");
+    return new Promise((resolve) => {
+      let resolved = false;
+      let pollTimer = null;
+      let timeoutTimer = null;
+      const cleanup = () => {
+        if (pollTimer) clearInterval(pollTimer);
+        if (timeoutTimer) clearTimeout(timeoutTimer);
+        this.wsServer.removeListener("human-solved", onHumanSolved);
+        this.capturer.stopCapture();
+      };
+      if (autoDetect && captchaInfo) {
+        pollTimer = setInterval(async () => {
+          if (resolved) return;
+          try {
+            const solved = await CaptchaDetector.isSolved(this.page, captchaInfo.selector);
+            if (solved) {
+              resolved = true;
+              cleanup();
+              this.wsServer.broadcast({ type: "resolved", sessionId: "default" });
+              console.log("\u2705 CAPTCHA auto-detected as solved!");
+              this.sendWebhook("captcha-resolved", { reason: "auto-detected" });
+              resolve({ solved: true, method: "auto-detected" });
+            }
+          } catch {
+          }
+        }, detectInterval);
+      }
+      const onHumanSolved = () => {
+        if (!resolved) {
+          resolved = true;
+          cleanup();
+          this.wsServer.broadcast({ type: "resolved", sessionId: "default" });
+          console.log("\u2705 CAPTCHA solved via preview!");
+          this.sendWebhook("captcha-resolved", { reason: "preview" });
+          resolve({ solved: true, method: "preview" });
+        }
+      };
+      this.wsServer.on("human-solved", onHumanSolved);
+      if (timeout > 0) {
+        timeoutTimer = setTimeout(() => {
+          if (!resolved) {
+            resolved = true;
+            cleanup();
+            console.log("\u23F0 Timeout - skipping");
+            this.sendWebhook("captcha-resolved", { reason: "timeout" });
+            resolve({ solved: false, method: "timeout" });
+          }
+        }, timeout * 1e3);
+      }
+    });
+  }
+};
+export {
+  HumanInteractionManager
+};

package/dist/index.d.ts

@@ -961,11 +961,41 @@ declare class HumanInteractionManager {
     waitForHuman(options?: WaitForHumanOptions): Promise<WaitForHumanResult>;
 }
 
+/**
+ * xbrowser — Anti-Bot Detection
+ *
+ * 主动检测页面的反机器人检测机制，在执行自动化动作前拦截可疑情况。
+ */
+
+/**
+ * 检测结果类型
+ */
+interface DetectionResult {
+    detected: boolean;
+    type?: string;
+    severity?: 'low' | 'medium' | 'high';
+    message?: string;
+    selector?: string;
+    actionRequired?: 'retry' | 'manual' | 'switch';
+}
+/**
+ * 检测器配置
+ */
+interface DetectionConfig {
+    checkCaptcha?: boolean;
+    checkWarning?: boolean;
+    checkBlocked?: boolean;
+    checkLogin?: boolean;
+    checkWebdriver?: boolean;
+    timeout?: number;
+}
+
 /**
  * Extended command context for browser automation commands.
  *
  * Provides Playwright Page, Browser, and BrowserContext instances,
- * along with an optional `waitForHuman` function for CAPTCHA handling.
+ * along with optional `waitForHuman` (CAPTCHA handling) and
+ * `detectAntiBot` (anti-bot detection) capabilities.
  */
 interface BrowserCommandContext extends CommandContext {
     page: XBPage;
@@ -974,6 +1004,7 @@ interface BrowserCommandContext extends CommandContext {
     sessionId?: string;
     cdpEndpoint?: string;
     waitForHuman?: (options?: WaitForHumanOptions) => Promise<WaitForHumanResult>;
+    detectAntiBot?: (page: XBPage, config?: DetectionConfig) => Promise<DetectionResult>;
 }
 /**
  * Validate that the required browser scope is available in the context.