feat: Add telemetry support for browser pools with BAA enforcement

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 127
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel/kernel-92c776855f978ae03a778fbbac49bf1edc65852530644772c382838b6eab9fe5.yml
-openapi_spec_hash: 4a9fbcb607be408ad646e207fe90687f
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel/kernel-e04362b2c82b88f4f7fb43209c764fa9fdf37fe98932e142547be43a1e99c50b.yml
+openapi_spec_hash: b16e79bfd6cac36090c815a8184b9e09
 config_hash: 77ee715aa17061166f9a02b264a21b8d

src/resources/browser-pools.ts

@@ -295,6 +295,12 @@ export namespace BrowserPool {
      */
     stealth?: boolean;
 
+    /**
+     * Active telemetry configuration applied to browsers warmed into this pool, if
+     * any.
+     */
+    telemetry?: TelemetryAPI.BrowserTelemetryConfig | null;
+
     /**
      * Default idle timeout in seconds for browsers acquired from this pool before they
      * are destroyed. Minimum 10, maximum 259200 (72 hours).
@@ -555,6 +561,16 @@ export interface BrowserPoolCreateParams {
    */
   stealth?: boolean;
 
+  /**
+   * Telemetry configuration applied to browsers warmed into this pool. Set enabled
+   * to true to start capture using the default set, or provide browser category
+   * settings. If omitted, null, set to an empty object ({}), set to enabled: false
+   * without browser category settings, or all four CDP categories are explicitly
+   * disabled, no telemetry is configured on the pool. Only applied to newly-warmed
+   * browsers.
+   */
+  telemetry?: BrowserPoolCreateParams.Telemetry | null;
+
   /**
    * Default idle timeout in seconds for browsers acquired from this pool before they
    * are destroyed. Defaults to 600 seconds. Minimum 10, maximum 259200 (72 hours).
@@ -598,6 +614,41 @@ export namespace BrowserPoolCreateParams {
      */
     name?: string;
   }
+
+  /**
+   * Telemetry configuration applied to browsers warmed into this pool. Set enabled
+   * to true to start capture using the default set, or provide browser category
+   * settings. If omitted, null, set to an empty object ({}), set to enabled: false
+   * without browser category settings, or all four CDP categories are explicitly
+   * disabled, no telemetry is configured on the pool. Only applied to newly-warmed
+   * browsers.
+   */
+  export interface Telemetry {
+    /**
+     * 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.
+     */
+    browser?: TelemetryAPI.BrowserTelemetryCategoriesConfig;
+
+    /**
+     * 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.
+     */
+    enabled?: boolean;
+  }
 }
 
 export interface BrowserPoolUpdateParams {
@@ -693,6 +744,17 @@ export interface BrowserPoolUpdateParams {
    */
   stealth?: boolean;
 
+  /**
+   * If provided, updates the pool's telemetry configuration. Omit, set to null, or
+   * set to an empty object ({}) to leave the existing configuration unchanged. Set
+   * enabled to true to enable capture using the default set. Set enabled to false to
+   * clear the pool's telemetry. Provide browser category settings for per-category
+   * updates, merged onto the pool's current configuration. Only applied to browsers
+   * warmed after the update; browsers already in the pool keep their configuration
+   * until discarded.
+   */
+  telemetry?: BrowserPoolUpdateParams.Telemetry | null;
+
   /**
    * If provided, replaces the default idle timeout in seconds for browsers acquired
    * from this pool before they are destroyed. Minimum 10, maximum 259200 (72 hours).
@@ -736,6 +798,42 @@ export namespace BrowserPoolUpdateParams {
      */
     name?: string;
   }
+
+  /**
+   * If provided, updates the pool's telemetry configuration. Omit, set to null, or
+   * set to an empty object ({}) to leave the existing configuration unchanged. Set
+   * enabled to true to enable capture using the default set. Set enabled to false to
+   * clear the pool's telemetry. Provide browser category settings for per-category
+   * updates, merged onto the pool's current configuration. Only applied to browsers
+   * warmed after the update; browsers already in the pool keep their configuration
+   * until discarded.
+   */
+  export interface Telemetry {
+    /**
+     * 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.
+     */
+    browser?: TelemetryAPI.BrowserTelemetryCategoriesConfig;
+
+    /**
+     * 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.
+     */
+    enabled?: boolean;
+  }
 }
 
 export interface BrowserPoolListParams extends OffsetPaginationParams {
@@ -791,6 +889,57 @@ export interface BrowserPoolAcquireParams {
    * the browser is released back to the pool. Up to 50 pairs.
    */
   tags?: BrowsersAPI.Tags;
+
+  /**
+   * Telemetry override for the acquired browser, applied to this lease only. Merges
+   * onto the browser's current (pool-inherited) telemetry using the same
+   * per-category semantics as PATCH /browsers: provided categories override the
+   * current configuration, omitted categories are inherited. Set enabled to true to
+   * resolve the config fresh from the default set, or enabled to false to stop
+   * capture. When the browser is released back to the pool with reuse, its telemetry
+   * is reset to the pool's baseline, so the override does not carry over to the next
+   * lease.
+   */
+  telemetry?: BrowserPoolAcquireParams.Telemetry | null;
+}
+
+export namespace BrowserPoolAcquireParams {
+  /**
+   * Telemetry override for the acquired browser, applied to this lease only. Merges
+   * onto the browser's current (pool-inherited) telemetry using the same
+   * per-category semantics as PATCH /browsers: provided categories override the
+   * current configuration, omitted categories are inherited. Set enabled to true to
+   * resolve the config fresh from the default set, or enabled to false to stop
+   * capture. When the browser is released back to the pool with reuse, its telemetry
+   * is reset to the pool's baseline, so the override does not carry over to the next
+   * lease.
+   */
+  export interface Telemetry {
+    /**
+     * 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.
+     */
+    browser?: TelemetryAPI.BrowserTelemetryCategoriesConfig;
+
+    /**
+     * 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.
+     */
+    enabled?: boolean;
+  }
 }
 
 export interface BrowserPoolReleaseParams {

tests/api-resources/browser-pools.test.ts

@@ -35,6 +35,20 @@ describe('resource browserPools', () => {
       refresh_on_profile_update: true,
       start_url: 'https://example.com',
       stealth: true,
+      telemetry: {
+        browser: {
+          captcha: { enabled: true },
+          connection: { enabled: true },
+          console: { enabled: true },
+          control: { enabled: true },
+          interaction: { enabled: true },
+          network: { enabled: true },
+          page: { enabled: true },
+          screenshot: { enabled: true },
+          system: { enabled: true },
+        },
+        enabled: true,
+      },
       timeout_seconds: 10,
       viewport: {
         height: 800,