@jmruthers/pace-core 0.5.188 → 0.5.190

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

@@ -38,9 +38,10 @@ export class FileReferenceServiceImpl implements FileReferenceService {
   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');
+      // 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');
@@ -52,12 +53,25 @@ export class FileReferenceServiceImpl implements FileReferenceService {
         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;
+      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 });
+      }
+
       // Step 1: Upload file to storage bucket first
-      // This generates a unique path: {orgId}/{folder}/{timestamp-uuid-filename}
+      // 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,
+        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
       });
@@ -74,13 +88,16 @@ export class FileReferenceServiceImpl implements FileReferenceService {
       // Step 2: Extract file metadata (dimensions, hash, etc.)
       const metadata = await extractFileMetadata(file, {
         appName: 'file-reference',
-        orgId: options.organisation_id,
+        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
-      // This ensures RLS policies can check the organisation context
-      await setOrganisationContext(this.supabase, options.organisation_id);
+      // Skip for user-scoped files (no org context needed)
+      if (!isUserScoped && options.organisation_id) {
+        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
@@ -89,7 +106,7 @@ export class FileReferenceServiceImpl implements FileReferenceService {
           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_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
@@ -101,7 +118,8 @@ export class FileReferenceServiceImpl implements FileReferenceService {
             ...metadata,
             ...options.custom_metadata
           },
-          p_is_public: options.is_public || false
+          p_is_public: options.is_public || false,
+          p_user_id: authenticatedUserId || options.userId || null // Pass authenticated user ID for user-scoped files
         });
 
       // Step 5: Rollback - if database insert fails, clean up uploaded file
@@ -131,10 +149,11 @@ export class FileReferenceServiceImpl implements FileReferenceService {
       }
 
       // 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,
-        options.organisation_id,
+        options.organisation_id || null,
         options.category
       );
 
@@ -145,15 +164,22 @@ export class FileReferenceServiceImpl implements FileReferenceService {
     }
   }
 
-  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<FileReference | null> {
     try {
-      const { data, error } = await this.supabase
+      let query = this.supabase
         .from('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)
-        .eq('organisation_id', organisation_id)
-        .single();
+        .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') {
@@ -169,7 +195,7 @@ export class FileReferenceServiceImpl implements FileReferenceService {
     }
   }
 
-  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<string | null> {
     try {
       // Get file reference to check if it's public
       const fileRef = await this.getFileReference(table_name, record_id, organisation_id);
@@ -202,14 +228,14 @@ export class FileReferenceServiceImpl implements FileReferenceService {
     }
   }
 
-  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<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_organisation_id: organisation_id ?? null,
           p_expires_in: expires_in
         });
 
@@ -225,6 +251,7 @@ export class FileReferenceServiceImpl implements FileReferenceService {
       const signedUrlResult = await getSignedUrl(this.supabase, filePath, {
         appName: 'file-reference',
         orgId: organisation_id,
+        userId: organisation_id ? undefined : record_id,
         expiresIn: expires_in
       });
 
@@ -255,7 +282,7 @@ export class FileReferenceServiceImpl implements FileReferenceService {
     }
   }
 
-  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<boolean> {
     try {
       // Get file reference first to determine bucket
       const fileRef = await this.getFileReference(table_name, record_id, organisation_id);
@@ -264,7 +291,7 @@ export class FileReferenceServiceImpl implements FileReferenceService {
         .rpc('data_file_reference_delete', {
           p_table_name: table_name,
           p_record_id: record_id,
-          p_organisation_id: organisation_id,
+          p_organisation_id: organisation_id ?? null,
           p_delete_file: delete_file
         });
 
@@ -284,13 +311,13 @@ export class FileReferenceServiceImpl implements FileReferenceService {
     }
   }
 
-  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<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
+          p_organisation_id: organisation_id ?? null
         });
 
       if (error) {
@@ -331,7 +358,7 @@ export class FileReferenceServiceImpl implements FileReferenceService {
               fileType,
               ...(item.file_metadata || {}),
             } as FileMetadata,
-            organisation_id: organisation_id,
+            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(),
@@ -347,13 +374,13 @@ export class FileReferenceServiceImpl implements FileReferenceService {
     }
   }
 
-  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<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
+          p_organisation_id: organisation_id ?? null
         });
 
       if (error) {
@@ -367,12 +394,12 @@ export class FileReferenceServiceImpl implements FileReferenceService {
     }
   }
 
-  async getFileReferenceById(id: string, organisation_id: string): Promise<FileReference | null> {
+  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
+          p_organisation_id: organisation_id ?? null
         });
 
       if (error) {
@@ -394,7 +421,7 @@ export class FileReferenceServiceImpl implements FileReferenceService {
     table_name: string, 
     record_id: string, 
     category: FileCategory, 
-    organisation_id: string
+    organisation_id?: string
   ): Promise<FileReference[]> {
     try {
       // CRITICAL: Use RPC function to get files by category - this correctly filters on file_metadata->>'category'
@@ -405,7 +432,7 @@ export class FileReferenceServiceImpl implements FileReferenceService {
           p_table_name: table_name,
           p_record_id: record_id,
           p_category: category,
-          p_organisation_id: organisation_id
+          p_organisation_id: organisation_id ?? null
         });
 
       if (error) {
@@ -471,7 +498,7 @@ export class FileReferenceServiceImpl implements FileReferenceService {
               category: (item.file_metadata?.category as FileCategory) || FileCategory.GENERAL_DOCUMENTS,
               ...(item.file_metadata || {}),
             } as FileMetadata,
-            organisation_id: organisation_id,
+            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(),
@@ -542,11 +569,12 @@ export async function uploadFileWithReference(
   const service = createFileReferenceService(supabase);
   const fileReference = await service.createFileReference(options, file);
   
-  const fileUrl = options.is_public 
+    const fileUrl = options.is_public 
     ? getPublicUrl(supabase, fileReference.file_path, true)
     : await getSignedUrl(supabase, fileReference.file_path, { 
         appName: 'file-reference',
-        orgId: options.organisation_id,
+        orgId: options.organisation_id || undefined,
+        userId: options.userId || undefined,
         expiresIn: 3600 
       });
 

package/src/utils/google-places/googlePlacesUtils.test.ts

@@ -14,6 +14,7 @@ import {
   getAddressByPlaceId,
 } from './googlePlacesUtils';
 import { clearInFlightRequests } from '../request-deduplication';
+import { loadGoogleMapsScript, isGoogleMapsLoaded } from './loadGoogleMapsScript';
 import type { GoogleAddressComponent } from './types';
 
 // Mock loadGoogleMapsScript
@@ -62,6 +63,10 @@ const mockPlacesService = {
   getDetails: vi.fn(),
 };
 
+const mockAutocompleteSuggestion = {
+  fetchAutocompleteSuggestions: vi.fn(),
+};
+
 // Setup global window.google mock before any tests
 const setupGoogleMapsMock = () => {
   const googleMapsMock = {
@@ -69,6 +74,7 @@ const setupGoogleMapsMock = () => {
       places: {
         AutocompleteService: vi.fn(() => mockAutocompleteService),
         PlacesService: vi.fn(() => mockPlacesService),
+        AutocompleteSuggestion: undefined as any,
         PlacesServiceStatus: {
           OK: 'OK',
           ZERO_RESULTS: 'ZERO_RESULTS',
@@ -105,9 +111,11 @@ describe('Google Places API Utilities', () => {
   beforeEach(() => {
     vi.clearAllMocks();
     clearInFlightRequests();
+    setupGoogleMapsMock();
     // Reset mocks
     mockAutocompleteService.getPlacePredictions.mockClear();
     mockPlacesService.getDetails.mockClear();
+    mockAutocompleteSuggestion.fetchAutocompleteSuggestions.mockReset();
   });
 
   afterEach(() => {
@@ -200,6 +208,96 @@ describe('Google Places API Utilities', () => {
       expect(callArgs.types).toEqual(['address']);
       expect(callArgs.language).toBe('en');
     }, { timeout: 5000 });
+
+    it('uses the new AutocompleteSuggestion API when available', async () => {
+      const fetchMock = mockAutocompleteSuggestion.fetchAutocompleteSuggestions;
+      (window as any).google.maps.places.AutocompleteSuggestion = mockAutocompleteSuggestion as any;
+
+      fetchMock.mockResolvedValue({
+        suggestions: [
+          {
+            placePrediction: {
+              placeId: 'place-new',
+              text: { text: 'Main St', matches: [] },
+              structuredFormat: {
+                mainText: { text: 'Main St' },
+                secondaryText: { text: 'Melbourne' },
+              },
+            },
+          },
+        ],
+      });
+
+      const result = await fetchPlaceAutocomplete('Main', mockApiKey);
+
+      expect(fetchMock).toHaveBeenCalledWith({ input: 'Main' });
+      expect(result).toEqual([
+        {
+          description: 'Main St',
+          place_id: 'place-new',
+          structured_formatting: {
+            main_text: 'Main St',
+            secondary_text: 'Melbourne',
+          },
+        },
+      ]);
+      expect(mockAutocompleteService.getPlacePredictions).not.toHaveBeenCalled();
+    });
+
+    it('surface errors from the new AutocompleteSuggestion API', async () => {
+      (window as any).google.maps.places.AutocompleteSuggestion = mockAutocompleteSuggestion as any;
+      mockAutocompleteSuggestion.fetchAutocompleteSuggestions.mockRejectedValue(new Error('network down'));
+
+      await expect(fetchPlaceAutocomplete('Main', mockApiKey)).rejects.toThrow(
+        'Failed to fetch autocomplete predictions: network down'
+      );
+    });
+
+    it('loads Google Maps script when not already available', async () => {
+      const mockedLoadScript = vi.mocked(loadGoogleMapsScript);
+      const mockedIsLoaded = vi.mocked(isGoogleMapsLoaded);
+
+      mockedIsLoaded.mockReturnValueOnce(false);
+      mockedLoadScript.mockResolvedValueOnce();
+
+      (window as any).google.maps.places.AutocompleteSuggestion = mockAutocompleteSuggestion as any;
+      mockAutocompleteSuggestion.fetchAutocompleteSuggestions.mockResolvedValue({ suggestions: [] });
+
+      await fetchPlaceAutocomplete('123 Main', mockApiKey);
+
+      expect(mockedLoadScript).toHaveBeenCalledWith(mockApiKey, 'places');
+    });
+
+    it('deduplicates simultaneous autocomplete requests', async () => {
+      vi.useFakeTimers();
+
+      mockAutocompleteService.getPlacePredictions.mockImplementation((request, callback) => {
+        setTimeout(() => {
+          callback(
+            [
+              {
+                description: 'First',
+                place_id: 'place-1',
+                structured_formatting: { main_text: 'First', secondary_text: '' },
+              },
+            ],
+            'OK'
+          );
+        }, 10);
+      });
+
+      const promise1 = fetchPlaceAutocomplete('duplicate', mockApiKey);
+      const promise2 = fetchPlaceAutocomplete('duplicate', mockApiKey);
+
+      vi.runAllTimers();
+
+      const [result1, result2] = await Promise.all([promise1, promise2]);
+
+      expect(mockAutocompleteService.getPlacePredictions).toHaveBeenCalledTimes(1);
+      expect(result1).toEqual(result2);
+
+      vi.useRealTimers();
+    });
   });
 
   describe('fetchPlaceDetails', () => {

package/src/utils/google-places/loadGoogleMapsScript.test.ts

@@ -0,0 +1,83 @@
+/**
+ * @file Google Maps Script Loader Tests
+ * @package @jmruthers/pace-core
+ * @module Utils/GooglePlaces/__tests__
+ * @since 0.1.0
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { isGoogleMapsLoaded, loadGoogleMapsScript } from './loadGoogleMapsScript';
+
+describe('loadGoogleMapsScript', () => {
+  const originalGoogle = (window as any).google;
+
+  beforeEach(() => {
+    (window as any).google = undefined;
+    document.head.innerHTML = '';
+  });
+
+  afterEach(() => {
+    (window as any).google = originalGoogle;
+    document.head.innerHTML = '';
+  });
+
+  it('detects when Google Maps is loaded', () => {
+    expect(isGoogleMapsLoaded()).toBe(false);
+
+    (window as any).google = { maps: { places: {} } };
+
+    expect(isGoogleMapsLoaded()).toBe(true);
+  });
+
+  it('resolves immediately when Maps is already available', async () => {
+    (window as any).google = { maps: { places: {} } };
+    const appendSpy = vi.spyOn(document.head, 'appendChild');
+
+    await expect(loadGoogleMapsScript('ready-key')).resolves.toBeUndefined();
+
+    expect(appendSpy).not.toHaveBeenCalled();
+  });
+
+  it('loads the script and resolves after the library initializes', async () => {
+    const appendSpy = vi.spyOn(document.head, 'appendChild');
+
+    const loadPromise = loadGoogleMapsScript('api-key');
+
+    expect(appendSpy).toHaveBeenCalledTimes(1);
+    const scriptEl = appendSpy.mock.calls[0][0] as HTMLScriptElement;
+    expect(scriptEl.src).toContain('key=api-key');
+
+    (window as any).google = { maps: { places: {} } };
+    scriptEl.onload?.(new Event('load'));
+
+    await expect(loadPromise).resolves.toBeUndefined();
+  });
+
+  it('reuses an existing script element', async () => {
+    const existingScript = document.createElement('script');
+    existingScript.src = 'https://maps.googleapis.com/maps/api/js?key=existing&libraries=places&loading=async';
+    document.head.appendChild(existingScript);
+
+    const appendSpy = vi.spyOn(document.head, 'appendChild');
+
+    const loadPromise = loadGoogleMapsScript('new-key');
+
+    (window as any).google = { maps: { places: {} } };
+    existingScript.dispatchEvent(new Event('load'));
+
+    await expect(loadPromise).resolves.toBeUndefined();
+    expect(appendSpy).not.toHaveBeenCalled();
+  });
+
+  it('rejects when the script fails to load', async () => {
+    const appendSpy = vi.spyOn(document.head, 'appendChild');
+
+    const loadPromise = loadGoogleMapsScript('bad-key');
+    const scriptEl = appendSpy.mock.calls[0][0] as HTMLScriptElement;
+
+    scriptEl.onerror?.(new Event('error'));
+
+    await expect(loadPromise).rejects.toThrow('Failed to load Google Maps script');
+  });
+});
+

package/src/utils/storage/helpers.test.ts

@@ -60,7 +60,7 @@ describe('[utility] Storage Helpers', () => {
 
     it('validates required orgId', () => {
       expect(() => generateFilePath({ orgId: '' } as any, 'test.jpg'))
-        .toThrow('orgId is required for file path generation');
+        .toThrow('Either orgId or userId is required for file path generation');
     });
 
     it('handles special characters in file names', () => {

package/src/utils/storage/helpers.ts

@@ -18,33 +18,37 @@ import { createLogger } from '../core/logger';
 const log = createLogger('StorageHelpers');
 
 /**
- * Generate a file path based on organization-first structure
+ * Generate a file path based on organization-first or user-first structure
+ * - If orgId is provided: {orgId}/{folder}/filename
+ * - If userId is provided (and orgId is not): users/{userId}/{folder}/filename
  */
 export function generateFilePath(options: StorageUploadOptions, fileName: string): string {
-  const { orgId, isPublic = false, customPath } = options;
+  const { orgId, userId, isPublic = false, customPath } = options;
   
-  
-  // Validate required orgId
-  if (!orgId) {
-    throw new Error('orgId is required for file path generation');
+  // Validate that either orgId or userId is provided
+  if (!orgId && !userId) {
+    throw new Error('Either orgId or userId is required for file path generation');
   }
   
+  // Determine base path: organisation-based or user-based
+  const basePath = orgId ? orgId : `users/${userId}`;
+  
   if (isPublic) {
-    // Public files go to {orgId}/{folder}/filename
+    // Public files go to {basePath}/{folder}/filename
     if (customPath) {
-      return `${orgId}/${customPath}/${fileName}`;
+      return `${basePath}/${customPath}/${fileName}`;
     }
-    return `${orgId}/public/${fileName}`;
+    return `${basePath}/public/${fileName}`;
   }
   
-  // Organization-first structure: {orgId}/{folder}/filename
+  // Organization-first or user-first structure: {basePath}/{folder}/filename
   if (customPath) {
-    return `${orgId}/${customPath}/${fileName}`;
+    return `${basePath}/${customPath}/${fileName}`;
   }
   
   // Use customPath if available, otherwise default to files
   const pathFolder = customPath || 'files';
-  return `${orgId}/${pathFolder}/${fileName}`;
+  return `${basePath}/${pathFolder}/${fileName}`;
 }
 
 /**
@@ -86,7 +90,8 @@ export async function extractFileMetadata(
   const metadata: StorageFileMetadata = {
     mimeType: file.type,
     size: file.size,
-    orgId: options.orgId,
+    ...(options.orgId && { orgId: options.orgId }),
+    ...(options.userId && { userId: options.userId }),
     appName: options.appName || 'pace-core',
     uploadedBy,
     uploadedAt: new Date().toISOString(),
@@ -608,8 +613,14 @@ export async function listFiles(
     // Select bucket based on isPublic flag (default to private files bucket)
     const bucketName = getBucketName(options.isPublic || false);
     
-    // Organization-first structure: {orgId}/{category}/
-    const pathPrefix = `${options.orgId}/`;
+    // Validate that either orgId or userId is provided
+    if (!options.orgId && !options.userId) {
+      throw new Error('Either orgId or userId is required for listing files');
+    }
+    
+    // Organization-first or user-first structure
+    const basePath = options.orgId ? options.orgId : `users/${options.userId}`;
+    const pathPrefix = `${basePath}/`;
     const searchPath = options.pathPrefix ? `${pathPrefix}${options.pathPrefix}` : pathPrefix;
 
     const { data, error } = await supabase.storage
@@ -634,7 +645,8 @@ export async function listFiles(
       metadata: {
         mimeType: item.metadata?.mimetype || 'application/octet-stream',
         size: item.metadata?.size || 0,
-        orgId: options.orgId,
+        ...(options.orgId && { orgId: options.orgId }),
+        ...(options.userId && { userId: options.userId }),
         appName: options.appName,
         uploadedBy: 'unknown',
         uploadedAt: item.created_at || new Date().toISOString(),
@@ -716,13 +728,20 @@ export async function downloadFile(
 export async function archiveFile(
   supabase: SupabaseClient,
   path: string,
-  options: { appName: string; orgId: string; isPublic?: boolean }
+  options: { appName: string; orgId?: string; userId?: string; isPublic?: boolean }
 ): Promise<{ success: boolean; error?: string }> {
   try {
     const bucketName = getBucketName(options.isPublic || false);
     
-    // Generate archived path for organization-first structure
-    const archivedPath = path.replace(`${options.orgId}/`, `archived/${options.orgId}/`);
+    // Generate archived path for organization-first or user-first structure
+    let archivedPath: string;
+    if (options.orgId) {
+      archivedPath = path.replace(`${options.orgId}/`, `archived/${options.orgId}/`);
+    } else if (options.userId) {
+      archivedPath = path.replace(`users/${options.userId}/`, `archived/users/${options.userId}/`);
+    } else {
+      throw new Error('Either orgId or userId is required for archiving files');
+    }
     
     // Copy file to archived location
     const { error: copyError } = await supabase.storage

package/src/utils/storage/types.ts

@@ -5,13 +5,15 @@
 export interface StorageUploadOptions {
   /** The app name from rbac_apps */
   appName: string;
-  /** Organisation ID for scoping */
-  orgId: string;
+  /** Organisation ID for scoping (required if userId not provided) */
+  orgId?: string;
+  /** User ID for user-scoped files (required if orgId not provided) */
+  userId?: string;
   /** Whether the file should be publicly accessible */
   isPublic?: boolean;
   /** Optional tags for categorisation */
   tags?: string[];
-  /** Optional custom path within the app/org structure */
+  /** Optional custom path within the app/org/user structure */
   customPath?: string;
   /** Optional metadata to store with the file */
   metadata?: Record<string, any>;
@@ -23,7 +25,8 @@ export interface StorageFileMetadata {
   width?: number;
   height?: number;
   hash?: string;
-  orgId: string;
+  orgId?: string;
+  userId?: string;
   appName: string;
   uploadedBy: string;
   uploadedAt: string;
@@ -43,8 +46,10 @@ export interface StorageUploadResult {
 export interface StorageUrlOptions {
   /** The app name from rbac_apps */
   appName: string;
-  /** Organisation ID for scoping */
-  orgId: string;
+  /** Organisation ID for scoping (required if userId not provided) */
+  orgId?: string;
+  /** User ID for user-scoped files (required if orgId not provided) */
+  userId?: string;
   /** Expiry time in seconds for signed URLs (default: 3600) */
   expiresIn?: number;
 }
@@ -52,8 +57,10 @@ export interface StorageUrlOptions {
 export interface StorageListOptions {
   /** The app name from rbac_apps */
   appName: string;
-  /** Organisation ID for scoping */
-  orgId: string;
+  /** Organisation ID for scoping (required if userId not provided) */
+  orgId?: string;
+  /** User ID for user-scoped files (required if orgId not provided) */
+  userId?: string;
   /** Optional path prefix to filter by */
   pathPrefix?: string;
   /** Optional tags to filter by */