wuying-agentbay-sdk 0.10.2 → 0.11.0

package/docs/examples/browser-use/browser/browser-fingerprint-persistence.ts

@@ -0,0 +1,242 @@
+/**
+ * Integration test for browser fingerprint persistence functionality.
+ * This test verifies that browser fingerprint can be persisted
+ * across sessions using the same ContextId and FingerprintContextId.
+ */
+
+// @ts-nocheck
+import { AgentBay, CreateSessionParams } from 'wuying-agentbay-sdk';
+import { BrowserOption, BrowserFingerprint, BrowserContext, BrowserFingerprintContext } from 'wuying-agentbay-sdk';
+import { chromium } from 'playwright';
+
+// Global variables for persistent context and fingerprint context
+let persistentContext: any = null;
+let persistentFingerprintContext: any = null;
+
+function getTestApiKey(): string {
+  const apiKey = process.env.AGENTBAY_API_KEY;
+  if (!apiKey) {
+    throw new Error("AGENTBAY_API_KEY environment variable not set");
+  }
+  return apiKey;
+}
+
+function isWindowsUserAgent(userAgent: string): boolean {
+  if (!userAgent) {
+    return false;
+  }
+  const userAgentLower = userAgent.toLowerCase();
+  const windowsIndicators = [
+    'windows nt',
+    'win32',
+    'win64',
+    'windows',
+    'wow64'
+  ];
+  return windowsIndicators.some(indicator => userAgentLower.includes(indicator));
+}
+
+async function runAsFirstTime(): Promise<void> {
+  console.log("====================");
+  console.log("Run as first time");
+  console.log("====================");
+
+  const apiKey = getTestApiKey();
+  const agentBay = new AgentBay({ apiKey });
+
+  // Create a browser context for first time
+  const sessionContextName = `test-browser-context-${Date.now()}`;
+  const contextResult = await agentBay.context.get(sessionContextName, true);
+  if (!contextResult.success || !contextResult.context) {
+    console.log("Failed to create browser context");
+    return;
+  }
+
+  persistentContext = contextResult.context;
+  console.log(`Created browser context: ${persistentContext.name} (ID: ${persistentContext.id})`);
+
+  // Create a browser fingerprint context for first time
+  const fingerprintContextName = `test-browser-fingerprint-${Date.now()}`;
+  const fingerprintContextResult = await agentBay.context.get(fingerprintContextName, true);
+  if (!fingerprintContextResult.success || !fingerprintContextResult.context) {
+    console.log("Failed to create fingerprint context");
+    return;
+  }
+
+  persistentFingerprintContext = fingerprintContextResult.context;
+  console.log(`Created fingerprint context: ${persistentFingerprintContext.name} (ID: ${persistentFingerprintContext.id})`);
+
+  // Create session with BrowserContext and FingerprintContext
+  console.log(`Creating session with browser context ID: ${persistentContext.id} ` +
+              `and fingerprint context ID: ${persistentFingerprintContext.id}`);
+  
+  const fingerprintContext = new BrowserFingerprintContext(persistentFingerprintContext.id);
+  const browserContext = new BrowserContext(persistentContext.id, true, undefined, fingerprintContext);
+
+  const params = new CreateSessionParams()
+    .withImageId("browser_latest")
+    .withBrowserContext(browserContext);
+
+  const sessionResult = await agentBay.create(params);
+  if (!sessionResult.success || !sessionResult.session) {
+    console.log(`Failed to create first session: ${sessionResult.errorMessage}`);
+    return;
+  }
+
+  const session = sessionResult.session;
+  console.log(`First session created with ID: ${session.sessionId}`);
+
+  // Get browser object and generate fingerprint for persistence
+  async function firstSessionOperations(): Promise<void> {
+    // Initialize browser with fingerprint persistent enabled and set fingerprint generation options
+    const browserOption: BrowserOption = {
+      useStealth: true,
+      fingerprintPersistent: true,
+      fingerprint: {
+        devices: ["desktop"],
+        operatingSystems: ["windows"],
+        locales: ["zh-CN"]
+      } as BrowserFingerprint
+    };
+
+    const initSuccess = await session.browser.initializeAsync(browserOption);
+    if (!initSuccess) {
+      console.log("Failed to initialize browser");
+      return;
+    }
+    console.log("First session browser initialized successfully");
+
+    // Get endpoint URL
+    const endpointUrl = await session.browser.getEndpointUrl();
+    if (!endpointUrl) {
+      console.log("Failed to get browser endpoint URL");
+      return;
+    }
+    console.log(`First session browser endpoint URL: ${endpointUrl}`);
+
+    // Connect with playwright, test first session fingerprint
+    console.log("Opening https://httpbin.org/user-agent and test user agent...");
+    const browser = await chromium.connectOverCDP(endpointUrl);
+    const context = browser.contexts().length > 0 ? browser.contexts()[0] : await browser.newContext();
+
+    const page = await context.newPage();
+    await page.goto("https://httpbin.org/user-agent", { timeout: 60000 });
+    const response = await page.evaluate(() => JSON.parse(document.body.textContent));
+    const userAgent = response["user-agent"];
+    console.log("user_agent =", userAgent);
+    
+    const isWindows = isWindowsUserAgent(userAgent);
+    if (!isWindows) {
+      console.log("Failed to get windows user agent");
+      return;
+    }
+
+    await context.close();
+    console.log("First session browser fingerprint check completed");
+  }
+
+  // Run first session operations
+  await firstSessionOperations();
+
+  // Delete first session with syncContext=true
+  console.log("Deleting first session with syncContext=true...");
+  const deleteResult = await agentBay.delete(session, { syncContext: true });
+  console.log(`First session deleted successfully (RequestID: ${deleteResult.requestId})`);
+}
+
+async function runAsSecondTime(): Promise<void> {
+  console.log("====================");
+  console.log("Run as second time");
+  console.log("====================");
+
+  const apiKey = getTestApiKey();
+  const agentBay = new AgentBay({ apiKey });
+
+  // Create second session with same browser context and fingerprint context
+  console.log(`Creating second session with same browser context ID: ${persistentContext.id} ` +
+              `and fingerprint context ID: ${persistentFingerprintContext.id}`);
+  
+  const fingerprintContext = new BrowserFingerprintContext(persistentFingerprintContext.id);
+  const browserContext = new BrowserContext(persistentContext.id, true, undefined, fingerprintContext);
+
+  const params = new CreateSessionParams()
+    .withImageId("browser_latest")
+    .withBrowserContext(browserContext);
+
+  const sessionResult = await agentBay.create(params);
+  if (!sessionResult.success || !sessionResult.session) {
+    console.log(`Failed to create second session: ${sessionResult.errorMessage}`);
+    return;
+  }
+
+  const session = sessionResult.session;
+  console.log(`Second session created with ID: ${session.sessionId}`);
+
+  // Get browser object and check if second session fingerprint is the same as first session
+  async function secondSessionOperations(): Promise<void> {
+    // Initialize browser with fingerprint persistent enabled but not specific fingerprint generation options
+    const browserOption: BrowserOption = {
+      useStealth: true,
+      fingerprintPersistent: true
+    };
+
+    const initSuccess = await session.browser.initializeAsync(browserOption);
+    if (!initSuccess) {
+      console.log("Failed to initialize browser in second session");
+      return;
+    }
+    console.log("Second session browser initialized successfully");
+
+    // Get endpoint URL
+    const endpointUrl = await session.browser.getEndpointUrl();
+    if (!endpointUrl) {
+      console.log("Failed to get browser endpoint URL in second session");
+      return;
+    }
+    console.log(`Second session browser endpoint URL: ${endpointUrl}`);
+
+    // Connect with playwright and test second session fingerprint
+    const browser = await chromium.connectOverCDP(endpointUrl);
+    const context = browser.contexts().length > 0 ? browser.contexts()[0] : await browser.newContext();
+    const page = await context.newPage();
+    await page.goto("https://httpbin.org/user-agent", { timeout: 60000 });
+    const response = await page.evaluate(() => JSON.parse(document.body.textContent));
+    const userAgent = response["user-agent"];
+    console.log("user_agent =", userAgent);
+    
+    const isWindows = isWindowsUserAgent(userAgent);
+    if (!isWindows) {
+      console.log("Failed to get windows user agent in second session");
+      return;
+    }
+    console.log("SUCCESS: fingerprint persisted correctly!");
+
+    await context.close();
+    console.log("Second session browser fingerprint check completed");
+  }
+
+  // Run second session operations
+  await secondSessionOperations();
+
+  // Delete second session with syncContext=true
+  console.log("Deleting second session with syncContext=true...");
+  const deleteResult = await agentBay.delete(session, { syncContext: true });
+  console.log(`Second session deleted successfully (RequestID: ${deleteResult.requestId})`);
+}
+
+async function main(): Promise<void> {
+  /**
+   * Test browser fingerprint persist across sessions with the same browser and fingerprint context.
+   */
+  try {
+    await runAsFirstTime();
+    await new Promise(resolve => setTimeout(resolve, 3000)); // Wait 3 seconds
+    await runAsSecondTime();
+  } catch (error) {
+    console.error("Error in main function:", error);
+  }
+}
+
+if (require.main === module) {
+  main().catch(console.error);
+}

package/docs/examples/browser-use/browser/browser-proxies.ts

@@ -0,0 +1,149 @@
+/**
+ * Example demonstrating Browser Proxy configuration with AgentBay SDK.
+ *
+ * This example shows how to use proxy functionality with AgentBay SDK. 
+ * AgentBay supports two types of proxies:
+ *
+ * 1. Custom Proxy:
+ *    - Uses user-provided proxy servers
+ *    - Supports HTTP/HTTPS/SOCKS proxies
+ *    - Optionally provides username and password for authentication
+ *
+ * 2. Wuying Proxy:
+ *    - Uses Alibaba Cloud Wuying proxy service
+ *    - Supports two strategies:
+ *      * restricted: Uses fixed proxy nodes
+ *      * polling: Rotates through proxy pool nodes
+ *
+ * This example demonstrates:
+ * - Create AIBrowser session with proxy configuration
+ * - Use playwright to connect to AIBrowser instance through CDP protocol
+ * - Verify the proxy's public IP address
+ */
+
+// @ts-nocheck
+import { AgentBay, CreateSessionParams } from 'wuying-agentbay-sdk';
+import { BrowserOption, BrowserProxy } from 'wuying-agentbay-sdk';
+import { chromium } from 'playwright';
+
+interface IpResponse {
+    origin: string;
+}
+
+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: '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}`);
+
+        // ==================== Proxy Configuration Examples ====================
+        
+        // Example 1: Custom Proxy Configuration
+        // Suitable for users who have their own proxy servers
+        // const browserProxy: BrowserProxy = {
+        //     type: 'custom',
+        //     server: 'http://127.0.0.1:9090',
+        //     username: 'username',
+        //     password: 'password',
+        //     toMap: function() {
+        //         return {
+        //             type: this.type,
+        //             server: this.server,
+        //             username: this.username,
+        //             password: this.password
+        //         };
+        //     }
+        // };
+
+        // Example 2: Wuying Proxy - Polling Strategy
+        // Rotates through proxy pool nodes, suitable for scenarios requiring frequent IP switching
+        const browserProxy: BrowserProxy = {
+            type: 'wuying',
+            strategy: 'polling',
+            pollsize: 2,
+            toMap: function() {
+                return {
+                    type: this.type,
+                    strategy: this.strategy,
+                    pollsize: this.pollsize
+                };
+            }
+        };
+
+        // Example 3: Wuying Proxy - Restricted Strategy
+        // Uses fixed proxy nodes, suitable for scenarios requiring stable IP
+        // const browserProxy: BrowserProxy = {
+        //     type: 'wuying',
+        //     strategy: 'restricted',
+        //     toMap: function() {
+        //         return {
+        //             type: this.type,
+        //             strategy: this.strategy
+        //         };
+        //     }
+        // };
+
+        // Create browser option with proxy configuration, now only support one proxy
+        const browserOption: BrowserOption = {
+            proxies: [browserProxy]
+        };
+
+        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];
+            const page = await context.newPage();
+
+            try {
+                // ==================== Verify Proxy IP ====================
+                console.log('\n--- Check proxy public IP start ---');
+                await page.goto('https://httpbin.org/ip');
+
+                const response = await page.evaluate((): IpResponse => {
+                    return JSON.parse(document.body.textContent || '{}');
+                });
+                const publicIp = response.origin || '';
+                console.log('proxy public IP:', publicIp);
+                console.log('--- Check proxy public IP end ---');
+
+                await page.waitForTimeout(3000);
+            } finally {
+                await browser.close();
+            }
+        }
+
+        // Clean up session
+        await agentBay.delete(session);
+    } catch (error) {
+        console.error('Error:', error);
+    }
+}
+
+if (require.main === module) {
+    main().catch(console.error);
+}

package/docs/examples/browser-use/browser/browser-type-example.ts

@@ -0,0 +1,266 @@
+// @ts-nocheck
+/**
+ * Browser Type Selection Example
+ *
+ * This example demonstrates how to select between Chrome and Chromium browsers
+ * when using computer use images in AgentBay.
+ *
+ * Features demonstrated:
+ * - Chrome browser selection
+ * - Chromium browser selection
+ * - Default browser (undefined)
+ * - Browser type verification
+ * - Configuration comparison
+ *
+ * Note: The browserType option is only available for computer use images.
+ */
+
+import { AgentBay, CreateSessionParams, BrowserOption } from 'wuying-agentbay-sdk';
+import { chromium } from 'playwright';
+
+/**
+ * Test a specific browser type configuration
+ */
+async function testBrowserType(
+  browserType: 'chrome' | 'chromium' | undefined,
+  description: string
+): Promise<void> {
+  console.log('\n' + '='.repeat(60));
+  console.log(`Testing: ${description}`);
+  console.log('='.repeat(60));
+
+  const apiKey = process.env.AGENTBAY_API_KEY;
+  if (!apiKey) {
+    throw new Error('AGENTBAY_API_KEY environment variable not set');
+  }
+
+  const agentBay = new AgentBay({ apiKey });
+
+  // Create session with computer use image
+  console.log('\n1. Creating session with computer use image...');
+  const params: 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;
+  console.log(`   ✓ Session created: ${session.getSessionId()}`);
+
+  try {
+    // Initialize browser with specified type
+    console.log(`\n2. Initializing browser with type: ${browserType || 'default (undefined)'}...`);
+    
+    // Using plain object (recommended)
+    const option: BrowserOption = {
+      browserType: browserType,
+      viewport: { width: 1920, height: 1080 }
+    };
+
+    const success = await session.browser.initializeAsync(option);
+    if (!success) {
+      throw new Error('Browser initialization failed');
+    }
+
+    console.log('   ✓ Browser initialized successfully');
+
+    // Get endpoint URL
+    const endpointUrl = session.browser.getEndpointUrl();
+    console.log(`\n3. CDP endpoint: ${String(endpointUrl).substring(0, 50)}...`);
+
+    // Connect Playwright and verify browser
+    console.log('\n4. Connecting to browser via CDP...');
+    const browser = await chromium.connectOverCDP(endpointUrl);
+    const context = browser.contexts()[0];
+    const page = await context.newPage();
+
+    console.log('   ✓ Connected successfully');
+    console.log('\n5. Verifying browser configuration...');
+
+    // Navigate to a page that shows browser info
+    await page.goto('https://www.whatismybrowser.com/');
+    await page.waitForLoadState('networkidle');
+
+    // Get browser information
+    const userAgent = await page.evaluate(() => (navigator as any).userAgent);
+    const viewportWidth = await page.evaluate(() => (window as any).innerWidth);
+    const viewportHeight = await page.evaluate(() => (window as any).innerHeight);
+
+    console.log('\n   Browser Information:');
+    console.log(`   - User Agent: ${userAgent.substring(0, 80)}...`);
+    console.log(`   - Viewport: ${viewportWidth} x ${viewportHeight}`);
+    console.log(`   - Configured Type: ${browserType || 'default'}`);
+
+    // Check if Chrome or Chromium is in user agent
+    if (userAgent.includes('Chrome')) {
+      const detected = userAgent.includes('Chromium') ? 'Chromium' : 'Chrome';
+      console.log(`   - Detected Browser: ${detected}`);
+    }
+
+    await browser.close();
+
+    console.log(`\n   ✓ Test completed successfully for ${description}`);
+
+  } finally {
+    console.log('\n6. Cleaning up...');
+    session.delete();
+    console.log('   ✓ Session deleted');
+  }
+}
+
+/**
+ * Main function to run all browser type examples
+ */
+async function main(): Promise<void> {
+  console.log('Browser Type Selection Example');
+  console.log('='.repeat(60));
+  console.log('\nThis example demonstrates browser type selection in AgentBay.');
+  console.log('Note: browserType is only available for computer use images.');
+
+  // Test 1: Chrome browser
+  await testBrowserType('chrome', 'Chrome Browser (Google Chrome)');
+
+  await new Promise(resolve => setTimeout(resolve, 2000)); // Brief pause
+
+  // Test 2: Chromium browser
+  await testBrowserType('chromium', 'Chromium Browser (Open Source)');
+
+  await new Promise(resolve => setTimeout(resolve, 2000)); // Brief pause
+
+  // Test 3: Default (undefined)
+  await testBrowserType(undefined, 'Default Browser (Platform decides)');
+
+  console.log('\n' + '='.repeat(60));
+  console.log('All browser type tests completed successfully!');
+  console.log('='.repeat(60));
+
+  // Summary
+  console.log('\nSummary:');
+  console.log('- Chrome: Use when you need Google Chrome specific features');
+  console.log('- Chromium: Use for open-source, lighter resource usage');
+  console.log('- Default (undefined): Let the platform choose the optimal browser');
+  console.log('\nBest Practice: Use undefined unless you have a specific requirement');
+}
+
+/**
+ * Quick example showing the most common usage
+ */
+async function quickExample(): Promise<void> {
+  console.log('\n' + '='.repeat(60));
+  console.log('Quick Example: Using Chrome Browser');
+  console.log('='.repeat(60));
+
+  const apiKey = process.env.AGENTBAY_API_KEY;
+  if (!apiKey) {
+    throw new Error('AGENTBAY_API_KEY not set');
+  }
+
+  const agentBay = new AgentBay({ apiKey });
+
+  // Create session
+  const params: 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;
+
+  try {
+    // Simply specify browserType in BrowserOption
+    const option: BrowserOption = {
+      browserType: 'chrome'
+    };
+
+    const success = await session.browser.initializeAsync(option);
+
+    if (success) {
+      console.log('✓ Chrome browser initialized successfully');
+
+      // Get endpoint and use with Playwright
+      const endpointUrl = session.browser.getEndpointUrl();
+      const browser = await chromium.connectOverCDP(endpointUrl);
+      const page = await browser.contexts()[0].newPage();
+
+      await page.goto('https://example.com');
+      const title = await page.title();
+      console.log(`✓ Page title: ${title}`);
+
+      await browser.close();
+    }
+  } finally {
+    session.delete();
+  }
+}
+
+/**
+ * Type-safe example showing all options
+ */
+async function typeSafeExample(): Promise<void> {
+  console.log('\n' + '='.repeat(60));
+  console.log('Type-Safe Example: Using TypeScript Types');
+  console.log('='.repeat(60));
+
+  const apiKey = process.env.AGENTBAY_API_KEY;
+  if (!apiKey) {
+    throw new Error('AGENTBAY_API_KEY not set');
+  }
+
+  const agentBay = new AgentBay({ apiKey });
+  const params: 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;
+
+  try {
+    // TypeScript ensures type safety
+    const browserTypes: Array<'chrome' | 'chromium' | undefined> = [
+      'chrome',
+      'chromium',
+      undefined
+    ];
+
+    for (const type of browserTypes) {
+      console.log(`\nTesting with type: ${type || 'undefined'}`);
+      
+      // Type-safe option creation
+      const option: BrowserOption = {
+        browserType: type,
+        viewport: { width: 1920, height: 1080 }
+      };
+
+      const success = await session.browser.initializeAsync(option);
+      console.log(`  ✓ Initialization: ${success ? 'Success' : 'Failed'}`);
+
+      if (success) {
+        // Verify configuration
+        const currentOption = session.browser.getOption();
+        if (currentOption) {
+          console.log(`  ✓ Configured type: ${currentOption.browserType || 'undefined'}`);
+        }
+      }
+
+      // Brief pause between iterations
+      await new Promise(resolve => setTimeout(resolve, 1000));
+    }
+
+    console.log('\n✓ Type-safe example completed');
+
+  } finally {
+    session.delete();
+  }
+}
+
+// Run the main example
+main()
+  .then(() => process.exit(0))
+  .catch(error => {
+    console.error('Error:', error.message);
+    process.exit(1);
+  });
+