feat: Auto-flush pools when a managed auth profile re-authenticates

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 125
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel/kernel-f6795e5d85e37b74f59876434c74b598e34171f99bc598c85b789abbb60614f1.yml
-openapi_spec_hash: 98e86fcbf0710a693bb1e03170ca85c3
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel/kernel-58ad412d62b3d94e3258c911d7028716d71191358ff769ce494c4b2d87027254.yml
+openapi_spec_hash: 45d710b7d2a9beadff021514bb997ba1
 config_hash: 06186eb40e0058a2a87ac251fc07415d

src/kernel/resources/browser_pools.py

@@ -69,6 +69,7 @@ def create(
         name: str | Omit = omit,
         profile: browser_pool_create_params.Profile | Omit = omit,
         proxy_id: str | Omit = omit,
+        refresh_on_profile_update: bool | Omit = omit,
         start_url: str | Omit = omit,
         stealth: bool | Omit = omit,
         timeout_seconds: int | Omit = omit,
@@ -110,16 +111,19 @@ def create(
 
           name: Optional name for the browser pool. Must be unique within the project.
 
-          profile: Profile selection for browsers in a pool. Provide either id or name. The
-              matching profile is loaded into every browser in the pool. Profiles must be
-              created beforehand. Unlike single browser sessions, pools load the profile
-              read-only and never persist changes back to it, so save_changes is omitted here.
-              Any save_changes value sent on a pool profile is silently ignored rather than
-              rejected, so callers reusing a single-session profile object will not error.
+          profile: Profile configuration for browsers in a pool. Provide either id or name.
+              Profiles must be created beforehand. Unlike single browser sessions, pools load
+              the profile read-only and never persist changes back to it, so save_changes is
+              omitted here. Any save_changes value sent on a pool profile is silently ignored
+              rather than rejected.
 
           proxy_id: Optional proxy to associate to the browser session. Must reference a proxy in
               the same project as the browser session.
 
+          refresh_on_profile_update: When true, flush idle browsers when the profile the pool uses is updated, so
+              pool browsers pick up the latest profile data. Requires a profile to be set on
+              the pool.
+
           start_url: Optional URL to navigate to when a new browser is warmed into the pool.
               Best-effort: failures to navigate do not fail pool fill. Only applied to
               newly-warmed browsers; browsers reused via release/acquire keep whatever URL the
@@ -166,6 +170,7 @@ def create(
                     "name": name,
                     "profile": profile,
                     "proxy_id": proxy_id,
+                    "refresh_on_profile_update": refresh_on_profile_update,
                     "start_url": start_url,
                     "stealth": stealth,
                     "timeout_seconds": timeout_seconds,
@@ -225,6 +230,7 @@ def update(
         name: str | Omit = omit,
         profile: browser_pool_update_params.Profile | Omit = omit,
         proxy_id: str | Omit = omit,
+        refresh_on_profile_update: bool | Omit = omit,
         size: int | Omit = omit,
         start_url: str | Omit = omit,
         stealth: bool | Omit = omit,
@@ -241,7 +247,9 @@ def update(
 
         As with creation,
         save_changes on the pool profile is ignored (not rejected); pooled browsers
-        never persist changes back to the profile.
+        never persist changes back to the profile. To clear the profile reference, send
+        `profile: { "id": "" }`. Clearing the profile also disables
+        `refresh_on_profile_update`.
 
         Args:
           chrome_policy: Custom Chrome enterprise policy overrides applied to all browsers in this pool.
@@ -269,16 +277,19 @@ def update(
 
           name: Optional name for the browser pool. Must be unique within the project.
 
-          profile: Profile selection for browsers in a pool. Provide either id or name. The
-              matching profile is loaded into every browser in the pool. Profiles must be
-              created beforehand. Unlike single browser sessions, pools load the profile
-              read-only and never persist changes back to it, so save_changes is omitted here.
-              Any save_changes value sent on a pool profile is silently ignored rather than
-              rejected, so callers reusing a single-session profile object will not error.
+          profile: Profile configuration for browsers in a pool. Provide either id or name.
+              Profiles must be created beforehand. Unlike single browser sessions, pools load
+              the profile read-only and never persist changes back to it, so save_changes is
+              omitted here. Any save_changes value sent on a pool profile is silently ignored
+              rather than rejected.
 
           proxy_id: Optional proxy to associate to the browser session. Must reference a proxy in
               the same project as the browser session.
 
+          refresh_on_profile_update: When true, flush idle browsers when the profile the pool uses is updated, so
+              pool browsers pick up the latest profile data. Requires a profile to be set on
+              the pool.
+
           size: Number of browsers to maintain in the pool. The maximum size is determined by
               your organization's pooled sessions limit (the sum of all pool sizes cannot
               exceed your limit).
@@ -331,6 +342,7 @@ def update(
                     "name": name,
                     "profile": profile,
                     "proxy_id": proxy_id,
+                    "refresh_on_profile_update": refresh_on_profile_update,
                     "size": size,
                     "start_url": start_url,
                     "stealth": stealth,
@@ -624,6 +636,7 @@ async def create(
         name: str | Omit = omit,
         profile: browser_pool_create_params.Profile | Omit = omit,
         proxy_id: str | Omit = omit,
+        refresh_on_profile_update: bool | Omit = omit,
         start_url: str | Omit = omit,
         stealth: bool | Omit = omit,
         timeout_seconds: int | Omit = omit,
@@ -665,16 +678,19 @@ async def create(
 
           name: Optional name for the browser pool. Must be unique within the project.
 
-          profile: Profile selection for browsers in a pool. Provide either id or name. The
-              matching profile is loaded into every browser in the pool. Profiles must be
-              created beforehand. Unlike single browser sessions, pools load the profile
-              read-only and never persist changes back to it, so save_changes is omitted here.
-              Any save_changes value sent on a pool profile is silently ignored rather than
-              rejected, so callers reusing a single-session profile object will not error.
+          profile: Profile configuration for browsers in a pool. Provide either id or name.
+              Profiles must be created beforehand. Unlike single browser sessions, pools load
+              the profile read-only and never persist changes back to it, so save_changes is
+              omitted here. Any save_changes value sent on a pool profile is silently ignored
+              rather than rejected.
 
           proxy_id: Optional proxy to associate to the browser session. Must reference a proxy in
               the same project as the browser session.
 
+          refresh_on_profile_update: When true, flush idle browsers when the profile the pool uses is updated, so
+              pool browsers pick up the latest profile data. Requires a profile to be set on
+              the pool.
+
           start_url: Optional URL to navigate to when a new browser is warmed into the pool.
               Best-effort: failures to navigate do not fail pool fill. Only applied to
               newly-warmed browsers; browsers reused via release/acquire keep whatever URL the
@@ -721,6 +737,7 @@ async def create(
                     "name": name,
                     "profile": profile,
                     "proxy_id": proxy_id,
+                    "refresh_on_profile_update": refresh_on_profile_update,
                     "start_url": start_url,
                     "stealth": stealth,
                     "timeout_seconds": timeout_seconds,
@@ -780,6 +797,7 @@ async def update(
         name: str | Omit = omit,
         profile: browser_pool_update_params.Profile | Omit = omit,
         proxy_id: str | Omit = omit,
+        refresh_on_profile_update: bool | Omit = omit,
         size: int | Omit = omit,
         start_url: str | Omit = omit,
         stealth: bool | Omit = omit,
@@ -796,7 +814,9 @@ async def update(
 
         As with creation,
         save_changes on the pool profile is ignored (not rejected); pooled browsers
-        never persist changes back to the profile.
+        never persist changes back to the profile. To clear the profile reference, send
+        `profile: { "id": "" }`. Clearing the profile also disables
+        `refresh_on_profile_update`.
 
         Args:
           chrome_policy: Custom Chrome enterprise policy overrides applied to all browsers in this pool.
@@ -824,16 +844,19 @@ async def update(
 
           name: Optional name for the browser pool. Must be unique within the project.
 
-          profile: Profile selection for browsers in a pool. Provide either id or name. The
-              matching profile is loaded into every browser in the pool. Profiles must be
-              created beforehand. Unlike single browser sessions, pools load the profile
-              read-only and never persist changes back to it, so save_changes is omitted here.
-              Any save_changes value sent on a pool profile is silently ignored rather than
-              rejected, so callers reusing a single-session profile object will not error.
+          profile: Profile configuration for browsers in a pool. Provide either id or name.
+              Profiles must be created beforehand. Unlike single browser sessions, pools load
+              the profile read-only and never persist changes back to it, so save_changes is
+              omitted here. Any save_changes value sent on a pool profile is silently ignored
+              rather than rejected.
 
           proxy_id: Optional proxy to associate to the browser session. Must reference a proxy in
               the same project as the browser session.
 
+          refresh_on_profile_update: When true, flush idle browsers when the profile the pool uses is updated, so
+              pool browsers pick up the latest profile data. Requires a profile to be set on
+              the pool.
+
           size: Number of browsers to maintain in the pool. The maximum size is determined by
               your organization's pooled sessions limit (the sum of all pool sizes cannot
               exceed your limit).
@@ -886,6 +909,7 @@ async def update(
                     "name": name,
                     "profile": profile,
                     "proxy_id": proxy_id,
+                    "refresh_on_profile_update": refresh_on_profile_update,
                     "size": size,
                     "start_url": start_url,
                     "stealth": stealth,

src/kernel/types/browser_pool.py

@@ -11,13 +11,12 @@
 
 
 class BrowserPoolConfigProfile(BaseModel):
-    """Profile selection for browsers in a pool.
+    """Profile configuration for browsers in a pool.
 
-    Provide either id or name. The matching profile is
-    loaded into every browser in the pool. Profiles must be created beforehand. Unlike single
-    browser sessions, pools load the profile read-only and never persist changes back to it, so
-    save_changes is omitted here. Any save_changes value sent on a pool profile is silently
-    ignored rather than rejected, so callers reusing a single-session profile object will not error.
+    Provide either id or name. Profiles must
+    be created beforehand. Unlike single browser sessions, pools load the profile read-only
+    and never persist changes back to it, so save_changes is omitted here. Any save_changes
+    value sent on a pool profile is silently ignored rather than rejected.
     """
 
     id: Optional[str] = None
@@ -74,14 +73,12 @@ class BrowserPoolConfig(BaseModel):
     """Optional name for the browser pool. Must be unique within the project."""
 
     profile: Optional[BrowserPoolConfigProfile] = None
-    """Profile selection for browsers in a pool.
+    """Profile configuration for browsers in a pool.
 
-    Provide either id or name. The matching profile is loaded into every browser in
-    the pool. Profiles must be created beforehand. Unlike single browser sessions,
-    pools load the profile read-only and never persist changes back to it, so
-    save_changes is omitted here. Any save_changes value sent on a pool profile is
-    silently ignored rather than rejected, so callers reusing a single-session
-    profile object will not error.
+    Provide either id or name. Profiles must be created beforehand. Unlike single
+    browser sessions, pools load the profile read-only and never persist changes
+    back to it, so save_changes is omitted here. Any save_changes value sent on a
+    pool profile is silently ignored rather than rejected.
     """
 
     proxy_id: Optional[str] = None
@@ -90,6 +87,13 @@ class BrowserPoolConfig(BaseModel):
     Must reference a proxy in the same project as the browser session.
     """
 
+    refresh_on_profile_update: Optional[bool] = None
+    """
+    When true, flush idle browsers when the profile the pool uses is updated, so
+    pool browsers pick up the latest profile data. Requires a profile to be set on
+    the pool.
+    """
+
     start_url: Optional[str] = None
     """Optional URL to navigate to when a new browser is warmed into the pool.
 

src/kernel/types/browser_pool_create_params.py

@@ -53,14 +53,12 @@ class BrowserPoolCreateParams(TypedDict, total=False):
     """Optional name for the browser pool. Must be unique within the project."""
 
     profile: Profile
-    """Profile selection for browsers in a pool.
+    """Profile configuration for browsers in a pool.
 
-    Provide either id or name. The matching profile is loaded into every browser in
-    the pool. Profiles must be created beforehand. Unlike single browser sessions,
-    pools load the profile read-only and never persist changes back to it, so
-    save_changes is omitted here. Any save_changes value sent on a pool profile is
-    silently ignored rather than rejected, so callers reusing a single-session
-    profile object will not error.
+    Provide either id or name. Profiles must be created beforehand. Unlike single
+    browser sessions, pools load the profile read-only and never persist changes
+    back to it, so save_changes is omitted here. Any save_changes value sent on a
+    pool profile is silently ignored rather than rejected.
     """
 
     proxy_id: str
@@ -69,6 +67,13 @@ class BrowserPoolCreateParams(TypedDict, total=False):
     Must reference a proxy in the same project as the browser session.
     """
 
+    refresh_on_profile_update: bool
+    """
+    When true, flush idle browsers when the profile the pool uses is updated, so
+    pool browsers pick up the latest profile data. Requires a profile to be set on
+    the pool.
+    """
+
     start_url: str
     """Optional URL to navigate to when a new browser is warmed into the pool.
 
@@ -108,13 +113,12 @@ class BrowserPoolCreateParams(TypedDict, total=False):
 
 
 class Profile(TypedDict, total=False):
-    """Profile selection for browsers in a pool.
+    """Profile configuration for browsers in a pool.
 
-    Provide either id or name. The matching profile is
-    loaded into every browser in the pool. Profiles must be created beforehand. Unlike single
-    browser sessions, pools load the profile read-only and never persist changes back to it, so
-    save_changes is omitted here. Any save_changes value sent on a pool profile is silently
-    ignored rather than rejected, so callers reusing a single-session profile object will not error.
+    Provide either id or name. Profiles must
+    be created beforehand. Unlike single browser sessions, pools load the profile read-only
+    and never persist changes back to it, so save_changes is omitted here. Any save_changes
+    value sent on a pool profile is silently ignored rather than rejected.
     """
 
     id: str

src/kernel/types/browser_pool_update_params.py

@@ -56,14 +56,12 @@ class BrowserPoolUpdateParams(TypedDict, total=False):
     """Optional name for the browser pool. Must be unique within the project."""
 
     profile: Profile
-    """Profile selection for browsers in a pool.
+    """Profile configuration for browsers in a pool.
 
-    Provide either id or name. The matching profile is loaded into every browser in
-    the pool. Profiles must be created beforehand. Unlike single browser sessions,
-    pools load the profile read-only and never persist changes back to it, so
-    save_changes is omitted here. Any save_changes value sent on a pool profile is
-    silently ignored rather than rejected, so callers reusing a single-session
-    profile object will not error.
+    Provide either id or name. Profiles must be created beforehand. Unlike single
+    browser sessions, pools load the profile read-only and never persist changes
+    back to it, so save_changes is omitted here. Any save_changes value sent on a
+    pool profile is silently ignored rather than rejected.
     """
 
     proxy_id: str
@@ -72,6 +70,13 @@ class BrowserPoolUpdateParams(TypedDict, total=False):
     Must reference a proxy in the same project as the browser session.
     """
 
+    refresh_on_profile_update: bool
+    """
+    When true, flush idle browsers when the profile the pool uses is updated, so
+    pool browsers pick up the latest profile data. Requires a profile to be set on
+    the pool.
+    """
+
     size: int
     """Number of browsers to maintain in the pool.
 
@@ -118,13 +123,12 @@ class BrowserPoolUpdateParams(TypedDict, total=False):
 
 
 class Profile(TypedDict, total=False):
-    """Profile selection for browsers in a pool.
+    """Profile configuration for browsers in a pool.
 
-    Provide either id or name. The matching profile is
-    loaded into every browser in the pool. Profiles must be created beforehand. Unlike single
-    browser sessions, pools load the profile read-only and never persist changes back to it, so
-    save_changes is omitted here. Any save_changes value sent on a pool profile is silently
-    ignored rather than rejected, so callers reusing a single-session profile object will not error.
+    Provide either id or name. Profiles must
+    be created beforehand. Unlike single browser sessions, pools load the profile read-only
+    and never persist changes back to it, so save_changes is omitted here. Any save_changes
+    value sent on a pool profile is silently ignored rather than rejected.
     """
 
     id: str

tests/api_resources/test_browser_pools.py

@@ -50,6 +50,7 @@ def test_method_create_with_all_params(self, client: Kernel) -> None:
                 "name": "name",
             },
             proxy_id="proxy_id",
+            refresh_on_profile_update=True,
             start_url="https://example.com",
             stealth=True,
             timeout_seconds=10,
@@ -159,6 +160,7 @@ def test_method_update_with_all_params(self, client: Kernel) -> None:
                 "name": "name",
             },
             proxy_id="proxy_id",
+            refresh_on_profile_update=True,
             size=10,
             start_url="https://example.com",
             stealth=True,
@@ -484,6 +486,7 @@ async def test_method_create_with_all_params(self, async_client: AsyncKernel) ->
                 "name": "name",
             },
             proxy_id="proxy_id",
+            refresh_on_profile_update=True,
             start_url="https://example.com",
             stealth=True,
             timeout_seconds=10,
@@ -593,6 +596,7 @@ async def test_method_update_with_all_params(self, async_client: AsyncKernel) ->
                 "name": "name",
             },
             proxy_id="proxy_id",
+            refresh_on_profile_update=True,
             size=10,
             start_url="https://example.com",
             stealth=True,