# Admin API Contract (Module 12)

## Scope
This document defines the frontend-facing contract used by admin modules.

## Standard Response Envelope
All admin endpoints are consumed as:

```json
{
  "message": "success",
  "data": {},
  "meta": {}
}
```

Contract rules:
- `message`: string status message.
- `data`: object, array, or Laravel paginator payload.
- `meta`: optional object for extra endpoint metadata (for example retention policy).

## Standard Error Envelope
Errors are normalized by `requestJson` / `requestAdminText` in [frontend/src/api.ts](frontend/src/api.ts):

```json
{
  "message": "Validation failed",
  "code": "optional_error_code",
  "errors": {
    "field": ["detail"]
  }
}
```

Normalized frontend error shape:
- `status`: HTTP status
- `message`: backend message (or fallback)
- `code`: optional backend code
- `details`: optional field errors map

## Standard Pagination Keys
List endpoints use:
- request: `page`, `per_page`
- response paginator fields: `current_page`, `per_page`, `total`, `last_page`

## Standard Filter/Sort Keys
Shared filter conventions:
- search: `search`
- sort: `sort_by`, `sort_dir`
- date range: `date_from`, `date_to`
- endpoint-specific filters keep snake_case names (for example `entity_type`, `account_status`, `stock_status`).

## Endpoint Summary
- Dashboard: `GET /api/admin/manage/dashboard`
- Products:
- `GET /api/admin/manage/products`
- `POST /api/admin/manage/products`
- `DELETE /api/admin/manage/products/{id}`
- `DELETE /api/admin/manage/products` (bulk ids)
- Categories:
- `GET /api/admin/manage/categories`
- `POST /api/admin/manage/categories`
- `DELETE /api/admin/manage/categories/{id}`
- Promotions:
- `GET /api/admin/manage/promotions`
- `POST /api/admin/manage/promotions`
- `DELETE /api/admin/manage/promotions/{id}`
- Orders:
- `GET /api/admin/manage/orders`
- `PUT /api/admin/manage/orders/{id}/status`
- Settings:
- `GET /api/admin/manage/settings`
- `POST /api/admin/manage/settings`
- Users:
- `GET /api/admin/manage/users`
- `POST /api/admin/manage/users`
- `DELETE /api/admin/manage/users/{id}`
- `POST /api/admin/manage/users/{id}/reset-password`
- `GET /api/admin/manage/users/{id}/activity`
- Roles:
- `GET /api/admin/manage/roles`
- `POST /api/admin/manage/roles`
- `DELETE /api/admin/manage/roles/{id}`
- `GET /api/admin/manage/roles/{id}/history`
- Activity Logs:
- `GET /api/admin/manage/activity-logs`
- `GET /api/admin/manage/activity-logs/export`

## Notes
- Query strings for admin lists are now built through shared helpers in [frontend/src/api.ts](frontend/src/api.ts) to enforce the same key naming across modules.
- API wrappers remain backward compatible with nested `data.data` paginator payloads.
