feat: add getUserAwards function

README.md

@@ -79,6 +79,7 @@ Click the function names to open their complete docs on the docs site.
 - [`getAchievementsEarnedBetween()`](https://retroachievements-api-js.vercel.app/v1/users/get-achievements-earned-between.html) - Get a list of achievements earned by a user between two dates.
 - [`getAchievementsEarnedOnDay()`](https://retroachievements-api-js.vercel.app/v1/users/get-achievements-earned-on-day.html) - Get a list of achievements earned by a user on a given date.
 - [`getGameInfoAndUserProgress()`](https://retroachievements-api-js.vercel.app/v1/users/get-game-info-and-user-progress.html) - Get metadata about a game as well as a user's progress on that game.
+- [`getUserAwards()`](https://retroachievements-api-js.vercel.app/v1/users/get-user-awards.html) - Get a list of a user's site awards/badges.
 - [`getUserClaims()`](https://retroachievements-api-js.vercel.app/v1/users/get-user-claims.html) - Get a list of set claims made over the lifetime of a user.
 - [`getUserCompletedGames()`](https://retroachievements-api-js.vercel.app/v1/users/get-user-completed-games.html) - Get hardcore and softcore completion metadata about games a user has played.
 - [`getUserGameRankAndScore()`](https://retroachievements-api-js.vercel.app/v1/users/get-user-game-rank-and-score.html) - Get metadata about how a user has performed on a given game.

docs/.vitepress/config.js

@@ -61,6 +61,10 @@ export default {
  text: "Users",
  collapsible: true,
  items: [
+ {
+ text: "Recent Achievements",
+ link: "/v1/users/get-user-recent-achievements"
+ },
  {
  text: "Achievements Earned Between Days",
  link: "/v1/users/get-achievements-earned-between"
@@ -73,6 +77,10 @@ export default {
  text: "Progress for Game with Game Info",
  link: "/v1/users/get-game-info-and-user-progress"
  },
+ {
+ text: "Awards / Badges",
+ link: "/v1/users/get-user-awards"
+ },
  {
  text: "Set Claims",
  link: "/v1/users/get-user-claims"

docs/v1/users/get-user-awards.md

@@ -0,0 +1,49 @@
+# getUserAwards
+
+A call to this function will retrieve metadata about the target user's site awards, via their username.
+
+## Examples
+
+```ts
+import { getUserAwards } from "@retroachievements/api";
+
+const userAwards = await getUserAwards(authorization, { userName: "xelnia" });
+```
+
+## Returns
+
+```json
+{
+ "totalAwardsCount": 10,
+ "hiddenAwardsCount": 2,
+ "masteryAwardsCount": 6,
+ "completionAwardsCount": 0,
+ "eventAwardsCount": 0,
+ "siteAwardsCount": 2,
+ "visibleUserAwards": [
+ {
+ "awardedAt": "2022-08-26T19:34:43+00:00",
+ "awardType": "Mastery/Completion",
+ "awardData": 802,
+ "awardDataExtra": 1,
+ "displayOrder": 114,
+ "title": "WarioWare, Inc.: Mega Microgames!",
+ "consoleName": "Game Boy Advance",
+ "flags": null,
+ "imageIcon": "/Images/034678.png"
+ }
+ ]
+}
+```
+
+## Parameters
+
+| Name | Type | Description |
+| :-------------- | :------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------- |
+| `authorization` | [`AuthObject`](/v1/data-models/auth-object) | An object that must contain a `userName` and a `webApiKey`. See [this page](/getting-started) for how to create this object. |
+| `userName` | `string` | The user for which to retrieve the site awards for. |
+
+## Source
+
+[@retroachievements/api, getUserAwards.ts](https://github.dev/RetroAchievements/retroachievements-api-js/blob/main/src/user/getUserAwards.ts) 
+[RAWeb, API_GetUserAwards.php](https://github.dev/RetroAchievements/RAWeb/blob/master/public/API/API_GetUserAwards.php)

docs/v1/users/get-user-recent-achievements.md

@@ -51,7 +51,7 @@ const userRecentAchievements = await getUserRecentAchievements(authorization, {
 | Name | Type | Description |
 | :-------------- | :------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------- |
 | `authorization` | [`AuthObject`](/v1/data-models/auth-object) | An object that must contain a `userName` and a `webApiKey`. See [this page](/getting-started) for how to create this object. |
-| `userName` | `string` | The user for which to retrieve the recently played games for.  |
+| `userName` | `string` | The user for which to retrieve the recently earned achievements for. |
 | `recentMinutes` | `number?` | Optional. Defaults to 60. How many minutes back to fetch for the given user. |
 
 ## Source

src/user/getUserAwards.test.ts

@@ -0,0 +1,83 @@
+import { rest } from "msw";
+import { setupServer } from "msw/node";
+
+import { apiBaseUrl } from "../utils/internal";
+import { buildAuthorization } from "../utils/public";
+import { getUserAwards } from "./getUserAwards";
+import type { GetUserAwardsResponse } from "./models";
+
+const server = setupServer();
+
+describe("Function: getUserAwards", () => {
+ // MSW Setup
+ beforeAll(() => server.listen());
+ afterEach(() => server.resetHandlers());
+ afterAll(() => server.close());
+
+ it("is defined #sanity", () => {
+ // ASSERT
+ expect(getUserAwards).toBeDefined();
+ });
+
+ it("retrieves a list of a target user awards", async () => {
+ // ARRANGE
+ const authorization = buildAuthorization({
+ userName: "mockUserName",
+ webApiKey: "mockWebApiKey"
+ });
+
+ const mockResponse: GetUserAwardsResponse = {
+ TotalAwardsCount: 10,
+ HiddenAwardsCount: 5,
+ MasteryAwardsCount: 5,
+ CompletionAwardsCount: 0,
+ EventAwardsCount: 0,
+ SiteAwardsCount: 0,
+ VisibleUserAwards: [
+ {
+ AwardedAt: "2022-08-26T19:34:43+00:00",
+ AwardType: "Mastery/Completion",
+ AwardData: 802,
+ AwardDataExtra: 1,
+ DisplayOrder: 114,
+ Title: "WarioWare, Inc.: Mega Microgames!",
+ ConsoleName: "Game Boy Advance",
+ Flags: null,
+ ImageIcon: "/Images/034678.png"
+ }
+ ]
+ };
+
+ server.use(
+ rest.get(`${apiBaseUrl}/API_GetUserAwards.php`, (_, res, ctx) =>
+ res(ctx.json(mockResponse))
+ )
+ );
+
+ // ACT
+ const response = await getUserAwards(authorization, { userName: "xelnia" });
+
+ // ASSERT
+ expect(response).toEqual({
+ totalAwardsCount: 10,
+ hiddenAwardsCount: 5,
+ masteryAwardsCount: 5,
+ completionAwardsCount: 0,
+ eventAwardsCount: 0,
+ siteAwardsCount: 0,
+ visibleUserAwards: [
+ {
+ awardedAt: "2022-08-26T19:34:43+00:00",
+ awardType: "Mastery/Completion",
+ awardData: 802,
+ awardDataExtra: 1,
+ displayOrder: 114,
+ title: "WarioWare, Inc.: Mega Microgames!",
+ consoleName: "Game Boy Advance",
+ flags: null,
+ imageIcon: "/Images/034678.png"
+ }
+ ]
+ });
+ });
+});

src/user/getUserAwards.ts

@@ -0,0 +1,70 @@
+import {
+ apiBaseUrl,
+ buildRequestUrl,
+ call,
+ serializeProperties
+} from "../utils/internal";
+import type { AuthObject } from "../utils/public";
+import type { GetUserAwardsResponse, UserAwards } from "./models";
+
+/**
+ * A call to this function will retrieve metadata about the target user's
+ * site awards, via their username.
+ *
+ * @param authorization An object containing your userName and webApiKey.
+ * This can be constructed with `buildAuthorization()`.
+ *
+ * @param payload.userName The user for which to retrieve the site awards for.
+ *
+ * @example
+ * ```
+ * const userAwards = await getUserAwards(
+ * authorization,
+ * { userName: "xelnia" }
+ * )
+ * ```
+ *
+ * @returns
+ * ```json
+ * {
+ * totalAwardsCount: 10,
+ * hiddenAwardsCount: 2,
+ * masteryAwardsCount: 6,
+ * completionAwardsCount: 0,
+ * eventAwardsCount: 0,
+ * siteAwardsCount: 2,
+ * visibleUserAwards: [
+ * {
+ * awardedAt: "2022-08-26T19:34:43+00:00",
+ * awardType: "Mastery/Completion",
+ * awardData: 802,
+ * awardDataExtra: 1,
+ * displayOrder: 114,
+ * title: "WarioWare, Inc.: Mega Microgames!",
+ * consoleName: "Game Boy Advance",
+ * flags: null,
+ * imageIcon: "/Images/034678.png"
+ * }
+ * ]
+ * }
+ * ```
+ */
+export const getUserAwards = async (
+ authorization: AuthObject,
+ payload: { userName: string }
+): Promise<UserAwards> => {
+ const { userName } = payload;
+
+ const queryParams: Record<string, string> = { u: userName };
+
+ const url = buildRequestUrl(
+ apiBaseUrl,
+ "/API_GetUserAwards.php",
+ authorization,
+ queryParams
+ );
+
+ const rawResponse = await call<GetUserAwardsResponse>({ url });
+
+ return serializeProperties(rawResponse);
+};

src/user/getUserRecentAchievements.ts

@@ -18,7 +18,7 @@ import type {
  * @param authorization An object containing your userName and webApiKey.
  * This can be constructed with `buildAuthorization()`.
  *
- * @param payload.userName The user for which to retrieve the summary for.
+ * @param payload.userName The user for which to retrieve the recent achievements for.
  *
  * @param payload.recentMinutes Optional. Defaults to 60. How many minutes
  * back to fetch for the given user.

src/user/index.ts

@@ -1,6 +1,7 @@
 export * from "./getAchievementsEarnedBetween";
 export * from "./getAchievementsEarnedOnDay";
 export * from "./getGameInfoAndUserProgress";
+export * from "./getUserAwards";
 export * from "./getUserClaims";
 export * from "./getUserCompletedGames";
 export * from "./getUserGameRankAndScore";

src/user/models/award-type.model.ts

@@ -0,0 +1,7 @@
+export type AwardType =
+ | "Mastery/Completion"
+ | "Achievement Unlocks Yield"
+ | "Achievement Points Yield"
+ | "Patreon Supporter"
+ | "Certified Legend"
+ | "Invalid or deprecated award type";

src/user/models/get-user-awards-response.model.ts

@@ -0,0 +1,23 @@
+import type { AwardType } from "./award-type.model";
+
+interface GetUserAwardsEntity {
+ AwardedAt: string;
+ AwardType: AwardType;
+ AwardData: number;
+ AwardDataExtra: number;
+ DisplayOrder: number;
+ Title: string;
+ ConsoleName: string;
+ Flags: number | null;
+ ImageIcon: string;
+}
+
+export interface GetUserAwardsResponse {
+ TotalAwardsCount: number;
+ HiddenAwardsCount: number;
+ MasteryAwardsCount: number;
+ CompletionAwardsCount: number;
+ EventAwardsCount: number;
+ SiteAwardsCount: number;
+ VisibleUserAwards: GetUserAwardsEntity[];
+}

src/user/models/index.ts

@@ -1,14 +1,17 @@
+export * from "./award-type.model";
 export * from "./dated-user-achievement.model";
 export * from "./dated-user-achievements-response.model";
 export * from "./game-info-and-user-progress.model";
 export * from "./get-game-info-and-user-progress-response.model";
+export * from "./get-user-awards-response.model";
 export * from "./get-user-completed-games-response.model";
 export * from "./get-user-game-rank-and-score-response.model";
 export * from "./get-user-points-response.model";
 export * from "./get-user-progress-response.model";
 export * from "./get-user-recent-achievements-response.model";
 export * from "./get-user-recently-played-games-response.model";
 export * from "./get-user-summary-response.model";
+export * from "./user-awards.model";
 export * from "./user-claims.model";
 export * from "./user-claims-response.model";
 export * from "./user-completed-games.model";

src/user/models/user-awards.model.ts

@@ -0,0 +1,23 @@
+import type { AwardType } from "./award-type.model";
+
+interface UserAward {
+ awardedAt: string;
+ awardType: AwardType;
+ awardData: number;
+ awardDataExtra: number;
+ displayOrder: number;
+ title: string;
+ consoleName: string;
+ flags: number | null;
+ imageIcon: string;
+}
+
+export interface UserAwards {
+ totalAwardsCount: number;
+ hiddenAwardsCount: number;
+ masteryAwardsCount: number;
+ completionAwardsCount: number;
+ eventAwardsCount: number;
+ siteAwardsCount: number;
+ visibleUserAwards: UserAward[];
+}

src/utils/internal/serializeProperties.ts

@@ -71,5 +71,8 @@ const naiveCamelCase = (originalValue: string) => {
  // "rAPoints" -> "raPoints"
  camelCased = camelCased.replace(/rA/g, "ra");
 
+ // "visibleUserawards" -> "visibleUserAwards"
+ camelCased = camelCased.replace(/visibleUserawards/g, "visibleUserAwards");
+
  return camelCased;
 };