@jmruthers/pace-core 0.6.10 → 0.6.11

package/src/utils/file-reference/{__tests__/file-reference.test.ts → file-reference.test.ts}

@@ -4,15 +4,15 @@
  */
 
 import { vi } from 'vitest';
-import { FileReferenceServiceImpl, createFileReferenceService, uploadFileWithReference } from '../index';
-import { FileCategory } from '../../../types/file-reference';
-import { createMockSupabaseClient } from '../../../__tests__/helpers/test-utils';
+import { FileReferenceServiceImpl, createFileReferenceService, uploadFileWithReference } from './index';
+import { FileCategory } from '../../types/file-reference';
+import { createMockSupabaseClient } from '../../__tests__/helpers/test-utils';
 
 // Mock dependencies
-import * as organisationContext from '../../context/organisationContext';
-import * as storageHelpers from '../../storage/helpers';
-import * as useFileDisplay from '../../../hooks/useFileDisplay';
-import * as rbacApi from '../../../rbac/api';
+import * as organisationContext from '../context/organisationContext';
+import * as storageHelpers from '../storage/helpers';
+import * as useFileDisplay from '../../components/FileDisplay/useFileDisplay';
+import * as rbacApi from '../../rbac/api';
 
 const mockSetOrganisationContext = vi.fn();
 const mockUploadFile = vi.fn();
@@ -29,19 +29,21 @@ beforeEach(() => {
   vi.clearAllMocks();
   
   // Default mock implementations
-  mockSetOrganisationContext.mockResolvedValue(undefined);
+  mockSetOrganisationContext.mockResolvedValue({ ok: true, data: undefined });
   mockUploadFile.mockResolvedValue({
-    success: true,
-    path: 'org-123/documents/test.pdf',
-    metadata: { size: 1024 }
+    ok: true,
+    data: { path: 'org-123/documents/test.pdf', metadata: { size: 1024 } }
   });
-  mockDeleteFile.mockResolvedValue({ success: true });
+  mockDeleteFile.mockResolvedValue({ ok: true, data: undefined });
   mockGenerateFilePath.mockReturnValue('org-123/documents/test.pdf');
   
-  // Default metadata extraction mock
-  mockExtractFileMetadata.mockResolvedValue({ width: 100, height: 100 });
+  // Default metadata extraction mock (ApiResult)
+  mockExtractFileMetadata.mockResolvedValue({
+    ok: true,
+    data: { mimeType: 'application/pdf', size: 1024, appName: 'pace-core', uploadedBy: 'system', uploadedAt: new Date().toISOString(), tags: [], isPublic: false, customMetadata: {}, width: 100, height: 100 }
+  });
   mockGetPublicUrl.mockReturnValue('https://example.com/public-url');
-  mockGetSignedUrl.mockResolvedValue({ url: 'https://example.com/signed-url' });
+  mockGetSignedUrl.mockResolvedValue({ ok: true, data: { url: 'https://example.com/signed-url', expiresAt: new Date().toISOString() } });
   mockIsSuperAdmin.mockResolvedValue(false);
   
   // Apply mocks
@@ -95,6 +97,12 @@ const createTestFile = (name = 'test.pdf', type = 'application/pdf', size = 1024
   return new File(['test content'], name, { type, size });
 };
 
+/** Unwrap ApiResult for tests; asserts ok and returns data. */
+function expectOk<T>(result: { ok: true; data: T } | { ok: false; error: { code: string; message: string } }): T {
+  expect(result.ok).toBe(true);
+  return (result as { ok: true; data: T }).data;
+}
+
 describe('[service] FileReferenceServiceImpl', () => {
   let service: FileReferenceServiceImpl;
 
@@ -112,13 +120,19 @@ describe('[service] FileReferenceServiceImpl', () => {
         error: null
       });
       
+      mockSupabase.from.mockReturnValue({
+        select: vi.fn().mockReturnThis(),
+        eq: vi.fn().mockReturnThis(),
+        single: vi.fn().mockResolvedValue({ data: mockFileReference, error: null })
+      });
       const result = await service.createFileReference(mockFileUploadOptions, testFile);
-      
+
+      expect(result.ok).toBe(true);
+      if (result.ok) expect(result.data).toEqual(mockFileReference);
       expect(mockSetOrganisationContext).toHaveBeenCalledWith(
         mockSupabase,
         mockFileUploadOptions.organisation_id
       );
-      
       expect(mockUploadFile).toHaveBeenCalledWith(
         mockSupabase,
         testFile,
@@ -128,7 +142,6 @@ describe('[service] FileReferenceServiceImpl', () => {
           isPublic: mockFileUploadOptions.is_public
         })
       );
-      
       expect(mockSupabase.rpc).toHaveBeenCalledWith(
         'data_file_reference_create',
         expect.objectContaining({
@@ -147,83 +160,59 @@ describe('[service] FileReferenceServiceImpl', () => {
         })
       );
       
-      expect(result && typeof result === 'object').toBe(true);
-      expect((result as any).id).toBeTruthy();
+      expect(result.ok).toBe(true);
+      if (result.ok) expect(result.data.id).toBeTruthy();
     });
 
     it('validates required options before upload', async () => {
       const testFile = createTestFile();
-      
-      await expect(service.createFileReference({ ...mockFileUploadOptions, table_name: '' }, testFile))
-        .rejects.toThrow('table_name is required');
-      
-      await expect(service.createFileReference({ ...mockFileUploadOptions, record_id: '' }, testFile))
-        .rejects.toThrow('record_id is required');
-      
-      await expect(service.createFileReference({ ...mockFileUploadOptions, folder: '' }, testFile))
-        .rejects.toThrow('folder is required');
-      
-      await expect(service.createFileReference({ ...mockFileUploadOptions, organisation_id: undefined, userId: undefined }, testFile))
-        .rejects.toThrow('organisation_id is required');
+      let result = await service.createFileReference({ ...mockFileUploadOptions, table_name: '' }, testFile);
+      expect(result.ok).toBe(false);
+      if (!result.ok) expect(result.error.message).toContain('table_name is required');
+      result = await service.createFileReference({ ...mockFileUploadOptions, record_id: '' }, testFile);
+      expect(result.ok).toBe(false);
+      if (!result.ok) expect(result.error.message).toContain('record_id is required');
+      result = await service.createFileReference({ ...mockFileUploadOptions, folder: '' }, testFile);
+      expect(result.ok).toBe(false);
+      if (!result.ok) expect(result.error.message).toContain('folder is required');
+      result = await service.createFileReference({ ...mockFileUploadOptions, organisation_id: undefined, userId: undefined }, testFile);
+      expect(result.ok).toBe(false);
+      if (!result.ok) expect(result.error.message).toContain('organisation_id is required');
     });
 
     it('validates file before upload', async () => {
-      await expect(service.createFileReference(mockFileUploadOptions, null as any))
-        .rejects.toThrow();
+      const result = await service.createFileReference(mockFileUploadOptions, null as any);
+      expect(result.ok).toBe(false);
     });
 
     it('handles upload errors gracefully', async () => {
       const testFile = createTestFile();
-      
-      mockUploadFile.mockResolvedValue({
-        success: false,
-        error: 'Upload failed'
-      });
-      
-      await expect(service.createFileReference(mockFileUploadOptions, testFile))
-        .rejects.toThrow('Upload failed');
+      mockUploadFile.mockResolvedValue({ ok: false, error: { code: 'UPLOAD_FAILED', message: 'Upload failed' } });
+      const result = await service.createFileReference(mockFileUploadOptions, testFile);
+      expect(result.ok).toBe(false);
+      if (!result.ok) expect(result.error.message).toBe('Upload failed');
     });
 
     it('handles RPC errors gracefully and rolls back upload', async () => {
       const testFile = createTestFile();
-      
-      mockSupabase.rpc.mockResolvedValue({
-        data: null,
-        error: { message: 'Database error' }
-      });
-      
-      await expect(service.createFileReference(mockFileUploadOptions, testFile))
-        .rejects.toThrow('Database error');
-      
-      // Verify rollback was attempted
+      mockSupabase.rpc.mockResolvedValue({ data: null, error: { message: 'Database error' } });
+      const result = await service.createFileReference(mockFileUploadOptions, testFile);
+      expect(result.ok).toBe(false);
+      if (!result.ok) expect(result.error.message).toContain('Database error');
       expect(mockDeleteFile).toHaveBeenCalled();
     });
 
     it('handles RPC returning null (permission denied)', async () => {
       const testFile = createTestFile();
-      
-      // Mock successful upload
-      mockUploadFile.mockResolvedValue({
-        success: true,
-        path: 'org-123/documents/test.pdf'
-      });
-      
-      // Mock RPC returning null (permission denied)
-      mockSupabase.rpc.mockResolvedValue({
-        data: null,
-        error: null
-      });
-      
-      // Mock app name lookup
+      mockUploadFile.mockResolvedValue({ ok: true, data: { path: 'org-123/documents/test.pdf' } });
+      mockSupabase.rpc.mockResolvedValue({ data: null, error: null });
       mockSupabase.from().select().eq().eq().single.mockResolvedValue({
         data: { name: 'test-app' },
         error: null
       });
-      
-      await expect(service.createFileReference(mockFileUploadOptions, testFile))
-        .rejects.toThrow('insufficient permissions');
-      
-      // Verify rollback was attempted
+      const result = await service.createFileReference(mockFileUploadOptions, testFile);
+      expect(result.ok).toBe(false);
+      if (!result.ok) expect(result.error.message).toContain('insufficient permissions');
       expect(mockDeleteFile).toHaveBeenCalled();
     });
 
@@ -232,21 +221,13 @@ describe('[service] FileReferenceServiceImpl', () => {
       
       mockIsSuperAdmin.mockResolvedValueOnce(true);
       
-      mockUploadFile.mockResolvedValue({
-        success: true,
-        path: 'org-123/documents/test.pdf'
-      });
-      
-      mockSupabase.rpc.mockResolvedValue({
-        data: 'file-ref-123',
-        error: null
-      });
-      
-      mockSupabase.from().select().eq().eq().eq().single.mockResolvedValue({
-        data: mockFileReference,
-        error: null
+      mockUploadFile.mockResolvedValue({ ok: true, data: { path: 'org-123/documents/test.pdf' } });
+      mockSupabase.rpc.mockResolvedValue({ data: 'file-ref-123', error: null });
+      mockSupabase.from.mockReturnValue({
+        select: vi.fn().mockReturnThis(),
+        eq: vi.fn().mockReturnThis(),
+        single: vi.fn().mockResolvedValue({ data: mockFileReference, error: null })
       });
-      
       await service.createFileReference(mockFileUploadOptions, testFile);
       
       // Super admin check should be called if userId is provided
@@ -295,11 +276,7 @@ describe('[service] FileReferenceServiceImpl', () => {
         error: null
       });
       
-      mockUploadFile.mockResolvedValue({
-        success: true,
-        path: 'users/user-123/documents/test.pdf'
-      });
-      
+      mockUploadFile.mockResolvedValue({ ok: true, data: { path: 'users/user-123/documents/test.pdf' } });
       mockSupabase.rpc.mockResolvedValue({
         data: 'file-ref-123',
         error: null
@@ -339,8 +316,9 @@ describe('[service] FileReferenceServiceImpl', () => {
         error: { message: 'Not authenticated' }
       });
       
-      await expect(service.createFileReference(userScopedOptions, testFile))
-        .rejects.toThrow('User must be authenticated');
+      const result = await service.createFileReference(userScopedOptions, testFile);
+      expect(result.ok).toBe(false);
+      if (!result.ok) expect(result.error.message).toContain('User must be authenticated');
     });
 
     it('invalidates cache after successful upload', async () => {
@@ -379,10 +357,9 @@ describe('[service] FileReferenceServiceImpl', () => {
         error: { message: 'Not found' }
       });
       
-      await expect(service.createFileReference(mockFileUploadOptions, testFile))
-        .rejects.toThrow('Failed to fetch created file reference');
-      
-      // Verify rollback was attempted
+      const result = await service.createFileReference(mockFileUploadOptions, testFile);
+      expect(result.ok).toBe(false);
+      if (!result.ok) expect(result.error.message).toBeTruthy();
       expect(mockDeleteFile).toHaveBeenCalled();
     });
   });
@@ -399,8 +376,7 @@ describe('[service] FileReferenceServiceImpl', () => {
         'test-record-123',
         'test-org-123'
       );
-      
-      expect(result).toEqual(mockFileReference);
+      expect(expectOk(result)).toEqual(mockFileReference);
     });
 
     it('returns null when no file reference found (PGRST116)', async () => {
@@ -414,8 +390,8 @@ describe('[service] FileReferenceServiceImpl', () => {
         'test-record-123',
         'test-org-123'
       );
-      
-      expect(result).toBeNull();
+      expect(result.ok).toBe(true);
+      expect(result.ok && result.data).toBeNull();
     });
 
     it('handles null organisation_id for user-scoped files', async () => {
@@ -439,8 +415,8 @@ describe('[service] FileReferenceServiceImpl', () => {
       );
       
       expect(queryBuilder.is).toHaveBeenCalledWith('organisation_id', null);
-      expect(result).toBeDefined();
-      expect(result?.organisation_id).toBeNull();
+      const data = expectOk(result);
+      expect(data?.organisation_id).toBeNull();
     });
 
     it('handles undefined organisation_id for user-scoped files', async () => {
@@ -464,8 +440,8 @@ describe('[service] FileReferenceServiceImpl', () => {
       );
       
       expect(queryBuilder.is).toHaveBeenCalledWith('organisation_id', null);
-      expect(result).toBeDefined();
-      expect(result?.organisation_id).toBeNull();
+      const data = expectOk(result);
+      expect(data?.organisation_id).toBeNull();
     });
 
     it('gets file reference by ID', async () => {
@@ -475,27 +451,18 @@ describe('[service] FileReferenceServiceImpl', () => {
       });
       
       const result = await service.getFileReferenceById('file-ref-123', 'test-org-123');
-      
       expect(mockSupabase.rpc).toHaveBeenCalledWith(
         'data_file_reference_get',
-        {
-          p_file_reference_id: 'file-ref-123',
-          p_organisation_id: 'test-org-123'
-        }
+        { p_file_reference_id: 'file-ref-123', p_organisation_id: 'test-org-123' }
       );
-      
-      expect(result).toEqual(mockFileReference);
+      expect(expectOk(result)).toEqual(mockFileReference);
     });
 
     it('returns null when file reference by ID not found', async () => {
-      mockSupabase.rpc.mockResolvedValue({
-        data: [],
-        error: null
-      });
-      
+      mockSupabase.rpc.mockResolvedValue({ data: [], error: null });
       const result = await service.getFileReferenceById('file-ref-123', 'test-org-123');
-      
-      expect(result).toBeNull();
+      expect(result.ok).toBe(true);
+      expect(result.ok && result.data).toBeNull();
     });
 
     it('gets files by category', async () => {
@@ -533,9 +500,9 @@ describe('[service] FileReferenceServiceImpl', () => {
         })
       );
       
-      // The method constructs FileReference from RPC response
-      expect(result).toHaveLength(1);
-      expect(result[0]).toEqual({
+      const data = expectOk(result);
+      expect(data).toHaveLength(1);
+      expect(data[0]).toEqual({
         id: 'file-ref-123',
         table_name: 'test_table',
         record_id: 'test-record-123',
@@ -568,29 +535,15 @@ describe('[service] FileReferenceServiceImpl', () => {
       
       expect(mockSupabase.rpc).toHaveBeenCalledWith(
         'data_file_reference_count_get',
-        {
-          p_table_name: 'test_table',
-          p_record_id: 'test-record-123',
-          p_organisation_id: 'test-org-123'
-        }
+        { p_table_name: 'test_table', p_record_id: 'test-record-123', p_organisation_id: 'test-org-123' }
       );
-      
-      expect(result).toBe(5);
+      expect(expectOk(result)).toBe(5);
     });
 
     it('returns 0 when file count RPC returns null', async () => {
-      mockSupabase.rpc.mockResolvedValue({
-        data: null,
-        error: null
-      });
-      
-      const result = await service.getFileCount(
-        'test_table',
-        'test-record-123',
-        'test-org-123'
-      );
-      
-      expect(result).toBe(0);
+      mockSupabase.rpc.mockResolvedValue({ data: null, error: null });
+      const result = await service.getFileCount('test_table', 'test-record-123', 'test-org-123');
+      expect(expectOk(result)).toBe(0);
     });
 
     it('handles null organisation_id in getFileCount', async () => {
@@ -629,8 +582,7 @@ describe('[service] FileReferenceServiceImpl', () => {
         'test-record-123',
         'test-org-123'
       );
-      
-      expect(result).toBe('https://example.com/public-url');
+      expect(expectOk(result)).toBe('https://example.com/public-url');
       expect(mockGetPublicUrl).toHaveBeenCalled();
     });
 
@@ -652,8 +604,7 @@ describe('[service] FileReferenceServiceImpl', () => {
         'test-record-123',
         'test-org-123'
       );
-      
-      expect(result).toBe('https://example.com/signed-url');
+      expect(expectOk(result)).toBe('https://example.com/signed-url');
       expect(mockGetSignedUrl).toHaveBeenCalled();
     });
 
@@ -668,8 +619,8 @@ describe('[service] FileReferenceServiceImpl', () => {
         'test-record-123',
         'test-org-123'
       );
-      
-      expect(result).toBeNull();
+      expect(result.ok).toBe(true);
+      expect(result.ok && result.data).toBeNull();
     });
 
     it('gets signed URL for private file', async () => {
@@ -684,8 +635,7 @@ describe('[service] FileReferenceServiceImpl', () => {
         'test-org-123',
         3600
       );
-      
-      expect(result).toBe('https://example.com/signed-url');
+      expect(expectOk(result)).toBe('https://example.com/signed-url');
       expect(mockGetSignedUrl).toHaveBeenCalledWith(
         mockSupabase,
         'org-123/documents/test.pdf',
@@ -734,7 +684,7 @@ describe('[service] FileReferenceServiceImpl', () => {
       
       const result = await service.updateFileReference('file-ref-123', updates);
       
-      expect(result).toEqual(expect.objectContaining(updates));
+      expect(expectOk(result)).toEqual(expect.objectContaining(updates));
     });
 
     it('deletes file reference successfully', async () => {
@@ -771,7 +721,7 @@ describe('[service] FileReferenceServiceImpl', () => {
         mockFileReference.is_public
       );
       
-      expect(result).toBe(true);
+      expect(expectOk(result)).toBe(true);
     });
 
     it('deletes file reference without deleting file from storage', async () => {
@@ -848,17 +798,17 @@ describe('[service] FileReferenceServiceImpl', () => {
         'test-org-123'
       );
       
-      // Verify result has correct structure (constructed from RPC response)
-      expect(result).toHaveLength(1);
-      expect(result[0].id).toBe('file-ref-123');
-      expect(result[0].table_name).toBe('test_table');
-      expect(result[0].record_id).toBe('test-record-123');
-      expect(result[0].organisation_id).toBe('test-org-123');
-      expect(result[0].file_path).toBe(mockFileReference.file_path);
-      expect(result[0].file_metadata.fileName).toBe('test-document.pdf');
-      expect(result[0].file_metadata.fileType).toBe('application/pdf');
-      expect(result[0].is_public).toBe(mockFileReference.is_public);
-      expect(result[0].app_id).toBe(mockFileReference.app_id);
+      const data = expectOk(result);
+      expect(data).toHaveLength(1);
+      expect(data[0].id).toBe('file-ref-123');
+      expect(data[0].table_name).toBe('test_table');
+      expect(data[0].record_id).toBe('test-record-123');
+      expect(data[0].organisation_id).toBe('test-org-123');
+      expect(data[0].file_path).toBe(mockFileReference.file_path);
+      expect(data[0].file_metadata.fileName).toBe('test-document.pdf');
+      expect(data[0].file_metadata.fileType).toBe('application/pdf');
+      expect(data[0].is_public).toBe(mockFileReference.is_public);
+      expect(data[0].app_id).toBe(mockFileReference.app_id);
     });
 
     it('returns empty array when no file references found', async () => {
@@ -873,7 +823,7 @@ describe('[service] FileReferenceServiceImpl', () => {
         'test-org-123'
       );
       
-      expect(result).toEqual([]);
+      expect(expectOk(result)).toEqual([]);
     });
 
     it('filters invalid RPC response items', async () => {
@@ -893,10 +843,9 @@ describe('[service] FileReferenceServiceImpl', () => {
         'test-record-123',
         'test-org-123'
       );
-      
-      // Should only include valid items
-      expect(result.length).toBeGreaterThan(0);
-      expect(result.every(r => r.id && r.file_path && r.file_metadata)).toBe(true);
+      const data = expectOk(result);
+      expect(data.length).toBeGreaterThan(0);
+      expect(data.every(r => r.id && r.file_path && r.file_metadata)).toBe(true);
     });
 
     it('handles null organisation_id in listFileReferences', async () => {
@@ -918,45 +867,39 @@ describe('[service] FileReferenceServiceImpl', () => {
 
   describe('Bulk Operations', () => {
     it('uploads multiple files successfully', async () => {
-      const files = [
-        createTestFile('file1.pdf'),
-        createTestFile('file2.pdf')
-      ];
-      
-      // Mock successful uploads
+      const files = [createTestFile('file1.pdf'), createTestFile('file2.pdf')];
       mockSupabase.rpc
         .mockResolvedValueOnce({ data: 'file-ref-1', error: null })
         .mockResolvedValueOnce({ data: 'file-ref-2', error: null });
-      
+      mockSupabase.from.mockReturnValue({
+        select: vi.fn().mockReturnThis(),
+        eq: vi.fn().mockReturnThis(),
+        single: vi.fn()
+          .mockResolvedValueOnce({ data: { ...mockFileReference, id: 'file-ref-1' }, error: null })
+          .mockResolvedValueOnce({ data: { ...mockFileReference, id: 'file-ref-2' }, error: null })
+      });
       const result = await service.uploadMultipleFiles(mockFileUploadOptions, files);
-      
-      expect(result.success).toHaveLength(2);
-      expect(result.failed).toHaveLength(0);
+      const data = expectOk(result);
+      expect(data.success).toHaveLength(2);
+      expect(data.failed).toHaveLength(0);
     });
 
     it('handles partial failures in bulk upload', async () => {
-      const files = [
-        createTestFile('file1.pdf'),
-        createTestFile('file2.pdf')
-      ];
-      
-      // Mock one success, one failure
+      const files = [createTestFile('file1.pdf'), createTestFile('file2.pdf')];
       mockUploadFile
-        .mockResolvedValueOnce({ success: true, path: 'path1' })
-        .mockResolvedValueOnce({ success: false, error: 'Upload failed' });
-      
-      mockSupabase.rpc
-        .mockResolvedValueOnce({ data: 'file-ref-1', error: null })
-        .mockResolvedValueOnce({ data: null, error: { message: 'Database error' } });
-      
-      const result = await service.uploadMultipleFiles(mockFileUploadOptions, files);
-      
-      expect(result.success).toHaveLength(1);
-      expect(result.failed).toHaveLength(1);
-      expect(result.failed[0]).toEqual({
-        file: files[1],
-        error: 'Failed to upload file: Upload failed'
+        .mockResolvedValueOnce({ ok: true, data: { path: 'path1' } })
+        .mockResolvedValueOnce({ ok: false, error: { code: 'UPLOAD_FAILED', message: 'Upload failed' } });
+      mockSupabase.rpc.mockResolvedValueOnce({ data: 'file-ref-1', error: null });
+      mockSupabase.from.mockReturnValue({
+        select: vi.fn().mockReturnThis(),
+        eq: vi.fn().mockReturnThis(),
+        single: vi.fn().mockResolvedValue({ data: { ...mockFileReference, id: 'file-ref-1' }, error: null })
       });
+      const result = await service.uploadMultipleFiles(mockFileUploadOptions, files);
+      const data = expectOk(result);
+      expect(data.success).toHaveLength(1);
+      expect(data.failed).toHaveLength(1);
+      expect(data.failed[0].error).toBe('Upload failed');
     });
   });
 
@@ -967,32 +910,25 @@ describe('[service] FileReferenceServiceImpl', () => {
         error: { message: 'Permission denied', code: 'ERR' }
       });
       
-      await expect(service.getFileReference('test_table', 'test-record-123', 'test-org-123'))
-        .rejects.toThrow('Permission denied');
+      const result = await service.getFileReference('test_table', 'test-record-123', 'test-org-123');
+      expect(result.ok).toBe(false);
+      if (!result.ok) expect(result.error.message).toContain('Permission denied');
     });
 
     it('handles network errors gracefully', async () => {
       (mockSupabase.from() as any).select().eq().eq().eq().single.mockRejectedValue(new Error('Network error'));
-      
-      await expect(service.getFileReference('test_table', 'test-record-123', 'test-org-123'))
-        .rejects.toThrow('Network error');
+      const result = await service.getFileReference('test_table', 'test-record-123', 'test-org-123');
+      expect(result.ok).toBe(false);
+      if (!result.ok) expect(result.error.message).toContain('Network error');
     });
 
     it('handles rollback when RPC fails after upload', async () => {
       const testFile = createTestFile();
-      
-      mockUploadFile.mockResolvedValue({
-        success: true,
-        path: 'org-123/documents/test.pdf'
-      });
-      
-      mockSupabase.rpc.mockResolvedValue({
-        data: null,
-        error: { message: 'Database error' }
-      });
-      
-      await expect(service.createFileReference(mockFileUploadOptions, testFile))
-        .rejects.toThrow('Database error');
+      mockUploadFile.mockResolvedValue({ ok: true, data: { path: 'org-123/documents/test.pdf' } });
+      mockSupabase.rpc.mockResolvedValue({ data: null, error: { message: 'Database error' } });
+      const result = await service.createFileReference(mockFileUploadOptions, testFile);
+      expect(result.ok).toBe(false);
+      if (!result.ok) expect(result.error.message).toContain('Database error');
       
       // Verify rollback was attempted
       expect(mockDeleteFile).toHaveBeenCalledWith(
@@ -1020,8 +956,8 @@ describe('[service] FileReferenceServiceImpl', () => {
         'test-record-123',
         'test-org-123'
       );
-      
-      expect(result).toBeNull();
+      expect(result.ok).toBe(true);
+      expect(result.ok && result.data).toBeNull();
     });
 
     it('handles getFilesByCategory with category mismatch', async () => {
@@ -1048,7 +984,7 @@ describe('[service] FileReferenceServiceImpl', () => {
       );
       
       // Should filter out mismatched category
-      expect(result).toHaveLength(0);
+      expect(expectOk(result)).toHaveLength(0);
     });
 
     it('handles getFilesByCategory with empty response', async () => {
@@ -1061,7 +997,7 @@ describe('[service] FileReferenceServiceImpl', () => {
         'test-org-123'
       );
       
-      expect(result).toEqual([]);
+      expect(expectOk(result)).toEqual([]);
     });
 
     it('handles getFilesByCategory RPC errors with helpful message', async () => {
@@ -1070,12 +1006,14 @@ describe('[service] FileReferenceServiceImpl', () => {
         error: { message: 'RPC function error', code: 'ERR' }
       });
       
-      await expect(service.getFilesByCategory(
+      const result = await service.getFilesByCategory(
         'test_table',
         'test-record-123',
         FileCategory.GENERAL_DOCUMENTS,
         'test-org-123'
-      )).rejects.toThrow('RPC function required');
+      );
+      expect(result.ok).toBe(false);
+      if (!result.ok) expect(result.error.message).toContain('RPC function');
     });
 
     it('handles null organisation_id in getFilesByCategory', async () => {
@@ -1104,8 +1042,9 @@ describe('[service] FileReferenceServiceImpl', () => {
         error: { message: 'Update failed', code: 'ERR' }
       });
       
-      await expect(service.updateFileReference('file-ref-123', updates))
-        .rejects.toThrow('Update failed');
+      const result = await service.updateFileReference('file-ref-123', updates);
+      expect(result.ok).toBe(false);
+      if (!result.ok) expect(result.error.message).toContain('Update failed');
     });
 
     it('handles deleteFileReference when file reference not found', async () => {
@@ -1127,56 +1066,44 @@ describe('[service] FileReferenceServiceImpl', () => {
         false
       );
       
-      expect(result).toBe(true);
+      expect(expectOk(result)).toBe(true);
     });
 
     it('handles uploadMultipleFiles with all files failing', async () => {
-      const files = [
-        createTestFile('file1.pdf'),
-        createTestFile('file2.pdf')
-      ];
-      
-      mockUploadFile.mockResolvedValue({
-        success: false,
-        error: 'Upload failed'
-      });
-      
+      const files = [createTestFile('file1.pdf'), createTestFile('file2.pdf')];
+      mockUploadFile.mockResolvedValue({ ok: false, error: { code: 'UPLOAD_FAILED', message: 'Upload failed' } });
       const result = await service.uploadMultipleFiles(mockFileUploadOptions, files);
-      
-      expect(result.success).toHaveLength(0);
-      expect(result.failed).toHaveLength(2);
-      expect(result.total).toBe(2);
-      expect(result.successful).toBe(0);
-      expect(result.failed.every(f => f.error.includes('Upload failed'))).toBe(true);
+      const data = expectOk(result);
+      expect(data.success).toHaveLength(0);
+      expect(data.failed).toHaveLength(2);
+      expect(data.total).toBe(2);
+      expect(data.successful).toBe(0);
+      expect(data.failed.every(f => f.error.includes('Upload failed'))).toBe(true);
     });
 
     it('handles uploadMultipleFiles with mixed success and failure', async () => {
-      const files = [
-        createTestFile('file1.pdf'),
-        createTestFile('file2.pdf'),
-        createTestFile('file3.pdf')
-      ];
-      
+      const files = [createTestFile('file1.pdf'), createTestFile('file2.pdf'), createTestFile('file3.pdf')];
       mockUploadFile
-        .mockResolvedValueOnce({ success: true, path: 'path1' })
-        .mockResolvedValueOnce({ success: false, error: 'Network timeout' })
-        .mockResolvedValueOnce({ success: true, path: 'path3' });
-      
+        .mockResolvedValueOnce({ ok: true, data: { path: 'path1' } })
+        .mockResolvedValueOnce({ ok: false, error: { code: 'UPLOAD_FAILED', message: 'Network timeout' } })
+        .mockResolvedValueOnce({ ok: true, data: { path: 'path3' } });
       mockSupabase.rpc
         .mockResolvedValueOnce({ data: 'file-ref-1', error: null })
         .mockResolvedValueOnce({ data: 'file-ref-3', error: null });
-      
-      mockSupabase.from().select().eq().eq().single
-        .mockResolvedValueOnce({ data: { ...mockFileReference, id: 'file-ref-1' }, error: null })
-        .mockResolvedValueOnce({ data: { ...mockFileReference, id: 'file-ref-3' }, error: null });
-      
+      mockSupabase.from.mockReturnValue({
+        select: vi.fn().mockReturnThis(),
+        eq: vi.fn().mockReturnThis(),
+        single: vi.fn()
+          .mockResolvedValueOnce({ data: { ...mockFileReference, id: 'file-ref-1' }, error: null })
+          .mockResolvedValueOnce({ data: { ...mockFileReference, id: 'file-ref-3' }, error: null })
+      });
       const result = await service.uploadMultipleFiles(mockFileUploadOptions, files);
-      
-      expect(result.success).toHaveLength(2);
-      expect(result.failed).toHaveLength(1);
-      expect(result.total).toBe(3);
-      expect(result.successful).toBe(2);
-      expect(result.failed[0].error).toContain('Network timeout');
+      const data = expectOk(result);
+      expect(data.success).toHaveLength(2);
+      expect(data.failed).toHaveLength(1);
+      expect(data.total).toBe(3);
+      expect(data.successful).toBe(2);
+      expect(data.failed[0].error).toContain('Network timeout');
     });
 
     it('handles getSignedUrl with null file path', async () => {
@@ -1191,7 +1118,8 @@ describe('[service] FileReferenceServiceImpl', () => {
         'test-org-123'
       );
       
-      expect(result).toBeNull();
+      expect(result.ok).toBe(true);
+      expect(result.ok && result.data).toBeNull();
     });
 
     it('handles getSignedUrl with RPC error', async () => {
@@ -1200,28 +1128,28 @@ describe('[service] FileReferenceServiceImpl', () => {
         error: { message: 'File not found' }
       });
       
-      await expect(service.getSignedUrl(
+      const result = await service.getSignedUrl(
         'test_table',
         'test-record-123',
         'test-org-123'
-      )).rejects.toThrow('File not found');
+      );
+      expect(result.ok).toBe(false);
+      if (!result.ok) expect(result.error.message).toContain('File not found');
     });
 
-    it('handles getSignedUrl when getSignedUrl helper returns null', async () => {
+    it('handles getSignedUrl when getSignedUrl helper returns err', async () => {
       mockSupabase.rpc.mockResolvedValue({
         data: 'org-123/documents/test.pdf',
         error: null
       });
-      
-      mockGetSignedUrl.mockResolvedValue(null);
-      
+      mockGetSignedUrl.mockResolvedValue({ ok: false, error: { code: 'SIGNED_URL_FAILED', message: 'Failed' } });
       const result = await service.getSignedUrl(
         'test_table',
         'test-record-123',
         'test-org-123'
       );
-      
-      expect(result).toBeNull();
+      expect(result.ok).toBe(false);
+      if (!result.ok) expect(result.error.code).toBe('SIGNED_URL_FAILED');
     });
   });
 });
@@ -1250,10 +1178,10 @@ describe('[utility] uploadFileWithReference', () => {
     });
 
     const result = await uploadFileWithReference(mockSupabase, publicOptions, testFile);
-    
-    expect(result).toHaveProperty('file_reference');
-    expect(result.file_url).toBe('https://example.com/public-url');
-    expect(result.signed_url).toBeUndefined();
+    const data = expectOk(result);
+    expect(data).toHaveProperty('file_reference');
+    expect(data.file_url).toBe('https://example.com/public-url');
+    expect(data.signed_url).toBeUndefined();
     expect(mockGetPublicUrl).toHaveBeenCalled();
   });
 
@@ -1271,22 +1199,19 @@ describe('[utility] uploadFileWithReference', () => {
     });
 
     const result = await uploadFileWithReference(mockSupabase, mockFileUploadOptions, testFile);
-    
-    expect(result).toHaveProperty('file_reference');
-    expect(result.file_url).toBe('https://example.com/signed-url');
-    expect(result.signed_url).toBe('https://example.com/signed-url');
+    const data = expectOk(result);
+    expect(data).toHaveProperty('file_reference');
+    expect(data.file_url).toBe('https://example.com/signed-url');
+    expect(data.signed_url).toBe('https://example.com/signed-url');
     expect(mockGetSignedUrl).toHaveBeenCalled();
   });
 
   it('handles upload failures gracefully', async () => {
-    mockUploadFile.mockResolvedValue({
-      success: false,
-      error: 'Upload failed'
-    });
-
+    mockUploadFile.mockResolvedValue({ ok: false, error: { code: 'UPLOAD_FAILED', message: 'Upload failed' } });
     const testFile = createTestFile();
-    await expect(uploadFileWithReference(mockSupabase, mockFileUploadOptions, testFile))
-      .rejects.toThrow('Upload failed');
+    const result = await uploadFileWithReference(mockSupabase, mockFileUploadOptions, testFile);
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error.message).toBe('Upload failed');
   });
 
   it('handles URL generation failures gracefully', async () => {
@@ -1302,12 +1227,12 @@ describe('[utility] uploadFileWithReference', () => {
       error: null
     });
     
-    mockGetSignedUrl.mockResolvedValue(null);
+    mockGetSignedUrl.mockResolvedValue({ ok: false, error: { code: 'SIGNED_URL_FAILED', message: 'Failed' } });
 
     const result = await uploadFileWithReference(mockSupabase, mockFileUploadOptions, testFile);
-    
-    expect(result).toHaveProperty('file_reference');
-    expect(result.file_url).toBe('');
-    expect(result.signed_url).toBeUndefined();
+    const data = expectOk(result);
+    expect(data).toHaveProperty('file_reference');
+    expect(data.file_url).toBe('');
+    expect(data.signed_url).toBeUndefined();
   });
 });