browser-use-sdk 1.2.0 → 2.0.1

package/README.md

@@ -1,382 +1,195 @@
-<img src="./assets/cloud-banner-js.png" alt="Browser Use JS" width="full"/>
+<img src="https://raw.githubusercontent.com/browser-use/browser-use-node/refs/heads/main/assets/cloud-banner-js.png" alt="Browser Use JS" width="full"/>
 
-```sh
-pnpm add browser-use-sdk
-```
+# BrowserUse TypeScript Library
 
-## Two-Step QuickStart
+[![fern shield](https://img.shields.io/badge/%F0%9F%8C%BF-Built%20with%20Fern-brightgreen)](https://buildwithfern.com?utm_source=github&utm_medium=github&utm_campaign=readme&utm_source=https%3A%2F%2Fgithub.com%2Fbrowser-use%2Fbrowser-use-node)
+[![npm shield](https://img.shields.io/npm/v/browser-use-sdk)](https://www.npmjs.com/package/browser-use-sdk)
 
-1. ☝️ Get your API Key at [Browser Use Cloud](https://cloud.browser-use.com)...
+The BrowserUse TypeScript library provides convenient access to the BrowserUse APIs from TypeScript.
 
-1. ✌️ Automate the web!
+## Three-Step QuickStart
 
-```ts
-import BrowserUse from 'browser-use-sdk';
+1.  📦 Install BrowserUse SDK.
 
-const client = new BrowserUse({
-  apiKey: 'bu_...',
-});
+    ```sh
+    # NPM
+    npm i -s browser-use-sdk
 
-const result = await client.tasks.run({
-  task: 'Search for the top 10 Hacker News posts and return the title and url.',
-});
+    # Yarn
+    yarn add browser-use-sdk
 
-console.log(result.doneOutput);
-```
+    # PNPM
+    pnpm add browser-use-sdk
+    ```
+
+1.  🔑 Get your API Key at [Browser Use Cloud](https://cloud.browser-use.com)!
+
+1.  🦄 Automate the Internet!
+
+    ```ts
+    import { BrowserUseClient } from "browser-use-sdk";
+
+    const client = new BrowserUseClient({
+        apiKey: "bu_...",
+    });
+
+    const task = await client.tasks.createTask({
+        task: "Search for the top 10 Hacker News posts and return the title and url.",
+    });
+
+    const result = await task.complete();
+
+    console.log(result.output);
+    ```
 
 > The full API of this library can be found in [api.md](api.md).
 
 ### Structured Output with Zod
 
 ```ts
-import z from 'zod';
+import z from "zod";
 
 const TaskOutput = z.object({
-  posts: z.array(
-    z.object({
-      title: z.string(),
-      url: z.string(),
-    }),
-  ),
+    posts: z.array(
+        z.object({
+            title: z.string(),
+            url: z.string(),
+        }),
+    ),
 });
 
-const result = await client.tasks.run({
-  task: 'Search for the top 10 Hacker News posts and return the title and url.',
+const task = await client.tasks.createTask({
+    task: "Search for the top 10 Hacker News posts and return the title and url.",
+    schema: TaskOutput,
 });
 
-for (const post of result.parsedOutput.posts) {
-  console.log(`${post.title} - ${post.url}`);
+const result = await task.complete();
+
+for (const post of result.parsed.posts) {
+    console.log(`${post.title} - ${post.url}`);
 }
 ```
 
 ### Streaming Agent Updates
 
-```ts
-const task = await browseruse.tasks.create({
-  task: 'Search for the top 10 Hacker News posts and return the title and url.',
-  schema: TaskOutput,
-});
+> You can use the `stream` method to get the latest step taken on every change.
 
-const stream = browseruse.tasks.stream({
-  taskId: task.id,
-  schema: TaskOutput,
+```ts
+const task = await browseruse.tasks.createTask({
+    task: "Search for the top 10 Hacker News posts and return the title and url.",
+    schema: TaskOutput,
 });
 
-for await (const msg of stream) {
-  switch (msg.status) {
-    case 'started':
-    case 'paused':
-    case 'stopped':
-      console.log(`running: ${msg}`);
-      break;
-
-    case 'finished':
-      console.log(`done:`);
-
-      for (const post of msg.parsedOutput.posts) {
-        console.log(`${post.title} - ${post.url}`);
-      }
-      break;
-  }
+for await (const step of task.stream()) {
+    console.log(step);
 }
-```
 
-## Webhook Verification
-
-> We encourage you to use the SDK functions that verify and parse webhook events.
+const result = await task.complete();
 
-```ts
-import {
-  verifyWebhookEventSignature,
-  type WebhookAgentTaskStatusUpdatePayload,
-} from 'browser-use-sdk/lib/webhooks';
-
-export async function POST(req: Request) {
-  const signature = req.headers['x-browser-use-signature'] as string;
-  const timestamp = req.headers['x-browser-use-timestamp'] as string;
-
-  const event = await verifyWebhookEventSignature(
-    {
-      body,
-      signature,
-      timestamp,
-    },
-    {
-      secret: SECRET_KEY,
-    },
-  );
-
-  if (!event.ok) {
-    return;
-  }
-
-  switch (event.event.type) {
-    case 'agent.task.status_update':
-      break;
-    case 'test':
-      break;
-    default:
-      break;
-  }
+for (const post of result.parsed.posts) {
+    console.log(`${post.title} - ${post.url}`);
 }
 ```
 
-## Advanced Usage
+### Watching Agent Updates
 
-## Handling errors
+> You can use the `watch` method to get the latest update on every change.
 
-When the library is unable to connect to the API,
-or if the API returns a non-success status code (i.e., 4xx or 5xx response),
-a subclass of `APIError` will be thrown:
-
-<!-- prettier-ignore -->
 ```ts
-const task = await client.tasks
-  .create({ task: 'Search for the top 10 Hacker News posts and return the title and url.' })
-  .catch(async (err) => {
-    if (err instanceof BrowserUse.APIError) {
-      console.log(err.status); // 400
-      console.log(err.name); // BadRequestError
-      console.log(err.headers); // {server: 'nginx', ...}
-    } else {
-      throw err;
-    }
-  });
-```
-
-Error codes are as follows:
-
-| Status Code | Error Type                 |
-| ----------- | -------------------------- |
-| 400         | `BadRequestError`          |
-| 401         | `AuthenticationError`      |
-| 403         | `PermissionDeniedError`    |
-| 404         | `NotFoundError`            |
-| 422         | `UnprocessableEntityError` |
-| 429         | `RateLimitError`           |
-| >=500       | `InternalServerError`      |
-| N/A         | `APIConnectionError`       |
-
-### Retries
-
-Certain errors will be automatically retried 2 times by default, with a short exponential backoff.
-Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict,
-429 Rate Limit, and >=500 Internal errors will all be retried by default.
-
-You can use the `maxRetries` option to configure or disable this:
-
-<!-- prettier-ignore -->
-```js
-// Configure the default for all requests:
-const client = new BrowserUse({
-  maxRetries: 0, // default is 2
-});
-
-// Or, configure per-request:
-await client.tasks.create({ task: 'Search for the top 10 Hacker News posts and return the title and url.' }, {
-  maxRetries: 5,
-});
-```
-
-### Timeouts
-
-Requests time out after 1 minute by default. You can configure this with a `timeout` option:
-
-<!-- prettier-ignore -->
-```ts
-// Configure the default for all requests:
-const client = new BrowserUse({
-  timeout: 20 * 1000, // 20 seconds (default is 1 minute)
-});
-
-// Override per-request:
-await client.tasks.create({ task: 'Search for the top 10 Hacker News posts and return the title and url.' }, {
-  timeout: 5 * 1000,
+const task = await browseruse.tasks.createTask({
+    task: "Search for the top 10 Hacker News posts and return the title and url.",
+    schema: TaskOutput,
 });
-```
-
-On timeout, an `APIConnectionTimeoutError` is thrown.
-
-Note that requests which time out will be [retried twice by default](#retries).
-
-### Accessing raw Response data (e.g., headers)
-
-The "raw" `Response` returned by `fetch()` can be accessed through the `.asResponse()` method on the `APIPromise` type that all methods return.
-This method returns as soon as the headers for a successful response are received and does not consume the response body, so you are free to write custom parsing or streaming logic.
-
-You can also use the `.withResponse()` method to get the raw `Response` along with the parsed data.
-Unlike `.asResponse()` this method consumes the body, returning once it is parsed.
-
-<!-- prettier-ignore -->
-```ts
-const client = new BrowserUse();
-
-const response = await client.tasks
-  .create({ task: 'Search for the top 10 Hacker News posts and return the title and url.' })
-  .asResponse();
-console.log(response.headers.get('X-My-Header'));
-console.log(response.statusText); // access the underlying Response object
-
-const { data: task, response: raw } = await client.tasks
-  .create({ task: 'Search for the top 10 Hacker News posts and return the title and url.' })
-  .withResponse();
-console.log(raw.headers.get('X-My-Header'));
-console.log(task.id);
-```
-
-### Logging
 
-> [!IMPORTANT]
-> All log messages are intended for debugging only. The format and content of log messages
-> may change between releases.
+for await (const update of task.watch()) {
+    console.log(update);
 
-#### Log levels
-
-The log level can be configured in two ways:
-
-1. Via the `BROWSER_USE_LOG` environment variable
-2. Using the `logLevel` client option (overrides the environment variable if set)
-
-```ts
-import BrowserUse from 'browser-use-sdk';
-
-const client = new BrowserUse({
-  logLevel: 'debug', // Show all log messages
-});
+    if (update.data.status === "finished") {
+        for (const post of update.data.parsed.posts) {
+            console.log(`${post.title} - ${post.url}`);
+        }
+    }
+}
 ```
 
-Available log levels, from most to least verbose:
-
-- `'debug'` - Show debug messages, info, warnings, and errors
-- `'info'` - Show info messages, warnings, and errors
-- `'warn'` - Show warnings and errors (default)
-- `'error'` - Show only errors
-- `'off'` - Disable all logging
-
-At the `'debug'` level, all HTTP requests and responses are logged, including headers and bodies.
-Some authentication-related headers are redacted, but sensitive data in request and response bodies
-may still be visible.
-
-#### Custom logger
-
-By default, this library logs to `globalThis.console`. You can also provide a custom logger.
-Most logging libraries are supported, including [pino](https://www.npmjs.com/package/pino), [winston](https://www.npmjs.com/package/winston), [bunyan](https://www.npmjs.com/package/bunyan), [consola](https://www.npmjs.com/package/consola), [signale](https://www.npmjs.com/package/signale), and [@std/log](https://jsr.io/@std/log). If your logger doesn't work, please open an issue.
+## Webhook Verification
 
-When providing a custom logger, the `logLevel` option still controls which messages are emitted, messages
-below the configured level will not be sent to your logger.
+> We encourage you to use the SDK functions that verify and parse webhook events.
 
 ```ts
-import BrowserUse from 'browser-use-sdk';
-import pino from 'pino';
-
-const logger = pino();
-
-const client = new BrowserUse({
-  logger: logger.child({ name: 'BrowserUse' }),
-  logLevel: 'debug', // Send all messages to pino, allowing it to filter
-});
-```
-
-### Customizing the fetch client
-
-By default, this library expects a global `fetch` function is defined.
+import { verifyWebhookEventSignature, type WebhookAgentTaskStatusUpdatePayload } from "browser-use-sdk";
 
-If you want to use a different `fetch` function, you can either polyfill the global:
-
-```ts
-import fetch from 'my-fetch';
+export async function POST(req: Request) {
+    const signature = req.headers["x-browser-use-signature"] as string;
+    const timestamp = req.headers["x-browser-use-timestamp"] as string;
+
+    const event = await verifyWebhookEventSignature(
+        {
+            body,
+            signature,
+            timestamp,
+        },
+        {
+            secret: SECRET_KEY,
+        },
+    );
+
+    if (!event.ok) {
+        return;
+    }
 
-globalThis.fetch = fetch;
+    switch (event.event.type) {
+        case "agent.task.status_update":
+            break;
+        case "test":
+            break;
+        default:
+            break;
+    }
+}
 ```
 
-Or pass it to the client:
-
-```ts
-import BrowserUse from 'browser-use-sdk';
-import fetch from 'my-fetch';
-
-const client = new BrowserUse({ fetch });
-```
+## Contributing
 
-### Fetch options
+While we value open-source contributions to this SDK, this library is generated programmatically.
+Additions made directly to this library would have to be moved over to our generation code,
+otherwise they would be overwritten upon the next generated release. Feel free to open a PR as
+a proof of concept, but know that we will not be able to merge it as-is. We suggest opening
+an issue first to discuss with us!
 
-If you want to set custom `fetch` options without overriding the `fetch` function, you can provide a `fetchOptions` object when instantiating the client or making a request. (Request-specific options override client options.)
+On the other hand, contributions to the README are always very welcome!
 
-```ts
-import BrowserUse from 'browser-use-sdk';
+## Installation
 
-const client = new BrowserUse({
-  fetchOptions: {
-    // `RequestInit` options
-  },
-});
+```sh
+npm i -s browser-use-sdk
 ```
 
-#### Configuring proxies
-
-To modify proxy behavior, you can provide custom `fetchOptions` that add runtime-specific proxy
-options to requests:
+## Reference
 
-<img src="https://raw.githubusercontent.com/stainless-api/sdk-assets/refs/heads/main/node.svg" align="top" width="18" height="21"> **Node** <sup>[[docs](https://github.com/nodejs/undici/blob/main/docs/docs/api/ProxyAgent.md#example---proxyagent-with-fetch)]</sup>
+A full reference for this library is available [here](https://github.com/browser-use/browser-use-node/blob/HEAD/./reference.md).
 
-```ts
-import BrowserUse from 'browser-use-sdk';
-import * as undici from 'undici';
-
-const proxyAgent = new undici.ProxyAgent('http://localhost:8888');
-const client = new BrowserUse({
-  fetchOptions: {
-    dispatcher: proxyAgent,
-  },
-});
-```
+### Runtime Compatibility
 
-<img src="https://raw.githubusercontent.com/stainless-api/sdk-assets/refs/heads/main/bun.svg" align="top" width="18" height="21"> **Bun** <sup>[[docs](https://bun.sh/guides/http/proxy)]</sup>
+The SDK works in the following runtimes:
 
-```ts
-import BrowserUse from 'browser-use-sdk';
+- Node.js 18+
+- Vercel
+- Cloudflare Workers
+- Deno v1.25+
+- Bun 1.0+
+- React Native
 
-const client = new BrowserUse({
-  fetchOptions: {
-    proxy: 'http://localhost:8888',
-  },
-});
-```
+### Customizing Fetch Client
 
-<img src="https://raw.githubusercontent.com/stainless-api/sdk-assets/refs/heads/main/deno.svg" align="top" width="18" height="21"> **Deno** <sup>[[docs](https://docs.deno.com/api/deno/~/Deno.createHttpClient)]</sup>
+The SDK provides a way for you to customize the underlying HTTP client / Fetch function. If you're running in an
+unsupported environment, this provides a way for you to break glass and ensure the SDK works.
 
-```ts
-import BrowserUse from 'npm:browser-use-sdk';
+```typescript
+import { BrowserUseClient } from "browser-use-sdk";
 
-const httpClient = Deno.createHttpClient({ proxy: { url: 'http://localhost:8888' } });
-const client = new BrowserUse({
-  fetchOptions: {
-    client: httpClient,
-  },
+const client = new BrowserUseClient({
+    ...
+    fetcher: // provide your implementation here
 });
 ```
-
-## Frequently Asked Questions
-
-## Requirements
-
-TypeScript >= 4.9 is supported.
-
-The following runtimes are supported:
-
-- Web browsers (Up-to-date Chrome, Firefox, Safari, Edge, and more)
-- Node.js 20 LTS or later ([non-EOL](https://endoflife.date/nodejs)) versions.
-- Deno v1.28.0 or higher.
-- Bun 1.0 or later.
-- Cloudflare Workers.
-- Vercel Edge Runtime.
-- Jest 28 or greater with the `"node"` environment (`"jsdom"` is not supported at this time).
-- Nitro v2.6 or greater.
-
-Note that React Native is not supported at this time.
-
-If you are interested in other runtime environments, please open or upvote an issue on GitHub.
-
-## Contributing
-
-See [the contributing documentation](./CONTRIBUTING.md).

package/dist/cjs/Client.d.ts

@@ -0,0 +1,46 @@
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+import * as environments from "./environments.js";
+import * as core from "./core/index.js";
+import { Accounts } from "./api/resources/accounts/client/Client.js";
+import { Tasks } from "./api/resources/tasks/client/Client.js";
+import { Sessions } from "./api/resources/sessions/client/Client.js";
+import { Files } from "./api/resources/files/client/Client.js";
+import { Profiles } from "./api/resources/profiles/client/Client.js";
+export declare namespace BrowserUseClient {
+    interface Options {
+        environment?: core.Supplier<environments.BrowserUseEnvironment | string>;
+        /** Specify a custom URL to connect the client to. */
+        baseUrl?: core.Supplier<string>;
+        apiKey: core.Supplier<string>;
+        /** Additional headers to include in requests. */
+        headers?: Record<string, string | core.Supplier<string | undefined> | undefined>;
+    }
+    interface RequestOptions {
+        /** The maximum time to wait for a response in seconds. */
+        timeoutInSeconds?: number;
+        /** The number of times to retry the request. Defaults to 2. */
+        maxRetries?: number;
+        /** A hook to abort the request. */
+        abortSignal?: AbortSignal;
+        /** Additional query string parameters to include in the request. */
+        queryParams?: Record<string, unknown>;
+        /** Additional headers to include in the request. */
+        headers?: Record<string, string | core.Supplier<string | undefined> | undefined>;
+    }
+}
+export declare class BrowserUseClient {
+    protected readonly _options: BrowserUseClient.Options;
+    protected _accounts: Accounts | undefined;
+    protected _tasks: Tasks | undefined;
+    protected _sessions: Sessions | undefined;
+    protected _files: Files | undefined;
+    protected _profiles: Profiles | undefined;
+    constructor(_options: BrowserUseClient.Options);
+    get accounts(): Accounts;
+    get tasks(): Tasks;
+    get sessions(): Sessions;
+    get files(): Files;
+    get profiles(): Profiles;
+}

package/dist/cjs/Client.js

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BrowserUseClient = void 0;
+const core = __importStar(require("./core/index.js"));
+const headers_js_1 = require("./core/headers.js");
+const Client_js_1 = require("./api/resources/accounts/client/Client.js");
+const Client_js_2 = require("./api/resources/tasks/client/Client.js");
+const Client_js_3 = require("./api/resources/sessions/client/Client.js");
+const Client_js_4 = require("./api/resources/files/client/Client.js");
+const Client_js_5 = require("./api/resources/profiles/client/Client.js");
+class BrowserUseClient {
+    constructor(_options) {
+        this._options = Object.assign(Object.assign({}, _options), { headers: (0, headers_js_1.mergeHeaders)({
+                "X-Fern-Language": "JavaScript",
+                "X-Fern-SDK-Name": "browser-use-sdk",
+                "X-Fern-SDK-Version": "2.0.1",
+                "User-Agent": "browser-use-sdk/2.0.1",
+                "X-Fern-Runtime": core.RUNTIME.type,
+                "X-Fern-Runtime-Version": core.RUNTIME.version,
+            }, _options === null || _options === void 0 ? void 0 : _options.headers) });
+    }
+    get accounts() {
+        var _a;
+        return ((_a = this._accounts) !== null && _a !== void 0 ? _a : (this._accounts = new Client_js_1.Accounts(this._options)));
+    }
+    get tasks() {
+        var _a;
+        return ((_a = this._tasks) !== null && _a !== void 0 ? _a : (this._tasks = new Client_js_2.Tasks(this._options)));
+    }
+    get sessions() {
+        var _a;
+        return ((_a = this._sessions) !== null && _a !== void 0 ? _a : (this._sessions = new Client_js_3.Sessions(this._options)));
+    }
+    get files() {
+        var _a;
+        return ((_a = this._files) !== null && _a !== void 0 ? _a : (this._files = new Client_js_4.Files(this._options)));
+    }
+    get profiles() {
+        var _a;
+        return ((_a = this._profiles) !== null && _a !== void 0 ? _a : (this._profiles = new Client_js_5.Profiles(this._options)));
+    }
+}
+exports.BrowserUseClient = BrowserUseClient;

package/dist/cjs/api/errors/BadRequestError.d.ts

@@ -0,0 +1,8 @@
+/**
+ * This file was auto-generated by Fern from our API Definition.
+ */
+import * as errors from "../../errors/index.js";
+import * as core from "../../core/index.js";
+export declare class BadRequestError extends errors.BrowserUseError {
+    constructor(body?: unknown, rawResponse?: core.RawResponse);
+}