@jmruthers/pace-core 0.6.10 → 0.6.12

package/src/utils/file-reference/file-reference.test.ts

@@ -0,0 +1,1249 @@
+/**
+ * @file File Reference Service Tests
+ * @description Comprehensive tests for the file reference service utilities following TEST_STANDARD.md
+ */
+
+import { vi } from 'vitest';
+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 '../../components/FileDisplay/useFileDisplay';
+import * as rbacApi from '../../rbac/api';
+
+const mockSetOrganisationContext = vi.fn();
+const mockUploadFile = vi.fn();
+const mockDeleteFile = vi.fn();
+const mockGenerateFilePath = vi.fn();
+const mockExtractFileMetadata = vi.fn();
+const mockGetPublicUrl = vi.fn();
+const mockGetSignedUrl = vi.fn();
+const mockInvalidateFileDisplayCache = vi.fn();
+const mockIsSuperAdmin = vi.fn();
+
+// Setup mocks
+beforeEach(() => {
+  vi.clearAllMocks();
+  
+  // Default mock implementations
+  mockSetOrganisationContext.mockResolvedValue({ ok: true, data: undefined });
+  mockUploadFile.mockResolvedValue({
+    ok: true,
+    data: { path: 'org-123/documents/test.pdf', metadata: { size: 1024 } }
+  });
+  mockDeleteFile.mockResolvedValue({ ok: true, data: undefined });
+  mockGenerateFilePath.mockReturnValue('org-123/documents/test.pdf');
+  
+  // 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({ ok: true, data: { url: 'https://example.com/signed-url', expiresAt: new Date().toISOString() } });
+  mockIsSuperAdmin.mockResolvedValue(false);
+  
+  // Apply mocks
+  vi.spyOn(organisationContext, 'setOrganisationContext').mockImplementation(mockSetOrganisationContext as any);
+  vi.spyOn(storageHelpers, 'uploadFile').mockImplementation(mockUploadFile as any);
+  vi.spyOn(storageHelpers, 'deleteFile').mockImplementation(mockDeleteFile as any);
+  vi.spyOn(storageHelpers, 'generateFilePath').mockImplementation(mockGenerateFilePath as any);
+  vi.spyOn(storageHelpers, 'extractFileMetadata').mockImplementation(mockExtractFileMetadata as any);
+  vi.spyOn(storageHelpers, 'getPublicUrl').mockImplementation(mockGetPublicUrl as any);
+  vi.spyOn(storageHelpers, 'getSignedUrl').mockImplementation(mockGetSignedUrl as any);
+  vi.spyOn(useFileDisplay, 'invalidateFileDisplayCache').mockImplementation(mockInvalidateFileDisplayCache as any);
+  vi.spyOn(rbacApi, 'isSuperAdmin').mockImplementation(mockIsSuperAdmin as any);
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+// Test data
+const mockSupabase = createMockSupabaseClient();
+const mockFileUploadOptions = {
+  table_name: 'test_table',
+  record_id: 'test-record-123',
+  organisation_id: 'test-org-123',
+  app_id: 'test-app-123',
+  category: FileCategory.GENERAL_DOCUMENTS,
+  folder: 'documents',
+  pageContext: 'configuration',
+  is_public: false
+};
+
+const mockFileReference = {
+  id: 'file-ref-123',
+  table_name: 'test_table',
+  record_id: 'test-record-123',
+  file_path: 'org-123/documents/test.pdf',
+  file_metadata: {
+    fileName: 'test-document.pdf',
+    fileType: 'application/pdf',
+    fileSize: 1024000,
+    category: FileCategory.GENERAL_DOCUMENTS
+  },
+  organisation_id: 'test-org-123',
+  app_id: 'test-app-123',
+  is_public: false,
+  created_at: '2023-01-01T00:00:00Z',
+  updated_at: '2023-01-01T00:00:00Z'
+};
+
+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;
+
+  beforeEach(() => {
+    service = new FileReferenceServiceImpl(mockSupabase);
+  });
+
+  describe('File Upload', () => {
+    it('creates file reference successfully', async () => {
+      const testFile = createTestFile();
+      
+      // Mock successful RPC call
+      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 })
+      });
+      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,
+        expect.objectContaining({
+          orgId: mockFileUploadOptions.organisation_id,
+          customPath: mockFileUploadOptions.folder,
+          isPublic: mockFileUploadOptions.is_public
+        })
+      );
+      expect(mockSupabase.rpc).toHaveBeenCalledWith(
+        'data_file_reference_create',
+        expect.objectContaining({
+          p_table_name: mockFileUploadOptions.table_name,
+          p_record_id: mockFileUploadOptions.record_id,
+          p_organisation_id: mockFileUploadOptions.organisation_id,
+          p_app_id: mockFileUploadOptions.app_id,
+          p_page_context: mockFileUploadOptions.pageContext,
+          p_file_metadata: expect.objectContaining({
+            fileName: testFile.name,
+            fileType: testFile.type,
+            fileSize: testFile.size,
+            category: mockFileUploadOptions.category
+          }),
+          p_is_public: mockFileUploadOptions.is_public
+        })
+      );
+      
+      expect(result.ok).toBe(true);
+      if (result.ok) expect(result.data.id).toBeTruthy();
+    });
+
+    it('validates required options before upload', async () => {
+      const testFile = createTestFile();
+      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 () => {
+      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({ 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' } });
+      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();
+      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
+      });
+      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();
+    });
+
+    it('handles super admin bypass logic', async () => {
+      const testFile = createTestFile();
+      
+      mockIsSuperAdmin.mockResolvedValueOnce(true);
+      
+      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
+      // Note: The check happens in the implementation, but may not be called if userId is not in options
+      expect(mockUploadFile).toHaveBeenCalled();
+    });
+
+    it('includes custom metadata when provided', async () => {
+      const testFile = createTestFile();
+      const customMetadata = { uploadedBy: 'user-123', tags: ['important'] };
+      const optionsWithMetadata = {
+        ...mockFileUploadOptions,
+        custom_metadata: customMetadata
+      };
+      
+      mockSupabase.rpc.mockResolvedValue({
+        data: 'file-ref-123',
+        error: null
+      });
+      
+      mockSupabase.from().select().eq().eq().single.mockResolvedValue({
+        data: mockFileReference,
+        error: null
+      });
+      
+      await service.createFileReference(optionsWithMetadata, testFile);
+      
+      expect(mockSupabase.rpc).toHaveBeenCalledWith(
+        'data_file_reference_create',
+        expect.objectContaining({
+          p_file_metadata: expect.objectContaining(customMetadata)
+        })
+      );
+    });
+
+    it('handles user-scoped files (organisation_id is null/undefined with userId)', async () => {
+      const testFile = createTestFile();
+      const userScopedOptions = {
+        ...mockFileUploadOptions,
+        organisation_id: undefined,
+        userId: 'user-123'
+      };
+      
+      mockSupabase.auth.getUser.mockResolvedValue({
+        data: { user: { id: 'user-123' } },
+        error: null
+      });
+      
+      mockUploadFile.mockResolvedValue({ ok: true, data: { path: 'users/user-123/documents/test.pdf' } });
+      mockSupabase.rpc.mockResolvedValue({
+        data: 'file-ref-123',
+        error: null
+      });
+      
+      mockSupabase.from().select().eq().eq().single.mockResolvedValue({
+        data: mockFileReference,
+        error: null
+      });
+      
+      await service.createFileReference(userScopedOptions, testFile);
+      
+      // Should not set organisation context for user-scoped files
+      expect(mockSetOrganisationContext).not.toHaveBeenCalled();
+      
+      // Should use authenticated user ID for upload
+      expect(mockUploadFile).toHaveBeenCalledWith(
+        mockSupabase,
+        testFile,
+        expect.objectContaining({
+          userId: 'user-123',
+          orgId: undefined
+        })
+      );
+    });
+
+    it('throws error when user-scoped file upload without authentication', async () => {
+      const testFile = createTestFile();
+      const userScopedOptions = {
+        ...mockFileUploadOptions,
+        organisation_id: undefined,
+        userId: 'user-123'
+      };
+      
+      mockSupabase.auth.getUser.mockResolvedValue({
+        data: { user: null },
+        error: { message: 'Not 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 () => {
+      const testFile = createTestFile();
+      
+      mockSupabase.rpc.mockResolvedValue({
+        data: 'file-ref-123',
+        error: null
+      });
+      
+      mockSupabase.from().select().eq().eq().single.mockResolvedValue({
+        data: mockFileReference,
+        error: null
+      });
+      
+      await service.createFileReference(mockFileUploadOptions, testFile);
+      
+      expect(mockInvalidateFileDisplayCache).toHaveBeenCalledWith(
+        mockFileUploadOptions.table_name,
+        mockFileUploadOptions.record_id,
+        mockFileUploadOptions.organisation_id,
+        mockFileUploadOptions.category
+      );
+    });
+
+    it('handles file reference fetch failure after RPC success', async () => {
+      const testFile = createTestFile();
+      
+      mockSupabase.rpc.mockResolvedValue({
+        data: 'file-ref-123',
+        error: null
+      });
+      
+      mockSupabase.from().select().eq().eq().single.mockResolvedValue({
+        data: null,
+        error: { message: 'Not found' }
+      });
+      
+      const result = await service.createFileReference(mockFileUploadOptions, testFile);
+      expect(result.ok).toBe(false);
+      if (!result.ok) expect(result.error.message).toBeTruthy();
+      expect(mockDeleteFile).toHaveBeenCalled();
+    });
+  });
+
+  describe('File Retrieval', () => {
+    it('gets file reference by table and record', async () => {
+      (mockSupabase.from() as any).select().eq().eq().eq().single.mockResolvedValue({
+        data: mockFileReference,
+        error: null
+      });
+      
+      const result = await service.getFileReference(
+        'test_table',
+        'test-record-123',
+        'test-org-123'
+      );
+      expect(expectOk(result)).toEqual(mockFileReference);
+    });
+
+    it('returns null when no file reference found (PGRST116)', async () => {
+      (mockSupabase.from() as any).select().eq().eq().eq().single.mockResolvedValue({
+        data: null,
+        error: { code: 'PGRST116', message: 'No rows found' }
+      });
+      
+      const result = await service.getFileReference(
+        'test_table',
+        'test-record-123',
+        'test-org-123'
+      );
+      expect(result.ok).toBe(true);
+      expect(result.ok && result.data).toBeNull();
+    });
+
+    it('handles null organisation_id for user-scoped files', async () => {
+      // When organisation_id is null, the query uses .is('organisation_id', null)
+      const queryBuilder = {
+        select: vi.fn().mockReturnThis(),
+        eq: vi.fn().mockReturnThis(),
+        is: vi.fn().mockReturnThis(),
+        single: vi.fn().mockResolvedValue({
+          data: { ...mockFileReference, organisation_id: null },
+          error: null
+        })
+      };
+      
+      (mockSupabase.from as any).mockReturnValue(queryBuilder);
+      
+      const result = await service.getFileReference(
+        'test_table',
+        'test-record-123',
+        null
+      );
+      
+      expect(queryBuilder.is).toHaveBeenCalledWith('organisation_id', null);
+      const data = expectOk(result);
+      expect(data?.organisation_id).toBeNull();
+    });
+
+    it('handles undefined organisation_id for user-scoped files', async () => {
+      // When organisation_id is undefined, the query uses .is('organisation_id', null)
+      const queryBuilder = {
+        select: vi.fn().mockReturnThis(),
+        eq: vi.fn().mockReturnThis(),
+        is: vi.fn().mockReturnThis(),
+        single: vi.fn().mockResolvedValue({
+          data: { ...mockFileReference, organisation_id: null },
+          error: null
+        })
+      };
+      
+      (mockSupabase.from as any).mockReturnValue(queryBuilder);
+      
+      const result = await service.getFileReference(
+        'test_table',
+        'test-record-123',
+        undefined
+      );
+      
+      expect(queryBuilder.is).toHaveBeenCalledWith('organisation_id', null);
+      const data = expectOk(result);
+      expect(data?.organisation_id).toBeNull();
+    });
+
+    it('gets file reference by ID', async () => {
+      mockSupabase.rpc.mockResolvedValue({
+        data: [mockFileReference],
+        error: null
+      });
+      
+      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' }
+      );
+      expect(expectOk(result)).toEqual(mockFileReference);
+    });
+
+    it('returns null when file reference by ID not found', async () => {
+      mockSupabase.rpc.mockResolvedValue({ data: [], error: null });
+      const result = await service.getFileReferenceById('file-ref-123', 'test-org-123');
+      expect(result.ok).toBe(true);
+      expect(result.ok && result.data).toBeNull();
+    });
+
+    it('gets files by category', async () => {
+      // RPC returns partial data: id, file_path, file_metadata, is_public, created_at
+      // The method constructs full FileReference objects from this data
+      const rpcResponse = [{
+        id: 'file-ref-123',
+        file_path: 'org-123/documents/test.pdf',
+        file_metadata: {
+          fileName: 'test-document.pdf',
+          fileType: 'application/pdf',
+          fileSize: 1024000,
+          category: FileCategory.GENERAL_DOCUMENTS
+        },
+        is_public: false,
+        created_at: '2023-01-01T00:00:00Z'
+      }];
+      
+      mockSupabase.rpc.mockResolvedValue({ data: rpcResponse, error: null });
+      
+      const result = await service.getFilesByCategory(
+        'test_table',
+        'test-record-123',
+        FileCategory.GENERAL_DOCUMENTS,
+        'test-org-123'
+      );
+      
+      expect(mockSupabase.rpc).toHaveBeenCalledWith(
+        'data_file_reference_by_category_list',
+        expect.objectContaining({
+          p_table_name: 'test_table',
+          p_record_id: 'test-record-123',
+          p_category: FileCategory.GENERAL_DOCUMENTS,
+          p_organisation_id: 'test-org-123'
+        })
+      );
+      
+      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',
+        file_path: 'org-123/documents/test.pdf',
+        file_metadata: {
+          fileName: 'test-document.pdf',
+          fileType: 'application/pdf',
+          fileSize: 1024000,
+          category: FileCategory.GENERAL_DOCUMENTS
+        },
+        organisation_id: 'test-org-123',
+        app_id: '',
+        is_public: false,
+        created_at: '2023-01-01T00:00:00Z',
+        updated_at: '2023-01-01T00:00:00Z'
+      });
+    });
+
+    it('gets file count for record', async () => {
+      mockSupabase.rpc.mockResolvedValue({
+        data: 5,
+        error: null
+      });
+      
+      const result = await service.getFileCount(
+        'test_table',
+        'test-record-123',
+        'test-org-123'
+      );
+      
+      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' }
+      );
+      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(expectOk(result)).toBe(0);
+    });
+
+    it('handles null organisation_id in getFileCount', async () => {
+      mockSupabase.rpc.mockResolvedValue({
+        data: 0,
+        error: null
+      });
+      
+      await service.getFileCount('test_table', 'test-record-123', null);
+      
+      expect(mockSupabase.rpc).toHaveBeenCalledWith(
+        'data_file_reference_count_get',
+        expect.objectContaining({
+          p_organisation_id: null
+        })
+      );
+    });
+  });
+
+  describe('URL Generation', () => {
+    it('gets file URL for public file', async () => {
+      const publicFileRef = { ...mockFileReference, is_public: true };
+      
+      (mockSupabase.from() as any).select().eq().eq().eq().single.mockResolvedValue({
+        data: publicFileRef,
+        error: null
+      });
+      
+      mockSupabase.rpc.mockResolvedValue({
+        data: 'org-123/documents/test.pdf',
+        error: null
+      });
+      
+      const result = await service.getFileUrl(
+        'test_table',
+        'test-record-123',
+        'test-org-123'
+      );
+      expect(expectOk(result)).toBe('https://example.com/public-url');
+      expect(mockGetPublicUrl).toHaveBeenCalled();
+    });
+
+    it('gets signed URL for private file via getFileUrl', async () => {
+      const privateFileRef = { ...mockFileReference, is_public: false };
+      
+      (mockSupabase.from() as any).select().eq().eq().eq().single.mockResolvedValue({
+        data: privateFileRef,
+        error: null
+      });
+      
+      mockSupabase.rpc.mockResolvedValue({
+        data: 'org-123/documents/test.pdf',
+        error: null
+      });
+      
+      const result = await service.getFileUrl(
+        'test_table',
+        'test-record-123',
+        'test-org-123'
+      );
+      expect(expectOk(result)).toBe('https://example.com/signed-url');
+      expect(mockGetSignedUrl).toHaveBeenCalled();
+    });
+
+    it('returns null when file reference not found in getFileUrl', async () => {
+      (mockSupabase.from() as any).select().eq().eq().eq().single.mockResolvedValue({
+        data: null,
+        error: { code: 'PGRST116' }
+      });
+      
+      const result = await service.getFileUrl(
+        'test_table',
+        'test-record-123',
+        'test-org-123'
+      );
+      expect(result.ok).toBe(true);
+      expect(result.ok && result.data).toBeNull();
+    });
+
+    it('gets signed URL for private file', async () => {
+      mockSupabase.rpc.mockResolvedValue({
+        data: 'org-123/documents/test.pdf',
+        error: null
+      });
+      
+      const result = await service.getSignedUrl(
+        'test_table',
+        'test-record-123',
+        'test-org-123',
+        3600
+      );
+      expect(expectOk(result)).toBe('https://example.com/signed-url');
+      expect(mockGetSignedUrl).toHaveBeenCalledWith(
+        mockSupabase,
+        'org-123/documents/test.pdf',
+        expect.objectContaining({
+          expiresIn: 3600
+        })
+      );
+    });
+
+    it('handles custom expires_in for signed URL', async () => {
+      mockSupabase.rpc.mockResolvedValue({
+        data: 'org-123/documents/test.pdf',
+        error: null
+      });
+      
+      await service.getSignedUrl(
+        'test_table',
+        'test-record-123',
+        'test-org-123',
+        7200
+      );
+      
+      expect(mockSupabase.rpc).toHaveBeenCalledWith(
+        'data_file_reference_signed_url_get',
+        expect.objectContaining({
+          p_expires_in: 7200
+        })
+      );
+    });
+  });
+
+  describe('File Management', () => {
+    it('updates file reference successfully', async () => {
+      const updates = {
+        file_metadata: {
+          ...mockFileReference.file_metadata,
+          tags: ['updated']
+        }
+      };
+
+      const updateChain = {
+        update: vi.fn().mockReturnThis(),
+        eq: vi.fn().mockReturnThis(),
+        select: vi.fn().mockReturnThis(),
+        single: vi.fn().mockResolvedValue({
+          data: { ...mockFileReference, ...updates },
+          error: null
+        })
+      };
+      (mockSupabase.from as any).mockReturnValue(updateChain);
+
+      const result = await service.updateFileReference('file-ref-123', updates);
+
+      expect(expectOk(result)).toEqual(expect.objectContaining(updates));
+    });
+
+    it('deletes file reference successfully', async () => {
+      (mockSupabase.from() as any).select().eq().eq().eq().single.mockResolvedValue({
+        data: mockFileReference,
+        error: null
+      });
+      
+      mockSupabase.rpc.mockResolvedValue({
+        data: true,
+        error: null
+      });
+      
+      const result = await service.deleteFileReference(
+        'test_table',
+        'test-record-123',
+        'test-org-123',
+        true
+      );
+      
+      expect(mockSupabase.rpc).toHaveBeenCalledWith(
+        'data_file_reference_delete',
+        {
+          p_table_name: 'test_table',
+          p_record_id: 'test-record-123',
+          p_organisation_id: 'test-org-123',
+          p_delete_file: true
+        }
+      );
+      
+      expect(mockDeleteFile).toHaveBeenCalledWith(
+        mockSupabase,
+        mockFileReference.file_path,
+        mockFileReference.is_public
+      );
+      
+      expect(expectOk(result)).toBe(true);
+    });
+
+    it('deletes file reference without deleting file from storage', async () => {
+      (mockSupabase.from() as any).select().eq().eq().eq().single.mockResolvedValue({
+        data: mockFileReference,
+        error: null
+      });
+      
+      mockSupabase.rpc.mockResolvedValue({
+        data: true,
+        error: null
+      });
+      
+      await service.deleteFileReference(
+        'test_table',
+        'test-record-123',
+        'test-org-123',
+        false
+      );
+      
+      expect(mockDeleteFile).not.toHaveBeenCalled();
+    });
+
+    it('handles null organisation_id in deleteFileReference', async () => {
+      // When organisation_id is null, getFileReference uses .is('organisation_id', null)
+      const queryBuilder = {
+        select: vi.fn().mockReturnThis(),
+        eq: vi.fn().mockReturnThis(),
+        is: vi.fn().mockReturnThis(),
+        single: vi.fn().mockResolvedValue({
+          data: { ...mockFileReference, organisation_id: null },
+          error: null
+        })
+      };
+      
+      (mockSupabase.from as any).mockReturnValue(queryBuilder);
+      
+      mockSupabase.rpc.mockResolvedValue({
+        data: true,
+        error: null
+      });
+      
+      await service.deleteFileReference('test_table', 'test-record-123', null, false);
+      
+      expect(mockSupabase.rpc).toHaveBeenCalledWith(
+        'data_file_reference_delete',
+        expect.objectContaining({
+          p_organisation_id: null
+        })
+      );
+    });
+
+    it('lists all file references for record', async () => {
+      // Mock RPC to return full data structure (as per new implementation)
+      // RPC returns: id, file_path, file_metadata, is_public, created_at
+      // The code constructs FileReference objects from this RPC response
+      mockSupabase.rpc.mockResolvedValue({ 
+        data: [{
+          id: 'file-ref-123',
+          file_path: mockFileReference.file_path,
+          file_metadata: {
+            ...mockFileReference.file_metadata,
+            app_id: mockFileReference.app_id // Include app_id in metadata for proper construction
+          },
+          is_public: mockFileReference.is_public,
+          created_at: mockFileReference.created_at
+        }], 
+        error: null 
+      });
+      
+      const result = await service.listFileReferences(
+        'test_table',
+        'test-record-123',
+        'test-org-123'
+      );
+      
+      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 () => {
+      mockSupabase.rpc.mockResolvedValue({
+        data: [],
+        error: null
+      });
+      
+      const result = await service.listFileReferences(
+        'test_table',
+        'test-record-123',
+        'test-org-123'
+      );
+      
+      expect(expectOk(result)).toEqual([]);
+    });
+
+    it('filters invalid RPC response items', async () => {
+      mockSupabase.rpc.mockResolvedValue({
+        data: [
+          { id: 'valid-1', file_path: 'path1', file_metadata: { fileName: 'file1.pdf' }, is_public: false, created_at: '2023-01-01' },
+          { id: null, file_path: 'path2', file_metadata: {} }, // Invalid - missing id
+          { id: 'valid-2', file_path: null, file_metadata: {} }, // Invalid - missing file_path
+          { id: 'valid-3', file_path: 'path3', file_metadata: null }, // Invalid - missing file_metadata
+          { id: 'valid-4', file_path: 'path4', file_metadata: { fileName: 'file4.pdf' }, is_public: false, created_at: '2023-01-01' }
+        ],
+        error: null
+      });
+      
+      const result = await service.listFileReferences(
+        'test_table',
+        'test-record-123',
+        'test-org-123'
+      );
+      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 () => {
+      mockSupabase.rpc.mockResolvedValue({
+        data: [],
+        error: null
+      });
+      
+      await service.listFileReferences('test_table', 'test-record-123', null);
+      
+      expect(mockSupabase.rpc).toHaveBeenCalledWith(
+        'data_file_reference_list',
+        expect.objectContaining({
+          p_organisation_id: null
+        })
+      );
+    });
+  });
+
+  describe('Bulk Operations', () => {
+    it('uploads multiple files successfully', async () => {
+      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);
+      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')];
+      mockUploadFile
+        .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');
+    });
+  });
+
+  describe('Error Handling', () => {
+    it('handles RPC errors gracefully in getFileReference', async () => {
+      (mockSupabase.from() as any).select().eq().eq().eq().single.mockResolvedValue({
+        data: null,
+        error: { message: 'Permission denied', code: 'ERR' }
+      });
+      
+      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'));
+      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({ 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(
+        mockSupabase,
+        'org-123/documents/test.pdf',
+        false
+      );
+    });
+
+    it('handles getFileUrl when RPC returns null path for public file', async () => {
+      const publicFileRef = { ...mockFileReference, is_public: true };
+      
+      (mockSupabase.from() as any).select().eq().eq().eq().single.mockResolvedValue({
+        data: publicFileRef,
+        error: null
+      });
+      
+      mockSupabase.rpc.mockResolvedValue({
+        data: null,
+        error: null
+      });
+      
+      const result = await service.getFileUrl(
+        'test_table',
+        'test-record-123',
+        'test-org-123'
+      );
+      expect(result.ok).toBe(true);
+      expect(result.ok && result.data).toBeNull();
+    });
+
+    it('handles getFilesByCategory with category mismatch', async () => {
+      const rpcResponse = [{
+        id: 'file-ref-123',
+        file_path: 'org-123/documents/test.pdf',
+        file_metadata: {
+          fileName: 'test-document.pdf',
+          fileType: 'application/pdf',
+          fileSize: 1024000,
+          category: FileCategory.IMAGES // Different category
+        },
+        is_public: false,
+        created_at: '2023-01-01T00:00:00Z'
+      }];
+      
+      mockSupabase.rpc.mockResolvedValue({ data: rpcResponse, error: null });
+      
+      const result = await service.getFilesByCategory(
+        'test_table',
+        'test-record-123',
+        FileCategory.GENERAL_DOCUMENTS,
+        'test-org-123'
+      );
+      
+      // Should filter out mismatched category
+      expect(expectOk(result)).toHaveLength(0);
+    });
+
+    it('handles getFilesByCategory with empty response', async () => {
+      mockSupabase.rpc.mockResolvedValue({ data: [], error: null });
+      
+      const result = await service.getFilesByCategory(
+        'test_table',
+        'test-record-123',
+        FileCategory.GENERAL_DOCUMENTS,
+        'test-org-123'
+      );
+      
+      expect(expectOk(result)).toEqual([]);
+    });
+
+    it('handles getFilesByCategory RPC errors with helpful message', async () => {
+      mockSupabase.rpc.mockResolvedValue({
+        data: null,
+        error: { message: 'RPC function error', code: 'ERR' }
+      });
+      
+      const result = await service.getFilesByCategory(
+        'test_table',
+        'test-record-123',
+        FileCategory.GENERAL_DOCUMENTS,
+        'test-org-123'
+      );
+      expect(result.ok).toBe(false);
+      if (!result.ok) expect(result.error.message).toContain('RPC function');
+    });
+
+    it('handles null organisation_id in getFilesByCategory', async () => {
+      mockSupabase.rpc.mockResolvedValue({ data: [], error: null });
+      
+      await service.getFilesByCategory(
+        'test_table',
+        'test-record-123',
+        FileCategory.GENERAL_DOCUMENTS,
+        null
+      );
+      
+      expect(mockSupabase.rpc).toHaveBeenCalledWith(
+        'data_file_reference_by_category_list',
+        expect.objectContaining({
+          p_organisation_id: null
+        })
+      );
+    });
+
+    it('handles updateFileReference errors', async () => {
+      const updates = { file_metadata: { tags: ['updated'] } };
+
+      const updateChain = {
+        update: vi.fn().mockReturnThis(),
+        eq: vi.fn().mockReturnThis(),
+        select: vi.fn().mockReturnThis(),
+        single: vi.fn().mockResolvedValue({
+          data: null,
+          error: { message: 'Update failed', code: 'ERR' }
+        })
+      };
+      (mockSupabase.from as any).mockReturnValue(updateChain);
+
+      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 () => {
+      (mockSupabase.from() as any).select().eq().eq().eq().single.mockResolvedValue({
+        data: null,
+        error: { code: 'PGRST116' }
+      });
+      
+      mockSupabase.rpc.mockResolvedValue({
+        data: true,
+        error: null
+      });
+      
+      // Should still succeed even if file reference not found (RPC handles it)
+      const result = await service.deleteFileReference(
+        'test_table',
+        'test-record-123',
+        'test-org-123',
+        false
+      );
+      
+      expect(expectOk(result)).toBe(true);
+    });
+
+    it('handles uploadMultipleFiles with all files failing', async () => {
+      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);
+      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')];
+      mockUploadFile
+        .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.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);
+      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 () => {
+      mockSupabase.rpc.mockResolvedValue({
+        data: null,
+        error: null
+      });
+      
+      const result = await service.getSignedUrl(
+        'test_table',
+        'test-record-123',
+        'test-org-123'
+      );
+      
+      expect(result.ok).toBe(true);
+      expect(result.ok && result.data).toBeNull();
+    });
+
+    it('handles getSignedUrl with RPC error', async () => {
+      mockSupabase.rpc.mockResolvedValue({
+        data: null,
+        error: { message: 'File not found' }
+      });
+      
+      const result = await service.getSignedUrl(
+        'test_table',
+        'test-record-123',
+        'test-org-123'
+      );
+      expect(result.ok).toBe(false);
+      if (!result.ok) expect(result.error.message).toContain('File not found');
+    });
+
+    it('handles getSignedUrl when getSignedUrl helper returns err', async () => {
+      mockSupabase.rpc.mockResolvedValue({
+        data: 'org-123/documents/test.pdf',
+        error: 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.ok).toBe(false);
+      if (!result.ok) expect(result.error.code).toBe('SIGNED_URL_FAILED');
+    });
+  });
+});
+
+describe('[utility] createFileReferenceService', () => {
+  it('creates service instance with supabase client', () => {
+    const service = createFileReferenceService(mockSupabase);
+    
+    expect(service).toBeInstanceOf(FileReferenceServiceImpl);
+  });
+});
+
+describe('[utility] uploadFileWithReference', () => {
+  it('uploads file and creates reference successfully for public file', async () => {
+    const testFile = createTestFile();
+    const publicOptions = { ...mockFileUploadOptions, is_public: true };
+    
+    mockSupabase.rpc.mockResolvedValue({
+      data: 'file-ref-123',
+      error: null
+    });
+
+    (mockSupabase.from() as any).select().eq().eq().eq().single.mockResolvedValue({
+      data: mockFileReference,
+      error: null
+    });
+
+    const result = await uploadFileWithReference(mockSupabase, publicOptions, testFile);
+    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();
+  });
+
+  it('uploads file and creates reference successfully for private file', async () => {
+    const testFile = createTestFile();
+    
+    mockSupabase.rpc.mockResolvedValue({
+      data: 'file-ref-123',
+      error: null
+    });
+
+    (mockSupabase.from() as any).select().eq().eq().eq().single.mockResolvedValue({
+      data: mockFileReference,
+      error: null
+    });
+
+    const result = await uploadFileWithReference(mockSupabase, mockFileUploadOptions, testFile);
+    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({ ok: false, error: { code: 'UPLOAD_FAILED', message: 'Upload failed' } });
+    const testFile = createTestFile();
+    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 () => {
+    const testFile = createTestFile();
+    
+    mockSupabase.rpc.mockResolvedValue({
+      data: 'file-ref-123',
+      error: null
+    });
+
+    (mockSupabase.from() as any).select().eq().eq().eq().single.mockResolvedValue({
+      data: mockFileReference,
+      error: null
+    });
+    
+    mockGetSignedUrl.mockResolvedValue({ ok: false, error: { code: 'SIGNED_URL_FAILED', message: 'Failed' } });
+
+    const result = await uploadFileWithReference(mockSupabase, mockFileUploadOptions, testFile);
+    const data = expectOk(result);
+    expect(data).toHaveProperty('file_reference');
+    expect(data.file_url).toBe('');
+    expect(data.signed_url).toBeUndefined();
+  });
+});