# AURA LIVE — REST API Contract (v1)

Base URL: `http://localhost:4000/api/v1`

All responses are JSON:

```json
{ "success": true, "data": { } }
{ "success": false, "error": { "code": "VALIDATION_ERROR", "message": "..." } }
```

**Auth**: send `Authorization: Bearer <accessToken>`. Access token TTL 15 min; refresh via `POST /auth/refresh` (returns new access + rotated refresh token).

**Pagination**: `?page=1&limit=20` → `data: { items: [...], page, limit, total, total_pages }`

---

## Auth
| Method | Path | Body | Notes |
|---|---|---|---|
| POST | /auth/register | full_name, username, email, mobile?, password, confirm_password, date_of_birth?, terms_accepted | creates user + wallet (signup bonus per settings) |
| POST | /auth/login | identifier (username or email), password | returns `{ user, accessToken, refreshToken }` |
| POST | /auth/logout | refreshToken | revokes session |
| POST | /auth/refresh | refreshToken | token rotation |
| POST | /auth/verify-email | email, code | |
| POST | /auth/verify-mobile | mobile, code | |
| POST | /auth/forgot-password | email | |
| POST | /auth/reset-password | token, password | |
| GET  | /auth/me | — (auth) | current user + settings + wallet |

## Users
| Method | Path | Notes |
|---|---|---|
| GET | /users/me | profile + settings + wallet |
| PATCH | /users/me | full_name, bio, country, avatar_url, cover_url, settings{} |
| GET | /users/search?q=&page= | discover users |
| GET | /users/online | online users list |
| GET | /users/:id | public profile |
| POST | /users/:id/follow | |
| DELETE | /users/:id/follow | |
| POST | /users/:id/block | |
| DELETE | /users/:id/block | unblock |
| POST | /users/:id/report | reason, details |
| GET | /users/me/blocked | list blocked |
| GET | /users/me/followers | paginated |
| GET | /users/me/following | paginated |
| POST | /users/me/device | register push token (platform, device_uid, push_token) |
| PATCH | /users/me/settings | privacy/notification settings |

## Friends
| Method | Path | Notes |
|---|---|---|
| GET | /friends/requests | incoming pending |
| POST | /friends/:userId/request | send request |
| POST | /friends/requests/:id/accept | |
| POST | /friends/requests/:id/reject | |

## Rooms
| Method | Path | Notes |
|---|---|---|
| GET | /rooms?category=&filter=recommended|new|popular&q=&page= | discovery cards |
| POST | /rooms | name, category, language, description?, is_private?, password?, seat_count? |
| GET | /rooms/:id | detail incl. seats + members |
| PATCH | /rooms/:id | host/admin only |
| DELETE | /rooms/:id | close room (host/admin) |
| POST | /rooms/:id/join | password? |
| POST | /rooms/:id/leave | |
| GET | /rooms/:id/messages?before= | room chat history |
| POST | /rooms/:id/gifts | gift_id, recipient_id, quantity |

## Voice (LiveKit)
| Method | Path | Notes |
|---|---|---|
| POST | /rooms/:id/voice-token | returns `{ token, wsUrl, roomName }`; 401/403 on no permission; 503 `VOICE_NOT_CONFIGURED` when server creds missing |
| POST | /rooms/:id/seat-request | ask for a mic seat |
| GET | /rooms/:id/seat-requests | host/mod: pending requests |

## Conversations (DM)
| Method | Path | Notes |
|---|---|---|
| GET | /conversations | inbox with peer, last message, unread |
| POST | /conversations | peer_id (creates/fetches 1:1) |
| GET | /conversations/:id/messages?before=&page= | membership enforced |
| POST | /conversations/:id/messages | body, attachment_url? |
| POST | /conversations/:id/read | mark read |

## Wallet / coins / payments
| Method | Path | Notes |
|---|---|---|
| GET | /wallet | balance |
| GET | /wallet/transactions?page= | ledger |
| GET | /coin-packages | active packages |
| POST | /payments/orders | package_id → `{ order, providerPayload }` (Razorpay order id etc.) |
| GET | /payments/orders/:id | status |
| POST | /payments/verify | razorpay_order_id, razorpay_payment_id, razorpay_signature → credits coins after server-side signature verification |
| POST | /payments/webhook/:provider | raw-body signature verified; idempotent |

## Gifts
| Method | Path | Notes |
|---|---|---|
| GET | /gifts | grouped by category |
| GET | /gifts/transactions/sent | history |
| GET | /gifts/transactions/received | history |

## Store (frames / VIP)
| Method | Path | Notes |
|---|---|---|
| GET | /store/frames | catalog with owned_by_me |
| POST | /store/frames/:id/purchase | server validates balance & price |
| POST | /store/frames/:id/equip | must own |
| GET | /store/vip-plans | |
| POST | /store/vip/:planId/purchase | creates payment order |

## Social feed
| Method | Path | Notes |
|---|---|---|
| GET | /posts?page= | following + public feed |
| POST | /posts | content, media: [{url,type}] |
| GET | /posts/:id | |
| DELETE | /posts/:id | owner only |
| POST | /posts/:id/like | toggles |
| GET | /posts/:id/comments | |
| POST | /posts/:id/comments | content |

## Games
| Method | Path | Notes |
|---|---|---|
| GET | /games/types | available game types + metadata |
| POST | /games/lobbies | type, room_id? |
| POST | /games/lobbies/:id/join | |
| POST | /games/lobbies/:id/ready | |
| POST | /games/lobbies/:id/start | host only, min players |
| GET | /games/sessions/:id | state |
| POST | /games/sessions/:id/action | server-validated actions (roll, move, answer, flip, prompt_pick) |

## Notifications
| Method | Path | Notes |
|---|---|---|
| GET | /notifications?page=&unread= | |
| PATCH | /notifications/:id/read | |
| POST | /notifications/read-all | |

## Events & leaderboards
| Method | Path | Notes |
|---|---|---|
| GET | /events | active campaigns |
| GET | /leaderboards?scope=popular_rooms|top_hosts|gift_senders|gift_receivers|activity&period=weekly | |

## Moderation (user-facing)
| Method | Path | Notes |
|---|---|---|
| POST | /reports | target_type, target_id, reason, details |
| GET | /settings/privacy | community guidelines + policies content |

## Misc
| Method | Path | Notes |
|---|---|---|
| GET | /config/public | app settings subset for clients (app_name, maintenance_mode, etc.) |
| POST | /support/tickets | subject, message, email |
| POST | /account/delete-request | auth; queues deletion |

---

## Admin API (`/api/v1/admin/*`, admin JWT + role permission)
- POST /admin/login {email,password} → admin token
- GET /admin/dashboard → DashboardStats
- GET /admin/charts?type=user_growth|room_activity|engagement|gifts|coin_sales&days=30 → ChartPoint[]
- CRUD: /admin/users (search, view, suspend, reactivate, adjust-balance [writes audit log]), /admin/rooms (list, close), /admin/reports (list, resolve), /admin/gifts (CRUD), /admin/gift-categories, /admin/coin-packages (CRUD), /admin/orders (list), /admin/transactions (ledger list), /admin/frames (CRUD), /admin/vip-plans (CRUD), /admin/events (CRUD), /admin/notifications (broadcast), /admin/posts (moderate hide/remove), /admin/settings (get/patch key-values), /admin/roles (list/create/permissions), /admin/audit-logs, /admin/tickets (list, respond), /admin/health (system health), /admin/maintenance (toggle)
- All privileged writes recorded in admin_audit_logs.

## WebSocket (Socket.IO) — namespace `/`
Auth: `io({ auth: { token: <accessToken> } })`
Events (see @aura/shared-types socket-events.ts):
- client→server: room:join, room:leave, room:message, seat:request/approve/reject/leave, seat:lock, audio:state, typing:dm, game:action
- server→client: room:participant_joined/left, room:new_message, room:seats_updated, room:seat_requested, room:closed, room:kicked, gift:animation, dm:new, dm:read, notification:new, game:state, presence:update