upload method for stagehand

.changeset/chubby-experts-invent.md

@@ -0,0 +1,66 @@
+---
+"@browserbasehq/stagehand-examples": minor
+"@browserbasehq/stagehand-lib": minor
+"@browserbasehq/stagehand": minor
+---
+
+add upload method with file input + url/buffer support
+
+## New Features
+
+### 🚀 File Upload Method
+- **`stagehand.upload(hint: string, file: FileSpec)`** - New method for AI-powered file uploads
+- **Natural language hints** - Use descriptive text to locate file inputs (e.g., "Upload resume", "Upload cover letter")
+- **Multiple file sources** - Support for URLs, local paths, and in-memory buffers
+- **AI-powered detection** - Leverages Stagehand's `observe()` method for intelligent element finding
+
+### 🔧 Enhanced Type System
+- **`FileSpec`** - Discriminated union type for flexible file specification
+- **`UploadResult`** - Structured response with upload status and metadata
+- **Type safety** - Proper validation of file input combinations
+
+### 🌐 Environment Support
+- **LOCAL environment** - Works with local Playwright browsers
+- **BROWSERBASE environment** - Compatible with cloud-managed browser sessions
+- **Cross-platform** - Consistent behavior across different environments
+
+## Technical Details
+
+### Upload Strategies
+1. **Direct input** - Attach files directly to `<input type="file">` elements
+2. **File chooser** - Trigger file choosers by clicking associated controls
+3. **Heuristic search** - Find file inputs near/within hinted elements
+
+### File Processing
+- **URL downloads** - Automatic fetching and MIME type detection
+- **Memory efficient** - No temporary file creation
+- **Buffer handling** - Direct support for in-memory file data
+
+### Integration
+- **History tracking** - Upload events logged to Stagehand history
+- **Error handling** - Graceful fallbacks with detailed error reporting
+- **Performance** - Optimized for minimal DOM queries and efficient file processing
+
+## Usage Examples
+
+```typescript
+// Upload from URL
+await stagehand.upload("Upload resume", "https://example.com/resume.pdf");
+
+// Upload from buffer
+await stagehand.upload("Upload document", {
+  name: "document.pdf",
+  mimeType: "application/pdf",
+  buffer: pdfBuffer
+});
+
+// Multiple uploads
+await stagehand.upload("Upload resume", resumeFileUrl);
+await stagehand.upload("Upload cover letter", letterFileUrl);
+```
+
+## Breaking Changes
+None - This is a purely additive feature that maintains backward compatibility.
+
+## Migration
+No migration required - existing code continues to work unchanged.

examples/upload_test.ts

@@ -0,0 +1,103 @@
+// Import directly from local dist to ensure latest build is used
+import { Stagehand } from "../dist";
+import type { Page as PlaywrightPage } from "playwright";
+import StagehandConfig from "../stagehand.config";
+
+// Load environment variables
+import dotenv from "dotenv";
+dotenv.config({ path: "../.env" });
+
+async function main() {
+  // Accept file URL as command line argument or use default
+  const fileUrl = process.argv[2] || "https://www.orimi.com/pdf-test.pdf";
+  const targetPage =
+    process.argv[3] || "https://ps.uci.edu/~franklin/doc/file_upload.html";
+
+  console.log(`File URL: ${fileUrl}`);
+  console.log(`Target page: ${targetPage}`);
+
+  const stagehand = new Stagehand({
+    ...StagehandConfig,
+    env: "BROWSERBASE",
+    verbose: 1,
+    modelName: "openai/gpt-4o-mini",
+  });
+  await stagehand.init();
+  const page = stagehand.page;
+
+  try {
+    // Navigate to the target page
+    await page.goto(targetPage, {
+      waitUntil: "domcontentloaded",
+    });
+
+    // Debug: check presence of file inputs before calling upload
+    const count = await page.locator('input[type="file"]').count();
+    console.log("file input count:", count);
+
+    // Debug: log accessibility tree (full)
+    try {
+      const ax = await page.evaluate(() => {
+        if (typeof window.getComputedStyle !== 'undefined') {
+          return document.querySelector('body')?.innerHTML || 'No body content';
+        }
+        return 'Accessibility snapshot not available';
+      });
+      console.log("Page content:");
+      console.log(ax);
+    } catch (e) {
+      console.log("Failed to get page content:", e);
+    }
+
+    // Upload using the new helper - let observe find the right input
+    // Now we can pass the URL directly since upload() handles URLs
+    const result = await stagehand.upload("Upload this file", fileUrl);
+    console.log("upload result:", result);
+
+    // Try to submit the form using observe to find the submit button
+    try {
+      const [submitAction] = await page.observe(
+        "Find and click the submit or send button",
+      );
+      if (submitAction?.selector) {
+        console.log(
+          `Found submit button with selector: ${submitAction.selector}`,
+        );
+
+        // Avoid mixed-content warning by upgrading http action → https when possible
+        try {
+          await page.evaluate(() => {
+            const form = document.querySelector(
+              "form",
+            ) as HTMLFormElement | null;
+            if (
+              form &&
+              typeof form.action === "string" &&
+              form.action.startsWith("http://")
+            ) {
+              form.action = form.action.replace("http://", "https://");
+            }
+          });
+        } catch {
+          // ignore non-fatal submit upgrade errors
+        }
+
+        await page.act(submitAction);
+        console.log("Form submitted successfully");
+      } else {
+        console.log("No submit button found via observe");
+      }
+    } catch (e) {
+      console.log("Failed to find submit button via observe:", e);
+    }
+
+    await page.waitForTimeout(1500);
+  } finally {
+    await stagehand.close();
+  }
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});