@jmruthers/pace-core 0.6.10 → 0.6.11

package/src/utils/storage/helpers.ts

@@ -5,7 +5,7 @@
 import { SupabaseClient } from '@supabase/supabase-js';
 import { 
   StorageUploadOptions, 
-  StorageUploadResult, 
+  StorageUploadSuccess,
   StorageFileMetadata,
   StorageUrlOptions,
   StorageListOptions,
@@ -14,6 +14,7 @@ import {
 } from './types';
 import { validateFileSize, getBucketName } from './config';
 import { createLogger } from '../core/logger';
+import { ok, err, type ApiResult } from '../../types/api-result';
 
 const log = createLogger('StorageHelpers');
 
@@ -80,49 +81,53 @@ export function generateUniqueFileName(originalName: string): string {
 }
 
 /**
- * Extract file metadata from a File object
+ * Extract file metadata from a File object.
+ * @returns ApiResult with metadata on success; optional dimensions/hash are best-effort.
  */
 export async function extractFileMetadata(
-  file: File, 
+  file: File,
   options: StorageUploadOptions,
   uploadedBy: string
-): Promise<StorageFileMetadata> {
-  const metadata: StorageFileMetadata = {
-    mimeType: file.type,
-    size: file.size,
-    ...(options.orgId && { orgId: options.orgId }),
-    ...(options.userId && { userId: options.userId }),
-    appName: options.appName || 'pace-core',
-    uploadedBy,
-    uploadedAt: new Date().toISOString(),
-    tags: options.tags || [],
-    isPublic: options.isPublic || false,
-    customMetadata: options.metadata || {}
-  };
+): Promise<ApiResult<StorageFileMetadata>> {
+  try {
+    const metadata: StorageFileMetadata = {
+      mimeType: file.type,
+      size: file.size,
+      ...(options.orgId && { orgId: options.orgId }),
+      ...(options.userId && { userId: options.userId }),
+      appName: options.appName || 'pace-core',
+      uploadedBy,
+      uploadedAt: new Date().toISOString(),
+      tags: options.tags || [],
+      isPublic: options.isPublic || false,
+      customMetadata: options.metadata || {}
+    };
+
+    // Extract image dimensions if it's an image (best-effort)
+    if (file.type.startsWith('image/')) {
+      try {
+        const dimensions = await getImageDimensions(file);
+        metadata.width = dimensions.width;
+        metadata.height = dimensions.height;
+      } catch (_error) {
+        // Non-critical - dimensions are optional
+      }
+    }
 
-  // Extract image dimensions if it's an image
-  if (file.type.startsWith('image/')) {
+    // Generate file hash if possible (best-effort)
     try {
-      const dimensions = await getImageDimensions(file);
-      metadata.width = dimensions.width;
-      metadata.height = dimensions.height;
+      metadata.hash = await generateFileHash(file);
     } catch (_error) {
-      // Non-critical error - image dimensions are optional metadata
-      // Using Logger would be better, but this is in a utility function
-      // For now, silently continue - dimensions are optional
+      // Non-critical - hash is optional
     }
-  }
 
-  // Generate file hash if possible
-  try {
-    metadata.hash = await generateFileHash(file);
-  } catch (_error) {
-    // Non-critical error - file hash is optional metadata
-    // Using Logger would be better, but this is in a utility function
-    // For now, silently continue - hash is optional
+    return ok(metadata);
+  } catch (error) {
+    return err({
+      code: 'EXTRACT_METADATA_FAILED',
+      message: error instanceof Error ? error.message : 'Unknown error'
+    });
   }
-
-  return metadata;
 }
 
 /**
@@ -219,43 +224,32 @@ async function ensureFolderExists(
 }
 
 /**
- * Upload a file to Supabase storage with app segregation
+ * Upload a file to Supabase storage with app segregation.
+ * Returns ApiResult with path, optional publicUrl and metadata on success.
  */
 export async function uploadFile(
   supabase: SupabaseClient,
   file: File,
   options: StorageUploadOptions
-): Promise<StorageUploadResult> {
+): Promise<ApiResult<StorageUploadSuccess>> {
   try {
-    // Validate file size
     const sizeValidation = validateFileSize(file);
     if (!sizeValidation.isValid) {
-      return {
-        success: false,
-        error: sizeValidation.error
-      };
+      return err({ code: 'FILE_SIZE_INVALID', message: sizeValidation.error ?? 'File size validation failed' });
     }
 
-    // Generate unique filename and path
     const uniqueFileName = generateUniqueFileName(file.name);
     const filePath = generateFilePath(options, uniqueFileName);
-
-    // Extract folder path from file path (everything except the filename)
     const folderPath = filePath.substring(0, filePath.lastIndexOf('/'));
-
-    // Extract metadata
-    const metadata = await extractFileMetadata(file, options, 'current-user'); // TODO: Get actual user ID
-
-    // Select bucket based on isPublic flag
+    const metadataResult = await extractFileMetadata(file, options, 'current-user');
+    if (!metadataResult.ok) {
+      return err(metadataResult.error);
+    }
+    const metadata = metadataResult.data;
     const bucketName = getBucketName(options.isPublic || false);
-
-    // Ensure folder exists (Supabase creates folders automatically on upload,
-    // but we verify the path is accessible)
     await ensureFolderExists(supabase, folderPath, bucketName);
 
-    // Upload file to Supabase
-    // Note: Supabase will automatically create the folder structure if it doesn't exist
-    const { data, error } = await supabase.storage
+    const { error } = await supabase.storage
       .from(bucketName)
       .upload(filePath, file, {
         cacheControl: '3600',
@@ -264,33 +258,21 @@ export async function uploadFile(
       });
 
     if (error) {
-      return {
-        success: false,
-        error: `Upload failed: ${error.message}`
-      };
+      return err({ code: 'UPLOAD_FAILED', message: error.message });
     }
 
-    // Generate public URL if file is public
     let publicUrl: string | undefined;
     if (options.isPublic) {
-      const { data: urlData } = supabase.storage
-        .from(bucketName)
-        .getPublicUrl(filePath);
+      const { data: urlData } = supabase.storage.from(bucketName).getPublicUrl(filePath);
       publicUrl = urlData.publicUrl;
     }
 
-    return {
-      success: true,
-      path: filePath,
-      publicUrl,
-      metadata
-    };
-
+    return ok({ path: filePath, publicUrl, metadata });
   } catch (error) {
-    return {
-      success: false,
-      error: `Upload failed: ${error instanceof Error ? error.message : 'Unknown error'}`
-    };
+    return err({
+      code: 'UPLOAD_FAILED',
+      message: error instanceof Error ? error.message : 'Unknown error'
+    });
   }
 }
 
@@ -390,38 +372,36 @@ function resolveBucketHint(pathWithPotentialBucket: string): { bucketNameFromPat
 }
 
 /**
- * Get a signed URL for a protected file
- * Private files are always in the 'files' bucket, so this always uses 'files' bucket
- * @param supabase - Supabase client instance
- * @param path - File path within the bucket
- * @param options - URL options including expiry time
- * @returns Signed URL with expiration timestamp, or null if failed
+ * Get a signed URL for a protected file.
+ * Private files are always in the 'files' bucket.
+ * @returns ApiResult with url and expiresAt on success.
  */
 export async function getSignedUrl(
   supabase: SupabaseClient,
   path: string,
   options: StorageUrlOptions
-): Promise<{ url: string; expiresAt: string } | null> {
+): Promise<ApiResult<{ url: string; expiresAt: string }>> {
   try {
-    // Signed URLs are only for private files, which are always in the 'files' bucket
     const bucketName = getBucketName(false);
-    
     const { data, error } = await supabase.storage
       .from(bucketName)
       .createSignedUrl(path, options.expiresIn || 3600);
 
     if (error) {
       log.error('Failed to create signed URL:', error);
-      return null;
+      return err({ code: 'SIGNED_URL_FAILED', message: error.message });
     }
 
-    return {
+    return ok({
       url: data.signedUrl,
       expiresAt: new Date(Date.now() + (options.expiresIn || 3600) * 1000).toISOString()
-    };
+    });
   } catch (error) {
     log.error('Failed to create signed URL:', error);
-    return null;
+    return err({
+      code: 'SIGNED_URL_FAILED',
+      message: error instanceof Error ? error.message : 'Unknown error'
+    });
   }
 }
 
@@ -456,168 +436,129 @@ function cleanupUrlCache(): void {
 }
 
 /**
- * Generate URLs for multiple file references in parallel
- * This batches URL generation to reduce sequential requests and uses caching
- * @param supabase - Supabase client instance
- * @param fileReferences - Array of file references to generate URLs for
- * @param options - URL options including expiry time and organisation ID
- * @returns Map of file ID to URL string (only includes successful URL generations)
+ * Generate URLs for multiple file references in parallel (best-effort; partial success returns ok with map).
+ * @returns ApiResult with Map of file ID to URL string.
  */
 export async function generateFileUrlsBatch(
   supabase: SupabaseClient,
   fileReferences: Array<{ id: string; file_path: string; is_public: boolean }>,
   options: StorageUrlOptions & { orgId?: string }
-): Promise<Map<string, string>> {
-  const urlMap = new Map<string, string>();
-  
-  if (fileReferences.length === 0) {
-    return urlMap;
-  }
+): Promise<ApiResult<Map<string, string>>> {
+  try {
+    const urlMap = new Map<string, string>();
 
-  const now = Date.now();
-  const ttl = (options.expiresIn || 3600) * 1000; // Convert seconds to milliseconds
-  
-  // Separate files into cached, public, and private
-  const publicFiles: Array<{ id: string; file_path: string }> = [];
-  const privateFiles: Array<{ id: string; file_path: string }> = [];
-  const uncachedFiles: Array<{ id: string; file_path: string; is_public: boolean }> = [];
-
-  for (const fileRef of fileReferences) {
-    const cacheKey = getCacheKey(fileRef.id, fileRef.file_path, fileRef.is_public);
-    const cached = globalUrlCache.get(cacheKey);
-    
-    // Use cached URL if still valid
-    if (cached && cached.expiresAt > now) {
-      urlMap.set(fileRef.id, cached.url);
-      continue;
+    if (fileReferences.length === 0) {
+      return ok(urlMap);
     }
-    
-    // Add to processing queue
-    if (fileRef.is_public) {
-      publicFiles.push({ id: fileRef.id, file_path: fileRef.file_path });
-    } else {
-      privateFiles.push({ id: fileRef.id, file_path: fileRef.file_path });
-    }
-    uncachedFiles.push(fileRef);
-  }
 
-  // Generate public URLs synchronously (they're just string concatenation)
-  for (const file of publicFiles) {
-    try {
-      const url = getPublicUrl(supabase, file.file_path, true);
-      if (url) {
-        urlMap.set(file.id, url);
-        // Cache the URL
-        const cacheKey = getCacheKey(file.id, file.file_path, true);
-        globalUrlCache.set(cacheKey, {
-          url,
-          expiresAt: now + ttl
-        });
+    const now = Date.now();
+    const ttl = (options.expiresIn || 3600) * 1000;
+
+    const publicFiles: Array<{ id: string; file_path: string }> = [];
+    const privateFiles: Array<{ id: string; file_path: string }> = [];
+    const uncachedFiles: Array<{ id: string; file_path: string; is_public: boolean }> = [];
+
+    for (const fileRef of fileReferences) {
+      const cacheKey = getCacheKey(fileRef.id, fileRef.file_path, fileRef.is_public);
+      const cached = globalUrlCache.get(cacheKey);
+      if (cached && cached.expiresAt > now) {
+        urlMap.set(fileRef.id, cached.url);
+        continue;
+      }
+      if (fileRef.is_public) {
+        publicFiles.push({ id: fileRef.id, file_path: fileRef.file_path });
+      } else {
+        privateFiles.push({ id: fileRef.id, file_path: fileRef.file_path });
       }
-    } catch (err) {
-      log.error(`Failed to generate public URL for file ${file.id}:`, err);
+      uncachedFiles.push(fileRef);
     }
-  }
 
-  // Generate signed URLs in parallel using Promise.all
-  if (privateFiles.length > 0) {
-    const signedUrlPromises = privateFiles.map(async (file) => {
+    for (const file of publicFiles) {
       try {
+        const url = getPublicUrl(supabase, file.file_path, true);
+        if (url) {
+          urlMap.set(file.id, url);
+          const cacheKey = getCacheKey(file.id, file.file_path, true);
+          globalUrlCache.set(cacheKey, { url, expiresAt: now + ttl });
+        }
+      } catch (e) {
+        log.error(`Failed to generate public URL for file ${file.id}:`, e);
+      }
+    }
+
+    if (privateFiles.length > 0) {
+      const signedUrlPromises = privateFiles.map(async (file) => {
         const signedUrlResult = await getSignedUrl(supabase, file.file_path, {
           appName: options.appName || 'pace-core',
           orgId: options.orgId,
           expiresIn: options.expiresIn || 3600
         });
-        const url = signedUrlResult?.url || null;
-        
-        // Cache the URL if generated successfully
+        const url = signedUrlResult.ok ? signedUrlResult.data.url : null;
         if (url) {
           const cacheKey = getCacheKey(file.id, file.file_path, false);
-          globalUrlCache.set(cacheKey, {
-            url,
-            expiresAt: now + ttl
-          });
+          globalUrlCache.set(cacheKey, { url, expiresAt: now + ttl });
         }
-        
         return { id: file.id, url };
-      } catch (err) {
-        log.error(`Failed to generate signed URL for file ${file.id}:`, err);
-        return { id: file.id, url: null };
+      });
+      const signedUrlResults = await Promise.all(signedUrlPromises);
+      for (const result of signedUrlResults) {
+        if (result.url) {
+          urlMap.set(result.id, result.url);
+        }
       }
-    });
+    }
 
-    const signedUrlResults = await Promise.all(signedUrlPromises);
-    
-    for (const result of signedUrlResults) {
-      if (result.url) {
-        urlMap.set(result.id, result.url);
-      }
+    if (uncachedFiles.length > 0) {
+      cleanupUrlCache();
     }
-  }
 
-  // Clean up cache after adding new entries
-  if (uncachedFiles.length > 0) {
-    cleanupUrlCache();
+    return ok(urlMap);
+  } catch (error) {
+    return err({
+      code: 'BATCH_URLS_FAILED',
+      message: error instanceof Error ? error.message : 'Unknown error'
+    });
   }
-
-  return urlMap;
 }
 
 /**
- * Delete a file from storage
- * @param supabase - Supabase client instance
- * @param path - File path within the bucket
- * @param isPublic - Whether the file is in the public-files bucket (default: false)
- * @returns Success status and optional error message
+ * Delete a file from storage.
+ * @returns ApiResult<void> on success.
  */
 export async function deleteFile(
   supabase: SupabaseClient,
   path: string,
   isPublic: boolean = false
-): Promise<{ success: boolean; error?: string }> {
+): Promise<ApiResult<void>> {
   try {
     const bucketName = getBucketName(isPublic);
-    
-    const { error } = await supabase.storage
-      .from(bucketName)
-      .remove([path]);
-
+    const { error } = await supabase.storage.from(bucketName).remove([path]);
     if (error) {
-      return {
-        success: false,
-        error: `Delete failed: ${error.message}`
-      };
+      return err({ code: 'DELETE_FAILED', message: error.message });
     }
-
-    return { success: true };
+    return ok(undefined);
   } catch (error) {
-    return {
-      success: false,
-      error: `Delete failed: ${error instanceof Error ? error.message : 'Unknown error'}`
-    };
+    return err({
+      code: 'DELETE_FAILED',
+      message: error instanceof Error ? error.message : 'Unknown error'
+    });
   }
 }
 
 /**
- * List files in an organization scope
- * @param supabase - Supabase client instance
- * @param options - List options including bucket selection via isPublic
- * @returns List of files with metadata
+ * List files in an organization scope.
+ * @returns ApiResult with files, totalCount, hasMore on success.
  */
 export async function listFiles(
   supabase: SupabaseClient,
   options: StorageListOptions & { isPublic?: boolean }
-): Promise<StorageListResult> {
+): Promise<ApiResult<StorageListResult>> {
   try {
-    // Select bucket based on isPublic flag (default to private files bucket)
     const bucketName = getBucketName(options.isPublic || false);
-    
-    // Validate that either orgId or userId is provided
     if (!options.orgId && !options.userId) {
-      throw new Error('Either orgId or userId is required for listing files');
+      return err({ code: 'LIST_FILES_INVALID_OPTIONS', message: 'Either orgId or userId is required for listing files' });
     }
-    
-    // Organization-first or user-first structure
+
     const basePath = options.orgId ? options.orgId : `users/${options.userId}`;
     const pathPrefix = `${basePath}/`;
     const searchPath = options.pathPrefix ? `${pathPrefix}${options.pathPrefix}` : pathPrefix;
@@ -632,7 +573,7 @@ export async function listFiles(
 
     if (error) {
       log.error('Failed to list files:', error);
-      return { files: [], totalCount: 0, hasMore: false };
+      return err({ code: 'LIST_FILES_FAILED', message: error.message });
     }
 
     const files: StorageFileInfo[] = (data || []).map(item => ({
@@ -653,118 +594,99 @@ export async function listFiles(
       }
     }));
 
-    return {
+    return ok({
       files,
       totalCount: files.length,
       hasMore: files.length >= (options.limit || 100)
-    };
+    });
   } catch (error) {
     log.error('Failed to list files:', error);
-    return { files: [], totalCount: 0, hasMore: false };
+    return err({
+      code: 'LIST_FILES_FAILED',
+      message: error instanceof Error ? error.message : 'Unknown error'
+    });
   }
 }
 
 /**
- * Download a file from storage
- * @param supabase - Supabase client instance
- * @param path - File path within the bucket
- * @param isPublic - Whether the file is in the public-files bucket (default: false)
- * @returns File blob with metadata, or null if failed
+ * Download a file from storage.
+ * @returns ApiResult with blob and metadata on success.
  */
 export async function downloadFile(
   supabase: SupabaseClient,
   path: string,
   isPublic: boolean = false
-): Promise<{ blob: Blob; metadata: { name: string; size: number; type: string } } | null> {
+): Promise<ApiResult<{ blob: Blob; metadata: { name: string; size: number; type: string } }>> {
   try {
     const bucketName = getBucketName(isPublic);
-    
-    const { data, error } = await supabase.storage
-      .from(bucketName)
-      .download(path);
+    const { data, error } = await supabase.storage.from(bucketName).download(path);
 
     if (error) {
       log.error('Failed to download file:', error);
-      return null;
+      return err({ code: 'DOWNLOAD_FAILED', message: error.message });
     }
 
     if (!data) {
-      return null;
+      return err({ code: 'DOWNLOAD_FAILED', message: 'No data returned' });
     }
 
-    // Extract file name from path
     const fileName = path.split('/').pop() || 'download';
-    
-    // Get file metadata
     const { data: fileInfo } = await supabase.storage
       .from(bucketName)
-      .list(path.split('/').slice(0, -1).join('/'), {
-        search: fileName
-      });
-
+      .list(path.split('/').slice(0, -1).join('/'), { search: fileName });
     const metadata = fileInfo?.[0]?.metadata || {};
-    
-    return {
+
+    return ok({
       blob: data,
       metadata: {
         name: fileName,
         size: metadata.size || data.size,
         type: metadata.mimetype || 'application/octet-stream'
       }
-    };
+    });
   } catch (error) {
     log.error('Failed to download file:', error);
-    return null;
+    return err({
+      code: 'DOWNLOAD_FAILED',
+      message: error instanceof Error ? error.message : 'Unknown error'
+    });
   }
 }
 
 /**
- * Move a file to archived location (soft delete)
- * @param supabase - Supabase client instance
- * @param path - File path within the bucket
- * @param options - Archive options including bucket selection via isPublic
+ * Move a file to archived location (soft delete).
+ * @returns ApiResult<void> on success.
  */
 export async function archiveFile(
   supabase: SupabaseClient,
   path: string,
   options: { appName: string; orgId?: string; userId?: string; isPublic?: boolean }
-): Promise<{ success: boolean; error?: string }> {
+): Promise<ApiResult<void>> {
   try {
     const bucketName = getBucketName(options.isPublic || false);
-    
-    // Generate archived path for organization-first or user-first structure
     let archivedPath: string;
     if (options.orgId) {
       archivedPath = path.replace(`${options.orgId}/`, `archived/${options.orgId}/`);
     } else if (options.userId) {
       archivedPath = path.replace(`users/${options.userId}/`, `archived/users/${options.userId}/`);
     } else {
-      throw new Error('Either orgId or userId is required for archiving files');
+      return err({ code: 'ARCHIVE_FAILED', message: 'Either orgId or userId is required for archiving files' });
     }
-    
-    // Copy file to archived location
-    const { error: copyError } = await supabase.storage
-      .from(bucketName)
-      .copy(path, archivedPath);
 
+    const { error: copyError } = await supabase.storage.from(bucketName).copy(path, archivedPath);
     if (copyError) {
-      return {
-        success: false,
-        error: `Archive failed: ${copyError.message}`
-      };
+      return err({ code: 'ARCHIVE_FAILED', message: copyError.message });
     }
 
-    // Delete original file
     const deleteResult = await deleteFile(supabase, path, options.isPublic || false);
-    if (!deleteResult.success) {
-      return deleteResult;
+    if (!deleteResult.ok) {
+      return err(deleteResult.error);
     }
-
-    return { success: true };
+    return ok(undefined);
   } catch (error) {
-    return {
-      success: false,
-      error: `Archive failed: ${error instanceof Error ? error.message : 'Unknown error'}`
-    };
+    return err({
+      code: 'ARCHIVE_FAILED',
+      message: error instanceof Error ? error.message : 'Unknown error'
+    });
   }
 }

package/src/utils/storage/{__tests__/index.unit.test.ts → index.unit.test.ts}

@@ -1,12 +1,12 @@
 /**
  * @file Unit Tests for Storage Index
  * @package @jmruthers/pace-core
- * @module Utils/Storage/__tests__
+ * @module Utils/Storage
  * @since 1.0.0
  */
 
 import { describe, it, expect } from 'vitest';
-import { StorageUtils } from '../storageUtils';
+import { StorageUtils } from './storageUtils';
 import {
   uploadFile,
   getPublicUrl,
@@ -18,7 +18,7 @@ import {
   generateFilePath,
   generateUniqueFileName,
   extractFileMetadata
-} from '../helpers';
+} from './helpers';
 
 // Following testing standards: use timeout parameter to prevent hanging
 const TEST_TIMEOUT = 10000; // 10 seconds per test