Centralize extension create input normalization

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

Author: cursoragent

CONTRIBUTING.md

@@ -88,6 +88,7 @@ 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_examples_naming_convention.py` (example sync/async prefix naming enforcement),
   - `tests/test_examples_syntax.py` (example script syntax guardrail),
+  - `tests/test_extension_create_helper_usage.py` (extension create-input normalization helper usage enforcement),
   - `tests/test_guardrail_ast_utils.py` (shared AST guard utility contract),
   - `tests/test_job_pagination_helper_usage.py` (shared scrape/crawl pagination helper usage enforcement),
   - `tests/test_makefile_quality_targets.py` (Makefile quality-gate target enforcement),

hyperbrowser/client/managers/async_manager/extension.py

@@ -1,8 +1,7 @@
 from typing import List
 
 from hyperbrowser.exceptions import HyperbrowserError
-from ...file_utils import ensure_existing_file_path
-from ..serialization_utils import serialize_model_dump_to_dict
+from ..extension_create_utils import normalize_extension_create_input
 from ..extension_utils import parse_extension_list_response_data
 from ..response_utils import parse_response_model
 from hyperbrowser.models.extension import CreateExtensionParams, ExtensionResponse
@@ -13,28 +12,7 @@ def __init__(self, client):
         self._client = client
 
     async def create(self, params: CreateExtensionParams) -> ExtensionResponse:
-        if type(params) is not CreateExtensionParams:
-            raise HyperbrowserError("params must be CreateExtensionParams")
-        try:
-            raw_file_path = params.file_path
-        except HyperbrowserError:
-            raise
-        except Exception as exc:
-            raise HyperbrowserError(
-                "params.file_path is invalid",
-                original_error=exc,
-            ) from exc
-        payload = serialize_model_dump_to_dict(
-            params,
-            error_message="Failed to serialize extension create params",
-        )
-        payload.pop("filePath", None)
-
-        file_path = ensure_existing_file_path(
-            raw_file_path,
-            missing_file_message=f"Extension file not found at path: {raw_file_path}",
-            not_file_message=f"Extension file path must point to a file: {raw_file_path}",
-        )
+        file_path, payload = normalize_extension_create_input(params)
 
         try:
             with open(file_path, "rb") as extension_file:

hyperbrowser/client/managers/extension_create_utils.py

@@ -0,0 +1,34 @@
+from typing import Any, Dict, Tuple
+
+from hyperbrowser.exceptions import HyperbrowserError
+from hyperbrowser.models.extension import CreateExtensionParams
+
+from ..file_utils import ensure_existing_file_path
+from .serialization_utils import serialize_model_dump_to_dict
+
+
+def normalize_extension_create_input(params: Any) -> Tuple[str, Dict[str, Any]]:
+    if type(params) is not CreateExtensionParams:
+        raise HyperbrowserError("params must be CreateExtensionParams")
+    try:
+        raw_file_path = params.file_path
+    except HyperbrowserError:
+        raise
+    except Exception as exc:
+        raise HyperbrowserError(
+            "params.file_path is invalid",
+            original_error=exc,
+        ) from exc
+
+    payload = serialize_model_dump_to_dict(
+        params,
+        error_message="Failed to serialize extension create params",
+    )
+    payload.pop("filePath", None)
+
+    file_path = ensure_existing_file_path(
+        raw_file_path,
+        missing_file_message=f"Extension file not found at path: {raw_file_path}",
+        not_file_message=f"Extension file path must point to a file: {raw_file_path}",
+    )
+    return file_path, payload

hyperbrowser/client/managers/sync_manager/extension.py

@@ -1,8 +1,7 @@
 from typing import List
 
 from hyperbrowser.exceptions import HyperbrowserError
-from ...file_utils import ensure_existing_file_path
-from ..serialization_utils import serialize_model_dump_to_dict
+from ..extension_create_utils import normalize_extension_create_input
 from ..extension_utils import parse_extension_list_response_data
 from ..response_utils import parse_response_model
 from hyperbrowser.models.extension import CreateExtensionParams, ExtensionResponse
@@ -13,28 +12,7 @@ def __init__(self, client):
         self._client = client
 
     def create(self, params: CreateExtensionParams) -> ExtensionResponse:
-        if type(params) is not CreateExtensionParams:
-            raise HyperbrowserError("params must be CreateExtensionParams")
-        try:
-            raw_file_path = params.file_path
-        except HyperbrowserError:
-            raise
-        except Exception as exc:
-            raise HyperbrowserError(
-                "params.file_path is invalid",
-                original_error=exc,
-            ) from exc
-        payload = serialize_model_dump_to_dict(
-            params,
-            error_message="Failed to serialize extension create params",
-        )
-        payload.pop("filePath", None)
-
-        file_path = ensure_existing_file_path(
-            raw_file_path,
-            missing_file_message=f"Extension file not found at path: {raw_file_path}",
-            not_file_message=f"Extension file path must point to a file: {raw_file_path}",
-        )
+        file_path, payload = normalize_extension_create_input(params)
 
         try:
             with open(file_path, "rb") as extension_file:

tests/test_architecture_marker_usage.py

@@ -29,6 +29,7 @@
     "tests/test_readme_examples_listing.py",
     "tests/test_examples_syntax.py",
     "tests/test_docs_python3_commands.py",
+    "tests/test_extension_create_helper_usage.py",
     "tests/test_examples_naming_convention.py",
     "tests/test_job_pagination_helper_usage.py",
     "tests/test_example_sync_async_parity.py",

tests/test_extension_create_helper_usage.py

@@ -0,0 +1,20 @@
+from pathlib import Path
+
+import pytest
+
+pytestmark = pytest.mark.architecture
+
+
+EXTENSION_MANAGER_MODULES = (
+    "hyperbrowser/client/managers/sync_manager/extension.py",
+    "hyperbrowser/client/managers/async_manager/extension.py",
+)
+
+
+def test_extension_managers_use_shared_extension_create_helper():
+    for module_path in EXTENSION_MANAGER_MODULES:
+        module_text = Path(module_path).read_text(encoding="utf-8")
+        assert "normalize_extension_create_input(" in module_text
+        assert "serialize_model_dump_to_dict(" not in module_text
+        assert "ensure_existing_file_path(" not in module_text
+        assert "params.file_path is invalid" not in module_text

tests/test_extension_create_utils.py

@@ -0,0 +1,117 @@
+from pathlib import Path
+from types import MappingProxyType
+
+import pytest
+
+from hyperbrowser.client.managers.extension_create_utils import (
+    normalize_extension_create_input,
+)
+from hyperbrowser.exceptions import HyperbrowserError
+from hyperbrowser.models.extension import CreateExtensionParams
+
+
+def _create_test_extension_zip(tmp_path: Path) -> Path:
+    file_path = tmp_path / "extension.zip"
+    file_path.write_bytes(b"extension-bytes")
+    return file_path
+
+
+def test_normalize_extension_create_input_returns_file_path_and_payload(tmp_path):
+    file_path = _create_test_extension_zip(tmp_path)
+    params = CreateExtensionParams(name="my-extension", file_path=file_path)
+
+    normalized_path, payload = normalize_extension_create_input(params)
+
+    assert normalized_path == str(file_path.resolve())
+    assert payload == {"name": "my-extension"}
+
+
+def test_normalize_extension_create_input_rejects_invalid_param_type():
+    with pytest.raises(HyperbrowserError, match="params must be CreateExtensionParams"):
+        normalize_extension_create_input({"name": "bad"})  # type: ignore[arg-type]
+
+
+def test_normalize_extension_create_input_rejects_subclass_param_type(tmp_path):
+    class _Params(CreateExtensionParams):
+        pass
+
+    params = _Params(name="bad", file_path=_create_test_extension_zip(tmp_path))
+
+    with pytest.raises(HyperbrowserError, match="params must be CreateExtensionParams"):
+        normalize_extension_create_input(params)
+
+
+def test_normalize_extension_create_input_wraps_serialization_errors(
+    tmp_path, monkeypatch: pytest.MonkeyPatch
+):
+    params = CreateExtensionParams(
+        name="serialize-extension",
+        file_path=_create_test_extension_zip(tmp_path),
+    )
+
+    def _raise_model_dump_error(*args, **kwargs):
+        _ = args
+        _ = kwargs
+        raise RuntimeError("broken model_dump")
+
+    monkeypatch.setattr(CreateExtensionParams, "model_dump", _raise_model_dump_error)
+
+    with pytest.raises(
+        HyperbrowserError, match="Failed to serialize extension create params"
+    ) as exc_info:
+        normalize_extension_create_input(params)
+
+    assert isinstance(exc_info.value.original_error, RuntimeError)
+
+
+def test_normalize_extension_create_input_preserves_hyperbrowser_serialization_errors(
+    tmp_path, monkeypatch: pytest.MonkeyPatch
+):
+    params = CreateExtensionParams(
+        name="serialize-extension",
+        file_path=_create_test_extension_zip(tmp_path),
+    )
+
+    def _raise_model_dump_error(*args, **kwargs):
+        _ = args
+        _ = kwargs
+        raise HyperbrowserError("custom model_dump failure")
+
+    monkeypatch.setattr(CreateExtensionParams, "model_dump", _raise_model_dump_error)
+
+    with pytest.raises(
+        HyperbrowserError, match="custom model_dump failure"
+    ) as exc_info:
+        normalize_extension_create_input(params)
+
+    assert exc_info.value.original_error is None
+
+
+def test_normalize_extension_create_input_rejects_non_dict_serialized_payload(
+    tmp_path, monkeypatch: pytest.MonkeyPatch
+):
+    params = CreateExtensionParams(
+        name="serialize-extension",
+        file_path=_create_test_extension_zip(tmp_path),
+    )
+
+    monkeypatch.setattr(
+        CreateExtensionParams,
+        "model_dump",
+        lambda *args, **kwargs: MappingProxyType({"name": "my-extension"}),
+    )
+
+    with pytest.raises(
+        HyperbrowserError, match="Failed to serialize extension create params"
+    ) as exc_info:
+        normalize_extension_create_input(params)
+
+    assert exc_info.value.original_error is None
+
+
+def test_normalize_extension_create_input_rejects_missing_file(tmp_path):
+    missing_path = tmp_path / "missing-extension.zip"
+    params = CreateExtensionParams(name="missing-extension", file_path=missing_path)
+
+    with pytest.raises(HyperbrowserError, match="Extension file not found"):
+        normalize_extension_create_input(params)