@onkernel/sdk 0.49.0 → 0.52.0

package/src/lib/browser-routing.ts

@@ -0,0 +1,329 @@
+import type { Fetch, RequestInfo, RequestInit } from '../internal/builtin-types';
+import { joinURL } from './join-url';
+
+export type BrowserRoute = {
+  sessionId: string;
+  baseURL: string;
+  jwt: string;
+};
+
+export class BrowserRouteCache {
+  private entries = new Map<string, BrowserRoute>();
+
+  get(sessionId: string): BrowserRoute | undefined {
+    return this.entries.get(sessionId);
+  }
+
+  set(route: BrowserRoute): void {
+    this.entries.set(route.sessionId, route);
+  }
+
+  delete(sessionId: string): void {
+    this.entries.delete(sessionId);
+  }
+
+  clear(): void {
+    this.entries.clear();
+  }
+}
+
+const BROWSER_ROUTING_SUBRESOURCES_ENV = 'KERNEL_BROWSER_ROUTING_SUBRESOURCES';
+const DEFAULT_BROWSER_ROUTING_SUBRESOURCES = ['curl'];
+const BROWSER_ROUTE_CACHEABLE_PATH = /^\/(?:v\d+\/)?browsers(?:\/[^/]+)?\/?$/;
+const BROWSER_POOL_ACQUIRE_PATH = /^\/(?:v\d+\/)?browser_pools\/[^/]+\/acquire\/?$/;
+const BROWSER_DELETE_BY_ID_PATH = /^\/(?:v\d+\/)?browsers\/([^/]+)\/?$/;
+const BROWSER_POOL_RELEASE_PATH = /^\/(?:v\d+\/)?browser_pools\/[^/]+\/release\/?$/;
+
+export function browserRoutingSubresourcesFromEnv(): string[] {
+  const raw = readBrowserRoutingSubresourcesEnv();
+  if (raw === undefined) {
+    return [...DEFAULT_BROWSER_ROUTING_SUBRESOURCES];
+  }
+
+  if (raw.trim() === '') {
+    return [];
+  }
+
+  return raw
+    .split(',')
+    .map((value) => value.trim())
+    .filter(Boolean);
+}
+
+export function createRoutingFetch(
+  innerFetch: Fetch,
+  {
+    apiBaseURL,
+    subresources,
+    cache,
+  }: {
+    apiBaseURL: string;
+    subresources: Iterable<string>;
+    cache: BrowserRouteCache;
+  },
+): Fetch {
+  const allowed = new Set([...subresources].map((value) => value.trim()).filter(Boolean));
+  const apiOrigin = new URL(apiBaseURL).origin;
+
+  return async (input, init) => {
+    const request = new Request(input, init);
+    const shouldSniff = shouldSniffAndPopulateCache(request, apiOrigin);
+    const response = await routeRequest(innerFetch, { input, init, request }, apiOrigin, allowed, cache);
+    if (shouldSniff) {
+      await sniffAndPopulateCache(response, cache);
+    }
+    await maybeEvictBrowserRoute(request, response, apiOrigin, cache);
+    return response;
+  };
+}
+
+function shouldSniffAndPopulateCache(request: Request, apiOrigin: string): boolean {
+  const url = new URL(request.url);
+  return (
+    url.origin === apiOrigin &&
+    (BROWSER_ROUTE_CACHEABLE_PATH.test(url.pathname) || BROWSER_POOL_ACQUIRE_PATH.test(url.pathname))
+  );
+}
+
+async function maybeEvictBrowserRoute(
+  request: Request,
+  response: Response,
+  apiOrigin: string,
+  cache: BrowserRouteCache,
+): Promise<void> {
+  if (!response.ok) {
+    return;
+  }
+
+  const url = new URL(request.url);
+  if (url.origin !== apiOrigin) {
+    return;
+  }
+
+  const sessionId =
+    deletedSessionIdFromPath(request, url.pathname) ??
+    (await releasedSessionIdFromRequest(request, url.pathname));
+  if (sessionId) {
+    cache.delete(sessionId);
+  }
+}
+
+function deletedSessionIdFromPath(request: Request, pathname: string): string | undefined {
+  if (request.method.toUpperCase() !== 'DELETE') {
+    return undefined;
+  }
+
+  const match = pathname.match(BROWSER_DELETE_BY_ID_PATH);
+  if (!match) {
+    return undefined;
+  }
+
+  const sessionId = decodeURIComponent(match[1] ?? '');
+  return sessionId || undefined;
+}
+
+async function releasedSessionIdFromRequest(request: Request, pathname: string): Promise<string | undefined> {
+  if (request.method.toUpperCase() !== 'POST' || !BROWSER_POOL_RELEASE_PATH.test(pathname)) {
+    return undefined;
+  }
+
+  try {
+    const body = await request.clone().json();
+    if (!body || typeof body !== 'object') {
+      return undefined;
+    }
+
+    const sessionId = (body as Record<string, unknown>)['session_id'];
+    return typeof sessionId === 'string' && sessionId.trim() ? sessionId.trim() : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function browserRouteFromValue(value: unknown): BrowserRoute | undefined {
+  if (!value || typeof value !== 'object') {
+    return undefined;
+  }
+
+  const record = value as Record<string, unknown>;
+  const sessionId = typeof record['session_id'] === 'string' ? record['session_id'].trim() : '';
+  const baseURL = typeof record['base_url'] === 'string' ? record['base_url'].trim() : '';
+  if (!sessionId || !baseURL) {
+    return undefined;
+  }
+
+  const explicitJWT = typeof record['jwt'] === 'string' ? record['jwt'].trim() : '';
+  const cdpWsURL = typeof record['cdp_ws_url'] === 'string' ? record['cdp_ws_url'] : undefined;
+  const jwt = explicitJWT || parseJwtFromCdpWsUrl(cdpWsURL) || '';
+  if (!jwt) {
+    return undefined;
+  }
+  return {
+    sessionId,
+    baseURL,
+    jwt,
+  };
+}
+
+async function sniffAndPopulateCache(response: Response, cache: BrowserRouteCache): Promise<void> {
+  const contentType = response.headers.get('content-type')?.toLowerCase() ?? '';
+  if (!contentType.includes('application/json')) {
+    return;
+  }
+
+  try {
+    populateCache(await response.clone().json(), cache);
+  } catch {
+    // Ignore malformed JSON in routing cache population.
+  }
+}
+
+function populateCache(value: unknown, cache: BrowserRouteCache): void {
+  const route = browserRouteFromValue(value);
+  if (route) {
+    cache.set(route);
+  }
+
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      populateCache(item, cache);
+    }
+    return;
+  }
+
+  if (!value || typeof value !== 'object') {
+    return;
+  }
+
+  for (const child of Object.values(value as Record<string, unknown>)) {
+    if (typeof child === 'object' && child !== null) {
+      populateCache(child, cache);
+    }
+  }
+}
+
+async function routeRequest(
+  innerFetch: Fetch,
+  {
+    input,
+    init,
+    request,
+  }: {
+    input: RequestInfo;
+    init: RequestInit | undefined;
+    request: Request;
+  },
+  apiOrigin: string,
+  allowed: ReadonlySet<string>,
+  cache: BrowserRouteCache,
+): Promise<Response> {
+  const url = new URL(request.url);
+  if (url.origin !== apiOrigin) {
+    return innerFetch(input, init);
+  }
+
+  const match = url.pathname.match(/^\/(?:v\d+\/)?browsers\/([^/]+)\/([^/]+)(\/.*)?$/);
+  if (!match) {
+    return innerFetch(input, init);
+  }
+
+  const sessionId = decodeURIComponent(match[1] ?? '');
+  const subresource = match[2] ?? '';
+  if (!sessionId || !allowed.has(subresource)) {
+    return innerFetch(input, init);
+  }
+  const route = cache.get(sessionId);
+  if (route === undefined) {
+    return innerFetch(input, init);
+  }
+
+  const target = new URL(joinURL(route.baseURL, `/${subresource}${match[3] ?? ''}`));
+  url.searchParams.forEach((value, key) => {
+    if (key !== 'jwt') {
+      target.searchParams.append(key, value);
+    }
+  });
+  if (!target.searchParams.get('jwt')) {
+    target.searchParams.set('jwt', route.jwt);
+  }
+
+  const headers = new Headers(request.headers);
+  headers.delete('authorization');
+  return innerFetch(target.toString(), buildRoutedInit(request, init, headers));
+}
+
+function buildRoutedInit(
+  request: Request,
+  originalInit: RequestInit | undefined,
+  headers: Headers,
+): RequestInit {
+  const method = request.method.toUpperCase();
+  const routedInit = {
+    ...((originalInit ?? {}) as Record<string, unknown>),
+    method,
+    headers,
+    redirect: request.redirect,
+    signal: request.signal,
+  } as RequestInit & Record<string, unknown>;
+
+  delete routedInit['body'];
+  delete routedInit['duplex'];
+
+  if (method !== 'GET' && method !== 'HEAD') {
+    const body = requestBodyForFetch(request, originalInit);
+    if (body !== undefined) {
+      routedInit.body = body;
+    }
+    if (originalInit?.duplex !== undefined) {
+      routedInit.duplex = originalInit.duplex;
+    } else if (requiresHalfDuplex(body)) {
+      routedInit.duplex = 'half';
+    }
+  }
+
+  return routedInit;
+}
+
+function requestBodyForFetch(
+  request: Request,
+  originalInit: RequestInit | undefined,
+): RequestInit['body'] | undefined {
+  if (originalInit?.body !== undefined && originalInit.body !== null) {
+    return originalInit.body;
+  }
+
+  return request.body ?? undefined;
+}
+
+function requiresHalfDuplex(body: RequestInit['body'] | undefined): boolean {
+  return (
+    ((globalThis as any).ReadableStream && body instanceof (globalThis as any).ReadableStream) ||
+    (typeof body === 'object' && body !== null && Symbol.asyncIterator in body)
+  );
+}
+
+function parseJwtFromCdpWsUrl(cdpWsUrl: string | undefined): string | undefined {
+  if (!cdpWsUrl) {
+    return undefined;
+  }
+
+  try {
+    return new URL(cdpWsUrl).searchParams.get('jwt') ?? undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function readBrowserRoutingSubresourcesEnv(): string | undefined {
+  if (typeof (globalThis as any).process !== 'undefined') {
+    const value = (globalThis as any).process.env?.[BROWSER_ROUTING_SUBRESOURCES_ENV];
+    return typeof value === 'string' ? value : undefined;
+  }
+
+  if (typeof (globalThis as any).Deno !== 'undefined') {
+    const value = (globalThis as any).Deno.env?.get?.(BROWSER_ROUTING_SUBRESOURCES_ENV);
+    return typeof value === 'string' ? value : undefined;
+  }
+
+  return undefined;
+}

package/src/lib/join-url.ts

@@ -0,0 +1,3 @@
+export function joinURL(baseURL: string, path: string): string {
+  return `${baseURL.replace(/\/+$/, '')}${path.startsWith('/') ? path : `/${path}`}`;
+}

package/src/resources/auth/connections.ts

@@ -244,6 +244,13 @@ export interface ManagedAuth {
    */
   allowed_domains?: Array<string>;
 
+  /**
+   * ID of the underlying browser session driving the current flow (present when flow
+   * in progress). Use this to inspect or terminate the browser session via the
+   * `/browsers` API.
+   */
+  browser_session_id?: string | null;
+
   /**
    * Whether automatic re-authentication is possible (has credential, selectors, and
    * login_url)
@@ -286,7 +293,10 @@ export interface ManagedAuth {
   external_action_message?: string | null;
 
   /**
-   * When the current flow expires (null when no flow in progress)
+   * When the current flow expires (null when no flow in progress). A flow past this
+   * timestamp is no longer valid and its `flow_status` will be `EXPIRED`. Clients
+   * may start a new login to supersede a stale `IN_PROGRESS` flow past this
+   * timestamp.
    */
   flow_expires_at?: string | null;
 
@@ -326,10 +336,21 @@ export interface ManagedAuth {
   hosted_url?: string | null;
 
   /**
-   * When the profile was last successfully authenticated
+   * @deprecated Deprecated alias for `last_auth_check_at`. Despite the name, this is
+   * the last health-check timestamp, not the last successful authentication. Use
+   * `last_auth_check_at` instead.
    */
   last_auth_at?: string;
 
+  /**
+   * When the most recent auth health check ran for this connection, regardless of
+   * outcome. Updated on every health check and does not by itself indicate that the
+   * profile is currently authenticated - use `status` for that. May be newer than
+   * `flow_expires_at` when a flow is still in progress because health checks
+   * continue to run in parallel.
+   */
+  last_auth_check_at?: string;
+
   /**
    * Browser live view URL for debugging (present when flow in progress)
    */
@@ -433,6 +454,12 @@ export namespace ManagedAuth {
      */
     type: 'text' | 'email' | 'password' | 'tel' | 'number' | 'url' | 'code' | 'totp';
 
+    /**
+     * Contextual help text near the field that tells the user what to enter (e.g.,
+     * "Enter the phone ending in (**_) _**-\*\*92")
+     */
+    hint?: string;
+
     /**
      * If this field is associated with an MFA option, the type of that option (e.g.,
      * password field linked to "Enter password" option)
@@ -890,6 +917,12 @@ export namespace ConnectionFollowResponse {
        */
       type: 'text' | 'email' | 'password' | 'tel' | 'number' | 'url' | 'code' | 'totp';
 
+      /**
+       * Contextual help text near the field that tells the user what to enter (e.g.,
+       * "Enter the phone ending in (**_) _**-\*\*92")
+       */
+      hint?: string;
+
       /**
        * If this field is associated with an MFA option, the type of that option (e.g.,
        * password field linked to "Enter password" option)

package/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-fetch';
 
 /**
  * Create and manage browser sessions.
@@ -168,6 +170,30 @@ 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 });
+  }
+
+  /**
+   * 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
    *
@@ -706,6 +732,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 +910,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 +981,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,
   };
 

package/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,

package/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,

package/src/resources/profiles.ts

@@ -49,8 +49,7 @@ export class Profiles extends APIResource {
   }
 
   /**
-   * Download the profile. Profiles are JSON files containing the pieces of state
-   * that we save.
+   * Returns a zstd-compressed tar file of the full user-data directory.
    */
   download(idOrName: string, options?: RequestOptions): APIPromise<Response> {
     return this._client.get(path`/profiles/${idOrName}/download`, {

package/src/resources/projects/projects.ts

@@ -16,8 +16,8 @@ export class Projects extends APIResource {
   limits: LimitsAPI.Limits = new LimitsAPI.Limits(this._client);
 
   /**
-   * Create a new project within the authenticated organization. Requires a paid plan
-   * and the projects feature flag.
+   * Create a new project within the authenticated organization. Requires the
+   * projects feature flag.
    *
    * @example
    * ```ts

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.49.0'; // x-release-please-version
+export const VERSION = '0.52.0'; // x-release-please-version

package/version.d.mts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.49.0";
+export declare const VERSION = "0.52.0";
 //# sourceMappingURL=version.d.mts.map

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.49.0";
+export declare const VERSION = "0.52.0";
 //# sourceMappingURL=version.d.ts.map

package/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = '0.49.0'; // x-release-please-version
+exports.VERSION = '0.52.0'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

@@ -1,2 +1,2 @@
-export const VERSION = '0.49.0'; // x-release-please-version
+export const VERSION = '0.52.0'; // x-release-please-version
 //# sourceMappingURL=version.mjs.map