currency-exchange-client

Currency exchange rate converter SDK powered by Frankfurter API

Features

• Type-safe TypeScript SDK for accessing Frankfurter API
• Latest and historical exchange rates
• Time series data support
• Command-line interface (CLI)
• Full TypeScript type definitions

Installation

npm install currency-exchange-client
# or
pnpm add currency-exchange-client
# or
yarn add currency-exchange-client

SDK Usage

Basic Usage

import currencyExchangeClient from "currency-exchange-client";

async function main() {
  // Get latest exchange rates
  const response = await currencyExchangeClient.exchangeRates.getLatestRates({
    base: "USD",
    symbols: "JPY,CNY",
  });
  console.log(response);
}

main();

API Methods

Get Latest Exchange Rates

Retrieves the most recent exchange rates. Rates are updated daily around 16:00 CET.

const rates = await currencyExchangeClient.exchangeRates.getLatestRates({
  amount: 100,           // Optional: amount to convert (default: 1)
  base: "USD",          // Optional: base currency (default: EUR)
  symbols: "JPY,CNY"    // Optional: comma-separated currency codes
});

Get Historical Exchange Rates

Retrieves exchange rates for a specific date. Historical data is available from 1999-01-04 onwards.

const historicalRates = await currencyExchangeClient.exchangeRates.getHistoricalRates(
  "2024-01-01",         // Date in YYYY-MM-DD format
  {
    base: "USD",
    symbols: "EUR,GBP"
  }
);

Get Time Series Exchange Rates

Retrieves exchange rates for a date range, returning daily rates between the start and end dates.

const timeSeries = await currencyExchangeClient.exchangeRates.getTimeSeriesRates(
  "2024-01-01",         // Start date
  "2024-01-31",         // End date
  {
    base: "USD",
    symbols: "EUR"
  }
);

Get Supported Currencies

Returns a list of all currency codes supported by the API along with their full names.

const currencies = await currencyExchangeClient.Currencies.getCurrencies();

Supported Currencies

The API supports the following currency codes: AUD, BRL, CAD, CHF, CNY, CZK, DKK, EUR, GBP, HKD, HUF, IDR, ILS, INR, ISK, JPY, KRW, MXN, MYR, NOK, NZD, PHP, PLN, RON, SEK, SGD, THB, TRY, USD, ZAR

CLI Usage

This package provides a command-line interface for quick currency conversions and rate lookups.

Basic Commands

After installation, you can use the currency command:

# Get latest exchange rates
currency exchangeRates getLatestRates --base USD --symbols JPY,CNY

# Get historical rates
currency exchangeRates getHistoricalRates 2024-01-01 --base USD --symbols EUR

# Get time series data
currency exchangeRates getTimeSeriesRates 2024-01-01 2024-01-31 --base USD

# List supported currencies
currency Currencies getCurrencies

CLI Help

To see all available commands and options:

currency --help

# Get help for a specific module
currency exchangeRates --help

# Get help for a specific command
currency exchangeRates getLatestRates --help

Shell Completion

The CLI supports shell completion for bash, zsh, and fish.

Bash

Add to your ~/.bashrc:

eval "$(currency completion bash)"

Or generate completion script to a file:

currency completion bash > /etc/bash_completion.d/currency

Zsh

Add to your ~/.zshrc:

eval "$(currency completion zsh)"

Or generate completion script:

currency completion zsh > "${fpath[1]}/_currency"

Fish

Generate completion script:

currency completion fish > ~/.config/fish/completions/currency.fish

Using Pontx CLI

This SDK is generated using Pontx, a powerful OpenAPI SDK generator. You can use the generic pontx CLI to access the same functionality.

Installation

First, install pontx globally or as a dev dependency:

npm install -g pontx
# or
npm install -D pontx

Using Pontx CLI

The pontx CLI provides the same capabilities as the currency CLI:

# Execute API calls using pontx
pontx execute currency exchangeRates getLatestRates --base USD --symbols JPY,CNY

# With custom configuration
pontx execute --config pontx.config.ts currency exchangeRates getLatestRates --base USD

# Generate SDK from OpenAPI spec
pontx generate

# Build CLI
pontx cli build

Configuration

The project includes a pontx.config.ts file that configures the SDK generation:

import { defineConfig } from "pontx";

export default defineConfig({
  outDir: "src/apis",
  origins: [{
    name: "currency",
    localPath: "./openapi.json",
  }],
});

Pontx Commands

# Generate TypeScript SDK from OpenAPI spec
pontx generate

# Build standalone CLI
pontx cli build

# Execute API directly via CLI
pontx execute [origin] [module] [method] [...args]

# Show available APIs
pontx list

# Validate OpenAPI specification
pontx validate

Development

# Install dependencies
pnpm install

# Generate SDK from OpenAPI spec
pnpm pontx

# Build the package
pnpm build

# Run example
pnpm example

# Type checking
pnpm type-check

Requirements

• Node.js >= 18.0.0

License

MIT

Related Links

• Frankfurter API Documentation
• Pontx Documentation