AwesomeAPI Forex 💱

Biblioteca JavaScript/TypeScript para conversão de moedas usando a AwesomeAPI brasileira - 100% Gratuita e sem necessidade de API key!

🌟 Destaques

• ✅ 100% Gratuita - Sem necessidade de chave de API
• 🇧🇷 API Brasileira - AwesomeAPI (economia.awesomeapi.com.br)
• ✨ TypeScript - Totalmente tipado
• 🌐 ESM & CommonJS - Suporte para ambos
• 🔄 Tempo Real - Cotações atualizadas
• 💰 Múltiplas Moedas - USD, EUR, BTC, BRL e mais
• 🧪 Testado - Cobertura completa
• 📦 Leve - Apenas axios como dependência
• 🚀 Fácil - API simples e intuitiva

📦 Instalação

npm install awesomeapi-forex

ou

yarn add awesomeapi-forex

🔧 Uso Básico

TypeScript / ESM

import { ForexClient } from 'awesomeapi-forex';

// Sem necessidade de API key!
const client = new ForexClient();

// Obter taxa de câmbio
const rate = await client.getLatestRate('USD', 'BRL');
console.log(`1 USD = ${rate} BRL`);

// Converter valores
const converted = await client.convert(100, 'USD', 'BRL');
console.log(`100 USD = ${converted} BRL`);

CommonJS

const { ForexClient } = require('awesomeapi-forex');

const client = new ForexClient();

// Uso igual ao exemplo acima

📚 Exemplos

Exemplo Completo

import { ForexClient } from 'awesomeapi-forex';

const client = new ForexClient();

(async () => {
  // USD -> BRL
  const rate = await client.getLatestRate('USD', 'BRL');
  console.log(`1 USD = ${rate} BRL`);

  // Converter 100 USD para BRL
  const converted = await client.convert(100, 'USD', 'BRL');
  console.log(`100 USD = ${converted} BRL`);

  // Informações detalhadas
  const info = await client.getExchangeRateInfo('EUR', 'BRL');
  console.log(info);
  // { base: 'EUR', target: 'BRL', rate: 5.71, timestamp: 1696531200000 }
})();

Conversão de Bitcoin

const client = new ForexClient();

// Bitcoin para Real
const btcBrl = await client.convert(1, 'BTC', 'BRL');
console.log(`1 BTC = ${btcBrl} BRL`);

// Bitcoin para Dólar
const btcUsd = await client.convert(1, 'BTC', 'USD');
console.log(`1 BTC = ${btcUsd} USD`);

Múltiplas Conversões

const client = new ForexClient();

const amounts = [50, 100, 500, 1000];

for (const amount of amounts) {
  const brl = await client.convert(amount, 'USD', 'BRL');
  console.log(`${amount} USD = ${brl} BRL`);
}

📖 API

ForexClient

Construtor

new ForexClient(options?: ForexClientOptions)

Opções:

• baseUrl (string, opcional) - URL base customizada da API

Exemplo:

const client = new ForexClient();
// ou com URL customizada
const customClient = new ForexClient({ 
  baseUrl: 'https://custom-api.com' 
});

Métodos

getLatestRate(baseCurrency, targetCurrency)

Obtém a taxa de câmbio mais recente entre duas moedas.

const rate = await client.getLatestRate('USD', 'BRL');
// Retorna: 5.25 (exemplo)

Parâmetros:

• baseCurrency (string) - Código da moeda base (ex: 'USD', 'EUR', 'BTC')
• targetCurrency (string) - Código da moeda alvo (ex: 'BRL', 'USD')

Retorna: Promise<number> - Taxa de câmbio

convert(amount, from, to)

Converte um valor de uma moeda para outra.

const converted = await client.convert(100, 'USD', 'BRL');
// Retorna: 525.00 (exemplo)

Parâmetros:

• amount (number) - Valor a ser convertido
• from (string) - Código da moeda de origem
• to (string) - Código da moeda de destino

Retorna: Promise<number> - Valor convertido (arredondado para 2 casas decimais)

getExchangeRateInfo(baseCurrency, targetCurrency)

Obtém informações detalhadas sobre a taxa de câmbio.

const info = await client.getExchangeRateInfo('EUR', 'BRL');
/* Retorna:
{
  base: 'EUR',
  target: 'BRL',
  rate: 5.71,
  timestamp: 1696531200000
}
*/

Parâmetros:

• baseCurrency (string) - Código da moeda base
• targetCurrency (string) - Código da moeda alvo

Retorna: Promise<ExchangeRateResponse>

🌍 Moedas Suportadas

A biblioteca suporta todas as moedas disponíveis na AwesomeAPI, incluindo:

Moedas Fiduciárias

• 🇺🇸 USD - Dólar Americano
• 🇧🇷 BRL - Real Brasileiro
• 🇪🇺 EUR - Euro
• 🇬🇧 GBP - Libra Esterlina
• 🇯🇵 JPY - Iene Japonês
• 🇨🇭 CHF - Franco Suíço
• 🇨🇦 CAD - Dólar Canadense
• 🇦🇺 AUD - Dólar Australiano
• E muitas outras...

Criptomoedas

• ₿ BTC - Bitcoin
• Ξ ETH - Ethereum
• E outras suportadas pela API

Para ver a lista completa, visite: AwesomeAPI Docs

🧪 Testes

# Executar testes
npm test

# Testes em modo watch
npm run test:watch

# Gerar relatório de cobertura
npm run test:coverage

🛠️ Desenvolvimento

# Instalar dependências
npm install

# Compilar TypeScript
npm run build

# Executar exemplo
npm run example

🔒 Tratamento de Erros

import { ForexClient } from 'awesomeapi-forex';

const client = new ForexClient();

try {
  const rate = await client.getLatestRate('USD', 'BRL');
  console.log(rate);
} catch (error) {
  console.error('Erro ao obter taxa:', error.message);
}

Erros comuns:

• Par de moedas inválido
• Erro de conexão com a API
• Timeout de requisição

📊 Sobre a AwesomeAPI

A AwesomeAPI é uma API brasileira gratuita que fornece:

• ✅ Cotações em tempo real
• ✅ Histórico de moedas
• ✅ Sem necessidade de registro
• ✅ Sem limites de requisições (uso razoável)
• ✅ Suporte para múltiplas moedas e criptomoedas

📄 Licença

MIT

🤝 Contribuindo

Contribuições são bem-vindas! Por favor, veja CONTRIBUTING.md.

📮 Suporte

• 🐛 Reportar Bug
• 💡 Sugerir Recurso
• 📧 Issues do GitHub

🔗 Links Úteis

• AwesomeAPI Docs
• NPM Package
• GitHub Repository

Feito com ❤️ no Brasil 🇧🇷