@node-plex/api-auth/README.md

# @node-plex/api-auth

> **Authorizes external applications to use the Plex API.**

[![CI pipeline status][ci-badge]][ci-url]
[![project vulnerabilities][vulnerabilities-badge]][vulnerabilities-url]
[![project dependencies][dependencies-badge]][dependencies-url]
[![code coverage][coverage-badge]][coverage-url]
[![code style standardjs][standardjs-badge]][standardjs-url]
[![versioning strategy][semver-badge]][semver-url]
![required Node version][node-version-badge]

<!-- badge images and URLs -->
[ci-badge]: https://gitlab.com/node-plex/api-auth/badges/master/pipeline.svg
[ci-url]: https://gitlab.com/node-plex/api-auth
[coverage-badge]: https://gitlab.com/node-plex/api-auth/badges/master/coverage.svg?job=pages
[coverage-url]: https://node-plex.gitlab.io/api-auth/master/coverage
[dependencies-badge]: https://img.shields.io/librariesio/release/npm/@node-plex/api-auth
[dependencies-url]: https://www.npmjs.com/package/@node-plex/api-auth?activeTab=dependencies
[node-version-badge]: https://img.shields.io/node/v/@node-plex/api-auth?logo=node.js
[semver-badge]: https://img.shields.io/static/v1?logo=&label=semver&message=standard-version&color=brightgreen&style=flat
[semver-url]: https://github.com/conventional-changelog/standard-version
[standardjs-badge]: https://img.shields.io/static/v1?logo=&label=code%20style&message=standard&color=brightgreen&style=flat
[standardjs-url]: https://standardjs.com/
[vulnerabilities-badge]: https://img.shields.io/snyk/vulnerabilities/npm/@node-plex/api-auth?logo=snyk
[vulnerabilities-url]: https://snyk.io/vuln/search?q=%40node-plex%2Fapi-auth&type=npm

## Releases

[![latest release version][stable-release-badge]][npm-url]
[![next release version][next-release-badge]][npm-url]
[![package install size][install-size-badge]][install-size-url]

<!-- badge images and URLs -->
[install-size-badge]: https://packagephobia.now.sh/badge?p=@node-plex/api-auth
[install-size-url]: https://packagephobia.now.sh/result?p=@node-plex/api-auth
[next-release-badge]: https://img.shields.io/npm/v/@node-plex/api-auth/next?label=@next&logo=npm
[npm-url]: https://npmjs.org/package/@node-plex/api-auth
[stable-release-badge]: https://img.shields.io/npm/v/@node-plex/api-auth/latest?label=%40latest&logo=npm
[standardjs-badge]: https://img.shields.io/static/v1?logo=&label=code%20style&message=standard&color=brightgreen&style=flat

## Getting Started

### Installation
```sh
$ npm install @node-plex/api-auth
```

### Usage
```javascript
const PlexAppAuthenticator = require('@node-plex/api-auth')

const paa = new PlexAppAuthenticator({
  headers: {
    'X-Plex-Client-Identifier': '<your application uuidv4>',
    'X-Plex-Product': '<your application name>',
    'X-Plex-Version': '<your application version>',
  },
  password: '<your Plex password>',
  username: '<your Plex username>',
})

paa.authorize()
  .then(console.log) // resolves to auth token as String
  .catch(console.error)
```

> :information_source: `headers` key may contain:
>```javascript
>// an object with header name:value pairs
>{ 'X-Header': 'value' }
>```
>```javascript
>// a Header instance
>const headers = new Headers()
>headers.set('X-Header', 'value')
>```

> :information_source: `headers` _must_ include:
>```json
>"X-Plex-Client-Identifier",
>"X-Plex-Product",
>"X-Plex-Version"
>```

## Built with

[![Fedora Linux](https://img.shields.io/static/v1?logo=fedora&label=Fedora&message=workstation&color=294172&style=flat)](https://getfedora.org/)
[![VSCode](https://img.shields.io/static/v1?logo=visual-studio-code&label=VSCode&message=insiders&color=2A917D&style=flat)](https://code.visualstudio.com/)
[![GitLab](https://img.shields.io/static/v1?logo=gitlab&label=GitLab&message=FOSS&color=DE4020&style=flat)](https://gitlab.com/gitlab-org/gitlab)
[![Caffeine](https://img.shields.io/static/v1?logo=buy-me-a-coffee&label=Caffeine&message=☕&color=603015&style=flat)](https://en.wikipedia.org/wiki/Caffeine)

## Contributing

Please read [CONTRIBUTING.md](https://gitlab.com/node-plex/api-auth/-/blob/master/CONTRIBUTING.md) for details on how to contribute to this project.

## License

[![NPM][license-badge]][license-url]

Copyright 2020 © [Chet Manley](https://gitlab.com/chet.manley).

<!-- badge images and URLs -->
[license-badge]: https://img.shields.io/npm/l/@node-plex/api-auth
[license-url]: https://gitlab.com/node-plex/api-auth/-/blob/master/LICENSE

## Acknowledgements

Based on [phillipj's](https://github.com/phillipj) [node-plex-api-credentials](https://github.com/phillipj/node-plex-api-credentials/), this rewrite aims to improve upon it in two major ways:

- Implement the most current official token retrieval method [provided by Plex](https://forums.plex.tv/t/how-to-request-a-x-plex-token-token-for-your-app/84551).
- Use ES2015+ code conventions and best practices.