release: 0.23.0

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.22.0"
+  ".": "0.23.0"
 }

.stats.yml

@@ -1,2 +1,2 @@
 configured_endpoints: 101
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/orb%2Forb-11f40c15fa889d9752019e8a35b82d2e7a3d42f2b42c850b469f120a5b2c47ba.yml
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/orb%2Forb-e480186cdd0e2cc631befa7e2c6ba5f2d7ae52052f0e79a748214f3ade8a98ee.yml

CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.23.0 (2025-01-18)
+
+Full Changelog: [v0.22.0...v0.23.0](https://github.com/orbcorp/orb-java/compare/v0.22.0...v0.23.0)
+
+### Features
+
+* **api:** api update ([#206](https://github.com/orbcorp/orb-java/issues/206)) ([e2eef46](https://github.com/orbcorp/orb-java/commit/e2eef4669606db8745234da24a04814da1118f86))
+
+
+### Chores
+
+* **internal:** upgrade kotlin compiler and gradle ([#203](https://github.com/orbcorp/orb-java/issues/203)) ([3e03f2b](https://github.com/orbcorp/orb-java/commit/3e03f2bb7a247262f89871ecec0a957ee50b64f4))
+
+
+### Documentation
+
+* add more documentation ([#205](https://github.com/orbcorp/orb-java/issues/205)) ([c8fbcb6](https://github.com/orbcorp/orb-java/commit/c8fbcb675e81cf8683c92843fffdbe7b4aa6286f))
+
 ## 0.22.0 (2025-01-16)
 
 Full Changelog: [v0.21.0...v0.22.0](https://github.com/orbcorp/orb-java/compare/v0.21.0...v0.22.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.22.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.23.0)
 
 <!-- x-release-please-end -->
 
@@ -25,7 +25,7 @@ The REST API documentation can be found on [docs.withorb.com](https://docs.with
 <!-- x-release-please-start-version -->
 
 ```kotlin
-implementation("com.withorb.api:orb-java:0.22.0")
+implementation("com.withorb.api:orb-java:0.23.0")
 ```
 
 #### Maven
@@ -34,7 +34,7 @@ implementation("com.withorb.api:orb-java:0.22.0")
 <dependency>
     <groupId>com.withorb.api</groupId>
     <artifactId>orb-java</artifactId>
-    <version>0.22.0</version>
+    <version>0.23.0</version>
 </dependency>
 ```
 

build.gradle.kts

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

buildSrc/build.gradle.kts

@@ -1,6 +1,6 @@
 plugins {
     `kotlin-dsl`
-    kotlin("jvm") version "1.9.22"
+    kotlin("jvm") version "2.1.0"
     id("com.vanniktech.maven.publish") version "0.28.0"
 }
 

buildSrc/src/main/kotlin/orb.kotlin.gradle.kts

@@ -21,8 +21,12 @@ configure<SpotlessExtension> {
 
 tasks.withType<KotlinCompile>().configureEach {
     kotlinOptions {
-        allWarningsAsErrors = true
-        freeCompilerArgs = listOf("-Xjvm-default=all", "-Xjdk-release=1.8")
+        freeCompilerArgs = listOf(
+          "-Xjvm-default=all",
+          "-Xjdk-release=1.8",
+          // Suppress deprecation warnings because we may still reference and test deprecated members.
+          "-Xsuppress-warning=DEPRECATION"
+        )
         jvmTarget = "1.8"
     }
 }

gradle/wrapper/gradle-wrapper.properties

@@ -1,6 +1,6 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-8.7-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.12-bin.zip
 networkTimeout=10000
 validateDistributionUrl=true
 zipStoreBase=GRADLE_USER_HOME

gradlew

@@ -15,6 +15,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
+# SPDX-License-Identifier: Apache-2.0
+#
 
 ##############################################################################
 #
@@ -55,7 +57,7 @@
 #       Darwin, MinGW, and NonStop.
 #
 #   (3) This script is generated from the Groovy template
-#       https://github.com/gradle/gradle/blob/HEAD/subprojects/plugins/src/main/resources/org/gradle/api/internal/plugins/unixStartScript.txt
+#       https://github.com/gradle/gradle/blob/HEAD/platforms/jvm/plugins-application/src/main/resources/org/gradle/api/internal/plugins/unixStartScript.txt
 #       within the Gradle project.
 #
 #       You can find Gradle at https://github.com/gradle/gradle/.
@@ -84,7 +86,7 @@ done
 # shellcheck disable=SC2034
 APP_BASE_NAME=${0##*/}
 # Discard cd standard output in case $CDPATH is set (https://github.com/gradle/gradle/issues/25036)
-APP_HOME=$( cd "${APP_HOME:-./}" > /dev/null && pwd -P ) || exit
+APP_HOME=$( cd -P "${APP_HOME:-./}" > /dev/null && printf '%s\n' "$PWD" ) || exit
 
 # Use the maximum available, or set MAX_FD != -1 to use that value.
 MAX_FD=maximum

gradlew.bat

@@ -13,6 +13,8 @@
 @rem See the License for the specific language governing permissions and
 @rem limitations under the License.
 @rem
+@rem SPDX-License-Identifier: Apache-2.0
+@rem
 
 @if "%DEBUG%"=="" @echo off
 @rem ##########################################################################

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

@@ -21,8 +21,8 @@ import java.util.Objects
 import java.util.Optional
 
 /**
- * [Alerts within Orb](https://docs.withorb.com/guides/product-catalog/configuring-alerts) monitor
- * spending, usage, or credit balance and trigger webhooks when a threshold is exceeded.
+ * [Alerts within Orb](/product-catalog/configuring-alerts) monitor spending, usage, or credit
+ * balance and trigger webhooks when a threshold is exceeded.
  *
  * Alerts created through the API can be scoped to either customers or subscriptions.
  */
@@ -915,6 +915,7 @@ private constructor(
             "Threshold{value=$value, additionalProperties=$additionalProperties}"
     }
 
+    /** The type of alert. This must be a valid alert type. */
     class Type
     @JsonCreator
     private constructor(

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

@@ -25,9 +25,9 @@ import java.util.Optional
  * This endpoint creates a new alert to monitor a customer's credit balance. There are three types
  * of alerts that can be scoped to customers: `credit_balance_depleted`, `credit_balance_dropped`,
  * and `credit_balance_recovered`. Customers can have a maximum of one of each type of alert per
- * [credit balance currency](https://docs.withorb.com/guides/product-catalog/prepurchase).
- * `credit_balance_dropped` alerts require a list of thresholds to be provided while
- * `credit_balance_depleted` and `credit_balance_recovered` alerts do not require thresholds.
+ * [credit balance currency](/product-catalog/prepurchase). `credit_balance_dropped` alerts require
+ * a list of thresholds to be provided while `credit_balance_depleted` and
+ * `credit_balance_recovered` alerts do not require thresholds.
  */
 class AlertCreateForCustomerParams
 constructor(
@@ -414,6 +414,7 @@ constructor(
             )
     }
 
+    /** The type of alert to create. This must be a valid alert type. */
     class Type
     @JsonCreator
     private constructor(

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

@@ -25,9 +25,9 @@ import java.util.Optional
  * This endpoint creates a new alert to monitor a customer's credit balance. There are three types
  * of alerts that can be scoped to customers: `credit_balance_depleted`, `credit_balance_dropped`,
  * and `credit_balance_recovered`. Customers can have a maximum of one of each type of alert per
- * [credit balance currency](https://docs.withorb.com/guides/product-catalog/prepurchase).
- * `credit_balance_dropped` alerts require a list of thresholds to be provided while
- * `credit_balance_depleted` and `credit_balance_recovered` alerts do not require thresholds.
+ * [credit balance currency](/product-catalog/prepurchase). `credit_balance_dropped` alerts require
+ * a list of thresholds to be provided while `credit_balance_depleted` and
+ * `credit_balance_recovered` alerts do not require thresholds.
  */
 class AlertCreateForExternalCustomerParams
 constructor(
@@ -423,6 +423,7 @@ constructor(
             )
     }
 
+    /** The type of alert to create. This must be a valid alert type. */
     class Type
     @JsonCreator
     private constructor(

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

@@ -534,6 +534,7 @@ constructor(
             "Threshold{value=$value, additionalProperties=$additionalProperties}"
     }
 
+    /** The type of alert to create. This must be a valid alert type. */
     class Type
     @JsonCreator
     private constructor(

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

@@ -19,6 +19,17 @@ import java.util.Optional
 import java.util.stream.Stream
 import java.util.stream.StreamSupport
 
+/**
+ * This endpoint returns a list of alerts within Orb.
+ *
+ * The request must specify one of `customer_id`, `external_customer_id`, or `subscription_id`.
+ *
+ * If querying by subscripion_id, the endpoint will return the subscription level alerts as well as
+ * the plan level alerts associated with the subscription.
+ *
+ * The list of alerts is ordered starting from the most recently created alert. This endpoint
+ * follows Orb's [standardized pagination format](/api-reference/pagination).
+ */
 class AlertListPage
 private constructor(
     private val alertsService: AlertService,

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

@@ -20,6 +20,17 @@ import java.util.concurrent.CompletableFuture
 import java.util.concurrent.Executor
 import java.util.function.Predicate
 
+/**
+ * This endpoint returns a list of alerts within Orb.
+ *
+ * The request must specify one of `customer_id`, `external_customer_id`, or `subscription_id`.
+ *
+ * If querying by subscripion_id, the endpoint will return the subscription level alerts as well as
+ * the plan level alerts associated with the subscription.
+ *
+ * The list of alerts is ordered starting from the most recently created alert. This endpoint
+ * follows Orb's [standardized pagination format](/api-reference/pagination).
+ */
 class AlertListPageAsync
 private constructor(
     private val alertsService: AlertServiceAsync,

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

@@ -19,7 +19,7 @@ import java.util.Optional
  * the plan level alerts associated with the subscription.
  *
  * The list of alerts is ordered starting from the most recently created alert. This endpoint
- * follows Orb's [standardized pagination format](../reference/pagination).
+ * follows Orb's [standardized pagination format](/api-reference/pagination).
  */
 class AlertListParams
 constructor(

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

@@ -35,37 +35,6 @@ import kotlin.jvm.optionals.getOrNull
  * percentage amount to an invoice or subscription. Coupons are activated using a redemption code,
  * which applies the discount to a subscription or invoice. The duration of a coupon determines how
  * long it remains available for use by end users.
- *
- * ## How to use coupons
- *
- * Coupons can be created using the Orb dashboard or programmatically through the API. Once a coupon
- * is created, it can be managed and applied programmatically via the API. To redeem a coupon, use
- * the `redemption_code` property when [creating a subscription](create-subscription.api.mdx) or
- * when scheduling a [plan change](schedule-plan-change.api.mdx).
- *
- * ## When to use coupons
- *
- * A common use case for coupons is through self-serve signup or upgrade flows in your checkout
- * experience or billing portal. Coupons can also be used as one-off to incentivize use for custom
- * agreements.
- *
- * Coupons are effective when launching new features and encouraging existing users to upgrade to a
- * higher tier. For example, you could create a coupon code "UPGRADE20" that offers a 20% discount
- * on the first month of the new plan. This code can be applied during the upgrade process in your
- * billing portal, making it straightforward for users to benefit from the new features at a reduced
- * cost.
- *
- * ## Coupon scoping
- *
- * When a coupon is applied on a subscription, it creates a discount adjustment that applies to all
- * of the prices on the subscription at the time of the coupon application. Notably, coupons do not
- * scope in new price additions to a subscription automatically — if a new price is added to the
- * subscription with a subscription edit or plan version migration, the discount created with the
- * coupon will not apply to it automatically. If you'd like the coupon to apply to newly added
- * prices, you can [edit the adjustment intervals](add-edit-price-intervals.api.mdx) to end the
- * discount interval created by the coupon at the time of the migration and add a new one starting
- * at the time of the migration that includes the newly added prices you'd like the coupon to apply
- * to.
  */
 @NoAutoDetect
 class Coupon

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

@@ -19,6 +19,13 @@ import java.util.Optional
 import java.util.stream.Stream
 import java.util.stream.StreamSupport
 
+/**
+ * This endpoint returns a list of all coupons for an account in a list format.
+ *
+ * The list of coupons is ordered starting from the most recently created coupon. The response also
+ * includes `pagination_metadata`, which lets the caller retrieve the next page of results if they
+ * exist. More information about pagination can be found in the Pagination-metadata schema.
+ */
 class CouponListPage
 private constructor(
     private val couponsService: CouponService,

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

@@ -20,6 +20,13 @@ import java.util.concurrent.CompletableFuture
 import java.util.concurrent.Executor
 import java.util.function.Predicate
 
+/**
+ * This endpoint returns a list of all coupons for an account in a list format.
+ *
+ * The list of coupons is ordered starting from the most recently created coupon. The response also
+ * includes `pagination_metadata`, which lets the caller retrieve the next page of results if they
+ * exist. More information about pagination can be found in the Pagination-metadata schema.
+ */
 class CouponListPageAsync
 private constructor(
     private val couponsService: CouponServiceAsync,

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

@@ -19,6 +19,12 @@ import java.util.Optional
 import java.util.stream.Stream
 import java.util.stream.StreamSupport
 
+/**
+ * This endpoint returns a list of all subscriptions that have redeemed a given coupon as a
+ * [paginated](/api-reference/pagination) list, ordered starting from the most recently created
+ * subscription. For a full discussion of the subscription resource, see
+ * [Subscription](/core-concepts#subscription).
+ */
 class CouponSubscriptionListPage
 private constructor(
     private val subscriptionsService: SubscriptionService,

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

@@ -20,6 +20,12 @@ import java.util.concurrent.CompletableFuture
 import java.util.concurrent.Executor
 import java.util.function.Predicate
 
+/**
+ * This endpoint returns a list of all subscriptions that have redeemed a given coupon as a
+ * [paginated](/api-reference/pagination) list, ordered starting from the most recently created
+ * subscription. For a full discussion of the subscription resource, see
+ * [Subscription](/core-concepts#subscription).
+ */
 class CouponSubscriptionListPageAsync
 private constructor(
     private val subscriptionsService: SubscriptionServiceAsync,

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

@@ -11,9 +11,9 @@ import java.util.Optional
 
 /**
  * This endpoint returns a list of all subscriptions that have redeemed a given coupon as a
- * [paginated](../reference/pagination) list, ordered starting from the most recently created
+ * [paginated](/api-reference/pagination) list, ordered starting from the most recently created
  * subscription. For a full discussion of the subscription resource, see
- * [Subscription](../guides/concepts#subscription).
+ * [Subscription](/core-concepts#subscription).
  */
 class CouponSubscriptionListParams
 constructor(

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

@@ -21,8 +21,8 @@ import java.util.Objects
 import java.util.Optional
 
 /**
- * The [Credit Note](/guides/invoicing/credit-notes) resource represents a credit that has been
- * applied to a particular invoice.
+ * The [Credit Note](/invoicing/credit-notes) resource represents a credit that has been applied to
+ * a particular invoice.
  */
 @NoAutoDetect
 class CreditNote

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

@@ -21,7 +21,7 @@ import com.withorb.api.errors.OrbInvalidDataException
 import java.util.Objects
 import java.util.Optional
 
-/** This endpoint is used to create a single [`Credit Note`](../guides/invoicing/credit-notes). */
+/** This endpoint is used to create a single [`Credit Note`](/invoicing/credit-notes). */
 class CreditNoteCreateParams
 constructor(
     private val body: CreditNoteCreateBody,
@@ -508,6 +508,7 @@ constructor(
             "LineItem{amount=$amount, invoiceLineItemId=$invoiceLineItemId, additionalProperties=$additionalProperties}"
     }
 
+    /** An optional reason for the credit note. */
     class Reason
     @JsonCreator
     private constructor(

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

@@ -9,8 +9,8 @@ import com.withorb.api.core.http.QueryParams
 import java.util.Objects
 
 /**
- * This endpoint is used to fetch a single [`Credit Note`](../guides/invoicing/credit-notes) given
- * an identifier.
+ * This endpoint is used to fetch a single [`Credit Note`](/invoicing/credit-notes) given an
+ * identifier.
  */
 class CreditNoteFetchParams
 constructor(