@isdk/web-fetcher 0.3.1 → 0.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (85) hide show
  1. package/README.action.cn.md +28 -4
  2. package/README.action.md +27 -4
  3. package/README.cn.md +2 -0
  4. package/README.engine.cn.md +1 -1
  5. package/README.engine.md +1 -1
  6. package/README.md +2 -0
  7. package/dist/index.d.mts +100 -2
  8. package/dist/index.d.ts +100 -2
  9. package/dist/index.js +1 -1
  10. package/dist/index.mjs +1 -1
  11. package/docs/README.md +2 -0
  12. package/docs/_media/README.action.md +27 -4
  13. package/docs/_media/README.cn.md +2 -0
  14. package/docs/_media/README.engine.md +1 -1
  15. package/docs/classes/CheerioFetchEngine.md +168 -92
  16. package/docs/classes/ClickAction.md +23 -23
  17. package/docs/classes/EvaluateAction.md +23 -23
  18. package/docs/classes/ExtractAction.md +23 -23
  19. package/docs/classes/FetchAction.md +25 -23
  20. package/docs/classes/FetchEngine.md +158 -90
  21. package/docs/classes/FetchSession.md +13 -13
  22. package/docs/classes/FillAction.md +23 -23
  23. package/docs/classes/GetContentAction.md +23 -23
  24. package/docs/classes/GotoAction.md +23 -23
  25. package/docs/classes/KeyboardPressAction.md +23 -23
  26. package/docs/classes/KeyboardTypeAction.md +23 -23
  27. package/docs/classes/MouseClickAction.md +23 -23
  28. package/docs/classes/MouseMoveAction.md +23 -23
  29. package/docs/classes/MouseWheelAction.md +533 -0
  30. package/docs/classes/PauseAction.md +23 -23
  31. package/docs/classes/PlaywrightFetchEngine.md +251 -117
  32. package/docs/classes/ScrollIntoViewAction.md +533 -0
  33. package/docs/classes/SubmitAction.md +23 -23
  34. package/docs/classes/TrimAction.md +23 -23
  35. package/docs/classes/WaitForAction.md +23 -23
  36. package/docs/classes/WebFetcher.md +5 -5
  37. package/docs/enumerations/FetchActionResultStatus.md +4 -4
  38. package/docs/functions/fetchWeb.md +2 -2
  39. package/docs/functions/getRandomDelay.md +25 -0
  40. package/docs/globals.md +5 -0
  41. package/docs/interfaces/BaseFetchActionProperties.md +12 -12
  42. package/docs/interfaces/BaseFetchCollectorActionProperties.md +16 -16
  43. package/docs/interfaces/BaseFetcherProperties.md +27 -27
  44. package/docs/interfaces/DispatchedEngineAction.md +4 -4
  45. package/docs/interfaces/EvaluateActionOptions.md +3 -3
  46. package/docs/interfaces/ExtractActionProperties.md +12 -12
  47. package/docs/interfaces/FetchActionInContext.md +15 -15
  48. package/docs/interfaces/FetchActionProperties.md +13 -13
  49. package/docs/interfaces/FetchActionResult.md +6 -6
  50. package/docs/interfaces/FetchContext.md +37 -37
  51. package/docs/interfaces/FetchEngineContext.md +32 -32
  52. package/docs/interfaces/FetchMetadata.md +5 -5
  53. package/docs/interfaces/FetchResponse.md +14 -14
  54. package/docs/interfaces/FetchReturnTypeRegistry.md +7 -7
  55. package/docs/interfaces/FetchSite.md +30 -30
  56. package/docs/interfaces/FetcherOptions.md +29 -29
  57. package/docs/interfaces/GotoActionOptions.md +7 -7
  58. package/docs/interfaces/KeyboardPressParams.md +3 -3
  59. package/docs/interfaces/KeyboardTypeParams.md +3 -3
  60. package/docs/interfaces/MouseClickParams.md +6 -6
  61. package/docs/interfaces/MouseMoveParams.md +5 -5
  62. package/docs/interfaces/MouseWheelParams.md +69 -0
  63. package/docs/interfaces/PendingEngineRequest.md +3 -3
  64. package/docs/interfaces/ScrollIntoViewParams.md +17 -0
  65. package/docs/interfaces/StorageOptions.md +5 -5
  66. package/docs/interfaces/SubmitActionOptions.md +2 -2
  67. package/docs/interfaces/TrimActionOptions.md +3 -3
  68. package/docs/interfaces/WaitForActionOptions.md +5 -5
  69. package/docs/type-aliases/BaseFetchActionOptions.md +1 -1
  70. package/docs/type-aliases/BaseFetchCollectorOptions.md +1 -1
  71. package/docs/type-aliases/BrowserEngine.md +1 -1
  72. package/docs/type-aliases/FetchActionCapabilities.md +1 -1
  73. package/docs/type-aliases/FetchActionCapabilityMode.md +1 -1
  74. package/docs/type-aliases/FetchActionOptions.md +1 -1
  75. package/docs/type-aliases/FetchEngineAction.md +2 -2
  76. package/docs/type-aliases/FetchEngineType.md +1 -1
  77. package/docs/type-aliases/FetchReturnType.md +1 -1
  78. package/docs/type-aliases/FetchReturnTypeFor.md +1 -1
  79. package/docs/type-aliases/OnFetchPauseCallback.md +1 -1
  80. package/docs/type-aliases/ResourceType.md +1 -1
  81. package/docs/type-aliases/TrimPreset.md +1 -1
  82. package/docs/variables/DefaultFetcherProperties.md +1 -1
  83. package/docs/variables/FetcherOptionKeys.md +1 -1
  84. package/docs/variables/TRIM_PRESETS.md +1 -1
  85. package/package.json +7 -7
@@ -251,8 +251,8 @@ await fetchWeb({
251
251
 
252
252
  * **`id`**: `mouseMove`
253
253
  * **`params`**:
254
- * `x` (number, 可选): 绝对 X 坐标。
255
- * `y` (number, 可选): 绝对 Y 坐标。
254
+ * `x` (number, 可选): 绝对 X 坐标。如果为负数,则被视为相对于当前位置的随机偏移。
255
+ * `y` (number, 可选): 绝对 Y 坐标。如果为负数,则被视为相对于当前位置的随机偏移。
256
256
  * `selector` (string, 可选): CSS 选择器。如果提供,鼠标将移动到该元素的中心。
257
257
  * `steps` (number, 可选): 轨迹的中间步数(默认:`-1`)。设置为 `-1` 可根据距离动态计算步数(模拟自然移动速度)。
258
258
  * **`returns`**: `none`
@@ -263,14 +263,38 @@ await fetchWeb({
263
263
 
264
264
  * **`id`**: `mouseClick`
265
265
  * **`params`**:
266
- * `x` (number, 可选): 点击的绝对 X 坐标。
267
- * `y` (number, 可选): 点击的绝对 Y 坐标。
266
+ * `x` (number, 可选): 要点击的绝对 X 坐标。如果为负数,则被视为相对于当前位置的随机偏移。
267
+ * `y` (number, 可选): 要点击的绝对 Y 坐标。如果为负数,则被视为相对于当前位置的随机偏移。
268
+
268
269
  * `selector` (string, 可选): CSS 选择器。如果提供,鼠标会先移动到该元素。
269
270
  * `button` (string, 可选): 使用的鼠标按键 (`left`, `right`, 或 `middle`)。默认为 `left`。
270
271
  * `clickCount` (number, 可选): 点击次数(例如:2 表示双击)。默认为 1。
271
272
  * `delay` (number, 可选): mousedown 和 mouseup 之间的延迟(毫秒)。
272
273
  * **`returns`**: `none`
273
274
 
275
+ #### `mouseWheel`
276
+
277
+ 模拟鼠标滚轮滚动事件。如果提供了 `selector`,元素会自动滚动到视口中,并且在滚动前将鼠标指针移动到其中心。如果提供了 `steps`,滚动增量将被拆分为多个步骤,以模拟真实的滚动行为。
278
+
279
+ * **`id`**: `mouseWheel`
280
+ * **`params`**:
281
+ * `x` (number, 可选): 滚动的绝对 X 坐标。如果为负数,则被视为相对于当前位置的随机偏移。
282
+ * `y` (number, 可选): 滚动的绝对 Y 坐标。如果为负数,则被视为相对于当前位置的随机偏移。
283
+ * `selector` (string, 可选): CSS 选择器。如果提供,则确保元素可见并先将鼠标移动到其中心。
284
+ * `deltaX` (number, 可选): 水平滚动量。默认值为 0。
285
+ * `deltaY` (number, 可选): 垂直滚动量。默认值为 0。
286
+ * `steps` (number, 可选): 将滚动拆分为多少步执行(默认值:`1`)。
287
+ * **`returns`**: `none`
288
+
289
+ #### `scrollIntoView`
290
+
291
+ 滚动页面或可滚动容器,使特定元素在视口中可见。
292
+
293
+ * **`id`**: `scrollIntoView`
294
+ * **`params`**:
295
+ * `selector` (string): 要滚动到视口可见的元素的 CSS 选择器。
296
+ * **`returns`**: `none`
297
+
274
298
  #### `keyboardType`
275
299
 
276
300
  模拟真人在当前获得焦点的元素中输入文本。
package/README.action.md CHANGED
@@ -253,8 +253,8 @@ Moves the mouse cursor to a specific coordinate or element. In `browser` mode, i
253
253
 
254
254
  * **`id`**: `mouseMove`
255
255
  * **`params`**:
256
- * `x` (number, optional): The absolute X coordinate.
257
- * `y` (number, optional): The absolute Y coordinate.
256
+ * `x` (number, optional): The absolute X coordinate. If negative, it's treated as a relative random offset from current position.
257
+ * `y` (number, optional): The absolute Y coordinate. If negative, it's treated as a relative random offset from current position.
258
258
  * `selector` (string, optional): A CSS selector. If provided, the mouse moves to the center of the element.
259
259
  * `steps` (number, optional): The number of intermediate steps for the trajectory (default: `-1`). Set to `-1` to calculate steps automatically based on distance (simulating natural speed).
260
260
  * **`returns`**: `none`
@@ -265,14 +265,37 @@ Triggers a mouse click at the current position or specified coordinates. If a `s
265
265
 
266
266
  * **`id`**: `mouseClick`
267
267
  * **`params`**:
268
- * `x` (number, optional): The absolute X coordinate to click.
269
- * `y` (number, optional): The absolute Y coordinate to click.
268
+ * `x` (number, optional): The absolute X coordinate to click. If negative, it's treated as a relative random offset from current position.
269
+ * `y` (number, optional): The absolute Y coordinate to click. If negative, it's treated as a relative random offset from current position.
270
270
  * `selector` (string, optional): A CSS selector. If provided, moves the mouse to the element first.
271
271
  * `button` (string, optional): The mouse button to use (`left`, `right`, or `middle`). Default is `left`.
272
272
  * `clickCount` (number, optional): The number of clicks (e.g., 2 for double-click). Default is 1.
273
273
  * `delay` (number, optional): Delay between mousedown and mouseup in milliseconds.
274
274
  * **`returns`**: `none`
275
275
 
276
+ #### `mouseWheel`
277
+
278
+ Simulates a mouse wheel scroll event. If a `selector` is provided, the element is automatically scrolled into view, and the cursor is moved to its center before scrolling. If `steps` is provided, the scroll delta is split into multiple steps for realistic simulation.
279
+
280
+ * **`id`**: `mouseWheel`
281
+ * **`params`**:
282
+ * `x` (number, optional): The absolute X coordinate to scroll at. If negative, it's treated as a relative random offset from current position.
283
+ * `y` (number, optional): The absolute Y coordinate to scroll at. If negative, it's treated as a relative random offset from current position.
284
+ * `selector` (string, optional): A CSS selector. If provided, ensures the element is visible and moves the mouse to its center first.
285
+ * `deltaX` (number, optional): The horizontal scroll amount. Default is 0.
286
+ * `deltaY` (number, optional): The vertical scroll amount. Default is 0.
287
+ * `steps` (number, optional): The number of steps to split the scroll into (default: `1`).
288
+ * **`returns`**: `none`
289
+
290
+ #### `scrollIntoView`
291
+
292
+ Scrolls the page or a scrollable container to make a specific element visible in the viewport.
293
+
294
+ * **`id`**: `scrollIntoView`
295
+ * **`params`**:
296
+ * `selector` (string): The CSS selector of the element to scroll into view.
297
+ * **`returns`**: `none`
298
+
276
299
  #### `keyboardType`
277
300
 
278
301
  Simulates a person typing text into the currently focused element.
package/README.cn.md CHANGED
@@ -162,6 +162,8 @@ searchGoogle('gemini');
162
162
  * `submit`: 提交表单(引擎相关)。
163
163
  * `mouseMove`: 将鼠标指针移动到指定的坐标或元素(支持贝塞尔曲线)。
164
164
  * `mouseClick`: 在当前位置或指定坐标触发鼠标点击。
165
+ * `mouseWheel`: 在目标位置模拟鼠标滚轮滚动,支持水平和垂直偏移、分步模拟以及自动将目标元素滚动到视口。
166
+ * `scrollIntoView`: 滚动页面或容器,使特定元素在视口中可见。
165
167
  * `keyboardType`: 模拟真人在当前获得焦点的元素中输入文本。
166
168
  * `keyboardPress`: 模拟按下单个按键或组合键。
167
169
  * `trim`: 从 DOM 中移除元素以清理页面(如脚本、广告、隐藏内容)。
@@ -158,7 +158,7 @@ await session.executeAll([
158
158
  * ✅ **快速轻量**:非常适合追求速度和低资源消耗的场景。
159
159
  * ✅ **符合 HTTP 标准的重定向**:正确处理 301-303 和 307/308 重定向,按照 HTTP 规范保留方法/正文或转换为 GET。
160
160
  * ❌ **无 JavaScript 执行**:无法与客户端渲染的内容交互。
161
- * ⚙️ **模拟交互**:像 `click` 和 `submit` 这样的动作是通过发起新的 HTTP 请求来模拟的。**仅浏览器支持的动作**(如 `mouseMove`, `keyboardType`)将抛出 `not_supported` 错误。
161
+ * ⚙️ **模拟交互**:像 `click` 和 `submit` 这样的动作是通过发起新的 HTTP 请求来模拟的。**仅浏览器支持的动作**(如 `mouseMove`, `mouseWheel`, `keyboardType`)将抛出 `not_supported` 错误。
162
162
  * **用例**: 抓取静态网站、服务器渲染页面或 API。
163
163
 
164
164
  ### `PlaywrightFetchEngine` (browser 模式)
package/README.engine.md CHANGED
@@ -158,7 +158,7 @@ There are two primary engine implementations:
158
158
  * ✅ **Fast and Lightweight**: Ideal for speed and low resource consumption.
159
159
  * ✅ **HTTP-Compliant Redirects**: Correctly handles 301-303 and 307/308 redirects, preserving methods/bodies or converting to GET as per HTTP specifications.
160
160
  * ❌ **No JavaScript Execution**: Cannot interact with client-side rendered content.
161
- * ⚙️ **Simulated Interaction**: Actions like `click` and `submit` are simulated by making new HTTP requests. **Browser-only actions** (e.g., `mouseMove`, `keyboardType`) will throw a `not_supported` error.
161
+ * ⚙️ **Simulated Interaction**: Actions like `click` and `submit` are simulated by making new HTTP requests. **Browser-only actions** (e.g., `mouseMove`, `mouseWheel`, `keyboardType`) will throw a `not_supported` error.
162
162
  * **Use Case**: Scraping static websites, server-rendered pages, or APIs.
163
163
 
164
164
  ### `PlaywrightFetchEngine` (browser mode)
package/README.md CHANGED
@@ -161,6 +161,8 @@ The library provides a set of powerful built-in actions, many of which are engin
161
161
  * `submit`: Submits a form (Engine-specific).
162
162
  * `mouseMove`: Moves the mouse cursor to a specific coordinate or element (Bézier curve supported).
163
163
  * `mouseClick`: Triggers a mouse click at the current position or specified coordinates.
164
+ * `mouseWheel`: Simulates a mouse wheel scroll event with horizontal and vertical deltas. Supports splitting into multiple steps and automatic scrolling to make the target element visible.
165
+ * `scrollIntoView`: Scrolls the page or a container to make a specific element visible in the viewport.
164
166
  * `keyboardType`: Simulates human-like typing into the currently focused element.
165
167
  * `keyboardPress`: Simulates pressing a single key or a key combination.
166
168
  * `trim`: Removes elements from the DOM to clean up the page.
package/dist/index.d.mts CHANGED
@@ -1219,6 +1219,17 @@ type FetchEngineAction = {
1219
1219
  button?: 'left' | 'right' | 'middle';
1220
1220
  clickCount?: number;
1221
1221
  delay?: number;
1222
+ steps?: number;
1223
+ };
1224
+ } | {
1225
+ type: 'mouseWheel';
1226
+ params: {
1227
+ x?: number;
1228
+ y?: number;
1229
+ selector?: string;
1230
+ deltaX?: number;
1231
+ deltaY?: number;
1232
+ steps?: number;
1222
1233
  };
1223
1234
  } | {
1224
1235
  type: 'keyboardType';
@@ -1232,6 +1243,11 @@ type FetchEngineAction = {
1232
1243
  key: string;
1233
1244
  delay?: number;
1234
1245
  };
1246
+ } | {
1247
+ type: 'scrollIntoView';
1248
+ params: {
1249
+ selector: string;
1250
+ };
1235
1251
  } | {
1236
1252
  type: 'waitFor';
1237
1253
  options?: WaitForActionOptions;
@@ -1608,6 +1624,27 @@ declare abstract class FetchEngine<TContext extends CrawlingContext = any, TCraw
1608
1624
  clickCount?: number;
1609
1625
  delay?: number;
1610
1626
  }): Promise<void>;
1627
+ /**
1628
+ * Scrolls the mouse wheel.
1629
+ *
1630
+ * @param params - Wheel parameters (x, y, selector, deltaX, deltaY, steps)
1631
+ */
1632
+ mouseWheel(params: {
1633
+ x?: number;
1634
+ y?: number;
1635
+ selector?: string;
1636
+ deltaX?: number;
1637
+ deltaY?: number;
1638
+ steps?: number;
1639
+ }): Promise<void>;
1640
+ /**
1641
+ * Scrolls the element into view.
1642
+ *
1643
+ * @param params - Scroll parameters (selector)
1644
+ */
1645
+ scrollIntoView(params: {
1646
+ selector: string;
1647
+ }): Promise<void>;
1611
1648
  /**
1612
1649
  * Types text into current focused element.
1613
1650
  *
@@ -1845,6 +1882,7 @@ declare abstract class FetchEngine<TContext extends CrawlingContext = any, TCraw
1845
1882
  */
1846
1883
  dispose(): Promise<void>;
1847
1884
  }
1885
+ declare function getRandomDelay(base: number, variance?: number): number;
1848
1886
 
1849
1887
  type FetchReturnType = 'response' | 'context' | 'outputs' | 'any' | 'none';
1850
1888
  interface FetchReturnTypeRegistry {
@@ -2078,7 +2116,9 @@ declare class PlaywrightFetchEngine extends FetchEngine<PlaywrightCrawlingContex
2078
2116
  x: number;
2079
2117
  y: number;
2080
2118
  };
2081
- protected _getRandomDelay(base: number, variance?: number): number;
2119
+ protected _sharedRequestHandler(context: PlaywrightCrawlingContext): Promise<void>;
2120
+ protected mouseInitialized: boolean;
2121
+ protected _initializeMousePos(page: Page): Promise<void>;
2082
2122
  protected _getTrajectory(start: {
2083
2123
  x: number;
2084
2124
  y: number;
@@ -2089,6 +2129,17 @@ declare class PlaywrightFetchEngine extends FetchEngine<PlaywrightCrawlingContex
2089
2129
  x: number;
2090
2130
  y: number;
2091
2131
  }[];
2132
+ protected _moveToPos(context: PlaywrightCrawlingContext, target: {
2133
+ x: number;
2134
+ y: number;
2135
+ }, steps?: number): Promise<{
2136
+ x: number;
2137
+ y: number;
2138
+ }>;
2139
+ protected _ensureVisible(context: PlaywrightCrawlingContext, selector: string): Promise<{
2140
+ x: number;
2141
+ y: number;
2142
+ }>;
2092
2143
  protected _moveToSelector(context: PlaywrightCrawlingContext, selector: string, steps?: number): Promise<{
2093
2144
  x: number;
2094
2145
  y: number;
@@ -2644,6 +2695,53 @@ declare class MouseClickAction extends FetchAction {
2644
2695
  };
2645
2696
  onExecute(context: FetchContext, options?: BaseFetchActionProperties): Promise<void>;
2646
2697
  }
2698
+ interface ScrollIntoViewParams {
2699
+ selector: string;
2700
+ }
2701
+ declare class ScrollIntoViewAction extends FetchAction {
2702
+ static id: string;
2703
+ static returnType: "none";
2704
+ static capabilities: {
2705
+ http: "noop";
2706
+ browser: "native";
2707
+ };
2708
+ onExecute(context: FetchContext, options?: BaseFetchActionProperties): Promise<void>;
2709
+ }
2710
+ interface MouseWheelParams {
2711
+ /**
2712
+ * Target X coordinate for the mouse wheel event.
2713
+ */
2714
+ x?: number;
2715
+ /**
2716
+ * Target Y coordinate for the mouse wheel event.
2717
+ */
2718
+ y?: number;
2719
+ /**
2720
+ * Selector for the element to scroll. If provided, mouse will move to this element before scrolling.
2721
+ */
2722
+ selector?: string;
2723
+ /**
2724
+ * Horizontal scroll delta.
2725
+ */
2726
+ deltaX?: number;
2727
+ /**
2728
+ * Vertical scroll delta.
2729
+ */
2730
+ deltaY?: number;
2731
+ /**
2732
+ * Number of steps to split the scroll into for simulating human-like behavior.
2733
+ */
2734
+ steps?: number;
2735
+ }
2736
+ declare class MouseWheelAction extends FetchAction {
2737
+ static id: string;
2738
+ static returnType: "none";
2739
+ static capabilities: {
2740
+ http: "noop";
2741
+ browser: "native";
2742
+ };
2743
+ onExecute(context: FetchContext, options?: BaseFetchActionProperties): Promise<void>;
2744
+ }
2647
2745
 
2648
2746
  interface KeyboardTypeParams {
2649
2747
  text: string;
@@ -2681,4 +2779,4 @@ declare function fetchWeb(url: string, options?: FetcherOptions): Promise<{
2681
2779
  outputs: Record<string, any>;
2682
2780
  }>;
2683
2781
 
2684
- export { type BaseFetchActionOptions, type BaseFetchActionProperties, type BaseFetchCollectorActionProperties, type BaseFetchCollectorOptions, type BaseFetcherProperties, type BrowserEngine, CheerioFetchEngine, ClickAction, DefaultFetcherProperties, type DispatchedEngineAction, EvaluateAction, type EvaluateActionOptions, ExtractAction, type ExtractActionProperties, FetchAction, type FetchActionCapabilities, type FetchActionCapabilityMode, type FetchActionInContext, type FetchActionOptions, type FetchActionProperties, type FetchActionResult, FetchActionResultStatus, type FetchContext, FetchEngine, type FetchEngineAction, type FetchEngineContext, type FetchEngineType, type FetchMetadata, type FetchResponse, type FetchReturnType, type FetchReturnTypeFor, type FetchReturnTypeRegistry, FetchSession, type FetchSite, FetcherOptionKeys, type FetcherOptions, FillAction, GetContentAction, GotoAction, type GotoActionOptions, KeyboardPressAction, type KeyboardPressParams, KeyboardTypeAction, type KeyboardTypeParams, MouseClickAction, type MouseClickParams, MouseMoveAction, type MouseMoveParams, type OnFetchPauseCallback, PauseAction, type PendingEngineRequest, PlaywrightFetchEngine, type ResourceType, type StorageOptions, SubmitAction, type SubmitActionOptions, TRIM_PRESETS, TrimAction, type TrimActionOptions, type TrimPreset, WaitForAction, type WaitForActionOptions, WebFetcher, fetchWeb };
2782
+ export { type BaseFetchActionOptions, type BaseFetchActionProperties, type BaseFetchCollectorActionProperties, type BaseFetchCollectorOptions, type BaseFetcherProperties, type BrowserEngine, CheerioFetchEngine, ClickAction, DefaultFetcherProperties, type DispatchedEngineAction, EvaluateAction, type EvaluateActionOptions, ExtractAction, type ExtractActionProperties, FetchAction, type FetchActionCapabilities, type FetchActionCapabilityMode, type FetchActionInContext, type FetchActionOptions, type FetchActionProperties, type FetchActionResult, FetchActionResultStatus, type FetchContext, FetchEngine, type FetchEngineAction, type FetchEngineContext, type FetchEngineType, type FetchMetadata, type FetchResponse, type FetchReturnType, type FetchReturnTypeFor, type FetchReturnTypeRegistry, FetchSession, type FetchSite, FetcherOptionKeys, type FetcherOptions, FillAction, GetContentAction, GotoAction, type GotoActionOptions, KeyboardPressAction, type KeyboardPressParams, KeyboardTypeAction, type KeyboardTypeParams, MouseClickAction, type MouseClickParams, MouseMoveAction, type MouseMoveParams, MouseWheelAction, type MouseWheelParams, type OnFetchPauseCallback, PauseAction, type PendingEngineRequest, PlaywrightFetchEngine, type ResourceType, ScrollIntoViewAction, type ScrollIntoViewParams, type StorageOptions, SubmitAction, type SubmitActionOptions, TRIM_PRESETS, TrimAction, type TrimActionOptions, type TrimPreset, WaitForAction, type WaitForActionOptions, WebFetcher, fetchWeb, getRandomDelay };
package/dist/index.d.ts CHANGED
@@ -1219,6 +1219,17 @@ type FetchEngineAction = {
1219
1219
  button?: 'left' | 'right' | 'middle';
1220
1220
  clickCount?: number;
1221
1221
  delay?: number;
1222
+ steps?: number;
1223
+ };
1224
+ } | {
1225
+ type: 'mouseWheel';
1226
+ params: {
1227
+ x?: number;
1228
+ y?: number;
1229
+ selector?: string;
1230
+ deltaX?: number;
1231
+ deltaY?: number;
1232
+ steps?: number;
1222
1233
  };
1223
1234
  } | {
1224
1235
  type: 'keyboardType';
@@ -1232,6 +1243,11 @@ type FetchEngineAction = {
1232
1243
  key: string;
1233
1244
  delay?: number;
1234
1245
  };
1246
+ } | {
1247
+ type: 'scrollIntoView';
1248
+ params: {
1249
+ selector: string;
1250
+ };
1235
1251
  } | {
1236
1252
  type: 'waitFor';
1237
1253
  options?: WaitForActionOptions;
@@ -1608,6 +1624,27 @@ declare abstract class FetchEngine<TContext extends CrawlingContext = any, TCraw
1608
1624
  clickCount?: number;
1609
1625
  delay?: number;
1610
1626
  }): Promise<void>;
1627
+ /**
1628
+ * Scrolls the mouse wheel.
1629
+ *
1630
+ * @param params - Wheel parameters (x, y, selector, deltaX, deltaY, steps)
1631
+ */
1632
+ mouseWheel(params: {
1633
+ x?: number;
1634
+ y?: number;
1635
+ selector?: string;
1636
+ deltaX?: number;
1637
+ deltaY?: number;
1638
+ steps?: number;
1639
+ }): Promise<void>;
1640
+ /**
1641
+ * Scrolls the element into view.
1642
+ *
1643
+ * @param params - Scroll parameters (selector)
1644
+ */
1645
+ scrollIntoView(params: {
1646
+ selector: string;
1647
+ }): Promise<void>;
1611
1648
  /**
1612
1649
  * Types text into current focused element.
1613
1650
  *
@@ -1845,6 +1882,7 @@ declare abstract class FetchEngine<TContext extends CrawlingContext = any, TCraw
1845
1882
  */
1846
1883
  dispose(): Promise<void>;
1847
1884
  }
1885
+ declare function getRandomDelay(base: number, variance?: number): number;
1848
1886
 
1849
1887
  type FetchReturnType = 'response' | 'context' | 'outputs' | 'any' | 'none';
1850
1888
  interface FetchReturnTypeRegistry {
@@ -2078,7 +2116,9 @@ declare class PlaywrightFetchEngine extends FetchEngine<PlaywrightCrawlingContex
2078
2116
  x: number;
2079
2117
  y: number;
2080
2118
  };
2081
- protected _getRandomDelay(base: number, variance?: number): number;
2119
+ protected _sharedRequestHandler(context: PlaywrightCrawlingContext): Promise<void>;
2120
+ protected mouseInitialized: boolean;
2121
+ protected _initializeMousePos(page: Page): Promise<void>;
2082
2122
  protected _getTrajectory(start: {
2083
2123
  x: number;
2084
2124
  y: number;
@@ -2089,6 +2129,17 @@ declare class PlaywrightFetchEngine extends FetchEngine<PlaywrightCrawlingContex
2089
2129
  x: number;
2090
2130
  y: number;
2091
2131
  }[];
2132
+ protected _moveToPos(context: PlaywrightCrawlingContext, target: {
2133
+ x: number;
2134
+ y: number;
2135
+ }, steps?: number): Promise<{
2136
+ x: number;
2137
+ y: number;
2138
+ }>;
2139
+ protected _ensureVisible(context: PlaywrightCrawlingContext, selector: string): Promise<{
2140
+ x: number;
2141
+ y: number;
2142
+ }>;
2092
2143
  protected _moveToSelector(context: PlaywrightCrawlingContext, selector: string, steps?: number): Promise<{
2093
2144
  x: number;
2094
2145
  y: number;
@@ -2644,6 +2695,53 @@ declare class MouseClickAction extends FetchAction {
2644
2695
  };
2645
2696
  onExecute(context: FetchContext, options?: BaseFetchActionProperties): Promise<void>;
2646
2697
  }
2698
+ interface ScrollIntoViewParams {
2699
+ selector: string;
2700
+ }
2701
+ declare class ScrollIntoViewAction extends FetchAction {
2702
+ static id: string;
2703
+ static returnType: "none";
2704
+ static capabilities: {
2705
+ http: "noop";
2706
+ browser: "native";
2707
+ };
2708
+ onExecute(context: FetchContext, options?: BaseFetchActionProperties): Promise<void>;
2709
+ }
2710
+ interface MouseWheelParams {
2711
+ /**
2712
+ * Target X coordinate for the mouse wheel event.
2713
+ */
2714
+ x?: number;
2715
+ /**
2716
+ * Target Y coordinate for the mouse wheel event.
2717
+ */
2718
+ y?: number;
2719
+ /**
2720
+ * Selector for the element to scroll. If provided, mouse will move to this element before scrolling.
2721
+ */
2722
+ selector?: string;
2723
+ /**
2724
+ * Horizontal scroll delta.
2725
+ */
2726
+ deltaX?: number;
2727
+ /**
2728
+ * Vertical scroll delta.
2729
+ */
2730
+ deltaY?: number;
2731
+ /**
2732
+ * Number of steps to split the scroll into for simulating human-like behavior.
2733
+ */
2734
+ steps?: number;
2735
+ }
2736
+ declare class MouseWheelAction extends FetchAction {
2737
+ static id: string;
2738
+ static returnType: "none";
2739
+ static capabilities: {
2740
+ http: "noop";
2741
+ browser: "native";
2742
+ };
2743
+ onExecute(context: FetchContext, options?: BaseFetchActionProperties): Promise<void>;
2744
+ }
2647
2745
 
2648
2746
  interface KeyboardTypeParams {
2649
2747
  text: string;
@@ -2681,4 +2779,4 @@ declare function fetchWeb(url: string, options?: FetcherOptions): Promise<{
2681
2779
  outputs: Record<string, any>;
2682
2780
  }>;
2683
2781
 
2684
- export { type BaseFetchActionOptions, type BaseFetchActionProperties, type BaseFetchCollectorActionProperties, type BaseFetchCollectorOptions, type BaseFetcherProperties, type BrowserEngine, CheerioFetchEngine, ClickAction, DefaultFetcherProperties, type DispatchedEngineAction, EvaluateAction, type EvaluateActionOptions, ExtractAction, type ExtractActionProperties, FetchAction, type FetchActionCapabilities, type FetchActionCapabilityMode, type FetchActionInContext, type FetchActionOptions, type FetchActionProperties, type FetchActionResult, FetchActionResultStatus, type FetchContext, FetchEngine, type FetchEngineAction, type FetchEngineContext, type FetchEngineType, type FetchMetadata, type FetchResponse, type FetchReturnType, type FetchReturnTypeFor, type FetchReturnTypeRegistry, FetchSession, type FetchSite, FetcherOptionKeys, type FetcherOptions, FillAction, GetContentAction, GotoAction, type GotoActionOptions, KeyboardPressAction, type KeyboardPressParams, KeyboardTypeAction, type KeyboardTypeParams, MouseClickAction, type MouseClickParams, MouseMoveAction, type MouseMoveParams, type OnFetchPauseCallback, PauseAction, type PendingEngineRequest, PlaywrightFetchEngine, type ResourceType, type StorageOptions, SubmitAction, type SubmitActionOptions, TRIM_PRESETS, TrimAction, type TrimActionOptions, type TrimPreset, WaitForAction, type WaitForActionOptions, WebFetcher, fetchWeb };
2782
+ export { type BaseFetchActionOptions, type BaseFetchActionProperties, type BaseFetchCollectorActionProperties, type BaseFetchCollectorOptions, type BaseFetcherProperties, type BrowserEngine, CheerioFetchEngine, ClickAction, DefaultFetcherProperties, type DispatchedEngineAction, EvaluateAction, type EvaluateActionOptions, ExtractAction, type ExtractActionProperties, FetchAction, type FetchActionCapabilities, type FetchActionCapabilityMode, type FetchActionInContext, type FetchActionOptions, type FetchActionProperties, type FetchActionResult, FetchActionResultStatus, type FetchContext, FetchEngine, type FetchEngineAction, type FetchEngineContext, type FetchEngineType, type FetchMetadata, type FetchResponse, type FetchReturnType, type FetchReturnTypeFor, type FetchReturnTypeRegistry, FetchSession, type FetchSite, FetcherOptionKeys, type FetcherOptions, FillAction, GetContentAction, GotoAction, type GotoActionOptions, KeyboardPressAction, type KeyboardPressParams, KeyboardTypeAction, type KeyboardTypeParams, MouseClickAction, type MouseClickParams, MouseMoveAction, type MouseMoveParams, MouseWheelAction, type MouseWheelParams, type OnFetchPauseCallback, PauseAction, type PendingEngineRequest, PlaywrightFetchEngine, type ResourceType, ScrollIntoViewAction, type ScrollIntoViewParams, type StorageOptions, SubmitAction, type SubmitActionOptions, TRIM_PRESETS, TrimAction, type TrimActionOptions, type TrimPreset, WaitForAction, type WaitForActionOptions, WebFetcher, fetchWeb, getRandomDelay };