feat(serp): add typed SERP requests, engine-specific mappings and integration smoke tests

Author: Thordata

src/thordata/async_client.py

@@ -75,6 +75,7 @@
     ProxyUserList,
     ScraperTaskConfig,
     SerpRequest,
+    SerpTypedRequest,
     UniversalScrapeRequest,
     UsageStatistics,
     VideoTaskConfig,
@@ -275,29 +276,53 @@ async def serp_search(
         *,
         engine: Engine | str = Engine.GOOGLE,
         num: int = 10,
+        start: int = 0,
         country: str | None = None,
         language: str | None = None,
+        google_domain: str | None = None,
+        countries_filter: str | None = None,
+        languages_filter: str | None = None,
+        location: str | None = None,
+        uule: str | None = None,
         search_type: str | None = None,
+        safe_search: bool | None = None,
+        time_filter: str | None = None,
+        no_autocorrect: bool = False,
+        filter_duplicates: bool | None = None,
         device: str | None = None,
         render_js: bool | None = None,
         no_cache: bool | None = None,
         output_format: str = "json",
         ai_overview: bool = False,
+        ludocid: str | None = None,
+        kgmid: str | None = None,
         **kwargs: Any,
     ) -> dict[str, Any]:
         engine_str = engine.value if isinstance(engine, Engine) else engine.lower()
         request = SerpRequest(
             query=query,
             engine=engine_str,
             num=num,
+            start=start,
             country=country,
             language=language,
+            google_domain=google_domain,
+            countries_filter=countries_filter,
+            languages_filter=languages_filter,
+            location=location,
+            uule=uule,
             search_type=search_type,
+            safe_search=safe_search,
+            time_filter=time_filter,
+            no_autocorrect=no_autocorrect,
+            filter_duplicates=filter_duplicates,
             device=device,
             render_js=render_js,
             no_cache=no_cache,
             output_format=output_format,
             ai_overview=ai_overview,
+            ludocid=ludocid,
+            kgmid=kgmid,
             extra_params=kwargs,
         )
         return await self.serp_search_advanced(request)
@@ -328,6 +353,12 @@ async def serp_search_advanced(self, request: SerpRequest) -> dict[str, Any]:
         text = await response.text()
         return {"html": text}
 
+    async def serp_search_typed(self, request: SerpTypedRequest) -> dict[str, Any]:
+        """
+        Execute a strongly-typed SERP request (async).
+        """
+        return await self.serp_search_advanced(request.to_serp_request())
+
     async def serp_batch_search(
         self,
         requests: list[SerpRequest | dict[str, Any]],

src/thordata/client.py

@@ -89,6 +89,7 @@
     ProxyUserList,
     ScraperTaskConfig,
     SerpRequest,
+    SerpTypedRequest,
     UniversalScrapeRequest,
     UsageStatistics,
     VideoTaskConfig,
@@ -301,14 +302,26 @@ def serp_search(
         *,
         engine: Engine | str = Engine.GOOGLE,
         num: int = 10,
+        start: int = 0,
         country: str | None = None,
         language: str | None = None,
+        google_domain: str | None = None,
+        countries_filter: str | None = None,
+        languages_filter: str | None = None,
+        location: str | None = None,
+        uule: str | None = None,
         search_type: str | None = None,
+        safe_search: bool | None = None,
+        time_filter: str | None = None,
+        no_autocorrect: bool = False,
+        filter_duplicates: bool | None = None,
         device: str | None = None,
         render_js: bool | None = None,
         no_cache: bool | None = None,
         output_format: str = "json",
         ai_overview: bool = False,
+        ludocid: str | None = None,
+        kgmid: str | None = None,
         **kwargs: Any,
     ) -> dict[str, Any]:
         engine_str = engine.value if isinstance(engine, Engine) else engine.lower()
@@ -317,14 +330,26 @@ def serp_search(
             query=query,
             engine=engine_str,
             num=num,
+            start=start,
             country=country,
             language=language,
+            google_domain=google_domain,
+            countries_filter=countries_filter,
+            languages_filter=languages_filter,
+            location=location,
+            uule=uule,
             search_type=search_type,
+            safe_search=safe_search,
+            time_filter=time_filter,
+            no_autocorrect=no_autocorrect,
+            filter_duplicates=filter_duplicates,
             device=device,
             render_js=render_js,
             no_cache=no_cache,
             output_format=output_format,
             ai_overview=ai_overview,
+            ludocid=ludocid,
+            kgmid=kgmid,
             extra_params=kwargs,
         )
         return self.serp_search_advanced(request)
@@ -363,6 +388,15 @@ def serp_search_advanced(self, request: SerpRequest) -> dict[str, Any]:
 
         return {"html": response.text}
 
+    def serp_search_typed(self, request: SerpTypedRequest) -> dict[str, Any]:
+        """
+        Execute a strongly-typed SERP request.
+
+        This keeps the SDK minimal while offering better DX for engine/mode-specific
+        required parameters with upfront validation.
+        """
+        return self.serp_search_advanced(request.to_serp_request())
+
     def serp_batch_search(
         self,
         requests: list[SerpRequest | dict[str, Any]],