feat: replace stealth/render_js booleans with FetchMode enum in FetchConfig

Align FetchConfig with the v2 API schema. Instead of separate `stealth`
and `render_js` boolean fields, use a single `mode` enum with values:
auto, fast, js, direct+stealth, js+stealth. Also rename `wait_ms` to
`wait` and add `timeout` field to match the API contract.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: VinciGit00

examples/crawl_with_fetch_config_example.py

@@ -1,7 +1,7 @@
 """
 Crawl with custom fetch configuration.
 
-Use FetchConfig to enable stealth mode, JS rendering, etc. for all
+Use FetchConfig to set the fetch mode, wait time, etc. for all
 pages during the crawl.
 """
 
@@ -17,9 +17,8 @@
     max_pages=10,
     format="html",
     fetch_config=FetchConfig(
-        stealth=True,
-        render_js=True,
-        wait_ms=1000,
+        mode="js",
+        wait=1000,
     ),
 )
 print("Crawl started:", json.dumps(job, indent=2))

examples/extract_with_fetch_config_example.py

@@ -1,7 +1,7 @@
 """
 Extract data from a JavaScript-heavy page using FetchConfig.
 
-Use FetchConfig to enable stealth mode, JS rendering, scrolling,
+Use FetchConfig to set the fetch mode, wait time, scrolling,
 and other options needed for dynamic pages.
 """
 
@@ -15,9 +15,8 @@
     url="https://example.com",
     prompt="Extract all visible text content",
     fetch_config=FetchConfig(
-        stealth=True,
-        render_js=True,
-        wait_ms=2000,
+        mode="js+stealth",
+        wait=2000,
         scrolls=3,
     ),
 )

examples/monitor_with_config_example.py

@@ -14,9 +14,8 @@
     prompt="Extract the top 5 news headlines with their dates",
     cron="0 */6 * * *",  # Every 6 hours
     fetch_config=FetchConfig(
-        stealth=True,
-        render_js=True,
-        wait_ms=2000,
+        mode="js+stealth",
+        wait=2000,
     ),
     llm_config=LlmConfig(
         temperature=0.1,

examples/scrape_with_fetch_config_example.py

@@ -1,8 +1,15 @@
 """
 Scrape a webpage with custom fetch configuration.
 
-FetchConfig allows you to control stealth mode, JavaScript rendering,
+FetchConfig allows you to control the fetch mode (proxy strategy),
 wait times, cookies, headers, country-based geolocation, and more.
+
+Available modes:
+  - auto: Automatically selects the best provider chain (default)
+  - fast: Direct HTTP fetch, fastest option, no JS rendering
+  - js: Headless browser rendering for JavaScript-heavy pages
+  - direct+stealth: Residential proxy with stealth headers (no JS)
+  - js+stealth: JS rendering combined with stealth/residential proxy
 """
 
 import json
@@ -15,9 +22,8 @@
     "https://example.com",
     format="markdown",
     fetch_config=FetchConfig(
-        stealth=True,
-        render_js=True,
-        wait_ms=3000,
+        mode="js+stealth",
+        wait=3000,
         headers={"User-Agent": "MyBot/1.0"},
         cookies={"session": "abc123"},
         country="us",

scrapegraph-py/MIGRATION_V2.md

@@ -97,12 +97,11 @@ response = client.extract(
     prompt="Extract the main heading and description",
     output_schema=MyPydanticModel,
     fetch_config=FetchConfig(
+        mode="js+stealth",
         headers={"User-Agent": "MyBot"},
         cookies={"session": "abc123"},
         scrolls=3,
-        render_js=True,
-        stealth=True,
-        wait_ms=2000,
+        wait=2000,
     ),
 )
 ```
@@ -115,9 +114,9 @@ response = client.extract(
 | `headers` | `fetch_config=FetchConfig(headers=...)` |
 | `cookies` | `fetch_config=FetchConfig(cookies=...)` |
 | `number_of_scrolls` | `fetch_config=FetchConfig(scrolls=...)` |
-| `render_heavy_js` | `fetch_config=FetchConfig(render_js=...)` |
-| `stealth` | `fetch_config=FetchConfig(stealth=...)` |
-| `wait_ms` | `fetch_config=FetchConfig(wait_ms=...)` |
+| `render_heavy_js` | `fetch_config=FetchConfig(mode="js")` or `mode="js+stealth"` |
+| `stealth` | `fetch_config=FetchConfig(mode="direct+stealth")` or `mode="js+stealth"` |
+| `wait_ms` | `fetch_config=FetchConfig(wait=...)` |
 | `mock` | Removed |
 | `plain_text` | Removed |
 | `total_pages` | Removed |
@@ -163,7 +162,7 @@ response = client.search(
 | `num_results` | `num_results` (unchanged) |
 | `output_schema` | `output_schema` (unchanged) |
 | `extraction_mode` | Removed (always AI extraction) |
-| `stealth` | Removed |
+| `stealth` | Removed (use `fetch_config=FetchConfig(mode=...)` on other endpoints) |
 | `location_geo_code` | Removed |
 | `time_range` | Removed |
 | `mock` | Removed |
@@ -211,9 +210,8 @@ response = client.scrape(
     "https://example.com",
     format="markdown",
     fetch_config=FetchConfig(
-        render_js=True,
-        stealth=True,
-        wait_ms=2000,
+        mode="js+stealth",
+        wait=2000,
         headers={"User-Agent": "MyBot"},
     ),
 )
@@ -222,11 +220,11 @@ response = client.scrape(
 | v1 parameter | v2 equivalent |
 |---|---|
 | `website_url` | `url` (positional) |
-| `render_heavy_js` | `fetch_config=FetchConfig(render_js=...)` |
+| `render_heavy_js` | `fetch_config=FetchConfig(mode="js")` or `mode="js+stealth"` |
 | `branding` | `format="branding"` |
 | `headers` | `fetch_config=FetchConfig(headers=...)` |
-| `stealth` | `fetch_config=FetchConfig(stealth=...)` |
-| `wait_ms` | `fetch_config=FetchConfig(wait_ms=...)` |
+| `stealth` | `fetch_config=FetchConfig(mode="direct+stealth")` or `mode="js+stealth"` |
+| `wait_ms` | `fetch_config=FetchConfig(wait=...)` |
 | `mock` | Removed |
 | `return_toon` | Removed |
 
@@ -254,7 +252,7 @@ response = client.markdownify(
 response = client.scrape(
     "https://example.com",
     format="markdown",
-    fetch_config=FetchConfig(render_js=True, stealth=True),
+    fetch_config=FetchConfig(mode="js+stealth"),
 )
 ```
 
@@ -305,9 +303,8 @@ response = client.crawl.start(
     include_patterns=["/blog/*"],
     exclude_patterns=["/admin/*"],
     fetch_config=FetchConfig(
-        render_js=True,
-        stealth=True,
-        wait_ms=1000,
+        mode="js+stealth",
+        wait=1000,
         headers={"User-Agent": "MyBot"},
     ),
 )
@@ -332,7 +329,7 @@ client.crawl.resume(crawl_id)
 | `max_pages` | `max_pages` (unchanged) |
 | `include_paths` | `include_patterns` |
 | `exclude_paths` | `exclude_patterns` |
-| `headers`, `stealth`, `render_heavy_js`, `wait_ms` | Moved to `fetch_config=FetchConfig(...)` |
+| `headers`, `stealth`, `render_heavy_js`, `wait_ms` | Moved to `fetch_config=FetchConfig(mode=..., wait=..., headers=...)` |
 | `same_domain_only` | Removed |
 | `batch_size` | Removed |
 | `sitemap` | Removed |
@@ -402,7 +399,7 @@ monitor = client.monitor.create(
     prompt="Extract company info",
     cron="0 9 * * *",
     output_schema={"type": "object", "properties": {"name": {"type": "string"}}},
-    fetch_config=FetchConfig(stealth=True),
+    fetch_config=FetchConfig(mode="direct+stealth"),
     llm_config=LlmConfig(temperature=0.1),
 )
 
@@ -530,17 +527,27 @@ Controls how pages are fetched. Used by `scrape()`, `extract()`, `crawl.start()`
 from scrapegraph_py import FetchConfig
 
 config = FetchConfig(
-    mock=False,          # Use mock mode for testing
-    stealth=True,        # Avoid bot detection
-    scrolls=3,           # Number of page scrolls (0-100)
-    country="us",        # Geo-located requests
-    cookies={"k": "v"},  # Cookies to send
+    mode="js+stealth",   # Fetch mode: auto, fast, js, direct+stealth, js+stealth
+    timeout=30000,       # Request timeout in ms (1000-60000)
+    wait=2000,           # Wait after page load in ms (0-30000)
     headers={"k": "v"},  # Custom HTTP headers
-    wait_ms=2000,        # Wait before scraping (ms)
-    render_js=True,      # Render heavy JavaScript
+    cookies={"k": "v"},  # Cookies to send
+    country="us",        # Two-letter country code for geo-located requests
+    scrolls=3,           # Number of page scrolls (0-100)
+    mock=False,          # Use mock mode for testing
 )
 ```
 
+**Available fetch modes:**
+
+| Mode | Description |
+|---|---|
+| `auto` | Automatically selects the best provider chain (default) |
+| `fast` | Direct HTTP fetch via impit — fastest, no JS rendering |
+| `js` | Headless browser rendering for JavaScript-heavy pages |
+| `direct+stealth` | Residential proxy with stealth headers, no JS |
+| `js+stealth` | JS rendering combined with stealth/residential proxy |
+
 ### LlmConfig
 
 Controls the AI model used for extraction. Used by `extract()`, `search()`, and `monitor.create()`.
@@ -639,7 +646,7 @@ For a fast migration, search your codebase for these patterns:
 | `client.replace_scheduled_job(` | Remove |
 | `client.get_job_executions(` | Remove |
 | `return_toon=True` | Remove |
-| `render_heavy_js=` | `fetch_config=FetchConfig(render_js=...)` |
+| `render_heavy_js=` | `fetch_config=FetchConfig(mode="js")` or `mode="js+stealth"` |
 | `from scrapegraph_py.models.smartscraper import` | Remove |
 | `from scrapegraph_py.models.searchscraper import` | Remove |
 | `from scrapegraph_py.models.markdownify import` | Remove |

scrapegraph-py/scrapegraph_py/__init__.py

@@ -32,7 +32,7 @@
 from .models.monitor import MonitorCreateRequest
 from .models.scrape import ScrapeFormat, ScrapeRequest
 from .models.search import SearchRequest
-from .models.shared import FetchConfig, LlmConfig
+from .models.shared import FetchConfig, FetchMode, LlmConfig
 
 __version__ = VERSION
 
@@ -41,6 +41,7 @@
     "AsyncClient",
     # Shared config
     "FetchConfig",
+    "FetchMode",
     "LlmConfig",
     # Scrape
     "ScrapeFormat",

scrapegraph-py/scrapegraph_py/models/__init__.py

@@ -8,11 +8,12 @@
 from .monitor import MonitorCreateRequest
 from .scrape import GetScrapeRequest, ScrapeFormat, ScrapeRequest
 from .search import SearchRequest
-from .shared import FetchConfig, LlmConfig
+from .shared import FetchConfig, FetchMode, LlmConfig
 
 __all__ = [
     # Shared
     "FetchConfig",
+    "FetchMode",
     "LlmConfig",
     # Scrape
     "ScrapeFormat",

scrapegraph-py/scrapegraph_py/models/shared.py

@@ -4,38 +4,61 @@
 These models are used across multiple endpoints for fetch and LLM configuration.
 """
 
+from enum import Enum
 from typing import Any, Dict, Optional
 
 from pydantic import BaseModel, Field
 
 
+class FetchMode(str, Enum):
+    """Fetch/proxy mode controlling how pages are retrieved.
+
+    - AUTO: Automatically selects the best provider chain.
+    - FAST: Direct HTTP fetch via impit (fastest, no JS).
+    - JS: Headless browser rendering for JavaScript-heavy pages.
+    - DIRECT_STEALTH: Residential proxy with stealth headers (no JS).
+    - JS_STEALTH: JS rendering combined with stealth/residential proxy.
+    """
+
+    AUTO = "auto"
+    FAST = "fast"
+    JS = "js"
+    DIRECT_STEALTH = "direct+stealth"
+    JS_STEALTH = "js+stealth"
+
+
 class FetchConfig(BaseModel):
     """Configuration for how pages are fetched."""
 
-    mock: bool = Field(default=False, description="Use mock mode for testing")
-    stealth: bool = Field(
-        default=False, description="Enable stealth mode to avoid bot detection"
-    )
-    scrolls: Optional[int] = Field(
-        default=None, ge=0, le=100, description="Number of scrolls to perform (0-100)"
+    mode: FetchMode = Field(
+        default=FetchMode.AUTO,
+        description="Fetch/proxy mode: 'auto', 'fast', 'js', 'direct+stealth', 'js+stealth'",
     )
-    country: Optional[str] = Field(
-        default=None, description="Country code for geo-located requests (e.g. 'us')"
+    timeout: Optional[int] = Field(
+        default=None,
+        ge=1000,
+        le=60000,
+        description="Request timeout in milliseconds (1000-60000)",
     )
-    cookies: Optional[Dict[str, str]] = Field(
-        default=None, description="Cookies to send with the request"
+    wait: Optional[int] = Field(
+        default=None,
+        ge=0,
+        le=30000,
+        description="Milliseconds to wait after page load before scraping (0-30000)",
     )
     headers: Optional[Dict[str, str]] = Field(
         default=None, description="Custom HTTP headers to send with the request"
     )
-    wait_ms: Optional[int] = Field(
-        default=None,
-        ge=0,
-        description="Milliseconds to wait before scraping for JS rendering",
+    cookies: Optional[Dict[str, str]] = Field(
+        default=None, description="Cookies to send with the request"
     )
-    render_js: bool = Field(
-        default=False, description="Whether to render heavy JavaScript"
+    country: Optional[str] = Field(
+        default=None, description="Two-letter country code for geo-located requests (e.g. 'us')"
     )
+    scrolls: Optional[int] = Field(
+        default=None, ge=0, le=100, description="Number of scrolls to perform (0-100)"
+    )
+    mock: bool = Field(default=False, description="Use mock mode for testing")
 
     def model_dump(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
         kwargs.setdefault("exclude_none", True)

scrapegraph-py/tests/test_models.py

@@ -8,7 +8,7 @@
 from scrapegraph_py.models.monitor import MonitorCreateRequest
 from scrapegraph_py.models.scrape import ScrapeFormat, ScrapeRequest
 from scrapegraph_py.models.search import SearchRequest
-from scrapegraph_py.models.shared import FetchConfig, LlmConfig
+from scrapegraph_py.models.shared import FetchConfig, FetchMode, LlmConfig
 
 # ------------------------------------------------------------------
 # Shared models
@@ -18,15 +18,25 @@
 def test_fetch_config_defaults():
     config = FetchConfig()
     assert config.mock is False
-    assert config.stealth is False
-    assert config.render_js is False
+    assert config.mode == FetchMode.AUTO
 
 
 def test_fetch_config_excludes_none():
-    config = FetchConfig(stealth=True)
+    config = FetchConfig(mode="fast")
     data = config.model_dump()
     assert "cookies" not in data
-    assert data["stealth"] is True
+    assert data["mode"] == "fast"
+
+
+def test_fetch_config_all_modes():
+    for mode in FetchMode:
+        config = FetchConfig(mode=mode)
+        assert config.mode == mode
+
+
+def test_fetch_config_invalid_mode():
+    with pytest.raises(ValueError):
+        FetchConfig(mode="invalid")
 
 
 def test_llm_config_excludes_none():