# Ticket Comment Attachments - Frontend Guide

## What We Built

Comments now support image and document attachments. The API returns enriched attachment data so you don't need extra calls.

## Upload Flow

### 1. Upload File First
```http
POST /api/v1/documents/upload
Content-Type: multipart/form-data

file: <binary>
entity_type: "ticket"
entity_id: "ticket-uuid"
document_type: "comment_attachment"
document_category: "operational"
```

**Response:**
```json
{
  "id": "doc-uuid",
  "file_name": "photo.jpg",
  "file_url": "https://storage.../photo.jpg"
}
```

### 2. Create Comment with Attachment
```http
POST /api/v1/tickets/{ticket_id}/comments

{
  "comment_text": "Found this issue",
  "is_internal": true,
  "comment_type": "issue",
  "attachment_document_ids": ["doc-uuid"]
}
```

## Response Structure

```json
{
  "id": "comment-uuid",
  "comment_text": "Found this issue",
  "attachment_document_ids": ["doc-uuid"],
  "attachments": [
    {
      "id": "doc-uuid",
      "file_name": "photo.jpg",
      "file_type": "image/jpeg",
      "file_url": "https://storage.../photo.jpg",
      "file_size": 245678,
      "is_image": true
    }
  ]
}
```

## Key Fields

- `attachment_document_ids`: Array of document UUIDs
- `attachments`: Full attachment details (auto-populated)
- `attachments[].is_image`: Boolean flag - use this to filter images vs other files
- `attachments[].file_url`: Direct URL - ready to use in `<img>` or download links

## Multiple Attachments

```json
{
  "comment_text": "Before and after photos",
  "attachment_document_ids": ["doc-1", "doc-2", "doc-3"]
}
```

All attachments returned in `attachments` array.

## Mobile Example (React Native)

```typescript
// Upload image
const formData = new FormData();
formData.append('file', {
  uri: photo.uri,
  type: 'image/jpeg',
  name: 'photo.jpg'
});
formData.append('entity_type', 'ticket');
formData.append('entity_id', ticketId);
formData.append('document_type', 'comment_attachment');

const uploadRes = await api.post('/documents/upload', formData);

// Create comment
await api.post(`/tickets/${ticketId}/comments`, {
  comment_text: "Found damaged cable",
  is_internal: true,
  comment_type: "issue",
  attachment_document_ids: [uploadRes.data.id]
});
```

## Web Example (React)

```typescript
// Upload file
const formData = new FormData();
formData.append('file', file);
formData.append('entity_type', 'ticket');
formData.append('entity_id', ticketId);
formData.append('document_type', 'comment_attachment');

const uploadRes = await api.post('/documents/upload', formData);

// Create comment
await api.post(`/tickets/${ticketId}/comments`, {
  comment_text: "See attached diagram",
  is_internal: true,
  comment_type: "resolution",
  attachment_document_ids: [uploadRes.data.id]
});
```

## Display Logic

```typescript
// Separate images from other files
const images = comment.attachments.filter(a => a.is_image);
const files = comment.attachments.filter(a => !a.is_image);

// Render images
images.forEach(img => {
  // <img src={img.file_url} alt={img.file_name} />
});

// Render file links
files.forEach(file => {
  // <a href={file.file_url} download={file.file_name}>{file.file_name}</a>
});
```

## Notes

- Upload files BEFORE creating comment
- Max file size and allowed types handled by `/documents/upload` endpoint
- Images auto-detected via MIME type (`image/*`)
- File URLs are permanent and CDN-backed
- No need to fetch attachment details separately - included in comment response