@crawlee/stagehand 3.15.4-beta.39

package/internals/utils/stagehand-utils.js

@@ -0,0 +1,120 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.enhancePageWithStagehand = enhancePageWithStagehand;
+const PROVIDER_ENV_VARS = {
+    OpenAI: 'OPENAI_API_KEY',
+    Anthropic: 'ANTHROPIC_API_KEY',
+    Google: 'GOOGLE_API_KEY',
+};
+/**
+ * Improves error messages for common Stagehand errors.
+ * Replaces confusing Stagehand API key error messages with ones that reference our options.
+ */
+function improveErrorMessage(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    // Improve API key error messages to reference our options
+    if (message.includes('API key is missing')) {
+        let provider = 'LLM provider';
+        for (const name of Object.keys(PROVIDER_ENV_VARS)) {
+            if (message.includes(name)) {
+                provider = name;
+                break;
+            }
+        }
+        const envVar = PROVIDER_ENV_VARS[provider] ?? '<PROVIDER>_API_KEY';
+        return `${provider} API key is missing. Pass it via 'stagehandOptions.apiKey' or set the ${envVar} environment variable.`;
+    }
+    return message;
+}
+/**
+ * Enhances a Playwright Page with Stagehand AI methods.
+ * Adds page.act(), page.extract(), page.observe(), and page.agent() methods.
+ *
+ * The key feature is that each AI method passes the specific page to Stagehand,
+ * allowing multiple pages to use AI operations concurrently without interference.
+ *
+ * @param page - The Playwright page to enhance
+ * @param stagehand - The Stagehand instance to bind methods from
+ * @returns The enhanced page with AI methods
+ *
+ * @example
+ * ```typescript
+ * const enhancedPage = enhancePageWithStagehand(page, stagehand);
+ * await enhancedPage.act('Click the button');
+ * const data = await enhancedPage.extract('Get title', schema);
+ * ```
+ *
+ * @ignore
+ */
+function enhancePageWithStagehand(page, stagehand) {
+    // Cast to StagehandPage to add properties
+    const enhancedPage = page;
+    /**
+     * Perform an action on the page using natural language.
+     * Passes this specific page to Stagehand so it operates on the correct page.
+     */
+    enhancedPage.act = async (instruction, options) => {
+        try {
+            // Pass the page option to ensure Stagehand operates on this specific page
+            return await stagehand.act(instruction, { ...options, page });
+        }
+        catch (error) {
+            throw new Error(`Stagehand act() failed: ${improveErrorMessage(error)}`, {
+                cause: error,
+            });
+        }
+    };
+    /**
+     * Extract structured data from the page using natural language and a Zod schema.
+     * Passes this specific page to Stagehand so it operates on the correct page.
+     */
+    enhancedPage.extract = async (instruction, schema, options) => {
+        try {
+            // Pass the page option to ensure Stagehand operates on this specific page
+            return await stagehand.extract(instruction, schema, { ...options, page });
+        }
+        catch (error) {
+            throw new Error(`Stagehand extract() failed: ${improveErrorMessage(error)}`, {
+                cause: error,
+            });
+        }
+    };
+    /**
+     * Observe the page and get AI-suggested actions.
+     * Passes this specific page to Stagehand so it operates on the correct page.
+     */
+    enhancedPage.observe = async (options) => {
+        try {
+            // Pass the page option to ensure Stagehand operates on this specific page
+            return await stagehand.observe({ ...options, page });
+        }
+        catch (error) {
+            throw new Error(`Stagehand observe() failed: ${improveErrorMessage(error)}`, {
+                cause: error,
+            });
+        }
+    };
+    /**
+     * Create an autonomous agent for multi-step workflows.
+     * Note: Agent operates on the page context.
+     *
+     * The `as any` cast is needed because stagehand.agent() has two overloaded signatures
+     * (streaming vs non-streaming) that TypeScript struggles to reconcile when assigning
+     * to a property.
+     */
+    enhancedPage.agent = (config) => {
+        try {
+            if (config?.stream === true) {
+                return stagehand.agent(config);
+            }
+            return stagehand.agent(config);
+        }
+        catch (error) {
+            throw new Error(`Stagehand agent() failed: ${improveErrorMessage(error)}`, {
+                cause: error,
+            });
+        }
+    };
+    return enhancedPage;
+}
+//# sourceMappingURL=stagehand-utils.js.map

package/internals/utils/stagehand-utils.js.map

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

package/package.json

@@ -0,0 +1,90 @@
+{
+    "name": "@crawlee/stagehand",
+    "version": "3.15.4-beta.39",
+    "description": "AI-powered web crawling with Stagehand integration for Crawlee - enables natural language browser automation with act(), extract(), and observe() methods.",
+    "engines": {
+        "node": ">=16.0.0"
+    },
+    "main": "./index.js",
+    "module": "./index.mjs",
+    "types": "./index.d.ts",
+    "exports": {
+        ".": {
+            "import": "./index.mjs",
+            "require": "./index.js",
+            "types": "./index.d.ts"
+        },
+        "./package.json": "./package.json"
+    },
+    "keywords": [
+        "apify",
+        "crawlee",
+        "stagehand",
+        "ai",
+        "crawler",
+        "scraper",
+        "automation",
+        "playwright",
+        "browserbase"
+    ],
+    "author": {
+        "name": "Apify",
+        "email": "support@apify.com",
+        "url": "https://apify.com"
+    },
+    "contributors": [
+        "Jan Curn <jan@apify.com>",
+        "Marek Trunkat <marek@apify.com>",
+        "Ondra Urban <ondra@apify.com>"
+    ],
+    "license": "Apache-2.0",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/apify/crawlee"
+    },
+    "bugs": {
+        "url": "https://github.com/apify/crawlee/issues"
+    },
+    "homepage": "https://crawlee.dev",
+    "scripts": {
+        "build": "yarn clean && yarn compile && yarn copy",
+        "clean": "rimraf ./dist",
+        "compile": "tsc -p tsconfig.build.json && gen-esm-wrapper ./index.js ./index.mjs",
+        "copy": "tsx ../../scripts/copy.ts"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "dependencies": {
+        "@apify/log": "^2.4.0",
+        "@apify/timeout": "^0.3.1",
+        "@crawlee/browser": "3.15.4-beta.39",
+        "@crawlee/browser-pool": "3.15.4-beta.39",
+        "@crawlee/core": "3.15.4-beta.39",
+        "@crawlee/types": "3.15.4-beta.39",
+        "@crawlee/utils": "3.15.4-beta.39",
+        "ow": "^0.28.1",
+        "tslib": "^2.4.0"
+    },
+    "peerDependencies": {
+        "@browserbasehq/stagehand": "^3.0.0",
+        "playwright": "*",
+        "zod": "^3.0.0 || ^4.0.0"
+    },
+    "peerDependenciesMeta": {
+        "@browserbasehq/stagehand": {
+            "optional": false
+        },
+        "playwright": {
+            "optional": true
+        },
+        "zod": {
+            "optional": true
+        }
+    },
+    "devDependencies": {
+        "@browserbasehq/stagehand": "^3.0.7",
+        "playwright": "^1.57.0",
+        "zod": "^4.3.5"
+    }
+}