@onkernel/sdk 0.49.0 → 0.51.0

package/src/client.ts

@@ -20,6 +20,11 @@ import * as Uploads from './core/uploads';
 import * as API from './resources/index';
 import { APIPromise } from './core/api-promise';
 import { AppListParams, AppListResponse, AppListResponsesOffsetPagination, Apps } from './resources/apps';
+import {
+  BrowserRouteCache,
+  browserRoutingSubresourcesFromEnv,
+  createRoutingFetch,
+} from './lib/browser-routing';
 import {
   BrowserPool,
   BrowserPoolAcquireParams,
@@ -103,6 +108,8 @@ import { Auth } from './resources/auth/auth';
 import {
   BrowserCreateParams,
   BrowserCreateResponse,
+  BrowserCurlParams,
+  BrowserCurlResponse,
   BrowserDeleteParams,
   BrowserListParams,
   BrowserListResponse,
@@ -245,9 +252,11 @@ export class Kernel {
   fetchOptions: MergedRequestInit | undefined;
 
   private fetch: Fetch;
+  private rawFetch: Fetch;
   #encoder: Opts.RequestEncoder;
   protected idempotencyHeader?: string;
   private _options: ClientOptions;
+  public browserRouteCache: BrowserRouteCache;
 
   /**
    * API Client for interfacing with the Kernel API.
@@ -310,7 +319,13 @@ export class Kernel {
       defaultLogLevel;
     this.fetchOptions = options.fetchOptions;
     this.maxRetries = options.maxRetries ?? 2;
-    this.fetch = options.fetch ?? Shims.getDefaultFetch();
+    this.rawFetch = options.fetch ?? Shims.getDefaultFetch();
+    this.browserRouteCache = new BrowserRouteCache();
+    this.fetch = createRoutingFetch(this.rawFetch, {
+      apiBaseURL: this.baseURL,
+      subresources: browserRoutingSubresourcesFromEnv(),
+      cache: this.browserRouteCache,
+    });
     this.#encoder = Opts.FallbackEncoder;
 
     this._options = options;
@@ -330,11 +345,17 @@ export class Kernel {
       timeout: this.timeout,
       logger: this.logger,
       logLevel: this.logLevel,
-      fetch: this.fetch,
+      fetch: this.rawFetch,
       fetchOptions: this.fetchOptions,
       apiKey: this.apiKey,
       ...options,
     });
+    client.browserRouteCache = this.browserRouteCache;
+    client.fetch = createRoutingFetch(client.rawFetch, {
+      apiBaseURL: client.baseURL,
+      subresources: browserRoutingSubresourcesFromEnv(),
+      cache: client.browserRouteCache,
+    });
     return client;
   }
 
@@ -1013,12 +1034,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,
   };
 

package/src/index.ts

@@ -5,6 +5,8 @@ export { Kernel as default } from './client';
 export { type Uploadable, toFile } from './core/uploads';
 export { APIPromise } from './core/api-promise';
 export { Kernel, type ClientOptions } from './client';
+export { type BrowserFetchInit } from './lib/browser-fetch';
+export { BrowserRouteCache, type BrowserRoute } from './lib/browser-routing';
 export { PagePromise } from './core/pagination';
 export {
   KernelError,

package/src/lib/browser-fetch.ts

@@ -0,0 +1,180 @@
+import type { RequestInfo, RequestInit } 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 { joinURL } from './join-url';
+import type { Kernel } from '../client';
+
+export interface BrowserFetchInit extends RequestInit {
+  timeout_ms?: number;
+}
+
+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 normalizeMethod(method: string): HTTPMethod {
+  const methodLower = method.toLowerCase();
+  const allowed = new Set(['get', 'post', 'put', 'patch', 'delete']);
+  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 headers = new Headers(input.headers);
+    if (init?.headers) {
+      const extra = new Headers(init.headers);
+      extra.forEach((value, key) => {
+        headers.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,
+    };
+    const body = init?.body ?? input.body;
+    if (body !== undefined && body !== null) {
+      out.body = body;
+    }
+    const signal = init?.signal ?? input.signal;
+    if (signal !== undefined) {
+      out.signal = signal;
+    }
+    if (init?.duplex !== undefined) {
+      out.duplex = init.duplex;
+    }
+    if (timeoutFromInit !== undefined) {
+      out.timeout_ms = timeoutFromInit;
+    }
+    return out;
+  }
+
+  const out: {
+    url: string;
+    method: string;
+    headers: Headers;
+    body?: RequestInit['body'];
+    signal?: AbortSignal | null;
+    duplex?: RequestInit['duplex'];
+    timeout_ms?: number;
+  } = {
+    url: input instanceof URL ? input.href : String(input),
+    method: (init?.method ?? 'GET').toUpperCase(),
+    headers: new Headers(init?.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) => {
+    switch (key.toLowerCase()) {
+      case 'accept':
+      case 'content-length':
+      case 'connection':
+      case 'keep-alive':
+      case 'proxy-authenticate':
+      case 'proxy-authorization':
+      case 'te':
+      case 'trailers':
+      case 'transfer-encoding':
+      case 'upgrade':
+        return;
+      default:
+        out[key] = value;
+    }
+  });
+
+  return out;
+}

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)