@jmruthers/pace-core 0.5.54 → 0.5.55

package/docs/implementation-guides/file-upload-storage.md

@@ -0,0 +1,733 @@
+# File Upload & Storage System
+
+> **📁 Complete File Management** | [← Back to Documentation](../README.md) | [↑ Table of Contents](#table-of-contents)
+
+Comprehensive guide to implementing file upload, storage, and management using PACE Core's file reference system.
+
+## Overview
+
+PACE Core provides a complete file management system with:
+- **File Upload Component** - Drag-and-drop file upload with validation
+- **File Display Component** - Secure file viewing and management
+- **File Reference System** - Database-backed file tracking with RLS
+- **Storage Hooks** - React hooks for file operations
+- **Security Integration** - Organisation-scoped access control
+
+## Architecture
+
+```mermaid
+graph TD
+    A[FileUpload Component] --> B[useFileReference Hook]
+    B --> C[File Reference Database]
+    C --> D[Storage Bucket]
+    E[FileDisplay Component] --> F[useFileReferenceForRecord Hook]
+    F --> C
+    G[RLS Policies] --> C
+    H[Organisation Context] --> G
+```
+
+## Quick Start
+
+### 1. Basic File Upload
+
+```tsx
+import { FileUpload, FileCategory } from '@jmruthers/pace-core';
+import { useFileReference } from '@jmruthers/pace-core';
+
+function MyFileUpload() {
+  const { uploadFile, getFileUrl, deleteFile, isLoading, error } = useFileReference(supabase);
+
+  const handleUpload = async (file: File) => {
+    try {
+      const fileRef = await uploadFile({
+        file,
+        category: FileCategory.DOCUMENT,
+        description: 'User uploaded document'
+      });
+      console.log('File uploaded:', fileRef);
+    } catch (err) {
+      console.error('Upload failed:', err);
+    }
+  };
+
+  return (
+    <FileUpload
+      supabase={supabase}
+      orgId="org-123"
+      onUploadComplete={handleUpload}
+      accept=".pdf,.doc,.docx"
+      maxSize={5 * 1024 * 1024} // 5MB
+    >
+      <div className="border-2 border-dashed border-main-300 rounded-lg p-8 text-center">
+        <p>Drag and drop files here or click to browse</p>
+      </div>
+    </FileUpload>
+  );
+}
+```
+
+### 2. File Display with Management
+
+```tsx
+import { FileDisplay, FileCategory } from '@jmruthers/pace-core';
+import { useFileReferenceForRecord } from '@jmruthers/pace-core';
+
+function UserProfile({ userId }: { userId: string }) {
+  const { fileUrl, uploadFile, deleteFile, isLoading } = useFileReferenceForRecord(
+    supabase,
+    'pace_person',
+    userId,
+    'org-123'
+  );
+
+  return (
+    <div>
+      <h2>Profile Documents</h2>
+      <FileDisplay
+        supabase={supabase}
+        orgId="org-123"
+        recordType="pace_person"
+        recordId={userId}
+        category={FileCategory.DOCUMENT}
+        onUpload={uploadFile}
+        onDelete={deleteFile}
+        showUpload={true}
+        showDelete={true}
+      />
+    </div>
+  );
+}
+```
+
+## Components
+
+### FileUpload
+
+A comprehensive file upload component with drag-and-drop support, validation, and progress tracking.
+
+#### Props
+
+```typescript
+interface FileUploadProps {
+  supabase: SupabaseClient;
+  appName: string;
+  orgId: string;
+  onUploadComplete?: (fileRef: FileReference) => void;
+  onUploadStart?: (file: File) => void;
+  accept?: string;
+  maxSize?: number;
+  multiple?: boolean;
+  disabled?: boolean;
+  className?: string;
+  children?: React.ReactNode;
+}
+```
+
+#### Usage Examples
+
+**Basic Upload:**
+```tsx
+<FileUpload
+  supabase={supabase}
+  appName="my-app"
+  orgId={organisationId}
+  onUploadComplete={(fileRef) => console.log('Uploaded:', fileRef)}
+  accept="image/*"
+  maxSize={2 * 1024 * 1024} // 2MB
+>
+  <Button>Upload Image</Button>
+</FileUpload>
+```
+
+**Multiple Files:**
+```tsx
+<FileUpload
+  supabase={supabase}
+  appName="my-app"
+  orgId={organisationId}
+  multiple={true}
+  accept=".pdf,.doc,.docx"
+  onUploadComplete={(fileRef) => addToFileList(fileRef)}
+>
+  <div className="upload-area">
+    <UploadIcon className="w-8 h-8" />
+    <p>Upload Documents</p>
+  </div>
+</FileUpload>
+```
+
+**Custom Validation:**
+```tsx
+<FileUpload
+  supabase={supabase}
+  appName="my-app"
+  orgId={organisationId}
+  onUploadStart={(file) => {
+    if (file.size > 10 * 1024 * 1024) {
+      throw new Error('File too large');
+    }
+  }}
+  onUploadComplete={(fileRef) => handleUpload(fileRef)}
+>
+  <CustomUploadArea />
+</FileUpload>
+```
+
+### FileDisplay
+
+A component for displaying and managing files associated with database records.
+
+#### Props
+
+```typescript
+interface FileDisplayProps {
+  supabase: SupabaseClient;
+  appName: string;
+  orgId: string;
+  recordType: string;
+  recordId: string;
+  category?: FileCategory;
+  onUpload?: (file: File) => Promise<FileReference>;
+  onDelete?: (fileRef: FileReference) => Promise<void>;
+  showUpload?: boolean;
+  showDelete?: boolean;
+  showPreview?: boolean;
+  className?: string;
+}
+```
+
+#### Usage Examples
+
+**Read-Only Display:**
+```tsx
+<FileDisplay
+  supabase={supabase}
+  appName="my-app"
+  orgId={organisationId}
+  recordType="pace_person"
+  recordId={personId}
+  category={FileCategory.DOCUMENT}
+  showUpload={false}
+  showDelete={false}
+/>
+```
+
+**Full Management:**
+```tsx
+<FileDisplay
+  supabase={supabase}
+  appName="my-app"
+  orgId={organisationId}
+  recordType="pace_person"
+  recordId={personId}
+  category={FileCategory.IMAGE}
+  onUpload={handleUpload}
+  onDelete={handleDelete}
+  showUpload={true}
+  showDelete={true}
+  showPreview={true}
+/>
+```
+
+## Hooks
+
+### useFileReference
+
+Primary hook for file operations with a Supabase client.
+
+```typescript
+interface UseFileReferenceReturn {
+  uploadFile: (options: UploadFileOptions) => Promise<FileReference>;
+  getFileUrl: (fileRef: FileReference) => Promise<string>;
+  deleteFile: (fileRef: FileReference) => Promise<void>;
+  isLoading: boolean;
+  error: Error | null;
+}
+
+interface UploadFileOptions {
+  file: File;
+  category: FileCategory;
+  description?: string;
+  metadata?: Record<string, any>;
+}
+```
+
+#### Usage
+
+```tsx
+import { useFileReference } from '@jmruthers/pace-core';
+
+function FileManager() {
+  const { uploadFile, getFileUrl, deleteFile, isLoading, error } = useFileReference(supabase);
+
+  const handleUpload = async (file: File) => {
+    try {
+      const fileRef = await uploadFile({
+        file,
+        category: FileCategory.DOCUMENT,
+        description: 'User document',
+        metadata: { uploadedBy: user.id }
+      });
+      
+      // Get the public URL
+      const url = await getFileUrl(fileRef);
+      console.log('File available at:', url);
+    } catch (err) {
+      console.error('Upload failed:', err);
+    }
+  };
+
+  const handleDelete = async (fileRef: FileReference) => {
+    try {
+      await deleteFile(fileRef);
+      console.log('File deleted');
+    } catch (err) {
+      console.error('Delete failed:', err);
+    }
+  };
+
+  return (
+    <div>
+      {/* Upload UI */}
+      {isLoading && <div>Uploading...</div>}
+      {error && <div>Error: {error.message}</div>}
+    </div>
+  );
+}
+```
+
+### useFileReferenceForRecord
+
+Hook for managing files associated with specific database records.
+
+```typescript
+interface UseFileReferenceForRecordReturn {
+  fileUrl: string | null;
+  uploadFile: (file: File) => Promise<FileReference>;
+  deleteFile: (fileRef: FileReference) => Promise<void>;
+  isLoading: boolean;
+  error: Error | null;
+}
+```
+
+#### Usage
+
+```tsx
+import { useFileReferenceForRecord } from '@jmruthers/pace-core';
+
+function PersonProfile({ personId }: { personId: string }) {
+  const { fileUrl, uploadFile, deleteFile, isLoading } = useFileReferenceForRecord(
+    supabase,
+    'pace_person',
+    personId,
+    organisationId
+  );
+
+  return (
+    <div>
+      {fileUrl && (
+        <img 
+          src={fileUrl} 
+          alt="Profile" 
+          className="w-32 h-32 rounded-full"
+        />
+      )}
+      
+      <FileUpload onUploadComplete={uploadFile}>
+        <Button>Change Photo</Button>
+      </FileUpload>
+      
+      {fileUrl && (
+        <Button onClick={() => deleteFile(fileRef)} variant="destructive">
+          Remove Photo
+        </Button>
+      )}
+    </div>
+  );
+}
+```
+
+## File Categories
+
+PACE Core supports predefined file categories for better organization:
+
+```typescript
+enum FileCategory {
+  DOCUMENT = 'document',
+  IMAGE = 'image',
+  AUDIO = 'audio',
+  VIDEO = 'video',
+  ARCHIVE = 'archive',
+  SPREADSHEET = 'spreadsheet',
+  PRESENTATION = 'presentation',
+  OTHER = 'other'
+}
+```
+
+### Usage
+
+```tsx
+import { FileCategory } from '@jmruthers/pace-core';
+
+// Upload a document
+await uploadFile({
+  file: pdfFile,
+  category: FileCategory.DOCUMENT,
+  description: 'Contract document'
+});
+
+// Upload an image
+await uploadFile({
+  file: imageFile,
+  category: FileCategory.IMAGE,
+  description: 'Profile photo'
+});
+```
+
+## Database Schema
+
+The file reference system uses the following database structure:
+
+### file_references Table
+
+```sql
+CREATE TABLE file_references (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  organisation_id UUID NOT NULL REFERENCES organisations(id),
+  record_type TEXT NOT NULL,
+  record_id UUID NOT NULL,
+  file_name TEXT NOT NULL,
+  file_size BIGINT NOT NULL,
+  file_type TEXT NOT NULL,
+  file_category TEXT NOT NULL,
+  storage_path TEXT NOT NULL,
+  description TEXT,
+  metadata JSONB,
+  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+  created_by UUID REFERENCES auth.users(id),
+  updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
+);
+
+-- RLS Policies
+ALTER TABLE file_references ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY "Users can view files in their organisation" ON file_references
+  FOR SELECT USING (
+    organisation_id IN (
+      SELECT organisation_id FROM user_organisation_memberships 
+      WHERE user_id = auth.uid()
+    )
+  );
+
+CREATE POLICY "Users can insert files in their organisation" ON file_references
+  FOR INSERT WITH CHECK (
+    organisation_id IN (
+      SELECT organisation_id FROM user_organisation_memberships 
+      WHERE user_id = auth.uid()
+    )
+  );
+
+CREATE POLICY "Users can update files in their organisation" ON file_references
+  FOR UPDATE USING (
+    organisation_id IN (
+      SELECT organisation_id FROM user_organisation_memberships 
+      WHERE user_id = auth.uid()
+    )
+  );
+
+CREATE POLICY "Users can delete files in their organisation" ON file_references
+  FOR DELETE USING (
+    organisation_id IN (
+      SELECT organisation_id FROM user_organisation_memberships 
+      WHERE user_id = auth.uid()
+    )
+  );
+```
+
+## Storage Configuration
+
+### Supabase Storage Setup
+
+1. **Create Storage Bucket:**
+```sql
+INSERT INTO storage.buckets (id, name, public)
+VALUES ('pace-files', 'pace-files', false);
+```
+
+2. **Set Bucket Policies:**
+```sql
+-- Allow authenticated users to upload
+CREATE POLICY "Authenticated users can upload files" ON storage.objects
+  FOR INSERT WITH CHECK (bucket_id = 'pace-files' AND auth.role() = 'authenticated');
+
+-- Allow users to view files in their organisation
+CREATE POLICY "Users can view files in their organisation" ON storage.objects
+  FOR SELECT USING (
+    bucket_id = 'pace-files' AND
+    (storage.foldername(name))[1] IN (
+      SELECT id::text FROM organisations 
+      WHERE id IN (
+        SELECT organisation_id FROM user_organisation_memberships 
+        WHERE user_id = auth.uid()
+      )
+    )
+  );
+
+-- Allow users to delete files in their organisation
+CREATE POLICY "Users can delete files in their organisation" ON storage.objects
+  FOR DELETE USING (
+    bucket_id = 'pace-files' AND
+    (storage.foldername(name))[1] IN (
+      SELECT id::text FROM organisations 
+      WHERE id IN (
+        SELECT organisation_id FROM user_organisation_memberships 
+        WHERE user_id = auth.uid()
+      )
+    )
+  );
+```
+
+## Security Considerations
+
+### Row Level Security (RLS)
+
+All file operations are protected by RLS policies that ensure:
+- Users can only access files within their organisation
+- File metadata is properly scoped
+- Storage paths are organisation-isolated
+
+### File Validation
+
+```tsx
+import { validateFileUpload } from '@jmruthers/pace-core';
+
+const fileUploadConfig = {
+  maxSize: 5 * 1024 * 1024, // 5MB
+  allowedTypes: ['image/jpeg', 'image/png', 'application/pdf'],
+  allowedExtensions: ['.jpg', '.jpeg', '.png', '.pdf']
+};
+
+function FileUpload() {
+  const handleFileUpload = async (file: File) => {
+    try {
+      const validation = await validateFileUpload(file, fileUploadConfig);
+      if (!validation.isValid) {
+        throw new Error(validation.errors.join(', '));
+      }
+      
+      // Proceed with upload
+      await uploadFile({ file, category: FileCategory.DOCUMENT });
+    } catch (error) {
+      console.error('File validation failed:', error);
+    }
+  };
+
+  return (
+    <FileUpload onUploadComplete={handleFileUpload}>
+      <UploadArea />
+    </FileUpload>
+  );
+}
+```
+
+## Migration from Old File Columns
+
+If you're migrating from direct file columns to the file reference system:
+
+### 1. Create Migration Script
+
+```sql
+-- Example migration for pace_person table
+INSERT INTO file_references (
+  organisation_id,
+  record_type,
+  record_id,
+  file_name,
+  file_size,
+  file_type,
+  file_category,
+  storage_path,
+  created_at,
+  created_by
+)
+SELECT 
+  organisation_id,
+  'pace_person',
+  id,
+  COALESCE(avatar_filename, 'unknown'),
+  COALESCE(avatar_size, 0),
+  COALESCE(avatar_type, 'application/octet-stream'),
+  'image',
+  COALESCE(avatar_path, ''),
+  created_at,
+  created_by
+FROM pace_person 
+WHERE avatar_filename IS NOT NULL;
+```
+
+### 2. Update Application Code
+
+```tsx
+// Before: Direct file column access
+const avatarUrl = person.avatar_url;
+
+// After: File reference system
+const { fileUrl } = useFileReferenceForRecord(
+  supabase,
+  'pace_person',
+  person.id,
+  organisationId
+);
+```
+
+## Complete Examples
+
+### Profile Photo Management
+
+```tsx
+import { 
+  FileUpload, 
+  FileDisplay, 
+  useFileReferenceForRecord,
+  FileCategory 
+} from '@jmruthers/pace-core';
+
+function ProfilePhotoManager({ personId }: { personId: string }) {
+  const { fileUrl, uploadFile, deleteFile, isLoading } = useFileReferenceForRecord(
+    supabase,
+    'pace_person',
+    personId,
+    organisationId
+  );
+
+  const handleUpload = async (file: File) => {
+    try {
+      await uploadFile(file);
+      toast.success('Photo updated successfully');
+    } catch (error) {
+      toast.error('Failed to update photo');
+    }
+  };
+
+  const handleDelete = async () => {
+    try {
+      await deleteFile(fileRef);
+      toast.success('Photo removed');
+    } catch (error) {
+      toast.error('Failed to remove photo');
+    }
+  };
+
+  return (
+    <div className="space-y-4">
+      <div className="flex items-center space-x-4">
+        {fileUrl ? (
+          <img 
+            src={fileUrl} 
+            alt="Profile" 
+            className="w-24 h-24 rounded-full object-cover"
+          />
+        ) : (
+          <div className="w-24 h-24 rounded-full bg-sec-200 flex items-center justify-center">
+            <UserIcon className="w-8 h-8 text-sec-500" />
+          </div>
+        )}
+        
+        <div className="space-y-2">
+          <FileUpload
+            supabase={supabase}
+            appName="my-app"
+            orgId={organisationId}
+            onUploadComplete={handleUpload}
+            accept="image/*"
+            maxSize={2 * 1024 * 1024}
+          >
+            <Button size="sm">Change Photo</Button>
+          </FileUpload>
+          
+          {fileUrl && (
+            <Button 
+              size="sm" 
+              variant="destructive"
+              onClick={handleDelete}
+            >
+              Remove Photo
+            </Button>
+          )}
+        </div>
+      </div>
+      
+      {isLoading && <div>Processing...</div>}
+    </div>
+  );
+}
+```
+
+### Document Management
+
+```tsx
+import { FileDisplay, FileCategory } from '@jmruthers/pace-core';
+
+function DocumentManager({ recordId, recordType }: { 
+  recordId: string; 
+  recordType: string; 
+}) {
+  return (
+    <div className="space-y-4">
+      <h3>Documents</h3>
+      
+      <FileDisplay
+        supabase={supabase}
+        appName="my-app"
+        orgId={organisationId}
+        recordType={recordType}
+        recordId={recordId}
+        category={FileCategory.DOCUMENT}
+        showUpload={true}
+        showDelete={true}
+        showPreview={true}
+      />
+    </div>
+  );
+}
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Issue: Files not uploading**
+- Check Supabase storage bucket configuration
+- Verify RLS policies are correctly set
+- Ensure organisation context is available
+
+**Issue: Files not displaying**
+- Check file reference database records
+- Verify storage path is correct
+- Ensure user has organisation access
+
+**Issue: Permission denied errors**
+- Verify RLS policies allow user access
+- Check organisation membership
+- Ensure file belongs to user's organisation
+
+### Debug Mode
+
+Enable debug logging to troubleshoot file operations:
+
+```tsx
+import { setRBACConfig } from '@jmruthers/pace-core/rbac';
+
+// Enable debug mode
+setRBACConfig({
+  logLevel: 'debug',
+  enableAuditLogging: true
+});
+```
+
+## Next Steps
+
+- **[Storage Utilities](../api-reference/utilities.md#storage)** - Additional storage utilities
+- **[Security Best Practices](../best-practices/security.md)** - Security guidelines
+- **[RBAC Integration](./permission-enforcement.md)** - Permission-based file access
+- **[Performance Optimization](./performance.md)** - Large file handling