@oxyhq/services 5.10.5 → 5.10.6

package/src/utils/s3FileManager.ts

@@ -0,0 +1,281 @@
+import { S3Client, PutObjectCommand, GetObjectCommand, DeleteObjectCommand, ListObjectsV2Command } from '@aws-sdk/client-s3';
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
+
+export interface S3Config {
+  region: string;
+  accessKeyId: string;
+  secretAccessKey: string;
+  bucketName: string;
+}
+
+export interface UploadOptions {
+  contentType?: string;
+  metadata?: Record<string, string>;
+  publicRead?: boolean;
+}
+
+export interface FileInfo {
+  key: string;
+  size: number;
+  lastModified: Date;
+  contentType?: string;
+  metadata?: Record<string, string>;
+}
+
+export class S3FileManager {
+  private s3Client: S3Client;
+  private bucketName: string;
+
+  constructor(config: S3Config) {
+    this.s3Client = new S3Client({
+      region: config.region,
+      credentials: {
+        accessKeyId: config.accessKeyId,
+        secretAccessKey: config.secretAccessKey,
+      },
+    });
+    this.bucketName = config.bucketName;
+  }
+
+  /**
+   * Upload a file to S3
+   */
+  async uploadFile(
+    key: string,
+    file: File | Buffer | string,
+    options: UploadOptions = {}
+  ): Promise<string> {
+    let body: Buffer | string;
+    let contentType = options.contentType;
+
+    if (file instanceof File) {
+      body = await this.fileToBuffer(file);
+      contentType = contentType || file.type;
+    } else if (typeof file === 'string') {
+      body = file;
+      contentType = contentType || 'text/plain';
+    } else {
+      body = file;
+      contentType = contentType || 'application/octet-stream';
+    }
+
+    const command = new PutObjectCommand({
+      Bucket: this.bucketName,
+      Key: key,
+      Body: body,
+      ContentType: contentType,
+      Metadata: options.metadata,
+      ACL: options.publicRead ? 'public-read' : 'private',
+    });
+
+    await this.s3Client.send(command);
+    return `https://${this.bucketName}.s3.amazonaws.com/${key}`;
+  }
+
+  /**
+   * Download a file from S3
+   */
+  async downloadFile(key: string): Promise<Buffer> {
+    const command = new GetObjectCommand({
+      Bucket: this.bucketName,
+      Key: key,
+    });
+
+    const response = await this.s3Client.send(command);
+    
+    if (!response.Body) {
+      throw new Error('File not found or empty');
+    }
+
+    // Convert stream to buffer
+    const chunks: Uint8Array[] = [];
+    const reader = response.Body.transformToWebStream().getReader();
+    
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      chunks.push(value);
+    }
+
+    return Buffer.concat(chunks);
+  }
+
+  /**
+   * Delete a file from S3
+   */
+  async deleteFile(key: string): Promise<void> {
+    const command = new DeleteObjectCommand({
+      Bucket: this.bucketName,
+      Key: key,
+    });
+
+    await this.s3Client.send(command);
+  }
+
+  /**
+   * Generate a presigned URL for file upload
+   */
+  async getPresignedUploadUrl(
+    key: string,
+    contentType: string,
+    expiresIn: number = 3600
+  ): Promise<string> {
+    const command = new PutObjectCommand({
+      Bucket: this.bucketName,
+      Key: key,
+      ContentType: contentType,
+    });
+
+    return getSignedUrl(this.s3Client, command, { expiresIn });
+  }
+
+  /**
+   * Generate a presigned URL for file download
+   */
+  async getPresignedDownloadUrl(
+    key: string,
+    expiresIn: number = 3600
+  ): Promise<string> {
+    const command = new GetObjectCommand({
+      Bucket: this.bucketName,
+      Key: key,
+    });
+
+    return getSignedUrl(this.s3Client, command, { expiresIn });
+  }
+
+  /**
+   * List files in a directory
+   */
+  async listFiles(prefix: string = '', maxKeys: number = 1000): Promise<FileInfo[]> {
+    const command = new ListObjectsV2Command({
+      Bucket: this.bucketName,
+      Prefix: prefix,
+      MaxKeys: maxKeys,
+    });
+
+    const response = await this.s3Client.send(command);
+    
+    if (!response.Contents) {
+      return [];
+    }
+
+    return response.Contents.map((item) => ({
+      key: item.Key!,
+      size: item.Size || 0,
+      lastModified: item.LastModified!,
+    }));
+  }
+
+  /**
+   * Check if a file exists
+   */
+  async fileExists(key: string): Promise<boolean> {
+    try {
+      const command = new GetObjectCommand({
+        Bucket: this.bucketName,
+        Key: key,
+      });
+
+      await this.s3Client.send(command);
+      return true;
+    } catch (error: any) {
+      if (error.name === 'NoSuchKey') {
+        return false;
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Get file metadata
+   */
+  async getFileMetadata(key: string): Promise<FileInfo | null> {
+    try {
+      const command = new GetObjectCommand({
+        Bucket: this.bucketName,
+        Key: key,
+      });
+
+      const response = await this.s3Client.send(command);
+      
+      return {
+        key,
+        size: parseInt(response.ContentLength?.toString() || '0'),
+        lastModified: response.LastModified!,
+        contentType: response.ContentType,
+        metadata: response.Metadata,
+      };
+    } catch (error: any) {
+      if (error.name === 'NoSuchKey') {
+        return null;
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Convert File object to Buffer (for React Native compatibility)
+   */
+  private async fileToBuffer(file: File): Promise<Buffer> {
+    return new Promise((resolve, reject) => {
+      const reader = new FileReader();
+      reader.onload = () => {
+        if (reader.result instanceof ArrayBuffer) {
+          resolve(Buffer.from(reader.result));
+        } else {
+          reject(new Error('Failed to read file'));
+        }
+      };
+      reader.onerror = () => reject(reader.error);
+      reader.readAsArrayBuffer(file);
+    });
+  }
+
+  /**
+   * Upload multiple files
+   */
+  async uploadMultipleFiles(
+    files: Array<{ key: string; file: File | Buffer | string; options?: UploadOptions }>
+  ): Promise<string[]> {
+    const uploadPromises = files.map(({ key, file, options }) =>
+      this.uploadFile(key, file, options)
+    );
+
+    return Promise.all(uploadPromises);
+  }
+
+  /**
+   * Delete multiple files
+   */
+  async deleteMultipleFiles(keys: string[]): Promise<void> {
+    const deletePromises = keys.map(key => this.deleteFile(key));
+    await Promise.all(deletePromises);
+  }
+
+  /**
+   * Copy file from one key to another
+   */
+  async copyFile(sourceKey: string, destinationKey: string): Promise<void> {
+    const command = new PutObjectCommand({
+      Bucket: this.bucketName,
+      Key: destinationKey,
+      Body: await this.downloadFile(sourceKey),
+    });
+
+    await this.s3Client.send(command);
+  }
+
+  /**
+   * Move file (copy + delete)
+   */
+  async moveFile(sourceKey: string, destinationKey: string): Promise<void> {
+    await this.copyFile(sourceKey, destinationKey);
+    await this.deleteFile(sourceKey);
+  }
+}
+
+// Export a factory function for easier configuration
+export function createS3FileManager(config: S3Config): S3FileManager {
+  return new S3FileManager(config);
+} 

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,
+  };
+};