feat: [kernel-1116] browser events api integration

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 112
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel/kernel-e564e74a7aae1744d4aa070a63c387f456c4719a48747dc6229b58a986255b65.yml
-openapi_spec_hash: 62beb1f20708652aaee31bbffb6cfbe9
-config_hash: 08d55086449943a8fec212b870061a3f
+configured_endpoints: 113
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel/kernel-a9c7e806132001dbfbd4e8ae6c7d0935e503f457d63385fc800c862e3d064375.yml
+openapi_spec_hash: b048dcb0c5401bc0a301c3d30cb8ecba
+config_hash: 37661d89120558d34b6cc184292632f2

api.md

@@ -103,6 +103,50 @@ Methods:
 - <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">load_extensions</a>(id, \*\*<a href="src/kernel/types/browser_load_extensions_params.py">params</a>) -> None</code>
 
+## Telemetry
+
+Types:
+
+```python
+from kernel.types.browsers import (
+    BrowserCallStack,
+    BrowserConsoleErrorEvent,
+    BrowserConsoleLogEvent,
+    BrowserEventContext,
+    BrowserEventSource,
+    BrowserHTTPHeaders,
+    BrowserInteractionClickEvent,
+    BrowserInteractionKeyEvent,
+    BrowserInteractionScrollSettledEvent,
+    BrowserMonitorDisconnectedEvent,
+    BrowserMonitorInitFailedEvent,
+    BrowserMonitorReconnectFailedEvent,
+    BrowserMonitorReconnectedEvent,
+    BrowserMonitorScreenshotEvent,
+    BrowserNetworkIdleEvent,
+    BrowserNetworkLoadingFailedEvent,
+    BrowserNetworkRequestEvent,
+    BrowserNetworkResponseEvent,
+    BrowserPageDomContentLoadedEvent,
+    BrowserPageLayoutSettledEvent,
+    BrowserPageLayoutShiftEvent,
+    BrowserPageLcpEvent,
+    BrowserPageLoadEvent,
+    BrowserPageNavigationEvent,
+    BrowserPageNavigationSettledEvent,
+    BrowserPageTabOpenedEvent,
+    BrowserTelemetryCategoriesConfig,
+    BrowserTelemetryCategoryConfig,
+    BrowserTelemetryConfig,
+    BrowserTelemetryEvent,
+    TelemetryStreamResponse,
+)
+```
+
+Methods:
+
+- <code title="get /browsers/{id}/telemetry">client.browsers.telemetry.<a href="./src/kernel/resources/browsers/telemetry.py">stream</a>(id) -> <a href="./src/kernel/types/browsers/telemetry_stream_response.py">TelemetryStreamResponse</a></code>
+
 ## Replays
 
 Types:

src/kernel/resources/browser_pools.py

@@ -110,9 +110,11 @@ def create(
           proxy_id: Optional proxy to associate to the browser session. Must reference a proxy
               belonging to the caller's org.
 
-          start_url: Optional URL to open when a browser is created for the pool. Navigation is
-              best-effort, so navigation failures do not prevent the pool from filling. Reused
-              browsers keep the page left by the previous lease.
+          start_url: Optional URL to navigate to when a new browser is warmed into the pool.
+              Best-effort: failures to navigate do not fail pool fill. Only applied to
+              newly-warmed browsers; browsers reused via release/acquire keep whatever URL the
+              previous lease left them on. Accepts any URL Chromium can resolve, including
+              chrome:// pages.
 
           stealth: If true, launches the browser in stealth mode to reduce detection by anti-bot
               mechanisms.
@@ -259,9 +261,11 @@ def update(
           proxy_id: Optional proxy to associate to the browser session. Must reference a proxy
               belonging to the caller's org.
 
-          start_url: Optional URL to open when a browser is created for the pool. Navigation is
-              best-effort, so navigation failures do not prevent the pool from filling. Reused
-              browsers keep the page left by the previous lease.
+          start_url: Optional URL to navigate to when a new browser is warmed into the pool.
+              Best-effort: failures to navigate do not fail pool fill. Only applied to
+              newly-warmed browsers; browsers reused via release/acquire keep whatever URL the
+              previous lease left them on. Accepts any URL Chromium can resolve, including
+              chrome:// pages.
 
           stealth: If true, launches the browser in stealth mode to reduce detection by anti-bot
               mechanisms.
@@ -584,9 +588,11 @@ async def create(
           proxy_id: Optional proxy to associate to the browser session. Must reference a proxy
               belonging to the caller's org.
 
-          start_url: Optional URL to open when a browser is created for the pool. Navigation is
-              best-effort, so navigation failures do not prevent the pool from filling. Reused
-              browsers keep the page left by the previous lease.
+          start_url: Optional URL to navigate to when a new browser is warmed into the pool.
+              Best-effort: failures to navigate do not fail pool fill. Only applied to
+              newly-warmed browsers; browsers reused via release/acquire keep whatever URL the
+              previous lease left them on. Accepts any URL Chromium can resolve, including
+              chrome:// pages.
 
           stealth: If true, launches the browser in stealth mode to reduce detection by anti-bot
               mechanisms.
@@ -733,9 +739,11 @@ async def update(
           proxy_id: Optional proxy to associate to the browser session. Must reference a proxy
               belonging to the caller's org.
 
-          start_url: Optional URL to open when a browser is created for the pool. Navigation is
-              best-effort, so navigation failures do not prevent the pool from filling. Reused
-              browsers keep the page left by the previous lease.
+          start_url: Optional URL to navigate to when a new browser is warmed into the pool.
+              Best-effort: failures to navigate do not fail pool fill. Only applied to
+              newly-warmed browsers; browsers reused via release/acquire keep whatever URL the
+              previous lease left them on. Accepts any URL Chromium can resolve, including
+              chrome:// pages.
 
           stealth: If true, launches the browser in stealth mode to reduce detection by anti-bot
               mechanisms.

src/kernel/resources/browsers/__init__.py

@@ -48,6 +48,14 @@
     ComputerResourceWithStreamingResponse,
     AsyncComputerResourceWithStreamingResponse,
 )
+from .telemetry import (
+    TelemetryResource,
+    AsyncTelemetryResource,
+    TelemetryResourceWithRawResponse,
+    AsyncTelemetryResourceWithRawResponse,
+    TelemetryResourceWithStreamingResponse,
+    AsyncTelemetryResourceWithStreamingResponse,
+)
 from .playwright import (
     PlaywrightResource,
     AsyncPlaywrightResource,
@@ -58,6 +66,12 @@
 )
 
 __all__ = [
+    "TelemetryResource",
+    "AsyncTelemetryResource",
+    "TelemetryResourceWithRawResponse",
+    "AsyncTelemetryResourceWithRawResponse",
+    "TelemetryResourceWithStreamingResponse",
+    "AsyncTelemetryResourceWithStreamingResponse",
     "ReplaysResource",
     "AsyncReplaysResource",
     "ReplaysResourceWithRawResponse",

src/kernel/resources/browsers/browsers.py

@@ -61,6 +61,14 @@
     AsyncComputerResourceWithStreamingResponse,
 )
 from ..._compat import cached_property
+from .telemetry import (
+    TelemetryResource,
+    AsyncTelemetryResource,
+    TelemetryResourceWithRawResponse,
+    AsyncTelemetryResourceWithRawResponse,
+    TelemetryResourceWithStreamingResponse,
+    AsyncTelemetryResourceWithStreamingResponse,
+)
 from .playwright import (
     PlaywrightResource,
     AsyncPlaywrightResource,
@@ -87,13 +95,19 @@
 from ...types.shared_params.browser_profile import BrowserProfile
 from ...types.shared_params.browser_viewport import BrowserViewport
 from ...types.shared_params.browser_extension import BrowserExtension
+from ...types.browsers.browser_telemetry_config_param import BrowserTelemetryConfigParam
 
 __all__ = ["BrowsersResource", "AsyncBrowsersResource"]
 
 
 class BrowsersResource(SyncAPIResource):
     """Create and manage browser sessions."""
 
+    @cached_property
+    def telemetry(self) -> TelemetryResource:
+        """Stream live telemetry events from a browser session."""
+        return TelemetryResource(self._client)
+
     @cached_property
     def replays(self) -> ReplaysResource:
         """Record and manage browser session video replays."""
@@ -156,6 +170,7 @@ def create(
         proxy_id: str | Omit = omit,
         start_url: str | Omit = omit,
         stealth: bool | Omit = omit,
+        telemetry: Optional[BrowserTelemetryConfigParam] | Omit = omit,
         timeout_seconds: int | Omit = omit,
         viewport: BrowserViewport | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
@@ -204,6 +219,10 @@ def create(
           stealth: If true, launches the browser in stealth mode to reduce detection by anti-bot
               mechanisms.
 
+          telemetry: Telemetry configuration for the browser session. If provided, telemetry capture
+              starts with the specified category filter when the session is created. If
+              omitted, no telemetry capture is started.
+
           timeout_seconds: The number of seconds of inactivity before the browser session is terminated.
               Activity includes CDP connections and live view connections. Defaults to 60
               seconds. Minimum allowed is 10 seconds. Maximum allowed is 259200 (72 hours). We
@@ -246,6 +265,7 @@ def create(
                     "proxy_id": proxy_id,
                     "start_url": start_url,
                     "stealth": stealth,
+                    "telemetry": telemetry,
                     "timeout_seconds": timeout_seconds,
                     "viewport": viewport,
                 },
@@ -306,6 +326,7 @@ def update(
         disable_default_proxy: bool | Omit = omit,
         profile: BrowserProfile | Omit = omit,
         proxy_id: Optional[str] | Omit = omit,
+        telemetry: Optional[BrowserTelemetryConfigParam] | Omit = omit,
         viewport: browser_update_params.Viewport | 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.
@@ -327,6 +348,11 @@ def update(
           proxy_id: ID of the proxy to use. Omit to leave unchanged, set to empty string to remove
               proxy.
 
+          telemetry: Telemetry configuration. Omit, set to null, or set to an empty object ({}) to
+              leave the existing configuration unchanged (no-op). To enable capture for all
+              categories using VM defaults, set browser to an empty object ({"browser": {}}).
+              To stop capture, set every category's enabled to false.
+
           viewport: Viewport configuration to apply to the browser session.
 
           extra_headers: Send extra headers
@@ -346,6 +372,7 @@ def update(
                     "disable_default_proxy": disable_default_proxy,
                     "profile": profile,
                     "proxy_id": proxy_id,
+                    "telemetry": telemetry,
                     "viewport": viewport,
                 },
                 browser_update_params.BrowserUpdateParams,
@@ -608,6 +635,11 @@ def load_extensions(
 class AsyncBrowsersResource(AsyncAPIResource):
     """Create and manage browser sessions."""
 
+    @cached_property
+    def telemetry(self) -> AsyncTelemetryResource:
+        """Stream live telemetry events from a browser session."""
+        return AsyncTelemetryResource(self._client)
+
     @cached_property
     def replays(self) -> AsyncReplaysResource:
         """Record and manage browser session video replays."""
@@ -670,6 +702,7 @@ async def create(
         proxy_id: str | Omit = omit,
         start_url: str | Omit = omit,
         stealth: bool | Omit = omit,
+        telemetry: Optional[BrowserTelemetryConfigParam] | Omit = omit,
         timeout_seconds: int | Omit = omit,
         viewport: BrowserViewport | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
@@ -718,6 +751,10 @@ async def create(
           stealth: If true, launches the browser in stealth mode to reduce detection by anti-bot
               mechanisms.
 
+          telemetry: Telemetry configuration for the browser session. If provided, telemetry capture
+              starts with the specified category filter when the session is created. If
+              omitted, no telemetry capture is started.
+
           timeout_seconds: The number of seconds of inactivity before the browser session is terminated.
               Activity includes CDP connections and live view connections. Defaults to 60
               seconds. Minimum allowed is 10 seconds. Maximum allowed is 259200 (72 hours). We
@@ -760,6 +797,7 @@ async def create(
                     "proxy_id": proxy_id,
                     "start_url": start_url,
                     "stealth": stealth,
+                    "telemetry": telemetry,
                     "timeout_seconds": timeout_seconds,
                     "viewport": viewport,
                 },
@@ -820,6 +858,7 @@ async def update(
         disable_default_proxy: bool | Omit = omit,
         profile: BrowserProfile | Omit = omit,
         proxy_id: Optional[str] | Omit = omit,
+        telemetry: Optional[BrowserTelemetryConfigParam] | Omit = omit,
         viewport: browser_update_params.Viewport | 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.
@@ -841,6 +880,11 @@ async def update(
           proxy_id: ID of the proxy to use. Omit to leave unchanged, set to empty string to remove
               proxy.
 
+          telemetry: Telemetry configuration. Omit, set to null, or set to an empty object ({}) to
+              leave the existing configuration unchanged (no-op). To enable capture for all
+              categories using VM defaults, set browser to an empty object ({"browser": {}}).
+              To stop capture, set every category's enabled to false.
+
           viewport: Viewport configuration to apply to the browser session.
 
           extra_headers: Send extra headers
@@ -860,6 +904,7 @@ async def update(
                     "disable_default_proxy": disable_default_proxy,
                     "profile": profile,
                     "proxy_id": proxy_id,
+                    "telemetry": telemetry,
                     "viewport": viewport,
                 },
                 browser_update_params.BrowserUpdateParams,
@@ -1152,6 +1197,11 @@ def __init__(self, browsers: BrowsersResource) -> None:
             browsers.load_extensions,
         )
 
+    @cached_property
+    def telemetry(self) -> TelemetryResourceWithRawResponse:
+        """Stream live telemetry events from a browser session."""
+        return TelemetryResourceWithRawResponse(self._browsers.telemetry)
+
     @cached_property
     def replays(self) -> ReplaysResourceWithRawResponse:
         """Record and manage browser session video replays."""
@@ -1213,6 +1263,11 @@ def __init__(self, browsers: AsyncBrowsersResource) -> None:
             browsers.load_extensions,
         )
 
+    @cached_property
+    def telemetry(self) -> AsyncTelemetryResourceWithRawResponse:
+        """Stream live telemetry events from a browser session."""
+        return AsyncTelemetryResourceWithRawResponse(self._browsers.telemetry)
+
     @cached_property
     def replays(self) -> AsyncReplaysResourceWithRawResponse:
         """Record and manage browser session video replays."""
@@ -1274,6 +1329,11 @@ def __init__(self, browsers: BrowsersResource) -> None:
             browsers.load_extensions,
         )
 
+    @cached_property
+    def telemetry(self) -> TelemetryResourceWithStreamingResponse:
+        """Stream live telemetry events from a browser session."""
+        return TelemetryResourceWithStreamingResponse(self._browsers.telemetry)
+
     @cached_property
     def replays(self) -> ReplaysResourceWithStreamingResponse:
         """Record and manage browser session video replays."""
@@ -1335,6 +1395,11 @@ def __init__(self, browsers: AsyncBrowsersResource) -> None:
             browsers.load_extensions,
         )
 
+    @cached_property
+    def telemetry(self) -> AsyncTelemetryResourceWithStreamingResponse:
+        """Stream live telemetry events from a browser session."""
+        return AsyncTelemetryResourceWithStreamingResponse(self._browsers.telemetry)
+
     @cached_property
     def replays(self) -> AsyncReplaysResourceWithStreamingResponse:
         """Record and manage browser session video replays."""