@jmruthers/pace-core 0.6.9 → 0.6.11

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

@@ -8,17 +8,57 @@ import {
   FileReferenceService, 
   FileUploadResult,
   FileCategory,
-  FileMetadata
+  FileMetadata,
+  BulkUploadResult
 } from '../../types/file-reference';
+import type { Database } from '../../types/database';
+import { ok, err, type ApiResult, type ApiError } from '../../types/api-result';
 import { uploadFile, getPublicUrl, getSignedUrl, deleteFile, extractFileMetadata } from '../storage/helpers';
 import { setOrganisationContext } from '../context/organisationContext';
-import { invalidateFileDisplayCache } from '../../hooks/useFileDisplay';
+import { invalidateFileDisplayCache } from '../../components/FileDisplay/useFileDisplay';
 import { createLogger } from '../core/logger';
 import { assertAppId } from '../../types/core';
-import { isSuperAdmin } from '../../rbac/api';
 
 const log = createLogger('FileReferenceService');
 
+function toApiError(error: unknown): ApiError {
+  const message = error instanceof Error ? error.message : 'Unknown error';
+  const code = error instanceof Error && (error as Error & { code?: string }).code
+    ? (error as Error & { code: string }).code
+    : 'FILE_REFERENCE_ERROR';
+  return { code, message };
+}
+
+/** Row type from core_file_references table */
+export type CoreFileReferencesRow = Database['public']['Tables']['core_file_references']['Row'];
+
+/**
+ * Maps a core_file_references DB row to FileReference.
+ * Used by useFileDisplay and fetchFileDisplayData when reading from direct queries.
+ */
+export function mapFileReferenceRowToFileReference(f: CoreFileReferencesRow): FileReference {
+  const fileName = f.file_path.split('/').pop() || 'unknown';
+  const fileType = fileName.split('.').pop() || 'unknown';
+  const metadata = f.file_metadata as { fileName?: string; fileType?: string; category?: FileCategory; [key: string]: unknown } | null;
+  return {
+    id: f.id,
+    table_name: f.table_name,
+    record_id: f.record_id,
+    file_path: f.file_path,
+    file_metadata: {
+      fileName: metadata?.fileName || fileName,
+      fileType: metadata?.fileType || fileType,
+      category: metadata?.category || FileCategory.GENERAL_DOCUMENTS,
+      ...(metadata || {})
+    } as FileReference['file_metadata'],
+    organisation_id: f.organisation_id,
+    app_id: f.app_id as FileReference['app_id'],
+    is_public: f.is_public ?? false,
+    created_at: f.created_at || new Date().toISOString(),
+    updated_at: f.updated_at || new Date().toISOString()
+  };
+}
+
 export class FileReferenceServiceImpl implements FileReferenceService {
   constructor(private supabase: SupabaseClient) {}
 
@@ -32,17 +72,163 @@ export class FileReferenceServiceImpl implements FileReferenceService {
         .select('name')
         .eq('id', appId)
         .single();
-      
+
       if (error || !data) {
         return 'unknown';
       }
-      
+
       return data.name || 'unknown';
     } catch {
       return 'unknown';
     }
   }
 
+  private validateCreateOptions(options: FileUploadOptions): ApiResult<{ isUserScoped: boolean }> {
+    const isUserScoped = !options.organisation_id && !!options.userId;
+    if (!isUserScoped && !options.organisation_id) {
+      return err({ code: 'VALIDATION_ERROR', message: 'organisation_id is required for file upload, or userId must be provided for user-scoped files' });
+    }
+    if (!options.table_name) {
+      return err({ code: 'VALIDATION_ERROR', message: 'table_name is required for file upload' });
+    }
+    if (!options.record_id) {
+      return err({ code: 'VALIDATION_ERROR', message: 'record_id is required for file upload' });
+    }
+    if (!options.folder) {
+      return err({ code: 'VALIDATION_ERROR', message: 'folder is required for file upload. The folder prop determines the storage path.' });
+    }
+    return ok({ isUserScoped });
+  }
+
+  private async resolveAuthenticatedUserIdForUserScoped(): Promise<ApiResult<string>> {
+    const { data: { user: authUser }, error: authError } = await this.supabase.auth.getUser();
+    if (authError || !authUser) {
+      return err({ code: 'UNAUTHORIZED', message: 'User must be authenticated to upload user-scoped files' });
+    }
+    log.debug('Using authenticated user ID for user-scoped file upload', { userId: authUser.id });
+    return ok(authUser.id);
+  }
+
+  private async checkSuperAdminUser(userId: string | undefined): Promise<boolean> {
+    if (!userId) return false;
+    try {
+      const { isSuperAdmin } = await import('../../rbac/api');
+      const superResult = await isSuperAdmin(userId);
+      if (superResult.ok && superResult.data) {
+        log.debug('Super admin detected - bypassing permission checks', { userId });
+        return true;
+      }
+      return false;
+    } catch (superAdminCheckError) {
+      log.warn('Failed to check super-admin status, proceeding with normal permission checks', superAdminCheckError);
+      return false;
+    }
+  }
+
+  private async uploadFileAndExtractMetadata(
+    options: FileUploadOptions,
+    file: File,
+    authenticatedUserId: string | undefined,
+    isUserScoped: boolean
+  ): Promise<ApiResult<{ path: string; metadata: Record<string, unknown> }>> {
+    const userId = authenticatedUserId || (isUserScoped ? undefined : options.userId);
+    const uploadResult = await uploadFile(this.supabase, file, {
+      appName: 'file-reference',
+      orgId: options.organisation_id || undefined,
+      userId,
+      isPublic: options.is_public || false,
+      customPath: options.folder
+    });
+    if (!uploadResult.ok) return err(uploadResult.error);
+    const metadataResult = await extractFileMetadata(file, {
+      appName: 'file-reference',
+      orgId: options.organisation_id || undefined,
+      userId,
+      isPublic: options.is_public || false
+    }, 'system');
+    if (!metadataResult.ok) return err(metadataResult.error);
+    return ok({ path: uploadResult.data.path, metadata: metadataResult.data as unknown as Record<string, unknown> });
+  }
+
+  private async setOrgContextIfNeeded(isUserScoped: boolean, organisation_id: string | undefined): Promise<void> {
+    if (isUserScoped || !organisation_id) return;
+    const ctxResult = await setOrganisationContext(this.supabase, organisation_id);
+    if (!ctxResult.ok) {
+      log.warn('setOrganisationContext failed (non-fatal):', ctxResult.error.message);
+    }
+  }
+
+  private async resolveRpcUserId(
+    authenticatedUserId: string | undefined,
+    options: FileUploadOptions
+  ): Promise<string | null> {
+    if (authenticatedUserId) return authenticatedUserId;
+    if (options.userId) return options.userId;
+    const { data: { user: authUser } } = await this.supabase.auth.getUser();
+    return authUser?.id ?? null;
+  }
+
+  private async buildPermissionDeniedMessage(
+    options: FileUploadOptions,
+    isSuperAdminUser: boolean
+  ): Promise<string> {
+    const appName = await this.getAppName(options.app_id).catch(() => 'unknown');
+    const pageContextDisplay = options.pageContext || 'undefined';
+    return isSuperAdminUser
+      ? `File upload failed for super-admin user. Page context: '${pageContextDisplay}', App: '${appName}'.`
+      : `File upload denied: insufficient permissions. You need 'create:page.${pageContextDisplay}' or 'update:page.${pageContextDisplay}' for the '${pageContextDisplay}' page.`;
+  }
+
+  private async rollbackUploadAndErr(
+    filePath: string,
+    isPublic: boolean,
+    code: string,
+    message: string
+  ): Promise<ApiResult<FileReference>> {
+    await deleteFile(this.supabase, filePath, isPublic);
+    return err({ code, message });
+  }
+
+  private async fetchCreatedFileReference(createdId: string): Promise<ApiResult<FileReference>> {
+    const { data: fileRef, error: fetchError } = await this.supabase
+      .from('core_file_references')
+      .select('id, table_name, record_id, file_path, file_metadata, organisation_id, app_id, is_public, created_at, updated_at')
+      .eq('id', createdId)
+      .single();
+    if (fetchError || !fileRef) {
+      return err({ code: 'FETCH_FAILED', message: fetchError?.message ?? 'Failed to fetch created file reference' });
+    }
+    return ok(fileRef as FileReference);
+  }
+
+  private buildCreateRpcPayload(
+    options: FileUploadOptions,
+    filePath: string,
+    file: File,
+    metadata: Record<string, unknown>,
+    rpcUserId: string | null
+  ): Record<string, unknown> {
+    return {
+      p_table_name: options.table_name,
+      p_record_id: options.record_id,
+      p_file_path: filePath,
+      p_organisation_id: options.organisation_id ?? null,
+      p_app_id: options.app_id,
+      p_page_context: options.pageContext,
+      p_event_id: options.event_id || null,
+      p_file_metadata: {
+        fileName: file.name,
+        fileType: file.type,
+        fileSize: file.size,
+        category: options.category,
+        ...metadata,
+        ...options.custom_metadata
+      },
+      p_is_public: options.is_public || false,
+      p_user_id: rpcUserId
+    };
+  }
+
   /**
    * Creates a file reference by uploading a file to storage and linking it in the database.
    * 
@@ -57,175 +243,50 @@ export class FileReferenceServiceImpl implements FileReferenceService {
    * 
    * This ensures atomicity: either both storage and DB succeed, or both are cleaned up.
    */
-  async createFileReference(options: FileUploadOptions, file: File): Promise<FileReference> {
+  async createFileReference(options: FileUploadOptions, file: File): Promise<ApiResult<FileReference>> {
     try {
+      const validation = this.validateCreateOptions(options);
+      if (!validation.ok) return validation;
+      const { isUserScoped } = validation.data;
 
-      // organisation_id is optional for user-scoped files (e.g., profile photos)
-      const isUserScoped = !options.organisation_id && options.userId;
-      if (!isUserScoped && !options.organisation_id) {
-        throw new Error('organisation_id is required for file upload, or userId must be provided for user-scoped files');
-      }
-      if (!options.table_name) {
-        throw new Error('table_name is required for file upload');
-      }
-      if (!options.record_id) {
-        throw new Error('record_id is required for file upload');
-      }
-      if (!options.folder) {
-        throw new Error('folder is required for file upload. The folder prop determines the storage path.');
-      }
-
-      // For user-scoped files, we MUST use auth.uid() for the path to match RLS policies
-      // Get the authenticated user ID from the Supabase session
-      let authenticatedUserId: string | undefined = undefined;
+      let authenticatedUserId: string | undefined;
       if (isUserScoped) {
-        const { data: { user: authUser }, error: authError } = await this.supabase.auth.getUser();
-        if (authError || !authUser) {
-          throw new Error('User must be authenticated to upload user-scoped files');
-        }
-        authenticatedUserId = authUser.id;
-        log.debug('Using authenticated user ID for user-scoped file upload', { userId: authenticatedUserId });
+        const authResult = await this.resolveAuthenticatedUserIdForUserScoped();
+        if (!authResult.ok) return authResult;
+        authenticatedUserId = authResult.data;
       }
 
-      // CRITICAL: Check super admin status in application layer (consistent with pace-core pattern)
-      // Super admins bypass all permission checks - this is handled in the application layer,
-      // not in RLS policies. The RPC function still validates input and handles the insert,
-      // but permission checks are bypassed for super admins.
-      let isSuperAdminUser = false;
-      const userIdForCheck = authenticatedUserId || options.userId;
-      if (userIdForCheck) {
-        try {
-          // Import isSuperAdmin from rbac/api - this is the standard way to check super admin
-          const { isSuperAdmin } = await import('../../rbac/api');
-          isSuperAdminUser = await isSuperAdmin(userIdForCheck);
-          if (isSuperAdminUser) {
-            log.debug('Super admin detected - bypassing permission checks', { userId: userIdForCheck });
-          }
-        } catch (superAdminCheckError) {
-          // If super admin check fails, continue with normal permission flow
-          log.warn('Failed to check super-admin status, proceeding with normal permission checks', superAdminCheckError);
-        }
-      }
+      const isSuperAdminUser = await this.checkSuperAdminUser(authenticatedUserId || options.userId);
 
-      // Step 1: Upload file to storage bucket first
-      // This generates a unique path: {orgId}/{folder}/{timestamp-uuid-filename} or users/{auth.uid()}/{folder}/{timestamp-uuid-filename}
-      // Bucket is automatically selected based on is_public flag
-      const uploadResult = await uploadFile(this.supabase, file, {
-        appName: 'file-reference',
-        orgId: options.organisation_id || undefined,
-        userId: authenticatedUserId || (isUserScoped ? undefined : options.userId), // Use auth.uid() for user-scoped files
-        isPublic: options.is_public || false,
-        customPath: options.folder // Use folder prop as the custom path segment
-      });
-      if (!uploadResult.success) {
-        throw new Error(`Failed to upload file: ${uploadResult.error}`);
-      }
+      const uploadResult = await this.uploadFileAndExtractMetadata(options, file, authenticatedUserId, isUserScoped);
+      if (!uploadResult.ok) return uploadResult;
+      const { path: filePath, metadata } = uploadResult.data;
 
-      if (!uploadResult.path) {
-        throw new Error('File upload did not return a path');
-      }
+      await this.setOrgContextIfNeeded(isUserScoped, options.organisation_id ?? undefined);
 
-      const filePath = uploadResult.path;
+      const rpcUserId = await this.resolveRpcUserId(authenticatedUserId, options);
 
-      // Step 2: Extract file metadata (dimensions, hash, etc.)
-      const metadata = await extractFileMetadata(file, {
-        appName: 'file-reference',
-        orgId: options.organisation_id || undefined,
-        userId: authenticatedUserId || (isUserScoped ? undefined : options.userId), // Use auth.uid() for user-scoped files
-        isPublic: options.is_public || false
-      }, 'system');
-
-      // Step 3: Set organisation context in database session before creating file reference
-      // Skip for user-scoped files (no org context needed)
-      if (!isUserScoped && options.organisation_id) {
-        await setOrganisationContext(this.supabase, options.organisation_id);
-      }
+      const payload = this.buildCreateRpcPayload(options, filePath, file, metadata, rpcUserId);
+      const { data, error } = await this.supabase.rpc('data_file_reference_create', payload as Parameters<SupabaseClient['rpc']>[1] & object);
 
-      // Step 4: Create file reference in database using RPC function
-      // This links the storage path to the record in core_file_references table
-      // CRITICAL: Always pass the authenticated user ID to SECURITY DEFINER functions
-      // In SECURITY DEFINER functions, auth.uid() returns the function owner's ID,
-      // not the caller's ID, so we must explicitly pass the user ID
-      let rpcUserId: string | null = null;
-      if (authenticatedUserId) {
-        rpcUserId = authenticatedUserId;
-      } else if (options.userId) {
-        rpcUserId = options.userId;
-      } else {
-        // Get authenticated user ID from session as fallback
-        const { data: { user: authUser } } = await this.supabase.auth.getUser();
-        if (authUser) {
-          rpcUserId = authUser.id;
-        }
-      }
-
-      const { data, error } = await this.supabase
-        .rpc('data_file_reference_create', {
-          p_table_name: options.table_name,
-          p_record_id: options.record_id,
-          p_file_path: filePath, // Storage path from step 1
-          p_organisation_id: options.organisation_id ?? null,
-          p_app_id: options.app_id,
-          p_page_context: options.pageContext,
-          p_event_id: options.event_id || null, // Pass event_id for event-based apps
-          p_file_metadata: {
-            fileName: file.name,
-            fileType: file.type,
-            fileSize: file.size,
-            category: options.category,
-            ...metadata,
-            ...options.custom_metadata
-          },
-          p_is_public: options.is_public || false,
-          p_user_id: rpcUserId // Always pass authenticated user ID for SECURITY DEFINER functions
-        });
-
-      // Step 5: Rollback - if database insert fails, clean up uploaded file
       if (error) {
-        await deleteFile(this.supabase, filePath, options.is_public || false);
-        throw new Error(`Failed to create file reference: ${error.message}`);
+        return await this.rollbackUploadAndErr(filePath, options.is_public ?? false, 'CREATE_FAILED', error.message);
       }
-
-      // Check if RPC returned null (permission denied or other failure)
       if (!data || data === null) {
-        // Clean up the uploaded file since DB insert failed
-        await deleteFile(this.supabase, filePath, options.is_public || false);
-
-        // Provide more helpful error message
-        const appName = await this.getAppName(options.app_id).catch(() => 'unknown');
-        const pageContextDisplay = options.pageContext || 'undefined';
-        
-        if (isSuperAdminUser) {
-          // Super-admin should have been allowed - this suggests a database or RPC function issue
-          // Since we already checked super admin in the application layer, this is unexpected
-          throw new Error(
-            `File upload failed for super-admin user. This may indicate a database issue. ` +
-            `Page context: '${pageContextDisplay}', App: '${appName}'. ` +
-            `Please check that the page '${pageContextDisplay}' exists in rbac_app_pages table for app '${appName}'.`
-          );
-        } else {
-          throw new Error(
-            `File upload denied: insufficient permissions. You need 'create:page.${pageContextDisplay}' or 'update:page.${pageContextDisplay}' permission for the '${pageContextDisplay}' page. ` +
-            `Make sure the page exists in rbac_app_pages table for app '${appName}'.`
-          );
-        }
+        const message = await this.buildPermissionDeniedMessage(options, isSuperAdminUser);
+        return await this.rollbackUploadAndErr(filePath, options.is_public ?? false, 'PERMISSION_DENIED', message);
       }
 
-      // Get the created file reference
-      const { data: fileRef, error: fetchError } = await this.supabase
-        .from('core_file_references')
-        .select('id, table_name, record_id, file_path, file_metadata, organisation_id, app_id, is_public, created_at, updated_at')
-        .eq('id', data)
-        .single();
-
-      if (fetchError || !fileRef) {
-        // Clean up uploaded file if we can't fetch the reference
-        await deleteFile(this.supabase, filePath, options.is_public || false);
-        throw new Error(`Failed to fetch created file reference: ${fetchError?.message}`);
+      const fetchResult = await this.fetchCreatedFileReference(data as string);
+      if (!fetchResult.ok) {
+        return await this.rollbackUploadAndErr(
+          filePath,
+          options.is_public ?? false,
+          'FETCH_FAILED',
+          fetchResult.error.message
+        );
       }
 
-      // Invalidate cache for this file display entry so newly uploaded files appear immediately
-      // For user-scoped files, pass null for organisation_id
       invalidateFileDisplayCache(
         options.table_name,
         options.record_id,
@@ -233,53 +294,49 @@ export class FileReferenceServiceImpl implements FileReferenceService {
         options.category
       );
 
-      return fileRef as FileReference;
+      return ok(fetchResult.data);
     } catch (error) {
       log.error('Error creating file reference:', error);
-      throw error;
+      return err(toApiError(error));
     }
   }
 
-  async getFileReference(table_name: string, record_id: string, organisation_id?: string): Promise<FileReference | null> {
+  async getFileReference(table_name: string, record_id: string, organisation_id?: string): Promise<ApiResult<FileReference | null>> {
     try {
       let query = this.supabase
         .from('core_file_references')
         .select('id, table_name, record_id, file_path, file_metadata, organisation_id, app_id, is_public, created_at, updated_at')
         .eq('table_name', table_name)
         .eq('record_id', record_id);
-      
-      // Handle NULL organisation_id for user-owned files
       if (organisation_id === null || organisation_id === undefined) {
         query = query.is('organisation_id', null);
       } else {
         query = query.eq('organisation_id', organisation_id);
       }
-      
       const { data, error } = await query.single();
-
       if (error) {
         if (error.code === 'PGRST116') {
-          return null; // No rows found
+          return ok(null);
         }
-        throw new Error(`Failed to get file reference: ${error.message}`);
+        return err({ code: 'FETCH_FAILED', message: error.message });
       }
-
-      return data as FileReference;
+      return ok(data as FileReference);
     } catch (error) {
       log.error('Error getting file reference:', error);
-      throw error;
+      return err(toApiError(error));
     }
   }
 
-  async getFileUrl(table_name: string, record_id: string, organisation_id?: string): Promise<string | null> {
+  async getFileUrl(table_name: string, record_id: string, organisation_id?: string): Promise<ApiResult<string | null>> {
     try {
-      // Get file reference to check if it's public
-      const fileRef = await this.getFileReference(table_name, record_id, organisation_id);
+      const refResult = await this.getFileReference(table_name, record_id, organisation_id);
+      if (!refResult.ok) {
+        return refResult;
+      }
+      const fileRef = refResult.data;
       if (!fileRef) {
-        return null;
+        return ok(null);
       }
-
-      // For public files, RPC returns file path - generate public URL client-side
       if (fileRef.is_public) {
         const { data: pathData } = await this.supabase
           .rpc('data_file_reference_url_get', {
@@ -287,26 +344,20 @@ export class FileReferenceServiceImpl implements FileReferenceService {
             p_record_id: record_id,
             p_organisation_id: organisation_id
           });
-
         if (!pathData) {
-          return null;
+          return ok(null);
         }
-
-        // Generate public URL using bucket-aware helper
-        return getPublicUrl(this.supabase, pathData, true);
-      } else {
-        // For private files, use signed URL
-        return await this.getSignedUrl(table_name, record_id, organisation_id);
+        return ok(getPublicUrl(this.supabase, pathData, true));
       }
+      return this.getSignedUrl(table_name, record_id, organisation_id);
     } catch (error) {
       log.error('Error getting file URL:', error);
-      throw error;
+      return err(toApiError(error));
     }
   }
 
-  async getSignedUrl(table_name: string, record_id: string, organisation_id?: string, expires_in: number = 3600): Promise<string | null> {
+  async getSignedUrl(table_name: string, record_id: string, organisation_id?: string, expires_in: number = 3600): Promise<ApiResult<string | null>> {
     try {
-      // Get file path from RPC function
       const { data: filePath, error } = await this.supabase
         .rpc('data_file_reference_signed_url_get', {
           p_table_name: table_name,
@@ -314,31 +365,29 @@ export class FileReferenceServiceImpl implements FileReferenceService {
           p_organisation_id: organisation_id ?? null,
           p_expires_in: expires_in
         });
-
       if (error) {
-        throw new Error(`Failed to get signed URL: ${error.message}`);
+        return err({ code: 'SIGNED_URL_FAILED', message: error.message });
       }
-
       if (!filePath) {
-        return null;
+        return ok(null);
       }
-
-      // Generate signed URL client-side using bucket-aware helper (files bucket for private files)
       const signedUrlResult = await getSignedUrl(this.supabase, filePath, {
         appName: 'file-reference',
         orgId: organisation_id,
         userId: organisation_id ? undefined : record_id,
         expiresIn: expires_in
       });
-
-      return signedUrlResult?.url || null;
+      if (!signedUrlResult.ok) {
+        return err(signedUrlResult.error);
+      }
+      return ok(signedUrlResult.data.url ?? null);
     } catch (error) {
       log.error('Error getting signed URL:', error);
-      throw error;
+      return err(toApiError(error));
     }
   }
 
-  async updateFileReference(id: string, updates: Partial<FileReference>): Promise<FileReference> {
+  async updateFileReference(id: string, updates: Partial<FileReference>): Promise<ApiResult<FileReference>> {
     try {
       const { data, error } = await this.supabase
         .from('core_file_references')
@@ -346,23 +395,21 @@ export class FileReferenceServiceImpl implements FileReferenceService {
         .eq('id', id)
         .select()
         .single();
-
       if (error) {
-        throw new Error(`Failed to update file reference: ${error.message}`);
+        return err({ code: 'UPDATE_FAILED', message: error.message });
       }
-
-      return data as FileReference;
+      return ok(data as FileReference);
     } catch (error) {
       log.error('Error updating file reference:', error);
-      throw error;
+      return err(toApiError(error));
     }
   }
 
-  async deleteFileReference(table_name: string, record_id: string, organisation_id?: string, delete_file: boolean = false): Promise<boolean> {
+  async deleteFileReference(table_name: string, record_id: string, organisation_id?: string, delete_file: boolean = false): Promise<ApiResult<boolean>> {
     try {
-      // Get file reference first to determine bucket
-      const fileRef = await this.getFileReference(table_name, record_id, organisation_id);
-      
+      const refResult = await this.getFileReference(table_name, record_id, organisation_id);
+      const fileRef = refResult.ok ? refResult.data : null;
+
       const { error } = await this.supabase
         .rpc('data_file_reference_delete', {
           p_table_name: table_name,
@@ -370,24 +417,20 @@ export class FileReferenceServiceImpl implements FileReferenceService {
           p_organisation_id: organisation_id ?? null,
           p_delete_file: delete_file
         });
-
       if (error) {
-        throw new Error(`Failed to delete file reference: ${error.message}`);
+        return err({ code: 'DELETE_FAILED', message: error.message });
       }
-
-      // If delete_file is true and we have the file reference, delete from storage
       if (delete_file && fileRef) {
         await deleteFile(this.supabase, fileRef.file_path, fileRef.is_public || false);
       }
-
-      return true;
+      return ok(true);
     } catch (error) {
       log.error('Error deleting file reference:', error);
-      throw error;
+      return err(toApiError(error));
     }
   }
 
-  async listFileReferences(table_name: string, record_id: string, organisation_id?: string): Promise<FileReference[]> {
+  async listFileReferences(table_name: string, record_id: string, organisation_id?: string): Promise<ApiResult<FileReference[]>> {
     try {
       const { data, error } = await this.supabase
         .rpc('data_file_reference_list', {
@@ -395,20 +438,12 @@ export class FileReferenceServiceImpl implements FileReferenceService {
           p_record_id: record_id,
           p_organisation_id: organisation_id ?? null
         });
-
       if (error) {
-        throw new Error(`Failed to list file references: ${error.message}`);
+        return err({ code: 'LIST_FAILED', message: error.message });
       }
-
-      // RPC returns: id, file_path, file_metadata, is_public, created_at
-      // We can construct FileReference objects directly from RPC response + function parameters
-      // This avoids a second query and reduces network requests
       if (!data || data.length === 0) {
-        return [];
+        return ok([]);
       }
-
-      // Construct FileReference objects from RPC response
-      // This avoids RLS issues with direct queries - the RPC already validated permissions
       interface RpcFileItem {
         id: string;
         file_path: string;
@@ -419,38 +454,29 @@ export class FileReferenceServiceImpl implements FileReferenceService {
       const fileReferences: FileReference[] = data
         .filter((item: RpcFileItem) => item.id && item.file_path && item.file_metadata)
         .map((item: RpcFileItem) => {
-          // Extract file name and type from file_path
           const fileName = item.file_path.split('/').pop() || 'unknown';
           const fileType = fileName.split('.').pop() || 'unknown';
-          
-          // Construct complete FileReference from RPC response + function parameters
-          const fileRef: FileReference = {
+          return {
             id: item.id,
             table_name: table_name,
             record_id: record_id,
             file_path: item.file_path,
-            file_metadata: {
-              fileName,
-              fileType,
-              ...(item.file_metadata || {}),
-            } as FileMetadata,
+            file_metadata: { fileName, fileType, ...(item.file_metadata || {}) } as FileMetadata,
             organisation_id: organisation_id ?? null,
-            app_id: item.file_metadata?.app_id ? assertAppId(item.file_metadata.app_id) : assertAppId(''), // May not be in metadata, use empty string
+            app_id: item.file_metadata?.app_id ? assertAppId(item.file_metadata.app_id) : assertAppId(''),
             is_public: item.is_public ?? false,
             created_at: item.created_at || new Date().toISOString(),
-            updated_at: item.created_at || new Date().toISOString() // RPC doesn't return updated_at, use created_at
-          };
-          return fileRef;
+            updated_at: item.created_at || new Date().toISOString()
+          } as FileReference;
         });
-
-      return fileReferences;
+      return ok(fileReferences);
     } catch (error) {
       log.error('Error listing file references:', error);
-      throw error;
+      return err(toApiError(error));
     }
   }
 
-  async getFileCount(table_name: string, record_id: string, organisation_id?: string): Promise<number> {
+  async getFileCount(table_name: string, record_id: string, organisation_id?: string): Promise<ApiResult<number>> {
     try {
       const { data, error } = await this.supabase
         .rpc('data_file_reference_count_get', {
@@ -458,51 +484,43 @@ export class FileReferenceServiceImpl implements FileReferenceService {
           p_record_id: record_id,
           p_organisation_id: organisation_id ?? null
         });
-
       if (error) {
-        throw new Error(`Failed to get file count: ${error.message}`);
+        return err({ code: 'COUNT_FAILED', message: error.message });
       }
-
-      return data || 0;
+      return ok(data ?? 0);
     } catch (error) {
       log.error('Error getting file count:', error);
-      throw error;
+      return err(toApiError(error));
     }
   }
 
-  async getFileReferenceById(id: string, organisation_id?: string): Promise<FileReference | null> {
+  async getFileReferenceById(id: string, organisation_id?: string): Promise<ApiResult<FileReference | null>> {
     try {
       const { data, error } = await this.supabase
         .rpc('data_file_reference_get', {
           p_file_reference_id: id,
           p_organisation_id: organisation_id ?? null
         });
-
       if (error) {
-        throw new Error(`Failed to get file reference by ID: ${error.message}`);
+        return err({ code: 'FETCH_FAILED', message: error.message });
       }
-
       if (!data || data.length === 0) {
-        return null;
+        return ok(null);
       }
-
-      return data[0] as FileReference;
+      return ok(data[0] as FileReference);
     } catch (error) {
       log.error('Error getting file reference by ID:', error);
-      throw error;
+      return err(toApiError(error));
     }
   }
 
   async getFilesByCategory(
-    table_name: string, 
-    record_id: string, 
-    category: FileCategory, 
+    table_name: string,
+    record_id: string,
+    category: FileCategory,
     organisation_id?: string
-  ): Promise<FileReference[]> {
+  ): Promise<ApiResult<FileReference[]>> {
     try {
-      // CRITICAL: Use RPC function to get files by category - this correctly filters on file_metadata->>'category'
-      // NOTE: We MUST use RPC function. Direct queries with .eq('category', ...) will FAIL with HTTP 406
-      // because there is NO 'category' column. The category is stored in the JSONB file_metadata field.
       const { data, error } = await this.supabase
         .rpc('data_file_reference_by_category_list', {
           p_table_name: table_name,
@@ -510,32 +528,13 @@ export class FileReferenceServiceImpl implements FileReferenceService {
           p_category: category,
           p_organisation_id: organisation_id ?? null
         });
-
       if (error) {
-        // Provide clear error message about category filtering
-        log.error('RPC ERROR getting files by category:', {
-          error,
-          errorCode: error.code,
-          errorMessage: error.message,
-          errorDetails: error.details,
-          table_name,
-          record_id,
-          category,
-          organisation_id,
-          message: 'CRITICAL: Category filtering MUST use RPC function data_file_reference_by_category_list. Direct queries with .eq(\'category\', ...) will FAIL with HTTP 406 because category is stored in file_metadata JSONB field, not a direct column.'
-        });
-        throw new Error(`Failed to get files by category: ${error.message}. Category filtering uses file_metadata JSONB field, not a direct column. RPC function required.`);
+        log.error('RPC ERROR getting files by category:', { error, table_name, record_id, category });
+        return err({ code: 'LIST_FAILED', message: error.message });
       }
-
-      // RPC returns partial data with: id, file_path, file_metadata, is_public, created_at
-      // We have table_name, record_id, organisation_id from function parameters
-      // We can construct FileReference objects directly without another query (avoiding RLS issues)
       if (!data || data.length === 0) {
-        return [];
+        return ok([]);
       }
-
-      // Construct FileReference objects from RPC response
-      // This avoids RLS issues with direct queries - the RPC already validated permissions
       interface RpcFileItem {
         id: string;
         file_path: string;
@@ -545,64 +544,45 @@ export class FileReferenceServiceImpl implements FileReferenceService {
       }
       const fileReferences: FileReference[] = data
         .filter((item: RpcFileItem) => {
-          // Verify category matches (defensive check)
           const fileCategory = item.file_metadata?.category;
-          const matches = fileCategory === category;
-          if (!matches) {
-            log.warn('File category mismatch in RPC response:', {
-              fileId: item.id,
-              expectedCategory: category,
-              actualCategory: fileCategory
-            });
-          }
-          return matches && item.id && item.file_path && item.file_metadata;
+          return fileCategory === category && item.id && item.file_path && item.file_metadata;
         })
-        .map((item: RpcFileItem) => {
-          // Extract file name and type from file_path
-          const fileName = item.file_path.split('/').pop() || 'unknown';
-          const fileType = fileName.split('.').pop() || 'unknown';
-          
-          // Construct complete FileReference from RPC response + function parameters
-          const fileRef: FileReference = {
-            id: item.id,
-            table_name: table_name,
-            record_id: record_id,
-            file_path: item.file_path,
-            file_metadata: {
-              fileName,
-              fileType,
-              category: (item.file_metadata?.category as FileCategory) || FileCategory.GENERAL_DOCUMENTS,
-              ...(item.file_metadata || {}),
-            } as FileMetadata,
-            organisation_id: organisation_id ?? null,
-            app_id: item.file_metadata?.app_id ? assertAppId(item.file_metadata.app_id) : assertAppId(''), // May not be in metadata, use empty string
-            is_public: item.is_public ?? false,
-            created_at: item.created_at || new Date().toISOString(),
-            updated_at: item.created_at || new Date().toISOString() // RPC doesn't return updated_at, use created_at
-          };
-          return fileRef;
-        });
-
-      return fileReferences;
+        .map((item: RpcFileItem) => ({
+          id: item.id,
+          table_name: table_name,
+          record_id: record_id,
+          file_path: item.file_path,
+          file_metadata: {
+            fileName: item.file_path.split('/').pop() || 'unknown',
+            fileType: (item.file_path.split('.').pop() || 'unknown'),
+            category: (item.file_metadata?.category as FileCategory) || FileCategory.GENERAL_DOCUMENTS,
+            ...(item.file_metadata || {}),
+          } as FileMetadata,
+          organisation_id: organisation_id ?? null,
+          app_id: item.file_metadata?.app_id ? assertAppId(item.file_metadata.app_id) : assertAppId(''),
+          is_public: item.is_public ?? false,
+          created_at: item.created_at || new Date().toISOString(),
+          updated_at: item.created_at || new Date().toISOString(),
+        } as FileReference));
+      return ok(fileReferences);
     } catch (error) {
       log.error('Error getting files by category:', error);
-      throw error;
+      return err(toApiError(error));
     }
   }
 
   async uploadMultipleFiles(
     options: FileUploadOptions,
     files: File[]
-  ): Promise<import('../../types/file-reference').BulkUploadResult> {
+  ): Promise<ApiResult<BulkUploadResult>> {
     const success: FileReference[] = [];
     const failed: { file: File; error: string }[] = [];
     const results: Array<{ file: File; result: FileUploadResult | null; error?: string }> = [];
 
-    // Upload files sequentially to avoid overwhelming the server
     for (const file of files) {
-      try {
-        const fileReference = await this.createFileReference(options, file);
-
+      const result = await this.createFileReference(options, file);
+      if (result.ok) {
+        const fileReference = result.data;
         success.push(fileReference);
         results.push({
           file,
@@ -613,20 +593,19 @@ export class FileReferenceServiceImpl implements FileReferenceService {
               : '',
           },
         });
-      } catch (error) {
-        const message = error instanceof Error ? error.message : 'Unknown error';
-        failed.push({ file, error: message });
-        results.push({ file, result: null, error: message });
+      } else {
+        failed.push({ file, error: result.error.message });
+        results.push({ file, result: null, error: result.error.message });
       }
     }
 
-    return {
+    return ok({
       success,
       failed,
       total: results.length,
       successful: success.length,
       results,
-    };
+    });
   }
 }
 
@@ -640,25 +619,28 @@ export async function uploadFileWithReference(
   supabase: SupabaseClient,
   options: FileUploadOptions,
   file: File
-): Promise<FileUploadResult> {
-  
+): Promise<ApiResult<FileUploadResult>> {
   const service = createFileReferenceService(supabase);
-  const fileReference = await service.createFileReference(options, file);
-  
-    const fileUrl = options.is_public 
-    ? getPublicUrl(supabase, fileReference.file_path, true)
-    : await getSignedUrl(supabase, fileReference.file_path, { 
-        appName: 'file-reference',
-        orgId: options.organisation_id || undefined,
-        userId: options.userId || undefined,
-        expiresIn: 3600 
-      });
-
-  const urlString = typeof fileUrl === 'string' ? fileUrl : fileUrl?.url || '';
-
-  return {
+  const result = await service.createFileReference(options, file);
+  if (!result.ok) {
+    return result;
+  }
+  const fileReference = result.data;
+  let urlString: string;
+  if (options.is_public) {
+    urlString = getPublicUrl(supabase, fileReference.file_path, true);
+  } else {
+    const signedResult = await getSignedUrl(supabase, fileReference.file_path, {
+      appName: 'file-reference',
+      orgId: options.organisation_id || undefined,
+      userId: options.userId || undefined,
+      expiresIn: 3600
+    });
+    urlString = signedResult.ok ? signedResult.data.url ?? '' : '';
+  }
+  return ok({
     file_reference: fileReference,
     file_url: urlString,
     signed_url: options.is_public ? undefined : urlString || undefined
-  };
+  });
 }