Engagement (Comments & Reactions)

​

1. API Purpose

​

2. Endpoint Definition

​

3. Authentication Flow

• All engagement is tied to the parent_id or staff_id extracted from the token.
• skole_id scoping ensures users only engage with content within their school.

​

4. Request Structure

​

POST /parent-app/engagement/comment

{
  "entity_type": "activity",
  "entity_id": 88,
  "content": "Looking forward to the sports day!"
}

​

POST /parent-app/engagement/react

{
  "entity_type": "diary",
  "entity_id": 501,
  "reaction_type": "love"
}

​

GET /parent-app/engagement/comments/:type/:id

​

GET /parent-app/engagement/reactions/:type/:id

​

5. Response Structure

​

Success: Comment Posted (201 Created)

{
  "success": true,
  "message": "Comment added",
  "data": { "id": 1001, "content": "Looking forward to it!" }
}

​

Success: Comment List (200 OK)

{
  "success": true,
  "data": [
    {
      "id": 1,
      "content": "Looking forward to it!",
      "author_name": "Ravi Kumar",
      "created_at": "2024-03-10T12:00:00Z"
    }
  ]
}

​

Success: Reaction Toggled (200 OK)

{
  "success": true,
  "message": "Reaction updated",
  "data": { "reaction_type": "love", "active": true }
}

​

Success: Reaction Stats (200 OK)

{
  "success": true,
  "data": {
    "love": 15,
    "thumbs_up": 22,
    "user_reaction": "love"
  }
}

​

6. Error Responses

​

7. Security Considerations

• Unique Constraint: The database enforces a @@unique([entity_type, entity_id, parent_id, staff_id]) constraint to prevent duplicate reactions from the same user.
• Toggle Logic: If the same reaction_type is sent twice, the reaction is removed (unlike standard social platforms).

​

8. Token Usage

POST /parent-app/engagement/react
Authorization: Bearer <TOKEN>

​

9. Token Refresh

​

10. Logout / Session Invalidation

​

11. Usage Example (cURL)

curl -X POST http://localhost:3000/parent-app/engagement/comment \
-H "Authorization: Bearer <TOKEN>" \
-d '{"entity_type": "diary", "entity_id": 501, "content": "Done!"}'

​

12. Notes / Special Behaviors

• Cross-Module Linkage: The entity_type field allows one API to handle engagement for multiple modules without logic duplication.
• Moderation: Deleted comments (deleted_status = 1) are filtered out at the service layer during listing.