@hyperbrowser/sdk 0.43.0 → 0.44.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (10) hide show
  1. package/README.md +107 -22
  2. package/dist/tools/anthropic.d.ts +2 -0
  3. package/dist/tools/anthropic.js +11 -1
  4. package/dist/tools/index.d.ts +11 -1
  5. package/dist/tools/index.js +20 -2
  6. package/dist/tools/openai.d.ts +2 -0
  7. package/dist/tools/openai.js +19 -1
  8. package/dist/tools/schema.d.ts +48 -0
  9. package/dist/tools/schema.js +66 -1
  10. package/package.json +1 -1
package/README.md CHANGED
@@ -9,40 +9,125 @@ Hyperbrowser can be installed via npm by running:
9
9
  ```bash
10
10
  npm install @hyperbrowser/sdk
11
11
  ```
12
+ or
13
+ ```bash
14
+ yarn add @hyperbrowser/sdk
15
+ ```
12
16
 
13
17
  ## Usage
14
18
 
19
+ ### Playwright
20
+ ```typescript
21
+ import { chromium } from "playwright-core";
22
+ import { Hyperbrowser } from "@hyperbrowser/sdk";
23
+ import { config } from "dotenv";
24
+
25
+ config();
26
+
27
+ const client = new Hyperbrowser({
28
+ apiKey: process.env.HYPERBROWSER_API_KEY,
29
+ });
30
+
31
+ const main = async () => {
32
+ const session = await client.sessions.create();
33
+
34
+ try {
35
+ const browser = await chromium.connectOverCDP(session.wsEndpoint);
36
+
37
+ const defaultContext = browser.contexts()[0];
38
+ const page = await defaultContext.newPage();
39
+
40
+ // Navigate to a website
41
+ console.log("Navigating to Hacker News...");
42
+ await page.goto("https://news.ycombinator.com/");
43
+ const pageTitle = await page.title();
44
+ console.log("Page 1:", pageTitle);
45
+ await page.evaluate(() => {
46
+ console.log("Page 1:", document.title);
47
+ });
48
+
49
+ await page.goto("https://example.com");
50
+ console.log("Page 2:", await page.title());
51
+ await page.evaluate(() => {
52
+ console.log("Page 2:", document.title);
53
+ });
54
+
55
+ await page.goto("https://apple.com");
56
+ console.log("Page 3:", await page.title());
57
+ await page.evaluate(() => {
58
+ console.log("Page 3:", document.title);
59
+ });
60
+
61
+ await page.goto("https://google.com");
62
+ console.log("Page 4:", await page.title());
63
+ await page.evaluate(() => {
64
+ console.log("Page 4:", document.title);
65
+ });
66
+ } catch (err) {
67
+ console.error(`Encountered error: ${err}`);
68
+ } finally {
69
+ await client.sessions.stop(session.id);
70
+ }
71
+ };
72
+
73
+ main();
74
+ ```
75
+
76
+ ### Puppeteer
15
77
  ```typescript
16
78
  import { connect } from "puppeteer-core";
17
79
  import { Hyperbrowser } from "@hyperbrowser/sdk";
18
- import dotenv from "dotenv";
80
+ import { config } from "dotenv";
19
81
 
20
- dotenv.config();
82
+ config();
21
83
 
22
84
  const client = new Hyperbrowser({
23
85
  apiKey: process.env.HYPERBROWSER_API_KEY,
24
86
  });
25
87
 
26
- (async () => {
88
+ const main = async () => {
27
89
  const session = await client.sessions.create();
28
90
 
29
- const browser = await connect({
30
- browserWSEndpoint: session.wsEndpoint,
31
- defaultViewport: null,
32
- });
33
-
34
- // Create a new page
35
- const [page] = await browser.pages();
36
-
37
- // Navigate to a website
38
- console.log("Navigating to Hacker News...");
39
- await page.goto("https://news.ycombinator.com/");
40
- const pageTitle = await page.title();
41
- console.log("Page title:", pageTitle);
42
-
43
- await page.close();
44
- await browser.close();
45
- console.log("Session completed!");
46
- await client.sessions.stop(session.id);
47
- })().catch((error) => console.error(error.message));
91
+ try {
92
+ const browser = await connect({
93
+ browserWSEndpoint: session.wsEndpoint,
94
+ defaultViewport: null,
95
+ });
96
+
97
+ const [page] = await browser.pages();
98
+
99
+ // Navigate to a website
100
+ console.log("Navigating to Hacker News...");
101
+ await page.goto("https://news.ycombinator.com/");
102
+ const pageTitle = await page.title();
103
+ console.log("Page 1:", pageTitle);
104
+ await page.evaluate(() => {
105
+ console.log("Page 1:", document.title);
106
+ });
107
+
108
+ await page.goto("https://example.com");
109
+ console.log("Page 2:", await page.title());
110
+ await page.evaluate(() => {
111
+ console.log("Page 2:", document.title);
112
+ });
113
+
114
+ await page.goto("https://apple.com");
115
+ console.log("Page 3:", await page.title());
116
+ await page.evaluate(() => {
117
+ console.log("Page 3:", document.title);
118
+ });
119
+
120
+ await page.goto("https://google.com");
121
+ console.log("Page 4:", await page.title());
122
+ await page.evaluate(() => {
123
+ console.log("Page 4:", document.title);
124
+ });
125
+ } catch (err) {
126
+ console.error(`Encountered error: ${err}`);
127
+ } finally {
128
+ await client.sessions.stop(session.id);
129
+ }
130
+ };
131
+
132
+ main();
48
133
  ```
package/dist/tools/anthropic.d.ts CHANGED
@@ -36,3 +36,5 @@ export declare const SCREENSHOT_TOOL_ANTHROPIC: Tool;
36
36
  export declare const CRAWL_TOOL_ANTHROPIC: Tool;
37
37
  export declare const EXTRACT_TOOL_ANTHROPIC: Tool;
38
38
  export declare const BROWSER_USE_TOOL_ANTHROPIC: Tool;
39
+ export declare const CLAUDE_COMPUTER_USE_TOOL_ANTHROPIC: Tool;
40
+ export declare const OPENAI_CUA_TOOL_ANTHROPIC: Tool;
package/dist/tools/anthropic.js CHANGED
@@ -1,6 +1,6 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.BROWSER_USE_TOOL_ANTHROPIC = exports.EXTRACT_TOOL_ANTHROPIC = exports.CRAWL_TOOL_ANTHROPIC = exports.SCREENSHOT_TOOL_ANTHROPIC = exports.SCRAPE_TOOL_ANTHROPIC = void 0;
3
+ exports.OPENAI_CUA_TOOL_ANTHROPIC = exports.CLAUDE_COMPUTER_USE_TOOL_ANTHROPIC = exports.BROWSER_USE_TOOL_ANTHROPIC = exports.EXTRACT_TOOL_ANTHROPIC = exports.CRAWL_TOOL_ANTHROPIC = exports.SCREENSHOT_TOOL_ANTHROPIC = exports.SCRAPE_TOOL_ANTHROPIC = void 0;
4
4
  const schema_1 = require("./schema");
5
5
  exports.SCRAPE_TOOL_ANTHROPIC = {
6
6
  input_schema: schema_1.SCRAPE_SCHEMA,
@@ -27,3 +27,13 @@ exports.BROWSER_USE_TOOL_ANTHROPIC = {
27
27
  name: "browser_use",
28
28
  description: "Have an AI agent use a browser to perform a task on the web.",
29
29
  };
30
+ exports.CLAUDE_COMPUTER_USE_TOOL_ANTHROPIC = {
31
+ input_schema: schema_1.CLAUDE_COMPUTER_USE_SCHEMA,
32
+ name: "claude_computer_use",
33
+ description: schema_1.CLAUDE_COMPUTER_USE_DESCRIPTION,
34
+ };
35
+ exports.OPENAI_CUA_TOOL_ANTHROPIC = {
36
+ input_schema: schema_1.OPENAI_CUA_SCHEMA,
37
+ name: "openai_cua",
38
+ description: schema_1.OPENAI_CUA_DESCRIPTION,
39
+ };
package/dist/tools/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import { HyperbrowserClient } from "../client";
2
- import { StartScrapeJobParams, StartCrawlJobParams, StartBrowserUseTaskParams } from "../types";
2
+ import { StartScrapeJobParams, StartCrawlJobParams, StartBrowserUseTaskParams, StartCuaTaskParams, StartClaudeComputerUseTaskParams } from "../types";
3
3
  import { StartExtractJobParams } from "../types/extract";
4
4
  export declare class WebsiteScrapeTool {
5
5
  static openaiToolDefinition: import("./openai").ChatCompletionTool;
@@ -26,3 +26,13 @@ export declare class BrowserUseTool {
26
26
  static anthropicToolDefinition: import("./anthropic").Tool;
27
27
  static runnable(hb: HyperbrowserClient, params: StartBrowserUseTaskParams): Promise<string>;
28
28
  }
29
+ export declare class ClaudeComputerUseTool {
30
+ static openaiToolDefinition: import("./openai").ChatCompletionTool;
31
+ static anthropicToolDefinition: import("./anthropic").Tool;
32
+ static runnable(hb: HyperbrowserClient, params: StartClaudeComputerUseTaskParams): Promise<string>;
33
+ }
34
+ export declare class OpenAICuaTool {
35
+ static openaiToolDefinition: import("./openai").ChatCompletionTool;
36
+ static anthropicToolDefinition: import("./anthropic").Tool;
37
+ static runnable(hb: HyperbrowserClient, params: StartCuaTaskParams): Promise<string>;
38
+ }
package/dist/tools/index.js CHANGED
@@ -1,6 +1,6 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.BrowserUseTool = exports.WebsiteExtractTool = exports.WebsiteCrawlTool = exports.WebsiteScreenshotTool = exports.WebsiteScrapeTool = void 0;
3
+ exports.OpenAICuaTool = exports.ClaudeComputerUseTool = exports.BrowserUseTool = exports.WebsiteExtractTool = exports.WebsiteCrawlTool = exports.WebsiteScreenshotTool = exports.WebsiteScrapeTool = void 0;
4
4
  const openai_1 = require("./openai");
5
5
  const anthropic_1 = require("./anthropic");
6
6
  class WebsiteScrapeTool {
@@ -53,9 +53,27 @@ WebsiteExtractTool.anthropicToolDefinition = anthropic_1.EXTRACT_TOOL_ANTHROPIC;
53
53
  class BrowserUseTool {
54
54
  static async runnable(hb, params) {
55
55
  const resp = await hb.agents.browserUse.startAndWait(params);
56
- return resp.data?.finalResult || "";
56
+ return resp.data?.finalResult || resp.error || "";
57
57
  }
58
58
  }
59
59
  exports.BrowserUseTool = BrowserUseTool;
60
60
  BrowserUseTool.openaiToolDefinition = openai_1.BROWSER_USE_TOOL_OPENAI;
61
61
  BrowserUseTool.anthropicToolDefinition = anthropic_1.BROWSER_USE_TOOL_ANTHROPIC;
62
+ class ClaudeComputerUseTool {
63
+ static async runnable(hb, params) {
64
+ const resp = await hb.agents.claudeComputerUse.startAndWait(params);
65
+ return resp.data?.finalResult || resp.error || "";
66
+ }
67
+ }
68
+ exports.ClaudeComputerUseTool = ClaudeComputerUseTool;
69
+ ClaudeComputerUseTool.openaiToolDefinition = openai_1.CLAUDE_COMPUTER_USE_TOOL_OPENAI;
70
+ ClaudeComputerUseTool.anthropicToolDefinition = anthropic_1.CLAUDE_COMPUTER_USE_TOOL_ANTHROPIC;
71
+ class OpenAICuaTool {
72
+ static async runnable(hb, params) {
73
+ const resp = await hb.agents.cua.startAndWait(params);
74
+ return resp.data?.finalResult || resp.error || "";
75
+ }
76
+ }
77
+ exports.OpenAICuaTool = OpenAICuaTool;
78
+ OpenAICuaTool.openaiToolDefinition = openai_1.OPENAI_CUA_TOOL_OPENAI;
79
+ OpenAICuaTool.anthropicToolDefinition = anthropic_1.OPENAI_CUA_TOOL_ANTHROPIC;
package/dist/tools/openai.d.ts CHANGED
@@ -41,3 +41,5 @@ export declare const SCREENSHOT_TOOL_OPENAI: ChatCompletionTool;
41
41
  export declare const CRAWL_TOOL_OPENAI: ChatCompletionTool;
42
42
  export declare const EXTRACT_TOOL_OPENAI: ChatCompletionTool;
43
43
  export declare const BROWSER_USE_TOOL_OPENAI: ChatCompletionTool;
44
+ export declare const CLAUDE_COMPUTER_USE_TOOL_OPENAI: ChatCompletionTool;
45
+ export declare const OPENAI_CUA_TOOL_OPENAI: ChatCompletionTool;
package/dist/tools/openai.js CHANGED
@@ -1,6 +1,6 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.BROWSER_USE_TOOL_OPENAI = exports.EXTRACT_TOOL_OPENAI = exports.CRAWL_TOOL_OPENAI = exports.SCREENSHOT_TOOL_OPENAI = exports.SCRAPE_TOOL_OPENAI = void 0;
3
+ exports.OPENAI_CUA_TOOL_OPENAI = exports.CLAUDE_COMPUTER_USE_TOOL_OPENAI = exports.BROWSER_USE_TOOL_OPENAI = exports.EXTRACT_TOOL_OPENAI = exports.CRAWL_TOOL_OPENAI = exports.SCREENSHOT_TOOL_OPENAI = exports.SCRAPE_TOOL_OPENAI = void 0;
4
4
  const schema_1 = require("./schema");
5
5
  exports.SCRAPE_TOOL_OPENAI = {
6
6
  type: "function",
@@ -47,3 +47,21 @@ exports.BROWSER_USE_TOOL_OPENAI = {
47
47
  strict: true,
48
48
  },
49
49
  };
50
+ exports.CLAUDE_COMPUTER_USE_TOOL_OPENAI = {
51
+ type: "function",
52
+ function: {
53
+ name: "claude_computer_use",
54
+ description: schema_1.CLAUDE_COMPUTER_USE_DESCRIPTION,
55
+ parameters: schema_1.CLAUDE_COMPUTER_USE_SCHEMA,
56
+ strict: true,
57
+ },
58
+ };
59
+ exports.OPENAI_CUA_TOOL_OPENAI = {
60
+ type: "function",
61
+ function: {
62
+ name: "openai_cua",
63
+ description: schema_1.OPENAI_CUA_DESCRIPTION,
64
+ parameters: schema_1.OPENAI_CUA_SCHEMA,
65
+ strict: true,
66
+ },
67
+ };
package/dist/tools/schema.d.ts CHANGED
@@ -1,3 +1,5 @@
1
+ export declare const OPENAI_CUA_DESCRIPTION = "This tool utilizes OpenAI's model to autonomously execute general-purpose browser-based tasks with balanced performance and reliability using a cloud browser. It handles complex interactions effectively with practical reasoning and clear execution.\n\nOptimal for tasks requiring:\n- Reliable, general-purpose browser automation\n- Clear, structured interactions with moderate complexity\n- Efficient handling of common web tasks and workflows\n\nBest suited use cases include:\n- Standard multi-step registration or form submissions\n- Navigating typical web applications requiring multiple interactions\n- Conducting structured web research tasks\n- Extracting data through interactive web processes\n\nProvide a clear step-by-step description, necessary context, and expected outcomes. Returns the completed result or an error message if issues arise.";
2
+ export declare const CLAUDE_COMPUTER_USE_DESCRIPTION = "\nThis tool leverages Anthropic's Claude model to autonomously execute complex browser tasks with sophisticated reasoning capabilities using a cloud browser. It specializes in handling intricate, nuanced, or highly context-sensitive web interactions.\n\nOptimal for tasks requiring:\n- Complex reasoning over multiple web pages\n- Nuanced interpretation and flexible decision-making\n- Human-like interaction with detailed context awareness\n\nBest suited use cases include:\n- Multi-step processes requiring reasoning (e.g., detailed registrations or onboarding)\n- Interacting intelligently with advanced web apps\n- Conducting in-depth research with complex conditions\n- Extracting information from dynamic or interactive websites\n\nProvide detailed task instructions, relevant context, and clearly specify the desired outcome for best results. Returns the completed result or an error message if issues arise.";
1
3
  export declare const SCRAPE_SCHEMA: {
2
4
  type: "object";
3
5
  properties: {
@@ -218,3 +220,49 @@ export declare const BROWSER_USE_SCHEMA: {
218
220
  required: string[];
219
221
  additionalProperties: boolean;
220
222
  };
223
+ export declare const CLAUDE_COMPUTER_USE_SCHEMA: {
224
+ type: "object";
225
+ properties: {
226
+ task: {
227
+ type: string;
228
+ description: string;
229
+ };
230
+ sessionOptions: {
231
+ type: string;
232
+ description: string;
233
+ properties: {
234
+ useProxy: {
235
+ type: string;
236
+ description: string;
237
+ };
238
+ };
239
+ required: string[];
240
+ additionalProperties: boolean;
241
+ };
242
+ };
243
+ required: string[];
244
+ additionalProperties: boolean;
245
+ };
246
+ export declare const OPENAI_CUA_SCHEMA: {
247
+ type: "object";
248
+ properties: {
249
+ task: {
250
+ type: string;
251
+ description: string;
252
+ };
253
+ sessionOptions: {
254
+ type: string;
255
+ description: string;
256
+ properties: {
257
+ useProxy: {
258
+ type: string;
259
+ description: string;
260
+ };
261
+ };
262
+ required: string[];
263
+ additionalProperties: boolean;
264
+ };
265
+ };
266
+ required: string[];
267
+ additionalProperties: boolean;
268
+ };
package/dist/tools/schema.js CHANGED
@@ -1,6 +1,35 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.BROWSER_USE_SCHEMA = exports.EXTRACT_SCHEMA = exports.CRAWL_SCHEMA = exports.SCREENSHOT_SCHEMA = exports.SCRAPE_SCHEMA = void 0;
3
+ exports.OPENAI_CUA_SCHEMA = exports.CLAUDE_COMPUTER_USE_SCHEMA = exports.BROWSER_USE_SCHEMA = exports.EXTRACT_SCHEMA = exports.CRAWL_SCHEMA = exports.SCREENSHOT_SCHEMA = exports.SCRAPE_SCHEMA = exports.CLAUDE_COMPUTER_USE_DESCRIPTION = exports.OPENAI_CUA_DESCRIPTION = void 0;
4
+ exports.OPENAI_CUA_DESCRIPTION = `This tool utilizes OpenAI's model to autonomously execute general-purpose browser-based tasks with balanced performance and reliability using a cloud browser. It handles complex interactions effectively with practical reasoning and clear execution.
5
+
6
+ Optimal for tasks requiring:
7
+ - Reliable, general-purpose browser automation
8
+ - Clear, structured interactions with moderate complexity
9
+ - Efficient handling of common web tasks and workflows
10
+
11
+ Best suited use cases include:
12
+ - Standard multi-step registration or form submissions
13
+ - Navigating typical web applications requiring multiple interactions
14
+ - Conducting structured web research tasks
15
+ - Extracting data through interactive web processes
16
+
17
+ Provide a clear step-by-step description, necessary context, and expected outcomes. Returns the completed result or an error message if issues arise.`;
18
+ exports.CLAUDE_COMPUTER_USE_DESCRIPTION = `
19
+ This tool leverages Anthropic's Claude model to autonomously execute complex browser tasks with sophisticated reasoning capabilities using a cloud browser. It specializes in handling intricate, nuanced, or highly context-sensitive web interactions.
20
+
21
+ Optimal for tasks requiring:
22
+ - Complex reasoning over multiple web pages
23
+ - Nuanced interpretation and flexible decision-making
24
+ - Human-like interaction with detailed context awareness
25
+
26
+ Best suited use cases include:
27
+ - Multi-step processes requiring reasoning (e.g., detailed registrations or onboarding)
28
+ - Interacting intelligently with advanced web apps
29
+ - Conducting in-depth research with complex conditions
30
+ - Extracting information from dynamic or interactive websites
31
+
32
+ Provide detailed task instructions, relevant context, and clearly specify the desired outcome for best results. Returns the completed result or an error message if issues arise.`;
4
33
  function getScrapeOptions(formats = ["markdown"]) {
5
34
  return {
6
35
  type: "object",
@@ -37,6 +66,18 @@ function getScrapeOptions(formats = ["markdown"]) {
37
66
  additionalProperties: false,
38
67
  };
39
68
  }
69
+ const SESSION_OPTIONS = {
70
+ type: "object",
71
+ description: "The options for the browser session that will be used.",
72
+ properties: {
73
+ useProxy: {
74
+ type: "boolean",
75
+ description: "Recommended false. Avoid setting this if not explicitly mentioned. Whether to use residential proxies to access the internet. Enabling this helps avoid getting detected as a bot.",
76
+ },
77
+ },
78
+ required: ["useProxy"],
79
+ additionalProperties: false,
80
+ };
40
81
  exports.SCRAPE_SCHEMA = {
41
82
  type: "object",
42
83
  properties: {
@@ -172,3 +213,27 @@ exports.BROWSER_USE_SCHEMA = {
172
213
  required: ["task", "llm", "plannerLlm", "pageExtractionLlm", "keepBrowserOpen"],
173
214
  additionalProperties: false,
174
215
  };
216
+ exports.CLAUDE_COMPUTER_USE_SCHEMA = {
217
+ type: "object",
218
+ properties: {
219
+ task: {
220
+ type: "string",
221
+ description: "The text description of the task to be performed by the agent.",
222
+ },
223
+ sessionOptions: SESSION_OPTIONS,
224
+ },
225
+ required: ["task", "sessionOptions"],
226
+ additionalProperties: false,
227
+ };
228
+ exports.OPENAI_CUA_SCHEMA = {
229
+ type: "object",
230
+ properties: {
231
+ task: {
232
+ type: "string",
233
+ description: "The text description of the task to be performed by the agent.",
234
+ },
235
+ sessionOptions: SESSION_OPTIONS,
236
+ },
237
+ required: ["task", "sessionOptions"],
238
+ additionalProperties: false,
239
+ };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hyperbrowser/sdk",
3
- "version": "0.43.0",
3
+ "version": "0.44.0",
4
4
  "description": "Node SDK for Hyperbrowser API",
5
5
  "author": "",
6
6
  "main": "dist/index.js",