@jmruthers/pace-core 0.6.10 → 0.6.12

package/src/components/FileDisplay/usePublicFileDisplay.ts

@@ -0,0 +1,579 @@
+/**
+ * @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 <p>Loading...</p>;
+ *   if (error) return <p>Error: {error.message}</p>;
+ *
+ *   return fileUrl ? <img src={fileUrl} alt="File" /> : null;
+ * }
+ * ```
+ */
+
+import { useState, useEffect, useCallback } from 'react';
+import type { SupabaseClient } from '@supabase/supabase-js';
+import type { Database } from '../../types/database';
+import { FileReference, FileCategory } from '../../types/file-reference';
+import { getPublicUrl, generateFileUrlsBatch } from '../../utils/storage/helpers';
+import { logger } from '../../utils/core/logger';
+import type { RpcFileItem } from '../../types/rpc-responses';
+
+// Cache data structure
+interface CacheData {
+  fileUrl: string | null;
+  fileReference: FileReference | null;
+  fileReferences: FileReference[];
+  fileUrls: Map<string, string>;
+  fileCount: number;
+}
+
+// Simple in-memory cache for public file data
+const publicFileCache = new Map<string, { data: CacheData; timestamp: number; ttl: number }>();
+
+/**
+ * Return value of the usePublicFileDisplay hook.
+ * Provides file URLs, references, loading state, error, and refetch function.
+ */
+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> => {
+    const emptySetters = (): void => {
+      applyEmptyPublicFileState(
+        setFileUrl,
+        setFileReference,
+        setFileReferences,
+        setFileUrls,
+        setFileCount,
+        setIsLoading,
+        setError
+      );
+    };
+
+    if (!table_name || !record_id || !supabase) {
+      emptySetters();
+      return;
+    }
+
+    warnInvalidOrganisationIdUuid(organisation_id ?? undefined);
+
+    const cacheKey = buildPublicFileCacheKey(table_name, record_id, organisation_id, category);
+    const cached = getCachedPublicFileData(cacheKey, enableCache);
+    if (cached) {
+      applyCachedPublicFileState(
+        cached,
+        setFileUrl,
+        setFileReference,
+        setFileReferences,
+        setFileUrls,
+        setFileCount,
+        setIsLoading,
+        setError
+      );
+      return;
+    }
+
+    try {
+      setIsLoading(true);
+      setError(null);
+
+      const rows = await fetchPublicFileRows(supabase, table_name, record_id, organisation_id, category);
+      const publicRows = rows.filter((f) => f.is_public === true);
+
+      if (publicRows.length === 0) {
+        emptySetters();
+        setCachedPublicFileData(cacheKey, emptyCacheData, enableCache, cacheTtl);
+        return;
+      }
+
+      const fileRefs = mapDbRowsToFileReferences(publicRows);
+      setFileReferences(fileRefs);
+      setFileCount(fileRefs.length);
+
+      if (category && fileRefs.length > 0) {
+        const firstFile = fileRefs[0];
+        setFileReference(firstFile);
+        setFileUrl(getPublicUrl(supabase, firstFile.file_path, true));
+      } else {
+        const urlResult = await generateFileUrlsBatch(supabase, fileRefs, {
+          appName: 'pace-core',
+          orgId: organisation_id,
+          expiresIn: 3600
+        });
+        setFileUrls(urlResult.ok ? urlResult.data : new Map());
+        setFileReference(null);
+        setFileUrl(null);
+      }
+
+      setCachedPublicFileData(
+        cacheKey,
+        buildCacheDataFromRefs(fileRefs, category, supabase),
+        enableCache,
+        cacheTtl
+      );
+    } catch (err) {
+      logger.error('usePublicFileDisplay', 'Error fetching files', {
+        table_name,
+        record_id,
+        organisation_id,
+        category,
+        error: err instanceof Error ? err.message : 'Unknown error',
+        errorDetails: err instanceof Error ? err.stack : String(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) {
+      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) return;
+    if (enableCache) {
+      const cacheKey = buildPublicFileCacheKey(table_name, record_id, organisation_id, category);
+      publicFileCache.delete(cacheKey);
+    }
+    await fetchFiles();
+  }, [fetchFiles, table_name, record_id, organisation_id, category, enableCache]);
+
+  return {
+    fileUrl,
+    fileReference,
+    fileReferences,
+    fileUrls,
+    fileCount,
+    isLoading,
+    error,
+    refetch
+  };
+}
+
+// --- Helpers (same file, non-exported) ---
+
+type FileReferenceRow = Database['public']['Tables']['core_file_references']['Row'];
+
+function buildPublicFileCacheKey(
+  table_name: string,
+  record_id: string,
+  organisation_id: string | undefined | null,
+  category: FileCategory | undefined
+): string {
+  return `public_file_${table_name}_${record_id}_${organisation_id === undefined ? 'undefined' : (organisation_id ?? 'null')}_${category || 'all'}`;
+}
+
+function getCachedPublicFileData(
+  cacheKey: string,
+  enableCache: boolean
+): CacheData | null {
+  if (!enableCache) return null;
+  const cached = publicFileCache.get(cacheKey);
+  if (!cached || Date.now() - cached.timestamp >= cached.ttl) return null;
+  return cached.data;
+}
+
+function setCachedPublicFileData(
+  cacheKey: string,
+  data: CacheData,
+  enableCache: boolean,
+  cacheTtl: number
+): void {
+  if (!enableCache) return;
+  publicFileCache.set(cacheKey, {
+    data,
+    timestamp: Date.now(),
+    ttl: cacheTtl
+  });
+}
+
+function mapRpcItemToRow(
+  item: RpcFileItem,
+  table_name: string,
+  record_id: string,
+  organisation_id: string | null
+): FileReferenceRow {
+  const metadata = item.file_metadata as { app_id?: string; [key: string]: unknown } | null;
+  return {
+    id: item.id,
+    table_name,
+    record_id,
+    file_path: item.file_path,
+    file_metadata: item.file_metadata || null,
+    organisation_id,
+    app_id: metadata?.app_id || '',
+    is_public: true,
+    created_at: item.created_at || new Date().toISOString(),
+    updated_at: item.created_at || new Date().toISOString(),
+    created_by: null
+  };
+}
+
+async function fetchPublicFileRowsWhenOrgUndefined(
+  supabase: SupabaseClient<Database>,
+  table_name: string,
+  record_id: string,
+  category: FileCategory | undefined
+): Promise<FileReferenceRow[]> {
+  let userScopedFiles: FileReferenceRow[] = [];
+  const orgScopedFiles: FileReferenceRow[] = [];
+
+  logger.debug('usePublicFileDisplay', 'organisation_id is undefined, searching both user-scoped and organisation-scoped files:', {
+    table_name,
+    record_id,
+    category
+  });
+
+  if (category) {
+    const { data: userData, error: userRpcError } = await supabase.rpc('data_file_reference_by_category_list', {
+      p_table_name: table_name,
+      p_record_id: record_id,
+      p_category: category,
+      p_organisation_id: undefined
+    });
+    if (!userRpcError && userData) {
+      userScopedFiles = userData
+        .filter((item: RpcFileItem) => item.is_public === true && item.id && item.file_path && item.file_metadata)
+        .map((item: RpcFileItem) => mapRpcItemToRow(item, table_name, record_id, null));
+    }
+  } else {
+    const { data: userData, error: userRpcError } = await supabase.rpc('data_file_reference_list', {
+      p_table_name: table_name,
+      p_record_id: record_id,
+      p_organisation_id: undefined
+    });
+    if (!userRpcError && userData) {
+      const ids = userData.map((item: RpcFileItem) => item.id);
+      if (ids.length > 0) {
+        const { data: fullData } = await supabase
+          .from('core_file_references')
+          .select('id, table_name, record_id, file_path, file_metadata, organisation_id, app_id, is_public, created_at, updated_at, created_by')
+          .in('id', ids)
+          .eq('is_public', true);
+        userScopedFiles = (fullData || []) as FileReferenceRow[];
+      }
+    }
+  }
+
+  const allFiles = [...userScopedFiles, ...orgScopedFiles];
+  allFiles.sort((a, b) => {
+    const aTime = new Date(a.created_at || 0).getTime();
+    const bTime = new Date(b.created_at || 0).getTime();
+    return bTime - aTime;
+  });
+
+  logger.debug('usePublicFileDisplay', 'Found files with undefined organisation_id:', {
+    userScopedCount: userScopedFiles.length,
+    orgScopedCount: orgScopedFiles.length,
+    totalCount: allFiles.length
+  });
+
+  return allFiles;
+}
+
+async function fetchPublicFileRowsWhenOrgDefined(
+  supabase: SupabaseClient<Database>,
+  table_name: string,
+  record_id: string,
+  organisation_id: string | undefined | null,
+  category: FileCategory | undefined
+): Promise<FileReferenceRow[]> {
+  if (category) {
+    const rpcParams = {
+      p_table_name: table_name,
+      p_record_id: record_id,
+      p_category: category,
+      p_organisation_id: organisation_id ?? undefined
+    };
+    const { data, error: rpcError } = await supabase.rpc('data_file_reference_by_category_list', rpcParams);
+    if (rpcError) {
+      logger.error('usePublicFileDisplay', 'RPC function error', {
+        function: 'data_file_reference_by_category_list',
+        table_name,
+        record_id,
+        category,
+        organisation_id,
+        error: rpcError.message,
+        errorCode: rpcError.code,
+        errorDetails: rpcError.details,
+        errorHint: rpcError.hint
+      });
+      throw new Error(rpcError.message || 'Failed to fetch file reference');
+    }
+    if (!data || data.length === 0) return [];
+    return data
+      .filter((item: RpcFileItem) => item.is_public === true && item.id && item.file_path && item.file_metadata)
+      .map((item: RpcFileItem) => mapRpcItemToRow(item, table_name, record_id, organisation_id ?? null));
+  }
+
+  const { data: fileIds, error: rpcError } = await supabase.rpc('data_file_reference_list', {
+    p_table_name: table_name,
+    p_record_id: record_id,
+    p_organisation_id: organisation_id ?? undefined
+  });
+  if (rpcError) {
+    logger.error('usePublicFileDisplay', 'RPC function error', {
+      function: 'data_file_reference_list',
+      table_name,
+      record_id,
+      organisation_id,
+      error: rpcError.message,
+      errorCode: rpcError.code,
+      errorDetails: rpcError.details,
+      errorHint: rpcError.hint
+    });
+    throw new Error(rpcError.message || 'Failed to fetch file references');
+  }
+  if (!fileIds || fileIds.length === 0) return [];
+  const ids = fileIds.map((item: RpcFileItem) => item.id);
+  const { data: fullData, error: fetchError } = await supabase
+    .from('core_file_references')
+    .select('id, table_name, record_id, file_path, file_metadata, organisation_id, app_id, is_public, created_at, updated_at, created_by')
+    .in('id', ids)
+    .eq('is_public', true);
+  if (fetchError) throw new Error(fetchError.message || 'Failed to fetch file references');
+  return (fullData || []) as FileReferenceRow[];
+}
+
+async function fetchPublicFileRows(
+  supabase: SupabaseClient<Database>,
+  table_name: string,
+  record_id: string,
+  organisation_id: string | undefined | null,
+  category: FileCategory | undefined
+): Promise<FileReferenceRow[]> {
+  if (organisation_id === undefined) {
+    return fetchPublicFileRowsWhenOrgUndefined(supabase, table_name, record_id, category);
+  }
+  return fetchPublicFileRowsWhenOrgDefined(supabase, table_name, record_id, organisation_id, category);
+}
+
+function mapDbRowsToFileReferences(rows: FileReferenceRow[]): FileReference[] {
+  return rows.map((f) => {
+    const fileName = f.file_path.split('/').pop() || 'unknown';
+    const fileType = fileName.split('.').pop() || 'unknown';
+    const metadata = f.file_metadata as { fileName?: string; fileType?: string; category?: FileCategory; [key: string]: unknown } | null;
+    return {
+      id: f.id,
+      table_name: f.table_name,
+      record_id: f.record_id,
+      file_path: f.file_path,
+      file_metadata: {
+        fileName: metadata?.fileName || fileName,
+        fileType: metadata?.fileType || fileType,
+        category: metadata?.category || FileCategory.GENERAL_DOCUMENTS,
+        ...(metadata || {})
+      } as FileReference['file_metadata'],
+      organisation_id: f.organisation_id,
+      app_id: f.app_id as FileReference['app_id'],
+      is_public: f.is_public ?? true,
+      created_at: f.created_at || new Date().toISOString(),
+      updated_at: f.updated_at || new Date().toISOString()
+    };
+  });
+}
+
+function buildCacheDataFromRefs(
+  fileRefs: FileReference[],
+  category: FileCategory | undefined,
+  supabase: SupabaseClient<Database>
+): CacheData {
+  const fileUrl = category && fileRefs.length > 0 ? getPublicUrl(supabase, fileRefs[0].file_path, true) : null;
+  const fileReference = category && fileRefs.length > 0 ? fileRefs[0] : null;
+  let fileUrls: Map<string, string>;
+  if (category) {
+    fileUrls = new Map();
+  } else {
+    fileUrls = new Map<string, string>();
+    for (const fileRef of fileRefs) {
+      const url = getPublicUrl(supabase, fileRef.file_path, true);
+      if (url) fileUrls.set(fileRef.id, url);
+    }
+  }
+  return {
+    fileUrl,
+    fileReference,
+    fileReferences: fileRefs,
+    fileUrls,
+    fileCount: fileRefs.length
+  };
+}
+
+const emptyCacheData: CacheData = {
+  fileUrl: null,
+  fileReference: null,
+  fileReferences: [],
+  fileUrls: new Map(),
+  fileCount: 0
+};
+
+function applyEmptyPublicFileState(
+  setFileUrl: (v: string | null) => void,
+  setFileReference: (v: FileReference | null) => void,
+  setFileReferences: (v: FileReference[]) => void,
+  setFileUrls: (v: Map<string, string>) => void,
+  setFileCount: (v: number) => void,
+  setIsLoading: (v: boolean) => void,
+  setError: (v: Error | null) => void
+): void {
+  setFileUrl(null);
+  setFileReference(null);
+  setFileReferences([]);
+  setFileUrls(new Map());
+  setFileCount(0);
+  setIsLoading(false);
+  setError(null);
+}
+
+function applyCachedPublicFileState(
+  cachedData: CacheData,
+  setFileUrl: (v: string | null) => void,
+  setFileReference: (v: FileReference | null) => void,
+  setFileReferences: (v: FileReference[]) => void,
+  setFileUrls: (v: Map<string, string>) => void,
+  setFileCount: (v: number) => void,
+  setIsLoading: (v: boolean) => void,
+  setError: (v: Error | null) => void
+): void {
+  setFileUrl(cachedData.fileUrl || null);
+  setFileReference(cachedData.fileReference || null);
+  setFileReferences(cachedData.fileReferences || []);
+  setFileUrls(cachedData.fileUrls || new Map());
+  setFileCount(cachedData.fileCount || 0);
+  setIsLoading(false);
+  setError(null);
+}
+
+function warnInvalidOrganisationIdUuid(organisation_id: string | undefined): void {
+  if (!organisation_id) return;
+  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)) {
+    logger.warn('usePublicFileDisplay', 'Invalid organisationId format (not a valid UUID)', { organisation_id });
+  }
+}
+
+/**
+ * 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
+  };
+}

package/src/components/FileUpload/FileUpload.test.tsx

@@ -1,7 +1,7 @@
 /**
  * @file FileUpload Component Tests
  * @package @jmruthers/pace-core
- * @module Components/FileUpload/__tests__
+ * @module Components/FileUpload
  * 
  * Comprehensive test suite for FileUpload component following testing standards.
  * Tests cover file selection, validation, upload workflows, error handling, and accessibility.
@@ -52,7 +52,7 @@ beforeEach(() => {
   });
 
   mockGetCurrentAppName.mockReturnValue('test-app');
-  mockGetAppId.mockResolvedValue('test-app-id');
+  mockGetAppId.mockResolvedValue({ ok: true, data: 'test-app-id' });
 
   vi.spyOn(useFileReferenceModule, 'useFileReference').mockImplementation(mockUseFileReference);
   vi.spyOn(appNameResolver, 'getCurrentAppName').mockImplementation(mockGetCurrentAppName);
@@ -183,7 +183,7 @@ describe('[component] FileUpload', () => {
 
     it('does not handle drop when disabled', () => {
       renderWithProviders(<FileUpload {...baseProps} disabled />);
-      const dropArea = screen.getByText(/Click to upload/i).closest('div') as HTMLElement;
+      const dropArea = screen.getByRole('button', { name: /File upload area/i });
 
       fireEvent.dragOver(dropArea);
       expect(screen.queryByText(/Drop files here/i)).not.toBeInTheDocument();
@@ -511,33 +511,39 @@ describe('[component] FileUpload', () => {
   });
 
   describe('Keyboard Navigation', () => {
-    it('triggers file input click on Enter key', () => {
+    it('triggers file input click on Enter key', async () => {
+      const user = userEvent.setup();
       renderWithProviders(<FileUpload {...baseProps} />);
       const dropArea = screen.getByRole('button', { name: 'File upload area' });
       const input = screen.getByTestId('file-input') as HTMLInputElement;
       const clickSpy = vi.spyOn(input, 'click');
 
-      fireEvent.keyDown(dropArea, { key: 'Enter' });
+      dropArea.focus();
+      await user.keyboard('{Enter}');
       expect(clickSpy).toHaveBeenCalled();
     });
 
-    it('triggers file input click on Space key', () => {
+    it('triggers file input click on Space key', async () => {
+      const user = userEvent.setup();
       renderWithProviders(<FileUpload {...baseProps} />);
       const dropArea = screen.getByRole('button', { name: 'File upload area' });
       const input = screen.getByTestId('file-input') as HTMLInputElement;
       const clickSpy = vi.spyOn(input, 'click');
 
-      fireEvent.keyDown(dropArea, { key: ' ' });
+      dropArea.focus();
+      await user.keyboard(' ');
       expect(clickSpy).toHaveBeenCalled();
     });
 
-    it('does not trigger click when disabled', () => {
+    it('does not trigger click when disabled', async () => {
+      const user = userEvent.setup();
       renderWithProviders(<FileUpload {...baseProps} disabled />);
       const dropArea = screen.getByRole('button', { name: 'File upload area' });
       const input = screen.getByTestId('file-input') as HTMLInputElement;
       const clickSpy = vi.spyOn(input, 'click');
 
-      fireEvent.keyDown(dropArea, { key: 'Enter' });
+      dropArea.focus();
+      await user.keyboard('{Enter}');
       expect(clickSpy).not.toHaveBeenCalled();
     });
   });
@@ -616,7 +622,7 @@ describe('[component] FileUpload', () => {
         renderWithProviders(
           <FileUpload
             {...baseProps}
-            pageContext={'' as any}
+            pageContext={''}
           />
         );
       }).toThrow('pageContext is required');