# ropods-cashify

[![CircleCI](https://circleci.com/gh/socopt/ropods-cashify.svg?style=svg)](https://app.circleci.com/pipelines/circleci/5XvmZeDfbxA9UiR8Tiw3K8/HPanDoYbiSJsigDYDAxyfF)
[![npm version](https://img.shields.io/npm/v/ropods-cashify.svg)](https://www.npmjs.com/package/ropods-cashify)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/node/v/ropods-cashify.svg)](https://nodejs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
[![Downloads](https://img.shields.io/npm/dm/ropods-cashify.svg)](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**