@jmruthers/pace-core 0.5.86 → 0.5.88

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

@@ -0,0 +1,631 @@
+/**
+ * @file Storage Helpers Tests
+ * @description Comprehensive tests for storage utility functions following TEST_STANDARD.md
+ */
+
+import { vi } from 'vitest';
+import { 
+  uploadFile, 
+  deleteFile, 
+  downloadFile, 
+  getPublicUrl, 
+  getSignedUrl, 
+  generateFilePath 
+} from './helpers';
+import { getBucketName } from './config';
+import { FileCategory } from '../../types/file-reference';
+import { createMockSupabaseClient } from '../../__tests__/helpers/test-utils';
+
+// Setup mocks
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+// 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', () => {
+  describe('getBucketName', () => {
+    it('returns public-files bucket for public files', () => {
+      expect(getBucketName(true)).toBe('public-files');
+    });
+
+    it('returns files bucket for private files', () => {
+      expect(getBucketName(false)).toBe('files');
+    });
+  });
+
+  describe('generateFilePath', () => {
+    it('generates correct file path with org and customPath', () => {
+      const result = generateFilePath(
+        { orgId: 'test-org-123', isPublic: false, customPath: 'general_documents' },
+        'test-document.pdf'
+      );
+      expect(result).toBe('test-org-123/general_documents/test-document.pdf');
+    });
+
+    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('validates required orgId', () => {
+      expect(() => generateFilePath({ orgId: '' } as any, 'test.jpg'))
+        .toThrow('orgId is required for file path generation');
+    });
+
+    it('handles special characters in file names', () => {
+      const result = generateFilePath(
+        { orgId: 'org-123', customPath: 'images' },
+        'test file with spaces & symbols.jpg'
+      );
+      
+      expect(result).toBe('org-123/images/test file with spaces & symbols.jpg');
+    });
+
+    it('preserves file extension', () => {
+      const testCases = [
+        { fileName: 'test.pdf', expectedExt: '.pdf' },
+        { fileName: 'image.jpeg', expectedExt: '.jpeg' },
+        { fileName: 'document.docx', expectedExt: '.docx' },
+        { fileName: 'noextension', expectedExt: '' }
+      ];
+      
+      testCases.forEach(({ fileName, expectedExt }) => {
+        const result = generateFilePath({ orgId: 'org-123', customPath: 'general_documents' }, fileName);
+        expect(result).toMatch(new RegExp(`${expectedExt.replace('.', '\\.')}$`));
+      });
+    });
+  });
+
+  describe('uploadFile', () => {
+    it('uploads file to correct bucket successfully', async () => {
+      const testFile = createTestFile();
+      const options = {
+        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);
+      
+      expect(mockSupabase.storage.from).toHaveBeenCalledWith('files');
+      expect(result.success).toBe(true);
+      expect(result.path).toMatch(/^test-org-123\//);
+    });
+
+    it('uploads to public bucket when isPublic is true', async () => {
+      const testFile = createTestFile();
+      const options = {
+        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
+          })
+        }))
+      };
+      
+      await uploadFile(mockSupabase, testFile, options);
+      
+      expect(mockSupabase.storage.from).toHaveBeenCalledWith('public-files');
+    });
+
+    it('handles upload errors gracefully', async () => {
+      const testFile = createTestFile();
+      const options = {
+        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' }
+          })
+        }))
+      };
+      
+      const result = await uploadFile(mockSupabase, testFile, options);
+      
+      expect(result.success).toBe(false);
+      expect(result.error).toBe('Upload failed: Upload failed');
+    });
+
+    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);
+      
+      const noOrg = await uploadFile(mockSupabase, testFile, { orgId: '' } as any);
+      expect(noOrg.success).toBe(false);
+    });
+
+    it('includes file metadata in result', async () => {
+      const testFile = createTestFile('test.jpg', 'image/jpeg', 2048);
+      const options = {
+        orgId: 'test-org-123',
+        category: FileCategory.IMAGES,
+        isPublic: false
+      };
+      
+      mockSupabase.storage = {
+        from: vi.fn(() => ({
+          upload: vi.fn().mockResolvedValue({
+            data: { path: 'test-path' },
+            error: null
+          })
+        }))
+      };
+      
+      const result = await uploadFile(mockSupabase, testFile, options);
+      
+      expect(result.metadata.mimeType).toBe('image/jpeg');
+      expect(result.metadata.size).toBe(testFile.size);
+      expect(result.metadata.orgId).toBe('test-org-123');
+    });
+
+    it('uses custom path when provided', async () => {
+      const testFile = createTestFile();
+      const options = {
+        orgId: 'test-org-123',
+        category: FileCategory.GENERAL_DOCUMENTS,
+        isPublic: false,
+        customPath: 'custom/path/file.pdf'
+      };
+      
+      const mockUpload = vi.fn().mockResolvedValue({
+        data: { path: 'custom/path/file.pdf' },
+        error: null
+      });
+      
+      mockSupabase.storage = {
+        from: vi.fn(() => ({ upload: mockUpload }))
+      };
+      
+      await uploadFile(mockSupabase, testFile, options);
+      
+      expect(mockUpload).toHaveBeenCalled();
+    });
+  });
+
+  describe('deleteFile', () => {
+    it('deletes file from correct bucket successfully', async () => {
+      const filePath = 'org-123/documents/test.pdf';
+      
+      const mockRemove = vi.fn().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);
+    });
+
+    it('deletes from public bucket when isPublic is true', async () => {
+      const filePath = 'org-123/logos/logo.png';
+      
+      const mockRemove = vi.fn().mockResolvedValue({
+        data: null,
+        error: null
+      });
+      
+      mockSupabase.storage = {
+        from: vi.fn(() => ({ remove: mockRemove }))
+      };
+      
+      await deleteFile(mockSupabase, filePath, true);
+      
+      expect(mockSupabase.storage.from).toHaveBeenCalledWith('public-files');
+    });
+
+    it('handles delete errors gracefully', async () => {
+      const filePath = 'org-123/documents/test.pdf';
+      
+      const mockRemove = vi.fn().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);
+    });
+  });
+
+  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 mockDownload = vi.fn().mockResolvedValue({
+        data: mockBlob,
+        error: null
+      });
+      
+      const mockList = vi.fn().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);
+    });
+
+    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 mockDownload = vi.fn().mockResolvedValue({
+        data: mockBlob,
+        error: null
+      });
+      
+      mockSupabase.storage = {
+        from: vi.fn(() => ({ download: mockDownload }))
+      };
+      
+      await downloadFile(mockSupabase, filePath, true);
+      
+      expect(mockSupabase.storage.from).toHaveBeenCalledWith('public-files');
+    });
+
+    it('returns null when download fails', async () => {
+      const filePath = 'org-123/documents/test.pdf';
+      
+      const mockDownload = vi.fn().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);
+    });
+  });
+
+  describe('getPublicUrl', () => {
+    it('generates public URL for public bucket', () => {
+      const filePath = 'org-123/logos/logo.png';
+      
+      const mockGetPublicUrl = vi.fn().mockReturnValue({
+        data: { publicUrl: 'https://example.com/public/logo.png' }
+      });
+      
+      mockSupabase.storage = {
+        from: vi.fn(() => ({ getPublicUrl: mockGetPublicUrl }))
+      };
+      
+      const result = getPublicUrl(mockSupabase, filePath, true);
+      
+      expect(mockSupabase.storage.from).toHaveBeenCalledWith('public-files');
+      expect(mockGetPublicUrl).toHaveBeenCalledWith(filePath);
+      expect(result).toBe('https://example.com/public/logo.png');
+    });
+
+    it('generates public URL for private bucket', () => {
+      const filePath = 'org-123/documents/test.pdf';
+      
+      const mockGetPublicUrl = vi.fn().mockReturnValue({
+        data: { publicUrl: 'https://example.com/files/test.pdf' }
+      });
+      
+      mockSupabase.storage = {
+        from: vi.fn(() => ({ getPublicUrl: mockGetPublicUrl }))
+      };
+      
+      const result = getPublicUrl(mockSupabase, filePath, false);
+      
+      expect(mockSupabase.storage.from).toHaveBeenCalledWith('files');
+      expect(result).toBe('https://example.com/files/test.pdf');
+    });
+
+    it('validates required parameters', () => {
+      expect(() => getPublicUrl(null as any, 'path', false))
+        .toThrow();
+      
+      expect(() => getPublicUrl(mockSupabase, '', false))
+        .toThrow();
+    });
+  });
+
+  describe('getSignedUrl', () => {
+    it('generates signed URL with default expiration', async () => {
+      const filePath = 'org-123/documents/test.pdf';
+      const options = {
+        appName: 'test-app',
+        orgId: 'org-123'
+      };
+      
+      const mockCreateSignedUrl = vi.fn().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');
+    });
+
+    it('generates signed URL with custom expiration', async () => {
+      const filePath = 'org-123/documents/test.pdf';
+      const options = {
+        appName: 'test-app',
+        orgId: 'org-123',
+        expiresIn: 7200
+      };
+      
+      const mockCreateSignedUrl = vi.fn().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);
+      
+      expect(mockCreateSignedUrl).toHaveBeenCalledWith(filePath, 7200);
+    });
+
+    it('returns null when signed URL generation fails', async () => {
+      const filePath = 'org-123/documents/test.pdf';
+      const options = {
+        appName: 'test-app',
+        orgId: 'org-123'
+      };
+      
+      const mockCreateSignedUrl = vi.fn().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);
+    });
+
+    it('includes expiration metadata in result', async () => {
+      const filePath = 'org-123/documents/test.pdf';
+      const options = {
+        appName: 'test-app',
+        orgId: 'org-123',
+        expiresIn: 3600
+      };
+      
+      const mockCreateSignedUrl = vi.fn().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');
+    });
+  });
+
+  describe('Error Handling', () => {
+    it('handles storage client errors gracefully', async () => {
+      const testFile = createTestFile();
+      const options = {
+        orgId: 'test-org-123',
+        category: FileCategory.GENERAL_DOCUMENTS,
+        isPublic: false
+      };
+      
+      mockSupabase.storage = {
+        from: vi.fn(() => {
+          throw new Error('Storage client error');
+        })
+      };
+      
+      const res = await uploadFile(mockSupabase, testFile, options);
+      expect(res.success).toBe(false);
+    });
+
+    it('handles network timeouts gracefully', async () => {
+      const filePath = 'org-123/documents/test.pdf';
+      
+      const mockDownload = vi.fn().mockRejectedValue(new Error('Network timeout'));
+      
+      mockSupabase.storage = {
+        from: vi.fn(() => ({ download: mockDownload }))
+      };
+      
+      const dl = await downloadFile(mockSupabase, filePath, false);
+      expect(dl).toBe(null);
+    });
+  });
+
+  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,
+        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
+      });
+      
+      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
+        }))
+      };
+      
+      // Upload file
+      const uploadResult = await uploadFile(mockSupabase, testFile, uploadOptions);
+      expect(uploadResult.success).toBe(true);
+      
+      // Download file
+      const downloadResult = await downloadFile(mockSupabase, uploadResult.path!, false);
+      expect(downloadResult?.blob).toBeInstanceOf(Blob);
+      expect(downloadResult?.metadata.type).toBe('application/pdf');
+    });
+
+    it('handles public vs private file workflows', async () => {
+      const publicFile = createTestFile('public.jpg', 'image/jpeg');
+      const privateFile = createTestFile('private.pdf', 'application/pdf');
+      
+      const mockUpload = vi.fn().mockResolvedValue({
+        data: { path: 'test-path' },
+        error: null
+      });
+      
+      const mockGetPublicUrl = vi.fn().mockReturnValue({
+        data: { publicUrl: 'https://example.com/public.jpg' }
+      });
+      
+      const mockCreateSignedUrl = vi.fn().mockResolvedValue({
+        data: { signedUrl: 'https://example.com/signed/private.pdf?token=abc' },
+        error: null
+      });
+      
+      mockSupabase.storage = {
+        from: vi.fn(() => ({
+          upload: mockUpload,
+          getPublicUrl: mockGetPublicUrl,
+          createSignedUrl: mockCreateSignedUrl
+        }))
+      };
+      
+      // Upload public file
+      await uploadFile(mockSupabase, publicFile, {
+        orgId: 'org-123',
+        category: FileCategory.IMAGES,
+        isPublic: true
+      });
+      
+      // Upload private file
+      await uploadFile(mockSupabase, privateFile, {
+        orgId: 'org-123',
+        category: FileCategory.GENERAL_DOCUMENTS,
+        isPublic: false
+      });
+      
+      // 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');
+    });
+  });
+});