feat: Add browser location session policy

Stainless-Generated-From: a55a0720ed50df5df1001ae2613977041468284b

Author: kernel-internal[bot]

README.md

@@ -203,9 +203,9 @@ from kernel import Kernel
 client = Kernel()
 
 browser = client.browsers.create(
-    network={},
+    location={},
 )
-print(browser.network)
+print(browser.location)
 ```
 
 ## File uploads

api.md

@@ -118,6 +118,10 @@ Types:
 ```python
 from kernel.types import (
     BrowserAllowlistState,
+    BrowserLocation,
+    BrowserLocationRequest,
+    BrowserLocationSource,
+    BrowserLocationUpdateRequest,
     BrowserMemory,
     BrowserMemoryRequest,
     BrowserNetworkConfig,

src/kernel/resources/browsers/browsers.py

@@ -116,8 +116,10 @@
 from ...types.browser_network_config_param import BrowserNetworkConfigParam
 from ...types.browser_network_update_param import BrowserNetworkUpdateParam
 from ...types.shared_params.browser_profile import BrowserProfile
+from ...types.browser_location_request_param import BrowserLocationRequestParam
 from ...types.shared_params.browser_viewport import BrowserViewport
 from ...types.shared_params.browser_extension import BrowserExtension
+from ...types.browser_location_update_request_param import BrowserLocationUpdateRequestParam
 
 __all__ = ["BrowsersResource", "AsyncBrowsersResource"]
 
@@ -195,6 +197,7 @@ def create(
         headless: bool | Omit = omit,
         invocation_id: str | Omit = omit,
         kiosk_mode: bool | Omit = omit,
+        location: BrowserLocationRequestParam | Omit = omit,
         memory: BrowserMemoryRequest | Omit = omit,
         name: str | Omit = omit,
         network: BrowserNetworkConfigParam | Omit = omit,
@@ -239,6 +242,9 @@ def create(
           kiosk_mode: If true, launches the browser in kiosk mode to hide address bar and tabs in live
               view.
 
+          location: Optional session-only timezone and locale overrides. Each omitted field uses the
+              default for the browser's region. start_url opens once the location applies.
+
           memory:
               Memory for a non-GPU browser. Headless: 1GiB (default), 2GiB, or 4GiB. Headful:
               8GiB (default) or 16GiB.
@@ -333,6 +339,7 @@ def create(
                     "headless": headless,
                     "invocation_id": invocation_id,
                     "kiosk_mode": kiosk_mode,
+                    "location": location,
                     "memory": memory,
                     "name": name,
                     "network": network,
@@ -404,6 +411,7 @@ def update(
         id_or_name: str,
         *,
         disable_default_proxy: bool | Omit = omit,
+        location: BrowserLocationUpdateRequestParam | Omit = omit,
         name: Optional[str] | Omit = omit,
         network: BrowserNetworkUpdateParam | Omit = omit,
         profile: BrowserProfile | Omit = omit,
@@ -427,6 +435,14 @@ def update(
           disable_default_proxy: If true, stealth browsers connect directly instead of using the default stealth
               proxy. Deprecated in favor of proxy.mode.
 
+          location: Session-only timezone and locale overrides. Omit the object or a field to leave
+              it unchanged; set a string to override; set null to clear that field and use the
+              browser region's default. A browser that cannot change location refuses the
+              request before anything changes. The location applies after the request's other
+              changes, and start_url opens once it has applied. If applying it fails, the
+              other changes and the saved override remain and start_url does not open; retry
+              the request to apply both.
+
           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
               within the project.
@@ -478,6 +494,7 @@ def update(
             body=maybe_transform(
                 {
                     "disable_default_proxy": disable_default_proxy,
+                    "location": location,
                     "name": name,
                     "network": network,
                     "profile": profile,
@@ -912,6 +929,7 @@ async def create(
         headless: bool | Omit = omit,
         invocation_id: str | Omit = omit,
         kiosk_mode: bool | Omit = omit,
+        location: BrowserLocationRequestParam | Omit = omit,
         memory: BrowserMemoryRequest | Omit = omit,
         name: str | Omit = omit,
         network: BrowserNetworkConfigParam | Omit = omit,
@@ -956,6 +974,9 @@ async def create(
           kiosk_mode: If true, launches the browser in kiosk mode to hide address bar and tabs in live
               view.
 
+          location: Optional session-only timezone and locale overrides. Each omitted field uses the
+              default for the browser's region. start_url opens once the location applies.
+
           memory:
               Memory for a non-GPU browser. Headless: 1GiB (default), 2GiB, or 4GiB. Headful:
               8GiB (default) or 16GiB.
@@ -1050,6 +1071,7 @@ async def create(
                     "headless": headless,
                     "invocation_id": invocation_id,
                     "kiosk_mode": kiosk_mode,
+                    "location": location,
                     "memory": memory,
                     "name": name,
                     "network": network,
@@ -1121,6 +1143,7 @@ async def update(
         id_or_name: str,
         *,
         disable_default_proxy: bool | Omit = omit,
+        location: BrowserLocationUpdateRequestParam | Omit = omit,
         name: Optional[str] | Omit = omit,
         network: BrowserNetworkUpdateParam | Omit = omit,
         profile: BrowserProfile | Omit = omit,
@@ -1144,6 +1167,14 @@ async def update(
           disable_default_proxy: If true, stealth browsers connect directly instead of using the default stealth
               proxy. Deprecated in favor of proxy.mode.
 
+          location: Session-only timezone and locale overrides. Omit the object or a field to leave
+              it unchanged; set a string to override; set null to clear that field and use the
+              browser region's default. A browser that cannot change location refuses the
+              request before anything changes. The location applies after the request's other
+              changes, and start_url opens once it has applied. If applying it fails, the
+              other changes and the saved override remain and start_url does not open; retry
+              the request to apply both.
+
           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
               within the project.
@@ -1195,6 +1226,7 @@ async def update(
             body=await async_maybe_transform(
                 {
                     "disable_default_proxy": disable_default_proxy,
+                    "location": location,
                     "name": name,
                     "network": network,
                     "profile": profile,

src/kernel/types/__init__.py

@@ -44,6 +44,7 @@
 from .lookup_response import LookupResponse as LookupResponse
 from .vault_reference import VaultReference as VaultReference
 from .analysis_summary import AnalysisSummary as AnalysisSummary
+from .browser_location import BrowserLocation as BrowserLocation
 from .browser_pool_ref import BrowserPoolRef as BrowserPoolRef
 from .app_list_response import AppListResponse as AppListResponse
 from .no_recommendation import NoRecommendation as NoRecommendation
@@ -100,6 +101,7 @@
 from .api_key_retrieve_params import APIKeyRetrieveParams as APIKeyRetrieveParams
 from .browser_allowlist_state import BrowserAllowlistState as BrowserAllowlistState
 from .browser_create_response import BrowserCreateResponse as BrowserCreateResponse
+from .browser_location_source import BrowserLocationSource as BrowserLocationSource
 from .browser_retrieve_params import BrowserRetrieveParams as BrowserRetrieveParams
 from .browser_update_response import BrowserUpdateResponse as BrowserUpdateResponse
 from .extension_list_response import ExtensionListResponse as ExtensionListResponse
@@ -144,6 +146,7 @@
 from .config_registry_lookup_params import ConfigRegistryLookupParams as ConfigRegistryLookupParams
 from .credential_totp_code_response import CredentialTotpCodeResponse as CredentialTotpCodeResponse
 from .browser_load_extensions_params import BrowserLoadExtensionsParams as BrowserLoadExtensionsParams
+from .browser_location_request_param import BrowserLocationRequestParam as BrowserLocationRequestParam
 from .config_registry_resolve_params import ConfigRegistryResolveParams as ConfigRegistryResolveParams
 from .credential_provider_list_params import CredentialProviderListParams as CredentialProviderListParams
 from .credential_provider_test_result import CredentialProviderTestResult as CredentialProviderTestResult
@@ -153,6 +156,9 @@
 from .vault_provider_config_list_params import VaultProviderConfigListParams as VaultProviderConfigListParams
 from .vault_provider_config_create_params import VaultProviderConfigCreateParams as VaultProviderConfigCreateParams
 from .vault_provider_config_update_params import VaultProviderConfigUpdateParams as VaultProviderConfigUpdateParams
+from .browser_location_update_request_param import (
+    BrowserLocationUpdateRequestParam as BrowserLocationUpdateRequestParam,
+)
 from .credential_provider_list_items_response import (
     CredentialProviderListItemsResponse as CredentialProviderListItemsResponse,
 )

src/kernel/types/browser_create_params.py

@@ -12,6 +12,7 @@
 from .browser_proxy_config_param import BrowserProxyConfigParam
 from .browser_network_config_param import BrowserNetworkConfigParam
 from .shared_params.browser_profile import BrowserProfile
+from .browser_location_request_param import BrowserLocationRequestParam
 from .shared_params.browser_viewport import BrowserViewport
 from .shared_params.browser_extension import BrowserExtension
 from .browsers.browser_telemetry_categories_config_param import BrowserTelemetryCategoriesConfigParam
@@ -62,6 +63,13 @@ class BrowserCreateParams(TypedDict, total=False):
     view.
     """
 
+    location: BrowserLocationRequestParam
+    """Optional session-only timezone and locale overrides.
+
+    Each omitted field uses the default for the browser's region. start_url opens
+    once the location applies.
+    """
+
     memory: BrowserMemoryRequest
     """Memory for a non-GPU browser.
 

src/kernel/types/browser_create_response.py

@@ -11,6 +11,7 @@
 from .browser_usage import BrowserUsage
 from .browser_memory import BrowserMemory
 from .vault_reference import VaultReference
+from .browser_location import BrowserLocation
 from .browser_pool_ref import BrowserPoolRef
 from .browser_video_memory import BrowserVideoMemory
 from .browser_network_config import BrowserNetworkConfig
@@ -76,6 +77,9 @@ class BrowserCreateResponse(BaseModel):
     kiosk_mode: Optional[bool] = None
     """Whether the browser session is running in kiosk mode."""
 
+    location: Optional[BrowserLocation] = None
+    """Effective browser timezone and locale with per-field provenance."""
+
     name: Optional[str] = None
     """Human-readable name of the browser session, if one was set at creation."""
 

src/kernel/types/browser_list_response.py

@@ -11,6 +11,7 @@
 from .browser_usage import BrowserUsage
 from .browser_memory import BrowserMemory
 from .vault_reference import VaultReference
+from .browser_location import BrowserLocation
 from .browser_pool_ref import BrowserPoolRef
 from .browser_video_memory import BrowserVideoMemory
 from .browser_network_config import BrowserNetworkConfig
@@ -76,6 +77,9 @@ class BrowserListResponse(BaseModel):
     kiosk_mode: Optional[bool] = None
     """Whether the browser session is running in kiosk mode."""
 
+    location: Optional[BrowserLocation] = None
+    """Effective browser timezone and locale with per-field provenance."""
+
     name: Optional[str] = None
     """Human-readable name of the browser session, if one was set at creation."""
 

src/kernel/types/browser_location.py

@@ -0,0 +1,28 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from .._models import BaseModel
+from .browser_location_source import BrowserLocationSource
+
+__all__ = ["BrowserLocation"]
+
+
+class BrowserLocation(BaseModel):
+    locale: str
+    """Effective canonical BCP 47 formatting locale selected for the browser session."""
+
+    locale_source: BrowserLocationSource
+    """Where one effective browser location field came from.
+
+    `override` is set explicitly on the session; `metro` is the default for the
+    browser's region.
+    """
+
+    timezone: str
+    """Effective IANA timezone selected for the browser session."""
+
+    timezone_source: BrowserLocationSource
+    """Where one effective browser location field came from.
+
+    `override` is set explicitly on the session; `metro` is the default for the
+    browser's region.
+    """

src/kernel/types/browser_location_request_param.py

@@ -0,0 +1,21 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from __future__ import annotations
+
+from typing_extensions import TypedDict
+
+__all__ = ["BrowserLocationRequestParam"]
+
+
+class BrowserLocationRequestParam(TypedDict, total=False):
+    locale: str
+    """Session-only supported canonical BCP 47 locale override.
+
+    Omit to use the default for the browser's region.
+    """
+
+    timezone: str
+    """Session-only IANA timezone override.
+
+    Omit to use the default for the browser's region.
+    """

src/kernel/types/browser_location_source.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__ = ["BrowserLocationSource"]
+
+BrowserLocationSource: TypeAlias = Literal["override", "metro"]