@oxyhq/services 5.10.4 → 5.10.6

package/src/utils/s3FileManagerExample.ts

@@ -0,0 +1,432 @@
+/**
+ * S3 File Management Examples
+ * 
+ * This file demonstrates how to use the S3 file management functionality
+ * in both web and React Native environments.
+ */
+
+import { 
+  S3FileManager, 
+  createS3FileManager,
+  S3Config,
+  UploadOptions
+} from './s3FileManager';
+import {
+  S3FileManagerRN,
+  createS3FileManagerRN,
+  RNFile
+} from './s3FileManagerRN';
+
+// Example configuration
+const s3Config: S3Config = {
+  region: 'us-east-1',
+  accessKeyId: 'your-access-key-id',
+  secretAccessKey: 'your-secret-access-key',
+  bucketName: 'your-bucket-name',
+};
+
+// ============================================================================
+// WEB ENVIRONMENT EXAMPLES
+// ============================================================================
+
+export class WebFileManagerExample {
+  private s3Manager: S3FileManager;
+
+  constructor() {
+    this.s3Manager = createS3FileManager(s3Config);
+  }
+
+  /**
+   * Example: Upload a file from web form
+   */
+  async uploadFileFromForm(fileInput: HTMLInputElement): Promise<string> {
+    const file = fileInput.files?.[0];
+    if (!file) {
+      throw new Error('No file selected');
+    }
+
+    const key = `uploads/${Date.now()}-${file.name}`;
+    const uploadOptions: UploadOptions = {
+      contentType: file.type,
+      metadata: {
+        originalName: file.name,
+        uploadedBy: 'web-user',
+        uploadedAt: new Date().toISOString(),
+      },
+      publicRead: false,
+    };
+
+    try {
+      const url = await this.s3Manager.uploadFile(key, file, uploadOptions);
+      console.log('File uploaded successfully:', url);
+      return url;
+    } catch (error) {
+      console.error('Upload failed:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Example: Upload multiple files
+   */
+  async uploadMultipleFiles(fileList: FileList): Promise<string[]> {
+    const files = Array.from(fileList).map(file => ({
+      key: `uploads/${Date.now()}-${file.name}`,
+      file,
+      options: {
+        contentType: file.type,
+        metadata: {
+          originalName: file.name,
+          uploadedBy: 'web-user',
+          uploadedAt: new Date().toISOString(),
+        },
+        publicRead: false,
+      } as UploadOptions,
+    }));
+
+    try {
+      const urls = await this.s3Manager.uploadMultipleFiles(files);
+      console.log('Files uploaded successfully:', urls);
+      return urls;
+    } catch (error) {
+      console.error('Upload failed:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Example: Download a file
+   */
+  async downloadFile(key: string): Promise<void> {
+    try {
+      const buffer = await this.s3Manager.downloadFile(key);
+      
+      // Create a blob and download link
+      const blob = new Blob([buffer]);
+      const url = URL.createObjectURL(blob);
+      const a = document.createElement('a');
+      a.href = url;
+      a.download = key.split('/').pop() || 'download';
+      document.body.appendChild(a);
+      a.click();
+      document.body.removeChild(a);
+      URL.revokeObjectURL(url);
+      
+      console.log('File downloaded successfully');
+    } catch (error) {
+      console.error('Download failed:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Example: Get presigned URLs
+   */
+  async getPresignedUrls(key: string): Promise<{ upload: string; download: string }> {
+    try {
+      const uploadUrl = await this.s3Manager.getPresignedUploadUrl(key, 'application/octet-stream');
+      const downloadUrl = await this.s3Manager.getPresignedDownloadUrl(key);
+      
+      return { upload: uploadUrl, download: downloadUrl };
+    } catch (error) {
+      console.error('Failed to get presigned URLs:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Example: List files with pagination
+   */
+  async listFiles(prefix: string = '', maxKeys: number = 50): Promise<void> {
+    try {
+      const files = await this.s3Manager.listFiles(prefix, maxKeys);
+      console.log('Files found:', files);
+      
+      files.forEach(file => {
+        console.log(`- ${file.key} (${file.size} bytes, modified: ${file.lastModified})`);
+      });
+    } catch (error) {
+      console.error('Failed to list files:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Example: File operations (copy, move, delete)
+   */
+  async performFileOperations(): Promise<void> {
+    const sourceKey = 'uploads/source-file.txt';
+    const destKey = 'uploads/destination-file.txt';
+    
+    try {
+      // Copy file
+      await this.s3Manager.copyFile(sourceKey, destKey);
+      console.log('File copied successfully');
+      
+      // Move file
+      await this.s3Manager.moveFile(destKey, 'uploads/moved-file.txt');
+      console.log('File moved successfully');
+      
+      // Delete file
+      await this.s3Manager.deleteFile('uploads/moved-file.txt');
+      console.log('File deleted successfully');
+    } catch (error) {
+      console.error('File operation failed:', error);
+      throw error;
+    }
+  }
+}
+
+// ============================================================================
+// REACT NATIVE ENVIRONMENT EXAMPLES
+// ============================================================================
+
+export class ReactNativeFileManagerExample {
+  private s3Manager: S3FileManagerRN;
+
+  constructor() {
+    this.s3Manager = createS3FileManagerRN(s3Config);
+  }
+
+  /**
+   * Example: Upload a file from React Native
+   */
+  async uploadFileFromRN(fileInfo: RNFile): Promise<string> {
+    const key = `uploads/${Date.now()}-${fileInfo.name}`;
+    const uploadOptions: UploadOptions = {
+      contentType: fileInfo.type || 'application/octet-stream',
+      metadata: {
+        originalName: fileInfo.name,
+        uploadedBy: 'rn-user',
+        uploadedAt: new Date().toISOString(),
+        fileSize: fileInfo.size?.toString() || '0',
+      },
+      publicRead: false,
+    };
+
+    try {
+      const url = await this.s3Manager.uploadFile(key, fileInfo, uploadOptions);
+      console.log('File uploaded successfully:', url);
+      return url;
+    } catch (error) {
+      console.error('Upload failed:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Example: Upload image with size validation
+   */
+  async uploadImageWithValidation(fileInfo: RNFile, maxSize: number = 5 * 1024 * 1024): Promise<string> {
+    // Get file size
+    const fileSize = await this.s3Manager.getFileSize(fileInfo);
+    
+    if (fileSize > maxSize) {
+      throw new Error(`File size (${fileSize} bytes) exceeds maximum allowed size (${maxSize} bytes)`);
+    }
+
+    const key = `images/${Date.now()}-${fileInfo.name}`;
+    const uploadOptions: UploadOptions = {
+      contentType: fileInfo.type || 'image/jpeg',
+      metadata: {
+        originalName: fileInfo.name,
+        uploadedBy: 'rn-user',
+        uploadedAt: new Date().toISOString(),
+        fileSize: fileSize.toString(),
+        category: 'image',
+      },
+      publicRead: true, // Images are often public
+    };
+
+    try {
+      const url = await this.s3Manager.uploadImage(key, fileInfo, uploadOptions);
+      console.log('Image uploaded successfully:', url);
+      return url;
+    } catch (error) {
+      console.error('Image upload failed:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Example: Download file to React Native
+   */
+  async downloadFileToRN(key: string): Promise<Buffer> {
+    try {
+      const buffer = await this.s3Manager.downloadFile(key);
+      console.log('File downloaded successfully, size:', buffer.length);
+      return buffer;
+    } catch (error) {
+      console.error('Download failed:', error);
+      throw error;
+    }
+  }
+
+  /**
+   * Example: Batch operations
+   */
+  async performBatchOperations(files: RNFile[]): Promise<void> {
+    try {
+      // Upload multiple files
+      const uploadPromises = files.map((file, index) => {
+        const key = `batch-uploads/${Date.now()}-${index}-${file.name}`;
+        return this.s3Manager.uploadFile(key, file, {
+          metadata: { batchId: Date.now().toString() },
+        });
+      });
+
+      const uploadedUrls = await Promise.all(uploadPromises);
+      console.log('Batch upload completed:', uploadedUrls);
+
+      // Delete multiple files (example with keys)
+      const keysToDelete = uploadedUrls.map((url: string) => {
+        const key = url.split('/').pop();
+        return `batch-uploads/${key}`;
+      });
+
+      await this.s3Manager.deleteMultipleFiles(keysToDelete);
+      console.log('Batch delete completed');
+    } catch (error) {
+      console.error('Batch operations failed:', error);
+      throw error;
+    }
+  }
+}
+
+// ============================================================================
+// USAGE EXAMPLES
+// ============================================================================
+
+/**
+ * Example usage in a React component
+ */
+export const useS3FileManager = () => {
+  const webManager = new WebFileManagerExample();
+  const rnManager = new ReactNativeFileManagerExample();
+
+  const handleFileUpload = async (file: File | RNFile) => {
+    try {
+      if ('uri' in file) {
+        // React Native file
+        return await rnManager.uploadFileFromRN(file);
+      } else {
+        // Web file
+        const mockInput = { files: [file] } as unknown as HTMLInputElement;
+        return await webManager.uploadFileFromForm(mockInput);
+      }
+    } catch (error) {
+      console.error('Upload failed:', error);
+      throw error;
+    }
+  };
+
+  const handleFileDownload = async (key: string) => {
+    try {
+      if (typeof window !== 'undefined') {
+        // Web environment
+        await webManager.downloadFile(key);
+      } else {
+        // React Native environment
+        const buffer = await rnManager.downloadFileToRN(key);
+        // Handle buffer in React Native (save to file system, etc.)
+        return buffer;
+      }
+    } catch (error) {
+      console.error('Download failed:', error);
+      throw error;
+    }
+  };
+
+  return {
+    uploadFile: handleFileUpload,
+    downloadFile: handleFileDownload,
+    listFiles: webManager.listFiles.bind(webManager),
+    getPresignedUrls: webManager.getPresignedUrls.bind(webManager),
+  };
+};
+
+/**
+ * Example: Error handling and retry logic
+ */
+export const uploadWithRetry = async (
+  s3Manager: S3FileManager | S3FileManagerRN,
+  key: string,
+  file: File | RNFile | Buffer,
+  options: UploadOptions = {},
+  maxRetries: number = 3
+): Promise<string> => {
+  // Type guard to determine which manager we're using
+  const isRNManager = (manager: S3FileManager | S3FileManagerRN): manager is S3FileManagerRN => {
+    return 'getFileSize' in manager;
+  };
+  let lastError: Error | undefined;
+
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      if (isRNManager(s3Manager)) {
+        // For React Native manager, ensure file is RNFile
+        if ('uri' in file) {
+          return await s3Manager.uploadFile(key, file, options);
+        } else {
+          throw new Error('React Native manager requires RNFile with uri property');
+        }
+      } else {
+        // For web manager, ensure file is not RNFile
+        if ('uri' in file) {
+          throw new Error('Web manager does not support RNFile');
+        } else {
+          return await s3Manager.uploadFile(key, file, options);
+        }
+      }
+    } catch (error) {
+      lastError = error as Error;
+      console.warn(`Upload attempt ${attempt} failed:`, error);
+      
+      if (attempt < maxRetries) {
+        // Wait before retrying (exponential backoff)
+        const delay = Math.pow(2, attempt) * 1000;
+        await new Promise(resolve => setTimeout(resolve, delay));
+      }
+    }
+  }
+
+  throw new Error(`Upload failed after ${maxRetries} attempts. Last error: ${lastError?.message || 'Unknown error'}`);
+};
+
+/**
+ * Example: File validation utilities
+ */
+export const validateFile = (
+  file: File | RNFile,
+  options: {
+    maxSize?: number;
+    allowedTypes?: string[];
+    allowedExtensions?: string[];
+  } = {}
+): { isValid: boolean; errors: string[] } => {
+  const errors: string[] = [];
+  const { maxSize = 10 * 1024 * 1024, allowedTypes = [], allowedExtensions = [] } = options;
+
+  // Check file size
+  if ('size' in file && file.size && file.size > maxSize) {
+    errors.push(`File size (${file.size} bytes) exceeds maximum allowed size (${maxSize} bytes)`);
+  }
+
+  // Check file type
+  if ('type' in file && file.type && allowedTypes.length > 0 && !allowedTypes.includes(file.type)) {
+    errors.push(`File type (${file.type}) is not allowed`);
+  }
+
+  // Check file extension
+  if (allowedExtensions.length > 0) {
+    const extension = file.name.split('.').pop()?.toLowerCase();
+    if (!extension || !allowedExtensions.includes(`.${extension}`)) {
+      errors.push(`File extension (.${extension}) is not allowed`);
+    }
+  }
+
+  return {
+    isValid: errors.length === 0,
+    errors,
+  };
+};