feat(getRecentGameAwards): add api-js documentation

RetroAchievements · May 24, 2024 · d5dc5b2 · d5dc5b2
1 parent d244df4
commit d5dc5b2
Show file tree

Hide file tree

Showing 34 changed files with 124 additions and 86 deletions.
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -93,10 +93,10 @@ You can now create your authorization object using your RA username & web API ke
 ```ts [NodeJS]
 import { buildAuthorization } from "@retroachievements/api";
 
-const userName = "<your username on RA>";
+const username = "<your username on RA>";
 const webApiKey = "<your web API key>";
 
-const authorization = buildAuthorization({ userName, webApiKey });
+const authorization = buildAuthorization({ username, webApiKey });
 ```
 
 ```kotlin [Kotlin]

diff --git a/docs/v1/get-achievement-count.md b/docs/v1/get-achievement-count.md
@@ -37,10 +37,10 @@ import {
 } from "@retroachievements/api";
 
 // First, build your authorization object.
-const userName = "<your username on RA>";
+const username = "<your username on RA>";
 const webApiKey = "<your web API key>";
 
-const authorization = buildAuthorization({ userName, webApiKey });
+const authorization = buildAuthorization({ username, webApiKey });
 
 // Then, make the API call.
 const achievementCount = await getAchievementCount(authorization, {

diff --git a/docs/v1/get-achievement-distribution.md b/docs/v1/get-achievement-distribution.md
@@ -39,10 +39,10 @@ import {
 } from "@retroachievements/api";
 
 // First, build your authorization object.
-const userName = "<your username on RA>";
+const username = "<your username on RA>";
 const webApiKey = "<your web API key>";
 
-const authorization = buildAuthorization({ userName, webApiKey });
+const authorization = buildAuthorization({ username, webApiKey });
 
 // Then, make the API call.
 const achievementDistribution = await getAchievementDistribution(

diff --git a/docs/v1/get-achievement-of-the-week.md b/docs/v1/get-achievement-of-the-week.md
@@ -36,10 +36,10 @@ import {
 } from "@retroachievements/api";
 
 // First, build your authorization object.
-const userName = "<your username on RA>";
+const username = "<your username on RA>";
 const webApiKey = "<your web API key>";
 
-const authorization = buildAuthorization({ userName, webApiKey });
+const authorization = buildAuthorization({ username, webApiKey });
 
 // Then, make the API call.
 const achievementOfTheWeek = await getAchievementOfTheWeek(authorization);

diff --git a/docs/v1/get-achievement-unlocks.md b/docs/v1/get-achievement-unlocks.md
@@ -33,10 +33,10 @@ import {
 } from "@retroachievements/api";
 
 // First, build your authorization object.
-const userName = "<your username on RA>";
+const username = "<your username on RA>";
 const webApiKey = "<your web API key>";
 
-const authorization = buildAuthorization({ userName, webApiKey });
+const authorization = buildAuthorization({ username, webApiKey });
 
 // Then, make the API call.
 const achievementUnlocks = await getAchievementUnlocks(authorization, {

diff --git a/docs/v1/get-achievements-earned-between.md b/docs/v1/get-achievements-earned-between.md
@@ -39,14 +39,14 @@ import {
 } from "@retroachievements/api";
 
 // First, build your authorization object.
-const userName = "<your username on RA>";
+const username = "<your username on RA>";
 const webApiKey = "<your web API key>";
 
-const authorization = buildAuthorization({ userName, webApiKey });
+const authorization = buildAuthorization({ username, webApiKey });
 
 // Then, make the API call.
 const achievements = await getAchievementsEarnedBetween(authorization, {
-  userName: "Jamiras",
+  username: "Jamiras",
   fromDate: new Date("2022-01-01"),
   toDate: new Date("2022-01-08"),
 });

diff --git a/docs/v1/get-achievements-earned-on-day.md b/docs/v1/get-achievements-earned-on-day.md
@@ -38,14 +38,14 @@ import {
 } from "@retroachievements/api";
 
 // First, build your authorization object.
-const userName = "<your username on RA>";
+const username = "<your username on RA>";
 const webApiKey = "<your web API key>";
 
-const authorization = buildAuthorization({ userName, webApiKey });
+const authorization = buildAuthorization({ username, webApiKey });
 
 // Then, make the API call.
 const achievements = await getAchievementsEarnedOnDay(authorization, {
-  userName: "MaxMilyin",
+  username: "MaxMilyin",
   onDate: new Date("2022-10-14"),
 });
 ```

diff --git a/docs/v1/get-active-claims.md b/docs/v1/get-active-claims.md
@@ -27,10 +27,10 @@ A call to this endpoint returns information about all (1000 max) active set clai
 import { buildAuthorization, getActiveClaims } from "@retroachievements/api";
 
 // First, build your authorization object.
-const userName = "<your username on RA>";
+const username = "<your username on RA>";
 const webApiKey = "<your web API key>";
 
-const authorization = buildAuthorization({ userName, webApiKey });
+const authorization = buildAuthorization({ username, webApiKey });
 
 // Then, make the API call.
 const activeClaims = await getActiveClaims(authorization);

diff --git a/docs/v1/get-claims.md b/docs/v1/get-claims.md
@@ -28,10 +28,10 @@ A call to this endpoint returns information about all (1000 max) achievement set
 import { buildAuthorization, getClaims } from "@retroachievements/api";
 
 // First, build your authorization object.
-const userName = "<your username on RA>";
+const username = "<your username on RA>";
 const webApiKey = "<your web API key>";
 
-const authorization = buildAuthorization({ userName, webApiKey });
+const authorization = buildAuthorization({ username, webApiKey });
 
 // Then, make the API call.
 const claims = await getClaims(authorization, { claimKind: "completed" });

diff --git a/docs/v1/get-console-ids.md b/docs/v1/get-console-ids.md
@@ -35,10 +35,10 @@ The systems list can be found by selecting the "Games" menu from the site navbar
 import { buildAuthorization, getConsoleIds } from "@retroachievements/api";
 
 // First, build your authorization object.
-const userName = "<your username on RA>";
+const username = "<your username on RA>";
 const webApiKey = "<your web API key>";
 
-const authorization = buildAuthorization({ userName, webApiKey });
+const authorization = buildAuthorization({ username, webApiKey });
 
 // Then, make the API call.
 const consoleIds = await getConsoleIds(authorization);

diff --git a/docs/v1/get-game-extended.md b/docs/v1/get-game-extended.md
@@ -35,10 +35,10 @@ Most of this data can be found on the game page, for example, [Sonic the Hedgeho
 import { buildAuthorization, getGameExtended } from "@retroachievements/api";
 
 // First, build your authorization object.
-const userName = "<your username on RA>";
+const username = "<your username on RA>";
 const webApiKey = "<your web API key>";
 
-const authorization = buildAuthorization({ userName, webApiKey });
+const authorization = buildAuthorization({ username, webApiKey });
 
 // Then, make the API call.
 const gameExtended = await getGameExtended(authorization, {

diff --git a/docs/v1/get-game-info-and-user-progress.md b/docs/v1/get-game-info-and-user-progress.md
@@ -33,16 +33,16 @@ import {
 } from "@retroachievements/api";
 
 // First, build your authorization object.
-const userName = "<your username on RA>";
+const username = "<your username on RA>";
 const webApiKey = "<your web API key>";
 
-const authorization = buildAuthorization({ userName, webApiKey });
+const authorization = buildAuthorization({ username, webApiKey });
 
 // Then, make the API call.
 const gameInfoAndUserProgress = await getGameInfoAndUserProgress(
   authorization,
   {
-    userName: "MaxMilyin",
+    username: "MaxMilyin",
     gameId: 14402,
   },
 );

diff --git a/docs/v1/get-game-list.md b/docs/v1/get-game-list.md
@@ -40,10 +40,10 @@ The system games list can be found by selecting any system in the "Games" menu f
 import { buildAuthorization, getGameList } from "@retroachievements/api";
 
 // First, build your authorization object.
-const userName = "<your username on RA>";
+const username = "<your username on RA>";
 const webApiKey = "<your web API key>";
 
-const authorization = buildAuthorization({ userName, webApiKey });
+const authorization = buildAuthorization({ username, webApiKey });
 
 // Then, make the API call.
 const gameList = await getGameList(authorization, {

diff --git a/docs/v1/get-game-rank-and-score.md b/docs/v1/get-game-rank-and-score.md
@@ -38,10 +38,10 @@ import {
 } from "@retroachievements/api";
 
 // First, build your authorization object.
-const userName = "<your username on RA>";
+const username = "<your username on RA>";
 const webApiKey = "<your web API key>";
 
-const authorization = buildAuthorization({ userName, webApiKey });
+const authorization = buildAuthorization({ username, webApiKey });
 
 // Then, make the API call.
 const gameRankAndScore = await getGameRankAndScore(authorization, {

diff --git a/docs/v1/get-game.md b/docs/v1/get-game.md
@@ -34,10 +34,10 @@ Most of this data can be found on the game page, for example, [Sonic the Hedgeho
 import { buildAuthorization, getGame } from "@retroachievements/api";
 
 // First, build your authorization object.
-const userName = "<your username on RA>";
+const username = "<your username on RA>";
 const webApiKey = "<your web API key>";
 
-const authorization = buildAuthorization({ userName, webApiKey });
+const authorization = buildAuthorization({ username, webApiKey });
 
 // Then, make the API call.
 const game = await getGame(authorization, {

diff --git a/docs/v1/get-recent-game-awards.md b/docs/v1/get-recent-game-awards.md
@@ -31,7 +31,25 @@ This data can be found on the Recent Game Awards page, for example:
 
 ## Client Library
 
-Not yet supported.
+::: code-group
+
+```ts [NodeJS]
+import {
+  buildAuthorization,
+  getRecentGameAwards,
+} from "@retroachievements/api";
+
+// First, build your authorization object.
+const username = "<your username on RA>";
+const webApiKey = "<your web API key>";
+
+const authorization = buildAuthorization({ username, webApiKey });
+
+// Then, make the API call.
+const game = await getRecentGameAwards(authorization);
+```
+
+:::
 
 ## Response
 
@@ -56,10 +74,30 @@ Not yet supported.
 }
 ```
 
+```json [NodeJS]
+{
+  "count": 25,
+  "total": 452857,
+  "results": [
+    {
+      "user": "renanbrj",
+      "awardKind": "mastered",
+      "awardDate": "2022-01-01T23:48:04+00:00",
+      "gameId": 14_284,
+      "gameTitle": "Batman Returns",
+      "consoleId": 15,
+      "consoleName": "Game Gear"
+    }
+    // ...
+  ]
+}
+```
+
 :::
 
 ## Source
 
-| Repo  | URL                                                                                           |
-| :---- | :-------------------------------------------------------------------------------------------- |
-| RAWeb | https://github.com/RetroAchievements/RAWeb/blob/master/public/API/API_GetRecentGameAwards.php |
+| Repo   | URL                                                                                           |
+| :----- | :-------------------------------------------------------------------------------------------- |
+| RAWeb  | https://github.com/RetroAchievements/RAWeb/blob/master/public/API/API_GetRecentGameAwards.php |
+| api-js | https://github.com/RetroAchievements/api-js/blob/main/src/feed/getRecentGameAwards.ts         |
diff --git a/docs/v1/get-ticket-data/get-achievement-ticket-stats.md b/docs/v1/get-ticket-data/get-achievement-ticket-stats.md
@@ -28,10 +28,10 @@ A call to `API_GetTicketData` in this manner will retrieve ticket stats for an a
 import { buildAuthorization, getTicketData } from "@retroachievements/api";
 
 // First, build your authorization object.
-const userName = "<your username on RA>";
+const username = "<your username on RA>";
 const webApiKey = "<your web API key>";
 
-const authorization = buildAuthorization({ userName, webApiKey });
+const authorization = buildAuthorization({ username, webApiKey });
 
 // Then, make the API call.
 const achievementTicketStats = await getTicketData(authorization, {

diff --git a/docs/v1/get-ticket-data/get-developer-ticket-stats.md b/docs/v1/get-ticket-data/get-developer-ticket-stats.md
@@ -28,14 +28,14 @@ A call to `API_GetTicketData` in this manner will retrieve ticket stats for a de
 import { buildAuthorization, getTicketData } from "@retroachievements/api";
 
 // First, build your authorization object.
-const userName = "<your username on RA>";
+const username = "<your username on RA>";
 const webApiKey = "<your web API key>";
 
-const authorization = buildAuthorization({ userName, webApiKey });
+const authorization = buildAuthorization({ username, webApiKey });
 
 // Then, make the API call.
 const developerTicketStats = await getTicketData(authorization, {
-  userName: "Hexadigital",
+  username: "Hexadigital",
 });
 ```
 

diff --git a/docs/v1/get-ticket-data/get-game-ticket-stats.md b/docs/v1/get-ticket-data/get-game-ticket-stats.md
@@ -30,10 +30,10 @@ A call to `API_GetTicketData` in this manner will retrieve ticket stats for a ga
 import { buildAuthorization, getTicketData } from "@retroachievements/api";
 
 // First, build your authorization object.
-const userName = "<your username on RA>";
+const username = "<your username on RA>";
 const webApiKey = "<your web API key>";
 
-const authorization = buildAuthorization({ userName, webApiKey });
+const authorization = buildAuthorization({ username, webApiKey });
 
 // Then, make the API call.
 const gameTicketStats = await getTicketData(authorization, { gameId: 1 });

diff --git a/docs/v1/get-ticket-data/get-most-recent-tickets.md b/docs/v1/get-ticket-data/get-most-recent-tickets.md
@@ -29,10 +29,10 @@ A call to `API_GetTicketData` in this manner will retrieve ticket metadata infor
 import { buildAuthorization, getTicketData } from "@retroachievements/api";
 
 // First, build your authorization object.
-const userName = "<your username on RA>";
+const username = "<your username on RA>";
 const webApiKey = "<your web API key>";
 
-const authorization = buildAuthorization({ userName, webApiKey });
+const authorization = buildAuthorization({ username, webApiKey });
 
 // Then, make the API call.
 const mostRecentTickets = await getTicketData(authorization, {

diff --git a/docs/v1/get-ticket-data/get-most-ticketed-games.md b/docs/v1/get-ticket-data/get-most-ticketed-games.md
@@ -30,10 +30,10 @@ A call to `API_GetTicketData` in this manner will retrieve the games on the site
 import { buildAuthorization, getTicketData } from "@retroachievements/api";
 
 // First, build your authorization object.
-const userName = "<your username on RA>";
+const username = "<your username on RA>";
 const webApiKey = "<your web API key>";
 
-const authorization = buildAuthorization({ userName, webApiKey });
+const authorization = buildAuthorization({ username, webApiKey });
 
 // Then, make the API call.
 const ticket = await getTicketData(authorization, {

diff --git a/docs/v1/get-ticket-data/get-ticket-by-id.md b/docs/v1/get-ticket-data/get-ticket-by-id.md
@@ -28,10 +28,10 @@ A call to `API_GetTicketData` in this manner will retrieve ticket metadata infor
 import { buildAuthorization, getTicketData } from "@retroachievements/api";
 
 // First, build your authorization object.
-const userName = "<your username on RA>";
+const username = "<your username on RA>";
 const webApiKey = "<your web API key>";
 
-const authorization = buildAuthorization({ userName, webApiKey });
+const authorization = buildAuthorization({ username, webApiKey });
 
 // Then, make the API call.
 const ticket = await getTicketData(authorization, { ticketId: 12345 });

diff --git a/docs/v1/get-top-ten-users.md b/docs/v1/get-top-ten-users.md
@@ -27,10 +27,10 @@ A call to this endpoint will retrieve the current top ten users, ranked by hardc
 import { buildAuthorization, getTopTenUsers } from "@retroachievements/api";
 
 // First, build your authorization object.
-const userName = "<your username on RA>";
+const username = "<your username on RA>";
 const webApiKey = "<your web API key>";
 
-const authorization = buildAuthorization({ userName, webApiKey });
+const authorization = buildAuthorization({ username, webApiKey });
 
 // Then, make the API call.
 const topTenUsers = await getTopTenUsers(authorization);
@@ -75,7 +75,7 @@ if (response is NetworkResponse.Success) {
 ```json [NodeJS]
 [
   {
-    "userName": "MaxMilyin",
+    "username": "MaxMilyin",
     "totalPoints": 399597,
     "totalRatioPoints": 1599212
   }

diff --git a/docs/v1/get-user-awards.md b/docs/v1/get-user-awards.md
@@ -34,13 +34,13 @@ The easiest place to see a summary of user awards in the Progression Status comp
 import { buildAuthorization, getUserAwards } from "@retroachievements/api";
 
 // First, build your authorization object.
-const userName = "<your username on RA>";
+const username = "<your username on RA>";
 const webApiKey = "<your web API key>";
 
-const authorization = buildAuthorization({ userName, webApiKey });
+const authorization = buildAuthorization({ username, webApiKey });
 
 // Then, make the API call.
-const userAwards = await getUserAwards(authorization, { userName: "xelnia" });
+const userAwards = await getUserAwards(authorization, { username: "xelnia" });
 ```
 
 ```kotlin [Kotlin]