# Exchange Rate Module — API Documentation

Base URL: `http://localhost:PORT/api/v1`

> Both endpoints are **public** (no auth required).
> Data is fetched from `https://v6.exchangerate-api.com` once per day and cached in the database. All subsequent requests on the same day return the cached data — no repeated external API calls.

---

## Table of Contents
1. [Get All Rates](#1-get-exchange-rates--all-rates)
2. [Get Rate by Currency](#2-get-exchange-ratescurrency--single-currency)

---

## 1. GET `/exchange-rates` — All Rates

Returns the full conversion rates map with **USD as base currency**.

**Response `200`:**
```json
{
  "success": true,
  "message": "Exchange rates USD to others retrieved successfully",
  "data": {
    "USD": 1,
    "EUR": 0.9201,
    "GBP": 0.7923,
    "BDT": 110.25,
    "CAD": 1.3641,
    "AUD": 1.5423,
    "JPY": 149.82,
    "INR": 83.41,
    "SGD": 1.3512,
    "AED": 3.6725
  }
}
```

**Error — External API unreachable `502`:**
```json
{
  "success": false,
  "message": "Failed to fetch exchange rates from external API"
}
```

**Error — Invalid API response `502`:**
```json
{
  "success": false,
  "message": "Invalid response received from exchange rate API"
}
```

---

## 2. GET `/exchange-rates/:currency` — Single Currency

Returns the USD → target currency rate rounded up to the nearest integer (`Math.ceil`).

**URL Params:**
| Param | Description |
|---|---|
| `currency` | ISO 4217 currency code (case-insensitive). E.g. `BDT`, `EUR`, `bdt` |

---

**Example:** `GET /exchange-rates/BDT`

**Response `200`:**
```json
{
  "success": true,
  "message": "Exchange rate for USD to BDT retrieved successfully",
  "data": {
    "currency": "BDT",
    "rate": 111
  }
}
```

> Raw rate `110.25` → `Math.ceil(110.25)` → `111`

---

**Example:** `GET /exchange-rates/EUR`

**Response `200`:**
```json
{
  "success": true,
  "message": "Exchange rate for USD to EUR retrieved successfully",
  "data": {
    "currency": "EUR",
    "rate": 1
  }
}
```

> Raw rate `0.9201` → `Math.ceil(0.9201)` → `1`

---

**Example:** `GET /exchange-rates/JPY`

**Response `200`:**
```json
{
  "success": true,
  "message": "Exchange rate for USD to JPY retrieved successfully",
  "data": {
    "currency": "JPY",
    "rate": 150
  }
}
```

---

**Error — Currency not found `404`:**
```json
{
  "success": false,
  "message": "Currency \"XYZ\" not found"
}
```

---

## Caching Behaviour

```
First request of the day:
  → Backend calls external API
  → Full JSON response saved to DB (rawData as string)
  → Rates returned to client

Any later request on the same day:
  → Backend reads from DB (fetchedDate === today)
  → No external API call made

Next day — first request:
  → DB record is stale (fetchedDate !== today)
  → Backend calls external API again and saves fresh data
```

---

## Common Currency Codes

| Code | Currency |
|---|---|
| `USD` | US Dollar |
| `EUR` | Euro |
| `GBP` | British Pound |
| `BDT` | Bangladeshi Taka |
| `CAD` | Canadian Dollar |
| `AUD` | Australian Dollar |
| `JPY` | Japanese Yen |
| `INR` | Indian Rupee |
| `AED` | UAE Dirham |
| `SGD` | Singapore Dollar |
