@iflow-mcp/jakeliume-webpeel 0.22.0

package/dist/core/human.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Human Behavior Engine for WebPeel
+ *
+ * Simulates realistic human interaction patterns to avoid bot detection.
+ * All functions introduce natural variance and imperfection that mirrors
+ * how real users actually interact with web pages.
+ *
+ * Key techniques:
+ * - Gaussian-distributed delays (not flat uniform random)
+ * - Bézier curve mouse movement (not teleport or linear)
+ * - Realistic typing with occasional typo+correction
+ * - Variable scroll speed with pauses
+ * - Site-specific warmup sequences
+ */
+import type { Page } from 'playwright';
+export interface HumanConfig {
+    /** Typing speed range in ms per character. Default: [45, 120] */
+    typingSpeed?: [number, number];
+    /** Chance of a typo + correction per character (0-1). Default: 0.03 */
+    typoChance?: number;
+    /** Mouse movement speed factor (1 = normal, 0.5 = slow, 2 = fast). Default: 1 */
+    mouseSpeed?: number;
+    /** Minimum think time before actions in ms. Default: 500 */
+    minThinkTime?: number;
+    /** Maximum think time before actions in ms. Default: 3000 */
+    maxThinkTime?: number;
+}
+/**
+ * Delay with gaussian-distributed timing centered between minMs and maxMs.
+ * Clamps to [minMs, maxMs] so the result is always in-range.
+ */
+export declare function humanDelay(minMs: number, maxMs: number): Promise<void>;
+/**
+ * Type text with human-like timing and occasional typos.
+ *
+ * Behavior:
+ * - Each character has a gaussian-distributed delay based on typingSpeed config
+ * - Speed varies: faster mid-word, slower at word boundaries
+ * - Occasionally pauses 200-500ms (simulating thinking/reading ahead)
+ * - Rarely makes a typo, notices it (100-300ms), backspaces, then corrects
+ *
+ * @param page     Playwright page
+ * @param selector CSS selector for the input element
+ * @param text     Text to type
+ * @param config   Optional human behavior config overrides
+ */
+export declare function humanType(page: Page, selector: string, text: string, config?: HumanConfig): Promise<void>;
+/**
+ * Clear a field and type new text — like a human triple-clicking to select all,
+ * then typing the replacement. Useful when the field already has content.
+ *
+ * @param page     Playwright page
+ * @param selector CSS selector for the input element
+ * @param text     Replacement text
+ * @param config   Optional human behavior config overrides
+ */
+export declare function humanClearAndType(page: Page, selector: string, text: string, config?: HumanConfig): Promise<void>;
+/**
+ * Click an element with human-like behavior:
+ * 1. Brief thinking pause
+ * 2. Bézier curve mouse movement to the element
+ * 3. Small random offset from center (humans rarely click the exact center)
+ * 4. Brief hover before clicking
+ * 5. Click
+ *
+ * @param page     Playwright page
+ * @param selector CSS selector for the target element
+ * @param config   Optional human behavior config overrides
+ */
+export declare function humanClick(page: Page, selector: string, config?: HumanConfig): Promise<void>;
+/**
+ * Scroll the page like a human.
+ *
+ * Behavior:
+ * - Variable scroll speed (natural: faster through boring areas, slower near content)
+ * - Occasional reading pauses mid-scroll
+ * - Small back-scrolls (re-reading behavior)
+ * - Uses page.mouse.wheel() for proper scroll events (not scrollTo)
+ *
+ * @param page    Playwright page
+ * @param options Scroll direction, amount, and duration
+ */
+export declare function humanScroll(page: Page, options?: {
+    /** Scroll direction. Default: 'down' */
+    direction?: 'up' | 'down';
+    /** Approximate pixels to scroll. Default: random 300-800 */
+    amount?: number;
+    /** Total scroll duration in ms. Default: random 1000-3000 */
+    duration?: number;
+}): Promise<void>;
+/**
+ * Scroll the page until a specific element is visible, with natural scrolling.
+ *
+ * @param page     Playwright page
+ * @param selector CSS selector for the target element
+ * @param config   Optional human behavior config overrides
+ */
+export declare function humanScrollToElement(page: Page, selector: string, config?: HumanConfig): Promise<void>;
+/**
+ * Browse a site naturally for warmup before performing target actions.
+ * Establishes a realistic browsing pattern that helps avoid bot detection.
+ *
+ * Site-specific behavior:
+ * - **LinkedIn**: Scroll feed, maybe hover posts, pause to "read"
+ * - **Upwork**: Browse job listings, scroll, hover over results
+ * - **Indeed**: Scroll job results, maybe hover over a few listings
+ * - **Generic**: Slow scroll, hover over links, maybe click one internal link
+ *
+ * @param page       Playwright page
+ * @param site       Site identifier for tailored warmup behavior
+ * @param durationMs Approximate warmup duration in ms (default: 30000-60000)
+ */
+export declare function warmupSession(page: Page, site?: 'linkedin' | 'upwork' | 'indeed' | 'generic', durationMs?: number): Promise<void>;
+/**
+ * Select an option from a <select> dropdown with human-like behavior:
+ * 1. Click the dropdown
+ * 2. Brief pause (deciding)
+ * 3. Select the target option
+ *
+ * @param page     Playwright page
+ * @param selector CSS selector for the <select> element
+ * @param value    Option value or label text to select
+ * @param config   Optional human behavior config overrides
+ */
+export declare function humanSelect(page: Page, selector: string, value: string, config?: HumanConfig): Promise<void>;
+/**
+ * Upload a file via a file input with natural delays.
+ * Simulates the realistic timing of a user who opened a file picker and
+ * navigated to the file.
+ *
+ * @param page      Playwright page
+ * @param selector  CSS selector for the file input element
+ * @param filePath  Absolute path to the file to upload
+ */
+export declare function humanUploadFile(page: Page, selector: string, filePath: string): Promise<void>;
+/**
+ * Click a checkbox or radio button with human-like behavior.
+ * Moves the mouse naturally before clicking.
+ *
+ * @param page     Playwright page
+ * @param selector CSS selector for the checkbox or radio
+ * @param config   Optional human behavior config overrides
+ */
+export declare function humanToggle(page: Page, selector: string, config?: HumanConfig): Promise<void>;
+/**
+ * Move mouse along a natural Bézier curve to a position.
+ * Public wrapper around the internal moveMouse function.
+ *
+ * @param page      Playwright page
+ * @param targetX   Target X coordinate
+ * @param targetY   Target Y coordinate
+ * @param options   Speed options
+ */
+export declare function humanMouseMove(page: Page, targetX: number, targetY: number, options?: {
+    /** Number of intermediate steps (approximated via speed factor). Default: normal */
+    steps?: number;
+    /** Total duration in ms range [min, max]. Default: [200, 600] */
+    duration?: [number, number];
+}): Promise<void>;
+/**
+ * Read a page like a human — scroll through content with natural pauses.
+ * Simulates someone actually reading the page before taking action.
+ *
+ * @param page       Playwright page
+ * @param durationMs Approximate time to spend "reading" (default: 5000-15000 random)
+ */
+export declare function humanRead(page: Page, durationMs?: number): Promise<void>;
+/**
+ * Browse a site naturally for warmup before performing the target action.
+ * Thin wrapper around `warmupSession` with a simplified site-detection interface.
+ *
+ * @param page       Playwright page
+ * @param durationMs How long to browse (default: 30000-60000 random)
+ */
+export declare function warmupBrowse(page: Page, durationMs?: number): Promise<void>;