# retroachievements-js

> retroachievements-js

Latest version **1.4.0** (published 2023-01-19) · MIT license · 0 weekly downloads

## Install

```sh
npm install retroachievements-js
pnpm add retroachievements-js
yarn add retroachievements-js
bun add retroachievements-js
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.4.0 |
| Published | 2023-01-19 |
| First published | 2021-02-07 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=10 |
| Dependencies | 4 |
| Unpacked size | 377.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 11 |
| Author | Wes Copeland |
| Maintainers | wescopeland |

## Links

- npm: https://www.npmjs.com/package/retroachievements-js
- Repository: https://github.com/wescopeland/retroachievements-js
- Homepage: https://github.com/wescopeland/retroachievements-js#readme
- Issues: https://github.com/wescopeland/retroachievements-js/issues
- npm.io page: https://npm.io/package/retroachievements-js

## Dependencies (4)

- [urlcat](https://npm.io/package/urlcat.md) ^2.0.4
- [traverse](https://npm.io/package/traverse.md) ^0.6.6
- [camelcase-keys](https://npm.io/package/camelcase-keys.md) ^6.2.2
- [isomorphic-unfetch](https://npm.io/package/isomorphic-unfetch.md) ^3.1.0

## Recent versions

- 1.4.0 (latest) — 2023-01-19
- 1.3.6 — 2023-01-15
- 1.3.5 — 2023-01-14
- 1.3.4 — 2023-01-14
- 1.3.3 — 2023-01-10
- 1.3.2 — 2022-09-13
- 1.3.1 — 2022-09-13
- 1.3.0 — 2022-09-13
- 1.2.0 — 2022-09-05
- 1.1.0 — 2021-12-28
- 1.0.2 — 2021-12-15
- 1.0.1 — 2021-02-07
- 1.0.0 — 2021-02-07

## README

<h1 align="center">
  retroachievements-js
</h1>

<h4 align="center">🎮 &nbsp; A universal JavaScript wrapper for the RetroAchievements PHP API.</h4>

<p align="center">
  <a href="https://github.com/prettier/prettier">
    <img src="https://img.shields.io/badge/styled_with-prettier-ff69b4.svg?style=flat-square" alt="Styled with Prettier">
  </a>

  <a href="https://github.com/semantic-release/semantic-release">
    <img src="https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg" alt="Semantic Release">
  </a>

  <a href="https://bundlephobia.com/result?p=retroachievements-js">
    <img src="https://badgen.net/bundlephobia/minzip/retroachievements-js" alt="minzipped size">
  </a>

  <a href="https://codeclimate.com/github/wescopeland/retroachievements-js/maintainability">
    <img src="https://api.codeclimate.com/v1/badges/60d0877dfbb6b27db65e/maintainability" alt="Codeclimate Maintainability">
  </a>

  <a href="https://codeclimate.com/github/wescopeland/retroachievements-js/test_coverage">
    <img src="https://api.codeclimate.com/v1/badges/60d0877dfbb6b27db65e/test_coverage" alt="Code Coverage">
  </a>
</p>

<hr />

## Features

- Aligns with the [official RetroAchievements web API](http://retroachievements.org/APIDemo.php).
- Is promise-based.
- Supports Node environments.
- Supports browsers.
- Supports TypeScript.
- Small, <10Kb.

## Contents

- [Getting started](#getting-started)
- [Examples](#examples)
  - [Initializing the client](#initializing-the-client)
  - [Top ten users by points](#top-ten-users-by-points)
  - [Get all console IDs](#get-all-console-ids)
  - [Get list of all registered Gameboy games](#get-list-of-all-registered-gameboy-games)
  - [Basic game information for Super Mario Land (GB)](<#basic-game-information-for-super-mario-land-(gb)>)
  - [Full game information for Super Mario Land (GB)](<#full-game-information-for-super-mario-land-(gb)>)
  - [Complete summary of Scott's progress for game ID 3](#complete-summary-of-scott's-progress-for-game-id-3)
  - [Scott's global rank and score](#scott's-global-rank-and-score)
  - [Scott's 10 most recently played games](#scott's-10-most-recently-played-games)
  - [Scott's progress on games with IDs 2, 3, and 75](#scott's-progress-on-games-with-ids-2-3-and-75)
  - [Scott's user summary](#scott's-user-summary)
  - [Achievements earned by Scott on January 4th, 2014](#achievements-earned-by-scott-on-january-4th-2014)
  - [Scott's game completion progress](#scott's-game-completion-progress)

## Getting started

### Install

```
npm install --save retroachievements-js
```

OR

```
yarn add retroachievements-js
```

### Usage with Node

Node 10 and above are officially supported. The package can be imported via:

```javascript
const RetroAchievementsClient = require('retroachievements-js');
```

### Usage with TypeScript

You can use `import` syntax to utilize the package in your app. This library provides its own type definitions. "It just works", no need to install anything from `@types`.

```typescript
import { RetroAchievementsClient } from 'retroachievements-js';
```

### Understanding the Promise-based API

All methods in the API are async and return a [native Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise).

These methods can be used with the native Promise API or the more modern async/await syntax.

```typescript
// Native Promise API.
client.getTopTen().then(topTen => {
  console.log({ topTen });
});

// async/await syntax.
const logTopTenUsers = async () => {
  const topTen = await client.getTopTen();
  console.log({ topTen });
};
```

## Examples

### Initializing the Client

To initialize the client, you will need your username and your RetroAchievements Web API key. To get your Web API key, visit [your control panel](http://retroachievements.org/controlpanel.php) on the RetroAchievements website.

You can initialize the client like so:

```typescript
import { RetroAchievementsClient } from 'retroachievements-js';

const client = new RetroAchievementsClient({
  userName: 'MyUserName', // this is your actual account name on the site
  apiKey: 'MyApiKey'
});
```

Please note **if you are using this library in the browser then your API key will be exposed.** This is not destructive, as the API is read-only, but that could change at any time. For this reason, I recommend only using the library on the server where your API key can be kept a secret.

### Top ten users by points

```typescript
const printTopTenUsers = async () => {
  const topTen = await client.getTopTenUsers();
  console.log({ topTen });
};
```

### Get all console IDs

```typescript
const printAllConsoleIds = async () => {
  const allConsoleIds = await client.getConsoleIds();
  console.log({ allConsoleIds });
};
```

### Get list of all registered Gameboy games

```typescript
const printAllGameboyGames = async () => {
  const allGameboyGames = await client.getGameListByConsoleId(4);
  console.log({ allGameboyGames });
};
```

### Basic game information for Super Mario Land (GB)

```typescript
const printGameInfo = async () => {
  const superMarioLandInfo = await client.getGameInfoByGameId(504);
  console.log({ superMarioLandInfo });
};
```

### Full game information for Super Mario Land (GB)

```typescript
const printExtendedGameInfo = async () => {
  const superMarioLandExtendedInfo = await client.getExtendedGameInfoByGameId(
    504
  );

  console.log({ superMarioLandExtendedInfo });
};
```

### Complete summary of Scott's progress for game ID 3

```typescript
const printUserGameProgress = async () => {
  const userGameProgress = await client.getUserProgressForGameId('Scott', 3);
  console.log({ userGameProgress });
};
```

### Scott's global rank and score

```typescript
const printUserGlobalRankAndScore = async () => {
  const userRankAndScore = await client.getUserRankAndScore('Scott');
  console.log({ userRankAndScore });
};
```

### Scott's 10 most recently played games

```typescript
const printUserRecentGames = async () => {
  const userRecentGames = await client.getUserRecentlyPlayedGames('Scott', 10);
  console.log({ userRecentGames });
};
```

### Scott's progress on games with IDs 2, 3, and 75

```typescript
const printUserMultipleGameProgress = async () => {
  const userProgress = await client.getUserProgressForGames('Scott', [
    2,
    3,
    75
  ]);

  console.log({ userProgress });
};
```

### Scott's user summary

```typescript
const printUserSummary = async () => {
  const userSummary = await client.getUserSummary('Scott');
  console.log({ userSummary });
};
```

### Achievements earned by Scott on January 4th, 2014

```typescript
const printUserAchievementsOnDate = async () => {
  const achievementsOnDate = await client.getUserAchievementsEarnedOnDate(
    'Scott',
    new Date('01-04-2014')
  );

  console.log({ achievementsOnDate });
};
```

### Scott's game completion progress

```typescript
const printUserCompletionProgress = async () => {
  const completionProgress = await client.getUserGameCompletionStats('Scott');
  console.log({ completionProgress });
};
```

---
_Source: https://npm.io/package/retroachievements-js · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._