@jmruthers/pace-core 0.5.93 → 0.5.95

package/src/hooks/useFileDisplay.ts

@@ -0,0 +1,370 @@
+/**
+ * @file File Display Hook (Authenticated)
+ * @package @jmruthers/pace-core
+ * @module Hooks
+ *
+ * A React hook for accessing file references in authenticated contexts.
+ * Can handle both public and private files using the file_references system.
+ *
+ * Features:
+ * - Works in authenticated contexts
+ * - Supports both public and private files
+ * - Automatic signed URL generation for private files
+ * - Caching for performance
+ * - Error handling and loading states
+ * - Supports both single file (category) and multiple files
+ *
+ * @example
+ * ```tsx
+ * import { useFileDisplay } from '@jmruthers/pace-core';
+ *
+ * function FileView() {
+ *   const { fileUrl, fileReference, isLoading, error } = useFileDisplay(
+ *     'event',
+ *     eventId,
+ *     organisationId,
+ *     FileCategory.EVENT_LOGOS
+ *   );
+ *
+ *   if (isLoading) return <div>Loading...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *
+ *   return fileUrl ? <img src={fileUrl} alt="File" /> : null;
+ * }
+ * ```
+ */
+
+import { useState, useEffect, useCallback } from 'react';
+import type { SupabaseClient } from '@supabase/supabase-js';
+import { FileReference, FileCategory } from '../types/file-reference';
+import { getPublicUrl, getSignedUrl } from '../utils/storage/helpers';
+import { createFileReferenceService } from '../utils/file-reference';
+
+// Simple in-memory cache for authenticated file data
+const authenticatedFileCache = new Map<string, { data: any; timestamp: number; ttl: number }>();
+
+// Cache size limit to prevent memory leaks
+const MAX_CACHE_SIZE = 100;
+
+// Helper function to clean up expired entries and enforce size limit
+function cleanupCache() {
+  const now = Date.now();
+  const entries = Array.from(authenticatedFileCache.entries());
+  
+  // Remove expired entries
+  const expiredKeys: string[] = [];
+  entries.forEach(([key, value]) => {
+    if (now - value.timestamp >= value.ttl) {
+      expiredKeys.push(key);
+    }
+  });
+  expiredKeys.forEach(key => authenticatedFileCache.delete(key));
+  
+  // If still over limit, remove oldest entries
+  if (authenticatedFileCache.size > MAX_CACHE_SIZE) {
+    const sorted = entries
+      .filter(([key]) => !expiredKeys.includes(key))
+      .sort((a, b) => a[1].timestamp - b[1].timestamp);
+    const toRemove = sorted.slice(0, authenticatedFileCache.size - MAX_CACHE_SIZE);
+    toRemove.forEach(([key]) => authenticatedFileCache.delete(key));
+  }
+}
+
+export interface UseFileDisplayReturn {
+  /** Single file URL if category is provided and file found, null otherwise */
+  fileUrl: string | null;
+  /** Single file reference if category is provided and file found, null otherwise */
+  fileReference: FileReference | null;
+  /** Array of all file references for the record (when category not provided or for multiple files) */
+  fileReferences: FileReference[];
+  /** Map of file IDs to URLs for multiple files */
+  fileUrls: Map<string, string>;
+  /** Total count of files for the record */
+  fileCount: number;
+  /** Whether the data is currently loading */
+  isLoading: boolean;
+  /** Any error that occurred during loading */
+  error: Error | null;
+  /** Function to manually refetch the data */
+  refetch: () => Promise<void>;
+}
+
+export interface UseFileDisplayOptions {
+  /** Cache TTL in milliseconds (default: 30 minutes) */
+  cacheTtl?: number;
+  /** Whether to enable caching (default: true) */
+  enableCache?: boolean;
+  /** Supabase client instance (required) */
+  supabase: SupabaseClient | null;
+}
+
+/**
+ * Hook for accessing file references in authenticated contexts
+ * 
+ * This hook provides access to file references for authenticated users.
+ * It supports both public and private files, generating appropriate URLs
+ * (public URLs for public files, signed URLs for private files).
+ * 
+ * @param table_name - The table name containing the file reference
+ * @param record_id - The record ID that owns the file(s)
+ * @param organisation_id - The organisation ID for storage path
+ * @param category - Optional file category to filter by (for single file mode)
+ * @param options - Configuration options for caching and behavior
+ * @returns Object containing file data, loading state, error, and refetch function
+ */
+export function useFileDisplay(
+  table_name: string | undefined,
+  record_id: string | undefined,
+  organisation_id: string | undefined,
+  category: FileCategory | undefined,
+  options: UseFileDisplayOptions
+): UseFileDisplayReturn {
+  const {
+    cacheTtl = 30 * 60 * 1000, // 30 minutes
+    enableCache = true,
+    supabase
+  } = options;
+
+  const [fileUrl, setFileUrl] = useState<string | null>(null);
+  const [fileReference, setFileReference] = useState<FileReference | null>(null);
+  const [fileReferences, setFileReferences] = useState<FileReference[]>([]);
+  const [fileUrls, setFileUrls] = useState<Map<string, string>>(new Map());
+  const [fileCount, setFileCount] = useState<number>(0);
+  const [isLoading, setIsLoading] = useState<boolean>(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const fetchFiles = useCallback(async (): Promise<void> => {
+    if (!table_name || !record_id || !organisation_id || !supabase) {
+      setFileUrl(null);
+      setFileReference(null);
+      setFileReferences([]);
+      setFileUrls(new Map());
+      setFileCount(0);
+      setIsLoading(false);
+      return;
+    }
+
+    // Validate UUID format for organisationId to prevent database errors
+    const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+    if (!uuidRegex.test(organisation_id)) {
+      console.warn('[useFileDisplay] Invalid organisationId format (not a valid UUID):', organisation_id);
+    }
+
+    // Check cache first
+    const cacheKey = `file_${table_name}_${record_id}_${organisation_id}_${category || 'all'}`;
+    if (enableCache) {
+      const cached = authenticatedFileCache.get(cacheKey);
+      if (cached && Date.now() - cached.timestamp < cached.ttl) {
+        const cachedData = cached.data;
+        setFileUrl(cachedData.fileUrl || null);
+        setFileReference(cachedData.fileReference || null);
+        setFileReferences(cachedData.fileReferences || []);
+        setFileUrls(cachedData.fileUrls || new Map());
+        setFileCount(cachedData.fileCount || 0);
+        setIsLoading(false);
+        setError(null);
+        return;
+      }
+    }
+
+    try {
+      setIsLoading(true);
+      setError(null);
+
+      const service = createFileReferenceService(supabase);
+      let files: FileReference[] = [];
+
+      if (category) {
+        // Single file mode - get files by category
+        files = await service.getFilesByCategory(
+          table_name,
+          record_id,
+          category,
+          organisation_id
+        );
+      } else {
+        // Multiple files mode - get all files
+        files = await service.listFileReferences(
+          table_name,
+          record_id,
+          organisation_id
+        );
+      }
+
+      if (files.length === 0) {
+        setFileUrl(null);
+        setFileReference(null);
+        setFileReferences([]);
+        setFileUrls(new Map());
+        setFileCount(0);
+        
+        // Cache empty result
+        if (enableCache) {
+          authenticatedFileCache.set(cacheKey, {
+            data: { fileUrl: null, fileReference: null, fileReferences: [], fileUrls: new Map(), fileCount: 0 },
+            timestamp: Date.now(),
+            ttl: cacheTtl
+          });
+          cleanupCache();
+        }
+        return;
+      }
+
+      setFileReferences(files);
+      setFileCount(files.length);
+
+      if (category && files.length > 0) {
+        // Single file mode - get first file
+        const firstFile = files[0];
+        setFileReference(firstFile);
+        
+        // Generate URL based on file visibility
+        let url: string | null = null;
+        if (firstFile.is_public) {
+          url = getPublicUrl(supabase, firstFile.file_path, true);
+        } else {
+          const signedUrlResult = await getSignedUrl(supabase, firstFile.file_path, {
+            appName: 'pace-core',
+            orgId: organisation_id,
+            expiresIn: 3600
+          });
+          url = signedUrlResult?.url || null;
+        }
+        setFileUrl(url);
+      } else {
+        // Multiple files mode - generate URLs for all files
+        const urlMap = new Map<string, string>();
+        for (const fileRef of files) {
+          let url: string | null = null;
+          if (fileRef.is_public) {
+            url = getPublicUrl(supabase, fileRef.file_path, true);
+          } else {
+            const signedUrlResult = await getSignedUrl(supabase, fileRef.file_path, {
+              appName: 'pace-core',
+              orgId: organisation_id,
+              expiresIn: 3600
+            });
+            url = signedUrlResult?.url || null;
+          }
+          if (url) {
+            urlMap.set(fileRef.id, url);
+          }
+        }
+        setFileUrls(urlMap);
+        setFileReference(null);
+        setFileUrl(null);
+      }
+
+      // Cache the result
+      if (enableCache) {
+        // Prepare cache data
+        let cacheData: any = {
+          fileReference: category && files.length > 0 ? files[0] : null,
+          fileReferences: files,
+          fileUrls: new Map(),
+          fileCount: files.length
+        };
+
+        if (category && files.length > 0) {
+          const firstFile = files[0];
+          let url: string | null = null;
+          if (firstFile.is_public) {
+            url = getPublicUrl(supabase, firstFile.file_path, true);
+          }
+          cacheData.fileUrl = url;
+        } else {
+          const urlMap = new Map<string, string>();
+          for (const fileRef of files) {
+            if (fileRef.is_public) {
+              const url = getPublicUrl(supabase, fileRef.file_path, true);
+              if (url) {
+                urlMap.set(fileRef.id, url);
+              }
+            }
+          }
+          cacheData.fileUrls = urlMap;
+        }
+
+        authenticatedFileCache.set(cacheKey, {
+          data: cacheData,
+          timestamp: Date.now(),
+          ttl: cacheTtl
+        });
+        cleanupCache();
+      }
+
+    } catch (err) {
+      console.error('[useFileDisplay] Error fetching files:', err);
+      const error = err instanceof Error ? err : new Error('Unknown error occurred');
+      setError(error);
+      setFileUrl(null);
+      setFileReference(null);
+      setFileReferences([]);
+      setFileUrls(new Map());
+      setFileCount(0);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [table_name, record_id, organisation_id, category, supabase, cacheTtl, enableCache]);
+
+  // Fetch files when parameters change
+  useEffect(() => {
+    if (table_name && record_id && organisation_id && supabase) {
+      fetchFiles();
+    } else {
+      setFileUrl(null);
+      setFileReference(null);
+      setFileReferences([]);
+      setFileUrls(new Map());
+      setFileCount(0);
+      setIsLoading(false);
+      setError(null);
+    }
+  }, [fetchFiles, table_name, record_id, organisation_id, supabase]);
+
+  const refetch = useCallback(async (): Promise<void> => {
+    if (!table_name || !record_id || !organisation_id || !supabase) return;
+    
+    // Clear cache for this file
+    if (enableCache) {
+      const cacheKey = `file_${table_name}_${record_id}_${organisation_id}_${category || 'all'}`;
+      authenticatedFileCache.delete(cacheKey);
+    }
+    await fetchFiles();
+  }, [fetchFiles, table_name, record_id, organisation_id, category, supabase, enableCache]);
+
+  return {
+    fileUrl,
+    fileReference,
+    fileReferences,
+    fileUrls,
+    fileCount,
+    isLoading,
+    error,
+    refetch
+  };
+}
+
+/**
+ * Clear all cached authenticated file data
+ * Useful for testing or when you need to force refresh all data
+ */
+export function clearFileDisplayCache(): void {
+  for (const [key] of authenticatedFileCache) {
+    if (key.startsWith('file_')) {
+      authenticatedFileCache.delete(key);
+    }
+  }
+}
+
+/**
+ * Get cache statistics for debugging
+ */
+export function getFileDisplayCacheStats(): { size: number; keys: string[] } {
+  const keys = Array.from(authenticatedFileCache.keys()).filter(key => key.startsWith('file_'));
+  return {
+    size: keys.length,
+    keys
+  };
+}
+

package/src/hooks/useFileUrl.ts

@@ -0,0 +1,130 @@
+/**
+ * @file Custom Hook for File URL Generation
+ * @package @jmruthers/pace-core
+ * @module Hooks/FileDisplay
+ * 
+ * Extracts URL generation logic to eliminate duplication across FileDisplay components.
+ * Handles both public and private file URL generation with proper error handling.
+ */
+
+import { useState, useEffect, useCallback, useRef } from 'react';
+import { SupabaseClient } from '@supabase/supabase-js';
+import { FileReference } from '../types/file-reference';
+import { getPublicUrl, getSignedUrl } from '../utils/storage/helpers';
+
+export interface UseFileUrlOptions {
+  /** Organisation ID for signed URL generation */
+  organisation_id: string;
+  /** Supabase client instance */
+  supabase: SupabaseClient;
+  /** Whether to auto-load URLs on mount */
+  autoLoad?: boolean;
+}
+
+export interface UseFileUrlReturn {
+  /** Generated URL for the file reference */
+  url: string | null;
+  /** Whether URL is currently being generated */
+  isLoading: boolean;
+  /** Error if URL generation failed */
+  error: Error | null;
+  /** Manually trigger URL generation */
+  loadUrl: () => Promise<void>;
+  /** Clear the current URL and error */
+  clear: () => void;
+}
+
+/**
+ * Custom hook for generating file URLs (public or signed) for a single file reference
+ * 
+ * @param fileReference - The file reference to generate URL for (null if no file)
+ * @param options - Configuration options
+ * @returns Hook return object with URL, loading state, and controls
+ */
+export function useFileUrl(
+  fileReference: FileReference | null,
+  options: UseFileUrlOptions
+): UseFileUrlReturn {
+  const { organisation_id, supabase, autoLoad = true } = options;
+  
+  const [url, setUrl] = useState<string | null>(null);
+  const [isLoading, setIsLoading] = useState<boolean>(false);
+  const [error, setError] = useState<Error | null>(null);
+  const fileReferenceIdRef = useRef<string | null>(null);
+
+  const loadUrl = useCallback(async () => {
+    if (!fileReference) {
+      setUrl(null);
+      setIsLoading(false);
+      setError(null);
+      return;
+    }
+
+    // Skip if already loading or URL already exists for this file
+    if (isLoading || (url && fileReferenceIdRef.current === fileReference.id)) {
+      return;
+    }
+
+    setIsLoading(true);
+    setError(null);
+    fileReferenceIdRef.current = fileReference.id;
+
+    try {
+      let generatedUrl: string | null = null;
+
+      if (fileReference.is_public) {
+        // Public files: generate public URL
+        generatedUrl = getPublicUrl(supabase, fileReference.file_path, true);
+      } else {
+        // Private files: generate signed URL
+        const signedUrlResult = await getSignedUrl(supabase, fileReference.file_path, {
+          appName: 'file-reference',
+          orgId: organisation_id,
+          expiresIn: 3600
+        });
+        generatedUrl = signedUrlResult?.url || null;
+      }
+
+      setUrl(generatedUrl);
+      setError(null);
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error('Failed to generate file URL');
+      setError(error);
+      setUrl(null);
+      console.error('[useFileUrl] Error generating URL:', error);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [fileReference, supabase, organisation_id, isLoading, url]);
+
+  const clear = useCallback(() => {
+    setUrl(null);
+    setError(null);
+    setIsLoading(false);
+    fileReferenceIdRef.current = null;
+  }, []);
+
+  // Auto-load URL when fileReference changes
+  useEffect(() => {
+    if (autoLoad) {
+      // Reset URL when file reference changes
+      if (fileReferenceIdRef.current !== fileReference?.id) {
+        setUrl(null);
+        setError(null);
+      }
+      
+      if (fileReference && !url && !isLoading) {
+        loadUrl();
+      }
+    }
+  }, [fileReference?.id, autoLoad, loadUrl, url, isLoading]);
+
+  return {
+    url,
+    isLoading,
+    error,
+    loadUrl,
+    clear
+  };
+}
+

package/src/services/AuthService.ts

@@ -435,16 +435,16 @@ export class AuthService extends BaseService implements IAuthService {
 
     try {
       console.debug('[AuthService] Fetching existing session from Supabase');
-      // Safely call getSession without destructuring to avoid runtime errors if undefined
       let currentSession: Session | null = null;
       let sessionError: AuthError | null = null;
-      const getSessionFn = (this.supabaseClient.auth as any)?.getSession as (() => Promise<{ data?: { session?: Session | null }, error?: AuthError | null }>) | undefined;
-      if (typeof getSessionFn === 'function') {
-        const sessionResult = await getSessionFn();
-        currentSession = sessionResult?.data?.session ?? null;
-        sessionError = sessionResult?.error ?? null;
-      } else {
-        // If getSession is unavailable in this environment/mocked client, treat as no active session
+
+      try {
+        const { data, error } = await this.supabaseClient.auth.getSession();
+        currentSession = data?.session ?? null;
+        sessionError = error ?? null;
+      } catch (error) {
+        // Handle cases where getSession might not exist (mocked/test clients)
+        console.debug('[AuthService] getSession unavailable, treating as no active session');
         currentSession = null;
         sessionError = null;
       }
@@ -456,20 +456,17 @@ export class AuthService extends BaseService implements IAuthService {
         
         // Attempt getUser as fallback when getSession fails
         try {
-          const getUserFn = (this.supabaseClient.auth as any)?.getUser as (() => Promise<{ data?: { user?: User | null }, error?: AuthError | null }>) | undefined;
-          if (typeof getUserFn === 'function') {
-            const userResult = await getUserFn();
-            const currentUser = userResult?.data?.user ?? null;
-            const userError = userResult?.error ?? null;
-            
-            if (currentUser) {
-              this.user = currentUser;
-              // If we got a user but no session, we still don't have a valid session
-              this.session = null;
-            }
-            if (userError && !this.authError) {
-              this.authError = userError;
-            }
+          const { data, error } = await this.supabaseClient.auth.getUser();
+          const currentUser = data?.user ?? null;
+          const userError = error ?? null;
+          
+          if (currentUser) {
+            this.user = currentUser;
+            // If we got a user but no session, we still don't have a valid session
+            this.session = null;
+          }
+          if (userError && !this.authError) {
+            this.authError = userError;
           }
         } catch (getUserError) {
           // If getUser also fails, we've already recorded the sessionError