Merge pull request #16 from browser-use/feat/v4-api-support

Add Browser Use Cloud API v4 support, CI, and tests

Author: sauravpanda

.eslintrc.js

@@ -28,6 +28,23 @@ module.exports = {
 		'n8n-nodes-base/node-class-description-inputs-wrong-regular-node': 'off',
 		'n8n-nodes-base/node-class-description-outputs-wrong': 'off',
 	},
+	overrides: [
+		{
+			// Plain CommonJS tests that drive the compiled output; they are deliberately
+			// outside tsconfig.json, so the type-aware parser must not run on them.
+			files: ['test/**/*.js'],
+			parserOptions: {
+				project: null,
+				sourceType: 'script',
+				ecmaVersion: 2022,
+			},
+			rules: {
+				// The package is CommonJS, so require() is the correct import style here.
+				'@typescript-eslint/no-require-imports': 'off',
+				'@typescript-eslint/no-var-requires': 'off',
+			},
+		},
+	],
 	ignorePatterns: [
 		'.eslintrc.js',
 		'dist/**',

.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+# A new push supersedes in-flight runs for the same ref.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    name: Verify (Node ${{ matrix.node-version }})
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        # Floor from package.json engines, plus the version the publish
+        # workflow releases from.
+        node-version: ['22.22', '24']
+
+    steps:
+      - uses: actions/checkout@v4
+
+      # Must precede setup-node so the pnpm store path can be resolved for caching.
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Check formatting
+        run: pnpm format:check
+
+      - name: Lint
+        run: pnpm lint
+
+      - name: Build
+        run: pnpm build
+
+      # Runs against dist/, so it must follow the build step.
+      - name: Test
+        run: pnpm test

.github/workflows/publish.yml

@@ -21,16 +21,34 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: 24
+          cache: pnpm
+
+      - name: Verify tag matches package.json version
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          PKG_VERSION="$(node -p "require('./package.json').version")"
+          if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
+            echo "::error::Tag $GITHUB_REF_NAME does not match package.json version $PKG_VERSION"
+            exit 1
+          fi
+          echo "Publishing version $PKG_VERSION"
 
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
+      - name: Check formatting
+        run: pnpm format:check
+
       - name: Lint
         run: pnpm lint
 
       - name: Build
         run: pnpm build
 
+      - name: Test
+        run: pnpm test
+
       - name: Publish
         run: |
           unset NODE_AUTH_TOKEN

CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 1.2.0
+
+### Added
+
+- Added **V4 Runs, Sessions, and Browsers** to the **API Version** dropdown on the **Browser Use** node.
+- Added v4 **Run** operations: run and wait, create, get, get status, get many, cancel, get events, and get attachments.
+- Added v4 **Session** operations for conversational follow-ups: queue message (with interrupt), get queue, cancel queued message, get, get many, and purge.
+- Added v4 **Browser** operations: create, get, get many, stop, and get downloads.
+- Added v4 run options for model selection, provider-native model parameters, session continuation, workspaces and attached files, judge settings, max cost, and per-run browser settings.
+- Added client-side structured output for v4: the JSON Schema is appended to the task and the result is parsed into `parsedResult`, with `structuredOutputError` describing any mismatch.
+
+### Changed
+
+- Newly added **Browser Use** nodes now default to **v4**, which Browser Use recommends for new integrations. The node gained a second `typeVersion` to do this safely: nodes already on the canvas stay at typeVersion 1 and keep defaulting to v2, while nodes added from now on are typeVersion 2 and default to v4. Changing the default in place would have migrated saved nodes silently, because n8n resolves a missing parameter to its property default and omits default-valued parameters when saving.
+- Labelled **V2 Tasks** as legacy in the **API Version** dropdown.
+- Structured output on v4 now accepts JSON Schema union types such as `["string", "null"]`, checks `required` even when the schema omits `type`, and validates the task length after the starting URL and schema are appended rather than before.
+- Credential testing and the v2 and v3 request paths now also normalise a Base URL saved as `/api/v4`.
+- Moved the shared structured-output templates and the base URL version helper into modules shared by all three API versions, replacing three copies of the same code.
+
+- Raised the minimum Node version from 20.19 to 22.22, matching n8n's own requirement. The development toolchain cannot install on Node 20 at all: `isolated-vm`, a transitive dependency of `n8n-workflow`, fails to compile against Node 20's V8 headers. Node 20 is also past end of life.
+- Added CI running formatting, lint, build, and tests on every pull request and push to main, across Node 22.22 and 24. The repository previously had no CI; lint and build only ran during a tagged publish.
+- Added a test suite covering all three API versions, run with Node's built-in test runner via `pnpm test` and added to `prepublishOnly`. It drives the compiled node against a stubbed HTTP layer, so no API key or network access is needed.
+- Hardened the publish workflow: a `v*` tag whose version does not match `package.json` now fails before publishing, formatting is checked alongside lint and build, and the pnpm store is cached.
+
+### Compatibility
+
+- Existing v2 and v3 workflows are unaffected; their request bodies and endpoints are unchanged, and existing nodes keep their current API version rather than moving to v4.
+- API v4 is not available on Zero Data Retention projects. Those workflows should stay on the v3 API Version; the node returns an explanatory error if v4 is used.
+
 ## 1.1.2
 
 ### Changed

README.md

@@ -1,6 +1,6 @@
 # n8n-nodes-browser-use
 
-An n8n community node package for Browser Use Cloud. The single **Browser Use** node supports both API v2 task workflows and API v3 session-based agent workflows.
+An n8n community node package for Browser Use Cloud. The single **Browser Use** node supports API v4 run workflows, API v3 session-based agent workflows, and the legacy API v2 task workflows.
 
 <p>
   <img src="https://raw.githubusercontent.com/browser-use/browser-use/main/static/browser-use.png" alt="Browser Use" width="360">
@@ -12,7 +12,9 @@ Browser Use Cloud lets AI agents control managed browsers for web research, data
 
 This package includes one n8n node:
 
-- **Browser Use**: choose **API Version** in the node UI to use v2 Tasks or v3 Sessions and Browsers
+- **Browser Use**: choose **API Version** in the node UI to use v4 Runs, v3 Sessions and Browsers, or v2 Tasks
+
+New nodes default to **v4**, which Browser Use recommends for new integrations. Existing workflows keep whichever API version they were saved with.
 
 ## Installation
 
@@ -43,10 +45,70 @@ The default Base URL remains:
 https://api.browser-use.com/api/v2
 ```
 
-Leave the credential Base URL at the default. In the **Browser Use** node, use the **API Version** dropdown to switch between **v2 Tasks** and **v3 Sessions and Browsers**. The node switches the API path internally, so existing credentials continue to work. The node authenticates with the `X-Browser-Use-API-Key` header.
+Leave the credential Base URL at the default. In the **Browser Use** node, use the **API Version** dropdown to switch between **v4 Runs**, **v3 Sessions and Browsers**, and **v2 Tasks**. The node rewrites the trailing `/api/vN` segment internally, so existing credentials continue to work. The node authenticates with the `X-Browser-Use-API-Key` header.
+
+## Choosing an API version
+
+| Version | Use it for | Notes |
+| --- | --- | --- |
+| **v4** (default) | New integrations, hard or long multi-step workflows | Highest accuracy. Not available on Zero Data Retention projects. |
+| **v3** | Cost- and speed-sensitive work | Session-based agents plus standalone cloud browsers. |
+| **v2** | Existing workflows only | Legacy; no longer actively maintained upstream. |
 
 ## Nodes
 
+### API Version: v4 Runs, Sessions, and Browsers
+
+In v4 the unit of work is a **run**. Every run belongs to a **session**, and a session is a conversation: follow-up messages queued onto a session reuse its context and browser state.
+
+#### Run
+
+Operations:
+
+- **Run and Wait**: Dispatch a run, poll `GET /runs/{id}/status` until it reaches `completed`, `failed`, or `cancelled`, then return the full run summary
+- **Create**: Dispatch a run and return immediately with its ID, status, session ID, and events URL
+- **Get**: Retrieve the full run summary including `result`, `error`, token counts, and `totalCostUsd`
+- **Get Status**: Retrieve only the status, which is the cheapest way to poll from your own loop
+- **Get Many**: List runs, optionally filtered to a single session
+- **Cancel**: Cancel a run that is still in flight
+- **Get Events**: Retrieve the step-by-step event stream for a run
+- **Get Attachments**: List files the agent attached to a run
+
+Run options:
+
+- **Model**: `gpt-5.6-luna` (default), the rest of the GPT-5.5/5.6 family, Claude Opus 4.7/4.8/5, Claude Sonnet 5, Claude Fable 5, Gemini 3/3.1/3.5/3.6, GLM 5.2, Grok 4.5, Kimi K3, or MiniMax M3
+- **Model Parameters**: Provider-native parameters forwarded unchanged, e.g. `{"reasoning": {"effort": "high"}}`
+- **Session ID**: Continue an existing conversation instead of starting a new one
+- **Workspace ID** and **Attached File IDs**: Persist and attach files across runs
+- **Judge** and **Judge Context**: Have an LLM judge the finished run; the verdict lands in `judgement`
+- **Max Cost USD**: Cap the total spend of a run
+- **Profile ID**, **Proxy Country Code**, **Disable Proxy**, **Custom Proxy**, **Screen Width/Height**, **Enable Recording**: Browser settings applied when a new browser is provisioned
+
+#### Session
+
+Operations:
+
+- **Queue Message**: Send a follow-up instruction; it runs immediately when the session is idle, or waits its turn. **Interrupt** cancels the active run so the message takes effect now
+- **Get Queue** / **Cancel Queued Message**: Inspect and manage pending messages
+- **Get** / **Get Many**: Session metadata, one entry per conversation
+- **Purge**: Permanently delete a session on a Zero Data Retention project
+
+#### Browser
+
+Standalone cloud browsers, the same computer-use style as v3, plus:
+
+- **Get Downloads**: List files the browser downloaded, with optional presigned URLs
+
+#### Structured output on v4
+
+API v4 has **no server-side output schema** — `run.result` is always a string. When **Extract Structured Data** is enabled, this node appends the JSON Schema to the task as an instruction and parses the returned text into a `parsedResult` field. This is best-effort:
+
+- The raw text always stays in `result`
+- If the text is not JSON, or does not match the schema's type or required properties, `parsedResult` is `null` or partial and `structuredOutputError` explains what happened
+- The run itself is never failed by a parsing problem
+
+Use **v3** if you need the API to enforce the schema server-side.
+
 ### API Version: v2 Tasks
 
 The v2 mode remains available for backward compatibility. It uses the v2 `/tasks` API and keeps the same operations:
@@ -100,6 +162,95 @@ Operations:
 
 Browser options include profile ID, proxy country code, timeout, screen size, resizing, custom proxy, and recording.
 
+## Browser Use v4 Examples
+
+### Run an agent task and wait
+
+```json
+{
+  "apiVersion": "v4",
+  "resource": "run",
+  "operation": "runAndWait",
+  "task": "Find the top 3 trending repositories on GitHub today and summarize why they are trending",
+  "waitTimeout": 900,
+  "runOptions": {
+    "model": "gpt-5.6-luna",
+    "maxCostUsd": 1.5
+  }
+}
+```
+
+The response is the full run summary: `status`, `result`, `error`, `sessionId`, `totalInputTokens`, `totalOutputTokens`, `totalCostUsd`, plus the `eventsUrl` returned when the run was created.
+
+### Continue the same conversation
+
+Pass the `sessionId` from the previous run to start a follow-up run with the same context and browser state.
+
+```json
+{
+  "apiVersion": "v4",
+  "resource": "run",
+  "operation": "runAndWait",
+  "task": "Open the first repository and extract its license and star count",
+  "runOptions": {
+    "sessionId": "SESSION_ID"
+  }
+}
+```
+
+To send a follow-up while a run may still be active, queue it on the session instead:
+
+```json
+{
+  "apiVersion": "v4",
+  "resource": "session",
+  "operation": "queueMessage",
+  "sessionId": "SESSION_ID",
+  "message": "Actually, sort by stars gained this week instead",
+  "queueOptions": {
+    "interrupt": true
+  }
+}
+```
+
+### Request structured output
+
+```json
+{
+  "apiVersion": "v4",
+  "resource": "run",
+  "operation": "runAndWait",
+  "task": "Extract company details from this website",
+  "startUrl": "https://example.com/about",
+  "enableStructuredOutput": true,
+  "schemaTemplate": "custom",
+  "outputSchema": {
+    "type": "object",
+    "properties": {
+      "companyName": { "type": "string" },
+      "industry": { "type": "string" },
+      "summary": { "type": "string" }
+    },
+    "required": ["companyName"]
+  }
+}
+```
+
+The parsed object arrives as `parsedResult`; the agent's raw text stays in `result`.
+
+### Poll a run from your own loop
+
+```json
+{
+  "apiVersion": "v4",
+  "resource": "run",
+  "operation": "getStatus",
+  "runId": "RUN_ID"
+}
+```
+
+`Get Status` returns only `{ id, status }`, so it is cheap to call on a schedule. Fetch the full summary with `Get` once the status is terminal.
+
 ## Browser Use v3 Examples
 
 ### Run an agent task and wait
@@ -180,8 +331,14 @@ The response includes:
 
 The node returns clear n8n errors for authentication failures, validation errors, missing resources, rate limits, and Browser Use API server errors. With n8n's "Continue On Fail" enabled, the error message is returned as item JSON.
 
+On v4 two statuses carry extra context:
+
+- **403**: the API key may lack project access, or the project has Zero Data Retention enabled, which v4 does not support — switch that workflow to the v3 API Version
+- **409**: a session runs one run at a time, so wait for the active run or cancel it first
+
 ## Documentation
 
+- [Browser Use API v4 Reference](https://docs.browser-use.com/cloud/openapi/v4.json)
 - [Browser Use API v3 Reference](https://docs.browser-use.com/cloud/api-reference)
 - [Browser Use API v2 Reference](https://docs.browser-use.com/cloud/api-v2-overview)
 - [Browser Use Dashboard](https://cloud.browser-use.com)

credentials/BrowserUseApi.credentials.ts

@@ -25,7 +25,7 @@ export class BrowserUseApi implements ICredentialType {
 			type: 'string',
 			default: 'https://api.browser-use.com/api/v2',
 			description:
-				'The base URL for the Browser Use API. Leave this as the default; the node switches between v2 and v3 based on the API Version field.',
+				'The base URL for the Browser Use API. Leave this as the default; the node switches between v2, v3, and v4 based on the API Version field.',
 			required: true,
 		},
 	];
@@ -42,7 +42,7 @@ export class BrowserUseApi implements ICredentialType {
 	test: ICredentialTestRequest = {
 		request: {
 			baseURL:
-				'={{$credentials.baseUrl.replace(/\\/api\\/v3\\/?$/, "/api/v2").replace(/\\/$/, "")}}',
+				'={{$credentials.baseUrl.replace(/\\/api\\/v[34]\\/?$/, "/api/v2").replace(/\\/$/, "")}}',
 			url: '/tasks',
 			method: 'GET',
 		},

nodes/BrowserUse/ApiVersion.ts

@@ -0,0 +1,12 @@
+/* eslint-disable n8n-nodes-base/node-filename-against-convention -- Shared helper module, not an n8n node file. */
+
+export type BrowserUseApiVersion = 'v2' | 'v3' | 'v4';
+
+/**
+ * Credentials hold a single Base URL (default `/api/v2`), while each node mode talks to its
+ * own API version. Rewrite a trailing `/api/vN` to the requested version and leave any other
+ * base URL untouched so custom gateways keep working.
+ */
+export function getVersionedBaseUrl(baseUrl: string, version: BrowserUseApiVersion): string {
+	return baseUrl.replace(/\/api\/v[234]\/?$/, `/api/${version}`);
+}