# Contrat d'API — PdfEditor

Document de référence **partagé** entre l'agent backend (Go) et l'agent frontend (Angular).
Toute évolution doit être répercutée des deux côtés.

Base URL : `/api`
Auth : JWT Bearer dans l'en-tête `Authorization: Bearer <access_token>`.
Format : JSON (sauf upload/download de fichier).

## Conventions
- Codes d'erreur : `400` (validation), `401` (non authentifié), `403` (interdit),
  `404` (introuvable), `409` (conflit, ex. email déjà pris), `500`.
- Corps d'erreur : `{ "error": "message lisible" }`.
- Dates : ISO 8601 (RFC 3339).
- Les `access_token` sont de courte durée (15 min). Les `refresh_token` permettent
  d'obtenir un nouveau couple de tokens.

## Authentification

### POST /api/auth/register
Req: `{ "email": "a@b.c", "password": "..." }`
Res `201`: `{ "user": { "id", "email", "created_at" }, "access_token", "refresh_token" }`

### POST /api/auth/login
Req: `{ "email", "password" }`
Res `200`: `{ "user": {...}, "access_token", "refresh_token" }`

### POST /api/auth/refresh
Req: `{ "refresh_token": "..." }`
Res `200`: `{ "access_token", "refresh_token" }`

### POST /api/auth/logout
Auth requise. Invalide le refresh token courant. Res `204`.

### GET /api/me
Auth requise. Res `200`: `{ "id", "email", "created_at" }`

## Documents
Toutes ces routes nécessitent l'authentification. Un utilisateur ne voit que ses
propres documents.

### GET /api/documents
Res `200`: `{ "documents": [ { "id", "name", "size", "created_at", "updated_at" } ] }`

### POST /api/documents
Upload d'un nouveau PDF. `multipart/form-data` :
- `file` : le binaire PDF (obligatoire)
- `name` : nom affiché (optionnel, défaut = nom du fichier)
Res `201`: `{ "id", "name", "size", "created_at", "updated_at" }`

### GET /api/documents/:id
Métadonnées. Res `200`: `{ "id", "name", "size", "created_at", "updated_at" }`

### GET /api/documents/:id/file
Renvoie le binaire PDF. `Content-Type: application/pdf`.

### PUT /api/documents/:id
Met à jour le PDF (après édition) et/ou le nom. `multipart/form-data` :
- `file` : nouveau binaire PDF (optionnel)
- `name` : nouveau nom (optionnel)
Res `200`: métadonnées à jour.

### DELETE /api/documents/:id
Res `204`.

## Santé
### GET /api/health
Res `200`: `{ "status": "ok" }` — utilisé par les healthchecks/monitoring.

## Modèle de données (backend)
- `users` : `id` (uuid), `email` (unique), `password_hash`, `created_at`
- `refresh_tokens` : `id`, `user_id`, `token_hash`, `expires_at`, `revoked`
- `documents` : `id` (uuid), `user_id` (fk), `name`, `file_path`, `size`,
  `created_at`, `updated_at`

## Notes d'intégration frontend
- Le frontend stocke `access_token` en mémoire et `refresh_token` de façon
  persistante ; un intercepteur HTTP ajoute le Bearer et tente un `/auth/refresh`
  sur `401`.
- En prod, nginx (image frontend) proxifie `/api/*` vers le service `backend:8080`.
  En dev (`docker-compose.local.yml`), même comportement via nginx, ou proxy
  Angular vers `http://localhost:8081`.