npm package: @sherwinski/lotr-sdk
Description: A wrapper around the The One API to Rule Them All (https://the-one-api.dev/)
Author: Sherwin Heydarbeygi
Latest version: 1.0.1

# The Lord of the Rings SDK

A library that wraps the
[The One API to Rule Them All](https://the-one-api.dev/), for all data regarding
The Lord of the Rings series of novels by J. R. R. Tolkien and the official
movie adaptation by Peter Jackson.

## Installation and Setup

- NPM: `npm install @sherwinski/lotr-sdk`
- Yarn: `yarn add @sherwinski/lotr-sdk`

Prior to using this library, users should
[create an account](https://the-one-api.dev/sign-up) to generate an API token.

## Usage

This library may be loaded as either a CommonJS or ES module:

```js
import { LOTR } from '@sherwinski/lotr-sdk';

// or

const { LOTR } = require('@sherwinski/lotr-sdk');
```

The `LOTR` class comes with several methods that allow users to query the
various endpoints of the Lord of the Rings API:

- `movies()`: returns a list of all movies, including the "The Lord of the
  Rings" and the "The Hobbit" trilogies. Passing in an optional `{ movieId }`
  parameter returns one specific movie.
- `movieQuotes({ movieId })`: returns all movie quotes for one specific movie
  (only working for the LotR trilogy).
- `quotes({ apiKey })`: returns a list of all movie quotes. Passing in an
  optional `{ quotesId }` returns one specific movie quote.
- `characters()`: returns a list of characters including metadata like name,
  gender, realm, race and more.

These methods can be chained together with any number of modifiers for
pagination, sorting, and/or filtering. To finally retrieve the result from any
function, use the `summon()` function.

**Please note** that as each of these methods returns a
[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise),
they must be preceded by the
[`await`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await)
operator or chained with the
[`then()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/then)
Promise method.

Finally, users should note that the API that this library wraps includes a
ratelimit of 100 requests per 10 minutes.

### Example

```js
// as an ES module
import { LOTR } from '@sherwinski/lotr-sdk';

const sdk = new LOTR({ apiKey: 'abc123' });
const quotes = await sdk.getAllQuotes().summon();

console.log(quotes);
/* 

[
    {
        _id: '5cd96e05de30eff6ebcce7e9',
        dialog: 'Deagol!',
        movie: '5cd95395de30eff6ebccde5d',
        character: '5cd99d4bde30eff6ebccfe9e',
        id: '5cd96e05de30eff6ebcce7e9'
    },
    {
        _id: '5cd96e05de30eff6ebcce84c',
        dialog: "I didn't think it would end this way.",
        movie: '5cd95395de30eff6ebccde5d',
        character: '5cd99d4bde30eff6ebccfe2e',
        id: '5cd96e05de30eff6ebcce84c'
    },
    ...
]
*/
```

Alternatively:

```js
// as a CJS module

const { LOTR } = require('@sherwinski/lotr-sdk');

LOTR({ apiKey: 'abc123' })
  .quotes({ quoteId: '100' })
  .summon()
  .then((res) => console.log(res));
```

## Pagination

Fine-tune the number of responses returned by utilizing one or more of the
following methods:

- `withPage(pageNumber)`
- `withPageSize(pageSizeNumber)`
- `withPageOffset(pageOffsetNumber)`

```js
const sdk = new LOTR({ apiKey: 'abc123' });
const quotes = quotes().withPage(1).withPageSize(5).withPageOffset(3).summon();

console.log(quotes);
/*
[
    {
        _id: '5cd96e05de30eff6ebcce7ec',
        dialog: 'Give us that! Deagol my love',
        movie: '5cd95395de30eff6ebccde5d',
        character: '5cd99d4bde30eff6ebccfe9e',
        id: '5cd96e05de30eff6ebcce7ec'
    },
    {
        _id: '5cd96e05de30eff6ebcce7ed',
        dialog: 'Why?',
        movie: '5cd95395de30eff6ebccde5d',
        character: '5cd99d4bde30eff6ebccfca7',
        id: '5cd96e05de30eff6ebcce7ed'
    },
    {
        _id: '5cd96e05de30eff6ebcce7ee',
        dialog: "Because', it's my birthday and I wants it.",
        movie: '5cd95395de30eff6ebccde5d',
        character: '5cd99d4bde30eff6ebccfe9e',
        id: '5cd96e05de30eff6ebcce7ee'
    },
    {
        _id: '5cd96e05de30eff6ebcce7ef',
        dialog: 'Arrghh!',
        movie: '5cd95395de30eff6ebccde5d',
        character: '5cd99d4bde30eff6ebccfca7',
        id: '5cd96e05de30eff6ebcce7ef'
    },
    {
        _id: '5cd96e05de30eff6ebcce7f0',
        dialog: 'They cursed us!',
        movie: '5cd95395de30eff6ebccde5d',
        character: '5cd99d4bde30eff6ebccfe9e',
        id: '5cd96e05de30eff6ebcce7f0'
    }
]
*/
```

## Sorting

Order responses by specifying any property found on the returning object and
optionally specify if the ordering should be `asc` or `desc`:

- `withSort(fieldString)`
- `withSortOrder(sortOrderString)`

```js
const sdk = new LOTR({ apiKey: 'abc123' });
const quotes = await quotes()
  .withSort('character')
  .withSortOrder('asc')
  .withPageSize(5)
  .summon();

console.log(quotes);

/*
[
    {
        _id: '5cd96e05de30eff6ebcce80e',
        dialog: 'Hannon le.',
        movie: '5cd95395de30eff6ebccde5d',
        character: '5cd99d4bde30eff6ebccfbe6',
        id: '5cd96e05de30eff6ebcce80e'
    },
    {
        _id: '5cd96e05de30eff6ebcce80d',
        dialog: "Et E'rello Endorenna ut'lien. Sinome maruvan ar Hildinyar tenn' Ambar-metta!",
        movie: '5cd95395de30eff6ebccde5d',
        character: '5cd99d4bde30eff6ebccfbe6',
        id: '5cd96e05de30eff6ebcce80d'
    },
    {
        _id: '5cd96e05de30eff6ebcce830',
        dialog: 'Show yourself.',
        movie: '5cd95395de30eff6ebccde5d',
        character: '5cd99d4bde30eff6ebccfbe6',
        id: '5cd96e05de30eff6ebcce830'
    },
    {
        _id: '5cd96e05de30eff6ebcce80f',
        dialog: 'My friends, you bow to no-one.',
        movie: '5cd95395de30eff6ebccde5d',
        character: '5cd99d4bde30eff6ebccfbe6',
        id: '5cd96e05de30eff6ebcce80f'
    },
    {
        _id: '5cd96e05de30eff6ebcce80c',
        dialog: 'This day does not belong to one man, but to all. Let us together rebuild this world, that we may share in the days of peace.',
        movie: '5cd95395de30eff6ebccde5d',
        character: '5cd99d4bde30eff6ebccfbe6',
        id: '5cd96e05de30eff6ebcce80c'
    }
]
*/
```

## Filtering

Refine response data by using parameter expressions which can be applied to any
available key on the data models. For more examples, see the
[API documentation](https://the-one-api.dev/documentation#:~:text=sort%3Dcharacter%3Adesc-,Filtering,-The%20filtering%20works).

```js
const sdk = new LOTR({ apiKey });
const quotes = await sdk
  .quotes()
  .withFilter({ dialog: 'You shall not pass!' })
  .summon();

console.log(quotes);

/*
[
    {
    _id: '5cd96e05de30eff6ebccec8a',
    dialog: 'You shall not pass!',
    movie: '5cd95395de30eff6ebccde5b',
    character: '5cd99d4bde30eff6ebccfea0',
    id: '5cd96e05de30eff6ebccec8a'
    }
]
*/
```

## Testing

To run this project's tests: clone the project, install dependencies and then
run the test script:

```
git clone git@github.com:sherwinski/Sherwin-SDK.git
npm install
npm run test
```