# API Reference

Base URL: `http://localhost:8000/v1`

All authenticated endpoints require `Authorization: Bearer <token>`. Registration and login require `X-Company-ID` header.

## Pagination

Every list endpoint accepts:

| Param | Default | Description |
|-------|---------|-------------|
| `page` | `1` | Page number |
| `limit` | `25` | Items per page (max 100) |
| `q` | — | Search query (ilike across relevant columns) |
| `sort` | varies | Sort field name |
| `order` | `asc` | `asc` or `desc` |

Response shape:

```json
{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 142,
    "totalPages": 6
  }
}
```

## Auth

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| POST | `/auth/register` | No (needs `X-Company-ID`) | Create user account |
| POST | `/auth/login` | No | Login, returns JWT |
| GET | `/auth/me` | Yes | Current user profile |
| PATCH | `/auth/me` | Yes | Update profile (firstName, lastName) |
| POST | `/auth/change-password` | Yes | Change password |
| POST | `/auth/reset-password/:userId` | Yes (`users.admin`) | Generate password reset link |

## Accounts

| Method | Path | Permission | Description |
|--------|------|------------|-------------|
| GET | `/accounts` | `accounts.view` | List accounts (paginated, searchable) |
| POST | `/accounts` | `accounts.edit` | Create account |
| GET | `/accounts/:id` | `accounts.view` | Get account |
| PATCH | `/accounts/:id` | `accounts.edit` | Update account |
| DELETE | `/accounts/:id` | `accounts.admin` | Soft-delete account |

## Members

| Method | Path | Permission | Description |
|--------|------|------------|-------------|
| GET | `/members` | `accounts.view` | List all members (paginated) |
| GET | `/accounts/:id/members` | `accounts.view` | List members for account |
| POST | `/accounts/:id/members` | `accounts.edit` | Create member |
| GET | `/members/:id` | `accounts.view` | Get member |
| PATCH | `/members/:id` | `accounts.edit` | Update member |
| DELETE | `/members/:id` | `accounts.admin` | Delete member |
| POST | `/members/:id/move` | `accounts.edit` | Move member to another account |

## Member Sub-Resources

| Method | Path | Permission | Description |
|--------|------|------------|-------------|
| GET | `/members/:id/identifiers` | `accounts.view` | List identifiers |
| POST | `/members/:id/identifiers` | `accounts.edit` | Create identifier |
| PATCH | `/identifiers/:id` | `accounts.edit` | Update identifier |
| DELETE | `/identifiers/:id` | `accounts.admin` | Delete identifier |
| GET | `/accounts/:id/payment-methods` | `accounts.view` | List payment methods |
| POST | `/accounts/:id/payment-methods` | `accounts.edit` | Create payment method |
| PATCH | `/payment-methods/:id` | `accounts.edit` | Update payment method |
| DELETE | `/payment-methods/:id` | `accounts.admin` | Delete payment method |
| GET | `/accounts/:id/tax-exemptions` | `accounts.view` | List tax exemptions |
| POST | `/accounts/:id/tax-exemptions` | `accounts.edit` | Create tax exemption |
| PATCH | `/tax-exemptions/:id` | `accounts.edit` | Update tax exemption |
| DELETE | `/tax-exemptions/:id` | `accounts.admin` | Delete tax exemption |
| GET | `/accounts/:id/processor-links` | `accounts.view` | List processor links |
| POST | `/accounts/:id/processor-links` | `accounts.edit` | Create processor link |
| PATCH | `/processor-links/:id` | `accounts.edit` | Update processor link |
| DELETE | `/processor-links/:id` | `accounts.admin` | Delete processor link |

## Users & RBAC

| Method | Path | Permission | Description |
|--------|------|------------|-------------|
| GET | `/users` | `users.view` | List users (paginated, includes roles) |
| PATCH | `/users/:id/status` | `users.admin` | Enable/disable user |
| GET | `/users/:id/roles` | `users.view` | Get user's roles |
| POST | `/users/:id/roles` | `users.edit` | Assign role to user |
| DELETE | `/users/:id/roles/:roleId` | `users.edit` | Remove role from user |
| GET | `/permissions` | `users.view` | List all permissions |
| GET | `/roles` | `users.view` | List roles (paginated) |
| GET | `/roles/all` | `users.view` | List all roles (unpaginated, for dropdowns) |
| GET | `/roles/:id` | `users.view` | Get role with permissions |
| POST | `/roles` | `users.admin` | Create custom role |
| PATCH | `/roles/:id` | `users.admin` | Update role |
| DELETE | `/roles/:id` | `users.admin` | Delete custom role |
| GET | `/me/permissions` | Yes | Current user's permissions + roles |

## Files

| Method | Path | Permission | Description |
|--------|------|------------|-------------|
| GET | `/files?entityType=&entityId=` | `files.view` | List files for entity |
| POST | `/files` | `files.upload` | Upload file (multipart) |
| GET | `/files/:id` | `files.view` | Get file metadata |
| GET | `/files/serve/*` | `files.view` | Serve file content |
| DELETE | `/files/:id` | `files.delete` | Delete file |

Upload accepts multipart form with fields: `file`, `entityType`, `entityId`, `category`.

Valid entity types: `user`, `member`, `member_identifier`, `product`, `rental_agreement`, `repair_ticket`.

## Products & Inventory

| Method | Path | Permission | Description |
|--------|------|------------|-------------|
| GET | `/products` | `inventory.view` | List products (paginated) |
| POST | `/products` | `inventory.edit` | Create product |
| GET | `/products/:id` | `inventory.view` | Get product |
| PATCH | `/products/:id` | `inventory.edit` | Update product |
| DELETE | `/products/:id` | `inventory.admin` | Delete product |
| GET | `/categories` | `inventory.view` | List categories |
| POST | `/categories` | `inventory.edit` | Create category |
| GET | `/suppliers` | `inventory.view` | List suppliers |
| POST | `/suppliers` | `inventory.edit` | Create supplier |

## Lookup Tables

| Method | Path | Permission | Description |
|--------|------|------------|-------------|
| GET | `/lookups/unit-statuses` | `inventory.view` | List unit statuses |
| POST | `/lookups/unit-statuses` | `inventory.admin` | Create custom status |
| GET | `/lookups/item-conditions` | `inventory.view` | List item conditions |
| POST | `/lookups/item-conditions` | `inventory.admin` | Create custom condition |

## Health

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/health` | No | Health check |