diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 7cfa47b..fe941d1 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "0.78.1" + ".": "0.79.0" } \ No newline at end of file diff --git a/.stats.yml b/.stats.yml index 7f088e4..3807b2f 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1,4 +1,4 @@ configured_endpoints: 127 -openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel/kernel-92c776855f978ae03a778fbbac49bf1edc65852530644772c382838b6eab9fe5.yml -openapi_spec_hash: 4a9fbcb607be408ad646e207fe90687f +openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel/kernel-e04362b2c82b88f4f7fb43209c764fa9fdf37fe98932e142547be43a1e99c50b.yml +openapi_spec_hash: b16e79bfd6cac36090c815a8184b9e09 config_hash: 77ee715aa17061166f9a02b264a21b8d diff --git a/CHANGELOG.md b/CHANGELOG.md index 7696e5f..7c25a06 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,13 @@ # Changelog +## 0.79.0 (2026-07-15) + +Full Changelog: [v0.78.1...v0.79.0](https://github.com/kernel/kernel-python-sdk/compare/v0.78.1...v0.79.0) + +### Features + +* Add telemetry support for browser pools with BAA enforcement ([a7f5d9e](https://github.com/kernel/kernel-python-sdk/commit/a7f5d9e4909fed534df873d90ac14481b18b7d20)) + ## 0.78.1 (2026-07-15) Full Changelog: [v0.78.0...v0.78.1](https://github.com/kernel/kernel-python-sdk/compare/v0.78.0...v0.78.1) diff --git a/pyproject.toml b/pyproject.toml index 25ced22..7727ba0 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "kernel" -version = "0.78.1" +version = "0.79.0" description = "The official Python library for the kernel API" dynamic = ["readme"] license = "Apache-2.0" diff --git a/src/kernel/_version.py b/src/kernel/_version.py index 740df44..73b9f56 100644 --- a/src/kernel/_version.py +++ b/src/kernel/_version.py @@ -1,4 +1,4 @@ # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. __title__ = "kernel" -__version__ = "0.78.1" # x-release-please-version +__version__ = "0.79.0" # x-release-please-version diff --git a/src/kernel/resources/browser_pools.py b/src/kernel/resources/browser_pools.py index a2725fb..d71fc27 100644 --- a/src/kernel/resources/browser_pools.py +++ b/src/kernel/resources/browser_pools.py @@ -2,7 +2,7 @@ from __future__ import annotations -from typing import Dict, Iterable +from typing import Dict, Iterable, Optional import httpx @@ -72,6 +72,7 @@ def create( refresh_on_profile_update: bool | Omit = omit, start_url: str | Omit = omit, stealth: bool | Omit = omit, + telemetry: Optional[browser_pool_create_params.Telemetry] | 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. @@ -134,6 +135,13 @@ def create( stealth: If true, launches the browser in stealth mode to reduce detection by anti-bot mechanisms. Defaults to false. + telemetry: Telemetry configuration applied to browsers warmed into this pool. Set enabled + to true to start capture using the default set, or provide browser category + settings. If omitted, null, set to an empty object ({}), set to enabled: false + without browser category settings, or all four CDP categories are explicitly + disabled, no telemetry is configured on the pool. Only applied to newly-warmed + browsers. + timeout_seconds: Default idle timeout in seconds for browsers acquired from this pool before they are destroyed. Defaults to 600 seconds. Minimum 10, maximum 259200 (72 hours). @@ -174,6 +182,7 @@ def create( "refresh_on_profile_update": refresh_on_profile_update, "start_url": start_url, "stealth": stealth, + "telemetry": telemetry, "timeout_seconds": timeout_seconds, "viewport": viewport, }, @@ -235,6 +244,7 @@ def update( size: int | Omit = omit, start_url: str | Omit = omit, stealth: bool | Omit = omit, + telemetry: Optional[browser_pool_update_params.Telemetry] | 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. @@ -306,6 +316,14 @@ def update( stealth: If provided, replaces whether browsers launch in stealth mode. + telemetry: If provided, updates the pool's telemetry configuration. Omit, set to null, or + set to an empty object ({}) to leave the existing configuration unchanged. Set + enabled to true to enable capture using the default set. Set enabled to false to + clear the pool's telemetry. Provide browser category settings for per-category + updates, merged onto the pool's current configuration. Only applied to browsers + warmed after the update; browsers already in the pool keep their configuration + until discarded. + timeout_seconds: If provided, replaces the default idle timeout in seconds for browsers acquired from this pool before they are destroyed. Minimum 10, maximum 259200 (72 hours). @@ -349,6 +367,7 @@ def update( "size": size, "start_url": start_url, "stealth": stealth, + "telemetry": telemetry, "timeout_seconds": timeout_seconds, "viewport": viewport, }, @@ -468,6 +487,7 @@ def acquire( name: str | Omit = omit, start_url: str | Omit = omit, tags: TagsParam | Omit = omit, + telemetry: Optional[browser_pool_acquire_params.Telemetry] | 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, @@ -500,6 +520,15 @@ def acquire( find and group sessions later. Applies to this lease only and are cleared when the browser is released back to the pool. Up to 50 pairs. + telemetry: Telemetry override for the acquired browser, applied to this lease only. Merges + onto the browser's current (pool-inherited) telemetry using the same + per-category semantics as PATCH /browsers: provided categories override the + current configuration, omitted categories are inherited. Set enabled to true to + resolve the config fresh from the default set, or enabled to false to stop + capture. When the browser is released back to the pool with reuse, its telemetry + is reset to the pool's baseline, so the override does not carry over to the next + lease. + extra_headers: Send extra headers extra_query: Add additional query parameters to the request @@ -518,6 +547,7 @@ def acquire( "name": name, "start_url": start_url, "tags": tags, + "telemetry": telemetry, }, browser_pool_acquire_params.BrowserPoolAcquireParams, ), @@ -650,6 +680,7 @@ async def create( refresh_on_profile_update: bool | Omit = omit, start_url: str | Omit = omit, stealth: bool | Omit = omit, + telemetry: Optional[browser_pool_create_params.Telemetry] | 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. @@ -712,6 +743,13 @@ async def create( stealth: If true, launches the browser in stealth mode to reduce detection by anti-bot mechanisms. Defaults to false. + telemetry: Telemetry configuration applied to browsers warmed into this pool. Set enabled + to true to start capture using the default set, or provide browser category + settings. If omitted, null, set to an empty object ({}), set to enabled: false + without browser category settings, or all four CDP categories are explicitly + disabled, no telemetry is configured on the pool. Only applied to newly-warmed + browsers. + timeout_seconds: Default idle timeout in seconds for browsers acquired from this pool before they are destroyed. Defaults to 600 seconds. Minimum 10, maximum 259200 (72 hours). @@ -752,6 +790,7 @@ async def create( "refresh_on_profile_update": refresh_on_profile_update, "start_url": start_url, "stealth": stealth, + "telemetry": telemetry, "timeout_seconds": timeout_seconds, "viewport": viewport, }, @@ -813,6 +852,7 @@ async def update( size: int | Omit = omit, start_url: str | Omit = omit, stealth: bool | Omit = omit, + telemetry: Optional[browser_pool_update_params.Telemetry] | 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. @@ -884,6 +924,14 @@ async def update( stealth: If provided, replaces whether browsers launch in stealth mode. + telemetry: If provided, updates the pool's telemetry configuration. Omit, set to null, or + set to an empty object ({}) to leave the existing configuration unchanged. Set + enabled to true to enable capture using the default set. Set enabled to false to + clear the pool's telemetry. Provide browser category settings for per-category + updates, merged onto the pool's current configuration. Only applied to browsers + warmed after the update; browsers already in the pool keep their configuration + until discarded. + timeout_seconds: If provided, replaces the default idle timeout in seconds for browsers acquired from this pool before they are destroyed. Minimum 10, maximum 259200 (72 hours). @@ -927,6 +975,7 @@ async def update( "size": size, "start_url": start_url, "stealth": stealth, + "telemetry": telemetry, "timeout_seconds": timeout_seconds, "viewport": viewport, }, @@ -1046,6 +1095,7 @@ async def acquire( name: str | Omit = omit, start_url: str | Omit = omit, tags: TagsParam | Omit = omit, + telemetry: Optional[browser_pool_acquire_params.Telemetry] | 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, @@ -1078,6 +1128,15 @@ async def acquire( find and group sessions later. Applies to this lease only and are cleared when the browser is released back to the pool. Up to 50 pairs. + telemetry: Telemetry override for the acquired browser, applied to this lease only. Merges + onto the browser's current (pool-inherited) telemetry using the same + per-category semantics as PATCH /browsers: provided categories override the + current configuration, omitted categories are inherited. Set enabled to true to + resolve the config fresh from the default set, or enabled to false to stop + capture. When the browser is released back to the pool with reuse, its telemetry + is reset to the pool's baseline, so the override does not carry over to the next + lease. + extra_headers: Send extra headers extra_query: Add additional query parameters to the request @@ -1096,6 +1155,7 @@ async def acquire( "name": name, "start_url": start_url, "tags": tags, + "telemetry": telemetry, }, browser_pool_acquire_params.BrowserPoolAcquireParams, ), diff --git a/src/kernel/types/browser_pool.py b/src/kernel/types/browser_pool.py index 4f7764a..344ffd7 100644 --- a/src/kernel/types/browser_pool.py +++ b/src/kernel/types/browser_pool.py @@ -6,6 +6,7 @@ from .._models import BaseModel from .shared.browser_viewport import BrowserViewport from .shared.browser_extension import BrowserExtension +from .browsers.browser_telemetry_config import BrowserTelemetryConfig __all__ = ["BrowserPool", "BrowserPoolConfig", "BrowserPoolConfigProfile"] @@ -110,6 +111,12 @@ class BrowserPoolConfig(BaseModel): mechanisms. """ + telemetry: Optional[BrowserTelemetryConfig] = None + """ + Active telemetry configuration applied to browsers warmed into this pool, if + any. + """ + timeout_seconds: Optional[int] = None """ Default idle timeout in seconds for browsers acquired from this pool before they diff --git a/src/kernel/types/browser_pool_acquire_params.py b/src/kernel/types/browser_pool_acquire_params.py index 80b9be2..70567ee 100644 --- a/src/kernel/types/browser_pool_acquire_params.py +++ b/src/kernel/types/browser_pool_acquire_params.py @@ -2,11 +2,13 @@ from __future__ import annotations +from typing import Optional from typing_extensions import TypedDict from .tags_param import TagsParam +from .browsers.browser_telemetry_categories_config_param import BrowserTelemetryCategoriesConfigParam -__all__ = ["BrowserPoolAcquireParams"] +__all__ = ["BrowserPoolAcquireParams", "Telemetry"] class BrowserPoolAcquireParams(TypedDict, total=False): @@ -38,3 +40,49 @@ class BrowserPoolAcquireParams(TypedDict, total=False): find and group sessions later. Applies to this lease only and are cleared when the browser is released back to the pool. Up to 50 pairs. """ + + telemetry: Optional[Telemetry] + """Telemetry override for the acquired browser, applied to this lease only. + + Merges onto the browser's current (pool-inherited) telemetry using the same + per-category semantics as PATCH /browsers: provided categories override the + current configuration, omitted categories are inherited. Set enabled to true to + resolve the config fresh from the default set, or enabled to false to stop + capture. When the browser is released back to the pool with reuse, its telemetry + is reset to the pool's baseline, so the override does not carry over to the next + lease. + """ + + +class Telemetry(TypedDict, total=False): + """Telemetry override for the acquired browser, applied to this lease only. + + Merges onto the browser's current (pool-inherited) telemetry using the same per-category semantics as PATCH /browsers: provided categories override the current configuration, omitted categories are inherited. Set enabled to true to resolve the config fresh from the default set, or enabled to false to stop capture. When the browser is released back to the pool with reuse, its telemetry is reset to the pool's baseline, so the override does not carry over to the next lease. + """ + + browser: BrowserTelemetryCategoriesConfigParam + """Per-category capture flags. + + The operational categories (control, connection, system, captcha) are captured + whenever telemetry is enabled; set one to enabled=false to opt out. The CDP + categories (console, network, page, interaction) and screenshot are off by + default; set enabled=true to opt in. On create, provided categories layer onto + the default set. On update, provided categories merge onto the session's current + config; when no telemetry is active this falls back to the default set (matching + create). If browser is omitted or empty, the default set is used. A browser + config that disables every category stops capture on update and starts no + capture on create. + """ + + enabled: bool + """Request shortcut for browser telemetry capture. + + True enables capture; with no browser category settings it captures the default + set (control, connection, system, captcha), and any browser category settings + are layered onto that default set. On update, enabled=true resolves the config + fresh from the default set plus any provided categories, replacing the session's + current selection rather than merging onto it; omit enabled to merge categories + onto the current selection instead. False stops capture on update and starts no + capture on create. enabled=false cannot be combined with browser category + settings. + """ diff --git a/src/kernel/types/browser_pool_create_params.py b/src/kernel/types/browser_pool_create_params.py index cd6573b..376af6b 100644 --- a/src/kernel/types/browser_pool_create_params.py +++ b/src/kernel/types/browser_pool_create_params.py @@ -2,13 +2,14 @@ from __future__ import annotations -from typing import Dict, Iterable +from typing import Dict, Iterable, Optional from typing_extensions import Required, TypedDict from .shared_params.browser_viewport import BrowserViewport from .shared_params.browser_extension import BrowserExtension +from .browsers.browser_telemetry_categories_config_param import BrowserTelemetryCategoriesConfigParam -__all__ = ["BrowserPoolCreateParams", "Profile"] +__all__ = ["BrowserPoolCreateParams", "Profile", "Telemetry"] class BrowserPoolCreateParams(TypedDict, total=False): @@ -90,6 +91,16 @@ class BrowserPoolCreateParams(TypedDict, total=False): mechanisms. Defaults to false. """ + telemetry: Optional[Telemetry] + """Telemetry configuration applied to browsers warmed into this pool. + + Set enabled to true to start capture using the default set, or provide browser + category settings. If omitted, null, set to an empty object ({}), set to + enabled: false without browser category settings, or all four CDP categories are + explicitly disabled, no telemetry is configured on the pool. Only applied to + newly-warmed browsers. + """ + timeout_seconds: int """ Default idle timeout in seconds for browsers acquired from this pool before they @@ -130,3 +141,37 @@ class Profile(TypedDict, total=False): Must be 1-255 characters, using letters, numbers, dots, underscores, or hyphens. """ + + +class Telemetry(TypedDict, total=False): + """Telemetry configuration applied to browsers warmed into this pool. + + Set enabled to true to start capture using the default set, or provide browser category settings. If omitted, null, set to an empty object ({}), set to enabled: false without browser category settings, or all four CDP categories are explicitly disabled, no telemetry is configured on the pool. Only applied to newly-warmed browsers. + """ + + browser: BrowserTelemetryCategoriesConfigParam + """Per-category capture flags. + + The operational categories (control, connection, system, captcha) are captured + whenever telemetry is enabled; set one to enabled=false to opt out. The CDP + categories (console, network, page, interaction) and screenshot are off by + default; set enabled=true to opt in. On create, provided categories layer onto + the default set. On update, provided categories merge onto the session's current + config; when no telemetry is active this falls back to the default set (matching + create). If browser is omitted or empty, the default set is used. A browser + config that disables every category stops capture on update and starts no + capture on create. + """ + + enabled: bool + """Request shortcut for browser telemetry capture. + + True enables capture; with no browser category settings it captures the default + set (control, connection, system, captcha), and any browser category settings + are layered onto that default set. On update, enabled=true resolves the config + fresh from the default set plus any provided categories, replacing the session's + current selection rather than merging onto it; omit enabled to merge categories + onto the current selection instead. False stops capture on update and starts no + capture on create. enabled=false cannot be combined with browser category + settings. + """ diff --git a/src/kernel/types/browser_pool_update_params.py b/src/kernel/types/browser_pool_update_params.py index a4c6557..b095604 100644 --- a/src/kernel/types/browser_pool_update_params.py +++ b/src/kernel/types/browser_pool_update_params.py @@ -2,13 +2,14 @@ from __future__ import annotations -from typing import Dict, Iterable +from typing import Dict, Iterable, Optional from typing_extensions import TypedDict from .shared_params.browser_viewport import BrowserViewport from .shared_params.browser_extension import BrowserExtension +from .browsers.browser_telemetry_categories_config_param import BrowserTelemetryCategoriesConfigParam -__all__ = ["BrowserPoolUpdateParams", "Profile"] +__all__ = ["BrowserPoolUpdateParams", "Profile", "Telemetry"] class BrowserPoolUpdateParams(TypedDict, total=False): @@ -100,6 +101,17 @@ class BrowserPoolUpdateParams(TypedDict, total=False): stealth: bool """If provided, replaces whether browsers launch in stealth mode.""" + telemetry: Optional[Telemetry] + """If provided, updates the pool's telemetry configuration. + + Omit, set to null, or set to an empty object ({}) to leave the existing + configuration unchanged. Set enabled to true to enable capture using the default + set. Set enabled to false to clear the pool's telemetry. Provide browser + category settings for per-category updates, merged onto the pool's current + configuration. Only applied to browsers warmed after the update; browsers + already in the pool keep their configuration until discarded. + """ + timeout_seconds: int """ If provided, replaces the default idle timeout in seconds for browsers acquired @@ -140,3 +152,37 @@ class Profile(TypedDict, total=False): Must be 1-255 characters, using letters, numbers, dots, underscores, or hyphens. """ + + +class Telemetry(TypedDict, total=False): + """If provided, updates the pool's telemetry configuration. + + Omit, set to null, or set to an empty object ({}) to leave the existing configuration unchanged. Set enabled to true to enable capture using the default set. Set enabled to false to clear the pool's telemetry. Provide browser category settings for per-category updates, merged onto the pool's current configuration. Only applied to browsers warmed after the update; browsers already in the pool keep their configuration until discarded. + """ + + browser: BrowserTelemetryCategoriesConfigParam + """Per-category capture flags. + + The operational categories (control, connection, system, captcha) are captured + whenever telemetry is enabled; set one to enabled=false to opt out. The CDP + categories (console, network, page, interaction) and screenshot are off by + default; set enabled=true to opt in. On create, provided categories layer onto + the default set. On update, provided categories merge onto the session's current + config; when no telemetry is active this falls back to the default set (matching + create). If browser is omitted or empty, the default set is used. A browser + config that disables every category stops capture on update and starts no + capture on create. + """ + + enabled: bool + """Request shortcut for browser telemetry capture. + + True enables capture; with no browser category settings it captures the default + set (control, connection, system, captcha), and any browser category settings + are layered onto that default set. On update, enabled=true resolves the config + fresh from the default set plus any provided categories, replacing the session's + current selection rather than merging onto it; omit enabled to merge categories + onto the current selection instead. False stops capture on update and starts no + capture on create. enabled=false cannot be combined with browser category + settings. + """ diff --git a/tests/api_resources/test_browser_pools.py b/tests/api_resources/test_browser_pools.py index 6f79fc8..3165778 100644 --- a/tests/api_resources/test_browser_pools.py +++ b/tests/api_resources/test_browser_pools.py @@ -53,6 +53,20 @@ def test_method_create_with_all_params(self, client: Kernel) -> None: refresh_on_profile_update=True, start_url="https://example.com", stealth=True, + telemetry={ + "browser": { + "captcha": {"enabled": True}, + "connection": {"enabled": True}, + "console": {"enabled": True}, + "control": {"enabled": True}, + "interaction": {"enabled": True}, + "network": {"enabled": True}, + "page": {"enabled": True}, + "screenshot": {"enabled": True}, + "system": {"enabled": True}, + }, + "enabled": True, + }, timeout_seconds=10, viewport={ "height": 800, @@ -164,6 +178,20 @@ def test_method_update_with_all_params(self, client: Kernel) -> None: size=10, start_url="https://example.com", stealth=True, + telemetry={ + "browser": { + "captcha": {"enabled": True}, + "connection": {"enabled": True}, + "console": {"enabled": True}, + "control": {"enabled": True}, + "interaction": {"enabled": True}, + "network": {"enabled": True}, + "page": {"enabled": True}, + "screenshot": {"enabled": True}, + "system": {"enabled": True}, + }, + "enabled": True, + }, timeout_seconds=10, viewport={ "height": 800, @@ -317,6 +345,20 @@ def test_method_acquire_with_all_params(self, client: Kernel) -> None: "team": "backend", "env": "staging", }, + telemetry={ + "browser": { + "captcha": {"enabled": True}, + "connection": {"enabled": True}, + "console": {"enabled": True}, + "control": {"enabled": True}, + "interaction": {"enabled": True}, + "network": {"enabled": True}, + "page": {"enabled": True}, + "screenshot": {"enabled": True}, + "system": {"enabled": True}, + }, + "enabled": True, + }, ) assert_matches_type(BrowserPoolAcquireResponse, browser_pool, path=["response"]) @@ -490,6 +532,20 @@ async def test_method_create_with_all_params(self, async_client: AsyncKernel) -> refresh_on_profile_update=True, start_url="https://example.com", stealth=True, + telemetry={ + "browser": { + "captcha": {"enabled": True}, + "connection": {"enabled": True}, + "console": {"enabled": True}, + "control": {"enabled": True}, + "interaction": {"enabled": True}, + "network": {"enabled": True}, + "page": {"enabled": True}, + "screenshot": {"enabled": True}, + "system": {"enabled": True}, + }, + "enabled": True, + }, timeout_seconds=10, viewport={ "height": 800, @@ -601,6 +657,20 @@ async def test_method_update_with_all_params(self, async_client: AsyncKernel) -> size=10, start_url="https://example.com", stealth=True, + telemetry={ + "browser": { + "captcha": {"enabled": True}, + "connection": {"enabled": True}, + "console": {"enabled": True}, + "control": {"enabled": True}, + "interaction": {"enabled": True}, + "network": {"enabled": True}, + "page": {"enabled": True}, + "screenshot": {"enabled": True}, + "system": {"enabled": True}, + }, + "enabled": True, + }, timeout_seconds=10, viewport={ "height": 800, @@ -754,6 +824,20 @@ async def test_method_acquire_with_all_params(self, async_client: AsyncKernel) - "team": "backend", "env": "staging", }, + telemetry={ + "browser": { + "captcha": {"enabled": True}, + "connection": {"enabled": True}, + "console": {"enabled": True}, + "control": {"enabled": True}, + "interaction": {"enabled": True}, + "network": {"enabled": True}, + "page": {"enabled": True}, + "screenshot": {"enabled": True}, + "system": {"enabled": True}, + }, + "enabled": True, + }, ) assert_matches_type(BrowserPoolAcquireResponse, browser_pool, path=["response"])