feat(client): allow providing some params positionally

Author: stainless-app[bot]

README.md

@@ -412,10 +412,7 @@ These methods return [`HttpResponse`](openai-java-core/src/main/kotlin/com/opena
 import com.openai.core.http.HttpResponse;
 import com.openai.models.files.FileContentParams;
 
-FileContentParams params = FileContentParams.builder()
-    .fileId("file_id")
-    .build();
-HttpResponse response = client.files().content(params);
+HttpResponse response = client.files().content("file_id");
 ```
 
 To save the response content to a file, use the [`Files.copy(...)`](https://docs.oracle.com/javase/8/docs/api/java/nio/file/Files.html#copy-java.io.InputStream-java.nio.file.Path-java.nio.file.CopyOption...-) method:

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

@@ -5,6 +5,9 @@ package com.openai.core
 import com.fasterxml.jackson.core.Version
 import com.fasterxml.jackson.core.util.VersionUtil
 
+fun checkRequired(name: String, condition: Boolean) =
+    check(condition) { "`$name` is required, but was not set" }
+
 fun <T : Any> checkRequired(name: String, value: T?): T =
     checkNotNull(value) { "`$name` is required, but was not set" }
 

openai-java-core/src/main/kotlin/com/openai/models/batches/BatchCancelParams.kt

@@ -4,12 +4,12 @@ package com.openai.models.batches
 
 import com.openai.core.JsonValue
 import com.openai.core.Params
-import com.openai.core.checkRequired
 import com.openai.core.http.Headers
 import com.openai.core.http.QueryParams
 import com.openai.core.toImmutable
 import java.util.Objects
 import java.util.Optional
+import kotlin.jvm.optionals.getOrNull
 
 /**
  * Cancels an in-progress batch. The batch will be in status `cancelling` for up to 10 minutes,
@@ -18,13 +18,13 @@ import java.util.Optional
  */
 class BatchCancelParams
 private constructor(
-    private val batchId: String,
+    private val batchId: String?,
     private val additionalHeaders: Headers,
     private val additionalQueryParams: QueryParams,
     private val additionalBodyProperties: Map<String, JsonValue>,
 ) : Params {
 
-    fun batchId(): String = batchId
+    fun batchId(): Optional<String> = Optional.ofNullable(batchId)
 
     fun _additionalBodyProperties(): Map<String, JsonValue> = additionalBodyProperties
 
@@ -36,14 +36,9 @@ private constructor(
 
     companion object {
 
-        /**
-         * Returns a mutable builder for constructing an instance of [BatchCancelParams].
-         *
-         * The following fields are required:
-         * ```java
-         * .batchId()
-         * ```
-         */
+        @JvmStatic fun none(): BatchCancelParams = builder().build()
+
+        /** Returns a mutable builder for constructing an instance of [BatchCancelParams]. */
         @JvmStatic fun builder() = Builder()
     }
 
@@ -63,7 +58,10 @@ private constructor(
             additionalBodyProperties = batchCancelParams.additionalBodyProperties.toMutableMap()
         }
 
-        fun batchId(batchId: String) = apply { this.batchId = batchId }
+        fun batchId(batchId: String?) = apply { this.batchId = batchId }
+
+        /** Alias for calling [Builder.batchId] with `batchId.orElse(null)`. */
+        fun batchId(batchId: Optional<String>) = batchId(batchId.getOrNull())
 
         fun additionalHeaders(additionalHeaders: Headers) = apply {
             this.additionalHeaders.clear()
@@ -189,17 +187,10 @@ private constructor(
          * Returns an immutable instance of [BatchCancelParams].
          *
          * Further updates to this [Builder] will not mutate the returned instance.
-         *
-         * The following fields are required:
-         * ```java
-         * .batchId()
-         * ```
-         *
-         * @throws IllegalStateException if any required field is unset.
          */
         fun build(): BatchCancelParams =
             BatchCancelParams(
-                checkRequired("batchId", batchId),
+                batchId,
                 additionalHeaders.build(),
                 additionalQueryParams.build(),
                 additionalBodyProperties.toImmutable(),
@@ -211,7 +202,7 @@ private constructor(
 
     fun _pathParam(index: Int): String =
         when (index) {
-            0 -> batchId
+            0 -> batchId ?: ""
             else -> ""
         }
 

openai-java-core/src/main/kotlin/com/openai/models/batches/BatchRetrieveParams.kt

@@ -3,20 +3,21 @@
 package com.openai.models.batches
 
 import com.openai.core.Params
-import com.openai.core.checkRequired
 import com.openai.core.http.Headers
 import com.openai.core.http.QueryParams
 import java.util.Objects
+import java.util.Optional
+import kotlin.jvm.optionals.getOrNull
 
 /** Retrieves a batch. */
 class BatchRetrieveParams
 private constructor(
-    private val batchId: String,
+    private val batchId: String?,
     private val additionalHeaders: Headers,
     private val additionalQueryParams: QueryParams,
 ) : Params {
 
-    fun batchId(): String = batchId
+    fun batchId(): Optional<String> = Optional.ofNullable(batchId)
 
     fun _additionalHeaders(): Headers = additionalHeaders
 
@@ -26,14 +27,9 @@ private constructor(
 
     companion object {
 
-        /**
-         * Returns a mutable builder for constructing an instance of [BatchRetrieveParams].
-         *
-         * The following fields are required:
-         * ```java
-         * .batchId()
-         * ```
-         */
+        @JvmStatic fun none(): BatchRetrieveParams = builder().build()
+
+        /** Returns a mutable builder for constructing an instance of [BatchRetrieveParams]. */
         @JvmStatic fun builder() = Builder()
     }
 
@@ -51,7 +47,10 @@ private constructor(
             additionalQueryParams = batchRetrieveParams.additionalQueryParams.toBuilder()
         }
 
-        fun batchId(batchId: String) = apply { this.batchId = batchId }
+        fun batchId(batchId: String?) = apply { this.batchId = batchId }
+
+        /** Alias for calling [Builder.batchId] with `batchId.orElse(null)`. */
+        fun batchId(batchId: Optional<String>) = batchId(batchId.getOrNull())
 
         fun additionalHeaders(additionalHeaders: Headers) = apply {
             this.additionalHeaders.clear()
@@ -155,25 +154,14 @@ private constructor(
          * Returns an immutable instance of [BatchRetrieveParams].
          *
          * Further updates to this [Builder] will not mutate the returned instance.
-         *
-         * The following fields are required:
-         * ```java
-         * .batchId()
-         * ```
-         *
-         * @throws IllegalStateException if any required field is unset.
          */
         fun build(): BatchRetrieveParams =
-            BatchRetrieveParams(
-                checkRequired("batchId", batchId),
-                additionalHeaders.build(),
-                additionalQueryParams.build(),
-            )
+            BatchRetrieveParams(batchId, additionalHeaders.build(), additionalQueryParams.build())
     }
 
     fun _pathParam(index: Int): String =
         when (index) {
-            0 -> batchId
+            0 -> batchId ?: ""
             else -> ""
         }
 

openai-java-core/src/main/kotlin/com/openai/models/beta/assistants/AssistantDeleteParams.kt

@@ -4,23 +4,23 @@ package com.openai.models.beta.assistants
 
 import com.openai.core.JsonValue
 import com.openai.core.Params
-import com.openai.core.checkRequired
 import com.openai.core.http.Headers
 import com.openai.core.http.QueryParams
 import com.openai.core.toImmutable
 import java.util.Objects
 import java.util.Optional
+import kotlin.jvm.optionals.getOrNull
 
 /** Delete an assistant. */
 class AssistantDeleteParams
 private constructor(
-    private val assistantId: String,
+    private val assistantId: String?,
     private val additionalHeaders: Headers,
     private val additionalQueryParams: QueryParams,
     private val additionalBodyProperties: Map<String, JsonValue>,
 ) : Params {
 
-    fun assistantId(): String = assistantId
+    fun assistantId(): Optional<String> = Optional.ofNullable(assistantId)
 
     fun _additionalBodyProperties(): Map<String, JsonValue> = additionalBodyProperties
 
@@ -32,14 +32,9 @@ private constructor(
 
     companion object {
 
-        /**
-         * Returns a mutable builder for constructing an instance of [AssistantDeleteParams].
-         *
-         * The following fields are required:
-         * ```java
-         * .assistantId()
-         * ```
-         */
+        @JvmStatic fun none(): AssistantDeleteParams = builder().build()
+
+        /** Returns a mutable builder for constructing an instance of [AssistantDeleteParams]. */
         @JvmStatic fun builder() = Builder()
     }
 
@@ -59,7 +54,10 @@ private constructor(
             additionalBodyProperties = assistantDeleteParams.additionalBodyProperties.toMutableMap()
         }
 
-        fun assistantId(assistantId: String) = apply { this.assistantId = assistantId }
+        fun assistantId(assistantId: String?) = apply { this.assistantId = assistantId }
+
+        /** Alias for calling [Builder.assistantId] with `assistantId.orElse(null)`. */
+        fun assistantId(assistantId: Optional<String>) = assistantId(assistantId.getOrNull())
 
         fun additionalHeaders(additionalHeaders: Headers) = apply {
             this.additionalHeaders.clear()
@@ -185,17 +183,10 @@ private constructor(
          * Returns an immutable instance of [AssistantDeleteParams].
          *
          * Further updates to this [Builder] will not mutate the returned instance.
-         *
-         * The following fields are required:
-         * ```java
-         * .assistantId()
-         * ```
-         *
-         * @throws IllegalStateException if any required field is unset.
          */
         fun build(): AssistantDeleteParams =
             AssistantDeleteParams(
-                checkRequired("assistantId", assistantId),
+                assistantId,
                 additionalHeaders.build(),
                 additionalQueryParams.build(),
                 additionalBodyProperties.toImmutable(),
@@ -207,7 +198,7 @@ private constructor(
 
     fun _pathParam(index: Int): String =
         when (index) {
-            0 -> assistantId
+            0 -> assistantId ?: ""
             else -> ""
         }
 

openai-java-core/src/main/kotlin/com/openai/models/beta/assistants/AssistantRetrieveParams.kt

@@ -3,20 +3,21 @@
 package com.openai.models.beta.assistants
 
 import com.openai.core.Params
-import com.openai.core.checkRequired
 import com.openai.core.http.Headers
 import com.openai.core.http.QueryParams
 import java.util.Objects
+import java.util.Optional
+import kotlin.jvm.optionals.getOrNull
 
 /** Retrieves an assistant. */
 class AssistantRetrieveParams
 private constructor(
-    private val assistantId: String,
+    private val assistantId: String?,
     private val additionalHeaders: Headers,
     private val additionalQueryParams: QueryParams,
 ) : Params {
 
-    fun assistantId(): String = assistantId
+    fun assistantId(): Optional<String> = Optional.ofNullable(assistantId)
 
     fun _additionalHeaders(): Headers = additionalHeaders
 
@@ -26,14 +27,9 @@ private constructor(
 
     companion object {
 
-        /**
-         * Returns a mutable builder for constructing an instance of [AssistantRetrieveParams].
-         *
-         * The following fields are required:
-         * ```java
-         * .assistantId()
-         * ```
-         */
+        @JvmStatic fun none(): AssistantRetrieveParams = builder().build()
+
+        /** Returns a mutable builder for constructing an instance of [AssistantRetrieveParams]. */
         @JvmStatic fun builder() = Builder()
     }
 
@@ -51,7 +47,10 @@ private constructor(
             additionalQueryParams = assistantRetrieveParams.additionalQueryParams.toBuilder()
         }
 
-        fun assistantId(assistantId: String) = apply { this.assistantId = assistantId }
+        fun assistantId(assistantId: String?) = apply { this.assistantId = assistantId }
+
+        /** Alias for calling [Builder.assistantId] with `assistantId.orElse(null)`. */
+        fun assistantId(assistantId: Optional<String>) = assistantId(assistantId.getOrNull())
 
         fun additionalHeaders(additionalHeaders: Headers) = apply {
             this.additionalHeaders.clear()
@@ -155,25 +154,18 @@ private constructor(
          * Returns an immutable instance of [AssistantRetrieveParams].
          *
          * Further updates to this [Builder] will not mutate the returned instance.
-         *
-         * The following fields are required:
-         * ```java
-         * .assistantId()
-         * ```
-         *
-         * @throws IllegalStateException if any required field is unset.
          */
         fun build(): AssistantRetrieveParams =
             AssistantRetrieveParams(
-                checkRequired("assistantId", assistantId),
+                assistantId,
                 additionalHeaders.build(),
                 additionalQueryParams.build(),
             )
     }
 
     fun _pathParam(index: Int): String =
         when (index) {
-            0 -> assistantId
+            0 -> assistantId ?: ""
             else -> ""
         }