@crawlee/stagehand 3.15.4-beta.39

package/internals/stagehand-controller.js

@@ -0,0 +1,146 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StagehandController = void 0;
+const tslib_1 = require("tslib");
+const browser_pool_1 = require("@crawlee/browser-pool");
+const log_1 = tslib_1.__importDefault(require("@apify/log"));
+/**
+ * StagehandController manages the lifecycle of a Stagehand-controlled browser for Crawlee's BrowserPool.
+ *
+ * This controller bridges Crawlee's browser management system with Stagehand:
+ * - Created by StagehandPlugin when a new browser is needed
+ * - Provides page creation via Playwright (connected to Stagehand's browser via CDP)
+ * - Exposes the Stagehand instance so crawling context can access AI methods (act/extract/observe)
+ * - Handles browser cleanup by delegating to Stagehand's close method
+ *
+ * Proxy authentication is handled transparently via anonymizeProxy in the plugin layer.
+ *
+ * @ignore
+ */
+class StagehandController extends browser_pool_1.BrowserController {
+    constructor(browserPlugin, stagehandInstances) {
+        super(browserPlugin);
+        Object.defineProperty(this, "stagehand", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "stagehandInstances", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.stagehandInstances = stagehandInstances;
+    }
+    /**
+     * Gets the Stagehand instance associated with this controller's browser.
+     */
+    getStagehand() {
+        if (!this.stagehand) {
+            this.stagehand = this.stagehandInstances.get(this.browser);
+            if (!this.stagehand) {
+                throw new Error('Stagehand instance not found for browser');
+            }
+        }
+        return this.stagehand;
+    }
+    /**
+     * Creates a new page using the browser's default context.
+     * We use Playwright's browser API directly since we connected via CDP.
+     */
+    async _newPage(_contextOptions) {
+        try {
+            // Get the default context from the Playwright browser (connected via CDP)
+            const contexts = this.browser.contexts();
+            if (contexts.length === 0) {
+                throw new Error('No browser context available');
+            }
+            const context = contexts[0];
+            const page = await context.newPage();
+            // Track active pages
+            page.once('close', () => {
+                this.activePages--;
+            });
+            return page;
+        }
+        catch (error) {
+            throw new Error(`Failed to create new page: ${error instanceof Error ? error.message : String(error)}`, {
+                cause: error,
+            });
+        }
+    }
+    /**
+     * Normalizes proxy options for Playwright.
+     */
+    normalizeProxyOptions(proxyUrl, pageOptions) {
+        if (!proxyUrl) {
+            return {};
+        }
+        const url = new URL(proxyUrl);
+        const username = decodeURIComponent(url.username);
+        const password = decodeURIComponent(url.password);
+        return {
+            proxy: {
+                server: url.origin,
+                username,
+                password,
+                bypass: pageOptions?.proxy?.bypass,
+            },
+        };
+    }
+    /**
+     * Sets cookies in the browser context.
+     * Uses Playwright's browser context API directly.
+     */
+    async _setCookies(page, cookies) {
+        try {
+            const context = page.context();
+            await context.addCookies(cookies);
+        }
+        catch {
+            // Silently skip if not supported
+        }
+    }
+    /**
+     * Gets cookies from the browser context.
+     * Uses Playwright's browser context API directly.
+     */
+    async _getCookies(page) {
+        try {
+            const context = page.context();
+            const cookies = await context.cookies();
+            return cookies;
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Closes the browser and cleans up Stagehand resources.
+     */
+    async _close() {
+        const stagehand = this.getStagehand();
+        try {
+            await stagehand.close();
+        }
+        catch (error) {
+            log_1.default.error('Error closing Stagehand', { error });
+        }
+    }
+    /**
+     * Kills the browser process forcefully.
+     */
+    async _kill() {
+        const stagehand = this.getStagehand();
+        try {
+            await stagehand.close({ force: true });
+        }
+        catch {
+            // Ignore errors during force close
+        }
+    }
+}
+exports.StagehandController = StagehandController;
+//# sourceMappingURL=stagehand-controller.js.map

package/internals/stagehand-controller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stagehand-controller.js","sourceRoot":"","sources":["../../src/internals/stagehand-controller.ts"],"names":[],"mappings":"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"}

package/internals/stagehand-crawler.d.ts

@@ -0,0 +1,419 @@
+import type { Action, ActOptions, ActResult, AgentConfig, ExtractOptions, LLMClient, ModelConfiguration, NonStreamingAgentInstance, ObserveOptions, Stagehand, StreamingAgentInstance } from '@browserbasehq/stagehand';
+import type { BrowserCrawlerOptions, BrowserCrawlingContext, BrowserHook, BrowserRequestHandler, GetUserDataFromRequest, LoadedContext, RouterRoutes } from '@crawlee/browser';
+import { BrowserCrawler, Configuration } from '@crawlee/browser';
+import type { Dictionary } from '@crawlee/types';
+import type { LaunchOptions, Page, Response } from 'playwright';
+import type { z } from 'zod';
+import type { StagehandController } from './stagehand-controller';
+import type { StagehandLaunchContext } from './stagehand-launcher';
+import type { StagehandPlugin } from './stagehand-plugin';
+/**
+ * Stagehand-specific configuration options.
+ */
+export interface StagehandOptions {
+    /**
+     * Environment to run Stagehand in.
+     * - `'LOCAL'`: Use local browser (default)
+     * - `'BROWSERBASE'`: Use Browserbase cloud browsers
+     * @default 'LOCAL'
+     */
+    env?: 'LOCAL' | 'BROWSERBASE';
+    /**
+     * API key - interpreted based on the `env` setting:
+     * - When `env: 'LOCAL'`: LLM provider API key (OpenAI, Anthropic, or Google)
+     * - When `env: 'BROWSERBASE'`: Browserbase API key
+     *
+     * For LOCAL env, can also be set via environment variables:
+     * - OpenAI: `OPENAI_API_KEY`
+     * - Anthropic: `ANTHROPIC_API_KEY`
+     * - Google: `GOOGLE_API_KEY`
+     *
+     * @example
+     * ```typescript
+     * // Local with OpenAI
+     * stagehandOptions: {
+     *   env: 'LOCAL',
+     *   model: 'openai/gpt-4.1-mini',
+     *   apiKey: 'sk-...',
+     * }
+     *
+     * // Browserbase cloud
+     * stagehandOptions: {
+     *   env: 'BROWSERBASE',
+     *   apiKey: 'bb-...',
+     *   projectId: 'proj-...',
+     * }
+     * ```
+     */
+    apiKey?: string;
+    /**
+     * Browserbase project ID (required when env is 'BROWSERBASE').
+     */
+    projectId?: string;
+    /**
+     * AI model to use for act(), extract(), observe() operations.
+     * Can be a string like "openai/gpt-4.1-mini" or a detailed ModelConfiguration object.
+     * @default 'openai/gpt-4.1-mini'
+     * @example "openai/gpt-4.1-mini"
+     * @example "anthropic/claude-sonnet-4-20250514"
+     */
+    model?: ModelConfiguration;
+    /**
+     * Logging verbosity level.
+     * - 0: Minimal logging
+     * - 1: Standard logging
+     * - 2: Debug logging
+     * @default 0
+     */
+    verbose?: 0 | 1 | 2;
+    /**
+     * Enable automatic error recovery for failed AI operations.
+     * @default true
+     */
+    selfHeal?: boolean;
+    /**
+     * Time to wait for DOM to stabilize before performing AI operations (ms).
+     * @default 30000
+     */
+    domSettleTimeout?: number;
+    /**
+     * Custom LLM client for AI operations.
+     */
+    llmClient?: LLMClient;
+    /**
+     * Custom system prompt for AI operations.
+     */
+    systemPrompt?: string;
+    /**
+     * Enable logging of AI inference details to file for debugging.
+     * @default false
+     */
+    logInferenceToFile?: boolean;
+    /**
+     * Cache directory for observation caching to improve performance.
+     */
+    cacheDir?: string;
+}
+/**
+ * Enhanced Playwright Page with Stagehand AI methods.
+ */
+export interface StagehandPage extends Page {
+    /**
+     * Perform an action on the page using natural language.
+     *
+     * @param instruction - Natural language instruction for the action
+     * @param options - Optional configuration for the action
+     * @returns Promise that resolves with the action result
+     *
+     * @example
+     * ```typescript
+     * await page.act('Click the login button');
+     * await page.act('Fill in email with test@example.com');
+     * await page.act('Scroll down to load more items');
+     * ```
+     */
+    act(instruction: string, options?: Omit<ActOptions, 'page'>): Promise<ActResult>;
+    /**
+     * Extract structured data from the page using natural language and a Zod schema.
+     *
+     * @param instruction - Natural language description of what to extract
+     * @param schema - Zod schema defining the structure of the data
+     * @param options - Optional configuration for the extraction
+     * @returns Promise that resolves with the extracted data matching the schema
+     *
+     * @example
+     * ```typescript
+     * const data = await page.extract(
+     *   'Get product title and price',
+     *   z.object({
+     *     title: z.string(),
+     *     price: z.number(),
+     *   })
+     * );
+     * ```
+     */
+    extract<T>(instruction: string, schema: z.ZodSchema<T>, options?: Omit<ExtractOptions, 'page'>): Promise<T>;
+    /**
+     * Observe the page and get AI-suggested actions.
+     *
+     * @param options - Optional configuration for the observation
+     * @returns Promise that resolves with available actions on the page
+     *
+     * @example
+     * ```typescript
+     * const suggestions = await page.observe();
+     * console.log('Available actions:', suggestions);
+     * ```
+     */
+    observe(options?: Omit<ObserveOptions, 'page'>): Promise<Action[]>;
+    /**
+     * Create an autonomous agent for multi-step workflows.
+     *
+     * @param config - Configuration for the agent
+     * @returns Agent instance that can execute complex workflows
+     *
+     * @example
+     * ```typescript
+     * const agent = page.agent({ task: 'Find and add cheapest laptop to cart' });
+     * await agent.execute();
+     * ```
+     */
+    agent(config: AgentConfig & {
+        stream: true;
+    }): StreamingAgentInstance;
+    agent(config?: AgentConfig & {
+        stream?: false;
+    }): NonStreamingAgentInstance;
+}
+/**
+ * Crawling context for StagehandCrawler with enhanced page object.
+ */
+export interface StagehandCrawlingContext<UserData extends Dictionary = Dictionary> extends BrowserCrawlingContext<StagehandCrawler, StagehandPage, Response, StagehandController, UserData> {
+    /**
+     * Enhanced Playwright page with Stagehand AI methods.
+     * Use page.act(), page.extract(), page.observe(), page.agent() for AI-powered operations.
+     */
+    page: StagehandPage;
+    /**
+     * Stagehand instance for advanced control.
+     * Usually you don't need to access this directly - use the enhanced page methods instead.
+     */
+    stagehand: Stagehand;
+}
+/**
+ * Hook function for StagehandCrawler.
+ */
+export interface StagehandHook extends BrowserHook<StagehandCrawlingContext, StagehandGotoOptions> {
+}
+/**
+ * Request handler for StagehandCrawler.
+ */
+export interface StagehandRequestHandler extends BrowserRequestHandler<LoadedContext<StagehandCrawlingContext>> {
+}
+/**
+ * Goto options for StagehandCrawler navigation.
+ */
+export type StagehandGotoOptions = Dictionary & Parameters<Page['goto']>[1];
+/**
+ * Options for StagehandCrawler.
+ */
+export interface StagehandCrawlerOptions extends BrowserCrawlerOptions<StagehandCrawlingContext, {
+    browserPlugins: [StagehandPlugin];
+}> {
+    /**
+     * Stagehand-specific configuration options.
+     * These options configure the AI behavior and Browserbase integration.
+     */
+    stagehandOptions?: StagehandOptions;
+    /**
+     * Launch context with Stagehand-specific options.
+     */
+    launchContext?: StagehandLaunchContext;
+    /**
+     * Function that is called to process each request.
+     *
+     * The function receives the {@apilink StagehandCrawlingContext} as an argument, where:
+     * - `request` is an instance of the {@apilink Request} object with details about the URL to open, HTTP method etc.
+     * - `page` is an enhanced Playwright [`Page`](https://playwright.dev/docs/api/class-page) with AI methods
+     * - `browserController` is an instance of {@apilink StagehandController}
+     * - `response` is the main resource response as returned by `page.goto(request.url)`
+     * - `stagehand` is the Stagehand instance for advanced control
+     *
+     * The page object is enhanced with AI-powered methods:
+     * - `page.act(instruction)` - Perform actions using natural language
+     * - `page.extract(instruction, schema)` - Extract structured data
+     * - `page.observe()` - Get AI-suggested actions
+     * - `page.agent(config)` - Create autonomous agents
+     *
+     * The function must return a promise, which is then awaited by the crawler.
+     *
+     * If the function throws an exception, the crawler will try to re-crawl the
+     * request later, up to `option.maxRequestRetries` times.
+     *
+     * @example
+     * ```typescript
+     * async requestHandler({ request, page, log }) {
+     *   log.info(`Processing ${request.url}`);
+     *
+     *   // Use AI-powered actions
+     *   await page.act('Click the Products menu');
+     *
+     *   // Extract structured data
+     *   const products = await page.extract(
+     *     'Get all products',
+     *     z.object({
+     *       items: z.array(z.object({
+     *         name: z.string(),
+     *         price: z.number(),
+     *       })),
+     *     })
+     *   );
+     *
+     *   // Mix with standard Playwright methods
+     *   await page.screenshot({ path: 'products.png' });
+     * }
+     * ```
+     */
+    requestHandler?: StagehandRequestHandler;
+    /**
+     * Function called when request handling fails after all retries.
+     */
+    failedRequestHandler?: StagehandRequestHandler;
+    /**
+     * Async functions that are sequentially evaluated before the navigation.
+     */
+    preNavigationHooks?: StagehandHook[];
+    /**
+     * Async functions that are sequentially evaluated after the navigation.
+     */
+    postNavigationHooks?: StagehandHook[];
+}
+/**
+ * StagehandCrawler provides AI-powered web crawling using Browserbase's Stagehand library.
+ *
+ * It extends {@apilink BrowserCrawler} and adds natural language interaction capabilities:
+ * - `page.act()` - Perform actions using natural language
+ * - `page.extract()` - Extract structured data with AI
+ * - `page.observe()` - Get AI-suggested actions
+ * - `page.agent()` - Create autonomous agents for complex workflows
+ *
+ * The crawler automatically applies anti-blocking features including browser fingerprinting,
+ * making it suitable for crawling sites with bot protection like Cloudflare.
+ *
+ * @example
+ * ```typescript
+ * import { StagehandCrawler } from '@crawlee/stagehand';
+ * import { z } from 'zod';
+ *
+ * const crawler = new StagehandCrawler({
+ *   stagehandOptions: {
+ *     env: 'LOCAL',
+ *     model: 'openai/gpt-4.1-mini',
+ *     verbose: 1,
+ *   },
+ *   maxConcurrency: 3,
+ *   async requestHandler({ page, request, log }) {
+ *     log.info(`Crawling ${request.url}`);
+ *
+ *     // Use AI to interact with the page
+ *     await page.act('Click the Products link');
+ *     await page.act('Scroll to load more items');
+ *
+ *     // Extract structured data
+ *     const products = await page.extract(
+ *       'Get all product names and prices',
+ *       z.object({
+ *         items: z.array(z.object({
+ *           name: z.string(),
+ *           price: z.number(),
+ *         })),
+ *       })
+ *     );
+ *
+ *     log.info(`Found ${products.items.length} products`);
+ *   },
+ * });
+ *
+ * await crawler.run(['https://example.com']);
+ * ```
+ */
+export declare class StagehandCrawler extends BrowserCrawler<{
+    browserPlugins: [StagehandPlugin];
+}, LaunchOptions, StagehandCrawlingContext> {
+    readonly config: Configuration;
+    protected static optionsShape: {
+        stagehandOptions: import("ow").ObjectPredicate<object> & import("ow").BasePredicate<object | undefined>;
+        browserPoolOptions: import("ow").ObjectPredicate<object> & import("ow").BasePredicate<object | undefined>;
+        handlePageFunction: import("ow").Predicate<Function> & import("ow").BasePredicate<Function | undefined>;
+        navigationTimeoutSecs: import("ow").NumberPredicate & import("ow").BasePredicate<number | undefined>;
+        preNavigationHooks: import("ow").ArrayPredicate<unknown> & import("ow").BasePredicate<unknown[] | undefined>;
+        postNavigationHooks: import("ow").ArrayPredicate<unknown> & import("ow").BasePredicate<unknown[] | undefined>;
+        launchContext: import("ow").ObjectPredicate<object> & import("ow").BasePredicate<object | undefined>;
+        headless: import("ow").AnyPredicate<string | boolean>;
+        sessionPoolOptions: import("ow").ObjectPredicate<object> & import("ow").BasePredicate<object | undefined>;
+        persistCookiesPerSession: import("ow").BooleanPredicate & import("ow").BasePredicate<boolean | undefined>;
+        useSessionPool: import("ow").BooleanPredicate & import("ow").BasePredicate<boolean | undefined>;
+        proxyConfiguration: import("ow").ObjectPredicate<object> & import("ow").BasePredicate<object | undefined>;
+        ignoreShadowRoots: import("ow").BooleanPredicate & import("ow").BasePredicate<boolean | undefined>;
+        ignoreIframes: import("ow").BooleanPredicate & import("ow").BasePredicate<boolean | undefined>;
+        requestList: import("ow").ObjectPredicate<object> & import("ow").BasePredicate<object | undefined>;
+        requestQueue: import("ow").ObjectPredicate<object> & import("ow").BasePredicate<object | undefined>;
+        requestHandler: import("ow").Predicate<Function> & import("ow").BasePredicate<Function | undefined>;
+        handleRequestFunction: import("ow").Predicate<Function> & import("ow").BasePredicate<Function | undefined>;
+        requestHandlerTimeoutSecs: import("ow").NumberPredicate & import("ow").BasePredicate<number | undefined>;
+        handleRequestTimeoutSecs: import("ow").NumberPredicate & import("ow").BasePredicate<number | undefined>;
+        errorHandler: import("ow").Predicate<Function> & import("ow").BasePredicate<Function | undefined>;
+        failedRequestHandler: import("ow").Predicate<Function> & import("ow").BasePredicate<Function | undefined>;
+        handleFailedRequestFunction: import("ow").Predicate<Function> & import("ow").BasePredicate<Function | undefined>;
+        maxRequestRetries: import("ow").NumberPredicate & import("ow").BasePredicate<number | undefined>;
+        sameDomainDelaySecs: import("ow").NumberPredicate & import("ow").BasePredicate<number | undefined>;
+        maxSessionRotations: import("ow").NumberPredicate & import("ow").BasePredicate<number | undefined>;
+        maxRequestsPerCrawl: import("ow").NumberPredicate & import("ow").BasePredicate<number | undefined>;
+        maxCrawlDepth: import("ow").NumberPredicate & import("ow").BasePredicate<number | undefined>;
+        autoscaledPoolOptions: import("ow").ObjectPredicate<object> & import("ow").BasePredicate<object | undefined>;
+        statusMessageLoggingInterval: import("ow").NumberPredicate & import("ow").BasePredicate<number | undefined>;
+        statusMessageCallback: import("ow").Predicate<Function> & import("ow").BasePredicate<Function | undefined>;
+        retryOnBlocked: import("ow").BooleanPredicate & import("ow").BasePredicate<boolean | undefined>;
+        respectRobotsTxtFile: import("ow").AnyPredicate<boolean | object>;
+        onSkippedRequest: import("ow").Predicate<Function> & import("ow").BasePredicate<Function | undefined>;
+        httpClient: import("ow").ObjectPredicate<object> & import("ow").BasePredicate<object | undefined>;
+        minConcurrency: import("ow").NumberPredicate & import("ow").BasePredicate<number | undefined>;
+        maxConcurrency: import("ow").NumberPredicate & import("ow").BasePredicate<number | undefined>;
+        maxRequestsPerMinute: import("ow").NumberPredicate & import("ow").BasePredicate<number | undefined>;
+        keepAlive: import("ow").BooleanPredicate & import("ow").BasePredicate<boolean | undefined>;
+        log: import("ow").ObjectPredicate<object> & import("ow").BasePredicate<object | undefined>;
+        experiments: import("ow").ObjectPredicate<object> & import("ow").BasePredicate<object | undefined>;
+        statisticsOptions: import("ow").ObjectPredicate<object> & import("ow").BasePredicate<object | undefined>;
+    };
+    /**
+     * Creates a new instance of StagehandCrawler.
+     *
+     * @param options - Crawler configuration options
+     */
+    constructor(options?: StagehandCrawlerOptions, config?: Configuration);
+    /**
+     * Overrides the request handler to enhance the page with Stagehand AI methods.
+     *
+     * The pattern here is:
+     * 1. Store the original userProvidedRequestHandler
+     * 2. Replace it with a wrapper that enhances the page first
+     * 3. Call super (which creates page/browserController, then calls our wrapper)
+     * 4. Our wrapper enhances the page and calls the original handler
+     * 5. Restore the original handler
+     *
+     * This is similar to how PlaywrightCrawler adds utility methods via registerUtilsToContext,
+     * but we need to actually transform the page object to add Stagehand AI methods.
+     */
+    protected _runRequestHandler(crawlingContext: StagehandCrawlingContext): Promise<void>;
+    /**
+     * Navigation handler for Stagehand crawler.
+     * Uses standard Playwright navigation.
+     */
+    protected _navigationHandler(crawlingContext: StagehandCrawlingContext, gotoOptions: StagehandGotoOptions): Promise<Response | null>;
+}
+/**
+ * Creates a new router for StagehandCrawler with type-safe route handlers.
+ *
+ * @param options - Router options
+ * @returns Configured router instance
+ *
+ * @example
+ * ```typescript
+ * const router = createStagehandRouter();
+ *
+ * router.addHandler('product', async ({ page, request, log }) => {
+ *   log.info(`Processing product: ${request.url}`);
+ *   const data = await page.extract('Get product info', schema);
+ * });
+ *
+ * router.addDefaultHandler(async ({ page, enqueueLinks }) => {
+ *   await enqueueLinks({ globs: ['https://example.com/products/*'] });
+ * });
+ *
+ * const crawler = new StagehandCrawler({
+ *   requestHandler: router,
+ * });
+ * ```
+ */
+export declare function createStagehandRouter<Context extends StagehandCrawlingContext = StagehandCrawlingContext, UserData extends Dictionary = GetUserDataFromRequest<Context['request']>>(routes?: RouterRoutes<Context, UserData>): import("@crawlee/browser").RouterHandler<Context>;
+//# sourceMappingURL=stagehand-crawler.d.ts.map

package/internals/stagehand-crawler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stagehand-crawler.d.ts","sourceRoot":"","sources":["../../src/internals/stagehand-crawler.ts"],"names":[],"mappings":"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"}