@retroachievements/api 1.0.0-rc.0 → 1.0.0-rc.2

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

@@ -6,5 +6,5 @@ interface TopTenUsersResponseEntity {
     /** Total ratio (white) points earned by the user  */
     "3": string;
 }
-export declare type GetTopTenUsersResponse = TopTenUsersResponseEntity[];
+export type GetTopTenUsersResponse = TopTenUsersResponseEntity[];
 export {};

package/dist/feed/models/most-ticketed-games.model.d.ts

@@ -1,4 +1,4 @@
-interface ReportedGameEntity {
+export interface ReportedGameEntity {
     gameId: number;
     gameTitle: string;
     gameIcon: string;
@@ -9,4 +9,3 @@ export interface MostTicketedGames {
     mostReportedGames: ReportedGameEntity[];
     url: string;
 }
-export {};

package/dist/feed/models/top-ten-users.model.d.ts

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

package/dist/game/getAchievementCount.d.ts

@@ -1,3 +1,4 @@
+import type { ID } from "../utils/internal";
 import type { AuthObject } from "../utils/public";
 import type { AchievementCount } from "./models";
 /**
@@ -27,5 +28,5 @@ import type { AchievementCount } from "./models";
  * ```
  */
 export declare const getAchievementCount: (authorization: AuthObject, payload: {
-    gameId: number;
+    gameId: ID;
 }) => Promise<AchievementCount>;

package/dist/game/getAchievementDistribution.d.ts

@@ -1,3 +1,4 @@
+import type { ID } from "../utils/internal";
 import type { AuthObject } from "../utils/public";
 import type { AchievementDistributionFlags, GetAchievementDistributionResponse } from "./models";
 /**
@@ -51,7 +52,7 @@ import type { AchievementDistributionFlags, GetAchievementDistributionResponse }
  * ```
  */
 export declare const getAchievementDistribution: (authorization: AuthObject, payload: {
-    gameId: number;
+    gameId: ID;
     flags?: AchievementDistributionFlags;
     hardcore?: boolean;
 }) => Promise<GetAchievementDistributionResponse>;

package/dist/game/getGame.d.ts

@@ -1,3 +1,4 @@
+import type { ID } from "../utils/internal";
 import type { AuthObject } from "../utils/public";
 import type { Game } from "./models";
 /**
@@ -44,5 +45,5 @@ import type { Game } from "./models";
  * ```
  */
 export declare const getGame: (authorization: AuthObject, payload: {
-    gameId: number;
+    gameId: ID;
 }) => Promise<Game>;

package/dist/game/getGameExtended.d.ts

@@ -1,3 +1,4 @@
+import type { ID } from "../utils/internal";
 import type { AuthObject } from "../utils/public";
 import type { GameExtended } from "./models";
 /**
@@ -64,5 +65,5 @@ import type { GameExtended } from "./models";
  * ```
  */
 export declare const getGameExtended: (authorization: AuthObject, payload: {
-    gameId: number;
+    gameId: ID;
 }) => Promise<GameExtended>;

package/dist/game/getGameRankAndScore.d.ts

@@ -1,3 +1,4 @@
+import type { ID } from "../utils/internal";
 import type { AuthObject } from "../utils/public";
 import type { GameRankAndScoreEntity } from "./models";
 /**
@@ -33,6 +34,6 @@ import type { GameRankAndScoreEntity } from "./models";
  * ```
  */
 export declare const getGameRankAndScore: (authorization: AuthObject, payload: {
-    gameId: number;
+    gameId: ID;
     type: "latest-masters" | "high-scores";
 }) => Promise<GameRankAndScoreEntity[]>;

package/dist/game/getGameRating.d.ts

@@ -1,3 +1,4 @@
+import type { ID } from "../utils/internal";
 import type { AuthObject } from "../utils/public";
 import type { GameRating } from "./models";
 /**
@@ -34,5 +35,5 @@ import type { GameRating } from "./models";
  * ```
  */
 export declare const getGameRating: (authorization: AuthObject, payload: {
-    gameId: number;
+    gameId: ID;
 }) => Promise<GameRating>;

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

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

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

@@ -4,5 +4,5 @@ interface RawGameRankAndScoreEntity {
     LastAward: string;
     Rank: number;
 }
-export declare type GetGameRankAndScoreResponse = RawGameRankAndScoreEntity[];
+export type GetGameRankAndScoreResponse = RawGameRankAndScoreEntity[];
 export {};

package/dist/user/getAchievementsEarnedBetween.d.ts

@@ -31,25 +31,25 @@ import type { DatedUserAchievement } from "./models";
  * @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'
- *    }
- *  ]
+ * [
+ *   {
+ *     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: {

package/dist/user/getGameInfoAndUserProgress.d.ts

@@ -1,3 +1,4 @@
+import type { ID } from "../utils/internal";
 import type { AuthObject } from "../utils/public";
 import type { GameInfoAndUserProgress } from "./models";
 /**
@@ -75,6 +76,6 @@ import type { GameInfoAndUserProgress } from "./models";
  * ```
  */
 export declare const getGameInfoAndUserProgress: (authorization: AuthObject, payload: {
-    gameId: number;
+    gameId: ID;
     userName: string;
 }) => Promise<GameInfoAndUserProgress>;

package/dist/user/getUserClaims.d.ts

@@ -15,7 +15,7 @@ import type { UserClaims } from "./models";
  * ```
  * const userClaims = await getUserClaims(
  *   authorization,
- *   { userName: "xelnia" }
+ *   { userName: "Jamiras" }
  * );
  * ```
  *

package/dist/user/getUserCompletedGames.d.ts

@@ -5,7 +5,7 @@ import type { UserCompletedGames } from "./models";
  * about the games a given user has played. It returns two
  * entries per each game: one for the softcore completion and
  * one for the hardcore completion. These are designated by
- * the `hardcoreMode` property on the completion object.
+ * the `hardcoreMode` property on each completion object.
  *
  * @param authorization An object containing your userName and webApiKey.
  * This can be constructed with `buildAuthorization()`.

package/dist/user/getUserGameRankAndScore.d.ts

@@ -1,3 +1,4 @@
+import type { ID } from "../utils/internal";
 import type { AuthObject } from "../utils/public";
 import type { UserGameRankAndScore } from "./models";
 /**
@@ -39,6 +40,6 @@ import type { UserGameRankAndScore } from "./models";
  * ```
  */
 export declare const getUserGameRankAndScore: (authorization: AuthObject, payload: {
-    gameId: number;
+    gameId: ID;
     userName: string;
 }) => Promise<UserGameRankAndScore>;

package/dist/user/getUserPoints.d.ts

@@ -7,7 +7,7 @@ import type { UserPoints } from "./models";
  * @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.
+ * @param payload.userName The user for which to retrieve the point totals for.
  *
  * @example
  * ```

package/dist/user/getUserProgress.d.ts

@@ -1,15 +1,16 @@
+import type { ID } from "../utils/internal";
 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.
+ * progress on a given list 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
+ * @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.
  *
@@ -17,7 +18,7 @@ import type { UserProgress } from "./models";
  * ```
  * const userProgress = await getUserProgress(
  *   authorization,
- *   { userName: "xelnia", gameIds: [14402, 1] }
+ *   { userName: "xelnia", gameIds: [1, 14402] }
  * );
  * ```
  *
@@ -45,5 +46,5 @@ import type { UserProgress } from "./models";
  */
 export declare const getUserProgress: (authorization: AuthObject, payload: {
     userName: string;
-    gameIds: Array<number | string>;
+    gameIds: ID[];
 }) => Promise<UserProgress>;

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

@@ -1,4 +1,4 @@
-export declare type DatedUserAchievement = {
+export type DatedUserAchievement = {
     date: string;
     hardcoreMode: boolean;
     achievementId: number;

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

@@ -15,5 +15,5 @@ interface DatedUserAchievementResponseEntity {
     BadgeURL: string;
     GameURL: string;
 }
-export declare type DatedUserAchievementsResponse = DatedUserAchievementResponseEntity[];
+export type DatedUserAchievementsResponse = DatedUserAchievementResponseEntity[];
 export {};

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

@@ -1,5 +1,5 @@
 import type { GameExtended, GameExtendedAchievementEntity } from "../../game/models";
-export declare type GameExtendedAchievementEntityWithUserProgress = GameExtendedAchievementEntity & {
+export type GameExtendedAchievementEntityWithUserProgress = GameExtendedAchievementEntity & {
     dateEarned: string;
     dateEarnedHardcore: string;
 };

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

@@ -1,6 +1,6 @@
 import type { GameExtendedRawAchievementEntity, GetGameExtendedResponse } from "../../game/models";
-declare type GetGameExtendedResponseWithoutClaims = Omit<GetGameExtendedResponse, "Claims">;
-declare type GameExtendedRawAchievementEntityWithUserProgress = GameExtendedRawAchievementEntity & {
+type GetGameExtendedResponseWithoutClaims = Omit<GetGameExtendedResponse, "Claims">;
+type GameExtendedRawAchievementEntityWithUserProgress = GameExtendedRawAchievementEntity & {
     DateEarned: string;
     DateEarnedHardcore: string;
 };

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

@@ -9,5 +9,5 @@ interface UserCompletedGamesResponseEntity {
     PctWon: string;
     HardcoreMode: "0" | "1";
 }
-export declare type GetUserCompletedGamesResponse = UserCompletedGamesResponseEntity[];
+export type GetUserCompletedGamesResponse = UserCompletedGamesResponseEntity[];
 export {};

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

@@ -4,5 +4,5 @@ interface UserGameRankAndScoreResponseEntity {
     LastAward: string;
     UserRank: string;
 }
-export declare type GetUserGameRankAndScoreResponse = UserGameRankAndScoreResponseEntity[];
+export type GetUserGameRankAndScoreResponse = UserGameRankAndScoreResponseEntity[];
 export {};

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

@@ -6,5 +6,5 @@ interface UserProgressResponseEntity {
     NumAchievedHardcore: number | string;
     ScoreAchievedHardcore: number | string;
 }
-export declare type GetUserProgressResponse = Record<`${number}`, UserProgressResponseEntity>;
+export type GetUserProgressResponse = Record<`${number}`, UserProgressResponseEntity>;
 export {};

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

@@ -5,6 +5,7 @@ interface UserRecentlyPlayedGameResponseEntity {
     Title: string;
     ImageIcon: string;
     LastPlayed: string;
+    MyVote: "1" | "2" | "3" | "4" | "5" | null;
     NumPossibleAchievements: string;
     PossibleScore: string;
     NumAchieved: string | number;
@@ -12,5 +13,5 @@ interface UserRecentlyPlayedGameResponseEntity {
     NumAchievedHardcore: string | number;
     ScoreAchievedHardcore: string | number;
 }
-export declare type GetUserRecentlyPlayedGamesResponse = UserRecentlyPlayedGameResponseEntity[];
+export type GetUserRecentlyPlayedGamesResponse = UserRecentlyPlayedGameResponseEntity[];
 export {};

package/dist/user/models/user-claims-response.model.d.ts

@@ -15,5 +15,5 @@ interface UserClaimsResponseEntity {
     Updated: string;
     MinutesLeft: string;
 }
-export declare type GetUserClaimsResponse = UserClaimsResponseEntity[];
+export type GetUserClaimsResponse = UserClaimsResponseEntity[];
 export {};

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

@@ -15,5 +15,5 @@ interface UserClaim {
     updated: string;
     minutesLeft: number;
 }
-export declare type UserClaims = UserClaim[];
+export type UserClaims = UserClaim[];
 export {};

package/dist/user/models/user-completed-games.model.d.ts

@@ -1,4 +1,4 @@
-interface UserCompletedGame {
+export interface UserCompletedGame {
     gameId: number;
     title: string;
     imageIcon: string;
@@ -9,5 +9,4 @@ interface UserCompletedGame {
     pctWon: number;
     hardcoreMode: boolean;
 }
-export declare type UserCompletedGames = UserCompletedGame[];
-export {};
+export type UserCompletedGames = UserCompletedGame[];

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

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

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

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

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

@@ -1,10 +1,11 @@
-interface UserRecentlyPlayedGameEntity {
+export interface UserRecentlyPlayedGameEntity {
     gameId: number;
     consoleId: number;
     consoleName: string;
     title: string;
     imageIcon: string;
     lastPlayed: string;
+    myVote: 1 | 2 | 3 | 4 | 5 | null;
     numPossibleAchievements: number;
     possibleScore: number;
     numAchieved: number;
@@ -12,5 +13,4 @@ interface UserRecentlyPlayedGameEntity {
     numAchievedHardcore: number;
     scoreAchievedHardcore: number;
 }
-export declare type UserRecentlyPlayedGames = UserRecentlyPlayedGameEntity[];
-export {};
+export type UserRecentlyPlayedGames = UserRecentlyPlayedGameEntity[];

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

@@ -1,4 +1,4 @@
-interface RecentlyPlayedGameEntity {
+export interface RecentlyPlayedGameEntity {
     gameId: number;
     consoleId: number;
     consoleName: string;
@@ -6,7 +6,7 @@ interface RecentlyPlayedGameEntity {
     imageIcon: string;
     lastPlayed: string;
 }
-interface LastActivityEntity {
+export interface LastActivityEntity {
     id: number;
     timestamp: string;
     lastupdate: string;
@@ -15,7 +15,7 @@ interface LastActivityEntity {
     data: string;
     data2: string;
 }
-interface LastGameEntity {
+export interface LastGameEntity {
     id: number;
     title: string;
     consoleId: number;
@@ -33,7 +33,7 @@ interface LastGameEntity {
     consoleName: string;
     richPresencePatch: string;
 }
-interface AwardedGameEntity {
+export interface AwardedGameEntity {
     numPossibleAchievements: number;
     possibleScore: number;
     numAchieved: number;
@@ -41,7 +41,7 @@ interface AwardedGameEntity {
     numAchievedHardcore: number;
     scoreAchievedHardcore: number;
 }
-interface ExtendedRecentAchievementEntity {
+export interface ExtendedRecentAchievementEntity {
     id: number;
     gameId: number;
     gameTitle: string;
@@ -80,4 +80,3 @@ export interface UserSummary {
     totalRanked: number;
     status: string;
 }
-export {};

package/dist/utils/internal/id.model.d.ts

@@ -0,0 +1 @@
+export type ID = string | number;

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

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

package/package.json

@@ -8,7 +8,7 @@
     "raweb",
     "retro gaming"
   ],
-  "version": "1.0.0-rc.0",
+  "version": "1.0.0-rc.2",
   "main": "dist/index.js",
   "module": "dist/api.esm.js",
   "typings": "dist/index.d.ts",
@@ -36,42 +36,47 @@
     "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"
+    "start": "dts watch",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
   },
   "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",
+    "@commitlint/cli": "^17.4.2",
+    "@commitlint/config-conventional": "^17.4.2",
+    "@digitak/esrun": "^3.2.19",
+    "@size-limit/preset-small-lib": "^8.1.2",
+    "@swc/core": "^1.3.30",
+    "@swc/jest": "^0.2.24",
+    "@tsconfig/recommended": "^1.0.2",
+    "@types/jest": "^29.4.0",
+    "@typescript-eslint/eslint-plugin": "^5.49.0",
+    "@typescript-eslint/parser": "^5.49.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",
+    "dts-cli": "^1.6.3",
+    "eslint": "^8.33.0",
+    "eslint-config-prettier": "^8.6.0",
+    "eslint-import-resolver-typescript": "^3.5.3",
+    "eslint-plugin-import": "^2.27.5",
+    "eslint-plugin-simple-import-sort": "^10.0.0",
+    "eslint-plugin-sonarjs": "^0.18.0",
+    "eslint-plugin-unicorn": "^45.0.2",
     "husky": "^4.3.8",
-    "jest": "^29.2.1",
-    "msw": "^0.47.4",
-    "prettier": "2.7.1",
+    "jest": "^29.4.1",
+    "msw": "^1.0.0",
+    "prettier": "2.8.3",
     "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": "^8.1.2",
+    "tslib": "^2.5.0",
+    "type-fest": "^3.5.3",
+    "typescript": "^4.9.4",
+    "vitepress": "^1.0.0-alpha.43",
+    "vue": "^3.2.45"
   },
   "size-limit": [
     {

package/src/__playground.ts

@@ -3,27 +3,40 @@
  * TO DIRECTLY IMPACT EVERY DEV WORKING ON THE PROJECT.
  *
  * Use this file to test and experiment with changes to the project.
+ * If changes to this file land in a PR, you probably did something wrong.
  */
 
-// If you can't import what you want from "./index", users won't
-// be able to import it either.
-// import { buildAuthorization, getAchievementCount } from "./index";
+// ---
+
+/**
+ * "./index" is the library's single public-facing export.
+ * In other words, if you're not able to import what you want
+ * to use from "./index", no one who uses the package will be
+ * able to either.
+ */
+import { buildAuthorization, getAchievementCount } from "./index";
+
+// MODIFY THESE VALUES.
+const userName = "myUserName";
+const webApiKey = "myWebApiKey";
 
 const main = async () => {
-  console.log("retroachievements-api-js playground is running.");
-  console.log(""); // newline
+  console.log("🚀  @retroachievements/api playground is running.\n");
 
   // -- Start testing stuff here --
 
-  /*
-  const authorization = buildAuthorization({
-    userName: 'myUserName',
-    webApiKey: 'myWebApiKey'
-  })
+  if (userName === "myUserName" || webApiKey === "myWebApiKey") {
+    console.error(
+      "⛔️  ERROR: In __playground.ts, modify the userName and webApiKey variables to match your RA credentials.\n"
+    );
+  }
+
+  const authorization = buildAuthorization({ userName, webApiKey });
 
-  const achievementCount = await getAchievementCount(authorization, 14_402);
+  const achievementCount = await getAchievementCount(authorization, {
+    gameId: 14_402
+  });
   console.log(achievementCount);
-  */
 };
 
 main();