# API Documentation

Base path: `/api`

All business routes use JSON and require a JWT bearer token unless explicitly marked public.

## Authentication

| Method | Route | Purpose |
|---|---|---|
| POST | `/auth/bootstrap-owner` | One-time first Owner setup using `BOOTSTRAP_TOKEN` |
| POST | `/auth/login` | Email, phone or employee ID login |
| POST | `/auth/refresh` | Rotate refresh/access tokens |
| POST | `/auth/logout` | Revoke refresh session |
| GET | `/auth/me` | Current user profile |
| POST | `/auth/change-password` | Change own password |
| POST | `/auth/forgot-password` | Accept password-reset request |
| POST | `/auth/admin/reset-user-password` | Owner/Admin temporary-password reset |

## Core business APIs

| Method / Route | Purpose |
|---|---|
| `GET /dashboard` | Role-aware KPI dashboard |
| `GET,POST /customers` | Customer CRM list/create |
| `GET,PATCH /customers/:id` | Customer detail/update |
| `GET /products` | Product master alias |
| `GET /parts` | Spare-parts inventory alias |
| `GET /stock/products` | Stock product search |
| `GET,POST /stock/movements` | Stock movement ledger and controlled adjustment |
| `GET,POST /service-tickets` | Ticket list/create |
| `POST /service-tickets/:id/assign` | Assign engineer and trigger notification |
| `POST /service-tickets/:id/start` | Start field job with optional GPS |
| `POST /service-tickets/:id/note` | Add service note |
| `POST /service-tickets/:id/complete` | Complete job, parts issue, payment/signature metadata |
| `GET,POST /engineers` | Engineer list/create |
| `GET /engineers/:id/schedule` | Engineer schedule |
| `GET /machines` | Machine register |
| `GET /invoices` | Invoice list |
| `GET,POST /payments` | Payment list/create |
| `GET /agreements` | Agreement list |
| `GET /ledgers/daily` | Daily ledger |
| `GET /ledgers/customer` | Customer ledger |
| `GET /ledgers/supplier` | Supplier ledger |
| `GET /cash-bank` | Cash/bank/MFS accounts |
| `GET /suppliers` | Supplier master |
| `GET /import-orders` | Foreign purchase/import orders |
| `GET /lc-tt` | LC/TT position |
| `GET /shipments` | Shipment tracking |
| `GET /landed-cost` | Landed-cost report |
| `GET /reports/:reportName` | Filtered business reports |
| `POST /files` | Protected upload |
| `GET /files/:id` | Protected file retrieval |

## Notification APIs

| Method | Route | Purpose |
|---|---|---|
| GET | `/notifications` | Current user's in-app notifications |
| POST | `/notifications/:id/read` | Mark notification read |
| POST | `/notifications/devices` | Idempotently register Expo push token for signed-in user |
| DELETE | `/notifications/devices` | Disable a device push token |
| POST | `/notifications/test` | Owner/Admin test push to own registered devices |

`POST /notifications/devices` body:

```json
{
  "token": "ExpoPushToken[...]",
  "platform": "android",
  "deviceName": "Engineer phone",
  "deviceModel": "Android device model",
  "appVersion": "1.1.0"
}
```

## Sync APIs

| Method | Route | Purpose |
|---|---|---|
| GET | `/sync/pull?after=<sequence>` | Pull ordered server sync events |
| POST | `/sync/push` | Apply idempotent offline actions |
| GET | `/health` | Database-aware health check |