Merge pull request #13 from browser-use/release-please--branches--main--changes--next--components--browser-use-sdk

release: 0.5.0

Author: maticzav

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.4.0"
+  ".": "0.5.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 26
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/browser-use%2Fbrowser-use-758a1c052b93e7e478fa650c1748f4b466653f44cb26f97fef1314c7a96924df.yml
-openapi_spec_hash: 9e0e99b613f2b9bf3993ac36aa0c7911
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/browser-use%2Fbrowser-use-3a9488448292a0736b08b2d6427e702eaf7106d86345ca2e65b64bed4398b036.yml
+openapi_spec_hash: 5ff2781dcc11a0c9aa353f5cb14bcc16
 config_hash: 9d52be5177b2ede4cb0633c04f4cc4ef

CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.5.0 (2025-08-18)
+
+Full Changelog: [v0.4.0...v0.5.0](https://github.com/browser-use/browser-use-node/compare/v0.4.0...v0.5.0)
+
+### Features
+
+* Add start_url ([10e4187](https://github.com/browser-use/browser-use-node/commit/10e4187e952398bb1bd7f1607a0450cca0e25b0f))
+* Align Task Filtering by Status with `status` Field ([1ea0943](https://github.com/browser-use/browser-use-node/commit/1ea0943b3cbca9fb9f40e36c33094756c979ac54))
+
 ## 0.4.0 (2025-08-17)
 
 Full Changelog: [v0.3.0...v0.4.0](https://github.com/browser-use/browser-use-node/compare/v0.3.0...v0.4.0)

package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-use-sdk",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "The official TypeScript library for the Browser Use API",
   "author": "Browser Use <[email protected]>",
   "types": "dist/index.d.ts",

src/lib/bin/commands/listen.ts

@@ -1,6 +1,6 @@
 import { Command } from 'commander';
 
-import { BrowserUse } from '../../../';
+import { APIUserAbortError, BrowserUse } from '../../../';
 import { createWebhookSignature, Webhook } from '../../webhooks';
 import { createBrowserUseClient, getBrowserUseWebhookSecret } from '../auth';
 
@@ -34,6 +34,7 @@ export const listen = new Command('listen')
 
     //
 
+    const startTimeDate = new Date();
     const queue: { current: Webhook[] } = { current: [] };
     const runs: Map<string, BrowserUse.TaskStatus> = new Map();
 
@@ -51,13 +52,26 @@ export const listen = new Command('listen')
 
       const tasks: BrowserUse.Tasks.TaskItemView[] = await client.tasks
         .list(
-          { pageSize: 10 },
+          {
+            pageSize: 10,
+            // NOTE: There's a bug in the API where the datetime needs to be provided in naive format.cur
+            after: startTimeDate.toISOString().replace('Z', ''),
+          },
           {
             signal: tickRef.abort.signal,
           },
         )
         .then((res) => res.items)
-        .catch((_) => []);
+        .catch((err) => {
+          if (err instanceof APIUserAbortError) {
+            return [];
+          }
+
+          console.log(`[polling] ${new Date().toISOString()} failed`);
+          console.error(err);
+
+          return [];
+        });
 
       for (const task of tasks) {
         const currentTaskStatus = runs.get(task.id);

src/resources/tasks.ts

@@ -226,25 +226,18 @@ export class Tasks extends APIResource {
   }
 
   /**
-   * Get a paginated list of all AI agent tasks for the authenticated user.
+   * Get a paginated list of all Browser Use Agent tasks for the authenticated user.
    *
-   * AI agent tasks are the individual jobs that your agents perform within a
-   * session. Each task represents a specific instruction or goal that the agent
+   * Browser Use Agent tasks are the individual jobs that your agents perform within
+   * a session. Each task represents a specific instruction or goal that the agent
    * works on, such as filling out a form, extracting data, or navigating to specific
    * pages.
    *
-   * You can control what data is included for each task:
-   *
-   * - Task steps: Detailed actions the agent took
-   * - User uploaded files: Files you provided for the task
-   * - Output files: Files generated by the agent during the task
-   *
    * Returns:
    *
-   * - A paginated list of agent tasks
-   * - Total count of tasks
+   * - A paginated list of Browser Use Agent tasks
+   * - Total count of Browser Use Agent tasks
    * - Page information for navigation
-   * - Optional detailed data based on your parameters
    */
   list(
     query: TaskListParams | null | undefined = {},
@@ -417,9 +410,10 @@ export interface TaskItemView {
   /**
    * Enumeration of possible task execution states
    *
-   * Attributes: STARTED: Task has been started and is currently running PAUSED: Task
-   * execution has been temporarily paused (can be resumed) STOPPED: Task execution
-   * has been stopped (cannot be resumed) FINISHED: Task has completed successfully
+   * Attributes: STARTED: Task has been started and is currently running. PAUSED:
+   * Task execution has been temporarily paused (can be resumed) FINISHED: Task has
+   * finished and the agent has completed the task. STOPPED: Task execution has been
+   * manually stopped (cannot be resumed).
    */
   status: TaskStatus;
 
@@ -439,11 +433,12 @@ export interface TaskItemView {
 /**
  * Enumeration of possible task execution states
  *
- * Attributes: STARTED: Task has been started and is currently running PAUSED: Task
- * execution has been temporarily paused (can be resumed) STOPPED: Task execution
- * has been stopped (cannot be resumed) FINISHED: Task has completed successfully
+ * Attributes: STARTED: Task has been started and is currently running. PAUSED:
+ * Task execution has been temporarily paused (can be resumed) FINISHED: Task has
+ * finished and the agent has completed the task. STOPPED: Task execution has been
+ * manually stopped (cannot be resumed).
  */
-export type TaskStatus = 'started' | 'paused' | 'stopped' | 'finished';
+export type TaskStatus = 'started' | 'paused' | 'finished' | 'stopped';
 
 /**
  * View model for representing a single step in a task's execution
@@ -501,9 +496,9 @@ export interface TaskView {
    * View model for representing a session that a task belongs to
    *
    * Attributes: id: Unique identifier for the session status: Current status of the
-   * session live_url: URL where the browser can be viewed live in real-time.
-   * started_at: Timestamp when the session was created and started. finished_at:
-   * Timestamp when the session was stopped (None if still active).
+   * session (active/stopped) live_url: URL where the browser can be viewed live in
+   * real-time. started_at: Timestamp when the session was created and started.
+   * finished_at: Timestamp when the session was stopped (None if still active).
    */
   session: TaskView.Session;
 
@@ -514,9 +509,10 @@ export interface TaskView {
   /**
    * Enumeration of possible task execution states
    *
-   * Attributes: STARTED: Task has been started and is currently running PAUSED: Task
-   * execution has been temporarily paused (can be resumed) STOPPED: Task execution
-   * has been stopped (cannot be resumed) FINISHED: Task has completed successfully
+   * Attributes: STARTED: Task has been started and is currently running. PAUSED:
+   * Task execution has been temporarily paused (can be resumed) FINISHED: Task has
+   * finished and the agent has completed the task. STOPPED: Task execution has been
+   * manually stopped (cannot be resumed).
    */
   status: TaskStatus;
 
@@ -542,9 +538,9 @@ export namespace TaskView {
    * View model for representing a session that a task belongs to
    *
    * Attributes: id: Unique identifier for the session status: Current status of the
-   * session live_url: URL where the browser can be viewed live in real-time.
-   * started_at: Timestamp when the session was created and started. finished_at:
-   * Timestamp when the session was stopped (None if still active).
+   * session (active/stopped) live_url: URL where the browser can be viewed live in
+   * real-time. started_at: Timestamp when the session was created and started.
+   * finished_at: Timestamp when the session was stopped (None if still active).
    */
   export interface Session {
     id: string;
@@ -633,19 +629,20 @@ export interface TaskCreateParams {
   task: string;
 
   /**
-   * Configuration settings for the AI agent
+   * Configuration settings for the agent
    *
-   * Attributes: llm: The LLM model to use for the agent profile_id: Unique
-   * identifier of the agent profile to use for the task
+   * Attributes: llm: The LLM model to use for the agent start_url: Optional URL to
+   * start the agent on (will not be changed as a step) profile_id: Unique identifier
+   * of the agent profile to use for the task
    */
   agentSettings?: TaskCreateParams.AgentSettings;
 
   /**
    * Configuration settings for the browser session
    *
    * Attributes: session_id: Unique identifier of existing session to continue
-   * profile_id: Unique identifier of browser profile to use save_browser_data:
-   * Whether to save browser state/data for the user to download later
+   * profile_id: Unique identifier of browser profile to use (use if you want to
+   * start a new session)
    */
   browserSettings?: TaskCreateParams.BrowserSettings;
 
@@ -660,29 +657,30 @@ export interface TaskCreateParams {
 
 export namespace TaskCreateParams {
   /**
-   * Configuration settings for the AI agent
+   * Configuration settings for the agent
    *
-   * Attributes: llm: The LLM model to use for the agent profile_id: Unique
-   * identifier of the agent profile to use for the task
+   * Attributes: llm: The LLM model to use for the agent start_url: Optional URL to
+   * start the agent on (will not be changed as a step) profile_id: Unique identifier
+   * of the agent profile to use for the task
    */
   export interface AgentSettings {
     llm?: TasksAPI.LlmModel;
 
     profileId?: string | null;
+
+    startUrl?: string | null;
   }
 
   /**
    * Configuration settings for the browser session
    *
    * Attributes: session_id: Unique identifier of existing session to continue
-   * profile_id: Unique identifier of browser profile to use save_browser_data:
-   * Whether to save browser state/data for the user to download later
+   * profile_id: Unique identifier of browser profile to use (use if you want to
+   * start a new session)
    */
   export interface BrowserSettings {
     profileId?: string | null;
 
-    saveBrowserData?: boolean;
-
     sessionId?: string | null;
   }
 }
@@ -699,14 +697,19 @@ export interface TaskUpdateParams {
 }
 
 export interface TaskListParams {
+  after?: string | null;
+
+  before?: string | null;
+
   /**
-   * Enumeration of possible task filters
+   * Enumeration of possible task execution states
    *
-   * Attributes: STARTED: All started tasks PAUSED: All paused tasks STOPPED: All
-   * stopped tasks FINISHED: All finished tasks SUCCESSFUL: All successful tasks
-   * UNSUCCESSFUL: All unsuccessful tasks
+   * Attributes: STARTED: Task has been started and is currently running. PAUSED:
+   * Task execution has been temporarily paused (can be resumed) FINISHED: Task has
+   * finished and the agent has completed the task. STOPPED: Task execution has been
+   * manually stopped (cannot be resumed).
    */
-  filterBy?: 'started' | 'paused' | 'stopped' | 'finished' | 'successful' | 'unsuccessful' | null;
+  filterBy?: TaskStatus | null;
 
   pageNumber?: number;
 

src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.4.0'; // x-release-please-version
+export const VERSION = '0.5.0'; // x-release-please-version

tests/api-resources/tasks.test.ts

@@ -24,10 +24,13 @@ describe('resource tasks', () => {
   test.skip('create: required and optional params', async () => {
     const response = await client.tasks.create({
       task: 'x',
-      agentSettings: { llm: 'gpt-4o', profileId: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e' },
+      agentSettings: {
+        llm: 'gpt-4o',
+        profileId: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
+        startUrl: 'startUrl',
+      },
       browserSettings: {
         profileId: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
-        saveBrowserData: true,
         sessionId: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
       },
       includedFileNames: ['string'],
@@ -84,6 +87,8 @@ describe('resource tasks', () => {
     await expect(
       client.tasks.list(
         {
+          after: '2019-12-27T18:11:19.117Z',
+          before: '2019-12-27T18:11:19.117Z',
           filterBy: 'started',
           pageNumber: 1,
           pageSize: 1,