@jmruthers/pace-core 0.5.135 → 0.5.137

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

@@ -0,0 +1,501 @@
+// File Reference Service
+// Provides CRUD operations for the centralized file reference system
+
+import { SupabaseClient } from '@supabase/supabase-js';
+import { 
+  FileReference, 
+  FileUploadOptions, 
+  FileReferenceService, 
+  FileUploadResult,
+  FileCategory 
+} from '../../types/file-reference';
+import { uploadFile, getPublicUrl, getSignedUrl, deleteFile, extractFileMetadata } from '../storage/helpers';
+import { setOrganisationContext } from '../context/organisationContext';
+import { invalidateFileDisplayCache } from '../../hooks/useFileDisplay';
+import { createLogger } from '../core/logger';
+
+const log = createLogger('FileReferenceService');
+
+export class FileReferenceServiceImpl implements FileReferenceService {
+  constructor(private supabase: SupabaseClient) {}
+
+  /**
+   * Creates a file reference by uploading a file to storage and linking it in the database.
+   * 
+   * Storage Flow:
+   * 1. Upload file to storage bucket first (files or public-files based on is_public flag)
+   *    - Path format: {orgId}/{category}/{timestamp-uuid-filename}
+   *    - Bucket selection: 'files' (private) or 'public-files' (public)
+   * 2. Extract file metadata (dimensions, hash, etc.)
+   * 3. Set organisation context for RLS policies
+   * 4. Create database reference via RPC function
+   * 5. If DB insert fails, rollback by deleting uploaded file
+   * 
+   * This ensures atomicity: either both storage and DB succeed, or both are cleaned up.
+   */
+  async createFileReference(options: FileUploadOptions, file: File): Promise<FileReference> {
+    try {
+
+      // Validate required options
+      if (!options.organisation_id) {
+        throw new Error('organisation_id is required for file upload');
+      }
+      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');
+      }
+
+      // Step 1: Upload file to storage bucket first
+      // This generates a unique path: {orgId}/{category}/{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,
+        isPublic: options.is_public || false,
+        customPath: options.category // Use category as the custom path segment
+      });
+      if (!uploadResult.success) {
+        throw new Error(`Failed to upload file: ${uploadResult.error}`);
+      }
+
+      if (!uploadResult.path) {
+        throw new Error('File upload did not return a path');
+      }
+
+      const filePath = uploadResult.path;
+
+      // Step 2: Extract file metadata (dimensions, hash, etc.)
+      const metadata = await extractFileMetadata(file, {
+        appName: 'file-reference',
+        orgId: options.organisation_id,
+        isPublic: options.is_public || false
+      }, 'system');
+
+      // Step 3: Set organisation context in database session before creating file reference
+      // This ensures RLS policies can check the organisation context
+      await setOrganisationContext(this.supabase, options.organisation_id);
+
+      // Step 4: Create file reference in database using RPC function
+      // This links the storage path to the record in file_references table
+      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,
+          p_app_id: options.app_id,
+          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
+        });
+
+      // 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}`);
+      }
+
+      // Get the created file reference
+      const { data: fileRef, error: fetchError } = await this.supabase
+        .from('file_references')
+        .select('*')
+        .eq('id', data)
+        .single();
+
+      if (fetchError || !fileRef) {
+        throw new Error(`Failed to fetch created file reference: ${fetchError?.message}`);
+      }
+
+      // Invalidate cache for this file display entry so newly uploaded files appear immediately
+      invalidateFileDisplayCache(
+        options.table_name,
+        options.record_id,
+        options.organisation_id,
+        options.category
+      );
+
+      return fileRef as FileReference;
+    } catch (error) {
+      log.error('Error creating file reference:', error);
+      throw error;
+    }
+  }
+
+  async getFileReference(table_name: string, record_id: string, organisation_id: string): Promise<FileReference | null> {
+    try {
+      const { data, error } = await this.supabase
+        .from('file_references')
+        .select('*')
+        .eq('table_name', table_name)
+        .eq('record_id', record_id)
+        .eq('organisation_id', organisation_id)
+        .single();
+
+      if (error) {
+        if (error.code === 'PGRST116') {
+          return null; // No rows found
+        }
+        throw new Error(`Failed to get file reference: ${error.message}`);
+      }
+
+      return data as FileReference;
+    } catch (error) {
+      log.error('Error getting file reference:', error);
+      throw error;
+    }
+  }
+
+  async getFileUrl(table_name: string, record_id: string, organisation_id: string): Promise<string | null> {
+    try {
+      // Get file reference to check if it's public
+      const fileRef = await this.getFileReference(table_name, record_id, organisation_id);
+      if (!fileRef) {
+        return 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', {
+            p_table_name: table_name,
+            p_record_id: record_id,
+            p_organisation_id: organisation_id
+          });
+
+        if (!pathData) {
+          return 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);
+      }
+    } catch (error) {
+      log.error('Error getting file URL:', error);
+      throw error;
+    }
+  }
+
+  async getSignedUrl(table_name: string, record_id: string, organisation_id: string, expires_in: number = 3600): Promise<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,
+          p_record_id: record_id,
+          p_organisation_id: organisation_id,
+          p_expires_in: expires_in
+        });
+
+      if (error) {
+        throw new Error(`Failed to get signed URL: ${error.message}`);
+      }
+
+      if (!filePath) {
+        return 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,
+        expiresIn: expires_in
+      });
+
+      return signedUrlResult?.url || null;
+    } catch (error) {
+      log.error('Error getting signed URL:', error);
+      throw error;
+    }
+  }
+
+  async updateFileReference(id: string, updates: Partial<FileReference>): Promise<FileReference> {
+    try {
+      const { data, error } = await this.supabase
+        .from('file_references')
+        .update(updates)
+        .eq('id', id)
+        .select()
+        .single();
+
+      if (error) {
+        throw new Error(`Failed to update file reference: ${error.message}`);
+      }
+
+      return data as FileReference;
+    } catch (error) {
+      log.error('Error updating file reference:', error);
+      throw error;
+    }
+  }
+
+  async deleteFileReference(table_name: string, record_id: string, organisation_id: string, delete_file: boolean = false): Promise<boolean> {
+    try {
+      // Get file reference first to determine bucket
+      const fileRef = await this.getFileReference(table_name, record_id, organisation_id);
+      
+      const { error } = await this.supabase
+        .rpc('data_file_reference_delete', {
+          p_table_name: table_name,
+          p_record_id: record_id,
+          p_organisation_id: organisation_id,
+          p_delete_file: delete_file
+        });
+
+      if (error) {
+        throw new Error(`Failed to delete file reference: ${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;
+    } catch (error) {
+      log.error('Error deleting file reference:', error);
+      throw error;
+    }
+  }
+
+  async listFileReferences(table_name: string, record_id: string, organisation_id: string): Promise<FileReference[]> {
+    try {
+      const { data, error } = await this.supabase
+        .rpc('data_file_reference_list', {
+          p_table_name: table_name,
+          p_record_id: record_id,
+          p_organisation_id: organisation_id
+        });
+
+      if (error) {
+        throw new Error(`Failed to list file references: ${error.message}`);
+      }
+
+      // RPC returns partial data, need to fetch full file references
+      if (!data || data.length === 0) {
+        return [];
+      }
+
+      // Fetch full file reference data for each ID
+      const ids = data.map((item: any) => item.id);
+      const { data: fullData, error: fetchError } = await this.supabase
+        .from('file_references')
+        .select('*')
+        .in('id', ids);
+
+      if (fetchError) {
+        throw new Error(`Failed to fetch file references: ${fetchError.message}`);
+      }
+
+      return (fullData || []) as FileReference[];
+    } catch (error) {
+      log.error('Error listing file references:', error);
+      throw error;
+    }
+  }
+
+  async getFileCount(table_name: string, record_id: string, organisation_id: string): Promise<number> {
+    try {
+      const { data, error } = await this.supabase
+        .rpc('data_file_reference_count_get', {
+          p_table_name: table_name,
+          p_record_id: record_id,
+          p_organisation_id: organisation_id
+        });
+
+      if (error) {
+        throw new Error(`Failed to get file count: ${error.message}`);
+      }
+
+      return data || 0;
+    } catch (error) {
+      log.error('Error getting file count:', error);
+      throw error;
+    }
+  }
+
+  async getFileReferenceById(id: string, organisation_id: string): Promise<FileReference | null> {
+    try {
+      const { data, error } = await this.supabase
+        .rpc('data_file_reference_get', {
+          p_file_reference_id: id,
+          p_organisation_id: organisation_id
+        });
+
+      if (error) {
+        throw new Error(`Failed to get file reference by ID: ${error.message}`);
+      }
+
+      if (!data || data.length === 0) {
+        return null;
+      }
+
+      return data[0] as FileReference;
+    } catch (error) {
+      log.error('Error getting file reference by ID:', error);
+      throw error;
+    }
+  }
+
+  async getFilesByCategory(
+    table_name: string, 
+    record_id: string, 
+    category: FileCategory, 
+    organisation_id: string
+  ): Promise<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,
+          p_record_id: record_id,
+          p_category: category,
+          p_organisation_id: organisation_id
+        });
+
+      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.`);
+      }
+
+      // 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 [];
+      }
+
+      // Construct FileReference objects from RPC response
+      // This avoids RLS issues with direct queries - the RPC already validated permissions
+      const fileReferences: FileReference[] = data
+        .filter((item: any) => {
+          // 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;
+        })
+        .map((item: any) => {
+          // 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: item.file_metadata || {},
+            organisation_id: organisation_id,
+            app_id: item.file_metadata?.app_id || '', // 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;
+    } catch (error) {
+      log.error('Error getting files by category:', error);
+      throw error;
+    }
+  }
+
+  async uploadMultipleFiles(
+    options: FileUploadOptions,
+    files: File[]
+  ): Promise<import('../../types/file-reference').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);
+
+        success.push(fileReference);
+        results.push({
+          file,
+          result: {
+            file_reference: fileReference,
+            file_url: fileReference.is_public
+              ? getPublicUrl(this.supabase, fileReference.file_path, true)
+              : '',
+          },
+        });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown error';
+        failed.push({ file, error: message });
+        results.push({ file, result: null, error: message });
+      }
+    }
+
+    return {
+      success,
+      failed,
+      total: results.length,
+      successful: success.length,
+      results,
+    };
+  }
+}
+
+// Factory function to create file reference service
+export function createFileReferenceService(supabase: SupabaseClient): FileReferenceService {
+  return new FileReferenceServiceImpl(supabase);
+}
+
+// Helper function to upload file and create reference in one operation
+export async function uploadFileWithReference(
+  supabase: SupabaseClient,
+  options: FileUploadOptions,
+  file: File
+): Promise<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,
+        expiresIn: 3600 
+      });
+
+  const urlString = typeof fileUrl === 'string' ? fileUrl : fileUrl?.url || '';
+
+  return {
+    file_reference: fileReference,
+    file_url: urlString,
+    signed_url: options.is_public ? undefined : urlString || undefined
+  };
+}