@retroachievements/api 0.0.0-development

package/dist/user/models/get-game-info-and-user-progress-response.model.d.ts

@@ -0,0 +1,14 @@
+import type { GameExtendedRawAchievementEntity, GetGameExtendedResponse } from "../../game/models";
+declare type GetGameExtendedResponseWithoutClaims = Omit<GetGameExtendedResponse, "Claims">;
+declare type GameExtendedRawAchievementEntityWithUserProgress = GameExtendedRawAchievementEntity & {
+    DateEarned: string;
+    DateEarnedHardcore: string;
+};
+export interface GetGameInfoAndUserProgressResponse extends GetGameExtendedResponseWithoutClaims {
+    Achievements: Record<number, GameExtendedRawAchievementEntityWithUserProgress>;
+    NumAwardedToUser: number;
+    NumAwardedToUserHardcore: number;
+    UserCompletion: string;
+    UserCompletionHardcore: string;
+}
+export {};

package/dist/user/models/get-user-game-rank-and-score-response.model.d.ts

@@ -0,0 +1,8 @@
+interface UserGameRankAndScoreResponseEntity {
+    User: string;
+    TotalScore: string;
+    LastAward: string;
+    UserRank: string;
+}
+export declare type GetUserGameRankAndScoreResponse = UserGameRankAndScoreResponseEntity[];
+export {};

package/dist/user/models/get-user-points-response.model.d.ts

@@ -0,0 +1,4 @@
+export interface GetUserPointsResponse {
+    Points: number;
+    SoftcorePoints: number;
+}

package/dist/user/models/get-user-progress-response.model.d.ts

@@ -0,0 +1,10 @@
+interface UserProgressResponseEntity {
+    NumPossibleAchievements: string;
+    PossibleScore: string;
+    NumAchieved: number | string;
+    ScoreAchieved: number | string;
+    NumAchievedHardcore: number | string;
+    ScoreAchievedHardcore: number | string;
+}
+export declare type GetUserProgressResponse = Record<`${number}`, UserProgressResponseEntity>;
+export {};

package/dist/user/models/get-user-recently-played-games-response.model.d.ts

@@ -0,0 +1,16 @@
+interface UserRecentlyPlayedGameResponseEntity {
+    GameID: string;
+    ConsoleID: string;
+    ConsoleName: string;
+    Title: string;
+    ImageIcon: string;
+    LastPlayed: string;
+    NumPossibleAchievements: string;
+    PossibleScore: string;
+    NumAchieved: string | number;
+    ScoreAchieved: string | number;
+    NumAchievedHardcore: string | number;
+    ScoreAchievedHardcore: string | number;
+}
+export declare type GetUserRecentlyPlayedGamesResponse = UserRecentlyPlayedGameResponseEntity[];
+export {};

package/dist/user/models/get-user-summary-response.model.d.ts

@@ -0,0 +1,82 @@
+interface RecentlyPlayedGameEntity {
+    GameID: string;
+    ConsoleID: string;
+    ConsoleName: string;
+    Title: string;
+    ImageIcon: string;
+    LastPlayed: string;
+}
+interface RecentlyAwardedAchievementEntity {
+    NumPossibleAchievements: string;
+    PossibleScore: string;
+    NumAchieved: number | string;
+    ScoreAchieved: number | string;
+    NumAchievedHardcore: number | string;
+    ScoreAchievedHardcore: number | string;
+}
+interface ExtendedRecentAchievementEntity {
+    ID: string;
+    GameID: string;
+    GameTitle: string;
+    Title: string;
+    Description: string;
+    Points: string;
+    BadgeName: string;
+    IsAwarded: "1";
+    DateAwarded: string;
+    HardcoreAchieved: "0";
+}
+interface LastGameEntity {
+    ID: number;
+    Title: string;
+    ConsoleID: number;
+    ForumTopicID: number;
+    Flags: number;
+    ImageIcon: string;
+    ImageTitle: string;
+    ImageIngame: string;
+    ImageBoxArt: string;
+    Publisher: string;
+    Developer: string;
+    Genre: string;
+    Released: string;
+    IsFinal: boolean;
+    ConsoleName: string;
+    RichPresencePatch: string;
+}
+export interface GetUserSummaryResponse {
+    RecentlyPlayedCount: number;
+    RecentlyPlayed: RecentlyPlayedGameEntity[];
+    MemberSince: string;
+    LastActivity: {
+        ID: string;
+        timestamp: string;
+        lastupdate: string;
+        activitytype: string;
+        User: string;
+        data: string;
+        data2: string;
+    };
+    RichPresenceMsg: string;
+    LastGameID: string;
+    LastGame: LastGameEntity;
+    ContribCount: string;
+    ContribYield: string;
+    TotalPoints: string;
+    TotalSoftcorePoints: string;
+    TotalTruePoints: string;
+    Permissions: string;
+    Untracked: "0" | "1";
+    ID: string;
+    UserWallActive: "0" | "1";
+    Motto: string;
+    Rank: number;
+    Awarded: Record<`${number}`, RecentlyAwardedAchievementEntity>;
+    RecentAchievements: Record<`${number}`, Record<`${number}`, ExtendedRecentAchievementEntity>>;
+    Points: string;
+    SoftcorePoints: string;
+    UserPic: string;
+    TotalRanked: number;
+    Status: string;
+}
+export {};

package/dist/user/models/index.d.ts

@@ -0,0 +1,14 @@
+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-game-rank-and-score-response.model";
+export * from "./get-user-points-response.model";
+export * from "./get-user-progress-response.model";
+export * from "./get-user-recently-played-games-response.model";
+export * from "./get-user-summary-response.model";
+export * from "./user-game-rank-and-score.model";
+export * from "./user-points.model";
+export * from "./user-progress.model";
+export * from "./user-recently-played-games.model";
+export * from "./user-summary.model";

package/dist/user/models/user-game-rank-and-score.model.d.ts

@@ -0,0 +1,8 @@
+interface UserGameRankAndScoreEntity {
+    user: string;
+    totalScore: number;
+    lastAward: string;
+    userRank: number;
+}
+export declare type UserGameRankAndScore = UserGameRankAndScoreEntity[];
+export {};

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

@@ -0,0 +1,4 @@
+export interface UserPoints {
+    points: number;
+    softcorePoints: number;
+}

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

@@ -0,0 +1,10 @@
+interface UserProgressEntity {
+    numPossibleAchievements: number;
+    possibleScore: number;
+    numAchieved: number;
+    scoreAchieved: number;
+    numAchievedHardcore: number;
+    scoreAchievedHardcore: number;
+}
+export declare type UserProgress = Record<`${number}`, UserProgressEntity>;
+export {};

package/dist/user/models/user-recently-played-games.model.d.ts

@@ -0,0 +1,16 @@
+interface UserRecentlyPlayedGameEntity {
+    gameId: number;
+    consoleId: number;
+    consoleName: string;
+    title: string;
+    imageIcon: string;
+    lastPlayed: string;
+    numPossibleAchievements: number;
+    possibleScore: number;
+    numAchieved: number;
+    scoreAchieved: number;
+    numAchievedHardcore: number;
+    scoreAchievedHardcore: number;
+}
+export declare type UserRecentlyPlayedGames = UserRecentlyPlayedGameEntity[];
+export {};

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

@@ -0,0 +1,83 @@
+interface RecentlyPlayedGameEntity {
+    gameId: number;
+    consoleId: number;
+    consoleName: string;
+    title: string;
+    imageIcon: string;
+    lastPlayed: string;
+}
+interface LastActivityEntity {
+    id: number;
+    timestamp: string;
+    lastupdate: string;
+    activitytype: number;
+    user: string;
+    data: string;
+    data2: string;
+}
+interface LastGameEntity {
+    id: number;
+    title: string;
+    consoleId: number;
+    forumTopicId: number;
+    flags: number;
+    imageIcon: string;
+    imageTitle: string;
+    imageIngame: string;
+    imageBoxArt: string;
+    publisher: string;
+    developer: string;
+    genre: string;
+    released: string;
+    isFinal: boolean;
+    consoleName: string;
+    richPresencePatch: string;
+}
+interface AwardedGameEntity {
+    numPossibleAchievements: number;
+    possibleScore: number;
+    numAchieved: number;
+    scoreAchieved: number;
+    numAchievedHardcore: number;
+    scoreAchievedHardcore: number;
+}
+interface ExtendedRecentAchievementEntity {
+    id: number;
+    gameId: number;
+    gameTitle: string;
+    title: string;
+    description: string;
+    points: number;
+    badgeName: string;
+    isAwarded: true;
+    dateAwarded: string;
+    hardcoreAchieved: false;
+}
+export interface UserSummary {
+    recentlyPlayedCount: number;
+    recentlyPlayed: RecentlyPlayedGameEntity[];
+    memberSince: string;
+    lastActivity: LastActivityEntity;
+    richPresenceMsg: string;
+    lastGameId: number;
+    lastGame: LastGameEntity;
+    contribCount: number;
+    contribYield: number;
+    totalPoints: number;
+    totalSoftcorePoints: number;
+    totalTruePoints: number;
+    permissions: number;
+    untracked: boolean;
+    id: number;
+    userWallActive: boolean;
+    motto: string;
+    rank: number;
+    awarded: Record<`${number}`, AwardedGameEntity>;
+    recentAchievements: Record<`${number}`, Record<`${number}`, ExtendedRecentAchievementEntity>>;
+    points: number;
+    softcorePoints: number;
+    userPic: string;
+    totalRanked: number;
+    status: string;
+}
+export {};

package/dist/utils/internal/apiBaseUrl.d.ts

@@ -0,0 +1 @@
+export declare const apiBaseUrl = "https://retroachievements.org/API";

package/dist/utils/internal/buildRequestUrl.d.ts

@@ -0,0 +1,2 @@
+import type { AuthObject } from "../public/models";
+export declare const buildRequestUrl: (baseUrl: string, endpointUrl: string, authObject: AuthObject, args?: Record<string, string | number>) => string;

package/dist/utils/internal/call.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Fetch an HTTP resource. This is publicly exposed in the
+ * event you would like to access an endpoint that this
+ * library does not currently support.
+ *
+ * UNLESS YOU'RE SURE OF WHAT YOU'RE DOING, YOU PROBABLY
+ * SHOULDN'T USE THIS FUNCTION.
+ *
+ * 2022-10-09: At the time of writing, Node.js LTS (16.x)
+ * does not yet support fetch. As a result, we pull in
+ * isomorphic-unfetch for Node.js compatibility. Our support
+ * matrix includes 14.x and 16.x.
+ *
+ * @FIXME - When Node.js 20.x is released, remove the
+ * isomorphic-unfetch dependency. At that point we will have
+ * two major LTS versions that include a native fetch API.
+ */
+export declare const call: <T extends readonly any[] | Record<string, any>>(config: {
+    url: string;
+}) => Promise<T>;

package/dist/utils/internal/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./apiBaseUrl";
+export * from "./buildRequestUrl";
+export * from "./call";
+export * from "./serializeProperties";

package/dist/utils/internal/serializeProperties.d.ts

@@ -0,0 +1,4 @@
+export declare const serializeProperties: (originalData: any, options?: Partial<{
+    shouldCastToNumbers: string[];
+    shouldMapToBooleans: string[];
+}>) => any;

package/dist/utils/public/buildAuthorization.d.ts

@@ -0,0 +1,22 @@
+import type { AuthObject } from "./models";
+/**
+ * Accepts your RetroAchievements.org userName and web API key. After
+ * receiving these inputs, the function returns you a value that can be
+ * used for the authentication parameter by any of the async calls in this
+ * library.
+ *
+ * Your account's personal Web API Key can be found on the Settings page
+ * of RetroAchievements.org. Do not use a Web API Key that is not associated
+ * with your account.
+ *
+ * @returns An `AuthObject` that you can pass to any of the API call functions.
+ *
+ * @example
+ * ```
+ * const authorization = buildAuthorization({
+ *   userName: "Scott",
+ *   webApiKey: "LtjCwW16nJI7cqOyPIQtXk8v1cfF0tmO"
+ * });
+ * ```
+ */
+export declare const buildAuthorization: (options: AuthObject) => AuthObject;

package/dist/utils/public/index.d.ts

@@ -0,0 +1,3 @@
+export { call as unsafe_call } from "../internal/call";
+export * from "./buildAuthorization";
+export * from "./models";

package/dist/utils/public/models/auth-object.model.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Each RetroAchievements API call is uniquely authenticated
+ * using a userName + API key combination. Your account's personal
+ * Web API Key can be found on the Settings page.
+ */
+export interface AuthObject {
+    /**
+     * You or your app's exact username on the RetroAchievements.org website.
+     * For example, https://retroachievements.org/user/Scott would have a value
+     * of "Scott".
+     */
+    userName: string;
+    /**
+     * This can be found in the "Keys" section of your Settings page on the
+     * RetroAchievements.org website. This is a 32-digit alphanumeric key
+     * that is case-sensitive.
+     */
+    webApiKey: string;
+}

package/dist/utils/public/models/index.d.ts

@@ -0,0 +1 @@
+export * from "./auth-object.model";

package/package.json

@@ -0,0 +1,117 @@
+{
+  "name": "@retroachievements/api",
+  "description": "A well-tested library that lets you get achievement, user, and game data from RetroAchievements.",
+  "keywords": [
+    "retroachievements",
+    "achievements",
+    "trophies",
+    "raweb",
+    "retro gaming"
+  ],
+  "version": "0.0.0-development",
+  "main": "dist/index.js",
+  "module": "dist/api.esm.js",
+  "typings": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "require": "./dist/index.js",
+      "import": "./dist/api.esm.js"
+    }
+  },
+  "license": "MIT",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "dev": "esrun --watch src/__playground.ts",
+    "build": "dts build",
+    "prepare": "dts build",
+    "format": "prettier --write . '**/*.{json,md,js,ts,tsx}'",
+    "format:write": "prettier --write . '**/*.{json,md,js,ts,tsx}'",
+    "format:check": "prettier --check . '**/*.{json,md,js,ts,tsx}'",
+    "lint": "eslint --ignore-path .gitignore --ext .js,.ts,.tsx .",
+    "lint:fix": "eslint --ignore-path .gitignore --ext .js,.ts,.tsx . --fix",
+    "test": "jest --selectProjects UNIT",
+    "test:coverage": "jest --selectProjects UNIT --coverage",
+    "verify": "yarn format:check && yarn lint && yarn test:coverage && yarn build && yarn size",
+    "size": "size-limit",
+    "start": "dts watch"
+  },
+  "dependencies": {
+    "isomorphic-unfetch": "^3.1.0"
+  },
+  "peerDependencies": {},
+  "devDependencies": {
+    "@commitlint/cli": "^17.1.2",
+    "@commitlint/config-conventional": "^17.1.0",
+    "@digitak/esrun": "^3.2.13",
+    "@size-limit/preset-small-lib": "^8.1.0",
+    "@swc/core": "^1.3.10",
+    "@swc/jest": "^0.2.23",
+    "@tsconfig/recommended": "^1.0.1",
+    "@types/jest": "^29.2.0",
+    "@typescript-eslint/eslint-plugin": "^5.41.0",
+    "@typescript-eslint/parser": "^5.41.0",
+    "cz-conventional-changelog": "^3.3.0",
+    "dotenv-flow-cli": "^1.0.0",
+    "dts-cli": "^1.6.0",
+    "eslint": "^8.26.0",
+    "eslint-config-prettier": "^8.5.0",
+    "eslint-import-resolver-typescript": "^3.5.2",
+    "eslint-plugin-import": "^2.26.0",
+    "eslint-plugin-simple-import-sort": "^8.0.0",
+    "eslint-plugin-sonarjs": "^0.16.0",
+    "eslint-plugin-unicorn": "^44.0.2",
+    "husky": "^4.3.8",
+    "jest": "^29.2.1",
+    "msw": "^0.47.4",
+    "prettier": "2.7.1",
+    "pretty-quick": "3.1.3",
+    "size-limit": "^8.1.0",
+    "tslib": "^2.4.0",
+    "type-fest": "^3.1.0",
+    "typescript": "^4.8.4"
+  },
+  "size-limit": [
+    {
+      "path": "dist/api.cjs.production.min.js",
+      "limit": "10 KB"
+    },
+    {
+      "path": "dist/api.esm.js",
+      "limit": "10 KB"
+    }
+  ],
+  "husky": {
+    "hooks": {
+      "pre-commit": "pretty-quick --staged && yarn lint",
+      "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
+    }
+  },
+  "config": {
+    "commitizen": {
+      "path": "./node_modules/cz-conventional-changelog"
+    }
+  },
+  "engines": {
+    "node": ">=14",
+    "npm": "please-use-yarn",
+    "yarn": ">= 1.19.1"
+  },
+  "release": {
+    "branches": [
+      "main",
+      "next"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RetroAchievements/retroachievements-api-js.git"
+  },
+  "bugs": {
+    "url": "https://github.com/RetroAchievements/retroachievements-api-js/issues"
+  },
+  "homepage": "https://github.com/RetroAchievements/retroachievements-api-js#readme",
+  "author": "RAWeb Team"
+}

package/src/__playground.ts

@@ -0,0 +1,27 @@
+/**
+ * PLEASE ONLY COMMIT CHANGES TO THIS FILE IF YOU WANT THEM
+ * TO DIRECTLY IMPACT EVERY DEV WORKING ON THE PROJECT.
+ *
+ * Use this file to test and experiment with changes to the project.
+ */
+
+// If you can't import what you want from "./index", users won't
+// be able to import it either.
+import { buildAuthorization, getTicketData } from "./index";
+
+const main = async () => {
+  console.log("retroachievements-api-js playground is running.");
+  console.log(""); // newline
+
+  // -- Start testing stuff here --
+
+  const authorization = buildAuthorization({
+    userName: "WCopeland",
+    webApiKey: "gYPwmMOAIiGkOmk1qpNDrTfqBiGIeh7X"
+  });
+
+  const ticketData = await getTicketData(authorization, {});
+  console.log(ticketData);
+};
+
+main();

package/src/achievement/getAchievementUnlocks.test.ts

@@ -0,0 +1,71 @@
+import { rest } from "msw";
+import { setupServer } from "msw/node";
+
+import { apiBaseUrl } from "../utils/internal";
+import { buildAuthorization } from "../utils/public";
+import { getAchievementUnlocks } from "./getAchievementUnlocks";
+import type { GetAchievementUnlocksResponse } from "./models";
+
+const server = setupServer();
+
+describe("Function: getAchievementUnlocks", () => {
+  // MSW Setup
+  beforeAll(() => server.listen());
+  afterEach(() => server.resetHandlers());
+  afterAll(() => server.close());
+
+  it("is defined #sanity", () => {
+    // ASSERT
+    expect(getAchievementUnlocks).toBeDefined();
+  });
+
+  it("retrieves metadata about unlocks for a target achievement", async () => {
+    // ARRANGE
+    const authorization = buildAuthorization({
+      userName: "mockUserName",
+      webApiKey: "mockWebApiKey"
+    });
+
+    const mockResponse: GetAchievementUnlocksResponse = [
+      {
+        User: "Podgicus0305",
+        RAPoints: "15544",
+        DateAwarded: "2022-07-12 19:06:34",
+        HardcoreMode: "1"
+      }
+    ];
+
+    let searchParams = "";
+
+    server.use(
+      rest.get(
+        `${apiBaseUrl}/API_GetAchievementUnlocks.php`,
+        (req, res, ctx) => {
+          searchParams = req.url.search;
+          return res(ctx.json(mockResponse));
+        }
+      )
+    );
+
+    // ACT
+    const response = await getAchievementUnlocks(authorization, {
+      achievementId: 18_000,
+      count: 1,
+      offset: 1
+    });
+
+    // ASSERT
+    expect(searchParams).toContain("a=18000");
+    expect(searchParams).toContain("o=1");
+    expect(searchParams).toContain("c=1");
+
+    expect(response).toEqual([
+      {
+        user: "Podgicus0305",
+        raPoints: 15_544,
+        dateAwarded: "2022-07-12 19:06:34",
+        hardcoreMode: true
+      }
+    ]);
+  });
+});

package/src/achievement/getAchievementUnlocks.ts

@@ -0,0 +1,80 @@
+import {
+  apiBaseUrl,
+  buildRequestUrl,
+  call,
+  serializeProperties
+} from "../utils/internal";
+import type { AuthObject } from "../utils/public";
+import type {
+  AchievementUnlockEntity,
+  GetAchievementUnlocksResponse
+} from "./models";
+
+/**
+ * A call to this function will retrieve a list of users who
+ * have earned the given achievementId.
+ *
+ * @param authorization An object containing your userName and webApiKey.
+ * This can be constructed with `buildAuthorization()`.
+ *
+ * @param payload.achievementId The target achievement we want to
+ * retrieve the unlocks list for. If unknown, this can be found
+ * by navigating to the achievement's page on the RetroAchievements.org
+ * website. eg: https://retroachievements.org/achievement/13876 has an
+ * ID of 13876.
+ *
+ * @param payload.offset Defaults to 0. The number of entries to skip.
+ *
+ * @param payload.count Defaults to 50, has a max of 500.
+ *
+ * @example
+ * ```
+ * const achievementUnlocks = await getAchievementUnlocks(
+ *   authorization,
+ *   { achievementId: 13876 }
+ * );
+ * ```
+ *
+ * @returns An array containing metadata about unlocks for
+ * the target achievement.
+ * ```
+ * [
+ *   {
+ *     user: 'Podgicus0305',
+ *     raPoints: 15544,
+ *     dateAwarded: '2022-07-12 19:06:34',
+ *     hardcoreMode: true
+ *   }
+ * ]
+ * ```
+ */
+export const getAchievementUnlocks = async (
+  authorization: AuthObject,
+  payload: { achievementId: number; offset?: number; count?: number }
+): Promise<AchievementUnlockEntity[]> => {
+  const { achievementId, offset, count } = payload;
+
+  const queryParams: Record<string, number> = { a: achievementId };
+
+  if (offset) {
+    queryParams.o = offset;
+  }
+
+  if (count) {
+    queryParams.c = count;
+  }
+
+  const url = buildRequestUrl(
+    apiBaseUrl,
+    "/API_GetAchievementUnlocks.php",
+    authorization,
+    queryParams
+  );
+
+  const rawResponse = await call<GetAchievementUnlocksResponse>({ url });
+
+  return serializeProperties(rawResponse, {
+    shouldCastToNumbers: ["RAPoints"],
+    shouldMapToBooleans: ["HardcoreMode"]
+  });
+};

package/src/achievement/index.ts

@@ -0,0 +1,2 @@
+export * from "./getAchievementUnlocks";
+export * from "./models";