feat: Support hot swap proxy on a session

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 90
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-cc60c65c6bb0b8a8ea662cf758806e641790870ded35f6ffdb9f4801f3d29b15.yml
-openapi_spec_hash: a1074e1bba578bcd5912512166ada0dc
-config_hash: 7868d3397406c2974b6f058488aeefd6
+configured_endpoints: 91
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-4f5307643555b7917e8681b1966ae0b99f770cf59805e2f917ec7528edf11ba8.yml
+openapi_spec_hash: 873a9aa3a88b6cec1ad94f848eeb1c45
+config_hash: 20337f7888852c165d099faa7589c90a

api.md

@@ -81,6 +81,7 @@ from kernel.types import (
     Profile,
     BrowserCreateResponse,
     BrowserRetrieveResponse,
+    BrowserUpdateResponse,
     BrowserListResponse,
 )
 ```
@@ -89,6 +90,7 @@ Methods:
 
 - <code title="post /browsers">client.browsers.<a href="./src/kernel/resources/browsers/browsers.py">create</a>(\*\*<a href="src/kernel/types/browser_create_params.py">params</a>) -> <a href="./src/kernel/types/browser_create_response.py">BrowserCreateResponse</a></code>
 - <code title="get /browsers/{id}">client.browsers.<a href="./src/kernel/resources/browsers/browsers.py">retrieve</a>(id) -> <a href="./src/kernel/types/browser_retrieve_response.py">BrowserRetrieveResponse</a></code>
+- <code title="patch /browsers/{id}">client.browsers.<a href="./src/kernel/resources/browsers/browsers.py">update</a>(id, \*\*<a href="src/kernel/types/browser_update_params.py">params</a>) -> <a href="./src/kernel/types/browser_update_response.py">BrowserUpdateResponse</a></code>
 - <code title="get /browsers">client.browsers.<a href="./src/kernel/resources/browsers/browsers.py">list</a>(\*\*<a href="src/kernel/types/browser_list_params.py">params</a>) -> <a href="./src/kernel/types/browser_list_response.py">SyncOffsetPagination[BrowserListResponse]</a></code>
 - <code title="delete /browsers">client.browsers.<a href="./src/kernel/resources/browsers/browsers.py">delete</a>(\*\*<a href="src/kernel/types/browser_delete_params.py">params</a>) -> None</code>
 - <code title="delete /browsers/{id}">client.browsers.<a href="./src/kernel/resources/browsers/browsers.py">delete_by_id</a>(id) -> None</code>

src/kernel/resources/browsers/browsers.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import typing_extensions
-from typing import Mapping, Iterable, cast
+from typing import Mapping, Iterable, Optional, cast
 
 import httpx
 
@@ -27,6 +27,7 @@
     browser_list_params,
     browser_create_params,
     browser_delete_params,
+    browser_update_params,
     browser_load_extensions_params,
 )
 from .process import (
@@ -75,6 +76,7 @@
 from ..._base_client import AsyncPaginator, make_request_options
 from ...types.browser_list_response import BrowserListResponse
 from ...types.browser_create_response import BrowserCreateResponse
+from ...types.browser_update_response import BrowserUpdateResponse
 from ...types.browser_persistence_param import BrowserPersistenceParam
 from ...types.browser_retrieve_response import BrowserRetrieveResponse
 from ...types.shared_params.browser_profile import BrowserProfile
@@ -253,6 +255,45 @@ def retrieve(
             cast_to=BrowserRetrieveResponse,
         )
 
+    def update(
+        self,
+        id: str,
+        *,
+        proxy_id: Optional[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,
+    ) -> BrowserUpdateResponse:
+        """Update a browser session.
+
+        Args:
+          proxy_id: ID of the proxy to use.
+
+        Omit to leave unchanged, set to empty string to remove
+              proxy.
+
+          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
+        """
+        if not id:
+            raise ValueError(f"Expected a non-empty value for `id` but received {id!r}")
+        return self._patch(
+            f"/browsers/{id}",
+            body=maybe_transform({"proxy_id": proxy_id}, browser_update_params.BrowserUpdateParams),
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=BrowserUpdateResponse,
+        )
+
     def list(
         self,
         *,
@@ -598,6 +639,45 @@ async def retrieve(
             cast_to=BrowserRetrieveResponse,
         )
 
+    async def update(
+        self,
+        id: str,
+        *,
+        proxy_id: Optional[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,
+    ) -> BrowserUpdateResponse:
+        """Update a browser session.
+
+        Args:
+          proxy_id: ID of the proxy to use.
+
+        Omit to leave unchanged, set to empty string to remove
+              proxy.
+
+          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
+        """
+        if not id:
+            raise ValueError(f"Expected a non-empty value for `id` but received {id!r}")
+        return await self._patch(
+            f"/browsers/{id}",
+            body=await async_maybe_transform({"proxy_id": proxy_id}, browser_update_params.BrowserUpdateParams),
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=BrowserUpdateResponse,
+        )
+
     def list(
         self,
         *,
@@ -786,6 +866,9 @@ def __init__(self, browsers: BrowsersResource) -> None:
         self.retrieve = to_raw_response_wrapper(
             browsers.retrieve,
         )
+        self.update = to_raw_response_wrapper(
+            browsers.update,
+        )
         self.list = to_raw_response_wrapper(
             browsers.list,
         )
@@ -836,6 +919,9 @@ def __init__(self, browsers: AsyncBrowsersResource) -> None:
         self.retrieve = async_to_raw_response_wrapper(
             browsers.retrieve,
         )
+        self.update = async_to_raw_response_wrapper(
+            browsers.update,
+        )
         self.list = async_to_raw_response_wrapper(
             browsers.list,
         )
@@ -886,6 +972,9 @@ def __init__(self, browsers: BrowsersResource) -> None:
         self.retrieve = to_streamed_response_wrapper(
             browsers.retrieve,
         )
+        self.update = to_streamed_response_wrapper(
+            browsers.update,
+        )
         self.list = to_streamed_response_wrapper(
             browsers.list,
         )
@@ -936,6 +1025,9 @@ def __init__(self, browsers: AsyncBrowsersResource) -> None:
         self.retrieve = async_to_streamed_response_wrapper(
             browsers.retrieve,
         )
+        self.update = async_to_streamed_response_wrapper(
+            browsers.update,
+        )
         self.list = async_to_streamed_response_wrapper(
             browsers.list,
         )

src/kernel/types/__init__.py

@@ -26,6 +26,7 @@
 from .browser_create_params import BrowserCreateParams as BrowserCreateParams
 from .browser_delete_params import BrowserDeleteParams as BrowserDeleteParams
 from .browser_list_response import BrowserListResponse as BrowserListResponse
+from .browser_update_params import BrowserUpdateParams as BrowserUpdateParams
 from .profile_create_params import ProfileCreateParams as ProfileCreateParams
 from .profile_list_response import ProfileListResponse as ProfileListResponse
 from .proxy_create_response import ProxyCreateResponse as ProxyCreateResponse
@@ -35,6 +36,7 @@
 from .invocation_list_params import InvocationListParams as InvocationListParams
 from .invocation_state_event import InvocationStateEvent as InvocationStateEvent
 from .browser_create_response import BrowserCreateResponse as BrowserCreateResponse
+from .browser_update_response import BrowserUpdateResponse as BrowserUpdateResponse
 from .extension_list_response import ExtensionListResponse as ExtensionListResponse
 from .extension_upload_params import ExtensionUploadParams as ExtensionUploadParams
 from .proxy_retrieve_response import ProxyRetrieveResponse as ProxyRetrieveResponse

src/kernel/types/browser_update_params.py

@@ -0,0 +1,16 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from __future__ import annotations
+
+from typing import Optional
+from typing_extensions import TypedDict
+
+__all__ = ["BrowserUpdateParams"]
+
+
+class BrowserUpdateParams(TypedDict, total=False):
+    proxy_id: Optional[str]
+    """ID of the proxy to use.
+
+    Omit to leave unchanged, set to empty string to remove proxy.
+    """

src/kernel/types/browser_update_response.py

@@ -0,0 +1,64 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from typing import Optional
+from datetime import datetime
+
+from .profile import Profile
+from .._models import BaseModel
+from .browser_persistence import BrowserPersistence
+from .shared.browser_viewport import BrowserViewport
+
+__all__ = ["BrowserUpdateResponse"]
+
+
+class BrowserUpdateResponse(BaseModel):
+    cdp_ws_url: str
+    """Websocket URL for Chrome DevTools Protocol connections to the browser session"""
+
+    created_at: datetime
+    """When the browser session was created."""
+
+    headless: bool
+    """Whether the browser session is running in headless mode."""
+
+    session_id: str
+    """Unique identifier for the browser session"""
+
+    stealth: bool
+    """Whether the browser session is running in stealth mode."""
+
+    timeout_seconds: int
+    """The number of seconds of inactivity before the browser session is terminated."""
+
+    browser_live_view_url: Optional[str] = None
+    """Remote URL for live viewing the browser session.
+
+    Only available for non-headless browsers.
+    """
+
+    deleted_at: Optional[datetime] = None
+    """When the browser session was soft-deleted. Only present for deleted sessions."""
+
+    kiosk_mode: Optional[bool] = None
+    """Whether the browser session is running in kiosk mode."""
+
+    persistence: Optional[BrowserPersistence] = None
+    """DEPRECATED: Use timeout_seconds (up to 72 hours) and Profiles instead."""
+
+    profile: Optional[Profile] = None
+    """Browser profile metadata."""
+
+    proxy_id: Optional[str] = None
+    """ID of the proxy associated with this browser session, if any."""
+
+    viewport: Optional[BrowserViewport] = None
+    """Initial browser window size in pixels with optional refresh rate.
+
+    If omitted, image defaults apply (1920x1080@25). Only specific viewport
+    configurations are supported. The server will reject unsupported combinations.
+    Supported resolutions are: 2560x1440@10, 1920x1080@25, 1920x1200@25,
+    1440x900@25, 1024x768@60, 1200x800@60 If refresh_rate is not provided, it will
+    be automatically determined from the width and height if they match a supported
+    configuration exactly. Note: Higher resolutions may affect the responsiveness of
+    live view browser
+    """