tm_panel/docs/client/Filestore Frontend Guide.md

# Frontend Guide: File Upload + Profile Image APIs

This is a simple reference for frontend integration with file upload, file retrieval, and setting profile image.

## Base URLs

- Admin APIs: `/admin/v1`
- Customer/Public APIs: `/api/v1`

All protected endpoints require:

- `Authorization: Bearer <access_token>`

---

## 1) Login (Admin)

Use this when you want to update admin user profile image.

### Request

- `POST /admin/v1/profile/login`
- `Content-Type: application/json`

```json
{
  "username": "admin",
  "password": "Admin1234"
}
```

### Response (success)

```json
{
  "success": true,
  "message": "Login successful",
  "data": {
    "user": {
      "id": "65bc1234567890abcdef1234",
      "profile_image": null
    },
    "access_token": "<jwt>",
    "refresh_token": "<jwt>",
    "expires_at": 1776783486
  }
}
```

---

## 2) Upload File (GridFS)

Use multipart form upload.

### Admin route

- `POST /admin/v1/files/upload`

### Customer route

- `POST /api/v1/files/upload`

### Form fields

- `file` (required, File)
- `category` (optional, string), example: `profile_images`
- `tags` (optional, repeatable), example: `user`, `profile`
- `description` (optional, string)

### Response (success)

```json
{
  "file_id": "69e7899c2053abd3fa5433e0",
  "filename": "avatar.png",
  "content_type": "image/png",
  "size": 123456,
  "message": "File uploaded successfully"
}
```

---

## 3) Get File Info

- `GET /admin/v1/files/{file_id}/info`
- `GET /api/v1/files/{file_id}/info`

### Response (success)

```json
{
  "file_id": "69e7899c2053abd3fa5433e0",
  "filename": "avatar.png",
  "content_type": "image/png",
  "size": 123456,
  "uploaded_by": "65bc1234567890abcdef1234",
  "uploaded_at": "2026-04-21T14:28:44.787Z",
  "category": "profile_images",
  "tags": ["user", "profile"],
  "description": "sample profile photo"
}
```

---

## 4) Download File

- `GET /admin/v1/files/{file_id}/download`
- `GET /api/v1/files/{file_id}/download`

Returns file binary stream.

Useful for image URL:

- `http://localhost:8080/admin/v1/files/<file_id>/download`
- or `http://localhost:8080/api/v1/files/<file_id>/download`

---

## 5) Set Admin User Profile Image

Upload does not update user profile automatically.  
After upload, call profile update endpoint with the download URL.

### Request

- `PUT /admin/v1/profile`
- `Content-Type: application/json`

```json
{
  "profile_image": "http://localhost:8080/admin/v1/files/69e7899c2053abd3fa5433e0/download"
}
```

### Response

- Success: standard success envelope with updated user data
- Failure example:

```json
{
  "success": false,
  "message": "Bad Request",
  "error": {
    "code": "BAD_REQUEST",
    "message": "failed to update user"
  }
}
```

---

## 6) Verify Profile

- `GET /admin/v1/profile`

Check:

- `data.profile_image` is now populated with file URL.

---

## Common Errors

- `401 Unauthorized`: missing/expired token
- `413 Request Entity Too Large`: file too big
- `400 Unsupported file type` or validation error
- `404 File not found`: wrong `file_id`

---

## Suggested Frontend Flow (Admin)

1. Login -> save `access_token`
2. Upload image -> get `file_id`
3. Build URL `.../admin/v1/files/{file_id}/download`
4. Update profile with `profile_image` URL
5. Refresh profile screen via `GET /admin/v1/profile`

---

## Customer: Company Documents Upload

Customers can upload company documents using customer auth token.

### Upload endpoint

- `POST /api/v1/files/upload`

### Recommended form-data for company docs

- `file`: actual document file
- `category`: `company_documents`
- `tags`: repeatable. Suggested:
  - `company`
  - `document`
  - `<doc_type>` (example: `tax_certificate`, `registration`, `license`)
- `description`: human-readable note, example: `Company tax certificate 2026`

### Example curl

```bash
CUSTOMER_TOKEN="<customer_access_token>"

curl -X POST "http://localhost:8080/api/v1/files/upload" \
  -H "Authorization: Bearer ${CUSTOMER_TOKEN}" \
  -F "file=@/absolute/path/to/company-doc.pdf" \
  -F "category=company_documents" \
  -F "tags=company" \
  -F "tags=document" \
  -F "tags=tax_certificate" \
  -F "description=Company tax certificate 2026"
```

### Response

```json
{
  "file_id": "69e8abcd2053abd3fa5433e1",
  "filename": "company-doc.pdf",
  "content_type": "application/pdf",
  "size": 245632,
  "message": "File uploaded successfully"
}
```

### Fetch company docs list

Use list with category filter:

- `GET /api/v1/files?category=company_documents&limit=50&skip=0`

You can also filter by tags:

- `GET /api/v1/files?category=company_documents&tags=tax_certificate`

### Download company doc

- `GET /api/v1/files/{file_id}/download`

### Important current behavior

- Upload works for customers and stores `uploaded_by` as `customer_id`.
- Company now supports `document_file_ids` for mapping GridFS files.

### Attach uploaded documents to company

Use admin company update endpoint after collecting uploaded `file_id` values:

- `PUT /admin/v1/companies/{company_id}`

Request body includes regular company fields plus `document_file_ids`:

```json
{
  "name": "Opplens",
  "type": "private",
  "registration_number": "1234567890",
  "tax_id": "1234567890",
  "industry": "Technology",
  "document_file_ids": [
    "69e8abcd2053abd3fa5433e1",
    "69e8abcd2053abd3fa5433e2"
  ]
}
```

`document_file_ids` is also returned in:

- `GET /admin/v1/companies/{id}`
- `GET /api/v1/companies` (customer "my company" profile)