Harden page-batch callback contract validation

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

Author: cursoragent

hyperbrowser/client/polling.py

@@ -397,7 +397,17 @@ def collect_paginated_results(
                 operation_name=operation_name,
             )
             current_page_batch = get_current_page_batch(page_response)
+            _ensure_non_awaitable(
+                current_page_batch,
+                callback_name="get_current_page_batch",
+                operation_name=operation_name,
+            )
             total_page_batches = get_total_page_batches(page_response)
+            _ensure_non_awaitable(
+                total_page_batches,
+                callback_name="get_total_page_batches",
+                operation_name=operation_name,
+            )
             _validate_page_batch_values(
                 operation_name=operation_name,
                 current_page_batch=current_page_batch,
@@ -477,7 +487,17 @@ async def collect_paginated_results_async(
                 operation_name=operation_name,
             )
             current_page_batch = get_current_page_batch(page_response)
+            _ensure_non_awaitable(
+                current_page_batch,
+                callback_name="get_current_page_batch",
+                operation_name=operation_name,
+            )
             total_page_batches = get_total_page_batches(page_response)
+            _ensure_non_awaitable(
+                total_page_batches,
+                callback_name="get_total_page_batches",
+                operation_name=operation_name,
+            )
             _validate_page_batch_values(
                 operation_name=operation_name,
                 current_page_batch=current_page_batch,

tests/test_polling.py

@@ -390,6 +390,40 @@ def on_page_success(response: dict) -> object:
     assert callback_attempts["count"] == 1
 
 
+def test_collect_paginated_results_rejects_awaitable_current_page_callback_result():
+    with pytest.raises(
+        HyperbrowserError,
+        match="get_current_page_batch must return a non-awaitable result",
+    ):
+        collect_paginated_results(
+            operation_name="sync paginated awaitable current page callback",
+            get_next_page=lambda page: {"current": 1, "total": 1, "items": []},
+            get_current_page_batch=lambda response: asyncio.sleep(0),  # type: ignore[return-value]
+            get_total_page_batches=lambda response: response["total"],
+            on_page_success=lambda response: None,
+            max_wait_seconds=1.0,
+            max_attempts=5,
+            retry_delay_seconds=0.0001,
+        )
+
+
+def test_collect_paginated_results_rejects_awaitable_total_pages_callback_result():
+    with pytest.raises(
+        HyperbrowserError,
+        match="get_total_page_batches must return a non-awaitable result",
+    ):
+        collect_paginated_results(
+            operation_name="sync paginated awaitable total pages callback",
+            get_next_page=lambda page: {"current": 1, "total": 1, "items": []},
+            get_current_page_batch=lambda response: response["current"],
+            get_total_page_batches=lambda response: asyncio.sleep(0),  # type: ignore[return-value]
+            on_page_success=lambda response: None,
+            max_wait_seconds=1.0,
+            max_attempts=5,
+            retry_delay_seconds=0.0001,
+        )
+
+
 def test_collect_paginated_results_allows_single_page_on_zero_max_wait():
     collected = []
 
@@ -486,6 +520,50 @@ def on_page_success(response: dict) -> object:
     asyncio.run(run())
 
 
+def test_collect_paginated_results_async_rejects_awaitable_current_page_callback_result():
+    async def run() -> None:
+        with pytest.raises(
+            HyperbrowserError,
+            match="get_current_page_batch must return a non-awaitable result",
+        ):
+            await collect_paginated_results_async(
+                operation_name="async paginated awaitable current page callback",
+                get_next_page=lambda page: asyncio.sleep(
+                    0, result={"current": 1, "total": 1, "items": []}
+                ),
+                get_current_page_batch=lambda response: asyncio.sleep(0),  # type: ignore[return-value]
+                get_total_page_batches=lambda response: response["total"],
+                on_page_success=lambda response: None,
+                max_wait_seconds=1.0,
+                max_attempts=5,
+                retry_delay_seconds=0.0001,
+            )
+
+    asyncio.run(run())
+
+
+def test_collect_paginated_results_async_rejects_awaitable_total_pages_callback_result():
+    async def run() -> None:
+        with pytest.raises(
+            HyperbrowserError,
+            match="get_total_page_batches must return a non-awaitable result",
+        ):
+            await collect_paginated_results_async(
+                operation_name="async paginated awaitable total pages callback",
+                get_next_page=lambda page: asyncio.sleep(
+                    0, result={"current": 1, "total": 1, "items": []}
+                ),
+                get_current_page_batch=lambda response: response["current"],
+                get_total_page_batches=lambda response: asyncio.sleep(0),  # type: ignore[return-value]
+                on_page_success=lambda response: None,
+                max_wait_seconds=1.0,
+                max_attempts=5,
+                retry_delay_seconds=0.0001,
+            )
+
+    asyncio.run(run())
+
+
 def test_collect_paginated_results_async_allows_single_page_on_zero_max_wait():
     async def run() -> None:
         collected = []