feat(stripe): migrate Stagehand payment example to v3 (#61)

- V3Options in stagehand.config; add stripe dependency
- observe/act on Stagehand; ObserveResult and actWithCache helpers

Made-with: Cursor

Author: Kylejeong2

examples/integrations/stripe/stagehand/4-make-payment.ts

@@ -10,7 +10,7 @@
  * To edit config, see `stagehand.config.ts`
  *
  */
-import { Page, BrowserContext, Stagehand } from "@browserbasehq/stagehand";
+import { Stagehand } from "@browserbasehq/stagehand";
 import { z } from "zod";
 import chalk from "chalk";
 import dotenv from "dotenv";
@@ -21,55 +21,42 @@ dotenv.config();
 const cardId = "ic_1Qu1XJGhqv5yXZ43z9OdjbXs"; // replace with your card id from the previous step
 
 export async function main({
-  page,
-  context,
   stagehand,
 }: {
-  page: Page; // Playwright Page with act, extract, and observe methods
-  context: BrowserContext; // Playwright BrowserContext
-  stagehand: Stagehand; // Stagehand instance
+  stagehand: Stagehand;
 }) {
-  // Learn more about Stagehand: https://www.stagehand.dev/
-
+  const page = stagehand.context.pages()[0];
   const paymentInfo = await getCard(cardId);
 
   // Navigate to Red Cross donation page
   await page.goto('https://www.redcross.org/donate/donation.html/')
-  const donationAmount = await page.observe({
-      instruction: "Find the donation amounts",
-      returnAction: true,
-      onlyVisible: false,
-  });
+  const donationAmount = await stagehand.observe(
+      "Find the donation amounts"
+  );
   // Click the first donation amount
-  await page.act(donationAmount[0])
+  await stagehand.act(donationAmount[0])
 
   // Find the continue button and click it
-  const continueButton = await page.observe({
-      instruction: "Find the continue button and click it",
-      returnAction: true,
-      onlyVisible: false,
-  });
-  await page.act(continueButton[0])
+  const continueButton = await stagehand.observe(
+      "Find the continue button and click it"
+  );
+  await stagehand.act(continueButton[0])
 
   // Find the credit card button and click it
-  const creditCardButton = await page.observe({
-      instruction: "Find the credit card button and click it",
-      returnAction: true,
-      onlyVisible: false,
-  });
-  await page.act(creditCardButton[0])
+  const creditCardButton = await stagehand.observe(
+      "Find the credit card button and click it"
+  );
+  await stagehand.act(creditCardButton[0])
 
-  await page.act({action: "click the continue button"})
+  await stagehand.act("click the continue button")
 
-  const formValues = await page.observe({
-      instruction: `Fill in the form with the following values: ${JSON.stringify(paymentInfo)}`,
-      returnAction: true,
-      onlyVisible: false,
-  });
+  const formValues = await stagehand.observe(
+      `Fill in the form with the following values: ${JSON.stringify(paymentInfo)}`
+  );
   console.log("formValues", formValues);
 
   // Fill in the form with the values
   for (const value of formValues) {
-      await page.act(value);
+      await stagehand.act(value);
   }
 }

examples/integrations/stripe/stagehand/index.ts

@@ -36,11 +36,7 @@ async function run() {
     );
   }
 
-  const page = stagehand.page;
-  const context = stagehand.context;
   await main({
-    page,
-    context,
     stagehand,
   });
   await stagehand.close();

examples/integrations/stripe/stagehand/package.json

@@ -8,7 +8,8 @@
   },
   "dependencies": {
     "@browserbasehq/sdk": "^2.6.0",
-    "@browserbasehq/stagehand": "^2.4.4",
+    "@browserbasehq/stagehand": "^3.2.0",
+    "stripe": "^17.7.0",
     "@playwright/test": "^1.49.1",
     "boxen": "^8.0.1",
     "chalk": "^5.3.0",

examples/integrations/stripe/stagehand/stagehand.config.ts

@@ -1,65 +1,24 @@
-import type { ConstructorParams, LogLine } from "@browserbasehq/stagehand";
+import type { LogLine, V3Options } from "@browserbasehq/stagehand";
 import dotenv from "dotenv";
-false
-false
 
 dotenv.config();
 
-const StagehandConfig: ConstructorParams = {
+const StagehandConfig: V3Options = {
   env: "BROWSERBASE",
-  apiKey: process.env.BROWSERBASE_API_KEY /* API key for authentication */,
-  projectId: process.env.BROWSERBASE_PROJECT_ID /* Project identifier */,
-  debugDom: undefined /* Enable DOM debugging features */,
-  headless: false /* Run browser in headless mode */,
-  logger: (message: LogLine) =>
-    console.log(logLineToString(message)) /* Custom logging function */,
-  domSettleTimeoutMs: 30_000 /* Timeout for DOM to settle in milliseconds */,
+  apiKey: process.env.BROWSERBASE_API_KEY,
+  projectId: process.env.BROWSERBASE_PROJECT_ID,
+  domSettleTimeout: 30_000,
+  logger: (message: LogLine) => console.log(logLineToString(message)),
+  model: "openai/gpt-4o",
   browserbaseSessionCreateParams: {
     projectId: process.env.BROWSERBASE_PROJECT_ID!,
   },
-  enableCaching: undefined /* Enable caching functionality */,
-  browserbaseSessionID:
-    undefined /* Session ID for resuming Browserbase sessions */,
-  modelName: "gpt-4o" /* Name of the model to use */,
-      modelClientOptions: {
-        apiKey: process.env.OPENAI_API_KEY,
-      } /* Configuration options for the model client */,
-  
-  
+  browserbaseSessionID: undefined,
 };
 
 export default StagehandConfig;
 
-/**
- * Custom logging function that you can use to filter logs.
- *
- * General pattern here is that `message` will always be unique with no params
- * Any param you would put in a log is in `auxiliary`.
- *
- * For example, an error log looks like this:
- *
- * ```
- * {
- *   category: "error",
- *   message: "Some specific error occurred",
- *   auxiliary: {
- *     message: { value: "Error message", type: "string" },
- *     trace: { value: "Error trace", type: "string" }
- *   }
- * }
- * ```
- *
- * You can then use `logLineToString` to filter for a specific log pattern like
- *
- * ```
- * if (logLine.message === "Some specific error occurred") {
- *   console.log(logLineToString(logLine));
- * }
- * ```
- */
 export function logLineToString(logLine: LogLine): string {
-  // If you want more detail, set this to false. However, this will make the logs
-  // more verbose and harder to read.
   const HIDE_AUXILIARY = true;
 
   try {
@@ -68,7 +27,6 @@ export function logLineToString(logLine: LogLine): string {
       return `${timestamp}::[stagehand:${logLine.category}] ${logLine.message}\n ${logLine.auxiliary.error.value}\n ${logLine.auxiliary.trace.value}`;
     }
 
-    // If we want to hide auxiliary information, we don't add it to the log
     return `${timestamp}::[stagehand:${logLine.category}] ${logLine.message} ${
       logLine.auxiliary && !HIDE_AUXILIARY
         ? JSON.stringify(logLine.auxiliary)
@@ -78,4 +36,4 @@ export function logLineToString(logLine: LogLine): string {
     console.error(`Error logging line:`, error);
     return "error logging line";
   }
-}
+}

examples/integrations/stripe/stagehand/utils.ts

@@ -1,4 +1,9 @@
-import { ObserveResult, Page } from "@browserbasehq/stagehand";
+import type {
+  Action,
+  ObserveResult,
+  Page,
+  Stagehand,
+} from "@browserbasehq/stagehand";
 import boxen from "boxen";
 import chalk from "chalk";
 import fs from "fs/promises";
@@ -10,15 +15,10 @@ export function announce(message: string, title?: string) {
       padding: 1,
       margin: 3,
       title: title || "Stagehand",
-    })
+    }),
   );
 }
 
-/**
- * Get an environment variable and throw an error if it's not found
- * @param name - The name of the environment variable
- * @returns The value of the environment variable
- */
 export function getEnvVar(name: string, required = true): string | undefined {
   const value = process.env[name];
   if (!value && required) {
@@ -27,12 +27,6 @@ export function getEnvVar(name: string, required = true): string | undefined {
   return value;
 }
 
-/**
- * Validate a Zod schema against some data
- * @param schema - The Zod schema to validate against
- * @param data - The data to validate
- * @returns Whether the data is valid against the schema
- */
 export function validateZodSchema(schema: z.ZodTypeAny, data: unknown) {
   try {
     schema.parse(data);
@@ -42,11 +36,9 @@ export function validateZodSchema(schema: z.ZodTypeAny, data: unknown) {
   }
 }
 
-export async function drawObserveOverlay(page: Page, results: ObserveResult[]) {
-  // Convert single xpath to array for consistent handling
-  const xpathList = results.map((result) => result.selector);
+export async function drawObserveOverlay(page: Page, results: ObserveResult) {
+  const xpathList = results.map((result: Action) => result.selector);
 
-  // Filter out empty xpaths
   const validXpaths = xpathList.filter((xpath) => xpath !== "xpath=");
 
   await page.evaluate((selectors) => {
@@ -59,7 +51,7 @@ export async function drawObserveOverlay(page: Page, results: ObserveResult[]) {
           document,
           null,
           XPathResult.FIRST_ORDERED_NODE_TYPE,
-          null
+          null,
         ).singleNodeValue;
       } else {
         element = document.querySelector(selector);
@@ -84,7 +76,6 @@ export async function drawObserveOverlay(page: Page, results: ObserveResult[]) {
 }
 
 export async function clearOverlays(page: Page) {
-  // remove existing stagehandObserve attributes
   await page.evaluate(() => {
     const elements = document.querySelectorAll('[stagehandObserve="true"]');
     elements.forEach((el) => {
@@ -97,39 +88,55 @@ export async function clearOverlays(page: Page) {
   });
 }
 
-export async function simpleCache(
-  instruction: string,
-  actionToCache: ObserveResult
-) {
-  // Save action to cache.json
+export async function simpleCache(instruction: string, actionToCache: Action) {
   try {
-    // Read existing cache if it exists
-    let cache: Record<string, ObserveResult> = {};
+    let cache: Record<string, Action> = {};
     try {
       const existingCache = await fs.readFile("cache.json", "utf-8");
       cache = JSON.parse(existingCache);
-    } catch (error) {
-      // File doesn't exist yet, use empty cache
+    } catch {
+      // no file yet
     }
 
-    // Add new action to cache
     cache[instruction] = actionToCache;
 
-    // Write updated cache to file
     await fs.writeFile("cache.json", JSON.stringify(cache, null, 2));
   } catch (error) {
     console.error(chalk.red("Failed to save to cache:"), error);
   }
 }
 
-export async function readCache(
-  instruction: string
-): Promise<ObserveResult | null> {
+export async function readCache(instruction: string): Promise<Action | null> {
   try {
     const existingCache = await fs.readFile("cache.json", "utf-8");
-    const cache: Record<string, ObserveResult> = JSON.parse(existingCache);
+    const cache: Record<string, Action> = JSON.parse(existingCache);
     return cache[instruction] || null;
-  } catch (error) {
+  } catch {
     return null;
   }
 }
+
+export async function actWithCache(
+  stagehand: Stagehand,
+  page: Page,
+  instruction: string,
+): Promise<void> {
+  const cachedAction = await readCache(instruction);
+  if (cachedAction) {
+    console.log(chalk.blue("Using cached action for:"), instruction);
+    await stagehand.act(cachedAction);
+    return;
+  }
+
+  const results = await stagehand.observe(instruction);
+  console.log(chalk.blue("Got results:"), results);
+
+  const actionToCache = results[0];
+  console.log(chalk.blue("Taking cacheable action:"), actionToCache);
+  await simpleCache(instruction, actionToCache);
+  await drawObserveOverlay(page, results);
+  await page.waitForTimeout(1000);
+  await clearOverlays(page);
+
+  await stagehand.act(actionToCache);
+}