Centralize web fetch and search manager metadata

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

Author: cursoragent

CONTRIBUTING.md

@@ -144,6 +144,7 @@ This runs lint, format checks, compile checks, tests, and package build.
   - `tests/test_team_route_constants_usage.py` (team manager route-constant usage enforcement),
   - `tests/test_tool_mapping_reader_usage.py` (tools mapping-helper usage),
   - `tests/test_type_utils_usage.py` (type `__mro__` boundary centralization in `hyperbrowser/type_utils.py`),
+  - `tests/test_web_fetch_search_usage.py` (web fetch/search manager shared route/metadata/request-helper usage enforcement),
   - `tests/test_web_operation_metadata_usage.py` (web manager operation-metadata usage enforcement),
   - `tests/test_web_pagination_internal_reuse.py` (web pagination helper internal reuse of shared job pagination helpers),
   - `tests/test_web_payload_helper_usage.py` (web manager payload-helper usage enforcement),

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

@@ -6,37 +6,38 @@
     WebSearchParams,
     WebSearchResponse,
 )
-from ...response_utils import parse_response_model
+from ...web_operation_metadata import WEB_REQUEST_OPERATION_METADATA
 from ...web_payload_utils import build_web_fetch_payload, build_web_search_payload
+from ...web_request_utils import start_web_job_async
+from ...web_route_constants import WEB_FETCH_ROUTE_PATH, WEB_SEARCH_ROUTE_PATH
 
 
 class WebManager:
+    _OPERATION_METADATA = WEB_REQUEST_OPERATION_METADATA
+    _FETCH_ROUTE_PATH = WEB_FETCH_ROUTE_PATH
+    _SEARCH_ROUTE_PATH = WEB_SEARCH_ROUTE_PATH
+
     def __init__(self, client):
         self._client = client
         self.batch_fetch = BatchFetchManager(client)
         self.crawl = WebCrawlManager(client)
 
     async def fetch(self, params: FetchParams) -> FetchResponse:
         payload = build_web_fetch_payload(params)
-
-        response = await self._client.transport.post(
-            self._client._build_url("/web/fetch"),
-            data=payload,
-        )
-        return parse_response_model(
-            response.data,
+        return await start_web_job_async(
+            client=self._client,
+            route_prefix=self._FETCH_ROUTE_PATH,
+            payload=payload,
             model=FetchResponse,
-            operation_name="web fetch",
+            operation_name=self._OPERATION_METADATA.fetch_operation_name,
         )
 
     async def search(self, params: WebSearchParams) -> WebSearchResponse:
         payload = build_web_search_payload(params)
-        response = await self._client.transport.post(
-            self._client._build_url("/web/search"),
-            data=payload,
-        )
-        return parse_response_model(
-            response.data,
+        return await start_web_job_async(
+            client=self._client,
+            route_prefix=self._SEARCH_ROUTE_PATH,
+            payload=payload,
             model=WebSearchResponse,
-            operation_name="web search",
+            operation_name=self._OPERATION_METADATA.search_operation_name,
         )

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

@@ -6,37 +6,38 @@
     WebSearchParams,
     WebSearchResponse,
 )
-from ...response_utils import parse_response_model
+from ...web_operation_metadata import WEB_REQUEST_OPERATION_METADATA
 from ...web_payload_utils import build_web_fetch_payload, build_web_search_payload
+from ...web_request_utils import start_web_job
+from ...web_route_constants import WEB_FETCH_ROUTE_PATH, WEB_SEARCH_ROUTE_PATH
 
 
 class WebManager:
+    _OPERATION_METADATA = WEB_REQUEST_OPERATION_METADATA
+    _FETCH_ROUTE_PATH = WEB_FETCH_ROUTE_PATH
+    _SEARCH_ROUTE_PATH = WEB_SEARCH_ROUTE_PATH
+
     def __init__(self, client):
         self._client = client
         self.batch_fetch = BatchFetchManager(client)
         self.crawl = WebCrawlManager(client)
 
     def fetch(self, params: FetchParams) -> FetchResponse:
         payload = build_web_fetch_payload(params)
-
-        response = self._client.transport.post(
-            self._client._build_url("/web/fetch"),
-            data=payload,
-        )
-        return parse_response_model(
-            response.data,
+        return start_web_job(
+            client=self._client,
+            route_prefix=self._FETCH_ROUTE_PATH,
+            payload=payload,
             model=FetchResponse,
-            operation_name="web fetch",
+            operation_name=self._OPERATION_METADATA.fetch_operation_name,
         )
 
     def search(self, params: WebSearchParams) -> WebSearchResponse:
         payload = build_web_search_payload(params)
-        response = self._client.transport.post(
-            self._client._build_url("/web/search"),
-            data=payload,
-        )
-        return parse_response_model(
-            response.data,
+        return start_web_job(
+            client=self._client,
+            route_prefix=self._SEARCH_ROUTE_PATH,
+            payload=payload,
             model=WebSearchResponse,
-            operation_name="web search",
+            operation_name=self._OPERATION_METADATA.search_operation_name,
         )

hyperbrowser/client/managers/web_operation_metadata.py

@@ -10,6 +10,12 @@ class WebOperationMetadata:
     operation_name_prefix: str
 
 
+@dataclass(frozen=True)
+class WebRequestOperationMetadata:
+    fetch_operation_name: str
+    search_operation_name: str
+
+
 BATCH_FETCH_OPERATION_METADATA = WebOperationMetadata(
     start_operation_name="batch fetch start",
     status_operation_name="batch fetch status",
@@ -25,3 +31,8 @@ class WebOperationMetadata:
     start_error_message="Failed to start web crawl job",
     operation_name_prefix="web crawl job ",
 )
+
+WEB_REQUEST_OPERATION_METADATA = WebRequestOperationMetadata(
+    fetch_operation_name="web fetch",
+    search_operation_name="web search",
+)

hyperbrowser/client/managers/web_route_constants.py

@@ -1,2 +1,4 @@
 BATCH_FETCH_JOB_ROUTE_PREFIX = "/web/batch-fetch"
 WEB_CRAWL_JOB_ROUTE_PREFIX = "/web/crawl"
+WEB_FETCH_ROUTE_PATH = "/web/fetch"
+WEB_SEARCH_ROUTE_PATH = "/web/search"

tests/test_architecture_marker_usage.py

@@ -77,6 +77,7 @@
     "tests/test_web_operation_metadata_usage.py",
     "tests/test_web_pagination_internal_reuse.py",
     "tests/test_web_payload_helper_usage.py",
+    "tests/test_web_fetch_search_usage.py",
     "tests/test_web_request_helper_usage.py",
     "tests/test_web_route_constants_usage.py",
 )

tests/test_web_fetch_search_usage.py

@@ -0,0 +1,42 @@
+from pathlib import Path
+
+import pytest
+
+pytestmark = pytest.mark.architecture
+
+
+MODULES = (
+    "hyperbrowser/client/managers/sync_manager/web/__init__.py",
+    "hyperbrowser/client/managers/async_manager/web/__init__.py",
+)
+
+
+def test_web_managers_use_shared_fetch_search_route_and_metadata_constants():
+    for module_path in MODULES:
+        module_text = Path(module_path).read_text(encoding="utf-8")
+        assert "web_route_constants import WEB_FETCH_ROUTE_PATH, WEB_SEARCH_ROUTE_PATH" in module_text
+        assert "web_operation_metadata import WEB_REQUEST_OPERATION_METADATA" in module_text
+        assert "_FETCH_ROUTE_PATH = WEB_FETCH_ROUTE_PATH" in module_text
+        assert "_SEARCH_ROUTE_PATH = WEB_SEARCH_ROUTE_PATH" in module_text
+        assert "_OPERATION_METADATA = WEB_REQUEST_OPERATION_METADATA" in module_text
+        assert '"/web/fetch"' not in module_text
+        assert '"/web/search"' not in module_text
+        assert 'operation_name="web fetch"' not in module_text
+        assert 'operation_name="web search"' not in module_text
+
+
+def test_web_managers_use_shared_fetch_search_request_helpers():
+    sync_text = Path("hyperbrowser/client/managers/sync_manager/web/__init__.py").read_text(
+        encoding="utf-8"
+    )
+    async_text = Path("hyperbrowser/client/managers/async_manager/web/__init__.py").read_text(
+        encoding="utf-8"
+    )
+
+    assert "start_web_job(" in sync_text
+    assert "_client.transport.post(" not in sync_text
+    assert "parse_response_model(" not in sync_text
+
+    assert "start_web_job_async(" in async_text
+    assert "_client.transport.post(" not in async_text
+    assert "parse_response_model(" not in async_text

tests/test_web_operation_metadata.py

@@ -1,5 +1,6 @@
 from hyperbrowser.client.managers.web_operation_metadata import (
     BATCH_FETCH_OPERATION_METADATA,
+    WEB_REQUEST_OPERATION_METADATA,
     WEB_CRAWL_OPERATION_METADATA,
 )
 
@@ -24,3 +25,8 @@ def test_web_crawl_operation_metadata_values():
         == "Failed to start web crawl job"
     )
     assert WEB_CRAWL_OPERATION_METADATA.operation_name_prefix == "web crawl job "
+
+
+def test_web_request_operation_metadata_values():
+    assert WEB_REQUEST_OPERATION_METADATA.fetch_operation_name == "web fetch"
+    assert WEB_REQUEST_OPERATION_METADATA.search_operation_name == "web search"

tests/test_web_route_constants.py

@@ -1,9 +1,13 @@
 from hyperbrowser.client.managers.web_route_constants import (
     BATCH_FETCH_JOB_ROUTE_PREFIX,
+    WEB_FETCH_ROUTE_PATH,
     WEB_CRAWL_JOB_ROUTE_PREFIX,
+    WEB_SEARCH_ROUTE_PATH,
 )
 
 
 def test_web_route_constants_match_expected_api_paths():
     assert BATCH_FETCH_JOB_ROUTE_PREFIX == "/web/batch-fetch"
     assert WEB_CRAWL_JOB_ROUTE_PREFIX == "/web/crawl"
+    assert WEB_FETCH_ROUTE_PATH == "/web/fetch"
+    assert WEB_SEARCH_ROUTE_PATH == "/web/search"