diff --git a/docs/.vitepress/config.js b/docs/.vitepress/config.js deleted file mode 100644 index cbb7993..0000000 --- a/docs/.vitepress/config.js +++ /dev/null @@ -1,221 +0,0 @@ -export default { - title: "RetroAchievements API", - description: - "The official JavaScript library for getting achievement, user, and game data from RetroAchievements.", - - themeConfig: { - siteTitle: "@retroachievements/api", - logo: "./favicon.webp", - - algolia: { - appId: "3QMK5TQHQC", - apiKey: "a5d33ec313db5c671171ca35d3de3cea", - indexName: "retroachievements-api-js" - }, - - socialLinks: [ - { - icon: "github", - link: "https://github.com/RetroAchievements/api-js" - }, - { - icon: "discord", - link: "https://discord.gg/dq2E4hE" - } - ], - - nav: [{ text: "Quick Start", link: "/getting-started" }], - - sidebar: [ - { - text: "About", - link: "/" - }, - { - text: "Getting Started", - link: "/getting-started" - }, - { - text: "Feed", - collapsible: true, - items: [ - { - text: "Achievement of the Week", - link: "/v1/feed/get-achievement-of-the-week" - }, - { - text: "Claims", - link: "/v1/feed/get-claims" - }, - { - text: "Active Claims", - link: "/v1/feed/get-active-claims" - }, - { - text: "Top Ten Users", - link: "/v1/feed/get-top-ten-users" - } - ] - }, - { - text: "Users", - collapsible: true, - items: [ - { - text: "Recent Achievements", - link: "/v1/users/get-user-recent-achievements" - }, - { - text: "Achievements Earned Between Days", - link: "/v1/users/get-achievements-earned-between" - }, - { - text: "Achievements Earned On Day", - link: "/v1/users/get-achievements-earned-on-day" - }, - { - text: "Progress for Game with Game Info", - link: "/v1/users/get-game-info-and-user-progress" - }, - { - text: "Awards / Badges", - link: "/v1/users/get-user-awards" - }, - { - text: "Set Claims", - link: "/v1/users/get-user-claims" - }, - { - text: "Completed Games", - link: "/v1/users/get-user-completed-games" - }, - { - text: "Rank and Score for Game", - link: "/v1/users/get-user-game-rank-and-score" - }, - { - text: "Point Totals", - link: "/v1/users/get-user-points" - }, - { - text: "Progress for Multiple Games", - link: "/v1/users/get-user-progress" - }, - { - text: "Recently Played Games", - link: "/v1/users/get-user-recently-played-games" - }, - { - text: "User Summary", - link: "/v1/users/get-user-summary" - } - ] - }, - { - text: "Games", - collapsible: true, - items: [ - { - text: "Achievement Count", - link: "/v1/games/get-achievement-count" - }, - { - text: "Achievement Distribution", - link: "/v1/games/get-achievement-distribution" - }, - { - text: "Game Info", - link: "/v1/games/get-game" - }, - { - text: "Extended Game Info", - link: "/v1/games/get-game-extended" - }, - { - text: "Game Rank and Score", - link: "/v1/games/get-game-rank-and-score" - }, - { - text: "Game Rating", - link: "/v1/games/get-game-rating" - } - ] - }, - { - text: "Consoles", - collapsible: true, - items: [ - { - text: "Get All IDs", - link: "/v1/consoles/get-console-ids" - }, - { - text: "Get All Games", - link: "/v1/consoles/get-game-list" - } - ] - }, - { - text: "Achievements", - collapsible: true, - items: [ - { - text: "Unlocks List", - link: "/v1/achievements/get-achievement-unlocks" - } - ] - }, - { - text: "Tickets", - collapsible: true, - items: [ - { - text: "Get Ticket by ID", - link: "/v1/tickets/get-ticket-by-id" - }, - { - text: "Get Most Ticketed Games", - link: "/v1/tickets/get-most-ticketed-games" - }, - { - text: "Get Most Recent Tickets", - link: "/v1/tickets/get-most-recent-tickets" - }, - { - text: "Get Game Ticket Stats", - link: "/v1/tickets/get-game-ticket-stats" - }, - { - text: "Get Developer Ticket Stats", - link: "/v1/tickets/get-developer-ticket-stats" - }, - { - tet: "Get Achievement Ticket Stats", - link: "/v1/tickets/get-achievement-ticket-stats" - } - ] - }, - { - text: "Utils", - collapsible: true, - items: [ - { - text: "buildAuthorization()", - link: "/v1/utils/build-authorization" - } - ] - } - ], - - editLink: { - pattern: - "https://github.com/RetroAchievements/api-js/edit/main/docs/:path", - text: "Edit this page on GitHub" - }, - - footer: { - message: "Released under the MIT license.", - copyright: "Copyright © 2023–Present RetroAchievements." - } - } -}; diff --git a/docs/getting-started.md b/docs/getting-started.md deleted file mode 100644 index 6473a2c..0000000 --- a/docs/getting-started.md +++ /dev/null @@ -1,56 +0,0 @@ -# Getting Started - -First, we'll install the package. Then, we'll create an authentication object. After these steps are completed, you are able to use any function provided by the library. - -## Quick Start - -Install the package: - -::: code-group - -```bash [npm] -npm install --save @retroachievements/api -``` - -```bash [yarn] -yarn add @retroachievements/api -``` - -::: - -You will need to be authenticated to use the official RetroAchievements API. To authenticate, follow these steps: - -1. Visit [your control panel](https://retroachievements.org/controlpanel.php) on the RA website. - -
- -2. Find the "Keys" section on the page. Copy the web API key value. - -::: warning -Store your API key as though it is a secret, like a password. Avoid checking in your API key with your code. -::: - -
- -3. You can now create your authorization object using your web API key. - -```ts -import { buildAuthorization } from "@retroachievements/api"; - -const userName = ""; -const webApiKey = ""; - -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 }); -``` diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index 42b3b9f..0000000 --- a/docs/index.md +++ /dev/null @@ -1,30 +0,0 @@ -# About - -@retroachievements/api is the official RetroAchievements JavaScript/TypeScript library for fetching achievement, user, and game data from RetroAchievements. - -## Features - -- Modular by design, and supports tree-shaking. -- Officially-supported, aligns 1:1 with the RAWeb API. -- Backwards-compatible, easy migration path to API v2. -- Supports Node environments (14 and above). -- Ships with TypeScript support and types. -- Correctly maps types and properties from RAWeb PHP calls. -- Small, <3Kb. - -## Getting started - -Are you starting from scratch? [Follow the starter tutorial](/getting-started). - -## Contact and support - -- Create a [GitHub issue](https://github.com/RetroAchievements/api-js/issues) for bug reports, feature requests, or questions. -- Add a [⭐️ star on GitHub](https://github.com/RetroAchievements/api-js) to support the project! - -## How to Contribute - -Check out [CONTRIBUTING.md](https://github.com/RetroAchievements/api-js/blob/main/CONTRIBUTING.md) for how to get started. - -## License - -This project is licensed under the [MIT license](https://github.com/RetroAchievements/api-js/blob/main/LICENSE.md). diff --git a/docs/public/favicon.webp b/docs/public/favicon.webp deleted file mode 100644 index 566f56d..0000000 Binary files a/docs/public/favicon.webp and /dev/null differ diff --git a/docs/v1/achievements/get-achievement-unlocks.md b/docs/v1/achievements/get-achievement-unlocks.md deleted file mode 100644 index 125a452..0000000 --- a/docs/v1/achievements/get-achievement-unlocks.md +++ /dev/null @@ -1,41 +0,0 @@ -# getAchievementUnlocks - -A call to this function will retrieve a list of users who have earned an achievement, targeted by the achievement's ID. - -## Examples - -```ts -import { getAchievementUnlocks } from "@retroachievements/api"; - -const achievementUnlocks = await getAchievementUnlocks(authorization, { - achievementId: 13876 -}); -``` - -## Returns - -```json -[ - { - "user": "Podgicus0305", - "raPoints": 15544, - "dateAwarded": "2022-07-12 19:06:34", - "hardcoreMode": true - } - // ... -] -``` - -## Parameters - -| Name | Type | Description | -| :-------------- | :------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `authorization` | [`AuthObject`](/v1/data-models/auth-object) | An object that must contain a `userName` and a `webApiKey`. See [this page](/getting-started) for how to create this object. | -| `achievementId` | `string` or `number` | The target achievement we want to retrieve the unlocks list for. If you're not sure of this, it can be found by navigating to the achievement's page on the RetroAchievements.org website and copying the number at the end of the URL. | -| `count` | `number?` | Optional. How many unlock records to return. The default is 50. The max is 500. | -| `offset` | `number?` | Optional. How many unlock records to skip. Useful for pagination. Zero-indexed. The default is 0. | - -## Source - -[@retroachievements/api, getAchievementUnlocks.ts](https://github.dev/RetroAchievements/api-js/blob/main/src/achievement/getAchievementUnlocks.ts) -[RAWeb, API_GetAchievementUnlocks.php](https://github.dev/RetroAchievements/RAWeb/blob/master/public/API/API_GetAchievementUnlocks.php) diff --git a/docs/v1/consoles/get-console-ids.md b/docs/v1/consoles/get-console-ids.md deleted file mode 100644 index 2e4617a..0000000 --- a/docs/v1/consoles/get-console-ids.md +++ /dev/null @@ -1,33 +0,0 @@ -# getConsoleIds - -A call to this function will retrieve the complete list of console ID and name pairs on the RetroAchievements.org platform. - -## Examples - -```ts -import { getConsoleIds } from "@retroachievements/api"; - -const consoleIds = await getConsoleIds(authorization); -``` - -## Returns - -```json -[ - { "id": 1, "name": "Mega Drive" }, - { "id": 2, "name": "Nintendo 64" }, - { "id": 3, "name": "SNES" } - // ... -] -``` - -## Parameters - -| Name | Type | Description | -| :-------------- | :------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------- | -| `authorization` | [`AuthObject`](/v1/data-models/auth-object) | An object that must contain a `userName` and a `webApiKey`. See [this page](/getting-started) for how to create this object. | - -## Source - -[@retroachievements/api, getConsoleIds.ts](https://github.dev/RetroAchievements/api-js/blob/main/src/console/getConsoleIds.ts) -[RAWeb, API_GetConsoleIDs.php](https://github.dev/RetroAchievements/RAWeb/blob/master/public/API/API_GetConsoleIDs.php) diff --git a/docs/v1/consoles/get-game-list.md b/docs/v1/consoles/get-game-list.md deleted file mode 100644 index 8d82fdc..0000000 --- a/docs/v1/consoles/get-game-list.md +++ /dev/null @@ -1,50 +0,0 @@ -# getGameList - -A call to this function will retrieve the complete list of games for a specified console on the RetroAchievements.org platform, targeted by the console ID. If you do not know the console ID you're looking for, try using the [`getConsoleIds()`](/v1/consoles/get-console-ids) function. - -## Examples - -```ts -import { getGameList } from "@retroachievements/api"; - -const gameList = await getGameList(authorization, { - consoleId: 1, - shouldOnlyRetrieveGamesWithAchievements: true, - shouldRetrieveGameHashes: true -}); -``` - -## Returns - -```json -[ - { - "title": "Elemental Master", - "id": 4247, - "consoleId": 1, - "consoleName": "Mega Drive", - "imageIcon": "/Images/048245.png", - "numAchievements": 44, - "numLeaderboards": 0, - "points": 500, - "dateModified": "2021-12-09 17:05:39", - "forumTopicId": 1972, - "hashes": ["32e1a15161ef1f070b023738353bde51"] - } - // ... -] -``` - -## Parameters - -| Name | Type | Description | -| :---------------------------------------- | :------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------- | -| `authorization` | [`AuthObject`](/v1/data-models/auth-object) | An object that must contain a `userName` and a `webApiKey`. See [this page](/getting-started) for how to create this object. | -| `consoleId` | `string` or `number` | The unique console ID to retrieve a list of games from. This can be retrieved using the [`getConsoleIds()`](/v1/consoles/get-console-ids) function. | -| `shouldOnlyRetrieveGamesWithAchievements` | `boolean` | Optional. If truthy, will not return games that do not have achievements. | -| `shouldRetrieveGameHashes` | `boolean` | Optional. If truthy, will return valid hashes for game ROMs in a `string` array attached to each game in the list. | - -## Source - -[@retroachievements/api, getGameList.ts](https://github.dev/RetroAchievements/api-js/blob/main/src/console/getGameList.ts) -[RAWeb, API_GetGameList.php](https://github.dev/RetroAchievements/RAWeb/blob/master/public/API/API_GetGameList.php) diff --git a/docs/v1/data-models/auth-object.md b/docs/v1/data-models/auth-object.md deleted file mode 100644 index e69de29..0000000 diff --git a/docs/v1/feed/get-achievement-of-the-week.md b/docs/v1/feed/get-achievement-of-the-week.md deleted file mode 100644 index f5a05e5..0000000 --- a/docs/v1/feed/get-achievement-of-the-week.md +++ /dev/null @@ -1,54 +0,0 @@ -# getAchievementOfTheWeek - -A call to this function will retrieve comprehensive metadata about the current Achievement of the Week. - -## Examples - -```ts -import { getAchievementOfTheWeek } from "@retroachievements/api"; - -const achievementOfTheWeek = await getAchievementOfTheWeek(authorization); -``` - -## Returns - -```json -{ - "achievement": { - "id": "165062", - "title": "The True Hero", - "description": "Receive any Ending as Han [Normal or Hard]", - "points": "10", - "trueRatio": "22", - "author": "BigWeedSmokerMan", - "dateCreated": "2021-08-08 17:47:46", - "dateModified": "2021-08-09 12:20:05" - }, - "console": { "id": "39", "title": "Saturn" }, - "forumTopic": { "id": "14767" }, - "game": { "id": "14513", "title": "Guardian Heroes" }, - "startAt": "2022-10-10 00:00:00", - "totalPlayers": "219", - "unlocks": [ - { - "user": "Tirbaba2", - "rAPoints": "72", - "dateAwarded": "2022-10-10 01:42:19", - "hardcoreMode": "1" - } - // ... - ], - "unlocksCount": "40" -} -``` - -## Parameters - -| Name | Type | Description | -| :-------------- | :------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------- | -| `authorization` | [`AuthObject`](/v1/data-models/auth-object) | An object that must contain a `userName` and a `webApiKey`. See [this page](/getting-started) for how to create this object. | - -## Source - -[@retroachievements/api, getAchievementOfTheWeek.ts](https://github.dev/RetroAchievements/api-js/blob/main/src/feed/getAchievementOfTheWeek.ts) -[RAWeb, API_GetAchievementOfTheWeek.php](https://github.dev/RetroAchievements/RAWeb/blob/master/public/API/API_GetAchievementOfTheWeek.php) diff --git a/docs/v1/feed/get-active-claims.md b/docs/v1/feed/get-active-claims.md deleted file mode 100644 index 98902ff..0000000 --- a/docs/v1/feed/get-active-claims.md +++ /dev/null @@ -1,49 +0,0 @@ -# getActiveClaims - -A call to this function returns information about all (1000 max) active set claims. - -## Examples - -```ts -import { getActiveClaims } from "@retroachievements/api"; - -const activeClaims = await getActiveClaims(authorization); -``` - -## Returns - -```json -[ - { - "id": 7044, - "user": "blendedsea", - "gameId": 19212, - "gameTitle": "SpongeBob SquarePants: Battle for Bikini Bottom", - "gameIcon": "/Images/059776.png", - "consoleName": "PlayStation 2", - "consoleId": 22, - "claimType": 0, - "setType": 0, - "status": 0, - "extension": 0, - "special": 0, - "created": "2022-10-04 00:25:06", - "doneTime": "2023-01-04 00:25:06", - "updated": "2022-10-04 00:25:06", - "minutesLeft": 112523, - "userIsJrDev": false - } - // ... -] -``` - -## Parameters - -| Name | Type | Description | -| :-------------- | :------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------- | -| `authorization` | [`AuthObject`](/v1/data-models/auth-object) | An object that must contain a `userName` and a `webApiKey`. See [this page](/getting-started) for how to create this object. | - -## Source - -[@retroachievements/api, getActiveClaims.ts](https://github.dev/RetroAchievements/api-js/blob/main/src/feed/getActiveClaims.ts) -[RAWeb, API_GetActiveClaims.php](https://github.dev/RetroAchievements/RAWeb/blob/master/public/API/API_GetActiveClaims.php) diff --git a/docs/v1/feed/get-claims.md b/docs/v1/feed/get-claims.md deleted file mode 100644 index 7bce178..0000000 --- a/docs/v1/feed/get-claims.md +++ /dev/null @@ -1,50 +0,0 @@ -# getClaims - -A call to this function returns information about all (1000 max) set claims of a specified kind: completed, dropped, or expired. - -## Examples - -```ts -import { getClaims } from "@retroachievements/api"; - -const claims = await getClaims(authorization, { claimKind: "dropped" }); -``` - -## Returns - -```json -[ - { - "id": 7044, - "user": "blendedsea", - "gameId": 19212, - "gameTitle": "SpongeBob SquarePants: Battle for Bikini Bottom", - "gameIcon": "/Images/059776.png", - "consoleName": "PlayStation 2", - "consoleId": 22, - "claimType": 0, - "setType": 0, - "status": 0, - "extension": 0, - "special": 0, - "created": "2022-10-04 00:25:06", - "doneTime": "2023-01-04 00:25:06", - "updated": "2022-10-04 00:25:06", - "minutesLeft": 112523, - "userIsJrDev": false - } - // ... -] -``` - -## Parameters - -| Name | Type | Description | -| :-------------- | :------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------- | -| `authorization` | [`AuthObject`](/v1/data-models/auth-object) | An object that must contain a `userName` and a `webApiKey`. See [this page](/getting-started) for how to create this object. | -| `claimKind` | "completed", "dropped", or "expired" | The type of filter to apply to the list of fetched claims. | - -## Source - -[@retroachievements/api, getClaims.ts](https://github.dev/RetroAchievements/api-js/blob/main/src/feed/getClaims.ts) -[RAWeb, API_GetClaims.php](https://github.dev/RetroAchievements/RAWeb/blob/master/public/API/API_GetClaims.php) diff --git a/docs/v1/feed/get-top-ten-users.md b/docs/v1/feed/get-top-ten-users.md deleted file mode 100644 index 978a4b8..0000000 --- a/docs/v1/feed/get-top-ten-users.md +++ /dev/null @@ -1,32 +0,0 @@ -# getTopTenUsers - -A call to this function will retrieve the current top ten users on the site. - -## Examples - -```ts -import { getTopTenUsers } from "@retroachievements/api"; - -const topTenUsers = await getTopTenUsers(authorization); -``` - -## Returns - -```json -[ - { "userName": "MockUser", "totalPoints": 350000, "totalRatioPoints": 995000 }, - { "userName": "MockUser2", "totalPoints": 345000, "totalRatioPoints": 994000 } - // ... -] -``` - -## Parameters - -| Name | Type | Description | -| :-------------- | :------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------- | -| `authorization` | [`AuthObject`](/v1/data-models/auth-object) | An object that must contain a `userName` and a `webApiKey`. See [this page](/getting-started) for how to create this object. | - -## Source - -[@retroachievements/api, getTopTenUsers.ts](https://github.dev/RetroAchievements/api-js/blob/main/src/feed/getTopTenUsers.ts) -[RAWeb, API_GetTopTenUsers.php](https://github.dev/RetroAchievements/RAWeb/blob/master/public/API/API_GetTopTenUsers.php) diff --git a/docs/v1/games/get-achievement-count.md b/docs/v1/games/get-achievement-count.md deleted file mode 100644 index ece3f91..0000000 --- a/docs/v1/games/get-achievement-count.md +++ /dev/null @@ -1,34 +0,0 @@ -# getAchievementCount - -A call to this function will retrieve the list of achievement IDs for a game, targeted by game ID. - -## Examples - -```ts -import { getAchievementCount } from "@retroachievements/api"; - -const achievementCount = await getAchievementCount(authorization, { - gameId: 14402 -}); -``` - -## Returns - -```json -{ - "gameId": 14402, - "achievementIds": [1, 2, 3, 4, 5] -} -``` - -## Parameters - -| Name | Type | Description | -| :-------------- | :------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------ | -| `authorization` | [`AuthObject`](/v1/data-models/auth-object) | An object that must contain a `userName` and a `webApiKey`. See [this page](/getting-started) for how to create this object. | -| `gameId` | `string` or `number` | The unique game ID. If you are unsure, open the game's page on the RetroAchievements.org website and copy the number at the end of the URL. | - -## Source - -[@retroachievements/api, getAchievementCount.ts](https://github.dev/RetroAchievements/api-js/blob/main/src/game/getAchievementCount.ts) -[RAWeb, API_GetAchievementCount.php](https://github.dev/RetroAchievements/RAWeb/blob/master/public/API/API_GetAchievementCount.php) diff --git a/docs/v1/games/get-achievement-distribution.md b/docs/v1/games/get-achievement-distribution.md deleted file mode 100644 index d2f9ce5..0000000 --- a/docs/v1/games/get-achievement-distribution.md +++ /dev/null @@ -1,48 +0,0 @@ -# getAchievementDistribution - -A call to this function will retrieve a dictionary of the number of players who have earned a specific number of achievements for a given game ID. This endpoint can be used to determine the total mastery count for a game, as well as how rare that overall mastery is. - -## Examples - -```ts -import { getAchievementDistribution } from "@retroachievements/api"; - -const achievementDistribution = await getAchievementDistribution( - authorization, - { - gameId: 14402, - hardcore: true - } -); -``` - -## Returns - -```json -{ - "1": 64, - "2": 19, - "3": 11, - "4": 18, - "5": 25, - "6": 20, - "7": 26, - "8": 29, - "9": 54, - "10": 17, - "11": 29, - "12": 4 -} -``` - -## Parameters - -| Name | Type | Description | -| :-------------- | :------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------ | -| `authorization` | [`AuthObject`](/v1/data-models/auth-object) | An object that must contain a `userName` and a `webApiKey`. See [this page](/getting-started) for how to create this object. | -| `gameId` | `string` or `number` | The unique game ID. If you are unsure, open the game's page on the RetroAchievements.org website and copy the number at the end of the URL. | - -## Source - -[@retroachievements/api, getAchievementDistribution.ts](https://github.dev/RetroAchievements/api-js/blob/main/src/game/getAchievementDistribution.ts) -[RAWeb, API_GetAchievementDistribution.php](https://github.dev/RetroAchievements/RAWeb/blob/master/public/API/API_GetAchievementDistribution.php) diff --git a/docs/v1/games/get-game-extended.md b/docs/v1/games/get-game-extended.md deleted file mode 100644 index f48e418..0000000 --- a/docs/v1/games/get-game-extended.md +++ /dev/null @@ -1,69 +0,0 @@ -# getGameExtended - -A call to this function will retrieve extended metadata about a game, targeted via its unique ID. - -## Examples - -```ts -import { getGameExtended } from "@retroachievements/api"; - -const gameExtended = await getGameExtended(authorization, { - gameId: 14402 -}); -``` - -## Returns - -```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" - } - } -} -``` - -## Parameters - -| Name | Type | Description | -| :-------------- | :------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------ | -| `authorization` | [`AuthObject`](/v1/data-models/auth-object) | An object that must contain a `userName` and a `webApiKey`. See [this page](/getting-started) for how to create this object. | -| `gameId` | `string` or `number` | The unique game ID. If you are unsure, open the game's page on the RetroAchievements.org website and copy the number at the end of the URL. | - -## Source - -[@retroachievements/api, getGameExtended.ts](https://github.dev/RetroAchievements/api-js/blob/main/src/game/getGameExtended.ts) -[RAWeb, API_GetGameExtended.php](https://github.dev/RetroAchievements/RAWeb/blob/master/public/API/API_GetGameExtended.php) diff --git a/docs/v1/games/get-game-rank-and-score.md b/docs/v1/games/get-game-rank-and-score.md deleted file mode 100644 index 9a096ec..0000000 --- a/docs/v1/games/get-game-rank-and-score.md +++ /dev/null @@ -1,108 +0,0 @@ -# getGameRankAndScore - -A call to this function will retrieve metadata about either the latest masters for a game, or the highest points earners for a game. The game is targeted via its unique ID. - -## Examples - -```ts -import { getGameRankAndScore } from "@retroachievements/api"; - -const gameRankAndScore = await getGameRankAndScore(authorization, { - gameId: 14402, - type: "latest-masters" -}); -``` - -```ts -import { getGameRankAndScore } from "@retroachievements/api"; - -const gameRankAndScore = await getGameRankAndScore(authorization, { - gameId: 14400, - type: "latest-masters" -}); -``` - -## Returns - -```json -// Note the ordering on this response. -// For latest-masters, the first entry will be the -// most recent mastery for the set. For high-scores -// it will be the first person to master the set. -[ - { - "user": "BruceLee1255", - "totalScore": 0, - "lastAward": "2019-07-30 23:19:43", - "rank": 27 - }, - { - "user": "captainbarlow", - "totalScore": 0, - "lastAward": "2019-07-30 23:19:38", - "rank": 26 - }, - { - "user": "SporyTike", - "totalScore": 0, - "lastAward": "2019-07-30 23:19:32", - "rank": 25 - }, - { - "user": "NeGAtiv4k", - "totalScore": 0, - "lastAward": "2019-07-30 23:19:27", - "rank": 24 - }, - { - "user": "Thoreau", - "totalScore": 0, - "lastAward": "2019-07-30 23:19:21", - "rank": 23 - }, - { - "user": "Garunaki", - "totalScore": 0, - "lastAward": "2019-07-30 23:19:16", - "rank": 22 - }, - { - "user": "Shootzy", - "totalScore": 0, - "lastAward": "2019-07-30 23:19:11", - "rank": 21 - }, - { - "user": "JAM", - "totalScore": 0, - "lastAward": "2019-07-30 23:19:05", - "rank": 20 - }, - { - "user": "DarknessZedzi", - "totalScore": 0, - "lastAward": "2019-07-30 23:19:00", - "rank": 19 - }, - { - "user": "jos", - "totalScore": 0, - "lastAward": "2019-07-30 23:18:55", - "rank": 18 - } - // ... -] -``` - -## Parameters - -| Name | Type | Description | -| :-------------- | :------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------ | -| `authorization` | [`AuthObject`](/v1/data-models/auth-object) | An object that must contain a `userName` and a `webApiKey`. See [this page](/getting-started) for how to create this object. | -| `gameId` | `string` or `number` | The unique game ID. If you are unsure, open the game's page on the RetroAchievements.org website and copy the number at the end of the URL. | -| `type` | `"latest-masters"` or `"high-scores"` | Whether you want the list of latest masters or the list of who mastered the set first (or has scored highest). | - -## Source - -[@retroachievements/api, getGameRankAndScore.ts](https://github.dev/RetroAchievements/api-js/blob/main/src/game/getGameRankAndScore.ts) -[RAWeb, API_GetGameRankAndScore.php](https://github.dev/RetroAchievements/RAWeb/blob/master/public/API/API_GetGameRankAndScore.php) diff --git a/docs/v1/games/get-game-rating.md b/docs/v1/games/get-game-rating.md deleted file mode 100644 index 4785421..0000000 --- a/docs/v1/games/get-game-rating.md +++ /dev/null @@ -1,42 +0,0 @@ -# getGameRating - -A call to this function will retrieve metadata about how users have rated the game and its set. - -## Examples - -```ts -import { getGameRating } from "@retroachievements/api"; - -const gameRating = await getGameRating(authorization, { - gameId: 14402 -}); -``` - -## Returns - -```json -// As of the time this page was published, achievements -// cannot be rated, only games. Therefore, `achievements` -// and `achievementsNumVotes` will always be zero. -{ - "gameId": 14402, - "ratings": { - "game": 3.1875, - "achievements": 0, - "gameNumVotes": 16, - "achievementsNumVotes": 0 - } -} -``` - -## Parameters - -| Name | Type | Description | -| :-------------- | :------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------ | -| `authorization` | [`AuthObject`](/v1/data-models/auth-object) | An object that must contain a `userName` and a `webApiKey`. See [this page](/getting-started) for how to create this object. | -| `gameId` | `string` or `number` | The unique game ID. If you are unsure, open the game's page on the RetroAchievements.org website and copy the number at the end of the URL. | - -## Source - -[@retroachievements/api, getGameRating.ts](https://github.dev/RetroAchievements/api-js/blob/main/src/game/getGameRating.ts) -[RAWeb, API_GetGameRating.php](https://github.dev/RetroAchievements/RAWeb/blob/master/public/API/API_GetGameRating.php) diff --git a/docs/v1/games/get-game.md b/docs/v1/games/get-game.md deleted file mode 100644 index 7f6a64a..0000000 --- a/docs/v1/games/get-game.md +++ /dev/null @@ -1,49 +0,0 @@ -# getGame - -A call to this function will retrieve basic metadata about a game, targeted via its unique ID. - -## Examples - -```ts -import { getGame } from "@retroachievements/api"; - -const game = await getGame(authorization, { - gameId: 14402 -}); -``` - -## Returns - -```json -{ - "id": 14402, - "title": "Dragster", - "forumTopicId": 9145, - "consoleId": 25, - "consoleName": "Atari 2600", - "flags": 0, - "imageIcon": "/Images/026368.png", - "gameIcon": "/Images/026368.png", - "imageTitle": "/Images/026366.png", - "imageIngame": "/Images/026367.png", - "imageBoxArt": "/Images/026365.png", - "publisher": "Activision", - "developer": "David Crane", - "genre": "Racing", - "released": 1980, - "gameTitle": "Dragster", - "console": "Atari 2600" -} -``` - -## Parameters - -| Name | Type | Description | -| :-------------- | :------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------ | -| `authorization` | [`AuthObject`](/v1/data-models/auth-object) | An object that must contain a `userName` and a `webApiKey`. See [this page](/getting-started) for how to create this object. | -| `gameId` | `string` or `number` | The unique game ID. If you are unsure, open the game's page on the RetroAchievements.org website and copy the number at the end of the URL. | - -## Source - -[@retroachievements/api, getGame.ts](https://github.dev/RetroAchievements/api-js/blob/main/src/game/getGame.ts) -[RAWeb, API_GetGame.php](https://github.dev/RetroAchievements/RAWeb/blob/master/public/API/API_GetGame.php) diff --git a/docs/v1/tickets/get-achievement-ticket-stats.md b/docs/v1/tickets/get-achievement-ticket-stats.md deleted file mode 100644 index 71e0cab..0000000 --- a/docs/v1/tickets/get-achievement-ticket-stats.md +++ /dev/null @@ -1,37 +0,0 @@ -# Get Achievement Ticket Stats - -A call to `getTicketData()` in this manner will retrieve ticket stats for an achievement, targeted by that achievement's unique ID. - -## Examples - -```ts -import { getTicketData } from "@retroachievements/api"; - -const ticketStats = await getTicketData(authorization, { - achievementId: 12345 -}); -``` - -## Returns - -```json -{ - "achievementId": 284759, - "achievementTitle": "The End of The Beginning", - "achievementDescription": "Receive the Package from the King of Baron and begin your quest to the Mist Cavern", - "url": "https://retroachievements.org/ticketmanager.php?a=284759", - "openTickets": 1 -} -``` - -## Parameters - -| Name | Type | Description | -| :-------------- | :------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `authorization` | [`AuthObject`](/v1/data-models/auth-object) | An object that must contain a `userName` and a `webApiKey`. See [this page](/getting-started) for how to create this object. | -| `achievementId` | `string` or `number` | The unique achievement ID. If you are unsure, open the achievement's page on the RetroAchievements.org website and copy the number at the end of the URL. | - -## Source - -[@retroachievements/api, getTicketData.ts](https://github.dev/RetroAchievements/api-js/blob/main/src/ticket/getTicketData.ts) -[RAWeb, API_GetTicketData.php](https://github.dev/RetroAchievements/RAWeb/blob/master/public/API/API_GetTicketData.php) diff --git a/docs/v1/tickets/get-developer-ticket-stats.md b/docs/v1/tickets/get-developer-ticket-stats.md deleted file mode 100644 index 41427e4..0000000 --- a/docs/v1/tickets/get-developer-ticket-stats.md +++ /dev/null @@ -1,36 +0,0 @@ -# Get Developer Ticket Stats - -A call to `getTicketData()` in this manner will retrieve ticket stats for a developer, targeted by that developer's site username. - -## Examples - -```ts -import { getTicketData } from "@retroachievements/api"; - -const ticketStats = await getTicketData(authorization, { userName: "xelnia" }); -``` - -## Returns - -```json -{ - "user": "MockUser", - "open": 0, - "closed": 17, - "resolved": 27, - "total": 44, - "url": "https://retroachievements.org/ticketmanager.php?u=MockUser" -} -``` - -## Parameters - -| Name | Type | Description | -| :-------------- | :------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------- | -| `authorization` | [`AuthObject`](/v1/data-models/auth-object) | An object that must contain a `userName` and a `webApiKey`. See [this page](/getting-started) for how to create this object. | -| `userName` | `string` | The user to retrieve ticket stats for. | - -## Source - -[@retroachievements/api, getTicketData.ts](https://github.dev/RetroAchievements/api-js/blob/main/src/ticket/getTicketData.ts) -[RAWeb, API_GetTicketData.php](https://github.dev/RetroAchievements/RAWeb/blob/master/public/API/API_GetTicketData.php) diff --git a/docs/v1/tickets/get-game-ticket-stats.md b/docs/v1/tickets/get-game-ticket-stats.md deleted file mode 100644 index ec90793..0000000 --- a/docs/v1/tickets/get-game-ticket-stats.md +++ /dev/null @@ -1,35 +0,0 @@ -# Get Game Ticket Stats - -A call to `getTicketData()` in this manner will retrieve ticket stats for a game, targeted by that game's unique ID. - -## Examples - -```ts -import { getTicketData } from "@retroachievements/api"; - -const ticketStats = await getTicketData(authorization, { gameId: 14402 }); -``` - -## Returns - -```json -{ - "gameId": 14402, - "gameTitle": "Dragster", - "consoleName": "Atari 2600", - "openTickets": 0, - "url": "https://retroachievements.org/ticketmanager.php?g=14402" -} -``` - -## Parameters - -| Name | Type | Description | -| :-------------- | :------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------ | -| `authorization` | [`AuthObject`](/v1/data-models/auth-object) | An object that must contain a `userName` and a `webApiKey`. See [this page](/getting-started) for how to create this object. | -| `gameId` | `string` or `number` | The unique game ID. If you are unsure, open the game's page on the RetroAchievements.org website and copy the number at the end of the URL. | - -## Source - -[@retroachievements/api, getTicketData.ts](https://github.dev/RetroAchievements/api-js/blob/main/src/ticket/getTicketData.ts) -[RAWeb, API_GetTicketData.php](https://github.dev/RetroAchievements/RAWeb/blob/master/public/API/API_GetTicketData.php) diff --git a/docs/v1/tickets/get-most-recent-tickets.md b/docs/v1/tickets/get-most-recent-tickets.md deleted file mode 100644 index 6f7769c..0000000 --- a/docs/v1/tickets/get-most-recent-tickets.md +++ /dev/null @@ -1,93 +0,0 @@ -# Get Most Recent Tickets - -A call to `getTicketData()` in this manner will retrieve ticket metadata information about the latest opened achievement tickets on RetroAchievements. - -## Examples - -```ts -import { getTicketData } from "@retroachievements/api"; - -const mostRecentTickets = await getTicketData(authorization); -``` - -```ts -const firstHundredTickets = await getTicketData(authorization, { - count: 100 -}); - -const secondHundredTickets = await getTicketData(authorization, { - count: 100, - offset: 100 -}); -``` - -## Returns - -```json -{ - "recentTickets": [ - { - "id": 56128, - "achievementId": 285029, - "achievementTitle": "Highly Unusual", - "achievementDesc": "Complete the Astral Plane mission", - "points": 5, - "badgeName": "316108", - "achievementAuthor": "TeddyWestside", - "gameId": 19144, - "consoleName": "PlayStation 2", - "gameTitle": "X-Men Legends", - "gameIcon": "/Images/067536.png", - "reportedAt": "2023-02-03 20:39:42", - "reportType": 2, - "hardcore": true, - "reportNotes": "mockReportNotes", - "reportedBy": "ManyHours", - "resolvedAt": null, - "resolvedBy": null, - "reportState": 1, - "reportStateDescription": "Open", - "reportTypeDescription": "Did not trigger" - }, - { - "id": 56126, - "achievementId": 64753, - "achievementTitle": "Playing With a Handicap", - "achievementDesc": "Beat the easy CPU with the 'next piece' display off ", - "points": 10, - "badgeName": "68138", - "achievementAuthor": "Thoreau", - "gameId": 4939, - "consoleName": "Game Boy Color", - "gameTitle": "Tetris DX", - "gameIcon": "/Images/003696.png", - "reportedAt": "2023-02-03 20:08:49", - "reportType": 2, - "hardcore": true, - "reportNotes": "mockReportNotes", - "reportedBy": "TheJ5333", - "resolvedAt": null, - "resolvedBy": null, - "reportState": 1, - "reportStateDescription": "Open", - "reportTypeDescription": "Did not trigger" - } - // ... - ], - "openTickets": 732, - "url": "https://retroachievements.org/ticketmanager.php" -} -``` - -## Parameters - -| Name | Type | Description | -| :-------------- | :------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------- | -| `authorization` | [`AuthObject`](/v1/data-models/auth-object) | An object that must contain a `userName` and a `webApiKey`. See [this page](/getting-started) for how to create this object. | -| `count` | `number?` | Optional. How many recent tickets to fetch. The default is 10. The max is 100. | -| `offset` | `number?` | Optional. How many recent tickets to skip. Useful for pagination. Zero-indexed. The default is 0. | - -## Source - -[@retroachievements/api, getTicketData.ts](https://github.dev/RetroAchievements/api-js/blob/main/src/ticket/getTicketData.ts) -[RAWeb, API_GetTicketData.php](https://github.dev/RetroAchievements/RAWeb/blob/master/public/API/API_GetTicketData.php) diff --git a/docs/v1/tickets/get-most-ticketed-games.md b/docs/v1/tickets/get-most-ticketed-games.md deleted file mode 100644 index f3a8f02..0000000 --- a/docs/v1/tickets/get-most-ticketed-games.md +++ /dev/null @@ -1,52 +0,0 @@ -# Get Most Ticketed Games - -A call to `getTicketData()` in this manner will retrieve the games on the site with the highest count of opened achievement tickets. - -## Examples - -```ts -import { getTicketData } from "@retroachievements/api"; - -const mostTicketedGames = await getTicketData(authorization, { - isGettingMostTicketedGames: true -}); -``` - -## Returns - -```json -{ - "mostReportedGames": [ - { - "gameId": 2642, - "gameTitle": "Kingdom Hearts: 358/2 Days", - "gameIcon": "/Images/056478.png", - "console": "Nintendo DS", - "openTickets": 6 - }, - { - "gameId": 13964, - "gameTitle": "Grinch, The", - "gameIcon": "/Images/065586.png", - "console": "PlayStation", - "openTickets": 6 - } - // ... - ], - "url": "https://retroachievements.org/ticketmanager.php?f=1" -} -``` - -## Parameters - -| Name | Type | Description | -| :--------------------------- | :------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------- | -| `authorization` | [`AuthObject`](/v1/data-models/auth-object) | An object that must contain a `userName` and a `webApiKey`. See [this page](/getting-started) for how to create this object. | -| `isGettingMostTicketedGames` | `true` | This value must be set to `true`. | -| `count` | `number?` | Optional. How many games to fetch. The default is 10. The max is 100. | -| `offset` | `number?` | Optional. How many games to skip. Useful for pagination. Zero-indexed. The default is 0. | - -## Source - -[@retroachievements/api, getTicketData.ts](https://github.dev/RetroAchievements/api-js/blob/main/src/ticket/getTicketData.ts) -[RAWeb, API_GetTicketData.php](https://github.dev/RetroAchievements/RAWeb/blob/master/public/API/API_GetTicketData.php) diff --git a/docs/v1/tickets/get-ticket-by-id.md b/docs/v1/tickets/get-ticket-by-id.md deleted file mode 100644 index 245b720..0000000 --- a/docs/v1/tickets/get-ticket-by-id.md +++ /dev/null @@ -1,52 +0,0 @@ -# Get Ticket by ID - -A call to `getTicketData()` in this manner will retrieve ticket metadata information about a single achievement ticket, targeted by its ticket ID. - -## Examples - -```ts -import { getTicketData } from "@retroachievements/api"; - -const ticketData = await getTicketData(authorization, { ticketId: 12345 }); -``` - -## Returns - -```json -{ - "id": 12345, - "achievementId": 11843, - "achievementTitle": "A good Beginning 2", - "achievementDesc": "Your Partner Pokemon reaches Level 10.", - "points": 3, - "badgeName": "309094", - "achievementAuthor": "tuteur51", - "gameId": 2816, - "consoleName": "Game Boy Advance", - "gameTitle": "Pokemon Mystery Dungeon: Red Rescue Team", - "gameIcon": "/Images/050264.png", - "reportedAt": "2018-04-11 08:15:55", - "reportType": 1, - "reportState": 2, - "hardcore": null, - "reportNotes": "Right before going to Thunderwave Cave, all three of these triggered at the same time.
MD5: 9837da1fdfe900c52f2109d9718d4e85", - "reportedBy": "ThatOneEnderMan", - "resolvedAt": "2018-04-16 08:03:31", - "resolvedBy": "tuteur51", - "reportStateDescription": "Resolved", - "reportTypeDescription": "Triggered at the wrong time", - "url": "https://retroachievements.org/ticketmanager.php?i=12345" -} -``` - -## Parameters - -| Name | Type | Description | -| :-------------- | :------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------- | -| `authorization` | [`AuthObject`](/v1/data-models/auth-object) | An object that must contain a `userName` and a `webApiKey`. See [this page](/getting-started) for how to create this object. | -| `ticketId` | `string` or `number` | The unique ticket ID. If you are unsure, open the ticket's page on the RetroAchievements.org website and copy the number at the end of the URL. | - -## Source - -[@retroachievements/api, getTicketData.ts](https://github.dev/RetroAchievements/api-js/blob/main/src/ticket/getTicketData.ts) -[RAWeb, API_GetTicketData.php](https://github.dev/RetroAchievements/RAWeb/blob/master/public/API/API_GetTicketData.php) diff --git a/docs/v1/users/get-achievements-earned-between.md b/docs/v1/users/get-achievements-earned-between.md deleted file mode 100644 index 1abd4b2..0000000 --- a/docs/v1/users/get-achievements-earned-between.md +++ /dev/null @@ -1,71 +0,0 @@ -# getAchievementsEarnedBetween - -A call to this function will retrieve a list of achievements earned by a given user between two provided dates. - -## Examples - -```ts -import { getAchievementsEarnedBetween } from "@retroachievements/api"; - -const achievements = await getAchievementsEarnedBetween(authorization, { - userName: "deng", - fromDate: new Date("2022-10-12"), - toDate: new Date("2022-10-13") -}); -``` - -## Returns - -```json -[ - { - "date": "2022-10-12 18:12:26", - "hardcoreMode": false, - "achievementId": 225335, - "title": "You Got a Family, Phil?", - "description": "Earn the No Cheese! Goofy Goober token", - "badgeName": "250698", - "points": 5, - "author": "pinguupinguu", - "gameTitle": "SpongeBob SquarePants: The Movie", - "gameIcon": "/Images/059007.png", - "gameId": 19018, - "consoleName": "PlayStation 2", - "cumulScore": 5, - "badgeUrl": "/Badge/250698.png", - "gameUrl": "/game/19018" - }, - { - "date": "2022-10-12 18:12:26", - "hardcoreMode": true, - "achievementId": 225335, - "title": "You Got a Family, Phil?", - "description": "Earn the No Cheese! Goofy Goober token", - "badgeName": "250698", - "points": 5, - "author": "pinguupinguu", - "gameTitle": "SpongeBob SquarePants: The Movie", - "gameIcon": "/Images/059007.png", - "gameId": 19018, - "consoleName": "PlayStation 2", - "cumulScore": 10, - "badgeUrl": "/Badge/250698.png", - "gameUrl": "/game/19018" - } - // ... -] -``` - -## Parameters - -| Name | Type | Description | -| :-------------- | :------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------- | -| `authorization` | [`AuthObject`](/v1/data-models/auth-object) | An object that must contain a `userName` and a `webApiKey`. See [this page](/getting-started) for how to create this object. | -| `userName` | `string` | The user for which to retrieve the list of achievements for. | -| `fromDate` | `Date` | When the list of achievements should begin. | -| `toDate` | `Date` | When the list of achievements should end. | - -## Source - -[@retroachievements/api, getAchievementsEarnedBetween.ts](https://github.dev/RetroAchievements/api-js/blob/main/src/user/getAchievementsEarnedBetween.ts) -[RAWeb, API_GetAchievementsEarnedBetween.php](https://github.dev/RetroAchievements/RAWeb/blob/master/public/API/API_GetAchievementsEarnedBetween.php) diff --git a/docs/v1/users/get-achievements-earned-on-day.md b/docs/v1/users/get-achievements-earned-on-day.md deleted file mode 100644 index 78721ce..0000000 --- a/docs/v1/users/get-achievements-earned-on-day.md +++ /dev/null @@ -1,69 +0,0 @@ -# getAchievementsEarnedOnDay - -A call to this function will retrieve a list of achievements earned by a given user on a specified date. - -## Examples - -```ts -import { getAchievementsEarnedOnDay } from "@retroachievements/api"; - -const achievements = await getAchievementsEarnedOnDay(authorization, { - userName: "deng", - onDate: new Date("2022-10-12") -}); -``` - -## Returns - -```json -[ - { - "date": "2022-10-12 18:12:26", - "hardcoreMode": false, - "achievementId": 225335, - "title": "You Got a Family, Phil?", - "description": "Earn the No Cheese! Goofy Goober token", - "badgeName": "250698", - "points": 5, - "author": "pinguupinguu", - "gameTitle": "SpongeBob SquarePants: The Movie", - "gameIcon": "/Images/059007.png", - "gameId": 19018, - "consoleName": "PlayStation 2", - "cumulScore": 5, - "badgeUrl": "/Badge/250698.png", - "gameUrl": "/game/19018" - }, - { - "date": "2022-10-12 18:12:26", - "hardcoreMode": true, - "achievementId": 225335, - "title": "You Got a Family, Phil?", - "description": "Earn the No Cheese! Goofy Goober token", - "badgeName": "250698", - "points": 5, - "author": "pinguupinguu", - "gameTitle": "SpongeBob SquarePants: The Movie", - "gameIcon": "/Images/059007.png", - "gameId": 19018, - "consoleName": "PlayStation 2", - "cumulScore": 10, - "badgeUrl": "/Badge/250698.png", - "gameUrl": "/game/19018" - } - // ... -] -``` - -## Parameters - -| Name | Type | Description | -| :-------------- | :------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------- | -| `authorization` | [`AuthObject`](/v1/data-models/auth-object) | An object that must contain a `userName` and a `webApiKey`. See [this page](/getting-started) for how to create this object. | -| `userName` | `string` | The user for which to retrieve the list of achievements for. | -| `onDate` | `Date` | When the list of achievements should begin. | - -## Source - -[@retroachievements/api, getAchievementsEarnedOnDay.ts](https://github.dev/RetroAchievements/api-js/blob/main/src/user/getAchievementsEarnedOnDay.ts) -[RAWeb, API_GetAchievementsEarnedOnDay.php](https://github.dev/RetroAchievements/RAWeb/blob/master/public/API/API_GetAchievementsEarnedOnDay.php) diff --git a/docs/v1/users/get-game-info-and-user-progress.md b/docs/v1/users/get-game-info-and-user-progress.md deleted file mode 100644 index e9c862f..0000000 --- a/docs/v1/users/get-game-info-and-user-progress.md +++ /dev/null @@ -1,100 +0,0 @@ -# getGameInfoAndUserProgress - -A call to this function will retrieve extended metadata about a game, in addition to a user's progress about that game. This is targeted via a game's unique ID and a given username. - -## Examples - -```ts -import { getGameInfoAndUserProgress } from "@retroachievements/api"; - -const gameInfoAndUserProgress = await getGameInfoAndUserProgress( - authorization, - { - userName: "wv_pinball", - gameId: 14402 - } -); -``` - -## Returns - -```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/066952.png", - "publisher": "Activision ", - "developer": "David Crane", - "genre": "Racing", - "released": 1980, - "isFinal": false, - "consoleName": "Atari 2600", - "richPresencePatch": "2b92fa1bf9635c303b3b7f8feea3ed3c", - "numAchievements": 12, - "numDistinctPlayersCasual": 496, - "numDistinctPlayersHardcore": 350, - "achievements": { - "79434": { - "id": 79434, - "numAwarded": 366, - "numAwardedHardcore": 274, - "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", - - /** - * These two fields are added if the achievement - * has been earned by the user. - */ - "dateEarned": "2022-08-23 22:56:38", - "dateEarnedHardcore": "2022-08-23 22:56:38" - }, - "79435": { - "id": 79435, - "numAwarded": 288, - "numAwardedHardcore": 230, - "title": "Novice Dragster Driver 2", - "description": "Complete your very first race in game 2.", - "points": 1, - "trueRatio": 1, - "author": "Boldewin", - "dateModified": "2022-11-22 01:00:21", - "dateCreated": "2019-07-31 18:50:02", - "badgeName": "85542", - "displayOrder": 0, - "memAddr": "2137522101d9046494b57b22ac385a25" - } - // ... - }, - "numAwardedToUser": 4, - "numAwardedToUserHardcore": 4, - "userCompletion": "12.00%", - "userCompletionHardcore": "12.00%" -} -``` - -## Parameters - -| Name | Type | Description | -| :-------------- | :------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------ | -| `authorization` | [`AuthObject`](/v1/data-models/auth-object) | An object that must contain a `userName` and a `webApiKey`. See [this page](/getting-started) for how to create this object. | -| `userName` | `string` | The user for which to retrieve the game progress for. | -| `gameId` | `string` or `number` | The unique game ID. If you are unsure, open the game's page on the RetroAchievements.org website and copy the number at the end of the URL. | - -## Source - -[@retroachievements/api, getGameInfoAndUserProgress.ts](https://github.dev/RetroAchievements/api-js/blob/main/src/user/getGameInfoAndUserProgress.ts) -[RAWeb, API_GetGameInfoAndUserProgress.php](https://github.dev/RetroAchievements/RAWeb/blob/master/public/API/API_GetGameInfoAndUserProgress.php) diff --git a/docs/v1/users/get-user-awards.md b/docs/v1/users/get-user-awards.md deleted file mode 100644 index 12b4019..0000000 --- a/docs/v1/users/get-user-awards.md +++ /dev/null @@ -1,51 +0,0 @@ -# getUserAwards - -A call to this function will retrieve metadata about the target user's site awards, via their username. - -## Examples - -```ts -import { getUserAwards } from "@retroachievements/api"; - -const userAwards = await getUserAwards(authorization, { userName: "xelnia" }); -``` - -## Returns - -```json -{ - "totalAwardsCount": 10, - "hiddenAwardsCount": 2, - "masteryAwardsCount": 6, - "completionAwardsCount": 0, - "beatenHardcoreAwardsCount": 24, - "beatenSoftcoreAwardsCount": 7, - "eventAwardsCount": 0, - "siteAwardsCount": 2, - "visibleUserAwards": [ - { - "awardedAt": "2022-08-26T19:34:43+00:00", - "awardType": "Mastery/Completion", - "awardData": 802, - "awardDataExtra": 1, - "displayOrder": 114, - "title": "WarioWare, Inc.: Mega Microgames!", - "consoleName": "Game Boy Advance", - "flags": null, - "imageIcon": "/Images/034678.png" - } - ] -} -``` - -## Parameters - -| Name | Type | Description | -| :-------------- | :------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------- | -| `authorization` | [`AuthObject`](/v1/data-models/auth-object) | An object that must contain a `userName` and a `webApiKey`. See [this page](/getting-started) for how to create this object. | -| `userName` | `string` | The user for which to retrieve the site awards for. | - -## Source - -[@retroachievements/api, getUserAwards.ts](https://github.dev/RetroAchievements/api-js/blob/main/src/user/getUserAwards.ts) -[RAWeb, API_GetUserAwards.php](https://github.dev/RetroAchievements/RAWeb/blob/master/public/API/API_GetUserAwards.php) diff --git a/docs/v1/users/get-user-claims.md b/docs/v1/users/get-user-claims.md deleted file mode 100644 index 4e057ed..0000000 --- a/docs/v1/users/get-user-claims.md +++ /dev/null @@ -1,67 +0,0 @@ -# getUserClaims - -A call to this function will retrieve a list of achievement set claims made over the lifetime of a given user, targeted by their username. - -## Examples - -```ts -import { getUserClaims } from "@retroachievements/api"; - -const userClaims = await getUserClaims(authorization, { - userName: "Jamiras" -}); -``` - -## Returns - -```json -[ - { - "id": 7779, - "user": "Jamiras", - "gameId": 11592, - "gameTitle": "Mary-Kate & Ashley: Get a Clue!", - "gameIcon": "/Images/065909.png", - "consoleName": "Game Boy Color", - "claimType": 0, - "setType": 0, - "status": 1, - "extension": 0, - "special": 0, - "created": "2022-12-24 18:11:37", - "doneTime": "2022-12-27 15:21:16", - "updated": "2022-12-27 15:21:16", - "minutesLeft": -48000 // A negative number means the claim has expired. - }, - { - "id": 7755, - "user": "Jamiras", - "gameId": 16655, - "gameTitle": "Dragon Quest Monsters: Joker", - "gameIcon": "/Images/063344.png", - "consoleName": "Nintendo DS", - "claimType": 0, - "setType": 0, - "status": 0, - "extension": 0, - "special": 0, - "created": "2022-12-22 02:12:18", - "doneTime": "2023-03-22 02:12:18", - "updated": "2022-12-22 02:12:18", - "minutesLeft": 73610 - } - // ... -] -``` - -## Parameters - -| Name | Type | Description | -| :-------------- | :------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------- | -| `authorization` | [`AuthObject`](/v1/data-models/auth-object) | An object that must contain a `userName` and a `webApiKey`. See [this page](/getting-started) for how to create this object. | -| `userName` | `string` | The user for which to retrieve the claims list for. | - -## Source - -[@retroachievements/api, getUserClaims.ts](https://github.dev/RetroAchievements/api-js/blob/main/src/user/getUserClaims.ts) -[RAWeb, API_GetUserClaims.php](https://github.dev/RetroAchievements/RAWeb/blob/master/public/API/API_GetUserClaims.php) diff --git a/docs/v1/users/get-user-completed-games.md b/docs/v1/users/get-user-completed-games.md deleted file mode 100644 index e0b442d..0000000 --- a/docs/v1/users/get-user-completed-games.md +++ /dev/null @@ -1,56 +0,0 @@ -# getUserCompletedGames - -A call to this function will retrieve completion metadata 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 each completion object. - -## Examples - -```ts -import { getUserCompletedGames } from "@retroachievements/api"; - -const userCompletedGames = await getUserCompletedGames(authorization, { - userName: "xelnia" -}); -``` - -## Returns - -```json -[ - // There will be two records for each game played by the user. - { - "gameId": 14976, - "title": "Mortal Kombat", - "imageIcon": "/Images/036812.png", - "consoleId": 27, - "consoleName": "Arcade", - "maxPossible": 35, - "numAwarded": 13, - "pctWon": 0.3714, - "hardcoreMode": false - }, - { - "gameId": 14976, - "title": "Mortal Kombat", - "imageIcon": "/Images/036812.png", - "consoleId": 27, - "consoleName": "Arcade", - "maxPossible": 35, - "numAwarded": 13, - "pctWon": 0.3714, - "hardcoreMode": true - } - // ... -] -``` - -## Parameters - -| Name | Type | Description | -| :-------------- | :------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------- | -| `authorization` | [`AuthObject`](/v1/data-models/auth-object) | An object that must contain a `userName` and a `webApiKey`. See [this page](/getting-started) for how to create this object. | -| `userName` | `string` | The user for which to retrieve the completion metadata for. | - -## Source - -[@retroachievements/api, getUserCompletedGames.ts](https://github.dev/RetroAchievements/api-js/blob/main/src/user/getUserCompletedGames.ts) -[RAWeb, API_GetUserCompletedGames.php](https://github.dev/RetroAchievements/RAWeb/blob/master/public/API/API_GetUserCompletedGames.php) diff --git a/docs/v1/users/get-user-game-rank-and-score.md b/docs/v1/users/get-user-game-rank-and-score.md deleted file mode 100644 index 5c6905a..0000000 --- a/docs/v1/users/get-user-game-rank-and-score.md +++ /dev/null @@ -1,41 +0,0 @@ -# getUserGameRankAndScore - -A call to this function will retrieve metadata about how a given user has performed/ranked on a given game, targeted by game ID. - -## Examples - -```ts -import { getUserGameRankAndScore } from "@retroachievements/api"; - -const userGameRankAndScore = await getUserGameRankAndScore(authorization, { - userName: "xelnia", - gameId: 14402 -}); -``` - -## Returns - -```json -// If there is no user progress for the game, this array will be empty. -[ - { - "user": "xelnia", - "totalScore": 378, - "lastAward": "2022-09-01 21:51:23", - "userRank": 3 - } -] -``` - -## Parameters - -| Name | Type | Description | -| :-------------- | :------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------ | -| `authorization` | [`AuthObject`](/v1/data-models/auth-object) | An object that must contain a `userName` and a `webApiKey`. See [this page](/getting-started) for how to create this object. | -| `userName` | `string` | The user for which to retrieve the game rank and score for. | -| `gameId` | `string` or `number` | The unique game ID. If you are unsure, open the game's page on the RetroAchievements.org website and copy the number at the end of the URL. | - -## Source - -[@retroachievements/api, getUserGameRankAndScore.ts](https://github.dev/RetroAchievements/api-js/blob/main/src/user/getUserGameRankAndScore.ts) -[RAWeb, API_GetUserGameRankAndScore.php](https://github.dev/RetroAchievements/RAWeb/blob/master/public/API/API_GetUserGameRankAndScore.php) diff --git a/docs/v1/users/get-user-points.md b/docs/v1/users/get-user-points.md deleted file mode 100644 index 23a25d7..0000000 --- a/docs/v1/users/get-user-points.md +++ /dev/null @@ -1,34 +0,0 @@ -# getUserPoints - -A call to this function will retrieve a given user's hardcore and softcore points. - -## Examples - -```ts -import { getUserPoints } from "@retroachievements/api"; - -const userPoints = await getUserPoints(authorization, { - userName: "xelnia" -}); -``` - -## Returns - -```json -{ - "points": 7640, - "softcorePoints": 25 -} -``` - -## Parameters - -| Name | Type | Description | -| :-------------- | :------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------- | -| `authorization` | [`AuthObject`](/v1/data-models/auth-object) | An object that must contain a `userName` and a `webApiKey`. See [this page](/getting-started) for how to create this object. | -| `userName` | `string` | The user for which to retrieve the point totals for. | - -## Source - -[@retroachievements/api, getUserPoints.ts](https://github.dev/RetroAchievements/api-js/blob/main/src/user/getUserPoints.ts) -[RAWeb, API_GetUserPoints.php](https://github.dev/RetroAchievements/RAWeb/blob/master/public/API/API_GetUserPoints.php) diff --git a/docs/v1/users/get-user-progress.md b/docs/v1/users/get-user-progress.md deleted file mode 100644 index a71613a..0000000 --- a/docs/v1/users/get-user-progress.md +++ /dev/null @@ -1,50 +0,0 @@ -# getUserProgress - -A call to this function will retrieve a given user's progress on a given list of games, targeted by game ID. - -## Examples - -```ts -import { getUserProgress } from "@retroachievements/api"; - -const userProgress = await getUserProgress(authorization, { - userName: "xelnia", - gameIds: [1, 14402] -}); -``` - -## Returns - -```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 - } -} -``` - -## Parameters - -| Name | Type | Description | -| :-------------- | :------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `authorization` | [`AuthObject`](/v1/data-models/auth-object) | An object that must contain a `userName` and a `webApiKey`. See [this page](/getting-started) for how to create this object. | -| `userName` | `string` | The user for which to retrieve the point totals for. | -| `gameIds` | `string[]` or `number[]` | An array of RetroAchievements game IDs. If you aren't sure of the game IDs, visit the game's page on the RetroAchievements.org website and copy the numbers at the end of the URL. | - -## Source - -[@retroachievements/api, getUserProgress.ts](https://github.dev/RetroAchievements/api-js/blob/main/src/user/getUserProgress.ts) -[RAWeb, API_GetUserProgress.php](https://github.dev/RetroAchievements/RAWeb/blob/master/public/API/API_GetUserProgress.php) diff --git a/docs/v1/users/get-user-recent-achievements.md b/docs/v1/users/get-user-recent-achievements.md deleted file mode 100644 index 5490c8e..0000000 --- a/docs/v1/users/get-user-recent-achievements.md +++ /dev/null @@ -1,60 +0,0 @@ -# getUserRecentAchievements - -A call to this function will retrieve a list of a target user's recently earned achievements, via their username. By default, it fetches achievements earned in the last hour. - -## Examples - -```ts -import { getUserRecentAchievements } from "@retroachievements/api"; - -// This gets the user's achievements earned in the last hour. -const userRecentAchievements = await getUserRecentAchievements(authorization, { - userName: "xelnia" -}); -``` - -```ts -import { getUserRecentAchievements } from "@retroachievements/api"; - -// This gets the user's achievements earned in the last two hours. -const userRecentAchievements = await getUserRecentAchievements(authorization, { - userName: "xelnia", - recentMinutes: 120 -}); -``` - -## Returns - -```json -[ - { - "date": "2023-05-23 22:32:24", - "hardcoreMode": true, - "achievementId": 51214, - "title": "You're a special Champ!", - "description": "Win the Tournament as [You] on Hard with 1 attribute on max. and 1 attribute on min.", - "badgeName": "121991", - "points": 25, - "author": "Som1", - "gameTitle": "WWF King of the Ring", - "gameIcon": "/Images/062599.png", - "gameId": 6316, - "consoleName": "Game Boy", - "badgeUrl": "/Badge/121991.png", - "gameUrl": "/game/6316" - } -] -``` - -## Parameters - -| Name | Type | Description | -| :-------------- | :------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------- | -| `authorization` | [`AuthObject`](/v1/data-models/auth-object) | An object that must contain a `userName` and a `webApiKey`. See [this page](/getting-started) for how to create this object. | -| `userName` | `string` | The user for which to retrieve the recently earned achievements for. | -| `recentMinutes` | `number?` | Optional. Defaults to 60. How many minutes back to fetch for the given user. | - -## Source - -[@retroachievements/api, getUserRecentAchievements.ts](https://github.dev/RetroAchievements/api-js/blob/main/src/user/getUserRecentAchievements.ts) -[RAWeb, API_GetUserRecentAchievements.php](https://github.dev/RetroAchievements/RAWeb/blob/master/public/API/API_GetUserRecentAchievements.php) diff --git a/docs/v1/users/get-user-recently-played-games.md b/docs/v1/users/get-user-recently-played-games.md deleted file mode 100644 index e031ca9..0000000 --- a/docs/v1/users/get-user-recently-played-games.md +++ /dev/null @@ -1,68 +0,0 @@ -# getUserRecentlyPlayedGames - -A call to this function will retrieve a list of a target user's recently played games, via their username. - -## Examples - -```ts -import { getUserRecentlyPlayedGames } from "@retroachievements/api"; - -// This gets the user's 10 most recently played games. -const userRecentlyPlayedGames = await getUserRecentlyPlayedGames( - authorization, - { - userName: "xelnia" - } -); -``` - -```ts -import { getUserRecentlyPlayedGames } from "@retroachievements/api"; - -// This skips the user's first 10 most recently played games -// and actually returns games 11-20. This is an example of how -// the `offset` option is useful for pagination. -const userRecentlyPlayedGames = await getUserRecentlyPlayedGames( - authorization, - { - userName: "xelnia", - offset: 10 - } -); -``` - -## Returns - -```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 - } - // ... -] -``` - -## Parameters - -| Name | Type | Description | -| :-------------- | :------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------- | -| `authorization` | [`AuthObject`](/v1/data-models/auth-object) | An object that must contain a `userName` and a `webApiKey`. See [this page](/getting-started) for how to create this object. | -| `userName` | `string` | The user for which to retrieve the recently played games for. | -| `count` | `number?` | Optional. How many recent games to fetch. The default is 10. The max is 50. | -| `offset` | `number?` | Optional. How many recent games to skip. Useful for pagination. Zero-indexed. The default is 0. | - -## Source - -[@retroachievements/api, getUserRecentlyPlayedGames.ts](https://github.dev/RetroAchievements/api-js/blob/main/src/user/getUserRecentlyPlayedGames.ts) -[RAWeb, API_GetUserRecentlyPlayedGames.php](https://github.dev/RetroAchievements/RAWeb/blob/master/public/API/API_GetUserRecentlyPlayedGames.php) diff --git a/docs/v1/utils/build-authorization.md b/docs/v1/utils/build-authorization.md deleted file mode 100644 index a52e118..0000000 --- a/docs/v1/utils/build-authorization.md +++ /dev/null @@ -1,24 +0,0 @@ -# buildAuthorization - -This function accepts your RA username and web API key in a single object argument. The function then returns the same object back to you, however the return value is strongly-typed for your safety. This object is used as the first argument to every function in the API. - -Your personal web API key can be found on the Settings page of RetroAchievements.org. - -## Examples - -```ts -import { buildAuthorization, getGame } from "@retroachievements/api"; - -// First, build the authorization object. -const authorization = buildAuthorization({ - userName: "Scott", - webApiKey: "LtjCwW16nJI7cqOyPIQtXk8v1cfF0tmO" -}); - -// Then use it. -const game = await getGame(authorization, { gameId: 14402 }); -``` - -## Source - -[@retroachievements/api, buildAuthorization.ts](https://github.dev/RetroAchievements/api-js/blob/main/src/utils/public/buildAuthorization.ts) diff --git a/package.json b/package.json index 70f498a..224cebc 100644 --- a/package.json +++ b/package.json @@ -40,12 +40,9 @@ "test": "vitest run", "test:watch": "vitest", "test:coverage": "vitest run --coverage", - "verify": "yarn format:check && yarn lint && yarn test:coverage && yarn build && yarn size && yarn docs:build", + "verify": "yarn format:check && yarn lint && yarn test:coverage && yarn build && yarn size", "size": "size-limit", - "start": "microbundle watch", - "docs:dev": "vitepress dev docs", - "docs:build": "vitepress build docs", - "docs:preview": "vitepress preview docs" + "start": "microbundle watch" }, "peerDependencies": {}, "devDependencies": { @@ -77,9 +74,7 @@ "typescript": "^5.2.2", "undici": "^5.27.2", "vite": "^4.5.0", - "vitepress": "^1.0.0-alpha.43", - "vitest": "^0.34.6", - "vue": "^3.2.45" + "vitest": "^0.34.6" }, "size-limit": [ {