@jmruthers/pace-core 0.5.93 → 0.5.94

package/src/hooks/public/usePublicFileDisplay.ts

@@ -0,0 +1,355 @@
+/**
+ * @file Public File Display Hook
+ * @package @jmruthers/pace-core
+ * @module Hooks/Public
+ * @since 1.0.0
+ *
+ * A React hook for accessing file references in public contexts without authentication.
+ * Provides file URLs and metadata for public pages.
+ *
+ * Features:
+ * - No authentication required
+ * - Only returns public files (is_public = true)
+ * - Caching for performance
+ * - Error handling and loading states
+ * - TypeScript support
+ * - Supports both single file (category) and multiple files
+ *
+ * @example
+ * ```tsx
+ * import { usePublicFileDisplay } from '@jmruthers/pace-core';
+ *
+ * function PublicFileView() {
+ *   const { fileUrl, fileReference, isLoading, error } = usePublicFileDisplay(
+ *     'event',
+ *     eventId,
+ *     organisationId,
+ *     FileCategory.EVENT_LOGOS,
+ *     { supabase }
+ *   );
+ *
+ *   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, useMemo } from 'react';
+import type { SupabaseClient } from '@supabase/supabase-js';
+import type { Database } from '../../types/database';
+import { FileReference, FileCategory } from '../../types/file-reference';
+import { getPublicUrl } from '../../utils/storage/helpers';
+
+// Simple in-memory cache for public file data
+const publicFileCache = new Map<string, { data: any; timestamp: number; ttl: number }>();
+
+export interface UsePublicFileDisplayReturn {
+  /** 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 UsePublicFileDisplayOptions {
+  /** Cache TTL in milliseconds (default: 30 minutes) */
+  cacheTtl?: number;
+  /** Whether to enable caching (default: true) */
+  enableCache?: boolean;
+  /** Supabase client instance (required) */
+  supabase: SupabaseClient<Database>;
+}
+
+/**
+ * Hook for accessing public file references
+ * 
+ * This hook provides access to file references without requiring
+ * authentication. It only returns public files and generates public URLs.
+ * 
+ * @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 usePublicFileDisplay(
+  table_name: string | undefined,
+  record_id: string | undefined,
+  organisation_id: string | undefined,
+  category: FileCategory | undefined,
+  options: UsePublicFileDisplayOptions
+): UsePublicFileDisplayReturn {
+  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('[usePublicFileDisplay] Invalid organisationId format (not a valid UUID):', organisation_id);
+    }
+
+    // Check cache first
+    const cacheKey = `public_file_${table_name}_${record_id}_${organisation_id}_${category || 'all'}`;
+    if (enableCache) {
+      const cached = publicFileCache.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);
+
+      let files: any[] = [];
+
+      if (category) {
+        // Single file mode - use RPC to get files by category
+        const { data, error: rpcError } = await (supabase as any)
+          .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 (rpcError) {
+          throw new Error(rpcError.message || 'Failed to fetch file reference');
+        }
+
+        files = data || [];
+      } else {
+        // Multiple files mode - use RPC to get all files
+        const { data: fileIds, error: rpcError } = await (supabase as any)
+          .rpc('data_file_reference_list', {
+            p_table_name: table_name,
+            p_record_id: record_id,
+            p_organisation_id: organisation_id
+          });
+
+        if (rpcError) {
+          throw new Error(rpcError.message || 'Failed to fetch file references');
+        }
+
+        if (!fileIds || fileIds.length === 0) {
+          files = [];
+        } else {
+          // Fetch full file reference data for each ID, but only public files
+          const ids = fileIds.map((item: any) => item.id);
+          const { data: fullData, error: fetchError } = await supabase
+            .from('file_references')
+            .select('*')
+            .in('id', ids)
+            .eq('is_public', true); // Only public files in public context
+
+          if (fetchError) {
+            throw new Error(fetchError.message || 'Failed to fetch file references');
+          }
+
+          files = fullData || [];
+        }
+      }
+
+      // Ensure all files are public (category RPC might return both)
+      const publicFiles = files.filter((f: any) => f.is_public === true);
+
+      if (publicFiles.length === 0) {
+        setFileUrl(null);
+        setFileReference(null);
+        setFileReferences([]);
+        setFileUrls(new Map());
+        setFileCount(0);
+        
+        // Cache empty result
+        if (enableCache) {
+          publicFileCache.set(cacheKey, {
+            data: { fileUrl: null, fileReference: null, fileReferences: [], fileUrls: new Map(), fileCount: 0 },
+            timestamp: Date.now(),
+            ttl: cacheTtl
+          });
+        }
+        return;
+      }
+
+      // Convert to FileReference format
+      const fileRefs: FileReference[] = publicFiles.map((f: any) => ({
+        id: f.id,
+        table_name: f.table_name,
+        record_id: f.record_id,
+        file_path: f.file_path,
+        file_metadata: f.file_metadata || {},
+        organisation_id: f.organisation_id,
+        app_id: f.app_id,
+        is_public: f.is_public ?? true,
+        created_at: f.created_at,
+        updated_at: f.updated_at
+      }));
+
+      setFileReferences(fileRefs);
+      setFileCount(fileRefs.length);
+
+      if (category && fileRefs.length > 0) {
+        // Single file mode - get first file
+        const firstFile = fileRefs[0];
+        setFileReference(firstFile);
+        
+        // Generate public URL
+        const url = getPublicUrl(supabase, firstFile.file_path, true);
+        setFileUrl(url);
+      } else {
+        // Multiple files mode - generate URLs for all files
+        const urlMap = new Map<string, string>();
+        for (const fileRef of fileRefs) {
+          const url = getPublicUrl(supabase, fileRef.file_path, true);
+          if (url) {
+            urlMap.set(fileRef.id, url);
+          }
+        }
+        setFileUrls(urlMap);
+        setFileReference(null);
+        setFileUrl(null);
+      }
+
+      // Cache the result
+      if (enableCache) {
+        publicFileCache.set(cacheKey, {
+          data: {
+            fileUrl: category ? (fileRefs.length > 0 ? getPublicUrl(supabase, fileRefs[0].file_path, true) : null) : null,
+            fileReference: category && fileRefs.length > 0 ? fileRefs[0] : null,
+            fileReferences: fileRefs,
+            fileUrls: category ? new Map() : (() => {
+              const urlMap = new Map<string, string>();
+              for (const fileRef of fileRefs) {
+                const url = getPublicUrl(supabase, fileRef.file_path, true);
+                if (url) {
+                  urlMap.set(fileRef.id, url);
+                }
+              }
+              return urlMap;
+            })(),
+            fileCount: fileRefs.length
+          },
+          timestamp: Date.now(),
+          ttl: cacheTtl
+        });
+      }
+
+    } catch (err) {
+      console.error('[usePublicFileDisplay] 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) {
+      fetchFiles();
+    } else {
+      setFileUrl(null);
+      setFileReference(null);
+      setFileReferences([]);
+      setFileUrls(new Map());
+      setFileCount(0);
+      setIsLoading(false);
+      setError(null);
+    }
+  }, [fetchFiles, table_name, record_id, organisation_id]);
+
+  const refetch = useCallback(async (): Promise<void> => {
+    if (!table_name || !record_id || !organisation_id) return;
+    
+    // Clear cache for this file
+    if (enableCache) {
+      const cacheKey = `public_file_${table_name}_${record_id}_${organisation_id}_${category || 'all'}`;
+      publicFileCache.delete(cacheKey);
+    }
+    await fetchFiles();
+  }, [fetchFiles, table_name, record_id, organisation_id, category, enableCache]);
+
+  return {
+    fileUrl,
+    fileReference,
+    fileReferences,
+    fileUrls,
+    fileCount,
+    isLoading,
+    error,
+    refetch
+  };
+}
+
+/**
+ * Clear all cached public file data
+ * Useful for testing or when you need to force refresh all data
+ */
+export function clearPublicFileDisplayCache(): void {
+  for (const [key] of publicFileCache) {
+    if (key.startsWith('public_file_')) {
+      publicFileCache.delete(key);
+    }
+  }
+}
+
+/**
+ * Get cache statistics for debugging
+ */
+export function getPublicFileDisplayCacheStats(): { size: number; keys: string[] } {
+  const keys = Array.from(publicFileCache.keys()).filter(key => key.startsWith('public_file_'));
+  return {
+    size: keys.length,
+    keys
+  };
+}
+