File Upload

File Upload Features

AstraCollab provides powerful file upload capabilities with support for both small and large files, progress tracking, and real-time status updates.

Upload Methods

Single File Upload

For files smaller than 100MB, use the simple single file upload:

import { FileUploaderWithUI } from '@astracollab/nextjs';

function SingleFileUpload() {
  const config = {
    baseURL: 'https://api.astracollab.app',
    apiKey: process.env.ASTRACOLLAB_API_KEY
  };

  return (
    <FileUploaderWithUI
      config={config}
      maxFiles={1}
      onUploadComplete={(results) => {
        console.log('File uploaded:', results[0]);
      }}
    />
  );
}

Multipart Upload

For large files (100MB+), AstraCollab automatically uses multipart uploads:

Chunking: Files are split into 15MB chunks
Parallel Upload: Chunks are uploaded in parallel for better performance
Progress Tracking: Real-time progress for each chunk
Resume Capability: Failed uploads can be resumed

import { useUploadService } from '@astracollab/nextjs';

function LargeFileUpload() {
  const config = {
    baseURL: 'https://api.astracollab.app',
    apiKey: process.env.ASTRACOLLAB_API_KEY
  };

  const uploadService = useUploadService(config);

  const handleLargeFile = async (file) => {
    // The SDK automatically handles multipart uploads for large files
    const fileId = await uploadService.uploadSingleFile({
      file,
      fileName: file.name
    });
    
    console.log('Large file uploaded:', fileId);
  };

  return (
    <input 
      type="file" 
      onChange={(e) => handleLargeFile(e.target.files[0])} 
    />
  );
}

Progress Tracking

Real-time Progress Updates

Track upload progress in real-time:

import { useUpload } from '@astracollab/nextjs';

function UploadWithProgress() {
  const { uploadProgress, isUploading } = useUpload(uploadService);

  return (
    <div>
      {isUploading && <p>Uploading files...</p>}
      
      {Array.from(uploadProgress.entries()).map(([fileId, progress]) => (
        <div key={fileId}>
          <p>{progress.fileName}</p>
          <div className="progress-bar">
            <div 
              className="progress-fill" 
              style={{ width: `${progress.progressPercentage}%` }}
            />
          </div>
          <p>{progress.progressPercentage}%</p>
          <p>Status: {progress.status}</p>
        </div>
      ))}
    </div>
  );
}

Progress States

Files go through these states during upload:

pending: File is queued for upload
uploading: File is currently being uploaded
completed: Upload finished successfully
failed: Upload failed with an error
canceled: Upload was canceled by user

File Validation

Size Limits

Free Plan: 100MB per file
Creator Plan: 1GB per file
Studio Plan: 5GB per file
Production Plan: 10GB per file

File Type Restrictions

Configure allowed file types:

<FileUploaderWithUI
  config={config}
  accept=".jpg,.jpeg,.png,.pdf,.doc,.docx"
  onUploadError={(error, fileId) => {
    if (error.includes('file type')) {
      console.error('Invalid file type');
    }
  }}
/>

Custom Validation

Add custom validation logic:

function CustomValidation() {
  const validateFile = (file) => {
    // Check file size
    if (file.size > 50 * 1024 * 1024) { // 50MB
      return 'File size exceeds 50MB limit';
    }
    
    // Check file type
    const allowedTypes = ['image/jpeg', 'image/png', 'application/pdf'];
    if (!allowedTypes.includes(file.type)) {
      return 'File type not allowed';
    }
    
    return null; // File is valid
  };

  return (
    <FileUploaderWithUI
      config={config}
      onUploadError={(error, fileId) => {
        const validationError = validateFile(file);
        if (validationError) {
          console.error(validationError);
        }
      }}
    />
  );
}

Upload Options

Folder Organization

Upload files to specific folders:

<FileUploaderWithUI
  config={config}
  folderId="my-folder-id"
  orgId="my-org-id"
/>

Multiple Files

Upload multiple files simultaneously:

<FileUploaderWithUI
  config={config}
  maxFiles={10}
  onUploadComplete={(results) => {
    console.log(`Uploaded ${results.length} files`);
  }}
/>

Custom File Names

Override file names during upload:

import { useUploadService } from '@astracollab/nextjs';

function CustomFileName() {
  const uploadService = useUploadService(config);

  const uploadWithCustomName = async (file) => {
    const timestamp = new Date().toISOString();
    const customName = `${timestamp}-${file.name}`;
    
    const fileId = await uploadService.uploadSingleFile({
      file,
      fileName: customName
    });
  };

  return (
    <input 
      type="file" 
      onChange={(e) => uploadWithCustomName(e.target.files[0])} 
    />
  );
}

Error Handling

Upload Failures

Handle various upload error scenarios:

function UploadWithErrorHandling() {
  const handleUploadError = (error, fileId) => {
    if (error.includes('network')) {
      console.error('Network error - check your connection');
    } else if (error.includes('storage limit')) {
      console.error('Storage limit exceeded');
    } else if (error.includes('rate limit')) {
      console.error('Rate limit exceeded');
    } else {
      console.error('Upload failed:', error);
    }
  };

  return (
    <FileUploaderWithUI
      config={config}
      onUploadError={handleUploadError}
    />
  );
}

Retry Logic

Implement automatic retry for failed uploads:

import { useUploadService } from '@astracollab/nextjs';

function UploadWithRetry() {
  const uploadService = useUploadService(config);

  const uploadWithRetry = async (file, maxRetries = 3) => {
    for (let attempt = 1; attempt <= maxRetries; attempt++) {
      try {
        const fileId = await uploadService.uploadSingleFile({ file });
        console.log('Upload successful:', fileId);
        return fileId;
      } catch (error) {
        console.error(`Upload attempt ${attempt} failed:`, error);
        
        if (attempt === maxRetries) {
          throw new Error('Upload failed after all retry attempts');
        }
        
        // Wait before retrying
        await new Promise(resolve => setTimeout(resolve, 1000 * attempt));
      }
    }
  };

  return (
    <input 
      type="file" 
      onChange={(e) => uploadWithRetry(e.target.files[0])} 
    />
  );
}

Performance Optimization

Chunk Size Configuration

Adjust chunk size for multipart uploads:

import { UploadService } from '@astracollab/nextjs';

const uploadService = new UploadService('https://api.astracollab.app', 'api-key', {
  chunkSize: 10 * 1024 * 1024 // 10MB chunks
});

Concurrent Uploads

Control the number of concurrent uploads:

const uploadService = new UploadService('https://api.astracollab.app', 'api-key', {
  maxConcurrentUploads: 3
});

Upload Queue

Manage upload queue for better performance:

function UploadQueue() {
  const [queue, setQueue] = useState([]);
  const [isProcessing, setIsProcessing] = useState(false);

  const addToQueue = (files) => {
    setQueue(prev => [...prev, ...files]);
  };

  const processQueue = async () => {
    if (isProcessing || queue.length === 0) return;
    
    setIsProcessing(true);
    
    for (const file of queue) {
      try {
        await uploadService.uploadSingleFile({ file });
        setQueue(prev => prev.filter(f => f !== file));
      } catch (error) {
        console.error('Failed to upload:', file.name, error);
      }
    }
    
    setIsProcessing(false);
  };

  useEffect(() => {
    processQueue();
  }, [queue, isProcessing]);

  return (
    <div>
      <input 
        type="file" 
        multiple 
        onChange={(e) => addToQueue(Array.from(e.target.files))} 
      />
      <p>Queue: {queue.length} files</p>
      <p>Processing: {isProcessing ? 'Yes' : 'No'}</p>
    </div>
  );
}

Security Features

File Scanning

AstraCollab automatically scans uploaded files for malware and viruses.

Access Control

Control who can upload files:

function SecureUpload() {
  const [userPermissions, setUserPermissions] = useState(null);

  useEffect(() => {
    // Check user permissions before allowing upload
    checkUserPermissions().then(setUserPermissions);
  }, []);

  if (!userPermissions?.canUpload) {
    return <p>You don't have permission to upload files</p>;
  }

  return (
    <FileUploaderWithUI
      config={config}
      maxFiles={userPermissions.maxFiles}
      maxFileSize={userPermissions.maxFileSize}
    />
  );
}

Best Practices

File Size Limits: Always validate file sizes before upload
File Type Validation: Restrict allowed file types for security
Progress Feedback: Show upload progress to improve user experience
Error Handling: Implement comprehensive error handling
Retry Logic: Add retry mechanisms for network failures
Queue Management: Use upload queues for multiple files
Security: Validate files on both client and server side

Support

Need help with file uploads?

API Reference: Check the upload endpoints
SDK Documentation: Use our Next.js SDK or JavaScript SDK
Examples: See upload examples
Support: Email us at [email protected]

Getting started

SDK & Packages

Features

Integration

File Upload Features

Upload Methods

Single File Upload

Multipart Upload

Progress Tracking

Real-time Progress Updates

Progress States

File Validation

Size Limits

File Type Restrictions

Custom Validation

Upload Options

Folder Organization

Multiple Files

Custom File Names

Error Handling

Upload Failures

Retry Logic

Performance Optimization

Chunk Size Configuration

Concurrent Uploads

Upload Queue

Security Features

File Scanning

Access Control

Best Practices

Support

Getting started

SDK & Packages

Features

Integration

​File Upload Features

​Upload Methods

​Single File Upload

​Multipart Upload

​Progress Tracking

​Real-time Progress Updates

​Progress States

​File Validation

​Size Limits

​File Type Restrictions

​Custom Validation

​Upload Options

​Folder Organization

​Multiple Files

​Custom File Names

​Error Handling

​Upload Failures

​Retry Logic

​Performance Optimization

​Chunk Size Configuration

​Concurrent Uploads

​Upload Queue

​Security Features

​File Scanning

​Access Control

​Best Practices

​Support

File Upload Features

Upload Methods

Single File Upload

Multipart Upload

Progress Tracking

Real-time Progress Updates

Progress States

File Validation

Size Limits

File Type Restrictions

Custom Validation

Upload Options

Folder Organization

Multiple Files

Custom File Names

Error Handling

Upload Failures

Retry Logic

Performance Optimization

Chunk Size Configuration

Concurrent Uploads

Upload Queue

Security Features

File Scanning

Access Control

Best Practices

Support