jaysahnan/gro-814-screenshots-template

.gitignore

@@ -2,6 +2,7 @@
 .env
 cursorrules.md
 .cursorrules
+.cursor/
 
 # Dependencies
 node_modules/

python/basic-screenshots/README.md

@@ -0,0 +1,57 @@
+# Stagehand + Browserbase: Basic Screenshots Automation
+
+## AT A GLANCE
+
+- Goal: demonstrate how to automate screenshot capture during browser interactions using Stagehand.
+- Sequential Screenshots: capture full-page screenshots at key interaction points throughout an automation flow.
+- AI-Powered Navigation: use Stagehand's `act` method to navigate and interact with web pages naturally.
+- Documentation & Debugging: save screenshots locally for visual verification and debugging of automation flows.
+
+## GLOSSARY
+
+- act: perform UI actions from a natural language prompt (type, click, navigate).
+  Docs → https://docs.stagehand.dev/v2/basics/act
+- screenshot: capture visual representation of a web page at a specific point in time.
+- full-page screenshot: captures the entire scrollable page content, not just the visible viewport.
+- CDP (Chrome DevTools Protocol): browser debugging protocol that enables faster screenshot capture.
+  Docs → https://docs.browserbase.com/features/screenshots
+
+## QUICKSTART
+
+1. cd python/basic-screenshots
+2. uv venv venv
+3. source venv/bin/activate # On Windows: venv\Scripts\activate
+4. uvx install stagehand python-dotenv
+5. cp ../../.env.example .env (or create .env with required keys)
+6. Add your Browserbase API key, Project ID, and Google Generative AI API key to .env
+7. python main.py
+
+## EXPECTED OUTPUT
+
+- Creates a `screenshots` directory in the project folder
+- Initializes Stagehand session with Browserbase
+- Navigates to Polymarket homepage
+- Takes screenshot after initial page load
+- Clicks search box and captures screenshot
+- Types search query and captures screenshot
+- Selects first search result and captures final screenshot
+- Saves all screenshots as JPEG files with sequential naming
+- Displays live session link for monitoring
+
+## COMMON PITFALLS
+
+- "ModuleNotFoundError": ensure all dependencies are installed via uvx install
+- Missing API keys: verify .env contains BROWSERBASE_PROJECT_ID, BROWSERBASE_API_KEY, and GOOGLE_GENERATIVE_AI_API_KEY
+- Screenshot directory permissions: ensure write permissions for creating the screenshots folder
+- Page load timeouts: website may be slow or unresponsive, check network connectivity
+- Search results not found: target website structure may have changed, verify selectors still work
+- Import errors: activate your virtual environment if you created one
+
+## HELPFUL RESOURCES
+
+📚 Stagehand Docs: https://docs.stagehand.dev/v3/first-steps/introduction
+🎮 Browserbase: https://www.browserbase.com
+💡 Screenshots Guide: https://docs.browserbase.com/features/screenshots
+🔧 Templates: https://www.browserbase.com/templates
+📧 Need help? support@browserbase.com
+💬 Discord: http://stagehand.dev/discord

python/basic-screenshots/main.py

@@ -0,0 +1,109 @@
+# Stagehand + Browserbase: Basic Screenshots Automation - See README.md for full documentation
+
+import asyncio
+import os
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+from stagehand import Stagehand, StagehandConfig
+
+# Load environment variables
+load_dotenv()
+
+SCREENSHOTS_DIR = "screenshots"
+
+
+# Helper function to take and save a screenshot
+# Captures full-page screenshots in JPEG format for documentation and debugging
+async def take_screenshot(page, filename: str):
+    print(f"Taking screenshot: {filename}...")
+    filepath = os.path.join(SCREENSHOTS_DIR, filename)
+    await page.screenshot(path=filepath, type="jpeg", quality=80, full_page=True)
+    print(f"Saved: {filepath}")
+
+
+async def main():
+    print("Starting Basic Screenshots Example...")
+
+    # Create screenshots directory if it doesn't exist
+    Path(SCREENSHOTS_DIR).mkdir(parents=True, exist_ok=True)
+    print(f"Created directory: {SCREENSHOTS_DIR}")
+
+    # Initialize Stagehand with Browserbase for cloud-based browser automation
+    config = StagehandConfig(
+        env="BROWSERBASE",
+        api_key=os.environ.get("BROWSERBASE_API_KEY"),
+        project_id=os.environ.get("BROWSERBASE_PROJECT_ID"),
+        model_name="google/gemini-2.5-flash",
+        model_api_key=os.environ.get("GOOGLE_GENERATIVE_AI_API_KEY"),
+        verbose=0,
+        # 0 = errors only, 1 = info, 2 = debug
+        # (When handling sensitive data like passwords or API keys, set verbose: 0 to prevent secrets from appearing in logs.)
+        # https://docs.stagehand.dev/configuration/logging
+    )
+
+    try:
+        # Use async context manager for automatic resource management
+        async with Stagehand(config) as stagehand:
+            # Initialize browser session to start automation
+            print("Initializing browser session...")
+            print("Stagehand initialized successfully!")
+
+            # Provide live session URL for debugging and monitoring
+            session_id = None
+            if hasattr(stagehand, "session_id"):
+                session_id = stagehand.session_id
+            elif hasattr(stagehand, "browserbase_session_id"):
+                session_id = stagehand.browserbase_session_id
+
+            if session_id:
+                print(f"Live View Link: https://browserbase.com/sessions/{session_id}")
+
+            page = stagehand.page
+
+            # Navigate to Polymarket homepage
+            print("Navigating to: https://polymarket.com/")
+            await page.goto("https://polymarket.com/")
+            print("Page loaded successfully")
+            await take_screenshot(page, "screenshot-01-initial-page.jpeg")
+
+            # Click the search box to trigger search dropdown
+            print("Clicking the search box at the top of the page")
+            await page.act("click the search box at the top of the page")
+            await take_screenshot(page, "screenshot-02-after-click-search.jpeg")
+
+            # Type search query into the search box
+            search_query = "Elon Musk unfollow Trump"
+            print(f"Typing '{search_query}' into the search box")
+            await page.act(f"type '{search_query}' into the search box")
+            await take_screenshot(page, "screenshot-03-after-type-search.jpeg")
+
+            # Click the first market result from the search dropdown
+            print("Selecting first market result from search dropdown")
+            await page.act("click the first market result from the search dropdown")
+            print("Market page loaded")
+            await take_screenshot(page, "screenshot-04-after-select-market.jpeg")
+
+            print("All screenshots captured!")
+
+        print("Session closed successfully")
+
+    except Exception as error:
+        print(f"Error during screenshot capture: {error}")
+
+        # Provide helpful troubleshooting information
+        print("\nCommon issues:")
+        print("  - Check .env file has BROWSERBASE_PROJECT_ID and BROWSERBASE_API_KEY")
+        print("  - Verify GOOGLE_GENERATIVE_AI_API_KEY is set in environment")
+        print("  - Ensure internet access and https://polymarket.com is accessible")
+        print("  - Verify Browserbase account has sufficient credits")
+        raise
+
+
+if __name__ == "__main__":
+    try:
+        asyncio.run(main())
+    except Exception as err:
+        print(f"Application error: {err}")
+        exit(1)

typescript/basic-screenshots/README.md

@@ -0,0 +1,54 @@
+# Stagehand + Browserbase: Basic Screenshots Automation
+
+## AT A GLANCE
+
+- Goal: demonstrate how to automate screenshot capture during browser interactions using Stagehand.
+- Sequential Screenshots: capture full-page screenshots at key interaction points throughout an automation flow.
+- AI-Powered Navigation: use Stagehand's `act` method to navigate and interact with web pages naturally.
+- Documentation & Debugging: save screenshots locally for visual verification and debugging of automation flows.
+
+## GLOSSARY
+
+- act: perform UI actions from a natural language prompt (type, click, navigate).
+  Docs → https://docs.stagehand.dev/basics/act
+- screenshot: capture visual representation of a web page at a specific point in time.
+- full-page screenshot: captures the entire scrollable page content, not just the visible viewport.
+- CDP (Chrome DevTools Protocol): browser debugging protocol that enables faster screenshot capture.
+  Docs → https://docs.browserbase.com/features/screenshots
+
+## QUICKSTART
+
+1. cd typescript/basic-screenshots
+2. pnpm install (from project root)
+3. cp ../../.env.example .env (or create .env with required keys)
+4. Add your Browserbase API key, Project ID, and Google Generative AI API key to .env
+5. pnpm start (or run: pnpm tsx incdex.ts)
+
+## EXPECTED OUTPUT
+
+- Creates a `screenshots` directory in the project folder
+- Initializes Stagehand session with Browserbase
+- Navigates to Polymarket homepage
+- Takes screenshot after initial page load
+- Clicks search box and captures screenshot
+- Types search query and captures screenshot
+- Selects first search result and captures final screenshot
+- Saves all screenshots as JPEG files with sequential naming
+- Displays live session link for monitoring
+
+## COMMON PITFALLS
+
+- "Cannot find module 'fs'": ensure you're running from a Node.js environment with proper TypeScript setup
+- Missing API keys: verify .env contains BROWSERBASE_PROJECT_ID, BROWSERBASE_API_KEY, and GOOGLE_GENERATIVE_AI_API_KEY
+- Screenshot directory permissions: ensure write permissions for creating the screenshots folder
+- Page load timeouts: website may be slow or unresponsive, check network connectivity
+- Search results not found: target website structure may have changed, verify selectors still work
+
+## HELPFUL RESOURCES
+
+📚 Stagehand Docs: https://docs.stagehand.dev/v3/first-steps/introduction
+🎮 Browserbase: https://www.browserbase.com
+💡 Screenshots Guide: https://docs.browserbase.com/features/screenshots
+🔧 Templates: https://www.browserbase.com/templates
+📧 Need help? support@browserbase.com
+💬 Discord: http://stagehand.dev/discord

typescript/basic-screenshots/index.ts

@@ -0,0 +1,104 @@
+// Stagehand + Browserbase: Basic Screenshots Automation - See README.md for full documentation
+
+import { writeFileSync, mkdirSync, existsSync } from "fs";
+import { join } from "path";
+import { Stagehand } from "@browserbasehq/stagehand";
+import type { Page } from "playwright";
+import "dotenv/config";
+
+const SCREENSHOTS_DIR = "screenshots";
+
+// Helper function to take and save a screenshot
+// Captures full-page screenshots in JPEG format for documentation and debugging
+async function takeScreenshot(page: Page, filename: string) {
+  console.log(`Taking screenshot: ${filename}...`);
+  const buffer = await page.screenshot({
+    type: "jpeg",
+    quality: 80,
+    fullPage: true,
+  });
+  const filepath = join(SCREENSHOTS_DIR, filename);
+  writeFileSync(filepath, buffer);
+  console.log(`Saved: ${filepath}`);
+}
+
+async function main() {
+  console.log("Starting Basic Screenshots Example...");
+
+  // Create screenshots directory if it doesn't exist
+  if (!existsSync(SCREENSHOTS_DIR)) {
+    mkdirSync(SCREENSHOTS_DIR, { recursive: true });
+    console.log(`Created directory: ${SCREENSHOTS_DIR}`);
+  }
+
+  // Initialize Stagehand with Browserbase for cloud-based browser automation
+  const stagehand = new Stagehand({
+    env: "BROWSERBASE",
+    verbose: 0,
+    // 0 = errors only, 1 = info, 2 = debug
+    // (When handling sensitive data like passwords or API keys, set verbose: 0 to prevent secrets from appearing in logs.)
+    // https://docs.stagehand.dev/configuration/logging
+    model: "google/gemini-2.5-flash",
+  });
+
+  try {
+    // Initialize browser session to start automation
+    console.log("Initializing browser session...");
+    await stagehand.init();
+    console.log("Stagehand initialized successfully!");
+
+    // Provide live session URL for debugging and monitoring
+    if (stagehand.browserbaseSessionID) {
+      console.log(
+        `Live View Link: https://browserbase.com/sessions/${stagehand.browserbaseSessionID}`,
+      );
+    }
+
+    const page = stagehand.context.pages()[0];
+
+    // Navigate to Polymarket homepage
+    console.log("Navigating to: https://polymarket.com/");
+    await page.goto("https://polymarket.com/");
+    console.log("Page loaded successfully");
+    await takeScreenshot(page, "screenshot-01-initial-page.jpeg");
+
+    // Click the search box to trigger search dropdown
+    console.log("Clicking the search box at the top of the page");
+    await stagehand.act("click the search box at the top of the page");
+    await takeScreenshot(page, "screenshot-02-after-click-search.jpeg");
+
+    // Type search query into the search box
+    const searchQuery = "Elon Musk unfollow Trump";
+    console.log(`Typing '${searchQuery}' into the search box`);
+    await stagehand.act(`type '${searchQuery}' into the search box`);
+    await takeScreenshot(page, "screenshot-03-after-type-search.jpeg");
+
+    // Click the first market result from the search dropdown
+    console.log("Selecting first market result from search dropdown");
+    await stagehand.act("click the first market result from the search dropdown");
+    console.log("Market page loaded");
+    await takeScreenshot(page, "screenshot-04-after-select-market.jpeg");
+
+    console.log("All screenshots captured!");
+  } catch (error) {
+    console.error("Error during screenshot capture:", error);
+
+    // Provide helpful troubleshooting information
+    console.error("\nCommon issues:");
+    console.error("  - Check .env file has BROWSERBASE_PROJECT_ID and BROWSERBASE_API_KEY");
+    console.error("  - Verify GOOGLE_GENERATIVE_AI_API_KEY is set in environment");
+    console.error("  - Ensure internet access and https://polymarket.com is accessible");
+    console.error("  - Verify Browserbase account has sufficient credits");
+    throw error;
+  } finally {
+    // Always close session to release resources and clean up
+    console.log("Closing browser session...");
+    await stagehand.close();
+    console.log("Session closed successfully");
+  }
+}
+
+main().catch((err) => {
+  console.error("Application error:", err);
+  process.exit(1);
+});

typescript/basic-screenshots/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "basic-screenshots-template",
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "start": "tsx index.ts"
+  },
+  "dependencies": {
+    "@browserbasehq/sdk": "latest",
+    "@browserbasehq/stagehand": "latest",
+    "dotenv": "^16.4.7",
+    "zod": "latest"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.2",
+    "typescript": "^5.0.0"
+  }
+}