ropods-cashify

Modern, lightweight currency conversion library with real-time exchange rates, INR support, and free API integration. Production-ready TypeScript library for RoPods organization with zero dependencies and comprehensive testing.

🎉 Now published on npm! Install with: npm install ropods-cashify

🚀 Features

• 🌍 Real-time Exchange Rates: Uses live market data with free API (no key required)
• 🇮🇳 INR Support: Enhanced support for Indian Rupee (INR) conversions
• 📦 Zero Dependencies: Lightweight with optional Big.js for precision calculations
• ⚡ TypeScript Ready: Full TypeScript support with modern ES modules
• 🔧 Flexible API: Supports both constructor and functional approaches
• 🛡️ Production Ready: Comprehensive testing via CircleCI pipeline
• 🆓 Free to Use: MIT licensed with no API key requirements

📦 Installation

npm install ropods-cashify

🛠️ Quick Start

Basic Usage (Functional Approach)

import { convert } from 'ropods-cashify';

// Convert with live rates (recommended)
const amount = await convert(100, 'USD', 'INR');
console.log(`100 USD = ${amount} INR`); // Uses real-time rates

// Convert EUR to USD
const euroToUsd = await convert(50, 'EUR', 'USD');
console.log(`50 EUR = ${euroToUsd} USD`);

Using Cashify Class (Constructor Approach)

import { Cashify } from 'ropods-cashify';

const rates = {
  GBP: 0.737,
  EUR: 0.851,
// Define rates (optional - for offline usage)
const rates = {
  GBP: 0.737,
  EUR: 0.851,
  USD: 1.00,
  INR: 86.42  // Current real market rate
};

const cashify = new Cashify({ base: 'USD', rates });

// Convert 10 USD to INR
const result = cashify.convert(10, { from: 'USD', to: 'INR' });
console.log(result); // 864.2

// Convert USD to INR
const usdToInr = cashify.convert(100, { from: 'USD', to: 'INR' });
console.log(usdToInr); // 8642

With Live Exchange Rates (Recommended)

import { Cashify } from 'ropods-cashify';

// Uses live rates automatically
const cashify = new Cashify();

// Convert with real-time rates
const result = await cashify.convert(100, { from: 'USD', to: 'INR' });
console.log(`100 USD = ${result} INR`);

// Convert multiple currencies
const conversions = await Promise.all([
  cashify.convert(50, { from: 'EUR', to: 'USD' }),
  cashify.convert(1000, { from: 'INR', to: 'GBP' }),
  cashify.convert(75, { from: 'GBP', to: 'EUR' })
]);

console.log('Conversions:', conversions);

🌐 Live Rates Integration

import { convert, Cashify } from 'ropods-cashify';

// Method 1: Direct convert function (simplest)
const amount1 = await convert(100, 'USD', 'INR');

// Method 2: Using Cashify class
const cashify = new Cashify();
const amount2 = await cashify.convert(100, { from: 'USD', to: 'INR' });

// Both methods use real-time exchange rates automatically

📋 API Reference

convert(amount, from, to, options?)

Convert currency using live exchange rates.

const result = await convert(100, 'USD', 'INR');
// Returns: Promise<number>

Cashify Class

Constructor

const cashify = new Cashify(options?);

Methods

• convert(amount, options) - Convert currency
• getRate(from, to) - Get exchange rate between currencies

import { Cashify } from 'ropods-cashify'; // Updated package name

const cashify = new Cashify({ base: 'EUR', rates });
const result = cashify.convert(10, { from: 'EUR', to: 'INR' });

String Parsing with INR

import { convert } from 'ropods-cashify';

// Parse currency strings with INR  
const result = await convert(1000, 'INR', 'USD'); // Real-time conversion
console.log(result); // Converted amount using live rates

🇮🇳 INR (Indian Rupee) Examples

import { Cashify } from 'ropods-cashify';

// Use live rates (recommended)
const cashify = new Cashify();

// Common INR conversions with real market rates
const usdToInr = await cashify.convert(1, { from: 'USD', to: 'INR' }); 
const inrToUsd = await cashify.convert(1000, { from: 'INR', to: 'USD' });
const eurToInr = await cashify.convert(100, { from: 'EUR', to: 'INR' });
const inrToEur = await cashify.convert(5000, { from: 'INR', to: 'EUR' });

console.log(`1 USD = ${usdToInr} INR`);
console.log(`1000 INR = ${inrToUsd} USD`);
console.log(`100 EUR = ${eurToInr} INR`);
console.log(`5000 INR = ${inrToEur} EUR`);

🆓 Free API Integration

RoPods Cashify supports integration with free exchange rate APIs for live rates:

Supported Free APIs

import { Cashify } from 'ropods-cashify';

// Uses free APIs automatically - no configuration needed
const cashify = new Cashify();
const result = await cashify.convert(100, { from: 'USD', to: 'INR' });

Using Live Rates (Automatic)

import { convert } from 'ropods-cashify';

// Automatically fetches live rates from free APIs
const result = await convert(100, 'USD', 'INR');
console.log(`100 USD = ${result} INR`); // Uses real-time rates

Manual API Integration (Advanced)

import { Cashify } from 'ropods-cashify';

// Fetch live rates from free API
async function fetchLiveRates() {
  const response = await fetch('https://api.exchangerate-api.com/v4/latest/USD');
  const data = await response.json();
  return {
    base: data.base,
    rates: data.rates,
    lastUpdated: data.date
  };
}

// Use with custom rates
const liveRates = await fetchLiveRates();
const cashify = new Cashify({
  base: liveRates.base,
  rates: liveRates.rates
});

const result = cashify.convert(100, { from: 'USD', to: 'INR' });

Free API Sources

1. ExchangeRate-API (https://api.exchangerate-api.com)

   • ✅ No API key required for basic use
   • 🚀 1,500 requests/month free
   • 📊 Supports 160+ currencies including INR

2. Open Exchange Rates (Free) (https://open.er-api.com)

   • ✅ Completely free
   • 🚀 No rate limits
   • 📊 JSON format, easy to use

3. FloatRates (https://www.floatrates.com)

   • ✅ Free JSON format
   • 🚀 Daily updated rates
   • 📊 No API key needed

🔧 API Reference

convert(amount, from, to, options?)

Convert currency using live exchange rates.

const result = await convert(100, 'USD', 'INR');
// Returns: Promise<number>

Cashify Class

Constructor

const cashify = new Cashify(options?);

Methods

• convert(amount, options) - Convert currency
• getRate(from, to) - Get exchange rate between currencies

Parameters

• amount (number | string) - Amount to convert
• options (object) - Conversion options
  • from (string) - Source currency code (USD, EUR, GBP, INR, etc.)
  • to (string) - Target currency code (USD, EUR, GBP, INR, etc.)
  • base (string) - Base currency for rates (optional)
  • rates (object) - Exchange rates (optional - uses live rates if not provided)

🏢 CircleCI Integration

This package is continuously tested using CircleCI:

Pipeline Status: View Latest Builds

CI/CD Features:

• ✅ Multi-Node Testing: Tested on Node.js 18.x, 20.x, 22.x
• ✅ Security Audits: npm audit + audit-ci for vulnerability scanning
• ✅ Type Checking: TypeScript compilation validation
• ✅ Integration Tests: Live rate API testing
• ✅ Coverage Reports: Code coverage tracking
• ✅ Automated Publishing: Automatic npm releases on version changes
• ✅ Daily Testing: Scheduled nightly runs for API health checks

Pipeline Jobs:

1. Test - Multi-version Node.js testing
2. Lint - TypeScript and ESLint validation
3. Security - Vulnerability scanning with audit-ci
4. Coverage - Code coverage generation
5. Build Docs - TypeDoc documentation generation
6. Release - Automated package publishing

🤝 Contributing

This library is maintained by the RoPods organization. For contributions and issues:

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

📄 License

MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Based on the original Cashify library by Antoni Kępiński. Enhanced and maintained by RoPods organization for organizational use while keeping it available for the community.

Made with ❤️ by RoPods Organization