release: 0.45.0

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.44.0"
+  ".": "0.45.0"
 }

.stats.yml

@@ -1,2 +1,2 @@
 configured_endpoints: 103
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/orb%2Forb-a2c1aa029d1e72a5fc7d3c6cd431479888ebd9a379683a2c8630da48437baa4f.yml
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/orb%2Forb-6797b438a8e6a6856e28f4304a5a3c81bb67e74fa2d6fcc20e734880c725295a.yml

CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.45.0 (2025-03-07)
+
+Full Changelog: [v0.44.0...v0.45.0](https://github.com/orbcorp/orb-java/compare/v0.44.0...v0.45.0)
+
+### Features
+
+* **api:** api update ([#317](https://github.com/orbcorp/orb-java/issues/317)) ([540fe9c](https://github.com/orbcorp/orb-java/commit/540fe9cfb9c92531ee1c517d06c3401f3b4511a1))
+* **client:** detect binary incompatible jackson versions ([#315](https://github.com/orbcorp/orb-java/issues/315)) ([50dd8a9](https://github.com/orbcorp/orb-java/commit/50dd8a98c468428cc2598ba4ce5d561a615b736e))
+
 ## 0.44.0 (2025-03-06)
 
 Full Changelog: [v0.43.0...v0.44.0](https://github.com/orbcorp/orb-java/compare/v0.43.0...v0.44.0)

README.md

@@ -2,7 +2,7 @@
 
 <!-- x-release-please-start-version -->
 
-[![Maven Central](https://img.shields.io/maven-central/v/com.withorb.api/orb-java)](https://central.sonatype.com/artifact/com.withorb.api/orb-java/0.44.0)
+[![Maven Central](https://img.shields.io/maven-central/v/com.withorb.api/orb-java)](https://central.sonatype.com/artifact/com.withorb.api/orb-java/0.45.0)
 
 <!-- x-release-please-end -->
 
@@ -19,7 +19,7 @@ The REST API documentation can be found on [docs.withorb.com](https://docs.witho
 ### Gradle
 
 ```kotlin
-implementation("com.withorb.api:orb-java:0.44.0")
+implementation("com.withorb.api:orb-java:0.45.0")
 ```
 
 ### Maven
@@ -28,7 +28,7 @@ implementation("com.withorb.api:orb-java:0.44.0")
 <dependency>
     <groupId>com.withorb.api</groupId>
     <artifactId>orb-java</artifactId>
-    <version>0.44.0</version>
+    <version>0.45.0</version>
 </dependency>
 ```
 

build.gradle.kts

@@ -1,4 +1,4 @@
 allprojects {
     group = "com.withorb.api"
-    version = "0.44.0" // x-release-please-version
+    version = "0.45.0" // x-release-please-version
 }

orb-java-core/src/main/kotlin/com/withorb/api/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.withorb.api.errors.OrbException
+import com.withorb.api.errors.OrbInvalidDataException
 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 OrbInvalidDataException(fallbackMessage, e)
+    }
+
+    val jacksonVersion = JsonMapper::class.java.`package`.implementationVersion
+    if (jacksonVersion.isNullOrEmpty() || jacksonVersion == COMPILED_JACKSON_VERSION) {
+        return OrbInvalidDataException(fallbackMessage, e)
+    }
+
+    return OrbException(
+        """
+            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"

orb-java-core/src/main/kotlin/com/withorb/api/core/handlers/JsonHandler.kt

@@ -4,18 +4,17 @@ package com.withorb.api.core.handlers
 
 import com.fasterxml.jackson.databind.json.JsonMapper
 import com.fasterxml.jackson.module.kotlin.jacksonTypeRef
+import com.withorb.api.core.enhanceJacksonException
 import com.withorb.api.core.http.HttpResponse
 import com.withorb.api.core.http.HttpResponse.Handler
-import com.withorb.api.errors.OrbException
 
 @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 OrbException("Error reading response", e)
+                throw enhanceJacksonException("Error reading response", e)
             }
-        }
     }

orb-java-core/src/main/kotlin/com/withorb/api/models/Alert.kt

@@ -992,26 +992,26 @@ private constructor(
 
         companion object {
 
-            @JvmField val USAGE_EXCEEDED = of("usage_exceeded")
-
-            @JvmField val COST_EXCEEDED = of("cost_exceeded")
-
             @JvmField val CREDIT_BALANCE_DEPLETED = of("credit_balance_depleted")
 
             @JvmField val CREDIT_BALANCE_DROPPED = of("credit_balance_dropped")
 
             @JvmField val CREDIT_BALANCE_RECOVERED = of("credit_balance_recovered")
 
+            @JvmField val USAGE_EXCEEDED = of("usage_exceeded")
+
+            @JvmField val COST_EXCEEDED = of("cost_exceeded")
+
             @JvmStatic fun of(value: String) = Type(JsonField.of(value))
         }
 
         /** An enum containing [Type]'s known values. */
         enum class Known {
-            USAGE_EXCEEDED,
-            COST_EXCEEDED,
             CREDIT_BALANCE_DEPLETED,
             CREDIT_BALANCE_DROPPED,
             CREDIT_BALANCE_RECOVERED,
+            USAGE_EXCEEDED,
+            COST_EXCEEDED,
         }
 
         /**
@@ -1024,11 +1024,11 @@ private constructor(
          * - It was constructed with an arbitrary value using the [of] method.
          */
         enum class Value {
-            USAGE_EXCEEDED,
-            COST_EXCEEDED,
             CREDIT_BALANCE_DEPLETED,
             CREDIT_BALANCE_DROPPED,
             CREDIT_BALANCE_RECOVERED,
+            USAGE_EXCEEDED,
+            COST_EXCEEDED,
             /** An enum member indicating that [Type] was instantiated with an unknown value. */
             _UNKNOWN,
         }
@@ -1042,11 +1042,11 @@ private constructor(
          */
         fun value(): Value =
             when (this) {
-                USAGE_EXCEEDED -> Value.USAGE_EXCEEDED
-                COST_EXCEEDED -> Value.COST_EXCEEDED
                 CREDIT_BALANCE_DEPLETED -> Value.CREDIT_BALANCE_DEPLETED
                 CREDIT_BALANCE_DROPPED -> Value.CREDIT_BALANCE_DROPPED
                 CREDIT_BALANCE_RECOVERED -> Value.CREDIT_BALANCE_RECOVERED
+                USAGE_EXCEEDED -> Value.USAGE_EXCEEDED
+                COST_EXCEEDED -> Value.COST_EXCEEDED
                 else -> Value._UNKNOWN
             }
 
@@ -1060,11 +1060,11 @@ private constructor(
          */
         fun known(): Known =
             when (this) {
-                USAGE_EXCEEDED -> Known.USAGE_EXCEEDED
-                COST_EXCEEDED -> Known.COST_EXCEEDED
                 CREDIT_BALANCE_DEPLETED -> Known.CREDIT_BALANCE_DEPLETED
                 CREDIT_BALANCE_DROPPED -> Known.CREDIT_BALANCE_DROPPED
                 CREDIT_BALANCE_RECOVERED -> Known.CREDIT_BALANCE_RECOVERED
+                USAGE_EXCEEDED -> Known.USAGE_EXCEEDED
+                COST_EXCEEDED -> Known.COST_EXCEEDED
                 else -> throw OrbInvalidDataException("Unknown Type: $value")
             }
 

orb-java-core/src/main/kotlin/com/withorb/api/models/AlertCreateForCustomerParams.kt

@@ -445,10 +445,6 @@ private constructor(
 
         companion object {
 
-            @JvmField val USAGE_EXCEEDED = of("usage_exceeded")
-
-            @JvmField val COST_EXCEEDED = of("cost_exceeded")
-
             @JvmField val CREDIT_BALANCE_DEPLETED = of("credit_balance_depleted")
 
             @JvmField val CREDIT_BALANCE_DROPPED = of("credit_balance_dropped")
@@ -460,8 +456,6 @@ private constructor(
 
         /** An enum containing [Type]'s known values. */
         enum class Known {
-            USAGE_EXCEEDED,
-            COST_EXCEEDED,
             CREDIT_BALANCE_DEPLETED,
             CREDIT_BALANCE_DROPPED,
             CREDIT_BALANCE_RECOVERED,
@@ -477,8 +471,6 @@ private constructor(
          * - It was constructed with an arbitrary value using the [of] method.
          */
         enum class Value {
-            USAGE_EXCEEDED,
-            COST_EXCEEDED,
             CREDIT_BALANCE_DEPLETED,
             CREDIT_BALANCE_DROPPED,
             CREDIT_BALANCE_RECOVERED,
@@ -495,8 +487,6 @@ private constructor(
          */
         fun value(): Value =
             when (this) {
-                USAGE_EXCEEDED -> Value.USAGE_EXCEEDED
-                COST_EXCEEDED -> Value.COST_EXCEEDED
                 CREDIT_BALANCE_DEPLETED -> Value.CREDIT_BALANCE_DEPLETED
                 CREDIT_BALANCE_DROPPED -> Value.CREDIT_BALANCE_DROPPED
                 CREDIT_BALANCE_RECOVERED -> Value.CREDIT_BALANCE_RECOVERED
@@ -513,8 +503,6 @@ private constructor(
          */
         fun known(): Known =
             when (this) {
-                USAGE_EXCEEDED -> Known.USAGE_EXCEEDED
-                COST_EXCEEDED -> Known.COST_EXCEEDED
                 CREDIT_BALANCE_DEPLETED -> Known.CREDIT_BALANCE_DEPLETED
                 CREDIT_BALANCE_DROPPED -> Known.CREDIT_BALANCE_DROPPED
                 CREDIT_BALANCE_RECOVERED -> Known.CREDIT_BALANCE_RECOVERED

orb-java-core/src/main/kotlin/com/withorb/api/models/AlertCreateForExternalCustomerParams.kt

@@ -451,10 +451,6 @@ private constructor(
 
         companion object {
 
-            @JvmField val USAGE_EXCEEDED = of("usage_exceeded")
-
-            @JvmField val COST_EXCEEDED = of("cost_exceeded")
-
             @JvmField val CREDIT_BALANCE_DEPLETED = of("credit_balance_depleted")
 
             @JvmField val CREDIT_BALANCE_DROPPED = of("credit_balance_dropped")
@@ -466,8 +462,6 @@ private constructor(
 
         /** An enum containing [Type]'s known values. */
         enum class Known {
-            USAGE_EXCEEDED,
-            COST_EXCEEDED,
             CREDIT_BALANCE_DEPLETED,
             CREDIT_BALANCE_DROPPED,
             CREDIT_BALANCE_RECOVERED,
@@ -483,8 +477,6 @@ private constructor(
          * - It was constructed with an arbitrary value using the [of] method.
          */
         enum class Value {
-            USAGE_EXCEEDED,
-            COST_EXCEEDED,
             CREDIT_BALANCE_DEPLETED,
             CREDIT_BALANCE_DROPPED,
             CREDIT_BALANCE_RECOVERED,
@@ -501,8 +493,6 @@ private constructor(
          */
         fun value(): Value =
             when (this) {
-                USAGE_EXCEEDED -> Value.USAGE_EXCEEDED
-                COST_EXCEEDED -> Value.COST_EXCEEDED
                 CREDIT_BALANCE_DEPLETED -> Value.CREDIT_BALANCE_DEPLETED
                 CREDIT_BALANCE_DROPPED -> Value.CREDIT_BALANCE_DROPPED
                 CREDIT_BALANCE_RECOVERED -> Value.CREDIT_BALANCE_RECOVERED
@@ -519,8 +509,6 @@ private constructor(
          */
         fun known(): Known =
             when (this) {
-                USAGE_EXCEEDED -> Known.USAGE_EXCEEDED
-                COST_EXCEEDED -> Known.COST_EXCEEDED
                 CREDIT_BALANCE_DEPLETED -> Known.CREDIT_BALANCE_DEPLETED
                 CREDIT_BALANCE_DROPPED -> Known.CREDIT_BALANCE_DROPPED
                 CREDIT_BALANCE_RECOVERED -> Known.CREDIT_BALANCE_RECOVERED

orb-java-core/src/main/kotlin/com/withorb/api/models/AlertCreateForSubscriptionParams.kt

@@ -576,22 +576,13 @@ private constructor(
 
             @JvmField val COST_EXCEEDED = of("cost_exceeded")
 
-            @JvmField val CREDIT_BALANCE_DEPLETED = of("credit_balance_depleted")
-
-            @JvmField val CREDIT_BALANCE_DROPPED = of("credit_balance_dropped")
-
-            @JvmField val CREDIT_BALANCE_RECOVERED = of("credit_balance_recovered")
-
             @JvmStatic fun of(value: String) = Type(JsonField.of(value))
         }
 
         /** An enum containing [Type]'s known values. */
         enum class Known {
             USAGE_EXCEEDED,
             COST_EXCEEDED,
-            CREDIT_BALANCE_DEPLETED,
-            CREDIT_BALANCE_DROPPED,
-            CREDIT_BALANCE_RECOVERED,
         }
 
         /**
@@ -606,9 +597,6 @@ private constructor(
         enum class Value {
             USAGE_EXCEEDED,
             COST_EXCEEDED,
-            CREDIT_BALANCE_DEPLETED,
-            CREDIT_BALANCE_DROPPED,
-            CREDIT_BALANCE_RECOVERED,
             /** An enum member indicating that [Type] was instantiated with an unknown value. */
             _UNKNOWN,
         }
@@ -624,9 +612,6 @@ private constructor(
             when (this) {
                 USAGE_EXCEEDED -> Value.USAGE_EXCEEDED
                 COST_EXCEEDED -> Value.COST_EXCEEDED
-                CREDIT_BALANCE_DEPLETED -> Value.CREDIT_BALANCE_DEPLETED
-                CREDIT_BALANCE_DROPPED -> Value.CREDIT_BALANCE_DROPPED
-                CREDIT_BALANCE_RECOVERED -> Value.CREDIT_BALANCE_RECOVERED
                 else -> Value._UNKNOWN
             }
 
@@ -642,9 +627,6 @@ private constructor(
             when (this) {
                 USAGE_EXCEEDED -> Known.USAGE_EXCEEDED
                 COST_EXCEEDED -> Known.COST_EXCEEDED
-                CREDIT_BALANCE_DEPLETED -> Known.CREDIT_BALANCE_DEPLETED
-                CREDIT_BALANCE_DROPPED -> Known.CREDIT_BALANCE_DROPPED
-                CREDIT_BALANCE_RECOVERED -> Known.CREDIT_BALANCE_RECOVERED
                 else -> throw OrbInvalidDataException("Unknown Type: $value")
             }