feat: allow get browser to paginate soft deleted browsers

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 66
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-d611cf8b0301a07123eab0e92498bea5ad69c5292b28aca1016c362cca0a0564.yml
-openapi_spec_hash: 6d30f4ad9d61a7da8a75d543cf3d3d75
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-2af1b468584cb44aa9babbbfb82bff4055614fbb5c815084a6b7dacc1cf1a822.yml
+openapi_spec_hash: 891affa2849341ea01d62011125f7edc
 config_hash: 9421eb86b7f3f4b274f123279da3858e

api.md

@@ -70,7 +70,7 @@ 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="get /browsers">client.browsers.<a href="./src/resources/browsers/browsers.ts">list</a>() -> BrowserListResponse</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>
 - <code title="post /browsers/{id}/extensions">client.browsers.<a href="./src/resources/browsers/browsers.ts">loadExtensions</a>(id, { ...params }) -> void</code>

src/client.ts

@@ -65,7 +65,9 @@ import {
   BrowserCreateParams,
   BrowserCreateResponse,
   BrowserDeleteParams,
+  BrowserListParams,
   BrowserListResponse,
+  BrowserListResponsesOffsetPagination,
   BrowserLoadExtensionsParams,
   BrowserPersistence,
   BrowserRetrieveResponse,
@@ -902,7 +904,9 @@ export declare namespace Kernel {
     type BrowserCreateResponse as BrowserCreateResponse,
     type BrowserRetrieveResponse as BrowserRetrieveResponse,
     type BrowserListResponse as BrowserListResponse,
+    type BrowserListResponsesOffsetPagination as BrowserListResponsesOffsetPagination,
     type BrowserCreateParams as BrowserCreateParams,
+    type BrowserListParams as BrowserListParams,
     type BrowserDeleteParams as BrowserDeleteParams,
     type BrowserLoadExtensionsParams as BrowserLoadExtensionsParams,
   };

src/resources/browsers/browsers.ts

@@ -1,7 +1,6 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 import { APIResource } from '../../core/resource';
-import * as BrowsersAPI from './browsers';
 import * as ComputerAPI from './computer';
 import {
   Computer,
@@ -63,6 +62,7 @@ import {
   Fs,
 } from './fs/fs';
 import { APIPromise } from '../../core/api-promise';
+import { OffsetPagination, type OffsetPaginationParams, PagePromise } from '../../core/pagination';
 import { type Uploadable } from '../../core/uploads';
 import { buildHeaders } from '../../internal/headers';
 import { RequestOptions } from '../../internal/request-options';
@@ -107,15 +107,22 @@ export class Browsers extends APIResource {
   }
 
   /**
-   * List active browser sessions
+   * List all browser sessions with pagination support. Use include_deleted=true to
+   * include soft-deleted sessions in the results.
    *
    * @example
    * ```ts
-   * const browsers = await client.browsers.list();
+   * // Automatically fetches more pages as needed.
+   * for await (const browserListResponse of client.browsers.list()) {
+   *   // ...
+   * }
    * ```
    */
-  list(options?: RequestOptions): APIPromise<BrowserListResponse> {
-    return this._client.get('/browsers', options);
+  list(
+    query: BrowserListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<BrowserListResponsesOffsetPagination, BrowserListResponse> {
+    return this._client.getAPIList('/browsers', OffsetPagination<BrowserListResponse>, { query, ...options });
   }
 
   /**
@@ -181,6 +188,8 @@ export class Browsers extends APIResource {
   }
 }
 
+export type BrowserListResponsesOffsetPagination = OffsetPagination<BrowserListResponse>;
+
 /**
  * Optional persistence configuration for the browser session.
  */
@@ -258,6 +267,11 @@ export interface BrowserCreateResponse {
    */
   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.
    */
@@ -358,6 +372,11 @@ export interface BrowserRetrieveResponse {
    */
   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.
    */
@@ -421,107 +440,108 @@ export namespace BrowserRetrieveResponse {
   }
 }
 
-export type BrowserListResponse = Array<BrowserListResponse.BrowserListResponseItem>;
+export interface BrowserListResponse {
+  /**
+   * Websocket URL for Chrome DevTools Protocol connections to the browser session
+   */
+  cdp_ws_url: string;
 
-export namespace BrowserListResponse {
-  export interface BrowserListResponseItem {
-    /**
-     * Websocket URL for Chrome DevTools Protocol connections to the browser session
-     */
-    cdp_ws_url: string;
+  /**
+   * When the browser session was created.
+   */
+  created_at: string;
 
-    /**
-     * When the browser session was created.
-     */
-    created_at: string;
+  /**
+   * Whether the browser session is running in headless mode.
+   */
+  headless: boolean;
 
-    /**
-     * Whether the browser session is running in headless mode.
-     */
-    headless: boolean;
+  /**
+   * Unique identifier for the browser session
+   */
+  session_id: string;
 
-    /**
-     * Unique identifier for the browser session
-     */
-    session_id: string;
+  /**
+   * Whether the browser session is running in stealth mode.
+   */
+  stealth: boolean;
 
-    /**
-     * 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;
 
-    /**
-     * 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;
 
-    /**
-     * 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;
+  /**
+   * Whether the browser session is running in kiosk mode.
+   */
+  kiosk_mode?: boolean;
 
-    /**
-     * Optional persistence configuration for the browser session.
-     */
-    persistence?: BrowsersAPI.BrowserPersistence;
+  /**
+   * Optional persistence configuration for the browser session.
+   */
+  persistence?: BrowserPersistence;
 
-    /**
-     * Browser profile metadata.
-     */
-    profile?: BrowsersAPI.Profile;
+  /**
+   * 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 (commonly 1024x768@60). 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?: BrowserListResponse.Viewport;
+}
 
+export namespace BrowserListResponse {
+  /**
+   * Initial browser window size in pixels with optional refresh rate. If omitted,
+   * image defaults apply (commonly 1024x768@60). 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
+   */
+  export interface Viewport {
     /**
-     * ID of the proxy associated with this browser session, if any.
+     * Browser window height in pixels.
      */
-    proxy_id?: string;
+    height: number;
 
     /**
-     * Initial browser window size in pixels with optional refresh rate. If omitted,
-     * image defaults apply (commonly 1024x768@60). 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
+     * Browser window width in pixels.
      */
-    viewport?: BrowserListResponseItem.Viewport;
-  }
+    width: number;
 
-  export namespace BrowserListResponseItem {
     /**
-     * Initial browser window size in pixels with optional refresh rate. If omitted,
-     * image defaults apply (commonly 1024x768@60). 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
+     * Display refresh rate in Hz. If omitted, automatically determined from width and
+     * height.
      */
-    export interface Viewport {
-      /**
-       * Browser window height in pixels.
-       */
-      height: number;
-
-      /**
-       * Browser window width in pixels.
-       */
-      width: number;
-
-      /**
-       * Display refresh rate in Hz. If omitted, automatically determined from width and
-       * height.
-       */
-      refresh_rate?: number;
-    }
+    refresh_rate?: number;
   }
 }
 
@@ -666,6 +686,14 @@ export namespace BrowserCreateParams {
   }
 }
 
+export interface BrowserListParams extends OffsetPaginationParams {
+  /**
+   * When true, includes soft-deleted browser sessions in the results alongside
+   * active sessions.
+   */
+  include_deleted?: boolean;
+}
+
 export interface BrowserDeleteParams {
   /**
    * Persistent browser identifier
@@ -709,7 +737,9 @@ export declare namespace Browsers {
     type BrowserCreateResponse as BrowserCreateResponse,
     type BrowserRetrieveResponse as BrowserRetrieveResponse,
     type BrowserListResponse as BrowserListResponse,
+    type BrowserListResponsesOffsetPagination as BrowserListResponsesOffsetPagination,
     type BrowserCreateParams as BrowserCreateParams,
+    type BrowserListParams as BrowserListParams,
     type BrowserDeleteParams as BrowserDeleteParams,
     type BrowserLoadExtensionsParams as BrowserLoadExtensionsParams,
   };

src/resources/browsers/index.ts

@@ -8,8 +8,10 @@ export {
   type BrowserRetrieveResponse,
   type BrowserListResponse,
   type BrowserCreateParams,
+  type BrowserListParams,
   type BrowserDeleteParams,
   type BrowserLoadExtensionsParams,
+  type BrowserListResponsesOffsetPagination,
 } from './browsers';
 export {
   Computer,

src/resources/index.ts

@@ -15,8 +15,10 @@ export {
   type BrowserRetrieveResponse,
   type BrowserListResponse,
   type BrowserCreateParams,
+  type BrowserListParams,
   type BrowserDeleteParams,
   type BrowserLoadExtensionsParams,
+  type BrowserListResponsesOffsetPagination,
 } from './browsers/browsers';
 export {
   Deployments,

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

@@ -66,6 +66,17 @@ describe('resource browsers', () => {
     expect(dataAndResponse.response).toBe(rawResponse);
   });
 
+  // Prism tests are disabled
+  test.skip('list: request options and params are passed correctly', async () => {
+    // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error
+    await expect(
+      client.browsers.list(
+        { include_deleted: true, limit: 1, offset: 0 },
+        { path: '/_stainless_unknown_path' },
+      ),
+    ).rejects.toThrow(Kernel.NotFoundError);
+  });
+
   // Prism tests are disabled
   test.skip('delete: only required params', async () => {
     const responsePromise = client.browsers.delete({ persistent_id: 'persistent_id' });