@hira-core/sdk 1.0.7 → 1.0.9

package/README.md

@@ -188,17 +188,22 @@ const utils = new BrowserUtils(context);
 
 #### Navigation & Interaction
 
-| Method                                     | Description                   |
-| ------------------------------------------ | ----------------------------- |
-| `utils.goto(url)`                          | Navigate to URL               |
-| `utils.click(selector)`                    | Wait + scroll + click         |
-| `utils.type(selector, text)`               | Wait + clear + type           |
-| `utils.getText(selector)`                  | Get text content              |
-| `utils.exists(selector, timeout?)`         | Check element exists          |
-| `utils.waitForElement(selector, timeout?)` | Wait for element              |
-| `utils.waitForNavigation()`                | Wait for page navigation      |
-| `utils.screenshot(path?)`                  | Take screenshot               |
-| `utils.sleep(ms)`                          | Delay (respects abort signal) |
+| Method                                     | Description                            |
+| ------------------------------------------ | -------------------------------------- |
+| `utils.goto(url)`                          | Navigate to URL                        |
+| `utils.click(selector)`                    | Wait + scroll + click                  |
+| `utils.click({ x, y })`                    | Click at specific coordinates          |
+| `utils.type(selector, text)`               | Wait + clear + type                    |
+| `utils.select(selector, value)`            | Select dropdown option (native `<select>`) |
+| `utils.getText(selector)`                  | Get text content                       |
+| `utils.getPosition(selector)`              | Get element center coordinates         |
+| `utils.exists(selector, timeout?)`         | Check element exists                   |
+| `utils.waitForElement(selector, timeout?)` | Wait for element                       |
+| `utils.waitForNavigation()`                | Wait for page navigation               |
+| `utils.screenshot(path?)`                  | Take screenshot                        |
+| `utils.sleep(ms)`                          | Delay (respects abort signal)          |
+| `utils.scroll({ deltaY })`                 | Smooth 60fps scroll (ease-in-out)      |
+| `utils.scroll({ deltaY, container })`      | Smooth scroll inside overflow container|
 
 #### Tab Management
 
@@ -344,6 +349,22 @@ npx @hira-core/cli build
 
 ---
 
+## Virtual Cursor
+
+The SDK includes a **virtual cursor** — a visible SVG cursor overlay that shows mouse movement, clicks, and scrolling in real-time. This is enabled by default and can be toggled via `IExecutionConfig.virtualCursor`:
+
+```typescript
+// In flow runner params
+execution: {
+  virtualCursor: true,   // default — show cursor overlay
+  // virtualCursor: false,  // disable cursor overlay
+}
+```
+
+When enabled, `BrowserUtils.click()`, `scroll()`, and other interaction methods will show realistic Bézier curve mouse movement with human-like timing.
+
+---
+
 ## License
 
 ISC

package/dist/index.d.ts

@@ -237,6 +237,12 @@ interface IExecutionConfig {
      * Dev mode: dùng constructor `super(AntidetectProvider.GPM, ...)` trong flow class.
      */
     antidetectProvider?: 'gpm' | 'hidemium' | 'genlogin' | 'adspower';
+    /**
+     * Enable virtual cursor — SVG arrow with Bézier curve mouse movement.
+     * When true, click() and type() will move cursor naturally before interacting.
+     * Default: true
+     */
+    virtualCursor?: boolean;
 }
 interface IBrowserWindowConfig {
     width: number;
@@ -314,6 +320,8 @@ interface IScriptContext<TConfig extends IFlowConfig = IFlowConfig> {
     page: Page;
     profile: IAntidetectProfile;
     index: number;
+    /** Execution config — includes virtualCursor flag etc. */
+    execution: IExecutionConfig;
     globalInput: InferGlobalInput<TConfig>;
     profileInput: InferProfileInput<TConfig>;
     /**
@@ -616,13 +624,26 @@ declare class BrowserUtils<TConfig extends IFlowConfig = IFlowConfig> {
     private activePage;
     /** Currently active iframe — null means main frame. Changed via activeIframe() */
     private activeFrame;
+    /** Virtual cursor — Bézier movement + SVG visualization */
+    private readonly hiraCursor;
     constructor(context: IScriptContext<TConfig>);
     /**
-     * CDP trick — Chromium nghĩ tab luôn focused, không bị throttle
-     * khi user chuyển sang tab khác hoặc click vào trình duyệt.
+     * CDP trick — Chromium thinks tab is always focused, not throttled
+     * when user switches to another tab or clicks elsewhere.
      */
     private enableFocusEmulation;
+    /**
+     * Apply stealth scripts to remove automation fingerprints.
+     * Uses evaluateOnNewDocument — runs BEFORE any page scripts on every navigation.
+     * Persists across navigations on the same page instance.
+     */
+    private applyStealthScripts;
     private checkAbort;
+    /**
+     * Scroll element vào viewport mượt mà — segments + delay.
+     * Chỉ scroll nếu element nằm ngoài viewport.
+     */
+    private smoothScrollToElement;
     /**
      * Pause execution for the given duration.
      *
@@ -650,10 +671,11 @@ declare class BrowserUtils<TConfig extends IFlowConfig = IFlowConfig> {
      */
     private resolveElement;
     /**
-     * Click on an element. Scrolls the element into view before clicking.
+     * Click on an element or at specific coordinates.
+     * Scrolls the element into view before clicking.
      * Throws if the element is not found.
      *
-     * @param target - CSS selector, XPath, or an existing ElementHandle
+     * @param target - CSS selector, XPath, ElementHandle, or `{ x, y }` coordinates
      * @param options.delay - Delay in ms before clicking (default: 1000)
      * @param options.waitTimeout - Max wait time for element to appear (default: 2000)
      * @param options.frame - Optional Frame to search within
@@ -662,9 +684,58 @@ declare class BrowserUtils<TConfig extends IFlowConfig = IFlowConfig> {
      * @example
      * await utils.click("#submit-btn");
      * await utils.click("#btn", { delay: 0 });             // click immediately
-     * await utils.click("#btn", { waitTimeout: 8000 });     // wait longer
+     * await utils.click({ x: 500, y: 300 });               // click at coordinates
+     * const pos = await utils.getPosition("#btn", { randomXY: true });
+     * await utils.click(pos!);                              // click random point inside element
      */
-    click(target: string | ElementHandle, options?: {
+    click(target: string | ElementHandle | {
+        x: number;
+        y: number;
+    }, options?: {
+        delay?: number;
+        waitTimeout?: number;
+        frame?: Frame;
+    }): Promise<boolean>;
+    /**
+     * Get the position (x, y) of an element.
+     * Returns center point by default, or a random point within bounds with `randomXY`.
+     *
+     * @param selector - CSS selector or XPath
+     * @param options.randomXY - If true, returns random point within element (10% margin from edges)
+     * @param options.waitTimeout - Max wait time for element (default: 2000ms)
+     * @param options.frame - Optional Frame to search within
+     * @returns `{ x, y }` or null if element not found / no bounding box
+     *
+     * @example
+     * const center = await utils.getPosition("#btn");
+     * const rand = await utils.getPosition("#btn", { randomXY: true });
+     * if (rand) await utils.click(rand);
+     */
+    getPosition(selector: string, options?: {
+        randomXY?: boolean;
+        waitTimeout?: number;
+        frame?: Frame;
+    }): Promise<{
+        x: number;
+        y: number;
+    } | null>;
+    /**
+     * Select a value from a `<select>` dropdown.
+     * Human-like flow: cursor moves to select → click to open → page.select() → close.
+     *
+     * NOTE: Native `<option>` elements CAN NOT be clicked via Puppeteer
+     * ("Node is either not clickable or not an Element").
+     * `page.select()` is the ONLY reliable method.
+     *
+     * @param selector - CSS selector or XPath of the `<select>` element
+     * @param value - The `value` attribute of the option to select
+     * @param options.delay - Delay before clicking (default: 500ms)
+     * @param options.waitTimeout - Max wait for element (default: 2000ms)
+     *
+     * @example
+     * await utils.select("#country", "vn");
+     */
+    select(selector: string, value: string, options?: {
         delay?: number;
         waitTimeout?: number;
         frame?: Frame;
@@ -741,6 +812,78 @@ declare class BrowserUtils<TConfig extends IFlowConfig = IFlowConfig> {
     goto(url: string, options?: {
         waitUntil?: "load" | "domcontentloaded" | "networkidle0" | "networkidle2";
     }): Promise<boolean>;
+    /**
+     * Scroll the page or a container by a specific amount.
+     * Uses CDP mouseWheel events (human-like, not JS scrollBy).
+     *
+     * @param direction - "up" or "down"
+     * @param amount - Pixels to scroll
+     * @param options.container - CSS selector of scroll container
+     * @param options.speed - Scroll speed 1-100 (default: 50)
+     *
+     * @example
+     * await utils.scroll("down", 500);
+     * await utils.scroll("up", 200, { container: "#chat-messages" });
+     */
+    scroll(direction: "up" | "down", amount: number, options?: {
+        container?: string;
+        speed?: number;
+    }): Promise<void>;
+    /**
+     * Scroll to the top or bottom of the page.
+     * Scrolls in segments with pauses — giống người lướt dần đến đích.
+     *
+     * @param position - "top" or "bottom"
+     * @param options.speed - Scroll speed 1-100 (default: 50)
+     *
+     * @example
+     * await utils.scrollTo("bottom");
+     * await utils.scrollTo("top");
+     */
+    scrollTo(position: "top" | "bottom", options?: {
+        speed?: number;
+    }): Promise<void>;
+    /**
+     * Scroll an element into the viewport.
+     * Scrolls in segments with pauses — không nhảy tới đích.
+     *
+     * @param selector - CSS selector or XPath of the element
+     * @param options.speed - Scroll speed 1-100 (default: 50)
+     * @returns true if element found and scrolled
+     *
+     * @example
+     * await utils.scrollToElement("#footer");
+     * await utils.scrollToElement("//button[text()='Load more']");
+     */
+    scrollToElement(selector: string, options?: {
+        speed?: number;
+    }): Promise<boolean>;
+    /**
+     * Simulate natural browsing scroll — cuộn xuống xen kẽ lướt ngược, delay random.
+     * Giống người đang đọc/lướt web tự nhiên.
+     *
+     * @param options.duration - Thời gian scroll tính bằng giây (default: 5)
+     * @param options.direction - Main direction (default: "down")
+     * @param options.backChance - Chance to scroll back 0-1 (default: 0.15)
+     * @param options.backAmount - [min, max] px to scroll back (default: [50, 150])
+     * @param options.stepSize - [min, max] px per step (default: [200, 400])
+     * @param options.stepDelay - [min, max] ms delay between steps (default: [300, 800])
+     * @param options.container - CSS selector of scroll container
+     *
+     * @example
+     * await utils.randomScroll();                     // 5s lướt xuống
+     * await utils.randomScroll({ duration: 10 });     // 10s
+     * await utils.randomScroll({ backChance: 0.3, container: "#feed" });
+     */
+    randomScroll(options?: {
+        duration?: number;
+        direction?: "down" | "up";
+        backChance?: number;
+        backAmount?: [number, number];
+        stepSize?: [number, number];
+        stepDelay?: [number, number];
+        container?: string;
+    }): Promise<void>;
     /**
      * Wait for the current page to complete a navigation (e.g. after a form submit).
      * Throws on timeout.