src/shared/modules/upload/uploadcare/UPLOADCARE_SETUP.md

# 🚀 Uploadcare Integration Guide

## 📋 Table of Contents

1. [Overview](#overview)
2. [Setup Instructions](#setup-instructions)
3. [API Endpoints](#api-endpoints)
4. [Testing with Postman](#testing-with-postman)
5. [Viewing Uploaded Files](#viewing-uploaded-files)
6. [Examples](#examples)

---

## 🎯 Overview

This integration uses **Uploadcare** with **secure signed uploads** enabled. We have 3 separate projects configured:

| Project                      | File Type  | Public Key                | Use Case                        |
| ---------------------------- | ---------- | ------------------------- | ------------------------------- |
| Streamflix Backend Image     | `IMAGE`    | `8460d7f9bdsc79569e82cec` | Images (JPG, PNG, GIF, etc.)    |
| Streamflix Backend Videos    | `VIDEO`    | `d92b2e314264sc80583f6b`  | Videos (MP4, AVI, MOV, etc.)    |
| Streamflix Backend Documents | `DOCUMENT` | `70e723d3652esxs3ec1f7a2` | Documents (PDF, DOC, TXT, etc.) |

**Key Features:**

- ✅ Secure signed uploads (prevents unauthorized uploads)
- ✅ Separate projects for different file types
- ✅ Automatic CDN delivery via `ucarecdn.com`
- ✅ Delete files by URL

---

## 🛠️ Setup Instructions

### 1. Environment Variables

Already configured in `.env`:

```env
# Uploadcare Storage Configuration
UPLOADCARE_IMAGE_PUBLIC_KEY=your_image_project_public_key
UPLOADCARE_IMAGE_PRIVATE_KEY=your_image_project_private_key

UPLOADCARE_VIDEO_PUBLIC_KEY=your_video_project_public_key
UPLOADCARE_VIDEO_PRIVATE_KEY=your_video_project_private_key

UPLOADCARE_DOCUMENT_PUBLIC_KEY=your_document_project_public_key
UPLOADCARE_DOCUMENT_PRIVATE_KEY=your_document_project_private_key
```

### 2. Enable Signed Uploads

In your Uploadcare dashboard for each project:

1. Go to **Settings → Security**
2. Enable **"Secure uploads"** toggle

### 3. Start Your Server

```bash
npm run start:dev
```

Endpoints available at:

- `http://localhost:5119/uploadcare/signed-upload`
- `http://localhost:5119/uploadcare/by-url`

---

## 📡 API Endpoints

### 1. Get Signed Upload Parameters

**Endpoint:** `GET /uploadcare/signed-upload`

**Query Parameters:**

- `type` (optional): `IMAGE`, `VIDEO`, or `DOCUMENT` (default: IMAGE)

**Example:**

```
GET http://localhost:5119/uploadcare/signed-upload?type=IMAGE
```

**Response:**

```json
{
  "publicKey": "8460d7f9b79569e82cecssas",
  "expire": 1703789456,
  "signature": "a1b2c3d4e5f6g7h8ias9j0",
  "uploadUrl": "https://upload.uploadcare.com/base/"
}
```

---

### 2. Get File Information by UUID

**Endpoint:** `GET /uploadcare/file-info`

Get the actual CDN URL and file details using the file UUID.

**Query Parameters:**

- `uuid` (required): File UUID
- `type` (optional): `IMAGE`, `VIDEO`, or `DOCUMENT` (default: IMAGE)

**Example:**

```
GET http://localhost:5119/uploadcare/file-info?uuid=f95cdfd1-25a5-4416-ae5b-c773a7af4958&type=IMAGE
```

**Response:**

```json
{
  "uuid": "f95cdfd1-25a5-4416-ae5b-c773a7af4958",
  "filename": "Terinajarokekaran4.jpg",
  "size": 245678,
  "mimeType": "image/jpeg",
  "url": "https://6880sokg5s.ucarecd.net/f95cdfd1-25a5-4416-ae5b-c773a7af4958/",
  "originalFileUrl": "https://6880sokg5s.ucarecd.net/f95cdfd1-25a5-4416-ae5b-c773a7af4958/Terinajarokekaran4.jpg",
  "isImage": true,
  "isReady": true,
  "datetimeStored": "2023-12-28T10:30:00Z",
  "datetimeUploaded": "2023-12-28T10:29:55Z"
}
```

**Note:** Use the `url` or `originalFileUrl` from the response to view/access the file in the browser.

---

### 3. Delete File by URL or UUID

**Endpoint:** `DELETE /uploadcare/by-url`

Deletes a file using either the full CDN URL or just the UUID.

**Query Parameters:**

- `url` (required): Full CDN URL or UUID
- `type` (optional): `IMAGE`, `VIDEO`, or `DOCUMENT` (default: IMAGE)

**Examples:**

**Delete by URL:**

```
DELETE http://localhost:5119/uploadcare/by-url?url=https://6880sokg5s.ucarecd.net/f95cdfd1-25a5-4416-ae5b-c773a7af4958/&type=IMAGE
```

**Delete by UUID:**

```
DELETE http://localhost:5119/uploadcare/by-url?url=f95cdfd1-25a5-4416-ae5b-c773a7af4958&type=IMAGE
```

**Response:**

```json
{
  "message": "File deleted successfully",
  "urlOrUuid": "https://6880sokg5s.ucarecd.net/f95cdfd1-25a5-4416-ae5b-c773a7af4958/",
  "fileUuid": "f95cdfd1-25a5-4416-ae5b-c7sxs73a7af4958"
}
```

---

## 🧪 Testing with Postman

### Step 1: Get Upload Signature

**Request:**

```
GET http://localhost:5119/uploadcare/signed-upload?type=IMAGE
```

**Response:**

```json
{
  "publicKey": "8460d7f9b79569e8sxs2cec",
  "expire": 1703789456,
  "signature": "abc12xs3def456",
  "uploadUrl": "https://upload.uploadcare.com/base/"
}
```

**Save the response values!**

---

### Step 2: Upload File to Uploadcare

**Request:**

```
POST https://upload.uploadcare.com/base/
Content-Type: multipart/form-data
```

**Form Data:**
| Key | Value |
|-----|-------|
| `UPLOADCARE_PUB_KEY` | `8460d7f9b79569e82cec` (from step 1) |
| `expire` | `1703789456` (from step 1) |
| `signature` | `abc123def456` (from step 1) |
| `file` | Select your file |

**Response:**

```json
{
  "file": "12345678-1234-1234-1234-123456789abc"
}
```

**The `file` value is your File UUID! Save it for the next step.**

---

### Step 3: Get File Information

Use the UUID from Step 2 to get the actual CDN URL:

**Request:**

```
GET http://localhost:5119/uploadcare/file-info?uuid=12345678-1234-1234-1234-123456789abc&type=IMAGE
```

**Response:**

```json
{
  "uuid": "12345678-1234-1234-1234-123456789abc",
  "filename": "my-image.jpg",
  "size": 245678,
  "mimeType": "image/jpeg",
  "url": "https://6880sokg5s.ucarecd.net/12345678-1234-1234-1234-123456789abc/",
  "originalFileUrl": "https://6880sokg5s.ucarecd.net/12345678-1234-1234-1234-123456789abc/my-image.jpg",
  "isImage": true,
  "isReady": true,
  "datetimeStored": "2023-12-28T10:30:00Z",
  "datetimeUploaded": "2023-12-28T10:29:55Z"
}
```

---

### Step 4: View Uploaded File in Browser

Copy the `originalFileUrl` from Step 3 and paste it in your browser:

```
https://6880sokg5s.ucarecd.net/12345678-1234-1234-1234-123456789abc/my-image.jpg
```

**That's it!** Your file is now uploaded and accessible via CDN.

---

### Step 5: Delete File (Optional)

**Request:**

```
DELETE http://localhost:5119/uploadcare/by-url?url=https://6880sokg5s.ucarecd.net/12345678-1234-1234-1234-123456789abc/&type=IMAGE
```

Or delete using just the UUID:

```
DELETE http://localhost:5119/uploadcare/by-url?url=12345678-1234-1234-1234-123456789abc&type=IMAGE
```

**Response:**

```json
{
  "message": "File deleted successfully",
  "urlOrUuid": "https://6880sokg5s.ucarecd.net/12345678-1234-1234-1234-123456789abc/",
  "fileUuid": "12345678-1234-1234-1234-123456789abc"
}
```

---

## 📝 Complete Examples

### Example 1: Upload an Image

**1. Get Signature:**

```
GET http://localhost:5119/uploadcare/signed-upload?type=IMAGE
```

**2. Upload:**

```
POST https://upload.uploadcare.com/base/

Form Data:
- UPLOADCARE_PUB_KEY: 8460d7f9b79569e82cec
- expire: 1703789456
- signature: xyz789abc123
- file: [your-image.jpg]
```

**3. View:**

```
https://ucarecdn.com/a1b2c3d4-e5f6-7890-abcd-ef1234567890/
```

**4. Delete:**

```
DELETE http://localhost:5119/uploadcare/by-url?url=https://ucarecdn.com/a1b2c3d4-e5f6-7890-abcd-ef1234567890/&type=IMAGE
```

---

### Example 2: Upload a Video

**1. Get Signature:**

```
GET http://localhost:5119/uploadcare/signed-upload?type=VIDEO
```

**2. Upload:**

```
POST https://upload.uploadcare.com/base/

Form Data:
- UPLOADCARE_PUB_KEY: d92b2e31426480583f6b
- expire: 1703796656
- signature: def456ghi789
- file: [your-video.mp4]
```

**3. View:**

```
https://ucarecdn.com/v1d2e3o4-5678-90ab-cdef-1234567890ab/
```

---

### Example 3: Upload a PDF Document

**1. Get Signature:**

```
GET http://localhost:5119/uploadcare/signed-upload?type=DOCUMENT
```

**2. Upload:**

```
POST https://upload.uploadcare.com/base/

Form Data:
- UPLOADCARE_PUB_KEY: 70e723d3652e3ec1f7a2
- expire: 1703789456
- signature: jkl012mno345
- file: [document.pdf]
```

**3. View:**

```
https://ucarecdn.com/d0c1u2m3-4567-89ab-cdef-0123456789ab/
```

---

## 🌐 CDN URL Formats

### Direct Access

```
https://ucarecdn.com/{FILE_UUID}/
```

### With Filename

```
https://ucarecdn.com/{FILE_UUID}/filename.jpg
```

### Image Transformations

```
# Resize to 400px width
https://ucarecdn.com/{UUID}/-/resize/400x/

# Preview (crop and resize)
https://ucarecdn.com/{UUID}/-/preview/800x600/

# Smart quality optimization
https://ucarecdn.com/{UUID}/-/quality/smart/

# Convert to WebP
https://ucarecdn.com/{UUID}/-/format/webp/

# Chain operations
https://ucarecdn.com/{UUID}/-/resize/400x/-/quality/smart/-/format/webp/
```

---

## 🔒 Security Notes

1. **Signed Uploads:** All uploads require a valid signature from the backend
2. **Expiration:** Signatures expire after 1 hour by default
3. **Private Keys:** Never expose private keys in frontend code
4. **Separate Projects:** Each file type uses a different project

---

## 📊 Uploadcare Dashboard

View your uploaded files:

- **Images:** https://app.uploadcare.com/projects/8460d7f9b79569e82cec/
- **Videos:** https://app.uploadcare.com/projects/d92b2e31426480583f6b/
- **Documents:** https://app.uploadcare.com/projects/70e723d3652e3ec1f7a2/

---

## 🐛 Troubleshooting

### Upload fails with "Signature is invalid"

- Ensure you're using the correct signature from the backend
- Check that the signature hasn't expired
- Verify you're using the correct public key

### File not found after upload

- Wait a few seconds - processing may take time
- Check the Uploadcare dashboard
- Verify the file UUID is correct

### Cannot delete file

- Ensure the URL format is correct
- Verify the file exists in the correct project
- Check that you're using the correct file type parameter

---

## ✅ Quick Testing Checklist

- [ ] Get signature from backend (`GET /uploadcare/signed-upload?type=IMAGE`)
- [ ] Upload file to Uploadcare with signature
- [ ] Verify file UUID in response
- [ ] Open CDN URL in browser
- [ ] Delete file by URL (optional)

---

**Happy Uploading! 🎉**