diff --git a/api.md b/api.md index 7de716a0..65ac4c06 100644 --- a/api.md +++ b/api.md @@ -81,6 +81,9 @@ Types: ```python from kernel.types import ( BrowserPoolRef, + BrowserProxy, + BrowserProxyConfig, + BrowserProxyMode, BrowserUsage, Profile, Tags, @@ -314,6 +317,7 @@ Types: from kernel.types.auth import ( LoginResponse, ManagedAuth, + ManagedAuthBrowserConfig, ManagedAuthCreateRequest, ManagedAuthTimelineEvent, ManagedAuthUpdateRequest, diff --git a/src/kernel/resources/auth/connections.py b/src/kernel/resources/auth/connections.py index f5f4529a..56785ea2 100644 --- a/src/kernel/resources/auth/connections.py +++ b/src/kernel/resources/auth/connections.py @@ -33,6 +33,7 @@ from ...types.auth.submit_fields_response import SubmitFieldsResponse from ...types.auth.connection_follow_response import ConnectionFollowResponse from ...types.auth.managed_auth_timeline_event import ManagedAuthTimelineEvent +from ...types.auth.managed_auth_browser_config_param import ManagedAuthBrowserConfigParam __all__ = ["ConnectionsResource", "AsyncConnectionsResource"] @@ -66,6 +67,7 @@ def create( profile_name: str, allowed_domains: SequenceNotStr[str] | Omit = omit, auto_reauth: bool | Omit = omit, + browser: ManagedAuthBrowserConfigParam | Omit = omit, browser_telemetry: Optional[connection_create_params.BrowserTelemetry] | Omit = omit, credential: connection_create_params.Credential | Omit = omit, health_check_interval: int | Omit = omit, @@ -120,9 +122,11 @@ def create( false, expired sessions are marked as `NEEDS_AUTH` instead of attempting re-auth. Defaults to true. - browser_telemetry: Browser telemetry configuration used by this connection's browser sessions by - default. Uses the exact create-browser configuration. Can be overridden - per-login. + browser: Default browser configuration for login, reauthentication, and health-check + sessions. + + browser_telemetry: Deprecated. Use browser.telemetry. Retained during migration for existing + clients. credential: Reference to credentials for the auth connection. Use one of: @@ -133,9 +137,10 @@ def create( health_check_interval: Interval in seconds between automatic health checks. When set, the system periodically verifies the authentication status and triggers re-authentication - if needed. Maximum is 86400 (24 hours). Default is 3600 (1 hour). The minimum - depends on your plan: Enterprise: 300 (5 minutes), Startup: 1200 (20 minutes), - Hobbyist: 3600 (1 hour). + if needed. Maximum is 86400 (24 hours). Default is 3600 (1 hour) or your plan + minimum, whichever is larger. The minimum depends on your plan: Enterprise: 300 + (5 minutes), Startup: 1200 (20 minutes), Hobbyist: 3600 (1 hour), Free: 21600 (6 + hours). health_checks: Whether to enable periodic health checks. When false, the system will not automatically verify authentication status, and `auto_reauth` has no effect on @@ -144,10 +149,7 @@ def create( login_url: Optional login page URL to skip discovery - proxy: Proxy selection. Provide either id or name. The proxy must be in the same - project as the resource referencing it. When selecting by name, the name must - match exactly one active proxy in the project. Ambiguous names return a 400; use - id for stable references. + proxy: Deprecated. Use browser.proxy. Retained during migration for existing clients. record_session: Whether to record browser sessions for this connection by default. Useful for debugging. Can be overridden per-login. Defaults to false. @@ -171,6 +173,7 @@ def create( "profile_name": profile_name, "allowed_domains": allowed_domains, "auto_reauth": auto_reauth, + "browser": browser, "browser_telemetry": browser_telemetry, "credential": credential, "health_check_interval": health_check_interval, @@ -229,6 +232,7 @@ def update( *, allowed_domains: SequenceNotStr[str] | Omit = omit, auto_reauth: bool | Omit = omit, + browser: ManagedAuthBrowserConfigParam | Omit = omit, browser_telemetry: Optional[connection_update_params.BrowserTelemetry] | Omit = omit, credential: connection_update_params.Credential | Omit = omit, health_check_interval: int | Omit = omit, @@ -260,9 +264,11 @@ def update( when `health_checks` is false. When false, expired sessions detected by a health check are marked as `NEEDS_AUTH` instead of attempting re-auth. - browser_telemetry: Browser telemetry configuration used by future browser sessions for this - connection. Uses the exact create-browser configuration. Set enabled to false to - disable telemetry. + browser: Browser configuration updates for future login, reauthentication, and + health-check sessions. Omitted properties remain unchanged. + + browser_telemetry: Deprecated. Use browser.telemetry. Retained during migration for existing + clients. credential: Reference to credentials for the auth connection. Use one of: @@ -280,10 +286,7 @@ def update( login_url: Login page URL. Set to empty string to clear. - proxy: Proxy selection. Provide either id or name. The proxy must be in the same - project as the resource referencing it. When selecting by name, the name must - match exactly one active proxy in the project. Ambiguous names return a 400; use - id for stable references. + proxy: Deprecated. Use browser.proxy. Retained during migration for existing clients. record_session: Whether to record browser sessions for this connection by default @@ -305,6 +308,7 @@ def update( { "allowed_domains": allowed_domains, "auto_reauth": auto_reauth, + "browser": browser, "browser_telemetry": browser_telemetry, "credential": credential, "health_check_interval": health_check_interval, @@ -464,6 +468,7 @@ def login( self, id: str, *, + browser: ManagedAuthBrowserConfigParam | Omit = omit, browser_telemetry: Optional[connection_login_params.BrowserTelemetry] | Omit = omit, proxy: connection_login_params.Proxy | Omit = omit, record_session: bool | Omit = omit, @@ -481,14 +486,13 @@ def login( credentials are stored. Args: - browser_telemetry: Override the connection's default browser telemetry configuration for this - login. When omitted, the connection's browser_telemetry default is used. Uses - the exact create-browser configuration. + browser: Browser configuration override for this login. Omitted properties inherit the + connection defaults. + + browser_telemetry: Deprecated. Use browser.telemetry. Retained during migration for existing + clients. - proxy: Proxy selection. Provide either id or name. The proxy must be in the same - project as the resource referencing it. When selecting by name, the name must - match exactly one active proxy in the project. Ambiguous names return a 400; use - id for stable references. + proxy: Deprecated. Use browser.proxy. Retained during migration for existing clients. record_session: Override the connection's default for recording this login's browser session. When omitted, the connection's record_session default is used. @@ -507,6 +511,7 @@ def login( path_template("/auth/connections/{id}/login", id=id), body=maybe_transform( { + "browser": browser, "browser_telemetry": browser_telemetry, "proxy": proxy, "record_session": record_session, @@ -675,6 +680,7 @@ async def create( profile_name: str, allowed_domains: SequenceNotStr[str] | Omit = omit, auto_reauth: bool | Omit = omit, + browser: ManagedAuthBrowserConfigParam | Omit = omit, browser_telemetry: Optional[connection_create_params.BrowserTelemetry] | Omit = omit, credential: connection_create_params.Credential | Omit = omit, health_check_interval: int | Omit = omit, @@ -729,9 +735,11 @@ async def create( false, expired sessions are marked as `NEEDS_AUTH` instead of attempting re-auth. Defaults to true. - browser_telemetry: Browser telemetry configuration used by this connection's browser sessions by - default. Uses the exact create-browser configuration. Can be overridden - per-login. + browser: Default browser configuration for login, reauthentication, and health-check + sessions. + + browser_telemetry: Deprecated. Use browser.telemetry. Retained during migration for existing + clients. credential: Reference to credentials for the auth connection. Use one of: @@ -742,9 +750,10 @@ async def create( health_check_interval: Interval in seconds between automatic health checks. When set, the system periodically verifies the authentication status and triggers re-authentication - if needed. Maximum is 86400 (24 hours). Default is 3600 (1 hour). The minimum - depends on your plan: Enterprise: 300 (5 minutes), Startup: 1200 (20 minutes), - Hobbyist: 3600 (1 hour). + if needed. Maximum is 86400 (24 hours). Default is 3600 (1 hour) or your plan + minimum, whichever is larger. The minimum depends on your plan: Enterprise: 300 + (5 minutes), Startup: 1200 (20 minutes), Hobbyist: 3600 (1 hour), Free: 21600 (6 + hours). health_checks: Whether to enable periodic health checks. When false, the system will not automatically verify authentication status, and `auto_reauth` has no effect on @@ -753,10 +762,7 @@ async def create( login_url: Optional login page URL to skip discovery - proxy: Proxy selection. Provide either id or name. The proxy must be in the same - project as the resource referencing it. When selecting by name, the name must - match exactly one active proxy in the project. Ambiguous names return a 400; use - id for stable references. + proxy: Deprecated. Use browser.proxy. Retained during migration for existing clients. record_session: Whether to record browser sessions for this connection by default. Useful for debugging. Can be overridden per-login. Defaults to false. @@ -780,6 +786,7 @@ async def create( "profile_name": profile_name, "allowed_domains": allowed_domains, "auto_reauth": auto_reauth, + "browser": browser, "browser_telemetry": browser_telemetry, "credential": credential, "health_check_interval": health_check_interval, @@ -838,6 +845,7 @@ async def update( *, allowed_domains: SequenceNotStr[str] | Omit = omit, auto_reauth: bool | Omit = omit, + browser: ManagedAuthBrowserConfigParam | Omit = omit, browser_telemetry: Optional[connection_update_params.BrowserTelemetry] | Omit = omit, credential: connection_update_params.Credential | Omit = omit, health_check_interval: int | Omit = omit, @@ -869,9 +877,11 @@ async def update( when `health_checks` is false. When false, expired sessions detected by a health check are marked as `NEEDS_AUTH` instead of attempting re-auth. - browser_telemetry: Browser telemetry configuration used by future browser sessions for this - connection. Uses the exact create-browser configuration. Set enabled to false to - disable telemetry. + browser: Browser configuration updates for future login, reauthentication, and + health-check sessions. Omitted properties remain unchanged. + + browser_telemetry: Deprecated. Use browser.telemetry. Retained during migration for existing + clients. credential: Reference to credentials for the auth connection. Use one of: @@ -889,10 +899,7 @@ async def update( login_url: Login page URL. Set to empty string to clear. - proxy: Proxy selection. Provide either id or name. The proxy must be in the same - project as the resource referencing it. When selecting by name, the name must - match exactly one active proxy in the project. Ambiguous names return a 400; use - id for stable references. + proxy: Deprecated. Use browser.proxy. Retained during migration for existing clients. record_session: Whether to record browser sessions for this connection by default @@ -914,6 +921,7 @@ async def update( { "allowed_domains": allowed_domains, "auto_reauth": auto_reauth, + "browser": browser, "browser_telemetry": browser_telemetry, "credential": credential, "health_check_interval": health_check_interval, @@ -1073,6 +1081,7 @@ async def login( self, id: str, *, + browser: ManagedAuthBrowserConfigParam | Omit = omit, browser_telemetry: Optional[connection_login_params.BrowserTelemetry] | Omit = omit, proxy: connection_login_params.Proxy | Omit = omit, record_session: bool | Omit = omit, @@ -1090,14 +1099,13 @@ async def login( credentials are stored. Args: - browser_telemetry: Override the connection's default browser telemetry configuration for this - login. When omitted, the connection's browser_telemetry default is used. Uses - the exact create-browser configuration. + browser: Browser configuration override for this login. Omitted properties inherit the + connection defaults. + + browser_telemetry: Deprecated. Use browser.telemetry. Retained during migration for existing + clients. - proxy: Proxy selection. Provide either id or name. The proxy must be in the same - project as the resource referencing it. When selecting by name, the name must - match exactly one active proxy in the project. Ambiguous names return a 400; use - id for stable references. + proxy: Deprecated. Use browser.proxy. Retained during migration for existing clients. record_session: Override the connection's default for recording this login's browser session. When omitted, the connection's record_session default is used. @@ -1116,6 +1124,7 @@ async def login( path_template("/auth/connections/{id}/login", id=id), body=await async_maybe_transform( { + "browser": browser, "browser_telemetry": browser_telemetry, "proxy": proxy, "record_session": record_session, diff --git a/src/kernel/resources/browsers/browsers.py b/src/kernel/resources/browsers/browsers.py index 553a98dd..19f48988 100644 --- a/src/kernel/resources/browsers/browsers.py +++ b/src/kernel/resources/browsers/browsers.py @@ -97,6 +97,7 @@ from ...types.browser_create_response import BrowserCreateResponse from ...types.browser_update_response import BrowserUpdateResponse from ...types.browser_retrieve_response import BrowserRetrieveResponse +from ...types.browser_proxy_config_param import BrowserProxyConfigParam from ...types.shared_params.browser_profile import BrowserProfile from ...types.shared_params.browser_viewport import BrowserViewport from ...types.shared_params.browser_extension import BrowserExtension @@ -172,6 +173,7 @@ def create( kiosk_mode: bool | Omit = omit, name: str | Omit = omit, profile: BrowserProfile | Omit = omit, + proxy: BrowserProxyConfigParam | Omit = omit, proxy_id: str | Omit = omit, start_url: str | Omit = omit, stealth: bool | Omit = omit, @@ -216,15 +218,26 @@ def create( specified, the matching profile will be loaded into the browser session. Profiles must be created beforehand. + proxy: Proxy configuration for the browser session. Cannot be combined with proxy_id. + Omit to use the browser default: stealth browsers use Kernel's default stealth + proxy, while non-stealth browsers use direct egress. Set mode to direct to force + direct egress regardless of stealth. Set mode to default to explicitly use the + browser default: Kernel's default stealth proxy when stealth=true, or direct + egress when stealth=false. Select id or name to use that proxy regardless of + stealth. Proxy selection does not change stealth or CAPTCHA solver behavior. + proxy_id: Optional proxy to associate to the browser session. Must reference a proxy in - the same project as the browser session. + the same project as the browser session. Deprecated in favor of proxy. start_url: Optional URL to open when the browser session is created. Navigation is best-effort, so navigation failures do not prevent the session from being created. - stealth: If true, launches the browser in stealth mode to reduce detection by anti-bot - mechanisms. + stealth: If true, launches the browser in stealth mode and enables the CAPTCHA solver. + Defaults to false. When proxy is omitted, stealth browsers use Kernel's default + stealth proxy and non-stealth browsers use direct egress. An explicit proxy + configuration changes only egress; it does not enable or disable stealth or the + CAPTCHA solver. tags: Optional user-defined key-value tags for the browser session, used to find and group sessions later. Can be changed later via PATCH /browsers/{id_or_name}. Up @@ -275,6 +288,7 @@ def create( "kiosk_mode": kiosk_mode, "name": name, "profile": profile, + "proxy": proxy, "proxy_id": proxy_id, "start_url": start_url, "stealth": stealth, @@ -340,6 +354,7 @@ def update( disable_default_proxy: bool | Omit = omit, name: Optional[str] | Omit = omit, profile: BrowserProfile | Omit = omit, + proxy: BrowserProxyConfigParam | Omit = omit, proxy_id: Optional[str] | Omit = omit, tags: Optional[TagsParam] | Omit = omit, telemetry: Optional[browser_update_params.Telemetry] | Omit = omit, @@ -356,7 +371,7 @@ def update( Args: disable_default_proxy: If true, stealth browsers connect directly instead of using the default stealth - proxy. + proxy. Deprecated in favor of proxy.mode. name: Human-readable name for the browser session. Omit to leave unchanged, set to an empty string to clear the name. When set, must be unique among active sessions @@ -365,8 +380,15 @@ def update( profile: Profile to load into the browser session. Only allowed if the session does not already have a profile loaded. + proxy: Proxy configuration to apply. Omit to leave the current configuration unchanged. + Cannot be combined with proxy_id or disable_default_proxy. Set mode to direct to + switch to direct egress regardless of stealth. Set mode to default to restore + the browser default after using a selected proxy: Kernel's default stealth proxy + for a stealth browser, or direct egress for a non-stealth browser. Updating + proxy does not change stealth or CAPTCHA solver behavior. + proxy_id: ID of the proxy to use. Omit to leave unchanged, set to empty string to remove - proxy. + proxy. Deprecated in favor of proxy. tags: User-defined key-value tags for the browser session. Omit to leave unchanged. Provide a map to replace the entire tag set (full replace, not a merge). Set to @@ -397,6 +419,7 @@ def update( "disable_default_proxy": disable_default_proxy, "name": name, "profile": profile, + "proxy": proxy, "proxy_id": proxy_id, "tags": tags, "telemetry": telemetry, @@ -750,6 +773,7 @@ async def create( kiosk_mode: bool | Omit = omit, name: str | Omit = omit, profile: BrowserProfile | Omit = omit, + proxy: BrowserProxyConfigParam | Omit = omit, proxy_id: str | Omit = omit, start_url: str | Omit = omit, stealth: bool | Omit = omit, @@ -794,15 +818,26 @@ async def create( specified, the matching profile will be loaded into the browser session. Profiles must be created beforehand. + proxy: Proxy configuration for the browser session. Cannot be combined with proxy_id. + Omit to use the browser default: stealth browsers use Kernel's default stealth + proxy, while non-stealth browsers use direct egress. Set mode to direct to force + direct egress regardless of stealth. Set mode to default to explicitly use the + browser default: Kernel's default stealth proxy when stealth=true, or direct + egress when stealth=false. Select id or name to use that proxy regardless of + stealth. Proxy selection does not change stealth or CAPTCHA solver behavior. + proxy_id: Optional proxy to associate to the browser session. Must reference a proxy in - the same project as the browser session. + the same project as the browser session. Deprecated in favor of proxy. start_url: Optional URL to open when the browser session is created. Navigation is best-effort, so navigation failures do not prevent the session from being created. - stealth: If true, launches the browser in stealth mode to reduce detection by anti-bot - mechanisms. + stealth: If true, launches the browser in stealth mode and enables the CAPTCHA solver. + Defaults to false. When proxy is omitted, stealth browsers use Kernel's default + stealth proxy and non-stealth browsers use direct egress. An explicit proxy + configuration changes only egress; it does not enable or disable stealth or the + CAPTCHA solver. tags: Optional user-defined key-value tags for the browser session, used to find and group sessions later. Can be changed later via PATCH /browsers/{id_or_name}. Up @@ -853,6 +888,7 @@ async def create( "kiosk_mode": kiosk_mode, "name": name, "profile": profile, + "proxy": proxy, "proxy_id": proxy_id, "start_url": start_url, "stealth": stealth, @@ -918,6 +954,7 @@ async def update( disable_default_proxy: bool | Omit = omit, name: Optional[str] | Omit = omit, profile: BrowserProfile | Omit = omit, + proxy: BrowserProxyConfigParam | Omit = omit, proxy_id: Optional[str] | Omit = omit, tags: Optional[TagsParam] | Omit = omit, telemetry: Optional[browser_update_params.Telemetry] | Omit = omit, @@ -934,7 +971,7 @@ async def update( Args: disable_default_proxy: If true, stealth browsers connect directly instead of using the default stealth - proxy. + proxy. Deprecated in favor of proxy.mode. name: Human-readable name for the browser session. Omit to leave unchanged, set to an empty string to clear the name. When set, must be unique among active sessions @@ -943,8 +980,15 @@ async def update( profile: Profile to load into the browser session. Only allowed if the session does not already have a profile loaded. + proxy: Proxy configuration to apply. Omit to leave the current configuration unchanged. + Cannot be combined with proxy_id or disable_default_proxy. Set mode to direct to + switch to direct egress regardless of stealth. Set mode to default to restore + the browser default after using a selected proxy: Kernel's default stealth proxy + for a stealth browser, or direct egress for a non-stealth browser. Updating + proxy does not change stealth or CAPTCHA solver behavior. + proxy_id: ID of the proxy to use. Omit to leave unchanged, set to empty string to remove - proxy. + proxy. Deprecated in favor of proxy. tags: User-defined key-value tags for the browser session. Omit to leave unchanged. Provide a map to replace the entire tag set (full replace, not a merge). Set to @@ -975,6 +1019,7 @@ async def update( "disable_default_proxy": disable_default_proxy, "name": name, "profile": profile, + "proxy": proxy, "proxy_id": proxy_id, "tags": tags, "telemetry": telemetry, diff --git a/src/kernel/types/__init__.py b/src/kernel/types/__init__.py index ab58edbc..e86ac9c4 100644 --- a/src/kernel/types/__init__.py +++ b/src/kernel/types/__init__.py @@ -22,6 +22,7 @@ from .credential import Credential as Credential from .tags_param import TagsParam as TagsParam from .browser_pool import BrowserPool as BrowserPool +from .browser_proxy import BrowserProxy as BrowserProxy from .browser_usage import BrowserUsage as BrowserUsage from .app_list_params import AppListParams as AppListParams from .audit_log_entry import AuditLogEntry as AuditLogEntry @@ -29,6 +30,7 @@ from .browser_pool_ref import BrowserPoolRef as BrowserPoolRef from .app_list_response import AppListResponse as AppListResponse from .proxy_list_params import ProxyListParams as ProxyListParams +from .browser_proxy_mode import BrowserProxyMode as BrowserProxyMode from .proxy_check_params import ProxyCheckParams as ProxyCheckParams from .api_key_list_params import APIKeyListParams as APIKeyListParams from .browser_curl_params import BrowserCurlParams as BrowserCurlParams @@ -39,6 +41,7 @@ from .proxy_create_params import ProxyCreateParams as ProxyCreateParams from .proxy_list_response import ProxyListResponse as ProxyListResponse from .proxy_update_params import ProxyUpdateParams as ProxyUpdateParams +from .browser_proxy_config import BrowserProxyConfig as BrowserProxyConfig from .proxy_check_response import ProxyCheckResponse as ProxyCheckResponse from .api_key_create_params import APIKeyCreateParams as APIKeyCreateParams from .api_key_rotate_params import APIKeyRotateParams as APIKeyRotateParams @@ -85,6 +88,7 @@ from .browser_pool_create_params import BrowserPoolCreateParams as BrowserPoolCreateParams from .browser_pool_delete_params import BrowserPoolDeleteParams as BrowserPoolDeleteParams from .browser_pool_update_params import BrowserPoolUpdateParams as BrowserPoolUpdateParams +from .browser_proxy_config_param import BrowserProxyConfigParam as BrowserProxyConfigParam from .deployment_create_response import DeploymentCreateResponse as DeploymentCreateResponse from .deployment_follow_response import DeploymentFollowResponse as DeploymentFollowResponse from .invocation_create_response import InvocationCreateResponse as InvocationCreateResponse diff --git a/src/kernel/types/auth/__init__.py b/src/kernel/types/auth/__init__.py index 2d0cf1b0..ced593b0 100644 --- a/src/kernel/types/auth/__init__.py +++ b/src/kernel/types/auth/__init__.py @@ -13,4 +13,6 @@ from .connection_update_params import ConnectionUpdateParams as ConnectionUpdateParams from .connection_follow_response import ConnectionFollowResponse as ConnectionFollowResponse from .connection_timeline_params import ConnectionTimelineParams as ConnectionTimelineParams +from .managed_auth_browser_config import ManagedAuthBrowserConfig as ManagedAuthBrowserConfig from .managed_auth_timeline_event import ManagedAuthTimelineEvent as ManagedAuthTimelineEvent +from .managed_auth_browser_config_param import ManagedAuthBrowserConfigParam as ManagedAuthBrowserConfigParam diff --git a/src/kernel/types/auth/connection_create_params.py b/src/kernel/types/auth/connection_create_params.py index 407857be..2fdc808b 100644 --- a/src/kernel/types/auth/connection_create_params.py +++ b/src/kernel/types/auth/connection_create_params.py @@ -6,6 +6,7 @@ from typing_extensions import Required, TypedDict from ..._types import SequenceNotStr +from .managed_auth_browser_config_param import ManagedAuthBrowserConfigParam from ..browsers.browser_telemetry_categories_config_param import BrowserTelemetryCategoriesConfigParam __all__ = [ @@ -62,11 +63,16 @@ class ConnectionCreateParams(TypedDict, total=False): re-auth. Defaults to true. """ - browser_telemetry: Optional[BrowserTelemetry] + browser: ManagedAuthBrowserConfigParam + """ + Default browser configuration for login, reauthentication, and health-check + sessions. """ - Browser telemetry configuration used by this connection's browser sessions by - default. Uses the exact create-browser configuration. Can be overridden - per-login. + + browser_telemetry: Optional[BrowserTelemetry] + """Deprecated. + + Use browser.telemetry. Retained during migration for existing clients. """ credential: Credential @@ -82,8 +88,9 @@ class ConnectionCreateParams(TypedDict, total=False): When set, the system periodically verifies the authentication status and triggers re-authentication if needed. Maximum is 86400 (24 hours). Default is - 3600 (1 hour). The minimum depends on your plan: Enterprise: 300 (5 minutes), - Startup: 1200 (20 minutes), Hobbyist: 3600 (1 hour). + 3600 (1 hour) or your plan minimum, whichever is larger. The minimum depends on + your plan: Enterprise: 300 (5 minutes), Startup: 1200 (20 minutes), Hobbyist: + 3600 (1 hour), Free: 21600 (6 hours). """ health_checks: bool @@ -98,13 +105,7 @@ class ConnectionCreateParams(TypedDict, total=False): """Optional login page URL to skip discovery""" proxy: Proxy - """Proxy selection. - - Provide either id or name. The proxy must be in the same project as the resource - referencing it. When selecting by name, the name must match exactly one active - proxy in the project. Ambiguous names return a 400; use id for stable - references. - """ + """Deprecated. Use browser.proxy. Retained during migration for existing clients.""" record_session: bool """Whether to record browser sessions for this connection by default. @@ -164,8 +165,9 @@ class BrowserTelemetryExport(TypedDict, total=False): class BrowserTelemetry(TypedDict, total=False): - """ - Browser telemetry configuration used by this connection's browser sessions by default. Uses the exact create-browser configuration. Can be overridden per-login. + """Deprecated. + + Use browser.telemetry. Retained during migration for existing clients. """ browser: BrowserTelemetryCategoriesConfigParam @@ -225,11 +227,7 @@ class Credential(TypedDict, total=False): class Proxy(TypedDict, total=False): - """Proxy selection. - - Provide either id or name. The proxy must be in the same project as the resource referencing it. - When selecting by name, the name must match exactly one active proxy in the project. Ambiguous names return a 400; use id for stable references. - """ + """Deprecated. Use browser.proxy. Retained during migration for existing clients.""" id: str """Proxy ID""" diff --git a/src/kernel/types/auth/connection_login_params.py b/src/kernel/types/auth/connection_login_params.py index 117d3c7d..c26b020f 100644 --- a/src/kernel/types/auth/connection_login_params.py +++ b/src/kernel/types/auth/connection_login_params.py @@ -5,6 +5,7 @@ from typing import Optional from typing_extensions import TypedDict +from .managed_auth_browser_config_param import ManagedAuthBrowserConfigParam from ..browsers.browser_telemetry_categories_config_param import BrowserTelemetryCategoriesConfigParam __all__ = [ @@ -18,23 +19,21 @@ class ConnectionLoginParams(TypedDict, total=False): - browser_telemetry: Optional[BrowserTelemetry] - """Override the connection's default browser telemetry configuration for this - login. + browser: ManagedAuthBrowserConfigParam + """Browser configuration override for this login. - When omitted, the connection's browser_telemetry default is used. Uses the exact - create-browser configuration. + Omitted properties inherit the connection defaults. """ - proxy: Proxy - """Proxy selection. + browser_telemetry: Optional[BrowserTelemetry] + """Deprecated. - Provide either id or name. The proxy must be in the same project as the resource - referencing it. When selecting by name, the name must match exactly one active - proxy in the project. Ambiguous names return a 400; use id for stable - references. + Use browser.telemetry. Retained during migration for existing clients. """ + proxy: Proxy + """Deprecated. Use browser.proxy. Retained during migration for existing clients.""" + record_session: bool """Override the connection's default for recording this login's browser session. @@ -87,9 +86,9 @@ class BrowserTelemetryExport(TypedDict, total=False): class BrowserTelemetry(TypedDict, total=False): - """Override the connection's default browser telemetry configuration for this login. + """Deprecated. - When omitted, the connection's browser_telemetry default is used. Uses the exact create-browser configuration. + Use browser.telemetry. Retained during migration for existing clients. """ browser: BrowserTelemetryCategoriesConfigParam @@ -127,11 +126,7 @@ class BrowserTelemetry(TypedDict, total=False): class Proxy(TypedDict, total=False): - """Proxy selection. - - Provide either id or name. The proxy must be in the same project as the resource referencing it. - When selecting by name, the name must match exactly one active proxy in the project. Ambiguous names return a 400; use id for stable references. - """ + """Deprecated. Use browser.proxy. Retained during migration for existing clients.""" id: str """Proxy ID""" diff --git a/src/kernel/types/auth/connection_update_params.py b/src/kernel/types/auth/connection_update_params.py index f92a40c7..ad3fbe44 100644 --- a/src/kernel/types/auth/connection_update_params.py +++ b/src/kernel/types/auth/connection_update_params.py @@ -6,6 +6,7 @@ from typing_extensions import TypedDict from ..._types import SequenceNotStr +from .managed_auth_browser_config_param import ManagedAuthBrowserConfigParam from ..browsers.browser_telemetry_categories_config_param import BrowserTelemetryCategoriesConfigParam __all__ = [ @@ -35,11 +36,16 @@ class ConnectionUpdateParams(TypedDict, total=False): re-auth. """ - browser_telemetry: Optional[BrowserTelemetry] + browser: ManagedAuthBrowserConfigParam + """ + Browser configuration updates for future login, reauthentication, and + health-check sessions. Omitted properties remain unchanged. """ - Browser telemetry configuration used by future browser sessions for this - connection. Uses the exact create-browser configuration. Set enabled to false to - disable telemetry. + + browser_telemetry: Optional[BrowserTelemetry] + """Deprecated. + + Use browser.telemetry. Retained during migration for existing clients. """ credential: Credential @@ -65,13 +71,7 @@ class ConnectionUpdateParams(TypedDict, total=False): """Login page URL. Set to empty string to clear.""" proxy: Proxy - """Proxy selection. - - Provide either id or name. The proxy must be in the same project as the resource - referencing it. When selecting by name, the name must match exactly one active - proxy in the project. Ambiguous names return a 400; use id for stable - references. - """ + """Deprecated. Use browser.proxy. Retained during migration for existing clients.""" record_session: bool """Whether to record browser sessions for this connection by default""" @@ -125,8 +125,9 @@ class BrowserTelemetryExport(TypedDict, total=False): class BrowserTelemetry(TypedDict, total=False): - """ - Browser telemetry configuration used by future browser sessions for this connection. Uses the exact create-browser configuration. Set enabled to false to disable telemetry. + """Deprecated. + + Use browser.telemetry. Retained during migration for existing clients. """ browser: BrowserTelemetryCategoriesConfigParam @@ -186,11 +187,7 @@ class Credential(TypedDict, total=False): class Proxy(TypedDict, total=False): - """Proxy selection. - - Provide either id or name. The proxy must be in the same project as the resource referencing it. - When selecting by name, the name must match exactly one active proxy in the project. Ambiguous names return a 400; use id for stable references. - """ + """Deprecated. Use browser.proxy. Retained during migration for existing clients.""" id: str """Proxy ID""" diff --git a/src/kernel/types/auth/managed_auth.py b/src/kernel/types/auth/managed_auth.py index e3bf7b9c..9db58514 100644 --- a/src/kernel/types/auth/managed_auth.py +++ b/src/kernel/types/auth/managed_auth.py @@ -5,6 +5,7 @@ from typing_extensions import Literal from ..._models import BaseModel +from .managed_auth_browser_config import ManagedAuthBrowserConfig from ..browsers.browser_telemetry_categories_config import BrowserTelemetryCategoriesConfig __all__ = [ @@ -68,8 +69,9 @@ class BrowserTelemetryExport(BaseModel): class BrowserTelemetry(BaseModel): - """ - Browser telemetry configuration used by this connection's browser sessions by default. The exact create-browser configuration is preserved and can be overridden per-login. + """Deprecated. + + Use browser.telemetry. Retained during migration for existing clients. """ browser: Optional[BrowserTelemetryCategoriesConfig] = None @@ -324,6 +326,12 @@ class ManagedAuth(BaseModel): re-auth. """ + browser: Optional[ManagedAuthBrowserConfig] = None + """ + Default browser configuration for login, reauthentication, and health-check + sessions. + """ + browser_session_id: Optional[str] = None """ ID of the underlying browser session driving the current flow (present when flow @@ -332,10 +340,9 @@ class ManagedAuth(BaseModel): """ browser_telemetry: Optional[BrowserTelemetry] = None - """ - Browser telemetry configuration used by this connection's browser sessions by - default. The exact create-browser configuration is preserved and can be - overridden per-login. + """Deprecated. + + Use browser.telemetry. Retained during migration for existing clients. """ can_reauth: Optional[bool] = None @@ -362,6 +369,7 @@ class ManagedAuth(BaseModel): "requires_totp_without_secret", "requires_sms_code", "requires_email_code", + "requires_customer_input", ] ] = None """ @@ -394,6 +402,8 @@ class ManagedAuth(BaseModel): automatically - `requires_email_code` — flow needs an email code that cannot be received automatically + - `requires_customer_input` — flow needs another field or choice that is + unavailable during unattended re-authentication """ choices: Optional[List[Choice]] = None @@ -459,8 +469,9 @@ class ManagedAuth(BaseModel): When set, the system periodically verifies the authentication status and triggers re-authentication if needed. Maximum is 86400 (24 hours). Default is - 3600 (1 hour). The minimum depends on your plan: Enterprise: 300 (5 minutes), - Startup: 1200 (20 minutes), Hobbyist: 3600 (1 hour). + 3600 (1 hour) or your plan minimum, whichever is larger. The minimum depends on + your plan: Enterprise: 300 (5 minutes), Startup: 1200 (20 minutes), Hobbyist: + 3600 (1 hour), Free: 21600 (6 hours). """ health_checks: Optional[bool] = None @@ -513,7 +524,10 @@ class ManagedAuth(BaseModel): """URL where the browser landed after successful login""" proxy_id: Optional[str] = None - """ID of the proxy associated with this connection, if any.""" + """Deprecated. + + Read browser.proxy instead. Retained during migration for existing clients. + """ sign_in_options: Optional[List[SignInOption]] = None """ diff --git a/src/kernel/types/auth/managed_auth_browser_config.py b/src/kernel/types/auth/managed_auth_browser_config.py new file mode 100644 index 00000000..a4d63de7 --- /dev/null +++ b/src/kernel/types/auth/managed_auth_browser_config.py @@ -0,0 +1,118 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional + +from ..._models import BaseModel +from ..browser_proxy_config import BrowserProxyConfig +from ..browsers.browser_telemetry_categories_config import BrowserTelemetryCategoriesConfig + +__all__ = [ + "ManagedAuthBrowserConfig", + "Telemetry", + "TelemetryExport", + "TelemetryExportOtlp", + "TelemetryExportOtlpDestination", +] + + +class TelemetryExportOtlpDestination(BaseModel): + """OTLP destination to export this session's captured telemetry to. + + Provide either id or name. Requires telemetry capture to be enabled. + """ + + id: Optional[str] = None + """OTLP destination ID""" + + name: Optional[str] = None + """OTLP destination name""" + + +class TelemetryExportOtlp(BaseModel): + """ + Export captured telemetry over OTLP to one of the org's configured destinations. + """ + + destination: Optional[TelemetryExportOtlpDestination] = None + """OTLP destination to export this session's captured telemetry to. + + Provide either id or name. Requires telemetry capture to be enabled. + """ + + enabled: Optional[bool] = None + """Whether to export captured telemetry over OTLP. + + Setting destination implies enabled=true, so this only needs to be set + explicitly to disable export (enabled=false with a destination is rejected). + """ + + +class TelemetryExport(BaseModel): + """Where to export this session's captured telemetry. + + Omit to capture without exporting. + """ + + otlp: Optional[TelemetryExportOtlp] = None + """ + Export captured telemetry over OTLP to one of the org's configured destinations. + """ + + +class Telemetry(BaseModel): + """Browser telemetry configuration using the same semantics as browser create.""" + + browser: Optional[BrowserTelemetryCategoriesConfig] = None + """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: Optional[bool] = None + """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. + """ + + export: Optional[TelemetryExport] = None + """Where to export this session's captured telemetry. + + Omit to capture without exporting. + """ + + +class ManagedAuthBrowserConfig(BaseModel): + """ + Browser configuration applied to browser sessions created for a managed auth connection. Managed auth controls the profile, headless mode, timeout, start URL, kiosk mode, and viewport. + """ + + proxy: Optional[BrowserProxyConfig] = None + """Proxy configuration for managed auth browser sessions. + + Omit on create to derive the default from stealth, or on update and login to + preserve or inherit the connection default. + """ + + stealth: Optional[bool] = None + """Whether managed auth browser sessions use stealth mode. + + Defaults to true when omitted. + """ + + telemetry: Optional[Telemetry] = None + """Browser telemetry configuration using the same semantics as browser create.""" diff --git a/src/kernel/types/auth/managed_auth_browser_config_param.py b/src/kernel/types/auth/managed_auth_browser_config_param.py new file mode 100644 index 00000000..7f8650e0 --- /dev/null +++ b/src/kernel/types/auth/managed_auth_browser_config_param.py @@ -0,0 +1,120 @@ +# 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 + +from ..browser_proxy_config_param import BrowserProxyConfigParam +from ..browsers.browser_telemetry_categories_config_param import BrowserTelemetryCategoriesConfigParam + +__all__ = [ + "ManagedAuthBrowserConfigParam", + "Telemetry", + "TelemetryExport", + "TelemetryExportOtlp", + "TelemetryExportOtlpDestination", +] + + +class TelemetryExportOtlpDestination(TypedDict, total=False): + """OTLP destination to export this session's captured telemetry to. + + Provide either id or name. Requires telemetry capture to be enabled. + """ + + id: str + """OTLP destination ID""" + + name: str + """OTLP destination name""" + + +class TelemetryExportOtlp(TypedDict, total=False): + """ + Export captured telemetry over OTLP to one of the org's configured destinations. + """ + + destination: TelemetryExportOtlpDestination + """OTLP destination to export this session's captured telemetry to. + + Provide either id or name. Requires telemetry capture to be enabled. + """ + + enabled: bool + """Whether to export captured telemetry over OTLP. + + Setting destination implies enabled=true, so this only needs to be set + explicitly to disable export (enabled=false with a destination is rejected). + """ + + +class TelemetryExport(TypedDict, total=False): + """Where to export this session's captured telemetry. + + Omit to capture without exporting. + """ + + otlp: TelemetryExportOtlp + """ + Export captured telemetry over OTLP to one of the org's configured destinations. + """ + + +class Telemetry(TypedDict, total=False): + """Browser telemetry configuration using the same semantics as browser create.""" + + 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. + """ + + export: TelemetryExport + """Where to export this session's captured telemetry. + + Omit to capture without exporting. + """ + + +class ManagedAuthBrowserConfigParam(TypedDict, total=False): + """ + Browser configuration applied to browser sessions created for a managed auth connection. Managed auth controls the profile, headless mode, timeout, start URL, kiosk mode, and viewport. + """ + + proxy: BrowserProxyConfigParam + """Proxy configuration for managed auth browser sessions. + + Omit on create to derive the default from stealth, or on update and login to + preserve or inherit the connection default. + """ + + stealth: bool + """Whether managed auth browser sessions use stealth mode. + + Defaults to true when omitted. + """ + + telemetry: Optional[Telemetry] + """Browser telemetry configuration using the same semantics as browser create.""" diff --git a/src/kernel/types/browser_create_params.py b/src/kernel/types/browser_create_params.py index f09a29cf..262383c5 100644 --- a/src/kernel/types/browser_create_params.py +++ b/src/kernel/types/browser_create_params.py @@ -6,6 +6,7 @@ from typing_extensions import TypedDict from .tags_param import TagsParam +from .browser_proxy_config_param import BrowserProxyConfigParam from .shared_params.browser_profile import BrowserProfile from .shared_params.browser_viewport import BrowserViewport from .shared_params.browser_extension import BrowserExtension @@ -70,10 +71,23 @@ class BrowserCreateParams(TypedDict, total=False): into the browser session. Profiles must be created beforehand. """ + proxy: BrowserProxyConfigParam + """Proxy configuration for the browser session. + + Cannot be combined with proxy_id. Omit to use the browser default: stealth + browsers use Kernel's default stealth proxy, while non-stealth browsers use + direct egress. Set mode to direct to force direct egress regardless of stealth. + Set mode to default to explicitly use the browser default: Kernel's default + stealth proxy when stealth=true, or direct egress when stealth=false. Select id + or name to use that proxy regardless of stealth. Proxy selection does not change + stealth or CAPTCHA solver behavior. + """ + proxy_id: str """Optional proxy to associate to the browser session. - Must reference a proxy in the same project as the browser session. + Must reference a proxy in the same project as the browser session. Deprecated in + favor of proxy. """ start_url: str @@ -84,9 +98,12 @@ class BrowserCreateParams(TypedDict, total=False): """ stealth: bool - """ - If true, launches the browser in stealth mode to reduce detection by anti-bot - mechanisms. + """If true, launches the browser in stealth mode and enables the CAPTCHA solver. + + Defaults to false. When proxy is omitted, stealth browsers use Kernel's default + stealth proxy and non-stealth browsers use direct egress. An explicit proxy + configuration changes only egress; it does not enable or disable stealth or the + CAPTCHA solver. """ tags: TagsParam diff --git a/src/kernel/types/browser_create_response.py b/src/kernel/types/browser_create_response.py index 0dbf867c..8618e7e5 100644 --- a/src/kernel/types/browser_create_response.py +++ b/src/kernel/types/browser_create_response.py @@ -6,6 +6,7 @@ from .tags import Tags from .profile import Profile from .._models import BaseModel +from .browser_proxy import BrowserProxy from .browser_usage import BrowserUsage from .browser_pool_ref import BrowserPoolRef from .shared.browser_viewport import BrowserViewport @@ -79,8 +80,14 @@ class BrowserCreateResponse(BaseModel): when the session ends. Omitted when no profile is attached. """ + proxy: Optional[BrowserProxy] = None + """Resolved proxy configuration for this browser session.""" + proxy_id: Optional[str] = None - """ID of the proxy associated with this browser session, if any.""" + """ID of the proxy associated with this browser session, if any. + + Deprecated in favor of proxy. + """ start_url: Optional[str] = None """URL the session was asked to navigate to on creation, if any. diff --git a/src/kernel/types/browser_list_response.py b/src/kernel/types/browser_list_response.py index f3215ed5..8f4917a8 100644 --- a/src/kernel/types/browser_list_response.py +++ b/src/kernel/types/browser_list_response.py @@ -6,6 +6,7 @@ from .tags import Tags from .profile import Profile from .._models import BaseModel +from .browser_proxy import BrowserProxy from .browser_usage import BrowserUsage from .browser_pool_ref import BrowserPoolRef from .shared.browser_viewport import BrowserViewport @@ -79,8 +80,14 @@ class BrowserListResponse(BaseModel): when the session ends. Omitted when no profile is attached. """ + proxy: Optional[BrowserProxy] = None + """Resolved proxy configuration for this browser session.""" + proxy_id: Optional[str] = None - """ID of the proxy associated with this browser session, if any.""" + """ID of the proxy associated with this browser session, if any. + + Deprecated in favor of proxy. + """ start_url: Optional[str] = None """URL the session was asked to navigate to on creation, if any. diff --git a/src/kernel/types/browser_pool_acquire_response.py b/src/kernel/types/browser_pool_acquire_response.py index 1dabc492..7d849958 100644 --- a/src/kernel/types/browser_pool_acquire_response.py +++ b/src/kernel/types/browser_pool_acquire_response.py @@ -6,6 +6,7 @@ from .tags import Tags from .profile import Profile from .._models import BaseModel +from .browser_proxy import BrowserProxy from .browser_usage import BrowserUsage from .browser_pool_ref import BrowserPoolRef from .shared.browser_viewport import BrowserViewport @@ -79,8 +80,14 @@ class BrowserPoolAcquireResponse(BaseModel): when the session ends. Omitted when no profile is attached. """ + proxy: Optional[BrowserProxy] = None + """Resolved proxy configuration for this browser session.""" + proxy_id: Optional[str] = None - """ID of the proxy associated with this browser session, if any.""" + """ID of the proxy associated with this browser session, if any. + + Deprecated in favor of proxy. + """ start_url: Optional[str] = None """URL the session was asked to navigate to on creation, if any. diff --git a/src/kernel/types/browser_proxy.py b/src/kernel/types/browser_proxy.py new file mode 100644 index 00000000..20078429 --- /dev/null +++ b/src/kernel/types/browser_proxy.py @@ -0,0 +1,30 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional + +from .._models import BaseModel +from .browser_proxy_mode import BrowserProxyMode + +__all__ = ["BrowserProxy"] + + +class BrowserProxy(BaseModel): + """Resolved proxy configuration for a browser session. + + Selected proxies are returned by stable ID. + """ + + id: Optional[str] = None + """Selected proxy ID.""" + + mode: Optional[BrowserProxyMode] = None + """Proxy egress mode. + + direct forces no proxy regardless of stealth. default uses the browser's + stealth-derived default: Kernel's default stealth proxy when stealth=true, or + direct egress when stealth=false. default is primarily useful on browser update + to restore the browser default after selected-proxy egress. + """ + + name: Optional[str] = None + """Selected proxy name.""" diff --git a/src/kernel/types/browser_proxy_config.py b/src/kernel/types/browser_proxy_config.py new file mode 100644 index 00000000..6db5d5ec --- /dev/null +++ b/src/kernel/types/browser_proxy_config.py @@ -0,0 +1,34 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional + +from .._models import BaseModel +from .browser_proxy_mode import BrowserProxyMode + +__all__ = ["BrowserProxyConfig"] + + +class BrowserProxyConfig(BaseModel): + """Browser proxy configuration. + + Provide exactly one of mode, id, or name; an empty object is invalid. + Set mode to direct for no proxy regardless of stealth. Set mode to default to use the browser's stealth-derived default: Kernel's default stealth proxy when stealth=true, or direct egress when stealth=false. + Select id or name to use that proxy regardless of stealth. The selected proxy must be in the same project as the browser. Names must match exactly one active proxy; use id for stable references. + Proxy configuration changes only egress and does not change stealth or CAPTCHA solver behavior. A stealth browser using mode=direct still runs in stealth mode with the CAPTCHA solver enabled. + When proxy is omitted on browser creation, stealth browsers use Kernel's default stealth proxy and non-stealth browsers use direct egress. When omitted on update, the current configuration is unchanged. + """ + + id: Optional[str] = None + """Proxy ID.""" + + mode: Optional[BrowserProxyMode] = None + """Proxy egress mode. + + direct forces no proxy regardless of stealth. default uses the browser's + stealth-derived default: Kernel's default stealth proxy when stealth=true, or + direct egress when stealth=false. default is primarily useful on browser update + to restore the browser default after selected-proxy egress. + """ + + name: Optional[str] = None + """Proxy name. Must match exactly one active proxy in the project.""" diff --git a/src/kernel/types/browser_proxy_config_param.py b/src/kernel/types/browser_proxy_config_param.py new file mode 100644 index 00000000..0fc83157 --- /dev/null +++ b/src/kernel/types/browser_proxy_config_param.py @@ -0,0 +1,35 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import TypedDict + +from .browser_proxy_mode import BrowserProxyMode + +__all__ = ["BrowserProxyConfigParam"] + + +class BrowserProxyConfigParam(TypedDict, total=False): + """Browser proxy configuration. + + Provide exactly one of mode, id, or name; an empty object is invalid. + Set mode to direct for no proxy regardless of stealth. Set mode to default to use the browser's stealth-derived default: Kernel's default stealth proxy when stealth=true, or direct egress when stealth=false. + Select id or name to use that proxy regardless of stealth. The selected proxy must be in the same project as the browser. Names must match exactly one active proxy; use id for stable references. + Proxy configuration changes only egress and does not change stealth or CAPTCHA solver behavior. A stealth browser using mode=direct still runs in stealth mode with the CAPTCHA solver enabled. + When proxy is omitted on browser creation, stealth browsers use Kernel's default stealth proxy and non-stealth browsers use direct egress. When omitted on update, the current configuration is unchanged. + """ + + id: str + """Proxy ID.""" + + mode: BrowserProxyMode + """Proxy egress mode. + + direct forces no proxy regardless of stealth. default uses the browser's + stealth-derived default: Kernel's default stealth proxy when stealth=true, or + direct egress when stealth=false. default is primarily useful on browser update + to restore the browser default after selected-proxy egress. + """ + + name: str + """Proxy name. Must match exactly one active proxy in the project.""" diff --git a/src/kernel/types/browser_proxy_mode.py b/src/kernel/types/browser_proxy_mode.py new file mode 100644 index 00000000..c8b51c1b --- /dev/null +++ b/src/kernel/types/browser_proxy_mode.py @@ -0,0 +1,7 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal, TypeAlias + +__all__ = ["BrowserProxyMode"] + +BrowserProxyMode: TypeAlias = Literal["direct", "default"] diff --git a/src/kernel/types/browser_retrieve_response.py b/src/kernel/types/browser_retrieve_response.py index 5563ab98..3afc6082 100644 --- a/src/kernel/types/browser_retrieve_response.py +++ b/src/kernel/types/browser_retrieve_response.py @@ -6,6 +6,7 @@ from .tags import Tags from .profile import Profile from .._models import BaseModel +from .browser_proxy import BrowserProxy from .browser_usage import BrowserUsage from .browser_pool_ref import BrowserPoolRef from .shared.browser_viewport import BrowserViewport @@ -79,8 +80,14 @@ class BrowserRetrieveResponse(BaseModel): when the session ends. Omitted when no profile is attached. """ + proxy: Optional[BrowserProxy] = None + """Resolved proxy configuration for this browser session.""" + proxy_id: Optional[str] = None - """ID of the proxy associated with this browser session, if any.""" + """ID of the proxy associated with this browser session, if any. + + Deprecated in favor of proxy. + """ start_url: Optional[str] = None """URL the session was asked to navigate to on creation, if any. diff --git a/src/kernel/types/browser_update_params.py b/src/kernel/types/browser_update_params.py index 01b19c8a..a9ea675c 100644 --- a/src/kernel/types/browser_update_params.py +++ b/src/kernel/types/browser_update_params.py @@ -6,6 +6,7 @@ from typing_extensions import TypedDict from .tags_param import TagsParam +from .browser_proxy_config_param import BrowserProxyConfigParam from .shared_params.browser_profile import BrowserProfile from .shared_params.browser_viewport import BrowserViewport from .browsers.browser_telemetry_categories_config_param import BrowserTelemetryCategoriesConfigParam @@ -24,7 +25,7 @@ class BrowserUpdateParams(TypedDict, total=False): disable_default_proxy: bool """ If true, stealth browsers connect directly instead of using the default stealth - proxy. + proxy. Deprecated in favor of proxy.mode. """ name: Optional[str] @@ -40,10 +41,22 @@ class BrowserUpdateParams(TypedDict, total=False): Only allowed if the session does not already have a profile loaded. """ + proxy: BrowserProxyConfigParam + """Proxy configuration to apply. + + Omit to leave the current configuration unchanged. Cannot be combined with + proxy_id or disable_default_proxy. Set mode to direct to switch to direct egress + regardless of stealth. Set mode to default to restore the browser default after + using a selected proxy: Kernel's default stealth proxy for a stealth browser, or + direct egress for a non-stealth browser. Updating proxy does not change stealth + or CAPTCHA solver behavior. + """ + proxy_id: Optional[str] """ID of the proxy to use. - Omit to leave unchanged, set to empty string to remove proxy. + Omit to leave unchanged, set to empty string to remove proxy. Deprecated in + favor of proxy. """ tags: Optional[TagsParam] diff --git a/src/kernel/types/browser_update_response.py b/src/kernel/types/browser_update_response.py index e4602bd5..d60fe900 100644 --- a/src/kernel/types/browser_update_response.py +++ b/src/kernel/types/browser_update_response.py @@ -6,6 +6,7 @@ from .tags import Tags from .profile import Profile from .._models import BaseModel +from .browser_proxy import BrowserProxy from .browser_usage import BrowserUsage from .browser_pool_ref import BrowserPoolRef from .shared.browser_viewport import BrowserViewport @@ -79,8 +80,14 @@ class BrowserUpdateResponse(BaseModel): when the session ends. Omitted when no profile is attached. """ + proxy: Optional[BrowserProxy] = None + """Resolved proxy configuration for this browser session.""" + proxy_id: Optional[str] = None - """ID of the proxy associated with this browser session, if any.""" + """ID of the proxy associated with this browser session, if any. + + Deprecated in favor of proxy. + """ start_url: Optional[str] = None """URL the session was asked to navigate to on creation, if any. diff --git a/src/kernel/types/invocation_list_browsers_response.py b/src/kernel/types/invocation_list_browsers_response.py index 9abb0fa6..5cfe7e89 100644 --- a/src/kernel/types/invocation_list_browsers_response.py +++ b/src/kernel/types/invocation_list_browsers_response.py @@ -6,6 +6,7 @@ from .tags import Tags from .profile import Profile from .._models import BaseModel +from .browser_proxy import BrowserProxy from .browser_usage import BrowserUsage from .browser_pool_ref import BrowserPoolRef from .shared.browser_viewport import BrowserViewport @@ -79,8 +80,14 @@ class Browser(BaseModel): when the session ends. Omitted when no profile is attached. """ + proxy: Optional[BrowserProxy] = None + """Resolved proxy configuration for this browser session.""" + proxy_id: Optional[str] = None - """ID of the proxy associated with this browser session, if any.""" + """ID of the proxy associated with this browser session, if any. + + Deprecated in favor of proxy. + """ start_url: Optional[str] = None """URL the session was asked to navigate to on creation, if any. diff --git a/tests/api_resources/auth/test_connections.py b/tests/api_resources/auth/test_connections.py index 321e84e4..f026a2cd 100644 --- a/tests/api_resources/auth/test_connections.py +++ b/tests/api_resources/auth/test_connections.py @@ -40,6 +40,37 @@ def test_method_create_with_all_params(self, client: Kernel) -> None: profile_name="user-123", allowed_domains=["login.netflix.com", "auth.netflix.com"], auto_reauth=True, + browser={ + "proxy": { + "id": "x", + "mode": "direct", + "name": "x", + }, + "stealth": False, + "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, + "export": { + "otlp": { + "destination": { + "id": "id", + "name": "name", + }, + "enabled": True, + } + }, + }, + }, browser_telemetry={ "browser": { "captcha": {"enabled": True}, @@ -166,6 +197,37 @@ def test_method_update_with_all_params(self, client: Kernel) -> None: id="id", allowed_domains=["login.netflix.com", "auth.netflix.com"], auto_reauth=True, + browser={ + "proxy": { + "id": "x", + "mode": "direct", + "name": "x", + }, + "stealth": False, + "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, + "export": { + "otlp": { + "destination": { + "id": "id", + "name": "name", + }, + "enabled": True, + } + }, + }, + }, browser_telemetry={ "browser": { "captcha": {"enabled": True}, @@ -377,6 +439,37 @@ def test_method_login(self, client: Kernel) -> None: def test_method_login_with_all_params(self, client: Kernel) -> None: connection = client.auth.connections.login( id="id", + browser={ + "proxy": { + "id": "x", + "mode": "direct", + "name": "x", + }, + "stealth": False, + "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, + "export": { + "otlp": { + "destination": { + "id": "id", + "name": "name", + }, + "enabled": True, + } + }, + }, + }, browser_telemetry={ "browser": { "captcha": {"enabled": True}, @@ -581,6 +674,37 @@ async def test_method_create_with_all_params(self, async_client: AsyncKernel) -> profile_name="user-123", allowed_domains=["login.netflix.com", "auth.netflix.com"], auto_reauth=True, + browser={ + "proxy": { + "id": "x", + "mode": "direct", + "name": "x", + }, + "stealth": False, + "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, + "export": { + "otlp": { + "destination": { + "id": "id", + "name": "name", + }, + "enabled": True, + } + }, + }, + }, browser_telemetry={ "browser": { "captcha": {"enabled": True}, @@ -707,6 +831,37 @@ async def test_method_update_with_all_params(self, async_client: AsyncKernel) -> id="id", allowed_domains=["login.netflix.com", "auth.netflix.com"], auto_reauth=True, + browser={ + "proxy": { + "id": "x", + "mode": "direct", + "name": "x", + }, + "stealth": False, + "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, + "export": { + "otlp": { + "destination": { + "id": "id", + "name": "name", + }, + "enabled": True, + } + }, + }, + }, browser_telemetry={ "browser": { "captcha": {"enabled": True}, @@ -918,6 +1073,37 @@ async def test_method_login(self, async_client: AsyncKernel) -> None: async def test_method_login_with_all_params(self, async_client: AsyncKernel) -> None: connection = await async_client.auth.connections.login( id="id", + browser={ + "proxy": { + "id": "x", + "mode": "direct", + "name": "x", + }, + "stealth": False, + "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, + "export": { + "otlp": { + "destination": { + "id": "id", + "name": "name", + }, + "enabled": True, + } + }, + }, + }, browser_telemetry={ "browser": { "captcha": {"enabled": True}, diff --git a/tests/api_resources/test_browsers.py b/tests/api_resources/test_browsers.py index a8f93efc..8b0a6182 100644 --- a/tests/api_resources/test_browsers.py +++ b/tests/api_resources/test_browsers.py @@ -51,6 +51,11 @@ def test_method_create_with_all_params(self, client: Kernel) -> None: "name": "name", "save_changes": True, }, + proxy={ + "id": "x", + "mode": "direct", + "name": "x", + }, proxy_id="proxy_id", start_url="https://example.com", stealth=True, @@ -183,6 +188,11 @@ def test_method_update_with_all_params(self, client: Kernel) -> None: "name": "name", "save_changes": True, }, + proxy={ + "id": "x", + "mode": "direct", + "name": "x", + }, proxy_id="proxy_id", tags={ "team": "backend", @@ -496,6 +506,11 @@ async def test_method_create_with_all_params(self, async_client: AsyncKernel) -> "name": "name", "save_changes": True, }, + proxy={ + "id": "x", + "mode": "direct", + "name": "x", + }, proxy_id="proxy_id", start_url="https://example.com", stealth=True, @@ -628,6 +643,11 @@ async def test_method_update_with_all_params(self, async_client: AsyncKernel) -> "name": "name", "save_changes": True, }, + proxy={ + "id": "x", + "mode": "direct", + "name": "x", + }, proxy_id="proxy_id", tags={ "team": "backend",