feat(api): manual updates

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 15
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/beeper%2Fbeeper-desktop-api-953cbc1ea1fe675bf2d32b18030a3ac509c521946921cb338c0d1c2cfef89424.yml
-openapi_spec_hash: b4d08ca2dc21bc00245c9c9408be89ef
-config_hash: 4fb2010b528ce4358300ddd10e750265
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/beeper%2Fbeeper-desktop-api-803a4423d75f7a43582319924f0770153fd5ec313b9466c290513b9a891c2653.yml
+openapi_spec_hash: f32dfbf172bb043fd8c961cba5f73765
+config_hash: 738402ade5ac9528c8ef1677aa1d70f7

README.md

@@ -118,6 +118,85 @@ Nested request parameters are [TypedDicts](https://docs.python.org/3/library/typ
 
 Typed requests and responses provide autocomplete and documentation within your editor. If you would like to see type errors in VS Code to help catch bugs earlier, set `python.analysis.typeCheckingMode` to `basic`.
 
+## Pagination
+
+List methods in the Beeper Desktop API are paginated.
+
+This library provides auto-paginating iterators with each list response, so you do not have to request successive pages manually:
+
+```python
+from beeper_desktop_api import BeeperDesktop
+
+client = BeeperDesktop()
+
+all_messages = []
+# Automatically fetches more pages as needed.
+for message in client.messages.search(
+    account_ids=["local-telegram_ba_QFrb5lrLPhO3OT5MFBeTWv0x4BI"],
+    limit=10,
+    query="deployment",
+):
+    # Do something with message here
+    all_messages.append(message)
+print(all_messages)
+```
+
+Or, asynchronously:
+
+```python
+import asyncio
+from beeper_desktop_api import AsyncBeeperDesktop
+
+client = AsyncBeeperDesktop()
+
+
+async def main() -> None:
+    all_messages = []
+    # Iterate through items across all pages, issuing requests as needed.
+    async for message in client.messages.search(
+        account_ids=["local-telegram_ba_QFrb5lrLPhO3OT5MFBeTWv0x4BI"],
+        limit=10,
+        query="deployment",
+    ):
+        all_messages.append(message)
+    print(all_messages)
+
+
+asyncio.run(main())
+```
+
+Alternatively, you can use the `.has_next_page()`, `.next_page_info()`, or `.get_next_page()` methods for more granular control working with pages:
+
+```python
+first_page = await client.messages.search(
+    account_ids=["local-telegram_ba_QFrb5lrLPhO3OT5MFBeTWv0x4BI"],
+    limit=10,
+    query="deployment",
+)
+if first_page.has_next_page():
+    print(f"will fetch next page using these details: {first_page.next_page_info()}")
+    next_page = await first_page.get_next_page()
+    print(f"number of items we just fetched: {len(next_page.items)}")
+
+# Remove `await` for non-async usage.
+```
+
+Or just work directly with the returned data:
+
+```python
+first_page = await client.messages.search(
+    account_ids=["local-telegram_ba_QFrb5lrLPhO3OT5MFBeTWv0x4BI"],
+    limit=10,
+    query="deployment",
+)
+
+print(f"next page cursor: {first_page.oldest_cursor}")  # => "next page cursor: ..."
+for message in first_page.items:
+    print(message.id)
+
+# Remove `await` for non-async usage.
+```
+
 ## Nested params
 
 Nested parameters are dictionaries, typed using `TypedDict`, for example:

api.md

@@ -70,11 +70,11 @@ Methods:
 Types:
 
 ```python
-from beeper_desktop_api.types import MessageSearchResponse, MessageSendResponse
+from beeper_desktop_api.types import MessageSendResponse
 ```
 
 Methods:
 
 - <code title="get /v1/messages">client.messages.<a href="./src/beeper_desktop_api/resources/messages.py">list</a>(\*\*<a href="src/beeper_desktop_api/types/message_list_params.py">params</a>) -> <a href="./src/beeper_desktop_api/types/shared/message.py">SyncCursor[Message]</a></code>
-- <code title="get /v1/messages/search">client.messages.<a href="./src/beeper_desktop_api/resources/messages.py">search</a>(\*\*<a href="src/beeper_desktop_api/types/message_search_params.py">params</a>) -> <a href="./src/beeper_desktop_api/types/message_search_response.py">MessageSearchResponse</a></code>
+- <code title="get /v1/messages/search">client.messages.<a href="./src/beeper_desktop_api/resources/messages.py">search</a>(\*\*<a href="src/beeper_desktop_api/types/message_search_params.py">params</a>) -> <a href="./src/beeper_desktop_api/types/shared/message.py">SyncCursor[Message]</a></code>
 - <code title="post /v1/messages">client.messages.<a href="./src/beeper_desktop_api/resources/messages.py">send</a>(\*\*<a href="src/beeper_desktop_api/types/message_send_params.py">params</a>) -> <a href="./src/beeper_desktop_api/types/message_send_response.py">MessageSendResponse</a></code>

src/beeper_desktop_api/pagination.py

@@ -1,14 +1,13 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-from typing import Dict, List, Generic, TypeVar, Optional
+from typing import List, Generic, TypeVar, Optional
 from typing_extensions import override
 
 from pydantic import Field as FieldInfo
 
-from .types.chat import Chat
 from ._base_client import BasePage, PageInfo, BaseSyncPage, BaseAsyncPage
 
-__all__ = ["SyncCursor", "AsyncCursor", "SyncCursorWithChats", "AsyncCursorWithChats"]
+__all__ = ["SyncCursor", "AsyncCursor"]
 
 _T = TypeVar("_T")
 
@@ -71,65 +70,3 @@ def next_page_info(self) -> Optional[PageInfo]:
             return None
 
         return PageInfo(params={"cursor": oldest_cursor})
-
-
-class SyncCursorWithChats(BaseSyncPage[_T], BasePage[_T], Generic[_T]):
-    items: List[_T]
-    chats: Optional[Dict[str, Chat]] = None
-    has_more: Optional[bool] = FieldInfo(alias="hasMore", default=None)
-    oldest_cursor: Optional[str] = FieldInfo(alias="oldestCursor", default=None)
-    newest_cursor: Optional[str] = FieldInfo(alias="newestCursor", default=None)
-
-    @override
-    def _get_page_items(self) -> List[_T]:
-        items = self.items
-        if not items:
-            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]:
-        oldest_cursor = self.oldest_cursor
-        if not oldest_cursor:
-            return None
-
-        return PageInfo(params={"cursor": oldest_cursor})
-
-
-class AsyncCursorWithChats(BaseAsyncPage[_T], BasePage[_T], Generic[_T]):
-    items: List[_T]
-    chats: Optional[Dict[str, Chat]] = None
-    has_more: Optional[bool] = FieldInfo(alias="hasMore", default=None)
-    oldest_cursor: Optional[str] = FieldInfo(alias="oldestCursor", default=None)
-    newest_cursor: Optional[str] = FieldInfo(alias="newestCursor", default=None)
-
-    @override
-    def _get_page_items(self) -> List[_T]:
-        items = self.items
-        if not items:
-            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]:
-        oldest_cursor = self.oldest_cursor
-        if not oldest_cursor:
-            return None
-
-        return PageInfo(params={"cursor": oldest_cursor})

src/beeper_desktop_api/resources/messages.py

@@ -23,7 +23,6 @@
 from .._base_client import AsyncPaginator, make_request_options
 from ..types.shared.message import Message
 from ..types.message_send_response import MessageSendResponse
-from ..types.message_search_response import MessageSearchResponse
 
 __all__ = ["MessagesResource", "AsyncMessagesResource"]
 
@@ -130,7 +129,7 @@ def search(
         extra_query: Query | None = None,
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
-    ) -> MessageSearchResponse:
+    ) -> SyncCursor[Message]:
         """
         Search messages across chats using Beeper's message index
 
@@ -180,8 +179,9 @@ def search(
 
           timeout: Override the client-level default timeout for this request, in seconds
         """
-        return self._get(
+        return self._get_api_list(
             "/v1/messages/search",
+            page=SyncCursor[Message],
             options=make_request_options(
                 extra_headers=extra_headers,
                 extra_query=extra_query,
@@ -206,7 +206,7 @@ def search(
                     message_search_params.MessageSearchParams,
                 ),
             ),
-            cast_to=MessageSearchResponse,
+            model=Message,
         )
 
     def send(
@@ -339,7 +339,7 @@ def list(
             model=Message,
         )
 
-    async def search(
+    def search(
         self,
         *,
         account_ids: SequenceNotStr[str] | Omit = omit,
@@ -361,7 +361,7 @@ async def search(
         extra_query: Query | None = None,
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
-    ) -> MessageSearchResponse:
+    ) -> AsyncPaginator[Message, AsyncCursor[Message]]:
         """
         Search messages across chats using Beeper's message index
 
@@ -411,14 +411,15 @@ async def search(
 
           timeout: Override the client-level default timeout for this request, in seconds
         """
-        return await self._get(
+        return self._get_api_list(
             "/v1/messages/search",
+            page=AsyncCursor[Message],
             options=make_request_options(
                 extra_headers=extra_headers,
                 extra_query=extra_query,
                 extra_body=extra_body,
                 timeout=timeout,
-                query=await async_maybe_transform(
+                query=maybe_transform(
                     {
                         "account_ids": account_ids,
                         "chat_ids": chat_ids,
@@ -437,7 +438,7 @@ async def search(
                     message_search_params.MessageSearchParams,
                 ),
             ),
-            cast_to=MessageSearchResponse,
+            model=Message,
         )
 
     async def send(

src/beeper_desktop_api/types/__init__.py

@@ -31,5 +31,4 @@
 from .message_send_response import MessageSendResponse as MessageSendResponse
 from .contact_search_response import ContactSearchResponse as ContactSearchResponse
 from .download_asset_response import DownloadAssetResponse as DownloadAssetResponse
-from .message_search_response import MessageSearchResponse as MessageSearchResponse
 from .client_download_asset_params import ClientDownloadAssetParams as ClientDownloadAssetParams

src/beeper_desktop_api/types/message_search_response.py

@@ -11,7 +11,6 @@
 from beeper_desktop_api import BeeperDesktop, AsyncBeeperDesktop
 from beeper_desktop_api.types import (
     MessageSendResponse,
-    MessageSearchResponse,
 )
 from beeper_desktop_api._utils import parse_datetime
 from beeper_desktop_api.pagination import SyncCursor, AsyncCursor
@@ -67,7 +66,7 @@ def test_streaming_response_list(self, client: BeeperDesktop) -> None:
     @parametrize
     def test_method_search(self, client: BeeperDesktop) -> None:
         message = client.messages.search()
-        assert_matches_type(MessageSearchResponse, message, path=["response"])
+        assert_matches_type(SyncCursor[Message], message, path=["response"])
 
     @parametrize
     def test_method_search_with_all_params(self, client: BeeperDesktop) -> None:
@@ -90,7 +89,7 @@ def test_method_search_with_all_params(self, client: BeeperDesktop) -> None:
             query="dinner",
             sender="me",
         )
-        assert_matches_type(MessageSearchResponse, message, path=["response"])
+        assert_matches_type(SyncCursor[Message], message, path=["response"])
 
     @parametrize
     def test_raw_response_search(self, client: BeeperDesktop) -> None:
@@ -99,7 +98,7 @@ def test_raw_response_search(self, client: BeeperDesktop) -> None:
         assert response.is_closed is True
         assert response.http_request.headers.get("X-Stainless-Lang") == "python"
         message = response.parse()
-        assert_matches_type(MessageSearchResponse, message, path=["response"])
+        assert_matches_type(SyncCursor[Message], message, path=["response"])
 
     @parametrize
     def test_streaming_response_search(self, client: BeeperDesktop) -> None:
@@ -108,7 +107,7 @@ def test_streaming_response_search(self, client: BeeperDesktop) -> None:
             assert response.http_request.headers.get("X-Stainless-Lang") == "python"
 
             message = response.parse()
-            assert_matches_type(MessageSearchResponse, message, path=["response"])
+            assert_matches_type(SyncCursor[Message], message, path=["response"])
 
         assert cast(Any, response.is_closed) is True
 
@@ -202,7 +201,7 @@ async def test_streaming_response_list(self, async_client: AsyncBeeperDesktop) -
     @parametrize
     async def test_method_search(self, async_client: AsyncBeeperDesktop) -> None:
         message = await async_client.messages.search()
-        assert_matches_type(MessageSearchResponse, message, path=["response"])
+        assert_matches_type(AsyncCursor[Message], message, path=["response"])
 
     @parametrize
     async def test_method_search_with_all_params(self, async_client: AsyncBeeperDesktop) -> None:
@@ -225,7 +224,7 @@ async def test_method_search_with_all_params(self, async_client: AsyncBeeperDesk
             query="dinner",
             sender="me",
         )
-        assert_matches_type(MessageSearchResponse, message, path=["response"])
+        assert_matches_type(AsyncCursor[Message], message, path=["response"])
 
     @parametrize
     async def test_raw_response_search(self, async_client: AsyncBeeperDesktop) -> None:
@@ -234,7 +233,7 @@ async def test_raw_response_search(self, async_client: AsyncBeeperDesktop) -> No
         assert response.is_closed is True
         assert response.http_request.headers.get("X-Stainless-Lang") == "python"
         message = await response.parse()
-        assert_matches_type(MessageSearchResponse, message, path=["response"])
+        assert_matches_type(AsyncCursor[Message], message, path=["response"])
 
     @parametrize
     async def test_streaming_response_search(self, async_client: AsyncBeeperDesktop) -> None:
@@ -243,7 +242,7 @@ async def test_streaming_response_search(self, async_client: AsyncBeeperDesktop)
             assert response.http_request.headers.get("X-Stainless-Lang") == "python"
 
             message = await response.parse()
-            assert_matches_type(MessageSearchResponse, message, path=["response"])
+            assert_matches_type(AsyncCursor[Message], message, path=["response"])
 
         assert cast(Any, response.is_closed) is True