chore: add support for new friends APIs (#35)

Author: gastongaiduk

README.md

@@ -1177,6 +1177,76 @@ if (response is NetworkResponse.Success) {
 
 </details>
 
+<details>
+<summary>GetUsersIFollow</summary>
+<br>
+
+> A call to this endpoint will retrieve a list of users that I follow.
+
+**Available Parameters**
+
+| Name   | Type | Description                            | Example | Default |
+|:-------|:-----|:---------------------------------------|:--------|:--------|
+| offset | Int  | number of entries to skip              | 100     | 0       |
+| count  | Int  | number of entries to return (max: 500) | 50      | 100     |
+
+**Example**
+```kotlin
+val credentials = RetroCredentials("<username>", "<web api key>")
+val api: RetroInterface = RetroClient(credentials).api
+
+val response: NetworkResponse<GetUsersIFollow.Response, ErrorResponse> = api.getUsersIFollow()
+
+if (response is NetworkResponse.Success) {
+    // handle the data
+    val users: GetUsersIFollow.Response = response.body
+
+} else if (response is NetworkResponse.Error) {
+    // if the server returns an error it be found here
+    val errorResponse: ErrorResponse? = response.body
+
+    // if the api (locally) had an internal error, it'll be found here
+    val internalError: Throwable? = response.error
+}
+```
+
+</details>
+
+<details>
+<summary>GetUsersFollowingMe</summary>
+<br>
+
+> A call to this endpoint will retrieve a list of users that are following me.
+
+**Available Parameters**
+
+| Name   | Type | Description                            | Example | Default |
+|:-------|:-----|:---------------------------------------|:--------|:--------|
+| offset | Int  | number of entries to skip              | 100     | 0       |
+| count  | Int  | number of entries to return (max: 500) | 50      | 100     |
+
+**Example**
+```kotlin
+val credentials = RetroCredentials("<username>", "<web api key>")
+val api: RetroInterface = RetroClient(credentials).api
+
+val response: NetworkResponse<GetUsersFollowingMe.Response, ErrorResponse> = api.getUsersFollowingMe()
+
+if (response is NetworkResponse.Success) {
+    // handle the data
+    val users: GetUsersFollowingMe.Response = response.body
+
+} else if (response is NetworkResponse.Error) {
+    // if the server returns an error it be found here
+    val errorResponse: ErrorResponse? = response.body
+
+    // if the api (locally) had an internal error, it'll be found here
+    val internalError: Throwable? = response.error
+}
+```
+
+</details>
+
 ## Testing
 
 Apache maven must be correctly installed on the system.

pom.xml

@@ -6,7 +6,7 @@
 
     <groupId>org.retroachievements</groupId>
     <artifactId>api-kotlin</artifactId>
-    <version>1.0.12</version>
+    <version>1.0.13</version>
 
     <dependencyManagement>
         <dependencies>

src/main/kotlin/org/retroachivements/api/RetroInterface.kt

@@ -171,6 +171,26 @@ interface RetroInterface {
         @Query("u") username: String
     ): NetworkResponse<GetUserCompletedGames.Response, ErrorResponse>
 
+    /**
+     * A call to this endpoint will retrieve a list of users that I follow.
+     */
+    @Mock @MockResponse(body = "/v1/user/GetUsersIFollow.json")
+    @POST("/API/API_GetUsersIFollow.php")
+    suspend fun getUsersIFollow(
+        @Query("o") offset: Int = 0,
+        @Query("c") count: Int = 100
+    ): NetworkResponse<GetUsersIFollow.Response, ErrorResponse>
+
+    /**
+     * A call to this endpoint will retrieve a list of users that are following me.
+     */
+    @Mock @MockResponse(body = "/v1/user/GetUsersFollowingMe.json")
+    @POST("/API/GetUsersFollowingMe.php")
+    suspend fun getUsersFollowingMe(
+        @Query("o") offset: Int = 0,
+        @Query("c") count: Int = 100
+    ): NetworkResponse<GetUsersFollowingMe.Response, ErrorResponse>
+
     /**
      * A call to this endpoint will retrieve basic metadata about a game, targeted via its unique ID.
      */

src/main/kotlin/org/retroachivements/api/data/pojo/user/GetUsersFollowingMe.kt

@@ -0,0 +1,26 @@
+package org.retroachivements.api.data.pojo.user
+
+import com.google.gson.annotations.SerializedName
+
+class GetUsersFollowingMe {
+    data class Response(
+        @SerializedName("Count")
+        val count: Long,
+        @SerializedName("Total")
+        val total: Long,
+        @SerializedName("Results")
+        val results: List<User>,
+    )
+
+    data class User(
+        @SerializedName("User")
+        val user: String,
+        @SerializedName("Points")
+        val points: Long,
+        @SerializedName("PointsSoftcore")
+        val pointsSoftcore: Long,
+        @SerializedName("AmIFollowing")
+        val amIFollowing: Boolean,
+    )
+
+}

src/main/kotlin/org/retroachivements/api/data/pojo/user/GetUsersIFollow.kt

@@ -0,0 +1,26 @@
+package org.retroachivements.api.data.pojo.user
+
+import com.google.gson.annotations.SerializedName
+
+class GetUsersIFollow {
+    data class Response(
+        @SerializedName("Count")
+        val count: Long,
+        @SerializedName("Total")
+        val total: Long,
+        @SerializedName("Results")
+        val results: List<User>,
+    )
+
+    data class User(
+        @SerializedName("User")
+        val user: String,
+        @SerializedName("Points")
+        val points: Long,
+        @SerializedName("PointsSoftcore")
+        val pointsSoftcore: Long,
+        @SerializedName("IsFollowingMe")
+        val isFollowingMe: Boolean,
+    )
+
+}

src/main/resources/mock/v1/user/GetUsersFollowingMe.json

@@ -0,0 +1,24 @@
+{
+    "Count": 3,
+    "Total": 3,
+    "Results": [
+        {
+            "User": "zuliman92",
+            "Points": 2071,
+            "PointsSoftcore": 258,
+            "AmIFollowing": true
+        },
+        {
+            "User": "SLOslobulus",
+            "Points": 7081,
+            "PointsSoftcore": 0,
+            "AmIFollowing": true
+        },
+        {
+            "User": "Moderator",
+            "Points": 1000,
+            "PointsSoftcore": 100,
+            "AmIFollowing": false
+        }
+    ]
+}

src/main/resources/mock/v1/user/GetUsersIFollow.json

@@ -0,0 +1,24 @@
+{
+    "Count": 3,
+    "Total": 3,
+    "Results": [
+        {
+            "User": "zuliman92",
+            "Points": 2071,
+            "PointsSoftcore": 258,
+            "IsFollowingMe": true
+        },
+        {
+            "User": "Jamiras",
+            "Points": 117273 ,
+            "PointsSoftcore": 1350,
+            "IsFollowingMe": false
+        },
+        {
+            "User": "SLOslobulus",
+            "Points": 7081,
+            "PointsSoftcore": 0,
+            "IsFollowingMe": true
+        }
+    ]
+}

src/test/kotlin/org/retroachivements/api/RetroInterfaceTest.kt

@@ -308,6 +308,38 @@ class RetroInterfaceTest {
         }
     }
 
+    @Test
+    fun `check getUsersIFollow response parser`() {
+
+        runBlocking {
+
+            // obtain mocked version of the API
+            val api = createMockedApi()
+
+            val getUsersIFollow: NetworkResponse<GetUsersIFollow.Response, ErrorResponse> = api.getUsersIFollow()
+
+            assert(getUsersIFollow is NetworkResponse.Success)
+
+            assertNotNull((getUsersIFollow as NetworkResponse.Success).body)
+        }
+    }
+
+    @Test
+    fun `check getUsersFollowingMe response parser`() {
+
+        runBlocking {
+
+            // obtain mocked version of the API
+            val api = createMockedApi()
+
+            val getUsersFollowingMe: NetworkResponse<GetUsersFollowingMe.Response, ErrorResponse> = api.getUsersFollowingMe()
+
+            assert(getUsersFollowingMe is NetworkResponse.Success)
+
+            assertNotNull((getUsersFollowingMe as NetworkResponse.Success).body)
+        }
+    }
+
     @Test
     fun `check getGame response parser`() {