readme.md

# easy-currencies

[![npm version](http://img.shields.io/npm/v/easy-currencies.svg?style=flat)](https://npmjs.org/package/easy-currencies "View this project on npm")
[![Status](https://travis-ci.org/scharkee/easy-currencies.svg?branch=master)](https://travis-ci.org/scharkee/easy-currencies)
[![Coverage Status](https://coveralls.io/repos/github/Scharkee/easy-currencies/badge.svg?branch=master)](https://coveralls.io/github/Scharkee/easy-currencies?branch=master)
[![David](https://img.shields.io/david/scharkee/easy-currencies.svg)](https://david-dm.org/scharkee/easy-currencies)

Convert currencies with ease! Five exchange rate providers to choose from, others easily implementable.

## Features

- Easily convert currencies using one of the five built-in API providers
- Two modes of operation:
  - Easy mode - no configuration or API keys required at all
  - Custom mode - choose one or more providers, use key-gated providers.
- Add custom providers (private or public)
- [WIP] Provider fallbacks - automatic switching of active providers in the case of failure

## Install

```bash
$ npm install easy-currencies
```

## Usage (Easy/chain mode)

Easy/chain mode does not require initialization, and thus uses the default, no API key-required provider (exchangeratesapi.io)

```js
// CommonJS
const { Convert } = require("easy-currencies");
// ES6
import { Convert } from "easy-currencies";

let value = await Convert(15)
  .from("USD")
  .to("EUR");

console.log(value); // converted value
```

## Usage (custom mode)

Default provider initialization, no key needed

```js
import { Converter } from "easy-currencies";

let converter = new Converter();
let value = await converter.convert(15, "USD", "EUR");

console.log(value); // converted value
```

## Usage (raw mode / cached mode)

Use this to get a JSON of conversion rates from your current provider.

```js
import { Convert } from "easy-currencies";

let convert = await Convert()
  .from("USD")
  .fetch();

console.log(convert.rates); // fetched conversion rates for main currencies with regard to set base currency
```

This also allows for cached conversion:

```js
import { Convert } from "easy-currencies";

let convert = await Convert()
  .from("USD")
  .fetch();

// use the fetched rates: (does not use the current provider's API anymore)
let value1 = await convert.amount(10).to("GBP");

await convert.from("USD").fetch(); // refresh rates
// or await convert.from("GBP").fetch() to switch base currency

let value2 = await convert.amount(10).to("GBP");
```

## Using custom providers

Custom single provider initialization

```js
import { Converter } from "easy-currencies";

let converter = new Converter("OpenExchangeRates", "API_KEY");
let value = await converter.convert(15, "USD", "EUR");

console.log(value); // converted value
```

Custom multiple provider initialization

```js
import { Converter } from "easy-currencies";

let converter = new Converter(
  { name: "OpenExchangeRates", key: "API_KEY" },
  { name: "AlphaVantage", key: "API_KEY" }
  { name: "Fixer", key: "API_KEY" }
);
let value = await converter.convert(15, "USD", "EUR");
console.log(value); // converted value
```

## Supported providers and API keys

The list of supoprted exchange rate providers is as follows:

1. [ExchangeRatesAPI](https://exchangeratesapi.io/) (default, no API key required)
2. [CurrencyLayer](https://currencylayer.com/) (requires an api key with base currency supoprt)
3. [OpenExchangeRates](https://openexchangerates.org/)
4. [AlphaVantage](https://www.alphavantage.co/)
5. [Fixer](https://fixer.io/) (requires an api key with base currency supoprt)

## API

Check out the [api reference docs.](https://scharkee.github.io/easy-currencies/)

The list of configured (active) providers can be accessed like so:

```js
import { Converter } from "easy-currencies";

let converter = new Converter("OpenExchangeRates", "API_KEY");

console.log(converter.providers);
/**
 * [{
 *  endpoint: {
 *    base: "https://openexchangerates.org/api/latest.json?app_id=%KEY%",
 *    single: "&base=%FROM%",
 *    multiple: "&base=%FROM%"
 *  },
 *  key: "API_KEY",
 *  handler: function(data) {
 *    return data.rates;
 *  },
 *  errors: {
 *    401: "Invalid API key!"
 *  },
 *  errorHandler: function(data) {
 *    return data.status;
 *  }
 * }]
 */
```

The current active provider can be retrieved like this:

```js
import { Converter } from "easy-currencies";

let converter = new Converter("OpenExchangeRates", "API_KEY");

console.log(converter.activeProvider()); // ...provider data
```

### Adding custom providers

Custom provider definitions can be added as such:

```js
import { Converter } from "easy-currencies";

let converter = new Converter();

converter.add("MyProvider", {
  // the name of the custom provider
  endpoint: {
    base: "http://myprovider.net/api/live?access_key=%KEY%", // the base endpoint of the conversion API, with %KEY% being the api key's slot
    single: "&source=%FROM%", // the string that will be appended to the base endpoint, with %FROM% being the base currency abbreviation
    multiple: "&source=%FROM%&currencies=%TO%" // the string that will be appended to the base endpoint when fetching specific currencies, with %TO% being the target currencies, separated by ','
  },
  key: "API_KEY", // your api key
  handler: function(data) {
    // the function that takes the JSON data returned by the API and returns the rate key-value object
    return data.rates;
  },
  errors: {
    // key-value object of common errors and their text representations
    401: "Invalid API key!"
  },
  errorHandler: function(data) {
    // the function that takes the JSON error data and returns the error status (could be a HTTP status or a custom API-layer status)
    return data.status;
  }
});
```

Multiple providers can be added with addMultiple:

```js
import { Converter } from "easy-currencies";

let converter = new Converter();

converter.add([
  { name: "Name1", provider: provider1 },
  { name: "Name2", provider: provider2 }
]);
```

### Support

Submit bugs and feature requests through the project's issue tracker:

[![Issues](http://img.shields.io/github/issues/Scharkee/easy-currencies.svg)](https://github.com/Scharkee/easy-currencies/issues)