feat: WIP browser extensions

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 51
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-8a6175a75caa75c3de5400edf97a34e526ac3f62c63955375437461581deb0c2.yml
-openapi_spec_hash: 1a880e4ce337a0e44630e6d87ef5162a
-config_hash: 49c2ff978aaa5ccb4ce324a72f116010
+configured_endpoints: 57
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-936db268b3dcae5d64bd5d590506d8134304ffcbf67389eb9b1555b3febfd4cb.yml
+openapi_spec_hash: 145485087adf1b28c052bacb4df68462
+config_hash: 5236f9b34e39dc1930e36a88c714abd4

api.md

@@ -82,6 +82,7 @@ Methods:
 - <code title="get /browsers">client.browsers.<a href="./src/kernel/resources/browsers/browsers.py">list</a>() -> <a href="./src/kernel/types/browser_list_response.py">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>
+- <code title="post /browsers/{id}/extensions">client.browsers.<a href="./src/kernel/resources/browsers/browsers.py">upload_extensions</a>(id, \*\*<a href="src/kernel/types/browser_upload_extensions_params.py">params</a>) -> None</code>
 
 ## Replays
 
@@ -195,3 +196,19 @@ Methods:
 - <code title="get /proxies/{id}">client.proxies.<a href="./src/kernel/resources/proxies.py">retrieve</a>(id) -> <a href="./src/kernel/types/proxy_retrieve_response.py">ProxyRetrieveResponse</a></code>
 - <code title="get /proxies">client.proxies.<a href="./src/kernel/resources/proxies.py">list</a>() -> <a href="./src/kernel/types/proxy_list_response.py">ProxyListResponse</a></code>
 - <code title="delete /proxies/{id}">client.proxies.<a href="./src/kernel/resources/proxies.py">delete</a>(id) -> None</code>
+
+# Extensions
+
+Types:
+
+```python
+from kernel.types import ExtensionListResponse, ExtensionUploadResponse
+```
+
+Methods:
+
+- <code title="get /extensions">client.extensions.<a href="./src/kernel/resources/extensions.py">list</a>() -> <a href="./src/kernel/types/extension_list_response.py">ExtensionListResponse</a></code>
+- <code title="delete /extensions/{id_or_name}">client.extensions.<a href="./src/kernel/resources/extensions.py">delete</a>(id_or_name) -> None</code>
+- <code title="get /extensions/{id_or_name}">client.extensions.<a href="./src/kernel/resources/extensions.py">download</a>(id_or_name) -> BinaryAPIResponse</code>
+- <code title="get /extensions/from_chrome_store">client.extensions.<a href="./src/kernel/resources/extensions.py">download_from_chrome_store</a>(\*\*<a href="src/kernel/types/extension_download_from_chrome_store_params.py">params</a>) -> BinaryAPIResponse</code>
+- <code title="post /extensions">client.extensions.<a href="./src/kernel/resources/extensions.py">upload</a>(\*\*<a href="src/kernel/types/extension_upload_params.py">params</a>) -> <a href="./src/kernel/types/extension_upload_response.py">ExtensionUploadResponse</a></code>

src/kernel/_client.py

@@ -21,7 +21,7 @@
 )
 from ._utils import is_given, get_async_library
 from ._version import __version__
-from .resources import apps, proxies, profiles, deployments, invocations
+from .resources import apps, proxies, profiles, extensions, deployments, invocations
 from ._streaming import Stream as Stream, AsyncStream as AsyncStream
 from ._exceptions import KernelError, APIStatusError
 from ._base_client import (
@@ -56,6 +56,7 @@ class Kernel(SyncAPIClient):
     browsers: browsers.BrowsersResource
     profiles: profiles.ProfilesResource
     proxies: proxies.ProxiesResource
+    extensions: extensions.ExtensionsResource
     with_raw_response: KernelWithRawResponse
     with_streaming_response: KernelWithStreamedResponse
 
@@ -143,6 +144,7 @@ def __init__(
         self.browsers = browsers.BrowsersResource(self)
         self.profiles = profiles.ProfilesResource(self)
         self.proxies = proxies.ProxiesResource(self)
+        self.extensions = extensions.ExtensionsResource(self)
         self.with_raw_response = KernelWithRawResponse(self)
         self.with_streaming_response = KernelWithStreamedResponse(self)
 
@@ -260,6 +262,7 @@ class AsyncKernel(AsyncAPIClient):
     browsers: browsers.AsyncBrowsersResource
     profiles: profiles.AsyncProfilesResource
     proxies: proxies.AsyncProxiesResource
+    extensions: extensions.AsyncExtensionsResource
     with_raw_response: AsyncKernelWithRawResponse
     with_streaming_response: AsyncKernelWithStreamedResponse
 
@@ -347,6 +350,7 @@ def __init__(
         self.browsers = browsers.AsyncBrowsersResource(self)
         self.profiles = profiles.AsyncProfilesResource(self)
         self.proxies = proxies.AsyncProxiesResource(self)
+        self.extensions = extensions.AsyncExtensionsResource(self)
         self.with_raw_response = AsyncKernelWithRawResponse(self)
         self.with_streaming_response = AsyncKernelWithStreamedResponse(self)
 
@@ -465,6 +469,7 @@ def __init__(self, client: Kernel) -> None:
         self.browsers = browsers.BrowsersResourceWithRawResponse(client.browsers)
         self.profiles = profiles.ProfilesResourceWithRawResponse(client.profiles)
         self.proxies = proxies.ProxiesResourceWithRawResponse(client.proxies)
+        self.extensions = extensions.ExtensionsResourceWithRawResponse(client.extensions)
 
 
 class AsyncKernelWithRawResponse:
@@ -475,6 +480,7 @@ def __init__(self, client: AsyncKernel) -> None:
         self.browsers = browsers.AsyncBrowsersResourceWithRawResponse(client.browsers)
         self.profiles = profiles.AsyncProfilesResourceWithRawResponse(client.profiles)
         self.proxies = proxies.AsyncProxiesResourceWithRawResponse(client.proxies)
+        self.extensions = extensions.AsyncExtensionsResourceWithRawResponse(client.extensions)
 
 
 class KernelWithStreamedResponse:
@@ -485,6 +491,7 @@ def __init__(self, client: Kernel) -> None:
         self.browsers = browsers.BrowsersResourceWithStreamingResponse(client.browsers)
         self.profiles = profiles.ProfilesResourceWithStreamingResponse(client.profiles)
         self.proxies = proxies.ProxiesResourceWithStreamingResponse(client.proxies)
+        self.extensions = extensions.ExtensionsResourceWithStreamingResponse(client.extensions)
 
 
 class AsyncKernelWithStreamedResponse:
@@ -495,6 +502,7 @@ def __init__(self, client: AsyncKernel) -> None:
         self.browsers = browsers.AsyncBrowsersResourceWithStreamingResponse(client.browsers)
         self.profiles = profiles.AsyncProfilesResourceWithStreamingResponse(client.profiles)
         self.proxies = proxies.AsyncProxiesResourceWithStreamingResponse(client.proxies)
+        self.extensions = extensions.AsyncExtensionsResourceWithStreamingResponse(client.extensions)
 
 
 Client = Kernel

src/kernel/resources/__init__.py

@@ -32,6 +32,14 @@
     ProfilesResourceWithStreamingResponse,
     AsyncProfilesResourceWithStreamingResponse,
 )
+from .extensions import (
+    ExtensionsResource,
+    AsyncExtensionsResource,
+    ExtensionsResourceWithRawResponse,
+    AsyncExtensionsResourceWithRawResponse,
+    ExtensionsResourceWithStreamingResponse,
+    AsyncExtensionsResourceWithStreamingResponse,
+)
 from .deployments import (
     DeploymentsResource,
     AsyncDeploymentsResource,
@@ -86,4 +94,10 @@
     "AsyncProxiesResourceWithRawResponse",
     "ProxiesResourceWithStreamingResponse",
     "AsyncProxiesResourceWithStreamingResponse",
+    "ExtensionsResource",
+    "AsyncExtensionsResource",
+    "ExtensionsResourceWithRawResponse",
+    "AsyncExtensionsResourceWithRawResponse",
+    "ExtensionsResourceWithStreamingResponse",
+    "AsyncExtensionsResourceWithStreamingResponse",
 ]

src/kernel/resources/browsers/browsers.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+from typing import Mapping, Iterable, cast
+
 import httpx
 
 from .logs import (
@@ -20,7 +22,7 @@
     FsResourceWithStreamingResponse,
     AsyncFsResourceWithStreamingResponse,
 )
-from ...types import browser_create_params, browser_delete_params
+from ...types import browser_create_params, browser_delete_params, browser_upload_extensions_params
 from .process import (
     ProcessResource,
     AsyncProcessResource,
@@ -38,7 +40,7 @@
     AsyncReplaysResourceWithStreamingResponse,
 )
 from ..._types import Body, Omit, Query, Headers, NoneType, NotGiven, omit, not_given
-from ..._utils import maybe_transform, async_maybe_transform
+from ..._utils import extract_files, maybe_transform, deepcopy_minimal, async_maybe_transform
 from ..._compat import cached_property
 from ..._resource import SyncAPIResource, AsyncAPIResource
 from ..._response import (
@@ -95,6 +97,7 @@ def with_streaming_response(self) -> BrowsersResourceWithStreamingResponse:
     def create(
         self,
         *,
+        extensions: Iterable[browser_create_params.Extension] | Omit = omit,
         headless: bool | Omit = omit,
         invocation_id: str | Omit = omit,
         persistence: BrowserPersistenceParam | Omit = omit,
@@ -113,6 +116,8 @@ def create(
         Create a new browser session from within an action.
 
         Args:
+          extensions: List of browser extensions to load into the session. Provide each by id or name.
+
           headless: If true, launches the browser using a headless image (no VNC/GUI). Defaults to
               false.
 
@@ -149,6 +154,7 @@ def create(
             "/browsers",
             body=maybe_transform(
                 {
+                    "extensions": extensions,
                     "headless": headless,
                     "invocation_id": invocation_id,
                     "persistence": persistence,
@@ -289,6 +295,52 @@ def delete_by_id(
             cast_to=NoneType,
         )
 
+    def upload_extensions(
+        self,
+        id: str,
+        *,
+        extensions: Iterable[browser_upload_extensions_params.Extension],
+        # 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,
+    ) -> None:
+        """
+        Loads one or more unpacked extensions and restarts Chromium on the browser
+        instance.
+
+        Args:
+          extensions: List of extensions to upload and activate
+
+          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}")
+        extra_headers = {"Accept": "*/*", **(extra_headers or {})}
+        body = deepcopy_minimal({"extensions": extensions})
+        files = extract_files(cast(Mapping[str, object], body), paths=[["extensions", "<array>", "zip_file"]])
+        # 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"
+        return self._post(
+            f"/browsers/{id}/extensions",
+            body=maybe_transform(body, browser_upload_extensions_params.BrowserUploadExtensionsParams),
+            files=files,
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=NoneType,
+        )
+
 
 class AsyncBrowsersResource(AsyncAPIResource):
     @cached_property
@@ -329,6 +381,7 @@ def with_streaming_response(self) -> AsyncBrowsersResourceWithStreamingResponse:
     async def create(
         self,
         *,
+        extensions: Iterable[browser_create_params.Extension] | Omit = omit,
         headless: bool | Omit = omit,
         invocation_id: str | Omit = omit,
         persistence: BrowserPersistenceParam | Omit = omit,
@@ -347,6 +400,8 @@ async def create(
         Create a new browser session from within an action.
 
         Args:
+          extensions: List of browser extensions to load into the session. Provide each by id or name.
+
           headless: If true, launches the browser using a headless image (no VNC/GUI). Defaults to
               false.
 
@@ -383,6 +438,7 @@ async def create(
             "/browsers",
             body=await async_maybe_transform(
                 {
+                    "extensions": extensions,
                     "headless": headless,
                     "invocation_id": invocation_id,
                     "persistence": persistence,
@@ -525,6 +581,52 @@ async def delete_by_id(
             cast_to=NoneType,
         )
 
+    async def upload_extensions(
+        self,
+        id: str,
+        *,
+        extensions: Iterable[browser_upload_extensions_params.Extension],
+        # 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,
+    ) -> None:
+        """
+        Loads one or more unpacked extensions and restarts Chromium on the browser
+        instance.
+
+        Args:
+          extensions: List of extensions to upload and activate
+
+          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}")
+        extra_headers = {"Accept": "*/*", **(extra_headers or {})}
+        body = deepcopy_minimal({"extensions": extensions})
+        files = extract_files(cast(Mapping[str, object], body), paths=[["extensions", "<array>", "zip_file"]])
+        # 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"
+        return await self._post(
+            f"/browsers/{id}/extensions",
+            body=await async_maybe_transform(body, browser_upload_extensions_params.BrowserUploadExtensionsParams),
+            files=files,
+            options=make_request_options(
+                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+            ),
+            cast_to=NoneType,
+        )
+
 
 class BrowsersResourceWithRawResponse:
     def __init__(self, browsers: BrowsersResource) -> None:
@@ -545,6 +647,9 @@ def __init__(self, browsers: BrowsersResource) -> None:
         self.delete_by_id = to_raw_response_wrapper(
             browsers.delete_by_id,
         )
+        self.upload_extensions = to_raw_response_wrapper(
+            browsers.upload_extensions,
+        )
 
     @cached_property
     def replays(self) -> ReplaysResourceWithRawResponse:
@@ -582,6 +687,9 @@ def __init__(self, browsers: AsyncBrowsersResource) -> None:
         self.delete_by_id = async_to_raw_response_wrapper(
             browsers.delete_by_id,
         )
+        self.upload_extensions = async_to_raw_response_wrapper(
+            browsers.upload_extensions,
+        )
 
     @cached_property
     def replays(self) -> AsyncReplaysResourceWithRawResponse:
@@ -619,6 +727,9 @@ def __init__(self, browsers: BrowsersResource) -> None:
         self.delete_by_id = to_streamed_response_wrapper(
             browsers.delete_by_id,
         )
+        self.upload_extensions = to_streamed_response_wrapper(
+            browsers.upload_extensions,
+        )
 
     @cached_property
     def replays(self) -> ReplaysResourceWithStreamingResponse:
@@ -656,6 +767,9 @@ def __init__(self, browsers: AsyncBrowsersResource) -> None:
         self.delete_by_id = async_to_streamed_response_wrapper(
             browsers.delete_by_id,
         )
+        self.upload_extensions = async_to_streamed_response_wrapper(
+            browsers.upload_extensions,
+        )
 
     @cached_property
     def replays(self) -> AsyncReplaysResourceWithStreamingResponse: