feat(api): pagination properties added to response (has_more, next_offset)

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 46
 openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-cb38560915edce03abce2ae3ef5bc745489dbe9b6f80c2b4ff42edf8c2ff276d.yml
 openapi_spec_hash: a869194d6c864ba28d79ec0105439c3e
-config_hash: 1f28d5c3c063f418ebd2799df1e4e781
+config_hash: ed56f95781ec9b2e73c97e1a66606071

README.md

@@ -182,6 +182,10 @@ first_page = await client.deployments.list(
     app_name="YOUR_APP",
     limit=2,
 )
+
+print(
+    f"the current start offset for this page: {first_page.next_offset}"
+)  # => "the current start offset for this page: 1"
 for deployment in first_page.items:
     print(deployment.id)
 

src/kernel/pagination.py

@@ -5,7 +5,7 @@
 
 from httpx import Response
 
-from ._utils import is_mapping
+from ._utils import is_mapping, maybe_coerce_boolean, maybe_coerce_integer
 from ._models import BaseModel
 from ._base_client import BasePage, PageInfo, BaseSyncPage, BaseAsyncPage
 
@@ -18,6 +18,8 @@
 
 class SyncOffsetPagination(BaseSyncPage[_T], BasePage[_T], Generic[_T]):
     items: List[_T]
+    has_more: Optional[bool] = None
+    next_offset: Optional[int] = None
 
     @override
     def _get_page_items(self) -> List[_T]:
@@ -26,14 +28,22 @@ def _get_page_items(self) -> List[_T]:
             return []
         return items
 
+    @override
+    def has_next_page(self) -> bool:
+        has_more = self.has_more
+        if has_more is not None and has_more is False:
+            return False
+
+        return super().has_next_page()
+
     @override
     def next_page_info(self) -> Optional[PageInfo]:
-        offset = self._options.params.get("offset") or 0
-        if not isinstance(offset, int):
-            raise ValueError(f'Expected "offset" param to be an integer but got {offset}')
+        next_offset = self.next_offset
+        if next_offset is None:
+            return None  # type: ignore[unreachable]
 
         length = len(self._get_page_items())
-        current_count = offset + length
+        current_count = next_offset + length
 
         return PageInfo(params={"offset": current_count})
 
@@ -43,12 +53,16 @@ def build(cls: Type[_BaseModelT], *, response: Response, data: object) -> _BaseM
             None,
             **{
                 **(cast(Mapping[str, Any], data) if is_mapping(data) else {"items": data}),
+                "has_more": maybe_coerce_boolean(response.headers.get("X-Has-More")),
+                "next_offset": maybe_coerce_integer(response.headers.get("X-Next-Offset")),
             },
         )
 
 
 class AsyncOffsetPagination(BaseAsyncPage[_T], BasePage[_T], Generic[_T]):
     items: List[_T]
+    has_more: Optional[bool] = None
+    next_offset: Optional[int] = None
 
     @override
     def _get_page_items(self) -> List[_T]:
@@ -57,14 +71,22 @@ def _get_page_items(self) -> List[_T]:
             return []
         return items
 
+    @override
+    def has_next_page(self) -> bool:
+        has_more = self.has_more
+        if has_more is not None and has_more is False:
+            return False
+
+        return super().has_next_page()
+
     @override
     def next_page_info(self) -> Optional[PageInfo]:
-        offset = self._options.params.get("offset") or 0
-        if not isinstance(offset, int):
-            raise ValueError(f'Expected "offset" param to be an integer but got {offset}')
+        next_offset = self.next_offset
+        if next_offset is None:
+            return None  # type: ignore[unreachable]
 
         length = len(self._get_page_items())
-        current_count = offset + length
+        current_count = next_offset + length
 
         return PageInfo(params={"offset": current_count})
 
@@ -74,5 +96,7 @@ def build(cls: Type[_BaseModelT], *, response: Response, data: object) -> _BaseM
             None,
             **{
                 **(cast(Mapping[str, Any], data) if is_mapping(data) else {"items": data}),
+                "has_more": maybe_coerce_boolean(response.headers.get("X-Has-More")),
+                "next_offset": maybe_coerce_integer(response.headers.get("X-Next-Offset")),
             },
         )