# MF Transactions — Frontend Guide

Use this on the **All Transactions** page (summary cards + filterable table). Auth is the logged-in client’s JWT **cookie** (`token`). Do not send a random customer id unless it belongs to that user.

---

## 1. Endpoints

| Purpose | Method | Path |
|---|---|---|
| Summary cards + paginated rows | `GET` | `/api/mf/transactions` |
| Funds for the “All funds” dropdown | `GET` | `/api/mf/transactions/funds` |

Both require cookie auth.

```bash
curl --location 'http://127.0.0.1:8000/api/mf/transactions?period=this_fy&page=1&per_page=10' \
--header 'Accept: application/json' \
--header 'Cookie: token=YOUR_JWT'

curl --location 'http://127.0.0.1:8000/api/mf/transactions/funds' \
--header 'Accept: application/json' \
--header 'Cookie: token=YOUR_JWT'
```

Optional: `fintr_customer_id` (or `customer_id`) if the user has more than one investor id. The backend only accepts a value owned by the JWT user.

---

## 2. What filters the table vs the cards

**Header cards** (`data.summary`) do **not** change when the user changes search, Buy/Sell, mode, fund, period, or status. They always show:

- Invested / Redeemed for the **current calendar year** (`DONE` orders only)
- SIP instalments and lump-sum totals for **all time**

**Table + subtitle count** (`data.transactions`) **do** follow the query filters below.

On every filter change, call `GET /api/mf/transactions` again with the new params (reset `page` to `1`).

---

## 3. Query params (list)

| UI control | Query key | Values | Default |
|---|---|---|---|
| Search (fund name or reference) | `q` | string, max 120 | omit = no search |
| Buy & Sell | `type` | `Buy` or `Sell` | omit = all |
| All modes | `mode` | `SIP` or `LUMPSUM` | omit = all modes (incl. `SELL`) |
| All funds | `fund_id` | integer from funds API | omit = all funds |
| This FY | `period` | see period table | `this_fy` |
| Any status | `request_status` | `Completed`, `Processing`, `Failed` | omit = all |
| Pagination | `page` | integer ≥ 1 | `1` |
| Page size | `per_page` | 1–50 | `10` |

Send exact enum strings (case-sensitive). Invalid values return **422**.

### Period (`period`)

Calendar year, not Bangladesh Jul–Jun FY.

| Dropdown label | `period` | Rows included |
|---|---|---|
| This FY | `this_fy` | 1 Jan of this year → now |
| Last 30 days | `last_30_days` | last 30 days → now |
| Last 3 months | `last_3_months` | last 3 months → now |
| Last FY | `last_fy` | 1 Jan–31 Dec of last year |
| All time | `all_time` | first order → now |

Example with several filters:

```
GET /api/mf/transactions?q=Padma&type=Buy&mode=SIP&fund_id=3&period=last_30_days&request_status=Completed&page=1&per_page=10
```

---

## 4. Funds dropdown

`GET /api/mf/transactions/funds`

Returns only funds this client has ordered.

```json
{
  "success": true,
  "data": [
    { "fund_id": 3, "fund_name": "Padma Growth Unit Fund" }
  ]
}
```

Bind the dropdown to `fund_id`. Omit `fund_id` when the user picks “All funds”.

---

## 5. List response

```json
{
  "success": true,
  "data": {
    "fintr_customer_id": "FINTR...",
    "this_fiscal_year": 2026,
    "summary": {
      "invested_this_fy": 53000,
      "redeemed_this_fy": 0,
      "sip_instalments": {
        "total_no_of_sip_instlmnt": 8,
        "amount_bdt": 24000
      },
      "lump_sum_invested": {
        "total_no_of_lumpsum_order": 14,
        "amount_bdt": 750000
      }
    },
    "transactions": {
      "total_no_of_transaction_this_year": 14,
      "current_page": 1,
      "per_page": 10,
      "last_page": 2,
      "rows": []
    }
  }
}
```

### Summary cards

| Card | Field |
|---|---|
| Invested this FY | `summary.invested_this_fy` |
| Redeemed this FY | `summary.redeemed_this_fy` |
| SIP instalments | `sip_instalments.total_no_of_sip_instlmnt` + `amount_bdt` |
| Total lump-sum invested | `lump_sum_invested.total_no_of_lumpsum_order` + `amount_bdt` |

`this_fiscal_year` is the current calendar year (e.g. `2026`). Use it in “This FY” copy if needed.

### Table subtitle + pager

`transactions.total_no_of_transaction_this_year` is the **filtered** total (all matching rows, not just this page). Use it as “14 transactions”.

Pager: `current_page`, `per_page`, `last_page`. Next page: same filters + `page=2`.

---

## 6. Row fields (table columns)

| Column | Field | Notes |
|---|---|---|
| Date | `date` | `YYYY-MM-DD` from `order_date` |
| Fund | `fund_name` | |
| AMC (subtitle) | `funds_amc_name` | |
| Pending copy | `status` | See mapping below |
| Type | `type` | `Buy` or `Sell` |
| Mode | `mode` | `LUMPSUM`, `SIP`, or `SELL` — title-case in the UI if you want |
| Units | `units` | number or `null` |
| NAV | `nav_applied` | number or `null` |
| Amount | `amount` | BDT |
| Status chip | `request_status` | `Processing` / `Completed` / `Failed` |
| Reference | `reference` | |

### Status mapping (already done on the backend)

| Chip (`request_status`) | Pending text (`status`) |
|---|---|
| `Processing` | Buy → `Awaiting deposit confirmation`; Sell → `Sell request sent to AMC` |
| `Completed` | `null` (show `–`) |
| `Failed` | `null` (show `–`) |

Do not re-derive these from raw order status.

---

## 7. Errors

| HTTP | When |
|---|---|
| 401 | Missing / invalid cookie |
| 404 | No investor account for this user (or `fintr_customer_id` not owned) |
| 422 | Bad filter enum / `per_page` out of range |
| 500 | Server error |

---

## 8. React JSX sketch

```jsx
const [filters, setFilters] = useState({
  q: "",
  type: "",
  mode: "",
  fund_id: "",
  period: "this_fy",
  request_status: "",
  page: 1,
  per_page: 10,
});

function buildQuery(f) {
  const p = new URLSearchParams();
  if (f.q) p.set("q", f.q);
  if (f.type) p.set("type", f.type);
  if (f.mode) p.set("mode", f.mode);
  if (f.fund_id) p.set("fund_id", f.fund_id);
  p.set("period", f.period || "this_fy");
  if (f.request_status) p.set("request_status", f.request_status);
  p.set("page", String(f.page || 1));
  p.set("per_page", String(f.per_page || 10));
  return p.toString();
}

// GET /api/mf/transactions?${buildQuery(filters)}
// credentials: "include"
```

When any filter except `page` changes, set `page` back to `1`.
