browser-use-sdk 3.3.1 → 3.3.2

package/README.md

@@ -1,213 +1,32 @@
 # browser-use-sdk
 
-Official TypeScript SDK for the [Browser Use](https://browser-use.com) API -- run AI-powered browser agents in the cloud.
+Official TypeScript SDK for [Browser Use Cloud](https://browser-use.com).
 
-## Installation
+## Install
 
 ```bash
 npm install browser-use-sdk
-# or
-pnpm add browser-use-sdk
-# or
-yarn add browser-use-sdk
-# or
-bun add browser-use-sdk
 ```
 
-## Quick Start (v2)
+## Quick Start
 
-The default import exposes the **v2** API client.
+Get your API key at [cloud.browser-use.com/settings](https://cloud.browser-use.com/settings?tab=api-keys&new=1).
 
-```ts
-import { BrowserUse } from "browser-use-sdk";
-
-const client = new BrowserUse();
-
-const result = await client.run("Find the top post on Hacker News");
-console.log(result.output);
-console.log(result.id, result.status);
+```bash
+export BROWSER_USE_API_KEY=your_key
 ```
 
-## V3 (Experimental)
-
-The v3 API uses a unified session model. Import from `browser-use-sdk/v3`:
-
-```ts
-import { BrowserUse } from "browser-use-sdk/v3";
+```typescript
+import { BrowserUse } from "browser-use-sdk";
 
 const client = new BrowserUse();
-
-const output = await client.run("Find the top post on HN");
-console.log(output);
-```
-
-## Client Options
-
-```ts
-const client = new BrowserUse({
-  apiKey: "bu_...",           // Or set BROWSER_USE_API_KEY env var
-  baseUrl: "https://...",     // Override API base URL
-  maxRetries: 3,              // Retry on 429 (default: 3)
-  timeout: 30_000,            // Request timeout in ms (default: 30s)
-});
-```
-
-## Structured Output
-
-Pass a Zod schema to get typed results:
-
-```ts
-import { z } from "zod";
-
-const Product = z.object({ name: z.string(), price: z.number() });
-
-const result = await client.run("Find the price of the MacBook Air", { schema: Product });
-console.log(`${result.output.name}: $${result.output.price}`);
-```
-
-## Polling and Streaming
-
-`client.run()` returns a dual-purpose handle: `await` it for the output, or `for await...of` it for step-by-step progress.
-
-### Wait for Result
-
-```ts
-const result = await client.run("Search for AI news");
-console.log(result.output, result.id, result.status);
-```
-
-### Stream Steps
-
-```ts
-for await (const step of client.run("Search for AI news")) {
-  console.log(`[${step.number}] ${step.nextGoal} — ${step.url}`);
-}
-```
-
-## V2 API Reference
-
-### Billing
-
-| Method                | Description                          |
-|-----------------------|--------------------------------------|
-| `billing.account()`  | Get account info and credit balance  |
-
-### Tasks
-
-| Method                       | Description                             |
-|------------------------------|-----------------------------------------|
-| `tasks.create(body)`        | Create and start a new task             |
-| `tasks.list(params?)`       | List tasks with optional filtering      |
-| `tasks.get(taskId)`         | Get detailed task information           |
-| `tasks.stop(taskId)`        | Stop a running task                     |
-| `tasks.status(taskId)`      | Lightweight status for polling          |
-| `tasks.wait(taskId, opts?)` | Poll until terminal, return TaskView    |
-| `tasks.logs(taskId)`        | Get download URL for task logs          |
-
-### Sessions
-
-| Method                             | Description                          |
-|------------------------------------|--------------------------------------|
-| `sessions.create(body?)`          | Create a new session                 |
-| `sessions.list(params?)`          | List sessions                        |
-| `sessions.get(sessionId)`         | Get session details                  |
-| `sessions.stop(sessionId)`        | Stop session and running tasks       |
-| `sessions.delete(sessionId)`      | Delete session and all tasks         |
-| `sessions.getShare(sessionId)`    | Get public share info                |
-| `sessions.createShare(sessionId)` | Create public share link             |
-| `sessions.deleteShare(sessionId)` | Remove public share                  |
-
-### Files
-
-| Method                                  | Description                            |
-|-----------------------------------------|----------------------------------------|
-| `files.sessionUrl(sessionId, body)`    | Presigned URL for session file upload  |
-| `files.browserUrl(sessionId, body)`    | Presigned URL for browser file upload  |
-| `files.taskOutput(taskId, fileId)`     | Download URL for task output file      |
-
-### Profiles
-
-| Method                            | Description                  |
-|-----------------------------------|------------------------------|
-| `profiles.create(body?)`         | Create a browser profile     |
-| `profiles.list(params?)`         | List profiles                |
-| `profiles.get(profileId)`        | Get profile details          |
-| `profiles.update(profileId, body)` | Update a profile           |
-| `profiles.delete(profileId)`     | Delete a profile             |
-
-### Browsers
-
-| Method                        | Description                        |
-|-------------------------------|------------------------------------|
-| `browsers.create(body)`      | Create a browser session           |
-| `browsers.list(params?)`     | List browser sessions              |
-| `browsers.get(sessionId)`    | Get browser session details        |
-| `browsers.stop(sessionId)`   | Stop a browser session             |
-
-### Skills
-
-| Method                                         | Description                          |
-|------------------------------------------------|--------------------------------------|
-| `skills.create(body)`                         | Create a skill via generation        |
-| `skills.list(params?)`                        | List skills                          |
-| `skills.get(skillId)`                         | Get skill details                    |
-| `skills.delete(skillId)`                      | Delete a skill                       |
-| `skills.update(skillId, body)`                | Update skill metadata                |
-| `skills.cancel(skillId)`                      | Cancel in-progress generation        |
-| `skills.execute(skillId, body)`               | Execute a skill                      |
-| `skills.refine(skillId, body)`                | Refine a skill with feedback         |
-| `skills.rollback(skillId)`                    | Rollback to previous version         |
-| `skills.executions(skillId, params?)`         | List skill executions                |
-| `skills.executionOutput(skillId, executionId)` | Download execution output           |
-
-### Marketplace
-
-| Method                              | Description                         |
-|-------------------------------------|-------------------------------------|
-| `marketplace.list(params?)`        | List public marketplace skills      |
-| `marketplace.get(skillSlug)`       | Get marketplace skill by slug       |
-| `marketplace.clone(skillId)`       | Clone a marketplace skill           |
-| `marketplace.execute(skillId, body)` | Execute a marketplace skill       |
-
-## V3 API Reference
-
-### Sessions
-
-| Method                               | Description                          |
-|--------------------------------------|--------------------------------------|
-| `sessions.create(body)`             | Create session and run a task        |
-| `sessions.list(params?)`            | List sessions                        |
-| `sessions.get(sessionId)`           | Get session details                  |
-| `sessions.stop(sessionId)`          | Stop a session                       |
-| `sessions.files(sessionId, params?)` | List files in session workspace     |
-
-## Error Handling
-
-All API errors throw `BrowserUseError`:
-
-```ts
-import { BrowserUse, BrowserUseError } from "browser-use-sdk";
-
-try {
-  await client.tasks.get("nonexistent-id");
-} catch (err) {
-  if (err instanceof BrowserUseError) {
-    console.error(err.statusCode); // 404
-    console.error(err.message);    // "Task not found"
-    console.error(err.detail);     // Raw error body
-  }
-}
+const result = await client.run("Find the top 3 trending repos on GitHub today");
+console.log(result.output);
 ```
 
-The client automatically retries on `429` (rate limit) with exponential backoff.
+## Docs
 
-## TypeScript
-
-Types are re-exported from `browser-use-sdk` and `browser-use-sdk/v3`. The SDK ships with full type definitions for all request/response shapes.
-
-```ts
-import type { TaskView, CreateTaskRequest } from "browser-use-sdk";
-```
+[docs.browser-use.com](https://docs.browser-use.com)
 
 ## License
 

package/dist/index.d.cts

@@ -1788,10 +1788,11 @@ interface components {
          *             CREATED: Task has been created but not yet started.
          *         STARTED: Task has been started and is currently running.
          *         FINISHED: Task has finished and the agent has completed the task.
+         *         FAILED: Task execution failed due to an error.
          *         STOPPED: Task execution has been manually stopped (cannot be resumed).
          * @enum {string}
          */
-        TaskStatus: "created" | "started" | "finished" | "stopped";
+        TaskStatus: "created" | "started" | "finished" | "failed" | "stopped";
         /**
          * TaskStatusView
          * @description Lightweight view optimized for polling. Use GET /tasks/{id}/status for efficient polling

package/dist/index.d.ts

@@ -1788,10 +1788,11 @@ interface components {
          *             CREATED: Task has been created but not yet started.
          *         STARTED: Task has been started and is currently running.
          *         FINISHED: Task has finished and the agent has completed the task.
+         *         FAILED: Task execution failed due to an error.
          *         STOPPED: Task execution has been manually stopped (cannot be resumed).
          * @enum {string}
          */
-        TaskStatus: "created" | "started" | "finished" | "stopped";
+        TaskStatus: "created" | "started" | "finished" | "failed" | "stopped";
         /**
          * TaskStatusView
          * @description Lightweight view optimized for polling. Use GET /tasks/{id}/status for efficient polling

package/dist/v3.cjs

@@ -6,6 +6,71 @@ var _chunkRIRVOEIUcjs = require('./chunk-RIRVOEIU.cjs');
 // src/v3/client.ts
 var _zod = require('zod');
 
+// src/v3/resources/billing.ts
+var Billing = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /** Get account billing information. */
+  account() {
+    return this.http.get("/billing/account");
+  }
+};
+
+// src/v3/resources/browsers.ts
+var Browsers = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /** Create a standalone browser session. */
+  create(body) {
+    return this.http.post("/browsers", body);
+  }
+  /** List browser sessions for the authenticated project. */
+  list(params) {
+    return this.http.get("/browsers", params);
+  }
+  /** Get browser session details. */
+  get(sessionId) {
+    return this.http.get(`/browsers/${sessionId}`);
+  }
+  /** Update a browser session (e.g. stop it). */
+  update(sessionId, body) {
+    return this.http.patch(`/browsers/${sessionId}`, body);
+  }
+  /** Stop a browser session. Convenience wrapper around update. */
+  stop(sessionId) {
+    return this.update(sessionId, { action: "stop" });
+  }
+};
+
+// src/v3/resources/profiles.ts
+var Profiles = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /** Create a browser profile. */
+  create(body) {
+    return this.http.post("/profiles", body);
+  }
+  /** List profiles for the authenticated project. */
+  list(params) {
+    return this.http.get("/profiles", params);
+  }
+  /** Get profile details. */
+  get(profileId) {
+    return this.http.get(`/profiles/${profileId}`);
+  }
+  /** Update a profile. */
+  update(profileId, body) {
+    return this.http.patch(`/profiles/${profileId}`, body);
+  }
+  /** Delete a profile. */
+  delete(profileId) {
+    return this.http.delete(`/profiles/${profileId}`);
+  }
+};
+
 // src/v3/resources/sessions.ts
 var Sessions = class {
   constructor(http) {
@@ -13,7 +78,7 @@ var Sessions = class {
   }
   /** Create a session and optionally dispatch a task. */
   create(body) {
-    return this.http.post("/sessions", body);
+    return this.http.post("/sessions", _nullishCoalesce(body, () => ( {})));
   }
   /** List sessions for the authenticated project. */
   list(params) {
@@ -49,9 +114,69 @@ var Sessions = class {
       params
     );
   }
+  /**
+   * Poll until recording URLs are available. Returns presigned MP4 URLs.
+   *
+   * Returns an empty array if no recording was produced (e.g. the agent
+   * answered without opening a browser, or recording was not enabled).
+   */
+  async waitForRecording(sessionId, options) {
+    const timeout = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _ => _.timeout]), () => ( 15e3));
+    const interval = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _2 => _2.interval]), () => ( 2e3));
+    const deadline = Date.now() + timeout;
+    while (Date.now() < deadline) {
+      const session = await this.get(sessionId);
+      if (_optionalChain([session, 'access', _3 => _3.recordingUrls, 'optionalAccess', _4 => _4.length])) return session.recordingUrls;
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) break;
+      await new Promise((r) => setTimeout(r, Math.min(interval, remaining)));
+    }
+    return [];
+  }
 };
 
 // src/v3/resources/workspaces.ts
+var _fs = require('fs');
+var _path = require('path');
+function safeJoin(base, untrusted) {
+  const baseResolved = _path.resolve.call(void 0, base) + "/";
+  const resolved = _path.resolve.call(void 0, base, untrusted);
+  if (resolved !== _path.resolve.call(void 0, base) && !resolved.startsWith(baseResolved)) {
+    throw new Error(`Path traversal detected: ${untrusted}`);
+  }
+  return resolved;
+}
+var MIME_TYPES = {
+  ".csv": "text/csv",
+  ".json": "application/json",
+  ".txt": "text/plain",
+  ".md": "text/markdown",
+  ".html": "text/html",
+  ".xml": "application/xml",
+  ".yaml": "application/yaml",
+  ".yml": "application/yaml",
+  ".pdf": "application/pdf",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".svg": "image/svg+xml",
+  ".mp4": "video/mp4",
+  ".mp3": "audio/mpeg",
+  ".wav": "audio/wav",
+  ".zip": "application/zip",
+  ".gz": "application/gzip",
+  ".tar": "application/x-tar",
+  ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  ".xls": "application/vnd.ms-excel",
+  ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  ".doc": "application/msword",
+  ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation"
+};
+function guessContentType(path) {
+  return _nullishCoalesce(MIME_TYPES[_path.extname.call(void 0, path).toLowerCase()], () => ( "application/octet-stream"));
+}
 var Workspaces = class {
   constructor(http) {
     this.http = http;
@@ -99,6 +224,79 @@ var Workspaces = class {
   size(workspaceId) {
     return this.http.get(`/workspaces/${workspaceId}/size`);
   }
+  /**
+   * Upload local files to a workspace. Returns the list of remote paths.
+   *
+   * ```ts
+   * await client.workspaces.upload(wsId, "data.csv", "config.json");
+   * ```
+   */
+  async upload(workspaceId, ...paths) {
+    const items = paths.map((p) => ({
+      name: _path.basename.call(void 0, p),
+      contentType: guessContentType(p),
+      size: _fs.statSync.call(void 0, p).size
+    }));
+    const resp = await this.uploadFiles(workspaceId, { files: items });
+    for (let i = 0; i < paths.length; i++) {
+      const body = _fs.readFileSync.call(void 0, paths[i]);
+      const res = await fetch(resp.files[i].uploadUrl, {
+        method: "PUT",
+        headers: { "Content-Type": items[i].contentType },
+        body
+      });
+      if (!res.ok) throw new Error(`Upload failed: ${res.status} ${res.statusText}`);
+    }
+    return resp.files.map((f) => f.path);
+  }
+  /**
+   * Download a single file from a workspace. Returns the local path.
+   *
+   * ```ts
+   * const local = await client.workspaces.download(wsId, "uploads/data.csv", { to: "./data.csv" });
+   * ```
+   */
+  async download(workspaceId, path, options) {
+    const fileList = await this.files(workspaceId, { prefix: path, includeUrls: true });
+    const match = _optionalChain([fileList, 'access', _5 => _5.files, 'optionalAccess', _6 => _6.find, 'call', _7 => _7((f) => f.path === path)]);
+    if (!match) throw new Error(`File not found in workspace: ${path}`);
+    const dest = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _8 => _8.to]), () => ( _path.basename.call(void 0, match.path)));
+    _fs.mkdirSync.call(void 0, _path.dirname.call(void 0, dest), { recursive: true });
+    const resp = await fetch(match.url);
+    if (!resp.ok) throw new Error(`Download failed: ${resp.status}`);
+    _fs.writeFileSync.call(void 0, dest, Buffer.from(await resp.arrayBuffer()));
+    return dest;
+  }
+  /**
+   * Download all files from a workspace. Returns list of local paths.
+   *
+   * ```ts
+   * const paths = await client.workspaces.downloadAll(wsId, { to: "./output" });
+   * ```
+   */
+  async downloadAll(workspaceId, options) {
+    const destDir = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _9 => _9.to]), () => ( "."));
+    _fs.mkdirSync.call(void 0, destDir, { recursive: true });
+    const results = [];
+    let cursor;
+    do {
+      const fileList = await this.files(workspaceId, {
+        prefix: _optionalChain([options, 'optionalAccess', _10 => _10.prefix]),
+        includeUrls: true,
+        cursor
+      });
+      for (const f of _nullishCoalesce(fileList.files, () => ( []))) {
+        const local = safeJoin(destDir, f.path);
+        _fs.mkdirSync.call(void 0, _path.dirname.call(void 0, local), { recursive: true });
+        const resp = await fetch(f.url);
+        if (!resp.ok) throw new Error(`Download failed for ${f.path}: ${resp.status}`);
+        _fs.writeFileSync.call(void 0, local, Buffer.from(await resp.arrayBuffer()));
+        results.push(local);
+      }
+      cursor = fileList.hasMore ? _nullishCoalesce(fileList.nextCursor, () => ( void 0)) : void 0;
+    } while (cursor);
+    return results;
+  }
 };
 
 // src/v3/helpers.ts
@@ -115,8 +313,8 @@ var SessionRun = (_class = class {
     this._createPromise = createPromise;
     this._sessions = sessions;
     this._schema = schema;
-    this._timeout = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _ => _.timeout]), () => ( 3e5));
-    this._interval = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _2 => _2.interval]), () => ( 2e3));
+    this._timeout = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _11 => _11.timeout]), () => ( 144e5));
+    this._interval = _nullishCoalesce(_optionalChain([options, 'optionalAccess', _12 => _12.interval]), () => ( 2e3));
   }
   /** The session ID, available after task creation resolves. */
   get sessionId() {
@@ -158,6 +356,40 @@ var SessionRun = (_class = class {
       `Session ${sessionId} did not complete within ${this._timeout}ms`
     );
   }
+  /**
+   * Enable `for await (const msg of client.run(...))` — yields messages as they appear.
+   * After iteration, `.result` contains the final SessionResult.
+   */
+  async *[Symbol.asyncIterator]() {
+    const sessionId = await this._ensureSessionId();
+    let cursor;
+    const deadline = Date.now() + this._timeout;
+    while (Date.now() < deadline) {
+      const resp = await this._sessions.messages(sessionId, { after: cursor, limit: 100 });
+      for (const msg of resp.messages) {
+        yield msg;
+        cursor = msg.id;
+      }
+      const session = await this._sessions.get(sessionId);
+      if (TERMINAL_STATUSES.has(session.status)) {
+        while (true) {
+          const page = await this._sessions.messages(sessionId, { after: cursor, limit: 100 });
+          if (!page.messages.length) break;
+          for (const msg of page.messages) {
+            yield msg;
+            cursor = msg.id;
+          }
+        }
+        const { output, ...rest } = session;
+        this._result = { ...rest, output: this._parseOutput(output) };
+        return;
+      }
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) break;
+      await new Promise((r) => setTimeout(r, Math.min(this._interval, remaining)));
+    }
+    throw new Error(`Session ${sessionId} did not complete within ${this._timeout}ms`);
+  }
   _parseOutput(output) {
     if (output == null) return null;
     if (!this._schema) return output;
@@ -172,6 +404,9 @@ var BrowserUse = class {
   
   
   
+  
+  
+  
   constructor(options = {}) {
     const apiKey = _nullishCoalesce(_nullishCoalesce(options.apiKey, () => ( process.env.BROWSER_USE_API_KEY)), () => ( ""));
     if (!apiKey) {
@@ -185,6 +420,9 @@ var BrowserUse = class {
       maxRetries: options.maxRetries,
       timeout: options.timeout
     });
+    this.billing = new Billing(this.http);
+    this.browsers = new Browsers(this.http);
+    this.profiles = new Profiles(this.http);
     this.sessions = new Sessions(this.http);
     this.workspaces = new Workspaces(this.http);
   }
@@ -194,6 +432,9 @@ var BrowserUse = class {
     if (schema) {
       body.outputSchema = _zod.z.toJSONSchema(schema);
     }
+    if (body.sessionId && body.keepAlive === void 0) {
+      body.keepAlive = true;
+    }
     const promise = this.sessions.create(body);
     return new SessionRun(promise, this.sessions, schema, { timeout, interval });
   }
@@ -204,5 +445,8 @@ var BrowserUse = class {
 
 
 
-exports.BrowserUse = BrowserUse; exports.BrowserUseError = _chunkRIRVOEIUcjs.BrowserUseError; exports.SessionRun = SessionRun; exports.Sessions = Sessions; exports.Workspaces = Workspaces;
+
+
+
+exports.Billing = Billing; exports.BrowserUse = BrowserUse; exports.BrowserUseError = _chunkRIRVOEIUcjs.BrowserUseError; exports.Browsers = Browsers; exports.Profiles = Profiles; exports.SessionRun = SessionRun; exports.Sessions = Sessions; exports.Workspaces = Workspaces;
 //# sourceMappingURL=v3.cjs.map