feat: restore node browser fetch helper

Bring back the cache-backed browser fetch helper so raw HTTP stays on the SDK's language-native surface instead of falling through to manual /curl/raw requests.

Made-with: Cursor

Author: rgarcia

examples/browser-routing.ts

@@ -4,18 +4,13 @@ async function main() {
   const kernel = new Kernel({
     browserRouting: {
       enabled: true,
-      subresources: ['computer', 'curl'],
+      subresources: ['computer'],
     },
   });
 
   const browser = await kernel.browsers.create({});
   await kernel.browsers.computer.clickMouse(browser.session_id, { x: 10, y: 10 });
-
-  const response = await kernel
-    .get(`/browsers/${browser.session_id}/curl/raw`, {
-      query: { url: 'https://example.com' },
-    })
-    .asResponse();
+  const response = await kernel.browsers.fetch(browser.session_id, 'https://example.com', { method: 'GET' });
   console.log('status', response.status);
 
   await kernel.browsers.deleteByID(browser.session_id);

src/index.ts

@@ -7,6 +7,7 @@ export { APIPromise } from './core/api-promise';
 export { Kernel, type ClientOptions } from './client';
 export {
   BrowserRouteCache,
+  type BrowserFetchInit,
   type BrowserRoute,
   type BrowserRoutingOptions,
 } from './lib/browser-routing';

src/lib/browser-routing.ts

@@ -1,5 +1,10 @@
-import type { Fetch } from '../internal/builtin-types';
+import type { RequestInfo, RequestInit, Fetch } from '../internal/builtin-types';
+import { KernelError } from '../core/error';
+import { buildHeaders } from '../internal/headers';
+import type { FinalRequestOptions, RequestOptions } from '../internal/request-options';
+import type { HTTPMethod } from '../internal/types';
 import { parseJwtFromCdpWsUrl } from './browser-transport';
+import type { Kernel } from '../client';
 
 export type BrowserRoute = {
   sessionId: string;
@@ -13,6 +18,10 @@ export interface BrowserRoutingOptions {
   cache?: BrowserRouteCache | undefined;
 }
 
+export interface BrowserFetchInit extends RequestInit {
+  timeout_ms?: number;
+}
+
 export class BrowserRouteCache {
   private entries = new Map<string, BrowserRoute>();
 
@@ -60,6 +69,51 @@ export function createRoutingFetch(
   };
 }
 
+export async function browserFetch(
+  client: Kernel,
+  sessionId: string,
+  input: RequestInfo | URL,
+  init?: BrowserFetchInit,
+): Promise<Response> {
+  const route = client.browserRouteCache.get(sessionId);
+  if (!route) {
+    throw new KernelError(
+      `browser route cache does not contain session ${sessionId}; create, retrieve, or list the browser before calling browser.fetch`,
+    );
+  }
+
+  const { url: targetURL, method, headers, body, signal, duplex, timeout_ms } = splitFetchArgs(input, init);
+  assertHTTPURL(targetURL);
+
+  const query: Record<string, unknown> = {
+    url: targetURL,
+    jwt: route.jwt,
+  };
+  if (timeout_ms !== undefined) {
+    query['timeout_ms'] = timeout_ms;
+  }
+
+  const accept = headers.get('accept');
+  const requestOptions: FinalRequestOptions = {
+    method: normalizeMethod(method),
+    path: joinURL(route.baseURL, '/curl/raw'),
+    query,
+    body: body as RequestOptions['body'],
+    headers: buildHeaders([
+      { Authorization: null },
+      accept ? { Accept: accept } : { Accept: '*/*' },
+      headersToRequestOptionsHeaders(headers),
+    ]),
+    signal: signal ?? null,
+    __binaryResponse: true,
+  };
+  if (duplex) {
+    requestOptions.fetchOptions = { duplex } as NonNullable<RequestOptions['fetchOptions']>;
+  }
+
+  return client.request(requestOptions).asResponse();
+}
+
 function browserRouteFromValue(value: unknown): BrowserRoute | undefined {
   if (!value || typeof value !== 'object') {
     return undefined;
@@ -180,3 +234,126 @@ function joinURL(baseURL: string, path: string): string {
   return `${baseURL.replace(/\/+$/, '')}${path.startsWith('/') ? path : `/${path}`}`;
 }
 
+function normalizeMethod(method: string): HTTPMethod {
+  const methodLower = method.toLowerCase();
+  const allowed = new Set(['get', 'post', 'put', 'patch', 'delete', 'head', 'options']);
+  if (!allowed.has(methodLower)) {
+    throw new KernelError(`browser.fetch unsupported HTTP method: ${method}`);
+  }
+  return methodLower as HTTPMethod;
+}
+
+function splitFetchArgs(
+  input: RequestInfo | URL,
+  init?: BrowserFetchInit,
+): {
+  url: string;
+  method: string;
+  headers: Headers;
+  body?: RequestInit['body'];
+  signal?: AbortSignal | null;
+  duplex?: RequestInit['duplex'];
+  timeout_ms?: number;
+} {
+  const timeoutFromInit = init && 'timeout_ms' in init ? init['timeout_ms'] : undefined;
+
+  if (input instanceof Request) {
+    const merged = new Headers(input.headers);
+    if (init?.headers) {
+      const extra = new Headers(init.headers);
+      extra.forEach((value, key) => {
+        merged.set(key, value);
+      });
+    }
+    const out: {
+      url: string;
+      method: string;
+      headers: Headers;
+      body?: RequestInit['body'];
+      signal?: AbortSignal | null;
+      duplex?: RequestInit['duplex'];
+      timeout_ms?: number;
+    } = {
+      url: input.url,
+      method: (init?.method ?? input.method)?.toUpperCase() || 'GET',
+      headers: merged,
+    };
+    const mergedBody = init?.body ?? input.body;
+    if (mergedBody !== undefined && mergedBody !== null) {
+      out.body = mergedBody;
+    }
+    const mergedSignal = init?.signal ?? input.signal;
+    if (mergedSignal !== undefined) {
+      out.signal = mergedSignal;
+    }
+    if (init?.duplex !== undefined) {
+      out.duplex = init.duplex;
+    }
+    if (timeoutFromInit !== undefined) {
+      out.timeout_ms = timeoutFromInit;
+    }
+    return out;
+  }
+
+  const url = input instanceof URL ? input.href : String(input);
+  const method = (init?.method ?? 'GET').toUpperCase();
+  const headers = new Headers(init?.headers);
+  const out: {
+    url: string;
+    method: string;
+    headers: Headers;
+    body?: RequestInit['body'];
+    signal?: AbortSignal | null;
+    duplex?: RequestInit['duplex'];
+    timeout_ms?: number;
+  } = { url, method, headers };
+  if (init?.body !== undefined) {
+    out.body = init.body;
+  }
+  if (init?.signal !== undefined) {
+    out.signal = init.signal;
+  }
+  if (init?.duplex !== undefined) {
+    out.duplex = init.duplex;
+  }
+  if (timeoutFromInit !== undefined) {
+    out.timeout_ms = timeoutFromInit;
+  }
+  return out;
+}
+
+function assertHTTPURL(url: string): void {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new KernelError(`browser.fetch target must be an absolute URL; received: ${url}`);
+  }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    throw new KernelError(`browser.fetch only supports http(s) URLs; received: ${parsed.protocol}`);
+  }
+}
+
+function headersToRequestOptionsHeaders(headers: Headers): Record<string, string | null | undefined> {
+  const out: Record<string, string | null | undefined> = {};
+  headers.forEach((value, key) => {
+    const lower = key.toLowerCase();
+    if (
+      lower === 'accept' ||
+      lower === 'content-length' ||
+      lower === 'connection' ||
+      lower === 'keep-alive' ||
+      lower === 'proxy-authenticate' ||
+      lower === 'proxy-authorization' ||
+      lower === 'te' ||
+      lower === 'trailers' ||
+      lower === 'transfer-encoding' ||
+      lower === 'upgrade'
+    ) {
+      return;
+    }
+    out[key] = value;
+  });
+  return out;
+}
+

src/resources/browsers/browsers.ts

@@ -1,5 +1,6 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+import type { RequestInfo } from '../../internal/builtin-types';
 import { APIResource } from '../../core/resource';
 import * as Shared from '../shared';
 import * as ComputerAPI from './computer';
@@ -75,6 +76,7 @@ import { buildHeaders } from '../../internal/headers';
 import { RequestOptions } from '../../internal/request-options';
 import { multipartFormRequestOptions } from '../../internal/uploads';
 import { path } from '../../internal/utils/path';
+import { browserFetch, type BrowserFetchInit } from '../../lib/browser-routing';
 
 /**
  * Create and manage browser sessions.
@@ -184,6 +186,14 @@ export class Browsers extends APIResource {
     return this._client.post(path`/browsers/${id}/curl`, { body, ...options });
   }
 
+  /**
+   * Issues an HTTP request through the browser VM network stack, routing directly
+   * to the browser's `base_url` using the shared browser route cache.
+   */
+  fetch(id: string, input: RequestInfo | URL, init?: BrowserFetchInit): Promise<Response> {
+    return browserFetch(this._client, id, input, init);
+  }
+
   /**
    * Delete a browser session by ID
    *

tests/lib/browser-routing.test.ts

@@ -127,4 +127,28 @@ describe('browser routing', () => {
     await kernel.browsers.create();
     expect(kernel.browserRouteCache.get('sess-1')).toBeUndefined();
   });
+
+  test('browser.fetch uses the shared cache and fails clearly on cache miss', async () => {
+    const calls: string[] = [];
+    const kernel = new Kernel({
+      apiKey: 'k',
+      baseURL: 'https://api.example/',
+      fetch: async (input) => {
+        const url = normalizeURL(input);
+        calls.push(url);
+        return new Response('ok', { status: 200, headers: { 'content-type': 'text/plain' } });
+      },
+    });
+
+    kernel.browserRouteCache.set({
+      sessionId: 'sess-1',
+      baseURL: 'http://browser-session.test/browser/kernel',
+      jwt: 'token-abc',
+    });
+    await kernel.browsers.fetch('sess-1', 'https://example.com/hello');
+    expect(calls[0]).toContain('http://browser-session.test/browser/kernel/curl/raw?');
+
+    kernel.browserRouteCache.delete('sess-1');
+    await expect(kernel.browsers.fetch('sess-1', 'https://example.com/again')).rejects.toThrow(/route cache/);
+  });
 });