Added JokeResponse data class

README.md

@@ -16,7 +16,7 @@ A simple library to retrieve jokes from [Sv443's JokeAPI](https://v2.jokeapi.dev
 ## Examples (TL;DR)
 
 ```kotlin
-import net.thauvin.erik.jokeapi.getJoke
+import net.thauvin.erik.jokeapi.joke
 
 val joke = joke()
 val safe = joke(safe = true)
@@ -124,8 +124,9 @@ You can also retrieve one or more raw (unprocessed) jokes in all [supported form
 
 For example for YAML:
 ```kotlin
-var joke = getRawJokes(format = Format.YAML, idRange = IdRange(22))
-println(joke)
+var jokes = getRawJokes(format = Format.YAML, idRange = IdRange(22))
+println(jokes.data)
+```
 ```
 ```yaml
 error: false
@@ -158,7 +159,7 @@ val lang = JokeApi.apiCall(
     path = "french",
     params = mapOf(Parameter.FORMAT to Format.YAML.value)
 )
-println(lang)
+println(lang.data)
 ```
 ```yaml
 error: false

src/main/kotlin/net/thauvin/erik/jokeapi/JokeApi.kt

@@ -54,7 +54,7 @@ object JokeApi {
     /**
      * Makes a direct API call.
      *
-     * Sse the [JokeAPI Documentation](https://jokeapi.dev/#endpoints) for more details.
+     * See the [JokeAPI Documentation](https://jokeapi.dev/#endpoints) for more details.
      */
     @JvmStatic
     @JvmOverloads
@@ -64,7 +64,7 @@ object JokeApi {
         path: String = "",
         params: Map<String, String> = emptyMap(),
         auth: String = ""
-    ): String {
+    ): JokeResponse {
         val urlBuilder = StringBuilder("$API_URL$endPoint")
 
         if (path.isNotEmpty()) {
@@ -98,7 +98,7 @@ object JokeApi {
      */
     @JvmStatic
     @Throws(HttpErrorException::class)
-    fun getRawJokes(config: JokeConfig): String {
+    fun getRawJokes(config: JokeConfig): JokeResponse {
         return rawJokes(
             categories = config.categories,
             lang = config.lang,
@@ -213,7 +213,7 @@ fun joke(
             idRange = idRange,
             safe = safe,
             auth = auth
-        )
+        ).data
     )
     if (json.getBoolean("error")) {
         throw parseError(json)
@@ -281,7 +281,7 @@ fun jokes(
             amount = amount,
             safe = safe,
             auth = auth
-        )
+        ).data
     )
     if (json.getBoolean("error")) {
         throw parseError(json)
@@ -333,6 +333,7 @@ fun jokes(
  * At the moment, you will only receive one of these tokens temporarily if something breaks or if you are a business
  * and need more than 120 requests per minute.
  */
+@Throws(HttpErrorException::class)
 fun rawJokes(
     categories: Set<Category> = setOf(Category.ANY),
     lang: Language = Language.EN,
@@ -344,7 +345,7 @@ fun rawJokes(
     amount: Int = 1,
     safe: Boolean = false,
     auth: String = ""
-): String {
+): JokeResponse {
     val params = mutableMapOf<String, String>()
 
     // Categories

src/main/kotlin/net/thauvin/erik/jokeapi/JokeUtil.kt

@@ -45,7 +45,7 @@ import java.util.logging.Level
 /**
  * Fetch a URL.
  */
-internal fun fetchUrl(url: String, auth: String = ""): String {
+internal fun fetchUrl(url: String, auth: String = ""): JokeResponse {
     if (JokeApi.logger.isLoggable(Level.FINE)) {
         JokeApi.logger.fine(url)
     }
@@ -63,11 +63,10 @@ internal fun fetchUrl(url: String, auth: String = ""): String {
         val body = stream.bufferedReader().use { it.readText() }
         if (body.isBlank()) {
             throw httpError(connection.responseCode)
-        }
-        if (JokeApi.logger.isLoggable(Level.FINE)) {
+        } else if (JokeApi.logger.isLoggable(Level.FINE)) {
             JokeApi.logger.fine(body)
         }
-        return body
+        return JokeResponse(connection.responseCode, body)
     } finally {
         connection.disconnect()
     }

src/main/kotlin/net/thauvin/erik/jokeapi/exceptions/HttpErrorException.kt

@@ -44,7 +44,6 @@ class HttpErrorException @JvmOverloads constructor(
     cause: Throwable? = null
 ) : IOException(message, cause) {
     companion object {
-        @Suppress("ConstPropertyName")
         private const val serialVersionUID = 1L
     }
 }

src/main/kotlin/net/thauvin/erik/jokeapi/models/JokeResponse.kt

@@ -0,0 +1,39 @@
+/*
+ * JokeResponse.kt
+ *
+ * Copyright 2022-2024 Erik C. Thauvin (erik@thauvin.net)
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ *   Redistributions of source code must retain the above copyright notice, this
+ *   list of conditions and the following disclaimer.
+ *
+ *   Redistributions in binary form must reproduce the above copyright notice,
+ *   this list of conditions and the following disclaimer in the documentation
+ *   and/or other materials provided with the distribution.
+ *
+ *   Neither the name of this project nor the names of its contributors may be
+ *   used to endorse or promote products derived from this software without
+ *   specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+ * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+ * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+ * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+ * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+package net.thauvin.erik.jokeapi.models
+
+/**
+ * The Joke API response.
+ *
+ * @property code The HTTP status code.
+ * @property data The response text.
+ */
+data class JokeResponse(val code: Int, val data: String)

src/main/kotlin/net/thauvin/erik/jokeapi/models/Parameter.kt

@@ -34,6 +34,7 @@ package net.thauvin.erik.jokeapi.models
 /**
  * The available [URL Parameters](https://jokeapi.dev/#url-parameters).
  */
+@Suppress("unused")
 object Parameter {
     const val AMOUNT = "amount"
     const val CONTAINS = "contains"

src/test/kotlin/net/thauvin/erik/jokeapi/ApiCallTest.kt

@@ -32,6 +32,7 @@
 package net.thauvin.erik.jokeapi
 
 import assertk.assertThat
+import assertk.assertions.isEqualTo
 import assertk.assertions.isGreaterThan
 import assertk.assertions.startsWith
 import net.thauvin.erik.jokeapi.JokeApi.apiCall
@@ -51,8 +52,9 @@ internal class ApiCallTest {
     fun `Get Flags`() {
         // See https://v2.jokeapi.dev/#flags-endpoint
         val response = apiCall(endPoint = "flags")
-        val json = JSONObject(response)
-        assertAll("Validate JSON",
+        val json = JSONObject(response.data)
+        assertAll(
+            "Validate JSON",
             { assertFalse(json.getBoolean("error"), "apiCall(flags).error") },
             { assertThat(json.getJSONArray("flags").length(), "apiCall(flags).flags").isGreaterThan(0) },
             { assertThat(json.getLong("timestamp"), "apiCall(flags).timestamp").isGreaterThan(0) })
@@ -65,14 +67,16 @@ internal class ApiCallTest {
             endPoint = "langcode", path = "french",
             params = mapOf(Parameter.FORMAT to Format.YAML.value)
         )
-        assertContains(lang, "code: \"fr\"", false, "apiCall(langcode, french, yaml)")
+        assertThat(lang.code).isEqualTo(200)
+        assertContains(lang.data, "code: \"fr\"", false, "apiCall(langcode, french, yaml)")
     }
 
     @Test
     fun `Get Ping Response`() {
         // See https://v2.jokeapi.dev/#ping-endpoint
         val ping = apiCall(endPoint = "ping", params = mapOf(Parameter.FORMAT to Format.TXT.value))
-        assertThat(ping, "apiCall(ping, txt)").startsWith("Pong!")
+        assertThat(ping.code).isEqualTo(200)
+        assertThat(ping.data).startsWith("Pong!")
     }
 
     @Test
@@ -82,6 +86,7 @@ internal class ApiCallTest {
             endPoint = "languages",
             params = mapOf(Parameter.FORMAT to Format.XML.value, Parameter.LANG to Language.FR.value)
         )
-        assertThat(lang).startsWith("<?xml version='1.0'?>")
+        assertThat(lang.code).isEqualTo(200)
+        assertThat(lang.data).startsWith("<?xml version='1.0'?>")
     }
 }

src/test/kotlin/net/thauvin/erik/jokeapi/GetRawJokesTest.kt

@@ -34,6 +34,7 @@ package net.thauvin.erik.jokeapi
 import assertk.all
 import assertk.assertThat
 import assertk.assertions.doesNotContain
+import assertk.assertions.isEqualTo
 import assertk.assertions.isNotEmpty
 import assertk.assertions.startsWith
 import net.thauvin.erik.jokeapi.models.Format
@@ -47,7 +48,8 @@ internal class GetRawJokesTest {
     @Test
     fun `Get Raw Joke with TXT`() {
         val response = rawJokes(format = Format.TXT)
-        assertThat(response, "rawJoke(txt)").all {
+        assertThat(response.code).isEqualTo(200)
+        assertThat(response.data, "rawJoke(data)").all {
             isNotEmpty()
             doesNotContain("Error")
         }
@@ -56,24 +58,28 @@ internal class GetRawJokesTest {
     @Test
     fun `Get Raw Joke with XML`() {
         val response = rawJokes(format = Format.XML)
-        assertThat(response, "rawJoke(xml)").startsWith("<?xml version='1.0'?>\n<data>\n    <error>false</error>")
+        assertThat(response.code).isEqualTo(200)
+        assertThat(response.data, "rawJoke(xml)").startsWith("<?xml version='1.0'?>\n<data>\n    <error>false</error>")
     }
 
     @Test
     fun `Get Raw Joke with YAML`() {
         val response = rawJokes(format = Format.YAML)
-        assertThat(response, "rawJoke(yaml)").startsWith("error: false")
+        assertThat(response.code).isEqualTo(200)
+        assertThat(response.data, "rawJoke(yaml)").startsWith("error: false")
     }
 
     @Test
     fun `Get Raw Jokes`() {
         val response = rawJokes(amount = 2)
-        assertContains(response, "\"amount\": 2", false, "rawJoke(2)")
+        assertThat(response.code).isEqualTo(200)
+        assertContains(response.data, "\"amount\": 2", false, "rawJoke(2)")
     }
 
     @Test
     fun `Get Raw Invalid Jokes`() {
         val response = rawJokes(contains = "foo", safe = true, amount = 2, idRange = IdRange(160, 161))
-        assertContains(response, "\"error\": true", false, "getRawJokes(foo)")
+        assertThat(response.code).isEqualTo(400)
+        assertContains(response.data, "\"error\": true", false, "getRawJokes(foo)")
     }
 }

src/test/kotlin/net/thauvin/erik/jokeapi/JokeConfigTest.kt

@@ -102,8 +102,9 @@ internal class JokeConfigTest {
             amount(2)
             safe(true)
         }.build()
-        val joke = getRawJokes(config)
-        assertContains(joke, "----------------------------------------------", false, "config.amount(2)")
+        val jokes = getRawJokes(config)
+        assertThat(jokes.code).isEqualTo(200)
+        assertContains(jokes.data, "----------------------------------------------", false, "config.amount(2)")
     }
 
     @Test

src/test/kotlin/net/thauvin/erik/jokeapi/JokeUtilTest.kt

@@ -33,6 +33,7 @@ package net.thauvin.erik.jokeapi
 
 import assertk.assertThat
 import assertk.assertions.contains
+import assertk.assertions.isEqualTo
 import org.json.JSONException
 import org.json.JSONObject
 import org.junit.jupiter.api.Test
@@ -54,7 +55,8 @@ internal class JokeUtilTest {
     @Test
     fun `Validate Authentication Header`() {
         val token = "AUTH-TOKEN"
-        val body = fetchUrl("https://postman-echo.com/get", token)
-        assertThat(body, "body").contains("\"authentication\": \"$token\"")
+        val response = fetchUrl("https://postman-echo.com/get", token)
+        assertThat(response.code).isEqualTo(200)
+        assertThat(response.data, "body").contains("\"authentication\": \"$token\"")
     }
 }