@browserbasehq/convex-stagehand 0.0.3 → 0.1.0

package/src/component/api.ts

@@ -2,9 +2,33 @@
  * Stagehand REST API Client
  *
  * Wraps the Stagehand API at https://api.stagehand.browserbase.com
+ * Wire format matches the OpenAPI spec defined in stagehand/packages/core/lib/v3/types/public/api.ts
  */
 
-const API_BASE = "https://api.stagehand.browserbase.com/v1";
+export type BrowserbaseRegion =
+  | "us-west-2"
+  | "us-east-1"
+  | "eu-central-1"
+  | "ap-southeast-1";
+
+export interface BrowserbaseSessionCreateParams {
+  region?: BrowserbaseRegion;
+}
+
+/** Multi-region API URL mapping (matches official SDK) */
+const REGION_API_URLS: Record<BrowserbaseRegion, string> = {
+  "us-west-2": "https://api.stagehand.browserbase.com",
+  "us-east-1": "https://api.use1.stagehand.browserbase.com",
+  "eu-central-1": "https://api.euc1.stagehand.browserbase.com",
+  "ap-southeast-1": "https://api.apse1.stagehand.browserbase.com",
+};
+
+export function getApiBase(region?: BrowserbaseRegion): string {
+  const baseUrl =
+    (region && REGION_API_URLS[region]) ||
+    REGION_API_URLS["us-west-2"];
+  return `${baseUrl}/v1`;
+}
 
 export interface ApiConfig {
   browserbaseApiKey: string;
@@ -13,19 +37,22 @@ export interface ApiConfig {
   modelName?: string;
 }
 
+/** Matches SessionStartResult from the OpenAPI spec */
 export interface SessionData {
   sessionId: string;
-  browserbaseSessionId?: string;
-  cdpUrl?: string;
+  cdpUrl?: string | null;
   available: boolean;
 }
 
 export interface StartSessionOptions {
-  browserbaseSessionId?: string;
-  browserbaseSessionCreateParams?: Record<string, unknown>;
+  browserbaseSessionID?: string;
+  browserbaseSessionCreateParams?: BrowserbaseSessionCreateParams;
+  model?: unknown;
   domSettleTimeoutMs?: number;
   selfHeal?: boolean;
   systemPrompt?: string;
+  verbose?: 0 | 1 | 2;
+  experimental?: boolean;
 }
 
 export interface ApiResponse<T> {
@@ -56,86 +83,135 @@ async function handleResponse<T>(response: Response): Promise<T> {
   return json.data;
 }
 
+/** POST /v1/sessions/start — matches SessionStartRequest schema */
 export async function startSession(
   config: ApiConfig,
   options?: StartSessionOptions,
 ): Promise<SessionData> {
-  const response = await fetch(`${API_BASE}/sessions/start`, {
-    method: "POST",
-    headers: getHeaders(config),
-    body: JSON.stringify({
-      modelName: config.modelName || "openai/gpt-4o",
-      browserbaseSessionId: options?.browserbaseSessionId,
-      browserbaseSessionCreateParams: options?.browserbaseSessionCreateParams,
-      domSettleTimeoutMs: options?.domSettleTimeoutMs,
-      selfHeal: options?.selfHeal,
-      systemPrompt: options?.systemPrompt,
-    }),
-  });
+  const region = options?.browserbaseSessionCreateParams?.region;
+  const response = await fetch(
+    `${getApiBase(region)}/sessions/start`,
+    {
+      method: "POST",
+      headers: getHeaders(config),
+      body: JSON.stringify({
+        modelName: config.modelName || "openai/gpt-4o",
+        model: options?.model,
+        browserbaseSessionID: options?.browserbaseSessionID,
+        browserbaseSessionCreateParams:
+          options?.browserbaseSessionCreateParams,
+        domSettleTimeoutMs: options?.domSettleTimeoutMs,
+        selfHeal: options?.selfHeal,
+        systemPrompt: options?.systemPrompt,
+        verbose: options?.verbose,
+        experimental: options?.experimental,
+      }),
+    },
+  );
   return handleResponse<SessionData>(response);
 }
 
+/** POST /v1/sessions/{id}/end */
 export async function endSession(
   sessionId: string,
   config: ApiConfig,
+  region?: BrowserbaseRegion,
 ): Promise<void> {
-  try {
-    await fetch(`${API_BASE}/sessions/${sessionId}/end`, {
-      method: "POST",
-      headers: getHeaders(config),
-    });
-  } catch {
-    // Ignore errors when ending session - best effort cleanup
+  const response = await fetch(`${getApiBase(region)}/sessions/${sessionId}/end`, {
+    method: "POST",
+    headers: getHeaders(config),
+  });
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`Stagehand API error (${response.status}): ${errorText}`);
+  }
+  const text = await response.text();
+  if (text) {
+    const json = JSON.parse(text) as { success?: boolean };
+    if (json.success === false) {
+      throw new Error("Stagehand API returned success: false");
+    }
   }
 }
 
+/** Matches NavigateOptions from the OpenAPI spec */
 export interface NavigateOptions {
   waitUntil?: "load" | "domcontentloaded" | "networkidle";
   timeout?: number;
+  referer?: string;
 }
 
+/** POST /v1/sessions/{id}/navigate — matches NavigateRequest schema */
 export async function navigate(
   sessionId: string,
   url: string,
   config: ApiConfig,
   options?: NavigateOptions,
+  region?: BrowserbaseRegion,
 ): Promise<void> {
-  const response = await fetch(`${API_BASE}/sessions/${sessionId}/navigate`, {
-    method: "POST",
-    headers: getHeaders(config),
-    body: JSON.stringify({
-      url,
-      options: {
-        waitUntil: options?.waitUntil || "networkidle",
-        timeout: options?.timeout,
-      },
-    }),
-  });
+  const response = await fetch(
+    `${getApiBase(region)}/sessions/${sessionId}/navigate`,
+    {
+      method: "POST",
+      headers: getHeaders(config),
+      body: JSON.stringify({
+        url,
+        options: {
+          waitUntil: options?.waitUntil || "networkidle",
+          timeout: options?.timeout,
+          referer: options?.referer,
+        },
+      }),
+    },
+  );
   await handleResponse(response);
 }
 
-export interface ExtractResult<T = any> {
+export interface ExtractResult<T = unknown> {
   result: T;
-  actionId: string;
+  actionId?: string;
+}
+
+/** Matches ExtractOptions from the OpenAPI spec */
+export interface ExtractOperationOptions {
+  model?: unknown;
+  timeout?: number;
+  selector?: string;
 }
 
+/** POST /v1/sessions/{id}/extract — matches ExtractRequest schema */
 export async function extract(
   sessionId: string,
   instruction: string,
-  schema: any,
+  schema: unknown,
   config: ApiConfig,
+  operationOptions?: ExtractOperationOptions,
+  region?: BrowserbaseRegion,
 ): Promise<ExtractResult> {
-  const response = await fetch(`${API_BASE}/sessions/${sessionId}/extract`, {
-    method: "POST",
-    headers: getHeaders(config),
-    body: JSON.stringify({
-      instruction,
-      schema,
-    }),
-  });
+  const body: Record<string, unknown> = { instruction, schema };
+  if (
+    operationOptions?.model != null ||
+    operationOptions?.timeout != null ||
+    operationOptions?.selector != null
+  ) {
+    body.options = {
+      model: operationOptions?.model,
+      timeout: operationOptions?.timeout,
+      selector: operationOptions?.selector,
+    };
+  }
+  const response = await fetch(
+    `${getApiBase(region)}/sessions/${sessionId}/extract`,
+    {
+      method: "POST",
+      headers: getHeaders(config),
+      body: JSON.stringify(body),
+    },
+  );
   return handleResponse<ExtractResult>(response);
 }
 
+/** Matches ActResultData from the OpenAPI spec */
 export interface ActResult {
   result: {
     actionDescription: string;
@@ -143,101 +219,182 @@ export interface ActResult {
       description: string;
       selector: string;
       arguments?: string[];
-      method: string;
+      method?: string;
+      backendNodeId?: number;
     }>;
     message: string;
     success: boolean;
   };
-  actionId: string;
+  actionId?: string;
 }
 
+/** Matches ActOptions from the OpenAPI spec */
+export interface ActOperationOptions {
+  model?: unknown;
+  variables?: Record<string, string>;
+  timeout?: number;
+}
+
+/** POST /v1/sessions/{id}/act — matches ActRequest schema */
 export async function act(
   sessionId: string,
   action: string,
   config: ApiConfig,
+  operationOptions?: ActOperationOptions,
+  region?: BrowserbaseRegion,
 ): Promise<ActResult> {
-  const response = await fetch(`${API_BASE}/sessions/${sessionId}/act`, {
-    method: "POST",
-    headers: getHeaders(config),
-    body: JSON.stringify({
-      input: action,
-    }),
-  });
+  const body: Record<string, unknown> = { input: action };
+  if (
+    operationOptions?.model != null ||
+    operationOptions?.variables != null ||
+    operationOptions?.timeout != null
+  ) {
+    body.options = {
+      model: operationOptions?.model,
+      variables: operationOptions?.variables,
+      timeout: operationOptions?.timeout,
+    };
+  }
+  const response = await fetch(
+    `${getApiBase(region)}/sessions/${sessionId}/act`,
+    {
+      method: "POST",
+      headers: getHeaders(config),
+      body: JSON.stringify(body),
+    },
+  );
   return handleResponse<ActResult>(response);
 }
 
+/** Matches ObserveResult from the OpenAPI spec (Action schema) */
 export interface ObserveResult {
   result: Array<{
     description: string;
     selector: string;
     arguments?: string[];
     backendNodeId?: number;
-    method: string;
+    method?: string;
   }>;
-  actionId: string;
+  actionId?: string;
+}
+
+/** Matches ObserveOptions from the OpenAPI spec */
+export interface ObserveOperationOptions {
+  model?: unknown;
+  timeout?: number;
+  selector?: string;
 }
 
+/** POST /v1/sessions/{id}/observe — matches ObserveRequest schema */
 export async function observe(
   sessionId: string,
   instruction: string,
   config: ApiConfig,
+  operationOptions?: ObserveOperationOptions,
+  region?: BrowserbaseRegion,
 ): Promise<ObserveResult> {
-  const response = await fetch(`${API_BASE}/sessions/${sessionId}/observe`, {
-    method: "POST",
-    headers: getHeaders(config),
-    body: JSON.stringify({
-      instruction,
-    }),
-  });
+  const body: Record<string, unknown> = { instruction };
+  if (
+    operationOptions?.model != null ||
+    operationOptions?.timeout != null ||
+    operationOptions?.selector != null
+  ) {
+    body.options = {
+      model: operationOptions?.model,
+      timeout: operationOptions?.timeout,
+      selector: operationOptions?.selector,
+    };
+  }
+  const response = await fetch(
+    `${getApiBase(region)}/sessions/${sessionId}/observe`,
+    {
+      method: "POST",
+      headers: getHeaders(config),
+      body: JSON.stringify(body),
+    },
+  );
   return handleResponse<ObserveResult>(response);
 }
 
+/** Matches AgentConfig from the OpenAPI spec */
 export interface AgentConfig {
   cua?: boolean;
-  model?: string;
+  mode?: "dom" | "hybrid" | "cua";
+  model?: unknown;
   systemPrompt?: string;
+  executionModel?: unknown;
+  provider?: "openai" | "anthropic" | "google" | "microsoft";
 }
 
+/** Matches AgentExecuteOptions from the OpenAPI spec */
 export interface AgentExecuteOptions {
   instruction: string;
   maxSteps?: number;
+  highlightCursor?: boolean;
 }
 
+/** Matches AgentAction from the OpenAPI spec */
 export interface AgentAction {
   type: string;
   action?: string;
   reasoning?: string;
   timeMs?: number;
+  taskCompleted?: boolean;
+  pageText?: string;
+  pageUrl?: string;
+  instruction?: string;
+}
+
+/** Matches AgentUsage from the OpenAPI spec */
+export interface AgentUsage {
+  input_tokens: number;
+  output_tokens: number;
+  reasoning_tokens?: number;
+  cached_input_tokens?: number;
+  inference_time_ms: number;
 }
 
+/** Matches AgentExecuteResult from the OpenAPI spec */
 export interface AgentExecuteResult {
   result: {
     actions: AgentAction[];
     completed: boolean;
     message: string;
     success: boolean;
+    metadata?: Record<string, unknown>;
+    usage?: AgentUsage;
   };
 }
 
+/** POST /v1/sessions/{id}/agentExecute — matches AgentExecuteRequest schema */
 export async function agentExecute(
   sessionId: string,
   agentConfig: AgentConfig,
   executeOptions: AgentExecuteOptions,
   config: ApiConfig,
+  shouldCache?: boolean,
+  region?: BrowserbaseRegion,
 ): Promise<AgentExecuteResult> {
   const response = await fetch(
-    `${API_BASE}/sessions/${sessionId}/agentExecute`,
+    `${getApiBase(region)}/sessions/${sessionId}/agentExecute`,
     {
       method: "POST",
       headers: getHeaders(config),
       body: JSON.stringify({
         agentConfig: {
           cua: agentConfig.cua,
+          mode: agentConfig.mode,
           model: agentConfig.model,
           systemPrompt: agentConfig.systemPrompt,
+          executionModel: agentConfig.executionModel,
+          provider: agentConfig.provider,
+        },
+        executeOptions: {
+          instruction: executeOptions.instruction,
+          maxSteps: executeOptions.maxSteps,
+          highlightCursor: executeOptions.highlightCursor,
         },
-        instruction: executeOptions.instruction,
-        maxSteps: executeOptions.maxSteps,
+        shouldCache,
       }),
     },
   );