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: 738402ade5ac9528c8ef1677aa1d70f7
+config_hash: 4fb2010b528ce4358300ddd10e750265

README.md

@@ -118,85 +118,6 @@ 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 MessageSendResponse
+from beeper_desktop_api.types import MessageSearchResponse, 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/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="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,13 +1,14 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-from typing import List, Generic, TypeVar, Optional
+from typing import Dict, 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"]
+__all__ = ["SyncCursor", "AsyncCursor", "SyncCursorWithChats", "AsyncCursorWithChats"]
 
 _T = TypeVar("_T")
 
@@ -70,3 +71,65 @@ 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,6 +23,7 @@
 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"]
 
@@ -129,7 +130,7 @@ def search(
         extra_query: Query | None = None,
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
-    ) -> SyncCursor[Message]:
+    ) -> MessageSearchResponse:
         """
         Search messages across chats using Beeper's message index
 
@@ -179,9 +180,8 @@ def search(
 
           timeout: Override the client-level default timeout for this request, in seconds
         """
-        return self._get_api_list(
+        return self._get(
             "/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,
                 ),
             ),
-            model=Message,
+            cast_to=MessageSearchResponse,
         )
 
     def send(
@@ -339,7 +339,7 @@ def list(
             model=Message,
         )
 
-    def search(
+    async def search(
         self,
         *,
         account_ids: SequenceNotStr[str] | Omit = omit,
@@ -361,7 +361,7 @@ def search(
         extra_query: Query | None = None,
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
-    ) -> AsyncPaginator[Message, AsyncCursor[Message]]:
+    ) -> MessageSearchResponse:
         """
         Search messages across chats using Beeper's message index
 
@@ -411,15 +411,14 @@ def search(
 
           timeout: Override the client-level default timeout for this request, in seconds
         """
-        return self._get_api_list(
+        return await self._get(
             "/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=maybe_transform(
+                query=await async_maybe_transform(
                     {
                         "account_ids": account_ids,
                         "chat_ids": chat_ids,
@@ -438,7 +437,7 @@ def search(
                     message_search_params.MessageSearchParams,
                 ),
             ),
-            model=Message,
+            cast_to=MessageSearchResponse,
         )
 
     async def send(

src/beeper_desktop_api/types/__init__.py

@@ -31,4 +31,5 @@
 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

@@ -0,0 +1,34 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from typing import Dict, List, Optional
+
+from pydantic import Field as FieldInfo
+
+from .chat import Chat
+from .._models import BaseModel
+from .shared.message import Message
+
+__all__ = ["MessageSearchResponse"]
+
+
+class MessageSearchResponse(BaseModel):
+    chats: Dict[str, Chat]
+    """Map of chatID -> chat details for chats referenced in items."""
+
+    has_more: bool = FieldInfo(alias="hasMore")
+    """True if additional results can be fetched using the provided cursors."""
+
+    items: List[Message]
+    """Messages matching the query and filters."""
+
+    newest_cursor: Optional[str] = FieldInfo(alias="newestCursor", default=None)
+    """Cursor for fetching newer results (use with direction='after').
+
+    Opaque string; do not inspect.
+    """
+
+    oldest_cursor: Optional[str] = FieldInfo(alias="oldestCursor", default=None)
+    """Cursor for fetching older results (use with direction='before').
+
+    Opaque string; do not inspect.
+    """

tests/api_resources/test_messages.py

@@ -11,6 +11,7 @@
 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
@@ -66,7 +67,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(SyncCursor[Message], message, path=["response"])
+        assert_matches_type(MessageSearchResponse, message, path=["response"])
 
     @parametrize
     def test_method_search_with_all_params(self, client: BeeperDesktop) -> None:
@@ -89,7 +90,7 @@ def test_method_search_with_all_params(self, client: BeeperDesktop) -> None:
             query="dinner",
             sender="me",
         )
-        assert_matches_type(SyncCursor[Message], message, path=["response"])
+        assert_matches_type(MessageSearchResponse, message, path=["response"])
 
     @parametrize
     def test_raw_response_search(self, client: BeeperDesktop) -> None:
@@ -98,7 +99,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(SyncCursor[Message], message, path=["response"])
+        assert_matches_type(MessageSearchResponse, message, path=["response"])
 
     @parametrize
     def test_streaming_response_search(self, client: BeeperDesktop) -> None:
@@ -107,7 +108,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(SyncCursor[Message], message, path=["response"])
+            assert_matches_type(MessageSearchResponse, message, path=["response"])
 
         assert cast(Any, response.is_closed) is True
 
@@ -201,7 +202,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(AsyncCursor[Message], message, path=["response"])
+        assert_matches_type(MessageSearchResponse, message, path=["response"])
 
     @parametrize
     async def test_method_search_with_all_params(self, async_client: AsyncBeeperDesktop) -> None:
@@ -224,7 +225,7 @@ async def test_method_search_with_all_params(self, async_client: AsyncBeeperDesk
             query="dinner",
             sender="me",
         )
-        assert_matches_type(AsyncCursor[Message], message, path=["response"])
+        assert_matches_type(MessageSearchResponse, message, path=["response"])
 
     @parametrize
     async def test_raw_response_search(self, async_client: AsyncBeeperDesktop) -> None:
@@ -233,7 +234,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(AsyncCursor[Message], message, path=["response"])
+        assert_matches_type(MessageSearchResponse, message, path=["response"])
 
     @parametrize
     async def test_streaming_response_search(self, async_client: AsyncBeeperDesktop) -> None:
@@ -242,7 +243,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(AsyncCursor[Message], message, path=["response"])
+            assert_matches_type(MessageSearchResponse, message, path=["response"])
 
         assert cast(Any, response.is_closed) is True