fix list responses not being nullable for empty lists

Author: CJCrafter

build.gradle.kts

@@ -1,7 +1,7 @@
 import com.github.breadmoirai.githubreleaseplugin.GithubReleaseTask
 
 group = "com.cjcrafter"
-version = "2.0.2"
+version = "2.0.2-SNAPSHOT"
 
 plugins {
     `java-library`

examples/build.gradle.kts

@@ -14,7 +14,7 @@ dependencies {
     implementation("com.fasterxml.jackson.core:jackson-databind:2.15.3")
     implementation("io.github.cdimascio:dotenv-kotlin:6.4.1")
 
-    implementation("ch.qos.logback:logback-classic:1.4.11")
+    implementation("ch.qos.logback:logback-classic:1.4.12")
 
     // https://mvnrepository.com/artifact/org.mariuszgromada.math/MathParser.org-mXparser
     // Used for tool tests

src/main/kotlin/com/cjcrafter/openai/assistants/ListAssistantResponse.kt

@@ -2,9 +2,19 @@ package com.cjcrafter.openai.assistants
 
 import com.fasterxml.jackson.annotation.JsonProperty
 
+/**
+ * A data class which represents a response from the OpenAI API containing a list of [Assistant]s.
+ *
+ * When the list is empty, [firstId] and [lastId] will be `null`.
+ *
+ * @property data The list of assistants
+ * @property firstId The ID of the first [Assistant] in the list, or null
+ * @property lastId The ID of the last [Assistant] in the list, or null
+ * @property hasMore Whether there are more [Assistant]s to retrieve from the API
+ */
 data class ListAssistantResponse(
     @JsonProperty(required = true) val data: List<Assistant>,
-    @JsonProperty("first_id", required = true) val firstId: String,
-    @JsonProperty("last_id", required = true) val lastId: String,
+    @JsonProperty("first_id") val firstId: String?,
+    @JsonProperty("last_id") val lastId: String?,
     @JsonProperty("has_more", required = true) val hasMore: Boolean,
 )

src/main/kotlin/com/cjcrafter/openai/files/ListFilesResponse.kt

@@ -6,6 +6,7 @@ import com.fasterxml.jackson.annotation.JsonProperty
  * Represents a response from the [list files](https://platform.openai.com/docs/api-reference/files)
  * endpoint.
  *
+ * @property hasMore Whether there are more files to retrieve from the API.
  * @property data The list of files.
  */
 data class ListFilesResponse(

src/main/kotlin/com/cjcrafter/openai/threads/message/ListMessageFilesResponse.kt

@@ -5,14 +5,16 @@ import com.fasterxml.jackson.annotation.JsonProperty
 /**
  * A data class which represents a response from the OpenAI API containing a list of [MessageFile]s.
  *
+ * When the list is empty, [firstId] and [lastId] will be `null`.
+ *
  * @property data The list of [MessageFile]s
- * @property firstId The ID of the first [MessageFile] in the list
- * @property lastId The ID of the last [MessageFile] in the list
+ * @property firstId The ID of the first [MessageFile] in the list, or null
+ * @property lastId The ID of the last [MessageFile] in the list, or null
  * @property hasMore Whether there are more [MessageFile]s to retrieve from the API
  */
 data class ListMessageFilesResponse(
     @JsonProperty(required = true) val data: List<MessageFile>,
-    @JsonProperty("first_id", required = true) val firstId: String,
-    @JsonProperty("last_id", required = true) val lastId: String,
+    @JsonProperty("first_id") val firstId: String?,
+    @JsonProperty("last_id") val lastId: String?,
     @JsonProperty("has_more", required = true) val hasMore: Boolean,
 )

src/main/kotlin/com/cjcrafter/openai/threads/message/ListThreadMessagesResponse.kt

@@ -1,21 +1,20 @@
 package com.cjcrafter.openai.threads.message
 
-import com.cjcrafter.openai.threads.Thread
 import com.fasterxml.jackson.annotation.JsonProperty
 
 /**
- * Represents a response from the [ListThreadMessagesRequest]. This contains a
- * list of [ThreadMessage]s. If you are trying to get **every** message in a
- * [Thread], you might need to make multiple requests.
+ * A data class which represents a response from the OpenAI API containing a list of [ThreadMessage]s.
+ *
+ * If the list is empty, [firstId] and [lastId] will be `null`.
  *
  * @property data The list of thread messages
- * @property firstId The id of the first message in the list
- * @property lastId The id of the last message in the list
+ * @property firstId The id of the first message in the list, or null
+ * @property lastId The id of the last message in the list, or null
  * @property hasMore Whether there are more messages to retrieve
  */
 data class ListThreadMessagesResponse(
     @JsonProperty(required = true) val data: List<ThreadMessage>,
-    @JsonProperty("first_id", required = true) val firstId: String,
-    @JsonProperty("last_id", required = true) val lastId: String,
+    @JsonProperty("first_id") val firstId: String?,
+    @JsonProperty("last_id") val lastId: String?,
     @JsonProperty("has_more", required = true) val hasMore: Boolean,
 )

src/main/kotlin/com/cjcrafter/openai/threads/runs/CreateRunRequest.kt

@@ -22,21 +22,51 @@ data class CreateRunRequest(
     var metadata: Map<String, String>? = null,
 ) {
 
+    /**
+     * Builder for [CreateRunRequest].
+     */
     @OpenAIDslMarker
     class Builder internal constructor() {
+
         private var assistantId: String? = null
         private var model: String? = null
         private var instructions: String? = null
         private var tools: MutableList<Tool>? = null
         private var metadata: MutableMap<String, String>? = null
 
+        /**
+         * Sets the assistant to use for the run. Shorthand for [assistantId].
+         */
         fun assistant(assistant: Assistant) = apply { this.assistantId = assistant.id }
+
+        /**
+         * Sets the assistant to use for the run.
+         */
         fun assistantId(assistantId: String) = apply { this.assistantId = assistantId }
+
+        /**
+         * Sets the model to override the assistant's default model.
+         */
         fun model(model: String) = apply { this.model = model }
+
+        /**
+         * Sets the instructions to override the assistant's default instructions.
+         */
         fun instructions(instructions: String) = apply { this.instructions = instructions }
+
+        /**
+         * Sets the tools to override the assistant's default tools.
+         */
         fun tools(tools: MutableList<Tool>) = apply { this.tools = tools }
+
+        /**
+         * Sets the metadata to attach to the [Run].
+         */
         fun metadata(metadata: MutableMap<String, String>) = apply { this.metadata = metadata }
 
+        /**
+         * Builds the [CreateRunRequest].
+         */
         fun build() = CreateRunRequest(
             assistantId = assistantId ?: throw IllegalStateException("assistantId must be set"),
             model = model,

src/main/kotlin/com/cjcrafter/openai/threads/runs/ListRunStepsResponse.kt

@@ -5,14 +5,16 @@ import com.fasterxml.jackson.annotation.JsonProperty
 /**
  * A data class which represents a response from the OpenAI API containing a list of [RunStep]s.
  *
+ * When the list is empty, [firstId] and [lastId] will be `null`.
+ *
  * @property data The list of [RunStep]s
- * @property firstId The ID of the first [RunStep] in the list
- * @property lastId The ID of the last [RunStep] in the list
+ * @property firstId The ID of the first [RunStep] in the list, or null
+ * @property lastId The ID of the last [RunStep] in the list, or null
  * @property hasMore Whether there are more [RunStep]s to retrieve from the API
  */
 data class ListRunStepsResponse(
     @JsonProperty(required = true) val data: List<RunStep>,
-    @JsonProperty("first_id", required = true) val firstId: String,
-    @JsonProperty("last_id", required = true) val lastId: String,
+    @JsonProperty("first_id") val firstId: String?,
+    @JsonProperty("last_id") val lastId: String?,
     @JsonProperty("has_more", required = true) val hasMore: Boolean,
 )

src/main/kotlin/com/cjcrafter/openai/threads/runs/ListRunsResponse.kt

@@ -5,14 +5,16 @@ import com.fasterxml.jackson.annotation.JsonProperty
 /**
  * A data class which represents a response from the OpenAI API containing a list of [Run]s.
  *
+ * When the list is empty, [firstId] and [lastId] will be `null`.
+ *
  * @property data The list of [Run]s
- * @property firstId The ID of the first [Run] in the list
- * @property lastId The ID of the last [Run] in the list
+ * @property firstId The ID of the first [Run] in the list, or null
+ * @property lastId The ID of the last [Run] in the list, or null
  * @property hasMore Whether there are more [Run]s to retrieve from the API
  */
 data class ListRunsResponse(
     @JsonProperty(required = true) val data: List<Run>,
-    @JsonProperty("first_id", required = true) val firstId: String,
-    @JsonProperty("last_id", required = true) val lastId: String,
+    @JsonProperty("first_id") val firstId: String?,
+    @JsonProperty("last_id") val lastId: String?,
     @JsonProperty("has_more", required = true) val hasMore: Boolean,
 )