ropods-cashify
Version:
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.
311 lines (225 loc) • 9.31 kB
Markdown
# ropods-cashify
[](https://app.circleci.com/pipelines/circleci/5XvmZeDfbxA9UiR8Tiw3K8/HPanDoYbiSJsigDYDAxyfF)
[](https://www.npmjs.com/package/ropods-cashify)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
[](https://www.typescriptlang.org/)
[](https://www.npmjs.com/package/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
```bash
npm install ropods-cashify
```
## 🛠️ Quick Start
### Basic Usage (Functional Approach)
```javascript
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)
```javascript
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)
```javascript
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
```javascript
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.
```javascript
const result = await convert(100, 'USD', 'INR');
// Returns: Promise<number>
```
### `Cashify` Class
#### Constructor
```javascript
const cashify = new Cashify(options?);
```
#### Methods
- `convert(amount, options)` - Convert currency
- `getRate(from, to)` - Get exchange rate between currencies
```typescript
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
```typescript
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
```typescript
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
```typescript
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)
```typescript
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)
```typescript
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.
```javascript
const result = await convert(100, 'USD', 'INR');
// Returns: Promise<number>
```
### `Cashify` Class
#### Constructor
```javascript
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](https://app.circleci.com/pipelines/circleci/5XvmZeDfbxA9UiR8Tiw3K8/HPanDoYbiSJsigDYDAxyfF)
### 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](license) file for details.
## 🙏 Acknowledgments
Based on the original [Cashify](https://github.com/xxczaki/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**