Merge pull request #29 from brand-dot-dev/release-please--branches--main--changes--next

release: 0.1.0-alpha.27

Author: YahiaBakour

.github/workflows/ci.yml

@@ -20,10 +20,10 @@ jobs:
     if: github.event_name == 'push' || github.event.pull_request.head.repo.fork
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Set up Java
-        uses: actions/setup-java@v4
+        uses: actions/setup-java@v5
         with:
           distribution: temurin
           java-version: |
@@ -40,14 +40,17 @@ jobs:
   build:
     timeout-minutes: 15
     name: build
+    permissions:
+      contents: read
+      id-token: write
     runs-on: ${{ github.repository == 'stainless-sdks/brand.dev-java' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
     if: github.event_name == 'push' || github.event.pull_request.head.repo.fork
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Set up Java
-        uses: actions/setup-java@v4
+        uses: actions/setup-java@v5
         with:
           distribution: temurin
           java-version: |
@@ -61,16 +64,31 @@ jobs:
       - name: Build SDK
         run: ./scripts/build
 
+      - name: Get GitHub OIDC Token
+        if: github.repository == 'stainless-sdks/brand.dev-java'
+        id: github-oidc
+        uses: actions/github-script@v8
+        with:
+          script: core.setOutput('github_token', await core.getIDToken());
+
+      - name: Build and upload Maven artifacts
+        if: github.repository == 'stainless-sdks/brand.dev-java'
+        env:
+          URL: https://pkg.stainless.com/s
+          AUTH: ${{ steps.github-oidc.outputs.github_token }}
+          SHA: ${{ github.sha }}
+          PROJECT: brand.dev-java
+        run: ./scripts/upload-artifacts
   test:
     timeout-minutes: 15
     name: test
     runs-on: ${{ github.repository == 'stainless-sdks/brand.dev-java' && 'depot-ubuntu-24.04' || 'ubuntu-latest' }}
     if: github.event_name == 'push' || github.event.pull_request.head.repo.fork
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Set up Java
-        uses: actions/setup-java@v4
+        uses: actions/setup-java@v5
         with:
           distribution: temurin
           java-version: |

.github/workflows/publish-sonatype.yml

@@ -14,10 +14,10 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Set up Java
-        uses: actions/setup-java@v4
+        uses: actions/setup-java@v5
         with:
           distribution: temurin
           java-version: |

.github/workflows/release-doctor.yml

@@ -12,7 +12,7 @@ jobs:
     if: github.repository == 'brand-dot-dev/java-sdk' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch' || startsWith(github.head_ref, 'release-please') || github.head_ref == 'next')
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Check release environment
         run: |

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.1.0-alpha.26"
+  ".": "0.1.0-alpha.27"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 15
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/brand-dev%2Fbrand.dev-863ddc13e032497459a639cf02a16349831dda7e39557cbd5ce33da34d086b02.yml
-openapi_spec_hash: f972aac9618fe8df340d96344b3d0578
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/brand-dev%2Fbrand.dev-737dbedd830e2c989387e90a9bb5baa3915306ecfef2e46b09d02cb1879f043c.yml
+openapi_spec_hash: 7bc21f4c6d5fd39c1a3b22626846ca87
 config_hash: 6f10592c7d0c3bafefc1271472283217

CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## 0.1.0-alpha.27 (2026-02-02)
+
+Full Changelog: [v0.1.0-alpha.26...v0.1.0-alpha.27](https://github.com/brand-dot-dev/java-sdk/compare/v0.1.0-alpha.26...v0.1.0-alpha.27)
+
+### Features
+
+* **api:** api update ([fed044d](https://github.com/brand-dot-dev/java-sdk/commit/fed044d09175f814f8e0bad4df5f9555f6410e15))
+* **client:** add `HttpRequest#url()` method ([6cfde89](https://github.com/brand-dot-dev/java-sdk/commit/6cfde8967d8054950cf7bfb62c3b5e9022f79107))
+* **client:** allow configuring dispatcher executor service ([7eca573](https://github.com/brand-dot-dev/java-sdk/commit/7eca57352b72de96b78b7ee16be87ea844a10f89))
+* **client:** send `X-Stainless-Kotlin-Version` header ([a67a402](https://github.com/brand-dot-dev/java-sdk/commit/a67a40257d88d3d34379b2f704d50958292b04e3))
+
+
+### Bug Fixes
+
+* **client:** disallow coercion from float to int ([f59913f](https://github.com/brand-dot-dev/java-sdk/commit/f59913f9452f71603dac23c42101f5f32696fe06))
+* **client:** fully respect max retries ([a0aa790](https://github.com/brand-dot-dev/java-sdk/commit/a0aa7903dfc548c4dd25ef4985e80937646539de))
+* **client:** preserve time zone in lenient date-time parsing ([615ebc2](https://github.com/brand-dot-dev/java-sdk/commit/615ebc293f66bbdd2ce451b0620a5cd37728212f))
+* **client:** send retry count header for max retries 0 ([a0aa790](https://github.com/brand-dot-dev/java-sdk/commit/a0aa7903dfc548c4dd25ef4985e80937646539de))
+* date time deserialization leniency ([0c299fe](https://github.com/brand-dot-dev/java-sdk/commit/0c299fefeefcbec581ad9c341d0a587eae6d2977))
+* **docs:** fix mcp installation instructions for remote servers ([0241743](https://github.com/brand-dot-dev/java-sdk/commit/02417434d1b53a5458346be5e14512bf5dcf092f))
+
+
+### Chores
+
+* **ci:** upgrade `actions/github-script` ([b05460b](https://github.com/brand-dot-dev/java-sdk/commit/b05460be067f2336ff4c1aebbd5a29c2b9cdd8db))
+* **ci:** upgrade `actions/setup-java` ([376fbbd](https://github.com/brand-dot-dev/java-sdk/commit/376fbbd3410d63bd7306bba1ccde2d264fa0cd3b))
+* **internal:** allow passing args to `./scripts/test` ([e27c90d](https://github.com/brand-dot-dev/java-sdk/commit/e27c90dd180ba3a7cea0e0082f484138f07175a1))
+* **internal:** clean up maven repo artifact script and add html documentation to repo root ([4718679](https://github.com/brand-dot-dev/java-sdk/commit/47186793b72b219c12faa54c3e3b54197880ff5a))
+* **internal:** correct cache invalidation for `SKIP_MOCK_TESTS` ([0b13154](https://github.com/brand-dot-dev/java-sdk/commit/0b13154ffa5b630ca445371d68b676bc5eadcea3))
+* **internal:** depend on packages directly in example ([a0aa790](https://github.com/brand-dot-dev/java-sdk/commit/a0aa7903dfc548c4dd25ef4985e80937646539de))
+* **internal:** improve maven repo docs ([0e378d5](https://github.com/brand-dot-dev/java-sdk/commit/0e378d5bf0f3016be36b8ca0189d1ee9614bbd1b))
+* **internal:** support uploading Maven repo artifacts to stainless package server ([95ab800](https://github.com/brand-dot-dev/java-sdk/commit/95ab800f7fd4ce873d638764f1c86ab6d1d427c1))
+* **internal:** update `actions/checkout` version ([fec5d3a](https://github.com/brand-dot-dev/java-sdk/commit/fec5d3a47682efc4f92c4b9890de7fbf6588b906))
+* **internal:** update maven repo doc to include authentication ([b1ed94c](https://github.com/brand-dot-dev/java-sdk/commit/b1ed94ce0d3afefc3597f5978bafa9adecc0ff20))
+* test on Jackson 2.14.0 to avoid encountering FasterXML/jackson-databind[#3240](https://github.com/brand-dot-dev/java-sdk/issues/3240) in tests ([0c299fe](https://github.com/brand-dot-dev/java-sdk/commit/0c299fefeefcbec581ad9c341d0a587eae6d2977))
+
+
+### Documentation
+
+* prominently feature MCP server setup in root SDK readmes ([18a0348](https://github.com/brand-dot-dev/java-sdk/commit/18a03480949d4afc6d8ed4a45a55c84094aadae6))
+
 ## 0.1.0-alpha.26 (2026-01-05)
 
 Full Changelog: [v0.1.0-alpha.25...v0.1.0-alpha.26](https://github.com/brand-dot-dev/java-sdk/compare/v0.1.0-alpha.25...v0.1.0-alpha.26)

README.md

@@ -2,18 +2,27 @@
 
 <!-- x-release-please-start-version -->
 
-[![Maven Central](https://img.shields.io/maven-central/v/com.branddev.api/brand-dev-java)](https://central.sonatype.com/artifact/com.branddev.api/brand-dev-java/0.1.0-alpha.26)
-[![javadoc](https://javadoc.io/badge2/com.branddev.api/brand-dev-java/0.1.0-alpha.26/javadoc.svg)](https://javadoc.io/doc/com.branddev.api/brand-dev-java/0.1.0-alpha.26)
+[![Maven Central](https://img.shields.io/maven-central/v/com.branddev.api/brand-dev-java)](https://central.sonatype.com/artifact/com.branddev.api/brand-dev-java/0.1.0-alpha.27)
+[![javadoc](https://javadoc.io/badge2/com.branddev.api/brand-dev-java/0.1.0-alpha.27/javadoc.svg)](https://javadoc.io/doc/com.branddev.api/brand-dev-java/0.1.0-alpha.27)
 
 <!-- x-release-please-end -->
 
 The Brand Dev Java SDK provides convenient access to the [Brand Dev REST API](https://docs.brand.dev/) from applications written in Java.
 
 It is generated with [Stainless](https://www.stainless.com/).
 
+## MCP Server
+
+Use the Brand Dev MCP Server to enable AI assistants to interact with this API, allowing them to explore endpoints, make test requests, and use documentation to help integrate this SDK into your application.
+
+[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=brand.dev-mcp&config=eyJuYW1lIjoiYnJhbmQuZGV2LW1jcCIsInRyYW5zcG9ydCI6Imh0dHAiLCJ1cmwiOiJodHRwczovL2JyYW5kLWRldi5zdGxtY3AuY29tIiwiaGVhZGVycyI6eyJ4LWJyYW5kLWRldi1hcGkta2V5IjoiTXkgQVBJIEtleSJ9fQ)
+[![Install in VS Code](https://img.shields.io/badge/_-Add_to_VS_Code-blue?style=for-the-badge&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGZpbGw9Im5vbmUiIHZpZXdCb3g9IjAgMCA0MCA0MCI+PHBhdGggZmlsbD0iI0VFRSIgZmlsbC1ydWxlPSJldmVub2RkIiBkPSJNMzAuMjM1IDM5Ljg4NGEyLjQ5MSAyLjQ5MSAwIDAgMS0xLjc4MS0uNzNMMTIuNyAyNC43OGwtMy40NiAyLjYyNC0zLjQwNiAyLjU4MmExLjY2NSAxLjY2NSAwIDAgMS0xLjA4Mi4zMzggMS42NjQgMS42NjQgMCAwIDEtMS4wNDYtLjQzMWwtMi4yLTJhMS42NjYgMS42NjYgMCAwIDEgMC0yLjQ2M0w3LjQ1OCAyMCA0LjY3IDE3LjQ1MyAxLjUwNyAxNC41N2ExLjY2NSAxLjY2NSAwIDAgMSAwLTIuNDYzbDIuMi0yYTEuNjY1IDEuNjY1IDAgMCAxIDIuMTMtLjA5N2w2Ljg2MyA1LjIwOUwyOC40NTIuODQ0YTIuNDg4IDIuNDg4IDAgMCAxIDEuODQxLS43MjljLjM1MS4wMDkuNjk5LjA5MSAxLjAxOS4yNDVsOC4yMzYgMy45NjFhMi41IDIuNSAwIDAgMSAxLjQxNSAyLjI1M3YuMDk5LS4wNDVWMzMuMzd2LS4wNDUuMDk1YTIuNTAxIDIuNTAxIDAgMCAxLTEuNDE2IDIuMjU3bC04LjIzNSAzLjk2MWEyLjQ5MiAyLjQ5MiAwIDAgMS0xLjA3Ny4yNDZabS43MTYtMjguOTQ3LTExLjk0OCA5LjA2MiAxMS45NTIgOS4wNjUtLjAwNC0xOC4xMjdaIi8+PC9zdmc+)](https://vscode.stainless.com/mcp/%7B%22name%22%3A%22brand.dev-mcp%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fbrand-dev.stlmcp.com%22%2C%22headers%22%3A%7B%22x-brand-dev-api-key%22%3A%22My%20API%20Key%22%7D%7D)
+
+> Note: You may need to set environment variables in your MCP client.
+
 <!-- x-release-please-start-version -->
 
-The REST API documentation can be found on [docs.brand.dev](https://docs.brand.dev/). Javadocs are available on [javadoc.io](https://javadoc.io/doc/com.branddev.api/brand-dev-java/0.1.0-alpha.26).
+The REST API documentation can be found on [docs.brand.dev](https://docs.brand.dev/). Javadocs are available on [javadoc.io](https://javadoc.io/doc/com.branddev.api/brand-dev-java/0.1.0-alpha.27).
 
 <!-- x-release-please-end -->
 
@@ -24,7 +33,7 @@ The REST API documentation can be found on [docs.brand.dev](https://docs.brand.d
 ### Gradle
 
 ```kotlin
-implementation("com.branddev.api:brand-dev-java:0.1.0-alpha.26")
+implementation("com.branddev.api:brand-dev-java:0.1.0-alpha.27")
 ```
 
 ### Maven
@@ -33,7 +42,7 @@ implementation("com.branddev.api:brand-dev-java:0.1.0-alpha.26")
 <dependency>
   <groupId>com.branddev.api</groupId>
   <artifactId>brand-dev-java</artifactId>
-  <version>0.1.0-alpha.26</version>
+  <version>0.1.0-alpha.27</version>
 </dependency>
 ```
 
@@ -270,6 +279,8 @@ If the SDK threw an exception, but you're _certain_ the version is compatible, t
 > [!CAUTION]
 > We make no guarantee that the SDK works correctly when the Jackson version check is disabled.
 
+Also note that there are bugs in older Jackson versions that can affect the SDK. We don't work around all Jackson bugs ([example](https://github.com/FasterXML/jackson-databind/issues/3240)) and expect users to upgrade Jackson for those instead.
+
 ## Network options
 
 ### Retries
@@ -307,7 +318,9 @@ To set a custom timeout, configure the method call using the `timeout` method:
 ```java
 import com.branddev.api.models.brand.BrandRetrieveResponse;
 
-BrandRetrieveResponse brand = client.brand().retrieve(RequestOptions.builder().timeout(Duration.ofSeconds(30)).build());
+BrandRetrieveResponse brand = client.brand().retrieve(
+  params, RequestOptions.builder().timeout(Duration.ofSeconds(30)).build()
+);
 ```
 
 Or configure the default for all method calls at the client level:
@@ -491,10 +504,9 @@ To forcibly omit a required parameter or property, pass [`JsonMissing`](brand-de
 
 ```java
 import com.branddev.api.core.JsonMissing;
-import com.branddev.api.models.brand.BrandAiProductsParams;
 import com.branddev.api.models.brand.BrandRetrieveParams;
 
-BrandRetrieveParams params = BrandAiProductsParams.builder()
+BrandRetrieveParams params = BrandRetrieveParams.builder()
     .domain(JsonMissing.of())
     .build();
 ```
@@ -572,7 +584,9 @@ Or configure the method call to validate the response using the `responseValidat
 ```java
 import com.branddev.api.models.brand.BrandRetrieveResponse;
 
-BrandRetrieveResponse brand = client.brand().retrieve(RequestOptions.builder().responseValidation(true).build());
+BrandRetrieveResponse brand = client.brand().retrieve(
+  params, RequestOptions.builder().responseValidation(true).build()
+);
 ```
 
 Or configure the default for all method calls at the client level:

brand-dev-java-client-okhttp/src/main/kotlin/com/branddev/api/client/okhttp/BrandDevOkHttpClient.kt

@@ -16,6 +16,7 @@ import java.net.Proxy
 import java.time.Clock
 import java.time.Duration
 import java.util.Optional
+import java.util.concurrent.ExecutorService
 import javax.net.ssl.HostnameVerifier
 import javax.net.ssl.SSLSocketFactory
 import javax.net.ssl.X509TrustManager
@@ -44,11 +45,31 @@ class BrandDevOkHttpClient private constructor() {
     class Builder internal constructor() {
 
         private var clientOptions: ClientOptions.Builder = ClientOptions.builder()
+        private var dispatcherExecutorService: ExecutorService? = null
         private var proxy: Proxy? = null
         private var sslSocketFactory: SSLSocketFactory? = null
         private var trustManager: X509TrustManager? = null
         private var hostnameVerifier: HostnameVerifier? = null
 
+        /**
+         * The executor service to use for running HTTP requests.
+         *
+         * Defaults to OkHttp's
+         * [default executor service](https://github.com/square/okhttp/blob/ace792f443b2ffb17974f5c0d1cecdf589309f26/okhttp/src/commonJvmAndroid/kotlin/okhttp3/Dispatcher.kt#L98-L104).
+         *
+         * This class takes ownership of the executor service and shuts it down when closed.
+         */
+        fun dispatcherExecutorService(dispatcherExecutorService: ExecutorService?) = apply {
+            this.dispatcherExecutorService = dispatcherExecutorService
+        }
+
+        /**
+         * Alias for calling [Builder.dispatcherExecutorService] with
+         * `dispatcherExecutorService.orElse(null)`.
+         */
+        fun dispatcherExecutorService(dispatcherExecutorService: Optional<ExecutorService>) =
+            dispatcherExecutorService(dispatcherExecutorService.getOrNull())
+
         fun proxy(proxy: Proxy?) = apply { this.proxy = proxy }
 
         /** Alias for calling [Builder.proxy] with `proxy.orElse(null)`. */
@@ -296,6 +317,7 @@ class BrandDevOkHttpClient private constructor() {
                         OkHttpClient.builder()
                             .timeout(clientOptions.timeout())
                             .proxy(proxy)
+                            .dispatcherExecutorService(dispatcherExecutorService)
                             .sslSocketFactory(sslSocketFactory)
                             .trustManager(trustManager)
                             .hostnameVerifier(hostnameVerifier)

brand-dev-java-client-okhttp/src/main/kotlin/com/branddev/api/client/okhttp/BrandDevOkHttpClientAsync.kt

@@ -16,6 +16,7 @@ import java.net.Proxy
 import java.time.Clock
 import java.time.Duration
 import java.util.Optional
+import java.util.concurrent.ExecutorService
 import javax.net.ssl.HostnameVerifier
 import javax.net.ssl.SSLSocketFactory
 import javax.net.ssl.X509TrustManager
@@ -44,11 +45,31 @@ class BrandDevOkHttpClientAsync private constructor() {
     class Builder internal constructor() {
 
         private var clientOptions: ClientOptions.Builder = ClientOptions.builder()
+        private var dispatcherExecutorService: ExecutorService? = null
         private var proxy: Proxy? = null
         private var sslSocketFactory: SSLSocketFactory? = null
         private var trustManager: X509TrustManager? = null
         private var hostnameVerifier: HostnameVerifier? = null
 
+        /**
+         * The executor service to use for running HTTP requests.
+         *
+         * Defaults to OkHttp's
+         * [default executor service](https://github.com/square/okhttp/blob/ace792f443b2ffb17974f5c0d1cecdf589309f26/okhttp/src/commonJvmAndroid/kotlin/okhttp3/Dispatcher.kt#L98-L104).
+         *
+         * This class takes ownership of the executor service and shuts it down when closed.
+         */
+        fun dispatcherExecutorService(dispatcherExecutorService: ExecutorService?) = apply {
+            this.dispatcherExecutorService = dispatcherExecutorService
+        }
+
+        /**
+         * Alias for calling [Builder.dispatcherExecutorService] with
+         * `dispatcherExecutorService.orElse(null)`.
+         */
+        fun dispatcherExecutorService(dispatcherExecutorService: Optional<ExecutorService>) =
+            dispatcherExecutorService(dispatcherExecutorService.getOrNull())
+
         fun proxy(proxy: Proxy?) = apply { this.proxy = proxy }
 
         /** Alias for calling [Builder.proxy] with `proxy.orElse(null)`. */
@@ -296,6 +317,7 @@ class BrandDevOkHttpClientAsync private constructor() {
                         OkHttpClient.builder()
                             .timeout(clientOptions.timeout())
                             .proxy(proxy)
+                            .dispatcherExecutorService(dispatcherExecutorService)
                             .sslSocketFactory(sslSocketFactory)
                             .trustManager(trustManager)
                             .hostnameVerifier(hostnameVerifier)

brand-dev-java-client-okhttp/src/main/kotlin/com/branddev/api/client/okhttp/OkHttpClient.kt

@@ -15,11 +15,13 @@ import java.net.Proxy
 import java.time.Duration
 import java.util.concurrent.CancellationException
 import java.util.concurrent.CompletableFuture
+import java.util.concurrent.ExecutorService
 import javax.net.ssl.HostnameVerifier
 import javax.net.ssl.SSLSocketFactory
 import javax.net.ssl.X509TrustManager
 import okhttp3.Call
 import okhttp3.Callback
+import okhttp3.Dispatcher
 import okhttp3.HttpUrl.Companion.toHttpUrl
 import okhttp3.MediaType
 import okhttp3.MediaType.Companion.toMediaType
@@ -198,6 +200,7 @@ private constructor(@JvmSynthetic internal val okHttpClient: okhttp3.OkHttpClien
 
         private var timeout: Timeout = Timeout.default()
         private var proxy: Proxy? = null
+        private var dispatcherExecutorService: ExecutorService? = null
         private var sslSocketFactory: SSLSocketFactory? = null
         private var trustManager: X509TrustManager? = null
         private var hostnameVerifier: HostnameVerifier? = null
@@ -208,6 +211,10 @@ private constructor(@JvmSynthetic internal val okHttpClient: okhttp3.OkHttpClien
 
         fun proxy(proxy: Proxy?) = apply { this.proxy = proxy }
 
+        fun dispatcherExecutorService(dispatcherExecutorService: ExecutorService?) = apply {
+            this.dispatcherExecutorService = dispatcherExecutorService
+        }
+
         fun sslSocketFactory(sslSocketFactory: SSLSocketFactory?) = apply {
             this.sslSocketFactory = sslSocketFactory
         }
@@ -223,12 +230,16 @@ private constructor(@JvmSynthetic internal val okHttpClient: okhttp3.OkHttpClien
         fun build(): OkHttpClient =
             OkHttpClient(
                 okhttp3.OkHttpClient.Builder()
+                    // `RetryingHttpClient` handles retries if the user enabled them.
+                    .retryOnConnectionFailure(false)
                     .connectTimeout(timeout.connect())
                     .readTimeout(timeout.read())
                     .writeTimeout(timeout.write())
                     .callTimeout(timeout.request())
                     .proxy(proxy)
                     .apply {
+                        dispatcherExecutorService?.let { dispatcher(Dispatcher(it)) }
+
                         val sslSocketFactory = sslSocketFactory
                         val trustManager = trustManager
                         if (sslSocketFactory != null && trustManager != null) {