add unix time + java.time wrappers

Author: CJCrafter

src/main/kotlin/com/cjcrafter/openai/chat/ChatResponse.kt

@@ -1,22 +1,26 @@
 package com.cjcrafter.openai.chat
 
 import com.google.gson.JsonObject
+import java.time.Instant
+import java.time.ZoneId
+import java.time.ZonedDateTime
+import java.util.*
 
 /**
  * The [ChatResponse] contains all the data returned by the OpenAI Chat API.
  * For most use cases, [ChatResponse.get] (passing 0 to the index argument) is
  * all you need.
  *
- * @property id
- * @property object
- * @property created
- * @property choices
- * @property usage
- * @constructor Create empty Chat response
+ * @property id      The unique id for your request.
+ * @property created The Unix timestamp (measured in seconds since 00:00:00 UTC on January 1, 1970) when the API response was created.
+ * @property choices The list of generated messages.
+ * @property usage   The number of tokens used in this request/response.
+ * @constructor Create Chat response (for internal usage).
+ * @see ChatChoice
+ * @see ChatUsage
  */
-class ChatResponse(
+data class ChatResponse(
     val id: String,
-    val `object`: String,
     val created: Long,
     val choices: List<ChatChoice>,
     val usage: ChatUsage
@@ -27,12 +31,39 @@ class ChatResponse(
      */
     constructor(json: JsonObject) : this(
         json["id"].asString,
-        json["object"].asString,
         json["created"].asLong,
         json["choices"].asJsonArray.map { ChatChoice(it.asJsonObject) },
         ChatUsage(json["usage"].asJsonObject)
     )
 
+    /**
+     * Returns the [Instant] time that the OpenAI Chat API sent this response.
+     * The time is measured as a unix timestamp (measured in seconds since
+     * 00:00:00 UTC on January 1, 1970).
+     *
+     * Note that users expect time to be measured in their timezone, so
+     * [getZonedTime] is preferred.
+     *
+     * @return The instant the api created this response.
+     * @see getZonedTime
+     */
+    fun getTime(): Instant {
+        return Instant.ofEpochSecond(created)
+    }
+
+    /**
+     * Returns the time-zoned instant that the OpenAI Chat API sent this
+     * response. By default, this method uses the system's timezone.
+     *
+     * @param timezone The user's timezone.
+     * @return The timezone adjusted date time.
+     * @see TimeZone.getDefault
+     */
+    @JvmOverloads
+    fun getZonedTime(timezone: ZoneId = TimeZone.getDefault().toZoneId()): ZonedDateTime {
+        return ZonedDateTime.ofInstant(getTime(), timezone)
+    }
+
     /**
      * Shorthand for accessing the generated messages (shorthand for
      * [ChatResponse.choices]).