Feat: add missing endpoints & features (#45)

* chore: Change Version

* chore: Change Version

* chore: Change Version

* feat: add richPresenceMsgDate

* feat: add GetGameProgression

* feat: add UserTotalPlaytime

* feat: add includeUserAward to getGameInfoAndUserProgress

* feat: add ReleasedAtGranularity

* feat: add offset & count for API_GetGameList

* chore: format

* chore: format

* feat: add GetUserSetRequests

* feat: add GetUserSetRequests

* feat: add GetUserGameLeaderboard

* fix: getUserSetRequests response

* feat: add getUserSetRequests & getUserGameLeaderboards tests

* feat: add releasedAtGranularity

* feat: add sort to API_GetComments

* feat: add Author and AuthorULID

* feat: add trueRatio

* chore: version change

* chore: make userId optional for getUserGameLeaderboards

* docs: update version change

Author: official-wizard

README.md

@@ -26,7 +26,7 @@ Then add this `api-kotlin` dependency to your `pom.xml` project!
 <dependency>    
     <groupId>com.github.RetroAchievements</groupId>    
     <artifactId>api-kotlin</artifactId>    
-    <version>1.0.18</version>
+    <version>1.1.0</version>
 </dependency>
 ```
 

pom.xml

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

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

@@ -80,9 +80,20 @@ interface RetroInterface {
     @POST("/API/API_GetGameInfoAndUserProgress.php")
     suspend fun getGameInfoAndUserProgress(
         @Query("u") username: String,
-        @Query("g") gameId: Long
+        @Query("g") gameId: Long,
+        @Query("a") includeUserAward: Int = 0
     ): NetworkResponse<GetGameInfoAndUserProgress.Response, ErrorResponse>
 
+    /**
+     * A call to this endpoint will retrieve information about the average time to unlock achievements in a game, targeted via its unique ID.
+     */
+    @Mock @MockResponse(body = "/v1/game/GetGameProgression.json")
+    @POST("/API/API_GetGameProgression.php")
+    suspend fun getGameProgression(
+        @Query("i") gameId: Long,
+        @Query("h") hardcore: Int = 0
+    ): NetworkResponse<GetGameProgression.Response, ErrorResponse>
+
     /**
      * A call to this function will retrieve a giver user's completion progress, targeted by their username.
      */
@@ -205,6 +216,16 @@ interface RetroInterface {
         @Query("c") count: Int = 100
     ): NetworkResponse<GetUsersFollowingMe.Response, ErrorResponse>
 
+    /**
+     * A call to this endpoint will retrieve a given user's set requests, maximum total requests and points until next request.
+     */
+    @Mock @MockResponse(body = "/v1/user/GetUserSetRequests.json")
+    @POST("/API/API_GetUserSetRequests.php")
+    suspend fun getUserSetRequests(
+        @Query("u") userId: String,
+        @Query("t") all: Int = 0
+    ): NetworkResponse<GetUserSetRequests.Response, ErrorResponse>
+
     /**
      * A call to this function will retrieve basic metadata about a game, targeted via its unique ID.
      */
@@ -291,6 +312,18 @@ interface RetroInterface {
         @Query("c") count: Int = 100
     ): NetworkResponse<GetLeaderboardEntries.Response, ErrorResponse>
 
+    /**
+     * A call to this function will retrieve a given leaderboard's entries, targeted by its ID.
+     */
+    @Mock @MockResponse(body = "/v1/game/GetUserGameLeaderboards.json")
+    @POST("/API/API_GetUserGameLeaderboards.php")
+    suspend fun getUserGameLeaderboards(
+        @Query("i") gameId: Long,
+        @Query("u") userId: String? = null,
+        @Query("o") offset: Int = 0,
+        @Query("c") count: Int = 100
+    ): NetworkResponse<GetUserGameLeaderboard.Response, ErrorResponse>
+
     /**
      * A call to this function will retrieve the complete list of all system ID and name pairs on the site.
      *
@@ -315,7 +348,9 @@ interface RetroInterface {
     suspend fun getGameList(
         @Query("i") consoleId: Long,
         @Query("f") shouldOnlyRetrieveGamesWithAchievements: Int = 0,
-        @Query("h") shouldRetrieveGameHashes: Int = 0
+        @Query("h") shouldRetrieveGameHashes: Int = 0,
+        @Query("o") offset: Int = 0,
+        @Query("c") count: Int = 0
     ): NetworkResponse<GetGameList.Response, ErrorResponse>
 
     /**
@@ -438,7 +473,8 @@ interface RetroInterface {
         @Query("i") username: String,
         @Query("c") count: Int = 10,
         @Query("o") offset: Int = 0,
-        @Query("t") type: Int = 3
+        @Query("t") type: Int = 3,
+        @Query("sort") sort: String = "submitted"
     ): NetworkResponse<GetComments.Response, ErrorResponse>
 
     /**
@@ -450,7 +486,8 @@ interface RetroInterface {
         @Query("i") gameId: Long,
         @Query("c") count: Int = 10,
         @Query("o") offset: Int = 0,
-        @Query("t") type: Int = 1
+        @Query("t") type: Int = 1,
+        @Query("sort") sort: String = "submitted"
     ): NetworkResponse<GetComments.Response, ErrorResponse>
 
     /**
@@ -462,6 +499,7 @@ interface RetroInterface {
         @Query("i") achievementId: Long,
         @Query("c") count: Int = 10,
         @Query("o") offset: Int = 0,
-        @Query("t") type: Int = 2
+        @Query("t") type: Int = 2,
+        @Query("sort") sort: String = "submitted"
     ): NetworkResponse<GetComments.Response, ErrorResponse>
 }

src/main/kotlin/org/retroachivements/api/data/pojo/game/GetGame.kt

@@ -50,6 +50,9 @@ class GetGame {
         @SerializedName("Released")
         val released: String?,
 
+        @SerializedName("ReleasedAtGranularity")
+        val releasedAtGranularity: String?,
+
         @SerializedName("GameTitle")
         val gameTitle: String,
 

src/main/kotlin/org/retroachivements/api/data/pojo/game/GetGameExtended.kt

@@ -44,6 +44,9 @@ class GetGameExtended {
         @SerializedName("Released")
         val released: String?,
 
+        @SerializedName("ReleasedAtGranularity")
+        val releasedAtGranularity: String?,
+
         @SerializedName("IsFinal")
         val isFinal: Boolean,
 

src/main/kotlin/org/retroachivements/api/data/pojo/game/GetGameHashes.kt

@@ -11,10 +11,13 @@ class GetGameHashes {
     data class Result(
         @SerializedName("Name")
         val name: String,
+
         @SerializedName("MD5")
         val md5: String,
+
         @SerializedName("Labels")
         val labels: List<String>,
+
         @SerializedName("PatchUrl")
         val patchUrl: String?,
     )

src/main/kotlin/org/retroachivements/api/data/pojo/game/GetGameInfoAndUserProgress.kt

@@ -56,6 +56,9 @@ class GetGameInfoAndUserProgress {
         @SerializedName("PlayersTotal")
         val playersTotal: Int,
 
+        @SerializedName("UserTotalPlaytime")
+        val userTotalPlaytime: Int,
+
         @SerializedName("GuideURL")
         val guideUrl: String?,
 

src/main/kotlin/org/retroachivements/api/data/pojo/game/GetGameLeaderboards.kt

@@ -3,35 +3,54 @@ package org.retroachivements.api.data.pojo.game
 import com.google.gson.annotations.SerializedName
 
 class GetGameLeaderboards {
+
     data class Response(
         @SerializedName("Count")
         val count: Long,
+
         @SerializedName("Total")
         val total: Long,
+
         @SerializedName("Results")
         val results: List<Leaderboard>,
     )
 
     data class Leaderboard(
         @SerializedName("ID")
         val id: Long,
+
         @SerializedName("RankAsc")
         val rankAsc: Boolean,
+
         @SerializedName("Title")
         val title: String,
+
         @SerializedName("Description")
         val description: String,
+
         @SerializedName("Format")
         val format: String,
+
         @SerializedName("TopEntry")
         val topEntry: TopEntry,
+
+        @SerializedName("Author")
+        val author: String,
+
+        @SerializedName("AuthorULID")
+        val authorUlid: String
     )
 
     data class TopEntry(
         @SerializedName("User")
         val user: String,
+
+        @SerializedName("ULID")
+        val ulid: String,
+
         @SerializedName("Score")
         val score: Long,
+
         @SerializedName("FormattedScore")
         val formattedScore: String,
     )

src/main/kotlin/org/retroachivements/api/data/pojo/game/GetGameProgression.kt

@@ -0,0 +1,99 @@
+package org.retroachivements.api.data.pojo.game
+
+import com.google.gson.annotations.SerializedName
+
+class GetGameProgression {
+
+    data class Response(
+
+        @SerializedName("ID")
+        val id: Int,
+
+        @SerializedName("Title")
+        val title: String,
+
+        @SerializedName("ConsoleID")
+        val consoleId: Int,
+
+        @SerializedName("ConsoleName")
+        val consoleName: String,
+
+        @SerializedName("ImageIcon")
+        val imageIcon: String,
+
+        @SerializedName("NumDistinctPlayers")
+        val numDistinctPlayers: Int,
+
+        @SerializedName("TimesUsedInBeatMedian")
+        val timesUsedInBeatMedian: Int,
+
+        @SerializedName("TimesUsedInHardcoreBeatMedian")
+        val timesUsedInHardcoreBeatMedia: Int,
+
+        @SerializedName("MedianTimeToBeat")
+        val medianTimeToBeat: Int,
+
+        @SerializedName("MedianTimeToBeatHardcore")
+        val medianTimeToBeatHardcore: Int,
+
+        @SerializedName("TimesUsedInCompletionMedian")
+        val timesUsedInCompletionMedian: Int,
+
+        @SerializedName("TimesUsedInMasteryMedian")
+        val timesUsedInMasteryMedian: Int,
+
+        @SerializedName("MedianTimeToComplete")
+        val mediaTimeToComplete: Int,
+
+        @SerializedName("MedianTimeToMaster")
+        val medianTimeToMaster: Int,
+
+        @SerializedName("NumAchievements")
+        val numAchievements: Int,
+
+        @SerializedName("Achievements")
+        val achievements: List<Achievement>
+    ) {
+        data class Achievement(
+
+            @SerializedName("ID")
+            val id: Int,
+
+            @SerializedName("Title")
+            val title: String,
+
+            @SerializedName("Description")
+            val description: String,
+
+            @SerializedName("Points")
+            val points: Int,
+
+            @SerializedName("TrueRatio")
+            val trueRatio: Int,
+
+            @SerializedName("Type")
+            val type: String?,
+
+            @SerializedName("BadgeName")
+            val badgeName: String,
+
+            @SerializedName("NumAwarded")
+            val numAwarded: Int,
+
+            @SerializedName("NumAwardedHardcore")
+            val numAwardedHardcore: Int,
+
+            @SerializedName("TimesUsedInUnlockMedian")
+            val timesUsedInUnlockMedian: Int,
+
+            @SerializedName("TimesUsedInHardcoreUnlockMedian")
+            val timesUsedInHardcoreUnlockMedian: Int,
+
+            @SerializedName("MedianTimeToUnlock")
+            val medianTimeToUnlock: Int,
+
+            @SerializedName("MedianTimeToUnlockHardcore")
+            val medianTimeToUnlockHardcore: Int
+        )
+    }
+}

src/main/kotlin/org/retroachivements/api/data/pojo/game/GetUserGameLeaderboard.kt

@@ -0,0 +1,60 @@
+package org.retroachivements.api.data.pojo.game
+
+import com.google.gson.annotations.SerializedName
+
+class GetUserGameLeaderboard {
+
+    data class Response(
+
+        @SerializedName("Count")
+        val count: Int,
+
+        @SerializedName("Total")
+        val total: Int,
+
+        @SerializedName("Results")
+        val results: List<Result>
+    ) {
+        data class Result(
+
+            @SerializedName("ID")
+            val id: Int,
+
+            @SerializedName("RankAsc")
+            val rankAsc: Boolean,
+
+            @SerializedName("Title")
+            val title: String,
+
+            @SerializedName("Description")
+            val description: String,
+
+            @SerializedName("Format")
+            val format: String,
+
+            @SerializedName("UserEntry")
+            val userEntry: UserEntry
+        ) {
+            data class UserEntry(
+
+                @SerializedName("User")
+                val user: String,
+
+                @SerializedName("ULID")
+                val ulid: String,
+
+                @SerializedName("Score")
+                val score: Int,
+
+                @SerializedName("FormattedScore")
+                val formattedScore: String,
+
+                @SerializedName("Rank")
+                val rank: Int,
+
+                @SerializedName("DateUpdated")
+                val dateUpdated: String
+            )
+        }
+    }
+}