Add optional model serialization helper for manager create flows

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

Author: cursoragent

CONTRIBUTING.md

@@ -91,6 +91,7 @@ This runs lint, format checks, compile checks, tests, and package build.
   - `tests/test_manager_model_dump_usage.py` (manager serialization centralization),
   - `tests/test_mapping_keys_access_usage.py` (centralized key-iteration boundaries),
   - `tests/test_mapping_reader_usage.py` (shared mapping-read parser usage),
+  - `tests/test_optional_serialization_helper_usage.py` (optional model serialization helper usage enforcement),
   - `tests/test_plain_type_guard_usage.py` (`str`/`int` guardrail enforcement via plain-type checks),
   - `tests/test_plain_type_identity_usage.py` (direct `type(... ) is str|int` guardrail enforcement via shared helpers),
   - `tests/test_polling_loop_usage.py` (`while True` polling-loop centralization in `hyperbrowser/client/polling.py`),

hyperbrowser/client/managers/async_manager/profile.py

@@ -8,7 +8,10 @@
     ProfileResponse,
 )
 from hyperbrowser.models.session import BasicResponse
-from ..serialization_utils import serialize_model_dump_to_dict
+from ..serialization_utils import (
+    serialize_model_dump_to_dict,
+    serialize_optional_model_dump_to_dict,
+)
 from ..response_utils import parse_response_model
 
 
@@ -19,12 +22,10 @@ def __init__(self, client):
     async def create(
         self, params: Optional[CreateProfileParams] = None
     ) -> CreateProfileResponse:
-        payload = {}
-        if params is not None:
-            payload = serialize_model_dump_to_dict(
-                params,
-                error_message="Failed to serialize profile create params",
-            )
+        payload = serialize_optional_model_dump_to_dict(
+            params,
+            error_message="Failed to serialize profile create params",
+        )
         response = await self._client.transport.post(
             self._client._build_url("/profile"),
             data=payload,

hyperbrowser/client/managers/async_manager/session.py

@@ -2,7 +2,10 @@
 from typing import IO, List, Optional, Union, overload
 import warnings
 from hyperbrowser.exceptions import HyperbrowserError
-from ..serialization_utils import serialize_model_dump_to_dict
+from ..serialization_utils import (
+    serialize_model_dump_to_dict,
+    serialize_optional_model_dump_to_dict,
+)
 from ..session_upload_utils import normalize_upload_file_input
 from ..session_utils import (
     parse_session_recordings_response_data,
@@ -61,12 +64,10 @@ def __init__(self, client):
     async def create(
         self, params: Optional[CreateSessionParams] = None
     ) -> SessionDetail:
-        payload = {}
-        if params is not None:
-            payload = serialize_model_dump_to_dict(
-                params,
-                error_message="Failed to serialize session create params",
-            )
+        payload = serialize_optional_model_dump_to_dict(
+            params,
+            error_message="Failed to serialize session create params",
+        )
         response = await self._client.transport.post(
             self._client._build_url("/session"),
             data=payload,

hyperbrowser/client/managers/serialization_utils.py

@@ -22,3 +22,20 @@ def serialize_model_dump_to_dict(
     if type(payload) is not dict:
         raise HyperbrowserError(error_message)
     return payload
+
+
+def serialize_optional_model_dump_to_dict(
+    model: Any,
+    *,
+    error_message: str,
+    exclude_none: bool = True,
+    by_alias: bool = True,
+) -> Dict[str, Any]:
+    if model is None:
+        return {}
+    return serialize_model_dump_to_dict(
+        model,
+        error_message=error_message,
+        exclude_none=exclude_none,
+        by_alias=by_alias,
+    )

hyperbrowser/client/managers/sync_manager/profile.py

@@ -8,7 +8,10 @@
     ProfileResponse,
 )
 from hyperbrowser.models.session import BasicResponse
-from ..serialization_utils import serialize_model_dump_to_dict
+from ..serialization_utils import (
+    serialize_model_dump_to_dict,
+    serialize_optional_model_dump_to_dict,
+)
 from ..response_utils import parse_response_model
 
 
@@ -19,12 +22,10 @@ def __init__(self, client):
     def create(
         self, params: Optional[CreateProfileParams] = None
     ) -> CreateProfileResponse:
-        payload = {}
-        if params is not None:
-            payload = serialize_model_dump_to_dict(
-                params,
-                error_message="Failed to serialize profile create params",
-            )
+        payload = serialize_optional_model_dump_to_dict(
+            params,
+            error_message="Failed to serialize profile create params",
+        )
         response = self._client.transport.post(
             self._client._build_url("/profile"),
             data=payload,

hyperbrowser/client/managers/sync_manager/session.py

@@ -2,7 +2,10 @@
 from typing import IO, List, Optional, Union, overload
 import warnings
 from hyperbrowser.exceptions import HyperbrowserError
-from ..serialization_utils import serialize_model_dump_to_dict
+from ..serialization_utils import (
+    serialize_model_dump_to_dict,
+    serialize_optional_model_dump_to_dict,
+)
 from ..session_upload_utils import normalize_upload_file_input
 from ..session_utils import (
     parse_session_recordings_response_data,
@@ -59,12 +62,10 @@ def __init__(self, client):
         self.event_logs = SessionEventLogsManager(client)
 
     def create(self, params: Optional[CreateSessionParams] = None) -> SessionDetail:
-        payload = {}
-        if params is not None:
-            payload = serialize_model_dump_to_dict(
-                params,
-                error_message="Failed to serialize session create params",
-            )
+        payload = serialize_optional_model_dump_to_dict(
+            params,
+            error_message="Failed to serialize session create params",
+        )
         response = self._client.transport.post(
             self._client._build_url("/session"),
             data=payload,

tests/test_architecture_marker_usage.py

@@ -18,6 +18,7 @@
     "tests/test_architecture_marker_usage.py",
     "tests/test_plain_type_guard_usage.py",
     "tests/test_plain_type_identity_usage.py",
+    "tests/test_optional_serialization_helper_usage.py",
     "tests/test_type_utils_usage.py",
     "tests/test_polling_loop_usage.py",
     "tests/test_core_type_helper_usage.py",

tests/test_manager_serialization_utils.py

@@ -4,6 +4,7 @@
 
 from hyperbrowser.client.managers.serialization_utils import (
     serialize_model_dump_to_dict,
+    serialize_optional_model_dump_to_dict,
 )
 from hyperbrowser.exceptions import HyperbrowserError
 
@@ -74,3 +75,27 @@ def test_serialize_model_dump_to_dict_rejects_non_dict_payloads():
         )
 
     assert exc_info.value.original_error is None
+
+
+def test_serialize_optional_model_dump_to_dict_returns_empty_dict_for_none():
+    assert (
+        serialize_optional_model_dump_to_dict(
+            None,
+            error_message="serialize failure",
+        )
+        == {}
+    )
+
+
+def test_serialize_optional_model_dump_to_dict_serializes_non_none_values():
+    model = _ModelWithPayload({"value": 1})
+
+    payload = serialize_optional_model_dump_to_dict(
+        model,
+        error_message="serialize failure",
+        exclude_none=False,
+        by_alias=False,
+    )
+
+    assert payload == {"value": 1}
+    assert model.calls == [(False, False)]

tests/test_optional_serialization_helper_usage.py

@@ -0,0 +1,20 @@
+from pathlib import Path
+
+import pytest
+
+pytestmark = pytest.mark.architecture
+
+
+MANAGER_MODULES = (
+    "hyperbrowser/client/managers/sync_manager/profile.py",
+    "hyperbrowser/client/managers/async_manager/profile.py",
+    "hyperbrowser/client/managers/sync_manager/session.py",
+    "hyperbrowser/client/managers/async_manager/session.py",
+)
+
+
+def test_profile_and_session_managers_use_optional_serialization_helper():
+    for module_path in MANAGER_MODULES:
+        module_text = Path(module_path).read_text(encoding="utf-8")
+        assert "serialize_optional_model_dump_to_dict(" in module_text
+        assert "payload = {}" not in module_text