@jmruthers/pace-core 0.6.9 → 0.6.11

package/src/utils/storage/helpers.test.ts

@@ -1,20 +1,30 @@
 /**
- * @file Storage Helpers Tests
- * @description Comprehensive tests for storage utility functions following TEST_STANDARD.md
+ * @file Unit Tests for Storage Helpers
+ * @package @jmruthers/pace-core
+ * @module Utils/Storage
+ * @since 1.0.0
  */
 
-import { vi } from 'vitest';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { 
   uploadFile, 
   deleteFile, 
   downloadFile, 
   getPublicUrl, 
   getSignedUrl, 
-  generateFilePath 
+  generateFilePath,
+  generateUniqueFileName,
+  extractFileMetadata,
+  listFiles,
+  archiveFile,
+  generateFileUrlsBatch
 } from './helpers';
 import { getBucketName } from './config';
-import { FileCategory } from '../../types/file-reference';
-import { createMockSupabaseClient } from '../../__tests__/helpers/test-utils';
+import type { SupabaseClient } from '@supabase/supabase-js';
+import type { Database } from '../../types/database';
+
+// Following testing standards: use timeout parameter to prevent hanging
+const TEST_TIMEOUT = 10000; // 10 seconds per test
 
 // Setup mocks
 beforeEach(() => {
@@ -26,12 +36,30 @@ afterEach(() => {
 });
 
 // Test data
-const mockSupabase = createMockSupabaseClient();
 const createTestFile = (name = 'test.pdf', type = 'application/pdf', size = 1024) => {
   return new File(['test content'], name, { type, size });
 };
 
-describe('[utility] Storage Helpers', () => {
+const createMockStorageClient = () => {
+  const mockStorage = {
+    upload: vi.fn(),
+    getPublicUrl: vi.fn(),
+    createSignedUrl: vi.fn(),
+    remove: vi.fn(),
+    download: vi.fn(),
+    list: vi.fn(),
+    copy: vi.fn()
+  };
+  
+  return {
+    from: vi.fn(() => mockStorage),
+    storage: {
+      from: vi.fn(() => mockStorage)
+    }
+  };
+};
+
+describe('[unit] Storage Helpers', () => {
   describe('getBucketName', () => {
     it('returns public-files bucket for public files', () => {
       expect(getBucketName(true)).toBe('public-files');
@@ -43,138 +71,422 @@ describe('[utility] Storage Helpers', () => {
   });
 
   describe('generateFilePath', () => {
-    it('generates correct file path with org and customPath', () => {
+    it('generates path for private files with orgId and default folder', () => {
       const result = generateFilePath(
-        { orgId: 'test-org-123', isPublic: false, customPath: 'general_documents' },
+        { appName: 'test-app', orgId: 'test-org-123', isPublic: false },
         'test-document.pdf'
       );
-      expect(result).toBe('test-org-123/general_documents/test-document.pdf');
-    });
+      expect(result).toBe('test-org-123/files/test-document.pdf');
+    }, TEST_TIMEOUT);
 
-    it('generates unique paths for same file name', () => {
-      const path1 = generateFilePath({ orgId: 'org-123', customPath: 'images' }, 'test.jpg');
-      const path2 = generateFilePath({ orgId: 'org-123', customPath: 'images' }, 'test.jpg');
-      
-      expect(path1).toBe(path2);
-    });
+    it('generates path for public files with orgId', () => {
+      const result = generateFilePath(
+        { appName: 'test-app', orgId: 'test-org-123', isPublic: true },
+        'test-document.pdf'
+      );
+      expect(result).toBe('test-org-123/public/test-document.pdf');
+    }, TEST_TIMEOUT);
+
+    it('generates path with customPath', () => {
+      const result = generateFilePath(
+        { appName: 'test-app', orgId: 'test-org-123', isPublic: false, customPath: 'documents' },
+        'test-document.pdf'
+      );
+      expect(result).toBe('test-org-123/documents/test-document.pdf');
+    }, TEST_TIMEOUT);
+
+    it('generates path for user-scoped files', () => {
+      const result = generateFilePath(
+        { appName: 'test-app', userId: 'user-123', isPublic: false },
+        'test-document.pdf'
+      );
+      expect(result).toBe('users/user-123/files/test-document.pdf');
+    }, TEST_TIMEOUT);
 
-    it('validates required orgId', () => {
-      expect(() => generateFilePath({ orgId: '' } as any, 'test.jpg'))
+    it('throws error when neither orgId nor userId provided', () => {
+      expect(() => generateFilePath({ appName: 'test-app' } as any, 'test.jpg'))
         .toThrow('Either orgId or userId is required for file path generation');
-    });
+    }, TEST_TIMEOUT);
+
+    it('prioritizes orgId over userId', () => {
+      const result = generateFilePath(
+        { appName: 'test-app', orgId: 'org-123', userId: 'user-123', isPublic: false },
+        'test.jpg'
+      );
+      expect(result).toMatch(/^org-123\//);
+      expect(result).not.toMatch(/users\//);
+    }, TEST_TIMEOUT);
+
+    it('handles customPath for public files', () => {
+      const result = generateFilePath(
+        { appName: 'test-app', orgId: 'org-123', isPublic: true, customPath: 'images' },
+        'test.jpg'
+      );
+      expect(result).toBe('org-123/images/test.jpg');
+    }, TEST_TIMEOUT);
+
+    it('handles customPath for private files', () => {
+      const result = generateFilePath(
+        { appName: 'test-app', orgId: 'org-123', isPublic: false, customPath: 'documents' },
+        'test.pdf'
+      );
+      expect(result).toBe('org-123/documents/test.pdf');
+    }, TEST_TIMEOUT);
 
-    it('handles special characters in file names', () => {
+    it('handles customPath for user-scoped files', () => {
       const result = generateFilePath(
-        { orgId: 'org-123', customPath: 'images' },
-        'test file with spaces & symbols.jpg'
+        { appName: 'test-app', userId: 'user-123', isPublic: false, customPath: 'profile' },
+        'avatar.jpg'
       );
+      expect(result).toBe('users/user-123/profile/avatar.jpg');
+    }, TEST_TIMEOUT);
+
+    it('handles customPath with nested paths', () => {
+      const result = generateFilePath(
+        { appName: 'test-app', orgId: 'org-123', isPublic: false, customPath: 'documents/2024' },
+        'test.pdf'
+      );
+      expect(result).toBe('org-123/documents/2024/test.pdf');
+    }, TEST_TIMEOUT);
+  });
+
+  describe('generateUniqueFileName', () => {
+    it('generates unique filename with timestamp and UUID', () => {
+      const result = generateUniqueFileName('test.jpg');
+      expect(result).toMatch(/^\d+-[a-f0-9-]+-test\.jpg$/);
+    }, TEST_TIMEOUT);
+
+    it('handles files without extension', () => {
+      const result = generateUniqueFileName('test');
+      expect(result).toMatch(/^\d+-[a-f0-9-]+-test$/);
+    }, TEST_TIMEOUT);
+
+    it('sanitizes filename by removing invalid characters', () => {
+      const result = generateUniqueFileName('test<>:"/\\|?*file.jpg');
+      expect(result).not.toMatch(/[<>:"/\\|?*]/);
+      expect(result).toMatch(/\.jpg$/);
+    }, TEST_TIMEOUT);
+
+    it('replaces spaces with underscores', () => {
+      const result = generateUniqueFileName('test file.jpg');
+      expect(result).toMatch(/test_file/);
+    }, TEST_TIMEOUT);
+
+    it('removes directory traversal attempts', () => {
+      const result = generateUniqueFileName('../../../test.jpg');
+      expect(result).not.toMatch(/\.\./);
+    }, TEST_TIMEOUT);
+
+    it('limits filename length', () => {
+      const longName = 'a'.repeat(300) + '.jpg';
+      const result = generateUniqueFileName(longName);
+      // Should be truncated (timestamp + UUID + baseName + extension)
+      expect(result.length).toBeLessThan(350);
+    }, TEST_TIMEOUT);
+
+    it('handles filenames with multiple dots', () => {
+      const result = generateUniqueFileName('test.file.name.jpg');
+      expect(result).toMatch(/\.jpg$/);
+      expect(result).toContain('test');
+    }, TEST_TIMEOUT);
+
+    it('handles filenames with leading/trailing dots', () => {
+      const result = generateUniqueFileName('.test.jpg');
+      expect(result).not.toMatch(/^\./);
+      expect(result).toMatch(/\.jpg$/);
+    }, TEST_TIMEOUT);
+
+    it('handles filenames with only extension', () => {
+      const result = generateUniqueFileName('.jpg');
+      expect(result).toMatch(/\.jpg$/);
+    }, TEST_TIMEOUT);
+
+    it('handles empty filename', () => {
+      const result = generateUniqueFileName('');
+      expect(result).toMatch(/^\d+-[a-f0-9-]+$/);
+    }, TEST_TIMEOUT);
+
+    it('handles unicode characters in filename', () => {
+      const result = generateUniqueFileName('测试文件.jpg');
+      expect(result).toMatch(/\.jpg$/);
+    }, TEST_TIMEOUT);
+
+    it('removes multiple consecutive invalid characters', () => {
+      const result = generateUniqueFileName('test<<>>file.jpg');
+      expect(result).not.toMatch(/[<>]/);
+      expect(result).toMatch(/test.*file/);
+    }, TEST_TIMEOUT);
+  });
+
+  describe('extractFileMetadata', () => {
+    it('extracts basic metadata for non-image files', async () => {
+      const file = createTestFile('test.pdf', 'application/pdf', 1024);
+      const options = { appName: 'test-app', orgId: 'org-123' };
       
-      expect(result).toBe('org-123/images/test file with spaces & symbols.jpg');
-    });
+      const result = await extractFileMetadata(file, options, 'user-123');
+      expect(result.ok).toBe(true);
+      const data = result.data;
+      expect(data.mimeType).toBe('application/pdf');
+      expect(data.size).toBe(file.size); // Use actual file size
+      expect(data.orgId).toBe('org-123');
+      expect(data.appName).toBe('test-app');
+      expect(data.uploadedBy).toBe('user-123');
+      expect(data.uploadedAt).toBeDefined();
+      expect(data.isPublic).toBe(false);
+    }, TEST_TIMEOUT);
+
+    it('extracts image dimensions for image files', async () => {
+      const file = createTestFile('test.jpg', 'image/jpeg', 2048);
+      
+      const mockImage = {
+        width: 800,
+        height: 600,
+        onload: null as any,
+        onerror: null as any,
+        _src: '',
+        get src() {
+          return this._src;
+        },
+        set src(value: string) {
+          this._src = value;
+          Promise.resolve().then(() => {
+            if (this.onload) {
+              this.onload();
+            }
+          });
+        }
+      };
+      
+      vi.stubGlobal('Image', vi.fn(() => mockImage));
+      vi.stubGlobal('URL', {
+        createObjectURL: vi.fn(() => 'blob:mock-url'),
+        revokeObjectURL: vi.fn()
+      });
 
-    it('preserves file extension', () => {
-      const testCases = [
-        { fileName: 'test.pdf', expectedExt: '.pdf' },
-        { fileName: 'image.jpeg', expectedExt: '.jpeg' },
-        { fileName: 'document.docx', expectedExt: '.docx' },
-        { fileName: 'noextension', expectedExt: '' }
-      ];
+      const options = { appName: 'test-app', orgId: 'org-123' };
+      const result = await extractFileMetadata(file, options, 'user-123');
+      expect(result.ok).toBe(true);
+      const data = result.data;
+      expect(data.mimeType).toBe('image/jpeg');
+      // Dimensions may or may not be extracted depending on async timing
+      if (data.width) {
+        expect(data.width).toBe(800);
+        expect(data.height).toBe(600);
+      }
+    }, TEST_TIMEOUT);
+
+    it('handles hash generation errors gracefully', async () => {
+      const file = createTestFile('test.pdf', 'application/pdf', 1024);
+      const options = { appName: 'test-app', orgId: 'org-123' };
+      
+      // Mock crypto.subtle.digest to throw an error
+      const originalDigest = crypto.subtle.digest;
+      (crypto.subtle as any).digest = vi.fn().mockRejectedValue(new Error('Hash generation failed'));
+      
+      const result = await extractFileMetadata(file, options, 'user-123');
+      expect(result.ok).toBe(true);
+      // Hash should be undefined when generation fails
+      expect(result.data.hash).toBeUndefined();
+      
+      // Restore original function
+      (crypto.subtle as any).digest = originalDigest;
+    }, TEST_TIMEOUT);
+
+    it('includes custom metadata when provided', async () => {
+      const file = createTestFile('test.pdf', 'application/pdf', 1024);
+      const options = { 
+        appName: 'test-app', 
+        orgId: 'org-123',
+        metadata: { customField: 'customValue' }
+      };
+      
+      const result = await extractFileMetadata(file, options, 'user-123');
+      expect(result.ok).toBe(true);
+      expect(result.data.customMetadata).toEqual({ customField: 'customValue' });
+    }, TEST_TIMEOUT);
+
+    it('handles user-scoped files with userId', async () => {
+      const file = createTestFile('test.pdf', 'application/pdf', 1024);
+      const options = { 
+        appName: 'test-app', 
+        userId: 'user-123'
+      };
+      
+      const result = await extractFileMetadata(file, options, 'user-123');
+      expect(result.ok).toBe(true);
+      expect(result.data.userId).toBe('user-123');
+      expect(result.data.orgId).toBeUndefined();
+    }, TEST_TIMEOUT);
+
+    it('handles public files', async () => {
+      const file = createTestFile('test.jpg', 'image/jpeg', 1024);
+      const options = { 
+        appName: 'test-app', 
+        orgId: 'org-123',
+        isPublic: true
+      };
+      
+      const result = await extractFileMetadata(file, options, 'user-123');
+      expect(result.ok).toBe(true);
+      expect(result.data.isPublic).toBe(true);
+    }, TEST_TIMEOUT);
+
+    it('handles tags when provided', async () => {
+      const file = createTestFile('test.pdf', 'application/pdf', 1024);
+      const options = { 
+        appName: 'test-app', 
+        orgId: 'org-123',
+        tags: ['tag1', 'tag2']
+      };
+      
+      const result = await extractFileMetadata(file, options, 'user-123');
+      expect(result.ok).toBe(true);
+      expect(result.data.tags).toEqual(['tag1', 'tag2']);
+    }, TEST_TIMEOUT);
+
+    it('handles image dimension extraction errors gracefully', async () => {
+      const file = createTestFile('test.jpg', 'image/jpeg', 1024);
+      
+      const mockImage = {
+        width: 0,
+        height: 0,
+        onload: null as any,
+        onerror: null as any,
+        _src: '',
+        get src() {
+          return this._src;
+        },
+        set src(value: string) {
+          this._src = value;
+          Promise.resolve().then(() => {
+            if (this.onerror) {
+              this.onerror();
+            }
+          });
+        }
+      };
       
-      testCases.forEach(({ fileName, expectedExt }) => {
-        const result = generateFilePath({ orgId: 'org-123', customPath: 'general_documents' }, fileName);
-        expect(result).toMatch(new RegExp(`${expectedExt.replace('.', '\\.')}$`));
+      vi.stubGlobal('Image', vi.fn(() => mockImage));
+      vi.stubGlobal('URL', {
+        createObjectURL: vi.fn(() => 'blob:mock-url'),
+        revokeObjectURL: vi.fn()
       });
-    });
+
+      const options = { appName: 'test-app', orgId: 'org-123' };
+      const result = await extractFileMetadata(file, options, 'user-123');
+      expect(result.ok).toBe(true);
+      // Should still return metadata even if image dimensions fail
+      expect(result.data.mimeType).toBe('image/jpeg');
+      expect(result.data.width).toBeUndefined();
+      expect(result.data.height).toBeUndefined();
+    }, TEST_TIMEOUT);
+
+    it('handles different image types', async () => {
+      const imageTypes = ['image/jpeg', 'image/png', 'image/gif', 'image/webp'];
+      
+      for (const type of imageTypes) {
+        const file = createTestFile('test.jpg', type, 1024);
+        const options = { appName: 'test-app', orgId: 'org-123' };
+        const result = await extractFileMetadata(file, options, 'user-123');
+        expect(result.ok).toBe(true);
+        expect(result.data.mimeType).toBe(type);
+      }
+    }, TEST_TIMEOUT);
   });
 
   describe('uploadFile', () => {
     it('uploads file to correct bucket successfully', async () => {
       const testFile = createTestFile();
+      const mockClient = createMockStorageClient() as any;
       const options = {
+        appName: 'test-app',
         orgId: 'test-org-123',
-        category: FileCategory.GENERAL_DOCUMENTS,
         isPublic: false
       };
       
-      mockSupabase.storage = {
-        from: vi.fn(() => ({
-          upload: vi.fn().mockResolvedValue({
-            data: { path: 'test-path' },
-            error: null
-          })
-        }))
-      };
-      
-      const result = await uploadFile(mockSupabase, testFile, options);
+      (mockClient.storage.from().upload as any).mockResolvedValue({
+        data: { path: 'test-path' },
+        error: null
+      });
+      (mockClient.storage.from().list as any).mockResolvedValue({
+        data: [],
+        error: null
+      });
       
-      expect(mockSupabase.storage.from).toHaveBeenCalledWith('files');
-      expect(result.success).toBe(true);
-      expect(result.path).toMatch(/^test-org-123\//);
-    });
+      const result = await uploadFile(mockClient as SupabaseClient<Database>, testFile, options);
+      expect(mockClient.storage.from).toHaveBeenCalledWith('files');
+      expect(result.ok).toBe(true);
+      expect(result.data.path).toMatch(/^test-org-123\//);
+    }, TEST_TIMEOUT);
 
     it('uploads to public bucket when isPublic is true', async () => {
       const testFile = createTestFile();
+      const mockClient = createMockStorageClient() as any;
       const options = {
+        appName: 'test-app',
         orgId: 'test-org-123',
-        category: FileCategory.EVENT_LOGOS,
         isPublic: true
       };
       
-      mockSupabase.storage = {
-        from: vi.fn(() => ({
-          upload: vi.fn().mockResolvedValue({
-            data: { path: 'test-path' },
-            error: null
-          })
-        }))
-      };
+      (mockClient.storage.from().upload as any).mockResolvedValue({
+        data: { path: 'test-path' },
+        error: null
+      });
+      (mockClient.storage.from().list as any).mockResolvedValue({
+        data: [],
+        error: null
+      });
+      (mockClient.storage.from().getPublicUrl as any).mockReturnValue({
+        data: { publicUrl: 'https://example.com/test-path' }
+      });
       
-      await uploadFile(mockSupabase, testFile, options);
+      await uploadFile(mockClient as SupabaseClient<Database>, testFile, options);
       
-      expect(mockSupabase.storage.from).toHaveBeenCalledWith('public-files');
-    });
+      expect(mockClient.storage.from).toHaveBeenCalledWith('public-files');
+    }, TEST_TIMEOUT);
 
     it('handles upload errors gracefully', async () => {
       const testFile = createTestFile();
+      const mockClient = createMockStorageClient() as any;
       const options = {
+        appName: 'test-app',
         orgId: 'test-org-123',
-        category: FileCategory.GENERAL_DOCUMENTS,
         isPublic: false
       };
       
-      mockSupabase.storage = {
-        from: vi.fn(() => ({
-          upload: vi.fn().mockResolvedValue({
-            data: null,
-            error: { message: 'Upload failed' }
-          })
-        }))
-      };
+      (mockClient.storage.from().upload as any).mockResolvedValue({
+        data: null,
+        error: { message: 'Upload failed' }
+      });
       
-      const result = await uploadFile(mockSupabase, testFile, options);
+      const result = await uploadFile(mockClient as SupabaseClient<Database>, testFile, options);
       
-      expect(result.success).toBe(false);
-      expect(result.error).toBe('Upload failed: Upload failed');
-    });
+      expect(result.ok).toBe(false);
+      expect(result.error.message).toBe('Upload failed');
+    }, TEST_TIMEOUT);
 
-    it('validates required parameters', async () => {
-      const testFile = createTestFile();
-      
-      const noClient = await uploadFile(null as any, testFile, {} as any);
-      expect(noClient.success).toBe(false);
-      
-      const noFile = await uploadFile(mockSupabase, null as any, {} as any);
-      expect(noFile.success).toBe(false);
+    it('validates file size before upload', async () => {
+      // PDF limit is 50MB, so use 60MB to exceed limit
+      const largeFile = createTestFile('large.pdf', 'application/pdf', 60 * 1024 * 1024);
+      const mockClient = createMockStorageClient() as any;
+      const options = {
+        appName: 'test-app',
+        orgId: 'test-org-123',
+        isPublic: false
+      };
       
-      const noOrg = await uploadFile(mockSupabase, testFile, { orgId: '' } as any);
-      expect(noOrg.success).toBe(false);
-    });
+      const result = await uploadFile(mockClient as SupabaseClient<Database>, largeFile, options);
+      expect(result.ok).toBe(false);
+      expect(result.error).toBeDefined();
+      // The error comes from validateFileSize which returns error message about size
+    }, TEST_TIMEOUT);
 
-    it('includes file metadata in result', { timeout: 10000 }, async () => {
+    it('includes file metadata in result', async () => {
       const testFile = createTestFile('test.jpg', 'image/jpeg', 2048);
+      const mockClient = createMockStorageClient() as any;
       const options = {
+        appName: 'test-app',
         orgId: 'test-org-123',
-        category: FileCategory.IMAGES,
         isPublic: false
       };
       
@@ -190,347 +502,283 @@ describe('[utility] Storage Helpers', () => {
         },
         set src(value: string) {
           this._src = value;
-          // Trigger onload asynchronously when src is set
-          setTimeout(() => {
+          Promise.resolve().then(() => {
             if (this.onload) {
               this.onload();
             }
-          }, 0);
+          });
         }
       };
       
-      const ImageConstructor = vi.fn(() => mockImage);
-      
-      vi.stubGlobal('Image', ImageConstructor);
+      vi.stubGlobal('Image', vi.fn(() => mockImage));
       vi.stubGlobal('URL', {
         createObjectURL: vi.fn(() => 'blob:mock-url'),
         revokeObjectURL: vi.fn()
       });
       
-      mockSupabase.storage = {
-        from: vi.fn(() => ({
-          upload: vi.fn().mockResolvedValue({
-            data: { path: 'test-path' },
-            error: null
-          }),
-          list: vi.fn().mockResolvedValue({
-            data: [],
-            error: null
-          })
-        }))
-      };
-      
-      const result = await uploadFile(mockSupabase, testFile, options);
+      (mockClient.storage.from().upload as any).mockResolvedValue({
+        data: { path: 'test-path' },
+        error: null
+      });
+      (mockClient.storage.from().list as any).mockResolvedValue({
+        data: [],
+        error: null
+      });
       
-      expect(result.metadata.mimeType).toBe('image/jpeg');
-      expect(result.metadata.size).toBe(testFile.size);
-      expect(result.metadata.orgId).toBe('test-org-123');
-    });
+      const result = await uploadFile(mockClient as SupabaseClient<Database>, testFile, options);
+      expect(result.ok).toBe(true);
+      expect(result.data.metadata?.mimeType).toBe('image/jpeg');
+      expect(result.data.metadata?.size).toBe(testFile.size);
+      expect(result.data.metadata?.orgId).toBe('test-org-123');
+    }, TEST_TIMEOUT);
 
     it('uses custom path when provided', async () => {
       const testFile = createTestFile();
+      const mockClient = createMockStorageClient() as any;
       const options = {
+        appName: 'test-app',
         orgId: 'test-org-123',
-        category: FileCategory.GENERAL_DOCUMENTS,
         isPublic: false,
-        customPath: 'custom/path/file.pdf'
+        customPath: 'custom/path'
       };
       
-      const mockUpload = vi.fn().mockResolvedValue({
-        data: { path: 'custom/path/file.pdf' },
+      (mockClient.storage.from().upload as any).mockResolvedValue({
+        data: { path: 'test-org-123/custom/path/test.pdf' },
+        error: null
+      });
+      (mockClient.storage.from().list as any).mockResolvedValue({
+        data: [],
         error: null
       });
       
-      mockSupabase.storage = {
-        from: vi.fn(() => ({ upload: mockUpload }))
-      };
-      
-      await uploadFile(mockSupabase, testFile, options);
-      
-      expect(mockUpload).toHaveBeenCalled();
-    });
+      const result = await uploadFile(mockClient as SupabaseClient<Database>, testFile, options);
+      expect(result.ok).toBe(true);
+      expect(result.data.path).toContain('custom/path');
+    }, TEST_TIMEOUT);
   });
 
   describe('deleteFile', () => {
     it('deletes file from correct bucket successfully', async () => {
       const filePath = 'org-123/documents/test.pdf';
+      const mockClient = createMockStorageClient() as any;
       
-      const mockRemove = vi.fn().mockResolvedValue({
+      (mockClient.storage.from().remove as any).mockResolvedValue({
         data: null,
         error: null
       });
       
-      mockSupabase.storage = {
-        from: vi.fn(() => ({ remove: mockRemove }))
-      };
-      
-      const result = await deleteFile(mockSupabase, filePath, false);
-      
-      expect(mockSupabase.storage.from).toHaveBeenCalledWith('files');
-      expect(mockRemove).toHaveBeenCalledWith([filePath]);
-      expect(result.success).toBe(true);
-    });
+      const result = await deleteFile(mockClient as SupabaseClient<Database>, filePath, false);
+      expect(mockClient.storage.from).toHaveBeenCalledWith('files');
+      expect(mockClient.storage.from().remove).toHaveBeenCalledWith([filePath]);
+      expect(result.ok).toBe(true);
+    }, TEST_TIMEOUT);
 
     it('deletes from public bucket when isPublic is true', async () => {
       const filePath = 'org-123/logos/logo.png';
+      const mockClient = createMockStorageClient() as any;
       
-      const mockRemove = vi.fn().mockResolvedValue({
+      (mockClient.storage.from().remove as any).mockResolvedValue({
         data: null,
         error: null
       });
       
-      mockSupabase.storage = {
-        from: vi.fn(() => ({ remove: mockRemove }))
-      };
-      
-      await deleteFile(mockSupabase, filePath, true);
+      await deleteFile(mockClient as SupabaseClient<Database>, filePath, true);
       
-      expect(mockSupabase.storage.from).toHaveBeenCalledWith('public-files');
-    });
+      expect(mockClient.storage.from).toHaveBeenCalledWith('public-files');
+    }, TEST_TIMEOUT);
 
     it('handles delete errors gracefully', async () => {
       const filePath = 'org-123/documents/test.pdf';
+      const mockClient = createMockStorageClient() as any;
       
-      const mockRemove = vi.fn().mockResolvedValue({
+      (mockClient.storage.from().remove as any).mockResolvedValue({
         data: null,
         error: { message: 'File not found' }
       });
       
-      mockSupabase.storage = {
-        from: vi.fn(() => ({ remove: mockRemove }))
-      };
-      
-      const result = await deleteFile(mockSupabase, filePath, false);
-      
-      expect(result.success).toBe(false);
-      expect(result.error).toBe('Delete failed: File not found');
-    });
-
-    it('validates required parameters', async () => {
-      const delNoClient = await deleteFile(null as any, 'path', false);
-      expect(delNoClient.success).toBe(false);
-      
-      const delNoPath = await deleteFile(mockSupabase, '', false);
-      expect(delNoPath.success).toBe(false);
-    });
+      const result = await deleteFile(mockClient as SupabaseClient<Database>, filePath, false);
+      expect(result.ok).toBe(false);
+      expect(result.error.message).toBe('File not found');
+    }, TEST_TIMEOUT);
   });
 
   describe('downloadFile', () => {
     it('downloads file from correct bucket successfully', async () => {
       const filePath = 'org-123/documents/test.pdf';
       const mockBlob = new Blob(['file content'], { type: 'application/pdf' });
+      const mockClient = createMockStorageClient() as any;
       
-      const mockDownload = vi.fn().mockResolvedValue({
+      (mockClient.storage.from().download as any).mockResolvedValue({
         data: mockBlob,
         error: null
       });
       
-      const mockList = vi.fn().mockResolvedValue({
+      (mockClient.storage.from().list as any).mockResolvedValue({
         data: [{ metadata: { size: mockBlob.size, mimetype: mockBlob.type } }],
         error: null
       });
-      mockSupabase.storage = {
-        from: vi.fn(() => ({ download: mockDownload, list: mockList }))
-      };
-      
-      const result = await downloadFile(mockSupabase, filePath, false);
       
-      expect(mockSupabase.storage.from).toHaveBeenCalledWith('files');
-      expect(mockDownload).toHaveBeenCalledWith(filePath);
-      expect(result?.blob).toBe(mockBlob);
-    });
+      const result = await downloadFile(mockClient as SupabaseClient<Database>, filePath, false);
+      expect(mockClient.storage.from).toHaveBeenCalledWith('files');
+      expect(mockClient.storage.from().download).toHaveBeenCalledWith(filePath);
+      expect(result.ok).toBe(true);
+      expect(result.data.blob).toBe(mockBlob);
+      expect(result.data.metadata.name).toBe('test.pdf');
+    }, TEST_TIMEOUT);
 
     it('downloads from public bucket when isPublic is true', async () => {
       const filePath = 'org-123/logos/logo.png';
       const mockBlob = new Blob(['image content'], { type: 'image/png' });
+      const mockClient = createMockStorageClient() as any;
       
-      const mockDownload = vi.fn().mockResolvedValue({
+      (mockClient.storage.from().download as any).mockResolvedValue({
         data: mockBlob,
         error: null
       });
       
-      mockSupabase.storage = {
-        from: vi.fn(() => ({ download: mockDownload }))
-      };
-      
-      await downloadFile(mockSupabase, filePath, true);
+      await downloadFile(mockClient as SupabaseClient<Database>, filePath, true);
       
-      expect(mockSupabase.storage.from).toHaveBeenCalledWith('public-files');
-    });
+      expect(mockClient.storage.from).toHaveBeenCalledWith('public-files');
+    }, TEST_TIMEOUT);
 
     it('returns null when download fails', async () => {
       const filePath = 'org-123/documents/test.pdf';
+      const mockClient = createMockStorageClient() as any;
       
-      const mockDownload = vi.fn().mockResolvedValue({
+      (mockClient.storage.from().download as any).mockResolvedValue({
         data: null,
         error: { message: 'File not found' }
       });
       
-      mockSupabase.storage = {
-        from: vi.fn(() => ({ download: mockDownload }))
-      };
-      
-      const result = await downloadFile(mockSupabase, filePath, false);
-      
-      expect(result).toBe(null);
-    });
-
-    it('validates required parameters', async () => {
-      const dlNoClient = await downloadFile(null as any, 'path', false);
-      expect(dlNoClient).toBe(null);
-      
-      const dlNoPath = await downloadFile(mockSupabase, '', false);
-      expect(dlNoPath).toBe(null);
-    });
+      const result = await downloadFile(mockClient as SupabaseClient<Database>, filePath, false);
+      expect(result.ok).toBe(false);
+      expect(result.error).toBeDefined();
+    }, TEST_TIMEOUT);
   });
 
   describe('getPublicUrl', () => {
     it('generates public URL for public bucket', () => {
       const filePath = 'org-123/logos/logo.png';
+      const mockClient = createMockStorageClient() as any;
 
-      const mockGetPublicUrl = vi.fn().mockReturnValue({
+      (mockClient.storage.from().getPublicUrl as any).mockReturnValue({
         data: { publicUrl: 'https://example.com/public/logo.png' }
       });
       
-      mockSupabase.storage = {
-        from: vi.fn(() => ({ getPublicUrl: mockGetPublicUrl }))
-      };
-      
-      const result = getPublicUrl(mockSupabase, filePath, true);
+      const result = getPublicUrl(mockClient as SupabaseClient<Database>, filePath, true);
       
-      expect(mockSupabase.storage.from).toHaveBeenCalledWith('public-files');
-      expect(mockGetPublicUrl).toHaveBeenCalledWith(filePath);
+      expect(mockClient.storage.from).toHaveBeenCalledWith('public-files');
+      expect(mockClient.storage.from().getPublicUrl).toHaveBeenCalledWith(filePath);
       expect(result).toBe('https://example.com/public/logo.png');
-    });
+    }, TEST_TIMEOUT);
 
     it('returns direct URLs without calling storage', () => {
       const directUrl = 'https://cdn.example.com/logo.png';
+      const mockClient = createMockStorageClient() as any;
 
-      const localSupabase = createMockSupabaseClient();
-      localSupabase.storage = {
-        from: vi.fn()
-      };
-
-      const result = getPublicUrl(localSupabase as any, directUrl, true);
+      const result = getPublicUrl(mockClient as SupabaseClient<Database>, directUrl, true);
 
-      expect(localSupabase.storage.from).not.toHaveBeenCalled();
+      expect(mockClient.storage.from).not.toHaveBeenCalled();
       expect(result).toBe(directUrl);
-    });
+    }, TEST_TIMEOUT);
 
     it('generates public URL for private bucket', () => {
       const filePath = 'org-123/documents/test.pdf';
+      const mockClient = createMockStorageClient() as any;
 
-      const mockGetPublicUrl = vi.fn().mockReturnValue({
+      (mockClient.storage.from().getPublicUrl as any).mockReturnValue({
         data: { publicUrl: 'https://example.com/files/test.pdf' }
       });
       
-      mockSupabase.storage = {
-        from: vi.fn(() => ({ getPublicUrl: mockGetPublicUrl }))
-      };
-      
-      const result = getPublicUrl(mockSupabase, filePath, false);
+      const result = getPublicUrl(mockClient as SupabaseClient<Database>, filePath, false);
       
-      expect(mockSupabase.storage.from).toHaveBeenCalledWith('files');
+      expect(mockClient.storage.from).toHaveBeenCalledWith('files');
       expect(result).toBe('https://example.com/files/test.pdf');
-    });
+    }, TEST_TIMEOUT);
 
     it('uses explicit bucket prefix when provided', () => {
       const filePath = 'public-files/org-123/logo.png';
+      const mockClient = createMockStorageClient() as any;
 
-      const mockGetPublicUrl = vi.fn().mockReturnValue({
+      (mockClient.storage.from().getPublicUrl as any).mockReturnValue({
         data: { publicUrl: 'https://example.com/public/logo.png' }
       });
 
-      mockSupabase.storage = {
-        from: vi.fn(() => ({ getPublicUrl: mockGetPublicUrl }))
-      };
-
-      const result = getPublicUrl(mockSupabase, filePath, true);
+      const result = getPublicUrl(mockClient as SupabaseClient<Database>, filePath, true);
 
-      expect(mockSupabase.storage.from).toHaveBeenCalledWith('public-files');
-      expect(mockGetPublicUrl).toHaveBeenCalledWith('org-123/logo.png');
+      expect(mockClient.storage.from).toHaveBeenCalledWith('public-files');
+      expect(mockClient.storage.from().getPublicUrl).toHaveBeenCalledWith('org-123/logo.png');
       expect(result).toBe('https://example.com/public/logo.png');
-    });
-
-    it('supports custom bucket hints without hyphen characters', () => {
-      const filePath = 'branding/org-123/logo.png';
-
-      const mockGetPublicUrl = vi.fn().mockReturnValue({
-        data: { publicUrl: 'https://example.com/branding/logo.png' }
-      });
-
-      mockSupabase.storage = {
-        from: vi.fn(() => ({ getPublicUrl: mockGetPublicUrl }))
-      };
-
-      const result = getPublicUrl(mockSupabase, filePath, true);
-
-      expect(mockSupabase.storage.from).toHaveBeenCalledWith('branding');
-      expect(mockGetPublicUrl).toHaveBeenCalledWith('org-123/logo.png');
-      expect(result).toBe('https://example.com/branding/logo.png');
-    });
+    }, TEST_TIMEOUT);
 
     it('supports double colon bucket hints to avoid path ambiguity', () => {
       const filePath = 'brand-assets::org-123/logo.png';
+      const mockClient = createMockStorageClient() as any;
 
-      const mockGetPublicUrl = vi.fn().mockReturnValue({
+      (mockClient.storage.from().getPublicUrl as any).mockReturnValue({
         data: { publicUrl: 'https://example.com/brand/logo.png' }
       });
 
-      mockSupabase.storage = {
-        from: vi.fn(() => ({ getPublicUrl: mockGetPublicUrl }))
-      };
-
-      const result = getPublicUrl(mockSupabase, filePath, true);
+      const result = getPublicUrl(mockClient as SupabaseClient<Database>, filePath, true);
 
-      expect(mockSupabase.storage.from).toHaveBeenCalledWith('brand-assets');
-      expect(mockGetPublicUrl).toHaveBeenCalledWith('org-123/logo.png');
+      expect(mockClient.storage.from).toHaveBeenCalledWith('brand-assets');
+      expect(mockClient.storage.from().getPublicUrl).toHaveBeenCalledWith('org-123/logo.png');
       expect(result).toBe('https://example.com/brand/logo.png');
-    });
+    }, TEST_TIMEOUT);
 
     it('treats numeric leading path segments as directories rather than buckets', () => {
       const filePath = '2024/05/logo.png';
+      const mockClient = createMockStorageClient() as any;
 
-      const mockGetPublicUrl = vi.fn().mockReturnValue({
+      (mockClient.storage.from().getPublicUrl as any).mockReturnValue({
         data: { publicUrl: 'https://example.com/public/logo.png' }
       });
 
-      mockSupabase.storage = {
-        from: vi.fn(() => ({ getPublicUrl: mockGetPublicUrl }))
-      };
-
-      const result = getPublicUrl(mockSupabase, filePath, true);
+      const result = getPublicUrl(mockClient as SupabaseClient<Database>, filePath, true);
 
-      expect(mockSupabase.storage.from).toHaveBeenCalledWith('public-files');
-      expect(mockGetPublicUrl).toHaveBeenCalledWith(filePath);
+      expect(mockClient.storage.from).toHaveBeenCalledWith('public-files');
+      expect(mockClient.storage.from().getPublicUrl).toHaveBeenCalledWith(filePath);
       expect(result).toBe('https://example.com/public/logo.png');
-    });
+    }, TEST_TIMEOUT);
 
     it('ignores bucket prefix when path starts with UUID', () => {
       const filePath = '123e4567-e89b-12d3-a456-426614174000/event_logos/logo.png';
+      const mockClient = createMockStorageClient() as any;
 
-      const mockGetPublicUrl = vi.fn().mockReturnValue({
+      (mockClient.storage.from().getPublicUrl as any).mockReturnValue({
         data: { publicUrl: 'https://example.com/public/logo.png' }
       });
 
-      mockSupabase.storage = {
-        from: vi.fn(() => ({ getPublicUrl: mockGetPublicUrl }))
-      };
-
-      const result = getPublicUrl(mockSupabase, filePath, true);
+      const result = getPublicUrl(mockClient as SupabaseClient<Database>, filePath, true);
 
-      expect(mockSupabase.storage.from).toHaveBeenCalledWith('public-files');
-      expect(mockGetPublicUrl).toHaveBeenCalledWith(filePath);
+      expect(mockClient.storage.from).toHaveBeenCalledWith('public-files');
+      expect(mockClient.storage.from().getPublicUrl).toHaveBeenCalledWith(filePath);
       expect(result).toBe('https://example.com/public/logo.png');
-    });
+    }, TEST_TIMEOUT);
 
     it('validates required parameters', () => {
+      const mockClient = createMockStorageClient() as any;
+      
       expect(() => getPublicUrl(null as any, 'path', false))
-        .toThrow();
+        .toThrow('Supabase client is required');
 
-      expect(() => getPublicUrl(mockSupabase, '', false))
-        .toThrow();
-    });
+      expect(() => getPublicUrl(mockClient as SupabaseClient<Database>, '', false))
+        .toThrow('A valid storage path is required');
+    }, TEST_TIMEOUT);
+
+    it('normalizes path by trimming whitespace and leading slashes', () => {
+      const filePath = '  /org-123/logo.png  ';
+      const mockClient = createMockStorageClient() as any;
+
+      (mockClient.storage.from().getPublicUrl as any).mockReturnValue({
+        data: { publicUrl: 'https://example.com/public/logo.png' }
+      });
+
+      const result = getPublicUrl(mockClient as SupabaseClient<Database>, filePath, true);
+
+      expect(mockClient.storage.from().getPublicUrl).toHaveBeenCalledWith('org-123/logo.png');
+      expect(result).toBe('https://example.com/public/logo.png');
+    }, TEST_TIMEOUT);
   });
 
   describe('getSignedUrl', () => {
@@ -540,22 +788,19 @@ describe('[utility] Storage Helpers', () => {
         appName: 'test-app',
         orgId: 'org-123'
       };
+      const mockClient = createMockStorageClient() as any;
       
-      const mockCreateSignedUrl = vi.fn().mockResolvedValue({
+      (mockClient.storage.from().createSignedUrl as any).mockResolvedValue({
         data: { signedUrl: 'https://example.com/signed/test.pdf?token=abc123' },
         error: null
       });
       
-      mockSupabase.storage = {
-        from: vi.fn(() => ({ createSignedUrl: mockCreateSignedUrl }))
-      };
-      
-      const result = await getSignedUrl(mockSupabase, filePath, options);
-      
-      expect(mockSupabase.storage.from).toHaveBeenCalledWith('files');
-      expect(mockCreateSignedUrl).toHaveBeenCalledWith(filePath, 3600);
-      expect(result?.url).toBe('https://example.com/signed/test.pdf?token=abc123');
-    });
+      const result = await getSignedUrl(mockClient as SupabaseClient<Database>, filePath, options);
+      expect(mockClient.storage.from).toHaveBeenCalledWith('files');
+      expect(mockClient.storage.from().createSignedUrl).toHaveBeenCalledWith(filePath, 3600);
+      expect(result.ok).toBe(true);
+      expect(result.data.url).toBe('https://example.com/signed/test.pdf?token=abc123');
+    }, TEST_TIMEOUT);
 
     it('generates signed URL with custom expiration', async () => {
       const filePath = 'org-123/documents/test.pdf';
@@ -564,20 +809,17 @@ describe('[utility] Storage Helpers', () => {
         orgId: 'org-123',
         expiresIn: 7200
       };
+      const mockClient = createMockStorageClient() as any;
       
-      const mockCreateSignedUrl = vi.fn().mockResolvedValue({
+      (mockClient.storage.from().createSignedUrl as any).mockResolvedValue({
         data: { signedUrl: 'https://example.com/signed/test.pdf?token=def456' },
         error: null
       });
       
-      mockSupabase.storage = {
-        from: vi.fn(() => ({ createSignedUrl: mockCreateSignedUrl }))
-      };
-      
-      await getSignedUrl(mockSupabase, filePath, options);
+      await getSignedUrl(mockClient as SupabaseClient<Database>, filePath, options);
       
-      expect(mockCreateSignedUrl).toHaveBeenCalledWith(filePath, 7200);
-    });
+      expect(mockClient.storage.from().createSignedUrl).toHaveBeenCalledWith(filePath, 7200);
+    }, TEST_TIMEOUT);
 
     it('returns null when signed URL generation fails', async () => {
       const filePath = 'org-123/documents/test.pdf';
@@ -585,36 +827,17 @@ describe('[utility] Storage Helpers', () => {
         appName: 'test-app',
         orgId: 'org-123'
       };
+      const mockClient = createMockStorageClient() as any;
       
-      const mockCreateSignedUrl = vi.fn().mockResolvedValue({
+      (mockClient.storage.from().createSignedUrl as any).mockResolvedValue({
         data: null,
         error: { message: 'Permission denied' }
       });
       
-      mockSupabase.storage = {
-        from: vi.fn(() => ({ createSignedUrl: mockCreateSignedUrl }))
-      };
-      
-      const result = await getSignedUrl(mockSupabase, filePath, options);
-      
-      expect(result).toBe(null);
-    });
-
-    it('validates required parameters', async () => {
-      const options = { appName: 'test-app', orgId: 'org-123' };
-      
-      const gsNoClient = await getSignedUrl(null as any, 'path', options);
-      expect(gsNoClient).toBe(null);
-      
-      const gsNoPath = await getSignedUrl(mockSupabase, '', options);
-      expect(gsNoPath).toBe(null);
-      
-      const gsNoOpts = await getSignedUrl(mockSupabase, 'path', {} as any);
-      expect(gsNoOpts).toBe(null);
-      
-      const gsNoOrg = await getSignedUrl(mockSupabase, 'path', { appName: 'test' } as any);
-      expect(gsNoOrg).toBe(null);
-    });
+      const result = await getSignedUrl(mockClient as SupabaseClient<Database>, filePath, options);
+      expect(result.ok).toBe(false);
+      expect(result.error).toBeDefined();
+    }, TEST_TIMEOUT);
 
     it('includes expiration metadata in result', async () => {
       const filePath = 'org-123/documents/test.pdf';
@@ -623,179 +846,269 @@ describe('[utility] Storage Helpers', () => {
         orgId: 'org-123',
         expiresIn: 3600
       };
+      const mockClient = createMockStorageClient() as any;
       
-      const mockCreateSignedUrl = vi.fn().mockResolvedValue({
+      (mockClient.storage.from().createSignedUrl as any).mockResolvedValue({
         data: { signedUrl: 'https://example.com/signed/test.pdf?token=abc123' },
         error: null
       });
       
-      mockSupabase.storage = {
-        from: vi.fn(() => ({ createSignedUrl: mockCreateSignedUrl }))
-      };
-      
-      const result = await getSignedUrl(mockSupabase, filePath, options);
-      
-      expect(result?.url).toContain('signed');
-      expect(typeof result?.expiresAt).toBe('string');
-    });
+      const result = await getSignedUrl(mockClient as SupabaseClient<Database>, filePath, options);
+      expect(result.ok).toBe(true);
+      expect(result.data.url).toContain('signed');
+      expect(typeof result.data.expiresAt).toBe('string');
+      expect(new Date(result.data.expiresAt).getTime()).toBeGreaterThan(Date.now());
+    }, TEST_TIMEOUT);
   });
 
-  describe('Error Handling', () => {
-    it('handles storage client errors gracefully', async () => {
-      const testFile = createTestFile();
+  describe('listFiles', () => {
+    it('lists files successfully with orgId', async () => {
+      const mockClient = createMockStorageClient() as any;
       const options = {
-        orgId: 'test-org-123',
-        category: FileCategory.GENERAL_DOCUMENTS,
+        appName: 'test-app',
+        orgId: 'org-123',
         isPublic: false
       };
       
-      mockSupabase.storage = {
-        from: vi.fn(() => {
-          throw new Error('Storage client error');
-        })
-      };
+      (mockClient.storage.from().list as any).mockResolvedValue({
+        data: [
+          { 
+            name: 'file1.jpg', 
+            metadata: { size: 1024, mimetype: 'image/jpeg' }, 
+            created_at: '2023-01-01T00:00:00Z',
+            updated_at: '2023-01-01T00:00:00Z'
+          }
+        ],
+        error: null
+      });
       
-      const res = await uploadFile(mockSupabase, testFile, options);
-      expect(res.success).toBe(false);
-    });
+      const result = await listFiles(mockClient as SupabaseClient<Database>, options);
+      expect(result.ok).toBe(true);
+      expect(result.data.files).toHaveLength(1);
+      expect(result.data.files[0].name).toBe('file1.jpg');
+      expect(result.data.totalCount).toBe(1);
+    }, TEST_TIMEOUT);
 
-    it('handles network timeouts gracefully', async () => {
-      const filePath = 'org-123/documents/test.pdf';
+    it('lists files with userId', async () => {
+      const mockClient = createMockStorageClient() as any;
+      const options = {
+        appName: 'test-app',
+        userId: 'user-123',
+        isPublic: false
+      };
       
-      const mockDownload = vi.fn().mockRejectedValue(new Error('Network timeout'));
+      (mockClient.storage.from().list as any).mockResolvedValue({
+        data: [],
+        error: null
+      });
       
-      mockSupabase.storage = {
-        from: vi.fn(() => ({ download: mockDownload }))
+      const result = await listFiles(mockClient as SupabaseClient<Database>, options);
+      expect(result.ok).toBe(true);
+      expect(result.data.files).toEqual([]);
+      expect(mockClient.storage.from().list).toHaveBeenCalledWith(
+        'users/user-123/',
+        expect.any(Object)
+      );
+    }, TEST_TIMEOUT);
+
+    it('handles missing orgId and userId gracefully', async () => {
+      const mockClient = createMockStorageClient() as any;
+      const options = {
+        appName: 'test-app',
+        isPublic: false
       };
       
-      const dl = await downloadFile(mockSupabase, filePath, false);
-      expect(dl).toBe(null);
-    });
-  });
+      // listFiles returns err when neither orgId nor userId is provided
+      const result = await listFiles(mockClient as SupabaseClient<Database>, options as any);
+      expect(result.ok).toBe(false);
+      expect(result.error.code).toBe('LIST_FILES_INVALID_OPTIONS');
+    }, TEST_TIMEOUT);
 
-  describe('Integration Scenarios', () => {
-    it('handles complete upload-download cycle', async () => {
-      const testFile = createTestFile('integration-test.pdf', 'application/pdf', 2048);
-      const uploadOptions = {
-        orgId: 'test-org-123',
-        category: FileCategory.GENERAL_DOCUMENTS,
+    it('handles list errors gracefully', async () => {
+      const mockClient = createMockStorageClient() as any;
+      const options = {
+        appName: 'test-app',
+        orgId: 'org-123',
         isPublic: false
       };
       
-      // Mock upload
-      const mockUpload = vi.fn().mockResolvedValue({
-        data: { path: 'org-123/documents/integration-test.pdf' },
-        error: null
-      });
-      
-      // Mock download
-      const mockDownload = vi.fn().mockResolvedValue({
-        data: new Blob(['file content'], { type: 'application/pdf' }),
-        error: null
+      (mockClient.storage.from().list as any).mockResolvedValue({
+        data: null,
+        error: { message: 'List failed' }
       });
       
-      const mockList = vi.fn().mockResolvedValue({ data: [{ metadata: { size: 2048, mimetype: 'application/pdf' } }], error: null });
-      mockSupabase.storage = {
-        from: vi.fn(() => ({
-          upload: mockUpload,
-          download: mockDownload,
-          list: mockList
-        }))
+      const result = await listFiles(mockClient as SupabaseClient<Database>, options);
+      expect(result.ok).toBe(false);
+      expect(result.error.message).toBe('List failed');
+    }, TEST_TIMEOUT);
+  });
+
+  describe('archiveFile', () => {
+    it('archives file successfully with orgId', async () => {
+      const mockClient = createMockStorageClient() as any;
+      const filePath = 'org-123/documents/test.pdf';
+      const options = {
+        appName: 'test-app',
+        orgId: 'org-123',
+        isPublic: false
       };
       
-      // Upload file
-      const uploadResult = await uploadFile(mockSupabase, testFile, uploadOptions);
-      expect(uploadResult.success).toBe(true);
+      (mockClient.storage.from().copy as any).mockResolvedValue({ error: null });
+      (mockClient.storage.from().remove as any).mockResolvedValue({ error: null });
       
-      // Download file
-      const downloadResult = await downloadFile(mockSupabase, uploadResult.path!, false);
-      expect(downloadResult?.blob).toBeInstanceOf(Blob);
-      expect(downloadResult?.metadata.type).toBe('application/pdf');
-    });
+      const result = await archiveFile(mockClient as SupabaseClient<Database>, filePath, options);
+      expect(result.ok).toBe(true);
+      expect(mockClient.storage.from().copy).toHaveBeenCalledWith(
+        filePath,
+        'archived/org-123/documents/test.pdf'
+      );
+    }, TEST_TIMEOUT);
 
-    it('handles public vs private file workflows', { timeout: 10000 }, async () => {
-      const publicFile = createTestFile('public.jpg', 'image/jpeg');
-      const privateFile = createTestFile('private.pdf', 'application/pdf');
+    it('archives file successfully with userId', async () => {
+      const mockClient = createMockStorageClient() as any;
+      const filePath = 'users/user-123/documents/test.pdf';
+      const options = {
+        appName: 'test-app',
+        userId: 'user-123',
+        isPublic: false
+      };
       
-      // Mock Image and URL for extractFileMetadata
-      const mockImage = {
-        width: 800,
-        height: 600,
-        onload: null as any,
-        onerror: null as any,
-        _src: '',
-        get src() {
-          return this._src;
-        },
-        set src(value: string) {
-          this._src = value;
-          // Trigger onload asynchronously when src is set
-          setTimeout(() => {
-            if (this.onload) {
-              this.onload();
-            }
-          }, 0);
-        }
+      (mockClient.storage.from().copy as any).mockResolvedValue({ error: null });
+      (mockClient.storage.from().remove as any).mockResolvedValue({ error: null });
+      
+      const result = await archiveFile(mockClient as SupabaseClient<Database>, filePath, options);
+      expect(result.ok).toBe(true);
+      expect(mockClient.storage.from().copy).toHaveBeenCalledWith(
+        filePath,
+        'archived/users/user-123/documents/test.pdf'
+      );
+    }, TEST_TIMEOUT);
+
+    it('returns error when neither orgId nor userId provided', async () => {
+      const mockClient = createMockStorageClient() as any;
+      const filePath = 'test.pdf';
+      const options = {
+        appName: 'test-app',
+        isPublic: false
       };
       
-      const ImageConstructor = vi.fn(() => mockImage);
+      const result = await archiveFile(mockClient as SupabaseClient<Database>, filePath, options as any);
+      expect(result.ok).toBe(false);
+      expect(result.error.message).toContain('Either orgId or userId is required');
+    }, TEST_TIMEOUT);
+
+    it('handles archive errors gracefully', async () => {
+      const mockClient = createMockStorageClient() as any;
+      const filePath = 'org-123/documents/test.pdf';
+      const options = {
+        appName: 'test-app',
+        orgId: 'org-123',
+        isPublic: false
+      };
       
-      vi.stubGlobal('Image', ImageConstructor);
-      vi.stubGlobal('URL', {
-        createObjectURL: vi.fn(() => 'blob:mock-url'),
-        revokeObjectURL: vi.fn()
+      (mockClient.storage.from().copy as any).mockResolvedValue({
+        error: { message: 'Copy failed' }
       });
       
-      const mockUpload = vi.fn().mockResolvedValue({
-        data: { path: 'test-path' },
-        error: null
-      });
+      const result = await archiveFile(mockClient as SupabaseClient<Database>, filePath, options);
+      expect(result.ok).toBe(false);
+      expect(result.error.message).toContain('Copy failed');
+    }, TEST_TIMEOUT);
+  });
+
+  describe('generateFileUrlsBatch', () => {
+    it('generates URLs for multiple public files', async () => {
+      const mockClient = createMockStorageClient() as any;
+      const fileReferences = [
+        { id: 'file-1', file_path: 'org-123/logo1.png', is_public: true },
+        { id: 'file-2', file_path: 'org-123/logo2.png', is_public: true }
+      ];
+      const options = {
+        appName: 'test-app',
+        orgId: 'org-123',
+        expiresIn: 3600
+      };
       
-      const mockGetPublicUrl = vi.fn().mockReturnValue({
-        data: { publicUrl: 'https://example.com/public.jpg' }
+      (mockClient.storage.from().getPublicUrl as any).mockReturnValue({
+        data: { publicUrl: 'https://example.com/file.png' }
       });
       
-      const mockCreateSignedUrl = vi.fn().mockResolvedValue({
-        data: { signedUrl: 'https://example.com/signed/private.pdf?token=abc' },
+      const result = await generateFileUrlsBatch(
+        mockClient as SupabaseClient<Database>,
+        fileReferences,
+        options
+      );
+      expect(result.ok).toBe(true);
+      expect(result.data.size).toBe(2);
+      expect(result.data.get('file-1')).toBeDefined();
+      expect(result.data.get('file-2')).toBeDefined();
+    }, TEST_TIMEOUT);
+
+    it('generates signed URLs for private files', async () => {
+      const mockClient = createMockStorageClient() as any;
+      const fileReferences = [
+        { id: 'file-1', file_path: 'org-123/doc1.pdf', is_public: false },
+        { id: 'file-2', file_path: 'org-123/doc2.pdf', is_public: false }
+      ];
+      const options = {
+        appName: 'test-app',
+        orgId: 'org-123',
+        expiresIn: 3600
+      };
+      
+      (mockClient.storage.from().createSignedUrl as any).mockResolvedValue({
+        data: { signedUrl: 'https://example.com/signed/file.pdf?token=abc' },
         error: null
       });
       
-      mockSupabase.storage = {
-        from: vi.fn(() => ({
-          upload: mockUpload,
-          getPublicUrl: mockGetPublicUrl,
-          createSignedUrl: mockCreateSignedUrl,
-          list: vi.fn().mockResolvedValue({
-            data: [],
-            error: null
-          })
-        }))
+      const result = await generateFileUrlsBatch(
+        mockClient as SupabaseClient<Database>,
+        fileReferences,
+        options
+      );
+      expect(result.ok).toBe(true);
+      expect(result.data.size).toBe(2);
+      expect(result.data.get('file-1')).toContain('signed');
+    }, TEST_TIMEOUT);
+
+    it('handles mixed public and private files', async () => {
+      const mockClient = createMockStorageClient() as any;
+      const fileReferences = [
+        { id: 'file-1', file_path: 'org-123/logo.png', is_public: true },
+        { id: 'file-2', file_path: 'org-123/doc.pdf', is_public: false }
+      ];
+      const options = {
+        appName: 'test-app',
+        orgId: 'org-123',
+        expiresIn: 3600
       };
       
-      // Upload public file
-      await uploadFile(mockSupabase, publicFile, {
-        orgId: 'org-123',
-        category: FileCategory.IMAGES,
-        isPublic: true
+      (mockClient.storage.from().getPublicUrl as any).mockReturnValue({
+        data: { publicUrl: 'https://example.com/public/logo.png' }
       });
-      
-      // Upload private file
-      await uploadFile(mockSupabase, privateFile, {
-        orgId: 'org-123',
-        category: FileCategory.GENERAL_DOCUMENTS,
-        isPublic: false
+      (mockClient.storage.from().createSignedUrl as any).mockResolvedValue({
+        data: { signedUrl: 'https://example.com/signed/doc.pdf?token=abc' },
+        error: null
       });
       
-      // Get public URL
-      const publicUrl = getPublicUrl(mockSupabase, 'org-123/images/public.jpg', true);
-      expect(publicUrl).toBe('https://example.com/public.jpg');
-      
-      // Get signed URL
-      const signedResult = await getSignedUrl(mockSupabase, 'org-123/documents/private.pdf', {
-        appName: 'test-app',
-        orgId: 'org-123'
-      });
-      expect(signedResult?.url).toBe('https://example.com/signed/private.pdf?token=abc');
-    });
+      const result = await generateFileUrlsBatch(
+        mockClient as SupabaseClient<Database>,
+        fileReferences,
+        options
+      );
+      expect(result.ok).toBe(true);
+      expect(result.data.size).toBe(2);
+    }, TEST_TIMEOUT);
+
+    it('returns empty map for empty file references', async () => {
+      const mockClient = createMockStorageClient() as any;
+      const result = await generateFileUrlsBatch(
+        mockClient as SupabaseClient<Database>,
+        [],
+        { appName: 'test-app', orgId: 'org-123' }
+      );
+      expect(result.ok).toBe(true);
+      expect(result.data.size).toBe(0);
+    }, TEST_TIMEOUT);
   });
 });