starr-philproperties/apps/api/controllers/admin/documentation/user_activity.md

User Activity Controller Documentation

File: controllers/admin/user_activity.controller.js
Base URL: /api/admin/activity and /api/admin/users/:id/activity
Guards: authenticate → requireAdmin() → adminLimiter

---

Table of Contents

• Get Global Activity Feed
• Get Per-User Activity

---

Notes

• user_activity rows are never soft-deleted — this is an append-only audit log.
• created_at is the timestamp column (no createdAt alias — Sequelize timestamps: false).
• The global feed endpoint joins the users table and enriches each row with full_name and avatar_url.
• The per-user endpoint skips the join for performance since user context is already known.

---

Activity Object Shape

{
  "activity_id": 1,
  "user_id": 42,
  "email": "user@example.com",
  "full_name": "Kenneth Obsequio",
  "avatar_url": "https://...",
  "acc_type": "admin",
  "action": "login",
  "entity_type": "session",
  "entity_id": 7,
  "details": { "session_id": 7, "reg_type": "system" },
  "created_at": "2026-06-21T08:00:00.000Z"
}

Common action Values

Action	Entity Type	Details Keys
login	session	session_id, reg_type
deactivate_user	user	target_email
lesson_read	lesson	lesson_uuid, status
submit_task	task	task_id
set_user_status	user	is_active
create_course	course	title
update_course	course	title
archive_course	course	—
create_task_list	task_list	name
create_advertisement	advertisement	type
grant_tier	tier	user_id, tier, plan_id
revoke_tier	tier	user_id, tier

---

Get Global Activity Feed

GET /api/admin/activity

Returns a paginated, reverse-chronological feed of all user activity across the system.

Query Parameters

Parameter	Type	Required	Description
page	number	No	Default: 1
limit	number	No	Default: 20, max: 100
action	string	No	Filter by exact action string (e.g. login)
from	date	No	ISO date — created_at >= from
to	date	No	ISO date — created_at <= to

Response 200

{
  "status": "success",
  "message": "Activity feed retrieved.",
  "data": {
    "total": 500,
    "page": 1,
    "totalPages": 25,
    "activities": [ ... ]
  }
}

---

Get Per-User Activity

GET /api/admin/users/:id/activity

Returns a paginated, reverse-chronological activity log for a single user.

Query Parameters

Same as global feed (page, limit, action, from, to).

Response 200

{
  "status": "success",
  "message": "User activity retrieved.",
  "data": {
    "total": 45,
    "page": 1,
    "totalPages": 3,
    "activities": [
      {
        "activity_id": 1,
        "user_id": 42,
        "session_id": null,
        "action": "update_course",
        "entity_type": "course",
        "entity_id": 3,
        "details": { "title": "Advanced JS" },
        "created_at": "2026-06-21T09:00:00.000Z"
      }
    ]
  }
}

Error Responses

Status	Message
400	Invalid User ID.
404	User not found.