feat(api): manual updates

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 17
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/beeper%2Fbeeper-desktop-api-0e4d333e81e670e605a6706dbb365bc96957a59331fdc87dd1550c59880cb130.yml
-openapi_spec_hash: 564146e6d318ecb486ff7c0d7983b398
-config_hash: e3418e22e2ca1df0f8a9fcaf7153285a
+configured_endpoints: 18
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/beeper%2Fbeeper-desktop-api-5fb80d7f97f2428d1826b9c381476f0d46117fc694140175dbc15920b1884f1f.yml
+openapi_spec_hash: 06f8538bc0a27163d33a80c00fb16e86
+config_hash: d0b0effc89b6d81f98400536657b6876

README.md

@@ -11,8 +11,8 @@ and offers both synchronous and asynchronous clients powered by [httpx](https://
 
 Use the Beeper Desktop MCP Server to enable AI assistants to interact with this API, allowing them to explore endpoints, make test requests, and use documentation to help integrate this SDK into your application.
 
-[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=%40beeper%2Fdesktop-api-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBiZWVwZXIvZGVza3RvcC1hcGktbWNwIl19)
-[![Install in VS Code](https://img.shields.io/badge/_-Add_to_VS_Code-blue?style=for-the-badge&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGZpbGw9Im5vbmUiIHZpZXdCb3g9IjAgMCA0MCA0MCI+PHBhdGggZmlsbD0iI0VFRSIgZmlsbC1ydWxlPSJldmVub2RkIiBkPSJNMzAuMjM1IDM5Ljg4NGEyLjQ5MSAyLjQ5MSAwIDAgMS0xLjc4MS0uNzNMMTIuNyAyNC43OGwtMy40NiAyLjYyNC0zLjQwNiAyLjU4MmExLjY2NSAxLjY2NSAwIDAgMS0xLjA4Mi4zMzggMS42NjQgMS42NjQgMCAwIDEtMS4wNDYtLjQzMWwtMi4yLTJhMS42NjYgMS42NjYgMCAwIDEgMC0yLjQ2M0w3LjQ1OCAyMCA0LjY3IDE3LjQ1MyAxLjUwNyAxNC41N2ExLjY2NSAxLjY2NSAwIDAgMSAwLTIuNDYzbDIuMi0yYTEuNjY1IDEuNjY1IDAgMCAxIDIuMTMtLjA5N2w2Ljg2MyA1LjIwOUwyOC40NTIuODQ0YTIuNDg4IDIuNDg4IDAgMCAxIDEuODQxLS43MjljLjM1MS4wMDkuNjk5LjA5MSAxLjAxOS4yNDVsOC4yMzYgMy45NjFhMi41IDIuNSAwIDAgMSAxLjQxNSAyLjI1M3YuMDk5LS4wNDVWMzMuMzd2LS4wNDUuMDk1YTIuNTAxIDIuNTAxIDAgMCAxLTEuNDE2IDIuMjU3bC04LjIzNSAzLjk2MWEyLjQ5MiAyLjQ5MiAwIDAgMS0xLjA3Ny4yNDZabS43MTYtMjguOTQ3LTExLjk0OCA5LjA2MiAxMS45NTIgOS4wNjUtLjAwNC0xOC4xMjdaIi8+PC9zdmc+)](https://vscode.stainless.com/mcp/%7B%22name%22%3A%22%40beeper%2Fdesktop-api-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40beeper%2Fdesktop-api-mcp%22%5D%7D)
+[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=%40beeper%2Fdesktop-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBiZWVwZXIvZGVza3RvcC1tY3AiXX0)
+[![Install in VS Code](https://img.shields.io/badge/_-Add_to_VS_Code-blue?style=for-the-badge&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGZpbGw9Im5vbmUiIHZpZXdCb3g9IjAgMCA0MCA0MCI+PHBhdGggZmlsbD0iI0VFRSIgZmlsbC1ydWxlPSJldmVub2RkIiBkPSJNMzAuMjM1IDM5Ljg4NGEyLjQ5MSAyLjQ5MSAwIDAgMS0xLjc4MS0uNzNMMTIuNyAyNC43OGwtMy40NiAyLjYyNC0zLjQwNiAyLjU4MmExLjY2NSAxLjY2NSAwIDAgMS0xLjA4Mi4zMzggMS42NjQgMS42NjQgMCAwIDEtMS4wNDYtLjQzMWwtMi4yLTJhMS42NjYgMS42NjYgMCAwIDEgMC0yLjQ2M0w3LjQ1OCAyMCA0LjY3IDE3LjQ1MyAxLjUwNyAxNC41N2ExLjY2NSAxLjY2NSAwIDAgMSAwLTIuNDYzbDIuMi0yYTEuNjY1IDEuNjY1IDAgMCAxIDIuMTMtLjA5N2w2Ljg2MyA1LjIwOUwyOC40NTIuODQ0YTIuNDg4IDIuNDg4IDAgMCAxIDEuODQxLS43MjljLjM1MS4wMDkuNjk5LjA5MSAxLjAxOS4yNDVsOC4yMzYgMy45NjFhMi41IDIuNSAwIDAgMSAxLjQxNSAyLjI1M3YuMDk5LS4wNDVWMzMuMzd2LS4wNDUuMDk1YTIuNTAxIDIuNTAxIDAgMCAxLTEuNDE2IDIuMjU3bC04LjIzNSAzLjk2MWEyLjQ5MiAyLjQ5MiAwIDAgMS0xLjA3Ny4yNDZabS43MTYtMjguOTQ3LTExLjk0OCA5LjA2MiAxMS45NTIgOS4wNjUtLjAwNC0xOC4xMjdaIi8+PC9zdmc+)](https://vscode.stainless.com/mcp/%7B%22name%22%3A%22%40beeper%2Fdesktop-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40beeper%2Fdesktop-mcp%22%5D%7D)
 
 > Note: You may need to set environment variables in your MCP client.
 
@@ -23,10 +23,13 @@ The REST API documentation can be found on [developers.beeper.com](https://devel
 ## Installation
 
 ```sh
-# install from PyPI
-pip install beeper_desktop_api
+# install from the production repo
+pip install git+ssh://git@github.com/beeper/desktop-api-python.git
 ```
 
+> [!NOTE]
+> Once this package is [published to PyPI](https://www.stainless.com/docs/guides/publish), this will become: `pip install beeper_desktop_api`
+
 ## Usage
 
 The full API of this library can be found in [api.md](api.md).
@@ -87,8 +90,8 @@ By default, the async client uses `httpx` for HTTP requests. However, for improv
 You can enable this by installing `aiohttp`:
 
 ```sh
-# install from PyPI
-pip install beeper_desktop_api[aiohttp]
+# install from the production repo
+pip install 'beeper_desktop_api[aiohttp] @ git+ssh://git@github.com/beeper/desktop-api-python.git'
 ```
 
 Then you can enable it by instantiating the client with `http_client=DefaultAioHttpClient()`:
@@ -221,6 +224,23 @@ client.chats.reminders.create(
 )
 ```
 
+## File uploads
+
+Request parameters that correspond to file uploads can be passed as `bytes`, or a [`PathLike`](https://docs.python.org/3/library/os.html#os.PathLike) instance or a tuple of `(filename, contents, media type)`.
+
+```python
+from pathlib import Path
+from beeper_desktop_api import BeeperDesktop
+
+client = BeeperDesktop()
+
+client.assets.upload(
+    file=Path("/path/to/file"),
+)
+```
+
+The async client uses the exact same interface. If you pass a [`PathLike`](https://docs.python.org/3/library/os.html#os.PathLike) instance, the file contents will be read asynchronously automatically.
+
 ## Handling errors
 
 When the library is unable to connect to the API (for example, due to network connection problems or a timeout), a subclass of `beeper_desktop_api.APIConnectionError` is raised.

api.md

@@ -84,10 +84,15 @@ Methods:
 Types:
 
 ```python
-from beeper_desktop_api.types import AssetDownloadResponse, AssetUploadResponse
+from beeper_desktop_api.types import (
+    AssetDownloadResponse,
+    AssetUploadResponse,
+    AssetUploadBase64Response,
+)
 ```
 
 Methods:
 
 - <code title="post /v1/assets/download">client.assets.<a href="./src/beeper_desktop_api/resources/assets.py">download</a>(\*\*<a href="src/beeper_desktop_api/types/asset_download_params.py">params</a>) -> <a href="./src/beeper_desktop_api/types/asset_download_response.py">AssetDownloadResponse</a></code>
 - <code title="post /v1/assets/upload">client.assets.<a href="./src/beeper_desktop_api/resources/assets.py">upload</a>(\*\*<a href="src/beeper_desktop_api/types/asset_upload_params.py">params</a>) -> <a href="./src/beeper_desktop_api/types/asset_upload_response.py">AssetUploadResponse</a></code>
+- <code title="post /v1/assets/upload/base64">client.assets.<a href="./src/beeper_desktop_api/resources/assets.py">upload_base64</a>(\*\*<a href="src/beeper_desktop_api/types/asset_upload_base64_params.py">params</a>) -> <a href="./src/beeper_desktop_api/types/asset_upload_base64_response.py">AssetUploadBase64Response</a></code>

src/beeper_desktop_api/_files.py

@@ -34,7 +34,7 @@ def assert_is_file_content(obj: object, *, key: str | None = None) -> None:
     if not is_file_content(obj):
         prefix = f"Expected entry at `{key}`" if key is not None else f"Expected file input `{obj!r}`"
         raise RuntimeError(
-            f"{prefix} to be bytes, an io.IOBase instance, PathLike or a tuple but received {type(obj)} instead."
+            f"{prefix} to be bytes, an io.IOBase instance, PathLike or a tuple but received {type(obj)} instead. See https://github.com/beeper/desktop-api-python/tree/main#file-uploads"
         ) from None
 
 

src/beeper_desktop_api/resources/assets.py

@@ -6,8 +6,8 @@
 
 import httpx
 
-from ..types import asset_upload_params, asset_download_params
-from .._types import Body, Omit, Query, Headers, NotGiven, omit, not_given
+from ..types import asset_upload_params, asset_download_params, asset_upload_base64_params
+from .._types import Body, Omit, Query, Headers, NotGiven, FileTypes, omit, not_given
 from .._utils import extract_files, maybe_transform, deepcopy_minimal, async_maybe_transform
 from .._compat import cached_property
 from .._resource import SyncAPIResource, AsyncAPIResource
@@ -20,6 +20,7 @@
 from .._base_client import make_request_options
 from ..types.asset_upload_response import AssetUploadResponse
 from ..types.asset_download_response import AssetDownloadResponse
+from ..types.asset_upload_base64_response import AssetUploadBase64Response
 
 __all__ = ["AssetsResource", "AsyncAssetsResource"]
 
@@ -84,7 +85,7 @@ def download(
     def upload(
         self,
         *,
-        content: str,
+        file: FileTypes,
         file_name: str | Omit = omit,
         mime_type: str | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
@@ -94,16 +95,15 @@ def upload(
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> AssetUploadResponse:
-        """Upload a file to a temporary location.
+        """Upload a file to a temporary location using multipart/form-data.
 
-        Supports JSON body with base64 `content`
-        field, or multipart/form-data with `file` field. Returns a local file URL that
-        can be used when sending messages with attachments.
+        Returns an
+        uploadID that can be referenced when sending messages with attachments.
 
         Args:
-          content: Base64-encoded file content (max ~500MB decoded)
+          file: The file to upload (max 500 MB).
 
-          file_name: Original filename. Generated if omitted
+          file_name: Original filename. Defaults to the uploaded file name if omitted
 
           mime_type: MIME type. Auto-detected from magic bytes if omitted
 
@@ -117,17 +117,16 @@ def upload(
         """
         body = deepcopy_minimal(
             {
-                "content": content,
+                "file": file,
                 "file_name": file_name,
                 "mime_type": mime_type,
             }
         )
         files = extract_files(cast(Mapping[str, object], body), paths=[["file"]])
-        if files:
-            # It should be noted that the actual Content-Type header that will be
-            # sent to the server will contain a `boundary` parameter, e.g.
-            # multipart/form-data; boundary=---abc--
-            extra_headers = {"Content-Type": "multipart/form-data", **(extra_headers or {})}
+        # It should be noted that the actual Content-Type header that will be
+        # sent to the server will contain a `boundary` parameter, e.g.
+        # multipart/form-data; boundary=---abc--
+        extra_headers = {"Content-Type": "multipart/form-data", **(extra_headers or {})}
         return self._post(
             "/v1/assets/upload",
             body=maybe_transform(body, asset_upload_params.AssetUploadParams),
@@ -138,6 +137,56 @@ def upload(
             cast_to=AssetUploadResponse,
         )
 
+    def upload_base64(
+        self,
+        *,
+        content: str,
+        file_name: str | Omit = omit,
+        mime_type: str | Omit = omit,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> AssetUploadBase64Response:
+        """Upload a file using a JSON body with base64-encoded content.
+
+        Returns an uploadID
+        that can be referenced when sending messages with attachments. Alternative to
+        the multipart upload endpoint.
+
+        Args:
+          content: Base64-encoded file content (max ~500MB decoded)
+
+          file_name: Original filename. Generated if omitted
+
+          mime_type: MIME type. Auto-detected from magic bytes if omitted
+
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        return self._post(
+            "/v1/assets/upload/base64",
+            body=maybe_transform(
+                {
+                    "content": content,
+                    "file_name": file_name,
+                    "mime_type": mime_type,
+                },
+                asset_upload_base64_params.AssetUploadBase64Params,
+            ),
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=AssetUploadBase64Response,
+        )
+
 
 class AsyncAssetsResource(AsyncAPIResource):
     """Manage assets in Beeper Desktop, like message attachments"""
@@ -199,7 +248,7 @@ async def download(
     async def upload(
         self,
         *,
-        content: str,
+        file: FileTypes,
         file_name: str | Omit = omit,
         mime_type: str | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
@@ -209,16 +258,15 @@ async def upload(
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> AssetUploadResponse:
-        """Upload a file to a temporary location.
+        """Upload a file to a temporary location using multipart/form-data.
 
-        Supports JSON body with base64 `content`
-        field, or multipart/form-data with `file` field. Returns a local file URL that
-        can be used when sending messages with attachments.
+        Returns an
+        uploadID that can be referenced when sending messages with attachments.
 
         Args:
-          content: Base64-encoded file content (max ~500MB decoded)
+          file: The file to upload (max 500 MB).
 
-          file_name: Original filename. Generated if omitted
+          file_name: Original filename. Defaults to the uploaded file name if omitted
 
           mime_type: MIME type. Auto-detected from magic bytes if omitted
 
@@ -232,17 +280,16 @@ async def upload(
         """
         body = deepcopy_minimal(
             {
-                "content": content,
+                "file": file,
                 "file_name": file_name,
                 "mime_type": mime_type,
             }
         )
         files = extract_files(cast(Mapping[str, object], body), paths=[["file"]])
-        if files:
-            # It should be noted that the actual Content-Type header that will be
-            # sent to the server will contain a `boundary` parameter, e.g.
-            # multipart/form-data; boundary=---abc--
-            extra_headers = {"Content-Type": "multipart/form-data", **(extra_headers or {})}
+        # It should be noted that the actual Content-Type header that will be
+        # sent to the server will contain a `boundary` parameter, e.g.
+        # multipart/form-data; boundary=---abc--
+        extra_headers = {"Content-Type": "multipart/form-data", **(extra_headers or {})}
         return await self._post(
             "/v1/assets/upload",
             body=await async_maybe_transform(body, asset_upload_params.AssetUploadParams),
@@ -253,6 +300,56 @@ async def upload(
             cast_to=AssetUploadResponse,
         )
 
+    async def upload_base64(
+        self,
+        *,
+        content: str,
+        file_name: str | Omit = omit,
+        mime_type: str | Omit = omit,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> AssetUploadBase64Response:
+        """Upload a file using a JSON body with base64-encoded content.
+
+        Returns an uploadID
+        that can be referenced when sending messages with attachments. Alternative to
+        the multipart upload endpoint.
+
+        Args:
+          content: Base64-encoded file content (max ~500MB decoded)
+
+          file_name: Original filename. Generated if omitted
+
+          mime_type: MIME type. Auto-detected from magic bytes if omitted
+
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        return await self._post(
+            "/v1/assets/upload/base64",
+            body=await async_maybe_transform(
+                {
+                    "content": content,
+                    "file_name": file_name,
+                    "mime_type": mime_type,
+                },
+                asset_upload_base64_params.AssetUploadBase64Params,
+            ),
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=AssetUploadBase64Response,
+        )
+
 
 class AssetsResourceWithRawResponse:
     def __init__(self, assets: AssetsResource) -> None:
@@ -264,6 +361,9 @@ def __init__(self, assets: AssetsResource) -> None:
         self.upload = to_raw_response_wrapper(
             assets.upload,
         )
+        self.upload_base64 = to_raw_response_wrapper(
+            assets.upload_base64,
+        )
 
 
 class AsyncAssetsResourceWithRawResponse:
@@ -276,6 +376,9 @@ def __init__(self, assets: AsyncAssetsResource) -> None:
         self.upload = async_to_raw_response_wrapper(
             assets.upload,
         )
+        self.upload_base64 = async_to_raw_response_wrapper(
+            assets.upload_base64,
+        )
 
 
 class AssetsResourceWithStreamingResponse:
@@ -288,6 +391,9 @@ def __init__(self, assets: AssetsResource) -> None:
         self.upload = to_streamed_response_wrapper(
             assets.upload,
         )
+        self.upload_base64 = to_streamed_response_wrapper(
+            assets.upload_base64,
+        )
 
 
 class AsyncAssetsResourceWithStreamingResponse:
@@ -300,3 +406,6 @@ def __init__(self, assets: AsyncAssetsResource) -> None:
         self.upload = async_to_streamed_response_wrapper(
             assets.upload,
         )
+        self.upload_base64 = async_to_streamed_response_wrapper(
+            assets.upload_base64,
+        )

src/beeper_desktop_api/types/__init__.py

@@ -27,3 +27,5 @@
 from .message_update_params import MessageUpdateParams as MessageUpdateParams
 from .asset_download_response import AssetDownloadResponse as AssetDownloadResponse
 from .message_update_response import MessageUpdateResponse as MessageUpdateResponse
+from .asset_upload_base64_params import AssetUploadBase64Params as AssetUploadBase64Params
+from .asset_upload_base64_response import AssetUploadBase64Response as AssetUploadBase64Response