@jmruthers/pace-core 0.5.87 → 0.5.88

package/src/utils/storage/README.md

@@ -1,348 +1,355 @@
-# Storage System
+# File Reference System
 
-A simple, secure file storage system with organization-scoped access control.
+A comprehensive file storage and management system with database tracking, organisation-scoped access control, and bucket management.
 
 ## Quick Start
 
 ```typescript
-import { useStorage, FileUpload } from '@jmruthers/pace-core';
+import { FileUpload, useFileReference, FileCategory } from '@jmruthers/pace-core';
 
-// Basic usage
-const { uploadFile, files, isUploading } = useStorage({
-  supabase,
-  appName: 'TRAC',
-  orgId: 'your-org-id'
-});
+// Basic usage with new file reference system
+const { uploadFile } = useFileReference(supabase);
 
-// File upload component
+// File upload component with progress tracking
 <FileUpload
   supabase={supabase}
-  appName="TRAC"
-  orgId="your-org-id"
-  onUploadComplete={(result) => console.log(result)}
+  table_name="person"
+  record_id="person-123"
+  organisation_id="org-123"
+  app_id="app-123" // Optional - auto-resolved if not provided
+  category={FileCategory.PROFILE_PHOTOS}
+  isPublic={false}
+  showProgress={true}
+  showPreview={true}
+  onUploadSuccess={(result) => console.log('Uploaded:', result)}
+  onUploadError={(error, file) => console.error('Failed:', error)}
 />
 ```
 
-## API Reference
+## Key Features
 
-### Hooks
+- **Database Tracking**: All files are tracked in the `file_references` table
+- **Bucket Management**: Automatic selection between `files` (private) and `public-files` (public) buckets
+- **Organisation Scoped**: Files are automatically scoped to organisations
+- **Progress Tracking**: Real-time upload progress with visual feedback
+- **File Previews**: Automatic image previews for uploaded files
+- **Validation**: Client-side file size and type validation
+- **URL Management**: Automatic generation of public and signed URLs
+- **RPC Integration**: Secure database operations via RPC functions
+- **App ID Resolution**: Automatic app ID resolution from app name configuration
+- **Memory Management**: Automatic cleanup to prevent memory leaks
+- **Error Handling**: Comprehensive error handling with user-friendly messages
 
-#### `useStorage(options)`
+## Components
 
-Main hook for storage operations.
+### FileUpload
 
-**Parameters:**
-- `supabase: SupabaseClient` - Supabase client instance
-- `appName: string` - Application name (TRAC, CAKE, PACE, etc.)
-- `orgId: string` - Organization ID
-- `debug?: boolean` - Enable debug logging (optional)
+Enhanced file upload component with progress tracking, previews, and validation.
 
-**Returns:**
 ```typescript
-{
-  // Upload
-  uploadFile: (file: File, options?: StorageUploadOptions) => Promise<StorageUploadResult>;
-  isUploading: boolean;
-  uploadError: string | null;
-  
-  // URLs
-  getPublicUrl: (path: string) => string;
-  getSignedUrl: (path: string, expiresIn?: number) => Promise<string | null>;
-  
-  // File management
-  deleteFile: (path: string) => Promise<{ success: boolean; error?: string }>;
-  archiveFile: (path: string) => Promise<{ success: boolean; error?: string }>;
-  listFiles: (options?: StorageListOptions) => Promise<StorageListResult>;
-  
-  // State
-  files: StorageFileInfo[];
-  refreshFiles: () => Promise<void>;
-  isLoading: boolean;
-  error: string | null;
-}
+<FileUpload
+  supabase={supabase}
+  table_name="person"           // Table name for the record
+  record_id="person-123"        // ID of the record
+  organisation_id="org-123"     // Organisation ID
+  app_id="app-123"              // Application ID (optional - auto-resolved)
+  category={FileCategory.PROFILE_PHOTOS}  // File category
+  isPublic={false}              // Use public bucket?
+  showProgress={true}           // Show progress bar
+  showPreview={true}            // Show image previews
+  accept="image/*"              // Accepted file types
+  maxSize={10 * 1024 * 1024}    // Max file size (10MB)
+  multiple={true}               // Allow multiple files
+  disabled={false}              // Disable upload
+  className="custom-class"      // Custom CSS classes
+  onUploadSuccess={(result) => {}}  // Success callback
+  onUploadError={(error, file) => {}}  // Error callback
+  onProgress={(progress) => {}}     // Progress callback
+>
+  {/* Optional custom upload UI */}
+  <div>Custom upload area</div>
+</FileUpload>
 ```
 
-#### `useFileUpload(options)`
+### FileDisplay
 
-Simplified hook for uploads with progress tracking.
+Display file references with automatic URL generation.
 
 ```typescript
-const { uploadWithProgress, uploadProgress, isUploading, uploadError } = useFileUpload({
-  supabase,
-  appName: 'TRAC',
-  orgId: 'your-org-id'
-});
+<FileDisplay
+  supabase={supabase}
+  table_name="person"
+  record_id="person-123"
+  organisation_id="org-123"
+  category={FileCategory.PROFILE_PHOTOS}
+  showDelete={true}
+/>
 ```
 
-### Components
+## Hooks
 
-#### `FileUpload`
+### useFileReference
 
-React component for file uploads with drag-and-drop.
+Main hook for file reference operations.
 
 ```typescript
-<FileUpload
-  supabase={supabase}
-  appName="TRAC"
-  orgId="your-org-id"
-  accept="image/*,.pdf"
-  maxSize={10 * 1024 * 1024} // 10MB
-  multiple={true}
-  onUploadComplete={(result) => {
-    if (result.success) {
-      console.log('File uploaded:', result.path);
-    }
-  }}
-/>
+const { 
+  uploadFile, 
+  getFileReference,
+  getFileReferenceById,
+  getFilesByCategory,
+  deleteFileReference,
+  isLoading,
+  error
+} = useFileReference(supabase);
+
+// Upload a file
+const result = await uploadFile({
+  table_name: 'person',
+  record_id: 'person-123',
+  organisation_id: 'org-123',
+  app_id: 'app-123',
+  category: FileCategory.PROFILE_PHOTOS,
+  is_public: false
+}, file);
+
+// Get files by category
+const files = await getFilesByCategory(
+  'person', 
+  'person-123', 
+  FileCategory.PROFILE_PHOTOS, 
+  'org-123'
+);
 ```
 
-### Utility Functions
+### useFileReferenceById
 
-```typescript
-import { uploadFile, getPublicUrl, getSignedUrl, deleteFile, archiveFile } from '@jmruthers/pace-core';
+Fetch a single file reference by ID.
 
-// Upload file
-const result = await uploadFile(supabase, file, {
-  appName: 'TRAC',
-  orgId: 'your-org-id',
-  metadata: { uploadedBy: userId }
-});
+```typescript
+const { fileReference, fileUrl, isLoading, error } = useFileReferenceById(
+  supabase, 
+  fileRefId, 
+  organisationId
+);
+```
 
-// Get URLs (using hooks)
-const { getPublicUrl, getSignedUrl } = useStorage({
-  supabase,
-  appName: 'TRAC',
-  orgId: 'your-org-id'
-});
+### useFilesByCategory
 
-const publicUrl = getPublicUrl('org-id/category/filename.pdf');
-const signedUrl = await getSignedUrl('org-id/category/private.pdf', 3600);
+Fetch multiple file references by category.
 
-// File management
-const deleteResult = await deleteFile(supabase, 'org-id/category/filename.pdf');
-const archiveResult = await archiveFile(supabase, 'org-id/category/filename.pdf', {
-  appName: 'TRAC',
-  orgId: 'your-org-id'
-});
+```typescript
+const { fileReferences, fileUrls, isLoading, error } = useFilesByCategory(
+  supabase,
+  table_name,
+  record_id,
+  category,
+  organisation_id
+);
 ```
 
-## File Structure
+### useEventLogo
 
-Files are organized by organization and category in the `files` bucket:
+Fetch event logos for both public and authenticated contexts with automatic fallback.
 
+```typescript
+const { logoUrl, fallbackText, isLoading, error, refetch } = useEventLogo(
+  supabase,
+  eventId,
+  eventName,
+  organisationId,
+  {
+    validateImage: true,
+    enableCache: true,
+    cacheTtl: 30 * 60 * 1000 // 30 minutes
+  }
+);
+
+// Display logo with fallback
+{logoUrl ? (
+  <img src={logoUrl} alt={`${eventName} logo`} />
+) : (
+  <div className="logo-fallback">{fallbackText}</div>
+)}
 ```
-files/
-├── {org_id}/
-│   ├── trac_accommodation/     # TRAC accommodation files
-│   ├── trac_activity/          # TRAC activity files
-│   ├── trac_transport/         # TRAC transport files
-│   ├── trac_journal/           # TRAC journal images
-│   ├── event_logos/            # PACE event logos (public)
-│   └── documents/              # Generic documents
+
+## File Categories
+
+```typescript
+enum FileCategory {
+  PROFILE_PHOTOS = 'profile_photos',
+  EVENT_LOGOS = 'event_logos',
+  DOCUMENTS = 'documents',
+  CAKE_DISH = 'cake_dish',
+  TRAC_ACCOMMODATION = 'trac_accommodation',
+  TRAC_ACTIVITY = 'trac_activity',
+  TRAC_JOURNAL = 'trac_journal',
+  TRAC_TRANSPORT = 'trac_transport'
+}
 ```
 
-**Note:** The actual file paths in storage are `{org_id}/category/filename` (without the `files/` prefix).
+## Storage Structure
 
-### Current File Distribution
+Files are stored in Supabase storage with the following structure:
 
-Based on the implemented system, files are distributed as follows:
-- **documents**: 73 files (generic documents)
-- **event_logos**: 27 files (PACE event logos, public)
-- **trac_journal**: 24 files (TRAC journal images)
-- **trac_transport**: 16 files (TRAC transport files)
-- **trac_activity**: 11 files (TRAC activity files)
-- **trac_accommodation**: 7 files (TRAC accommodation files)
+```
+files/ (private bucket)
+├── {orgId}/
+│   ├── profile_photos/
+│   │   └── filename.jpg
+│   ├── event_logos/
+│   │   └── logo.png
+│   └── documents/
+│       └── document.pdf
+
+public-files/ (public bucket)
+├── {orgId}/
+│   ├── profile_photos/
+│   │   └── filename.jpg
+│   └── event_logos/
+│       └── logo.png
+```
 
-## Security
+## URL Generation
+
+### Public Files
+```typescript
+import { getPublicUrl } from '@jmruthers/pace-core';
 
-- **Organization Segregation**: Users can only access files from their organization
-- **RLS Policies**: Database-level security enforcement with `org_scoped_file_access` policy
-- **Path-based Access Control**: Organization ID in path enables easy access control
-- **App Access Control**: Users must have access to the specific application
-- **File References Table**: Centralized metadata tracking in `file_references` table
+const url = getPublicUrl(supabase, filePath, true);
+```
 
-### RLS Policy Details
+### Private Files (Signed URLs)
+```typescript
+import { getSignedUrl } from '@jmruthers/pace-core';
 
-The system uses the following RLS policies on `storage.objects`:
-- `org_scoped_file_access`: Read access for users with organization membership
-- `app_org_scoped_file_upload`: Upload access with path validation
-- `app_org_scoped_file_update`: Update access for owned files
-- `app_org_scoped_file_delete`: Delete access for owned files
+const { url } = await getSignedUrl(supabase, filePath, {
+  appName: 'my-app',
+  orgId: 'org-123',
+  expiresIn: 3600
+});
+```
 
-### Database Structure
+## Database Schema
 
-The system uses a centralized `file_references` table for metadata:
+The system uses the `file_references` table:
 
 ```sql
 CREATE TABLE file_references (
   id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-  app_name TEXT NOT NULL,
   table_name TEXT NOT NULL,
-  record_id UUID NOT NULL,
+  record_id TEXT NOT NULL,
   file_path TEXT NOT NULL,
-  file_metadata JSONB,
   organisation_id UUID NOT NULL,
-  is_public BOOLEAN DEFAULT false,
+  app_id UUID,
+  file_metadata JSONB,
+  is_public BOOLEAN DEFAULT FALSE,
   created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
   updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
 );
 ```
 
-This replaces individual file reference columns in various tables, providing centralized file management.
-
-## File Size Limits
-
-| Type | Limit |
-|------|-------|
-| Images (JPEG, PNG, WebP) | 5MB |
-| GIF | 10MB |
-| SVG | 1MB |
-| PDF | 50MB |
-| Office Documents | 25MB |
-| Archives (ZIP, RAR) | 100MB |
-| Default | 10MB |
+## RPC Functions
 
-## Best Practices
+The system uses several RPC functions for secure database operations:
 
-### 1. Use Descriptive Paths
-```typescript
-// Good: Descriptive, organized paths
-const path = `org-id/documents/2024/reports/quarterly-report.pdf`;
+- `data_file_reference_create` - Create a new file reference
+- `data_file_reference_get` - Get a file reference by ID
+- `data_file_reference_list` - List file references for a record
+- `data_file_reference_by_category_list` - List files by category
+- `data_file_reference_count_get` - Get file count for a record
+- `data_file_reference_delete` - Delete a file reference
+- `data_file_reference_url_get` - Get file URL info
+- `data_file_reference_signed_url_get` - Get signed URL info
 
-// Avoid: Generic, flat structure
-const path = `org-id/files/file.pdf`;
-```
+## Migration from Legacy System
 
-### 2. Validate File Types
+### Before (Legacy)
 ```typescript
-const allowedTypes = ['image/jpeg', 'image/png', 'application/pdf'];
-if (!allowedTypes.includes(file.type)) {
-  throw new Error('File type not allowed');
-}
-```
-
-### 3. Handle Errors Gracefully
-```typescript
-const handleUpload = async (file: File) => {
-  try {
-    const result = await uploadFile(file);
-    if (result.success) {
-      showSuccess('File uploaded successfully');
-    } else {
-      showError(result.error);
-    }
-  } catch (error) {
-    showError('Upload failed. Please try again.');
-  }
-};
-```
-
-### 4. Use Signed URLs for Private Files
-```typescript
-// For private files, always use signed URLs
-const { getSignedUrl } = useStorage({
+const { uploadFile } = useStorage({
   supabase,
-  appName: 'TRAC',
-  orgId: 'your-org-id'
+  appName: 'my-app',
+  orgId: 'org-123'
 });
 
-const signedUrl = await getSignedUrl(filePath, 3600); // 1 hour expiry
+await uploadFile(file, { customPath: 'photos' });
 ```
 
-## Migration from Legacy Storage
-
-**Code Migration:**
+### After (New System)
 ```typescript
-// Before (Legacy)
-const { data, error } = await supabase.storage
-  .from('trac_attachments')
-  .upload('file.pdf', file);
-
-// After (New System)
-const { uploadFile } = useStorage({
-  supabase,
-  appName: 'TRAC',
-  orgId: 'your-org-id'
-});
-const result = await uploadFile(file);
+const { uploadFile } = useFileReference(supabase);
+
+await uploadFile({
+  table_name: 'person',
+  record_id: 'person-123',
+  organisation_id: 'org-123',
+  app_id: 'app-123',
+  category: FileCategory.PROFILE_PHOTOS,
+  is_public: false
+}, file);
 ```
 
-**Note:** Migration scripts have been completed. All files have been moved to the new organization-first structure.
+## Best Practices
+
+1. **Always specify organization context** - Files are automatically scoped to organizations
+2. **Use appropriate file categories** - This helps with organization and access control
+3. **Choose the right bucket** - Use `is_public: true` for files that don't need authentication
+4. **Handle errors gracefully** - The system provides detailed error messages
+5. **Clean up unused files** - Use the delete functions to remove old files
+6. **Monitor file sizes** - Set appropriate `maxSize` limits for your use case
 
 ## Troubleshooting
 
 ### Common Issues
 
-1. **"supabase is undefined"** - Ensure Supabase client is passed as prop
-2. **Upload permission denied** - Check user has organization access
-3. **File not found** - Verify file path and user permissions
-4. **RLS policy errors** - Check organization membership and app access
+1. **"Invalid key: undefined/files/..."** 
+   - Ensure `organisation_id` is provided and valid
+   - Check that app context is properly set
+   - Verify the file path generation is working correctly
+
+2. **"Permission denied" / "RLS policy violation"**
+   - Check RLS policies on `file_references` table
+   - Verify user has active organisation membership
+   - Ensure organisation context is set in database session
+   - For super admins, check `rbac_global_roles` table
+
+3. **"File not found"** 
+   - Verify the file reference exists in the database
+   - Check if file is in the correct bucket (`files` vs `public-files`)
+   - Ensure file path matches the stored `file_path` in database
+
+4. **"URL generation failed"** 
+   - Check if the file is in the correct bucket
+   - Verify Supabase client configuration
+   - For signed URLs, ensure expiration time is valid
+
+5. **"App ID resolution failed"**
+   - Ensure app name is set via `setRBACAppName()` or provide `app_id` prop
+   - Check that app exists in `rbac_apps` table
+   - Verify app name matches exactly (case-sensitive)
+
+6. **Memory leak / "Maximum update depth exceeded"**
+   - Ensure proper cleanup in useEffect hooks
+   - Check for infinite re-render loops in components
+   - Use `clearEventLogoCache()` when unmounting components
 
 ### Debug Mode
 
-```typescript
-const { uploadFile } = useStorage({
-  supabase,
-  appName: 'TRAC',
-  orgId: 'your-org-id',
-  debug: true // Enable debug logging
-});
-```
+Enable debug logging by checking the browser console for detailed information about file operations:
 
-## Examples
-
-### File Upload with Progress
 ```typescript
-const { uploadWithProgress, uploadProgress, isUploading } = useFileUpload({
-  supabase,
-  appName: 'TRAC',
-  orgId: 'your-org-id'
-});
-
-const handleUpload = async (file: File) => {
-  const result = await uploadWithProgress(file);
-  
-  if (result.success) {
-    console.log('Uploaded:', result.path);
-    // uploadProgress is automatically tracked
-  }
-};
-```
-
-### File List with Pagination
-```typescript
-const [files, setFiles] = useState([]);
-const [page, setPage] = useState(0);
-
-const loadFiles = async (pageNum = 0) => {
-  const result = await listFiles({
-    appName: 'TRAC',
-    orgId: 'your-org-id',
-    limit: 50,
-    offset: pageNum * 50
-  });
-  
-  setFiles(prev => pageNum === 0 ? result.files : [...prev, ...result.files]);
-};
-```
-
-### Error Handling
-```typescript
-const handleUpload = async (file: File) => {
-  try {
-    const result = await uploadFile(file);
-    
-    if (result.success) {
-      showSuccess('File uploaded successfully');
-    } else {
-      showError(result.error);
-    }
-  } catch (error) {
-    showError('Upload failed. Please try again.');
-  }
-};
-```
-
----
-
-This storage system provides a simple, secure way to manage files with organization-scoped access control. For more complex use cases, refer to the Supabase Storage documentation.
+// Check file reference status
+const { data } = await supabase
+  .from('file_references')
+  .select('*')
+  .eq('table_name', 'person')
+  .eq('record_id', recordId)
+  .eq('organisation_id', orgId);
+
+console.log('File references:', data);
+
+// Check bucket selection
+import { getBucketName } from '@jmruthers/pace-core';
+const bucket = getBucketName(isPublic);
+console.log('Using bucket:', bucket);
+```

package/src/utils/storage/config.ts

@@ -64,6 +64,15 @@ export function getFileSizeLimit(mimeType: string): number {
   return STORAGE_CONFIG.fileSizeLimits[mimeType] || STORAGE_CONFIG.defaultFileSizeLimit;
 }
 
+/**
+ * Get the bucket name based on whether the file is public or private
+ * @param isPublic - Whether the file should be publicly accessible
+ * @returns The bucket name: 'public-files' for public files, 'files' for private files
+ */
+export function getBucketName(isPublic: boolean): 'files' | 'public-files' {
+  return isPublic ? 'public-files' : 'files';
+}
+
 /**
  * Validate file size against limits
  */