@retroachievements/api 0.0.0-development

package/dist/game/models/game-extended.model.d.ts

@@ -0,0 +1,25 @@
+import type { GameExtendedAchievementEntity } from "./game-extended-achievement-entity.model";
+import type { GameExtendedClaimEntity } from "./game-extended-claim-entity.model";
+export interface GameExtended {
+    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: number;
+    isFinal: boolean;
+    consoleName: string;
+    richPresencePatch: string;
+    numAchievements: number;
+    numDistinctPlayersCasual: number;
+    numDistinctPlayersHardcore: number;
+    claims: GameExtendedClaimEntity[];
+    achievements: Record<number, GameExtendedAchievementEntity>;
+}

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

@@ -0,0 +1,6 @@
+export interface GameRankAndScoreEntity {
+    user: string;
+    totalScore: number;
+    lastAward: string;
+    rank: number;
+}

package/dist/game/models/game-rating.model.d.ts

@@ -0,0 +1,9 @@
+export interface GameRating {
+    gameId: number;
+    ratings: {
+        game: number;
+        achievements: number;
+        gameNumVotes: number;
+        achievementsNumVotes: number;
+    };
+}

package/dist/game/models/game.model.d.ts

@@ -0,0 +1,19 @@
+export interface Game {
+    id: number;
+    title: string;
+    forumTopicId: number;
+    consoleId: number;
+    consoleName: string;
+    flags: number;
+    imageIcon: string;
+    gameIcon: string;
+    imageTitle: string;
+    imageIngame: string;
+    imageBoxArt: string;
+    publisher: string;
+    developer: string;
+    genre: string;
+    released: number;
+    gameTitle: string;
+    console: string;
+}

package/dist/game/models/get-achievement-count-response.model.d.ts

@@ -0,0 +1,4 @@
+export interface GetAchievementCountResponse {
+    GameID: number;
+    AchievementIDs: number[];
+}

package/dist/game/models/get-achievement-distribution-response.model.d.ts

@@ -0,0 +1 @@
+export declare type GetAchievementDistributionResponse = Record<`${number}`, number>;

package/dist/game/models/get-game-extended-response.model.d.ts

@@ -0,0 +1,50 @@
+declare enum GameExtendedClaimType {
+    Primary = "0",
+    Collaboration = "1"
+}
+export interface GameExtendedRawAchievementEntity {
+    ID: string;
+    NumAwarded: string;
+    NumAwardedHardcore: string;
+    Title: string;
+    Description: string;
+    Points: string;
+    TrueRatio: string;
+    Author: string;
+    DateModified: string;
+    DateCreated: string;
+    BadgeName: string;
+    DisplayOrder: string;
+    MemAddr: string;
+}
+interface GameExtendedRawClaimEntity {
+    User: string;
+    SetType: string;
+    ClaimType: GameExtendedClaimType;
+    Created: string;
+    Expiration: string;
+}
+export interface GetGameExtendedResponse {
+    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;
+    NumAchievements: number;
+    NumDistinctPlayersCasual: string;
+    NumDistinctPlayersHardcore: string;
+    Claims: GameExtendedRawClaimEntity[];
+    Achievements: Record<number, GameExtendedRawAchievementEntity> | [];
+}
+export {};

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

@@ -0,0 +1,8 @@
+interface RawGameRankAndScoreEntity {
+    User: string;
+    TotalScore: string;
+    LastAward: string;
+    Rank: number;
+}
+export declare type GetGameRankAndScoreResponse = RawGameRankAndScoreEntity[];
+export {};

package/dist/game/models/get-game-rating-response.model.d.ts

@@ -0,0 +1,9 @@
+export interface GetGameRatingResponse {
+    GameID: number;
+    Ratings: {
+        Game: number;
+        Achievements: number;
+        GameNumVotes: number;
+        AchievementsNumVotes: number;
+    };
+}

package/dist/game/models/get-game-response.model.d.ts

@@ -0,0 +1,19 @@
+export interface GetGameResponse {
+    ID: string;
+    Title: string;
+    ForumTopicID: string;
+    ConsoleID: string;
+    ConsoleName: string;
+    Flags: string;
+    ImageIcon: string;
+    GameIcon: string;
+    ImageTitle: string;
+    ImageIngame: string;
+    ImageBoxArt: string;
+    Publisher: string;
+    Developer: string;
+    Genre: string;
+    Released: string;
+    GameTitle: string;
+    Console: string;
+}

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

@@ -0,0 +1,14 @@
+export * from "./achievement-count.model";
+export * from "./achievement-distribution-flags.model";
+export * from "./game.model";
+export * from "./game-extended.model";
+export * from "./game-extended-achievement-entity.model";
+export * from "./game-extended-claim-entity.model";
+export * from "./game-rank-and-score-entity.model";
+export * from "./game-rating.model";
+export * from "./get-achievement-count-response.model";
+export * from "./get-achievement-distribution-response.model";
+export * from "./get-game-extended-response.model";
+export * from "./get-game-rank-and-score-response.model";
+export * from "./get-game-rating-response.model";
+export * from "./get-game-response.model";

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./achievement";
+export * from "./console";
+export * from "./feed";
+export * from "./game";
+export * from "./user";
+export * from "./utils/public";

package/dist/index.js

@@ -0,0 +1,8 @@
+
+'use strict'
+
+if (process.env.NODE_ENV === 'production') {
+  module.exports = require('./api.cjs.production.min.js')
+} else {
+  module.exports = require('./api.cjs.development.js')
+}

package/dist/user/getAchievementsEarnedBetween.d.ts

@@ -0,0 +1,59 @@
+import type { AuthObject } from "../utils/public";
+import type { DatedUserAchievement } from "./models";
+/**
+ * A call to this function will retrieve a list of achievements
+ * earned by a given user between two provided dates.
+ *
+ * @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
+ * list of achievements for.
+ *
+ * @param payload.fromDate A Date object specifying when
+ * the list itself should begin.
+ *
+ * @param payload.toDate A Date object specifying when
+ * the list itself should end.
+ *
+ * @example
+ * ```
+ * const achievementsEarnedBetween = await getAchievementsEarnedBetween(
+ *   authorization,
+ *   {
+ *     userName: "xelnia",
+ *     fromDate: new Date("2022-10-12"),
+ *     toDate: new Date("2022-10-13")
+ *   }
+ * );
+ * ```
+ *
+ * @returns An array containing metadata about the user
+ * achievements earned during the specified date range.
+ * ```
+ *  [
+ *    {
+ *      date: '2022-10-12 07:58:05',
+ *      hardcoreMode: true,
+ *      achievementId: 173315,
+ *      title: 'Your Puny Human Weapons',
+ *      description: 'Collect all objects in the Weapons Category.',
+ *      badgeName: '193756',
+ *      points: 10,
+ *      author: 'blendedsea',
+ *      gameTitle: 'Me & My Katamari',
+ *      gameIcon: '/Images/047357.png',
+ *      gameId: 3571,
+ *      consoleName: 'PlayStation Portable',
+ *      cumulScore: 120,
+ *      badgeUrl: '/Badge/193756.png',
+ *      gameUrl: '/game/3571'
+ *    }
+ *  ]
+ * ```
+ */
+export declare const getAchievementsEarnedBetween: (authorization: AuthObject, payload: {
+    userName: string;
+    fromDate: Date;
+    toDate: Date;
+}) => Promise<DatedUserAchievement[]>;

package/dist/user/getAchievementsEarnedOnDay.d.ts

@@ -0,0 +1,57 @@
+import type { AuthObject } from "../utils/public";
+import type { DatedUserAchievement } from "./models";
+/**
+ * A call to this function will retrieve a list of achievements
+ * earned by a given user on a specified date.
+ *
+ * @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
+ * list of achievements for.
+ *
+ * @param payload.fromDate A Date object specifying when
+ * the list itself should begin.
+ *
+ * @param payload.onDate A Date object specifying the day
+ * to query for a user's earned achievements.
+ *
+ * @example
+ * ```
+ * const achievementsEarnedOnDay = await getAchievementsEarnedOnDay(
+ *   authorization,
+ *   {
+ *     userName: "xelnia",
+ *     onDate: new Date("2022-10-13")
+ *   }
+ * );
+ * ```
+ *
+ * @returns An array containing metadata about the user
+ * achievements earned on the specified day.
+ * ```
+ *  [
+ *    {
+ *      date: '2022-10-12 07:58:05',
+ *      hardcoreMode: true,
+ *      achievementId: 173315,
+ *      title: 'Your Puny Human Weapons',
+ *      description: 'Collect all objects in the Weapons Category.',
+ *      badgeName: '193756',
+ *      points: 10,
+ *      author: 'blendedsea',
+ *      gameTitle: 'Me & My Katamari',
+ *      gameIcon: '/Images/047357.png',
+ *      gameId: 3571,
+ *      consoleName: 'PlayStation Portable',
+ *      cumulScore: 120,
+ *      badgeUrl: '/Badge/193756.png',
+ *      gameUrl: '/game/3571'
+ *    }
+ *  ]
+ * ```
+ */
+export declare const getAchievementsEarnedOnDay: (authorization: AuthObject, payload: {
+    userName: string;
+    onDate: Date;
+}) => Promise<DatedUserAchievement[]>;

package/dist/user/getGameInfoAndUserProgress.d.ts

@@ -0,0 +1,80 @@
+import type { AuthObject } from "../utils/public";
+import type { GameInfoAndUserProgress } from "./models";
+/**
+ * A call to this function will retrieve extended metadata
+ * about a game, in addition to a user's progress about a game.
+ * This is targeted via a game's unique ID and a given username.
+ *
+ * @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".
+ *
+ * @param payload.userName The user for which to retrieve the
+ * game progress for.
+ *
+ * @example
+ * ```
+ * const gameInfoAndUserProgress = await getGameInfoAndUserProgress(
+ *   authorization,
+ *   { gameId: 14402, userName: "wv_pinball" }
+ * );
+ * ```
+ *
+ * @returns An object containing extended metadata about a target game,
+ * with attached progress for a target username.
+ * ```json
+ * {
+ *   id: 14402,
+ *   title: "Dragster",
+ *   consoleId: 25,
+ *   forumTopicId: 9145,
+ *   flags: 0,
+ *   imageIcon: "/Images/026368.png",
+ *   imageTitle: "/Images/026366.png",
+ *   imageIngame: "/Images/026367.png",
+ *   imageBoxArt: "/Images/026365.png",
+ *   publisher: "Activision",
+ *   developer: "David Crane",
+ *   genre: "Racing",
+ *   released: 1980,
+ *   isFinal: false,
+ *   consoleName: "Atari 2600",
+ *   richPresencePatch: "2b92fa1bf9635c303b3b7f8feea3ed3c",
+ *   numAchievements: 12,
+ *   numDistinctPlayersCasual: 454,
+ *   numDistinctPlayersHardcore, 323
+ *   claims: [],
+ *   achievements: {
+ *     '79434': {
+ *       id: 79434,
+ *       numAwarded: 338,
+ *       numAwardedHardcore: 253,
+ *       title: "Novice Dragster Driver 1",
+ *       description: "Complete your very first race in game 1.",
+ *       points: 1,
+ *       trueRatio: 1,
+ *       author: "Boldewin",
+ *       dateModified: "2019-08-01 19:03:46",
+ *       dateCreated: "2019-07-31 18:49:57",
+ *       badgeName: "85541",
+ *       displayOrder: 0,
+ *       memAddr: "f5c41fa0b5fa0d5fbb8a74c598f18582",
+ *       dateEarned: '2022-08-23 22:56:38',
+ *       dateEarnedHardcore: '2022-08-23 22:56:38'
+ *     }
+ *   },
+ *   numAwardedToUser: 12,
+ *   numAwardedToUserHardcore: 12,
+ *   userCompletion: "100.00%",
+ *   userCompletionHardcore: "100.00%"
+ * }
+ * ```
+ */
+export declare const getGameInfoAndUserProgress: (authorization: AuthObject, payload: {
+    gameId: number;
+    userName: string;
+}) => Promise<GameInfoAndUserProgress>;

package/dist/user/getUserGameRankAndScore.d.ts

@@ -0,0 +1,44 @@
+import type { AuthObject } from "../utils/public";
+import type { UserGameRankAndScore } from "./models";
+/**
+ * A call to this function will retrieve metadata about
+ * how a particular user has performed/ranked on a particular
+ * game, targeted by game ID.
+ *
+ * @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".
+ *
+ * @param payload.userName The user for which to retrieve the
+ * game ranking metadata for.
+ *
+ * @example
+ * ```
+ * const userGameRankAndScore = await getUserGameRankAndScore(
+ *   authorization,
+ *   { gameId: 14402, userName: "xelnia" }
+ * );
+ * ```
+ *
+ * @returns An array containing metadata about the user's
+ * rank and score for the target game ID. If metadata
+ * cannot be found, the array is empty.
+ * ```
+ * [
+ *   {
+ *     user: "xelnia",
+ *     totalScore: 378,
+ *     lastAward: "2022-09-01 21:51:23",
+ *     userRank: 3
+ *   }
+ * ]
+ * ```
+ */
+export declare const getUserGameRankAndScore: (authorization: AuthObject, payload: {
+    gameId: number;
+    userName: string;
+}) => Promise<UserGameRankAndScore>;

package/dist/user/getUserPoints.d.ts

@@ -0,0 +1,30 @@
+import type { AuthObject } from "../utils/public";
+import type { UserPoints } from "./models";
+/**
+ * A call to this function will retrieve a given user's hardcore
+ * and softcore points.
+ *
+ * @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 points for.
+ *
+ * @example
+ * ```
+ * const userPoints = await getUserPoints(
+ *   authorization,
+ *   { userName: "xelnia" }
+ * );
+ * ```
+ *
+ * @returns An object containing metadata about a target user's points.
+ * ```json
+ * {
+ *   points: 7640,
+ *   softcorePoints: 25
+ * }
+ * ```
+ */
+export declare const getUserPoints: (authorization: AuthObject, payload: {
+    userName: string;
+}) => Promise<UserPoints>;

package/dist/user/getUserProgress.d.ts

@@ -0,0 +1,49 @@
+import type { AuthObject } from "../utils/public";
+import type { UserProgress } from "./models";
+/**
+ * A call to this function will retrieve a given user's
+ * progress on a given set of games, targeted by game ID.
+ *
+ * @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 progress for.
+ *
+ * @param payload.gameIds An array of RetroAchievements Game IDs. If you aren't
+ * sure of the game ID, visit the game's page on the website and copy the number
+ * at the end of the URL.
+ *
+ * @example
+ * ```
+ * const userProgress = await getUserProgress(
+ *   authorization,
+ *   { userName: "xelnia", gameIds: [14402, 1] }
+ * );
+ * ```
+ *
+ * @returns An object which is a map of summarized progress for games.
+ * ```json
+ * {
+ *   "1": {
+ *     numPossibleAchievements: 24,
+ *     possibleScore: 255,
+ *     numAchieved: 0,
+ *     scoreAchieved: 0,
+ *     numAchievedHardcore: 0,
+ *     scoreAchievedHardcore: 0
+ *   },
+ *   "14402": {
+ *     numPossibleAchievements: 24,
+ *     possibleScore: 255,
+ *     numAchieved: 0,
+ *     scoreAchieved: 0,
+ *     numAchievedHardcore: 0,
+ *     scoreAchievedHardcore: 0
+ *   }
+ * }
+ * ```
+ */
+export declare const getUserProgress: (authorization: AuthObject, payload: {
+    userName: string;
+    gameIds: Array<number | string>;
+}) => Promise<UserProgress>;

package/dist/user/getUserRecentlyPlayedGames.d.ts

@@ -0,0 +1,50 @@
+import type { AuthObject } from "../utils/public";
+import type { UserRecentlyPlayedGames } from "./models";
+/**
+ * A call to this function will retrieve a list of a target user's
+ * recently played games, targeted by 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 summary for.
+ *
+ * @param payload.count Optional. Defaults to 10. Max is 50. How many
+ * recently played games for the user to retrieve.
+ *
+ * @param payload.offset Optional. Defaults to 0. Number of recently played
+ * game entries to skip. This can be used for pagination.
+ *
+ * @example
+ * ```
+ * const userRecentlyPlayedGames = await getUserRecentlyPlayedGames(
+ *   authorization,
+ *   { userName: "xelnia" }
+ * );
+ * ```
+ *
+ * @returns An array containing metadata about a user's recently played games.
+ * ```json
+ * [
+ *   {
+ *     gameId: 19010,
+ *     consoleId: 21,
+ *     consoleName: "PlayStation 2",
+ *     title: "Simpsons, The: Hit & Run",
+ *     imageIcon: "/Images/066024.png",
+ *     lastPlayed: "2022-10-24 22:05:12",
+ *     numPossibleAchievements: 131,
+ *     possibleScore: 865,
+ *     numAchieved: 23,
+ *     scoreAchieved: 84,
+ *     numAchievedHardcore: 23,
+ *     scoreAchievedHardcore: 84
+ *   }
+ * ]
+ * ```
+ */
+export declare const getUserRecentlyPlayedGames: (authorization: AuthObject, payload: {
+    userName: string;
+    offset?: number;
+    count?: number;
+}) => Promise<UserRecentlyPlayedGames>;

package/dist/user/getUserSummary.d.ts

@@ -0,0 +1,32 @@
+import type { AuthObject } from "../utils/public";
+import type { UserSummary } from "./models";
+/**
+ * A call to this function will retrieve summary information about
+ * a given user, targeted by 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 summary for.
+ *
+ * @param payload.recentGamesCount Optional. The number of recent games to return.
+ * This defaults to 5.
+ *
+ * @param payload.recentAchievementsCount Optional. The number of recent achievements
+ * to return. This defaults to 5.
+ *
+ * @example
+ * ```
+ * const userSummary = await getUserSummary(
+ *   authorization,
+ *   { userName: "xelnia" }
+ * );
+ * ```
+ *
+ * @returns An object containing summary metadata about a target user.
+ */
+export declare const getUserSummary: (authorization: AuthObject, payload: {
+    userName: string;
+    recentGamesCount?: number;
+    recentAchievementsCount?: number;
+}) => Promise<UserSummary>;

package/dist/user/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./getAchievementsEarnedBetween";
+export * from "./getAchievementsEarnedOnDay";
+export * from "./getGameInfoAndUserProgress";
+export * from "./getUserGameRankAndScore";
+export * from "./getUserPoints";
+export * from "./getUserProgress";
+export * from "./getUserRecentlyPlayedGames";
+export * from "./getUserSummary";
+export * from "./models";

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

@@ -0,0 +1,17 @@
+export declare type DatedUserAchievement = {
+    date: string;
+    hardcoreMode: boolean;
+    achievementId: number;
+    title: string;
+    description: string;
+    badgeName: string;
+    points: number;
+    author: string;
+    gameTitle: string;
+    gameIcon: string;
+    gameId: number;
+    consoleName: string;
+    cumulScore: number;
+    badgeUrl: string;
+    gameUrl: string;
+}[];

package/dist/user/models/dated-user-achievements-response.model.d.ts

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

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

@@ -0,0 +1,12 @@
+import type { GameExtended, GameExtendedAchievementEntity } from "../../game/models";
+export declare type GameExtendedAchievementEntityWithUserProgress = GameExtendedAchievementEntity & {
+    dateEarned: string;
+    dateEarnedHardcore: string;
+};
+export interface GameInfoAndUserProgress extends GameExtended {
+    achievements: Record<number, GameExtendedAchievementEntityWithUserProgress>;
+    numAwardedToUser: number;
+    numAwardedToUserHardcore: number;
+    userCompletion: string;
+    userCompletionHardcore: string;
+}