release: 0.33.0 (#281)

* chore(ci): run more examples

* feat(client): detect binary incompatible jackson versions (#282)

* release: 0.33.0

---------

Co-authored-by: Tomer Aberbach <[email protected]>
Co-authored-by: stainless-app[bot] <142633134+stainless-app[bot]@users.noreply.github.com>

Author: stainless-app[bot]

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.32.0"
+  ".": "0.33.0"
 }

CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.33.0 (2025-03-06)
+
+Full Changelog: [v0.32.0...v0.33.0](https://github.com/openai/openai-java/compare/v0.32.0...v0.33.0)
+
+### Features
+
+* **client:** detect binary incompatible jackson versions ([#282](https://github.com/openai/openai-java/issues/282)) ([10eca3f](https://github.com/openai/openai-java/commit/10eca3f728726b0022d7f851a3784548764ede6c))
+
+
+### Chores
+
+* **ci:** run more examples ([4815776](https://github.com/openai/openai-java/commit/48157762da46b6bca6169a79adbfd7c07a701496))
+
 ## 0.32.0 (2025-03-06)
 
 Full Changelog: [v0.31.1...v0.32.0](https://github.com/openai/openai-java/compare/v0.31.1...v0.32.0)

README.md

@@ -9,8 +9,8 @@
 
 <!-- x-release-please-start-version -->
 
-[![Maven Central](https://img.shields.io/maven-central/v/com.openai/openai-java)](https://central.sonatype.com/artifact/com.openai/openai-java/0.32.0)
-[![javadoc](https://javadoc.io/badge2/com.openai/openai-java/0.32.0/javadoc.svg)](https://javadoc.io/doc/com.openai/openai-java/0.32.0)
+[![Maven Central](https://img.shields.io/maven-central/v/com.openai/openai-java)](https://central.sonatype.com/artifact/com.openai/openai-java/0.33.0)
+[![javadoc](https://javadoc.io/badge2/com.openai/openai-java/0.33.0/javadoc.svg)](https://javadoc.io/doc/com.openai/openai-java/0.33.0)
 
 <!-- x-release-please-end -->
 
@@ -25,7 +25,7 @@ The REST API documentation can be found on [platform.openai.com](https://platfor
 ### Gradle
 
 ```kotlin
-implementation("com.openai:openai-java:0.32.0")
+implementation("com.openai:openai-java:0.33.0")
 ```
 
 ### Maven
@@ -34,7 +34,7 @@ implementation("com.openai:openai-java:0.32.0")
 <dependency>
     <groupId>com.openai</groupId>
     <artifactId>openai-java</artifactId>
-    <version>0.32.0</version>
+    <version>0.33.0</version>
 </dependency>
 ```
 

build.gradle.kts

@@ -8,7 +8,7 @@ repositories {
 
 allprojects {
     group = "com.openai"
-    version = "0.32.0" // x-release-please-version
+    version = "0.33.0" // x-release-please-version
 }
 
 subprojects {

openai-java-core/src/main/kotlin/com/openai/core/ObjectMappers.kt

@@ -9,11 +9,15 @@ import com.fasterxml.jackson.databind.SerializationFeature
 import com.fasterxml.jackson.databind.SerializerProvider
 import com.fasterxml.jackson.databind.cfg.CoercionAction.Fail
 import com.fasterxml.jackson.databind.cfg.CoercionInputShape.Integer
+import com.fasterxml.jackson.databind.exc.InvalidDefinitionException
+import com.fasterxml.jackson.databind.exc.UnrecognizedPropertyException
 import com.fasterxml.jackson.databind.json.JsonMapper
 import com.fasterxml.jackson.databind.module.SimpleModule
 import com.fasterxml.jackson.datatype.jdk8.Jdk8Module
 import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule
 import com.fasterxml.jackson.module.kotlin.jacksonMapperBuilder
+import com.openai.errors.OpenAIException
+import com.openai.errors.OpenAIInvalidDataException
 import java.io.InputStream
 
 fun jsonMapper(): JsonMapper =
@@ -43,3 +47,38 @@ private object InputStreamJsonSerializer : BaseSerializer<InputStream>(InputStre
         }
     }
 }
+
+@JvmSynthetic
+internal fun enhanceJacksonException(fallbackMessage: String, e: Exception): Exception {
+    // These exceptions should only happen if our code is wrong OR if the user is using a binary
+    // incompatible version of `com.fasterxml.jackson.core:jackson-databind`:
+    // https://javadoc.io/static/com.fasterxml.jackson.core/jackson-databind/2.18.1/index.html
+    val isUnexpectedException =
+        e is UnrecognizedPropertyException || e is InvalidDefinitionException
+    if (!isUnexpectedException) {
+        return OpenAIInvalidDataException(fallbackMessage, e)
+    }
+
+    val jacksonVersion = JsonMapper::class.java.`package`.implementationVersion
+    if (jacksonVersion.isNullOrEmpty() || jacksonVersion == COMPILED_JACKSON_VERSION) {
+        return OpenAIInvalidDataException(fallbackMessage, e)
+    }
+
+    return OpenAIException(
+        """
+            Jackson threw an unexpected exception and its runtime version ($jacksonVersion) mismatches the version the SDK was compiled with ($COMPILED_JACKSON_VERSION).
+
+            You may be using a version of `com.fasterxml.jackson.core:jackson-databind` that's not binary compatible with the SDK.
+
+            This can happen if you are either:
+            1. Directly depending on a different Jackson version
+            2. Depending on some library that depends on a different Jackson version, potentially transitively
+
+            Double-check that you are depending on a compatible Jackson version.
+        """
+            .trimIndent(),
+        e,
+    )
+}
+
+const val COMPILED_JACKSON_VERSION = "2.18.1"

openai-java-core/src/main/kotlin/com/openai/core/handlers/JsonHandler.kt

@@ -4,18 +4,17 @@ package com.openai.core.handlers
 
 import com.fasterxml.jackson.databind.json.JsonMapper
 import com.fasterxml.jackson.module.kotlin.jacksonTypeRef
+import com.openai.core.enhanceJacksonException
 import com.openai.core.http.HttpResponse
 import com.openai.core.http.HttpResponse.Handler
-import com.openai.errors.OpenAIException
 
 @JvmSynthetic
 internal inline fun <reified T> jsonHandler(jsonMapper: JsonMapper): Handler<T> =
     object : Handler<T> {
-        override fun handle(response: HttpResponse): T {
+        override fun handle(response: HttpResponse): T =
             try {
-                return jsonMapper.readValue(response.body(), jacksonTypeRef())
+                jsonMapper.readValue(response.body(), jacksonTypeRef())
             } catch (e: Exception) {
-                throw OpenAIException("Error reading response", e)
+                throw enhanceJacksonException("Error reading response", e)
             }
-        }
     }

openai-java-core/src/main/kotlin/com/openai/core/handlers/SseHandler.kt

@@ -124,11 +124,5 @@ internal inline fun <reified T> Handler<StreamResponse<SseMessage>>.mapJson(
 ): Handler<StreamResponse<T>> =
     object : Handler<StreamResponse<T>> {
         override fun handle(response: HttpResponse): StreamResponse<T> =
-            this@mapJson.handle(response).map {
-                try {
-                    it.json<T>(includeEventAndData)
-                } catch (e: Exception) {
-                    throw OpenAIException("Error reading response", e)
-                }
-            }
+            this@mapJson.handle(response).map { it.json<T>(includeEventAndData) }
     }

openai-java-core/src/main/kotlin/com/openai/core/http/SseMessage.kt

@@ -4,7 +4,7 @@ package com.openai.core.http
 
 import com.fasterxml.jackson.databind.json.JsonMapper
 import com.fasterxml.jackson.module.kotlin.jacksonTypeRef
-import com.openai.errors.OpenAIException
+import com.openai.core.enhanceJacksonException
 import java.util.Objects
 
 internal class SseMessage
@@ -50,14 +50,18 @@ private constructor(
             jsonNode = newJsonNode
         }
 
-        return jsonMapper.readerFor(jacksonTypeRef<T>()).readValue(jsonNode)
+        try {
+            return jsonMapper.readerFor(jacksonTypeRef<T>()).readValue(jsonNode)
+        } catch (e: Exception) {
+            throw enhanceJacksonException("Error reading response", e)
+        }
     }
 
     private val jsonNode by lazy {
         try {
             jsonMapper.readTree(data)
         } catch (e: Exception) {
-            throw OpenAIException("Error deserializing json", e)
+            throw enhanceJacksonException("Error reading response", e)
         }
     }
 

openai-java-example/build.gradle.kts

@@ -15,5 +15,5 @@ tasks.withType<JavaCompile>().configureEach {
 }
 
 application {
-    mainClass = "com.openai.example.CompletionsExample"
+    mainClass = "com.openai.example.Main"
 }

openai-java-example/src/main/java/com/openai/example/Main.java

@@ -0,0 +1,11 @@
+package com.openai.example;
+
+public final class Main {
+    private Main() {}
+
+    public static void main(String[] args) throws Exception {
+        CompletionsExample.main(args);
+        CompletionsStreamingExample.main(args);
+        AudioTranscriptionsExample.main(args);
+    }
+}