@retroachievements/api 0.0.0-development

package/src/feed/getTopTenUsers.test.ts

@@ -0,0 +1,101 @@
+import { rest } from "msw";
+import { setupServer } from "msw/node";
+
+import { apiBaseUrl } from "../utils/internal";
+import { buildAuthorization } from "../utils/public";
+import { getTopTenUsers } from "./getTopTenUsers";
+import type { GetTopTenUsersResponse } from "./models";
+
+const server = setupServer();
+
+describe("Function: getTopTenUsers", () => {
+  // MSW Setup
+  beforeAll(() => server.listen());
+  afterEach(() => server.resetHandlers());
+  afterAll(() => server.close());
+
+  it("is defined #sanity", () => {
+    // ASSERT
+    expect(getTopTenUsers).toBeDefined();
+  });
+
+  it("retrieves metadata about the current top ten users on the site", async () => {
+    // ARRANGE
+    const authorization = buildAuthorization({
+      userName: "mockUserName",
+      webApiKey: "mockWebApiKey"
+    });
+
+    const mockResponse: GetTopTenUsersResponse = [
+      { "1": "MaxMilyin", "2": "346289", "3": "995092" },
+      { "1": "HippopotamusRex", "2": "312118", "3": "1151351" },
+      { "1": "Sarconius", "2": "257862", "3": "1181770" },
+      { "1": "guineu", "2": "241623", "3": "672597" },
+      { "1": "Andrey199650", "2": "240101", "3": "567522" },
+      { "1": "Wendigo", "2": "227903", "3": "1099685" },
+      { "1": "donutweegee", "2": "204701", "3": "587221" },
+      { "1": "AmericanNinja", "2": "202980", "3": "567618" },
+      { "1": "Infernum", "2": "202171", "3": "689967" },
+      { "1": "FabricioPrie", "2": "196974", "3": "450436" }
+    ];
+
+    server.use(
+      rest.get(`${apiBaseUrl}/API_GetTopTenUsers.php`, (_, res, ctx) =>
+        res(ctx.json(mockResponse))
+      )
+    );
+
+    // ACT
+    const response = await getTopTenUsers(authorization);
+
+    // ASSERT
+    expect(response).toEqual([
+      {
+        userName: "MaxMilyin",
+        totalPoints: 346_289,
+        totalRatioPoints: 995_092
+      },
+      {
+        userName: "HippopotamusRex",
+        totalPoints: 312_118,
+        totalRatioPoints: 1_151_351
+      },
+      {
+        userName: "Sarconius",
+        totalPoints: 257_862,
+        totalRatioPoints: 1_181_770
+      },
+      { userName: "guineu", totalPoints: 241_623, totalRatioPoints: 672_597 },
+      {
+        userName: "Andrey199650",
+        totalPoints: 240_101,
+        totalRatioPoints: 567_522
+      },
+      {
+        userName: "Wendigo",
+        totalPoints: 227_903,
+        totalRatioPoints: 1_099_685
+      },
+      {
+        userName: "donutweegee",
+        totalPoints: 204_701,
+        totalRatioPoints: 587_221
+      },
+      {
+        userName: "AmericanNinja",
+        totalPoints: 202_980,
+        totalRatioPoints: 567_618
+      },
+      {
+        userName: "Infernum",
+        totalPoints: 202_171,
+        totalRatioPoints: 689_967
+      },
+      {
+        userName: "FabricioPrie",
+        totalPoints: 196_974,
+        totalRatioPoints: 450_436
+      }
+    ]);
+  });
+});

package/src/feed/getTopTenUsers.ts

@@ -0,0 +1,51 @@
+import { apiBaseUrl, buildRequestUrl, call } from "../utils/internal";
+import type { AuthObject } from "../utils/public";
+import type {
+  GetTopTenUsersResponse,
+  TopTenUsers,
+  TopTenUsersEntity
+} from "./models";
+
+/**
+ * A call to this function will retrieve the current top ten users
+ * on the site.
+ *
+ * @param authorization An object containing your userName and webApiKey.
+ * This can be constructed with `buildAuthorization()`.
+ *
+ * @example
+ * ```
+ * const topTenUsers = await getTopTenUsers(authorization);
+ * ```
+ *
+ * @returns An array containing the list of top ten users.
+ * ```json
+ * [
+ *   { userName: "MockUser", totalPoints: 350000, totalRatioPoints: 995000 },
+ *   { userName: "MockUser2", totalPoints: 345000, totalRatioPoints: 994000 },
+ *   ...
+ * ]
+ * ```
+ */
+export const getTopTenUsers = async (
+  authorization: AuthObject
+): Promise<TopTenUsers> => {
+  const url = buildRequestUrl(
+    apiBaseUrl,
+    "/API_GetTopTenUsers.php",
+    authorization
+  );
+
+  const rawTopTenUsers = await call<GetTopTenUsersResponse>({ url });
+
+  const sanitizedTopTenUsers: TopTenUsersEntity[] = [];
+  for (const rawUser of rawTopTenUsers) {
+    sanitizedTopTenUsers.push({
+      userName: rawUser["1"],
+      totalPoints: Number(rawUser["2"]),
+      totalRatioPoints: Number(rawUser["3"])
+    });
+  }
+
+  return sanitizedTopTenUsers;
+};

package/src/feed/index.ts

@@ -0,0 +1,5 @@
+export * from "./getAchievementOfTheWeek";
+export * from "./getActiveClaims";
+export * from "./getTicketData";
+export * from "./getTopTenUsers";
+export * from "./models";

package/src/feed/models/achievement-of-the-week.model.ts

@@ -0,0 +1,27 @@
+export interface AchievementOfTheWeek {
+  achievement: {
+    id: number;
+    title: string;
+    description: string;
+    points: number;
+    trueRatio: number;
+    author: string;
+    dateCreated: string;
+    dateModified: string;
+  };
+
+  console: { id: number; title: string };
+  forumTopic: { id: number };
+  game: { id: number; title: string };
+  startAt: string;
+  totalPlayers: number;
+
+  unlocks: Array<{
+    user: string;
+    raPoints: number;
+    dateAwarded: string;
+    hardcoreMode: boolean;
+  }>;
+
+  unlocksCount: number;
+}

package/src/feed/models/achievement-ticket-stats-response.model.ts

@@ -0,0 +1,7 @@
+export interface AchievementTicketStatsResponse {
+  AchievementID: number;
+  AchievementTitle: string;
+  AchievementDescription: string;
+  URL: string;
+  OpenTickets: number;
+}

package/src/feed/models/achievement-ticket-stats.model.ts

@@ -0,0 +1,7 @@
+export interface AchievementTicketStats {
+  achievementId: number;
+  achievementTitle: string;
+  achievementDescription: string;
+  url: string;
+  openTickets: number;
+}

package/src/feed/models/active-claim.model.ts

@@ -0,0 +1,66 @@
+export enum ClaimType {
+  Primary = 0,
+  Collaboration = 1
+}
+
+export enum ClaimSetType {
+  NewSet = 0,
+  Revision = 1
+}
+
+export enum ClaimStatus {
+  Active = 0,
+  Complete = 1,
+  Dropped = 2
+}
+
+export interface ActiveClaim {
+  /** Unique ID of the claim. */
+  id: number;
+
+  /** User who made the claim. */
+  user: string;
+
+  /** ID of the claimed game. */
+  gameId: number;
+
+  /** Title of the claimed game. */
+  gameTitle: string;
+
+  /** Site-relative path of the game's icon image. */
+  gameIcon: string;
+
+  /** Console name of the claimed game. */
+  consoleName: string;
+
+  /** Whether the claim is primary or a collaboration. */
+  claimType: ClaimType;
+
+  /** Whether the claim is for a new set or a revision. */
+  setType: ClaimSetType;
+
+  /** Whether the claim is active, complete, or dropped. */
+  status: ClaimStatus;
+
+  /** Number of times the claim has been extended. */
+  extension: number;
+
+  /** Flag indicating a special type of claim. */
+  special: number;
+
+  /** Date the claim was made. */
+  created: string;
+
+  /**
+   * Date the claim is done. This is an expiration
+   * date for active claims, completion date for complete
+   * claims, and dropped date for dropped claims.
+   */
+  doneTime: string;
+
+  /** Date the claim was updated. */
+  updated: string;
+
+  /** Time in minutes left until the claim expires. */
+  minutesLeft: number;
+}

package/src/feed/models/game-ticket-stats.model.ts

@@ -0,0 +1,11 @@
+import type { TicketEntity } from "./ticket-entity.model";
+
+export interface GameTicketStats {
+  gameId: number;
+  gameTitle: string;
+  consoleName: string;
+  openTickets: number;
+  url: string;
+
+  tickets?: TicketEntity[];
+}

package/src/feed/models/game-tickets-response.model.ts

@@ -0,0 +1,7 @@
+export interface GameTicketsResponse {
+  GameID: number;
+  GameTitle: string;
+  ConsoleName: string;
+  OpenTickets: number;
+  URL: string;
+}

package/src/feed/models/get-achievement-of-the-week-response.model.ts

@@ -0,0 +1,27 @@
+export interface GetAchievementOfTheWeekResponse {
+  Achievement: {
+    ID: string;
+    Title: string;
+    Description: string;
+    Points: string;
+    TrueRatio: string;
+    Author: string;
+    DateCreated: string;
+    DateModified: string;
+  };
+
+  Console: { ID: string; Title: string };
+  ForumTopic: { ID: string };
+  Game: { ID: string; Title: string };
+  StartAt: string;
+  TotalPlayers: string;
+
+  Unlocks: Array<{
+    User: string;
+    RAPoints: string;
+    DateAwarded: string;
+    HardcoreMode: string;
+  }>;
+
+  UnlocksCount: string;
+}

package/src/feed/models/get-active-claims-response.model.ts

@@ -0,0 +1,19 @@
+interface ActiveClaimResponseEntity {
+  ID: string;
+  User: string;
+  GameID: string;
+  GameTitle: string;
+  GameIcon: string;
+  ConsoleName: string;
+  ClaimType: string;
+  SetType: string;
+  Status: string;
+  Extension: string;
+  Special: string;
+  Created: string;
+  DoneTime: string;
+  Updated: string;
+  MinutesLeft: string;
+}
+
+export type GetActiveClaimsResponse = ActiveClaimResponseEntity[];

package/src/feed/models/get-top-ten-users-response.model.ts

@@ -0,0 +1,12 @@
+interface TopTenUsersResponseEntity {
+  /** Username */
+  "1": string;
+
+  /** Total points earned by the user */
+  "2": string;
+
+  /** Total ratio (white) points earned by the user  */
+  "3": string;
+}
+
+export type GetTopTenUsersResponse = TopTenUsersResponseEntity[];

package/src/feed/models/index.ts

@@ -0,0 +1,19 @@
+export * from "./achievement-of-the-week.model";
+export * from "./achievement-ticket-stats.model";
+export * from "./achievement-ticket-stats-response.model";
+export * from "./active-claim.model";
+export * from "./game-ticket-stats.model";
+export * from "./game-tickets-response.model";
+export * from "./get-achievement-of-the-week-response.model";
+export * from "./get-active-claims-response.model";
+export * from "./get-top-ten-users-response.model";
+export * from "./most-ticketed-games.model";
+export * from "./most-ticketed-games-response.model";
+export * from "./recent-tickets.model";
+export * from "./recent-tickets-response.model";
+export * from "./response-ticket-entity.model";
+export * from "./ticket-entity.model";
+export * from "./tickets-by-user-response.model";
+export * from "./top-ten-users.model";
+export * from "./top-ten-users-entity.model";
+export * from "./user-ticket-stats.model";

package/src/feed/models/most-ticketed-games-response.model.ts

@@ -0,0 +1,12 @@
+interface ReportedGameEntity {
+  GameID: string;
+  GameTitle: string;
+  GameIcon: string;
+  Console: string;
+  OpenTickets: string;
+}
+
+export interface MostTicketedGamesResponse {
+  MostReportedGames: ReportedGameEntity[];
+  URL: string;
+}

package/src/feed/models/most-ticketed-games.model.ts

@@ -0,0 +1,12 @@
+interface ReportedGameEntity {
+  gameId: number;
+  gameTitle: string;
+  gameIcon: string;
+  console: string;
+  openTickets: number;
+}
+
+export interface MostTicketedGames {
+  mostReportedGames: ReportedGameEntity[];
+  url: string;
+}

package/src/feed/models/recent-tickets-response.model.ts

@@ -0,0 +1,7 @@
+import type { ResponseTicketEntity } from "./response-ticket-entity.model";
+
+export interface RecentTicketsResponse {
+  RecentTickets: ResponseTicketEntity[];
+  OpenTickets: number;
+  URL: string;
+}

package/src/feed/models/recent-tickets.model.ts

@@ -0,0 +1,7 @@
+import type { TicketEntity } from "./ticket-entity.model";
+
+export interface RecentTickets {
+  recentTickets: TicketEntity[];
+  openTickets: number;
+  url: string;
+}

package/src/feed/models/response-ticket-entity.model.ts

@@ -0,0 +1,25 @@
+export interface ResponseTicketEntity {
+  ID: string;
+  AchievementID: string;
+  AchievementTitle: string;
+  AchievementDesc: string;
+  Points: string;
+  BadgeName: string;
+  AchievementAuthor: string;
+  GameID: string;
+  ConsoleName: string;
+  GameTitle: string;
+  GameIcon: string;
+  ReportedAt: string;
+  ReportType: string;
+  ReportState: string;
+  Hardcore: "0" | "1" | null;
+  ReportNotes: string;
+  ReportedBy: string;
+  ResolvedAt: string | null;
+  ResolvedBy: string | null;
+  ReportStateDescription: string;
+  ReportTypeDescription: string;
+
+  URL?: string;
+}

package/src/feed/models/ticket-entity.model.ts

@@ -0,0 +1,24 @@
+export interface TicketEntity {
+  id: number;
+  achievementId: number;
+  achievementTitle: string;
+  achievementDesc: string;
+  points: number;
+  badgeName: string;
+  achievementAuthor: string;
+  gameId: number;
+  consoleName: string;
+  gameTitle: string;
+  gameIcon: string;
+  reportedAt: string;
+  reportType: number;
+  reportState: number;
+  hardcore: boolean | null;
+  reportNotes: string;
+  reportedBy: string;
+  resolvedAt: string | null;
+  resolvedBy: string | null;
+  reportStateDescription: string;
+  reportTypeDescription: string;
+  url: string;
+}

package/src/feed/models/tickets-by-user-response.model.ts

@@ -0,0 +1,8 @@
+export interface TicketsByUserResponse {
+  User: string;
+  Open: number;
+  Closed: number;
+  Resolved: number;
+  Total: number;
+  URL: string;
+}

package/src/feed/models/top-ten-users-entity.model.ts

@@ -0,0 +1,5 @@
+export interface TopTenUsersEntity {
+  userName: string;
+  totalPoints: number;
+  totalRatioPoints: number;
+}

package/src/feed/models/top-ten-users.model.ts

@@ -0,0 +1,3 @@
+import type { TopTenUsersEntity } from "./top-ten-users-entity.model";
+
+export type TopTenUsers = TopTenUsersEntity[];

package/src/feed/models/user-ticket-stats.model.ts

@@ -0,0 +1,8 @@
+export interface UserTicketStats {
+  user: string;
+  open: number;
+  closed: number;
+  resolved: number;
+  total: number;
+  url: string;
+}

package/src/game/getAchievementCount.test.ts

@@ -0,0 +1,49 @@
+import { rest } from "msw";
+import { setupServer } from "msw/node";
+
+import { apiBaseUrl } from "../utils/internal";
+import { buildAuthorization } from "../utils/public";
+import { getAchievementCount } from "./getAchievementCount";
+import type { GetAchievementCountResponse } from "./models";
+
+const server = setupServer();
+
+describe("Function: getAchievementCount", () => {
+  // MSW Setup
+  beforeAll(() => server.listen());
+  afterEach(() => server.resetHandlers());
+  afterAll(() => server.close());
+
+  it("is defined #sanity", () => {
+    // ASSERT
+    expect(getAchievementCount).toBeDefined();
+  });
+
+  it("given a game ID, retrieves the list of achievement IDs associated with the game and cleans properties", async () => {
+    // ARRANGE
+    const authorization = buildAuthorization({
+      userName: "mockUserName",
+      webApiKey: "mockWebApiKey"
+    });
+
+    const mockResponse: GetAchievementCountResponse = {
+      GameID: 8,
+      AchievementIDs: [1, 2, 3, 4, 5]
+    };
+
+    server.use(
+      rest.get(`${apiBaseUrl}/API_GetAchievementCount.php`, (_, res, ctx) =>
+        res(ctx.json(mockResponse))
+      )
+    );
+
+    // ACT
+    const response = await getAchievementCount(authorization, { gameId: 8 });
+
+    // ASSERT
+    expect(response).toEqual({
+      gameId: 8,
+      achievementIds: [1, 2, 3, 4, 5]
+    });
+  });
+});

package/src/game/getAchievementCount.ts

@@ -0,0 +1,52 @@
+import {
+  apiBaseUrl,
+  buildRequestUrl,
+  call,
+  serializeProperties
+} from "../utils/internal";
+import type { AuthObject } from "../utils/public";
+import type { AchievementCount, GetAchievementCountResponse } from "./models";
+
+/**
+ * A call to this function will retrieve the list of
+ * achievement IDs for a game.
+ *
+ * @param authorization An object containing your userName and webApiKey.
+ * This can be constructed with `buildAuthorization()`.
+ *
+ * @param payload.gameId The unique game ID. If you are unsure, open the
+ * game's page on the RetroAchievements.org website. For example, Dragster's
+ * URL is https://retroachievements.org/game/14402. We can see from the
+ * URL that the game ID is "14402".
+ *
+ * @example
+ * ```
+ * const achievementCount = await getAchievementCount(
+ *   authorization,
+ *   { gameId: 14402 }
+ * );
+ * ```
+ *
+ * @returns An object containing a gameId and a list of
+ * achievementIds.
+ * ```
+ * { gameId: 14402, achievementIds: [1,2,3,4,5] }
+ * ```
+ */
+export const getAchievementCount = async (
+  authorization: AuthObject,
+  payload: { gameId: number }
+): Promise<AchievementCount> => {
+  const { gameId } = payload;
+
+  const url = buildRequestUrl(
+    apiBaseUrl,
+    "/API_GetAchievementCount.php",
+    authorization,
+    { i: gameId }
+  );
+
+  const rawResponse = await call<GetAchievementCountResponse>({ url });
+
+  return serializeProperties(rawResponse);
+};