feat: api: paginate GET /browser_pools

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 117
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel/kernel-f3e52a8a9d9e37f8b527bdcce63b39cf8807d138cf3570c9954ba7f42ef02375.yml
-openapi_spec_hash: 2b787691eba1bb7bafb553528c09d5c0
-config_hash: e12afec516ced9520590c7a05af7a6f7
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel/kernel-e5524e6eeeedc614c05bf19896f1ce6c4f8a113de85c02952d6874d579651f70.yml
+openapi_spec_hash: 7815a189a50e6aa9e283213cc78d041c
+config_hash: 453b25a35834fd59a55a2315d1d50746

api.md

@@ -307,15 +307,14 @@ Methods:
 Types:
 
 - <code><a href="./src/resources/browser-pools.ts">BrowserPool</a></code>
-- <code><a href="./src/resources/browser-pools.ts">BrowserPoolListResponse</a></code>
 - <code><a href="./src/resources/browser-pools.ts">BrowserPoolAcquireResponse</a></code>
 
 Methods:
 
 - <code title="post /browser_pools">client.browserPools.<a href="./src/resources/browser-pools.ts">create</a>({ ...params }) -> BrowserPool</code>
 - <code title="get /browser_pools/{id_or_name}">client.browserPools.<a href="./src/resources/browser-pools.ts">retrieve</a>(idOrName) -> BrowserPool</code>
 - <code title="patch /browser_pools/{id_or_name}">client.browserPools.<a href="./src/resources/browser-pools.ts">update</a>(idOrName, { ...params }) -> BrowserPool</code>
-- <code title="get /browser_pools">client.browserPools.<a href="./src/resources/browser-pools.ts">list</a>() -> BrowserPoolListResponse</code>
+- <code title="get /browser_pools">client.browserPools.<a href="./src/resources/browser-pools.ts">list</a>({ ...params }) -> BrowserPoolsOffsetPagination</code>
 - <code title="delete /browser_pools/{id_or_name}">client.browserPools.<a href="./src/resources/browser-pools.ts">delete</a>(idOrName, { ...params }) -> void</code>
 - <code title="post /browser_pools/{id_or_name}/acquire">client.browserPools.<a href="./src/resources/browser-pools.ts">acquire</a>(idOrName, { ...params }) -> BrowserPoolAcquireResponse</code>
 - <code title="post /browser_pools/{id_or_name}/flush">client.browserPools.<a href="./src/resources/browser-pools.ts">flush</a>(idOrName) -> void</code>

src/client.ts

@@ -40,10 +40,11 @@ import {
   BrowserPoolAcquireResponse,
   BrowserPoolCreateParams,
   BrowserPoolDeleteParams,
-  BrowserPoolListResponse,
+  BrowserPoolListParams,
   BrowserPoolReleaseParams,
   BrowserPoolUpdateParams,
   BrowserPools,
+  BrowserPoolsOffsetPagination,
 } from './resources/browser-pools';
 import {
   CreateCredentialProviderRequest,
@@ -1100,10 +1101,11 @@ export declare namespace Kernel {
   export {
     BrowserPools as BrowserPools,
     type BrowserPool as BrowserPool,
-    type BrowserPoolListResponse as BrowserPoolListResponse,
     type BrowserPoolAcquireResponse as BrowserPoolAcquireResponse,
+    type BrowserPoolsOffsetPagination as BrowserPoolsOffsetPagination,
     type BrowserPoolCreateParams as BrowserPoolCreateParams,
     type BrowserPoolUpdateParams as BrowserPoolUpdateParams,
+    type BrowserPoolListParams as BrowserPoolListParams,
     type BrowserPoolDeleteParams as BrowserPoolDeleteParams,
     type BrowserPoolAcquireParams as BrowserPoolAcquireParams,
     type BrowserPoolReleaseParams as BrowserPoolReleaseParams,

src/resources/browser-pools.ts

@@ -5,6 +5,7 @@ import * as Shared from './shared';
 import * as BrowsersAPI from './browsers/browsers';
 import * as TelemetryAPI from './browsers/telemetry';
 import { APIPromise } from '../core/api-promise';
+import { OffsetPagination, type OffsetPaginationParams, PagePromise } from '../core/pagination';
 import { buildHeaders } from '../internal/headers';
 import { RequestOptions } from '../internal/request-options';
 import { path } from '../internal/utils/path';
@@ -60,11 +61,17 @@ export class BrowserPools extends APIResource {
    *
    * @example
    * ```ts
-   * const browserPools = await client.browserPools.list();
+   * // Automatically fetches more pages as needed.
+   * for await (const browserPool of client.browserPools.list()) {
+   *   // ...
+   * }
    * ```
    */
-  list(options?: RequestOptions): APIPromise<BrowserPoolListResponse> {
-    return this._client.get('/browser_pools', options);
+  list(
+    query: BrowserPoolListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<BrowserPoolsOffsetPagination, BrowserPool> {
+    return this._client.getAPIList('/browser_pools', OffsetPagination<BrowserPool>, { query, ...options });
   }
 
   /**
@@ -143,6 +150,8 @@ export class BrowserPools extends APIResource {
   }
 }
 
+export type BrowserPoolsOffsetPagination = OffsetPagination<BrowserPool>;
+
 /**
  * A browser pool containing multiple identically configured browsers.
  */
@@ -276,8 +285,6 @@ export namespace BrowserPool {
   }
 }
 
-export type BrowserPoolListResponse = Array<BrowserPool>;
-
 export interface BrowserPoolAcquireResponse {
   /**
    * Websocket URL for Chrome DevTools Protocol connections to the browser session
@@ -591,6 +598,8 @@ export interface BrowserPoolUpdateParams {
   viewport?: Shared.BrowserViewport;
 }
 
+export interface BrowserPoolListParams extends OffsetPaginationParams {}
+
 export interface BrowserPoolDeleteParams {
   /**
    * If true, force delete even if browsers are currently leased. Leased browsers
@@ -624,10 +633,11 @@ export interface BrowserPoolReleaseParams {
 export declare namespace BrowserPools {
   export {
     type BrowserPool as BrowserPool,
-    type BrowserPoolListResponse as BrowserPoolListResponse,
     type BrowserPoolAcquireResponse as BrowserPoolAcquireResponse,
+    type BrowserPoolsOffsetPagination as BrowserPoolsOffsetPagination,
     type BrowserPoolCreateParams as BrowserPoolCreateParams,
     type BrowserPoolUpdateParams as BrowserPoolUpdateParams,
+    type BrowserPoolListParams as BrowserPoolListParams,
     type BrowserPoolDeleteParams as BrowserPoolDeleteParams,
     type BrowserPoolAcquireParams as BrowserPoolAcquireParams,
     type BrowserPoolReleaseParams as BrowserPoolReleaseParams,

src/resources/index.ts

@@ -20,13 +20,14 @@ export { Auth } from './auth/auth';
 export {
   BrowserPools,
   type BrowserPool,
-  type BrowserPoolListResponse,
   type BrowserPoolAcquireResponse,
   type BrowserPoolCreateParams,
   type BrowserPoolUpdateParams,
+  type BrowserPoolListParams,
   type BrowserPoolDeleteParams,
   type BrowserPoolAcquireParams,
   type BrowserPoolReleaseParams,
+  type BrowserPoolsOffsetPagination,
 } from './browser-pools';
 export {
   Browsers,

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

@@ -83,6 +83,14 @@ describe('resource browserPools', () => {
     expect(dataAndResponse.response).toBe(rawResponse);
   });
 
+  // Mock server 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.browserPools.list({ limit: 1, offset: 0 }, { path: '/_stainless_unknown_path' }),
+    ).rejects.toThrow(Kernel.NotFoundError);
+  });
+
   // Mock server tests are disabled
   test.skip('delete', async () => {
     const responsePromise = client.browserPools.delete('id_or_name');