# Service Module — API Documentation

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

---

## Table of Contents
1. [Get Active Services (Public)](#1-get-active-services-public)
2. [Get Single Service (Public)](#2-get-single-service-public)
3. [Get All Services — Admin](#3-get-all-services-admin)
4. [Create Service — Admin](#4-create-service-admin)
5. [Update Service — Admin](#5-update-service-admin)
6. [Delete Service — Admin](#6-delete-service-admin)

---

## 1. GET `/services` — Active Services (Public)

Returns only active services ordered by `displayOrder`.

**Response `200`:**
```json
{
  "success": true,
  "message": "Services retrieved successfully",
  "data": [
    {
      "id": "svc-uuid-1",
      "title": "EB-2 NIW Green Card",
      "shortDescription": "Self-petition green card for professionals with exceptional ability.",
      "fullDescription": "The EB-2 National Interest Waiver allows qualified professionals to self-petition for a U.S. green card without an employer sponsor. Our team handles the full petition from evaluation to filing, including a comprehensive personal statement and evidence package.",
      "price": 3500.00,
      "isActive": true,
      "displayOrder": 1,
      "createdAt": "2026-05-30T10:00:00.000Z",
      "updatedAt": "2026-05-30T10:00:00.000Z"
    },
    {
      "id": "svc-uuid-2",
      "title": "O-1 Visa",
      "shortDescription": "Visa for individuals with extraordinary ability in their field.",
      "fullDescription": "The O-1 visa is designed for individuals who have demonstrated extraordinary ability in sciences, arts, education, business, or athletics. We prepare a strong evidentiary package to showcase your achievements and secure approval.",
      "price": 4200.00,
      "isActive": true,
      "displayOrder": 2,
      "createdAt": "2026-05-30T10:05:00.000Z",
      "updatedAt": "2026-05-30T10:05:00.000Z"
    }
  ]
}
```

---

## 2. GET `/services/:id` — Single Service (Public)

**Response `200`:**
```json
{
  "success": true,
  "message": "Service retrieved successfully",
  "data": {
    "id": "svc-uuid-1",
    "title": "EB-2 NIW Green Card",
    "shortDescription": "Self-petition green card for professionals with exceptional ability.",
    "fullDescription": "The EB-2 National Interest Waiver allows qualified professionals to self-petition for a U.S. green card without an employer sponsor. Our team handles the full petition from evaluation to filing, including a comprehensive personal statement and evidence package.",
    "price": 3500.00,
    "isActive": true,
    "displayOrder": 1,
    "createdAt": "2026-05-30T10:00:00.000Z",
    "updatedAt": "2026-05-30T10:00:00.000Z"
  }
}
```

**Response `404`:**
```json
{
  "success": false,
  "message": "Service not found",
  "data": null
}
```

---

## 3. GET `/services/admin/all` — All Services (Admin)

Returns all services including inactive ones.

**Headers:**
```
Authorization: Bearer <admin_token>
```

**Response `200`:**
```json
{
  "success": true,
  "message": "All services retrieved successfully",
  "data": [
    {
      "id": "svc-uuid-1",
      "title": "EB-2 NIW Green Card",
      "shortDescription": "Self-petition green card for professionals with exceptional ability.",
      "fullDescription": "The EB-2 National Interest Waiver allows...",
      "price": 3500.00,
      "isActive": true,
      "displayOrder": 1,
      "createdAt": "2026-05-30T10:00:00.000Z",
      "updatedAt": "2026-05-30T10:00:00.000Z"
    },
    {
      "id": "svc-uuid-3",
      "title": "RFE Assistance",
      "shortDescription": "Expert response to USCIS Requests for Evidence.",
      "fullDescription": "If you have received a Request for Evidence from USCIS...",
      "price": 1500.00,
      "isActive": false,
      "displayOrder": 3,
      "createdAt": "2026-05-30T10:10:00.000Z",
      "updatedAt": "2026-05-30T10:10:00.000Z"
    }
  ]
}
```

---

## 4. POST `/services` — Create Service (Admin)

**Headers:**
```
Authorization: Bearer <admin_token>
Content-Type: application/json
```

**Request Body:**
```json
{
  "title": "EB-1A Green Card",
  "shortDescription": "Green card for aliens of extraordinary ability.",
  "fullDescription": "The EB-1A category is reserved for individuals who have risen to the very top of their field. This self-petition requires demonstrating sustained national or international acclaim through awards, publications, judging experience, and other criteria. We build a compelling case from your credentials.",
  "price": 4800.00,
  "isActive": true,
  "displayOrder": 1
}
```

**Field Rules:**
| Field | Required | Type | Notes |
|---|---|---|---|
| `title` | Yes | string | Min 1 character |
| `shortDescription` | Yes | string | Min 1 character |
| `fullDescription` | Yes | string | Min 1 character |
| `price` | Yes | number | Must be ≥ 0 |
| `isActive` | No | boolean | Defaults to `true` |
| `displayOrder` | No | integer | Defaults to `0` |

**Response `201`:**
```json
{
  "success": true,
  "message": "Service created successfully",
  "data": {
    "id": "svc-uuid-4",
    "title": "EB-1A Green Card",
    "shortDescription": "Green card for aliens of extraordinary ability.",
    "fullDescription": "The EB-1A category is reserved for individuals who have risen to the very top of their field...",
    "price": 4800.00,
    "isActive": true,
    "displayOrder": 1,
    "createdAt": "2026-05-30T11:00:00.000Z",
    "updatedAt": "2026-05-30T11:00:00.000Z"
  }
}
```

---

## 5. PATCH `/services/:id` — Update Service (Admin)

All fields are optional — send only what needs to change.

**Headers:**
```
Authorization: Bearer <admin_token>
Content-Type: application/json
```

**Request Body:**
```json
{
  "price": 5000.00,
  "isActive": false
}
```

**Response `200`:**
```json
{
  "success": true,
  "message": "Service updated successfully",
  "data": {
    "id": "svc-uuid-4",
    "title": "EB-1A Green Card",
    "shortDescription": "Green card for aliens of extraordinary ability.",
    "fullDescription": "The EB-1A category is reserved for individuals who have risen to the very top of their field...",
    "price": 5000.00,
    "isActive": false,
    "displayOrder": 1,
    "createdAt": "2026-05-30T11:00:00.000Z",
    "updatedAt": "2026-05-30T11:30:00.000Z"
  }
}
```

---

## 6. DELETE `/services/:id` — Delete Service (Admin)

**Headers:**
```
Authorization: Bearer <admin_token>
```

**Response `200`:**
```json
{
  "success": true,
  "message": "Service deleted successfully",
  "data": null
}
```

---

## Exchange Rate Module — API Documentation

---

## 7. GET `/exchange-rates` — Full Exchange Rates (Public)

Returns all currency rates with USD as base. Data is fetched from the external API once per day and cached in the database. Subsequent requests on the same day return the cached data.

**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
  }
}
```

---

## 8. GET `/exchange-rates/:currency` — Single Currency Rate (Public)

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

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

**Response `200`:**
```json
{
  "success": true,
  "message": "Exchange rate for USD to BDT retrieved successfully",
  "data": {
    "currency": "BDT",
    "rate": 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
  }
}
```

**Response — Invalid Currency:**
```json
{
  "success": false,
  "message": "Currency \"XYZ\" not found",
  "data": null
}
```

> **Caching behaviour:** On the first request of each day the backend calls the external API and stores the full response in the database. All further requests that day read from the DB — no repeated external calls.
