feat(client): add various convenience setters to models (#184)

feat(client): allow setting arbitrary JSON for top-level body params
feat(client): expose getters for `JsonField` of body params
fix(client): consistently throw on omitting required fields
fix(client): convert `JsonField` containing list type to mutable in builder
style(internal): simplify existing convenience setters on params
style(internal): move headers and query params setters below others
style(internal): explicitly add some method return types

Author: stainless-app[bot]

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

@@ -72,6 +72,19 @@ private constructor(
 
         fun baseUrl(baseUrl: String) = apply { this.baseUrl = baseUrl }
 
+        fun responseValidation(responseValidation: Boolean) = apply {
+            this.responseValidation = responseValidation
+        }
+
+        fun maxRetries(maxRetries: Int) = apply { this.maxRetries = maxRetries }
+
+        fun apiKey(apiKey: String) = apply { this.apiKey = apiKey }
+
+        fun webhookSecret(webhookSecret: String?) = apply { this.webhookSecret = webhookSecret }
+
+        fun webhookSecret(webhookSecret: Optional<String>) =
+            webhookSecret(webhookSecret.orElse(null))
+
         fun headers(headers: Headers) = apply {
             this.headers.clear()
             putAllHeaders(headers)
@@ -152,19 +165,6 @@ private constructor(
 
         fun removeAllQueryParams(keys: Set<String>) = apply { queryParams.removeAll(keys) }
 
-        fun responseValidation(responseValidation: Boolean) = apply {
-            this.responseValidation = responseValidation
-        }
-
-        fun maxRetries(maxRetries: Int) = apply { this.maxRetries = maxRetries }
-
-        fun apiKey(apiKey: String) = apply { this.apiKey = apiKey }
-
-        fun webhookSecret(webhookSecret: String?) = apply { this.webhookSecret = webhookSecret }
-
-        fun webhookSecret(webhookSecret: Optional<String>) =
-            webhookSecret(webhookSecret.orElse(null))
-
         fun fromEnv() = apply {
             System.getenv("ORB_API_KEY")?.let { apiKey(it) }
             System.getenv("ORB_WEBHOOK_SECRET")?.let { webhookSecret(it) }

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

@@ -9,6 +9,7 @@ import com.fasterxml.jackson.annotation.JsonProperty
 import com.withorb.api.core.Enum
 import com.withorb.api.core.ExcludeMissing
 import com.withorb.api.core.JsonField
+import com.withorb.api.core.JsonMissing
 import com.withorb.api.core.JsonValue
 import com.withorb.api.core.NoAutoDetect
 import com.withorb.api.core.http.Headers
@@ -46,12 +47,21 @@ constructor(
     /** The thresholds that define the values at which the alert will be triggered. */
     fun thresholds(): Optional<List<Threshold>> = body.thresholds()
 
-    fun _additionalHeaders(): Headers = additionalHeaders
+    /** The case sensitive currency or custom pricing unit to use for this alert. */
+    fun _currency(): JsonField<String> = body._currency()
 
-    fun _additionalQueryParams(): QueryParams = additionalQueryParams
+    /** The type of alert to create. This must be a valid alert type. */
+    fun _type(): JsonField<Type> = body._type()
+
+    /** The thresholds that define the values at which the alert will be triggered. */
+    fun _thresholds(): JsonField<List<Threshold>> = body._thresholds()
 
     fun _additionalBodyProperties(): Map<String, JsonValue> = body._additionalProperties()
 
+    fun _additionalHeaders(): Headers = additionalHeaders
+
+    fun _additionalQueryParams(): QueryParams = additionalQueryParams
+
     @JvmSynthetic internal fun getBody(): AlertCreateForCustomerBody = body
 
     @JvmSynthetic internal fun getHeaders(): Headers = additionalHeaders
@@ -69,27 +79,53 @@ constructor(
     class AlertCreateForCustomerBody
     @JsonCreator
     internal constructor(
-        @JsonProperty("currency") private val currency: String,
-        @JsonProperty("type") private val type: Type,
-        @JsonProperty("thresholds") private val thresholds: List<Threshold>?,
+        @JsonProperty("currency")
+        @ExcludeMissing
+        private val currency: JsonField<String> = JsonMissing.of(),
+        @JsonProperty("type") @ExcludeMissing private val type: JsonField<Type> = JsonMissing.of(),
+        @JsonProperty("thresholds")
+        @ExcludeMissing
+        private val thresholds: JsonField<List<Threshold>> = JsonMissing.of(),
         @JsonAnySetter
         private val additionalProperties: Map<String, JsonValue> = immutableEmptyMap(),
     ) {
 
         /** The case sensitive currency or custom pricing unit to use for this alert. */
-        @JsonProperty("currency") fun currency(): String = currency
+        fun currency(): String = currency.getRequired("currency")
+
+        /** The type of alert to create. This must be a valid alert type. */
+        fun type(): Type = type.getRequired("type")
+
+        /** The thresholds that define the values at which the alert will be triggered. */
+        fun thresholds(): Optional<List<Threshold>> =
+            Optional.ofNullable(thresholds.getNullable("thresholds"))
+
+        /** The case sensitive currency or custom pricing unit to use for this alert. */
+        @JsonProperty("currency") @ExcludeMissing fun _currency(): JsonField<String> = currency
 
         /** The type of alert to create. This must be a valid alert type. */
-        @JsonProperty("type") fun type(): Type = type
+        @JsonProperty("type") @ExcludeMissing fun _type(): JsonField<Type> = type
 
         /** The thresholds that define the values at which the alert will be triggered. */
         @JsonProperty("thresholds")
-        fun thresholds(): Optional<List<Threshold>> = Optional.ofNullable(thresholds)
+        @ExcludeMissing
+        fun _thresholds(): JsonField<List<Threshold>> = thresholds
 
         @JsonAnyGetter
         @ExcludeMissing
         fun _additionalProperties(): Map<String, JsonValue> = additionalProperties
 
+        private var validated: Boolean = false
+
+        fun validate(): AlertCreateForCustomerBody = apply {
+            if (!validated) {
+                currency()
+                type()
+                thresholds().map { it.forEach { it.validate() } }
+                validated = true
+            }
+        }
+
         fun toBuilder() = Builder().from(this)
 
         companion object {
@@ -99,38 +135,57 @@ constructor(
 
         class Builder {
 
-            private var currency: String? = null
-            private var type: Type? = null
-            private var thresholds: MutableList<Threshold>? = null
+            private var currency: JsonField<String>? = null
+            private var type: JsonField<Type>? = null
+            private var thresholds: JsonField<MutableList<Threshold>>? = null
             private var additionalProperties: MutableMap<String, JsonValue> = mutableMapOf()
 
             @JvmSynthetic
             internal fun from(alertCreateForCustomerBody: AlertCreateForCustomerBody) = apply {
                 currency = alertCreateForCustomerBody.currency
                 type = alertCreateForCustomerBody.type
-                thresholds = alertCreateForCustomerBody.thresholds?.toMutableList()
+                thresholds = alertCreateForCustomerBody.thresholds.map { it.toMutableList() }
                 additionalProperties =
                     alertCreateForCustomerBody.additionalProperties.toMutableMap()
             }
 
             /** The case sensitive currency or custom pricing unit to use for this alert. */
-            fun currency(currency: String) = apply { this.currency = currency }
+            fun currency(currency: String) = currency(JsonField.of(currency))
+
+            /** The case sensitive currency or custom pricing unit to use for this alert. */
+            fun currency(currency: JsonField<String>) = apply { this.currency = currency }
+
+            /** The type of alert to create. This must be a valid alert type. */
+            fun type(type: Type) = type(JsonField.of(type))
 
             /** The type of alert to create. This must be a valid alert type. */
-            fun type(type: Type) = apply { this.type = type }
+            fun type(type: JsonField<Type>) = apply { this.type = type }
 
             /** The thresholds that define the values at which the alert will be triggered. */
-            fun thresholds(thresholds: List<Threshold>?) = apply {
-                this.thresholds = thresholds?.toMutableList()
-            }
+            fun thresholds(thresholds: List<Threshold>?) =
+                thresholds(JsonField.ofNullable(thresholds))
 
             /** The thresholds that define the values at which the alert will be triggered. */
             fun thresholds(thresholds: Optional<List<Threshold>>) =
                 thresholds(thresholds.orElse(null))
 
+            /** The thresholds that define the values at which the alert will be triggered. */
+            fun thresholds(thresholds: JsonField<List<Threshold>>) = apply {
+                this.thresholds = thresholds.map { it.toMutableList() }
+            }
+
             /** The thresholds that define the values at which the alert will be triggered. */
             fun addThreshold(threshold: Threshold) = apply {
-                thresholds = (thresholds ?: mutableListOf()).apply { add(threshold) }
+                thresholds =
+                    (thresholds ?: JsonField.of(mutableListOf())).apply {
+                        asKnown()
+                            .orElseThrow {
+                                IllegalStateException(
+                                    "Field was set to non-list type: ${javaClass.simpleName}"
+                                )
+                            }
+                            .add(threshold)
+                    }
             }
 
             fun additionalProperties(additionalProperties: Map<String, JsonValue>) = apply {
@@ -156,7 +211,7 @@ constructor(
                 AlertCreateForCustomerBody(
                     checkNotNull(currency) { "`currency` is required but was not set" },
                     checkNotNull(type) { "`type` is required but was not set" },
-                    thresholds?.toImmutable(),
+                    (thresholds ?: JsonMissing.of()).map { it.toImmutable() },
                     additionalProperties.toImmutable(),
                 )
         }
@@ -207,18 +262,48 @@ constructor(
         /** The case sensitive currency or custom pricing unit to use for this alert. */
         fun currency(currency: String) = apply { body.currency(currency) }
 
+        /** The case sensitive currency or custom pricing unit to use for this alert. */
+        fun currency(currency: JsonField<String>) = apply { body.currency(currency) }
+
         /** The type of alert to create. This must be a valid alert type. */
         fun type(type: Type) = apply { body.type(type) }
 
+        /** The type of alert to create. This must be a valid alert type. */
+        fun type(type: JsonField<Type>) = apply { body.type(type) }
+
         /** The thresholds that define the values at which the alert will be triggered. */
         fun thresholds(thresholds: List<Threshold>?) = apply { body.thresholds(thresholds) }
 
         /** The thresholds that define the values at which the alert will be triggered. */
         fun thresholds(thresholds: Optional<List<Threshold>>) = thresholds(thresholds.orElse(null))
 
+        /** The thresholds that define the values at which the alert will be triggered. */
+        fun thresholds(thresholds: JsonField<List<Threshold>>) = apply {
+            body.thresholds(thresholds)
+        }
+
         /** The thresholds that define the values at which the alert will be triggered. */
         fun addThreshold(threshold: Threshold) = apply { body.addThreshold(threshold) }
 
+        fun additionalBodyProperties(additionalBodyProperties: Map<String, JsonValue>) = apply {
+            body.additionalProperties(additionalBodyProperties)
+        }
+
+        fun putAdditionalBodyProperty(key: String, value: JsonValue) = apply {
+            body.putAdditionalProperty(key, value)
+        }
+
+        fun putAllAdditionalBodyProperties(additionalBodyProperties: Map<String, JsonValue>) =
+            apply {
+                body.putAllAdditionalProperties(additionalBodyProperties)
+            }
+
+        fun removeAdditionalBodyProperty(key: String) = apply { body.removeAdditionalProperty(key) }
+
+        fun removeAllAdditionalBodyProperties(keys: Set<String>) = apply {
+            body.removeAllAdditionalProperties(keys)
+        }
+
         fun additionalHeaders(additionalHeaders: Headers) = apply {
             this.additionalHeaders.clear()
             putAllAdditionalHeaders(additionalHeaders)
@@ -317,25 +402,6 @@ constructor(
             additionalQueryParams.removeAll(keys)
         }
 
-        fun additionalBodyProperties(additionalBodyProperties: Map<String, JsonValue>) = apply {
-            body.additionalProperties(additionalBodyProperties)
-        }
-
-        fun putAdditionalBodyProperty(key: String, value: JsonValue) = apply {
-            body.putAdditionalProperty(key, value)
-        }
-
-        fun putAllAdditionalBodyProperties(additionalBodyProperties: Map<String, JsonValue>) =
-            apply {
-                body.putAllAdditionalProperties(additionalBodyProperties)
-            }
-
-        fun removeAdditionalBodyProperty(key: String) = apply { body.removeAdditionalProperty(key) }
-
-        fun removeAllAdditionalBodyProperties(keys: Set<String>) = apply {
-            body.removeAllAdditionalProperties(keys)
-        }
-
         fun build(): AlertCreateForCustomerParams =
             AlertCreateForCustomerParams(
                 checkNotNull(customerId) { "`customerId` is required but was not set" },
@@ -425,7 +491,9 @@ constructor(
     class Threshold
     @JsonCreator
     private constructor(
-        @JsonProperty("value") private val value: Double,
+        @JsonProperty("value")
+        @ExcludeMissing
+        private val value: JsonField<Double> = JsonMissing.of(),
         @JsonAnySetter
         private val additionalProperties: Map<String, JsonValue> = immutableEmptyMap(),
     ) {
@@ -435,12 +503,28 @@ constructor(
          * or below this value. For usage and cost alerts, the alert will fire at or above this
          * value.
          */
-        @JsonProperty("value") fun value(): Double = value
+        fun value(): Double = value.getRequired("value")
+
+        /**
+         * The value at which an alert will fire. For credit balance alerts, the alert will fire at
+         * or below this value. For usage and cost alerts, the alert will fire at or above this
+         * value.
+         */
+        @JsonProperty("value") @ExcludeMissing fun _value(): JsonField<Double> = value
 
         @JsonAnyGetter
         @ExcludeMissing
         fun _additionalProperties(): Map<String, JsonValue> = additionalProperties
 
+        private var validated: Boolean = false
+
+        fun validate(): Threshold = apply {
+            if (!validated) {
+                value()
+                validated = true
+            }
+        }
+
         fun toBuilder() = Builder().from(this)
 
         companion object {
@@ -450,7 +534,7 @@ constructor(
 
         class Builder {
 
-            private var value: Double? = null
+            private var value: JsonField<Double>? = null
             private var additionalProperties: MutableMap<String, JsonValue> = mutableMapOf()
 
             @JvmSynthetic
@@ -464,7 +548,14 @@ constructor(
              * at or below this value. For usage and cost alerts, the alert will fire at or above
              * this value.
              */
-            fun value(value: Double) = apply { this.value = value }
+            fun value(value: Double) = value(JsonField.of(value))
+
+            /**
+             * The value at which an alert will fire. For credit balance alerts, the alert will fire
+             * at or below this value. For usage and cost alerts, the alert will fire at or above
+             * this value.
+             */
+            fun value(value: JsonField<Double>) = apply { this.value = value }
 
             fun additionalProperties(additionalProperties: Map<String, JsonValue>) = apply {
                 this.additionalProperties.clear()