wuying-agentbay-sdk 0.10.2 → 0.12.0

package/docs/examples/basic-usage.ts

@@ -0,0 +1,86 @@
+import { AgentBay, logError, log } from 'wuying-agentbay-sdk';
+
+async function main() {
+  try {
+    // Use the test API key function from test-helpers
+    const apiKey = process.env.AGENTBAY_API_KEY || 'akm-xxx'; // Replace with your actual API key
+    if (!process.env.AGENTBAY_API_KEY) {
+      log('Warning: Using placeholder API key. Set AGENTBAY_API_KEY environment variable for production use.');
+    }
+
+    // Initialize the AgentBay client
+    const agentBay = new AgentBay({ apiKey });
+
+    // Create a new session with labels
+    log('Creating a new session with labels...');
+    const createResponse = await agentBay.create({imageId:'browser_latest'});
+    const session = createResponse.session;
+    log(`Session created with ID: ${session.sessionId}`);
+    log(`Create Session RequestId: ${createResponse.requestId}`);
+
+    // Execute a command
+    log('\nExecuting a command...');
+    const commandResponse = await session.command.executeCommand('ls -la');
+    log('Command result:', commandResponse.output);
+    log(`Execute Command RequestId: ${commandResponse.requestId}`);
+
+    // Read a file
+    log('\nReading a file...');
+    const fileResponse = await session.fileSystem.readFile('/etc/hosts');
+    log(`File content: ${fileResponse.content}`);
+    log(`Read File RequestId: ${fileResponse.requestId}`);
+
+    // Get the session link
+    log('\nGetting session link...');
+    try {
+      const linkResponse = await session.getLink();
+      log(`Session link: ${linkResponse.data}`);
+      log(`Get Link RequestId: ${linkResponse.requestId}`);
+    } catch (error) {
+      log(`Note: Failed to get session link: ${error}`);
+    }
+
+    // Note: Screenshot functionality is available via session.mobile.screenshot() or session.computer.screenshot()
+    // depending on the session type (mobile or computer). Browser sessions don't have a direct screenshot API
+    // at the session level - use browser automation tools like Playwright for browser screenshots.
+
+    // List all sessions by labels
+    log('\nListing sessions...');
+    try {
+      // List sessions with labels (page 1, limit 5)
+      const listResponse = await agentBay.list({ test: 'basic-usage' }, 1, 5);
+      log(`Available sessions count: ${listResponse.sessionIds.length}`);
+      if (listResponse.totalCount !== undefined) {
+        log(`Total count: ${listResponse.totalCount}`);
+      }
+      if (listResponse.maxResults !== undefined) {
+        log(`Max results: ${listResponse.maxResults}`);
+      }
+      log('Session IDs:', listResponse.sessionIds);
+      log(`List Sessions RequestId: ${listResponse.requestId}`);
+
+      // Demonstrate pagination if there's a next token
+      if (listResponse.nextToken) {
+        log('\nFetching next page...');
+        const nextPageResponse = await agentBay.list({ test: 'basic-usage' }, 2, 5);
+        log(`Next page sessions count: ${nextPageResponse.sessionIds.length}`);
+        log(`Next page RequestId: ${nextPageResponse.requestId}`);
+      }
+    } catch (error) {
+      log(`Note: Failed to list sessions: ${error}`);
+    }
+
+    // Delete the session
+    log('\nDeleting the session...');
+    const deleteResponse = await agentBay.delete(session);
+    log('Session deleted successfully');
+    log(`Delete Session RequestId: ${deleteResponse.requestId}`);
+
+  } catch (error) {
+    logError('Error:', error);
+    // In a Node.js environment, you would use process.exit(1) here
+    throw error;
+  }
+}
+
+main();

package/docs/examples/browser-use/browser/README.md

@@ -0,0 +1,356 @@
+# TypeScript Browser Examples
+
+This directory contains TypeScript examples demonstrating browser automation capabilities of the AgentBay SDK.
+
+## Prerequisites
+
+1. **Install TypeScript SDK**:
+   ```bash
+   npm install @wuying-org/agentbay-sdk
+   ```
+
+2. **Install Playwright**:
+   ```bash
+   npm install playwright
+   npx playwright install chromium
+   ```
+
+3. **Set API Key**:
+   ```bash
+   export AGENTBAY_API_KEY=your_api_key_here
+   ```
+
+## Examples
+
+### 1. basic-usage.ts
+
+A basic example showing how to:
+- Create a session with a browser-enabled image
+- Initialize the browser with default options
+- Connect to the browser using Playwright over CDP
+- Navigate to a website and interact with it
+- Proper cleanup of resources
+
+**Run:**
+```bash
+ts-node basic-usage.ts
+```
+
+**Key Features:**
+- Session creation and management
+- Browser initialization
+- CDP connection with Playwright
+- Basic navigation
+- Resource cleanup
+
+### 2. browser-viewport.ts
+
+Demonstrates custom viewport and screen configuration:
+- Setting custom user agent
+- Configuring viewport dimensions
+- Setting screen dimensions
+- Verifying browser configuration
+
+**Run:**
+```bash
+ts-node browser-viewport.ts
+```
+
+**Key Features:**
+- Custom user agent
+- Viewport configuration
+- Screen dimensions
+- Configuration verification
+
+### 3. browser-fingerprint-xxx.ts
+
+Shows how to configure browser fingerprinting:
+- Three construction methods: random generation, custom configuration, and local fingerprint sync
+- Fingerprint persistence capabilities across sessions
+
+**Run:**
+```bash
+ts-node browser-fingerprint-xxx.ts
+```
+
+### 4. browser-proxies.ts
+
+Demonstrates proxy configuration:
+- Custom proxy setup
+- WuYing proxy strategies (restricted/polling)
+- Proxy authentication
+
+**Run:**
+```bash
+ts-node browser-proxies.ts
+```
+
+**Key Features:**
+- Custom proxy configuration
+- WuYing proxy integration
+- Proxy authentication
+- IP rotation strategies
+
+### 5. browser-context-cookie-persistence.ts
+
+Demonstrates cookie persistence across sessions:
+- Creating sessions with Browser Context
+- Setting cookies manually using Playwright
+- Deleting sessions with context synchronization
+- Verifying cookie persistence in new sessions
+
+**Run:**
+```bash
+ts-node browser-context-cookie-persistence.ts
+```
+
+**Key Features:**
+- Browser Context configuration
+- Cookie persistence
+- Cross-session data sharing
+- Resource cleanup
+
+### 6. browser-type-example.ts
+
+Comprehensive example demonstrating browser type selection:
+- Chrome browser initialization
+- Chromium browser initialization
+- Default browser (undefined) usage
+- Browser configuration verification
+- Type-safe TypeScript patterns
+
+**Run:**
+```bash
+# Run full example (tests all browser types)
+ts-node browser-type-example.ts
+
+# Run quick example (Chrome only)
+ts-node browser-type-example.ts --quick
+
+# Run type-safe example (demonstrates TypeScript types)
+ts-node browser-type-example.ts --type-safe
+```
+
+**Key Features:**
+- Browser type selection for Chrome, Chromium, and default
+- TypeScript type safety demonstration
+- Configuration validation
+- Browser detection and verification
+- Multiple usage patterns (BrowserOptionClass vs plain object)
+- Command-line options for different test modes
+
+### 7. Game Automation Examples
+
+**run-2048.ts** and **run-sudoku.ts** demonstrate:
+- Complex interaction patterns
+- Agent-based automation for games
+- Advanced browser control
+- AI-powered game solving
+
+**Run:**
+```bash
+ts-node run-2048.ts
+ts-node run-sudoku.ts
+```
+
+### 8. screenshot-example.ts
+
+An example demonstrating screenshot capabilities:
+- Creating a browser session with AgentBay
+- Using Playwright to connect to the browser instance
+- Taking screenshots using direct Playwright integration (Uint8Array data)
+- Saving screenshots to local files
+- Customizing screenshot options (full page, image format, quality)
+
+**Run:**
+```bash
+ts-node screenshot-example.ts
+```
+
+**Expected Output:**
+```
+📸 AgentBay Browser Screenshot Demo (TypeScript)
+==================================================
+Initializing AgentBay client...
+Creating a new session...
+Session created with ID: sess-xxxxx
+Browser initialized successfully
+Endpoint URL: ws://...
+📸 Taking screenshot...
+ℹ️  Note: Screenshot functionality requires Playwright TypeScript integration
+✅ Browser screenshot demo completed
+
+🧹 Cleaning up session sess-xxxxx...
+✅ Session deleted successfully
+```
+
+## Browser Type Selection
+
+When using computer use images, you can choose between Chrome and Chromium:
+
+```typescript
+import { BrowserOptionClass } from '@wuying-org/agentbay-sdk';
+
+// Use Chrome
+const option = new BrowserOptionClass(
+  false,  // useStealth
+  undefined,  // userAgent
+  undefined,  // viewport
+  undefined,  // screen
+  undefined,  // fingerprint
+  false,  // solveCaptchas
+  undefined,  // proxies
+  'chrome' as 'chrome'  // browserType
+);
+
+// Or use plain object
+const option = { browserType: 'chrome' as 'chrome' };
+
+// Use Chromium
+const option = { browserType: 'chromium' as 'chromium' };
+
+// Use default (undefined - let image decide)
+const option = new BrowserOptionClass();
+```
+
+## Common Patterns
+
+### Basic Browser Initialization
+
+```typescript
+import { AgentBay, CreateSessionParams, BrowserOptionClass } from '@wuying-org/agentbay-sdk';
+
+const agentBay = new AgentBay(process.env.AGENTBAY_API_KEY!);
+const params = new CreateSessionParams({ imageId: 'browser_latest' });
+const result = await agentBay.create(params);
+
+if (!result.success || !result.session) {
+  throw new Error("Failed to create session");
+}
+
+const session = result.session;
+const option = new BrowserOptionClass();
+const success = await session.browser.initializeAsync(option);
+
+if (!success) {
+  throw new Error("Browser initialization failed");
+}
+```
+
+### Connecting Playwright
+
+```typescript
+import { chromium } from 'playwright';
+
+const endpointUrl = session.browser.getEndpointUrl();
+const browser = await chromium.connectOverCDP(endpointUrl);
+const context = browser.contexts()[0];
+const page = await context.newPage();
+
+// Use page...
+
+await browser.close();
+session.delete();
+```
+
+### Error Handling
+
+```typescript
+try {
+  const success = await session.browser.initializeAsync(option);
+  if (!success) {
+    throw new Error("Initialization failed");
+  }
+  
+  // Use browser...
+  
+} catch (error) {
+  console.error(`Error: ${error.message}`);
+} finally {
+  session.delete();
+}
+```
+
+### Type-Safe Configuration
+
+```typescript
+import { BrowserOption } from '@wuying-org/agentbay-sdk';
+
+const option: BrowserOption = {
+  browserType: 'chrome',  // Type-checked
+  useStealth: true,
+  viewport: { width: 1920, height: 1080 },
+  fingerprint: {
+    devices: ["desktop"],
+    operatingSystems: ["windows", "macos"],
+    locales: ["en-US"]
+  }
+};
+```
+
+## Troubleshooting
+
+### "AGENTBAY_API_KEY not set"
+
+Set your API key:
+```bash
+export AGENTBAY_API_KEY=your_api_key_here
+```
+
+### "Browser not initialized"
+
+Ensure the browser is initialized before connecting:
+```typescript
+if (!session.browser.isInitialized()) {
+  throw new Error("Browser must be initialized first");
+}
+```
+
+### "Failed to connect over CDP"
+
+Check that the browser initialization was successful:
+```typescript
+const success = await session.browser.initializeAsync(option);
+console.log(`Initialization success: ${success}`);
+```
+
+### TypeScript Compilation Errors
+
+Ensure you have the correct types:
+```bash
+npm install --save-dev @types/node
+```
+
+## Additional Resources
+
+- [Browser API Reference](../../../api/browser-use/browser.md)
+- [Browser Use Guide](../../../../../docs/guides/browser-use/README.md)
+- [Core Features](../../../../../docs/guides/browser-use/core-features.md)
+- [Advanced Features](../../../../../docs/guides/browser-use/advance-features.md)
+- [Playwright Documentation](https://playwright.dev/docs/intro)
+
+## Example Output
+
+### Successful Execution
+
+```
+Creating session...
+Session created: sess-xxxxx
+Initializing browser...
+Browser initialized successfully
+CDP endpoint: ws://...
+Connecting to browser...
+Page title: Example Domain
+Browser automation completed
+Session deleted
+```
+
+### With Custom Configuration
+
+```
+Initializing browser with custom configuration...
+User Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...
+Viewport: 1920 x 1080
+Screen: 1920 x 1080
+Configuration verified successfully
+```

package/docs/examples/browser-use/browser/basic-usage.ts

@@ -0,0 +1,136 @@
+/**
+ * Basic usage example for AgentBay Browser functionality in TypeScript.
+ * This example demonstrates the core browser operations without external dependencies.
+ */
+
+import { AgentBay, CreateSessionParams, ActOptions, ObserveOptions, ExtractOptions } from 'wuying-agentbay-sdk';
+
+// Simple schema for demonstration
+class PageInfo {
+  title: string = "";
+  url: string = "";
+}
+
+async function main() {
+  // Get API key from environment variable
+  const apiKey = process.env.AGENTBAY_API_KEY;
+  if (!apiKey) {
+    console.log("Error: AGENTBAY_API_KEY environment variable not set");
+    return;
+  }
+
+  try {
+    // Initialize AgentBay client
+    console.log("Initializing AgentBay client...");
+    const agentBay = new AgentBay({ apiKey });
+
+    // Create a session with browser image
+    console.log("Creating a new session...");
+    const params: CreateSessionParams = {
+      imageId: "browser_latest",
+    };
+    const sessionResult = await agentBay.create(params);
+
+    if (!sessionResult.success) {
+      console.log("Failed to create session");
+      return;
+    }
+
+    const session = sessionResult.session;
+    console.log(`Session created with ID: ${session.sessionId}`);
+
+    // Initialize browser
+    console.log("Initializing browser...");
+    // Note: persistentPath is currently ignored by the SDK implementation
+    const initialized = await session.browser.initializeAsync({});
+    if (!initialized) {
+      console.log("Failed to initialize browser");
+      return;
+    }
+
+    console.log("Browser initialized successfully");
+
+    // Get browser endpoint for external connections (like Playwright)
+    const endpointUrl = await session.browser.getEndpointUrl();
+    console.log("Browser endpoint URL:", endpointUrl);
+
+    // Example: Mock page object (in real usage, you'd get this from Playwright)
+    const mockPage = {
+      url: () => "https://example.com",
+      title: () => "Example Domain"
+    };
+
+    // Example 1: Perform an action
+    console.log("\n--- Example 1: Performing an action ---");
+    try {
+      const actOptions: ActOptions = {
+        action: "Click the 'More information...' link",
+        timeoutMS: 5000
+      };
+
+      const actResult = await session.browser.agent.act(actOptions, mockPage);
+      console.log("Action result:", {
+        success: actResult.success,
+        message: actResult.message,
+      });
+    } catch (error) {
+      console.log("Action failed:", error);
+    }
+
+    // Example 2: Observe elements on the page
+    console.log("\n--- Example 2: Observing page elements ---");
+    try {
+      const observeOptions: ObserveOptions = {
+        instruction: "Find all links and buttons on the page"
+      };
+
+      const [observeSuccess, observations] = await session.browser.agent.observe(observeOptions, mockPage);
+      console.log("Observe success:", observeSuccess);
+      console.log("Number of observations:", observations.length);
+
+      observations.forEach((obs: any, index: number) => {
+        console.log(`Observation ${index + 1}:`, {
+          selector: obs.selector,
+          description: obs.description,
+          method: obs.method
+        });
+      });
+    } catch (error) {
+      console.log("Observation failed:", error);
+    }
+
+    // Example 3: Extract structured data from the page
+    console.log("\n--- Example 3: Extracting structured data ---");
+    try {
+      const extractOptions: ExtractOptions<PageInfo> = {
+        instruction: "Extract the page title and URL",
+        schema: PageInfo,
+        use_text_extract: false
+      };
+
+      const [extractSuccess, extractedData] = await session.browser.agent.extract(extractOptions, mockPage);
+      console.log("Extract success:", extractSuccess);
+      console.log("Extracted data count:", extractedData.length);
+
+      extractedData.forEach((data: PageInfo, index: number) => {
+        console.log(`Extracted item ${index + 1}:`, {
+          title: data.title,
+          url: data.url
+        });
+      });
+    } catch (error) {
+      console.log("Extraction failed:", error);
+    }
+
+    // Clean up
+    console.log("\n--- Cleanup ---");
+    console.log("Browser session completed successfully");
+
+  } catch (error) {
+    console.error("Error in main function:", error);
+  }
+}
+
+if (require.main === module) {
+  main().catch(console.error);
+}

package/docs/examples/browser-use/browser/browser-command-args.ts

@@ -0,0 +1,117 @@
+/**
+ * Example demonstrating Browser Launch with Custom Command Arguments and 
+ * go to Default Navigation URL with AgentBay SDK.
+ *
+ * This example shows how to configure browser with custom command arguments
+ * and go to default navigation URL:
+ * - Create AIBrowser session with custom command arguments and go to default navigation URL
+ * - Use playwright to connect to AIBrowser instance through CDP protocol
+ * - Verify the browser navigated to the default URL
+ * - Test custom command arguments effects
+ */
+
+// @ts-nocheck
+import { AgentBay, CreateSessionParams } from 'wuying-agentbay-sdk';
+import { BrowserOption } from 'wuying-agentbay-sdk';
+import { chromium } from 'playwright';
+
+async function main(): Promise<void> {
+    // Get API key from environment variable
+    const apiKey = process.env.AGENTBAY_API_KEY;
+    if (!apiKey) {
+        console.log('Error: AGENTBAY_API_KEY environment variable not set');
+        return;
+    }
+
+    try {
+        // Initialize AgentBay client
+        console.log('Initializing AgentBay client...');
+        const agentBay = new AgentBay({ apiKey });
+
+        // Create a session
+        console.log('Creating a new session...');
+        const params: CreateSessionParams = {
+            imageId: 'linux_latest',
+        };
+        const sessionResult = await agentBay.create(params);
+
+        if (!sessionResult.success) {
+            console.log('Failed to create session');
+            return;
+        }
+
+        const session = sessionResult.session;
+        console.log(`Session created with ID: ${session.sessionId}`);
+
+        // Create browser option with user defined cmd args and default navigate url
+        const browserOption: BrowserOption = {
+            cmdArgs: ['--disable-features=PrivacySandboxSettings4'],
+            defaultNavigateUrl: 'chrome://version/',
+        };
+
+        console.log('Browser configuration:');
+        console.log('- Command arguments:', browserOption.cmdArgs);
+        console.log('- Default navigate URL:', browserOption.defaultNavigateUrl);
+
+        const initialized = await session.browser.initializeAsync(browserOption);
+        if (initialized) {
+            const endpointUrl = await session.browser.getEndpointUrl();
+            console.log('endpoint_url =', endpointUrl);
+
+            const browser = await chromium.connectOverCDP(endpointUrl);
+            const context = browser.contexts()[0];
+            console.log('page count =', context.pages().length);
+            const page = context.pages()[0];
+
+            try {
+                // Check if browser navigated to default URL
+                console.log('\n--- Check Default Navigation ---');
+                await page.waitForTimeout(2000); // Wait for navigation
+                const currentUrl = page.url();
+                console.log('Current URL:', currentUrl);
+                
+                if (currentUrl.includes('chrome://version/')) {
+                    console.log('✓ Browser successfully navigated to default URL');
+                } else {
+                    console.log('✗ Browser did not navigate to default URL');
+                }
+
+                // Test command arguments effect by checking Chrome version page
+                if (currentUrl.includes('chrome://version/')) {
+                    console.log('\n--- Check Chrome Version Info ---');
+                    const versionInfo = await page.evaluate(() => {
+                        const versionElement = document.querySelector('#version');
+                        const commandLineElement = document.querySelector('#command_line');
+                        return {
+                            version: versionElement ? versionElement.textContent : 'Not found',
+                            commandLine: commandLineElement ? commandLineElement.textContent : 'Not found'
+                        };
+                    });
+                    
+                    console.log('Chrome Version:', versionInfo.version);
+                    console.log('Command Line:', versionInfo.commandLine);
+                    
+                    if (versionInfo.commandLine.includes('--disable-features=PrivacySandboxSettings4')) {
+                        console.log('✓ Custom command argument found in browser');
+                    } else {
+                        console.log('✗ Custom command argument not found in browser');
+                    }
+                }
+
+                await page.waitForTimeout(3000);
+            } finally {
+                await browser.close();
+            }
+            await session.browser.destroy();
+        }
+
+        // Clean up session
+        await agentBay.delete(session);
+    } catch (error) {
+        console.error('Error:', error);
+    }
+}
+
+if (require.main === module) {
+    main().catch(console.error);
+}