Engagement API

Endpoints pour les interactions utilisateur : reactions, vues, favoris et historique de visionnage.

Base URL : /api/v2

Vue d'ensemble

Feature	Description
Reactions	Like/Dislike sur le contenu
Views	Suivi des vues avec anti-abus
Favorites	Bookmarks utilisateur
Watch History	Historique de visionnage avec progression

---

Reactions

Endpoints

Methode	Endpoint	Description	Auth
POST	/reactions	Ajouter une reaction (toggle)	Oui
DELETE	/reactions/:mediaType/:mediaId	Supprimer une reaction	Oui
GET	/reactions/:mediaType/:mediaId	Obtenir la reaction de l'utilisateur	Oui
GET	/reactions/user	Toutes les reactions de l'utilisateur	Oui
POST	/reactions/toggle	Toggle reaction (like/dislike)	Oui
GET	/reactions/my	Mes reactions	Oui

POST /reactions

Ajouter ou modifier une reaction.

POST /api/v2/reactions
Authorization: Bearer <token>
Content-Type: application/json

{
  "mediaId": "uuid",
  "mediaType": "MOVIE",
  "type": "LIKE"
}

Reponse 201 Created (nouvelle reaction)

{
  "id": "uuid",
  "mediaId": "uuid",
  "mediaType": "MOVIE",
  "type": "LIKE",
  "createdAt": "2025-01-15T10:30:00.000Z"
}

Comportement toggle :

• Meme reaction = supprime la reaction
• Reaction differente = change la reaction (LIKE vers DISLIKE ou inversement)

---

Views

Endpoints

Methode	Endpoint	Description	Auth
POST	/views	Enregistrer une vue	Non*
GET	/views/count/:mediaType/:mediaId	Stats de vues	Non
GET	/views/stats/:mediaType/:mediaId	Stats de vues	Non

*Auth optionnelle, mais recommandee pour un tracking precis.

POST /views

Enregistrer une vue de contenu.

POST /api/v2/views
Authorization: Bearer <token>
Content-Type: application/json

{
  "mediaId": "uuid",
  "mediaType": "MOVIE"
}

Reponse 201 Created (nouvelle vue)

{
  "counted": true,
  "viewCount": 125001
}

Reponse 200 OK (cooldown actif)

{
  "counted": false,
  "reason": "COOLDOWN",
  "cooldownRemaining": 1800
}

Protection anti-abus

Protection	Description
Cooldown	30 minutes entre vues du meme contenu
User tracking	userId, sessionId, ipAddress, userAgent
Deduplication	Combinaison unique des identifiants

---

Favorites

Endpoints

Methode	Endpoint	Description	Auth
GET	/favorites	Lister les favoris	Oui
POST	/favorites	Ajouter un favori	Oui
DELETE	/favorites/:mediaType/:mediaId	Supprimer un favori	Oui
DELETE	/favorites/:id	Supprimer un favori par ID	Oui
GET	/favorites/check/:mediaType/:mediaId	Verifier si favori	Oui

GET /favorites

Liste des favoris de l'utilisateur.

GET /api/v2/favorites?page=1&limit=10&mediaType=MOVIE
Authorization: Bearer <token>

Reponse 200 OK

{
  "data": [
    {
      "id": "uuid",
      "mediaId": "uuid",
      "mediaType": "MOVIE",
      "media": {
        "id": "uuid",
        "title": "Inception",
        "posterUrl": "https://..."
      },
      "createdAt": "2025-01-15T10:30:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 45
  }
}

GET /favorites/check/:mediaType/:mediaId

Verifier si un contenu est en favori.

GET /api/v2/favorites/check/MOVIE/uuid
Authorization: Bearer <token>

Reponse 200 OK

{
  "isFavorite": true,
  "favoriteId": "uuid"
}

---

Watch History

Endpoints

Methode	Endpoint	Description	Auth
GET	/watch-history	Historique de visionnage	Oui
POST	/watch-history	Ajouter/mettre a jour l'historique	Oui
GET	/watch-history/continue	Contenu "Continuer a regarder"	Oui
PATCH	/watch-history/:id	Mettre a jour la progression	Oui
DELETE	/watch-history/:id	Supprimer de l'historique	Oui
DELETE	/watch-history	Vider tout l'historique	Oui

POST /watch-history

Ajouter ou mettre a jour l'historique de visionnage.

POST /api/v2/watch-history
Authorization: Bearer <token>
Content-Type: application/json

{
  "mediaId": "uuid",
  "mediaType": "EPISODE",
  "progress": 1250,
  "duration": 2400
}

GET /watch-history/continue

Contenu "Continuer a regarder" (reprise de lecture).

GET /api/v2/watch-history/continue
Authorization: Bearer <token>

Reponse 200 OK

{
  "data": [
    {
      "mediaId": "uuid",
      "mediaType": "EPISODE",
      "media": {
        "title": "Breaking Bad S1E3",
        "posterUrl": "https://..."
      },
      "progress": 1250,
      "duration": 2400,
      "progressPercent": 52,
      "lastWatchedAt": "2025-01-15T10:30:00.000Z"
    }
  ]
}

Types de media supportes

enum MediaType {
  MOVIE     // Film
  SERIES    // Serie
  EPISODE   // Episode
  LIVETV    // Chaine TV
  RADIO     // Station radio
  PODCAST   // Podcast
  NEWS      // Article
  EVENT     // Evenement live
  REPLAY    // Replay
}

Codes d'erreur

Code	Message	Description
404	Content not found	Contenu introuvable
409	Already exists	Favori deja existant
429	Cooldown active	Trop de vues (attendre 30 min)