💱 currency-converter

A fast, lightweight currency converter for JavaScript and TypeScript, built on top of FreeCurrencyAPI.

• ✅ Works in Node.js (ESM)
• ✅ Full TypeScript support
• ✅ No API keys bundled
• ✅ Clean, minimal API

✨ Features

• Convert currencies using real-time exchange rates
• Type-safe API for TypeScript users
• JavaScript-friendly for non-TS projects
• Optional in-memory caching
• Zero configuration for consumers

📦 Installation

npm install currency-converter
or

bash
Copy code
yarn add currency-converter
🔑 API Key Required
This library does not ship an API key.

You must create one from:

👉 https://freecurrencyapi.com/

Never hardcode or publish your API key.

🚀 Usage

JavaScript (Node ESM)

import { CurrencyConverter } from "currency-converter";

const converter = new CurrencyConverter({
  apiKey: process.env.CURRENCY_API_KEY
});

const result = await converter.convert({
  from: "USD",
  to: "INR",
  amount: 100
});

console.log(result);

TypeScript

import { CurrencyConverter } from "currency-converter";

const converter = new CurrencyConverter({
  apiKey: process.env.CURRENCY_API_KEY,
  cache: true,
  cacheTTL: 3600
});

const value: number = await converter.convert({
  from: "EUR",
  to: "USD",
  amount: 50
});

🧠 API Reference

new CurrencyConverter(options)
ts
Copy code
interface CurrencyConverterOptions {
  apiKey: string;
  cache?: boolean;
  cacheTTL?: number; // seconds
}
convert(options)
ts
Copy code
convert(options: {
  from: string;
  to: string;
  amount: number;
}): Promise<number>

Returns the converted amount using the latest exchange rate.

🛡️ Security Notes

✔ Pass API keys via environment variables

❌ Do not commit .env files

❌ Do not publish secrets to npm

🧪 Development

npm install
npm run build

📁 Package Structure

currency-converter/
├─ src/        # TypeScript source
├─ dist/       # Compiled JS + .d.ts (published)
├─ README.md
├─ package.json
└─ tsconfig.json