starr-philproperties/controllers/admin/documentation/profile.md

Profile Controller Documentation (Admin)

File: controllers/admin/profile.controller.js
Base URL: /api/admin/profile
Guards: authenticate → requireAdmin() → adminLimiter

---

Table of Contents

• Get Profile
• Update Profile
• Upload Avatar
• Delete Avatar

---

Notes

• All endpoints are self-service — they operate on the currently authenticated admin (req.user.user_id).
• password, otp_code, and otp_expires_at are always excluded from responses.
• Avatar files are stored in S3 via s3.service. The old avatar is deleted before upload.

---

Get Profile

GET /api/admin/profile

Returns the authenticated admin's full user record.

Response 200

{
  "status": "success",
  "message": "Profile retrieved.",
  "data": {
    "user_id": 1,
    "email": "admin@example.com",
    "is_active": true,
    "is_verified": true,
    "reg_type": "system",
    "acc_type": "admin",
    "personal_info": {
      "name": {
        "given_name": "Kenneth",
        "middle_name": null,
        "last_name": "Obsequio",
        "extension_name": null,
        "full_name": "Kenneth Obsequio"
      },
      "occupation": null,
      "addresses": [],
      "phone_number": [],
      "date_of_birth": null,
      "avatar": {
        "url": "https://...",
        "uuid": "storage-key",
        "name": "avatar.jpg",
        "mime_type": "image/jpeg",
        "size": 204800
      }
    },
    "createdAt": "2025-10-06T00:00:00.000Z",
    "updatedAt": "2026-06-18T00:00:00.000Z"
  }
}

---

Update Profile

PUT /api/admin/profile

Deep-merges personal_info — top-level keys and name sub-keys are merged separately. Existing keys not present in the request body are preserved.

Request Body

{
  "personal_info": {
    "name": {
      "given_name": "Kenneth",
      "last_name": "Obsequio"
    },
    "occupation": "Software Engineer",
    "date_of_birth": "1995-05-15"
  }
}

Response 200

{
  "status": "success",
  "message": "Profile updated.",
  "data": { ... }
}

---

Upload Avatar

POST /api/admin/profile/avatar

Uploads (or replaces) the admin's avatar via multipart/form-data.

• Old avatar is deleted from S3 before uploading the new one.
• Avatar metadata is stored in personal_info.avatar.

Request

Content-Type: multipart/form-data

Field	Type	Required	Description
file	file	Yes	Image file (handled by avatar_upload.middleware)

Response 200

{
  "status": "success",
  "message": "Avatar updated.",
  "data": { ... }
}

Error Responses

Status	Message
400	No file provided.

---

Delete Avatar

DELETE /api/admin/profile/avatar

Removes the admin's avatar from S3 and sets personal_info.avatar to null.

Response 200

{ "status": "success", "message": "Avatar removed." }

Error Responses

Status	Message
404	No avatar to remove.