Centralize web manager payload building

Co-authored-by: Shri Sukhani <shrisukhani@users.noreply.github.com>

Author: cursoragent

CONTRIBUTING.md

@@ -98,7 +98,8 @@ This runs lint, format checks, compile checks, tests, and package build.
   - `tests/test_example_sync_async_parity.py` (sync/async example parity enforcement),
   - `tests/test_example_run_instructions.py` (example run-instruction consistency enforcement),
   - `tests/test_computer_action_endpoint_helper_usage.py` (computer-action endpoint-normalization helper usage enforcement),
-  - `tests/test_session_upload_helper_usage.py` (session upload-input normalization helper usage enforcement).
+  - `tests/test_session_upload_helper_usage.py` (session upload-input normalization helper usage enforcement),
+  - `tests/test_web_payload_helper_usage.py` (web manager payload-helper usage enforcement).
 
 ## Code quality conventions
 

hyperbrowser/client/managers/async_manager/web/__init__.py

@@ -6,9 +6,8 @@
     WebSearchParams,
     WebSearchResponse,
 )
-from ....schema_utils import inject_web_output_schemas
-from ...serialization_utils import serialize_model_dump_to_dict
 from ...response_utils import parse_response_model
+from ...web_payload_utils import build_web_fetch_payload, build_web_search_payload
 
 
 class WebManager:
@@ -18,13 +17,7 @@ def __init__(self, client):
         self.crawl = WebCrawlManager(client)
 
     async def fetch(self, params: FetchParams) -> FetchResponse:
-        payload = serialize_model_dump_to_dict(
-            params,
-            error_message="Failed to serialize web fetch params",
-        )
-        inject_web_output_schemas(
-            payload, params.outputs.formats if params.outputs else None
-        )
+        payload = build_web_fetch_payload(params)
 
         response = await self._client.transport.post(
             self._client._build_url("/web/fetch"),
@@ -37,10 +30,7 @@ async def fetch(self, params: FetchParams) -> FetchResponse:
         )
 
     async def search(self, params: WebSearchParams) -> WebSearchResponse:
-        payload = serialize_model_dump_to_dict(
-            params,
-            error_message="Failed to serialize web search params",
-        )
+        payload = build_web_search_payload(params)
         response = await self._client.transport.post(
             self._client._build_url("/web/search"),
             data=payload,

hyperbrowser/client/managers/sync_manager/web/__init__.py

@@ -6,9 +6,8 @@
     WebSearchParams,
     WebSearchResponse,
 )
-from ....schema_utils import inject_web_output_schemas
-from ...serialization_utils import serialize_model_dump_to_dict
 from ...response_utils import parse_response_model
+from ...web_payload_utils import build_web_fetch_payload, build_web_search_payload
 
 
 class WebManager:
@@ -18,13 +17,7 @@ def __init__(self, client):
         self.crawl = WebCrawlManager(client)
 
     def fetch(self, params: FetchParams) -> FetchResponse:
-        payload = serialize_model_dump_to_dict(
-            params,
-            error_message="Failed to serialize web fetch params",
-        )
-        inject_web_output_schemas(
-            payload, params.outputs.formats if params.outputs else None
-        )
+        payload = build_web_fetch_payload(params)
 
         response = self._client.transport.post(
             self._client._build_url("/web/fetch"),
@@ -37,10 +30,7 @@ def fetch(self, params: FetchParams) -> FetchResponse:
         )
 
     def search(self, params: WebSearchParams) -> WebSearchResponse:
-        payload = serialize_model_dump_to_dict(
-            params,
-            error_message="Failed to serialize web search params",
-        )
+        payload = build_web_search_payload(params)
         response = self._client.transport.post(
             self._client._build_url("/web/search"),
             data=payload,

hyperbrowser/client/managers/web_payload_utils.py

@@ -0,0 +1,22 @@
+from typing import Any, Dict
+
+from hyperbrowser.models import FetchParams, WebSearchParams
+
+from ..schema_utils import inject_web_output_schemas
+from .serialization_utils import serialize_model_dump_to_dict
+
+
+def build_web_fetch_payload(params: FetchParams) -> Dict[str, Any]:
+    payload = serialize_model_dump_to_dict(
+        params,
+        error_message="Failed to serialize web fetch params",
+    )
+    inject_web_output_schemas(payload, params.outputs.formats if params.outputs else None)
+    return payload
+
+
+def build_web_search_payload(params: WebSearchParams) -> Dict[str, Any]:
+    return serialize_model_dump_to_dict(
+        params,
+        error_message="Failed to serialize web search params",
+    )

tests/test_architecture_marker_usage.py

@@ -29,6 +29,7 @@
     "tests/test_example_run_instructions.py",
     "tests/test_computer_action_endpoint_helper_usage.py",
     "tests/test_session_upload_helper_usage.py",
+    "tests/test_web_payload_helper_usage.py",
 )
 
 

tests/test_web_payload_helper_usage.py

@@ -0,0 +1,20 @@
+from pathlib import Path
+
+import pytest
+
+pytestmark = pytest.mark.architecture
+
+
+WEB_MANAGER_MODULES = (
+    "hyperbrowser/client/managers/sync_manager/web/__init__.py",
+    "hyperbrowser/client/managers/async_manager/web/__init__.py",
+)
+
+
+def test_web_managers_use_shared_payload_helpers():
+    for module_path in WEB_MANAGER_MODULES:
+        module_text = Path(module_path).read_text(encoding="utf-8")
+        assert "build_web_fetch_payload(" in module_text
+        assert "build_web_search_payload(" in module_text
+        assert "inject_web_output_schemas(" not in module_text
+        assert "serialize_model_dump_to_dict(" not in module_text

tests/test_web_payload_utils.py

@@ -0,0 +1,65 @@
+import pytest
+
+import hyperbrowser.client.managers.web_payload_utils as web_payload_utils
+from hyperbrowser.exceptions import HyperbrowserError
+from hyperbrowser.models import FetchOutputOptions, FetchParams, WebSearchParams
+
+
+def test_build_web_fetch_payload_returns_serialized_payload():
+    payload = web_payload_utils.build_web_fetch_payload(
+        FetchParams(url="https://example.com")
+    )
+
+    assert payload["url"] == "https://example.com"
+
+
+def test_build_web_fetch_payload_invokes_schema_injection(monkeypatch: pytest.MonkeyPatch):
+    captured = {"payload": None, "formats": None}
+
+    def _capture(payload, formats):
+        captured["payload"] = payload
+        captured["formats"] = formats
+
+    monkeypatch.setattr(web_payload_utils, "inject_web_output_schemas", _capture)
+
+    payload = web_payload_utils.build_web_fetch_payload(
+        FetchParams(
+            url="https://example.com",
+            outputs=FetchOutputOptions(formats=["markdown"]),
+        )
+    )
+
+    assert captured["payload"] is payload
+    assert captured["formats"] == ["markdown"]
+
+
+def test_build_web_search_payload_returns_serialized_payload():
+    payload = web_payload_utils.build_web_search_payload(
+        WebSearchParams(query="hyperbrowser sdk")
+    )
+
+    assert payload["query"] == "hyperbrowser sdk"
+
+
+def test_build_web_fetch_payload_wraps_runtime_model_dump_failures():
+    class _BrokenFetchParams:
+        outputs = None
+
+        def model_dump(self, **kwargs):  # noqa: ARG002
+            raise RuntimeError("boom")
+
+    with pytest.raises(HyperbrowserError, match="Failed to serialize web fetch params") as exc_info:
+        web_payload_utils.build_web_fetch_payload(_BrokenFetchParams())  # type: ignore[arg-type]
+
+    assert isinstance(exc_info.value.original_error, RuntimeError)
+
+
+def test_build_web_search_payload_preserves_hyperbrowser_model_dump_failures():
+    class _BrokenSearchParams:
+        def model_dump(self, **kwargs):  # noqa: ARG002
+            raise HyperbrowserError("custom dump failure")
+
+    with pytest.raises(HyperbrowserError, match="custom dump failure") as exc_info:
+        web_payload_utils.build_web_search_payload(_BrokenSearchParams())  # type: ignore[arg-type]
+
+    assert exc_info.value.original_error is None