@retroachievements/api 1.1.1 → 1.2.1

package/dist/user/models/user-awards.model.d.ts

@@ -0,0 +1,22 @@
+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[];
+}
+export {};

package/dist/user/models/user-recent-achievement.model.d.ts

@@ -0,0 +1,16 @@
+export interface UserRecentAchievement {
+    date: string;
+    hardcoreMode: boolean;
+    achievementId: number;
+    title: string;
+    description: string;
+    badgeName: string;
+    points: number;
+    author: string;
+    gameTitle: string;
+    gameIcon: string;
+    gameId: number;
+    consoleName: string;
+    badgeUrl: string;
+    gameUrl: string;
+}

package/package.json

@@ -10,7 +10,7 @@
     "raweb",
     "retro gaming"
   ],
-  "version": "1.1.1",
+  "version": "1.2.1",
   "typings": "dist/index.d.ts",
   "exports": {
     ".": {

package/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"
+        }
+      ]
+    });
+  });
+});

package/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);
+};

package/src/user/getUserRecentAchievements.test.ts

@@ -0,0 +1,82 @@
+import { rest } from "msw";
+import { setupServer } from "msw/node";
+
+import { apiBaseUrl } from "../utils/internal";
+import { buildAuthorization } from "../utils/public";
+import { getUserRecentAchievements } from "./getUserRecentAchievements";
+import type { GetUserRecentAchievementsResponse } from "./models";
+
+const server = setupServer();
+
+describe("Function: getUserRecentAchievements", () => {
+  // MSW Setup
+  beforeAll(() => server.listen());
+  afterEach(() => server.resetHandlers());
+  afterAll(() => server.close());
+
+  it("is defined #sanity", () => {
+    // ASSERT
+    expect(getUserRecentAchievements).toBeDefined();
+  });
+
+  it("retrieves a list of recently-earned user achievements", async () => {
+    // ARRANGE
+    const authorization = buildAuthorization({
+      userName: "mockUserName",
+      webApiKey: "mockWebApiKey"
+    });
+
+    const mockResponse: GetUserRecentAchievementsResponse = [
+      {
+        Date: "2023-05-23 22:32:24",
+        HardcoreMode: 1,
+        AchievementID: 51_214,
+        Title: "You're a special Champ!",
+        Description:
+          "Win the Tournament as [You] on Hard with 1 attribute on max. and 1 attribute on min.",
+        BadgeName: "121991",
+        Points: 25,
+        Author: "Som1",
+        GameTitle: "WWF King of the Ring",
+        GameIcon: "/Images/062599.png",
+        GameID: 6316,
+        ConsoleName: "Game Boy",
+        BadgeURL: "/Badge/121991.png",
+        GameURL: "/game/6316"
+      }
+    ];
+
+    server.use(
+      rest.get(
+        `${apiBaseUrl}/API_GetUserRecentAchievements.php`,
+        (_, res, ctx) => res(ctx.json(mockResponse))
+      )
+    );
+
+    // ACT
+    const response = await getUserRecentAchievements(authorization, {
+      userName: "xelnia"
+    });
+
+    // ASSERT
+    expect(response).toEqual([
+      {
+        date: "2023-05-23 22:32:24",
+        hardcoreMode: true,
+        achievementId: 51_214,
+        title: "You're a special Champ!",
+        description:
+          "Win the Tournament as [You] on Hard with 1 attribute on max. and 1 attribute on min.",
+        badgeName: "121991",
+        points: 25,
+        author: "Som1",
+        gameTitle: "WWF King of the Ring",
+        gameIcon: "/Images/062599.png",
+        gameId: 6316,
+        consoleName: "Game Boy",
+        badgeUrl: "/Badge/121991.png",
+        gameUrl: "/game/6316"
+      }
+    ]);
+  });
+});

package/src/user/getUserRecentAchievements.ts

@@ -0,0 +1,80 @@
+import {
+  apiBaseUrl,
+  buildRequestUrl,
+  call,
+  serializeProperties
+} from "../utils/internal";
+import type { AuthObject } from "../utils/public";
+import type {
+  GetUserRecentAchievementsResponse,
+  UserRecentAchievement
+} from "./models";
+
+/**
+ * A call to this function will retrieve a list of a target user's
+ * recently earned achievements, via their username. By default, it
+ * fetches achievements earned in the last hour.
+ *
+ * @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 recent achievements for.
+ *
+ * @param payload.recentMinutes Optional. Defaults to 60. How many minutes
+ * back to fetch for the given user.
+ *
+ * @example
+ * ```
+ * const userRecentAchievements = await getUserRecentAchievements(
+ *   authorization,
+ *   { userName: "xelnia" }
+ * );
+ * ```
+ *
+ * @returns An array containing metadata about a user's recently earned achievements.
+ * ```json
+ * [
+ *   {
+ *     date: '2023-05-23 22:32:24',
+ *     hardcoreMode: true,
+ *     achievementId: 51214,
+ *     title: "You're a special Champ!",
+ *     description: 'Win the Tournament as [You] on Hard with 1 attribute on max. and 1 attribute on min.',
+ *     badgeName: '121991',
+ *     points: 25,
+ *     author: 'Som1',
+ *     gameTitle: 'WWF King of the Ring',
+ *     gameIcon: '/Images/062599.png',
+ *     gameId: 6316,
+ *     consoleName: 'Game Boy',
+ *     badgeUrl: '/Badge/121991.png',
+ *     gameUrl: '/game/6316'
+ *   }
+ * ]
+ * ```
+ */
+export const getUserRecentAchievements = async (
+  authorization: AuthObject,
+  payload: { userName: string; recentMinutes?: number }
+): Promise<UserRecentAchievement[]> => {
+  const { userName, recentMinutes } = payload;
+
+  const queryParams: Record<string, string | number> = { u: userName };
+
+  if (recentMinutes !== undefined) {
+    queryParams["m"] = recentMinutes;
+  }
+
+  const url = buildRequestUrl(
+    apiBaseUrl,
+    "/API_GetUserRecentAchievements.php",
+    authorization,
+    queryParams
+  );
+
+  const rawResponse = await call<GetUserRecentAchievementsResponse>({ url });
+
+  return serializeProperties(rawResponse, {
+    shouldMapToBooleans: ["HardcoreMode"]
+  });
+};

package/src/user/getUserSummary.test.ts

@@ -44,6 +44,27 @@ describe("Function: getUserSummary", () => {
     // ASSERT
     expect(response).toEqual(mockExpectedSummaryValue);
   });
+
+  it("given the API returns a 503, throws an error", async () => {
+    // ARRANGE
+    const authorization = buildAuthorization({
+      userName: "mockUserName",
+      webApiKey: "mockWebApiKey"
+    });
+
+    const mockResponse = "<html><body>the api is down</body></html>";
+
+    server.use(
+      rest.get(`${apiBaseUrl}/API_GetUserSummary.php`, (_, res, ctx) =>
+        res(ctx.status(503), ctx.body(mockResponse))
+      )
+    );
+
+    // ASSERT
+    await expect(
+      getUserSummary(authorization, { userName: "WCopeland" })
+    ).rejects.toThrow();
+  });
 });
 
 const mockGetUserSummaryResponse: GetUserSummaryResponse = {

package/src/user/index.ts

@@ -1,11 +1,13 @@
 export * from "./getAchievementsEarnedBetween";
 export * from "./getAchievementsEarnedOnDay";
 export * from "./getGameInfoAndUserProgress";
+export * from "./getUserAwards";
 export * from "./getUserClaims";
 export * from "./getUserCompletedGames";
 export * from "./getUserGameRankAndScore";
 export * from "./getUserPoints";
 export * from "./getUserProgress";
+export * from "./getUserRecentAchievements";
 export * from "./getUserRecentlyPlayedGames";
 export * from "./getUserSummary";
 export * from "./models";

package/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";

package/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[];
+}

package/src/user/models/get-user-recent-achievements-response.model.ts

@@ -0,0 +1,19 @@
+interface GetUserRecentAchievementsEntity {
+  Date: string;
+  HardcoreMode: 0 | 1;
+  AchievementID: number;
+  Title: string;
+  Description: string;
+  BadgeName: string;
+  Points: number;
+  Author: string;
+  GameTitle: string;
+  GameIcon: string;
+  GameID: number;
+  ConsoleName: string;
+  BadgeURL: string;
+  GameURL: string;
+}
+
+export type GetUserRecentAchievementsResponse =
+  GetUserRecentAchievementsEntity[];

package/src/user/models/index.ts

@@ -1,18 +1,23 @@
+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";
 export * from "./user-game-rank-and-score.model";
 export * from "./user-points.model";
 export * from "./user-progress.model";
+export * from "./user-recent-achievement.model";
 export * from "./user-recently-played-games.model";
 export * from "./user-summary.model";

package/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[];
+}

package/src/user/models/user-recent-achievement.model.ts

@@ -0,0 +1,16 @@
+export interface UserRecentAchievement {
+  date: string;
+  hardcoreMode: boolean;
+  achievementId: number;
+  title: string;
+  description: string;
+  badgeName: string;
+  points: number;
+  author: string;
+  gameTitle: string;
+  gameIcon: string;
+  gameId: number;
+  consoleName: string;
+  badgeUrl: string;
+  gameUrl: string;
+}

package/src/utils/internal/call.test.ts

@@ -36,4 +36,21 @@ describe("Util: call", () => {
     expect(response).toEqual({ foo: "bar" });
     expect(receivedMethod).toEqual("GET");
   });
+
+  it("given the call returns an error, throws an error", async () => {
+    // ARRANGE
+    const mockRequestUrl = "https://abc.xyz/v1/endpoint2";
+
+    server.use(
+      rest.get(mockRequestUrl, (req, res, ctx) => {
+        return res(
+          ctx.status(503),
+          ctx.text("<HTML><BODY>something bad happened</BODY></HTML>")
+        );
+      })
+    );
+
+    // ASSERT
+    await expect(call({ url: mockRequestUrl })).rejects.toThrow();
+  });
 });

package/src/utils/internal/call.ts

@@ -25,5 +25,12 @@ export const call = async <
   const { url } = config;
 
   const rawResponse = await unfetch(url);
+
+  if (!rawResponse.ok) {
+    throw new Error(
+      `HTTP Error: Status ${rawResponse.status} ${rawResponse.statusText}`
+    );
+  }
+
   return (await rawResponse.json()) as T;
 };

package/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;
 };