# Profile Controller Documentation (Admin)

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

---

## Table of Contents
- [Get Profile](#get-profile)
- [Update Profile](#update-profile)
- [Upload Avatar](#upload-avatar)
- [Delete 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`
```json
{
  "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
```json
{
  "personal_info": {
    "name": {
      "given_name": "Kenneth",
      "last_name": "Obsequio"
    },
    "occupation": "Software Engineer",
    "date_of_birth": "1995-05-15"
  }
}
```

### Response `200`
```json
{
  "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`
```json
{
  "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`
```json
{ "status": "success", "message": "Avatar removed." }
```

### Error Responses
| Status | Message |
|--------|---------|
| `404` | `No avatar to remove.` |