release: 3.21.0

.github/workflows/ci.yml

@@ -22,10 +22,10 @@ jobs:
     if: (github.event_name == 'push' || github.event.pull_request.head.repo.fork) && (github.event_name != 'push' || github.event.head_commit.message != 'codegen metadata')
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Set up Java
-        uses: actions/setup-java@v5
+        uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
         with:
           distribution: temurin
           java-version: |
@@ -34,7 +34,7 @@ jobs:
           cache: gradle
 
       - name: Set up Gradle
-        uses: gradle/actions/setup-gradle@v4
+        uses: gradle/actions/setup-gradle@ed408507eac070d1f99cc633dbcf757c94c7933a # v4.4.3
 
       - name: Run lints
         run: ./scripts/lint
@@ -49,10 +49,10 @@ jobs:
     if: (github.event_name == 'push' || github.event.pull_request.head.repo.fork) && (github.event_name != 'push' || github.event.head_commit.message != 'codegen metadata')
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Set up Java
-        uses: actions/setup-java@v5
+        uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
         with:
           distribution: temurin
           java-version: |
@@ -61,7 +61,7 @@ jobs:
           cache: gradle
 
       - name: Set up Gradle
-        uses: gradle/actions/setup-gradle@v4
+        uses: gradle/actions/setup-gradle@ed408507eac070d1f99cc633dbcf757c94c7933a # v4.4.3
 
       - name: Build SDK
         run: ./scripts/build
@@ -71,7 +71,7 @@ jobs:
           github.repository == 'stainless-sdks/stagehand-java' &&
           !startsWith(github.ref, 'refs/heads/stl/')
         id: github-oidc
-        uses: actions/github-script@v8
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
         with:
           script: core.setOutput('github_token', await core.getIDToken());
 
@@ -91,10 +91,10 @@ jobs:
     runs-on: ${{ github.repository == 'stainless-sdks/stagehand-java' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
     if: github.event_name == 'push' || github.event.pull_request.head.repo.fork
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Set up Java
-        uses: actions/setup-java@v5
+        uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
         with:
           distribution: temurin
           java-version: |
@@ -103,7 +103,7 @@ jobs:
           cache: gradle
 
       - name: Set up Gradle
-        uses: gradle/gradle-build-action@v2
+        uses: gradle/gradle-build-action@a8f75513eafdebd8141bd1cd4e30fcd194af8dfa # v2.12.0
 
       - name: Run tests
         run: ./scripts/test

.github/workflows/publish-sonatype.yml

@@ -14,10 +14,10 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Set up Java
-        uses: actions/setup-java@v5
+        uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
         with:
           distribution: temurin
           java-version: |
@@ -26,7 +26,7 @@ jobs:
           cache: gradle
 
       - name: Set up Gradle
-        uses: gradle/gradle-build-action@v2
+        uses: gradle/gradle-build-action@a8f75513eafdebd8141bd1cd4e30fcd194af8dfa # v2.12.0
 
       - name: Publish to Sonatype
         run: |-

.github/workflows/release-doctor.yml

@@ -12,7 +12,7 @@ jobs:
     if: github.repository == 'browserbase/stagehand-java' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch' || startsWith(github.head_ref, 'release-please') || github.head_ref == 'next')
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Check release environment
         run: |

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "3.20.0"
+  ".": "3.21.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 8
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/browserbase/stagehand-6f6bfb81d092f30a5e2005328c97d61b9ea36132bb19e9e79e55294b9534ce20.yml
-openapi_spec_hash: f3fc1e3688a38dc2c28f7178f7d534e5
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/browserbase/stagehand-c7910965e66e73ad8b65b6cc391d431094b2a6c6577c3e9d82feaa8138e74cff.yml
+openapi_spec_hash: 37748bb69c22a9ce721d9b5a5861f964
 config_hash: 1fb12ae9b478488bc1e56bfbdc210b01

CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 3.21.0 (2026-05-29)
+
+Full Changelog: [v3.20.0...v3.21.0](https://github.com/browserbase/stagehand-java/compare/v3.20.0...v3.21.0)
+
+### Features
+
+* [feat]: add `ignoreSelectors` to `observe()` ([aa7ad0c](https://github.com/browserbase/stagehand-java/commit/aa7ad0c2033478107f3944b625d1b172b8f39e83))
+* [STG-1756] forward Vertex model config ([b37b827](https://github.com/browserbase/stagehand-java/commit/b37b827f38cc168d12e0d3a355f25a137796f5d7))
+* Add `screenshot` option to Extract ([043d138](https://github.com/browserbase/stagehand-java/commit/043d138a98a8caab6bc2c59c2abb0a864019c3c5))
+* **client:** improve logging ([1d84566](https://github.com/browserbase/stagehand-java/commit/1d845661917baf3d12a97286cf760e0d0fda0218))
+* STG-1756 add Vertex auth params to Stagehand spec ([f072067](https://github.com/browserbase/stagehand-java/commit/f072067e7adef04886423e1232e6b7e42e5f8a28))
+
+
+### Bug Fixes
+
+* **java:** update model config examples ([991a894](https://github.com/browserbase/stagehand-java/commit/991a894f6c93371eaf18a5878a41a4e27928adc8))
+
+
+### Chores
+
+* redact api-key headers in debug logs ([ce7e1d2](https://github.com/browserbase/stagehand-java/commit/ce7e1d278d5f7a9ceda6bc3108ed8d097f9b313d))
+
 ## 3.20.0 (2026-05-06)
 
 Full Changelog: [v3.19.3...v3.20.0](https://github.com/browserbase/stagehand-java/compare/v3.19.3...v3.20.0)

README.md

@@ -2,8 +2,8 @@
 
 <!-- x-release-please-start-version -->
 
-[![Maven Central](https://img.shields.io/maven-central/v/com.browserbase.api/stagehand-java)](https://central.sonatype.com/artifact/com.browserbase.api/stagehand-java/3.20.0)
-[![javadoc](https://javadoc.io/badge2/com.browserbase.api/stagehand-java/3.20.0/javadoc.svg)](https://javadoc.io/doc/com.browserbase.api/stagehand-java/3.20.0)
+[![Maven Central](https://img.shields.io/maven-central/v/com.browserbase.api/stagehand-java)](https://central.sonatype.com/artifact/com.browserbase.api/stagehand-java/3.21.0)
+[![javadoc](https://javadoc.io/badge2/com.browserbase.api/stagehand-java/3.21.0/javadoc.svg)](https://javadoc.io/doc/com.browserbase.api/stagehand-java/3.21.0)
 
 <!-- x-release-please-end -->
 
@@ -85,7 +85,7 @@ Most existing browser automation tools either require you to write low-level cod
 ### Gradle
 
 ```kotlin
-implementation("com.browserbase.api:stagehand-java:3.20.0")
+implementation("com.browserbase.api:stagehand-java:3.21.0")
 ```
 
 ### Maven
@@ -94,7 +94,7 @@ implementation("com.browserbase.api:stagehand-java:3.20.0")
 <dependency>
   <groupId>com.browserbase.api</groupId>
   <artifactId>stagehand-java</artifactId>
-  <version>3.20.0</version>
+  <version>3.21.0</version>
 </dependency>
 ```
 
@@ -526,8 +526,6 @@ The SDK throws custom unchecked exception types:
 
 ## Logging
 
-The SDK uses the standard [OkHttp logging interceptor](https://github.com/square/okhttp/tree/master/okhttp-logging-interceptor).
-
 Enable logging by setting the `STAGEHAND_LOG` environment variable to `info`:
 
 ```sh
@@ -540,6 +538,19 @@ Or to `debug` for more verbose logging:
 export STAGEHAND_LOG=debug
 ```
 
+Or configure the client manually using the `logLevel` method:
+
+```java
+import com.browserbase.api.client.StagehandClient;
+import com.browserbase.api.client.okhttp.StagehandOkHttpClient;
+import com.browserbase.api.core.LogLevel;
+
+StagehandClient client = StagehandOkHttpClient.builder()
+    .fromEnv()
+    .logLevel(LogLevel.INFO)
+    .build();
+```
+
 ## ProGuard and R8
 
 Although the SDK uses reflection, it is still usable with [ProGuard](https://github.com/Guardsquare/proguard) and [R8](https://developer.android.com/topic/performance/app-optimization/enable-app-optimization) because `stagehand-java-core` is published with a [configuration file](stagehand-java-core/src/main/resources/META-INF/proguard/stagehand-java-core.pro) containing [keep rules](https://www.guardsquare.com/manual/configuration/usage).

build.gradle.kts

@@ -8,7 +8,7 @@ repositories {
 
 allprojects {
     group = "com.browserbase.api"
-    version = "3.20.0" // x-release-please-version
+    version = "3.21.0" // x-release-please-version
 }
 
 subprojects {

stagehand-java-client-okhttp/build.gradle.kts

@@ -7,7 +7,6 @@ dependencies {
     api(project(":stagehand-java-core"))
 
     implementation("com.squareup.okhttp3:okhttp:4.12.0")
-    implementation("com.squareup.okhttp3:logging-interceptor:4.12.0")
 
     testImplementation(kotlin("test"))
     testImplementation("org.assertj:assertj-core:3.27.7")

stagehand-java-client-okhttp/src/main/kotlin/com/browserbase/api/client/okhttp/OkHttpClient.kt

@@ -35,7 +35,6 @@ import okhttp3.Request
 import okhttp3.RequestBody
 import okhttp3.RequestBody.Companion.toRequestBody
 import okhttp3.Response
-import okhttp3.logging.HttpLoggingInterceptor
 import okio.BufferedSink
 import okio.buffer
 import okio.sink
@@ -93,21 +92,6 @@ internal constructor(@JvmSynthetic internal val okHttpClient: okhttp3.OkHttpClie
     private fun newCall(request: HttpRequest, requestOptions: RequestOptions): Call {
         val clientBuilder = okHttpClient.newBuilder()
 
-        val logLevel =
-            when (System.getenv("STAGEHAND_LOG")?.lowercase()) {
-                "info" -> HttpLoggingInterceptor.Level.BASIC
-                "debug" -> HttpLoggingInterceptor.Level.BODY
-                else -> null
-            }
-        if (logLevel != null) {
-            clientBuilder.addNetworkInterceptor(
-                HttpLoggingInterceptor().setLevel(logLevel).apply {
-                    redactHeader("x-bb-api-key")
-                    redactHeader("x-model-api-key")
-                }
-            )
-        }
-
         requestOptions.timeout?.let {
             clientBuilder
                 .connectTimeout(it.connect())

stagehand-java-client-okhttp/src/main/kotlin/com/browserbase/api/client/okhttp/StagehandOkHttpClient.kt

@@ -5,6 +5,7 @@ package com.browserbase.api.client.okhttp
 import com.browserbase.api.client.StagehandClient
 import com.browserbase.api.client.StagehandClientImpl
 import com.browserbase.api.core.ClientOptions
+import com.browserbase.api.core.LogLevel
 import com.browserbase.api.core.Sleeper
 import com.browserbase.api.core.Timeout
 import com.browserbase.api.core.http.AsyncStreamResponse
@@ -290,6 +291,15 @@ class StagehandOkHttpClient private constructor() {
          */
         fun maxRetries(maxRetries: Int) = apply { clientOptions.maxRetries(maxRetries) }
 
+        /**
+         * The level at which to log request and response information.
+         *
+         * [fromEnv] will set the level from environment variables. See [LogLevel.fromEnv].
+         *
+         * Defaults to [LogLevel.fromEnv].
+         */
+        fun logLevel(logLevel: LogLevel) = apply { clientOptions.logLevel(logLevel) }
+
         /** Your [Browserbase API Key](https://www.browserbase.com/settings) */
         fun browserbaseApiKey(browserbaseApiKey: String) = apply {
             clientOptions.browserbaseApiKey(browserbaseApiKey)

stagehand-java-client-okhttp/src/main/kotlin/com/browserbase/api/client/okhttp/StagehandOkHttpClientAsync.kt

@@ -5,6 +5,7 @@ package com.browserbase.api.client.okhttp
 import com.browserbase.api.client.StagehandClientAsync
 import com.browserbase.api.client.StagehandClientAsyncImpl
 import com.browserbase.api.core.ClientOptions
+import com.browserbase.api.core.LogLevel
 import com.browserbase.api.core.Sleeper
 import com.browserbase.api.core.Timeout
 import com.browserbase.api.core.http.AsyncStreamResponse
@@ -290,6 +291,15 @@ class StagehandOkHttpClientAsync private constructor() {
          */
         fun maxRetries(maxRetries: Int) = apply { clientOptions.maxRetries(maxRetries) }
 
+        /**
+         * The level at which to log request and response information.
+         *
+         * [fromEnv] will set the level from environment variables. See [LogLevel.fromEnv].
+         *
+         * Defaults to [LogLevel.fromEnv].
+         */
+        fun logLevel(logLevel: LogLevel) = apply { clientOptions.logLevel(logLevel) }
+
         /** Your [Browserbase API Key](https://www.browserbase.com/settings) */
         fun browserbaseApiKey(browserbaseApiKey: String) = apply {
             clientOptions.browserbaseApiKey(browserbaseApiKey)