File Management & Storage APIs

​

Overview

​

Base URL

https://talentg.vercel.app/api

​

Authentication

Authorization: Bearer <supabase_jwt_token>
Content-Type: multipart/form-data  // for file uploads

​

File Upload

​

Upload Avatar

​

Upload General File

​

Avatar Management

​

Get User Avatar

​

Update Avatar URL

​

Reset Avatar Cache

​

Invalidate Avatar Cache

​

File Storage Management

​

Sync Avatar URLs

​

Clear Google Avatar Cache

​

Ensure Storage Bucket

​

Apply Storage Policies

​

Document Processing

​

Generate PDF (Already documented in Assessments API)

​

Test PDF Generation (Already documented in Assessments API)

​

File Type Support

​

Supported Image Formats

• PNG: Portable Network Graphics
• JPG/JPEG: Joint Photographic Experts Group
• WebP: Web Picture format
• GIF: Graphics Interchange Format (for avatars)

​

File Size Limits

• Avatars: 5MB maximum
• General uploads: 10MB maximum
• PDF documents: 25MB maximum

​

Image Processing

• Automatic resizing for avatars (200x200px)
• Format optimization
• Quality compression
• EXIF data stripping for privacy

​

Storage Organization

​

Bucket Structure

talentg-storage/
├── avatars/
│   ├── user_{id}/
│   │   ├── avatar.{ext}
│   │   └── thumbnails/
│   └── ...
├── assessments/
│   ├── user_{id}/
│   │   ├── assessment_{id}.pdf
│   │   └── ...
│   └── ...
├── documents/
│   ├── user_{id}/
│   └── ...
└── temp/
    └── ...

​

File Naming Convention

• Avatars: avatar.{timestamp}.{ext} or avatar.{ext}
• PDFs: assessment_{id}_{timestamp}.pdf
• General files: {original_name}_{timestamp}.{ext}

​

Error Handling

​

Common Error Codes

​

Error Response Format

{
  "success": false,
  "error": {
    "code": "FILE_TOO_LARGE",
    "message": "File size exceeds limit",
    "details": {
      "max_size": "5MB",
      "provided_size": "8.5MB"
    }
  }
}

​

Rate Limiting

• Avatar uploads: 10 uploads per hour per user
• File uploads: 50 uploads per hour per user
• Metadata requests: 200 requests per hour per user
• Admin operations: 100 requests per hour per user

​

SDK Examples

const uploadAvatar = async (file) => {
  const token = await getSupabaseToken();

  const formData = new FormData();
  formData.append('avatar', file);

  const response = await fetch('/api/upload-avatar', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`
    },
    body: formData
  });

  return response.json();
};

// Usage
const fileInput = document.getElementById('avatar-input');
fileInput.addEventListener('change', async (e) => {
  const file = e.target.files[0];
  if (file) {
    const result = await uploadAvatar(file);
    if (result.success) {
      console.log('Avatar uploaded:', result.data.url);
    }
  }
});

​

Security Considerations

​

File Validation

• Server-side file type validation
• Content analysis for malicious files
• Size limits enforcement
• Path traversal protection

​

Access Control

• User-scoped file access
• Signed URLs for temporary access
• CORS policy enforcement
• Rate limiting by user and IP

​

Privacy Protection

• EXIF data removal from images
• Secure file URLs with expiration
• Access logging for audit trails
• GDPR compliance for user data

​

Storage Security

• Encrypted storage at rest
• Secure bucket policies
• Regular security audits
• Backup and recovery procedures