1d48f0befa
- README with quick start, package overview, links to docs - docs/setup.md — prerequisites, env vars, installation, running, testing - docs/architecture.md — monorepo structure, backend/frontend design - docs/api.md — full endpoint reference with permissions - docs/database.md — schema overview, migrations, multi-tenancy - docs/testing.md — test runner, suites, writing tests - Updated .env.example with all supported variables
147 lines
6.2 KiB
Markdown
147 lines
6.2 KiB
Markdown
# 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 |
|