feat: Support hot swap proxy on a session

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 90
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-cc60c65c6bb0b8a8ea662cf758806e641790870ded35f6ffdb9f4801f3d29b15.yml
-openapi_spec_hash: a1074e1bba578bcd5912512166ada0dc
-config_hash: 7868d3397406c2974b6f058488aeefd6
+configured_endpoints: 91
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-4f5307643555b7917e8681b1966ae0b99f770cf59805e2f917ec7528edf11ba8.yml
+openapi_spec_hash: 873a9aa3a88b6cec1ad94f848eeb1c45
+config_hash: 20337f7888852c165d099faa7589c90a

api.md

@@ -67,12 +67,14 @@ Types:
 - <code><a href="./src/resources/browsers/browsers.ts">Profile</a></code>
 - <code><a href="./src/resources/browsers/browsers.ts">BrowserCreateResponse</a></code>
 - <code><a href="./src/resources/browsers/browsers.ts">BrowserRetrieveResponse</a></code>
+- <code><a href="./src/resources/browsers/browsers.ts">BrowserUpdateResponse</a></code>
 - <code><a href="./src/resources/browsers/browsers.ts">BrowserListResponse</a></code>
 
 Methods:
 
 - <code title="post /browsers">client.browsers.<a href="./src/resources/browsers/browsers.ts">create</a>({ ...params }) -> BrowserCreateResponse</code>
 - <code title="get /browsers/{id}">client.browsers.<a href="./src/resources/browsers/browsers.ts">retrieve</a>(id) -> BrowserRetrieveResponse</code>
+- <code title="patch /browsers/{id}">client.browsers.<a href="./src/resources/browsers/browsers.ts">update</a>(id, { ...params }) -> BrowserUpdateResponse</code>
 - <code title="get /browsers">client.browsers.<a href="./src/resources/browsers/browsers.ts">list</a>({ ...params }) -> BrowserListResponsesOffsetPagination</code>
 - <code title="delete /browsers">client.browsers.<a href="./src/resources/browsers/browsers.ts">delete</a>({ ...params }) -> void</code>
 - <code title="delete /browsers/{id}">client.browsers.<a href="./src/resources/browsers/browsers.ts">deleteByID</a>(id) -> void</code>

src/client.ts

@@ -95,6 +95,8 @@ import {
   BrowserLoadExtensionsParams,
   BrowserPersistence,
   BrowserRetrieveResponse,
+  BrowserUpdateParams,
+  BrowserUpdateResponse,
   Browsers,
   Profile,
 } from './resources/browsers/browsers';
@@ -933,9 +935,11 @@ export declare namespace Kernel {
     type Profile as Profile,
     type BrowserCreateResponse as BrowserCreateResponse,
     type BrowserRetrieveResponse as BrowserRetrieveResponse,
+    type BrowserUpdateResponse as BrowserUpdateResponse,
     type BrowserListResponse as BrowserListResponse,
     type BrowserListResponsesOffsetPagination as BrowserListResponsesOffsetPagination,
     type BrowserCreateParams as BrowserCreateParams,
+    type BrowserUpdateParams as BrowserUpdateParams,
     type BrowserListParams as BrowserListParams,
     type BrowserDeleteParams as BrowserDeleteParams,
     type BrowserLoadExtensionsParams as BrowserLoadExtensionsParams,

src/resources/browsers/browsers.ts

@@ -109,6 +109,20 @@ export class Browsers extends APIResource {
     return this._client.get(path`/browsers/${id}`, options);
   }
 
+  /**
+   * Update a browser session.
+   *
+   * @example
+   * ```ts
+   * const browser = await client.browsers.update(
+   *   'htzv5orfit78e1m2biiifpbv',
+   * );
+   * ```
+   */
+  update(id: string, body: BrowserUpdateParams, options?: RequestOptions): APIPromise<BrowserUpdateResponse> {
+    return this._client.patch(path`/browsers/${id}`, { body, ...options });
+  }
+
   /**
    * List all browser sessions with pagination support. Use include_deleted=true to
    * include soft-deleted sessions in the results.
@@ -382,6 +396,82 @@ export interface BrowserRetrieveResponse {
   viewport?: Shared.BrowserViewport;
 }
 
+export interface BrowserUpdateResponse {
+  /**
+   * Websocket URL for Chrome DevTools Protocol connections to the browser session
+   */
+  cdp_ws_url: string;
+
+  /**
+   * When the browser session was created.
+   */
+  created_at: string;
+
+  /**
+   * Whether the browser session is running in headless mode.
+   */
+  headless: boolean;
+
+  /**
+   * Unique identifier for the browser session
+   */
+  session_id: string;
+
+  /**
+   * Whether the browser session is running in stealth mode.
+   */
+  stealth: boolean;
+
+  /**
+   * The number of seconds of inactivity before the browser session is terminated.
+   */
+  timeout_seconds: number;
+
+  /**
+   * Remote URL for live viewing the browser session. Only available for non-headless
+   * browsers.
+   */
+  browser_live_view_url?: string;
+
+  /**
+   * When the browser session was soft-deleted. Only present for deleted sessions.
+   */
+  deleted_at?: string;
+
+  /**
+   * Whether the browser session is running in kiosk mode.
+   */
+  kiosk_mode?: boolean;
+
+  /**
+   * @deprecated DEPRECATED: Use timeout_seconds (up to 72 hours) and Profiles
+   * instead.
+   */
+  persistence?: BrowserPersistence;
+
+  /**
+   * Browser profile metadata.
+   */
+  profile?: Profile;
+
+  /**
+   * ID of the proxy associated with this browser session, if any.
+   */
+  proxy_id?: string;
+
+  /**
+   * Initial browser window size in pixels with optional refresh rate. If omitted,
+   * image defaults apply (1920x1080@25). Only specific viewport configurations are
+   * supported. The server will reject unsupported combinations. Supported
+   * resolutions are: 2560x1440@10, 1920x1080@25, 1920x1200@25, 1440x900@25,
+   * 1024x768@60, 1200x800@60 If refresh_rate is not provided, it will be
+   * automatically determined from the width and height if they match a supported
+   * configuration exactly. Note: Higher resolutions may affect the responsiveness of
+   * live view browser
+   */
+  viewport?: Shared.BrowserViewport;
+}
+
 export interface BrowserListResponse {
   /**
    * Websocket URL for Chrome DevTools Protocol connections to the browser session
@@ -528,6 +618,14 @@ export interface BrowserCreateParams {
   viewport?: Shared.BrowserViewport;
 }
 
+export interface BrowserUpdateParams {
+  /**
+   * ID of the proxy to use. Omit to leave unchanged, set to empty string to remove
+   * proxy.
+   */
+  proxy_id?: string | null;
+}
+
 export interface BrowserListParams extends OffsetPaginationParams {
   /**
    * When true, includes soft-deleted browser sessions in the results alongside
@@ -578,9 +676,11 @@ export declare namespace Browsers {
     type Profile as Profile,
     type BrowserCreateResponse as BrowserCreateResponse,
     type BrowserRetrieveResponse as BrowserRetrieveResponse,
+    type BrowserUpdateResponse as BrowserUpdateResponse,
     type BrowserListResponse as BrowserListResponse,
     type BrowserListResponsesOffsetPagination as BrowserListResponsesOffsetPagination,
     type BrowserCreateParams as BrowserCreateParams,
+    type BrowserUpdateParams as BrowserUpdateParams,
     type BrowserListParams as BrowserListParams,
     type BrowserDeleteParams as BrowserDeleteParams,
     type BrowserLoadExtensionsParams as BrowserLoadExtensionsParams,

src/resources/browsers/index.ts

@@ -6,8 +6,10 @@ export {
   type Profile,
   type BrowserCreateResponse,
   type BrowserRetrieveResponse,
+  type BrowserUpdateResponse,
   type BrowserListResponse,
   type BrowserCreateParams,
+  type BrowserUpdateParams,
   type BrowserListParams,
   type BrowserDeleteParams,
   type BrowserLoadExtensionsParams,

src/resources/index.ts

@@ -25,8 +25,10 @@ export {
   type Profile,
   type BrowserCreateResponse,
   type BrowserRetrieveResponse,
+  type BrowserUpdateResponse,
   type BrowserListResponse,
   type BrowserCreateParams,
+  type BrowserUpdateParams,
   type BrowserListParams,
   type BrowserDeleteParams,
   type BrowserLoadExtensionsParams,

tests/api-resources/browsers/browsers.test.ts

@@ -62,6 +62,18 @@ describe('resource browsers', () => {
     expect(dataAndResponse.response).toBe(rawResponse);
   });
 
+  // Prism tests are disabled
+  test.skip('update', async () => {
+    const responsePromise = client.browsers.update('htzv5orfit78e1m2biiifpbv', {});
+    const rawResponse = await responsePromise.asResponse();
+    expect(rawResponse).toBeInstanceOf(Response);
+    const response = await responsePromise;
+    expect(response).not.toBeInstanceOf(Response);
+    const dataAndResponse = await responsePromise.withResponse();
+    expect(dataAndResponse.data).toBe(response);
+    expect(dataAndResponse.response).toBe(rawResponse);
+  });
+
   // Prism tests are disabled
   test.skip('list', async () => {
     const responsePromise = client.browsers.list();