# API Reference

> **Status:** This document tracks the API contract assumed by the frontend.
> The backend team should treat this as the **expected contract** and update
> it in lock-step as endpoints land. Each endpoint section lists its current
> implementation status:
>
> | Status      | Meaning                                                   |
> | ----------- | --------------------------------------------------------- |
> | 🟡 Planned  | Frontend is using **dummy data** until the endpoint ships |
> | 🟢 Live     | Endpoint is implemented; dummy fallback only on error      |
> | 🔴 Deprecated | Endpoint is being retired                                |

All endpoints share the conventions below.

---

## Conventions

**Base URL**: configured via `NEXT_PUBLIC_API_URL`. Default `http://localhost:4000/api`.

**Auth**: bearer token in `Authorization: Bearer <token>` header. Tokens are
issued by `POST /auth/login` and stored in `localStorage` under `dj.auth.token`.

**Response envelope**:

```json
{ "success": true,  "data": <T>,                 "message": "optional" }
{ "success": false, "data": null, "message": "...", "errors": { "field": ["err"] } }
```

The frontend's `apiFetch` helper auto-unwraps `data`, so service functions
return `T` directly.

**Pagination**: list endpoints return:

```ts
type Paginated<T> = {
  items: T[];
  total: number;
  page: number;
  pageSize: number;
  pageCount: number;
};
```

Query parameters supported on every list endpoint:
`q`, `page`, `pageSize`, `sortBy`, `sortOrder` (`asc` | `desc`).

**Money**: JPY values are integers (yen). Other currencies in their major
unit (USD dollars). The frontend formats via `formatJPY` / `formatUSD`.

**IDs**: opaque strings.

**Timestamps**: ISO-8601 strings (`2026-04-22T15:30:00Z`).

---

## Authentication 🟡 Planned

| Method | Path           | Purpose         |
| ------ | -------------- | --------------- |
| POST   | `/auth/login`  | Email + password login |
| POST   | `/auth/logout` | Invalidate session |
| GET    | `/auth/me`     | Current admin user |

**Login request**

```json
{ "email": "akira@dolphinjapan.com", "password": "••••••••" }
```

**Login response**

```json
{ "token": "eyJhbGciOi...", "user": { "id": "au-1", "name": "...", "role": "admin", "...": "..." } }
```

---

## Vehicles (cars) 🟡 Planned

| Method | Path                     | Purpose                       |
| ------ | ------------------------ | ----------------------------- |
| GET    | `/vehicles`              | Public list (filterable)      |
| GET    | `/vehicles/{id-or-slug}` | Public detail                 |
| POST   | `/admin/vehicles`        | Admin create                  |
| PUT    | `/admin/vehicles/{id}`   | Admin update                  |
| DELETE | `/admin/vehicles/{id}`   | Admin delete                  |

**Filter params** for `GET /vehicles`:
`q`, `brandId`, `modelId`, `bodyStyleId`, `colorId`, `yearFrom`, `yearTo`,
`priceMin`, `priceMax`, `fuelType`, `transmission`, `status`, `page`,
`pageSize`, `sortBy` (`price` | `year` | `mileage` | `createdAt`),
`sortOrder`.

**Vehicle shape** – see [`src/features/vehicles/types/vehicle.types.ts`](../src/features/vehicles/types/vehicle.types.ts).

---

## Brands 🟡 Planned

| Method | Path                  |
| ------ | --------------------- |
| GET    | `/brands`             |
| POST   | `/admin/brands`       |
| PUT    | `/admin/brands/{id}`  |
| DELETE | `/admin/brands/{id}`  |

## Models 🟡 Planned

| Method | Path                      |                          |
| ------ | ------------------------- | ------------------------ |
| GET    | `/models?brandId={id}`    | optional `brandId` filter |
| POST   | `/admin/models`           |                          |
| PUT    | `/admin/models/{id}`      |                          |
| DELETE | `/admin/models/{id}`      |                          |

## Body styles, Colors 🟡 Planned

Same CRUD pattern under `/body-styles` and `/colors`.

---

## Vehicle Inquiries 🟡 Planned

| Method | Path                          | Purpose                  |
| ------ | ----------------------------- | ------------------------ |
| POST   | `/inquiries`                  | Public — submit inquiry  |
| GET    | `/admin/inquiries`            | Admin list               |
| PATCH  | `/admin/inquiries/{id}`       | Update status            |
| DELETE | `/admin/inquiries/{id}`       | Delete                   |

**Inquiry shape** – see [`src/features/inquiry/types/inquiry.types.ts`](../src/features/inquiry/types/inquiry.types.ts).

---

## Custom Orders 🟡 Planned

| Method | Path                       | Purpose                   |
| ------ | -------------------------- | ------------------------- |
| POST   | `/orders/custom`           | Public — submit request   |
| GET    | `/admin/orders`            | Admin list                |
| PATCH  | `/admin/orders/{id}`       | Update status             |
| DELETE | `/admin/orders/{id}`       | Delete                    |

---

## Contact Messages 🟡 Planned

| Method | Path                          | Purpose                |
| ------ | ----------------------------- | ---------------------- |
| POST   | `/contact`                    | Public — submit message |
| GET    | `/admin/contacts`             | Admin list             |
| PATCH  | `/admin/contacts/{id}`        | Update status          |
| DELETE | `/admin/contacts/{id}`        | Delete                 |

---

## Payments 🟡 Planned (admin only)

| Method | Path                          |
| ------ | ----------------------------- |
| GET    | `/admin/payments`             |
| POST   | `/admin/payments`             |
| PUT    | `/admin/payments/{id}`        |
| DELETE | `/admin/payments/{id}`        |

---

## Gallery 🟡 Planned

| Method | Path                            |                    |
| ------ | ------------------------------- | ------------------ |
| GET    | `/gallery`                      | public list        |
| POST   | `/admin/gallery`                | accepts `FormData` for image upload |
| PUT    | `/admin/gallery/{id}`           |                    |
| DELETE | `/admin/gallery/{id}`           |                    |

---

## FAQ 🟡 Planned

| Method | Path                  |
| ------ | --------------------- |
| GET    | `/faqs`               |
| POST   | `/admin/faqs`         |
| PUT    | `/admin/faqs/{id}`    |
| DELETE | `/admin/faqs/{id}`    |

---

## Pricing & Quote Calculator 🟡 Planned

| Method | Path                                | Purpose                          |
| ------ | ----------------------------------- | -------------------------------- |
| GET    | `/admin/pricing/rules`              | List shipping/insurance rules    |
| POST   | `/admin/pricing/rules`              | Create rule                      |
| PUT    | `/admin/pricing/rules/{id}`         | Update rule                      |
| DELETE | `/admin/pricing/rules/{id}`         | Delete rule                      |
| POST   | `/pricing/calculate`                | Public — calculate CIF quote     |

---

## Admin Users & Permissions 🟡 Planned

| Method | Path                                    | Purpose                  |
| ------ | --------------------------------------- | ------------------------ |
| GET    | `/admin/users/admins`                   | List admins              |
| GET    | `/admin/users/editors`                  | List editors             |
| POST   | `/admin/users`                          | Create                   |
| PUT    | `/admin/users/{id}`                     | Update                   |
| DELETE | `/admin/users/{id}`                     | Delete                   |
| GET    | `/admin/permissions`                    | List permission keys     |
| GET    | `/admin/permissions/roles`              | Role → permission matrix |
| PUT    | `/admin/permissions/roles/{role}`       | Update permissions for a role |

---

## Dashboard 🟡 Planned

| Method | Path                              | Purpose                |
| ------ | --------------------------------- | ---------------------- |
| GET    | `/admin/dashboard/stats`          | KPI counters           |

Returns the [`DashboardStats`](../src/features/admin/types/admin.types.ts) shape.

---

## Updating this document

When the backend ships an endpoint:

1. Flip its status from 🟡 → 🟢 here.
2. Update the request/response example if the contract drifted.
3. Adjust the corresponding feature service / types if needed.
4. Once **all** endpoints in a feature are 🟢, set
   `NEXT_PUBLIC_USE_DUMMY_FALLBACK=false` in deploy environments to surface
   real failures instead of silently falling back to dummy data.