refactor: simplify authorization API

README.md

@@ -45,29 +45,20 @@ Learn how to authenticate and start pulling data from RetroAchievements on our d
 
 To use any endpoint function in the API, you must first be authorized by RetroAchievements. Fortunately, this is a fairly straightforward process.
 
-1. Visit [your control panel](https://retroachievements.org/controlpanel.php) on the RA website.
+1. Visit the [settings page](https://retroachievements.org/settings) on the RA website.
 
 2. Find the "Keys" section on the page. Copy the web API key value. **Do not expose your API key anywhere publicly.**
 
-3. You can now create your authorization object using your web API key.
+3. You now have all you need to use any function from the API. Each function takes this web API key as its first argument. Here's an example:
 
 ```ts
-import { buildAuthorization } from "@retroachievements/api";
+import { getGame } from "@retroachievements/api";
 
-const username = "<your username on RA>";
 const webApiKey = "<your web API key>";
 
-const authorization = buildAuthorization({ username, webApiKey });
-```
-
-4. You now have all you need to use any function in the API. Each function takes this authorization object as its first argument. Here's an example:
-
-```ts
-import { getGame } from "@retroachievements/api";
-
 // This returns basic metadata about the game on this page:
 // https://retroachievements.org/game/14402
-const game = await getGame(authorization, { gameId: 14402 });
+const game = await getGame(webApiKey, { gameId: 14402 });
 ```
 
 ## API

package.json

@@ -38,7 +38,7 @@
     "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": "vitest run",
+    "test": "vitest run --reporter=dot",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "verify": "pnpm format:check && pnpm lint && pnpm test:coverage && pnpm build",

src/achievement/getAchievementUnlocks.ts

@@ -5,7 +5,7 @@ import {
   call,
   serializeProperties,
 } from "../utils/internal";
-import type { AuthObject } from "../utils/public";
+import type { ApiAuthorization } from "../utils/public";
 import type {
   AchievementUnlocksMetadata,
   GetAchievementUnlocksResponse,
@@ -15,8 +15,7 @@ import type {
  * A call to this function will retrieve a list of users who
  * have earned a given achievement, targeted by the achievement's ID.
  *
- * @param authorization An object containing your username and webApiKey.
- * This can be constructed with `buildAuthorization()`.
+ * @param authorization Your web API key retrieved from retroachievements.org/settings.
  *
  * @param payload.achievementId The target achievement we want to
  * retrieve the unlocks list for. If unknown, this can be found
@@ -31,7 +30,7 @@ import type {
  * @example
  * ```
  * const achievementUnlocks = await getAchievementUnlocks(
- *   authorization,
+ *   webApiKey,
  *   { achievementId: 13876 }
  * );
  * ```
@@ -50,7 +49,7 @@ import type {
  * ```
  */
 export const getAchievementUnlocks = async (
-  authorization: AuthObject,
+  authorization: ApiAuthorization,
   payload: { achievementId: ID; offset?: number; count?: number }
 ): Promise<AchievementUnlocksMetadata> => {
   const { achievementId, offset, count } = payload;

src/console/getConsoleIds.ts

@@ -4,16 +4,15 @@ import {
   call,
   serializeProperties,
 } from "../utils/internal";
-import type { AuthObject } from "../utils/public";
+import type { ApiAuthorization } from "../utils/public";
 import type { FetchedSystem, GetConsoleIdsResponse } from "./models";
 
 /**
  * A call to this function will retrieve the complete list
  * of console ID and name pairs on the RetroAchievements.org
  * platform.
  *
- * @param authorization An object containing your username and webApiKey.
- * This can be constructed with `buildAuthorization()`.
+ * @param authorization Your web API key retrieved from retroachievements.org/settings.
  *
  * @param payload.shouldOnlyRetrieveActiveSystems If true, only systems that
  * officially support achievements will be returned.
@@ -39,7 +38,7 @@ import type { FetchedSystem, GetConsoleIdsResponse } from "./models";
  * ```
  */
 export const getConsoleIds = async (
-  authorization: AuthObject,
+  authorization: ApiAuthorization,
   payload?: {
     shouldOnlyRetrieveActiveSystems: boolean;
     shouldOnlyRetrieveGameSystems: boolean;

src/console/getGameList.ts

@@ -5,15 +5,14 @@ import {
   call,
   serializeProperties,
 } from "../utils/internal";
-import type { AuthObject } from "../utils/public";
+import type { ApiAuthorization } from "../utils/public";
 import type { GameList, GetGameListResponse } from "./models";
 /**
  * A call to this function will retrieve the complete list
  * of games for a specified console on the RetroAchievements.org
  * platform.
  *
- * @param authorization An object containing your username and webApiKey.
- * This can be constructed with `buildAuthorization()`.
+ * @param authorization Your web API key retrieved from retroachievements.org/settings.
  *
  * @param payload.consoleId The unique console ID to retrieve a list of
  * games from. The list of consoleIds can be retrieved using the `getConsoleIds()`
@@ -53,7 +52,7 @@ import type { GameList, GetGameListResponse } from "./models";
  * ```
  */
 export const getGameList = async (
-  authorization: AuthObject,
+  authorization: ApiAuthorization,
   payload: {
     consoleId: ID;
     shouldOnlyRetrieveGamesWithAchievements?: boolean;

src/feed/getAchievementOfTheWeek.ts

@@ -4,7 +4,7 @@ import {
   call,
   serializeProperties,
 } from "../utils/internal";
-import type { AuthObject } from "../utils/public";
+import type { ApiAuthorization } from "../utils/public";
 import type {
   AchievementOfTheWeek,
   GetAchievementOfTheWeekResponse,
@@ -14,8 +14,7 @@ import type {
  * A call to this function will retrieve comprehensive
  * metadata about the current Achievement of the Week.
  *
- * @param authorization An object containing your username and webApiKey.
- * This can be constructed with `buildAuthorization()`.
+ * @param authorization Your web API key retrieved from retroachievements.org/settings.
  *
  * @example
  * ```
@@ -59,7 +58,7 @@ import type {
  * ```
  */
 export const getAchievementOfTheWeek = async (
-  authorization: AuthObject
+  authorization: ApiAuthorization
 ): Promise<AchievementOfTheWeek> => {
   const url = buildRequestUrl(
     apiBaseUrl,

src/feed/getActiveClaims.ts

@@ -4,15 +4,14 @@ import {
   call,
   serializeProperties,
 } from "../utils/internal";
-import type { AuthObject } from "../utils/public";
+import type { ApiAuthorization } from "../utils/public";
 import type { GetSetClaimsResponse, SetClaim } from "./models";
 
 /**
  * A call to this function returns information about all
  * (1000 max) active set claims.
  *
- * @param authorization An object containing your username and webApiKey.
- * This can be constructed with `buildAuthorization()`.
+ * @param authorization Your web API key retrieved from retroachievements.org/settings.
  *
  * @example
  * ```
@@ -45,7 +44,7 @@ import type { GetSetClaimsResponse, SetClaim } from "./models";
  * ```
  */
 export const getActiveClaims = async (
-  authorization: AuthObject
+  authorization: ApiAuthorization
 ): Promise<SetClaim[]> => {
   const url = buildRequestUrl(
     apiBaseUrl,

src/feed/getClaims.ts

@@ -4,13 +4,30 @@ import {
   call,
   serializeProperties,
 } from "../utils/internal";
-import type { AuthObject } from "../utils/public";
+import type { ApiAuthorization } from "../utils/public";
 import type { GetSetClaimsResponse, SetClaim } from "./models";
 
 type ClaimKind = "completed" | "dropped" | "expired";
 
+/**
+ * A call to this function will retrieve a list of achievement set claims.
+ *
+ * @param authorization Your web API key retrieved from retroachievements.org/settings.
+ *
+ * @param payload.claimKind The specific kind of claims you'd like to retrieve a list of.
+ *
+ * @example
+ * ```
+ * const claims = await getClaims(
+ *   authorization,
+ *   { claimKind: "completed" }
+ * );
+ * ```
+ *
+ * @returns An array containing all the specified claims.
+ */
 export const getClaims = async (
-  authorization: AuthObject,
+  authorization: ApiAuthorization,
   payload: { claimKind: ClaimKind }
 ): Promise<SetClaim[]> => {
   const { claimKind } = payload;

src/feed/getRecentGameAwards.ts

@@ -4,15 +4,14 @@ import {
   call,
   serializeProperties,
 } from "../utils/internal";
-import type { AuthObject, AwardKind } from "../utils/public";
+import type { ApiAuthorization, AwardKind } from "../utils/public";
 import type { GetRecentGameAwardsResponse, RecentGameAwards } from "./models";
 
 /**
  * A call to this function will retrieve all recently granted game
  * awards across the site's userbase.
  *
- * @param authorization An object containing your username and webApiKey.
- * This can be constructed with `buildAuthorization()`.
+ * @param authorization Your web API key retrieved from retroachievements.org/settings.
  *
  * @param payload.startDate The date to fetch awards from.
  *
@@ -50,7 +49,7 @@ import type { GetRecentGameAwardsResponse, RecentGameAwards } from "./models";
  * ```
  */
 export const getRecentGameAwards = async (
-  authorization: AuthObject,
+  authorization: ApiAuthorization,
   payload?: Partial<{
     startDate: string;
     offset: number;

src/feed/getTopTenUsers.ts

@@ -1,5 +1,5 @@
 import { apiBaseUrl, buildRequestUrl, call } from "../utils/internal";
-import type { AuthObject } from "../utils/public";
+import type { ApiAuthorization } from "../utils/public";
 import type {
   GetTopTenUsersResponse,
   TopTenUsers,
@@ -10,8 +10,7 @@ import type {
  * 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()`.
+ * @param authorization Your web API key retrieved from retroachievements.org/settings.
  *
  * @example
  * ```
@@ -28,7 +27,7 @@ import type {
  * ```
  */
 export const getTopTenUsers = async (
-  authorization: AuthObject
+  authorization: ApiAuthorization
 ): Promise<TopTenUsers> => {
   const url = buildRequestUrl(
     apiBaseUrl,

src/game/getAchievementCount.ts

@@ -5,15 +5,14 @@ import {
   call,
   serializeProperties,
 } from "../utils/internal";
-import type { AuthObject } from "../utils/public";
+import type { ApiAuthorization } from "../utils/public";
 import type { AchievementCount, GetAchievementCountResponse } from "./models";
 
 /**
  * A call to this function will retrieve the list of
  * achievement IDs for a game, targeted by game ID.
  *
- * @param authorization An object containing your username and webApiKey.
- * This can be constructed with `buildAuthorization()`.
+ * @param authorization Your web API key retrieved from retroachievements.org/settings.
  *
  * @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
@@ -35,7 +34,7 @@ import type { AchievementCount, GetAchievementCountResponse } from "./models";
  * ```
  */
 export const getAchievementCount = async (
-  authorization: AuthObject,
+  authorization: ApiAuthorization,
   payload: { gameId: ID }
 ): Promise<AchievementCount> => {
   const { gameId } = payload;

src/game/getAchievementDistribution.ts

@@ -1,6 +1,6 @@
 import type { ID } from "../utils/internal";
 import { apiBaseUrl, buildRequestUrl, call } from "../utils/internal";
-import type { AuthObject } from "../utils/public";
+import type { ApiAuthorization } from "../utils/public";
 import type {
   AchievementDistributionFlags,
   GetAchievementDistributionResponse,
@@ -11,8 +11,7 @@ import type {
  * of the number of players who have earned a specific
  * number of achievements for a given game ID.
  *
- * @param authorization An object containing your username and webApiKey.
- * This can be constructed with `buildAuthorization()`.
+ * @param authorization Your web API key retrieved from retroachievements.org/settings.
  *
  * @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
@@ -57,7 +56,7 @@ import type {
  * ```
  */
 export const getAchievementDistribution = async (
-  authorization: AuthObject,
+  authorization: ApiAuthorization,
   payload: {
     gameId: ID;
     flags?: AchievementDistributionFlags;

src/game/getGame.ts

@@ -5,15 +5,14 @@ import {
   call,
   serializeProperties,
 } from "../utils/internal";
-import type { AuthObject } from "../utils/public";
+import type { ApiAuthorization } from "../utils/public";
 import type { Game, GetGameResponse } from "./models";
 
 /**
  * A call to this function will retrieve basic metadata about
  * a game, targeted via its unique ID.
  *
- * @param authorization An object containing your username and webApiKey.
- * This can be constructed with `buildAuthorization()`.
+ * @param authorization Your web API key retrieved from retroachievements.org/settings.
  *
  * @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
@@ -52,7 +51,7 @@ import type { Game, GetGameResponse } from "./models";
  * ```
  */
 export const getGame = async (
-  authorization: AuthObject,
+  authorization: ApiAuthorization,
   payload: { gameId: ID }
 ): Promise<Game> => {
   const { gameId } = payload;

src/game/getGameExtended.ts

@@ -5,15 +5,14 @@ import {
   call,
   serializeProperties,
 } from "../utils/internal";
-import type { AuthObject } from "../utils/public";
+import type { ApiAuthorization } from "../utils/public";
 import type { GameExtended, GetGameExtendedResponse } from "./models";
 
 /**
  * A call to this function will retrieve extended metadata
  * about a game, targeted via its unique ID.
  *
- * @param authorization An object containing your username and webApiKey.
- * This can be constructed with `buildAuthorization()`.
+ * @param authorization Your web API key retrieved from retroachievements.org/settings.
  *
  * @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
@@ -72,7 +71,7 @@ import type { GameExtended, GetGameExtendedResponse } from "./models";
  * ```
  */
 export const getGameExtended = async (
-  authorization: AuthObject,
+  authorization: ApiAuthorization,
   payload: { gameId: ID; isRequestingUnofficialAchievements?: boolean }
 ): Promise<GameExtended> => {
   const { gameId, isRequestingUnofficialAchievements } = payload;