feat: add POST /browsers/{id}/curl and /curl/raw endpoints

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 111
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-7d048a0d07483d4fa8d1094f5ec172d1758f044b4e5ced1f41f92f1de8b47def.yml
-openapi_spec_hash: 0ffef6a95f9d9b1096180fc5e4c5b39c
-config_hash: 9818dd634f87b677410eefd013d7a179
+configured_endpoints: 112
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-930823e8b25b4644b74098ad5479840f64a329321aa236460f8a9562ae9051bf.yml
+openapi_spec_hash: 9f868e67df8fd2fec8d8fc3eb5ba0b26
+config_hash: 08d55086449943a8fec212b870061a3f

api.md

@@ -74,6 +74,7 @@ Types:
 - <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>
+- <code><a href="./src/resources/browsers/browsers.ts">BrowserCurlResponse</a></code>
 
 Methods:
 
@@ -82,6 +83,7 @@ Methods:
 - <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="post /browsers/{id}/curl">client.browsers.<a href="./src/resources/browsers/browsers.ts">curl</a>(id, { ...params }) -> BrowserCurlResponse</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

@@ -103,6 +103,8 @@ import { Auth } from './resources/auth/auth';
 import {
   BrowserCreateParams,
   BrowserCreateResponse,
+  BrowserCurlParams,
+  BrowserCurlResponse,
   BrowserDeleteParams,
   BrowserListParams,
   BrowserListResponse,
@@ -1013,12 +1015,14 @@ export declare namespace Kernel {
     type BrowserRetrieveResponse as BrowserRetrieveResponse,
     type BrowserUpdateResponse as BrowserUpdateResponse,
     type BrowserListResponse as BrowserListResponse,
+    type BrowserCurlResponse as BrowserCurlResponse,
     type BrowserListResponsesOffsetPagination as BrowserListResponsesOffsetPagination,
     type BrowserCreateParams as BrowserCreateParams,
     type BrowserRetrieveParams as BrowserRetrieveParams,
     type BrowserUpdateParams as BrowserUpdateParams,
     type BrowserListParams as BrowserListParams,
     type BrowserDeleteParams as BrowserDeleteParams,
+    type BrowserCurlParams as BrowserCurlParams,
     type BrowserLoadExtensionsParams as BrowserLoadExtensionsParams,
   };
 

src/resources/browsers/browsers.ts

@@ -168,6 +168,22 @@ export class Browsers extends APIResource {
     });
   }
 
+  /**
+   * Sends an HTTP request through Chrome's HTTP request stack, inheriting the
+   * browser's TLS fingerprint, cookies, proxy configuration, and headers. Returns a
+   * structured JSON response with status, headers, body, and timing.
+   *
+   * @example
+   * ```ts
+   * const response = await client.browsers.curl('id', {
+   *   url: 'url',
+   * });
+   * ```
+   */
+  curl(id: string, body: BrowserCurlParams, options?: RequestOptions): APIPromise<BrowserCurlResponse> {
+    return this._client.post(path`/browsers/${id}/curl`, { body, ...options });
+  }
+
   /**
    * Delete a browser session by ID
    *
@@ -706,6 +722,31 @@ export interface BrowserListResponse {
   viewport?: Shared.BrowserViewport;
 }
 
+/**
+ * Structured response from the browser curl request.
+ */
+export interface BrowserCurlResponse {
+  /**
+   * Response body (UTF-8 string or base64 depending on request).
+   */
+  body: string;
+
+  /**
+   * Total request duration in milliseconds.
+   */
+  duration_ms: number;
+
+  /**
+   * Response headers (multi-value).
+   */
+  headers: { [key: string]: Array<string> };
+
+  /**
+   * HTTP status code from target.
+   */
+  status: number;
+}
+
 export interface BrowserCreateParams {
   /**
    * List of browser extensions to load into the session. Provide each by id or name.
@@ -859,6 +900,38 @@ export interface BrowserDeleteParams {
   persistent_id: string;
 }
 
+export interface BrowserCurlParams {
+  /**
+   * Target URL (must be http or https).
+   */
+  url: string;
+
+  /**
+   * Request body (for POST/PUT/PATCH).
+   */
+  body?: string;
+
+  /**
+   * Custom headers merged with browser defaults.
+   */
+  headers?: { [key: string]: string };
+
+  /**
+   * HTTP method.
+   */
+  method?: 'GET' | 'HEAD' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS';
+
+  /**
+   * Encoding for the response body. Use base64 for binary content.
+   */
+  response_encoding?: 'utf8' | 'base64';
+
+  /**
+   * Request timeout in milliseconds.
+   */
+  timeout_ms?: number;
+}
+
 export interface BrowserLoadExtensionsParams {
   /**
    * List of extensions to upload and activate
@@ -898,12 +971,14 @@ export declare namespace Browsers {
     type BrowserRetrieveResponse as BrowserRetrieveResponse,
     type BrowserUpdateResponse as BrowserUpdateResponse,
     type BrowserListResponse as BrowserListResponse,
+    type BrowserCurlResponse as BrowserCurlResponse,
     type BrowserListResponsesOffsetPagination as BrowserListResponsesOffsetPagination,
     type BrowserCreateParams as BrowserCreateParams,
     type BrowserRetrieveParams as BrowserRetrieveParams,
     type BrowserUpdateParams as BrowserUpdateParams,
     type BrowserListParams as BrowserListParams,
     type BrowserDeleteParams as BrowserDeleteParams,
+    type BrowserCurlParams as BrowserCurlParams,
     type BrowserLoadExtensionsParams as BrowserLoadExtensionsParams,
   };
 

src/resources/browsers/index.ts

@@ -10,11 +10,13 @@ export {
   type BrowserRetrieveResponse,
   type BrowserUpdateResponse,
   type BrowserListResponse,
+  type BrowserCurlResponse,
   type BrowserCreateParams,
   type BrowserRetrieveParams,
   type BrowserUpdateParams,
   type BrowserListParams,
   type BrowserDeleteParams,
+  type BrowserCurlParams,
   type BrowserLoadExtensionsParams,
   type ProfilesOffsetPagination,
   type BrowserListResponsesOffsetPagination,

src/resources/index.ts

@@ -29,11 +29,13 @@ export {
   type BrowserRetrieveResponse,
   type BrowserUpdateResponse,
   type BrowserListResponse,
+  type BrowserCurlResponse,
   type BrowserCreateParams,
   type BrowserRetrieveParams,
   type BrowserUpdateParams,
   type BrowserListParams,
   type BrowserDeleteParams,
+  type BrowserCurlParams,
   type BrowserLoadExtensionsParams,
   type ProfilesOffsetPagination,
   type BrowserListResponsesOffsetPagination,

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

@@ -133,6 +133,30 @@ describe('resource browsers', () => {
     const response = await client.browsers.delete({ persistent_id: 'persistent_id' });
   });
 
+  // Mock server tests are disabled
+  test.skip('curl: only required params', async () => {
+    const responsePromise = client.browsers.curl('id', { url: 'url' });
+    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);
+  });
+
+  // Mock server tests are disabled
+  test.skip('curl: required and optional params', async () => {
+    const response = await client.browsers.curl('id', {
+      url: 'url',
+      body: 'body',
+      headers: { foo: 'string' },
+      method: 'GET',
+      response_encoding: 'utf8',
+      timeout_ms: 1000,
+    });
+  });
+
   // Mock server tests are disabled
   test.skip('deleteByID', async () => {
     const responsePromise = client.browsers.deleteByID('htzv5orfit78e1m2biiifpbv');